Returns Calendar

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

"use client";

import { useEffect, useState } from "react";

/**
 * Returns true only on devices that have a true hover (mouse / trackpad).
 * Touch devices fire phantom `:hover` on tap that sticks until tap-elsewhere
 * — gate hover-only effects (scale lifts, magnetic pulls) behind this.
 */
export function useHoverCapable() {
  const [canHover, setCanHover] = useState(false);

  useEffect(() => {
    if (typeof window === "undefined" || !window.matchMedia) return;
    const mq = window.matchMedia("(hover: hover) and (pointer: fine)");
    const update = () => setCanHover(mq.matches);
    update();
    mq.addEventListener?.("change", update);
    return () => mq.removeEventListener?.("change", update);
  }, []);

  return canHover;
}

// Shared motion tokens. Easing curves mirror the CSS custom properties in
// globals.css; springs are the canonical physics used across components.
// Strong custom variants — defaults like `ease-in`/`ease-out` feel weak.

export const EASE_OUT = [0.16, 1, 0.3, 1] as const;
export const EASE_IN_OUT = [0.77, 0, 0.175, 1] as const;
export const EASE_DRAWER = [0.32, 0.72, 0, 1] as const;

/** CSS string form of EASE_OUT for inline style transitions. */
export const EASE_OUT_CSS = "cubic-bezier(0.16, 1, 0.3, 1)";

/** Press feedback on buttons and other tappable surfaces. */
export const SPRING_PRESS = {
  type: "spring",
  stiffness: 500,
  damping: 30,
  mass: 0.6,
} as const;

/** Content swaps — label/icon slots trading places inside a control. */
export const SPRING_SWAP = {
  type: "spring",
  stiffness: 460,
  damping: 30,
  mass: 0.55,
} as const;

/** Overlay panel entrances — modals and sheets summoned by pointer. */
export const SPRING_PANEL = {
  type: "spring",
  stiffness: 420,
  damping: 40,
  mass: 0.5,
} as const;

/** Shared-layout glides — pills, indicators and panels morphing between positions. */
export const SPRING_LAYOUT = {
  type: "spring",
  stiffness: 360,
  damping: 32,
  mass: 0.6,
} as const;

/** Cursor-follow physics for decorative mouse tracking (magnetic, tilt, dock). */
export const SPRING_MOUSE = {
  stiffness: 200,
  damping: 15,
  mass: 0.3,
} as const;

/** Dragged handles and fills (sliders) — critically damped `useSpring` config,
 * so the value follows the pointer butterily and never rebounds off an end. */
export const SPRING_GLIDE = {
  stiffness: 700,
  damping: 50,
  mass: 0.5,
} as const;

"use client";

import { type RefObject, useEffect } from "react";

/**
 * What the dismissing gesture does to the control it landed on.
 *
 * `"pass-through"` is the platform norm (native popover light-dismiss): the
 * tap closes the overlay *and* activates whatever was under it. Use
 * `"consume"` where the open overlay sits over or beside controls that would
 * be costly to trigger by accident — the dismissal then swallows the
 * activation too, so the gesture only closes.
 */
export type DismissBehavior = "pass-through" | "consume";

export interface DismissOptions {
  /** Default `"pass-through"`. */
  behavior?: DismissBehavior;
  /** Dismiss on Escape as well. Default true. */
  escape?: boolean;
  /** Return true for an outside target that should *not* dismiss. Must be stable. */
  ignore?: (target: Element) => boolean;
}

/**
 * What every currently open dismiss scope counts as inside itself. A consumed
 * dismissal reads this to tell a stray gesture from one that belongs to an
 * overlay in front of it: overlays have no shared z-order to consult, but the
 * one the gesture landed in has said as much by registering it.
 */
const openScopes = new Set<(target: Element) => boolean>();

function claimedByAnotherScope(
  self: (target: Element) => boolean,
  target: Element,
) {
  for (const scope of openScopes) {
    if (scope !== self && scope(target)) return true;
  }
  return false;
}

// preventDefault on pointerdown does not suppress the click that follows, so
// consuming a gesture means swallowing that click itself. The swallower
// deliberately outlives the effect that installed it — the dismissal it
// belongs to has already unmounted or re-rendered by the time the click lands.
// It releases on that click, or on the next gesture if the pointer is dragged
// away and no click ever arrives, so it can never eat a later one. A keydown
// releases it too: a gesture that ends with neither a click nor a cancel would
// otherwise leave it armed, and the click Enter synthesizes on some focused
// control is not the one this dismissal was owed.
function consumeActivation(source: Event) {
  const swallow = (event: MouseEvent) => {
    event.preventDefault();
    event.stopPropagation();
    release();
  };
  const restart = (event: Event) => {
    if (event !== source) release();
  };
  const release = () => {
    window.removeEventListener("click", swallow, true);
    window.removeEventListener("pointerdown", restart, true);
    window.removeEventListener("pointercancel", restart, true);
    window.removeEventListener("keydown", release, true);
  };
  window.addEventListener("click", swallow, true);
  window.addEventListener("pointerdown", restart, true);
  window.addEventListener("pointercancel", restart, true);
  window.addEventListener("keydown", release, true);
}

/**
 * Close an open overlay on Escape or a pointerdown outside `ref`. Pass `null`
 * for `ref` when what counts as inside isn't one element, and say so with
 * `ignore` instead.
 *
 * The pointerdown listener is capture-phase: a bubble-phase one is blinded by
 * any handler in between that stops propagation, and an overlay cannot know
 * what it is layered over. `onDismiss` and `ignore` must be stable (wrap in
 * useCallback) so the listeners aren't re-bound every render while open.
 */
export function useDismiss(
  open: boolean,
  onDismiss: () => void,
  ref: RefObject<HTMLElement | SVGElement | null> | null,
  {
    behavior = "pass-through",
    escape: dismissOnEscape = true,
    ignore,
  }: DismissOptions = {},
) {
  useEffect(() => {
    if (!open) return;
    const inside = (target: Element) =>
      Boolean(ref?.current?.contains(target)) || Boolean(ignore?.(target));
    const onKey = (event: KeyboardEvent) => {
      if (dismissOnEscape && event.key === "Escape") onDismiss();
    };
    const onPointer = (event: PointerEvent) => {
      const target = event.target as Element | null;
      if (!target || inside(target)) return;
      // Outside this overlay, but inside one that is also open: the gesture is
      // that overlay's to answer, and swallowing its click from behind would
      // cost the user the control they actually aimed at.
      if (behavior === "consume" && !claimedByAnotherScope(inside, target)) {
        consumeActivation(event);
      }
      onDismiss();
    };
    openScopes.add(inside);
    window.addEventListener("keydown", onKey);
    window.addEventListener("pointerdown", onPointer, true);
    return () => {
      openScopes.delete(inside);
      window.removeEventListener("keydown", onKey);
      window.removeEventListener("pointerdown", onPointer, true);
    };
  }, [open, onDismiss, ref, behavior, dismissOnEscape, ignore]);
}

