@primitiv-ui/react 0.1.27 → 0.1.29

package/src/Tooltip/Tooltip.tsx

@@ -24,11 +24,27 @@ import type {
 } from "./types";
 
 /**
- * Wraps one or more `Tooltip.Root` instances and provides shared
- * delay configuration. Required ancestor — rendering `Tooltip.Root`
- * without a Provider throws a context error.
+ * Wraps one or more {@link TooltipRoot | `Tooltip.Root`} instances and provides
+ * the shared delay configuration and group-wide open coordination. Required
+ * ancestor — rendering `Tooltip.Root` without a Provider throws a context
+ * error. Renders no DOM of its own (a `TooltipProviderContext` provider only).
  *
- * @example
+ * **Delay coordination.** Two timings govern how a group of tooltips feels:
+ *
+ * - `delayDuration` — how long a pointer must rest on a trigger before its
+ *   tooltip opens (hover only; focus always opens immediately).
+ * - `skipDelayDuration` — the grace window after a tooltip closes during which
+ *   moving to *another* trigger in the same Provider opens that tooltip
+ *   instantly, with no `delayDuration` wait. Rest longer than this window and
+ *   the next hover pays the full `delayDuration` again. This is what makes a
+ *   toolbar of icon buttons feel responsive once the first tip has shown.
+ *
+ * Place a single Provider high in the tree (typically at the app root) so every
+ * tooltip shares one skip window. A per-instance
+ * {@link TooltipRootProps.delayDuration | `delayDuration`} on `Tooltip.Root`
+ * overrides the Provider's value for that one tooltip.
+ *
+ * @example App-wide provider
  * ```tsx
  * <Tooltip.Provider delayDuration={400}>
  *   <App />
@@ -55,13 +71,27 @@ export function TooltipProviderComponent({
 TooltipProviderComponent.displayName = "TooltipProvider";
 
 /**
- * The state boundary for a single tooltip. Owns the open/closed
- * state and wires it down to all sub-components via context.
+ * The state boundary for a single tooltip. Owns the open/closed state, runs the
+ * open-delay and grace-period timers, and wires everything down to the
+ * sub-components via `TooltipContext`. Renders no DOM of its own. Must be a
+ * descendant of {@link TooltipProviderComponent | `Tooltip.Provider`}.
  *
- * Supports two state modes, statically discriminated at the type level:
+ * **Controlled vs uncontrolled**, statically discriminated at the type level so
+ * TypeScript accepts only one shape:
  *
- * - **Uncontrolled** — pass `defaultOpen` or omit for closed-on-mount.
- * - **Controlled** — pass `open` (and optionally `onOpenChange`).
+ * - **Uncontrolled** — pass {@link UncontrolledTooltipRootProps.defaultOpen | `defaultOpen`}
+ *   (or omit it for closed-on-mount). The component owns the flag; observe
+ *   transitions with `onOpenChange`.
+ * - **Controlled** — pass {@link ControlledTooltipRootProps.open | `open`}
+ *   (with an optional `onOpenChange`). The parent owns the flag; the delay and
+ *   grace timers still run and drive `onOpenChange`, but the tooltip only moves
+ *   when the parent updates `open`.
+ *
+ * **Timing overrides.** {@link TooltipRootProps.delayDuration | `delayDuration`}
+ * overrides the Provider's open delay for this tooltip only.
+ * {@link TooltipRootProps.disableHoverableContent | `disableHoverableContent`}
+ * removes the grace period, so the tooltip closes the instant the pointer
+ * leaves the trigger (the user cannot move into the content).
  *
  * @example
  * ```tsx
@@ -94,13 +124,24 @@ export function TooltipRoot({
 TooltipRoot.displayName = "TooltipRoot";
 
 /**
- * The element that triggers the tooltip on hover and focus. Renders a
- * `<button type="button">` by default; use `asChild` to wrap a custom
- * element.
+ * The element that opens the tooltip. Renders a `<button type="button">` by
+ * default; pass `asChild` to project the trigger behaviour onto a custom
+ * element (a link, an icon button, etc.).
+ *
+ * **Open / close behaviour.** Pointer-enter opens after the effective
+ * `delayDuration` (immediately if the group's skip window is active);
+ * pointer-leave closes after a short grace period so the pointer can travel
+ * into hoverable content (immediately when `disableHoverableContent` is set on
+ * Root). Focus opens immediately and blur closes immediately, and `Escape`
+ * while focused closes immediately — matching the WAI-ARIA tooltip pattern.
+ * Consumer `onPointerEnter` / `onPointerLeave` / `onFocus` / `onBlur` /
+ * `onKeyDown` all compose (they run first).
  *
- * ARIA wiring:
- * - `aria-describedby` points at `Tooltip.Content`'s id.
- * - `data-state="open" | "closed"` mirrors the tooltip state.
+ * **ARIA wiring.**
+ * - `aria-describedby` points at {@link TooltipContent | `Tooltip.Content`}'s id.
+ * - `data-state="open" | "closed"` mirrors the tooltip state for CSS.
+ *
+ * @extends HTMLButtonElement
  *
  * @example
  * ```tsx
@@ -148,7 +189,8 @@ TooltipTrigger.displayName = "TooltipTrigger";
  *
  * By default the portal only renders while the tooltip is open. Pass
  * `forceMount` to keep the subtree mounted when closed — useful for
- * CSS exit animations driven by `data-state="closed"`.
+ * CSS exit animations driven by `data-state="closed"`. Renders no wrapper
+ * element of its own.
  *
  * @example
  * ```tsx
@@ -192,6 +234,8 @@ TooltipPortal.displayName = "TooltipPortal";
  * `anchor-name` to the trigger and `position-anchor` / `position-area`
  * to the content in your own stylesheet.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Tooltip.Content className="tooltip__content">
@@ -233,6 +277,8 @@ TooltipContent.displayName = "TooltipContent";
  *
  * All positioning and styling is the consumer's responsibility via CSS.
  *
+ * @extends HTMLSpanElement
+ *
  * @example
  * ```tsx
  * <Tooltip.Content>
@@ -270,11 +316,43 @@ export type TooltipCompound = typeof TooltipRoot & {
  * Headless, accessible **Tooltip** — a compound component implementing the
  * [WAI-ARIA tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/):
  * a deferred, hoverable label anchored to a trigger, with a shared
- * {@link Tooltip.Provider} governing open / skip delays across a group. Zero
- * styles ship.
+ * {@link TooltipProviderComponent | `Tooltip.Provider`} governing open / skip
+ * delays across a group. Opens on hover (after a delay) and on focus
+ * (immediately); closes on blur, on `Escape`, and after a short grace period on
+ * pointer-leave so the pointer can travel into hoverable content. Zero styles
+ * ship; visual placement is your CSS concern (CSS anchor positioning).
+ *
+ * `Tooltip` is both callable (an alias of {@link TooltipRoot | `Tooltip.Root`})
+ * and carries its sub-components as static properties. A `Tooltip.Provider`
+ * ancestor is required — `Tooltip.Root` throws without one.
+ *
+ * - {@link TooltipProviderComponent | `Tooltip.Provider`} — shared delay config + group open coordination.
+ * - {@link TooltipRoot | `Tooltip.Root`} — per-tooltip state owner and timing.
+ * - {@link TooltipTrigger | `Tooltip.Trigger`} — `<button>` that opens on hover/focus.
+ * - {@link TooltipPortal | `Tooltip.Portal`} — optional portal to `document.body`.
+ * - {@link TooltipContent | `Tooltip.Content`} — the `role="tooltip"` panel.
+ * - {@link TooltipArrow | `Tooltip.Arrow`} — optional visual pointer.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Tooltip } from "@primitiv-ui/react";
+ *
+ * <Tooltip.Provider>
+ *   <Tooltip.Root>
+ *     <Tooltip.Trigger>Save</Tooltip.Trigger>
+ *     <Tooltip.Portal>
+ *       <Tooltip.Content>
+ *         Save your changes
+ *         <Tooltip.Arrow />
+ *       </Tooltip.Content>
+ *     </Tooltip.Portal>
+ *   </Tooltip.Root>
+ * </Tooltip.Provider>;
+ * ```
  *
- * The default export is the `Root`; sub-components are attached as static
- * properties (`Tooltip.Provider`, `Tooltip.Trigger`, `Tooltip.Content`, …).
+ * @see {@link TooltipProviderComponent} for delay / skip-delay coordination.
+ * @see {@link TooltipRoot} for the controlled/uncontrolled state modes and timing overrides.
+ * @see {@link TooltipContent} for the grace period and the Escape / outside-pointer escape hatches.
  */
 const TooltipCompound: TooltipCompound = Object.assign(TooltipRoot, {
   Provider: TooltipProviderComponent,

package/src/Tooltip/hooks/__tests__/useTooltipProvider.test.tsx

@@ -0,0 +1,40 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { useTooltipProvider } from "../useTooltipProvider";
+
+/**
+ * `useTooltipProvider` schedules its skip-delay reset with a raw
+ * `setTimeout`, so it is exercised here directly rather than through the
+ * full `Tooltip.Provider` tree — the defect under test (a timer surviving
+ * unmount) has no user-facing render output to assert on.
+ */
+function Probe() {
+  const { contextValue } = useTooltipProvider({
+    delayDuration: 0,
+    skipDelayDuration: 300,
+  });
+  return <button onClick={contextValue.onCloseGlobally}>close</button>;
+}
+
+describe("useTooltipProvider — timer cleanup", () => {
+  it("clears the pending skip-delay timeout on unmount instead of letting it fire later", async () => {
+    const user = userEvent.setup();
+    const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout");
+    const clearTimeoutSpy = vi.spyOn(globalThis, "clearTimeout");
+
+    const { unmount } = render(<Probe />);
+    await user.click(screen.getByRole("button", { name: "close" }));
+
+    // setTimeoutSpy also captures unrelated timers (userEvent's own
+    // scheduling, React internals) — find the one this hook scheduled with
+    // its 300ms skipDelayDuration.
+    const callIndex = setTimeoutSpy.mock.calls.findIndex(
+      ([, delay]) => delay === 300,
+    );
+    const timerId = setTimeoutSpy.mock.results[callIndex].value;
+    unmount();
+
+    expect(clearTimeoutSpy).toHaveBeenCalledWith(timerId);
+  });
+});

package/src/Tooltip/hooks/useTooltipProvider.ts

@@ -1,4 +1,4 @@
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 
 import type { TooltipProviderContextValue } from "../types";
 
@@ -29,6 +29,18 @@ export function useTooltipProvider({
     }, skipDelayDuration);
   }, [skipDelayDuration]);
 
