ensure all accessible labels are supported via our i18n

Author: pan-kot

src/__tests__/__snapshots__/documenter.test.ts.snap

@@ -128,6 +128,11 @@ Supported Highcharts versions:
       "inlineType": {
         "name": "BaseI18nStrings",
         "properties": [
+          {
+            "name": "chartAccessibleDescription",
+            "optional": true,
+            "type": "string",
+          },
           {
             "name": "detailPopoverDismissAriaLabel",
             "optional": true,
@@ -163,6 +168,21 @@ Supported Highcharts versions:
             "optional": true,
             "type": "string",
           },
+          {
+            "name": "seriesFilterSelectedAriaLabel",
+            "optional": true,
+            "type": "string",
+          },
+          {
+            "name": "xAxisAccessibleDescription",
+            "optional": true,
+            "type": "string",
+          },
+          {
+            "name": "yAxisAccessibleDescription",
+            "optional": true,
+            "type": "string",
+          },
         ],
         "type": "object",
       },
@@ -619,6 +639,11 @@ Supported Highcharts versions:
       "inlineType": {
         "name": "BaseI18nStrings",
         "properties": [
+          {
+            "name": "chartAccessibleDescription",
+            "optional": true,
+            "type": "string",
+          },
           {
             "name": "detailPopoverDismissAriaLabel",
             "optional": true,
@@ -654,6 +679,21 @@ Supported Highcharts versions:
             "optional": true,
             "type": "string",
           },
+          {
+            "name": "seriesFilterSelectedAriaLabel",
+            "optional": true,
+            "type": "string",
+          },
+          {
+            "name": "xAxisAccessibleDescription",
+            "optional": true,
+            "type": "string",
+          },
+          {
+            "name": "yAxisAccessibleDescription",
+            "optional": true,
+            "type": "string",
+          },
         ],
         "type": "object",
       },

src/core/chart-core.tsx

@@ -8,6 +8,7 @@ import HighchartsReact from "highcharts-react-official";
 
 import { getIsRtl, useMergeRefs, useUniqueId } from "@cloudscape-design/component-toolkit/internal";
 import { isDevelopment } from "@cloudscape-design/component-toolkit/internal";
+import { useInternalI18n } from "@cloudscape-design/components/internal/do-not-use/i18n";
 import Spinner from "@cloudscape-design/components/spinner";
 
 import { getDataAttributes } from "../internal/base-component/get-data-attributes";
@@ -64,6 +65,7 @@ export function InternalCoreChart({
   ...rest
 }: CoreChartProps & InternalBaseComponentProps) {
   const highcharts = rest.highcharts as null | typeof Highcharts;
+  const i18n = useInternalI18n("[charts]");
 
   const settings = {
     chartId: useUniqueId(),
@@ -107,6 +109,15 @@ export function InternalCoreChart({
     );
   }
 
+  const aria = {
+    chartLabel: ariaLabel,
+    chartDescription: ariaDescription,
+    // We reuse existing translations as passing for now, but it is possible to introduce new i18n strings that
+    // are parametrized with axes names, and more.
+    chartContainerLabel: i18n("i18nStrings.chartAriaRoleDescription", i18nStrings?.chartAccessibleDescription),
+    chartXAxisLabel: i18n("i18nStrings.xAxisAriaRoleDescription", i18nStrings?.xAxisAccessibleDescription),
+    chartYAxisLabel: i18n("i18nStrings.yAxisAriaRoleDescription", i18nStrings?.yAxisAccessibleDescription),
+  };
   const apiOptions = api.getOptions();
   const inverted = !!options.chart?.inverted;
   const isRtl = () => getIsRtl(rootRef?.current);
@@ -168,11 +179,28 @@ export function InternalCoreChart({
             legend: options.legend ?? { enabled: false },
             lang: {
               ...options.lang,
-              // The default chart title is disabled by default to prevent the default "Chart" in the screen-reader detail.
-              accessibility: { defaultChartTitle: "", chartContainerLabel: ariaLabel, ...options.lang?.accessibility },
+              accessibility: {
+                // The default chart title is disabled by default to prevent the default "Chart" in the screen-reader detail.
+                defaultChartTitle: "",
+                chartContainerLabel: aria.chartLabel,
+                svgContainerLabel: aria.chartContainerLabel,
+                // We used {names[0]} to inject the axis title, see: https://api.highcharts.com/highcharts/lang.accessibility.axis.xAxisDescriptionSingular.
+                axis: {
+                  xAxisDescriptionSingular: aria.chartXAxisLabel ? `${aria.chartXAxisLabel}, {names[0]}` : undefined,
+                  yAxisDescriptionSingular: aria.chartYAxisLabel ? `${aria.chartYAxisLabel}, {names[0]}` : undefined,
+                },
+                ...options.lang?.accessibility,
+              },
             },
             accessibility: {
-              description: ariaDescription,
+              description: aria.chartDescription,
+              screenReaderSection: {
+                // We use custom before-message to remove detail that are currently not supported with our i18n.
+                // See: https://api.highcharts.com/highcharts/accessibility.screenReaderSection.beforeChartFormat.
+                beforeChartFormat: "<div>{xAxisDescription}</div><div>{yAxisDescription}</div>",
+                // We hide after message as it is currently not supported with our i18n.
+                afterChartFormat: "",
+              },
               ...options.accessibility,
               // Highcharts keyboard navigation is disabled by default in favour of the custom Cloudscape navigation.
               keyboardNavigation: options.accessibility?.keyboardNavigation ?? { enabled: !keyboardNavigation },

src/core/interfaces.ts

@@ -101,14 +101,28 @@ export interface BaseNoDataOptions {
 }
 
 export interface BaseI18nStrings {
+  /** Text that is displayed when the chart is loading, i.e. when `noData.statusType` is set to `"loading". */
   loadingText?: string;
+  /** Text that is displayed when the chart is in error state, i.e. when `noData.statusType` is set to `"error". */
   errorText?: string;
+  /** Text for the recovery button that is displayed next to the error text. */
   recoveryText?: string;
+  /** Visible label of the default series filter */
   seriesFilterLabel?: string;
+  /** Placeholder text of the default series filter */
   seriesFilterPlaceholder?: string;
+  /** ARIA label of the default series filter which is appended to any option that is selected */
   seriesFilterSelectedAriaLabel?: string;
+  /** ARIA label that is associated with the legend in case there is no visible `legendTitle` defined */
   legendAriaLabel?: string;
+  /** ARIA label for details popover dismiss button */
   detailPopoverDismissAriaLabel?: string;
+  /** Generalized accessible description of the chart, e.g. "line chart" */
+  chartAccessibleDescription?: string;
+  /** Generalized accessible description of the x axis, e.g. "x axis" */
+  xAxisAccessibleDescription?: string;
+  /** Generalized accessible description of the y axis, e.g. "y axis" */
+  yAxisAccessibleDescription?: string;
 }
 
 export interface BaseFilterOptions {