Tooltip

1/* Deepak Kumar E — https://craft.iam-deepak.space */2 3import { useId, useRef, useState } from "react";4 5/**6 * A tooltip that flips when it would leave the viewport.7 *8 * Placement is measured, not assumed. The preferred side is tried first, and9 * if the tooltip would overflow the viewport it flips to the opposite side and10 * shifts along the cross axis to stay on screen. A tooltip that renders11 * half-off the edge is worse than none, and it happens to every fixed-position12 * implementation the moment the trigger is near a boundary.13 *14 * It is a describedby relationship, not a label: the trigger keeps its own15 * accessible name and the tooltip adds to it. Using aria-label instead would16 * REPLACE the visible text, so a voice-control user could no longer say what17 * they can see.18 *19 * Opens on focus as well as hover, and Escape closes it — a keyboard user20 * reaches a tooltip by tabbing, and must be able to dismiss it without moving21 * focus away.22 */23 24type Side = "top" | "bottom" | "left" | "right";25 26export interface TooltipProps {27  children: React.ReactNode;28  content: string;29  side?: Side;30  /** Gap between trigger and tooltip, in pixels. */31  offset?: number;32  /** Milliseconds before it appears on hover. Focus always opens instantly. */33  delay?: number;34  still?: boolean;35  className?: string;36}37 38export function Tooltip({39  children,40  content,41  side = "top",42  offset = 8,43  delay = 120,44  still = false,45  className = "",46}: TooltipProps) {47  const id = useId();48  const hostRef = useRef<HTMLSpanElement>(null);49  const bubbleRef = useRef<HTMLSpanElement>(null);50  const timer = useRef<number | undefined>(undefined);51 52  const [open, setOpen] = useState(false);53  const [placement, setPlacement] = useState<{ side: Side; shift: number }>({54    side,55    shift: 0,56  });57 58  /** Flip if the preferred side overflows; shift to stay within the edges. */59  const place = () => {60    const host = hostRef.current;61    const bubble = bubbleRef.current;62    if (!host || !bubble) return;63 64    const trigger = host.getBoundingClientRect();65    const box = bubble.getBoundingClientRect();66    const margin = 8;67    let next: Side = side;68 69    const room = {70      top: trigger.top,71      bottom: window.innerHeight - trigger.bottom,72      left: trigger.left,73      right: window.innerWidth - trigger.right,74    };75    const needed = side === "top" || side === "bottom" ? box.height : box.width;76 77    // Flip only if the opposite side genuinely has more room — flipping into78    // an equally cramped side just moves the problem.79    if (room[side] < needed + offset + margin) {80      const opposite: Record<Side, Side> = {81        top: "bottom",82        bottom: "top",83        left: "right",84        right: "left",85      };86      if (room[opposite[side]] > room[side]) next = opposite[side];87    }88 89    let shift = 0;90    if (next === "top" || next === "bottom") {91      const centre = trigger.left + trigger.width / 2;92      const half = box.width / 2;93      if (centre - half < margin) shift = margin - (centre - half);94      else if (centre + half > window.innerWidth - margin) {95        shift = window.innerWidth - margin - (centre + half);96      }97    }98 99    setPlacement({ side: next, shift });100  };101 102  const show = (immediate: boolean) => {103    window.clearTimeout(timer.current);104    const run = () => {105      setOpen(true);106      // Measured after it exists — a hidden element has no useful box.107      window.setTimeout(place, 0);108    };109    if (immediate) run();110    else timer.current = window.setTimeout(run, delay);111  };112 113  const hide = () => {114    window.clearTimeout(timer.current);115    setOpen(false);116  };117 118  const position: React.CSSProperties = {119    top: { bottom: "100%", left: "50%", marginBottom: offset },120    bottom: { top: "100%", left: "50%", marginTop: offset },121    left: { right: "100%", top: "50%", marginRight: offset },122    right: { left: "100%", top: "50%", marginLeft: offset },123  }[placement.side];124 125  const translate =126    placement.side === "top" || placement.side === "bottom"127      ? `translateX(calc(-50% + ${placement.shift}px))`128      : "translateY(-50%)";129 130  return (131    <span132      ref={hostRef}133      className={`relative inline-block ${className}`}134      onPointerEnter={(e) => {135        // Touch already fires a tap; a hover delay there just feels broken.136        if (e.pointerType !== "touch") show(false);137      }}138      onPointerLeave={hide}139      onFocusCapture={() => show(true)}140      onBlurCapture={hide}141      onKeyDown={(e) => {142        if (e.key === "Escape") hide();143      }}144    >145      {/* describedby, not label: the trigger keeps its own accessible name. */}146      <span aria-describedby={open ? id : undefined}>{children}</span>147 148      <span149        ref={bubbleRef}150        id={id}151        role="tooltip"152        // Always rendered so it can be measured; visibility is what changes.153        className="pointer-events-none absolute z-50 w-max max-w-[16rem] rounded-md border border-ink-500 bg-ink-800 px-2.5 py-1.5 font-mono text-micro leading-relaxed text-bone-200 shadow-xl"154        style={{155          ...position,156          transform: translate,157          opacity: open ? 1 : 0,158          visibility: open ? "visible" : "hidden",159          transition: still ? "none" : "opacity 140ms linear",160        }}161      >162        {content}163      </span>164    </span>165  );166}167