@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/TopNav/TopNav.spec.md

@@ -1,190 +0,0 @@
----
-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/TopNavHeading.spec.md

@@ -1,211 +0,0 @@
----
-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/TopNavItem.spec.md

@@ -1,189 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:TopNavItem
-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]
-design_specs: [design:reduced-motion]
-architecture:
-  [
-    architecture:interaction-modality,
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-  ]
-contributing: []
-system_specs: [spec:AST-085]
----
-
-# TopNavItem component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                    |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `TopNavItem` with `label`, `href`, `target`, `as`, `isSelected`, `isDisabled`, `isIconOnly`, `icon`, `children`, and `size`; target `top-nav-item` with `mode` and `selected` states.                                       |
-| Behavior                | A link in the TopNav bar or drawer. Selected marks the current page; disabled drops the destination; in the drawer, activating it closes the drawer.                                                                        |
-| End-user impact         | Users see and hear which destination is current; a disabled item cannot navigate by any input; drawer users return to the page after choosing a destination.                                                                |
-| Builder impact          | None.                                                                                                                                                                                                                       |
-| Compatibility/readiness | Records shipped behavior; no prop, default, target, or export changes. Three implementation gaps (see Current-state impact).                                                                                                |
-| Review checks           | Reject a disabled item that keeps an `href` or fires `onClick`, a selected item without `aria-current="page"`, an icon-only item without an accessible name, or a drawer item that leaves the drawer open after navigating. |
-| Governing rules         | `component:TopNav` render modes; `spec:AST-085` (disabled items); `architecture:interaction-modality` (shared focus indicator); `architecture:component-theming-surface`.                                                   |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-TopNavItem is one destination link inside TopNav. It owns the link's selected,
-disabled, and icon-only states and its rendering in the bar and in the mobile
-drawer. Consumer usage lives in `TopNavItem.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public change
-- Controlled/uncontrolled behavior: not applicable; selection is caller-owned
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Caller props can replace item state.** Other DOM props spread onto the link
-  after `aria-current`, `aria-disabled`, and `tabIndex`, so a caller value
-  replaces them; a caller `aria-disabled` can hide a disabled item's state.
-  `architecture:public-component-api` INV5 keeps component-owned accessibility
-  from being overwritten by accident.
-- **Color transition under reduced motion.** The bar link's background and text
-  color still animate when reduced motion is requested; `design:reduced-motion`
-  DR3 allows no animated property for a fine pointer.
-- **A disabled item leaves the tab order.** A disabled item is an `<a>` without
-  `href` carrying `tabIndex=-1`, so keyboard users cannot reach it or learn that
-  it is disabled. `spec:AST-085` FR1 has a disabled control keep the tab stop it has
-  when enabled.
-
-## Ownership boundary
-
-**Owns**
-
-- The link element, its selected, disabled, and icon-only states, and its
-  bar and drawer renderings (FR1–FR7).
-
-**Does not own / non-goals**
-
-- Destination acceptance and blocking for every `href` this component renders —
-  owned by `family:navigation-destinations`.
-- Which item is selected — owned by the caller.
-- The bar's slots and render mode — owned by `component:TopNav` and
-  `component:AppShell`.
-- Router link rendering — owned by `LinkProvider` and the `as` component.
-
-## Public concepts
-
-| Concept   | Closed values or states | Meaning                                         | Availability by variant/orientation/state | Default | Owner                  | Stability | Invalid-value behavior            |
-| --------- | ----------------------- | ----------------------------------------------- | ----------------------------------------- | ------- | ---------------------- | --------- | --------------------------------- |
-| Selected  | `true`, `false`         | The item is the current page.                   | All modes.                                | `false` | `component:TopNavItem` | Stable    | Not applicable.                   |
-| Disabled  | `true`, `false`         | The item cannot navigate.                       | All modes.                                | `false` | `component:TopNavItem` | Stable    | Not applicable.                   |
-| Icon only | `true`, `false`         | Hides the visible text; `label` names the link. | All modes.                                | `false` | `component:TopNavItem` | Stable    | Without `icon` the link is empty. |
-| Size      | `sm`, `md`, `lg`        | Drawer row height and padding.                  | Drawer mode only; no effect in the bar.   | `md`    | `component:TopNavItem` | Stable    | TypeScript rejects other values.  |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                            | Basis                    |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | An enabled item renders the `as` component, else the `LinkProvider` link component, else `<a>`, with `href` and `target`, the forwarded `ref`, and other DOM props. It shows `icon`, then `children` if given, else `label`.                                                                                                                         | Current source and tests |
-| FR2 | `isSelected` sets `aria-current="page"` and the selected treatment; the selected fill stays under hover and touch press with no overlay.                                                                                                                                                                                                             | Current source and tests |
-| FR3 | `isDisabled` renders a plain `<a>` with no `href` and no `target` and `aria-disabled="true"`, and suppresses clicks, so no input can navigate or fire `onClick`. A disabled item MUST keep the tab stop it has when enabled (`spec:AST-085` FR1). Implementation gap: it is an `<a>` without `href` carrying `tabIndex=-1`, so it is not a tab stop. | Current source and tests |
-| FR4 | `isIconOnly` hides the text and sets `aria-label` to `label`.                                                                                                                                                                                                                                                                                        | Current source and tests |
-| FR5 | In `default` and `mobile-bar` modes the item is a horizontal bar link with `top-nav-item`. In `drawer` mode it is a full-width row sized by `size`, carries `data-mode="drawer"`, and on activation calls `onClick` and then closes the AppShell drawer.                                                                                             | Current source and tests |
-| FR6 | Both renderings paint the shared focus outline on keyboard focus and use the shared press feedback.                                                                                                                                                                                                                                                  | Current source           |
-| FR7 | `className`, `style`, and `xstyle` merge after component styles.                                                                                                                                                                                                                                                                                     | Current source           |
-
-### Allowed variation
-
-- **AV1 — Theme styling.** Themes may restyle `top-nav-item` per mode and
-  selected state.
-
-### Representative states
-
-| State     | Required invariant                                                                | Allowed variation |
-| --------- | --------------------------------------------------------------------------------- | ----------------- |
-| Rest      | Link with label.                                                                  | Theme styling.    |
-| Selected  | `aria-current="page"`; selected fill.                                             | Fill color.       |
-| Disabled  | No `href`, no click; keeps its tab stop. Implementation gap: `tabIndex=-1` (FR3). | Muted styling.    |
-| Icon only | `aria-label` from `label`; no visible text.                                       | Icon.             |
-| Drawer    | Full-width row; activation closes the drawer.                                     | Row size.         |
-
-### Transformation and precedence order
-
-- **ORD1 — Root element.** Disabled `<a>`, then `as`, then `LinkProvider`, then
-  `<a>`.
-- **ORD2 — Content.** `children`, then `label`.
-
-### Performance and resources
-
-- No resource rule.
-
-## Accessibility contract
-
-- **AR1 — Current page.** The selected item exposes `aria-current="page"`.
-- **AR2 — Disabled.** A disabled item is exposed as disabled and keeps its tab
-  stop (`spec:AST-085` FR1, FR5); see FR3's implementation gap.
-- **AR3 — Name.** An icon-only item is named by `label`.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | --------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Link             | Label with optional leading icon. | Current source and public docs | Prominent      | FR1, FR4           |
-| Selected state   | Neutral fill and stronger text.   | Current source                 | Prominent      | FR2                |
-
-`TopNavItem.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:TopNav` supplies the render mode; `component:AppShell` supplies
-  the drawer close action.
-- `architecture:interaction-modality` provides the shared focus indicator.
-
-## Verification map
-
-| Contract         | Verification                                                  | Representative states         | Mutation or failure expectation                        | Audit section                    |
-| ---------------- | ------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------ | -------------------------------- |
-| FR1, ORD1        | `TopNav.test.tsx` TopNavItem anchor, `as`, LinkProvider tests | Default, `as`, provider       | Wrong element or lost precedence fails.                | `audit:TopNavItem/behavior`      |
-| FR2–FR4, AR1–AR3 | `TopNav.test.tsx` TopNavItem state tests                      | Selected, disabled, icon only | Missing attribute or a navigating disabled item fails. | `audit:TopNavItem/accessibility` |
-| FR5              | `TopNav.test.tsx` disabled-navigation tests in both modes     | Default and drawer            | Lost click forwarding or href handling fails.          | `audit:TopNavItem/behavior`      |
-
-Pending conformance: the TopNavItem state test and the two disabled-navigation
-tests assert `tabIndex=-1` on a disabled item, pinning FR3's implementation
-gap; they change when disabled items follow `spec:AST-085`.
-
-Read from source, with no focused test yet: the disabled plain `<a>` taking precedence over `as` and `LinkProvider` (ORD1, FR3); other DOM props reaching the link (FR1); the `top-nav-item` target and its `mode` and `selected` states (FR5); the selected fill under hover and press (FR2); the drawer row size, `data-mode="drawer"`, and closing the drawer on activation (FR5); FR6; and FR7.
-
-## 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.