@multiplatform.one/components 7.4.1 → 7.5.0

package/src/Tooltip/Tooltip.spec.tsx

@@ -3,13 +3,14 @@
  */
 
 import { fireEvent } from "@testing-library/react";
-import { __resetDevWarnSeen } from "@multiplatform.one/theme";
+import { OVERLAY_ANCHOR_GAP, __resetDevWarnSeen } from "@multiplatform.one/theme";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { Button } from "@multiplatform.one/forms";
 import {
   Tooltip,
   __resetTooltipSkipForTests,
+  createNativeTooltipPressHandlers,
   noteTooltipClosed,
   resolveTooltipDelay,
   resolveTooltipPadRecipe,
@@ -18,7 +19,7 @@ import {
   tooltipSizeRecipes,
   TOOLTIP_COLLISION_PADDING_PX,
   TOOLTIP_DEFAULT_DELAY_MS,
-  TOOLTIP_OFFSET_PX,
+  TOOLTIP_NATIVE_LONG_PRESS_MS,
   TOOLTIP_SKIP_DELAY_MS,
 } from "./index";
 
@@ -42,7 +43,7 @@ describe("Tooltip size vs space recipes", () => {
   it("nested bubble recipes stay below the 44px press floor", () => {
     expect(tooltipSizeRecipes.medium.maxWidth).toBeGreaterThan(44);
     expect(tooltipPadRecipes.medium.paddingVertical).not.toBe("$4");
-    expect(TOOLTIP_OFFSET_PX).toBe(4);
+    expect(OVERLAY_ANCHOR_GAP).toBe(4);
     expect(TOOLTIP_COLLISION_PADDING_PX).toBe(8);
   });
 });
@@ -97,3 +98,47 @@ describe("Tooltip interaction", () => {
     expect(onOpenChange).toHaveBeenCalledWith(false);
   });
 });
+
+describe("Tooltip native long-press open path", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("opens after the ~500ms press-in delay and closes on press-out", () => {
+    const setOpen = vi.fn();
+    const press = createNativeTooltipPressHandlers(setOpen, TOOLTIP_NATIVE_LONG_PRESS_MS);
+    press.pressIn();
+    vi.advanceTimersByTime(TOOLTIP_NATIVE_LONG_PRESS_MS - 1);
+    expect(setOpen).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(setOpen).toHaveBeenCalledWith(true);
+    press.pressOut();
+    expect(setOpen).toHaveBeenLastCalledWith(false);
+    press.dispose();
+  });
+
+  it("cancels a pending press-in when the finger lifts early", () => {
+    const setOpen = vi.fn();
+    const press = createNativeTooltipPressHandlers(setOpen);
+    press.pressIn();
+    press.pressOut();
+    vi.advanceTimersByTime(TOOLTIP_NATIVE_LONG_PRESS_MS);
+    expect(setOpen).toHaveBeenCalledTimes(1);
+    expect(setOpen).toHaveBeenCalledWith(false);
+    press.dispose();
+  });
+
+  it("opens on long-press and closes on tap outside", () => {
+    const setOpen = vi.fn();
+    const press = createNativeTooltipPressHandlers(setOpen);
+    press.longPress();
+    expect(setOpen).toHaveBeenCalledWith(true);
+    press.tapOutside();
+    expect(setOpen).toHaveBeenLastCalledWith(false);
+    press.dispose();
+  });
+});

package/src/Tooltip/Tooltip.stories.tsx

@@ -1,9 +1,12 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { PrinterIcon } from "@phosphor-icons/react";
 import { Button } from "@multiplatform.one/forms";
+import { Platform } from "react-native";
 import { YStack, XStack } from "tamagui";
 import { Tooltip } from "./index";
 
