@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/src/Table/__tests__/Table.a11y.chromium.spec.ts

@@ -0,0 +1,129 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(internal/a11y-spec/src/patterns/table\.|packages/core/src/Table/|apps/storybook/stories/TableA11y)
+
+/** Real-browser and accessibility-tree binding evidence for Table. */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {TABLE_A11Y_STATES, type TableA11yRow} from './Table.a11y.states';
+import {tableContractFor} from './Table.a11y.contracts';
+
+const SUBJECT_SELECTOR = '[data-a11y-table]';
+const ROWS = `${SUBJECT_SELECTOR} > thead > tr, ${SUBJECT_SELECTOR} > tbody > tr`;
+const COLUMN_HEADERS = `${SUBJECT_SELECTOR} > thead > tr > th`;
+const ROW_HEADERS = `${SUBJECT_SELECTOR} > tbody > tr > th`;
+const FIRST_ROW_CELLS = `${SUBJECT_SELECTOR} > tbody > tr:first-child > td`;
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => storybook?.close());
+
+function storyUrl(id: string): string {
+  return `${storybook.origin}/iframe.html?id=${id}&viewMode=story`;
+}
+
+function relatedFor(page: Page, state: TableA11yRow): Record<string, Locator> {
+  const related: Record<string, Locator> = {};
+  const designate = (selector: string, prefix: string, count: number) => {
+    const elements = page.locator(selector);
+    for (let index = 0; index < count; index += 1) {
+      related[`${prefix}-${index}`] = elements.nth(index);
+    }
+  };
+  designate(ROWS, 'row', state.facts.rows);
+  designate(COLUMN_HEADERS, 'column-header', state.facts.columnHeaders.length);
+  designate(ROW_HEADERS, 'row-header', state.facts.rowHeaders.length);
+  designate(FIRST_ROW_CELLS, 'cell', state.facts.cells);
+  return related;
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: TableA11yRow,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: tableContractFor(state),
+    binding: 'Table',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+      await holdMotionStill(page);
+      const subject = page.locator(SUBJECT_SELECTOR);
+      await subject.waitFor({state: 'attached'});
+      await expect(subject).toHaveCount(1);
+      await expect(page.locator(ROWS)).toHaveCount(state.facts.rows);
+      await expect(page.locator(COLUMN_HEADERS)).toHaveCount(
+        state.facts.columnHeaders.length,
+      );
+      await expect(page.locator(ROW_HEADERS)).toHaveCount(
+        state.facts.rowHeaders.length,
+      );
+      await expect(page.locator(FIRST_ROW_CELLS)).toHaveCount(
+        state.facts.cells,
+      );
+      return createChromiumHarness({
+        page,
+        cdp,
+        subject,
+        related: relatedFor(page, state),
+      });
+    },
+  });
+}
+
+test('every Table expectation is exercised by at least one Table state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of TABLE_A11Y_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+});
+
+for (const state of TABLE_A11Y_STATES) {
+  test(`Table [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(tableContractFor(state), [result]);
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(
+      result.results
+        .filter(row => row.status === 'fail')
+        .map(row => `${row.expectation}: ${row.detail ?? ''}`),
+      'this binding expects no failures',
+    ).toEqual([]);
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/Table/__tests__/Table.a11y.contracts.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * The contract each Table binding state checks: the base table contract, plus
+ * a module's contract for the states rendered with that module.
+ */
+
+import {
+  TABLE_PATTERN,
+  type PatternContract,
+  type TableStateFacts,
+} from '@astryxdesign/a11y-spec';
+import {
+  TABLE_SORTABLE_PATTERN,
+  type TableSortFacts,
+} from '../plugins/sortable/__tests__/useTableSortable.a11y';
+import type {TableA11yState} from './Table.a11y.states';
+
+/** Whether a state renders with useTableSortable. */
+export function tableUsesSort(state: TableA11yState): boolean {
+  return state.modules.includes('sort');
+}
+
+export function tableContractFor(
+  state: TableA11yState,
+): PatternContract<TableStateFacts> {
+  return (
+    tableUsesSort(state) ? TABLE_SORTABLE_PATTERN : TABLE_PATTERN
+  ) as PatternContract<TableStateFacts>;
+}
+
+/** The sort a state declares, or none when it renders without the sort module. */
+export function tableSortFor(state: TableA11yState): TableSortFacts['sort'] {
+  return 'sort' in state.facts ? state.facts.sort : [];
+}

package/src/Table/__tests__/Table.a11y.renders.tsx

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/** Stable Table renders shared by jsdom, Storybook, and Chromium. */
+
+import {useState, type ReactElement} from 'react';
+import {useTableSortable, type TableSortState} from '../plugins/sortable';
+import {Table} from '../Table';
+import {TableBody} from '../TableBody';
+import {TableCell} from '../TableCell';
+import {TableHeader} from '../TableHeader';
+import {TableHeaderCell} from '../TableHeaderCell';
+import {TableRow} from '../TableRow';
+import type {TableColumn} from '../types';
+import type {TableA11yRow} from './Table.a11y.states';
+
+type Member = {name: string; role: string; location: string};
+
+const MEMBERS: Member[] = [
+  {name: 'Ada', role: 'Engineer', location: 'London'},
+  {name: 'Grace', role: 'Admiral', location: 'Arlington'},
+];
+
+const COLUMNS: TableColumn<Member>[] = [
+  {key: 'name', header: 'Name'},
+  {key: 'role', header: 'Role'},
+  {key: 'location', header: 'Location'},
+];
+
+const SORTABLE_COLUMNS: TableColumn<Member>[] = COLUMNS.map(column => ({
+  ...column,
+  sortable: true,
+}));
+
+// useTableSortable only exposes the sort state; the caller orders the data.
+// Rows follow the state so the exposed aria-sort always matches the rows.
+function sortMembers(members: Member[], sort: TableSortState): Member[] {
+  const [primary] = sort;
+  if (primary == null) {
+    return members;
+  }
+  const key = primary.sortKey as keyof Member;
+  const sign = primary.direction === 'descending' ? -1 : 1;
+  return [...members].sort(
+    (a, b) => sign * (a[key] < b[key] ? -1 : a[key] > b[key] ? 1 : 0),
+  );
+}
+
+function SortedTable(): ReactElement {
+  const [sort, setSort] = useState<TableSortState>([
+    {sortKey: 'name', direction: 'descending'},
+  ]);
+  const sortPlugin = useTableSortable<Member>({sort, onSortChange: setSort});
+  return (
+    <Table<Member>
+      data-a11y-table
+      aria-label="Team members"
+      columns={SORTABLE_COLUMNS}
+      data={sortMembers(MEMBERS, sort)}
+      plugins={{sort: sortPlugin}}
+    />
+  );
+}
+
+export const TABLE_A11Y_RENDERS: Readonly<
+  Record<TableA11yRow['id'], () => ReactElement>
+> = {
+  'data-columns': () => (
+    <Table<Member>
+      data-a11y-table
+      aria-label="Team members"
+      columns={COLUMNS}
+      data={MEMBERS}
+    />
+  ),
+  'sorted-descending': () => <SortedTable />,
+  'children-row-headers-rtl': () => (
+    <div dir="rtl">
+      <h2 id="a11y-table-quarterly-heading">Quarterly totals</h2>
+      <Table data-a11y-table aria-labelledby="a11y-table-quarterly-heading">
+        <TableHeader>
+          <TableRow>
+            <TableHeaderCell>Region</TableHeaderCell>
+            <TableHeaderCell>Q1</TableHeaderCell>
+            <TableHeaderCell>Q2</TableHeaderCell>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          <TableRow>
+            <TableHeaderCell scope="row">North</TableHeaderCell>
+            <TableCell>120</TableCell>
+            <TableCell>135</TableCell>
+          </TableRow>
+          <TableRow>
+            <TableHeaderCell scope="row">South</TableHeaderCell>
+            <TableCell>98</TableCell>
+            <TableCell>104</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>
+    </div>
+  ),
+  'empty-data': () => (
+    <Table<Member>
+      data-a11y-table
+      aria-label="Team members"
+      columns={COLUMNS}
+      data={[]}
+    />
+  ),
+};

package/src/Table/__tests__/Table.a11y.states.ts

@@ -0,0 +1,140 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * AST-021 state inventory for the Table binding to the shared Table contract.
+ * A state rendered with a Table module also binds that module's contract
+ * (`Table.a11y.contracts.ts`); the others bind the base contract alone.
+ */
+
+import type {TableStateFacts} from '@astryxdesign/a11y-spec';
+import type {TableSortFacts} from '../plugins/sortable/__tests__/useTableSortable.a11y';
+
+export interface TableA11yState {
+  readonly id:
+    | 'data-columns'
+    | 'sorted-descending'
+    | 'children-row-headers-rtl'
+    | 'empty-data';
+  readonly mode: 'data-driven' | 'children';
+  readonly summary: string;
+  /** The Table modules the state renders with; each adds its own contract. */
+  readonly modules: ReadonlyArray<'sort'>;
+  readonly facts: TableStateFacts | (TableStateFacts & TableSortFacts);
+  readonly storyId: string;
+}
+
+export type TableA11yRow = (typeof TABLE_A11Y_STATES)[number];
+
+const story = (id: string) => `a11y-table-pattern--${id}`;
+
+export const TABLE_A11Y_STATES = [
+  {
+    id: 'data-columns',
+    mode: 'data-driven',
+    summary:
+      'a labelled data-driven table with three column headers and data rows',
+    modules: [],
+    facts: {
+      label: 'Team members',
+      columnHeaders: ['Name', 'Role', 'Location'],
+      rows: 3,
+      rowHeaders: [],
+      cells: 3,
+    },
+    storyId: story('data-columns'),
+  },
+  {
+    id: 'sorted-descending',
+    mode: 'data-driven',
+    summary:
+      'every column sortable through useTableSortable, sorted by Name descending',
+    modules: ['sort'],
+    facts: {
+      label: 'Team members',
+      columnHeaders: [
+        'Sort by Name, sorted descending',
+        'Sort by Role',
+        'Sort by Location',
+      ],
+      rows: 3,
+      rowHeaders: [],
+      cells: 3,
+      sort: [{column: 0, direction: 'descending'}],
+    },
+    storyId: story('sorted-descending'),
+  },
+  {
+    id: 'children-row-headers-rtl',
+    mode: 'children',
+    summary:
+      'a composed right-to-left table named by a visible heading, with a row header per row',
+    modules: [],
+    facts: {
+      label: 'Quarterly totals',
+      columnHeaders: ['Region', 'Q1', 'Q2'],
+      rows: 3,
+      rowHeaders: ['North', 'South'],
+      cells: 2,
+    },
+    storyId: story('children-row-headers-rtl'),
+  },
+  {
+    id: 'empty-data',
+    mode: 'data-driven',
+    summary:
+      'a labelled data-driven table with no rows, whose default empty state is one spanning data cell',
+    modules: [],
+    facts: {
+      label: 'Team members',
+      columnHeaders: ['Name', 'Role', 'Location'],
+      rows: 2,
+      rowHeaders: [],
+      cells: 1,
+    },
+    storyId: story('empty-data'),
+  },
+] as const satisfies ReadonlyArray<TableA11yState>;
+
+export const TABLE_A11Y_EXCLUSIONS = [
+  {
+    owner: 'useTableSelection tests and the checkbox contract',
+    reason:
+      'Selection controls, their labels, and row aria-selected are module behavior under component:Table FR6; this binding does not add the selection column.',
+  },
+  {
+    owner: 'useTableRowStatus tests (module:Table/useTableRowStatus)',
+    reason:
+      'The generated status column adds a visually hidden header name and per-row indicator cells, which are exactly the parts this contract checks; this binding does not add the status column, so those parts bind separately.',
+  },
+  {
+    owner:
+      'useTableRowExpansion, useTableGroupedRows, and useTableTreeData tests',
+    reason:
+      'Expansion detail rows, group header rows, and tree rows add rows and cells with their own semantics; each module binds separately.',
+  },
+  {
+    owner: 'BaseTable row-index tests',
+    reason:
+      'aria-rowcount and aria-rowindex for paged or windowed views are not encoded by the Table contract yet.',
+  },
+  {
+    owner: 'useTableSortable tests',
+    reason:
+      'Sort header buttons, their click and keyboard cycling, multi-sort priority, and sort context-menu actions stay with the module; this binding checks only the header role, name, and aria-sort it produces.',
+  },
+  {
+    owner: 'useTableFiltering and useTableColumnResize tests',
+    reason:
+      'The filter button and the resize separator render inside header cells and can change the header names this contract checks; each module keeps its own control semantics, and its header states bind separately.',
+  },
+  {
+    owner: 'TableScroll real-browser spec (component:Table FR1)',
+    reason:
+      'The named Scroll region, its conditional Tab stop, and overflow containment have their own browser evidence.',
+  },
+  {
+    owner: 'AST-009',
+    reason:
+      'This binding claims DOM and browser accessibility-tree exposure, not table navigation, speech, braille, or virtual-cursor behavior.',
+  },
+] as const;

package/src/Table/__tests__/Table.a11y.test.tsx

@@ -0,0 +1,198 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/** Fast DOM binding for Table against the shared Table contract. */
+
+import {cleanup, render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {TABLE_A11Y_RENDERS} from './Table.a11y.renders';
+import {
+  tableContractFor,
+  tableSortFor,
+  tableUsesSort,
+} from './Table.a11y.contracts';
+import {TABLE_SORTABLE_PATTERN} from '../plugins/sortable/__tests__/useTableSortable.a11y';
+import {
+  TABLE_A11Y_EXCLUSIONS,
+  TABLE_A11Y_STATES,
+  type TableA11yRow,
+} from './Table.a11y.states';
+
+const SUBJECT_SELECTOR = '[data-a11y-table]';
+const ROWS = ':scope > thead > tr, :scope > tbody > tr';
+const COLUMN_HEADERS = ':scope > thead > tr > th';
+const ROW_HEADERS = ':scope > tbody > tr > th';
+const FIRST_ROW_CELLS = ':scope > tbody > tr:first-child > td';
+
+function subjectFor(): HTMLElement {
+  const subjects = document.querySelectorAll(SUBJECT_SELECTOR);
+  if (subjects.length !== 1 || !(subjects[0] instanceof HTMLElement)) {
+    throw new Error(
+      `binding rendered ${subjects.length} table subjects instead of one`,
+    );
+  }
+  return subjects[0];
+}
+
+function relatedFor(state: TableA11yRow): Record<string, Element> {
+  const table = subjectFor();
+  const related: Record<string, Element> = {};
+  const designate = (selector: string, prefix: string, count: number) => {
+    const elements = table.querySelectorAll(selector);
+    if (elements.length < count) {
+      throw new Error(
+        `binding rendered ${elements.length} ${prefix} elements, fewer than the ${count} it declares`,
+      );
+    }
+    for (let index = 0; index < count; index += 1) {
+      related[`${prefix}-${index}`] = elements[index]!;
+    }
+  };
+  designate(ROWS, 'row', state.facts.rows);
+  designate(COLUMN_HEADERS, 'column-header', state.facts.columnHeaders.length);
+  designate(ROW_HEADERS, 'row-header', state.facts.rowHeaders.length);
+  designate(FIRST_ROW_CELLS, 'cell', state.facts.cells);
+  return related;
+}
+
+async function checkState(state: TableA11yRow): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: tableContractFor(state),
+    binding: 'Table',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(TABLE_A11Y_RENDERS[state.id]());
+      return createJsdomHarness({
+        subject: subjectFor(),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('the shared Table pattern, jsdom lane', () => {
+  it.each(
+    TABLE_A11Y_STATES.map(
+      state => [`Table [${state.id}]`, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: tableContractFor(state),
+      binding: 'Table',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(TABLE_A11Y_RENDERS[state.id]());
+      },
+      subject: subjectFor,
+      related: () => relatedFor(state),
+      cleanup,
+    });
+  });
+
+  it('runs DOM expectations and reports accessibility-tree outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of TABLE_A11Y_STATES) {
+      results.push(await checkState(state));
+    }
+    // The sortable contract is the base plus the sort module, so it reports
+    // every expectation any state ran.
+    const report = summarize(TABLE_SORTABLE_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('the Table binding inventory', () => {
+  it('names a distinct checked-in story for every state', () => {
+    const ids = TABLE_A11Y_STATES.map(state => state.storyId);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('binds only labelled tables, so every state exercises the table name', () => {
+    for (const state of TABLE_A11Y_STATES) {
+      expect(state.facts.label, state.id).not.toBeNull();
+    }
+  });
+
+  it('covers data-driven and children composition, row headers, sort, and empty data', () => {
+    expect(new Set(TABLE_A11Y_STATES.map(state => state.mode))).toEqual(
+      new Set(['data-driven', 'children']),
+    );
+    expect(
+      TABLE_A11Y_STATES.some(state => state.facts.rowHeaders.length > 0),
+    ).toBe(true);
+    expect(
+      TABLE_A11Y_STATES.some(state => tableSortFor(state).length > 0),
+    ).toBe(true);
+    expect(TABLE_A11Y_STATES.map(state => state.id)).toContain('empty-data');
+  });
+
+  it('renders the rows of every sorted state in the order its sort state declares', () => {
+    // useTableSortable exposes aria-sort but never reorders data, so a binding
+    // can claim a direction its own rows contradict.
+    for (const state of TABLE_A11Y_STATES) {
+      for (const {column, direction} of tableSortFor(state)) {
+        render(TABLE_A11Y_RENDERS[state.id]());
+        const values = [
+          ...subjectFor().querySelectorAll(':scope > tbody > tr'),
+        ].map(row => row.children[column]?.textContent ?? '');
+        const ordered = [...values].sort();
+        if (direction === 'descending') {
+          ordered.reverse();
+        }
+        expect(values.length, state.id).toBeGreaterThan(1);
+        expect(values, `${state.id} column ${column}`).toEqual(ordered);
+        cleanup();
+      }
+    }
+  });
+
+  it('composes the sort module only for states rendered with useTableSortable', () => {
+    for (const state of TABLE_A11Y_STATES) {
+      const ids = tableContractFor(state).expectations.map(
+        expectation => expectation.id,
+      );
+      expect(ids.includes('table.sort.exposed'), state.id).toBe(
+        tableUsesSort(state),
+      );
+      expect('sort' in state.facts, state.id).toBe(tableUsesSort(state));
+    }
+  });
+
+  it('records every adjacent exclusion with an owner and reason', () => {
+    expect(TABLE_A11Y_EXCLUSIONS.every(row => row.owner && row.reason)).toBe(
+      true,
+    );
+  });
+
+  it('declares exactly the rows, headers, and first-row cells each state renders', () => {
+    for (const state of TABLE_A11Y_STATES) {
+      render(TABLE_A11Y_RENDERS[state.id]());
+      const table = subjectFor();
+      expect(table.querySelectorAll(ROWS).length, state.id).toBe(
+        state.facts.rows,
+      );
+      expect(table.querySelectorAll(COLUMN_HEADERS).length, state.id).toBe(
+        state.facts.columnHeaders.length,
+      );
+      expect(table.querySelectorAll(ROW_HEADERS).length, state.id).toBe(
+        state.facts.rowHeaders.length,
+      );
+      expect(table.querySelectorAll(FIRST_ROW_CELLS).length, state.id).toBe(
+        state.facts.cells,
+      );
+      cleanup();
+    }
+  });
+});

package/src/Table/__tests__/TableMinWidth.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y always
 
 /**
  * @file TableMinWidth.a11y.chromium.spec.ts

package/src/Table/__tests__/TableScroll.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file TableScroll.a11y.chromium.spec.ts