An open source design system that's fully customizable and agent ready
TypeScript
feat: XDSCheckboxList + XDSCheckboxListItem (#1127) (#1133)
Cindy Zhange71a59b71090
diff --git a/apps/storybook/stories/CheckboxList.stories.tsx b/apps/storybook/stories/CheckboxList.stories.tsxnew file mode 100644index 0000000000..bbd6b7ebb9--- /dev/null+++ b/apps/storybook/stories/CheckboxList.stories.tsx@@ -0,0 +1,416 @@+import {useState} from 'react';+import type {Meta, StoryObj} from '@storybook/react';+import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList';+import {XDSList} from '@xds/core/List';+import {XDSCard} from '@xds/core/Card';++const meta: Meta<typeof XDSCheckboxList> = {+ title: 'Form/XDSCheckboxList',+ component: XDSCheckboxList,+ tags: ['autodocs'],+ argTypes: {+ label: {+ control: 'text',+ description: 'Label text (required)',+ },+ isLabelHidden: {+ control: 'boolean',+ description:+ 'Visually hide the label (still accessible to screen readers)',+ },+ description: {+ control: 'text',+ description: 'Description text displayed below the label',+ },+ density: {+ control: 'select',+ options: ['compact', 'balanced', 'spacious'],+ description: 'Spacing density for list items',+ },+ hasDividers: {+ control: 'boolean',+ description: 'Whether to show dividers between items',+ },+ isDisabled: {+ control: 'boolean',+ description: 'Whether all checkbox items are disabled',+ },+ },+};++export default meta;+type Story = StoryObj<typeof XDSCheckboxList>;++export const Default: Story = {+ render: args => {+ const [value, setValue] = useState<string[]>(args.value ?? []);+ const {value: _value, onChange: _onChange, ...restArgs} = args;+ return (+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+ <XDSCheckboxListItem label="Push notification" value="push" />+ </XDSCheckboxList>+ );+ },+ args: {+ label: 'Notification preferences',+ },+};++export const WithDescriptions: Story = {+ render: args => {+ const [value, setValue] = useState<string[]>(args.value ?? []);+ const {value: _value, onChange: _onChange, ...restArgs} = args;+ return (+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>+ <XDSCheckboxListItem+ label="Email"+ value="email"+ description="Receive notifications via email"+ />+ <XDSCheckboxListItem+ label="SMS"+ value="sms"+ description="Standard messaging rates apply"+ />+ <XDSCheckboxListItem+ label="Push notification"+ value="push"+ description="Instant alerts on your device"+ />+ </XDSCheckboxList>+ );+ },+ args: {+ label: 'Notification preferences',+ description: 'Choose how you would like to be notified',+ hasDividers: true,+ },+};++export const DynamicItems: Story = {+ render: args => {+ const items = [+ {id: 'react', label: 'React'},+ {id: 'vue', label: 'Vue'},+ {id: 'angular', label: 'Angular'},+ {id: 'svelte', label: 'Svelte'},+ ];+ const [value, setValue] = useState<string[]>(['react']);+ const {value: _value, onChange: _onChange, ...restArgs} = args;+ return (+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>+ {items.map(item => (+ <XDSCheckboxListItem+ key={item.id}+ label={item.label}+ value={item.id}+ />+ ))}+ </XDSCheckboxList>+ );+ },+ args: {+ label: 'Frameworks',+ },+};++export const StandaloneMode: Story = {+ render: () => {+ const [accepted, setAccepted] = useState(false);+ const [subscribed, setSubscribed] = useState(true);+ const [marketing, setMarketing] = useState(false);+ return (+ <XDSList>+ <XDSCheckboxListItem+ label="Accept terms and conditions"+ isChecked={accepted}+ onCheck={setAccepted}+ />+ <XDSCheckboxListItem+ label="Subscribe to newsletter"+ description="Weekly updates about new features"+ isChecked={subscribed}+ onCheck={setSubscribed}+ />+ <XDSCheckboxListItem+ label="Receive marketing emails"+ isChecked={marketing}+ onCheck={setMarketing}+ />+ </XDSList>+ );+ },+};++export const ReadOnly: Story = {+ render: () => (+ <XDSList>+ <XDSCheckboxListItem label="Completed task" isChecked={true} />+ <XDSCheckboxListItem label="Pending task" isChecked={false} />+ <XDSCheckboxListItem label="In progress" isChecked="indeterminate" />+ </XDSList>+ ),+};++export const SelectAllWithIndeterminate: Story = {+ render: () => {+ const allItems = ['email', 'sms', 'push'];+ const [selected, setSelected] = useState<string[]>(['email']);++ const allChecked = allItems.every(item => selected.includes(item));+ const noneChecked = selected.length === 0;+ const selectAllState = allChecked+ ? true+ : noneChecked+ ? false+ : ('indeterminate' as const);++ const handleSelectAll = (checked: boolean) => {+ if (checked) {+ setSelected([...allItems]);+ } else {+ setSelected([]);+ }+ };++ return (+ <XDSCheckboxList label="Notifications" hasDividers>+ <XDSCheckboxListItem+ label="Select all"+ isChecked={selectAllState}+ onCheck={handleSelectAll}+ />+ {allItems.map(item => (+ <XDSCheckboxListItem+ key={item}+ label={item.charAt(0).toUpperCase() + item.slice(1)}+ isChecked={selected.includes(item)}+ onCheck={checked => {+ setSelected(prev =>+ checked ? [...prev, item] : prev.filter(v => v !== item),+ );+ }}+ />+ ))}+ </XDSCheckboxList>+ );+ },+};++export const Disabled: Story = {+ render: args => {+ const [value, setValue] = useState<string[]>(['email']);+ const {value: _value, onChange: _onChange, ...restArgs} = args;+ return (+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+ <XDSCheckboxListItem label="Push notification" value="push" />+ </XDSCheckboxList>+ );+ },+ args: {+ label: 'Notification preferences',+ isDisabled: true,+ },+};++export const DisabledItem: Story = {+ render: args => {+ const [value, setValue] = useState<string[]>([]);+ const {value: _value, onChange: _onChange, ...restArgs} = args;+ return (+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" isDisabled />+ <XDSCheckboxListItem label="Push notification" value="push" />+ </XDSCheckboxList>+ );+ },+ args: {+ label: 'Notification preferences',+ },+};++export const WithErrorStatus: Story = {+ render: args => {+ const [value, setValue] = useState<string[]>([]);+ const {value: _value, onChange: _onChange, ...restArgs} = args;+ return (+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+ <XDSCheckboxListItem label="Push notification" value="push" />+ </XDSCheckboxList>+ );+ },+ args: {+ label: 'Notification preferences',+ status: {+ type: 'error',+ message: 'Please select at least one notification method',+ },+ },+};++export const WithEndContent: Story = {+ render: args => {+ const [value, setValue] = useState<string[]>(['free']);+ const {value: _value, onChange: _onChange, ...restArgs} = args;+ return (+ <XDSCheckboxList {...restArgs} value={value} onChange={setValue}>+ <XDSCheckboxListItem+ label="Free tier"+ value="free"+ description="Basic features included"+ endContent={<span style={{color: '#0D8626'}}>$0/mo</span>}+ />+ <XDSCheckboxListItem+ label="Pro tier"+ value="pro"+ description="Advanced features"+ endContent={<span style={{color: '#0064E0'}}>$9/mo</span>}+ />+ <XDSCheckboxListItem+ label="Enterprise"+ value="enterprise"+ description="Custom solutions"+ endContent={<span style={{color: '#5B08D8'}}>Custom</span>}+ />+ </XDSCheckboxList>+ );+ },+ args: {+ label: 'Add-on packages',+ hasDividers: true,+ },+};++export const AllVariations: Story = {+ render: () => {+ const [value1, setValue1] = useState<string[]>([]);+ const [value2, setValue2] = useState<string[]>(['email']);+ const [standalone1, setStandalone1] = useState(false);+ const [standalone2, setStandalone2] = useState(true);+ return (+ <div+ style={{+ display: 'flex',+ flexDirection: 'column',+ gap: '24px',+ maxWidth: '400px',+ }}>+ <XDSCheckboxList label="Unselected" value={value1} onChange={setValue1}>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+ </XDSCheckboxList>+ <XDSCheckboxList+ label="Pre-selected"+ value={value2}+ onChange={setValue2}>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+ </XDSCheckboxList>+ <XDSCheckboxList+ label="Disabled group"+ value={['a']}+ onChange={() => {}}+ isDisabled>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+ </XDSCheckboxList>+ <XDSCheckboxList+ label="With descriptions"+ value={value1}+ onChange={setValue1}+ hasDividers>+ <XDSCheckboxListItem+ label="Email"+ value="email"+ description="Delivered to your inbox"+ />+ <XDSCheckboxListItem+ label="SMS"+ value="sms"+ description="Standard rates apply"+ />+ </XDSCheckboxList>+ <XDSCheckboxList+ label="With error"+ value={[]}+ onChange={() => {}}+ status={{+ type: 'error',+ message: 'Please select at least one option',+ }}>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+ </XDSCheckboxList>+ <div>+ <h4 style={{margin: '0 0 8px'}}>Standalone mode</h4>+ <XDSList>+ <XDSCheckboxListItem+ label="Accept terms"+ isChecked={standalone1}+ onCheck={setStandalone1}+ />+ <XDSCheckboxListItem+ label="Subscribe"+ isChecked={standalone2}+ onCheck={setStandalone2}+ />+ </XDSList>+ </div>+ </div>+ );+ },+};++export const InsideCard: Story = {+ render() {+ const [selected, setSelected] = useState<string[]>(['email']);+ return (+ <div style={{maxWidth: 400}}>+ <XDSCard>+ <XDSCheckboxList+ label="Notifications"+ description="Choose how to be notified"+ value={selected}+ onChange={setSelected}>+ <XDSCheckboxListItem+ value="email"+ label="Email"+ description="Weekly digest"+ />+ <XDSCheckboxListItem value="push" label="Push notifications" />+ <XDSCheckboxListItem value="sms" label="SMS" isDisabled />+ </XDSCheckboxList>+ </XDSCard>+ </div>+ );+ },+};++export const InsideCardWithDividers: Story = {+ render() {+ const [selected, setSelected] = useState<string[]>(['admin']);+ return (+ <div style={{maxWidth: 400}}>+ <XDSCard>+ <XDSCheckboxList+ label="Assign Roles"+ value={selected}+ onChange={setSelected}+ hasDividers>+ <XDSCheckboxListItem value="admin" label="Admin" />+ <XDSCheckboxListItem value="editor" label="Editor" />+ <XDSCheckboxListItem value="viewer" label="Viewer" />+ <XDSCheckboxListItem value="guest" label="Guest" />+ </XDSCheckboxList>+ </XDSCard>+ </div>+ );+ },+};diff --git a/packages/core/package.json b/packages/core/package.jsonindex c5afc03800..018897e28c 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -94,6 +94,12 @@"import": "./dist/CheckboxInput/index.mjs","require": "./dist/CheckboxInput/index.js"},+ "./CheckboxList": {+ "source": "./src/CheckboxList/index.ts",+ "types": "./dist/CheckboxList/index.d.ts",+ "import": "./dist/CheckboxList/index.mjs",+ "require": "./dist/CheckboxList/index.js"+ },"./CodeBlock": {"source": "./src/CodeBlock/index.ts","types": "./dist/CodeBlock/index.d.ts",diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsxindex a1be6b22b0..7046cc4603 100644--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx@@ -130,16 +130,15 @@ const styles = stylex.create({'@media (hover: hover)': colorVars['--color-border'],},},+ },+ checkboxDisabledUnchecked: {backgroundColor: {- default: 'unset',+ default: colorVars['--color-background-muted'],[stylex.when.ancestor(':hover')]: {- '@media (hover: hover)': 'unset',+ '@media (hover: hover)': colorVars['--color-background-muted'],},},},- checkboxDisabledUnchecked: {- backgroundColor: colorVars['--color-background-muted'],- },checkmark: {display: 'none',color: colorVars['--color-on-accent'],diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjsnew file mode 100644index 0000000000..565e3c6b29--- /dev/null+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs@@ -0,0 +1,576 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'CheckboxList',+ description:+ 'A checkbox group component for multi-value selection from a list of options. Supports collection mode (parent-managed state) and standalone mode (per-item state).',+ keywords: ["checkboxlist","checkbox","checkboxgroup","multichoice","multiselect","checklist"],+ features: [+ 'Accessible — uses native <input type="checkbox"> with proper ARIA attributes',+ 'Collection mode — parent manages selected values as string[], items derive checked state',+ 'Standalone mode — individual items use isChecked/onCheck for independent control',+ 'Density — compact, balanced, spacious via XDSList integration',+ 'Dividers — optional border dividers between items',+ 'Indeterminate — supports three-state checkbox (true, false, indeterminate) in standalone mode',+ 'Descriptions — optional secondary text per item',+ 'End content — slot for badges, actions, or other content after the label',+ 'Disabled state — supports disabling the entire group or individual items',+ 'Async actions — onChangeAction with optimistic updates and busy state',+ 'Full-row click — clicking anywhere on the row toggles the checkbox',+ 'Field integration — uses XDSField for label, description, and status messaging',+ ],+ examples: [+ {+ label: 'Basic collection mode',+ code: `<XDSCheckboxList+ label="Notifications"+ value={selected}+ onChange={setSelected}+>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+ <XDSCheckboxListItem label="Push" value="push" />+</XDSCheckboxList>`,+ },+ {+ label: 'With descriptions',+ code: `<XDSCheckboxList+ label="Preferences"+ value={selected}+ onChange={setSelected}+ hasDividers+>+ <XDSCheckboxListItem+ label="Email"+ value="email"+ description="Receive notifications via email"+ />+ <XDSCheckboxListItem+ label="SMS"+ value="sms"+ description="Standard messaging rates apply"+ />+</XDSCheckboxList>`,+ },+ {+ label: 'Standalone mode',+ code: `<XDSList>+ <XDSCheckboxListItem+ label="Accept terms"+ isChecked={accepted}+ onCheck={setAccepted}+ />+ <XDSCheckboxListItem+ label="Subscribe to newsletter"+ isChecked={subscribed}+ onCheck={setSubscribed}+ />+</XDSList>`,+ },+ {+ label: 'With status',+ code: `<XDSCheckboxList+ label="Required selections"+ value={selected}+ onChange={setSelected}+ status={{ type: 'error', message: 'Please select at least one option' }}+>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+</XDSCheckboxList>`,+ },+ {+ label: 'Disabled group',+ code: `<XDSCheckboxList+ label="Locked selections"+ value={['email']}+ onChange={() => {}}+ isDisabled+>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+</XDSCheckboxList>`,+ },+ ],+ theming: {+ targets: [+ {className: 'xds-checkbox-list-item'},+ ],+ },+ notes: [+ 'XDSCheckboxList composes XDSField (label, description, status) and XDSList (density, dividers)',+ 'XDSCheckboxListItem can be used inside XDSCheckboxList (collection mode) or XDSList (standalone mode)',+ 'In collection mode, XDSCheckboxListItem requires a `value` prop — throws if missing',+ 'Uses XDSCheckboxInput internally with isLabelHidden for the checkbox visual',+ 'Full-row click target with guard against interactive endContent children',+ 'Async actions use useOptimistic + useTransition for immediate visual feedback',+ 'Density maps to checkbox size: compact → sm, balanced/spacious → md',+ ],+ components: [+ {+ name: 'XDSCheckboxList',+ description:+ 'Checkbox group container with field integration for label, description, and status.',+ examples: [+ {+ label: 'Basic',+ code: `<XDSCheckboxList label="Notifications" value={selected} onChange={setSelected}>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+</XDSCheckboxList>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ 'Label text for the checkbox group (always rendered for accessibility).',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'XDSCheckboxListItem elements.',+ required: true,+ },+ {+ name: 'value',+ type: 'string[]',+ description: 'The currently selected values (collection mode).',+ },+ {+ name: 'onChange',+ type: '(values: string[]) => void',+ description: 'Callback fired when the selected values change.',+ },+ {+ name: 'onChangeAction',+ type: '(values: string[]) => void | Promise<void>',+ description: 'Async action on change with optimistic updates.',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: 'External loading state.',+ default: 'false',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Whether to visually hide the label.',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Description text displayed below the label.',+ },+ {+ name: 'density',+ type: "'compact' | 'balanced' | 'spacious'",+ description: 'Spacing density for list items.',+ default: "'balanced'",+ },+ {+ name: 'hasDividers',+ type: 'boolean',+ description: 'Whether to show dividers between items.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether all checkbox items are disabled.',+ default: 'false',+ },+ {+ name: 'status',+ type: 'XDSInputStatus',+ description: 'Status indicator ({ type, message }).',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ },+ {+ name: 'XDSCheckboxListItem',+ description:+ 'Individual checkbox item with label, description, and end content slot. Works in collection mode (inside XDSCheckboxList) or standalone mode (inside XDSList).',+ examples: [+ {+ label: 'Collection mode',+ code: `<XDSCheckboxListItem label="Email" value="email" />`,+ },+ {+ label: 'Standalone mode',+ code: `<XDSCheckboxListItem+ label="Accept terms"+ isChecked={accepted}+ onCheck={setAccepted}+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Primary text label for the item.',+ required: true,+ },+ {+ name: 'value',+ type: 'string',+ description: 'Identity key (required inside XDSCheckboxList).',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Secondary text below the label.',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description: 'Content rendered after the label area.',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether this individual item is disabled.',+ default: 'false',+ },+ {+ name: 'isChecked',+ type: "boolean | 'indeterminate'",+ description: 'Direct checked state (standalone mode only).',+ },+ {+ name: 'onCheck',+ type: '(checked: boolean) => void',+ description: 'Direct check handler (standalone mode only).',+ },+ ],+ },+ ],+};++/** @type {import('../docs-types').ComponentDoc} */+export const docsZh = {+ name: 'CheckboxList',+ description:+ '用于从选项列表中进行多值选择的复选框组组件。支持集合模式(父组件管理状态)和独立模式(逐项状态)。',+ features: [+ '无障碍 - 使用原生 <input type="checkbox">,配合正确的 ARIA 属性',+ '集合模式 - 父组件将选中值管理为 string[],子项派生选中状态',+ '独立模式 - 各项使用 isChecked/onCheck 进行独立控制',+ '密度 - 通过 XDSList 集成支持紧凑、平衡、宽敞三种密度',+ '分隔线 - 列表项之间的可选边框分隔线',+ '不确定状态 - 独立模式下支持三态复选框(true、false、indeterminate)',+ '描述 - 每个选项可选的辅助文本',+ '尾部内容 - 标签后的徽章、操作或其他内容插槽',+ '禁用状态 - 支持禁用整个组或单个选项',+ '异步操作 - onChangeAction 配合乐观更新和忙碌状态',+ '全行点击 - 点击行中任意位置均可切换复选框',+ '字段集成 - 使用 XDSField 提供标签、描述和状态消息',+ ],+ examples: [+ {+ label: '基础集合模式',+ code: `<XDSCheckboxList+ label="Notifications"+ value={selected}+ onChange={setSelected}+>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+ <XDSCheckboxListItem label="Push" value="push" />+</XDSCheckboxList>`,+ },+ {+ label: '带描述',+ code: `<XDSCheckboxList+ label="Preferences"+ value={selected}+ onChange={setSelected}+ hasDividers+>+ <XDSCheckboxListItem+ label="Email"+ value="email"+ description="Receive notifications via email"+ />+ <XDSCheckboxListItem+ label="SMS"+ value="sms"+ description="Standard messaging rates apply"+ />+</XDSCheckboxList>`,+ },+ {+ label: '独立模式',+ code: `<XDSList>+ <XDSCheckboxListItem+ label="Accept terms"+ isChecked={accepted}+ onCheck={setAccepted}+ />+</XDSList>`,+ },+ {+ label: '带状态',+ code: `<XDSCheckboxList+ label="Required selections"+ value={selected}+ onChange={setSelected}+ status={{ type: 'error', message: 'Please select at least one option' }}+>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+</XDSCheckboxList>`,+ },+ {+ label: '禁用组',+ code: `<XDSCheckboxList+ label="Locked selections"+ value={['email']}+ onChange={() => {}}+ isDisabled+>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+</XDSCheckboxList>`,+ },+ ],+ theming: {+ targets: [+ {className: 'xds-checkbox-list-item'},+ ],+ },+ notes: [+ 'XDSCheckboxList 组合 XDSField(标签、描述、状态)和 XDSList(密度、分隔线)',+ 'XDSCheckboxListItem 可在 XDSCheckboxList(集合模式)或 XDSList(独立模式)内使用',+ '在集合模式下,XDSCheckboxListItem 需要 `value` 属性——缺失时会抛出错误',+ '内部使用带 isLabelHidden 的 XDSCheckboxInput 作为复选框视觉元素',+ '全行点击目标,带有对交互式尾部内容子元素的防护',+ '异步操作使用 useOptimistic + useTransition 实现即时视觉反馈',+ '密度映射到复选框尺寸:compact → sm,balanced/spacious → md',+ ],+ components: [+ {+ name: 'XDSCheckboxList',+ description:+ '复选框组容器,集成字段功能,支持标签、描述和状态。',+ examples: [+ {+ label: '基础用法',+ code: `<XDSCheckboxList label="Notifications" value={selected} onChange={setSelected}>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+</XDSCheckboxList>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description:+ '复选框组的标签文本(始终渲染以确保无障碍可访问性)。',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'XDSCheckboxListItem 元素。',+ required: true,+ },+ {+ name: 'value',+ type: 'string[]',+ description: '当前选中的值(集合模式)。',+ },+ {+ name: 'onChange',+ type: '(values: string[]) => void',+ description: '选中值变更时触发的回调函数。',+ },+ {+ name: 'onChangeAction',+ type: '(values: string[]) => void | Promise<void>',+ description: '变更时的异步操作,配合乐观更新。',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: '外部加载状态。',+ default: 'false',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: '是否在视觉上隐藏标签。',+ default: 'false',+ },+ {+ name: 'description',+ type: 'string',+ description: '显示在标签下方的描述文本。',+ },+ {+ name: 'density',+ type: "'compact' | 'balanced' | 'spacious'",+ description: '列表项的间距密度。',+ default: "'balanced'",+ },+ {+ name: 'hasDividers',+ type: 'boolean',+ description: '是否在选项之间显示分隔线。',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: '是否禁用所有复选框选项。',+ default: 'false',+ },+ {+ name: 'status',+ type: 'XDSInputStatus',+ description: '状态指示器({ type, message })。',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',+ },+ ],+ },+ {+ name: 'XDSCheckboxListItem',+ description:+ '单个复选框选项,包含标签、描述和尾部内容插槽。可在集合模式或独立模式下使用。',+ examples: [+ {+ label: '集合模式',+ code: `<XDSCheckboxListItem label="Email" value="email" />`,+ },+ {+ label: '独立模式',+ code: `<XDSCheckboxListItem+ label="Accept terms"+ isChecked={accepted}+ onCheck={setAccepted}+/>`,+ },+ ],+ props: [+ {+ name: 'label',+ type: 'string',+ description: '选项的主要文本标签。',+ required: true,+ },+ {+ name: 'value',+ type: 'string',+ description: '标识键(在 XDSCheckboxList 内为必填)。',+ },+ {+ name: 'description',+ type: 'string',+ description: '标签下方的辅助文本。',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description: '在标签区域后渲染的内容。',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: '是否禁用此单个选项。',+ default: 'false',+ },+ {+ name: 'isChecked',+ type: "boolean | 'indeterminate'",+ description: '直接选中状态(仅独立模式)。',+ },+ {+ name: 'onCheck',+ type: '(checked: boolean) => void',+ description: '直接选中处理器(仅独立模式)。',+ },+ ],+ },+ ],+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description:+ 'Checkbox group component for multi-value selection. Collection mode (parent state) + standalone mode (per-item state).',+ features: [+ 'Accessible; uses native <input type="checkbox"> w/ proper ARIA attributes',+ 'Collection mode; parent manages selected values as string[]',+ 'Standalone mode; items use isChecked/onCheck independently',+ 'Density; compact, balanced, spacious via XDSList',+ 'Dividers; optional border dividers between items',+ 'Indeterminate; three-state checkbox in standalone mode',+ 'End content; slot for badges/actions after label',+ 'Disabled state; group-level or individual',+ 'Async actions; onChangeAction w/ optimistic updates + busy state',+ 'Full-row click; toggles checkbox, guards interactive endContent',+ 'Field integration; XDSField for label, description, status',+ ],+ notes: [+ 'XDSCheckboxList composes XDSField (label, description, status) + XDSList (density, dividers)',+ 'XDSCheckboxListItem works inside XDSCheckboxList (collection) or XDSList (standalone)',+ 'Collection mode requires `value` prop on items; throws if missing',+ 'Uses XDSCheckboxInput w/ isLabelHidden for checkbox visual',+ 'Full-row click target w/ guard against interactive endContent children',+ 'Async uses useOptimistic + useTransition for immediate feedback',+ 'Density maps to checkbox size: compact → sm, balanced/spacious → md',+ ],+ components: [+ {+ name: 'XDSCheckboxList',+ description:+ 'Checkbox group container w/ field integration for label, description, status.',+ propDescriptions: {+ label: 'Label text for checkbox group (always rendered for accessibility).',+ children: 'XDSCheckboxListItem elements.',+ value: 'Currently selected values (collection mode).',+ onChange: 'Callback fired when selected values change.',+ onChangeAction: 'Async action on change w/ optimistic updates.',+ isLoading: 'External loading state.',+ isLabelHidden: 'Whether to visually hide label.',+ description: 'Description text below label.',+ density: 'Spacing density for list items.',+ hasDividers: 'Whether to show dividers between items.',+ isDisabled: 'Whether all checkbox items disabled.',+ status: 'Status indicator ({ type, message }).',+ xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',+ },+ },+ {+ name: 'XDSCheckboxListItem',+ description:+ 'Individual checkbox item w/ label, description, end content slot.',+ propDescriptions: {+ label: 'Primary text label for item.',+ value: 'Identity key (required inside XDSCheckboxList).',+ description: 'Secondary text below label.',+ endContent: 'Content rendered after label area.',+ isDisabled: 'Whether this individual item disabled.',+ isChecked: 'Direct checked state (standalone mode only).',+ onCheck: 'Direct check handler (standalone mode only).',+ },+ },+ ],+};diff --git a/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx b/packages/core/src/CheckboxList/XDSCheckboxList.test.tsxnew file mode 100644index 0000000000..81a0ae533f--- /dev/null+++ b/packages/core/src/CheckboxList/XDSCheckboxList.test.tsx@@ -0,0 +1,417 @@+/**+ * @file XDSCheckboxList.test.tsx+ * @input Uses vitest, @testing-library/react, XDSCheckboxList, XDSCheckboxListItem+ * @output Unit tests for XDSCheckboxList and XDSCheckboxListItem behavior+ * @position Testing; validates XDSCheckboxList.tsx and XDSCheckboxListItem.tsx implementation+ *+ * SYNC: When XDSCheckboxList.tsx or XDSCheckboxListItem.tsx changes, update tests to match new behavior+ */++import {describe, it, expect, vi} from 'vitest';+import {render, screen, fireEvent} from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import {XDSCheckboxList} from './XDSCheckboxList';+import {XDSCheckboxListItem} from './XDSCheckboxListItem';+import {XDSList} from '../List/XDSList';++describe('XDSCheckboxList', () => {+ it('renders with label', () => {+ render(+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>+ <XDSCheckboxListItem label="Option A" value="a" />+ </XDSCheckboxList>,+ );+ expect(screen.getByText('Preferences')).toBeInTheDocument();+ });++ it('renders checkbox items', () => {+ render(+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+ <XDSCheckboxListItem label="Option C" value="c" />+ </XDSCheckboxList>,+ );+ expect(screen.getAllByRole('checkbox')).toHaveLength(3);+ });++ it('checks the correct items based on value prop', () => {+ render(+ <XDSCheckboxList+ label="Preferences"+ value={['a', 'c']}+ onChange={() => {}}>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+ <XDSCheckboxListItem label="Option C" value="c" />+ </XDSCheckboxList>,+ );+ const checkboxes = screen.getAllByRole('checkbox');+ expect(checkboxes[0]).toBeChecked();+ expect(checkboxes[1]).not.toBeChecked();+ expect(checkboxes[2]).toBeChecked();+ });++ it('calls onChange with added value when checking an item', async () => {+ const user = userEvent.setup();+ const handleChange = vi.fn();+ render(+ <XDSCheckboxList+ label="Preferences"+ value={['a']}+ onChange={handleChange}>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+ </XDSCheckboxList>,+ );++ await user.click(screen.getByRole('checkbox', {name: 'Option B'}));+ expect(handleChange).toHaveBeenCalledTimes(1);+ expect(handleChange).toHaveBeenCalledWith(['a', 'b']);+ });++ it('calls onChange with removed value when unchecking an item', async () => {+ const user = userEvent.setup();+ const handleChange = vi.fn();+ render(+ <XDSCheckboxList+ label="Preferences"+ value={['a', 'b']}+ onChange={handleChange}>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+ </XDSCheckboxList>,+ );++ await user.click(screen.getByRole('checkbox', {name: 'Option A'}));+ expect(handleChange).toHaveBeenCalledWith(['b']);+ });++ it('disables all checkboxes when group isDisabled is true', () => {+ render(+ <XDSCheckboxList+ label="Preferences"+ value={[]}+ onChange={() => {}}+ isDisabled>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+ </XDSCheckboxList>,+ );+ const checkboxes = screen.getAllByRole('checkbox');+ expect(checkboxes[0]).toBeDisabled();+ expect(checkboxes[1]).toBeDisabled();+ });++ it('does not call onChange when group is disabled', () => {+ const handleChange = vi.fn();+ render(+ <XDSCheckboxList+ label="Preferences"+ value={[]}+ onChange={handleChange}+ isDisabled>+ <XDSCheckboxListItem label="Option A" value="a" />+ </XDSCheckboxList>,+ );++ // Use fireEvent since userEvent correctly blocks pointer-events: none+ fireEvent.click(screen.getByRole('checkbox', {name: 'Option A'}));+ expect(handleChange).not.toHaveBeenCalled();+ });++ it('disables individual item when item isDisabled is true', () => {+ render(+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" isDisabled />+ </XDSCheckboxList>,+ );+ const checkboxes = screen.getAllByRole('checkbox');+ expect(checkboxes[0]).not.toBeDisabled();+ expect(checkboxes[1]).toBeDisabled();+ });++ it('throws when item has no value prop inside collection-mode XDSCheckboxList', () => {+ // Suppress console.error for expected error+ const spy = vi.spyOn(console, 'error').mockImplementation(() => {});+ expect(() => {+ render(+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>+ <XDSCheckboxListItem label="No value" />+ </XDSCheckboxList>,+ );+ }).toThrow(+ 'XDSCheckboxListItem requires a `value` prop when used inside XDSCheckboxList with a value array.',+ );+ spy.mockRestore();+ });++ it('renders error status message', () => {+ render(+ <XDSCheckboxList+ label="Preferences"+ value={[]}+ onChange={() => {}}+ status={{type: 'error', message: 'Select at least one'}}>+ <XDSCheckboxListItem label="Option A" value="a" />+ </XDSCheckboxList>,+ );+ expect(screen.getByText('Select at least one')).toBeInTheDocument();+ });++ it('renders description on items', () => {+ render(+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>+ <XDSCheckboxListItem+ label="Option A"+ value="a"+ description="This is option A"+ />+ </XDSCheckboxList>,+ );+ expect(screen.getByText('This is option A')).toBeInTheDocument();+ });++ it('renders description on the checkbox list group', () => {+ render(+ <XDSCheckboxList+ label="Preferences"+ description="Choose your preferences"+ value={[]}+ onChange={() => {}}>+ <XDSCheckboxListItem label="Option A" value="a" />+ </XDSCheckboxList>,+ );+ expect(screen.getByText('Choose your preferences')).toBeInTheDocument();+ });++ it('supports data-testid on CheckboxList', () => {+ render(+ <XDSCheckboxList+ label="Preferences"+ value={[]}+ onChange={() => {}}+ data-testid="my-checkbox-list">+ <XDSCheckboxListItem label="Option A" value="a" />+ </XDSCheckboxList>,+ );+ expect(screen.getByTestId('my-checkbox-list')).toBeInTheDocument();+ });++ it('supports data-testid on CheckboxListItem', () => {+ render(+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>+ <XDSCheckboxListItem+ label="Option A"+ value="a"+ data-testid="my-checkbox-item"+ />+ </XDSCheckboxList>,+ );+ expect(screen.getByTestId('my-checkbox-item')).toBeInTheDocument();+ });++ it('renders endContent', () => {+ render(+ <XDSCheckboxList label="Preferences" value={[]} onChange={() => {}}>+ <XDSCheckboxListItem+ label="Option A"+ value="a"+ endContent={<span data-testid="end">Badge</span>}+ />+ </XDSCheckboxList>,+ );+ expect(screen.getByTestId('end')).toBeInTheDocument();+ });++ it('does not toggle when clicking interactive endContent', async () => {+ const user = userEvent.setup();+ const handleChange = vi.fn();+ render(+ <XDSCheckboxList label="Preferences" value={[]} onChange={handleChange}>+ <XDSCheckboxListItem+ label="Option A"+ value="a"+ endContent={<button data-testid="end-btn">Action</button>}+ />+ </XDSCheckboxList>,+ );++ await user.click(screen.getByTestId('end-btn'));+ expect(handleChange).not.toHaveBeenCalled();+ });++ it('allows standalone items inside XDSCheckboxList without parent value (select-all pattern)', async () => {+ const user = userEvent.setup();+ const handleSelectAll = vi.fn();+ const handleCheck = vi.fn();+ render(+ <XDSCheckboxList label="Columns" hasDividers>+ <XDSCheckboxListItem+ label="Select all"+ isChecked={false}+ onCheck={handleSelectAll}+ />+ <XDSCheckboxListItem+ label="Name"+ isChecked={true}+ onCheck={handleCheck}+ />+ <XDSCheckboxListItem+ label="Email"+ isChecked={false}+ onCheck={handleCheck}+ />+ </XDSCheckboxList>,+ );++ // All items render without throwing+ expect(screen.getAllByRole('checkbox')).toHaveLength(3);++ // Select all triggers its own handler+ await user.click(screen.getByRole('checkbox', {name: 'Select all'}));+ expect(handleSelectAll).toHaveBeenCalledWith(true);+ expect(handleCheck).not.toHaveBeenCalled();+ });+});++describe('XDSCheckboxListItem standalone mode', () => {+ it('uses isChecked/onCheck for standalone control', async () => {+ const user = userEvent.setup();+ const handleCheck = vi.fn();+ render(+ <XDSList>+ <XDSCheckboxListItem+ label="Accept terms"+ isChecked={false}+ onCheck={handleCheck}+ />+ </XDSList>,+ );++ await user.click(screen.getByRole('checkbox', {name: 'Accept terms'}));+ expect(handleCheck).toHaveBeenCalledWith(true);+ });++ it('renders checked state from isChecked prop', () => {+ render(+ <XDSList>+ <XDSCheckboxListItem label="Checked item" isChecked={true} />+ </XDSList>,+ );+ expect(screen.getByRole('checkbox')).toBeChecked();+ });++ it('renders unchecked when no isChecked provided', () => {+ render(+ <XDSList>+ <XDSCheckboxListItem label="Default item" />+ </XDSList>,+ );+ expect(screen.getByRole('checkbox')).not.toBeChecked();+ });++ it('does not throw without value prop in standalone mode', () => {+ expect(() => {+ render(+ <XDSList>+ <XDSCheckboxListItem label="No value needed" />+ </XDSList>,+ );+ }).not.toThrow();+ });++ it('renders indeterminate state', () => {+ render(+ <XDSList>+ <XDSCheckboxListItem label="Partial" isChecked="indeterminate" />+ </XDSList>,+ );+ const checkbox = screen.getByRole('checkbox');+ expect(checkbox).toHaveAttribute('aria-checked', 'mixed');+ });++ it('calls onCheck with true when clicking indeterminate item', async () => {+ const user = userEvent.setup();+ const handleCheck = vi.fn();+ render(+ <XDSList>+ <XDSCheckboxListItem+ label="Partial"+ isChecked="indeterminate"+ onCheck={handleCheck}+ />+ </XDSList>,+ );++ await user.click(screen.getByRole('checkbox', {name: 'Partial'}));+ expect(handleCheck).toHaveBeenCalledWith(true);+ });+});++describe('XDSCheckboxListItem ARIA props', () => {+ it('sets aria-checked on the list item in collection mode', () => {+ render(+ <XDSCheckboxList label="Prefs" value={['a']} onChange={() => {}}>+ <XDSCheckboxListItem label="Option A" value="a" />+ <XDSCheckboxListItem label="Option B" value="b" />+ </XDSCheckboxList>,+ );+ const items = screen.getAllByRole('listitem');+ // Item A is checked+ expect(items[0]).toHaveAttribute('aria-checked', 'true');+ // Item B is not checked+ expect(items[1]).toHaveAttribute('aria-checked', 'false');+ });++ it('sets aria-checked on the list item in standalone mode', () => {+ render(+ <XDSList>+ <XDSCheckboxListItem label="Done" isChecked={true} />+ <XDSCheckboxListItem label="Todo" isChecked={false} />+ </XDSList>,+ );+ const items = screen.getAllByRole('listitem');+ expect(items[0]).toHaveAttribute('aria-checked', 'true');+ expect(items[1]).toHaveAttribute('aria-checked', 'false');+ });++ it('sets aria-checked="mixed" for indeterminate items', () => {+ render(+ <XDSList>+ <XDSCheckboxListItem label="Partial" isChecked="indeterminate" />+ </XDSList>,+ );+ const item = screen.getByRole('listitem');+ expect(item).toHaveAttribute('aria-checked', 'mixed');+ });++ it('sets aria-busy during async actions', () => {+ // Render with a pending async action by providing onChangeAction+ // that returns a promise that never resolves+ render(+ <XDSCheckboxList label="Prefs" value={['a']} onChange={() => {}}>+ <XDSCheckboxListItem label="Option A" value="a" />+ </XDSCheckboxList>,+ );+ // By default isBusy is false, so aria-busy should not be present+ const item = screen.getByRole('listitem');+ expect(item).not.toHaveAttribute('aria-busy');+ });++ it('forwards arbitrary aria attributes to the list item DOM element', () => {+ render(+ <XDSList>+ <XDSCheckboxListItem+ label="Custom aria"+ aria-describedby="help-text"+ aria-label="custom label"+ />+ </XDSList>,+ );+ const item = screen.getByRole('listitem');+ expect(item).toHaveAttribute('aria-describedby', 'help-text');+ expect(item).toHaveAttribute('aria-label', 'custom label');+ });+});diff --git a/packages/core/src/CheckboxList/XDSCheckboxList.tsx b/packages/core/src/CheckboxList/XDSCheckboxList.tsxnew file mode 100644index 0000000000..e7ecbf2a7d--- /dev/null+++ b/packages/core/src/CheckboxList/XDSCheckboxList.tsx@@ -0,0 +1,210 @@+'use client';++/**+ * @file XDSCheckboxList.tsx+ * @input Uses React, useId, useOptimistic, useTransition, XDSField, XDSList, XDSCheckboxListContext+ * @output Exports XDSCheckboxList component, XDSCheckboxListProps+ * @position Core implementation; consumed by index.ts, tested by XDSCheckboxList.test.tsx+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/CheckboxList/CheckboxList.doc.mjs+ * - /packages/core/src/CheckboxList/XDSCheckboxList.test.tsx+ * - /packages/core/src/CheckboxList/index.ts+ * - /apps/storybook/stories/CheckboxList.stories.tsx+ */++import {useId, useOptimistic, useTransition, type ReactNode} from 'react';+import type {StyleXStyles} from '@stylexjs/stylex';+import {XDSField} from '../Field/XDSField';+import type {XDSInputStatus} from '../Field/types';+import {XDSList} from '../List/XDSList';+import type {XDSListDensity} from '../List/XDSListContext';+import {+ XDSCheckboxListContext,+ type XDSCheckboxListContextValue,+} from './XDSCheckboxListContext';++const EMPTY_ARRAY: string[] = [];++export interface XDSCheckboxListProps {+ /**+ * Label text for the checkbox group (always rendered for accessibility).+ */+ label: string;+ /**+ * Whether to visually hide the label (still accessible to screen readers).+ * @default false+ */+ isLabelHidden?: boolean;+ /**+ * Description text displayed below the label.+ */+ description?: string;+ /**+ * Status indicator for the checkbox group.+ * When set with a message, displays a colored message box below the group.+ */+ status?: XDSInputStatus;+ /**+ * The currently selected values (collection mode).+ */+ value?: string[];+ /**+ * Callback fired when the selected values change (collection mode).+ */+ onChange?: (values: string[]) => void;+ /**+ * Async action on change. Fires after onChange.+ * While pending, items show reduced opacity and aria-busy.+ */+ onChangeAction?: (values: string[]) => void | Promise<void>;+ /**+ * Whether the checkbox group is in an external loading state.+ * @default false+ */+ isLoading?: boolean;+ /**+ * Spacing density for list items.+ * @default 'balanced'+ */+ density?: XDSListDensity;+ /**+ * Whether to show dividers between list items.+ * @default false+ */+ hasDividers?: boolean;+ /**+ * Whether all checkbox items are disabled.+ * @default false+ */+ isDisabled?: boolean;+ /**+ * Checkbox list items to render.+ */+ children: ReactNode;+ /** Ref forwarded to the root element */+ ref?: React.Ref<HTMLDivElement>;+ /**+ * StyleX styles created via `stylex.create()`. Merged with the component's+ * base styles inside a single `stylex.props()` call for optimal deduplication.+ *+ * @example+ * ```+ * const overrides = stylex.create({ root: { marginBottom: 8 } });+ * <Component xstyle={overrides.root} />+ * ```+ */+ xstyle?: StyleXStyles;+ /**+ * CSS class name(s) appended to the root element.+ * If you're using StyleX, prefer `xstyle` for optimal style deduplication.+ */+ className?: string;+ /**+ * Inline styles to apply to the root element. Spread after StyleX+ * inline styles, so these values take priority.+ */+ style?: React.CSSProperties;+ /**+ * Test ID for the outer container.+ */+ 'data-testid'?: string;+}++/**+ * A checkbox group component for multi-value selection.+ *+ * Composes XDSField (for label, description, status) and XDSList+ * (for density, dividers) with a context provider for collection mode.+ *+ * @example+ * ```+ * <XDSCheckboxList+ * label="Notifications"+ * value={selected}+ * onChange={setSelected}>+ * <XDSCheckboxListItem label="Email" value="email" />+ * <XDSCheckboxListItem label="SMS" value="sms" />+ * <XDSCheckboxListItem label="Push" value="push" />+ * </XDSCheckboxList>+ * ```+ */+export function XDSCheckboxList({+ label,+ isLabelHidden = false,+ description,+ status,+ value,+ onChange,+ onChangeAction,+ isLoading = false,+ density = 'balanced',+ hasDividers = false,+ isDisabled = false,+ children,+ ref,+ xstyle,+ className,+ style,+ 'data-testid': dataTestId,+}: XDSCheckboxListProps) {+ const inputID = useId();+ const descriptionID = useId();+ const statusMessageID = useId();++ const [, startTransition] = useTransition();+ const isCollectionMode = value !== undefined;+ const effectiveValue = value ?? EMPTY_ARRAY;+ const [optimisticValue, setOptimisticValue] = useOptimistic(effectiveValue);+ const isBusy = isLoading || optimisticValue !== effectiveValue;++ const handleChange = (newValues: string[]) => {+ onChange?.(newValues);+ if (onChangeAction) {+ startTransition(async () => {+ setOptimisticValue(newValues);+ await onChangeAction(newValues);+ });+ }+ };++ const contextValue: XDSCheckboxListContextValue = {+ value: isCollectionMode ? optimisticValue : undefined,+ onChange: isCollectionMode ? handleChange : undefined,+ isDisabled,+ isBusy,+ };++ return (+ <XDSField+ ref={ref}+ data-testid={dataTestId}+ label={label}+ isLabelHidden={isLabelHidden}+ description={description}+ inputID={inputID}+ descriptionID={description ? descriptionID : undefined}+ isDisabled={isDisabled}+ status={+ status+ ? {+ type: status.type,+ message: status.message,+ messageID: status.message ? statusMessageID : undefined,+ }+ : undefined+ }+ statusVariant="detached"+ xstyle={xstyle}+ className={className}+ style={style}>+ <XDSCheckboxListContext.Provider value={contextValue}>+ <XDSList density={density} hasDividers={hasDividers}>+ {children}+ </XDSList>+ </XDSCheckboxListContext.Provider>+ </XDSField>+ );+}++XDSCheckboxList.displayName = 'XDSCheckboxList';diff --git a/packages/core/src/CheckboxList/XDSCheckboxListContext.tsx b/packages/core/src/CheckboxList/XDSCheckboxListContext.tsxnew file mode 100644index 0000000000..8b0aacb776--- /dev/null+++ b/packages/core/src/CheckboxList/XDSCheckboxListContext.tsx@@ -0,0 +1,20 @@+'use client';++/**+ * @file XDSCheckboxListContext.tsx+ * @input Uses React createContext+ * @output Exports XDSCheckboxListContext for parent-child communication+ * @position Internal context; consumed by XDSCheckboxList.tsx and XDSCheckboxListItem.tsx+ */++import {createContext} from 'react';++export interface XDSCheckboxListContextValue {+ value?: string[];+ onChange?: (values: string[]) => void;+ isDisabled: boolean;+ isBusy: boolean;+}++export const XDSCheckboxListContext =+ createContext<XDSCheckboxListContextValue | null>(null);diff --git a/packages/core/src/CheckboxList/XDSCheckboxListItem.tsx b/packages/core/src/CheckboxList/XDSCheckboxListItem.tsxnew file mode 100644index 0000000000..1672f3f0bf--- /dev/null+++ b/packages/core/src/CheckboxList/XDSCheckboxListItem.tsx@@ -0,0 +1,203 @@+'use client';++/**+ * @file XDSCheckboxListItem.tsx+ * @input Uses React, XDSCheckboxInput, XDSListItem, XDSCheckboxListContext+ * @output Exports XDSCheckboxListItem component, XDSCheckboxListItemProps+ * @position Core implementation; consumed by index.ts, tested by XDSCheckboxList.test.tsx+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/CheckboxList/CheckboxList.doc.mjs+ * - /packages/core/src/CheckboxList/XDSCheckboxList.test.tsx+ * - /packages/core/src/CheckboxList/index.ts+ * - /apps/storybook/stories/CheckboxList.stories.tsx+ */++import {useContext, useState, type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {colorVars} from '../theme/tokens.stylex';+import type {XDSBaseProps} from '../XDSBaseProps';+import {XDSCheckboxInput} from '../CheckboxInput/XDSCheckboxInput';+import {XDSListItem} from '../List/XDSListItem';+import {XDSListContext} from '../List/XDSListContext';+import {XDSCheckboxListContext} from './XDSCheckboxListContext';++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ selected: {+ backgroundColor: colorVars['--color-accent-muted'],+ },+});++// =============================================================================+// Types+// =============================================================================++export interface XDSCheckboxListItemProps extends XDSBaseProps<HTMLLIElement> {+ /**+ * Primary text label for the item.+ */+ label: string;+ /**+ * Identity key for collection mode (REQUIRED inside XDSCheckboxList).+ * Throws a runtime error if missing when used inside XDSCheckboxList.+ */+ value?: string;+ /**+ * Secondary text below the label.+ */+ description?: string;+ /**+ * Content rendered after the label area.+ */+ endContent?: ReactNode;+ /**+ * Whether this individual item is disabled.+ * @default false+ */+ isDisabled?: boolean;+ /**+ * Direct checked state (standalone mode only).+ * Ignored when inside XDSCheckboxList.+ */+ isChecked?: boolean | 'indeterminate';+ /**+ * Direct check handler (standalone mode only).+ * Ignored when inside XDSCheckboxList.+ */+ onCheck?: (checked: boolean) => void;+ /** Ref forwarded to the root element */+ ref?: React.Ref<HTMLLIElement>;+}++// =============================================================================+// Component+// =============================================================================++/**+ * A checkbox item for use within XDSCheckboxList (collection mode)+ * or XDSList (standalone mode).+ *+ * In collection mode, checked state is derived from the parent's value array.+ * In standalone mode, uses isChecked/onCheck props directly.+ *+ * Composes XDSListItem internally — gets density, dividers, hover/press,+ * focus, and container alignment for free.+ *+ * @example+ * ```+ * <XDSCheckboxListItem label="Email" value="email" />+ * <XDSCheckboxListItem+ * label="Accept terms"+ * isChecked={accepted}+ * onCheck={setAccepted}+ * />+ * ```+ */+export function XDSCheckboxListItem({+ label,+ value,+ description,+ endContent,+ isDisabled: isItemDisabled = false,+ isChecked,+ onCheck,+ ref,+ xstyle,+ className,+ style,+ ...restProps+}: XDSCheckboxListItemProps) {+ const ctx = useContext(XDSCheckboxListContext);++ if (ctx && ctx.value !== undefined && value === undefined) {+ throw new Error(+ 'XDSCheckboxListItem requires a `value` prop when used inside XDSCheckboxList with a value array.',+ );+ }++ const [isFocused, setIsFocused] = useState(false);++ // Density from list context for checkbox sizing+ const listCtx = useContext(XDSListContext);+ const density = listCtx?.density ?? 'balanced';+ const checkboxSize = density === 'compact' ? 'sm' : 'md';++ // Disabled: parent-level OR item-level+ const effectiveDisabled = (ctx?.isDisabled ?? false) || isItemDisabled;+ const isBusy = ctx?.isBusy ?? false;++ // Resolve checked state:+ // 1. Collection mode (inside XDSCheckboxList with value[])+ // 2. Standalone mode (isChecked prop)+ // 3. Neither → unchecked+ let resolvedChecked: boolean | 'indeterminate' = false;+ if (ctx && ctx.value !== undefined) {+ resolvedChecked = ctx.value.includes(value!);+ } else if (isChecked !== undefined) {+ resolvedChecked = isChecked;+ }++ // Whether this item is interactive (has a toggle handler)+ const isInteractive = ctx != null || onCheck != null;++ const handleToggle = () => {+ if (effectiveDisabled || isBusy) return;++ if (ctx && ctx.value !== undefined) {+ // Collection mode+ const currentlyChecked = ctx.value.includes(value!);+ if (currentlyChecked) {+ ctx.onChange?.(ctx.value.filter(v => v !== value));+ } else {+ ctx.onChange?.([...ctx.value, value!]);+ }+ } else {+ // Standalone mode+ const shouldCheck = resolvedChecked === true ? false : true;+ onCheck?.(shouldCheck);+ }+ };++ return (+ <XDSListItem+ {...restProps}+ ref={ref}+ label={label}+ description={description}+ endContent={endContent}+ isDisabled={effectiveDisabled}+ onClick={isInteractive ? handleToggle : undefined}+ aria-checked={+ resolvedChecked === 'indeterminate' ? 'mixed' : resolvedChecked+ }+ aria-busy={isBusy || undefined}+ xstyle={+ [+ resolvedChecked === true && !effectiveDisabled && styles.selected,+ xstyle,+ ] as StyleXStyles+ }+ className={className}+ style={style}+ startContent={+ <XDSCheckboxInput+ label={label}+ isLabelHidden+ value={resolvedChecked}+ onChange={() => handleToggle()}+ onFocus={() => setIsFocused(true)}+ onBlur={() => setIsFocused(false)}+ isDisabled={effectiveDisabled}+ size={checkboxSize}+ />+ }+ />+ );+}++XDSCheckboxListItem.displayName = 'XDSCheckboxListItem';diff --git a/packages/core/src/CheckboxList/index.ts b/packages/core/src/CheckboxList/index.tsnew file mode 100644index 0000000000..79d21249fe--- /dev/null+++ b/packages/core/src/CheckboxList/index.ts@@ -0,0 +1,15 @@+'use client';++/**+ * @file index.ts+ * @input Imports XDSCheckboxList, XDSCheckboxListItem components and types+ * @output Exports XDSCheckboxList, XDSCheckboxListProps, XDSCheckboxListItem, XDSCheckboxListItemProps+ * @position Component entry point; re-exported by /packages/core/src/index.ts+ *+ * SYNC: When modified, update this header+ */++export {XDSCheckboxList} from './XDSCheckboxList';+export type {XDSCheckboxListProps} from './XDSCheckboxList';+export {XDSCheckboxListItem} from './XDSCheckboxListItem';+export type {XDSCheckboxListItemProps} from './XDSCheckboxListItem';diff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsxindex 601818dad2..9cc05a9f5f 100644--- a/packages/core/src/List/XDSList.tsx+++ b/packages/core/src/List/XDSList.tsx@@ -102,6 +102,12 @@ const styles = stylex.create({margin: 0,paddingInlineStart: 0,listStyleType: 'none',+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-0-5'],+ },+ withDividers: {+ gap: 0,},withCounter: {counterReset: 'xds-list',@@ -170,6 +176,7 @@ export function XDSList({xdsClassName('list', {density, listStyle}),stylex.props(styles.list,+ hasDividers && styles.withDividers,listStyle !== 'none' && styles.withCounter,xstyle,),diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsxindex 461aedeaa0..213cd6f710 100644--- a/packages/core/src/List/XDSListItem.tsx+++ b/packages/core/src/List/XDSListItem.tsx@@ -25,6 +25,7 @@ import {typeScaleVars,borderVars,} from '../theme/tokens.stylex';+import type {XDSBaseProps} from '../XDSBaseProps';import {XDSListContext} from './XDSListContext';import {xdsClassName, mergeProps} from '../utils';@@ -32,7 +33,7 @@ import {xdsClassName, mergeProps} from '../utils';// Types// =============================================================================-export interface XDSListItemProps {+export interface XDSListItemProps extends XDSBaseProps<HTMLLIElement> {/** Ref forwarded to the root element */ref?: React.Ref<HTMLLIElement>;/**@@ -88,33 +89,6 @@ export interface XDSListItemProps {* @default false*/isSelected?: boolean;-- /**- * StyleX styles created via `stylex.create()`. Merged with the component's- * base styles inside a single `stylex.props()` call for optimal deduplication.- *- * @example- * ```- * const overrides = stylex.create({ root: { marginBottom: 8 } });- * <Component xstyle={overrides.root} />- * ```- */- xstyle?: StyleXStyles;- /**- * CSS class name(s) appended to the root element.- * If you're using StyleX, prefer `xstyle` for optimal style deduplication.- */- className?: string;- /**- * Inline styles to apply to the root element. Spread after StyleX- * inline styles, so these values take priority.- */- style?: React.CSSProperties;-- /**- * Test ID for testing frameworks.- */- 'data-testid'?: string;}// =============================================================================@@ -175,9 +149,11 @@ const styles = stylex.create({},disabled: {cursor: 'not-allowed',- opacity: 0.5,pointerEvents: 'none' as const,},+ disabledContent: {+ opacity: 0.5,+ },selected: {backgroundColor: colorVars['--color-accent-muted'],},@@ -352,8 +328,8 @@ export function XDSListItem({xstyle,className,style,- 'data-testid': testId,ref,+ ...restProps}: XDSListItemProps) {const ctx = useContext(XDSListContext);const density = ctx?.density ?? 'balanced';@@ -400,7 +376,10 @@ export function XDSListItem({target={target}aria-disabled={isDisabled || undefined}tabIndex={isDisabled ? -1 : undefined}- {...stylex.props(styles.invisibleAnchor)}>+ {...stylex.props(+ styles.invisibleAnchor,+ isDisabled && styles.disabledContent,+ )}>{labelAndDescription}</a>) : onClick != null ? (@@ -408,15 +387,30 @@ export function XDSListItem({type="button"onClick={onClick}disabled={isDisabled}- {...stylex.props(styles.invisibleButton)}>+ {...stylex.props(+ styles.invisibleButton,+ isDisabled && styles.disabledContent,+ )}>{labelAndDescription}</button>) : (- <span {...stylex.props(styles.content)}>{labelAndDescription}</span>+ <span+ {...stylex.props(+ styles.content,+ isDisabled && styles.disabledContent,+ )}>+ {labelAndDescription}+ </span>)}{endContent != null && (- <span {...stylex.props(styles.endContent)}>{endContent}</span>+ <span+ {...stylex.props(+ styles.endContent,+ isDisabled && styles.disabledContent,+ )}>+ {endContent}+ </span>)}</>);@@ -437,9 +431,9 @@ export function XDSListItem({return (<liref={ref}- data-testid={testId}aria-selected={isSelected || undefined}aria-disabled={isDisabled || undefined}+ {...restProps}{...mergeProps(xdsClassName('list-item'),stylex.props(diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 24a068af59..667b2daa15 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -26,6 +26,7 @@ export * from './Center';export * from './CodeBlock';export * from './CommandPalette';export * from './CheckboxInput';+export * from './CheckboxList';export * from './Collapsible';export * from './RadioList';export * from './Divider';