atlas-react-kit 1.2.0 → 1.2.2

package/dist/date-time-picker.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { format } from "date-fns";
+import { labelText } from "./internal/styles.js";
 import { PickerShell } from "./picker-shell.js";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "./select.js";
 /** Default clock increment, in minutes. Must divide 60. */
@@ -71,7 +72,7 @@ export function DateTimePickerButton({ value, onValueChange, onChange, timeStep,
                     return;
                 emit?.(combineDateAndTime(next, date?.getHours() ?? 0, date?.getMinutes() ?? 0));
             },
-        }, onClear: () => emit?.(null), clearDisabled: empty, children: _jsxs("div", { role: "group", "aria-label": "Time", "data-slot": "date-time-picker-time", className: "flex min-w-0 flex-col gap-2 border-t p-3", children: [_jsx("p", { className: "text-xs font-semibold tracking-wide uppercase", children: "Time" }), _jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [_jsxs(Select, { value: date ? padTimePart(date.getHours()) : undefined, onValueChange: (nextHour) => {
+        }, onClear: () => emit?.(null), clearDisabled: empty, children: _jsxs("div", { role: "group", "aria-label": "Time", "data-slot": "date-time-picker-time", className: "flex min-w-0 flex-col gap-2 border-t p-3", children: [_jsx("p", { className: labelText, children: "Time" }), _jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [_jsxs(Select, { value: date ? padTimePart(date.getHours()) : undefined, onValueChange: (nextHour) => {
                                 if (!date)
                                     return;
                                 emit?.(combineDateAndTime(date, Number(nextHour), date.getMinutes()));

package/dist/dialog.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Dialog as DialogPrimitive } from "radix-ui";
 import { overlayFade, overlayFadeZoom, overlaySurface, } from "./internal/overlay-styles.js";
+import { descriptionText } from "./internal/styles.js";
 import { cn } from "./utils.js";
 import { Button } from "./button.js";
 import { XIcon } from "lucide-react";
@@ -36,6 +37,6 @@ function DialogTitle({ className, ...props }) {
     return (_jsx(DialogPrimitive.Title, { "data-slot": "dialog-title", className: cn("pr-[var(--dialog-close-gutter,0px)] font-heading text-lg leading-none font-semibold tracking-wider uppercase", className), ...props }));
 }
 function DialogDescription({ className, ...props }) {
-    return (_jsx(DialogPrimitive.Description, { "data-slot": "dialog-description", className: cn("mt-0.5 text-sm leading-relaxed text-muted-foreground *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground", className), ...props }));
+    return (_jsx(DialogPrimitive.Description, { "data-slot": "dialog-description", className: cn("mt-0.5", descriptionText, "*:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground", className), ...props }));
 }
 export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, };

package/dist/dropdown-menu.js

@@ -3,12 +3,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui";
 import { CheckIcon, ChevronRightIcon } from "lucide-react";
-import { menuLabel, optionRow, overlayFadeZoom, overlaySideSlide, overlaySurface, } from "./internal/overlay-styles.js";
+import { anchoredPanel, menuLabel, optionRow, OVERLAY_COLLISION_PADDING, OVERLAY_SIDE_OFFSET, } from "./internal/overlay-styles.js";
 import { dataDisabledState, inlineIcon, optionState, } from "./internal/styles.js";
 import { cn } from "./utils.js";
 /** Menu row: the shared option row with menu padding and the inset slot. */
 const menuItemClassName = cn(optionRow, optionState.focus, dataDisabledState, inlineIcon.default, "pr-3 data-inset:pl-9");
-const menuContentClassName = cn(overlaySurface, overlaySideSlide, overlayFadeZoom, "z-50 overflow-x-hidden overflow-y-auto p-1");
+/** The check or dot in the inset of a checkbox or radio item. */
+const menuIndicatorClassName = "pointer-events-none absolute left-3 flex size-3.5 items-center justify-center";
+const menuContentClassName = cn(anchoredPanel, "z-50 overflow-x-hidden overflow-y-auto p-1");
 /** Action menu for commands (row actions, overflow menus). Use `Select` to pick a value. */
 function DropdownMenu({ ...props }) {
     return _jsx(DropdownMenuPrimitive.Root, { "data-slot": "dropdown-menu", ...props });
@@ -19,7 +21,7 @@ function DropdownMenuPortal({ ...props }) {
 function DropdownMenuTrigger({ ...props }) {
     return (_jsx(DropdownMenuPrimitive.Trigger, { "data-slot": "dropdown-menu-trigger", ...props }));
 }
-function DropdownMenuContent({ className, align = "start", sideOffset = 4, collisionPadding = 8, ...props }) {
+function DropdownMenuContent({ className, align = "start", sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = OVERLAY_COLLISION_PADDING, ...props }) {
     return (_jsx(DropdownMenuPrimitive.Portal, { children: _jsx(DropdownMenuPrimitive.Content, { "data-slot": "dropdown-menu-content", align: align, sideOffset: sideOffset, collisionPadding: collisionPadding, className: cn(menuContentClassName, "max-h-(--radix-dropdown-menu-content-available-height) origin-(--radix-dropdown-menu-content-transform-origin)", className), ...props }) }));
 }
 function DropdownMenuGroup({ ...props }) {
@@ -29,13 +31,13 @@ function DropdownMenuItem({ className, inset, variant = "default", ...props }) {
     return (_jsx(DropdownMenuPrimitive.Item, { "data-slot": "dropdown-menu-item", "data-inset": inset || undefined, "data-variant": variant, className: cn(menuItemClassName, "data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive", className), ...props }));
 }
 function DropdownMenuCheckboxItem({ className, children, checked, ...props }) {
-    return (_jsxs(DropdownMenuPrimitive.CheckboxItem, { "data-slot": "dropdown-menu-checkbox-item", className: cn(menuItemClassName, "pl-9", className), checked: checked, ...props, children: [_jsx("span", { className: "pointer-events-none absolute left-3 flex size-3.5 items-center justify-center", children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx(CheckIcon, {}) }) }), children] }));
+    return (_jsxs(DropdownMenuPrimitive.CheckboxItem, { "data-slot": "dropdown-menu-checkbox-item", className: cn(menuItemClassName, "pl-9", className), checked: checked, ...props, children: [_jsx("span", { className: menuIndicatorClassName, children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx(CheckIcon, {}) }) }), children] }));
 }
 function DropdownMenuRadioGroup({ ...props }) {
     return (_jsx(DropdownMenuPrimitive.RadioGroup, { "data-slot": "dropdown-menu-radio-group", ...props }));
 }
 function DropdownMenuRadioItem({ className, children, ...props }) {
-    return (_jsxs(DropdownMenuPrimitive.RadioItem, { "data-slot": "dropdown-menu-radio-item", className: cn(menuItemClassName, "pl-9", className), ...props, children: [_jsx("span", { className: "pointer-events-none absolute left-3 flex size-3.5 items-center justify-center", children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx("span", { className: "block size-1.5 rounded-full bg-current" }) }) }), children] }));
+    return (_jsxs(DropdownMenuPrimitive.RadioItem, { "data-slot": "dropdown-menu-radio-item", className: cn(menuItemClassName, "pl-9", className), ...props, children: [_jsx("span", { className: menuIndicatorClassName, children: _jsx(DropdownMenuPrimitive.ItemIndicator, { children: _jsx("span", { className: "block size-1.5 rounded-full bg-current" }) }) }), children] }));
 }
 function DropdownMenuLabel({ className, inset, ...props }) {
     return (_jsx(DropdownMenuPrimitive.Label, { "data-slot": "dropdown-menu-label", "data-inset": inset || undefined, className: cn(menuLabel, "data-inset:pl-9", className), ...props }));

package/dist/field.d.ts

@@ -31,10 +31,13 @@ declare function FieldSeparator({ children, className, ...props }: React.Compone
     /** Optional text shown in a gap in the middle of the line, e.g. "Or". */
     children?: React.ReactNode;
 }): import("react").JSX.Element;
+/** One error as form libraries report it; `FieldError` shows its `message`. */
+type FieldErrorItem = {
+    message?: string;
+} | undefined;
 declare function FieldError({ className, children, errors, ...props }: React.ComponentProps<"div"> & {
     /** Errors to list, deduplicated by message; `children` replaces them. */
-    errors?: Array<{
-        message?: string;
-    } | undefined>;
+    errors?: FieldErrorItem[];
 }): import("react").JSX.Element | null;
 export { Field, FieldLabel, FieldDescription, FieldError, FieldGroup, FieldLegend, FieldSeparator, FieldSet, FieldContent, FieldTitle, };
+export type { FieldErrorItem };

package/dist/field.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { cva } from "class-variance-authority";
+import { labelText } from "./internal/styles.js";
 import { cn } from "./utils.js";
 import { Label } from "./label.js";
 import { Separator } from "./separator.js";
@@ -9,7 +10,7 @@ function FieldSet({ className, ...props }) {
     return (_jsx("fieldset", { "data-slot": "field-set", className: cn("flex flex-col gap-6 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3", className), ...props }));
 }
 function FieldLegend({ className, variant = "legend", ...props }) {
-    return (_jsx("legend", { "data-slot": "field-legend", "data-variant": variant, className: cn("mb-3 font-semibold uppercase data-[variant=label]:text-xs data-[variant=legend]:text-xs", className), ...props }));
+    return (_jsx("legend", { "data-slot": "field-legend", "data-variant": variant, className: cn("mb-3", labelText, className), ...props }));
 }
 /**
  * Stack of fields and the `@container/field-group` that responsive fields
@@ -49,7 +50,7 @@ function FieldLabel({ className, ...props }) {
     return (_jsx(Label, { "data-slot": "field-label", className: cn("group/field-label peer/field-label flex w-fit gap-2 leading-relaxed group-data-[disabled=true]/field:opacity-50 has-data-checked:border-primary/30 has-data-checked:bg-selected has-[>[data-slot=field]]:rounded-none has-[>[data-slot=field]]:border *:data-[slot=field]:p-4 dark:has-data-checked:border-primary/20 dark:has-data-checked:bg-selected", "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col", className), ...props }));
 }
 function FieldTitle({ className, ...props }) {
-    return (_jsx("div", { "data-slot": "field-label", className: cn("flex w-fit items-center gap-2 text-xs font-semibold uppercase group-data-[disabled=true]/field:opacity-50 in-data-[slot=field-label]:font-semibold", className), ...props }));
+    return (_jsx("div", { "data-slot": "field-label", className: cn(labelText, "flex w-fit items-center gap-2 group-data-[disabled=true]/field:opacity-50 in-data-[slot=field-label]:font-semibold", className), ...props }));
 }
 function FieldDescription({ className, ...props }) {
     return (_jsx("p", { "data-slot": "field-description", className: cn("text-left text-sm leading-normal font-normal tracking-normal text-muted-foreground normal-case group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5", "last:mt-0 nth-last-2:-mt-1", "[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-selected-foreground", className), ...props }));

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

@@ -1,4 +1,4 @@
-import { type FormFieldBaseProps, type FormFieldDescriptionProps, type FormFieldMetaProps } from "./field-error.js";
+import type { FormFieldBaseProps, FormFieldDescriptionProps, FormFieldMetaProps } from "./field-error.js";
 type CheckboxFieldProps = FormFieldBaseProps & FormFieldMetaProps & FormFieldDescriptionProps & {
     /** Whether the box is checked. */
     checked: boolean;
@@ -6,8 +6,6 @@ type CheckboxFieldProps = FormFieldBaseProps & FormFieldMetaProps & FormFieldDes
     onCheckedChange: (checked: boolean) => void;
     /** Called when the checkbox loses focus; pass the field's blur handler. */
     onBlur?: () => void;
-    /** Checkbox id the label points at. Defaults to a generated id. */
-    id?: string;
     /** Sets `required` on the checkbox and marks the label. */
     required?: boolean;
     /** Disables the checkbox. */
@@ -21,7 +19,7 @@ type CheckboxFieldProps = FormFieldBaseProps & FormFieldMetaProps & FormFieldDes
  * One boolean as a labelled checkbox, with an optional hint and the same
  * error text and timing as the other `form/*` fields.
  */
-export declare function FormCheckboxField({ checked, onCheckedChange, onBlur, label, description, id: idProp, meta, submitted, showError, required, disabled, controlPosition, className, fieldClassName, }: CheckboxFieldProps): import("react").JSX.Element;
+export declare function FormCheckboxField({ checked, onCheckedChange, onBlur, fieldName, label, description, meta, submitted, showError, required, disabled, controlPosition, className, fieldClassName, }: CheckboxFieldProps): import("react").JSX.Element;
 export type CheckboxGroupOption<T extends string | number> = {
     /** Value added to the group's `value` while this box is checked. */
     value: T;
@@ -41,5 +39,5 @@ type CheckboxGroupFieldProps<T extends string | number> = FormFieldBaseProps & F
     className?: string;
 };
 /** Several values from a short list, as a labelled set of checkboxes. */
-export declare function FormCheckboxGroupField<T extends string | number>({ label, description, options, value, onValueChange, meta, submitted, showError, disabled, className, fieldClassName, }: CheckboxGroupFieldProps<T>): import("react").JSX.Element;
+export declare function FormCheckboxGroupField<T extends string | number>({ fieldName, label, description, options, value, onValueChange, meta, submitted, showError, disabled, className, fieldClassName, }: CheckboxGroupFieldProps<T>): import("react").JSX.Element;
 export {};

package/dist/form/checkbox-field.js

@@ -1,29 +1,23 @@
 "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 { Field, FieldContent, FieldLabel, FieldLegend } from "../field.js";
+import { fieldNameProps } from "../internal/form-control.js";
 import { cn } from "../utils.js";
-import { FieldError, } from "./field-error.js";
-import { describedBy, descriptionIdFor, errorIdFor, invalidWhen, metaErrorText, } from "./field-shell.js";
+import { fieldAria, FormFieldDescription, FormFieldFrame, useFormField, } 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 }));
+export function FormCheckboxField({ checked, onCheckedChange, onBlur, fieldName, label, description, meta, submitted, showError, required, disabled, controlPosition = "start", className, fieldClassName, }) {
+    const { id, errorText } = useFormField(meta, { submitted, showError });
+    const checkbox = (_jsx(Checkbox, { id: id, ...fieldNameProps(fieldName), checked: checked, onCheckedChange: (next) => onCheckedChange(next === true), onBlur: onBlur, disabled: disabled, required: required, ...fieldAria(id, errorText, { description, required }), 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 })] }));
+    return (_jsx(FormFieldFrame, { id: id, errorText: errorText, className: fieldClassName, children: _jsxs(Field, { orientation: "horizontal", children: [controlPosition === "start" ? checkbox : null, description ? (_jsxs(FieldContent, { children: [labelNode, _jsx(FormFieldDescription, { id: id, children: description })] })) : (labelNode), controlPosition === "end" ? checkbox : null] }) }));
 }
 /** 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;
+export function FormCheckboxGroupField({ fieldName, label, description, options, value, onValueChange, meta, submitted, showError, disabled, className, fieldClassName, }) {
+    const { id, errorText } = useFormField(meta, { submitted, showError });
     function toggle(option, on) {
         const next = new Set(value);
         if (on)
@@ -32,8 +26,8 @@ export function FormCheckboxGroupField({ label, description, options, value, onV
             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 })] }));
+    return (_jsx(FormFieldFrame, { asChild: true, id: id, errorText: errorText, className: fieldClassName, children: _jsxs("fieldset", { ...fieldAria(id, errorText, { description }), children: [_jsx(FieldLegend, { variant: "label", className: "mb-0", children: label }), description ? (_jsx(FormFieldDescription, { id: id, 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, index) => {
+                        const optionId = `${id}-${option.value}`;
+                        return (_jsxs(Field, { orientation: "horizontal", children: [_jsx(Checkbox, { id: optionId, ...fieldNameProps(index === 0 ? fieldName : undefined), checked: value.includes(option.value), onCheckedChange: (next) => toggle(option.value, next === true), disabled: disabled }), _jsx(FieldLabel, { htmlFor: optionId, children: option.label })] }, option.value));
+                    }) })] }) }));
 }

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

@@ -1,4 +1,4 @@
-import { type ComponentProps } from "react";
+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"> & {
@@ -9,5 +9,5 @@ type Props = FormFieldBaseProps & FormFieldMetaProps & FormFieldDescriptionProps
  * `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 declare function FormComboboxField({ fieldName, label, description, meta, submitted, showError, required, fieldClassName, ...props }: Props): import("react").JSX.Element;
 export {};

package/dist/form/combobox-field.js

@@ -1,14 +1,13 @@
 "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";
+import { fieldNameProps } from "../internal/form-control.js";
+import { fieldAria, FormFieldShell, useFormField } 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) }) }));
+export function FormComboboxField({ fieldName, label, description, meta, submitted, showError, required, fieldClassName, ...props }) {
+    const { id, errorText } = useFormField(meta, { submitted, showError });
+    return (_jsx(FormFieldShell, { id: id, label: label, description: description, errorText: errorText, required: required, className: fieldClassName, children: _jsx(Combobox, { ...props, id: id, ...fieldNameProps(fieldName), ...fieldAria(id, errorText, { description, required }) }) }));
 }

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

@@ -1,9 +1,11 @@
-import { type ComponentProps, type ReactNode } from "react";
+import type { ComponentProps, ReactNode } from "react";
 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. */
+    /** Generated id the label points at. */
     id: string;
+    /** The field's `fieldName`, for `focusFirstInvalid`; `undefined` without one. */
+    "data-field-name": string | undefined;
     /** `true` while the field shows error text. */
     "aria-invalid": true | undefined;
     /** Ids of the hint and the error text, when shown. */
@@ -12,8 +14,6 @@ export type FormControlProps = {
     "aria-required": true | undefined;
 };
 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;
     /** Marks the label and passes `aria-required` to the control. */
     required?: boolean;
     /** Renders the control from the id and ARIA props it should carry. */
@@ -26,5 +26,5 @@ type Props = Omit<FormFieldBaseProps, "fieldClassName"> & FormFieldMetaProps & F
  * timing as `FormTextField`. `className` and other div props go to the
  * wrapper (`data-slot="form-field"`).
  */
-export declare function FormControlField({ id: idProp, label, description, required, meta, submitted, showError, children, ...props }: Props): import("react").JSX.Element;
+export declare function FormControlField({ fieldName, label, description, required, meta, submitted, showError, children, ...props }: Props): import("react").JSX.Element;
 export {};

package/dist/form/control-field.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useId } from "react";
-import { describedBy, descriptionIdFor, FormFieldShell, invalidWhen, metaErrorText, } from "./field-shell.js";
+import { fieldNameProps } from "../internal/form-control.js";
+import { fieldAria, FormFieldShell, useFormField } from "./field-shell.js";
 /**
  * The `form/*` field layout for a control the kit does not ship (a
  * combobox, a segmented picker): label with the required marker, optional
@@ -9,14 +9,11 @@ import { describedBy, descriptionIdFor, FormFieldShell, invalidWhen, metaErrorTe
  * timing as `FormTextField`. `className` and other div props go to the
  * wrapper (`data-slot="form-field"`).
  */
-export function FormControlField({ id: idProp, label, description, required, meta, submitted, showError, children, ...props }) {
-    const generatedId = useId();
-    const id = idProp ?? generatedId;
-    const errorText = metaErrorText(meta, { submitted, showError });
+export function FormControlField({ fieldName, label, description, required, meta, submitted, showError, children, ...props }) {
+    const { id, errorText } = useFormField(meta, { submitted, showError });
     return (_jsx(FormFieldShell, { ...props, id: id, label: label, description: description, errorText: errorText, required: required, children: children({
             id,
-            "aria-invalid": invalidWhen(errorText),
-            "aria-describedby": describedBy(id, errorText, description ? descriptionIdFor(id) : undefined),
-            "aria-required": required || undefined,
+            ...fieldNameProps(fieldName),
+            ...fieldAria(id, errorText, { description, required }),
         }) }));
 }

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

@@ -14,5 +14,5 @@ type Props = PickerFieldBaseProps & {
     clearable?: boolean;
 };
 /** Date picker with built-in field error text and invalid styling. */
-export declare function FormDatePickerField({ id: idProp, onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }: Props): import("react").JSX.Element;
+export declare function FormDatePickerField(props: Props): import("react").JSX.Element;
 export {};

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

@@ -1,12 +1,8 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useId } from "react";
 import { DatePickerButton } from "../date-picker.js";
-import { FormFieldShell, metaErrorText, pickerFieldAria, } from "./field-shell.js";
+import { FormPickerField } from "./field-shell.js";
 /** Date picker with built-in field error text and invalid styling. */
-export function FormDatePickerField({ id: idProp, onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }) {
-    const errorText = metaErrorText(meta, { submitted, showError });
-    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) }) }));
+export function FormDatePickerField(props) {
+    return _jsx(FormPickerField, { field: props, picker: DatePickerButton });
 }

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

