@primitiv-ui/react 0.1.0

package/src/Button/README.md

@@ -0,0 +1,112 @@
+# Button
+
+A headless, accessible `<button>` element. Zero styles ship — apply whatever
+design system you use.
+
+```tsx
+import { Button } from "@primitiv-ui/react";
+
+<Button onClick={handleSave}>Save</Button>
+```
+
+## Props
+
+| Prop       | Type                                   | Default    | Notes                                                            |
+| ---------- | -------------------------------------- | ---------- | ---------------------------------------------------------------- |
+| `type`     | `"button"` \| `"submit"` \| `"reset"` | `"button"` | Override to `"submit"` inside forms                              |
+| `disabled` | `boolean`                              | —          | Native `disabled` + `data-disabled=""` styling hook             |
+| `asChild`  | `boolean`                              | `false`    | Delegate rendering to the child element via Slot                 |
+| `ref`      | `Ref<HTMLButtonElement>`               | —          | Forwarded to the underlying button element                       |
+| `children` | `ReactNode`                            | —          | Text, icons, or any React nodes                                  |
+| `...rest`  | `ComponentProps<"button">`             | —          | All other `<button>` props (`aria-*`, `data-*`, event handlers) |
+
+## Default type
+
+`type="button"` is the default to prevent accidental form submission when a
+`<Button>` is nested inside a `<form>`. Override explicitly when you need
+form semantics:
+
+```tsx
+<form onSubmit={handleSubmit}>
+  <Button type="submit">Send</Button>
+  <Button type="reset">Clear</Button>
+</form>
+```
+
+## Disabled
+
+Passing `disabled` forwards the native `disabled` attribute (removing the
+button from the tab order and suppressing clicks) **and** sets
+`data-disabled=""` so CSS can target `[data-disabled]` without relying on
+the `:disabled` pseudo-class:
+
+```tsx
+<Button disabled>Save</Button>
+```
+
+```css
+button[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+```
+
+## Icon-only buttons
+
+For buttons with no visible text, supply `aria-label` or `aria-labelledby`
+so screen readers can announce the button's purpose. Mark decorative icons
+`aria-hidden="true"`:
+
+```tsx
+<Button aria-label="Close dialog">
+  <svg aria-hidden="true" viewBox="0 0 24 24" focusable="false">
+    <path d="M6 18L18 6M6 6l12 12" />
+  </svg>
+</Button>
+```
+
+## Text + icon
+
+When combining text and an icon, mark the icon as decorative so it is not
+included in the accessible name:
+
+```tsx
+<Button>
+  <StarIcon aria-hidden="true" />
+  Favourite
+</Button>
+```
+
+## `asChild` composition
+
+Pass `asChild` to render any consumer-supplied element instead of `<button>`.
+All props (`aria-*`, `data-*`, event handlers, `ref`) are merged onto the
+child via the `Slot` utility — event handlers compose (child runs first),
+`style` is shallow-merged, `className` is concatenated.
+
+`type="button"` is **not** forwarded when `asChild` is set — the child
+element owns its own type semantics.
+
+```tsx
+// Render a router link styled as a button
+<Button asChild>
+  <a href="/dashboard">Dashboard</a>
+</Button>
+```
+
+## Ref forwarding
+
+```tsx
+const ref = useRef<HTMLButtonElement>(null);
+<Button ref={ref}>Save</Button>
+```
+
+## Keyboard interaction
+
+Keyboard activation is handled natively by the underlying `<button>` element.
+
+| Key     | Behaviour                 |
+| ------- | ------------------------- |
+| `Space` | Activates the button      |
+| `Enter` | Activates the button      |
+| `Tab`   | Moves focus to the button |

package/src/Button/__tests__/Button.asChild.test.tsx

