An open source design system that's fully customizable and agent ready
TypeScript
Improve MultiSelector docs page and block examples (#1593)
Ted McDonald57e157bb2275
diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.doc.mjs b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.doc.mjsindex 258e5b50cf..3e17eb6570 100644--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.doc.mjs+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.doc.mjs@@ -3,8 +3,8 @@ export const doc = {type: 'block',name: 'MultiSelector — Column Visibility',description:- 'Table column visibility toggle with hidden label, search, select-all, and count display.',+ 'Column visibility toggle with hidden label, search, select-all, and selection count.',isReady: true,aspectRatio: 4 / 3,- componentsUsed: ['MultiSelector'],+ componentsUsed: ['MultiSelector', 'Center'],};diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.tsx b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.tsxindex 213e9d5885..9694c8d801 100644--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.tsx+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorColumnVisibilitySelector.tsx@@ -2,6 +2,7 @@import {useState} from 'react';import {XDSMultiSelector} from '@xds/core/MultiSelector';+import {XDSCenter} from '@xds/core/Center';const allColumns = [{value: 'name', label: 'Name'},@@ -21,7 +22,7 @@ export default function MultiSelectorColumnVisibilitySelector() {'status',]);return (- <div style={{width: 300}}>+ <XDSCenter width={300}><XDSMultiSelectorlabel="Columns"isLabelHidden@@ -33,6 +34,6 @@ export default function MultiSelectorColumnVisibilitySelector() {triggerDisplay="count"placeholder="Columns"/>- </div>+ </XDSCenter>);}diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.doc.mjs b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.doc.mjsindex 194709067a..ab37fdea7c 100644--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.doc.mjs+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.doc.mjs@@ -3,8 +3,8 @@ export const doc = {type: 'block',name: 'MultiSelector — Form Composition',description:- 'Two multi-selectors in a form layout with labels, badges, and required/optional states.',+ 'Two multi-selectors in a form with required/optional states.',isReady: true,aspectRatio: 4 / 3,- componentsUsed: ['MultiSelector'],+ componentsUsed: ['MultiSelector', 'Center', 'VStack'],};diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.tsx b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.tsxindex 640d1818b8..ae4e64aaa2 100644--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.tsx+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorForm.tsx@@ -2,38 +2,42 @@import {useState} from 'react';import {XDSMultiSelector} from '@xds/core/MultiSelector';+import {XDSVStack} from '@xds/core/Layout';+import {XDSCenter} from '@xds/core/Center';export default function MultiSelectorForm() {const [columns, setColumns] = useState<string[]>(['name', 'email']);const [filters, setFilters] = useState<string[]>([]);return (- <div style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>- <XDSMultiSelector- label="Visible columns"- description="Choose which columns to display in the table"- options={[- {value: 'name', label: 'Name'},- {value: 'email', label: 'Email'},- {value: 'role', label: 'Role'},- {value: 'status', label: 'Status'},- {value: 'created', label: 'Created at'},- ]}- value={columns}- onChange={setColumns}- hasSelectAll- isRequired- triggerDisplay="labels"- />- <XDSMultiSelector- label="Status filter"- description="Filter by status"- options={['Active', 'Inactive', 'Pending', 'Archived']}- value={filters}- onChange={setFilters}- isOptional- triggerDisplay="badges"- placeholder="All statuses"- />- </div>+ <XDSCenter width={300}>+ <XDSVStack gap={4}>+ <XDSMultiSelector+ label="Visible columns"+ description="Choose which columns to display in the table"+ options={[+ {value: 'name', label: 'Name'},+ {value: 'email', label: 'Email'},+ {value: 'role', label: 'Role'},+ {value: 'status', label: 'Status'},+ {value: 'created', label: 'Created at'},+ ]}+ value={columns}+ onChange={setColumns}+ hasSelectAll+ isRequired+ triggerDisplay="labels"+ />+ <XDSMultiSelector+ label="Status filter"+ description="Filter by status"+ options={['Active', 'Inactive', 'Pending', 'Archived']}+ value={filters}+ onChange={setFilters}+ isOptional+ triggerDisplay="badges"+ placeholder="All statuses"+ />+ </XDSVStack>+ </XDSCenter>);}diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.doc.mjs b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.doc.mjsindex ed2040416d..218c29be2a 100644--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.doc.mjs+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.doc.mjs@@ -3,8 +3,8 @@ export const doc = {type: 'block',name: 'MultiSelector — Searchable',description:- 'Multi-select with search filtering and select-all for long option lists.',+ 'Multi-select with search filtering and select-all.',isReady: true,aspectRatio: 4 / 3,- componentsUsed: ['MultiSelector'],+ componentsUsed: ['MultiSelector', 'Center'],};diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.tsx b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.tsxindex c6c366f3ac..8e8d27f245 100644--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.tsx+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSearchableMultiSelector.tsx@@ -2,6 +2,7 @@import {useState} from 'react';import {XDSMultiSelector} from '@xds/core/MultiSelector';+import {XDSCenter} from '@xds/core/Center';const countries = ['United States',@@ -19,7 +20,7 @@ const countries = [export default function MultiSelectorSearchableMultiSelector() {const [value, setValue] = useState<string[]>([]);return (- <div style={{width: 300}}>+ <XDSCenter width={300}><XDSMultiSelectorlabel="Countries"options={countries}@@ -29,6 +30,6 @@ export default function MultiSelectorSearchableMultiSelector() {hasSelectAllplaceholder="Select countries..."/>- </div>+ </XDSCenter>);}diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.doc.mjs b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.doc.mjsindex 94429299d2..1b2a07fd95 100644--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.doc.mjs+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.doc.mjs@@ -3,8 +3,8 @@ export const doc = {type: 'block',name: 'MultiSelector — Sectioned Permissions',description:- 'Multi-select with options organized into labeled sections for grouped selection.',+ 'Multi-select with options grouped into labeled sections.',isReady: true,aspectRatio: 4 / 3,- componentsUsed: ['MultiSelector'],+ componentsUsed: ['MultiSelector', 'Center'],};diff --git a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.tsx b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.tsxindex c404027470..ea02e232d4 100644--- a/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.tsx+++ b/packages/cli/templates/blocks/components/MultiSelector/MultiSelectorSectionedMultiSelector.tsx@@ -2,11 +2,12 @@import {useState} from 'react';import {XDSMultiSelector} from '@xds/core/MultiSelector';+import {XDSCenter} from '@xds/core/Center';export default function MultiSelectorSectionedMultiSelector() {const [value, setValue] = useState<string[]>([]);return (- <div style={{width: 300}}>+ <XDSCenter width={300}><XDSMultiSelectorlabel="Permissions"options={[@@ -32,6 +33,6 @@ export default function MultiSelectorSectionedMultiSelector() {onChange={setValue}placeholder="Select permissions..."/>- </div>+ </XDSCenter>);}diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjsindex 3c017d415b..75fbb39a8b 100644--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs@@ -141,12 +141,13 @@ export const docs = {],usage: {description:- 'MultiSelector is a dropdown with checkboxes for selecting multiple items from a finite list. Use it for filter facets, column toggles, or any small set of options where multiple choices are needed.',+ 'A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.',bestPractices: [- { guidance: true, description: 'Use for small, finite option sets where users need to select multiple items at once.' },- { guidance: true, description: 'Enable search filtering when the list exceeds 10–15 options to help users find items quickly.' },- { guidance: false, description: 'Use MultiSelector as a replacement for Tokenizer — Tokenizer is better suited for large or dynamic datasets.' },- { guidance: false, description: 'Omit the label — every MultiSelector needs a visible or visually hidden label for accessibility.' },+ { guidance: true, description: 'Use for a moderate, finite set of options where multiple choices are needed.' },+ { guidance: true, description: 'Enable search filtering when the list exceeds ~15 options.' },+ { guidance: true, description: 'Enable select-all when most users will want all or nearly all options selected.' },+ { guidance: false, description: 'Use for single-value selection — use Selector instead.' },+ { guidance: false, description: 'Show more than ~20 options without enabling search.' },],},};@@ -185,12 +186,13 @@ export const docsZh = {],usage: {description:- 'MultiSelector is a dropdown with checkboxes for selecting multiple items from a finite list. Use it for filter facets, column toggles, or any small set of options where multiple choices are needed.',+ 'A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.',bestPractices: [- { guidance: true, description: 'Use for small, finite option sets where users need to select multiple items at once.' },- { guidance: true, description: 'Enable search filtering when the list exceeds 10–15 options to help users find items quickly.' },- { guidance: false, description: 'Use MultiSelector as a replacement for Tokenizer — Tokenizer is better suited for large or dynamic datasets.' },- { guidance: false, description: 'Omit the label — every MultiSelector needs a visible or visually hidden label for accessibility.' },+ { guidance: true, description: 'Use for a moderate, finite set of options where multiple choices are needed.' },+ { guidance: true, description: 'Enable search filtering when the list exceeds ~15 options.' },+ { guidance: true, description: 'Enable select-all when most users will want all or nearly all options selected.' },+ { guidance: false, description: 'Use for single-value selection — use Selector instead.' },+ { guidance: false, description: 'Show more than ~20 options without enabling search.' },],},};@@ -200,12 +202,13 @@ export const docsDense = {description: 'checkbox multi-select dropdown for finite sets like column toggles or filter facets',usage: {description:- 'MultiSelector is a dropdown with checkboxes for selecting multiple items from a finite list. Use it for filter facets, column toggles, or any small set of options where multiple choices are needed.',+ 'A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.',bestPractices: [- { guidance: true, description: 'Use for small, finite option sets where users need to select multiple items at once.' },- { guidance: true, description: 'Enable search filtering when the list exceeds 10–15 options to help users find items quickly.' },- { guidance: false, description: 'Use MultiSelector as a replacement for Tokenizer — Tokenizer is better suited for large or dynamic datasets.' },- { guidance: false, description: 'Omit the label — every MultiSelector needs a visible or visually hidden label for accessibility.' },+ { guidance: true, description: 'Use for a moderate, finite set of options where multiple choices are needed.' },+ { guidance: true, description: 'Enable search filtering when the list exceeds ~15 options.' },+ { guidance: true, description: 'Enable select-all when most users will want all or nearly all options selected.' },+ { guidance: false, description: 'Use for single-value selection — use Selector instead.' },+ { guidance: false, description: 'Show more than ~20 options without enabling search.' },],},components: [