@astryxdesign/core 0.7.7 → 0.7.8-canary.0d54fd3

package/dist/Tooltip/useTooltip.js

@@ -4,22 +4,23 @@
 
 /**
  * @file useTooltip.tsx
- * @input Uses useLayer, usePressPin, React hooks
- * @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
+ * @input Uses useLayer, useTouchTriggerInternal, React hooks
+ * @output Exports useTooltip hook with stable trigger refs for hover/focus/tap tooltips
+ *   and imperative show() and hide() for an app-built toggle trigger
  * @position Layer hook; builds on useLayer for tooltip behavior
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Tooltip/index.ts
  */
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createTriggerFocusGate } from "../utils/triggerFocus.js";
 import * as stylex from '@stylexjs/stylex';
 import { useLayerInternal } from "../Layer/useLayer.js";
+import { useTouchTriggerInternal } from "../Layer/useTouchTrigger.js";
 import { useAnnounceRenderedText } from "../hooks/useAnnounceRenderedText.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { layerAnimations } from "../Layer/layerAnimations.stylex.js";
 import { registerLayerSurface } from "../Layer/layerSurfacePress.js";
-import { usePressPin } from "../Layer/usePressPin.js";
 import { useLayerDismissal } from "../Layer/useLayerDismissal.js";
 import { themeProps } from "../utils/themeProps.js";
 import "../theme/tokens.stylex.js";
