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' | 'accessibilityDescription' | 'useDefaultSummary' | 'ariaLabel' | 'headingLevel';
+export type DefaultSettingsProps = 'id' | 'chartType' | 'specType' | 'rendering' | 'rotation' | 'resizeDebounce' | 'animateData' | 'debug' | 'tooltip' | 'theme' | 'hideDuplicateAxes' | 'brushAxis' | 'minBrushDelta' | 'externalPointerEvents' | 'showLegend' | 'showLegendExtra' | 'legendPosition' | 'legendMaxDepth' | 'ariaUseDefaultSummary' | 'ariaLabelHeadingLevel';
 
 // @public (undocumented)
 export const DEPTH_KEY = "depth";
@@ -1735,20 +1735,22 @@ export const Settings: React_2.FunctionComponent<SettingsSpecProps>;
 
 // @public
 export interface SettingsSpec extends Spec, LegendSpec {
-    accessibilityDescription?: string;
     allowBrushingLastHistogramBucket?: boolean;
     // (undocumented)
     animateData: boolean;
+    ariaDescribedBy?: string;
+    ariaDescription?: string;
     ariaLabel?: string;
+    ariaLabelHeadingLevel: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
     ariaLabelledBy?: string;
+    ariaUseDefaultSummary: boolean;
     baseTheme?: Theme;
     brushAxis?: BrushAxis;
     debug: boolean;
     // @alpha
     debugState?: boolean;
     // @alpha
     externalPointerEvents: ExternalPointerEventsSettings;
-    headingLevel: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
     hideDuplicateAxes: boolean;
     minBrushDelta?: number;
     noResults?: ComponentType | ReactChild;
@@ -1777,7 +1779,6 @@ export interface SettingsSpec extends Spec, LegendSpec {
     roundHistogramBrushValues?: boolean;
     theme?: PartialTheme | PartialTheme[];
     tooltip: TooltipSettings;
-    useDefaultSummary: boolean;
     // (undocumented)
     xDomain?: CustomXDomain;
 }

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

@@ -22,10 +22,16 @@ import { connect } from 'react-redux';
 import { bindActionCreators, Dispatch } from 'redux';
 
 import { LegendItem } from '../../../../common/legend';
+import { Description } from '../../../../components/accessibility/description';
+import { Label } from '../../../../components/accessibility/label';
 import { onChartRendered } from '../../../../state/actions/chart';
 import { GlobalChartState } from '../../../../state/chart_state';
+import {
+  A11ySettings,
+  DEFAULT_A11_SETTINGS,
+  getA11ySettingsSelector,
+} from '../../../../state/selectors/get_accessibility_config';
 import { getChartContainerDimensionsSelector } from '../../../../state/selectors/get_chart_container_dimensions';
-import { getChartIdSelector } from '../../../../state/selectors/get_chart_id';
 import { getChartRotationSelector } from '../../../../state/selectors/get_chart_rotation';
 import { getChartThemeSelector } from '../../../../state/selectors/get_chart_theme';
 import { getInternalIsInitializedSelector, InitStatus } from '../../../../state/selectors/get_internal_is_intialized';
@@ -79,12 +85,7 @@ export interface ReactiveChartStateProps {
   annotationSpecs: AnnotationSpec[];
   panelGeoms: PanelGeoms;
   seriesTypes: Set<SeriesType>;
-  accessibilityDescription?: string;
-  useDefaultSummary: boolean;
-  chartId: string;
-  ariaLabel?: string;
-  ariaLabelledBy?: string;
-  headingLevel: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
+  a11ySettings: A11ySettings;
 }
 
 interface ReactiveChartDispatchProps {
@@ -95,10 +96,6 @@ 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';
@@ -166,12 +163,7 @@ class XYChartComponent extends React.Component<XYChartProps> {
       isChartEmpty,
       chartContainerDimensions: { width, height },
       seriesTypes,
-      accessibilityDescription,
-      useDefaultSummary,
-      chartId,
-      ariaLabel,
-      ariaLabelledBy,
-      headingLevel,
+      a11ySettings,
     } = this.props;
 
     if (!initialized || isChartEmpty) {
@@ -181,42 +173,9 @@ 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}>{label}</h1>;
-        case 'h2':
-          return <h2 id={id}>{label}</h2>;
-        case 'h3':
-          return <h3 id={id}>{label}</h3>;
-        case 'h4':
-          return <h4 id={id}>{label}</h4>;
-        case 'h5':
-          return <h5 id={id}>{label}</h5>;
-        case 'h6':
-          return <h6 id={id}>{label}</h6>;
-        default:
-          return <p id={id}>{label}</p>;
-      }
-    };
     return (
-      <figure {...ariaProps}>
+      <figure aria-labelledby={a11ySettings.labelId} aria-describedby={a11ySettings.descriptionId}>
         <canvas
           ref={forwardStageRef}
           className="echCanvasRenderer"
@@ -229,19 +188,16 @@ class XYChartComponent extends React.Component<XYChartProps> {
           // eslint-disable-next-line jsx-a11y/no-interactive-element-to-noninteractive-role
           role="presentation"
         >
-          {/* @ts-ignore */}
-          <ChartLabel id={chartIdLabel} label={ariaLabel} heading={headingLevel} />
-          {(accessibilityDescription || useDefaultSummary) && (
-            <div className="echScreenReaderOnly">
-              {accessibilityDescription && <p id={chartIdDescription}>{accessibilityDescription}</p>}
-              {useDefaultSummary && (
-                <dl>
-                  <dt>Chart type</dt>
-                  <dd id={idForChartSeriesTypes}>{chartSeriesTypes}</dd>
-                </dl>
-              )}
-            </div>
-          )}
+          <div className="echScreenReaderOnly">
+            <Label {...a11ySettings} />
+            <Description {...a11ySettings} />
+            {a11ySettings.defaultSummaryId && (
+              <dl id={a11ySettings.defaultSummaryId}>
+                <dt>Chart type</dt>
+                <dd>{chartSeriesTypes}</dd>
+              </dl>
+            )}
+          </div>
         </canvas>
       </figure>
     );
@@ -296,12 +252,7 @@ const DEFAULT_PROPS: ReactiveChartStateProps = {
   annotationSpecs: [],
   panelGeoms: [],
   seriesTypes: new Set(),
-  accessibilityDescription: undefined,
-  useDefaultSummary: true,
-  chartId: '',
-  ariaLabel: undefined,
-  ariaLabelledBy: undefined,
-  headingLevel: 'h2',
+  a11ySettings: DEFAULT_A11_SETTINGS,
 };
 
 const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
@@ -310,14 +261,7 @@ const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
   }
 
   const { geometries, geometriesIndex } = computeSeriesGeometriesSelector(state);
