Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

[Component Audit] CheckboxListItem: document when standalone checked state applies (#6778)

Cindy Zhang0550afdf4b18
diff --git a/.changeset/checkbox-list-item-standalone-docs.md b/.changeset/checkbox-list-item-standalone-docs.md
new file mode 100644
index 0000000000..5f828a9511
--- /dev/null
+++ b/.changeset/checkbox-list-item-standalone-docs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] Clarify that CheckboxListItem reads `isChecked` and `onCheck` inside a CheckboxList without `value` (such as a select-all item), and requires `value` only when the parent CheckboxList has a `value` array.
+
+@cixzhang
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index bf90975392..603711a0a0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1132,15 +1132,16 @@ jobs:
retention-days: 30
if-no-files-found: error
- # CheckboxList's component audit grades interactive row paint, focus,
- # busy, disabled, read-only, status, narrow, forced-colors, and RTL states
- # from exact-head Chromium receipts. The shared checkbox contract also runs
- # for its CheckboxListItem bindings, with its own output directory so it
- # cannot clear the receipts. Each lane runs even when another fails, and
- # the step still runs after an earlier audit step fails, so a
- # failing-before head banks complete evidence.
+ # The CheckboxList and CheckboxListItem component audits grade the same
+ # option rows: interactive row paint, focus, busy, disabled, read-only,
+ # status, narrow, forced-colors, and RTL states from exact-head Chromium
+ # receipts. The shared checkbox contract also runs for its
+ # CheckboxListItem bindings, with its own output directory so it cannot
+ # clear the receipts. Each lane runs even when another fails, and the
+ # step still runs after an earlier audit step fails, so a failing-before
+ # head banks complete evidence.
- name: Run CheckboxList audit browser evidence
- if: ${{ !cancelled() && github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, '[Component Audit] CheckboxList:') }}
+ if: ${{ !cancelled() && github.event_name == 'pull_request' && (startsWith(github.event.pull_request.title, '[Component Audit] CheckboxList:') || startsWith(github.event.pull_request.title, '[Component Audit] CheckboxListItem:')) }}
env:
ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
PLAYWRIGHT_JSON_OUTPUT_NAME: checkbox-list-pattern-results.json
@@ -1149,7 +1150,7 @@ jobs:
node .github/scripts/accessibility-audit.js \
--storybook-dir apps/storybook/dist \
--output checkbox-list-a11y-report.json \
- --components CheckboxList \
+ --components CheckboxList,CheckboxListItem \
--baseline .github/a11y-baseline.json \
--fail-on-new || status=1
pnpm exec playwright test \
@@ -1164,7 +1165,7 @@ jobs:
exit "$status"
- name: Upload CheckboxList audit evidence
- if: always() && github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, '[Component Audit] CheckboxList:')
+ if: always() && github.event_name == 'pull_request' && (startsWith(github.event.pull_request.title, '[Component Audit] CheckboxList:') || startsWith(github.event.pull_request.title, '[Component Audit] CheckboxListItem:'))
uses: actions/upload-artifact@v7
with:
name: checkbox-list-audit-evidence-${{ needs.build-storybook.outputs.short_hash }}
diff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.json
index 66890e4bd8..b6beb3d608 100644
--- a/apps/storybook/rtl-audit/targets.json
+++ b/apps/storybook/rtl-audit/targets.json
@@ -67,6 +67,15 @@
"next": "[data-testid=\"checkbox-end-content\"]"
}
},
+ {
+ "component": "CheckboxListItem",
+ "storyId": "core-checkboxlist--rich-descriptions",
+ "dims": ["D2"],
+ "selectors": {
+ "prev": ".astryx-checkbox-input",
+ "next": "[data-testid=\"checkbox-end-content\"]"
+ }
+ },
{
"component": "PowerSearch",
"storyId": "core-powersearch--with-date-filters",
diff --git a/packages/core/src/CheckboxList/CheckboxList.spec.md b/packages/core/src/CheckboxList/CheckboxList.spec.md
index 47f06cfded..0920595da9 100644
--- a/packages/core/src/CheckboxList/CheckboxList.spec.md
+++ b/packages/core/src/CheckboxList/CheckboxList.spec.md
@@ -39,15 +39,15 @@ system_specs: [spec:AST-011, spec:AST-021, spec:AST-038]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | `CheckboxList` is a labeled `role="group"` of `CheckboxListItem` rows. A `value` array selects controlled collection mode (`onChange`, `changeAction`); without it, items use standalone `isChecked`/`onCheck`. The group owns disabled, disabled-reason, read-only, and status. |
-| Behavior | Each option is one native checkbox and one tab stop; the row surface delegates clicks to it. A toggled item stays busy and cannot be re-toggled while its `changeAction` is pending, while other items stay interactive. |
-| End-user impact | People can identify the group, operate every option by pointer, touch, and keyboard, learn why a group is unavailable, and see which options are still saving. |
-| Builder impact | Builders choose collection or standalone mode and supply stable item `value`s in collection mode. Handlerless, invalid-status, pass-through-target, checked-row theming and feedback, and focus-ring ownership remain owner decisions. |
-| Compatibility/readiness | Released API, defaults, DOM ownership, and targets are unchanged. This draft records shipped behavior plus two objective remediations: concurrent pending items keep their busy state, and a read-only item's `onClick` fires once per click instead of looping. |
-| Review checks | Reject a second tab stop per option, a pending item that loses busy or its re-toggle guard, an item `onClick` that fires more than once per click, dropped group naming or description ids, disabled or read-only mutation, or new target/state API introduced without an owner decision. |
-| Governing rules | `architecture:public-component-api/INV1–INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:interaction-modality/INV1–INV4`; `architecture:component-test-sufficiency/INV1–INV7`; `spec:AST-021/FR8–FR10`; `spec:AST-038/FR7`; WCAG 2.2 1.3.1, 2.1.1, 4.1.2. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `CheckboxList` is a labeled `role="group"` of `CheckboxListItem` rows. A `value` array selects controlled collection mode (`onChange`, `changeAction`); without it, its items are standalone. The group owns naming, description, disabled, disabled-reason, read-only, pending values, and status. Each option's behavior is `component:CheckboxListItem`. |
+| Behavior | The group names and describes its options, tracks every value whose `changeAction` is pending so each saving option stays busy while the others stay interactive, and applies disabled, read-only, and status to every option. |
+| End-user impact | People can identify the group, operate every option by pointer, touch, and keyboard, learn why a group is unavailable, and see which options are still saving. |
+| Builder impact | Builders choose collection mode by passing `value`, and then supply stable item `value`s. Invalid-status and group pass-through-target meaning remain owner decisions here; per-option owner decisions are recorded in `component:CheckboxListItem`. |
+| Compatibility/readiness | Released API, defaults, DOM ownership, and targets are unchanged. This draft records shipped behavior, including the concurrent-pending fix from the CheckboxList audit (#6777). |
+| Review checks | Reject a pending value that loses its busy state or re-toggle guard when another option is toggled, dropped group naming or description ids, a toggle while the group is disabled or read-only, or new target or state API introduced without an owner decision. Per-option checks are in `component:CheckboxListItem`. |
+| Governing rules | `architecture:public-component-api/INV1–INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:interaction-modality/INV1–INV5`; `architecture:component-test-sufficiency/INV1–INV7`; `architecture:knowledge-contracts/INV2`; `spec:AST-021/FR8–FR10`; `spec:AST-038/FR7`; WCAG 2.2 1.3.1, 2.1.1, 4.1.2. |
This table is a review projection; the body below becomes authoritative only after owner approval.
@@ -60,10 +60,12 @@ touch, keyboard, and assistive technology.
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: observational record plus two objective bug fixes; public
- types, defaults, DOM ownership, targets, and focus order are unchanged
+- Compatibility class: observational record, including the CheckboxList audit's
+ concurrent-pending fix; public types, defaults, DOM ownership, targets, and
+ focus order are unchanged
- Controlled/uncontrolled behavior: collection mode is controlled by `value`;
- standalone items are controlled by `isChecked`; no uncontrolled mode exists
+ standalone items follow `component:CheckboxListItem`; no uncontrolled mode
+ exists
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
@@ -76,17 +78,17 @@ Consumer migration instructions belong in consumer docs and release notes.
description, status, and disabled-reason relationships.
- Collection state shared with CheckboxListItem: checked membership, change
ordering, optimistic pending values, and group-level availability.
-- CheckboxListItem's option composition: one CheckboxInput per row, row-surface
- click delegation, naming and description relationships, and the checked-row
- fill.
+- The composed option anatomy and its target dispositions (Theming anatomy
+ below).
**Does not own / non-goals**
+- Each option's behavior — its checkbox, naming and description, standalone
+ mode, row-surface delegation and `onClick` routing, item disabled and loading
+ states, density sizing, and checked-row fill — owned by
+ `component:CheckboxListItem`.
- List and option-row presentation — owned by `component:List`; its
`list-item` target reaches only the row root.
-- Standard option-label and option-description wrappers — rendered as separate,
- untargeted spans by Item rather than Text; rich label content and end content
- remain caller-owned.
- The checkbox control, its indicator, focus ring, and pressed overlay — owned
by `component:CheckboxInput` and `component:CheckboxIndicator`.
- Group-label and validation-message presentation — owned by `component:Field`
@@ -97,80 +99,76 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| -------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------- | ---------------------- | -------------------------------------- | --------------------------------------------- |
-| group naming | `label`, `isLabelHidden`, `description` | Names and describes the `role="group"`; a hidden label still names it. | All states. | label required; visible | caller and Field | stable | rejected by the public type |
-| selection mode | collection (`value` set), standalone in group, standalone in List | Collection derives checked state from membership; standalone items read `isChecked`. | Standalone item props are ignored in collection mode. | standalone | component | stable | a collection item without `value` throws |
-| change path | `onChange`, `changeAction` (collection); `onCheck` (standalone); none | Reports the next value array or boolean; `changeAction` runs after `onChange` in a transition. | Enabled, non-read-only, non-busy items. | none | caller and component | shipped; handlerless meaning unsettled | no handler means no component-owned mutation |
-| checked state | unchecked, checked, mixed (standalone only) | Native checkbox state; mixed uses the native `indeterminate` property. | All states. | unchecked | caller | stable | rejected by the public type |
-| availability | enabled, group disabled, group disabled with reason, item disabled | Blocks toggling; a reason keeps checkboxes focusable through `aria-disabled` and shows a group tooltip. | Reason applies only with group `isDisabled`. | enabled | component | stable | a reason without `isDisabled` renders nothing |
-| read-only | group `isReadOnly` | Keeps values visible, focusable, and full-opacity while blocking toggling. | Group-wide; not available on a standalone List item. | false | component | stable | boolean only |
-| busy | item `isLoading`; pending collection `changeAction` | Shows Spinner in the checkbox, marks the row and checkbox busy, and blocks re-toggling that item. | Per item; other items remain interactive. | idle | component | stable | boolean/transition state only |
-| status | `warning`, `error`, `success`, optional message | A message renders a detached FieldStatus after the list and describes the group. | All states. | none | caller and FieldStatus | shipped; invalid semantics unsettled | a status without a message renders nothing |
-| row layout | `density` compact/balanced/spacious; `hasDividers`; `width` | Row padding and checkbox size (`sm` for compact); dividers between rows; field width for label, list, and status. | All states. | balanced; none; intrinsic | component and List | stable | rejected by the public types |
-| option content | string or node `label`, `aria-label`, `description`, `endContent` | Names and describes the checkbox; end content stays caller-owned. | All states. | label required | caller | stable | typed values only |
-| pass-through | CheckboxList rest, `ref`, styling; CheckboxListItem rest, `ref`, styling, `onClick` | CheckboxList inputs reach the field root; item inputs reach the row; item `onClick` rides the checkbox. | All states. | none | component | shipped; ARIA target unsettled | component-owned attributes win |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------- | ---------------------- | -------------------------------------- | ------------------------------------------------------------ |
+| group naming | `label`, `isLabelHidden`, `description` | Names and describes the `role="group"`; a hidden label still names it. | All states. | label required; visible | caller and Field | stable | rejected by the public type |
+| collection value | `value` array present or absent | Present: the group owns checked membership and change handling for its items. Absent: its items are standalone. | All states. | absent | caller and component | stable | an item without `value` in collection mode throws (item FR4) |
+| change path | `onChange`, `changeAction`, both, neither | Reports the next value array; `changeAction` runs after `onChange` in a transition with an optimistic value. | Collection mode. | neither | caller and component | shipped; handlerless meaning unsettled | no handler means no component-owned mutation |
+| availability | enabled, `isDisabled`, `isDisabled` with `disabledMessage` | Blocks toggling on every item; a reason keeps the items focusable through `aria-disabled` and shows a group tooltip. | Reason applies only with `isDisabled`. | enabled | component | stable | a reason without `isDisabled` renders nothing |
+| read-only | `isReadOnly` | Makes every item read-only. | Group-wide. | false | component | stable | boolean only |
+| pending values | the values whose `changeAction` is pending | Each pending value's item renders busy; toggling another item does not clear it; concurrent values settle together. | Collection mode with `changeAction`. | none | component | stable | transition state only |
+| status | `warning`, `error`, `success`, optional message | A message renders a detached FieldStatus after the list and describes the group. | All states. | none | caller and FieldStatus | shipped; invalid semantics unsettled | a status without a message renders nothing |
+| row layout | `density` compact/balanced/spacious; `hasDividers`; `width` | Density reaches the List and its rows; dividers separate rows; width sizes the label, list, and status together. | All states. | balanced; none; intrinsic | component and List | stable | rejected by the public types |
+| pass-through | CheckboxList rest, `ref`, `className`, `style`, `xstyle` | Reach the field root. | All states. | none | component | shipped; ARIA target unsettled | component-owned attributes win |
+
+Item props (`label`, `aria-label`, `description`, `endContent`, `isChecked`,
+`onCheck`, item `isDisabled`, `isLoading`, and item pass-through) are concepts
+of `component:CheckboxListItem`.
## Behavioral and layout contract
Draft requirements identify their basis so observed code is not mistaken for an
intentional decision. A `current` contract contains no unresolved rows.
-| ID | Candidate invariant | Basis | Draft review state |
-| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| FR1 | The render MUST place CheckboxListItem children inside a List within a `role="group"` named by the group label through `aria-labelledby`; its `aria-describedby` MUST list the description, status message, and disabled-reason tooltip that are present, in that order. | shipped source; focused tests; WCAG 1.3.1 and 4.1.2 | verify |
-| FR2 | The CheckboxList root MUST carry the current `checkbox-list` target. | shipped source and public docs | settled |
-| FR3 | The option-row root and checkbox MUST continue to be rendered by List and CheckboxInput rather than reimplemented. | shipped source | settled |
-| FR4 | A busy item MUST render Spinner inside that item's checkbox and mark both the row and the checkbox busy; a status message MUST render through a detached FieldStatus after the list. | shipped source, focused tests, and Chromium receipts | verify |
-| FR5 | Item MUST render the option label and description as separate untargeted children; end content MUST remain caller-provided inside its own untargeted slot wrapper. | shipped source and focused tests | settled |
-| FR6 | In collection mode, items MUST derive checked state from `value` membership; toggling MUST call `onChange` with the next array (appending or filtering the item's `value`) and then run `changeAction` with the same array in a transition with an optimistic value. | shipped source and focused tests | verify |
-| FR7 | While an item's `changeAction` is pending, that item MUST show Spinner, expose busy state, and refuse re-toggling; toggling another item MUST NOT clear it. Concurrent pending items settle together, after which every busy state clears. | shipped public `changeAction` promise; focused regression test; Chromium receipts | verify (remediated by this audit) |
-| FR8 | Without a `value` array, or inside a plain List, items MUST read `isChecked` and call `onCheck` with the next boolean; a mixed item proposes `true`. | shipped source and focused tests | verify |
-| FR9 | Group `isDisabled` MUST natively disable every checkbox unless `disabledMessage` is set; with a reason, checkboxes MUST stay focusable through `aria-disabled`, show the reason tooltip on group hover and focus, and refuse toggling. Item `isDisabled` MUST natively disable that item. | shipped source, focused tests, and shared checkbox binding | verify |
-| FR10 | Group `isReadOnly` MUST expose read-only state on every checkbox, keep it focusable and full-opacity, and refuse every toggle, whether it comes from the checkbox, the keyboard, or the row. Row-surface clicks still delegate to the checkbox when the item has an `onClick`, which fires once per click; without one, the row does not delegate. | shipped source; focused read-only test; shared checkbox binding; `spec:AST-011` read-only vocabulary | verify (row-click loop remediated by this audit) |
-| FR11 | Each option MUST expose exactly one tab stop, its checkbox. A click on the row surface outside interactive descendants MUST toggle through that checkbox, and an item `onClick` MUST fire once for each direct, keyboard, or delegated click. | shipped source and focused tests; WCAG 2.1.1 and 4.1.2 | verify |
-| FR12 | A string `label` MUST name the checkbox; a node `label` MUST name it from its visible text through `aria-labelledby`; `aria-label` MUST replace the derived name; a renderable `description` MUST describe the checkbox. | shipped source and focused tests | verify |
-| FR13 | `compact` density MUST render the `sm` checkbox and other densities `md`; `hasDividers` MUST separate rows without a divider after the last row; `width` MUST size the label, list, and status together. | shipped source, docs, and Chromium receipts | verify |
-| GAP1 | A standalone item with `isChecked` and no `onCheck` is inert but exposed as an editable checkbox. | exact `spec:AST-021` known failure `list-item-handlerless-read-only`; WCAG 4.1.2 | owner decision |
-| GAP2 | CheckboxListItem paints the checked-row fill itself, but no selection state is reflected on the row's `list-item`/`item` targets, so a theme cannot restyle checked rows apart from unchecked rows. | `architecture:component-theming-surface/INV6`; shipped source | owner decision |
-| GAP3 | An error `status` exposes no programmatic invalid state on the group or its checkboxes, and a status without a message renders nothing. | shipped source; `spec:AST-002/FR15` | owner decision |
-| GAP4 | Consumer ARIA pass-throughs on CheckboxList reach the field root rather than the named `role="group"`. | shipped source; `architecture:public-component-api/INV5` | owner decision |
-| GAP5 | On an enabled, editable checked row, the checked-row fill replaces the row's hover and pressed overlays, so pointer hover and hold give no row feedback on checked options. | exact-head Chromium `hover-checked` and `pressed-checked` receipts; `design:user-states` leaves hover and selection treatments outside its current claim | authority gap (unscored); owner decision |
-| GAP6 | Keyboard focus on an option paints two rings for one focus move: Item's row focus-within outline and CheckboxInput's indicator ring. | exact-head Chromium `focus-visible` receipts; `architecture:interaction-modality/INV3` | owner decision |
+| ID | Candidate invariant | Basis | Draft review state |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------ |
+| FR1 | The render MUST place CheckboxListItem children inside a List within a `role="group"` named by the group label through `aria-labelledby`; its `aria-describedby` MUST list the description, status message, and disabled-reason tooltip that are present, in that order. | shipped source; focused tests; WCAG 1.3.1 and 4.1.2 | verify |
+| FR2 | The CheckboxList root MUST carry the current `checkbox-list` target. | shipped source and public docs | settled |
+| FR4 | A status message MUST render through a detached FieldStatus after the list. | shipped source, focused tests, and Chromium receipts | verify |
+| FR6 | With a `value` array, the group MUST provide membership to its items, call `onChange` with the next array an item proposes (`component:CheckboxListItem` FR4), and then run `changeAction` with the same array in a transition with an optimistic value. | shipped source and focused tests | verify |
+| FR7 | The group MUST track every value whose `changeAction` is pending and expose it to its items, each of which renders busy (`component:CheckboxListItem` FR7); toggling another item MUST NOT clear an earlier pending value. Concurrent pending values settle together, after which every busy state clears. | shipped public `changeAction` promise; focused regression test; Chromium receipts | verify |
+| FR9 | Group `isDisabled` MUST natively disable every checkbox unless `disabledMessage` is set; with a reason, checkboxes MUST stay focusable through `aria-disabled`, show the reason tooltip on group hover and focus, and refuse toggling. | shipped source, focused tests, and shared checkbox binding | verify |
+| FR10 | Group `isReadOnly` MUST make every item in the group read-only (`component:CheckboxListItem` FR8 and FR10). | shipped source; shared checkbox binding; `spec:AST-011` read-only vocabulary | verify |
+| FR13 | `density` MUST reach the List and its rows (the checkbox size follows `component:CheckboxListItem` FR11); `hasDividers` MUST separate rows without a divider after the last row; `width` MUST size the label, list, and status together. | shipped source, docs, and Chromium receipts | verify |
+| GAP3 | An error `status` exposes no programmatic invalid state on the group or its checkboxes, and a status without a message renders nothing. | shipped source; `spec:AST-002/FR15` | owner decision |
+| GAP4 | Consumer ARIA pass-throughs on CheckboxList reach the field root rather than the named `role="group"`. | shipped source; `architecture:public-component-api/INV5` | owner decision |
+
+Per-option requirements and gaps that earlier drafts listed here have one owner
+(`architecture:knowledge-contracts/INV2`): former FR3 is
+`component:CheckboxListItem` FR1; FR5 is its FR2, FR3, and content concept (the
+target dispositions stay in the theming anatomy below); FR8 is its FR5; FR11 is
+its FR1, FR9, and FR10; FR12 is its FR2 and FR3; and GAP1, GAP2, GAP5, and GAP6
+keep their numbers there.
### Allowed variation
-- **AV1 — Option content.** Option labels, descriptions, and end content may
- vary with caller-provided CheckboxListItem content without becoming new
- CheckboxList targets.
-- **AV2 — Composed ownership.** Density, dividers, disabled dimming, hover and
- pressed row overlays, and the checkbox indicator remain capabilities of their
- current owning components rather than separate anatomy parts.
-- **AV3 — Theme paint.** Semantic tokens and composed targets may change
- admitted visual properties without changing semantics, tab order, or state
- precedence.
+- **AV1 — Group content.** The label, description, status message, and width
+ may vary within their public types.
+- **AV2 — Theme paint.** The `checkbox-list` target and the composed group
+ targets may change admitted visual properties without changing semantics or
+ state precedence.
+
+Option variation is `component:CheckboxListItem` AV1–AV3.
### Representative states
-| State | Required invariant | Allowed variation |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| Default collection | Named group, options list, rows, and checkboxes render; one tab stop per option | Option content and selected values |
-| Item pending | Each pending checkbox includes Spinner and busy state and refuses re-toggling | Which options are pending |
-| Group disabled with reason | Checkboxes stay focusable and inoperable; the reason is reachable by hover, focus, and AT | Reason text |
-| Group read-only | Values stay visible, focusable, full-opacity, and immutable with read-only semantics; an item `onClick` fires once per click | Which values are checked |
-| Group status with message | Detached FieldStatus follows the group and describes it | Error, warning, or success status |
-| Handlerless standalone | Inert; read-only, unavailable, or invalid-usage meaning is unsettled | No policy is introduced by this draft |
+| State | Required invariant | Allowed variation |
+| -------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------- |
+| Default collection | Named group, options list, and rows render; membership reaches every item | Option content and selected values |
+| Pending values | Each pending value keeps its item busy until every pending value settles | Which options are pending |
+| Group disabled with reason | Checkboxes stay focusable and inoperable; the reason is reachable by hover, focus, and AT | Reason text |
+| Group read-only | Every item is read-only | Which values are checked |
+| Group status with message | Detached FieldStatus follows the group and describes it | Error, warning, or success status |
### Transformation and precedence order
-- **ORD1 — Checked state.** Collection `value` → optimistic pending value →
- item membership; standalone items use `isChecked` only outside collection
- mode.
-- **ORD2 — Toggle.** disabled, read-only, or busy guard → next value →
- `onChange` → `changeAction` in a transition that adds the item to the pending
- set.
-- **ORD3 — Availability.** Item disabled or group disabled wins; a group reason
- changes focusability, not operability; read-only applies to mutation only.
+- **ORD1 — Checked state.** Collection `value` → optimistic pending value → the
+ membership each item reads (`component:CheckboxListItem` ORD1).
+- **ORD2 — Toggle.** An item's proposed next array (`component:CheckboxListItem`
+ ORD2) → `onChange` → `changeAction` in a transition that adds the toggled value
+ to the pending set.
+- **ORD3 — Availability.** Group disabled wins; a group reason changes
+ focusability, not operability; group read-only applies to mutation only.
### Performance and resources
@@ -184,26 +182,19 @@ durable constraints and their verification target.
- **AR1 — Group identity.** The group name and its description, status, and
disabled-reason relationships MUST remain programmatically determinable.
-- **AR2 — Option semantics.** Each option MUST remain a native checkbox with a
- determinable name, checked or mixed state, disabled, read-only, and busy
- state.
-- **AR3 — Keyboard parity.** Tab MUST reach each option's checkbox exactly once
- and Space MUST follow the same availability and change rules as pointer
- activation.
+- **AR2, AR3, AR5 — Option semantics, keyboard parity, and busy perception** are
+ owned by `component:CheckboxListItem` AR1, AR2, and AR4.
- **AR4 — Disabled reasons.** A group reason MUST stay discoverable by keyboard
focus and assistive technology while toggling stays blocked.
-- **AR5 — Busy perception.** A pending option MUST expose busy state in the
- accessibility tree and visibly through Spinner.
## Design relationships
-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
-| ------------------ | ---------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------- | ------------------ |
-| Group | Contains the current checkbox-group composition. | Current source and public docs | Supporting | FR1, FR2 |
-| Options and rows | Present the List-owned list and row root plus Item-rendered child structure. | Current source | Supporting | FR1, FR3, FR13 |
-| Checkbox | Presents each option's current selection indicator. | CheckboxInput owner and `design:user-states` for its press | Prominent | FR3, FR9–FR11 |
-| Checked-row fill | Supplements the checkbox state on enabled, editable checked rows. | unsettled (GAP2) | Supporting | GAP2 |
-| Spinner and status | Present the current conditional feedback components. | Current shared-component source | Supporting | FR4, FR7 |
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ---------------------------------------------------------------------------- | ------------------------------- | -------------- | ------------------------------------- |
+| Group | Contains the current checkbox-group composition. | Current source and public docs | Supporting | FR1, FR2 |
+| Options list | Presents the List-owned list and row roots. | Current source | Supporting | FR1, FR13 |
+| Option rows | Present each option's checkbox, content, busy spinner, and checked-row fill. | `component:CheckboxListItem` | Prominent | `component:CheckboxListItem` FR1–FR13 |
+| Status message | Presents the group's current status. | Current shared-component source | Supporting | FR4 |
### Theming anatomy
@@ -265,7 +256,7 @@ untargeted spans, so neither delegates to Text nor inherits the row-root
`list-item` target; future exposure remains unsettled. Rich label content and end
content are caller-provided, and end content intentionally stays outside
CheckboxList's public theming ownership. The `Option row` delegation reaches the
-row surface, but not a checked-row state (GAP2).
+row surface, but not a checked-row state (`component:CheckboxListItem` GAP2).
## Family and system relationships
@@ -276,59 +267,52 @@ row surface, but not a checked-row state (GAP2).
reflection.
- `architecture:interaction-modality` owns focus visibility and the boundary
between the focused checkbox and the element that paints its ring.
+- `architecture:knowledge-contracts/INV2` keeps each per-option fact in
+ `component:CheckboxListItem` rather than copying it here.
- `spec:AST-021` owns the reusable checkbox accessibility binding for
CheckboxListItem and its exact known-failure lifecycle.
- `spec:AST-011` records `isReadOnly` as the name for visible, focusable,
non-editable values.
- `spec:AST-038/FR7` stops CheckboxList context at a layer boundary; an item
inside a layer needs its own provider.
+- `component:CheckboxListItem` owns the per-option contract this group
+ composes.
- List, CheckboxInput, Field, FieldStatus, Spinner, and Tooltip retain their
existing public target and behavior contracts when composed by CheckboxList.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| -------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
-| FR1, AR1 | `CheckboxList.test.tsx` group naming, description, status, and disabled-reason assertions | Named group; description plus status; disabled reason | Dropping the label, description, status, or tooltip id from the group fails the accessible name or description assertions. | `audit:CheckboxList/a11y` |
-| FR3, FR5, FR11, FR12 | `CheckboxList.test.tsx` structure, naming, delegation, and tab-order suites | Collection mode; string/rich label; description; end content; row-surface click | A second tab stop, lost delegation, or a wrong name or description breaks existing interaction and ARIA assertions. | `audit:CheckboxList/behavior` |
-| FR4, FR7, AR5 | `CheckboxList.test.tsx` loading and pending suites; Chromium `pending-*` receipts | Item loading; one pending item; two pending items; settled | Clearing an earlier pending item, allowing its re-toggle, or leaving busy state after settlement fails the tests and receipts. | `audit:CheckboxList/behavior` |
-| FR6, FR8 | `CheckboxList.test.tsx` collection and standalone suites | add, remove, mixed, select-all | A wrong array, wrong boolean, or missing `value` error fails callback assertions. | `audit:CheckboxList/behavior` |
-| FR9, FR10, AR2–AR4 | Shared checkbox jsdom and Chromium bindings; `CheckboxList.test.tsx` disabled and read-only suites | Group disabled; disabled with reason; item disabled; read-only with and without an item `onClick`; handlerless known failure | A focusability, state, reason, or single-fire expectation fails, a read-only toggle succeeds, or the recorded known failure becomes stale. | `audit:CheckboxList/a11y` |
-| FR13 | Chromium density, divider, long-content, and RTL receipts | compact, balanced, spacious; dividers; 320px long content; RTL | A size, divider, width, overflow, or direction sensor fails. | `audit:CheckboxList/responsive` |
-| Local target source | `themingTargets.test.ts` | `checkbox-list` | Source/docs target drift fails the repository target guard. | `audit:CheckboxList/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local target | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:CheckboxList/theming` |
-
-No current repository check resolves `delegatesTo` owner/target pairs; the pairs
-in this draft were verified manually, so semantic delegation drift remains a
-validation gap.
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1, AR1 | `CheckboxList.test.tsx` group naming, description, status, and disabled-reason assertions | Named group; description plus status; disabled reason | Dropping the label, description, status, or tooltip id from the group fails the accessible name or description assertions. | `audit:CheckboxList/a11y` |
+| FR4, FR6, FR7 | `CheckboxList.test.tsx` collection, status, and pending suites; Chromium `pending-*` receipts | add, remove; status; one pending value; two pending values; settled | A wrong array, a missing status, clearing an earlier pending value, allowing its re-toggle, or leaving busy after settlement fails. | `audit:CheckboxList/behavior` |
+| FR9, FR10, AR4 | `CheckboxList.test.tsx` disabled and read-only suites; shared checkbox bindings | Group disabled; disabled with reason; group read-only | A focusability, state, or reason expectation fails, or a toggle succeeds while the group is disabled or read-only. | `audit:CheckboxList/a11y` |
+| FR13 | Chromium density, divider, long-content, and RTL receipts | compact, balanced, spacious; dividers; 320px long content; RTL | A density, divider, width, overflow, or direction sensor fails. | `audit:CheckboxList/responsive` |
+| Local target source | `themingTargets.test.ts` | `checkbox-list` | Source/docs target drift fails the repository target guard. | `audit:CheckboxList/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local target | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails repository validation. | `audit:CheckboxList/theming` |
+
+Per-option verification is owned by `component:CheckboxListItem`'s
+verification map. No current repository check resolves `delegatesTo`
+owner/target pairs; the pairs in this draft were verified manually, so semantic
+delegation drift remains a validation gap.
## Decision log
-None. This draft records shipped behavior and two objective remediations; it
-introduces no new API, default, target, or subjective visual decision.
+None. This draft records shipped behavior; it introduces no new API, default,
+target, or subjective visual decision.
## Open questions
-- **OQ1 — What does a standalone item with `isChecked` and no `onCheck`
- mean?** (`human-api`) It is inert while exposed as editable. Direction must
- choose read-only, unavailable, or invalid usage, consistent with the matching
- CheckboxInput decision.
-- **OQ2 — How should a theme reach the checked-row fill?** (`human-api`) The
- fill is component-owned paint on a delegated List row with no reflected state;
- exposing it needs a target or state decision.
- **OQ3 — Should an error status expose invalid state, and what should a status
without a message render?** (`human-api`)
- **OQ4 — Which element owns consumer ARIA pass-throughs on CheckboxList?**
(`human-api`) They currently reach the field root rather than the group.
-- **OQ5 — What hover and pressed feedback should a checked row show?**
- (`human-design`) The checked-row fill currently replaces both overlays.
-- **OQ6 — Which element paints the focus ring for an option?** (`human-design`)
- The row ring and the indicator ring both paint today;
- `architecture:interaction-modality/INV3` requires one owning indicator, and
- RadioList composes the same two painters.
+
+Former OQ1, OQ2, OQ5, and OQ6 are per-option questions and keep their numbers in
+`component:CheckboxListItem`.
## Content boundary
This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or shared-component contracts. It links to their
-owners.
+results, implementation steps, the per-option contract, or shared-component
+contracts. It links to their owners.
diff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsx
index ce017528d0..1cca5eabe6 100644
--- a/packages/core/src/CheckboxList/CheckboxList.test.tsx
+++ b/packages/core/src/CheckboxList/CheckboxList.test.tsx
@@ -610,6 +610,54 @@ describe('CheckboxList', () => {
});
describe('CheckboxListItem standalone mode', () => {
+ it('ignores isChecked and onCheck when the parent CheckboxList has a value array', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ const onCheck = vi.fn();
+ render(
+ <CheckboxList label="Preferences" value={[]} onChange={onChange}>
+ <CheckboxListItem
+ label="Option A"
+ value="a"
+ isChecked
+ onCheck={onCheck}
+ />
+ </CheckboxList>,
+ );
+ const checkbox = screen.getByRole('checkbox', {name: 'Option A'});
+ // The list's value array owns checked state in collection mode.
+ expect(checkbox).not.toBeChecked();
+ await user.click(checkbox);
+ expect(onChange).toHaveBeenCalledWith(['a']);
+ expect(onCheck).not.toHaveBeenCalled();
+ });
+
+ it('renders the sm checkbox at compact density and md otherwise', () => {
+ const {unmount} = render(
+ <CheckboxList
+ label="Preferences"
+ density="compact"
+ value={[]}
+ onChange={() => {}}>
+ <CheckboxListItem label="Option A" value="a" />
+ </CheckboxList>,
+ );
+ const compactField = screen
+ .getByRole('checkbox')
+ .closest('.astryx-checkbox-input');
+ expect(compactField).toHaveAttribute('data-size', 'sm');
+ unmount();
+ render(
+ <List>
+ <CheckboxListItem label="Option A" />
+ </List>,
+ );
+ const balancedField = screen
+ .getByRole('checkbox')
+ .closest('.astryx-checkbox-input');
+ expect(balancedField).toHaveAttribute('data-size', 'md');
+ });
+
it('uses isChecked/onCheck for standalone control', async () => {
const user = userEvent.setup();
const handleCheck = vi.fn();
diff --git a/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs b/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs
index f7111b81a1..878a0540c5 100644
--- a/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs
@@ -8,7 +8,7 @@ export const docs = {
displayName: 'Checkbox List Item',
isHiddenFromOverview: true,
description:
- 'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside CheckboxList) or standalone mode (inside List).',
+ 'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside a CheckboxList with a value array) or standalone mode (inside List, or inside a CheckboxList without value, such as a select-all item).',
props: [
{
name: 'label',
@@ -26,7 +26,8 @@ export const docs = {
{
name: 'value',
type: 'string',
- description: 'Identity key (required inside CheckboxList).',
+ description:
+ 'Identity key. Required when the parent CheckboxList has a value array; the item throws without it there.',
},
{
name: 'description',
@@ -70,12 +71,14 @@ export const docs = {
{
name: 'isChecked',
type: "boolean | 'indeterminate'",
- description: 'Direct checked state (standalone mode only).',
+ description:
+ 'Direct checked state in standalone mode: inside List, or inside a CheckboxList without value (for example, a select-all item). Ignored when the parent CheckboxList has a value array.',
},
{
name: 'onCheck',
type: '(checked: boolean) => void',
- description: 'Direct check handler (standalone mode only).',
+ description:
+ "Direct check handler in standalone mode: inside List, or inside a CheckboxList without value. Ignored when the parent CheckboxList has a value array; that list's onChange receives the change.",
},
],
examples: [
@@ -95,7 +98,7 @@ export const docsZh = {
isHiddenFromOverview: true,
displayName: 'Checkbox List Item',
description:
- '单个复选框选项,包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',
+ '单个复选框选项,包含标签、描述和尾部内容插槽。可在集合模式(位于带 value 数组的 CheckboxList 内)或独立模式(位于 List 内,或位于不带 value 的 CheckboxList 内,例如“全选”选项)下使用。',
props: [
{
name: 'label',
@@ -113,7 +116,8 @@ export const docsZh = {
{
name: 'value',
type: 'string',
- description: '标识键(在 CheckboxList 内为必填)。',
+ description:
+ '标识键。当父级 CheckboxList 带有 value 数组时为必填;缺少时该选项会抛出错误。',
},
{
name: 'description',
@@ -142,12 +146,14 @@ export const docsZh = {
{
name: 'isChecked',
type: "boolean | 'indeterminate'",
- description: '直接选中状态(仅独立模式)。',
+ description:
+ '独立模式下的直接选中状态:位于 List 内,或位于不带 value 的 CheckboxList 内(例如“全选”选项)。当父级 CheckboxList 带有 value 数组时忽略。',
},
{
name: 'onCheck',
type: '(checked: boolean) => void',
- description: '直接选中处理器(仅独立模式)。',
+ description:
+ '独立模式下的直接选中处理函数:位于 List 内,或位于不带 value 的 CheckboxList 内。当父级 CheckboxList 带有 value 数组时忽略,改由该列表的 onChange 接收变更。',
},
],
};
@@ -157,20 +163,23 @@ export const docsDense = {
isHiddenFromOverview: true,
displayName: 'Checkbox List Item',
description:
- 'Individual checkbox item w/ label, description, end content slot.',
+ 'Individual checkbox item w/ label, description, end content slot. Collection mode inside CheckboxList with value; standalone inside List or CheckboxList without value.',
propDescriptions: {
label:
'Primary label. String or ReactNode; nested controls keep their behavior. A ReactNode names the checkbox from its visible text.',
'aria-label':
'Plain-text checkbox name replacing the one derived from label. Use when visible text is absent; otherwise retain every visible label word.',
- value: 'Identity key (required inside CheckboxList).',
+ value:
+ 'Identity key. Required when parent CheckboxList has a value array (throws without it).',
description:
"Secondary content below label. String or ReactNode. Exposed as the checkbox's accessible description via aria-describedby.",
endContent: 'Content rendered after label area.',
- isDisabled: 'Whether this individual item disabled.',
+ isDisabled: 'Whether this individual item is disabled.',
isLoading:
'Item loading: spinner inside checkbox + blocks interaction. Auto-set on toggled item while parent changeAction pending.',
- isChecked: 'Direct checked state (standalone mode only).',
- onCheck: 'Direct check handler (standalone mode only).',
+ isChecked:
+ 'Direct checked state in standalone mode (inside List, or CheckboxList without value). Ignored when parent CheckboxList has a value array.',
+ onCheck:
+ 'Direct check handler in standalone mode (inside List, or CheckboxList without value). Ignored when parent CheckboxList has a value array; its onChange gets the change.',
},
};
diff --git a/packages/core/src/CheckboxList/CheckboxListItem.spec.md b/packages/core/src/CheckboxList/CheckboxListItem.spec.md
new file mode 100644
index 0000000000..e7ced972a0
--- /dev/null
+++ b/packages/core/src/CheckboxList/CheckboxListItem.spec.md
@@ -0,0 +1,276 @@
+---
+schema_version: 3
+template_version: 6
+kind: component
+id: component:CheckboxListItem
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers:
+ [public-api, behavior, interaction, theming, accessibility, visual]
+verified_by:
+ [
+ packages/core/src/CheckboxList/CheckboxList.test.tsx,
+ packages/core/src/CheckboxList/__tests__/CheckboxList.a11y.chromium.spec.ts,
+ packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx,
+ packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts,
+ apps/storybook/stories/CheckboxList.stories.tsx,
+ apps/storybook/rtl-audit/targets.json,
+ scripts/check-knowledge.mjs,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:public-component-api,
+ architecture:component-theming-surface,
+ architecture:component-test-sufficiency,
+ architecture:interaction-modality,
+ ]
+contributing: []
+system_specs: [spec:AST-011, spec:AST-021, spec:AST-038]
+---
+
+# CheckboxListItem component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | One option row: a native checkbox named by `label` or `aria-label`, described by `description`, with optional `endContent`, rendered through ListItem. Inside a CheckboxList with a `value` array (collection mode), checked state comes from membership and `value` is required. Inside List, or inside a CheckboxList without `value` (standalone mode), the item reads `isChecked` and calls `onCheck`. |
+| Behavior | The checkbox is the option's only tab stop. Row-surface clicks delegate to it when the item is editable and sits in a CheckboxList or has `onCheck`, or when it has `onClick`; an item `onClick` fires once per direct, keyboard, or row-surface click. Disabled, read-only, and busy states refuse toggling. |
+| End-user impact | People can operate each option by pointer, touch, and keyboard, hear its name, description, and checked, mixed, disabled, read-only, or busy state, and see a spinner while it saves. |
+| Builder impact | Where the item sits, and whether its parent list has `value`, selects the mode; `value` is required only in collection mode. Handlerless meaning, checked-row theming and pointer feedback, consumer DOM-prop targets, and focus-ring ownership remain owner decisions. Read-only click propagation to ancestors is an unscored authority gap routed to the shared clickable-container hook. |
+| Compatibility/readiness | Released API, defaults, DOM ownership, and targets are unchanged. This draft records shipped behavior only. |
+| Review checks | Reject a second tab stop, a toggle while disabled, read-only, or busy, `isChecked` overriding a parent `value` array, an `onClick` that fires more than once per click, a dropped description relationship, or a new target, state, or event-routing API introduced without an owner decision. |
+| Governing rules | `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:interaction-modality/INV1–INV5`; `architecture:component-test-sufficiency/INV1–INV7`; `spec:AST-021/FR8–FR10`; `spec:AST-011`; `spec:AST-038/FR7`; WCAG 2.2 1.3.1, 2.1.1, 4.1.2. |
+
+This table is a review projection; the body below becomes authoritative only after owner approval.
+
+## Intent
+
+Present one independent choice as a full-width row whose checkbox, label,
+description, and end content stay aligned with its checked, available,
+read-only, and busy state, inside a CheckboxList or a plain List.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: observational record; no runtime change
+- Controlled/uncontrolled behavior: controlled only — by the parent list's
+ `value` in collection mode, by `isChecked` in standalone mode
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One option row: its CheckboxInput, naming (string label, rich label through
+ `aria-labelledby`, `aria-label` override), description relationship,
+ end-content slot, and the checkbox size that follows list density.
+- Mode resolution: collection membership versus standalone `isChecked` and
+ `onCheck`, the error for a missing `value` in collection mode, and the next
+ value the row proposes.
+- Row-surface click delegation, the single-tab-stop rule, and item `onClick`
+ routing.
+- Item disabled and loading states, the busy rendering of a pending collection
+ item, read-only rendering, and the checked-row fill.
+
+**Does not own / non-goals**
+
+- The group, its label, description, status, disabled reason, read-only and
+ disabled inputs, pending-value set, and collection change ordering — owned by
+ `component:CheckboxList`.
+- Row presentation, density, dividers, hover and pressed overlays, the
+ focus-within ring, the `list-item` target, and label and description
+ truncation — owned by `component:List` and Item.
+- The checkbox control, its indicator, focus ring, pressed overlay, and busy,
+ disabled, and read-only semantics — owned by `component:CheckboxInput` and
+ `component:CheckboxIndicator`.
+- Loading-indicator presentation — owned by `component:Spinner`; delegation
+ mechanics — owned by the shared clickable-container hook.
+- New targets, reflected states, or event-routing API.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------- | -------------------- | -------------------------------------- | -------------------------------------------- |
+| naming | string `label`; node `label`; `aria-label` | Names the checkbox; a node label names it from its visible text; `aria-label` replaces the derived name on the checkbox, not the row. | All states. | label required | caller and component | stable | rejected by the public type |
+| mode | collection (parent has `value`); standalone in CheckboxList without `value`; standalone in List | Collection reads membership and reports through the parent; standalone reads `isChecked` and calls `onCheck`. | Chosen by placement; `isChecked` and `onCheck` are ignored in collection mode. | standalone | component | stable | a collection item without `value` throws |
+| checked state | unchecked, checked, mixed (standalone only) | Native checkbox state; mixed uses the native `indeterminate` property and proposes `true`. | All modes. | unchecked | caller | stable | rejected by the public type |
+| change path | parent `onChange`/`changeAction` (collection); `onCheck` (standalone); none | Proposes the next value array or boolean. | Enabled, editable, non-busy items. | none | caller and component | shipped; handlerless meaning unsettled | no handler means no component-owned mutation |
+| availability | enabled; item `isDisabled`; group disabled; group disabled with reason | Blocks toggling and the checked-row fill; a group reason keeps the checkbox focusable through `aria-disabled`. | Item and group. | enabled | component | stable | boolean only |
+| read-only | from the group's `isReadOnly` | Keeps the value visible, focusable, and full-opacity while refusing toggles. | Inside CheckboxList only. | false | component | stable | boolean only |
+| busy | `isLoading`; pending parent `changeAction` for the item's `value` | Spinner in the checkbox, busy row and checkbox, toggling refused. | Per item. | idle | component | stable | boolean/transition state only |
+| content | `description`, `endContent` | Description describes the checkbox; end content stays caller-owned and outside the name. | All states. | none | caller | stable | typed values only |
+| `onClick` | fires on the checkbox for direct, keyboard, and row-surface clicks | Once per click, including read-only items; the public type names the row element. | All states. | none | caller and component | shipped; target unsettled | — |
+| pass-through | `ref`, `className`, `style`, `xstyle`, data, ARIA except `aria-label`, other events | Reach the row `<li>`; consumer `xstyle` composes after the checked-row fill. | All states. | none | component | shipped; ARIA target unsettled | component-owned attributes win |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision. A `current` contract contains no unresolved rows.
+
+| ID | Candidate invariant | Basis | Draft review state |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
+| FR1 | The row MUST render one native CheckboxInput as ListItem start content; that checkbox MUST be the option's only focusable control, and the row itself MUST NOT be focusable. | shipped source; focused tests; WCAG 2.1.1 and 4.1.2 | verify |
+| FR2 | A string `label` MUST name the checkbox; a node `label` MUST name it from the visible label element through `aria-labelledby`; `aria-label` MUST replace the derived name on the checkbox and never reach the row. | shipped source and focused tests | verify |
+| FR3 | A renderable `description` MUST describe the checkbox through `aria-describedby`; an absent or empty description MUST add none. | shipped source and focused tests; WCAG 1.3.1 | verify |
+| FR4 | Inside a CheckboxList with a `value` array, the item MUST read checked state from membership, throw without `value`, and propose the array with its `value` added or removed through the parent's change path; `isChecked` and `onCheck` MUST be ignored. | shipped source and focused tests | verify |
+| FR5 | Inside List, or inside a CheckboxList without `value`, the item MUST read `isChecked` and call `onCheck` with the next boolean; a mixed item MUST propose `true`, and `value` MAY be omitted. | shipped source and focused tests | verify |
+| FR6 | Item `isDisabled` or a disabled group MUST disable the checkbox, refuse toggling, and omit the checked-row fill; a group reason keeps the checkbox focusable through `aria-disabled` (`component:CheckboxList` FR9). | shipped source, focused tests, and shared checkbox binding | verify |
+| FR7 | Item `isLoading`, or a pending parent `changeAction` for the item's `value`, MUST render Spinner inside the checkbox, mark the row and the checkbox busy, and refuse toggling. | shipped source, focused tests, and Chromium receipts | verify |
+| FR8 | A read-only group MUST make the checkbox read-only, focusable, and full-opacity, refuse every toggle, and omit the checked-row fill; the row delegates clicks only when the item has `onClick`. | shipped source, focused tests, and shared checkbox binding; `spec:AST-011` | verify |
+| FR9 | On an enabled, editable item inside a CheckboxList or with `onCheck`, a row-surface click outside interactive descendants MUST be delegated to the checkbox; links and buttons in the label, description, or end content MUST keep their own behavior. | shipped source and focused tests | verify |
+| FR10 | An item `onClick` MUST fire once for each direct, keyboard, or row-surface click, including on read-only items. | shipped source and focused tests; `architecture:public-component-api/INV5` | verify |
+| FR11 | `compact` density MUST render the `sm` checkbox; other densities MUST render `md`. | shipped source and focused test | verify |
+| FR12 | An enabled, editable, checked row MUST paint the `--color-accent-muted` fill, and consumer `xstyle` MUST compose after it. | shipped source and Chromium receipts | verify |
+| FR13 | `ref`, `className`, `style`, `xstyle`, data attributes, ARIA other than `aria-label`, and events other than `onClick` MUST reach the row `<li>`. | shipped source and focused tests | verify |
+| GAP1 | A standalone item with `isChecked` and no `onCheck` is inert but exposed as an editable checkbox; inside a CheckboxList without `value`, its row also delegates clicks and shows pointer feedback. | exact `spec:AST-021` known failure `list-item-handlerless-read-only`; WCAG 4.1.2 | owner decision |
+| GAP2 | The item paints the checked-row fill itself, but no selection state is reflected on the row's `list-item`/`item` targets, so a theme cannot restyle checked rows apart from unchecked rows. | `architecture:component-theming-surface/INV6` | owner decision |
+| GAP3 | Consumer DOM inputs split between two elements: data attributes and ARIA reach the row, while `onClick` runs on the checkbox and is typed for the row, so `event.currentTarget` is the checkbox and does not carry the row's data attributes. | `architecture:public-component-api/INV5`; `INV9` for any retype or move | owner decision |
+| GAP4 | On a read-only item with `onClick`, the item stops the click's propagation, so React ancestors never receive those clicks, while they do for enabled items. The stop exists because the shared clickable-container hook would re-delegate a click that came from an `aria-readonly` delegate target back to it. The item's own `onClick` still fires once per click (FR10). | No current authority owns ancestor propagation; shared clickable-container hook behavior (advisory) | authority gap (unscored); shared-module advisory |
+| GAP5 | On an enabled, editable, checked row, the checked-row fill replaces the row's hover and pressed overlays, so pointer hover and hold give no row feedback. | Chromium receipts; `design:user-states` leaves hover and selection treatment outside its current claim | authority gap (unscored); owner decision |
+| GAP6 | One keyboard focus move paints two indicators: Item's row focus-within outline and CheckboxInput's indicator ring. | Chromium receipts; `architecture:interaction-modality/INV3` | owner decision |
+
+### Allowed variation
+
+- **AV1 — Content.** Label, description, and end content may vary within their
+ public types without becoming new targets.
+- **AV2 — Composed presentation.** Density, dividers, row overlays, the focus
+ ring, and the checkbox indicator remain capabilities of their owning
+ components.
+- **AV3 — Theme paint.** Semantic tokens and composed targets may change
+ admitted visual properties without changing semantics, tab order, or state
+ precedence.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| --------------------------------- | --------------------------------------------------------------------------- | ------------------------------------- |
+| Collection option | Checked from membership; one tab stop; toggles through the parent | Label, description, end content |
+| Standalone option (List or group) | Reads `isChecked`, calls `onCheck`; mixed proposes `true` | Placement |
+| Busy option | Spinner, busy row and checkbox, toggling refused | Loading source (prop or pending save) |
+| Read-only option | Visible, focusable, full-opacity, immutable; `onClick` fires once per click | Whether the item has `onClick` |
+| Disabled option | Inoperable; no checked-row fill | Item or group source; group reason |
+| Handlerless standalone option | Inert; read-only, unavailable, or invalid-usage meaning is unsettled | No policy is introduced by this draft |
+
+### Transformation and precedence order
+
+- **ORD1 — Checked state.** Parent `value` array (collection) → optimistic
+ pending value → membership; otherwise `isChecked`; otherwise unchecked.
+- **ORD2 — Toggle.** disabled, read-only, or busy guard → mode → parent
+ `onChange` (collection) or `onCheck` (standalone).
+- **ORD3 — Click routing.** Interactive descendants keep their clicks → other
+ row-surface clicks delegate to the checkbox when the item is editable and sits
+ in a CheckboxList or has `onCheck`, or has `onClick` → the checkbox's click
+ runs `onClick` once.
+- **ORD4 — Attributes.** Consumer rest props → row `<li>`; `aria-label` and
+ `onClick` → checkbox; component-owned name, description, state, and busy
+ attributes win.
+
+### Performance and resources
+
+- **PR1 — Bounded resources.** The item owns no observer, timer, or global
+ listener; delegation listeners belong to the row and its lifetime.
+
+Current measurements belong in the audit record; this subsection owns only
+durable constraints and their verification target.
+
+## Accessibility contract
+
+- **AR1 — Option semantics.** Each option MUST remain a native checkbox whose
+ name, description, checked or mixed state, and disabled, read-only, and busy
+ states are programmatically determinable.
+- **AR2 — Keyboard parity.** Tab MUST reach the checkbox exactly once, and Space
+ MUST follow the same availability and change rules as pointer activation.
+- **AR3 — Enlarged target.** The row surface MUST act as the checkbox's pointer
+ and touch target without becoming a second control.
+- **AR4 — Busy perception.** A busy option MUST expose busy state in the
+ accessibility tree and visibly through Spinner.
+- **AR5 — Focus visibility.** Keyboard focus on the checkbox MUST stay visible;
+ which element owns the single indicator is open (GAP6).
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------- | ------------------ |
+| Option row | Full-width row with start checkbox, label and description, and end content. | List and Item | Supporting | FR1, FR9, FR13 |
+| Checkbox | Presents the option's selection indicator. | CheckboxInput owner and `design:user-states` for its press | Prominent | FR1, FR6–FR8, FR11 |
+| Label, description | Name and describe the checkbox. | Item | Primary content | FR2, FR3 |
+| Checked-row fill | Supplements the checkbox state on enabled, editable checked rows. | unsettled (GAP2, GAP5) | Supporting | FR12 |
+| Spinner | Replaces the mark while the option is busy. | Spinner | Supporting | FR7 |
+
+This draft adds no `anatomy-theming:v1` block. The composed option anatomy and
+its target dispositions are recorded in `component:CheckboxList`'s theming
+anatomy, and CheckboxListItem owns no target of its own.
+
+## Family and system relationships
+
+- `component:CheckboxList` composes this contract: it supplies the collection
+ value, availability, read-only, and pending values the option reads through
+ context, and owns the group around it.
+- `architecture:public-component-api` owns pass-through preservation, event
+ composition, refs, and released-change rules.
+- `architecture:component-theming-surface` owns target placement and state
+ reflection.
+- `architecture:interaction-modality` owns focus visibility and the one-indicator
+ rule.
+- `spec:AST-021` owns the reusable checkbox accessibility binding for
+ CheckboxListItem and its exact known-failure lifecycle.
+- `spec:AST-011` records `isReadOnly` as the name for visible, focusable,
+ non-editable values.
+- `spec:AST-038/FR7` stops CheckboxList context at a layer boundary; an item
+ inside a layer needs its own provider.
+- List, Item, CheckboxInput, CheckboxIndicator, and Spinner retain their
+ existing target and behavior contracts when composed here.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
+| FR1, FR9, AR2, AR3 | `CheckboxList.test.tsx` single-tab-stop, delegation, and interactive-content suites | Collection option; row-surface click; link in a rich label; interactive end content | A second tab stop, lost delegation, or a toggle from an interactive descendant fails the assertions. | `audit:CheckboxListItem/behavior` |
+| FR2, FR3, AR1 | `CheckboxList.test.tsx` accessible-name and description suites; shared checkbox bindings | String and rich label; `aria-label` override; string and node description; absent description | A wrong name or description, or `aria-label` on the row, fails the assertions. | `audit:CheckboxListItem/a11y` |
+| FR4, FR5 | `CheckboxList.test.tsx` collection, standalone, and select-all suites | add, remove, missing `value`, mixed, select-all, `isChecked` with a parent `value` array | A wrong array or boolean, a missing error, or `isChecked` overriding the parent fails the assertions. | `audit:CheckboxListItem/behavior` |
+| FR6–FR8, AR4 | `CheckboxList.test.tsx` disabled, loading, pending, and read-only suites; shared checkbox bindings; Chromium receipts | Item and group disabled; reason; loading; pending; read-only with and without `onClick` | A toggle while disabled, read-only, or busy, a lost busy state, or a read-only toggle fails the tests. | `audit:CheckboxListItem/a11y` |
+| FR10 | `CheckboxList.test.tsx` item `onClick` and read-only click tests | Enabled and read-only; direct, keyboard, and row-surface clicks | An `onClick` that fires zero or several times per click fails the assertions. | `audit:CheckboxListItem/behavior` |
+| FR11 | `CheckboxList.test.tsx` density test | compact and balanced | A wrong checkbox size fails the assertion. | `audit:CheckboxListItem/behavior` |
+| FR12 | Chromium checked, hover, and pressed receipts | light and dark | A missing or misplaced fill fails the receipts' row-paint check. | `audit:CheckboxListItem/design-rendered` |
+| FR13 | `CheckboxList.test.tsx` pass-through, data-testid, and ARIA tests | row ref, class, style, data, ARIA | A dropped or misrouted input fails the assertions. | `audit:CheckboxListItem/api` |
+| Direction | curated RTL D2 target `core-checkboxlist--rich-descriptions` | LTR and RTL | The checkbox and end content fail to swap inline order. | `audit:CheckboxListItem/i18n-rtl` |
+
+## Decision log
+
+None. This draft records shipped behavior; it introduces no new API, default,
+target, or subjective visual decision.
+
+## Open questions
+
+- **OQ1 — What does a standalone item with `isChecked` and no `onCheck`
+ mean?** (`human-api`) Choose read-only, unavailable, or invalid usage,
+ consistent with the matching CheckboxInput question.
+- **OQ2 — How should a theme reach the checked-row fill?** (`human-api`)
+ Exposing it needs a target or reflected-state decision.
+- **OQ3 — Which element owns consumer DOM inputs?** (`human-api`) Data and ARIA
+ reach the row while `onClick` runs on the checkbox under a row-typed handler.
+- **OQ4 — Should read-only item clicks propagate?** (`human-api`) No current
+ authority owns ancestor propagation, so this is an unscored authority gap.
+ Removing the stop needs the shared clickable-container hook to stop
+ re-delegating clicks that already came from its delegate target.
+- **OQ5 — What hover and pressed feedback should a checked row show?**
+ (`human-design`) The checked-row fill currently replaces both overlays.
+- **OQ6 — Which element paints the option's focus ring?** (`human-design`)
+ `architecture:interaction-modality/INV3` requires one indicator; RadioList
+ composes the same two painters.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables and examples, current audit
+results, implementation steps, or the group contract. It links to their
+owners.
diff --git a/packages/core/src/CheckboxList/CheckboxListItem.tsx b/packages/core/src/CheckboxList/CheckboxListItem.tsx
index bf762ba797..1e65681599 100644
--- a/packages/core/src/CheckboxList/CheckboxListItem.tsx
+++ b/packages/core/src/CheckboxList/CheckboxListItem.tsx
@@ -9,6 +9,7 @@
* @position Core implementation; consumed by index.ts, tested by CheckboxList.test.tsx
*
* SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/CheckboxList/CheckboxListItem.doc.mjs
* - /packages/core/src/CheckboxList/CheckboxList.doc.mjs
* - /packages/core/src/CheckboxList/CheckboxList.test.tsx
* - /packages/core/src/CheckboxList/index.ts
@@ -81,8 +82,9 @@ export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
*/
'aria-label'?: string;
/**
- * Identity key for collection mode (REQUIRED inside CheckboxList).
- * Throws a runtime error if missing when used inside CheckboxList.
+ * Identity key for collection mode. Required when the parent CheckboxList
+ * has a `value` array: the item throws without it there. An item inside
+ * List, or inside a CheckboxList without `value`, may omit it.
*/
value?: string;
/**
@@ -112,13 +114,16 @@ export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {
*/
isLoading?: boolean;
/**
- * Direct checked state (standalone mode only).
- * Ignored when inside CheckboxList.
+ * Direct checked state for standalone mode: an item inside List, or inside
+ * a CheckboxList without `value` (for example, a select-all item). Ignored
+ * when the parent CheckboxList has a `value` array, which then owns the
+ * checked state.
*/
isChecked?: boolean | 'indeterminate';
/**
- * Direct check handler (standalone mode only).
- * Ignored when inside CheckboxList.
+ * Direct check handler for standalone mode: an item inside List, or inside a
+ * CheckboxList without `value`. Ignored when the parent CheckboxList has a
+ * `value` array; that list's `onChange` receives the change instead.
*/
onCheck?: (checked: boolean) => void;
/** Ref forwarded to the root element */
@@ -152,8 +157,9 @@ function DescribedCheckboxInput(
}
/**
- * A checkbox item for use within CheckboxList (collection mode)
- * or List (standalone mode).
+ * A checkbox item for use within CheckboxList (collection mode, when the list
+ * has a `value` array) or standalone (inside List, or inside a CheckboxList
+ * without `value`).
*
* In collection mode, checked state is derived from the parent's value array.
* In standalone mode, uses isChecked/onCheck props directly.