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

package/src/TopNav/TopNavMenu.spec.md

@@ -0,0 +1,195 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TopNavMenu
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-25
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/TopNav/TopNavMenu.test.tsx,
+    packages/core/src/hooks/useMenuHover.test.tsx,
+    apps/storybook/stories/TopNavMenu.stories.tsx,
+  ]
+modules: []
+families: [family:navigation-destinations, family:overlay-dismissal]
+design_specs: [design:reduced-motion]
+architecture:
+  [
+    architecture:interaction-modality,
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: []
+---
+
+# TopNavMenu component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                     |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `TopNavMenu` with `label`, `items` (`{title, description?, icon?, href?, onClick?}`), `delay` (150), and `hideDelay` (200); target `top-nav-menu`.                                           |
+| Behavior                | In the bar, a button that opens a menu of rich items on hover or click, with APG menu keyboard support. In the drawer, a disclosure that expands its items inline. Hidden in the mobile bar. |
+| End-user impact         | Mouse users preview destinations on hover; keyboard users move through items with arrows and typeahead; drawer users expand the group in place.                                              |
+| Builder impact          | None.                                                                                                                                                                                        |
+| Compatibility/readiness | Records shipped behavior; no public change. Three current-state gaps (see Current-state impact).                                                                                             |
+| Review checks           | Reject wrapping the popup in a modal dialog, more than one tab stop among items, a collapsed drawer group that stays reachable, or caller trigger handlers that replace the built-in ones.   |
+| Governing rules         | `architecture:public-component-api` INV5 and INV7; `architecture:interaction-modality`; `component:TopNav` render modes.                                                                     |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TopNavMenu is a TopNav entry that groups several destinations under one label.
+It owns the trigger, the hover or click menu popover in the bar, and the
+expandable group in the mobile drawer. Consumer usage lives in
+`TopNavMenu.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: open and expanded states are internal
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Drawer action items are not keyboard operable.** A drawer item with only
+  `onClick` renders a link without `href`, so keyboard users cannot reach or
+  activate it. WCAG 2.1.1 and `architecture:interaction-modality` INV4 require an
+  operable keyboard path.
+- **Motion under reduced motion.** The drawer group's height, the bar and
+  drawer chevrons' rotation, the trigger's background and text color, and each
+  bar item's background color still animate when reduced motion is requested;
+  `design:reduced-motion` DR1–DR3 allow no animated property for a fine pointer
+  and only a short opacity change for touch.
+- **The drawer trigger drops the ref.** In `drawer` mode the disclosure button
+  receives the caller's other DOM props but not `ref`.
+  `architecture:public-component-api` INV8 has the ref reach the element the
+  contract promises.
+
+## Ownership boundary
+
+**Owns**
+
+- The trigger button, the menu popover and its items, keyboard handling, and the
+  drawer group (FR1–FR10).
+
+**Does not own / non-goals**
+
+- Destination acceptance and blocking for every `href` this component renders —
+  owned by `family:navigation-destinations`.
+- Render mode and slot — owned by `component:TopNav`.
+- Popover positioning, native light dismiss, and layer hosting — owned by the
+  shared popover and layer runtime.
+- Rich panel layouts — owned by `component:TopNavMegaMenu`.
+
+## Public concepts
+
+| Concept   | Closed values or states                                    | Meaning                    | Availability by variant/orientation/state | Default | Owner                  | Stability | Invalid-value behavior               |
+| --------- | ---------------------------------------------------------- | -------------------------- | ----------------------------------------- | ------- | ---------------------- | --------- | ------------------------------------ |
+| Menu item | `title`, optional `description`, `icon`, `href`, `onClick` | One destination or action. | Bar and drawer.                           | —       | `component:TopNavMenu` | Stable    | A rejected `href` renders no `href`. |
+
+## Behavioral and layout contract
+
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                              | Basis                    |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1  | In `default` mode the trigger is a `<button>` showing `label` and a chevron that turns when open; it carries `top-nav-menu`, the forwarded `ref`, and other DOM props, and announces a menu popup with its expanded state.                                                                                                                                             | Current source and tests |
+| FR2  | On a hover-capable pointer, hovering the trigger opens the menu after `delay` ms and leaving the trigger and the menu closes it after `hideDelay` ms; a hover-open does not move focus. A click opens the menu and moves focus to the first item; a click within 500 ms of a hover-open keeps it open.                                                                 | Current source and tests |
+| FR3  | The popup is a non-modal popover below the trigger, aligned to the trigger's TopNav slot (start, center, or end). It contains one `role="menu"` named by `label`, followed by a close button named by `@astryx.popover.close` that stays visually hidden until it holds focus.                                                                                         | Current source and tests |
+| FR4  | Each item is a `role="menuitem"`: an `<a>` when `href` is set (rendering its `href` only when the URL is accepted), else a `div`. Bar items render a native `<a>`, not the `LinkProvider` link. It shows an icon box, the title, and the description, and runs the item's `onClick` on activation.                                                                     | Current source and tests |
+| FR5  | Items use a roving tab index with exactly one tab stop. ArrowDown and ArrowUp move focus and wrap at both ends; typing a character moves to the matching item; Enter or Space activates the focused item; Escape closes the menu and returns focus to the trigger.                                                                                                     | APG menu pattern; tests  |
+| FR6  | Caller `onClick`, `onMouseEnter`, and `onMouseLeave` on the trigger run before the built-in open behavior and compose with it instead of replacing it; a caller handler that calls `preventDefault()` cancels the built-in open or toggle for that event. Caller attributes never override the popup wiring.                                                           | Current source and tests |
+| FR7  | In `drawer` mode the trigger is a full-width disclosure button with `aria-expanded` and `aria-controls`; activating it toggles the group. Collapsed items are `inert` and `aria-hidden`, and the group clips while collapsed and while it expands, and stops clipping once fully expanded. Without a reduced-motion preference, expansion animates the group's height. | Current source and tests |
+| FR8  | Drawer items render through the `LinkProvider` link component; activating one runs the item's `onClick` and then closes the AppShell drawer.                                                                                                                                                                                                                           | Current source           |
+| FR9  | In `mobile-bar` mode TopNavMenu renders nothing.                                                                                                                                                                                                                                                                                                                       | Current source           |
+| FR10 | The trigger, each bar item, and each drawer control paint the shared focus outline.                                                                                                                                                                                                                                                                                    | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Timing.** `delay` and `hideDelay` vary per caller.
+
+### Representative states
+
+| State            | Required invariant                                | Allowed variation |
+| ---------------- | ------------------------------------------------- | ----------------- |
+| Closed           | Trigger with collapsed state.                     | Theme styling.    |
+| Hover-open       | Menu open; focus does not move.                   | Delay.            |
+| Click-open       | Menu open; focus on the first item.               | —                 |
+| Drawer collapsed | Items inert and hidden from assistive technology. | —                 |
+| Drawer expanded  | Items reachable; activation closes the drawer.    | Animation.        |
+
+### Transformation and precedence order
+
+- **ORD1 — Trigger handlers.** Caller handler first, then the built-in handler
+  (FR6).
+
+### Performance and resources
+
+- **PR1 — Timers.** Hover timers clear on close and on unmount.
+
+## Accessibility contract
+
+- **AR1 — Menu semantics.** The popup is not a modal dialog; the trigger
+  announces a menu popup; items are `menuitem`s inside one named `menu`.
+- **AR2 — Keyboard.** FR5's keys follow the APG menu pattern.
+- **AR3 — Drawer disclosure.** The drawer trigger exposes its expanded state and
+  controls the group; collapsed items are unreachable.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                  | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Trigger          | Bar-item styling with a chevron.    | Current source and public docs | Prominent      | FR1                |
+| Menu item        | Icon box, title, description.       | Current source and public docs | Supporting     | FR4                |
+| Drawer group     | Disclosure row with indented items. | Current source                 | Supporting     | FR7                |
+
+`TopNavMenu.doc.mjs` declares no anatomy of its own, so no anatomy-theming map is
+recorded.
+
+## Family and system relationships
+
+- `family:overlay-dismissal` owns Escape and close-request ordering for this
+  component's popover.
+- `family:navigation-destinations` owns the accept/block decision for each
+  destination this component renders.
+- `component:TopNav` supplies the render mode and slot.
+- `architecture:public-component-api` INV5 and INV7 govern forwarding and
+  handler composition.
+- `architecture:interaction-modality` provides the shared focus indicator.
+
+## Verification map
+
+| Contract          | Verification                                               | Representative states                           | Mutation or failure expectation                                               | Audit section                    |
+| ----------------- | ---------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------- |
+| FR1, FR3, AR1     | `TopNavMenu.test.tsx` trigger and semantics tests          | Closed and open                                 | A dialog wrapper or wrong popup type fails.                                   | `audit:TopNavMenu/accessibility` |
+| FR4, FR5, AR2     | `TopNavMenu.test.tsx` keyboard tests                       | Arrows, wrap, typeahead, Enter, Escape          | Extra tab stops or lost activation fails.                                     | `audit:TopNavMenu/accessibility` |
+| FR6               | `TopNavMenu.test.tsx` pass-through and owned-handler tests | Bar and drawer triggers                         | A replaced built-in handler or lost prop fails.                               | `audit:TopNavMenu/behavior`      |
+| FR7, FR10, AR3    | `TopNavMenu.test.tsx` drawer tests                         | Collapsed and expanded                          | Reachable collapsed items or a missing ring fails.                            | `audit:TopNavMenu/behavior`      |
+| Shared menu focus | `useMenuHover.test.tsx`                                    | Hover-open, click-open, Escape, Enter and Space | Focus moved on hover, not moved in on click, or not returned on Escape fails. | `audit:TopNavMenu/accessibility` |
+
+Read from source, with no focused test yet: the visually hidden close button after the menu (FR3); the native `<a>` for bar items, the icon box, and the description (FR4); the forwarded `ref`, the `top-nav-menu` target, and the bar and drawer chevrons' turn (FR1, FR7); the drawer group's clipping while it expands and its height animation (FR7); the caller `preventDefault()` cancellation (FR6); hover opening and closing with `delay` and `hideDelay` (FR2); slot alignment (FR3); FR8; FR9; and the bar trigger and item parts of FR10.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+- **OQ1 — Should bar menu items render through the `LinkProvider` link, as the
+  drawer items do?** (`human-api`) Today bar items render a native `<a>` and
+  drawer items the `LinkProvider` link (FR4, FR8).
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, or popover
+mechanics. It links to their owners.

package/src/TopNav/__tests__/TopNavMobileLongHeading.a11y.chromium.spec.ts

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

package/src/TreeList/TreeList.doc.mjs

@@ -118,6 +118,12 @@ export const docs = {
             'Visual treatment of the hierarchy guide lines. lineGuides shows connector lines; noGuides hides them, keeping indentation. Orthogonal to density.',
           default: "'lineGuides'",
         },
+        {
+          name: 'animatedLayout',
+          type: 'AnimatedLayout',
+          description:
+            'The handle from useAnimatedLayout({containerRef}). With it, expanding or collapsing a row glides the rows and content after it, up to that container, on one shared motion role instead of jumping, and the shown rows and the chevron move on the same motion. Without it, the content after the row takes its place at once.',
+        },
         {
           name: 'header',
           type: 'ReactNode',
@@ -199,6 +205,12 @@ export const docsZh = {
             '层级引导线的视觉呈现。lineGuides 显示连接线；noGuides 隐藏连接线并保留缩进。与 density 正交。',
           default: "'lineGuides'",
         },
+        {
+          name: 'animatedLayout',
+          type: 'AnimatedLayout',
+          description:
+            'useAnimatedLayout({containerRef}) 返回的句柄。传入后，展开或收起一行时，该行之后直到该容器内的行和内容会以同一个共享动效角色平滑移动，而不是跳动；新显示的行和箭头也使用同一动效。不传时，该行之后的内容会立即就位。',
+        },
         {
           name: 'header',
           type: 'ReactNode',
@@ -248,6 +260,7 @@ export const docsDense = {
     items: 'Recursive tree item data w/ id, label, optional children + isExpanded, plus optional xstyle/className/style on its row.',
     density: 'Spacing density for items.',
     variant: 'Guide-line treatment: lineGuides shows connectors, noGuides hides them (indent kept). Orthogonal to density.',
+    animatedLayout: 'handle from useAnimatedLayout({containerRef}); expand/collapse glides the content after the row inside that container on one shared motion role. Omit: content after the row snaps.',
     header: 'Header content, linked to tree via aria-labelledby.',
     xstyle: 'StyleX styles for layout. Must be stylex.create() value.',
   },

package/src/TreeList/TreeList.spec.md

@@ -26,22 +26,23 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: [spec:AST-002/DEC-1, spec:AST-005/DEC-1]
+system_specs:
+  [spec:AST-002/DEC-1, spec:AST-005/DEC-1, spec:AST-094/FR4, spec:AST-105]
 ---
 
 # TreeList component contract
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                                 |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | Each `TreeListItemData` may carry the standard `className`, `style`, and `xstyle` styling inputs for its Item row.                                                                                                                                                       |
-| Behavior                | All supplied styling inputs compose on the same Item row box—the element that paints the row, owns its hover state, and contains its visible content. They do not target the outer semantic `<li>`.                                                                      |
-| End-user impact         | A builder can reveal or style content for one row without causing every row in the tree to react.                                                                                                                                                                        |
-| Builder impact          | The three standard styling mechanisms remain interchangeable parts of one row-styling seam. A builder may use one or combine them; no existing callsite must opt in.                                                                                                     |
-| Compatibility/readiness | The contract is additive and preserves default output. Its authority is current; implementation support may arrive separately, but the durable API is incomplete until all three mechanisms are supported on the same row.                                               |
-| Review checks           | Reject an implementation that omits one mechanism from the durable API, sends the mechanisms to different elements, drops a supplied value, targets the semantic `<li>`, or moves the promised row target without an explicit compatibility decision.                    |
-| Governing rules         | [Public component API INV5–INV6](../../../../docs/architecture/public-component-api.md) and [AST-002 FR1, FR4, FR7–FR10, FR12, and DEC-1](../../../../docs/specs/AST-002/spec.md) govern admission, predictability, and composition of the component-local styling seam. |
+| Area                    | Contract                                                                                                                                                                                                                                                                     |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | Each `TreeListItemData` may carry the standard `className`, `style`, and `xstyle` styling inputs for its Item row.                                                                                                                                                           |
+| Behavior                | All supplied styling inputs compose on the same Item row box—the element that paints the row, owns its hover state, and contains its visible content. They do not target the outer semantic `<li>`.                                                                          |
+| End-user impact         | A builder can reveal or style content for one row without causing every row in the tree to react.                                                                                                                                                                            |
+| Builder impact          | The three standard styling mechanisms remain interchangeable parts of one row-styling seam. A builder may use one or combine them; no existing callsite must opt in.                                                                                                         |
+| Compatibility/readiness | The contract is additive and preserves default output, except FR8's group motion under a coarse pointer. Its authority is current; implementation support may arrive separately, but the durable API is incomplete until all three mechanisms are supported on the same row. |
+| Review checks           | Reject an implementation that omits one mechanism from the durable API, sends the mechanisms to different elements, drops a supplied value, targets the semantic `<li>`, or moves the promised row target without an explicit compatibility decision.                        |
+| Governing rules         | [Public component API INV5–INV6](../../../../docs/architecture/public-component-api.md) and [AST-002 FR1, FR4, FR7–FR10, FR12, and DEC-1](../../../../docs/specs/AST-002/spec.md) govern admission, predictability, and composition of the component-local styling seam.     |
 
 This table is a review projection; the body below is authoritative.
 
@@ -54,9 +55,12 @@ requiring product code to reconstruct TreeList behavior.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- Compatibility class: additive optional public API; no default rendering, DOM,
-  styling, or interaction changes when the inputs are absent
+- Released default preserved: `no` under a coarse primary pointer, where a
+  toggled group slides (FR8); fine pointers are unchanged without an
+  `animatedLayout` handle
+- Compatibility class: additive optional public API, plus FR8's group motion
+  under a coarse pointer; no other default rendering, DOM, styling, or
+  interaction changes when the inputs are absent
 - Controlled/uncontrolled behavior: unchanged
 - Migration decision: none; existing callsites remain valid
 
@@ -87,24 +91,27 @@ the accepted API direction. Consumer syntax and release timing belong in
 
 ## Public concepts
 
-| Concept          | Closed values or states               | Meaning                                                                                        | Availability by variant/orientation/state | Default | Owner                | Stability | Invalid-value behavior                                          |
-| ---------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | ------- | -------------------- | --------- | --------------------------------------------------------------- |
-| Item row styling | `className`, `style`, and/or `xstyle` | Applies caller-supplied classes, inline styles, or StyleX styles to one item's stable row box. | Every rendered item row                   | Absent  | `component:TreeList` | Stable    | TypeScript rejects unsupported values; supplied inputs compose. |
+| Concept          | Closed values or states               | Meaning                                                                                                           | Availability by variant/orientation/state | Default                                               | Owner                | Stability | Invalid-value behavior                                          |
+| ---------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------------- | -------------------- | --------- | --------------------------------------------------------------- |
+| Item row styling | `className`, `style`, and/or `xstyle` | Applies caller-supplied classes, inline styles, or StyleX styles to one item's stable row box.                    | Every rendered item row                   | Absent                                                | `component:TreeList` | Stable    | TypeScript rejects unsupported values; supplied inputs compose. |
+| Animated layout  | absent, a `useAnimatedLayout` handle  | Whether expanding and collapsing a row glide the content after it, up to the handle's container (`spec:AST-105`). | Every tree                                | Absent: content after the row takes its place at once | `spec:AST-105`       | Stable    | TypeScript rejects unsupported values.                          |
 
 The three mechanisms are one styling concept, not three separate feature tiers.
 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                                      |
-| 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        |
+| 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        |
+| FR8 | Expanding or collapsing an Item with children MUST play its group's own motion: under a coarse primary pointer its rows slide out from under the parent as one block, clipped to the group's box, and back on collapse, a collapsing group's rows leaving the accessibility tree as the slide starts, while the Chevron turns, by transform only (`spec:AST-094` FR4–FR5); under a fine pointer the group appears and leaves at once. With an `animatedLayout` handle, the group and the rows after it follow `spec:AST-105`'s shared motion under every pointer (FR4, FR5); without one, the group's own slide stays touch-only and the rows after the group take their places at once (`spec:AST-105` FR2). | UIKit outline list (`UICollectionView`), iOS 26.2; `spec:AST-105` FR2               | Proposed; awaiting an engineering owner's approval  |
+| FR9 | `TreeList` MUST accept `animatedLayout?: AnimatedLayout`. With a handle, expanding and collapsing a row report the row's size change through it, so the content after the row glides inside the handle's container, and the shown rows and the row's Chevron move on the same motion (`spec:AST-105` FR1–FR4; `spec:AST-108` FR4a). Without one, expanding and collapsing follow FR8. The prop MUST NOT change tree semantics or keyboard behavior.                                                                                                                                                                                                                                                           | `spec:AST-105` FR1, FR2; `spec:AST-108` FR4a                                        | Current behavior                                    |
 
 ### Allowed variation
 
@@ -118,6 +125,10 @@ Supporting one does not justify omitting another from the durable contract.
 - **AV4 — Row implementation.** The row's HTML tag and internal descendants may
   change while the same logical row remains the target of all three styling
   inputs and keeps the observable boundary in FR6.
+- **AV5 — Expansion motion.** Without an `animatedLayout` handle, under a fine
+  pointer a group appears and leaves at once; under reduced motion nothing travels: under a coarse primary
+  pointer the group fades in where it lands and out where it is (DR2), and
+  otherwise it changes at once (`design:reduced-motion` DR3).
 
 ### Representative states
 
@@ -127,6 +138,7 @@ Supporting one does not justify omitting another from the durable contract.
 | Flat items               | Each Item contains an Item label.                                                           | Description and consumer slots may be absent. |
 | Styled item              | The supplied `className`, `style`, and `xstyle` values compose on only that item's row box. | Any subset of the three inputs may be absent. |
 | Expandable item          | Item may contain Chevron and delegated Chevron glyph.                                       | Expanded or collapsed state.                  |
+| Item toggled by a finger | Its group slides out from under it, or back, as one block while the Chevron turns.          | Reduced motion: a fade, no travel.            |
 | Nested `lineGuides` tree | Guide instances show parent-child relationships.                                            | Count and position follow hierarchy.          |
 | `noGuides` tree          | Guide instances are absent; indentation remains.                                            | All other anatomy remains unchanged.          |
 | Described item           | Item description renders below Item label.                                                  | Caller-provided description text.             |
@@ -250,19 +262,23 @@ authorize or prohibit a future target.
   item paths to preserve that result.
 - TreeList's current custom-router path inherits the `useLinkComponent` adoption
   gap recorded by the family until the accepted implementation lands.
+- `spec:AST-105` owns the animated layout handle and how the content after a
+  toggled group moves; TreeList owns only the group's own motion (FR8).
 
 ## 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`           |
-| 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`       |
+| 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`      |
+| FR8                 | Real-browser frame evidence under a finger and a mouse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | expand and collapse; a toggle mid-motion; reduced motion; rows after the group, with and without an `animatedLayout` handle                                          | Rows inside the group that jump, travel under a fine pointer without a handle or under reduced motion, an animated property under a fine pointer with reduced motion, a fade under a mouse without a handle, collapsing rows still in the accessibility tree during the slide, layout or paint per frame, or rows after the group moving without a handle fails | `audit:TreeList/behavior`      |
+| FR9                 | `animatedLayoutAdopters.test.tsx` (with and without a handle; `isExpanded` changed in `items` glides; the collapsing group kept inert and out of the keyboard order until its exit ends) and `animatedLayoutAdopters.interaction.browser.spec.ts` (the `Core/Animated layout` story through a ScrollableArea ref, expanding and collapsing)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | No handle; a handle; click, keyboard, and `items`-driven changes; expanding and collapsing                                                                           | The rows after a row jump with a handle, an `items` change lands at once, a collapsing group vanishes before its exit or its rows stay focusable during it, or anything changes without a handle                                                                                                                                                                | `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,