@primitiv-ui/react 0.1.28 → 0.1.29

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

@@ -0,0 +1,71 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Popover } from "../Popover";
+
+describe("Popover keyboard interaction", () => {
+  it("closes the popover when Escape is pressed", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Popover.Root defaultOpen>
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Content data-testid="content">
+          <button type="button">Inside</button>
+        </Popover.Content>
+      </Popover.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+    const content = screen.getByTestId("content");
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Inside", hidden: true }));
+    await user.keyboard("{Escape}");
+
+    // Assert
+    expect(content).toHaveAttribute("data-state", "closed");
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("returns focus to the trigger after Escape", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Popover.Root defaultOpen>
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Content>
+          <button type="button">Inside</button>
+        </Popover.Content>
+      </Popover.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Inside", hidden: true }));
+    await user.keyboard("{Escape}");
+
+    // Assert
+    expect(trigger).toHaveFocus();
+  });
+
+  it("still fires a consumer onKeyDown on the content", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onKeyDown = vi.fn();
+    render(
+      <Popover.Root defaultOpen>
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Content onKeyDown={onKeyDown}>
+          <button type="button">Inside</button>
+        </Popover.Content>
+      </Popover.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Inside", hidden: true }));
+    await user.keyboard("a");
+
+    // Assert
+    expect(onKeyDown).toHaveBeenCalled();
+  });
+});

package/src/Popover/__tests__/Popover.mouse-interaction.test.tsx

@@ -0,0 +1,69 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Popover } from "../Popover";
+
+describe("Popover mouse interaction", () => {
+  it("opens the popover when the trigger is clicked", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Popover.Root>
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Content data-testid="content">Content</Popover.Content>
+      </Popover.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+    const content = screen.getByTestId("content");
+
+    // Act
+    await user.click(trigger);
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    expect(content).toHaveAttribute("data-state", "open");
+    expect(content).toHaveAttribute("data-popover-open");
+  });
+
+  it("closes the popover when the trigger is clicked again", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Popover.Root>
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Content data-testid="content">Content</Popover.Content>
+      </Popover.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+    const content = screen.getByTestId("content");
+
+    // Act
+    await user.click(trigger);
+    await user.click(trigger);
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(content).toHaveAttribute("data-state", "closed");
+    expect(content).not.toHaveAttribute("data-popover-open");
+  });
+
+  it("composes a consumer onClick on the trigger with the toggle behaviour", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <Popover.Root>
+        <Popover.Trigger onClick={onClick}>Open</Popover.Trigger>
+        <Popover.Content>Content</Popover.Content>
+      </Popover.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+
+    // Act
+    await user.click(trigger);
+
+    // Assert
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+  });
+});

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

@@ -0,0 +1,44 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Popover } from "../Popover";
+
+describe("Popover uncontrolled state", () => {
+  it("starts open when defaultOpen is set", () => {
+    // Arrange & Act
+    render(
+      <Popover.Root defaultOpen>
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Content data-testid="content">Content</Popover.Content>
+      </Popover.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+    const content = screen.getByTestId("content");
+
+    // Assert
+    expect(trigger).toHaveAttribute("aria-expanded", "true");
+    expect(content).toHaveAttribute("data-state", "open");
+    expect(content).toHaveAttribute("data-popover-open");
+  });
+
+  it("notifies onOpenChange as the internal state changes", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <Popover.Root onOpenChange={onOpenChange}>
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Content>Content</Popover.Content>
+      </Popover.Root>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+
+    // Act
+    await user.click(trigger);
+    await user.click(trigger);
+
+    // Assert
+    expect(onOpenChange).toHaveBeenNthCalledWith(1, true);
+    expect(onOpenChange).toHaveBeenNthCalledWith(2, false);
+  });
+});

package/src/Popover/hooks/index.ts

@@ -0,0 +1,3 @@
+export { usePopoverRoot } from "./usePopoverRoot";
+export { usePopoverTrigger } from "./usePopoverTrigger";
+export { usePopoverContent } from "./usePopoverContent";

package/src/Popover/hooks/usePopoverContent.ts

