@primitiv-ui/react 0.1.0

package/src/Slot/composeEventHandlers.ts

@@ -0,0 +1,38 @@
+/**
+ * Returns an event handler that runs the consumer-supplied handler first,
+ * then the library's own handler — unless the consumer called
+ * `event.preventDefault()`, in which case the library handler is skipped.
+ *
+ * This is the standard composition pattern used throughout headless
+ * components to let consumers attach their own listeners onto a
+ * sub-component without clobbering the component's own behaviour, while
+ * still giving them an opt-out via `preventDefault()`.
+ *
+ * @example Consumer logs every click; component still closes the modal
+ * afterwards:
+ * ```tsx
+ * <Modal.Overlay onClick={(e) => console.log("overlay clicked")} />
+ * ```
+ *
+ * @example Consumer vetoes the component's behaviour:
+ * ```tsx
+ * <Modal.Overlay onClick={(e) => {
+ *   if (formIsDirty) e.preventDefault(); // don't close
+ * }} />
+ * ```
+ */
+export function composeEventHandlers<E>(
+  theirHandler: ((event: E) => void) | undefined,
+  ourHandler: (event: E) => void,
+  { checkForDefaultPrevented = true }: { checkForDefaultPrevented?: boolean } = {},
+) {
+  return function handleEvent(event: E) {
+    theirHandler?.(event);
+    if (
+      !checkForDefaultPrevented ||
+      !(event as unknown as Event).defaultPrevented
+    ) {
+      ourHandler(event);
+    }
+  };
+}

package/src/Slot/index.ts

@@ -0,0 +1,3 @@
+export * from "./Slot";
+export * from "./composeEventHandlers";
+export * from "./types";

package/src/Slot/types.ts

@@ -0,0 +1,5 @@
+import { HTMLAttributes, ReactNode } from "react";
+
+export type SlotProps = HTMLAttributes<HTMLElement> & {
+  children?: ReactNode;
+};

package/src/Status/README.md