@@ -0,0 +1,91 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Button } from "../Button";
+
+describe("Button asChild composition", () => {
+  it("renders the consumer's element instead of <button>", () => {
+    // Arrange & Act
+    render(
+      <Button asChild>
+        <a href="/dashboard">Dashboard</a>
+      </Button>,
+    );
+
+    // Assert
+    expect(screen.getByRole("link", { name: "Dashboard" }).tagName).toBe("A");
+  });
+
+  it("does not render a <button> when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <Button asChild>
+        <a href="/dashboard">Dashboard</a>
+      </Button>,
+    );
+
+    // Assert
+    expect(screen.queryByRole("button")).not.toBeInTheDocument();
+  });
+
+  it("merges aria-* props onto the child element", () => {
+    // Arrange & Act
+    render(
+      <Button asChild aria-label="Go to dashboard">
+        <a href="/dashboard">Dashboard</a>
+      </Button>,
+    );
+
+    // Assert
+    expect(
+      screen.getByRole("link", { name: "Go to dashboard" }),
+    ).toHaveAttribute("aria-label", "Go to dashboard");
+  });
+
+  it("does not forward type to the child element", () => {
+    // Arrange & Act
+    render(
+      <Button asChild>
+        <a href="/dashboard">Dashboard</a>
+      </Button>,
+    );
+    const link = screen.getByRole("link", { name: "Dashboard" });
+
+    // Assert
+    expect(link).not.toHaveAttribute("type");
+  });
+
+  it("composes onClick — child handler fires first, then Button's", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const order: string[] = [];
+    const childClick = () => order.push("child");
+    const buttonClick = () => order.push("button");
+
+    render(
+      <Button asChild onClick={buttonClick}>
+        <a href="#" onClick={childClick}>
+          Dashboard
+        </a>
+      </Button>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("link", { name: "Dashboard" }));
+
+    // Assert
+    expect(order).toEqual(["child", "button"]);
+  });
+
+  it("sets data-disabled on the child element when disabled", () => {
+    // Arrange & Act
+    render(
+      <Button asChild disabled>
+        <span>Locked</span>
+      </Button>,
+    );
+
+    // Assert
+    expect(screen.getByText("Locked")).toHaveAttribute("data-disabled", "");
+  });
+});

package/src/Button/__tests__/Button.basic-rendering.test.tsx

@@ -0,0 +1,126 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+
+import { Button } from "../Button";
+
+describe("Button basic rendering", () => {
+  it("renders a <button> element", () => {
+    // Arrange & Act
+    render(<Button>Save</Button>);
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Save" }).tagName).toBe("BUTTON");
+  });
+
+  it('defaults to type="button" to prevent accidental form submission', () => {
+    // Arrange & Act
+    render(<Button>Save</Button>);
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Save" })).toHaveAttribute(
+      "type",
+      "button",
+    );
+  });
+
+  it('allows type="submit" to be set by the consumer', () => {
+    // Arrange & Act
+    render(<Button type="submit">Send</Button>);
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Send" })).toHaveAttribute(
+      "type",
+      "submit",
+    );
+  });
+
+  it('allows type="reset" to be set by the consumer', () => {
+    // Arrange & Act
+    render(<Button type="reset">Clear</Button>);
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Clear" })).toHaveAttribute(
+      "type",
+      "reset",
+    );
+  });
+
+  it("renders arbitrary children", () => {
+    // Arrange & Act
+    render(
+      <Button>
+        <span data-testid="icon" aria-hidden="true">★</span>
+        Save
+      </Button>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("icon")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /Save/ })).toBeInTheDocument();
+  });
+
+  it("forwards a ref to the underlying button element (object ref)", () => {
+    // Arrange
+    const ref = createRef<HTMLButtonElement>();
+
+    // Act
+    render(<Button ref={ref}>Save</Button>);
+
+    // Assert
+    expect(ref.current).toBe(screen.getByRole("button", { name: "Save" }));
+  });
+
+  it("forwards a ref to the underlying button element (function ref)", () => {
+    // Arrange
+    const received: (HTMLButtonElement | null)[] = [];
+    const functionRef = (node: HTMLButtonElement | null) => {
+      received.push(node);
+    };
+
+    // Act
+    render(<Button ref={functionRef}>Save</Button>);
+
+    // Assert
+    expect(received).toContain(screen.getByRole("button", { name: "Save" }));
+  });
+
+  it("passes through aria-* attributes", () => {
+    // Arrange & Act
+    render(<Button aria-label="Close dialog" aria-pressed={false}>✕</Button>);
+    const button = screen.getByRole("button", { name: "Close dialog" });
+
+    // Assert
+    expect(button).toHaveAttribute("aria-pressed", "false");
+  });
+
+  it("passes through data-* attributes", () => {
+    // Arrange & Act
+    render(<Button data-testid="submit-btn">Save</Button>);
+
+    // Assert
+    expect(screen.getByTestId("submit-btn")).toBeInTheDocument();
+  });
+
+  it("passes through className", () => {
+    // Arrange & Act
+    render(<Button className="btn-primary">Save</Button>);
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Save" })).toHaveAttribute(
+      "class",
+      "btn-primary",
+    );
+  });
+
+  it("passes through event handlers (onClick)", () => {
+    // Arrange
+    const onClick = vi.fn();
+    render(<Button onClick={onClick}>Save</Button>);
+
+    // Act
+    screen.getByRole("button", { name: "Save" }).click();
+
+    // Assert
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});

package/src/Button/__tests__/Button.contract.test.tsx

@@ -0,0 +1,72 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { render, screen } from "@testing-library/react";
+
+import { Button } from "../Button";
+
+/**
+ * Auto-verification of the Button styling contract (RFC 0004 §3.4 / D15). The
+ * `data-*` half of `registry/components/button/contract.json` is *derived from and
+ * asserted against the rendered headless component* so it can never drift from
+ * what the component actually emits. The authored half (root class, modifiers,
+ * custom properties) is checked for self-consistency only — it is a styling
+ * convention the headless layer does not emit.
+ */
+const contractPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "../../../../../registry/components/button/contract.json",
+);
+
+const contract = JSON.parse(readFileSync(contractPath, "utf8"));
+
+/** Every `data-*` attribute name present on an element. */
+function dataAttributeNames(element: Element): string[] {
+  return [...element.attributes]
+    .map((attribute) => attribute.name)
+    .filter((name) => name.startsWith("data-"))
+    .sort();
+}
+
+describe("Button styling contract", () => {
+  const autoAttributes = contract.dataAttributes.filter(
+    (attribute: { source: string }) => attribute.source === "auto",
+  );
+
+  it("declares every data-* attribute as auto-verified against the component", () => {
+    // The Button has no authored data-* surface; the whole contract is derived.
+    expect(autoAttributes).toHaveLength(contract.dataAttributes.length);
+  });
+
+  it("emits exactly the contracted data-* attributes across its states", () => {
+    const { rerender } = render(<Button disabled>Save</Button>);
+    const emitted = new Set(dataAttributeNames(screen.getByRole("button")));
+
+    rerender(<Button>Save</Button>);
+    for (const name of dataAttributeNames(screen.getByRole("button"))) {
+      emitted.add(name);
+    }
+
+    const contracted = autoAttributes
+      .map((attribute: { name: string }) => attribute.name)
+      .sort();
+    expect([...emitted].sort()).toEqual(contracted);
+  });
+
+  it("emits data-disabled exactly as the contract documents it", () => {
+    const entry = autoAttributes.find(
+      (attribute: { name: string }) => attribute.name === "data-disabled",
+    );
+
+    render(<Button disabled>Save</Button>);
+    // Present with the documented value when the documented condition holds…
+    expect(screen.getByRole("button")).toHaveAttribute(entry.name, entry.value);
+  });
+
+  it("omits data-disabled when the documented condition does not hold", () => {
+    render(<Button>Save</Button>);
+
+    expect(screen.getByRole("button")).not.toHaveAttribute("data-disabled");
+  });
+});

package/src/Button/__tests__/Button.disabled.test.tsx

@@ -0,0 +1,52 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Button } from "../Button";
+
+describe("Button disabled state", () => {
+  it("sets the native disabled attribute", () => {
+    // Arrange & Act
+    render(<Button disabled>Save</Button>);
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Save" })).toBeDisabled();
+  });
+
+  it('sets data-disabled="" as a CSS styling hook', () => {
+    // Arrange & Act
+    render(<Button disabled>Save</Button>);
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Save" })).toHaveAttribute(
+      "data-disabled",
+      "",
+    );
+  });
+
+  it("does not set data-disabled when not disabled", () => {
+    // Arrange & Act
+    render(<Button>Save</Button>);
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Save" })).not.toHaveAttribute(
+      "data-disabled",
+    );
+  });
+
+  it("does not fire onClick when disabled", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <Button disabled onClick={onClick}>
+        Save
+      </Button>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("button", { name: "Save" }));
+
+    // Assert
+    expect(onClick).not.toHaveBeenCalled();
+  });
+});

package/src/Button/__tests__/Button.icon-usage.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from "@testing-library/react";
+
+import { Button } from "../Button";
+
+describe("Button icon usage", () => {
+  it("renders an icon-only button with aria-label for accessibility", () => {
+    // Arrange & Act
+    render(
+      <Button aria-label="Close dialog">
+        <span aria-hidden="true">✕</span>
+      </Button>,
+    );
+
+    // Assert
+    expect(
+      screen.getByRole("button", { name: "Close dialog" }),
+    ).toBeInTheDocument();
+  });
+
+  it("renders an icon alongside text — icon carries aria-hidden", () => {
+    // Arrange & Act
+    render(
+      <Button>
+        <span aria-hidden="true" data-testid="icon">★</span>
+        Save
+      </Button>,
+    );
+    const button = screen.getByRole("button", { name: /Save/ });
+    const icon = screen.getByTestId("icon");
+
+    // Assert
+    expect(button).toBeInTheDocument();
+    expect(icon).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("renders an SVG icon — consumer marks it aria-hidden", () => {
+    // Arrange & Act
+    render(
+      <Button aria-label="Submit form">
+        <svg
+          aria-hidden="true"
+          data-testid="svg-icon"
+          viewBox="0 0 24 24"
+          focusable="false"
+        >
+          <path d="M5 12l5 5L20 7" />
+        </svg>
+      </Button>,
+    );
+    const button = screen.getByRole("button", { name: "Submit form" });
+    const svg = screen.getByTestId("svg-icon");
+
+    // Assert
+    expect(button).toBeInTheDocument();
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+  });
+});

package/src/Button/__tests__/Button.keyboard-interaction.test.tsx

@@ -0,0 +1,70 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Button } from "../Button";
+
+describe("Button keyboard interaction", () => {
+  it("fires onClick when activated with Enter", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(<Button onClick={onClick}>Save</Button>);
+    screen.getByRole("button", { name: "Save" }).focus();
+
+    // Act
+    await user.keyboard("{Enter}");
+
+    // Assert
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("fires onClick when activated with Space", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(<Button onClick={onClick}>Save</Button>);
+    screen.getByRole("button", { name: "Save" }).focus();
+
+    // Act
+    await user.keyboard(" ");
+
+    // Assert
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("is reachable via Tab", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <>
+        <input aria-label="Name" />
+        <Button>Save</Button>
+      </>,
+    );
+    screen.getByRole("textbox", { name: "Name" }).focus();
+
+    // Act
+    await user.tab();
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Save" })).toHaveFocus();
+  });
+
+  it("is not reachable via Tab when disabled", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <>
+        <input aria-label="Name" />
+        <Button disabled>Save</Button>
+      </>,
+    );
+    screen.getByRole("textbox", { name: "Name" }).focus();
+
+    // Act
+    await user.tab();
+
+    // Assert
+    expect(screen.getByRole("button", { name: "Save" })).not.toHaveFocus();
+  });
+});

package/src/Button/index.ts

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

package/src/Button/types.ts

@@ -0,0 +1,8 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+export type ButtonProps = Omit<ComponentProps<"button">, "type"> & {
+  type?: "button" | "submit" | "reset";
+  asChild?: boolean;
+  ref?: Ref<HTMLButtonElement>;
+  children?: ReactNode;
+};