@multiplatform.one/components 6.6.0 → 7.0.0

package/src/Tooltip/index.tsx

@@ -1,15 +1,26 @@
 /**
- * Tooltip - Compact tooltip component wired to knobs system.
+ * Tooltip — compact, non-interactive overlay (Radix / Primer / Polaris / Spectrum).
  *
- * A simple, compact tooltip that appears on hover/focus.
- * Designed for use in dense UI like table headers.
+ * 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.
  */
 
+import { zIndex } from "@multiplatform.one/forms";
 import { useResolvedKnobs, warnTooltipOnDisabled } from "@multiplatform.one/theme";
 import type { ReactNode } from "react";
 import React from "react";
-import { Tooltip as TamaguiTooltip, Text, styled, type GetProps } from "tamagui";
-import { componentColors } from "../componentColors";
+import {
+  Tooltip as TamaguiTooltip,
+  TooltipGroup as TamaguiTooltipGroup,
+  Text,
+  styled,
+  useTheme,
+  type GetProps,
+} from "tamagui";
+import { wrapBareTextChildren } from "../shared/textRidesText";
 
 // ── Types ─────────────────────────────────────────────────────
 
@@ -20,24 +31,94 @@ export interface TooltipProps {
   content: ReactNode;
   /** Placement of the tooltip relative to trigger */
   placement?: "top" | "bottom" | "left" | "right";
-  /** Delay before showing tooltip in ms */
+  /** 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",
-  backgroundColor: componentColors.overlay.background,
-  borderWidth: 1,
-  borderColor: componentColors.overlay.border,
-  paddingHorizontal: "$2",
-  paddingVertical: "$1.5",
-  maxWidth: 250,
-  // enterStyle/exitStyle are inert without a transition token (tamagui 2.0).
-  // Runtime `transition={knobProps.transition}` on the instance wires the driver.
+  // 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,
@@ -53,38 +134,77 @@ const TooltipContent = styled(TamaguiTooltip.Content, {
 
 const TooltipArrow = styled(TamaguiTooltip.Arrow, {
   name: "TooltipArrow",
-  borderWidth: 0,
-  backgroundColor: componentColors.overlay.background,
+  backgroundColor: "$color1",
+  borderColor: "$color1",
 });
 
 const TooltipText = styled(Text, {
   name: "TooltipText",
-  fontSize: "$1",
-  lineHeight: "$1",
-  color: componentColors.overlay.text,
 });
 
-// ── Tooltip Component ─────────────────────────────────────────
+/**
+ * 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>
+  ));
+}
 
-// SP-PAD (spec Tooltip content) via the house space-map pattern
-// (getTableCellPadding precedent): a tooltip stays compact, so the space
-// knob steps a tooltip-scale inset; medium keeps the previous $2/$1.5.
-const tooltipPadMap: Record<string, { h: string; v: string }> = {
-  small: { h: "$1.5", v: "$1" },
-  medium: { h: "$2", v: "$1.5" },
-  large: { h: "$3", v: "$2" },
-};
+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 ─────────────────────────────────────────
 
 export function Tooltip({
   children,
   content,
   placement = "top",
-  delay = 300,
+  delay = TOOLTIP_DEFAULT_DELAY_MS,
   disabled = false,
+  open: openProp,
+  onOpenChange: onOpenChangeProp,
 }: TooltipProps) {
-  const { knobProps } = useResolvedKnobs();
-  const pad = tooltipPadMap[knobProps.space] ?? tooltipPadMap.medium;
-  const [open, setOpen] = React.useState(false);
+  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 delayMs = useTooltipSkipDelay(delay);
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(false);
+  const isControlled = openProp !== undefined;
+  const open = isControlled ? openProp : uncontrolledOpen;
+
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (!isControlled) setUncontrolledOpen(next);
+      onOpenChangeProp?.(next);
+      if (!next) noteTooltipClosed();
+    },
+    [isControlled, onOpenChangeProp],
+  );
 
   // DG-A11Y — tooltips on disabled triggers are not keyboard-reachable.
   if (React.isValidElement(children)) {
@@ -99,9 +219,20 @@ export function Tooltip({
     });
   }
 
+  React.useEffect(() => {
+    if (!open || typeof document === "undefined") return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return;
+      event.stopPropagation();
+      setOpen(false);
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [open, setOpen]);
+
   // Open on keyboard (focus-visible) focus of the trigger, close on blur —
   // attached to the child directly because Trigger asChild does not forward
-  // focus handlers to the wrapped element.
+  // focus handlers to the wrapped element. Keyboard warmup is 0 (Spectrum).
   const trigger = React.isValidElement(children)
     ? React.cloneElement(children as React.ReactElement<Record<string, unknown>>, {
         onFocus: (e: React.FocusEvent<HTMLElement>) => {
@@ -129,22 +260,46 @@ export function Tooltip({
     return <>{children}</>;
   }
 
+  const elevated = knobProps.elevatedSurface;
+
   return (
-    <TamaguiTooltip placement={placement} delay={delay} open={open} onOpenChange={setOpen}>
+    <TamaguiTooltip
+      placement={placement}
+      delay={{ open: delayMs, close: 0 }}
+      restMs={100}
+      offset={TOOLTIP_OFFSET_PX}
+      zIndex={zIndex.dropdown}
+      open={open}
+      onOpenChange={setOpen}
+    >
       <TamaguiTooltip.Trigger asChild>{trigger}</TamaguiTooltip.Trigger>
       <TooltipContent
-        {...knobProps.borderRadius}
-        paddingHorizontal={pad.h as any}
-        paddingVertical={pad.v as any}
+        {...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}
+        onOpenAutoFocus={preventTooltipFocus}
+        onCloseAutoFocus={preventTooltipFocus}
       >
-        <TooltipArrow />
-        {/* T-BODY (spec Tooltip content): label rides the body font knobs. */}
-        {typeof content === "string" ? (
-          <TooltipText {...knobProps.body}>{content}</TooltipText>
-        ) : (
-          content
-        )}
+        <TooltipArrow
+          backgroundColor={surfaceFill}
+          borderColor={surfaceFill}
+          style={{ backgroundColor: surfaceFill, borderColor: surfaceFill }}
+        />
+        {/* Nested type: label (size) + body family/weight. $color12 clears AA at caption size. */}
+        {wrapTooltipContent(content, {
+          ...knobProps.body,
+          ...knobProps.label,
+          color: "$color12",
+          lineHeight: knobProps.label.fontSize,
+        })}
       </TooltipContent>
     </TamaguiTooltip>
   );
@@ -155,6 +310,7 @@ 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>;