An open source design system that's fully customizable and agent ready
TypeScript
fix(CheckboxInput): hardening — swarm findings (#734)
Joey709edb925b53
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjsindex a636f563ee..75897cd22f 100644--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs@@ -5,12 +5,23 @@ export const docs = {description: 'A checkbox input component for toggling boolean values.',features: ['Accessible — always includes a label (can be visually hidden)',- 'Indeterminate state — supports indeterminate state for "select all" patterns',+ 'Indeterminate state — supports indeterminate for "select all" patterns','Descriptions — optional description text below the label',- 'Custom styling — uses StyleX with XDS design tokens',+ 'Sizes — sm (compact) and md (default)',+ 'Async actions — onChangeAction with optimistic updates and loading spinner',+ 'Status messages — error, warning, success validation feedback',+ 'Optional/required indicators — label suffix with field state',+ 'Label icons — optional icon before label text','Disabled state — full support for disabled state styling',+ 'Reduced motion — respects prefers-reduced-motion',],props: [+ {+ name: 'ref',+ type: 'React.Ref<HTMLInputElement>',+ description:+ 'Ref forwarded to the underlying <input> element.',+ },{name: 'label',type: 'string',@@ -21,7 +32,7 @@ export const docs = {{name: 'isLabelHidden',type: 'boolean',- description: 'Whether to visually hide the label.',+ description: 'Whether to visually hide the label (still accessible to screen readers).',default: 'false',},{@@ -38,15 +49,66 @@ export const docs = {},{name: 'onChange',- type: '(checked: boolean, e: ChangeEvent) => void',+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void',description: 'Callback fired when the checkbox state changes.',},+ {+ name: 'onChangeAction',+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',+ description:+ 'Async action on change. Fires after onChange if not prevented. Shows loading spinner while pending.',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: 'Whether the checkbox is in a loading state. Shows spinner and prevents interaction.',+ default: 'false',+ },{name: 'isDisabled',type: 'boolean',description: 'Whether the checkbox is disabled.',default: 'false',},+ {+ name: 'isOptional',+ type: 'boolean',+ description: 'Whether the field is optional. Mutually exclusive with isRequired.',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Whether the checkbox is required. Mutually exclusive with isOptional.',+ default: 'false',+ },+ {+ name: 'size',+ type: "'sm' | 'md'",+ description: 'The size of the checkbox. sm for compact layouts, md for default.',+ default: "'md'",+ },+ {+ name: 'onFocus',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Callback fired when the checkbox receives focus.',+ },+ {+ name: 'onBlur',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: 'Callback fired when the checkbox loses focus.',+ },+ {+ name: 'labelIcon',+ type: 'XDSIconType',+ description: 'Icon to display before the label text.',+ },+ {+ name: 'status',+ type: "{ type: 'error' | 'warning' | 'success', message: string }",+ description:+ 'Status indicator. Displays a colored message box below the checkbox and sets aria-invalid for errors.',+ },],examples: [{@@ -91,19 +153,50 @@ export const docs = {value={false}onChange={() => {}}isDisabled+/>`,+ },+ {+ label: 'Small size',+ code: `<XDSCheckboxInput+ label="Compact checkbox"+ value={checked}+ onChange={setChecked}+ size="sm"+/>`,+ },+ {+ label: 'With error status',+ code: `<XDSCheckboxInput+ label="Accept terms"+ value={false}+ onChange={setAccepted}+ status={{ type: 'error', message: 'You must accept the terms to continue' }}+/>`,+ },+ {+ label: 'Async action',+ code: `<XDSCheckboxInput+ label="Enable feature"+ value={enabled}+ onChange={setEnabled}+ onChangeAction={async (checked) => {+ await savePreference(checked);+ }}/>`,},],theming: {targets: [{className: 'xds-checkbox-input', visualProps: ['size']},+ {className: 'xds-checkbox'},],},notes: ['Uses a hidden native <input type="checkbox"> for accessibility with a custom visual checkbox overlay.',- 'The visual checkbox responds to hover, focus, and checked states via sibling selectors in CSS.',+ 'The visual checkbox responds to hover, focus, and checked states via ancestor selectors (stylex.when.ancestor).','Label is clickable and properly associated with the input via htmlFor/id.',- 'Focus outline uses the standard XDS focus outline token.',+ 'Focus outline uses the standard XDS focus ring token.',+ 'Interaction is blocked during busy state (loading or pending async action) to prevent double-toggling.',],};@@ -115,21 +208,30 @@ export const docsZh = {'无障碍——始终包含标签(可视觉隐藏)','不确定状态——支持"全选"模式的不确定状态','描述——标签下方可选的描述文本',- '自定义样式——使用 StyleX 和 XDS 设计令牌',+ '尺寸——sm(紧凑)和 md(默认)',+ '异步操作——onChangeAction 带乐观更新和加载旋转器',+ '状态消息——错误、警告、成功验证反馈',+ '可选/必填指示器——带字段状态的标签后缀',+ '标签图标——标签文本前可选图标','禁用状态——完整支持禁用状态样式',+ '减少动画——尊重 prefers-reduced-motion',],props: [+ {+ name: 'ref',+ type: 'React.Ref<HTMLInputElement>',+ description: '转发至底层 <input> 元素的 ref。',+ },{name: 'label',type: 'string',- description:- '复选框的标签文本(始终为无障碍性而渲染)。',+ description: '复选框的标签文本(始终为无障碍性而渲染)。',required: true,},{name: 'isLabelHidden',type: 'boolean',- description: '是否视觉隐藏标签。',+ description: '是否视觉隐藏标签(屏幕阅读器仍可访问)。',default: 'false',},{@@ -140,21 +242,69 @@ export const docsZh = {{name: 'value',type: "boolean | 'indeterminate'",- description:- '复选框是否为选中、未选中或不确定状态。',+ description: '复选框是否为选中、未选中或不确定状态。',required: true,},{name: 'onChange',- type: '(checked: boolean, e: ChangeEvent) => void',+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void',description: '复选框状态变更时触发的回调。',},+ {+ name: 'onChangeAction',+ type: '(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>',+ description: '异步变更操作。在 onChange 之后触发(未被阻止时)。等待期间显示加载旋转器。',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: '复选框是否处于加载状态。显示旋转器并阻止交互。',+ default: 'false',+ },{name: 'isDisabled',type: 'boolean',description: '复选框是否禁用。',default: 'false',},+ {+ name: 'isOptional',+ type: 'boolean',+ description: '字段是否可选。与 isRequired 互斥。',+ default: 'false',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: '复选框是否必填。与 isOptional 互斥。',+ default: 'false',+ },+ {+ name: 'size',+ type: "'sm' | 'md'",+ description: '复选框尺寸。sm 用于紧凑布局,md 为默认。',+ default: "'md'",+ },+ {+ name: 'onFocus',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: '复选框获得焦点时触发的回调。',+ },+ {+ name: 'onBlur',+ type: '(e: FocusEvent<HTMLInputElement>) => void',+ description: '复选框失去焦点时触发的回调。',+ },+ {+ name: 'labelIcon',+ type: 'XDSIconType',+ description: '标签文本前显示的图标。',+ },+ {+ name: 'status',+ type: "{ type: 'error' | 'warning' | 'success', message: string }",+ description: '状态指示器。在复选框下方显示彩色消息框,错误时设置 aria-invalid。',+ },],examples: [{@@ -199,19 +349,50 @@ export const docsZh = {value={false}onChange={() => {}}isDisabled+/>`,+ },+ {+ label: '紧凑尺寸',+ code: `<XDSCheckboxInput+ label="Compact checkbox"+ value={checked}+ onChange={setChecked}+ size="sm"+/>`,+ },+ {+ label: '错误状态',+ code: `<XDSCheckboxInput+ label="Accept terms"+ value={false}+ onChange={setAccepted}+ status={{ type: 'error', message: 'You must accept the terms to continue' }}+/>`,+ },+ {+ label: '异步操作',+ code: `<XDSCheckboxInput+ label="Enable feature"+ value={enabled}+ onChange={setEnabled}+ onChangeAction={async (checked) => {+ await savePreference(checked);+ }}/>`,},],theming: {targets: [{className: 'xds-checkbox-input', visualProps: ['size']},+ {className: 'xds-checkbox'},],},notes: ['使用隐藏的原生 <input type="checkbox"> 确保无障碍性,并覆盖自定义视觉复选框。',- '视觉复选框通过 CSS 兄弟选择器响应悬停、焦点和选中状态。',+ '视觉复选框通过祖先选择器(stylex.when.ancestor)响应悬停、焦点和选中状态。','标签可点击,并通过 htmlFor/id 与输入框正确关联。',- '焦点轮廓使用标准的 XDS 焦点轮廓令牌。',+ '焦点轮廓使用标准的 XDS 焦点环令牌。',+ '忙碌状态(加载中或异步操作等待中)期间阻止交互,防止重复切换。',],};@@ -222,21 +403,37 @@ export const docsDense = {'accessible; always includes label (can be visually hidden)','indeterminate state for "select all" patterns','optional description text below label',- 'custom styling via StyleX w/ XDS design tokens',+ 'sizes: sm (compact), md (default)',+ 'async actions w/ onChangeAction, optimistic updates, loading spinner',+ 'status messages: error/warning/success validation',+ 'optional/required field indicators',+ 'label icons','full disabled state styling',+ 'respects prefers-reduced-motion',],notes: ['hidden native <input type="checkbox"> w/ custom visual overlay',- 'visual checkbox responds to hover, focus, checked via CSS sibling selectors',+ 'visual checkbox responds to hover, focus, checked via ancestor selectors (stylex.when.ancestor)','label clickable + associated via htmlFor/id',- 'focus outline uses XDS focus outline token',+ 'focus outline uses XDS focus ring token',+ 'interaction blocked during busy state to prevent double-toggling',],propDescriptions: {+ ref: 'ref forwarded to underlying <input>',label: 'label text; always rendered for a11y',- isLabelHidden: 'visually hide label',+ isLabelHidden: 'visually hide label (still accessible to screen readers)',description: 'text below label',value: 'checked, unchecked, or indeterminate',onChange: 'callback on state change',+ onChangeAction: 'async action; fires after onChange, shows spinner while pending',+ isLoading: 'shows spinner + prevents interaction',isDisabled: 'disable checkbox',+ isOptional: 'mark field as optional (mutually exclusive w/ isRequired)',+ isRequired: 'mark field as required (mutually exclusive w/ isOptional)',+ size: 'sm (compact) or md (default)',+ onFocus: 'callback on focus',+ onBlur: 'callback on blur',+ labelIcon: 'icon before label text',+ status: 'error/warning/success with message; sets aria-invalid on error',},};diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsxindex 592a562294..f810d88084 100644--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx@@ -29,7 +29,10 @@ import {durationVars,easeVars,typographyVars,+ lineHeightVars,+ fontWeightVars,} from '../theme/tokens.stylex';+import type {XDSBaseProps} from '../XDSBaseProps';import {XDSFieldLabel} from '../Field/XDSFieldLabel';import {XDSFieldStatus} from '../Field/XDSFieldStatus';import type {XDSIconType} from '../Icon';@@ -40,7 +43,7 @@ import {xdsClassName, mergeProps} from '../utils';const styles = stylex.create({container: {display: 'flex',- alignItems: 'flex-start',+ alignItems: 'center',gap: spacingVars['--spacing-2'],},containerLabelHidden: {@@ -72,7 +75,10 @@ const styles = stylex.create({borderStyle: 'solid',borderRadius: radiusVars['--radius-1'],transitionProperty: 'background-color, border-color',- transitionDuration: durationVars['--duration-fast'],+ transitionDuration: {+ default: durationVars['--duration-fast'],+ '@media (prefers-reduced-motion: reduce)': '0s',+ },transitionTimingFunction: easeVars['--ease-standard'],},checkboxFocus: {@@ -145,6 +151,8 @@ const styles = stylex.create({description: {fontFamily: typographyVars['--font-body'],fontSize: textSizeVars['--text-xsm'],+ lineHeight: lineHeightVars['--leading-relaxed'],+ fontWeight: fontWeightVars['--font-weight-normal'],color: colorVars['--color-text-secondary'],},});@@ -193,19 +201,10 @@ const indeterminateSizeStyles = stylex.create({},});-const labelWrapperSizeStyles = stylex.create({- sm: {- marginTop: 1,- },- md: {- marginTop: 3,- },-});-export type XDSCheckboxInputSize = keyof typeof wrapperSizeStyles;-export interface XDSCheckboxInputProps {- /** Ref forwarded to the root element */+export interface XDSCheckboxInputProps extends Omit<XDSBaseProps, 'onChange'> {+ /** Ref forwarded to the underlying `<input>` element */ref?: React.Ref<HTMLInputElement>;/*** Label text for the checkbox (always rendered for accessibility).@@ -315,6 +314,9 @@ export function XDSCheckboxInput({onBlur,labelIcon,status,+ xstyle,+ className,+ style,ref,}: XDSCheckboxInputProps) {const id = useId();@@ -338,7 +340,13 @@ export function XDSCheckboxInput({describedByParts.length > 0 ? describedByParts.join(' ') : undefined;return (- <div className={xdsClassName('checkbox-input', {size})}>+ <div+ {...mergeProps(+ xdsClassName('checkbox-input', {size}),+ stylex.props(xstyle),+ className,+ style,+ )}><div{...stylex.props(styles.container,@@ -354,6 +362,7 @@ export function XDSCheckboxInput({disabled={isDisabled}required={isRequired}onChange={e => {+ if (isBusy) return;const checked = e.target.checked;onChange?.(checked, e);if (onChangeAction && !e.defaultPrevented) {@@ -377,17 +386,20 @@ export function XDSCheckboxInput({/><divaria-hidden="true"- {...stylex.props(- styles.checkbox,- checkboxSizeStyles[size],- !isDisabled && styles.checkboxFocus,- isCheckedOrIndeterminate- ? styles.checkboxChecked- : styles.checkboxUnchecked,- isDisabled && styles.checkboxDisabled,- isDisabled &&- !isCheckedOrIndeterminate &&- styles.checkboxDisabledUnchecked,+ {...mergeProps(+ xdsClassName('checkbox'),+ stylex.props(+ styles.checkbox,+ checkboxSizeStyles[size],+ !isDisabled && styles.checkboxFocus,+ isCheckedOrIndeterminate+ ? styles.checkboxChecked+ : styles.checkboxUnchecked,+ isDisabled && styles.checkboxDisabled,+ isDisabled &&+ !isCheckedOrIndeterminate &&+ styles.checkboxDisabledUnchecked,+ ),)}>{isBusy ? (<XDSSpinner@@ -424,7 +436,7 @@ export function XDSCheckboxInput({</div></div><div- {...stylex.props(styles.labelWrapper, labelWrapperSizeStyles[size])}>+ {...stylex.props(styles.labelWrapper)}><XDSFieldLabellabel={label}inputID={id}