@octanejs/visx 0.1.0

package/src/a11y/index.ts

@@ -0,0 +1,35 @@
+// @octanejs/visx/a11y
+export {
+	DEFAULT_CHART_A11Y_ID_PREFIX,
+	DEFAULT_POINT_DESCRIPTION_THRESHOLD,
+	DEFAULT_SINGLE_SERIES_LABEL,
+	normalizeChartA11yData,
+} from './utils/data';
+export { getChartAriaProps } from './generators/ariaProps';
+export { generateDataTableHTML } from './generators/dataTableHTML';
+export { generateChartDescription } from './generators/description';
+export type {
+	ChartA11yKeyboardIntent,
+	ChartA11yKeyboardState,
+	ChartA11yMode,
+	ChartA11yPointFocus,
+} from './keyboard/stateMachine';
+
+export type {
+	A11yLocale,
+	ChartA11yAccessor,
+	ChartA11yConfig,
+	ChartA11yFlatConfig,
+	ChartA11yFocusedPoint,
+	ChartA11yFormatter,
+	ChartA11yIds,
+	ChartA11yNestedConfig,
+	ChartA11yPointProps,
+	ChartA11yProps,
+	ChartA11ySeriesProps,
+	ChartA11ySeriesConfig,
+	ChartA11ySvgProps,
+	ChartA11yValue,
+	ChartType,
+} from './types';
+export type { NormalizedChartA11yData, NormalizedChartA11ySeries } from './utils/data';

package/src/a11y/keyboard/stateMachine.ts

