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

package/src/RadioList/RadioList.tsx

@@ -31,6 +31,7 @@ import type {InputStatus} from '../Field/types';
 import {useTooltip} from '../Tooltip';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {composeEventHandlers, mergeProps} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 import {
   type FieldInputBaseProps,
   useFieldInputStyling,
@@ -216,6 +217,7 @@ export function RadioList({
   htmlName,
   children,
   onFocus,
+  'aria-labelledby': ariaLabelledByProp,
   'aria-describedby': ariaDescribedByProp,
   ...restProps
 }: RadioListProps) {
@@ -399,7 +401,8 @@ export function RadioList({
           disabledMessageTooltip.ref(el);
         }}
         role="radiogroup"
-        aria-labelledby={labelID}
+        // A caller aria-labelledby names the group together with its label.
+        aria-labelledby={joinAriaIDs(labelID, ariaLabelledByProp)}
         onFocus={composeEventHandlers(handleFocus, onFocus)}
         aria-describedby={
           [

package/src/RadioList/RadioListItem.doc.mjs

@@ -43,6 +43,13 @@ export const docs = {
       description:
         'Secondary content displayed below the label. Links and buttons keep their own click behaviour — the row only delegates clicks from its non-interactive surface to the radio.',
     },
+    {
+      name: 'align',
+      type: "'center' | 'start' | 'first-line'",
+      description:
+        'Vertical alignment of the start and end content against the label, passed through to Item unchanged. `first-line` keeps a small mark (a radio) level with the first line of a wrapped label. See Item.align.',
+      default: "'center'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -117,6 +124,13 @@ export const docsZh = {
       description:
         '显示在标签下方的次要内容。链接和按钮保留自身的点击行为——整行仅将非交互区域的点击委派给单选框。',
     },
+    {
+      name: 'align',
+      type: "'center' | 'start' | 'first-line'",
+      description:
+        '起始和结束内容相对于标签的垂直对齐方式，原样传递给 Item。`first-line` 让小标记（单选按钮）与换行标签的第一行保持水平。参见 Item.align。',
+      default: "'center'",
+    },
     {
       name: 'isDisabled',
       type: 'boolean',
@@ -142,6 +156,8 @@ export const docsDense = {
   displayName: 'Radio List Item',
   description: 'Individual radio item w/ label, description, content slots.',
   propDescriptions: {
+    align:
+      "Start/end content alignment, passed to Item: 'center' (default), 'start', or 'first-line' (centered on the label's first line).",
     label:
       'Primary label. String or ReactNode; nested controls keep their behavior.',
     'aria-label':

package/src/RadioList/RadioListItem.tsx

@@ -29,7 +29,7 @@ import {indicatorScope} from '../Indicator/indicator.markers.stylex';
 import {useIndicatorFocusRing} from '../hooks/useIndicatorFocusRing';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import {useIndicator} from '../Indicator';
-import {Item} from '../Item';
+import {Item, type ItemAlign} from '../Item';
 import {themeProps} from '../utils/themeProps';
 
 // The touch press's paint, declared by the shared overlay styles on the
@@ -156,6 +156,13 @@ const rowStyles = stylex.create({
 
 export interface RadioListItemProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
+  /**
+   * Vertical alignment of the start and end content against the label,
+   * forwarded to Item. Use `first-line` to keep the radio level with the
+   * first line of a wrapped label.
+   * @default 'center'
+   */
+  align?: ItemAlign;
   /**
    * Primary label for the radio item.
    *
@@ -232,6 +239,7 @@ export function RadioListItem({
   isDisabled: isItemDisabled = false,
   startContent,
   endContent,
+  align,
   xstyle,
   className,
   style,
@@ -366,6 +374,7 @@ export function RadioListItem({
         ) : undefined
       }
       endContent={endContent}
+      align={align}
       xstyle={
         [
           // Hover reaches the radio visual through this ancestor marker rather

package/src/Resizable/useResizable.doc.mjs

@@ -14,6 +14,8 @@ export const docs = {
     'sidebar',
     'divider',
     'splitter',
+    'splitpane',
+    'resizablepanels',
   ],
   params: [
     {

package/src/ScrollableArea/ScrollableArea.doc.mjs

@@ -5,7 +5,7 @@ export const docs = {
   name: 'ScrollableArea',
   displayName: 'Scrollable Area',
   category: 'Layout',
-  keywords: ['scroll', 'overflow', 'viewport', 'logical axis', 'keyboard', 'overscroll', 'sticky', 'scrollbar', 'padding', 'full bleed'],
+  keywords: ['scroll', 'overflow', 'viewport', 'logical axis', 'keyboard', 'overscroll', 'sticky', 'scrollbar', 'padding', 'full bleed', 'scrollarea', 'scrollview'],
   usage: {
     description: 'Provides a native scroll viewport and a real observed content box. The viewport enters the tab order only while a requested logical axis is effectively scrollable, and containment applies only to effective axes.',
     bestPractices: [

package/src/Selector/hooks.ts

@@ -6,8 +6,12 @@
  * @file hooks.ts
  * @input Uses untransformed DOM layout geometry from the Selector's outer
  *   anchor, listbox, and selected option
- * @output Hooks for Selector
- * @position Internal hooks; used by Selector.tsx
+ * @output Hooks for Selector: useSelectedItemOffset, and useCombobox (public,
+ *   exported from the Selector entry point; also used by CommandPalette)
+ * @position Selector hooks; used by Selector.tsx and CommandPalette
+ *
+ * SYNC: When useCombobox's options or return change, update:
+ * - /packages/core/src/Selector/useCombobox.doc.mjs
  */
 
 import {useCallback, useState} from 'react';

package/src/Selector/useCombobox.doc.mjs

@@ -0,0 +1,237 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useCombobox',
+  displayName: 'useCombobox',
+  group: 'Selector',
+  keywords: [
+    'combobox',
+    'listbox',
+    'select',
+    'dropdown',
+    'highlight',
+    'active option',
+    'aria-activedescendant',
+    'keyboard',
+    'arrow keys',
+    'headless',
+    'apg',
+    'accessibility',
+    'a11y',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseComboboxOptions',
+      description: 'Configuration object.',
+      required: true,
+    },
+    {
+      name: 'options.selectableItems',
+      type: 'SelectorOptionData[]',
+      description:
+        'The options in the same order as they render. Options with `disabled` cannot be picked and are skipped while moving through the open list; ArrowDown or ArrowUp that opens the list still lands on the first or last option.',
+      required: true,
+    },
+    {
+      name: 'options.isOpen',
+      type: 'boolean',
+      description: 'Whether the list is shown. The caller owns this state.',
+      required: true,
+    },
+    {
+      name: 'options.onOpen',
+      type: '() => unknown',
+      description:
+        'Called to show the list. Return `false` to refuse; the hook then leaves the highlight alone.',
+      required: true,
+    },
+    {
+      name: 'options.onClose',
+      type: '() => void',
+      description:
+        'Called when the hook hides the list; the hook resets the highlight first. When the caller closes the list itself (an outside press, say), it should also call `setHighlightedIndex(-1)`.',
+      required: true,
+    },
+    {
+      name: 'options.listboxId',
+      type: 'string',
+      description:
+        "The listbox element's id. Option ids are derived from it through `getItemId`.",
+      required: true,
+    },
+    {
+      name: 'options.value',
+      type: 'string',
+      description:
+        'The selected value. Without search, opening by a press, Enter or Space highlights it, or the first option when nothing is selected; ArrowDown and ArrowUp open on the first and last option.',
+    },
+    {
+      name: 'options.onSelect',
+      type: '(value: string) => void',
+      description:
+        'Called with the picked value. Picking also closes the list.',
+    },
+    {
+      name: 'options.onClear',
+      type: '() => void',
+      description:
+        'Clears the value. When provided, Delete or Backspace on the closed control clears it, so clearing is not pointer-only. Ignored while the list is open or with `hasSearch`.',
+    },
+    {
+      name: 'options.hasSearch',
+      type: 'boolean',
+      description:
+        'Whether the list has its own search field. Space then types instead of picking, opening by a press or Enter does not pre-highlight (ArrowDown and ArrowUp still open on the first and last option), and printable keys on the closed control go to `onSearchSeed`.',
+      default: 'false',
+    },
+    {
+      name: 'options.onSearchSeed',
+      type: '(char: string) => void',
+      description:
+        'With `hasSearch`, receives each printable character except Space typed while the control has focus, opening the list first when it is closed, so type-to-find needs no separate open step.',
+    },
+    {
+      name: 'options.isDisabled',
+      type: 'boolean',
+      description: 'Whether the control ignores clicks and keys.',
+      default: 'false',
+    },
+  ],
+  returns: [
+    {
+      name: 'highlightedIndex',
+      type: 'number',
+      description:
+        'Index of the active option, or -1 when none is active. With `hasSearch`, opening by a press or Enter does not set one, so it stays -1 after the hook itself closes the list; ArrowDown and ArrowUp still open on the first or last option. Render it as the active option and name it in `aria-activedescendant` only while it points at a rendered option.',
+    },
+    {
+      name: 'setHighlightedIndex',
+      type: '(index: number) => void',
+      description:
+        'Sets the active option, for example from a filter that changes the options.',
+    },
+    {
+      name: 'getItemId',
+      type: '(index: number) => string',
+      description:
+        "The id to render on the option at `index`. Set the control's `aria-activedescendant` to `isOpen && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined`, so it never names an option that does not exist, including in an empty list.",
+    },
+    {
+      name: 'onTriggerClick',
+      type: '() => void',
+      description: 'Toggles the list from a press on the control.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: React.KeyboardEvent) => void',
+      description:
+        'Key handler for the control that keeps focus. ArrowDown and ArrowUp open the list or move the active option; Enter (and Space without search) picks it or opens the list; Escape and Tab close it; Home, End, PageUp and PageDown jump to the first or last option. An editable control that keeps Home and End for the caret does not pass them to this handler, as CommandPalette does.',
+    },
+    {
+      name: 'onItemSelect',
+      type: '(item: SelectorOptionData) => void',
+      description: 'Picks an option from a press on it, then closes the list.',
+    },
+    {
+      name: 'onItemMouseEnter',
+      type: '(item: SelectorOptionData, index: number) => void',
+      description:
+        'Makes the hovered option active without scrolling the list or moving focus.',
+    },
+  ],
+  usage: {
+    description:
+      'Tracks the active option of a single-select combobox and handles its keys, while DOM focus stays on the control. It powers Selector and CommandPalette; use it to build a combobox those components do not cover. It renders nothing and sets no attributes: the caller renders the control, the listbox and the options, and wires `role`, `aria-expanded`, `aria-controls` and `aria-activedescendant` from what it returns.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Render each option with `id={getItemId(index)}` and set the control's `aria-activedescendant` only while `isOpen` and `highlightedIndex` points at a rendered option, as CommandPalette does.",
+      },
+      {
+        guidance: true,
+        description:
+          "For type-to-select without a search field, run useTypeahead's handler first and fall through to this `onKeyDown` when it returns false, as Selector does.",
+      },
+      {
+        guidance: true,
+        description:
+          'Announce the number of results through useAnnounce when the options change for a new query.',
+      },
+      {
+        guidance: false,
+        description:
+          'Move DOM focus onto the options; the active option is announced through `aria-activedescendant` while focus stays on the control.',
+      },
+    ],
+  },
+  relatedComponents: ['Selector', 'CommandPalette'],
+  relatedHooks: ['useMultiCombobox', 'useTypeahead', 'useAnnounce'],
+  importPath: '@astryxdesign/core/Selector',
+  category: 'focus',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Single-select combobox state + keys; focus stays on control. Powers Selector / CommandPalette. Renders nothing, sets no attrs: caller renders control / listbox / options and wires role, aria-expanded, aria-controls, aria-activedescendant.',
+  paramDescriptions: {
+    options: 'config.',
+    'options.selectableItems':
+      'options in render order; disabled ones not pickable, skipped while moving in open list (ArrowDown/Up opening still lands first / last).',
+    'options.isOpen': 'list shown; caller owns state.',
+    'options.onOpen':
+      'show list; return false to refuse (highlight untouched).',
+    'options.onClose':
+      'hook hides list; resets highlight first. caller closing itself (outside press): also setHighlightedIndex(-1).',
+    'options.listboxId': 'listbox id; option ids derive from it (getItemId).',
+    'options.value':
+      'selected value; w/o search, press / Enter / Space opening highlights it (else first); ArrowDown/Up open on first / last.',
+    'options.onSelect': 'called w/ picked value; picking closes.',
+    'options.onClear':
+      'clears value; Delete / Backspace on closed control. ignored when open or hasSearch.',
+    'options.hasSearch':
+      'list has own search field: Space types, press / Enter opening does not pre-highlight (ArrowDown/Up still first / last), printable keys on closed control -> onSearchSeed.',
+    'options.onSearchSeed':
+      'w/ hasSearch, each printable char except Space typed while control focused (opens first if closed).',
+    'options.isDisabled': 'ignore clicks + keys.',
+  },
+  returnDescriptions: {
+    highlightedIndex:
+      'active option index, -1 = none. hasSearch: press / Enter opening sets none (stays -1 after hook closes); ArrowDown/Up still first / last. name in aria-activedescendant only when it points at a rendered option.',
+    setHighlightedIndex: 'set active option (e.g. after filtering).',
+    getItemId:
+      'id for option at index; aria-activedescendant = isOpen && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined (empty list safe).',
+    onTriggerClick: 'toggle list from a press on control.',
+    onKeyDown:
+      'control keydown: ArrowDown/Up open or move; Enter (Space w/o search) picks or opens; Escape / Tab close; Home / End / PageUp / PageDown jump. editable control keeping Home / End for caret: do not pass them.',
+    onItemSelect: 'pick from a press, then close.',
+    onItemMouseEnter: 'hover makes option active; no scroll, no focus move.',
+  },
+  usage: {
+    description:
+      'Headless single-select combobox: active option + keys, focus stays on control. Caller renders + wires ARIA.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Option id = getItemId(index); aria-activedescendant only while open and highlightedIndex points at a rendered option.',
+      },
+      {
+        guidance: true,
+        description:
+          'Type-to-select w/o search: run useTypeahead first, fall through when it returns false.',
+      },
+      {
+        guidance: true,
+        description: 'Announce result count via useAnnounce on new query.',
+      },
+      {
+        guidance: false,
+        description: 'Move DOM focus onto options; use aria-activedescendant.',
+      },
+    ],
+  },
+};

package/src/SideNav/SideNav.spec.md

@@ -0,0 +1,227 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:SideNav
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-16
+owners: [cixzhang]
+review_triggers: [layout, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/SideNav/SideNav.test.tsx,
+    apps/storybook/stories/SideNav.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:internationalization,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-017/FR3]
+---
+
+# SideNav component contract
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+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.
+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.                                                                                                                    |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+SideNav is the vertical navigation region of an app. SideNavItem rows can nest
+to show a hierarchy of destinations. Nesting must read as one list of equal
+rows, so the eye compares labels and states across depths rather than seeing a
+second, narrower kind of row. SideNav owns this because only SideNavItem knows
+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.
+- Compatibility class: nonbreaking appearance change of visual direction under
+  `spec:AST-017/FR3`; no public API, accepted input, or accessibility semantic
+  changes.
+- Controlled/uncontrolled behavior: unchanged.
+- Migration decision: none; there is no supported way to keep the inset look.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The width of every expanded SideNavItem row, at every depth.
+- Where a nested row's indent sits, its step, and how it adds to the row's
+  padding.
+- What the indent area paints and what a click on it does.
+- Whether the nested group clips its rows.
+
+**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.
+- 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.
+
+## Public concepts
+
+| Concept       | Closed values or states                        | Meaning                                                                                                     | Availability by variant/orientation/state | Default | Owner               | Stability | Invalid-value behavior |
+| ------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------- | ------------------- | --------- | ---------------------- |
+| Nesting depth | `0`, `1`, `2`, … (derived, not a prop)         | The number of SideNavItem ancestors of a row within the same list. A collapsed rail's flyout restarts at 0. | Expanded rail; mobile drawer; flyout      | `0`     | `component:SideNav` | stable    | Not caller-settable    |
+| Row size      | `sm`, `md`, `lg` (existing SideNavItem `size`) | Sets the row's height and base inline padding; the indent adds to that padding.                             | Every row                                 | `md`    | `component:SideNav` | stable    | Rejected by the type   |
+
+## 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 |
+
+### Allowed variation
+
+- **AV1 — Depth and size.** Any depth and any row size may appear; FR3 holds for
+  each row from its own size's padding.
+- **AV2 — Theme tokens.** A theme that changes `--spacing-6` or the row padding
+  tokens changes the step or the base with them.
+- **AV3 — Row implementation.** The element that carries the indent may change
+  while the painted row stays full width and the indent stays clickable.
+
+### Representative states
+
+| State                                 | Required invariant                                                                        | Allowed variation               |
+| ------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------- |
+| Depth 1–3, `md`                       | Row width equals a top-level row's; content starts one step further in per level.         | Labels, icons, selection.       |
+| `sm` and `lg` nested rows             | Indent adds to that size's base padding.                                                  | Row height by size.             |
+| Nested row with own link and children | Full-width row; indent is part of the link; the expand toggle stays at the trailing edge. | Collapsed or expanded children. |
+| Nested row with `actions`             | Full-width row; indent is part of the primary element; actions stay at the trailing edge. | Action content.                 |
+| Keyboard focus on a nested row        | The focus ring paints in full around the row.                                             | Ring style by theme.            |
+| Right-to-left                         | Indent sits at the inline start (right); same widths.                                     | Writing direction.              |
+| Collapsed rail                        | Icon-only items; the flyout's top level has no indent; deeper flyout levels indent.       | Flyout content.                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Row inline-start padding.** The row's size padding, then plus depth ×
+  `--spacing-6`. A caller's `style` on a nested item composes after the indent in the
+  shared order (`architecture:public-component-api`): properties the caller does
+  not set keep the indent, and a caller-set inline-start padding replaces it.
+
+### Performance and resources
+
+- **PR1 — No measurement.** Depth and indent come from composition; no
+  measurement, observer, or extra render pass is added.
+
+## Accessibility contract
+
+- **AR1 — Presentation only.** Width and indent MUST NOT change any row's role,
+  accessible name, state, DOM order, or tab order.
+- **AR2 — Visible focus.** A nested row's focus indicator MUST paint in full at
+  every depth (FR5).
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                 | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
+| Navigation items | Nested rows read as equal rows of one list; depth reads as indent. | Owner choice (DD1)       | Prominent      | FR3–FR5            |
+
+### Design decisions
+
+<!-- design-decisions:v1 -->
+
+| ID  | Decision                                                                                                                                                                                                         | Intent or reason                                                                                                                                                                                            | Applies to                                                                                         | Allowed variation                                                                                            |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| DD1 | Every SideNavItem row spans the full width of its nav list at any depth; nesting shows as indent inside the row, ahead of its content. Hover, pressed, selected, and focus paint the whole row, indent included. | Fills line up across depths, so the nav reads as one list of equal rows while labels keep their per-level alignment; the indent belongs to the row's primary target rather than sitting beside it as a gap. | SideNavItem rows at every depth, at rest and through hover, pressed, selected, disabled, and focus | Themes restyle fill, radius, and padding through the `side-nav-item` target; the step follows `--spacing-6`. |
+
+## Family and system relationships
+
+- `family:navigation-destinations` owns the accept/block result for a
+  SideNavItem `href`; the indent area activates the same destination the primary
+  element does (FR4).
+- `architecture:internationalization` owns logical direction; the indent is
+  inline-start and mirrors under right-to-left.
+- `architecture:interaction-modality` owns shared focus-visible behavior; FR5
+  keeps the ring visible at every depth.
+- `architecture:component-theming-surface` owns the `side-nav-item` target;
+  this record adds no target or state.
+- `architecture:public-component-api` owns how caller styling inputs compose;
+  ORD1 places the indent before a caller's `style`.
+- `spec:AST-017/FR3` classifies the change as a nonbreaking change of visual
+  direction.
+- `component:TreeList` DD1–DD3 record the same row geometry for TreeList. They
+  are precedent, not authority here; each component owns its own rows.
+
+## 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`     |
+
+## Decision log
+
+<!-- Record the boundary or requirement, not how it was reached. A rejected alternative is at most one line here, kept only when it is consequential and likely to recur. -->
+
+### DEC-1 — Nested rows are full width; depth is indent inside the row
+
+**Reference:** `component:SideNav/DEC-1`
+**Decider:** cixzhang, 2026-10-16
+
+A nested row that starts at its indent paints its fills from a different edge
+than the rows above it, so it reads as a different, narrower component. A row that
+spans the full width with its indent inside lines up every fill and keeps each
+label at its per-depth position. The indent is part of the row's primary
+target, so it acts as well as lights up. Full-width rows reach the nested group's
+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.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.