@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/src/Tooltip/Tooltip.doc.mjs

@@ -66,6 +66,13 @@ export const docs = {
           description: 'Controls when focus events trigger the tooltip.',
           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 (a button, link, or form control), whose tap belongs to the control. tap always opens; use it for an info icon rendered as a button, whose only job is to reveal the tooltip. none never opens on touch.',
+          default: "'auto'",
+        },
         {
           name: 'isEnabled',
           type: 'boolean',
@@ -103,6 +110,7 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
       {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
+      {guidance: true, description: 'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip, such as an info icon: touch has no hover, and auto keeps the tap for triggers that perform an action.'},
       {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
       {guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
     ],
@@ -165,6 +173,13 @@ export const docsZh = {
           description: '控制聚焦事件何时触发工具提示。',
           default: "'auto'",
         },
+        {
+          name: 'touchTrigger',
+          type: "'auto' | 'tap' | 'none'",
+          description:
+            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有。tap：始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none：触摸永不打开。',
+          default: "'auto'",
+        },
         {
           name: 'isEnabled',
           type: 'boolean',
@@ -202,6 +217,7 @@ export const docsZh = {
     bestPractices: [
       {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
       {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
+      {guidance: true, description: 'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip, such as an info icon: touch has no hover, and auto keeps the tap for triggers that perform an action.'},
       {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
       {guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
     ],
@@ -217,6 +233,7 @@ export const docsDense = {
     bestPractices: [
       {guidance: true, description: 'Keep tooltip content concise: aim for under 140 characters of plain text.'},
       {guidance: true, description: 'Add a tooltip to icon-only buttons and controls that lack a visible label.'},
+      {guidance: true, description: 'Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip, such as an info icon: touch has no hover, and auto keeps the tap for triggers that perform an action.'},
       {guidance: false, description: 'Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.'},
       {guidance: false, description: 'Use tooltips for essential information that users must see to complete a task.'},
     ],
@@ -235,6 +252,7 @@ export const docsDense = {
         delay: 'Show delay in ms.',
         hideDelay: 'Hide delay in ms.',
         focusTrigger: 'Controls when focus events trigger tooltip.',
+        touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control); tap = always opens (info icon rendered as a button); none = never on touch.',
         isEnabled: 'Enables/disables tooltip triggers.',
         onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',
         hasHoverIndication: 'Dashed underline on trigger element.',

package/src/Tooltip/Tooltip.test.tsx

@@ -9,9 +9,18 @@
  * SYNC: When Tooltip.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  beforeEach,
+  afterAll,
+} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {Tooltip} from './Tooltip';
+import {__resetInteractionModalityForTest} from '../utils/interactionModality';
 
 // Store original matches to restore later
 const originalMatches = HTMLElement.prototype.matches;
@@ -267,4 +276,248 @@ describe('Tooltip', () => {
       expect(onOpenChange).not.toHaveBeenCalledWith(false);
     });
   });
+  describe('touch', () => {
+    // The modality is document-global; a tap in one case must not decide the
+    // next one's answer.
+    beforeEach(() => {
+      __resetInteractionModalityForTest();
+    });
+
+    /** A tap: the pointer sequence a finger produces before hover is faked. */
+    const tap = (element: HTMLElement) => {
+      // A finger's arrival fires pointerenter too, and that is the path a pen
+      // must not take — cover it here rather than starting at pointerdown.
+      fireEvent.pointerEnter(element, {pointerType: 'touch'});
+      fireEvent.pointerDown(element, {pointerType: 'touch'});
+      fireEvent.pointerUp(element, {pointerType: 'touch'});
+      // Touch synthesizes hover after the press; the tooltip must not act on it.
+      fireEvent.mouseEnter(element);
+    };
+
+    it('opens on a tap when the trigger performs no action', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={200}>
+          Abbreviation
+        </Tooltip>,
+      );
+
+      tap(screen.getByText('Abbreviation'));
+
+      // Immediately: a tap is a decision, not hover intent, so no delay applies.
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+
+    it('stays shut on a tap when the trigger performs an action', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Save</button>
+        </Tooltip>,
+      );
+
+      tap(screen.getByRole('button', {name: 'Save'}));
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(true);
+    });
+
+    it('opens on a tap of an action trigger when touchTrigger is "tap"', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip
+          content="What this metric means"
+          onOpenChange={onOpenChange}
+          touchTrigger="tap"
+          delay={0}>
+          <button type="button">Info</button>
+        </Tooltip>,
+      );
+
+      tap(screen.getByRole('button', {name: 'Info'}));
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+
+    it('never opens on a tap when touchTrigger is "none"', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip
+          content="Tooltip text"
+          onOpenChange={onOpenChange}
+          touchTrigger="none"
+          delay={0}>
+          Abbreviation
+        </Tooltip>,
+      );
+
+      tap(screen.getByText('Abbreviation'));
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(true);
+    });
+
+    it('closes on a second tap of the trigger', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
+          Abbreviation
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByText('Abbreviation');
+      tap(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+
+      tap(trigger);
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('closes on a tap outside — the dismissal a tap-open owes the user', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <>
+          <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
+            Abbreviation
+          </Tooltip>
+          <button type="button">Elsewhere</button>
+        </>,
+      );
+
+      tap(screen.getByText('Abbreviation'));
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+
+      fireEvent.pointerDown(screen.getByRole('button', {name: 'Elsewhere'}), {
+        pointerType: 'touch',
+      });
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(false);
+      });
+    });
+
+    it('still opens on a real mouse hover after a tap', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Save</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Save'});
+      tap(trigger);
+      await new Promise(resolve => setTimeout(resolve, 20));
+      expect(onOpenChange).not.toHaveBeenCalledWith(true);
+
+      // A hybrid device: the same trigger, now under a mouse.
+      fireEvent.pointerEnter(trigger, {pointerType: 'mouse'});
+      fireEvent.mouseEnter(trigger);
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+
+    it('opens on a hovering pen, which is a hover and not a tap', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
+          <button type="button">Save</button>
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByRole('button', {name: 'Save'});
+      // A stylus in detection range: pointerenter with nothing in contact, on
+      // a device where `(hover: hover)` matches. Reading that as touch would
+      // bail out of the hover path and leave the user no tooltip at all.
+      fireEvent.pointerEnter(trigger, {pointerType: 'pen', buttons: 0});
+      fireEvent.mouseEnter(trigger);
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+
+    it('tap-opens when a pen lands on an inert trigger', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={200}>
+          Abbreviation
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByText('Abbreviation');
+      // Hovering first, as a real pen does — then contact, which is a tap.
+      fireEvent.pointerEnter(trigger, {pointerType: 'pen', buttons: 0});
+      fireEvent.pointerDown(trigger, {pointerType: 'pen'});
+      fireEvent.pointerUp(trigger, {pointerType: 'pen'});
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+
+    it('does not reopen from the focus a tapped text field takes', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
+          <input type="text" aria-label="Amount" />
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByLabelText('Amount');
+      // A tapped text field matches `:focus-visible` in a real browser —
+      // deliberately, per Selectors 4, so typing has a visible home. jsdom
+      // does not model that, so stand it up here; without it this case cannot
+      // fail, whatever the focus path does.
+      const realMatches = trigger.matches.bind(trigger);
+      vi.spyOn(trigger, 'matches').mockImplementation((selector: string) =>
+        selector === ':focus-visible' ? true : realMatches(selector),
+      );
+
+      // An `<input>` is an action trigger, so `auto` gives it the tap — and
+      // the focus it takes must not put the tooltip back over the field the
+      // user is about to type into.
+      tap(trigger);
+      fireEvent.focusIn(trigger);
+
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(onOpenChange).not.toHaveBeenCalledWith(true);
+    });
+
+    it('still opens on keyboard focus of a trigger a finger touched', async () => {
+      const onOpenChange = vi.fn();
+      render(
+        <Tooltip content="Tooltip text" onOpenChange={onOpenChange} delay={0}>
+          <input type="text" aria-label="Amount" />
+        </Tooltip>,
+      );
+
+      const trigger = screen.getByLabelText('Amount');
+      const realMatches = trigger.matches.bind(trigger);
+      vi.spyOn(trigger, 'matches').mockImplementation((selector: string) =>
+        selector === ':focus-visible' ? true : realMatches(selector),
+      );
+
+      tap(trigger);
+      // Reaching for the keyboard ends the touch interaction; the guard is on
+      // the gesture in flight, not on the device the trigger last saw.
+      fireEvent.keyDown(document, {key: 'Tab'});
+      fireEvent.focusIn(trigger);
+
+      await waitFor(() => {
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+      });
+    });
+  });
 });

package/src/Tooltip/Tooltip.tsx

@@ -22,11 +22,15 @@ import React, {
 } from 'react';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
-import {useTooltip, type TooltipFocusTrigger} from './useTooltip';
+import {
+  useTooltip,
+  type TooltipFocusTrigger,
+  type TooltipTouchTrigger,
+} from './useTooltip';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {colorVars} from '../theme/tokens.stylex';
 
-export type {TooltipFocusTrigger} from './useTooltip';
+export type {TooltipFocusTrigger, TooltipTouchTrigger} from './useTooltip';
 
 const styles = stylex.create({
   wrapperContents: {
@@ -99,6 +103,20 @@ export interface TooltipProps {
    */
   focusTrigger?: TooltipFocusTrigger;
 
+  /**
+   * What a tap does on a touch pointer, where there is no hover:
+   * - `auto`: tap opens the tooltip, unless the trigger performs an action of
+   *   its own (a button, a link, a form control) — that tap belongs to the
+   *   control, and a hint about a control the user just operated is noise
+   * - `tap`: tap always opens the tooltip. This is what an info icon rendered
+   *   as a button wants: it looks like an action to the DOM, but revealing the
+   *   tooltip is the only thing it does
+   * - `none`: touch never opens the tooltip
+   *
+   * @default 'auto'
+   */
+  touchTrigger?: TooltipTouchTrigger;
+
   /**
    * Whether the tooltip is enabled.
    * When false, hover/focus triggers are disabled.
@@ -176,6 +194,7 @@ export function Tooltip({
   delay = 200,
   hideDelay = 0,
   focusTrigger = 'auto',
+  touchTrigger = 'auto',
   isEnabled = true,
   onOpenChange,
   hasHoverIndication = 'auto',
@@ -204,6 +223,7 @@ export function Tooltip({
     delay,
     hideDelay,
     focusTrigger,
+    touchTrigger,
     isEnabled,
     isOpen,
     isDefaultOpen,

package/src/Tooltip/index.ts

@@ -15,6 +15,7 @@
 export {useTooltip} from './useTooltip';
 export type {
   TooltipFocusTrigger,
+  TooltipTouchTrigger,
   TooltipOptions,
   TooltipReturn,
 } from './useTooltip';

package/src/Tooltip/useTooltip.doc.mjs

@@ -12,6 +12,7 @@ export const docs = {
     {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 only attaches focus listeners to naturally focusable elements.', 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; tap always opens (an info icon rendered as a button); 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'},
@@ -49,6 +50,7 @@ export const docsDense = {
     delay: 'show delay in ms.',
     hideDelay: 'hide delay after mouse/focus leave in ms.',
     focusTrigger: 'when focus opens tooltip; auto = naturally focusable elements only.',
+    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.',
     isDefaultOpen: 'show on mount.',

package/src/Tooltip/useTooltip.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file useTooltip.tsx
- * @input Uses useLayer, React hooks
- * @output Exports useTooltip hook for hover/focus triggered tooltips
+ * @input Uses useLayer, useTouchTrigger, React hooks
+ * @output Exports useTooltip hook for hover/focus/tap triggered tooltips
  * @position Layer hook; builds on useLayer for tooltip behavior
  *
  * SYNC: When modified, update:
@@ -26,6 +26,10 @@ import {
   type LayerAlignment,
   type LayerPlacement,
 } from '../Layer/useLayer';
+import {
+  useTouchTrigger,
+  type LayerTouchTrigger,
+} from '../Layer/useTouchTrigger';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {themeProps} from '../utils/themeProps';
 import {isImeKeyEvent} from '../utils/ime';
@@ -73,6 +77,11 @@ const styles = stylex.create({
  */
 export type TooltipFocusTrigger = 'auto' | 'always' | 'never';
 
+/**
+ * Touch trigger behavior for tooltips
+ */
+export type TooltipTouchTrigger = LayerTouchTrigger;
+
 export interface TooltipOptions {
   /**
    * Position placement relative to anchor
@@ -108,6 +117,20 @@ export interface TooltipOptions {
    */
   focusTrigger?: TooltipFocusTrigger;
 
+  /**
+   * What a tap does on a touch pointer, where there is no hover:
+   * - `auto`: tap opens the tooltip, unless the trigger performs an action of
+   *   its own (a button, a link, a form control) — that tap belongs to the
+   *   control, and a hint about a control the user just operated is noise
+   * - `tap`: tap always opens the tooltip. This is what an info icon rendered
+   *   as a button wants: it looks like an action to the DOM, but revealing the
+   *   tooltip is the only thing it does
+   * - `none`: touch never opens the tooltip
+   *
+   * @default 'auto'
+   */
+  touchTrigger?: TooltipTouchTrigger;
+
   /**
    * Whether the tooltip is enabled.
    * When false, hover/focus triggers are disabled.
@@ -218,6 +241,7 @@ function isFocusable(element: HTMLElement): boolean {
  * Builds on useLayer to add:
  * - Hover triggers with configurable delay
  * - Focus triggers with auto-detection for focusable elements
+ * - Tap triggers on touch, where there is no hover (see useTouchTrigger)
  * - Inverted color palette for high contrast
  *
  * Unlike HoverCard, tooltips:
@@ -242,6 +266,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     delay = 200,
     hideDelay = 0,
     focusTrigger = 'auto',
+    touchTrigger = 'auto',
     isEnabled = true,
     isOpen,
     isDefaultOpen = false,
@@ -273,6 +298,29 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     }
   }, []);
 
+  // Touch resolves immediately: the hover delays exist to filter out a pointer
+  // passing across the trigger, and a tap is never that.
+  const showNow = useCallback(() => {
+    clearTimeouts();
+    layer.show();
+  }, [clearTimeouts, layer]);
+
+  const hideNow = useCallback(() => {
+    clearTimeouts();
+    layer.hide();
+  }, [clearTimeouts, layer]);
+
+  const touch = useTouchTrigger({
+    touchTrigger,
+    isEnabled,
+    isControlled: isOpen !== undefined,
+    isOpen: layer.isOpen,
+    layerId: layer.id,
+    triggerRef,
+    show: showNow,
+    hide: hideNow,
+  });
+
   // Schedule show with delay (suppressed when isOpen is false)
   const scheduleShow = useCallback(() => {
     if (!isEnabled || isOpen === false) {
@@ -309,26 +357,38 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
 
   // Event handlers
   const handleMouseEnter = useCallback(() => {
-    // Suppress tooltips on touch devices — hover is simulated and eats a tap
-    if (
-      typeof window !== 'undefined' &&
-      typeof window.matchMedia === 'function' &&
-      window.matchMedia('(hover: none)').matches
-    ) {
+    // A tap synthesizes mouseenter. On touch the tap path owns the decision,
+    // so hover must not also fire — including the tap that just opened the
+    // tooltip, which would otherwise be double-handled.
+    if (touch.isTouchPointerRef.current) {
       return;
     }
     scheduleShow();
-  }, [scheduleShow]);
+  }, [touch, scheduleShow]);
 
   const handleMouseLeave = useCallback(() => {
+    // On touch the synthesized mouseleave arrives with the next tap elsewhere,
+    // which the outside-tap dismissal already handles — and handling it here
+    // too would close the tooltip behind the tap-open bookkeeping's back.
+    if (touch.isTouchPointerRef.current) {
+      return;
+    }
     scheduleHide();
-  }, [scheduleHide]);
+  }, [touch, scheduleHide]);
 
   const handleFocusIn = useCallback(
     (e: Event) => {
       if (!isEnabled) {
         return;
       }
+      // A tap focuses the trigger it activates, and `:focus-visible` does not
+      // filter that out on every element: a tapped `<input>` or contenteditable
+      // matches it. Those are exactly the action triggers `auto` just decided
+      // to keep shut, so without this the focus reopens what the tap
+      // suppressed, over the field the user is trying to type into.
+      if (touch.isTouchInteraction()) {
+        return;
+      }
       // Only show tooltip for keyboard focus (:focus-visible),
       // not programmatic focus (e.g. dialog auto-focus, touch tap)
       const target = e.target as HTMLElement;
@@ -338,7 +398,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       clearTimeouts();
       layer.show();
     },
-    [isEnabled, clearTimeouts, layer],
+    [isEnabled, touch, clearTimeouts, layer],
   );
 
   const handleFocusOut = useCallback(() => {
@@ -350,15 +410,24 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // just-pressed control reads as stale. Fires on pointerdown so it feels
   // immediate. Uncontrolled tooltips only — a controlled tooltip's visibility
   // is owned by the consumer. `layer.hide()` self-guards when already closed.
-  const handlePointerDown = useCallback(() => {
-    if (isOpen !== undefined) {
-      return;
-    }
-    clearTimeouts();
-    layer.hide();
-  }, [isOpen, clearTimeouts, layer]);
+  // 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.
+  const handlePointerDown = useCallback(
+    (event: PointerEvent) => {
+      if (touch.handlePointerDown(event)) {
+        return;
+      }
+      if (isOpen !== undefined) {
+        return;
+      }
+      clearTimeouts();
+      layer.hide();
+    },
+    [touch, isOpen, clearTimeouts, layer],
+  );
 
   // Interaction ref that handles event listeners only
+  const {handlePointerEnter, clearTapOpen} = touch;
   const interactionRef: RefCallback<HTMLElement> = useCallback(
     (el: HTMLElement | null) => {
       // Cleanup previous element
@@ -367,6 +436,10 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         triggerRef.current.removeEventListener('mouseleave', handleMouseLeave);
         triggerRef.current.removeEventListener('focusin', handleFocusIn);
         triggerRef.current.removeEventListener('focusout', handleFocusOut);
+        triggerRef.current.removeEventListener(
+          'pointerenter',
+          handlePointerEnter,
+        );
         triggerRef.current.removeEventListener(
           'pointerdown',
           handlePointerDown,
@@ -374,10 +447,13 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       }
 
       if (el) {
-        // Attach hover listeners
+        // Attach hover listeners. `pointerenter` runs before the synthesized
+        // `mouseenter` a tap produces, which is what lets the hover path know
+        // it is looking at a finger.
+        el.addEventListener('pointerenter', handlePointerEnter);
         el.addEventListener('mouseenter', handleMouseEnter);
         el.addEventListener('mouseleave', handleMouseLeave);
-        // Press-to-dismiss: activating the trigger hides its own tooltip.
+        // Press-to-dismiss on a mouse; tap-to-open on a touch pointer.
         el.addEventListener('pointerdown', handlePointerDown);
 
         // Attach focus listeners based on focusTrigger option
@@ -399,6 +475,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       handleMouseLeave,
       handleFocusIn,
       handleFocusOut,
+      handlePointerEnter,
       handlePointerDown,
     ],
   );
@@ -461,13 +538,14 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
         return;
       }
       clearTimeouts();
+      clearTapOpen();
       layer.hide();
     };
     document.addEventListener('keydown', handleKeyDown);
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
     };
-  }, [isOpen, layer, clearTimeouts]);
+  }, [isOpen, layer, clearTimeouts, clearTapOpen]);
 
   // Render function that wraps layer.render with tooltip styling
   const renderTooltip = useCallback(