@primitiv-ui/react 0.1.28 → 0.1.30

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,16 +5,13 @@ 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"`,
- * `"number"`, `"search"`, `"tel"`, `"url"`, `"date"`, …). Future
+ * `"number"`, `"search"`, `"tel"`, `"url"`, `"date"`, ...). Future
  * composite primitives (`PasswordInput`, `NumberInput`, `DatePicker`)
  * will layer richer interaction on top of those types.
  *
@@ -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>

package/src/Input/README.md

@@ -14,11 +14,11 @@ import { Input } from "@primitiv-ui/react";
 
 | Prop       | Type                       | Default  | Notes                                                          |
 | ---------- | -------------------------- | -------- | -------------------------------------------------------------- |
-| `type`     | `string`                   | `"text"` | Any native `<input>` type (`"email"`, `"password"`, …)         |
+| `type`     | `string`                   | `"text"` | Any native `<input>` type (`"email"`, `"password"`, ...)         |
 | `disabled` | `boolean`                  | —        | Native `disabled` + `data-disabled=""` styling hook            |
 | `asChild`  | `boolean`                  | `false`  | Delegate rendering to the child element via Slot               |
 | `ref`      | `Ref<HTMLInputElement>`    | —        | Forwarded to the underlying input element                      |
-| `...rest`  | `ComponentProps<"input">`  | —        | All other `<input>` props (`value`, `placeholder`, `aria-*`, …) |
+| `...rest`  | `ComponentProps<"input">`  | —        | All other `<input>` props (`value`, `placeholder`, `aria-*`, ...) |
 
 ## Default type
 

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

@@ -115,4 +115,9 @@ describe("Input basic rendering", () => {
     // Assert
     expect(onChange).toHaveBeenCalledTimes(2);
   });
+
+  it('sets displayName to "Input" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(Input.displayName).toBe("Input");
+  });
 });

package/src/Input/types.ts

@@ -1,11 +1,28 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
 /**
- * Props for {@link Input} — all native `<input>` attributes plus the
- * `asChild` escape hatch and a typed `ref`.
+ * Props for {@link Input} — all native `<input>` attributes (with `type`
+ * defaulting to `"text"`) plus the `asChild` escape hatch and a typed `ref`.
  */
 export type InputProps = ComponentProps<"input"> & {
+  /**
+   * Renders the child element instead of a native `<input>`, merging all
+   * props — `aria-*`, `data-*`, event handlers, `ref` — onto it via
+   * {@link Slot}. Event handlers compose (child runs first). `type` is
+   * not forwarded in this mode; the child owns its own type semantics.
+   * See the `asChild` example on {@link Input}.
+   * @default false
+   */
   asChild?: boolean;
+  /**
+   * Forwarded to the underlying `HTMLInputElement`. Under `asChild`,
+   * merged onto the rendered child via {@link Slot}.
+   */
   ref?: Ref<HTMLInputElement>;
+  /**
+   * Under `asChild`, becomes the single child element `Slot` merges props
+   * onto. Not rendered by the native `<input>` path (inputs are void
+   * elements in HTML).
+   */
   children?: ReactNode;
 };

package/src/InputGroup/InputGroup.tsx

@@ -19,6 +19,8 @@ import { InputGroupAdornmentProps, InputGroupRootProps } from "./types";
  * element instead of `<div>` — e.g. a `<label>` so a click anywhere on
  * the frame focuses the wrapped input.
  *
+ * @extends HTMLDivElement
+ *
  * @example Basic frame with no adornments
  * ```tsx
  * <InputGroup>
@@ -56,6 +58,7 @@ export function InputGroupRoot({
 }
 
 /** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 InputGroupRoot.displayName = "InputGroupRoot";
 
 /**
@@ -76,6 +79,8 @@ InputGroupRoot.displayName = "InputGroupRoot";
  * search, opens a colour picker, or any other action. Event handlers
  * compose (child runs first); refs forward to the consumer element.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Decorative leading icon
  * ```tsx
  * <InputGroup.LeadingAdornment>