"use client";

import { useMemo, useRef } from "react";
import { isHoveringPointer } from "@/lib/touch";

interface BoundaryEvent {
  pointerId: number;
  pointerType: string;
  buttons: number;
}

export interface HoverGesture {
  /** True when this enter starts a hover: the pointer arrived resting, not pressing. */
  enter: (event: BoundaryEvent) => boolean;
  /** True when this leave ends a hover that entered as one. */
  leave: (event: BoundaryEvent) => boolean;
}

/**
 * Pairs a surface's enter with its leave, per pointer.
 *
 * `isHoveringPointer` answers the question the *enter* asks — is this pointer
 * resting on the surface or pressing it — and both boundary cases go wrong if
 * the leave is asked the same question again:
 *
 * - A pen with no hover never rests. It arrives in contact, taps, and the spec
 *   then requires its boundary events after `pointerup`, so the leave carries
 *   `buttons: 0` and reads as a mouse gliding off. Hover teardown then undid
 *   the tap — the panel the pen had just opened closed under it.
 * - A mouse pressed on the surface and dragged off leaves with `buttons: 1`.
 *   Skipping teardown there strands the surface open: the release happens
 *   outside, and no second leave ever comes.
 *
 * So the state a hover holds is released by the pointer that took it, whatever
 * the buttons say at the boundary, and a pointer that arrived in contact never
 * took it in the first place. Contact is the exception tracked here, not
 * hover: a leave from a pointer this surface never saw enter — mounted under
 * the cursor, say — still counts, since the alternative is state with no way
 * out.
 */
export function useHoverGesture(): HoverGesture {
  const contact = useRef(new Set<number>());

  return useMemo(
    () => ({
      enter: (event) => {
        if (isHoveringPointer(event)) {
          contact.current.delete(event.pointerId);
          return true;
        }
        contact.current.add(event.pointerId);
        return false;
      },
      leave: (event) => {
        const arrivedInContact = contact.current.delete(event.pointerId);
        return !arrivedInContact && event.pointerType !== "touch";
      },
    }),
    [],
  );
}

"use client";

import { useMemo, useRef } from "react";

/** What a pointerdown recorded, read back by the click that ends its gesture. */
export interface TapRecord<S> {
  /** Which input started the gesture. */
  pointerType: string;
  /** What the surface was showing when it started. */
  state: S;
}

export interface TapGesture<S> {
  /** Record the gesture a pointerdown starts, with the state it starts in. */
  start: (event: { pointerType: string }, state: S) => void;
  /** Read the record and clear it. `null` when no pointer is behind this click. */
  take: () => TapRecord<S> | null;
  /** Drop the record: this gesture will never spend it on a click. */
  drop: () => void;
}

/**
 * The pointer gesture behind a click, recorded where the click cannot report
 * it. A `click` carries no `pointerType` in the engines that matter, so the
 * `pointerdown` before it is the only thing that says which input activated
 * the control — and whether one did at all, since keyboard activation
 * synthesizes a click with no pointer behind it.
 *
 * State goes in with the record because a click reports that no better: a
 * browser that focuses a control on contact can open the very panel the tap
 * was meant to open, and reading "is it open" at click time then undoes it.
 * What the gesture started against is what it acts on.
 *
 * The record is spent by one click and dropped by everything else, because a
 * record that outlives its gesture is worse than none:
 *
 * - A scroll or an OS gesture takes the touch away — `pointercancel`, no click
 *   ever — and the finger would sit in the record until some later click.
 * - That later click is often `Enter` on a keyboard, which arrives with no
 *   pointerdown of its own and would inherit the abandoned finger. A keydown
 *   is the start of a keyboard activation and never part of a tap, so it drops
 *   the record too.
 *
 * Both ends have to be wired by the surface: `drop` on `onPointerCancel` and
 * on `onKeyDown`.
 */
export function useTapGesture<S>(): TapGesture<S> {
  const record = useRef<TapRecord<S> | null>(null);

  return useMemo(
    () => ({
      start: (event, state) => {
        record.current = { pointerType: event.pointerType, state };
      },
      take: () => {
        const spent = record.current;
        record.current = null;
        return spent;
      },
      drop: () => {
        record.current = null;
      },
    }),
    [],
  );
}

// Shared touch primitives. iOS and iPadOS run their own gestures on top of the
// page — the long-press selection callout and the selection it drags in with
// it — and they win: once the platform claims a touch it cancels ours
// mid-gesture, so a press-and-hold or a drag simply dies. Surfaces that own
// their gesture have to opt out.
//
// What the two classes below cover, precisely:
// - `-webkit-touch-callout: none` stops iOS's long-press callout. WebKit-only:
//   it is not a property other engines have, so it is inert everywhere else.
// - `user-select: none` stops the long-press selection on every engine,
//   Android included, and stops a drag from painting a selection under the
//   cursor. It is inherited, so it reaches every descendant — which is why the
//   two classes differ only in whether they apply it unconditionally.
// What neither covers:
// - Chrome for Android's long-press menu on a link or an image. No CSS
//   suppresses it; a gesture surface that wraps one needs its own
//   `onContextMenu` with `preventDefault()`.
// - The native drag of an `<img>` or `<a>` descendant. `-webkit-user-drag` is
//   not inherited and plain divs and buttons are not drag sources, so setting
//   it on the surface does nothing — the child itself needs `draggable={false}`.

/**
 * Classes for a surface that *is* the control: a thumb, a drum, a stage, a
 * handle, a hold button. Selection is suppressed on every input, because a
 * drag that highlights the control's own label is wrong on a mouse too.
 * Compose with `touch-none` when the surface also owns the scroll axis — leave
 * it off when the page must still scroll from there.
 */
export const TOUCH_GESTURE_CLASS = "select-none [-webkit-touch-callout:none]";

/**
 * The same opt-out for a gesture surface that wraps content the consumer owns:
 * a scroller, a context-menu trigger, a sheet header, a list row. Selection is
 * suppressed only where the platform runs its own press gestures — a coarse
 * pointer — so a mouse user can still select and copy that content. If the
 * gesture itself would paint a selection under the cursor, add `select-none`
 * for the duration of the gesture rather than reaching for
 * `TOUCH_GESTURE_CLASS`.
 *
 * `pointer: coarse` describes the *primary* pointer and nothing else, so a
 * hybrid machine reads it wrong in both directions: a tablet with a mouse
 * plugged in keeps touch as primary and loses mouse selection, and a laptop
 * with a touchscreen keeps the mouse as primary and leaves selection live
 * under a finger. No media query can answer per interaction — the query is
 * about the device, and the question is about the gesture in progress. The
 * default stays here because it is right on the machines that are one thing or
 * the other, and losing a selection is a nuisance; where the miss costs a
 * *gesture* instead, the surface pairs it with `holdSelection` on the press.
 */
