atlas-react-kit 0.13.0 → 1.1.0

package/dist/form/checkbox-field.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { Checkbox } from "../checkbox.js";
+import { Field, FieldContent, FieldDescription, FieldLabel, FieldLegend, FieldSet, } from "../field.js";
+import { cn } from "../utils.js";
+import { FieldError, } from "./field-error.js";
+import { describedBy, descriptionIdFor, errorIdFor, invalidWhen, metaErrorText, } from "./field-shell.js";
+/**
+ * One boolean as a labelled checkbox, with an optional hint and the same
+ * error text and timing as the other `form/*` fields.
+ */
+export function FormCheckboxField({ checked, onCheckedChange, onBlur, label, description, id: idProp, meta, submitted, showError, required, disabled, controlPosition = "start", className, fieldClassName, }) {
+    const generatedId = useId();
+    const id = idProp ?? generatedId;
+    const errorText = metaErrorText(meta, { submitted, showError });
+    const descriptionId = description ? descriptionIdFor(id) : undefined;
+    const checkbox = (_jsx(Checkbox, { id: id, checked: checked, onCheckedChange: (next) => onCheckedChange(next === true), onBlur: onBlur, disabled: disabled, required: required, "aria-required": required || undefined, "aria-invalid": invalidWhen(errorText), "aria-describedby": describedBy(id, errorText, descriptionId), className: className }));
+    const labelNode = (_jsx(FieldLabel, { htmlFor: id, required: required, children: label }));
+    return (_jsxs("div", { "data-slot": "form-field", className: cn("flex flex-col gap-1.5", fieldClassName), children: [_jsxs(Field, { orientation: "horizontal", children: [controlPosition === "start" ? checkbox : null, description ? (_jsxs(FieldContent, { children: [labelNode, _jsx(FieldDescription, { id: descriptionId, children: description })] })) : (labelNode), controlPosition === "end" ? checkbox : null] }), _jsx(FieldError, { id: errorIdFor(id), text: errorText })] }));
+}
+/** Several values from a short list, as a labelled set of checkboxes. */
+export function FormCheckboxGroupField({ label, description, options, value, onValueChange, meta, submitted, showError, disabled, className, fieldClassName, }) {
+    const id = useId();
+    const errorText = metaErrorText(meta, { submitted, showError });
+    const descriptionId = description ? descriptionIdFor(id) : undefined;
+    function toggle(option, on) {
+        const next = new Set(value);
+        if (on)
+            next.add(option);
+        else
+            next.delete(option);
+        onValueChange(options.map((o) => o.value).filter((v) => next.has(v)));
+    }
+    return (_jsxs(FieldSet, { "data-slot": "form-field", "aria-invalid": invalidWhen(errorText), "aria-describedby": describedBy(id, errorText, descriptionId), className: cn("gap-1.5", fieldClassName), children: [_jsx(FieldLegend, { variant: "label", className: "mb-0", children: label }), description ? (_jsx("p", { id: descriptionId, "data-slot": "form-field-description", className: "text-xs text-muted-foreground", children: description })) : null, _jsx("div", { "data-slot": "form-checkbox-group-options", className: cn("flex flex-wrap gap-x-6 gap-y-3 pt-1", className), children: options.map((option) => {
+                    const optionId = `${id}-${option.value}`;
+                    return (_jsxs(Field, { orientation: "horizontal", children: [_jsx(Checkbox, { id: optionId, checked: value.includes(option.value), onCheckedChange: (next) => toggle(option.value, next === true), disabled: disabled }), _jsx(FieldLabel, { htmlFor: optionId, children: option.label })] }, option.value));
+                }) }), _jsx(FieldError, { id: errorIdFor(id), text: errorText })] }));
+}

package/dist/form/combobox-field.d.ts

