@primitiv-ui/react 0.1.38 → 0.1.40

package/src/Drawer/README.md

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

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

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

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

@@ -1,111 +0,0 @@
-import "./dialog-polyfill";
-
-import { render, screen } from "@testing-library/react";
-
-import { Drawer } from "../Drawer";
-
-describe("Drawer — rendering & structure", () => {
-  it("Trigger renders a <button> with dialog ARIA", () => {
-    // Arrange / Act
-    render(
-      <Drawer.Root>
-        <Drawer.Trigger>Open</Drawer.Trigger>
-      </Drawer.Root>,
-    );
-
-    // Assert
-    const trigger = screen.getByRole("button", { name: "Open" });
-    expect(trigger).toHaveAttribute("type", "button");
-    expect(trigger).toHaveAttribute("aria-haspopup", "dialog");
-    expect(trigger).toHaveAttribute("aria-expanded", "false");
-  });
-
-  it("Content renders a native <dialog> when open", () => {
-    // Arrange / Act
-    render(
-      <Drawer.Root defaultOpen>
-        <Drawer.Content data-testid="drawer">body</Drawer.Content>
-      </Drawer.Root>,
-    );
-
-    // Assert
-    const dialog = screen.getByTestId("drawer");
-    expect(dialog).toBeInTheDocument();
-    expect(dialog.tagName).toBe("DIALOG");
-  });
-
-  it("Title and Description render and auto-wire the dialog's ARIA", () => {
-    // Arrange / Act
-    render(
-      <Drawer.Root defaultOpen>
-        <Drawer.Content data-testid="drawer">
-          <Drawer.Title>Filters</Drawer.Title>
-          <Drawer.Description>Narrow the results.</Drawer.Description>
-        </Drawer.Content>
-      </Drawer.Root>,
-    );
-
-    // Assert
-    const title = screen.getByRole("heading", { name: "Filters", level: 2 });
-    const description = screen.getByText("Narrow the results.");
-    const dialog = screen.getByTestId("drawer");
-    expect(dialog).toHaveAttribute("aria-labelledby", title.id);
-    expect(dialog).toHaveAttribute("aria-describedby", description.id);
-    expect(description.tagName).toBe("P");
-  });
-
-  it("Portal escapes to document.body and Overlay is a decorative sibling", () => {
-    // Arrange / Act
-    render(
-      <div data-testid="host">
-        <Drawer.Root defaultOpen>
-          <Drawer.Portal>
-            <Drawer.Overlay data-testid="overlay" />
-            <Drawer.Content data-testid="drawer">body</Drawer.Content>
-          </Drawer.Portal>
-        </Drawer.Root>
-      </div>,
-    );
-
-    // Assert
-    const overlay = screen.getByTestId("overlay");
-    expect(overlay).toHaveAttribute("aria-hidden", "true");
-    expect(overlay).toHaveAttribute("data-state", "open");
-    // portalled out of the host wrapper, onto document.body
-    expect(screen.getByTestId("host")).not.toContainElement(
-      screen.getByTestId("drawer"),
-    );
-  });
-
-  it("Close renders a <button>", () => {
-    // Arrange / Act
-    render(
-      <Drawer.Root defaultOpen>
-        <Drawer.Content>
-          <Drawer.Close>Done</Drawer.Close>
-        </Drawer.Content>
-      </Drawer.Root>,
-    );
-
-    // Assert
-    expect(screen.getByRole("button", { name: "Done" })).toHaveAttribute(
-      "type",
-      "button",
-    );
-  });
-
-  it("forwards asChild on the Trigger to the consumer element", () => {
-    // Arrange / Act
-    render(
-      <Drawer.Root>
-        <Drawer.Trigger asChild>
-          <a href="/cart">Cart</a>
-        </Drawer.Trigger>
-      </Drawer.Root>,
-    );
-
-    // Assert
-    const link = screen.getByRole("link", { name: "Cart" });
-    expect(link).toHaveAttribute("aria-haspopup", "dialog");
-  });
-});

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

@@ -1,69 +0,0 @@
-import "./dialog-polyfill";
-
-import { render, screen } from "@testing-library/react";
-
-import { Drawer } from "../Drawer";
-import type { DrawerSide } from "../types";
-
-const SIDES: DrawerSide[] = ["top", "right", "bottom", "left"];
-
-describe("Drawer.Content — side axis", () => {
-  it("defaults data-side to 'right' when side is omitted", () => {
-    // Arrange / Act
-    render(
-      <Drawer.Root defaultOpen>
-        <Drawer.Content data-testid="drawer">body</Drawer.Content>
-      </Drawer.Root>,
-    );
-
-    // Assert
-    expect(screen.getByTestId("drawer")).toHaveAttribute("data-side", "right");
-  });
-
-  it.each(SIDES)(
-    "emits data-side='%s' on the dialog",
-    (side) => {
-      // Arrange / Act
-      render(
-        <Drawer.Root defaultOpen>
-          <Drawer.Content data-testid="drawer" side={side}>
-            body
-          </Drawer.Content>
-        </Drawer.Root>,
-      );
-
-      // Assert
-      expect(screen.getByTestId("drawer")).toHaveAttribute("data-side", side);
-    },
-  );
-
-  it("does not leak the `side` prop as a raw attribute on the dialog", () => {
-    // Arrange / Act
-    render(
-      <Drawer.Root defaultOpen>
-        <Drawer.Content data-testid="drawer" side="left">
-          body
-        </Drawer.Content>
-      </Drawer.Root>,
-    );
-
-    // Assert
-    expect(screen.getByTestId("drawer")).not.toHaveAttribute("side");
-  });
-
-  it("keeps data-state alongside data-side", () => {
-    // Arrange / Act
-    render(
-      <Drawer.Root defaultOpen>
-        <Drawer.Content data-testid="drawer" side="bottom">
-          body
-        </Drawer.Content>
-      </Drawer.Root>,
-    );
-
-    // Assert
-    const dialog = screen.getByTestId("drawer");
-    expect(dialog).toHaveAttribute("data-side", "bottom");
-    expect(dialog).toHaveAttribute("data-state", "open");
-  });
-});

