@astryxdesign/lab 0.2.0-canary.f306f13 → 0.2.0-canary.fc53ff7

package/src/Radial/RadialChart.tsx

@@ -7,6 +7,10 @@
  *
  * Owns the radial coordinate space: center, radius, angle/radius scales.
  * Same Tier 1 guarantee as Chart — all children map through the same context.
+ *
+ * Accessibility: the svg is exposed as a named image (role="img" + aria-label,
+ * overridable via `label`), and small datasets are mirrored in a visually
+ * hidden data table (slices in pie mode, axis values in spider mode).
  */
 
 import {
@@ -16,6 +20,7 @@ import {
   useState,
   useLayoutEffect,
 } from 'react';
+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
 import {RadialProvider} from './RadialContext';
 import type {RadialMode} from './types';
 
@@ -52,9 +57,32 @@ export interface RadialChartProps {
    * Enable touch interaction mode — blocks scroll on mobile.
    */
   interactive?: boolean;
+  /**
+   * Accessible name for the chart, announced by screen readers (the svg is
+   * exposed as `role="img"`). Defaults to an English description derived from
+   * the mode and keys (e.g. "Radar chart of speed, handling" or
+   * "Pie chart of revenue") — pass a localized string to override.
+   */
+  label?: string;
   children: ReactNode;
 }
 
+/**
+ * Maximum number of data points (rows × axes in spider mode, slices in pie
+ * mode) for which the visually hidden data-table fallback is rendered. Beyond
+ * this a table is more noise than signal, so larger charts are name-only.
+ */
+const MAX_TABLE_POINTS = 100;
+
+/**
+ * Row header for a spider-mode table row: the first string field in the row
+ * (the same heuristic RadialArea uses to match its `dataKey`), else the index.
+ */
+function spiderRowHeader(row: Record<string, unknown>, index: number): string {
+  const name = Object.values(row).find(v => typeof v === 'string');
+  return typeof name === 'string' ? name : `Series ${index + 1}`;
+}
+
 /**
  * Root radial chart container. Computes angular/radial scales and provides
  * them to children via context.
@@ -82,6 +110,7 @@ export function RadialChart({
   labelKey,
   innerRadius: innerRadiusFraction = 0,
   padAngle = 0.02,
+  label,
   children,
 }: RadialChartProps) {
   const containerRef = useRef<HTMLDivElement>(null);
@@ -202,13 +231,85 @@ export function RadialChart({
     [cx, cy, outerRadius, innerRadiusPx, data, mode, spiderCtx, pieCtx],
   );
 
+  const accessibleLabel =
+    label ??
+    (mode === 'spider'
+      ? `Radar chart of ${(axes ?? []).join(', ')}`
+      : `Pie chart of ${valueKey ?? 'values'}`);
+
+  const slices = pieCtx.slices ?? [];
+  const showPieTable =
+    mode === 'pie' && slices.length > 0 && slices.length <= MAX_TABLE_POINTS;
+  const showSpiderTable =
+    mode === 'spider' &&
+    axes != null &&
+    axes.length > 0 &&
+    data.length > 0 &&
+    data.length * axes.length <= MAX_TABLE_POINTS;
+
   return (
     <div ref={containerRef} style={{width: '100%'}}>
       {containerWidth > 0 && (
-        <svg width={containerWidth} height={height}>
+        <svg
+          role="img"
+          aria-label={accessibleLabel}
+          width={containerWidth}
+          height={height}>
           <RadialProvider value={ctx}>{children}</RadialProvider>
         </svg>
       )}
+      {showPieTable && (
+        <VisuallyHidden as="div">
+          <table>
+            <caption>{`${accessibleLabel} data`}</caption>
+            <thead>
+              <tr>
+                <th scope="col">{labelKey ?? 'Label'}</th>
+                <th scope="col">{valueKey}</th>
+                <th scope="col">Percentage</th>
+              </tr>
+            </thead>
+            <tbody>
+              {slices.map((slice, i) => (
+                <tr key={i}>
+                  <th scope="row">{slice.key}</th>
+                  <td>{String(slice.value)}</td>
+                  <td>{`${(slice.percentage * 100).toFixed(1)}%`}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </VisuallyHidden>
+      )}
+      {showSpiderTable && (
+        <VisuallyHidden as="div">
+          <table>
+            <caption>{`${accessibleLabel} data`}</caption>
+            <thead>
+              <tr>
+                <th scope="col">Series</th>
+                {axes.map(key => (
+                  <th key={key} scope="col">
+                    {key}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {data.map((row, i) => (
+                <tr key={i}>
+                  <th scope="row">{spiderRowHeader(row, i)}</th>
+                  {axes.map(key => (
+                    <td key={key}>
+                      {row[key] == null ? '' : String(row[key])}
+                    </td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </VisuallyHidden>
+      )}
     </div>
   );
 }

package/src/Sankey/SankeyChart.test.tsx

@@ -75,3 +75,98 @@ describe('SankeyChart scroll container', () => {
     ).not.toBeInTheDocument();
   });
 });
+
+describe('SankeyChart accessible name', () => {
+  it('names the svg when the chart does not scroll', () => {
+    render(
+      <SankeyChart nodes={nodes} links={links} minColumnWidth={50}>
+        <SankeyNode />
+      </SankeyChart>,
+    );
+    reportWidth(1000);
+
+    expect(screen.getByRole('img', {name: 'Sankey chart'})).toBeInTheDocument();
+  });
+
+  it('names the svg when the chart scrolls', () => {
+    render(
+      <SankeyChart nodes={nodes} links={links} minColumnWidth={400}>
+        <SankeyNode />
+      </SankeyChart>,
+    );
+    reportWidth(300);
+
+    expect(screen.getByRole('img', {name: 'Sankey chart'})).toBeInTheDocument();
+  });
+
+  it('applies a custom label to both the svg and the scroll region', () => {
+    render(
+      <SankeyChart
+        nodes={nodes}
+        links={links}
+        minColumnWidth={400}
+        label="Traffic flow">
+        <SankeyNode />
+      </SankeyChart>,
+    );
+    reportWidth(300);
+
+    expect(screen.getByRole('img', {name: 'Traffic flow'})).toBeInTheDocument();
+    expect(
+      screen.getByRole('group', {name: 'Traffic flow'}),
+    ).toBeInTheDocument();
+  });
+});
+
+describe('SankeyChart data table fallback', () => {
+  it('renders a visually hidden table of flows', () => {
+    render(
+      <SankeyChart nodes={nodes} links={links} minColumnWidth={50}>
+        <SankeyNode />
+      </SankeyChart>,
+    );
+    reportWidth(1000);
+
+    const table = screen.getByRole('table');
+    expect(table).toBeInTheDocument();
+
+    expect(
+      screen.getByRole('columnheader', {name: 'From'}),
+    ).toBeInTheDocument();
+    expect(screen.getByRole('columnheader', {name: 'To'})).toBeInTheDocument();
+    expect(
+      screen.getByRole('columnheader', {name: 'Value'}),
+    ).toBeInTheDocument();
+
+    // Link a → b (value 5), labels resolved from node definitions.
+    expect(screen.getByRole('rowheader', {name: 'A'})).toBeInTheDocument();
+    expect(screen.getByRole('rowheader', {name: 'B'})).toBeInTheDocument();
+    expect(screen.getAllByRole('cell', {name: '5'})).toHaveLength(2);
+
+    // Visually hidden, but still in the a11y tree.
+    const wrapper = table.parentElement as HTMLElement;
+    expect(wrapper.getAttribute('class')).toBeTruthy();
+    expect(wrapper).not.toHaveAttribute('hidden');
+  });
+
+  it('skips the table when there are too many links', () => {
+    const manyNodes = Array.from({length: 102}, (_, i) => ({
+      id: `n${i}`,
+      label: `N${i}`,
+      value: 1,
+    }));
+    const manyLinks = Array.from({length: 101}, (_, i) => ({
+      source: `n${i}`,
+      target: `n${i + 1}`,
+      value: 1,
+    }));
+    render(
+      <SankeyChart nodes={manyNodes} links={manyLinks} minColumnWidth={5}>
+        <SankeyNode />
+      </SankeyChart>,
+    );
+    reportWidth(1000);
+
+    expect(screen.queryByRole('table')).not.toBeInTheDocument();
+  });
+});

package/src/Sankey/SankeyChart.tsx

@@ -7,6 +7,10 @@
  *
  * When columns × minColumnWidth exceeds the container, the chart
  * scrolls horizontally rather than squishing columns together.
+ *
+ * Accessibility: the svg is exposed as a named image (role="img" + aria-label,
+ * overridable via `label`) in both the scrolling and non-scrolling paths, and
+ * small graphs are mirrored in a visually hidden From/To/Value table.
  */
 
 import {
@@ -16,6 +20,7 @@ import {
   useState,
   useLayoutEffect,
 } from 'react';
+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
 import {SankeyProvider} from './SankeyContext';
 import {computeLayout} from './layout';
 import type {SankeyNodeDatum, SankeyLinkDatum, SankeyColumn} from './types';
@@ -51,10 +56,25 @@ export interface SankeyChartProps {
    * When total min width exceeds the container, horizontal scrolling activates.
    */
   minColumnWidth?: number;
+  /**
+   * Accessible name for the chart, announced by screen readers. Applied to the
+   * svg (`role="img"`) and, when the chart scrolls, to the focusable scroll
+   * region. Pass a localized string to override the English default.
+   *
+   * @default 'Sankey chart'
+   */
+  label?: string;
   /** Chart contents */
   children: ReactNode;
 }
 
+/**
+ * Maximum number of links for which the visually hidden data-table fallback is
+ * rendered. Beyond this a table is more noise than signal, so larger charts
+ * are name-only.
+ */
+const MAX_TABLE_LINKS = 100;
+
 /** Resolve column count from raw column input or auto-detect from graph */
 function resolveColumnCount(
   columns: SankeyColumn[] | undefined,
@@ -131,6 +151,7 @@ export function SankeyChart({
   nodeGap = 14,
   nodeColor,
   minColumnWidth = 160,
+  label = 'Sankey chart',
   children,
 }: SankeyChartProps) {
   const containerRef = useRef<HTMLDivElement>(null);
@@ -197,17 +218,25 @@ export function SankeyChart({
     };
   }, [layout, chartWidth, height, nodeWidth, nodeColor]);
 
+  const nodeLabelById = useMemo(
+    () => new Map(nodes.map(n => [n.id, n.label || n.id])),
+    [nodes],
+  );
+  const showDataTable = links.length > 0 && links.length <= MAX_TABLE_LINKS;
+
   return (
     <div ref={containerRef} style={{width: '100%'}}>
       {ctx && (
         <div
           role={needsScroll ? 'group' : undefined}
-          aria-label={needsScroll ? 'Sankey chart' : undefined}
+          aria-label={needsScroll ? label : undefined}
           tabIndex={needsScroll ? 0 : undefined}
           style={
             needsScroll ? {overflowX: 'auto', overflowY: 'hidden'} : undefined
           }>
           <svg
+            role="img"
+            aria-label={label}
             width={chartWidth}
             height={height}
             style={{overflow: 'visible', display: 'block'}}>
@@ -215,6 +244,31 @@ export function SankeyChart({
           </svg>
         </div>
       )}
+      {showDataTable && (
+        <VisuallyHidden as="div">
+          <table>
+            <caption>{`${label} data`}</caption>
+            <thead>
+              <tr>
+                <th scope="col">From</th>
+                <th scope="col">To</th>
+                <th scope="col">Value</th>
+              </tr>
+            </thead>
+            <tbody>
+              {links.map((link, i) => (
+                <tr key={i}>
+                  <th scope="row">
+                    {nodeLabelById.get(link.source) ?? link.source}
+                  </th>
+                  <td>{nodeLabelById.get(link.target) ?? link.target}</td>
+                  <td>{String(link.value)}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </VisuallyHidden>
+      )}
     </div>
   );
 }

package/src/ThreeD/ThreeDChart.test.tsx

@@ -0,0 +1,251 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {render, screen, act, fireEvent} from '@testing-library/react';
+import {ThreeDChart} from './ThreeDChart';
+import {use3D} from './ThreeDContext';
+
+const data = [
+  {x: 0, y: 0, z: 0},
+  {x: 10, y: 20, z: 30},
+];
+
+/** Renders the current camera angles so tests can observe rotation. */
+function CameraProbe() {
+  const {camera} = use3D();
+  return (
+    <>
+      <text data-testid="azimuth">{camera.azimuth}</text>
+      <text data-testid="elevation">{camera.elevation}</text>
+    </>
+  );
+}
+
+function azimuth(): number {
+  return Number(screen.getByTestId('azimuth').textContent);
+}
+
+function elevation(): number {
+  return Number(screen.getByTestId('elevation').textContent);
+}
+
+// Capture the ResizeObserver callback so tests can drive the reported width.
+let resizeCallback: ResizeObserverCallback | undefined;
+
+// Manual rAF queue: callbacks are collected and only run when the test
+// flushes them, so we can observe whether the rotation loop is scheduled.
+let rafCallbacks: Map<number, FrameRequestCallback>;
+let nextRafId: number;
+let cancelSpy: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  resizeCallback = undefined;
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      constructor(cb: ResizeObserverCallback) {
+        resizeCallback = cb;
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+
+  rafCallbacks = new Map();
+  nextRafId = 0;
+  cancelSpy = vi.fn((id: number) => {
+    rafCallbacks.delete(id);
+  });
+  vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+    nextRafId += 1;
+    rafCallbacks.set(nextRafId, cb);
+    return nextRafId;
+  });
+  vi.stubGlobal('cancelAnimationFrame', cancelSpy);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function reportWidth(width: number) {
+  act(() => {
+    resizeCallback?.(
+      [{contentRect: {width}} as unknown as ResizeObserverEntry],
+      {} as ResizeObserver,
+    );
+  });
+}
+
+function flushFrame(now: number) {
+  const callbacks = [...rafCallbacks.values()];
+  rafCallbacks.clear();
+  act(() => {
+    callbacks.forEach(cb => cb(now));
+  });
+}
+
+/** matchMedia stub where prefers-reduced-motion: reduce matches. */
+function stubReducedMotion() {
+  vi.stubGlobal('matchMedia', (query: string): MediaQueryList => {
+    return {
+      matches: query === '(prefers-reduced-motion: reduce)',
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    } as unknown as MediaQueryList;
+  });
+}
+
+function renderChart(props: Partial<Parameters<typeof ThreeDChart>[0]> = {}) {
+  const result = render(
+    <ThreeDChart data={data} xKey="x" yKey="y" zKey="z" {...props}>
+      <CameraProbe />
+    </ThreeDChart>,
+  );
+  reportWidth(600);
+  return result;
+}
+
+describe('ThreeDChart accessible name', () => {
+  it('exposes role="img" with a default label derived from the data keys', () => {
+    renderChart();
+    expect(
+      screen.getByRole('img', {name: '3D chart of y by x and z'}),
+    ).toBeInTheDocument();
+  });
+
+  it('uses the label prop when provided', () => {
+    renderChart({label: 'Revenue by region and quarter'});
+    expect(
+      screen.getByRole('img', {name: 'Revenue by region and quarter'}),
+    ).toBeInTheDocument();
+  });
+
+  it('is not a tab stop when static (no interaction, no rotation)', () => {
+    renderChart();
+    expect(screen.getByRole('img')).not.toHaveAttribute('tabindex');
+  });
+});
+
+describe('ThreeDChart auto-rotation', () => {
+  it('rotates the camera when autoRotate is set', () => {
+    renderChart({autoRotate: 1});
+    expect(rafCallbacks.size).toBe(1);
+    flushFrame(100);
+    expect(azimuth()).toBeGreaterThan(35);
+  });
+
+  it('does not start the rotation loop under prefers-reduced-motion', () => {
+    stubReducedMotion();
+    renderChart({autoRotate: 1});
+    expect(rafCallbacks.size).toBe(0);
+    expect(azimuth()).toBe(35);
+  });
+
+  it('pauses rotation while hovered and resumes on leave', () => {
+    renderChart({autoRotate: 1});
+    expect(rafCallbacks.size).toBe(1);
+
+    fireEvent.mouseOver(screen.getByRole('img'));
+    expect(cancelSpy).toHaveBeenCalled();
+    expect(rafCallbacks.size).toBe(0);
+
+    const before = azimuth();
+    flushFrame(200);
+    expect(azimuth()).toBe(before);
+
+    fireEvent.mouseOut(screen.getByRole('img'));
+    expect(rafCallbacks.size).toBe(1);
+  });
+
+  it('pauses rotation while focused and resumes on blur', () => {
+    renderChart({autoRotate: 1});
+    expect(rafCallbacks.size).toBe(1);
+
+    fireEvent.focus(screen.getByRole('img'));
+    expect(cancelSpy).toHaveBeenCalled();
+    expect(rafCallbacks.size).toBe(0);
+
+    fireEvent.blur(screen.getByRole('img'));
+    expect(rafCallbacks.size).toBe(1);
+  });
+
+  it('is focusable when auto-rotating so keyboard users can pause it', () => {
+    renderChart({autoRotate: 1});
+    expect(screen.getByRole('img')).toHaveAttribute('tabindex', '0');
+  });
+});
+
+describe('ThreeDChart keyboard camera', () => {
+  it('is focusable when interactive', () => {
+    renderChart({interactive: true});
+    expect(screen.getByRole('img')).toHaveAttribute('tabindex', '0');
+  });
+
+  it('rotates yaw with ArrowLeft/ArrowRight', () => {
+    renderChart({interactive: true});
+    const svg = screen.getByRole('img');
+
+    fireEvent.keyDown(svg, {key: 'ArrowRight'});
+    expect(azimuth()).toBe(45);
+
+    fireEvent.keyDown(svg, {key: 'ArrowLeft'});
+    fireEvent.keyDown(svg, {key: 'ArrowLeft'});
+    expect(azimuth()).toBe(25);
+  });
+
+  it('rotates pitch with ArrowUp/ArrowDown', () => {
+    renderChart({interactive: true});
+    const svg = screen.getByRole('img');
+
+    fireEvent.keyDown(svg, {key: 'ArrowUp'});
+    expect(elevation()).toBe(35);
+
+    fireEvent.keyDown(svg, {key: 'ArrowDown'});
+    fireEvent.keyDown(svg, {key: 'ArrowDown'});
+    expect(elevation()).toBe(15);
+  });
+
+  it('clamps pitch to the same [-89, 89] range as pointer drag', () => {
+    renderChart({interactive: true, elevation: 85});
+    const svg = screen.getByRole('img');
+
+    fireEvent.keyDown(svg, {key: 'ArrowUp'});
+    expect(elevation()).toBe(89);
+    fireEvent.keyDown(svg, {key: 'ArrowUp'});
+    expect(elevation()).toBe(89);
+  });
+
+  it('clamps pitch at the lower bound', () => {
+    renderChart({interactive: true, elevation: -85});
+    const svg = screen.getByRole('img');
+
+    fireEvent.keyDown(svg, {key: 'ArrowDown'});
+    expect(elevation()).toBe(-89);
+  });
+
+  it('prevents default on arrow keys so the page does not scroll', () => {
+    renderChart({interactive: true});
+    const svg = screen.getByRole('img');
+
+    // fireEvent returns false when preventDefault() was called.
+    expect(fireEvent.keyDown(svg, {key: 'ArrowRight'})).toBe(false);
+    expect(fireEvent.keyDown(svg, {key: 'ArrowUp'})).toBe(false);
+    // Non-camera keys are left alone.
+    expect(fireEvent.keyDown(svg, {key: 'Enter'})).toBe(true);
+  });
+
+  it('ignores arrow keys when not interactive', () => {
+    renderChart({autoRotate: 1});
+    const svg = screen.getByRole('img');
+
+    expect(fireEvent.keyDown(svg, {key: 'ArrowRight'})).toBe(true);
+    expect(azimuth()).toBe(35);
+  });
+});