Skip to content

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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
deleted file mode 100644
index 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.tsx
deleted file mode 100644
index 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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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: {