+const triggerLabel = Platform.OS === "web" ? "Hover me" : "Long-press me";
+
 const meta: Meta<typeof Tooltip> = {
   title: "Components/Tooltip",
   component: Tooltip,
@@ -20,7 +23,7 @@ export const Default: Story = {
   render: () => (
     <YStack padding="$8" alignItems="center">
       <Tooltip content="This is a tooltip">
-        <Button>Hover me</Button>
+        <Button>{triggerLabel}</Button>
       </Tooltip>
     </YStack>
   ),

package/src/Tooltip/index.native.tsx

@@ -0,0 +1,205 @@
+/**
+ * Tooltip (native) — same bubble API as web, opened by long-press.
+ *
+ * Tamagui Tooltip is hover+delay; there is no hover on device. This twin
+ * opens after a ~500ms press-in (or `onLongPress`) and closes on press-out
+ * or tap outside. The trigger stays the caller's press target (LC-71). The
+ * bubble stays nested-scale — never a Sheet, never the 44px press floor.
+ */
+
+import { zIndex } from "@multiplatform.one/forms";
+import {
+  OVERLAY_ANCHOR_GAP,
+  useResolvedKnobs,
+  warnTooltipOnDisabled,
+} from "@multiplatform.one/theme";
+import React from "react";
+import { Pressable, StyleSheet } from "react-native";
+import {
+  Tooltip as TamaguiTooltip,
+  TooltipGroup as TamaguiTooltipGroup,
+  Portal,
+  useTheme,
+  type GetProps,
+} from "tamagui";
+import { TOOLTIP_NATIVE_LONG_PRESS_MS, createNativeTooltipPressHandlers } from "./nativePress";
+import {
+  TooltipArrow,
+  TooltipContent,
+  TooltipText,
+  noteTooltipClosed,
+  preventTooltipFocus,
+  resolveThemeColor,
+  resolveTooltipPadRecipe,
+  resolveTooltipSizeRecipe,
+  wrapTooltipContent,
+  type TooltipProps,
+} from "./tooltipShared";
+
+export type { TooltipProps, TooltipSizeRecipe } from "./tooltipShared";
+export {
+  tooltipSizeRecipes,
+  tooltipPadRecipes,
+  TOOLTIP_COLLISION_PADDING_PX,
+  TOOLTIP_SKIP_DELAY_MS,
+  TOOLTIP_DEFAULT_DELAY_MS,
+  noteTooltipClosed,
+  resolveTooltipDelay,
+  resolveTooltipSizeRecipe,
+  resolveTooltipPadRecipe,
+  __resetTooltipSkipForTests,
+  wrapTooltipContent,
+  TooltipContent,
+  TooltipArrow,
+  TooltipText,
+} from "./tooltipShared";
+export { TOOLTIP_NATIVE_LONG_PRESS_MS, createNativeTooltipPressHandlers } from "./nativePress";
+export type { NativeTooltipPressHandlers } from "./nativePress";
+
+type PressHandler = ((event: unknown) => void) | undefined;
+
+export function Tooltip({
+  children,
+  content,
+  placement = "top",
+  delay = TOOLTIP_NATIVE_LONG_PRESS_MS,
+  disabled = false,
+  open: openProp,
+  onOpenChange: onOpenChangeProp,
+}: TooltipProps) {
+  const { knobProps } = useResolvedKnobs({ component: "Tooltip" });
+  const theme = useTheme();
+  const surfaceFill = resolveThemeColor(theme.color1, "$color1");
+  const pad = resolveTooltipPadRecipe(knobProps.space);
+  const sizeRecipe = resolveTooltipSizeRecipe(knobProps.size);
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(false);
+  const isControlled = openProp !== undefined;
+  const open = isControlled ? openProp : uncontrolledOpen;
+  const [outsideArmed, setOutsideArmed] = React.useState(false);
+
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (!isControlled) setUncontrolledOpen(next);
+      onOpenChangeProp?.(next);
+      if (!next) noteTooltipClosed();
+    },
+    [isControlled, onOpenChangeProp],
+  );
+
+  const press = React.useMemo(
+    () => createNativeTooltipPressHandlers(setOpen, delay),
+    [setOpen, delay],
+  );
+  React.useEffect(() => () => press.dispose(), [press]);
+
+  React.useEffect(() => {
+    if (!open) {
+      setOutsideArmed(false);
+      return;
+    }
+    const arm = setTimeout(() => setOutsideArmed(true), 50);
+    return () => clearTimeout(arm);
+  }, [open]);
+
+  if (React.isValidElement(children)) {
+    const childProps = (children as React.ReactElement<Record<string, unknown>>).props;
+    const childDisabled =
+      childProps.disabled === true ||
+      childProps["aria-disabled"] === true ||
+      childProps["aria-disabled"] === "true";
+    warnTooltipOnDisabled({
+      component: "Tooltip",
+      childDisabled,
+    });
+  }
+
+  const trigger = React.isValidElement(children)
+    ? React.cloneElement(children as React.ReactElement<Record<string, unknown>>, {
+        delayLongPress: delay,
+        onPressIn: (event: unknown) => {
+          (children.props as { onPressIn?: PressHandler }).onPressIn?.(event);
+          press.pressIn();
+        },
+        onPressOut: (event: unknown) => {
+          (children.props as { onPressOut?: PressHandler }).onPressOut?.(event);
+          press.pressOut();
+        },
+        onLongPress: (event: unknown) => {
+          (children.props as { onLongPress?: PressHandler }).onLongPress?.(event);
+          press.longPress();
+        },
+      })
+    : children;
+
+  if (disabled) {
+    return <>{children}</>;
+  }
+
+  const elevated = knobProps.elevatedSurface;
+
+  return (
+    <>
+      {open ? (
+        <Portal>
+          <Pressable
+            accessibilityLabel="Dismiss tooltip"
+            disabled={!outsideArmed}
+            onPress={() => {
+              if (outsideArmed) press.tapOutside();
+            }}
+            style={[StyleSheet.absoluteFill, { zIndex: zIndex.dropdown - 1 }]}
+          />
+        </Portal>
+      ) : null}
+      <TamaguiTooltip
+        placement={placement}
+        delay={0}
+        restMs={0}
+        offset={OVERLAY_ANCHOR_GAP}
+        zIndex={zIndex.dropdown}
+        open={open}
+        onOpenChange={setOpen}
+      >
+        <TamaguiTooltip.Trigger asChild>{trigger}</TamaguiTooltip.Trigger>
+        <TooltipContent
+          {...elevated}
+          paddingHorizontal={pad.paddingHorizontal as never}
+          paddingVertical={pad.paddingVertical as never}
+          maxWidth={sizeRecipe.maxWidth}
+          transition={knobProps.transition}
+          role="tooltip"
+          data-tooltip="content"
+          data-tooltip-size={knobProps.size}
+          data-tooltip-space={knobProps.space}
+          data-tooltip-density={knobProps.density}
+          data-tooltip-fill={surfaceFill}
+          pointerEvents="none"
+          onOpenAutoFocus={preventTooltipFocus}
+          onCloseAutoFocus={preventTooltipFocus}
+        >
+          <TooltipArrow
+            backgroundColor={surfaceFill}
+            borderColor={surfaceFill}
+            style={{ backgroundColor: surfaceFill, borderColor: surfaceFill }}
+          />
+          {wrapTooltipContent(content, {
+            ...knobProps.body,
+            ...knobProps.label,
+            color: "$color12",
+            lineHeight: knobProps.label.fontSize,
+          })}
+        </TooltipContent>
+      </TamaguiTooltip>
+    </>
+  );
+}
+
+Tooltip.Content = TooltipContent;
+Tooltip.Arrow = TooltipArrow;
+Tooltip.Text = TooltipText;
+Tooltip.Trigger = TamaguiTooltip.Trigger;
+Tooltip.Group = TamaguiTooltipGroup;
+
+export type TooltipContentProps = GetProps<typeof TooltipContent>;
+export type TooltipArrowProps = GetProps<typeof TooltipArrow>;
+export type TooltipTextProps = GetProps<typeof TooltipText>;

