@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Drawer/Drawer.tsx

@@ -0,0 +1,315 @@
+import type { ReactElement } from "react";
+
+import { Modal } from "../Modal/index.ts";
+import type {
+  DrawerCloseProps,
+  DrawerContentProps,
+  DrawerDescriptionProps,
+  DrawerOverlayProps,
+  DrawerPortalProps,
+  DrawerRootProps,
+  DrawerTitleProps,
+  DrawerTriggerProps,
+} from "./types";
+
+/**
+ * The root of a Drawer — owns open state, registers the dialog's id,
+ * title id, and description id, and exposes an imperative handle for
+ * opening / closing from outside the React subtree.
+ *
+ * A Drawer *is* a {@link Modal | Modal} that slides in from a screen edge, so
+ * `Drawer.Root` delegates its entire behaviour to `Modal.Root`: the two
+ * state modes (uncontrolled `defaultOpen` vs. controlled `open` +
+ * `onOpenChange`, statically discriminated at the type level) and the
+ * imperative open/close API are identical.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Drawer.Root defaultOpen>
+ *   <Drawer.Content>...</Drawer.Content>
+ * </Drawer.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Drawer.Root open={open} onOpenChange={setOpen}>
+ *   <Drawer.Trigger>Open</Drawer.Trigger>
+ *   <Drawer.Portal>
+ *     <Drawer.Overlay />
+ *     <Drawer.Content side="right">...</Drawer.Content>
+ *   </Drawer.Portal>
+ * </Drawer.Root>
+ * ```
+ */
+function DrawerRoot(props: DrawerRootProps): ReactElement {
+  return <Modal.Root {...props} />;
+}
+
+DrawerRoot.displayName = "DrawerRoot";
+
+/**
+ * A button that toggles the drawer open. Renders a
+ * `<button type="button">` with full ARIA wiring inherited from
+ * `Modal.Trigger`:
+ *
+ * - `aria-haspopup="dialog"`
+ * - `aria-expanded` tracks open state
+ * - `aria-controls` points at the `Drawer.Content` dialog's id
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied
+ * element (e.g. a router `<Link>`) with the trigger's ARIA attributes,
+ * composed event handlers, and ref merged in.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Trigger>Open menu</Drawer.Trigger>
+ *
+ * <Drawer.Trigger asChild>
+ *   <Link to="/cart">Cart</Link>
+ * </Drawer.Trigger>
+ * ```
+ */
+function DrawerTrigger(props: DrawerTriggerProps): ReactElement {
+  return <Modal.Trigger {...props} />;
+}
+
+DrawerTrigger.displayName = "DrawerTrigger";
+
+/**
+ * Renders its children through `React.createPortal` so the drawer is
+ * detached from wherever `Drawer.Root` lives in the React tree and becomes
+ * a direct child of `container` (default `document.body`).
+ *
+ * By default the portal only renders while the drawer is open. Pass
+ * `forceMount` to keep the subtree in the DOM after `open` flips false —
+ * useful for the CSS slide-out animation driven by `data-state="closed"`.
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Portal container={document.getElementById("drawer-root")!}>
+ *   <Drawer.Overlay />
+ *   <Drawer.Content>...</Drawer.Content>
+ * </Drawer.Portal>
+ * ```
+ */
+function DrawerPortal(props: DrawerPortalProps): ReactElement {
+  return <Modal.Portal {...props} />;
+}
+
+DrawerPortal.displayName = "DrawerPortal";
+
+/**
+ * A decorative, animation-friendly backdrop rendered as a **sibling** of
+ * `Drawer.Content`. Like `Modal.Overlay` it is **not** the click-outside
+ * event surface — opening the native `<dialog>` via `showModal()` promotes
+ * it to the top layer with a browser-painted `::backdrop` above this
+ * overlay, so click-outside-to-close is wired on the dialog itself via
+ * `onPointerDownOutside`.
+ *
+ * - `aria-hidden="true"` (the backdrop is decorative).
+ * - `data-state="open" | "closed"` follows the drawer's open state.
+ *
+ * **`asChild` prop.** Pass `asChild` to render a consumer-supplied element
+ * (e.g. a motion wrapper) with the overlay's ARIA and data-state merged in.
+ *
+ * **`forceMount` prop.** Pass `forceMount` to keep the overlay in the DOM
+ * while `open` is false so a CSS fade-out can play.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Overlay />
+ * ```
+ */
+function DrawerOverlay(props: DrawerOverlayProps): ReactElement {
+  return <Modal.Overlay {...props} />;
+}
+
+DrawerOverlay.displayName = "DrawerOverlay";
+
+/**
+ * The native `<dialog>` element — the sliding panel. Behaviour is
+ * `Modal.Content`'s: React drives `showModal()` / `close()` in response to
+ * open state, so the browser owns the inert background, the top layer, and
+ * the `Esc` key, while the same JS `Tab`-wrap focus trap (last ⇄ first)
+ * applies — inherited from `Modal.Content`. `aria-labelledby` /
+ * `aria-describedby` are wired automatically from `Drawer.Title` /
+ * `Drawer.Description`, and the `onEscapeKeyDown` / `onPointerDownOutside`
+ * escape hatches pass straight through.
+ *
+ * **The one drawer-specific addition —
+ * {@link DrawerContentProps.side | `side`}.** Which edge the panel slides in
+ * from (`"top" | "right" | "bottom" | "left"`, default `"right"`). It is
+ * emitted verbatim as `data-side` on the dialog for the styled layer to
+ * position and animate against; it changes no behaviour, focus, or ARIA.
+ *
+ * **`asChild` is intentionally not supported** (as with `Modal.Content`) —
+ * the native dialog is what provides the inert background and top layer (and
+ * hosts the inherited Tab-wrap focus trap).
+ *
+ * **Styling hooks.** `data-state="open" | "closed"` and
+ * `data-side="top|right|bottom|left"` on the dialog.
+ *
+ * @extends HTMLDialogElement
+ *
+ * @example Right-hand drawer (default)
+ * ```tsx
+ * <Drawer.Content>...</Drawer.Content>
+ * ```
+ *
+ * @example Bottom sheet
+ * ```tsx
+ * <Drawer.Content side="bottom">...</Drawer.Content>
+ * ```
+ */
+function DrawerContent({
+  side = "right",
+  ...rest
+}: DrawerContentProps): ReactElement {
+  // `side` is stripped from the props and re-emitted as `data-side` on the
+  // native <dialog> (Modal.Content forwards unrecognised props through its own
+  // `...rest`), giving the styled layer its positioning hook.
+  return <Modal.Content {...rest} data-side={side} />;
+}
+
+DrawerContent.displayName = "DrawerContent";
+
+/**
+ * The drawer's accessible name. Renders an `<h2>` by default and
+ * auto-registers its generated id so `Drawer.Content` can wire it up as
+ * `aria-labelledby` (via `Modal.Title`).
+ *
+ * Pass `asChild` to render the consumer's own heading element; the id is
+ * still registered.
+ *
+ * @extends HTMLHeadingElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Title>Filters</Drawer.Title>
+ * ```
+ */
+function DrawerTitle(props: DrawerTitleProps): ReactElement {
+  return <Modal.Title {...props} />;
+}
+
+DrawerTitle.displayName = "DrawerTitle";
+
+/**
+ * The drawer's accessible description. Renders a `<p>` by default and
+ * auto-registers its generated id so `Drawer.Content` can wire it up as
+ * `aria-describedby` (via `Modal.Description`).
+ *
+ * Pass `asChild` to render any consumer-supplied element; the id is still
+ * registered.
+ *
+ * @extends HTMLParagraphElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Description>Narrow the results below.</Drawer.Description>
+ * ```
+ */
+function DrawerDescription(props: DrawerDescriptionProps): ReactElement {
+  return <Modal.Description {...props} />;
+}
+
+DrawerDescription.displayName = "DrawerDescription";
+
+/**
+ * A button that closes the drawer. Renders a `<button type="button">`
+ * whose `onClick` is composed with the close action (via `Modal.Close`) —
+ * consumer handlers run first and can `event.preventDefault()` to veto.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any element (e.g. an
+ * icon-only button of your own) with the close behaviour merged in.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Close>Done</Drawer.Close>
+ *
+ * <Drawer.Close asChild>
+ *   <IconButton aria-label="Close" icon={<XIcon />} />
+ * </Drawer.Close>
+ * ```
+ */
+function DrawerClose(props: DrawerCloseProps): ReactElement {
+  return <Modal.Close {...props} />;
+}
+
+DrawerClose.displayName = "DrawerClose";
+
+/** @internal */
+type DrawerCompound = typeof DrawerRoot & {
+  Root: typeof DrawerRoot;
+  Trigger: typeof DrawerTrigger;
+  Portal: typeof DrawerPortal;
+  Overlay: typeof DrawerOverlay;
+  Content: typeof DrawerContent;
+  Title: typeof DrawerTitle;
+  Description: typeof DrawerDescription;
+  Close: typeof DrawerClose;
+};
+
+/**
+ * Headless, accessible **Drawer** — a Modal dialog that slides in from a
+ * screen edge. It reuses {@link Modal | Modal}'s native-`<dialog>` machinery
+ * wholesale (focus trap, inert background, top layer, `Esc`, click-outside,
+ * controlled / uncontrolled state, the imperative API), adding a single
+ * presentational axis: {@link DrawerContentProps.side | `side`} on
+ * `Drawer.Content`, emitted as `data-side` for the styled layer to slide the
+ * panel from `top` / `right` / `bottom` / `left`.
+ *
+ * `Drawer` is both callable (an alias of {@link DrawerRoot | `Drawer.Root`})
+ * and carries its sub-components as static properties.
+ *
+ * - {@link DrawerRoot | `Drawer.Root`} — state owner, context provider, imperative API holder.
+ * - {@link DrawerTrigger | `Drawer.Trigger`} — `<button>` that opens the drawer.
+ * - {@link DrawerPortal | `Drawer.Portal`} — `createPortal` wrapper with `container` + `forceMount`.
+ * - {@link DrawerOverlay | `Drawer.Overlay`} — click-outside backdrop sibling of the dialog.
+ * - {@link DrawerContent | `Drawer.Content`} — native `<dialog>` with the `side` axis and auto-ARIA.
+ * - {@link DrawerTitle | `Drawer.Title`} — accessible name; auto-wires `aria-labelledby`.
+ * - {@link DrawerDescription | `Drawer.Description`} — auto-wires `aria-describedby`.
+ * - {@link DrawerClose | `Drawer.Close`} — `<button>` that closes the drawer.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Drawer } from "@primitiv-ui/react";
+ *
+ * <Drawer.Root>
+ *   <Drawer.Trigger>Open</Drawer.Trigger>
+ *   <Drawer.Portal>
+ *     <Drawer.Overlay />
+ *     <Drawer.Content side="right">
+ *       <Drawer.Title>Filters</Drawer.Title>
+ *       <Drawer.Description>Narrow the results below.</Drawer.Description>
+ *       <Drawer.Close>Done</Drawer.Close>
+ *     </Drawer.Content>
+ *   </Drawer.Portal>
+ * </Drawer.Root>;
+ * ```
+ *
+ * @see {@link Modal} for the shared dialog behaviour, state modes, and imperative API.
+ * @see {@link DrawerContent} for the `side` axis and the styling hooks.
+ */
+const DrawerCompound: DrawerCompound = Object.assign(DrawerRoot, {
+  Root: DrawerRoot,
+  Trigger: DrawerTrigger,
+  Portal: DrawerPortal,
+  Overlay: DrawerOverlay,
+  Content: DrawerContent,
+  Title: DrawerTitle,
+  Description: DrawerDescription,
+  Close: DrawerClose,
+});
+
+DrawerCompound.displayName = "Drawer";
+
+export { DrawerCompound as Drawer };