@@ -0,0 +1,13 @@
+import { type ComponentProps } from "react";
+import { Combobox } from "../combobox.js";
+import type { FormFieldBaseProps, FormFieldDescriptionProps, FormFieldMetaProps } from "./field-error.js";
+type Props = FormFieldBaseProps & FormFieldMetaProps & FormFieldDescriptionProps & Omit<ComponentProps<typeof Combobox>, "id" | "aria-invalid" | "aria-describedby" | "aria-required"> & {
+    /** Marks the label and passes `aria-required` to the trigger. */
+    required?: boolean;
+};
+/**
+ * `Combobox` with a label, optional hint, and the `form/*` error text and
+ * timing. Pass the field's blur handler as `onBlur` so touch state updates.
+ */
+export declare function FormComboboxField({ label, description, meta, submitted, showError, required, fieldClassName, ...props }: Props): import("react").JSX.Element;
+export {};

package/dist/form/combobox-field.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useId } from "react";
+import { Combobox } from "../combobox.js";
+import { describedBy, descriptionIdFor, FormFieldShell, invalidWhen, metaErrorText, } from "./field-shell.js";
+/**
+ * `Combobox` with a label, optional hint, and the `form/*` error text and
+ * timing. Pass the field's blur handler as `onBlur` so touch state updates.
+ */
+export function FormComboboxField({ label, description, meta, submitted, showError, required, fieldClassName, ...props }) {
+    const id = useId();
+    const errorText = metaErrorText(meta, { submitted, showError });
+    return (_jsx(FormFieldShell, { id: id, label: label, description: description, errorText: errorText, required: required, className: fieldClassName, children: _jsx(Combobox, { ...props, id: id, "aria-required": required || undefined, "aria-invalid": invalidWhen(errorText), "aria-describedby": describedBy(id, errorText, description ? descriptionIdFor(id) : undefined) }) }));
+}

package/dist/form/control-field.d.ts

@@ -1,22 +1,21 @@
 import { type ComponentProps, type ReactNode } from "react";
-import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
+import type { FormFieldBaseProps, FormFieldDescriptionProps, FormFieldMetaProps } from "./field-error.js";
 /** Props `FormControlField` hands its control: spread them onto it. */
 export type FormControlProps = {
+    /** Id the label points at. */
     id: string;
+    /** `true` while the field shows error text. */
     "aria-invalid": true | undefined;
+    /** Ids of the hint and the error text, when shown. */
     "aria-describedby": string | undefined;
+    /** `true` when the field is `required`. */
     "aria-required": true | undefined;
 };
