@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Popover/Popover.tsx

@@ -0,0 +1,427 @@
+import { useEffect, useId } from "react";
+import type { ReactElement, Ref } from "react";
+
+import { Slot, composeEventHandlers } from "../Slot/index.ts";
+import { PopoverContext, usePopoverContext } from "./PopoverContext";
+import {
+  usePopoverContent,
+  usePopoverRoot,
+  usePopoverTrigger,
+} from "./hooks/index.ts";
+
+import type {
+  PopoverAnchorProps,
+  PopoverCloseProps,
+  PopoverContentProps,
+  PopoverDescriptionProps,
+  PopoverRootProps,
+  PopoverTitleProps,
+  PopoverTriggerProps,
+} from "./types";
+
+/**
+ * The root of a Popover — owns open state, generates the ids that wire the
+ * trigger to the content, and provides context to descendants. Renders no DOM
+ * of its own.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass {@link PopoverRootUncontrolledProps.defaultOpen | `defaultOpen`}
+ *   (or omit it for closed-on-mount). The component owns the open flag
+ *   internally; observe transitions with `onOpenChange`.
+ * - **Controlled** — pass {@link PopoverRootControlledProps.open | `open`} *and*
+ *   {@link PopoverRootControlledProps.onOpenChange | `onOpenChange`} together.
+ *   The parent owns the flag; the component defers every change back through
+ *   the callback.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Popover.Root>
+ *   <Popover.Trigger>Open</Popover.Trigger>
+ *   <Popover.Content>...</Popover.Content>
+ * </Popover.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Popover.Root open={open} onOpenChange={setOpen}>
+ *   <Popover.Trigger>Open</Popover.Trigger>
+ *   <Popover.Content>...</Popover.Content>
+ * </Popover.Root>
+ * ```
+ */
+export function PopoverRoot({
+  children,
+  defaultOpen,
+  open,
+  onOpenChange,
+}: PopoverRootProps): ReactElement {
+  const { contextValue } = usePopoverRoot({ defaultOpen, open, onOpenChange });
+
+  return (
+    <PopoverContext.Provider value={contextValue}>
+      {children}
+    </PopoverContext.Provider>
+  );
+}
+
+/** @internal */
+PopoverRoot.displayName = "PopoverRoot";
+
+/**
+ * A button that toggles the popover. Renders `<button type="button">` with
+ * full ARIA wiring:
+ *
+ * - `aria-haspopup="dialog"`
+ * - `aria-expanded` tracks open state
+ * - `aria-controls` points at the `Popover.Content` dialog's id
+ *
+ * Clicking toggles the popover; a consumer `onClick` composes (runs first, can
+ * `event.preventDefault()` to veto the toggle).
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied element
+ * (e.g. an icon button of your own) with the trigger's ARIA, composed event
+ * handlers, and ref merged in. Supply the child's element type via the generic
+ * (e.g. `Popover.Trigger<HTMLAnchorElement>`).
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Trigger>Open</Popover.Trigger>
+ *
+ * <Popover.Trigger<HTMLAnchorElement> asChild>
+ *   <a href="#panel">Open</a>
+ * </Popover.Trigger>
+ * ```
+ */
+export function PopoverTrigger<T extends HTMLElement = HTMLButtonElement>({
+  children,
+  asChild = false,
+  ref,
+  ...rest
+}: PopoverTriggerProps<T>): ReactElement {
+  const { triggerProps } = usePopoverTrigger({
+    ref: ref as Ref<HTMLButtonElement>,
+    asChild,
+    ...rest,
+  });
+
+  if (asChild) {
+    return <Slot {...triggerProps}>{children}</Slot>;
+  }
+
+  return (
+    <button type="button" {...triggerProps}>
+      {children}
+    </button>
+  );
+}
+
+/** @internal */
+PopoverTrigger.displayName = "PopoverTrigger";
+
+/**
+ * The floating panel, rendered with the native HTML
+ * [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+ * (`popover="auto"`) — no portal, no floating-ui. The browser manages the top
+ * layer and light-dismiss (outside click / Escape); visual placement is your
+ * CSS concern (use CSS anchor positioning against the trigger or
+ * {@link PopoverAnchor | `Popover.Anchor`}).
+ *
+ * Renders a `<div role="dialog">`. On open, focus moves into the panel (first
+ * focusable descendant, else the panel itself — it carries `tabIndex={-1}`).
+ * `Escape` closes and returns focus to the trigger. `aria-labelledby` /
+ * `aria-describedby` are wired automatically when `Popover.Title` /
+ * `Popover.Description` are rendered inside.
+ *
+ * **`asChild` prop.** Pass `asChild` to render a consumer element (e.g. a
+ * `<section>` or a motion wrapper) with the dialog props and internal ref
+ * merged in. A consumer `ref` composes with the internal ref, so open state
+ * keeps working.
+ *
+ * **Styling hook.** `data-state="open" | "closed"`.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Content className="panel">
+ *   <Popover.Title>Filters</Popover.Title>
+ *   <Popover.Close>Done</Popover.Close>
+ * </Popover.Content>
+ * ```
+ */
+export function PopoverContent({
+  children,
+  onKeyDown,
+  asChild = false,
+  ref,
+  ...rest
+}: PopoverContentProps): ReactElement {
+  const { contentProps } = usePopoverContent({
+    onKeyDown,
+    ref: ref as Ref<HTMLDivElement>,
+  });
+
+  if (asChild) {
+    return (
+      <Slot {...rest} {...contentProps}>
+        {children}
+      </Slot>
+    );
+  }
+
+  return (
+    <div {...rest} {...contentProps}>
+      {children}
+    </div>
+  );
+}
+
+/** @internal */
+PopoverContent.displayName = "PopoverContent";
+
+/**
+ * An optional positioning reference. By default the popover is positioned
+ * against the trigger; render `Popover.Anchor` around (or in place of) another
+ * element to anchor the panel there instead — useful when the trigger is a
+ * small icon inside a larger control.
+ *
+ * Renders a `<div>`. Positioning is CSS-driven: attach a CSS `anchor-name` to
+ * this element and a matching `position-anchor` to `Popover.Content`. Pass
+ * `asChild` to project the anchor semantics onto an existing element.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Anchor asChild>
+ *   <div className="field" style={{ anchorName: "--popover" }}>
+ *     <input />
+ *     <Popover.Trigger>▾</Popover.Trigger>
+ *   </div>
+ * </Popover.Anchor>
+ * ```
+ */
+export function PopoverAnchor({
+  children,
+  asChild = false,
+  ...rest
+}: PopoverAnchorProps): ReactElement {
+  // Consume context so an Anchor rendered outside a Root throws, matching the
+  // other sub-components. Positioning itself is a CSS (anchor-name) concern.
+  usePopoverContext();
+
+  if (asChild) {
+    return <Slot {...rest}>{children}</Slot>;
+  }
+
+  return <div {...rest}>{children}</div>;
+}
+
+/** @internal */
+PopoverAnchor.displayName = "PopoverAnchor";
+
+/**
+ * A button that closes the popover and returns focus to the trigger. Renders a
+ * `<button type="button">` whose `onClick` composes with the close — consumer
+ * handlers run first and can `event.preventDefault()` to veto closing.
+ *
+ * Pass `asChild` to render any element (e.g. a text link or your own icon
+ * button) with the close behaviour merged in.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Close>Done</Popover.Close>
+ * ```
+ */
+export function PopoverClose({
+  children,
+  onClick,
+  asChild = false,
+  ...rest
+}: PopoverCloseProps): ReactElement {
+  const { setOpen, triggerRef } = usePopoverContext();
+
+  const closeProps = {
+    ...rest,
+    onClick: composeEventHandlers(onClick, () => {
+      setOpen(false);
+      triggerRef.current?.focus();
+    }),
+  };
+
+  if (asChild) {
+    return <Slot {...closeProps}>{children}</Slot>;
+  }
+
+  return (
+    <button type="button" {...closeProps}>
+      {children}
+    </button>
+  );
+}
+
+/** @internal */
+PopoverClose.displayName = "PopoverClose";
+
+/**
+ * The popover's accessible name. Renders an `<h2>` by default and
+ * auto-registers its generated id so `Popover.Content` wires it up as
+ * `aria-labelledby`. Pass `asChild` to render your own heading element (e.g.
+ * an `<h3>`); the id is still registered.
+ *
+ * @extends HTMLHeadingElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Title>Filters</Popover.Title>
+ * ```
+ */
+export function PopoverTitle({
+  children,
+  asChild = false,
+  ...rest
+}: PopoverTitleProps): ReactElement {
+  const { registerTitle } = usePopoverContext();
+  const id = useId();
+
+  useEffect(() => {
+    registerTitle(id);
+    return () => registerTitle(undefined);
+  }, [registerTitle, id]);
+
+  if (asChild) {
+    return (
+      <Slot id={id} {...rest}>
+        {children}
+      </Slot>
+    );
+  }
+
+  return (
+    <h2 id={id} {...rest}>
+      {children}
+    </h2>
+  );
+}
+
+/** @internal */
+PopoverTitle.displayName = "PopoverTitle";
+
+/**
+ * The popover's accessible description. Renders a `<p>` by default and
+ * auto-registers its generated id so `Popover.Content` wires it up as
+ * `aria-describedby`. Pass `asChild` to render any element; the id is still
+ * registered.
+ *
+ * @extends HTMLParagraphElement
+ *
+ * @example
+ * ```tsx
+ * <Popover.Description>Narrow the results below.</Popover.Description>
+ * ```
+ */
+export function PopoverDescription({
+  children,
+  asChild = false,
+  ...rest
+}: PopoverDescriptionProps): ReactElement {
+  const { registerDescription } = usePopoverContext();
+  const id = useId();
+
+  useEffect(() => {
+    registerDescription(id);
+    return () => registerDescription(undefined);
+  }, [registerDescription, id]);
+
+  if (asChild) {
+    return (
+      <Slot id={id} {...rest}>
+        {children}
+      </Slot>
+    );
+  }
+
+  return (
+    <p id={id} {...rest}>
+      {children}
+    </p>
+  );
+}
+
+/** @internal */
+PopoverDescription.displayName = "PopoverDescription";
+
+/** Type of the {@link Popover} compound — the Root callable plus its sub-components. */
+type PopoverCompound = typeof PopoverRoot & {
+  /** The root, owning open state and context. */
+  Root: typeof PopoverRoot;
+  /** The button that toggles the popover. */
+  Trigger: typeof PopoverTrigger;
+  /** An optional positioning reference used instead of the trigger. */
+  Anchor: typeof PopoverAnchor;
+  /** The floating panel. */
+  Content: typeof PopoverContent;
+  /** A button that closes the popover. */
+  Close: typeof PopoverClose;
+  /** The popover's accessible name; auto-wires `aria-labelledby`. */
+  Title: typeof PopoverTitle;
+  /** The popover's accessible description; auto-wires `aria-describedby`. */
+  Description: typeof PopoverDescription;
+};
+
+/**
+ * Headless, accessible **Popover** — a compound component built on the native
+ * HTML Popover API (`popover="auto"`). A non-modal dialog anchored to a
+ * trigger: the browser owns the top layer and light-dismiss, focus moves into
+ * the panel on open and returns to the trigger on close, and the background
+ * stays interactive (no focus trap — use `Modal` for that). Zero styles ship;
+ * visual placement is your CSS concern (CSS anchor positioning).
+ *
+ * `Popover` is both callable (an alias of {@link PopoverRoot | `Popover.Root`})
+ * and carries its sub-components as static properties.
+ *
+ * - {@link PopoverRoot | `Popover.Root`} — state owner and context provider.
+ * - {@link PopoverTrigger | `Popover.Trigger`} — `<button>` that toggles the popover.
+ * - {@link PopoverAnchor | `Popover.Anchor`} — optional positioning reference.
+ * - {@link PopoverContent | `Popover.Content`} — the native-popover `role="dialog"` panel.
+ * - {@link PopoverClose | `Popover.Close`} — `<button>` that closes the popover.
+ * - {@link PopoverTitle | `Popover.Title`} — accessible name; auto-wires `aria-labelledby`.
+ * - {@link PopoverDescription | `Popover.Description`} — auto-wires `aria-describedby`.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Popover } from "@primitiv-ui/react";
+ *
+ * <Popover.Root>
+ *   <Popover.Trigger>Filters</Popover.Trigger>
+ *   <Popover.Content>
+ *     <Popover.Title>Filters</Popover.Title>
+ *     <Popover.Description>Narrow the results.</Popover.Description>
+ *     <Popover.Close>Done</Popover.Close>
+ *   </Popover.Content>
+ * </Popover.Root>;
+ * ```
+ *
+ * @see {@link PopoverRoot} for the controlled/uncontrolled state modes.
+ * @see {@link PopoverContent} for focus behaviour and ARIA auto-wiring.
+ */
+const PopoverCompound: PopoverCompound = Object.assign(PopoverRoot, {
+  Root: PopoverRoot,
+  Trigger: PopoverTrigger,
+  Anchor: PopoverAnchor,
+  Content: PopoverContent,
+  Close: PopoverClose,
+  Title: PopoverTitle,
+  Description: PopoverDescription,
+});
+
+PopoverCompound.displayName = "Popover";
+
+export { PopoverCompound as Popover };

