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, except a modified click on a link, which leaves it open. |
| 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. Two 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 an unmodified activation. |
| 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, andtabIndex, so a caller value replaces them; a calleraria-disabledcan hide a disabled item's state.architecture:public-component-apiINV5 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-motionDR3 allows no animated property for a fine pointer.
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
hrefthis component renders — owned byfamily:navigation-destinations. - Which item is selected — owned by the caller.
- The bar's slots and render mode — owned by
component:TopNavandcomponent:AppShell. - Router link rendering — owned by
LinkProviderand theascomponent.
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. With onClick and no href, an enabled item is a button to assistive technology and the keyboard: it carries role="button", has no href, is in the Tab order, and activates on Enter and on Space released (Space does not scroll the page), keeping its HTMLAnchorElement type. |
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 sets aria-disabled="true" and suppresses clicks, so no input can navigate or fire onClick. A disabled link renders a plain <a> with no href and no target. A disabled onClick-only item keeps its host, role="button", and tab stop. A disabled item MUST keep the tab stop it has when enabled (spec:AST-085 FR1). |
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, 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 |
| 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-itemper 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. |
Muted styling. |
| Icon only | aria-label from label; no visible text. |
Icon. |
| Drawer | Full-width row; activation closes the drawer, except a modified click on a link, which leaves it open. | Row size. |
Transformation and precedence order¶
- ORD1 — Root element. For a disabled link, a plain
<a>; otherwiseas, thenLinkProvider, then<a>. - ORD2 — Content.
children, thenlabel.
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-085FR1, FR5). - 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-destinationsowns the accept/block decision for each destination this component renders.component:TopNavsupplies the render mode;component:AppShellsupplies the drawer close action.architecture:interaction-modalityprovides 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, and onClick-only keyboard button 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 |
| RTL relation (FR1) | RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on TopNav / Full example |
The Dashboard item's leading icon; LTR and RTL |
A leading icon that is not at the inline start of its item fails D2. | audit:TopNavItem/i18n-rtl |
Read from source, with no focused test yet: the disabled link's 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.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx