@primitiv-ui/react 0.1.37 → 0.1.39

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

@@ -1,71 +0,0 @@
-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

@@ -1,69 +0,0 @@
-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

@@ -1,44 +0,0 @@
-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

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

package/src/Popover/hooks/usePopoverContent.ts

@@ -1,98 +0,0 @@
-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

@@ -1,84 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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

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

package/src/Popover/types.ts

@@ -1,197 +0,0 @@
-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

@@ -1,70 +0,0 @@
-import type { ReactPortal } from "react";
-import { createPortal } from "react-dom";
-
-import type { PortalProps } from "./types";
-
-/**
- * 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";
- *
- * <Portal>
- *   <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");
- *
- * <Portal container={overlayRoot}>
- *   <div role="tooltip">Tooltip content</div>
- * </Portal>
- * ```
- */
-function Portal({ children, container }: PortalProps): ReactPortal {
-  return createPortal(children, container ?? document.body);
-}
-
-/** @internal */
-Portal.displayName = "Portal";
-
-export { Portal };