feat(a11y): allow user to add optional semantic meaning to goal/gauge charts

packages/charts/api/charts.api.md

@@ -801,6 +801,8 @@ export interface GoalSpec extends Spec {
     // (undocumented)
     labelMinor: string | BandFillColorAccessor;
     // (undocumented)
+    semanticValues?: Array<(number | string)[]>;
+    // (undocumented)
     specType: typeof SpecType.Series;
     // Warning: (ae-forgotten-export) The symbol "GoalSubtype" needs to be exported by the entry point index.d.ts
     //

packages/charts/src/chart_types/goal_chart/layout/types/viewmodel_types.ts

@@ -24,7 +24,8 @@ import { GoalSubtype } from '../../specs/constants';
 import { config } from '../config/config';
 import { Config } from './config_types';
 
-interface BandViewModel {
+/** @internal */
+export interface BandViewModel {
   value: number;
   fillColor: string;
 }
@@ -50,6 +51,7 @@ export interface BulletViewModel {
   lowestValue: number;
   aboveBaseCount: number;
   belowBaseCount: number;
+  semanticValues?: Array<(string | number)[]>;
 }
 
 /** @internal */

packages/charts/src/chart_types/goal_chart/layout/viewmodel/viewmodel.ts

@@ -52,6 +52,7 @@ export function shapeViewModel(textMeasure: TextMeasure, spec: GoalSpec, config:
     labelMinor,
     centralMajor,
     centralMinor,
+    semanticValues,
   } = spec;
 
   const [lowestValue, highestValue] = [base, target, actual, ...bands, ...ticks].reduce(
@@ -95,6 +96,7 @@ export function shapeViewModel(textMeasure: TextMeasure, spec: GoalSpec, config:
     lowestValue,
     aboveBaseCount,
     belowBaseCount,
+    semanticValues,
   };
 
   // combined viewModel

packages/charts/src/chart_types/goal_chart/renderer/canvas/canvas_renderers.ts

@@ -85,7 +85,6 @@ export function renderCanvas2d(
     const vertical = subtype === GoalSubtype.VerticalBullet;
 
     const domain = [lowestValue, highestValue];
-
     const data = {
       base: { value: base },
       ...Object.fromEntries(bands.map(({ value }, index) => [`qualitative_${index}`, { value }])),

packages/charts/src/chart_types/goal_chart/renderer/canvas/connected_component.tsx

@@ -21,7 +21,7 @@ import React, { MouseEvent, RefObject } from 'react';
 import { connect } from 'react-redux';
 import { bindActionCreators, Dispatch } from 'redux';
 
-import { ScreenReaderSummary } from '../../../../components/accessibility';
+import { GoalSemanticDescription, ScreenReaderSummary } from '../../../../components/accessibility';
 import { onChartRendered } from '../../../../state/actions/chart';
 import { GlobalChartState } from '../../../../state/chart_state';
 import {
@@ -33,13 +33,15 @@ import { getInternalIsInitializedSelector, InitStatus } from '../../../../state/
 import { Dimensions } from '../../../../utils/dimensions';
 import { nullShapeViewModel, ShapeViewModel } from '../../layout/types/viewmodel_types';
 import { geometries } from '../../state/selectors/geometries';
+import { getGoalChartSemanticDataSelector } from '../../state/selectors/get_goal_chart_data';
 import { renderCanvas2d } from './canvas_renderers';
 
 interface ReactiveChartStateProps {
   initialized: boolean;
   geometries: ShapeViewModel;
   chartContainerDimensions: Dimensions;
   a11ySettings: A11ySettings;
+  semanticValues?: Array<(string | number)[]>;
 }
 
 interface ReactiveChartDispatchProps {
@@ -112,11 +114,11 @@ class Component extends React.Component<Props> {
       chartContainerDimensions: { width, height },
       forwardStageRef,
       a11ySettings,
+      semanticValues,
     } = this.props;
     if (!initialized || width === 0 || height === 0) {
       return null;
     }
-
     return (
       <figure aria-labelledby={a11ySettings.labelId} aria-describedby={a11ySettings.descriptionId}>
         <canvas
@@ -133,6 +135,7 @@ class Component extends React.Component<Props> {
           role="presentation"
         >
           <ScreenReaderSummary />
+          {semanticValues && semanticValues.length > 1 && <GoalSemanticDescription semanticValues={semanticValues} />}
         </canvas>
       </figure>
     );
@@ -183,6 +186,7 @@ const mapStateToProps = (state: GlobalChartState): ReactiveChartStateProps => {
     geometries: geometries(state),
     chartContainerDimensions: state.parentDimensions,
     a11ySettings: getA11ySettingsSelector(state),
+    semanticValues: getGoalChartSemanticDataSelector(state),
   };
 };
 

packages/charts/src/chart_types/goal_chart/specs/index.ts

@@ -67,6 +67,7 @@ export interface GoalSpec extends Spec {
   centralMajor: string | BandFillColorAccessor;
   centralMinor: string | BandFillColorAccessor;
   config: RecursivePartial<Config>;
+  semanticValues?: Array<(number | string)[]>;
 }
 
 type SpecRequiredProps = Pick<GoalSpec, 'id' | 'actual'>;

packages/charts/src/chart_types/goal_chart/state/selectors/get_goal_chart_data.ts

@@ -0,0 +1,59 @@
+/*
+ * 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 { createCustomCachedSelector } from '../../../../state/create_selector';
+import { geometries } from './geometries';
+
+/** @internal */
+export type GoalChartData = {
+  maximum: number;
+  minimum: number;
+  target: number;
+  value: number;
+};
+
+/** @internal */
+export type GoalChartLabels = {
+  minorLabel: string;
+  majorLabel: string;
+};
+
+/** @internal */
+export const getGoalChartDataSelector = createCustomCachedSelector(
+  [geometries],
+  (geoms): GoalChartData => {
+    const goalChartData: GoalChartData = {
+      maximum: geoms.bulletViewModel.highestValue,
+      minimum: geoms.bulletViewModel.lowestValue,
+      target: geoms.bulletViewModel.target,
+      value: geoms.bulletViewModel.actual,
+    };
+    return goalChartData;
+  },
+);
+
+/** @internal */
+export const getGoalChartLabelsSelector = createCustomCachedSelector([geometries], (geoms) => {
+  return { majorLabel: geoms.bulletViewModel.labelMajor, minorLabel: geoms.bulletViewModel.labelMinor };
+});
+
+/** @internal */
+export const getGoalChartSemanticDataSelector = createCustomCachedSelector([geometries], (geoms) => {
+  return geoms.bulletViewModel.semanticValues ?? [];
+});

packages/charts/src/chart_types/partition_chart/renderer/canvas/partition.tsx

@@ -21,8 +21,7 @@ import React, { MouseEvent, RefObject } from 'react';
 import { connect } from 'react-redux';
 import { bindActionCreators, Dispatch } from 'redux';
 
-import { ScreenReaderSummary } from '../../../../components/accessibility';
-import { ScreenReaderPartitionTable } from '../../../../components/accessibility/partitions_data_table';
+import { ScreenReaderSummary, ScreenReaderPartitionTable } from '../../../../components/accessibility';
 import { clearCanvas } from '../../../../renderers/canvas';
 import { SettingsSpec } from '../../../../specs/settings';
 import { onChartRendered } from '../../../../state/actions/chart';

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

@@ -74,11 +74,11 @@ exports[`Chart should render the legend name test 1`] = `
                       <canvas className=\\"echCanvasRenderer\\" width={150} height={200} style={{...}} role=\\"presentation\\" />
                     </figure>
                     <Connect(ScreenReaderSummaryComponent)>
-                      <ScreenReaderSummaryComponent chartTypeDescription=\\"bar chart\\" a11ySettings={{...}} dispatch={[Function: dispatch]}>
+                      <ScreenReaderSummaryComponent chartTypeDescription=\\"bar chart\\" a11ySettings={{...}} goalChartData={{...}} goalChartLabels={{...}} dispatch={[Function: dispatch]}>
                         <div className=\\"echScreenReaderOnly\\">
-                          <ScreenReaderLabel label={[undefined]} labelId={[undefined]} labelHeadingLevel=\\"p\\" description={[undefined]} descriptionId=\\"chart1--defaultSummary\\" defaultSummaryId=\\"chart1--defaultSummary\\" tableCaption={[undefined]} />
+                          <ScreenReaderLabel label={[undefined]} labelId={[undefined]} labelHeadingLevel=\\"p\\" description={[undefined]} descriptionId=\\"chart1--defaultSummary\\" defaultSummaryId=\\"chart1--defaultSummary\\" tableCaption={[undefined]} goalChartLabels={{...}} />
                           <ScreenReaderDescription label={[undefined]} labelId={[undefined]} labelHeadingLevel=\\"p\\" description={[undefined]} descriptionId=\\"chart1--defaultSummary\\" defaultSummaryId=\\"chart1--defaultSummary\\" tableCaption={[undefined]} />
-                          <ScreenReaderTypes label={[undefined]} labelId={[undefined]} labelHeadingLevel=\\"p\\" description={[undefined]} descriptionId=\\"chart1--defaultSummary\\" defaultSummaryId=\\"chart1--defaultSummary\\" tableCaption={[undefined]} chartTypeDescription=\\"bar chart\\">
+                          <ScreenReaderTypes label={[undefined]} labelId={[undefined]} labelHeadingLevel=\\"p\\" description={[undefined]} descriptionId=\\"chart1--defaultSummary\\" defaultSummaryId=\\"chart1--defaultSummary\\" tableCaption={[undefined]} chartTypeDescription=\\"bar chart\\" goalChartData={{...}}>
                             <dl>
                               <dt>
                                 Chart type:

packages/charts/src/components/accessibility/accessibility.test.tsx

@@ -20,6 +20,8 @@
 import { mount } from 'enzyme';
 import React from 'react';
 
+import { Goal } from '../../chart_types/goal_chart/specs';
+import { GoalSubtype } from '../../chart_types/goal_chart/specs/constants';
 import { config } from '../../chart_types/partition_chart/layout/config';
 import { PartitionLayout } from '../../chart_types/partition_chart/layout/types/config_types';
 import { arrayToLookup } from '../../common/color_calcs';
@@ -132,4 +134,100 @@ describe('Accessibility', () => {
       expect(sunburstLayerWrapper.find('tr').first().text()).toBe('DepthLabelParentValuePercentage');
     });
   });
+
+  describe('Goal chart type accessibility', () => {
+    const goalChartWrapper = mount(
+      <Chart className="story-chart">
+        <Goal
+          id="spec_1"
+          subtype={GoalSubtype.Goal}
+          base={0}
+          target={260}
+          actual={170}
+          bands={[200, 250, 300]}
+          ticks={[0, 50, 100, 150, 200, 250, 300]}
+          labelMajor="Revenue 2020 YTD  "
+          labelMinor="(thousand USD)  "
+          centralMajor="170"
+          centralMinor=""
+          config={{ angleStart: Math.PI, angleEnd: 0 }}
+        />
+      </Chart>,
+    );
+
+    const bandsWithSemanticsAscending = [
+      [200, 'freezing'],
+      [250, 'chilly'],
+      [300, 'brisk'],
+    ];
+
+    const ascendingSemanticValuesGoalChart = mount(
+      <Chart className="story-chart">
+        <Goal
+          id="spec_1"
+          subtype={GoalSubtype.Goal}
+          base={0}
+          target={260}
+          actual={170}
+          // doesn't mess with canvas_renderers.ts
+          // @ts-ignore
+          bands={bandsWithSemanticsAscending.flat().filter((val) => typeof val === 'number')}
+          ticks={[0, 50, 100, 150, 200, 250, 300]}
+          // tickValueFormatter={({ value }: BandFillColorAccessorInput) => String(value)}
+          // bandFillColor={({ value }: BandFillColorAccessorInput) => semanticBandFillColor(value)}
+          labelMajor="Revenue 2020 YTD  "
+          labelMinor="(thousand USD)  "
+          centralMajor="170"
+          centralMinor=""
+          config={{ angleStart: Math.PI, angleEnd: 0 }}
+          semanticValues={bandsWithSemanticsAscending}
+        />
+      </Chart>,
+    );
+
+    const bandsWithSemanticsDescending = [
+      [300, 'brisk'],
+      [250, 'chilly'],
+      [200, 'freezing'],
+    ];
+
+    const descendingSemanticValuesGoalChart = mount(
+      <Chart className="story-chart">
+        <Goal
+          id="spec_1"
+          subtype={GoalSubtype.Goal}
+          base={300}
+          target={260}
+          actual={170}
+          // doesn't mess with canvas_renderers.ts
+          // @ts-ignore
+          bands={bandsWithSemanticsDescending.flat().filter((val) => typeof val === 'number')}
+          ticks={[300, 250, 200, 150, 100, 50, 0]}
+          // tickValueFormatter={({ value }: BandFillColorAccessorInput) => String(value)}
+          // bandFillColor={({ value }: BandFillColorAccessorInput) => semanticBandFillColor(value)}
+          labelMajor="Revenue 2020 YTD  "
+          labelMinor="(thousand USD)  "
+          centralMajor="170"
+          centralMinor=""
+          config={{ angleStart: Math.PI, angleEnd: 0 }}
+          semanticValues={bandsWithSemanticsDescending}
+        />
+      </Chart>,
+    );
+    it('should test defaults for goal charts', () => {
+      expect(goalChartWrapper.find('.echScreenReaderOnly').first().text()).toBe(
+        'Goal chart label: Revenue 2020 YTD   (thousand USD)  Chart type:goal chartMinimum: 0Maximum: 300Target: 260Value: 170',
+      );
+    });
+    it('should correctly render ascending semantic values', () => {
+      expect(ascendingSemanticValuesGoalChart.find('.echGoalDescription').first().text()).toBe(
+        'values 200 - 250: freezingvalues 250 - 300: chillyvalues above 300: brisk',
+      );
+    });
+    it('should correctly render descending semantic values', () => {
+      expect(descendingSemanticValuesGoalChart.find('.echGoalDescription').first().text()).toBe(
+        'values 300 - 250: briskvalues 250 - 200: chillyvalues below 200: freezing',
+      );
+    });
+  });
 });

packages/charts/src/components/accessibility/goal_semantic_description.tsx

@@ -0,0 +1,43 @@
+/*
+ * 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';
+
+interface GoalSemanticDescriptionProps {
+  semanticValues: Array<(string | number)[]>;
+}
+
+/** @internal */
+export const GoalSemanticDescription = ({ semanticValues }: GoalSemanticDescriptionProps) => {
+  return (
+    <div className="echScreenReaderOnly echGoalDescription">
+      {semanticValues.map(([value, semantic], index) => {
+        const nextValue = semanticValues[index + 1];
+        const prevValue = semanticValues[index - 1];
+        return nextValue !== undefined ? (
+          <dd key={index}>{`values ${value} - ${nextValue[0]}: ${semantic}`}</dd>
+        ) : prevValue[0] < value ? (
+          <dd key={index}>{`values above ${value}: ${semantic}`}</dd>
+        ) : (
+          <dd key={index}>{`values below ${value}: ${semantic}`}</dd>
+        );
+      })}
+    </div>
+  );
+};

packages/charts/src/components/accessibility/index.ts

@@ -19,3 +19,5 @@
 
 /* @internal */
 export { ScreenReaderSummary } from './screen_reader_summary';
+export { ScreenReaderPartitionTable } from './partitions_data_table';
+export { GoalSemanticDescription } from './goal_semantic_description';

packages/charts/src/components/accessibility/label.tsx

@@ -19,11 +19,30 @@
 
 import React from 'react';
 
+import { GoalChartLabels } from '../../chart_types/goal_chart/state/selectors/get_goal_chart_data';
 import { A11ySettings } from '../../state/selectors/get_accessibility_config';
 
+interface ScreenReaderLabelProps {
+  goalChartLabels?: GoalChartLabels;
+}
+
 /** @internal */
-export function ScreenReaderLabel(props: A11ySettings) {
-  if (!props.label) return null;
-  const Heading = props.labelHeadingLevel;
-  return <Heading id={props.labelId}>{props.label}</Heading>;
+export function ScreenReaderLabel({
+  label,
+  labelHeadingLevel,
+  labelId,
+  goalChartLabels,
+}: A11ySettings & ScreenReaderLabelProps) {
+  if (!label && !goalChartLabels?.majorLabel) return null;
+  const Heading = labelHeadingLevel;
+  const goalChartLabelsSection = !goalChartLabels?.majorLabel
+    ? null
+    : `Goal chart label: ${goalChartLabels.majorLabel} ${goalChartLabels.minorLabel}`;
+
+  return (
+    <Heading id={labelId}>
+      {label}
+      {goalChartLabelsSection}
+    </Heading>
+  );
 }