An open source design system that's fully customizable and agent ready
TypeScript
Improve TextInput docs page and block examples (#1572)
Kenton Quatmanfa3fe4fa26db
diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputBasicTextInput.doc.mjs b/packages/cli/templates/blocks/components/TextInput/TextInputBasicTextInput.doc.mjsdeleted file mode 100644index ebe421df10..0000000000--- a/packages/cli/templates/blocks/components/TextInput/TextInputBasicTextInput.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'TextInput — Basic',- description:- 'Simple text input with label and description for single-line data entry.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['TextInput'],-};diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputBasicTextInput.tsx b/packages/cli/templates/blocks/components/TextInput/TextInputBasicTextInput.tsxdeleted file mode 100644index 6f53c39ccb..0000000000--- a/packages/cli/templates/blocks/components/TextInput/TextInputBasicTextInput.tsx+++ /dev/null@@ -1,17 +0,0 @@-'use client';--import {useState} from 'react';-import {XDSTextInput} from '@xds/core/TextInput';--export default function TextInputBasicTextInput() {- const [value, setValue] = useState('');- return (- <XDSTextInput- label="Email"- description="We'll never share your email with anyone."- value={value}- onChange={setValue}- placeholder="Enter your email"- />- );-}diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputPasswordInput.doc.mjs b/packages/cli/templates/blocks/components/TextInput/TextInputPasswordInput.doc.mjsdeleted file mode 100644index eeebaab5c7..0000000000--- a/packages/cli/templates/blocks/components/TextInput/TextInputPasswordInput.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'TextInput — Password',- description:- 'Password input with masked characters for secure credential entry.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['TextInput'],-};diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputPasswordInput.tsx b/packages/cli/templates/blocks/components/TextInput/TextInputPasswordInput.tsxdeleted file mode 100644index 35436f8fb9..0000000000--- a/packages/cli/templates/blocks/components/TextInput/TextInputPasswordInput.tsx+++ /dev/null@@ -1,17 +0,0 @@-'use client';--import {useState} from 'react';-import {XDSTextInput} from '@xds/core/TextInput';--export default function TextInputPasswordInput() {- const [value, setValue] = useState('');- return (- <XDSTextInput- type="password"- label="Password"- value={value}- onChange={setValue}- placeholder="Enter your password"- />- );-}diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputSearchInput.doc.mjs b/packages/cli/templates/blocks/components/TextInput/TextInputSearchInput.doc.mjsindex 1cd2ac883e..b302448fea 100644--- a/packages/cli/templates/blocks/components/TextInput/TextInputSearchInput.doc.mjs+++ b/packages/cli/templates/blocks/components/TextInput/TextInputSearchInput.doc.mjs@@ -2,9 +2,8 @@export const doc = {type: 'block',name: 'TextInput — Search',- description:- 'Search input with hidden label, search icon, and clear button.',+ description: 'Search input with a hidden label, start icon, and clear button. Use for toolbar and header search bars where the icon provides sufficient context.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['TextInput'],+ aspectRatio: 16 / 9,+ componentsUsed: ['TextInput', 'Layout'],};diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputSearchInput.tsx b/packages/cli/templates/blocks/components/TextInput/TextInputSearchInput.tsxindex 7af41671a8..bd6401a8f2 100644--- a/packages/cli/templates/blocks/components/TextInput/TextInputSearchInput.tsx+++ b/packages/cli/templates/blocks/components/TextInput/TextInputSearchInput.tsx@@ -2,36 +2,33 @@import {useState} from 'react';import {XDSTextInput} from '@xds/core/TextInput';--function SearchIcon(props: React.SVGProps<SVGSVGElement>) {- return (- <svg- xmlns="http://www.w3.org/2000/svg"- fill="none"- viewBox="0 0 24 24"- strokeWidth={1.5}- stroke="currentColor"- {...props}>- <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 {XDSStack} from '@xds/core/Layout';+import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';export default function TextInputSearchInput() {- const [value, setValue] = useState('');+ const [query, setQuery] = useState('');+ const [filter, setFilter] = useState('design systems');+return (- <XDSTextInput- label="Search"- isLabelHidden- value={value}- onChange={setValue}- placeholder="Search..."- startIcon={SearchIcon}- hasClear- />+ <XDSStack direction="vertical" gap={3}>+ <XDSTextInput+ label="Search"+ isLabelHidden+ value={query}+ onChange={setQuery}+ placeholder="Search projects…"+ startIcon={MagnifyingGlassIcon}+ hasClear+ />+ <XDSTextInput+ label="Filter results"+ isLabelHidden+ value={filter}+ onChange={setFilter}+ placeholder="Filter…"+ startIcon={MagnifyingGlassIcon}+ hasClear+ />+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputShowcase.doc.mjs b/packages/cli/templates/blocks/components/TextInput/TextInputShowcase.doc.mjsindex 2393b6b375..5642f8e18b 100644--- a/packages/cli/templates/blocks/components/TextInput/TextInputShowcase.doc.mjs+++ b/packages/cli/templates/blocks/components/TextInput/TextInputShowcase.doc.mjs@@ -3,6 +3,6 @@ export const doc = {type: 'block',name: 'TextInput',isReady: true,- aspectRatio: 1,+ aspectRatio: 16 / 9,isShowcase: true,};diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputSizes.doc.mjs b/packages/cli/templates/blocks/components/TextInput/TextInputSizes.doc.mjsnew file mode 100644index 0000000000..4f9b4d7900--- /dev/null+++ b/packages/cli/templates/blocks/components/TextInput/TextInputSizes.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'TextInput — Sizes',+ description: 'Small, medium, and large inputs side by side. Use small in dense UIs like table filters, medium for most forms, and large for prominent single-field pages.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['TextInput', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputSizes.tsx b/packages/cli/templates/blocks/components/TextInput/TextInputSizes.tsxnew file mode 100644index 0000000000..c592d8d0b8--- /dev/null+++ b/packages/cli/templates/blocks/components/TextInput/TextInputSizes.tsx@@ -0,0 +1,37 @@+'use client';++import {useState} from 'react';+import {XDSTextInput} from '@xds/core/TextInput';+import {XDSStack} from '@xds/core/Layout';++export default function TextInputSizes() {+ const [sm, setSm] = useState('');+ const [md, setMd] = useState('');+ const [lg, setLg] = useState('');++ return (+ <XDSStack direction="vertical" gap={3}>+ <XDSTextInput+ label="Small"+ value={sm}+ onChange={setSm}+ placeholder="Enter a value"+ size="sm"+ />+ <XDSTextInput+ label="Medium"+ value={md}+ onChange={setMd}+ placeholder="Enter a value"+ size="md"+ />+ <XDSTextInput+ label="Large"+ value={lg}+ onChange={setLg}+ placeholder="Enter a value"+ size="lg"+ />+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputStates.doc.mjs b/packages/cli/templates/blocks/components/TextInput/TextInputStates.doc.mjsnew file mode 100644index 0000000000..e670f9e55d--- /dev/null+++ b/packages/cli/templates/blocks/components/TextInput/TextInputStates.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'TextInput — States',+ description: 'Text, password, and email inputs in default, disabled, and loading states. Shows the three input types side by side with realistic data.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['TextInput', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputStates.tsx b/packages/cli/templates/blocks/components/TextInput/TextInputStates.tsxnew file mode 100644index 0000000000..604b4bbf65--- /dev/null+++ b/packages/cli/templates/blocks/components/TextInput/TextInputStates.tsx@@ -0,0 +1,49 @@+'use client';++import {useState} from 'react';+import {XDSTextInput} from '@xds/core/TextInput';+import {XDSStack} from '@xds/core/Layout';++export default function TextInputStates() {+ const [text, setText] = useState('Sarah Chen');+ const [password, setPassword] = useState('hunter42');+ const [email, setEmail] = useState('[email protected]');++ return (+ <XDSStack direction="vertical" gap={3}>+ <XDSTextInput+ label="Default field"+ value={text}+ onChange={setText}+ placeholder="Enter a value"+ />+ <XDSTextInput+ type="password"+ label="Password field"+ value={password}+ onChange={setPassword}+ placeholder="Enter a value"+ />+ <XDSTextInput+ type="email"+ label="Email field"+ value={email}+ onChange={setEmail}+ placeholder="Enter a value"+ />+ <XDSTextInput+ label="Disabled field"+ value=""+ onChange={() => {}}+ placeholder="Enter a value"+ isDisabled+ />+ <XDSTextInput+ label="Loading field"+ value="sarahc"+ onChange={() => {}}+ isLoading+ />+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputWithIcon.doc.mjs b/packages/cli/templates/blocks/components/TextInput/TextInputWithIcon.doc.mjsnew file mode 100644index 0000000000..67208cad17--- /dev/null+++ b/packages/cli/templates/blocks/components/TextInput/TextInputWithIcon.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'TextInput — Icon',+ description: 'Inputs with a leading icon that hints at the expected content. Use when the icon helps users identify the field faster, like a lock for passwords or an envelope for email.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['TextInput', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputWithIcon.tsx b/packages/cli/templates/blocks/components/TextInput/TextInputWithIcon.tsxnew file mode 100644index 0000000000..4b51fcbd2a--- /dev/null+++ b/packages/cli/templates/blocks/components/TextInput/TextInputWithIcon.tsx@@ -0,0 +1,53 @@+'use client';++import {useState} from 'react';+import {XDSTextInput} from '@xds/core/TextInput';+import {XDSStack} from '@xds/core/Layout';+import {+ EnvelopeIcon,+ LockClosedIcon,+ UserIcon,+ GlobeAltIcon,+} from '@heroicons/react/24/outline';++export default function TextInputWithIcon() {+ const [name, setName] = useState('');+ const [email, setEmail] = useState('');+ const [password, setPassword] = useState('');+ const [website, setWebsite] = useState('');++ return (+ <XDSStack direction="vertical" gap={3}>+ <XDSTextInput+ label="Full name"+ value={name}+ onChange={setName}+ placeholder="Sarah Chen"+ startIcon={UserIcon}+ />+ <XDSTextInput+ type="email"+ label="Email"+ value={email}+ onChange={setEmail}+ placeholder="[email protected]"+ startIcon={EnvelopeIcon}+ />+ <XDSTextInput+ type="password"+ label="Password"+ value={password}+ onChange={setPassword}+ placeholder="Enter your password"+ startIcon={LockClosedIcon}+ />+ <XDSTextInput+ label="Website"+ value={website}+ onChange={setWebsite}+ placeholder="https://example.com"+ startIcon={GlobeAltIcon}+ />+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputWithValidation.doc.mjs b/packages/cli/templates/blocks/components/TextInput/TextInputWithValidation.doc.mjsindex cea4082a9c..677ffa9ea2 100644--- a/packages/cli/templates/blocks/components/TextInput/TextInputWithValidation.doc.mjs+++ b/packages/cli/templates/blocks/components/TextInput/TextInputWithValidation.doc.mjs@@ -1,10 +1,9 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'TextInput — Email Validation',- description:- 'Text input with dynamic email validation providing real-time status feedback.',+ name: 'TextInput — Validation',+ description: 'Error, warning, and success validation states with status messages. Use to show users what went wrong and how to fix it.',isReady: true,aspectRatio: 4 / 3,- componentsUsed: ['TextInput'],+ componentsUsed: ['TextInput', 'Layout'],};diff --git a/packages/cli/templates/blocks/components/TextInput/TextInputWithValidation.tsx b/packages/cli/templates/blocks/components/TextInput/TextInputWithValidation.tsxindex c33153655f..c3d443ff5a 100644--- a/packages/cli/templates/blocks/components/TextInput/TextInputWithValidation.tsx+++ b/packages/cli/templates/blocks/components/TextInput/TextInputWithValidation.tsx@@ -2,28 +2,36 @@import {useState} from 'react';import {XDSTextInput} from '@xds/core/TextInput';+import {XDSStack} from '@xds/core/Layout';export default function TextInputWithValidation() {- const [value, setValue] = useState('');-- const getStatus = () => {- if (value.length === 0) return undefined;- if (!value.includes('@')) {- return {- type: 'error' as const,- message: 'Please enter a valid email address',- };- }- return {type: 'success' as const, message: 'Email looks good!'};- };+ const [error, setError] = useState('sarah@');+ const [warning, setWarning] = useState('sarah_chen');+ const [success, setSuccess] = useState('https://sarahchen.dev');return (- <XDSTextInput- label="Email"- value={value}- onChange={setValue}- placeholder="Enter your email"- status={getStatus()}- />+ <XDSStack direction="vertical" gap={3}>+ <XDSTextInput+ label="Error message"+ value={error}+ onChange={setError}+ placeholder="Enter a value"+ status={{type: 'error', message: 'Please enter a valid email address.'}}+ />+ <XDSTextInput+ label="Warning message"+ value={warning}+ onChange={setWarning}+ placeholder="Enter a value"+ status={{type: 'warning', message: 'This username is already taken — try adding a number.'}}+ />+ <XDSTextInput+ label="Success message"+ value={success}+ onChange={setSuccess}+ placeholder="Enter a value"+ status={{type: 'success', message: 'URL is valid and reachable.'}}+ />+ </XDSStack>);}diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjsindex 3aa7e526ad..4768ab72fc 100644--- a/packages/core/src/TextInput/TextInput.doc.mjs+++ b/packages/core/src/TextInput/TextInput.doc.mjs@@ -131,19 +131,24 @@ export const docs = {},usage: {description:- 'TextInput enables users to enter or edit short-form text such as names, emails, or search queries. Use it for single-line values where the expected input is brief, and pair it with validation status to guide users through required fields.',+ 'TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.',bestPractices: [- { guidance: true, description: 'Size the input to reflect the expected content length so users can gauge how much to type.' },- { guidance: true, description: 'Use validation status messages to provide clear, contextual feedback on field errors.' },- { guidance: false, description: 'Use a TextInput for multi-line content like comments or descriptions — use TextArea instead.' },- { guidance: false, description: 'Rely on placeholder text as a substitute for a label.' },+ {guidance: true, description: 'Always provide a visible label so users know what the field is for. Only hide the label when surrounding context makes it obvious, like a search bar with a magnifying-glass icon.'},+ {guidance: true, description: 'Use validation status with a message to explain what went wrong — "Email must include @" is better than just turning the border red.'},+ {guidance: true, description: 'Size the input to match the expected content length so users can gauge how much to type — small for zip codes, medium for names, large for URLs.'},+ {guidance: true, description: 'Add a clear button for search and filter inputs so users can quickly reset without selecting all text.'},+ {guidance: false, description: "Don't use placeholder text as a replacement for a label — placeholders disappear on focus and are not reliably read by screen readers."},+ {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions — use TextArea instead."},+ {guidance: false, description: "Don't mark every field as required — only flag truly mandatory fields so users are not overwhelmed by validation errors."},],anatomy: [- {name: 'Label', required: true, description: 'Text that identifies the input field.'},- {name: 'Description', required: false, description: 'Helper text providing additional context.'},- {name: 'Icon', required: false, description: '16px icon displayed inside the input.'},- {name: 'Placeholder', required: false, description: 'Hint text shown when the input is empty.'},- {name: 'Spinner', required: false, description: 'Loading indicator for pending actions.'},+ {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},+ {name: 'Description', required: false, description: 'Helper text between the label and the input that provides additional context or formatting hints.'},+ {name: 'Start icon', required: false, description: 'A leading icon inside the input that hints at the expected content, like a magnifying glass for search.'},+ {name: 'Placeholder', required: false, description: 'Hint text shown when the input is empty. Disappears on focus.'},+ {name: 'Clear button', required: false, description: 'A trailing × button that resets the value and returns focus to the input.'},+ {name: 'Spinner', required: false, description: 'Loading indicator that appears during async actions like server-side validation.'},+ {name: 'Status icon', required: false, description: 'A trailing icon (error, warning, or success) that communicates validation state.'},],},};@@ -277,19 +282,24 @@ export const docsZh = {},usage: {description:- 'TextInput enables users to enter or edit short-form text such as names, emails, or search queries. Use it for single-line values where the expected input is brief, and pair it with validation status to guide users through required fields.',+ 'TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.',bestPractices: [- { guidance: true, description: 'Size the input to reflect the expected content length so users can gauge how much to type.' },- { guidance: true, description: 'Use validation status messages to provide clear, contextual feedback on field errors.' },- { guidance: false, description: 'Use a TextInput for multi-line content like comments or descriptions — use TextArea instead.' },- { guidance: false, description: 'Rely on placeholder text as a substitute for a label.' },+ {guidance: true, description: 'Always provide a visible label so users know what the field is for. Only hide the label when surrounding context makes it obvious, like a search bar with a magnifying-glass icon.'},+ {guidance: true, description: 'Use validation status with a message to explain what went wrong — "Email must include @" is better than just turning the border red.'},+ {guidance: true, description: 'Size the input to match the expected content length so users can gauge how much to type — small for zip codes, medium for names, large for URLs.'},+ {guidance: true, description: 'Add a clear button for search and filter inputs so users can quickly reset without selecting all text.'},+ {guidance: false, description: "Don't use placeholder text as a replacement for a label — placeholders disappear on focus and are not reliably read by screen readers."},+ {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions — use TextArea instead."},+ {guidance: false, description: "Don't mark every field as required — only flag truly mandatory fields so users are not overwhelmed by validation errors."},],anatomy: [- {name: 'Label', required: true, description: 'Text that identifies the input field.'},- {name: 'Description', required: false, description: 'Helper text providing additional context.'},- {name: 'Icon', required: false, description: '16px icon displayed inside the input.'},- {name: 'Placeholder', required: false, description: 'Hint text shown when the input is empty.'},- {name: 'Spinner', required: false, description: 'Loading indicator for pending actions.'},+ {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},+ {name: 'Description', required: false, description: 'Helper text between the label and the input that provides additional context or formatting hints.'},+ {name: 'Start icon', required: false, description: 'A leading icon inside the input that hints at the expected content, like a magnifying glass for search.'},+ {name: 'Placeholder', required: false, description: 'Hint text shown when the input is empty. Disappears on focus.'},+ {name: 'Clear button', required: false, description: 'A trailing × button that resets the value and returns focus to the input.'},+ {name: 'Spinner', required: false, description: 'Loading indicator that appears during async actions like server-side validation.'},+ {name: 'Status icon', required: false, description: 'A trailing icon (error, warning, or success) that communicates validation state.'},],},};@@ -299,19 +309,24 @@ export const docsDense = {description: 'Text input for collecting user text w/ label, description, validation status, optional/required indicators.',usage: {description:- 'TextInput enables users to enter or edit short-form text such as names, emails, or search queries. Use it for single-line values where the expected input is brief, and pair it with validation status to guide users through required fields.',+ 'TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.',bestPractices: [- { guidance: true, description: 'Size the input to reflect the expected content length so users can gauge how much to type.' },- { guidance: true, description: 'Use validation status messages to provide clear, contextual feedback on field errors.' },- { guidance: false, description: 'Use a TextInput for multi-line content like comments or descriptions — use TextArea instead.' },- { guidance: false, description: 'Rely on placeholder text as a substitute for a label.' },+ {guidance: true, description: 'Always provide a visible label so users know what the field is for. Only hide the label when surrounding context makes it obvious, like a search bar with a magnifying-glass icon.'},+ {guidance: true, description: 'Use validation status with a message to explain what went wrong — "Email must include @" is better than just turning the border red.'},+ {guidance: true, description: 'Size the input to match the expected content length so users can gauge how much to type — small for zip codes, medium for names, large for URLs.'},+ {guidance: true, description: 'Add a clear button for search and filter inputs so users can quickly reset without selecting all text.'},+ {guidance: false, description: "Don't use placeholder text as a replacement for a label — placeholders disappear on focus and are not reliably read by screen readers."},+ {guidance: false, description: "Don't use TextInput for multi-line content like comments or descriptions — use TextArea instead."},+ {guidance: false, description: "Don't mark every field as required — only flag truly mandatory fields so users are not overwhelmed by validation errors."},],anatomy: [- {name: 'Label', required: true, description: 'Text that identifies the input field.'},- {name: 'Description', required: false, description: 'Helper text providing additional context.'},- {name: 'Icon', required: false, description: '16px icon displayed inside the input.'},- {name: 'Placeholder', required: false, description: 'Hint text shown when the input is empty.'},- {name: 'Spinner', required: false, description: 'Loading indicator for pending actions.'},+ {name: 'Label', required: true, description: 'Text that identifies the field. Always rendered for accessibility even when visually hidden.'},+ {name: 'Description', required: false, description: 'Helper text between the label and the input that provides additional context or formatting hints.'},+ {name: 'Start icon', required: false, description: 'A leading icon inside the input that hints at the expected content, like a magnifying glass for search.'},+ {name: 'Placeholder', required: false, description: 'Hint text shown when the input is empty. Disappears on focus.'},+ {name: 'Clear button', required: false, description: 'A trailing × button that resets the value and returns focus to the input.'},+ {name: 'Spinner', required: false, description: 'Loading indicator that appears during async actions like server-side validation.'},+ {name: 'Status icon', required: false, description: 'A trailing icon (error, warning, or success) that communicates validation state.'},],},propDescriptions: {