@astryxdesign/core 0.7.5 → 0.7.6-canary.0ef60dd

package/src/DateInput/MonthScrollerSettle.test.tsx

@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {act, render} from '@testing-library/react';
+import {createRef} from 'react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {MonthScroller, type MonthScrollerHandle} from './MonthScroller';
+import {SCROLL_QUIET_MS} from './useScrollSettle';
+
+class FakeResizeObserver {
+  constructor(private callback: ResizeObserverCallback) {}
+  observe() {
+    this.callback([], this);
+  }
+  unobserve() {}
+  disconnect() {}
+}
+
+const PANE = 300;
+
+/**
+ * The month scroller's settle, with the browser's scrolling played by hand:
+ * `scrollTo` is recorded, and the offset is whatever the test sets.
+ */
+describe('MonthScroller settle', () => {
+  const scrollTo = vi.fn();
+  beforeEach(() => {
+    vi.useFakeTimers({
+      toFake: [
+        'setTimeout',
+        'clearTimeout',
+        'requestAnimationFrame',
+        'cancelAnimationFrame',
+        'Date',
+        'performance',
+      ],
+    });
+    vi.stubGlobal('ResizeObserver', FakeResizeObserver);
+    vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockReturnValue(PANE);
+    vi.spyOn(HTMLElement.prototype, 'clientHeight', 'get').mockReturnValue(
+      PANE,
+    );
+    Element.prototype.scrollTo = scrollTo;
+    scrollTo.mockClear();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  function renderScroller() {
+    const handleRef = createRef<MonthScrollerHandle>();
+    const view = render(
+      <MonthScroller
+        handleRef={handleRef}
+        minMonthIndex={0}
+        maxMonthIndex={23}
+        initialMonthIndex={9}
+        onVisibleMonthChange={() => {}}
+        selectedDate={null}
+        today={{year: 2026, month: 10, day: 15}}
+        isDateDisabled={() => false}
+        weekStartsOn={0}
+        onSelect={() => {}}
+      />,
+    );
+    const scroller = view.container.querySelector<HTMLElement>(
+      '[data-scroller="months"]',
+    );
+    if (scroller == null) {
+      throw new Error('no month scroller');
+    }
+    scrollTo.mockClear();
+    return {handleRef, scroller};
+  }
+
+  /** The browser moving the scroller to `left`, as a scroll event reports. */
+  /**
+   * A touch event carrying the lists a real one always has: jsdom has no
+   * constructible TouchEvent, and the gesture hook reads `touches[0]`.
+   */
+  function touchEvent(type: 'touchstart' | 'touchend') {
+    const event = new Event(type, {bubbles: true});
+    const point = {identifier: 1, clientX: 100, clientY: 100};
+    Object.defineProperties(event, {
+      touches: {value: type === 'touchend' ? [] : [point]},
+      targetTouches: {value: type === 'touchend' ? [] : [point]},
+      changedTouches: {value: [point]},
+    });
+    return event;
+  }
+
+  function scrollBy(scroller: HTMLElement, left: number) {
+    scroller.scrollLeft = left;
+    scroller.dispatchEvent(new Event('scroll'));
+  }
+
+  it('turns scroll snapping back on after re-centers that end on the month they began on', () => {
+    const {handleRef, scroller} = renderScroller();
+    // Two far jumps in one batch, out and back: each re-centers the mounted
+    // months, pausing scroll snapping, and the second puts the center back
+    // where it was, so the render that follows changes no center.
+    act(() => {
+      handleRef.current?.scrollToMonth(20);
+      handleRef.current?.scrollToMonth(9);
+    });
+    act(() => {
+      vi.advanceTimersByTime(50);
+    });
+    expect(scroller.style.scrollSnapType).toBe('');
+  });
+
+  it('leaves snapping on for a re-center while a finger drives the scroll', () => {
+    const {scroller} = renderScroller();
+    // A finger drags the next month in: the scroller crosses the middle of
+    // October's pane and re-centers its months with the finger still down.
+    act(() => {
+      scroller.dispatchEvent(touchEvent('touchstart'));
+    });
+    act(() => scrollBy(scroller, 9 * PANE + 0.6 * PANE));
+    act(() => {
+      vi.advanceTimersByTime(16);
+    });
+    // Snapping stays on: iOS tracks a snap target for the gesture.
+    expect(scroller.style.scrollSnapType).toBe('');
+  });
+
+  it('pauses snapping for a re-center again once the finger’s scroll has come to rest', () => {
+    const {handleRef, scroller} = renderScroller();
+    act(() => {
+      scroller.dispatchEvent(touchEvent('touchstart'));
+      scroller.dispatchEvent(touchEvent('touchend'));
+    });
+    act(() => {
+      vi.advanceTimersByTime(SCROLL_QUIET_MS + 50);
+    });
+    // An arrow's far jump after the swipe re-centers with snapping paused.
+    act(() => handleRef.current?.scrollToMonth(20));
+    expect(scroller.style.scrollSnapType).toBe('none');
+    act(() => {
+      vi.advanceTimersByTime(50);
+    });
+    expect(scroller.style.scrollSnapType).toBe('');
+  });
+
+  it('finishes a steer the browser cut short instead of rounding it back', () => {
+    const {handleRef, scroller} = renderScroller();
+    // An arrow toward month 10, its scroll 95 % of the way there.
+    act(() => handleRef.current?.scrollToMonth(10));
+    act(() => scrollBy(scroller, 9 * PANE + 0.95 * PANE));
+    // The other arrow, late in that scroll: back toward month 9.
+    act(() => handleRef.current?.scrollToMonth(9));
+    scrollTo.mockClear();
+    // WebKit ends the retargeted scroll where the first one's time ran out,
+    // near month 10, and the scroller goes quiet there.
+    act(() => scrollBy(scroller, 9 * PANE + 0.95 * PANE));
+    act(() => {
+      vi.advanceTimersByTime(SCROLL_QUIET_MS + 50);
+    });
+    // The settle finishes the steer onto month 9, not the nearest pane (10).
+    expect(
+      scrollTo.mock.calls.map(([options]) => (options as ScrollToOptions).left),
+    ).toEqual([9 * PANE]);
+  });
+});

package/src/DateInput/TouchDateField.tsx

@@ -772,7 +772,7 @@ export function TouchDateField({
 
   const fireChange = useCallback(
     (newValue: ISODateString | undefined) => {
-      if (isBusy) {
+      if (isEffectivelyDisabled) {
         return;
       }
       onChange?.(newValue);
@@ -783,7 +783,13 @@ export function TouchDateField({
         });
       }
     },
-    [isBusy, onChange, changeAction, startTransition, setOptimisticValue],
+    [
+      isEffectivelyDisabled,
+      onChange,
+      changeAction,
+      startTransition,
+      setOptimisticValue,
+    ],
   );
 
   const openSheet = useCallback(() => {
@@ -841,6 +847,11 @@ export function TouchDateField({
    * value is still cleared either way — that half never depends on the range.
    */
   const handleResetInSheet = useCallback(() => {
+    // Disabled: reject the entire reset without closing or moving focus.
+    // Busy-only fields keep month navigation; fireChange blocks the clear.
+    if (isDisabled) {
+      return;
+    }
     fireChange(undefined);
     const currentMonth = monthIndexOf(today);
     if (currentMonth < minMonthIndex || currentMonth > maxMonthIndex) {
@@ -851,7 +862,7 @@ export function TouchDateField({
     }
     setMonthIndex(currentMonth);
     scrollerHandleRef.current?.scrollToMonth(currentMonth, 'smooth');
-  }, [fireChange, today, monthIndex, minMonthIndex, maxMonthIndex]);
+  }, [isDisabled, fireChange, today, monthIndex, minMonthIndex, maxMonthIndex]);
 
   // Selection commits on the tap and leaves the sheet up, so a mistake can be
   // corrected in place and a nearby date reconsidered without reopening.

package/src/DateInput/__tests__/MonthScrollerSteps.interaction.browser.spec.ts

@@ -0,0 +1,312 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MonthScrollerSteps.interaction.browser.spec.ts
+ * @input The built "Default" DateInput story, shown in a bottom sheet, the
+ *   arrows clicked from the page, real mouse and trackpad input and the
+ *   interaction harness
+ * @output Interaction proofs for the month scroller's steps: after the month
+ *   and year wheels close, a trackpad scroll still pages to the next month and
+ *   Reset from four months on still rests on today's month; an arrow step
+ *   through a stalled frame moves exactly one month; under a finger, a swipe
+ *   that crosses the middle of a month as it lifts keeps scroll snapping on
+ *   and rests on the next month.
+ *   (A second arrow step late in the first one's scroll, which WebKit cuts
+ *   short, is proven in MonthScrollerSettle.test.tsx: a loaded page's frames
+ *   are too far apart to aim a click at a share of a 300 ms scroll.)
+ * @position Interaction tests of MonthScroller.tsx
+ *   (`*.interaction.browser.spec.ts`, run by `pnpm test:interaction`)
+ */
+
+import {expect, test, type Locator, type Page} from '@playwright/test';
+import {
+  blockMainThread,
+  drag,
+  openStory,
+  touchDriver,
+  withStorybook,
+} from '@astryxdesign/interaction-harness';
+
+const storybook = withStorybook(test);
+const STORY = 'core-dateinput--default';
+const ARGS = {presentation: 'bottom-sheet'};
+
+/** Waits until the scroller's offset has not moved for ten frames. */
+async function waitForRest(viewport: Locator): Promise<number> {
+  return viewport.evaluate(
+    async element =>
+      new Promise<number>(resolve => {
+        let last = element.scrollLeft;
+        let still = 0;
+        const check = () => {
+          const now = element.scrollLeft;
+          still = now === last ? still + 1 : 0;
+          last = now;
+          if (still >= 10) {
+            resolve(now);
+          } else {
+            requestAnimationFrame(check);
+          }
+        };
+        requestAnimationFrame(check);
+      }),
+  );
+}
+
+/** The month the scroller rests on, as the pane's own grid names it. */
+/**
+ * Waits until a month's grid sits flush with the scroller's edge, the offset
+ * unchanged, for ten frames: the end of the scroller's own settle
+ * correction, however long the page takes to run it. (The panes' width can
+ * be fractional, so the grid's own box is the measure, not the offset.)
+ */
+async function waitForRestOnMonth(viewport: Locator): Promise<number> {
+  return viewport.evaluate(
+    async element =>
+      new Promise<number>(resolve => {
+        let last = element.scrollLeft;
+        let still = 0;
+        const flush = () => {
+          const edge = element.getBoundingClientRect().left;
+          return [
+            ...element.querySelectorAll<HTMLElement>('[role="grid"]'),
+          ].some(
+            grid => Math.abs(grid.getBoundingClientRect().left - edge) < 1,
+          );
+        };
+        const check = () => {
+          const now = element.scrollLeft;
+          still = now === last && flush() ? still + 1 : 0;
+          last = now;
+          if (still >= 10) {
+            resolve(now);
+          } else {
+            requestAnimationFrame(check);
+          }
+        };
+        requestAnimationFrame(check);
+      }),
+  );
+}
+
+async function monthAtRest(viewport: Locator): Promise<string> {
+  return viewport.evaluate(element => {
+    const box = element.getBoundingClientRect();
+    const middle = box.left + box.width / 2;
+    for (const grid of element.querySelectorAll<HTMLElement>('[role="grid"]')) {
+      const r = grid.getBoundingClientRect();
+      if (r.left <= middle && r.right >= middle) {
+        return grid.getAttribute('aria-label') ?? '';
+      }
+    }
+    return '';
+  });
+}
+
+async function openCalendar(page: Page) {
+  await openStory(page, storybook(), STORY, ARGS);
+  await page
+    .getByRole('button', {name: /calendar/i})
+    .first()
+    .click();
+  const viewport = page.locator('[data-scroller="months"]');
+  await expect(viewport).toBeVisible();
+  await waitForRest(viewport);
+  return viewport;
+}
+
+test.use({hasTouch: false, isMobile: false});
+
+/**
+ * Waits until the scroller comes to rest, or until it has gone more than
+ * `limit` past `from`: a scroller that runs on by itself never rests, and
+ * the proof should fail where it ran, not at the test's timeout.
+ */
+async function waitForRestOrRun(
+  viewport: Locator,
+  from: number,
+  limit: number,
+): Promise<number> {
+  return viewport.evaluate(
+    async (element, {from, limit}) =>
+      new Promise<number>(resolve => {
+        let last = element.scrollLeft;
+        let still = 0;
+        const check = () => {
+          const now = element.scrollLeft;
+          still = now === last ? still + 1 : 0;
+          last = now;
+          if (still >= 10 || Math.abs(now - from) > limit) {
+            resolve(now);
+          } else {
+            requestAnimationFrame(check);
+          }
+        };
+        requestAnimationFrame(check);
+      }),
+    {from, limit},
+  );
+}
+
+/**
+ * A stalled frame right after an arrow (a 300 ms block of the main thread)
+ * let the re-center that follows the step land after the scroll had ended,
+ * and WebKit's re-snap after it then paged on by itself, a month every few
+ * frames. The step moves exactly one month.
+ */
+test('an arrow step through a stalled frame moves exactly one month', async ({
+  page,
+}) => {
+  const viewport = await openCalendar(page);
+  const title = page.getByRole('button', {name: /Choose month and year/});
+  const from = await viewport.evaluate(element => element.scrollLeft);
+  const width = await viewport.evaluate(element => element.clientWidth);
+  const box = await page
+    .getByRole('button', {name: 'Next month'})
+    .boundingBox();
+  if (box == null) {
+    throw new Error('no Next month button');
+  }
+  await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
+  await blockMainThread(page, 300);
+  const at = await waitForRestOrRun(viewport, from, 2 * width);
+  expect(Math.round((at - from) / width)).toBe(1);
+  await waitForRestOnMonth(viewport);
+  expect(
+    Math.round(((await viewport.evaluate(e => e.scrollLeft)) - from) / width),
+  ).toBe(1);
+  await expect(title).toHaveAccessibleName(
+    new RegExp(await monthAtRest(viewport)),
+  );
+});
+
+/**
+ * Closing the month and year wheels re-asserts the month shown, a steer that
+ * moves nothing. A trackpad scroll after it is the user's: it pages to the
+ * next month and stays there, the title following.
+ */
+test('after the month and year wheels close, a trackpad scroll to the next month stays there', async ({
+  page,
+}) => {
+  const viewport = await openCalendar(page);
+  const toggle = page.getByRole('button', {name: /Choose month and year/});
+  const start = await monthAtRest(viewport);
+  expect(start).not.toBe('');
+  const toggleBox = await toggle.boundingBox();
+  if (toggleBox == null) {
+    throw new Error('no month and year toggle');
+  }
+  const clickToggle = async () =>
+    page.mouse.click(
+      toggleBox.x + toggleBox.width / 2,
+      toggleBox.y + toggleBox.height / 2,
+    );
+  await clickToggle();
+  await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+  await clickToggle();
+  await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+  await waitForRest(viewport);
+
+  const box = await viewport.boundingBox();
+  if (box == null) {
+    throw new Error('no month scroller');
+  }
+  await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+  // A horizontal trackpad scroll of 70 % of a month, as one wheel event: a
+  // burst of small ones reaches a loaded page far enough apart to count as
+  // separate gestures, each snapping back on its own.
+  await page.mouse.wheel(box.width * 0.7, 0);
+  // Past the scroller's own settle correction too, which ends on a month's
+  // boundary.
+  await waitForRestOnMonth(viewport);
+  const next = await monthAtRest(viewport);
+  expect(next).not.toBe(start);
+  await expect(toggle).toHaveAccessibleName(new RegExp(next));
+});
+
+/**
+ * Reset from four months on is a far jump, mounting today's month before the
+ * scroller moves. After the month and year wheels close, whose re-assert is a
+ * steer that moved nothing, the jump still rests on today's month, the title
+ * with it.
+ */
+test('after the month and year wheels close, Reset from four months on rests on today’s month', async ({
+  page,
+}) => {
+  const viewport = await openCalendar(page);
+  const toggle = page.getByRole('button', {name: /Choose month and year/});
+  const today = await monthAtRest(viewport);
+  expect(today).not.toBe('');
+  const clickCentre = async (name: string | RegExp) => {
+    const box = await page.getByRole('button', {name}).boundingBox();
+    if (box == null) {
+      throw new Error(`no ${String(name)} button`);
+    }
+    await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
+  };
+  for (let step = 0; step < 4; step++) {
+    await clickCentre('Next month');
+    await waitForRest(viewport);
+  }
+  expect(await monthAtRest(viewport)).not.toBe(today);
+  await clickCentre(/Choose month and year/);
+  await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+  await clickCentre(/Choose month and year/);
+  await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+  await waitForRest(viewport);
+
+  await clickCentre('Reset');
+  // Past the scroller's own settle correction too, which ends on a month's
+  // boundary.
+  await waitForRestOnMonth(viewport);
+  expect(await monthAtRest(viewport)).toBe(today);
+  await expect(toggle).toHaveAccessibleName(new RegExp(today));
+});
+
+test.describe('under a finger', () => {
+  test.use({hasTouch: true, isMobile: true});
+
+  /**
+   * A swipe whose last move crosses the middle of the month makes the
+   * scroller re-center as the finger lifts. The finger drives that scroll, so
+   * the re-center leaves scroll snapping on (turning it off drops the snap
+   * target iOS tracks for the gesture, and the swipe coasted past the month),
+   * and the swipe comes to rest on the next month.
+   */
+  test('a swipe that crosses the middle of a month as it lifts keeps snapping on and rests on the next month', async ({
+    page,
+  }) => {
+    const viewport = await openCalendar(page);
+    const start = await monthAtRest(viewport);
+    const box = await viewport.boundingBox();
+    if (box == null) {
+      throw new Error('no month scroller');
+    }
+    // Every change of the scroller's inline scroll-snap-type from here on.
+    await viewport.evaluate(element => {
+      const changes: string[] = [];
+      (window as unknown as {snapChanges: string[]}).snapChanges = changes;
+      new MutationObserver(() => {
+        changes.push((element as HTMLElement).style.scrollSnapType || 'on');
+      }).observe(element, {attributes: true, attributeFilter: ['style']});
+    });
+    const driver = await touchDriver(page);
+    const y = box.y + box.height / 2;
+    const from = {x: box.x + box.width * 0.8, y};
+    // 55 % of a month toward the next one, the middle crossed by the last
+    // move, lifting a quarter frame after it.
+    await driver.play(
+      drag(from, {x: from.x - box.width * 0.55, y}, {durationMs: 300}),
+    );
+    await waitForRestOnMonth(viewport);
+    const rest = await monthAtRest(viewport);
+    expect(rest).not.toBe('');
+    expect(rest).not.toBe(start);
+    // Snapping was never turned off while the finger drove the scroll.
+    expect(
+      await page.evaluate(
+        () => (window as unknown as {snapChanges: string[]}).snapChanges,
+      ),
+    ).not.toContain('none');
+  });
+});

package/src/DateRangeInput/DateRangeInput.test.tsx

@@ -18,9 +18,9 @@ function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
   const {prose, component} = generateThemeCSS(theme);
   return [prose, component].filter(Boolean).join('\n\n');
 }
-// getButton/queryButton instead of getByRole('button', {name}): the closed
-// popover keeps a two-month Calendar (~85 role=button nodes) mounted, which
-// made every role+name query compute ~85 accessible names through jsdom's
+// getButton/queryButton instead of getByRole('button', {name}): the open
+// popover holds a two-month Calendar (~85 role=button nodes), which makes
+// every role+name query compute ~85 accessible names through jsdom's
 // slow getComputedStyle (~450ms per query). See fastRoleQueries.ts.
 import {getButton, queryButton} from '../__tests__/fastRoleQueries';
 import * as stylex from '@stylexjs/stylex';
@@ -767,6 +767,49 @@ describe('DateRangeInput', () => {
   });
 });
 
+describe('DateRangeInput calendar while the popover is closed', () => {
+  const calendarGrid = () => document.querySelector('[role="grid"]');
+
+  it('renders no calendar until the popover opens, and none after it closes', () => {
+    render(
+      <DateRangeInput
+        label="Range"
+        value={{start: '2026-01-05', end: '2026-01-09'}}
+        onChange={() => {}}
+      />,
+    );
+    const toggle = getButton('Open calendar');
+    expect(calendarGrid()).toBeNull();
+
+    fireEvent.click(toggle);
+    expect(calendarGrid()).not.toBeNull();
+
+    fireEvent.click(toggle);
+    expect(calendarGrid()).toBeNull();
+  });
+
+  it('moves focus into the popover on each open from the toggle', async () => {
+    render(
+      <DateRangeInput
+        label="Range"
+        value={{start: '2026-01-05', end: '2026-01-09'}}
+        onChange={() => {}}
+      />,
+    );
+    const toggle = getButton('Open calendar');
+
+    for (let i = 0; i < 2; i++) {
+      fireEvent.click(toggle);
+      // The first calendar control takes focus, not the dialog surface.
+      await waitFor(() => {
+        expect(getButton('Previous month')).toHaveFocus();
+      });
+      fireEvent.click(toggle);
+      expect(calendarGrid()).toBeNull();
+    }
+  });
+});
+
 describe('DateRangeInput statusVariant forwarding', () => {
   it('defaults to attached (status renders with data-variant="attached")', () => {
     const {container} = render(

package/src/DateRangeInput/DateRangeInput.tsx

@@ -851,18 +851,22 @@ export function DateRangeInput({
               })}
             </div>
           )}
-          <Calendar
-            mode="range"
-            value={optimisticValue}
-            onChange={handleRangeSelect}
-            min={min}
-            max={max}
-            dateConstraints={dateConstraints}
-            maxRangeSpan={maxRangeSpan}
-            minRangeSpan={minRangeSpan}
-            numberOfMonths={numberOfMonths}
-            weekStartsOn={weekStartsOn}
-          />
+          {/* The layer renders its children open or closed, so mount the
+              calendar only while it is open. */}
+          {popover.isOpen && (
+            <Calendar
+              mode="range"
+              value={optimisticValue}
+              onChange={handleRangeSelect}
+              min={min}
+              max={max}
+              dateConstraints={dateConstraints}
+              maxRangeSpan={maxRangeSpan}
+              minRangeSpan={minRangeSpan}
+              numberOfMonths={numberOfMonths}
+              weekStartsOn={weekStartsOn}
+            />
+          )}
         </div>,
         {placement: 'below', alignment: 'start'},
       )}

package/src/DateTimeInput/DateTimeInput.doc.mjs

@@ -115,8 +115,8 @@ export const docs = {
       name: 'hourFormat',
       type: "'12h' | '24h'",
       description:
-        "Hour display format. '12h' shows AM/PM; '24h' uses 24-hour notation.",
-      default: "'12h'",
+        "Hour display format. '12h' shows the locale's day period; '24h' uses 24-hour notation. When unset, follows the InternationalizationProvider locale's hour cycle (en-US 12-hour, en-GB 24-hour); a person's own preference rides on the locale tag (e.g. 'en-US-u-hc-h23').",
+      default: "the locale's hour cycle",
     },
     {
       name: 'timeIncrement',
@@ -270,7 +270,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          "Choose the hour format (12h or 24h) that matches your audience's locale.",
+          "Leave hourFormat unset so the field follows the InternationalizationProvider locale's hour cycle (12-hour in en-US, 24-hour in en-GB or de-DE). Set it only when the field itself needs a fixed format, and carry a person's own 12/24-hour preference on the provider locale (e.g. 'en-US-u-hc-h23') rather than on each field.",
       },
       {
         guidance: false,
@@ -393,7 +393,7 @@ export const docsZh = {
       {
         guidance: true,
         description:
-          "Choose the hour format (12h or 24h) that matches your audience's locale.",
+          "Leave hourFormat unset so the field follows the InternationalizationProvider locale's hour cycle (12-hour in en-US, 24-hour in en-GB or de-DE). Set it only when the field itself needs a fixed format, and carry a person's own 12/24-hour preference on the provider locale (e.g. 'en-US-u-hc-h23') rather than on each field.",
       },
       {
         guidance: false,
@@ -502,8 +502,9 @@ export const docsZh = {
     {
       name: 'hourFormat',
       type: "'12h' | '24h'",
-      description: "控制显示格式。'12h' 显示 AM/PM；'24h' 使用 24 小时制。",
-      default: "'12h'",
+      description:
+        "控制显示格式。'12h' 使用区域设置的上午/下午用语；'24h' 使用 24 小时制。未设置时遵循 InternationalizationProvider 区域设置的小时制（en-US 为 12 小时制，en-GB 为 24 小时制）；用户自己的偏好可通过区域标签传入（例如 'en-US-u-hc-h23'）。",
+      default: '区域设置的小时制',
     },
     {
       name: 'timeIncrement',
@@ -648,7 +649,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          "Choose the hour format (12h or 24h) that matches your audience's locale.",
+          "Leave hourFormat unset so the field follows the InternationalizationProvider locale's hour cycle (12-hour in en-US, 24-hour in en-GB or de-DE). Set it only when the field itself needs a fixed format, and carry a person's own 12/24-hour preference on the provider locale (e.g. 'en-US-u-hc-h23') rather than on each field.",
       },
       {
         guidance: false,
@@ -690,7 +691,8 @@ export const docsDense = {
     dateConstraints: 'custom constraint fns to disable specific dates',
     hasSeconds:
       'include seconds; retains Astryx time field because iOS native picker has no seconds wheel',
-    hourFormat: "display format. '12h' shows AM/PM; '24h' uses 24-hour",
+    hourFormat:
+      "display format. '12h' shows the locale's day period; '24h' uses 24-hour. Unset follows the provider locale's hour cycle (a -u-hc- tag carries a user preference)",
     timeIncrement:
       'minute step for Astryx typed field; non-default retains Astryx time field in native modes because iOS native step is validation-only',
     timeOptionInterval: