@astryxdesign/core 0.4.4 → 0.4.5-canary.013e728

package/src/Timestamp/tooltipEntries.ts

@@ -24,6 +24,7 @@
 import {devWarn} from '../utils/devWarning';
 import {formatInstant} from './formatInstant';
 import type {InstantFormat} from './formatInstant';
+import type {Locale} from '../i18n/types';
 
 // =============================================================================
 // Types
@@ -130,7 +131,9 @@ function resolveTimezoneID(timezoneID: string | undefined): string | undefined {
   // degrade to the viewer's zone and say so, mirroring how an unparseable
   // `value` is handled in Timestamp.tsx.
   try {
-    new Intl.DateTimeFormat(undefined, {timeZone: timezoneID});
+    // Locale does not affect time-zone identifier validity; pin one so this
+    // validation path stays explicit and deterministic.
+    new Intl.DateTimeFormat('en-US', {timeZone: timezoneID});
   } catch {
     if (!warnedTimezoneIDs.has(timezoneID)) {
       warnedTimezoneIDs.add(timezoneID);
@@ -202,6 +205,7 @@ function shouldShowZoneName(
 export function formatTooltipLines(
   date: Date,
   entries: ReadonlyArray<TimestampTooltipEntry>,
+  locale: Locale,
 ): ReadonlyArray<TimestampTooltipLine> {
   const resolved = entries.map(entry => resolveTimezoneID(entry.timezoneID));
   const hasMultipleZones = new Set(resolved.map(zoneKey)).size > 1;
@@ -213,7 +217,7 @@ export function formatTooltipLines(
     return {
       ...(entry.label === undefined ? {} : {label: entry.label}),
       isCopyable: entry.isCopyable ?? false,
-      value: formatInstant(date, format, {
+      value: formatInstant(date, format, locale, {
         timeZone,
         isTimezoneShown: shouldShowZoneName(
           format,

package/src/Token/Token.tsx

@@ -142,7 +142,7 @@ const styles = stylex.create({
     transitionTimingFunction: easeVars['--ease-standard'],
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,

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.',