atlas-react-kit 0.12.0 → 1.0.0

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

@@ -1,29 +1,14 @@
-import type { DateLike, DatePickerCalendarProps } from "../date-picker.js";
-import type { FieldMetaState } from "./field-error.js";
-type Props = {
+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, required, fieldClassName, ...picker }: Props): import("react").JSX.Element;
+export declare function FormDateTimePickerField({ 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,8 @@ 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, required, fieldClassName, ...picker }) {
-    const errorText = metaErrorText(meta);
+export function FormDateTimePickerField({ 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) }) }));
+    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,15 +1,64 @@
+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
+     * `meta.isTouched`). When it is `false`, the `form/*` fields hold back
+     * the error until the field is touched or their `submitted` prop is set.
+     * Leave it out to show errors as soon as they exist.
+     */
+    isTouched?: boolean;
+};
+/** 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.
+     */
+    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,15 +1,23 @@
-import type { ReactNode } from "react";
-import { type FieldMetaState } from "./field-error.js";
+import type { ComponentProps, ReactNode } from "react";
+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.
+ * shares, so a field only says which control it renders. Custom controls
+ * get the same shell through the public `FormControlField`.
  */
-/** First error in `meta`, or `undefined` when there is no meta or no error. */
-export declare function metaErrorText(meta: FieldMetaState | undefined): string | undefined;
+/**
+ * First error in `meta`, or `undefined` when there is no meta, no error,
+ * `showError` is false, or the field is untouched (`isTouched: false`)
+ * and the form has not been submitted.
+ */
+export declare function metaErrorText(meta: FieldMetaState | undefined, { submitted, showError }?: ErrorTimingProps): string | undefined;
 /** `aria-invalid` for the control: `true` while there is error text. */
 export declare function invalidWhen(errorText: string | undefined): true | undefined;
 /** Id of the label `FormFieldShell` renders for control `id`. */
 export declare function labelIdFor(id: string): string;
+/** Id of the hint `FormFieldShell` renders for control `id`. */
+export declare function descriptionIdFor(id: string): string;
 /** Id of the error text `FormFieldShell` renders for control `id`. */
 export declare function errorIdFor(id: string): string;
 /**
@@ -22,6 +30,26 @@ export declare function requiredIdFor(id: string): string;
  * 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 & {
+    /** 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
@@ -38,16 +66,27 @@ export declare function pickerFieldAria(id: string, errorText: string | undefine
  * `labelAction` sits on the label's row (the Markdown field's mode toggle).
  * Set `labelFor` to false when the control is not rendered (Markdown
  * preview), so the label does not point at a missing element.
- * `className` styles the wrapper (`data-slot="form-field"`), e.g. a width.
+ * `description` is a hint between the label and the control, with id
+ * `descriptionIdFor(id)`. `className` and other div props go to the
+ * wrapper (`data-slot="form-field"`), e.g. a width.
  * `required` marks the label; the control still sets its own `required`.
+ * The error sits below the control and takes no space while there is none,
+ * so put fields in a grid row with `items-start` to keep controls aligned.
  */
-export declare function FormFieldShell({ id, label, labelAction, errorText, labelFor, required, className, children, }: {
+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;
-    className?: string;
     children: ReactNode;
 }): import("react").JSX.Element;

package/dist/form/field-shell.js

@@ -5,11 +5,20 @@ import { cn } from "../utils.js";
 import { FieldError, getFieldErrorMessage, } 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.
+ * shares, so a field only says which control it renders. Custom controls
+ * get the same shell through the public `FormControlField`.
  */