@@ -0,0 +1,231 @@
+export type ChartA11yMode = 'chart' | 'data';
+
+export type ChartA11yPointFocus = {
+	seriesIndex: number;
+	index: number;
+};
+
+export type ChartA11yKeyboardState = {
+	mode: ChartA11yMode;
+	focusedPoint: ChartA11yPointFocus | null;
+	lastFocusedPoint: ChartA11yPointFocus | null;
+};
+
+export type ChartA11yKeyboardIntent =
+	| 'enter'
+	| 'exit'
+	| 'nextPoint'
+	| 'previousPoint'
+	| 'nextSeries'
+	| 'previousSeries'
+	| 'firstPoint'
+	| 'lastPoint'
+	| 'firstChartPoint'
+	| 'lastChartPoint';
+
+export const initialChartA11yKeyboardState: ChartA11yKeyboardState = {
+	mode: 'chart',
+	focusedPoint: null,
+	lastFocusedPoint: null,
+};
+
+function getSeriesLength(seriesLengths: readonly number[], seriesIndex: number) {
+	return seriesLengths[seriesIndex] ?? 0;
+}
+
+function getPointCount(seriesLengths: readonly number[]) {
+	return seriesLengths.reduce((total, length) => total + length, 0);
+}
+
+function getFirstPoint(seriesLengths: readonly number[]): ChartA11yPointFocus | null {
+	const seriesIndex = seriesLengths.findIndex((length) => length > 0);
+
+	return seriesIndex < 0 ? null : { seriesIndex, index: 0 };
+}
+
+function getLastPoint(seriesLengths: readonly number[]): ChartA11yPointFocus | null {
+	for (let seriesIndex = seriesLengths.length - 1; seriesIndex >= 0; seriesIndex -= 1) {
+		const length = getSeriesLength(seriesLengths, seriesIndex);
+
+		if (length > 0) {
+			return { seriesIndex, index: length - 1 };
+		}
+	}
+
+	return null;
+}
+
+function arePointsEqual(
+	firstPoint: ChartA11yPointFocus | null,
+	secondPoint: ChartA11yPointFocus | null,
+) {
+	return (
+		firstPoint?.seriesIndex === secondPoint?.seriesIndex && firstPoint?.index === secondPoint?.index
+	);
+}
+
+function clampPoint(
+	seriesLengths: readonly number[],
+	point: ChartA11yPointFocus | null,
+): ChartA11yPointFocus | null {
+	if (!point || getPointCount(seriesLengths) === 0) {
+		return getFirstPoint(seriesLengths);
+	}
+
+	const length = getSeriesLength(seriesLengths, point.seriesIndex);
+
+	if (length > 0) {
+		return {
+			seriesIndex: point.seriesIndex,
+			index: Math.min(Math.max(point.index, 0), length - 1),
+		};
+	}
+
+	return getFirstPoint(seriesLengths);
+}
+
+function setFocusedPoint(
+	state: ChartA11yKeyboardState,
+	focusedPoint: ChartA11yPointFocus | null,
+): ChartA11yKeyboardState {
+	if (arePointsEqual(state.focusedPoint, focusedPoint)) {
+		return state;
+	}
+
+	return {
+		mode: focusedPoint ? 'data' : state.mode,
+		focusedPoint,
+		lastFocusedPoint: focusedPoint ?? state.lastFocusedPoint,
+	};
+}
+
+function movePoint(
+	seriesLengths: readonly number[],
+	point: ChartA11yPointFocus | null,
+	direction: 1 | -1,
+): ChartA11yPointFocus | null {
+	const focusedPoint = clampPoint(seriesLengths, point);
+
+	if (!focusedPoint) {
+		return null;
+	}
+
+	const length = getSeriesLength(seriesLengths, focusedPoint.seriesIndex);
+
+	if (length <= 1) {
+		return focusedPoint;
+	}
+
+	return {
+		seriesIndex: focusedPoint.seriesIndex,
+		index: (focusedPoint.index + direction + length) % length,
+	};
+}
+
+function moveSeries(
+	seriesLengths: readonly number[],
+	point: ChartA11yPointFocus | null,
+	direction: 1 | -1,
+): ChartA11yPointFocus | null {
+	const focusedPoint = clampPoint(seriesLengths, point);
+	const seriesCount = seriesLengths.length;
+
+	if (!focusedPoint || seriesCount <= 1) {
+		return focusedPoint;
+	}
+
+	for (let offset = 1; offset < seriesCount; offset += 1) {
+		const seriesIndex = (focusedPoint.seriesIndex + direction * offset + seriesCount) % seriesCount;
+		const length = getSeriesLength(seriesLengths, seriesIndex);
+
+		if (length > 0) {
+			return {
+				seriesIndex,
+				index: Math.min(focusedPoint.index, length - 1),
+			};
+		}
+	}
+
+	return focusedPoint;
+}
+
+export function getChartA11ySeriesLengths(seriesData: readonly (readonly unknown[])[]) {
+	return seriesData.map((series) => series.length);
+}
+
+export function focusChartA11yPoint(
+	state: ChartA11yKeyboardState,
+	seriesLengths: readonly number[],
+	point: ChartA11yPointFocus | null,
+): ChartA11yKeyboardState {
+	return setFocusedPoint(state, clampPoint(seriesLengths, point));
+}
+
+export function transitionChartA11yKeyboardState(
+	state: ChartA11yKeyboardState,
+	seriesLengths: readonly number[],
+	intent: ChartA11yKeyboardIntent,
+): ChartA11yKeyboardState {
+	if (getPointCount(seriesLengths) === 0) {
+		return initialChartA11yKeyboardState;
+	}
+
+	if (intent === 'enter') {
+		return setFocusedPoint(state, clampPoint(seriesLengths, state.lastFocusedPoint));
+	}
+
+	if (intent === 'exit') {
+		return state.mode === 'chart'
+			? state
+			: {
+					mode: 'chart',
+					focusedPoint: null,
+					lastFocusedPoint: state.focusedPoint ?? state.lastFocusedPoint,
+				};
+	}
+
+	if (state.mode !== 'data') {
+		return state;
+	}
+
+	if (intent === 'nextPoint') {
+		return setFocusedPoint(state, movePoint(seriesLengths, state.focusedPoint, 1));
+	}
+
+	if (intent === 'previousPoint') {
+		return setFocusedPoint(state, movePoint(seriesLengths, state.focusedPoint, -1));
+	}
+
+	if (intent === 'nextSeries') {
+		return setFocusedPoint(state, moveSeries(seriesLengths, state.focusedPoint, 1));
+	}
+
+	if (intent === 'previousSeries') {
+		return setFocusedPoint(state, moveSeries(seriesLengths, state.focusedPoint, -1));
+	}
+
+	if (intent === 'firstPoint') {
+		const focusedPoint = clampPoint(seriesLengths, state.focusedPoint);
+
+		return setFocusedPoint(
+			state,
+			focusedPoint ? { seriesIndex: focusedPoint.seriesIndex, index: 0 } : null,
+		);
+	}
+
+	if (intent === 'lastPoint') {
+		const focusedPoint = clampPoint(seriesLengths, state.focusedPoint);
+		const length = focusedPoint ? getSeriesLength(seriesLengths, focusedPoint.seriesIndex) : 0;
+
+		return setFocusedPoint(
+			state,
+			focusedPoint ? { seriesIndex: focusedPoint.seriesIndex, index: length - 1 } : null,
+		);
+	}
+
+	if (intent === 'firstChartPoint') {
+		return setFocusedPoint(state, getFirstPoint(seriesLengths));
+	}
+
+	return setFocusedPoint(state, getLastPoint(seriesLengths));
+}

