Tooltip

"use client";

import { Tooltip as BaseTooltip } from "@base-ui-components/react/tooltip";
import type * as React from "react";
import { cn } from "@/lib/ledger/cn";

/**
 * The system's one floating-context surface.
 *
 * Two components, and the distinction is not cosmetic — it is the whole point:
 *
 * - `Tooltip` labels something already on screen. Hover and focus only. It is
 *   unreachable on touch by design, so it may only ever carry a *restatement*
 *   — the unabbreviated figure, the full timestamp, the untruncated name.
 * - `InfoTip` carries context that is genuinely additional. It is a real
 *   button, so it opens on press as well as on hover, which makes it the only
 *   one of the two a touch user can open.
 *
 * The rule that follows: if a sentence would be lost on a phone, it belongs in
 * an `InfoTip` (or inline), never in a `Tooltip`.
 */

export const TOOLTIP_DELAY = 400;

/** e2, radius 8, hairline + shadow. Shared so the two never drift apart. */
export const TOOLTIP_SURFACE = cn(
  "z-tooltip max-w-[264px] rounded-sm border border-border bg-surface-raised",
  "px-3 py-2 text-caption text-text-primary shadow-elevation-2",
);

/**
 * Enter 140ms, exit 100ms, opacity + scale only. `data-instant` is set by Base
 * UI when a tooltip opens without its delay — hovering along a toolbar after
 * the first one is already open — and it must skip the animation too, or the
 * "instant" second tooltip still visibly fades.
 */
export const TOOLTIP_MOTION = cn(
  "origin-[var(--transform-origin)] transition-[opacity,transform] duration-2 ease-out",
  "data-[starting-style]:scale-[0.97] data-[starting-style]:opacity-0",
  "data-[ending-style]:scale-[0.97] data-[ending-style]:opacity-0 data-[ending-style]:duration-1",
  "data-[instant]:duration-0",
);

export interface TooltipProviderProps {
  children?: React.ReactNode;
  closeDelay?: number;
  /** Before the first tooltip in a group. Subsequent ones open instantly. */
  delay?: number;
}

/**
 * Wrap a surface — a toolbar, a table, an app — so its tooltips share one
 * delay. Without it every tooltip waits 400ms independently, which makes a
 * dense toolbar feel unresponsive; with it, only the first one waits.
 */
export function TooltipProvider({ children, delay = TOOLTIP_DELAY, closeDelay = 0 }: TooltipProviderProps) {
  return (
    <BaseTooltip.Provider closeDelay={closeDelay} delay={delay}>
      {children}
    </BaseTooltip.Provider>
  );
}

export type TooltipSide = "top" | "bottom" | "left" | "right";
export type TooltipAlign = "start" | "center" | "end";

export interface TooltipProps {
  align?: TooltipAlign;
  children: React.ReactNode;
  /** Classes for the popup. */
  className?: string;
  /** Supplementary only. Never the sole home of anything a user must read. */
  content: React.ReactNode;
  /** Overrides the provider's delay for this one trigger. */
  delay?: number;
  disabled?: boolean;
  /**
   * The trigger's own display. `inline` wraps a phrase inside a line;
   * `block` is for a child that fills its column — a truncating cell, a table
   * memo — where an inline trigger would shrink-wrap it and defeat the
   * ellipsis it exists to reveal.
   */
  display?: "inline" | "block";
  side?: TooltipSide;
  /** Classes for the trigger element, not the popup. */
  triggerClassName?: string;
}

/**
 * `content` is nullable on purpose: a truncated cell has a tooltip and a short
 * one does not, and the call site should not have to branch.
 */
export function Tooltip({
  content,
  children,
  side = "top",
  align = "center",
  delay,
  disabled,
  display = "inline",
  triggerClassName,
  className,
}: TooltipProps) {
  if (disabled || content == null || content === "") return <>{children}</>;

  return (
    <BaseTooltip.Root>
      {/* The trigger is our own element with `children` inside it, rather than
          Base UI cloning the caller's element via `render={children}`.

          That looks like the tidier API and it is a trap: a Server Component
          hands its JSX children across the boundary as a *lazy* node, not an
          element — `isValidElement` is false and `type` is undefined — so the
          clone renders `undefined` and the page throws. Rendering the child as
          a child sidesteps it entirely, and works from either side. */}
      <BaseTooltip.Trigger
        className={cn(display === "block" ? "block min-w-0" : "inline", triggerClassName)}
        delay={delay}
        render={<span />}
      >
        {children}
      </BaseTooltip.Trigger>
      <BaseTooltip.Portal>
        <BaseTooltip.Positioner align={align} className="z-tooltip" side={side} sideOffset={8}>
          <BaseTooltip.Popup className={cn(TOOLTIP_SURFACE, TOOLTIP_MOTION, className)}>
            {content}
          </BaseTooltip.Popup>
        </BaseTooltip.Positioner>
      </BaseTooltip.Portal>
    </BaseTooltip.Root>
  );
}