package/src/Drawer/__tests__/dialog-polyfill.ts

@@ -1,39 +0,0 @@
-/**
- * Minimal scoped polyfill for the native <dialog> element in jsdom 29.
- *
- * jsdom does not implement showModal() / close() on HTMLDialogElement, so
- * integration tests that render Drawer.Content (a native <dialog>, via
- * Modal.Content) need a shim that:
- *  - toggles the `open` attribute (which is what .open reflects)
- *  - dispatches the native `close` event on close()
- *
- * The Drawer suite drives open/close through the trigger, the Close button,
- * and the imperative API — the Esc/`cancel` and click-outside paths are
- * Modal's behaviour and are covered by Modal's own suite, so this shim stays
- * minimal. Mirrors Modal's scoped polyfill — imported explicitly where needed
- * rather than installed globally, so other components keep exercising the real
- * DOM.
- */
-
-type DialogProto = HTMLDialogElement & { returnValue: string };
-
-const proto = HTMLDialogElement.prototype as DialogProto;
-
-if (typeof proto.showModal !== "function") {
-  proto.showModal = function showModal(this: HTMLDialogElement) {
-    this.setAttribute("open", "");
-  };
-}
-
-if (typeof proto.close !== "function") {
-  proto.close = function close(this: HTMLDialogElement, returnValue?: string) {
-    if (!this.hasAttribute("open")) return;
-    this.removeAttribute("open");
-    if (returnValue !== undefined) {
-      (this as DialogProto).returnValue = String(returnValue);
-    }
-    this.dispatchEvent(new Event("close"));
-  };
-}
-
-export {};

package/src/Drawer/index.ts

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

package/src/Drawer/types.ts

@@ -1,66 +0,0 @@
-import type { Ref } from "react";
-
-import type {
-  ModalCloseProps,
-  ModalContentProps,
-  ModalDescriptionProps,
-  ModalImperativeApi,
-  ModalOverlayProps,
-  ModalPortalProps,
-  ModalRootProps,
-  ModalTitleProps,
-  ModalTriggerProps,
-} from "../Modal/types";
-
-/**
- * Which edge the drawer slides in from.
- *
- * - `"top"` / `"bottom"` — a horizontal sheet spanning the viewport width.
- * - `"left"` / `"right"` — a vertical panel spanning the viewport height.
- */
-export type DrawerSide = "top" | "right" | "bottom" | "left";
-
-/**
- * Imperative handle exposed on `Drawer.Root`'s `ref`, letting callers open
- * and close the drawer programmatically. Behaviour is inherited from
- * {@link ModalImperativeApi | Modal} — a drawer is a Modal that slides from an edge.
- */
-export type DrawerImperativeApi = ModalImperativeApi;
-
-/** Props for `Drawer.Root`, in either the controlled or uncontrolled mode. */
-export type DrawerRootProps = ModalRootProps;
-
-/** Props for `Drawer.Trigger` — a `<button>` that opens the drawer. */
-export type DrawerTriggerProps = ModalTriggerProps;
-
-/** Props for `Drawer.Portal` — renders its children into `container`. */
-export type DrawerPortalProps = ModalPortalProps;
-
-/** Props for `Drawer.Overlay` — the click-outside backdrop. */
-export type DrawerOverlayProps = ModalOverlayProps;
-
-/** Props for `Drawer.Title` — supplies the drawer's accessible name. */
-export type DrawerTitleProps = ModalTitleProps;
-
-/** Props for `Drawer.Description` — supplies the drawer's accessible description. */
-export type DrawerDescriptionProps = ModalDescriptionProps;
-
-/** Props for `Drawer.Close` — a `<button>` that closes the drawer. */
-export type DrawerCloseProps = ModalCloseProps;
-
-/**
- * Props for `Drawer.Content` — the native `<dialog>` props plus the
- * drawer-specific {@link DrawerContentProps.side | `side`} axis.
- */
-export type DrawerContentProps = ModalContentProps & {
-  /** Ref to the underlying native `<dialog>` element. */
-  ref?: Ref<HTMLDialogElement>;
-  /**
-   * Which edge the drawer slides in from. Emitted verbatim as `data-side`
-   * on the `<dialog>`, which the styled layer keys off to position and
-   * animate the panel against that edge. Purely presentational — it does
-   * not change any behaviour, focus, or ARIA.
-   * @default "right"
-   */
-  side?: DrawerSide;
-};