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, except a modified click on a link, which leaves it open. |
| End-user impact | Users see a title, description, and icon per destination. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior; no public change. One implementation gap (see Current-state impact). |
| Review checks | Reject a drawer item that leaves the drawer open after an unmodified 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¶
- Color transition under reduced motion. The desktop tile's background color
still animates when reduced motion is requested;
design:reduced-motionDR3 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
hrefthis component renders — owned byfamily:navigation-destinations. - Panel layout, grid, and the drawer group — owned by
component:TopNavMegaMenu. - Router link rendering — owned by
LinkProviderandas.
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, a <button type="button"> when it has onClick and no href, 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, except that a Ctrl-, Cmd-, Shift- or Alt-click on a link runs onClick and leaves it open for the next one, unless onClick cancels the click. |
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, except a modified click on a link, which leaves it open. | — |
| Drawer action | Button row; activation closes the drawer. | — |
Transformation and precedence order¶
- ORD1 — Link element.
as, thenLinkProvider, then<a>.
Performance and resources¶
- No resource rule.
Accessibility contract¶
- AR1 — Drawer actions are buttons. A drawer item without
hrefis 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-destinationsowns the accept/block decision for each destination this component renders.component:TopNavMegaMenuplaces 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 (including the desktop onClick-only native button) and drawer-item tests |
Desktop link, button, and placeholder; 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 |
| RTL relation | RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on TopNavMenu / Mega menu (panel opened) |
Item icon and text; LTR and RTL | An icon that is not at the inline start of its text fails D2. | audit:TopNavMegaMenuItem/i18n-rtl |
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.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx