@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Selector/useCombobox.test.tsx

@@ -0,0 +1,444 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useCombobox.test.tsx
+ * @input Uses vitest, @testing-library/react, @testing-library/user-event,
+ *   useCombobox and the layer dismissal stack
+ * @output Unit tests for useCombobox over a single-line field the caller renders
+ * @position Tests; validates the field props, keys and pointer model of
+ *   hooks.ts against spec:AST-075 FR1–FR6
+ *
+ * SYNC: When useCombobox's field props or keys change, update these tests.
+ */
+
+import {cleanup, fireEvent, render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {useRef, useState, type ReactNode} from 'react';
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {
+  COMBOBOX_PATTERN,
+  expectAccessibilitySpec,
+  type ComboboxStateFacts,
+} from '@astryxdesign/a11y-spec';
+import {LayerDepthProvider} from '../Layer/LayerDepthContext';
+import {resetLayerStackForTests} from '../Layer/layerStack';
+import {useLayerDismissal} from '../Layer/useLayerDismissal';
+import {useCombobox} from './hooks';
+
+type Person = {value: string; label: string; disabled?: boolean};
+
+const PEOPLE: Person[] = [
+  {value: 'ada', label: 'Ada'},
+  {value: 'bea', label: 'Bea', disabled: true},
+  {value: 'cy', label: 'Cy'},
+];
+
+afterEach(() => {
+  resetLayerStackForTests();
+});
+
+interface PickerProps {
+  options?: Person[];
+  isInitiallyOpen?: boolean;
+  onSelect?: (value: string) => void;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onFieldKeyDown?: (event: React.KeyboardEvent) => void;
+}
+
+/** A field the test renders itself, with its list in the page's flow. */
+function Picker({
+  options = PEOPLE,
+  isInitiallyOpen = true,
+  onSelect,
+  onOpen,
+  onClose,
+  onFieldKeyDown,
+}: PickerProps) {
+  const [isOpen, setIsOpen] = useState(isInitiallyOpen);
+  const combobox = useCombobox({
+    selectableItems: options,
+    isOpen,
+    onOpen: () => {
+      onOpen?.();
+      setIsOpen(true);
+    },
+    onClose: () => {
+      onClose?.();
+      setIsOpen(false);
+    },
+    onSelect,
+    listboxId: 'people',
+  });
+  const fieldProps = combobox.getFieldProps({onKeyDown: onFieldKeyDown});
+  return (
+    <>
+      <input aria-label="To" {...fieldProps} />
+      {isOpen && options.length > 0 ? (
+        <div aria-label="People" {...combobox.getListboxProps()}>
+          {options.map((person, index) => (
+            <div key={person.value} {...combobox.getOptionProps(index)}>
+              {person.label}
+            </div>
+          ))}
+        </div>
+      ) : null}
+    </>
+  );
+}
+
+/** A registered layer, like a Dialog or Popover, around the field. */
+function Layer({
+  onDismiss,
+  children,
+}: {
+  onDismiss: () => void;
+  children: ReactNode;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  useLayerDismissal({
+    isActive: true,
+    onDismiss,
+    getContainer: () => containerRef.current,
+  });
+  return (
+    <div ref={containerRef}>
+      <LayerDepthProvider>{children}</LayerDepthProvider>
+    </div>
+  );
+}
+
+function toField(): HTMLElement {
+  return screen.getByRole('combobox', {name: 'To'});
+}
+
+function option(name: string): HTMLElement {
+  return screen.getByRole('option', {name});
+}
+
+describe('useCombobox field props — roles and state (FR1–FR3)', () => {
+  it('a hidden list leaves the field collapsed with nothing to reference', () => {
+    render(<Picker isInitiallyOpen={false} />);
+    const box = toField();
+    expect(box).toHaveAttribute('role', 'combobox');
+    expect(box).toHaveAttribute('aria-autocomplete', 'list');
+    expect(box).toHaveAttribute('aria-expanded', 'false');
+    expect(box).not.toHaveAttribute('aria-controls');
+    expect(box).not.toHaveAttribute('aria-activedescendant');
+  });
+
+  it('a shown list expands the field and names the listbox', () => {
+    render(<Picker />);
+    const box = toField();
+    const listbox = screen.getByRole('listbox', {name: 'People'});
+    expect(box).toHaveAttribute('aria-expanded', 'true');
+    expect(box).toHaveAttribute('aria-controls', listbox.id);
+    expect(screen.getAllByRole('option')).toHaveLength(3);
+    // No option is active until the person moves to one.
+    expect(box).not.toHaveAttribute('aria-activedescendant');
+  });
+
+  it('an open list with no options renders no listbox, so the field stays collapsed', () => {
+    render(<Picker options={[]} />);
+    const box = toField();
+    expect(screen.queryByRole('listbox')).toBeNull();
+    expect(box).toHaveAttribute('aria-expanded', 'false');
+    expect(box).not.toHaveAttribute('aria-controls');
+  });
+
+  it('moving the active option keeps focus in the field and names it (FR1)', async () => {
+    const user = userEvent.setup();
+    render(<Picker />);
+    const box = toField();
+    await user.click(box);
+
+    await user.keyboard('{ArrowDown}');
+    expect(box).toHaveFocus();
+    expect(box).toHaveAttribute('aria-activedescendant', option('Ada').id);
+    expect(option('Ada')).toHaveAttribute('aria-selected', 'true');
+    expect(option('Cy')).toHaveAttribute('aria-selected', 'false');
+
+    // The disabled option is skipped, and the arrows wrap at either end.
+    await user.keyboard('{ArrowDown}');
+    expect(box).toHaveAttribute('aria-activedescendant', option('Cy').id);
+    await user.keyboard('{ArrowDown}');
+    expect(box).toHaveAttribute('aria-activedescendant', option('Ada').id);
+    await user.keyboard('{ArrowUp}');
+    expect(box).toHaveAttribute('aria-activedescendant', option('Cy').id);
+    expect(box).toHaveFocus();
+    expect(option('Bea')).toHaveAttribute('aria-disabled', 'true');
+  });
+
+  it('ArrowUp with nothing active starts at the last option', async () => {
+    const user = userEvent.setup();
+    render(<Picker />);
+    const box = toField();
+    await user.click(box);
+    await user.keyboard('{ArrowUp}');
+    expect(box).toHaveAttribute('aria-activedescendant', option('Cy').id);
+  });
+});
+
+describe('useCombobox field props — the reusable Combobox contract', () => {
+  const closed: ComboboxStateFacts = {
+    name: 'To',
+    expanded: false,
+    popupRole: 'listbox',
+    popupVisible: false,
+    activeDescendant: false,
+    readOnly: false,
+    busy: false,
+    inertUnderOwnModal: false,
+  };
+
+  it.each([
+    {open: false, facts: closed},
+    {
+      open: true,
+      facts: {
+        ...closed,
+        expanded: true,
+        popupVisible: true,
+        activeDescendant: true,
+      },
+    },
+  ] as const)('input, list shown: $open', async ({open, facts}) => {
+    await expectAccessibilitySpec({
+      spec: COMBOBOX_PATTERN,
+      binding: 'useCombobox.field',
+      state: `input-${open ? 'shown' : 'hidden'}`,
+      facts,
+      render: async () => {
+        render(<Picker isInitiallyOpen={open} />);
+        if (open) {
+          toField().focus();
+          fireEvent.keyDown(toField(), {key: 'ArrowDown'});
+        }
+      },
+      subject: () => toField(),
+      related: (): Record<string, Element> =>
+        open
+          ? {
+              popup: screen.getByRole('listbox'),
+              'active-descendant': option('Ada'),
+            }
+          : {},
+      cleanup,
+    });
+  });
+});
+
+describe('useCombobox field props — keys (FR4)', () => {
+  it('Enter picks only an active option, and only then stops the field’s own Enter', async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    const onFieldKeyDown = vi.fn();
+    render(<Picker onSelect={onSelect} onFieldKeyDown={onFieldKeyDown} />);
+    const box = toField();
+    await user.click(box);
+
+    // Nothing active: Enter is the field's own, such as a submit.
+    expect(fireEvent.keyDown(box, {key: 'Enter'})).toBe(true);
+    expect(onSelect).not.toHaveBeenCalled();
+    expect(onFieldKeyDown).toHaveBeenCalledTimes(1);
+
+    await user.keyboard('{ArrowDown}');
+    expect(fireEvent.keyDown(box, {key: 'Enter'})).toBe(false);
+    expect(onSelect).toHaveBeenCalledWith('ada');
+    // The arrow and the pick never reached the field's handler.
+    expect(onFieldKeyDown).toHaveBeenCalledTimes(1);
+    // Picking hides the list; focus never left the field.
+    expect(screen.queryByRole('listbox')).toBeNull();
+    expect(box).toHaveFocus();
+  });
+
+  it('Escape hides the list without dismissing the enclosing layer on the same press', async () => {
+    const user = userEvent.setup();
+    const onDismiss = vi.fn();
+    render(
+      <Layer onDismiss={onDismiss}>
+        <Picker />
+      </Layer>,
+    );
+    await user.click(toField());
+
+    await user.keyboard('{Escape}');
+    expect(screen.queryByRole('listbox')).toBeNull();
+    expect(onDismiss).not.toHaveBeenCalled();
+
+    // With the list hidden, Escape belongs to the layer again.
+    await user.keyboard('{Escape}');
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it('Escape also hides an open list that has no options', () => {
+    const onClose = vi.fn();
+    render(<Picker options={[]} onClose={onClose} />);
+    expect(fireEvent.keyDown(toField(), {key: 'Escape'})).toBe(false);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it.each(['shiftKey', 'ctrlKey', 'altKey', 'metaKey'] as const)(
+    'Escape held with %s still hides the list first and leaves the enclosing layer open',
+    modifier => {
+      const onDismiss = vi.fn();
+      render(
+        <Layer onDismiss={onDismiss}>
+          <Picker />
+        </Layer>,
+      );
+      const box = toField();
+      box.focus();
+      expect(fireEvent.keyDown(box, {key: 'Escape', [modifier]: true})).toBe(
+        false,
+      );
+      expect(screen.queryByRole('listbox')).toBeNull();
+      expect(onDismiss).not.toHaveBeenCalled();
+
+      // With the list hidden, the same chord belongs to the layer again.
+      fireEvent.keyDown(box, {key: 'Escape', [modifier]: true});
+      expect(onDismiss).toHaveBeenCalledTimes(1);
+    },
+  );
+
+  it('ArrowDown shows a hidden list in a single-line field', async () => {
+    const user = userEvent.setup();
+    render(<Picker isInitiallyOpen={false} />);
+    const box = toField();
+    await user.click(box);
+    await user.keyboard('{ArrowDown}');
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+    expect(box).toHaveAttribute('aria-expanded', 'true');
+    expect(box).toHaveAttribute('aria-activedescendant', option('Ada').id);
+  });
+
+  it('ArrowDown leaves a hidden list alone when there is nothing to show', () => {
+    const onOpen = vi.fn();
+    render(<Picker options={[]} isInitiallyOpen={false} onOpen={onOpen} />);
+    expect(fireEvent.keyDown(toField(), {key: 'ArrowDown'})).toBe(true);
+    expect(onOpen).not.toHaveBeenCalled();
+  });
+
+  it('keys other than the arrows, Enter and Escape reach the field while the list is shown', async () => {
+    const user = userEvent.setup();
+    const onFieldKeyDown = vi.fn();
+    render(<Picker onFieldKeyDown={onFieldKeyDown} />);
+    const box = toField();
+    await user.click(box);
+    await user.keyboard('{ArrowDown}');
+    const active = box.getAttribute('aria-activedescendant');
+
+    // Home and End stay with the caret: their combobox meaning is undecided.
+    for (const key of ['Home', 'End', 'PageDown', 'Tab', ' ', 'a']) {
+      expect(fireEvent.keyDown(box, {key})).toBe(true);
+    }
+    expect(onFieldKeyDown).toHaveBeenCalledTimes(6);
+    expect(box).toHaveAttribute('aria-activedescendant', active);
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+  });
+
+  it('a chord such as Shift+Enter is the field’s own command', async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<Picker onSelect={onSelect} />);
+    const box = toField();
+    await user.click(box);
+    await user.keyboard('{ArrowDown}');
+    expect(fireEvent.keyDown(box, {key: 'Enter', shiftKey: true})).toBe(true);
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  it('leaves onKeyDown with the trigger model it already had', async () => {
+    const user = userEvent.setup();
+    function Trigger() {
+      const [isOpen, setIsOpen] = useState(true);
+      const combobox = useCombobox({
+        selectableItems: PEOPLE,
+        isOpen,
+        onOpen: () => setIsOpen(true),
+        onClose: () => setIsOpen(false),
+        listboxId: 'trigger',
+      });
+      return (
+        <button
+          type="button"
+          aria-activedescendant={
+            combobox.highlightedIndex >= 0
+              ? combobox.getItemId(combobox.highlightedIndex)
+              : undefined
+          }
+          onKeyDown={combobox.onKeyDown}>
+          Pick
+        </button>
+      );
+    }
+    render(<Trigger />);
+    const button = screen.getByRole('button', {name: 'Pick'});
+    button.focus();
+    await user.keyboard('{End}');
+    expect(button).toHaveAttribute('aria-activedescendant', 'trigger-item-2');
+  });
+});
+
+describe('useCombobox field props — input-method composition (FR5)', () => {
+  it('a composing key neither moves, picks nor hides', async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    const onClose = vi.fn();
+    render(<Picker onSelect={onSelect} onClose={onClose} />);
+    const box = toField();
+    await user.click(box);
+    await user.keyboard('{ArrowDown}');
+    const active = option('Ada').id;
+
+    for (const init of [
+      {key: 'ArrowDown', isComposing: true},
+      {key: 'Enter', isComposing: true},
+      {key: 'Escape', isComposing: true},
+      {key: 'Enter', keyCode: 229},
+    ]) {
+      expect(fireEvent.keyDown(box, init)).toBe(true);
+    }
+    expect(box).toHaveAttribute('aria-activedescendant', active);
+    expect(onSelect).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+
+    // Once the composition ends, Enter picks again.
+    fireEvent.keyDown(box, {key: 'Enter'});
+    expect(onSelect).toHaveBeenCalledWith('ada');
+  });
+});
+
+describe('useCombobox field props — pointer (FR6)', () => {
+  it('hovering makes an option active and pressing picks it, with focus kept in the field', async () => {
+    const user = userEvent.setup();
+    const onSelect = vi.fn();
+    render(<Picker onSelect={onSelect} />);
+    const box = toField();
+    await user.click(box);
+
+    await user.hover(option('Cy'));
+    expect(box).toHaveAttribute('aria-activedescendant', option('Cy').id);
+    expect(box).toHaveFocus();
+
+    // A disabled option never becomes active and cannot be picked.
+    await user.hover(option('Bea'));
+    expect(box).toHaveAttribute('aria-activedescendant', option('Cy').id);
+    await user.click(option('Bea'));
+    expect(onSelect).not.toHaveBeenCalled();
+    expect(box).toHaveFocus();
+
+    await user.click(option('Cy'));
+    expect(onSelect).toHaveBeenCalledWith('cy');
+    expect(box).toHaveFocus();
+    expect(screen.queryByRole('listbox')).toBeNull();
+  });
+
+  it('a press on the listbox itself keeps focus in the field', () => {
+    render(<Picker />);
+    const box = toField();
+    box.focus();
+    expect(fireEvent.mouseDown(screen.getByRole('listbox'))).toBe(false);
+    expect(fireEvent.mouseDown(option('Ada'))).toBe(false);
+  });
+});

package/src/SideNav/SideNav.spec.md

@@ -36,22 +36,23 @@ system_specs: [spec:AST-017/FR3]
 
 This record governs how nested SideNavItem rows are drawn: their width, where
 their nesting indent sits, and what the indent area does. It covers SideNav,
-SideNavSection, and SideNavItem only as far as that geometry depends on them.
+SideNavSection, and SideNavItem only as far as that geometry depends on them. It
+also governs the rail's own collapse motion (FR6).
 SideNavItem's link and destination safety is governed by
 `family:navigation-destinations`; other SideNav behavior remains described by
 its source, tests, and consumer docs until a record claims it.
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | None. No prop, value, default, or theme target changes.                                                                                                                                                                                                 |
-| Behavior                | Every SideNavItem row spans the full width of its nav list at any depth. Depth shows as inline-start indent inside the row: one `--spacing-6` step per level, added to the row's own padding.                                                           |
-| End-user impact         | A person scanning a nested nav sees hover, pressed, selected, and focus fills that line up with the top-level rows, and can click a nested row's indent to activate it, as they would its label.                                                        |
-| Builder impact          | No new choice or prop. Icons and labels keep their per-depth position. Content placed directly inside a SideNavItem that is not itself a SideNavItem sits at the nav list edge, because the nested group adds no inset; no supported setting insets it. |
-| Compatibility/readiness | Nonbreaking change of visual direction (`spec:AST-017/FR3`). The collapsed rail and top-level rows are unchanged. Authority is current; implementation may be staged.                                                                                   |
-| Review checks           | Reject a nested row narrower than a top-level row, an indent drawn outside the row, an indent area that shows feedback but does not activate, a clipped focus ring, or an indent in the flyout's top level.                                             |
-| Governing rules         | DD1 and FR3–FR5 below; `family:navigation-destinations` for destinations; `architecture:internationalization` for logical direction.                                                                                                                    |
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None. No prop, value, default, or theme target changes.                                                                                                                                                                                                                                                                                                                 |
+| Behavior                | Every SideNavItem row spans the full width of its nav list at any depth. Depth shows as inline-start indent inside the row: one `--spacing-6` step per level, added to the row's own padding. Collapsing or expanding the rail snaps the layout to its final width and clips the labels in or out; a collapse ends icons-only and an expand ends with its labels (FR6). |
+| End-user impact         | A person scanning a nested nav sees hover, pressed, selected, and focus fills that line up with the top-level rows, and can click a nested row's indent to activate it, as they would its label. Collapsing the rail moves no layout frame by frame (FR6).                                                                                                              |
+| Builder impact          | No new choice or prop. Icons and labels keep their per-depth position. Content placed directly inside a SideNavItem that is not itself a SideNavItem sits at the nav list edge, because the nested group adds no inset; no supported setting insets it.                                                                                                                 |
+| Compatibility/readiness | Nonbreaking change of visual direction (`spec:AST-017/FR3`). The collapsed rail and top-level rows are unchanged. Authority is current; implementation may be staged.                                                                                                                                                                                                   |
+| Review checks           | Reject a nested row narrower than a top-level row, an indent drawn outside the row, an indent area that shows feedback but does not activate, a clipped focus ring, or an indent in the flyout's top level. Also reject an animated rail width (FR6).                                                                                                                   |
+| Governing rules         | DD1 and FR3–FR6 below; `component:AppShell` FR17 for the content; `family:navigation-destinations` for destinations; `architecture:internationalization` for logical direction.                                                                                                                                                                                         |
 
 This table is a review projection; the body below is authoritative.
 
@@ -66,7 +67,8 @@ a row's depth and its row padding.
 ## Compatibility and migration
 
 - Released default preserved: `no`; nested rows change from inset to full width.
-  Top-level rows and the collapsed rail are unchanged.
+  Top-level rows and the collapsed rail are unchanged. The rail's
+  collapse and expand gain FR6's motion.
 - Compatibility class: nonbreaking appearance change of visual direction under
   `spec:AST-017/FR3`; no public API, accepted input, or accessibility semantic
   changes.
@@ -84,18 +86,22 @@ Consumer migration instructions belong in consumer docs and release notes.
   padding.
 - What the indent area paints and what a click on it does.
 - Whether the nested group clips its rows.
+- The rail's collapse and expand motion: the snap to the final width and the
+  clip that reveals or covers the labels (FR6).
 
 **Does not own / non-goals**
 
 - Destination acceptance, blocking, and router handoff — owned by
   `family:navigation-destinations`.
-- The collapsed item's tooltip and how it attaches — outside this record.
+- The collapsed item's tooltip and how it attaches — owned by
+  `component:SideNavItem`.
 - Exact fill colors, radius, row height, and row padding per size — owned by
   the shared nav item styles and the `side-nav-item` theme target.
 - Layout of caller content placed directly inside a SideNavItem that is not a
   SideNavItem — owned by the product callsite.
-- SideNavHeading, SideNavCollapseButton, and the SideNav header, footer, and
-  resize zones.
+- SideNavHeading — owned by `component:SideNavHeading`; SideNavCollapseButton —
+  owned by `component:SideNavCollapseButton`.
+- The SideNav header, footer, and resize zones.
 
 ## Public concepts
 
@@ -106,13 +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 |
+| 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 |
 
 ### Allowed variation
 
@@ -188,15 +195,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Verification map
 
-| Contract  | Verification                                                                          | Representative states                                                                         | Mutation or failure expectation                                                                                                                                        | Audit section            |
-| --------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1, FR2  | `SideNav.test.tsx` nesting, collapsible, and collapsed-rail suites                    | Nested, collapsible, collapsed rail, flyout                                                   | Removing the labelled group, its collapsed inert state, or the collapsed icon-only and flyout paths fails.                                                             | `audit:SideNav/anatomy`  |
-| FR3, ORD1 | Focused `SideNav.test.tsx` indent coverage, required with implementation              | Depth 1 and 2; `sm` and `md`; split and actions rows; caller `style`; flyout                  | A group inset, a missing or wrong indent, a dropped caller `style`, an indent that overrides a caller-set inline-start padding, or an indented flyout top level fails. | `audit:SideNav/layout`   |
-| FR3, DD1  | Real-browser geometry over the SideNav nested stories                                 | Depths 1–3; `sm`, `md`, `lg`; light and dark; right-to-left; mobile drawer                    | A nested row's box narrower than a top-level row's, or a label moved from its per-depth position, fails.                                                               | `audit:SideNav/layout`   |
-| FR4       | Real-browser click in the indent area of plain, split, and actions rows               | Link and button rows; plain, modified, and middle clicks; nested rows with toggle and actions | A click in the indent that does nothing or differs from the same click on the primary element, or a toggle or action that activates the row, fails.                    | `audit:SideNav/behavior` |
-| FR5, AR2  | `SideNav.test.tsx` group clipping case and real-browser keyboard focus on nested rows | Only-child and last nested rows; after opening; collapsed                                     | A focus ring cut at any edge of an expanded group, or an expanded group that still clips, fails.                                                                       | `audit:SideNav/a11y`     |
-| FR2, FR3  | Real-browser collapsed rail and flyout                                                | Collapsed rail with nested children                                                           | Any change to the collapsed rail, or an indent on the flyout's top level, fails.                                                                                       | `audit:SideNav/layout`   |
-| AR1       | Accessibility-tree comparison of nested rows                                          | Plain, split, and actions rows                                                                | Any change in role, name, state, or order fails.                                                                                                                       | `audit:SideNav/a11y`     |
+| Contract  | Verification                                                                                                                                                                                   | Representative states                                                                                                                                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                   | Audit section            |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1, FR2  | `SideNav.test.tsx` nesting, collapsible, and collapsed-rail suites                                                                                                                             | Nested, collapsible, collapsed rail, flyout                                                                                                                                             | Removing the labelled group, its collapsed inert state, or the collapsed icon-only and flyout paths fails.                                                                                                                                                                                                                                                                                        | `audit:SideNav/anatomy`  |
+| FR3, ORD1 | Focused `SideNav.test.tsx` indent coverage, required with implementation                                                                                                                       | Depth 1 and 2; `sm` and `md`; split and actions rows; caller `style`; flyout                                                                                                            | A group inset, a missing or wrong indent, a dropped caller `style`, an indent that overrides a caller-set inline-start padding, or an indented flyout top level fails.                                                                                                                                                                                                                            | `audit:SideNav/layout`   |
+| FR3, DD1  | Real-browser geometry over the SideNav nested stories                                                                                                                                          | Depths 1–3; `sm`, `md`, `lg`; light and dark; right-to-left; mobile drawer                                                                                                              | A nested row's box narrower than a top-level row's, or a label moved from its per-depth position, fails.                                                                                                                                                                                                                                                                                          | `audit:SideNav/layout`   |
+| FR4       | Real-browser click in the indent area of plain, split, and actions rows                                                                                                                        | Link and button rows; plain, modified, and middle clicks; nested rows with toggle and actions                                                                                           | A click in the indent that does nothing or differs from the same click on the primary element, or a toggle or action that activates the row, fails.                                                                                                                                                                                                                                               | `audit:SideNav/behavior` |
+| FR5, AR2  | `SideNav.test.tsx` group clipping case and real-browser keyboard focus on nested rows                                                                                                          | Only-child and last nested rows; after opening; collapsed                                                                                                                               | A focus ring cut at any edge of an expanded group, or an expanded group that still clips, fails.                                                                                                                                                                                                                                                                                                  | `audit:SideNav/a11y`     |
+| FR2, FR3  | Real-browser collapsed rail and flyout                                                                                                                                                         | Collapsed rail with nested children                                                                                                                                                     | Any change to the collapsed rail, or an indent on the flyout's top level, fails.                                                                                                                                                                                                                                                                                                                  | `audit:SideNav/layout`   |
+| AR1       | Accessibility-tree comparison of nested rows                                                                                                                                                   | Plain, split, and actions rows                                                                                                                                                          | Any change in role, name, state, or order fails.                                                                                                                                                                                                                                                                                                                                                  | `audit:SideNav/a11y`     |
+| FR6       | `SideNavRailMotion.test.tsx`; `SideNavRailMotion.interaction.browser.spec.ts` frames of a collapse and an expand under a finger and a mouse (the `reducedMotion: 'always'` theme case pending) | collapse and expand; a mouse and a finger; Reduce Motion under a coarse and under a fine primary pointer; a theme with `reducedMotion: 'always'`; a second toggle while the motion runs | an animated width, a collapse that does not end icons-only, an expand that does not end with its labels, a rail copy reachable by assistive technology or left after the motion ends, travel under Reduce Motion, anything but an opacity-only change of 200 ms or less under Reduce Motion on a coarse pointer (DR2), or any animated property under Reduce Motion on a fine pointer (DR3) fails | `audit:SideNav/behavior` |
 
 ## Decision log
 
@@ -217,6 +225,18 @@ edges, so an open group must not clip them, or their focus ring is cut off.
 Rejected: indenting the nested group from outside the rows, because fills then
 start at a different edge per depth.
 
+### DEC-2 — The rail collapses by snap, clip, and cross-fade
+
+**Reference:** `component:SideNav/DEC-2`
+**Decider:** `cixzhang`, `2026-10-27`
+
+Animating the rail's width relays out the whole shell every frame. Snapping
+the layout to its final width, revealing or covering the rail by a clip, and
+cross-fading the content's old and new wrap on one shared clock moves only
+composited layers, and the rail ends in its real collapsed state.
+
+Rejected: animating the rail's width.
+
 ## Open questions
 
 None.