@astryxdesign/core 0.6.2 → 0.6.3-canary.039a67e

package/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: {
@@ -99,9 +105,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],
@@ -159,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'
@@ -399,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;
 }
 
 /**
@@ -943,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';

package/src/DateInput/NativeDateField.tsx

@@ -100,10 +100,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
-    // Below 16px iOS zooms the page when the field takes focus.
+    // Below 16px iOS zooms the page when the field takes focus. Only iOS
+    // WebKit implements -webkit-touch-callout, so the coarse-pointer floor is
+    // keyed to iOS alone.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],
@@ -112,11 +116,20 @@ const styles = stylex.create({
     // A date control's intrinsic height comes from its inner edit fields, not
     // from `line-height`, so it renders ~2px taller than a text input and its
     // value sits off the shared baseline inside the same flex row. One line
-    // box is exactly what the text field occupies.
-    height: stylex.firstThatWorks(
-      '1lh',
-      `calc(max(1rem, ${typeScaleVars['--text-body-size']}) * ${typeScaleVars['--text-body-leading']})`,
-    ),
+    // box is exactly what the text field occupies. The calc fallback mirrors
+    // the iOS-only floor above; browsers with `1lh` track it for free.
+    height: {
+      default: stylex.firstThatWorks(
+        '1lh',
+        `calc(${typeScaleVars['--text-body-size']} * ${typeScaleVars['--text-body-leading']})`,
+      ),
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': stylex.firstThatWorks(
+          '1lh',
+          `calc(max(1rem, ${typeScaleVars['--text-body-size']}) * ${typeScaleVars['--text-body-leading']})`,
+        ),
+      },
+    },
     // iOS gives date controls their own button-like chrome, with inner
     // spacing and a centred value that no reset of ours can reach.
     WebkitAppearance: 'none',
@@ -187,9 +200,12 @@ const styles = stylex.create({
     // covers — one line of that leading fills its height exactly, which puts
     // the glyphs on the input's own baseline.
     display: 'block',
+    // ...with the input's own iOS floor, so the two baselines stay shared.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     // A tap has to reach the control underneath — that is what raises the

package/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',
+    );
+  });
+});

package/src/DateInput/TouchDateField.tsx

@@ -194,10 +194,14 @@ const styles = stylex.create({
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
     // Below 16px iOS zooms the page on focus. The field is focusable even
-    // though it is not typable, so it needs the same floor DateInput has.
+    // though it is not typable, so it needs the same floor DateInput has —
+    // keyed to iOS alone, since only iOS WebKit implements
+    // -webkit-touch-callout.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/src/DateInput/index.ts

@@ -15,6 +15,7 @@ export type {
   DateInputSize,
   DateInputFormat,
   DateInputNativePicker,
+  DateInputPresentation,
   DateInputStatus,
   DateInputStatusType,
 } from './DateInput';

package/src/DateRangeInput/DateRangeInput.tsx

@@ -92,9 +92,14 @@ const styles = stylex.create({
     borderStyle: 'none',
     padding: 0,
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-body-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-body-size']})`,
+      },
     },
     lineHeight: typeScaleVars['--text-body-leading'],
     color: colorVars['--color-text-primary'],

package/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',
   },
 };