@astryxdesign/core 0.7.7-canary.c0929c8 → 0.7.7-canary.c19ca12

package/src/Tooltip/useTooltip.doc.mjs

@@ -7,33 +7,146 @@ export const docs = {
   group: 'Tooltip',
   keywords: ['tooltip', 'hint', 'label', 'hover', 'info', 'title', 'floating'],
   params: [
-    {name: 'placement', type: "'above' | 'below' | 'start' | 'end'", description: "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'above'"},
-    {name: 'alignment', type: "'start' | 'center' | 'end'", description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'center'"},
-    {name: 'delay', type: 'number', description: 'Delay before showing on hover, in milliseconds.', default: '200'},
-    {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '0'},
-    {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the tooltip. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.', default: "'auto'"},
-    {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens; none never opens on touch. It decides only under triggerBehavior="adaptive", the default.', default: "'auto'"},
-    {name: 'triggerBehavior', type: "'adaptive' | 'hover' | 'toggle'", description: 'How the trigger opens the tooltip. adaptive (the default) previews on hover and focus and opens on a tap unless the trigger acts (touchTrigger decides while it remains); hover previews on hover and focus, and no touch or pen tap opens it; toggle, on a button trigger, pins on a click, a tap, Enter, or Space and closes on the same press, Escape, a press outside, or focus leaving. The trigger carries aria-expanded and aria-controls, the tooltip is announced once when it pins. Astryx clickable rows and cards ignore the pinning press, except an Item row on a trigger that is not a native button; a plain onClick ancestor still receives it from the hook (the Tooltip component stops it at a child trigger).', default: "'adaptive'"},
-    {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
-    {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
-    {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the tooltip should be shown on mount.', default: 'false'},
-    {name: 'onShow', type: '() => void', description: 'Callback fired when the tooltip becomes visible.'},
-    {name: 'onHide', type: '() => void', description: 'Callback fired when the tooltip is hidden.'},
+    {
+      name: 'placement',
+      type: "'above' | 'below' | 'start' | 'end'",
+      description:
+        "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+      default: "'above'",
+    },
+    {
+      name: 'alignment',
+      type: "'start' | 'center' | 'end'",
+      description:
+        "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+      default: "'center'",
+    },
+    {
+      name: 'delay',
+      type: 'number',
+      description: 'Delay before showing on hover, in milliseconds.',
+      default: '200',
+    },
+    {
+      name: 'hideDelay',
+      type: 'number',
+      description:
+        'Delay before hiding after mouse or focus leaves, in milliseconds.',
+      default: '0',
+    },
+    {
+      name: 'focusTrigger',
+      type: "'auto' | 'always' | 'never'",
+      description:
+        'When focus should open the tooltip. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.',
+      default: "'auto'",
+    },
+    {
+      name: 'touchTrigger',
+      type: "'auto' | 'tap' | 'none'",
+      description:
+        'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens (a button whose only job is revealing the tooltip); none never opens on touch.',
+      default: "'auto'",
+    },
+    {
+      name: 'isEnabled',
+      type: 'boolean',
+      description: 'Whether hover and focus triggers are enabled.',
+      default: 'true',
+    },
+    {
+      name: 'isOpen',
+      type: 'boolean',
+      description:
+        'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.',
+    },
+    {
+      name: 'isDefaultOpen',
+      type: 'boolean',
+      description: 'Whether the tooltip should be shown on mount.',
+      default: 'false',
+    },
+    {
+      name: 'onShow',
+      type: '() => void',
+      description: 'Callback fired when the tooltip becomes visible.',
+    },
+    {
+      name: 'onHide',
+      type: '() => void',
+      description: 'Callback fired when the tooltip is hidden.',
+    },
   ],
   returns: [
-    {name: 'ref', type: 'RefCallback<HTMLElement>', description: 'Combined ref that sets both position and interaction on the same trigger element.'},
-    {name: 'positionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the positioning anchor element.'},
-    {name: 'interactionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the hover/focus interaction element.'},
-    {name: 'anchorId', type: 'string', description: 'CSS anchor name for advanced positioning cases.'},
-    {name: 'describedBy', type: 'string', description: 'ID to compose into aria-describedby on the trigger.'},
-    {name: 'renderTooltip', type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode", description: 'Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment.'},
+    {
+      name: 'ref',
+      type: 'RefCallback<HTMLElement>',
+      description:
+        'Combined ref that sets both position and interaction on the same trigger element.',
+    },
+    {
+      name: 'positionRef',
+      type: 'RefCallback<HTMLElement>',
+      description: 'Ref for the positioning anchor element.',
+    },
+    {
+      name: 'interactionRef',
+      type: 'RefCallback<HTMLElement>',
+      description: 'Ref for the hover/focus interaction element.',
+    },
+    {
+      name: 'anchorId',
+      type: 'string',
+      description: 'CSS anchor name for advanced positioning cases.',
+    },
+    {
+      name: 'describedBy',
+      type: 'string',
+      description: 'ID to compose into aria-describedby on the trigger.',
+    },
+    {
+      name: 'renderTooltip',
+      type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode",
+      description:
+        'Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment.',
+    },
+    {
+      name: 'show',
+      type: '() => void',
+      description:
+        'Opens the tooltip now and keeps it open until hide(), Escape, a press outside, or focus leaving its trigger. Its text is announced once, and onShow fires. Under a controlled isOpen it only calls onShow. Does nothing while isEnabled is false.',
+    },
+    {
+      name: 'hide',
+      type: '() => void',
+      description:
+        'Closes the tooltip now, and onHide fires. Under a controlled isOpen it only calls onHide.',
+    },
   ],
   usage: {
-    description: 'Headless hook for hover/focus-triggered tooltips. Builds on useLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.',
+    description:
+      'Headless hook for hover/focus-triggered tooltips. Builds on useLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.',
     bestPractices: [
-      {guidance: true, description: 'Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.'},
-      {guidance: true, description: 'Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.'},
-      {guidance: false, description: 'Put interactive content inside tooltips: use Popover or HoverCard instead.'},
+      {
+        guidance: true,
+        description:
+          'Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.',
+      },
+      {
+        guidance: true,
+        description:
+          'For a toggle-style trigger, have your own button call show() and hide() on each press. Give it aria-describedby and aria-controls set to describedBy, and aria-expanded (true while show() holds the tooltip, false after hide() or onHide), and keep its own accessible name. For an info icon, use InfoTip instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put interactive content inside tooltips: use Popover or HoverCard instead.',
+      },
     ],
   },
   relatedComponents: ['Tooltip', 'HoverCard', 'Popover'],
@@ -44,17 +157,22 @@ export const docs = {
 
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
-  description: 'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
+  description:
+    'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
   paramDescriptions: {
-    placement: 'position relative to trigger. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
-    alignment: 'alignment along placement axis. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
+    placement:
+      "position relative to trigger. logical: start/end follow the popover's inherited direction (RTL mirrors).",
+    alignment:
+      "alignment along placement axis. logical: start/end follow the popover's inherited direction (RTL mirrors).",
     delay: 'show delay in ms.',
     hideDelay: 'hide delay after mouse/focus leave in ms.',
-    focusTrigger: 'when focus opens tooltip; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
-    touchTrigger: 'tap behavior with no hover, under triggerBehavior adaptive only; auto = tap unless trigger acts, tap = always, none = never.',
-    triggerBehavior: 'adaptive (default) = hover/focus preview, tap opens unless the trigger acts; hover = no touch/pen tap opens; toggle = a press on a button trigger pins and closes; clickable rows and cards ignore it (an Item row only on a native-button trigger), and the Tooltip component also stops it at a child trigger.',
+    focusTrigger:
+      'when focus opens tooltip; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
+    touchTrigger:
+      'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
     isEnabled: 'whether hover/focus triggers are enabled.',
-    isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
+    isOpen:
+      'controlled open state: true force-show, false force-hide, undefined unmanaged.',
     isDefaultOpen: 'show on mount.',
     onShow: 'fires when tooltip becomes visible.',
     onHide: 'fires when tooltip hides.',
@@ -66,13 +184,33 @@ export const docsDense = {
     anchorId: 'CSS anchor name.',
     describedBy: 'ID for aria-describedby.',
     renderTooltip: 'renders anchor-positioned tooltip content.',
+    show: 'opens + holds until hide()/Escape/outside press/focus leave; announces once; onShow. Controlled: onShow only. No-op when disabled.',
+    hide: 'closes; onHide. Controlled: onHide only.',
   },
   usage: {
-    description: 'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
+    description:
+      'Headless hover/focus tooltip hook. Builds on useLayer w/ hover intent, keyboard focus handling, aria-describedby. Use for custom triggers without wrapper component.',
     bestPractices: [
-      {guidance: true, description: 'Use for brief text labels describing icon buttons, truncated text, abbreviations, compact controls.'},
-      {guidance: true, description: 'Prefer Tooltip for standard wrapping; use hook when trigger is not simple child.'},
-      {guidance: false, description: 'Put interactive content in tooltips: use Popover / HoverCard instead.'},
+      {
+        guidance: true,
+        description:
+          'Use for brief text labels describing icon buttons, truncated text, abbreviations, compact controls.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer Tooltip for standard wrapping; use hook when trigger is not simple child.',
+      },
+      {
+        guidance: true,
+        description:
+          'Toggle-style trigger: own button calls show()/hide() per press, sets aria-describedby + aria-controls={describedBy}, aria-expanded (true while held), keeps its own name. Info icon: use InfoTip.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put interactive content in tooltips: use Popover / HoverCard instead.',
+      },
     ],
   },
 };

package/src/Tooltip/useTooltip.tsx

@@ -6,6 +6,8 @@
  * @file useTooltip.tsx
  * @input Uses useLayer, usePressPin, 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,
+ *   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:
@@ -16,9 +18,11 @@ import {
   useCallback,
   useEffect,
   useRef,
+  useState,
   type ReactNode,
   type RefCallback,
 } from 'react';
+import {createTriggerFocusGate} from '../utils/triggerFocus';
 import * as stylex from '@stylexjs/stylex';
 import {
   useLayerInternal,
@@ -31,7 +35,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 +87,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 +131,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.
@@ -245,29 +219,25 @@ export interface TooltipReturn {
     children: ReactNode,
     props?: Omit<ContextRenderProps, 'positioning'>,
   ) => ReactNode;
-}
 
-/**
- * Check if an element is naturally focusable
- */
-function isFocusable(element: HTMLElement): boolean {
-  // 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 as HTMLButtonElement).disabled;
-  }
-
-  // Elements with contenteditable
-  if (element.isContentEditable) {
-    return true;
-  }
-
-  return false;
+  /**
+   * Opens the tooltip now and keeps it open until `hide()`, Escape, a press
+   * outside, or focus leaving its trigger, as a pinned tooltip does. Its text
+   * is announced once. Reports through `onShow`. Under a controlled `isOpen`,
+   * it calls `onShow` and does not change `isOpen`. Does nothing while
+   * `isEnabled` is false.
+   *
+   * Use `show()` and `hide()` to build a toggle-style trigger: your own button
+   * calls them, sets `aria-describedby` and `aria-controls` to `describedBy`
+   * and `aria-expanded` (true while shown), and keeps its own accessible name.
+   */
+  show: () => void;
+
+  /**
+   * Closes the tooltip now. Reports through `onHide`. Under a controlled
+   * `isOpen`, it calls `onHide` and does not change `isOpen`.
+   */
+  hide: () => void;
 }
 
 /**
@@ -296,6 +266,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',
@@ -368,6 +374,9 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     isHeldOpen: isPressHeldOpen,
     attach: attachPressPin,
     unpin: unpinPress,
+    hold: holdPress,
+    release: releasePress,
+    isAppHeld,
     isPinShown,
     touch: {
       isTouchPointerRef,
@@ -478,32 +487,13 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     [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: Event): boolean => {
-      if (focusTrigger === 'always') {
-        return true;
-      }
-      const triggerEl = e.currentTarget as HTMLElement | null;
-      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: Event) => {
-      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
@@ -524,8 +514,9 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       showLayer();
     },
     [
+      focusGate,
+      focusTrigger,
       isEnabled,
-      isFocusForTrigger,
       isTouchInteraction,
       clearTimeouts,
       showLayer,
@@ -537,13 +528,12 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // which a held tooltip skips.
   const handleFocusOut = useCallback(
     (e: Event) => {
-      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
@@ -555,9 +545,10 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // tooltip at all), so the touch path answers it first.
   const handlePointerDown = useCallback(
     (event: PointerEvent) => {
-      // 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)) {
+      // A toggle trigger's press pins or closes through its click. The app's
+      // hide() closes a held tooltip. Neither path hides here or waits for a
+      // tap verdict.
+      if (isToggleTrigger(triggerRef.current) || isAppHeld()) {
         return;
       }
       if (handleTouchPointerDown(event)) {
@@ -569,7 +560,14 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       clearTimeouts();
       hideLayer();
     },
-    [isToggleTrigger, handleTouchPointerDown, isOpen, clearTimeouts, hideLayer],
+    [
+      isToggleTrigger,
+      isAppHeld,
+      handleTouchPointerDown,
+      isOpen,
+      clearTimeouts,
+      hideLayer,
+    ],
   );
 
   // Interaction ref that handles event listeners only
@@ -602,7 +600,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         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);
@@ -658,9 +656,11 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       showLayer();
     } else {
       clearTimeouts();
+      // A pin or app hold ends when the consumer closes the tooltip.
+      unpinPress();
       hideLayer();
     }
-  }, [isOpen, clearTimeouts, showLayer, hideLayer]);
+  }, [isOpen, clearTimeouts, showLayer, hideLayer, unpinPress]);
 
   // 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
@@ -756,6 +756,16 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     ],
   );
 
+  const show = useCallback(() => {
+    clearTimeouts();
+    holdPress();
+  }, [clearTimeouts, holdPress]);
+
+  const hide = useCallback(() => {
+    clearTimeouts();
+    releasePress();
+  }, [clearTimeouts, releasePress]);
+
   return {
     ref,
     positionRef: layerRef,
@@ -763,5 +773,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     anchorId: layerAnchorId,
     describedBy: layerId,
     renderTooltip,
+    show,
+    hide,
   };
 }

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,