package/src/Tooltip/index.tsx

@@ -1,182 +1,63 @@
 /**
  * Tooltip — compact, non-interactive overlay (Radix / Primer / Polaris / Spectrum).
  *
- * Opens on hover (with warmup) and keyboard focus; closes on leave, blur,
- * Escape, and trigger activation. Content is hoverable (WCAG 1.4.13) but
- * never a tab stop — the trigger keeps the LC-71 ring. Size drives type and
- * max-width; space/density drive inset. The bubble stays nested-scale (below
- * the 44px press floor); the trigger is the caller's contract.
+ * Web: opens on hover (with warmup) and keyboard focus; closes on leave, blur,
+ * Escape, and trigger activation. Native twin (`index.native.tsx`) opens on
+ * long-press (~500ms) and closes on press-out or tap outside.
+ *
+ * Content is hoverable (WCAG 1.4.13) but never a tab stop — the trigger keeps
+ * the LC-71 ring. Size drives type and max-width; space/density drive inset.
+ * The bubble stays nested-scale (below the 44px press floor); the trigger is
+ * the caller's contract.
  */
 
 import { zIndex } from "@multiplatform.one/forms";
-import { useResolvedKnobs, warnTooltipOnDisabled } from "@multiplatform.one/theme";
-import type { ReactNode } from "react";
+import {
+  OVERLAY_ANCHOR_GAP,
+  useResolvedKnobs,
+  warnTooltipOnDisabled,
+} from "@multiplatform.one/theme";
 import React from "react";
 import {
   Tooltip as TamaguiTooltip,
   TooltipGroup as TamaguiTooltipGroup,
-  Text,
-  styled,
   useTheme,
   type GetProps,
 } from "tamagui";
