@primitiv-ui/react 0.1.0

package/src/Field/__tests__/Field.state-cascade.test.tsx

@@ -0,0 +1,75 @@
+import { render, screen } from "@testing-library/react";
+
+import { Field } from "../Field";
+
+describe("Field state cascade", () => {
+  it("sets data-field-invalid='' on the root when invalid", () => {
+    // Arrange & Act
+    render(<Field.Root data-testid="field" invalid />);
+
+    // Assert
+    expect(screen.getByTestId("field")).toHaveAttribute(
+      "data-field-invalid",
+      "",
+    );
+  });
+
+  it("sets data-field-disabled='' on the root when disabled", () => {
+    // Arrange & Act
+    render(<Field.Root data-testid="field" disabled />);
+
+    // Assert
+    expect(screen.getByTestId("field")).toHaveAttribute(
+      "data-field-disabled",
+      "",
+    );
+  });
+
+  it("sets data-field-required='' on the root when required", () => {
+    // Arrange & Act
+    render(<Field.Root data-testid="field" required />);
+
+    // Assert
+    expect(screen.getByTestId("field")).toHaveAttribute(
+      "data-field-required",
+      "",
+    );
+  });
+
+  it("does not set state data-* attributes when the corresponding flag is false", () => {
+    // Arrange & Act
+    render(<Field.Root data-testid="field" />);
+    const root = screen.getByTestId("field");
+
+    // Assert
+    expect(root).not.toHaveAttribute("data-field-invalid");
+    expect(root).not.toHaveAttribute("data-field-disabled");
+    expect(root).not.toHaveAttribute("data-field-required");
+  });
+
+  it("Field.ErrorText returns null when invalid=false", () => {
+    // Arrange & Act
+    render(
+      <Field.Root>
+        <Field.ErrorText>You should not see this.</Field.ErrorText>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(
+      screen.queryByText("You should not see this."),
+    ).not.toBeInTheDocument();
+  });
+
+  it("Field.ErrorText renders when invalid=true", () => {
+    // Arrange & Act
+    render(
+      <Field.Root invalid>
+        <Field.ErrorText>Required.</Field.ErrorText>
+      </Field.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("Required.")).toBeInTheDocument();
+  });
+});

package/src/Field/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from "./useFieldContext";
+export * from "./useFieldProps";

package/src/Field/hooks/useFieldContext.ts

@@ -0,0 +1 @@
+export { useFieldContext } from "../FieldContext";

package/src/Field/hooks/useFieldProps.ts

@@ -0,0 +1,57 @@
+import { useContext } from "react";
+
+import { FieldContext } from "../FieldContext";
+
+type FieldAwareProps = {
+  id?: string;
+  "aria-describedby"?: string;
+  "aria-invalid"?:
+    | boolean
+    | "true"
+    | "false"
+    | "grammar"
+    | "spelling"
+    | undefined;
+  disabled?: boolean;
+  required?: boolean;
+};
+
+/**
+ * Merges consumer-supplied props with any {@link FieldContext} available
+ * higher in the tree. Use it inside form controls (Input, Textarea,
+ * Select, …) so they automatically inherit the field's id, aria
+ * wiring, and `disabled` / `required` cascade when nested inside
+ * `<Field.Root>`.
+ *
+ * **Merge rules**
+ * - `id`, `disabled`, `required`, `aria-invalid`: consumer wins; the
+ *   field provides the fallback.
+ * - `aria-describedby`: composes — consumer-supplied ids come first,
+ *   then the field's `descriptionId`, then the `errorId` when invalid.
+ *
+ * When no FieldContext is in scope the consumer props are returned
+ * unchanged, so existing usage outside a `<Field.Root>` is unaffected.
+ */
+export function useFieldProps<P extends FieldAwareProps>(consumerProps: P): P {
+  const field = useContext(FieldContext);
+  if (!field) return consumerProps;
+
+  const composedDescribedBy =
+    [
+      consumerProps["aria-describedby"],
+      field.descriptionId,
+      field.invalid ? field.errorId : null,
+    ]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  return {
+    ...consumerProps,
+    id: consumerProps.id ?? field.id,
+    disabled: consumerProps.disabled ?? field.disabled,
+    required: consumerProps.required ?? field.required,
+    "aria-invalid":
+      consumerProps["aria-invalid"] ?? (field.invalid || undefined),
+    "aria-describedby": composedDescribedBy,
+  };
+}

package/src/Field/index.ts

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

package/src/Field/types.ts

@@ -0,0 +1,33 @@
+import { ComponentProps, ReactNode } from "react";
+
+export type FieldRootProps = ComponentProps<"div"> & {
+  /** Stable id wired to the control via {@link FieldLabel}'s `htmlFor`. Auto-generated via `useId` when omitted. */
+  id?: string;
+  /** Marks the field as invalid; cascades to the control via context. */
+  invalid?: boolean;
+  /** Disables the field; cascades to the control via context. */
+  disabled?: boolean;
+  /** Marks the field as required; cascades to the control via context. */
+  required?: boolean;
+  /** Renders the consumer element instead of `<div>` via Slot. */
+  asChild?: boolean;
+  children?: ReactNode;
+};
+
+export type FieldLabelProps = ComponentProps<"label"> & {
+  /** Renders the consumer element instead of `<label>` via Slot. */
+  asChild?: boolean;
+  children?: ReactNode;
+};
+
+export type FieldDescriptionProps = ComponentProps<"div"> & {
+  /** Renders the consumer element instead of `<div>` via Slot. */
+  asChild?: boolean;
+  children?: ReactNode;
+};
+
+export type FieldErrorTextProps = ComponentProps<"div"> & {
+  /** Renders the consumer element instead of `<div>` via Slot. */
+  asChild?: boolean;
+  children?: ReactNode;
+};

package/src/Fieldset/Fieldset.tsx

@@ -0,0 +1,104 @@
+import { FieldsetLegendProps, FieldsetProps } from "./types";
+
+/**
+ * The root of a Fieldset — renders a native `<fieldset>` element.
+ *
+ * A `<fieldset>` carries an implicit `role="group"` and groups a set of
+ * related form controls (radios, checkboxes, inputs). Pair it with a
+ * {@link FieldsetLegend} so the group is announced with an accessible
+ * name when the user enters any control inside it.
+ *
+ * **Disabled.** Setting `disabled` forwards the native attribute, which
+ * disables *every* form control nested inside the fieldset at once — the
+ * standard way to disable a whole section of a form. It also sets
+ * `data-disabled=""` so CSS can target the state without the `:disabled`
+ * pseudo-class:
+ *
+ * ```css
+ * fieldset[data-disabled] { opacity: 0.5; }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <Fieldset.Root>
+ *   <Fieldset.Legend>Notifications</Fieldset.Legend>
+ *   <label><input type="checkbox" name="email" /> Email</label>
+ *   <label><input type="checkbox" name="sms" /> SMS</label>
+ * </Fieldset.Root>
+ * ```
+ */
+function Fieldset({ disabled, children, ...rest }: FieldsetProps) {
+  return (
+    <fieldset
+      {...rest}
+      disabled={disabled}
+      data-disabled={disabled ? "" : undefined}
+    >
+      {children}
+    </fieldset>
+  );
+}
+
+Fieldset.displayName = "Fieldset";
+
+/**
+ * The caption for a {@link Fieldset} — renders a native `<legend>`.
+ *
+ * The `<legend>` must be the first child of the `<fieldset>`. It supplies
+ * the group's accessible name, so assistive technology announces it when
+ * the user moves focus into any control within the group.
+ *
+ * @example
+ * ```tsx
+ * <Fieldset.Legend>Shipping address</Fieldset.Legend>
+ * ```
+ */
+function FieldsetLegend({ children, ...rest }: FieldsetLegendProps) {
+  return <legend {...rest}>{children}</legend>;
+}
+
+FieldsetLegend.displayName = "FieldsetLegend";
+
+type FieldsetCompound = typeof Fieldset & {
+  Root: typeof Fieldset;
+  Legend: typeof FieldsetLegend;
+};
+
+const FieldsetCompound: FieldsetCompound = Object.assign(Fieldset, {
+  Root: Fieldset,
+  Legend: FieldsetLegend,
+});
+
+/**
+ * Headless, accessible **Fieldset** — a stateless compound component that
+ * groups related form controls, with zero styles.
+ *
+ * `Fieldset` is both callable (an alias of {@link Fieldset | `Fieldset.Root`})
+ * and carries its sub-component as a static property. Prefer the
+ * namespaced form in application code:
+ *
+ * - {@link Fieldset | `Fieldset.Root`} — `<fieldset>`, implicit `role="group"`.
+ * - {@link FieldsetLegend | `Fieldset.Legend`} — `<legend>`, the group's accessible name.
+ *
+ * @example Grouping a set of radios
+ * ```tsx
+ * import { Fieldset } from "@primitiv-ui/react";
+ *
+ * <Fieldset.Root>
+ *   <Fieldset.Legend>Plan</Fieldset.Legend>
+ *   <label><input type="radio" name="plan" value="free" /> Free</label>
+ *   <label><input type="radio" name="plan" value="pro" /> Pro</label>
+ * </Fieldset.Root>
+ * ```
+ *
+ * @example Disabling a whole section
+ * ```tsx
+ * <Fieldset.Root disabled>
+ *   <Fieldset.Legend>Billing</Fieldset.Legend>
+ *   …every nested control is disabled…
+ * </Fieldset.Root>
+ * ```
+ */
+FieldsetCompound.displayName = "Fieldset";
+
+export { FieldsetCompound as Fieldset };

package/src/Fieldset/README.md

@@ -0,0 +1,74 @@
+# Fieldset
+
+A headless, accessible grouping for related form controls — a stateless
+compound component wrapping `<fieldset>` and `<legend>`. Zero styles ship.
+
+```tsx
+import { Fieldset } from "@primitiv-ui/react";
+
+<Fieldset.Root>
+  <Fieldset.Legend>Notifications</Fieldset.Legend>
+  <label><input type="checkbox" name="email" /> Email</label>
+  <label><input type="checkbox" name="sms" /> SMS</label>
+</Fieldset.Root>;
+```
+
+`Fieldset` is both callable (an alias of `Fieldset.Root`) and carries its
+sub-component as a static property.
+
+## Parts
+
+| Part              | Element      | Notes                                                  |
+| ----------------- | ------------ | ------------------------------------------------------ |
+| `Fieldset.Root`   | `<fieldset>` | Implicit `role="group"`; `disabled` styling hook       |
+| `Fieldset.Legend` | `<legend>`   | Supplies the group's accessible name                   |
+
+## Props
+
+### `Fieldset.Root`
+
+| Prop       | Type                         | Default | Notes                                                       |
+| ---------- | ---------------------------- | ------- | ----------------------------------------------------------- |
+| `disabled` | `boolean`                    | —       | Native `disabled` + `data-disabled=""` styling hook         |
+| `...rest`  | `ComponentProps<"fieldset">` | —       | All other `<fieldset>` props (`aria-*`, `data-*`, etc.)     |
+
+### `Fieldset.Legend`
+
+| Prop      | Type                       | Default | Notes                            |
+| --------- | -------------------------- | ------- | -------------------------------- |
+| `...rest` | `ComponentProps<"legend">` | —       | All `<legend>` props             |
+
+## Accessible name
+
+A `<fieldset>` has an implicit `role="group"`. Place a `Fieldset.Legend`
+as the first child so the group is announced with a name — assistive
+technology reads the legend when the user moves focus into any control
+within the group.
+
+```tsx
+<Fieldset.Root>
+  <Fieldset.Legend>Shipping address</Fieldset.Legend>
+  …
+</Fieldset.Root>
+```
+
+## Disabled
+
+Passing `disabled` to `Fieldset.Root` forwards the native `disabled`
+attribute. Natively, this disables **every** form control nested inside
+the fieldset at once — the standard way to disable a whole section of a
+form. It also sets `data-disabled=""` so CSS can target the state
+directly:
+
+```tsx
+<Fieldset.Root disabled>
+  <Fieldset.Legend>Billing</Fieldset.Legend>
+  …every nested control is disabled…
+</Fieldset.Root>
+```
+
+```css
+fieldset[data-disabled] {
+  opacity: 0.5;
+}
+```

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

@@ -0,0 +1,81 @@
+import { render, screen } from "@testing-library/react";
+
+import { Fieldset } from "../Fieldset";
+
+describe("Fieldset basic rendering", () => {
+  it("renders a <fieldset> element with an implicit group role", () => {
+    // Arrange & Act
+    render(<Fieldset.Root />);
+
+    // Assert
+    expect(screen.getByRole("group").tagName).toBe("FIELDSET");
+  });
+
+  it("Fieldset is callable as an alias of Fieldset.Root", () => {
+    // Arrange & Act
+    render(<Fieldset />);
+
+    // Assert
+    expect(screen.getByRole("group").tagName).toBe("FIELDSET");
+  });
+
+  it("renders Fieldset.Legend as a <legend> element", () => {
+    // Arrange & Act
+    render(
+      <Fieldset.Root>
+        <Fieldset.Legend>Shipping address</Fieldset.Legend>
+      </Fieldset.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("Shipping address").tagName).toBe("LEGEND");
+  });
+
+  it("uses the legend as the group's accessible name", () => {
+    // Arrange & Act
+    render(
+      <Fieldset.Root>
+        <Fieldset.Legend>Contact details</Fieldset.Legend>
+      </Fieldset.Root>,
+    );
+
+    // Assert
+    expect(
+      screen.getByRole("group", { name: "Contact details" }),
+    ).toBeInTheDocument();
+  });
+
+  it("renders children inside the fieldset", () => {
+    // Arrange & Act
+    render(
+      <Fieldset.Root>
+        <input data-testid="field" />
+      </Fieldset.Root>,
+    );
+
+    // Assert
+    expect(screen.getByRole("group")).toContainElement(
+      screen.getByTestId("field"),
+    );
+  });
+
+  it("passes through className and data-* attributes on the root", () => {
+    // Arrange & Act
+    render(<Fieldset.Root className="group" data-testid="fs" />);
+
+    // Assert
+    expect(screen.getByTestId("fs")).toHaveClass("group");
+  });
+
+  it("passes through props on the legend", () => {
+    // Arrange & Act
+    render(
+      <Fieldset.Root>
+        <Fieldset.Legend className="group__legend">Billing</Fieldset.Legend>
+      </Fieldset.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("Billing")).toHaveClass("group__legend");
+  });
+});

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

@@ -0,0 +1,41 @@
+import { render, screen } from "@testing-library/react";
+
+import { Fieldset } from "../Fieldset";
+
+describe("Fieldset disabled state", () => {
+  it("sets the native disabled attribute on the fieldset", () => {
+    // Arrange & Act
+    render(<Fieldset.Root disabled />);
+
+    // Assert
+    expect(screen.getByRole("group")).toBeDisabled();
+  });
+
+  it('sets data-disabled="" as a CSS styling hook', () => {
+    // Arrange & Act
+    render(<Fieldset.Root disabled data-testid="fs" />);
+
+    // Assert
+    expect(screen.getByTestId("fs")).toHaveAttribute("data-disabled", "");
+  });
+
+  it("does not set data-disabled when not disabled", () => {
+    // Arrange & Act
+    render(<Fieldset.Root data-testid="fs" />);
+
+    // Assert
+    expect(screen.getByTestId("fs")).not.toHaveAttribute("data-disabled");
+  });
+
+  it("disables form controls nested inside the fieldset", () => {
+    // Arrange & Act
+    render(
+      <Fieldset.Root disabled>
+        <input data-testid="field" />
+      </Fieldset.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("field")).toBeDisabled();
+  });
+});

package/src/Fieldset/index.ts

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

package/src/Fieldset/types.ts

@@ -0,0 +1,5 @@
+import { ComponentProps } from "react";
+
+export type FieldsetProps = ComponentProps<"fieldset">;
+
+export type FieldsetLegendProps = ComponentProps<"legend">;

package/src/Input/Input.tsx

@@ -0,0 +1,120 @@
+import { useFieldProps } from "../Field/hooks";
+import { Slot } from "../Slot";
+import { InputProps } from "./types";
+
+/**
+ * A headless, accessible single-line text input.
+ *
+ * Renders a native `<input>` and passes every standard input attribute
+ * straight through to the DOM — `value` / `defaultValue`, `placeholder`,
+ * `type`, `name`, `required`, `pattern`, `min`, `max`, `step`,
+ * `maxLength`, and so on. No styles ship with the component.
+ *
+ * **Default type.** `type="text"` is set by default. Override with the
+ * `type` prop for any native variant (`"email"`, `"password"`,
+ * `"number"`, `"search"`, `"tel"`, `"url"`, `"date"`, …). Future
+ * composite primitives (`PasswordInput`, `NumberInput`, `DatePicker`)
+ * will layer richer interaction on top of those types.
+ *
+ * **Labelling.** An `<input>` has no implicit accessible name. Pair it
+ * with a `<label>` (`htmlFor` → the input's `id`), or pass `aria-label`
+ * / `aria-labelledby` for the control to be announced correctly.
+ *
+ * **Native validation.** All HTML constraint-validation attributes
+ * (`required`, `pattern`, `min`, `max`, `minLength`, `maxLength`,
+ * `type="email"` / `"url"` / `"number"`) work as the browser intends —
+ * the component does not interfere. CSS can target `input:invalid`
+ * directly; for assistive technology, set `aria-invalid` explicitly
+ * based on your validation state.
+ *
+ * **Form library compatibility.** `ref`, `name`, `onChange`, and
+ * `onBlur` all pass through, so the spread pattern used by
+ * react-hook-form's `register("field")` and similar libraries works
+ * directly:
+ *
+ * ```tsx
+ * <Input {...register("email")} type="email" required />
+ * ```
+ *
+ * **Field integration.** When rendered inside a `<Field.Root>`, Input
+ * opts into `FieldContext` and inherits `id`, `aria-describedby`,
+ * `aria-invalid`, `disabled`, and `required` from the field. Any prop
+ * the consumer passes wins; `aria-describedby` is composed (consumer
+ * ids first, then field-supplied description / error ids). Outside a
+ * `<Field.Root>`, behaviour is unchanged.
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLInputElement`:
+ *
+ * ```tsx
+ * const ref = useRef<HTMLInputElement>(null);
+ * <Input ref={ref} aria-label="Email" />
+ * ```
+ *
+ * **Disabled.** Sets native `disabled` (removing the field from the tab
+ * order and blocking input) plus `data-disabled=""` so CSS can target
+ * `[data-disabled]` without relying on the `:disabled` pseudo-class:
+ *
+ * ```css
+ * input[data-disabled] { opacity: 0.5; cursor: not-allowed; }
+ * ```
+ *
+ * **`asChild` composition.** Renders the consumer's element instead of
+ * `<input>`, merging all props (aria-*, data-*, event handlers, ref)
+ * via the {@link Slot} utility. `type` is **not** forwarded in this
+ * mode — the child element owns its own type semantics.
+ *
+ * **Adornments** live in the separate `InputGroup` primitive — leading
+ * / trailing icons, currency symbols, clear buttons, password-reveal
+ * toggles.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <label htmlFor="email">Email</label>
+ * <Input id="email" type="email" required />
+ * ```
+ *
+ * @example Inside a Field — id, aria-*, disabled, required all wired automatically
+ * ```tsx
+ * <Field.Root invalid={!!errors.email}>
+ *   <Field.Label>Email</Field.Label>
+ *   <Input type="email" {...register("email")} />
+ *   <Field.ErrorText>{errors.email?.message}</Field.ErrorText>
+ * </Field.Root>
+ * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <Input aria-label="Email" disabled />
+ * ```
+ *
+ * @example asChild — wrap a custom input variant
+ * ```tsx
+ * <Input asChild aria-label="Email">
+ *   <MaskedInput mask="email" />
+ * </Input>
+ * ```
+ */
+export function Input({
+  asChild = false,
+  type = "text",
+  children,
+  ref,
+  ...consumer
+}: InputProps) {
+  const merged = useFieldProps(consumer);
+
+  const rootProps = {
+    ...merged,
+    ref,
+    "data-disabled": merged.disabled ? "" : undefined,
+  };
+
+  if (asChild) {
+    return <Slot {...rootProps}>{children}</Slot>;
+  }
+
+  return <input type={type} {...rootProps} />;
+}
+
+Input.displayName = "Input";