Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve TimeInput docs page and block examples (#1608)

Kenton Quatman1573757f373b
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputConstrained.doc.mjs b/packages/cli/templates/blocks/components/TimeInput/TimeInputConstrained.doc.mjs
new file mode 100644
index 0000000000..b621c726a2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TimeInput/TimeInputConstrained.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TimeInput — Constrained',
+ description: 'Time inputs with min/max constraints limiting selection to specific windows. Use to prevent out-of-bounds selections for appointments, reservations, or shift scheduling.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TimeInput', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputConstrained.tsx b/packages/cli/templates/blocks/components/TimeInput/TimeInputConstrained.tsx
new file mode 100644
index 0000000000..c7fc1ced9d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TimeInput/TimeInputConstrained.tsx
@@ -0,0 +1,24 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTimeInput} from '@xds/core/TimeInput';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function TimeInputConstrained() {
+ const [evening, setEvening] = useState(undefined);
+
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSTimeInput
+ label="Dinner reservation"
+ min={'17:00' as never}
+ max={'22:00' as never}
+ description="Evening seating: 5 PM – 10 PM"
+ placeholder="Select reservation time"
+ value={evening as never}
+ onChange={setEvening as never}
+ hasClear
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputFormats.doc.mjs b/packages/cli/templates/blocks/components/TimeInput/TimeInputFormats.doc.mjs
new file mode 100644
index 0000000000..91e4759b1f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TimeInput/TimeInputFormats.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TimeInput — Formats',
+ description: '12-hour, 24-hour, and seconds formats side by side. Use 12h for US-centric UIs, 24h for international or technical contexts, and seconds for precise timing.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['TimeInput', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputFormats.tsx b/packages/cli/templates/blocks/components/TimeInput/TimeInputFormats.tsx
new file mode 100644
index 0000000000..5e769b01e4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TimeInput/TimeInputFormats.tsx
@@ -0,0 +1,33 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTimeInput} from '@xds/core/TimeInput';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function TimeInputFormats() {
+ const [time24h, setTime24h] = useState('14:30');
+ const [timeSec, setTimeSec] = useState('14:30:45');
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Format variations for different contexts
+ </XDSText>
+ <XDSStack direction="vertical" gap={3}>
+ <XDSTimeInput
+ label="24-hour"
+ value={time24h as never}
+ onChange={setTime24h as never}
+ hourFormat="24h"
+ />
+ <XDSTimeInput
+ label="With seconds"
+ value={timeSec as never}
+ onChange={setTimeSec as never}
+ hasSeconds
+ />
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputShowcase.doc.mjs b/packages/cli/templates/blocks/components/TimeInput/TimeInputShowcase.doc.mjs
index 4aed3ad80b..662c22d83d 100644
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/TimeInput/TimeInputShowcase.doc.mjs
@@ -3,6 +3,6 @@ export const doc = {
type: 'block',
name: 'TimeInput',
isReady: true,
- aspectRatio: 1,
+ aspectRatio: 16 / 9,
isShowcase: true,
};
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputStates.doc.mjs b/packages/cli/templates/blocks/components/TimeInput/TimeInputStates.doc.mjs
new file mode 100644
index 0000000000..ca4974e372
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TimeInput/TimeInputStates.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TimeInput — States',
+ description: 'Default, disabled, error, warning, and success states. Use status messages to give users clear feedback about their time selection.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['TimeInput', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputStates.tsx b/packages/cli/templates/blocks/components/TimeInput/TimeInputStates.tsx
new file mode 100644
index 0000000000..7f9d85122f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TimeInput/TimeInputStates.tsx
@@ -0,0 +1,41 @@
+'use client';
+
+import {useState} from 'react';
+import {XDSTimeInput} from '@xds/core/TimeInput';
+import {XDSStack} from '@xds/core/Layout';
+
+export default function TimeInputStates() {
+ const [disabledVal, setDisabledVal] = useState('10:00');
+ const [errorVal, setErrorVal] = useState('22:00');
+ const [warningVal, setWarningVal] = useState('07:00');
+ const [successVal, setSuccessVal] = useState('10:00');
+
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSTimeInput
+ label="Disabled field"
+ value={disabledVal as never}
+ onChange={setDisabledVal as never}
+ isDisabled
+ />
+ <XDSTimeInput
+ label="Error message"
+ value={errorVal as never}
+ onChange={setErrorVal as never}
+ status={{type: 'error', message: 'Time must be during business hours'}}
+ />
+ <XDSTimeInput
+ label="Warning message"
+ value={warningVal as never}
+ onChange={setWarningVal as never}
+ status={{type: 'warning', message: 'Early morning — are you sure?'}}
+ />
+ <XDSTimeInput
+ label="Success message"
+ value={successVal as never}
+ onChange={setSuccessVal as never}
+ status={{type: 'success', message: 'Time slot is available'}}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputTwentyFourHour.doc.mjs b/packages/cli/templates/blocks/components/TimeInput/TimeInputTwentyFourHour.doc.mjs
deleted file mode 100644
index b6b8c80590..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputTwentyFourHour.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'TimeInput — 24-Hour Format',
- description: 'Time input using 24-hour display format instead of 12-hour AM/PM.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TimeInput'],
-};
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputTwentyFourHour.tsx b/packages/cli/templates/blocks/components/TimeInput/TimeInputTwentyFourHour.tsx
deleted file mode 100644
index 5d9cfda1d2..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputTwentyFourHour.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTimeInput} from '@xds/core/TimeInput';
-
-
-export default function TimeInputTwentyFourHour() {
- const [value, setValue] = useState('14:30');
- return (
- <XDSTimeInput
- label="Time (24h)"
- hourFormat="24h"
- value={value as never}
- onChange={setValue as never}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithError.doc.mjs b/packages/cli/templates/blocks/components/TimeInput/TimeInputWithError.doc.mjs
deleted file mode 100644
index 9dfb290261..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithError.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'TimeInput — Error State',
- description:
- 'Time input displaying an error status message for invalid time selection.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TimeInput'],
-};
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithError.tsx b/packages/cli/templates/blocks/components/TimeInput/TimeInputWithError.tsx
deleted file mode 100644
index 932752b9de..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithError.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTimeInput} from '@xds/core/TimeInput';
-
-
-export default function TimeInputWithError() {
- const [value, setValue] = useState('22:00');
- return (
- <XDSTimeInput
- label="Event time"
- value={value as never}
- onChange={setValue as never}
- status={{
- type: 'error',
- message: 'Time must be during business hours',
- }}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithMinMax.doc.mjs b/packages/cli/templates/blocks/components/TimeInput/TimeInputWithMinMax.doc.mjs
deleted file mode 100644
index bd3de1a35a..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithMinMax.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'TimeInput — Constrained Range',
- description:
- 'Time input with min/max constraints limiting selection to business hours.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TimeInput'],
-};
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithMinMax.tsx b/packages/cli/templates/blocks/components/TimeInput/TimeInputWithMinMax.tsx
deleted file mode 100644
index dc1e95ecf4..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithMinMax.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTimeInput} from '@xds/core/TimeInput';
-
-
-export default function TimeInputWithMinMax() {
- const [value, setValue] = useState(undefined);
- return (
- <XDSTimeInput
- label="Appointment time"
- min={'09:00' as never}
- max={'17:00' as never}
- description="Business hours: 9 AM – 5 PM"
- placeholder="Select appointment time"
- value={value as never}
- onChange={setValue as never}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithSeconds.doc.mjs b/packages/cli/templates/blocks/components/TimeInput/TimeInputWithSeconds.doc.mjs
deleted file mode 100644
index d8d86ba2b9..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithSeconds.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'TimeInput — With Seconds',
- description: 'Time input including a seconds field for precise time entry.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TimeInput'],
-};
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithSeconds.tsx b/packages/cli/templates/blocks/components/TimeInput/TimeInputWithSeconds.tsx
deleted file mode 100644
index 497fc310ce..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithSeconds.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTimeInput} from '@xds/core/TimeInput';
-
-
-export default function TimeInputWithSeconds() {
- const [value, setValue] = useState('14:30:45');
- return (
- <XDSTimeInput
- label="Precise time"
- hasSeconds
- value={value as never}
- onChange={setValue as never}
- />
- );
-}
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithValue.doc.mjs b/packages/cli/templates/blocks/components/TimeInput/TimeInputWithValue.doc.mjs
deleted file mode 100644
index c24b278b84..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithValue.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'TimeInput — With Value',
- description: 'Time input pre-populated with a default time value.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['TimeInput'],
-};
diff --git a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithValue.tsx b/packages/cli/templates/blocks/components/TimeInput/TimeInputWithValue.tsx
deleted file mode 100644
index 860d659888..0000000000
--- a/packages/cli/templates/blocks/components/TimeInput/TimeInputWithValue.tsx
+++ /dev/null
@@ -1,16 +0,0 @@
-'use client';
-
-import {useState} from 'react';
-import {XDSTimeInput} from '@xds/core/TimeInput';
-
-
-export default function TimeInputWithValue() {
- const [value, setValue] = useState('14:30');
- return (
- <XDSTimeInput
- label="Meeting time"
- value={value as never}
- onChange={setValue as never}
- />
- );
-}
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index 0e3ffba564..8051cd5fd8 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -3,12 +3,35 @@
export const docs = {
name: 'TimeInput',
group: 'Inputs',
- keywords: ["timeinput","timepicker","time","clock","hour","minute","ampm","timeselect","timefield"],
+ keywords: ["timeinput","timepicker","time","clock","hour","minute","ampm","timeselect","timefield","schedule"],
+
+ usage: {
+ description:
+ 'TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.',
+ bestPractices: [
+ {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.'},
+ {guidance: true, description: 'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.'},
+ {guidance: true, description: 'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.'},
+ {guidance: true, description: 'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.'},
+ {guidance: true, description: 'Enable hasClear when the field is optional, so users can easily remove a previously selected time.'},
+ {guidance: false, description: 'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.'},
+ {guidance: false, description: 'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.'},
+ ],
+ anatomy: [
+ {name: 'Clock icon', required: false, description: 'A leading clock icon that identifies the field as a time input.'},
+ {name: 'Text input', required: true, description: 'The editable text field where users type or see the formatted time.'},
+ {name: 'Clear button', required: false, description: 'A trailing button to reset the value, shown when hasClear is true and a value is set.'},
+ {name: 'Status icon', required: false, description: 'A trailing icon indicating error, warning, or success state.'},
+ {name: 'Spinner', required: false, description: 'Replaces trailing content during loading to show an async action is in progress.'},
+ ],
+ },
+
props: [
{
name: 'label',
type: 'string',
- description: 'Label text for the input (required for accessibility).',
+ description:
+ 'Label text for the input (required for accessibility).',
required: true,
},
{
@@ -142,152 +165,34 @@ export const docs = {
{className: 'xds-time-input', visualProps: ['size', 'status']},
],
},
- usage: {
- description:
- 'TimeInput is a time entry field with free-text parsing and arrow-key navigation. Use it in forms, scheduling interfaces, or anywhere users need to specify a time of day.',
- bestPractices: [
- {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\'s locale and expectations.'},
- {guidance: true, description: 'Set min and max constraints to prevent users from selecting invalid times for the context.'},
- {guidance: false, description: 'Use TimeInput for date-and-time selection — pair it with DateInput for combined date-time fields.'},
- ],
- },
};
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'TimeInput',
+
props: [
- {
- name: 'label',
- type: 'string',
- description: '输入框的标签文本(无障碍性所必需)。',
- required: true,
- },
- {
- name: 'isLabelHidden',
- type: 'boolean',
- description:
- '视觉上隐藏标签,同时保持屏幕阅读器的无障碍性。',
- default: 'false',
- },
- {
- name: 'description',
- type: 'string',
- description: '显示在标签和输入框之间的描述文本。',
- },
- {
- name: 'isOptional',
- type: 'boolean',
- description:
- '在标签旁显示"(可选)"指示器。与 isRequired 互斥。',
- default: 'false',
- },
- {
- name: 'isRequired',
- type: 'boolean',
- description:
- '将字段标记为必填并设置 aria-required。与 isOptional 互斥。',
- default: 'false',
- },
- {
- name: 'isDisabled',
- type: 'boolean',
- description: '禁用输入框并抑制交互。',
- default: 'false',
- },
- {
- name: 'value',
- type: 'ISOTimeString',
- description: 'ISO 格式的受控时间值(HH:MM 或 HH:MM:SS)。',
- },
- {
- name: 'onChange',
- type: '(value: ISOTimeString | undefined) => void',
- description:
- '时间变化时触发的回调。输入被清除时接收 undefined。',
- },
- {
- name: 'onChangeAction',
- type: '(value: ISOTimeString | undefined) => void | Promise<void>',
- description:
- '在 onChange 之后触发的异步操作。包装在 React transition 中以提供乐观 UI;挂起时触发加载旋转器。',
- },
- {
- name: 'isLoading',
- type: 'boolean',
- description: '使输入框进入加载状态,显示旋转器。',
- default: 'false',
- },
- {
- name: 'min',
- type: 'ISOTimeString',
- description:
- 'ISO 格式的最小可选时间。超出范围的值将被拒绝。',
- },
- {
- name: 'max',
- type: 'ISOTimeString',
- description:
- 'ISO 格式的最大可选时间。超出范围的值将被拒绝。',
- },
- {
- name: 'hasSeconds',
- type: 'boolean',
- description: '在时间显示和解析中包含秒。',
- default: 'false',
- },
- {
- name: 'hasClear',
- type: 'boolean',
- description:
- '当有值且输入框未被禁用时显示清除按钮。',
- default: 'false',
- },
- {
- name: 'hourFormat',
- type: "'12h' | '24h'",
- description:
- "控制显示格式。'12h' 显示 AM/PM(例如 '2:30 PM');'24h' 使用 24 小时制(例如 '14:30')。",
- default: "'12h'",
- },
- {
- name: 'increment',
- type: 'number',
- description:
- '用户按上或下方向键时增加或减少的分钟数。',
- default: '1',
- },
- {
- name: 'placeholder',
- type: 'string',
- description:
- '未选择时间时显示的占位符文本。当输入框聚焦且为空时,格式提示会覆盖此文本。',
- default: "'Select a time'",
- },
- {
- name: 'size',
- type: "'sm' | 'md' | 'lg'",
- description: '控制输入框元素的高度。',
- default: "'md'",
- },
- {
- name: 'status',
- type: 'XDSInputStatus',
- description:
- '为边框着色并显示图标的状态指示器。当提供消息时,消息渲染在输入框下方。',
- },
- {
- name: 'labelTooltip',
- type: 'string',
- description:
- '在标签行末尾以信息图标形式渲染的工具提示文本。',
- },
- {
- name: 'xstyle',
- type: 'StyleXStyles',
- description:
- 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
- },
+ {name: 'label', type: 'string', description: '输入框的标签文本(无障碍性所必需)。', required: true},
+ {name: 'isLabelHidden', type: 'boolean', description: '视觉上隐藏标签,同时保持屏幕阅读器的无障碍性。', default: 'false'},
+ {name: 'description', type: 'string', description: '显示在标签和输入框之间的描述文本。'},
+ {name: 'isOptional', type: 'boolean', description: '在标签旁显示"(可选)"指示器。与 isRequired 互斥。', default: 'false'},
+ {name: 'isRequired', type: 'boolean', description: '将字段标记为必填并设置 aria-required。与 isOptional 互斥。', default: 'false'},
+ {name: 'isDisabled', type: 'boolean', description: '禁用输入框并抑制交互。', default: 'false'},
+ {name: 'value', type: 'ISOTimeString', description: 'ISO 格式的受控时间值(HH:MM 或 HH:MM:SS)。'},
+ {name: 'onChange', type: '(value: ISOTimeString | undefined) => void', description: '时间变化时触发的回调。输入被清除时接收 undefined。'},
+ {name: 'onChangeAction', type: '(value: ISOTimeString | undefined) => void | Promise<void>', description: '在 onChange 之后触发的异步操作。包装在 React transition 中以提供乐观 UI;挂起时触发加载旋转器。'},
+ {name: 'isLoading', type: 'boolean', description: '使输入框进入加载状态,显示旋转器。', default: 'false'},
+ {name: 'min', type: 'ISOTimeString', description: 'ISO 格式的最小可选时间。超出范围的值将被拒绝。'},
+ {name: 'max', type: 'ISOTimeString', description: 'ISO 格式的最大可选时间。超出范围的值将被拒绝。'},
+ {name: 'hasSeconds', type: 'boolean', description: '在时间显示和解析中包含秒。', default: 'false'},
+ {name: 'hasClear', type: 'boolean', description: '当有值且输入框未被禁用时显示清除按钮。', default: 'false'},
+ {name: 'hourFormat', type: "'12h' | '24h'", description: "控制显示格式。'12h' 显示 AM/PM(例如 '2:30 PM');'24h' 使用 24 小时制(例如 '14:30')。", default: "'12h'"},
+ {name: 'increment', type: 'number', description: '用户按上或下方向键时增加或减少的分钟数。', default: '1'},
+ {name: 'placeholder', type: 'string', description: '未选择时间时显示的占位符文本。当输入框聚焦且为空时,格式提示会覆盖此文本。', default: "'Select a time'"},
+ {name: 'size', type: "'sm' | 'md' | 'lg'", description: '控制输入框元素的高度。', default: "'md'"},
+ {name: 'status', type: 'XDSInputStatus', description: '为边框着色并显示图标的状态指示器。当提供消息时,消息渲染在输入框下方。'},
+ {name: 'labelTooltip', type: 'string', description: '在标签行末尾以信息图标形式渲染的工具提示文本。'},
+ {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX 样式,用于布局自定义(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。'},
],
theming: {
targets: [
@@ -296,25 +201,40 @@ export const docsZh = {
},
usage: {
description:
- 'TimeInput is a time entry field with free-text parsing and arrow-key navigation. Use it in forms, scheduling interfaces, or anywhere users need to specify a time of day.',
+ 'TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.',
bestPractices: [
- {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\'s locale and expectations.'},
- {guidance: true, description: 'Set min and max constraints to prevent users from selecting invalid times for the context.'},
- {guidance: false, description: 'Use TimeInput for date-and-time selection — pair it with DateInput for combined date-time fields.'},
+ {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\u2019s locale \u2014 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.'},
+ {guidance: true, description: 'Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.'},
+ {guidance: true, description: 'Provide a description or placeholder that hints at the expected format or purpose, like \u201cBusiness hours: 9 AM \u2013 5 PM\u201d.'},
+ {guidance: true, description: 'Use the status prop to surface validation errors inline \u2014 show a message like \u201cTime must be during business hours\u201d so users know exactly what to fix.'},
+ {guidance: true, description: 'Enable hasClear when the field is optional, so users can easily remove a previously selected time.'},
+ {guidance: false, description: 'Don\u2019t use TimeInput for combined date-and-time selection \u2014 pair it with a separate DateInput instead.'},
+ {guidance: false, description: 'Don\u2019t hide the label \u2014 even when space is tight, keep the label visible or provide a description so the purpose is clear.'},
+ ],
+ anatomy: [
+ {name: 'Clock icon', required: false, description: 'A leading clock icon that identifies the field as a time input.'},
+ {name: 'Text input', required: true, description: 'The editable text field where users type or see the formatted time.'},
+ {name: 'Clear button', required: false, description: 'A trailing button to reset the value, shown when hasClear is true and a value is set.'},
+ {name: 'Status icon', required: false, description: 'A trailing icon indicating error, warning, or success state.'},
+ {name: 'Spinner', required: false, description: 'Replaces trailing content during loading to show an async action is in progress.'},
],
},
};
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
- description: 'Time input w/ free-text entry, text parsing, arrow-key navigation.',
+ description: 'Time input that converts free-text entry to standard format with arrow-key adjustment.',
usage: {
description:
- 'TimeInput is a time entry field with free-text parsing and arrow-key navigation. Use it in forms, scheduling interfaces, or anywhere users need to specify a time of day.',
+ 'TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.',
bestPractices: [
- {guidance: true, description: 'Choose the hour format (12h or 24h) that matches your audience\'s locale and expectations.'},
- {guidance: true, description: 'Set min and max constraints to prevent users from selecting invalid times for the context.'},
- {guidance: false, description: 'Use TimeInput for date-and-time selection — pair it with DateInput for combined date-time fields.'},
+ {guidance: true, description: 'Choose hour format (12h/24h) to match locale \u2014 12h for US, 24h for international.'},
+ {guidance: true, description: 'Set min/max constraints for valid ranges like business hours.'},
+ {guidance: true, description: 'Provide description or placeholder hinting at expected format.'},
+ {guidance: true, description: 'Use status prop for inline validation errors.'},
+ {guidance: true, description: 'Enable hasClear for optional fields.'},
+ {guidance: false, description: 'Don\u2019t use for date-and-time \u2014 pair with DateInput instead.'},
+ {guidance: false, description: 'Don\u2019t hide the label \u2014 keep it visible for clarity.'},
],
},
propDescriptions: {