@primitiv-ui/react 0.1.0

package/src/Tooltip/__tests__/Tooltip.keyboard-interaction.test.tsx

@@ -0,0 +1,85 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Tooltip } from "../Tooltip";
+
+describe("Tooltip — keyboard interaction", () => {
+  it("closes when Escape is pressed while the tooltip is open", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Tooltip.Provider>
+        <Tooltip.Root defaultOpen>
+          <Tooltip.Trigger>Focusable</Tooltip.Trigger>
+          <Tooltip.Content>Tooltip text</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+
+    await user.keyboard("{Escape}");
+
+    expect(screen.queryByRole("tooltip")).toBeNull();
+  });
+
+  it("fires onEscapeKeyDown when Escape is pressed", async () => {
+    const user = userEvent.setup();
+    const onEscapeKeyDown = vi.fn();
+
+    render(
+      <Tooltip.Provider>
+        <Tooltip.Root defaultOpen>
+          <Tooltip.Trigger>Focusable</Tooltip.Trigger>
+          <Tooltip.Content onEscapeKeyDown={onEscapeKeyDown}>
+            Tooltip text
+          </Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    await user.keyboard("{Escape}");
+
+    expect(onEscapeKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the tooltip open when onEscapeKeyDown calls preventDefault()", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Tooltip.Provider>
+        <Tooltip.Root defaultOpen>
+          <Tooltip.Trigger>Focusable</Tooltip.Trigger>
+          <Tooltip.Content
+            onEscapeKeyDown={(e) => e.preventDefault()}
+          >
+            Tooltip text
+          </Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    await user.keyboard("{Escape}");
+
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+  });
+
+  it("closes when Escape is pressed on the trigger while open via focus", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Tooltip.Provider>
+        <Tooltip.Root>
+          <Tooltip.Trigger>Focusable</Tooltip.Trigger>
+          <Tooltip.Content>Tooltip text</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    await user.tab();
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+
+    await user.keyboard("{Escape}");
+    expect(screen.queryByRole("tooltip")).toBeNull();
+  });
+});

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

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

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

package/src/Tooltip/hooks/useTooltipContent.ts

@@ -0,0 +1,53 @@
+import { useEffect, useRef } from "react";
+
+import { composeEventHandlers } from "../../Slot";
+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) => {
+      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

@@ -0,0 +1,41 @@
+import { useCallback, 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(() => {
+    if (skipDelayTimerRef.current !== null) {
+      clearTimeout(skipDelayTimerRef.current);
+      skipDelayTimerRef.current = null;
+    }
+    setIsOpenGlobally(true);
+  }, []);
+
+  const onCloseGlobally = useCallback(() => {
+    skipDelayTimerRef.current = setTimeout(() => {
+      setIsOpenGlobally(false);
+      skipDelayTimerRef.current = null;
+    }, skipDelayDuration);
+  }, [skipDelayDuration]);
+
+  const contextValue: TooltipProviderContextValue = {
+    delayDuration,
+    skipDelayDuration,
+    isOpenGlobally,
+    onOpenGlobally,
+    onCloseGlobally,
+  };
+
+  return { contextValue };
+}

package/src/Tooltip/hooks/useTooltipRoot.ts

@@ -0,0 +1,106 @@
+import { useCallback, useId, useMemo, useRef } from "react";
+
+import { useControllableState } from "../../hooks";
+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(() => {
+    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(() => {
+    if (gracePeriodTimerRef.current !== null) {
+      clearTimeout(gracePeriodTimerRef.current);
+      gracePeriodTimerRef.current = null;
+    }
+    setOpen(false);
+    providerCtx.onCloseGlobally();
+  }, [setOpen, providerCtx]);
+
+  const cancelGrace = useCallback(() => {
+    if (gracePeriodTimerRef.current !== null) {
+      clearTimeout(gracePeriodTimerRef.current);
+      gracePeriodTimerRef.current = null;
+    }
+  }, []);
+
+  const closeWithGrace = useCallback(() => {
+    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

@@ -0,0 +1,44 @@
+import { KeyboardEvent } from "react";
+
+import { composeEventHandlers } from "../../Slot";
+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

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

package/src/Tooltip/types.ts

@@ -0,0 +1,64 @@
+import { ComponentProps, ReactNode } from "react";
+
+export type TooltipProviderContextValue = {
+  delayDuration: number;
+  skipDelayDuration: number;
+  isOpenGlobally: boolean;
+  onOpenGlobally: () => void;
+  onCloseGlobally: () => void;
+};
+
+export type TooltipContextValue = {
+  open: boolean;
+  contentId: string;
+  disableHoverableContent: boolean;
+  openWithDelay: () => void;
+  openImmediate: () => void;
+  closeImmediate: () => void;
+  closeWithGrace: () => void;
+  cancelGrace: () => void;
+};
+
+export type TooltipProviderProps = {
+  children?: ReactNode;
+  delayDuration?: number;
+  skipDelayDuration?: number;
+};
+
+type UncontrolledTooltipRootProps = {
+  defaultOpen?: boolean;
+  open?: never;
+  onOpenChange?: (open: boolean) => void;
+};
+
+type ControlledTooltipRootProps = {
+  open: boolean;
+  onOpenChange?: (open: boolean) => void;
+  defaultOpen?: never;
+};
+
+export type TooltipRootProps = {
+  children?: ReactNode;
+  delayDuration?: number;
+  disableHoverableContent?: boolean;
+} & (UncontrolledTooltipRootProps | ControlledTooltipRootProps);
+
+export type TooltipTriggerProps = ComponentProps<"button"> & {
+  asChild?: boolean;
+};
+
+export type TooltipPortalProps = {
+  children?: ReactNode;
+  container?: HTMLElement;
+  forceMount?: boolean;
+};
+
+export type TooltipContentProps = ComponentProps<"div"> & {
+  forceMount?: boolean;
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+  onPointerDownOutside?: (event: PointerEvent) => void;
+};
+
+export type TooltipArrowProps = ComponentProps<"span"> & {
+  asChild?: boolean;
+};