+  // The skip-delay reset is a raw `setTimeout`, so it outlives the
+  // component it was scheduled from unless explicitly cancelled — without
+  // this, an in-flight timer fires after unmount and can throw once its
+  // surrounding environment (e.g. a test's jsdom `window`) is gone.
+  useEffect(() => {
+    return () => {
+      if (skipDelayTimerRef.current !== null) {
+        clearTimeout(skipDelayTimerRef.current);
+      }
+    };
+  }, []);
+
   const contextValue: TooltipProviderContextValue = {
     delayDuration,
     skipDelayDuration,

package/src/Tooltip/types.ts

@@ -30,12 +30,26 @@ export type TooltipContextValue = {
 };
 
 /**
- * Props for {@link Tooltip.Provider} — sets the `delayDuration` and
- * `skipDelayDuration` shared by every tooltip in the subtree.
+ * Props for {@link Tooltip.Provider} — sets the delay timings shared by every
+ * tooltip in the subtree.
  */
 export type TooltipProviderProps = {
+  /** The tooltips (and other markup) that share this Provider's timings. */
   children?: ReactNode;
+  /**
+   * How long, in milliseconds, a pointer must rest on a trigger before the
+   * tooltip opens on hover. Focus always opens immediately regardless of this.
+   * Overridable per tooltip via {@link TooltipRootProps.delayDuration}.
+   * @default 700
+   */
   delayDuration?: number;
+  /**
+   * The grace window, in milliseconds, after a tooltip in this group closes
+   * during which hovering *another* trigger in the same Provider opens it
+   * instantly (no `delayDuration` wait). Rest longer than this and the next
+   * hover pays the full delay again.
+   * @default 300
+   */
   skipDelayDuration?: number;
 };
 
@@ -45,8 +59,16 @@ export type TooltipProviderProps = {
  * and `open` is forbidden.
  */
 export type UncontrolledTooltipRootProps = {
+  /**
+   * Whether the tooltip is open on first render. The component owns the flag
+   * from then on (hover/focus/blur/Escape drive it internally).
+   * @default false
+   */
   defaultOpen?: boolean;
+  /** Forbidden in uncontrolled mode — use `defaultOpen` instead. */
   open?: never;
+  /** Called with the new open state after every transition. Optional in
+   * uncontrolled mode; use it to observe (not drive) open/close. */
   onOpenChange?: (open: boolean) => void;
 };
 
@@ -56,8 +78,13 @@ export type UncontrolledTooltipRootProps = {
  * forbidden.
  */
 export type ControlledTooltipRootProps = {
+  /** The current open state. The delay and grace timers still run and call
+   * `onOpenChange`, but the tooltip only moves when the parent updates this. */
   open: boolean;
+  /** Called with the requested open state whenever the tooltip wants to open
+   * or close. Optional even in controlled mode. */
   onOpenChange?: (open: boolean) => void;
+  /** Forbidden in controlled mode — use `open` instead. */
   defaultOpen?: never;
 };
 
@@ -68,45 +95,99 @@ export type ControlledTooltipRootProps = {
  * so TypeScript accepts exactly one mode.
  */
 export type TooltipRootProps = {
+  /** The tooltip's {@link TooltipTriggerProps | `Tooltip.Trigger`},
+   * {@link TooltipContentProps | `Tooltip.Content`} (usually inside a
+   * {@link TooltipPortalProps | `Tooltip.Portal`}), and optional
+   * {@link TooltipArrowProps | `Tooltip.Arrow`}. */
   children?: ReactNode;
+  /**
+   * Overrides {@link TooltipProviderProps.delayDuration} for this tooltip only
+   * — the hover open delay in milliseconds. Falls back to the Provider's value
+   * when omitted.
+   */
   delayDuration?: number;
+  /**
+   * When `true`, removes the pointer-leave grace period: the tooltip closes the
+   * instant the pointer leaves the trigger, so the user cannot move into the
+   * content. Leave `false` for tooltips whose content is meant to be hovered.
+   * @default false
+   */
   disableHoverableContent?: boolean;
 } & (UncontrolledTooltipRootProps | ControlledTooltipRootProps);
 
 /**
  * Props for {@link Tooltip.Trigger} — all native `<button>` attributes plus
- * the `asChild` escape hatch.
+ * the `asChild` escape hatch. The `aria-describedby`, `data-state`, and the
+ * hover/focus/blur/Escape open-close handlers are added by the component
+ * (consumer handlers compose and run first).
  */
 export type TooltipTriggerProps = ComponentProps<"button"> & {
+  /**
+   * Render the single child element (a link, icon button, etc.) instead of the
+   * default `<button>`, merging the trigger's ARIA and event handlers onto it
+   * via the {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
 };
 
 /**
  * Props for {@link Tooltip.Portal} — the `container` to render the content
- * into (defaults to `document.body`) and `forceMount` to keep the content
- * in the DOM while closed for exit animations.
+ * into and `forceMount` to keep the content in the DOM while closed for exit
+ * animations.
  */
 export type TooltipPortalProps = {
+  /** The content to portal — typically a single
+   * {@link TooltipContentProps | `Tooltip.Content`}. */
   children?: ReactNode;
+  /**
+   * The element to portal the content into.
+   * @default document.body
+   */
   container?: HTMLElement;
+  /**
+   * Keep the content mounted while the tooltip is closed (instead of removing
+   * it), so a CSS exit animation on `data-state="closed"` can play.
+   * @default false
+   */
   forceMount?: boolean;
 };
 
 /**
  * Props for {@link Tooltip.Content} — all native `<div>` attributes plus
- * `forceMount` and the dismissal callbacks fired on Escape
- * (`onEscapeKeyDown`) and outside pointer-down (`onPointerDownOutside`).
+ * `forceMount` and the dismissal escape hatches. The component adds
+ * `role="tooltip"`, the shared `id` (for the trigger's `aria-describedby`),
+ * the `data-state` hook, and the pointer handlers that cancel/allow the grace
+ * period close.
  */
 export type TooltipContentProps = ComponentProps<"div"> & {
+  /**
+   * Keep the content mounted while the tooltip is closed (instead of removing
+   * it), so a CSS exit animation on `data-state="closed"` can play.
+   * @default false
+   */
   forceMount?: boolean;
+  /**
+   * Fires when `Escape` is pressed while the tooltip is open. Call
+   * `event.preventDefault()` to keep the tooltip open; otherwise it closes.
+   */
   onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  /**
+   * Fires on a pointer-down outside the content. Call `event.preventDefault()`
+   * to keep the tooltip open; otherwise it closes.
+   */
   onPointerDownOutside?: (event: PointerEvent) => void;
 };
 
 /**
  * Props for {@link Tooltip.Arrow} — all native `<span>` attributes plus the
- * `asChild` escape hatch.
+ * `asChild` escape hatch. Purely presentational; position and size it with CSS.
  */
 export type TooltipArrowProps = ComponentProps<"span"> & {
+  /**
+   * Render the single child element (e.g. an `<svg>`) instead of the default
+   * `<span>` via the {@link Slot} pattern.
+   * @default false
+   */
   asChild?: boolean;
 };