@@ -0,0 +1,98 @@
+import {
+  KeyboardEvent,
+  KeyboardEventHandler,
+  Ref,
+  useEffect,
+  useRef,
+} from "react";
+
+import { composeEventHandlers, composeRefs } from "../../Slot/index.ts";
+import { FOCUSABLE_SELECTOR } from "../../utils/index.ts";
+import { usePopoverContext } from "../PopoverContext";
+
+type UsePopoverContentArgs = {
+  onKeyDown?: KeyboardEventHandler<HTMLDivElement>;
+  ref?: Ref<HTMLDivElement>;
+};
+
+export function usePopoverContent({
+  onKeyDown,
+  ref,
+}: UsePopoverContentArgs = {}) {
+  const { open, setOpen, contentId, triggerRef, titleId, descriptionId } =
+    usePopoverContext();
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const composedRef = ref ? composeRefs(contentRef, ref) : contentRef;
+
+  useEffect(() => {
+    const content = contentRef.current!;
+    if (open) {
+      content.showPopover();
+      // Move focus into the popover (WAI-ARIA non-modal dialog): the first
+      // focusable descendant, or the content itself (it carries tabIndex=-1).
+      const focusable = content.querySelector<HTMLElement>(FOCUSABLE_SELECTOR);
+      (focusable ?? content).focus();
+    } else {
+      try {
+        content.hidePopover();
+      } catch {
+        // already hidden — no-op (e.g. browser already light-dismissed it)
+      }
+    }
+  }, [open]);
+
+  // Sync React state when the browser closes the popover without our code
+  // doing it (real-browser ToggleEvent on light-dismiss or native Escape).
+  useEffect(() => {
+    const content = contentRef.current!;
+    const handleToggle = (event: Event) => {
+      if ((event as ToggleEvent).newState === "closed") setOpen(false);
+    };
+    content.addEventListener("toggle", handleToggle);
+    return () => content.removeEventListener("toggle", handleToggle);
+  }, [setOpen]);
+
+  // Close on clicks outside the popover. This is only a fallback for
+  // environments WITHOUT the native Popover API (e.g. jsdom): a real browser
+  // already light-dismisses an `auto` popover on an outside click and fires the
+  // `toggle` event we sync above. Running this listener in a real browser is
+  // not just redundant — React 19 can flush this effect synchronously inside
+  // the very click that opened the popover from an external control, so the
+  // listener would catch that click and immediately re-close it. Gate it to
+  // non-native environments; `"popover" in HTMLElement.prototype` is true only
+  // where the native API (and its own light-dismiss) exists.
+  useEffect(() => {
+    if (!open) return;
+    if ("popover" in HTMLElement.prototype) return;
+    const handleClick = (event: MouseEvent) => {
+      const target = event.target as Element;
+      if (triggerRef.current?.contains(target)) return;
+      if (target.closest?.("[popover]")) return;
+      setOpen(false);
+    };
+    document.addEventListener("click", handleClick);
+    return () => document.removeEventListener("click", handleClick);
+  }, [open, setOpen, triggerRef]);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      setOpen(false);
+      triggerRef.current?.focus();
+    }
+  };
+
+  const contentProps = {
+    ref: composedRef,
+    id: contentId,
+    role: "dialog" as const,
+    popover: "auto" as const,
+    tabIndex: -1,
+    "aria-labelledby": titleId,
+    "aria-describedby": descriptionId,
+    "data-state": (open ? "open" : "closed") as "open" | "closed",
+    onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+  };
+
+  return { contentProps };
+}

package/src/Popover/hooks/usePopoverRoot.ts

@@ -0,0 +1,84 @@
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+import { useControllableState } from "../../hooks/index.ts";
+import { PopoverContextValue } from "../types";
+
+type UsePopoverRootArgs = {
+  defaultOpen?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+};
+
+export function usePopoverRoot({
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+}: UsePopoverRootArgs) {
+  const contentId = useId();
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const [open, setOpenBase] = useControllableState<boolean>(
+    controlledOpen,
+    defaultOpen,
+    onOpenChange,
+  );
+
+  // Mirror `open` so setOpen can short-circuit repeat transitions within a
+  // single event without a re-render in between. Without this, internal
+  // paths that converge on the same close (e.g. a light-dismiss firing both
+  // a `toggle` event and a document click) would double-notify consumers.
+  const openRef = useRef(open);
+  useEffect(() => {
+    openRef.current = open;
+  });
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (openRef.current === next) return;
+      openRef.current = next;
+      setOpenBase(next);
+    },
+    [setOpenBase],
+  );
+
+  const [titleId, setTitleId] = useState<string | undefined>(undefined);
+  const [descriptionId, setDescriptionId] = useState<string | undefined>(
+    undefined,
+  );
+  const registerTitle = useCallback((id: string | undefined) => {
+    setTitleId(id);
+  }, []);
+  const registerDescription = useCallback((id: string | undefined) => {
+    setDescriptionId(id);
+  }, []);
+
+  const contextValue = useMemo<PopoverContextValue>(
+    () => ({
+      open,
+      setOpen,
+      triggerRef,
+      contentId,
+      titleId,
+      descriptionId,
+      registerTitle,
+      registerDescription,
+    }),
+    [
+      open,
+      setOpen,
+      contentId,
+      titleId,
+      descriptionId,
+      registerTitle,
+      registerDescription,
+    ],
+  );
+
+  return { contextValue };
+}

