An open source design system that's fully customizable and agent ready
TypeScript
fix(CheckboxListItem): expose the description to the checkbox via aria-describedby (#6190)
홍규진1ea48bc762c2
diff --git a/.changeset/checkbox-list-item-description.md b/.changeset/checkbox-list-item-description.mdnew file mode 100644index 0000000000..091bc50c94--- /dev/null+++ b/.changeset/checkbox-list-item-description.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] CheckboxListItem: the visible `description` is now the checkbox's accessible description, so the browser computes a distinct description instead of none. Item ids the description element it already renders and publishes that id to the content it renders in a slot, which keeps a plain string description's automatic single-line truncation. CheckboxInput now merges a consumer-supplied `aria-describedby` with its own description, status, and disabled-reason ids rather than replacing it. No public API changes.++@Kyujeniusdiff --git a/packages/core/src/CheckboxInput/CheckboxInput.test.tsx b/packages/core/src/CheckboxInput/CheckboxInput.test.tsxindex 2e5860aff4..547546b58b 100644--- a/packages/core/src/CheckboxInput/CheckboxInput.test.tsx+++ b/packages/core/src/CheckboxInput/CheckboxInput.test.tsx@@ -268,6 +268,27 @@ describe('CheckboxInput', () => {expect(checkbox.getAttribute('aria-describedby')).toContain(description.id);});+ it('merges a consumer aria-describedby with its own description id', () => {+ render(+ <>+ <span id="row-hint">Hint from the row</span>+ <CheckboxInput+ label="Select row"+ isLabelHidden+ description="Selects this row for bulk actions"+ aria-describedby="row-hint"+ value={false}+ onChange={() => {}}+ />+ </>,+ );+ const checkbox = screen.getByRole('checkbox');+ const description = screen.getByText('Selects this row for bulk actions');+ const ids = checkbox.getAttribute('aria-describedby')!.split(' ');+ expect(ids).toContain('row-hint');+ expect(ids).toContain(description.id);+ });+it('shows label visually by default', () => {render(<CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,@@ -415,6 +436,27 @@ describe('CheckboxInput', () => {expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();});+ it('keeps a consumer aria-describedby alongside the reason tooltip', () => {+ render(+ <>+ <span id="terms-hint">Required before checkout</span>+ <CheckboxInput+ label="Accept terms"+ value={false}+ onChange={() => {}}+ isDisabled+ disabledMessage="Terms are managed by your administrator"+ aria-describedby="terms-hint"+ />+ </>,+ );+ const checkbox = screen.getByRole('checkbox');+ const tooltip = screen.getByRole('tooltip', h);+ const ids = checkbox.getAttribute('aria-describedby')!.split(' ');+ expect(ids).toContain('terms-hint');+ expect(ids).toContain(tooltip.id);+ });+it('does not render a tooltip when disabled without a reason', () => {render(<CheckboxInputdiff --git a/packages/core/src/CheckboxInput/CheckboxInput.tsx b/packages/core/src/CheckboxInput/CheckboxInput.tsxindex c565e31e51..81d4c75696 100644--- a/packages/core/src/CheckboxInput/CheckboxInput.tsx+++ b/packages/core/src/CheckboxInput/CheckboxInput.tsx@@ -287,6 +287,7 @@ export function CheckboxInput({className,style,ref,+ 'aria-describedby': ariaDescribedByProp,...rest}: CheckboxInputProps) {const id = useId();@@ -353,7 +354,13 @@ export function CheckboxInput({// Only include descriptionID when the element actually renders.// FieldLabel renders the description (with descriptionID) even when the// label is visually hidden — it's sr-only, so keep it linked.+ // A consumer's own `aria-describedby` (CheckboxListItem points the control+ // at its visible row description) comes first, then the input's own ids —+ // the explicit attribute below would otherwise replace it via `...rest`.const describedByParts: string[] = [];+ if (ariaDescribedByProp) {+ describedByParts.push(ariaDescribedByProp);+ }if (description) {describedByParts.push(descriptionID);}diff --git a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.known-failures.ts b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.known-failures.tsindex 364a8d6a89..c8108f375a 100644--- a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.known-failures.ts+++ b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.known-failures.ts@@ -12,32 +12,6 @@import type {KnownFailure} from '@astryxdesign/a11y-spec';export const CHECKBOX_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [- {- expectation: 'checkbox.description.resolvable',- binding: 'CheckboxListItem',- state: 'list-item-described',- evidenceLayer: 'dom',- failureEquals:- 'the binding renders supporting text for this state, but the checkbox has no aria-describedby, so the text is never attached to the control',- standardsReference: 'WCAG 2.2 1.3.1 Info and Relationships (Level A)',- userImpact:- 'The browser accessibility node exposes no separate description for the visible supporting text, so downstream accessibility consumers cannot distinguish it as the choice explanation.',- reason:- 'CheckboxListItem renders its description in the ListItem row but does not pass or reference that content from the nested CheckboxInput. The migration records the gap without changing component behavior.',- },- {- expectation: 'checkbox.description.exposed',- binding: 'CheckboxListItem',- state: 'list-item-described',- evidenceLayer: 'accessibility-tree',- failureEquals:- 'the binding expects the description "Receive notifications by email", but the browser computes no accessible description',- standardsReference: 'WCAG 2.2 4.1.2 Name, Role, Value (Level A)',- userImpact:- 'The browser computes no distinct description for the visible explanation; this records browser exposure only, not what any assistive technology announces.',- reason:- 'This is the accessibility-tree face of the missing relationship recorded above. It is separate because each known failure names exactly one expectation and layer.',- },{expectation: 'checkbox.readonly.declared',binding: 'CheckboxInput',diff --git a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.states.tsindex e22aadc82d..b003eb7878 100644--- a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts+++ b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.states.ts@@ -255,9 +255,6 @@ export const CHECKBOX_BINDING_STATES = [visibleLabel: 'Email',visibleLabelSelector: '[data-a11y-visible-label]',storyId: 'a11y-checkbox-pattern--list-item-described',- declaredNotDelivered: [- {fact: 'description', owned: 'checkbox.description.resolvable'},- ],},{id: 'list-item-rich-label-visible-name',diff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsxindex 1b14c4a870..98bb90c7b8 100644--- a/packages/core/src/CheckboxList/CheckboxList.test.tsx+++ b/packages/core/src/CheckboxList/CheckboxList.test.tsx@@ -386,6 +386,57 @@ describe('CheckboxList', () => {expect(onChange).not.toHaveBeenCalled();});+ it('exposes a string description to the checkbox via aria-describedby', () => {+ render(+ <List>+ <CheckboxListItem+ label="Email"+ description="Receive notifications by email"+ />+ </List>,+ );+ const checkbox = screen.getByRole('checkbox', {name: 'Email'});+ const ids = checkbox.getAttribute('aria-describedby');+ expect(ids).not.toBeNull();+ const target = document.getElementById(ids!);+ expect(target).toHaveTextContent('Receive notifications by email');+ });++ it('exposes a ReactNode description to the checkbox via aria-describedby', () => {+ render(+ <List>+ <CheckboxListItem+ label="Pro plan"+ description={+ <span>+ See the <a href="#pricing">pricing page</a>+ </span>+ }+ />+ </List>,+ );+ const checkbox = screen.getByRole('checkbox', {name: 'Pro plan'});+ const target = document.getElementById(+ checkbox.getAttribute('aria-describedby')!,+ );+ expect(target).toHaveTextContent('See the pricing page');+ });++ it('adds no aria-describedby when the description is absent or empty', () => {+ render(+ <List>+ <CheckboxListItem label="Plain" />+ <CheckboxListItem label="Empty" description="" />+ <CheckboxListItem label="False" description={false} />+ </List>,+ );+ for (const name of ['Plain', 'Empty', 'False']) {+ expect(screen.getByRole('checkbox', {name})).not.toHaveAttribute(+ 'aria-describedby',+ );+ }+ });+it('renders description on the checkbox list group', () => {render(<CheckboxListdiff --git a/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs b/packages/core/src/CheckboxList/CheckboxListItem.doc.mjsindex 7d03534bf9..f7111b81a1 100644--- a/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs+++ b/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs@@ -31,7 +31,8 @@ export const docs = {{name: 'description',type: 'ReactNode',- description: 'Secondary content below the label. String or ReactNode.',+ description:+ "Secondary content below the label. String or ReactNode. Exposed as the checkbox's accessible description through aria-describedby, so assistive technology can tell it is the explanation for that choice.",},{name: 'endContent',@@ -117,7 +118,8 @@ export const docsZh = {{name: 'description',type: 'ReactNode',- description: '标签下方的辅助内容。可为字符串或 ReactNode。',+ description:+ '标签下方的辅助内容。可为字符串或 ReactNode。会通过 aria-describedby 作为复选框的无障碍描述暴露,便于辅助技术识别它是该选项的说明。',},{name: 'endContent',@@ -162,7 +164,8 @@ export const docsDense = {'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).',- description: 'Secondary content below label. String or ReactNode.',+ 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.',isLoading:diff --git a/packages/core/src/CheckboxList/CheckboxListItem.tsx b/packages/core/src/CheckboxList/CheckboxListItem.tsxindex d9281d778b..0e32fdbf49 100644--- a/packages/core/src/CheckboxList/CheckboxListItem.tsx+++ b/packages/core/src/CheckboxList/CheckboxListItem.tsx@@ -22,10 +22,12 @@ import type {StyleXStyles} from '@stylexjs/stylex';import {colorVars} from '../theme/tokens.stylex';import type {BaseProps} from '../BaseProps';import {CheckboxInput} from '../CheckboxInput/CheckboxInput';+import type {CheckboxInputProps} from '../CheckboxInput/CheckboxInput';import {ListItem} from '../List/ListItem';import {ListContext} from '../List/ListContext';import {CheckboxListContext} from './CheckboxListContext';import {useTranslator} from '../i18n';+import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';// =============================================================================// Styles@@ -85,6 +87,9 @@ export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {value?: string;/*** Secondary content below the label. Accepts a plain string or a ReactNode.+ * Exposed as the checkbox's accessible description through+ * `aria-describedby`, so assistive technology can tell it is the explanation+ * for this choice rather than unrelated row text.*/description?: ReactNode;/**@@ -124,6 +129,28 @@ export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {// Component// =============================================================================+/**+ * The row's visible description is the checkbox's accessible description. Item+ * renders that element and owns its id, and publishes the id through+ * ItemDescriptionContext; this reads it from inside the slot Item renders. The+ * row cannot wrap the description in an id'd element instead — that turns a+ * plain string into a ReactNode and drops the single-line truncation ListItem+ * documents — and a public `descriptionId` prop would fail+ * `spec:AST-002/DEC-1`, since the caller decides nothing Item cannot derive.+ *+ * This component owns `aria-describedby`, so the prop is omitted rather than+ * accepted and overwritten: a caller passing one would otherwise lose the id+ * silently.+ */+function DescribedCheckboxInput(+ props: Omit<CheckboxInputProps, 'aria-describedby'>,+) {+ const describedBy = use(ItemDescriptionContext);+ return (+ <CheckboxInput {...props} aria-describedby={describedBy ?? undefined} />+ );+}+/*** A checkbox item for use within CheckboxList (collection mode)* or List (standalone mode).@@ -180,6 +207,7 @@ export function CheckboxListItem({const isRichLabel = typeof label !== 'string';const labelID = useId();const namesFromVisibleLabel = isRichLabel && ariaLabel == null;+const checkboxLabel =ariaLabel ??(isRichLabel ? t('@astryx.checkboxList.item.checkbox') : label);@@ -273,7 +301,7 @@ export function CheckboxListItem({className={className}style={style}startContent={- <CheckboxInput+ <DescribedCheckboxInputref={checkboxRef}label={checkboxLabel}aria-labelledby={namesFromVisibleLabel ? labelID : undefined}diff --git a/packages/core/src/Item/Item.test.tsx b/packages/core/src/Item/Item.test.tsxindex 19073919b3..fb6b794825 100644--- a/packages/core/src/Item/Item.test.tsx+++ b/packages/core/src/Item/Item.test.tsx@@ -9,11 +9,12 @@* SYNC: When Item component changes, update tests to match new behavior*/-import {useRef} from 'react';+import {use, useRef} from 'react';import {describe, it, expect, vi} from 'vitest';import {render, screen} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {Item} from './Item';+import {ItemDescriptionContext} from './ItemDescriptionContext';/*** Item in delegation mode: `interactiveRef` points at a nested control that@@ -43,6 +44,44 @@ describe('Item', () => {// Basic rendering// ===========================================================================+ it('ids the rendered description and publishes it to slot content', () => {+ function Probe() {+ const describedBy = use(ItemDescriptionContext);+ return <span data-testid="probe">{describedBy ?? 'none'}</span>;+ }+ render(+ <Item+ label="Email"+ description="Receive notifications by email"+ startContent={<Probe />}+ />,+ );+ const description = screen.getByText('Receive notifications by email');+ expect(description.id).not.toBe('');+ expect(screen.getByTestId('probe')).toHaveTextContent(description.id);+ // The string description stays Item's own element. Wrapping it to carry an+ // id would make it a ReactNode and drop the single-line truncation.+ expect(description.children).toHaveLength(0);+ });++ it('publishes no description id when the description renders nothing', () => {+ function Probe() {+ const describedBy = use(ItemDescriptionContext);+ return <span data-testid="probe">{describedBy ?? 'none'}</span>;+ }+ for (const description of ['', false] as const) {+ const {unmount} = render(+ <Item+ label="Email"+ description={description}+ startContent={<Probe />}+ />,+ );+ expect(screen.getByTestId('probe')).toHaveTextContent('none');+ unmount();+ }+ });+it('renders label text', () => {render(<Item label="Contact Name" />);expect(screen.getByText('Contact Name')).toBeInTheDocument();diff --git a/packages/core/src/Item/Item.tsx b/packages/core/src/Item/Item.tsxindex 36caacb1d3..2576d2746d 100644--- a/packages/core/src/Item/Item.tsx+++ b/packages/core/src/Item/Item.tsx@@ -16,7 +16,7 @@* - /packages/cli/assets/templates/blocks/components/Item/ (showcase blocks)*/-import {useRef, type ReactNode} from 'react';+import {useId, useRef, type ReactNode} from 'react';import * as stylex from '@stylexjs/stylex';import {colorVars,@@ -27,7 +27,8 @@ import {typeScaleVars,} from '../theme/tokens.stylex';import type {BaseProps} from '../BaseProps';-import {mergeProps} from '../utils';+import {isRenderable, mergeProps} from '../utils';+import {ItemDescriptionContext} from './ItemDescriptionContext';import {useMergedRefs} from '../hooks/useMergedRefs';import {computeTargetAndRel} from '../Link/computeTargetAndRel';import {useLinkComponent} from '../Link/useLinkComponent';@@ -441,6 +442,15 @@ export function Item({// that need selection semantics pass a permitted role.const allowsAriaSelected = role != null && ARIA_SELECTED_ROLES.has(role);+ // The description element's id, published through ItemDescriptionContext so a+ // control Item renders in a slot can point at it with `aria-describedby`.+ // `isRenderable` rather than `!= null` so the common empty values — `null`,+ // `undefined`, `false`, `''` — publish no id and leave a consumer with no+ // dangling reference. It is a shallow check: content that renders nothing+ // only once React runs it, such as an empty fragment, still publishes an id.+ const descriptionID = useId();+ const hasRenderableDescription = isRenderable(description);+const isStringLabel = typeof label === 'string';const isStringDescription = typeof description === 'string';@@ -481,6 +491,7 @@ export function Item({</span>{description != null && (<span+ id={hasRenderableDescription ? descriptionID : undefined}{...stylex.props(styles.description,isInline && styles.inlineDescription,@@ -616,7 +627,10 @@ export function Item({? handleContainerClick: undefined}>- {innerContent}+ <ItemDescriptionContext+ value={hasRenderableDescription ? descriptionID : null}>+ {innerContent}+ </ItemDescriptionContext></Component>);}diff --git a/packages/core/src/Item/ItemDescriptionContext.tsx b/packages/core/src/Item/ItemDescriptionContext.tsxnew file mode 100644index 0000000000..141cd4f620--- /dev/null+++ b/packages/core/src/Item/ItemDescriptionContext.tsx@@ -0,0 +1,29 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file ItemDescriptionContext.tsx+ * @input Uses React createContext+ * @output Exports ItemDescriptionContext+ * @position Internal seam between Item and a control it renders in a slot+ *+ * Item renders the row's description and owns the element that holds it. A+ * control Item renders in a slot — the checkbox in CheckboxListItem, for+ * example — has to point at that element with `aria-describedby`, and only+ * Item knows its id.+ *+ * Publishing the id here keeps that wiring internal. The alternative, a public+ * `descriptionId` prop, would fail `spec:AST-002/DEC-1`: the caller decides+ * nothing, and Item can derive the id itself. Wrapping the description in an+ * id'd element instead would turn a plain string into a ReactNode and drop the+ * single-line truncation ListItem documents.+ *+ * `null` when the row renders no description, so a consumer adds no dangling+ * `aria-describedby`.+ */++import {createContext} from 'react';++export const ItemDescriptionContext = createContext<string | null>(null);+ItemDescriptionContext.displayName = 'ItemDescriptionContext';