@primitiv-ui/react 0.1.0

package/src/Tooltip/README.md

@@ -0,0 +1,214 @@
+# Tooltip
+
+A headless, accessible compound component implementing the
+[WAI-ARIA Tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/).
+
+Tooltip is built as a pure React state machine with no floating-UI or
+measurement dependency. Positioning is fully the consumer's responsibility
+via CSS Anchor Positioning — the component emits no inline styles.
+
+- Hover and focus open/close with configurable delay.
+- Provider-level skip-delay: a second tooltip opens instantly when one is
+  already open and the cursor moves between triggers.
+- Grace period: 100 ms after leaving the trigger lets users move the cursor
+  into the tooltip content without it closing.
+- `onEscapeKeyDown` and `onPointerDownOutside` escape hatches.
+- Portal support for breaking out of stacking contexts.
+- `forceMount` on Portal and Content for CSS exit animations.
+- `asChild` composition on Trigger and Arrow.
+
+```tsx
+import { Tooltip } from "@primitiv-ui/react";
+
+<Tooltip.Provider>
+  <Tooltip.Root>
+    <Tooltip.Trigger className="save-btn">Save</Tooltip.Trigger>
+    <Tooltip.Portal>
+      <Tooltip.Content className="tooltip">
+        Save your changes
+      </Tooltip.Content>
+    </Tooltip.Portal>
+  </Tooltip.Root>
+</Tooltip.Provider>
+```
+
+## Sub-components
+
+| Export              | Element          | Notes                                                                                                  |
+| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ |
+| `Tooltip.Provider`  | context provider | Sets `delayDuration` (default 700 ms) and `skipDelayDuration` (default 300 ms) for all descendants    |
+| `Tooltip.Root`      | context provider | Owns open state per tooltip. `open`, `defaultOpen`, `onOpenChange`, `delayDuration`, `disableHoverableContent` |
+| `Tooltip.Trigger`   | `<button>`       | Wires `aria-describedby`, hover/focus handlers. `asChild`                                              |
+| `Tooltip.Portal`    | `createPortal`   | `container?: HTMLElement` (default `document.body`). `forceMount`                                      |
+| `Tooltip.Content`   | `<div role="tooltip">` | `data-state`. Escape hatches for Esc / pointer-down-outside. `forceMount`                       |
+| `Tooltip.Arrow`     | `<span>`         | Optional visual pointer. All positioning via consumer CSS. `asChild`                                   |
+
+## Keyboard interaction
+
+| Key   | Behaviour                                                                |
+| ----- | ------------------------------------------------------------------------ |
+| `Tab` | Moves focus to the trigger; opens the tooltip immediately (no delay)     |
+| `Tab` (away) | Closes the tooltip immediately                                  |
+| `Esc` | Closes the tooltip. Preventable via `onEscapeKeyDown`                    |
+
+## State modes
+
+- **Uncontrolled** — pass `defaultOpen` (or omit for closed on mount).
+- **Controlled** — pass `open` and `onOpenChange` together.
+
+The two shapes are statically discriminated at the type level.
+
+```tsx
+// Uncontrolled
+<Tooltip.Root defaultOpen>…</Tooltip.Root>
+
+// Controlled
+const [open, setOpen] = useState(false);
+<Tooltip.Root open={open} onOpenChange={setOpen}>
+  …
+</Tooltip.Root>
+```
+
+## Delay and skip-delay
+
+`delayDuration` (default 700 ms) controls how long the pointer must rest on
+the trigger before the tooltip opens. Set it on `Tooltip.Provider` to apply
+globally, or on an individual `Tooltip.Root` to override.
+
+`skipDelayDuration` (default 300 ms) controls the "skip window". Once one
+tooltip is open, moving to any other trigger opens it instantly. After the
+last tooltip closes, the skip window is active for `skipDelayDuration` ms
+before the normal delay resumes.
+
+```tsx
+<Tooltip.Provider delayDuration={400} skipDelayDuration={150}>
+  …
+</Tooltip.Provider>
+```
+
+## Hoverable content
+
+By default, users can move the cursor from the trigger into the tooltip
+content without it closing (a 100 ms grace period bridges the gap). Set
+`disableHoverableContent` on `Tooltip.Root` to close the tooltip immediately
+when the cursor leaves the trigger:
+
+```tsx
+<Tooltip.Root disableHoverableContent>
+  …
+</Tooltip.Root>
+```
+
+## Escape hatches
+
+Both close paths — Escape and pointer-down-outside — fire observable
+callbacks on `Tooltip.Content`. Call `event.preventDefault()` to keep the
+tooltip open:
+
+```tsx
+<Tooltip.Content
+  onEscapeKeyDown={(event) => {
+    event.preventDefault(); // keep open when Escape is pressed
+  }}
+  onPointerDownOutside={(event) => {
+    event.preventDefault(); // keep open when clicking outside
+  }}
+>
+  …
+</Tooltip.Content>
+```
+
+## CSS anchor positioning
+
+This component is headless — it applies **no inline styles** and no
+positioning logic. Position the tooltip with CSS Anchor Positioning:
+
+```css
+/* Trigger declares an anchor name */
+.my-trigger {
+  anchor-name: --my-tooltip;
+}
+
+/* Content attaches to that anchor */
+.my-tooltip {
+  position: absolute;
+  position-anchor: --my-tooltip;
+  position-area: top;
+  position-try-fallbacks: bottom, left, right;
+  margin-bottom: 8px;
+}
+```
+
+For multiple tooltips on a page, assign each trigger/content pair a
+distinct `anchor-name`. A data attribute or CSS `:nth-child` selector
+can automate this without per-element class names.
+
+## Arrow
+
+`Tooltip.Arrow` renders a `<span>` (or a custom element via `asChild`).
+Arrow position is entirely consumer CSS. A common pattern places it with
+`position: absolute` relative to the content and uses `position-area` or
+a CSS pseudo-element triangle:
+
+```tsx
+<Tooltip.Content className="tooltip">
+  Save your changes
+  <Tooltip.Arrow className="tooltip__arrow" />
+</Tooltip.Content>
+```
+
+```css
+.tooltip__arrow {
+  position: absolute;
+  bottom: -4px;
+  left: 50%;
+  translate: -50% 0;
+  width: 8px;
+  height: 8px;
+  background: inherit;
+  rotate: 45deg;
+}
+```
+
+## Animation hooks
+
+`Tooltip.Portal` and `Tooltip.Content` accept `forceMount`. When set, the
+subtree stays in the DOM while closed so a CSS animation can play on
+`data-state="closed"`:
+
+```tsx
+<Tooltip.Portal forceMount>
+  <Tooltip.Content forceMount>…</Tooltip.Content>
+</Tooltip.Portal>
+```
+
+```css
+[data-state="open"]  { animation: fade-in  120ms ease-out; }
+[data-state="closed"] { animation: fade-out 80ms  ease-in forwards; }
+```
+
+## `asChild` composition
+
+`Tooltip.Trigger` and `Tooltip.Arrow` accept `asChild`. The component
+merges its own props (event handlers, ARIA, `data-state`) onto the
+child element; the child's own handlers run first.
+
+```tsx
+<Tooltip.Trigger asChild>
+  <a href="/help">Help</a>
+</Tooltip.Trigger>
+
+<Tooltip.Arrow asChild>
+  <svg viewBox="0 0 10 5">…</svg>
+</Tooltip.Arrow>
+```
+
+## Styling hooks
+
+`data-state="open" | "closed"` is set on both `Tooltip.Trigger` and
+`Tooltip.Content`:
+
+```css
+.tooltip[data-state="open"]   { opacity: 1; }
+.tooltip[data-state="closed"] { opacity: 0; }
+```