package/src/a11y/react/index.ts

@@ -0,0 +1,59 @@
+'use client';
+
+export {
+	DEFAULT_CHART_A11Y_ID_PREFIX,
+	DEFAULT_POINT_DESCRIPTION_THRESHOLD,
+	DEFAULT_SINGLE_SERIES_LABEL,
+	generateChartDescription,
+	generateDataTableHTML,
+	getChartAriaProps,
+	normalizeChartA11yData,
+} from '..';
+export { useChartA11y } from '../useChartA11y.tsrx';
+export { useChartKeyboardNav } from '../useChartKeyboardNav.tsrx';
+export { ChartA11yAnnouncer } from '../components/ChartA11yAnnouncer.tsrx';
+export { ChartA11yDataTable } from '../components/ChartA11yDataTable.tsrx';
+
+export type {
+	ChartA11yKeyboardIntent,
+	ChartA11yKeyboardState,
+	ChartA11yMode,
+	ChartA11yPointFocus,
+} from '../keyboard/stateMachine';
+export type {
+	UseChartA11yAnnouncerProps,
+	UseChartA11yDataTableProps,
+	UseChartA11yPointProps,
+	UseChartA11yResult,
+	UseChartA11ySvgProps,
+} from '../useChartA11y.tsrx';
+export type {
+	UseChartKeyboardNavConfig,
+	UseChartKeyboardNavPointProps,
+	UseChartKeyboardNavResult,
+	UseChartKeyboardNavSvgProps,
+} from '../useChartKeyboardNav.tsrx';
+export type {
+	ChartA11yAnnouncerProps,
+	ChartA11yLivePoliteness,
+} from '../components/ChartA11yAnnouncer.tsrx';
+export type { ChartA11yDataTableProps } from '../components/ChartA11yDataTable.tsrx';
+export type {
+	A11yLocale,
+	ChartA11yAccessor,
+	ChartA11yConfig,
+	ChartA11yFlatConfig,
+	ChartA11yFocusedPoint,
+	ChartA11yFormatter,
+	ChartA11yIds,
+	ChartA11yNestedConfig,
+	ChartA11yPointProps,
+	ChartA11yProps,
+	ChartA11ySeriesProps,
+	ChartA11ySeriesConfig,
+	ChartA11ySvgProps,
+	ChartA11yValue,
+	ChartType,
+	NormalizedChartA11yData,
+	NormalizedChartA11ySeries,
+} from '..';

package/src/a11y/server.ts

@@ -0,0 +1,29 @@
+// @octanejs/visx/a11y/server
+export {
+	DEFAULT_CHART_A11Y_ID_PREFIX,
+	DEFAULT_POINT_DESCRIPTION_THRESHOLD,
+	DEFAULT_SINGLE_SERIES_LABEL,
+	normalizeChartA11yData,
+} from './utils/data';
+export { getChartAriaProps } from './generators/ariaProps';
+export { generateDataTableHTML } from './generators/dataTableHTML';
+export { generateChartDescription } from './generators/description';
+
+export type {
+	A11yLocale,
+	ChartA11yAccessor,
+	ChartA11yConfig,
+	ChartA11yFlatConfig,
+	ChartA11yFocusedPoint,
+	ChartA11yFormatter,
+	ChartA11yIds,
+	ChartA11yNestedConfig,
+	ChartA11yPointProps,
+	ChartA11yProps,
+	ChartA11ySeriesProps,
+	ChartA11ySeriesConfig,
+	ChartA11ySvgProps,
+	ChartA11yValue,
+	ChartType,
+} from './types';
+export type { NormalizedChartA11yData, NormalizedChartA11ySeries } from './utils/data';

