@astryxdesign/core 0.7.7-canary.4a8a76e → 0.7.7-canary.4e495ec

package/src/Tooltip/useTooltip.tsx

@@ -5,7 +5,8 @@
 /**
  * @file useTooltip.tsx
  * @input Uses useLayer, usePressPin, React hooks
- * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips
+ * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips,
+ *   and the module-only useTooltipWithTriggerBehavior that InfoTip's press-to-pin uses
  * @position Layer hook; builds on useLayer for tooltip behavior
  *
  * SYNC: When modified, update:
@@ -31,7 +32,7 @@ import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {registerLayerSurface} from '../Layer/layerSurfacePress';
-import {usePressPin} from '../Layer/usePressPin';
+import {usePressPin, type LayerTriggerBehavior} from '../Layer/usePressPin';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {themeProps} from '../utils/themeProps';
 import {
@@ -83,14 +84,6 @@ export type TooltipFocusTrigger = 'auto' | 'always' | 'never';
  */
 export type TooltipTouchTrigger = LayerTouchTrigger;
 
-/**
- * How the trigger opens the tooltip. `adaptive`, the default, previews it on
- * hover and focus, and a tap opens it unless the trigger acts. `hover`
- * previews it on hover and focus, and no touch or pen tap opens it. `toggle`
- * pins it on a click, tap, Enter, or Space on a button trigger.
- */
-export type TooltipTriggerBehavior = 'adaptive' | 'hover' | 'toggle';
-
 export interface TooltipOptions {
   /**
    * Position placement relative to anchor
@@ -135,32 +128,10 @@ export interface TooltipOptions {
    * - `tap`: tap always opens the tooltip, even on a trigger that acts
    * - `none`: touch never opens the tooltip
    *
-   * It decides only under `triggerBehavior="adaptive"`, the default.
-   *
    * @default 'auto'
    */
   touchTrigger?: TooltipTouchTrigger;
 
-  /**
-   * How the trigger opens the tooltip:
-   * - `adaptive` (the default): hover and focus preview it. A tap opens it
-   *   unless the trigger performs an action of its own. While `touchTrigger`
-   *   remains, it decides those taps.
-   * - `hover`: hover and focus preview it; no touch or pen tap opens it.
-   * - `toggle`: on a button trigger, a click, a tap, Enter, or Space pins the
-   *   tooltip open, and the same press closes it. Hover and keyboard focus
-   *   still preview it. A pinned tooltip stays until Escape, a second press,
-   *   a press outside, or focus leaving. Astryx clickable rows and cards
-   *   ignore the pinning press, except an Item row on a trigger that is not
-   *   a native button. The `Tooltip` component also stops it at a child
-   *   trigger. A hook caller stops a plain `onClick` ancestor itself. The
-   *   trigger reports `aria-expanded` and `aria-controls`, and the tooltip's
-   *   text is announced once when it pins. `touchTrigger` is ignored.
-   *
-   * @default 'adaptive'
-   */
-  triggerBehavior?: TooltipTriggerBehavior;
-
   /**
    * Whether the tooltip is enabled.
    * When false, hover/focus triggers are disabled.
@@ -296,6 +267,42 @@ function isFocusable(element: HTMLElement): boolean {
  */
 
 export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
+  // The option is fixed to `adaptive`, so an options object that carries it at
+  // runtime cannot reach the press-to-pin path.
+  return useTooltipWithTriggerBehavior({
+    ...options,
+    triggerBehavior: 'adaptive',
+  });
+}
+
+/**
+ * Module-only options for `useTooltipWithTriggerBehavior`. Not exported from
+ * the package.
+ */
+export interface TooltipWithTriggerBehaviorOptions extends TooltipOptions {
+  /**
+   * How the trigger opens the tooltip:
+   * - `adaptive` (the default): hover and focus preview it. `touchTrigger`
+   *   decides taps.
+   * - `toggle`: on a button trigger, a click, a tap, Enter, or Space pins the
+   *   tooltip open, and the same press closes it. Hover and keyboard focus
+   *   still preview it. A pinned tooltip stays until Escape, a second press,
+   *   a press outside, or focus leaving. The trigger reports `aria-expanded`
+   *   and `aria-controls`, and the tooltip's text is announced once when it
+   *   pins. `touchTrigger` is ignored. InfoTip uses it.
+   *
+   * @default 'adaptive'
+   */
+  triggerBehavior?: LayerTriggerBehavior;
+}
+
+/**
+ * `useTooltip` with a trigger behavior. Module-only: InfoTip's press-to-pin
+ * goes through it, and the package does not export it.
+ */
+export function useTooltipWithTriggerBehavior(
+  options: TooltipWithTriggerBehaviorOptions = {},
+): TooltipReturn {
   const {
     placement = 'above',
     alignment = 'center',

package/src/TopNav/TopNavItem.tsx

@@ -33,7 +33,7 @@ import type {LinkComponentType} from '../Link/types';
 import {useTopNavRenderMode} from './TopNavRenderContext';
 import {navItemStyles, type NavItemSize} from '../NavItem/navItemStyles.stylex';
 import {mergeProps} from '../utils';
-import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
+import {useCloseMobileDrawerOnActivate} from '../AppShell/useCloseMobileDrawerOnActivate';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
@@ -199,7 +199,9 @@ export function TopNavItem({
   const pressable = usePressFeedback();
   const LinkComponent = useLinkComponent(as);
   const renderMode = useTopNavRenderMode();
-  const {closeMobileNav} = useAppShellMobile();
+  const closeDrawerAfter = useCloseMobileDrawerOnActivate(
+    renderMode === 'drawer',
+  );
 
   // A disabled item renders as a plain <a> with no href: an href-less anchor
   // is not focusable and exposes no link affordance, so programmatic focus +
@@ -214,14 +216,13 @@ export function TopNavItem({
   // Drawer mode — render as a SideNavItem-style vertical list element
   // =========================================================================
   if (renderMode === 'drawer') {
+    const activate = closeDrawerAfter(onClick);
     const handleDrawerClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
       if (isDisabled) {
         preventDefaultClick(e);
         return;
       }
-      // Forward the original onClick if present
-      onClick?.(e);
-      closeMobileNav();
+      activate?.(e);
     };
 
     return (

package/src/TopNav/TopNavMegaMenuItem.tsx

@@ -32,7 +32,7 @@ import type {LinkComponentType} from '../Link/types';
 import {useTopNavRenderMode} from './TopNavRenderContext';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
-import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
+import {useCloseMobileDrawerOnActivate} from '../AppShell/useCloseMobileDrawerOnActivate';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
@@ -200,7 +200,9 @@ export function TopNavMegaMenuItem({
   const pressable = usePressFeedback();
   const renderMode = useTopNavRenderMode();
   const LinkComponent = useLinkComponent(as);
-  const {closeMobileNav} = useAppShellMobile();
+  const closeDrawerAfter = useCloseMobileDrawerOnActivate(
+    renderMode === 'drawer',
+  );
 
   // =========================================================================
   // Drawer mode — matches SideNavItem / TopNavMenu drawer appearance
@@ -208,10 +210,9 @@ export function TopNavMegaMenuItem({
   if (renderMode === 'drawer') {
     const Element = href ? LinkComponent : 'button';
     const elementProps = Element === 'button' ? {type: 'button' as const} : {};
-    const handleDrawerClick = () => {
+    const handleDrawerClick = closeDrawerAfter(() => {
       onClick?.();
-      closeMobileNav();
-    };
+    });
     return (
       <Element
         {...restProps}

package/src/TopNav/TopNavMenu.tsx

@@ -39,7 +39,7 @@ import type {BaseProps} from '../BaseProps';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
 import {useTopNavSlot} from './TopNavContext';
 import {useTopNavRenderMode} from './TopNavRenderContext';
-import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
+import {useCloseMobileDrawerOnActivate} from '../AppShell/useCloseMobileDrawerOnActivate';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {isSafeUrl} from '../utils/safeUrl';
 import {themeProps} from '../utils/themeProps';
@@ -363,7 +363,9 @@ export function TopNavMenu({
 }: TopNavMenuProps) {
   const pressable = usePressFeedback();
   const renderMode = useTopNavRenderMode();
-  const {closeMobileNav} = useAppShellMobile();
+  const closeDrawerAfter = useCloseMobileDrawerOnActivate(
+    renderMode === 'drawer',
+  );
   const LinkComponent = useLinkComponent();
   const [drawerExpanded, setDrawerExpanded] = useState(false);
   const menuId = useId();
@@ -524,10 +526,9 @@ export function TopNavMenu({
                 key={getMenuItemKey(item)}
                 href={item.href}
                 {...pressable}
-                onClick={(_e: React.MouseEvent) => {
+                onClick={closeDrawerAfter((_e: React.MouseEvent) => {
                   item.onClick?.();
-                  closeMobileNav();
-                }}
+                })}
                 {...focusOutlineProps.focusVisible(
                   navItemStyles.item,
                   interactionOverlayStyles.backgroundColor,

package/src/gestures/GestureHost.ts

@@ -475,6 +475,16 @@ interface WheelFollow {
   /** The fingers' speed at that move, content px per ms. */
   speedX: number;
   speedY: number;
+  /**
+   * The reading behind that speed: the fingers' travel where it began, and
+   * its interval in ms.
+   */
+  readFromX: number;
+  readFromY: number;
+  readSpan: number;
+  /** The fingers' speed before that reading, content px per ms. */
+  priorSpeedX: number;
+  priorSpeedY: number;
 }
 
 /**
@@ -503,6 +513,39 @@ function absorbedDebt(debt: number, moved: number): number {
   return Math.sign(debt) * Math.max(0, Math.abs(debt) - Math.abs(moved) / 2);
 }
 
+/**
+ * A stall held a bunched wheel's frames back, and the move just before it took
+ * their time. So the wheel joins that move's reading. It can restore what the
+ * late move lowered, but never passes the speed before it.
+ */
+function joinReading(f: WheelFollow, trueX: number, trueY: number): void {
+  if (f.readSpan <= 0) {
+    return;
+  }
+  f.speedX = joinedSpeed(
+    f.speedX,
+    (trueX - f.readFromX) / f.readSpan,
+    f.priorSpeedX,
+  );
+  f.speedY = joinedSpeed(
+    f.speedY,
+    (trueY - f.readFromY) / f.readSpan,
+    f.priorSpeedY,
+  );
+}
+
+/**
+ * A joined reading, held to the speed before the late move. It only ever
+ * raises the current speed, in the current direction.
+ */
+function joinedSpeed(current: number, reading: number, prior: number): number {
+  const held =
+    Math.sign(reading) * Math.min(Math.abs(reading), Math.abs(prior));
+  return held * current >= 0 && Math.abs(held) > Math.abs(current)
+    ? held
+    : current;
+}
+
 /**
  * `target` where it is ahead of `shown` in the direction of `speed`, else
  * `shown`: a reconcile that never steps back.
@@ -2276,9 +2319,22 @@ export class GestureHost {
       }
       if (this.wheelSegment?.decaying === true) {
         // Undecided: the real deltas wait for the splitter while the
-        // fingers' last speed carries the pan on.
+        // fingers' last speed carries the pan on. A held wheel with its own
+        // frame ends the reading a stall's bunch joins.
         f.heldX += dx;
         f.heldY += dy;
+        if (this.wheelSegment.bunched) {
+          // A raised speed moves on from where the pan is shown, so the
+          // position never jumps inside the bunch.
+          const since = time - f.lastMove;
+          const speedX = f.speedX;
+          const speedY = f.speedY;
+          joinReading(f, f.trueX - f.heldX, f.trueY - f.heldY);
+          f.baseX += (speedX - f.speedX) * since;
+          f.baseY += (speedY - f.speedY) * since;
+        } else {
+          f.readSpan = 0;
+        }
         this.followProvisionally(gesture, f, time);
         return;
       }
@@ -2291,10 +2347,18 @@ export class GestureHost {
       const debtY = absorbedDebt(gesture.y - beforeY, dy);
       const trueX = beforeX - dx;
       const trueY = beforeY - dy;
-      // A wheel the splitter reads as one stall's merge sets no speed. Its
-      // speed is one the fingers never had.
+      // A wheel the splitter reads as one stall's merge has no speed of its
+      // own. It joins the reading of the move before its bunch, whose
+      // interval holds its time.
       const elapsed = time - f.lastMove;
-      if (elapsed > 0 && this.wheelSegment?.bunched !== true) {
+      if (this.wheelSegment?.bunched === true) {
+        joinReading(f, trueX, trueY);
+      } else if (elapsed > 0) {
+        f.priorSpeedX = f.speedX;
+        f.priorSpeedY = f.speedY;
+        f.readFromX = f.trueX;
+        f.readFromY = f.trueY;
+        f.readSpan = elapsed;
         f.speedX = (trueX - f.trueX) / elapsed;
         f.speedY = (trueY - f.trueY) / elapsed;
       }
@@ -2445,6 +2509,11 @@ export class GestureHost {
         baseY: kept.y,
         speedX: 0,
         speedY: 0,
+        readFromX: kept.x,
+        readFromY: kept.y,
+        readSpan: 0,
+        priorSpeedX: 0,
+        priorSpeedY: 0,
       };
     }
     this.arena.began(

package/src/hooks/actionGroupTracker.ts

@@ -12,6 +12,8 @@
  * SYNC: When modified, update actionGroupTracker.test.ts
  */
 
+import {clickAndReport, clickForLift} from '../utils/browserClickWait';
+import {armClickGuard} from '../utils/clickGuard';
 import {PRESSED_ATTRIBUTE} from '../utils/pressFeedback';
 import {PRESS_FADE_MS} from '../utils/pressGesture';
 
@@ -70,9 +72,9 @@ export interface ActionGroupTrackerOptions {
    */
   onActivated?: (item: HTMLElement, cancelled: boolean) => void;
   /**
-   * After the lift ran an action, take the browser's own click for that
-   * touch (left to it by a recognizer that did not claim the touch), so the
-   * action runs once. @default false
+   * After the lift ran an action, the shared click guard takes the browser's
+   * own click for that touch, so the action runs once. A recognizer that did
+   * not claim the touch leaves that click to the browser. @default false
    */
   swallowsNativeClick?: boolean;
 }
@@ -126,54 +128,6 @@ interface TrackedAction {
   bottom: number;
 }
 
-/**
- * Swallow the browser's own click for a touch that the lift already acted
- * on. The listeners exist only from that lift until the click, the next
- * press, or the next key. An activation with `detail === 0` (a key or
- * assistive technology) always passes, and the swallower keeps waiting
- * (`AST-094`).
- */
-function swallowNextClick(view: Window): void {
-  const disarm = () => {
-    view.removeEventListener('click', onClick, true);
-    view.removeEventListener('pointerdown', disarm, true);
-    view.removeEventListener('keydown', disarm, true);
-  };
-  const onClick = (event: MouseEvent) => {
-    if (!event.isTrusted || event.detail === 0) {
-      return;
-    }
-    disarm();
-    event.preventDefault();
-    event.stopImmediatePropagation();
-  };
-  view.addEventListener('click', onClick, true);
-  view.addEventListener('pointerdown', disarm, true);
-  view.addEventListener('keydown', disarm, true);
-}
-
-/**
- * Click `element` (its own `click()`, so its activation behavior and every
- * handler run as for any click) and report whether a handler cancelled it.
- * The event is read from a capture listener that exists only for the call.
- */
-function clickAndReport(element: HTMLElement): boolean {
-  const view = element.ownerDocument.defaultView;
-  let clicked: Event | null = null;
-  const grab = (event: Event) => {
-    if (clicked == null && event.target === element) {
-      clicked = event;
-    }
-  };
-  view?.addEventListener('click', grab, true);
-  try {
-    element.click();
-  } finally {
-    view?.removeEventListener('click', grab, true);
-  }
-  return (clicked as Event | null)?.defaultPrevented === true;
-}
-
 /**
  * Create a tracker. `getOptions` is read on every call, so a hook can pass
  * the latest props without recreating it.
@@ -358,14 +312,16 @@ export function createActionGroupTracker(
       const {onActivate, onActivated, swallowsNativeClick} = getOptions();
       if (onActivate != null) {
         onActivate(lifted);
+        if (swallowsNativeClick === true) {
+          armClickGuard(lifted.ownerDocument);
+        }
       } else {
-        const cancelled = clickAndReport(lifted);
+        const cancelled =
+          swallowsNativeClick === true
+            ? clickForLift(lifted)
+            : clickAndReport(lifted);
         onActivated?.(lifted, cancelled);
       }
-      const view = lifted.ownerDocument.defaultView;
-      if (swallowsNativeClick === true && view != null) {
-        swallowNextClick(view);
-      }
       return lifted;
     },
     cancel() {

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/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]);