@primitiv-ui/react 0.1.0

package/src/Breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,234 @@
+import { Slot } from "../Slot";
+
+import {
+  BreadcrumbItemProps,
+  BreadcrumbLinkProps,
+  BreadcrumbListProps,
+  BreadcrumbPageProps,
+  BreadcrumbRootProps,
+  BreadcrumbSeparatorProps,
+} from "./types";
+
+/**
+ * The root of a Breadcrumb — a `<nav>` landmark that wraps the breadcrumb
+ * trail.
+ *
+ * The `<nav>` defaults to `aria-label="Breadcrumb"` so assistive technology
+ * announces it as the breadcrumb navigation landmark. Override `aria-label`
+ * if your product uses different terminology.
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumb.Root>
+ *   <Breadcrumb.List>…</Breadcrumb.List>
+ * </Breadcrumb.Root>
+ * ```
+ */
+function BreadcrumbRoot({ children, ...rest }: BreadcrumbRootProps) {
+  return (
+    <nav aria-label="Breadcrumb" {...rest}>
+      {children}
+    </nav>
+  );
+}
+
+BreadcrumbRoot.displayName = "BreadcrumbRoot";
+
+/**
+ * The ordered list of breadcrumb entries — renders an `<ol>`.
+ *
+ * An ordered list is the correct semantic: breadcrumb entries have a
+ * meaningful sequence from the site root to the current page. Contains
+ * {@link BreadcrumbItem | `Breadcrumb.Item`}s interleaved with
+ * {@link BreadcrumbSeparator | `Breadcrumb.Separator`}s.
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumb.List>
+ *   <Breadcrumb.Item>…</Breadcrumb.Item>
+ *   <Breadcrumb.Separator />
+ *   <Breadcrumb.Item>…</Breadcrumb.Item>
+ * </Breadcrumb.List>
+ * ```
+ */
+function BreadcrumbList({ children, ...rest }: BreadcrumbListProps) {
+  return <ol {...rest}>{children}</ol>;
+}
+
+BreadcrumbList.displayName = "BreadcrumbList";
+
+/**
+ * A single entry in the breadcrumb trail — renders an `<li>`.
+ *
+ * Wraps either a {@link BreadcrumbLink | `Breadcrumb.Link`} (an ancestor
+ * page) or a {@link BreadcrumbPage | `Breadcrumb.Page`} (the current page).
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumb.Item>
+ *   <Breadcrumb.Link href="/library">Library</Breadcrumb.Link>
+ * </Breadcrumb.Item>
+ * ```
+ */
+function BreadcrumbItem({ children, ...rest }: BreadcrumbItemProps) {
+  return <li {...rest}>{children}</li>;
+}
+
+BreadcrumbItem.displayName = "BreadcrumbItem";
+
+/**
+ * A link to an ancestor page — renders an `<a>`.
+ *
+ * Use for every entry except the current page. Pass `href` (and any other
+ * anchor attributes) directly.
+ *
+ * **`asChild` prop.** Pass `asChild` to render a consumer-supplied element —
+ * typically a routing library's `<Link>` — with the breadcrumb link's props
+ * merged in. The native `<a>` is dropped.
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumb.Link href="/library">Library</Breadcrumb.Link>
+ * ```
+ *
+ * @example With a router link
+ * ```tsx
+ * <Breadcrumb.Link asChild>
+ *   <RouterLink to="/library">Library</RouterLink>
+ * </Breadcrumb.Link>
+ * ```
+ */
+function BreadcrumbLink({
+  children,
+  asChild = false,
+  ...rest
+}: BreadcrumbLinkProps) {
+  if (asChild) {
+    return <Slot {...rest}>{children}</Slot>;
+  }
+  return <a {...rest}>{children}</a>;
+}
+
+BreadcrumbLink.displayName = "BreadcrumbLink";
+
+/**
+ * The current page in the trail — renders a `<span aria-current="page">`.
+ *
+ * The last entry of a breadcrumb is the page the user is on, so it is not a
+ * link. `aria-current="page"` tells assistive technology this entry
+ * represents the current location.
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumb.Item>
+ *   <Breadcrumb.Page>Current article</Breadcrumb.Page>
+ * </Breadcrumb.Item>
+ * ```
+ */
+function BreadcrumbPage({ children, ...rest }: BreadcrumbPageProps) {
+  return (
+    <span aria-current="page" {...rest}>
+      {children}
+    </span>
+  );
+}
+
+BreadcrumbPage.displayName = "BreadcrumbPage";
+
+/**
+ * The visual divider between two breadcrumb entries — renders an
+ * `<li role="presentation" aria-hidden="true">`.
+ *
+ * The separator sits inside the `<ol>` as a sibling of the
+ * {@link BreadcrumbItem | `Breadcrumb.Item`}s, but `role="presentation"`
+ * removes it from the list semantics and `aria-hidden` hides it from the
+ * accessibility tree — it is purely decorative.
+ *
+ * Defaults to a `"/"` glyph; pass `children` to use a custom separator (an
+ * icon, a chevron, etc.).
+ *
+ * @example Default separator
+ * ```tsx
+ * <Breadcrumb.Separator />
+ * ```
+ *
+ * @example Custom separator
+ * ```tsx
+ * <Breadcrumb.Separator><ChevronRight /></Breadcrumb.Separator>
+ * ```
+ */
+function BreadcrumbSeparator({
+  children = "/",
+  ...rest
+}: BreadcrumbSeparatorProps) {
+  return (
+    <li role="presentation" aria-hidden="true" {...rest}>
+      {children}
+    </li>
+  );
+}
+
+BreadcrumbSeparator.displayName = "BreadcrumbSeparator";
+
+type TBreadcrumbCompound = typeof BreadcrumbRoot & {
+  Root: typeof BreadcrumbRoot;
+  List: typeof BreadcrumbList;
+  Item: typeof BreadcrumbItem;
+  Link: typeof BreadcrumbLink;
+  Page: typeof BreadcrumbPage;
+  Separator: typeof BreadcrumbSeparator;
+};
+
+/**
+ * Headless, accessible **Breadcrumb** — a compound component implementing the
+ * [WAI-ARIA breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/):
+ * a `<nav>` landmark wrapping an ordered list of links to ancestor pages,
+ * ending with the current page. Stateless — purely structural. Zero styles
+ * ship.
+ *
+ * `Breadcrumb` is both callable (an alias of
+ * {@link BreadcrumbRoot | `Breadcrumb.Root`}) and carries its sub-components
+ * as static properties.
+ *
+ * - {@link BreadcrumbRoot | `Breadcrumb.Root`} — `<nav aria-label="Breadcrumb">`.
+ * - {@link BreadcrumbList | `Breadcrumb.List`} — `<ol>`, the ordered trail.
+ * - {@link BreadcrumbItem | `Breadcrumb.Item`} — `<li>`, one entry.
+ * - {@link BreadcrumbLink | `Breadcrumb.Link`} — `<a>`, an ancestor-page link.
+ * - {@link BreadcrumbPage | `Breadcrumb.Page`} — `<span aria-current="page">`, the current page.
+ * - {@link BreadcrumbSeparator | `Breadcrumb.Separator`} — decorative `<li>` divider.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Breadcrumb } from "@primitiv-ui/react";
+ *
+ * <Breadcrumb.Root>
+ *   <Breadcrumb.List>
+ *     <Breadcrumb.Item>
+ *       <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
+ *     </Breadcrumb.Item>
+ *     <Breadcrumb.Separator />
+ *     <Breadcrumb.Item>
+ *       <Breadcrumb.Link href="/library">Library</Breadcrumb.Link>
+ *     </Breadcrumb.Item>
+ *     <Breadcrumb.Separator />
+ *     <Breadcrumb.Item>
+ *       <Breadcrumb.Page>Current article</Breadcrumb.Page>
+ *     </Breadcrumb.Item>
+ *   </Breadcrumb.List>
+ * </Breadcrumb.Root>
+ * ```
+ *
+ * @see {@link BreadcrumbSeparator} for customising the divider glyph.
+ */
+const BreadcrumbCompound: TBreadcrumbCompound = Object.assign(BreadcrumbRoot, {
+  Root: BreadcrumbRoot,
+  List: BreadcrumbList,
+  Item: BreadcrumbItem,
+  Link: BreadcrumbLink,
+  Page: BreadcrumbPage,
+  Separator: BreadcrumbSeparator,
+});
+
+BreadcrumbCompound.displayName = "Breadcrumb";
+
+export { BreadcrumbCompound as Breadcrumb };

