@primitiv-ui/react 0.1.0

package/src/EmptyState/__tests__/EmptyState.Title.test.tsx

@@ -0,0 +1,26 @@
+import { EmptyState } from "..";
+import { render, screen } from "@testing-library/react";
+
+describe("EmptyState.Title component", () => {
+  it("should render a paragraph containing its children", () => {
+    // Arrange
+    render(<EmptyState.Title>No results found</EmptyState.Title>);
+
+    // Assert
+    const title = screen.getByText("No results found");
+    expect(title.tagName).toBe("P");
+  });
+
+  it("should render the consumer element with asChild", () => {
+    // Arrange
+    render(
+      <EmptyState.Title asChild>
+        <h2>No results found</h2>
+      </EmptyState.Title>,
+    );
+
+    // Assert
+    const title = screen.getByRole("heading", { name: "No results found" });
+    expect(title.tagName).toBe("H2");
+  });
+});

package/src/EmptyState/index.ts

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

package/src/EmptyState/types.ts

@@ -0,0 +1,21 @@
+import { ComponentProps } from "react";
+
+type WithAsChild = {
+  /** Render the consumer's own element instead of the default, via `Slot`. */
+  asChild?: boolean;
+};
+
+/** Props for {@link EmptyState.Root} — all `<div>` props plus `asChild`. */
+export type EmptyStateRootProps = ComponentProps<"div"> & WithAsChild;
+
+/** Props for {@link EmptyState.Media} — all `<div>` props plus `asChild`. */
+export type EmptyStateMediaProps = ComponentProps<"div"> & WithAsChild;
+
+/** Props for {@link EmptyState.Title} — all `<p>` props plus `asChild`. */
+export type EmptyStateTitleProps = ComponentProps<"p"> & WithAsChild;
+
+/** Props for {@link EmptyState.Description} — all `<p>` props plus `asChild`. */
+export type EmptyStateDescriptionProps = ComponentProps<"p"> & WithAsChild;
+
+/** Props for {@link EmptyState.Actions} — all `<div>` props plus `asChild`. */
+export type EmptyStateActionsProps = ComponentProps<"div"> & WithAsChild;

package/src/Field/Field.tsx

