Skip to content

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

TypeScript

feat(core): add presentation to DateInput, DateTimeInput, TimeInput (AST-043) (#6628)

Xinzi Zhouc1c233522965
diff --git a/.changeset/input-presentation-prop.md b/.changeset/input-presentation-prop.md
new file mode 100644
index 0000000000..6ee9ef9ac4
--- /dev/null
+++ b/.changeset/input-presentation-prop.md
@@ -0,0 +1,12 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[feat] Add `presentation` to DateInput, DateTimeInput, and TimeInput (`spec:AST-043`).
+
+`presentation` names every picker surface, distinguishing Astryx's desktop surface, Astryx's bottom sheet (including a new TimeInput sheet), the browser/OS picker, and — for TimeInput only — a plain typed field. DateInput and DateTimeInput accept five values: `'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'` (default). TimeInput accepts those five plus `'text-input'`, the typed field on every pointer, because that is the surface its released `nativePicker="never"` already was. `presentation="native"` always shows native; `adaptive-native` keeps the released native fallbacks.
+
+`nativePicker` is deprecated but keeps working exactly as released (`touch`→`adaptive-native`, `always`→`native`, `never`→`adaptive-bottom-sheet`, or `text-input` for TimeInput); `presentation` wins when both are set. `astryx upgrade` ships `migrate-native-picker-to-presentation` for static callsites.
+
+@imdreamrunner
diff --git a/apps/storybook/stories/DateInput.stories.tsx b/apps/storybook/stories/DateInput.stories.tsx
index ddba116062..e6e9b306de 100644
--- a/apps/storybook/stories/DateInput.stories.tsx
+++ b/apps/storybook/stories/DateInput.stories.tsx
@@ -107,11 +107,23 @@ const meta: Meta<typeof DateInput> = {
description:
"Display format for the committed value, reusing Timestamp's vocabulary. Defaults to 'date_long' (long-month date).",
},
+ presentation: {
+ control: 'select',
+ options: [
+ 'popover',
+ 'bottom-sheet',
+ 'native',
+ 'adaptive-bottom-sheet',
+ 'adaptive-native',
+ ],
+ description:
+ 'Which surface draws the picker (spec:AST-043); nativePicker is deprecated',
+ },
nativePicker: {
control: 'radio',
options: ['touch', 'always', 'never'],
description:
- 'Whether the browser or Astryx draws the picker for each pointer type',
+ "Deprecated — use presentation ('touch' → 'adaptive-native', 'always' → 'native', 'never' → 'adaptive-bottom-sheet'); presentation wins when both are set",
},
},
};
@@ -216,25 +228,25 @@ export const NativePickerModes: Story = {
return (
<div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
<DateInput
- label="nativePicker='touch' (default)"
+ label="presentation='adaptive-native' (default)"
description="Native picker on a coarse pointer; Astryx picker otherwise"
value={value}
onChange={setValue}
- nativePicker="touch"
+ presentation="adaptive-native"
/>
<DateInput
- label="nativePicker='always'"
+ label="presentation='native'"
description="Native picker wherever the browser supports it"
value={value}
onChange={setValue}
- nativePicker="always"
+ presentation="native"
/>
<DateInput
- label="nativePicker='never'"
+ label="presentation='adaptive-bottom-sheet'"
description="Astryx picker on every pointer type"
value={value}
onChange={setValue}
- nativePicker="never"
+ presentation="adaptive-bottom-sheet"
/>
</div>
);
diff --git a/apps/storybook/stories/DateTimeInput.stories.tsx b/apps/storybook/stories/DateTimeInput.stories.tsx
index ba0edc5b51..a54ce01c5e 100644
--- a/apps/storybook/stories/DateTimeInput.stories.tsx
+++ b/apps/storybook/stories/DateTimeInput.stories.tsx
@@ -74,11 +74,23 @@ const meta: Meta<typeof DateTimeInput> = {
control: 'boolean',
description: 'Whether to show a clear button',
},
+ presentation: {
+ control: 'select',
+ options: [
+ 'popover',
+ 'bottom-sheet',
+ 'native',
+ 'adaptive-bottom-sheet',
+ 'adaptive-native',
+ ],
+ description:
+ 'Which surfaces draw the pickers (spec:AST-043); nativePicker is deprecated',
+ },
nativePicker: {
control: 'radio',
options: ['touch', 'always', 'never'],
description:
- "Date and time picker surfaces: native browser/OS controls on touch by default, native wherever compatible, or Astryx's surfaces everywhere",
+ "Deprecated — use presentation ('touch' → 'adaptive-native', 'always' → 'native', 'never' → 'adaptive-bottom-sheet'); presentation wins when both are set",
},
numberOfMonths: {
control: 'radio',
@@ -146,25 +158,25 @@ export const NativePickerModes: Story = {
return (
<div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
<DateTimeInput
- label="nativePicker='touch' (default)"
+ label="presentation='adaptive-native' (default)"
description="Native date and compatible time controls on a coarse primary pointer"
value={value}
onChange={setValue}
- nativePicker="touch"
+ presentation="adaptive-native"
/>
<DateTimeInput
- label="nativePicker='always'"
+ label="presentation='native'"
description="Native date and compatible time controls on every pointer type"
value={value}
onChange={setValue}
- nativePicker="always"
+ presentation="native"
/>
<DateTimeInput
- label="nativePicker='never'"
+ label="presentation='adaptive-bottom-sheet'"
description="Astryx bottom sheet on coarse pointers; calendar popover on fine pointers"
value={value}
onChange={setValue}
- nativePicker="never"
+ presentation="adaptive-bottom-sheet"
/>
</div>
);
@@ -405,7 +417,7 @@ export const TwoMonthCalendar: Story = {
args: {
label: 'Travel departure',
numberOfMonths: 2,
- nativePicker: 'never',
+ presentation: 'adaptive-bottom-sheet',
},
};
diff --git a/apps/storybook/stories/TimeInput.stories.tsx b/apps/storybook/stories/TimeInput.stories.tsx
index 93a8278e6f..c10005e203 100644
--- a/apps/storybook/stories/TimeInput.stories.tsx
+++ b/apps/storybook/stories/TimeInput.stories.tsx
@@ -64,11 +64,24 @@ const meta: Meta<typeof TimeInput> = {
control: 'boolean',
description: 'Whether to show a clear button',
},
+ presentation: {
+ control: 'select',
+ options: [
+ 'text-input',
+ 'popover',
+ 'bottom-sheet',
+ 'native',
+ 'adaptive-bottom-sheet',
+ 'adaptive-native',
+ ],
+ description:
+ 'Which surface selects the time (spec:AST-043); nativePicker is deprecated',
+ },
nativePicker: {
control: 'radio',
options: ['touch', 'always', 'never'],
description:
- 'Native browser/OS time picker on touch by default, native wherever compatible, or Astryx typed field everywhere',
+ "Deprecated — use presentation ('touch' → 'adaptive-native', 'always' → 'native', 'never' → 'text-input'); presentation wins when both are set",
},
increment: {
control: 'number',
@@ -111,25 +124,32 @@ export const NativePickerModes: Story = {
return (
<div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
<TimeInput
- label="nativePicker='touch' (default)"
+ label="presentation='adaptive-native' (default)"
description="Native picker on a coarse primary pointer; Astryx typed field on a fine pointer"
value={value}
onChange={setValue}
- nativePicker="touch"
+ presentation="adaptive-native"
/>
<TimeInput
- label="nativePicker='always'"
+ label="presentation='native'"
description="Native picker wherever input type=time is compatible"
value={value}
onChange={setValue}
- nativePicker="always"
+ presentation="native"
+ />
+ <TimeInput
+ label="presentation='adaptive-bottom-sheet'"
+ description="Astryx bottom sheet on a coarse primary pointer; Astryx typed field on a fine pointer"
+ value={value}
+ onChange={setValue}
+ presentation="adaptive-bottom-sheet"
/>
<TimeInput
- label="nativePicker='never'"
+ label="presentation='text-input'"
description="Astryx typed field on every pointer type"
value={value}
onChange={setValue}
- nativePicker="never"
+ presentation="text-input"
/>
</div>
);
diff --git a/packages/cli/assets/codemods/transforms/next/__tests__/migrate-native-picker-to-presentation.test.mjs b/packages/cli/assets/codemods/transforms/next/__tests__/migrate-native-picker-to-presentation.test.mjs
new file mode 100644
index 0000000000..ae55807d92
--- /dev/null
+++ b/packages/cli/assets/codemods/transforms/next/__tests__/migrate-native-picker-to-presentation.test.mjs
@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import transform from '../migrate-native-picker-to-presentation.mjs';
+
+async function applyTransform(source) {
+ const jscodeshift = (await import('jscodeshift')).default;
+ const j = jscodeshift.withParser('tsx');
+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+ return transform({source, path: 'test.tsx'}, api) ?? source;
+}
+
+describe('migrate-native-picker-to-presentation', () => {
+ it('maps DateInput and DateTimeInput values (FR3)', async () => {
+ const output =
+ await applyTransform(`import {DateInput, DateTimeInput} from '@astryxdesign/core';
+const a = <DateInput label="d" nativePicker="touch" />;
+const b = <DateInput label="d" nativePicker="always" />;
+const c = <DateTimeInput label="dt" nativePicker="never" />;`);
+
+ expect(output).toContain("presentation='adaptive-native'");
+ expect(output).toContain("presentation='native'");
+ expect(output).toContain("presentation='adaptive-bottom-sheet'");
+ expect(output).not.toContain('nativePicker');
+ });
+
+ it('maps TimeInput never to text-input (FR3)', async () => {
+ const output =
+ await applyTransform(`import {TimeInput} from '@astryxdesign/core';
+const a = <TimeInput label="t" nativePicker="never" />;
+const b = <TimeInput label="t" nativePicker={'touch'} />;`);
+
+ expect(output).toContain("presentation='text-input'");
+ expect(output).toContain("presentation={'adaptive-native'}");
+ });
+
+ it('drops nativePicker when presentation is already set (FR4)', async () => {
+ const output =
+ await applyTransform(`import {DateInput} from '@astryxdesign/core';
+const a = <DateInput label="d" presentation="popover" nativePicker="always" />;`);
+
+ expect(output).toContain('presentation="popover"');
+ expect(output).not.toContain('nativePicker');
+ });
+
+ it('leaves dynamic values and unrelated components unchanged', async () => {
+ const source = `import {DateInput, Selector} from '@astryxdesign/core';
+const a = <DateInput label="d" nativePicker={mode} />;
+const b = <Selector nativePicker="never" />;`;
+ expect(await applyTransform(source)).toBe(source);
+ });
+
+ it('leaves a mixed static/dynamic conditional byte-identical when a sibling migrates', async () => {
+ const output =
+ await applyTransform(`import {TimeInput} from '@astryxdesign/core';
+const a = <TimeInput label="t" nativePicker="touch" />;
+const b = <TimeInput label="t" nativePicker={flag ? 'always' : mode} />;`);
+
+ expect(output).toContain("presentation='adaptive-native'");
+ expect(output).toContain("nativePicker={flag ? 'always' : mode}");
+ expect(output).not.toContain("'native'");
+ });
+});
diff --git a/packages/cli/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs b/packages/cli/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs
index 9efee8b0d6..b710550855 100644
--- a/packages/cli/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs
+++ b/packages/cli/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs
@@ -81,6 +81,7 @@ describe('migrate-theme-catalog-to-descriptors', () => {
it('is staged for the next release as a project codemod', () => {
expect(manifest.map(t => [t.name, t.meta.codemodType])).toEqual([
['migrate-theme-catalog-to-descriptors', 'project'],
+ ['migrate-native-picker-to-presentation', undefined],
]);
});
@@ -135,6 +136,9 @@ describe('migrate-theme-catalog-to-descriptors', () => {
it('previews without writing, even with no source folder', async () => {
writeKit([entry('ocean')]);
+ // A staged code codemod (migrate-native-picker-to-presentation) requires
+ // the source folder to exist; an empty one exercises the same preview.
+ fs.mkdirSync(path.join(root, 'src'), {recursive: true});
const result = await run(false, path.join(root, 'src'));
diff --git a/packages/cli/assets/codemods/transforms/next/index.mjs b/packages/cli/assets/codemods/transforms/next/index.mjs
index 66ba03012e..f15e506749 100644
--- a/packages/cli/assets/codemods/transforms/next/index.mjs
+++ b/packages/cli/assets/codemods/transforms/next/index.mjs
@@ -10,6 +10,9 @@
import migrateThemeCatalogToDescriptors, {
meta as migrateThemeCatalogToDescriptorsMeta,
} from './migrate-theme-catalog-to-descriptors.mjs';
+import migrateNativePickerToPresentation, {
+ meta as migrateNativePickerToPresentationMeta,
+} from './migrate-native-picker-to-presentation.mjs';
export default [
{
@@ -17,4 +20,9 @@ export default [
transform: migrateThemeCatalogToDescriptors,
meta: migrateThemeCatalogToDescriptorsMeta,
},
+ {
+ name: 'migrate-native-picker-to-presentation',
+ transform: migrateNativePickerToPresentation,
+ meta: migrateNativePickerToPresentationMeta,
+ },
];
diff --git a/packages/cli/assets/codemods/transforms/next/migrate-native-picker-to-presentation.mjs b/packages/cli/assets/codemods/transforms/next/migrate-native-picker-to-presentation.mjs
new file mode 100644
index 0000000000..b9736e30f5
--- /dev/null
+++ b/packages/cli/assets/codemods/transforms/next/migrate-native-picker-to-presentation.mjs
@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate nativePicker to presentation on date/time inputs
+ *
+ * `spec:AST-043` FR3 mapping, applied only to static literals written
+ * directly on imported `DateInput`, `DateTimeInput`, and `TimeInput`
+ * elements: the prop is renamed to `presentation` and its value mapped.
+ * When the element already sets `presentation`, the deprecated prop is
+ * removed (presentation wins, FR4). Dynamic values are left unchanged —
+ * the deprecated prop keeps working, so an unmigrated callsite is still
+ * correct, and guessing at an expression's values would not be.
+ */
+
+import {transformProp} from '../../transform-prop.mjs';
+
+export const meta = {
+ title: 'Migrate nativePicker to presentation',
+ description:
+ 'Renames `nativePicker` to `presentation` on DateInput, DateTimeInput, ' +
+ 'and TimeInput, mapping touch→adaptive-native, always→native, and ' +
+ 'never→adaptive-bottom-sheet (text-input for TimeInput). Dynamic ' +
+ 'values are left for manual migration; the deprecated prop still works.',
+};
+
+const CORE_IMPORT_RE = /^@(astryxdesign|xds)\/core(?:\/|$)/;
+
+const COMPONENT_PROPS = new Map([
+ ['DateInput', new Set(['nativePicker'])],
+ ['DateTimeInput', new Set(['nativePicker'])],
+ ['TimeInput', new Set(['nativePicker'])],
+]);
+
+/** @param {string} component @param {string} value */
+function mapValue(component, value) {
+ switch (value) {
+ case 'touch':
+ return 'adaptive-native';
+ case 'always':
+ return 'native';
+ case 'never':
+ return component === 'TimeInput' ? 'text-input' : 'adaptive-bottom-sheet';
+ default:
+ return undefined;
+ }
+}
+
+/**
+ * Collect the string-literal leaves of a value expression without mutating
+ * anything. Returns false for any dynamic or non-string node.
+ * @param {any} node
+ * @param {any[]} leaves
+ * @returns {boolean}
+ */
+function collectStaticLeaves(node, leaves) {
+ if (!node) return false;
+ if (
+ node.type === 'TSAsExpression' ||
+ node.type === 'TSSatisfiesExpression' ||
+ node.type === 'TypeCastExpression' ||
+ node.type === 'ParenthesizedExpression'
+ ) {
+ return collectStaticLeaves(node.expression, leaves);
+ }
+ if (node.type === 'ConditionalExpression') {
+ return (
+ collectStaticLeaves(node.consequent, leaves) &&
+ collectStaticLeaves(node.alternate, leaves)
+ );
+ }
+ if (
+ (node.type !== 'StringLiteral' && node.type !== 'Literal') ||
+ typeof node.value !== 'string'
+ ) {
+ return false;
+ }
+ leaves.push(node);
+ return true;
+}
+
+/**
+ * Map every leaf, or none of them: a mixed static/dynamic conditional must
+ * stay byte-identical, never half-migrated.
+ * @param {any} node
+ * @param {string} component
+ */
+function mapStaticValue(node, component) {
+ /** @type {any[]} */
+ const leaves = [];
+ if (!collectStaticLeaves(node, leaves)) return false;
+ if (leaves.some(leaf => mapValue(component, leaf.value) === undefined)) {
+ return false;
+ }
+ for (const leaf of leaves) {
+ leaf.value = mapValue(component, leaf.value);
+ if (leaf.raw) leaf.raw = undefined;
+ }
+ return true;
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+ if (!file.source.includes('nativePicker')) return undefined;
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ let hasChanges = false;
+
+ transformProp(
+ root,
+ j,
+ {
+ matchesImport: source => CORE_IMPORT_RE.test(source),
+ components: COMPONENT_PROPS,
+ },
+ (propPath, {component}) => {
+ const opening = propPath.parent?.node;
+ const attributes = opening?.attributes ?? [];
+ const hasPresentation = attributes.some(
+ (/** @type {any} */ attribute) =>
+ attribute.type === 'JSXAttribute' &&
+ attribute.name?.name === 'presentation',
+ );
+ const prop = propPath.node;
+ if (hasPresentation) {
+ // FR4: presentation wins; drop the deprecated prop.
+ opening.attributes = attributes.filter(
+ (/** @type {any} */ attribute) => attribute !== prop,
+ );
+ hasChanges = true;
+ return;
+ }
+ const value =
+ prop.value?.type === 'JSXExpressionContainer'
+ ? prop.value.expression
+ : prop.value;
+ if (!mapStaticValue(value, component)) return;
+ prop.name.name = 'presentation';
+ hasChanges = true;
+ },
+ );
+
+ if (!hasChanges) return undefined;
+ return root.toSource({quote: 'single'});
+}
diff --git a/packages/cli/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx b/packages/cli/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx
index 14199aa63e..12afae1423 100644
--- a/packages/cli/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx
+++ b/packages/cli/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx
@@ -41,7 +41,7 @@ export default function DateInputDateRange() {
max={max}
description={description}
placeholder="Select a booking date"
- nativePicker="never"
+ presentation="adaptive-bottom-sheet"
value={value}
onChange={setValue}
/>
diff --git a/packages/cli/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx b/packages/cli/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx
index a93fc2d0be..3ce662d841 100644
--- a/packages/cli/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx
+++ b/packages/cli/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx
@@ -17,6 +17,7 @@ export default function TimeInputConstrained() {
max={'22:00' as never}
description="Evening seating: 5 PM – 10 PM"
placeholder="Select reservation time"
+ presentation="adaptive-bottom-sheet"
value={evening as never}
onChange={setEvening as never}
hasClear
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index 8dc2bc6d5a..5c7bb74913 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -156,11 +156,18 @@ export const docs = {
"How the committed date value is displayed. Named values are reused from Timestamp's format vocabulary: 'date' shows 'Mar 21, 2026', 'date_long' shows 'March 21, 2026', 'date_weekday' shows 'Wed, Mar 21, 2026', 'system_date' shows '2026-03-21'. A function receives the ISO value and returns a custom string. Applies only to the committed value, never to text being typed.",
default: "'date_long'",
},
+ {
+ name: 'presentation',
+ type: "'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
+ description:
+ "Which surface draws the date picker. 'adaptive-native' (the default) uses Astryx's calendar popover on a fine pointer and the browser/OS picker (input type=date) on a coarse pointer, keeping Astryx fallbacks where a native control cannot express the value; 'native' always uses the browser/OS picker with no fallback; 'adaptive-bottom-sheet' uses the popover on a fine pointer and Astryx's bottom-sheet picker on a coarse pointer; 'popover' and 'bottom-sheet' force that Astryx surface on every pointer. Every value opens a picker; a typed-only field is TimeInput's alone. Use a non-native presentation for a field that needs weekStartsOn, numberOfMonths or dateConstraints, none of which a native picker can express.",
+ default: "'adaptive-native'",
+ },
{
name: 'nativePicker',
type: "'touch' | 'always' | 'never'",
description:
- "Which surface draws the date picker. 'touch' (the default) hands a touch device to the browser/OS: the field becomes an input type=date and the platform draws the picker (the iOS wheel, the Android calendar dialog); 'always' does that wherever the browser supports input type=date; 'never' keeps Astryx's own pickers everywhere (the bottom-sheet picker on a finger, the calendar popover on a mouse). Use 'never' for a field that needs weekStartsOn, numberOfMonths or dateConstraints, none of which a native picker can express. format and placeholder still apply in native mode; min and max are forwarded, but a native picker may not show them (on iOS an out-of-range date can be selected and is refused on commit rather than greyed out).",
+ "Deprecated: use presentation ('touch' = 'adaptive-native', 'always' = 'native', 'never' = 'adaptive-bottom-sheet'). Still works exactly as released; presentation wins when both are set.",
default: "'touch'",
},
{
@@ -178,9 +185,16 @@ export const docs = {
],
theming: {
targets: [
- {className: 'astryx-date-input', visualProps: ['size', 'status'], states: ['disabled']},
+ {
+ className: 'astryx-date-input',
+ visualProps: ['size', 'status'],
+ states: ['disabled'],
+ },
{className: 'astryx-date-input-toggle-icon', states: ['state']},
- {className: 'astryx-date-input-clear-icon', deprecatedFor: 'input-clear-icon'},
+ {
+ className: 'astryx-date-input-clear-icon',
+ deprecatedFor: 'input-clear-icon',
+ },
],
},
usage: {
@@ -434,7 +448,8 @@ export const docsZh = {
{
name: 'weekStartsOn',
type: "0 | 1 | 2 | 3 | 4 | 5 | 6 | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'",
- description: '日历弹出层中每周的起始日。可为数字(0=周日……6=周六)或三字母星期缩写。',
+ description:
+ '日历弹出层中每周的起始日。可为数字(0=周日……6=周六)或三字母星期缩写。',
default: '0',
},
{
@@ -444,11 +459,18 @@ export const docsZh = {
"已选日期的显示格式。命名值复用 Timestamp 的格式词汇:'date' 显示 'Mar 21, 2026','date_long' 显示 'March 21, 2026','date_weekday' 显示 'Wed, Mar 21, 2026','system_date' 显示 '2026-03-21'。函数接收 ISO 值并返回自定义字符串。仅作用于已提交的值,不影响正在输入的文本。",
default: "'date_long'",
},
+ {
+ name: 'presentation',
+ type: "'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
+ description:
+ "由哪个界面绘制日期选择器。'adaptive-native'(默认)在精细指针上使用 Astryx 日历弹出层、在粗指针上使用浏览器/操作系统选择器(input type=date),且原生控件无法表达值时保留 Astryx 回退;'native' 始终使用浏览器/操作系统选择器且不回退;'adaptive-bottom-sheet' 在精细指针上用弹出层、在粗指针上用 Astryx 底部选择器;'popover' 与 'bottom-sheet' 在任何指针上强制使用对应 Astryx 界面。每个值都会打开选择器;仅输入字段的呈现只属于 TimeInput。需要 weekStartsOn、numberOfMonths 或 dateConstraints 的字段应使用非原生呈现,原生选择器无法表达这些。",
+ default: "'adaptive-native'",
+ },
{
name: 'nativePicker',
type: "'touch' | 'always' | 'never'",
description:
- "由哪个界面绘制日期选择器。'touch'(默认)在触摸设备上交给浏览器/操作系统:字段变为 input type=date,由平台绘制选择器(iOS 滚轮、Android 日历对话框);'always' 在所有支持 input type=date 的浏览器上都这样做;'never' 始终使用 Astryx 自带的选择器(触摸设备用底部弹出选择器,鼠标设备用日历弹出层)。需要 weekStartsOn、numberOfMonths 或 dateConstraints 的字段应使用 'never',原生选择器无法表达这些。原生模式下 format 和 placeholder 仍然生效;min 和 max 会传递给原生控件,但原生选择器可能不会显示这些限制(在 iOS 上仍可选中超出范围的日期,会在提交时被拒绝,而不是变灰)。",
+ "已弃用:请使用 presentation('touch'='adaptive-native'、'always'='native'、'never'='adaptive-bottom-sheet')。仍按已发布行为工作;同时设置时以 presentation 为准。",
default: "'touch'",
},
{
@@ -466,7 +488,10 @@ export const docsZh = {
states: ['disabled'],
},
{className: 'astryx-date-input-toggle-icon', states: ['state']},
- {className: 'astryx-date-input-clear-icon', deprecatedFor: 'input-clear-icon'},
+ {
+ className: 'astryx-date-input-clear-icon',
+ deprecatedFor: 'input-clear-icon',
+ },
],
},
};
@@ -544,15 +569,19 @@ export const docsDense = {
placeholder: 'placeholder text in input',
size: 'input control size',
status: 'error/warning/success status w/ message',
- statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
+ statusVariant:
+ 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
labelTooltip: 'tooltip text via info icon at label end',
hasClear: 'Shows clear button when date is set. Clears value on click.',
numberOfMonths: 'months shown simultaneously in calendar popover',
- weekStartsOn: 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
+ weekStartsOn:
+ 'first day of week in calendar (0=Sunday, or name e.g. "mon")',
format:
"committed-value display: 'date_long' (default, March 21, 2026), 'date' (Mar 21, 2026), 'date_weekday' (Wed, Mar 21, 2026), 'system_date' (2026-03-21), or (iso)=>string; reuses Timestamp vocabulary. Committed value only, not while typing.",
+ presentation:
+ "which surface draws the picker: 'adaptive-native' (default) = Astryx popover on fine, browser/OS on coarse w/ Astryx fallbacks; 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = popover fine / Astryx sheet coarse; 'popover'/'bottom-sheet' force Astryx. every value opens a picker (no text-only value; that is TimeInput's). use non-native for weekStartsOn/numberOfMonths/dateConstraints.",
nativePicker:
- "which surface draws the picker: 'touch' (default) = browser/OS on a coarse pointer, 'always', 'never' = Astryx's own everywhere. use 'never' for weekStartsOn/numberOfMonths/dateConstraints. format+placeholder still apply; min/max forwarded but not necessarily shown by the OS picker, refused on commit instead.",
+ "deprecated, use presentation: 'touch'='adaptive-native', 'always'='native', 'never'='adaptive-bottom-sheet'. still works as released; presentation wins if both set.",
xstyle: 'StyleX styles for layout; must be stylex.create() value',
},
};
diff --git a/packages/core/src/DateInput/DateInput.tsx b/packages/core/src/DateInput/DateInput.tsx
index c60fdd00d4..97a2f75dc4 100644
--- a/packages/core/src/DateInput/DateInput.tsx
+++ b/packages/core/src/DateInput/DateInput.tsx
@@ -71,6 +71,12 @@ import {
formatSharedDate,
} from '../utils/plainDate';
import type {TimestampFormat} from '../Timestamp';
+import {
+ effectivePickerPresentation,
+ resolvePickerPresentation,
+ type PickerPresentation,
+} from '../utils/inputPresentation';
+import {useDevWarning} from '../hooks/useDevWarning';
const styles = stylex.create({
iconButton: {
@@ -164,8 +170,12 @@ export type DateInputSize = keyof typeof sizeStyles;
* - `'always'`: native wherever the browser supports `<input type="date">`
* - `'never'`: Astryx's own pickers everywhere
*/
+/** @deprecated Use {@link DateInputPresentation} via the `presentation` prop. */
export type DateInputNativePicker = 'touch' | 'always' | 'never';
+/** Which surface collects the date (`spec:AST-043` FR1; no `text-input` — TimeInput-only). */
+export type DateInputPresentation = PickerPresentation;
+
export type DateInputFormat = Extract<
TimestampFormat,
'date' | 'date_long' | 'date_weekday' | 'system_date'
@@ -404,13 +414,30 @@ export interface DateInputProps extends Omit<
* reason enough to prefer `'never'` on a field that uses it.
*
* @default 'touch'
- * @example
- * ```
- * // Astryx's own touch picker instead of the platform's
- * <DateInput label="Event date" value={date} onChange={setDate} nativePicker="never" />
- * ```
+ * @deprecated Use `presentation` (`spec:AST-043` FR3):
+ * `'touch'` → `'adaptive-native'`, `'always'` → `'native'`,
+ * `'never'` → `'adaptive-bottom-sheet'`. Still works exactly as released;
+ * `presentation` wins when both are set.
*/
nativePicker?: DateInputNativePicker;
+
+ /**
+ * Which surface collects the date (`spec:AST-043` FR1). Every value opens
+ * a picker; the typed-field-only `'text-input'` belongs to `TimeInput`.
+ *
+ * - `'popover'`: Astryx's typed field + calendar popover on every pointer
+ * - `'bottom-sheet'`: Astryx's bottom-sheet calendar on every pointer
+ * - `'native'`: the browser/OS picker on every pointer, with no Astryx
+ * fallback (FR2)
+ * - `'adaptive-bottom-sheet'`: popover on a fine pointer, bottom sheet on
+ * a coarse pointer
+ * - `'adaptive-native'` (default): popover on a fine pointer, browser/OS
+ * picker on a coarse pointer, keeping the released Astryx fallbacks
+ * where a native control cannot express the value (FR2)
+ *
+ * @default 'adaptive-native'
+ */
+ presentation?: DateInputPresentation;
}
/**
@@ -948,18 +975,28 @@ PointerDateField.displayName = 'PointerDateField';
*/
export function DateInput(props: DateInputProps) {
const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
- const nativePicker = props.nativePicker ?? 'touch';
-
- // The platform's picker, where the consumer asked for it — see the
- // `nativePicker` prop for what that trades away.
- if (nativePicker === 'always' || (nativePicker === 'touch' && isTouch)) {
- return <NativeDateField {...props} />;
- }
- return isTouch ? (
- <TouchDateField {...props} />
- ) : (
- <PointerDateField {...props} />
+ useDevWarning(
+ 'DateInput',
+ '`nativePicker` is deprecated; use `presentation` instead (`touch` → `adaptive-native`, `always` → `native`, `never` → `adaptive-bottom-sheet`). `presentation` wins when both are set.',
+ props.nativePicker !== undefined,
+ );
+ const surface = resolvePickerPresentation(
+ effectivePickerPresentation(props.presentation, props.nativePicker),
+ isTouch,
);
+ const {
+ presentation: _presentation,
+ nativePicker: _nativePicker,
+ ...rest
+ } = props;
+ switch (surface) {
+ case 'native':
+ return <NativeDateField {...rest} />;
+ case 'sheet':
+ return <TouchDateField {...rest} />;
+ case 'desktop':
+ return <PointerDateField {...rest} />;
+ }
}
DateInput.displayName = 'DateInput';
diff --git a/packages/core/src/DateInput/Presentation.test.tsx b/packages/core/src/DateInput/Presentation.test.tsx
new file mode 100644
index 0000000000..09dc840d3d
--- /dev/null
+++ b/packages/core/src/DateInput/Presentation.test.tsx
@@ -0,0 +1,121 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Presentation.test.tsx
+ * @input Uses vitest, Testing Library, and DateInput
+ * @output Tests for the `presentation` prop (`spec:AST-043` FR1–FR4)
+ * @position Testing; covers surface resolution and precedence
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {DateInput} from './DateInput';
+import {resetDateSegmentProbe} from './nativeDateSegments';
+
+const HOVER_CAPABLE = /\(\s*hover\s*:\s*hover\s*\)/;
+
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+function stubPointer(isCoarse: boolean): void {
+ vi.stubGlobal('matchMedia', (query: string) => ({
+ matches: /pointer:\s*coarse/.test(query)
+ ? isCoarse
+ : /pointer:\s*fine/.test(query)
+ ? !isCoarse
+ : HOVER_CAPABLE.test(query),
+ media: query,
+ onchange: null,
+ addListener: () => {},
+ removeListener: () => {},
+ addEventListener: () => {},
+ removeEventListener: () => {},
+ dispatchEvent: () => false,
+ }));
+ vi.stubGlobal('ResizeObserver', MockResizeObserver);
+}
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ resetDateSegmentProbe();
+});
+
+describe('DateInput presentation', () => {
+ it('popover forces the calendar field on a coarse pointer', () => {
+ stubPointer(true);
+ render(
+ <DateInput
+ label="Ship date"
+ presentation="popover"
+ onChange={() => {}}
+ />,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Open calendar'}),
+ ).toBeInTheDocument();
+ expect(document.querySelector('input[type="date"]')).toBeNull();
+ });
+
+ it('bottom-sheet forces the sheet field on a fine pointer', () => {
+ stubPointer(false);
+ render(
+ <DateInput
+ label="Ship date"
+ presentation="bottom-sheet"
+ onChange={() => {}}
+ />,
+ );
+ const input = screen.getByRole('combobox', {name: 'Ship date'});
+ expect(input).toHaveAttribute('readonly');
+ expect(document.querySelector('input[type="date"]')).toBeNull();
+ });
+
+ it('native forces the native field on a fine pointer', () => {
+ stubPointer(false);
+ render(
+ <DateInput label="Ship date" presentation="native" onChange={() => {}} />,
+ );
+ expect(document.querySelector('input[type="date"]')).not.toBeNull();
+ });
+
+ it('presentation wins over nativePicker (FR4)', () => {
+ stubPointer(false);
+ render(
+ <DateInput
+ label="Ship date"
+ presentation="bottom-sheet"
+ nativePicker="always"
+ onChange={() => {}}
+ />,
+ );
+ // A sheet on a fine pointer can only come from `presentation`: the
+ // deprecated `always` alone would have rendered the native field.
+ expect(screen.getByRole('combobox', {name: 'Ship date'})).toHaveAttribute(
+ 'readonly',
+ );
+ expect(document.querySelector('input[type="date"]')).toBeNull();
+ });
+
+ it('deprecated nativePicker="never" keeps popover/sheet by pointer (FR3)', () => {
+ stubPointer(false);
+ const {unmount} = render(
+ <DateInput label="Ship date" nativePicker="never" onChange={() => {}} />,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Open calendar'}),
+ ).toBeInTheDocument();
+ unmount();
+
+ stubPointer(true);
+ render(
+ <DateInput label="Ship date" nativePicker="never" onChange={() => {}} />,
+ );
+ expect(screen.getByRole('combobox', {name: 'Ship date'})).toHaveAttribute(
+ 'readonly',
+ );
+ });
+});
diff --git a/packages/core/src/DateInput/index.ts b/packages/core/src/DateInput/index.ts
index 8144a3e54d..049e0184ab 100644
--- a/packages/core/src/DateInput/index.ts
+++ b/packages/core/src/DateInput/index.ts
@@ -15,6 +15,7 @@ export type {
DateInputSize,
DateInputFormat,
DateInputNativePicker,
+ DateInputPresentation,
DateInputStatus,
DateInputStatusType,
} from './DateInput';
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
index 5a6e981d7c..30349b6b43 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
+++ b/packages/core/src/DateTimeInput/DateTimeInput.doc.mjs
@@ -121,14 +121,14 @@ export const docs = {
name: 'timeIncrement',
type: '1 | 5 | 10 | 15 | 30',
description:
- 'Minute step for arrow keys in Astryx\'s typed time field. A non-default value keeps the Astryx time field in nativePicker modes because iOS treats native step as validation, not picker cadence. Ignored by the Astryx touch sheet, which uses wheels.',
+ "Minute step for arrow keys in Astryx's typed time field. A non-default value keeps the Astryx time field in nativePicker modes because iOS treats native step as validation, not picker cadence. Ignored by the Astryx touch sheet, which uses wheels.",
default: '1',
},
{
name: 'timeOptionInterval',
type: '5 | 10 | 15 | 30 | 60',
description:
- 'Minute cadence for the preset-time combobox on Astryx\'s fine-pointer time field. Setting it keeps that Astryx time field even in nativePicker modes because the OS picker has no equivalent preset list. The Astryx touch sheet uses wheels.',
+ "Minute cadence for the preset-time combobox on Astryx's fine-pointer time field. Setting it keeps that Astryx time field even in nativePicker modes because the OS picker has no equivalent preset list. The Astryx touch sheet uses wheels.",
},
{
name: 'hasClear',
@@ -188,11 +188,18 @@ export const docs = {
'First day of week in Astryx calendars. A number (0 = Sunday to 6 = Saturday) or a three-letter day name. Ignored by native date controls.',
default: '0',
},
+ {
+ name: 'presentation',
+ type: "'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
+ description:
+ "Which surfaces draw the date and time pickers. 'adaptive-native' (the default) uses Astryx's typed fields and popovers on a fine pointer and browser/OS controls on a coarse pointer — with per-segment Astryx fallbacks: hasSeconds, non-default timeIncrement, or timeOptionInterval retain Astryx's time field because iOS cannot express them faithfully; 'native' always uses both browser/OS controls with no fallback; 'adaptive-bottom-sheet' uses popovers on a fine pointer and Astryx's coordinated bottom sheet on a coarse pointer; 'popover' and 'bottom-sheet' force that Astryx surface on every pointer. Every value opens pickers; typed-only fields are TimeInput's alone. Use a non-native presentation when numberOfMonths, weekStartsOn, or visible dateConstraints behavior matters. Constraints are enforced on commit; min/max are forwarded as hints. hourFormat formats the closed time, while the OS picker follows the user's locale.",
+ default: "'adaptive-native'",
+ },
{
name: 'nativePicker',
type: "'touch' | 'always' | 'never'",
description:
- "Which surfaces draw the date and time pickers. 'touch' (the default) uses browser/OS controls on a coarse primary pointer; 'always' uses them wherever input type=date/time are supported; 'never' keeps Astryx's own surfaces everywhere. The native time control is used only for the default minute-precision contract: hasSeconds, non-default timeIncrement, or timeOptionInterval retain Astryx's time field because iOS cannot express them faithfully. Use 'never' when numberOfMonths, weekStartsOn, or visible dateConstraints behavior matters. Constraints are enforced on commit; min/max are forwarded as hints. hourFormat formats the closed time, while the OS picker follows the user's locale.",
+ "Deprecated: use presentation ('touch' = 'adaptive-native', 'always' = 'native', 'never' = 'adaptive-bottom-sheet'). Still works exactly as released; presentation wins when both are set.",
default: "'touch'",
},
{
@@ -231,7 +238,7 @@ export const docs = {
},
usage: {
description:
- 'DateTimeInput combines date and time selection in one field. With nativePicker="touch" (the default), mouse/trackpad devices use Astryx typed fields and popovers, while coarse-pointer devices use browser/OS date and time controls in the same two-segment field. nativePicker="always" uses both native controls on every pointer; nativePicker="never" keeps Astryx\'s own surfaces — pointer fields on fine pointers and the coordinated Date/Time bottom sheet on coarse pointers. The closed segments stay side by side when at least 400px is available and wrap into full-width rows below 400px, independent of viewport width. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
+ 'DateTimeInput combines date and time selection in one field. With presentation="adaptive-native" (the default), mouse/trackpad devices use Astryx typed fields and popovers, while coarse-pointer devices use browser/OS date and time controls in the same two-segment field. presentation="native" uses both native controls on every pointer; presentation="adaptive-bottom-sheet" keeps Astryx\'s own surfaces — pointer fields on fine pointers and the coordinated Date/Time bottom sheet on coarse pointers; "popover" and "bottom-sheet" force one Astryx surface on every pointer. The closed segments stay side by side when at least 400px is available and wrap into full-width rows below 400px, independent of viewport width. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
bestPractices: [
{
guidance: true,
@@ -285,7 +292,7 @@ export const docs = {
name: 'Date input',
required: true,
description:
- 'A typed date field with calendar popover on the fine-pointer Astryx surface, a real input type=date in native modes, or a read-only segment opening the Astryx touch sheet when nativePicker is never on a coarse pointer.',
+ 'A typed date field with calendar popover on the fine-pointer Astryx surface, a real input type=date in native modes, or a read-only segment opening the Astryx touch sheet under presentation="adaptive-bottom-sheet" on a coarse pointer.',
},
{
name: 'Calendar icon',
@@ -297,19 +304,19 @@ export const docs = {
name: 'Date picker',
required: false,
description:
- 'The browser/OS picker in native modes, an Astryx month-grid popover on a fine pointer, or the Date panel of the Astryx bottom sheet on a coarse pointer with nativePicker="never".',
+ 'The browser/OS picker in native modes, an Astryx month-grid popover on a fine pointer, or the Date panel of the Astryx bottom sheet on a coarse pointer with presentation="adaptive-bottom-sheet".',
},
{
name: 'Time input',
required: true,
description:
- 'A real input type=time for the default minute-precision native mode, a text/combobox time field when seconds, custom increments, or preset options are requested, or a read-only segment opening accessible time wheels when nativePicker is never on a coarse pointer.',
+ 'A real input type=time for the default minute-precision native mode, a text/combobox time field when seconds, custom increments, or preset options are requested, or a read-only segment opening accessible time wheels under presentation="adaptive-bottom-sheet" on a coarse pointer.',
},
{
name: 'Time options popover',
required: false,
description:
- 'A list of preset times at the timeOptionInterval cadence. Setting the prop retains Astryx\'s text/combobox time field even when nativePicker otherwise selects native controls; the Astryx touch sheet uses wheels instead.',
+ "A list of preset times at the timeOptionInterval cadence. Setting the prop retains Astryx's text/combobox time field even when nativePicker otherwise selects native controls; the Astryx touch sheet uses wheels instead.",
},
{
name: 'Clear button',
@@ -331,7 +338,7 @@ export const docsZh = {
displayName: 'Date Time Input',
usage: {
description:
- 'DateTimeInput combines date and time selection in one field. With nativePicker="touch" (the default), mouse/trackpad devices use Astryx typed fields and popovers, while coarse-pointer devices use browser/OS date and time controls in the same two-segment field. nativePicker="always" uses both native controls on every pointer; nativePicker="never" keeps Astryx\'s own surfaces — pointer fields on fine pointers and the coordinated Date/Time bottom sheet on coarse pointers. The closed segments stay side by side when at least 400px is available and wrap into full-width rows below 400px, independent of viewport width. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
+ 'DateTimeInput combines date and time selection in one field. With presentation="adaptive-native" (the default), mouse/trackpad devices use Astryx typed fields and popovers, while coarse-pointer devices use browser/OS date and time controls in the same two-segment field. presentation="native" uses both native controls on every pointer; presentation="adaptive-bottom-sheet" keeps Astryx\'s own surfaces — pointer fields on fine pointers and the coordinated Date/Time bottom sheet on coarse pointers; "popover" and "bottom-sheet" force one Astryx surface on every pointer. The closed segments stay side by side when at least 400px is available and wrap into full-width rows below 400px, independent of viewport width. Use it for scheduling, event creation, deadline setting, or any form field that needs a specific datetime.',
bestPractices: [
{
guidance: true,
@@ -525,11 +532,18 @@ export const docsZh = {
'Astryx 日历中每周的起始日。可为数字(0=周日……6=周六)或三字母星期缩写。原生日期控件会忽略此属性。',
default: '0',
},
+ {
+ name: 'presentation',
+ type: "'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
+ description:
+ "选择由哪些界面绘制日期和时间选择器。'adaptive-native'(默认)在精细指针上使用 Astryx 文本字段与弹出层、在粗指针上使用浏览器/操作系统控件,并按段回退:hasSeconds、非默认 timeIncrement 或 timeOptionInterval 会保留 Astryx 时间字段;'native' 始终使用两个原生控件且不回退;'adaptive-bottom-sheet' 在精细指针上用弹出层、在粗指针上用 Astryx 协调底部面板;'popover' 与 'bottom-sheet' 在任何指针上强制使用对应 Astryx 界面。每个值都会打开选择器;仅文本字段的呈现只属于 TimeInput。需要 numberOfMonths、weekStartsOn 或可见 dateConstraints 行为时请使用非原生呈现。约束会在提交时执行,min/max 作为提示传给原生控件。hourFormat 格式化关闭状态的时间,而操作系统选择器遵循用户区域设置。",
+ default: "'adaptive-native'",
+ },
{
name: 'nativePicker',
type: "'touch' | 'always' | 'never'",
description:
- "选择由哪些界面绘制日期和时间选择器。'touch'(默认)在粗略主指针设备上使用浏览器/操作系统的原生控件;'always' 在支持 input type=date/time 的浏览器中始终使用原生控件;'never' 始终使用 Astryx 自带的界面。原生时间控件仅用于默认的分钟精度:hasSeconds、非默认 timeIncrement 或 timeOptionInterval 会保留 Astryx 时间字段,因为 iOS 无法忠实表达这些行为。需要 numberOfMonths、weekStartsOn 或可见 dateConstraints 行为时请使用 'never'。约束会在提交时执行,min/max 作为提示传给原生控件。hourFormat 格式化关闭状态的时间,而操作系统选择器遵循用户区域设置。",
+ "已弃用:请使用 presentation('touch'='adaptive-native'、'always'='native'、'never'='adaptive-bottom-sheet')。仍按已发布行为工作;同时设置时以 presentation 为准。",
default: "'touch'",
},
{
@@ -568,7 +582,7 @@ export const docsDense = {
'combined date + time picker with calendar popover and time input',
usage: {
description:
- 'DateTimeInput combines date and time selection. nativePicker="touch" (default) uses browser/OS date+time controls on coarse pointers and Astryx pointer fields on fine pointers; "always" uses both native controls everywhere; "never" uses Astryx\'s coordinated bottom sheet on coarse pointers and pointer fields on fine pointers. Closed segments stay side by side when at least 400px is available and wrap below 400px.',
+ 'DateTimeInput combines date and time selection. presentation="adaptive-native" (default) uses browser/OS date+time controls on coarse pointers and Astryx pointer fields on fine pointers; "native" uses both native controls everywhere; "adaptive-bottom-sheet" uses Astryx\'s coordinated bottom sheet on coarse pointers and pointer fields on fine pointers; "popover"/"bottom-sheet" force one Astryx surface everywhere. Closed segments stay side by side when at least 400px is available and wrap below 400px.',
bestPractices: [
{
guidance: true,
@@ -648,8 +662,10 @@ export const docsDense = {
'Astryx pointer-calendar months shown simultaneously; ignored by native date controls and the mobile touch sheet',
weekStartsOn:
'first day of week in Astryx calendars (0=Sunday, or name e.g. "mon"); ignored by native date controls',
+ presentation:
+ "date+time surfaces: 'adaptive-native' (default) = Astryx popovers fine / browser/OS coarse w/ per-segment fallbacks (seconds/timeIncrement/timeOptionInterval); 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = popovers fine / coordinated sheet coarse; 'popover'/'bottom-sheet' force Astryx. every value opens pickers (no typed-only value; that is TimeInput's).",
nativePicker:
- "date+time surfaces: 'touch' (default) = browser/OS controls on a coarse pointer, 'always' = native on every pointer, 'never' = Astryx calendar/time popovers on fine pointers and coordinated bottom sheet on coarse pointers. use 'never' for numberOfMonths/weekStartsOn/visible dateConstraints/timeOptionInterval; native mode enforces constraints on commit and forwards min/max.",
+ "deprecated, use presentation: 'touch'='adaptive-native', 'always'='native', 'never'='adaptive-bottom-sheet'. still works as released; presentation wins if both set.",
xstyle: 'StyleX styles for layout; must be stylex.create() value',
},
};
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsx
index 3c77df35d9..4ef83e6861 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx
@@ -102,12 +102,22 @@ import {useHighlightedOptionScroll} from '../hooks/useHighlightedOptionScroll';
import {NativeDateSegment} from './NativeDateSegment';
import {NativeTimeSegment} from './NativeTimeSegment';
import {TouchDateTimeField} from './TouchDateTimeField';
+import {
+ effectivePickerPresentation,
+ resolvePickerPresentation,
+ type PickerPresentation,
+} from '../utils/inputPresentation';
+import {useDevWarning} from '../hooks/useDevWarning';
export type ISODateTimeString = string & {
readonly __brand: 'ISODateTimeString';
};
+/** @deprecated Use {@link DateTimeInputPresentation} via the `presentation` prop. */
export type DateTimeInputNativePicker = 'touch' | 'always' | 'never';
+/** Which surfaces collect the date and time (`spec:AST-043` FR1; no `text-input` — TimeInput-only). */
+export type DateTimeInputPresentation = PickerPresentation;
+
export type DateTimeInputHourFormat = '12h' | '24h';
export type DateTimeInputSize = 'sm' | 'md' | 'lg';
@@ -501,17 +511,32 @@ export interface DateTimeInputProps extends Omit<
* user's locale.
*
* @default 'touch'
- * @example
- * ```
- * <DateTimeInput
- * label="Event time"
- * value={dateTime}
- * onChange={setDateTime}
- * nativePicker="never"
- * />
- * ```
+ * @deprecated Use `presentation` (`spec:AST-043` FR3):
+ * `'touch'` → `'adaptive-native'`, `'always'` → `'native'`,
+ * `'never'` → `'adaptive-bottom-sheet'`. Still works exactly as released;
+ * `presentation` wins when both are set.
*/
nativePicker?: DateTimeInputNativePicker;
+
+ /**
+ * Which surfaces collect the date and time (`spec:AST-043` FR1). Every
+ * value opens pickers; the typed-fields-only `'text-input'` belongs to
+ * `TimeInput`.
+ *
+ * - `'popover'`: Astryx's typed fields + popovers on every pointer
+ * - `'bottom-sheet'`: Astryx's bottom-sheet date/time wheels on every pointer
+ * - `'native'`: browser/OS date and time pickers on every pointer, with no
+ * Astryx fallback (FR2)
+ * - `'adaptive-bottom-sheet'`: popovers on a fine pointer, bottom sheet on
+ * a coarse pointer
+ * - `'adaptive-native'` (default): popovers on a fine pointer, browser/OS
+ * pickers on a coarse pointer, keeping the released per-segment Astryx
+ * fallbacks (seconds, non-default `timeIncrement`, `timeOptionInterval`)
+ * where a native control cannot express the value (FR2)
+ *
+ * @default 'adaptive-native'
+ */
+ presentation?: DateTimeInputPresentation;
}
function splitDateTime(dt: ISODateTimeString | undefined): {
@@ -593,27 +618,30 @@ function PointerDateTimeField({
labelTooltip,
numberOfMonths = 1,
weekStartsOn,
- nativePicker = 'touch',
width,
xstyle,
className,
style,
ref,
+ nativeMode = 'off',
...rest
-}: DateTimeInputProps) {
+}: DateTimeInputProps & {
+ nativeMode?: 'off' | 'adaptive' | 'forced' | 'legacy';
+}) {
const t = useTranslator();
const locale = useLocale();
- const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
- const usesNativePicker =
- nativePicker === 'always' || (nativePicker === 'touch' && isTouch);
+ const usesNativePicker = nativeMode !== 'off';
+ // `forced` (`presentation="native"`, FR2): no Astryx fallback. `adaptive`
+ // (`adaptive-native` coarse) and `legacy` (deprecated `always`):
// iOS's native time picker has no seconds wheel, treats step as validation
- // rather than picker cadence, and cannot express our preset-time list. Keep
- // the Astryx time field for those explicit contracts instead of losing them.
+ // rather than picker cadence, and cannot express our preset-time list, so
+ // those keep the Astryx time field — exactly as released.
const usesNativeTimePicker =
- usesNativePicker &&
- !hasSeconds &&
- timeIncrement === 1 &&
- timeOptionInterval === undefined;
+ nativeMode === 'forced' ||
+ ((nativeMode === 'adaptive' || nativeMode === 'legacy') &&
+ !hasSeconds &&
+ timeIncrement === 1 &&
+ timeOptionInterval === undefined);
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
// Speaks arrow-key stepping results through the persistent live regions:
// stepping programmatically rewrites a plain textbox's value, which screen
@@ -1920,25 +1948,48 @@ function PointerDateTimeField({
PointerDateTimeField.displayName = 'PointerDateTimeField';
/**
- * A combined date and time picker whose `nativePicker` prop chooses both
- * surfaces. Native modes use OS-owned date and time controls in Astryx field
- * chrome. With `nativePicker="never"`, fine pointers keep the typed fields and
- * popovers while coarse pointers get Astryx's coordinated Date/Time bottom
- * sheet.
+ * A combined date and time picker whose `presentation` prop chooses both
+ * surfaces (`spec:AST-043`). Native modes use OS-owned date and time controls
+ * in Astryx field chrome; the deprecated `nativePicker` maps to the same
+ * surfaces (FR3).
*/
-export function DateTimeInput({
- nativePicker = 'touch',
- ...props
-}: DateTimeInputProps) {
+export function DateTimeInput(props: DateTimeInputProps) {
const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
- const usesNativePicker =
- nativePicker === 'always' || (nativePicker === 'touch' && isTouch);
-
- return usesNativePicker || !isTouch ? (
- <PointerDateTimeField {...props} nativePicker={nativePicker} />
- ) : (
- <TouchDateTimeField {...props} />
+ useDevWarning(
+ 'DateTimeInput',
+ '`nativePicker` is deprecated; use `presentation` instead (`touch` → `adaptive-native`, `always` → `native`, `never` → `adaptive-bottom-sheet`). `presentation` wins when both are set.',
+ props.nativePicker !== undefined,
+ );
+ const effective = effectivePickerPresentation(
+ props.presentation,
+ props.nativePicker,
);
+ const {
+ presentation: _presentation,
+ nativePicker: _nativePicker,
+ ...rest
+ } = props;
+ if (effective === 'native') {
+ return (
+ <PointerDateTimeField
+ {...rest}
+ nativeMode={
+ props.presentation === undefined && props.nativePicker === 'always'
+ ? 'legacy'
+ : 'forced'
+ }
+ />
+ );
+ }
+ switch (resolvePickerPresentation(effective, isTouch)) {
+ case 'native':
+ // Only `adaptive-native` on a coarse pointer resolves here (FR2).
+ return <PointerDateTimeField {...rest} nativeMode="adaptive" />;
+ case 'sheet':
+ return <TouchDateTimeField {...rest} />;
+ case 'desktop':
+ return <PointerDateTimeField {...rest} />;
+ }
}
DateTimeInput.displayName = 'DateTimeInput';
diff --git a/packages/core/src/DateTimeInput/Presentation.test.tsx b/packages/core/src/DateTimeInput/Presentation.test.tsx
new file mode 100644
index 0000000000..e219371757
--- /dev/null
+++ b/packages/core/src/DateTimeInput/Presentation.test.tsx
@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Presentation.test.tsx
+ * @input Uses vitest, Testing Library, and DateTimeInput
+ * @output Tests for the `presentation` prop (`spec:AST-043` FR1–FR4)
+ * @position Testing; covers surface resolution and precedence
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {render} from '@testing-library/react';
+import {DateTimeInput} from './DateTimeInput';
+import {resetDateSegmentProbe} from '../DateInput/nativeDateSegments';
+
+const HOVER_CAPABLE = /\(\s*hover\s*:\s*hover\s*\)/;
+
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+function stubPointer(isCoarse: boolean): void {
+ vi.stubGlobal('matchMedia', (query: string) => ({
+ matches: /pointer:\s*coarse/.test(query)
+ ? isCoarse
+ : /pointer:\s*fine/.test(query)
+ ? !isCoarse
+ : HOVER_CAPABLE.test(query),
+ media: query,
+ onchange: null,
+ addListener: () => {},
+ removeListener: () => {},
+ addEventListener: () => {},
+ removeEventListener: () => {},
+ dispatchEvent: () => false,
+ }));
+ vi.stubGlobal('ResizeObserver', MockResizeObserver);
+}
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ resetDateSegmentProbe();
+});
+
+describe('DateTimeInput presentation', () => {
+ it('native forces native date and time segments on a fine pointer', () => {
+ stubPointer(false);
+ render(
+ <DateTimeInput label="Event" presentation="native" onChange={() => {}} />,
+ );
+ expect(document.querySelector('input[type="date"]')).not.toBeNull();
+ expect(document.querySelector('input[type="time"]')).not.toBeNull();
+ });
+
+ it('bottom-sheet forces the sheet field on a fine pointer', () => {
+ stubPointer(false);
+ render(
+ <DateTimeInput
+ label="Event"
+ presentation="bottom-sheet"
+ onChange={() => {}}
+ />,
+ );
+ for (const input of document.querySelectorAll('input[readonly]')) {
+ expect(input).toBeInTheDocument();
+ }
+ expect(document.querySelector('input[type="date"]')).toBeNull();
+ expect(document.querySelectorAll('input[readonly]').length).toBe(2);
+ });
+
+ it('presentation wins over nativePicker (FR4)', () => {
+ stubPointer(false);
+ render(
+ <DateTimeInput
+ label="Event"
+ presentation="bottom-sheet"
+ nativePicker="always"
+ onChange={() => {}}
+ />,
+ );
+ // A sheet on a fine pointer can only come from `presentation`: the
+ // deprecated `always` alone would have rendered both native controls.
+ expect(document.querySelector('input[type="date"]')).toBeNull();
+ expect(document.querySelector('input[type="time"]')).toBeNull();
+ expect(document.querySelectorAll('input[readonly]').length).toBe(2);
+ });
+});
diff --git a/packages/core/src/DateTimeInput/index.ts b/packages/core/src/DateTimeInput/index.ts
index 514235a431..7d81b060ad 100644
--- a/packages/core/src/DateTimeInput/index.ts
+++ b/packages/core/src/DateTimeInput/index.ts
@@ -15,6 +15,7 @@ export type {
DateTimeInputSize,
DateTimeInputHourFormat,
DateTimeInputNativePicker,
+ DateTimeInputPresentation,
DateTimeInputTimeIncrement,
DateTimeInputTimeOptionInterval,
DateTimeInputStatus,
diff --git a/packages/core/src/TimeInput/NativeTimeInput.test.tsx b/packages/core/src/TimeInput/NativeTimeInput.test.tsx
index b1168d3715..69de851be1 100644
--- a/packages/core/src/TimeInput/NativeTimeInput.test.tsx
+++ b/packages/core/src/TimeInput/NativeTimeInput.test.tsx
@@ -99,14 +99,47 @@ describe('TimeInput nativePicker', () => {
it.each([
['seconds', {hasSeconds: true}],
['custom increment', {increment: 15}],
- ] as const)('retains the typed field for %s', (_name, props) => {
- stubPointer(true);
+ ] as const)(
+ 'retains the typed field for %s under adaptive-native (default)',
+ (_name, props) => {
+ stubPointer(true);
+ render(<TimeInput label="Start time" onChange={() => {}} {...props} />);
+
+ expect(
+ screen.getByRole('textbox', {name: 'Start time'}),
+ ).toBeInTheDocument();
+ expect(document.querySelector('input[type="time"]')).toBeNull();
+ },
+ );
+
+ it.each([
+ ['seconds', {hasSeconds: true}],
+ ['custom increment', {increment: 15}],
+ ] as const)(
+ 'forces the native field for %s under presentation="native" (FR2)',
+ (_name, props) => {
+ stubPointer(false);
+ render(
+ <TimeInput
+ label="Start time"
+ presentation="native"
+ onChange={() => {}}
+ {...props}
+ />,
+ );
+
+ expect(getNativeTimeInput()).toBeInTheDocument();
+ },
+ );
+
+ it('deprecated nativePicker="always" keeps released fallbacks (FR2 legacy)', () => {
+ stubPointer(false);
render(
<TimeInput
label="Start time"
nativePicker="always"
+ hasSeconds
onChange={() => {}}
- {...props}
/>,
);
diff --git a/packages/core/src/TimeInput/Presentation.test.tsx b/packages/core/src/TimeInput/Presentation.test.tsx
new file mode 100644
index 0000000000..0875e367c5
--- /dev/null
+++ b/packages/core/src/TimeInput/Presentation.test.tsx
@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Presentation.test.tsx
+ * @input Uses vitest, Testing Library, and TimeInput
+ * @output Tests for the `presentation` prop (`spec:AST-043` FR1–FR4)
+ * @position Testing; covers surface resolution, fallback split, and precedence
+ */
+
+import {afterEach, beforeAll, describe, expect, it, vi} from 'vitest';
+import {fireEvent, render, screen} from '@testing-library/react';
+import {TimeInput} from './TimeInput';
+import {resetDateSegmentProbe} from '../DateInput/nativeDateSegments';
+
+const HOVER_CAPABLE = /\(\s*hover\s*:\s*hover\s*\)/;
+
+class MockResizeObserver {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+function stubPointer(isCoarse: boolean): void {
+ vi.stubGlobal('matchMedia', (query: string) => ({
+ matches: /pointer:\s*coarse/.test(query)
+ ? isCoarse
+ : /pointer:\s*fine/.test(query)
+ ? !isCoarse
+ : HOVER_CAPABLE.test(query),
+ media: query,
+ onchange: null,
+ addListener: () => {},
+ removeListener: () => {},
+ addEventListener: () => {},
+ removeEventListener: () => {},
+ dispatchEvent: () => false,
+ }));
+ vi.stubGlobal('ResizeObserver', MockResizeObserver);
+}
+
+beforeAll(() => {
+ window.scrollTo = vi.fn();
+ Element.prototype.scrollTo = vi.fn();
+ Element.prototype.scrollIntoView = vi.fn();
+ HTMLDialogElement.prototype.showModal = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.open = true;
+ });
+ HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+ this.open = true;
+ });
+ HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+ this.open = false;
+ });
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ resetDateSegmentProbe();
+});
+
+describe('TimeInput presentation', () => {
+ it('text-input renders the typed field on both pointers', () => {
+ for (const isCoarse of [false, true]) {
+ stubPointer(isCoarse);
+ const {unmount} = render(
+ <TimeInput
+ label="Start"
+ presentation="text-input"
+ onChange={() => {}}
+ />,
+ );
+ const input = screen.getByRole('textbox', {name: 'Start'});
+ expect(input).toHaveAttribute('type', 'text');
+ expect(input).not.toHaveAttribute('readonly');
+ expect(document.querySelector('input[type="time"]')).toBeNull();
+ unmount();
+ }
+ });
+
+ it('bottom-sheet renders the sheet field even on a fine pointer', () => {
+ stubPointer(false);
+ render(
+ <TimeInput
+ label="Start"
+ presentation="bottom-sheet"
+ onChange={() => {}}
+ />,
+ );
+ const input = screen.getByRole('combobox', {name: 'Start'});
+ expect(input).toHaveAttribute('readonly');
+ fireEvent.click(input);
+ expect(screen.getByRole('listbox', {name: 'Hour'})).toBeInTheDocument();
+ expect(screen.getByRole('listbox', {name: 'Minute'})).toBeInTheDocument();
+ });
+
+ it('adaptive-bottom-sheet: typed on fine, sheet on coarse', () => {
+ stubPointer(false);
+ const {unmount} = render(
+ <TimeInput
+ label="Start"
+ presentation="adaptive-bottom-sheet"
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByRole('textbox', {name: 'Start'})).not.toHaveAttribute(
+ 'readonly',
+ );
+ unmount();
+
+ stubPointer(true);
+ render(
+ <TimeInput
+ label="Start"
+ presentation="adaptive-bottom-sheet"
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByRole('combobox', {name: 'Start'})).toHaveAttribute(
+ 'readonly',
+ );
+ });
+
+ it('deprecated nativePicker="never" maps to text-input, not a sheet (FR3)', () => {
+ stubPointer(true);
+ render(
+ <TimeInput label="Start" nativePicker="never" onChange={() => {}} />,
+ );
+ const input = screen.getByRole('textbox', {name: 'Start'});
+ expect(input).not.toHaveAttribute('readonly');
+ });
+
+ it('presentation wins over nativePicker (FR4)', () => {
+ stubPointer(false);
+ render(
+ <TimeInput
+ label="Start"
+ presentation="text-input"
+ nativePicker="always"
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByRole('textbox', {name: 'Start'})).toBeInTheDocument();
+ expect(document.querySelector('input[type="time"]')).toBeNull();
+ });
+});
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index 95bf35aa09..edca28b66f 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -80,7 +80,7 @@ export const docs = {
name: 'Time control',
required: true,
description:
- 'A real input type=time in native modes, or Astryx\'s editable text field for fine pointers, nativePicker="never", seconds, and custom increments.',
+ 'A real input type=time in native modes, or Astryx\'s editable text field for fine pointers, presentation="text-input", seconds, and custom increments.',
},
{
name: 'Clear button',
@@ -210,11 +210,18 @@ export const docs = {
'Number of minutes to add or subtract when the user presses the up or down arrow key.',
default: '1',
},
+ {
+ name: 'presentation',
+ type: "'text-input' | 'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
+ description:
+ "Which surface selects the time. 'adaptive-native' (the default) uses Astryx's typed field on a fine pointer and the browser/OS input type=time on a coarse pointer — except hasSeconds or increment other than 1, which retain the typed field because iOS has no seconds wheel and treats step as validation rather than picker cadence; 'native' always uses the browser/OS control with no Astryx fallback; 'adaptive-bottom-sheet' uses the typed field on a fine pointer and Astryx's bottom-sheet time wheels on a coarse pointer; 'bottom-sheet' forces the wheels on every pointer; 'text-input' (like 'popover', which has no distinct TimeInput surface) keeps only the typed field. Native mode forwards min/max and enforces them on commit. hourFormat formats the closed value; the open OS picker follows the device locale.",
+ default: "'adaptive-native'",
+ },
{
name: 'nativePicker',
type: "'touch' | 'always' | 'never'",
description:
- "Which surface selects the time. 'touch' (the default) uses the browser/OS input type=time on a coarse pointer and Astryx's typed field on a fine pointer; 'always' requests the native control on every pointer; 'never' keeps Astryx's typed field everywhere. Native mode forwards min/max and enforces them on commit. hasSeconds or increment other than 1 automatically retains the typed field because iOS has no seconds wheel and treats step as validation rather than picker cadence. hourFormat formats the closed value; the open OS picker follows the device locale.",
+ "Deprecated: use presentation ('touch' = 'adaptive-native', 'always' = 'native', 'never' = 'text-input'). Still works exactly as released; presentation wins when both are set.",
default: "'touch'",
},
{
@@ -377,11 +384,18 @@ export const docsZh = {
description: '用户按上或下方向键时增加或减少的分钟数。',
default: '1',
},
+ {
+ name: 'presentation',
+ type: "'text-input' | 'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native'",
+ description:
+ "选择时间所用的界面。'adaptive-native'(默认)在精细指针上使用 Astryx 文本字段、在粗指针上使用浏览器/操作系统 input type=time——但 hasSeconds 或 increment 不为 1 时保留文本字段;'native' 始终使用浏览器/操作系统控件且不回退;'adaptive-bottom-sheet' 在精细指针上用文本字段、在粗指针上用 Astryx 底部滚轮选择器;'bottom-sheet' 在任何指针上强制使用滚轮;'text-input'(与无独立界面的 'popover' 相同)只保留文本字段。原生模式会传递 min/max 并在提交时强制校验。hourFormat 控制关闭状态的显示;打开的系统选择器遵循设备区域设置。",
+ default: "'adaptive-native'",
+ },
{
name: 'nativePicker',
type: "'touch' | 'always' | 'never'",
description:
- "选择时间所用的界面。'touch'(默认)在粗指针设备上使用浏览器/操作系统的 input type=time,在精细指针设备上使用 Astryx 文本字段;'always' 在所有指针类型上请求原生控件;'never' 始终使用 Astryx 文本字段。原生模式会传递 min/max 并在提交时强制校验。hasSeconds 或 increment 不为 1 时会自动保留文本字段,因为 iOS 没有秒滚轮,并且只把 step 当作校验规则而非选择器步进。hourFormat 控制关闭状态的显示;打开的系统选择器遵循设备区域设置。",
+ "已弃用:请使用 presentation('touch'='adaptive-native'、'always'='native'、'never'='text-input')。仍按已发布行为工作;同时设置时以 presentation 为准。",
default: "'touch'",
},
{
@@ -487,7 +501,7 @@ export const docsZh = {
name: 'Time control',
required: true,
description:
- '原生模式下使用真正的 input type=time;精细指针、nativePicker="never"、秒或自定义步进场景使用 Astryx 可编辑文本字段。',
+ '原生模式下使用真正的 input type=time;精细指针、presentation="text-input"、秒或自定义步进场景使用 Astryx 可编辑文本字段。',
},
{
name: 'Clear button',
@@ -583,8 +597,10 @@ export const docsDense = {
hourFormat:
"Display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
increment: 'Minutes to add/subtract on arrow up/down.',
+ presentation:
+ "picker surface: 'adaptive-native' (default) = typed field fine / browser/OS coarse (hasSeconds or increment!=1 retains typed); 'native' = browser/OS always, no fallback; 'adaptive-bottom-sheet' = typed fine / Astryx wheel sheet coarse; 'bottom-sheet' = sheet always; 'text-input'/'popover' = typed field only.",
nativePicker:
- "picker surface: 'touch' (default) = browser/OS on coarse pointer, 'always' = native wherever compatible, 'never' = Astryx typed field. hasSeconds or increment!=1 retains typed field; min/max enforced on commit.",
+ "deprecated, use presentation: 'touch'='adaptive-native', 'always'='native', 'never'='text-input'. still works as released; presentation wins if both set.",
placeholder: 'Placeholder when empty. Focused+empty shows format hint.',
size: 'Input element height.',
status: 'Colored border+icon. Message rendered below input.',
diff --git a/packages/core/src/TimeInput/TimeInput.tsx b/packages/core/src/TimeInput/TimeInput.tsx
index c70a071121..633fe2dbd5 100644
--- a/packages/core/src/TimeInput/TimeInput.tsx
+++ b/packages/core/src/TimeInput/TimeInput.tsx
@@ -77,6 +77,13 @@ import {useTranslator} from '../i18n';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {NativeTimeSegment} from '../DateTimeInput/NativeTimeSegment';
+import {TouchTimeField} from './TouchTimeField';
+import {
+ effectiveInputPresentation,
+ resolveInputPresentation,
+ type InputPresentation,
+} from '../utils/inputPresentation';
+import {useDevWarning} from '../hooks/useDevWarning';
const TOUCH_POINTER_QUERY = '(pointer: coarse)';
@@ -139,9 +146,12 @@ export type TimeInputSize = keyof typeof sizeStyles;
export type TimeInputHourFormat = '12h' | '24h';
-/** Which surface TimeInput uses for time selection. */
+/** @deprecated Use {@link TimeInputPresentation} via the `presentation` prop. */
export type TimeInputNativePicker = 'touch' | 'always' | 'never';
+/** Which surface TimeInput uses for time selection (`spec:AST-043` FR1). */
+export type TimeInputPresentation = InputPresentation;
+
// Re-export shared types for convenience
export type {
@@ -287,9 +297,32 @@ export interface TimeInputProps extends Omit<
* Native time pickers cannot preserve seconds or Astryx's arrow-key cadence,
* so `hasSeconds` or `increment !== 1` keeps the typed field.
* @default 'touch'
+ * @deprecated Use `presentation` (`spec:AST-043` FR3):
+ * `'touch'` → `'adaptive-native'`, `'always'` → `'native'`,
+ * `'never'` → `'text-input'`. Still works exactly as released;
+ * `presentation` wins when both are set.
*/
nativePicker?: TimeInputNativePicker;
+ /**
+ * Which surface selects the time (`spec:AST-043` FR1).
+ *
+ * - `'text-input'`: Astryx's typed field only (today's `nativePicker="never"`)
+ * - `'popover'`: no distinct popover exists for TimeInput; resolves to the
+ * typed field (FR1 surface table)
+ * - `'bottom-sheet'`: Astryx's bottom-sheet time wheels on every pointer
+ * - `'native'`: the browser/OS `<input type="time">` on every pointer, with
+ * no Astryx fallback (FR2)
+ * - `'adaptive-bottom-sheet'`: typed field on a fine pointer, bottom sheet
+ * on a coarse pointer
+ * - `'adaptive-native'` (default): typed field on a fine pointer, browser/OS
+ * picker on a coarse pointer, keeping the released Astryx fallback
+ * (`hasSeconds` or `increment !== 1`) where native cannot express it (FR2)
+ *
+ * @default 'adaptive-native'
+ */
+ presentation?: TimeInputPresentation;
+
/**
* Placeholder text shown when no time is selected.
* @default "Select a time"
@@ -345,7 +378,7 @@ export interface TimeInputProps extends Omit<
* />
* ```
*/
-export function TimeInput({
+function TimeField({
label,
isLabelHidden = false,
description,
@@ -364,7 +397,6 @@ export function TimeInput({
hasAutoFocus = false,
hourFormat = '12h',
increment = 1,
- nativePicker = 'touch',
placeholder: placeholderFromProps,
size: sizeProp,
status,
@@ -375,19 +407,23 @@ export function TimeInput({
className,
style,
ref,
-}: TimeInputProps) {
+ nativeMode = 'off',
+}: TimeInputProps & {nativeMode?: 'off' | 'adaptive' | 'forced' | 'legacy'}) {
const t = useTranslator();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.timeInput.placeholder');
const size = useSize(sizeProp, 'md');
- const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
- const requestsNativePicker =
- nativePicker === 'always' || (nativePicker === 'touch' && isTouch);
- // iOS has no seconds wheel and treats step as validation rather than wheel
- // cadence. Preserve those explicit Astryx contracts instead of degrading them.
+ // `forced` (explicit `presentation="native"`, FR2): always native, no
+ // fallback. `adaptive` (`adaptive-native` coarse) and `legacy` (deprecated
+ // `nativePicker="always"`): iOS has no seconds wheel and treats step as
+ // validation rather than wheel cadence, so those keep the typed field —
+ // `legacy` on every pointer, exactly as released.
const usesNativeTimePicker =
- requestsNativePicker && !hasSeconds && increment === 1;
+ nativeMode === 'forced' ||
+ ((nativeMode === 'adaptive' || nativeMode === 'legacy') &&
+ !hasSeconds &&
+ increment === 1);
const id = useId();
const inputLabelID = useId();
@@ -811,4 +847,54 @@ export function TimeInput({
);
}
+TimeField.displayName = 'TimeField';
+
+/**
+ * A time input whose `presentation` prop chooses the selection surface
+ * (`spec:AST-043`); the deprecated `nativePicker` maps to the same surfaces
+ * (FR3).
+ */
+export function TimeInput(props: TimeInputProps) {
+ const isTouch = useMediaQuery(TOUCH_POINTER_QUERY);
+ useDevWarning(
+ 'TimeInput',
+ '`nativePicker` is deprecated; use `presentation` instead (`touch` → `adaptive-native`, `always` → `native`, `never` → `text-input`). `presentation` wins when both are set.',
+ props.nativePicker !== undefined,
+ );
+ const effective = effectiveInputPresentation(
+ props.presentation,
+ props.nativePicker,
+ 'time',
+ );
+ const {
+ presentation: _presentation,
+ nativePicker: _nativePicker,
+ ...rest
+ } = props;
+ if (effective === 'native') {
+ // Deprecated `always` keeps released fallbacks (FR2 legacy); only an
+ // explicit `presentation="native"` is forced.
+ return (
+ <TimeField
+ {...rest}
+ nativeMode={
+ props.presentation === undefined && props.nativePicker === 'always'
+ ? 'legacy'
+ : 'forced'
+ }
+ />
+ );
+ }
+ switch (resolveInputPresentation(effective, isTouch)) {
+ case 'native':
+ // Only `adaptive-native` on a coarse pointer resolves here (FR2).
+ return <TimeField {...rest} nativeMode="adaptive" />;
+ case 'sheet':
+ return <TouchTimeField {...rest} />;
+ case 'text-input':
+ case 'desktop':
+ return <TimeField {...rest} />;
+ }
+}
+
TimeInput.displayName = 'TimeInput';
diff --git a/packages/core/src/TimeInput/TouchTimeField.tsx b/packages/core/src/TimeInput/TouchTimeField.tsx
new file mode 100644
index 0000000000..44c20bbf08
--- /dev/null
+++ b/packages/core/src/TimeInput/TouchTimeField.tsx
@@ -0,0 +1,572 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TouchTimeField.tsx
+ * @input Uses React, Field, BottomSheet, Wheel, DateInput touch geometry
+ * tokens, and shared time utilities
+ * @output Exports TouchTimeField — the bottom-sheet surface behind TimeInput
+ * @position Internal component; consumed by TimeInput.tsx for `presentation`
+ * sheet surfaces (`spec:AST-043` DEC-3: the time half of DateTimeInput's sheet)
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/TimeInput/TimeInput.tsx
+ * - /packages/core/src/TimeInput/TimeInput.doc.mjs
+ * - /packages/core/src/DateTimeInput/TouchDateTimeField.tsx (wheel behavior)
+ */
+
+import {
+ useCallback,
+ useId,
+ useMemo,
+ useOptimistic,
+ useRef,
+ useState,
+ useTransition,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {BottomSheet} from '../BottomSheet';
+import {Button} from '../Button';
+import {
+ Field,
+ InputClearButton,
+ inputWrapperStyles,
+ inputStatusBorderStyles,
+ inputStatusHoverShadowStyles,
+ inputStatusFocusWithinStyles,
+} from '../Field';
+import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {groupStyles} from '../InputGroup/groupStyles';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import {Icon} from '../Icon';
+import {useTranslator} from '../i18n';
+import {sizeVars, spacingVars} from '../theme/tokens.stylex';
+import {useSize} from '../SizeContext/SizeContext';
+import {Spinner} from '../Spinner';
+import {useTooltip} from '../Tooltip';
+import {Wheel, type WheelOption} from '../DateInput/Wheel';
+import {dateInputTouchGeometry} from '../DateInput/tokens.stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {themeProps} from '../utils/themeProps';
+import {
+ clampTime,
+ formatDisplayTime12h,
+ formatDisplayTime24h,
+ formatISOTime,
+ getInputARIA,
+ isTimeInRange,
+ mergeProps,
+ parseISOTime,
+ type ISOTimeString,
+} from '../utils';
+import type {TimeInputProps} from './TimeInput';
+
+const sizeStyles = stylex.create({
+ sm: {height: sizeVars['--size-element-sm'], minWidth: 120},
+ md: {height: sizeVars['--size-element-md'], minWidth: 120},
+ lg: {height: sizeVars['--size-element-lg'], minWidth: 120},
+});
+
+const styles = stylex.create({
+ iconButton: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ padding: 0,
+ margin: 0,
+ borderWidth: 0,
+ borderStyle: 'none',
+ backgroundColor: 'transparent',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled,[aria-disabled="true"])': 'default',
+ },
+ flexShrink: 0,
+ },
+ input: {
+ display: 'block',
+ flex: 1,
+ minWidth: 0,
+ borderWidth: 0,
+ borderStyle: 'none',
+ padding: 0,
+ backgroundColor: 'transparent',
+ outline: 'none',
+ cursor: {
+ default: 'pointer',
+ ':is(:disabled,[aria-disabled="true"])': 'default',
+ },
+ },
+ // Sheet chrome mirrors TouchDateTimeField: `touchSheetBody` insets (the
+ // BottomSheet handle floats over the panel, so the wrapper supplies the top
+ // clearance and the side/bottom insets) flattened with `touchPanel`'s column
+ // layout, which is the wheels' direct parent there and spaces the footer.
+ sheetBody: {
+ boxSizing: 'border-box',
+ display: 'flex',
+ flexDirection: 'column',
+ inlineSize: '100%',
+ minInlineSize: 0,
+ gap: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-4'],
+ paddingBlockStart: spacingVars['--spacing-6'],
+ paddingBlockEnd: spacingVars['--spacing-4'],
+ },
+ wheels: {
+ display: 'flex',
+ inlineSize: '100%',
+ minInlineSize: 0,
+ blockSize: dateInputTouchGeometry.paneBlockSize,
+ gap: spacingVars['--spacing-2'],
+ },
+ footer: {
+ display: 'flex',
+ marginBlockStart: 'auto',
+ paddingBlockStart: spacingVars['--spacing-1'],
+ },
+});
+
+function twoDigits(value: number): string {
+ return String(value).padStart(2, '0');
+}
+
+function hour12From24(hour: number): number {
+ return hour === 0 ? 12 : hour > 12 ? hour - 12 : hour;
+}
+
+function hour24From12(hour: number, meridiem: number): number {
+ if (meridiem === 0) {
+ return hour === 12 ? 0 : hour;
+ }
+ return hour === 12 ? 12 : hour + 12;
+}
+
+function timeToSeconds(time: ISOTimeString | undefined): number | null {
+ if (time == null) {
+ return null;
+ }
+ const parsed = parseISOTime(time);
+ return parsed == null
+ ? null
+ : parsed.hour * 3600 + parsed.minute * 60 + parsed.second;
+}
+
+function rangeOverlaps(
+ startSecond: number,
+ endSecond: number,
+ min: ISOTimeString | undefined,
+ max: ISOTimeString | undefined,
+): boolean {
+ const minSecond = timeToSeconds(min);
+ const maxSecond = timeToSeconds(max);
+ return (
+ (minSecond == null || endSecond >= minSecond) &&
+ (maxSecond == null || startSecond <= maxSecond)
+ );
+}
+
+/**
+ * The Astryx bottom-sheet time surface: a read-only closed field that opens
+ * hour/minute(/second/meridiem) wheels in a BottomSheet. Wheels commit live,
+ * clamped to `min`/`max`; the footer Save button only closes the sheet.
+ */
+export function TouchTimeField({
+ label,
+ isLabelHidden = false,
+ description,
+ isOptional = false,
+ isRequired = false,
+ isDisabled = false,
+ disabledMessage,
+ value,
+ onChange,
+ changeAction,
+ isLoading = false,
+ min,
+ max,
+ hasSeconds = false,
+ hasClear = false,
+ hourFormat = '12h',
+ placeholder: placeholderFromProps,
+ size: sizeProp,
+ status,
+ statusVariant = 'attached',
+ labelTooltip,
+ width,
+ xstyle,
+ className,
+ style,
+ ref,
+}: TimeInputProps) {
+ const t = useTranslator();
+ const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
+ const placeholder =
+ placeholderFromProps ?? t('@astryx.timeInput.placeholder');
+ const size = useSize(sizeProp, 'md');
+ const id = useId();
+ const inputLabelID = useId();
+ const descriptionID = useId();
+ const statusMessageID = useId();
+ const inputRef = useRef<HTMLInputElement | null>(null);
+ const mergedInputRef = useMergedRefs(ref, inputRef);
+ const inputGroup = useInputGroup();
+ const [isSheetOpen, setIsSheetOpen] = useState(false);
+ const [, startTransition] = useTransition();
+ const [optimisticValue, setOptimisticValue] = useOptimistic(value);
+ const isBusy = isLoading || optimisticValue !== value;
+ const isEffectivelyDisabled = isDisabled || isLoading;
+
+ const showsDisabledMessage = isDisabled && !!disabledMessage;
+ const disabledMessageTooltip = useTooltip({
+ placement: 'above',
+ focusTrigger: 'always',
+ isEnabled: showsDisabledMessage,
+ });
+ const {statusIcon, describedBy: statusTooltipDescribedBy} =
+ useInputStatusIcon({status, statusVariant, isInGroup: !!inputGroup});
+ const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
+ inputLabelID,
+ [
+ description ? descriptionID : null,
+ statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+ statusTooltipDescribedBy,
+ showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
+ ],
+ inputGroup,
+ );
+
+ const fireChange = useCallback(
+ (newValue: ISOTimeString | undefined) => {
+ if (isEffectivelyDisabled) {
+ return;
+ }
+ onChange?.(newValue);
+ if (changeAction) {
+ startTransition(async () => {
+ setOptimisticValue(newValue);
+ await changeAction(newValue);
+ });
+ }
+ },
+ [changeAction, isEffectivelyDisabled, onChange, setOptimisticValue],
+ );
+
+ const formatDisplayTime =
+ hourFormat === '12h' ? formatDisplayTime12h : formatDisplayTime24h;
+ const displayValue = optimisticValue
+ ? formatDisplayTime(optimisticValue, hasSeconds)
+ : '';
+
+ const fallbackTime = useMemo(() => {
+ const now = new Date();
+ return formatISOTime(
+ {
+ hour: now.getHours(),
+ minute: now.getMinutes(),
+ second: now.getSeconds(),
+ },
+ hasSeconds,
+ );
+ }, [hasSeconds]);
+ const parsedWheelTime = useMemo(
+ () =>
+ parseISOTime(optimisticValue ?? fallbackTime) ?? {
+ hour: 0,
+ minute: 0,
+ second: 0,
+ },
+ [fallbackTime, optimisticValue],
+ );
+
+ const composeWheelTime = useCallback(
+ (patch: {
+ hour24?: number;
+ hour12?: number;
+ minute?: number;
+ second?: number;
+ meridiem?: number;
+ }): ISOTimeString => {
+ const meridiem = patch.meridiem ?? (parsedWheelTime.hour < 12 ? 0 : 1);
+ let hour = parsedWheelTime.hour;
+ if (patch.hour24 !== undefined) {
+ hour = patch.hour24;
+ } else if (patch.hour12 !== undefined) {
+ hour = hour24From12(patch.hour12, meridiem);
+ } else if (patch.meridiem !== undefined) {
+ hour = hour24From12(hour12From24(hour), patch.meridiem);
+ }
+ return formatISOTime(
+ {
+ hour,
+ minute: patch.minute ?? parsedWheelTime.minute,
+ second: hasSeconds ? (patch.second ?? parsedWheelTime.second) : 0,
+ },
+ hasSeconds,
+ );
+ },
+ [hasSeconds, parsedWheelTime],
+ );
+
+ const commitWheelTime = useCallback(
+ (rawTime: ISOTimeString) => {
+ const next = clampTime(rawTime, min, max, hasSeconds);
+ if (next !== optimisticValue && isTimeInRange(next, min, max)) {
+ fireChange(next);
+ }
+ },
+ [fireChange, hasSeconds, max, min, optimisticValue],
+ );
+
+ const hourOptions: WheelOption[] = useMemo(() => {
+ if (hourFormat === '24h') {
+ return Array.from({length: 24}, (_, hour) => ({
+ value: hour,
+ label: twoDigits(hour),
+ isDisabled: !rangeOverlaps(hour * 3600, hour * 3600 + 3599, min, max),
+ }));
+ }
+ const meridiem = parsedWheelTime.hour < 12 ? 0 : 1;
+ return Array.from({length: 12}, (_, index) => {
+ const hour = index + 1;
+ const hour24 = hour24From12(hour, meridiem);
+ return {
+ value: hour,
+ label: String(hour),
+ isDisabled: !rangeOverlaps(
+ hour24 * 3600,
+ hour24 * 3600 + 3599,
+ min,
+ max,
+ ),
+ };
+ });
+ }, [hourFormat, max, min, parsedWheelTime.hour]);
+
+ const minuteOptions: WheelOption[] = useMemo(
+ () =>
+ Array.from({length: 60}, (_, minute) => {
+ const start = parsedWheelTime.hour * 3600 + minute * 60;
+ return {
+ value: minute,
+ label: twoDigits(minute),
+ isDisabled: !rangeOverlaps(
+ start,
+ start + (hasSeconds ? 59 : 0),
+ min,
+ max,
+ ),
+ };
+ }),
+ [hasSeconds, max, min, parsedWheelTime.hour],
+ );
+
+ const secondOptions: WheelOption[] = useMemo(
+ () =>
+ Array.from({length: 60}, (_, second) => ({
+ value: second,
+ label: twoDigits(second),
+ isDisabled: !isTimeInRange(
+ formatISOTime(
+ {
+ hour: parsedWheelTime.hour,
+ minute: parsedWheelTime.minute,
+ second,
+ },
+ true,
+ ),
+ min,
+ max,
+ ),
+ })),
+ [max, min, parsedWheelTime.hour, parsedWheelTime.minute],
+ );
+
+ const meridiemOptions: WheelOption[] = useMemo(
+ () => [
+ {
+ value: 0,
+ label: t('@astryx.dateTimeInput.meridiemAM'),
+ isDisabled: !rangeOverlaps(0, 11 * 3600 + 3599, min, max),
+ },
+ {
+ value: 1,
+ label: t('@astryx.dateTimeInput.meridiemPM'),
+ isDisabled: !rangeOverlaps(12 * 3600, 23 * 3600 + 3599, min, max),
+ },
+ ],
+ [max, min, t],
+ );
+
+ const openSheet = useCallback(() => {
+ if (!isEffectivelyDisabled) {
+ setIsSheetOpen(true);
+ }
+ }, [isEffectivelyDisabled]);
+
+ const inputWrapper = (
+ <div
+ ref={el => {
+ disabledMessageTooltip.ref(el);
+ }}
+ {...mergeProps(
+ themeProps('time-input', {
+ size,
+ status: status?.type ?? null,
+ disabled: isDisabled ? 'disabled' : null,
+ }),
+ stylex.props(
+ inputWrapperStyles.base,
+ sizeStyles[size],
+ isDisabled && inputWrapperStyles.disabled,
+ status && inputStatusBorderStyles[status.type],
+ status && !isDisabled && inputStatusHoverShadowStyles[status.type],
+ status && inputStatusFocusWithinStyles[status.type],
+ inputGroup && groupStyles.inGroup,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ <button
+ type="button"
+ onClick={openSheet}
+ disabled={isEffectivelyDisabled}
+ aria-label={t('@astryx.timeInput.openPicker', {label})}
+ tabIndex={-1}
+ {...stylex.props(focusOutlineStyles.focusVisible, styles.iconButton)}>
+ <Icon icon="clock" size="sm" color="secondary" />
+ </button>
+ <input
+ ref={mergedInputRef}
+ id={id}
+ type="text"
+ role="combobox"
+ value={displayValue}
+ readOnly
+ inputMode="none"
+ onChange={() => {}}
+ onClick={openSheet}
+ placeholder={placeholder}
+ disabled={isEffectivelyDisabled && !showsDisabledMessage}
+ aria-disabled={showsDisabledMessage ? 'true' : undefined}
+ aria-describedby={ariaDescribedBy}
+ aria-required={isEffectivelyRequired ? 'true' : undefined}
+ aria-invalid={status?.type === 'error' ? 'true' : undefined}
+ aria-busy={isBusy || undefined}
+ aria-expanded={isSheetOpen}
+ aria-haspopup="dialog"
+ aria-autocomplete="none"
+ autoComplete="off"
+ aria-labelledby={ariaLabelledBy}
+ {...stylex.props(styles.input)}
+ />
+ {isBusy && <Spinner size="sm" />}
+ {hasClear && optimisticValue && !isEffectivelyDisabled && (
+ <InputClearButton
+ label={t('@astryx.timeInput.clearLabel', {label})}
+ onClick={() => fireChange(undefined)}
+ />
+ )}
+ {statusIcon}
+ <BottomSheet
+ isOpen={isSheetOpen}
+ onOpenChange={setIsSheetOpen}
+ label={label}
+ height="hug">
+ <div {...stylex.props(styles.sheetBody)}>
+ <div {...stylex.props(styles.wheels)}>
+ <Wheel
+ label={t('@astryx.dateTimeInput.hourWheel')}
+ options={hourOptions}
+ value={
+ hourFormat === '24h'
+ ? parsedWheelTime.hour
+ : hour12From24(parsedWheelTime.hour)
+ }
+ isActive={isSheetOpen}
+ onChange={hour =>
+ commitWheelTime(
+ hourFormat === '24h'
+ ? composeWheelTime({hour24: hour})
+ : composeWheelTime({hour12: hour}),
+ )
+ }
+ />
+ <Wheel
+ label={t('@astryx.dateTimeInput.minuteWheel')}
+ options={minuteOptions}
+ value={parsedWheelTime.minute}
+ isActive={isSheetOpen}
+ onChange={minute => commitWheelTime(composeWheelTime({minute}))}
+ />
+ {hasSeconds && (
+ <Wheel
+ label={t('@astryx.dateTimeInput.secondWheel')}
+ options={secondOptions}
+ value={parsedWheelTime.second}
+ isActive={isSheetOpen}
+ onChange={second => commitWheelTime(composeWheelTime({second}))}
+ />
+ )}
+ {hourFormat === '12h' && (
+ <Wheel
+ label={t('@astryx.dateTimeInput.meridiemWheel')}
+ options={meridiemOptions}
+ value={parsedWheelTime.hour < 12 ? 0 : 1}
+ isActive={isSheetOpen}
+ onChange={meridiem =>
+ commitWheelTime(composeWheelTime({meridiem}))
+ }
+ />
+ )}
+ </div>
+ <div {...stylex.props(styles.footer)}>
+ <Button
+ variant="primary"
+ size="md"
+ width="100%"
+ label={t('@astryx.dateInput.savePicking')}
+ onClick={() => setIsSheetOpen(false)}
+ />
+ </div>
+ </div>
+ </BottomSheet>
+ {showsDisabledMessage &&
+ disabledMessageTooltip.renderTooltip(disabledMessage)}
+ </div>
+ );
+
+ if (inputGroup) {
+ return inputWrapper;
+ }
+ return (
+ <Field
+ label={label}
+ isLabelHidden={isLabelHidden}
+ description={description}
+ inputID={id}
+ descriptionID={description ? descriptionID : undefined}
+ isOptional={isOptional}
+ isRequired={isRequired}
+ isDisabled={isDisabled}
+ status={
+ status
+ ? {
+ type: status.type,
+ message: status.message,
+ messageID: status.message ? statusMessageID : undefined,
+ }
+ : undefined
+ }
+ statusVariant={statusVariant}
+ labelTooltip={labelTooltip}
+ width={width}>
+ {inputWrapper}
+ </Field>
+ );
+}
+
+TouchTimeField.displayName = 'TouchTimeField';
diff --git a/packages/core/src/TimeInput/index.ts b/packages/core/src/TimeInput/index.ts
index e4a1da8bc7..0e30df47b0 100644
--- a/packages/core/src/TimeInput/index.ts
+++ b/packages/core/src/TimeInput/index.ts
@@ -17,6 +17,7 @@ export type {
TimeInputSize,
TimeInputHourFormat,
TimeInputNativePicker,
+ TimeInputPresentation,
TimeInputStatus,
TimeInputStatusType,
} from './TimeInput';
diff --git a/packages/core/src/utils/inputPresentation.ts b/packages/core/src/utils/inputPresentation.ts
new file mode 100644
index 0000000000..778c0fbb75
--- /dev/null
+++ b/packages/core/src/utils/inputPresentation.ts
@@ -0,0 +1,143 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file inputPresentation.ts
+ * @input A presentation policy, the deprecated nativePicker value, and pointer type
+ * @output The resolved picker surface for DateInput, DateTimeInput, and TimeInput
+ * @position Shared presentation vocabulary owned by spec:AST-043
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /docs/specs/AST-043-input-presentation/spec.md (FR1–FR3 tables)
+ * - /packages/core/src/DateInput/DateInput.tsx
+ * - /packages/core/src/DateTimeInput/DateTimeInput.tsx
+ * - /packages/core/src/TimeInput/TimeInput.tsx
+ */
+
+/** Picker-surface policy for date/time inputs (`spec:AST-043` FR1). */
+export type InputPresentation =
+ | 'text-input'
+ | 'popover'
+ | 'bottom-sheet'
+ | 'native'
+ | 'adaptive-bottom-sheet'
+ | 'adaptive-native';
+
+/** `presentation` for components without a text-only surface: all except `TimeInput` exclude `text-input` (AST-043). */
+export type PickerPresentation = Exclude<InputPresentation, 'text-input'>;
+
+/** The surface a resolved `InputPresentation` actually renders. */
+export type InputPresentationSurface =
+ 'text-input' | 'desktop' | 'sheet' | 'native';
+
+/** The surface a resolved `PickerPresentation` renders: one where a picker opens. */
+export type PickerPresentationSurface = Exclude<
+ InputPresentationSurface,
+ 'text-input'
+>;
+
+/** Deprecated picker policy (`spec:AST-043` FR3). */
+export type LegacyNativePicker = 'touch' | 'always' | 'never';
+
+/**
+ * Typed as the narrower policy because the default opens a picker for every
+ * component; it is still a valid `InputPresentation`.
+ */
+export const DEFAULT_INPUT_PRESENTATION: PickerPresentation = 'adaptive-native';
+
+/**
+ * Map a deprecated `nativePicker` value to its `presentation` equivalent for
+ * a component whose every surface opens a picker (`DateInput`,
+ * `DateTimeInput`). Their released `never` was Astryx's own pickers on every
+ * pointer, so no value maps to `text-input` — which is what lets the return
+ * type exclude it.
+ */
+export function pickerPresentationFromNativePicker(
+ nativePicker: LegacyNativePicker,
+): PickerPresentation {
+ switch (nativePicker) {
+ case 'touch':
+ return 'adaptive-native';
+ case 'always':
+ return 'native';
+ case 'never':
+ return 'adaptive-bottom-sheet';
+ }
+}
+
+/**
+ * Map a deprecated `nativePicker` value to its `presentation` equivalent.
+ * `TimeInput` differs: its released `never` is the typed field on every
+ * pointer, so it maps to `text-input`, not a sheet policy.
+ */
+export function presentationFromNativePicker(
+ nativePicker: LegacyNativePicker,
+ component: 'date' | 'time',
+): InputPresentation {
+ if (component === 'time' && nativePicker === 'never') {
+ return 'text-input';
+ }
+ return pickerPresentationFromNativePicker(nativePicker);
+}
+
+/**
+ * The effective picker-only policy: explicit `presentation` wins over the
+ * deprecated prop. The narrow twin of {@link effectiveInputPresentation} for
+ * `DateInput` and `DateTimeInput`, whose `presentation` cannot be
+ * `text-input`.
+ */
+export function effectivePickerPresentation(
+ presentation: PickerPresentation | undefined,
+ nativePicker: LegacyNativePicker | undefined,
+): PickerPresentation {
+ if (presentation !== undefined) {
+ return presentation;
+ }
+ if (nativePicker !== undefined) {
+ return pickerPresentationFromNativePicker(nativePicker);
+ }
+ return DEFAULT_INPUT_PRESENTATION;
+}
+
+/** The effective policy: explicit `presentation` wins over the deprecated prop. */
+export function effectiveInputPresentation(
+ presentation: InputPresentation | undefined,
+ nativePicker: LegacyNativePicker | undefined,
+ component: 'date' | 'time',
+): InputPresentation {
+ if (presentation !== undefined) {
+ return presentation;
+ }
+ if (nativePicker !== undefined) {
+ return presentationFromNativePicker(nativePicker, component);
+ }
+ return DEFAULT_INPUT_PRESENTATION;
+}
+
+/** Resolve a picker-only policy to the surface rendered for the current pointer. */
+export function resolvePickerPresentation(
+ presentation: PickerPresentation,
+ isCoarsePointer: boolean,
+): PickerPresentationSurface {
+ switch (presentation) {
+ case 'popover':
+ return 'desktop';
+ case 'bottom-sheet':
+ return 'sheet';
+ case 'native':
+ return 'native';
+ case 'adaptive-bottom-sheet':
+ return isCoarsePointer ? 'sheet' : 'desktop';
+ case 'adaptive-native':
+ return isCoarsePointer ? 'native' : 'desktop';
+ }
+}
+
+/** Resolve a policy to the surface rendered for the current pointer. */
+export function resolveInputPresentation(
+ presentation: InputPresentation,
+ isCoarsePointer: boolean,
+): InputPresentationSurface {
+ return presentation === 'text-input'
+ ? 'text-input'
+ : resolvePickerPresentation(presentation, isCoarsePointer);
+}