@astryxdesign/core 0.7.2-canary.55d8dff → 0.7.2-canary.577a62e

package/src/PowerSearch/PowerSearchValueEditor.test.tsx

@@ -80,6 +80,77 @@ function createSearchSource(
   };
 }
 
+describe('isDisabled reaches every built-in value editor', () => {
+  const items = [
+    {id: 'a', label: 'Alpha'},
+    {id: 'b', label: 'Beta'},
+  ];
+  const enumValues = [
+    {value: 'a', label: 'Alpha'},
+    {value: 'b', label: 'Beta'},
+  ];
+  const cases: ReadonlyArray<[string, OperatorValue]> = [
+    ['string', {type: 'string'}],
+    [
+      'string with a search source',
+      {type: 'string', searchSource: createSearchSource(items)},
+    ],
+    [
+      'string_list',
+      {type: 'string_list', searchSource: createSearchSource(items)},
+    ],
+    ['integer', {type: 'integer'}],
+    ['float', {type: 'float'}],
+    ['time', {type: 'time'}],
+    ['date_absolute', {type: 'date_absolute'}],
+    ['date_relative', {type: 'date_relative'}],
+    ['date_range', {type: 'date_range'}],
+    ['enum', {type: 'enum', values: enumValues}],
+    ['enum_list', {type: 'enum_list', values: enumValues}],
+    [
+      'entity_list',
+      {type: 'entity_list', searchSource: createSearchSource(items)},
+    ],
+  ];
+
+  // Every form control the editor renders outside a closed popover (a date
+  // input's calendar stays mounted while closed, and its disabled trigger
+  // cannot open it), so a disabled built-in editor leaves nothing a person
+  // can type into, press, or open.
+  function controlsOf(container: HTMLElement): HTMLElement[] {
+    return Array.from(
+      container.querySelectorAll<HTMLElement>(
+        'input, textarea, button, select, [role="combobox"], [contenteditable="true"]',
+      ),
+    ).filter(element => {
+      const popover = element.closest<HTMLElement>('[popover]');
+      return (
+        element.getAttribute('aria-hidden') !== 'true' &&
+        (popover == null || popover.matches(':popover-open'))
+      );
+    });
+  }
+
+  const isUnavailable = (element: HTMLElement) =>
+    (element as HTMLInputElement).disabled === true ||
+    element.getAttribute('aria-disabled') === 'true';
+
+  it.each(cases)('%s', (_name, operatorValue) => {
+    const {container} = render(
+      <PowerSearchValueEditor
+        operatorValue={operatorValue}
+        filterValue={undefined}
+        onChange={() => {}}
+        config={stubConfig}
+        isDisabled
+      />,
+    );
+    const controls = controlsOf(container);
+    expect(controls.length).toBeGreaterThan(0);
+    expect(controls.filter(element => !isUnavailable(element))).toEqual([]);
+  });
+});
+
 // =============================================================================
 // #1103 — StringEditor ignores searchSource
 // =============================================================================

package/src/PowerSearch/PowerSearchValueEditor.tsx

