An open source design system that's fully customizable and agent ready
TypeScript
Improve CheckboxInput docs page and block examples (#1559)
rubyycheung419e4f603ae7
diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.doc.mjsnew file mode 100644index 0000000000..1b94e3aac2--- /dev/null+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'CheckboxInput — States',+ description: 'Checkboxes with labels and descriptions in checked, unchecked, and disabled states. Each checkbox controls a single on/off setting. Add a description to explain what the setting does.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['CheckboxInput', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.tsxnew file mode 100644index 0000000000..dc1503fee7--- /dev/null+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputBasic.tsx@@ -0,0 +1,44 @@+'use client';++import {useState} from 'react';+import {XDSCheckboxInput} from '@xds/core/CheckboxInput';+import {XDSStack} from '@xds/core/Layout';++export default function CheckboxInputBasic() {+ const [checked, setChecked] = useState<boolean | 'indeterminate'>(true);+ const [unchecked, setUnchecked] = useState<boolean | 'indeterminate'>(false);+ const [disabled, setDisabled] = useState<boolean | 'indeterminate'>(false);+ const [indeterminate, setIndeterminate] = useState<boolean | 'indeterminate'>(+ 'indeterminate',+ );++ return (+ <XDSStack direction="vertical" gap={4}>+ <XDSCheckboxInput+ label="Checked"+ description="This checkbox is currently on."+ value={checked}+ onChange={setChecked}+ />+ <XDSCheckboxInput+ label="Unchecked"+ description="This checkbox is currently off."+ value={unchecked}+ onChange={setUnchecked}+ />+ <XDSCheckboxInput+ label="Disabled"+ description="This checkbox cannot be changed."+ value={disabled}+ onChange={setDisabled}+ isDisabled+ />+ <XDSCheckboxInput+ label="Indeterminate"+ description="This checkbox represents a partial selection."+ value={indeterminate}+ onChange={setIndeterminate}+ />+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.doc.mjsdeleted file mode 100644index 7f50f9ebcf..0000000000--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'CheckboxInput — Disabled Checkbox',- description:- 'Disabled checkbox with a description explaining why the option is unavailable.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['CheckboxInput'],-};diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.tsxdeleted file mode 100644index 12c5f26259..0000000000--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputDisabledCheckbox.tsx+++ /dev/null@@ -1,17 +0,0 @@-'use client';--import {useState} from 'react';-import {XDSCheckboxInput} from '@xds/core/CheckboxInput';--export default function CheckboxInputDisabledCheckbox() {- const [value, setValue] = useState<boolean | 'indeterminate'>(false);- return (- <XDSCheckboxInput- label="Premium feature"- description="Upgrade to enable this option"- value={value}- onChange={setValue}- isDisabled- />- );-}diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.doc.mjsindex ddc88ee6eb..28ad8c1409 100644--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.doc.mjs+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.doc.mjs@@ -1,10 +1,9 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'CheckboxInput — Indeterminate State',- description:- 'Checkbox in the indeterminate state, useful for "select all" patterns with partial selection.',+ name: 'CheckboxInput — Indeterminate',+ description: 'A "select all" checkbox that controls a group of options. When only some options are checked, it shows a dash instead of a checkmark. Clicking it checks or unchecks everything.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['CheckboxInput'],+ aspectRatio: 16 / 9,+ componentsUsed: ['CheckboxInput', 'Divider', 'Layout'],};diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.tsxindex 45b79085b8..4687770355 100644--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.tsx+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputIndeterminateState.tsx@@ -2,15 +2,61 @@import {useState} from 'react';import {XDSCheckboxInput} from '@xds/core/CheckboxInput';+import {XDSStack} from '@xds/core/Layout';+import {XDSDivider} from '@xds/core/Divider';export default function CheckboxInputIndeterminateState() {- const [value, setValue] = useState<boolean | 'indeterminate'>('indeterminate');+ const [items, setItems] = useState({+ email: true,+ push: false,+ sms: true,+ slack: false,+ });++ const checkedCount = Object.values(items).filter(Boolean).length;+ const totalCount = Object.keys(items).length;+ const selectAllValue =+ checkedCount === 0+ ? false+ : checkedCount === totalCount+ ? true+ : ('indeterminate' as const);++ const handleSelectAll = (checked: boolean) => {+ setItems({email: checked, push: checked, sms: checked, slack: checked});+ };+return (- <XDSCheckboxInput- label="Select all items"- description="Some items are selected"- value={value}- onChange={setValue}- />+ <XDSStack direction="vertical" gap={3}>+ <XDSCheckboxInput+ label="Select all notifications"+ description={`${checkedCount} of ${totalCount} enabled`}+ value={selectAllValue}+ onChange={handleSelectAll}+ />+ <XDSDivider />+ <XDSStack direction="vertical" gap={3}>+ <XDSCheckboxInput+ label="Email notifications"+ value={items.email}+ onChange={v => setItems(prev => ({...prev, email: v}))}+ />+ <XDSCheckboxInput+ label="Push notifications"+ value={items.push}+ onChange={v => setItems(prev => ({...prev, push: v}))}+ />+ <XDSCheckboxInput+ label="SMS alerts"+ value={items.sms}+ onChange={v => setItems(prev => ({...prev, sms: v}))}+ />+ <XDSCheckboxInput+ label="Slack messages"+ value={items.slack}+ onChange={v => setItems(prev => ({...prev, slack: v}))}+ />+ </XDSStack>+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.doc.mjsindex 277cc1749f..12f3bed4ae 100644--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.doc.mjs+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.doc.mjs@@ -1,10 +1,9 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'CheckboxInput — Status Variations',- description:- 'Multiple checkboxes showing error, warning, and success status messages.',+ name: 'CheckboxInput — Status',+ description: 'Checkboxes with error, warning, and success validation messages. Use the status prop to show feedback after form validation — errors block submission, warnings inform, and success confirms.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['CheckboxInput'],+ aspectRatio: 16 / 9,+ componentsUsed: ['CheckboxInput', 'Layout'],};diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.tsxindex 3469cc2789..a477faa197 100644--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.tsx+++ b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputStatusVariations.tsx@@ -2,32 +2,42 @@import {useState} from 'react';import {XDSCheckboxInput} from '@xds/core/CheckboxInput';+import {XDSStack} from '@xds/core/Layout';export default function CheckboxInputStatusVariations() {- const [value1, setValue1] = useState<boolean | 'indeterminate'>(false);- const [value2, setValue2] = useState<boolean | 'indeterminate'>(true);- const [value3, setValue3] = useState<boolean | 'indeterminate'>(true);+ const [error, setError] = useState<boolean | 'indeterminate'>(false);+ const [warning, setWarning] = useState<boolean | 'indeterminate'>(true);+ const [success, setSuccess] = useState<boolean | 'indeterminate'>(true);+return (- <div style={{display: 'flex', flexDirection: 'column', gap: 24, maxWidth: 400}}>+ <XDSStack direction="vertical" gap={4}><XDSCheckboxInput- label="Accept terms and conditions"- value={value1}- onChange={setValue1}- status={{type: 'error', message: 'You must accept the terms to continue'}}+ label="Error"+ description="Required field that has not been accepted."+ value={error}+ onChange={setError}+ status={{+ type: 'error',+ message: 'You must accept the terms to continue',+ }}/><XDSCheckboxInput- label="Share usage data"- description="Help us improve by sharing anonymous usage statistics"- value={value2}- onChange={setValue2}- status={{type: 'warning', message: 'This data may be shared with partners'}}+ label="Warning"+ description="Enabled setting with a side effect to be aware of."+ value={warning}+ onChange={setWarning}+ status={{+ type: 'warning',+ message: 'This data may be shared with partners',+ }}/><XDSCheckboxInput- label="Email verified"- value={value3}- onChange={setValue3}+ label="Success"+ description="Confirmed setting that has been verified."+ value={success}+ onChange={setSuccess}status={{type: 'success', message: 'Your email has been verified'}}/>- </div>+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.doc.mjsdeleted file mode 100644index 1f9b744bfd..0000000000--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'CheckboxInput — With Description',- description:- 'Checkbox with a descriptive helper text below the label.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['CheckboxInput'],-};diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.tsxdeleted file mode 100644index f77a1f68a0..0000000000--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithDescription.tsx+++ /dev/null@@ -1,16 +0,0 @@-'use client';--import {useState} from 'react';-import {XDSCheckboxInput} from '@xds/core/CheckboxInput';--export default function CheckboxInputWithDescription() {- const [value, setValue] = useState<boolean | 'indeterminate'>(false);- return (- <XDSCheckboxInput- label="Subscribe to newsletter"- description="Receive weekly updates about new features and announcements."- value={value}- onChange={setValue}- />- );-}diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.doc.mjs b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.doc.mjsdeleted file mode 100644index f03e6ed0d6..0000000000--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'CheckboxInput — With Error Status',- description:- 'Checkbox displaying a validation error message.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['CheckboxInput'],-};diff --git a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.tsx b/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.tsxdeleted file mode 100644index 668a4bbb06..0000000000--- a/packages/cli/templates/blocks/components/CheckboxInput/CheckboxInputWithErrorStatus.tsx+++ /dev/null@@ -1,16 +0,0 @@-'use client';--import {useState} from 'react';-import {XDSCheckboxInput} from '@xds/core/CheckboxInput';--export default function CheckboxInputWithErrorStatus() {- const [value, setValue] = useState<boolean | 'indeterminate'>(false);- return (- <XDSCheckboxInput- label="Accept terms and conditions"- value={value}- onChange={setValue}- status={{type: 'error', message: 'You must accept the terms to continue'}}- />- );-}diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjsindex c28c8012d4..35c42d1fcd 100644--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs@@ -105,12 +105,19 @@ export const docs = {],},usage: {- description: 'CheckboxInput is a form control for toggling a single boolean value. Use it for standalone on/off settings, terms acceptance, or as a building block inside CheckboxList for multi-select groups.',+ description: 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',bestPractices: [- { guidance: true, description: 'Always provide a visible label for context. Use isLabelHidden only when surrounding UI already makes the purpose clear.' },- { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes that represent a partial selection.' },- { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList or a toggle switch instead.' },- { guidance: false, description: 'Hide the label without an equivalent accessible alternative nearby.' },+ { guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },+ { guidance: true, description: 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.' },+ { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList when only one option can be selected.' },+ { guidance: false, description: 'Use a checkbox for actions that take effect immediately — use a toggle switch or button instead.' },+ ],+ anatomy: [+ { name: 'Checkbox', required: true, description: 'The check box itself — unchecked, checked, or indeterminate.' },+ { name: 'Label', required: true, description: 'Text describing what the checkbox controls. Always present for accessibility.' },+ { name: 'Description', required: false, description: 'Helper text below the label with additional context.' },+ { name: 'Status message', required: false, description: 'An error, warning, or success message below the checkbox.' },],},};@@ -119,12 +126,13 @@ export const docs = {export const docsZh = {name: 'CheckboxInput',usage: {- description: 'CheckboxInput is a form control for toggling a single boolean value. Use it for standalone on/off settings, terms acceptance, or as a building block inside CheckboxList for multi-select groups.',+ description: 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',bestPractices: [- { guidance: true, description: 'Always provide a visible label for context. Use isLabelHidden only when surrounding UI already makes the purpose clear.' },- { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes that represent a partial selection.' },- { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList or a toggle switch instead.' },- { guidance: false, description: 'Hide the label without an equivalent accessible alternative nearby.' },+ { guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },+ { guidance: true, description: 'Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.' },+ { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.' },+ { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList when only one option can be selected.' },+ { guidance: false, description: 'Use a checkbox for actions that take effect immediately — use a toggle switch or button instead.' },],},props: [@@ -169,14 +177,12 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'checkbox for toggling boolean values',+ description: 'single on/off toggle for settings, terms, and opt-in choices',usage: {- description: 'CheckboxInput is a form control for toggling a single boolean value. Use it for standalone on/off settings, terms acceptance, or as a building block inside CheckboxList for multi-select groups.',+ description: 'CheckboxInput toggles a single on/off value. Use for settings, terms acceptance, opt-in choices. Use CheckboxList for groups.',bestPractices: [- { guidance: true, description: 'Always provide a visible label for context. Use isLabelHidden only when surrounding UI already makes the purpose clear.' },- { guidance: true, description: 'Use the indeterminate state for "select all" checkboxes that represent a partial selection.' },- { guidance: false, description: 'Use a checkbox for mutually exclusive choices — use RadioList or a toggle switch instead.' },- { guidance: false, description: 'Hide the label without an equivalent accessible alternative nearby.' },+ { guidance: true, description: 'Always provide a visible label. Add description for context. Use indeterminate for partial "select all".' },+ { guidance: false, description: 'Use for mutually exclusive choices (use RadioList). Use for immediate actions (use toggle/button).' },],},propDescriptions: {