Skip to content

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.md
new file mode 100644
index 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.
+
+@Kyujenius
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.test.tsx b/packages/core/src/CheckboxInput/CheckboxInput.test.tsx
index 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(
<CheckboxInput
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.tsx b/packages/core/src/CheckboxInput/CheckboxInput.tsx
index 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.ts
index 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.ts
index 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.tsx
index 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(
<CheckboxList
diff --git a/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs b/packages/core/src/CheckboxList/CheckboxListItem.doc.mjs
index 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.tsx
index 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
+ <DescribedCheckboxInput
ref={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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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';