-type Props = ErrorTimingProps & Omit<ComponentProps<"div">, "id" | "children"> & {
+type Props = Omit<FormFieldBaseProps, "fieldClassName"> & FormFieldMetaProps & FormFieldDescriptionProps & Omit<ComponentProps<"div">, "id" | "children"> & {
     /** Control id the label points at. Defaults to a generated id. */
     id?: string;
-    label: string;
-    /** Hint between the label and the control, read with the control. */
-    description?: ReactNode;
     /** Marks the label and passes `aria-required` to the control. */
     required?: boolean;
-    /** Error meta, the same shape the other `form/*` fields take. */
-    meta?: FieldMetaState;
     /** Renders the control from the id and ARIA props it should carry. */
     children: (control: FormControlProps) => ReactNode;
 };

package/dist/form/date-picker-field.d.ts

@@ -1,27 +1,18 @@
-import { type DateLike, type DatePickerCalendarProps } from "../date-picker.js";
-import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
-type Props = ErrorTimingProps & {
+import { type DateLike } from "../date-picker.js";
+import { type PickerFieldBaseProps } from "./field-shell.js";
+type Props = PickerFieldBaseProps & {
+    /** The picked day, as a `Date` or `yyyy-MM-dd`; empty when unset. */
     value: DateLike;
+    /** Called with the picked day, or `undefined` when cleared. */
     onValueChange: (date: Date | undefined) => void;
-    label: string;
-    meta?: FieldMetaState;
+    /** Trigger text while no day is picked. Default "Pick a date". */
     placeholder?: string;
-    disabled?: boolean;
-    /** Marks the label and adds "Required" to the trigger's description. */
-    required?: boolean;
-    /** Earliest day that can be picked; earlier days are disabled. */
-    minDate?: DateLike;
-    /** Latest day that can be picked; later days are disabled. */
-    maxDate?: DateLike;
-    /** Forwarded to the date picker trigger. */
-    className?: string;
-    /** Classes for the field wrapper (label, trigger, and error). */
-    fieldClassName?: string;
-    /** Forwarded to the date picker popover. */
-    contentClassName?: string;
-    /** Day Picker options forwarded to the calendar (disabled days, etc.). */
-    calendarProps?: DatePickerCalendarProps;
+    /**
+     * Shows a Clear row in the popover, which calls `onValueChange` with
+     * `undefined`. Default `false`.
+     */
+    clearable?: boolean;
 };
 /** Date picker with built-in field error text and invalid styling. */
-export declare function FormDatePickerField({ onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }: Props): import("react").JSX.Element;
+export declare function FormDatePickerField({ id: idProp, onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }: Props): import("react").JSX.Element;
 export {};

package/dist/form/date-picker-field.js

@@ -1,11 +1,12 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from "react";
-import { DatePickerButton, } from "../date-picker.js";
+import { DatePickerButton } from "../date-picker.js";
 import { FormFieldShell, metaErrorText, pickerFieldAria, } from "./field-shell.js";
 /** Date picker with built-in field error text and invalid styling. */
-export function FormDatePickerField({ onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }) {
+export function FormDatePickerField({ id: idProp, onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }) {
     const errorText = metaErrorText(meta, { submitted, showError });
-    const id = useId();
-    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, required: required, className: fieldClassName, children: _jsx(DatePickerButton, { ...picker, id: id, onChange: onValueChange, ...pickerFieldAria(id, errorText, required) }) }));
+    const generatedId = useId();
+    const id = idProp ?? generatedId;
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, required: required, className: fieldClassName, children: _jsx(DatePickerButton, { ...picker, id: id, onValueChange: onValueChange, ...pickerFieldAria(id, errorText, required) }) }));
 }

package/dist/form/date-time-picker-field.d.ts

@@ -1,29 +1,14 @@
-import type { DateLike, DatePickerCalendarProps } from "../date-picker.js";
-import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
-type Props = ErrorTimingProps & {
+import { type PickerFieldBaseProps } from "./field-shell.js";
+type Props = PickerFieldBaseProps & {
+    /** The picked instant, or `null` when empty. */
     value: Date | null;
+    /** Called with the picked instant, or `null` on Clear. */
     onValueChange: (date: Date | null) => void;
-    label: string;
-    meta?: FieldMetaState;
+    /** Trigger text while nothing is picked. Default "Pick a date and time". */
     placeholder?: string;
-    disabled?: boolean;
-    /** Marks the label and adds "Required" to the trigger's description. */
-    required?: boolean;
-    /** Earliest day that can be picked; earlier days are disabled. */
-    minDate?: DateLike;
-    /** Latest day that can be picked; later days are disabled. */
-    maxDate?: DateLike;
-    /** Minute increment forwarded to the picker. */
+    /** Minute increment for the time selects (1, 5, 15, 30, or 60). Default 15. */
     timeStep?: number;
-    /** Forwarded to the date-time picker trigger. */
-    className?: string;
-    /** Classes for the field wrapper (label, trigger, and error). */
-    fieldClassName?: string;
-    /** Forwarded to the date-time picker popover. */
-    contentClassName?: string;
-    /** Day Picker options forwarded to the calendar (disabled days, etc.). */
-    calendarProps?: DatePickerCalendarProps;
 };
 /** Date-time picker with built-in field error text and invalid styling. */
-export declare function FormDateTimePickerField({ onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }: Props): import("react").JSX.Element;
+export declare function FormDateTimePickerField({ id: idProp, onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }: Props): import("react").JSX.Element;
 export {};

package/dist/form/date-time-picker-field.js

@@ -4,8 +4,9 @@ import { useId } from "react";
 import { DateTimePickerButton } from "../date-time-picker.js";
 import { FormFieldShell, metaErrorText, pickerFieldAria, } from "./field-shell.js";
 /** Date-time picker with built-in field error text and invalid styling. */
-export function FormDateTimePickerField({ onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }) {
+export function FormDateTimePickerField({ id: idProp, onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }) {
     const errorText = metaErrorText(meta, { submitted, showError });
-    const id = useId();
-    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, required: required, className: fieldClassName, children: _jsx(DateTimePickerButton, { ...picker, id: id, onChange: onValueChange, ...pickerFieldAria(id, errorText, required) }) }));
+    const generatedId = useId();
+    const id = idProp ?? generatedId;
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, required: required, className: fieldClassName, children: _jsx(DateTimePickerButton, { ...picker, id: id, onValueChange: onValueChange, ...pickerFieldAria(id, errorText, required) }) }));
 }

