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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex bf90975392..603711a0a0 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -1132,15 +1132,16 @@ jobs:retention-days: 30if-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=1pnpm 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@v7with: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.jsonindex 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.mdindex 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: noneConsumer 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, changeordering, 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 — ownedby `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 contractDraft requirements identify their basis so observed code is not mistaken for anintentional 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, anddisabled-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 keyboardfocus 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 endcontent are caller-provided, and end content intentionally stays outsideCheckboxList'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 boundarybetween 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 forCheckboxListItem 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 iteminside a layer needs its own provider.+- `component:CheckboxListItem` owns the per-option contract this group+ composes.- List, CheckboxInput, Field, FieldStatus, Spinner, and Tooltip retain theirexisting 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 statuswithout 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 boundaryThis 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.tsxindex 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.mjsindex 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.mdnew file mode 100644index 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.tsxindex 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.