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.mdnew file mode 100644index 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.++@imdreamrunnerdiff --git a/apps/storybook/stories/DateInput.stories.tsx b/apps/storybook/stories/DateInput.stories.tsxindex 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.tsxindex 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.tsxindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.tsxindex 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.tsxindex 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}hasCleardiff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjsindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsindex 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.mjsindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsindex 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.tsxindex 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(<TimeInputlabel="Start time"nativePicker="always"+ hasSecondsonChange={() => {}}- {...props}/>,);diff --git a/packages/core/src/TimeInput/Presentation.test.tsx b/packages/core/src/TimeInput/Presentation.test.tsxnew file mode 100644index 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.mjsindex 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.tsxindex 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 convenienceexport 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.tsxnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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);+}