An open source design system that's fully customizable and agent ready
TypeScript
Improve DateInput docs page and block examples (#1569)
rubyycheungf2ac927fee1d
diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputClearable.doc.mjs b/packages/cli/templates/blocks/components/DateInput/DateInputClearable.doc.mjsindex 0ebf674831..edb1092974 100644--- a/packages/cli/templates/blocks/components/DateInput/DateInputClearable.doc.mjs+++ b/packages/cli/templates/blocks/components/DateInput/DateInputClearable.doc.mjs@@ -2,8 +2,9 @@export const doc = {type: 'block',name: 'DateInput — Clearable',- description: 'Date input with a clear button to reset the selected value.',+ description:+ 'Date input with a clear button that resets the value. Use when the date field is optional and the user may need to undo their selection.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['DateInput'],+ aspectRatio: 16 / 9,+ componentsUsed: ['DateInput', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputClearable.tsx b/packages/cli/templates/blocks/components/DateInput/DateInputClearable.tsxindex 31ddc8cc25..ef0d619118 100644--- a/packages/cli/templates/blocks/components/DateInput/DateInputClearable.tsx+++ b/packages/cli/templates/blocks/components/DateInput/DateInputClearable.tsx@@ -2,19 +2,30 @@import {useState} from 'react';import {XDSDateInput} from '@xds/core/DateInput';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';-type DateString = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;+type DateString =+ `${number}${number}${number}${number}-${number}${number}-${number}${number}`;export default function DateInputClearable() {- const [value, setValue] = useState<DateString | undefined>('2026-04-06' as DateString);+ const [value, setValue] = useState<DateString | undefined>(+ '2026-04-06' as DateString,+ );return (- <XDSDateInput- label="Event date"- placeholder="Select a date"- value={value}- onChange={setValue}- hasClear- />+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ {value ? `Selected: ${value}` : 'No date selected'}+ </XDSText>+ <XDSDateInput+ label="Event date"+ description="Pick a date for your event"+ placeholder="Select a date"+ value={value}+ onChange={setValue}+ hasClear+ />+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputDateRange.doc.mjs b/packages/cli/templates/blocks/components/DateInput/DateInputDateRange.doc.mjsindex 034c8569ab..7b143412c7 100644--- a/packages/cli/templates/blocks/components/DateInput/DateInputDateRange.doc.mjs+++ b/packages/cli/templates/blocks/components/DateInput/DateInputDateRange.doc.mjs@@ -2,8 +2,9 @@export const doc = {type: 'block',name: 'DateInput — Date Range',- description: 'Date input constrained to a min/max date range.',+ description:+ 'Date input constrained to a min/max window. Use when only certain dates are valid, like booking availability or a fiscal quarter.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['DateInput'],+ aspectRatio: 16 / 9,+ componentsUsed: ['DateInput', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputDateRange.tsx b/packages/cli/templates/blocks/components/DateInput/DateInputDateRange.tsxindex cfac25ca9b..9e46a05410 100644--- a/packages/cli/templates/blocks/components/DateInput/DateInputDateRange.tsx+++ b/packages/cli/templates/blocks/components/DateInput/DateInputDateRange.tsx@@ -1,23 +1,30 @@'use client';import {useState} from 'react';--type DateString = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;-import {XDSDateInput} from '@xds/core/DateInput';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++type DateString =+ `${number}${number}${number}${number}-${number}${number}-${number}${number}`;export default function DateInputDateRange() {const [value, setValue] = useState<DateString | undefined>(undefined);return (- <XDSDateInput- label="Booking date"- min="2026-01-15"- max="2026-02-15"- description="Available dates: Jan 15 – Feb 15, 2026"- placeholder="Select a booking date"- value={value}- onChange={setValue}- />+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ {value ? `Booked: ${value}` : 'Pick a date in the available range'}+ </XDSText>+ <XDSDateInput+ label="Booking date"+ min="2026-01-15"+ max="2026-02-15"+ description="Available dates: Jan 15 – Feb 15, 2026"+ placeholder="Select a booking date"+ value={value}+ onChange={setValue}+ />+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputPrefilledDate.doc.mjs b/packages/cli/templates/blocks/components/DateInput/DateInputPrefilledDate.doc.mjsdeleted file mode 100644index 3a65b8249c..0000000000--- a/packages/cli/templates/blocks/components/DateInput/DateInputPrefilledDate.doc.mjs+++ /dev/null@@ -1,9 +0,0 @@-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */-export const doc = {- type: 'block',- name: 'DateInput — Prefilled Date',- description: 'Date input initialized with a pre-selected value.',- isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['DateInput'],-};diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputPrefilledDate.tsx b/packages/cli/templates/blocks/components/DateInput/DateInputPrefilledDate.tsxdeleted file mode 100644index 7bf0f16ca0..0000000000--- a/packages/cli/templates/blocks/components/DateInput/DateInputPrefilledDate.tsx+++ /dev/null@@ -1,12 +0,0 @@-'use client';--import {useState} from 'react';-import {XDSDateInput} from '@xds/core/DateInput';--type DateString = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;--export default function DateInputPrefilledDate() {- const [value, setValue] = useState<DateString | undefined>('2026-01-25' as DateString);-- return <XDSDateInput label="Event date" value={value} onChange={setValue} />;-}diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputWithDescription.doc.mjs b/packages/cli/templates/blocks/components/DateInput/DateInputWithDescription.doc.mjsindex fc4eb5181f..0d36e80278 100644--- a/packages/cli/templates/blocks/components/DateInput/DateInputWithDescription.doc.mjs+++ b/packages/cli/templates/blocks/components/DateInput/DateInputWithDescription.doc.mjs@@ -1,9 +1,10 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'DateInput — With Description',- description: 'Date input with a helper description below the label.',+ name: 'DateInput — Description',+ description:+ 'Date input with helper text below the label explaining what the field expects. Use when the purpose of the date is not obvious from the label alone.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['DateInput'],+ aspectRatio: 16 / 9,+ componentsUsed: ['DateInput', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputWithDescription.tsx b/packages/cli/templates/blocks/components/DateInput/DateInputWithDescription.tsxindex ca0cad1256..c6c1f13ddd 100644--- a/packages/cli/templates/blocks/components/DateInput/DateInputWithDescription.tsx+++ b/packages/cli/templates/blocks/components/DateInput/DateInputWithDescription.tsx@@ -1,21 +1,28 @@'use client';import {useState} from 'react';--type DateString = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;-import {XDSDateInput} from '@xds/core/DateInput';+import {XDSStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';++type DateString =+ `${number}${number}${number}${number}-${number}${number}-${number}${number}`;export default function DateInputWithDescription() {const [value, setValue] = useState<DateString | undefined>(undefined);return (- <XDSDateInput- label="Birthday"- description="Enter your date of birth"- placeholder="Select your birthday"- value={value}- onChange={setValue}- />+ <XDSStack direction="vertical" gap={4}>+ <XDSText type="supporting" color="secondary">+ Helper text explains what the field expects+ </XDSText>+ <XDSDateInput+ label="Start date"+ description="Your subscription begins on this date"+ placeholder="Select a start date"+ value={value}+ onChange={setValue}+ />+ </XDSStack>);}diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputWithValidation.doc.mjs b/packages/cli/templates/blocks/components/DateInput/DateInputWithValidation.doc.mjsindex 3b0c91fb9a..eaaa669ef6 100644--- a/packages/cli/templates/blocks/components/DateInput/DateInputWithValidation.doc.mjs+++ b/packages/cli/templates/blocks/components/DateInput/DateInputWithValidation.doc.mjs@@ -1,9 +1,10 @@/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */export const doc = {type: 'block',- name: 'DateInput — With Validation',- description: 'Date input displaying an error validation message.',+ name: 'DateInput — Validation',+ description:+ 'Date input in all three status states: error, warning, and success. Use to surface validation issues, caution the user, or confirm a valid selection.',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['DateInput'],+ aspectRatio: 16 / 9,+ componentsUsed: ['DateInput', 'Layout', 'Text'],};diff --git a/packages/cli/templates/blocks/components/DateInput/DateInputWithValidation.tsx b/packages/cli/templates/blocks/components/DateInput/DateInputWithValidation.tsxindex 921f3b2b5b..947cf596ab 100644--- a/packages/cli/templates/blocks/components/DateInput/DateInputWithValidation.tsx+++ b/packages/cli/templates/blocks/components/DateInput/DateInputWithValidation.tsx@@ -2,21 +2,42 @@import {useState} from 'react';import {XDSDateInput} from '@xds/core/DateInput';+import {XDSStack} from '@xds/core/Layout';-type DateString = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;+type DateString =+ `${number}${number}${number}${number}-${number}${number}-${number}${number}`;export default function DateInputWithValidation() {- const [value, setValue] = useState<DateString | undefined>('2026-01-25' as DateString);+ const [errorVal, setErrorVal] = useState<DateString | undefined>(+ '2026-01-25' as DateString,+ );+ const [warningVal, setWarningVal] = useState<DateString | undefined>(+ '2026-12-25' as DateString,+ );+ const [successVal, setSuccessVal] = useState<DateString | undefined>(+ '2026-03-10' as DateString,+ );return (- <XDSDateInput- label="Event date"- value={value}- onChange={setValue}- status={{- type: 'error',- message: 'This date is not available',- }}- />+ <XDSStack direction="vertical" gap={4}>+ <XDSDateInput+ label="Event date"+ value={errorVal}+ onChange={setErrorVal}+ status={{type: 'error', message: 'This date is already booked'}}+ />+ <XDSDateInput+ label="Preferred date"+ value={warningVal}+ onChange={setWarningVal}+ status={{type: 'warning', message: 'This date falls on a holiday'}}+ />+ <XDSDateInput+ label="Start date"+ value={successVal}+ onChange={setSuccessVal}+ status={{type: 'success', message: 'Date confirmed'}}+ />+ </XDSStack>);}diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjsindex b17747a9ec..aabb3d93ce 100644--- a/packages/core/src/DateInput/DateInput.doc.mjs+++ b/packages/core/src/DateInput/DateInput.doc.mjs@@ -106,12 +106,6 @@ export const docs = {'Shows a clear (\u00d7) button when a date value is set. Clicking it clears the value and returns focus to the input.',default: 'false',},- {- name: 'hasClear',- type: 'boolean',- description: '设置日期值时显示清除 (×) 按鈕。点击后清空值并将焦点返回输入框。',- default: 'false',- },{name: 'numberOfMonths',type: '1 | 2',@@ -132,12 +126,23 @@ export const docs = {],},usage: {- description: 'A date input field that combines a text input with a calendar popover for selecting dates. Use when users need to enter a specific date, such as scheduling events, setting deadlines, or completing form submissions.',+ description: 'DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.',bestPractices: [{ guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },{ guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },+ { guidance: true, description: 'Use hasClear when the date is optional so the user can easily reset it.' },+ { guidance: true, description: 'Show a loading state with onChangeAction when the date triggers a server-side save.' },{ guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },+ { guidance: false, description: 'Rely on the calendar alone — the text input lets users type dates directly, which is faster for known dates.' },+ ],+ anatomy: [+ {name: 'Label', required: true, description: 'Text above the input describing what date is expected.'},+ {name: 'Text input', required: true, description: 'A field where the user can type a date directly. Parses common formats like MM/DD/YYYY.'},+ {name: 'Calendar icon', required: true, description: 'A button that opens the calendar popover for visual date picking.'},+ {name: 'Calendar popover', required: false, description: 'A month grid that appears when the icon is clicked or the input is focused.'},+ {name: 'Clear button', required: false, description: 'A × button that resets the date value. Shown when hasClear is true and a date is set.'},+ {name: 'Status message', required: false, description: 'An error, warning, or success message below the input.'},],},};@@ -146,12 +151,15 @@ export const docs = {export const docsZh = {name: 'DateInput',usage: {- description: 'A date input field that combines a text input with a calendar popover for selecting dates. Use when users need to enter a specific date, such as scheduling events, setting deadlines, or completing form submissions.',+ description: 'DateInput lets the user type or pick a date from a calendar popover. Use it for scheduling, deadlines, booking dates, or any form field that needs a specific calendar date.',bestPractices: [{ guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },{ guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },+ { guidance: true, description: 'Use hasClear when the date is optional so the user can easily reset it.' },+ { guidance: true, description: 'Show a loading state with onChangeAction when the date triggers a server-side save.' },{ guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },{ guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },+ { guidance: false, description: 'Rely on the calendar alone — the text input lets users type dates directly, which is faster for known dates.' },],},props: [@@ -199,14 +207,14 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'text input w/ calendar popover for date selection',+ description: 'text input w/ calendar popover for picking a date',usage: {- description: 'A date input field that combines a text input with a calendar popover for selecting dates. Use when users need to enter a specific date, such as scheduling events, setting deadlines, or completing form submissions.',+ description: 'DateInput lets the user type or pick a date from a calendar popover. Use for scheduling, deadlines, booking dates, or any form field needing a calendar date.',bestPractices: [- { guidance: true, description: 'Provide clear labels and descriptions so users understand what date is expected.' },- { guidance: true, description: 'Use min, max, and dateConstraints to restrict selectable dates to valid ranges.' },- { guidance: false, description: 'Use a DateInput for free-form text that does not represent a calendar date.' },- { guidance: false, description: 'Hide the label without surrounding context that makes the field purpose obvious.' },+ { guidance: true, description: 'Clear labels + descriptions. Use min/max/dateConstraints for valid ranges.' },+ { guidance: true, description: 'Use hasClear for optional dates. Use onChangeAction for server-side saves.' },+ { guidance: false, description: 'Use for free-form text that is not a calendar date.' },+ { guidance: false, description: 'Hide the label without surrounding context. Don\'t ignore the text input — users can type dates directly.' },],},propDescriptions: {