package/src/a11y/types.ts

@@ -0,0 +1,104 @@
+export type ChartType =
+	| 'line'
+	| 'bar'
+	| 'scatter'
+	| 'area'
+	| 'pie'
+	| 'donut'
+	| 'histogram'
+	| 'heatmap';
+
+export type ChartA11yValue = string | number | Date;
+
+export type ChartA11yAccessor<Datum, Value = ChartA11yValue> = (
+	datum: Datum,
+	index: number,
+	data: readonly Datum[],
+) => Value;
+
+export type ChartA11yFormatter<Value = unknown> = (value: Value) => string;
+
+export type ChartA11ySeriesConfig<Datum> = {
+	label: string | ((seriesIndex: number) => string);
+	data?: readonly Datum[];
+};
+
+export type ChartA11yFocusedPoint<Datum> = {
+	seriesIndex: number;
+	index: number;
+	datum: Datum;
+};
+
+export type ChartA11yIds = {
+	rootId: string;
+	descriptionId: string;
+	tableId: string;
+};
+
+export type ChartA11ySvgProps = {
+	role: 'graphics-document';
+	'aria-roledescription': string;
+	'aria-label': string;
+	'aria-describedby': string;
+};
+
+export type ChartA11ySeriesProps = {
+	role: 'graphics-object';
+	'aria-roledescription': string;
+	'aria-label': string;
+};
+
+export type ChartA11yPointProps = {
+	role: 'graphics-symbol';
+	'aria-roledescription': string;
+	'aria-label': string;
+};
+
+export type ChartA11yProps = {
+	ids: ChartA11yIds;
+	svg: ChartA11ySvgProps;
+	series: ChartA11ySeriesProps[];
+	points: ChartA11yPointProps[][];
+};
+
+export type A11yLocale = {
+	chartRoleDescription: string;
+	seriesRoleDescription: string;
+	pointRoleDescription: string;
+	chartTypes: Partial<Record<ChartType, string>>;
+	dataTableCaption: (title: string) => string;
+	keyboardHelp: string;
+};
+
+type ChartA11yBaseConfig<Datum> = {
+	/** Stable id for generated description, table, and live-region relationships. */
+	id?: string;
+	/** Prefix used when an id is generated by client or server helpers. */
+	idPrefix?: string;
+	title: string;
+	x: ChartA11yAccessor<Datum>;
+	y: ChartA11yAccessor<Datum, number>;
+	xLabel?: string;
+	yLabel?: string;
+	description?: string;
+	chartType?: ChartType;
+	formatX?: ChartA11yFormatter;
+	formatY?: ChartA11yFormatter<number>;
+	pointDescriptionThreshold?: number;
+	dataTableEnabled?: boolean;
+	keyboardNavEnabled?: boolean;
+	onPointFocus?: (point: ChartA11yFocusedPoint<Datum>) => void;
+	locale?: Partial<A11yLocale>;
+};
+
+export type ChartA11yFlatConfig<Datum> = ChartA11yBaseConfig<Datum> & {
+	data: readonly Datum[];
+	series?: readonly ChartA11ySeriesConfig<Datum>[];
+};
+
+export type ChartA11yNestedConfig<Datum> = ChartA11yBaseConfig<Datum> & {
+	data: readonly (readonly Datum[])[];
+	series: readonly [ChartA11ySeriesConfig<Datum>, ...ChartA11ySeriesConfig<Datum>[]];
+};
+
+export type ChartA11yConfig<Datum> = ChartA11yFlatConfig<Datum> | ChartA11yNestedConfig<Datum>;

