Link component contract¶
Contract at a glance¶
| Area | Contract |
|---|---|
| Public contract | None changes. Link takes href, as, label, onClick, isDisabled, isExternalLink, newTabLabel, target, rel, download, referrerPolicy, hasUnderline, isStandalone, tooltip, Text props, and children. |
| Behavior | An enabled Link with href is a link rendered by as, then LinkProvider, then a native anchor. Otherwise it is a link-styled <button>, except that an inherited link role renders the link component, and a disabled Link with href and no onClick renders a plain anchor unless an inherited button role makes it a disabled <button> (FR1). A disabled Link stays focusable and inert. |
| End-user impact | People get one link look for navigation and link-styled actions. Keyboard and screen-reader users can reach a disabled Link and hear that it is disabled. External links without label announce that they open a new tab. |
| Builder impact | A theme restyles Link's label color through the link target; a text target color no longer reaches it. |
| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A focused link with href that becomes disabled loses focus; this is listed under Current-state impact. |
| Review checks | Reject a disabled Link that navigates, runs onClick, or leaves the tab order; a _blank target without noopener noreferrer; an external link with no new-tab text; or a rejected destination that reaches a router. |
| Governing rules | family:navigation-destinations FR1–FR7; spec:AST-005; spec:AST-085 FR1, FR2, FR4, FR5; architecture:interaction-modality INV1; design:user-states DR1, DR2. |
This table is a review projection; the body below is authoritative.
Intent¶
Link is the styled navigation link. It decides whether it renders a link or a
link-styled button, keeps a disabled link reachable and inert, adds new-tab
safety and announcement for external links, and sets link typography and color.
Consumer usage lives in Link.doc.mjs.
Compatibility and migration¶
- Released default preserved:
yes;color="accent",type="body",display="inline",maxLines={0}, no underline at rest - Compatibility class: records shipped behavior; no public prop, default,
export, or DOM change; the label inherits the root's color, so a theme restyles
Link's color through the
linktarget, not thetexttarget - Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary¶
Owns
- The rendered element: link component, disabled anchor, or link-styled button.
- Disabled operability for every element form.
targetandrelsafety and the external-link icon and new-tab text.- Link typography (through Text), color, underline, hover, press, and focus paint.
- The
linktarget.
Does not own / non-goals
- Destination acceptance and custom-router handoff — owned by
family:navigation-destinationsandspec:AST-005, through the shared link boundary. - The subtree link component — owned by
component:LinkProvider. - Text typography and truncation — owned by
component:Text. - Tooltip behavior — owned by
component:Tooltip. useLinkifyanduseLinkComponent— public hooks without their own module records; uncontracted here beyond their use above.- Button-surface links — owned by
component:Buttonlink mode.
Public concepts¶
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Element form | link, disabled anchor, button | What Link renders (FR1). | Derived from href, onClick, isDisabled, and an inherited interactive role. |
link when href is set |
component:Link |
Stable | A rejected destination renders an inert anchor (family:navigation-destinations FR6). |
| External link | off, on | Opens in a new tab with an icon and new-tab text. | Link and disabled-anchor forms. | off | component:Link |
Stable | Not applicable. |
| Color | primary, secondary, accent, disabled, placeholder, inherit, plus augmented Text colors |
Link text color. | Every form. | accent |
component:Link |
Stable | An augmented color colors the Text only; the root paints no color for it. |
| Underline | on hover, always | When the underline shows. | Hover underline on enabled forms; hasUnderline underlines at rest in every form, disabled included. |
on hover | component:Link |
Stable | Not applicable. |
| Standalone | off, on | Body font size outside running text. | Every form. | off | component:Link |
Stable | Not applicable. |
Behavioral and layout contract¶
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Element form, in order: (a) href set and enabled → the link component from as, then LinkProvider, then a native anchor, with href, target, rel, and onClick. (b) Otherwise, onClick set → <button type="button">. (c) Otherwise an inherited interactive role decides: button → <button type="button">, link → the link component, or the disabled anchor of (d) when disabled. (d) Otherwise, href set and disabled → a plain <a role="link"> with no href; otherwise <button type="button">. |
family:navigation-destinations FR1, FR2; current source and tests |
| FR2 | isExternalLink sets target="_blank". Whenever target is _blank, rel contains noopener and noreferrer in addition to every caller token. download and referrerPolicy reach the element. |
family:navigation-destinations FR5, AV4; current tests |
| FR3 | An external Link that is not rendered as a button shows a trailing extra-small external-link icon that inherits the root's color, followed by visually hidden new-tab text: newTabLabel, else the localized default. |
Current source and tests |
| FR4 | A destination reaches the link component only through the shared navigation rule; a rejected destination renders an inert anchor and never invokes a router. | family:navigation-destinations FR1–FR6; spec:AST-005 |
| FR5 | A disabled Link stays focusable with aria-disabled="true", never navigates, and never runs onClick. The disabled anchor form omits href, target, and rel, takes a Tab stop, and skips the custom link component. In every form, clicks are cancelled and stopped, Enter and Space are suppressed, other keys reach the caller's onKeyDown, and the Link paints at half opacity with no pointer events and no press paint. A focused Link that becomes disabled MUST keep focus and expose the change on that element (spec:AST-085 FR4, FR5), and a caller aria-disabled or role MUST NOT replace the disabled exposure (architecture:public-component-api INV5); a caller tabIndex keeps the enabled focus order (spec:AST-085 FR1). FR5 gap: a focused Link with href that becomes disabled is replaced by another element, so focus falls to the page (spec:AST-085 FR4). |
spec:AST-085 FR1, FR2, FR4, FR5; family:navigation-destinations FR7; current tests |
| FR6 | Children render inside Text with type (default body), size, weight, color (default accent; for a color the root paints, FR7, the label inherits it), display (default inline), and maxLines (default 0). The root inherits font family, size, weight, line height, and text alignment and lays content out with a small gap; it stops at its container and its label may shrink, so a label with no break opportunity, such as a bare URL, wraps inside the line (component:Text FR3), and with maxLines above 0 its Text truncates inside a constrained line; isStandalone sets the body size and leading on the root. A Link inside a Text with maxLines MUST truncate with that text: there its root lays out inline, in the text's lines, unless the Link sets its own display or maxLines or renders as a button, and keeps its visible focus ring (an inset ring, architecture:interaction-modality INV1). A Link whose content is block-level is not supported inside a clamped Text, because it breaks the clamp. Link reads the enclosing Text's clamp, never its children (AV1). |
Current source and tests |
| FR7 | The root paints the chosen color for the six built-in colors, which the underline and the external icon take. The label inherits the root's color at rest and on hover; a theme styles Link's color through the link target. On hover-capable pointers an enabled Link underlines on hover, and for primary, secondary, and accent the root color mixes in the hover tint, so the label, the underline, and the icon keep one color. hasUnderline underlines at rest. |
Current source and tests |
| FR8 | Press feedback follows design:user-states DR1 and DR2 for Link's text surface: an enabled link or button form paints the pressed overlay, and a disabled Link does not. |
design:user-states DR1, DR2; current tests |
| FR9 | label, when non-empty, becomes aria-label and replaces the content as the accessible name; a caller aria-label overrides it; otherwise the content is the name. |
Current tests |
| FR10 | With tooltip, Link renders inside a Tooltip that opens above it. |
Current source and tests |
| FR11 | The root carries astryx-link and reflects data-color. ref, className, style, xstyle, and other DOM props reach the root. |
architecture:component-theming-surface; current tests; architecture:public-component-api INV5 |
Allowed variation¶
- AV1 — Content.
childrenmay be text or caller content such as an icon; Link does not inspect it. - AV2 — Router. Any link component accepted by the shared boundary may render the link form.
Representative states¶
| State | Required invariant | Allowed variation |
|---|---|---|
| Native link | Anchor with href; accent color; underline on hover. |
Color, underline. |
| Router link | Link component from as or LinkProvider receives the accepted destination. |
Router. |
| External link | _blank, noopener noreferrer, icon, and new-tab text. |
newTabLabel. |
| Button form | <button type="button"> styled as a link; runs onClick. |
— |
| Disabled link | <a role="link" aria-disabled="true" tabindex="0"> with no href; inert. |
— |
| Disabled button form | aria-disabled button; focusable; inert. |
— |
Transformation and precedence order¶
- ORD1 — Element form. FR1's order (a) → (d).
- ORD2 — Link component.
as, thenLinkProvider, then a native anchor; the disabled anchor form always uses a native anchor. - ORD3 — Target and rel.
isExternalLinkoverridestarget; a_blanktarget then adds the two safety tokens torel.
Performance and resources¶
- PR1 — No per-link listeners. Link adds no global listener, observer, or measurement; press feedback uses the shared document controller.
Accessibility contract¶
- AR1 — Role. The link form exposes the link role; the disabled anchor
form sets
role="link"explicitly; the button form exposes the button role. - AR2 — Disabled. A disabled Link keeps its Tab stop and exposes
aria-disabled="true"on the focusable element (FR5); a callertabIndexkeeps the enabled focus order (spec:AST-085FR1). - AR3 — New tab. An external link without
labelannounces that it opens in a new tab through visually hidden text; the icon adds no name (FR3). Withlabel, the label becomes the whole accessible name (FR9), so the new-tab text is not announced unless the caller's label says it. - AR4 — Name. FR9. A
labelon a text link overrides its visible text. - AR5 — Focus indicator. Keyboard focus paints the shared focus outline;
visibility follows
architecture:interaction-modalityINV1.
Design relationships¶
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Label | Takes the root's color; underline on hover or always. | Current source and tests | Prominent | FR6, FR7 |
| External icon | Extra-small trailing icon that inherits the root's color. | Current source and tests | Supporting | FR3 |
| Disabled | Half opacity; no hover, press, or pointer interaction. | Current source and tests | Supporting | FR5 |
design:user-states governs Link's pressed overlay (FR8); no other design record
governs Link. The root carries the link target, which paints the label, the underline, and
the external icon; the label is a Text that inherits the root's color
(architecture:component-theming-surface INV5). The consumer anatomy names no root part, so this record
carries no anatomy-theming map.
Family and system relationships¶
family:navigation-destinationsandspec:AST-005own destination handling (FR4); Link is a member and keeps its own disabled semantics (FR7 of the family).spec:AST-085owns disabled focusability; Link meets FR1, FR2, and FR5's steady-state exposure in every form, but not FR4 or FR5's transition clause for a focused link withhref(FR5 gap).component:LinkProvidersupplies the subtree link component (ORD2).
Verification map¶
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | Link.test.tsx element-form, as, provider, and inherited-role cases; Link.a11y.chromium.spec.ts |
Native, router, button form, disabled, inherited role | A wrong element form or role fails, including under an inherited interactive role (FR1 (c)). | audit:Link/anatomy |
| FR2, FR3, AR3 | Link.test.tsx external, target, rel, referrerPolicy, labelled-name, and new-tab cases; Link.a11y.chromium.spec.ts external state; Link.hoverColor.a11y.chromium.spec.ts and LinkAudit.a11y.chromium.spec.ts (the external icon takes the root's color) |
External; explicit _blank; custom label |
A missing safety token, icon, new-tab text, or referrerPolicy fails, as does an external link with label whose name is not the label alone. An external icon whose color differs from the root's fails. Evidence gap: no test asserts the external icon's size. |
audit:Link/accessibility |
| FR4 | Link.navigation.a11y.chromium.spec.ts |
Rejected and ordinary schemes; native, router, downloads | A rejected destination that navigates or reaches a router fails. | audit:Link/behavior |
| FR5, AR2 | Link.test.tsx disabled and disabled-exposure cases; LinkAudit.a11y.chromium.spec.ts disabled stories (half opacity, no pointer events, no hover paint) |
Disabled anchor; disabled button form; with onClick; caller aria-disabled and role |
Navigation, a consumer onClick, a lost Tab stop, a custom component on a disabled link, a caller aria-disabled or role that replaces the disabled exposure on the anchor or button form, another key that does not reach the caller's onKeyDown, or a disabled Link that is not half opacity or takes pointer events fails. Evidence gap: no test disables a focused link or passes a caller tabIndex. |
audit:Link/accessibility |
| FR6 (type) | Link.test.tsx text-type and clamp-display cases; Link.wrappedLines.a11y.chromium.spec.ts (wrapped text alignment); Link.longLabel.a11y.chromium.spec.ts (a bare URL label in a 200 px column wraps and stays inside it, as an anchor, a button and an external link); Link.ancestor-clamp.a11y.chromium.spec.ts (a default Link inside <Text maxLines={2}> is inline and the clamp cuts through it; a Link inside a one- and a two-line clamp shows the top and bottom edges of its inset focus ring; a composed Link outside a clamp keeps its box and focus outline) |
Default body; type="inherit"; wrapped button and anchor forms in a start-aligned, right-to-left and centred line |
A dropped Text type fails. Link.truncation.a11y.chromium.spec.ts: an anchor and a button Link with maxLines={1} in a fixed-width line stop at the line and draw an ellipsis. Evidence gap: no test asserts that size, weight, color, or display reach Text, or the isStandalone root size. A button form whose wrapped lines line up differently from the anchor form fails. |
audit:Link/visual |
| FR6, FR7 (paint) | Link.hoverColor.a11y.chromium.spec.ts (the hovered label, root, and icon share one computed color; the resting color returns); LinkAudit.a11y.chromium.spec.ts (the accent, primary, secondary, and inherit colors' roots paint their tokens at rest, and the label takes the accent, primary, and secondary colors; hasUnderline underlines at rest, and a Link without it underlines only on hover); evidence gap: the standalone case asserts only that a link renders; evidence gap: no test renders the disabled or placeholder color; evidence gap: no test asserts that the label takes the inherit color |
Each color; hasUnderline; isStandalone |
A label color that differs from the root, or a missing or extra underline, fails. | audit:Link/visual |
| FR8 | Link.test.tsx pressed-state suite |
Link, button form, disabled | No press paint, or press paint on a disabled Link, fails. | audit:Link/behavior |
| FR9, FR11, AR4 | Link.test.tsx label, aria-label, ref, theme-class, and caller className and style cases |
With and without label; data-color |
A missing or extra aria-label, target, data-color, or ref fails. The accessibility suites assert a passed data-* attribute and aria-current on the root, and the navigation suite asserts download. Evidence gap: no test passes xstyle. |
audit:Link/theming |
| FR10 | Link.test.tsx tooltip case (the tooltip text describes the link); evidence gap: no test asserts that the tooltip opens above the link |
Tooltip | A tooltip text that does not describe the link fails. | audit:Link/accessibility |
| ORD1–ORD3 | Covered by the FR1–FR3 rows | — | — | audit:Link/behavior |
| PR1, AR5 | LinkAudit.a11y.chromium.spec.ts focus cases (keyboard focus paints an outline on the Link); evidence gap: no test asserts the absence of per-link listeners |
Default, disabled, and disabled button form under keyboard focus | A keyboard-focused Link with no outline fails. | audit:Link/accessibility |
Current-state impact¶
- Becoming disabled (FR5). A focused link with
hrefthat becomes disabled is replaced by the plain disabled anchor, or by a<button>when it hasonClick, so keyboard focus falls to the page and the change is not exposed on the focused element, againstspec:AST-085FR4 and FR5. - Consumer docs.
Link.doc.mjsanatomy lists Left icon and Right icon parts; Link renders no icon slots, only caller content and the external icon (FR3).
Decision log¶
No component-local decision. Link applies family:navigation-destinations and
spec:AST-085.
Open questions¶
None.
Content boundary¶
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx