@primitiv-ui/react 0.1.28 → 0.1.29

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

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

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

@@ -0,0 +1,39 @@
+/**
+ * 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

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

package/src/Drawer/types.ts

@@ -0,0 +1,66 @@
+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;
+};

package/src/Dropdown/Dropdown.tsx

@@ -121,6 +121,8 @@ DropdownRoot.displayName = "DropdownRoot";
  * component). All ARIA attributes and event handlers are merged onto the
  * child following the {@link Slot} composition rules.
  *
+ * @extends HTMLButtonElement
+ *
  * @example With an anchor via `asChild`
  * ```tsx
  * <Dropdown.Trigger asChild>
@@ -180,6 +182,17 @@ DropdownTrigger.displayName = "DropdownTrigger";
  * so `ArrowDown` past a {@link DropdownSubTrigger | `Dropdown.SubTrigger`}
  * lands on the next sibling item in the parent rather than getting
  * stuck on a non-focusable item inside a closed sub-popover.
+ *
+ * @extends HTMLMenuElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Content>
+ *   <Dropdown.Item onSelect={rename}>Rename</Dropdown.Item>
+ *   <Dropdown.Separator />
+ *   <Dropdown.Item onSelect={remove}>Delete</Dropdown.Item>
+ * </Dropdown.Content>
+ * ```
  */
 export function DropdownContent({
   children,
@@ -218,6 +231,18 @@ DropdownContent.displayName = "DropdownContent";
  *
  * Disabled items receive `aria-disabled="true"` and are skipped by arrow
  * navigation, typeahead, and activation handlers.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example Keep the menu open after selecting
+ * ```tsx
+ * <Dropdown.Item onSelect={(event) => {
+ *   copyToClipboard();
+ *   event.preventDefault();
+ * }}>
+ *   Copy link
+ * </Dropdown.Item>
+ * ```
  */
 export function DropdownItem({
   children,
@@ -248,6 +273,15 @@ DropdownItem.displayName = "DropdownItem";
  * A visual separator between groups of items. Renders a `<li role="separator">`
  * by default; pass `asChild` to render any element with separator semantics.
  * Non-interactive — skipped by focus, arrow navigation, and typeahead.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Item>Cut</Dropdown.Item>
+ * <Dropdown.Separator />
+ * <Dropdown.Item>Paste</Dropdown.Item>
+ * ```
  */
 export function DropdownSeparator({
   asChild = false,
@@ -275,6 +309,17 @@ DropdownSeparator.displayName = "DropdownSeparator";
  * wired automatically via `aria-labelledby`. Nest a `Dropdown.Label` as the
  * first child to provide the accessible name; screen readers will announce
  * the group when arrowing into it.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Group>
+ *   <Dropdown.Label>Sort by</Dropdown.Label>
+ *   <Dropdown.Item>Name</Dropdown.Item>
+ *   <Dropdown.Item>Date</Dropdown.Item>
+ * </Dropdown.Group>
+ * ```
  */
 export function DropdownGroup({
   children,
@@ -307,6 +352,16 @@ DropdownGroup.displayName = "DropdownGroup";
  *
  * Renders a `<li>` by default; pass `asChild` to render any element. A
  * caller-supplied `id` takes precedence over the auto-generated one.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Group>
+ *   <Dropdown.Label>Actions</Dropdown.Label>
+ *   <Dropdown.Item>Duplicate</Dropdown.Item>
+ * </Dropdown.Group>
+ * ```
  */
 export function DropdownLabel({
   id,
@@ -350,6 +405,18 @@ DropdownLabel.displayName = "DropdownLabel";
  * context and exposes `data-state` for styling.
  *
  * Disabled items receive `aria-disabled="true"` and no-op on activation.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example Controlled checkbox item
+ * ```tsx
+ * <Dropdown.CheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
+ *   <Dropdown.ItemIndicator>
+ *     <CheckIcon />
+ *   </Dropdown.ItemIndicator>
+ *   Show grid
+ * </Dropdown.CheckboxItem>
+ * ```
  */
 export function DropdownCheckboxItem({
   children,
@@ -425,6 +492,22 @@ DropdownCheckboxItem.displayName = "DropdownCheckboxItem";
  * - **Uncontrolled** — pass `defaultValue` (or omit for no initial selection).
  *   Optional `onValueChange` observes selections.
  * - **Controlled** — pass `value` *and* `onValueChange` together.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.RadioGroup value={sort} onValueChange={setSort}>
+ *   <Dropdown.RadioItem value="name">
+ *     <Dropdown.ItemIndicator>•</Dropdown.ItemIndicator>
+ *     Name
+ *   </Dropdown.RadioItem>
+ *   <Dropdown.RadioItem value="date">
+ *     <Dropdown.ItemIndicator>•</Dropdown.ItemIndicator>
+ *     Date
+ *   </Dropdown.RadioItem>
+ * </Dropdown.RadioGroup>
+ * ```
  */
 export function DropdownRadioGroup({
   defaultValue,
@@ -476,6 +559,16 @@ DropdownRadioGroup.displayName = "DropdownRadioGroup";
  * and exposes `data-state` for styling.
  *
  * Disabled items receive `aria-disabled="true"` and no-op on activation.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.RadioItem value="compact">
+ *   <Dropdown.ItemIndicator>•</Dropdown.ItemIndicator>
+ *   Compact
+ * </Dropdown.RadioItem>
+ * ```
  */
 export function DropdownRadioItem({
   children,
@@ -555,6 +648,8 @@ DropdownRadioItem.displayName = "DropdownRadioItem";
  * the DOM node mounted in both states, which is handy when animating the
  * indicator in and out via CSS transitions or a React animation library.
  *
+ * @extends HTMLSpanElement
+ *
  * @example
  * ```tsx
  * <Dropdown.CheckboxItem checked={showBookmarks} onCheckedChange={setShowBookmarks}>
@@ -683,6 +778,18 @@ DropdownSub.displayName = "DropdownSub";
  *
  * Disabled triggers receive `aria-disabled="true"` and ignore both click
  * and the open arrow key.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Sub>
+ *   <Dropdown.SubTrigger>Share</Dropdown.SubTrigger>
+ *   <Dropdown.SubContent>
+ *     <Dropdown.Item>Email link</Dropdown.Item>
+ *   </Dropdown.SubContent>
+ * </Dropdown.Sub>
+ * ```
  */
 export function DropdownSubTrigger({
   children,
@@ -749,6 +856,16 @@ DropdownSubTrigger.displayName = "DropdownSubTrigger";
  * `ArrowLeft` in `"ltr"`, `ArrowRight` in `"rtl"`. All other keys bubble
  * to the parent {@link DropdownContent | `Dropdown.Content`} so arrow
  * navigation and typeahead apply to the submenu's items.
+ *
+ * @extends HTMLMenuElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.SubContent>
+ *   <Dropdown.Item>Project A</Dropdown.Item>
+ *   <Dropdown.Item>Project B</Dropdown.Item>
+ * </Dropdown.SubContent>
+ * ```
  */
 export function DropdownSubContent({
   children,