@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Tooltip/useTooltip.tsx

@@ -21,7 +21,7 @@ import {
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
-  useLayer,
+  useLayerInternal,
   type ContextRenderProps,
   type LayerAlignment,
   type LayerPlacement,
@@ -279,10 +279,15 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     onHide,
   } = options;
 
-  const layer = useLayer({
+  // A tooltip stays open while its trigger is hovered, so it must never settle
+  // over the trigger: content taller than the room above and below opens
+  // beside it, or on the roomier side sized to that room, and scrolls what does not
+  // fit inside the surface, which stays hoverable (spec:AST-059 FR4).
+  const layer = useLayerInternal({
     mode: 'context',
     onShow,
     onHide,
+    keepsAnchorClear: true,
   });
   const {
     ref: layerRef,

package/src/TopNav/TopNav.spec.md

@@ -0,0 +1,190 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TopNav
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-25
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/TopNav/TopNav.test.tsx,
+    packages/core/src/TopNav/__tests__/TopNavMobileLongHeading.a11y.chromium.spec.ts,
+    packages/core/src/AppShell/AppShell.test.tsx,
+    apps/storybook/stories/TopNav.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# TopNav component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `TopNav` with `heading`, `startContent` (alias `children`), `centerContent`, `endContent`, and `label`; target `top-nav` with a `mode` state.                                                                                                                     |
+| Behavior                | A labeled navigation landmark with start, optional center, and end regions. Inside AppShell's mobile layout it becomes a compact bar (heading, end content, and, while auto toggles are on, a drawer toggle) and its start and center content move into a drawer. |
+| End-user impact         | Screen-reader users get a named navigation landmark; phone-width users keep the product heading, end controls, and, while auto toggles are on, a drawer toggle in view while the navigation items move into the drawer.                                           |
+| Builder impact          | None. Callers fill slots; `children` is accepted so nav items are not dropped.                                                                                                                                                                                    |
+| Compatibility/readiness | Records shipped behavior; no prop, default, target, or export changes. Two implementation gaps (see Current-state impact).                                                                                                                                        |
+| Review checks           | Reject dropping `children` when `startContent` is absent, dropping the three-column layout when `centerContent` is present, an unlabeled landmark, or a mobile bar that hides the toggle while drawer content exists and auto toggles are on (FR5).               |
+| Governing rules         | `component:AppShell` FR9–FR10 select the render mode; MobileNav owns the drawer dialog; `architecture:component-theming-surface`.                                                                                                                                 |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TopNav is the horizontal navigation bar of an application header. It owns the
+bar's landmark, its slot layout, and how the bar and its content render in each
+of the three modes AppShell selects: the full bar, the mobile bar, and the
+drawer. Consumer usage lives in `TopNav.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, target,
+  or export changes
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Caller props can replace the landmark's role and name.** Other DOM props
+  spread onto the `<nav>` after `role` and `aria-label`, so a caller `role` or
+  `aria-label` replaces them. `architecture:public-component-api` INV5 keeps
+  component-owned accessibility from being overwritten by accident.
+- **Wide end content shifts the center.** The end column sets no minimum width
+  of zero, so end content wider than its share widens that column and moves the
+  center content toward the start.
+
+## Ownership boundary
+
+**Owns**
+
+- The navigation landmark and its default name (FR1, AR1).
+- Slot resolution and the flex and three-column layouts (FR2–FR4).
+- The mobile-bar and drawer renderings of the bar itself (FR5, FR6).
+- The `<nav>`'s positioning and styling inputs (FR8, FR9).
+- The slot each descendant sits in, which TopNav menus read for popover
+  alignment (FR7).
+
+**Does not own / non-goals**
+
+- Each item's rendering in each mode — owned by `component:TopNavItem`,
+  `component:TopNavMenu`, `component:TopNavMegaMenu`,
+  `component:TopNavMegaMenuItem`, `component:TopNavMegaMenuFeaturedCard`, and
+  `component:TopNavHeading`.
+- Which render mode applies and when — owned by `component:AppShell`.
+- The drawer dialog, its header, focus behavior, and dismissal — owned by
+  MobileNav; the toggle is MobileNav's `MobileNavToggle`.
+- The exported `TopNavRenderContext` and `useTopNavRenderMode` — an uncontracted
+  module; this record covers only how TopNav responds to the mode.
+
+## Public concepts
+
+| Concept     | Closed values or states           | Meaning                                         | Availability by variant/orientation/state | Default   | Owner                | Stability | Invalid-value behavior              |
+| ----------- | --------------------------------- | ----------------------------------------------- | ----------------------------------------- | --------- | -------------------- | --------- | ----------------------------------- |
+| Render mode | `default`, `mobile-bar`, `drawer` | Full bar, compact phone bar, or drawer content. | Set by AppShell or the exported context.  | `default` | `component:AppShell` | Stable    | TypeScript rejects other values.    |
+| Slot        | `start`, `center`, `end`          | The region a descendant renders in.             | `default` mode.                           | `start`   | `component:TopNav`   | Stable    | Not caller-settable; set by TopNav. |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                             | Basis                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | In `default` and `mobile-bar` modes TopNav renders one `<nav role="navigation">` named by `label`, or by the translated `@astryx.topNav.landmarkLabel` ("Top navigation") when `label` is omitted. It carries `top-nav`, the forwarded `ref`, and other DOM props; `mobile-bar` adds `data-mode="mobile-bar"`.                                                                        | Current source and tests |
+| FR2 | `startContent` wins over `children`; `children` render as start content only when `startContent` is `null` or `undefined`.                                                                                                                                                                                                                                                            | Current source and tests |
+| FR3 | Without `centerContent` the bar is a flex row: heading then start content at the inline start, end content pushed to the inline end.                                                                                                                                                                                                                                                  | Current source and tests |
+| FR4 | With `centerContent` the bar is a three-column grid (`1fr auto 1fr`) that centers the center content while the start and end regions each fit their equal share.                                                                                                                                                                                                                      | Current source and tests |
+| FR5 | `mobile-bar` mode renders the heading, then the end content and, when drawer content exists and auto toggles are on, the mobile nav toggle at the inline end. Start and center content do not render. The heading yields width first so end content and the toggle stay on screen. Drawer content exists when start or center content is present or AppShell passes side nav content. | Current source and tests |
+| FR6 | `drawer` mode renders a MobileNav whose header is `heading` and whose body is start then center content in a vertical list, a divider when items and side nav content are both present, then any side nav content AppShell passes. With neither, TopNav renders nothing.                                                                                                              | Current source and tests |
+| FR7 | In `default` mode TopNav tells start, center, and end descendants which slot they are in.                                                                                                                                                                                                                                                                                             | Current source           |
+| FR8 | The `<nav>` itself is not a positioned element, so it creates no stacking context.                                                                                                                                                                                                                                                                                                    | Current source and tests |
+| FR9 | `className`, `style`, and `xstyle` merge onto the `<nav>` after component styles in `default` and `mobile-bar` modes.                                                                                                                                                                                                                                                                 | Current source           |
+
+### Allowed variation
+
+- **AV1 — Slot content.** Caller content varies without becoming TopNav anatomy.
+- **AV2 — Theme styling.** Themes may restyle `top-nav` per mode without changing
+  regions, order, or the landmark.
+
+### Representative states
+
+| State                             | Required invariant                                                       | Allowed variation   |
+| --------------------------------- | ------------------------------------------------------------------------ | ------------------- |
+| Heading and items, no center      | Flex row; end content at the inline end.                                 | Gaps and padding.   |
+| Center content present            | Three-column grid; center centered while each side fits its share (FR4). | Column content.     |
+| Mobile bar with a long heading    | With auto toggles on, toggle and end content stay inside the bar.        | Heading truncation. |
+| Mobile bar with no drawer content | No toggle.                                                               | —                   |
+| Drawer with items and side nav    | Items, divider, side nav content.                                        | Item modes.         |
+
+### Transformation and precedence order
+
+- **ORD1 — Start content.** `startContent`, then `children` (FR2).
+
+### Performance and resources
+
+- **PR1 — No measurement.** TopNav observes no size and registers no listener.
+
+## Accessibility contract
+
+- **AR1 — Named landmark.** Every rendered bar is a navigation landmark with an
+  accessible name (FR1).
+- **AR2 — Toggle reachable.** In `mobile-bar` mode with drawer content and auto
+  toggles on, the toggle stays fully on screen, and inside the opened drawer the close button
+  stays fully in the viewport, even with a long heading.
+
+## Design relationships
+
+| Anatomy or state      | Design requirement                                | Representation authority       | Hierarchy role | Component contract |
+| --------------------- | ------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Product icon and name | Heading slot at the inline start.                 | Current source and public docs | Prominent      | FR3, FR5           |
+| Navigation items      | Start or center content.                          | Current source and public docs | Prominent      | FR2–FR4, FR6       |
+| More menu             | A caller-placed menu; TopNav renders none itself. | Public docs                    | Supporting     | FR2                |
+| Flex area             | End content for search, actions, or profile.      | Current source and public docs | Supporting     | FR3, FR5           |
+
+No anatomy-theming map is recorded yet; the block is optional during migration.
+Mapping TopNav's four anatomy parts against the family's seven targets, by
+delegation where a part belongs to a sub-component, is deferred. Each family
+component's record names its own target.
+
+## Family and system relationships
+
+- `component:AppShell` selects the render mode and passes side nav content.
+- MobileNav renders the drawer TopNav fills.
+- `architecture:component-theming-surface` owns target qualification.
+
+## Verification map
+
+| Contract     | Verification                                    | Representative states                           | Mutation or failure expectation                            | Audit section                |
+| ------------ | ----------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- | ---------------------------- |
+| FR1, AR1     | `TopNav.test.tsx` landmark tests                | Default and mobile-bar; default and custom name | A missing role or name fails.                              | `audit:TopNav/accessibility` |
+| FR2–FR4, FR8 | `TopNav.test.tsx` slot tests                    | Each slot; all slots; center without start/end  | A dropped slot, wrong precedence, or positioned nav fails. | `audit:TopNav/layout`        |
+| FR5, FR6     | `AppShell.test.tsx` mobile suites               | Heading-only; items; items with side nav        | A missing toggle or duplicated items fails.                | `audit:TopNav/behavior`      |
+| AR2          | `TopNavMobileLongHeading.a11y.chromium.spec.ts` | Long heading at phone width                     | The toggle or close button leaves the viewport.            | `audit:TopNav/accessibility` |
+
+Read from source, with no focused test yet: the mobile bar's part order (FR5); the drawer's `heading` header (FR6); other DOM props reaching the `<nav>` (FR1); the auto-toggle condition (FR5); rendering nothing in `drawer` mode with no content (FR6); the `top-nav` target and its `mode` state (FR1); the flex and grid layout geometry (FR3, FR4); that start and center content do not render in the mobile bar (FR5); the drawer's content order and divider (FR6); FR7; and FR9.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, item behavior, or
+the drawer's dialog behavior. It links to their owners.

package/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} />);

package/src/TopNav/TopNavHeading.spec.md

@@ -0,0 +1,211 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TopNavHeading
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-25
+owners: [cixzhang]
+review_triggers: [public-api, behavior, accessibility]
+verified_by:
+  [
+    packages/core/src/TopNav/TopNav.test.tsx,
+    apps/storybook/stories/TopNav.stories.tsx,
+  ]
+modules: []
+families:
+  [
+    family:navigation-destinations,
+    family:overlay-dismissal,
+    family:action-groups,
+  ]
+design_specs: []
+architecture:
+  [
+    architecture:component-style-authoring,
+    architecture:interaction-modality,
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: []
+---
+
+# TopNavHeading component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `TopNavHeading` with `logo`, `logoLabel`, `heading`, `superheading`, `subheading`, their `*Href` links, `headerEndContent`, `menu`, and `as`; target `top-nav-heading`. |
+| Behavior                | The product identity block. Which parts are links and which part opens the menu follows from which `*Href` props and `menu` are set (FR2).                              |
+| End-user impact         | Users reach product, suite, and account destinations and a product switcher menu; screen-reader users hear a named logo link and a named menu.                          |
+| Builder impact          | None.                                                                                                                                                                   |
+| Compatibility/readiness | Records shipped behavior; no public change. Five implementation gaps (see Current-state impact).                                                                        |
+| Review checks           | Reject a logo link without an accessible name, a menu popup wrapped in a modal dialog, or a heading button placed inside `role="menu"`.                                 |
+| Governing rules         | `architecture:public-component-api` INV5; `architecture:interaction-modality` (shared focus indicator); `architecture:component-theming-surface`.                       |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TopNavHeading presents the product's logo and name, with optional suite and
+account lines, in the TopNav heading slot. It owns how those parts become links
+or a menu trigger and the product menu popover. Consumer usage lives in
+`TopNavHeading.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: the menu's open state is internal
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Menu configurations drop DOM props.** When `menu` is set, other DOM props
+  passed to TopNavHeading (beyond `data-testid`, `className`, `style`, `xstyle`,
+  and `ref`) do not reach any element. `architecture:public-component-api` INV5
+  requires accepted DOM, data, ARIA, and event inputs to reach the owning
+  element.
+- **Browser default focus rings.** The chevron menu button, the whole-heading
+  link, the linked logo, the logo-only link, the menu-configuration heading
+  link, and the popover's heading button do not use the shared focus outline;
+  keyboard focus on them paints the browser's default ring.
+  `architecture:interaction-modality` provides the shared focus indicator these
+  controls bypass.
+
+- **NavHeadingMenu nests a second menu.** The heading wraps `menu` in its own
+  `role="menu"`; NavHeadingMenu, the documented `menu` content, adds another
+  `role="menu"` inside it. WAI-ARIA 1.2 allows a `menu` to own only
+  `menuitem`-family items and groups.
+- **Links nested in the popover's heading button.** In the links-plus-trigger
+  configuration, the popover's heading button repeats the superheading,
+  heading, and subheading links inside itself, so interactive content is nested
+  inside a button. HTML forbids interactive content inside a `<button>`.
+- **The open menu repeats the identity row.** While the menu is open, its
+  heading button repeats the logo and text that stay mounted in the bar's block,
+  so that content renders twice. `architecture:component-style-authoring` INV7
+  has content render once.
+
+## Ownership boundary
+
+**Owns**
+
+- The identity block layout and its link and trigger configurations (FR1–FR6).
+- The product menu popover and its close behavior (FR7–FR9).
+
+**Does not own / non-goals**
+
+- Destination acceptance and blocking for every `href` this component renders —
+  owned by `family:navigation-destinations`.
+- Menu content — owned by the caller; NavHeadingMenu items read the close action this
+  component provides (NavHeadingMenu).
+- The logo artwork — owned by the caller, typically NavIcon.
+- The TopNav heading slot and mobile-bar placement — owned by `component:TopNav`.
+- Popover positioning and layer hosting — owned by the shared popover and layer
+  runtime.
+
+## Public concepts
+
+| Concept       | Closed values or states                                                            | Meaning                                                    | Availability by variant/orientation/state | Default | Owner                     | Stability | Invalid-value behavior |
+| ------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------------- | ------- | ------------------------- | --------- | ---------------------- |
+| Configuration | logo only, plain, whole link, independent links, whole trigger, links plus trigger | Derived from which `*Href` props and `menu` are set (FR2). | All.                                      | Plain   | `component:TopNavHeading` | Stable    | Not applicable.        |
+
+## 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           |
+| FR10 | In the product menu's `role="menu"` region, a press (finger, pen or mouse) that lands on an enabled item and slides across the items acts on the one it lifts on, once, through that item's own activation, with the highlight following the pointer; a lift outside acts on nothing, and a mouse released outside closes the menu. The menu adopts `module:DropdownMenu/useMenuPress` for this (`family:action-groups` FR1–FR5; `module:DropdownMenu/useMenuPress` DEC-7). A press on caller content that is not an item, and a Ctrl-, Cmd- or Shift-click or a middle click on a link item, stays that content's or the browser's own, and keyboard and assistive-technology behavior is unchanged. | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Logo artwork and lines.** Any combination of lines may be present; the
+  block keeps its order.
+
+### Representative states
+
+| State                      | Required invariant                                            | Allowed variation |
+| -------------------------- | ------------------------------------------------------------- | ----------------- |
+| Heading with `headingHref` | One link wrapping logo and text.                              | —                 |
+| Suite and product links    | Independent links; logo link named.                           | Line content.     |
+| Menu, no hrefs             | Whole block triggers; chevron button named.                   | Menu content.     |
+| Menu with hrefs            | Links independent; chevron and the rest of the block trigger. | Menu content.     |
+| Logo only with href        | Link named by `logoLabel`.                                    | Artwork.          |
+
+### Transformation and precedence order
+
+- **ORD1 — Logo link name.** `logoLabel`, then `heading`.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Named links.** A linked logo without adjacent link text is named by
+  `logoLabel` or `heading`.
+- **AR2 — Menu semantics.** The popup is not a modal dialog; `role="menu"`
+  wraps only the menu content, never the popover's heading button.
+- **AR3 — Named trigger.** The chevron button has a translated name and exposes
+  the popover's expanded state.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                     | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Logo             | Leading product mark.                                                  | Current source and public docs | Prominent      | FR1, FR2           |
+| Heading lines    | Superheading, heading, subheading; plain lines stay on one line (FR1). | Current source and public docs | Prominent      | FR1                |
+| Menu popover     | Overlaps the block; a heading button closes it.                        | Current source                 | Supporting     | FR7                |
+
+`TopNavHeading.doc.mjs` declares no anatomy of its own, so no anatomy-theming map
+is recorded.
+
+## Family and system relationships
+
+- `family:overlay-dismissal` owns Escape and close-request ordering for this
+  component's popover.
+- `family:navigation-destinations` owns the accept/block decision for each
+  destination this component renders.
+- `component:TopNav` places the heading in its heading slot and mobile bar.
+- NavHeadingMenu items close this menu through the provided close action.
+- `architecture:public-component-api` INV5 and `architecture:interaction-modality`
+  govern the gaps under Current-state impact.
+
+## 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`      |
+| 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.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, or popover
+mechanics. It links to their owners.

package/src/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 invalid
                 child 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 invalid
                 child 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>