@primitiv-ui/react 0.1.38 → 0.1.40

package/src/EmptyState/types.ts

@@ -1,65 +0,0 @@
-import { ComponentProps } from "react";
-
-/** Mixin adding the `asChild` opt-in to a sub-component's props. */
-export type WithAsChild = {
-  /**
-   * When `true`, renders the consumer's own element instead of the
-   * sub-component's default host element, merging all props (aria-*, data-*,
-   * event handlers) onto it via the `Slot` utility. The child must be a single
-   * React element. For `EmptyState.Root` and `EmptyState.Media`, the implicit
-   * `role="status"` / `aria-hidden="true"` are also forwarded through `Slot`.
-   * @default false
-   */
-  asChild?: boolean;
-};
-
-/**
- * Props for {@link EmptyStateRoot | `EmptyState.Root`} — all native `<div>`
- * attributes plus the `asChild` escape hatch.
- *
- * The root renders `role="status"` by default, creating a polite ARIA live
- * region. Override with `role={undefined}` for a static empty state that has
- * nothing to announce on appearance.
- */
-export type EmptyStateRootProps = ComponentProps<"div"> & WithAsChild;
-
-/**
- * Props for {@link EmptyStateMedia | `EmptyState.Media`} — all native `<div>`
- * attributes plus the `asChild` escape hatch.
- *
- * The media wrapper renders `aria-hidden="true"` by default, hiding decorative
- * artwork from assistive technology. Pass `aria-hidden={false}` and provide an
- * accessible name when the artwork is genuinely informative.
- */
-export type EmptyStateMediaProps = ComponentProps<"div"> & WithAsChild;
-
-/**
- * Props for {@link EmptyStateTitle | `EmptyState.Title`} — all native `<p>`
- * attributes plus the `asChild` escape hatch.
- *
- * Renders a `<p>` by default. Use `asChild` to substitute a heading element
- * (`<h2>`, `<h3>`, etc.) when the empty state stands in for a titled section
- * and needs to participate in the document's heading hierarchy.
- */
-export type EmptyStateTitleProps = ComponentProps<"p"> & WithAsChild;
-
-/**
- * Props for {@link EmptyStateDescription | `EmptyState.Description`} — all
- * native `<p>` attributes plus the `asChild` escape hatch.
- *
- * Renders a `<p>` for secondary supporting copy that explains the situation or
- * suggests a next step. Actionable controls belong in
- * {@link EmptyStateActionsProps | `EmptyState.Actions`} rather than here.
- */
-export type EmptyStateDescriptionProps = ComponentProps<"p"> & WithAsChild;
-
-/**
- * Props for {@link EmptyStateActions | `EmptyState.Actions`} — all native
- * `<div>` attributes plus the `asChild` escape hatch.
- *
- * Renders a plain `<div>` with no ARIA role of its own, so buttons and links
- * placed inside it retain their native semantics. The element is a child of the
- * `role="status"` live region, so its text content is included in the
- * announcement.
- */
-export type EmptyStateActionsProps = ComponentProps<"div"> & WithAsChild;

package/src/Field/Field.tsx

@@ -1,276 +0,0 @@
-import { useId, useMemo } from "react";
-import type { ReactElement } from "react";
-
-import { Slot } from "../Slot/index.ts";
-import { FieldContext } from "./FieldContext";
-import { useFieldContext } from "./hooks/index.ts";
-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.
- *
- * **Styling hooks.** `data-field=""` always; `data-field-invalid` /
- * `data-field-disabled` / `data-field-required` present (empty string)
- * only when the corresponding flag is truthy.
- *
- * @extends HTMLDivElement
- *
- * @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>
- * ```
- */
-export function FieldRoot({
-  id: idProp,
-  invalid = false,
-  disabled = false,
-  required = false,
-  asChild = false,
-  children,
-  ...rest
-}: FieldRootProps): ReactElement {
-  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>
-  );
-}
-
-/** @internal */
-// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
-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>`.
- *
- * @extends HTMLLabelElement
- *
- * @example
- * ```tsx
- * <Field.Label>Email address</Field.Label>
- * ```
- */
-export function FieldLabel({
-  asChild = false,
-  children,
-  ...rest
-}: FieldLabelProps): ReactElement {
-  const { id } = useFieldContext();
-  const labelProps = { ...rest, htmlFor: id };
-
-  if (asChild) {
-    return <Slot {...labelProps}>{children}</Slot>;
-  }
-  return <label {...labelProps}>{children}</label>;
-}
-
-/** @internal */
-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>`.
- *
- * @extends HTMLDivElement
- *
- * @example
- * ```tsx
- * <Field.Description>We'll only use this to sign you in.</Field.Description>
- * ```
- */
-export function FieldDescription({
-  asChild = false,
-  children,
-  ...rest
-}: FieldDescriptionProps): ReactElement {
-  const { descriptionId } = useFieldContext();
-  const descriptionProps = { ...rest, id: descriptionId };
-
-  if (asChild) {
-    return <Slot {...descriptionProps}>{children}</Slot>;
-  }
-  return <div {...descriptionProps}>{children}</div>;
-}
-
-/** @internal */
-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.
- *
- * @extends HTMLDivElement
- *
- * @example
- * ```tsx
- * <Field.Root invalid={!!errors.email}>
- *   <Field.ErrorText>{errors.email?.message ?? "Required"}</Field.ErrorText>
- * </Field.Root>
- * ```
- *
- * @throws If rendered outside a `<Field.Root>`.
- */
-export function FieldErrorText({
-  asChild = false,
-  children,
-  ...rest
-}: FieldErrorTextProps): ReactElement | null {
-  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>;
-}
-
-/** @internal */
-FieldErrorText.displayName = "FieldErrorText";
-
-/** Type of the {@link Field} compound — the Root callable plus its sub-components. */
-export type TFieldCompound = typeof FieldRoot & {
-  /** The wrapper that owns shared field state and context. */
-  Root: typeof FieldRoot;
-  /** The field's label. */
-  Label: typeof FieldLabel;
-  /** The field's supporting helper text. */
-  Description: typeof FieldDescription;
-  /** The error message shown when invalid. */
-  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

@@ -1,22 +0,0 @@
-import { createStrictContext } from "../utils/index.ts";
-
-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

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

@@ -1,83 +0,0 @@
-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");
-  });
-});