@astryxdesign/core 0.7.8 → 0.7.9-canary.07992bb

package/src/MobileNav/MobileNav.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file MobileNav.tsx
- * @input Uses React, useEffect, useRef, useCallback, ReactNode, StyleX
+ * @input Uses React, useEffect, useRef, useCallback, ReactNode, StyleX and
+ *   the Layer module's entrance hold
  * @output Exports MobileNav component and MobileNavProps
  * @position Core implementation; consumed by index.ts
  *
@@ -38,6 +39,7 @@
  * - /packages/core/src/MobileNav/index.ts (exports if types change)
  * - /packages/core/src/Layer/useLayerDismissal.ts (dismissal stack)
  * - /packages/core/src/hooks/useScrollLock.ts (the page's scroll lock)
+ * - /packages/core/src/MobileNav/MobileNavTouchPresentation.test.tsx (touch)
  * - /packages/cli/assets/templates/blocks/components/MobileNav/ (showcase blocks)
  */
 
@@ -63,6 +65,7 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {Heading} from '../Heading/Heading';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
+import {holdEntranceInput} from '../Layer/holdEntranceInput';
 import {mergeProps, composeEventHandlers} from '../utils';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
 import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
@@ -77,6 +80,7 @@ import {themeProps} from '../utils/themeProps';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useScrollLock} from '../hooks/useScrollLock';
+import {useFocusRegionContainment} from '../hooks/useFocusTrap';
 import {
   registerEnglishFallback,
   useComponentTranslator,
@@ -282,6 +286,14 @@ const dynamicStyles = stylex.create({
  * own scheduled `dialog.close()` has a chance to run (#5701).
  */
 export const MAX_CLOSE_DELAY_MS = 250;
+/**
+ * Longest the drawer slides in or out for, in ms. Both run for the theme's
+ * `--duration-medium`: 410 ms by default, and at most 545 ms on the default
+ * scale (`--duration-medium-max`). The slide-out keeps playing after the
+ * dialog closes, while the dialog's `display` transition keeps it rendered.
+ * The touch hold on the slide-in ends by this time.
+ */
+export const MAX_EXIT_MS = 550;
 /** Fraction of the hold to close at, so the close never lands on its boundary. */
 const CLOSE_WITHIN_HOLD = 0.6;
 
@@ -504,7 +516,15 @@ export function MobileNav({
   );
 
   const dialogRef = useRef<HTMLDialogElement>(null);
+  // Native showModal() lets Tab leave for the browser's own UI, so the shared
+  // module wraps it. A closing drawer stops containing as soon as it starts to
+  // slide out.
+  useFocusRegionContainment(dialogRef, isOpen);
+  const drawerRef = useRef<HTMLDivElement>(null);
   const closeTimeoutRef = useRef<ReturnType<typeof setTimeout>>(null);
+  // The input hold on the drawer's layer while it slides in under a coarse
+  // primary pointer. It is null under a fine one and once the slide-in ends.
+  const releaseHoldRef = useRef<(() => void) | null>(null);
   // Element that was focused when the drawer opened; focus goes back to it
   // once the native dialog has closed (see closeAndRestoreFocus).
   const triggerElementRef = useRef<HTMLElement | null>(null);
@@ -569,6 +589,8 @@ export function MobileNav({
     }
 
     if (isOpen) {
+      releaseHoldRef.current?.();
+      releaseHoldRef.current = null;
       if (!dialog.open) {
         // Capture the opener before showModal() pulls focus into the top
         // layer. Only on the transition into open: a reopen while the delayed
@@ -578,7 +600,16 @@ export function MobileNav({
           document.activeElement as HTMLElement | null;
         dialog.showModal();
       }
+      // Under a coarse primary pointer, nothing takes a touch until the
+      // slide-in ends, at most MAX_EXIT_MS in. A close holds nothing, because
+      // only an entrance is held. Under a fine one, nothing is held.
+      releaseHoldRef.current = holdEntranceInput(dialog, {
+        entrance: drawerRef.current,
+        capMs: MAX_EXIT_MS,
+      });
     } else if (dialog.open) {
+      releaseHoldRef.current?.();
+      releaseHoldRef.current = null;
       closeTimeoutRef.current = setTimeout(() => {
         closeAndRestoreFocus(dialog, triggerElementRef);
         setIsCloseHeld(false);
@@ -594,6 +625,10 @@ export function MobileNav({
         clearTimeout(closeTimeoutRef.current);
         closeTimeoutRef.current = null;
       }
+      // The hold this run took ends with it: a reopen, a close or an
+      // unmount mid-slide never leaves input blocked.
+      releaseHoldRef.current?.();
+      releaseHoldRef.current = null;
     };
   }, [isOpen]);
 
@@ -613,6 +648,8 @@ export function MobileNav({
   useEffect(() => {
     const dialog = dialogRef.current;
     return () => {
+      releaseHoldRef.current?.();
+      releaseHoldRef.current = null;
       if (dialog?.open) {
         closeAndRestoreFocus(dialog, triggerElementRef);
       }
@@ -704,6 +741,7 @@ export function MobileNav({
           <LayerContentBoundary>
             {/* Drawer panel — tabIndex so showModal() focuses the drawer, not the close button */}
             <div
+              ref={drawerRef}
               tabIndex={-1}
               {...stylex.props(
                 styles.drawer,

package/src/MoreMenu/MoreMenu.doc.mjs

@@ -104,8 +104,7 @@ export const docs = {
     {
       name: 'presentation',
       type: "'popover' | 'bottom-sheet' | 'adaptive'",
-      description: 'Presentation policy forwarded to DropdownMenu. `adaptive` keeps the anchored popover on pointer-based layouts and uses a BottomSheet on a compact touch screen: a coarse primary pointer, and a viewport narrower than the theme `md` breakpoint (768px by default) or shorter than 500px.',
-      default: "'popover'",
+      description: 'Presentation policy forwarded to DropdownMenu. `adaptive` keeps the anchored popover on pointer-based layouts and uses a BottomSheet on a compact touch screen: a coarse primary pointer, and a viewport narrower than the theme `md` breakpoint (768px by default) or shorter than 500px. Omitted, the menu is the anchored popover, and under a finger, on every device, the finger that opened it picks a row only after moving 10 px. Pass \'popover\' to keep the pointer behavior on every device, the settle rule included.',
     },
     {
       name: 'onOpenChange',
@@ -204,8 +203,7 @@ export const docsZh = {
     {
       name: 'presentation',
       type: "'popover' | 'bottom-sheet' | 'adaptive'",
-      description: '菜单呈现策略。`adaptive` 在指针布局中使用锚定浮层，在主指针为粗略指针且视口宽度小于主题的 `md` 断点（默认 768px）或高度小于 500px 时使用 BottomSheet。',
-      default: "'popover'",
+      description: '菜单呈现策略。`adaptive` 在指针布局中使用锚定浮层，在主指针为粗略指针且视口宽度小于主题的 `md` 断点（默认 768px）或高度小于 500px 时使用 BottomSheet。省略时，菜单为锚定浮层；在任何设备上用手指操作时，打开菜单的手指移动 10 px 后才会选择菜单项。传入 \'popover\' 可在所有设备上保持指针行为，包括稳定规则。',
     },
     {
       name: 'xstyle',

package/src/MoreMenu/MoreMenu.tsx

@@ -97,9 +97,11 @@ export interface MoreMenuProps extends Pick<
   alignment?: LayerAlignment;
 
   /**
-   * Menu presentation policy. `adaptive` uses a BottomSheet on compact
-   * coarse-pointer viewports and an anchored popover elsewhere.
-   * @default 'popover'
+   * Menu presentation policy, forwarded to DropdownMenu. `adaptive` uses a
+   * BottomSheet on compact coarse-pointer viewports and an anchored popover
+   * elsewhere. Omitted, the menu is the anchored popover, and the finger that
+   * opened it follows UIMenu's handoff on every device. `'popover'` pins the
+   * pointer behavior on every device.
    */
   presentation?: DropdownMenuPresentation;
 

package/src/NumberInput/NumberInput.doc.mjs

@@ -160,7 +160,7 @@ export const docs = {
       name: 'hasNumberSteppers',
       type: 'boolean',
       description:
-        'Shows increment and decrement buttons at the end of the input on fine pointers. Hidden on coarse pointers (such as touch screens); text entry and keyboard stepping remain available.',
+        'Shows increment and decrement buttons at the end of the input on fine pointers. Hidden on coarse pointers (such as touch screens); text entry and keyboard stepping remain available. Holding a button with a mouse or a pen repeats the step and commits once, when the hold ends.',
       default: 'false',
     },
     {

package/src/NumberInput/NumberInput.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file NumberInput.tsx
- * @input Uses React, useId, useState, useMemo, useCallback, Field, Icon, InputGroupContext
- * @output Exports NumberInput component, NumberInputProps; optional steppers are hidden on coarse pointers
+ * @input Uses React, useId, useState, useMemo, useCallback, useEffect, Field, Icon, InputGroupContext
+ * @output Exports NumberInput component, NumberInputProps; optional steppers are hidden on coarse pointers, and a held one repeats into the draft
  * @position Core implementation; consumed by index.ts, tested by NumberInput.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -24,9 +24,12 @@ import {
   useState,
   useMemo,
   useCallback,
+  useEffect,
   useRef,
   type FocusEvent,
   type KeyboardEvent,
+  type MouseEvent,
+  type PointerEvent,
   type ReactNode,
 } from 'react';
 import {flushSync} from 'react-dom';
@@ -56,6 +59,7 @@ import {joinAriaIDs} from '../utils/inputAria';
 import {withholdCallerHandlers} from '../utils/disabledInteraction';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
+import {lockSelection, locksSelectionFor} from '../utils/selectionLock';
 import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
@@ -403,6 +407,8 @@ interface NumberInputPropsBase extends Omit<
   /**
    * Whether to show increment and decrement buttons at the end of the input.
    * The buttons are hidden on coarse pointers (such as touch screens).
+   * Holding a button with a mouse or a pen repeats the step and commits once,
+   * when the hold ends.
    * Direct text entry and keyboard stepping remain available.
    * @default false
    */
@@ -460,6 +466,32 @@ export type NumberInputProps =
 
 type StepDirection = -1 | 1;
 
+/**
+ * A held stepper's timing: the first repeat comes `delayMs` after the press.
+ * Each later interval is `acceleration` times the one before, from
+ * `firstIntervalMs` down to `minIntervalMs`.
+ */
+const STEPPER_HOLD = {
+  delayMs: 500,
+  firstIntervalMs: 250,
+  acceleration: 0.9,
+  minIntervalMs: 50,
+} as const;
+
+/**
+ * A held stepper press: its pointer, its next repeat, the value its repeats
+ * reached, whether the field stopped taking them, and the release of its
+ * selection lock.
+ */
+type StepperHold = {
+  pointerId: number;
+  timer: ReturnType<typeof setTimeout> | null;
+  held: number | null;
+  intervalMs: number;
+  isFrozen: boolean;
+  unlockSelection: (() => void) | null;
+};
+
 function getDecimalPlaces(value: number): number {
   const [coefficient, exponentText] = String(value).toLowerCase().split('e');
   const fractionLength = coefficient.split('.')[1]?.length ?? 0;
@@ -625,6 +657,13 @@ export function NumberInput({
 
   // Pending input while user is typing (null = show formatted value)
   const [pendingInput, setPendingInput] = useState<string | null>(null);
+  // The value a held stepper's repeats reached, shown until the hold ends.
+  const [holdDraft, setHoldDraft] = useState<number | null>(null);
+  // A field that turns disabled or read-only drops the held value during
+  // render, so no commit shows a value that the release does not commit.
+  if (holdDraft !== null && (isDisabled || isReadOnly)) {
+    setHoldDraft(null);
+  }
   const [isFocused, setIsFocused] = useState(false);
 
   // Disabled-reason tooltip. The tooltip listeners attach to the input container (which already exists) and
@@ -689,6 +728,9 @@ export function NumberInput({
   // Preserve pending text while editing. Otherwise show the formatted value
   // at rest and the raw numeric value while focused so it remains editable.
   const displayValue = useMemo(() => {
+    if (holdDraft !== null) {
+      return formatEditableNumber(holdDraft, locale);
+    }
     if (pendingInput !== null) {
       return pendingInput;
     }
@@ -696,15 +738,19 @@ export function NumberInput({
       return '';
     }
     return isFocused ? formatEditableNumber(value, locale) : formattedValue;
-  }, [formattedValue, isFocused, locale, pendingInput, value]);
+  }, [formattedValue, holdDraft, isFocused, locale, pendingInput, value]);
 
   // Check if current pending input is valid (for styling purposes)
   const isInputValid = useMemo(() => {
+    // A held value is a step on the grid, so it is always valid.
+    if (holdDraft !== null) {
+      return true;
+    }
     if (pendingInput === null || !pendingInput.trim()) {
       return true;
     }
     return parseInput(pendingInput) !== null;
-  }, [pendingInput, parseInput]);
+  }, [holdDraft, pendingInput, parseInput]);
 
   // Keep the whole text edit as a draft until an explicit commit boundary.
   const handleInputChange = useCallback(
@@ -850,6 +896,167 @@ export function NumberInput({
     [getNextValue, isDisabled, isReadOnly, onChange, value],
   );
 
+  // A held stepper repeats into its own draft and commits once, when the hold
+  // ends.
+  const stepperHoldRef = useRef<StepperHold | null>(null);
+  const isClickAfterHoldRef = useRef(false);
+  // The pointer of a repeated hold that another press cancelled. Its own
+  // release still swallows the click that follows.
+  const cancelledHoldPointerRef = useRef<number | null>(null);
+
+  // Ends a hold with no commit, and drops the draft its repeats wrote.
+  const cancelStepperHold = useCallback(() => {
+    const hold = stepperHoldRef.current;
+    if (hold == null) {
+      return;
+    }
+    stepperHoldRef.current = null;
+    cancelledHoldPointerRef.current = hold.held != null ? hold.pointerId : null;
+    if (hold.timer != null) {
+      clearTimeout(hold.timer);
+    }
+    hold.unlockSelection?.();
+    setHoldDraft(null);
+  }, []);
+
+  // Syncs the held stepper's repeat timer with the field's editability: a
+  // field that turns disabled or read-only stops the repeats, and the release
+  // commits nothing.
+  useEffect(() => {
+    const hold = stepperHoldRef.current;
+    if (hold == null || !(isDisabled || isReadOnly)) {
+      return;
+    }
+    hold.isFrozen = true;
+    if (hold.timer != null) {
+      clearTimeout(hold.timer);
+      hold.timer = null;
+    }
+  }, [isDisabled, isReadOnly]);
+
+  // The stepper column's removal or unmount ends the hold with no commit, as
+  // its buttons can no longer hear the release.
+  const stepperColumnRef = useCallback(
+    () => () => {
+      cancelStepperHold();
+    },
+    [cancelStepperHold],
+  );
+
+  const startStepperHold = (
+    direction: StepDirection,
+    canStep: boolean,
+    event: PointerEvent<HTMLButtonElement>,
+  ) => {
+    isClickAfterHoldRef.current = false;
+    if (cancelledHoldPointerRef.current === event.pointerId) {
+      cancelledHoldPointerRef.current = null;
+    }
+    // Any new press ends a running hold, whichever pointer made it.
+    cancelStepperHold();
+    // Steppers render only under a non-coarse primary pointer, so a hold is a
+    // mouse or pen press. A finger keeps the single step of its click.
+    if (
+      event.button !== 0 ||
+      event.pointerType === 'touch' ||
+      !canStep ||
+      isDisabled ||
+      isReadOnly
+    ) {
+      return;
+    }
+    const first = getNextValue(direction);
+    if (first == null) {
+      return;
+    }
+    // The release ends the hold wherever the pointer is by then.
+    event.currentTarget.setPointerCapture?.(event.pointerId);
+    const grid = {direction, min, max, step, isIntegerOnly};
+    const hold: StepperHold = {
+      pointerId: event.pointerId,
+      timer: null,
+      held: null,
+      intervalMs: STEPPER_HOLD.firstIntervalMs,
+      isFrozen: false,
+      // A pen's hold starts no text selection or callout.
+      unlockSelection: locksSelectionFor(event.pointerType)
+        ? lockSelection([event.currentTarget], event.target)
+        : null,
+    };
+    const repeat = () => {
+      const next =
+        hold.held == null
+          ? first
+          : getSteppedValue({currentValue: hold.held, ...grid});
+      // At a bound the repeats stop, and the release still commits.
+      if (next == null || next === hold.held) {
+        hold.timer = null;
+        return;
+      }
+      hold.held = next;
+      setHoldDraft(next);
+      hold.timer = setTimeout(repeat, hold.intervalMs);
+      hold.intervalMs = Math.max(
+        STEPPER_HOLD.minIntervalMs,
+        hold.intervalMs * STEPPER_HOLD.acceleration,
+      );
+    };
+    hold.timer = setTimeout(repeat, STEPPER_HOLD.delayMs);
+    stepperHoldRef.current = hold;
+  };
+
+  const handleStepperContextMenu = (event: MouseEvent<HTMLButtonElement>) => {
+    const hold = stepperHoldRef.current;
+    if (hold == null) {
+      return;
+    }
+    // A pen's hold opens no callout menu. A mouse's context request, such as
+    // a Control-click, ends its hold with no commit and opens the menu.
+    if (hold.unlockSelection != null) {
+      event.preventDefault();
+      return;
+    }
+    cancelStepperHold();
+    // A click that follows the menu steps nothing, as after any ended hold.
+    cancelledHoldPointerRef.current = hold.pointerId;
+    isClickAfterHoldRef.current = true;
+  };
+
+  const endStepperHold = (end: 'release' | 'cancel', pointerId: number) => {
+    const hold = stepperHoldRef.current;
+    // Only the pointer that holds can end the hold.
+    if (hold == null || hold.pointerId !== pointerId) {
+      if (cancelledHoldPointerRef.current === pointerId) {
+        cancelledHoldPointerRef.current = null;
+        // Only arm the swallow here: a lost capture must not clear it.
+        if (end === 'release') {
+          isClickAfterHoldRef.current = true;
+        }
+      }
+      return;
+    }
+    stepperHoldRef.current = null;
+    if (hold.timer != null) {
+      clearTimeout(hold.timer);
+    }
+    hold.unlockSelection?.();
+    // A press released before its first repeat is a click, and its click
+    // steps.
+    if (hold.held == null) {
+      return;
+    }
+    isClickAfterHoldRef.current = end === 'release';
+    setHoldDraft(null);
+    // A frozen hold commits nothing, so a typed draft under it stays.
+    if (hold.isFrozen || isDisabled || isReadOnly) {
+      return;
+    }
+    setPendingInput(null);
+    if (hold.held !== value) {
+      onChange(hold.held);
+    }
+  };
+
   // Handle keyboard events
   const handleKeyDown = useCallback(
     (e: KeyboardEvent<HTMLInputElement>) => {
@@ -927,8 +1134,15 @@ export function NumberInput({
     [ref, wheelListenerRef],
   );
 
-  const canIncrement = getNextValue(1) !== valueForStepping;
-  const canDecrement = getNextValue(-1) !== valueForStepping;
+  // While a hold runs, the steppers follow the value that it shows.
+  const {canIncrement, canDecrement} = useMemo(() => {
+    const base = holdDraft ?? valueForStepping;
+    const grid = {currentValue: base, min, max, step, isIntegerOnly};
+    return {
+      canIncrement: getSteppedValue({...grid, direction: 1}) !== base,
+      canDecrement: getSteppedValue({...grid, direction: -1}) !== base,
+    };
+  }, [holdDraft, isIntegerOnly, max, min, step, valueForStepping]);
 
   // Handle clear button click
   const handleClear = useCallback(
@@ -1069,7 +1283,7 @@ export function NumberInput({
       )}
       {statusIcon}
       {hasNumberSteppers && (
-        <div {...stylex.props(styles.numberSteppers)}>
+        <div ref={stepperColumnRef} {...stylex.props(styles.numberSteppers)}>
           <button
             type="button"
             tabIndex={-1}
@@ -1078,8 +1292,25 @@ export function NumberInput({
               isDisabled || isReadOnly || !canIncrement || undefined
             }
             aria-label={t('@astryx.numberInput.incrementLabel', {label})}
-            onPointerDown={event => event.preventDefault()}
-            onClick={() => {
+            onPointerDown={event => {
+              event.preventDefault();
+              startStepperHold(1, canIncrement, event);
+            }}
+            onContextMenu={handleStepperContextMenu}
+            onPointerUp={event => endStepperHold('release', event.pointerId)}
+            onPointerCancel={event => endStepperHold('cancel', event.pointerId)}
+            onLostPointerCapture={event =>
+              endStepperHold('cancel', event.pointerId)
+            }
+            onClick={event => {
+              const isAfterHold = isClickAfterHoldRef.current;
+              isClickAfterHoldRef.current = false;
+              // A pointer's click after a held press's release steps nothing.
+              // A click with no pointer, such as a screen reader's, steps.
+              if (isAfterHold && event.detail > 0) {
+                inputRef.current?.focus();
+                return;
+              }
               // An aria-disabled stepper does nothing, as a natively disabled
               // one did (spec:AST-085 FR2).
               if (isDisabled || isReadOnly || !canIncrement) {
@@ -1109,8 +1340,25 @@ export function NumberInput({
               isDisabled || isReadOnly || !canDecrement || undefined
             }
             aria-label={t('@astryx.numberInput.decrementLabel', {label})}
-            onPointerDown={event => event.preventDefault()}
-            onClick={() => {
+            onPointerDown={event => {
+              event.preventDefault();
+              startStepperHold(-1, canDecrement, event);
+            }}
+            onContextMenu={handleStepperContextMenu}
+            onPointerUp={event => endStepperHold('release', event.pointerId)}
+            onPointerCancel={event => endStepperHold('cancel', event.pointerId)}
+            onLostPointerCapture={event =>
+              endStepperHold('cancel', event.pointerId)
+            }
+            onClick={event => {
+              const isAfterHold = isClickAfterHoldRef.current;
+              isClickAfterHoldRef.current = false;
+              // A pointer's click after a held press's release steps nothing.
+              // A click with no pointer, such as a screen reader's, steps.
+              if (isAfterHold && event.detail > 0) {
+                inputRef.current?.focus();
+                return;
+              }
               // An aria-disabled stepper does nothing, as a natively disabled
               // one did (spec:AST-085 FR2).
               if (isDisabled || isReadOnly || !canDecrement) {

package/src/Popover/usePopover.tsx

@@ -298,6 +298,7 @@ export interface UsePopoverReturn {
   /**
    * The CSS anchor name to use for positioning.
    * Use when you need to set anchorName manually (e.g., display:contents wrapper).
+   * Set it only while the layer is shown or its exit animation runs.
    */
   anchorId: string;
 

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -142,7 +142,7 @@ export const docs = {
       name: 'timezoneID',
       type: 'string',
       description:
-        'IANA zone a date-only date_absolute value, and each absolute part of a date_range, is read and written in: the day shows, edits and stores (as that midnight) in it; unset, a day is its UTC day. A date_absolute with isDateOnly: false shows and edits its date and time in it; unset, in the viewer\'s zone. E.g. "America/New_York".',
+        'IANA zone a date-only date_absolute value, and each absolute part of a date_range, is read and written in: the day shows, edits and stores (as that midnight) in it; unset, a day is its UTC day. A date_absolute with isDateOnly: false shows and edits its date and time in it; unset, in the viewer\'s zone. E.g. "America/New_York". Date values are written in the InternationalizationProvider calendar, such as calendar="persian"; filter values stay Unix seconds. The value editor, a DateInput or DateRangeInput, shows the calendar that input resolves, which is Gregorian.',
     },
     {
       name: 'handleRef',
@@ -450,7 +450,7 @@ export const docsZh = {
       name: 'timezoneID',
       type: 'string',
       description:
-        '仅日期的 date_absolute 值及 date_range 的每个绝对端点读写所用的 IANA 时区：该日在此时区显示、编辑并以其午夜存储；未设置时为 UTC 日。isDateOnly: false 的 date_absolute 值在此时区显示并编辑其日期和时间；未设置时为查看者所在时区。例如 "America/New_York"。',
+        '仅日期的 date_absolute 值及 date_range 的每个绝对端点读写所用的 IANA 时区：该日在此时区显示、编辑并以其午夜存储；未设置时为 UTC 日。isDateOnly: false 的 date_absolute 值在此时区显示并编辑其日期和时间；未设置时为查看者所在时区。例如 "America/New_York"。日期值使用 InternationalizationProvider 的历法（如 calendar="persian"）显示；筛选值仍为 Unix 秒数。值编辑器（DateInput 或 DateRangeInput）显示该输入框解析的历法，即公历。',
     },
     {
       name: 'handleRef',
@@ -572,7 +572,7 @@ export const docsDense = {
     menuWidth: 'Main field/search menu width in pixels.',
     popoverSaveButtonLabel: 'Label for save button in edit popover.',
     timezoneID:
-      'IANA zone a date-only value reads and writes in; unset, its UTC day.',
+      'IANA zone a date-only value reads and writes in; unset, its UTC day. Dates show in the provider calendar; their editor shows Gregorian dates.',
     handleRef:
       'Imperative handle w/ focusTypeahead() + blurTypeahead() methods.',
     endContent:

package/src/PowerSearch/PowerSearch.tsx

@@ -86,6 +86,7 @@ import {
 import {resolveOperatorLabel} from './resolveOperatorLabel';
 import {themeProps} from '../utils/themeProps';
 import {useLocale} from '../i18n/useLocale';
+import {useCalendarSystem} from '../i18n/useCalendarSystem';
 import type {Locale} from '../i18n/types';
 import type {SearchableItem} from '../Typeahead/types';
 import type {
@@ -242,6 +243,15 @@ const sheetTriggerStyles = stylex.create({
     },
     outline: 'none',
   },
+  // A placeholder longer than the trigger ends in an ellipsis inside it, as
+  // Selector's value does. It never runs under the result count or past the
+  // field's border.
+  placeholder: {
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+  },
   // Once a token is present the empty trigger covers the token lane instead
   // of reserving 40px or wrapping onto an otherwise blank row.
   triggerWithTokens: {
@@ -590,6 +600,7 @@ export function PowerSearch({
   const searchSource = usePowerSearchSource(config, maxSearchResults);
   const t = useComponentTranslator();
   const locale = useLocale();
+  const calendar = useCalendarSystem(undefined, 'PowerSearch');
   const label = labelFromProps ?? t('@astryx.powersearch.label');
   const placeholder =
     placeholderFromProps ?? t('@astryx.powersearch.placeholder');
@@ -714,6 +725,7 @@ export function PowerSearch({
               10,
             ),
             locale,
+            calendar,
             undefined,
             undefined,
             timezoneID,
@@ -721,7 +733,7 @@ export function PowerSearch({
         : null;
       return {label, value, full: value != null ? `${label} ${value}` : label};
     },
-    [config, maxTokenLength, t, locale, timezoneID],
+    [config, maxTokenLength, t, locale, timezoneID, calendar],
   );
   // The built-in token being edited. A token from a `components` override
   // names itself, so its editor keeps the plain popover.
@@ -872,6 +884,7 @@ export function PowerSearch({
             t,
             locale,
             timezoneID,
+            calendar,
           )
         : '';
 
@@ -890,7 +903,7 @@ export function PowerSearch({
         },
       };
     });
-  }, [filters, config, maxTokenLength, timezoneID, t, locale]);
+  }, [filters, config, maxTokenLength, timezoneID, t, locale, calendar]);
 
   // Handle tokenizer onChange (field selected from typeahead)
   const handleTokenizerChange = useCallback(
@@ -1544,7 +1557,11 @@ export function PowerSearch({
                   sheetTriggerStyles.trigger,
                   filters.length > 0 && sheetTriggerStyles.triggerWithTokens,
                 )}>
-                {filters.length === 0 ? placeholder : null}
+                {filters.length === 0 ? (
+                  <span {...stylex.props(sheetTriggerStyles.placeholder)}>
+                    {placeholder}
+                  </span>
+                ) : null}
               </button>
             </div>
             {(endContent || isRenderable(resultCountText)) && (

package/src/PowerSearch/PowerSearchBottomSheet.tsx

@@ -76,6 +76,7 @@ import {useAnnounce, type AnnounceFn} from '../hooks/useAnnounce';
 import type {TranslatorFn} from '../i18n';
 import {useListFormatter} from '../i18n/useListFormatter';
 import {useLocale} from '../i18n/useLocale';
+import {useCalendarSystem} from '../i18n/useCalendarSystem';
 import {SheetConfirmation} from '../internal/SheetConfirmation';
 import {useDismissSearchOnTouchDrag} from '../internal/useDismissSearchOnTouchDrag';
 import {
@@ -968,6 +969,7 @@ export function PowerSearchBottomSheet({
   const {NestedEditor} = editors;
   const t = useComponentTranslator();
   const locale = useLocale();
+  const calendar = useCalendarSystem(undefined, 'PowerSearch');
   const formatList = useListFormatter();
   const isInteractive = !isDisabled && !isReadOnly;
 
@@ -1524,13 +1526,14 @@ export function PowerSearchBottomSheet({
               filter.value,
               Number.MAX_SAFE_INTEGER,
               locale,
+              calendar,
               t,
               formatList,
               timezoneID,
             );
       return {label, value};
     },
-    [config, editors, formatList, locale, t, timezoneID],
+    [calendar, config, editors, formatList, locale, t, timezoneID],
   );
   const describeFilter = useCallback(
     (filter: PowerSearchFilter): string => {