@primitiv-ui/react 0.1.38 → 0.1.40

package/src/Tooltip/__tests__/Tooltip.uncontrolled-state.test.tsx

@@ -1,67 +0,0 @@
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-
-import { Tooltip } from "../Tooltip";
-
-describe("Tooltip — uncontrolled state", () => {
-  it("is closed by default when defaultOpen is not set", () => {
-    render(
-      <Tooltip.Provider>
-        <Tooltip.Root>
-          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
-          <Tooltip.Content>Tooltip text</Tooltip.Content>
-        </Tooltip.Root>
-      </Tooltip.Provider>,
-    );
-
-    expect(screen.queryByRole("tooltip")).toBeNull();
-  });
-
-  it("is open by default when defaultOpen={true}", () => {
-    render(
-      <Tooltip.Provider>
-        <Tooltip.Root defaultOpen>
-          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
-          <Tooltip.Content>Tooltip text</Tooltip.Content>
-        </Tooltip.Root>
-      </Tooltip.Provider>,
-    );
-
-    expect(screen.getByRole("tooltip")).toBeInTheDocument();
-  });
-
-  it("opens immediately when the trigger is focused", async () => {
-    const user = userEvent.setup();
-    render(
-      <Tooltip.Provider>
-        <Tooltip.Root>
-          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
-          <Tooltip.Content>Tooltip text</Tooltip.Content>
-        </Tooltip.Root>
-      </Tooltip.Provider>,
-    );
-
-    await user.tab();
-
-    expect(screen.getByRole("tooltip")).toBeInTheDocument();
-  });
-
-  it("closes immediately when the trigger loses focus", async () => {
-    const user = userEvent.setup();
-    render(
-      <Tooltip.Provider>
-        <Tooltip.Root>
-          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
-          <Tooltip.Content>Tooltip text</Tooltip.Content>
-        </Tooltip.Root>
-        <button>Other</button>
-      </Tooltip.Provider>,
-    );
-
-    await user.tab();
-    expect(screen.getByRole("tooltip")).toBeInTheDocument();
-
-    await user.tab();
-    expect(screen.queryByRole("tooltip")).toBeNull();
-  });
-});

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

@@ -1,40 +0,0 @@
-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/index.ts

@@ -1,4 +0,0 @@
-export * from "./useTooltipProvider";
-export * from "./useTooltipRoot";
-export * from "./useTooltipTrigger";
-export * from "./useTooltipContent";

package/src/Tooltip/hooks/useTooltipContent.ts

@@ -1,56 +0,0 @@
-import { useEffect, useRef } from "react";
-
-import { composeEventHandlers } from "../../Slot/index.ts";
-import { useTooltipContext } from "../TooltipContext";
-import type { TooltipContentProps } from "../types";
-
-export function useTooltipContent({
-  onEscapeKeyDown,
-  onPointerDownOutside,
-  onPointerEnter,
-  onPointerLeave,
-  ...rest
-}: Omit<TooltipContentProps, "forceMount"> = {}) {
-  const { open, contentId, cancelGrace, closeImmediate } = useTooltipContext();
-  const internalRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!open) return;
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key !== "Escape") return;
-      onEscapeKeyDown?.(event);
-      if (event.defaultPrevented) return;
-      closeImmediate();
-    };
-    document.addEventListener("keydown", handleKeyDown);
-    return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [open, onEscapeKeyDown, closeImmediate]);
-
-  useEffect(() => {
-    if (!open) return;
-    const handlePointerDown = (event: PointerEvent) => {
-      // Stryker disable next-line OptionalChaining: equivalent — this listener
-      // is only attached while `open` is true, and the Content `<div>` (and
-      // therefore internalRef.current) is always mounted whenever open is true.
-      if (internalRef.current?.contains(event.target as Node)) return;
-      onPointerDownOutside?.(event);
-      if (event.defaultPrevented) return;
-      closeImmediate();
-    };
-    document.addEventListener("pointerdown", handlePointerDown);
-    return () => document.removeEventListener("pointerdown", handlePointerDown);
-  }, [open, onPointerDownOutside, closeImmediate]);
-
-  function getContentProps() {
-    return {
-      ...rest,
-      id: contentId,
-      role: "tooltip" as const,
-      "data-state": (open ? "open" : "closed") as "open" | "closed",
-      onPointerEnter: composeEventHandlers(onPointerEnter, cancelGrace),
-      onPointerLeave: composeEventHandlers(onPointerLeave, closeImmediate),
-    };
-  }
-
-  return { getContentProps, internalRef };
-}

package/src/Tooltip/hooks/useTooltipProvider.ts

