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

package/dist/Sankey/SankeyChart.js

@@ -7,12 +7,24 @@
  *
  * 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 { useMemo, useRef, useState, useLayoutEffect } from 'react';
+import { VisuallyHidden } from '@astryxdesign/core/VisuallyHidden';
 import { SankeyProvider } from "./SankeyContext.js";
 import { computeLayout } from "./layout.js";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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, nodes, links) {
   if (columns) {
@@ -85,6 +97,7 @@ export function SankeyChart({
   nodeGap = 14,
   nodeColor,
   minColumnWidth = 160,
+  label = 'Sankey chart',
   children
 }) {
   const containerRef = useRef(null);
@@ -133,20 +146,24 @@ export function SankeyChart({
       nodeColor
     };
   }, [layout, chartWidth, height, nodeWidth, nodeColor]);
-  return /*#__PURE__*/_jsx("div", {
+  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 /*#__PURE__*/_jsxs("div", {
     ref: containerRef,
     style: {
       width: '100%'
     },
-    children: ctx && /*#__PURE__*/_jsx("div", {
+    children: [ctx && /*#__PURE__*/_jsx("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,
       children: /*#__PURE__*/_jsx("svg", {
+        role: "img",
+        "aria-label": label,
         width: chartWidth,
         height: height,
         style: {
@@ -158,7 +175,38 @@ export function SankeyChart({
           children: children
         })
       })
-    })
+    }), showDataTable && /*#__PURE__*/_jsx(VisuallyHidden, {
+      as: "div",
+      children: /*#__PURE__*/_jsxs("table", {
+        children: [/*#__PURE__*/_jsx("caption", {
+          children: `${label} data`
+        }), /*#__PURE__*/_jsx("thead", {
+          children: /*#__PURE__*/_jsxs("tr", {
+            children: [/*#__PURE__*/_jsx("th", {
+              scope: "col",
+              children: "From"
+            }), /*#__PURE__*/_jsx("th", {
+              scope: "col",
+              children: "To"
+            }), /*#__PURE__*/_jsx("th", {
+              scope: "col",
+              children: "Value"
+            })]
+          })
+        }), /*#__PURE__*/_jsx("tbody", {
+          children: links.map((link, i) => /*#__PURE__*/_jsxs("tr", {
+            children: [/*#__PURE__*/_jsx("th", {
+              scope: "row",
+              children: nodeLabelById.get(link.source) ?? link.source
+            }), /*#__PURE__*/_jsx("td", {
+              children: nodeLabelById.get(link.target) ?? link.target
+            }), /*#__PURE__*/_jsx("td", {
+              children: String(link.value)
+            })]
+          }, i))
+        })]
+      })
+    })]
   });
 }
 SankeyChart.displayName = 'SankeyChart';

package/dist/ThreeD/ThreeDChart.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file ThreeDChart.tsx
- * @output Root 3D chart container — projected SVG with depth sorting
+ * @output Root 3D chart container — projected SVG with depth sorting,
+ *   accessible name, pointer + keyboard camera controls, and pausable
+ *   auto-rotation (respects prefers-reduced-motion)
  * @position Parent component; all 3D marks read from its context
  */
 import { type ReactNode } from 'react';
@@ -16,9 +18,20 @@ export interface ThreeDChartProps {
     azimuth?: number;
     elevation?: number;
     interactive?: boolean;
-    /** Auto-rotate speed in degrees per frame (default: 0 = off) */
+    /**
+     * Auto-rotate speed in degrees per frame (default: 0 = off).
+     *
+     * Rotation pauses while the chart is hovered or focused, and is disabled
+     * entirely when the user has `prefers-reduced-motion: reduce` set. Pass 0
+     * (or omit) to turn it off.
+     */
     autoRotate?: number;
+    /**
+     * Accessible label for the chart. Defaults to a description derived from
+     * the data keys, e.g. "3D chart of sales by month and region".
+     */
+    label?: string;
     children: ReactNode;
 }
-export declare function ThreeDChart({ data, xKey, yKey, zKey, xDomain: xDomainProp, yDomain: yDomainProp, zDomain: zDomainProp, height, azimuth: azimuthProp, elevation: elevationProp, interactive, autoRotate, children, }: ThreeDChartProps): import("react").JSX.Element;
+export declare function ThreeDChart({ data, xKey, yKey, zKey, xDomain: xDomainProp, yDomain: yDomainProp, zDomain: zDomainProp, height, azimuth: azimuthProp, elevation: elevationProp, interactive, autoRotate, label, children, }: ThreeDChartProps): import("react").JSX.Element;
 //# sourceMappingURL=ThreeDChart.d.ts.map

package/dist/ThreeD/ThreeDChart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ThreeDChart.d.ts","sourceRoot":"","sources":["../../src/ThreeD/ThreeDChart.tsx"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,EAEL,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAIf,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAsBD,wBAAgB,WAAW,CAAC,EAC1B,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,EACpB,MAAY,EACZ,OAAO,EAAE,WAAgB,EACzB,SAAS,EAAE,aAAkB,EAC7B,WAAmB,EACnB,UAAc,EACd,QAAQ,GACT,EAAE,gBAAgB,+BA6LlB"}
+{"version":3,"file":"ThreeDChart.d.ts","sourceRoot":"","sources":["../../src/ThreeD/ThreeDChart.tsx"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,EAGL,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAKf,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;CACrB;AAyBD,wBAAgB,WAAW,CAAC,EAC1B,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,WAAW,EACpB,MAAY,EACZ,OAAO,EAAE,WAAgB,EACzB,SAAS,EAAE,aAAkB,EAC7B,WAAmB,EACnB,UAAc,EACd,KAAK,EACL,QAAQ,GACT,EAAE,gBAAgB,+BAwPlB"}

package/dist/ThreeD/ThreeDChart.js

@@ -2,13 +2,18 @@
 
 /**
  * @file ThreeDChart.tsx
- * @output Root 3D chart container — projected SVG with depth sorting
+ * @output Root 3D chart container — projected SVG with depth sorting,
+ *   accessible name, pointer + keyboard camera controls, and pausable
+ *   auto-rotation (respects prefers-reduced-motion)
  * @position Parent component; all 3D marks read from its context
  */
 
 import { useMemo, useRef, useState, useEffect, useLayoutEffect, useCallback } from 'react';
+import { useMediaQuery } from '@astryxdesign/core/hooks';
 import { ThreeDProvider } from "./ThreeDContext.js";
 import { jsx as _jsx } from "react/jsx-runtime";
+/** Degrees the camera rotates per arrow-key press. */
+const KEYBOARD_STEP_DEGREES = 10;
 function computeDomain(data, key) {
   let min = Infinity,
     max = -Infinity;
@@ -38,10 +43,14 @@ export function ThreeDChart({
   elevation: elevationProp = 25,
   interactive = false,
   autoRotate = 0,
+  label,
   children
 }) {
   const containerRef = useRef(null);
   const [containerWidth, setContainerWidth] = useState(0);
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
   const [camera, setCamera] = useState({
     azimuth: azimuthProp,
     elevation: elevationProp
@@ -123,9 +132,44 @@ export function ThreeDChart({
     dragRef.current = null;
   }, []);
 
-  // Auto-rotation — throttled to ~20fps to avoid overwhelming React with re-renders
+  // Keyboard camera: arrow keys rotate yaw/pitch with the same clamps as
+  // pointer drag (WCAG 2.1.1 — every pointer operation needs a keyboard
+  // equivalent). preventDefault stops the page from scrolling while focused.
+  const handleKeyDown = useCallback(e => {
+    if (!interactive) {
+      return;
+    }
+    let deltaAzimuth = 0;
+    let deltaElevation = 0;
+    switch (e.key) {
+      case 'ArrowLeft':
+        deltaAzimuth = -KEYBOARD_STEP_DEGREES;
+        break;
+      case 'ArrowRight':
+        deltaAzimuth = KEYBOARD_STEP_DEGREES;
+        break;
+      case 'ArrowUp':
+        deltaElevation = KEYBOARD_STEP_DEGREES;
+        break;
+      case 'ArrowDown':
+        deltaElevation = -KEYBOARD_STEP_DEGREES;
+        break;
+      default:
+        return;
+    }
+    e.preventDefault();
+    setCamera(prev => ({
+      azimuth: prev.azimuth + deltaAzimuth,
+      elevation: Math.max(-89, Math.min(89, prev.elevation + deltaElevation))
+    }));
+  }, [interactive]);
+
+  // Auto-rotation — throttled to ~20fps to avoid overwhelming React with
+  // re-renders. Disabled under prefers-reduced-motion (WCAG 2.3.3) and
+  // paused while the chart is hovered or focused (WCAG 2.2.2).
+  const rotationActive = autoRotate !== 0 && !prefersReducedMotion && !hovered && !focused;
   useEffect(() => {
-    if (autoRotate === 0) {
+    if (!rotationActive) {
       return;
     }
     let raf;
@@ -145,7 +189,7 @@ export function ThreeDChart({
     };
     raf = requestAnimationFrame(tick);
     return () => cancelAnimationFrame(raf);
-  }, [autoRotate]);
+  }, [autoRotate, rotationActive]);
   const ctx = useMemo(() => ({
     width,
     height,
@@ -165,16 +209,30 @@ export function ThreeDChart({
     touchAction: interactive ? 'none' : undefined,
     userSelect: interactive ? 'none' : undefined
   };
+  const accessibleLabel = label ?? `3D chart of ${yKey} by ${xKey} and ${zKey}`;
+  // Focusable when there is something keyboard users can do with it:
+  // rotate the camera (interactive) or pause the auto-rotation.
+  const focusable = interactive || autoRotate !== 0;
   return /*#__PURE__*/_jsx("div", {
     ref: containerRef,
     style: containerStyle,
     children: containerWidth > 0 && /*#__PURE__*/_jsx("svg", {
+      role: "img",
+      "aria-label": accessibleLabel,
+      tabIndex: focusable ? 0 : undefined,
       width: containerWidth,
       height: height,
+      onKeyDown: handleKeyDown,
+      onFocus: () => setFocused(true),
+      onBlur: () => setFocused(false),
+      onMouseEnter: () => setHovered(true),
       onMouseDown: e => handleStart(e.clientX, e.clientY),
       onMouseMove: e => handleMove(e.clientX, e.clientY),
       onMouseUp: handleEnd,
-      onMouseLeave: handleEnd,
+      onMouseLeave: () => {
+        setHovered(false);
+        handleEnd();
+      },
       onTouchStart: e => {
         const t = e.touches[0];
         if (t) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/lab",
-  "version": "0.2.0-canary.f306f13",
+  "version": "0.2.0-canary.fc53ff7",
   "description": "Experimental Astryx components — published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
   "author": "Meta Open Source",
   "license": "MIT",
@@ -45,7 +45,7 @@
   },
   "peerDependencies": {
     "@stylexjs/stylex": ">=0.10.0",
-    "@astryxdesign/core": "0.2.0-canary.f306f13",
+    "@astryxdesign/core": "0.2.0-canary.fc53ff7",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "lexical": "^0.46.0",

package/src/Chart/Chart.test.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Chart.test.tsx
+ * @input Uses vitest, @testing-library/react, Chart component
+ * @output Unit tests for Chart accessibility (WCAG 1.1.1)
+ * @position Testing; validates Chart.tsx accessible name + data-table fallback
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {render, screen, act} from '@testing-library/react';
+import {Chart} from './Chart';
+
+const data = [
+  {month: 'Jan', revenue: 100, profit: 20},
+  {month: 'Feb', revenue: 200, profit: 40},
+  {month: 'Mar', revenue: 150, profit: 30},
+];
+
+// Capture the ResizeObserver callback so tests can drive the reported width.
+let resizeCallback: ResizeObserverCallback | undefined;
+
+beforeEach(() => {
+  resizeCallback = undefined;
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      constructor(cb: ResizeObserverCallback) {
+        resizeCallback = cb;
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function reportWidth(width: number) {
+  act(() => {
+    resizeCallback?.(
+      [{contentRect: {width}} as unknown as ResizeObserverEntry],
+      {} as ResizeObserver,
+    );
+  });
+}
+
+describe('Chart accessible name', () => {
+  it('exposes the svg as a named image with a default label', () => {
+    render(
+      <Chart data={data} xKey="month" yKeys={['revenue', 'profit']}>
+        <g />
+      </Chart>,
+    );
+    reportWidth(600);
+
+    expect(
+      screen.getByRole('img', {name: 'Chart of revenue, profit by month'}),
+    ).toBeInTheDocument();
+  });
+
+  it('uses a custom label when provided', () => {
+    render(
+      <Chart data={data} xKey="month" yKeys={['revenue']} label="Q1 revenue">
+        <g />
+      </Chart>,
+    );
+    reportWidth(600);
+
+    expect(screen.getByRole('img', {name: 'Q1 revenue'})).toBeInTheDocument();
+  });
+});
+
+describe('Chart data table fallback', () => {
+  it('renders a visually hidden table mirroring the data', () => {
+    render(
+      <Chart data={data} xKey="month" yKeys={['revenue', 'profit']}>
+        <g />
+      </Chart>,
+    );
+    reportWidth(600);
+
+    const table = screen.getByRole('table');
+    expect(table).toBeInTheDocument();
+
+    // Column headers: x key + each y key
+    expect(
+      screen.getByRole('columnheader', {name: 'month'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('columnheader', {name: 'revenue'}),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('columnheader', {name: 'profit'}),
+    ).toBeInTheDocument();
+
+    // Row headers and values
+    expect(screen.getByRole('rowheader', {name: 'Feb'})).toBeInTheDocument();
+    expect(screen.getByRole('cell', {name: '200'})).toBeInTheDocument();
+    expect(screen.getByRole('cell', {name: '40'})).toBeInTheDocument();
+
+    // Visually hidden, but still in the a11y tree (StyleX clip class attached,
+    // not display:none/hidden — jsdom does not apply the stylesheet itself).
+    const wrapper = table.parentElement as HTMLElement;
+    expect(wrapper.getAttribute('class')).toBeTruthy();
+    expect(wrapper).not.toHaveAttribute('hidden');
+  });
+
+  it('skips the table when the dataset exceeds the size cutoff', () => {
+    const big = Array.from({length: 101}, (_, i) => ({
+      month: `m${i}`,
+      revenue: i,
+    }));
+    render(
+      <Chart data={big} xKey="month" yKeys={['revenue']}>
+        <g />
+      </Chart>,
+    );
+    reportWidth(600);
+
+    expect(screen.queryByRole('table')).not.toBeInTheDocument();
+  });
+});

package/src/Chart/Chart.tsx

@@ -7,6 +7,10 @@
  *
  * Handles the d3 margin convention: outer SVG at full size, inner <g> translated
  * by margins. Children receive scales and dimensions via 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 so screen reader users can read the underlying values.
  */
 
 import {
@@ -20,6 +24,7 @@ import {
 } from 'react';
 import {scaleLinear, scaleBand} from 'd3-scale';
 import type {ScaleLinear} from 'd3-scale';
+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
 import {isBandScale} from './utils';
 import {ChartProvider} from './ChartContext';
 import type {ChartMargin, ChartScale} from './types';
@@ -75,12 +80,31 @@ export interface ChartProps {
    * interference 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 keys (e.g. "Chart of revenue by month") — pass a localized string to
+   * override.
+   */
+  label?: string;
   /** Chart contents — axes, marks, tooltips */
   children: ReactNode;
 }
 
 const DEFAULT_MARGIN: ChartMargin = {top: 16, right: 16, bottom: 32, left: 48};
 
+/**
+ * Maximum number of data points (rows × series) for which the visually hidden
+ * data-table fallback is rendered. Beyond this a table is more noise than
+ * signal for screen reader users, so larger charts are name-only.
+ */
+const MAX_TABLE_POINTS = 100;
+
+/** Stringify a cell value for the hidden data table. */
+function tableCell(value: unknown): string {
+  return value == null ? '' : String(value);
+}
+
 /**
  * Root chart container. Computes scales from data and provides them to children.
  *
@@ -103,6 +127,7 @@ export function Chart({
   yDomain: yDomainProp,
   xDomain: xDomainProp,
   interactive = false,
+  label,
   children,
 }: ChartProps) {
   const containerRef = useRef<HTMLDivElement>(null);
@@ -289,11 +314,18 @@ export function Chart({
     userSelect: interactive ? 'none' : undefined,
   };
 
+  const accessibleLabel = label ?? `Chart of ${yKeys.join(', ')} by ${xKey}`;
+  const showDataTable =
+    data.length > 0 &&
+    data.length * Math.max(yKeys.length, 1) <= MAX_TABLE_POINTS;
+
   return (
     <div ref={containerRef} style={containerStyle}>
       {containerWidth > 0 && (
         <svg
           ref={svgRef}
+          role="img"
+          aria-label={accessibleLabel}
           width={containerWidth}
           height={height}
           style={interactive ? {touchAction: 'none'} : undefined}>
@@ -307,6 +339,33 @@ export function Chart({
           </g>
         </svg>
       )}
+      {showDataTable && (
+        <VisuallyHidden as="div">
+          <table>
+            <caption>{`${accessibleLabel} data`}</caption>
+            <thead>
+              <tr>
+                <th scope="col">{xKey}</th>
+                {yKeys.map(key => (
+                  <th key={key} scope="col">
+                    {key}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {data.map((d, i) => (
+                <tr key={i}>
+                  <th scope="row">{tableCell(d[xKey])}</th>
+                  {yKeys.map(key => (
+                    <td key={key}>{tableCell(d[key])}</td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </VisuallyHidden>
+      )}
     </div>
   );
 }