package/src/Drawer/README.md

@@ -0,0 +1,124 @@
+# Drawer
+
+A headless, accessible **dialog that slides in from a screen edge** — a
+settings panel, a filter sheet, a navigation drawer, a cart. Behaviourally it
+_is_ [Modal](../Modal/README.md): it reuses the same native
+[`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) +
+`showModal()` machinery, so the inert background, top-layer stacking, and
+`Esc`-to-close are handled by the browser, and the same JS `Tab`-wrap focus
+trap (last ⇄ first) applies. The single addition is a **`side`** axis on
+`Drawer.Content` that says which edge the panel enters from.
+
+```tsx
+import { Drawer } from "@primitiv-ui/react";
+
+<Drawer.Root>
+  <Drawer.Trigger>Filters</Drawer.Trigger>
+  <Drawer.Portal>
+    <Drawer.Overlay />
+    <Drawer.Content side="right">
+      <Drawer.Title>Filters</Drawer.Title>
+      <Drawer.Description>Narrow the results below.</Drawer.Description>
+      {/* body */}
+      <Drawer.Close>Done</Drawer.Close>
+    </Drawer.Content>
+  </Drawer.Portal>
+</Drawer.Root>;
+```
+
+## Relationship to Modal
+
+Drawer is a **thin composition over Modal** — every sub-component renders its
+`Modal.*` counterpart and inherits its behaviour and props verbatim. There is no
+separate state machine, context, or focus logic to learn or maintain: a fix to
+Modal is a fix to Drawer. The _only_ behavioural surface that differs is
+`Drawer.Content`'s `side` prop. If you need a centred dialog rather than an
+edge-anchored one, use [Modal](../Modal/README.md) directly.
+
+The visual difference — the panel spanning an edge and sliding in — is a
+**styling concern**, driven by the `data-side` hook below, not by this headless
+layer. Panel size is likewise a styling concern (a `size` variant on the styled
+distribution), not a headless prop.
+
+## Sub-components
+
+| Export                | Element / role       | Notes                                                                          |
+| --------------------- | -------------------- | ------------------------------------------------------------------------------ |
+| `Drawer.Root`         | State owner          | Uncontrolled (`defaultOpen`) or controlled (`open` + `onOpenChange`); exposes the imperative API via `ref` |
+| `Drawer.Trigger`      | `<button>`           | `aria-haspopup="dialog"` / `aria-expanded` / `aria-controls`; `asChild`         |
+| `Drawer.Portal`       | `createPortal`       | `container?` (default `document.body`); `forceMount`                             |
+| `Drawer.Overlay`      | `<div>` (sibling)    | Decorative backdrop — **not** the click-outside surface (see Modal); `asChild`, `forceMount` |
+| `Drawer.Content`      | `<dialog>`           | The sliding panel; adds the `side` axis; escape hatches + auto-ARIA. `asChild` **not** supported |
+| `Drawer.Title`        | `<h2>`               | Accessible name; auto-wires `aria-labelledby`; `asChild`                        |
+| `Drawer.Description`  | `<p>`                | Accessible description; auto-wires `aria-describedby`; `asChild`                 |
+| `Drawer.Close`        | `<button>`           | Composes `onClick` with close; `asChild`                                         |
+
+## The `side` axis
+
+`Drawer.Content` accepts **`side`** — `"top" | "right" | "bottom" | "left"`,
+default `"right"`. It is emitted verbatim as **`data-side`** on the `<dialog>`
+and changes no behaviour, focus, or ARIA — it exists purely so the styling layer
+can position and animate the panel against the right edge:
+
+```tsx
+<Drawer.Content side="bottom">...</Drawer.Content>
+// → <dialog data-side="bottom" data-state="open" ...>
+```
+
+```css
+dialog[data-side="right"] {
+  inset: 0 0 0 auto;
+  block-size: 100dvh;
+}
+dialog[data-side="bottom"] {
+  inset: auto 0 0 0;
+  inline-size: 100vw;
+}
+```
+
+## State, focus, keyboard, escape hatches
+
+All identical to [Modal](../Modal/README.md) — see its README for the full
+detail:
+
+- **State modes** — uncontrolled `defaultOpen`, or controlled `open` +
+  `onOpenChange` (statically discriminated; mixing them is a type error).
+- **Imperative API** — `ref.current?.open()` / `.close()` on `Drawer.Root`
+  (`DrawerImperativeApi`). In controlled mode these delegate to `onOpenChange`.
+- **Keyboard** — `Esc` closes (native `cancel`); `Tab` / `Shift+Tab` wrap
+  focus at the dialog's boundaries (the JS trap inherited from `Modal.Content`,
+  since native `showModal()` doesn't cycle focus).
+- **Escape hatches** — `onEscapeKeyDown` and `onPointerDownOutside` on
+  `Drawer.Content`; call `event.preventDefault()` to keep the drawer open.
+- **Click-outside** — detected on the dialog itself (the `::backdrop` sits above
+  a sibling `Drawer.Overlay`), exactly as in Modal.
+
+## Animation hooks
+
+`Drawer.Portal` and `Drawer.Overlay` accept `forceMount` to keep the subtree in
+the DOM while `open` is false, so a CSS slide-out can play against
+`data-state="closed"` before unmount. Combine `data-state` with `data-side` to
+drive direction-aware transforms:
+
+```css
+dialog[data-side="right"][data-state="closed"] {
+  translate: 100% 0;
+}
+dialog[data-side="right"][data-state="open"] {
+  translate: 0 0;
+}
+```
+
+## Styling hooks
+
+- `data-state="open" | "closed"` on `Drawer.Content` (and `Drawer.Overlay`).
+- `data-side="top" | "right" | "bottom" | "left"` on `Drawer.Content`.
+- `aria-expanded` on the trigger tracks the same open state.
+
+## `asChild` composition
+
+Every rendered sub-component except `Drawer.Content` accepts `asChild` to project
+its behaviour onto a consumer element via [Slot](../Slot.tsx), exactly as in
+Modal. `Drawer.Content` is intentionally not slot-able — its native `<dialog>` is
+what provides the inert background and top layer (and hosts the inherited
+Tab-wrap focus trap).

package/src/Drawer/__tests__/Drawer.behavior.test.tsx

@@ -0,0 +1,100 @@
+import "./dialog-polyfill";
+
+import { act, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { createRef } from "react";
+
+import { Drawer } from "../Drawer";
+import type { DrawerImperativeApi } from "../types";
+
+describe("Drawer — behaviour (delegated to Modal)", () => {
+  it("opens on trigger click and closes on Close click", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Drawer.Root>
+        <Drawer.Trigger>Open</Drawer.Trigger>
+        <Drawer.Portal>
+          <Drawer.Content data-testid="drawer">
+            <Drawer.Close>Done</Drawer.Close>
+          </Drawer.Content>
+        </Drawer.Portal>
+      </Drawer.Root>,
+    );
+    // closed → the portal renders nothing
+    expect(screen.queryByTestId("drawer")).toBeNull();
+
+    // Act — open
+    await user.click(screen.getByRole("button", { name: "Open" }));
+    // Assert
+    expect(screen.getByTestId("drawer")).toHaveAttribute("open");
+
+    // Act — close
+    await user.click(screen.getByRole("button", { name: "Done" }));
+    // Assert
+    expect(screen.queryByTestId("drawer")).toBeNull();
+  });
+
+  it("defers to onOpenChange in controlled mode", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <Drawer.Root open={false} onOpenChange={onOpenChange}>
+        <Drawer.Trigger>Open</Drawer.Trigger>
+      </Drawer.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Open" }));
+
+    // Assert
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+
+  it("exposes an imperative open/close handle on Root", () => {
+    // Arrange
+    const ref = createRef<DrawerImperativeApi>();
+    render(
+      <Drawer.Root ref={ref}>
+        <Drawer.Content data-testid="drawer">body</Drawer.Content>
+      </Drawer.Root>,
+    );
+    expect(screen.getByTestId("drawer")).not.toHaveAttribute("open");
+
+    // Act — open
+    act(() => ref.current?.open());
+    // Assert
+    expect(screen.getByTestId("drawer")).toHaveAttribute("open");
+
+    // Act — close
+    act(() => ref.current?.close());
+    // Assert
+    expect(screen.getByTestId("drawer")).not.toHaveAttribute("open");
+  });
+
+  it("forwards a ref to the <dialog> and keeps forceMount mounted while closed", () => {
+    // Arrange
+    const ref = createRef<HTMLDialogElement>();
+
+    // Act
+    render(
+      <Drawer.Root>
+        <Drawer.Portal forceMount>
+          <Drawer.Overlay forceMount data-testid="overlay" />
+          <Drawer.Content ref={ref} data-testid="drawer">
+            body
+          </Drawer.Content>
+        </Drawer.Portal>
+      </Drawer.Root>,
+    );
+
+    // Assert — forceMount keeps the subtree in the DOM even though closed
+    expect(ref.current).toBe(screen.getByTestId("drawer"));
+    expect(ref.current?.tagName).toBe("DIALOG");
+    expect(screen.getByTestId("overlay")).toHaveAttribute(
+      "data-state",
+      "closed",
+    );
+  });
+});

package/src/Drawer/__tests__/Drawer.focus-trap.test.tsx

@@ -0,0 +1,55 @@
+import "./dialog-polyfill";
+
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Drawer } from "../Drawer";
+
+// Drawer.Content delegates wholesale to Modal.Content, so it inherits the
+// boundary Tab-wrap focus trap. These two tests are the conformance guard that
+// the inheritance holds — the exhaustive branch coverage lives in
+// Modal.focus-trap.test.tsx. The Trigger sits outside the dialog so a native
+// wrap (without the trap) would land there, not on the asserted element.
+describe("Drawer focus trap — inherited from Modal.Content", () => {
+  it("wraps focus from the last element back to the first on Tab", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Drawer.Root defaultOpen>
+        <Drawer.Trigger>Open</Drawer.Trigger>
+        <Drawer.Content>
+          <button type="button">First</button>
+          <button type="button">Second</button>
+        </Drawer.Content>
+      </Drawer.Root>,
+    );
+    screen.getByRole("button", { name: "Second" }).focus();
+
+    // Act
+    await user.tab();
+
+    // Assert
+    expect(screen.getByRole("button", { name: "First" })).toHaveFocus();
+  });
+
+  it("wraps focus from the first element to the last on Shift+Tab", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <Drawer.Root defaultOpen>
+        <Drawer.Trigger>Open</Drawer.Trigger>
+        <Drawer.Content>
+          <button type="button">First</button>
+          <button type="button">Second</button>
+        </Drawer.Content>
+      </Drawer.Root>,
+    );
+    screen.getByRole("button", { name: "First" }).focus();
+
+    // Act
+    await user.tab({ shift: true });
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Second" })).toHaveFocus();
+  });
+});