@astryxdesign/core 0.7.1 → 0.7.2-canary.020e1fe

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

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Toolbar.a11y.test.tsx
+ * @input TOOLBAR_PATTERN bound to Toolbar's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for Toolbar (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  TOOLBAR_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {renderToolbarState} from './Toolbar.a11y.renders';
+import {
+  TOOLBAR_BINDING_STATES,
+  TOOLBAR_EXCLUSIONS,
+  type ToolbarBindingState,
+} from './Toolbar.a11y.states';
+
+function toolbarFor(state: ToolbarBindingState): HTMLElement {
+  return screen.getByRole('toolbar', {name: state.label});
+}
+
+function relatedFor(
+  state: ToolbarBindingState,
+): Readonly<Record<string, Element>> {
+  const related: Record<string, Element> = {
+    before: screen.getByRole('button', {name: 'Before the toolbar'}),
+    after: screen.getByRole('button', {name: 'After the toolbar'}),
+  };
+  for (const [relation, name] of Object.entries(state.controls)) {
+    related[relation] = screen.getByRole('button', {name});
+  }
+  return related;
+}
+
+async function checkState(state: ToolbarBindingState): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLBAR_PATTERN,
+    binding: 'Toolbar',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(renderToolbarState(state));
+      return createJsdomHarness({
+        subject: toolbarFor(state),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('Toolbar — toolbar pattern, jsdom lane', () => {
+  it.each(
+    TOOLBAR_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: TOOLBAR_PATTERN,
+      binding: 'Toolbar',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(renderToolbarState(state));
+      },
+      subject: () => toolbarFor(state),
+      related: () => relatedFor(state),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of TOOLBAR_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(TOOLBAR_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('toolbar binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = TOOLBAR_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps control semantics, editing and popover keys, the three-lane layout, and outer chrome explicit', () => {
+    expect(TOOLBAR_EXCLUSIONS.map(row => row.id)).toEqual([
+      'control-semantics',
+      'caret-guard-and-nested-popovers',
+      'three-lane-layout',
+      'outer-chrome',
+    ]);
+    for (const exclusion of TOOLBAR_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the toolbar and every control relation it names for every state', () => {
+    for (const state of TOOLBAR_BINDING_STATES) {
+      render(renderToolbarState(state));
+      const toolbar = toolbarFor(state);
+      for (const name of Object.values(state.controls)) {
+        expect(
+          toolbar.contains(screen.getByRole('button', {name})),
+          `${state.id}: ${name}`,
+        ).toBe(true);
+      }
+      cleanup();
+    }
+  });
+});

package/src/Tooltip/Tooltip.test.tsx

@@ -183,6 +183,37 @@ describe('Tooltip', () => {
     });
   });
 
+  describe('icon-only trigger', () => {
+    // A rendered icon is an SVGElement, and ShowPopoverOptions.source is
+    // declared as an HTMLElement. Handing the icon to showPopover throws
+    // during dictionary conversion, before the popover opens, so the hint
+    // never appeared. (#7226)
+    it('opens an icon trigger without passing an SVGElement as the source', async () => {
+      const showSpy = vi.mocked(HTMLElement.prototype.showPopover);
+      showSpy.mockClear();
+
+      render(
+        <Tooltip content="Shared memory" isDefaultOpen>
+          <svg data-testid="icon" aria-hidden="true" />
+        </Tooltip>,
+      );
+
+      await waitFor(() => {
+        expect(showSpy).toHaveBeenCalled();
+      });
+
+      const [options] = showSpy.mock.calls[0];
+      // Compared as a boolean on purpose: a plain `toBeUndefined` failure makes
+      // the diff printer walk the SVGElement, which it cannot inspect.
+      expect(options?.source === undefined).toBe(true);
+
+      // The icon is still the trigger the ARIA tooltip pattern is wired to.
+      expect(screen.getByTestId('icon').getAttribute('aria-describedby')).toBe(
+        screen.getByRole('tooltip', {hidden: true}).id,
+      );
+    });
+  });
+
   describe('WCAG 1.4.13 — content on hover or focus', () => {
     it('dismisses on Escape while visible (dismissible)', async () => {
       const onOpenChange = vi.fn();

package/src/Tooltip/useTooltip.test.tsx

@@ -147,6 +147,19 @@ describe('useTooltip — show delay', () => {
 
     expect(onShow).not.toHaveBeenCalled();
   });
+
+  it('drops a pending show when isEnabled turns false before the delay elapses', () => {
+    const onShow = vi.fn();
+    const {rerender} = render(<Harness onShow={onShow} />);
+
+    fireEvent.mouseEnter(trigger());
+    tick(100);
+    rerender(<Harness isEnabled={false} onShow={onShow} />);
+    tick(1000);
+
+    expect(onShow).not.toHaveBeenCalled();
+    expect(tooltipElement().matches(':popover-open')).toBe(false);
+  });
 });
 
 describe('useTooltip — touch suppression', () => {

package/src/Tooltip/useTooltip.tsx

@@ -352,6 +352,17 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     }, delay);
   }, [isEnabled, isOpen, clearTimeouts, showLayer, delay]);
 
+  // A show scheduled while the triggers were enabled must not outlive them:
+  // disabling also detaches the leave listener that would have cancelled it,
+  // so the timer would open a tooltip that nothing ever closes. Only the
+  // pending show is dropped; a pending hide still runs.
+  useEffect(() => {
+    if (!isEnabled && showTimeoutRef.current) {
+      clearTimeout(showTimeoutRef.current);
+      showTimeoutRef.current = null;
+    }
+  }, [isEnabled]);
+
   // Schedule hide with delay (suppressed when isOpen is true).
   // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
   // trigger onto the tooltip surface without the tooltip vanishing — required

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -769,6 +769,28 @@ describe('TopNavMegaMenu — drawer mode', () => {
     expect(handleClick).toHaveBeenCalledTimes(1);
   });
 
+  it('clips the drawer section only while it is collapsed', async () => {
+    // The ring paints outside the item, so a permanent clip would cut it off.
+    const user = userEvent.setup();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu
+          label="Products"
+          items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+        />
+      </TopNavRenderContext>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    const section = document.getElementById(
+      trigger.getAttribute('aria-controls') ?? '',
+    )!;
+    expect(getComputedStyle(section).overflow).toBe('hidden');
+    expect(getComputedStyle(section.firstElementChild!).overflow).toBe('');
+
+    await user.click(trigger);
+    expect(getComputedStyle(section).overflow).toBe('visible');
+  });
+
   it('renders featured content when expanded', async () => {
     const user = userEvent.setup();
 

package/src/TopNav/TopNavMegaMenu.tsx

@@ -229,18 +229,22 @@ const styles = stylex.create({
   drawerChevronExpanded: {
     transform: 'rotate(180deg)',
   },
+  // Clips only while collapsed or animating; see TopNavMenu drawerStyles.items.
   drawerItems: {
     display: 'grid',
     gridTemplateRows: '0fr',
-    transitionProperty: 'grid-template-rows',
-    transitionDuration: durationVars['--duration-medium'],
+    overflow: 'hidden',
+    transitionProperty: 'grid-template-rows, overflow',
+    transitionBehavior: 'allow-discrete',
+    transitionDuration: `${durationVars['--duration-medium']}, 0s`,
     transitionTimingFunction: easeVars['--ease-standard'],
   },
   drawerItemsExpanded: {
     gridTemplateRows: '1fr',
+    overflow: 'visible',
+    transitionDelay: `0s, ${durationVars['--duration-medium']}`,
   },
   drawerItemsInner: {
-    overflow: 'hidden',
     minHeight: 0,
   },
 

package/src/TopNav/TopNavMenu.test.tsx

@@ -241,6 +241,25 @@ describe('TopNavMenu — drawer focus ring', () => {
     );
     expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
   });
+
+  it('clips the drawer section only while it is collapsed', async () => {
+    // The ring paints outside the item, so a permanent clip would cut it off.
+    const user = userEvent.setup();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu label="Products" items={mockItems} />
+      </TopNavRenderContext>,
+    );
+    const trigger = screen.getByRole('button', {name: /Products/});
+    const section = document.getElementById(
+      trigger.getAttribute('aria-controls') ?? '',
+    )!;
+    expect(getComputedStyle(section).overflow).toBe('hidden');
+    expect(getComputedStyle(section.firstElementChild!).overflow).toBe('');
+
+    await user.click(trigger);
+    expect(getComputedStyle(section).overflow).toBe('visible');
+  });
 });
 
 describe('TopNavMenu pass-through props', () => {

package/src/TopNav/TopNavMenu.tsx

@@ -194,18 +194,26 @@ const drawerStyles = stylex.create({
   chevronExpanded: {
     transform: 'rotate(180deg)',
   },
+  // The section clips its items only for the 0fr collapse animation: a
+  // permanent clip cuts off the focus ring, which paints outside the item.
+  // `overflow` is discrete, so it rides the transition with `allow-discrete`
+  // and switches to `visible` only after the open has finished. Collapsing
+  // clips again at once.
   items: {
     display: 'grid',
     gridTemplateRows: '0fr',
-    transitionProperty: 'grid-template-rows',
-    transitionDuration: durationVars['--duration-medium'],
+    overflow: 'hidden',
+    transitionProperty: 'grid-template-rows, overflow',
+    transitionBehavior: 'allow-discrete',
+    transitionDuration: `${durationVars['--duration-medium']}, 0s`,
     transitionTimingFunction: easeVars['--ease-standard'],
   },
   itemsExpanded: {
     gridTemplateRows: '1fr',
+    overflow: 'visible',
+    transitionDelay: `0s, ${durationVars['--duration-medium']}`,
   },
   itemsInner: {
-    overflow: 'hidden',
     minHeight: 0,
   },
   item: {

package/src/TreeList/TreeList.doc.mjs

@@ -89,6 +89,7 @@ export const docs = {
       {name: '--tree-list-indent', description: 'Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the `tree-list` target to retune the metric (e.g. `var(--spacing-5)` for a wider indent).', default: 'var(--spacing-4)'},
       {name: '--tree-list-row-gap', description: 'Vertical gap between adjacent rows. Default `2px` (var(--spacing-0-5)) gives a subtle separation; set it on the `tree-list` target to widen or close the gap. The connector guides span the gap automatically (the line stays continuous) and do not overhang the last row, so no guide-height tuning is needed.', default: 'var(--spacing-0-5)'},
       {name: '--_tree-indent', description: 'Distance one row is indented, computed per row from --tree-list-indent and the row depth. Set --tree-list-indent to retune indentation; this is the resolved value.', default: '0px', private: true},
+      {name: '--_tree-focus-z', description: 'Stacking order of a row while its treeitem has keyboard focus, published by each treeitem so its focused row paints above the guide lines. Not a theming lever.', default: 'auto', private: true},
     ],
   },
   components: [

package/src/TreeList/TreeList.spec.md

@@ -96,14 +96,15 @@ Supporting one does not justify omitting another from the durable contract.
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                 | Basis                                                                               | Contract state                                      |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
-| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs.                                                              | Current source, docs, and tests                                                     | Current behavior                                    |
-| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                                                                             | Current source and target docs                                                      | Current behavior                                    |
-| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                                                                                   | Current source and component docs                                                   | Current ownership                                   |
-| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.                                                               | Current source and target docs                                                      | Current reachability gap; no new target is accepted |
-| FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two. | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged        |
-| FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `<li>` or another element without a compatibility decision.    | Owner decision and the caller-owned per-row interaction boundary                    | Settled intent                                      |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                               | Contract state                                      |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs.                                                                                                                                                                                                                                                              | Current source, docs, and tests                                                     | Current behavior                                    |
+| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below.                                                                                                                                                                                                                                                                                                                                                             | Current source and target docs                                                      | Current behavior                                    |
+| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target.                                                                                                                                                                                                                                                                                                                                   | Current source and component docs                                                   | Current ownership                                   |
+| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content.                                                                                                                                                                                                                                                               | Current source and target docs                                                      | Current reachability gap; no new target is accepted |
+| FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two.                                                                                                                                                                                                 | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged        |
+| FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `<li>` or another element without a compatibility decision.                                                                                                                                                                                                    | Owner decision and the caller-owned per-row interaction boundary                    | Settled intent                                      |
+| FR7 | A click on an Item row outside its Item label performs the row's action: an Item with `onClick` runs it; otherwise an Item with children toggles; otherwise an Item whose only action is its link follows that link as Enter does, with modified and middle clicks following the shared enlarged-surface rule in `family:navigation-destinations`. The Chevron and controls in Start content and End content keep their own activation, and a disabled Item does nothing. | Owner decision; `family:navigation-destinations`                                    | Settled intent; implementation may be staged        |
 
 ### Allowed variation
 
@@ -183,6 +184,16 @@ structure. Its current lack of a target is a reachability gap, not a decision
 that it must remain unthemeable. Header, Start content, and End content remain
 caller-owned even though TreeList positions their slot wrappers.
 
+### Design decisions
+
+<!-- design-decisions:v1 -->
+
+| ID  | Decision                                                                                                                     | Intent or reason                                                                                                                                                                                               | Applies to                                                                             | Allowed variation                                                                                                                                                 |
+| --- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| DD1 | Every Item spans the full width of the tree list at any depth; its nesting indent sits inside the row, ahead of its content. | Hover, pressed, and selected fills line up across depths, so the tree reads as one list of equal rows while labels keep their per-level alignment.                                                             | Item at every depth, at rest and through hover, pressed, selected, disabled, and focus | Themes set the indent step with `--tree-list-indent` and may restyle the row's fill, radius, and padding; row padding adds to the indent instead of replacing it. |
+| DD2 | A nested Item's indent area is part of the row's painted target: it shows the row's hover and press feedback.                | The whole painted row reads as one target, matching where a click acts (FR7), so no part of a row lights up apart from the rest.                                                                               | Nested Items that act on click                                                         | Themes may restyle the feedback through the `tree-list-item` target.                                                                                              |
+| DD3 | Guides paint above row fills, and an Item whose focus ring is showing paints above the guides.                               | Hierarchy lines stay continuous through hover and selection, and the focus indicator is never cut; on a focused row that is also filled, the ring takes precedence and the fill covers the guides at that row. | Guide and Item in `lineGuides` trees                                                   | Themes may recolor or hide guides through the `tree-list-guide` target.                                                                                           |
+
 ### Theming anatomy
 
 <!-- anatomy-theming:v1 -->
@@ -242,15 +253,16 @@ 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`       |
-| 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`       |
+| 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`           |
+| FR7                 | Focused `TreeList.test.tsx` row-click coverage, required with implementation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Action, parent, link, and disabled rows; clicks in the indent and padding, on the Chevron, and on Start and End content controls; plain, modified, and middle clicks | A click outside the label does nothing or runs the wrong action, a link-row click reaches ancestors twice, the Chevron or a Start or End content control activates the row, or a disabled row acts.                                                 | `audit:TreeList/behavior`      |
+| 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,