@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/Field/Field.d.ts

@@ -0,0 +1,178 @@
+import type { ReactElement } from "react";
+import { FieldDescriptionProps, FieldErrorTextProps, FieldLabelProps, FieldRootProps } from "./types.js";
+/**
+ * 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 declare function FieldRoot({ id: idProp, invalid, disabled, required, asChild, children, ...rest }: FieldRootProps): ReactElement;
+export declare namespace FieldRoot {
+    var displayName: string;
+}
+/**
+ * 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 declare function FieldLabel({ asChild, children, ...rest }: FieldLabelProps): ReactElement;
+export declare namespace FieldLabel {
+    var displayName: string;
+}
+/**
+ * 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 declare function FieldDescription({ asChild, children, ...rest }: FieldDescriptionProps): ReactElement;
+export declare namespace FieldDescription {
+    var displayName: string;
+}
+/**
+ * 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 declare function FieldErrorText({ asChild, children, ...rest }: FieldErrorTextProps): ReactElement | null;
+export declare namespace FieldErrorText {
+    var displayName: string;
+}
+/** 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.
+ */
+declare const FieldCompound: TFieldCompound;
+export { FieldCompound as Field };

package/dist/Field/Field.js

@@ -0,0 +1,211 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useId, useMemo } from "react";
+import { Slot } from "../Slot/index.js";
+import { FieldContext } from "./FieldContext.js";
+import { useFieldContext } from "./hooks/index.js";
+/**
+ * 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 }) {
+    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 (_jsx(FieldContext.Provider, { value: value, children: asChild ? (_jsx(Slot, { ...rootProps, children: children })) : (_jsx("div", { ...rootProps, children: children })) }));
+}
+/** @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 }) {
+    const { id } = useFieldContext();
+    const labelProps = { ...rest, htmlFor: id };
+    if (asChild) {
+        return _jsx(Slot, { ...labelProps, children: children });
+    }
+    return _jsx("label", { ...labelProps, children: children });
+}
+/** @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 }) {
+    const { descriptionId } = useFieldContext();
+    const descriptionProps = { ...rest, id: descriptionId };
+    if (asChild) {
+        return _jsx(Slot, { ...descriptionProps, children: children });
+    }
+    return _jsx("div", { ...descriptionProps, children: children });
+}
+/** @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 }) {
+    const { errorId, invalid } = useFieldContext();
+    if (!invalid)
+        return null;
+    const errorProps = { ...rest, id: errorId, role: "alert" };
+    if (asChild) {
+        return _jsx(Slot, { ...errorProps, children: children });
+    }
+    return _jsx("div", { ...errorProps, children: children });
+}
+/** @internal */
+FieldErrorText.displayName = "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 = Object.assign(FieldRoot, {
+    Root: FieldRoot,
+    Label: FieldLabel,
+    Description: FieldDescription,
+    ErrorText: FieldErrorText,
+});
+FieldCompound.displayName = "Field";
+export { FieldCompound as Field };

package/dist/Field/FieldContext.d.ts

@@ -0,0 +1,15 @@
+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 declare const FieldContext: import("react").Context<FieldContextValue | null>, useFieldContext: () => FieldContextValue;

package/dist/Field/FieldContext.js

@@ -0,0 +1,3 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+export const [FieldContext, useFieldContext] = createStrictContext("Field sub-components must be rendered inside a <Field.Root>.", "FieldContext");

package/dist/Field/hooks/index.d.ts

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

package/dist/Field/hooks/index.js

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

package/dist/Field/hooks/useFieldContext.d.ts

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

package/dist/Field/hooks/useFieldContext.js

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

package/dist/Field/hooks/useFieldProps.d.ts

@@ -0,0 +1,25 @@
+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 declare function useFieldProps<P extends FieldAwareProps>(consumerProps: P): P;
+export {};

package/dist/Field/hooks/useFieldProps.js

@@ -0,0 +1,39 @@
+"use client";
+import { useContext } from "react";
+import { FieldContext } from "../FieldContext.js";
+/**
+ * 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(consumerProps) {
+    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/dist/Field/index.d.ts

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

package/dist/Field/index.js

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

package/dist/Field/types.d.ts

@@ -0,0 +1,81 @@
+import { ComponentProps, ReactNode } from "react";
+/**
+ * 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 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 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's `disabled` prop and
+     * sets `data-field-disabled` on the wrapper.
+     * @default false */
+    disabled?: boolean;
+    /** Marks the field required. Cascades to the control's `required` prop
+     * and sets `data-field-required` on the wrapper.
+     * @default false */
+    required?: boolean;
+    /** 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 {@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"> & {
+    /** 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 {@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"> & {
+    /** 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 {@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"> & {
+    /** 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/dist/Field/types.js

@@ -0,0 +1 @@
+export {};