@primitiv-ui/react 0.1.27 → 0.1.29

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

@@ -13,7 +13,7 @@ describe("EmptyState.Title component", () => {
 
   it("should render the consumer element with asChild", () => {
     // Arrange
-    render(
+    const { container } = render(
       <EmptyState.Title asChild>
         <h2>No results found</h2>
       </EmptyState.Title>,
@@ -22,5 +22,7 @@ describe("EmptyState.Title component", () => {
     // Assert
     const title = screen.getByRole("heading", { name: "No results found" });
     expect(title.tagName).toBe("H2");
+    // Slot renders the child in place — no default <p> wrapper around it.
+    expect(container.querySelector("p")).toBeNull();
   });
 });

package/src/EmptyState/types.ts

@@ -2,21 +2,64 @@ import { ComponentProps } from "react";
 
 /** Mixin adding the `asChild` opt-in to a sub-component's props. */
 export type WithAsChild = {
-  /** Render the consumer's own element instead of the default, via `Slot`. */
+  /**
+   * 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 EmptyState.Root} — all `<div>` props plus `asChild`. */
+/**
+ * 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 EmptyState.Media} — all `<div>` props plus `asChild`. */
+/**
+ * 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 EmptyState.Title} — all `<p>` props plus `asChild`. */
+/**
+ * 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 EmptyState.Description} — all `<p>` props plus `asChild`. */
+/**
+ * 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 EmptyState.Actions} — all `<div>` props plus `asChild`. */
+/**
+ * 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

@@ -36,6 +36,12 @@ import {
  * `<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}>
@@ -85,6 +91,7 @@ export function FieldRoot({
 }
 
 /** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 FieldRoot.displayName = "FieldRoot";
 
 /**
@@ -95,6 +102,13 @@ FieldRoot.displayName = "FieldRoot";
  * 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,
@@ -123,6 +137,13 @@ FieldLabel.displayName = "FieldLabel";
  * `<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,
@@ -150,6 +171,8 @@ FieldDescription.displayName = "FieldDescription";
  * **`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}>

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

@@ -101,4 +101,15 @@ describe("Field basic rendering", () => {
     // Assert
     expect(screen.getByTestId("field")).toHaveClass("form-field");
   });
+
+  it("sets a displayName on the compound and each sub-component", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `Field`, `Field.Root`, and the underlying function are one object
+    // (Object.assign compound), so the compound's "Field" alias is the
+    // observable Root displayName; the sub-components are distinct objects.
+    expect(Field.displayName).toBe("Field");
+    expect(Field.Label.displayName).toBe("FieldLabel");
+    expect(Field.Description.displayName).toBe("FieldDescription");
+    expect(Field.ErrorText.displayName).toBe("FieldErrorText");
+  });
 });

package/src/Field/__tests__/Field.error-handling.test.tsx

@@ -0,0 +1,23 @@
+import { render } from "@testing-library/react";
+
+import { Field } from "../Field";
+import { FieldContext } from "../FieldContext";
+
+describe("Field error handling", () => {
+  it("throws a helpful error when a sub-component is rendered outside Root", () => {
+    // Arrange
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Assert
+    expect(() => render(<Field.Label>Email</Field.Label>)).toThrow(
+      /Field sub-components must be rendered inside a <Field\.Root>/,
+    );
+
+    error.mockRestore();
+  });
+
+  it("names the context for React DevTools", () => {
+    // Assert — an empty displayName would render the provider as anonymous.
+    expect(FieldContext.displayName).toBe("FieldContext");
+  });
+});

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

@@ -72,4 +72,25 @@ describe("Field state cascade", () => {
     // Assert
     expect(screen.getByText("Required.")).toBeInTheDocument();
   });
+
+  it("re-derives the cascaded context when a flag changes after mount", () => {
+    // Arrange — a valid field: the error is gated off.
+    const { rerender } = render(
+      <Field.Root>
+        <Field.ErrorText>Required.</Field.ErrorText>
+      </Field.Root>,
+    );
+    expect(screen.queryByText("Required.")).not.toBeInTheDocument();
+
+    // Act — flip to invalid; the memoised context value must recompute.
+    rerender(
+      <Field.Root invalid>
+        <Field.ErrorText>Required.</Field.ErrorText>
+      </Field.Root>,
+    );
+
+    // Assert — a frozen memo (empty dependency array) would leave the error
+    // gated off; the recomputed context reveals it.
+    expect(screen.getByText("Required.")).toBeInTheDocument();
+  });
 });

package/src/Field/hooks/__tests__/useFieldProps.test.tsx

@@ -5,20 +5,26 @@ import { useFieldProps } from "../useFieldProps";
 
 /**
  * `useFieldProps` is a reusable hook that reads {@link FieldContext} directly,
- * so it is exercised here against a hand-built provider value rather than the
- * full `Field.Root`. `Field.Root` always supplies a truthy `descriptionId`,
- * which means its defensive "nothing to describe" fallback is only reachable
- * through a custom provider like the one below.
+ * so it is exercised here against a hand-built provider value (and, for the
+ * no-context path, no provider at all) rather than the full `Field.Root` —
+ * always through a real component that consumes it. `Field.Root` always
+ * supplies a truthy `descriptionId`, so its defensive "nothing to describe"
+ * fallback is only reachable through a custom provider like the one below.
  */
-function Probe(props: { "aria-describedby"?: string }) {
+type ProbeProps = {
+  id?: string;
+  disabled?: boolean;
+  required?: boolean;
+  "aria-invalid"?: boolean | "true" | "false";
+  "aria-describedby"?: string;
+};
+
+function Probe(props: ProbeProps) {
   const merged = useFieldProps(props);
   return <input data-testid="probe" {...merged} />;
 }
 
-function renderInField(
-  field: Partial<FieldContextValue>,
-  props: { "aria-describedby"?: string } = {},
-) {
+function renderInField(field: Partial<FieldContextValue>, props: ProbeProps = {}) {
   const value: FieldContextValue = {
     id: "f",
     descriptionId: "",
@@ -35,6 +41,80 @@ function renderInField(
   );
 }
 
+describe("useFieldProps without a FieldContext", () => {
+  it("returns the consumer props unchanged when no provider is in scope", () => {
+    // Arrange & Act — no <FieldContext.Provider>: the early guard must fire.
+    render(<Probe id="consumer-id" aria-invalid="true" />);
+    const probe = screen.getByTestId("probe");
+
+    // Assert — consumer props survive untouched and no field wiring is added.
+    expect(probe).toHaveAttribute("id", "consumer-id");
+    expect(probe).toHaveAttribute("aria-invalid", "true");
+    expect(probe).not.toHaveAttribute("aria-describedby");
+  });
+});
+
+describe("useFieldProps inheriting from the field", () => {
+  it("adopts the field's id, disabled, required, and invalid state when the consumer omits them", () => {
+    // Arrange & Act
+    renderInField(
+      {
+        id: "field-id",
+        descriptionId: "field-desc",
+        errorId: "field-err",
+        invalid: true,
+        disabled: true,
+        required: true,
+      },
+      {},
+    );
+    const probe = screen.getByTestId("probe");
+
+    // Assert — every value falls back to the field.
+    expect(probe).toHaveAttribute("id", "field-id");
+    expect(probe).toBeDisabled();
+    expect(probe).toBeRequired();
+    expect(probe).toHaveAttribute("aria-invalid", "true");
+    expect(probe).toHaveAttribute("aria-describedby", "field-desc field-err");
+  });
+
+  it("omits aria-invalid entirely when the field is valid and the consumer is silent", () => {
+    // Arrange & Act
+    renderInField({ invalid: false }, {});
+
+    // Assert — a valid field contributes no aria-invalid, so the attribute is
+    // absent rather than rendered as aria-invalid="false".
+    expect(screen.getByTestId("probe")).not.toHaveAttribute("aria-invalid");
+  });
+});
+
+describe("useFieldProps with consumer overrides", () => {
+  it("lets consumer id, disabled, required, and aria-invalid win over the field", () => {
+    // Arrange & Act — field would contribute the opposite of each override.
+    renderInField(
+      {
+        id: "field-id",
+        invalid: false,
+        disabled: false,
+        required: false,
+      },
+      {
+        id: "consumer-id",
+        disabled: true,
+        required: true,
+        "aria-invalid": "true",
+      },
+    );
+    const probe = screen.getByTestId("probe");
+
+    // Assert — the consumer's explicit values are preserved.
+    expect(probe).toHaveAttribute("id", "consumer-id");
+    expect(probe).toBeDisabled();
+    expect(probe).toBeRequired();
+    expect(probe).toHaveAttribute("aria-invalid", "true");
+  });
+});
+
 describe("useFieldProps aria-describedby composition", () => {
   it("omits aria-describedby entirely when nothing contributes an id", () => {
     // Arrange & Act — empty description/error ids, not invalid, no consumer id.
@@ -44,4 +124,19 @@ describe("useFieldProps aria-describedby composition", () => {
     // rather than rendered as aria-describedby="".
     expect(screen.getByTestId("probe")).not.toHaveAttribute("aria-describedby");
   });
+
+  it("prepends the consumer's ids ahead of the field's, space-separated", () => {
+    // Arrange & Act — a valid field so the errorId does not join in.
+    renderInField(
+      { descriptionId: "field-desc", errorId: "field-err", invalid: false },
+      { "aria-describedby": "consumer-desc" },
+    );
+
+    // Assert — consumer id first, then the field's descriptionId; the errorId is
+    // excluded while valid.
+    expect(screen.getByTestId("probe")).toHaveAttribute(
+      "aria-describedby",
+      "consumer-desc field-desc",
+    );
+  });
 });

package/src/Field/types.ts

@@ -1,37 +1,85 @@
 import { ComponentProps, ReactNode } from "react";
 
-/** Props for `Field.Root`, the wrapper that owns shared field state. */
+/**
+ * Props for {@link FieldRoot | `Field.Root`} — the wrapper that owns the
+ * shared field id, derived `descriptionId` / `errorId`, and the
+ * `invalid` / `disabled` / `required` cascade. Extends the native
+ * `<div>` props; `id` is redeclared purely to document its role as the
+ * field-wide id (its type is unchanged from the native attribute).
+ */
 export type FieldRootProps = ComponentProps<"div"> & {
-  /** Stable id wired to the control via {@link FieldLabel}'s `htmlFor`. Auto-generated via `useId` when omitted. */
+  /** Stable id for the field. Wired to the control via
+   * {@link FieldLabel | `Field.Label`}'s `htmlFor`, and used to derive
+   * the `descriptionId` (`<id>-description`) and `errorId`
+   * (`<id>-error`) exposed through {@link FieldContext}. Auto-generated
+   * via React's `useId` when omitted. */
   id?: string;
-  /** Marks the field as invalid; cascades to the control via context. */
+  /** Marks the field invalid. Cascades to a context-aware control (e.g.
+   * `Input`) as `aria-invalid`, sets `data-field-invalid` on the
+   * wrapper, and gates {@link FieldErrorText | `Field.ErrorText`}
+   * rendering.
+   * @default false */
   invalid?: boolean;
-  /** Disables the field; cascades to the control via context. */
+  /** Disables the field. Cascades to the control's `disabled` prop and
+   * sets `data-field-disabled` on the wrapper.
+   * @default false */
   disabled?: boolean;
-  /** Marks the field as required; cascades to the control via context. */
+  /** Marks the field required. Cascades to the control's `required` prop
+   * and sets `data-field-required` on the wrapper.
+   * @default false */
   required?: boolean;
-  /** Renders the consumer element instead of `<div>` via Slot. */
+  /** Render the consumer's element instead of `<div>` via the
+   * {@link Slot} pattern — e.g. a semantic `<fieldset>`. The
+   * `data-field-*` hooks and context provider are preserved.
+   * @default false */
   asChild?: boolean;
+  /** The label, control, description, and error sub-components composed
+   * inside the field. */
   children?: ReactNode;
 };
 
-/** Props for `Field.Label`, the field's `<label>`. */
+/**
+ * Props for {@link FieldLabel | `Field.Label`} — the field's `<label>`,
+ * wired to the field id via `htmlFor`. Extends the native `<label>`
+ * props.
+ */
 export type FieldLabelProps = ComponentProps<"label"> & {
-  /** Renders the consumer element instead of `<label>` via Slot. */
+  /** Render the consumer's element instead of `<label>` via the
+   * {@link Slot} pattern, with `htmlFor` merged on.
+   * @default false */
   asChild?: boolean;
+  /** The label text. */
   children?: ReactNode;
 };
 
-/** Props for `Field.Description`, the field's supporting helper text. */
+/**
+ * Props for {@link FieldDescription | `Field.Description`} — the field's
+ * supporting helper text, carrying the field's `descriptionId` so a
+ * context-aware control can reference it via `aria-describedby`. Extends
+ * the native `<div>` props.
+ */
 export type FieldDescriptionProps = ComponentProps<"div"> & {
-  /** Renders the consumer element instead of `<div>` via Slot. */
+  /** Render the consumer's element instead of `<div>` via the
+   * {@link Slot} pattern (e.g. a `<p>` or `<span>`), with the derived
+   * `id` merged on.
+   * @default false */
   asChild?: boolean;
+  /** The helper text. */
   children?: ReactNode;
 };
 
-/** Props for `Field.ErrorText`, the error message shown when invalid. */
+/**
+ * Props for {@link FieldErrorText | `Field.ErrorText`} — the error
+ * message shown only when the field is
+ * {@link FieldRootProps.invalid | invalid}. Renders `role="alert"` and
+ * carries the field's `errorId`. Extends the native `<div>` props.
+ */
 export type FieldErrorTextProps = ComponentProps<"div"> & {
-  /** Renders the consumer element instead of `<div>` via Slot. */
+  /** Render the consumer's element instead of `<div>` via the
+   * {@link Slot} pattern, with the derived `id` and `role="alert"`
+   * merged on.
+   * @default false */
   asChild?: boolean;
+  /** The error message. */
   children?: ReactNode;
 };

package/src/Fieldset/Fieldset.tsx

@@ -3,24 +3,37 @@ import type { ReactElement } from "react";
 import { FieldsetLegendProps, FieldsetProps } from "./types";
 
 /**
- * The root of a Fieldset — renders a native `<fieldset>` element.
+ * The root of a Fieldset — renders a native `<fieldset>` element with an
+ * implicit `role="group"`.
  *
- * 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.
+ * Groups a set of related form controls (radios, checkboxes, inputs). Pair
+ * it with a {@link FieldsetLegend} as the first child so the group is
+ * announced with an accessible name when the user moves focus into 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:
+ * **Styling hooks.** `data-disabled=""` is set when the `disabled` prop is
+ * truthy (omitted otherwise), so CSS can target the state without relying
+ * on the `:disabled` pseudo-class:
  *
  * ```css
- * fieldset[data-disabled] { opacity: 0.5; }
+ * fieldset[data-disabled] { opacity: 0.5; cursor: not-allowed; }
  * ```
  *
- * @example
+ * **Disabled.** Forwarding the native `disabled` attribute disables *every*
+ * form control nested inside the fieldset at once — the standard way to
+ * disable a whole section of a form.
+ *
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLFieldSetElement` directly:
+ *
+ * ```tsx
+ * const ref = useRef<HTMLFieldSetElement>(null);
+ * <Fieldset.Root ref={ref}>…</Fieldset.Root>
+ * ```
+ *
+ * @extends HTMLFieldSetElement
+ *
+ * @example Basic grouping
  * ```tsx
  * <Fieldset.Root>
  *   <Fieldset.Legend>Notifications</Fieldset.Legend>
@@ -28,6 +41,14 @@ import { FieldsetLegendProps, FieldsetProps } from "./types";
  *   <label><input type="checkbox" name="sms" /> SMS</label>
  * </Fieldset.Root>
  * ```
+ *
+ * @example Disabled section
+ * ```tsx
+ * <Fieldset.Root disabled>
+ *   <Fieldset.Legend>Billing</Fieldset.Legend>
+ *   …every nested control is disabled…
+ * </Fieldset.Root>
+ * ```
  */
 export function FieldsetRoot({
   disabled,
@@ -46,14 +67,26 @@ export function FieldsetRoot({
 }
 
 /** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 FieldsetRoot.displayName = "Fieldset";
 
 /**
- * The caption for a {@link Fieldset} — renders a native `<legend>`.
+ * The caption for a {@link FieldsetRoot | `Fieldset.Root`} — renders a
+ * native `<legend>`.
+ *
+ * Must be the **first child** of the `<fieldset>`. It supplies the group's
+ * accessible name; assistive technology announces it when the user moves
+ * focus into any control within the group.
  *
- * 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.
+ * **Ref forwarding.** Pass a `ref` prop to access the underlying
+ * `HTMLLegendElement` directly:
+ *
+ * ```tsx
+ * const ref = useRef<HTMLLegendElement>(null);
+ * <Fieldset.Legend ref={ref}>Address</Fieldset.Legend>
+ * ```
+ *
+ * @extends HTMLLegendElement
  *
  * @example
  * ```tsx
@@ -83,11 +116,11 @@ export type FieldsetCompound = typeof FieldsetRoot & {
  * 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`})
+ * `Fieldset` is both callable (an alias of {@link FieldsetRoot | `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 FieldsetRoot | `Fieldset.Root`} — `<fieldset>`, implicit `role="group"`.
  * - {@link FieldsetLegend | `Fieldset.Legend`} — `<legend>`, the group's accessible name.
  *
  * @example Grouping a set of radios
@@ -108,6 +141,9 @@ export type FieldsetCompound = typeof FieldsetRoot & {
  *   …every nested control is disabled…
  * </Fieldset.Root>
  * ```
+ *
+ * @see {@link FieldsetRoot} for the `disabled` prop and `data-disabled` styling hook.
+ * @see {@link FieldsetLegend} for accessible name requirements.
  */
 const FieldsetCompound: FieldsetCompound = Object.assign(FieldsetRoot, {
   Root: FieldsetRoot,

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

@@ -78,4 +78,13 @@ describe("Fieldset basic rendering", () => {
     // Assert
     expect(screen.getByText("Billing")).toHaveClass("group__legend");
   });
+
+  it("sets a displayName on the compound and Legend", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `Fieldset`, `Fieldset.Root`, and the underlying function are one object
+    // (Object.assign compound), so the compound's "Fieldset" alias is the
+    // observable Root displayName; Legend is a distinct object.
+    expect(Fieldset.displayName).toBe("Fieldset");
+    expect(Fieldset.Legend.displayName).toBe("FieldsetLegend");
+  });
 });

package/src/Fieldset/types.ts

@@ -1,7 +1,25 @@
 import { ComponentProps } from "react";
 
-/** Props for `Fieldset.Root` — the native `<fieldset>` attributes. */
+/**
+ * Props for {@link FieldsetRoot | `Fieldset.Root`} — all native `<fieldset>`
+ * attributes plus the `data-disabled` styling hook.
+ *
+ * No custom props narrow any native attribute, so the full `ComponentProps<"fieldset">`
+ * surface is passed through unchanged, including `ref` (forwarded to the
+ * underlying `HTMLFieldSetElement`).
+ *
+ * The one behaviour addition over a bare `<fieldset>` is `data-disabled=""`:
+ * when `disabled` is truthy the component sets this attribute alongside the
+ * native `disabled`, so CSS can target `[data-disabled]` without relying on
+ * the `:disabled` pseudo-class.
+ */
 export type FieldsetProps = ComponentProps<"fieldset">;
 
-/** Props for `Fieldset.Legend` — the native `<legend>` attributes. */
+/**
+ * Props for {@link FieldsetLegend | `Fieldset.Legend`} — all native `<legend>`
+ * attributes, including `ref` (forwarded to the underlying `HTMLLegendElement`).
+ *
+ * `<legend>` has no interactive state, so no additional `data-*` attributes
+ * are emitted beyond what is passed explicitly by the consumer.
+ */
 export type FieldsetLegendProps = ComponentProps<"legend">;

package/src/Input/Input.tsx

@@ -5,12 +5,9 @@ import { Slot } from "../Slot/index.ts";
 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.
+ * A headless, accessible single-line text input. Renders a native
+ * `<input>` element and passes every standard attribute straight through
+ * to the DOM. 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"`,
@@ -45,6 +42,11 @@ import { InputProps } from "./types";
  * ids first, then field-supplied description / error ids). Outside a
  * `<Field.Root>`, behaviour is unchanged.
  *
+ * **Styling hooks.**
+ * - `data-disabled=""` — present when `disabled` is `true`; absent
+ *   otherwise. Lets CSS target `[data-disabled]` without depending on
+ *   the `:disabled` pseudo-class.
+ *
  * **Ref forwarding.** Pass a `ref` prop to access the underlying
  * `HTMLInputElement`:
  *
@@ -62,14 +64,17 @@ import { InputProps } from "./types";
  * ```
  *
  * **`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.
+ * `<input>`, 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.
  *
  * **Adornments** live in the separate `InputGroup` primitive — leading
  * / trailing icons, currency symbols, clear buttons, password-reveal
  * toggles.
  *
+ * @extends HTMLInputElement
+ *
  * @example Basic usage
  * ```tsx
  * <label htmlFor="email">Email</label>