export const TOUCH_GESTURE_CONTENT_CLASS =
  "[-webkit-touch-callout:none] pointer-coarse:select-none";

/**
 * Suppress selection on `element` for as long as a gesture is running on it,
 * whatever the primary pointer of the machine happens to be. Returns the
 * release. Inline, so it wins over the class above and is gone again the
 * moment the gesture ends.
 *
 * For the press gestures a native selection would otherwise steal — a
 * long-press that opens a menu. Elsewhere prefer the classes: a surface that
 * takes selection away for the whole session is a surface whose text nobody
 * can copy.
 */
export function holdSelection(element: HTMLElement) {
  element.style.setProperty("user-select", "none");
  element.style.setProperty("-webkit-user-select", "none");
  return () => {
    element.style.removeProperty("user-select");
    element.style.removeProperty("-webkit-user-select");
  };
}

/**
 * Pointer capture, best effort. WebKit throws `NotFoundError` when the pointer
 * is already gone by the time the handler runs — routine on iOS, where the
 * system can claim the touch first — and an uncaught throw takes the rest of
 * the handler, the gesture included, down with it. Touch pointers carry
 * implicit capture anyway, so losing it is never fatal.
 */
export function capturePointer(element: Element, pointerId: number) {
  try {
    element.setPointerCapture(pointerId);
  } catch {
    // Pointer is no longer active — implicit capture still applies on touch.
  }
}

/** Release a capture taken with `capturePointer`, ignoring a stale pointer. */
export function releasePointer(element: Element, pointerId: number) {
  try {
    if (element.hasPointerCapture(pointerId)) {
      element.releasePointerCapture(pointerId);
    }
  } catch {
    // Capture was already dropped by the browser.
  }
}

/**
 * Whether this event came from a pointer that is *hovering*: not a touch, and
 * not currently pressed. Which input the user is holding right now is not
 * something a device capability can answer — a touchscreen laptop hovers and
 * taps, and iPadOS reports a fine hovering pointer for a finger — so both
 * paths stay live and each handler branches on the event it was given.
 *
 * A pen resting on the glass is making contact, not hovering: `buttons` is the
 * tell, and it sends a pen tap down the same route a finger takes.
 *
 * This answers what an *enter* asks. A leave is the other half of a pair and
 * has to be read against the enter that started it — `useHoverGesture` in
 * `lib/hooks/use-hover-gesture` does that, and hover surfaces should use it
 * rather than asking this question twice.
 */
export const isHoveringPointer = (event: {
  pointerType: string;
  buttons: number;
}) => event.pointerType !== "touch" && event.buttons === 0;

"use client";
// beui.dev/charts/returns-calendar

import { cn } from "@/lib/utils";
import { ReturnsCalendarContext, useReturnsCalendarModel } from "./returns-calendar/context";
import { ReturnsCalendarGrid } from "./returns-calendar/grid";
import { ReturnsCalendarTooltip } from "./returns-calendar/tooltip";
import type { ReturnsCalendarProps } from "./returns-calendar/types";

/** Compose Grid and Tooltip, or omit children for the complete chart. */
export function ReturnsCalendar({ children, className, ...props }: ReturnsCalendarProps) {
  const model = useReturnsCalendarModel(props);
  return (
    <ReturnsCalendarContext.Provider value={model}>
      <div className={cn("w-[480px] max-w-full [--ink-l:0.5] dark:[--ink-l:1]", className)}>
        {children === undefined ? (
          <ReturnsCalendarGrid>
            <ReturnsCalendarTooltip />
          </ReturnsCalendarGrid>
        ) : (
          children
        )}
      </div>
    </ReturnsCalendarContext.Provider>
  );
}

export { useReturnsCalendar } from "./returns-calendar/context";
export { ReturnsCalendarGrid } from "./returns-calendar/grid";
export { ReturnsCalendarTooltip } from "./returns-calendar/tooltip";
export type {
  ReturnsCalendarProps,
  ReturnsCalendarSelection,
  ReturnsCalendarTooltipData,
} from "./returns-calendar/types";

// A local type alias keeps docgen from listing this data shape as a component.
export type ReturnsCalendarCell = import("./returns-calendar/types").ReturnsCalendarCell;

"use client";

import { useReducedMotion } from "motion/react";
import {
  createContext,
  useContext,
  useEffect,
  useId,
  useMemo,
  useRef,
  useState,
} from "react";
import { useHoverCapable } from "@/lib/hooks/use-hover-capable";
import type { ReturnsCalendarCell, ReturnsCalendarProps, ReturnsCalendarSelection } from "./types";
import { compound, MONTHS, same, YEAR } from "./utils";

/**
 * Monthly returns as a years by months grid. Each cell tints toward the up or
 * down color by magnitude, and a compounded year column closes every row.
 * Cells spring in on a diagonal wave. Hovering a month glides a tooltip with
 * its value and dims everything that shares neither its row nor its column;
 * hovering a year total replays that row month by month. Clicking a month
 * anchors a span: the grid dims, hovering previews the run from that month to
 * the pointer with its compounded return, a second click locks it and a third
 * clears it. The Year column selects the same way but by whole years — anchor a
 * year, a second year spans every month between them. Hover lifts are gated to
 * pointer devices, and reduced motion keeps the fades only.
 */