@@ -0,0 +1,239 @@
+import { useId, useMemo } from "react";
+
+import { Slot } from "../Slot";
+import { FieldContext } from "./FieldContext";
+import { useFieldContext } from "./hooks";
+import {
+  FieldDescriptionProps,
+  FieldErrorTextProps,
+  FieldLabelProps,
+  FieldRootProps,
+} from "./types";
+
+/**
+ * The root of a Field — provides {@link FieldContext} (stable id plus
+ * derived `descriptionId` / `errorId`, and the cascaded `invalid` /
+ * `disabled` / `required` flags) and renders a `<div data-field>`
+ * wrapper.
+ *
+ * **ID propagation.** If `id` is passed, it's used directly; otherwise
+ * a stable id is auto-generated via React's `useId`. The
+ * `descriptionId` and `errorId` are derived from the field id
+ * (`<id>-description` / `<id>-error`) and are exposed via context to
+ * any sub-component or context-aware control (e.g. `Input`).
+ *
+ * **State cascade.** `invalid`, `disabled`, and `required` cascade via
+ * context to any control reading {@link FieldContext} — `Input`
+ * inherits them automatically when nested inside a `<Field.Root>` and
+ * the consumer hasn't passed an explicit override. The wrapper also
+ * carries `data-field-invalid` / `data-field-disabled` /
+ * `data-field-required` attributes when the corresponding flag is
+ * truthy, so CSS can style the whole field group on a single selector.
+ *
+ * **`asChild` composition.** Pass `asChild` to render the consumer's
+ * element instead of `<div>` — e.g. a semantic `<fieldset>` or
+ * `<section>`. The `data-field-*` hooks and context provider stay
+ * intact.
+ *
+ * @example
+ * ```tsx
+ * <Field.Root id="email" invalid={!!errors.email}>
+ *   <Field.Label>Email</Field.Label>
+ *   <Input type="email" {...register("email")} />
+ *   <Field.Description>We won't share it.</Field.Description>
+ *   <Field.ErrorText>{errors.email?.message}</Field.ErrorText>
+ * </Field.Root>
+ * ```
+ */
+function FieldRoot({
+  id: idProp,
+  invalid = false,
+  disabled = false,
+  required = false,
+  asChild = false,
+  children,
+  ...rest
+}: FieldRootProps) {
+  const autoId = useId();
+  const id = idProp ?? autoId;
+  const descriptionId = `${id}-description`;
+  const errorId = `${id}-error`;
+
+  const value = useMemo(
+    () => ({ id, descriptionId, errorId, invalid, disabled, required }),
+    [id, descriptionId, errorId, invalid, disabled, required],
+  );
+
+  const rootProps = {
+    ...rest,
+    "data-field": "",
+    "data-field-invalid": invalid ? "" : undefined,
+    "data-field-disabled": disabled ? "" : undefined,
+    "data-field-required": required ? "" : undefined,
+  };
+
+  return (
+    <FieldContext.Provider value={value}>
+      {asChild ? (
+        <Slot {...rootProps}>{children}</Slot>
+      ) : (
+        <div {...rootProps}>{children}</div>
+      )}
+    </FieldContext.Provider>
+  );
+}
+
+FieldRoot.displayName = "FieldRoot";
+
+/**
+ * Renders a `<label>` wired to the field's id via `htmlFor` — clicking
+ * the label focuses the associated control.
+ *
+ * **`asChild` composition.** Pass `asChild` to render any consumer
+ * element with the `htmlFor` attribute merged on.
+ *
+ * @throws If rendered outside a `<Field.Root>`.
+ */
+function FieldLabel({ asChild = false, children, ...rest }: FieldLabelProps) {
+  const { id } = useFieldContext();
+  const labelProps = { ...rest, htmlFor: id };
+
+  if (asChild) {
+    return <Slot {...labelProps}>{children}</Slot>;
+  }
+  return <label {...labelProps}>{children}</label>;
+}
+
+FieldLabel.displayName = "FieldLabel";
+
+/**
+ * Renders a `<div>` carrying the field's `descriptionId`. Reference it
+ * from your control via `aria-describedby` for assistive technology to
+ * announce it alongside the label — `Input` does this automatically
+ * when nested inside a `<Field.Root>`.
+ *
+ * **`asChild` composition.** Pass `asChild` to render a `<p>`,
+ * `<span>`, or any other element with the `id` merged on.
+ *
+ * @throws If rendered outside a `<Field.Root>`.
+ */
+function FieldDescription({
+  asChild = false,
+  children,
+  ...rest
+}: FieldDescriptionProps) {
+  const { descriptionId } = useFieldContext();
+  const descriptionProps = { ...rest, id: descriptionId };
+
+  if (asChild) {
+    return <Slot {...descriptionProps}>{children}</Slot>;
+  }
+  return <div {...descriptionProps}>{children}</div>;
+}
+
+FieldDescription.displayName = "FieldDescription";
+
+/**
+ * Renders a `<div role="alert">` carrying the field's `errorId` — only
+ * when the field is in an invalid state. Returns `null` otherwise, so
+ * consumers can render it unconditionally and rely on the field to gate
+ * visibility.
+ *
+ * **`asChild` composition.** Pass `asChild` to render the consumer's
+ * element with the `id` and `role="alert"` merged on.
+ *
+ * @example
+ * ```tsx
+ * <Field.Root invalid={!!errors.email}>
+ *   <Field.ErrorText>{errors.email?.message ?? "Required"}</Field.ErrorText>
+ * </Field.Root>
+ * ```
+ *
+ * @throws If rendered outside a `<Field.Root>`.
+ */
+function FieldErrorText({
+  asChild = false,
+  children,
+  ...rest
+}: FieldErrorTextProps) {
+  const { errorId, invalid } = useFieldContext();
+  if (!invalid) return null;
+  const errorProps = { ...rest, id: errorId, role: "alert" as const };
+
+  if (asChild) {
+    return <Slot {...errorProps}>{children}</Slot>;
+  }
+  return <div {...errorProps}>{children}</div>;
+}
+
+FieldErrorText.displayName = "FieldErrorText";
+
+type TFieldCompound = typeof FieldRoot & {
+  Root: typeof FieldRoot;
+  Label: typeof FieldLabel;
+  Description: typeof FieldDescription;
+  ErrorText: typeof FieldErrorText;
+};
+
+/**
+ * Headless, accessible **Field** — a coordinator compound that owns the
+ * `id`, `aria-describedby`, and `invalid` / `disabled` / `required`
+ * wiring for a single form control plus its label, description, and
+ * error message. Zero styles ship.
+ *
+ * `Field` does not render the control itself — it sits *around* an
+ * existing control (`Input`, `InputGroup` wrapping an `Input`, a future
+ * `Textarea`, etc.). The control opts into {@link FieldContext} to
+ * inherit the wiring; the sub-components below render the
+ * label / description / error UI.
+ *
+ * `Field` is callable (alias of `Field.Root`) and carries its
+ * sub-components as static properties:
+ *
+ * - {@link FieldRoot | `Field.Root`} — provides context, renders the
+ *   `<div data-field>` wrapper (or any element via `asChild`).
+ * - {@link FieldLabel | `Field.Label`} — `<label htmlFor>` wired to the
+ *   field id.
+ * - {@link FieldDescription | `Field.Description`} — `<div id>` for
+ *   help text, referenced via `aria-describedby`.
+ * - {@link FieldErrorText | `Field.ErrorText`} — `<div role="alert">`
+ *   rendered only when invalid.
+ *
+ * Every part supports `asChild` for the consumer to swap in their own
+ * element while keeping the wiring.
+ *
+ * @example Basic
+ * ```tsx
+ * import { Field, Input } from "@primitiv-ui/react";
+ *
+ * <Field.Root>
+ *   <Field.Label>Email</Field.Label>
+ *   <Input type="email" required />
+ *   <Field.Description>We won't share it.</Field.Description>
+ * </Field.Root>
+ * ```
+ *
+ * @example With error and InputGroup adornments
+ * ```tsx
+ * <Field.Root id="email" invalid={!!errors.email}>
+ *   <Field.Label>Email</Field.Label>
+ *   <InputGroup>
+ *     <InputGroup.LeadingAdornment><MailIcon aria-hidden="true" /></InputGroup.LeadingAdornment>
+ *     <Input type="email" {...register("email")} />
+ *   </InputGroup>
+ *   <Field.ErrorText>{errors.email?.message}</Field.ErrorText>
+ * </Field.Root>
+ * ```
+ *
+ * @see {@link FieldContext} — the context shape that controls can opt into.
+ */
+const FieldCompound: TFieldCompound = Object.assign(FieldRoot, {
+  Root: FieldRoot,
+  Label: FieldLabel,
+  Description: FieldDescription,
+  ErrorText: FieldErrorText,
+});
+
+FieldCompound.displayName = "Field";
+
+export { FieldCompound as Field };