package/src/Breadcrumb/README.md

@@ -0,0 +1,111 @@
+# Breadcrumb
+
+Headless, accessible **Breadcrumb** — a compound component implementing the
+[WAI-ARIA breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/):
+a `<nav>` landmark wrapping an ordered list of links to ancestor pages, ending
+with the current page. Stateless — purely structural. Zero styles ship.
+
+```tsx
+import { Breadcrumb } from "@primitiv-ui/react";
+
+<Breadcrumb.Root>
+  <Breadcrumb.List>
+    <Breadcrumb.Item>
+      <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
+    </Breadcrumb.Item>
+    <Breadcrumb.Separator />
+    <Breadcrumb.Item>
+      <Breadcrumb.Link href="/library">Library</Breadcrumb.Link>
+    </Breadcrumb.Item>
+    <Breadcrumb.Separator />
+    <Breadcrumb.Item>
+      <Breadcrumb.Page>Current article</Breadcrumb.Page>
+    </Breadcrumb.Item>
+  </Breadcrumb.List>
+</Breadcrumb.Root>;
+```
+
+## Sub-components
+
+| Export | Element | ARIA hooks | `asChild` |
+|--------|---------|------------|-----------|
+| `Breadcrumb.Root` | `<nav>` | `aria-label="Breadcrumb"` (overridable) | — |
+| `Breadcrumb.List` | `<ol>` | — | — |
+| `Breadcrumb.Item` | `<li>` | — | — |
+| `Breadcrumb.Link` | `<a>` | — | yes |
+| `Breadcrumb.Page` | `<span>` | `aria-current="page"` | — |
+| `Breadcrumb.Separator` | `<li>` | `role="presentation"`, `aria-hidden="true"` | — |
+
+Every sub-component passes all of its element's native attributes straight
+through to the DOM.
+
+## Structure
+
+A breadcrumb is an **ordered list** — its entries have a meaningful sequence
+from the site root to the current page — wrapped in a `<nav>` landmark.
+
+- The `<nav>` defaults to `aria-label="Breadcrumb"`, which is how assistive
+  technology identifies the breadcrumb navigation landmark. Override it only
+  if your product uses different terminology.
+- The final entry is the **current page**, so it is a `Breadcrumb.Page`
+  (a non-link `<span>`) rather than a `Breadcrumb.Link`.
+- `Breadcrumb.Page` carries `aria-current="page"` to mark the user's current
+  location.
+
+## The current page
+
+The last entry should always be a `Breadcrumb.Page`:
+
+```tsx
+<Breadcrumb.Item>
+  <Breadcrumb.Page>Current article</Breadcrumb.Page>
+</Breadcrumb.Item>
+```
+
+It renders a `<span aria-current="page">` — not a link — because the page the
+user is already on is not a navigation target.
+
+## Separators
+
+`Breadcrumb.Separator` is a decorative `<li role="presentation" aria-hidden="true">`.
+It sits inside the `<ol>` as a sibling of the items, but `role="presentation"`
+removes it from the list semantics and `aria-hidden` hides it from the
+accessibility tree — screen readers never announce it.
+
+It defaults to a `"/"` glyph. Pass `children` to use a custom separator:
+
+```tsx
+<Breadcrumb.Separator>›</Breadcrumb.Separator>
+<Breadcrumb.Separator><ChevronRight /></Breadcrumb.Separator>
+```
+
+## `asChild` composition
+
+`Breadcrumb.Link` accepts `asChild` so it can render a routing library's link
+component instead of a bare `<a>`. The breadcrumb link's props are merged onto
+the consumer's element and the native `<a>` is dropped.
+
+```tsx
+import { Link as RouterLink } from "react-router-dom";
+
+<Breadcrumb.Link asChild>
+  <RouterLink to="/library">Library</RouterLink>
+</Breadcrumb.Link>;
+```
+
+## Styling hooks
+
+No styles ship with the component. Target the rendered elements directly or
+pass a `className` to any sub-component:
+
+```css
+nav[aria-label="Breadcrumb"] ol {
+  display: flex;
+  gap: 0.5rem;
+  list-style: none;
+}
+
+nav[aria-label="Breadcrumb"] [aria-current="page"] {
+  font-weight: 600;
+}
+```

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

