feat(a11y): add label for screen readers

api/charts.api.md

@@ -621,7 +621,7 @@ export const DEFAULT_TOOLTIP_SNAP = true;
 export const DEFAULT_TOOLTIP_TYPE: "vertical";
 
 // @public (undocumented)
-export type DefaultSettingsProps = 'id' | 'chartType' | 'specType' | 'rendering' | 'rotation' | 'resizeDebounce' | 'animateData' | 'debug' | 'tooltip' | 'theme' | 'hideDuplicateAxes' | 'brushAxis' | 'minBrushDelta' | 'externalPointerEvents' | 'showLegend' | 'showLegendExtra' | 'legendPosition' | 'legendMaxDepth' | 'description' | 'useDefaultSummary';
+export type DefaultSettingsProps = 'id' | 'chartType' | 'specType' | 'rendering' | 'rotation' | 'resizeDebounce' | 'animateData' | 'debug' | 'tooltip' | 'theme' | 'hideDuplicateAxes' | 'brushAxis' | 'minBrushDelta' | 'externalPointerEvents' | 'showLegend' | 'showLegendExtra' | 'legendPosition' | 'legendMaxDepth' | 'accessibilityDescription' | 'useDefaultSummary' | 'ariaLabel' | 'headingLevel';
 
 // @public (undocumented)
 export const DEPTH_KEY = "depth";