package/dist/form/feedback-field.d.ts

@@ -1,5 +1,7 @@
 /** Form-level submit or mutation error (not tied to a single field). */
 export declare function FormFeedbackField({ message, className, }: {
+    /** Error text to show; `null` or empty renders nothing. */
     message: string | null;
+    /** Classes for the message paragraph. */
     className?: string;
 }): import("react").JSX.Element | null;

package/dist/form/field-error.d.ts

@@ -1,7 +1,9 @@
+import type { ReactNode } from "react";
 export type FieldErrorMessage = string | {
     message?: string;
 } | undefined;
 export type FieldMetaState = {
+    /** Validation errors for the field; the `form/*` fields show the first. */
     errors: FieldErrorMessage[];
     /**
      * Whether the person has changed or left the field (TanStack Form's
@@ -14,20 +16,50 @@ export type FieldMetaState = {
 /** When a field shows its error: the `form/*` fields' shared timing props. */
 export type ErrorTimingProps = {
     /**
-     * Set once the form has been submitted (TanStack Form:
-     * `form.state.submissionAttempts > 0`), so an untouched field shows its
-     * error too. Only matters when `meta.isTouched` is passed.
+     * Set once the form has been submitted, so an untouched field shows its
+     * error too. For form libraries that do not mark fields touched on
+     * submit; TanStack Form does, so its users pass `meta` only. Only matters
+     * when `meta.isTouched` is passed.
      */
     submitted?: boolean;
     /** When false, never shows error text or invalid styling. Default true. */
     showError?: boolean;
 };
+/**
+ * Props every labelled `form/*` field shares: the error timing, the label,
+ * and the classes for the field wrapper.
+ */
+export type FormFieldBaseProps = ErrorTimingProps & {
+    /** Visible label text (the legend, for a checkbox group). */
+    label: string;
+    /**
+     * Classes for the field wrapper (`data-slot="form-field"`: label, hint,
+     * control, and error), e.g. a width.
+     */
+    fieldClassName?: string;
+};
+/** Error meta for the `form/*` fields that are not bound to a `field` API. */
+export type FormFieldMetaProps = {
+    /**
+     * The field's meta (TanStack Form's `field.state.meta`); its first error
+     * shows under the control. Leave it out for no error text.
+     */
+    meta?: FieldMetaState;
+};
+/** The optional hint the `form/*` fields render under the label. */
+export type FormFieldDescriptionProps = {
+    /** Hint between the label and the control, read with the control. */
+    description?: ReactNode;
+};
 /** First TanStack Form error message for a field, if any. */
 export declare function getFieldErrorMessage(message: FieldErrorMessage): string | undefined;
 export declare function FieldError({ id, message, text, className, }: {
     /** Point the control's `aria-describedby` here so the error is read with it. */
     id?: string;
+    /** Error to show, as TanStack Form reports it; ignored when `text` is set. */
     message?: FieldErrorMessage;
+    /** Error text to show as is; takes precedence over `message`. */
     text?: string;
+    /** Classes for the error paragraph. */
     className?: string;
 }): import("react").JSX.Element | null;

package/dist/form/field-shell.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentProps, ReactNode } from "react";
-import { type ErrorTimingProps, type FieldMetaState } from "./field-error.js";
+import type { DateLike, DatePickerCalendarProps } from "../date-picker.js";
+import { type ErrorTimingProps, type FieldMetaState, type FormFieldBaseProps, type FormFieldMetaProps } from "./field-error.js";
 /**
  * Not a public entry. The layout and error wiring every `form/*` field
  * shares, so a field only says which control it renders. Custom controls
@@ -19,16 +20,37 @@ export declare function labelIdFor(id: string): string;
 export declare function descriptionIdFor(id: string): string;
 /** Id of the error text `FormFieldShell` renders for control `id`. */
 export declare function errorIdFor(id: string): string;
