@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/SideNav/SideNavHeading.spec.md

@@ -1,226 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:SideNavHeading
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-25
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility]
-verified_by:
-  [
-    packages/core/src/SideNav/SideNav.test.tsx,
-    apps/storybook/stories/SideNav.stories.tsx,
-  ]
-modules: []
-families:
-  [
-    family:navigation-destinations,
-    family:overlay-dismissal,
-    family:action-groups,
-  ]
-design_specs: []
-architecture:
-  [
-    architecture:component-style-authoring,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-  ]
-contributing: []
-system_specs: []
----
-
-# SideNavHeading component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                           |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `SideNavHeading` with `icon`, `heading`, `superheading`, `subheading`, their `*Href` links, `headerEndContent`, `menu`, and `as`; target `side-nav-heading`.                                                                       |
-| Behavior                | The product identity block at the top of SideNav. Which parts are links and which part opens the menu follows from the `*Href` props and `menu`; in a collapsed rail it is an icon-only link, menu button, or icon with a tooltip. |
-| End-user impact         | Users reach product, suite, and account destinations and a product menu, in both the expanded and the collapsed rail; screen-reader users hear named links, a named trigger, and a named menu.                                     |
-| Builder impact          | None.                                                                                                                                                                                                                              |
-| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps (see Current-state impact).                                                                                                                                    |
-| Review checks           | Reject a collapsed icon without a name, a menu popup wrapped in a modal dialog, a heading button inside `role="menu"`, or `headerEndContent` rendered inside the whole-heading link.                                               |
-| Governing rules         | `architecture:public-component-api` INV5; `architecture:interaction-modality`; `family:navigation-destinations`.                                                                                                                   |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-SideNavHeading presents the product's icon and name, with optional suite and
-account lines, at the top of SideNav. It owns how those parts become links or a
-menu trigger, the product menu popover, and the collapsed-rail form. Consumer
-usage lives in `SideNavHeading.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: the menu's open state is internal
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Some configurations drop DOM props.** Other DOM props passed to
-  SideNavHeading (beyond `data-testid`, `className`, `style`, `xstyle`, and
-  `ref`) reach no element in the menu configurations and in the collapsed link
-  and menu-button forms. `architecture:public-component-api` INV5 requires
-  accepted DOM, data, ARIA, and event inputs to reach the owning element.
-
-- **NavHeadingMenu nests a second menu.** The heading wraps `menu` in its own
-  `role="menu"`; NavHeadingMenu, the documented `menu` content, adds another
-  `role="menu"` inside it. WAI-ARIA 1.2 allows a `menu` to own only
-  `menuitem`-family items and groups.
-- **Links nested in the popover's heading button.** In the expanded
-  links-plus-trigger configuration, the popover's heading button repeats the
-  superheading, heading, and subheading links inside itself, so interactive
-  content is nested inside a button. HTML forbids interactive content inside a
-  `<button>`.
-- **The open menu repeats the identity row.** While the menu is open, its
-  heading button repeats the icon and text that stay mounted in the rail's block,
-  so that content renders twice. `architecture:component-style-authoring` INV7
-  has content render once.
-- **Links in the links-plus-trigger form also open the menu.** The block that
-  holds the links carries the menu's trigger handlers. With touch or the
-  keyboard, activating the heading or suite link both navigates and opens the
-  menu, moving focus to its first item. With a mouse, moving the pointer onto
-  the block opens the menu at once over it, so a click lands on the menu's heading button, with its repeated links, rather than on the link underneath. Both break FR2's split between
-  the links and the menu trigger.
-- **End content also opens the menu.** In both menu configurations
-  `headerEndContent` renders inside the block that carries the menu's trigger
-  handlers. With touch or the keyboard, activating a control there runs that
-  control and also opens the menu, moving focus to its first item. With a mouse,
-  moving the pointer onto the links or end content opens the menu at once over
-  the whole block, so a click on end content lands on the menu's heading button
-  and the menu reopens under the pointer. A control in end content is the
-  caller's, outside FR2's trigger area.
-
-## Ownership boundary
-
-**Owns**
-
-- The identity block and its link and trigger configurations (FR1–FR4).
-- The product menu popover (FR5–FR7).
-- The collapsed-rail form (FR8) and the focus outline (FR9).
-
-**Does not own / non-goals**
-
-- Destination acceptance and blocking — owned by
-  `family:navigation-destinations`.
-- Menu content — owned by the caller (typically NavHeadingMenu).
-- The rail's collapsed state — owned by SideNav.
-
-## Public concepts
-
-| Concept       | Closed values or states                                                                              | Meaning                                          | Availability by variant/orientation/state | Default | Owner                      | Stability | Invalid-value behavior |
-| ------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------- | ------- | -------------------------- | --------- | ---------------------- |
-| Configuration | plain, whole link, whole link with end content, independent links, whole trigger, links plus trigger | Derived from the `*Href` props and `menu` (FR2). | Expanded rail.                            | Plain   | `component:SideNavHeading` | Stable    | Not applicable.        |
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Basis                    |
-| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1  | In an expanded rail the block carries `side-nav-heading` and shows the icon, a text column (superheading, a heading row, subheading; plain-text lines and the menu-configuration heading link stay on one line with ellipsis, while lines rendered through the Link component wrap), and `headerEndContent`. With `menu`, the heading row holds the heading then the chevron button; without `menu` there is no chevron.                                                                                                                                                                                                                                                                              | Current source and tests |
-| FR2  | `headingHref` alone without `menu` makes the icon and text one link; with `headerEndContent` that content sits beside the link, not inside it. Other `*Href` props without `menu` make each line with an href its own link, and a linked icon is named by `heading`. `menu` without hrefs makes the whole block, apart from `headerEndContent`, open the menu; `menu` with hrefs makes each line with an href its own link, and the chevron button and the rest of the block, apart from `headerEndContent`, open the menu.                                                                                                                                                                           | Current source and tests |
-| FR3  | The icon link, the whole-heading link, and the menu-configuration heading link use the `as` component, else the `LinkProvider` link, else `<a>`. Supporting lines, and the heading line in the independent-links configuration, use the Link component, which does not receive `as`.                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
-| FR4  | The chevron button is named by `@astryx.sideNav.heading.openMenu` and is the popover's trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR5  | On a hover-capable pointer, hovering opens the menu immediately and does not move focus; a click opens it and moves focus to the first menu item; a click within 500 ms of a hover-open keeps it open; Escape closes it and returns focus to the trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests |
-| FR6  | The menu is a non-modal popover below the block, aligned to its start; in the expanded rail it overlaps the block. It contains a heading button that closes the menu (see Current-state impact for its content), then a `role="menu"` named by `heading` that holds `menu`.                                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
-| FR7  | Only the collapsed menu form gives `menu` descendants the close action NavMenu items call on selection; the expanded menu forms do not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source           |
-| FR8  | In a collapsed rail, without `icon` it renders nothing. With `icon`: `headingHref` makes an icon-only link named by `heading`; else `menu` makes an icon-only button named by `heading` that is the native invoker of its menu popover; else the icon renders alone. Each form shows a tooltip with `heading` at the inline end; `headerEndContent` and the chevron are hidden.                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR9  | Every focusable part paints the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source and tests |
-| FR10 | In the product menu's `role="menu"` region, a press (finger, pen or mouse) that lands on an enabled item and slides across the items acts on the one it lifts on, once, through that item's own activation, with the highlight following the pointer; a lift outside acts on nothing, and a mouse released outside closes the menu. The menu adopts `module:DropdownMenu/useMenuPress` for this (`family:action-groups` FR1–FR5; `module:DropdownMenu/useMenuPress` DEC-7). A press on caller content that is not an item, and a Ctrl-, Cmd- or Shift-click or a middle click on a link item, stays that content's or the browser's own, and keyboard and assistive-technology behavior is unchanged. | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Lines.** Any combination of lines may be present; the block keeps its
-  order.
-
-### Representative states
-
-| State                       | Required invariant                                | Allowed variation |
-| --------------------------- | ------------------------------------------------- | ----------------- |
-| Whole link with end content | End content beside the link.                      | —                 |
-| Menu, no hrefs              | Whole block triggers; named chevron button.       | Menu content.     |
-| Menu with hrefs             | Links; chevron and the rest of the block trigger. | —                 |
-| Collapsed with menu         | Named icon button; flyout menu; tooltip.          | —                 |
-| Collapsed without icon      | Nothing renders.                                  | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Collapsed form.** `headingHref`, then `menu`, then plain icon.
-
-### Performance and resources
-
-- No resource rule.
-
-## Accessibility contract
-
-- **AR1 — Named icons.** A linked or button icon without visible text is named
-  by `heading`.
-- **AR2 — Menu semantics.** The popup is not a modal dialog; `role="menu"` wraps
-  only the menu content.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                              | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | ----------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Icon             | Leading product mark; alone when collapsed.     | Current source and public docs | Prominent      | FR1, FR8           |
-| Heading lines    | Superheading, heading, subheading.              | Current source and public docs | Prominent      | FR1                |
-| Menu popover     | Overlaps the block; a heading button closes it. | Current source                 | Supporting     | FR6                |
-
-`SideNavHeading.doc.mjs` declares no anatomy of its own, so no anatomy-theming
-map is recorded.
-
-## Family and system relationships
-
-- `family:overlay-dismissal` owns Escape and close-request ordering for this
-  component's popover.
-- `family:navigation-destinations` owns the accept/block decision for each
-  `href`.
-- NavHeadingMenu items close this menu where the close action is provided
-  (FR7).
-
-## Verification map
-
-| Contract     | Verification                                                                  | Representative states                                                            | Mutation or failure expectation                              | Audit section                        |
-| ------------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------ |
-| FR1–FR4, AR1 | `SideNav.test.tsx` SideNavHeading and headerEndContent suites                 | Each configuration                                                               | Wrong element, unnamed link, or misplaced end content fails. | `audit:SideNavHeading/behavior`      |
-| FR5          | `SideNav.test.tsx` SideNavHeading hover/click guard suite                     | Hover, click, late click, Escape                                                 | Lost guard or focus return fails.                            | `audit:SideNavHeading/behavior`      |
-| FR6, AR2     | `SideNav.test.tsx` menu popover semantics suite                               | Whole trigger; mixed; collapsed                                                  | A dialog wrapper or misplaced menu role fails.               | `audit:SideNavHeading/accessibility` |
-| FR8          | `SideNav.test.tsx` SideNavHeading collapsed suite                             | Link, menu, plain, no icon                                                       | Missing name, tooltip, or invoker fails.                     | `audit:SideNavHeading/behavior`      |
-| FR9          | `SideNav.test.tsx` focus ring suite                                           | Whole-heading link, collapsed link, menu trigger                                 | A missing shared ring class fails.                           | `audit:SideNavHeading/accessibility` |
-| FR10         | `SideNav.test.tsx` SideNavHeading menu-popover suite (touch and mouse slides) | Touch and mouse slides across items; a caller button and link; a release outside | Removing the adoption fails the slide tests.                 | —                                    |
-
-Read from source, with no focused test yet:
-
-- FR1: the forwarded `ref`, the `side-nav-heading` target, the order of parts,
-  and one-line truncation.
-- FR2: that the rest of the block opens the menu in the links-plus-trigger
-  configuration.
-- FR3: `as` on the icon and menu-configuration heading links, and the Link
-  component for the other lines.
-- FR5: that hover opens the menu without delay.
-- FR6: the popover's placement and the menu's name.
-- FR7; FR8's tooltip placement at the inline end; and FR9 on the popover's
-  heading button and the linked icon.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, or popover
-mechanics. It links to their owners.

package/src/SideNav/SideNavItem.spec.md

@@ -1,236 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:SideNavItem
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-25
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility]
-verified_by:
-  [
-    packages/core/src/SideNav/SideNav.test.tsx,
-    apps/storybook/stories/SideNav.stories.tsx,
-  ]
-modules: []
-families: [family:navigation-destinations, family:overlay-dismissal]
-design_specs: [design:reduced-motion]
-architecture:
-  [
-    architecture:component-size-cascade,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-  ]
-contributing: []
-system_specs: [spec:AST-085]
----
-
-# SideNavItem component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                      |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `SideNavItem` with `label`, `href`, `as`, `onClick`, `icon`, `selectedIcon`, `isSelected`, `isDisabled`, `endContent`, `actions`, `children`, `collapsible`, and `size`; target `side-nav-item` with `size`, `selected`, and `disabled` states.               |
-| Behavior                | One SideNav row: a link or button with optional icon and passive end content, optional row-level actions beside it, and optional nested children that can expand and collapse. In a collapsed rail it is icon-only with a tooltip or a flyout.                |
-| End-user impact         | Users see and hear the current page, reach row actions before nested items, expand or collapse groups without navigating, and return to the page after choosing a destination in the mobile drawer.                                                           |
-| Builder impact          | None.                                                                                                                                                                                                                                                         |
-| Compatibility/readiness | Records shipped behavior; no public change. Three implementation gaps (see Current-state impact).                                                                                                                                                             |
-| Review checks           | Reject an interactive control rendered inside the primary element, a link that also toggles collapse, a toggle or action that activates the row, collapsed children that stay reachable, or a drawer activation that leaves the drawer open after navigating. |
-| Governing rules         | `component:SideNav` FR1–FR5, DD1 (nesting and row geometry); `family:navigation-destinations`; `architecture:interaction-modality`; `architecture:public-component-api`.                                                                                      |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-SideNavItem is one destination or group row in SideNav. It owns the row's
-primary element, its selected and disabled states, its icon swap, the
-placement of passive end content and row-level actions, the expand and collapse
-behavior of its nested children, its collapsed-rail tooltip and flyout
-interaction, and closing the mobile drawer on activation. Consumer usage lives
-in `SideNavItem.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: nested children start expanded and the item
-  owns that state unless `collapsible.isCollapsed` is defined; a controlled item
-  reports toggle intent through `onCollapsedChange` and flips only when the prop
-  changes (FR6)
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **A disabled parent stays operable in a collapsed rail.** In a collapsed rail,
-  a disabled item with children renders its flyout trigger with neither
-  `disabled` nor `aria-disabled`, so it keeps its tab stop and announces no
-  disabled state; a click does nothing, while Enter opens its flyout. `spec:AST-085` FR2 and
-  FR5 have a disabled control block activation and expose its disabled state.
-- **A disabled split row's toggle answers only the keyboard.** On a disabled
-  item with `href` or `onClick` and children, the expand toggle inherits the
-  row's pointer blocking but carries neither `disabled` nor `aria-disabled`, so
-  a click does nothing while Tab reaches it and Enter collapses the group. Its
-  pointer and keyboard behavior disagree, and its disabled state is not exposed
-  (`spec:AST-085` FR5). OQ1 asks whether a disabled item's children stay
-  expandable.
-- **Reduced motion on touch changes at once.** Under reduced motion the
-  chevron's rotation and the group's height change at once on every pointer;
-  `design:reduced-motion` DR2 has a touch-screen change cross-fade within
-  200 ms.
-
-## Ownership boundary
-
-**Owns**
-
-- The primary element, states, icons, end content, and actions placement
-  (FR1–FR5).
-- Expand and collapse of nested children, including the independent toggle
-  (FR6, FR7).
-- Collapsed-rail tooltip and flyout interaction (FR8, FR9).
-- Mobile drawer close on activation (FR10).
-- Focus outline and reduced-motion behavior (FR11, FR12).
-
-**Does not own / non-goals**
-
-- The nested group's labelling, its collapsed inert state, collapsed-rail
-  rendering rules, row width, indent, indent target, and group clipping — owned
-  by `component:SideNav` FR1–FR5 and DD1.
-- Destination acceptance and blocking — owned by
-  `family:navigation-destinations`.
-- The rail's collapsed state — owned by SideNav and `component:SideNavCollapseButton`.
-- Each control placed in `actions` — owned by that control (name, keyboard,
-  disabled state).
-- Row fill colors, radius, height, and padding per size — owned by the shared
-  nav item styles and the `side-nav-item` target.
-
-## Public concepts
-
-| Concept     | Closed values or states                                                 | Meaning                                                                | Availability by variant/orientation/state | Default               | Owner                   | Stability | Invalid-value behavior    |
-| ----------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------- | --------------------- | ----------------------- | --------- | ------------------------- |
-| Collapsible | `false`, `true`, `{defaultIsCollapsed, isCollapsed, onCollapsedChange}` | Whether and how nested children expand and collapse.                   | Items with children, expanded rail.       | Collapsible, expanded | `component:SideNavItem` | Stable    | Ignored without children. |
-| Row shape   | whole-row, split (link or `onClick` plus toggle), with actions          | Derived from `href`/`onClick`, children, `collapsible`, and `actions`. | Expanded rail and drawer.                 | Whole-row             | `component:SideNavItem` | Stable    | Not applicable.           |
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
-| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1  | The primary element is the `as` component, else the `LinkProvider` link, else `<a>`, when `href` is set and the item is enabled; otherwise a `<button type="button">`. A disabled item stays focusable with `aria-disabled="true"`, keeps its tab stop, and keeps focus when it becomes disabled (`spec:AST-085` FR1, FR4). It shows the icon (`selectedIcon` when selected and given), the label, `endContent`, and, for a whole-row collapsible item, a chevron. `endContent` is passive and renders inside the primary element.                                                                                                                                          | Current source and tests |
-| FR2  | In an expanded rail and on a collapsed leaf, `isSelected` sets `aria-current="page"` on the primary element, never on a row wrapper. A collapsed parent's flyout trigger carries no `aria-current`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
-| FR3  | A disabled item does not fire `onClick` or navigate. Its row actions stay operable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
-| FR4  | `actions` render as siblings of the primary element at the row's trailing edge, after the toggle and before nested children in DOM and focus order, at the row's control size (`sm`) unless a control sets its own (`architecture:component-size-cascade`). Clicking an action neither activates nor toggles the row. A row wrapper exists only when there are actions or an independent toggle; a falsy `actions` adds none.                                                                                                                                                                                                                                               | Current source and tests |
-| FR5  | The forwarded `ref`, other DOM props, `className`, and `style` reach the primary element; `data-testid` marks the row wrapper when one exists, else the primary element; `xstyle` styles the item's outer box.                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests |
-| FR6  | Whether an item with children collapses follows `component:SideNav` FR1. A collapsible item starts expanded unless `defaultIsCollapsed` is true; a controlled item calls `onCollapsedChange` with the next state and changes only when `isCollapsed` changes.                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests |
-| FR7  | With `href` or `onClick` in an expanded rail, a collapsible item is split: the primary element navigates or fires `onClick` and never toggles, and a separate toggle button named by `@astryx.sideNavItem.expand` or `.collapse` owns `aria-expanded` and `aria-controls`. Without either, the whole primary element toggles and carries `aria-expanded` and `aria-controls`.                                                                                                                                                                                                                                                                                               | Current source and tests |
-| FR8  | In a collapsed rail, a leaf item shows a tooltip with its label at the inline end, anchored to the item, including when the rail is collapsed at mount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests |
-| FR9  | In a collapsed rail, an item with children (rendered per `component:SideNav` FR2) opens its flyout: on a hover-capable pointer after a hover-intent delay, leaving closes a hover-opened flyout, and a click-opened one stays; a click under a stationary pointer does not spring it back open; no hover timers run on a coarse pointer. Keyboard opening moves focus into the flyout and Escape restores it to the trigger; hover opening does not move focus. The flyout is labeled by `@astryx.sideNavItem.submenuLabel`, shows the parent label as a header, light-dismisses, and closes when anything inside is clicked. Arrow keys inside it are left to the browser. | Current source and tests |
-| FR10 | Inside the mobile drawer, activating a link or button item calls `onClick` and then closes the drawer. Toggling a collapsible parent, clicking a row action, or activating outside the drawer does not close it.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
-| FR11 | Every focusable part paints the shared focus outline; a row with actions paints it on the wrapper when the primary element has focus.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR12 | The expand chevron's rotation and the nested group's height change animate only without a reduced-motion preference. Under reduced motion they change at once for a fine pointer, and on a touch screen they MUST cross-fade within 200 ms (`design:reduced-motion` DR2, DR3). Implementation gap: on a touch screen they also change at once.                                                                                                                                                                                                                                                                                                                              | Current source           |
-
-### Allowed variation
-
-- **AV1 — Size.** `sm`, `md`, and `lg` change row height and padding.
-- **AV2 — Theme styling.** Themes restyle `side-nav-item` per size, selected,
-  and disabled state.
-
-### Representative states
-
-| State                      | Required invariant                                             | Allowed variation |
-| -------------------------- | -------------------------------------------------------------- | ----------------- |
-| Link, selected             | `aria-current="page"` on the link; selected icon if given.     | Fill.             |
-| Disabled button            | `aria-disabled`; focusable; no `onClick`.                      | Muted styling.    |
-| Collapsible without action | Whole row toggles; chevron turns.                              | —                 |
-| Collapsible with `href`    | Link navigates; separate toggle button collapses.              | —                 |
-| Actions                    | Actions after toggle, before children; never activate the row. | Action content.   |
-| Collapsed rail leaf        | Icon-only; tooltip with label.                                 | —                 |
-| Collapsed rail parent      | Icon-only trigger; flyout with header and children.            | Delay.            |
-| Mobile drawer              | Activation closes the drawer.                                  | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Primary element.** Disabled or no `href` → button; else `as`, then
-  `LinkProvider`, then `<a>`.
-- **ORD2 — Icon.** `selectedIcon` when selected and given, else `icon`.
-
-### Performance and resources
-
-- **PR1 — Timers.** Flyout hover timers clear on close and unmount, and none are
-  scheduled on a coarse pointer.
-
-## Accessibility contract
-
-- **AR1 — Current page.** FR2.
-- **AR2 — Disclosure.** Exactly one element owns `aria-expanded` and
-  `aria-controls` for the nested group (FR7).
-- **AR3 — Focus order.** Row actions come after the primary element and toggle
-  and before nested items (FR4).
-- **AR4 — Collapsed names.** Collapsed-rail items keep a name per
-  `component:SideNav` FR2.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                  | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | --------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Primary element  | Icon, label, passive end content, optional chevron. | Current source and public docs | Prominent      | FR1                |
-| Toggle           | Trailing chevron button of the row control size.    | Current source                 | Supporting     | FR7                |
-| Actions          | Trailing row controls.                              | Current source and public docs | Supporting     | FR4                |
-| Flyout           | Parent label header over the children.              | Current source                 | Supporting     | FR9                |
-
-`SideNavItem.doc.mjs` declares no anatomy of its own, so no anatomy-theming map
-is recorded. Row geometry visual intent is `component:SideNav` DD1.
-
-## Family and system relationships
-
-- `family:overlay-dismissal` owns Escape and close-request ordering for this
-  component's popover.
-- `component:SideNav` owns nesting geometry and collapsed-rail rendering rules
-  this component follows.
-- `family:navigation-destinations` owns the accept/block decision for `href`.
-- `architecture:interaction-modality` provides the shared focus indicator.
-
-## Verification map
-
-| Contract      | Verification                                                        | Representative states                                                                                                     | Mutation or failure expectation                                                   | Audit section                     |
-| ------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------- |
-| FR1–FR3, FR5  | `SideNav.test.tsx` SideNavItem suite                                | Link, button, `as`, provider, disabled                                                                                    | Wrong element, lost `aria-current`, or a disabled item that runs `onClick` fails. | `audit:SideNavItem/behavior`      |
-| FR4–FR7, AR3  | `SideNav.test.tsx` actions-slot suite                               | Actions with toggle, endContent, disabled; row-wrapper `data-testid`; `defaultIsCollapsed` with whole-row `aria-controls` | Actions inside the primary element or wrong order fails.                          | `audit:SideNavItem/behavior`      |
-| FR6, FR7, AR2 | `SideNav.test.tsx` collapsible + href suite                         | Split, whole-row, controlled                                                                                              | A link that toggles or duplicated `aria-expanded` fails.                          | `audit:SideNavItem/accessibility` |
-| FR8, FR9      | `SideNav.test.tsx` collapsed, hover-intent, and rail-tooltip suites | Leaf, parent, hover, click, keyboard, coarse                                                                              | Lost delay, focus restore, or tooltip anchor fails.                               | `audit:SideNavItem/behavior`      |
-| FR10          | `SideNav.test.tsx` mobile drawer close-on-activate suite            | Link, button, toggle, action, outside drawer                                                                              | Wrong close behavior fails.                                                       | `audit:SideNavItem/behavior`      |
-| FR11          | `SideNav.test.tsx` focus ring suite                                 | Plain, split, actions rows                                                                                                | Missing shared ring classes fail.                                                 | `audit:SideNavItem/accessibility` |
-| FR3, FR7, FR9 | `SideNav.test.tsx` keyboard operation and focus management suites   | Tab order, Enter/Space toggle, flyout Escape                                                                              | Lost order, a stranded focus, or no focus return fails.                           | `audit:SideNavItem/accessibility` |
-
-Read from source, with no focused test yet:
-
-- FR1 and ORD1–ORD2: the button's `type="button"`, the icon, the
-  selected-icon swap, and the whole-row chevron.
-- FR4: the actions' trailing-edge placement and the wrapper for an independent
-  toggle without actions.
-- FR5: the forwarded `ref` and `xstyle` on the outer box.
-- FR7: the toggle's translated names.
-- FR8: the tooltip's inline-end placement.
-- FR9: the flyout's light dismiss and close on an inner click.
-- FR12; PR1's timer clearing on close; and the `size` and `selected` theme
-  states.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-- **OQ1 — Do a disabled item's children stay expandable?** (`human-api`)
-  Today a disabled split row's toggle ignores the pointer and answers the
-  keyboard (Current-state impact).
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, or SideNav's
-nesting geometry. It links to their owners.