export function useReturnsCalendarModel({
  years = [],
  returns = [],
  selection: controlledSelection,
  defaultSelection = null,
  onSelectionChange,
}: ReturnsCalendarProps) {
  const reduce = useReducedMotion();
  const canHover = useHoverCapable();
  const [storedHover, setHover] = useState<ReturnsCalendarCell | null>(null);
  const [internalSelection, setInternalSelection] = useState(defaultSelection);
  const requestedSelection = controlledSelection === undefined ? internalSelection : controlledSelection;
  const validCell = (cell: ReturnsCalendarCell) =>
    Number.isInteger(cell.y) &&
    Number.isInteger(cell.m) &&
    cell.y >= 0 &&
    cell.y < years.length &&
    cell.m >= 0 &&
    cell.m <= YEAR;
  const selection =
    requestedSelection &&
    validCell(requestedSelection.start) &&
    (!requestedSelection.end ||
      (validCell(requestedSelection.end) &&
        (requestedSelection.start.m === YEAR) === (requestedSelection.end.m === YEAR)))
      ? requestedSelection
      : null;
  if (requestedSelection && !selection && controlledSelection === undefined) setInternalSelection(null);
  const hover = storedHover && validCell(storedHover) ? storedHover : null;
  if (storedHover && !hover) setHover(null);
  const pinned = selection?.start ?? null;
  const spanEnd = selection?.end ?? null;
  const setSelection = (next: ReturnsCalendarSelection | null) => {
    if (controlledSelection === undefined) setInternalSelection(next);
    onSelectionChange?.(next);
  };
  const gridRef = useRef<HTMLDivElement>(null);
  const tooltipId = useId();
  // the entrance wave owns the cells until it has landed; hover lifts take over after
  const [settled, setSettled] = useState(false);
  useEffect(() => {
    const t = setTimeout(() => setSettled(true), reduce ? 0 : (years.length + 13) * 20 + 500);
    return () => clearTimeout(t);
  }, [years.length, reduce]);

  // Normalize each displayed row to twelve months so missing values never
  // shift the following year's positions when a span is compounded.
  const rows = useMemo(
    () => years.map((_, y) => MONTHS.map((_, m) => returns[y]?.[m] ?? 0)),
    [years, returns],
  );
  const totals = useMemo(() => rows.map(compound), [rows]);
  /** every month in order, so a span is one slice */
  const flat = useMemo(() => rows.flat(), [rows]);

  const valueAt = (y: number, m: number) => returns[y]?.[m] ?? 0;
  /** percent that saturates a month's tint */
  const range = 8;

  // one click on a month anchors a span and dims everything else; hovering then
  // previews the run from the anchor to the pointer and compounds it live, a
  // second click locks it, and the next click anywhere clears it
  const ci = (c: ReturnsCalendarCell) => c.y * 12 + c.m;
  const clear = () => {
    setSelection(null);
  };
  const anchored = pinned !== null && pinned.m !== YEAR;
  const spanTo = spanEnd ?? (anchored && hover && hover.m !== YEAR ? hover : null);
  const span =
    anchored && pinned
      ? spanTo
        ? { lo: Math.min(ci(pinned), ci(spanTo)), hi: Math.max(ci(pinned), ci(spanTo)) }
        : { lo: ci(pinned), hi: ci(pinned) }
      : null;
  const spanValue = span ? compound(flat.slice(span.lo, span.hi + 1)) : 0;

  // the Year column runs its own selection: anchor a year, then a second year
  // spans whole years and compounds every month between them
  const yearAnchored = pinned !== null && pinned.m === YEAR;
  const yearTo = spanEnd ?? (yearAnchored && hover && hover.m === YEAR ? hover : null);
  const yearSpan =
    yearAnchored && pinned
      ? { lo: Math.min(pinned.y, (yearTo ?? pinned).y), hi: Math.max(pinned.y, (yearTo ?? pinned).y) }
      : null;
  const yearSpanValue = yearSpan ? compound(flat.slice(yearSpan.lo * 12, (yearSpan.hi + 1) * 12)) : 0;

  const select = (cell: ReturnsCalendarCell) => {
    if (spanEnd || same(pinned, cell.y, cell.m)) clear();
    // extend within the same track — month→month or year→year; a different track re-anchors
    else if (pinned && (pinned.m === YEAR) === (cell.m === YEAR)) setSelection({ start: pinned, end: cell });
    else {
      setSelection({ start: cell });
    }
  };

  /** the cell the grid reacts to: lift, labels and the year replay follow the pointer */
  const hot = hover ?? spanEnd ?? pinned;
  /** the cell the tooltip hangs from: a locked span keeps it on its end */
  const tip = spanEnd ?? hover ?? pinned;
  // the year replay is a plain-hover flourish; hold it back while a year span is being built
  const sweepRow = !yearAnchored && hot?.m === YEAR ? hot.y : null;
  const showSpan = span !== null && span.lo !== span.hi;
  const showYearSpan = yearSpan !== null && yearSpan.lo !== yearSpan.hi;
  const tipValue = showYearSpan
    ? yearSpanValue
    : showSpan && span
      ? spanValue
      : tip
        ? tip.m === YEAR
          ? totals[tip.y]
          : valueAt(tip.y, tip.m)
        : 0;
  const tipLabel =
    showYearSpan && yearSpan
      ? `${years[yearSpan.lo]} – ${years[yearSpan.hi]}`
      : showSpan && span
        ? `${MONTHS[span.lo % 12]} ${years[Math.floor(span.lo / 12)]} – ${MONTHS[span.hi % 12]} ${years[Math.floor(span.hi / 12)]}`
        : tip
          ? tip.m === YEAR
            ? `${years[tip.y]}`
            : `${MONTHS[tip.m]} ${years[tip.y]}`
          : "";
  const tipNote =
    showYearSpan && yearSpan
      ? `${yearSpan.hi - yearSpan.lo + 1} years`
      : showSpan && span
        ? `${span.hi - span.lo + 1} months`
        : tip?.m === YEAR
          ? "for the year"
          : null;
  const enter = (y: number, m: number) => () => setHover({ y, m });
  const press = (y: number, m: number) => () => select({ y, m });
  const clearOnEscape = (e: { key: string }) => {
    if (e.key === "Escape") clear();
  };

  return {
    years,
    reduce,
    canHover,
    hover,
    pinned,
    spanEnd,
    settled,
    totals,
    valueAt,
    range,
    clear,
    span,
    yearSpan,
    hot,
    tip,
    sweepRow,
    tipValue,
    tipLabel,
    tipNote,
    enter,
    press,
    clearOnEscape,
    setHover,
    gridRef,
    tooltipId,
    selection,
    setSelection,
  };
}


export const ReturnsCalendarContext = createContext<ReturnType<typeof useReturnsCalendarModel> | null>(null);

export function useReturnsCalendar() {
  const context = useContext(ReturnsCalendarContext);
  if (!context) throw new Error("ReturnsCalendar parts must be inside ReturnsCalendar");
  return context;
}

"use client";

import { AnimatePresence, motion } from "motion/react";
import type { ReactNode } from "react";
import { EASE_OUT, SPRING_PRESS } from "@/lib/ease";
import { cn } from "@/lib/utils";
import { useReturnsCalendar } from "./context";
import { COLS, DOWN, ink, MONTHS, RING, same, signed, tint, UP, YEAR } from "./utils";