@@ -52,28 +53,6 @@ const styles = {
  * Touch trigger behavior for tooltips
  */
 
-/**
- * Check if an element is naturally focusable
- */
-function isFocusable(element) {
-  // Elements with explicit tabindex
-  if (element.hasAttribute('tabindex')) {
-    return element.tabIndex >= 0;
-  }
-
-  // Naturally focusable elements
-  const focusableTags = ['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA'];
-  if (focusableTags.includes(element.tagName)) {
-    return !element.disabled;
-  }
-
-  // Elements with contenteditable
-  if (element.isContentEditable) {
-    return true;
-  }
-  return false;
-}
-
 /**
  * Hook for tooltip behavior with hover/focus triggers.
  *
@@ -100,24 +79,6 @@ function isFocusable(element) {
  */
 
 export function useTooltip(options = {}) {
-  // 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.
- */
-
-/**
- * `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 = {}) {
   const {
     placement = 'above',
     alignment = 'center',
@@ -125,7 +86,6 @@ export function useTooltipWithTriggerBehavior(options = {}) {
     hideDelay = 0,
     focusTrigger = 'auto',
     touchTrigger = 'auto',
-    triggerBehavior = 'adaptive',
     isEnabled = true,
     isOpen,
     isDefaultOpen = false,
@@ -180,39 +140,118 @@ export function useTooltipWithTriggerBehavior(options = {}) {
     hideLayer();
   }, [clearTimeouts, hideLayer]);
 
-  // A press pins the tooltip under `triggerBehavior="toggle"`. The pin also
-  // owns the tooltip's touch trigger, so this one call wires both.
+  // DOM listeners read the latest controlled state through a ref.
+  const latestRef = useRef({
+    isOpen,
+    isLayerOpen,
+    onShow,
+    onHide
+  });
+  latestRef.current = {
+    isOpen,
+    isLayerOpen,
+    onShow,
+    onHide
+  };
+
+  // The app's show() holds the tooltip open until hide(), Escape, a press or
+  // scroll outside, or focus leaving the trigger and the tooltip.
+  const isHeldRef = useRef(false);
+  const [isHeldState, setIsHeldState] = useState(false);
+  const setHeld = useCallback(next => {
+    isHeldRef.current = next;
+    setIsHeldState(next);
+  }, []);
+
+  // Whether the current hold began during a press on the trigger. Such a
+  // hold ends with the press when the press ends off the trigger, as no click
+  // pins it. The hover rules then decide. isHoldInThisTaskRef covers a show()
+  // that runs before the hook's own pointerdown listener.
+  const isHoldFromPressRef = useRef(false);
+  const isHoldInThisTaskRef = useRef(false);
+  const handleReleaseInLayer = useCallback(() => {
+    if (isHoldFromPressRef.current && isHeldRef.current) {
+      isHoldFromPressRef.current = false;
+      setHeld(false);
+    }
+  }, [setHeld]);
+
+  // The touch trigger's outside dismissal (a press or scroll outside) ends a
+  // hold with the tooltip.
+  const hideFromTouch = useCallback(() => {
+    if (isHeldRef.current) {
+      setHeld(false);
+      const latest = latestRef.current;
+      if (latest.isOpen !== undefined) {
+        latest.onHide?.();
+        return;
+      }
+    }
+    hideNow();
+  }, [setHeld, hideNow]);
   const {
-    isToggleTrigger,
-    isHeldOpen: isPressHeldOpen,
-    attach: attachPressPin,
-    unpin: unpinPress,
-    isPinShown,
-    touch: {
-      isTouchPointerRef,
-      isTouchInteraction,
-      handlePointerEnter,
-      handlePointerDown: handleTouchPointerDown,
-      clearTapOpen
-    }
-  } = usePressPin({
-    triggerBehavior,
+    isTouchPointerRef,
+    isTouchInteraction,
+    handlePointerEnter,
+    handlePointerDown: handleTouchPointerDown,
+    clearTapOpen,
+    armOutsideDismiss
+  } = useTouchTriggerInternal({
     touchTrigger,
     isEnabled,
-    isOpen,
-    isLayerOpen,
+    isControlled: isOpen !== undefined,
+    isOpen: isLayerOpen,
     layerId,
     triggerRef,
-    component: 'Tooltip',
     show: showNow,
-    hide: hideNow,
-    report: next => next ? onShow?.() : onHide?.()
-  });
+    hide: hideFromTouch
+  }, handleReleaseInLayer);
+  const isHeldOpen = useCallback(() => {
+    const latest = latestRef.current;
+    return isHeldRef.current && latest.isLayerOpen && latest.isOpen !== false;
+  }, []);
+  const releaseHold = useCallback(() => {
+    clearTapOpen();
+    setHeld(false);
+    const latest = latestRef.current;
+    if (latest.isOpen !== undefined) {
+      latest.onHide?.();
+      return;
+    }
+    hideNow();
+  }, [clearTapOpen, setHeld, hideNow]);
+  const dropHold = useCallback(() => {
+    if (isHeldRef.current) {
+      setHeld(false);
+    }
+  }, [setHeld]);
+
+  // Focus leaving the trigger and the tooltip ends a hold, whatever
+  // `focusTrigger` is. Focus that leaves for no element is a press's to
+  // decide. The trigger can sit in another document, so the check uses its
+  // own window.
+  const handleHeldFocusOut = useCallback(event => {
+    if (!isHeldOpen()) {
+      return;
+    }
+    const next = event.relatedTarget;
+    const trigger = triggerRef.current;
+    const view = trigger?.ownerDocument.defaultView;
+    if (view == null || !(next instanceof view.Node)) {
+      return;
+    }
+    const surface = trigger?.ownerDocument.getElementById(layerId) ?? null;
+    if (trigger?.contains(next) === true || surface?.contains(next) === true) {
+      return;
+    }
+    releaseHold();
+  }, [isHeldOpen, layerId, releaseHold]);
+  const isHoldShown = isHeldState && isLayerOpen && isOpen !== false;
 
-  // Only a pin announces the text: a preview is already the trigger's
+  // Only a hold announces the text: a preview is already the trigger's
   // description.
   const contentRef = useRef(null);
-  useAnnounceRenderedText(contentRef, isPinShown, 'pinned');
+  useAnnounceRenderedText(contentRef, isHoldShown, 'pinned');
   const contentRefs = useMergedRefs(contentRef, registerLayerSurface);
 
   // Schedule show with delay (suppressed when isOpen is false)
@@ -242,7 +281,7 @@ export function useTooltipWithTriggerBehavior(options = {}) {
   // trigger onto the tooltip surface without the tooltip vanishing — required
   // for WCAG 1.4.13 (Content on Hover or Focus: hoverable).
   const scheduleHide = useCallback(() => {
-    if (isOpen === true || isPressHeldOpen()) {
+    if (isOpen === true || isHeldOpen()) {
       return;
     }
     clearTimeouts();
@@ -250,7 +289,7 @@ export function useTooltipWithTriggerBehavior(options = {}) {
     hideTimeoutRef.current = setTimeout(() => {
       hideLayer();
     }, effectiveHideDelay);
-  }, [isOpen, isPressHeldOpen, clearTimeouts, hideLayer, hideDelay]);
+  }, [isOpen, isHeldOpen, clearTimeouts, hideLayer, hideDelay]);
 
   // Cancel a pending hide (e.g. the pointer entered the tooltip surface).
   const cancelHide = useCallback(() => {
@@ -289,25 +328,11 @@ export function useTooltipWithTriggerBehavior(options = {}) {
     scheduleHide();
   }, [isTouchPointerRef, layerId, scheduleHide]);
 
-  // Under `auto`, whether focus counts is decided when it arrives, not when
-  // the listeners attach: a roving-tabindex member that was `tabindex="-1"`
-  // then can be the tab stop now. A trigger that receives focus is focusable
-  // by definition; focus inside it counts only while the trigger is
-  // focusable too, so a plain wrapper still ignores its children's focus.
-  const isFocusForTrigger = useCallback(e => {
-    if (focusTrigger === 'always') {
-      return true;
-    }
-    const triggerEl = e.currentTarget;
-    return triggerEl != null && (e.target === triggerEl || isFocusable(triggerEl));
-  }, [focusTrigger]);
-
-  // Whether the trigger's current focus counted when it arrived, so its blur
-  // hides the tooltip even if the trigger has since left the tab order.
-  const focusCountedRef = useRef(false);
+  // Under `auto`, whether focus counts is decided when it arrives, and a
+  // focus that counted still hides on blur (utils/triggerFocus.ts).
+  const [focusGate] = useState(createTriggerFocusGate);
   const handleFocusIn = useCallback(e => {
-    focusCountedRef.current = isFocusForTrigger(e);
-    if (!isEnabled || !focusCountedRef.current) {
+    if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
       return;
     }
     // A tap focuses the trigger it activates, and `:focus-visible` does not
@@ -326,18 +351,17 @@ export function useTooltipWithTriggerBehavior(options = {}) {
     }
     clearTimeouts();
     showLayer();
-  }, [isEnabled, isFocusForTrigger, isTouchInteraction, clearTimeouts, showLayer]);
+  }, [focusGate, focusTrigger, isEnabled, isTouchInteraction, clearTimeouts, showLayer]);
 
-  // A pinned tooltip's focus-leave close is the pin's own: it listens on the
-  // trigger whatever `focusTrigger` is. This schedules the unpinned hide,
-  // which a held tooltip skips.
+  // A held tooltip's focus-leave close is the hold's own: it listens on the
+  // trigger whatever `focusTrigger` is. This schedules the unheld hide, which
+  // a held tooltip skips.
   const handleFocusOut = useCallback(e => {
-    if (!focusCountedRef.current && !isFocusForTrigger(e)) {
+    if (!focusGate.focusOut(e, focusTrigger)) {
       return;
     }
-    focusCountedRef.current = false;
     scheduleHide();
-  }, [isFocusForTrigger, scheduleHide]);
+  }, [focusGate, focusTrigger, scheduleHide]);
 
   // Pressing the trigger hides its own tooltip: once the control is activated
   // the hint has served its purpose, and a tooltip lingering over a
@@ -346,10 +370,41 @@ export function useTooltipWithTriggerBehavior(options = {}) {
   // is owned by the consumer. `hideLayer()` self-guards when already closed.
   // A touch press is a different gesture (it may be the only way to open the
   // tooltip at all), so the touch path answers it first.
+  // Whether a press on the trigger is down, from the hook's pointerdown to
+  // the press's end.
+  const isTriggerPressedRef = useRef(false);
+  const stopPressTrackingRef = useRef(null);
+  const trackTriggerPress = useCallback(() => {
+    stopPressTrackingRef.current?.();
+    const view = triggerRef.current?.ownerDocument.defaultView;
+    if (view == null) {
+      return;
+    }
+    isTriggerPressedRef.current = true;
+    const trigger = triggerRef.current;
+    const stop = event => {
+      // A press that ends on the trigger keeps its hold, as a click does.
+      if (event?.type === 'pointerup' && event.target instanceof view.Node && trigger?.contains(event.target) === true) {
+        isHoldFromPressRef.current = false;
+      }
+      view.removeEventListener('pointerup', stop, true);
+      view.removeEventListener('pointercancel', stop, true);
+      isTriggerPressedRef.current = false;
+      stopPressTrackingRef.current = null;
+    };
+    view.addEventListener('pointerup', stop, true);
+    view.addEventListener('pointercancel', stop, true);
+    stopPressTrackingRef.current = stop;
+  }, []);
   const handlePointerDown = useCallback(event => {
-    // A press on a toggle trigger pins or closes through its click. It
-    // neither hides the preview here nor waits for a tap verdict.
-    if (isToggleTrigger(triggerRef.current)) {
+    trackTriggerPress();
+    // The app's hide() closes a held tooltip. A press neither hides it here
+    // nor waits for a tap verdict. A show() in a capture handler of this
+    // press runs before this listener. Tie that hold to the press.
+    if (isHeldRef.current) {
+      if (isHoldInThisTaskRef.current) {
+        isHoldFromPressRef.current = true;
+      }
       return;
     }
     if (handleTouchPointerDown(event)) {
@@ -360,7 +415,7 @@ export function useTooltipWithTriggerBehavior(options = {}) {
     }
     clearTimeouts();
     hideLayer();
-  }, [isToggleTrigger, handleTouchPointerDown, isOpen, clearTimeouts, hideLayer]);
+  }, [handleTouchPointerDown, trackTriggerPress, isOpen, clearTimeouts, hideLayer]);
 
   // Interaction ref that handles event listeners only
   const interactionRef = useCallback(el => {
@@ -370,6 +425,8 @@ export function useTooltipWithTriggerBehavior(options = {}) {
       triggerRef.current.removeEventListener('mouseleave', handleMouseLeave);
       triggerRef.current.removeEventListener('focusin', handleFocusIn);
       triggerRef.current.removeEventListener('focusout', handleFocusOut);
+      triggerRef.current.removeEventListener('focusout', handleHeldFocusOut);
+      stopPressTrackingRef.current?.();
       triggerRef.current.removeEventListener('pointerenter', handlePointerEnter);
       triggerRef.current.removeEventListener('pointerdown', handlePointerDown);
     }
@@ -384,15 +441,17 @@ export function useTooltipWithTriggerBehavior(options = {}) {
       el.addEventListener('pointerdown', handlePointerDown);
 
       // Focus listeners unless focus never opens the tooltip; `auto` decides
-      // per event (isFocusForTrigger).
+      // per event (utils/triggerFocus.ts).
       if (focusTrigger !== 'never') {
         el.addEventListener('focusin', handleFocusIn);
         el.addEventListener('focusout', handleFocusOut);
       }
     }
+
+    // Its own focus-leave listener: `focusTrigger="never"` attaches none.
+    el?.addEventListener('focusout', handleHeldFocusOut);
     triggerRef.current = el;
-    attachPressPin(el);
-  }, [attachPressPin, focusTrigger, handleMouseEnter, handleMouseLeave, handleFocusIn, handleFocusOut, handlePointerEnter, handlePointerDown]);
+  }, [handleHeldFocusOut, focusTrigger, handleMouseEnter, handleMouseLeave, handleFocusIn, handleFocusOut, handlePointerEnter, handlePointerDown]);
 
   // Combined ref - shorthand for calling both positionRef and interactionRef
   const ref = useCallback(el => {
@@ -425,9 +484,11 @@ export function useTooltipWithTriggerBehavior(options = {}) {
       showLayer();
     } else {
       clearTimeouts();
+      // A hold ends when the consumer closes the tooltip.
+      dropHold();
       hideLayer();
     }
-  }, [isOpen, clearTimeouts, showLayer, hideLayer]);
+  }, [isOpen, clearTimeouts, showLayer, hideLayer, dropHold]);
 
   // Dismiss on Escape (WCAG 1.4.13 — dismissible) through the shared layer
   // stack. A visible tip is the top-most layer, so it takes the press and
@@ -465,7 +526,7 @@ export function useTooltipWithTriggerBehavior(options = {}) {
     onDismiss: () => {
       clearTimeouts();
       clearTapOpen();
-      unpinPress();
+      dropHold();
       if (isOpen !== undefined) {
         onHide?.();
         return;
@@ -498,7 +559,7 @@ export function useTooltipWithTriggerBehavior(options = {}) {
     // something else in the shared interactive-ancestor walk, so a
     // clickable container around the trigger leaves the press alone while
     // document listeners still see it.
-    // The pin's announcement reads this element's text.
+    // The hold's announcement reads this element's text.
     _jsx("div", {
       ref: contentRefs,
       ...{
@@ -507,12 +568,37 @@ export function useTooltipWithTriggerBehavior(options = {}) {
       children: children
     }), renderProps);
   }, [renderLayer, placement, alignment, popoverXstyle, cancelHide, scheduleHide, contentRefs]);
+  const show = useCallback(() => {
+    clearTimeouts();
+    if (!isEnabled) {
+      return;
+    }
+    setHeld(true);
+    armOutsideDismiss();
+    isHoldFromPressRef.current = isTriggerPressedRef.current;
+    isHoldInThisTaskRef.current = true;
+    triggerRef.current?.ownerDocument.defaultView?.setTimeout(() => {
+      isHoldInThisTaskRef.current = false;
+    }, 0);
+    const latest = latestRef.current;
+    if (latest.isOpen !== undefined) {
+      latest.onShow?.();
+      return;
+    }
+    showLayer();
+  }, [clearTimeouts, isEnabled, setHeld, armOutsideDismiss, showLayer]);
+  const hide = useCallback(() => {
+    clearTimeouts();
+    releaseHold();
+  }, [clearTimeouts, releaseHold]);
   return {
     ref,
     positionRef: layerRef,
     interactionRef,
     anchorId: layerAnchorId,
     describedBy: layerId,
-    renderTooltip
+    renderTooltip,
+    show,
+    hide
   };
 }

package/dist/Typeahead/BaseTypeahead.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseTypeahead.d.ts","sourceRoot":"","sources":["../../src/Typeahead/BaseTypeahead.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,EAOZ,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAKf,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAgCnD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAgB,cAAc,EAAE,YAAY,EAAC,MAAM,SAAS,CAAC;AAmBzE,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,cAAc,CAAE,SAAQ,IAAI,CACxE,SAAS,CAAC,WAAW,CAAC,EACtB,UAAU,CACX;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC;;OAEG;IACH,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9B;;OAEG;IACH,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,CAAC;IAEpC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAE5B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;OASG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;IAEtD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;IAE3B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE1C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IAE/D;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;CAC3B;AA8MD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,EAq1CrB,CAAC,CAAC,SAAS,cAAc,EAC5B,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,KACzB,KAAK,CAAC,YAAY,CAAC"}
+{"version":3,"file":"BaseTypeahead.d.ts","sourceRoot":"","sources":["../../src/Typeahead/BaseTypeahead.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,EAQZ,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAKf,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAgCnD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAgB,cAAc,EAAE,YAAY,EAAC,MAAM,SAAS,CAAC;AAmBzE,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,cAAc,CAAE,SAAQ,IAAI,CACxE,SAAS,CAAC,WAAW,CAAC,EACtB,UAAU,CACX;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC;;OAEG;IACH,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9B;;OAEG;IACH,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,CAAC;IAEpC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC;IAE5B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;OASG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;IAEtD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;IAE3B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE1C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IAE/D;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;CAC3B;AA8MD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,EA81CrB,CAAC,CAAC,SAAS,cAAc,EAC5B,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,KACzB,KAAK,CAAC,YAAY,CAAC"}

package/dist/Typeahead/BaseTypeahead.js

@@ -19,7 +19,7 @@
  * - /packages/core/src/Typeahead/index.ts
  * - /packages/cli/assets/templates/blocks/components/Typeahead/ (showcase blocks)
  */
-import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useId, useInsertionEffect, useMemo, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { useBusyIndicatorLane } from "./busyIndicatorLane.js";
 import { useTrailingKeyDown } from "./trailingKeyDown.js";
@@ -455,15 +455,6 @@ export const BaseTypeahead = function BaseTypeahead({
   // source: they can never be re-shown, so focus bootstraps the new source.
   const sourceGenRef = useRef(0);
 
-  // Results still arriving from a replaced source must not land in the new
-  // one's menu.
-  const prevSearchSourceRef = useRef(searchSource);
-  if (prevSearchSourceRef.current !== searchSource) {
-    prevSearchSourceRef.current.cancel?.();
-    prevSearchSourceRef.current = searchSource;
-    sourceGenRef.current = ++searchGenRef.current;
-  }
-
   // The previous source is remembered in state, not a ref, so a render React
   // discards cannot consume the comparison without its state updates.
   const [sourceOfState, setSourceOfState] = useState(searchSource);
@@ -473,7 +464,6 @@ export const BaseTypeahead = function BaseTypeahead({
       setIsLoading(false);
       setHasSearched(false);
     }
-    loadingRef.current = false;
   }
   // A field that becomes disabled stops showing a search as busy in the same
   // render, and the dropped query shows no outcome, so no empty state; the
@@ -487,15 +477,34 @@ export const BaseTypeahead = function BaseTypeahead({
     }
   }
 
-  // When the search source is replaced, any in-flight load from the previous
-  // source is abandoned (generation bumped above). Notify the wrapper's busy lane
-  // in an effect so external store listeners run safely after commit.
-  const isInitialMountRef = useRef(true);
-  useEffect(() => {
-    if (isInitialMountRef.current) {
-      isInitialMountRef.current = false;
+  // Results that arrive from a replaced source must not land in the new
+  // source's menu, so the replacement starts a new generation. That happens
+  // when the replacement commits, not in render. React can render a
+  // replacement and then discard it, for example when a transition suspends
+  // and a newer update replaces it. The source that stays then keeps its read.
+  // An insertion effect runs before every layout effect and ref callback of
+  // its commit. A read that one of them starts against the replacement gets a
+  // later generation, after the replaced source stopped its requests.
+  const prevSearchSourceRef = useRef(searchSource);
+  const isSourceReplacedRef = useRef(false);
+  useInsertionEffect(() => {
+    if (prevSearchSourceRef.current === searchSource) {
+      return;
+    }
+    prevSearchSourceRef.current.cancel?.();
+    prevSearchSourceRef.current = searchSource;
+    sourceGenRef.current = ++searchGenRef.current;
+    // The replacing render cleared the busy state.
+    loadingRef.current = false;
+    isSourceReplacedRef.current = true;
+  }, [searchSource]);
+  // Syncs the wrapper's busy lane. A read of the replacement that already
+  // started keeps the lane busy.
+  useIsomorphicLayoutEffect(() => {
+    if (!isSourceReplacedRef.current) {
       return;
     }
+    isSourceReplacedRef.current = false;
     if (!loadingRef.current) {
       onLoadingChangeRef.current?.(false);
     }

package/dist/Typeahead/TypeaheadItem.d.ts

@@ -31,7 +31,8 @@ export interface TypeaheadItemProps<T extends SearchableItem = SearchableItem> e
      */
     isDisabled?: boolean;
     /**
-     * Group label for grouping items visually.
+     * This prop has no effect. Set `item.auxiliaryData.group` on search-source
+     * items to group results in Typeahead or BaseTypeahead.
      */
     group?: string;
 }

package/dist/Typeahead/TypeaheadItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TypeaheadItem.d.ts","sourceRoot":"","sources":["../../src/Typeahead/TypeaheadItem.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAQ5C,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAQ5C,MAAM,WAAW,kBAAkB,CACjC,CAAC,SAAS,cAAc,GAAG,cAAc,CACzC,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA6CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,cAAc,EAAE,EACtD,GAAG,EACH,IAAI,EACJ,IAAI,EACJ,WAAW,EACX,UAAkB,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,kBAAkB,CAAC,CAAC,CAAC,qBAyBvB;yBApCe,aAAa"}
+{"version":3,"file":"TypeaheadItem.d.ts","sourceRoot":"","sources":["../../src/Typeahead/TypeaheadItem.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAQ5C,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAQ5C,MAAM,WAAW,kBAAkB,CACjC,CAAC,SAAS,cAAc,GAAG,cAAc,CACzC,SAAQ,SAAS,CAAC,cAAc,CAAC;IACjC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,IAAI,EAAE,CAAC,CAAC;IAER;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA6CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,cAAc,EAAE,EACtD,GAAG,EACH,IAAI,EACJ,IAAI,EACJ,WAAW,EACX,UAAkB,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,kBAAkB,CAAC,CAAC,CAAC,qBAyBvB;yBApCe,aAAa"}

package/dist/animator/createAnimator.d.ts

@@ -0,0 +1,98 @@
+/**
+ * A channel the animator drives. `x` and `y` translate the element (px).
+ * `scale` scales it about its transform origin (1 is its size). `rotate`
+ * turns it (degrees, clockwise), and `opacity` fades it (0 to 1).
+ */
+export type AnimatorChannel = 'x' | 'y' | 'scale' | 'rotate' | 'opacity';
+/**
+ * Values by channel. A velocity uses the same keys, in units per second:
+ * px/s, scale per second, deg/s, opacity per second.
+ */
+export type AnimatorValues = Partial<Record<AnimatorChannel, number>>;
+/** Every channel's value (or velocity), as `get` and `getVelocity` read it. */
+export type AnimatorSnapshot = Readonly<Record<AnimatorChannel, number>>;
+/** Options of `AnimatorHandle.animate`. */
+export interface AnimatorAnimateOptions {
+    /**
+     * Each channel's velocity at the start, such as a drag's release velocity.
+     * A channel without one keeps the
+     * velocity it has on screen, so an `animate` that interrupts another
+     * carries on smoothly.
+     */
+    velocity?: AnimatorValues;
+}
+/**
+ * A release velocity for `AnimatorHandle.decay`, per channel, in its units
+ * per second. That is px/s for `x` and `y`, and degrees per second for
+ * `rotate`. `scale` and `opacity` take their units per second.
+ */
+export type AnimatorDecayVelocity = AnimatorValues;
+/**
+ * Animates one element. Each method acts on the channels it is given and
+ * leaves the others where they are.
+ */
+export interface AnimatorHandle {
+    /**
+     * Springs the given channels to `target` on the `springs.stateChange`
+     * motion role, from wherever they are on screen. The promise resolves when
+     * they arrive, or as soon as a later `animate`, `decay`, `set` or `stop`
+     * takes any of them over.
+     */
+    animate(target: AnimatorValues, options?: AnimatorAnimateOptions): Promise<void>;
+    /**
+     * Coasts the given channels from a release velocity, slowing as a scroll
+     * view's momentum does. It resolves when they stop, or when another call
+     * takes them over. The distance follows from the velocity alone: there are
+     * no bounds, except that opacity stops at 0 or 1.
+     */
+    decay(velocity: AnimatorDecayVelocity): Promise<void>;
+    /**
+     * Puts the given channels at these values at once, ending their motion:
+     * the per-frame write of a drag.
+     */
+    set(values: AnimatorValues): void;
+    /** Every channel's value on screen now. */
+    get(): AnimatorSnapshot;
+    /** Every channel's velocity on screen now, in units per second. */
+    getVelocity(): AnimatorSnapshot;
+    /** Halts every channel where it is on screen. */
+    stop(): void;
+}
+/** What `createAnimator` returns: the handle, and `destroy`. */
+export interface Animator extends AnimatorHandle {
+    /**
+     * Stops every motion and lets go of the element; the element keeps the
+     * values it shows. The animator does nothing after this.
+     */
+    destroy(): void;
+}
+/**
+ * An animator whose element is attached later, through `attach`. It is the
+ * one construction `createAnimator` and `useAnimator` share, so the hook has
+ * no behavior of its own. Not exported from the package.
+ */
+export declare function createAttachableAnimator(): {
+    readonly animator: Animator;
+    readonly attach: (element: HTMLElement | null) => void;
+};
+/**
+ * Animates `element` with the motion Core uses. `animate` springs channels to
+ * a target on the state-change motion, and `decay` coasts them from a release
+ * velocity. `set` jumps them, `get` and `getVelocity` read them, `stop` halts
+ * them, and `destroy` lets the element go. Under Reduce Motion every call is
+ * planned. A move becomes a short cross-fade on a touch screen, and it lands
+ * at once with a mouse.
+ *
+ * Use one animator per element: two on one element overwrite each other.
+ *
+ * @example
+ * ```
+ * const card = document.querySelector('.card');
+ * const animator = createAnimator(card);
+ * await animator.animate({x: 0, rotate: 0}, {velocity: {x: -900}});
+ * animator.decay({x: 2400});
+ * animator.destroy();
+ * ```
+ */
+export declare function createAnimator(element: HTMLElement): Animator;
+//# sourceMappingURL=createAnimator.d.ts.map

package/dist/animator/createAnimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAnimator.d.ts","sourceRoot":"","sources":["../../src/animator/createAnimator.ts"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,GAAG,GAAG,GAAG,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzE;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;AAEtE,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;AAEzE,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,cAAc,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,OAAO,CACL,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAClC,2CAA2C;IAC3C,GAAG,IAAI,gBAAgB,CAAC;IACxB,mEAAmE;IACnE,WAAW,IAAI,gBAAgB,CAAC;IAChC,iDAAiD;IACjD,IAAI,IAAI,IAAI,CAAC;CACd;AAED,gEAAgE;AAChE,MAAM,WAAW,QAAS,SAAQ,cAAc;IAC9C;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAqFD;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI;IAC1C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;CACxD,CA+FA;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,CAI7D"}