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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/docs/specs/components/CheckboxList/CheckboxList.spec.md b/docs/specs/components/CheckboxList/CheckboxList.spec.mdindex 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 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 (`component:CheckboxListItem` FR15).+row surface and, on a checked, enabled, editable row, its `selected` state+(`component:CheckboxListItem` FR15).## Family and system relationshipsdiff --git a/docs/specs/components/CheckboxList/CheckboxListItem.spec.md b/docs/specs/components/CheckboxList/CheckboxListItem.spec.mdindex 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 valuestays 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 outlineand 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 ARIAreach the row while `onClick` runs on the checkbox under a row-typed handler.- **OQ4 — Should read-only item clicks propagate?** (`human-api`) No currentdiff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsxindex 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.tsxindex 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}