Skip to content

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

TypeScript

fix(CheckboxListItem): a checked row reflects selected on its row targets (#10146)

Cindy Zhangde0bbc2ffd1e
diff --git a/.changeset/checkbox-list-item-selected-state.md b/.changeset/checkbox-list-item-selected-state.md
new file mode 100644
index 0000000000..3180f5222d
--- /dev/null
+++ b/.changeset/checkbox-list-item-selected-state.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] A checked, enabled, editable `CheckboxListItem` row now reflects `data-selected="selected"` on its row, the element that carries its `item` and `list-item` targets, so a theme's `selected` rules for those targets restyle checked rows and the text on their fill.
+
+@cixzhang
diff --git a/docs/specs/components/CheckboxList/CheckboxList.spec.md b/docs/specs/components/CheckboxList/CheckboxList.spec.md
index dee7b83862..8b160bc92b 100644
--- a/docs/specs/components/CheckboxList/CheckboxList.spec.md
+++ b/docs/specs/components/CheckboxList/CheckboxList.spec.md
@@ -270,7 +270,8 @@ 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 (`component:CheckboxListItem` FR15).
+row surface and, on a checked, enabled, editable row, its `selected` state
+(`component:CheckboxListItem` FR15).
## Family and system relationships
diff --git a/docs/specs/components/CheckboxList/CheckboxListItem.spec.md b/docs/specs/components/CheckboxList/CheckboxListItem.spec.md
index 7053d8e5c5..3ba0d16c2e 100644
--- a/docs/specs/components/CheckboxList/CheckboxListItem.spec.md
+++ b/docs/specs/components/CheckboxList/CheckboxListItem.spec.md
@@ -56,8 +56,8 @@ system_specs: [spec:AST-011, spec:AST-021, spec:AST-038, spec:AST-085]
| 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, read-only click propagation, and focus-ring ownership stay open questions (OQ1–OQ6). |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Handlerless items, checked-row state reflection, and the double focus indicator are listed under Current-state impact. |
+| 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 pointer feedback, consumer DOM-prop targets, read-only click propagation, and focus-ring ownership stay open questions (OQ1, OQ3–OQ6). |
+| Compatibility/readiness | A checked, enabled, editable row reflects `selected` (FR15); no API or default change. Handlerless items and the double focus indicator are listed under Current-state impact. |
| 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-085/FR1, FR7`; `spec:AST-011`; `spec:AST-038/FR7`; WCAG 2.2 1.3.1, 2.1.1, 4.1.2. |
@@ -143,7 +143,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR12 | An enabled, editable, checked row MUST paint the `--color-accent-muted` fill, and consumer `xstyle` MUST compose after it. | shipped source and the Chromium accessibility suite |
| 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 |
| FR14 | A standalone item with `isChecked` and no `onCheck` changes nothing on activation. Implementation gap: it declares no read-only state, so the checkbox is exposed as editable (WCAG 2.2 4.1.2); inside a CheckboxList without `value`, its row also delegates clicks and shows pointer feedback. Its meaning is OQ1. | exact `spec:AST-021` known failure `list-item-handlerless-read-only`; WCAG 4.1.2 |
-| FR15 | The item paints the checked-row fill itself and reflects no selection state on the row's `list-item` or `item` targets, so a theme cannot restyle checked rows apart from unchecked rows (OQ2). Selection state MUST be reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: no selection state is reflected. | `architecture:component-theming-surface/INV6` |
+| FR15 | A checked, enabled, editable row paints the checked-row fill and reflects a `selected` state on the row's `item` and `list-item` targets, so a theme can restyle checked rows and the text on that fill (`architecture:component-theming-surface` INV6). A read-only or disabled row paints no fill and reflects no state; its targets match unchecked rows. | `architecture:component-theming-surface/INV6` |
| FR16 | Shipped behavior, not a requirement until its open question is ruled: 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 (OQ3). | `architecture:public-component-api/INV5`; `INV9` for any retype or move |
| FR17 | Shipped behavior, not a requirement until its open question is ruled: 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 (OQ4). The item's own `onClick` still fires once per click (FR10). | Current source; shared clickable-container hook behavior |
| FR18 | Shipped behavior, not a requirement until its open question is ruled: 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 (OQ5). | the Chromium accessibility suite; `design:user-states` leaves hover and selection treatment outside its current claim |
@@ -215,7 +215,7 @@ durable constraints and their verification target.
| 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 (FR15, FR18) | Supporting | FR12 |
+| Checked-row fill | Supplements the checkbox state on enabled, editable checked rows. | row `selected` state (FR15); FR18 open | Supporting | FR12 |
| Spinner | Replaces the mark while the option is busy. | Spinner | Supporting | FR7 |
This record carries no anatomy-theming map. The composed option anatomy and its
@@ -256,7 +256,8 @@ and CheckboxListItem owns no target of its own.
| FR12, FR18 | `CheckboxList.a11y.chromium.spec.ts` `checked`, `hover-*`, and `pressed-*` cases | Light and dark; unchecked and checked | A missing or misplaced fill fails the row-paint check. Evidence gap: no assertion that `xstyle` composes after the fill. | `audit:CheckboxListItem/visual` |
| FR13, FR16 | `CheckboxList.test.tsx` ref and styling, data-testid, and ARIA cases | Row ref, class, style, data, ARIA | A dropped or misrouted input fails. Evidence gap: no test asserts `event.currentTarget` for `onClick` (FR16). | `audit:CheckboxListItem/api` |
| FR14 | `Checkbox.a11y.test.tsx` known failure `list-item-handlerless-read-only`; `CheckboxList.a11y.chromium.spec.ts` `handlerless` case | Standalone with `isChecked` and no `onCheck` | The recorded known failure stops matching when its gap closes. | `audit:CheckboxListItem/accessibility` |
-| FR15, FR19, AR5 | `CheckboxList.a11y.chromium.spec.ts` `focus-visible` and `forced-colors-focus` cases | Keyboard focus; forced colors | A lost focus indicator fails. Evidence gap: no test asserts the absent selection state (FR15) or counts focus indicators (FR19). | `audit:CheckboxListItem/visual` |
+| FR15 | `CheckboxList.test.tsx` checked-row state case | checked, unchecked, read-only and disabled rows | A checked, enabled, editable row without `selected` on its row targets fails; a read-only or disabled row with it fails | current source |
+| FR19, AR5 | `CheckboxList.a11y.chromium.spec.ts` `focus-visible` and `forced-colors-focus` cases | Keyboard focus; forced colors | A lost focus indicator fails. Evidence gap: no test counts focus indicators (FR19). | `audit:CheckboxListItem/visual` |
| Direction | RTL audit target `core-checkboxlist--rich-descriptions` (`apps/storybook/rtl-audit/targets.json`); `CheckboxList.a11y.chromium.spec.ts` `rtl` case | LTR and RTL | The checkbox and end content fail to swap inline order. | `audit:CheckboxListItem/layout` |
| ORD1–ORD4, PR1 | Covered by the FR4–FR10 and FR13 rows. Evidence gap: no test asserts the absence of observers, timers, or global listeners | — | — | `audit:CheckboxListItem/behavior` |
@@ -269,8 +270,6 @@ and CheckboxListItem owns no target of its own.
- **Mixed state after activation (FR5).** A standalone mixed item whose value
stays mixed loses its native mixed state on activation, as
`component:CheckboxInput` records.
-- **Checked-row state (FR15).** No selection state is reflected on the row
- targets, against `architecture:component-theming-surface` INV6.
- **Two focus indicators (FR19).** Keyboard focus paints both the row outline
and the checkbox ring, against `architecture:interaction-modality` INV3.
@@ -284,8 +283,6 @@ No component-local decision. CheckboxListItem applies `spec:AST-021` and
- **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
diff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsx
index 2f4daee7b8..52bb65e21f 100644
--- a/packages/core/src/CheckboxList/CheckboxList.test.tsx
+++ b/packages/core/src/CheckboxList/CheckboxList.test.tsx
@@ -92,6 +92,48 @@ describe('CheckboxList', () => {
);
});
+ it('reflects a checked row as selected on its row targets, so a theme can restyle checked rows (FR15)', () => {
+ render(
+ <>
+ <CheckboxList label="Toppings" value={['cheese']} onChange={() => {}}>
+ <CheckboxListItem
+ label="Cheese"
+ value="cheese"
+ data-testid="cheese"
+ />
+ <CheckboxListItem
+ label="Olives"
+ value="olives"
+ data-testid="olives"
+ />
+ </CheckboxList>
+ <CheckboxList
+ label="Locked"
+ value={['ham']}
+ onChange={() => {}}
+ isReadOnly>
+ <CheckboxListItem label="Ham" value="ham" data-testid="ham" />
+ </CheckboxList>
+ <CheckboxList
+ label="Off"
+ value={['egg']}
+ onChange={() => {}}
+ isDisabled>
+ <CheckboxListItem label="Egg" value="egg" data-testid="egg" />
+ </CheckboxList>
+ </>,
+ );
+ const cheese = screen.getByTestId('cheese');
+ expect(cheese).toHaveClass('astryx-item');
+ expect(cheese).toHaveClass('astryx-list-item');
+ expect(cheese).toHaveAttribute('data-selected', 'selected');
+ expect(screen.getByTestId('olives')).not.toHaveAttribute('data-selected');
+ // The state follows the checked-row fill, which a read-only or disabled
+ // row does not paint.
+ expect(screen.getByTestId('ham')).not.toHaveAttribute('data-selected');
+ expect(screen.getByTestId('egg')).not.toHaveAttribute('data-selected');
+ });
+
it('renders with label', () => {
render(
<CheckboxList label="Preferences" value={[]} onChange={() => {}}>
diff --git a/packages/core/src/CheckboxList/CheckboxListItem.tsx b/packages/core/src/CheckboxList/CheckboxListItem.tsx
index 08279a1d22..0175d4e7ed 100644
--- a/packages/core/src/CheckboxList/CheckboxListItem.tsx
+++ b/packages/core/src/CheckboxList/CheckboxListItem.tsx
@@ -36,6 +36,7 @@ import {CheckboxListContext} from './CheckboxListContext';
import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';
import {joinAriaIDs} from '../utils/inputAria';
import {useMergedRefs} from '../hooks/useMergedRefs';
+import {themeDataAttributes} from '../utils/themeProps';
import type {ItemAlign} from '../Item';
import {
registerEnglishFallback,
@@ -352,9 +353,14 @@ export function CheckboxListItem({
}
};
+ // The state follows the fill, so a theme can restyle the text on it.
+ const isCheckedRow =
+ resolvedChecked === true && !effectiveDisabled && !effectiveReadOnly;
+
return (
<ListItem
{...restProps}
+ {...themeDataAttributes({selected: isCheckedRow ? 'selected' : null})}
ref={ref}
label={namesFromVisibleLabel ? <span id={labelID}>{label}</span> : label}
description={description}
@@ -376,10 +382,7 @@ export function CheckboxListItem({
// at that strength. So the row brings the release back, and the box
// fades with the row.
rowOwnsPress && interactionOverlayStyles.pressedAlpha,
- resolvedChecked === true &&
- !effectiveDisabled &&
- !effectiveReadOnly &&
- styles.selected,
+ isCheckedRow && styles.selected,
xstyle,
] as StyleXStyles
}