跳转至

RadioListItem component contract

Contract at a glance

Area Contract
Public contract None changes. RadioListItem takes label, aria-label, value, description, isDisabled, startContent, endContent, align, and base props, and must sit inside a RadioList.
Behavior One option row: a visually hidden native radio drawn by the radio indicator, named by the visible label, with the whole row as its click target and the radio as its only tab stop.
End-user impact People can click anywhere on an option to choose it, and keyboard users reach one control per option. An item-disabled option, or one in a group disabled without a reason, leaves the tab order; a focused disabled option shows the row outline but no indicator ring.
Builder impact None.
Compatibility/readiness Records shipped behavior; no API, default, or DOM change. Native disabled, two focus indicators, the missing indicator ring on a disabled option, and the startContent docs are listed under Current-state impact.
Review checks Reject a second tab stop on the row, a link in the label that selects the option, a description that is not linked, a theme target off the painted row, or a selection while disabled.
Governing rules component:RadioList; spec:AST-085 FR1–FR3, FR6; design:user-states DR1, DR2 (pressed overlay); architecture:interaction-modality INV1–INV3.

This table is a review projection; the body below is authoritative.

Intent

RadioListItem is one option in a RadioList. It owns the option's native radio, naming and description, row-surface click delegation, item disabled state, pressed and hover feedback on the radio, and the radio-list-item target. Consumer usage lives in RadioListItem.doc.mjs.

Compatibility and migration

  • Released default preserved: yes
  • Compatibility class: records shipped behavior; no public prop, default, export, or DOM change
  • Controlled/uncontrolled behavior: controlled by the parent RadioList's value
  • Migration decision: none

Consumer migration instructions belong in consumer docs and release notes.

Ownership boundary

Owns

  • The option's native radio, its name, description link, and form value.
  • Row-surface click delegation to the radio and onClick routing.
  • Item disabled state and the disabled, selected, and size reflection on radio-list-item.
  • The radio indicator's hover tint and pressed overlay, and its focus ring (FR7, OQ1).
  • The bare default row appearance.

Does not own / non-goals

  • The group, its value, name, size, disabled reason, and required and status semantics — owned by component:RadioList.
  • Row layout of label, description, start and end content — owned by Item.
  • The radio indicator's paint — owned by the Indicator registry's radio indicator.
  • Use outside RadioList — not supported; it throws.

Public concepts

Concept Closed values or states Meaning Availability by variant/orientation/state Default Owner Stability Invalid-value behavior
Naming label node or text; aria-label Names the radio; aria-label replaces the visible-label name. Always. label required component:RadioListItem Stable TypeScript rejects a missing label.
Value string The value the group selects and submits. Always. required component:RadioListItem Stable TypeScript rejects a missing value.
Disabled off, item, group, group with reason Blocks selection. Always. off component:RadioListItem Stable Not applicable.
Content description, startContent, endContent Supporting text and caller content around the label. Always. none caller Stable A description that renders nothing adds no link.

Behavioral and layout contract