@@ -0,0 +1,33 @@
+import { render, screen } from "@testing-library/react";
+
+import { Breadcrumb } from "../Breadcrumb";
+
+describe("Breadcrumb asChild", () => {
+  it("renders Breadcrumb.Link as the consumer element, with no wrapping <a>", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Link asChild>
+        <button type="button">Library</button>
+      </Breadcrumb.Link>,
+    );
+    const link = screen.getByRole("button", { name: "Library" });
+
+    // Assert — the native <a> is dropped entirely
+    expect(link.closest("a")).toBeNull();
+  });
+
+  it("merges Breadcrumb.Link props onto the asChild element", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Link asChild className="crumb" data-testid="link">
+        <a href="/library">Library</a>
+      </Breadcrumb.Link>,
+    );
+    const link = screen.getByTestId("link");
+
+    // Assert — consumer's <a> kept; className and href both present on it
+    expect(link.tagName).toBe("A");
+    expect(link).toHaveClass("crumb");
+    expect(link).toHaveAttribute("href", "/library");
+  });
+});

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

@@ -0,0 +1,132 @@
+import { render, screen } from "@testing-library/react";
+
+import { Breadcrumb } from "../Breadcrumb";
+
+describe("Breadcrumb basic rendering", () => {
+  it('renders the Root as a <nav aria-label="Breadcrumb">', () => {
+    // Arrange & Act
+    render(<Breadcrumb.Root />);
+    const nav = screen.getByRole("navigation", { name: "Breadcrumb" });
+
+    // Assert
+    expect(nav.tagName).toBe("NAV");
+  });
+
+  it("lets the consumer override the Root aria-label", () => {
+    // Arrange & Act
+    render(<Breadcrumb.Root aria-label="You are here" />);
+
+    // Assert
+    expect(
+      screen.getByRole("navigation", { name: "You are here" }),
+    ).toBeInTheDocument();
+  });
+
+  it("renders the List as an <ol>", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Root>
+        <Breadcrumb.List />
+      </Breadcrumb.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("list").tagName).toBe("OL");
+  });
+
+  it("renders the Item as an <li>", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Root>
+        <Breadcrumb.List>
+          <Breadcrumb.Item>Home</Breadcrumb.Item>
+        </Breadcrumb.List>
+      </Breadcrumb.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("listitem").tagName).toBe("LI");
+  });
+
+  it("renders the Link as an <a> carrying its href", () => {
+    // Arrange & Act
+    render(<Breadcrumb.Link href="/library">Library</Breadcrumb.Link>);
+    const link = screen.getByRole("link", { name: "Library" });
+
+    // Assert
+    expect(link.tagName).toBe("A");
+    expect(link).toHaveAttribute("href", "/library");
+  });
+
+  it('renders the Page as a <span aria-current="page">', () => {
+    // Arrange & Act
+    render(<Breadcrumb.Page>Current article</Breadcrumb.Page>);
+    const page = screen.getByText("Current article");
+
+    // Assert
+    expect(page.tagName).toBe("SPAN");
+    expect(page).toHaveAttribute("aria-current", "page");
+  });
+
+  it("renders the Separator as a decorative <li> with a default glyph", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Root>
+        <Breadcrumb.List>
+          <Breadcrumb.Separator data-testid="sep" />
+        </Breadcrumb.List>
+      </Breadcrumb.Root>,
+    );
+    const separator = screen.getByTestId("sep");
+
+    // Assert — presentation role keeps it out of the list semantics
+    expect(separator.tagName).toBe("LI");
+    expect(separator).toHaveAttribute("role", "presentation");
+    expect(separator).toHaveAttribute("aria-hidden", "true");
+    expect(separator).toHaveTextContent("/");
+    expect(screen.queryByRole("listitem")).not.toBeInTheDocument();
+  });
+
+  it("lets the consumer override the Separator glyph", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Root>
+        <Breadcrumb.List>
+          <Breadcrumb.Separator data-testid="sep">&rsaquo;</Breadcrumb.Separator>
+        </Breadcrumb.List>
+      </Breadcrumb.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("sep")).toHaveTextContent("›");
+  });
+
+  it("composes a full trail of links, separators, and the current page", () => {
+    // Arrange & Act
+    render(
+      <Breadcrumb.Root>
+        <Breadcrumb.List>
+          <Breadcrumb.Item>
+            <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
+          </Breadcrumb.Item>
+          <Breadcrumb.Separator />
+          <Breadcrumb.Item>
+            <Breadcrumb.Link href="/library">Library</Breadcrumb.Link>
+          </Breadcrumb.Item>
+          <Breadcrumb.Separator />
+          <Breadcrumb.Item>
+            <Breadcrumb.Page>Current article</Breadcrumb.Page>
+          </Breadcrumb.Item>
+        </Breadcrumb.List>
+      </Breadcrumb.Root>,
+    );
+
+    // Assert — two links, three list items, current page marked
+    expect(screen.getAllByRole("link")).toHaveLength(2);
+    expect(screen.getAllByRole("listitem")).toHaveLength(3);
+    expect(screen.getByText("Current article")).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+  });
+});

