An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): NavMenu records its shipped contract as current (#8524)
Cindy Zhang79fb52533a84
diff --git a/packages/core/src/NavMenu/NavHeadingMenu.spec.md b/packages/core/src/NavMenu/NavHeadingMenu.spec.mdindex 1211da890c..afe042d0f0 100644--- a/packages/core/src/NavMenu/NavHeadingMenu.spec.md+++ b/packages/core/src/NavMenu/NavHeadingMenu.spec.md@@ -1,18 +1,19 @@---schema_version: 3-template_version: 3+template_version: 7kind: componentid: component:NavHeadingMenu-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-26owners: [cixzhang]review_triggers: [behavior, theming, accessibility]verified_by:[packages/core/src/NavMenu/NavHeadingMenu.test.tsx,+ apps/storybook/stories/NavMenu.stories.tsx,packages/core/src/Icon/Icon.test.tsx,packages/core/src/Text/Text.test.tsx,packages/core/src/theme/themingTargets.test.ts,@@ -25,32 +26,77 @@ architecture:[architecture:component-theming-surface,architecture:icon-resolution-and-component-slots,+ architecture:interaction-modality,architecture:layer-runtime,architecture:public-component-api,]contributing: []-system_specs: [spec:AST-005/DEC-1]+system_specs: [spec:AST-005/DEC-1, spec:AST-020, spec:AST-085]---# NavHeadingMenu component contract+## Contract at a glance++| Area | Contract |+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `NavHeadingMenu` with `children`, `size` (`sm`, `md`, `lg`; default `md`), and `minWidth`; `NavHeadingMenuItem` with `label`, `description`, `icon`, `href`, `onClick`, and `isDisabled`; targets `nav-heading-menu` and `nav-heading-menu-item` with a `size` state. |+| Behavior | A `role="menu"` list of `menuitem` rows inside a heading popover, with arrow, Home, End, typeahead, Enter, Space, and Escape support. Selecting an enabled item runs it and, where the host heading supplies a close action, closes the heading menu. |+| End-user impact | Users switch products or accounts from the heading menu by pointer or keyboard; disabled rows are skipped by keyboard and typeahead. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps (see Current-state impact). |+| Review checks | Reject losing `menu`/`menuitem` roles to caller props, keyboard focus landing on a disabled item, or a caller `onKeyDown` that silently disables the keyboard model. |+| Governing rules | `family:navigation-destinations` FR7; `architecture:interaction-modality`; `architecture:component-theming-surface`; `architecture:layer-runtime`. |++This table is a review projection; the body below is authoritative.+## IntentNavHeadingMenu presents selectable actions inside a SideNavHeading or-TopNavHeading popover. This draft records the current consumer anatomy and-theming ownership without changing rendering, keyboard behavior, layer-lifecycle, targets, or public API.+TopNavHeading popover. It owns the menu list, its keyboard model, and each+item's row. `NavMenu.doc.mjs` documents NavHeadingMenu and NavHeadingMenuItem+together, and NavHeadingMenuItem has no consumer doc of its own, so this record+covers both.## Compatibility and migration- Released default preserved: `yes`-- Compatibility class: additive documentation only; runtime, DOM, styling,+- Compatibility class: records shipped behavior; runtime, DOM, styling,targets, and public API remain unchanged-- Controlled/uncontrolled behavior: unchanged+- Controlled/uncontrolled behavior: not applicable- Migration decision: noneConsumer migration instructions belong in consumer docs and release notes.+## Current-state impact++- **A disabled link item still navigates.** A disabled NavHeadingMenuItem with+ `href` keeps its link destination and does not cancel the click, so a pointer+ click navigates even though the item reports `aria-disabled` and skips its+ `onClick`. `family:navigation-destinations` FR7 has members keep their own+ disabled semantics, and `spec:AST-085` FR2 has a disabled control block+ navigation.+- **The documented composition nests two menus.** Passed as the `menu` of+ SideNavHeading or TopNavHeading, as its consumer doc directs, NavHeadingMenu's+ `role="menu"` sits directly inside the heading's own `role="menu"` wrapper.+ WAI-ARIA 1.2 allows a `menu` to own only `menuitem`-family items and groups,+ so assistive technology meets a menu nested in a menu.+- **Inside a heading, arrow keys move twice.** Inside SideNavHeading or+ TopNavHeading, the heading's own list handler also moves focus over every+ `menuitem`, so one ArrowDown moves two items, and in a two-item menu ArrowDown+ never moves focus. The APG menu pattern moves focus one item per arrow press.+- **The menu has no name of its own.** NavHeadingMenu's `menu` carries no+ accessible name unless the caller passes `aria-label`; inside a heading only+ the heading's wrapper `menu` is named. The APG menu pattern, which+ `spec:AST-020` FR15 adopts, names each menu.+- **A disabled item changes focusability.** A disabled item drops the+ `tabIndex=-1` enabled items carry: a disabled link item becomes a page tab+ stop, and a disabled action item cannot take focus at all. `spec:AST-085` FR1+ keeps a disabled control's focus order as it is when enabled.+- **Focus is shown only by fill.** An item removes the outline and marks focus+ with the hover fill; it does not use the shared focus outline that+ `architecture:interaction-modality` provides.+## Ownership boundary**Owns**@@ -70,23 +116,28 @@ Consumer migration instructions belong in consumer docs and release notes.`component:Text`.- Non-string label content — owned by the caller.- The SideNavHeading or TopNavHeading trigger, popup surface, positioning,- dismissal lifecycle, or close-state ownership.-- New NavHeadingMenu targets for either label path or Item description, or any- runtime, API, target, or DOM change.+ dismissal lifecycle, or close-state ownership — owned by+ `component:SideNavHeading` and `component:TopNavHeading`.+- Destination acceptance and blocking — owned by+ `family:navigation-destinations`.## Public concepts-No new public concept is introduced. The canonical `NavMenu.doc.mjs` continues-to document NavHeadingMenu and NavHeadingMenuItem together.+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ------- | ----------------------- | ------------------------------------------------------- | ----------------------------------------- | ------- | -------------------------- | --------- | -------------------------------- |+| Size | `sm`, `md`, `lg` | Menu minimum width (160, 200, 240 px) and item padding. | Menu and every item through context. | `md` | `component:NavHeadingMenu` | Stable | TypeScript rejects other values. |## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------- |-| FR1 | NavHeadingMenu renders one Menu carrying `role="menu"` and the current `nav-heading-menu` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |-| FR2 | NavHeadingMenuItem renders one Item carrying `role="menuitem"` and the current `nav-heading-menu-item` target as a link when `href` is supplied and a div otherwise. | Current source, docs, and tests | Verified current behavior; no target change |-| FR3 | An optional Icon-rendered icon delegates to Icon's `icon` target. String labels and all descriptions render through Text's `text` target; non-string labels render directly as caller-owned content. | Current source and target docs | Verified current ownership; focused evidence is partial |-| FR4 | The parent nav heading supplies the close callback and owns its popup runtime; NavHeadingMenu consumes that callback for Escape and successful Item selection. | Current source and tests | Verified current relationship; no layer change |+| ID | Invariant | Basis |+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |+| FR1 | NavHeadingMenu renders one Menu `div` carrying `role="menu"`, the current `nav-heading-menu` target with `size`, the forwarded `ref`, `data-testid`, and other DOM props; caller props cannot replace the role. `minWidth` overrides the size's minimum width. | Current source, docs, and tests |+| FR2 | NavHeadingMenuItem renders one Item carrying `role="menuitem"` and the current `nav-heading-menu-item` target with the menu's size, as the `LinkProvider` link (else `<a>`) when `href` is supplied and a `div` otherwise. Caller props cannot replace its role, tab index, or disabled state. | Current source, docs, and tests |+| FR3 | An optional Icon-rendered icon delegates to Icon's `icon` target. String labels and all descriptions render through Text's `text` target on one line; non-string labels render directly as caller-owned content. | Current source and target docs |+| FR4 | The host heading owns the popup runtime. Where it supplies a close callback (TopNavHeading and the collapsed SideNavHeading), NavHeadingMenu calls it on Escape and on successful Item selection; an expanded SideNavHeading supplies none, so the menu stays open after a choice (`component:SideNavHeading` FR7). | Current source and tests |+| FR5 | Enabled items are focusable but not tab stops. In a standalone menu, ArrowDown and ArrowUp move one enabled item and wrap; Home and End go to the first and last; typing a character moves to the matching enabled item; Enter or Space activates the focused item. | Current source and tests |+| FR6 | Activating an enabled item runs its `onClick` and then the close callback; a disabled item carries `aria-disabled="true"`, MUST stay focusable outside the tab order as an enabled item is (`spec:AST-085` FR1), is skipped by keyboard movement and typeahead, and does not run `onClick` or close the menu. Implementation gap: a disabled item drops `tabIndex=-1` (Current-state impact). | Current source and tests |+| FR7 | A caller `onKeyDown` on the menu runs first; the keyboard model still runs unless that caller calls `preventDefault()` on an event no item handler has already cancelled; an item handler that cancels does not stop arrow navigation. | Current source and tests |### Allowed variation@@ -111,18 +162,21 @@ to document NavHeadingMenu and NavHeadingMenuItem together.### Transformation and precedence order-- No new focus, typeahead, activation, close, size, or styling precedence rule- is introduced.+- **ORD1 — Menu width.** `minWidth`, then the size's minimum width.+- **ORD2 — Keyboard.** Caller `onKeyDown`, then the menu keyboard model (FR7).### Performance and resources-- No new performance or resource rule is introduced.+- No resource rule.## Accessibility contract-This draft does not change or extend the current menu/menuitem roles, disabled-state, arrow/Home/End/Escape movement, typeahead, keyboard activation, or caller-labeling behavior.+- **AR1 — Menu semantics.** One `menu` holds `menuitem` rows (FR1, FR2). It is+ named only by a caller `aria-label`; inside a heading, the heading names its+ own wrapper `menu`, not this one (Current-state impact).+- **AR2 — Keyboard.** FR5 and FR6.+- **AR3 — Disabled.** Disabled items are exposed as disabled and unreachable by+ keyboard movement.## Design relationships@@ -168,37 +222,39 @@ owns the layer lifecycle and supplies the close callback through context.- `architecture:component-theming-surface` owns anatomy qualification, localtarget mapping, component delegation, and factual `none` dispositions.- `architecture:icon-resolution-and-component-slots` owns Icon slot resolution;- this draft records the current Icon delegation without changing slot behavior.+ this record states the current Icon delegation.- `architecture:layer-runtime` owns the shared popup host lifecycle used by theparent nav heading. NavHeadingMenu owns only its menu behavior and consumes theheading-provided close callback.- `architecture:public-component-api` owns the stable props and subcomponent- surface; this documentation adds no API.+ surface.- `family:navigation-destinations` owns the shared accept/block result for aNavHeadingMenuItem `href`; `spec:AST-005/DEC-1` requires native andcustom-router item paths to preserve that result.-- NavHeadingMenu's current custom-router path inherits the `useLinkComponent`- adoption gap recorded by the family until the accepted implementation lands.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |-| FR1, FR2 | `NavHeadingMenu.test.tsx` role, render, link, and disabled suites | Menu with link, action, and disabled Items | Removing menu/item semantics, content, or current rendering branches fails existing role, tag, attribute, and text checks. | `audit:NavHeadingMenu/anatomy` |-| FR3 | NavHeadingMenuItem source inspection plus Icon and Text target metadata | Icon, string label, caller-rendered label, and description paths | Source proves Icon-slot delegation, conditional label rendering, and Text-wrapped description; focused tests assert string and description content but not target placement or custom-label ownership. | `audit:NavHeadingMenu/theming` |-| FR4 | `NavHeadingMenu.test.tsx` context and keyboard suites | Selection, Escape, arrows, Home/End, typeahead | Breaking close callback consumption or keyboard behavior fails focused interaction assertions. | `audit:NavHeadingMenu/behavior` |-| Target inventory | Source inspection and `themingTargets.test.ts` | Menu, Item, and delegated Icon targets | Runtime and documented target metadata drift fails target validation. | `audit:NavHeadingMenu/theming` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and both current local targets | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:NavHeadingMenu/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |+| FR1, FR2 | `NavHeadingMenu.test.tsx` role, render, link, and disabled suites | Menu with link, action, and disabled Items | Removing menu/item semantics, content, or current rendering branches fails existing role, tag, attribute, and text checks. | `audit:NavHeadingMenu/anatomy` |+| FR3 | NavHeadingMenuItem source inspection plus Icon and Text target metadata | Icon, string label, caller-rendered label, and description paths | Source proves Icon-slot delegation, conditional label rendering, and Text-wrapped description; focused tests assert string and description content but not target placement or custom-label ownership. | `audit:NavHeadingMenu/theming` |+| FR4–FR7 | `NavHeadingMenu.test.tsx` context, keyboard, disabled, and pass-through suites | Selection, Escape, arrows, Home/End, typeahead, disabled, caller handlers | Breaking close callback consumption, keyboard behavior, or role precedence fails focused interaction assertions. | `audit:NavHeadingMenu/behavior` |+| Target inventory | Source inspection and `themingTargets.test.ts` | Menu, Item, and delegated Icon targets | Runtime and documented target metadata drift fails target validation. | `audit:NavHeadingMenu/theming` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and both current local targets | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:NavHeadingMenu/theming` |++Read from source, with no focused test yet:-Existing tests prove menu/item roles, string-label and description content,-interaction, and the heading-provided close callback. The conditional non-string-label path, Icon target placement, Text target placement, and both local target-placements remain source-inspected rather than pinned by focused assertions.+- FR1: the forwarded `ref`, and the menu role winning over caller props.+- FR2: the `nav-heading-menu-item` target and the `LinkProvider` link.+- FR3.+- FR5: that enabled items are focusable but not tab stops.+- FR6: that a disabled item does not close the menu.+- FR4, FR5, and AR1 inside SideNavHeading or TopNavHeading.+- The Menu and Item target placements in the theming map.## Decision log-None. This draft records current facts and introduces no component-local design,-behavior, accessibility, layer, or API decision.+No component-local decision is recorded.## Open questions