@primitiv-ui/react 0.1.38 → 0.1.39

package/src/Popover/Popover.tsx

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

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

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

@@ -1,38 +0,0 @@
-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");
-  });
-});