export function ReturnsCalendarGrid({ children, className }: { children?: ReactNode; className?: string }) {
  const {
    years,
    reduce,
    canHover,
    pinned,
    settled,
    totals,
    valueAt,
    range,
    span,
    yearSpan,
    hot,
    sweepRow,
    enter,
    press,
    clearOnEscape,
    setHover,
    gridRef,
    tooltipId,
  } = useReturnsCalendar();
  return (
    <div
      ref={gridRef}
      className={cn("relative grid gap-1", className)}
      style={{ gridTemplateColumns: "32px repeat(12, 1fr) 52px" }}
      onPointerLeave={() => setHover(null)}
    >
      <span />
      {COLS.map((c) => (
        <span
          key={c.name}
          className={cn(
            "pb-1 text-center text-[10px] transition-colors duration-200",
            hot?.m === c.m ? "text-foreground" : "text-muted-foreground",
          )}
        >
          {c.initial}
        </span>
      ))}
      <span
        className={cn(
          "pb-1 text-center text-[10px] transition-colors duration-200",
          hot?.m === YEAR ? "text-foreground" : "text-muted-foreground",
        )}
      >
        Year
      </span>

      {years.map((year, y) => (
        <div key={year} className="contents">
          <span
            className={cn(
              "flex items-center justify-end pr-1.5 font-mono text-[10px] tabular-nums transition-colors duration-200",
              hot?.y === y ? "text-foreground" : "text-muted-foreground",
            )}
          >
            {`’${String(year).slice(2)}`}
          </span>

          {COLS.map(({ name, m }) => {
            const v = valueAt(y, m);
            const i = y * 12 + m;
            const on = same(hot, y, m);
            const isEnd = span ? i === span.lo || i === span.hi : same(pinned, y, m);
            // a year span lights whole rows; months in the picked years stay lit, the rest dim
            const dim = span
              ? i < span.lo || i > span.hi
              : yearSpan
                ? y < yearSpan.lo || y > yearSpan.hi
                : !!hot && !on && hot.y !== y && hot.m !== m;
            const lift = settled && on && canHover && !reduce ? 1.15 : 1;
            return (
              // the outer span owns the dim so it never fights the transforms inside
              <span
                key={`${year}-${name}`}
                className="relative block aspect-square w-full transition-opacity duration-200"
                style={{ opacity: dim ? 0.35 : 1 }}
              >
                {/* the hit area is the cell plus half the gap on every side, so the grid
                      has no dead space; the visual inside never takes pointer events */}
                <motion.button
                  type="button"
                  data-return-cell={`${y}-${m}`}
                  aria-describedby={on ? tooltipId : undefined}
                  aria-label={`${MONTHS[m]} ${year} ${signed(v, 1)}%`}
                  aria-pressed={isEnd}
                  onPointerEnter={enter(y, m)}
                  onFocus={enter(y, m)}
                  onBlur={() => setHover(null)}
                  onClick={press(y, m)}
                  onKeyDown={clearOnEscape}
                  className="absolute -inset-0.5 block rounded-[5px] outline-none focus-visible:ring-2 focus-visible:ring-ring"
                  whileTap={reduce ? undefined : { scale: 0.92, transition: SPRING_PRESS }}
                >
                  <motion.span
                    className="pointer-events-none absolute inset-0.5 grid place-items-center rounded-[4px] font-mono text-[9px] font-medium tabular-nums"
                    style={{
                      background: tint(v, range, on),
                      color: `color-mix(in srgb, var(--foreground) ${Math.round(85 + Math.min(Math.abs(v) / range, 1) * 15)}%, transparent)`,
                      boxShadow: isEnd ? RING : "none",
                      transition: "background 150ms, box-shadow 150ms",
                    }}
                    initial={reduce ? false : { opacity: 0, scale: 0.6 }}
                    // the diagonal wave on entrance; after it lands the hovered cell lifts,
                    // and hovering the year total replays the row Jan to Dec
                    animate={
                      sweepRow === y && !reduce
                        ? {
                            opacity: 1,
                            // a gentle pulse: kept under the cell gap so a peaking cell
                            // never grows into its neighbours as the wave passes
                            scale: [1, 1.1, 1],
                            transition: { duration: 0.36, ease: EASE_OUT, delay: m * 0.035 },
                          }
                        : settled
                          ? { opacity: 1, scale: lift, transition: SPRING_PRESS }
                          : {
                              opacity: 1,
                              scale: 1,
                              transition: reduce
                                ? { duration: 0 }
                                : { ...SPRING_PRESS, delay: (y + m) * 0.02 },
                            }
                    }
                  >
                    {/* the ring lives INSIDE the cell: inset-0 fills its box and
                          borderRadius:inherit copies its corner, so it always shares the
                          cell's exact size, scale (hover lift included) and roundness and
                          cannot drift however the cells are restyled */}
                    <AnimatePresence>
                      {on && !isEnd ? (
                        <motion.span
                          className="pointer-events-none absolute inset-0 border-[1.5px]"
                          style={{ borderRadius: "inherit", borderColor: v >= 0 ? UP : DOWN }}
                          initial={reduce ? false : { opacity: 0 }}
                          animate={{ opacity: 1 }}
                          exit={{ opacity: 0 }}
                          transition={{ duration: 0.12, ease: EASE_OUT }}
                        />
                      ) : null}
                    </AnimatePresence>
                    {Math.abs(v) >= 4 ? Math.round(v) : ""}
                  </motion.span>
                </motion.button>
              </span>
            );
          })}

          <span
            className="relative block transition-opacity duration-200"
            style={{
              opacity: (
                span
                  ? y < Math.floor(span.lo / 12) || y > Math.floor(span.hi / 12)
                  : yearSpan
                    ? y < yearSpan.lo || y > yearSpan.hi
                    : hot && hot.y !== y
              )
                ? 0.35
                : 1,
            }}
          >
            <motion.button
              type="button"
              data-return-cell={`${y}-${YEAR}`}
              aria-describedby={same(hot, y, YEAR) ? tooltipId : undefined}
              aria-label={`${year} ${signed(totals[y], 1)}% for the year`}
              aria-pressed={yearSpan ? y === yearSpan.lo || y === yearSpan.hi : same(pinned, y, YEAR)}
              onPointerEnter={enter(y, YEAR)}
              onFocus={enter(y, YEAR)}
              onBlur={() => setHover(null)}
              onClick={press(y, YEAR)}
              onKeyDown={clearOnEscape}
              className="absolute -inset-0.5 block rounded-[5px] outline-none focus-visible:ring-2 focus-visible:ring-ring"
              whileTap={reduce ? undefined : { scale: 0.96, transition: SPRING_PRESS }}
            >
              <motion.span
                className="pointer-events-none absolute inset-0.5 grid place-items-center rounded-[4px] font-mono text-[11px] font-medium tabular-nums"
                // a neutral cell under the colored number: the tint of the same hue ate its contrast
                style={{
                  background: same(hot, y, YEAR)
                    ? "var(--background)"
                    : "color-mix(in srgb, var(--foreground) 6%, transparent)",
                  color: ink(totals[y] >= 0 ? UP : DOWN),
                  // the ends of a year span carry the locked ring, like a month span's ends
                  boxShadow: (yearSpan ? y === yearSpan.lo || y === yearSpan.hi : same(pinned, y, YEAR))
                    ? RING
                    : same(hot, y, YEAR)
                      ? "inset 0 0 0 1px var(--border-strong)"
                      : "none",
                  transition: "background 150ms, box-shadow 150ms",
                }}
                initial={reduce ? false : { opacity: 0 }}
                animate={{ opacity: 1 }}
                transition={
                  reduce ? { duration: 0 } : { duration: 0.4, ease: EASE_OUT, delay: 0.02 * (y + 13) }
                }
              >
                {/* the year total gets the same flush hover ring as the month cells,
                      unless it already carries a span-end ring */}
                <AnimatePresence>
                  {same(hot, y, YEAR) &&
                  !(yearSpan ? y === yearSpan.lo || y === yearSpan.hi : same(pinned, y, YEAR)) ? (
                    <motion.span
                      className="pointer-events-none absolute inset-0 border-[1.5px]"
                      style={{ borderRadius: "inherit", borderColor: totals[y] >= 0 ? UP : DOWN }}
                      initial={reduce ? false : { opacity: 0 }}
                      animate={{ opacity: 1 }}
                      exit={{ opacity: 0 }}
                      transition={{ duration: 0.12, ease: EASE_OUT }}
                    />
                  ) : null}
                </AnimatePresence>
                {signed(totals[y], 0)}%
              </motion.span>
            </motion.button>
          </span>
        </div>
      ))}

      {children}
    </div>
  );
}

