An open source design system that's fully customizable and agent ready
TypeScript
Improve FormLayout docs and block examples (#1667)
Ted McDonald2f11edb92e80
diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.doc.mjs b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.doc.mjsindex 25e19e9cee..49fad1557f 100644--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.doc.mjs+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.doc.mjs@@ -2,7 +2,7 @@export const doc = {type: 'block',name: 'FormLayout — Horizontal',- description: 'Side-by-side form fields for short related inputs like names',+ description: 'Two fields side by side for naturally paired inputs like first and last name',isReady: true,aspectRatio: 4 / 3,componentsUsed: ['FormLayout', 'TextInput'],diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.tsx b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.tsxindex 78ecb9659c..be9b36d89f 100644--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.tsx+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontal.tsx@@ -5,8 +5,8 @@ import {XDSFormLayout} from '@xds/core/FormLayout';import {XDSTextInput} from '@xds/core/TextInput';export default function FormLayoutHorizontal() {- const [first, setFirst] = useState('');- const [last, setLast] = useState('');+ const [first, setFirst] = useState('Jordan');+ const [last, setLast] = useState('Rivera');return (<XDSFormLayout direction="horizontal">diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontalLabels.doc.mjs b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontalLabels.doc.mjsindex c20d5208b9..d000bc920e 100644--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontalLabels.doc.mjs+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutHorizontalLabels.doc.mjs@@ -2,8 +2,7 @@export const doc = {type: 'block',name: 'FormLayout — Settings Form',- description:- 'Horizontal-labels layout for settings pages with labels beside inputs',+ description: 'Settings form with labels placed beside their inputs',isReady: true,aspectRatio: 4 / 3,componentsUsed: ['FormLayout', 'TextInput', 'Selector'],diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.doc.mjs b/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.doc.mjsindex 09185ea7c3..2ff1b6b075 100644--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.doc.mjs+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.doc.mjs@@ -2,9 +2,8 @@export const doc = {type: 'block',name: 'FormLayout — Mixed Controls',- description:- 'Form combining text inputs, a selector, and a custom checkbox group via XDSField',+ description: 'Form with different control types — text input, selector, and checkboxes',isReady: true,aspectRatio: 4 / 3,- componentsUsed: ['FormLayout', 'TextInput', 'Selector', 'Field'],+ componentsUsed: ['FormLayout', 'TextInput', 'Selector', 'CheckboxList'],};diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.tsx b/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.tsxindex 0cf2169740..01c1a4a044 100644--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.tsx+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutMixedControls.tsx@@ -4,15 +4,16 @@ import {useState} from 'react';import {XDSFormLayout} from '@xds/core/FormLayout';import {XDSTextInput} from '@xds/core/TextInput';import {XDSSelector} from '@xds/core/Selector';-import {XDSField} from '@xds/core/Field';+import {XDSCheckboxList, XDSCheckboxListItem} from '@xds/core/CheckboxList';export default function FormLayoutMixedControls() {- const [name, setName] = useState('');- const [role, setRole] = useState('viewer');+ const [name, setName] = useState('Maya Torres');+ const [role, setRole] = useState('editor');+ const [notifications, setNotifications] = useState(['email', 'push']);return (<XDSFormLayout>- <XDSTextInput label="Name" value={name} onChange={setName} />+ <XDSTextInput label="Full Name" value={name} onChange={setName} /><XDSSelectorlabel="Role"value={role}@@ -23,21 +24,14 @@ export default function FormLayoutMixedControls() {{label: 'Admin', value: 'admin'},]}/>- <XDSField label="Notifications" inputID="notif-group">- <div- id="notif-group"- style={{display: 'flex', flexDirection: 'column', gap: 4}}>- <label style={{display: 'flex', alignItems: 'center', gap: 8}}>- <input type="checkbox" defaultChecked /> Email- </label>- <label style={{display: 'flex', alignItems: 'center', gap: 8}}>- <input type="checkbox" /> SMS- </label>- <label style={{display: 'flex', alignItems: 'center', gap: 8}}>- <input type="checkbox" defaultChecked /> Push- </label>- </div>- </XDSField>+ <XDSCheckboxList+ label="Notifications"+ value={notifications}+ onChange={setNotifications}>+ <XDSCheckboxListItem label="Email" value="email" />+ <XDSCheckboxListItem label="SMS" value="sms" />+ <XDSCheckboxListItem label="Push" value="push" />+ </XDSCheckboxList></XDSFormLayout>);}diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.doc.mjs b/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.doc.mjsindex 2f12dc9a8e..e7a6a6436e 100644--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.doc.mjs+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.doc.mjs@@ -2,8 +2,7 @@export const doc = {type: 'block',name: 'FormLayout — Nested Address Form',- description:- 'Nested vertical and horizontal layouts for a multi-section address form',+ description: 'Address form mixing vertical and horizontal layouts for grouped fields',isReady: true,aspectRatio: 4 / 3,componentsUsed: ['FormLayout', 'TextInput'],diff --git a/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.tsx b/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.tsxindex 864b319f38..e46dc4bd7d 100644--- a/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.tsx+++ b/packages/cli/templates/blocks/components/FormLayout/FormLayoutNested.tsx@@ -5,12 +5,12 @@ import {XDSFormLayout} from '@xds/core/FormLayout';import {XDSTextInput} from '@xds/core/TextInput';export default function FormLayoutNested() {- const [first, setFirst] = useState('');- const [last, setLast] = useState('');- const [email, setEmail] = useState('');- const [city, setCity] = useState('');- const [state, setState] = useState('');- const [zip, setZip] = useState('');+ const [first, setFirst] = useState('Priya');+ const [last, setLast] = useState('Sharma');+ const [email, setEmail] = useState('[email protected]');+ const [city, setCity] = useState('San Francisco');+ const [state, setState] = useState('CA');+ const [zip, setZip] = useState('94105');return (<XDSFormLayout>diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjsindex a5c9cb0d2e..b4de3846a0 100644--- a/packages/core/src/FormLayout/FormLayout.doc.mjs+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs@@ -30,11 +30,14 @@ export const docs = {],},usage: {- description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Use FormLayout to structure sign-in flows, settings pages, and object creation or editing forms. Prefer single-column layouts with top-aligned labels for step-by-step flows.',+ description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go — not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',bestPractices: [- { guidance: true, description: 'Use vertical direction for most forms — it provides the clearest reading flow for step-by-step input.' },- { guidance: true, description: 'Group related fields together and separate logical sections with headings or spacing.' },- { guidance: false, description: 'Use FormLayout to manage form state or submission — it handles only visual arrangement. Pair it with a separate <form> element.' },+ { guidance: true, description: 'Stack fields vertically for most forms — it\'s the easiest to scan top to bottom.' },+ { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },+ { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },+ { guidance: false, description: 'Use FormLayout for form state or submission — it\'s just layout. Wrap it in a <form> for that.' },+ { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout — save it for fields that belong together.' },+ { guidance: false, description: 'Nest horizontal-labels inside another FormLayout — it uses CSS Grid and needs to be the outermost container.' },],anatomy: [{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},@@ -74,11 +77,14 @@ export const docsZh = {],},usage: {- description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Use FormLayout to structure sign-in flows, settings pages, and object creation or editing forms. Prefer single-column layouts with top-aligned labels for step-by-step flows.',+ description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go — not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',bestPractices: [- { guidance: true, description: 'Use vertical direction for most forms — it provides the clearest reading flow for step-by-step input.' },- { guidance: true, description: 'Group related fields together and separate logical sections with headings or spacing.' },- { guidance: false, description: 'Use FormLayout to manage form state or submission — it handles only visual arrangement. Pair it with a separate <form> element.' },+ { guidance: true, description: 'Stack fields vertically for most forms — it\'s the easiest to scan top to bottom.' },+ { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },+ { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },+ { guidance: false, description: 'Use FormLayout for form state or submission — it\'s just layout. Wrap it in a <form> for that.' },+ { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout — save it for fields that belong together.' },+ { guidance: false, description: 'Nest horizontal-labels inside another FormLayout — it uses CSS Grid and needs to be the outermost container.' },],anatomy: [{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},@@ -91,13 +97,16 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {description:- 'Spatial layout container for arranging form fields w/ consistent spacing + direction.',+ 'Layout container for form fields w/ consistent spacing + direction.',usage: {- description: 'A spatial layout container for arranging form fields with consistent spacing and direction. Use FormLayout to structure sign-in flows, settings pages, and object creation or editing forms. Prefer single-column layouts with top-aligned labels for step-by-step flows.',+ description: 'A layout container that arranges form fields with consistent spacing and direction. FormLayout handles where fields go — not state or submission. Wrap it in a <form> for that. Supports vertical (default), horizontal, and horizontal-labels directions, and can be nested to mix them.',bestPractices: [- { guidance: true, description: 'Use vertical direction for most forms — it provides the clearest reading flow for step-by-step input.' },- { guidance: true, description: 'Group related fields together and separate logical sections with headings or spacing.' },- { guidance: false, description: 'Use FormLayout to manage form state or submission — it handles only visual arrangement. Pair it with a separate <form> element.' },+ { guidance: true, description: 'Stack fields vertically for most forms — it\'s the easiest to scan top to bottom.' },+ { guidance: true, description: 'Nest a horizontal FormLayout inside a vertical one when fields naturally pair up, like First Name + Last Name or City + State + ZIP.' },+ { guidance: true, description: 'Use horizontal-labels for settings pages where labels sit beside their inputs.' },+ { guidance: false, description: 'Use FormLayout for form state or submission — it\'s just layout. Wrap it in a <form> for that.' },+ { guidance: false, description: 'Put unrelated fields side by side in a horizontal layout — save it for fields that belong together.' },+ { guidance: false, description: 'Nest horizontal-labels inside another FormLayout — it uses CSS Grid and needs to be the outermost container.' },],anatomy: [{name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},