@slithy/base-ui 0.1.0 → 0.2.0

package/src/Tooltip/TooltipStore.ts

@@ -0,0 +1,142 @@
+import { useCallback, useRef, useSyncExternalStore } from "react";
+import type { ReactNode } from "react";
+
+/* ------------------------------------------------------------------ */
+/*  Minimal store (self-contained, no external deps)                   */
+/* ------------------------------------------------------------------ */
+
+type Listener = () => void;
+
+export type TooltipPositionConfig = {
+  side?: "top" | "bottom" | "left" | "right" | "inline-end" | "inline-start";
+  sideOffset?: number;
+  align?: "start" | "center" | "end";
+  alignOffset?: number;
+  collisionPadding?: number | Partial<Record<"top" | "right" | "bottom" | "left", number>>;
+};
+
+export type TooltipStoreState = {
+  open: boolean;
+  content: ReactNode | null;
+  anchor: HTMLElement | null;
+  positionConfig: TooltipPositionConfig;
+  /** Whether the popup can be hovered without closing */
+  hoverable: boolean;
+  /** Close delay in ms — used by the renderer for popup hover */
+  closeDelay: number;
+  /** Stable id for the popup element — set by the renderer, read by triggers for aria-describedby */
+  popupId: string | null;
+  /** Timestamp of last close — enables warm-up (instant open after recent close) */
+  lastCloseTime: number;
+  setPopupId: (id: string) => void;
+  openTooltip: (
+    content: ReactNode,
+    anchor: HTMLElement,
+    options?: { positionConfig?: TooltipPositionConfig; hoverable?: boolean; closeDelay?: number },
+  ) => void;
+  closeTooltip: (options?: { skipWarmUp?: boolean }) => void;
+  updateContent: (content: ReactNode) => void;
+};
+
+function shallowEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+    return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every((k) =>
+    Object.is(
+      (a as Record<string, unknown>)[k],
+      (b as Record<string, unknown>)[k],
+    ),
+  );
+}
+
+function createTooltipStore() {
+  const listeners = new Set<Listener>();
+
+  function notify() {
+    listeners.forEach((l) => l());
+  }
+
+  let state: TooltipStoreState = {
+    open: false,
+    content: null,
+    anchor: null,
+    positionConfig: {},
+    hoverable: false,
+    closeDelay: 300,
+    popupId: null,
+    lastCloseTime: 0,
+
+    setPopupId(id) {
+      if (state.popupId === id) return;
+      state = { ...state, popupId: id };
+      notify();
+    },
+
+    openTooltip(content, anchor, options) {
+      state = {
+        ...state,
+        open: true,
+        content,
+        anchor,
+        positionConfig: options?.positionConfig ?? {},
+        hoverable: options?.hoverable ?? false,
+        closeDelay: options?.closeDelay ?? 300,
+      };
+      notify();
+    },
+
+    closeTooltip(options) {
+      if (!state.open) return;
+      state = {
+        ...state,
+        open: false,
+        content: null,
+        anchor: null,
+        lastCloseTime: options?.skipWarmUp ? 0 : Date.now(),
+      };
+      notify();
+    },
+
+    updateContent(content) {
+      if (!state.open || state.content === content) return;
+      state = { ...state, content };
+      notify();
+    },
+  };
+
+  return {
+    getState: () => state,
+    subscribe: (listener: Listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+const store = createTooltipStore();
+
+export function useTooltipStore<T>(selector: (state: TooltipStoreState) => T): T {
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  const prevRef = useRef<T | undefined>(undefined);
+
+  const getSnapshot = useCallback(() => {
+    const result = selectorRef.current(store.getState());
+    const prev = prevRef.current;
+    if (prev !== undefined && shallowEqual(prev, result)) {
+      return prev;
+    }
+    prevRef.current = result;
+    return result;
+  }, []);
+
+  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}
+
+/** Direct access for imperative use inside event handlers */
+useTooltipStore.getState = store.getState;

package/src/Tooltip/index.ts

@@ -1 +1,2 @@
-export { Tooltip } from './Tooltip';
+export { Tooltip } from "./Tooltip";
+export { TooltipRenderer } from "./TooltipRenderer";

package/src/index.ts

@@ -1,2 +1,2 @@
-export { Dropdown } from './Dropdown';
-export { Tooltip } from './Tooltip';
+export { Dropdown, DropdownRenderer } from './Dropdown';
+export { Tooltip, TooltipRenderer } from './Tooltip';

package/src/useCloseCleanup.ts

@@ -0,0 +1,60 @@
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Defensive safety net for singleton renderer cleanup.
+ *
+ * Base UI's `onOpenChangeComplete` is the primary cleanup mechanism and
+ * fires reliably in normal usage (verified empirically).  This hook
+ * exists as insurance: if `onOpenChangeComplete` ever fails to fire
+ * (e.g., CSS transition edge cases, rapid open/close cycles, or future
+ * Base UI changes), the timeout guarantees stale content and anchor refs
+ * are cleared within 500ms, preventing ghost positioner elements in the DOM.
+ *
+ * The returned callback is idempotent — calling it from both
+ * `onOpenChangeComplete` and the timeout is safe; only the first
+ * invocation per close cycle runs the cleanup.
+ *
+ * Usage in renderers:
+ *
+ *   const [onCloseComplete] = useCloseCleanup(open, () => {
+ *     lastContentRef.current = null;
+ *     lastAnchorRef.current = null;
+ *   });
+ *
+ *   <Root onOpenChangeComplete={(isOpen) => {
+ *     if (!isOpen) onCloseComplete();   // primary path — fires first
+ *   }} />
+ *
+ *   // Safety net fires automatically after 500ms if primary never calls.
+ */
+export function useCloseCleanup(
+  open: boolean,
+  onDone: () => void,
+): [cleanup: () => void] {
+  const onDoneRef = useRef(onDone);
+  onDoneRef.current = onDone;
+
+  // Track whether cleanup has been called for this close cycle.
+  const calledRef = useRef(false);
+
+  // Reset when a new open cycle starts.
+  if (open) {
+    calledRef.current = false;
+  }
+
+  // Stable callback — safe to call from onOpenChangeComplete.
+  const runCleanup = useCallback(() => {
+    if (calledRef.current) return;
+    calledRef.current = true;
+    onDoneRef.current();
+  }, []);
+
+  // Safety net: guarantee cleanup after a generous timeout.
+  useEffect(() => {
+    if (open) return;
+    const timerId = setTimeout(runCleanup, 500);
+    return () => clearTimeout(timerId);
+  }, [open, runCleanup]);
+
+  return [runCleanup];
+}

package/src/useSafePolygon.ts

@@ -0,0 +1,144 @@
+import { useEffect, useRef, type RefObject } from "react";
+
+/**
+ * Tracks the pointer after it leaves the trigger and keeps the popup open
+ * while the pointer moves toward it (safe polygon / hover bridge).
+ *
+ * Creates a triangle from the pointer's exit point to the two far corners
+ * of the popup. As long as the pointer stays inside this triangle, the
+ * popup remains open. If the pointer enters the popup element, tracking
+ * stops (the popup's own hover handlers take over). If the pointer exits
+ * the triangle, `onClose` is called.
+ *
+ * Shared by TooltipRenderer, DropdownRenderer, and any future hover-based
+ * floating components.
+ */
+export function useSafePolygon({
+  enabled,
+  anchor,
+  popupRef,
+  onClose,
+}: {
+  /** Whether safe polygon tracking is active (trigger was hovered, popup is open) */
+  enabled: boolean;
+  /** The trigger element */
+  anchor: HTMLElement | null;
+  /** Ref to the popup element — read inside effects so it works even when the popup mounts after the hook runs */
+  popupRef: RefObject<HTMLElement | null>;
+  /** Called when the pointer exits the safe polygon */
+  onClose: () => void;
+}) {
+  const exitPointRef = useRef<{ x: number; y: number } | null>(null);
+
+  // Capture the pointer position when leaving the trigger
+  useEffect(() => {
+    if (!enabled || !anchor) return;
+
+    const handlePointerLeave = (e: PointerEvent) => {
+      exitPointRef.current = { x: e.clientX, y: e.clientY };
+    };
+
+    anchor.addEventListener("pointerleave", handlePointerLeave);
+    return () => anchor.removeEventListener("pointerleave", handlePointerLeave);
+  }, [enabled, anchor]);
+
+  // Track pointer movement and check against the safe polygon
+  useEffect(() => {
+    if (!enabled || !anchor) return;
+
+    const handlePointerMove = (e: PointerEvent) => {
+      const exit = exitPointRef.current;
+      if (!exit) return;
+
+      const popup = popupRef.current;
+      if (!popup) return;
+
+      // If the pointer entered the popup, stop tracking
+      const popupRect = popup.getBoundingClientRect();
+      if (
+        e.clientX >= popupRect.left &&
+        e.clientX <= popupRect.right &&
+        e.clientY >= popupRect.top &&
+        e.clientY <= popupRect.bottom
+      ) {
+        exitPointRef.current = null;
+        return;
+      }
+
+      // Build triangle from exit point to two corners of the popup
+      const triangle = getTriangle(exit, popupRect);
+
+      if (!pointInTriangle({ x: e.clientX, y: e.clientY }, triangle)) {
+        exitPointRef.current = null;
+        onClose();
+      }
+    };
+
+    document.addEventListener("pointermove", handlePointerMove);
+    return () => document.removeEventListener("pointermove", handlePointerMove);
+  }, [enabled, anchor, popupRef, onClose]);
+
+  // Clear exit point when tracking stops
+  useEffect(() => {
+    if (!enabled) {
+      exitPointRef.current = null;
+    }
+  }, [enabled]);
+}
+
+/* ------------------------------------------------------------------ */
+/*  Geometry                                                           */
+/* ------------------------------------------------------------------ */
+
+type Point = { x: number; y: number };
+
+/**
+ * Build a triangle from the pointer exit point to the two far corners
+ * of the popup, creating a bridge zone the pointer can travel through.
+ *
+ * We pick corners based on which quadrant the popup is in relative to
+ * the exit point, ensuring the triangle covers the gap between them.
+ */
+function getTriangle(exit: Point, rect: DOMRect): [Point, Point, Point] {
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+
+  // Determine primary axis — is the popup more horizontal or vertical?
+  const dx = cx - exit.x;
+  const dy = cy - exit.y;
+
+  if (Math.abs(dy) >= Math.abs(dx)) {
+    // Popup is above or below — use left and right edges
+    if (dy > 0) {
+      // Popup below
+      return [exit, { x: rect.left, y: rect.top }, { x: rect.right, y: rect.top }];
+    }
+    // Popup above
+    return [exit, { x: rect.left, y: rect.bottom }, { x: rect.right, y: rect.bottom }];
+  }
+  // Popup is to the left or right — use top and bottom edges
+  if (dx > 0) {
+    // Popup right
+    return [exit, { x: rect.left, y: rect.top }, { x: rect.left, y: rect.bottom }];
+  }
+  // Popup left
+  return [exit, { x: rect.right, y: rect.top }, { x: rect.right, y: rect.bottom }];
+}
+
+/**
+ * Point-in-triangle test using cross products (sign method).
+ */
+function pointInTriangle(p: Point, [a, b, c]: [Point, Point, Point]): boolean {
+  const d1 = sign(p, a, b);
+  const d2 = sign(p, b, c);
+  const d3 = sign(p, c, a);
+
+  const hasNeg = d1 < 0 || d2 < 0 || d3 < 0;
+  const hasPos = d1 > 0 || d2 > 0 || d3 > 0;
+
+  return !(hasNeg && hasPos);
+}
+
+function sign(p1: Point, p2: Point, p3: Point): number {
+  return (p1.x - p3.x) * (p2.y - p3.y) - (p2.x - p3.x) * (p1.y - p3.y);
+}