Skip to content

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

TypeScript

Improve Typeahead docs page and block examples (#1594)

Ted McDonaldd53c2314b4a3
diff --git a/packages/cli/templates/blocks/components/Typeahead/TypeaheadLimitedResults.doc.mjs b/packages/cli/templates/blocks/components/Typeahead/TypeaheadLimitedResults.doc.mjs
index fca6ea6930..a4bdf5a0e6 100644
--- a/packages/cli/templates/blocks/components/Typeahead/TypeaheadLimitedResults.doc.mjs
+++ b/packages/cli/templates/blocks/components/Typeahead/TypeaheadLimitedResults.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'Typeahead — Limited Results',
description:
- 'Typeahead with a capped dropdown showing at most three suggestions, ideal for compact selection UIs.',
+ 'Typeahead with a capped dropdown showing at most three results.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Typeahead'],
+ componentsUsed: ['Typeahead', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/Typeahead/TypeaheadLimitedResults.tsx b/packages/cli/templates/blocks/components/Typeahead/TypeaheadLimitedResults.tsx
index e56ed953e8..c9678ae1c3 100644
--- a/packages/cli/templates/blocks/components/Typeahead/TypeaheadLimitedResults.tsx
+++ b/packages/cli/templates/blocks/components/Typeahead/TypeaheadLimitedResults.tsx
@@ -3,16 +3,17 @@
import {useState} from 'react';
import {XDSTypeahead} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+import {XDSCenter} from '@xds/core/Center';
const items: XDSSearchableItem[] = [
- {id: '1', label: 'Apple'},
- {id: '2', label: 'Banana'},
- {id: '3', label: 'Cherry'},
- {id: '4', label: 'Date'},
- {id: '5', label: 'Elderberry'},
- {id: '6', label: 'Fig'},
- {id: '7', label: 'Grape'},
- {id: '8', label: 'Honeydew'},
+ {id: '1', label: 'United States'},
+ {id: '2', label: 'United Kingdom'},
+ {id: '3', label: 'Canada'},
+ {id: '4', label: 'Australia'},
+ {id: '5', label: 'Germany'},
+ {id: '6', label: 'France'},
+ {id: '7', label: 'Japan'},
+ {id: '8', label: 'Brazil'},
];
const searchSource: XDSSearchSource = {
@@ -24,16 +25,16 @@ const searchSource: XDSSearchSource = {
export default function TypeaheadLimitedResults() {
const [value, setValue] = useState<XDSSearchableItem | null>(null);
return (
- <div style={{width: 320}}>
+ <XDSCenter width={320}>
<XDSTypeahead
- label="Fruit"
- placeholder="Search fruits..."
+ label="Country"
+ placeholder="Search countries..."
searchSource={searchSource}
value={value}
onChange={setValue}
hasEntriesOnFocus
maxMenuItems={3}
/>
- </div>
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/Typeahead/TypeaheadSearchField.doc.mjs b/packages/cli/templates/blocks/components/Typeahead/TypeaheadSearchField.doc.mjs
index 6d6a84bcaf..70fa18535f 100644
--- a/packages/cli/templates/blocks/components/Typeahead/TypeaheadSearchField.doc.mjs
+++ b/packages/cli/templates/blocks/components/Typeahead/TypeaheadSearchField.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'Typeahead — Search Field',
description:
- 'Search input with a magnifying glass icon and suggestions that appear on focus before typing.',
+ 'Search input with icon and suggestions on focus.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Typeahead'],
+ componentsUsed: ['Typeahead', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/Typeahead/TypeaheadSearchField.tsx b/packages/cli/templates/blocks/components/Typeahead/TypeaheadSearchField.tsx
index a9ffd069ba..1f73637d85 100644
--- a/packages/cli/templates/blocks/components/Typeahead/TypeaheadSearchField.tsx
+++ b/packages/cli/templates/blocks/components/Typeahead/TypeaheadSearchField.tsx
@@ -3,24 +3,18 @@
import {useState} from 'react';
import {XDSTypeahead} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
-
-function SearchIcon() {
- return (
- <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
- <path strokeLinecap="round" strokeLinejoin="round" d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z" />
- </svg>
- );
-}
+import {XDSCenter} from '@xds/core/Center';
+import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
const items: XDSSearchableItem[] = [
- {id: '1', label: 'Apple'},
- {id: '2', label: 'Banana'},
- {id: '3', label: 'Cherry'},
- {id: '4', label: 'Date'},
- {id: '5', label: 'Elderberry'},
- {id: '6', label: 'Fig'},
- {id: '7', label: 'Grape'},
- {id: '8', label: 'Honeydew'},
+ {id: '1', label: 'Olivia Martin'},
+ {id: '2', label: 'Jackson Lee'},
+ {id: '3', label: 'Isabella Nguyen'},
+ {id: '4', label: 'William Kim'},
+ {id: '5', label: 'Sofia Davis'},
+ {id: '6', label: 'Lucas Brown'},
+ {id: '7', label: 'Mia Wilson'},
+ {id: '8', label: 'Ethan Jones'},
];
const searchSource: XDSSearchSource = {
@@ -32,16 +26,16 @@ const searchSource: XDSSearchSource = {
export default function TypeaheadSearchField() {
const [value, setValue] = useState<XDSSearchableItem | null>(null);
return (
- <div style={{width: 320}}>
+ <XDSCenter width={320}>
<XDSTypeahead
- label="Fruit"
- placeholder="Search fruits..."
+ label="Team member"
+ placeholder="Search people..."
searchSource={searchSource}
value={value}
onChange={setValue}
- startIcon={SearchIcon}
+ startIcon={MagnifyingGlassIcon}
hasEntriesOnFocus
/>
- </div>
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithHelperText.doc.mjs b/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithHelperText.doc.mjs
index 7a71935e49..92a734880f 100644
--- a/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithHelperText.doc.mjs
+++ b/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithHelperText.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'Typeahead — With Helper Text',
description:
- 'Typeahead field with a description below the label providing guidance on what to select.',
+ 'Typeahead with a description below the label.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Typeahead'],
+ componentsUsed: ['Typeahead', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithHelperText.tsx b/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithHelperText.tsx
index 5333e07c53..6ea4224662 100644
--- a/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithHelperText.tsx
+++ b/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithHelperText.tsx
@@ -3,16 +3,17 @@
import {useState} from 'react';
import {XDSTypeahead} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+import {XDSCenter} from '@xds/core/Center';
const items: XDSSearchableItem[] = [
- {id: '1', label: 'Apple'},
- {id: '2', label: 'Banana'},
- {id: '3', label: 'Cherry'},
- {id: '4', label: 'Date'},
- {id: '5', label: 'Elderberry'},
- {id: '6', label: 'Fig'},
- {id: '7', label: 'Grape'},
- {id: '8', label: 'Honeydew'},
+ {id: '1', label: 'Engineering'},
+ {id: '2', label: 'Design'},
+ {id: '3', label: 'Marketing'},
+ {id: '4', label: 'Sales'},
+ {id: '5', label: 'Product'},
+ {id: '6', label: 'Finance'},
+ {id: '7', label: 'Legal'},
+ {id: '8', label: 'Operations'},
];
const searchSource: XDSSearchSource = {
@@ -24,15 +25,15 @@ const searchSource: XDSSearchSource = {
export default function TypeaheadWithHelperText() {
const [value, setValue] = useState<XDSSearchableItem | null>(null);
return (
- <div style={{width: 320}}>
+ <XDSCenter width={320}>
<XDSTypeahead
- label="Fruit"
- placeholder="Search fruits..."
+ label="Department"
+ placeholder="Search departments..."
searchSource={searchSource}
value={value}
onChange={setValue}
- description="Pick your favorite fruit from the list"
+ description="Select the department this request should be routed to"
/>
- </div>
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithValidation.doc.mjs b/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithValidation.doc.mjs
index e2be0a7740..f4c0c42cc4 100644
--- a/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithValidation.doc.mjs
+++ b/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithValidation.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'Typeahead — With Validation',
description:
- 'Typeahead field displaying an error validation message, useful in form contexts requiring selection.',
+ 'Typeahead with an error validation message.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Typeahead'],
+ componentsUsed: ['Typeahead', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithValidation.tsx b/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithValidation.tsx
index a5a3a2d99b..14e2ddd478 100644
--- a/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithValidation.tsx
+++ b/packages/cli/templates/blocks/components/Typeahead/TypeaheadWithValidation.tsx
@@ -3,16 +3,17 @@
import {useState} from 'react';
import {XDSTypeahead} from '@xds/core/Typeahead';
import type {XDSSearchableItem, XDSSearchSource} from '@xds/core/Typeahead';
+import {XDSCenter} from '@xds/core/Center';
const items: XDSSearchableItem[] = [
- {id: '1', label: 'Apple'},
- {id: '2', label: 'Banana'},
- {id: '3', label: 'Cherry'},
- {id: '4', label: 'Date'},
- {id: '5', label: 'Elderberry'},
- {id: '6', label: 'Fig'},
- {id: '7', label: 'Grape'},
- {id: '8', label: 'Honeydew'},
+ {id: '1', label: 'New York'},
+ {id: '2', label: 'San Francisco'},
+ {id: '3', label: 'London'},
+ {id: '4', label: 'Berlin'},
+ {id: '5', label: 'Tokyo'},
+ {id: '6', label: 'Singapore'},
+ {id: '7', label: 'Sydney'},
+ {id: '8', label: 'Toronto'},
];
const searchSource: XDSSearchSource = {
@@ -24,15 +25,15 @@ const searchSource: XDSSearchSource = {
export default function TypeaheadWithValidation() {
const [value, setValue] = useState<XDSSearchableItem | null>(null);
return (
- <div style={{width: 320}}>
+ <XDSCenter width={320}>
<XDSTypeahead
- label="Fruit"
- placeholder="Search fruits..."
+ label="Office"
+ placeholder="Search offices..."
searchSource={searchSource}
value={value}
onChange={setValue}
- status={{type: 'error', message: 'Please select a fruit'}}
+ status={{type: 'error', message: 'Please select an office location'}}
/>
- </div>
+ </XDSCenter>
);
}
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index d776262428..846b29383e 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -301,12 +301,14 @@ export const docs = {
},
usage: {
description:
- 'Typeahead is a searchable dropdown for selecting a single item from a large or dynamic dataset. Use Typeahead when users benefit from search-as-you-type to quickly find and select an option. For small fixed lists, use Selector instead; for multiple selections, use Tokenizer.',
+ 'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',
bestPractices: [
{guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
- {guidance: true, description: 'Enable hasEntriesOnFocus when users benefit from seeing popular or recent options before typing.'},
- {guidance: false, description: 'Avoid using Typeahead for short, static option lists — use Selector for better discoverability.'},
- {guidance: false, description: 'Avoid placing multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
+ {guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},
+ {guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},
+ {guidance: false, description: 'Use for short, static option lists — use Selector for better discoverability.'},
+ {guidance: false, description: 'Use for multi-selection — use Tokenizer instead.'},
+ {guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
],
},
};
@@ -612,12 +614,14 @@ export const docsZh = {
},
usage: {
description:
- 'Typeahead is a searchable dropdown for selecting a single item from a large or dynamic dataset. Use Typeahead when users benefit from search-as-you-type to quickly find and select an option. For small fixed lists, use Selector instead; for multiple selections, use Tokenizer.',
+ 'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',
bestPractices: [
{guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
- {guidance: true, description: 'Enable hasEntriesOnFocus when users benefit from seeing popular or recent options before typing.'},
- {guidance: false, description: 'Avoid using Typeahead for short, static option lists — use Selector for better discoverability.'},
- {guidance: false, description: 'Avoid placing multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
+ {guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},
+ {guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},
+ {guidance: false, description: 'Use for short, static option lists — use Selector for better discoverability.'},
+ {guidance: false, description: 'Use for multi-selection — use Tokenizer instead.'},
+ {guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
],
},
};
@@ -627,12 +631,14 @@ export const docsDense = {
description: 'Searchable dropdown for single-item selection w/ keyboard navigation. Supports async+sync search via searchSource interface.',
usage: {
description:
- 'Typeahead is a searchable dropdown for selecting a single item from a large or dynamic dataset. Use Typeahead when users benefit from search-as-you-type to quickly find and select an option. For small fixed lists, use Selector instead; for multiple selections, use Tokenizer.',
+ 'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',
bestPractices: [
{guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
- {guidance: true, description: 'Enable hasEntriesOnFocus when users benefit from seeing popular or recent options before typing.'},
- {guidance: false, description: 'Avoid using Typeahead for short, static option lists — use Selector for better discoverability.'},
- {guidance: false, description: 'Avoid placing multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
+ {guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},
+ {guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},
+ {guidance: false, description: 'Use for short, static option lists — use Selector for better discoverability.'},
+ {guidance: false, description: 'Use for multi-selection — use Tokenizer instead.'},
+ {guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
],
},
components: [