@@ -10,5 +10,5 @@ type Props = PickerFieldBaseProps & {
     timeStep?: number;
 };
 /** Date-time picker with built-in field error text and invalid styling. */
-export declare function FormDateTimePickerField({ id: idProp, onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }: Props): import("react").JSX.Element;
+export declare function FormDateTimePickerField(props: Props): import("react").JSX.Element;
 export {};

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

@@ -1,12 +1,8 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useId } from "react";
 import { DateTimePickerButton } from "../date-time-picker.js";
-import { FormFieldShell, metaErrorText, pickerFieldAria, } from "./field-shell.js";
+import { FormPickerField } from "./field-shell.js";
 /** Date-time picker with built-in field error text and invalid styling. */
-export function FormDateTimePickerField({ id: idProp, onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }) {
-    const errorText = metaErrorText(meta, { submitted, showError });
-    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) }) }));
+export function FormDateTimePickerField(props) {
+    return _jsx(FormPickerField, { field: props, picker: DateTimePickerButton });
 }

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

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
-export type FieldErrorMessage = string | {
-    message?: string;
-} | undefined;
+import type { FieldErrorItem } from "../field.js";
+/** An error as TanStack Form reports it: text, or an error with a `message`. */
+export type FieldErrorMessage = string | FieldErrorItem;
 export type FieldMetaState = {
     /** Validation errors for the field; the `form/*` fields show the first. */
     errors: FieldErrorMessage[];
@@ -38,13 +38,22 @@ export type FormFieldBaseProps = ErrorTimingProps & {
      */
     fieldClassName?: string;
 };
-/** Error meta for the `form/*` fields that are not bound to a `field` API. */
+/**
+ * What the `form/*` fields that are not bound to a `field` API take in its
+ * place: its meta and its name.
+ */
 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 field's name (TanStack Form's `field.name`). Put on the control as