package/src/SideNav/SideNavSection.spec.md

@@ -1,153 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:SideNavSection
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-25
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility]
-verified_by:
-  [
-    packages/core/src/SideNav/SideNav.test.tsx,
-    apps/storybook/stories/SideNav.stories.tsx,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [architecture:public-component-api, architecture:component-theming-surface]
-contributing: []
-system_specs: []
----
-
-# SideNavSection component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `SideNavSection` with `title`, `subtitle`, `endContent`, `isHeaderHidden`, and `children`; target `side-nav-section`.                                                   |
-| Behavior                | A labeled group of SideNav items. Its header is visible in an expanded rail and visually hidden, but still read, when `isHeaderHidden` is set or the rail is collapsed. |
-| End-user impact         | Screen-reader users hear each group's title in every rail state; sighted users see section titles only in the expanded rail.                                            |
-| Builder impact          | None.                                                                                                                                                                   |
-| Compatibility/readiness | Records shipped behavior; no public change. One implementation gap (see Current-state impact).                                                                          |
-| Review checks           | Reject a section without `role="group"` named by its title, or a hidden header removed from the accessibility tree.                                                     |
-| Governing rules         | `architecture:public-component-api` INV5–INV6; `architecture:component-theming-surface`.                                                                                |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-SideNavSection groups related SideNav items under a title. It owns the group's
-semantics and its header's visibility. Consumer usage lives in
-`SideNavSection.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **A hidden header keeps its end content focusable.** When the header is
-  visually hidden (`isHeaderHidden` or a collapsed rail), a control placed in
-  `endContent` stays in the tab order while it is clipped out of sight, so
-  keyboard users land on a control they cannot see. WCAG 2.4.7 requires visible
-  focus. OQ1 asks whether a hidden header renders `endContent`.
-
-## Ownership boundary
-
-**Owns**
-
-- The group element, its name, header visibility, and root styling (FR1–FR4).
-
-**Does not own / non-goals**
-
-- Item rendering and nesting — owned by `component:SideNavItem` and
-  `component:SideNav`.
-- Interactive content placed in `endContent` — owned by that content.
-
-## Public concepts
-
-No component-local concept beyond the consumer props.
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                     | Basis                    |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | The root is a `div` with `role="group"` and `aria-labelledby` pointing at the title. It carries `side-nav-section`, the forwarded `ref`, `data-testid`, and other DOM props; the role and label cannot be overridden by them. | Current source and tests |
-| FR2 | The header shows the title, an optional subtitle, and `endContent` at the inline end, followed by the items.                                                                                                                  | Current source and tests |
-| FR3 | When `isHeaderHidden` is true or the rail is collapsed, the header is visually hidden but stays in the accessibility tree, so the group keeps its name.                                                                       | Current source and tests |
-| FR4 | `className`, `style`, and `xstyle` merge onto the root after component styles.                                                                                                                                                | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Header content.** Subtitle and end content may be absent.
-
-### Representative states
-
-| State          | Required invariant                   | Allowed variation |
-| -------------- | ------------------------------------ | ----------------- |
-| Expanded rail  | Visible header; named group.         | End content.      |
-| Header hidden  | Hidden header still names the group. | —                 |
-| Collapsed rail | Hidden header still names the group. | —                 |
-
-### Transformation and precedence order
-
-- No precedence rule.
-
-### Performance and resources
-
-- No resource rule.
-
-## Accessibility contract
-
-- **AR1 — Named group.** FR1 and FR3.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                     | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | -------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Header           | Title, subtitle, trailing end content. | Current source and public docs | Supporting     | FR2, FR3           |
-
-`SideNavSection.doc.mjs` declares no anatomy of its own, so no anatomy-theming
-map is recorded.
-
-## Family and system relationships
-
-- `component:SideNav` hosts sections in its list.
-
-## Verification map
-
-| Contract      | Verification                                  | Representative states               | Mutation or failure expectation             | Audit section                        |
-| ------------- | --------------------------------------------- | ----------------------------------- | ------------------------------------------- | ------------------------------------ |
-| FR1, FR2, FR4 | `SideNav.test.tsx` SideNavSection suite       | Title, subtitle, end content, props | A lost role, name, or forwarded prop fails. | `audit:SideNavSection/accessibility` |
-| FR3           | `SideNav.test.tsx` hidden section header test | Header hidden                       | A header removed from the tree fails.       | `audit:SideNavSection/accessibility` |
-
-Read from source, with no focused test yet: the forwarded `ref`, the
-`side-nav-section` target, and the role and label winning over caller props
-(FR1); the header's part order and end placement (FR2); hiding the header in a
-collapsed rail (FR3); and `xstyle` on the root (FR4).
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-- **OQ1 — Does a hidden header render `endContent`?** (`human-api`) Today it
-  does, and a control there stays focusable while hidden (Current-state
-  impact).
-
-## Content boundary
-
-This file does not duplicate consumer prop tables or examples. It links to their
-owners.