package/src/a11y/useChartA11y.tsrx

@@ -0,0 +1,144 @@
+import type { ComponentType } from 'react';
+import { useCallback, useId, useMemo, useState } from 'octane';
+
+import { ChartA11yAnnouncer } from './components/ChartA11yAnnouncer.tsrx';
+import type { ChartA11yAnnouncerProps } from './components/ChartA11yAnnouncer.tsrx';
+import { ChartA11yDataTable } from './components/ChartA11yDataTable.tsrx';
+import type { ChartA11yDataTableProps } from './components/ChartA11yDataTable.tsrx';
+import { getChartAriaProps } from './generators/ariaProps';
+import { generateChartDescription } from './generators/description';
+import type { ChartA11yMode, ChartA11yPointFocus } from './keyboard/stateMachine';
+import type {
+  ChartA11yConfig,
+  ChartA11yIds,
+  ChartA11yPointProps,
+  ChartA11ySeriesProps,
+  ChartA11ySvgProps,
+} from './types';
+import { useChartKeyboardNav } from './useChartKeyboardNav.tsrx';
+import type {
+  UseChartKeyboardNavPointProps,
+  UseChartKeyboardNavSvgProps,
+} from './useChartKeyboardNav.tsrx';
+import { DEFAULT_CHART_A11Y_ID_PREFIX } from './utils/data';
+
+export type { ChartA11yMode } from './keyboard/stateMachine';
+
+export type UseChartA11ySvgProps = ChartA11ySvgProps & UseChartKeyboardNavSvgProps;
+
+export type UseChartA11yPointProps = Partial<ChartA11yPointProps> & UseChartKeyboardNavPointProps;
+
+export type UseChartA11yDataTableProps<Datum> = Pick<
+  ChartA11yDataTableProps<Datum>,
+  'className' | 'style' | 'visible'
+>;
+
+export type UseChartA11yAnnouncerProps = Omit<ChartA11yAnnouncerProps, 'message'>;
+
+export type UseChartA11yResult<Datum> = {
+  id: string;
+  ids: ChartA11yIds;
+  svgProps: UseChartA11ySvgProps;
+  getSeriesProps: (seriesIndex: number) => ChartA11ySeriesProps;
+  getPointProps: (seriesIndex: number, index: number) => UseChartA11yPointProps;
+  descriptionId: string;
+  description: string;
+  DataTable: ComponentType<UseChartA11yDataTableProps<Datum>>;
+  Announcer: ComponentType<UseChartA11yAnnouncerProps>;
+  announce: (message: string) => void;
+  mode: ChartA11yMode;
+  focusedPoint: ChartA11yPointFocus | null;
+};
+
+function formatReactId(id: string) {
+  return id.replace(/[^\w-]/g, '') || 'chart';
+}
+
+export function useChartA11y<Datum>(config: ChartA11yConfig<Datum>): UseChartA11yResult<Datum> {
+  const reactId = useId();
+  const [announcement, setAnnouncement] = useState('');
+  const id =
+    config.id ?? `${config.idPrefix ?? DEFAULT_CHART_A11Y_ID_PREFIX}-${formatReactId(reactId)}`;
+  const hookConfig = useMemo(() => ({ ...config, id }), [config, id]);
+  const ariaProps = useMemo(() => getChartAriaProps(hookConfig), [hookConfig]);
+  const description = useMemo(() => generateChartDescription(hookConfig), [hookConfig]);
+  const keyboard = useChartKeyboardNav({
+    data: hookConfig.data,
+    keyboardNavEnabled: hookConfig.keyboardNavEnabled,
+    locale: hookConfig.locale,
+    onKeyboardHelp: setAnnouncement,
+    onPointFocus: hookConfig.onPointFocus,
+    pointDescriptionThreshold: hookConfig.pointDescriptionThreshold,
+    series: hookConfig.series,
+  });
+  const {
+    focusedPoint,
+    getPointProps: getKeyboardPointProps,
+    mode,
+    svgProps: keyboardSvgProps,
+  } = keyboard;
+
+  const svgProps = useMemo<UseChartA11ySvgProps>(
+    () => ({
+      ...ariaProps.svg,
+      ...keyboardSvgProps,
+    }),
+    [ariaProps.svg, keyboardSvgProps],
+  );
+
+  const getSeriesProps = useCallback(
+    (seriesIndex: number) =>
+      ariaProps.series[seriesIndex] ?? {
+        role: 'graphics-object',
+        'aria-roledescription': hookConfig.locale?.seriesRoleDescription ?? 'series',
+        'aria-label': `Series ${seriesIndex + 1}`,
+      },
+    [ariaProps.series, hookConfig.locale],
+  );
+
+  const getPointProps = useCallback(
+    (seriesIndex: number, index: number): UseChartA11yPointProps => {
+      const pointProps = ariaProps.points[seriesIndex]?.[index];
+
+      return {
+        ...pointProps,
+        ...getKeyboardPointProps(seriesIndex, index),
+      };
+    },
+    [ariaProps.points, getKeyboardPointProps],
+  );
+
+  const DataTable = useCallback(
+    ({ visible, className, style }: UseChartA11yDataTableProps<Datum> = {}) => {
+      if (hookConfig.dataTableEnabled === false) {
+        return null;
+      }
+
+      return <ChartA11yDataTable {...hookConfig} className={className} style={style} visible={visible} />
+    },
+    [hookConfig],
+  );
+
+  const Announcer = useCallback(
+    (props: UseChartA11yAnnouncerProps = {}) => (
+      <ChartA11yAnnouncer {...props} message={announcement} />
+    ),
+    [announcement],
+  );
+  const announce = useCallback((message: string) => setAnnouncement(message), []);
+
+  return {
+    id: ariaProps.ids.rootId,
+    ids: ariaProps.ids,
+    svgProps,
+    getSeriesProps,
+    getPointProps,
+    descriptionId: ariaProps.ids.descriptionId,
+    description,
+    DataTable,
+    Announcer,
+    announce,
+    mode,
+    focusedPoint,
+  };
+}