-/**
- * Id of the hidden "Required" text `FormFieldShell` renders for a required
- * control `id`, for controls that cannot carry `required` themselves.
- */
-export declare function requiredIdFor(id: string): string;
 /**
  * `aria-describedby` for the control: the given hint ids, plus the error
  * text while there is one, or `undefined` when there is nothing to read.
  */
 export declare function describedBy(id: string, errorText: string | undefined, ...hintIds: Array<string | undefined>): string | undefined;
+/**
+ * Props the date and date-time fields share; each adds its own `value`,
+ * `onValueChange`, and `placeholder`.
+ */
+export type PickerFieldBaseProps = FormFieldBaseProps & FormFieldMetaProps & {
+    /**
+     * Id of the trigger the label points at. Defaults to a generated id;
+     * pass the field name (`id={field.name}`) so a submit handler such as
+     * `focusFirstInvalid` can find the control.
+     */
+    id?: string;
+    /** Disables the trigger so no date can be picked. */
+    disabled?: boolean;
+    /** Marks the label and adds "Required" to the trigger's description. */
+    required?: boolean;
+    /** Earliest day that can be picked; earlier days are disabled. */
+    minDate?: DateLike;
+    /** Latest day that can be picked; later days are disabled. */
+    maxDate?: DateLike;
+    /** Forwarded to the picker trigger. */
+    className?: string;
+    /** Forwarded to the picker popover. */
+    contentClassName?: string;
+    /** Day Picker options forwarded to the calendar (disabled days, etc.). */
+    calendarProps?: DatePickerCalendarProps;
+};
 /**
  * Trigger ARIA for the date and date-time fields: invalid while there is
  * error text, named "label, value" (a `<label for>` alone would hide the
@@ -53,12 +75,19 @@ export declare function pickerFieldAria(id: string, errorText: string | undefine
  * so put fields in a grid row with `items-start` to keep controls aligned.
  */
 export declare function FormFieldShell({ id, label, labelAction, description, errorText, labelFor, required, className, children, ...props }: Omit<ComponentProps<"div">, "id" | "children"> & {
+    /** Id of the control; the label, hint, and error ids derive from it. */
     id: string;
+    /** Visible label text. */
     label: string;
+    /** Content on the label's row, after the label (e.g. a mode toggle). */
     labelAction?: ReactNode;
+    /** Hint between the label and the control, with id `descriptionIdFor(id)`. */
     description?: ReactNode;
+    /** Error text under the control; `undefined` shows none. */
     errorText: string | undefined;
+    /** When false, the label does not point at the control. Default true. */
     labelFor?: boolean;
+    /** Marks the label and renders the hidden "Required" text. */
     required?: boolean;
     children: ReactNode;
 }): import("react").JSX.Element;

package/dist/form/field-shell.js