@@ -0,0 +1,50 @@
+# Status
+
+A polite live region for low-priority, non-urgent status messages,
+implementing the
+[WAI-ARIA `status` role](https://www.w3.org/TR/wai-aria-1.2/#status).
+
+```tsx
+import { Status } from "@primitiv-ui/react";
+
+{
+  saved && <Status>All changes saved.</Status>;
+}
+```
+
+## Props
+
+| Prop        | Type                    | Default | Notes                                              |
+| ----------- | ----------------------- | ------- | -------------------------------------------------- |
+| `asChild`   | `boolean`               | `false` | Render the consumer's element instead of a `<div>` |
+| `className` | `string`                | —       | Applied directly to the rendered element           |
+| `...rest`   | `ComponentProps<"div">` | —       | All other `<div>` props, including `aria-*`         |
+
+## Behaviour
+
+`Status` renders a `<div role="status">`. The `status` role carries an
+implicit `aria-live="polite"` and `aria-atomic="true"`, so assistive
+technology announces the message once the user is idle, without
+interrupting them. Use it for confirmations, counts, and background
+progress — for errors the user must see immediately, reach for
+[`Alert`](../Alert/README.md).
+
+## Announce on change
+
+A live region announces content that changes *after* the region is in
+the DOM. Either render the `Status` conditionally, or keep it mounted
+and update its text content:
+
+```tsx
+<Status>{count} items in your cart</Status>
+```
+
+## asChild
+
+Pass `asChild` to apply `role="status"` to the consumer's own element:
+
+```tsx
+<Status asChild>
+  <output>{count} items in your cart</output>
+</Status>
+```

package/src/Status/Status.tsx

@@ -0,0 +1,44 @@
+import { Slot } from "../Slot";
+import { StatusProps } from "./types";
+
+/**
+ * A polite live region for low-priority, non-urgent status messages.
+ *
+ * Renders a `<div role="status">`. The `status` role carries an
+ * implicit `aria-live="polite"` and `aria-atomic="true"`, so assistive
+ * technology announces the message once the user is idle, without
+ * interrupting them — use it for confirmations, counts, and background
+ * progress. For errors the user must see immediately, reach for
+ * `Alert` instead.
+ *
+ * Render the `Status` conditionally, or update its text content while
+ * it stays mounted: the live region announces content that changes
+ * *after* it is already in the DOM.
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of
+ * a `<div>`, merging `role="status"` and all other props in via the
+ * {@link Slot} utility.
+ *
+ * @example Confirmation message
+ * ```tsx
+ * {saved && <Status>All changes saved.</Status>}
+ * ```
+ *
+ * @example asChild — keep semantic markup
+ * ```tsx
+ * <Status asChild>
+ *   <output>{count} items in your cart</output>
+ * </Status>
+ * ```
+ */
+export function Status({ asChild = false, children, ...rest }: StatusProps) {
+  const rootProps = { role: "status", ...rest };
+
+  if (asChild) {
+    return <Slot {...rootProps}>{children}</Slot>;
+  }
+
+  return <div {...rootProps}>{children}</div>;
+}
+
+Status.displayName = "Status";

package/src/Status/__tests__/Status.test.tsx

@@ -0,0 +1,28 @@
+import { Status } from "..";
+import { render, screen } from "@testing-library/react";
+
+describe("Status component", () => {
+  it("should render a div with role status containing its children", () => {
+    // Arrange
+    render(<Status>3 items added to your cart</Status>);
+
+    // Assert
+    const status = screen.getByRole("status");
+    expect(status.tagName).toBe("DIV");
+    expect(status).toHaveTextContent("3 items added to your cart");
+  });
+
+  it("should render the consumer element with asChild, keeping role status", () => {
+    // Arrange
+    render(
+      <Status asChild>
+        <section>Saved</section>
+      </Status>,
+    );
+
+    // Assert
+    const status = screen.getByRole("status");
+    expect(status.tagName).toBe("SECTION");
+    expect(status).toHaveTextContent("Saved");
+  });
+});

package/src/Status/index.ts

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

package/src/Status/types.ts

@@ -0,0 +1,5 @@
+import { ComponentProps } from "react";
+
+export type StatusProps = ComponentProps<"div"> & {
+  asChild?: boolean;
+};

package/src/Switch/README.md

@@ -0,0 +1,121 @@
+# Switch
+
+Headless, accessible **Switch** — a compound component implementing the
+[WAI-ARIA Switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
+on a native `<button role="switch">`. Semantically represents an immediate
+on/off action (as opposed to a selection choice). Zero styles ship.
+
+```tsx
+import { Switch } from "@primitiv-ui/react";
+
+<Switch.Root defaultChecked aria-label="Enable notifications">
+  <Switch.Thumb />
+</Switch.Root>
+```
+
+## Sub-components
+
+| Export | Element | ARIA / data hooks | `asChild` |
+|--------|---------|------------------|-----------|
+| `Switch.Root` | `<button>` | `role="switch"`, `aria-checked`, `data-state`, `data-disabled` | yes |
+| `Switch.Thumb` | `<span>` | `aria-hidden="true"`, `data-state` | yes |
+
+## State modes
+
+### Uncontrolled
+
+Pass `defaultChecked` (or omit for unchecked on mount). The component owns
+the value internally.
+
+```tsx
+<Switch.Root defaultChecked aria-label="Enable dark mode">
+  <Switch.Thumb />
+</Switch.Root>
+```
+
+### Controlled
+
+Pass `checked` and `onCheckedChange` together. The parent owns the value.
+
+```tsx
+const [enabled, setEnabled] = useState(false);
+
+<Switch.Root checked={enabled} onCheckedChange={setEnabled} aria-label="…">
+  <Switch.Thumb />
+</Switch.Root>
+```
+
+## Keyboard interaction
+
+| Key | Behaviour |
+|-----|-----------|
+| `Space` | Toggle the switch (native `<button>` behaviour) |
+| `Enter` | Toggle the switch (native `<button>` behaviour) |
+| `Tab` | Move focus to or from the switch |
+
+## Disabled
+
+Pass `disabled` on the Root. The native attribute suppresses clicks and removes
+the switch from the focus ring. `data-disabled=""` is set for CSS targeting.
+
+```tsx
+<Switch.Root aria-label="Enable feature" disabled>
+  <Switch.Thumb />
+</Switch.Root>
+```
+
+## The Thumb
+
+`Switch.Thumb` is **always mounted** — unlike `Checkbox.Indicator`, it never
+conditionally unmounts. Its visual position (left for off, right for on) is
+driven entirely by CSS targeting `data-state`. This gives consumers a real DOM
+node to animate with `transition` or Web Animations, rather than being
+constrained to pseudo-elements.
+
+```scss
+.switch-root {
+  position: relative;
+  width: 2.75rem;
+  height: 1.5rem;
+  border-radius: 9999px;
+  background: #d1d5db;
+  transition: background 120ms ease;
+
+  &[data-state="checked"] {
+    background: #6366f1;
+  }
+}
+
+.switch-thumb {
+  position: absolute;
+  top: 0.125rem;
+  left: 0.125rem;
+  width: 1.25rem;
+  height: 1.25rem;
+  border-radius: 50%;
+  background: white;
+  transition: translate 120ms ease;
+
+  &[data-state="checked"] {
+    translate: 1.25rem 0;
+  }
+}
+```
+
+## `asChild` composition
+
+Both sub-components accept `asChild`. The library's ARIA attributes,
+`data-state`, event handlers, and ref are merged onto the consumer's element.
+
+```tsx
+<Switch.Root asChild aria-label="Enable notifications">
+  <div role="switch">…</div>
+</Switch.Root>
+```
+
+## Styling hooks
+
+| Attribute | Values | Set on |
+|-----------|--------|--------|
+| `data-state` | `"checked"` \| `"unchecked"` | `Switch.Root`, `Switch.Thumb` |
+| `data-disabled` | `""` (present when disabled) | `Switch.Root` |

package/src/Switch/Switch.tsx

@@ -0,0 +1,167 @@
+import { useMemo } from "react";
+
+import { Slot, composeEventHandlers } from "../Slot";
+
+import { SwitchContext } from "./SwitchContext";
+import { useSwitchContext, useSwitchRoot } from "./hooks";
+import { SwitchRootProps, SwitchThumbProps } from "./types";
+
+/**
+ * The root of a Switch — a native `<button type="button" role="switch">` that
+ * owns the binary checked state and provides {@link SwitchContext} to
+ * descendant {@link SwitchThumb | `Switch.Thumb`}s.
+ *
+ * Supports two state modes, statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass
+ *   {@link SwitchRootProps.defaultChecked | `defaultChecked`} (or omit for
+ *   unchecked-on-mount). The component owns the value internally.
+ * - **Controlled** — pass
+ *   {@link SwitchRootProps.checked | `checked`} *and*
+ *   {@link SwitchRootProps.onCheckedChange | `onCheckedChange`} together.
+ *   The parent owns the value; every click defers back through the callback.
+ *
+ * **ARIA.** `role="switch"` and `aria-checked` are set automatically.
+ * Provide an accessible name via `aria-label`, `aria-labelledby`, or
+ * a visible label element.
+ *
+ * **Styling hooks.** `data-state="checked" | "unchecked"` on the root, plus
+ * `data-disabled=""` when disabled.
+ *
+ * **`asChild` prop.** Pass `asChild` to render any consumer-supplied element
+ * with the switch's ARIA attributes, `data-state`, composed `onClick`, and
+ * `ref` merged in. The native `<button>` is dropped.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Switch.Root defaultChecked aria-label="Enable notifications">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [enabled, setEnabled] = useState(false);
+ *
+ * <Switch.Root checked={enabled} onCheckedChange={setEnabled} aria-label="…">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ */
+function SwitchRoot({
+  defaultChecked,
+  checked,
+  onCheckedChange,
+  disabled,
+  asChild = false,
+  onClick,
+  children,
+  ref,
+  ...rest
+}: SwitchRootProps) {
+  const { checked: isChecked, toggle } = useSwitchRoot({
+    defaultChecked,
+    checked,
+    onCheckedChange,
+  });
+  const contextValue = useMemo(() => ({ checked: isChecked }), [isChecked]);
+  const rootProps = {
+    ...rest,
+    ref,
+    role: "switch" as const,
+    "aria-checked": isChecked,
+    "data-state": isChecked ? ("checked" as const) : ("unchecked" as const),
+    "data-disabled": disabled ? "" : undefined,
+    disabled,
+    onClick: composeEventHandlers(onClick, toggle),
+  };
+  return (
+    <SwitchContext.Provider value={contextValue}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <button type="button" {...rootProps}>
+          {children}
+        </button>
+      )}
+    </SwitchContext.Provider>
+  );
+}
+
+SwitchRoot.displayName = "SwitchRoot";
+
+/**
+ * A decorative `<span aria-hidden="true">` that represents the sliding thumb
+ * of the switch. Always mounted — its position is driven entirely by CSS
+ * targeting `data-state="checked" | "unchecked"`. Unlike
+ * {@link Checkbox.Indicator}, it never conditionally unmounts.
+ *
+ * **Styling hook.** Mirrors the parent Root's
+ * `data-state="checked" | "unchecked"` for CSS transitions.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the consumer's own element
+ * as the thumb, with `aria-hidden` and `data-state` merged in.
+ *
+ * @example
+ * ```tsx
+ * <Switch.Root aria-label="Enable notifications">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ *
+ * @throws if rendered outside a `Switch.Root`.
+ */
+function SwitchThumb({ children, asChild = false, ...rest }: SwitchThumbProps) {
+  const { checked } = useSwitchContext();
+  const thumbProps = {
+    ...rest,
+    "aria-hidden": "true" as const,
+    "data-state": checked ? ("checked" as const) : ("unchecked" as const),
+  };
+  if (asChild) {
+    return <Slot {...thumbProps}>{children}</Slot>;
+  }
+  return <span {...thumbProps}>{children}</span>;
+}
+
+SwitchThumb.displayName = "SwitchThumb";
+
+type TSwitchCompound = typeof SwitchRoot & {
+  Root: typeof SwitchRoot;
+  Thumb: typeof SwitchThumb;
+};
+
+/**
+ * Headless, accessible **Switch** — a compound component implementing the
+ * [WAI-ARIA Switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
+ * on a native `<button role="switch">`. Semantically represents an immediate
+ * on/off action (as opposed to a selection choice). Zero styles ship.
+ *
+ * `Switch` is both callable (an alias of
+ * {@link SwitchRoot | `Switch.Root`}) and carries its sub-components as
+ * static properties.
+ *
+ * - {@link SwitchRoot | `Switch.Root`} — state owner, context provider, toggle button.
+ * - {@link SwitchThumb | `Switch.Thumb`} — always-mounted decorative thumb;
+ *   position driven by `data-state` via CSS.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { Switch } from "@primitiv-ui/react";
+ *
+ * <Switch.Root aria-label="Enable notifications">
+ *   <Switch.Thumb />
+ * </Switch.Root>
+ * ```
+ *
+ * @see {@link SwitchRoot} for state modes and ARIA details.
+ * @see {@link SwitchThumb} for styling the sliding thumb.
+ */
+const SwitchCompound: TSwitchCompound = Object.assign(SwitchRoot, {
+  Root: SwitchRoot,
+  Thumb: SwitchThumb,
+});
+
+SwitchCompound.displayName = "Switch";
+
+export { SwitchCompound as Switch };

