@lovett/ui 0.0.10 → 0.1.0

package/src/tooltip.tsx

@@ -0,0 +1,297 @@
+/**
+ * Tooltip — a short, non-interactive label that appears on hover or focus.
+ *
+ * Wraps ONE trigger element (always "asChild": the child is cloned with the
+ * ref, the hover / focus handlers and `aria-describedby`; no wrapper node is
+ * added). The tip is `role="tooltip"`, portals to `document.body`, positions
+ * through `useAnchoredPosition` (default: above, centred; flips below when
+ * there is no room), enters with `.ds-enter-pop` once positioned, and is
+ * `pointer-events: none` so it never blocks the thing under it.
+ *
+ * Timing: hover opens after `openDelay` (300 ms) and closes after
+ * `closeDelay` (0 ms) — the delay is what keeps a mouse sweeping across a
+ * toolbar from flashing every label. Keyboard focus opens IMMEDIATELY (a
+ * keyboard user has already committed to the control); a focus that arrives
+ * by pointer (clicking a button) does not open it, and pressing the trigger
+ * dismisses it. Escape dismisses through the shared layer stack, so it never
+ * steals the keypress from a Modal underneath — a tooltip is pushed above
+ * the modal only while it is showing.
+ *
+ * Never traps or moves focus: the tip is not focusable and the trigger keeps
+ * whatever focus it had. Only non-interactive content belongs in it — the
+ * trigger should still have its own accessible name (`aria-label`) when it
+ * is icon-only; the tooltip DESCRIBES, it does not name.
+ *
+ * Promoted per ADR-0030 Decision G (meta-ads-audit-dashboard task manager:
+ * truncated cells, icon-only row actions, relative timestamps). Second
+ * consumer is the workspace app, which hand-rolls two today —
+ * `tools/_shared/calc/info-tip.tsx` and
+ * `components/ui/sidebar/rail-tooltip.tsx` — and leans on 900+ `title`
+ * attributes elsewhere.
+ *
+ * Token discipline: token-only inline surface like Kbd — INTERNAL
+ * `--popover` / `--popover-foreground` (allowed inside packages/ui) with
+ * public `--border`, `--shadow-md`, `--radius-sm`, `--space-*`. The same
+ * chrome family as Popover / DropdownMenu, so a tip and a menu read as one
+ * system. Geometry from the hook; motion from `.ds-enter-pop`, which
+ * honours prefers-reduced-motion in styles.css.
+ *
+ * Usage:
+ *
+ *   <Tooltip content="Archive task">
+ *     <Button variant="secondary" aria-label="Archive task"><Archive /></Button>
+ *   </Tooltip>
+ *
+ *   <Tooltip content={fullTitle} side="bottom" align="start">
+ *     <span className="truncate">{fullTitle}</span>
+ *   </Tooltip>
+ */
+
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type FocusEvent as ReactFocusEvent,
+  type HTMLAttributes,
+  type PointerEvent as ReactPointerEvent,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from 'react'
+import { createPortal } from 'react-dom'
+import { cn } from './lib/utils'
+import { composeRefs } from './lib/refs'
+import { useLayer } from './lib/layer-stack'
+import { useAnchoredPosition, type AnchorAlign, type AnchorSide } from './lib/anchor'
+
+export interface TooltipProps {
+  /** The tip's content. Nothing renders (children pass through untouched) when null. */
+  content: ReactNode
+  /** Exactly one element — it becomes the trigger. */
+  children: ReactElement<TooltipTriggerProps>
+  /** Default `top`. Flips when it cannot fit. */
+  side?: AnchorSide
+  /** Default `center`. */
+  align?: AnchorAlign
+  /** Gap from the trigger, px. Default 6. */
+  offset?: number
+  /** Hover-open delay, ms. Default 300. Focus opens immediately. */
+  openDelay?: number
+  /** Close delay, ms. Default 0. */
+  closeDelay?: number
+  /** Controlled open state. Omit for internal state. */
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** Extra classes on the tip surface. */
+  className?: string
+}
+
+/** What the cloned trigger element must accept. */
+export type TooltipTriggerProps = HTMLAttributes<HTMLElement> & {
+  ref?: Ref<HTMLElement>
+}
+
+const TOOLTIP_SURFACE_STYLE: CSSProperties = {
+  background: 'rgb(var(--popover))',
+  color: 'rgb(var(--popover-foreground))',
+  border: '1px solid rgb(var(--border))',
+  boxShadow: 'var(--shadow-md)',
+  borderRadius: 'var(--radius-sm)',
+  padding: 'var(--space-1) var(--space-2)',
+}
+
+export function Tooltip({
+  content,
+  children,
+  side = 'top',
+  align = 'center',
+  offset = 6,
+  openDelay = 300,
+  closeDelay = 0,
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  className,
+}: TooltipProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(Boolean(defaultOpen))
+  const isControlled = openProp !== undefined
+  const open = isControlled ? Boolean(openProp) : uncontrolledOpen
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isControlled) setUncontrolledOpen(next)
+      onOpenChange?.(next)
+    },
+    [isControlled, onOpenChange],
+  )
+
+  const triggerRef = useRef<HTMLElement | null>(null)
+  const tipRef = useRef<HTMLDivElement | null>(null)
+  const timerRef = useRef<number | null>(null)
+  // Set on pointerdown, cleared on the next pointerup / pointercancel
+  // anywhere: a focus that arrives during that window came from the pointer,
+  // not the keyboard. The document listener is held in a ref so an
+  // interrupted press (unmount mid-press, a second pointerdown) removes it
+  // rather than leaving a stale closure on document.
+  const pointerDownRef = useRef(false)
+  const pressEndListenerRef = useRef<(() => void) | null>(null)
+  const clearPressEndListener = useCallback(() => {
+    const listener = pressEndListenerRef.current
+    if (listener === null) return
+    pressEndListenerRef.current = null
+    document.removeEventListener('pointerup', listener)
+    document.removeEventListener('pointercancel', listener)
+  }, [])
+  useEffect(() => clearPressEndListener, [clearPressEndListener])
+
+  const tipId = `tooltip-${useId().replace(/[^a-zA-Z0-9_-]/g, '')}`
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      window.clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+  }, [])
+  useEffect(() => clearTimer, [clearTimer])
+
+  const scheduleOpen = useCallback(
+    (delay: number) => {
+      clearTimer()
+      if (delay <= 0) {
+        setOpen(true)
+        return
+      }
+      timerRef.current = window.setTimeout(() => {
+        timerRef.current = null
+        setOpen(true)
+      }, delay)
+    },
+    [clearTimer, setOpen],
+  )
+  const scheduleClose = useCallback(
+    (delay: number) => {
+      clearTimer()
+      if (delay <= 0) {
+        setOpen(false)
+        return
+      }
+      timerRef.current = window.setTimeout(() => {
+        timerRef.current = null
+        setOpen(false)
+      }, delay)
+    },
+    [clearTimer, setOpen],
+  )
+
+  const {
+    ref: positionRef,
+    style: positionStyle,
+    placement,
+    positioned,
+  } = useAnchoredPosition<HTMLDivElement>({
+    anchorRef: triggerRef,
+    side,
+    align,
+    offset,
+    enabled: open,
+  })
+
+  useLayer({
+    enabled: open,
+    kind: 'popover',
+    elementRef: tipRef,
+    onEscape: () => {
+      clearTimer()
+      setOpen(false)
+    },
+  })
+
+  const tipRefs = useMemo(
+    () => composeRefs<HTMLDivElement>(tipRef, positionRef),
+    [positionRef],
+  )
+
+  if (!isValidElement<TooltipTriggerProps>(children)) {
+    throw new Error('Tooltip expects exactly one element child to use as its trigger.')
+  }
+  if (content === null || content === undefined || content === false) return children
+
+  const childProps = children.props
+  const describedBy = open
+    ? [childProps['aria-describedby'], tipId].filter(Boolean).join(' ')
+    : childProps['aria-describedby']
+
+  const trigger = cloneElement(children, {
+    ref: composeRefs<HTMLElement>(childProps.ref, triggerRef),
+    'aria-describedby': describedBy,
+    onPointerEnter: (event: ReactPointerEvent<HTMLElement>) => {
+      childProps.onPointerEnter?.(event)
+      // Touch has no hover; a long-press tooltip is a different pattern.
+      if (event.pointerType === 'touch') return
+      scheduleOpen(openDelay)
+    },
+    onPointerLeave: (event: ReactPointerEvent<HTMLElement>) => {
+      childProps.onPointerLeave?.(event)
+      scheduleClose(closeDelay)
+    },
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => {
+      childProps.onPointerDown?.(event)
+      pointerDownRef.current = true
+      clearPressEndListener()
+      const onPressEnd = () => {
+        pointerDownRef.current = false
+        clearPressEndListener()
+      }
+      pressEndListenerRef.current = onPressEnd
+      document.addEventListener('pointerup', onPressEnd)
+      document.addEventListener('pointercancel', onPressEnd)
+      // Pressing the trigger is the user acting on it; the label is in the way.
+      clearTimer()
+      setOpen(false)
+    },
+    onFocus: (event: ReactFocusEvent<HTMLElement>) => {
+      childProps.onFocus?.(event)
+      if (pointerDownRef.current) return
+      scheduleOpen(0)
+    },
+    onBlur: (event: ReactFocusEvent<HTMLElement>) => {
+      childProps.onBlur?.(event)
+      scheduleClose(0)
+    },
+  })
+
+  return (
+    <>
+      {trigger}
+      {open && typeof document !== 'undefined'
+        ? createPortal(
+            <div
+              ref={tipRefs}
+              id={tipId}
+              role="tooltip"
+              data-slot="tooltip"
+              data-state="open"
+              data-side={placement?.side}
+              data-align={placement?.align}
+              data-positioned={positioned ? 'true' : 'false'}
+              className={cn(
+                'pointer-events-none fixed z-[110] max-w-xs text-xs font-medium leading-snug',
+                positioned && 'ds-enter-pop',
+                className,
+              )}
+              style={{ ...positionStyle, ...TOOLTIP_SURFACE_STYLE }}
+            >
+              {content}
+            </div>,
+            document.body,
+          )
+        : null}
+    </>
+  )
+}