@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/MobileNav/MobileNav.doc.mjs

@@ -98,7 +98,7 @@ export const docs = {
           name: 'onOpenChange',
           type: '(isOpen: boolean) => void',
           description:
-            'Called when the drawer visibility changes (backdrop click, Escape key, or close button). Inside AppShell, this is managed automatically via context.',
+            'Called when the drawer visibility changes (backdrop click, Escape key, or close button). Inside AppShell, this is managed automatically via context. On a phone or tablet (a coarse primary pointer), the drawer takes no tap or drag while it slides in; keys and assistive technology still act. After a close, focus returns to the element that opened it once its dialog closes.',
         },
         {
           name: 'children',
@@ -203,7 +203,7 @@ export const docsZh = {
       name: 'onOpenChange',
       type: '(isOpen: boolean) => void',
       description:
-        '当抽屉可见性变化时调用（点击背景遮罩、按 Escape 键或点击关闭按钮）。',
+        '当抽屉可见性变化时调用（点击背景遮罩、按 Escape 键或点击关闭按钮）。在手机或平板上（主指针为粗指针时），抽屉滑入期间不接受点按或拖动；键盘和辅助技术仍可操作。关闭后，焦点会在对话框关闭时回到打开它的元素。',
       required: true,
     },
     {
@@ -311,7 +311,7 @@ export const docsDense = {
   propDescriptions: {
     isOpen: 'whether drawer is open',
     onOpenChange:
-      'called when drawer visibility changes (backdrop click, Escape, close button)',
+      'called when drawer visibility changes (backdrop click, Escape, close button); under a coarse primary pointer the drawer takes no tap or drag while it slides in (keys still act)',
     children:
       'drawer content; typically SideNavSection/SideNavItem or any ReactNode',
     header:

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/MultiSelector/MultiSelector.tsx

@@ -79,6 +79,7 @@ import {joinAriaIDs} from '../utils/inputAria';
 import {withholdCallerHandlers} from '../utils/disabledInteraction';
 import {devWarn, warnOnce} from '../utils/devWarning';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
+import {useKeyboardHighlight} from '../hooks/useKeyboardHighlight';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {FOCUSABLE_SELECTOR} from '../hooks/focusableSelector';
 import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
@@ -1851,23 +1852,12 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     ),
   });
 
-  const [isKeyboardHighlight, setIsKeyboardHighlight] = useState(
-    () => readModality() === 'keyboard',
-  );
-  const onKeyDown = useCallback(
-    (event: React.KeyboardEvent<HTMLElement>) => {
-      onComboboxKeyDown(event);
-      setIsKeyboardHighlight(readModality() === 'keyboard');
-    },
-    [onComboboxKeyDown, readModality],
-  );
-  const onItemMouseEnter = useCallback(
-    (...args: Parameters<typeof onComboboxItemMouseEnter>) => {
-      onComboboxItemMouseEnter(...args);
-      setIsKeyboardHighlight(readModality() === 'keyboard');
-    },
-    [onComboboxItemMouseEnter, readModality],
-  );
+  const {isKeyboardHighlight, onKeyDown, onItemMouseEnter} =
+    useKeyboardHighlight(
+      readModality,
+      onComboboxKeyDown,
+      onComboboxItemMouseEnter,
+    );
 
   // The trigger button owns its click so a consumer `onClick`, which lands on
   // the button, composes after the built-in toggle. A press elsewhere in the

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/OverflowList/OverflowList.tsx

@@ -31,7 +31,7 @@ import {isRenderable} from '../utils/isRenderable';
 import type {SpacingStep} from '../utils/types';
 import * as stylex from '@stylexjs/stylex';
 import {mergeProps} from '../utils';
-import {useOverflow} from '../hooks/useOverflow';
+import {useOverflowInternal} from '../hooks/useOverflow';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {spacingVars} from '../theme/tokens.stylex';
 import {themeProps} from '../utils/themeProps';
@@ -284,15 +284,21 @@ export function OverflowList({
   const observeParent = behavior === 'observeParent';
   const isMultiRow = maxRows != null && maxRows > 1;
 
+  // Only the multi-row path renders from `rowHeight` (it caps the
+  // container's height), so only that path tracks it.
   const {containerRef, measureRef, visibleCount, hasOverflow, rowHeight} =
-    useOverflow(itemCount, {
-      gap: gapPx,
-      minVisibleItems,
-      maxVisibleItems,
-      maxRows,
-      collapseFrom,
-      behavior,
-    });
+    useOverflowInternal(
+      itemCount,
+      {
+        gap: gapPx,
+        minVisibleItems,
+        maxVisibleItems,
+        maxRows,
+        collapseFrom,
+        behavior,
+      },
+      {tracksRows: isMultiRow},
+    );
 
   const allItems: OverflowItem[] = childArray.map((child, index) => ({
     child,

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.',
     },
     {
       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 秒数。',
     },
     {
       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.',
     handleRef:
       'Imperative handle w/ focusTypeahead() + blurTypeahead() methods.',
     endContent: