@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/TopNav/TopNavMegaMenuFeaturedCard.spec.md

@@ -0,0 +1,150 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TopNavMegaMenuFeaturedCard
+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]
+modules: []
+families: [family:navigation-destinations]
+design_specs: [design:bidirectionality]
+architecture:
+  [architecture:interaction-modality, architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# TopNavMegaMenuFeaturedCard component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `TopNavMegaMenuFeaturedCard` with `title`, `description`, `image`, `imageAlt`, `linkLabel`, `linkHref`, and `children`; target `top-nav-mega-menu-featured-card`. |
+| Behavior                | A promotional card for a mega menu's featured slot: optional image, title, description, an optional call-to-action link, then caller content.                     |
+| End-user impact         | Users see a highlighted destination; screen-reader users skip a decorative image unless `imageAlt` names it.                                                      |
+| Builder impact          | None.                                                                                                                                                             |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps (see Current-state impact).                                                                   |
+| Review checks           | Reject an image without `imageAlt` that is exposed to assistive technology, or a link rendered when only one of `linkLabel` and `linkHref` is set.                |
+| Governing rules         | `design:bidirectionality` DR4; `architecture:interaction-modality`; `architecture:component-theming-surface`.                                                     |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TopNavMegaMenuFeaturedCard fills a TopNavMegaMenu's featured slot with a card
+that promotes one destination. Consumer usage lives in
+`TopNavMegaMenuFeaturedCard.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **The link arrow does not mirror.** The call-to-action link ends with a
+  literal `→`, which points right in right-to-left layouts too.
+  `design:bidirectionality` DR4 requires a progression glyph to mirror once.
+- **Browser default focus ring.** The call-to-action link does not use the shared
+  focus outline; keyboard focus paints the browser's default ring.
+  `architecture:interaction-modality` provides the shared indicator it bypasses.
+
+## Ownership boundary
+
+**Owns**
+
+- The card's content order, image semantics, and link condition (FR1–FR4).
+
+**Does not own / non-goals**
+
+- Destination acceptance and blocking for every `href` this component renders —
+  owned by `family:navigation-destinations`.
+- Placement in the panel and drawer — owned by `component:TopNavMegaMenu`.
+- Caller `children` content.
+
+## Public concepts
+
+No component-local concept beyond the consumer props.
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                  | Basis                    |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The root `div` carries `top-nav-mega-menu-featured-card`, the forwarded `ref`, and other DOM props, and shows: the image (full width, 140 px tall) when `image` is set, then the title, description, link, and `children`. | Current source and tests |
+| FR2 | Without `imageAlt` the image is decorative: `alt=""`, `role="presentation"`, and `aria-hidden="true"`. With `imageAlt` it is a normal image with that alternative text.                                                    | Current source and tests |
+| FR3 | The link renders only when both `linkLabel` and `linkHref` are set, through the `LinkProvider` link component, as `linkLabel` followed by ` →`.                                                                            | Current source and tests |
+| FR4 | `className`, `style`, and `xstyle` merge after component styles.                                                                                                                                                           | Current source           |
+
+### Allowed variation
+
+- **AV1 — Optional parts.** Image, description, link, and children may each be
+  absent.
+
+### Representative states
+
+| State            | Required invariant                      | Allowed variation |
+| ---------------- | --------------------------------------- | ----------------- |
+| Decorative image | Image hidden from assistive technology. | Image.            |
+| Described image  | Image exposed with `imageAlt`.          | —                 |
+| With link        | Link after the description.             | Label.            |
+
+### Transformation and precedence order
+
+- No precedence rule.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Image semantics.** FR2.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                              | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Card             | Image above a body of title, description, link. | Current source and public docs | Supporting     | FR1, FR3           |
+
+`TopNavMegaMenuFeaturedCard.doc.mjs` declares no anatomy of its own, so no
+anatomy-theming map is recorded.
+
+## Family and system relationships
+
+- `family:navigation-destinations` owns the accept/block decision for each
+  destination this component renders.
+- `component:TopNavMegaMenu` renders the card in its featured area.
+- `design:bidirectionality` DR4 governs the link glyph gap.
+
+## Verification map
+
+| Contract | Verification                                         | Representative states       | Mutation or failure expectation              | Audit section                                    |
+| -------- | ---------------------------------------------------- | --------------------------- | -------------------------------------------- | ------------------------------------------------ |
+| FR1      | `TopNav.test.tsx` featured-card rest-forwarding test | Root props                  | Dropped props fail.                          | `audit:TopNavMegaMenuFeaturedCard/behavior`      |
+| FR2, FR3 | `TopNav.test.tsx` featured-card image tests          | With and without `imageAlt` | Exposed decorative image or lost link fails. | `audit:TopNavMegaMenuFeaturedCard/accessibility` |
+
+Read from source, with no focused test yet: the content order (FR1); the forwarded `ref` and the `top-nav-mega-menu-featured-card` target (FR1); that the link renders only when both `linkLabel` and `linkHref` are set (FR3); the image size (FR1), the `LinkProvider` link and trailing arrow (FR3), and FR4.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples. It links to their
+owners.

package/src/TopNav/TopNavMegaMenuItem.spec.md

@@ -0,0 +1,155 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TopNavMegaMenuItem
+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/TopNavMegaMenu.test.tsx]
+modules: []
+families: [family:navigation-destinations]
+design_specs: [design:reduced-motion]
+architecture:
+  [architecture:interaction-modality, architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# TopNavMegaMenuItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                      |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `TopNavMegaMenuItem` with `title`, `description`, `icon`, `href`, `onClick`, and `as`; target `top-nav-mega-menu-item` with a `mode` state.                                   |
+| Behavior                | One destination in a mega menu: a rich tile in the desktop panel and a row in the drawer. A drawer row closes the drawer on activation.                                       |
+| End-user impact         | Users see a title, description, and icon per destination. Keyboard users cannot reach or activate a desktop item that has `onClick` but no `href` (see Current-state impact). |
+| Builder impact          | None.                                                                                                                                                                         |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps (see Current-state impact).                                                                               |
+| Review checks           | Reject a drawer item that leaves the drawer open after activation or drops caller props and styling.                                                                          |
+| Governing rules         | `architecture:interaction-modality` INV4; WCAG 2.1.1; `component:TopNav` render modes.                                                                                        |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TopNavMegaMenuItem is one destination inside a TopNavMegaMenu. It renders itself
+for the desktop panel or the mobile drawer from the TopNav render mode. Consumer
+usage lives in `TopNavMegaMenuItem.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Desktop action items are not keyboard operable.** In the desktop panel, an
+  item with `onClick` and no `href` renders a `div` with no role and no tab
+  stop, so keyboard users cannot reach or activate it. WCAG 2.1.1 and
+  `architecture:interaction-modality` INV4 require an operable keyboard path.
+- **Color transition under reduced motion.** The desktop tile's background color
+  still animates when reduced motion is requested; `design:reduced-motion` DR3
+  allows no animated property for a fine pointer.
+
+## Ownership boundary
+
+**Owns**
+
+- The item element in both modes, its content order, and drawer close on
+  activation (FR1–FR4).
+
+**Does not own / non-goals**
+
+- Destination acceptance and blocking for every `href` this component renders —
+  owned by `family:navigation-destinations`.
+- Panel layout, grid, and the drawer group — owned by
+  `component:TopNavMegaMenu`.
+- Router link rendering — owned by `LinkProvider` and `as`.
+
+## Public concepts
+
+No component-local concept beyond the consumer props.
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                       | Basis                    |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | Outside the drawer the item is the `as` component, else the `LinkProvider` link, else `<a>` when `href` is set, and a `div` otherwise. It shows an icon box, then the title and the description, carries `top-nav-mega-menu-item`, and runs `onClick` on click. | Current source and tests |
+| FR2 | In `drawer` mode the item is a link when `href` is set and a `<button type="button">` otherwise, carries `data-mode="drawer"`, and on activation runs `onClick` and then closes the AppShell drawer.                                                            | Current source and tests |
+| FR3 | Both modes forward the `ref`, `tabIndex`, other DOM props, and event handlers, and merge `className`, `style`, and `xstyle` after component styles.                                                                                                             | Current source and tests |
+| FR4 | Both modes paint the shared focus outline on keyboard focus and use the shared press feedback.                                                                                                                                                                  | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Optional parts.** Icon and description may be absent.
+
+### Representative states
+
+| State         | Required invariant                        | Allowed variation |
+| ------------- | ----------------------------------------- | ----------------- |
+| Desktop link  | Link tile with title and description.     | Icon.             |
+| Drawer link   | Row link; activation closes the drawer.   | —                 |
+| Drawer action | Button row; activation closes the drawer. | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Link element.** `as`, then `LinkProvider`, then `<a>`.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Drawer actions are buttons.** A drawer item without `href` is a native
+  button.
+- **AR2 — Link names.** A link item's name is its title and description text.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                         | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------ | ------------------------------ | -------------- | ------------------ |
+| Tile             | Icon box, title, description.              | Current source and public docs | Supporting     | FR1                |
+| Drawer row       | Nav-row styling with optional description. | Current source                 | Supporting     | FR2                |
+
+`TopNavMegaMenuItem.doc.mjs` declares no anatomy of its own, so no
+anatomy-theming map is recorded.
+
+## Family and system relationships
+
+- `family:navigation-destinations` owns the accept/block decision for each
+  destination this component renders.
+- `component:TopNavMegaMenu` places items in its panel grid and drawer group.
+
+## Verification map
+
+| Contract | Verification                                                       | Representative states       | Mutation or failure expectation          | Audit section                            |
+| -------- | ------------------------------------------------------------------ | --------------------------- | ---------------------------------------- | ---------------------------------------- |
+| FR1, FR2 | `TopNavMegaMenu.test.tsx` TopNavMegaMenuItem and drawer-item tests | Desktop; drawer link/button | Wrong element or lost description fails. | `audit:TopNavMegaMenuItem/behavior`      |
+| FR3      | `TopNavMegaMenu.test.tsx` TopNavMegaMenuItem pass-through tests    | Both modes                  | Dropped props or styling fails.          | `audit:TopNavMegaMenuItem/behavior`      |
+| FR4      | `TopNavMegaMenu.test.tsx` drawer focus-ring test                   | Drawer item                 | Missing shared ring classes fail.        | `audit:TopNavMegaMenuItem/accessibility` |
+
+Read from source, with no focused test yet: the drawer button's `type="button"` (FR2); a desktop item's `onClick` and icon box (FR1); press feedback (FR4); the `div` for a desktop item without `href` (FR1); the desktop item's forwarded `tabIndex` (FR3); the forwarded `ref` and the `top-nav-mega-menu-item` target and its `mode` state (FR1–FR3); the `as` and `LinkProvider` precedence (FR1, ORD1); closing the drawer on activation (FR2) and the desktop focus outline (FR4).
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables or examples. It links to their
+owners.

package/src/TopNav/TopNavMenu.spec.md

@@ -0,0 +1,202 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:TopNavMenu
+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/TopNavMenu.test.tsx,
+    packages/core/src/hooks/useMenuHover.test.tsx,
+    apps/storybook/stories/TopNavMenu.stories.tsx,
+  ]
+modules: []
+families:
+  [
+    family:navigation-destinations,
+    family:overlay-dismissal,
+    family:action-groups,
+  ]
+design_specs: [design:reduced-motion]
+architecture:
+  [
+    architecture:interaction-modality,
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+  ]
+contributing: []
+system_specs: []
+---
+
+# TopNavMenu component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                     |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `TopNavMenu` with `label`, `items` (`{title, description?, icon?, href?, onClick?}`), `delay` (150), and `hideDelay` (200); target `top-nav-menu`.                                           |
+| Behavior                | In the bar, a button that opens a menu of rich items on hover or click, with APG menu keyboard support. In the drawer, a disclosure that expands its items inline. Hidden in the mobile bar. |
+| End-user impact         | Mouse users preview destinations on hover; keyboard users move through items with arrows and typeahead; drawer users expand the group in place.                                              |
+| Builder impact          | None.                                                                                                                                                                                        |
+| Compatibility/readiness | Records shipped behavior; no public change. Three current-state gaps (see Current-state impact).                                                                                             |
+| Review checks           | Reject wrapping the popup in a modal dialog, more than one tab stop among items, a collapsed drawer group that stays reachable, or caller trigger handlers that replace the built-in ones.   |
+| Governing rules         | `architecture:public-component-api` INV5 and INV7; `architecture:interaction-modality`; `component:TopNav` render modes.                                                                     |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+TopNavMenu is a TopNav entry that groups several destinations under one label.
+It owns the trigger, the hover or click menu popover in the bar, and the
+expandable group in the mobile drawer. Consumer usage lives in
+`TopNavMenu.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: open and expanded states are internal
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Drawer action items are not keyboard operable.** A drawer item with only
+  `onClick` renders a link without `href`, so keyboard users cannot reach or
+  activate it. WCAG 2.1.1 and `architecture:interaction-modality` INV4 require an
+  operable keyboard path.
+- **Motion under reduced motion.** The drawer group's height, the bar and
+  drawer chevrons' rotation, the trigger's background and text color, and each
+  bar item's background color still animate when reduced motion is requested;
+  `design:reduced-motion` DR1–DR3 allow no animated property for a fine pointer
+  and only a short opacity change for touch.
+- **The drawer trigger drops the ref.** In `drawer` mode the disclosure button
+  receives the caller's other DOM props but not `ref`.
+  `architecture:public-component-api` INV8 has the ref reach the element the
+  contract promises.
+
+## Ownership boundary
+
+**Owns**
+
+- The trigger button, the menu popover and its items, keyboard handling, and the
+  drawer group (FR1–FR10).
+
+**Does not own / non-goals**
+
+- Destination acceptance and blocking for every `href` this component renders —
+  owned by `family:navigation-destinations`.
+- Render mode and slot — owned by `component:TopNav`.
+- Popover positioning, native light dismiss, and layer hosting — owned by the
+  shared popover and layer runtime.
+- Rich panel layouts — owned by `component:TopNavMegaMenu`.
+
+## Public concepts
+
+| Concept   | Closed values or states                                    | Meaning                    | Availability by variant/orientation/state | Default | Owner                  | Stability | Invalid-value behavior               |
+| --------- | ---------------------------------------------------------- | -------------------------- | ----------------------------------------- | ------- | ---------------------- | --------- | ------------------------------------ |
+| Menu item | `title`, optional `description`, `icon`, `href`, `onClick` | One destination or action. | Bar and drawer.                           | —       | `component:TopNavMenu` | Stable    | A rejected `href` renders no `href`. |
+
+## 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 |
+| 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
+
+- **AV1 — Timing.** `delay` and `hideDelay` vary per caller.
+
+### Representative states
+
+| State            | Required invariant                                | Allowed variation |
+| ---------------- | ------------------------------------------------- | ----------------- |
+| Closed           | Trigger with collapsed state.                     | Theme styling.    |
+| Hover-open       | Menu open; focus does not move.                   | Delay.            |
+| Click-open       | Menu open; focus on the first item.               | —                 |
+| Drawer collapsed | Items inert and hidden from assistive technology. | —                 |
+| Drawer expanded  | Items reachable; activation closes the drawer.    | Animation.        |
+
+### Transformation and precedence order
+
+- **ORD1 — Trigger handlers.** Caller handler first, then the built-in handler
+  (FR6).
+
+### Performance and resources
+
+- **PR1 — Timers.** Hover timers clear on close and on unmount.
+
+## Accessibility contract
+
+- **AR1 — Menu semantics.** The popup is not a modal dialog; the trigger
+  announces a menu popup; items are `menuitem`s inside one named `menu`.
+- **AR2 — Keyboard.** FR5's keys follow the APG menu pattern.
+- **AR3 — Drawer disclosure.** The drawer trigger exposes its expanded state and
+  controls the group; collapsed items are unreachable.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                  | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Trigger          | Bar-item styling with a chevron.    | Current source and public docs | Prominent      | FR1                |
+| Menu item        | Icon box, title, description.       | Current source and public docs | Supporting     | FR4                |
+| Drawer group     | Disclosure row with indented items. | Current source                 | Supporting     | FR7                |
+
+`TopNavMenu.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` supplies the render mode and slot.
+- `architecture:public-component-api` INV5 and INV7 govern forwarding and
+  handler composition.
+- `architecture:interaction-modality` provides the shared focus indicator.
+
+## 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` |
+| 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.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+- **OQ1 — Should bar menu items render through the `LinkProvider` link, as the
+  drawer items do?** (`human-api`) Today bar items render a native `<a>` and
+  drawer items the `LinkProvider` link (FR4, FR8).
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, or popover
+mechanics. It links to their owners.

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