atlas-react-kit 0.11.2 → 0.13.0

package/dist/date-picker.js

@@ -1,42 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
-import { format, isSameDay, parseISO } from "date-fns";
+import { format, isSameDay } from "date-fns";
+import { toDate, } from "./internal/date-like.js";
 import { MD_MEDIA_QUERY, useMediaQuery } from "./internal/use-media-query.js";
 import { LazyCalendar } from "./lazy-calendar.js";
-import { PickerClearFooter, PickerShell, } from "./picker-shell.js";
-/**
- * Coerce a date-like value to a local `Date`.
- * Plain calendar dates (`yyyy-MM-dd`) parse as local midnight so they do not
- * shift when the runtime timezone is behind UTC.
- */
-export function toDate(value) {
-    if (value == null || value === "")
-        return undefined;
-    if (value instanceof Date) {
-        return Number.isNaN(value.getTime()) ? undefined : value;
-    }
-    if (typeof value === "number") {
-        const date = new Date(value);
-        return Number.isNaN(date.getTime()) ? undefined : date;
-    }
-    const trimmed = value.trim();
-    const ymd = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
-    if (ymd) {
-        const year = Number(ymd[1]);
-        const month = Number(ymd[2]);
-        const day = Number(ymd[3]);
-        const date = new Date(year, month - 1, day);
-        if (date.getFullYear() !== year ||
-            date.getMonth() !== month - 1 ||
-            date.getDate() !== day) {
-            return undefined;
-        }
-        return date;
-    }
-    const parsed = parseISO(trimmed);
-    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
-}
+import { PickerClearFooter, PickerShell, limitCalendarProps, } from "./picker-shell.js";
+export { toDate };
 /** Format a Date as a timezone-safe calendar date (`yyyy-MM-dd`). */
 export function formatLocalDate(date) {
     return format(date, "yyyy-MM-dd");
@@ -52,15 +22,15 @@ function formatRangeTriggerLabel(from, to, placeholder) {
         return format(from, "PPP");
     return `${format(from, "PPP")} – ${format(to, "PPP")}`;
 }
-function DatePickerSingleButton({ value, onChange, placeholder = "Pick a date", numberOfMonths, defaultMonth, calendarProps, ...shell }) {
+function DatePickerSingleButton({ value, onChange, placeholder = "Pick a date", numberOfMonths, defaultMonth, calendarProps, minDate, maxDate, ...shell }) {
     const [open, setOpen] = React.useState(false);
     const date = toDate(value);
-    return (_jsx(PickerShell, { ...shell, empty: !date, label: date ? format(date, "PPP") : placeholder, dialogLabel: "Choose date", open: open, onOpenChange: setOpen, children: _jsx(LazyCalendar, { ...calendarProps, mode: "single", autoFocus: true, selected: date, defaultMonth: defaultMonth ?? date, numberOfMonths: numberOfMonths, onSelect: (next) => {
+    return (_jsx(PickerShell, { ...shell, empty: !date, label: date ? format(date, "PPP") : placeholder, dialogLabel: "Choose date", open: open, onOpenChange: setOpen, children: _jsx(LazyCalendar, { ...limitCalendarProps(calendarProps, minDate, maxDate), mode: "single", autoFocus: true, selected: date, defaultMonth: defaultMonth ?? date, numberOfMonths: numberOfMonths, onSelect: (next) => {
                 onChange(next);
                 setOpen(false);
             } }) }));
 }
-function DatePickerRangeButton({ value, onChange, placeholder = "Pick a date range", numberOfMonths, defaultMonth, calendarProps, ...shell }) {
+function DatePickerRangeButton({ value, onChange, placeholder = "Pick a date range", numberOfMonths, defaultMonth, calendarProps, minDate, maxDate, ...shell }) {
     const [open, setOpen] = React.useState(false);
     const mdUp = useMediaQuery(MD_MEDIA_QUERY);
     const months = numberOfMonths ?? (mdUp ? 2 : 1);
@@ -76,7 +46,7 @@ function DatePickerRangeButton({ value, onChange, placeholder = "Pick a date ran
             restartRef.current = Boolean(from && to);
         setOpen(next);
     };
-    return (_jsxs(PickerShell, { ...shell, empty: !from, label: formatRangeTriggerLabel(from, to, placeholder), dialogLabel: "Choose dates", open: open, onOpenChange: onOpenChange, children: [_jsx(LazyCalendar, { ...calendarProps, mode: "range", autoFocus: true, selected: selected, defaultMonth: defaultMonth ?? from ?? to, numberOfMonths: months, onSelect: (next, day) => {
+    return (_jsxs(PickerShell, { ...shell, empty: !from, label: formatRangeTriggerLabel(from, to, placeholder), dialogLabel: "Choose dates", open: open, onOpenChange: onOpenChange, children: [_jsx(LazyCalendar, { ...limitCalendarProps(calendarProps, minDate, maxDate), mode: "range", autoFocus: true, selected: selected, defaultMonth: defaultMonth ?? from ?? to, numberOfMonths: months, onSelect: (next, day) => {
                     const range = restartRef.current ? { from: day, to: day } : next;
                     restartRef.current = false;
                     onChange(range);

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

@@ -25,4 +25,4 @@ export declare function resolveTimeStep(step: number | undefined): number;
  * stays on-screen at a 390px width. `className` styles the trigger,
  * `contentClassName` the popover, and `calendarProps` reaches Day Picker.
  */
-export declare function DateTimePickerButton({ value, onChange, timeStep, placeholder, defaultMonth, calendarProps, ...shell }: DateTimePickerButtonProps): React.JSX.Element;
+export declare function DateTimePickerButton({ value, onChange, timeStep, placeholder, defaultMonth, calendarProps, minDate, maxDate, ...shell }: DateTimePickerButtonProps): React.JSX.Element;

package/dist/date-time-picker.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { format } from "date-fns";
 import { LazyCalendar } from "./lazy-calendar.js";
-import { PickerClearFooter, PickerShell, } from "./picker-shell.js";
+import { PickerClearFooter, PickerShell, limitCalendarProps, } from "./picker-shell.js";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "./select.js";
 /** Default clock increment, in minutes. Must divide 60. */
 export const DEFAULT_TIME_STEP = 15;
@@ -68,14 +68,14 @@ function preventDismissForPortaledSelect(event) {
  * stays on-screen at a 390px width. `className` styles the trigger,
  * `contentClassName` the popover, and `calendarProps` reaches Day Picker.
  */
-export function DateTimePickerButton({ value, onChange, timeStep, placeholder = "Pick a date and time", defaultMonth, calendarProps, ...shell }) {
+export function DateTimePickerButton({ value, onChange, timeStep, placeholder = "Pick a date and time", defaultMonth, calendarProps, minDate, maxDate, ...shell }) {
     const [open, setOpen] = React.useState(false);
     const date = value ?? null;
     const step = resolveTimeStep(timeStep);
     const empty = date == null;
     const hourId = React.useId();
     const minuteId = React.useId();
-    return (_jsxs(PickerShell, { ...shell, empty: empty, label: date ? format(date, "PPP p") : placeholder, dialogLabel: "Choose date and time", open: open, onOpenChange: setOpen, onInteractOutside: preventDismissForPortaledSelect, children: [_jsx(LazyCalendar, { ...calendarProps, mode: "single", autoFocus: true, selected: date ?? undefined, defaultMonth: defaultMonth ?? date ?? undefined, onSelect: (next) => {
+    return (_jsxs(PickerShell, { ...shell, empty: empty, label: date ? format(date, "PPP p") : placeholder, dialogLabel: "Choose date and time", open: open, onOpenChange: setOpen, onInteractOutside: preventDismissForPortaledSelect, children: [_jsx(LazyCalendar, { ...limitCalendarProps(calendarProps, minDate, maxDate), mode: "single", autoFocus: true, selected: date ?? undefined, defaultMonth: defaultMonth ?? date ?? undefined, onSelect: (next) => {
                     // Re-clicking a selected day would clear it; require Clear instead
                     // so a time already set is not dropped by an accidental second tap.
                     if (!next)

package/dist/error-boundary.d.ts

@@ -31,6 +31,6 @@ export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBo
     componentDidCatch(error: Error, info: ErrorInfo): void;
     retry: () => void;
     reload: () => void;
-    render(): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+    render(): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
 }
 export {};

package/dist/field.d.ts

@@ -19,7 +19,7 @@ declare function FieldGroup({ className, ...props }: React.ComponentProps<"div">
  * content in a row.
  */
 declare const fieldVariants: (props?: ({
-    orientation?: "horizontal" | "vertical" | "responsive" | null | undefined;
+    orientation?: "horizontal" | "responsive" | "vertical" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 declare function Field({ className, orientation, ...props }: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>): import("react").JSX.Element;
 declare function FieldContent({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;

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

@@ -0,0 +1,31 @@
+import { type ComponentProps, type ReactNode } from "react";
+import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
+/** Props `FormControlField` hands its control: spread them onto it. */
+export type FormControlProps = {
+    id: string;
+    "aria-invalid": true | undefined;
+    "aria-describedby": string | undefined;
+    "aria-required": true | undefined;
+};
+type Props = ErrorTimingProps & 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;
+};
+/**
+ * The `form/*` field layout for a control the kit does not ship (a
+ * combobox, a segmented picker): label with the required marker, optional
+ * hint, the control, and its error, with the same spacing, ids, and error
+ * 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 {};

package/dist/form/control-field.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useId } from "react";
+import { describedBy, descriptionIdFor, FormFieldShell, invalidWhen, metaErrorText, } 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
+ * hint, the control, and its error, with the same spacing, ids, and error
+ * 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 });
+    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,
+        }) }));
+}

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

@@ -1,12 +1,18 @@
 import { type DateLike, type DatePickerCalendarProps } from "../date-picker.js";
-import type { FieldMetaState } from "./field-error.js";
-type Props = {
+import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
+type Props = ErrorTimingProps & {
     value: DateLike;
     onValueChange: (date: Date | undefined) => void;
     label: string;
     meta?: FieldMetaState;
     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). */
@@ -17,5 +23,5 @@ type Props = {
     calendarProps?: DatePickerCalendarProps;
 };
 /** Date picker with built-in field error text and invalid styling. */
-export declare function FormDatePickerField({ onValueChange, label, meta, fieldClassName, ...picker }: Props): import("react").JSX.Element;
+export declare function FormDatePickerField({ onValueChange, label, meta, submitted, showError, required, fieldClassName, ...picker }: Props): import("react").JSX.Element;
 export {};

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

@@ -4,8 +4,8 @@ import { useId } from "react";
 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, fieldClassName, ...picker }) {
-    const errorText = metaErrorText(meta);
+export function FormDatePickerField({ 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, className: fieldClassName, children: _jsx(DatePickerButton, { ...picker, id: id, onChange: onValueChange, ...pickerFieldAria(id, errorText) }) }));
+    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) }) }));
 }

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

@@ -1,12 +1,18 @@
-import type { DatePickerCalendarProps } from "../date-picker.js";
-import type { FieldMetaState } from "./field-error.js";
-type Props = {
+import type { DateLike, DatePickerCalendarProps } from "../date-picker.js";
+import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
+type Props = ErrorTimingProps & {
     value: Date | null;
     onValueChange: (date: Date | null) => void;
     label: string;
     meta?: FieldMetaState;
     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. */
     timeStep?: number;
     /** Forwarded to the date-time picker trigger. */
@@ -19,5 +25,5 @@ type Props = {
     calendarProps?: DatePickerCalendarProps;
 };
 /** Date-time picker with built-in field error text and invalid styling. */
-export declare function FormDateTimePickerField({ onValueChange, label, meta, 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, 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, className: fieldClassName, children: _jsx(DateTimePickerButton, { ...picker, id: id, onChange: onValueChange, ...pickerFieldAria(id, errorText) }) }));
+    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) }) }));
 }

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

@@ -3,6 +3,24 @@ export type FieldErrorMessage = string | {
 } | undefined;
 export type FieldMetaState = {
     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;
 };
 /** First TanStack Form error message for a field, if any. */
 export declare function getFieldErrorMessage(message: FieldErrorMessage): string | undefined;

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

@@ -1,17 +1,29 @@
-import type { ReactNode } from "react";
-import { type FieldMetaState } from "./field-error.js";
+import type { ComponentProps, ReactNode } from "react";
+import { type ErrorTimingProps, type FieldMetaState } 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;
+/**
+ * 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.
@@ -20,9 +32,10 @@ export declare function describedBy(id: string, errorText: string | undefined, .
 /**
  * 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 the error.
+ * picked value), and described by "Required" (a button cannot take
+ * `aria-required`) and the error.
  */
-export declare function pickerFieldAria(id: string, errorText: string | undefined): {
+export declare function pickerFieldAria(id: string, errorText: string | undefined, required?: boolean): {
     "aria-invalid": boolean | undefined;
     "aria-labelledby": string;
     "aria-describedby": string | undefined;
@@ -32,14 +45,20 @@ 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, className, children, }: {
+export declare function FormFieldShell({ id, label, labelAction, description, errorText, labelFor, required, className, children, ...props }: Omit<ComponentProps<"div">, "id" | "children"> & {
     id: string;
     label: string;
     labelAction?: ReactNode;
+    description?: ReactNode;
     errorText: string | undefined;
     labelFor?: boolean;
-    className?: string;
+    required?: boolean;
     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,10 +28,21 @@ 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`;
 }
+/**
+ * Id of the hidden "Required" text `FormFieldShell` renders for a required
+ * control `id`, for controls that cannot carry `required` themselves.
+ */
+export function requiredIdFor(id) {
+    return `${id}-required`;
+}
 /**
  * `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.
@@ -34,13 +54,14 @@ export function describedBy(id, errorText, ...hintIds) {
 /**
  * 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 the error.
+ * picked value), and described by "Required" (a button cannot take
+ * `aria-required`) and the error.
  */
-export function pickerFieldAria(id, errorText) {
+export function pickerFieldAria(id, errorText, required) {
     return {
         "aria-invalid": invalidWhen(errorText),
         "aria-labelledby": `${labelIdFor(id)} ${pickerValueId(id)}`,
-        "aria-describedby": describedBy(id, errorText),
+        "aria-describedby": describedBy(id, errorText, required ? requiredIdFor(id) : undefined),
     };
 }
 /**
@@ -48,9 +69,14 @@ export function pickerFieldAria(id, errorText) {
  * `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, className, children, }) {
-    const labelNode = (_jsx(Label, { id: labelIdFor(id), htmlFor: labelFor ? id : undefined, 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, _jsx(FieldError, { id: errorIdFor(id), text: errorText })] }));
+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), ...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,9 +1,10 @@
+import type { ErrorTimingProps } from "./field-error.js";
 import type { TextFieldApi } 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, className, fieldClassName, previewClassName, }: {
+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
@@ -13,7 +14,8 @@ export declare function FormMarkdownField({ field, id, label, placeholder, rows,
     label: string;
     placeholder?: string;
     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). */

package/dist/form/markdown-field.js

@@ -16,14 +16,14 @@ 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, 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")
             setMode(value);
     }
-    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, labelFor: mode === "write", className: fieldClassName, labelAction: _jsxs(ToggleGroup, { type: "single", value: mode, onValueChange: handleModeChange, variant: "outline", size: "sm", spacing: 0, "aria-label": `${label} mode`, children: [_jsx(ToggleGroupItem, { value: "write", children: "Write" }), _jsx(ToggleGroupItem, { value: "preview", onPointerEnter: preloadMarkdown, onFocus: preloadMarkdown, children: "Preview" })] }), children: mode === "write" ? (_jsx(Textarea, { id: id, value: field.state.value, onChange: onChange, onBlur: field.handleBlur, placeholder: placeholder, rows: rows, className: className, "aria-invalid": invalidWhen(errorText), "aria-describedby": describedBy(id, errorText) })) : (_jsx("div", { "data-slot": "form-markdown-preview", className: cn(fieldSurface, "min-h-16", previewClassName), "aria-live": "polite", children: trimmed ? (_jsx(Suspense, { fallback: _jsx(Spinner, { "aria-label": "Loading preview" }), children: _jsx(Markdown, { content: trimmed }) })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: "Nothing to preview" })) })) }));
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, labelFor: mode === "write", required: required, className: fieldClassName, labelAction: _jsxs(ToggleGroup, { type: "single", value: mode, onValueChange: handleModeChange, variant: "outline", size: "sm", spacing: 0, "aria-label": `${label} mode`, children: [_jsx(ToggleGroupItem, { value: "write", children: "Write" }), _jsx(ToggleGroupItem, { value: "preview", onPointerEnter: preloadMarkdown, onFocus: preloadMarkdown, children: "Preview" })] }), children: mode === "write" ? (_jsx(Textarea, { id: id, value: field.state.value, onChange: onChange, onBlur: field.handleBlur, placeholder: placeholder, rows: rows, required: required, className: className, "aria-invalid": invalidWhen(errorText), "aria-describedby": describedBy(id, errorText) })) : (_jsx("div", { "data-slot": "form-markdown-preview", className: cn(fieldSurface, "min-h-16", previewClassName), "aria-live": "polite", children: trimmed ? (_jsx(Suspense, { fallback: _jsx(Spinner, { "aria-label": "Loading preview" }), children: _jsx(Markdown, { content: trimmed }) })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: "Nothing to preview" })) })) }));
 }

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

@@ -1,11 +1,13 @@
 import { type ReactNode } from "react";
-import type { FieldMetaState } from "./field-error.js";
-type Props = {
+import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
+type Props = ErrorTimingProps & {
     value: string | undefined;
     meta?: FieldMetaState;
     label: string;
     onValueChange: (value: string) => void;
     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). */
@@ -15,5 +17,5 @@ type Props = {
     children: ReactNode;
 };
 /** Select control with built-in field error text and invalid styling. */
-export declare function FormSelectField({ value, meta, label, onValueChange, placeholder, 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, 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, className: fieldClassName, children: _jsxs(Select, { value: value, onValueChange: onValueChange, children: [_jsx(SelectTrigger, { id: id, className: className, "aria-invalid": invalidWhen(errorText), "aria-describedby": describedBy(id, errorText), children: _jsx(SelectValue, { placeholder: placeholder }) }), _jsx(SelectContent, { className: contentClassName, children: children })] }) }));
+    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,4 +1,4 @@
-import type { FieldMetaState } from "./field-error.js";
+import type { ErrorTimingProps, FieldMetaState } from "./field-error.js";
 export type TextFieldApi = {
     name: string;
     state: {
@@ -8,7 +8,7 @@ export type TextFieldApi = {
     handleChange: (value: string) => void;
     handleBlur: () => void;
 };
-export declare function FormTextField({ field, id, label, placeholder, description, autoFocus, multiline, rows, inputType, showError, autoComplete, required, minLength, className, fieldClassName, }: {
+export declare function FormTextField({ field, id, label, placeholder, description, autoFocus, multiline, rows, inputType, showError, submitted, autoComplete, required, minLength, className, fieldClassName, }: ErrorTimingProps & {
     field: TextFieldApi;
     /**
      * Control id the label points at. Defaults to `field.name`; pass a unique
@@ -25,9 +25,8 @@ export declare function FormTextField({ field, id, label, placeholder, descripti
     /** Textarea rows when `multiline` is set. */
     rows?: number;
     inputType?: "text" | "email" | "password" | "date" | "datetime-local" | "time" | "number";
-    /** When true (default), shows meta.errors and aria-invalid styling. */
-    showError?: boolean;
     autoComplete?: string;
+    /** Sets `required` on the control and marks the label. */
     required?: boolean;
     minLength?: number;
     /** Forwarded to the input or textarea. */

package/dist/form/text-field.js

@@ -1,13 +1,13 @@
 "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";
+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 +21,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, 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/internal/date-like.d.ts

@@ -0,0 +1,31 @@
+/** A date the pickers accept: a `Date`, `yyyy-MM-dd`, ISO text, or a timestamp. */
+export type DateLike = Date | string | number | null | undefined;
+/**
+ * Coerce a date-like value to a local `Date`.
+ * Plain calendar dates (`yyyy-MM-dd`) parse as local midnight so they do not
+ * 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);