-import { wrapBareTextChildren } from "../shared/textRidesText";
-
-// ── Types ─────────────────────────────────────────────────────
-
-export interface TooltipProps {
-  /** The element that triggers the tooltip */
-  children: ReactNode;
-  /** The tooltip content - can be a string or ReactNode */
-  content: ReactNode;
-  /** Placement of the tooltip relative to trigger */
-  placement?: "top" | "bottom" | "left" | "right";
-  /** Delay before showing tooltip in ms (hover warmup; keyboard is immediate) */
-  delay?: number;
-  /** Whether the tooltip is disabled */
-  disabled?: boolean;
-  /** Controlled open. Omit for hover/focus-driven open. */
-  open?: boolean;
-  /** Fired whenever open changes (controlled or internal). */
-  onOpenChange?: (open: boolean) => void;
-}
-
-// ── Size / space recipes (density ≠ size) ─────────────────────
-// Size: type + wrap width (Spectrum size-2000 / Primer 250px multiline).
-// Space: compact overlay inset — not panelPadding (dialog-scale).
-
-export interface TooltipSizeRecipe {
-  maxWidth: number;
-}
-
-export const tooltipSizeRecipes: Record<"small" | "medium" | "large", TooltipSizeRecipe> = {
-  small: { maxWidth: 160 },
-  medium: { maxWidth: 250 },
-  large: { maxWidth: 320 },
-};
-
-export const tooltipPadRecipes: Record<
-  "small" | "medium" | "large",
-  { paddingHorizontal: string; paddingVertical: string }
-> = {
-  small: { paddingHorizontal: "$1.5", paddingVertical: "$1" },
-  medium: { paddingHorizontal: "$2", paddingVertical: "$1.5" },
-  large: { paddingHorizontal: "$3", paddingVertical: "$2" },
-};
-
-/** Spectrum offset (tip → trigger). */
-export const TOOLTIP_OFFSET_PX = 4;
-/** Spectrum container padding so the bubble stays inside the viewport. */
-export const TOOLTIP_COLLISION_PADDING_PX = 8;
-/** Radix skipDelayDuration / Spectrum cooldown — next tooltip opens instantly. */
-export const TOOLTIP_SKIP_DELAY_MS = 300;
-/** Primer/Spectrum hover warmup when not in the skip window. */
-export const TOOLTIP_DEFAULT_DELAY_MS = 300;
-
-let tooltipSkipUntil = 0;
-const tooltipSkipListeners = new Set<() => void>();
-
-export function noteTooltipClosed(now = Date.now()): void {
-  tooltipSkipUntil = now + TOOLTIP_SKIP_DELAY_MS;
-  for (const listener of tooltipSkipListeners) listener();
-}
-
-export function resolveTooltipDelay(delay: number, now = Date.now()): number {
-  return now < tooltipSkipUntil ? 0 : delay;
-}
-
-export function resolveTooltipSizeRecipe(size: string): TooltipSizeRecipe {
-  return tooltipSizeRecipes[size as keyof typeof tooltipSizeRecipes] ?? tooltipSizeRecipes.medium;
-}
-
-export function resolveTooltipPadRecipe(space: string): {
-  paddingHorizontal: string;
-  paddingVertical: string;
-} {
-  return tooltipPadRecipes[space as keyof typeof tooltipPadRecipes] ?? tooltipPadRecipes.medium;
-}
-
-/** @internal tests */
-export function __resetTooltipSkipForTests(): void {
-  tooltipSkipUntil = 0;
-}
-
-function useTooltipSkipDelay(delay: number): number {
-  const [, bump] = React.useState(0);
-  React.useEffect(() => {
-    const listener = () => bump((n) => n + 1);
-    tooltipSkipListeners.add(listener);
-    return () => {
-      tooltipSkipListeners.delete(listener);
-    };
-  }, []);
-  return resolveTooltipDelay(delay);
-}
-
-// ── Styled components ─────────────────────────────────────────
-
-const TooltipContent = styled(TamaguiTooltip.Content, {
-  name: "TooltipContent",
-  // Surface, radius, elevation, pad, and type come from knob recipes on
-  // the instance (LC-18). enterStyle/exitStyle need a transition token (LC-24).
-  opacity: 1,
-  enterStyle: {
-    opacity: 0,
-    y: -4,
-    scale: 0.96,
-  },
-  exitStyle: {
-    opacity: 0,
-    y: -4,
-    scale: 0.96,
-  },
-});
-
-const TooltipArrow = styled(TamaguiTooltip.Arrow, {
-  name: "TooltipArrow",
-  backgroundColor: "$color1",
-  borderColor: "$color1",
-});
-
-const TooltipText = styled(Text, {
-  name: "TooltipText",
-});
-
-/**
- * The Tooltip content slot (exported for spec). LC-82 TEXT-RIDES-TEXT: wrap
- * ALL bare string/number content (coalesced runs), not just the singleton
- * case — an array like `{label}{cond ? suffix : ""}` renders web-only and
- * crashes native otherwise.
- */
-export function wrapTooltipContent(
-  content: ReactNode,
-  bodyProps: Record<string, unknown>,
-): ReactNode {
-  return wrapBareTextChildren(content, (label, key) => (
-    <TooltipText key={key} {...bodyProps}>
-      {label}
-    </TooltipText>
-  ));
-}
-
-function resolveThemeColor(
-  token: { get?: () => string; val?: string } | undefined,
-  fallback: string,
-): string {
-  const raw = token?.val ?? token?.get?.() ?? fallback;
-  if (typeof raw === "string" && raw.startsWith("var(") && typeof document !== "undefined") {
-    const name = raw.slice(4, -1).trim();
-    const value = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
-    if (value) return value;
-  }
-  return typeof raw === "string" ? raw : fallback;
-}
-
-function preventTooltipFocus(event: { preventDefault?: () => void }) {
-  event.preventDefault?.();
-}
-
-// ── Tooltip Component ─────────────────────────────────────────
+import {
+  TooltipArrow,
+  TooltipContent,
+  TooltipText,
+  noteTooltipClosed,
+  preventTooltipFocus,
+  resolveThemeColor,
+  resolveTooltipPadRecipe,
+  resolveTooltipSizeRecipe,
+  useTooltipSkipDelay,
+  wrapTooltipContent,
+  TOOLTIP_DEFAULT_DELAY_MS,
+  type TooltipProps,
+} from "./tooltipShared";
+
+export type { TooltipProps, TooltipSizeRecipe } from "./tooltipShared";
+export {
+  tooltipSizeRecipes,
+  tooltipPadRecipes,
+  TOOLTIP_COLLISION_PADDING_PX,
+  TOOLTIP_SKIP_DELAY_MS,
+  TOOLTIP_DEFAULT_DELAY_MS,
+  noteTooltipClosed,
+  resolveTooltipDelay,
+  resolveTooltipSizeRecipe,
+  resolveTooltipPadRecipe,
+  __resetTooltipSkipForTests,
+  wrapTooltipContent,
+  TooltipContent,
+  TooltipArrow,
+  TooltipText,
+} from "./tooltipShared";
+export { TOOLTIP_NATIVE_LONG_PRESS_MS, createNativeTooltipPressHandlers } from "./nativePress";
+export type { NativeTooltipPressHandlers } from "./nativePress";
 
 export function Tooltip({
   children,
@@ -267,7 +148,7 @@ export function Tooltip({
       placement={placement}
       delay={{ open: delayMs, close: 0 }}
       restMs={100}
-      offset={TOOLTIP_OFFSET_PX}
+      offset={OVERLAY_ANCHOR_GAP}
       zIndex={zIndex.dropdown}
       open={open}
       onOpenChange={setOpen}
@@ -305,7 +186,6 @@ export function Tooltip({
   );
 }
 
-// Re-export parts for advanced usage
 Tooltip.Content = TooltipContent;
 Tooltip.Arrow = TooltipArrow;
 Tooltip.Text = TooltipText;

package/src/Tooltip/nativePress.ts

@@ -0,0 +1,53 @@
+/**
+ * Native Tooltip press session — long-press (~500ms) / press-in after delay
+ * opens; press-out or tap-outside closes. Extracted so jsdom can cover the
+ * open path without a React Native runtime.
+ */
+
+export const TOOLTIP_NATIVE_LONG_PRESS_MS = 500;
+
+export interface NativeTooltipPressHandlers {
+  pressIn: () => void;
+  pressOut: () => void;
+  longPress: () => void;
+  tapOutside: () => void;
+  dispose: () => void;
+}
+
+export function createNativeTooltipPressHandlers(
+  setOpen: (open: boolean) => void,
+  delayMs: number = TOOLTIP_NATIVE_LONG_PRESS_MS,
+): NativeTooltipPressHandlers {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const clearTimer = () => {
+    if (timer == null) return;
+    clearTimeout(timer);
+    timer = null;
+  };
+
+  return {
+    pressIn() {
+      clearTimer();
+      timer = setTimeout(() => {
+        timer = null;
+        setOpen(true);
+      }, delayMs);
+    },
+    pressOut() {
+      clearTimer();
+      setOpen(false);
+    },
+    longPress() {
+      clearTimer();
+      setOpen(true);
+    },
+    tapOutside() {
+      clearTimer();
+      setOpen(false);
+    },
+    dispose() {
+      clearTimer();
+    },
+  };
+}