@@ -105,12 +105,14 @@ function StringEditor({
   onChange,
   onEnter: _onEnter,
   maxMenuItems,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'string'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue, shouldSave?: boolean) => void;
   onEnter?: () => void;
   maxMenuItems?: number;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const currentValue = filterValue?.type === 'string' ? filterValue.value : '';
@@ -126,6 +128,7 @@ function StringEditor({
       <Typeahead
         label={t('@astryx.powersearch.valueEditor.value')}
         isLabelHidden
+        isDisabled={isDisabled}
         searchSource={operatorValue.searchSource}
         value={selectedItem}
         onChange={item => {
@@ -146,6 +149,7 @@ function StringEditor({
     <TextInput
       label={t('@astryx.powersearch.valueEditor.value')}
       isLabelHidden
+      isDisabled={isDisabled}
       value={currentValue}
       placeholder={t('@astryx.powersearch.valueEditor.enterValuePlaceholder')}
       onChange={(value: string) => {
@@ -160,11 +164,13 @@ function StringListEditor({
   filterValue,
   onChange,
   maxMenuItems,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'string_list'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue) => void;
   maxMenuItems?: number;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const currentValue: SearchableItem[] = useMemo(() => {
@@ -194,6 +200,7 @@ function StringListEditor({
     <Tokenizer
       label={t('@astryx.powersearch.valueEditor.values')}
       isLabelHidden
+      isDisabled={isDisabled}
       searchSource={source}
       value={currentValue}
       onChange={items => {
@@ -278,11 +285,13 @@ function IntegerEditor({
   filterValue,
   onChange,
   onEnter,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'integer'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue, shouldSave?: boolean) => void;
   onEnter?: () => void;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const currentValue =
@@ -300,6 +309,7 @@ function IntegerEditor({
     <NumberInput
       label={t('@astryx.powersearch.valueEditor.value')}
       isLabelHidden
+      isDisabled={isDisabled}
       value={currentValue ?? null}
       onChange={handlers.handleChange}
       onFocus={handlers.handleFocus}
@@ -320,11 +330,13 @@ function FloatEditor({
   filterValue,
   onChange,
   onEnter,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'float'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue, shouldSave?: boolean) => void;
   onEnter?: () => void;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const currentValue =
@@ -342,6 +354,7 @@ function FloatEditor({
     <NumberInput
       label={t('@astryx.powersearch.valueEditor.value')}
       isLabelHidden
+      isDisabled={isDisabled}
       value={currentValue ?? null}
       onChange={handlers.handleChange}
       onFocus={handlers.handleFocus}
@@ -360,10 +373,12 @@ function TimeEditor({
   operatorValue,
   filterValue,
   onChange,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'time'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue) => void;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const currentValue =
@@ -375,6 +390,7 @@ function TimeEditor({
     <TimeInput
       label={t('@astryx.powersearch.valueEditor.time')}
       isLabelHidden
+      isDisabled={isDisabled}
       value={currentValue}
       onChange={value => {
         if (value != null) {
@@ -390,10 +406,12 @@ function TimeEditor({
 function DateAbsoluteEditor({
   filterValue,
   onChange,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'date_absolute'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue) => void;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   // Convert unixSeconds to ISO date string for the date input
@@ -409,6 +427,7 @@ function DateAbsoluteEditor({
     <DateInput
       label={t('@astryx.powersearch.valueEditor.date')}
       isLabelHidden
+      isDisabled={isDisabled}
       value={currentValue}
       onChange={value => {
         if (value != null) {
@@ -424,10 +443,12 @@ function DateRelativeEditor({
   operatorValue,
   filterValue,
   onChange,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'date_relative'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue, shouldSave?: boolean) => void;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const currentValue =
@@ -469,6 +490,7 @@ function DateRelativeEditor({
     <Selector
       label={t('@astryx.powersearch.valueEditor.relativeDate')}
       isLabelHidden
+      isDisabled={isDisabled}
       options={options}
       value={currentValue}
       onChange={value => {
@@ -481,10 +503,12 @@ function DateRelativeEditor({
 function DateRangeEditor({
   filterValue,
   onChange,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'date_range'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue) => void;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const currentValue = useMemo<DateRange | null>(() => {
@@ -534,6 +558,7 @@ function DateRangeEditor({
       <DateRangeInput
         label={t('@astryx.powersearch.valueEditor.dateRange')}
         isLabelHidden
+        isDisabled={isDisabled}
         value={currentValue}
         onChange={handleChange}
         hasClear={false}
@@ -546,10 +571,12 @@ function EnumEditor({
   operatorValue,
   filterValue,
   onChange,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'enum'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue, shouldSave?: boolean) => void;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const currentValue =
@@ -568,6 +595,7 @@ function EnumEditor({
     <Selector
       label={t('@astryx.powersearch.valueEditor.value')}
       isLabelHidden
+      isDisabled={isDisabled}
       options={options}
       value={currentValue}
       onChange={value => {
@@ -581,10 +609,12 @@ function EnumListEditor({
   operatorValue,
   filterValue,
   onChange,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'enum_list'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue) => void;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const items = useMemo(
@@ -608,6 +638,7 @@ function EnumListEditor({
     <Tokenizer
       label={t('@astryx.powersearch.valueEditor.values')}
       isLabelHidden
+      isDisabled={isDisabled}
       searchSource={source}
       value={currentValue}
       onChange={selectedItems => {
@@ -632,11 +663,13 @@ function EntityListEditor({
   filterValue,
   onChange,
   maxMenuItems,
+  isDisabled,
 }: {
   operatorValue: OperatorValue & {type: 'entity_list'};
   filterValue: FilterValue | undefined;
   onChange: (value: FilterValue) => void;
   maxMenuItems?: number;
+  isDisabled?: boolean;
 }) {
   const t = useTranslator();
   const source = useMemo<SearchSource<SearchableItem>>(() => {
@@ -665,6 +698,7 @@ function EntityListEditor({
     <Tokenizer
       label={t('@astryx.powersearch.valueEditor.entities')}
       isLabelHidden
+      isDisabled={isDisabled}
       searchSource={source}
       value={currentValue}
       onChange={items => {
@@ -738,6 +772,7 @@ export function PowerSearchValueEditor({
     case 'string':
       return (
         <StringEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -749,6 +784,7 @@ export function PowerSearchValueEditor({
     case 'string_list':
       return (
         <StringListEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -759,6 +795,7 @@ export function PowerSearchValueEditor({
     case 'integer':
       return (
         <IntegerEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -769,6 +806,7 @@ export function PowerSearchValueEditor({
     case 'float':
       return (
         <FloatEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -779,6 +817,7 @@ export function PowerSearchValueEditor({
     case 'time':
       return (
         <TimeEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -788,6 +827,7 @@ export function PowerSearchValueEditor({
     case 'date_absolute':
       return (
         <DateAbsoluteEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -797,6 +837,7 @@ export function PowerSearchValueEditor({
     case 'date_relative':
       return (
         <DateRelativeEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -806,6 +847,7 @@ export function PowerSearchValueEditor({
     case 'date_range':
       return (
         <DateRangeEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -815,6 +857,7 @@ export function PowerSearchValueEditor({
     case 'enum':
       return (
         <EnumEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -824,6 +867,7 @@ export function PowerSearchValueEditor({
     case 'enum_list':
       return (
         <EnumListEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}
@@ -833,6 +877,7 @@ export function PowerSearchValueEditor({
     case 'entity_list':
       return (
         <EntityListEditor
+          isDisabled={isDisabled}
           operatorValue={operatorValue}
           filterValue={filterValue}
           onChange={onChange}

package/src/Resizable/useResizable.doc.mjs

@@ -15,7 +15,6 @@ export const docs = {
     'divider',
     'splitter',
     'splitpane',
-    'splitview',
     'resizablepanels',
   ],
   params: [

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.