package/src/Popover/hooks/usePopoverTrigger.ts

@@ -0,0 +1,33 @@
+import { MouseEventHandler, Ref } from "react";
+
+import { composeEventHandlers, composeRefs } from "../../Slot/index.ts";
+import { PopoverTriggerProps } from "../types";
+import { usePopoverContext } from "../PopoverContext";
+
+export function usePopoverTrigger({
+  ref,
+  onClick,
+  asChild = false,
+  ...rest
+}: Omit<PopoverTriggerProps, "children">) {
+  const { open, setOpen, triggerRef, contentId } = usePopoverContext();
+  const composedRef = ref
+    ? composeRefs(triggerRef, ref as Ref<HTMLButtonElement>)
+    : triggerRef;
+
+  const toggle = () => setOpen(!open);
+
+  const triggerProps = {
+    ref: composedRef,
+    "aria-haspopup": "dialog" as const,
+    "aria-expanded": open,
+    "aria-controls": contentId,
+    onClick: composeEventHandlers(
+      onClick as MouseEventHandler | undefined,
+      toggle,
+    ),
+    ...rest,
+  };
+
+  return { triggerProps };
+}

package/src/Popover/index.ts

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

package/src/Popover/types.ts

@@ -0,0 +1,197 @@
+import { ComponentProps, ReactNode, Ref, RefObject } from "react";
+
+/** Props common to both controlled and uncontrolled `Popover.Root` modes. */
+export type PopoverRootBaseProps = {
+  /** The Popover sub-components — typically a {@link PopoverTriggerProps | `Popover.Trigger`}
+   * and a {@link PopoverContentProps | `Popover.Content`}, optionally a
+   * {@link PopoverAnchorProps | `Popover.Anchor`}. */
+  children?: ReactNode;
+};
+
+/**
+ * Props for {@link PopoverRoot | `Popover.Root`} in uncontrolled mode — the
+ * component owns the open state. Pass `defaultOpen` to set the initial value;
+ * `open` is forbidden.
+ */
+export type PopoverRootUncontrolledProps = PopoverRootBaseProps & {
+  /**
+   * Whether the popover is open on first render. The component owns the flag
+   * from then on (trigger toggles, `Popover.Close`, Escape, and light-dismiss
+   * all mutate 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;
+};
+
+/**
+ * Props for {@link PopoverRoot | `Popover.Root`} in controlled mode — the
+ * parent owns the open value. Pass `open` and `onOpenChange` together;
+ * `defaultOpen` is forbidden.
+ */
+export type PopoverRootControlledProps = PopoverRootBaseProps & {
+  /** The current open state. Must be kept in sync by the parent via
+   * `onOpenChange`. */
+  open: boolean;
+  /** Called with the requested open state whenever the popover wants to open
+   * or close (trigger click, `Popover.Close`, Escape, outside dismiss).
+   * Required in controlled mode — the popover will not move unless the parent
+   * updates `open`. */
+  onOpenChange: (open: boolean) => void;
+  /** Forbidden in controlled mode — use `open` instead. */
+  defaultOpen?: never;
+};
+
+/**
+ * Props for {@link PopoverRoot | `Popover.Root`} — a discriminated union that
+ * resolves to either {@link PopoverRootUncontrolledProps} or
+ * {@link PopoverRootControlledProps}, so TypeScript accepts exactly one mode.
+ */
+export type PopoverRootProps =
+  | PopoverRootUncontrolledProps
+  | PopoverRootControlledProps;
+
+/**
+ * Props for {@link PopoverTrigger | `Popover.Trigger`}, the button that toggles
+ * the popover. Extends the native `<button>` attributes (with `ref` re-typed to
+ * the generic element `T`); the trigger's `aria-haspopup` / `aria-expanded` /
+ * `aria-controls` and toggle `onClick` are added by the component (a consumer
+ * `onClick` composes and can `preventDefault()` to veto the toggle).
+ */
+export type PopoverTriggerProps<T extends HTMLElement = HTMLButtonElement> =
+  Omit<ComponentProps<"button">, "ref"> & {
+    /** Trigger content (label, icon, etc.). */
+    children?: ReactNode;
+    /**
+     * Render the single child element instead of the default `<button>`,
+     * merging the trigger's ARIA, composed event handlers, and ref onto it via
+     * the {@link Slot} pattern.
+     * @default false
+     */
+    asChild?: boolean;
+    /** Ref to the rendered element, composed with Root's internal trigger ref
+     * (used for focus return on close). Defaults to `HTMLButtonElement`; with
+     * `asChild`, set the generic to the child's element type
+     * (e.g. `HTMLAnchorElement`). */
+    ref?: Ref<T>;
+  };
+
+/**
+ * Props for {@link PopoverContent | `Popover.Content`}, the floating panel.
+ * Extends the native `<div>` attributes; the component adds `role="dialog"`,
+ * `popover="auto"`, `tabIndex={-1}`, the `aria-labelledby` / `aria-describedby`
+ * wiring (from {@link PopoverTitleProps | `Popover.Title`} /
+ * {@link PopoverDescriptionProps | `Popover.Description`}), and the
+ * `data-state` hook. Open/close, focus movement into the panel, Escape, and
+ * light-dismiss are all handled internally — no props needed.
+ */
+export type PopoverContentProps = ComponentProps<"div"> & {
+  /** Panel content — typically {@link PopoverTitleProps | `Popover.Title`},
+   * body markup, and a {@link PopoverCloseProps | `Popover.Close`}. */
+  children?: ReactNode;
+  /**
+   * Render the single child element (e.g. a `<section>` or motion wrapper)
+   * instead of the default `<div>`, merging the dialog props and internal ref
+   * onto it via the {@link Slot} pattern.
+   * @default false
+   */
+  asChild?: boolean;
+  /** Ref to the rendered element, composed with Root's internal content ref so
+   * open/close and focus management keep working. */
+  ref?: Ref<HTMLDivElement>;
+};
+
+/**
+ * Props for {@link PopoverAnchor | `Popover.Anchor`}, an optional element the
+ * popover is positioned against instead of the trigger. Attach a CSS
+ * `anchor-name` to it and a matching `position-anchor` to
+ * {@link PopoverContentProps | `Popover.Content`}. Renders no behaviour of its
+ * own — positioning is purely a CSS concern.
+ */
+export type PopoverAnchorProps = ComponentProps<"div"> & {
+  /** Anchor content — the element(s) the popover should be positioned against. */
+  children?: ReactNode;
+  /**
+   * Render the single child element instead of the default `<div>`, projecting
+   * the anchor onto an existing element via the {@link Slot} pattern.
+   * @default false
+   */
+  asChild?: boolean;
+};
+
+/**
+ * Props for {@link PopoverClose | `Popover.Close`}, the button that closes the
+ * popover and returns focus to the trigger. Extends the native `<button>`
+ * attributes; a consumer `onClick` composes with the close (runs first, can
+ * `preventDefault()` to veto closing).
+ */
+export type PopoverCloseProps = ComponentProps<"button"> & {
+  /** Close-button content (label, icon, etc.). */
+  children?: ReactNode;
+  /**
+   * Render the single child element (e.g. a text link or icon button) instead
+   * of the default `<button>`, merging the close behaviour onto it via the
+   * {@link Slot} pattern.
+   * @default false
+   */
+  asChild?: boolean;
+};
+
+/**
+ * Props for {@link PopoverTitle | `Popover.Title`}, the popover's accessible
+ * name. Extends the native `<h2>` attributes; the component supplies a
+ * generated `id` and registers it so `Popover.Content` exposes it via
+ * `aria-labelledby`.
+ */
+export type PopoverTitleProps = ComponentProps<"h2"> & {
+  /** Title content, rendered as the popover's accessible name. */
+  children?: ReactNode;
+  /**
+   * Render the single child element (e.g. an `<h3>`) instead of the default
+   * `<h2>` via the {@link Slot} pattern; the generated `id` is still applied
+   * and registered.
+   * @default false
+   */
+  asChild?: boolean;
+};
+
+/**
+ * Props for {@link PopoverDescription | `Popover.Description`}, the popover's
+ * accessible description. Extends the native `<p>` attributes; the component
+ * supplies a generated `id` and registers it so `Popover.Content` exposes it
+ * via `aria-describedby`.
+ */
+export type PopoverDescriptionProps = ComponentProps<"p"> & {
+  /** Description content, exposed as the popover's accessible description. */
+  children?: ReactNode;
+  /**
+   * Render the single child element instead of the default `<p>` via the
+   * {@link Slot} pattern; the generated `id` is still applied and registered.
+   * @default false
+   */
+  asChild?: boolean;
+};
+
+/** Value shared through Popover context to all sub-components. */
+export type PopoverContextValue = {
+  /** Whether the popover is currently open. */
+  open: boolean;
+  /** Request an open-state change. */
+  setOpen: (open: boolean) => void;
+  /** Ref to the trigger element, used for focus return. */
+  triggerRef: RefObject<HTMLButtonElement | null>;
+  /** Generated id of the content panel. */
+  contentId: string;
+  /** Id of the rendered `Popover.Title`, or `undefined` when absent. */
+  titleId: string | undefined;
+  /** Id of the rendered `Popover.Description`, or `undefined` when absent. */
+  descriptionId: string | undefined;
+  /** Register (or clear) the title id for `aria-labelledby`. */
+  registerTitle: (id: string | undefined) => void;
+  /** Register (or clear) the description id for `aria-describedby`. */
+  registerDescription: (id: string | undefined) => void;
+};

package/src/Portal/Portal.tsx

@@ -4,21 +4,61 @@ import { createPortal } from "react-dom";
 import type { PortalProps } from "./types";
 
 /**
- * Renders children outside the current React subtree by mounting them into a
- * DOM node via `createPortal`. Defaults to `document.body`; pass `container`
- * to target a different element.
+ * Teleports its children into a DOM node outside the current React subtree
+ * using React's `createPortal`. Renders no host element of its own — the
+ * children appear directly inside the target `container`.
+ *
+ * Use `Portal` whenever a subtree must escape its ancestor's stacking context,
+ * overflow clipping, or z-index hierarchy — tooltips, modals, dropdowns, and
+ * similar overlays are the typical cases. `Portal` carries no state, context,
+ * or open/close awareness; those concerns belong in the composing component
+ * (see `Modal.Portal`, which layers open-state suppression and `forceMount` on
+ * top of this primitive).
+ *
+ * **Conditional rendering.** `Portal` always mounts when rendered. To control
+ * visibility, conditionally render the `Portal` itself, or manage show/hide
+ * logic in the composing component:
+ *
+ * ```tsx
+ * {isOpen && (
+ *   <Portal>
+ *     <div role="dialog">…</div>
+ *   </Portal>
+ * )}
+ * ```
+ *
+ * For CSS-driven exit animations, keep the portal mounted and drive styles
+ * through a `data-state` attribute on its child:
+ *
+ * ```tsx
+ * <Portal>
+ *   <div data-state={isOpen ? "open" : "closed"}>…</div>
+ * </Portal>
+ * ```
+ *
+ * **Ref forwarding.** `Portal` does not forward a ref (there is no host
+ * element to attach one to). Attach `ref` directly to the child element
+ * rendered inside the portal.
+ *
+ * @example Mount into document.body (default)
+ * ```tsx
+ * import { Portal } from "@primitiv-ui/react";
  *
- * @example
- * // Mount into document.body (default)
  * <Portal>
- *   <div role="dialog">…</div>
+ *   <div role="dialog" aria-modal="true">
+ *     Modal content rendered directly in document.body
+ *   </div>
  * </Portal>
+ * ```
+ *
+ * @example Mount into a custom container
+ * ```tsx
+ * const overlayRoot = document.getElementById("overlay-root");
  *
- * @example
- * // Mount into a specific container
- * <Portal container={document.getElementById("overlays")}>
- *   <div role="dialog">…</div>
+ * <Portal container={overlayRoot}>
+ *   <div role="tooltip">Tooltip content</div>
  * </Portal>
+ * ```
  */
 function Portal({ children, container }: PortalProps): ReactPortal {
   return createPortal(children, container ?? document.body);