-/** First error in `meta`, or `undefined` when there is no meta or no error. */
-export function metaErrorText(meta) {
-    return meta ? getFieldErrorMessage(meta.errors[0]) : undefined;
+/**
+ * First error in `meta`, or `undefined` when there is no meta, no error,
+ * `showError` is false, or the field is untouched (`isTouched: false`)
+ * and the form has not been submitted.
+ */
+export function metaErrorText(meta, { submitted, showError = true } = {}) {
+    if (!meta || !showError)
+        return undefined;
+    if (meta.isTouched === false && !submitted)
+        return undefined;
+    return getFieldErrorMessage(meta.errors[0]);
 }
 /** `aria-invalid` for the control: `true` while there is error text. */
 export function invalidWhen(errorText) {
@@ -19,6 +28,10 @@ export function invalidWhen(errorText) {
 export function labelIdFor(id) {
     return `${id}-label`;
 }
+/** Id of the hint `FormFieldShell` renders for control `id`. */
+export function descriptionIdFor(id) {
+    return `${id}-description`;
+}
 /** Id of the error text `FormFieldShell` renders for control `id`. */
 export function errorIdFor(id) {
     return `${id}-error`;
@@ -56,10 +69,14 @@ export function pickerFieldAria(id, errorText, required) {
  * `labelAction` sits on the label's row (the Markdown field's mode toggle).
  * Set `labelFor` to false when the control is not rendered (Markdown
  * preview), so the label does not point at a missing element.
- * `className` styles the wrapper (`data-slot="form-field"`), e.g. a width.
+ * `description` is a hint between the label and the control, with id
+ * `descriptionIdFor(id)`. `className` and other div props go to the
+ * wrapper (`data-slot="form-field"`), e.g. a width.
  * `required` marks the label; the control still sets its own `required`.
+ * The error sits below the control and takes no space while there is none,
+ * so put fields in a grid row with `items-start` to keep controls aligned.
  */
-export function FormFieldShell({ id, label, labelAction, errorText, labelFor = true, required, className, children, }) {
+export function FormFieldShell({ id, label, labelAction, description, errorText, labelFor = true, required, className, children, ...props }) {
     const labelNode = (_jsx(Label, { id: labelIdFor(id), htmlFor: labelFor ? id : undefined, required: required, children: label }));
-    return (_jsxs("div", { "data-slot": "form-field", className: cn("flex flex-col gap-1.5", className), children: [labelAction ? (_jsxs("div", { "data-slot": "form-field-header", className: "flex items-center justify-between gap-2", children: [labelNode, labelAction] })) : (labelNode), children, required ? (_jsx("span", { id: requiredIdFor(id), hidden: true, children: "Required" })) : null, _jsx(FieldError, { id: errorIdFor(id), text: errorText })] }));
+    return (_jsxs("div", { "data-slot": "form-field", className: cn("flex flex-col gap-1.5", className), ...props, children: [labelAction ? (_jsxs("div", { "data-slot": "form-field-header", className: "flex items-center justify-between gap-2", children: [labelNode, labelAction] })) : (labelNode), description ? (_jsx("p", { id: descriptionIdFor(id), "data-slot": "form-field-description", className: "text-xs text-muted-foreground", children: description })) : null, children, required ? (_jsx("span", { id: requiredIdFor(id), hidden: true, children: "Required" })) : null, _jsx(FieldError, { id: errorIdFor(id), text: errorText })] }));
 }

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

@@ -1,25 +1,13 @@
-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, required, className, fieldClassName, previewClassName, }: {
-    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;
-    showError?: boolean;
-    /** 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/markdown-field.js

@@ -16,10 +16,10 @@ const Markdown = lazy(() => loadMarkdown().then((module) => ({ default: module.M
  * GFM body field: Write is a textarea, Preview is the sanitized Markdown
  * renderer. String-in/string-out — not a WYSIWYG document model.
  */
-export function FormMarkdownField({ field, id = field.name, label, placeholder = "Markdown supported", rows = 5, showError = true, required, className, fieldClassName, previewClassName, }) {
+export function FormMarkdownField({ field, id = field.name, label, placeholder = "Markdown supported", rows = 5, showError, submitted, required, className, fieldClassName, previewClassName, }) {
     const [mode, setMode] = useState("write");
     const onChange = onInputChange(field.handleChange);
-    const errorText = showError ? metaErrorText(field.state.meta) : undefined;
+    const errorText = metaErrorText(field.state.meta, { submitted, showError });
     const trimmed = field.state.value.trim();
     function handleModeChange(value) {
         if (value === "write" || value === "preview")

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

@@ -1,21 +1,21 @@
 import { type ReactNode } from "react";
-import type { FieldMetaState } from "./field-error.js";
-type Props = {
+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;
     /** 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, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }: Props): import("react").JSX.Element;
+export declare function FormSelectField({ 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,8 @@ 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, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }) {
-    const errorText = metaErrorText(meta);
+export function FormSelectField({ value, meta, submitted, showError, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }) {
+    const errorText = metaErrorText(meta, { submitted, showError });
     const id = useId();
     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 { 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, autoComplete, required, minLength, className, fieldClassName, }: {
+/**
+ * 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,23 +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";
-    /** When true (default), shows meta.errors and aria-invalid styling. */
-    showError?: boolean;
+    /** 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

@@ -1,13 +1,17 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { Input } from "../input.js";
 import { Textarea } from "../textarea.js";
 import { onInputChange } from "../utils.js";
-import { describedBy, FormFieldShell, invalidWhen, metaErrorText, } from "./field-shell.js";
-export function FormTextField({ field, id = field.name, label, placeholder, description, autoFocus, multiline, rows = 3, inputType = "text", showError = true, autoComplete, required, minLength, className, fieldClassName, }) {
+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 = showError ? metaErrorText(field.state.meta) : undefined;
-    const descriptionId = description ? `${id}-description` : undefined;
+    const errorText = metaErrorText(field.state.meta, { submitted, showError });
+    const descriptionId = description ? descriptionIdFor(id) : undefined;
     const controlProps = {
         id,
         value: field.state.value,
@@ -21,5 +25,5 @@ export function FormTextField({ field, id = field.name, label, placeholder, desc
         "aria-invalid": invalidWhen(errorText),
         "aria-describedby": describedBy(id, errorText, descriptionId),
     };
-    return (_jsxs(FormFieldShell, { id: id, label: label, errorText: errorText, required: required, className: fieldClassName, children: [description ? (_jsx("p", { id: descriptionId, "data-slot": "form-field-description", className: "text-xs text-muted-foreground", children: description })) : null, multiline ? (_jsx(Textarea, { ...controlProps, rows: rows })) : (_jsx(Input, { ...controlProps, type: inputType, autoFocus: autoFocus }))] }));
+    return (_jsx(FormFieldShell, { id: id, label: label, description: description, errorText: errorText, required: required, className: fieldClassName, children: multiline ? (_jsx(Textarea, { ...controlProps, rows: rows })) : (_jsx(Input, { ...controlProps, type: inputType, autoFocus: autoFocus })) }));
 }

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 {};

package/dist/form/toggle-group-field.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useId } from "react";
+import { ToggleGroup, ToggleGroupItem } from "../toggle-group.js";
+import { describedBy, descriptionIdFor, FormFieldShell, invalidWhen, labelIdFor, metaErrorText, } from "./field-shell.js";
+/**
+ * One choice from a few as a joined outline toggle group (a segmented
+ * control), with a visible label and the `form/*` error wiring.
+ */
+export function FormToggleGroupField({ label, description, value, onValueChange, options, meta, submitted, showError, required, disabled, size = "sm", className, fieldClassName, }) {
+    const id = useId();
+    const errorText = metaErrorText(meta, { submitted, showError });
+    function handleValueChange(next) {
+        const option = options.find((o) => o.value === next);
+        if (option)
+            onValueChange(option.value);
+    }
+    return (_jsx(FormFieldShell, { id: id, label: label, labelFor: false, description: description, errorText: errorText, required: required, className: fieldClassName, children: _jsx(ToggleGroup, { id: id, type: "single", value: value, onValueChange: handleValueChange, variant: "outline", size: size, spacing: 0, disabled: disabled, "aria-labelledby": labelIdFor(id), "aria-invalid": invalidWhen(errorText), "aria-describedby": describedBy(id, errorText, description ? descriptionIdFor(id) : undefined), className: className, children: options.map((option) => (_jsx(ToggleGroupItem, { value: option.value, children: option.label }, option.value))) }) }));
+}

package/dist/info-tip.d.ts

@@ -4,15 +4,24 @@ export type InfoTipLayout = "box" | "inline";
 export type InfoTipProps = {
     /** Required name for the icon button (the glyph has no visible text). */
     label: string;
+    /** Panel heading; also names the panel. Without it the panel uses `label`. */
     title?: string;
+    /** Muted text under the title. */
     description?: React.ReactNode;
     /** Extra body after the title and description. */
     children?: React.ReactNode;
-    /** `inline` keeps the surrounding line height; the 44px hit area overflows. */
+    /**
+     * `inline` keeps the surrounding line height; the 44px hit area overflows.
+     * Default `box`.
+     */
     layout?: InfoTipLayout;
+    /** Panel side. Default `top`; Radix still flips on collision. */
     side?: React.ComponentProps<typeof PopoverContent>["side"];
+    /** Panel alignment against the trigger. Default `center`. */
     align?: React.ComponentProps<typeof PopoverContent>["align"];
+    /** Shown beside the title, e.g. a `Badge`. */
     badge?: React.ReactNode;
+    /** Replaces the default question-mark glyph. */
     icon?: React.ReactNode;
     /** Classes for the trigger button. */
     className?: string;

package/dist/internal/as-child.d.ts

@@ -0,0 +1,8 @@
+/** Not a public entry. The Slot prop that Button, Badge, and the links share. */
+export type AsChildProps = {
+    /**
+     * Render the single child (e.g. a router `Link`) with these styles instead
+     * of the default element. Default `false`.
+     */
+    asChild?: boolean;
+};

package/dist/internal/as-child.js

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

package/dist/internal/date-like.d.ts

@@ -6,3 +6,26 @@ export type DateLike = Date | string | number | null | undefined;
  * shift when the runtime timezone is behind UTC.
  */
 export declare function toDate(value: DateLike): Date | undefined;
+/**
+ * A from/to pair of days. `to` is unset while a range is half picked. Same
+ * shape as Day Picker's, so either can be passed where the other is expected.
+ */
+export type DateRange = {
+    from: Date | undefined;
+    to?: Date | undefined;
+};
+/**
+ * Matches calendar days, for `disabled` and `hidden`: `true` for every day,
+ * one date or a list, a range, days `before` / `after` a date (both: the days
+ * outside them), weekdays (`0` is Sunday), or a predicate.
+ */
+export type DateMatcher = boolean | Date | Date[] | DateRange | {
+    before: Date;
+} | {
+    after: Date;
+} | {
+    before: Date;
+    after: Date;
+} | {
+    dayOfWeek: number | number[];
+} | ((date: Date) => boolean);

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

@@ -9,9 +9,10 @@
 export declare const formControlTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background";
 /**
  * Date and date-time picker trigger: the form-control chrome, start-aligned,
- * with muted text while empty (`data-empty`).
+ * with muted text while empty (`data-empty`). Intrinsic padding makes one
+ * line 40px tall while longer values wrap and consumer height classes work.
  */
-export declare const pickerTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background justify-start data-[empty=true]:text-muted-foreground";
+export declare const pickerTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background h-auto justify-start py-[calc((--spacing(10)_-_1lh_-_2px)/2)] data-[empty=true]:text-muted-foreground";
 /** Calendar popover body: fits the viewport height and scrolls inside it. */
 export declare const pickerContentClassName = "max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0";
 /** Gutter used when a calendar popover collides with the viewport. */

package/dist/internal/form-control.js

@@ -9,9 +9,10 @@
 export const formControlTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background";
 /**
  * Date and date-time picker trigger: the form-control chrome, start-aligned,
- * with muted text while empty (`data-empty`).
+ * with muted text while empty (`data-empty`). Intrinsic padding makes one
+ * line 40px tall while longer values wrap and consumer height classes work.
  */
-export const pickerTriggerClassName = `${formControlTriggerClassName} justify-start data-[empty=true]:text-muted-foreground`;
+export const pickerTriggerClassName = `${formControlTriggerClassName} h-auto justify-start py-[calc((--spacing(10)_-_1lh_-_2px)/2)] data-[empty=true]:text-muted-foreground`;
 /** Calendar popover body: fits the viewport height and scrolls inside it. */
 export const pickerContentClassName = "max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0";
 /** Gutter used when a calendar popover collides with the viewport. */