"use client";
import { type ReactNode, useMemo, useState } from "react";
import { NumberTicker } from "@/components/motion/number-ticker";
import { Tooltip } from "@/components/motion/tooltip";
import { cn } from "@/lib/utils";
import { useReturnsCalendar } from "./context";
import type { ReturnsCalendarCell, ReturnsCalendarTooltipData } from "./types";
import { DOWN, ink, UP } from "./utils";

export function ReturnsCalendarTooltip({
  children,
  className,
}: {
  children?: ReactNode | ((data: ReturnsCalendarTooltipData) => ReactNode);
  className?: string;
}) {
  const { gridRef, tooltipId, tip, tipValue, tipLabel, tipNote } = useReturnsCalendar();
  const [dismissed, setDismissed] = useState<ReturnsCalendarCell | null>(null);
  const anchorRef = useMemo(
    () => ({
      get current() {
        return tip
          ? (gridRef.current?.querySelector<HTMLElement>(`[data-return-cell="${tip.y}-${tip.m}"]`) ?? null)
          : null;
      },
    }),
    [gridRef, tip],
  );
  const data = { label: tipLabel, value: tipValue, note: tipNote };
  return (
    <Tooltip
      key={tip ? `${tip.y}-${tip.m}` : "closed"}
      open={tip !== null && dismissed !== tip}
      onOpenChange={(open) => {
        if (!open) setDismissed(tip);
      }}
      id={tooltipId}
      anchorRef={anchorRef}
      className={cn("flex items-center gap-1.5", className)}
      content={
        typeof children === "function"
          ? children(data)
          : (children ?? (
              <>
                <span className="text-muted-foreground">{tipLabel}</span>
                <span
                  className="inline-flex items-center font-mono tabular-nums"
                  style={{ color: ink(tipValue >= 0 ? UP : DOWN) }}
                >
                  <NumberTicker
                    value={Math.round(Math.abs(tipValue) * 10)}
                    format={(v) => (v / 10).toFixed(1)}
                    prefix={tipValue >= 0 ? "+" : "−"}
                    suffix="%"
                    duration={0.35}
                    startOnView={false}
                  />
                </span>
                {tipNote ? <span className="text-muted-foreground">{tipNote}</span> : null}
              </>
            ))
      }
    />
  );
}

import type { ReactNode } from "react";

/** Zero-based row and month; month 12 selects the year total. */
export type ReturnsCalendarCell = { y: number; m: number };

export interface ReturnsCalendarSelection {
  start: ReturnsCalendarCell;
  end?: ReturnsCalendarCell;
}

export interface ReturnsCalendarProps {
  /** Row labels, one per row of `returns`. */
  years?: number[];
  /** `returns[year][month]` in percent, twelve months per row. */
  returns?: number[][];
  className?: string;
  children?: ReactNode;
  selection?: ReturnsCalendarSelection | null;
  defaultSelection?: ReturnsCalendarSelection | null;
  onSelectionChange?: (selection: ReturnsCalendarSelection | null) => void;
}

export interface ReturnsCalendarTooltipData {
  label: string;
  value: number;
  note: string | null;
}

import type { ReturnsCalendarCell } from "./types";

export const UP = "var(--success)";

export const DOWN = "var(--destructive)";

export const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];

export const COLS = MONTHS.map((name, m) => ({ name, initial: name[0], m }));

/** The compounded column, addressed like a thirteenth month. */
export const YEAR = 12;

/** Compounded return of a run of percentages, in percent. */
export const compound = (run: number[]) => (run.reduce((acc, r) => acc * (1 + r / 100), 1) - 1) * 100;

export const signed = (v: number, dp: number) => `${v >= 0 ? "+" : "−"}${Math.abs(v).toFixed(dp)}`;

/** A hue as text: on the light page its lightness is capped so 11px numbers reach AA while the chroma stays, in dark it is native (`--ink-l` flips per theme on the root). */
export const ink = (c: string) => `oklch(from ${c} min(l, var(--ink-l, 1)) c h)`;

/** magnitude → strength of the one up or down hue, never a second color */
export const tint = (v: number, range: number, on: boolean) =>
  `color-mix(in srgb, ${v >= 0 ? UP : DOWN} ${Math.round(Math.min(Math.abs(v) / range, 1) * 55 + (on ? 24 : 8))}%, transparent)`;

export const same = (a: ReturnsCalendarCell | null, y: number, m: number) => a?.y === y && a?.m === m;

export const RING = "inset 0 0 0 1.5px var(--foreground)";

"use client";

import { animate, motion, useInView, useReducedMotion } from "motion/react";
import { useEffect, useMemo, useRef, useState } from "react";
import { EASE_OUT } from "@/lib/ease";
import { cn } from "@/lib/utils";

export interface NumberTickerProps {
  value: number;
  /** Digits to pad to (left). */
  pad?: number;
  /** Per-digit roll duration in seconds. */
  duration?: number;
  /** Stagger between digits. */
  stagger?: number;
  /** Render only after the element enters the viewport. */
  startOnView?: boolean;
  prefix?: string;
  suffix?: string;
  /** Add a small blur during digit rolls. */
  blur?: boolean;
  className?: string;
  digitClassName?: string;
  /** Insert locale group separators (commas). Server-component safe. */
  locale?: boolean;
  /** Custom formatter. Client-only — server components must use `locale` instead. */
  format?: (value: number) => string;
}

const DIGIT_HEIGHT_EM = 1.1;
const DIGITS = Array.from({ length: 10 }, (_, n) => n);

