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

package/src/Table/Table.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {act, render, screen} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {BaseTable} from './BaseTable';
 import {Table} from './Table';
@@ -837,22 +837,95 @@ describe('Table', () => {
     expect(screen.getAllByRole('row')).toHaveLength(4);
   });
 
-  it('wraps table in a scroll container', () => {
+  it('wraps the table in an observed scroll content box', () => {
     render(<Table data={users} columns={columns} />);
     const table = screen.getByRole('table');
-    const wrapper = table.parentElement;
+    const content = table.parentElement;
+    const wrapper = content?.parentElement;
+    expect(content).toHaveAttribute('data-scroll-content');
     expect(wrapper).toBeTruthy();
     expect(wrapper!.className).toContain('astryx-table-scroll-wrapper');
   });
 
-  it('makes the scroll container keyboard-focusable', () => {
+  it('keeps a fitting scroll container out of the keyboard order', () => {
     render(<Table data={users} columns={columns} />);
-    const table = screen.getByRole('table');
-    const wrapper = table.parentElement;
-    expect(wrapper).toBeTruthy();
-    expect(wrapper!).toHaveAttribute('tabindex', '0');
-    expect(wrapper!).toHaveAttribute('role', 'group');
-    expect(wrapper!).toHaveAttribute('aria-label', 'Table');
+    const wrapper = screen.getByRole('group', {name: 'Table'});
+    expect(wrapper).not.toHaveAttribute('tabindex');
+    expect(wrapper.style.overscrollBehaviorX).toBe('auto');
+  });
+
+  it('preserves scroll-wrapper HTML attributes from plugins', () => {
+    const plugin: TablePlugin<User> = {
+      transformScrollWrapper: props => ({
+        ...props,
+        htmlProps: {
+          ...props.htmlProps,
+          role: 'region',
+          'aria-label': 'Orders',
+          tabIndex: 2,
+        },
+      }),
+    };
+    render(<Table data={users} columns={columns} plugins={{custom: plugin}} />);
+    const wrapper = screen.getByRole('region', {name: 'Orders'});
+    expect(wrapper).toHaveAttribute('tabindex', '2');
+  });
+
+  it('contains overscroll only while the table scrolls', () => {
+    const frames: FrameRequestCallback[] = [];
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn((callback: FrameRequestCallback) => {
+        frames.push(callback);
+        return frames.length;
+      }),
+    );
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+
+    try {
+      render(<Table data={users} columns={columns} />);
+      const wrapper = screen.getByRole('group', {name: 'Table'});
+      Object.assign(wrapper.style, {overflowX: 'auto'});
+      for (const [key, value] of Object.entries({
+        clientWidth: 100,
+        clientHeight: 100,
+        scrollWidth: 180,
+        scrollHeight: 100,
+        scrollLeft: 0,
+        scrollTop: 0,
+      })) {
+        Object.defineProperty(wrapper, key, {
+          configurable: true,
+          value,
+          writable: true,
+        });
+      }
+
+      act(() => {
+        wrapper.dispatchEvent(new Event('scroll'));
+        frames.splice(0).forEach(callback => callback(performance.now()));
+      });
+
+      expect(wrapper).toHaveAttribute('tabindex', '0');
+      expect(wrapper).toHaveAttribute('data-scrollable-inline', 'true');
+      expect(wrapper.style.overscrollBehaviorX).toBe('contain');
+
+      Object.defineProperty(wrapper, 'scrollWidth', {
+        configurable: true,
+        value: 100,
+        writable: true,
+      });
+      act(() => {
+        wrapper.dispatchEvent(new Event('scroll'));
+        frames.splice(0).forEach(callback => callback(performance.now()));
+      });
+
+      expect(wrapper).not.toHaveAttribute('tabindex');
+      expect(wrapper).not.toHaveAttribute('data-scrollable-inline');
+      expect(wrapper.style.overscrollBehaviorX).toBe('auto');
+    } finally {
+      vi.unstubAllGlobals();
+    }
   });
 
   it('uses table-layout: auto in children mode', () => {

package/src/Table/Table.tsx

@@ -11,6 +11,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Table/Table.doc.mjs (props table, features, usage examples)
  * - /packages/core/src/Table/Table.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Table/__tests__/TableScroll.a11y.chromium.spec.ts (browser scroll behavior)
  * - /packages/core/src/Table/index.ts (exports if types change)
  * - /apps/storybook/stories/Table.stories.tsx (storybook stories)
  * - /packages/cli/assets/templates/blocks/components/Table/ (showcase blocks)
@@ -22,6 +23,7 @@ import {colorVars} from '../theme/tokens.stylex';
 import {BaseTable} from './BaseTable';
 import {TableContext} from './TableContext';
 import {useBaseTablePlugins} from './useBaseTablePlugins';
+import {useScrollableArea} from '../hooks/useScrollableArea';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import type {
@@ -149,30 +151,36 @@ function TableScrollWrapper({
   afterTable?: React.ReactNode;
 }) {
   const t = useTranslator();
+  const label = t('@astryx.table.label');
+  const {getViewportProps, getContentProps, state} = useScrollableArea({
+    axis: 'inline',
+    keyboardAccess: {owner: 'content'},
+    overscroll: 'contain',
+  });
   const {ref, ...restHtmlProps} = htmlProps ?? {};
+  const viewportProps = getViewportProps<HTMLDivElement>({
+    role: 'group',
+    'aria-label': label,
+    ...(state.inline.isScrollable ? {tabIndex: 0} : {}),
+    ...restHtmlProps,
+    ref,
+    ...mergeProps(
+      themeProps('table-scroll-wrapper'),
+      stylex.props(
+        scrollWrapperStyles.base,
+        scrollWrapperStyles.containerBleed,
+        ...(pluginStyles ?? []),
+      ),
+    ),
+  });
+
   return (
-    <div
-      ref={ref}
-      // Keyboard-focusable so keyboard users can scroll a horizontally
-      // overflowing table. Uses role="group" (not "region") so multiple
-      // tables on a page don't create duplicate same-named landmarks
-      // (axe: landmark-unique). Callers may override role/aria-label via
-      // htmlProps.
-      tabIndex={0}
-      role="group"
-      aria-label={t('@astryx.table.label')}
-      {...restHtmlProps}
-      {...mergeProps(
-        themeProps('table-scroll-wrapper'),
-        stylex.props(
-          scrollWrapperStyles.base,
-          scrollWrapperStyles.containerBleed,
-          ...(pluginStyles ?? []),
-        ),
-      )}>
-      {beforeTable}
-      {children}
-      {afterTable}
+    <div {...viewportProps}>
+      <div {...getContentProps<HTMLDivElement>()}>
+        {beforeTable}
+        {children}
+        {afterTable}
+      </div>
     </div>
   );
 }

package/src/Table/__tests__/TableScroll.a11y.chromium.spec.ts

@@ -0,0 +1,137 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TableScroll.a11y.chromium.spec.ts
+ * @input Built responsive Table story and real Chromium wheel input
+ * @output Browser evidence for conditional inline containment and scroll chaining
+ * @position Table integration proof for the shared useScrollableArea behavior
+ */
+
+import {expect, test, type Locator, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+async function mount(page: Page) {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-table--responsive-scroll&viewMode=story`,
+  );
+  const wrappers = page.locator('.astryx-table-scroll-wrapper');
+  await expect(wrappers).toHaveCount(3);
+  return wrappers;
+}
+
+async function putInsideOuterScroller(
+  page: Page,
+  viewport: Locator,
+  viewportWidth: number,
+  contentWidth: number,
+  tableWidth: number,
+) {
+  await viewport.evaluate(
+    (node, sizes) => {
+      const outer = document.createElement('div');
+      outer.dataset.tableScrollOuter = '';
+      outer.style.inlineSize = `${sizes.viewportWidth}px`;
+      outer.style.overflowX = 'auto';
+      const content = document.createElement('div');
+      content.style.inlineSize = `${sizes.contentWidth}px`;
+      node.parentElement?.insertBefore(outer, node);
+      outer.append(content);
+      content.append(node);
+      (node as HTMLElement).style.inlineSize = `${sizes.tableWidth}px`;
+    },
+    {viewportWidth, contentWidth, tableWidth},
+  );
+  return page.locator('[data-table-scroll-outer]');
+}
+
+async function wheelInline(page: Page, target: Locator) {
+  const box = await target.boundingBox();
+  if (box == null) {
+    throw new Error('Table scroll viewport has no rendered bounds');
+  }
+  await page.mouse.move(box.x + Math.min(box.width / 2, 100), box.y + 20);
+  await page.mouse.wheel(200, 0);
+}
+
+test('an overflowing table contains horizontal wheel input at its edge', async ({
+  page,
+}) => {
+  const wrappers = await mount(page);
+  const tableViewport = wrappers.nth(0);
+  await tableViewport.locator('table').evaluate(table => {
+    const viewport = table.closest<HTMLElement>('.astryx-table-scroll-wrapper');
+    if (viewport != null) {
+      table.style.minWidth = `${viewport.clientWidth + 400}px`;
+    }
+  });
+  await expect(tableViewport).toHaveAttribute('data-scrollable-inline', 'true');
+  await expect(tableViewport).toHaveAttribute('tabindex', '0');
+  await expect
+    .poll(async () =>
+      tableViewport.evaluate(
+        element => getComputedStyle(element).overscrollBehaviorX,
+      ),
+    )
+    .toBe('contain');
+
+  const outer = await putInsideOuterScroller(
+    page,
+    tableViewport,
+    320,
+    800,
+    320,
+  );
+  await tableViewport.evaluate(element => {
+    element.scrollLeft = element.scrollWidth - element.clientWidth;
+  });
+  await wheelInline(page, tableViewport);
+  await expect
+    .poll(async () => outer.evaluate(element => element.scrollLeft))
+    .toBe(0);
+});
+
+test('a fitting table passes horizontal wheel input to its outer scroller', async ({
+  page,
+}) => {
+  const wrappers = await mount(page);
+  const tableViewport = wrappers.nth(2);
+  const outer = await putInsideOuterScroller(
+    page,
+    tableViewport,
+    320,
+    800,
+    800,
+  );
+
+  await expect(tableViewport).not.toHaveAttribute(
+    'data-scrollable-inline',
+    'true',
+  );
+  await expect(tableViewport).not.toHaveAttribute('tabindex');
+  await expect
+    .poll(async () =>
+      tableViewport.evaluate(
+        element => getComputedStyle(element).overscrollBehaviorX,
+      ),
+    )
+    .toBe('auto');
+
+  await wheelInline(page, tableViewport);
+  await expect
+    .poll(async () => outer.evaluate(element => element.scrollLeft))
+    .toBeGreaterThan(0);
+});

package/src/TextArea/TextArea.tsx

@@ -95,9 +95,14 @@ const styles = stylex.create({
     paddingBlock: spacingVars['--spacing-1'],
     paddingInline: 'var(--_textarea-inline-padding)',
     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/TextInput/TextInput.test.tsx

@@ -2,7 +2,8 @@
 
 /**
  * @file TextInput.test.tsx
- * @input Uses vitest, @testing-library/react, TextInput component
+ * @input Uses vitest, @testing-library/react, TextInput component, and the
+ *   shared declaredValue StyleX read-back helper
  * @output Unit tests for TextInput component behavior
  * @position Testing; validates TextInput.tsx implementation
  *
@@ -13,6 +14,7 @@ import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
+import {declaredValue} from '../__tests__/stylexDeclarations';
 import {InputGroup} from '../InputGroup';
 import {TextInput} from './TextInput';
 
@@ -1113,3 +1115,20 @@ describe('TextInput clear button focus behavior', () => {
     rafSpy.mockRestore();
   });
 });
+
+describe('TextInput text size', () => {
+  it('renders the theme body size outside the iOS zoom gate', () => {
+    // The 16px floor rides `@supports (-webkit-touch-callout: none)` inside
+    // `@media (pointer: coarse)` — iOS Safari is the browser that zooms on
+    // focus under 16px, so the floor targets it alone instead of every
+    // coarse pointer. jsdom's CSSOM drops at-rule-wrapped declarations it
+    // cannot parse, so the gate itself is pinned against the sources in
+    // inputFontFloor.test.ts; what this asserts is the visible result off
+    // the gate: the plain token size, not a floor.
+    render(<TextInput label="Name" value="" onChange={() => {}} />);
+    expect(declaredValue(screen.getByLabelText('Name'), 'font-size')).toBe(
+      'var(--text-body-size)',
+    );
+  });
+});
+

package/src/TextInput/TextInput.tsx

@@ -58,9 +58,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/TimeInput/NativeTimeInput.test.tsx

@@ -99,14 +99,47 @@ describe('TimeInput nativePicker', () => {
   it.each([
     ['seconds', {hasSeconds: true}],
     ['custom increment', {increment: 15}],
-  ] as const)('retains the typed field for %s', (_name, props) => {
-    stubPointer(true);
+  ] as const)(
+    'retains the typed field for %s under adaptive-native (default)',
+    (_name, props) => {
+      stubPointer(true);
+      render(<TimeInput label="Start time" onChange={() => {}} {...props} />);
+
+      expect(
+        screen.getByRole('textbox', {name: 'Start time'}),
+      ).toBeInTheDocument();
+      expect(document.querySelector('input[type="time"]')).toBeNull();
+    },
+  );
+
+  it.each([
+    ['seconds', {hasSeconds: true}],
+    ['custom increment', {increment: 15}],
+  ] as const)(
+    'forces the native field for %s under presentation="native" (FR2)',
+    (_name, props) => {
+      stubPointer(false);
+      render(
+        <TimeInput
+          label="Start time"
+          presentation="native"
+          onChange={() => {}}
+          {...props}
+        />,
+      );
+
+      expect(getNativeTimeInput()).toBeInTheDocument();
+    },
+  );
+
+  it('deprecated nativePicker="always" keeps released fallbacks (FR2 legacy)', () => {
+    stubPointer(false);
     render(
       <TimeInput
         label="Start time"
         nativePicker="always"
+        hasSeconds
         onChange={() => {}}
-        {...props}
       />,
     );
 

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

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