@slithy/base-ui 0.1.0 → 0.2.0

package/src/Tooltip/Tooltip.tsx

@@ -7,269 +7,344 @@ import {
   useContext,
   useEffect,
   useRef,
-  useState,
   type ComponentPropsWithoutRef,
   type ReactElement,
   type ReactNode,
-  type RefObject,
 } from "react";
-import "./Tooltip.css";
+import { useTooltipStore, type TooltipPositionConfig } from "./TooltipStore";
 
 /* ------------------------------------------------------------------ */
-/*  Deferred rendering — avoids mounting Base UI hooks/positioning     */
-/*  until the user actually interacts with the trigger.                */
+/*  Context — connects Trigger to Portal content                       */
 /* ------------------------------------------------------------------ */
 
-interface DeferredState {
-  activated: boolean;
-  activate: () => void;
-  isHoveringRef: RefObject<boolean>;
-  shouldRefocusRef: RefObject<boolean>;
+interface TooltipContext {
+  contentRef: React.RefObject<ReactNode | null>;
+  triggerRef: React.RefObject<HTMLElement | null>;
+  disabled: boolean;
   touchDisabled: boolean;
+  /** Whether the popup can be hovered without closing (hover card behavior) */
+  hoverable: boolean;
+  delay: number;
+  closeDelay: number;
+  /** Warm-up window in ms. If the previous tooltip closed within this window,
+   *  the next tooltip opens instantly (no delay). @default 300 */
+  warmUpDelay: number;
+  positionConfig: TooltipPositionConfig;
 }
 
-const DeferredContext = createContext<DeferredState | null>(null);
+const TooltipCtx = createContext<TooltipContext | null>(null);
 
 /* ------------------------------------------------------------------ */
-/*  Provider (passthrough)                                             */
+/*  Root — context provider                                            */
 /* ------------------------------------------------------------------ */
 
-const Provider = BaseTooltip.Provider;
-
-/* ------------------------------------------------------------------ */
-/*  Root — owns the activation latch                                   */
-/* ------------------------------------------------------------------ */
-
-type RootProps = ComponentPropsWithoutRef<typeof BaseTooltip.Root> & {
+type RootProps = {
   children?: ReactNode;
-  /** Block activation from touch interactions. Defaults to `true`. */
+  /** Controlled open state. */
+  open?: boolean;
+  /** Open on first render (uncontrolled). */
+  defaultOpen?: boolean;
+  disabled?: boolean;
+  /** Block activation from touch interactions. @default true */
   touchDisabled?: boolean;
-  /** Unmount Base UI after close animation completes, returning to the
-   *  lightweight pre-activation state. Defaults to `false`. */
-  unmountOnClose?: boolean;
+  /** Allow hovering into the popup without closing (hover card behavior). @default false */
+  hoverable?: boolean;
+  /** Delay before opening in ms. @default 600 */
+  delay?: number;
+  /** Delay before closing in ms. @default 300 */
+  closeDelay?: number;
+  /** Warm-up window in ms. If a tooltip closed within this window,
+   *  the next one opens instantly. @default 300 */
+  warmUpDelay?: number;
+  /** Which side of the trigger to place the popup. @default "top" */
+  side?: TooltipPositionConfig["side"];
+  /** Distance between trigger and popup in pixels. @default 6 */
+  sideOffset?: number;
+  /** Alignment relative to the trigger. @default "center" */
+  align?: TooltipPositionConfig["align"];
+  /** Offset along the alignment axis in pixels. @default 0 */
+  alignOffset?: number;
+  /** Padding from viewport edges for collision detection. @default 5 */
+  collisionPadding?: TooltipPositionConfig["collisionPadding"];
 };
 
 function Root({
   children,
   open,
   defaultOpen,
-  disabled,
+  disabled = false,
   touchDisabled = true,
-  unmountOnClose = false,
-  onOpenChangeComplete,
-  ...props
+  hoverable = false,
+  delay = 600,
+  closeDelay = 300,
+  warmUpDelay = 300,
+  side,
+  sideOffset,
+  align,
+  alignOffset,
+  collisionPadding,
 }: RootProps) {
-  const [wasActivated, setWasActivated] = useState(false);
-  const isHoveringRef = useRef(false);
-  const shouldRefocusRef = useRef(false);
-
-  // One-way latch: once true, stays true so leave animations can play.
-  // Controlled `open` or `defaultOpen` bypass the latch entirely.
-  // When unmountOnClose is true, the latch resets after close completes.
-  const activated = wasActivated || !!open || !!defaultOpen;
-
-  const activate = useCallback(() => {
-    if (!disabled) setWasActivated(true);
-  }, [disabled]);
-
-  const ctx: DeferredState = {
-    activated,
-    activate,
-    isHoveringRef,
-    shouldRefocusRef,
+  const contentRef = useRef<ReactNode | null>(null);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const positionConfig: TooltipPositionConfig = { side, sideOffset, align, alignOffset, collisionPadding };
+  const initializedRef = useRef(false);
+
+  // Controlled open: sync store with prop
+  useEffect(() => {
+    if (open === undefined) return;
+    const store = useTooltipStore.getState();
+    if (open && !store.open) {
+      const content = contentRef.current;
+      const anchor = triggerRef.current;
+      if (content && anchor) {
+        store.openTooltip(content, anchor, { positionConfig, hoverable, closeDelay });
+      }
+    } else if (!open && store.open && store.anchor === triggerRef.current) {
+      store.closeTooltip();
+    }
+  }, [open]);
+
+  // defaultOpen: open on first render
+  useEffect(() => {
+    if (initializedRef.current || defaultOpen === undefined || !defaultOpen) return;
+    initializedRef.current = true;
+    requestAnimationFrame(() => {
+      const content = contentRef.current;
+      const anchor = triggerRef.current;
+      if (content && anchor) {
+        useTooltipStore.getState().openTooltip(content, anchor, { positionConfig, hoverable, closeDelay });
+      }
+    });
+  }, [defaultOpen]);
+
+  const ctx: TooltipContext = {
+    contentRef,
+    triggerRef,
+    disabled,
     touchDisabled,
+    hoverable,
+    delay,
+    closeDelay,
+    warmUpDelay,
+    positionConfig,
   };
 
-  if (!activated) {
-    return (
-      <DeferredContext.Provider value={ctx}>
-        {children}
-      </DeferredContext.Provider>
-    );
-  }
-
   return (
-    <DeferredContext.Provider value={ctx}>
-      <BaseTooltip.Root
-        open={open}
-        defaultOpen={defaultOpen}
-        disabled={disabled}
-        onOpenChangeComplete={(isOpen) => {
-          onOpenChangeComplete?.(isOpen);
-          if (!isOpen && unmountOnClose) setWasActivated(false);
-        }}
-        {...props}
-      >
-        {children}
-      </BaseTooltip.Root>
-    </DeferredContext.Provider>
+    <TooltipCtx.Provider value={ctx}>
+      {children}
+    </TooltipCtx.Provider>
   );
 }
 
 /* ------------------------------------------------------------------ */
-/*  Trigger — lightweight pre-activation handlers, then Base UI        */
+/*  Trigger — plain element, zero Base UI overhead                     */
 /* ------------------------------------------------------------------ */
 
-type TriggerProps = ComponentPropsWithoutRef<typeof BaseTooltip.Trigger>;
-
-// Base UI Trigger props that must not leak onto a raw <button>
-const BASE_UI_KEYS = new Set([
-  "closeOnClick",
-  "handle",
-  "payload",
-  "delay",
-  "closeDelay",
-  "render",
-]);
-
-function pickHtmlProps(props: Record<string, unknown>) {
-  const html: Record<string, unknown> = {};
-  for (const key in props) {
-    if (!BASE_UI_KEYS.has(key)) html[key] = props[key];
-  }
-  return html;
-}
+type TriggerProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  children?: ReactNode;
+  /** Replace the default `<button>` with a custom element. */
+  render?: ReactElement | ((props: Record<string, unknown>) => ReactElement);
+};
 
-function Trigger({
-  children,
-  className,
-  style,
-  disabled,
-  ...rest
-}: TriggerProps) {
-  const deferred = useContext(DeferredContext);
-  const triggerElRef = useRef<HTMLButtonElement | null>(null);
-  const pendingRef = useRef(0);
+function Trigger({ children, render, ...props }: TriggerProps) {
+  const ctx = useContext(TooltipCtx);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const openTimerRef = useRef(0);
+  const closeTimerRef = useRef(0);
   const lastPointerTypeRef = useRef("");
 
-  // Ref callback: stores the element AND restores focus when the DOM
-  // swaps from the pre-activation button to BaseTooltip.Trigger.
-  // shouldRefocusRef lives in DeferredContext because Root's tree change
-  // (wrapping in BaseTooltip.Root) causes Trigger to remount.
-  const shouldRefocusRef = deferred?.shouldRefocusRef;
-  const triggerRef = useCallback(
+  // Register trigger element with Root
+  const setTriggerRef = useCallback(
     (el: HTMLButtonElement | null) => {
-      triggerElRef.current = el;
-      if (shouldRefocusRef?.current && el) {
-        shouldRefocusRef.current = false;
-        el.focus();
-      }
+      triggerRef.current = el;
+      if (ctx) ctx.triggerRef.current = el;
     },
-    [shouldRefocusRef],
+    [ctx],
   );
 
-  const activated = deferred?.activated ?? true;
-
-  // After hover-activation, dispatch synthetic events to kick-start
-  // Base UI's hover detection. Base UI uses:
-  //   - React onPointerEnter → sets pointerType
-  //   - native mouseenter listener → starts hover tracking
-  //   - React onMouseMove → triggers the restMs timer that opens the tooltip
+  // Clear pending timers on unmount
   useEffect(() => {
-    if (!activated || !deferred?.isHoveringRef.current) return;
-    const el = triggerElRef.current;
-    if (!el) return;
-    const frame = requestAnimationFrame(() => {
-      if (!deferred.isHoveringRef.current) return;
-      el.dispatchEvent(
-        new PointerEvent("pointerenter", {
-          bubbles: false,
-          pointerType: "mouse",
-        }),
-      );
-      el.dispatchEvent(new MouseEvent("mouseenter", { bubbles: false }));
-      el.dispatchEvent(new MouseEvent("mousemove", { bubbles: true }));
-    });
-    return () => cancelAnimationFrame(frame);
-  }, [activated]);
-
-  if (deferred && !deferred.activated) {
-    const { render: renderProp } = rest;
-    const htmlProps = pickHtmlProps(rest);
-
-    const preProps = {
-      ...htmlProps,
-      ref: triggerRef,
-      className: typeof className === "function" ? undefined : className,
-      style: typeof style === "function" ? undefined : style,
-      disabled,
-      onPointerDown: (e: React.PointerEvent<HTMLButtonElement>) => {
-        lastPointerTypeRef.current = e.pointerType;
-      },
-      onMouseEnter: () => {
-        if (deferred.touchDisabled && lastPointerTypeRef.current === "touch")
-          return;
-        deferred.isHoveringRef.current = true;
-        pendingRef.current = requestAnimationFrame(() => {
-          if (deferred.isHoveringRef.current) deferred.activate();
-        });
-      },
-      onMouseLeave: () => {
-        deferred.isHoveringRef.current = false;
-        cancelAnimationFrame(pendingRef.current);
-      },
-      onFocus: () => {
-        if (deferred.touchDisabled && lastPointerTypeRef.current === "touch")
-          return;
-        deferred.shouldRefocusRef.current = true;
-        deferred.activate();
-      },
+    return () => {
+      clearTimeout(openTimerRef.current);
+      clearTimeout(closeTimerRef.current);
     };
-
-    if (isValidElement(renderProp)) {
-      return cloneElement(renderProp, preProps, children) as ReactElement;
+  }, []);
+
+  const storeState = useTooltipStore((s) => ({
+    open: s.open,
+    anchor: s.anchor,
+    popupId: s.popupId,
+  }));
+  const isActive = storeState.open && storeState.anchor === triggerRef.current;
+
+  const scheduleOpen = useCallback(() => {
+    if (ctx?.disabled || !triggerRef.current) return;
+
+    // Cancel any pending close
+    clearTimeout(closeTimerRef.current);
+
+    const content = ctx?.contentRef.current;
+    if (!content) return;
+
+    const store = useTooltipStore.getState();
+
+    // If already showing this tooltip, do nothing
+    if (store.open && store.anchor === triggerRef.current) return;
+
+    // Instant switch: if another tooltip is open, or one closed recently (warm-up)
+    const isSwitch = store.open && store.anchor !== triggerRef.current;
+    const elapsed = Date.now() - store.lastCloseTime;
+    const isWarmUp = !isSwitch && elapsed < (ctx?.warmUpDelay ?? 300);
+    const effectiveDelay = isSwitch || isWarmUp ? 0 : (ctx?.delay ?? 600);
+
+    const openOptions = { positionConfig: ctx?.positionConfig, hoverable: ctx?.hoverable, closeDelay: ctx?.closeDelay };
+
+    if (effectiveDelay === 0) {
+      store.openTooltip(content, triggerRef.current!, openOptions);
+    } else {
+      openTimerRef.current = window.setTimeout(() => {
+        const currentContent = ctx?.contentRef.current;
+        if (currentContent && triggerRef.current) {
+          useTooltipStore.getState().openTooltip(currentContent, triggerRef.current, openOptions);
+        }
+      }, effectiveDelay);
     }
-    if (typeof renderProp === "function") {
-      return renderProp({ ...preProps, children } as Parameters<typeof renderProp>[0], {} as Parameters<typeof renderProp>[1]);
+  }, [ctx]);
+
+  const scheduleClose = useCallback(() => {
+    clearTimeout(openTimerRef.current);
+
+    // When hoverable, the renderer's safe polygon and popup hover
+    // handlers own the close lifecycle — trigger doesn't close.
+    if (ctx?.hoverable) return;
+
+    const store = useTooltipStore.getState();
+    if (!store.open || store.anchor !== triggerRef.current) return;
+
+    const closeDelay = ctx?.closeDelay ?? 300;
+    if (closeDelay === 0) {
+      store.closeTooltip();
+    } else {
+      closeTimerRef.current = window.setTimeout(() => {
+        const s = useTooltipStore.getState();
+        if (s.open && s.anchor === triggerRef.current) {
+          s.closeTooltip();
+        }
+      }, closeDelay);
     }
-    return <button {...preProps}>{children}</button>;
-  }
+  }, [ctx]);
 
-  return (
-    <BaseTooltip.Trigger
-      ref={triggerRef}
-      className={className}
-      style={style}
-      disabled={disabled}
-      {...rest}
-    >
-      {children}
-    </BaseTooltip.Trigger>
+  const handlePointerDown = useCallback(
+    (e: React.PointerEvent<HTMLButtonElement>) => {
+      lastPointerTypeRef.current = e.pointerType;
+      props.onPointerDown?.(e);
+    },
+    [props.onPointerDown],
+  );
+
+  const handlePointerEnter = useCallback(
+    (e: React.PointerEvent<HTMLButtonElement>) => {
+      props.onPointerEnter?.(e);
+      if (e.defaultPrevented) return;
+      if (ctx?.touchDisabled && lastPointerTypeRef.current === "touch") return;
+      scheduleOpen();
+    },
+    [ctx, props.onPointerEnter, scheduleOpen],
+  );
+
+  const handlePointerLeave = useCallback(
+    (e: React.PointerEvent<HTMLButtonElement>) => {
+      props.onPointerLeave?.(e);
+      if (e.defaultPrevented) return;
+      scheduleClose();
+    },
+    [props.onPointerLeave, scheduleClose],
+  );
+
+  const handleFocus = useCallback(
+    (e: React.FocusEvent<HTMLButtonElement>) => {
+      props.onFocus?.(e);
+      if (e.defaultPrevented) return;
+      if (ctx?.touchDisabled && lastPointerTypeRef.current === "touch") return;
+      scheduleOpen();
+    },
+    [ctx, props.onFocus, scheduleOpen],
+  );
+
+  const handleBlur = useCallback(
+    (e: React.FocusEvent<HTMLButtonElement>) => {
+      props.onBlur?.(e);
+      if (e.defaultPrevented) return;
+      // Close immediately on blur (no delay)
+      clearTimeout(openTimerRef.current);
+      const store = useTooltipStore.getState();
+      if (store.open && store.anchor === triggerRef.current) {
+        store.closeTooltip();
+      }
+    },
+    [props.onBlur],
   );
+
+  const triggerProps = {
+    ref: setTriggerRef,
+    type: "button" as const,
+    "aria-describedby": isActive && storeState.popupId ? storeState.popupId : undefined,
+    onPointerDown: handlePointerDown,
+    onPointerEnter: handlePointerEnter,
+    onPointerLeave: handlePointerLeave,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    ...props,
+  };
+
+  if (isValidElement(render)) {
+    return cloneElement(render, triggerProps, children) as ReactElement;
+  }
+  if (typeof render === "function") {
+    return render({ ...triggerProps, children });
+  }
+  return <button {...triggerProps}>{children}</button>;
 }
 
 /* ------------------------------------------------------------------ */
-/*  Portal — returns null pre-activation                               */
+/*  Portal — captures children, does not render them                   */
 /* ------------------------------------------------------------------ */
 
-type PortalProps = ComponentPropsWithoutRef<typeof BaseTooltip.Portal>;
+type PortalProps = {
+  children?: ReactNode;
+};
+
+function Portal({ children }: PortalProps) {
+  const ctx = useContext(TooltipCtx);
+  const storeAnchor = useTooltipStore((s) => s.anchor);
+
+  if (ctx) {
+    ctx.contentRef.current = children;
+  }
+
+  // If this tooltip is currently active, push content updates to the store
+  // so dynamic content reflects immediately in the open popup.
+  const isActive = !!(ctx && storeAnchor && storeAnchor === ctx.triggerRef.current);
+  useEffect(() => {
+    if (isActive) {
+      useTooltipStore.getState().updateContent(children);
+    }
+  });
 
-function Portal(props: PortalProps) {
-  const deferred = useContext(DeferredContext);
-  if (deferred && !deferred.activated) return null;
-  return <BaseTooltip.Portal {...props} />;
+  return null;
 }
 
 /* ------------------------------------------------------------------ */
 /*  Positioner / Popup / Arrow — default class names                   */
 /* ------------------------------------------------------------------ */
 
-type PositionerProps = ComponentPropsWithoutRef<typeof BaseTooltip.Positioner>;
-
-function Positioner({ className, ...props }: PositionerProps) {
-  return (
-    <BaseTooltip.Positioner
-      className={className ?? "slithy-tooltip-positioner"}
-      {...props}
-    />
-  );
-}
-
 type PopupProps = ComponentPropsWithoutRef<typeof BaseTooltip.Popup>;
 
-function Popup({ className, ...props }: PopupProps) {
+function Popup({ className, id, ...props }: PopupProps) {
+  const popupId = useTooltipStore((s) => s.popupId);
   return (
     <BaseTooltip.Popup
+      id={id ?? popupId ?? undefined}
       className={className ?? "slithy-tooltip-popup"}
       {...props}
     />
@@ -292,11 +367,9 @@ function Arrow({ className, ...props }: ArrowProps) {
 /* ------------------------------------------------------------------ */
 
 export const Tooltip = {
-  Provider,
   Root,
   Trigger,
   Portal,
-  Positioner,
   Popup,
   Arrow,
 };

package/src/Tooltip/TooltipRenderer.tsx

@@ -0,0 +1,137 @@
+import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import { useSafePolygon } from "../useSafePolygon";
+import { useTooltipStore } from "./TooltipStore";
+import "./Tooltip.css";
+
+/**
+ * Singleton renderer — mount once at the app root.
+ * Subscribes to the global TooltipStore and renders the active tooltip
+ * using Base UI's Tooltip.Root + Tooltip.Positioner.
+ *
+ * Tooltip.Root stays mounted so CSS transitions can play on both open and close.
+ */
+export function TooltipRenderer() {
+  const popupId = useId();
+
+  // Register the popup id so triggers can reference it for aria-describedby
+  useEffect(() => {
+    useTooltipStore.getState().setPopupId(popupId);
+  }, [popupId]);
+
+  const open = useTooltipStore((s) => s.open);
+  const content = useTooltipStore((s) => s.content);
+  const anchor = useTooltipStore((s) => s.anchor);
+  const positionConfig = useTooltipStore((s) => s.positionConfig);
+
+  // Keep content/anchor alive during close animation so the popup
+  // doesn't disappear before the transition finishes.
+  const lastContentRef = useRef(content);
+  const lastAnchorRef = useRef(anchor);
+  if (content) lastContentRef.current = content;
+  if (anchor) lastAnchorRef.current = anchor;
+
+  const activeContent = content ?? lastContentRef.current;
+  const activeAnchor = anchor ?? lastAnchorRef.current;
+
+  // Track whether we've ever had content (don't mount Tooltip.Root until first open)
+  const [hasOpened, setHasOpened] = useState(false);
+  // Defer the first open by one frame so Tooltip.Root mounts with open={false},
+  // then transitions to open={true} — enabling the starting-style animation.
+  const [deferredOpen, setDeferredOpen] = useState(false);
+  useEffect(() => {
+    if (open && !hasOpened) {
+      setHasOpened(true);
+      requestAnimationFrame(() => setDeferredOpen(true));
+    } else {
+      setDeferredOpen(open);
+    }
+  }, [open, hasOpened]);
+
+  // Dismiss on Escape key
+  useEffect(() => {
+    if (!open) return;
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        useTooltipStore.getState().closeTooltip();
+      }
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [open]);
+
+  // Hoverable popup support — keep open while pointer is in the popup
+  const hoverable = useTooltipStore((s) => s.hoverable);
+  const storeCloseDelay = useTooltipStore((s) => s.closeDelay);
+  const popupRef = useRef<HTMLDivElement | null>(null);
+  const popupCloseTimerRef = useRef(0);
+
+  // Safe polygon: keep open while pointer moves from trigger toward popup
+  const handleSafePolygonClose = useCallback(() => {
+    useTooltipStore.getState().closeTooltip();
+  }, []);
+
+  useSafePolygon({
+    enabled: open && hoverable,
+    anchor: anchor,
+    popupRef,
+    onClose: handleSafePolygonClose,
+  });
+
+  const handlePopupPointerEnter = useCallback(() => {
+    if (!hoverable) return;
+    clearTimeout(popupCloseTimerRef.current);
+  }, [hoverable]);
+
+  const handlePopupPointerLeave = useCallback(() => {
+    if (!hoverable) return;
+    popupCloseTimerRef.current = window.setTimeout(() => {
+      useTooltipStore.getState().closeTooltip();
+    }, storeCloseDelay);
+  }, [hoverable, storeCloseDelay]);
+
+  // Clear popup close timer on unmount or when tooltip closes
+  useEffect(() => {
+    if (!open) clearTimeout(popupCloseTimerRef.current);
+    return () => clearTimeout(popupCloseTimerRef.current);
+  }, [open]);
+
+  // Clear stale content after close animation completes
+  const handleOpenChangeComplete = (isOpen: boolean) => {
+    if (!isOpen) {
+      lastContentRef.current = null;
+      lastAnchorRef.current = null;
+    }
+  };
+
+  if (!hasOpened) return null;
+
+  return (
+    <BaseTooltip.Root
+      open={deferredOpen}
+      onOpenChange={(isOpen) => {
+        if (!isOpen) {
+          useTooltipStore.getState().closeTooltip();
+        }
+      }}
+      onOpenChangeComplete={handleOpenChangeComplete}
+    >
+      <BaseTooltip.Portal>
+        <BaseTooltip.Positioner
+          ref={popupRef}
+          anchor={activeAnchor}
+          className="slithy-tooltip-positioner"
+          side={positionConfig.side ?? "top"}
+          sideOffset={positionConfig.sideOffset ?? 6}
+          align={positionConfig.align}
+          alignOffset={positionConfig.alignOffset}
+          collisionPadding={positionConfig.collisionPadding}
+          onPointerEnter={handlePopupPointerEnter}
+          onPointerLeave={handlePopupPointerLeave}
+        >
+          {activeContent}
+        </BaseTooltip.Positioner>
+      </BaseTooltip.Portal>
+    </BaseTooltip.Root>
+  );
+}