[charts] Introduce keyboard navigation

docs/data/charts/accessibility/accessibility.md

@@ -0,0 +1,73 @@
+---
+productId: x-charts
+title: Charts - Accessibility
+packageName: '@mui/x-charts'
+---
+
+# Accessibility
+
+<p class="description">Learn how the Charts implement accessibility features and guidelines, including keyboard navigation that follows international standards.</p>
+
+:::info
+A common misconception about accessibility is to only consider blind people and the screen reader.
+But there are other disability to consider, like:
+
+- **Color blindness**, making it hard to distinguish different series, or low contrast elements.
+- **Motion disability**, making it hard to open the tooltip on a given item.
+- **Cognitive disability**, making it hard to focus your attention on some details.
+- **Vestibular dysfunction**, making you unconformable with animations.
+
+:::
+
+## Guidelines
+
+Common conformance guidelines for accessibility include:
+
+- Globally accepted standard: [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/)
+- US:
+  - [ADA](https://www.ada.gov/) - US Department of Justice
+  - [Section 508](https://www.section508.gov/) - US federal agencies
+- Europe: [EAA](https://employment-social-affairs.ec.europa.eu/policies-and-activities/social-protection-social-inclusion/persons-disabilities/union-equality-strategy-rights-persons-disabilities-2021-2030/european-accessibility-act_en) (European Accessibility Act)
+
+WCAG 2.1 has three levels of conformance: A, AA, and AAA.
+Level AA exceeds the basic criteria for accessibility and is a common target for most organizations, so this is what we aim to support.
+
+The WAI-ARIA Authoring Practices includes examples on [Tooltip](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/).
+
+<!-- ### Dialog considerations
+
+Both `Desktop` and `Mobile` Date and Time Pickers are using `role="dialog"` to display their interactive view parts and thus they should follow [Modal accessibility guidelines](/material-ui/react-modal/#accessibility).
+This behavior is automated as much as possible, ensuring that the Date and Time Pickers are accessible in most cases.
+A correct `aria-labelledby` value is assigned to the dialog component based on the following rules:
+
+- Use `toolbar` id if the toolbar is visible;
+- Use the id of the input label if the toolbar is hidden;
+
+:::info
+Make sure to provide an `aria-labelledby` prop to `popper` and/or `mobilePaper` slots in case you are using Date and Time Pickers component with **hidden toolbar** and **without a label**.
+::: -->
+
+## Animation
+
+Most of the charts have an animation when rendering or when data update.
+For users with vestibular motion disorders those animations can be problematic.
+By default we skip animation based on the [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media feature.
+
+<!--
+## Screen reader compatibility
+
+Date and Time Pickers use ARIA roles and robust focus management across the interactive elements to convey the necessary information to users, being optimized for use with assistive technologies.
+-->
+
+## Keyboard support
+
+Set `enableKeyboardNavigation` to `true` to enable the keyboard navigation on your charts.
+This feature is currently supported by line, bar, pie, and scatter charts.
+
+This makes the SVG component focusable thanks to [`tabIndex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/tabindex).
+When focused, the charts highlight a value item that can be modified with arrow navigation.
+
+|                                                                  Keys | Description                   |
+| --------------------------------------------------------------------: | :---------------------------- |
+| <kbd class="key">Arrow Left</kbd>, <kbd class="key">Arrow Right</kbd> | Moves focus inside the series |
+|    <kbd class="key">Arrow Up</kbd>, <kbd class="key">Arrow Down</kbd> | Move focus between series     |

docs/data/charts/lines/lines.md

@@ -1,7 +1,7 @@
 ---
 title: React Line chart
 productId: x-charts
-components: LineChart, LineChartPro, LineElement, LineHighlightElement, LineHighlightPlot, LinePlot, MarkElement, MarkPlot, AreaElement, AreaPlot, AnimatedLine, AnimatedArea, ChartsGrid
+components: LineChart, LineChartPro, LineElement, LineHighlightElement, LineHighlightPlot, LinePlot, MarkElement, MarkPlot, AreaElement, AreaPlot, AnimatedLine, AnimatedArea, ChartsGrid, FocusedMark
 ---
 
 # Charts - Lines

docs/pages/x/react-charts/accessibility.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docsx/data/charts/accessibility/accessibility.md?muiMarkdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}

packages/x-charts-pro/src/BarChartPro/BarChartPro.plugins.ts

@@ -7,6 +7,8 @@ import {
   UseChartInteractionSignature,
   useChartHighlight,
   UseChartHighlightSignature,
+  useChartKeyboardNavigation,
+  UseChartKeyboardNavigationSignature,
   ConvertSignaturesIntoPlugins,
 } from '@mui/x-charts/internals';
 import {
@@ -20,6 +22,7 @@ export type BarChartProPluginsSignatures = [
   UseChartCartesianAxisSignature<'bar'>,
   UseChartInteractionSignature,
   UseChartHighlightSignature,
+  UseChartKeyboardNavigationSignature,
   UseChartProZoomSignature,
   UseChartProExportSignature,
 ];
@@ -29,6 +32,7 @@ export const BAR_CHART_PRO_PLUGINS: ConvertSignaturesIntoPlugins<BarChartProPlug
   useChartCartesianAxis,
   useChartInteraction,
   useChartHighlight,
+  useChartKeyboardNavigation,
   useChartProZoom,
   useChartProExport,
 ];

packages/x-charts-pro/src/BarChartPro/BarChartPro.tsx

@@ -177,6 +177,7 @@ BarChartPro.propTypes = {
    * @default false
    */
   disableAxisListener: PropTypes.bool,
+  enableKeyboardNavigation: PropTypes.bool,
   /**
    * Option to display a cartesian grid in the background.
    */

packages/x-charts-pro/src/LineChartPro/LineChartPro.plugins.ts

@@ -7,6 +7,8 @@ import {
   UseChartInteractionSignature,
   useChartHighlight,
   UseChartHighlightSignature,
+  useChartKeyboardNavigation,
+  UseChartKeyboardNavigationSignature,
   ConvertSignaturesIntoPlugins,
 } from '@mui/x-charts/internals';
 import {
@@ -20,6 +22,7 @@ export type LineChartProPluginsSignatures = [
   UseChartCartesianAxisSignature<'line'>,
   UseChartInteractionSignature,
   UseChartHighlightSignature,
+  UseChartKeyboardNavigationSignature,
   UseChartProZoomSignature,
   UseChartProExportSignature,
 ];
@@ -29,6 +32,7 @@ export const LINE_CHART_PRO_PLUGINS: ConvertSignaturesIntoPlugins<LineChartProPl
   useChartCartesianAxis,
   useChartInteraction,
   useChartHighlight,
+  useChartKeyboardNavigation,
   useChartProZoom,
   useChartProExport,
 ];

packages/x-charts-pro/src/LineChartPro/LineChartPro.tsx

@@ -183,6 +183,7 @@ LineChartPro.propTypes = {
    * If `true`, render the line highlight item.
    */
   disableLineItemHighlight: PropTypes.bool,
+  enableKeyboardNavigation: PropTypes.bool,
   /**
    * Options to enable features planned for the next major.
    */

packages/x-charts-pro/src/PieChartPro/PieChartPro.plugins.ts

@@ -3,6 +3,7 @@ import {
   UseChartHighlightSignature,
   UseChartInteractionSignature,
   PIE_CHART_PLUGINS,
+  UseChartKeyboardNavigationSignature,
 } from '@mui/x-charts/internals';
 import {
   useChartProExport,
@@ -12,6 +13,7 @@ import {
 export type PieChartProPluginSignatures = [
   UseChartInteractionSignature,
   UseChartHighlightSignature,
+  UseChartKeyboardNavigationSignature,
   UseChartProExportSignature,
 ];
 

packages/x-charts-pro/src/PieChartPro/PieChartPro.tsx

@@ -144,6 +144,7 @@ PieChartPro.propTypes = {
    */
   dataset: PropTypes.arrayOf(PropTypes.object),
   desc: PropTypes.string,
+  enableKeyboardNavigation: PropTypes.bool,
   /**
    * The height of the chart in px. If not defined, it takes the height of the parent element.
    */

packages/x-charts-pro/src/ScatterChartPro/ScatterChartPro.plugins.ts

@@ -9,6 +9,8 @@ import {
   UseChartHighlightSignature,
   useChartVoronoi,
   UseChartVoronoiSignature,
+  useChartKeyboardNavigation,
+  UseChartKeyboardNavigationSignature,
   ConvertSignaturesIntoPlugins,
 } from '@mui/x-charts/internals';
 import {
@@ -23,6 +25,7 @@ export type ScatterChartProPluginsSignatures = [
   UseChartInteractionSignature,
   UseChartHighlightSignature,
   UseChartVoronoiSignature,
+  UseChartKeyboardNavigationSignature,
   UseChartProZoomSignature,
   UseChartProExportSignature,
 ];
@@ -34,6 +37,7 @@ export const SCATTER_CHART_PRO_PLUGINS: ConvertSignaturesIntoPlugins<ScatterChar
     useChartInteraction,
     useChartHighlight,
     useChartVoronoi,
+    useChartKeyboardNavigation,
     useChartProZoom,
     useChartProExport,
   ];

packages/x-charts-pro/src/ScatterChartPro/ScatterChartPro.tsx

@@ -186,6 +186,7 @@ ScatterChartPro.propTypes = {
    * @default false
    */
   disableVoronoi: PropTypes.bool,
+  enableKeyboardNavigation: PropTypes.bool,
   /**
    * Option to display a cartesian grid in the background.
    */

packages/x-charts/src/BarChart/BarChart.plugins.ts

@@ -14,18 +14,24 @@ import {
   useChartHighlight,
   UseChartHighlightSignature,
 } from '../internals/plugins/featurePlugins/useChartHighlight';
+import {
+  useChartKeyboardNavigation,
+  UseChartKeyboardNavigationSignature,
+} from '../internals/plugins/featurePlugins/useChartKeyboardNavigation';
 import { ConvertSignaturesIntoPlugins } from '../internals/plugins/models/helpers';
 
 export type BarChartPluginsSignatures = [
   UseChartZAxisSignature,
   UseChartCartesianAxisSignature<'bar'>,
   UseChartInteractionSignature,
   UseChartHighlightSignature,
+  UseChartKeyboardNavigationSignature,
 ];
 
 export const BAR_CHART_PLUGINS: ConvertSignaturesIntoPlugins<BarChartPluginsSignatures> = [
   useChartZAxis,
   useChartCartesianAxis,
   useChartInteraction,
   useChartHighlight,
+  useChartKeyboardNavigation,
 ];

packages/x-charts/src/BarChart/BarChart.tsx

@@ -205,6 +205,7 @@ BarChart.propTypes = {
    * @default false
    */
   disableAxisListener: PropTypes.bool,
+  enableKeyboardNavigation: PropTypes.bool,
   /**
    * Option to display a cartesian grid in the background.
    */

packages/x-charts/src/BarChart/BarElement.tsx

@@ -7,6 +7,7 @@ import { BarElementOwnerState, useUtilityClasses } from './barElementClasses';
 import { useInteractionItemProps } from '../hooks/useInteractionItemProps';
 import { useItemHighlighted } from '../hooks/useItemHighlighted';
 import { AnimatedBarElement, BarProps } from './AnimatedBarElement';
+import { useIsItemFocused } from '../hooks/useIsItemFocused';
 
 export interface BarElementSlots {
   /**
@@ -67,6 +68,11 @@ function BarElement(props: BarElementProps) {
     seriesId: id,
     dataIndex,
   });
+  const isFocused = useIsItemFocused({
+    seriesType: 'bar',
+    seriesId: id,
+    dataIndex,
+  });
 
   const ownerState = {
     id,
@@ -75,6 +81,7 @@ function BarElement(props: BarElementProps) {
     color,
     isFaded,
     isHighlighted,
+    isFocused,
   };
 
   const classes = useUtilityClasses(ownerState);
@@ -103,6 +110,7 @@ function BarElement(props: BarElementProps) {
       fill: color,
       skipAnimation,
       layout,
+      'data-focused': isFocused || undefined,
     },
     className: classes.root,
     ownerState,

packages/x-charts/src/ChartContainer/useChartContainerProps.ts

@@ -55,6 +55,7 @@ export const useChartContainerProps = <
     slots,
     slotProps,
     experimentalFeatures,
+    enableKeyboardNavigation,
     ...other
   } = props as ChartContainerProps<TSeries, AllPluginSignatures>;
 
@@ -91,6 +92,7 @@ export const useChartContainerProps = <
     localeText,
     seriesConfig,
     experimentalFeatures,
+    enableKeyboardNavigation,
     plugins: plugins ?? DEFAULT_PLUGINS,
     slots,
     slotProps,

packages/x-charts/src/ChartsSurface/ChartsSurface.tsx

@@ -11,6 +11,10 @@ import {
   selectorChartContainerSize,
   selectorChartPropsSize,
 } from '../internals/plugins/corePlugins/useChartDimensions/useChartDimensions.selectors';
+import {
+  selectorChartsHasFocusedItem,
+  selectorChartsIsKeyboardNavigationEnabled,
+} from '../internals/plugins/featurePlugins/useChartKeyboardNavigation';
 
 export interface ChartsSurfaceProps
   extends Omit<
@@ -40,6 +44,13 @@ const ChartsSurfaceStyles = styled('svg', {
   // For example, prevent page scroll & zoom.
   touchAction: 'pan-y',
   userSelect: 'none',
+  '&[data-has-focused-item=true]': {
+    // Move the focus outline responsibility to children
+    outline: 'none',
+  },
+  '& [data-focused=true]': {
+    outline: 'auto',
+  },
 }));
 
 /**
@@ -63,6 +74,8 @@ const ChartsSurface = React.forwardRef<SVGSVGElement, ChartsSurfaceProps>(functi
   const store = useStore();
   const { width: svgWidth, height: svgHeight } = useSelector(store, selectorChartContainerSize);
   const { width: propsWidth, height: propsHeight } = useSelector(store, selectorChartPropsSize);
+  const isKeyboardNavigationEnabled = useSelector(store, selectorChartsIsKeyboardNavigationEnabled);
+  const hasFocusedItem = useSelector(store, selectorChartsHasFocusedItem);
   const svgRef = useSvgRef();
   const handleRef = useForkRef(svgRef, ref);
   const themeProps = useThemeProps({ props: inProps, name: 'MuiChartsSurface' });
@@ -76,6 +89,8 @@ const ChartsSurface = React.forwardRef<SVGSVGElement, ChartsSurfaceProps>(functi
       ownerState={{ width: propsWidth, height: propsHeight }}
       viewBox={`${0} ${0} ${svgWidth} ${svgHeight}`}
       className={className}
+      tabIndex={isKeyboardNavigationEnabled ? 0 : undefined}
+      data-has-focused-item={hasFocusedItem || undefined}
       {...other}
       ref={handleRef}
     >

packages/x-charts/src/LineChart/FocusedMark.tsx

@@ -0,0 +1,38 @@
+'use client';
+import * as React from 'react';
+import { useTheme } from '@mui/material/styles';
+import { useFocusedItem } from '../hooks/useFocusedItem';
+import { useLineSeriesContext, useXAxes, useYAxes } from '../hooks';
+
+const RADIUS = 6;
+export function FocusedMark() {
+  const theme = useTheme();
+  const focusedItem = useFocusedItem();
+
+  const lineSeries = useLineSeriesContext();
+  const { xAxis, xAxisIds } = useXAxes();
+  const { yAxis, yAxisIds } = useYAxes();
+
+  if (focusedItem === null || focusedItem.seriesType !== 'line' || !lineSeries) {
+    return null;
+  }
+
+  const series = lineSeries?.series[focusedItem.seriesId];
+
+  const xAxisId = series.xAxisId ?? xAxisIds[0];
+  const yAxisId = series.yAxisId ?? yAxisIds[0];
+
+  return (
+    <rect
+      fill="none"
+      stroke={(theme.vars ?? theme).palette.text.primary}
+      strokeWidth={2}
+      x={xAxis[xAxisId].scale(xAxis[xAxisId].data![focusedItem.dataIndex])! - RADIUS}
+      y={yAxis[yAxisId].scale(series.stackedData[focusedItem.dataIndex][1])! - RADIUS}
+      width={2 * RADIUS}
+      height={2 * RADIUS}
+      rx={3}
+      ry={3}
+    />
+  );
+}