phokus/src/components/Tooltip.tsx

import { MouseEvent, ReactNode, useEffect, useRef, useState } from 'react'
import { createPortal } from 'react-dom'
import { motion } from 'framer-motion'

type TooltipSide = 'top' | 'bottom' | 'left' | 'right'
type TooltipAlign = 'center' | 'start' | 'end'

// Horizontal alignment only applies to top/bottom; left/right center vertically.
function positionClasses(side: TooltipSide, align: TooltipAlign): string {
  if (side === 'left') return 'right-full top-1/2 mr-1.5 -translate-y-1/2'
  if (side === 'right') return 'left-full top-1/2 ml-1.5 -translate-y-1/2'
  const vertical = side === 'top' ? 'bottom-full mb-1.5' : 'top-full mt-1.5'
  const horizontal =
    align === 'start' ? 'left-0' : align === 'end' ? 'right-0' : 'left-1/2 -translate-x-1/2'
  return `${vertical} ${horizontal}`
}

const BASE_CLASSES =
  'pointer-events-none z-50 whitespace-nowrap rounded-md border border-white/10 bg-gray-800 px-2 py-1 text-[11px] text-gray-200 shadow-lg'
const STATIC_CLASSES = `${BASE_CLASSES} transition-opacity duration-100`

/**
 * Lightweight custom tooltip — fades in (faster than the native one) after a
 * tunable hover `delay`, and hides instantly on leave or click. By default it
 * anchors to a `side` of the wrapper. `anchorToCursor` shows at the pointer's
 * entry position; `followCursor` keeps tracking the pointer.
 */
export function Tooltip({
  label,
  delay = 400,
  side = 'bottom',
  align = 'center',
  block = false,
  anchorToCursor = false,
  followCursor = false,
  disabled = false,
  className = '',
  children,
}: {
  label: ReactNode
  /** Milliseconds the pointer must hover before the tooltip appears (0 = instant). */
  delay?: number
  side?: TooltipSide
  /** Horizontal alignment for top/bottom tooltips. */
  align?: TooltipAlign
  /** Full-width block wrapper (e.g. wrapping a grid cell) instead of inline. */
  block?: boolean
  /** Position at the cursor when shown, without following subsequent movement. */
  anchorToCursor?: boolean
  /** Track the cursor (fixed position) instead of anchoring to a side. */
  followCursor?: boolean
  /** Render the wrapper but suppress tooltip display. */
  disabled?: boolean
  /** Extra classes for the wrapper (e.g. layout). */
  className?: string
  children: ReactNode
}) {
  const [visible, setVisible] = useState(false)
  const [coords, setCoords] = useState({ x: 0, y: 0 })
  const [mounted, setMounted] = useState(false)
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
  const frame = useRef<number | undefined>(undefined)
  const tooltipRef = useRef<HTMLSpanElement>(null)

  // Resolve a viewport-safe position near the cursor: below-right by default,
  // but flipped above the cursor if it would overflow the bottom edge, and
  // clamped so it never runs off the right/left.
  const place = (clientX: number, clientY: number) => {
    const tip = tooltipRef.current
    const tipWidth = tip?.offsetWidth ?? 0
    const tipHeight = tip?.offsetHeight ?? 24
    const gap = 16
    let top = clientY + gap
    if (top + tipHeight > window.innerHeight - 4) {
      top = clientY - gap - tipHeight
    }
    let left = clientX + 14
    if (left + tipWidth > window.innerWidth - 4) left = window.innerWidth - 4 - tipWidth
    if (left < 4) left = 4
    setCoords({ x: left, y: top })
  }

  const clear = () => {
    if (timer.current) clearTimeout(timer.current)
    timer.current = undefined
    if (frame.current !== undefined) cancelAnimationFrame(frame.current)
    frame.current = undefined
  }
  const show = (event: MouseEvent<HTMLElement>) => {
    if (disabled) return
    clear()
    if (anchorToCursor || followCursor) place(event.clientX, event.clientY)
    if (delay <= 0) {
      setVisible(true)
      return
    }
    timer.current = setTimeout(() => setVisible(true), delay)
  }
  const hide = () => {
    clear()
    setVisible(false)
  }
  const move = (event: MouseEvent<HTMLElement>) => {
    if (!followCursor) return
    const { clientX, clientY } = event
    if (frame.current !== undefined) cancelAnimationFrame(frame.current)
    frame.current = requestAnimationFrame(() => {
      frame.current = undefined
      place(clientX, clientY)
    })
  }

  useEffect(() => {
    setMounted(true)
    return clear
  }, [])

  useEffect(() => {
    if (disabled) hide()
  }, [disabled])

  const Wrapper = block ? 'div' : 'span'
  const cursorTooltip = (
    <motion.span
      ref={tooltipRef}
      role="tooltip"
      aria-hidden={!visible}
      // Portaled + fixed so transformed parents and scroll containers cannot
      // distort cursor-anchored tooltip coordinates.
      className={`fixed ${BASE_CLASSES}`}
      initial={false}
      animate={{ left: coords.x, top: coords.y, opacity: visible ? 1 : 0 }}
      transition={{
        left: followCursor
          ? { type: 'spring', stiffness: 700, damping: 45, mass: 0.35 }
          : { duration: 0 },
        top: followCursor
          ? { type: 'spring', stiffness: 520, damping: 34, mass: 0.45 }
          : { duration: 0 },
        opacity: { duration: visible ? 0.1 : 0.05 },
      }}
    >
      {label}
    </motion.span>
  )

  return (
    <Wrapper
      className={`${block ? 'relative block w-full' : 'relative inline-flex'} ${className}`}
      onMouseEnter={show}
      onMouseMove={followCursor ? move : undefined}
      onMouseLeave={hide}
      onPointerDown={hide}
    >
      {children}
      {disabled ? null : anchorToCursor || followCursor ? (
        mounted ? (
          createPortal(cursorTooltip, document.body)
        ) : null
      ) : (
        <span
          role="tooltip"
          aria-hidden={!visible}
          className={`absolute ${STATIC_CLASSES} ${positionClasses(side, align)} ${visible ? 'opacity-100' : 'opacity-0'}`}
        >
          {label}
        </span>
      )}
    </Wrapper>
  )
}