An open source design system that's fully customizable and agent ready
TypeScript
feat(core): the nav, breadcrumb and tab menus track a held pointer across their items (#8791)
Cindy Zhang7bcb81cbe138
diff --git a/.changeset/nav-menus-track-held-pointer.md b/.changeset/nav-menus-track-held-pointer.mdnew file mode 100644index 0000000000..a4f6c20941--- /dev/null+++ b/.changeset/nav-menus-track-held-pointer.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feature] NavHeadingMenu, TopNavMenu, SideNavHeading's menu, TopNavHeading's product menu, BreadcrumbItem's menu and TabMenu track a held pointer across their items, as DropdownMenu does: a press (finger, pen or mouse) that slides across the items acts on the one it lifts on, once, with the highlight following the pointer, and a mouse released outside closes the menu. A link item is no longer draggable, so a mouse press that slides to another item is not a drag. Keyboard and assistive-technology behavior is unchanged. No API changes.++@cixzhangdiff --git a/apps/storybook/stories/SideNav.stories.tsx b/apps/storybook/stories/SideNav.stories.tsxindex ae13ad4983..8e3772b50c 100644--- a/apps/storybook/stories/SideNav.stories.tsx+++ b/apps/storybook/stories/SideNav.stories.tsx@@ -14,6 +14,7 @@ import {Icon} from '@astryxdesign/core/Icon';import {ListItem} from '@astryxdesign/core/List';import {MoreMenu} from '@astryxdesign/core/MoreMenu';import {NavIcon} from '@astryxdesign/core/NavIcon';+import {NavHeadingMenu, NavHeadingMenuItem} from '@astryxdesign/core/NavMenu';import {Text} from '@astryxdesign/core/Text';import {HomeIcon,@@ -126,6 +127,35 @@ export const TitleWithoutIcon: Story = {// With Header Menu// =============================================================================+/**+ * A header whose menu holds NavHeadingMenu items. A press that slides across+ * them acts on the item it lifts on, as every menu does.+ */+export const WithHeaderMenuItems: Story = {+ name: 'Header with Menu Items',+ render: () => (+ <SideNav+ header={+ <SideNavHeading+ icon={<NavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}+ heading="Product Name"+ subheading="Business Account"+ menu={+ <NavHeadingMenu>+ <NavHeadingMenuItem label="Personal Account" onClick={() => {}} />+ <NavHeadingMenuItem label="Acme Corp" onClick={() => {}} />+ <NavHeadingMenuItem label="Sign out" onClick={() => {}} />+ </NavHeadingMenu>+ }+ />+ }>+ <SideNavSection title="Navigation">+ <SideNavItem label="Dashboard" icon={HomeIcon} isSelected />+ </SideNavSection>+ </SideNav>+ ),+};+export const WithHeaderMenu: Story = {name: 'Header with Menu',render: () => (diff --git a/apps/storybook/stories/TopNav.stories.tsx b/apps/storybook/stories/TopNav.stories.tsxindex db14273c54..9b9f5034b9 100644--- a/apps/storybook/stories/TopNav.stories.tsx+++ b/apps/storybook/stories/TopNav.stories.tsx@@ -3,6 +3,7 @@import type {Meta, StoryObj} from '@storybook/react';import {TopNav, TopNavHeading, TopNavItem} from '@astryxdesign/core/TopNav';import {NavIcon} from '@astryxdesign/core/NavIcon';+import {NavHeadingMenu, NavHeadingMenuItem} from '@astryxdesign/core/NavMenu';import {Button} from '@astryxdesign/core/Button';import {HomeIcon,@@ -109,6 +110,29 @@ export const WithLogo: Story = {},};+/**+ * A heading with a product menu. A press that slides across the menu's items+ * acts on the item it lifts on, as every menu does.+ */+export const WithHeadingMenu: Story = {+ args: {+ label: 'Main navigation',+ heading: (+ <TopNavHeading+ heading="Acme Suite"+ logo={<NavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />}+ menu={+ <NavHeadingMenu>+ <NavHeadingMenuItem label="Analytics" onClick={() => {}} />+ <NavHeadingMenuItem label="Billing" onClick={() => {}} />+ <NavHeadingMenuItem label="Settings" onClick={() => {}} />+ </NavHeadingMenu>+ }+ />+ ),+ },+};+export const TitleOnly: Story = {args: {label: 'Main navigation',diff --git a/packages/core/src/Breadcrumbs/BreadcrumbItem.spec.md b/packages/core/src/Breadcrumbs/BreadcrumbItem.spec.mdindex 4cac1c5cd2..e2ef78c65f 100644--- a/packages/core/src/Breadcrumbs/BreadcrumbItem.spec.md+++ b/packages/core/src/Breadcrumbs/BreadcrumbItem.spec.md@@ -20,7 +20,12 @@ verified_by:scripts/check-knowledge.mjs,]modules: []-families: [family:navigation-destinations, family:overlay-dismissal]+families:+ [+ family:navigation-destinations,+ family:overlay-dismissal,+ family:action-groups,+ ]design_specs: [design:bidirectionality]architecture:[@@ -120,17 +125,18 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |-| FR1 | The item root is one `<li>` carrying the public ref, the `breadcrumb-item` target with the trail's variant, `data-testid`, styling escape hatches, and other DOM props. | Released types, source, docs, and tests; `architecture:public-component-api` |-| FR2 | A non-current item with `href` and no menu uses the shared link renderer, with `onClick` on the link; an item with only `onClick` uses a native button styled as a link; an item with neither renders text content. | Released source, docs, and tests |-| FR3 | Explicit `isCurrent=true` renders the content as text (or the menu trigger) carrying `aria-current="page"` and ignores `href` and `onClick`; explicit `false` opts out; when no item in the list carries `aria-current="page"`, the list's last child, if it omits the prop, receives it on its content owner (Current-state impact records the fallback to the `<li>`); a trail whose last child sets `isCurrent={false}` has no current crumb. | Released source, docs, and tests |-| FR4 | Every item renders one `aria-hidden` separator container before its content, hidden on the first item. The built-in `/` mirrors exactly once in RTL; caller-provided separators render as given. | Source, focused tests, and `design:bidirectionality` DR4 |-| FR5 | A menu item exposes one menu button with `aria-haspopup="menu"`, its expanded state, and `aria-controls`, and one `role="menu"` surface labelled by the trigger, including non-string trigger content. Click, Enter, Space, and ArrowDown open it and focus its first item; Escape, Tab, and selection close it; arrows move between items without wrapping, and typeahead jumps to a matching item. | APG Menu Button pattern, `component:Popover`, source, tests, and browser evidence |-| FR6 | Closing the menu preserves a newly focused outside control. Focus returns to the trigger only when the closing surface would otherwise strand focus. | `component:Popover` and browser focus behavior |-| FR7 | The menu branch delegates item rendering, selection, row focus, and submenu content to the shared DropdownMenu item pipeline, from a data array or composed children. With `menu`, `href` and `onClick` are ignored and a development warning is logged. | Released source and focused tests |-| FR8 | Omitted `menuSize` resolves to `sm` under the `supporting` variant and `md` otherwise before entering the menu pipeline. | Released source and consumer docs |-| FR9 | The local targets are `breadcrumb-item` on the `<li>`, `breadcrumb-item-menu-trigger` on the menu button, and `breadcrumb-menu` on the menu surface; the first two reflect the trail's variant. Link, button, and menu trigger paint the shared focus outline. | Released docs, source, and theming tests |+| ID | Invariant | Basis |+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |+| FR1 | The item root is one `<li>` carrying the public ref, the `breadcrumb-item` target with the trail's variant, `data-testid`, styling escape hatches, and other DOM props. | Released types, source, docs, and tests; `architecture:public-component-api` |+| FR2 | A non-current item with `href` and no menu uses the shared link renderer, with `onClick` on the link; an item with only `onClick` uses a native button styled as a link; an item with neither renders text content. | Released source, docs, and tests |+| FR3 | Explicit `isCurrent=true` renders the content as text (or the menu trigger) carrying `aria-current="page"` and ignores `href` and `onClick`; explicit `false` opts out; when no item in the list carries `aria-current="page"`, the list's last child, if it omits the prop, receives it on its content owner (Current-state impact records the fallback to the `<li>`); a trail whose last child sets `isCurrent={false}` has no current crumb. | Released source, docs, and tests |+| FR4 | Every item renders one `aria-hidden` separator container before its content, hidden on the first item. The built-in `/` mirrors exactly once in RTL; caller-provided separators render as given. | Source, focused tests, and `design:bidirectionality` DR4 |+| FR5 | A menu item exposes one menu button with `aria-haspopup="menu"`, its expanded state, and `aria-controls`, and one `role="menu"` surface labelled by the trigger, including non-string trigger content. Click, Enter, Space, and ArrowDown open it and focus its first item; Escape, Tab, and selection close it; arrows move between items without wrapping, and typeahead jumps to a matching item. | APG Menu Button pattern, `component:Popover`, source, tests, and browser evidence |+| FR6 | Closing the menu preserves a newly focused outside control. Focus returns to the trigger only when the closing surface would otherwise strand focus. | `component:Popover` and browser focus behavior |+| FR7 | The menu branch delegates item rendering, selection, row focus, and submenu content to the shared DropdownMenu item pipeline, from a data array or composed children. With `menu`, `href` and `onClick` are ignored and a development warning is logged. | Released source and focused tests |+| FR8 | Omitted `menuSize` resolves to `sm` under the `supporting` variant and `md` otherwise before entering the menu pipeline. | Released source and consumer docs |+| FR9 | The local targets are `breadcrumb-item` on the `<li>`, `breadcrumb-item-menu-trigger` on the menu button, and `breadcrumb-menu` on the menu surface; the first two reflect the trail's variant. Link, button, and menu trigger paint the shared focus outline. | Released docs, source, and theming tests |+| FR10 | 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@@ -229,6 +235,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR5–FR8, AR3–AR5 | `Breadcrumbs.test.tsx` menu suites | String and ReactNode labels, click/keyboard open, rows, selection, Escape, outside dismiss | A menu loses its name/state, focus enters the wrong owner, or dismissal steals valid outside focus. | `audit:BreadcrumbItem/accessibility-behavior` || FR9 | `Breadcrumbs.test.tsx` theme-target tests; `themingTargets.test.ts` | Item, menu trigger, menu surface; default/supporting | A target disappears, moves to non-painting plumbing, or loses variant reflection. | `audit:BreadcrumbItem/theming` || AR1–AR2 | `Breadcrumbs.a11y.test.tsx` and `Breadcrumbs.a11y.chromium.spec.ts` | Trail, explicit current, auto current, opt-out | A role, name, state, or focus expectation regresses. | `audit:BreadcrumbItem/accessibility-behavior` |+| FR10 | `Breadcrumbs.test.tsx` menu-crumb suite (touch and mouse slides) | Touch and mouse slides across items | Removing the adoption fails the slide tests. | — |Read from source, with no focused test yet:diff --git a/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx b/packages/core/src/Breadcrumbs/BreadcrumbItem.tsxindex 6df4d9e270..6892c80c9c 100644--- a/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx+++ b/packages/core/src/Breadcrumbs/BreadcrumbItem.tsx@@ -51,6 +51,10 @@ import {focusOutlineProps} from '../utils/focusOutline.stylex';import {Icon} from '../Icon';import {usePopover} from '../Popover/usePopover';import {useListFocus} from '../hooks/useListFocus';+import {useMenuPress} from '../hooks/useMenuPress';+import {pressOnItemsOnly} from '../hooks/menuPressOnItems';+import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';+import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';import {useTypeahead} from '../hooks/useTypeahead';import {layerAnimations} from '../Layer/layerAnimations.stylex';import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';@@ -552,6 +556,15 @@ function BreadcrumbMenuTrigger({onEscape: closeMenu,});+ // A press that slides across the menu's items acts on the item it lifts on,+ // the highlight following the pointer, as DropdownMenu's does+ // (`family:action-groups` FR1-FR3, FR5); a mouse released outside closes it.+ const menuPress = useMenuPress({+ menuRef: listRef,+ itemSelector: MENU_ITEM_SELECTOR,+ onDismiss: closeMenu,+ });+const typeahead = useTypeahead({getItemLabels: () => getMenuItems().map(el => el.textContent),onMatch: focusItem,@@ -625,6 +638,7 @@ function BreadcrumbMenuTrigger({);const menuContent = Array.isArray(menu) ? renderDropdownItems(menu) : menu;+ const hasOverflow = useMenuOverflow(listRef, menuContent, popover.isOpen);return (<>@@ -673,10 +687,20 @@ function BreadcrumbMenuTrigger({id={menuId}role="menu"aria-labelledby={triggerId}+ {...menuPress.menuProps}+ onPointerDown={pressOnItemsOnly(+ menuPress.menuProps.onPointerDown,+ MENU_ITEM_SELECTOR,+ )}onKeyDown={listKeyDown}{...mergeProps(themeProps('breadcrumb-menu'),- stylex.props(menuStyles.menu),+ stylex.props(+ menuStyles.menu,+ hasOverflow+ ? menuTouchActionStyles.scrolls+ : menuTouchActionStyles.fits,+ ),)}><DropdownMenuContext value={contextValue}><DropdownMenuRootOpenContext value={popover.isOpen}>diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx b/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsxindex aaba1212fe..e5956e7614 100644--- a/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx@@ -2,6 +2,8 @@import {describe, it, expect, vi, beforeEach} from 'vitest';import {render, screen, waitFor, fireEvent, act} from '@testing-library/react';+import {__resetMenuPressForTest} from '../hooks/useMenuPress';+import {expectNativeLinkClicks} from '../hooks/__tests__/menuLinkClicks';import userEvent from '@testing-library/user-event';import {Breadcrumbs} from './Breadcrumbs';import {BreadcrumbItem} from './BreadcrumbItem';@@ -435,6 +437,62 @@ describe('BreadcrumbItem menu', () => {);});+ it('leaves a Ctrl-, Cmd-, Shift- or middle click on a link item in its menu to the browser', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ render(+ <Breadcrumbs>+ <BreadcrumbItem+ menu={[+ {label: 'Design', href: '/design'},+ {label: 'Engineering', href: '/engineering'},+ ]}>+ Teams+ </BreadcrumbItem>+ <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>+ </Breadcrumbs>,+ );+ await user.click(screen.getByRole('button', {name: 'Teams'}));+ const row = screen.getByRole('menuitem', {name: 'Design', hidden: true});+ expectNativeLinkClicks(row.closest('a') ?? row);+ });++ it('acts on the menu item a press slid across the menu lifts on, once (family:action-groups FR1, FR2, FR5)', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ const onFirst = vi.fn();+ const onSecond = vi.fn();+ render(+ <Breadcrumbs>+ <BreadcrumbItem+ menu={[+ {label: 'Design', onClick: onFirst},+ {label: 'Engineering', onClick: onSecond},+ ]}>+ Teams+ </BreadcrumbItem>+ <BreadcrumbItem isCurrent>Overview</BreadcrumbItem>+ </Breadcrumbs>,+ );+ await user.click(screen.getByRole('button', {name: 'Teams'}));+ const FIRST = 'Design';+ const SECOND = 'Engineering';+ const item = (name: string) =>+ screen.getByRole('menuitem', {name, hidden: true});+ for (const pointer of [+ {pointerType: 'touch', pointerId: 1},+ {pointerType: 'mouse', pointerId: 2, button: 0},+ ]) {+ onFirst.mockClear();+ onSecond.mockClear();+ fireEvent.pointerDown(item(FIRST), pointer);+ fireEvent.pointerMove(item(SECOND), pointer);+ fireEvent.pointerUp(item(SECOND), pointer);+ expect(onSecond).toHaveBeenCalledTimes(1);+ expect(onFirst).not.toHaveBeenCalled();+ }+ });+it('portability: a DropdownMenuOption[] renders its items on open', async () => {const user = userEvent.setup();render(diff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsxindex 55c9ed0164..31367307bc 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx@@ -79,6 +79,7 @@ import {moveRegionsTab} from './menuRegionStops';import {useDevWarning} from '../hooks/useDevWarning';import {useMenuDrillIn} from './useMenuDrillIn';import {resolveMenuWidth} from './menuWidth';+import {menuTouchActionStyles} from './menuTouchAction.stylex';import {layerViewportInset} from '../Layer/layerViewportInset.stylex';import {useAdaptivePresentation,@@ -214,18 +215,6 @@ const styles = stylex.create({flexShrink: 0,padding: spacingVars['--spacing-1'],},- // Scroll ownership by the browser's own signal. A menu whose rows fit keeps- // every one-finger move: a slide over its rows stays a slide. One that- // scrolls lets the browser pan it vertically and cancel the press when it- // does. Both leave a two-finger pinch to the browser, so the page stays- // zoomable over an open menu; `pinch-zoom` admits no one-finger pan.- touchPinchZoom: {- touchAction: 'pinch-zoom',- },- touchPanYPinchZoom: {- touchAction: 'pan-y pinch-zoom',- overscrollBehavior: 'contain',- },// The menu's lower block cap rides on the layer box too, so the layer's// flip decision sees the same height the menu paints.popoverViewport: {@@ -1715,7 +1704,9 @@ function DropdownMenuPopover({styles.dropdown,resolvedMaxHeight != null &&dynamicStyles.menuMaxHeight(resolvedMaxHeight),- hasOverflow ? styles.touchPanYPinchZoom : styles.touchPinchZoom,+ hasOverflow+ ? menuTouchActionStyles.scrolls+ : menuTouchActionStyles.fits,hasOverflow && styles.scrollable,hasRegions && styles.menuInFrame,// Between a header and a footer the menu is a Tab stop, sodiff --git a/packages/core/src/DropdownMenu/menuTouchAction.stylex.ts b/packages/core/src/DropdownMenu/menuTouchAction.stylex.tsnew file mode 100644index 0000000000..6f335cd612--- /dev/null+++ b/packages/core/src/DropdownMenu/menuTouchAction.stylex.ts@@ -0,0 +1,28 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file menuTouchAction.stylex.ts+ * @input Nothing; styles only+ * @output Exports menuTouchActionStyles: a menu's touch-action, by whether it+ * scrolls+ * @position Shared by every menu that tracks a held pointer through+ * useMenuPress (DropdownMenu and the nav, breadcrumb and tab menus)+ *+ * Scroll ownership by the browser's own signal. A menu whose rows fit keeps+ * every one-finger move, so a slide over its rows stays a slide. One that+ * scrolls lets the browser pan it vertically and cancel the press when it+ * does. Both leave a two-finger pinch to the browser, so the page stays+ * zoomable over an open menu; `pinch-zoom` admits no one-finger pan.+ */++import * as stylex from '@stylexjs/stylex';++export const menuTouchActionStyles = stylex.create({+ fits: {+ touchAction: 'pinch-zoom',+ },+ scrolls: {+ touchAction: 'pan-y pinch-zoom',+ overscrollBehavior: 'contain',+ },+});diff --git a/packages/core/src/NavMenu/NavHeadingMenu.spec.md b/packages/core/src/NavMenu/NavHeadingMenu.spec.mdindex afe042d0f0..23afe2aa80 100644--- a/packages/core/src/NavMenu/NavHeadingMenu.spec.md+++ b/packages/core/src/NavMenu/NavHeadingMenu.spec.md@@ -20,7 +20,7 @@ verified_by:scripts/check-knowledge.mjs,]modules: []-families: [family:navigation-destinations]+families: [family:navigation-destinations, family:action-groups]design_specs: []architecture:[@@ -129,15 +129,16 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| 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 |+| 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@@ -234,13 +235,14 @@ owns the layer lifecycle and supplies the close callback through context.## 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–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` |+| 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:diff --git a/packages/core/src/NavMenu/NavHeadingMenu.test.tsx b/packages/core/src/NavMenu/NavHeadingMenu.test.tsxindex 1e3762ec73..f857f95a11 100644--- a/packages/core/src/NavMenu/NavHeadingMenu.test.tsx+++ b/packages/core/src/NavMenu/NavHeadingMenu.test.tsx@@ -1,6 +1,6 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {describe, it, expect, vi} from 'vitest';+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';@@ -8,6 +8,8 @@ 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"', () => {@@ -636,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();+ });+});diff --git a/packages/core/src/NavMenu/NavHeadingMenu.tsx b/packages/core/src/NavMenu/NavHeadingMenu.tsxindex d70cc7ba25..1221eb142c 100644--- a/packages/core/src/NavMenu/NavHeadingMenu.tsx+++ b/packages/core/src/NavMenu/NavHeadingMenu.tsx@@ -12,15 +12,21 @@* - /packages/core/src/NavMenu/index.ts*/-import React, {useCallback, useMemo, useRef, type ReactNode} from 'react';+import React, {use, useCallback, useMemo, useRef, type ReactNode} from 'react';import * as stylex from '@stylexjs/stylex';import {spacingVars} from '../theme/tokens.stylex';import {mergeProps} from '../utils';import type {BaseProps} from '../BaseProps';import {useListFocus} from '../hooks/useListFocus';+import {useMenuPress} from '../hooks/useMenuPress';+import {pressOnItemsOnly} from '../hooks/menuPressOnItems';+import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';+import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';+import {composeEventHandlers} from '../utils/composeEventHandlers';import {useTypeahead} from '../hooks/useTypeahead';import {themeProps} from '../utils/themeProps';import {+ NavHeadingDismissContext,NavHeadingMenuContext,useNavHeadingCloseContext,type NavHeadingMenuSize,@@ -47,6 +53,9 @@ const sizeStyles = stylex.create({},});+/** The rows a press, a key or typeahead can reach. */+const ENABLED_ITEM_SELECTOR = '[role="menuitem"]:not([aria-disabled="true"])';+export interface NavHeadingMenuProps extends BaseProps<HTMLDivElement> {ref?: React.Ref<HTMLDivElement>;/** Menu items (NavHeadingMenuItem, dividers, custom content). */@@ -98,23 +107,37 @@ export function NavHeadingMenu({'data-testid': testId,onKeyDown: onKeyDownProp,onKeyDownCapture: onKeyDownCaptureProp,+ onPointerDown: onPointerDownProp,...rest}: NavHeadingMenuProps) {const closeCtx = useNavHeadingCloseContext();const closeMenu = closeCtx?.closeMenu;+ // A heading whose menu items do not close it on selection (an expanded+ // SideNavHeading) still lets a mouse released outside dismiss it.+ const dismissMenu = use(NavHeadingDismissContext)?.dismiss;const {listRef, handleKeyDown, focusItem} = useListFocus({- itemSelector: '[role="menuitem"]:not([aria-disabled="true"])',+ itemSelector: ENABLED_ITEM_SELECTOR,onEscape: closeMenu,});+ // A press that slides across the rows acts on the row it lifts on, the+ // highlight following the pointer, as every menu does+ // (`family:action-groups` FR1-FR3); a mouse released outside closes it.+ const menuPress = useMenuPress({+ menuRef: listRef,+ itemSelector: ENABLED_ITEM_SELECTOR,+ onDismiss: closeMenu ?? dismissMenu,+ });+ const hasOverflow = useMenuOverflow(listRef, children, true);+// First-character typeahead over the (enabled) menu items (menus-11).const getMenuItems = useCallback((): HTMLElement[] =>listRef.current? Array.from(listRef.current.querySelectorAll<HTMLElement>(- '[role="menuitem"]:not([aria-disabled="true"])',+ ENABLED_ITEM_SELECTOR,),): [],@@ -189,11 +212,26 @@ export function NavHeadingMenu({data-testid={testId}{...mergeProps(themeProps('nav-heading-menu', {size}),- stylex.props(styles.root, sizeStyles[size], xstyle),+ stylex.props(+ styles.root,+ sizeStyles[size],+ hasOverflow+ ? menuTouchActionStyles.scrolls+ : menuTouchActionStyles.fits,+ xstyle,+ ),className,inlineStyle,)}{...rest}+ {...menuPress.menuProps}+ onPointerDown={composeEventHandlers(+ onPointerDownProp,+ pressOnItemsOnly(+ menuPress.menuProps.onPointerDown,+ ENABLED_ITEM_SELECTOR,+ ),+ )}role="menu"onKeyDownCapture={handleMenuKeyDownCapture}onKeyDown={handleMenuKeyDown}>diff --git a/packages/core/src/NavMenu/NavHeadingMenuItem.tsx b/packages/core/src/NavMenu/NavHeadingMenuItem.tsxindex 9ac1a0fb7a..c7680505e5 100644--- a/packages/core/src/NavMenu/NavHeadingMenuItem.tsx+++ b/packages/core/src/NavMenu/NavHeadingMenuItem.tsx@@ -202,6 +202,9 @@ export function NavHeadingMenuItem({tabIndex={isDisabled && !href ? undefined : -1}aria-disabled={isDisabled || undefined}href={isDisabled ? undefined : href}+ // A menu row is never a draggable link: a mouse press that slides to+ // another row would start a drag and cancel the press.+ draggable={href != null ? false : undefined}onClick={handleClick}data-testid={testId}{...mergeProps(diff --git a/packages/core/src/NavMenu/NavMenuContext.tsx b/packages/core/src/NavMenu/NavMenuContext.tsxindex b41680a2be..0c716eb378 100644--- a/packages/core/src/NavMenu/NavMenuContext.tsx+++ b/packages/core/src/NavMenu/NavMenuContext.tsx@@ -34,6 +34,17 @@ export function useNavHeadingCloseContext(): NavHeadingCloseContextValue | nullreturn use(NavHeadingCloseContext);}+/**+ * Internal (not exported from the NavMenu entry): the dismissal a nav heading+ * popover gives its menu when its items do not close it on selection (an+ * expanded SideNavHeading, FR7). NavHeadingMenu calls it for a mouse released+ * outside, never on an item's selection.+ */+export const NavHeadingDismissContext = createContext<{+ dismiss: () => void;+} | null>(null);+NavHeadingDismissContext.displayName = 'NavHeadingDismissContext';+/*** Size and close context provided by NavHeadingMenu to its children.* Items read this for consistent padding and dismiss-on-click.diff --git a/packages/core/src/SideNav/SideNav.test.tsx b/packages/core/src/SideNav/SideNav.test.tsxindex 0ba8d3c258..9027e561fd 100644--- a/packages/core/src/SideNav/SideNav.test.tsx+++ b/packages/core/src/SideNav/SideNav.test.tsx@@ -26,6 +26,9 @@ import {focusOutlineStyles} from '../utils/focusOutline.stylex';import {getForcedColorsRules} from '../__tests__/forcedColors';import {Button} from '../Button';import {SideNav} from './SideNav';+import {__resetMenuPressForTest} from '../hooks/useMenuPress';+import {expectNativeLinkClicks} from '../hooks/__tests__/menuLinkClicks';+import {NavHeadingMenu, NavHeadingMenuItem} from '../NavMenu';import {SideNavCollapseButton} from './SideNavCollapseButton';import {SideNavHeading} from './SideNavHeading';import {SideNavItem} from './SideNavItem';@@ -425,6 +428,138 @@ describe('SideNavHeading', () => {</>);+ it('leaves a press on caller content that is not an item to that content: a button click and a link click run (interaction-modality INV4)', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ const onButton = vi.fn();+ const onLink = vi.fn((event: React.MouseEvent) => event.preventDefault());+ render(+ <SideNavHeading+ heading="My App"+ menu={+ <>+ <button type="button" onClick={onButton}>+ Switch account+ </button>+ <a href="#docs" onClick={onLink}>+ Docs+ </a>+ </>+ }+ />,+ );+ await user.click(screen.getByRole('button', {name: 'Open menu'}));+ for (const pointer of [+ {pointerType: 'mouse', pointerId: 1, button: 0},+ {pointerType: 'touch', pointerId: 2},+ ]) {+ onButton.mockClear();+ onLink.mockClear();+ const button = screen.getByRole('button', {+ name: 'Switch account',+ hidden: true,+ });+ fireEvent.pointerDown(button, pointer);+ fireEvent.pointerUp(button, pointer);+ // A pointer's click reports detail 1 (a keyboard's reports 0).+ fireEvent.click(button, {detail: 1});+ expect(onButton).toHaveBeenCalledTimes(1);+ const link = screen.getByRole('link', {name: 'Docs', hidden: true});+ fireEvent.pointerDown(link, pointer);+ fireEvent.pointerUp(link, pointer);+ fireEvent.click(link, {detail: 1});+ expect(onLink).toHaveBeenCalledTimes(1);+ }+ });++ it('leaves a Ctrl-, Cmd-, Shift- or middle click on a link item in its menu to the browser', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ render(+ <SideNavHeading+ heading="My App"+ menu={+ <NavHeadingMenu>+ <NavHeadingMenuItem label="Docs" href="/docs" />+ <NavHeadingMenuItem label="Status" href="/status" />+ </NavHeadingMenu>+ }+ />,+ );+ await user.click(screen.getByRole('button', {name: 'Open menu'}));+ expectNativeLinkClicks(+ screen.getByRole('menuitem', {name: 'Docs', hidden: true}),+ );+ });++ it('closes when a mouse pressed on a NavHeadingMenu item is released outside the menu (useMenuPress FR3)', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ render(+ <>+ <SideNavHeading+ heading="My App"+ menu={+ <NavHeadingMenu>+ <NavHeadingMenuItem label="Alpha" onClick={() => {}} />+ <NavHeadingMenuItem label="Beta" onClick={() => {}} />+ </NavHeadingMenu>+ }+ />+ <button type="button">Outside</button>+ </>,+ );+ const trigger = screen.getByRole('button', {name: 'Open menu'});+ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ const mouse = {pointerType: 'mouse', pointerId: 3, button: 0};+ const outside = screen.getByRole('button', {name: 'Outside'});+ fireEvent.pointerDown(+ screen.getByRole('menuitem', {name: 'Alpha', hidden: true}),+ mouse,+ );+ fireEvent.pointerMove(outside, mouse);+ fireEvent.pointerUp(outside, mouse);+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('acts on the item a press slid across the menu lifts on, once (family:action-groups FR1, FR2, FR5)', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ const onAlpha = vi.fn();+ const onBeta = vi.fn();+ render(+ <SideNavHeading+ heading="My App"+ menu={+ <>+ <div role="menuitem" tabIndex={-1} onClick={onAlpha}>+ Alpha+ </div>+ <div role="menuitem" tabIndex={-1} onClick={onBeta}>+ Beta+ </div>+ </>+ }+ />,+ );+ await user.click(screen.getByRole('button', {name: 'Open menu'}));+ const item = (name: string) =>+ screen.getByRole('menuitem', {name, hidden: true});+ for (const pointer of [+ {pointerType: 'touch', pointerId: 1},+ {pointerType: 'mouse', pointerId: 2, button: 0},+ ]) {+ onAlpha.mockClear();+ onBeta.mockClear();+ fireEvent.pointerDown(item('Alpha'), pointer);+ fireEvent.pointerMove(item('Beta'), pointer);+ fireEvent.pointerUp(item('Beta'), pointer);+ expect(onBeta).toHaveBeenCalledTimes(1);+ expect(onAlpha).not.toHaveBeenCalled();+ }+ });+it('does not wrap the heading menu popup in a modal dialog', async () => {const user = userEvent.setup();render(<SideNavHeading heading="My App" menu={menuItems} />);diff --git a/packages/core/src/SideNav/SideNavHeading.spec.md b/packages/core/src/SideNav/SideNavHeading.spec.mdindex 2bfea03eb3..451f4e9a31 100644--- a/packages/core/src/SideNav/SideNavHeading.spec.md+++ b/packages/core/src/SideNav/SideNavHeading.spec.md@@ -16,7 +16,12 @@ verified_by:apps/storybook/stories/SideNav.stories.tsx,]modules: []-families: [family:navigation-destinations, family:overlay-dismissal]+families:+ [+ family:navigation-destinations,+ family:overlay-dismissal,+ family:action-groups,+ ]design_specs: []architecture:[@@ -120,17 +125,18 @@ Consumer migration instructions belong in consumer docs and release notes.## 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 |+| 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@@ -184,13 +190,14 @@ map is recorded.## 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` |+| 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:diff --git a/packages/core/src/SideNav/SideNavHeading.tsx b/packages/core/src/SideNav/SideNavHeading.tsxindex e38e2140f6..844d7b8d4b 100644--- a/packages/core/src/SideNav/SideNavHeading.tsx+++ b/packages/core/src/SideNav/SideNavHeading.tsx@@ -47,7 +47,14 @@ import {mergeProps} from '../utils';import {useMergedRefs} from '../hooks/useMergedRefs';import type {BaseProps} from '../BaseProps';import {useMenuHover} from '../hooks/useMenuHover';-import {NavHeadingCloseContext} from '../NavMenu/NavMenuContext';+import {useMenuPress} from '../hooks/useMenuPress';+import {pressOnItemsOnly} from '../hooks/menuPressOnItems';+import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';+import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';+import {+ NavHeadingCloseContext,+ NavHeadingDismissContext,+} from '../NavMenu/NavMenuContext';import {themeProps} from '../utils/themeProps';import {useTranslator} from '../i18n';@@ -55,6 +62,10 @@ import {useTranslator} from '../i18n';// Styles// =============================================================================+/** The rows a press can act on in the heading's menu. */+const HEADING_MENU_ITEM_SELECTOR =+ '[role="menuitem"]:not([aria-disabled="true"])';+const styles = stylex.create({root: {display: 'flex',@@ -417,6 +428,28 @@ export function SideNavHeading({popoverId: isCollapsed ? popover.id : undefined,});+ // A press that slides across the menu's items acts on the item it lifts on,+ // the highlight following the pointer (`family:action-groups` FR1-FR3,+ // FR5); a mouse released outside closes it. Only the role="menu" region is+ // tracked, not the heading button above it.+ const headingMenuRef = useRef<HTMLDivElement>(null);+ const headingMenuPress = useMenuPress({+ menuRef: headingMenuRef,+ itemSelector: HEADING_MENU_ITEM_SELECTOR,+ onDismiss: closeMenu,+ isEnabled: !!menu,+ });+ const headingMenuPointerDown = pressOnItemsOnly(+ headingMenuPress.menuProps.onPointerDown,+ HEADING_MENU_ITEM_SELECTOR,+ );+ const dismissCtx = useMemo(() => ({dismiss: closeMenu}), [closeMenu]);+ const headingMenuTouch = stylex.props(+ useMenuOverflow(headingMenuRef, menu, popover.isOpen)+ ? menuTouchActionStyles.scrolls+ : menuTouchActionStyles.fits,+ );+const closeMenuCtx = useMemo(() => ({closeMenu}), [closeMenu]);// setTriggerEl belongs on the chevron button, not this root: it is the@@ -533,7 +566,13 @@ export function SideNavHeading({{/* The menu role is scoped to the actual menu items so theheading button above stays a valid sibling, not an invalidchild of a role="menu" element. */}- <div role="menu" aria-label={heading}>+ <div+ ref={headingMenuRef}+ role="menu"+ aria-label={heading}+ {...headingMenuPress.menuProps}+ onPointerDown={headingMenuPointerDown}+ {...headingMenuTouch}><NavHeadingCloseContext value={closeMenuCtx}>{menu}</NavHeadingCloseContext>@@ -755,8 +794,16 @@ export function SideNavHeading({{/* The menu role is scoped to the actual menu items so theheading button above stays a valid sibling, not an invalidchild of a role="menu" element. */}- <div role="menu" aria-label={heading}>- {menu}+ <div+ ref={headingMenuRef}+ role="menu"+ aria-label={heading}+ {...headingMenuPress.menuProps}+ onPointerDown={headingMenuPointerDown}+ {...headingMenuTouch}>+ <NavHeadingDismissContext value={dismissCtx}>+ {menu}+ </NavHeadingDismissContext></div></div>,{@@ -831,8 +878,16 @@ export function SideNavHeading({{/* The menu role is scoped to the actual menu items so theheading button above stays a valid sibling, not an invalidchild of a role="menu" element. */}- <div role="menu" aria-label={heading}>- {menu}+ <div+ ref={headingMenuRef}+ role="menu"+ aria-label={heading}+ {...headingMenuPress.menuProps}+ onPointerDown={headingMenuPointerDown}+ {...headingMenuTouch}>+ <NavHeadingDismissContext value={dismissCtx}>+ {menu}+ </NavHeadingDismissContext></div></div>,{diff --git a/packages/core/src/TabList/TabList.test.tsx b/packages/core/src/TabList/TabList.test.tsxindex f196079ee0..b35949ed5c 100644--- a/packages/core/src/TabList/TabList.test.tsx+++ b/packages/core/src/TabList/TabList.test.tsx@@ -11,6 +11,7 @@import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';import {render, screen, fireEvent} from '@testing-library/react';+import {__resetMenuPressForTest} from '../hooks/useMenuPress';import userEvent from '@testing-library/user-event';import {hasPressedArm,@@ -734,6 +735,32 @@ describe('TabMenu', () => {expect(heading).toHaveTextContent('More');});+ it('picks the option a press slid across the menu lifts on, once (family:action-groups FR1, FR2, FR5)', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ const handleChange = vi.fn();+ render(+ <TabList value="home" onChange={handleChange}>+ <Tab value="home" label="Home" />+ <TabMenu label="More" options={menuOptions} />+ </TabList>,+ );+ await user.click(screen.getByRole('button', {name: /More/}));+ const option = (name: string) =>+ screen.getByRole('menuitemradio', {name, hidden: true});+ for (const pointer of [+ {pointerType: 'touch', pointerId: 1},+ {pointerType: 'mouse', pointerId: 2, button: 0},+ ]) {+ handleChange.mockClear();+ fireEvent.pointerDown(option('Analytics'), pointer);+ fireEvent.pointerMove(option('Reports'), pointer);+ fireEvent.pointerUp(option('Reports'), pointer);+ expect(handleChange).toHaveBeenCalledTimes(1);+ expect(handleChange).toHaveBeenCalledWith('reports');+ }+ });+it('selects a menu item and calls onChange', async () => {const user = userEvent.setup();const handleChange = vi.fn();diff --git a/packages/core/src/TabList/TabMenu.spec.md b/packages/core/src/TabList/TabMenu.spec.mdindex 91a2ce314d..9334617c82 100644--- a/packages/core/src/TabList/TabMenu.spec.md+++ b/packages/core/src/TabList/TabMenu.spec.md@@ -16,7 +16,7 @@ verified_by:apps/storybook/stories/TabList.stories.tsx,]modules: []-families: [family:overlay-dismissal]+families: [family:overlay-dismissal, family:action-groups]design_specs: [design:reduced-motion]architecture:[@@ -117,6 +117,7 @@ No component-local concept beyond the consumer props.| FR4 | The menu is a `role="menu"` named by `label`, carrying `tab-menu-dropdown`, with a presentational heading repeating `label`, then one `role="menuitemradio"` per option with `aria-checked` for the selected value, an optional icon, and a check mark when selected. | Current source and tests || FR5 | Inside the menu one option is a tab stop, and ArrowUp, ArrowDown, Home, and End move it; ArrowLeft and ArrowRight are left to the strip; Enter, Space, or click on an option selects its value through the TabList and closes the menu; Escape and Tab close it. Closing returns focus to the trigger. | Current source and tests || FR6 | The trigger and options paint the shared focus outline. | Current source |+| FR7 | In the open menu, a press (finger, pen or mouse) that lands on an option and slides across the options picks the one it lifts on, once, through that option'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). Keyboard and assistive-technology behavior is unchanged. | Current source and tests |### Allowed variation@@ -166,6 +167,7 @@ recorded.| FR1, FR3 | `TabList.test.tsx` TabMenu and host-attribute tests | Closed, open | Lost popup attributes fail. | `audit:TabMenu/accessibility` || FR2, FR4 | `TabList.test.tsx` TabMenu label, heading, and menuitemradio tests | Selected and unselected | Wrong label or missing `aria-checked` fails. | `audit:TabMenu/behavior` || FR5 | `TabList.test.tsx` TabMenu keyboard navigation tests | ArrowUp, ArrowDown, Home, End, Tab, Escape, Enter | Extra tab stops or a menu left open fails. | `audit:TabMenu/accessibility` |+| FR7 | `TabList.test.tsx` TabMenu suite (touch and mouse slides) | Touch and mouse slides across options | Removing the adoption fails the slide tests. | — |Read from source, with no focused test yet:diff --git a/packages/core/src/TabList/TabMenu.tsx b/packages/core/src/TabList/TabMenu.tsxindex 8241bbc563..53cbbc6e77 100644--- a/packages/core/src/TabList/TabMenu.tsx+++ b/packages/core/src/TabList/TabMenu.tsx@@ -34,6 +34,9 @@ import {focusOutlineProps} from '../utils/focusOutline.stylex';import {usePopover} from '../Popover/usePopover';import {MENU_ITEM_SELECTOR} from '../DropdownMenu/menuItemRoles';import {useListFocus} from '../hooks/useListFocus';+import {useMenuPress} from '../hooks/useMenuPress';+import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';+import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';import {useTabListContext} from './TabListContext';import type {TabListSize} from './TabListContext';import {tabScope} from './tab.markers.stylex';@@ -302,6 +305,16 @@ export function TabMenu({onEscape: () => popover.hide(),});+ // A press that slides across the options picks the one it lifts on, the+ // highlight following the pointer, as DropdownMenu's does+ // (`family:action-groups` FR1-FR3, FR5); a mouse released outside closes it.+ const menuPress = useMenuPress({+ menuRef: listRef,+ itemSelector: MENU_ITEM_SELECTOR,+ onDismiss: popover.hide,+ });+ const hasOverflow = useMenuOverflow(listRef, options.length, popover.isOpen);+const handleToggle = useCallback(() => {if (popover.isOpen) {popover.hide();@@ -404,11 +417,17 @@ export function TabMenu({id={menuId}role="menu"aria-label={label}+ {...menuPress.menuProps}onKeyDown={handleMenuKeyDown}onFocus={handleFocus}{...mergeProps(themeProps('tab-menu-dropdown'),- stylex.props(styles.dropdown),+ stylex.props(+ styles.dropdown,+ hasOverflow+ ? menuTouchActionStyles.scrolls+ : menuTouchActionStyles.fits,+ ),)}><span role="presentation" {...stylex.props(styles.menuHeading)}>{label}diff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsxindex bfa85f602d..0d510da231 100644--- a/packages/core/src/TopNav/TopNav.test.tsx+++ b/packages/core/src/TopNav/TopNav.test.tsx@@ -11,6 +11,9 @@import {describe, it, expect, vi} from 'vitest';import {fireEvent, render, screen, act} from '@testing-library/react';+import {__resetMenuPressForTest} from '../hooks/useMenuPress';+import {expectNativeLinkClicks} from '../hooks/__tests__/menuLinkClicks';+import {NavHeadingMenu, NavHeadingMenuItem} from '../NavMenu';import userEvent from '@testing-library/user-event';import {TopNav} from './TopNav';import {TopNavRenderContext} from './TopNavRenderContext';@@ -315,6 +318,92 @@ describe('TopNavHeading', () => {</>);+ it('acts on the product-menu item a press slid across it lifts on, once (family:action-groups FR1, FR2, FR5)', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ const onFirst = vi.fn();+ const onSecond = vi.fn();+ render(+ <TopNavHeading+ heading="My App"+ menu={+ <>+ <div role="menuitem" tabIndex={-1} onClick={onFirst}>+ Alpha+ </div>+ <div role="menuitem" tabIndex={-1} onClick={onSecond}>+ Beta+ </div>+ </>+ }+ />,+ );+ await user.click(screen.getByRole('button', {name: 'Open menu'}));+ const FIRST = 'Alpha';+ const SECOND = 'Beta';+ const item = (name: string) =>+ screen.getByRole('menuitem', {name, hidden: true});+ for (const pointer of [+ {pointerType: 'touch', pointerId: 1},+ {pointerType: 'mouse', pointerId: 2, button: 0},+ ]) {+ onFirst.mockClear();+ onSecond.mockClear();+ fireEvent.pointerDown(item(FIRST), pointer);+ fireEvent.pointerMove(item(SECOND), pointer);+ fireEvent.pointerUp(item(SECOND), pointer);+ expect(onSecond).toHaveBeenCalledTimes(1);+ expect(onFirst).not.toHaveBeenCalled();+ }+ });++ it('leaves a Ctrl-, Cmd-, Shift- or middle click on a link item in its product menu to the browser', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ render(+ <TopNavHeading+ heading="My App"+ menu={+ <NavHeadingMenu>+ <NavHeadingMenuItem label="Docs" href="/docs" />+ <NavHeadingMenuItem label="Status" href="/status" />+ </NavHeadingMenu>+ }+ />,+ );+ await user.click(screen.getByRole('button', {name: 'Open menu'}));+ expectNativeLinkClicks(+ screen.getByRole('menuitem', {name: 'Docs', hidden: true}),+ );+ });++ it('after a pointer pick, returns focus to the trigger without a keyboard ring (interaction-modality INV1)', async () => {+ __resetMenuPressForTest();+ const user = userEvent.setup();+ render(+ <TopNavHeading+ heading="My App"+ menu={+ <NavHeadingMenu>+ <NavHeadingMenuItem label="Alpha" onClick={() => {}} />+ <NavHeadingMenuItem label="Beta" onClick={() => {}} />+ </NavHeadingMenu>+ }+ />,+ );+ const trigger = screen.getByRole('button', {name: 'Open menu'});+ await user.click(trigger);+ const focusSpy = vi.spyOn(trigger, 'focus');+ const alpha = screen.getByRole('menuitem', {name: 'Alpha', hidden: true});+ const mouse = {pointerType: 'mouse', pointerId: 4, button: 0};+ alpha.focus();+ fireEvent.pointerDown(alpha, mouse);+ fireEvent.pointerUp(alpha, mouse);+ expect(focusSpy).toHaveBeenCalledWith(+ expect.objectContaining({focusVisible: false}),+ );+ });+it('does not wrap the heading menu popup in a modal dialog', async () => {const user = userEvent.setup();render(<TopNavHeading heading="My App" menu={menuItems} />);diff --git a/packages/core/src/TopNav/TopNavHeading.spec.md b/packages/core/src/TopNav/TopNavHeading.spec.mdindex 4e6e4727e5..6cfc5d14b2 100644--- a/packages/core/src/TopNav/TopNavHeading.spec.md+++ b/packages/core/src/TopNav/TopNavHeading.spec.md@@ -16,7 +16,12 @@ verified_by:apps/storybook/stories/TopNav.stories.tsx,]modules: []-families: [family:navigation-destinations, family:overlay-dismissal]+families:+ [+ family:navigation-destinations,+ family:overlay-dismissal,+ family:action-groups,+ ]design_specs: []architecture:[@@ -114,17 +119,18 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | The root carries `top-nav-heading` and shows, in order: the logo, 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` at the inline end. With `menu`, the heading row holds the heading then the chevron button; without `menu` there is no chevron. | Current source and tests |-| FR2 | Configuration: no `heading` and no `menu` → logo only, a link named by `logoLabel` when `headingHref` is set, else a `div`; `headingHref` alone without `menu` → the whole block is one link; other `*Href` props without `menu` → each line with an href is its own link and a linked logo is named by `logoLabel`, else `heading`; `menu` without any href → the whole block opens the menu; `menu` with hrefs → the links stay independent, and the chevron button and the rest of the block open the menu; otherwise a plain `div`. | Current source and tests |-| FR3 | The logo link, the whole-heading link, the logo-only 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 | In both menu configurations, the chevron is a button named by the translated `@astryx.topNav.heading.openMenu` that toggles the menu; it is at least 28 by 28 px. | Current source and tests |-| FR5 | On a hover-capable pointer, hovering the block opens the menu immediately and does not move focus; a click within 500 ms of a hover-open keeps the menu open and moves focus to the first menu item, and a later click closes it. | Current source and tests |-| FR6 | Clicking a link inside a menu configuration navigates without toggling the menu. | Current source |-| FR7 | The menu is a non-modal popover below the block, aligned to its start and overlapping it. It contains a heading button that closes the menu (see Current-state impact for its content), then a `role="menu"` region named by `heading` (or `@astryx.topNav.heading.dialogLabel`) that holds `menu`. | Current source and tests |-| FR8 | Escape closes the menu and returns focus to the trigger. | Current source and tests |-| FR9 | Descendants of `menu` receive a close action, which NavHeadingMenu items call on selection. | Current source |+| ID | Invariant | Basis |+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | The root carries `top-nav-heading` and shows, in order: the logo, 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` at the inline end. With `menu`, the heading row holds the heading then the chevron button; without `menu` there is no chevron. | Current source and tests |+| FR2 | Configuration: no `heading` and no `menu` → logo only, a link named by `logoLabel` when `headingHref` is set, else a `div`; `headingHref` alone without `menu` → the whole block is one link; other `*Href` props without `menu` → each line with an href is its own link and a linked logo is named by `logoLabel`, else `heading`; `menu` without any href → the whole block opens the menu; `menu` with hrefs → the links stay independent, and the chevron button and the rest of the block open the menu; otherwise a plain `div`. | Current source and tests |+| FR3 | The logo link, the whole-heading link, the logo-only 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 | In both menu configurations, the chevron is a button named by the translated `@astryx.topNav.heading.openMenu` that toggles the menu; it is at least 28 by 28 px. | Current source and tests |+| FR5 | On a hover-capable pointer, hovering the block opens the menu immediately and does not move focus; a click within 500 ms of a hover-open keeps the menu open and moves focus to the first menu item, and a later click closes it. | Current source and tests |+| FR6 | Clicking a link inside a menu configuration navigates without toggling the menu. | Current source |+| FR7 | The menu is a non-modal popover below the block, aligned to its start and overlapping it. It contains a heading button that closes the menu (see Current-state impact for its content), then a `role="menu"` region named by `heading` (or `@astryx.topNav.heading.dialogLabel`) that holds `menu`. | Current source and tests |+| FR8 | Escape closes the menu and returns focus to the trigger. | Current source and tests |+| FR9 | Descendants of `menu` receive a close action, which NavHeadingMenu items call on selection. | Current source |+| 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@@ -182,11 +188,12 @@ is recorded.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ----------------- | ---------------------------------------------------------- | ------------------------------------- | --------------------------------------------- | ----------------------------------- |-| FR1–FR3, AR1 | `TopNav.test.tsx` TopNavHeading render and logo-name tests | Each configuration | A wrong element or unnamed logo link fails. | `audit:TopNavHeading/behavior` |-| FR4, FR7, AR2–AR3 | `TopNav.test.tsx` menu popover semantics tests | Whole trigger; links plus trigger | A modal wrapper or misplaced menu role fails. | `audit:TopNavHeading/accessibility` |-| FR5, FR8 | `TopNav.test.tsx` hover/click guard tests | Hover-open, click, late click, Escape | Losing the guard or focus return fails. | `audit:TopNavHeading/behavior` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ----------------- | --------------------------------------------------------------------------- | ------------------------------------- | --------------------------------------------- | ----------------------------------- |+| FR1–FR3, AR1 | `TopNav.test.tsx` TopNavHeading render and logo-name tests | Each configuration | A wrong element or unnamed logo link fails. | `audit:TopNavHeading/behavior` |+| FR4, FR7, AR2–AR3 | `TopNav.test.tsx` menu popover semantics tests | Whole trigger; links plus trigger | A modal wrapper or misplaced menu role fails. | `audit:TopNavHeading/accessibility` |+| FR5, FR8 | `TopNav.test.tsx` hover/click guard tests | Hover-open, click, late click, Escape | Losing the guard or focus return fails. | `audit:TopNavHeading/behavior` |+| FR10 | `TopNav.test.tsx` TopNavHeading menu-popover suite (touch and mouse slides) | Touch and mouse slides across items | Removing the adoption fails the slide tests. | — |Read from source, with no focused test yet: that clicking the block itself opens the menu in the menu-without-hrefs configuration (FR2); the `dialogLabel` fallback name of the menu (FR7); that the rest of the block opens the menu in the links-plus-trigger configuration (FR2); the `top-nav-heading` target (FR1); line truncation, part order, and `headerEndContent` (FR1); `as` and `LinkProvider` rendering (FR3); the chevron button's size (FR4); FR6; the popover's placement (FR7); and FR9.diff --git a/packages/core/src/TopNav/TopNavHeading.tsx b/packages/core/src/TopNav/TopNavHeading.tsxindex 2636d4f803..e8808431f3 100644--- a/packages/core/src/TopNav/TopNavHeading.tsx+++ b/packages/core/src/TopNav/TopNavHeading.tsx@@ -38,6 +38,10 @@ import {mergeProps} from '../utils';import {useMergedRefs} from '../hooks/useMergedRefs';import type {BaseProps} from '../BaseProps';import {useMenuHover} from '../hooks/useMenuHover';+import {useMenuPress} from '../hooks/useMenuPress';+import {pressOnItemsOnly} from '../hooks/menuPressOnItems';+import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';+import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';import {NavHeadingCloseContext} from '../NavMenu/NavMenuContext';import {themeProps} from '../utils/themeProps';import {useTranslator} from '../i18n';@@ -361,6 +365,27 @@ export function TopNavHeading({showDelay: 0,});+ // A press that slides across the product menu's items acts on the item it+ // lifts on, the highlight following the pointer (`family:action-groups`+ // FR1-FR3, FR5); a mouse released outside closes it. Only the role="menu"+ // region is tracked, not the heading above it.+ const productMenuRef = useRef<HTMLDivElement>(null);+ const productMenuPress = useMenuPress({+ menuRef: productMenuRef,+ itemSelector: '[role="menuitem"]:not([aria-disabled="true"])',+ onDismiss: closeMenu,+ isEnabled: !!menu,+ });+ const productMenuPointerDown = pressOnItemsOnly(+ productMenuPress.menuProps.onPointerDown,+ '[role="menuitem"]:not([aria-disabled="true"])',+ );+ const productMenuTouch = stylex.props(+ useMenuOverflow(productMenuRef, menu, popover.isOpen)+ ? menuTouchActionStyles.scrolls+ : menuTouchActionStyles.fits,+ );+const closeMenuCtx = useMemo(() => ({closeMenu}), [closeMenu]);// setTriggerEl belongs on the chevron button, not this root: it is the@@ -551,8 +576,12 @@ export function TopNavHeading({heading button above stays a valid sibling, not an invalidchild of a role="menu" element. */}<div+ ref={productMenuRef}role="menu"- aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>+ aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}+ {...productMenuPress.menuProps}+ onPointerDown={productMenuPointerDown}+ {...productMenuTouch}><NavHeadingCloseContext value={closeMenuCtx}>{menu}</NavHeadingCloseContext>@@ -630,8 +659,12 @@ export function TopNavHeading({heading button above stays a valid sibling, not an invalidchild of a role="menu" element. */}<div+ ref={productMenuRef}role="menu"- aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>+ aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}+ {...productMenuPress.menuProps}+ onPointerDown={productMenuPointerDown}+ {...productMenuTouch}><NavHeadingCloseContext value={closeMenuCtx}>{menu}</NavHeadingCloseContext>diff --git a/packages/core/src/TopNav/TopNavMenu.spec.md b/packages/core/src/TopNav/TopNavMenu.spec.mdindex 14bc1305a6..70f4145130 100644--- a/packages/core/src/TopNav/TopNavMenu.spec.md+++ b/packages/core/src/TopNav/TopNavMenu.spec.md@@ -17,7 +17,12 @@ verified_by:apps/storybook/stories/TopNavMenu.stories.tsx,]modules: []-families: [family:navigation-destinations, family:overlay-dismissal]+families:+ [+ family:navigation-destinations,+ family:overlay-dismissal,+ family:action-groups,+ ]design_specs: [design:reduced-motion]architecture:[@@ -101,18 +106,19 @@ Consumer migration instructions belong in consumer docs and release notes.## Behavioral and layout contract-| ID | Invariant | Basis |-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | In `default` mode the trigger is a `<button>` showing `label` and a chevron that turns when open; it carries `top-nav-menu`, the forwarded `ref`, and other DOM props, and announces a menu popup with its expanded state. | Current source and tests |-| FR2 | On a hover-capable pointer, hovering the trigger opens the menu after `delay` ms and leaving the trigger and the menu closes it after `hideDelay` ms; a hover-open does not move focus. A click opens the menu and moves focus to the first item; a click within 500 ms of a hover-open keeps it open. | Current source and tests |-| FR3 | The popup is a non-modal popover below the trigger, aligned to the trigger's TopNav slot (start, center, or end). It contains one `role="menu"` named by `label`, followed by a close button named by `@astryx.popover.close` that stays visually hidden until it holds focus. | Current source and tests |-| FR4 | Each item is a `role="menuitem"`: an `<a>` when `href` is set (rendering its `href` only when the URL is accepted), else a `div`. Bar items render a native `<a>`, not the `LinkProvider` link. It shows an icon box, the title, and the description, and runs the item's `onClick` on activation. | Current source and tests |-| FR5 | Items use a roving tab index with exactly one tab stop. ArrowDown and ArrowUp move focus and wrap at both ends; typing a character moves to the matching item; Enter or Space activates the focused item; Escape closes the menu and returns focus to the trigger. | APG menu pattern; tests |-| FR6 | Caller `onClick`, `onMouseEnter`, and `onMouseLeave` on the trigger run before the built-in open behavior and compose with it instead of replacing it; a caller handler that calls `preventDefault()` cancels the built-in open or toggle for that event. Caller attributes never override the popup wiring. | Current source and tests |-| FR7 | In `drawer` mode the trigger is a full-width disclosure button with `aria-expanded` and `aria-controls`; activating it toggles the group. Collapsed items are `inert` and `aria-hidden`, and the group clips while collapsed and while it expands, and stops clipping once fully expanded. Without a reduced-motion preference, expansion animates the group's height. | Current source and tests |-| FR8 | Drawer items render through the `LinkProvider` link component; activating one runs the item's `onClick` and then closes the AppShell drawer. | Current source |-| FR9 | In `mobile-bar` mode TopNavMenu renders nothing. | Current source |-| FR10 | The trigger, each bar item, and each drawer control paint the shared focus outline. | Current source and tests |+| ID | Invariant | Basis |+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | In `default` mode the trigger is a `<button>` showing `label` and a chevron that turns when open; it carries `top-nav-menu`, the forwarded `ref`, and other DOM props, and announces a menu popup with its expanded state. | Current source and tests |+| FR2 | On a hover-capable pointer, hovering the trigger opens the menu after `delay` ms and leaving the trigger and the menu closes it after `hideDelay` ms; a hover-open does not move focus. A click opens the menu and moves focus to the first item; a click within 500 ms of a hover-open keeps it open. | Current source and tests |+| FR3 | The popup is a non-modal popover below the trigger, aligned to the trigger's TopNav slot (start, center, or end). It contains one `role="menu"` named by `label`, followed by a close button named by `@astryx.popover.close` that stays visually hidden until it holds focus. | Current source and tests |+| FR4 | Each item is a `role="menuitem"`: an `<a>` when `href` is set (rendering its `href` only when the URL is accepted), else a `div`. Bar items render a native `<a>`, not the `LinkProvider` link. It shows an icon box, the title, and the description, and runs the item's `onClick` on activation. | Current source and tests |+| FR5 | Items use a roving tab index with exactly one tab stop. ArrowDown and ArrowUp move focus and wrap at both ends; typing a character moves to the matching item; Enter or Space activates the focused item; Escape closes the menu and returns focus to the trigger. | APG menu pattern; tests |+| FR6 | Caller `onClick`, `onMouseEnter`, and `onMouseLeave` on the trigger run before the built-in open behavior and compose with it instead of replacing it; a caller handler that calls `preventDefault()` cancels the built-in open or toggle for that event. Caller attributes never override the popup wiring. | Current source and tests |+| FR7 | In `drawer` mode the trigger is a full-width disclosure button with `aria-expanded` and `aria-controls`; activating it toggles the group. Collapsed items are `inert` and `aria-hidden`, and the group clips while collapsed and while it expands, and stops clipping once fully expanded. Without a reduced-motion preference, expansion animates the group's height. | Current source and tests |+| FR8 | Drawer items render through the `LinkProvider` link component; activating one runs the item's `onClick` and then closes the AppShell drawer. | Current source |+| FR9 | In `mobile-bar` mode TopNavMenu renders nothing. | Current source |+| FR10 | The trigger, each bar item, and each drawer control paint the shared focus outline. | Current source and tests |+| FR11 | 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). Link items are undraggable, so a mouse slide is not a drag; a Ctrl-, Cmd- or Shift-click or a middle click on a link item stays the browser's; and keyboard and assistive-technology behavior is unchanged. | Current source and tests |### Allowed variation@@ -169,13 +175,14 @@ recorded.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ----------------- | ---------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------- |-| FR1, FR3, AR1 | `TopNavMenu.test.tsx` trigger and semantics tests | Closed and open | A dialog wrapper or wrong popup type fails. | `audit:TopNavMenu/accessibility` |-| FR4, FR5, AR2 | `TopNavMenu.test.tsx` keyboard tests | Arrows, wrap, typeahead, Enter, Escape | Extra tab stops or lost activation fails. | `audit:TopNavMenu/accessibility` |-| FR6 | `TopNavMenu.test.tsx` pass-through and owned-handler tests | Bar and drawer triggers | A replaced built-in handler or lost prop fails. | `audit:TopNavMenu/behavior` |-| FR7, FR10, AR3 | `TopNavMenu.test.tsx` drawer tests | Collapsed and expanded | Reachable collapsed items or a missing ring fails. | `audit:TopNavMenu/behavior` |-| Shared menu focus | `useMenuHover.test.tsx` | Hover-open, click-open, Escape, Enter and Space | Focus moved on hover, not moved in on click, or not returned on Escape fails. | `audit:TopNavMenu/accessibility` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ----------------- | ----------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------- |+| FR1, FR3, AR1 | `TopNavMenu.test.tsx` trigger and semantics tests | Closed and open | A dialog wrapper or wrong popup type fails. | `audit:TopNavMenu/accessibility` |+| FR4, FR5, AR2 | `TopNavMenu.test.tsx` keyboard tests | Arrows, wrap, typeahead, Enter, Escape | Extra tab stops or lost activation fails. | `audit:TopNavMenu/accessibility` |+| FR6 | `TopNavMenu.test.tsx` pass-through and owned-handler tests | Bar and drawer triggers | A replaced built-in handler or lost prop fails. | `audit:TopNavMenu/behavior` |+| FR7, FR10, AR3 | `TopNavMenu.test.tsx` drawer tests | Collapsed and expanded | Reachable collapsed items or a missing ring fails. | `audit:TopNavMenu/behavior` |+| Shared menu focus | `useMenuHover.test.tsx` | Hover-open, click-open, Escape, Enter and Space | Focus moved on hover, not moved in on click, or not returned on Escape fails. | `audit:TopNavMenu/accessibility` |+| FR11 | `TopNavMenu.test.tsx` action-group suite (touch and mouse slides) | Touch and mouse slides across items; undraggable link items | Removing the adoption fails the slide tests. | — |Read from source, with no focused test yet: the visually hidden close button after the menu (FR3); the native `<a>` for bar items, the icon box, and the description (FR4); the forwarded `ref`, the `top-nav-menu` target, and the bar and drawer chevrons' turn (FR1, FR7); the drawer group's clipping while it expands and its height animation (FR7); the caller `preventDefault()` cancellation (FR6); hover opening and closing with `delay` and `hideDelay` (FR2); slot alignment (FR3); FR8; FR9; and the bar trigger and item parts of FR10.diff --git a/packages/core/src/TopNav/TopNavMenu.test.tsx b/packages/core/src/TopNav/TopNavMenu.test.tsxindex 3502db4ca1..12f83e5cb5 100644--- a/packages/core/src/TopNav/TopNavMenu.test.tsx+++ b/packages/core/src/TopNav/TopNavMenu.test.tsx@@ -9,13 +9,15 @@* SYNC: When TopNavMenu changes, update tests to match new behavior*/-import {describe, it, expect, vi} from 'vitest';+import {beforeEach, describe, it, expect, vi} from 'vitest';import {render, screen, fireEvent, act} from '@testing-library/react';import userEvent from '@testing-library/user-event';import * as stylex from '@stylexjs/stylex';import {focusOutlineStyles} from '../utils/focusOutline.stylex';import {TopNavRenderContext} from './TopNavRenderContext';import {TopNavMenu} from './TopNavMenu';+import {__resetMenuPressForTest} from '../hooks/useMenuPress';+import {expectNativeLinkClicks} from '../hooks/__tests__/menuLinkClicks';const mockItems = [{@@ -419,3 +421,65 @@ describe('TopNavMenu — owned handlers on the trigger', () => {expect(handleMouseEnter).toHaveBeenCalledOnce();});});++describe('TopNavMenu as an action group (family:action-groups)', () => {+ beforeEach(() => {+ __resetMenuPressForTest();+ });++ const item = (name: RegExp) =>+ screen.getByRole('menuitem', {name, hidden: true});++ it('renders a link item undraggable, so a mouse press that slides to another item is not a drag', () => {+ render(+ <TopNavMenu+ label="Products"+ items={[+ {title: 'Docs', href: '/docs'},+ {title: 'Status', onClick: () => {}},+ ]}+ />,+ );+ expect(item(/Docs/)).toHaveAttribute('draggable', 'false');+ expect(item(/Status/)).not.toHaveAttribute('draggable');+ });++ it('leaves a Ctrl-, Cmd-, Shift- or middle click on a link item to the browser', () => {+ render(+ <TopNavMenu+ label="Products"+ items={[+ {title: 'Docs', href: '/docs'},+ {title: 'Status', href: '/status'},+ ]}+ />,+ );+ expectNativeLinkClicks(item(/Docs/));+ });++ it('acts on the item a press lifts on, once, after sliding from another (FR1, FR2, FR5)', () => {+ const onAnalytics = vi.fn();+ const onMessaging = vi.fn();+ render(+ <TopNavMenu+ label="Products"+ items={[+ {title: 'Analytics', onClick: onAnalytics},+ {title: 'Messaging', onClick: onMessaging},+ ]}+ />,+ );+ for (const pointer of [+ {pointerType: 'touch', pointerId: 1},+ {pointerType: 'mouse', pointerId: 2, button: 0},+ ]) {+ onAnalytics.mockClear();+ onMessaging.mockClear();+ fireEvent.pointerDown(item(/Analytics/), pointer);+ fireEvent.pointerMove(item(/Messaging/), pointer);+ fireEvent.pointerUp(item(/Messaging/), pointer);+ expect(onMessaging).toHaveBeenCalledTimes(1);+ expect(onAnalytics).not.toHaveBeenCalled();+ }+ });+});diff --git a/packages/core/src/TopNav/TopNavMenu.tsx b/packages/core/src/TopNav/TopNavMenu.tsxindex 060c0ba910..c1208427be 100644--- a/packages/core/src/TopNav/TopNavMenu.tsx+++ b/packages/core/src/TopNav/TopNavMenu.tsx@@ -26,6 +26,10 @@ import React, {import * as stylex from '@stylexjs/stylex';import {usePopover} from '../Popover/usePopover';import {useMenuHover} from '../hooks/useMenuHover';+import {useMenuPress} from '../hooks/useMenuPress';+import {pressOnItemsOnly} from '../hooks/menuPressOnItems';+import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';+import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';import {useListFocus} from '../hooks/useListFocus';import {useTypeahead} from '../hooks/useTypeahead';import {Icon} from '../Icon';@@ -451,6 +455,16 @@ export function TopNavMenu({// focus management) and the list-focus ref (for roving tabindex/typeahead).const setMenuRef = useMergedRefs<HTMLDivElement>(menuRef, listRef);+ // A press that slides across the items acts on the item it lifts on, the+ // highlight following the pointer, as every menu does+ // (`family:action-groups` FR1-FR3); a mouse released outside closes it.+ const menuPress = useMenuPress({+ menuRef: listRef,+ itemSelector: '[role="menuitem"]',+ onDismiss: close,+ });+ const hasOverflow = useMenuOverflow(listRef, items.length, popover.isOpen);+// Mobile bar: hide menus entirelyif (renderMode === 'mobile-bar') {return null;@@ -578,12 +592,22 @@ export function TopNavMenu({role="menu"aria-label={label}{...contentProps}+ {...menuPress.menuProps}+ onPointerDown={pressOnItemsOnly(+ menuPress.menuProps.onPointerDown,+ '[role="menuitem"]',+ )}// After the contentProps spread so the full APG composition (roving// tabindex + typeahead + Enter/Space activation) replaces the hover// hook's basic arrow-key handler.onKeyDown={menuKeyDown}onFocus={handleFocus}- {...stylex.props(styles.menuContainer)}>+ {...stylex.props(+ styles.menuContainer,+ hasOverflow+ ? menuTouchActionStyles.scrolls+ : menuTouchActionStyles.fits,+ )}>{items.map(item => {const Element = item.href ? 'a' : 'div';return (@@ -598,6 +622,9 @@ export function TopNavMenu({? item.href: undefined}+ // A menu row is never a draggable link: a mouse press that+ // slides to another item would start a drag instead.+ draggable={item.href != null ? false : undefined}onClick={item.onClick}{...focusOutlineProps.focusVisible(styles.menuItem)}><div {...stylex.props(styles.menuItemIcon)}>{item.icon}</div>diff --git a/packages/core/src/hooks/__tests__/menuLinkClicks.ts b/packages/core/src/hooks/__tests__/menuLinkClicks.tsnew file mode 100644index 0000000000..c1b90ddc99--- /dev/null+++ b/packages/core/src/hooks/__tests__/menuLinkClicks.ts@@ -0,0 +1,71 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file menuLinkClicks.ts+ * @input A link item inside an open menu that tracks presses with useMenuPress+ * @output expectNativeLinkClicks: asserts that a Ctrl-, Cmd- or Shift-click+ * and a middle click on the link reach the page once, not prevented, and+ * that the menu dispatches no activation of its own for them+ * @position Test helper for the menus that adopt useMenuPress over caller or+ * link items (NavHeadingMenu, TopNavMenu, SideNavHeading, TopNavHeading,+ * BreadcrumbItem)+ */++import {fireEvent} from '@testing-library/react';+import {expect} from 'vitest';++interface Seen {+ type: string;+ detail: number;+ defaultPrevented: boolean;+}++export function expectNativeLinkClicks(link: HTMLElement): void {+ const seen: Seen[] = [];+ const record = (event: Event) => {+ seen.push({+ type: event.type,+ detail: (event as MouseEvent).detail,+ defaultPrevented: event.defaultPrevented,+ });+ // The test page never navigates.+ event.preventDefault();+ };+ // Bubble phase on the document: what reaches the page after every+ // component handler ran.+ const view = link.ownerDocument;+ view.addEventListener('click', record);+ view.addEventListener('auxclick', record);+ try {+ let pointerId = 100;+ for (const modifier of ['ctrlKey', 'metaKey', 'shiftKey'] as const) {+ seen.length = 0;+ const init = {pointerType: 'mouse', pointerId: ++pointerId, button: 0};+ fireEvent.pointerDown(link, {...init, [modifier]: true});+ fireEvent.pointerUp(link, {...init, [modifier]: true});+ fireEvent.click(link, {detail: 1, button: 0, [modifier]: true});+ expect(seen, modifier).toEqual([+ {type: 'click', detail: 1, defaultPrevented: false},+ ]);+ }+ seen.length = 0;+ const middle = {pointerType: 'mouse', pointerId: ++pointerId, button: 1};+ fireEvent.pointerDown(link, middle);+ fireEvent.pointerUp(link, middle);+ fireEvent(+ link,+ new MouseEvent('auxclick', {+ bubbles: true,+ cancelable: true,+ detail: 1,+ button: 1,+ }),+ );+ expect(seen, 'middle').toEqual([+ {type: 'auxclick', detail: 1, defaultPrevented: false},+ ]);+ } finally {+ view.removeEventListener('click', record);+ view.removeEventListener('auxclick', record);+ }+}diff --git a/packages/core/src/hooks/menuPressOnItems.ts b/packages/core/src/hooks/menuPressOnItems.tsnew file mode 100644index 0000000000..4f2bf444d6--- /dev/null+++ b/packages/core/src/hooks/menuPressOnItems.ts@@ -0,0 +1,40 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file menuPressOnItems.ts+ * @input useMenuPress's menu `onPointerDown` and the menu's item selector+ * @output Exports pressOnItemsOnly: the same handler, run only for a press+ * that lands on an item and is not a modified mouse press on a link+ * @position Internal to core's menus with caller content or link items+ * (NavHeadingMenu, TopNavMenu, SideNavHeading's and TopNavHeading's menus,+ * BreadcrumbItem's menu)+ *+ * A menu that holds caller content beside its items (a button, a link list)+ * tracks only presses that land on an item. A press on anything else stays+ * the browser's own, so that content's click runs as it always has+ * (`architecture:interaction-modality` INV4). A mouse press with Ctrl, Cmd or+ * Shift on a link item is the browser's too, so it opens the link in a new+ * tab or window as it always has; a middle press never reaches the model.+ */++import type {PointerEvent as ReactPointerEvent} from 'react';++export function pressOnItemsOnly<E extends HTMLElement>(+ onPointerDown: (event: ReactPointerEvent<E>) => void,+ itemSelector: string,+): (event: ReactPointerEvent<E>) => void {+ return event => {+ const target = event.target;+ if (!(target instanceof Element) || target.closest(itemSelector) == null) {+ return;+ }+ const isModifiedLinkPress =+ event.pointerType === 'mouse' &&+ (event.ctrlKey || event.metaKey || event.shiftKey) &&+ target.closest('a[href]') != null;+ if (event.button !== 0 || isModifiedLinkPress) {+ return;+ }+ onPointerDown(event);+ };+}diff --git a/packages/core/src/hooks/useMenuHover.ts b/packages/core/src/hooks/useMenuHover.tsindex 7afcbf9c77..35ea2ddc4d 100644--- a/packages/core/src/hooks/useMenuHover.ts+++ b/packages/core/src/hooks/useMenuHover.ts@@ -40,6 +40,7 @@ import {useCallback, useEffect, useRef} from 'react';import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';import {useListFocus} from './useListFocus';import {useMediaQuery} from './useMediaQuery';+import {focusForLastInput} from '../utils/focusReturn';const DEFAULT_CLICK_GUARD_MS = 500;@@ -279,8 +280,11 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(const menuHadFocus =menuRef.current?.contains(document.activeElement) ?? false;hide();- if (menuHadFocus) {- triggerElRef.current?.focus();+ const trigger = triggerElRef.current;+ if (menuHadFocus && trigger != null) {+ // A pointer's pick leaves no keyboard ring on the trigger; a keyboard's+ // keeps it (`architecture:interaction-modality` INV1).+ focusForLastInput(trigger);}}, [hide, menuRef]);