@@ -40,7 +40,7 @@ export function errorIdFor(id) {
  * Id of the hidden "Required" text `FormFieldShell` renders for a required
  * control `id`, for controls that cannot carry `required` themselves.
  */
-export function requiredIdFor(id) {
+function requiredIdFor(id) {
     return `${id}-required`;
 }
 /**

package/dist/form/focus-first-invalid.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The part of a form library's invalid-submit event this helper reads: the
+ * form state's per-field meta, keyed by field name (TanStack Form's
+ * `onSubmitInvalid` passes `{ formApi }` with this shape).
+ */
+export type InvalidSubmitEvent = {
+    formApi: {
+        state: {
+            fieldMeta: Partial<Record<string, {
+                errors: readonly unknown[];
+            }>>;
+        };
+    };
+};
+/**
+ * Invalid-submit handler that focuses the first field, in page order, whose
+ * meta has errors. It reads the form state, not the rendered `aria-invalid`,
+ * so it works before React has re-rendered. Fields are matched by control
+ * id, so give each `form/*` field `id={field.name}` (`FormTextField`
+ * defaults to it). The form library needs no focus API of its own.
+ *
+ * ```tsx
+ * const form = useForm({ onSubmitInvalid: focusFirstInvalid("order-form") })
+ * <form id="order-form" onSubmit={...}>
+ *   <FormSelectField id={field.name} ... />
+ * ```
+ */
+export declare function focusFirstInvalid(formId: string): ({ formApi }: InvalidSubmitEvent) => void;

package/dist/form/focus-first-invalid.js

@@ -0,0 +1,29 @@
+/**
+ * Invalid-submit handler that focuses the first field, in page order, whose
+ * meta has errors. It reads the form state, not the rendered `aria-invalid`,
+ * so it works before React has re-rendered. Fields are matched by control
+ * id, so give each `form/*` field `id={field.name}` (`FormTextField`
+ * defaults to it). The form library needs no focus API of its own.
+ *
+ * ```tsx
+ * const form = useForm({ onSubmitInvalid: focusFirstInvalid("order-form") })
+ * <form id="order-form" onSubmit={...}>
+ *   <FormSelectField id={field.name} ... />
+ * ```
+ */
+export function focusFirstInvalid(formId) {
+    return ({ formApi }) => {
+        const form = document.getElementById(formId);
+        if (!(form instanceof HTMLFormElement))
+            return;
+        const invalid = new Set(Object.entries(formApi.state.fieldMeta)
+            .filter(([, meta]) => meta?.errors.length)
+            .map(([name]) => name));
+        for (const element of form.elements) {
+            if (element instanceof HTMLElement && invalid.has(element.id)) {
+                element.focus();
+                return;
+            }
+        }
+    };
+}

package/dist/form/markdown-field.d.ts

@@ -1,25 +1,13 @@
-import type { ErrorTimingProps } from "./field-error.js";
-import type { TextFieldApi } from "./text-field.js";
+import type { TextFieldBaseProps } from "./text-field.js";
 /**
  * GFM body field: Write is a textarea, Preview is the sanitized Markdown
  * renderer. String-in/string-out — not a WYSIWYG document model.
  */
-export declare function FormMarkdownField({ field, id, label, placeholder, rows, showError, submitted, required, className, fieldClassName, previewClassName, }: ErrorTimingProps & {
-    field: TextFieldApi;
-    /**
-     * Control id the label points at. Defaults to `field.name`; pass a unique
-     * id when two forms on one page share a field name.
-     */
-    id?: string;
-    label: string;
+export declare function FormMarkdownField({ field, id, label, placeholder, rows, showError, submitted, required, className, fieldClassName, previewClassName, }: TextFieldBaseProps & {
+    /** Write textarea placeholder. Default "Markdown supported". */
     placeholder?: string;
+    /** Write textarea rows. Default 5. */
     rows?: number;
-    /** Sets `required` on the Write textarea and marks the label. */
-    required?: boolean;
-    /** Forwarded to the Write textarea. */
-    className?: string;
-    /** Classes for the field wrapper (label row, body, and error). */
-    fieldClassName?: string;
     /** Classes for the Preview surface, e.g. a taller `min-h-40`. */
     previewClassName?: string;
 }): import("react").JSX.Element;

package/dist/form/select-field.d.ts

@@ -1,21 +1,27 @@
 import { type ReactNode } from "react";
-import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
-type Props = ErrorTimingProps & {
+import type { FormFieldBaseProps, FormFieldMetaProps } from "./field-error.js";
+type Props = FormFieldBaseProps & FormFieldMetaProps & {
+    /** The selected item's value, or `undefined` for none. */
     value: string | undefined;
-    meta?: FieldMetaState;
-    label: string;
+    /** Called with the value of the item the person picks. */
     onValueChange: (value: string) => void;
+    /** Trigger text while no item is selected. */
     placeholder?: string;
+    /**
+     * Id of the trigger the label points at. Defaults to a generated id;
+     * pass the field name (`id={field.name}`) so a submit handler such as
+     * `focusFirstInvalid` can find the control.
+     */
+    id?: string;
     /** Requires a value (native form validation) and marks the label. */
     required?: boolean;
     /** Forwarded to the select trigger. */
     className?: string;
-    /** Classes for the field wrapper (label, trigger, and error). */
-    fieldClassName?: string;
     /** Forwarded to the select's option list (`SelectContent`). */
     contentClassName?: string;
+    /** The `SelectItem`s (and groups) to choose from. */
     children: ReactNode;
 };
 /** Select control with built-in field error text and invalid styling. */
-export declare function FormSelectField({ value, meta, submitted, showError, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }: Props): import("react").JSX.Element;
+export declare function FormSelectField({ id: idProp, value, meta, submitted, showError, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }: Props): import("react").JSX.Element;
 export {};

package/dist/form/select-field.js

@@ -4,8 +4,9 @@ import { useId } from "react";
 import { Select, SelectContent, SelectTrigger, SelectValue } from "../select.js";
 import { describedBy, FormFieldShell, invalidWhen, metaErrorText, } from "./field-shell.js";
 /** Select control with built-in field error text and invalid styling. */
-export function FormSelectField({ value, meta, submitted, showError, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }) {
+export function FormSelectField({ id: idProp, value, meta, submitted, showError, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }) {
     const errorText = metaErrorText(meta, { submitted, showError });
-    const id = useId();
+    const generatedId = useId();
+    const id = idProp ?? generatedId;
     return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, required: required, className: fieldClassName, children: _jsxs(Select, { value: value, onValueChange: onValueChange, required: required, children: [_jsx(SelectTrigger, { id: id, className: className, "aria-required": required || undefined, "aria-invalid": invalidWhen(errorText), "aria-describedby": describedBy(id, errorText), children: _jsx(SelectValue, { placeholder: placeholder }) }), _jsx(SelectContent, { className: contentClassName, children: children })] }) }));
 }

package/dist/form/text-field.d.ts

@@ -1,14 +1,24 @@
-import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
+import type { FieldMetaState, FormFieldBaseProps } from "./field-error.js";
 export type TextFieldApi = {
+    /** Field name; the default control id. */
     name: string;
     state: {
+        /** Current text. */
         value: string;
+        /** Error meta; its first error shows under the control. */
         meta: FieldMetaState;
     };
+    /** Called with the new text on every change. */
     handleChange: (value: string) => void;
+    /** Called when the control loses focus, to mark the field touched. */
     handleBlur: () => void;
 };
-export declare function FormTextField({ field, id, label, placeholder, description, autoFocus, multiline, rows, inputType, showError, submitted, autoComplete, required, minLength, className, fieldClassName, }: ErrorTimingProps & {
+/**
+ * Props the text and Markdown fields share: both bind to a TanStack Form
+ * `field` and render a text control.
+ */
+export type TextFieldBaseProps = FormFieldBaseProps & {
+    /** The TanStack Form field (or the same shape) the control reads and writes. */
     field: TextFieldApi;
     /**
      * Control id the label points at. Defaults to `field.name`; pass a unique
@@ -16,21 +26,30 @@ export declare function FormTextField({ field, id, label, placeholder, descripti
      * `email`), or the second label focuses the first input.
      */
     id?: string;
-    label: string;
+    /** Sets `required` on the text control and marks the label. */
+    required?: boolean;
+    /** Forwarded to the text control (the input or textarea). */
+    className?: string;
+};
+/**
+ * Text input, or a textarea with `multiline`, bound to a TanStack Form
+ * `field`, with a label, optional hint, and the `form/*` error text.
+ */
+export declare function FormTextField({ field, id, label, placeholder, description, autoFocus, multiline, rows, inputType, showError, submitted, autoComplete, required, minLength, className, fieldClassName, }: TextFieldBaseProps & {
+    /** Text shown in the empty control. */
     placeholder?: string;
     /** Optional hint under the label (employer vs referrer, etc.). */
     description?: string;
+    /** Focuses the input on mount (ignored with `multiline`). */
     autoFocus?: boolean;
+    /** Renders a textarea instead of an input. */
     multiline?: boolean;
-    /** Textarea rows when `multiline` is set. */
+    /** Textarea rows when `multiline` is set. Default 3. */
     rows?: number;
+    /** The input's `type` when not `multiline`. Default "text". */
     inputType?: "text" | "email" | "password" | "date" | "datetime-local" | "time" | "number";
+    /** Forwarded to the control's `autoComplete`. */
     autoComplete?: string;
-    /** Sets `required` on the control and marks the label. */
-    required?: boolean;
+    /** Minimum text length (native form validation). */
     minLength?: number;
-    /** Forwarded to the input or textarea. */
-    className?: string;
-    /** Classes for the field wrapper (label, hint, control, and error). */
-    fieldClassName?: string;
 }): import("react").JSX.Element;

package/dist/form/text-field.js

@@ -4,6 +4,10 @@ import { Input } from "../input.js";
 import { Textarea } from "../textarea.js";
 import { onInputChange } from "../utils.js";
 import { describedBy, descriptionIdFor, FormFieldShell, invalidWhen, metaErrorText, } from "./field-shell.js";
+/**
+ * Text input, or a textarea with `multiline`, bound to a TanStack Form
+ * `field`, with a label, optional hint, and the `form/*` error text.
+ */
 export function FormTextField({ field, id = field.name, label, placeholder, description, autoFocus, multiline, rows = 3, inputType = "text", showError, submitted, autoComplete, required, minLength, className, fieldClassName, }) {
     const onChange = onInputChange(field.handleChange);
     const errorText = metaErrorText(field.state.meta, { submitted, showError });

package/dist/form/toggle-group-field.d.ts

@@ -0,0 +1,30 @@
+import { type ReactNode } from "react";
+import type { FormFieldBaseProps, FormFieldDescriptionProps, FormFieldMetaProps } from "./field-error.js";
+export type ToggleGroupFieldOption<T extends string> = {
+    /** Value passed to `onValueChange` when this item is pressed. */
+    value: T;
+    /** Content of the toggle item. */
+    label: ReactNode;
+};
+type Props<T extends string> = FormFieldBaseProps & FormFieldMetaProps & FormFieldDescriptionProps & {
+    /** The selected option, or `""` for none yet. */
+    value: T | "";
+    /** Called with an option's value; pressing the active item keeps it. */
+    onValueChange: (value: T) => void;
+    /** The items to choose from, in order. */
+    options: ToggleGroupFieldOption<T>[];
+    /** Marks the label. */
+    required?: boolean;
+    /** Disables every item in the group. */
+    disabled?: boolean;
+    /** Size of the toggle items. Default "sm". */
+    size?: "default" | "sm" | "lg";
+    /** Forwarded to the toggle group. */
+    className?: string;
+};
+/**
+ * One choice from a few as a joined outline toggle group (a segmented
+ * control), with a visible label and the `form/*` error wiring.
+ */
+export declare function FormToggleGroupField<T extends string>({ label, description, value, onValueChange, options, meta, submitted, showError, required, disabled, size, className, fieldClassName, }: Props<T>): import("react").JSX.Element;
+export {};