@multiplatform.one/components 7.4.1 → 7.6.0

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();
+    },
+  };
+}

package/src/Tooltip/tooltipGapContract.spec.ts

@@ -0,0 +1,54 @@
+/**
+ * MPO-38 AC-7, the source half: Tooltip owns no gap constant of its own.
+ *
+ * The runtime value is asserted where it lives — `layoutTokens.spec.ts` pins
+ * `OVERLAY_ANCHOR_GAP` at 4. Asserting that number again from a Tooltip spec
+ * proves nothing about Tooltip: it passes just as happily if this component
+ * goes back to a hardcoded `offset={4}`, which is exactly the drift the AC
+ * was written to close.
+ *
+ * So this is the source half, in the shape of `panelWidthContract.spec.ts`.
+ * A Tooltip is a FREE overlay — no trigger to attach to — so it is one of the
+ * few overlays `OVERLAY_ANCHOR_GAP` still governs after the cover ruling
+ * (`OVERLAY_ATTACH_GAP = 0`). It must READ that token rather than restate its
+ * value under a second name (LC-16 ONE-IMPLEMENTATION).
+ *
+ * Both twins are checked. The web/native split is where a duplicate constant
+ * survives longest: fixing one file and leaving the other still renders the
+ * right gap on the platform anyone happened to look at.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const tooltipDir = dirname(fileURLToPath(import.meta.url));
+
+/** The web twin, the native twin, and the module they share. */
+const tooltipSources = ["index.tsx", "index.native.tsx", "tooltipShared.tsx"];
+
+function read(relative: string): string {
+  return readFileSync(resolve(tooltipDir, relative), "utf8");
+}
+
+describe("Tooltip gap contract (MPO-38 AC-7)", () => {
+  it.each(tooltipSources)("%s declares no gap constant of its own", (relative) => {
+    // Named for the constant this AC deleted, but the assertion is the rule,
+    // not the name: any local OFFSET/GAP constant is the same drift again.
+    expect(read(relative)).not.toMatch(/\b(?:const|let|var)\s+\w*(?:OFFSET|GAP)\w*\s*=/);
+  });
+
+  it.each(["index.tsx", "index.native.tsx"])(
+    "%s positions the bubble with the shared FREE-overlay token",
+    (relative) => {
+      const source = read(relative);
+      expect(source).toMatch(
+        /import\s*\{[^}]*\bOVERLAY_ANCHOR_GAP\b[^}]*\}\s*from\s*"@multiplatform\.one\/theme"/s,
+      );
+      expect(source).toContain("offset={OVERLAY_ANCHOR_GAP}");
+      // A literal offset is the regression: it renders the same 4px today and
+      // silently stops tracking the token the moment the house rule moves.
+      expect(source).not.toMatch(/offset=\{\s*\d/);
+    },
+  );
+});

package/src/Tooltip/tooltipShared.tsx

@@ -0,0 +1,157 @@
+/**
+ * Shared Tooltip recipes, content chrome, and text wrapping.
+ * Platform twins (index.tsx web / index.native.tsx) own open/close.
+ */
+
+import type { ReactNode } from "react";
+import React from "react";
+import { Tooltip as TamaguiTooltip, Text, styled } from "tamagui";
+import { wrapBareTextChildren } from "../shared/textRidesText";
+
+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. Web: hover warmup (keyboard is
+   * immediate). Native: long-press / press-in hold. Defaults differ per
+   * platform (300 web, 500 native).
+   */
+  delay?: number;
+  /** Whether the tooltip is disabled */
+  disabled?: boolean;
+  /** Controlled open. Omit for hover/focus (web) or long-press (native). */
+  open?: boolean;
+  /** Fired whenever open changes (controlled or internal). */
+  onOpenChange?: (open: boolean) => void;
+}
+
+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 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;
+}
+
+export 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);
+}
+
+export 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,
+  },
+});
+
+export const TooltipArrow = styled(TamaguiTooltip.Arrow, {
+  name: "TooltipArrow",
+  backgroundColor: "$color1",
+  borderColor: "$color1",
+});
+
+export 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>
+  ));
+}
+
+export 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;
+}
+
+export function preventTooltipFocus(event: { preventDefault?: () => void }) {
+  event.preventDefault?.();
+}