An open source design system that's fully customizable and agent ready
TypeScript
spec(a11y): TreeList adopts APG Tree View as one composite control, single caller-owned selection (#7460)
Cindy Zhang17b2fcfed5c9
diff --git a/packages/core/src/TreeList/TreeList.spec.md b/packages/core/src/TreeList/TreeList.spec.mdindex 6886d38afe..90752b774c 100644--- a/packages/core/src/TreeList/TreeList.spec.md+++ b/packages/core/src/TreeList/TreeList.spec.md@@ -148,6 +148,27 @@ The styling seam does not change TreeList's tree, treeitem, group, roving-focus,expansion, selection, disabled, or activation behavior. Styling inputs MUST NOTreplace 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, 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. Implementation gap until+ its fix ships: a parent row's name reads "Toggle children <label>" because the+ chevron button sits inside the `treeitem`; a plain row folds its description+ into its name; a row with `href` or `onClick` names and describes its inner+ control rather than the row; start and end content add their text and+ control names to the row's name; and typeahead matches the row's whole text+ rather than its label.+## Design relationships| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |@@ -227,14 +248,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` 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 supportand mutation-sensitive coverage for the item styling seam may land separately,@@ -261,6 +283,15 @@ Rejected: applying the seam to the outer semantic `<li>`. That element owns treesemantics and child grouping, while the row box is the stable visual and hoverboundary 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 questionsNone.