package/src/a11y/useChartA11y.tsrx.d.ts

@@ -0,0 +1,27 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { ComponentType } from 'react';
+import type { ChartA11yAnnouncerProps } from './components/ChartA11yAnnouncer.tsrx';
+import type { ChartA11yDataTableProps } from './components/ChartA11yDataTable.tsrx';
+import type { ChartA11yMode, ChartA11yPointFocus } from './keyboard/stateMachine';
+import type { ChartA11yConfig, ChartA11yIds, ChartA11yPointProps, ChartA11ySeriesProps, ChartA11ySvgProps } from './types';
+import type { UseChartKeyboardNavPointProps, UseChartKeyboardNavSvgProps } from './useChartKeyboardNav.tsrx';
+export type { ChartA11yMode } from './keyboard/stateMachine';
+export type UseChartA11ySvgProps = ChartA11ySvgProps & UseChartKeyboardNavSvgProps;
+export type UseChartA11yPointProps = Partial<ChartA11yPointProps> & UseChartKeyboardNavPointProps;
+export type UseChartA11yDataTableProps<Datum> = Pick<ChartA11yDataTableProps<Datum>, 'className' | 'style' | 'visible'>;
+export type UseChartA11yAnnouncerProps = Omit<ChartA11yAnnouncerProps, 'message'>;
+export type UseChartA11yResult<Datum> = {
+    id: string;
+    ids: ChartA11yIds;
+    svgProps: UseChartA11ySvgProps;
+    getSeriesProps: (seriesIndex: number) => ChartA11ySeriesProps;
+    getPointProps: (seriesIndex: number, index: number) => UseChartA11yPointProps;
+    descriptionId: string;
+    description: string;
+    DataTable: ComponentType<UseChartA11yDataTableProps<Datum>>;
+    Announcer: ComponentType<UseChartA11yAnnouncerProps>;
+    announce: (message: string) => void;
+    mode: ChartA11yMode;
+    focusedPoint: ChartA11yPointFocus | null;
+};
+export declare function useChartA11y<Datum>(config: ChartA11yConfig<Datum>): UseChartA11yResult<Datum>;