Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve Tokenizer docs page and block examples (#1612)

Kenton Quatman45ed527119af
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerClear.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerClear.doc.mjs
new file mode 100644
index 0000000000..3a8d579e0a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerClear.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Tokenizer \u2014 Clear',
+ description: 'Tokenizer with a built-in clear-all button for bulk removal of all selected tokens.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Tokenizer', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerClear.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerClear.tsx
new file mode 100644
index 0000000000..5870939559
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerClear.tsx
@@ -0,0 +1,47 @@
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSTokenizer} from '@xds/core/Tokenizer';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+
+const styles = stylex.create({
+ fixed: {width: 400},
+});
+
+const users: XDSSearchableItem[] = [
+ {id: '1', label: 'Alice Johnson'},
+ {id: '2', label: 'Bob Smith'},
+ {id: '3', label: 'Charlie Brown'},
+ {id: '4', label: 'Diana Prince'},
+ {id: '5', label: 'Eve Williams'},
+];
+
+const userSource: XDSSearchSource = {
+ search: (query: string) =>
+ users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: () => users,
+};
+
+export default function TokenizerClear() {
+ const [value, setValue] = useState<XDSSearchableItem[]>([users[0], users[1]]);
+
+ return (
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Clear-all button appears when tokens are selected
+ </XDSText>
+ <XDSTokenizer
+ label="Team Members"
+ placeholder="Search people..."
+ searchSource={userSource}
+ value={value}
+ onChange={items => setValue(items)}
+ hasClear
+ xstyle={styles.fixed}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatable.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatable.doc.mjs
new file mode 100644
index 0000000000..07183ea2f9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatable.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Tokenizer \u2014 Creatable',
+ description: 'Free-text tokenizer for creating custom tags and a combined create-or-search pattern. Use when users need to enter values that may not exist in a predefined list.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Tokenizer', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatable.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatable.tsx
new file mode 100644
index 0000000000..f5758fcf0a
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatable.tsx
@@ -0,0 +1,70 @@
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSTokenizer} from '@xds/core/Tokenizer';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+
+const styles = stylex.create({
+ fixed: {width: 400},
+});
+
+const emptySource: XDSSearchSource = {
+ search: () => [],
+ bootstrap: () => [],
+};
+
+const users: XDSSearchableItem[] = [
+ {id: '1', label: 'Alice Johnson'},
+ {id: '2', label: 'Bob Smith'},
+ {id: '3', label: 'Charlie Brown'},
+ {id: '4', label: 'Diana Prince'},
+ {id: '5', label: 'Eve Williams'},
+];
+
+const userSource: XDSSearchSource = {
+ search: (query: string) =>
+ users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: () => users,
+};
+
+export default function TokenizerCreatable() {
+ const [tags, setTags] = useState<XDSSearchableItem[]>([]);
+ const [members, setMembers] = useState<XDSSearchableItem[]>([]);
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Free-text only
+ </XDSText>
+ <XDSTokenizer
+ label="Tags"
+ searchSource={emptySource}
+ value={tags}
+ onChange={items => setTags(items)}
+ hasCreate
+ placeholder="Type a tag and press Enter..."
+ xstyle={styles.fixed}
+ />
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Create or search
+ </XDSText>
+ <XDSTokenizer
+ label="Team Members"
+ searchSource={userSource}
+ value={members}
+ onChange={items => setMembers(items)}
+ hasCreate
+ hasEntriesOnFocus
+ placeholder="Search or type a new name..."
+ xstyle={styles.fixed}
+ />
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatableTags.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatableTags.doc.mjs
deleted file mode 100644
index b031e85812..0000000000
--- a/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatableTags.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Tokenizer — Creatable Tags',
- description:
- 'Free-text tokenizer for creating custom tags by typing and pressing Enter.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Tokenizer'],
-};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatableTags.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatableTags.tsx
deleted file mode 100644
index 731aa31bd5..0000000000
--- a/packages/cli/templates/blocks/components/Tokenizer/TokenizerCreatableTags.tsx
+++ /dev/null
@@ -1,29 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTokenizer} from '@xds/core/Tokenizer';
-import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
-
-const emptySource: XDSSearchSource = {
- search: () => [],
- bootstrap: () => [],
-};
-
-export default function TokenizerCreatableTags() {
- const [tags, setTags] = useState<XDSSearchableItem[]>([]);
- return (
- <div>
- <XDSTokenizer
- label="Tags"
- searchSource={emptySource}
- value={tags}
- onChange={items => setTags(items)}
- hasCreate
- placeholder="Type a tag and press Enter..."
- />
- <p style={{marginTop: 8, fontSize: 14, color: '#666'}}>
- {tags.length} tag{tags.length !== 1 ? 's' : ''} added
- </p>
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerEndContent.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerEndContent.doc.mjs
new file mode 100644
index 0000000000..6c7f6a9b77
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerEndContent.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Tokenizer \u2014 End Content',
+ description: 'Tokenizer with an action button in the end slot. Use for inline actions like applying selections alongside the input.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Tokenizer', 'Button', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerEndContent.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerEndContent.tsx
new file mode 100644
index 0000000000..111bf3fd1b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerEndContent.tsx
@@ -0,0 +1,49 @@
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSTokenizer} from '@xds/core/Tokenizer';
+import {XDSButton} from '@xds/core/Button';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+
+const styles = stylex.create({
+ fixed: {width: 400},
+});
+
+const users: XDSSearchableItem[] = [
+ {id: '1', label: 'Alice Johnson'},
+ {id: '2', label: 'Bob Smith'},
+ {id: '3', label: 'Charlie Brown'},
+ {id: '4', label: 'Diana Prince'},
+ {id: '5', label: 'Eve Williams'},
+ {id: '6', label: 'Frank Miller'},
+];
+
+const userSource: XDSSearchSource = {
+ search: (query: string) =>
+ users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: () => users,
+};
+
+export default function TokenizerEndContent() {
+ const [value, setValue] = useState<XDSSearchableItem[]>([users[0], users[2]]);
+
+ return (
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Action button in the end slot
+ </XDSText>
+ <XDSTokenizer
+ label="Team Members"
+ placeholder="Search people..."
+ searchSource={userSource}
+ value={value}
+ onChange={items => setValue(items)}
+ endContent={<XDSButton label="Apply" variant="primary" size="sm" />}
+ xstyle={styles.fixed}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerIcon.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerIcon.doc.mjs
new file mode 100644
index 0000000000..94f74a8752
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerIcon.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Tokenizer \u2014 Icon',
+ description: 'Tokenizer with a leading search icon to visually reinforce the search behavior.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Tokenizer', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerIcon.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerIcon.tsx
new file mode 100644
index 0000000000..da0d240c8c
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerIcon.tsx
@@ -0,0 +1,48 @@
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSTokenizer} from '@xds/core/Tokenizer';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
+import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+
+const styles = stylex.create({
+ fixed: {width: 400},
+});
+
+const users: XDSSearchableItem[] = [
+ {id: '1', label: 'Alice Johnson'},
+ {id: '2', label: 'Bob Smith'},
+ {id: '3', label: 'Charlie Brown'},
+ {id: '4', label: 'Diana Prince'},
+ {id: '5', label: 'Eve Williams'},
+];
+
+const userSource: XDSSearchSource = {
+ search: (query: string) =>
+ users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: () => users,
+};
+
+export default function TokenizerIcon() {
+ const [value, setValue] = useState<XDSSearchableItem[]>([users[0], users[2]]);
+
+ return (
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Leading icon reinforces the search affordance
+ </XDSText>
+ <XDSTokenizer
+ label="Team Members"
+ placeholder="Search people..."
+ searchSource={userSource}
+ value={value}
+ onChange={items => setValue(items)}
+ startIcon={MagnifyingGlassIcon}
+ xstyle={styles.fixed}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerMaxEntries.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerMaxEntries.doc.mjs
new file mode 100644
index 0000000000..8591b8b4e6
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerMaxEntries.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Tokenizer \u2014 Max Entries',
+ description: 'Tokenizer with a maximum selection limit. The input hides automatically when the limit is reached, preventing further additions.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Tokenizer', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerMaxEntries.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerMaxEntries.tsx
new file mode 100644
index 0000000000..764ca539b5
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerMaxEntries.tsx
@@ -0,0 +1,57 @@
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSTokenizer} from '@xds/core/Tokenizer';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+
+const styles = stylex.create({
+ fixed: {width: 400},
+});
+
+const skills: XDSSearchableItem[] = [
+ {id: '1', label: 'React'},
+ {id: '2', label: 'TypeScript'},
+ {id: '3', label: 'GraphQL'},
+ {id: '4', label: 'Node.js'},
+ {id: '5', label: 'Python'},
+ {id: '6', label: 'Rust'},
+ {id: '7', label: 'Go'},
+ {id: '8', label: 'Swift'},
+];
+
+const skillSource: XDSSearchSource = {
+ search: (query: string) =>
+ skills.filter(s => s.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: () => skills,
+};
+
+const MAX_SKILLS = 3;
+
+export default function TokenizerMaxEntries() {
+ const [value, setValue] = useState<XDSSearchableItem[]>([
+ skills[0],
+ skills[1],
+ ]);
+
+ return (
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Limited to {MAX_SKILLS} selections — {MAX_SKILLS - value.length}{' '}
+ remaining
+ </XDSText>
+ <XDSTokenizer
+ label="Top Skills"
+ placeholder="Search skills..."
+ description={`Choose up to ${MAX_SKILLS} skills`}
+ searchSource={skillSource}
+ value={value}
+ onChange={items => setValue(items)}
+ maxEntries={MAX_SKILLS}
+ xstyle={styles.fixed}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerOverflow.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerOverflow.doc.mjs
new file mode 100644
index 0000000000..70d8b8255b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerOverflow.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Tokenizer \u2014 Overflow',
+ description: 'Tokenizer with overflow truncation when unfocused. Inline mode pushes content down on expand; layer mode overlays without shifting layout.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Tokenizer', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerOverflow.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerOverflow.tsx
new file mode 100644
index 0000000000..5db195143f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerOverflow.tsx
@@ -0,0 +1,65 @@
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSTokenizer} from '@xds/core/Tokenizer';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+
+const styles = stylex.create({
+ fixed: {width: 400, maxWidth: 400},
+});
+
+const users: XDSSearchableItem[] = [
+ {id: '1', label: 'Alice Johnson'},
+ {id: '2', label: 'Bob Smith'},
+ {id: '3', label: 'Charlie Brown'},
+ {id: '4', label: 'Diana Prince'},
+ {id: '5', label: 'Eve Williams'},
+ {id: '6', label: 'Frank Miller'},
+];
+
+const userSource: XDSSearchSource = {
+ search: (query: string) =>
+ users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: () => users,
+};
+
+export default function TokenizerOverflow() {
+ const [inlineValue, setInlineValue] = useState<XDSSearchableItem[]>(users);
+ const [layerValue, setLayerValue] = useState<XDSSearchableItem[]>(users);
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Inline overflow — content shifts down on expand
+ </XDSText>
+ <XDSTokenizer
+ label="Inline Overflow"
+ placeholder="Add more..."
+ searchSource={userSource}
+ value={inlineValue}
+ onChange={items => setInlineValue(items)}
+ tokenOverflowBehavior="unfocusedInline"
+ xstyle={styles.fixed}
+ />
+ </XDSStack>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Layer overflow — expands as overlay, no layout shift
+ </XDSText>
+ <XDSTokenizer
+ label="Layer Overflow"
+ placeholder="Add more..."
+ searchSource={userSource}
+ value={layerValue}
+ onChange={items => setLayerValue(items)}
+ tokenOverflowBehavior="unfocusedLayer"
+ xstyle={styles.fixed}
+ />
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerPreselectedItems.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerPreselectedItems.doc.mjs
deleted file mode 100644
index 78f0b19442..0000000000
--- a/packages/cli/templates/blocks/components/Tokenizer/TokenizerPreselectedItems.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Tokenizer — Pre-selected Items',
- description:
- 'Tokenizer pre-populated with selected items that users can modify.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Tokenizer'],
-};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerPreselectedItems.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerPreselectedItems.tsx
deleted file mode 100644
index 06b65b6c70..0000000000
--- a/packages/cli/templates/blocks/components/Tokenizer/TokenizerPreselectedItems.tsx
+++ /dev/null
@@ -1,32 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTokenizer} from '@xds/core/Tokenizer';
-import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
-
-const users: XDSSearchableItem[] = [
- {id: '1', label: 'Alice Johnson'},
- {id: '2', label: 'Bob Smith'},
- {id: '3', label: 'Charlie Brown'},
- {id: '4', label: 'Diana Prince'},
- {id: '5', label: 'Eve Williams'},
-];
-
-const userSource: XDSSearchSource = {
- search: (query: string) =>
- users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
- bootstrap: () => users.slice(0, 5),
-};
-
-export default function TokenizerPreselectedItems() {
- const [value, setValue] = useState<XDSSearchableItem[]>([users[0], users[2]]);
- return (
- <XDSTokenizer
- label="Team Members"
- placeholder="Add more..."
- searchSource={userSource}
- value={value}
- onChange={items => setValue(items)}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerShowcase.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerShowcase.tsx
index 917ca8e08a..cff54fca58 100644
--- a/packages/cli/templates/blocks/components/Tokenizer/TokenizerShowcase.tsx
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerShowcase.tsx
@@ -1,8 +1,13 @@
'use client';
+import * as stylex from '@stylexjs/stylex';
import {XDSTokenizer} from '@xds/core/Tokenizer';
import type {XDSSearchSource} from '@xds/core/Typeahead';
+const styles = stylex.create({
+ fixed: {width: 400},
+});
+
const source: XDSSearchSource = {
search: () => [],
bootstrap: () => [],
@@ -19,6 +24,7 @@ export default function TokenizerShowcase() {
{id: '2', label: 'Engineering'},
]}
onChange={() => {}}
+ xstyle={styles.fixed}
/>
);
}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerStates.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerStates.doc.mjs
new file mode 100644
index 0000000000..42c75aca20
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerStates.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Tokenizer \u2014 States',
+ description: 'Tokenizer in disabled, error, warning, and success states. Use to communicate validation feedback or lock a selection from editing.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Tokenizer', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerStates.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerStates.tsx
new file mode 100644
index 0000000000..013f65a244
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Tokenizer/TokenizerStates.tsx
@@ -0,0 +1,80 @@
+'use client';
+
+import {useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSTokenizer} from '@xds/core/Tokenizer';
+import {XDSStack} from '@xds/core/Layout';
+import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+
+const styles = stylex.create({
+ fixed: {width: 400},
+});
+
+const users: XDSSearchableItem[] = [
+ {id: '1', label: 'Alice Johnson'},
+ {id: '2', label: 'Bob Smith'},
+ {id: '3', label: 'Charlie Brown'},
+ {id: '4', label: 'Diana Prince'},
+ {id: '5', label: 'Eve Williams'},
+];
+
+const userSource: XDSSearchSource = {
+ search: (query: string) =>
+ users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
+ bootstrap: () => users,
+};
+
+export default function TokenizerStates() {
+ const [errorValue, setErrorValue] = useState<XDSSearchableItem[]>([]);
+ const [warningValue, setWarningValue] = useState<XDSSearchableItem[]>([
+ users[0],
+ ]);
+ const [successValue, setSuccessValue] = useState<XDSSearchableItem[]>([
+ users[1],
+ users[3],
+ ]);
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSTokenizer
+ label="Disabled field"
+ searchSource={userSource}
+ value={[users[0], users[2]]}
+ onChange={() => {}}
+ isDisabled
+ xstyle={styles.fixed}
+ />
+ <XDSTokenizer
+ label="Error message"
+ placeholder="Search people..."
+ searchSource={userSource}
+ value={errorValue}
+ onChange={items => setErrorValue(items)}
+ isRequired
+ status={{type: 'error', message: 'At least one reviewer is required'}}
+ xstyle={styles.fixed}
+ />
+ <XDSTokenizer
+ label="Warning message"
+ placeholder="Search people..."
+ searchSource={userSource}
+ value={warningValue}
+ onChange={items => setWarningValue(items)}
+ status={{
+ type: 'warning',
+ message: 'Consider adding at least 2 approvers',
+ }}
+ xstyle={styles.fixed}
+ />
+ <XDSTokenizer
+ label="Success message"
+ placeholder="Search people..."
+ searchSource={userSource}
+ value={successValue}
+ onChange={items => setSuccessValue(items)}
+ status={{type: 'success', message: 'All required reviewers added'}}
+ xstyle={styles.fixed}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerValidationError.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerValidationError.doc.mjs
deleted file mode 100644
index 2b04c97f4b..0000000000
--- a/packages/cli/templates/blocks/components/Tokenizer/TokenizerValidationError.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Tokenizer — Validation Error',
- description:
- 'Tokenizer displaying an error status message for form validation.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Tokenizer'],
-};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerValidationError.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerValidationError.tsx
deleted file mode 100644
index d4e92623c3..0000000000
--- a/packages/cli/templates/blocks/components/Tokenizer/TokenizerValidationError.tsx
+++ /dev/null
@@ -1,33 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTokenizer} from '@xds/core/Tokenizer';
-import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
-
-const users: XDSSearchableItem[] = [
- {id: '1', label: 'Alice Johnson'},
- {id: '2', label: 'Bob Smith'},
- {id: '3', label: 'Charlie Brown'},
- {id: '4', label: 'Diana Prince'},
- {id: '5', label: 'Eve Williams'},
-];
-
-const userSource: XDSSearchSource = {
- search: (query: string) =>
- users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
- bootstrap: () => users.slice(0, 5),
-};
-
-export default function TokenizerValidationError() {
- const [value, setValue] = useState<XDSSearchableItem[]>([]);
- return (
- <XDSTokenizer
- label="Team Members"
- placeholder="Search people..."
- searchSource={userSource}
- value={value}
- onChange={items => setValue(items)}
- status={{type: 'error', message: 'At least one member is required'}}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerWithEndContent.doc.mjs b/packages/cli/templates/blocks/components/Tokenizer/TokenizerWithEndContent.doc.mjs
deleted file mode 100644
index 7d1c4641f8..0000000000
--- a/packages/cli/templates/blocks/components/Tokenizer/TokenizerWithEndContent.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Tokenizer — With End Content',
- description:
- 'Tokenizer with an action button in the end slot for inline actions.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Tokenizer', 'Button'],
-};
diff --git a/packages/cli/templates/blocks/components/Tokenizer/TokenizerWithEndContent.tsx b/packages/cli/templates/blocks/components/Tokenizer/TokenizerWithEndContent.tsx
deleted file mode 100644
index 9cc5501210..0000000000
--- a/packages/cli/templates/blocks/components/Tokenizer/TokenizerWithEndContent.tsx
+++ /dev/null
@@ -1,36 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTokenizer} from '@xds/core/Tokenizer';
-import {XDSButton} from '@xds/core/Button';
-import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
-
-const users: XDSSearchableItem[] = [
- {id: '1', label: 'Alice Johnson'},
- {id: '2', label: 'Bob Smith'},
- {id: '3', label: 'Charlie Brown'},
- {id: '4', label: 'Diana Prince'},
- {id: '5', label: 'Eve Williams'},
-];
-
-const userSource: XDSSearchSource = {
- search: (query: string) =>
- users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
- bootstrap: () => users.slice(0, 5),
-};
-
-export default function TokenizerWithEndContent() {
- const [value, setValue] = useState<XDSSearchableItem[]>([
- users[0],
- users[2],
- ]);
- return (
- <XDSTokenizer
- label="Team Members"
- searchSource={userSource}
- value={value}
- onChange={items => setValue(items)}
- endContent={<XDSButton label="Apply" variant="primary" size="sm" />}
- />
- );
-}
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index fd040489d2..74f4f2dc21 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -159,7 +159,7 @@ export const docs = {
name: 'xstyle',
type: 'StyleXStyles',
description:
- 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
+ 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value \u2014 not an inline style object like style={{}}.',
},
],
theming: {
@@ -169,12 +169,23 @@ export const docs = {
},
usage: {
description:
- 'Tokenizer is a multi-select input that lets users search and select multiple items displayed as removable token chips. Use Tokenizer when users need to build a set of selections from a searchable data source, such as adding recipients or applying multiple filters.',
+ 'Tokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.',
bestPractices: [
- {guidance: true, description: 'Provide a clear placeholder that communicates what users can search for.'},
- {guidance: true, description: 'Set a maxEntries limit when the number of selections should be bounded.'},
- {guidance: false, description: 'Avoid applying colored backgrounds to tokens within a Tokenizer — use the default color for consistency.'},
- {guidance: false, description: 'Avoid using Tokenizer for single-item selection — use Typeahead instead.'},
+ {guidance: true, description: 'Write a placeholder that tells users what they can search for \u2014 "Search people\u2026" or "Add tags\u2026" \u2014 so the input is not a blank mystery.'},
+ {guidance: true, description: 'Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers.'},
+ {guidance: true, description: 'Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source.'},
+ {guidance: true, description: 'Show validation status with the status prop so users know immediately when a selection is missing or invalid.'},
+ {guidance: false, description: 'Don\u2019t use Tokenizer for single-item selection \u2014 use Typeahead instead. Tokenizer is for building sets of two or more items.'},
+ {guidance: false, description: 'Avoid applying custom colors to individual tokens inside a Tokenizer \u2014 use the default token style for visual consistency across the set.'},
+ {guidance: false, description: 'Don\u2019t hide the label \u2014 every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.'},
+ ],
+ anatomy: [
+ {name: 'Label', required: true, description: 'The visible text above the input describing what the user is selecting. Also used as the accessible name.'},
+ {name: 'Token chips', required: false, description: 'Removable chips representing each selected item. Each chip shows a label and a remove button.'},
+ {name: 'Search input', required: true, description: 'The text input where users type to search the data source. Hides when maxEntries is reached.'},
+ {name: 'Dropdown menu', required: false, description: 'The search results list that appears below the input as the user types.'},
+ {name: 'End content', required: false, description: 'A trailing slot after the input for action buttons, counts, or other controls.'},
+ {name: 'Clear button', required: false, description: 'A button that removes all selected tokens at once. Shown when hasClear is true and tokens are present.'},
],
},
};
@@ -186,152 +197,152 @@ export const docsZh = {
{
name: 'label',
type: 'string',
- description: '输入框的无障碍标签。',
+ description: '\u8f93\u5165\u6846\u7684\u65e0\u969c\u788d\u6807\u7b7e\u3002',
required: true,
},
{
name: 'searchSource',
type: 'XDSSearchSource<T>',
description:
- '提供搜索和引导方法的数据源,用于填充下拉列表。',
+ '\u63d0\u4f9b\u641c\u7d22\u548c\u5f15\u5bfc\u65b9\u6cd5\u7684\u6570\u636e\u6e90\uff0c\u7528\u4e8e\u586b\u5145\u4e0b\u62c9\u5217\u8868\u3002',
required: true,
},
{
name: 'value',
type: 'T[]',
- description: '当前已选项目的数组。',
+ description: '\u5f53\u524d\u5df2\u9009\u9879\u76ee\u7684\u6570\u7ec4\u3002',
required: true,
},
{
name: 'onChange',
type: '(items: T[], change: XDSTokenizerChange<T>) => void',
description:
- "选择变更时调用。change 参数包含受影响的项目和类型('add' | 'create' | 'remove' | 'reorder')。",
+ "\u9009\u62e9\u53d8\u66f4\u65f6\u8c03\u7528\u3002change \u53c2\u6570\u5305\u542b\u53d7\u5f71\u54cd\u7684\u9879\u76ee\u548c\u7c7b\u578b\uff08'add' | 'create' | 'remove' | 'reorder'\uff09\u3002",
required: true,
},
{
name: 'placeholder',
type: 'string',
description:
- '输入框占位文本。仅在未选择任何标记时显示。',
+ '\u8f93\u5165\u6846\u5360\u4f4d\u6587\u672c\u3002\u4ec5\u5728\u672a\u9009\u62e9\u4efb\u4f55\u6807\u8bb0\u65f6\u663e\u793a\u3002',
},
{
name: 'maxEntries',
type: 'number',
description:
- '允许的最大选择数量。达到限制时输入框会隐藏。',
+ '\u5141\u8bb8\u7684\u6700\u5927\u9009\u62e9\u6570\u91cf\u3002\u8fbe\u5230\u9650\u5236\u65f6\u8f93\u5165\u6846\u4f1a\u9690\u85cf\u3002',
},
{
name: 'hasClear',
type: 'boolean',
- description: '显示全部清除按钮,用于批量移除所有标记。',
+ description: '\u663e\u793a\u5168\u90e8\u6e05\u9664\u6309\u94ae\uff0c\u7528\u4e8e\u6279\u91cf\u79fb\u9664\u6240\u6709\u6807\u8bb0\u3002',
default: 'false',
},
{
name: 'renderToken',
type: '(item: T, onRemove: () => void) => ReactNode',
description:
- '已选标记的自定义渲染函数。默认渲染带有 label 和 onRemove 的 XDSToken。',
+ '\u5df2\u9009\u6807\u8bb0\u7684\u81ea\u5b9a\u4e49\u6e32\u67d3\u51fd\u6570\u3002\u9ed8\u8ba4\u6e32\u67d3\u5e26\u6709 label \u548c onRemove \u7684 XDSToken\u3002',
},
{
name: 'renderItem',
type: '(item: T) => ReactNode',
description:
- '下拉列表项的自定义渲染函数。默认渲染 XDSTypeaheadItem。',
+ '\u4e0b\u62c9\u5217\u8868\u9879\u7684\u81ea\u5b9a\u4e49\u6e32\u67d3\u51fd\u6570\u3002\u9ed8\u8ba4\u6e32\u67d3 XDSTypeaheadItem\u3002',
},
{
name: 'isDisabled',
type: 'boolean',
- description: '禁用输入框和所有标记交互。',
+ description: '\u7981\u7528\u8f93\u5165\u6846\u548c\u6240\u6709\u6807\u8bb0\u4ea4\u4e92\u3002',
default: 'false',
},
{
name: 'status',
type: 'XDSInputStatus',
description:
- '验证状态对象,包含类型和消息,用于错误/警告/成功状态。',
+ '\u9a8c\u8bc1\u72b6\u6001\u5bf9\u8c61\uff0c\u5305\u542b\u7c7b\u578b\u548c\u6d88\u606f\uff0c\u7528\u4e8e\u9519\u8bef/\u8b66\u544a/\u6210\u529f\u72b6\u6001\u3002',
},
{
name: 'isLabelHidden',
type: 'boolean',
- description: '视觉隐藏标签,同时保持其可访问性。',
+ description: '\u89c6\u89c9\u9690\u85cf\u6807\u7b7e\uff0c\u540c\u65f6\u4fdd\u6301\u5176\u53ef\u8bbf\u95ee\u6027\u3002',
default: 'false',
},
{
name: 'description',
type: 'string',
- description: '显示在标签下方的辅助文本。',
+ description: '\u663e\u793a\u5728\u6807\u7b7e\u4e0b\u65b9\u7684\u8f85\u52a9\u6587\u672c\u3002',
},
{
name: 'isRequired',
type: 'boolean',
- description: '将字段标记为必填。',
+ description: '\u5c06\u5b57\u6bb5\u6807\u8bb0\u4e3a\u5fc5\u586b\u3002',
default: 'false',
},
{
name: 'isOptional',
type: 'boolean',
- description: '在标签上显示可选指示器。',
+ description: '\u5728\u6807\u7b7e\u4e0a\u663e\u793a\u53ef\u9009\u6307\u793a\u5668\u3002',
default: 'false',
},
{
name: 'labelTooltip',
type: 'string',
- description: '标签上显示的工具提示文本。',
+ description: '\u6807\u7b7e\u4e0a\u663e\u793a\u7684\u5de5\u5177\u63d0\u793a\u6587\u672c\u3002',
},
{
name: 'hasEntriesOnFocus',
type: 'boolean',
- description: '聚焦时在输入前显示引导结果。',
+ description: '\u805a\u7126\u65f6\u5728\u8f93\u5165\u524d\u663e\u793a\u5f15\u5bfc\u7ed3\u679c\u3002',
default: 'false',
},
{
name: 'maxMenuItems',
type: 'number',
- description: '下拉列表显示的最大项目数。',
+ description: '\u4e0b\u62c9\u5217\u8868\u663e\u793a\u7684\u6700\u5927\u9879\u76ee\u6570\u3002',
default: '10',
},
{
name: 'emptySearchResultsText',
type: 'string',
- description: '搜索无结果时显示的文本。',
+ description: '\u641c\u7d22\u65e0\u7ed3\u679c\u65f6\u663e\u793a\u7684\u6587\u672c\u3002',
default: "'No results found'",
},
{
name: 'hasAutoFocus',
type: 'boolean',
- description: '挂载时自动聚焦输入框。',
+ description: '\u6302\u8f7d\u65f6\u81ea\u52a8\u805a\u7126\u8f93\u5165\u6846\u3002',
default: 'false',
},
{
name: 'size',
type: "'sm' | 'md'",
- description: '输入框和标记的尺寸。',
+ description: '\u8f93\u5165\u6846\u548c\u6807\u8bb0\u7684\u5c3a\u5bf8\u3002',
default: "'md'",
},
{
name: 'debounceMs',
type: 'number',
description:
- '触发搜索前的防抖延迟(毫秒)。同步数据源设置为 0。',
+ '\u89e6\u53d1\u641c\u7d22\u524d\u7684\u9632\u6296\u5ef6\u8fdf\uff08\u6beb\u79d2\uff09\u3002\u540c\u6b65\u6570\u636e\u6e90\u8bbe\u7f6e\u4e3a 0\u3002',
default: '150',
},
{
name: 'onChangeQuery',
type: '(query: string) => void',
- description: '搜索查询文本变更时触发的回调。',
+ description: '\u641c\u7d22\u67e5\u8be2\u6587\u672c\u53d8\u66f4\u65f6\u89e6\u53d1\u7684\u56de\u8c03\u3002',
},
{
name: 'endContent',
type: 'ReactNode',
description:
- '在输入行末尾显示的内容。适用于按钮、结果计数或其他控件。',
+ '\u5728\u8f93\u5165\u884c\u672b\u5c3e\u663e\u793a\u7684\u5185\u5bb9\u3002\u9002\u7528\u4e8e\u6309\u94ae\u3001\u7ed3\u679c\u8ba1\u6570\u6216\u5176\u4ed6\u63a7\u4ef6\u3002',
},
{
name: 'xstyle',
type: 'StyleXStyles',
description:
- '用于布局自定义的 StyleX 样式(外边距、定位、尺寸)。必须是 stylex.create() 的值 — 不能是内联样式对象如 style={{}}。',
+ '\u7528\u4e8e\u5e03\u5c40\u81ea\u5b9a\u4e49\u7684 StyleX \u6837\u5f0f\uff08\u5916\u8fb9\u8ddd\u3001\u5b9a\u4f4d\u3001\u5c3a\u5bf8\uff09\u3002\u5fc5\u987b\u662f stylex.create() \u7684\u503c \u2014 \u4e0d\u80fd\u662f\u5185\u8054\u6837\u5f0f\u5bf9\u8c61\u5982 style={{}}\u3002',
},
],
theming: {
@@ -341,12 +352,23 @@ export const docsZh = {
},
usage: {
description:
- 'Tokenizer is a multi-select input that lets users search and select multiple items displayed as removable token chips. Use Tokenizer when users need to build a set of selections from a searchable data source, such as adding recipients or applying multiple filters.',
+ 'Tokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.',
bestPractices: [
- {guidance: true, description: 'Provide a clear placeholder that communicates what users can search for.'},
- {guidance: true, description: 'Set a maxEntries limit when the number of selections should be bounded.'},
- {guidance: false, description: 'Avoid applying colored backgrounds to tokens within a Tokenizer — use the default color for consistency.'},
- {guidance: false, description: 'Avoid using Tokenizer for single-item selection — use Typeahead instead.'},
+ {guidance: true, description: 'Write a placeholder that tells users what they can search for \u2014 "Search people\u2026" or "Add tags\u2026" \u2014 so the input is not a blank mystery.'},
+ {guidance: true, description: 'Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers.'},
+ {guidance: true, description: 'Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source.'},
+ {guidance: true, description: 'Show validation status with the status prop so users know immediately when a selection is missing or invalid.'},
+ {guidance: false, description: 'Don\u2019t use Tokenizer for single-item selection \u2014 use Typeahead instead. Tokenizer is for building sets of two or more items.'},
+ {guidance: false, description: 'Avoid applying custom colors to individual tokens inside a Tokenizer \u2014 use the default token style for visual consistency across the set.'},
+ {guidance: false, description: 'Don\u2019t hide the label \u2014 every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious.'},
+ ],
+ anatomy: [
+ {name: 'Label', required: true, description: 'The visible text above the input describing what the user is selecting. Also used as the accessible name.'},
+ {name: 'Token chips', required: false, description: 'Removable chips representing each selected item. Each chip shows a label and a remove button.'},
+ {name: 'Search input', required: true, description: 'The text input where users type to search the data source. Hides when maxEntries is reached.'},
+ {name: 'Dropdown menu', required: false, description: 'The search results list that appears below the input as the user types.'},
+ {name: 'End content', required: false, description: 'A trailing slot after the input for action buttons, counts, or other controls.'},
+ {name: 'Clear button', required: false, description: 'A button that removes all selected tokens at once. Shown when hasClear is true and tokens are present.'},
],
},
};
@@ -356,12 +378,15 @@ export const docsDense = {
description: 'Multi-select typeahead w/ token chips for selected items. Composes XDSBaseTypeahead for search+XDSToken for chips.',
usage: {
description:
- 'Tokenizer is a multi-select input that lets users search and select multiple items displayed as removable token chips. Use Tokenizer when users need to build a set of selections from a searchable data source, such as adding recipients or applying multiple filters.',
+ 'Multi-select input for searching and selecting multiple items as removable chips. Use for team members, tags, filters, or any set built from a searchable source.',
bestPractices: [
- {guidance: true, description: 'Provide a clear placeholder that communicates what users can search for.'},
- {guidance: true, description: 'Set a maxEntries limit when the number of selections should be bounded.'},
- {guidance: false, description: 'Avoid applying colored backgrounds to tokens within a Tokenizer — use the default color for consistency.'},
- {guidance: false, description: 'Avoid using Tokenizer for single-item selection — use Typeahead instead.'},
+ {guidance: true, description: 'Placeholder that communicates what to search \u2014 "Search people\u2026" not blank.'},
+ {guidance: true, description: 'maxEntries when selections are bounded (e.g. 5 approvers max).'},
+ {guidance: true, description: 'hasCreate for free-form tagging with values not in the source.'},
+ {guidance: true, description: 'status prop for immediate validation feedback.'},
+ {guidance: false, description: 'Don\u2019t use for single-item selection \u2014 use Typeahead instead.'},
+ {guidance: false, description: 'Avoid custom token colors \u2014 default style for consistency.'},
+ {guidance: false, description: 'Don\u2019t hide the label unless context makes purpose obvious.'},
],
},
propDescriptions: {