package/src/Switch/SwitchContext.ts

@@ -0,0 +1,10 @@
+import { createStrictContext } from "../utils";
+
+export type SwitchContextValue = {
+  checked: boolean;
+};
+
+export const [SwitchContext, useSwitchContext] =
+  createStrictContext<SwitchContextValue>(
+    "Switch.Thumb must be rendered inside a <Switch.Root>.",
+  );

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

@@ -0,0 +1,56 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Switch } from "../Switch";
+
+describe("Switch asChild", () => {
+  it("renders the Root as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <Switch.Root asChild aria-label="Enable notifications">
+        <div>Toggle</div>
+      </Switch.Root>,
+    );
+
+    // Assert — div rendered, not button; role and aria-checked merged
+    const sw = screen.getByRole("switch", { name: "Enable notifications" });
+    expect(sw.tagName).toBe("DIV");
+    expect(sw).toHaveAttribute("aria-checked", "false");
+  });
+
+  it("merges onClick and toggles state on the asChild Root element", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <Switch.Root asChild aria-label="Enable notifications" onClick={onClick}>
+        <div>Toggle</div>
+      </Switch.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("switch", { name: "Enable notifications" }));
+
+    // Assert — consumer onClick ran and state toggled
+    expect(onClick).toHaveBeenCalledOnce();
+    expect(
+      screen.getByRole("switch", { name: "Enable notifications" }),
+    ).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("renders the Thumb as the consumer element when asChild is set", () => {
+    // Arrange & Act
+    render(
+      <Switch.Root aria-label="Enable notifications">
+        <Switch.Thumb asChild>
+          <span data-testid="custom-thumb" />
+        </Switch.Thumb>
+      </Switch.Root>,
+    );
+
+    // Assert — our span rendered; aria-hidden and data-state merged onto it
+    const thumb = screen.getByTestId("custom-thumb");
+    expect(thumb).toHaveAttribute("aria-hidden", "true");
+    expect(thumb).toHaveAttribute("data-state", "unchecked");
+  });
+});

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