+     * `data-field-name`, so `focusFirstInvalid` can find it. Leave it out and
+     * the field is not a focus target.
+     */
+    fieldName?: string;
 };
 /** The optional hint the `form/*` fields render under the label. */
 export type FormFieldDescriptionProps = {

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

@@ -1,41 +1,41 @@
-import type { ComponentProps, ReactNode } from "react";
+import { type ComponentProps, type ComponentType, type ReactNode } from "react";
 import type { DateLike, DatePickerCalendarProps } from "../date-picker.js";
+import type { AsChildProps } from "../internal/as-child.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
- * get the same shell through the public `FormControlField`.
+ * The error text a `form/*` field shows (`metaErrorText`) and its control
+ * id. The id is generated per field, so two forms that share a field name
+ * (login and sign-up `email`) never share an id, and each label, hint, and
+ * error links to its own control.
  */
+export declare function useFormField(meta: FieldMetaState | undefined, timing: ErrorTimingProps): {
+    id: string;
+    errorText: 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;
-/**
- * `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.
+ * ARIA for a field's control, from the ids `FormFieldShell` renders:
+ * invalid while there is error text, described by the hint, the hidden
+ * "Required" text, and the error. `required: "described"` is for a button
+ * trigger, which cannot take `aria-required`; leave `required` out where
+ * the control carries native `required`. `labelledBy: "label"` names a
+ * group; `"label-value"` reads a picker "label, value".
  */
-export declare function describedBy(id: string, errorText: string | undefined, ...hintIds: Array<string | undefined>): string | undefined;
+export declare function fieldAria(id: string, errorText: string | undefined, { description, required, labelledBy, }?: {
+    /** The field's hint; when set, the control is described by it. */
+    description?: ReactNode;
+    required?: boolean | "described";
+    labelledBy?: "label" | "label-value";
+}): {
+    "aria-invalid": true | undefined;
+    "aria-describedby": string | undefined;
+    "aria-required": true | undefined;
+    "aria-labelledby"?: 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. */
@@ -51,30 +51,45 @@ export type PickerFieldBaseProps = FormFieldBaseProps & FormFieldMetaProps & {
     /** Day Picker options forwarded to the calendar (disabled days, etc.). */
     calendarProps?: DatePickerCalendarProps;
 };
+/** The props a date or date-time field keeps for its shell, not the picker. */
+type PickerFieldOwnKey = "fieldName" | "label" | "meta" | "submitted" | "showError" | "required" | "fieldClassName";
 /**
- * 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
- * picked value), and described by "Required" (a button cannot take
- * `aria-required`) and the error.
+ * The date and date-time fields: `picker` (the trigger) in a
+ * `FormFieldShell`, given every prop of `field` the shell does not take. A
+ * button cannot carry `required`, so the trigger is described by the hidden
+ * "Required" text and reads "label, value".
  */
-export declare function pickerFieldAria(id: string, errorText: string | undefined, required?: boolean): {
-    "aria-invalid": boolean | undefined;
-    "aria-labelledby": string;
-    "aria-describedby": string | undefined;
-};
+export declare function FormPickerField<P extends PickerFieldBaseProps>({ field, picker: Picker, }: {
+    /** The field's props. */
+    field: P;
+    /** The picker trigger. */
+    picker: ComponentType<Omit<P, PickerFieldOwnKey> & {
+        id: string;
+        "data-field-name"?: string;
+    } & ReturnType<typeof fieldAria>>;
+}): import("react").JSX.Element;
+/**
+ * Every `form/*` field's wrapper (`data-slot="form-field"`): children with
+ * the field spacing, then the error text. `asChild` makes the one child the
+ * wrapper (the checkbox group's fieldset).
+ */
+export declare function FormFieldFrame({ id, errorText, asChild, className, children, ...props }: Omit<ComponentProps<"div">, "id"> & AsChildProps & {
+    /** Id of the control; the error id derives from it. */
+    id: string;
+    /** Error text under the children; `undefined` shows none. */
+    errorText: string | undefined;
+}): import("react").JSX.Element;
+/** A field's hint, with id `descriptionIdFor(id)`. */
+export declare function FormFieldDescription({ id, children, }: {
+    id: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
 /**
- * Label, control, and error text stacked with the kit's field spacing.
- * `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.
- * `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.
+ * Label, hint, control, and error in a `FormFieldFrame`. `labelAction` sits
+ * on the label's row; `labelFor={false}` when the control is not rendered
+ * (Markdown preview). `required` marks the label only.
  */
-export declare function FormFieldShell({ id, label, labelAction, description, errorText, labelFor, required, className, children, ...props }: Omit<ComponentProps<"div">, "id" | "children"> & {
+export declare function FormFieldShell({ id, label, labelAction, description, errorText, labelFor, required, 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. */
@@ -91,3 +106,4 @@ export declare function FormFieldShell({ id, label, labelAction, description, er
     required?: boolean;
     children: ReactNode;
 }): import("react").JSX.Element;
+export {};