export function NumberTicker({
  value,
  pad,
  duration = 0.9,
  stagger = 0.04,
  startOnView = true,
  prefix,
  suffix,
  blur = false,
  className,
  digitClassName,
  locale,
  format,
}: NumberTickerProps) {
  const containerRef = useRef<HTMLSpanElement>(null);
  const inView = useInView(containerRef, { once: true, amount: 0.6 });
  const [armed, setArmed] = useState(!startOnView);

  useEffect(() => {
    if (startOnView && inView) setArmed(true);
  }, [startOnView, inView]);

  const text = useMemo(() => {
    const rounded = Math.round(value);
    const formatted = format
      ? format(rounded)
      : locale
        ? rounded.toLocaleString()
        : rounded.toString();
    return pad ? formatted.padStart(pad, "0") : formatted;
  }, [value, pad, format, locale]);
  const glyphs = useMemo(() => {
    const chars = text.split("");
    // Key by place value (position from the right): a changing digit keeps its
    // identity and rolls to the new value instead of remounting and replaying
    // from 0. Growing numbers add glyphs on the left without re-keying the
    // ones, tens, hundreds already on screen.
    return chars.map((char, i) => ({ char, id: `g-${chars.length - 1 - i}` }));
  }, [text]);
  const readableText = `${prefix ?? ""}${text}${suffix ?? ""}`;

  // Stagger is an entrance flourish. Once the reveal has played, value
  // changes roll every digit immediately — a per-digit delay on live updates
  // reads as lag.
  const [entered, setEntered] = useState(false);
  useEffect(() => {
    if (!armed || entered) return;
    const total = (duration + glyphs.length * stagger) * 1000;
    const t = window.setTimeout(() => setEntered(true), total);
    return () => window.clearTimeout(t);
  }, [armed, entered, duration, stagger, glyphs.length]);

  return (
    <span
      ref={containerRef}
      className={cn("inline-flex items-center tabular-nums", className)}
    >
      <span className="sr-only">{readableText}</span>
      <span aria-hidden="true" className="inline-flex items-center">
        {prefix ? <span>{prefix}</span> : null}
        {glyphs.map(({ char, id }, i) => {
          const isDigit = /\d/.test(char);
          if (!isDigit) {
            return (
              <span key={id} className="inline-block">
                {char}
              </span>
            );
          }
          const digit = Number(char);
          return (
            <Digit
              key={id}
              digit={armed ? digit : 0}
              delay={entered ? 0 : i * stagger}
              duration={duration}
              blur={blur}
              className={digitClassName}
            />
          );
        })}
        {suffix ? <span>{suffix}</span> : null}
      </span>
    </span>
  );
}

function Digit({
  digit,
  delay,
  duration,
  blur,
  className,
}: {
  digit: number;
  delay: number;
  duration: number;
  blur: boolean;
  className?: string;
}) {
  const reduce = useReducedMotion();
  const columnRef = useRef<HTMLSpanElement>(null);

  useEffect(() => {
    if (reduce || !blur || !columnRef.current || !Number.isFinite(digit)) {
      return;
    }

    const node = columnRef.current;
    const controls = animate(
      node,
      { filter: ["blur(10px)", "blur(0px)"] },
      {
        duration: Math.min(duration * 0.75, 0.32),
        delay,
        ease: EASE_OUT,
      },
    );

    return () => {
      controls.stop();
      node.style.filter = "blur(0px)";
    };
  }, [blur, delay, digit, duration, reduce]);

  return (
    <span
      className={cn("relative inline-block overflow-hidden", className)}
      style={{ height: `${DIGIT_HEIGHT_EM}em`, width: "1ch" }}
    >
      <motion.span
        ref={columnRef}
        initial={{ y: 0 }}
        animate={{ y: `-${digit * DIGIT_HEIGHT_EM}em` }}
        transition={
          reduce
            ? { duration: 0 }
            : { duration, delay, ease: EASE_OUT }
        }
        className="absolute inset-x-0 top-0 flex flex-col items-center will-change-[transform,filter]"
      >
        {DIGITS.map((n) => (
          <span
            key={n}
            className="flex h-[1.1em] items-center justify-center leading-none"
          >
            {n}
          </span>
        ))}
      </motion.span>
    </span>
  );
}

"use client";

import { AnimatePresence } from "motion/react";
import {
  cloneElement,
  isValidElement,
  type PointerEvent,
  type ReactElement,
  type ReactNode,
  type RefObject,
  useCallback,
  useEffect,
  useId,
  useLayoutEffect,
  useRef,
  useState,
} from "react";
import { createPortal } from "react-dom";
import { TooltipSurface } from "@/components/motion/tooltip-surface";
import { useDismiss } from "@/lib/hooks/use-dismiss";
import { useHoverGesture } from "@/lib/hooks/use-hover-gesture";
import { useTapGesture } from "@/lib/hooks/use-tap-gesture";
import { cn } from "@/lib/utils";

type Side = "top" | "right" | "bottom" | "left";

export interface TooltipProps {
  content: ReactNode;
  children?: ReactElement;
  /** Existing trigger for controlled integrations such as chart cells. */
  anchorRef?: RefObject<HTMLElement | SVGElement | null>;
  /** Point within the anchor, as fractions of its rendered width and height. */
  anchorPoint?: { x: number; y: number };
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
  id?: string;
  side?: Side;
  /** Delay before showing (ms). Default 120. */
  delay?: number;
  className?: string;
  /** Classes for the outer wrapper span. Use to fix baseline / fill parent. */
  wrapperClassName?: string;
}

// Gap between trigger and tooltip, in px.
const GAP = 8;

// Centering transform for the fixed-positioned anchor point, per side.
const anchorTransform: Record<Side, string> = {
  top: "translate(-50%, -100%)",
  bottom: "translate(-50%, 0)",
  left: "translate(-100%, -50%)",
  right: "translate(0, -50%)",
};

const transformOrigin: Record<Side, string> = {
  top: "center bottom",
  bottom: "center top",
  left: "right center",
  right: "left center",
};

// Once any tooltip has just closed, neighbouring tooltips open without the
// initial delay — moving along a toolbar feels instant after the first one.
const WARM_WINDOW_MS = 300;
let lastHiddenAt = 0;

