atlas-react-kit 0.12.0 → 1.0.0

package/dist/combobox.js

@@ -53,7 +53,6 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
     const [open, setOpen] = React.useState(false);
     const [query, setQuery] = React.useState("");
     const [highlight, setHighlight] = React.useState(0);
-    const inputRef = React.useRef(null);
     const listId = React.useId();
     const generatedId = React.useId();
     const triggerId = id ?? generatedId;
@@ -101,12 +100,6 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
         const selectedIndex = resolvedOptions.findIndex((option) => option.value === value);
         setHighlight(selectedIndex >= 0 ? selectedIndex : 0);
     };
-    React.useEffect(() => {
-        if (!open)
-            return;
-        const frame = window.requestAnimationFrame(() => inputRef.current?.focus());
-        return () => window.cancelAnimationFrame(frame);
-    }, [open]);
     const onQueryChange = onInputChange((next) => {
         setQuery(next);
         setHighlight(0);
@@ -141,7 +134,7 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
             },
         });
     };
-    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { ...props, id: triggerId, type: "button", variant: "outline", role: "combobox", "aria-expanded": open, "aria-controls": listId, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, onKeyDown: onTriggerKeyDown, className: cn(formControlTriggerClassName, "justify-between", !selected && "text-muted-foreground", className), children: [_jsx("span", { className: "truncate", children: selected?.label ?? placeholder }), _jsx(ChevronDownIcon, { "data-icon": "inline-end", className: "opacity-50" })] }) }), _jsxs(PopoverContent, { align: "start", className: cn("w-[var(--radix-popover-trigger-width)] gap-0 rounded-none p-0", contentClassName), children: [_jsx("div", { "data-slot": "combobox-search", className: "border-b p-2", children: _jsx(Input, { ref: inputRef, value: query, onChange: onQueryChange, onKeyDown: onSearchKeyDown, placeholder: searchPlaceholder, "aria-label": searchPlaceholder, "aria-autocomplete": "list", "aria-controls": listId, "aria-activedescendant": activeOption ? listboxOptionId(listId, highlight) : undefined }) }), _jsx("ul", { id: listId, role: "listbox", "data-slot": "combobox-list", "aria-label": ariaLabelledBy ? undefined : ariaLabel, "aria-labelledby": ariaLabelledBy ?? (ariaLabel ? undefined : triggerId), className: empty
+    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { ...props, id: triggerId, type: "button", variant: "outline", role: "combobox", "aria-expanded": open, "aria-controls": listId, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, onKeyDown: onTriggerKeyDown, className: cn(formControlTriggerClassName, "justify-between", !selected && "text-muted-foreground", className), children: [_jsx("span", { className: "truncate", children: selected?.label ?? placeholder }), _jsx(ChevronDownIcon, { "data-icon": "inline-end", className: "opacity-50" })] }) }), _jsxs(PopoverContent, { align: "start", className: cn("w-[var(--radix-popover-trigger-width)] gap-0 rounded-none p-0", contentClassName), children: [_jsx("div", { "data-slot": "combobox-search", className: "border-b p-2", children: _jsx(Input, { value: query, onChange: onQueryChange, onKeyDown: onSearchKeyDown, placeholder: searchPlaceholder, "aria-label": searchPlaceholder, "aria-autocomplete": "list", "aria-controls": listId, "aria-activedescendant": activeOption ? listboxOptionId(listId, highlight) : undefined }) }), _jsx("ul", { id: listId, role: "listbox", "data-slot": "combobox-list", "aria-label": ariaLabelledBy ? undefined : ariaLabel, "aria-labelledby": ariaLabelledBy ?? (ariaLabel ? undefined : triggerId), className: empty
                             ? "sr-only"
                             : cn("max-h-60 overflow-y-auto p-1", listClassName), children: list.map((option, index) => {
                             const isCreate = createOption != null && option === createOption;

package/dist/date-picker.d.ts

@@ -1,13 +1,13 @@
 import * as React from "react";
-import type { DateRange } from "react-day-picker";
-import { toDate, type DateLike } from "./internal/date-like.js";
+import { toDate, type DateLike, type DateMatcher, type DateRange } from "./internal/date-like.js";
 import { type PickerCalendarProps, type PickerTriggerProps } from "./picker-shell.js";
-export type { DateRange };
-export type { DateLike };
+export type { DateLike, DateMatcher, DateRange };
 export { toDate };
 /** From/to value for `DatePickerButton` in range mode; each side is `DateLike`. */
 export type DatePickerRangeValue = {
+    /** First day of the range. */
     from?: DateLike;
+    /** Last day of the range; missing while only the start is picked. */
     to?: DateLike;
 };
 /** Format a Date as a timezone-safe calendar date (`yyyy-MM-dd`). */
@@ -22,14 +22,24 @@ type DatePickerSharedProps = PickerTriggerProps & {
     numberOfMonths?: number;
 };
 export type DatePickerSingleProps = DatePickerSharedProps & {
+    /** Pick one day. Default `"single"`. */
     mode?: "single";
+    /** Controlled day, as a `Date` or `yyyy-MM-dd`. Omitted is empty. */
     value?: DateLike;
-    onChange: (date: Date | undefined) => void;
+    /** Called with the picked day, or `undefined` on Clear. */
+    onValueChange?: (date: Date | undefined) => void;
+    /** @deprecated Use `onValueChange`; `onChange` keeps working until 2.0. */
+    onChange?: (date: Date | undefined) => void;
 };
 export type DatePickerRangeProps = DatePickerSharedProps & {
+    /** Pick a from/to range of days. */
     mode: "range";
+    /** Controlled range; each side is a `Date` or `yyyy-MM-dd`. Omitted is empty. */
     value?: DatePickerRangeValue;
-    onChange: (range: DateRange | undefined) => void;
+    /** Called on every range click, or with `undefined` on Clear. */
+    onValueChange?: (range: DateRange | undefined) => void;
+    /** @deprecated Use `onValueChange`; `onChange` keeps working until 2.0. */
+    onChange?: (range: DateRange | undefined) => void;
 };
 export type DatePickerButtonProps = DatePickerSingleProps | DatePickerRangeProps;
 /**

package/dist/date-picker.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { format, isSameDay } from "date-fns";
-import { toDate } from "./internal/date-like.js";
+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, limitCalendarProps, } from "./picker-shell.js";
@@ -22,41 +22,34 @@ 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, minDate, maxDate, ...shell }) {
+function DatePickerSingleButton({ value, onValueChange, onChange, placeholder = "Pick a date", numberOfMonths, defaultMonth, calendarProps, minDate, maxDate, ...shell }) {
     const [open, setOpen] = React.useState(false);
+    const emit = onValueChange ?? onChange;
     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, { ...limitCalendarProps(calendarProps, minDate, maxDate), mode: "single", autoFocus: true, selected: date, defaultMonth: defaultMonth ?? date, numberOfMonths: numberOfMonths, onSelect: (next) => {
-                onChange(next);
+                emit?.(next);
                 setOpen(false);
             } }) }));
 }
-function DatePickerRangeButton({ value, onChange, placeholder = "Pick a date range", numberOfMonths, defaultMonth, calendarProps, minDate, maxDate, ...shell }) {
+function DatePickerRangeButton({ value, onValueChange, onChange, placeholder = "Pick a date range", numberOfMonths, defaultMonth, calendarProps, minDate, maxDate, ...shell }) {
     const [open, setOpen] = React.useState(false);
+    const emit = onValueChange ?? onChange;
     const mdUp = useMediaQuery(MD_MEDIA_QUERY);
     const months = numberOfMonths ?? (mdUp ? 2 : 1);
     const from = toDate(value?.from);
     const to = toDate(value?.to);
     const selected = from || to ? { from, to } : undefined;
-    // Opening on a complete range means the next click starts a new one.
-    // Without this, Day Picker extends the old range and the popover closes
-    // on that first click, so a fresh range needs Clear first.
-    const restartRef = React.useRef(false);
-    const onOpenChange = (next) => {
-        if (next)
-            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, { ...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);
-                    // First click is a same-day range; keep the popover open so the
-                    // user can set `to`. Close once the ends differ.
+    return (_jsxs(PickerShell, { ...shell, empty: !from, label: formatRangeTriggerLabel(from, to, placeholder), dialogLabel: "Choose dates", open: open, onOpenChange: setOpen, children: [_jsx(LazyCalendar, { ...limitCalendarProps(calendarProps, minDate, maxDate), mode: "range", 
+                // A click on a complete range (or on none) starts a new one, so a
+                // fresh range never needs Clear first. The start emits `to: undefined`.
+                resetOnSelect: true, autoFocus: true, selected: selected, defaultMonth: defaultMonth ?? from ?? to, numberOfMonths: months, onSelect: (range) => {
+                    emit?.(range);
+                    // Close once the ends differ; a start or a one-day range stays open.
                     if (range?.from && range.to && !isSameDay(range.from, range.to)) {
                         setOpen(false);
                     }
                 } }), _jsx(PickerClearFooter, { disabled: !from && !to, onClear: () => {
-                    onChange(undefined);
+                    emit?.(undefined);
                     setOpen(false);
                 } })] }));
 }

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

@@ -5,7 +5,10 @@ export declare const DEFAULT_TIME_STEP = 15;
 export type DateTimePickerButtonProps = PickerTriggerProps & {
     /** Controlled instant. `null` or omitted is empty. */
     value?: Date | null;
-    onChange: (date: Date | null) => void;
+    /** Called with the picked instant, or `null` on Clear. */
+    onValueChange?: (date: Date | null) => void;
+    /** @deprecated Use `onValueChange`; `onChange` keeps working until 2.0. */
+    onChange?: (date: Date | null) => void;
     /**
      * Minute increment for the time selects (1, 5, 15, 30, or 60).
      * Values that do not divide 60 fall back to 15 so the list stays even.
@@ -25,4 +28,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, minDate, maxDate, ...shell }: DateTimePickerButtonProps): React.JSX.Element;
+export declare function DateTimePickerButton({ value, onValueChange, onChange, timeStep, placeholder, defaultMonth, calendarProps, minDate, maxDate, ...shell }: DateTimePickerButtonProps): React.JSX.Element;

package/dist/date-time-picker.js

@@ -68,8 +68,9 @@ 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, minDate, maxDate, ...shell }) {
+export function DateTimePickerButton({ value, onValueChange, onChange, timeStep, placeholder = "Pick a date and time", defaultMonth, calendarProps, minDate, maxDate, ...shell }) {
     const [open, setOpen] = React.useState(false);
+    const emit = onValueChange ?? onChange;
     const date = value ?? null;
     const step = resolveTimeStep(timeStep);
     const empty = date == null;
@@ -80,20 +81,20 @@ export function DateTimePickerButton({ value, onChange, timeStep, placeholder =
                     // so a time already set is not dropped by an accidental second tap.
                     if (!next)
                         return;
-                    onChange(combineDateAndTime(next, date?.getHours() ?? 0, date?.getMinutes() ?? 0));
+                    emit?.(combineDateAndTime(next, date?.getHours() ?? 0, date?.getMinutes() ?? 0));
                 } }), _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) => {
                                     if (!date)
                                         return;
-                                    onChange(combineDateAndTime(date, Number(nextHour), date.getMinutes()));
+                                    emit?.(combineDateAndTime(date, Number(nextHour), date.getMinutes()));
                                 }, disabled: empty, children: [_jsx(SelectTrigger, { id: hourId, "aria-label": "Hour", className: "min-w-0 flex-1", children: _jsx(SelectValue, { placeholder: "\u2013\u2013" }) }), _jsx(SelectContent, { children: HOUR_OPTIONS.map((hour) => (_jsx(SelectItem, { value: hour, children: hour }, hour))) })] }), _jsx("span", { className: "text-muted-foreground", "aria-hidden": "true", children: ":" }), _jsxs(Select, { value: date ? padTimePart(date.getMinutes()) : undefined, onValueChange: (nextMinute) => {
                                     if (!date)
                                         return;
-                                    onChange(combineDateAndTime(date, date.getHours(), Number(nextMinute)));
+                                    emit?.(combineDateAndTime(date, date.getHours(), Number(nextMinute)));
                                 }, disabled: empty, children: [_jsx(SelectTrigger, { id: minuteId, "aria-label": "Minute", className: "min-w-0 flex-1", children: _jsx(SelectValue, { placeholder: "\u2013\u2013" }) }), _jsx(SelectContent, { children: minuteOptions(step, date?.getMinutes()).map((minute) => {
                                             const value = padTimePart(minute);
                                             return (_jsx(SelectItem, { value: value, children: value }, value));
                                         }) })] })] })] }), _jsx(PickerClearFooter, { disabled: empty, onClear: () => {
-                    onChange(null);
+                    emit?.(null);
                     setOpen(false);
                 } })] }));
 }

package/dist/dialog.d.ts

@@ -6,6 +6,7 @@ declare function DialogPortal({ ...props }: React.ComponentProps<typeof DialogPr
 declare function DialogClose({ ...props }: React.ComponentProps<typeof DialogPrimitive.Close>): React.JSX.Element;
 declare function DialogOverlay({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Overlay>): React.JSX.Element;
 declare function DialogContent({ className, children, showCloseButton, overlayClassName, closeButtonClassName, ...props }: React.ComponentProps<typeof DialogPrimitive.Content> & {
+    /** Show the X close button in the top-right corner. Default `true`. */
     showCloseButton?: boolean;
     /** Classes for the backdrop, e.g. a darker scrim. */
     overlayClassName?: string;

package/dist/dialog.js

@@ -22,7 +22,9 @@ function DialogOverlay({ className, ...props }) {
     return (_jsx(DialogPrimitive.Overlay, { "data-slot": "dialog-overlay", className: cn(overlayFade, "fixed inset-0 isolate z-50 bg-black/20 supports-backdrop-filter:backdrop-blur-sm", className), ...props }));
 }
 function DialogContent({ className, children, showCloseButton = true, overlayClassName, closeButtonClassName, ...props }) {
-    return (_jsxs(DialogPortal, { children: [_jsx(DialogOverlay, { className: overlayClassName }), _jsxs(DialogPrimitive.Content, { "data-slot": "dialog-content", className: cn(overlaySurface, overlayFadeZoom, "fixed top-1/2 left-1/2 z-50 grid max-h-[90dvh] w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-6 overflow-y-auto p-6 text-sm outline-none", className), ...props, children: [children, showCloseButton && (_jsx(DialogPrimitive.Close, { "data-slot": "dialog-close-button", asChild: true, children: _jsxs(Button, { variant: "ghost", size: "icon-sm", className: cn("absolute top-4 right-4 text-muted-foreground hover:text-foreground", closeButtonClassName), children: [_jsx(XIcon, {}), _jsx("span", { className: "sr-only", children: "Close" })] }) }))] })] }));
+    return (_jsxs(DialogPortal, { children: [_jsx(DialogOverlay, { className: overlayClassName }), _jsxs(DialogPrimitive.Content, { "data-slot": "dialog-content", className: cn(overlaySurface, overlayFadeZoom, "fixed top-1/2 left-1/2 z-50 grid max-h-[90dvh] w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-6 overflow-y-auto p-6 text-sm outline-none", showCloseButton
+                    ? "[--dialog-close-gutter:--spacing(10)]"
+                    : "[--dialog-close-gutter:0px]", className), ...props, children: [children, showCloseButton && (_jsx(DialogPrimitive.Close, { "data-slot": "dialog-close-button", asChild: true, children: _jsxs(Button, { variant: "ghost", size: "icon-sm", className: cn("absolute top-4 right-4 text-muted-foreground hover:text-foreground", closeButtonClassName), children: [_jsx(XIcon, {}), _jsx("span", { className: "sr-only", children: "Close" })] }) }))] })] }));
 }
 function DialogHeader({ className, ...props }) {
     return (_jsx("div", { "data-slot": "dialog-header", className: cn("flex flex-col gap-2", className), ...props }));
@@ -31,7 +33,7 @@ function DialogFooter({ className, children, ...props }) {
     return (_jsx("div", { "data-slot": "dialog-footer", className: cn("flex flex-col-reverse gap-2 sm:flex-row sm:justify-end", className), ...props, children: children }));
 }
 function DialogTitle({ className, ...props }) {
-    return (_jsx(DialogPrimitive.Title, { "data-slot": "dialog-title", className: cn("font-heading text-lg leading-none font-semibold tracking-wider uppercase", 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 }));

package/dist/dropdown-menu.d.ts

@@ -1,26 +1,27 @@
 import * as React from "react";
 import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui";
+/** Props for menu rows that can line up with checkbox and radio items. */
+type MenuInsetProps = {
+    /** Indent the row to line up with checkbox and radio item text. */
+    inset?: boolean;
+};
 /** Action menu for commands (row actions, overflow menus). Use `Select` to pick a value. */
 declare function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Root>): React.JSX.Element;
 declare function DropdownMenuPortal({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>): React.JSX.Element;
 declare function DropdownMenuTrigger({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>): React.JSX.Element;
 declare function DropdownMenuContent({ className, align, sideOffset, collisionPadding, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Content>): React.JSX.Element;
 declare function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Group>): React.JSX.Element;
-declare function DropdownMenuItem({ className, inset, variant, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
-    inset?: boolean;
+declare function DropdownMenuItem({ className, inset, variant, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & MenuInsetProps & {
+    /** `destructive` colors the row for a dangerous action. Default `default`. */
     variant?: "default" | "destructive";
 }): React.JSX.Element;
 declare function DropdownMenuCheckboxItem({ className, children, checked, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>): React.JSX.Element;
 declare function DropdownMenuRadioGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>): React.JSX.Element;
 declare function DropdownMenuRadioItem({ className, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>): React.JSX.Element;
-declare function DropdownMenuLabel({ className, inset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
-    inset?: boolean;
-}): React.JSX.Element;
+declare function DropdownMenuLabel({ className, inset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & MenuInsetProps): React.JSX.Element;
 declare function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>): React.JSX.Element;
 declare function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<"span">): React.JSX.Element;
 declare function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>): React.JSX.Element;
-declare function DropdownMenuSubTrigger({ className, inset, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
-    inset?: boolean;
-}): React.JSX.Element;
+declare function DropdownMenuSubTrigger({ className, inset, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & MenuInsetProps): React.JSX.Element;
 declare function DropdownMenuSubContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>): React.JSX.Element;
 export { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, };

package/dist/empty-panel.d.ts

@@ -1,9 +1,15 @@
 import type * as React from "react";
 type Props = React.ComponentProps<"div"> & {
     children: React.ReactNode;
-    /** Tighter padding for compact widgets; default is standard form empty states. */
-    size?: "sm" | "md" | "lg";
+    /**
+     * `sm` is tighter padding for compact widgets; `default` is standard form
+     * empty states; `lg` is roomier, for page-level states. `md` is a
+     * deprecated alias of `default`, kept until 2.0. Default `default`.
+     */
+    size?: "sm" | "default" | "lg" | "md";
+    /** Tinted muted background. Default `true`. */
     muted?: boolean;
+    /** Classes for the root `div`. */
     className?: string;
 };
 /** Dashed empty-state panel for lists, widgets, and form sections. Other props go to the root `div`. */

package/dist/empty-panel.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "./utils.js";
 /** Dashed empty-state panel for lists, widgets, and form sections. Other props go to the root `div`. */
-export function EmptyPanel({ children, size = "md", muted = true, className, ...props }) {
-    return (_jsx("div", { "data-slot": "empty-panel", ...props, className: cn("rounded-none border border-dashed text-center text-sm text-muted-foreground", muted && "bg-muted/30", size === "sm" && "px-3 py-4", size === "md" && "px-4 py-6", size === "lg" && "px-4 py-8", className), children: children }));
+export function EmptyPanel({ children, size = "default", muted = true, className, ...props }) {
+    return (_jsx("div", { "data-slot": "empty-panel", ...props, className: cn("rounded-none border border-dashed text-center text-sm text-muted-foreground", muted && "bg-muted/30", size === "sm" && "px-3 py-4", (size === "default" || size === "md") && "px-4 py-6", size === "lg" && "px-4 py-8", className), children: children }));
 }

package/dist/error-boundary.d.ts

@@ -1,9 +1,12 @@
 import { Component, type ErrorInfo, type ReactNode } from "react";
 type ErrorFallbackProps = {
-    /** User-facing recovery copy. */
+    /** User-facing recovery copy. Default "Something went wrong.". */
     message?: string;
+    /** Shows a "Try again" button that calls this. Hidden when omitted. */
     onRetry?: () => void;
+    /** Shows a "Reload" button that calls this. Hidden when omitted. */
     onReload?: () => void;
+    /** Classes for the panel. */
     className?: string;
 };
 /**
@@ -13,9 +16,11 @@ type ErrorFallbackProps = {
  */
 export declare function ErrorFallback({ message, onRetry, onReload, className, }: ErrorFallbackProps): import("react").JSX.Element;
 type ErrorBoundaryProps = {
+    /** Content to render until it throws. */
     children: ReactNode;
     /** Overrides the default recovery message. */
     message?: string;
+    /** Called with the caught error and its component stack, e.g. to log it. */
     onError?: (error: Error, info: ErrorInfo) => void;
 };
 type ErrorBoundaryState = {
@@ -31,6 +36,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

@@ -2,6 +2,7 @@ import { type VariantProps } from "class-variance-authority";
 import { Label } from "./label.js";
 declare function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">): import("react").JSX.Element;
 declare function FieldLegend({ className, variant, ...props }: React.ComponentProps<"legend"> & {
+    /** `label` styles the legend like a field label. Default `legend`. */
     variant?: "legend" | "label";
 }): import("react").JSX.Element;
 /**
@@ -19,7 +20,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;
@@ -27,9 +28,11 @@ declare function FieldLabel({ className, ...props }: React.ComponentProps<typeof
 declare function FieldTitle({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
 declare function FieldDescription({ className, ...props }: React.ComponentProps<"p">): import("react").JSX.Element;
 declare function FieldSeparator({ children, className, ...props }: React.ComponentProps<"div"> & {
+    /** Optional text shown in a gap in the middle of the line, e.g. "Or". */
     children?: React.ReactNode;
 }): import("react").JSX.Element;
 declare function FieldError({ className, children, errors, ...props }: React.ComponentProps<"div"> & {
+    /** Errors to list, deduplicated by message; `children` replaces them. */
     errors?: Array<{
         message?: string;
     } | undefined>;

package/dist/field.js

@@ -71,7 +71,7 @@ function FieldError({ className, children, errors, ...props }) {
         if (uniqueErrors?.length == 1) {
             return uniqueErrors[0]?.message;
         }
-        return (_jsx("ul", { className: "ml-4 flex list-disc flex-col gap-1", children: uniqueErrors.map((error, index) => error?.message && _jsx("li", { children: error.message }, index)) }));
+        return (_jsx("ul", { className: "ml-4 flex list-disc flex-col gap-1", children: uniqueErrors.map((error) => error?.message && _jsx("li", { children: error.message }, error.message)) }));
     }, [children, errors]);
     if (!content) {
         return null;

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

@@ -0,0 +1,45 @@
+import { type FormFieldBaseProps, type FormFieldDescriptionProps, type FormFieldMetaProps } from "./field-error.js";
+type CheckboxFieldProps = FormFieldBaseProps & FormFieldMetaProps & FormFieldDescriptionProps & {
+    /** Whether the box is checked. */
+    checked: boolean;
+    /** Called with the new checked state when the person toggles the box. */
+    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. */
+    disabled?: boolean;
+    /** Checkbox before the label (default) or after the label and hint. */
+    controlPosition?: "start" | "end";
+    /** Forwarded to the checkbox. */
+    className?: string;
+};
+/**
+ * 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 type CheckboxGroupOption<T extends string | number> = {
+    /** Value added to the group's `value` while this box is checked. */
+    value: T;
+    /** Text shown next to the box. */
+    label: string;
+};
+type CheckboxGroupFieldProps<T extends string | number> = FormFieldBaseProps & FormFieldMetaProps & FormFieldDescriptionProps & {
+    /** The boxes to show, in order. */
+    options: CheckboxGroupOption<T>[];
+    /** The checked values. */
+    value: T[];
+    /** Called with the checked values, in `options` order. */
+    onValueChange: (value: T[]) => void;
+    /** Disables every checkbox in the group. */
+    disabled?: boolean;
+    /** Layout of the options, e.g. a grid. Defaults to a wrapping row. */
+    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 {};

package/dist/form/checkbox-field.js

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

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

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

package/dist/form/combobox-field.js

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

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

@@ -0,0 +1,30 @@
+import { type ComponentProps, type 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. */
+    id: string;
+    /** `true` while the field shows error text. */
+    "aria-invalid": true | undefined;
+    /** Ids of the hint and the error text, when shown. */
+    "aria-describedby": string | undefined;
+    /** `true` when the field is `required`. */
+    "aria-required": true | undefined;
+};
+type Props = 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. */
+    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,27 +1,13 @@
-import { type DateLike, type DatePickerCalendarProps } from "../date-picker.js";
-import type { FieldMetaState } from "./field-error.js";
-type Props = {
+import { type DateLike } from "../date-picker.js";
+import { type PickerFieldBaseProps } from "./field-shell.js";
+type Props = PickerFieldBaseProps & {
+    /** The picked day, as a `Date` or `yyyy-MM-dd`; empty when unset. */
     value: DateLike;
+    /** Called with the picked day, or `undefined` when cleared. */
     onValueChange: (date: Date | undefined) => void;
-    label: string;
-    meta?: FieldMetaState;
+    /** Trigger text while no day is picked. Default "Pick a date". */
     placeholder?: string;
-    disabled?: boolean;
-    /** Marks the label and adds "Required" to the trigger's description. */
-    required?: boolean;
-    /** Earliest day that can be picked; earlier days are disabled. */
-    minDate?: DateLike;
-    /** Latest day that can be picked; later days are disabled. */
-    maxDate?: DateLike;
-    /** Forwarded to the date picker trigger. */
-    className?: string;
-    /** Classes for the field wrapper (label, trigger, and error). */
-    fieldClassName?: string;
-    /** Forwarded to the date picker popover. */
-    contentClassName?: string;
-    /** Day Picker options forwarded to the calendar (disabled days, etc.). */
-    calendarProps?: DatePickerCalendarProps;
 };
 /** Date picker with built-in field error text and invalid styling. */
-export declare function FormDatePickerField({ onValueChange, label, meta, required, 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

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