@@ -0,0 +1,76 @@
+import { render, screen } from "@testing-library/react";
+
+import { Switch } from "../Switch";
+
+describe("Switch basic rendering", () => {
+  it('renders a <button type="button" role="switch">', () => {
+    // Arrange & Act
+    render(<Switch.Root aria-label="Enable notifications" />);
+    const sw = screen.getByRole("switch", { name: "Enable notifications" });
+
+    // Assert
+    expect(sw.tagName).toBe("BUTTON");
+    expect(sw).toHaveAttribute("type", "button");
+  });
+
+  it('defaults aria-checked="false" when unchecked', () => {
+    // Arrange & Act
+    render(<Switch.Root aria-label="Enable notifications" />);
+
+    // Assert
+    expect(
+      screen.getByRole("switch", { name: "Enable notifications" }),
+    ).toHaveAttribute("aria-checked", "false");
+  });
+
+  it('defaults data-state="unchecked" on mount', () => {
+    // Arrange & Act
+    render(<Switch.Root aria-label="Enable notifications" />);
+
+    // Assert
+    expect(
+      screen.getByRole("switch", { name: "Enable notifications" }),
+    ).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("renders Switch.Thumb as a <span> inside the root", () => {
+    // Arrange & Act
+    render(
+      <Switch.Root aria-label="Enable notifications">
+        <Switch.Thumb data-testid="thumb" />
+      </Switch.Root>,
+    );
+
+    // Assert
+    const thumb = screen.getByTestId("thumb");
+    expect(thumb.tagName).toBe("SPAN");
+    expect(thumb).toBeInTheDocument();
+  });
+
+  it('sets aria-hidden="true" on the Thumb', () => {
+    // Arrange & Act
+    render(
+      <Switch.Root aria-label="Enable notifications">
+        <Switch.Thumb data-testid="thumb" />
+      </Switch.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("thumb")).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it('sets data-state="unchecked" on Thumb by default', () => {
+    // Arrange & Act
+    render(
+      <Switch.Root aria-label="Enable notifications">
+        <Switch.Thumb data-testid="thumb" />
+      </Switch.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("thumb")).toHaveAttribute(
+      "data-state",
+      "unchecked",
+    );
+  });
+});