package/src/Field/FieldContext.ts

@@ -0,0 +1,22 @@
+import { createStrictContext } from "../utils";
+
+export type FieldContextValue = {
+  /** Stable id for the control wired to this field. */
+  id: string;
+  /** Id of the {@link Field.Description} element, when rendered. */
+  descriptionId: string;
+  /** Id of the {@link Field.ErrorText} element, when rendered. */
+  errorId: string;
+  /** Whether the field is in an invalid state. */
+  invalid: boolean;
+  /** Whether the field is disabled. */
+  disabled: boolean;
+  /** Whether the field is required. */
+  required: boolean;
+};
+
+export const [FieldContext, useFieldContext] =
+  createStrictContext<FieldContextValue>(
+    "Field sub-components must be rendered inside a <Field.Root>.",
+    "FieldContext",
+  );

package/src/Field/README.md

@@ -0,0 +1,167 @@
+# Field
+
+A headless, accessible coordinator that owns the `id`,
+`aria-describedby`, and `invalid` / `disabled` / `required` wiring for
+a single form control plus its label, description, and error message.
+Zero styles ship.
+
+```tsx
+import { Field, Input } from "@primitiv-ui/react";
+
+<Field.Root>
+  <Field.Label>Email</Field.Label>
+  <Input type="email" required />
+  <Field.Description>We won't share it.</Field.Description>
+</Field.Root>
+```
+
+## Anatomy
+
+| Part                        | Element                  | Styling hook                          |
+| --------------------------- | ------------------------ | ------------------------------------- |
+| `Field` / `Field.Root`      | `<div>`                  | `data-field=""`                       |
+| `Field.Label`               | `<label>` (`htmlFor=id`) | n/a                                   |
+| `Field.Description`         | `<div id=…-description>` | n/a                                   |
+| `Field.ErrorText`           | `<div role="alert">`     | n/a (only renders when invalid)       |
+
+Plus three state-driven hooks on the root: `data-field-invalid`,
+`data-field-disabled`, `data-field-required`.
+
+`Field` does **not** render the control itself — it sits *around* an
+existing control. `Input` reads `FieldContext` automatically and
+inherits the wiring; outside a `<Field.Root>`, `Input` behaves exactly
+as before.
+
+## State cascade
+
+Three props on `Field.Root` propagate via context to the control:
+
+```tsx
+<Field.Root invalid disabled required>
+  <Field.Label>Email</Field.Label>
+  <Input type="email" />
+  {/*  ^ inherits aria-invalid="true", disabled, required, plus
+        aria-describedby pointing at the error / description ids */}
+</Field.Root>
+```
+
+Consumer-supplied props on the control always win — pass
+`disabled={false}` on `Input` and it stays enabled regardless of
+`Field.Root`'s `disabled`.
+
+## ID and aria-describedby wiring
+
+`Field.Root` either accepts an explicit `id` or auto-generates one via
+`useId`. The derived ids:
+
+| Reference            | Form                |
+| -------------------- | ------------------- |
+| `field.id`           | `<id>`              |
+| `field.descriptionId`| `<id>-description`  |
+| `field.errorId`      | `<id>-error`        |
+
+When `Input` is rendered inside `Field.Root`:
+
+- `id` defaults to `field.id`
+- `aria-describedby` composes consumer-supplied ids first, then the
+  field's `descriptionId`, then the `errorId` (only when invalid)
+- `aria-invalid` is set to `"true"` when `field.invalid` is true
+
+If you don't render `Field.Description` or `Field.ErrorText`, the
+referenced ids point at nothing — screen readers handle missing ids
+gracefully, but it's worth knowing.
+
+## Validation flow
+
+`Field.ErrorText` returns `null` unless `Field.Root` is `invalid`, so
+you can render it unconditionally:
+
+```tsx
+<Field.Root invalid={!!errors.email}>
+  <Field.Label>Email</Field.Label>
+  <Input type="email" required {...register("email")} />
+  <Field.ErrorText>{errors.email?.message ?? "Required"}</Field.ErrorText>
+</Field.Root>
+```
+
+## With react-hook-form
+
+`Field` doesn't know about RHF — it just provides the wiring; you tell
+it whether the field is invalid by passing `invalid` to `Field.Root`,
+and spread `register` onto the `Input`:
+
+```tsx
+import { useForm } from "react-hook-form";
+
+const { register, formState: { errors } } = useForm();
+
+<Field.Root invalid={!!errors.email}>
+  <Field.Label>Email</Field.Label>
+  <Input type="email" required {...register("email")} />
+  <Field.Description>We won't spam you.</Field.Description>
+  <Field.ErrorText>{errors.email?.message}</Field.ErrorText>
+</Field.Root>
+```
+
+## With InputGroup
+
+`Field` and `InputGroup` compose freely — `Field` wraps the entire
+field group; `InputGroup` wraps just the control plus its adornments.
+
+```tsx
+<Field.Root invalid={!!errors.email}>
+  <Field.Label>Email</Field.Label>
+  <InputGroup>
+    <InputGroup.LeadingAdornment>
+      <MailIcon aria-hidden="true" />
+    </InputGroup.LeadingAdornment>
+    <Input type="email" {...register("email")} />
+  </InputGroup>
+  <Field.ErrorText>{errors.email?.message}</Field.ErrorText>
+</Field.Root>
+```
+
+`Input` still reads `FieldContext` even when wrapped in `InputGroup` —
+the context flows through any DOM nesting.
+
+## Sub-components throw when used outside a Root
+
+`Field.Label`, `Field.Description`, and `Field.ErrorText` throw a
+clear error if rendered outside a `<Field.Root>`. The strict-context
+hook ensures the typo / misuse fails loudly rather than rendering
+silently broken markup.
+
+## `asChild` composition
+
+Every part supports `asChild` for swapping the default element while
+preserving the wiring:
+
+```tsx
+// Render the field as a semantic <fieldset>
+<Field.Root asChild>
+  <fieldset>
+    <Field.Label>Email</Field.Label>
+    <Input type="email" />
+  </fieldset>
+</Field.Root>
+
+// Render the description as a <p> instead of a <div>
+<Field.Description asChild>
+  <p className="hint">We won't share it.</p>
+</Field.Description>
+
+// Render the error as a <p>
+<Field.ErrorText asChild>
+  <p className="error">{errors.email?.message}</p>
+</Field.ErrorText>
+
+// Render the label on a custom heading slot
+<Field.Label asChild>
+  <span className="label-text">Email</span>
+</Field.Label>
+```
+
+Merge rules follow the standard Slot contract: event handlers compose
+(child runs first), `style` is shallow-merged, `className` is
+concatenated, and the wired attributes (`htmlFor`, `id`, `role`,
+`data-field*`) are always merged onto the consumer element.

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

