@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/Tokenizer/Tokenizer.tsx

@@ -729,6 +729,18 @@ export function Tokenizer<T extends SearchableItem>({
     [value],
   );
 
+  // Selected labels, lowercased, for the Create entry's duplicate check. The
+  // typed text is a label, not an id: real selections usually carry an opaque
+  // id (`usr_123` under the label "Alice"), so comparing the text against ids
+  // alone misses an already-tokenized label — and the search results cannot
+  // catch it either, because filteredSource has already removed the selected
+  // item from them. The result was a "Create Alice" entry that, when picked,
+  // added a second "Alice" token under a different id.
+  const selectedLabels = useMemo(
+    () => new Set(value.map(item => item.label.toLowerCase())),
+    [value],
+  );
+
   const filteredSource: SearchSource<T> = useMemo(
     () => ({
       search: async (query: string) => {
@@ -759,6 +771,7 @@ export function Tokenizer<T extends SearchableItem>({
       }
       const alreadyExists =
         selectedIds.has(trimmed) ||
+        selectedLabels.has(trimmed.toLowerCase()) ||
         results.some(
           item => item.label.toLowerCase() === trimmed.toLowerCase(),
         );
@@ -773,7 +786,7 @@ export function Tokenizer<T extends SearchableItem>({
         } as unknown as T,
       ];
     },
-    [hasCreate, selectedIds],
+    [hasCreate, selectedIds, selectedLabels],
   );
 
   const emptySource: SearchSource<T> = useMemo(
@@ -807,7 +820,13 @@ export function Tokenizer<T extends SearchableItem>({
         item.id.startsWith(CREATABLE_ID_PREFIX)
       ) {
         const createdValue = item.id.slice(CREATABLE_ID_PREFIX.length);
-        if (selectedIds.has(createdValue)) {
+        // Same domain fix as createEntries: the created value names itself by
+        // label, so a selection carrying an opaque id with that label is also a
+        // duplicate, not just one whose id happens to equal the text.
+        if (
+          selectedIds.has(createdValue) ||
+          selectedLabels.has(createdValue.toLowerCase())
+        ) {
           return;
         }
         const base = {id: createdValue, label: createdValue};
@@ -825,7 +844,16 @@ export function Tokenizer<T extends SearchableItem>({
       onChange(newItems, {item, type: 'add'});
       announce(t('@astryx.tokenizer.tokenAdded', {label: item.label}));
     },
-    [value, onChange, isAtMax, selectedIds, hasCreate, announce, t],
+    [
+      value,
+      onChange,
+      isAtMax,
+      selectedIds,
+      selectedLabels,
+      hasCreate,
+      announce,
+      t,
+    ],
   );
 
   // Handle removing an item. Single removal path: both Backspace on an empty

package/src/Toolbar/Toolbar.test.tsx

@@ -2,18 +2,19 @@
 
 /**
  * @file Toolbar.test.tsx
- * @input Uses vitest, @testing-library/react, Toolbar
- * @output Unit tests for Toolbar component
- * @position Testing; validates Toolbar implementation
+ * @input Uses vitest, @testing-library/react, user-event, Toolbar, MoreMenu
+ * @output Unit tests for Toolbar component and nested popover focus ownership
+ * @position Testing; validates Toolbar implementation and post-dismissal tab stops
  *
  * SYNC: When Toolbar component changes, update tests to match new behavior
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {act, fireEvent, render, screen, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import * as stylex from '@stylexjs/stylex';
 import {Toolbar} from './Toolbar';
+import {MoreMenu} from '../MoreMenu';
 import {
   paddingBlockStyles,
   paddingInlineStyles,
@@ -377,6 +378,132 @@ describe('Toolbar', () => {
     expect(buttons[2]).toHaveAttribute('tabindex', '-1');
   });
 
+  it('keeps its tab stop after outside dismissal of MoreMenu', async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <button type="button">Before</button>
+        <Toolbar
+          label="Actions"
+          startContent={<button type="button">Copy</button>}
+          endContent={
+            <MoreMenu
+              label="More actions"
+              items={[{label: 'Duplicate'}, {label: 'Delete'}]}
+            />
+          }
+        />
+        <button type="button">After</button>
+      </>,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'More actions'});
+    // Seed the trigger's tab stop with keyboard navigation so this tests
+    // boundary ownership independently of pointer-focus synchronization.
+    act(() => screen.getByRole('button', {name: 'Copy'}).focus());
+    await user.keyboard('{ArrowRight}');
+    expect(trigger).toHaveFocus();
+    await user.click(trigger);
+    await waitFor(() =>
+      expect(screen.getByRole('menu', {hidden: true})).toHaveFocus(),
+    );
+
+    const item = screen.getByRole('menuitem', {
+      name: 'Duplicate',
+      hidden: true,
+    });
+    act(() => item.focus());
+    expect(item).toHaveFocus();
+    expect(trigger.getAttribute('tabindex')).toBe('0');
+    expect(
+      screen.getByRole('button', {name: 'Copy'}).getAttribute('tabindex'),
+    ).toBe('-1');
+    expect(
+      screen.getByRole('menu', {hidden: true}).getAttribute('tabindex'),
+    ).not.toBe('0');
+
+    await user.click(screen.getByRole('button', {name: 'After'}));
+    // jsdom has no native light dismiss. Deliver the browser's close event
+    // after focus has moved outside, without restoring it to the trigger.
+    const popover = item.closest('[popover]');
+    fireEvent(
+      popover!,
+      Object.assign(new Event('toggle'), {newState: 'closed'}),
+    );
+    await waitFor(() =>
+      expect(trigger).toHaveAttribute('aria-expanded', 'false'),
+    );
+    expect(screen.getByRole('button', {name: 'After'})).toHaveFocus();
+    await user.tab({shift: true});
+    expect(trigger).toHaveFocus();
+    await user.tab({shift: true});
+    expect(screen.getByRole('button', {name: 'Before'})).toHaveFocus();
+  });
+
+  it('leaves navigation inside an open MoreMenu to the menu', async () => {
+    const user = userEvent.setup();
+    render(
+      <Toolbar
+        label="Actions"
+        startContent={<button type="button">Copy</button>}
+        endContent={
+          <MoreMenu
+            label="More actions"
+            items={[{label: 'Duplicate'}, {label: 'Delete'}]}
+          />
+        }
+      />,
+    );
+    const trigger = screen.getByRole('button', {name: 'More actions'});
+    act(() => screen.getByRole('button', {name: 'Copy'}).focus());
+    await user.keyboard('{ArrowRight}');
+    expect(trigger).toHaveFocus();
+    await user.click(trigger);
+    await waitFor(() =>
+      expect(screen.getByRole('menu', {hidden: true})).toHaveFocus(),
+    );
+
+    const first = screen.getByRole('menuitem', {
+      name: 'Duplicate',
+      hidden: true,
+    });
+    const last = screen.getByRole('menuitem', {name: 'Delete', hidden: true});
+    act(() => first.focus());
+    await user.keyboard('{ArrowLeft}');
+    expect(first).toHaveFocus();
+    await user.keyboard('{ArrowRight}');
+    expect(first).toHaveFocus();
+
+    await user.keyboard('{ArrowDown}');
+    expect(last).toHaveFocus();
+
+    expect(trigger).toHaveAttribute('tabindex', '0');
+  });
+
+  it('keeps its own arrow navigation when rendered inside a popover', async () => {
+    const user = userEvent.setup();
+    render(
+      <div popover="manual">
+        <Toolbar
+          label="Actions"
+          startContent={
+            <>
+              <button type="button">Copy</button>
+              <button type="button">Paste</button>
+            </>
+          }
+        />
+      </div>,
+    );
+    // jsdom does not open native popovers; the ancestor still tests ownership.
+    const copy = screen.getByRole('button', {name: 'Copy', hidden: true});
+    const paste = screen.getByRole('button', {name: 'Paste', hidden: true});
+    act(() => copy.focus());
+    await user.keyboard('{ArrowRight}');
+    expect(paste).toHaveFocus();
+    expect(paste.getAttribute('tabindex')).toBe('0');
+  });
+
   it('does not steal caret keys from a text input mid-line (navigation-4)', async () => {
     const user = userEvent.setup();
     render(

package/src/Toolbar/Toolbar.tsx

@@ -6,7 +6,8 @@
  * @file Toolbar.tsx
  * @input Uses Section, SizeContext, useListFocus, useKeyboardHint, StyleX, spacingVars, sizeVars
  * @output Exports Toolbar component and ToolbarProps
- * @position Core implementation; consumed by index.ts
+ * @position Core implementation; consumed by index.ts. Owns toolbar focus and
+ *   keyboard navigation, excluding nested toolbars and popover contents.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Toolbar/Toolbar.doc.mjs
@@ -248,6 +249,7 @@ export function Toolbar({
 
   const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
     itemSelector: 'button, input, [tabindex]',
+    boundarySelector: '[role="toolbar"], [popover]',
     orientation,
     hasRovingTabIndex: true,
     hasCaretGuard: true,

package/src/TreeList/TreeList.spec.md

@@ -148,6 +148,21 @@ The styling seam does not change TreeList's tree, treeitem, group, roving-focus,
 expansion, selection, disabled, or activation behavior. Styling inputs MUST NOT
 replace component-owned semantic or interaction props.
 
+- **AR1 — TreeList adopts the APG Tree View pattern** (`spec:AST-020/FR15`), as
+  one composite control: the Tree list is `role="tree"`, named by its Header
+  when one is rendered and otherwise by the caller's `aria-label` or
+  `aria-labelledby`; every row is `role="treeitem"`, named by its label and described by its
+  description, `aria-expanded` when it has children,
+  `aria-selected` when it is the selected row, `aria-level` for its depth, and
+  `aria-posinset`/`aria-setsize` among its siblings; children sit in a `role="group"`. One row holds the Tab stop
+  (roving focus). ArrowDown/ArrowUp move between visible rows; ArrowRight expands
+  a closed row, then moves into its first child, and ArrowLeft collapses an open
+  row or moves to the parent — mirrored under RTL; Home and End move to the first
+  and last visible rows; Enter and Space activate the focused row; typing letters
+  moves to the next row whose label starts with them. Selection is caller-owned:
+  callers mark at most one row selected (`isSelected`); the tree does not
+  enforce it, claims no `aria-multiselectable`, and has no selection keyboard.
+
 ## Design relationships
 
 | Anatomy or state | Design requirement                                                               | Representation authority        | Hierarchy role    | Component contract |
@@ -227,14 +242,15 @@ authorize or prohibit a future target.
 
 ## Verification map
 
-| Contract            | Verification                                                                                            | Representative states                                 | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section            |
-| ------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection         | Flat, nested, described, headed, and slotted items    | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` |
-| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                        | Five local targets and their documented states        | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming` |
-| FR3                 | Source inspection plus Icon public target metadata                                                      | Expandable rows and caller-provided slots             | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming` |
-| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                                    | Item with description                                 | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy` |
-| FR5, FR6, ORD1      | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation | One input at a time; all three together; sibling rows | Dropping any mechanism, applying mechanisms to different elements, targeting the `<li>`, changing the merge order, or styling a sibling row fails.                                                                                                  | `audit:TreeList/api`     |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                           | Canonical anatomy and five current local targets      | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                                                                                                                                 | `audit:TreeList/theming` |
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Representative states                                                                  | Mutation or failure expectation                                                                                                                                                                                                                     | Audit section                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1                 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Flat, nested, described, headed, and slotted items                                     | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy`       |
+| FR2                 | `TreeList.test.tsx` and `themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Five local targets and their documented states                                         | Removing or moving any current local target fails focused class assertions or the global inventory.                                                                                                                                                 | `audit:TreeList/theming`       |
+| FR3                 | Source inspection plus Icon public target metadata                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Expandable rows and caller-provided slots                                              | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change.                                                                                      | `audit:TreeList/theming`       |
+| FR4                 | `TreeList.test.tsx` description rendering test and source inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Item with description                                                                  | Removing description fails content coverage; adding a target requires an explicit map update.                                                                                                                                                       | `audit:TreeList/anatomy`       |
+| AR1                 | Tree View accessibility contract (`internal/a11y-spec`, pending) bound to TreeList, in jsdom and Chromium; `TreeList.test.tsx` row-naming cases ("names a parent row by its label alone, not the chevron toggle", "names a plain row by its label and describes it with its description", "names and describes link and action rows themselves, not only their inner control", "keeps start and end content, including controls, out of the row name", "typeahead matches the label, not the description or start content") and `TreeListRowNames.a11y.chromium.spec.ts` for the browser-computed names; `TreeList.test.tsx` structural ARIA cases ("sets aria-level, aria-posinset, and aria-setsize at the top level", "sets aria-level/posinset/setsize correctly at deeper levels", "sets aria-level across three depths"); `TreeList.test.tsx` and `useTreeFocus.test.tsx` keyboard suites | Flat and nested trees; expanded/collapsed; selected/unselected; LTR and RTL; typeahead | A row loses its role, label name, state or position, two rows hold a Tab stop, an arrow key stops moving or stops mirroring under RTL, Home/End or typeahead stop working, or the tree claims multi-select                                          | `audit:TreeList/accessibility` |
+| FR5, FR6, ORD1      | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | One input at a time; all three together; sibling rows                                  | Dropping any mechanism, applying mechanisms to different elements, targeting the `<li>`, changing the merge order, or styling a sibling row fails.                                                                                                  | `audit:TreeList/api`           |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Canonical anatomy and five current local targets                                       | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation.                                                                                                                                                                 | `audit:TreeList/theming`       |
 
 Focused target-placement assertions cover all five local targets. Runtime support
 and mutation-sensitive coverage for the item styling seam may land separately,
@@ -261,6 +277,15 @@ Rejected: applying the seam to the outer semantic `<li>`. That element owns tree
 semantics and child grouping, while the row box is the stable visual and hover
 boundary callers need to address.
 
+### DEC-2 — The tree is one composite control with single, caller-owned selection
+
+**Reference:** `component:TreeList/DEC-2`
+**Decider:** `cixzhang`, `2026-10-13`
+
+TreeList already plays the Tree View's role as one widget — one Tab stop, arrows, Home/End, activation, typeahead — so it adopts the pattern's keyboard model except the optional `*` key (AR1), not only the required parts. Callers mark at most one row selected (`isSelected`) and the tree does not enforce it, so the tree never claims `aria-multiselectable` and adds no range or toggle keyboard.
+
+Rejected: multi-select (`aria-multiselectable`, Shift/Ctrl ranges); a Tab stop per row.
+
 ## Open questions
 
 None.

package/src/TreeList/TreeList.test.tsx

@@ -170,6 +170,78 @@ describe('TreeList', () => {
     expect(screen.getByText('Description text')).toBeInTheDocument();
   });
 
+  // ===========================================================================
+  // Row accessible name and description (APG tree view: named by the label)
+  // ===========================================================================
+
+  it('names a parent row by its label alone, not the chevron toggle', () => {
+    const items: TreeListItemData[] = [
+      {id: 'docs', label: 'Documents', children: [{id: 'a', label: 'Annual'}]},
+    ];
+    render(<TreeList items={items} />);
+    const row = screen.getByText('Documents').closest('li')!;
+    expect(row).toHaveAccessibleName('Documents');
+  });
+
+  it('names a plain row by its label and describes it with its description', () => {
+    const items: TreeListItemData[] = [
+      {id: 'a', label: 'Budget', description: 'Updated yesterday'},
+    ];
+    render(<TreeList items={items} />);
+    const row = screen.getByText('Budget').closest('li')!;
+    expect(row).toHaveAccessibleName('Budget');
+    expect(row).toHaveAccessibleDescription('Updated yesterday');
+  });
+
+  it('names and describes link and action rows themselves, not only their inner control', () => {
+    const items: TreeListItemData[] = [
+      {id: 'l', label: 'Report', description: 'Opens the report', href: '#'},
+      {
+        id: 'b',
+        label: 'Export',
+        description: 'Downloads a file',
+        onClick: () => {},
+      },
+    ];
+    render(<TreeList items={items} />);
+    const link = screen.getByText('Report').closest('li')!;
+    expect(link).toHaveAccessibleName('Report');
+    expect(link).toHaveAccessibleDescription('Opens the report');
+    const action = screen.getByText('Export').closest('li')!;
+    expect(action).toHaveAccessibleName('Export');
+    expect(action).toHaveAccessibleDescription('Downloads a file');
+  });
+
+  it('keeps start and end content, including controls, out of the row name', () => {
+    const items: TreeListItemData[] = [
+      {
+        id: 'a',
+        label: 'Invoices',
+        startContent: <span>12</span>,
+        endContent: <button type="button">Pin folder</button>,
+      },
+    ];
+    render(<TreeList items={items} />);
+    const row = screen.getByText('Invoices').closest('li')!;
+    expect(row).toHaveAccessibleName('Invoices');
+  });
+
+  it('typeahead matches the label, not the description or start content', async () => {
+    const user = userEvent.setup();
+    const items: TreeListItemData[] = [
+      {id: 'a', label: 'Apple', description: 'Cherry-red fruit'},
+      {id: 'b', label: 'Banana', startContent: <span>Curved</span>},
+      {id: 'c', label: 'Cherry'},
+    ];
+    render(<TreeList items={items} />);
+    const apple = screen.getByText('Apple').closest('li')!;
+    apple.focus();
+    await user.keyboard('c');
+    expect(document.activeElement).toBe(
+      screen.getByText('Cherry').closest('li'),
+    );
+  });
+
   // ===========================================================================
   // Semantic HTML
   // ===========================================================================

package/src/TreeList/TreeList.tsx

@@ -27,7 +27,7 @@ import type {
   TreeListVariant,
 } from './TreeListTypes';
 import {themeProps} from '../utils/themeProps';
-import {useTreeFocus} from '../hooks/useTreeFocus';
+import {useTreeFocusInternal} from '../hooks/useTreeFocus';
 
 // =============================================================================
 // Types
@@ -255,11 +255,15 @@ export function TreeList({
     return false;
   }, []);
 
-  const {treeRef, handleKeyDown, handleFocus} = useTreeFocus<HTMLUListElement>({
-    onToggleExpand: handleToggle,
-    onActivate: activateItem,
-    hasRovingTabIndex: true,
-  });
+  const {treeRef, handleKeyDown, handleFocus} =
+    useTreeFocusInternal<HTMLUListElement>({
+      onToggleExpand: handleToggle,
+      onActivate: activateItem,
+      hasRovingTabIndex: true,
+      // Rows are named by their label (AR1); typeahead matches that label, not
+      // the chevron toggle, start content or description.
+      matchLabelledBy: true,
+    });
 
   const handleRootKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLDivElement>) => {

package/src/TreeList/TreeListItem.tsx

@@ -557,6 +557,11 @@ export function TreeListItem({
   return (
     <li
       role="treeitem"
+      // The row is named by its label alone and described by its description
+      // (APG tree view): without these the name would be the row's whole text,
+      // chevron button label and description included.
+      aria-labelledby={labelId}
+      aria-describedby={description != null ? descriptionId : undefined}
       aria-expanded={hasChildren ? isExpanded : undefined}
       aria-selected={isSelected || undefined}
       aria-disabled={isDisabled || undefined}

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

@@ -0,0 +1,125 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TreeList.a11y.chromium.spec.ts
+ * @input Built TreeList tree-view stories and TREE_VIEW_PATTERN in real Chromium
+ * @output Browser evidence for every tree-view expectation across the binding's states
+ * @position Chromium lane of the TreeList tree-view binding (component:TreeList AR1)
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  TREE_VIEW_PATTERN,
+  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 {
+  TREE_LIST_BINDING_STATES,
+  type TreeListBindingState,
+} from './TreeList.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+  return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+function rowLocator(page: Page, id: string): Locator {
+  return page.locator(
+    `#storybook-root [role="treeitem"][data-tree-id="${id}"]`,
+  );
+}
+
+async function mountState(
+  page: Page,
+  state: TreeListBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const subject = rowLocator(page, state.subject);
+  await subject.waitFor({state: 'attached'});
+  const root = page.locator('#storybook-root');
+  const related: Record<string, Locator> = {
+    tree: root.getByRole('tree'),
+    before: root.getByRole('button', {name: 'Before the tree'}),
+    after: root.getByRole('button', {name: 'After the tree'}),
+    group: subject.locator('[role="group"]'),
+  };
+  for (const [name, id] of Object.entries(state.relations)) {
+    related[name] = rowLocator(page, id);
+  }
+  return {subject, related};
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: TreeListBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TREE_VIEW_PATTERN,
+    binding: 'TreeList',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every tree-view expectation is exercised by a TreeList state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of TREE_LIST_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+});
+
+for (const state of TREE_LIST_BINDING_STATES) {
+  test(`TreeList [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(TREE_VIEW_PATTERN, [result]);
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(
+      result.results.filter(
+        row => row.status !== 'pass' && row.status !== 'not-applicable',
+      ),
+    ).toEqual([]);
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

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

@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TreeList.a11y.renders.tsx
+ * @input One TreeList tree-view binding state
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook)
+ * @position Shared fixture for the TreeList tree-view binding
+ */
+
+import type {ReactElement} from 'react';
+import {TreeList} from '../TreeList';
+import type {TreeListItemData} from '../TreeListTypes';
+import {
+  TREE_LIST_LABEL,
+  type TreeListBindingState,
+} from './TreeList.a11y.states';
+
+export function renderTreeListState(
+  state: Pick<TreeListBindingState, 'expanded' | 'disabled' | 'direction'>,
+): ReactElement {
+  const expanded = (id: string) => state.expanded.includes(id);
+  const disabled = (id: string) => state.disabled?.includes(id) ?? false;
+  const items: TreeListItemData[] = [
+    {
+      id: 'docs',
+      label: 'Documents',
+      isExpanded: expanded('docs'),
+      isDisabled: disabled('docs'),
+      children: [
+        {id: 'annual', label: 'Annual report'},
+        {id: 'budget', label: 'Budget'},
+      ],
+    },
+    {id: 'photos', label: 'Photos', isDisabled: disabled('photos')},
+    {id: 'trash', label: 'Trash', isDisabled: disabled('trash')},
+  ];
+  return (
+    <div dir={state.direction ?? 'ltr'}>
+      <button type="button">Before the tree</button>
+      <TreeList aria-label={TREE_LIST_LABEL} items={items} />
+      <button type="button">After the tree</button>
+    </div>
+  );
+}