@@ -1735,17 +1735,20 @@ export const Settings: React_2.FunctionComponent<SettingsSpecProps>;
 
 // @public
 export interface SettingsSpec extends Spec, LegendSpec {
+    accessibilityDescription?: string;
     allowBrushingLastHistogramBucket?: boolean;
     // (undocumented)
     animateData: boolean;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
     baseTheme?: Theme;
     brushAxis?: BrushAxis;
     debug: boolean;
     // @alpha
     debugState?: boolean;
-    description?: string;
     // @alpha
     externalPointerEvents: ExternalPointerEventsSettings;
+    headingLevel: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
     hideDuplicateAxes: boolean;
     minBrushDelta?: number;
     noResults?: ComponentType | ReactChild;

src/chart_types/xy_chart/renderer/canvas/xy_chart.tsx

@@ -79,9 +79,12 @@ export interface ReactiveChartStateProps {
   annotationSpecs: AnnotationSpec[];
   panelGeoms: PanelGeoms;
   seriesTypes: Set<SeriesType>;
-  description?: string;
+  accessibilityDescription?: string;
   useDefaultSummary: boolean;
   chartId: string;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
+  headingLevel: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
 }
 
 interface ReactiveChartDispatchProps {
@@ -92,6 +95,10 @@ interface ReactiveChartOwnProps {
 }
 const CLIPPING_MARGINS = 0.5;
 
+type AriaProps = {
+  [key: string]: string | undefined;
+};
+
 type XYChartProps = ReactiveChartStateProps & ReactiveChartDispatchProps & ReactiveChartOwnProps;
 class XYChartComponent extends React.Component<XYChartProps> {
   static displayName = 'XYChart';
@@ -159,9 +166,12 @@ class XYChartComponent extends React.Component<XYChartProps> {
       isChartEmpty,
       chartContainerDimensions: { width, height },
       seriesTypes,
-      description,
+      accessibilityDescription,
       useDefaultSummary,
       chartId,
+      ariaLabel,
+      ariaLabelledBy,
+      headingLevel,
     } = this.props;
 
     if (!initialized || isChartEmpty) {
@@ -172,8 +182,69 @@ class XYChartComponent extends React.Component<XYChartProps> {
     const chartSeriesTypes =
       seriesTypes.size > 1 ? `Mixed chart: ${[...seriesTypes].join(' and ')} chart` : `${[...seriesTypes]} chart`;
     const chartIdDescription = `${chartId}--description`;
+    const chartIdLabel = ariaLabel ? `${chartId}--label` : undefined;
+    const idForChartSeriesTypes = `${chartId}--series-types`;
+
+    const ariaProps: AriaProps = {};
+
+    if (ariaLabelledBy || ariaLabel) {
+      ariaProps['aria-labelledby'] = ariaLabelledBy ?? chartIdLabel;
+    }
+    if (accessibilityDescription || useDefaultSummary) {
+      ariaProps['aria-describedby'] = `${accessibilityDescription ? chartIdDescription : undefined} ${
+        useDefaultSummary ? idForChartSeriesTypes : undefined
+      }`;
+    }
+
+    const ChartLabel = (heading: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p', id: string, label?: string) => {
+      if (!label) return null;
+      switch (heading) {
+        case 'h1':
+          return (
+            <h1 id={id} aria-label={label}>
+              {label}
+            </h1>
+          );
+        case 'h2':
+          return (
+            <h2 id={id} aria-label={label}>
+              {label}
+            </h2>
+          );
+        case 'h3':
+          return (
+            <h3 id={id} aria-label={label}>
+              {label}
+            </h3>
+          );
+        case 'h4':
+          return (
+            <h4 id={id} aria-label={label}>
+              {label}
+            </h4>
+          );
+        case 'h5':
+          return (
+            <h5 id={id} aria-label={label}>
+              {label}
+            </h5>
+          );
+        case 'h6':
+          return (
+            <h6 id={id} aria-label={label}>
+              {label}
+            </h6>
+          );
+        default:
+          return (
+            <p id={id} aria-label={label}>
+              {label}
+            </p>
+          );
+      }
+    };
     return (
-      <figure>
+      <figure {...ariaProps}>
         <canvas
           ref={forwardStageRef}
           className="echCanvasRenderer"
@@ -185,15 +256,16 @@ class XYChartComponent extends React.Component<XYChartProps> {
           }}
           // eslint-disable-next-line jsx-a11y/no-interactive-element-to-noninteractive-role
           role="presentation"
-          {...(description ? { 'aria-describedby': chartIdDescription } : {})}
         >
-          {(description || useDefaultSummary) && (
+          {/* @ts-ignore */}
+          <ChartLabel id={chartIdLabel} label={ariaLabel} heading={headingLevel} />
+          {(accessibilityDescription || useDefaultSummary) && (
             <div className="echScreenReaderOnly">
-              {description && <p id={chartIdDescription}>{description}</p>}
+              {accessibilityDescription && <p id={chartIdDescription}>{accessibilityDescription}</p>}
               {useDefaultSummary && (
                 <dl>
                   <dt>Chart type</dt>
-                  <dd>{chartSeriesTypes}</dd>
+                  <dd id={idForChartSeriesTypes}>{chartSeriesTypes}</dd>
                 </dl>
               )}
             </div>
@@ -252,9 +324,12 @@ const DEFAULT_PROPS: ReactiveChartStateProps = {
   annotationSpecs: [],
   panelGeoms: [],
   seriesTypes: new Set(),
-  description: undefined,
+  accessibilityDescription: undefined,
   useDefaultSummary: true,
   chartId: '',
+  ariaLabel: undefined,
+  ariaLabelledBy: undefined,
+  headingLevel: 'h2',
 };
 
 const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
@@ -263,7 +338,14 @@ const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
   }
 
   const { geometries, geometriesIndex } = computeSeriesGeometriesSelector(state);
-  const { debug, description, useDefaultSummary } = getSettingsSpecSelector(state);
+  const {
+    debug,
+    accessibilityDescription,
+    useDefaultSummary,
+    ariaLabel,
+    ariaLabelledBy,
+    headingLevel,
+  } = getSettingsSpecSelector(state);
 
   return {
     initialized: true,
@@ -285,9 +367,12 @@ const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
     annotationSpecs: getAnnotationSpecsSelector(state),
     panelGeoms: computePanelsSelectors(state),
     seriesTypes: getSeriesTypes(state),
-    description,
+    accessibilityDescription,
     useDefaultSummary,
     chartId: getChartIdSelector(state),
+    ariaLabel,
+    ariaLabelledBy,
+    headingLevel,
   };
 };