Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(AST-105, Resizable, LayoutPanel, SideNav): one shared edge reveal; a resizable LayoutPanel slides on collapse and open; focus leaves a collapsing panel (#8783)

Cindy Zhang0fa02074f901
diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md
index 52c90483f3..62b5ba172f 100644
--- a/docs/architecture/react-component-runtime.md
+++ b/docs/architecture/react-component-runtime.md
@@ -195,11 +195,20 @@ those contracts.
transient copy of the old content (`spec:AST-105` FR8). Two Core components hold their own handle
for their own change: AppShell's content area and the SideNav rail, during a
side nav collapse or expand (`component:AppShell` FR17, `component:SideNav`
- FR6), each making its copy through the swap. The module may also play
+ FR6), each making its copy through the swap. A resize controller also holds
+ its own handle for a LayoutPanel's collapse and open, with no copy
+ (`component:Resizable` FR8). The module may also play
caller-supplied frames on elements the page already renders, on the one
shared motion, with no copy, releasing them when the motion ends; AppShell's
content surface uses this to cover an expand's gap when its old wrap is not
- copied. Neither is public
+ copied. The module also produces `spec:AST-105` FR9's edge reveal, the one
+ edge reveal in Core: Collapsible, TreeList and Table's row expansion
+ (`component:Table` FR15) use its block-end form, the SideNav rail
+ uses its inline-edge two-state form and keeps only its labels' and icons'
+ fades of its own, and a resizable LayoutPanel's pane uses it on collapse and
+ open, moving the content on its moving edge's side, the resize controller measuring the pane's box before and after its
+ collapse state commits and playing from the edge its direction names
+ (`component:Resizable` FR8, `component:LayoutPanel` FR7). None of these is public
(`architecture:component-style-authoring` INV7). The module follows INV3
and INV5.
- **INV13 — One shared set of internal touch modules.** Core's touch
diff --git a/docs/families/layout-regions.md b/docs/families/layout-regions.md
index a3cd865d2b..e9d1234a8b 100644
--- a/docs/families/layout-regions.md
+++ b/docs/families/layout-regions.md
@@ -87,7 +87,10 @@ wrapper, or a header-like visual treatment.
painted surface, variant, and selected divider edges to Section.
- `architecture:container-padding` owns inherited inset and bleed mechanics.
- useResizable and ResizeHandle own resize state and interaction. LayoutPanel
- only accepts their current size as an alternative width owner.
+ accepts their current size as an alternative width owner, lends its element
+ to the resize controller for the edge reveal on collapse and open, and owns
+ the focus move and inert state of a collapsing panel
+ (`component:LayoutPanel` FR7, AR2).
## Canonical concepts
diff --git a/docs/specs/AST-105-animated-layout/spec.md b/docs/specs/AST-105-animated-layout/spec.md
index e15e1de56d..cb4addf33b 100644
--- a/docs/specs/AST-105-animated-layout/spec.md
+++ b/docs/specs/AST-105-animated-layout/spec.md
@@ -14,7 +14,7 @@ affects_architecture: [architecture:react-component-runtime]
affects_families: []
affects_contributing: []
affects_consumer_docs:
- [useAnimatedLayout, TreeList, Collapsible, useTableRowExpansion]
+ [useAnimatedLayout, TreeList, Collapsible, useTableRowExpansion, LayoutPanel]
---
# Animated layout system spec
@@ -68,8 +68,10 @@ const animatedLayout = useAnimatedLayout({containerRef: scrollRef});
keeps its behavior: the changed element shows its change as its own record
says, and content after it takes its place at once. AppShell's content area and
the SideNav rail animate their own change during a side nav collapse or
- expand, as their records state (`component:AppShell` FR17, `component:SideNav`
- FR6).
+ expand, and a resizable pane a LayoutPanel renders animates its own collapse
+ and open, as their records state (`component:AppShell` FR17,
+ `component:SideNav` FR6, `component:Resizable` FR8, `component:LayoutPanel`
+ FR7).
- **FR3 — The content after a change glides within the area.** For any change
a component holding the handle reports, such as a disclosure opening,
content loading in, a message appearing, or an item inserted or removed,
@@ -121,27 +123,66 @@ const animatedLayout = useAnimatedLayout({containerRef: scrollRef});
(`component:SideNav` FR6).
The swap is internal; the hook's public contract is unchanged.
+- **FR9 — One shared edge reveal.** An area can reveal or conceal an element
+ from one of its edges: its block-end edge by default, or its block-start,
+ inline-start or inline-end edge, such as a panel collapsing beside content.
+ The reveal measures the element's box before and after the change, as FR3
+ measures any change, and the element's moving edge and the content on that
+ edge's side move on FR4's one motion, whether that content comes after the
+ element or before it (an end panel's LayoutContent comes before the panel),
+ so the content beside the edge glides with it and no gap opens. An optional
+ two-state form holds the element's old state as FR8's swap holds it, while
+ the element rides the glide of the content beside its moving edge; a reversal
+ from the shown state springs from where it is. Under Reduce Motion it follows
+ `design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise.
+ Every edge reveal in Core is this one:
+ - Collapsible, TreeList and Table's row expansion keep its block-end form
+ (`component:Collapsible`, `component:TreeList`, `component:Table` FR15).
+ - The SideNav rail conceals and reveals by its inline edge in the two-state
+ form, and keeps only its labels' and icons' fades of its own
+ (`component:SideNav` FR6).
+ - A resizable pane that a LayoutPanel renders conceals and reveals by the edge
+ facing its ResizeHandle each time it collapses or opens, and LayoutContent
+ beside it moves on the same motion (`component:Resizable` FR8,
+ `component:LayoutPanel` FR7). A drag that crosses the collapse threshold plays
+ the conceal; a drag that reopens a collapsed pane plays nothing, because the
+ pointer drives the edge. A pane the caller renders at `useResizable`'s size
+ alone shows no reveal, because Core never holds that element, and so does
+ a LayoutPanel given the configuration-object form, a hand-built
+ `ResizableProps` object that `useResizable` did not return; the hook's own
+ `props` passed through `resizable` slide.
+
+ When a resizable pane a LayoutPanel renders collapses and focus is inside
+ it, focus moves to its ResizeHandle, the control that opens it again, and
+ the collapsed pane is inert and hidden from assistive technology until it
+ opens, under any resize controller (`component:LayoutPanel` AR2);
+ opening moves no focus. This focus rule covers only a collapsing pane: the
+ SideNav rail follows its own record, and Collapsible, TreeList and Table's
+ row expansion keep their records' behavior. The edge reveal is internal: `useAnimatedLayout`'s public
+ contract is unchanged, and no prop or option is added.
+
## Coverage
What moves inside an area, each case with its test:
-| Case | Behavior | Test |
-| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| Normal-flow block siblings after the changed element, at each ancestor level up to the area | Moves when its rectangle changed | Nested changed element with block siblings at three levels |
-| An element with `display: contents` | Has no box; its children are taken in its place | A following `display: contents` wrapper with two children |
-| Absolutely positioned or fixed elements | Skipped and take their final place; an absolute child of a moving element rides with it | One of each, plus an absolute badge on a moving row |
-| Content inside an absolutely positioned, fixed, stuck sticky or top-layer ancestor of the change | Only the content after the change moves; that ancestor, the ancestors inside it and the siblings before the change take their final place | A header above a card around the change in a bottom-docked panel, and a bottom-stuck sticky footer around the change |
-| Sticky elements | In flow while unstuck, so moves when its rectangle changed; a stuck element takes its final place | A sticky header above and below its stuck point |
-| Floats | Moves when its rectangle changed | A float after the changed element |
-| Flex and grid items after the changed element, including wrap and row direction | Moves when its rectangle changed | A wrapping flex row and a row-direction neighbor that does not shift |
-| Siblings before the changed element, and its ancestors, at each level | Moves when its rectangle changed: a centered, end-aligned or space-between row, a centered column, or `order` among the siblings near the visible part moves them | A centered row, a space-between row, an end-aligned row, a centered column and an `order`-placed sibling |
-| Hidden, `display: none`, or zero-size elements | Skipped | One of each after the changed element |
-| Changed elements outside the area's visible part | Take their final place without animation | A long list with changed rows above and below the fold |
-| Elements under a scaled or transformed ancestor | Moves by its layout change, corrected for the ancestor's scale | A moving row inside a scaled panel |
-| Portals and top-layer content | Never moved | A popover open from a following row |
-| Elements already moving | Keep their running motion and add the new move to it | Two changes 100 ms apart |
-| Nested areas | Motion stops at the area of the handle the changed component holds; an inner area moves as one unit within an outer one | An area inside an area, changed in the inner one |
-| Table rows after an opening or closing detail row | The rows glide; a closing detail row hides at once, and its space is held while the rows after it glide up. A table that draws column lines (`component:Table` FR15) does not glide: it and the content after it take their final places at once | A detail row opening and closing in a table with a pinned column, and in a table with column lines |
+| Case | Behavior | Test |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Normal-flow block siblings after the changed element, at each ancestor level up to the area | Moves when its rectangle changed | Nested changed element with block siblings at three levels |
+| An element with `display: contents` | Has no box; its children are taken in its place | A following `display: contents` wrapper with two children |
+| Absolutely positioned or fixed elements | Skipped and take their final place; an absolute child of a moving element rides with it | One of each, plus an absolute badge on a moving row |
+| Content inside an absolutely positioned, fixed, stuck sticky or top-layer ancestor of the change | Only the content after the change moves; that ancestor, the ancestors inside it and the siblings before the change take their final place | A header above a card around the change in a bottom-docked panel, and a bottom-stuck sticky footer around the change |
+| Sticky elements | In flow while unstuck, so moves when its rectangle changed; a stuck element takes its final place | A sticky header above and below its stuck point |
+| Floats | Moves when its rectangle changed | A float after the changed element |
+| Flex and grid items after the changed element, including wrap and row direction | Moves when its rectangle changed | A wrapping flex row and a row-direction neighbor that does not shift |
+| Siblings before the changed element, and its ancestors, at each level | Moves when its rectangle changed: a centered, end-aligned or space-between row, a centered column, or `order` among the siblings near the visible part moves them | A centered row, a space-between row, an end-aligned row, a centered column and an `order`-placed sibling |
+| Hidden, `display: none`, or zero-size elements | Skipped | One of each after the changed element |
+| Changed elements outside the area's visible part | Take their final place without animation | A long list with changed rows above and below the fold |
+| Elements under a scaled or transformed ancestor | Moves by its layout change, corrected for the ancestor's scale | A moving row inside a scaled panel |
+| Portals and top-layer content | Never moved | A popover open from a following row |
+| Elements already moving | Keep their running motion and add the new move to it | Two changes 100 ms apart |
+| Nested areas | Motion stops at the area of the handle the changed component holds; an inner area moves as one unit within an outer one | An area inside an area, changed in the inner one |
+| Table rows after an opening or closing detail row | The rows glide; a closing detail row hides at once, and its space is held while the rows after it glide up. A table that draws column lines (`component:Table` FR15) does not glide: it and the content after it take their final places at once | A detail row opening and closing in a table with a pinned column, and in a table with column lines |
+| An edge reveal or conceal on either axis | Content revealed or concealed from its block-end edge (default), its block-start edge or an inline edge, with an optional two-state form where the swap holds the old state and the element rides the glide of the content beside its moving edge; the content on the moving edge's side moves, before or after the element; a resizable LayoutPanel pane on collapse and open; focus inside a collapsing LayoutPanel pane moves to its ResizeHandle (FR9) | Animated-layout browser tests of a block-end reveal and conceal, a block-start reveal and conceal (a panel opening above the content after it), an inline-start and an inline-end reveal and conceal (an end panel, with its LayoutContent before it), of the two-state form, of a LayoutPanel pane collapsing and opening by toggle, Enter and a drag past the threshold, and of focus leaving a concealed pane (pending) |
Out of coverage, each taking its final place at once:
@@ -170,16 +211,20 @@ Out of coverage, each taking its final place at once:
- `architecture:react-component-runtime` INV12 produces the glide.
- `architecture:react-component-runtime` INV12 also gains the in-place swap
(FR8); no component swaps yet.
+- INV12 also produces the edge reveal (FR9). SideNav's rail clip and ride move
+ into it from SideNav's own code, and a resizable LayoutPanel's collapse and
+ open, which today jump, adopt it; LayoutPanel's docs say a collapse slides.
## Verification
-| Contract | Verification | Representative states | Mutation or failure expectation |
-| ------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1, FR2 | Unit and browser tests with and without a handle | a handle on TreeList; no handle; a ScrollableArea ref | a handle with public members, behavior that changes without a handle, or ScrollableArea registering itself fails |
-| FR3, Coverage | Real-browser tests, one per Coverage row | each Coverage row; mixed Astryx and plain content; two changes in one frame; an area scrolled mid-list | an element that behaves other than its row says, an element moved twice for one frame, content past the area that moves, or the area scrolling fails |
-| FR4 | Real-browser frame capture under a coarse and a fine pointer, with and without Reduce Motion | a changed element and its visible followers | starting on different frames or reading different motion, a component-specific timing, or Reduce Motion applied to one and not the other fails |
-| FR5 | Fine-pointer before-and-after evidence on each adopting pull request, from the component's Storybook story | a mouse on each adopting component | a glide missing under a mouse, or an adopting pull request without that evidence, fails |
-| FR8 | Unit tests of the swap and real-browser proofs of its adopters | a fast load, a slow load, a forward and a back page change, Reduce Motion | an empty area during a swap, a placeholder flashed for a fast load, travel under Reduce Motion, a layer exit played by it, or a public export fails |
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| FR1, FR2 | Unit and browser tests with and without a handle | a handle on TreeList; no handle; a ScrollableArea ref | a handle with public members, behavior that changes without a handle, or ScrollableArea registering itself fails |
+| FR3, Coverage | Real-browser tests, one per Coverage row | each Coverage row; mixed Astryx and plain content; two changes in one frame; an area scrolled mid-list | an element that behaves other than its row says, an element moved twice for one frame, content past the area that moves, or the area scrolling fails |
+| FR4 | Real-browser frame capture under a coarse and a fine pointer, with and without Reduce Motion | a changed element and its visible followers | starting on different frames or reading different motion, a component-specific timing, or Reduce Motion applied to one and not the other fails |
+| FR5 | Fine-pointer before-and-after evidence on each adopting pull request, from the component's Storybook story | a mouse on each adopting component | a glide missing under a mouse, or an adopting pull request without that evidence, fails |
+| FR8 | Unit tests of the swap and real-browser proofs of its adopters | a fast load, a slow load, a forward and a back page change, Reduce Motion | an empty area during a swap, a placeholder flashed for a fast load, travel under Reduce Motion, a layer exit played by it, or a public export fails |
+| FR9 | Unit tests of the reveal's measurement and real-browser frame capture of each adopter | Collapsible opening; the SideNav rail collapsing and expanding; a start and an end LayoutPanel collapsing and opening by toggle, Enter, the grow arrow, a controlled change and a drag past the threshold; a drag reopening a pane; a hook-only pane; focus inside a collapsing pane; Reduce Motion | a gap opening beside a moving edge, two motions for one rail collapse, a reveal during a drag that reopens a pane, a reveal on a hook-only pane, focus left inside a concealed pane, a concealed pane reachable by Tab, or a public export fails |
## Decision log
diff --git a/packages/core/src/Layout/LayoutPanel.spec.md b/packages/core/src/Layout/LayoutPanel.spec.md
index 6a74d0688d..0561250862 100644
--- a/packages/core/src/Layout/LayoutPanel.spec.md
+++ b/packages/core/src/Layout/LayoutPanel.spec.md
@@ -27,22 +27,22 @@ architecture:
architecture:public-component-api,
]
contributing: []
-system_specs: []
+system_specs: [spec:AST-105]
---
# LayoutPanel component contract
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `children`, `width`, `resizable`, `hasDivider`, `isScrollable`, `padding`, `label`, `role`, root `BaseProps`, and a root `ref`. |
-| Behavior | A fixed-width side region at logical start or end that scrolls by default, with an optional divider on its content-facing edge. |
-| End-user impact | People see a side panel that keeps its width, scrolls on its own, and mirrors to the other side in right-to-left. |
-| Builder impact | None; the record describes shipped behavior. |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact. |
-| Review checks | Reject a divider on the outer edge, a panel that shrinks, an inferred landmark, `width` beating `resizable`, or a further publication mismatch. |
-| Governing rules | `family:layout-regions` FR1, FR2, FR4–FR8, FR10; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `children`, `width`, `resizable`, `hasDivider`, `isScrollable`, `padding`, `label`, `role`, root `BaseProps`, and a root `ref`. |
+| Behavior | A fixed-width side region at logical start or end that scrolls by default, with an optional divider on its content-facing edge. |
+| End-user impact | People see a side panel that keeps its width, scrolls on its own, and mirrors to the other side in right-to-left. |
+| Builder impact | None: no API change; a collapsing resizable panel slides with no code change. |
+| Compatibility/readiness | No API or default changes; a collapsing resizable panel slides (FR7) and moves focus out, then becomes inert (AR2): patch, `[feat]` slide and `[fix]` focus. Implementation gaps are listed under Current-state impact. |
+| Review checks | Reject a divider on the outer edge, a panel that shrinks, an inferred landmark, `width` beating `resizable`, or a further publication mismatch. |
+| Governing rules | `family:layout-regions` FR1, FR2, FR4–FR8, FR10; `architecture:container-padding`; `architecture:public-component-api` INV5–INV8. |
This table is a review projection; the body below is authoritative.
@@ -58,8 +58,11 @@ Consumer syntax and examples belong in `LayoutPanel.doc.mjs`.
- Released default preserved: `yes` — no divider, scrollable, automatic
inset, content width.
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
- target, or styling output changes.
+- Compatibility class: patch. No public prop, default, target, or styling
+ output changes. A collapsing resizable panel now slides (FR7, `[feat]`,
+ visual-only under `spec:AST-017/DEC-17`), and focus inside it moves to the
+ adjacent ResizeHandle while the collapsed panel becomes inert (DOM: `inert`
+ and `aria-hidden`; AR2, `[fix]` under `spec:AST-017` FR53).
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
@@ -77,6 +80,10 @@ Consumer migration instructions belong in consumer docs and release notes.
`hasDivider` beside a ResizeHandle that draws the same line paints the
boundary twice; nothing prevents it, so callers keep `hasDivider={false}`
when the ResizeHandle owns the line (`family:layout-regions` FR5).
+- **A collapsing panel jumps and keeps focus (FR7, AR2).** A resizable panel
+ closes and opens at once, where `spec:AST-105` FR9 slides it, and a panel
+ collapsed by app code keeps focus inside it and its controls in the tab
+ order while it is out of sight.
## Ownership boundary
@@ -106,14 +113,15 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| FR1 | LayoutPanel renders one `div` carrying the `layout-panel` target that does not shrink and holds the children directly. `width` sets its inline size, with numbers as pixels; a `resizable` value's size wins over `width`. It scrolls overflow by default; `isScrollable={false}` clips it. | Current source and tests; `family:layout-regions` FR7, FR10 |
-| FR2 | In the `start` slot the panel's content-facing edge is its inline end; in the `end` slot it is its inline start; both follow writing direction. | Current source and tests; `family:layout-regions` FR2 |
-| FR3 | Without `padding`, the panel's outer inline edge has the Layout-edge inset, a block edge with no header or footer beside it has the Layout-edge inset, and other edges have the inner inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise. A `padding` step replaces all four edges, and `0` removes them. The panel publishes container-padding values equal to the padding it applies. Implementation gap: on the automatic path it publishes the inner inset on every edge (Current-state impact). | Current source; `family:layout-regions` FR4; `architecture:container-padding` |
-| FR4 | `hasDivider` draws a 1px solid `--color-border` line on the content-facing edge; LayoutPanel does not read a Layout divider default. Without a divider and with the automatic inset, the panel overlaps the content area by the inner inset so the two share one gap. One boundary has one divider owner (`family:layout-regions` FR5). Implementation gap: nothing prevents a panel divider and an adjacent ResizeHandle line from both painting (Current-state impact). | Current source and docs; `family:layout-regions` FR5, FR6 |
-| FR5 | `role` and `label` set the root's `role` and `aria-label`; LayoutPanel adds no role of its own. | Current source and tests; `family:layout-regions` FR8 |
-| FR6 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root after the component's own attributes; `xstyle`, `className`, and `style` compose after component styles. | Current source and tests; `architecture:public-component-api` INV5–INV8 |
+| ID | Invariant | Basis |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| FR1 | LayoutPanel renders one `div` carrying the `layout-panel` target that does not shrink and holds the children directly. `width` sets its inline size, with numbers as pixels; a `resizable` value's size wins over `width`. It scrolls overflow by default; `isScrollable={false}` clips it. | Current source and tests; `family:layout-regions` FR7, FR10 |
+| FR2 | In the `start` slot the panel's content-facing edge is its inline end; in the `end` slot it is its inline start; both follow writing direction. | Current source and tests; `family:layout-regions` FR2 |
+| FR3 | Without `padding`, the panel's outer inline edge has the Layout-edge inset, a block edge with no header or footer beside it has the Layout-edge inset, and other edges have the inner inset, where the Layout-edge inset comes from the Layout's `padding`, else the nearest padding container, and the inner inset from the nearest padding container (Card, Section, Dialog, Drawer, or BottomSheet), each spacing step 4 otherwise. A `padding` step replaces all four edges, and `0` removes them. The panel publishes container-padding values equal to the padding it applies. Implementation gap: on the automatic path it publishes the inner inset on every edge (Current-state impact). | Current source; `family:layout-regions` FR4; `architecture:container-padding` |
+| FR4 | `hasDivider` draws a 1px solid `--color-border` line on the content-facing edge; LayoutPanel does not read a Layout divider default. Without a divider and with the automatic inset, the panel overlaps the content area by the inner inset so the two share one gap. One boundary has one divider owner (`family:layout-regions` FR5). Implementation gap: nothing prevents a panel divider and an adjacent ResizeHandle line from both painting (Current-state impact). | Current source and docs; `family:layout-regions` FR5, FR6 |
+| FR5 | `role` and `label` set the root's `role` and `aria-label`; LayoutPanel adds no role of its own. | Current source and tests; `family:layout-regions` FR8 |
+| FR6 | `ref` reaches the root. Supported DOM, data, ARIA, and event props reach the root after the component's own attributes; `xstyle`, `className`, and `style` compose after component styles. | Current source and tests; `architecture:public-component-api` INV5–INV8 |
+| FR7 | A LayoutPanel whose size comes from a resize controller lends its element to the controller of the ResizeHandle on its content-facing edge through an internal channel, so the panel slides closed and open by `spec:AST-105` FR9's edge reveal when its region collapses or opens: its content-facing edge (FR2) moves, and the content on that edge's side moves on the same motion (`component:Resizable` FR8). A panel given the configuration-object form, a hand-built `ResizableProps` object that `useResizable` did not return passed through `resizable`, and a panel with no resize controller, never slide; `useResizable`'s own `props` passed through `resizable` do slide. LayoutPanel adds no prop. Implementation gap: no panel slides yet (Current-state impact). | `spec:AST-105` FR9; `component:Resizable` FR8 |
### Allowed variation
@@ -122,13 +130,14 @@ Consumer migration instructions belong in consumer docs and release notes.
### Representative states
-| State | Required invariant | Allowed variation |
-| ------------------- | ------------------------------------------------------ | ----------------- |
-| Start panel | Divider and shared gap on the inline-end edge. | Width. |
-| End panel | Divider and shared gap on the inline-start edge. | Width. |
-| Right-to-left | Start and end mirror. | — |
-| Resizable | The resizable size sets the width. | Size. |
-| Navigation landmark | `role="navigation"` and the caller's name on the root. | Name. |
+| State | Required invariant | Allowed variation |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| Start panel | Divider and shared gap on the inline-end edge. | Width. |
+| End panel | Divider and shared gap on the inline-start edge. | Width. |
+| Right-to-left | Start and end mirror. | — |
+| Resizable | The resizable size sets the width. | Size. |
+| Collapsing | The panel slides closed from its content-facing edge; focus inside it moves to the ResizeHandle; it is then inert. | Start or end; Reduce Motion; configuration-object form without the slide. |
+| Navigation landmark | `role="navigation"` and the caller's name on the root. | Name. |
### Transformation and precedence order
@@ -139,13 +148,23 @@ Consumer migration instructions belong in consumer docs and release notes.
- **PR1 — No external lifecycle.** LayoutPanel reads its slot and which slots
its Layout fills, and adds no listener, observer, timer, or measurement of
- its own.
+ its own; the slide's measurement is the resize controller's (FR7).
## Accessibility contract
- **AR1 — Explicit landmarks only.** The panel is a landmark only when the
caller supplies `role`, named only by the caller's `label`
(`family:layout-regions` FR8).
+- **AR2 — Focus leaves a collapsing panel.** When a panel's region collapses
+ while focus is inside the panel, under any resize controller, the
+ configuration-object form (FR7) included, focus moves to
+ the adjacent ResizeHandle on the panel's content-facing edge, the control
+ that opens it again; the collapsed panel is then inert and `aria-hidden`
+ until it opens (`spec:AST-105` FR9). Opening moves no focus. A collapse
+ started from the Handle, or from a control outside the panel, leaves focus
+ where it is. Only the slide (FR7) excludes the configuration-object form.
+ Implementation gap: focus stays in a collapsed panel, which stays reachable
+ (Current-state impact).
## Design relationships
@@ -162,6 +181,8 @@ of its own, so no anatomy-theming block is declared here.
- `family:layout-regions` owns region direction, padding replacement,
boundary ownership, divider spacing, scrolling, landmarks, and resize
delegation; FR1–FR5 and AR1 apply them.
+- `spec:AST-105` FR9 owns the edge reveal FR7 plays and the focus rule AR2
+ applies; `component:Resizable` FR8 owns when it plays.
- `architecture:container-padding` owns inset publication; FR3 applies it and
records the gap.
- `component:Layout` owns slot placement, the Layout-edge inset, and the
@@ -169,19 +190,20 @@ of its own, so no anatomy-theming block is declared here.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| FR1, ORD1 | `LayoutSlots.test.tsx` class, width, and resizable tests | Numeric and string width; resizable | A lost `layout-panel` class, a missing width, or `width` beating `resizable` fails. Gap: the non-shrinking root, scrolling, and `isScrollable={false}` have no check. No requirement or check covers how a keyboard user reaches a scrolling panel's overflow when the panel holds no focusable content. | `audit:LayoutPanel/layout` |
-| FR2 | `LayoutSlots.test.tsx` start- and end-slot tests; `Layout.a11y.chromium.spec.ts` `start-end-navigation-rtl` state | Start and end panels; right-to-left | A panel that fails to render in either slot fails. Gap: no check asserts which edge carries the divider or the shared gap, or the mirrored placement. | `audit:LayoutPanel/layout` |
-| FR3, ORD2 | Source review | Automatic, explicit, and zero padding | Gap: no test covers the automatic per-edge inset, the `padding` replacement, full bleed, or the published values. | `audit:LayoutPanel/layout` |
-| FR4 | Source review | `hasDivider`; no divider | Gap: no test covers the divider line, the shared gap, or a panel divider beside a ResizeHandle. | `audit:LayoutPanel/layout` |
-| FR5, AR1 | `LayoutSlots.test.tsx` landmark test; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `start-end-navigation-rtl` and `nested-panel-region` states | Caller `navigation` and `region` roles and labels | A lost role or name fails, including at the accessibility tree. Gap: no test asserts that a panel without `role` exposes none. | `audit:LayoutPanel/accessibility` |
-| FR6 | `LayoutSlots.test.tsx` ref and className tests | Ref; caller class | A ref on another element or a dropped class fails. Gap: no test covers `style`, DOM, data, or event props, or the `xstyle` merge order. | `audit:LayoutPanel/api` |
-| PR1 | Source review | Every state | Gap: no automated check fails if LayoutPanel adds a listener, timer, or measurement. | `audit:LayoutPanel/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1, ORD1 | `LayoutSlots.test.tsx` class, width, and resizable tests | Numeric and string width; resizable | A lost `layout-panel` class, a missing width, or `width` beating `resizable` fails. Gap: the non-shrinking root, scrolling, and `isScrollable={false}` have no check. No requirement or check covers how a keyboard user reaches a scrolling panel's overflow when the panel holds no focusable content. | `audit:LayoutPanel/layout` |
+| FR2 | `LayoutSlots.test.tsx` start- and end-slot tests; `Layout.a11y.chromium.spec.ts` `start-end-navigation-rtl` state | Start and end panels; right-to-left | A panel that fails to render in either slot fails. Gap: no check asserts which edge carries the divider or the shared gap, or the mirrored placement. | `audit:LayoutPanel/layout` |
+| FR3, ORD2 | Source review | Automatic, explicit, and zero padding | Gap: no test covers the automatic per-edge inset, the `padding` replacement, full bleed, or the published values. | `audit:LayoutPanel/layout` |
+| FR4 | Source review | `hasDivider`; no divider | Gap: no test covers the divider line, the shared gap, or a panel divider beside a ResizeHandle. | `audit:LayoutPanel/layout` |
+| FR5, AR1 | `LayoutSlots.test.tsx` landmark test; `Layout.a11y.test.tsx` and `Layout.a11y.chromium.spec.ts` `start-end-navigation-rtl` and `nested-panel-region` states | Caller `navigation` and `region` roles and labels | A lost role or name fails, including at the accessibility tree. Gap: no test asserts that a panel without `role` exposes none. | `audit:LayoutPanel/accessibility` |
+| FR6 | `LayoutSlots.test.tsx` ref and className tests | Ref; caller class | A ref on another element or a dropped class fails. Gap: no test covers `style`, DOM, data, or event props, or the `xstyle` merge order. | `audit:LayoutPanel/api` |
+| FR7, AR2 | Real-browser frame capture of a start and an end panel collapsing and opening, with focus inside, with the hook's `props` and with a hand-built object (pending) | Start and end; toggle, Enter and a drag past the threshold; configuration-object form; Reduce Motion | A jump instead of a slide, a gap beside the moving edge, a slide under the configuration-object form, focus left in a collapsed panel, a collapsed panel reachable by Tab or exposed to assistive technology, or a new prop fails. | `audit:LayoutPanel/behavior` |
+| PR1 | Source review | Every state | Gap: no automated check fails if LayoutPanel adds a listener, timer, or measurement. | `audit:LayoutPanel/behavior` |
## Decision log
-None recorded. The record describes shipped behavior.
+None recorded.
## Open questions
diff --git a/packages/core/src/Resizable/Resizable.spec.md b/packages/core/src/Resizable/Resizable.spec.md
index 47b60b72b7..2020dc65a4 100644
--- a/packages/core/src/Resizable/Resizable.spec.md
+++ b/packages/core/src/Resizable/Resizable.spec.md
@@ -32,7 +32,7 @@ architecture:
architecture:public-component-api,
]
contributing: []
-system_specs: [spec:AST-010, spec:AST-020, spec:AST-085]
+system_specs: [spec:AST-010, spec:AST-020, spec:AST-085, spec:AST-105]
---
# Resizable component contract
@@ -42,12 +42,12 @@ system_specs: [spec:AST-010, spec:AST-020, spec:AST-085]
| Area | Contract |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public contract | `useResizable` (size, bounds, collapse, snaps, persistence) and `ResizeHandle` (`direction`, `position`, `isReversed`, `isDisabled`, `hasDivider`, `isAlwaysVisible`, `pillPlacement`, `label`, `resizable`, `children`), plus the `pixel()` and `percent()` size helpers. |
-| Behavior | The hook owns a region's size in pixels; the Handle is a focusable window splitter that resizes it by pointer and keyboard. |
+| Behavior | The hook owns a region's size in pixels; the Handle is a focusable window splitter that resizes it by pointer and keyboard; a pane a LayoutPanel renders slides on collapse and open. |
| End-user impact | People drag or use the keyboard to resize a panel, collapse and restore it, and have the size remembered, with the divider moving the way the page reads. |
-| Builder impact | None; the record describes shipped behavior. |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Implementation gaps are listed under Current-state impact. |
+| Builder impact | None: no API change; a LayoutPanel's collapse slides with no code change. |
+| Compatibility/readiness | No API or default changes; a collapsing LayoutPanel pane slides and moves focus out, then becomes inert (FR8; `component:LayoutPanel` AR2): patch, `[feat]` slide and `[fix]` focus. Implementation gaps are listed under Current-state impact. |
| Review checks | Reject a Handle that loses its splitter role, values, or keys, arrows that move against the reading direction, a percentage default that rescales, or settled state, paint, storage, and ARIA that disagree; storage holds the last settled size and receives the final size once when a drag ends, cancels, or unmounts. |
-| Governing rules | `spec:AST-010`; `spec:AST-020` FR15 (APG Window Splitter); `spec:AST-085`; `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:public-component-api`. |
+| Governing rules | `spec:AST-010`; `spec:AST-020` FR15 (APG Window Splitter); `spec:AST-085`; `spec:AST-105` FR9; `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:public-component-api`. |
This table is a review projection; the body below is authoritative.
@@ -66,8 +66,12 @@ Consumer syntax and examples belong in `Resizable.doc.mjs` and
- Released default preserved: `yes`; numbers and exact `Npx` are pixels, exact
`N%` is a one-time default, and the broad `defaultSize` string type remains
source-compatible.
-- Compatibility class: records shipped behavior; `minSize` and `maxSize` are
- the bound props, and numeric bounds are pixels.
+- Compatibility class: patch. `minSize` and `maxSize` are the bound props,
+ and numeric bounds are pixels. A collapsing pane a LayoutPanel renders now
+ slides (FR8, `[feat]`, visual-only under `spec:AST-017/DEC-17`), and focus
+ inside it moves to its ResizeHandle while the collapsed pane becomes inert
+ (DOM: `inert` and `aria-hidden`; `component:LayoutPanel` AR2, `[fix]` under
+ `spec:AST-017` FR53). No prop, option, or return member changes.
- Controlled/uncontrolled behavior: collapse may be controlled
(`isCollapsed`, `onCollapseChange`) or uncontrolled (`defaultIsCollapsed`);
size is hook-owned.
@@ -96,6 +100,8 @@ Consumer migration instructions belong in consumer docs and release notes.
`onDoubleClick`, so passing any of them stops the Handle's focus-visible
pill and its double-click collapse, where
`architecture:public-component-api` INV7 has handlers compose.
+- **Collapse and open do not slide yet (FR8).** A LayoutPanel's pane jumps
+ closed and open, where `spec:AST-105` FR9 slides it.
- **`shrinkOrder` is inert.** useResizable accepts and documents
`shrinkOrder`, but no code reads it, so it has no effect.
@@ -132,15 +138,16 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| FR1 | ResizeHandle renders one focusable Handle and one enlarged Grab zone (a `--spacing-4` strip on the resize axis); the default render also contains a Grip pill, and caller `children` replace the pill. | Current source, docs, and tests |
-| FR2 | The Handle carries `resize-handle`, the Grip pill carries `resize-handle-pill`, and the Grab zone carries no public target. | Current source and docs |
-| FR3 | Pointer drag, keyboard, double-click collapse, snapping, persistence, reversal, and size behavior are owned by ResizeHandle and useResizable; dragging under right-to-left inverts the pointer delta so the divider follows the pointer. A disabled Handle ignores pointer and keyboard input and exposes `aria-disabled`, and keeps its tab stop (`spec:AST-085` FR1). With `autoSaveId`, storage holds the last settled size and receives the final size once when a drag ends, cancels, or unmounts. Implementation gap: a disabled Handle sets `tabIndex={-1}` (Current-state impact). | Current source, docs, and tests |
-| FR4 | The Handle reflects the documented `direction` visual state on its target (`architecture:component-theming-surface` INV6). Implementation gap: it reflects no `direction` (Current-state impact). | Current source and docs |
-| FR5 | A `percent(value, {min: pixel(value)})` or `percent(value, {max: pixel(value)})` resolves against one basis — the supplied container, or the viewport when no `containerRef` is given (`spec:AST-010` FR1, FR2); as a default it selects pixels once, and as a bound it stays live and clamps the selected pixels. A descriptor with both or neither bound is invalid. Selected state, persistence, callbacks, paint, and ARIA are pixels. | `spec:AST-010`; current source and tests |
-| FR6 | `minSize` and `maxSize` are the bound props; numeric values are pixels. When resolved bounds conflict, the maximum wins. | `spec:AST-010`; current source and tests |
-| FR7 | `ref`, DOM, data, ARIA, and event props reach the Handle, and a caller's explicit `role`, ARIA attribute, or `tabIndex` reaches it as given; a caller `onKeyDown` runs before the Handle's own key handling; caller `onFocus`, `onBlur`, and `onDoubleClick` compose with the Handle's own focus tracking and double-click collapse (`architecture:public-component-api` INV5, INV7); `xstyle` and `className` compose after component styles, and `style` is not accepted. Implementation gap: caller `onFocus`, `onBlur`, and `onDoubleClick` replace the Handle's own handlers (Current-state impact). | Current source; `architecture:public-component-api` INV5–INV8 |
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| FR1 | ResizeHandle renders one focusable Handle and one enlarged Grab zone (a `--spacing-4` strip on the resize axis); the default render also contains a Grip pill, and caller `children` replace the pill. | Current source, docs, and tests |
+| FR2 | The Handle carries `resize-handle`, the Grip pill carries `resize-handle-pill`, and the Grab zone carries no public target. | Current source and docs |
+| FR3 | Pointer drag, keyboard, double-click collapse, snapping, persistence, reversal, and size behavior are owned by ResizeHandle and useResizable; dragging under right-to-left inverts the pointer delta so the divider follows the pointer. A disabled Handle ignores pointer and keyboard input and exposes `aria-disabled`, and keeps its tab stop (`spec:AST-085` FR1). With `autoSaveId`, storage holds the last settled size and receives the final size once when a drag ends, cancels, or unmounts. Implementation gap: a disabled Handle sets `tabIndex={-1}` (Current-state impact). | Current source, docs, and tests |
+| FR4 | The Handle reflects the documented `direction` visual state on its target (`architecture:component-theming-surface` INV6). Implementation gap: it reflects no `direction` (Current-state impact). | Current source and docs |
+| FR5 | A `percent(value, {min: pixel(value)})` or `percent(value, {max: pixel(value)})` resolves against one basis — the supplied container, or the viewport when no `containerRef` is given (`spec:AST-010` FR1, FR2); as a default it selects pixels once, and as a bound it stays live and clamps the selected pixels. A descriptor with both or neither bound is invalid. Selected state, persistence, callbacks, paint, and ARIA are pixels. | `spec:AST-010`; current source and tests |
+| FR6 | `minSize` and `maxSize` are the bound props; numeric values are pixels. When resolved bounds conflict, the maximum wins. | `spec:AST-010`; current source and tests |
+| FR7 | `ref`, DOM, data, ARIA, and event props reach the Handle, and a caller's explicit `role`, ARIA attribute, or `tabIndex` reaches it as given; a caller `onKeyDown` runs before the Handle's own key handling; caller `onFocus`, `onBlur`, and `onDoubleClick` compose with the Handle's own focus tracking and double-click collapse (`architecture:public-component-api` INV5, INV7); `xstyle` and `className` compose after component styles, and `style` is not accepted. Implementation gap: caller `onFocus`, `onBlur`, and `onDoubleClick` replace the Handle's own handlers (Current-state impact). | Current source; `architecture:public-component-api` INV5–INV8 |
+| FR8 | When a region collapses or opens, its pane slides by `spec:AST-105` FR9's edge reveal when a LayoutPanel renders it (`component:LayoutPanel` FR7): the resize controller measures the pane's box before and after the collapse state commits, before its subscribers hear of it, and the pane's edge facing its ResizeHandle, read from the region's direction and reversal, moves with the content on that edge's side on one motion. Every collapse and open plays it: `collapse()`, `expand()`, a resize out of collapse, Enter, a double-click, the grow arrow, a controlled `isCollapsed` change, and a drag that crosses `collapsedSize` to collapse. A drag that reopens a collapsed pane plays nothing, because the pointer drives the edge; a resize that neither collapses nor opens, and the first render, play nothing. A pane the caller renders at the hook's size alone, and a LayoutPanel given the configuration-object form, a hand-built `ResizableProps` object that `useResizable` did not return passed through its `resizable`, show no slide; the hook's own `props` passed through `resizable` do slide. No prop, option or return member is added; size, `isCollapsed`, callbacks, persistence and the Handle's ARIA values are unchanged. Focus inside a collapsing pane follows `component:LayoutPanel` AR2. Implementation gap: no collapse or open slides yet (Current-state impact). | `spec:AST-105` FR9; `component:LayoutPanel` FR7, AR2 |
### Allowed variation
@@ -250,18 +257,19 @@ Consumer migration instructions belong in consumer docs and release notes.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
-| FR1 | `ResizeHandle.test.tsx`; stable visual baseline `core-resizable--horizontal-split` | Default, collapsed, both axes | Handle and Grab zone regressions fail focused tests; a changed default handle comes back changed for review. Gap: no test renders `children` to prove they replace the Grip pill. | `audit:Resizable/anatomy` |
-| FR2 | `themingTargets.test.ts`; source review | Handle, Grip pill, Grab zone | A removed target fails the inventory. `themingTargets.test.ts` catches only a renamed or undocumented target; no check fails if the Handle or Grip pill stops carrying its target. | `audit:Resizable/theming` |
-| FR3 | `ResizeHandle.test.tsx` and `useResizable.test.ts`; storage timing: `ResizeHandle.test.tsx` ("saves the size once, when a drag ends on …", "saves the dragged size once when the split unmounts mid-drag", "still saves each keyboard step at once") and `useResizable.test.ts` ("writes the size a drag reached once, after … releases it", "writes the final size once when the release comes before the last move renders", "keeps the size a region was dragged to when it unmounts mid-drag", "writes only the re-clamped size when the container shrank mid-drag") | Pointer, keyboard, snap, collapse, persistence; RTL drag; disabled keyboard | A changed transformation, an RTL drag that moves against the pointer, keyboard input that resizes a disabled Handle, or a per-move, stale or missing final storage write fails. Gap: no test covers disabled pointer input or the disabled tab stop. | `audit:Resizable/behavior` |
-| FR4 | Source and docs comparison | Horizontal and vertical Handle | Gap: no test detects that the documented `direction` is not reflected. | `audit:Resizable/theming` |
-| FR5, ORD1–ORD3 | `useResizable.test.ts`, `utils.test.ts`, typecheck | Floor, ceiling, default; invalid shapes; basis changes; numeric container parity | Wrong resolution, a rescaled default, a stale clamp, an observer leak, or state, paint, storage, and ARIA that disagree fails. | `audit:Resizable/behavior` |
-| FR6 | `useResizable.test.ts`; typecheck | Numeric bounds; conflicting bounds | A removed alias that type-checks, a numeric bound that is not pixels, or a minimum that wins a conflict fails. | `audit:Resizable/behavior` |
-| FR7 | `ResizeHandle.test.tsx` consumer `onKeyDown` test; source review | Caller props and `onKeyDown` | A consumer `onKeyDown` that stops keyboard resizing, or keyboard resizing that skips the consumer handler, fails. Gap: no test covers other caller props, the styling merge, caller `onFocus`, `onBlur`, or `onDoubleClick`, or a caller `role` or ARIA attribute. | `audit:Resizable/api` |
-| AR1 | `ResizeHandle.test.tsx` ("makes the separator focusable", "exposes the region size and bounds via ARIA", "grows the panel by a step on ArrowRight", "shrinks the panel by a step on ArrowLeft", "uses the large step when Shift is held", "jumps to the minimum on Home", "jumps to the maximum on End", "collapses on Enter when the region is collapsible", "inverts the pointer delta under RTL so dragging resizes intuitively", "restores the previous size, not the minimum, when Enter reopens a collapsed pane", "reopens on Enter even when the minimum size sits below the collapse threshold", "reports the window basis as aria-valuemax when no maximum is configured; End leaves an unbounded region alone", "reports the container basis as aria-valuemax while a percentage bound already observes it", "never reports aria-valuemax below aria-valuemin while collapsed in a small window", "reports no aria-valuemax for an unbounded pixel-only region in a container, which stays unobserved", "a grow arrow opens a collapsed pane one step above its minimum; the shrink arrow leaves it collapsed", "a grow arrow opens a collapsed pane at its collapsedSize when the minimum sits below it", "a grow arrow opens a collapsed pane in the reversed layout and under RTL too", "in a reversed layout, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "under RTL, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "a grow arrow opens a hand-built collapsed region one step above its minimum", "with snap points, an arrow moves to the adjacent point in its direction and Shift moves two, clamped to the ends", "with snap points past the bounds, a point beyond maxSize or minSize counts as that bound", "with snap points, the arrows follow the reversed layout and the reading direction", "with snap points in a reversed layout, ArrowLeft moves to the next point and ArrowRight to the previous", "with snap points, the grow arrow opens a collapsed pane at the snap point nearest one step above its minimum") and `shippedDirections.test.ts`; `SideNav.test.tsx` ("names the nav it resizes with aria-controls (APG window splitter)"); RTL keyboard mirroring, and the disabled state under the Window Splitter accessibility contract (`internal/a11y-spec`, pending); `ResizeHandle.a11y.test.tsx` and `ResizeHandle.a11y.chromium.spec.ts` | Inline and block axes; LTR and RTL; collapsed; disabled | The Handle loses its role, name, orientation, or value properties; an arrow, Home, End, or Enter stops moving the divider or moves it against the reading direction. | `audit:Resizable/accessibility` |
-| PR1 | `useResizable.test.ts` observer tests | Pixel, percentage default, percentage bound | An observer on a pixel-only path, or one that outlives a final default, fails. | `audit:Resizable/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and two targets | Missing, extra, or stale mappings fail repository validation. | `audit:Resizable/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
+| FR1 | `ResizeHandle.test.tsx`; stable visual baseline `core-resizable--horizontal-split` | Default, collapsed, both axes | Handle and Grab zone regressions fail focused tests; a changed default handle comes back changed for review. Gap: no test renders `children` to prove they replace the Grip pill. | `audit:Resizable/anatomy` |
+| FR2 | `themingTargets.test.ts`; source review | Handle, Grip pill, Grab zone | A removed target fails the inventory. `themingTargets.test.ts` catches only a renamed or undocumented target; no check fails if the Handle or Grip pill stops carrying its target. | `audit:Resizable/theming` |
+| FR3 | `ResizeHandle.test.tsx` and `useResizable.test.ts`; storage timing: `ResizeHandle.test.tsx` ("saves the size once, when a drag ends on …", "saves the dragged size once when the split unmounts mid-drag", "still saves each keyboard step at once") and `useResizable.test.ts` ("writes the size a drag reached once, after … releases it", "writes the final size once when the release comes before the last move renders", "keeps the size a region was dragged to when it unmounts mid-drag", "writes only the re-clamped size when the container shrank mid-drag") | Pointer, keyboard, snap, collapse, persistence; RTL drag; disabled keyboard | A changed transformation, an RTL drag that moves against the pointer, keyboard input that resizes a disabled Handle, or a per-move, stale or missing final storage write fails. Gap: no test covers disabled pointer input or the disabled tab stop. | `audit:Resizable/behavior` |
+| FR4 | Source and docs comparison | Horizontal and vertical Handle | Gap: no test detects that the documented `direction` is not reflected. | `audit:Resizable/theming` |
+| FR5, ORD1–ORD3 | `useResizable.test.ts`, `utils.test.ts`, typecheck | Floor, ceiling, default; invalid shapes; basis changes; numeric container parity | Wrong resolution, a rescaled default, a stale clamp, an observer leak, or state, paint, storage, and ARIA that disagree fails. | `audit:Resizable/behavior` |
+| FR6 | `useResizable.test.ts`; typecheck | Numeric bounds; conflicting bounds | A removed alias that type-checks, a numeric bound that is not pixels, or a minimum that wins a conflict fails. | `audit:Resizable/behavior` |
+| FR7 | `ResizeHandle.test.tsx` consumer `onKeyDown` test; source review | Caller props and `onKeyDown` | A consumer `onKeyDown` that stops keyboard resizing, or keyboard resizing that skips the consumer handler, fails. Gap: no test covers other caller props, the styling merge, caller `onFocus`, `onBlur`, or `onDoubleClick`, or a caller `role` or ARIA attribute. | `audit:Resizable/api` |
+| FR8 | Real-browser frame capture of a start and an end LayoutPanel collapsing and opening by each listed path, a drag reopening a pane, a hook-only pane, and a hand-built `ResizableProps` pane (pending) | Start and end panes; `collapse()`, `expand()`, Enter, double-click, the grow arrow, a controlled `isCollapsed` change, a drag across `collapsedSize`; a reopening drag; the hook's `props` and a hand-built object through `resizable`; Reduce Motion | A jump instead of a slide, a slide from the wrong edge, a slide during a reopening drag or on first render, a slide for a hook-only pane or a hand-built object, no slide for the hook's `props`, or a new prop, option or return member fails. | `audit:Resizable/behavior` |
+| AR1 | `ResizeHandle.test.tsx` ("makes the separator focusable", "exposes the region size and bounds via ARIA", "grows the panel by a step on ArrowRight", "shrinks the panel by a step on ArrowLeft", "uses the large step when Shift is held", "jumps to the minimum on Home", "jumps to the maximum on End", "collapses on Enter when the region is collapsible", "inverts the pointer delta under RTL so dragging resizes intuitively", "restores the previous size, not the minimum, when Enter reopens a collapsed pane", "reopens on Enter even when the minimum size sits below the collapse threshold", "reports the window basis as aria-valuemax when no maximum is configured; End leaves an unbounded region alone", "reports the container basis as aria-valuemax while a percentage bound already observes it", "never reports aria-valuemax below aria-valuemin while collapsed in a small window", "reports no aria-valuemax for an unbounded pixel-only region in a container, which stays unobserved", "a grow arrow opens a collapsed pane one step above its minimum; the shrink arrow leaves it collapsed", "a grow arrow opens a collapsed pane at its collapsedSize when the minimum sits below it", "a grow arrow opens a collapsed pane in the reversed layout and under RTL too", "in a reversed layout, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "under RTL, ArrowLeft opens a collapsed pane and ArrowRight leaves it collapsed", "a grow arrow opens a hand-built collapsed region one step above its minimum", "with snap points, an arrow moves to the adjacent point in its direction and Shift moves two, clamped to the ends", "with snap points past the bounds, a point beyond maxSize or minSize counts as that bound", "with snap points, the arrows follow the reversed layout and the reading direction", "with snap points in a reversed layout, ArrowLeft moves to the next point and ArrowRight to the previous", "with snap points, the grow arrow opens a collapsed pane at the snap point nearest one step above its minimum") and `shippedDirections.test.ts`; `SideNav.test.tsx` ("names the nav it resizes with aria-controls (APG window splitter)"); RTL keyboard mirroring, and the disabled state under the Window Splitter accessibility contract (`internal/a11y-spec`, pending); `ResizeHandle.a11y.test.tsx` and `ResizeHandle.a11y.chromium.spec.ts` | Inline and block axes; LTR and RTL; collapsed; disabled | The Handle loses its role, name, orientation, or value properties; an arrow, Home, End, or Enter stops moving the divider or moves it against the reading direction. | `audit:Resizable/accessibility` |
+| PR1 | `useResizable.test.ts` observer tests | Pixel, percentage default, percentage bound | An observer on a pixel-only path, or one that outlives a final default, fails. | `audit:Resizable/behavior` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and two targets | Missing, extra, or stale mappings fail repository validation. | `audit:Resizable/theming` |
## Decision log
diff --git a/packages/core/src/SideNav/SideNav.spec.md b/packages/core/src/SideNav/SideNav.spec.md
index 25a3c17232..a9b0505ea8 100644
--- a/packages/core/src/SideNav/SideNav.spec.md
+++ b/packages/core/src/SideNav/SideNav.spec.md
@@ -112,14 +112,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis | Draft review state |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1 | SideNav renders its navigation children in a scrollable list, which may be grouped by SideNavSection. A SideNavItem with children renders them, after its own row, in a group labelled by the parent's label; unless `collapsible` is `false`, the group expands and collapses and is hidden from assistive technology and inert while collapsed. | Current source, docs, and tests | Current behavior |
-| FR2 | In a collapsed rail, a SideNavItem without an icon is not rendered; a leaf item renders icon-only, named by a non-blank caller `aria-label` or else its label; an item with children renders an icon-only trigger that opens a flyout listing its children as the flyout's top level. | Current source, docs, and tests | Current behavior |
-| FR3 | In an expanded rail, in a flyout, and in the mobile navigation drawer, every SideNavItem row MUST span the full inline size of its list at any depth. A row at depth `n` MUST start its content `n` × `--spacing-6` beyond the row's own inline-start padding for its size, inside the row; the nested group MUST add no inset. A flyout's top level is depth 0. | `component:SideNav/DEC-1` | Settled intent; implementation may be staged |
-| FR4 | The indent area MUST be part of the row's target: a click there, including a modified or middle click on a link row, does what the same click on the row's primary element does. When the row also carries an independent expand toggle or `actions`, the indent belongs to the primary link or button, and the toggle and actions keep their own activation at the row's trailing edge. | `component:SideNav/DEC-1`; `family:navigation-destinations` | Settled intent; implementation may be staged |
-| FR5 | An expanded nested group MUST NOT clip its rows once it has finished opening, so a nested row's focus ring paints in full. The group MAY clip while collapsed and while it opens or closes. | `component:SideNav/DEC-1` | Settled intent; implementation may be staged |
-| FR6 | Collapsing or expanding the rail plays one motion on one clock, `spec:AST-105` FR4's one shared motion (`springs.settle`): layout snaps to the final rail width at once, with no width animation, and the rail reveals or covers its labels by a clip: a collapse ends in the real collapsed state, icons only, and an expand ends in the real expanded state, with its labels. On a collapse or an expand the rail's old state is one transient copy, inert and hidden from assistive technology, removed when the motion ends. The main content moves on the same clock, as `component:AppShell` FR17 states. Under reduced motion the rail follows `design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise. | `component:SideNav/DEC-2`; `component:AppShell` FR17; `spec:AST-105` FR8 | Verified by `SideNavRailMotion.test.tsx` and `SideNavRailMotion.interaction.browser.spec.ts`; the `reducedMotion: 'always'` theme case pending |
+| ID | Invariant | Basis | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | SideNav renders its navigation children in a scrollable list, which may be grouped by SideNavSection. A SideNavItem with children renders them, after its own row, in a group labelled by the parent's label; unless `collapsible` is `false`, the group expands and collapses and is hidden from assistive technology and inert while collapsed. | Current source, docs, and tests | Current behavior |
+| FR2 | In a collapsed rail, a SideNavItem without an icon is not rendered; a leaf item renders icon-only, named by a non-blank caller `aria-label` or else its label; an item with children renders an icon-only trigger that opens a flyout listing its children as the flyout's top level. | Current source, docs, and tests | Current behavior |
+| FR3 | In an expanded rail, in a flyout, and in the mobile navigation drawer, every SideNavItem row MUST span the full inline size of its list at any depth. A row at depth `n` MUST start its content `n` × `--spacing-6` beyond the row's own inline-start padding for its size, inside the row; the nested group MUST add no inset. A flyout's top level is depth 0. | `component:SideNav/DEC-1` | Settled intent; implementation may be staged |
+| FR4 | The indent area MUST be part of the row's target: a click there, including a modified or middle click on a link row, does what the same click on the row's primary element does. When the row also carries an independent expand toggle or `actions`, the indent belongs to the primary link or button, and the toggle and actions keep their own activation at the row's trailing edge. | `component:SideNav/DEC-1`; `family:navigation-destinations` | Settled intent; implementation may be staged |
+| FR5 | An expanded nested group MUST NOT clip its rows once it has finished opening, so a nested row's focus ring paints in full. The group MAY clip while collapsed and while it opens or closes. | `component:SideNav/DEC-1` | Settled intent; implementation may be staged |
+| FR6 | Collapsing or expanding the rail plays one motion on one clock, `spec:AST-105` FR4's one shared motion (`springs.settle`): layout snaps to the final rail width at once, with no width animation, and the rail reveals or covers its labels by a clip, its edge riding the main content's glide and its labels and collapsed icons fading on the same clock (`spec:AST-105` FR9's inline two-state form; the clip and the ride are the shared edge reveal's, and SideNav's own code keeps only the fades; the rail lends no pane to its resize controller, so a collapse plays once; implementation gap: the clip and the ride still run in SideNav's own rail motion code, not in the shared edge reveal): a collapse ends in the real collapsed state, icons only, and an expand ends in the real expanded state, with its labels. On a collapse or an expand the rail's old state is one transient copy, inert and hidden from assistive technology, removed when the motion ends. The main content moves on the same clock, as `component:AppShell` FR17 states. Under reduced motion the rail follows `design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise. | `component:SideNav/DEC-2`; `component:AppShell` FR17; `spec:AST-105` FR8, FR9 | Verified by `SideNavRailMotion.test.tsx` and `SideNavRailMotion.interaction.browser.spec.ts`; the `reducedMotion: 'always'` theme case pending |
### Allowed variation