package/src/Popover/PopoverContext.ts

@@ -0,0 +1,13 @@
+import type { Context } from "react";
+
+import { createStrictContext } from "../utils/index.ts";
+import { PopoverContextValue } from "./types";
+
+const popoverContext = createStrictContext<PopoverContextValue>(
+  "Popover sub-components must be rendered inside a <Popover.Root>.",
+  "PopoverContext",
+);
+
+export const PopoverContext: Context<PopoverContextValue | null> =
+  popoverContext[0];
+export const usePopoverContext: () => PopoverContextValue = popoverContext[1];

package/src/Popover/README.md

@@ -0,0 +1,106 @@
+# Popover
+
+A headless, accessible **non-modal dialog** anchored to a trigger, built on the
+native HTML [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+(`popover="auto"`). The browser owns the top layer and light-dismiss; the
+background stays interactive. For a modal dialog that traps focus and inerts the
+page, use [Modal](../Modal/README.md) instead.
+
+```tsx
+import { Popover } from "@primitiv-ui/react";
+
+<Popover.Root>
+  <Popover.Trigger>Filters</Popover.Trigger>
+  <Popover.Content>
+    <Popover.Title>Filters</Popover.Title>
+    <Popover.Description>Narrow the results below.</Popover.Description>
+    <Popover.Close>Done</Popover.Close>
+  </Popover.Content>
+</Popover.Root>;
+```
+
+## Sub-components
+
+| Export                 | Role                  | Notes                                                                                     |
+| ---------------------- | --------------------- | ----------------------------------------------------------------------------------------- |
+| `Popover.Root`         | State owner           | Uncontrolled (`defaultOpen`) or controlled (`open` + `onOpenChange`); renders no DOM       |
+| `Popover.Trigger`      | Toggle button         | `<button>` with `aria-haspopup="dialog"` / `aria-expanded` / `aria-controls`; `asChild`   |
+| `Popover.Anchor`       | Positioning reference | Optional `<div>` to anchor against instead of the trigger; `asChild`                       |
+| `Popover.Content`      | Floating panel        | Native-popover `<div role="dialog">`; manages focus + Escape; `asChild`, ref-composing     |
+| `Popover.Close`        | Close button          | Composes `onClick` with close + focus return; `asChild`                                    |
+| `Popover.Title`        | Accessible name        | `<h2>`; auto-wires `aria-labelledby`; `asChild`                                           |
+| `Popover.Description`  | Accessible description | `<p>`; auto-wires `aria-describedby`; `asChild`                                            |
+
+## State modes
+
+- **Uncontrolled** — pass `defaultOpen` (or omit to start closed). `onOpenChange`
+  is optional and fires on every transition.
+- **Controlled** — pass `open` and `onOpenChange` together. The parent owns the
+  value; the component defers every change back through the callback.
+
+The two shapes are discriminated at the type level: passing `defaultOpen`
+alongside `open` is a type error.
+
+## Focus & keyboard
+
+| Key      | Behaviour                                      |
+| -------- | ---------------------------------------------- |
+| `Escape` | Closes the popover, returns focus to the trigger |
+
+On open, focus moves into the panel — to the first focusable descendant, or to
+the `Popover.Content` element itself (it carries `tabIndex={-1}`) when it has
+none. Closing via `Escape` or `Popover.Close` returns focus to the trigger.
+There is **no focus trap**: the popover is non-modal and the rest of the page
+remains reachable.
+
+## Light-dismiss
+
+Because `Popover.Content` uses `popover="auto"`, the browser light-dismisses it
+on an outside click or `Escape` and promotes it to the top layer. The component
+listens for the native `toggle` event to keep React state in sync, with a
+document-click fallback for environments that don't dispatch it (e.g. jsdom).
+
+## Positioning
+
+Placement is a **CSS concern** — no floating-ui, no JS measurement. Use CSS
+anchor positioning: give the trigger (or `Popover.Anchor`) an `anchor-name` and
+`Popover.Content` a matching `position-anchor`, then place it with
+`position-area` / `position-try-fallbacks`. Reach for `Popover.Anchor` when the
+panel should be anchored to something other than the trigger — e.g. a whole
+input group whose trigger is a small button.
+
+```tsx
+<Popover.Root>
+  <Popover.Anchor asChild>
+    <div className="field" style={{ anchorName: "--popover" }}>
+      <input aria-label="Amount" />
+      <Popover.Trigger aria-label="Options">▾</Popover.Trigger>
+    </div>
+  </Popover.Anchor>
+  <Popover.Content /* position-anchor: --popover in CSS */>...</Popover.Content>
+</Popover.Root>;
+```
+
+## `asChild` composition
+
+Every rendered sub-component accepts `asChild` to project its behaviour onto a
+consumer element via [Slot](../Slot.tsx): event handlers compose (child first,
+then the library's, unless the child calls `event.preventDefault()`), `style`
+is shallow-merged, `className` strings concatenate, and refs compose. On
+`Popover.Content`, a consumer `ref` composes with the internal ref so open state
+keeps working.
+
+## Styling hooks
+
+- `data-state="open" | "closed"` on `Popover.Content`.
+- `aria-expanded` on the trigger tracks the same state.
+
+> **Gotcha — don't set `display` on the closed panel.** A closed popover is
+> hidden by the UA rule `[popover]:not(:popover-open) { display: none }`. An
+> author `display` (e.g. `display: flex` for layout) overrides it and leaves the
+> panel visible while closed. Put layout `display` behind `:popover-open`:
+>
+> ```css
+> .panel { padding: 12px; /* no display here */ }
+> .panel:popover-open { display: flex; flex-direction: column; gap: 8px; }
+> ```

package/src/Popover/__tests__/Popover.anchor.test.tsx

@@ -0,0 +1,38 @@
+import { render, screen } from "@testing-library/react";
+
+import { Popover } from "../Popover";
+
+describe("Popover.Anchor", () => {
+  it("renders a div wrapping its children as the positioning reference", () => {
+    // Arrange
+    render(
+      <Popover.Root>
+        <Popover.Anchor data-testid="anchor">
+          <span>Reference</span>
+        </Popover.Anchor>
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Content>Content</Popover.Content>
+      </Popover.Root>,
+    );
+    const anchor = screen.getByTestId("anchor");
+
+    // Assert
+    expect(anchor.tagName).toBe("DIV");
+    expect(anchor).toContainElement(screen.getByText("Reference"));
+  });
+
+  it("forwards arbitrary props to the rendered div", () => {
+    // Arrange
+    render(
+      <Popover.Root>
+        <Popover.Anchor data-testid="anchor" className="anchor-name" />
+        <Popover.Trigger>Open</Popover.Trigger>
+        <Popover.Content>Content</Popover.Content>
+      </Popover.Root>,
+    );
+    const anchor = screen.getByTestId("anchor");
+
+    // Assert
+    expect(anchor).toHaveClass("anchor-name");
+  });
+});