ID Invariant Basis
FR1 RadioListItem throws when rendered outside a RadioList. Current source
FR2 The option renders an Item row whose start content is a visually hidden native <input type="radio"> (the group's name, this value, checked when the group value matches) layered over the radio indicator, followed by any startContent. Current source and tests
FR3 The radio is named by the visible label element through aria-labelledby, for text and node labels alike; aria-label replaces that name and never reaches the row. A renderable description is linked through aria-describedby; one that renders nothing adds no link. Current tests
FR4 The radio is the option's only tab stop. Clicks on the row surface (label, description, empty area) are delegated to the radio; links and buttons inside the label, description, or end content keep their own behavior. A caller onClick, typed for the row, runs on the radio for direct and delegated clicks; that routing is shipped behavior, not a requirement until OQ2 is ruled. WCAG 4.1.2; current tests
FR5 Selecting the radio calls the group's onChange(value) unless the option is disabled. Current tests
FR6 Disabled when the item or the group is disabled. A disabled radio MUST stay focusable with aria-disabled="true", be detached from the form, and refuse selection (spec:AST-085 FR1–FR3); disabled options show no hover tint or pressed overlay. Implementation gap: only a group-disabled radio with a group reason renders that shape; an item-disabled radio, and a group-disabled radio without a reason, get native disabled, which removes them from the tab order. A focusable disabled radio also still runs a caller onClick, on a click or an arrow key onto it (spec:AST-085 FR2). spec:AST-085; current source and tests
FR7 Keyboard focus on the radio paints the shared focus ring on the radio indicator, and Item's row focus-within outline on the row. One focus move MUST have one owning indicator (architecture:interaction-modality INV3); which element owns it is OQ1. Implementation gap: both paint. On a focused disabled option the indicator ring is skipped, against spec:AST-085 FR6; only the row outline shows, and whether it is enough follows OQ1. architecture:interaction-modality INV1–INV3; spec:AST-085 FR6; current source
FR8 Hovering the enabled row tints the radio indicator. RadioListItem applies design:user-states DR1 and DR2 for the pressed overlay, painting it on the indicator while the enabled row is pressed, as a circle at a 50% radius that matches the indicator's (component:Indicator FR5). The row itself paints no padding, radius, hover, or press background by default. design:user-states; current tests
FR9 The radio's hit area is at least 24 by 24 CSS pixels on coarse pointers, and its position follows the inline direction. WCAG 2.5.8; current tests
FR10 Under forced colors, the selected dot stays visible. WCAG 1.4.11; current tests
FR11 The painted row element carries astryx-radio-list-item (alongside Item's own target) and reflects data-size, data-selected when checked, and data-disabled when disabled. A theme's radio-list-item styles override the bare default row. architecture:component-theming-surface INV6; current tests
FR12 ref, className, style, xstyle, align, data-*, id, and ARIA other than aria-label reach the row. Current tests
FR13 Under a coarse pointer, the touch target grows toward 44 × 44 px, up to halfway to a neighboring target, and is never smaller than the control's own box (owner decision, 2026-11-04; spec:AST-094 FR42). It grows through an invisible band on an enabled option's row, and the row keeps its size. spec:AST-094 FR42; current source and tests

Allowed variation

  • AV1 — Content. Label, description, start and end content vary within their types.
  • AV2 — Theme paint. Themes may restore row padding, radius, hover, and selected paint through radio-list-item.

Representative states

State Required invariant Allowed variation
Unselected Radio named by label; row click selects. Content.
Selected Radio checked; data-selected; dot visible under forced colors. Theme paint.
Rich label Name from the label text; a link inside it does not select. —
Item disabled Focusable with aria-disabled; no hover or press feedback; the focus indicator shows under keyboard focus. Implementation gap: native disabled, and the indicator ring is skipped (FR6, FR7). —

Transformation and precedence order

  • ORD1 — Name. aria-label, else the visible label element.
  • ORD2 — Availability. Group disabled or item disabled; only the group reason keeps the radio focusable.

Performance and resources

  • PR1 — Bounded resources. The item owns no observer or global listener; its press feedback uses the shared press controller.

Accessibility contract

  • AR1 — Radio semantics. Each option is a native radio with a name, optional description, and checked state.
  • AR2 — One tab stop. FR4.
  • AR3 — Target size. FR9.
  • AR4 — Non-color state. FR10.

Design relationships

Anatomy or state Design requirement Representation authority Hierarchy role Component contract
Radio Indicator with hover tint, pressed overlay, focus ring. design:user-states for the pressed overlay; current source for the hover tint; FR7 for the focus ring Prominent FR2, FR7, FR8
Label Names the option. Item Prominent FR3
Description Supporting text linked to the radio. Item Supporting FR3
Row Bare, full-width click target. Current source and tests Supporting FR4, FR8, FR11

No design record beyond design:user-states governs RadioListItem.

Family and system relationships

  • component:RadioList supplies the name, value, size, and group availability.
  • design:user-states owns the pressed treatment the radio indicator paints.
  • spec:AST-085 owns disabled focusability; FR6 and FR7 record the gaps.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1 Evidence gap: no test renders RadioListItem outside a RadioList — — audit:RadioListItem/behavior
FR2–FR5, ORD1, AR1, AR2 RadioList.test.tsx selection, rich-content, and rest-forwarding cases; RadioGroup.a11y.test.tsx and RadioGroup.a11y.chromium.spec.ts Text and node labels; aria-label; description; link in label A wrong name, dangling description, or link that selects fails. Evidence gap: no test asserts a caller onClick on the radio for direct and delegated clicks. audit:RadioListItem/accessibility
FR6, ORD2 RadioList.test.tsx item-disabled and form cases; RadioGroup.a11y.test.tsx and RadioGroup.a11y.chromium.spec.ts radio-list-option-disabled, radio-list-option-group-disabled, and radio-list-option-disabled-with-message states Item and group disabled; group reason A disabled option that selects, or a submitted value from a group disabled with a reason, fails; the binding expects tabReachable: false for radio-list-option-group-disabled, which fails when that gap closes. Evidence gap: no state guards item-disabled focusability, since radio-list-option-disabled binds a radio that is not the group's Tab stop. No form case submits an item-disabled option. audit:RadioListItem/accessibility
FR7 Evidence gap: no test of focus-ring placement on the indicator, the disabled ring, or the indicator count — — audit:RadioListItem/accessibility
FR8 RadioList.test.tsx pressed-state and bare-row cases; RadioListItem.press.source-build.test.mjs Enabled, disabled, touch Press paint on a disabled option, or a default row background, fails. Evidence gap: no test asserts the hover tint. audit:RadioListItem/visual
FR9, FR10, AR3, AR4 RadioList.test.tsx coarse-pointer, RTL, and forced-colors cases Coarse pointer; RTL; forced colors Evidence gap: the forced-colors case passes on any matching rule (the checkbox mark supplies one), so it does not prove the dot; the coarse-pointer and RTL cases check only the direction-symmetric centering class, not the 24 by 24 minimum or RTL placement. audit:RadioListItem/accessibility
FR11, FR12 RadioList.test.tsx theme-target and rest-forwarding cases Sizes; selected; disabled A target off the painted row, or a missing state, fails. Evidence gap: no test asserts ref, className, style, or xstyle on the row. audit:RadioListItem/theming
FR13 touchTarget.test.tsx hit-band and minimum cases; TouchTargets.interaction.browser.spec.ts RadioList and mouse cases Enabled and disabled; both orientations; 24 and 60 px; a mouse A band on a disabled option, a band under a mouse, a row or gap that changes size, a band past half the gap, a 24 px row short of 44 px, or a 60 px row with a band fails. audit:RadioListItem/behavior
PR1 Evidence gap: no test asserts the absence of observers or global listeners — — audit:RadioListItem/behavior
RTL relation RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on RadioList / Default Indicator and label; LTR and RTL An indicator that is not at the inline start of its label fails D2. audit:RadioListItem/i18n-rtl

Current-state impact

  • Two focus indicators (FR7). Keyboard focus paints both Item's row outline and the radio indicator ring, against architecture:interaction-modality INV3.
  • Caller onClick while disabled (FR6). A focusable disabled radio still runs a caller's onClick, against spec:AST-085 FR2.
  • Disabled focusability (FR6). Item-disabled radios, and group-disabled radios without a reason, use native disabled, against spec:AST-085 FR1.
  • Disabled focus ring (FR7). The indicator ring is skipped on a focused disabled option, against spec:AST-085 FR6; only the row outline shows.
  • Consumer docs (FR2). RadioListItem.doc.mjs and the startContent prop JSDoc in RadioListItem.tsx say startContent renders before the radio circle; it renders after it.

Decision log

No component-local decision.

Open questions

  • OQ1 — Which element paints the option's focus ring, the row or the radio indicator? (human-design) architecture:interaction-modality INV3 requires one indicator; CheckboxListItem composes the same two painters.
  • OQ2 — Which element owns a caller onClick? (human-api) It is typed for the row but runs on the radio, as CheckboxListItem's matching open question records.

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