@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/NavMenu/NavHeadingMenu.spec.md

@@ -1,56 +1,102 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:NavHeadingMenu
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-26
 owners: [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,
     scripts/check-knowledge.mjs,
   ]
 modules: []
-families: [family:navigation-destinations]
+families: [family:navigation-destinations, family:action-groups]
 design_specs: []
 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.
+
 ## Intent
 
 NavHeadingMenu 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: none
 
 Consumer 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,29 @@ 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        |
+| FR8 | In the open menu, 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
 
@@ -111,18 +163,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 +223,40 @@ owns the layer lifecycle and supplies the close callback through context.
 - `architecture:component-theming-surface` owns anatomy qualification, local
   target 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 the
   parent nav heading. NavHeadingMenu owns only its menu behavior and consumes the
   heading-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 a
   NavHeadingMenuItem `href`; `spec:AST-005/DEC-1` requires native and
   custom-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`  |
-
-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.
+| 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`  |
+| FR8                 | `NavHeadingMenu.test.tsx` action-group suite (touch and mouse slides)          | Touch and mouse slides across items; a disabled item; undraggable link items | Removing the adoption fails the slide tests.                                                                                                                                                           | —                               |
+
+Read from source, with no focused test yet:
+
+- 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
 

package/src/NavMenu/NavHeadingMenu.test.tsx

@@ -1,12 +1,15 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, vi} from 'vitest';
-import type {KeyboardEvent} from 'react';
+import {beforeEach, describe, it, expect, vi} from 'vitest';
+import {Activity, type KeyboardEvent} from 'react';
 import {render, screen, fireEvent} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {LinkProvider} from '../Link';
 import {NavHeadingMenu} from './NavHeadingMenu';
 import {NavHeadingMenuItem} from './NavHeadingMenuItem';
 import {NavHeadingCloseContext} from './NavMenuContext';