@@ -0,0 +1,83 @@
+import { render, screen } from "@testing-library/react";
+
+import { Field } from "../Field";
+
+describe("Field asChild composition", () => {
+  it("Root asChild renders the consumer element with data-field merged on", () => {
+    // Arrange & Act
+    render(
+      <Field.Root asChild data-testid="field">
+        <fieldset />
+      </Field.Root>,
+    );
+    const root = screen.getByTestId("field");
+
+    // Assert
+    expect(root.tagName).toBe("FIELDSET");
+    expect(root).toHaveAttribute("data-field", "");
+  });
+
+  it("Root asChild keeps data-field-invalid when invalid", () => {
+    // Arrange & Act
+    render(
+      <Field.Root asChild data-testid="field" invalid>
+        <section />
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("field")).toHaveAttribute(
+      "data-field-invalid",
+      "",
+    );
+  });
+
+  it("Label asChild renders the consumer element with htmlFor merged on", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="email">
+        <Field.Label asChild>
+          <span data-testid="label">Email</span>
+        </Field.Label>
+      </Field.Root>,
+    );
+    const label = screen.getByTestId("label");
+
+    // Assert
+    expect(label.tagName).toBe("SPAN");
+    expect(label).toHaveAttribute("for", "email");
+  });
+
+  it("Description asChild renders the consumer element with id merged on", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="email">
+        <Field.Description asChild>
+          <p data-testid="hint">We won't share it.</p>
+        </Field.Description>
+      </Field.Root>,
+    );
+    const description = screen.getByTestId("hint");
+
+    // Assert
+    expect(description.tagName).toBe("P");
+    expect(description).toHaveAttribute("id", "email-description");
+  });
+
+  it("ErrorText asChild renders the consumer element with id and role merged on", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="email" invalid>
+        <Field.ErrorText asChild>
+          <p data-testid="error">Required.</p>
+        </Field.ErrorText>
+      </Field.Root>,
+    );
+    const error = screen.getByTestId("error");
+
+    // Assert
+    expect(error.tagName).toBe("P");
+    expect(error).toHaveAttribute("id", "email-error");
+    expect(error).toHaveAttribute("role", "alert");
+  });
+});

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