package/src/Tooltip/Tooltip.tsx

@@ -0,0 +1,260 @@
+import { Portal } from "../Portal";
+import { Slot, composeRefs } from "../Slot";
+
+import {
+  TooltipProvider,
+  TooltipProviderProvider,
+  useTooltipContext,
+} from "./TooltipContext";
+import {
+  useTooltipContent,
+  useTooltipProvider,
+  useTooltipRoot,
+  useTooltipTrigger,
+} from "./hooks";
+import type {
+  TooltipArrowProps,
+  TooltipContentProps,
+  TooltipPortalProps,
+  TooltipProviderProps,
+  TooltipRootProps,
+  TooltipTriggerProps,
+} 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.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip.Provider delayDuration={400}>
+ *   <App />
+ * </Tooltip.Provider>
+ * ```
+ */
+function TooltipProviderComponent({
+  children,
+  delayDuration = 700,
+  skipDelayDuration = 300,
+}: TooltipProviderProps) {
+  const { contextValue } = useTooltipProvider({ delayDuration, skipDelayDuration });
+  return (
+    <TooltipProviderProvider value={contextValue}>
+      {children}
+    </TooltipProviderProvider>
+  );
+}
+
+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.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass `defaultOpen` or omit for closed-on-mount.
+ * - **Controlled** — pass `open` (and optionally `onOpenChange`).
+ *
+ * @example
+ * ```tsx
+ * <Tooltip.Root>
+ *   <Tooltip.Trigger>Save</Tooltip.Trigger>
+ *   <Tooltip.Content>Save your changes</Tooltip.Content>
+ * </Tooltip.Root>
+ * ```
+ */
+function TooltipRoot({
+  children,
+  defaultOpen,
+  open,
+  onOpenChange,
+  delayDuration,
+  disableHoverableContent,
+}: TooltipRootProps) {
+  const { contextValue } = useTooltipRoot({
+    defaultOpen,
+    open,
+    onOpenChange,
+    delayDuration,
+    disableHoverableContent,
+  });
+
+  return <TooltipProvider value={contextValue}>{children}</TooltipProvider>;
+}
+
+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.
+ *
+ * ARIA wiring:
+ * - `aria-describedby` points at `Tooltip.Content`'s id.
+ * - `data-state="open" | "closed"` mirrors the tooltip state.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip.Trigger>Save</Tooltip.Trigger>
+ *
+ * <Tooltip.Trigger asChild>
+ *   <a href="/help">Help</a>
+ * </Tooltip.Trigger>
+ * ```
+ */
+function TooltipTrigger({
+  ref,
+  asChild = false,
+  onPointerEnter,
+  onPointerLeave,
+  onFocus,
+  onBlur,
+  onKeyDown,
+  type,
+  ...rest
+}: TooltipTriggerProps) {
+  const { getTriggerProps } = useTooltipTrigger({
+    onPointerEnter,
+    onPointerLeave,
+    onFocus,
+    onBlur,
+    onKeyDown,
+    ...rest,
+  });
+
+  if (asChild) {
+    return <Slot ref={ref} {...getTriggerProps()} />;
+  }
+
+  return <button ref={ref} type={type ?? "button"} {...getTriggerProps()} />;
+}
+
+TooltipTrigger.displayName = "TooltipTrigger";
+
+/**
+ * Renders its children through `React.createPortal` so the tooltip
+ * content is detached from wherever `Tooltip.Root` lives in the tree
+ * and becomes a direct child of `container` (default `document.body`).
+ *
+ * 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"`.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip.Portal>
+ *   <Tooltip.Content>…</Tooltip.Content>
+ * </Tooltip.Portal>
+ * ```
+ */
+function TooltipPortal({ children, container, forceMount }: TooltipPortalProps) {
+  const { open } = useTooltipContext();
+
+  if (!open && !forceMount) return null;
+
+  return <Portal container={container}>{children}</Portal>;
+}
+
+TooltipPortal.displayName = "TooltipPortal";
+
+/**
+ * The tooltip panel. Renders a `<div role="tooltip">` with the shared
+ * `contentId` so `Tooltip.Trigger`'s `aria-describedby` resolves correctly.
+ *
+ * - Unmounts when the tooltip closes unless `forceMount` is set.
+ * - `data-state="open" | "closed"` is always present for CSS animation hooks.
+ * - Pointer events on the content cancel the grace-period close timer,
+ *   letting users move the cursor from the trigger into the content without
+ *   the tooltip dismissing (unless `disableHoverableContent` is set on Root).
+ *
+ * **Escape hatches:**
+ * - `onEscapeKeyDown` — fires when Escape is pressed while the tooltip is
+ *   open; call `event.preventDefault()` to keep it open.
+ * - `onPointerDownOutside` — fires on a pointer-down outside the content;
+ *   call `event.preventDefault()` to keep it open.
+ *
+ * CSS anchor positioning is the consumer's responsibility. Apply
+ * `anchor-name` to the trigger and `position-anchor` / `position-area`
+ * to the content in your own stylesheet.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip.Content className="tooltip__content">
+ *   Save your changes
+ *   <Tooltip.Arrow className="tooltip__arrow" />
+ * </Tooltip.Content>
+ * ```
+ */
+function TooltipContent({
+  ref,
+  forceMount,
+  onEscapeKeyDown,
+  onPointerDownOutside,
+  onPointerEnter,
+  onPointerLeave,
+  ...rest
+}: TooltipContentProps) {
+  const { open } = useTooltipContext();
+  const { getContentProps, internalRef } = useTooltipContent({
+    onEscapeKeyDown,
+    onPointerDownOutside,
+    onPointerEnter,
+    onPointerLeave,
+    ...rest,
+  });
+
+  if (!open && !forceMount) return null;
+
+  return <div ref={composeRefs(internalRef, ref)} {...getContentProps()} />;
+}
+
+TooltipContent.displayName = "TooltipContent";
+
+/**
+ * An optional visual pointer that connects the tooltip content to its
+ * trigger. Renders a `<span>` by default; use `asChild` for a custom
+ * element such as an SVG.
+ *
+ * All positioning and styling is the consumer's responsibility via CSS.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip.Content>
+ *   Save your changes
+ *   <Tooltip.Arrow className="tooltip__arrow" />
+ * </Tooltip.Content>
+ * ```
+ */
+function TooltipArrow({ ref, asChild = false, ...rest }: TooltipArrowProps) {
+  if (asChild) {
+    return <Slot ref={ref} {...rest} />;
+  }
+
+  return <span ref={ref} {...rest} />;
+}
+
+TooltipArrow.displayName = "TooltipArrow";
+
+type TooltipCompound = typeof TooltipRoot & {
+  Provider: typeof TooltipProviderComponent;
+  Root: typeof TooltipRoot;
+  Trigger: typeof TooltipTrigger;
+  Portal: typeof TooltipPortal;
+  Content: typeof TooltipContent;
+  Arrow: typeof TooltipArrow;
+};
+
+const TooltipCompound: TooltipCompound = Object.assign(TooltipRoot, {
+  Provider: TooltipProviderComponent,
+  Root: TooltipRoot,
+  Trigger: TooltipTrigger,
+  Portal: TooltipPortal,
+  Content: TooltipContent,
+  Arrow: TooltipArrow,
+});
+
+TooltipCompound.displayName = "Tooltip";
+
+export { TooltipCompound as Tooltip };

