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' | 'description' | 'useDefaultSummary' | 'label' | 'HeadingLevel';
 
 // @public (undocumented)
 export const DEPTH_KEY = "depth";
@@ -1746,7 +1746,9 @@ export interface SettingsSpec extends Spec, LegendSpec {
     description?: string;
     // @alpha
     externalPointerEvents: ExternalPointerEventsSettings;
+    HeadingLevel: 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
     hideDuplicateAxes: boolean;
+    label?: string;
     minBrushDelta?: number;
     noResults?: ComponentType | ReactChild;
     // (undocumented)

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

@@ -82,6 +82,8 @@ export interface ReactiveChartStateProps {
   description?: string;
   useDefaultSummary: boolean;
   chartId: string;
+  label?: string;
+  HeadingLevel: 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 }
 
 interface ReactiveChartDispatchProps {
@@ -162,6 +164,8 @@ class XYChartComponent extends React.Component<XYChartProps> {
       description,
       useDefaultSummary,
       chartId,
+      label,
+      HeadingLevel,
     } = this.props;
 
     if (!initialized || isChartEmpty) {
@@ -172,6 +176,7 @@ 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 = `${chartId}--label`;
     return (
       <figure>
         <canvas
@@ -187,6 +192,7 @@ class XYChartComponent extends React.Component<XYChartProps> {
           role="presentation"
           {...(description ? { 'aria-describedby': chartIdDescription } : {})}
         >
+          {label && <HeadingLevel id={chartIdLabel}>{label}</HeadingLevel>}
           {(description || useDefaultSummary) && (
             <div className="echScreenReaderOnly">
               {description && <p id={chartIdDescription}>{description}</p>}
@@ -255,6 +261,8 @@ const DEFAULT_PROPS: ReactiveChartStateProps = {
   description: undefined,
   useDefaultSummary: true,
   chartId: '',
+  label: undefined,
+  HeadingLevel: 'h2',
 };
 
 const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
@@ -263,7 +271,7 @@ const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
   }
 
   const { geometries, geometriesIndex } = computeSeriesGeometriesSelector(state);
-  const { debug, description, useDefaultSummary } = getSettingsSpecSelector(state);
+  const { debug, description, useDefaultSummary, label, HeadingLevel } = getSettingsSpecSelector(state);
 
   return {
     initialized: true,
@@ -288,6 +296,8 @@ const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
     description,
     useDefaultSummary,
     chartId: getChartIdSelector(state),
+    label,
+    HeadingLevel,
   };
 };
 

src/components/__snapshots__/chart.test.tsx.snap

@@ -54,7 +54,7 @@ exports[`Chart should render the legend name test 1`] = `
         <Connect(SpecsParserComponent)>
           <SpecsParserComponent specParsed={[Function (anonymous)]} specUnmounted={[Function (anonymous)]}>
             <Connect(SpecInstance) debug={true} rendering=\\"svg\\" showLegend={true}>
-              <SpecInstance debug={true} rendering=\\"svg\\" showLegend={true} upsertSpec={[Function (anonymous)]} removeSpec={[Function (anonymous)]} id=\\"__global__settings___\\" chartType=\\"global\\" specType=\\"settings\\" rotation={0} animateData={true} resizeDebounce={10} tooltip={{...}} externalPointerEvents={{...}} hideDuplicateAxes={false} baseTheme={{...}} brushAxis=\\"x\\" minBrushDelta={2} useDefaultSummary={true} showLegendExtra={false} legendMaxDepth={Infinity} legendPosition=\\"right\\" />
+              <SpecInstance debug={true} rendering=\\"svg\\" showLegend={true} upsertSpec={[Function (anonymous)]} removeSpec={[Function (anonymous)]} id=\\"__global__settings___\\" chartType=\\"global\\" specType=\\"settings\\" rotation={0} animateData={true} resizeDebounce={10} tooltip={{...}} externalPointerEvents={{...}} hideDuplicateAxes={false} baseTheme={{...}} brushAxis=\\"x\\" minBrushDelta={2} useDefaultSummary={true} HeadingLevel=\\"h2\\" showLegendExtra={false} legendMaxDepth={Infinity} legendPosition=\\"right\\" />
             </Connect(SpecInstance)>
             <Connect(SpecInstance) id=\\"test\\" data={{...}}>
               <SpecInstance id=\\"test\\" data={{...}} upsertSpec={[Function (anonymous)]} removeSpec={[Function (anonymous)]} chartType=\\"xy_axis\\" specType=\\"series\\" seriesType=\\"bar\\" groupId=\\"__global__\\" xScaleType=\\"ordinal\\" yScaleType=\\"linear\\" xAccessor=\\"x\\" yAccessors={{...}} yScaleToDataExtent={false} hideInLegend={false} enableHistogramMode={false} />
@@ -72,7 +72,7 @@ exports[`Chart should render the legend name test 1`] = `
                   </Crosshair>
                 </Connect(Crosshair)>
                 <Connect(XYChart) forwardStageRef={{...}}>
-                  <XYChart forwardStageRef={{...}} initialized={true} isChartEmpty={false} debug={true} geometries={{...}} geometriesIndex={{...}} theme={{...}} chartContainerDimensions={{...}} highlightedLegendItem={[undefined]} rotation={0} renderingArea={{...}} chartTransform={{...}} axesSpecs={{...}} perPanelAxisGeoms={{...}} perPanelGridLines={{...}} axesStyles={{...}} annotationDimensions={{...}} annotationSpecs={{...}} panelGeoms={{...}} seriesTypes={{...}} description={[undefined]} useDefaultSummary={true} chartId=\\"chart1\\" onChartRendered={[Function (anonymous)]}>
+                  <XYChart forwardStageRef={{...}} initialized={true} isChartEmpty={false} debug={true} geometries={{...}} geometriesIndex={{...}} theme={{...}} chartContainerDimensions={{...}} highlightedLegendItem={[undefined]} rotation={0} renderingArea={{...}} chartTransform={{...}} axesSpecs={{...}} perPanelAxisGeoms={{...}} perPanelGridLines={{...}} axesStyles={{...}} annotationDimensions={{...}} annotationSpecs={{...}} panelGeoms={{...}} seriesTypes={{...}} description={[undefined]} useDefaultSummary={true} chartId=\\"chart1\\" label={[undefined]} HeadingLevel=\\"h2\\" onChartRendered={[Function (anonymous)]}>
                     <figure>
                       <canvas className=\\"echCanvasRenderer\\" width={150} height={200} style={{...}} role=\\"presentation\\">
                         <div className=\\"echScreenReaderOnly\\">

src/specs/constants.ts

@@ -156,6 +156,7 @@ export const DEFAULT_SETTINGS_SPEC: SettingsSpec = {
   brushAxis: BrushAxis.X,
   minBrushDelta: 2,
   useDefaultSummary: true,
+  HeadingLevel: 'h2',
 
   ...DEFAULT_LEGEND_CONFIG,
 };

src/specs/settings.tsx

@@ -548,6 +548,15 @@ export interface SettingsSpec extends Spec, LegendSpec {
    * Render component for no results UI
    */
   noResults?: ComponentType | ReactChild;
+  /**
+   * User can specify the heading level for the label
+   * @defaultValue 'h2'
+   */
+  HeadingLevel: 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  /**
+   * User can set a label
+   */
+  label?: string;
   /**
    * User can provide a custom description to be read by a screen reader about their chart
    */
@@ -619,7 +628,9 @@ export type DefaultSettingsProps =
   | 'legendPosition'
   | 'legendMaxDepth'
   | 'description'
-  | 'useDefaultSummary';
+  | 'useDefaultSummary'
+  | 'label'
+  | 'HeadingLevel';
 
 /** @public */
 export type SettingsSpecProps = Partial<Omit<SettingsSpec, 'chartType' | 'specType' | 'id'>>;

stories/test_cases/6_a11y_custom_description.tsx

@@ -17,18 +17,27 @@
  * under the License.
  */
 
-import { boolean, text } from '@storybook/addon-knobs';
+import { boolean, text, select } from '@storybook/addon-knobs';
 import React from 'react';
 
 import { AreaSeries, Chart, ScaleType, Settings } from '../../src';
 import { KIBANA_METRICS } from '../../src/utils/data_samples/test_dataset_kibana';
 
 export const Example = () => {
   const automatedSeries = boolean('Use the default generated series types of charts for screen readers', true);
-  const customDescriptionForScreenReaders = text('custom description for screen readers', '');
+  const customDescriptionForScreenReaders = text('add a description for screen readers', '');
+  const customLabelForScreenReaders = text('add a label for screen readers', '');
+  const headingLevelForScreenReaders = customLabelForScreenReaders
+    ? select('heading level for label', { H2: 'h2', H3: 'h3', H4: 'h4', H5: 'h5', H6: 'h6' }, 'h2')
+    : undefined;
   return (
     <Chart className="story-chart">
-      <Settings description={customDescriptionForScreenReaders} useDefaultSummary={automatedSeries} />
+      <Settings
+        description={customDescriptionForScreenReaders}
+        useDefaultSummary={automatedSeries}
+        label={customLabelForScreenReaders}
+        HeadingLevel={headingLevelForScreenReaders}
+      />
       <AreaSeries
         id="area"
         xScaleType={ScaleType.Time}

stories/test_cases/test_cases.stories.tsx

@@ -31,4 +31,4 @@ export { Example as chromePathBugFix } from './2_chrome_path_bug_fix';
 export { Example as noAxesAnnotationBugFix } from './3_no_axes_annotation';
 export { Example as filterZerosInLogFitDomain } from './4_filter_zero_values_log';
 export { Example as legendScrollBarSizing } from './5_legend_scroll_bar_sizing';
-export { Example as addCustomDescription } from './6_a11y_custom_description';
+export { Example as accessibilityCustomizations } from './6_a11y_custom_description';