@@ -1,79 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from "react";
-
-import type { TooltipProviderContextValue } from "../types";
-
-type UseTooltipProviderArgs = {
-  delayDuration: number;
-  skipDelayDuration: number;
-};
-
-export function useTooltipProvider({
-  delayDuration,
-  skipDelayDuration,
-}: UseTooltipProviderArgs) {
-  const [isOpenGlobally, setIsOpenGlobally] = useState(false);
-  const skipDelayTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const onOpenGlobally = useCallback(
-    () => {
-      // Stryker disable next-line ConditionalExpression: equivalent —
-      // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
-      // harmless when no skip-delay timer is pending; the false / never-clear
-      // variant is killed by the "clears a pending skip-delay timer when a
-      // tooltip opens again within the skip window" test.
-      if (skipDelayTimerRef.current !== null) {
-        clearTimeout(skipDelayTimerRef.current);
-        skipDelayTimerRef.current = null;
-      }
-      setIsOpenGlobally(true);
-    },
-    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze.
-    [],
-  );
-
-  const onCloseGlobally = useCallback(() => {
-    // Cancel before re-scheduling. The ref tracks only the newest timer, so
-    // overwriting it without cancelling orphans the previous one: it survives,
-    // fires unobserved, and can no longer be cancelled by a later open. Two
-    // closes in a row is not hypothetical — `closeImmediate` is unguarded and
-    // both Escape and blur are wired straight to it, so pressing Escape and then
-    // tabbing away leaks a timer. `clearTimeout(undefined)` is a spec'd no-op, so
-    // this needs no guard for the first close.
-    clearTimeout(skipDelayTimerRef.current ?? undefined);
-    skipDelayTimerRef.current = setTimeout(() => {
-      setIsOpenGlobally(false);
-      skipDelayTimerRef.current = null;
-    }, 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 () => {
-        // Stryker disable next-line ConditionalExpression: equivalent —
-        // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
-        // harmless when no skip-delay timer is pending; the false / never-clear
-        // variant is killed by the "clears the pending skip-delay timeout on
-        // unmount" test.
-        if (skipDelayTimerRef.current !== null) {
-          clearTimeout(skipDelayTimerRef.current);
-        }
-      };
-    },
-    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze (mount/unmount only).
-    [],
-  );
-
-  const contextValue: TooltipProviderContextValue = {
-    delayDuration,
-    skipDelayDuration,
-    isOpenGlobally,
-    onOpenGlobally,
-    onCloseGlobally,
-  };
-
-  return { contextValue };
-}

package/src/Tooltip/hooks/useTooltipRoot.ts

@@ -1,130 +0,0 @@
-import { useCallback, useId, useMemo, useRef } from "react";
-
-import { useControllableState } from "../../hooks/index.ts";
-import { useTooltipProviderContext } from "../TooltipContext";
-import type { TooltipContextValue, TooltipRootProps } from "../types";
-
-const GRACE_PERIOD_MS = 100;
-
-type UseTooltipRootArgs = Pick<
-  TooltipRootProps,
-  "defaultOpen" | "open" | "onOpenChange" | "delayDuration" | "disableHoverableContent"
->;
-
-export function useTooltipRoot({
-  defaultOpen = false,
-  open: controlledOpen,
-  onOpenChange,
-  delayDuration: instanceDelayDuration,
-  disableHoverableContent = false,
-}: UseTooltipRootArgs) {
-  const providerCtx = useTooltipProviderContext();
-  const [open, setOpen] = useControllableState<boolean>(
-    controlledOpen,
-    defaultOpen,
-    onOpenChange,
-  );
-  const contentId = useId();
-  const effectiveDelayDuration = instanceDelayDuration ?? providerCtx.delayDuration;
-
-  const openTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const gracePeriodTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const openImmediate = useCallback(() => {
-    // Stryker disable next-line ConditionalExpression: equivalent —
-    // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
-    // harmless when no open timer is pending; the false / never-clear variant
-    // is killed by the "cancels a pending hover-delay open timer when the
-    // trigger is focused before it elapses" test.
-    if (openTimerRef.current !== null) {
-      clearTimeout(openTimerRef.current);
-      openTimerRef.current = null;
-    }
-    setOpen(true);
-    providerCtx.onOpenGlobally();
-  }, [setOpen, providerCtx]);
-
-  const openWithDelay = useCallback(() => {
-    const delay = providerCtx.isOpenGlobally ? 0 : effectiveDelayDuration;
-    if (delay === 0) {
-      openImmediate();
-    } else {
-      openTimerRef.current = setTimeout(() => {
-        openImmediate();
-        openTimerRef.current = null;
-      }, delay);
-    }
-  }, [openImmediate, effectiveDelayDuration, providerCtx.isOpenGlobally]);
-
-  const closeImmediate = useCallback(() => {
-    // Stryker disable next-line ConditionalExpression: equivalent —
-    // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
-    // harmless when no grace timer is pending; the false / never-clear variant
-    // is killed by the "cancels a pending grace-period timer when the tooltip
-    // closes immediately during the grace window" test.
-    if (gracePeriodTimerRef.current !== null) {
-      clearTimeout(gracePeriodTimerRef.current);
-      gracePeriodTimerRef.current = null;
-    }
-    setOpen(false);
-    providerCtx.onCloseGlobally();
-  }, [setOpen, providerCtx]);
-
-  const cancelGrace = useCallback(
-    () => {
-      // Stryker disable next-line ConditionalExpression: equivalent —
-      // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
-      // harmless when no grace timer is pending; the false / never-clear
-      // variant is killed by the "cancels the grace-period close timer when
-      // the pointer moves into the content" test.
-      if (gracePeriodTimerRef.current !== null) {
-        clearTimeout(gracePeriodTimerRef.current);
-        gracePeriodTimerRef.current = null;
-      }
-    },
-    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze.
-    [],
-  );
-
-  const closeWithGrace = useCallback(() => {
-    // Stryker disable next-line ConditionalExpression: equivalent —
-    // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
-    // harmless when no open timer is pending; the false / never-clear variant
-    // is killed by the "cancels a pending hover-delay open timer when the
-    // pointer leaves before it elapses" test.
-    if (openTimerRef.current !== null) {
-      clearTimeout(openTimerRef.current);
-      openTimerRef.current = null;
-    }
-    gracePeriodTimerRef.current = setTimeout(() => {
-      setOpen(false);
-      providerCtx.onCloseGlobally();
-      gracePeriodTimerRef.current = null;
-    }, GRACE_PERIOD_MS);
-  }, [setOpen, providerCtx]);
-
-  const contextValue = useMemo<TooltipContextValue>(
-    () => ({
-      open,
-      contentId,
-      disableHoverableContent,
-      openWithDelay,
-      openImmediate,
-      closeImmediate,
-      closeWithGrace,
-      cancelGrace,
-    }),
-    [
-      open,
-      contentId,
-      disableHoverableContent,
-      openWithDelay,
-      openImmediate,
-      closeImmediate,
-      closeWithGrace,
-      cancelGrace,
-    ],
-  );
-
-  return { contextValue };
-}

package/src/Tooltip/hooks/useTooltipTrigger.ts

@@ -1,44 +0,0 @@
-import { KeyboardEvent } from "react";
-
-import { composeEventHandlers } from "../../Slot/index.ts";
-import { useTooltipContext } from "../TooltipContext";
-import type { TooltipTriggerProps } from "../types";
-
-export function useTooltipTrigger({
-  onPointerEnter,
-  onPointerLeave,
-  onFocus,
-  onBlur,
-  onKeyDown,
-  ...rest
-}: Omit<TooltipTriggerProps, "asChild"> = {}) {
-  const {
-    open,
-    contentId,
-    disableHoverableContent,
-    openWithDelay,
-    openImmediate,
-    closeImmediate,
-    closeWithGrace,
-  } = useTooltipContext();
-
-  function getTriggerProps() {
-    return {
-      ...rest,
-      "aria-describedby": contentId,
-      "data-state": (open ? "open" : "closed") as "open" | "closed",
-      onPointerEnter: composeEventHandlers(onPointerEnter, openWithDelay),
-      onPointerLeave: composeEventHandlers(
-        onPointerLeave,
-        disableHoverableContent ? closeImmediate : closeWithGrace,
-      ),
-      onFocus: composeEventHandlers(onFocus, openImmediate),
-      onBlur: composeEventHandlers(onBlur, closeImmediate),
-      onKeyDown: composeEventHandlers(onKeyDown, (e: KeyboardEvent<HTMLButtonElement>) => {
-        if (e.key === "Escape") closeImmediate();
-      }),
-    };
-  }
-
-  return { getTriggerProps };
-}

package/src/Tooltip/index.ts

@@ -1,2 +0,0 @@
-export * from "./Tooltip";
-export * from "./types";

package/src/Tooltip/types.ts

@@ -1,193 +0,0 @@
-import { ComponentProps, ReactNode } from "react";
-
-/**
- * Context published by {@link Tooltip.Provider} — the shared open / skip
- * delays and the group-wide open coordination callbacks used to suppress
- * the open delay while another tooltip in the group is already showing.
- */
-export type TooltipProviderContextValue = {
-  delayDuration: number;
-  skipDelayDuration: number;
-  isOpenGlobally: boolean;
-  onOpenGlobally: () => void;
-  onCloseGlobally: () => void;
-};
-
-/**
- * Context published by {@link Tooltip.Root} to its descendants — the live
- * `open` state, the content `id` for ARIA wiring, and the timing callbacks
- * the trigger and content use to open / close with the correct delays.
- */
-export type TooltipContextValue = {
-  open: boolean;
-  contentId: string;
-  disableHoverableContent: boolean;
-  openWithDelay: () => void;
-  openImmediate: () => void;
-  closeImmediate: () => void;
-  closeWithGrace: () => void;
-  cancelGrace: () => void;
-};
-
-/**
- * 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;
-};
-
-/**
- * Uncontrolled variant of {@link TooltipRootProps}: the component owns the
- * open state. Pass `defaultOpen` (or omit it); `onOpenChange` is optional
- * 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;
-};
-
-/**
- * Controlled variant of {@link TooltipRootProps}: the parent owns the open
- * state. Pass `open` (with an optional `onOpenChange`); `defaultOpen` is
- * 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;
-};
-
-/**
- * Props for {@link Tooltip.Root}. Combines the per-tooltip timing /
- * hoverable-content options with one of the two state modes
- * ({@link UncontrolledTooltipRootProps} | {@link 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 `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 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 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. 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;
-};