-  const {
-    debug,
-    accessibilityDescription,
-    useDefaultSummary,
-    ariaLabel,
-    ariaLabelledBy,
-    headingLevel,
-  } = getSettingsSpecSelector(state);
+  const { debug } = getSettingsSpecSelector(state);
 
   return {
     initialized: true,
@@ -339,12 +283,7 @@ const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
     annotationSpecs: getAnnotationSpecsSelector(state),
     panelGeoms: computePanelsSelectors(state),
     seriesTypes: getSeriesTypes(state),
-    accessibilityDescription,
-    useDefaultSummary,
-    chartId: getChartIdSelector(state),
-    ariaLabel,
-    ariaLabelledBy,
-    headingLevel,
+    a11ySettings: getA11ySettingsSelector(state),
   };
 };
 

src/chart_types/xy_chart/state/chart_state.accessibility.test.ts

@@ -22,6 +22,7 @@ import { Store } from 'redux';
 import { MockGlobalSpec, MockSeriesSpec } from '../../../mocks/specs';
 import { MockStore } from '../../../mocks/store/store';
 import { GlobalChartState } from '../../../state/chart_state';
+import { DEFAULT_A11_SETTINGS } from '../../../state/selectors/get_accessibility_config';
 import { getSettingsSpecSelector } from '../../../state/selectors/get_settings_specs';
 
 describe('test accessibility prop defaults', () => {
@@ -44,15 +45,15 @@ describe('test accessibility prop defaults', () => {
   it('should test defaults', () => {
     const state = store.getState();
     const {
-      accessibilityDescription,
-      useDefaultSummary,
-      headingLevel,
+      ariaDescription,
+      ariaUseDefaultSummary,
+      ariaLabelHeadingLevel,
       ariaLabel,
       ariaLabelledBy,
     } = getSettingsSpecSelector(state);
-    expect(accessibilityDescription).toBeUndefined();
-    expect(useDefaultSummary).toBeTrue();
-    expect(headingLevel).toBe('p');
+    expect(ariaDescription).toBeUndefined();
+    expect(ariaUseDefaultSummary).toBeTrue();
+    expect(ariaLabelHeadingLevel).toBe(DEFAULT_A11_SETTINGS.labelHeadingLevel);
     expect(ariaLabel).toBeUndefined();
     expect(ariaLabelledBy).toBeUndefined();
   });
@@ -78,27 +79,27 @@ describe('custom description for screen readers', () => {
     MockStore.addSpecs(
       [
         MockGlobalSpec.settings({
-          accessibilityDescription: 'This is sample Kibana data',
+          ariaDescription: 'This is sample Kibana data',
         }),
       ],
       store,
     );
     const state = store.getState();
-    const { accessibilityDescription } = getSettingsSpecSelector(state);
-    expect(accessibilityDescription).toBe('This is sample Kibana data');
+    const { ariaDescription } = getSettingsSpecSelector(state);
+    expect(ariaDescription).toBe('This is sample Kibana data');
   });
   it('should be able to disable generated descriptions', () => {
     MockStore.addSpecs(
       [
         MockGlobalSpec.settings({
-          useDefaultSummary: false,
+          ariaUseDefaultSummary: false,
         }),
       ],
       store,
     );
     const state = store.getState();
-    const { useDefaultSummary } = getSettingsSpecSelector(state);
-    expect(useDefaultSummary).toBe(false);
+    const { ariaUseDefaultSummary } = getSettingsSpecSelector(state);
+    expect(ariaUseDefaultSummary).toBe(false);
   });
 });
 describe('custom labels for screen readers', () => {
@@ -129,32 +130,32 @@ describe('custom labels for screen readers', () => {
     );
     const state = store.getState();
     const { ariaLabel } = getSettingsSpecSelector(state);
-    expect(ariaLabel).toBeTruthy();
+    expect(ariaLabel).toBe('Label set by user');
   });
   it('should allow labelledBy set by the user', () => {
     MockStore.addSpecs(
       [
         MockGlobalSpec.settings({
-          ariaLabelledBy: 'Label',
+          ariaLabelledBy: 'label-id',
         }),
       ],
       store,
     );
     const state = store.getState();
     const { ariaLabelledBy } = getSettingsSpecSelector(state);
-    expect(ariaLabelledBy).toBeTruthy();
+    expect(ariaLabelledBy).toBe('label-id');
   });
   it('should allow users to specify valid heading levels', () => {
     MockStore.addSpecs(
       [
         MockGlobalSpec.settings({
-          headingLevel: 'h5',
+          ariaLabelHeadingLevel: 'h5',
         }),
       ],
       store,
     );
     const state = store.getState();
-    const { headingLevel } = getSettingsSpecSelector(state);
-    expect(headingLevel).toBe('h5');
+    const { ariaLabelHeadingLevel } = getSettingsSpecSelector(state);
+    expect(ariaLabelHeadingLevel).toBe('h5');
   });
 });

src/components/accessibility/description.tsx

@@ -0,0 +1,28 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import React from 'react';
+
+import { A11ySettings } from '../../state/selectors/get_accessibility_config';
+
+/** @internal */
+export function Description(props: A11ySettings) {
+  if (!props.description) return null;
+  return <p id={props.descriptionId}>{props.description}</p>;
+}

src/components/accessibility/label.tsx

@@ -0,0 +1,29 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import React from 'react';
+
+import { A11ySettings } from '../../state/selectors/get_accessibility_config';
+
+/** @internal */
+export function Label(props: A11ySettings) {
+  if (!props.label) return null;
+  const Heading = props.labelHeadingLevel;
+  return <Heading id={props.labelId}>{props.label}</Heading>;
+}

src/specs/constants.ts

@@ -155,8 +155,7 @@ export const DEFAULT_SETTINGS_SPEC: SettingsSpec = {
   baseTheme: LIGHT_THEME,
   brushAxis: BrushAxis.X,
   minBrushDelta: 2,
-  useDefaultSummary: true,
-  headingLevel: 'p',
-
+  ariaUseDefaultSummary: true,
+  ariaLabelHeadingLevel: 'h2',
   ...DEFAULT_LEGEND_CONFIG,
 };