Tooltip

1'use client';
2
3import { AnimatePresence, type HTMLMotionProps, motion, useReducedMotion } from 'motion/react';
4import * as React from 'react';
5import { cn } from '../lib/cn';
6import { FloatingPortal, useFloating } from '../lib/floating';
7import { floatingOrigin, floatingVariants, reveal } from '../lib/motion';
8import { assignRef, getFocusable, useLayer } from '../lib/overlay';
9import { useControllableState } from '../lib/use-controllable-state';
10
11const TOOLTIP_ARROW_CLASSES = {
12  top: '-bottom-1 left-1/2 -translate-x-1/2',
13  bottom: '-top-1 left-1/2 -translate-x-1/2',
14  left: '-right-1 top-1/2 -translate-y-1/2',
15  right: '-left-1 top-1/2 -translate-y-1/2',
16} as const;
17
18const TOOLTIP_STYLE = { willChange: 'opacity, transform, filter' } as const;
19
20const CLOSE_DELAY = 100;
21const LONG_PRESS_DELAY = 500;
22const ARROW_INSET = 8;
23
24type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
25
26interface TooltipContextType {
27  open: boolean;
28  setOpen: (open: boolean) => void;
29  delayDuration: number;
30  id: string;
31  triggerRef: React.RefObject<HTMLElement | null>;
32  contentRef: React.RefObject<HTMLDivElement | null>;
33  schedule: (open: boolean, delay: number) => void;
34  cancel: () => void;
35}
36
37const TooltipContext = React.createContext<TooltipContextType | undefined>(undefined);
38
39const useTooltip = () => {
40  const context = React.use(TooltipContext);
41  if (!context) {
42    throw new Error('useTooltip must be used within a TooltipProvider');
43  }
44  return context;
45};
46
47interface TooltipProps {
48  children: React.ReactNode;
49  delayDuration?: number;
50  defaultOpen?: boolean;
51  open?: boolean;
52  onOpenChange?: (open: boolean) => void;
53}
54
55const TooltipRoot = ({
56  children,
57  delayDuration = 200,
58  defaultOpen = false,
59  open: controlledOpen,
60  onOpenChange,
61}: TooltipProps) => {
62  const [open, setOpen] = useControllableState({
63    value: controlledOpen,
64    defaultValue: defaultOpen,
65    onChange: onOpenChange,
66  });
67
68  const id = React.useId();
69  const triggerRef = React.useRef<HTMLElement>(null);
70  const contentRef = React.useRef<HTMLDivElement>(null);
71  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
72  const layer = useLayer(open, false, contentRef);
73
74  const cancel = React.useCallback(() => {
75    if (timerRef.current) clearTimeout(timerRef.current);
76    timerRef.current = null;
77  }, []);
78
79  const schedule = React.useCallback(
80    (next: boolean, delay: number) => {
81      cancel();
82      timerRef.current = setTimeout(() => {
83        timerRef.current = null;
84        setOpen(next);
85      }, delay);
86    },
87    [cancel, setOpen],
88  );
89
90  React.useEffect(() => cancel, [cancel]);
91
92  React.useEffect(() => {
93    if (!open) return;
94    const handlePointerDown = (event: PointerEvent) => {
95      const target = event.target as Node | null;
96      if (!target) return;
97      if (triggerRef.current?.contains(target) || contentRef.current?.contains(target)) return;
98      cancel();
99      setOpen(false);
100    };
101    const handleEscape = (event: KeyboardEvent) => {
102      if (event.key !== 'Escape' || event.defaultPrevented || !layer.isTopmost()) return;
103      event.preventDefault();
104      cancel();
105      setOpen(false);
106    };
107    document.addEventListener('pointerdown', handlePointerDown);
108    document.addEventListener('keydown', handleEscape);
109    return () => {
110      document.removeEventListener('pointerdown', handlePointerDown);
111      document.removeEventListener('keydown', handleEscape);
112    };
113  }, [open, setOpen, cancel, layer]);
114
115  const contextValue = React.useMemo(
116    () => ({ open, setOpen, delayDuration, id, triggerRef, contentRef, schedule, cancel }),
117    [open, setOpen, delayDuration, id, schedule, cancel],
118  );
119
120  return (
121    <TooltipContext value={contextValue}>
122      <span className="relative inline-flex h-fit w-fit items-center justify-center">
123        {children}
124      </span>
125    </TooltipContext>
126  );
127};
128
129interface TooltipTriggerProps extends React.HTMLAttributes<HTMLElement> {
130  asChild?: boolean;
131}
132
133type TriggerHandlers = {
134  onPointerEnter?: (event: React.PointerEvent<HTMLElement>) => void;
135  onPointerLeave?: (event: React.PointerEvent<HTMLElement>) => void;
136  onPointerDown?: (event: React.PointerEvent<HTMLElement>) => void;
137  onPointerUp?: (event: React.PointerEvent<HTMLElement>) => void;
138  onPointerCancel?: (event: React.PointerEvent<HTMLElement>) => void;
139  onClick?: (event: React.MouseEvent<HTMLElement>) => void;
140  onFocus?: (event: React.FocusEvent<HTMLElement>) => void;
141  onBlur?: (event: React.FocusEvent<HTMLElement>) => void;
142};
143
144function joinIds(...ids: Array<string | undefined>) {
145  return ids.filter(Boolean).join(' ') || undefined;
146}
147
148function TooltipTrigger({ children, asChild = false, className, ...props }: TooltipTriggerProps) {
149  const { open, setOpen, delayDuration, id, triggerRef, schedule, cancel } = useTooltip();
150  const pointerTypeRef = React.useRef<string | null>(null);
151  const [nestedTarget, setNestedTarget] = React.useState<HTMLElement | null>(null);
152
153  const wrapperRef = React.useCallback(
154    (node: HTMLSpanElement | null) => {
155      triggerRef.current = node;
156      setNestedTarget(node ? (getFocusable(node)[0] ?? null) : null);
157    },
158    [triggerRef],
159  );
160
161  React.useEffect(() => {
162    if (!open || !nestedTarget) return;
163    const previous = nestedTarget.getAttribute('aria-describedby');
164    nestedTarget.setAttribute('aria-describedby', previous ? `${previous} ${id}` : id);
165    return () => {
166      if (previous === null) nestedTarget.removeAttribute('aria-describedby');
167      else nestedTarget.setAttribute('aria-describedby', previous);
168    };
169  }, [open, nestedTarget, id]);
170
171  const slotted = asChild && React.isValidElement(children);
172  const childProps = (slotted ? (children as React.ReactElement).props : {}) as TriggerHandlers & {
173    className?: string;
174    ref?: React.Ref<HTMLElement>;
175    'aria-describedby'?: string;
176  };
177
178  const handlers: TriggerHandlers = {
179    onPointerEnter: (event) => {
180      if (event.pointerType !== 'touch') schedule(true, delayDuration);
181      props.onPointerEnter?.(event);
182      childProps.onPointerEnter?.(event);
183    },
184    onPointerLeave: (event) => {
185      if (event.pointerType !== 'touch') schedule(false, CLOSE_DELAY);
186      else if (!open) cancel();
187      props.onPointerLeave?.(event);
188      childProps.onPointerLeave?.(event);
189    },
190    onPointerDown: (event) => {
191      pointerTypeRef.current = event.pointerType;
192      if (event.pointerType === 'touch') schedule(true, LONG_PRESS_DELAY);
193      props.onPointerDown?.(event);
194      childProps.onPointerDown?.(event);
195    },
196    onPointerUp: (event) => {
197      if (event.pointerType === 'touch' && !open) cancel();
198      props.onPointerUp?.(event);
199      childProps.onPointerUp?.(event);
200    },
201    onPointerCancel: (event) => {
202      if (event.pointerType === 'touch' && !open) cancel();
203      props.onPointerCancel?.(event);
204      childProps.onPointerCancel?.(event);
205    },
206    onClick: (event) => {
207      pointerTypeRef.current = null;
208      props.onClick?.(event);
209      childProps.onClick?.(event);
210    },
211    onFocus: (event) => {
212      if (pointerTypeRef.current !== 'touch') {
213        cancel();
214        setOpen(true);
215      }
216      props.onFocus?.(event);
217      childProps.onFocus?.(event);
218    },
219    onBlur: (event) => {
220      cancel();
221      setOpen(false);
222      props.onBlur?.(event);
223      childProps.onBlur?.(event);
224    },
225  };
226
227  if (slotted) {
228    const baseDescribedBy = childProps['aria-describedby'] ?? props['aria-describedby'];
229
230    return React.cloneElement(children as React.ReactElement<Record<string, unknown>>, {
231      ...props,
232      ...handlers,
233      'aria-describedby': open ? joinIds(baseDescribedBy, id) : baseDescribedBy,
234      className: cn(className, childProps.className),
235      ref: (node: HTMLElement | null) => {
236        triggerRef.current = node;
237        assignRef(childProps.ref, node);
238      },
239    });
240  }
241
242  const describedBy =
243    open && !nestedTarget ? joinIds(props['aria-describedby'], id) : props['aria-describedby'];
244
245  return (
246    <span
247      tabIndex={nestedTarget ? undefined : 0}
248      className={cn('cursor-pointer', className)}
249      {...props}
250      {...handlers}
251      aria-describedby={describedBy}
252      ref={wrapperRef}
253    >
254      {children}
255    </span>
256  );
257}
258
259interface TooltipContentProps extends HTMLMotionProps<'div'> {
260  side?: TooltipSide;
261  sideOffset?: number;
262  children?: React.ReactNode;
263}
264
265const TooltipPanel = ({
266  side: preferredSide = 'top',
267  sideOffset = 4,
268  className,
269  children,
270  style,
271  onPointerEnter,
272  onPointerLeave,
273  ...props
274}: TooltipContentProps) => {
275  const { id, triggerRef, contentRef, schedule, cancel } = useTooltip();
276  const shouldReduceMotion = useReducedMotion();
277  const arrowRef = React.useRef<HTMLSpanElement>(null);
278  const floating = useFloating({
279    open: true,
280    anchorRef: triggerRef,
281    floatingRef: contentRef,
282    side: preferredSide,
283    sideOffset,
284  });
285  const side = floating.side;
286  const top = floating.style.top;
287  const left = floating.style.left;
288
289  React.useLayoutEffect(() => {
290    const arrow = arrowRef.current;
291    const content = contentRef.current;
292    const anchor = triggerRef.current;
293    if (!arrow || !content || !anchor) return;
294    const rect = anchor.getBoundingClientRect();
295    const vertical = side === 'top' || side === 'bottom';
296    const size = vertical ? content.offsetWidth : content.offsetHeight;
297    const center = vertical
298      ? rect.left + rect.width / 2 - Number(left)
299      : rect.top + rect.height / 2 - Number(top);
300    const offset = Math.min(
301      Math.max(center, ARROW_INSET),
302      Math.max(ARROW_INSET, size - ARROW_INSET),
303    );
304    arrow.style.left = vertical ? `${offset}px` : '';
305    arrow.style.top = vertical ? '' : `${offset}px`;
306  }, [side, top, left, contentRef, triggerRef]);
307
308  return (
309    <motion.div
310      ref={contentRef}
311      id={id}
312      role="tooltip"
313      data-side={side}
314      variants={shouldReduceMotion ? reveal : floatingVariants[side]}
315      initial="hidden"
316      animate="visible"
317      exit="exit"
318      style={{ ...TOOLTIP_STYLE, ...style, ...floating.style }}
319      onPointerEnter={(event) => {
320        onPointerEnter?.(event);
321        cancel();
322      }}
323      onPointerLeave={(event) => {
324        onPointerLeave?.(event);
325        if (event.pointerType !== 'touch') schedule(false, CLOSE_DELAY);
326      }}
327      className={cn(
328        'bg-foreground text-background z-500 w-max max-w-[min(20rem,calc(100vw-2rem))] rounded-sm px-2.5 py-1 text-xs whitespace-normal',
329        floatingOrigin[side],
330        className,
331      )}
332      {...props}
333    >
334      <span
335        ref={arrowRef}
336        aria-hidden="true"
337        className={cn(
338          'bg-foreground absolute size-2 rotate-45 rounded-[1px]',
339          TOOLTIP_ARROW_CLASSES[side],
340        )}
341      />
342      {children as React.ReactNode}
343    </motion.div>
344  );
345};
346
347const TooltipContent = (props: TooltipContentProps) => {
348  const { open } = useTooltip();
349
350  return (
351    <FloatingPortal>
352      <AnimatePresence>{open && <TooltipPanel {...props} />}</AnimatePresence>
353    </FloatingPortal>
354  );
355};
356
357const Tooltip = Object.assign(TooltipRoot, {
358  Trigger: TooltipTrigger,
359  Content: TooltipContent,
360});
361
362const TooltipProvider = Tooltip;
363
364export { Tooltip, TooltipProvider };
365export type { TooltipProps, TooltipTriggerProps, TooltipContentProps, TooltipSide };