export function Tooltip({
  content,
  children,
  side = "top",
  delay = 120,
  className,
  wrapperClassName,
  anchorRef: externalAnchorRef,
  anchorPoint,
  open: controlledOpen,
  onOpenChange,
  id: providedId,
}: TooltipProps) {
  const [internalOpen, setInternalOpen] = useState(false);
  const open = controlledOpen ?? internalOpen;
  const setOpen = useCallback(
    (next: boolean) => {
      if (controlledOpen === undefined) setInternalOpen(next);
      onOpenChange?.(next);
    },
    [controlledOpen, onOpenChange],
  );
  const [coords, setCoords] = useState<{ top: number; left: number } | null>(null);
  const generatedId = useId();
  const id = providedId ?? generatedId;
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const wrapperRef = useRef<HTMLSpanElement>(null);
  const anchorRef = externalAnchorRef ?? wrapperRef;
  const hover = useHoverGesture();
  const surfaceRef = useRef<HTMLSpanElement>(null);

  // Anchor point in viewport coords, on the edge of the trigger facing `side`.
  // Position:fixed means these viewport coords place the tooltip directly, so
  // it escapes every ancestor's stacking context and overflow.
  const place = useCallback(() => {
    const el = anchorRef.current;
    if (!el) return;
    const r = el.getBoundingClientRect();
    const cx = r.left + r.width * (anchorPoint?.x ?? 0.5);
    const cy = r.top + r.height * (anchorPoint?.y ?? 0.5);
    const point: Record<Side, { top: number; left: number }> = {
      top: { top: (anchorPoint ? cy : r.top) - GAP, left: cx },
      bottom: { top: (anchorPoint ? cy : r.bottom) + GAP, left: cx },
      left: { top: cy, left: (anchorPoint ? cx : r.left) - GAP },
      right: { top: cy, left: (anchorPoint ? cx : r.right) + GAP },
    };
    const next = point[side];
    const width = surfaceRef.current?.offsetWidth ?? 0;
    const height = surfaceRef.current?.offsetHeight ?? 0;
    const dx = side === "left" ? width : side === "right" ? 0 : width / 2;
    const dy = side === "top" ? height : side === "bottom" ? 0 : height / 2;
    next.left = Math.max(GAP + dx, Math.min(next.left, window.innerWidth - GAP - width + dx));
    next.top = Math.max(GAP + dy, Math.min(next.top, window.innerHeight - GAP - height + dy));
    setCoords(previous => previous?.top === next.top && previous.left === next.left ? previous : next);
  }, [side, anchorRef, anchorPoint]);

  const positioned = coords !== null;
  useLayoutEffect(() => {
    if (!open) return;
    place();
    const observer = new ResizeObserver(place);
    if (anchorRef.current) observer.observe(anchorRef.current);
    if (positioned && surfaceRef.current) observer.observe(surfaceRef.current);
    return () => observer.disconnect();
  }, [open, place, anchorRef, positioned]);

  const show = useCallback(() => {
    if (timer.current) clearTimeout(timer.current);
    const warm = Date.now() - lastHiddenAt < WARM_WINDOW_MS;
    timer.current = setTimeout(
      () => {
        place();
        setOpen(true);
      },
      warm ? 0 : delay,
    );
  }, [delay, place, setOpen]);

  const hide = useCallback(() => {
    if (timer.current) {
      clearTimeout(timer.current);
      timer.current = null;
    }
    if (open) lastHiddenAt = Date.now();
    setOpen(false);
  }, [open, setOpen]);

  // A finger never hovers, and Safari does not focus a button on tap either, so
  // the label is only reachable if the tap itself opens the tooltip. A click
  // carries no pointerType, so the pointerdown that preceded it is what says
  // whether this was a tap; keyboard activation arrives with no pointerdown at
  // all, and focus has already shown the label there.
  const tap = useTapGesture<boolean>();

  const toggleOnTap = useCallback(() => {
    const gesture = tap.take();
    if (!gesture || gesture.pointerType === "mouse") return;
    if (gesture.state) {
      hide();
      return;
    }
    if (timer.current) clearTimeout(timer.current);
    place();
    setOpen(true);
  }, [hide, place, tap, setOpen]);

  // ...and closed again by the next tap that lands somewhere else. The label
  // covers nothing interactive, so that tap passes through to what it hit.
  useDismiss(open, hide, anchorRef);

  // Keep the tooltip pinned to the trigger while it's open and the page scrolls
  // or resizes (fixed coords are viewport-relative).
  useEffect(() => {
    if (!open) return;
    const onMove = () => place();
    window.addEventListener("scroll", onMove, true);
    window.addEventListener("resize", onMove);
    return () => {
      window.removeEventListener("scroll", onMove, true);
      window.removeEventListener("resize", onMove);
    };
  }, [open, place]);

  useEffect(
    () => () => {
      if (timer.current) clearTimeout(timer.current);
    },
    [],
  );

  if (!externalAnchorRef && !isValidElement(children)) return children;

  // The label describes the trigger, so it has to name the trigger itself.
  // Everything else the tooltip needs is read off the anchor below instead of
  // cloned on: a handler written onto the child is the child's handler as far
  // as that child can tell, and a component that owns its activation —
  // hard-wiring onClick and spreading the rest of its props over it, as
  // ThemeToggle does — then runs the tooltip's instead of its own. Composing
  // with `props.onClick` cannot save it either, because a component element's
  // props hold nothing the component does internally.
  const trigger = isValidElement(children)
    ? cloneElement(children as ReactElement<Record<string, unknown>>, {
        "aria-describedby": id,
      })
    : null;

  return (
    <>
      {!externalAnchorRef ? (
        // biome-ignore lint/a11y/noStaticElementInteractions: This wrapper observes bubbling trigger events without replacing the control's handlers.
        <span
          ref={wrapperRef}
          className={cn("relative inline-flex align-middle", wrapperClassName)}
          // Pointer events, not the mouse pair: a tap fires compatibility
          // mouseenter/mouseleave that carry no pointerType, which raced the tap
          // path into opening and closing the same label.
          onPointerEnter={(event: PointerEvent) => {
            if (hover.enter(event)) show();
          }}
          onPointerLeave={(event: PointerEvent) => {
            if (hover.leave(event)) hide();
          }}
          onFocus={show}
          onBlur={hide}
          onPointerDown={(event: PointerEvent) => tap.start(event, open)}
          // A gesture the platform took away sends no click, and a key press
          // starts an activation that never had a pointer behind it. Either way
          // the record has to go, or the next click reads a finger that has long
          // since lifted.
          onPointerCancel={tap.drop}
          onKeyDown={tap.drop}
          onClick={toggleOnTap}
        >
          {trigger}
        </span>
      ) : null}
      {typeof document !== "undefined"
        ? createPortal(
            <AnimatePresence>
              {open && coords ? (
                <span
                  className="pointer-events-none fixed z-[9999]"
                  style={{
                    top: coords.top,
                    left: coords.left,
                    transform: anchorTransform[side],
                  }}
                >
                  <TooltipSurface
                    ref={surfaceRef}
                    id={id}
                    side={side}
                    style={{ transformOrigin: transformOrigin[side], maxWidth: "calc(100vw - 16px)", whiteSpace: "normal" }}
                    className={className}
                  >
                    {content}
                  </TooltipSurface>
                </span>
              ) : null}
            </AnimatePresence>,
            document.body,
          )
        : null}
    </>
  );
}