@helloimjolopez-pathway/pathway-components 0.1.1 → 0.2.0

package/components/tooltip/tooltip-demo.jsx

@@ -0,0 +1,149 @@
+/**
+ * Tooltip's standalone demo. Imports the real module, so there is nothing here
+ * that can fall out of step with the shipped component: see
+ * components/_demo/harness.jsx for why the newer demos are generated.
+ */
+import React, { useState } from "react";
+import { DemoChrome, mount } from "../_demo/harness.jsx";
+import { Tooltip, TooltipProvider } from "./tooltip.jsx";
+import { Button } from "../button/button.jsx";
+
+const U = (n) => `var(--semantic-layout-units-${n})`;
+const C = (n) => `var(--semantic-color-${n})`;
+const Y = (n) => `var(--semantic-type-${n})`;
+
+const SIDES = ["top", "bottom", "left", "right"];
+const ALIGNS = ["start", "center", "end"];
+const LONG = "Weekly totals aren't available because budgets are set by month. Switch to Month to compare.";
+
+const label = { fontSize: Y("font-size-xs"), lineHeight: Y("line-height-xs-single"), color: C("foreground-static-neutral-subtle") };
+const card = {
+  background: C("fill-surface-elevated"), border: `1px solid ${C("stroke-static-neutral-base")}`,
+  borderRadius: U("cornerradius-large"), padding: U("padding-relaxed"),
+  display: "flex", flexDirection: "column", gap: U("gap-base"), minWidth: 0,
+};
+const h2 = { margin: 0, fontSize: Y("font-size-m"), lineHeight: Y("line-height-m-single"), fontWeight: Y("weight-semibold"), color: C("foreground-static-neutral-bold") };
+
+/* An unavailable option stays focusable so it can say why, which a native
+   disabled button cannot. This stands in for a Toggle Button option. */
+const Unavailable = React.forwardRef(function Unavailable({ children, ...rest }, ref) {
+  return (
+    <button ref={ref} type="button" aria-disabled="true" {...rest}
+      style={{ minWidth: U("accessibility-touch-target-aa-width"), minHeight: U("accessibility-touch-target-aa-height"),
+        padding: `0 ${U("padding-tight")}`, border: 0, borderRadius: U("cornerradius-base"), cursor: "not-allowed",
+        background: C("fill-action-disabled"), color: C("foreground-action-disabled"),
+        fontFamily: Y("family-brand"), fontSize: Y("font-size-s"), fontWeight: Y("weight-medium") }}>
+      {children}
+    </button>
+  );
+});
+
+function Playground() {
+  const [side, setSide] = useState("top");
+  const [align, setAlign] = useState("center");
+  const [arrow, setArrow] = useState(true);
+  const [text, setText] = useState("Bar chart");
+  const pick = (list, v, set) => (
+    <div style={{ display: "flex", gap: U("gap-xtight"), flexWrap: "wrap" }}>
+      {list.map((x) => <Button key={x} size="S" buttonStyle={x === v ? "Fill" : "Outlined"} type="Secondary" text={x} onClick={() => set(x)} />)}
+    </div>
+  );
+  return (
+    <section style={card}>
+      <h2 style={h2}>Playground</h2>
+      <div style={{ display: "flex", gap: U("gap-relaxed"), flexWrap: "wrap" }}>
+        <div><div style={label}>Side</div>{pick(SIDES, side, setSide)}</div>
+        <div><div style={label}>Align</div>{pick(ALIGNS, align, setAlign)}</div>
+        <div><div style={label}>Arrow</div>{pick(["on", "off"], arrow ? "on" : "off", (x) => setArrow(x === "on"))}</div>
+      </div>
+      <label style={{ ...label, display: "flex", flexDirection: "column", gap: U("gap-xxtight"), maxWidth: 420 }}>
+        Content
+        <input id="tooltip-content" value={text} onChange={(e) => setText(e.target.value)}
+          style={{ font: "inherit", fontSize: Y("font-size-s"), padding: U("padding-xtight"), borderRadius: U("cornerradius-small"),
+            border: `1px solid ${C("stroke-static-neutral-bold")}`, background: C("fill-surface-elevated"), color: C("foreground-static-neutral-base") }} />
+      </label>
+      <div style={{ minHeight: 160, display: "flex", alignItems: "center", justifyContent: "center" }}>
+        <Tooltip content={text} side={side} align={align} arrow={arrow} open purpose="description">
+          <button type="button" style={{ width: 120, height: 44, border: `1px dashed ${C("stroke-static-neutral-bold")}`,
+            borderRadius: U("cornerradius-base"), background: "transparent", color: C("foreground-static-neutral-subtle"), font: "inherit" }}>
+            Trigger
+          </button>
+        </Tooltip>
+      </div>
+    </section>
+  );
+}
+
+function Uses() {
+  return (
+    <section style={card}>
+      <h2 style={h2}>Try it: hover, Tab, tap, Esc</h2>
+      <div style={{ display: "flex", gap: U("gap-wide"), flexWrap: "wrap", alignItems: "flex-end" }}>
+        <div style={{ display: "flex", flexDirection: "column", gap: U("gap-tight") }}>
+          <span style={label}>Names icon-only controls</span>
+          <div style={{ display: "flex", gap: U("gap-xxtight") }}>
+            {[["bar_chart", "Bar chart"], ["show_chart", "Line chart"], ["table_rows", "Table"]].map(([icon, name]) => (
+              <Tooltip key={icon} content={name} purpose="label">
+                <Button buttonStyle="Naked" type="Secondary" size="M" showText={false} text={name}
+                  leadingIcon={icon} showLeadingIcon />
+              </Tooltip>
+            ))}
+          </div>
+        </div>
+        <div style={{ display: "flex", flexDirection: "column", gap: U("gap-tight") }}>
+          <span style={label}>Says why an option is unavailable</span>
+          <Tooltip content="Weekly totals aren't available. Budgets are set by month." persistOnPress>
+            <Unavailable>Week</Unavailable>
+          </Tooltip>
+        </div>
+        <div style={{ display: "flex", flexDirection: "column", gap: U("gap-tight") }}>
+          <span style={label}>Adds a short hint</span>
+          <Tooltip content="Includes payments that haven't cleared yet.">
+            <Button buttonStyle="Naked" type="Secondary" size="M" showText={false} text="About this balance"
+              leadingIcon="info" showLeadingIcon />
+          </Tooltip>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function Grid() {
+  return (
+    <section style={card}>
+      <h2 style={h2}>Sides and alignment</h2>
+      <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(220px, 1fr))", gap: U("gap-base") }}>
+        {SIDES.flatMap((s) => ALIGNS.map((a) => (
+          <div key={s + a} style={{ minHeight: 150, display: "flex", flexDirection: "column", gap: U("gap-tight"),
+            border: `1px dashed ${C("stroke-static-neutral-base")}`, borderRadius: U("cornerradius-base"), padding: U("padding-tight") }}>
+            <span style={label}>{s}, {a}</span>
+            <div style={{ flex: 1, display: "flex", alignItems: "center", justifyContent: "center" }}>
+              <Tooltip content={a === "center" ? "Bar chart" : LONG.slice(0, 44)} side={s} align={a} open>
+                <span tabIndex={-1} style={{ width: 28, height: 28, borderRadius: U("cornerradius-small"), background: C("fill-static-neutral-base") }} />
+              </Tooltip>
+            </div>
+          </div>
+        )))}
+      </div>
+    </section>
+  );
+}
+
+function App() {
+  return (
+    <DemoChrome title="Tooltip"
+      blurb={"A short, plain-text label beside a control. It is always the opposite mode to the page: " +
+             "switch to Midnight to see it turn light. Hover waits 300ms, keyboard focus opens it at once, " +
+             "a tap shows it for 2.6 seconds, Esc closes it."}>
+      <TooltipProvider>
+        <div style={{ display: "flex", flexDirection: "column", gap: U("gap-relaxed") }}>
+          <Uses />
+          <Playground />
+          <Grid />
+        </div>
+      </TooltipProvider>
+    </DemoChrome>
+  );
+}
+
+mount(<App />);

package/components/tooltip/tooltip.jsx

@@ -0,0 +1,416 @@
+/**
+ * Tooltip, Pathway Design System
+ *
+ * Importable React component module. Source of truth for the Tooltip
+ * implementation; the standalone demo (tooltip.html), the Storybook stories
+ * and the <pathway-tooltip> web component all consume this.
+ *
+ * A short, plain-text label beside a control. It names an icon-only control,
+ * says why an option is unavailable, or shows text that has been cut off.
+ * Never interactive: anything with a title, link or button is a Popover.
+ *
+ * Follows the WAI-ARIA tooltip pattern and the Radix Tooltip anatomy
+ * (Provider, Trigger, Portal, Content, Arrow), hand-built so the package keeps
+ * zero runtime dependencies (pipeline decision G-A, 2026-10-29).
+ *
+ * Spec:  components/tooltip/tooltip-spec.md
+ * Figma: https://www.figma.com/design/3sw45aVcngFAmpbP6cfrXP/?node-id=40018655-12004
+ */
+
+import React, { createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { useReducedMotion } from "../_shared/use-reduced-motion.jsx";
+
+// ─── TOKEN HELPERS ────────────────────────────────────────────────────────────
+// SC = semantic-color (themes/*.css), SL = semantic-layout-units (layout.css),
+// ST = semantic-type (type.css), M = motion (motion.css). Every name is
+// modeless: the inverse surface comes from a data-theme on the container, not
+// from a separate token family (spec §3.0).
+const SC = (p) => `var(--semantic-color-${p})`;
+const SL = (p) => `var(--semantic-layout-units-${p})`;
+const ST = (p) => `var(--semantic-type-${p})`;
+const M = (p) => `var(--motion-${p})`;
+
+// ─── COLOUR TOKENS ────────────────────────────────────────────────────────────
+// Static and Surface tokens: a tooltip is not interactive, so nothing here has
+// a rest/hover/pressed set. They resolve in the INVERSE mode.
+export const T = {
+  fill:   SC("fill-surface-elevated"),
+  stroke: SC("stroke-static-neutral-base"),
+  fg:     SC("foreground-static-neutral-base"),
+  shadow: "var(--elevation-widget)",
+};
+
+// ─── LAYOUT ───────────────────────────────────────────────────────────────────
+// Max width and the arrow are measurements, not tokens (CLAUDE.md §5).
+export const L = {
+  padY:    SL("padding-xxtight"),         // 6px
+  padX:    SL("padding-xtight"),          // 8px
+  radius:  SL("cornerradius-small"),      // 4px
+  stroke:  SL("borderwidth-base"),        // 1px
+  offset:  "--semantic-layout-units-gap-xxtight",    // 4px, read at runtime
+  edge:    "--semantic-layout-units-padding-xtight", // 8px, read at runtime
+  maxW:    240,
+  arrowW:  12,
+  arrowH:  6,
+  arrowInset: 8,                          // arrow edge to container corner, minimum
+  bridgeMs: 120,                          // pointer grace between trigger and tooltip
+  tapMs:   2600,                          // tap and press hold
+};
+
+const TYPE = {
+  fontFamily:    ST("family-brand"),
+  fontSize:      ST("font-size-s"),
+  fontWeight:    ST("weight-regular"),
+  lineHeight:    ST("line-height-s-single"),
+  letterSpacing: ST("letter-spacing-wide"),
+};
+
+// The theme the tooltip takes, for each page theme (spec §3.0).
+const INVERSE = {
+  "amplify-light": "amplify-dark", light: "dark",
+  "amplify-dark": "amplify-light", dark: "light", midnight: "light",
+};
+
+const CSS = `
+.pw-tooltip{position:fixed;left:0;top:0;z-index:1000;box-sizing:border-box;width:max-content;
+  max-width:min(${L.maxW}px, calc(100vw - 2 * var(${L.edge})));
+  padding:${L.padY} ${L.padX};border-radius:${L.radius};background:${T.fill};color:${T.fg};
+  box-shadow:inset 0 0 0 ${L.stroke} ${T.stroke},${T.shadow};
+  font-family:${TYPE.fontFamily},sans-serif;font-size:${TYPE.fontSize};font-weight:${TYPE.fontWeight};
+  line-height:${TYPE.lineHeight};letter-spacing:${TYPE.letterSpacing};
+  overflow-wrap:anywhere;text-align:start;pointer-events:auto;user-select:none}
+.pw-tooltip[data-state=open]{animation:pw-tooltip-in ${M("duration-2")} ${M("easing-decelerate")}}
+.pw-tooltip[data-state=closed]{animation:pw-tooltip-out ${M("duration-1")} ${M("easing-accelerate")} forwards}
+.pw-tooltip[data-side=top]{--pw-tooltip-dx:0;--pw-tooltip-dy:${SL("gap-xxtight")}}
+.pw-tooltip[data-side=bottom]{--pw-tooltip-dx:0;--pw-tooltip-dy:calc(-1 * ${SL("gap-xxtight")})}
+.pw-tooltip[data-side=left]{--pw-tooltip-dx:${SL("gap-xxtight")};--pw-tooltip-dy:0}
+.pw-tooltip[data-side=right]{--pw-tooltip-dx:calc(-1 * ${SL("gap-xxtight")});--pw-tooltip-dy:0}
+.pw-tooltip[data-reduced][data-state=open]{animation-name:pw-tooltip-fade}
+@keyframes pw-tooltip-in{from{opacity:0;transform:translate(var(--pw-tooltip-dx),var(--pw-tooltip-dy))}to{opacity:1;transform:none}}
+@keyframes pw-tooltip-fade{from{opacity:0}to{opacity:1}}
+@keyframes pw-tooltip-out{from{opacity:1}to{opacity:0}}
+.pw-tooltip__arrow{position:absolute;display:block;width:${L.arrowW}px;height:calc(${L.arrowH}px + ${L.stroke});overflow:hidden;transform-origin:0 0;pointer-events:none}
+.pw-tooltip__arrow::before{content:"";position:absolute;left:50%;top:0;width:8px;height:8px;box-sizing:border-box;
+  transform:translate(-50%,-50%) rotate(45deg);background:${T.fill};box-shadow:inset 0 0 0 ${L.stroke} ${T.stroke}}
+.pw-tooltip__sr{display:none}
+.pw-tooltip__trigger{display:inline-flex}
+`;
+
+let injected = false;
+function useStyles() {
+  useEffect(() => {
+    if (injected || typeof document === "undefined" || document.getElementById("pw-tooltip-css")) { injected = true; return; }
+    const el = document.createElement("style");
+    el.id = "pw-tooltip-css";
+    el.textContent = CSS;
+    document.head.appendChild(el);
+    injected = true;
+  }, []);
+}
+
+/* Radix-style timing needs numbers, so read the token values at runtime. */
+function tokenPx(name, fallback) {
+  if (typeof document === "undefined") return fallback;
+  const v = parseFloat(getComputedStyle(document.documentElement).getPropertyValue(name));
+  return Number.isFinite(v) ? v : fallback;
+}
+const clamp = (v, lo, hi) => Math.min(Math.max(v, lo), Math.max(lo, hi));
+
+/* Nearest ancestor with the attribute, crossing shadow roots, so a trigger
+   inside <pathway-tooltip> still finds the page's theme. */
+function closestAcross(el, sel) {
+  let n = el;
+  while (n) {
+    const hit = n.closest?.(sel);
+    if (hit) return hit;
+    n = n.getRootNode?.().host || null;
+  }
+  return null;
+}
+function themeOf(el) {
+  const host = closestAcross(el, "[data-theme]") || document.documentElement;
+  const brandHost = closestAcross(el, "[data-brand]") || document.documentElement;
+  return { theme: host.getAttribute("data-theme") || "light", brand: brandHost.getAttribute("data-brand") };
+}
+
+// One shared timestamp gives the skip delay: a new hover soon after a tooltip
+// closed opens at once.
+let lastClosedAt = 0;
+
+const TimingContext = createContext(null);
+
+/** App-wide defaults. Each Tooltip prop overrides its default. */
+export const TooltipDefaults = createContext({ arrow: true });
+
+/**
+ * Optional, once per app.
+ * @param {number} delay      hover delay in ms (default --motion-duration-4)
+ * @param {number} skipDelay  ms after a tooltip closes during which the next opens at once
+ */
+export function TooltipProvider({ children, delay, skipDelay }) {
+  return <TimingContext.Provider value={{ delay, skipDelay }}>{children}</TimingContext.Provider>;
+}
+
+/* Where the tooltip goes: preferred side and alignment, flipped and shifted to
+   stay inside the boundary, with the arrow kept on the trigger. */
+function computePosition(trigger, tip, { side, align, arrow, boundary }) {
+  const tr = trigger.getBoundingClientRect();
+  const w = tip.offsetWidth, h = tip.offsetHeight;
+  const b = boundary ? boundary.getBoundingClientRect() : { left: 0, top: 0, right: window.innerWidth, bottom: window.innerHeight };
+  const edge = tokenPx(L.edge, 8);
+  const gap = tokenPx(L.offset, 4) + (arrow ? L.arrowH : 0);
+  const fits = {
+    top: tr.top - gap - h >= b.top + edge,
+    bottom: tr.bottom + gap + h <= b.bottom - edge,
+    left: tr.left - gap - w >= b.left + edge,
+    right: tr.right + gap + w <= b.right - edge,
+  };
+  const opposite = { top: "bottom", bottom: "top", left: "right", right: "left" };
+  const s = !fits[side] && fits[opposite[side]] ? opposite[side] : side;
+  const vertical = s === "top" || s === "bottom";
+  let x, y;
+  if (vertical) {
+    y = s === "top" ? tr.top - gap - h : tr.bottom + gap;
+    x = align === "start" ? tr.left : align === "end" ? tr.right - w : tr.left + tr.width / 2 - w / 2;
+  } else {
+    x = s === "left" ? tr.left - gap - w : tr.right + gap;
+    y = align === "start" ? tr.top : align === "end" ? tr.bottom - h : tr.top + tr.height / 2 - h / 2;
+  }
+  // Shift to stay inside the boundary, but never so far that the arrow can no
+  // longer reach the trigger: a tooltip whose trigger scrolls out of view goes
+  // with it instead of sticking to the window edge.
+  const min = L.arrowInset + L.arrowW / 2;
+  let a = align;
+  if (vertical) {
+    const c = tr.left + tr.width / 2;
+    const nx = clamp(clamp(x, b.left + edge, b.right - edge - w), c - (w - min), c - min);
+    if (Math.abs(nx - x) > 0.5) a = nx > x ? "start" : "end";
+    x = nx;
+  } else {
+    const c = tr.top + tr.height / 2;
+    const ny = clamp(clamp(y, b.top + edge, b.bottom - edge - h), c - (h - min), c - min);
+    if (Math.abs(ny - y) > 0.5) a = ny > y ? "start" : "end";
+    y = ny;
+  }
+  const along = vertical ? clamp(tr.left + tr.width / 2 - x, min, w - min) : clamp(tr.top + tr.height / 2 - y, min, h - min);
+  return { x, y, side: s, align: a, along };
+}
+
+/* The arrow is drawn pointing down, attached by its top edge, then rotated
+   about its top-left corner for the other sides (spec §7). */
+function arrowStyle(side, along) {
+  const k = L.stroke;
+  switch (side) {
+    case "bottom": return { top: k, left: along + L.arrowW / 2, transform: "rotate(180deg)" };
+    case "left":   return { left: `calc(100% - ${k})`, top: along + L.arrowW / 2, transform: "rotate(-90deg)" };
+    case "right":  return { left: k, top: along - L.arrowW / 2, transform: "rotate(90deg)" };
+    default:       return { top: `calc(100% - ${k})`, left: along - L.arrowW / 2 };
+  }
+}
+
+/**
+ * @param {React.ReactElement} children  the trigger: one focusable element that forwards refs
+ * @param {string}  content     the text, plain, one or two short sentences
+ * @param {string}  describe    what aria-describedby reads, when it differs from content
+ * @param {"label"|"description"} purpose  label: the text is the trigger's name; description: a reason or hint
+ * @param {"top"|"bottom"|"left"|"right"} side   preferred side, flips when there is no room
+ * @param {"start"|"center"|"end"} align
+ * @param {boolean} arrow       point at the trigger
+ * @param {boolean} disabled    render the trigger alone (for example, text that is not cut off)
+ * @param {boolean} persistOnPress  a press shows it for 2.6s instead of closing it
+ * @param {Element} boundary    keep it inside this element instead of the window
+ * @param {boolean} open        controlled open; documentation and stories
+ * @param {Function} onOpenChange  (open) => void
+ * @param {boolean} manageAria  false when the caller names or describes the trigger itself (the web component)
+ */
+export function Tooltip({
+  children, content, describe, purpose = "description", side = "top", align = "center", arrow: arrowProp,
+  disabled = false, persistOnPress = false, boundary, open: forced, onOpenChange, manageAria = true,
+}) {
+  useStyles();
+  const defaults = useContext(TooltipDefaults);
+  const timing = useContext(TimingContext);
+  const arrow = arrowProp ?? defaults.arrow ?? true;
+  const reduced = useReducedMotion();
+  const descId = useId();
+  const triggerRef = useRef(null);
+  const tipRef = useRef(null);
+  const [hover, setHover] = useState(false);
+  const [focusOpen, setFocusOpen] = useState(false);
+  const [tapped, setTapped] = useState(false);
+  const [dismissed, setDismissed] = useState(false);
+  const [mounted, setMounted] = useState(false);
+  const [pos, setPos] = useState(null);
+  const [island, setIsland] = useState(null);
+  const openT = useRef(null), closeT = useRef(null), tapT = useRef(null), unmountT = useRef(null);
+  useEffect(() => () => [openT, closeT, tapT, unmountT].forEach((t) => clearTimeout(t.current)), []);
+
+  const isOpen = !disabled && !!content && (forced ?? (tapped || (!dismissed && (hover || focusOpen))));
+
+  // Keep the tooltip mounted through its exit animation.
+  const wasOpen = useRef(false);
+  useEffect(() => {
+    clearTimeout(unmountT.current);
+    if (isOpen) setMounted(true);
+    else if (wasOpen.current) {
+      lastClosedAt = Date.now();
+      unmountT.current = setTimeout(() => { setMounted(false); setPos(null); }, reduced ? 0 : tokenPx("--motion-duration-1", 100));
+    }
+    if (wasOpen.current !== isOpen) onOpenChange?.(isOpen);
+    wasOpen.current = isOpen;
+  }, [isOpen]);
+
+  // Resolve the inverse theme each time it opens, so a mode switch is picked up.
+  useEffect(() => {
+    if (!isOpen) return;
+    const resolve = () => {
+      const { theme, brand } = themeOf(triggerRef.current);
+      setIsland({ theme: INVERSE[theme] || "dark", brand });
+    };
+    resolve();
+    // A page that switches mode while a tooltip is held open (Storybook, the
+    // demo) updates it too.
+    const mo = typeof MutationObserver !== "undefined" ? new MutationObserver(resolve) : null;
+    mo?.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme", "data-brand"] });
+    return () => mo?.disconnect();
+  }, [isOpen]);
+
+  const place = useCallback(() => {
+    if (!triggerRef.current || !tipRef.current) return;
+    setPos(computePosition(triggerRef.current, tipRef.current, { side, align, arrow, boundary }));
+  }, [side, align, arrow, boundary]);
+
+  useLayoutEffect(() => {
+    if (!mounted) return;
+    place();
+    const onMove = () => place();
+    window.addEventListener("scroll", onMove, true);
+    window.addEventListener("resize", onMove);
+    const ro = typeof ResizeObserver !== "undefined" ? new ResizeObserver(onMove) : null;
+    if (ro && tipRef.current) ro.observe(tipRef.current);
+    // The trigger can also move without any scroll or resize (content above it
+    // loads, a panel opens), so follow its box while the tooltip is shown.
+    let raf = 0, last = "";
+    const follow = () => {
+      const r = triggerRef.current?.getBoundingClientRect();
+      const key = r ? `${r.left},${r.top},${r.width},${r.height}` : "";
+      if (key !== last) { last = key; place(); }
+      raf = requestAnimationFrame(follow);
+    };
+    raf = requestAnimationFrame(follow);
+    return () => { window.removeEventListener("scroll", onMove, true); window.removeEventListener("resize", onMove); ro?.disconnect(); cancelAnimationFrame(raf); };
+  }, [mounted, place, content, island]);
+
+  // Esc closes it wherever focus is; a press outside closes it too.
+  useEffect(() => {
+    if (!isOpen) return;
+    const onKey = (e) => { if (e.key === "Escape") { setDismissed(true); setTapped(false); } };
+    const onDown = (e) => { if (!triggerRef.current?.contains(e.target) && !tipRef.current?.contains(e.target)) { setHover(false); setTapped(false); } };
+    document.addEventListener("keydown", onKey);
+    document.addEventListener("pointerdown", onDown);
+    return () => { document.removeEventListener("keydown", onKey); document.removeEventListener("pointerdown", onDown); };
+  }, [isOpen]);
+
+  if (disabled || !content) return children;
+
+  const child = React.Children.only(children);
+  // A child that can take a ref (a DOM element, forwardRef or class) becomes
+  // the trigger itself. One that cannot, such as Pathway Button, is wrapped in
+  // an inline-flex span that carries the handlers and the position; the ARIA
+  // still goes onto the child, which spreads it onto its own element.
+  const canRef = typeof child.type === "string" || child.type?.$$typeof === Symbol.for("react.forward_ref")
+    || !!child.type?.prototype?.isReactComponent;
+  // A wrapped child keeps its own handlers, so only a cloned one needs them forwarded.
+  const call = (name, e) => { if (canRef) child.props[name]?.(e); };
+  const delay = timing?.delay ?? tokenPx("--motion-duration-4", 300);
+  const skip = timing?.skipDelay ?? delay;
+
+  const enter = (e) => {
+    call("onPointerEnter", e);
+    if (e.pointerType === "touch") return;
+    clearTimeout(closeT.current);
+    setDismissed(false);
+    if (hover) return;
+    if (Date.now() - lastClosedAt < skip) setHover(true);
+    else { clearTimeout(openT.current); openT.current = setTimeout(() => setHover(true), delay); }
+  };
+  const leave = (e) => {
+    call("onPointerLeave", e);
+    clearTimeout(openT.current);
+    clearTimeout(closeT.current);
+    // The grace period lets the pointer cross onto the tooltip (WCAG 1.4.13).
+    closeT.current = setTimeout(() => setHover(false), L.bridgeMs);
+  };
+  const keepOpen = () => clearTimeout(closeT.current);
+  const leaveTip = () => { clearTimeout(closeT.current); closeT.current = setTimeout(() => setHover(false), L.bridgeMs); };
+  const onFocus = (e) => {
+    call("onFocus", e);
+    let visible = true;
+    try { visible = e.target.matches(":focus-visible"); } catch { /* older browsers: treat as keyboard */ }
+    if (visible) { setDismissed(false); setFocusOpen(true); }
+  };
+  const onBlur = (e) => { call("onBlur", e); setFocusOpen(false); setTapped(false); };
+  // A tap shows it for 2.6s; persistOnPress does the same for a mouse press.
+  // Otherwise a press closes it, so it never covers what the press changed.
+  const onPointerDown = (e) => {
+    call("onPointerDown", e);
+    clearTimeout(openT.current);
+    if (e.pointerType === "touch" || persistOnPress) {
+      setTapped(true);
+      clearTimeout(tapT.current);
+      tapT.current = setTimeout(() => setTapped(false), L.tapMs);
+    } else { setHover(false); setDismissed(true); }
+  };
+
+  // The description is always in the page, so a screen reader reads it as soon
+  // as the trigger takes focus, not only once the tooltip has opened.
+  const describedBy = purpose === "description"
+    ? [child.props["aria-describedby"], descId].filter(Boolean).join(" ")
+    : child.props["aria-describedby"];
+
+  const setRef = (node) => {
+    triggerRef.current = node;
+    const r = child.ref;
+    if (typeof r === "function") r(node); else if (r && typeof r === "object") r.current = node;
+  };
+  const handlers = { onPointerEnter: enter, onPointerLeave: leave, onPointerDown, onFocus, onBlur };
+  const aria = manageAria ? {
+    "aria-label": purpose === "label" && typeof content === "string" ? content : child.props["aria-label"],
+    "aria-describedby": describedBy || undefined,
+  } : {};
+  const trigger = canRef
+    ? React.cloneElement(child, { ref: setRef, ...handlers, ...aria })
+    : <span ref={(n) => { triggerRef.current = n; }} className="pw-tooltip__trigger" {...handlers}>{React.cloneElement(child, aria)}</span>;
+
+  const tip = mounted && typeof document !== "undefined" ? createPortal(
+    <div
+      ref={tipRef}
+      className="pw-tooltip"
+      role="tooltip"
+      aria-hidden="true"
+      data-state={isOpen ? "open" : "closed"}
+      data-side={pos?.side ?? side}
+      data-align={pos?.align ?? align}
+      data-theme={island?.theme}
+      data-brand={island?.brand || undefined}
+      data-reduced={reduced || undefined}
+      onPointerEnter={keepOpen}
+      onPointerLeave={leaveTip}
+      style={{ left: pos ? pos.x : 0, top: pos ? pos.y : 0, visibility: pos ? "visible" : "hidden" }}>
+      {content}
+      {arrow && pos && <span className="pw-tooltip__arrow" style={arrowStyle(pos.side, pos.along)} />}
+    </div>,
+    document.body,
+  ) : null;
+
+  return (
+    <>
+      {trigger}
+      {manageAria && purpose === "description" && <span id={descId} className="pw-tooltip__sr" hidden>{describe ?? content}</span>}
+      {tip}
+    </>
+  );
+}
+
+export default Tooltip;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helloimjolopez-pathway/pathway-components",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Pathway Design System React components",
   "type": "module",
   "sideEffects": false,
@@ -16,7 +16,8 @@
     "./top-nav": "./components/top-nav/top-nav.jsx",
     "./sidenav": "./components/sidenav/sidenav.jsx",
     "./nav-shell": "./components/nav-shell/nav-shell.jsx",
-    "./page-template": "./components/page-template/page-template.jsx"
+    "./page-template": "./components/page-template/page-template.jsx",
+    "./tooltip": "./components/tooltip/tooltip.jsx"
   },
   "peerDependencies": {
     "react": ">=17",