@@ -131,6 +136,8 @@ InputGroupLeadingAdornment.displayName = "InputGroupLeadingAdornment";
  * element such as `<button>`. Event handlers compose (child runs
  * first); refs forward to the consumer element.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Trailing clear button via asChild
  * ```tsx
  * <InputGroup.TrailingAdornment asChild>
@@ -191,9 +198,10 @@ export type TInputGroupCompound = typeof InputGroupRoot & {
  *   trailing slot, `data-input-group-adornment="trailing"`.
  *
  * **State coordination.** None. CSS handles disabled / invalid /
- * focus-within styling via `:has()` and `:focus-within`. When `Field`
- * lands it will sit *outside* `InputGroup` and own label / error /
- * description wiring without InputGroup needing to change.
+ * focus-within styling via `:has()` and `:focus-within`. {@link Field}
+ * sits *outside* `InputGroup` and owns the label / error / description
+ * wiring, so the two compose without `InputGroup` needing to know about
+ * it — wrap the `Input` in an `InputGroup` inside a `Field.Root`.
  *
  * @example Leading search icon
  * ```tsx

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

@@ -103,4 +103,18 @@ describe("InputGroup basic rendering", () => {
     expect(screen.getByTestId("lead")).toHaveClass("lead");
     expect(screen.getByTestId("trail")).toHaveClass("trail");
   });
+
+  it("sets a displayName on the compound and each adornment", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `InputGroup`, `InputGroup.Root`, and the underlying function are one
+    // object (Object.assign compound), so the compound's "InputGroup" alias is
+    // the observable Root displayName; the adornments are distinct objects.
+    expect(InputGroup.displayName).toBe("InputGroup");
+    expect(InputGroup.LeadingAdornment.displayName).toBe(
+      "InputGroupLeadingAdornment",
+    );
+    expect(InputGroup.TrailingAdornment.displayName).toBe(
+      "InputGroupTrailingAdornment",
+    );
+  });
 });

package/src/InputGroup/types.ts

@@ -1,22 +1,43 @@
 import { ComponentProps, ReactNode, Ref } from "react";
 
 /**
- * Props for {@link InputGroup.Root} — all `<div>` attributes plus the
- * `asChild` escape hatch and a typed `ref`.
+ * Props for {@link InputGroupRoot | `InputGroup.Root`} — the frame
+ * wrapper. Extends the native `<div>` attributes plus the `asChild`
+ * escape hatch and a typed `ref`.
  */
 export type InputGroupRootProps = ComponentProps<"div"> & {
+  /** Render the consumer's element instead of `<div>` via the
+   * {@link Slot} pattern — e.g. a `<label>` so the whole frame is
+   * clickable. The `data-input-group` hook is preserved.
+   * @default false */
   asChild?: boolean;
+  /** Forwarded to the underlying `HTMLDivElement` (or the `asChild`
+   * element). */
   ref?: Ref<HTMLDivElement>;
+  /** The wrapped control and its optional leading / trailing
+   * adornments. */
   children?: ReactNode;
 };
 
 /**
- * Props for {@link InputGroup.LeadingAdornment} and
- * {@link InputGroup.TrailingAdornment} — all `<span>` attributes plus the
- * `asChild` escape hatch and a typed `ref`.
+ * Props shared by
+ * {@link InputGroupLeadingAdornment | `InputGroup.LeadingAdornment`} and
+ * {@link InputGroupTrailingAdornment | `InputGroup.TrailingAdornment`} —
+ * the positioned adornment slots. Extends the native `<span>` attributes
+ * plus the `asChild` escape hatch and a typed `ref`.
  */
 export type InputGroupAdornmentProps = ComponentProps<"span"> & {
+  /** Render the consumer's element instead of `<span>` via the
+   * {@link Slot} pattern — e.g. an interactive `<button>`. Event
+   * handlers compose (child runs first) and the `data-input-group-adornment`
+   * hook is preserved.
+   * @default false */
   asChild?: boolean;
+  /** Forwarded to the underlying `HTMLSpanElement` (or the `asChild`
+   * element). */
   ref?: Ref<HTMLSpanElement>;
+  /** The adornment content — a decorative icon (mark it
+   * `aria-hidden="true"`), suffix text, or an interactive control with an
+   * accessible name. */
   children?: ReactNode;
 };