package/src/Breadcrumb/index.ts

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

package/src/Breadcrumb/types.ts

@@ -0,0 +1,22 @@
+import { ComponentProps } from "react";
+
+/** Props for {@link Breadcrumb.Root} — all `<nav>` attributes. */
+export type BreadcrumbRootProps = ComponentProps<"nav">;
+
+/** Props for {@link Breadcrumb.List} — all `<ol>` attributes. */
+export type BreadcrumbListProps = ComponentProps<"ol">;
+
+/** Props for {@link Breadcrumb.Item} — all `<li>` attributes. */
+export type BreadcrumbItemProps = ComponentProps<"li">;
+
+/** Props for {@link Breadcrumb.Link} — all `<a>` attributes plus `asChild`. */
+export type BreadcrumbLinkProps = ComponentProps<"a"> & {
+  /** Render the consumer's own element instead of the native `<a>`. */
+  asChild?: boolean;
+};
+
+/** Props for {@link Breadcrumb.Page} — all `<span>` attributes. */
+export type BreadcrumbPageProps = ComponentProps<"span">;
+
+/** Props for {@link Breadcrumb.Separator} — all `<li>` attributes. */
+export type BreadcrumbSeparatorProps = ComponentProps<"li">;

package/src/Button/Button.tsx

@@ -0,0 +1,95 @@
+import { Slot } from "../Slot";
+import { ButtonProps } from "./types";
+
+/**
+ * A headless, accessible `<button>` element.
+ *
+ * Renders a native `<button type="button">` by default, preventing
+ * accidental form submission. The `type` prop can override this to
+ * `"submit"` or `"reset"` when the button lives inside a form.
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLButtonElement` directly:
+ *
+ * ```tsx
+ * const ref = useRef<HTMLButtonElement>(null);
+ * <Button ref={ref}>Click me</Button>
+ * ```
+ *
+ * **Disabled.** Sets native `disabled` (removing the button from the
+ * tab order and suppressing clicks) plus `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; }
+ * ```
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of
+ * `<button>`, merging all props (aria-*, data-*, event handlers, ref)
+ * via the {@link Slot} utility. Event handlers compose with the child's
+ * own handlers (child runs first). `type` is **not** forwarded in this
+ * mode — the child element owns its own type semantics.
+ *
+ * **Icon-only buttons.** Provide `aria-label` or `aria-labelledby`
+ * when the button has no visible text label. Mark decorative icons
+ * `aria-hidden="true"`:
+ *
+ * ```tsx
+ * <Button aria-label="Close dialog">
+ *   <CloseIcon aria-hidden="true" />
+ * </Button>
+ * ```
+ *
+ * @example Text button
+ * ```tsx
+ * <Button onClick={handleSave}>Save</Button>
+ * ```
+ *
+ * @example Submit button inside a form
+ * ```tsx
+ * <Button type="submit">Send</Button>
+ * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <Button disabled>Save</Button>
+ * ```
+ *
+ * @example asChild — render a router link styled as a button
+ * ```tsx
+ * <Button asChild>
+ *   <a href="/settings">Settings</a>
+ * </Button>
+ * ```
+ */
+export function Button({
+  asChild = false,
+  type = "button",
+  disabled,
+  children,
+  ref,
+  ...rest
+}: ButtonProps) {
+  const rootProps = {
+    ...rest,
+    ref,
+    disabled,
+    "data-disabled": disabled ? "" : undefined,
+  };
+
+  if (asChild) {
+    return <Slot {...rootProps}>{children}</Slot>;
+  }
+
+  return (
+    <button type={type} {...rootProps}>
+      {children}
+    </button>
+  );
+}
+
+Button.displayName = "Button";