An open source design system that's fully customizable and agent ready
TypeScript
Improve TextArea docs page and block examples (#1573)
Kenton Quatmana943d20f29ce
diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.doc.mjsdeleted file mode 100644index 40656405fc..0000000000--- a/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'TextArea — Basic',- description:- 'Simple textarea with label and description for multi-line text entry.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['TextArea'],-};diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.tsxdeleted file mode 100644index f36a2b1602..0000000000--- a/packages/cli/templates/blocks/components/TextArea/TextAreaBasicTextArea.tsx+++ /dev/null@@ -1,17 +0,0 @@-'use client';--import {useState} from 'react';-import {XDSTextArea} from '@xds/core/TextArea';--export default function TextAreaBasicTextArea() {- const [value, setValue] = useState('');- return (- <XDSTextArea- label="Bio"- description="Tell us about yourself in a few sentences."- value={value}- onChange={setValue}- placeholder="Write your bio here..."- />- );-}diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.doc.mjssimilarity index 58%rename from packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.doc.mjsrename to packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.doc.mjsindex 1914529d93..faa9d73ed3 100644--- a/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.doc.mjs+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.doc.mjs@@ -2,9 +2,8 @@export const doc = {type: 'block',name: 'TextArea — Character Count',- description:- 'Textarea with a maximum character limit and live counter display.',+ description: 'Textareas with maxLength and a live character counter. The counter turns red when the limit is exceeded.',isReady: true,- aspectRatio: 4 / 3,+ aspectRatio: 16 / 9,componentsUsed: ['TextArea'],};diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.tsxnew file mode 100644index 0000000000..a7b4d105d0--- /dev/null+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaCharacterCount.tsx@@ -0,0 +1,21 @@+'use client';++import {useState} from 'react';+import {XDSTextArea} from '@xds/core/TextArea';++export default function TextAreaCharacterCount() {+ const [value, setValue] = useState(+ 'Excited to announce that our team just shipped the new dashboard! Check it out and let us know what you think.',+ );++ return (+ <XDSTextArea+ label="Status update"+ value={value}+ onChange={setValue}+ placeholder="What's on your mind?"+ maxLength={280}+ rows={3}+ />+ );+}diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaStates.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaStates.doc.mjsnew file mode 100644index 0000000000..d61a46ebb4--- /dev/null+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaStates.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'TextArea — States',+ description: 'Required, disabled, and loading textareas side by side. Shows the interactive states the component supports.',+ isReady: true,+ aspectRatio: 1,+ componentsUsed: ['TextArea', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaStates.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaStates.tsxnew file mode 100644index 0000000000..cd1c756ce5--- /dev/null+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaStates.tsx@@ -0,0 +1,34 @@+'use client';++import {useState} from 'react';+import {XDSTextArea} from '@xds/core/TextArea';+import {XDSStack} from '@xds/core/Layout';++export default function TextAreaStates() {+ const [requiredValue, setRequiredValue] = useState('');++ return (+ <XDSStack direction="vertical" gap={4}>+ <XDSTextArea+ label="Required field"+ value={requiredValue}+ onChange={setRequiredValue}+ placeholder="Describe the issue..."+ isRequired+ />+ <XDSTextArea+ label="Disabled field"+ value="This field is read-only and cannot be edited."+ onChange={() => {}}+ isDisabled+ />+ <XDSTextArea+ label="Loading field"+ value=""+ onChange={() => {}}+ placeholder="Generating summary..."+ isLoading+ />+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjsnew file mode 100644index 0000000000..51752300ca--- /dev/null+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'TextArea — Validation',+ description: 'All three status variants — error, warning, and success — with status messages. Use to show inline validation feedback as the user types.',+ isReady: true,+ aspectRatio: 1,+ componentsUsed: ['TextArea', 'Layout'],+};diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.tsxnew file mode 100644index 0000000000..3bc936cac3--- /dev/null+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaValidation.tsx@@ -0,0 +1,45 @@+'use client';++import {useState} from 'react';+import {XDSTextArea} from '@xds/core/TextArea';+import {XDSStack} from '@xds/core/Layout';++export default function TextAreaValidation() {+ const [errorValue, setErrorValue] = useState('Fix the');+ const [warningValue, setWarningValue] = useState('Summarize the Q2 results');+ const [successValue, setSuccessValue] = useState(+ 'Redesign the onboarding flow to reduce drop-off by 15% in Q3. Focus on simplifying the account creation step and adding a progress indicator.',+ );++ return (+ <XDSStack direction="vertical" gap={4}>+ <XDSTextArea+ label="Error message"+ value={errorValue}+ onChange={setErrorValue}+ status={{+ type: 'error',+ message: 'Description must be at least 20 characters.',+ }}+ />+ <XDSTextArea+ label="Warning message"+ value={warningValue}+ onChange={setWarningValue}+ status={{+ type: 'warning',+ message: 'Consider adding more detail for clarity.',+ }}+ />+ <XDSTextArea+ label="Success message"+ value={successValue}+ onChange={setSuccessValue}+ status={{+ type: 'success',+ message: 'Looks good — clear and actionable.',+ }}+ />+ </XDSStack>+ );+}diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.tsxdeleted file mode 100644index 5eb1f2ceaf..0000000000--- a/packages/cli/templates/blocks/components/TextArea/TextAreaWithCharacterCount.tsx+++ /dev/null@@ -1,17 +0,0 @@-'use client';--import {useState} from 'react';-import {XDSTextArea} from '@xds/core/TextArea';--export default function TextAreaWithCharacterCount() {- const [value, setValue] = useState('');- return (- <XDSTextArea- label="Bio"- value={value}- onChange={setValue}- placeholder="Tell us about yourself..."- maxLength={150}- />- );-}diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.doc.mjsnew file mode 100644index 0000000000..d9ed36bb0e--- /dev/null+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.doc.mjs@@ -0,0 +1,9 @@+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */+export const doc = {+ type: 'block',+ name: 'TextArea — Icon',+ description: 'Textareas with a leading icon that hints at the expected content, like a chat bubble for messages or a pencil for notes.',+ isReady: true,+ aspectRatio: 16 / 9,+ componentsUsed: ['TextArea'],+};diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.tsxnew file mode 100644index 0000000000..7eb1c6fab1--- /dev/null+++ b/packages/cli/templates/blocks/components/TextArea/TextAreaWithIcon.tsx@@ -0,0 +1,20 @@+'use client';++import {useState} from 'react';+import {XDSTextArea} from '@xds/core/TextArea';+import {PencilSquareIcon} from '@heroicons/react/24/outline';++export default function TextAreaWithIcon() {+ const [value, setValue] = useState('');++ return (+ <XDSTextArea+ label="Meeting notes"+ description="Capture key decisions and action items."+ value={value}+ onChange={setValue}+ placeholder="What was discussed?"+ startIcon={PencilSquareIcon}+ />+ );+}diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.doc.mjs b/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.doc.mjsdeleted file mode 100644index 610504e33f..0000000000--- a/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.doc.mjs+++ /dev/null@@ -1,10 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'TextArea — Dynamic Validation',- description:- 'Textarea with dynamic validation feedback that changes status as the user types.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['TextArea'],-};diff --git a/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.tsx b/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.tsxdeleted file mode 100644index 5bbf172808..0000000000--- a/packages/cli/templates/blocks/components/TextArea/TextAreaWithValidation.tsx+++ /dev/null@@ -1,27 +0,0 @@-'use client';--import {useState} from 'react';-import {XDSTextArea} from '@xds/core/TextArea';--export default function TextAreaWithValidation() {- const [value, setValue] = useState('');- return (- <div style={{maxWidth: 400}}>- <XDSTextArea- label="Description"- description="Provide a comprehensive description of your project"- value={value}- onChange={setValue}- placeholder="Enter description..."- isRequired- status={- value.length > 0 && value.length < 20- ? {type: 'warning', message: 'Consider adding more detail'}- : value.length >= 20- ? {type: 'success', message: 'Description looks good!'}- : undefined- }- />- </div>- );-}diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjsindex bd28038ef1..f02a4f0c19 100644--- a/packages/core/src/TextArea/TextArea.doc.mjs+++ b/packages/core/src/TextArea/TextArea.doc.mjs@@ -155,12 +155,15 @@ export const docs = {},usage: {description:- 'TextArea is a multi-line text input for collecting longer-form content such as comments, messages, or descriptions. Use it when the expected input exceeds a single line, and choose TextInput for shorter single-line values.',+ 'TextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.',bestPractices: [- { guidance: true, description: 'Provide a visible label or set isLabelHidden with a descriptive label for screen readers.' },- { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit to help users stay within bounds.' },- { guidance: false, description: 'Use a TextArea for short, single-line values like names or emails — use TextInput instead.' },- { guidance: false, description: 'Rely solely on placeholder text to communicate the purpose of the field.' },+ { guidance: true, description: 'Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers.' },+ { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit — it helps users stay within bounds before they submit.' },+ { guidance: true, description: 'Use the status prop to surface validation feedback inline — show success when input is valid, warning for soft limits, and error for hard failures.' },+ { guidance: true, description: 'Add a description or placeholder to clarify expected content, like "Describe the issue in detail" — but never rely on placeholder alone as the only label.' },+ { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails — use TextInput instead.' },+ { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field — placeholders disappear on focus and are not accessible labels.' },+ { guidance: false, description: 'Don\'t show a status message without also setting the status type — the colored border and icon are what draw the user\'s attention to the message.' },],},};@@ -177,8 +180,7 @@ export const docsZh = {{name: 'label',type: 'string',- description:- '文本域的标签文本 — 始终渲染以确保无障碍性。',+ description: '文本域的标签文本 — 始终渲染以确保无障碍性。',required: true,},{@@ -195,14 +197,12 @@ export const docsZh = {{name: 'onChangeAction',type: '(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void | Promise<void>',- description:- '在 React transition 内于 onChange 之后触发的异步操作。通过 useOptimistic 启用乐观更新。',+ description: '在 React transition 内于 onChange 之后触发的异步操作。通过 useOptimistic 启用乐观更新。',},{name: 'isLabelHidden',type: 'boolean',- description:- '视觉上隐藏标签,同时保持屏幕阅读器的无障碍性。',+ description: '视觉上隐藏标签,同时保持屏幕阅读器的无障碍性。',default: 'false',},{@@ -213,15 +213,13 @@ export const docsZh = {{name: 'isOptional',type: 'boolean',- description:- '在标签旁显示"可选"指示器。与 isRequired 互斥。',+ description: '在标签旁显示"可选"指示器。与 isRequired 互斥。',default: 'false',},{name: 'isRequired',type: 'boolean',- description:- '在标签旁显示"必填"指示器并设置 aria-required。与 isOptional 互斥。',+ description: '在标签旁显示"必填"指示器并设置 aria-required。与 isOptional 互斥。',default: 'false',},{@@ -233,8 +231,7 @@ export const docsZh = {{name: 'isLoading',type: 'boolean',- description:- '使文本域进入加载状态,在输入框内显示旋转器。',+ description: '使文本域进入加载状态,在输入框内显示旋转器。',default: 'false',},{@@ -251,26 +248,22 @@ export const docsZh = {{name: 'maxLength',type: 'number',- description:- '允许的最大字符数。设置后,在文本域下方显示字符计数器(当前/最大)。不原生强制限制——超出时计数器显示错误样式。',+ description: '允许的最大字符数。设置后,在文本域下方显示字符计数器(当前/最大)。不原生强制限制——超出时计数器显示错误样式。',},{name: 'status',type: "{ type: 'warning' | 'error' | 'success'; message?: string }",- description:- '应用彩色边框和图标的状态指示器。可选消息显示在文本域下方的浮动框中。',+ description: '应用彩色边框和图标的状态指示器。可选消息显示在文本域下方的浮动框中。',},{name: 'labelTooltip',type: 'string',- description:- '在标签末尾的信息图标中显示的工具提示文本。',+ description: '在标签末尾的信息图标中显示的工具提示文本。',},{name: 'startIcon',type: 'XDSIconType',- description:- '在文本域包装器前端内部渲染的图标组件。',+ description: '在文本域包装器前端内部渲染的图标组件。',},{name: 'hasSpellCheck',@@ -292,8 +285,7 @@ export const docsZh = {{name: 'htmlName',type: 'string',- description:- '文本域元素的 HTML name 属性,用于表单提交。',+ description: '文本域元素的 HTML name 属性,用于表单提交。',},{name: 'onFocus',@@ -308,8 +300,7 @@ export const docsZh = {{name: 'xstyle',type: 'StyleXStyles',- description:- 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',+ description: 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象。',},],theming: {@@ -319,12 +310,15 @@ export const docsZh = {},usage: {description:- 'TextArea is a multi-line text input for collecting longer-form content such as comments, messages, or descriptions. Use it when the expected input exceeds a single line, and choose TextInput for shorter single-line values.',+ 'TextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.',bestPractices: [- { guidance: true, description: 'Provide a visible label or set isLabelHidden with a descriptive label for screen readers.' },- { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit to help users stay within bounds.' },- { guidance: false, description: 'Use a TextArea for short, single-line values like names or emails — use TextInput instead.' },- { guidance: false, description: 'Rely solely on placeholder text to communicate the purpose of the field.' },+ { guidance: true, description: 'Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers.' },+ { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit — it helps users stay within bounds before they submit.' },+ { guidance: true, description: 'Use the status prop to surface validation feedback inline — show success when input is valid, warning for soft limits, and error for hard failures.' },+ { guidance: true, description: 'Add a description or placeholder to clarify expected content, like "Describe the issue in detail" — but never rely on placeholder alone as the only label.' },+ { guidance: false, description: 'Avoid using TextArea for short, single-line values like names or emails — use TextInput instead.' },+ { guidance: false, description: 'Don\'t rely solely on placeholder text to communicate the purpose of the field — placeholders disappear on focus and are not accessible labels.' },+ { guidance: false, description: 'Don\'t show a status message without also setting the status type — the colored border and icon are what draw the user\'s attention to the message.' },],},};@@ -334,12 +328,15 @@ export const docsDense = {description: 'Multi-line text input for collecting longer user input.',usage: {description:- 'TextArea is a multi-line text input for collecting longer-form content such as comments, messages, or descriptions. Use it when the expected input exceeds a single line, and choose TextInput for shorter single-line values.',+ 'Multi-line input for comments, descriptions, messages. Use when input spans multiple lines; use TextInput for single-line.',bestPractices: [- { guidance: true, description: 'Provide a visible label or set isLabelHidden with a descriptive label for screen readers.' },- { guidance: true, description: 'Set maxLength with a character counter when there is a defined limit to help users stay within bounds.' },- { guidance: false, description: 'Use a TextArea for short, single-line values like names or emails — use TextInput instead.' },- { guidance: false, description: 'Rely solely on placeholder text to communicate the purpose of the field.' },+ { guidance: true, description: 'Visible label or isLabelHidden with descriptive label for screen readers.' },+ { guidance: true, description: 'Set maxLength for character counter when a limit exists.' },+ { guidance: true, description: 'Use status prop for inline validation — success, warning, error.' },+ { guidance: true, description: 'Add description or placeholder for context — never placeholder alone as label.' },+ { guidance: false, description: 'Avoid TextArea for single-line values — use TextInput.' },+ { guidance: false, description: 'Don\'t use placeholder as only label — disappears on focus, not accessible.' },+ { guidance: false, description: 'Don\'t show status message without status type — border and icon draw attention.' },],},propDescriptions: {