@@ -0,0 +1,104 @@
+import { render, screen } from "@testing-library/react";
+
+import { Field } from "../Field";
+
+describe("Field basic rendering", () => {
+  it("renders a wrapper element with data-field on the root", () => {
+    // Arrange & Act
+    render(<Field.Root data-testid="field" />);
+
+    // Assert
+    const root = screen.getByTestId("field");
+    expect(root.tagName).toBe("DIV");
+    expect(root).toHaveAttribute("data-field", "");
+  });
+
+  it("Field is callable as an alias of Field.Root", () => {
+    // Arrange & Act
+    render(<Field data-testid="field" />);
+
+    // Assert
+    expect(screen.getByTestId("field").tagName).toBe("DIV");
+  });
+
+  it("Field.Label renders a <label> wired to an auto-generated id", () => {
+    // Arrange & Act
+    render(
+      <Field.Root>
+        <Field.Label>Email</Field.Label>
+      </Field.Root>,
+    );
+    const label = screen.getByText("Email");
+
+    // Assert
+    expect(label.tagName).toBe("LABEL");
+    expect(label).toHaveAttribute("for");
+    expect(label.getAttribute("for")).toBeTruthy();
+  });
+
+  it("Field.Label uses a consumer-supplied id on Root", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="email">
+        <Field.Label>Email</Field.Label>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("Email")).toHaveAttribute("for", "email");
+  });
+
+  it("Field.Description renders a <div> with id derived from the field id", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="email">
+        <Field.Description>We won't share it.</Field.Description>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("We won't share it.")).toHaveAttribute(
+      "id",
+      "email-description",
+    );
+  });
+
+  it("Field.ErrorText renders a <div role='alert'> with derived id when invalid", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="email" invalid>
+        <Field.ErrorText>Required.</Field.ErrorText>
+      </Field.Root>,
+    );
+    const error = screen.getByText("Required.");
+
+    // Assert
+    expect(error.tagName).toBe("DIV");
+    expect(error).toHaveAttribute("role", "alert");
+    expect(error).toHaveAttribute("id", "email-error");
+  });
+
+  it("renders children inside the wrapper in source order", () => {
+    // Arrange & Act
+    render(
+      <Field.Root id="email">
+        <Field.Label>Email</Field.Label>
+        <input data-testid="input" />
+        <Field.Description>Hint.</Field.Description>
+      </Field.Root>,
+    );
+    const wrapper = screen.getByText("Email").parentElement;
+
+    // Assert
+    expect(wrapper).toContainElement(screen.getByTestId("input"));
+    expect(wrapper).toContainElement(screen.getByText("Hint."));
+  });
+
+  it("passes className and data-* through on the Root", () => {
+    // Arrange & Act
+    render(<Field.Root className="form-field" data-testid="field" />);
+
+    // Assert
+    expect(screen.getByTestId("field")).toHaveClass("form-field");
+  });
+});