@astryxdesign/core 0.7.7-canary.550ff21 → 0.7.7-canary.58c5b8a

package/src/hooks/useAttachment.ts

@@ -4,16 +4,16 @@
 
 /**
  * @file useAttachment.ts
- * @input A node ref (an element's, or the document's), an attach function
+ * @input Node refs (an element's, or the document's), an attach function
  *   and a key
- * @output Exports useAttachment: keeps the attach function bound to the node
- *   the ref holds across commits
- * @position Internal React helper, not in hooks/index.ts: the one attach
- *   and release lifecycle of the gesture hooks (useGestureRecognizer,
- *   usePressTracker, useFingerScroll)
+ * @output Exports useAttachment and useAttachmentPair (two elements): they keep
+ *   the attach function bound to the nodes the refs hold across commits
+ * @position Internal React helper, not in hooks/index.ts: the one attach and
+ *   release lifecycle of the gesture hooks, the pager and useAnimator
  *
- * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx
- * and gestures/__tests__/useFingerScroll.test.tsx.
+ * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx,
+ * gestures/__tests__/useFingerScroll.test.tsx and
+ * __tests__/useAttachmentPair.test.tsx.
  */
 
 import {useRef, type RefObject} from 'react';
@@ -29,23 +29,65 @@ export function useAttachment<T extends Node = Element>(
   ref: RefObject<T | null>,
   attach: (element: T) => () => void,
   key: unknown,
+): void {
+  useAttachedNodes([ref], ([node]) => attach(node as T), key);
+}
+
+/**
+ * `useAttachment` for two elements. It keeps `attach` bound to the pair the
+ * refs hold after each commit, once both are there. Replacing either element
+ * releases the attachment and attaches the new pair. A changed `key`
+ * re-attaches, and the last attachment is released on unmount. A commit that
+ * changes neither does nothing.
+ */
+export function useAttachmentPair<A extends Element, B extends Element>(
+  firstRef: RefObject<A | null>,
+  secondRef: RefObject<B | null>,
+  attach: (first: A, second: B) => () => void,
+  key: unknown,
+): void {
+  useAttachedNodes(
+    [firstRef, secondRef],
+    ([first, second]) => attach(first as A, second as B),
+    key,
+  );
+}
+
+/**
+ * The lifecycle both share: one attachment of the nodes the refs hold. It is
+ * made once every node is there, and released when a node or `key` changes
+ * and at unmount.
+ */
+function useAttachedNodes(
+  refs: ReadonlyArray<RefObject<Node | null>>,
+  attach: (nodes: ReadonlyArray<Node>) => () => void,
+  key: unknown,
 ): void {
   const attachmentRef = useRef<{
-    element: T;
+    nodes: ReadonlyArray<Node>;
     key: unknown;
     release: () => void;
   } | null>(null);
 
-  // Syncs the attachment with the DOM node `ref` holds after this commit.
+  // Syncs the attachment with the DOM nodes the refs hold after this commit.
   useIsomorphicLayoutEffect(() => {
-    const element = ref.current;
+    const nodes = refs.map(ref => ref.current);
     const current = attachmentRef.current;
-    if (current?.element === element && current?.key === key) {
+    if (
+      current != null &&
+      current.key === key &&
+      nodes.every((node, index) => node === current.nodes[index])
+    ) {
       return;
     }
     current?.release();
-    attachmentRef.current =
-      element == null ? null : {element, key, release: attach(element)};
+    attachmentRef.current = nodes.every(node => node != null)
+      ? {
+          nodes: nodes,
+          key,
+          release: attach(nodes),
+        }
+      : null;
   });
 
   // Releases the attachment at unmount.

package/src/hooks/useFocusTrap.ts

@@ -228,7 +228,29 @@ export interface UseFocusTrapReturn<T extends HTMLElement = HTMLElement> {
 export function useFocusTrap<T extends HTMLElement = HTMLElement>(
   options: UseFocusTrapOptions,
 ): UseFocusTrapReturn<T> {
-  const {isActive, onEscape} = options;
+  return useFocusTrapInternal<T>(options);
+}
+
+/**
+ * Package-internal options. Not re-exported from the package entry point.
+ */
+interface InternalFocusTrapOptions extends UseFocusTrapOptions {
+  /**
+   * The element to restore focus to on deactivation, read at activation. For
+   * an overlay that may move focus inside before the trap activates (initial
+   * focus within the opening event), the element focused at activation is
+   * already inside, so the overlay names its opener instead. Returning `null`
+   * falls back to the element focused at activation.
+   */
+  getRestoreTarget?: () => HTMLElement | null;
+}
+
+export function useFocusTrapInternal<T extends HTMLElement = HTMLElement>(
+  options: InternalFocusTrapOptions,
+): UseFocusTrapReturn<T> {
+  const {isActive, onEscape, getRestoreTarget} = options;
+  const getRestoreTargetRef = useRef(getRestoreTarget);
+  getRestoreTargetRef.current = getRestoreTarget;
 
   const containerRef = useRef<T | null>(null);
   const lastFocusRef = useRef<Element | null>(null);
@@ -302,7 +324,9 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
     // Snapshot the container now; by cleanup it may be detached or unmounted.
     const container = containerRef.current;
     const doc = trapDocument(container);
-    const previouslyFocused = doc.activeElement as HTMLElement | null;
+    const previouslyFocused =
+      getRestoreTargetRef.current?.() ??
+      (doc.activeElement as HTMLElement | null);
 
     // Whether focus ever entered the trap container while it was active.
     // Initialized from the current active element in case focus was already

package/src/hooks/useHighlightedOptionScroll.ts

@@ -8,7 +8,8 @@
  *   option-id resolver for the owning listbox
  * @output Exports useHighlightedOptionScroll: keeps the highlighted option
  *   scrolled into view for keyboard navigation while hover-driven highlights
- *   never scroll
+ *   never scroll, and a hover after a keyboard move waits for the pointer to
+ *   move or press; the hover callback is stable while `setHighlightedIndex` is
  * @position Internal hook; used by useCombobox, useMultiCombobox,
  *   BaseTypeahead, and DateTimeInput — the owners of combobox highlight state
  */
@@ -27,6 +28,21 @@ interface UseHighlightedOptionScrollOptions {
   itemCount?: number;
 }
 
+/**
+ * Highlights the hovered option at `index`. `onHighlight` runs when the hover
+ * takes effect: at once, or after the pointer moves or presses when a
+ * keyboard move holds the highlight.
+ */
+export type HighlightFromHover = (
+  index: number,
+  onHighlight?: () => void,
+) => void;
+
+interface WaitingHover {
+  index: number;
+  onHighlight?: () => void;
+}
+
 /**
  * Keep the highlighted option visible during keyboard navigation — but not for
  * hover highlights. Hover must highlight only: scrollIntoView moves the next
@@ -34,6 +50,10 @@ interface UseHighlightedOptionScrollOptions {
  * scrolls again — a runaway auto-scroll loop with no user input.
  * Keyboard paths call the raw setter directly and keep their scrolling; hover
  * paths call the returned callback.
+ *
+ * A keyboard move holds the highlight. A key that scrolls the list moves rows
+ * under a still mouse, and the browser reports the row under it as entered;
+ * that row takes the highlight only once the pointer moves or presses.
  */
 export function useHighlightedOptionScroll({
   isOpen,
@@ -41,31 +61,119 @@ export function useHighlightedOptionScroll({
   setHighlightedIndex,
   getOptionId,
   itemCount,
-}: UseHighlightedOptionScrollOptions): (index: number) => void {
-  const hoverHighlightRef = useRef(false);
+}: UseHighlightedOptionScrollOptions): HighlightFromHover {
+  // The callback reads no render state, so memoized rows keep one function.
+  const hoveredIndexRef = useRef<number | null>(null);
+  const shownIndexRef = useRef(highlightedIndex);
+  // The hover that came while a keyboard move held the highlight.
+  const waitingHoverRef = useRef<WaitingHover | null>(null);
+  // Set only while a keyboard move holds the highlight.
+  const removeHoldListenersRef = useRef<(() => void) | null>(null);
+  const setHighlightedIndexRef = useRef(setHighlightedIndex);
+  // The pointer's last screen position a hold saw, kept across holds.
+  const lastPointerRef = useRef<{x: number; y: number} | null>(null);
+
+  const applyHover = useCallback((hover: WaitingHover) => {
+    hoveredIndexRef.current = hover.index;
+    setHighlightedIndexRef.current(hover.index);
+    hover.onHighlight?.();
+  }, []);
+
+  const endHold = useCallback(() => {
+    removeHoldListenersRef.current?.();
+    removeHoldListenersRef.current = null;
+  }, []);
+
+  const releaseHold = useCallback(() => {
+    endHold();
+    const waiting = waitingHoverRef.current;
+    waitingHoverRef.current = null;
+    if (waiting != null) {
+      applyHover(waiting);
+    }
+  }, [applyHover, endHold]);
+
+  // Holds the highlight until the pointer moves or presses. The listeners
+  // live only while the hold does. Movement is read by screen coordinates: a
+  // scroll moves the rows, not the pointer. The browser reports a row as
+  // entered before the move that reaches it, so the first real move gives
+  // that row the highlight. A press releases at once, so a held press lights
+  // the pressed row.
+  const startHold = useCallback(() => {
+    waitingHoverRef.current = null;
+    if (removeHoldListenersRef.current != null) {
+      return;
+    }
+    const onPointerMove = (event: PointerEvent) => {
+      const last = lastPointerRef.current;
+      lastPointerRef.current = {x: event.screenX, y: event.screenY};
+      if (
+        last != null &&
+        last.x === event.screenX &&
+        last.y === event.screenY
+      ) {
+        return;
+      }
+      releaseHold();
+    };
+    const options = {capture: true, passive: true} as const;
+    document.addEventListener('pointermove', onPointerMove, options);
+    document.addEventListener('pointerdown', releaseHold, options);
+    removeHoldListenersRef.current = () => {
+      document.removeEventListener('pointermove', onPointerMove, options);
+      document.removeEventListener('pointerdown', releaseHold, options);
+    };
+  }, [releaseHold]);
 
-  const highlightFromHover = useCallback(
-    (index: number) => {
-      if (index !== highlightedIndex) {
-        hoverHighlightRef.current = true;
+  const highlightFromHover = useCallback<HighlightFromHover>(
+    (index, onHighlight) => {
+      if (removeHoldListenersRef.current != null) {
+        waitingHoverRef.current = {index, onHighlight};
+        return;
       }
+      hoveredIndexRef.current = index;
       setHighlightedIndex(index);
+      onHighlight?.();
     },
-    [highlightedIndex, setHighlightedIndex],
+    [setHighlightedIndex],
   );
 
+  // Effect: keeps the hold's document listeners calling the current setter.
+  useEffect(() => {
+    setHighlightedIndexRef.current = setHighlightedIndex;
+  }, [setHighlightedIndex]);
+
+  // Effect: removes the hold's document listeners on unmount.
+  useEffect(() => endHold, [endHold]);
+
+  // Effect: scrolls the highlighted option into view in the document, and
+  // starts or ends the hold on its document listeners.
   useEffect(() => {
-    if (hoverHighlightRef.current) {
-      hoverHighlightRef.current = false;
+    // Only a move to the hovered row came from the hover. A hover on the row
+    // already highlighted changes nothing, so a later run for the same row
+    // (a new list) still scrolls it into view.
+    const hasMoved = shownIndexRef.current !== highlightedIndex;
+    shownIndexRef.current = highlightedIndex;
+    const isFromHover =
+      hasMoved && hoveredIndexRef.current === highlightedIndex;
+    hoveredIndexRef.current = null;
+    if (isFromHover) {
       return;
     }
-    if (!isOpen || highlightedIndex < 0) {
+    // A cleared highlight, a closed list, or a list that is not shown (a
+    // closed CommandPalette reports itself as open) has nothing to hold.
+    const option =
+      isOpen && highlightedIndex >= 0
+        ? document.getElementById(getOptionId(highlightedIndex))
+        : null;
+    if (option == null) {
+      waitingHoverRef.current = null;
+      endHold();
       return;
     }
-    document
-      .getElementById(getOptionId(highlightedIndex))
-      ?.scrollIntoView?.({block: 'nearest'});
-  }, [isOpen, highlightedIndex, getOptionId, itemCount]);
+    startHold();
+    option.scrollIntoView?.({block: 'nearest'});
+  }, [isOpen, highlightedIndex, getOptionId, itemCount, endHold, startHold]);
 
   return highlightFromHover;
 }

package/src/hooks/useInputStatusIcon.tsx

@@ -15,9 +15,10 @@
 import {useCallback, useEffect, useState} from 'react';
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Icon, type IconName, type IconSize} from '../Icon';
+import {Icon, type IconSize} from '../Icon/Icon';
+import type {IconName} from '../Icon/globalIconRegistry';
 import type {InputStatus, InputStatusType} from '../Field/types';
-import {useTooltip} from '../Tooltip';
+import {useTooltip} from '../Tooltip/useTooltip';
 import {radiusVars} from '../theme/tokens.stylex';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';

package/src/hooks/useMediaQuery.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
     },
   ],
   usage: {
-    description: 'SSR-safe media query hook that subscribes to window.matchMedia changes. Returns whether the given media query matches. Always returns false on first render for SSR compatibility.',
+    description: 'SSR-safe media query hook that subscribes to window.matchMedia changes. Returns whether the given media query matches. Always returns false on first render for SSR compatibility. Where `window.matchMedia` is missing, it returns its server default and never throws.',
     bestPractices: [
       { guidance: true, description: 'Use for responsive layout switching based on viewport width, color scheme, or motion preferences.' },
       { guidance: true, description: 'Prefer Astryx responsive tokens and component props over manual breakpoint logic when possible.' },
@@ -44,7 +44,7 @@ export const docsDense = {
     matches: 'whether media query currently matches. Always false on first render (SSR-safe).',
   },
   usage: {
-    description: 'SSR-safe media query hook subscribing to window.matchMedia changes. Returns whether given media query matches. Always returns false on first render for SSR compatibility.',
+    description: 'SSR-safe media query hook subscribing to window.matchMedia changes. Returns whether given media query matches. Always returns false on first render for SSR compatibility. Where `window.matchMedia` is missing, returns its server default and never throws.',
     bestPractices: [
       { guidance: true, description: 'Use for responsive layout switching based on viewport width, color scheme, or motion preferences.' },
       { guidance: true, description: 'Prefer Astryx responsive tokens + component props over manual breakpoint logic when possible.' },

package/src/hooks/useMediaQuery.ts

@@ -20,7 +20,8 @@ import {useCallback, useSyncExternalStore} from 'react';
 
 /**
  * SSR-safe media query hook.
- * Returns whether the given media query matches.
+ * Returns whether the given media query matches. Where the window has no
+ * `matchMedia`, as in a test DOM, it returns `serverDefault`.
  *
  * @param query - CSS media query string
  * @param serverDefault - Value to return during SSR. Pass a server-side hint
@@ -35,6 +36,10 @@ import {useCallback, useSyncExternalStore} from 'react';
 export function useMediaQuery(query: string, serverDefault = false): boolean {
   const subscribe = useCallback(
     (onStoreChange: () => void) => {
+      // A DOM without `matchMedia`, such as a test DOM, has nothing to watch.
+      if (typeof window.matchMedia !== 'function') {
+        return () => {};
+      }
       const mql = window.matchMedia(query);
       mql.addEventListener('change', onStoreChange);
       return () => mql.removeEventListener('change', onStoreChange);
@@ -42,9 +47,13 @@ export function useMediaQuery(query: string, serverDefault = false): boolean {
     [query],
   );
 
-  const getSnapshot = useCallback(() => {
-    return window.matchMedia(query).matches;
-  }, [query]);
+  const getSnapshot = useCallback(
+    () =>
+      typeof window.matchMedia === 'function'
+        ? window.matchMedia(query).matches
+        : serverDefault,
+    [query, serverDefault],
+  );
 
   const getServerSnapshot = useCallback(() => serverDefault, [serverDefault]);
 

package/src/hooks/useMenuPress.ts

@@ -483,7 +483,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
           // Detach before acting: the activation usually closes the menu.
           endGesture();
           // Once armed, the one swallower stays installed.
-          armClickGuard(doc, {staysInstalled: true});
+          armClickGuard(doc, {
+            staysInstalled: true,
+            cancelsTouchEnd: native?.pointerType === 'touch',
+          });
           if (native != null) {
             activate(effect.row, native);
           }
@@ -492,7 +495,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
         case 'settle': {
           endGesture();
           if (effect.stray) {
-            armClickGuard(doc, {staysInstalled: true});
+            armClickGuard(doc, {
+              staysInstalled: true,
+              cancelsTouchEnd: native?.pointerType === 'touch',
+            });
           }
           if (effect.dismiss) {
             optionsRef.current.onDismiss?.();