+import {__resetMenuPressForTest} from '../hooks/useMenuPress';
+import {expectNativeLinkClicks} from '../hooks/__tests__/menuLinkClicks';
 
 describe('NavHeadingMenu', () => {
   it('renders with role="menu"', () => {
@@ -128,6 +131,203 @@ describe('NavHeadingMenuItem', () => {
     );
   });
 
+  it('exposes no destination on a disabled link item', () => {
+    render(
+      <NavHeadingMenu>
+        <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
+      </NavHeadingMenu>,
+    );
+    const item = screen.getByRole('menuitem');
+    // No href means no navigation path at all: not a pointer click, a
+    // middle-click, an assistive-technology activation, or Enter.
+    expect(item).not.toHaveAttribute('href');
+    // The row keeps its shape and still reports the disabled state.
+    expect(item.tagName).toBe('A');
+    expect(item).toHaveAttribute('aria-disabled', 'true');
+  });
+
+  it('does not reach a custom link component when a link item is disabled', () => {
+    function CustomLink({
+      children,
+      ref,
+      ...props
+    }: React.ComponentPropsWithRef<'a'>) {
+      return (
+        <a ref={ref} data-custom-link {...props}>
+          {children}
+        </a>
+      );
+    }
+    render(
+      <LinkProvider component={CustomLink}>
+        <NavHeadingMenu>
+          <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
+        </NavHeadingMenu>
+      </LinkProvider>,
+    );
+    const item = screen.getByRole('menuitem');
+    expect(item).not.toHaveAttribute('data-custom-link');
+    expect(item).not.toHaveAttribute('href');
+  });
+
+  it('keeps an enabled link item on the custom link component', () => {
+    function CustomLink({
+      children,
+      ref,
+      ...props
+    }: React.ComponentPropsWithRef<'a'>) {
+      return (
+        <a ref={ref} data-custom-link {...props}>
+          {children}
+        </a>
+      );
+    }
+    render(
+      <LinkProvider component={CustomLink}>
+        <NavHeadingMenu>
+          <NavHeadingMenuItem label="Docs" href="/docs" />
+        </NavHeadingMenu>
+      </LinkProvider>,
+    );
+    const item = screen.getByRole('menuitem');
+    expect(item).toHaveAttribute('data-custom-link');
+    expect(item).toHaveAttribute('href', '/docs');
+  });
+
+  it('keeps a disabled link item focusable but out of the Tab order', () => {
+    render(
+      <NavHeadingMenu>
+        <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
+      </NavHeadingMenu>,
+    );
+    const item = screen.getByRole('menuitem');
+    // No href and no tabindex would make the anchor unfocusable.
+    expect(item).toHaveAttribute('tabindex', '-1');
+    item.focus();
+    expect(item).toHaveFocus();
+  });
+
+  it('keeps focus on a link item that becomes disabled while focused', () => {
+    const {rerender} = render(
+      <NavHeadingMenu>
+        <NavHeadingMenuItem label="Docs" href="/docs" />
+      </NavHeadingMenu>,
+    );
+    screen.getByRole('menuitem').focus();
+    expect(screen.getByRole('menuitem')).toHaveFocus();
+
+    rerender(
+      <NavHeadingMenu>
+        <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
+      </NavHeadingMenu>,
+    );
+    const disabled = screen.getByRole('menuitem');
+    expect(disabled).not.toHaveAttribute('href');
+    expect(disabled).toHaveFocus();
+
+    rerender(
+      <NavHeadingMenu>
+        <NavHeadingMenuItem label="Docs" href="/docs" />
+      </NavHeadingMenu>,
+    );
+    expect(screen.getByRole('menuitem')).toHaveFocus();
+  });
+
+  it('does not steal focus when an unfocused link item toggles disabled', () => {
+    const {rerender} = render(
+      <NavHeadingMenu>
+        <NavHeadingMenuItem label="Docs" href="/docs" />
+      </NavHeadingMenu>,
+    );
+    rerender(
+      <NavHeadingMenu>
+        <NavHeadingMenuItem label="Docs" href="/docs" isDisabled />
+      </NavHeadingMenu>,
+    );
+    expect(screen.getByRole('menuitem')).not.toHaveFocus();
+  });
+
+  it('does not pull focus back when an Activity boundary reveals a row', () => {
+    const tree = (mode: 'visible' | 'hidden') => (
+      <>
+        <button type="button">Elsewhere</button>
+        <Activity mode={mode}>
+          <NavHeadingMenu>
+            <NavHeadingMenuItem label="Docs" href="/docs" />
+          </NavHeadingMenu>
+        </Activity>
+      </>
+    );
+    const {rerender} = render(tree('visible'));
+    screen.getByRole('menuitem').focus();
+    expect(screen.getByRole('menuitem')).toHaveFocus();
+
+    // Hide the row while it holds focus, then move focus elsewhere.
+    rerender(tree('hidden'));
+    const other = screen.getByRole('button', {name: 'Elsewhere'});
+    other.focus();
+    expect(other).toHaveFocus();
+
+    // Revealing the same node must leave focus where the person put it.
+    rerender(tree('visible'));
+    expect(other).toHaveFocus();
+  });
+
+  it('leaves focus on the page when an Activity boundary reveals a row', () => {
+    const tree = (mode: 'visible' | 'hidden') => (
+      <Activity mode={mode}>
+        <NavHeadingMenu>
+          <NavHeadingMenuItem label="Docs" href="/docs" />
+        </NavHeadingMenu>
+      </Activity>
+    );
+    const {rerender} = render(tree('visible'));
+    screen.getByRole('menuitem').focus();
+    expect(screen.getByRole('menuitem')).toHaveFocus();
+
+    // Hide while focused, then drop focus to the page.
+    rerender(tree('hidden'));
+    (document.activeElement as HTMLElement | null)?.blur();
+
+    // The same node re-attaches on reveal; it was not replaced, so it must not
+    // pull focus back from the page.
+    rerender(tree('visible'));
+    expect(document.activeElement).toBe(document.body);
+  });
+
+  it('does not take focus on reveal when isDisabled flipped while hidden', () => {
+    const tree = (mode: 'visible' | 'hidden', isDisabled: boolean) => (
+      <>
+        <button type="button">Elsewhere</button>
+        <Activity mode={mode}>
+          <NavHeadingMenu>
+            <NavHeadingMenuItem
+              label="Billing"
+              href="/billing"
+              isDisabled={isDisabled}
+            />
+          </NavHeadingMenu>
+        </Activity>
+      </>
+    );
+    const {rerender} = render(tree('visible', false));
+    screen.getByRole('menuitem').focus();
+    expect(screen.getByRole('menuitem')).toHaveFocus();
+
+    // Hide while focused, swap the row's element type while hidden, then move
+    // focus to another control.
+    rerender(tree('hidden', false));
+    rerender(tree('hidden', true));
+    const other = screen.getByRole('button', {name: 'Elsewhere'});
+    other.focus();
+    expect(other).toHaveFocus();
+
+    // The swapped-in node attaches only now and must not take focus.
+    rerender(tree('visible', true));
+    expect(screen.getByRole('menuitem')).not.toHaveAttribute('href');
+    expect(other).toHaveFocus();
+  });
+
   it('renders description text', () => {
     render(
       <NavHeadingMenu>
@@ -438,3 +638,77 @@ describe('NavHeadingMenuItem pass-through props', () => {
     expect(item).toHaveAttribute('aria-disabled', 'true');
   });
 });
+
+describe('NavHeadingMenu as an action group (family:action-groups)', () => {
+  beforeEach(() => {
+    __resetMenuPressForTest();
+  });
+
+  const item = (name: string) => screen.getByRole('menuitem', {name});
+  const finger = {pointerType: 'touch', pointerId: 1};
+  const mouse = {pointerType: 'mouse', pointerId: 1, button: 0};
+
+  function renderMenu() {
+    const onDashboard = vi.fn();
+    const onSettings = vi.fn();
+    const closeMenu = vi.fn();
+    render(
+      <NavHeadingCloseContext value={{closeMenu}}>
+        <NavHeadingMenu>
+          <NavHeadingMenuItem label="Dashboard" onClick={onDashboard} />
+          <NavHeadingMenuItem label="Settings" onClick={onSettings} />
+          <NavHeadingMenuItem label="Archive" isDisabled />
+        </NavHeadingMenu>
+      </NavHeadingCloseContext>,
+    );
+    return {onDashboard, onSettings, closeMenu};
+  }
+
+  it('renders a link item undraggable, so a mouse press that slides to another item is not a drag', () => {
+    render(
+      <NavHeadingMenu>
+        <NavHeadingMenuItem label="Docs" href="/docs" />
+        <NavHeadingMenuItem label="Sign out" onClick={() => {}} />
+      </NavHeadingMenu>,
+    );
+    expect(item('Docs')).toHaveAttribute('draggable', 'false');
+    expect(item('Sign out')).not.toHaveAttribute('draggable');
+  });
+
+  it('leaves a Ctrl-, Cmd-, Shift- or middle click on a link item to the browser', () => {
+    render(
+      <NavHeadingMenu>
+        <NavHeadingMenuItem label="Docs" href="/docs" />
+        <NavHeadingMenuItem label="Status" href="/status" />
+      </NavHeadingMenu>,
+    );
+    expectNativeLinkClicks(item('Docs'));
+  });
+
+  it('acts on the item a finger lifts on, once, after sliding from another (FR1, FR2)', () => {
+    const {onDashboard, onSettings} = renderMenu();
+    fireEvent.pointerDown(item('Dashboard'), finger);
+    fireEvent.pointerMove(item('Settings'), finger);
+    fireEvent.pointerUp(item('Settings'), finger);
+    expect(onSettings).toHaveBeenCalledTimes(1);
+    expect(onDashboard).not.toHaveBeenCalled();
+  });
+
+  it('acts on the item a held mouse lifts on (FR5)', () => {
+    const {onDashboard, onSettings} = renderMenu();
+    fireEvent.pointerDown(item('Settings'), mouse);
+    fireEvent.pointerMove(item('Dashboard'), mouse);
+    fireEvent.pointerUp(item('Dashboard'), mouse);
+    expect(onDashboard).toHaveBeenCalledTimes(1);
+    expect(onSettings).not.toHaveBeenCalled();
+  });
+
+  it('acts on nothing for a lift on a disabled item (FR2)', () => {
+    const {onDashboard, onSettings} = renderMenu();
+    fireEvent.pointerDown(item('Dashboard'), finger);
+    fireEvent.pointerMove(item('Archive'), finger);
+    fireEvent.pointerUp(item('Archive'), finger);
+    expect(onDashboard).not.toHaveBeenCalled();
+    expect(onSettings).not.toHaveBeenCalled();
+  });
+});