package/src/Tooltip/TooltipContext.ts

@@ -0,0 +1,20 @@
+import { createStrictContext } from "../utils";
+
+import type { TooltipContextValue, TooltipProviderContextValue } from "./types";
+
+export const [TooltipProviderContext, useTooltipProviderContext] =
+  createStrictContext<TooltipProviderContextValue>(
+    "Tooltip sub-components must be rendered inside a <Tooltip.Provider>.",
+    "TooltipProviderContext",
+  );
+
+export const [TooltipContext, useTooltipContext] =
+  createStrictContext<TooltipContextValue>(
+    "Tooltip sub-components must be rendered inside a <Tooltip.Root>.",
+    "TooltipContext",
+  );
+
+const TooltipProviderProvider = TooltipProviderContext.Provider;
+const TooltipProvider = TooltipContext.Provider;
+
+export { TooltipProviderProvider, TooltipProvider };

package/src/Tooltip/__tests__/Tooltip.asChild.test.tsx

@@ -0,0 +1,77 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Tooltip } from "../Tooltip";
+
+describe("Tooltip — asChild", () => {
+  it("Trigger with asChild renders the consumer element instead of a button", () => {
+    render(
+      <Tooltip.Provider>
+        <Tooltip.Root defaultOpen>
+          <Tooltip.Trigger asChild>
+            <a href="/help">Help</a>
+          </Tooltip.Trigger>
+          <Tooltip.Content>Helpful tooltip</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    const link = screen.getByRole("link", { name: "Help" });
+    expect(link).toBeInTheDocument();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("Trigger with asChild merges aria-describedby onto the consumer element", () => {
+    render(
+      <Tooltip.Provider>
+        <Tooltip.Root defaultOpen>
+          <Tooltip.Trigger asChild>
+            <a href="/help">Help</a>
+          </Tooltip.Trigger>
+          <Tooltip.Content>Helpful tooltip</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    const link = screen.getByRole("link", { name: "Help" });
+    const tooltip = screen.getByRole("tooltip");
+    expect(link).toHaveAttribute("aria-describedby", tooltip.id);
+  });
+
+  it("Trigger with asChild still opens the tooltip on focus", async () => {
+    const user = userEvent.setup();
+    render(
+      <Tooltip.Provider>
+        <Tooltip.Root>
+          <Tooltip.Trigger asChild>
+            <a href="/help">Help</a>
+          </Tooltip.Trigger>
+          <Tooltip.Content>Helpful tooltip</Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    await user.tab();
+
+    expect(screen.getByRole("tooltip")).toBeInTheDocument();
+  });
+
+  it("Arrow with asChild renders the consumer element", () => {
+    render(
+      <Tooltip.Provider>
+        <Tooltip.Root defaultOpen>
+          <Tooltip.Trigger>Hover me</Tooltip.Trigger>
+          <Tooltip.Content>
+            Tooltip text
+            <Tooltip.Arrow asChild>
+              <svg data-testid="arrow-svg" />
+            </Tooltip.Arrow>
+          </Tooltip.Content>
+        </Tooltip.Root>
+      </Tooltip.Provider>,
+    );
+
+    expect(screen.getByTestId("arrow-svg")).toBeInTheDocument();
+    expect(screen.queryByRole("tooltip")?.querySelector("span")).toBeNull();
+  });
+});