@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f77aaf2

package/src/Tooltip/useTooltip.test.tsx

@@ -1,483 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file useTooltip.test.tsx
- * @input Uses vitest, @testing-library/react, useTooltip hook
- * @output Unit tests for the tooltip show/hide timers and controlled state
- * @position Testing; validates useTooltip.tsx timing contract. Component-level
- *   behavior lives in Tooltip.test.tsx — this file pins the delays, the
- *   hover-bridge constant, and timer teardown, which are invisible from there.
- *
- * SYNC: When useTooltip.tsx changes, update tests to match new behavior
- */
-
-import {
-  describe,
-  it,
-  expect,
-  vi,
-  beforeAll,
-  afterAll,
-  beforeEach,
-  afterEach,
-} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
-import {useTooltip, type TooltipOptions} from './useTooltip';
-import {useLayer} from '../Layer/useLayer';
-
-// jsdom implements neither the Popover API nor `:popover-open`; mirror
-// Tooltip.test.tsx's shims so the layer can open.
-const originalMatches = HTMLElement.prototype.matches;
-const popoverOpenState = new WeakMap<HTMLElement, boolean>();
-
-beforeAll(() => {
-  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
-    popoverOpenState.set(this, true);
-  });
-  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
-    popoverOpenState.set(this, false);
-  });
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  (HTMLElement.prototype as any).matches = function (selector: string) {
-    if (selector === ':popover-open') {
-      return popoverOpenState.get(this) ?? false;
-    }
-    return originalMatches.call(this, selector);
-  };
-});
-
-afterAll(() => {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  (HTMLElement.prototype as any).matches = originalMatches;
-});
-
-beforeEach(() => {
-  vi.useFakeTimers();
-});
-
-afterEach(() => {
-  vi.useRealTimers();
-});
-
-function Harness(options: TooltipOptions) {
-  const tooltip = useTooltip(options);
-  return (
-    <div>
-      <button
-        type="button"
-        ref={tooltip.ref}
-        aria-describedby={tooltip.describedBy}>
-        Trigger
-      </button>
-      {tooltip.renderTooltip('Helpful text')}
-    </div>
-  );
-}
-
-function trigger() {
-  return screen.getByRole('button', {name: 'Trigger'});
-}
-
-/** The popover element the trigger's aria-describedby points at. */
-function tooltipElement(): HTMLElement {
-  const id = trigger().getAttribute('aria-describedby');
-  const element = id == null ? null : document.getElementById(id);
-  expect(element).not.toBeNull();
-  return element as HTMLElement;
-}
-
-/** Advance timers inside act so the layer's state updates flush. */
-function tick(ms: number) {
-  act(() => {
-    vi.advanceTimersByTime(ms);
-  });
-}
-
-describe('useTooltip — show delay', () => {
-  it('does not show before the default 200ms delay elapses', () => {
-    const onShow = vi.fn();
-    render(<Harness onShow={onShow} />);
-
-    fireEvent.mouseEnter(trigger());
-    tick(199);
-
-    expect(onShow).not.toHaveBeenCalled();
-  });
-
-  it('shows once the default 200ms delay elapses', () => {
-    const onShow = vi.fn();
-    render(<Harness onShow={onShow} />);
-
-    fireEvent.mouseEnter(trigger());
-    tick(200);
-
-    expect(onShow).toHaveBeenCalledTimes(1);
-  });
-
-  it('honors a custom delay on both sides of the boundary', () => {
-    const onShow = vi.fn();
-    render(<Harness delay={50} onShow={onShow} />);
-
-    fireEvent.mouseEnter(trigger());
-    tick(49);
-    expect(onShow).not.toHaveBeenCalled();
-
-    tick(1);
-    expect(onShow).toHaveBeenCalledTimes(1);
-  });
-
-  it('cancels a pending show when the pointer leaves before the delay elapses', () => {
-    const onShow = vi.fn();
-    render(<Harness onShow={onShow} />);
-
-    fireEvent.mouseEnter(trigger());
-    tick(100);
-    fireEvent.mouseLeave(trigger());
-    tick(1000);
-
-    expect(onShow).not.toHaveBeenCalled();
-  });
-
-  it('does not show on hover while isEnabled is false', () => {
-    const onShow = vi.fn();
-    render(<Harness isEnabled={false} onShow={onShow} />);
-
-    fireEvent.mouseEnter(trigger());
-    tick(1000);
-
-    expect(onShow).not.toHaveBeenCalled();
-  });
-
-  it('drops a pending show when isEnabled turns false before the delay elapses', () => {
-    const onShow = vi.fn();
-    const {rerender} = render(<Harness onShow={onShow} />);
-
-    fireEvent.mouseEnter(trigger());
-    tick(100);
-    rerender(<Harness isEnabled={false} onShow={onShow} />);
-    tick(1000);
-
-    expect(onShow).not.toHaveBeenCalled();
-    expect(tooltipElement().matches(':popover-open')).toBe(false);
-  });
-});
-
-describe('useTooltip — touch suppression', () => {
-  it('never shows on the hover a finger synthesizes, but still on a mouse', () => {
-    // Touch is decided per interaction from the pointer type — a finger's
-    // arrival fires `pointerenter` ahead of the `mouseenter` a tap synthesizes
-    // — not once per device from a `(hover: none)` media query, so a hybrid
-    // device keeps hover under a mouse.
-    const onShow = vi.fn();
-    render(<Harness onShow={onShow} />);
-
-    fireEvent.pointerEnter(trigger(), {pointerType: 'touch'});
-    fireEvent.mouseEnter(trigger());
-    tick(1000);
-    expect(onShow).not.toHaveBeenCalled();
-
-    fireEvent.pointerEnter(trigger(), {pointerType: 'mouse'});
-    fireEvent.mouseEnter(trigger());
-    tick(200);
-    expect(onShow).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe('useTooltip — hide delay', () => {
-  function showTooltip(onHide: () => void, options: TooltipOptions = {}) {
-    render(<Harness delay={0} onHide={onHide} {...options} />);
-    fireEvent.mouseEnter(trigger());
-    tick(0);
-  }
-
-  it('holds the tooltip open for a 100ms hover bridge when hideDelay is 0', () => {
-    const onHide = vi.fn();
-    showTooltip(onHide, {hideDelay: 0});
-
-    fireEvent.mouseLeave(trigger());
-    tick(99);
-    expect(onHide).not.toHaveBeenCalled();
-
-    tick(1);
-    expect(onHide).toHaveBeenCalledTimes(1);
-  });
-
-  it('applies the same hover bridge when hideDelay is left unset', () => {
-    const onHide = vi.fn();
-    showTooltip(onHide);
-
-    fireEvent.mouseLeave(trigger());
-    tick(99);
-    expect(onHide).not.toHaveBeenCalled();
-
-    tick(1);
-    expect(onHide).toHaveBeenCalledTimes(1);
-  });
-
-  it('stays open when the pointer crosses onto the tooltip in one step', () => {
-    const onHide = vi.fn();
-    showTooltip(onHide);
-    const surface = tooltipElement();
-
-    // A one-step crossing dispatches in browser order: the trigger's mouseout
-    // (React derives the surface's onMouseEnter from it), then the trigger's
-    // native mouseleave, both pointing at the surface. fireEvent.mouseLeave
-    // would add a mouseout after the leave, so the leave is dispatched raw.
-    fireEvent.mouseOut(trigger(), {relatedTarget: surface});
-    act(() => {
-      trigger().dispatchEvent(
-        new MouseEvent('mouseleave', {relatedTarget: surface}),
-      );
-    });
-    tick(500);
-    expect(onHide).not.toHaveBeenCalled();
-
-    fireEvent.mouseOut(surface, {relatedTarget: document.body});
-    tick(100);
-    expect(onHide).toHaveBeenCalledTimes(1);
-  });
-
-  it('uses an explicit hideDelay instead of the hover bridge', () => {
-    const onHide = vi.fn();
-    showTooltip(onHide, {hideDelay: 500});
-
-    fireEvent.mouseLeave(trigger());
-    tick(100);
-    expect(onHide).not.toHaveBeenCalled();
-
-    tick(400);
-    expect(onHide).toHaveBeenCalledTimes(1);
-  });
-});
-
-describe('useTooltip — controlled isOpen', () => {
-  it('shows on mount when isOpen is true', () => {
-    const onShow = vi.fn();
-    render(<Harness isOpen onShow={onShow} />);
-    expect(onShow).toHaveBeenCalledTimes(1);
-  });
-
-  it('ignores pointer-leave while isOpen is true', () => {
-    const onHide = vi.fn();
-    render(<Harness isOpen onHide={onHide} />);
-
-    fireEvent.mouseLeave(trigger());
-    tick(1000);
-
-    expect(onHide).not.toHaveBeenCalled();
-  });
-
-  it('never schedules a show while isOpen is false', () => {
-    const onShow = vi.fn();
-    render(<Harness isOpen={false} onShow={onShow} />);
-
-    fireEvent.mouseEnter(trigger());
-    expect(vi.getTimerCount()).toBe(0);
-
-    tick(1000);
-    expect(onShow).not.toHaveBeenCalled();
-  });
-});
-
-describe('useTooltip — Escape dismissal', () => {
-  it('hides an uncontrolled tooltip when Escape is pressed', () => {
-    const onHide = vi.fn();
-    render(<Harness delay={0} onHide={onHide} />);
-    fireEvent.mouseEnter(trigger());
-    tick(0);
-    expect(tooltipElement().matches(':popover-open')).toBe(true);
-
-    fireEvent.keyDown(document, {key: 'Escape'});
-
-    expect(onHide).toHaveBeenCalledTimes(1);
-    expect(tooltipElement().matches(':popover-open')).toBe(false);
-  });
-
-  it('ignores an Escape that carries the IME keyCode 229', () => {
-    const onHide = vi.fn();
-    render(<Harness delay={0} onHide={onHide} />);
-    fireEvent.mouseEnter(trigger());
-    tick(0);
-
-    fireEvent.keyDown(document, {key: 'Escape', keyCode: 229});
-
-    expect(onHide).not.toHaveBeenCalled();
-  });
-
-  it('ignores keys other than Escape', () => {
-    const onHide = vi.fn();
-    render(<Harness delay={0} onHide={onHide} />);
-    fireEvent.mouseEnter(trigger());
-    tick(0);
-
-    fireEvent.keyDown(document, {key: 'Enter'});
-
-    expect(onHide).not.toHaveBeenCalled();
-  });
-
-  it('reports Escape on a controlled tooltip through onHide without hiding it', () => {
-    const onHide = vi.fn();
-    render(<Harness isOpen onHide={onHide} />);
-    expect(tooltipElement().matches(':popover-open')).toBe(true);
-
-    fireEvent.keyDown(document, {key: 'Escape'});
-
-    // `isOpen` is the consumer's value: the hook asks, the consumer decides.
-    expect(onHide).toHaveBeenCalledTimes(1);
-    expect(tooltipElement().matches(':popover-open')).toBe(true);
-  });
-});
-
-describe('useTooltip — teardown', () => {
-  it('clears a pending show timer on unmount', () => {
-    const {unmount} = render(<Harness />);
-
-    fireEvent.mouseEnter(trigger());
-    expect(vi.getTimerCount()).toBe(1);
-
-    unmount();
-
-    expect(vi.getTimerCount()).toBe(0);
-  });
-
-  it('clears a pending hide timer on unmount', () => {
-    const {unmount} = render(<Harness delay={0} />);
-    fireEvent.mouseEnter(trigger());
-    tick(0);
-
-    fireEvent.mouseLeave(trigger());
-    expect(vi.getTimerCount()).toBe(1);
-
-    unmount();
-
-    expect(vi.getTimerCount()).toBe(0);
-  });
-});
-
-describe('useTooltip — focus returning from a popover the keyboard closed', () => {
-  const shimmedShowPopover = HTMLElement.prototype.showPopover;
-  const shimmedHidePopover = HTMLElement.prototype.hidePopover;
-
-  afterEach(() => {
-    HTMLElement.prototype.showPopover = shimmedShowPopover;
-    HTMLElement.prototype.hidePopover = shimmedHidePopover;
-  });
-
-  /**
-   * The Popover API's re-entrancy rule, which the file-level shims leave out:
-   * hiding hands focus back to the previously focused element while the
-   * document still counts the popover as hiding, and `showPopover()` throws
-   * while any popover in the document is being shown or hidden.
-   */
-  function installReentrantPopoverApi() {
-    let operationsInFlight = 0;
-    const previouslyFocused = new WeakMap<HTMLElement, Element | null>();
-    const showSpy = vi.fn(function (this: HTMLElement) {
-      if (operationsInFlight > 0) {
-        throw new DOMException(
-          "Failed to execute 'showPopover' on 'HTMLElement': Invalid to show a popover during another show operation",
-          'InvalidStateError',
-        );
-      }
-      operationsInFlight += 1;
-      try {
-        previouslyFocused.set(this, this.ownerDocument.activeElement);
-        popoverOpenState.set(this, true);
-      } finally {
-        operationsInFlight -= 1;
-      }
-    });
-    HTMLElement.prototype.showPopover = showSpy;
-    HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
-      operationsInFlight += 1;
-      try {
-        popoverOpenState.set(this, false);
-        const target = previouslyFocused.get(this);
-        previouslyFocused.delete(this);
-        if (
-          target instanceof HTMLElement &&
-          this.contains(document.activeElement)
-        ) {
-          target.focus();
-        }
-      } finally {
-        operationsInFlight -= 1;
-      }
-    });
-    return showSpy;
-  }
-
-  /** A popover whose trigger also carries a tooltip. */
-  function PopoverWithTooltipTrigger({onShow}: {onShow: () => void}) {
-    const popover = useLayer({mode: 'context'});
-    const tooltip = useTooltip({onShow});
-    return (
-      <div>
-        <button
-          type="button"
-          ref={el => {
-            popover.ref(el);
-            tooltip.ref(el);
-          }}
-          aria-describedby={tooltip.describedBy}
-          onClick={popover.show}>
-          Trigger
-        </button>
-        {popover.render(
-          <button
-            type="button"
-            onKeyDown={event => {
-              if (event.key === 'Escape') {
-                popover.hide();
-              }
-            }}>
-            Inside
-          </button>,
-          {role: 'dialog'},
-        )}
-        {tooltip.renderTooltip('Helpful text')}
-      </div>
-    );
-  }
-
-  it('shows the tooltip after the hide returns instead of nesting a show inside it', async () => {
-    const showSpy = installReentrantPopoverApi();
-    const errors: unknown[] = [];
-    const onError = (event: ErrorEvent) => {
-      errors.push(event.error);
-      event.preventDefault();
-    };
-    window.addEventListener('error', onError);
-    const onShow = vi.fn();
-    render(<PopoverWithTooltipTrigger onShow={onShow} />);
-    const inside = screen.getByRole('button', {name: 'Inside', hidden: true});
-    // Keyboard focus: jsdom does not model `:focus-visible`.
-    const realMatches = trigger().matches.bind(trigger());
-    vi.spyOn(trigger(), 'matches').mockImplementation((selector: string) =>
-      selector === ':focus-visible' ? true : realMatches(selector),
-    );
-
-    // Tab to the trigger (tooltip shows), open the popover, move inside.
-    act(() => trigger().focus());
-    fireEvent.click(trigger());
-    act(() => inside.focus());
-    tick(100);
-    expect(onShow).toHaveBeenCalledTimes(1);
-    expect(tooltipElement().matches(':popover-open')).toBe(false);
-
-    // Escape closes the popover; the browser returns focus to the trigger
-    // inside that hide, and the tooltip's focus-in asks to show.
-    fireEvent.keyDown(inside, {key: 'Escape'});
-    window.removeEventListener('error', onError);
-
-    expect(errors).toEqual([]);
-    expect(document.activeElement).toBe(trigger());
-    // The press that closed the popover is not also the tooltip's to take:
-    // the show waits until the dispatch has unwound, then runs once.
-    expect(onShow).toHaveBeenCalledTimes(1);
-    await act(async () => {});
-    expect(showSpy.mock.results.every(r => r.type === 'return')).toBe(true);
-    expect(onShow).toHaveBeenCalledTimes(2);
-    expect(tooltipElement().matches(':popover-open')).toBe(true);
-  });
-});

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.