atlas-react-kit 0.9.3 → 0.9.4

package/COMPONENTS.md

@@ -8,6 +8,12 @@ no root component barrel.
 For installation, see [README.md](./README.md); for styling and accessibility,
 see [DESIGN_RULES.md](./DESIGN_RULES.md).
 
+For LLM-assisted implementation of patterns this kit does not export, use
+[COSS UI](https://coss.com/ui) as a reference before building a component from
+scratch. Its Base UI catalog includes input groups, number fields, OTP fields,
+drawers, and segmented controls. COSS is a separate library; its components
+are not Atlas exports.
+
 ## Optional peer dependencies
 
 Core entries need only the kit. These feature entries need an extra install

package/README.md

@@ -8,7 +8,7 @@ React 19, Tailwind 4, and Node >=20.19 are required. Next 16 is needed only
 when using `next/tabs-nav-link`.
 
 ```sh
-npm install --save-exact atlas-react-kit@0.9.3
+npm install --save-exact atlas-react-kit@0.9.4
 ```
 
 Import components by subpath:
@@ -128,7 +128,7 @@ artifact with the package owner's npm login:
 ```sh
 mkdir -p release-artifacts
 npm pack --pack-destination release-artifacts
-npm publish ./release-artifacts/atlas-react-kit-0.9.3.tgz --access public
+npm publish ./release-artifacts/atlas-react-kit-0.9.4.tgz --access public
 ```
 
 Pin an exact package version in consuming applications. Roll back an upgrade by

package/dist/combobox.js

@@ -5,9 +5,9 @@ import { CheckIcon, ChevronDownIcon } from "lucide-react";
 import { Button } from "./button.js";
 import { Input } from "./input.js";
 import { formControlTriggerClassName } from "./internal/form-control.js";
-import { moveListboxHighlight } from "./internal/listbox-navigation.js";
+import { listboxOptionId, moveListboxHighlight, scrollOptionIntoView, } from "./internal/listbox-navigation.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
-import { optionState } from "./internal/styles.js";
+import { listboxEmpty, optionState } from "./internal/styles.js";
 import { cn, onInputChange } from "./utils.js";
 const CREATE_OPTION_KEY = "__atlas-combobox-create";
 /**
@@ -96,12 +96,6 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
         const frame = window.requestAnimationFrame(() => inputRef.current?.focus());
         return () => window.cancelAnimationFrame(frame);
     }, [open]);
-    // Callback ref (not an effect) so scroll runs when Radix mounts the list
-    // and when the highlight moves. A layout effect on `open` is too early:
-    // the option node does not exist until the popover content is in the DOM.
-    const scrollHighlightedOption = React.useCallback((node) => {
-        node?.scrollIntoView({ block: "nearest" });
-    }, []);
     const onQueryChange = onInputChange((next) => {
         setQuery(next);
         setHighlight(0);
@@ -114,9 +108,6 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
         setOpen(false);
         setQuery("");
     };
-    // Index-based ids: option values may contain spaces, which are not valid
-    // in an id or an aria-activedescendant reference.
-    const optionId = (index) => `${listId}-option-${index}`;
     const activeOption = list[highlight];
     const onSearchKeyDown = (event) => {
         const nextHighlight = moveListboxHighlight(event.key, highlight, list.length);
@@ -132,10 +123,10 @@ export function Combobox({ options, value, onValueChange, placeholder = "Select"
                 selectValue(option.value);
         }
     };
-    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", role: "combobox", "aria-expanded": open, "aria-controls": listId, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, 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: "w-[var(--radix-popover-trigger-width)] gap-0 rounded-none p-0", children: [_jsx("div", { className: "border-b p-2", children: _jsx(Input, { ref: inputRef, value: query, onChange: onQueryChange, onKeyDown: onSearchKeyDown, placeholder: searchPlaceholder, "aria-autocomplete": "list", "aria-controls": listId, "aria-activedescendant": activeOption ? optionId(highlight) : undefined }) }), _jsx("ul", { id: listId, role: "listbox", className: "max-h-60 overflow-y-auto p-1", children: list.length === 0 ? (_jsx("li", { className: "px-3 py-4 text-center text-sm text-muted-foreground", children: emptyText })) : (list.map((option, index) => {
+    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", role: "combobox", "aria-expanded": open, "aria-controls": listId, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, 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: "w-[var(--radix-popover-trigger-width)] gap-0 rounded-none p-0", children: [_jsx("div", { className: "border-b p-2", children: _jsx(Input, { ref: inputRef, value: query, onChange: onQueryChange, onKeyDown: onSearchKeyDown, placeholder: searchPlaceholder, "aria-autocomplete": "list", "aria-controls": listId, "aria-activedescendant": activeOption ? listboxOptionId(listId, highlight) : undefined }) }), _jsx("ul", { id: listId, role: "listbox", className: "max-h-60 overflow-y-auto p-1", children: list.length === 0 ? (_jsx("li", { className: listboxEmpty, children: emptyText })) : (list.map((option, index) => {
                             const isCreate = createOption != null && option === createOption;
                             const isSelected = option.value === value && !isCreate;
                             const isActive = index === highlight;
-                            return (_jsx("li", { role: "none", children: _jsxs("button", { ref: isActive ? scrollHighlightedOption : undefined, id: optionId(index), type: "button", role: "option", "aria-selected": isSelected, className: cn("relative flex w-full cursor-default items-center gap-2 rounded-none py-2 pr-8 pl-3 text-left text-sm outline-hidden select-none", isSelected && optionState.selected, isActive && optionState.active), onMouseEnter: () => setHighlight(index), onClick: () => selectValue(option.value), children: [_jsx("span", { className: "truncate", children: option.label }), isSelected ? (_jsx(CheckIcon, { className: "pointer-events-none absolute right-2 size-3.5" })) : null] }) }, isCreate ? CREATE_OPTION_KEY : option.value));
+                            return (_jsx("li", { role: "none", children: _jsxs("button", { ref: isActive ? scrollOptionIntoView : undefined, id: listboxOptionId(listId, index), type: "button", role: "option", "aria-selected": isSelected, className: cn("relative flex w-full cursor-default items-center gap-2 rounded-none py-2 pr-8 pl-3 text-left text-sm outline-hidden select-none", isSelected && optionState.selected, isActive && optionState.active), onMouseEnter: () => setHighlight(index), onClick: () => selectValue(option.value), children: [_jsx("span", { className: "truncate", children: option.label }), isSelected ? (_jsx(CheckIcon, { className: "pointer-events-none absolute right-2 size-3.5" })) : null] }) }, isCreate ? CREATE_OPTION_KEY : option.value));
                         })) })] })] }));
 }

package/dist/date-picker.js

@@ -5,7 +5,7 @@ import { format, isSameDay, parseISO } from "date-fns";
 import { CalendarIcon } from "lucide-react";
 import { Button } from "./button.js";
 import { Calendar } from "./calendar.js";
-import { formControlTriggerClassName } from "./internal/form-control.js";
+import { PICKER_COLLISION_PADDING, pickerContentClassName, pickerTriggerClassName, } from "./internal/form-control.js";
 import { MD_MEDIA_QUERY, useMediaQuery } from "./internal/use-media-query.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
 import { cn } from "./utils.js";
@@ -56,11 +56,9 @@ function formatRangeTriggerLabel(from, to, placeholder) {
         return format(from, "PPP");
     return `${format(from, "PPP")} – ${format(to, "PPP")}`;
 }
-/** Gutter used when the calendar popover collides with the viewport. */
-const DATE_PICKER_COLLISION_PADDING = 16;
 /** Shared trigger + auto-sized popover chrome for single and range modes. */
 function DatePickerShell({ id, disabled, ariaInvalid, className, empty, label, open, onOpenChange, side, children, }) {
-    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "data-empty": empty, className: cn(formControlTriggerClassName, "justify-start data-[empty=true]:text-muted-foreground", className), children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), label] }) }), _jsx(PopoverContent, { align: "start", side: side, collisionPadding: DATE_PICKER_COLLISION_PADDING, className: "w-auto max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0", children: children })] }));
+    return (_jsxs(Popover, { open: open, onOpenChange: onOpenChange, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "data-empty": empty, className: cn(pickerTriggerClassName, className), children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), label] }) }), _jsx(PopoverContent, { align: "start", side: side, collisionPadding: PICKER_COLLISION_PADDING, className: cn("w-auto", pickerContentClassName), children: children })] }));
 }
 function DatePickerSingleButton({ id, value, onChange, placeholder = "Pick a date", disabled, className, "aria-invalid": ariaInvalid, numberOfMonths, side, defaultMonth, }) {
     const [open, setOpen] = React.useState(false);

package/dist/date-time-picker.js

@@ -5,14 +5,12 @@ import { format } from "date-fns";
 import { CalendarIcon } from "lucide-react";
 import { Button } from "./button.js";
 import { Calendar } from "./calendar.js";
-import { formControlTriggerClassName } from "./internal/form-control.js";
+import { PICKER_COLLISION_PADDING, pickerContentClassName, pickerTriggerClassName, } from "./internal/form-control.js";
 import { Popover, PopoverContent, PopoverTrigger } from "./popover.js";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "./select.js";
 import { cn } from "./utils.js";
 /** Default clock increment, in minutes. Must divide 60. */
 export const DEFAULT_TIME_STEP = 15;
-/** Gutter used when the calendar popover collides with the viewport. */
-const DATE_TIME_PICKER_COLLISION_PADDING = 16;
 /**
  * Normalize a minute step so option lists stay even (1, 5, 15, 30, 60).
  * Invalid values fall back to 15 so a bad prop cannot empty the minute list.
@@ -81,7 +79,7 @@ export function DateTimePickerButton({ id, value, onChange, timeStep, placeholde
     const label = date ? format(date, "PPP p") : placeholder;
     const hourId = React.useId();
     const minuteId = React.useId();
-    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "data-empty": empty, className: cn(formControlTriggerClassName, "justify-start data-[empty=true]:text-muted-foreground", className), children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), label] }) }), _jsxs(PopoverContent, { align: "start", side: side, collisionPadding: DATE_TIME_PICKER_COLLISION_PADDING, onInteractOutside: preventDismissForPortaledSelect, className: "w-auto min-w-0 max-w-[min(100vw-2rem,24rem)] max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0", children: [_jsx(Calendar, { mode: "single", selected: date ?? undefined, defaultMonth: defaultMonth ?? date ?? undefined, onSelect: (next) => {
+    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsxs(Button, { id: id, type: "button", variant: "outline", disabled: disabled, "aria-invalid": ariaInvalid, "data-empty": empty, className: cn(pickerTriggerClassName, className), children: [_jsx(CalendarIcon, { "data-icon": "inline-start" }), label] }) }), _jsxs(PopoverContent, { align: "start", side: side, collisionPadding: PICKER_COLLISION_PADDING, onInteractOutside: preventDismissForPortaledSelect, className: cn("w-auto min-w-0 max-w-[min(100vw-2rem,24rem)]", pickerContentClassName), children: [_jsx(Calendar, { mode: "single", 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/field.d.ts

@@ -6,7 +6,7 @@ declare function FieldLegend({ className, variant, ...props }: React.ComponentPr
 }): import("react").JSX.Element;
 declare function FieldGroup({ className, ...props }: React.ComponentProps<"div">): import("react").JSX.Element;
 declare const fieldVariants: (props?: ({
-    orientation?: "horizontal" | "vertical" | "responsive" | null | undefined;
+    orientation?: "vertical" | "horizontal" | "responsive" | 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/date-picker-field.d.ts

@@ -1,5 +1,5 @@
 import { type DateLike } from "../date-picker.js";
-import { type FieldMetaState } from "./field-error.js";
+import type { FieldMetaState } from "./field-error.js";
 type Props = {
     value: DateLike;
     onValueChange: (date: Date | undefined) => void;

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

@@ -1,12 +1,11 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from "react";
 import { DatePickerButton } from "../date-picker.js";
-import { Label } from "../label.js";
-import { FieldError, getFieldErrorMessage, } from "./field-error.js";
+import { FormFieldShell, invalidWhen, metaErrorText } from "./field-shell.js";
 /** Date picker with built-in field error text and invalid styling. */
 export function FormDatePickerField({ value, onValueChange, label, meta, placeholder, disabled, className, }) {
-    const errorText = meta ? getFieldErrorMessage(meta.errors[0]) : undefined;
+    const errorText = metaErrorText(meta);
     const id = useId();
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Label, { htmlFor: id, children: label }), _jsx(DatePickerButton, { id: id, value: value, onChange: onValueChange, placeholder: placeholder, disabled: disabled, className: className, "aria-invalid": errorText ? true : undefined }), _jsx(FieldError, { text: errorText })] }));
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, children: _jsx(DatePickerButton, { id: id, value: value, onChange: onValueChange, placeholder: placeholder, disabled: disabled, className: className, "aria-invalid": invalidWhen(errorText) }) }));
 }

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

@@ -1,4 +1,4 @@
-import { type FieldMetaState } from "./field-error.js";
+import type { FieldMetaState } from "./field-error.js";
 type Props = {
     value: Date | null;
     onValueChange: (date: Date | null) => void;

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

@@ -1,12 +1,11 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
 import { useId } from "react";
 import { DateTimePickerButton } from "../date-time-picker.js";
-import { Label } from "../label.js";
-import { FieldError, getFieldErrorMessage, } from "./field-error.js";
+import { FormFieldShell, invalidWhen, metaErrorText } from "./field-shell.js";
 /** Date-time picker with built-in field error text and invalid styling. */
 export function FormDateTimePickerField({ value, onValueChange, label, meta, placeholder, disabled, timeStep, className, }) {
-    const errorText = meta ? getFieldErrorMessage(meta.errors[0]) : undefined;
+    const errorText = metaErrorText(meta);
     const id = useId();
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Label, { htmlFor: id, children: label }), _jsx(DateTimePickerButton, { id: id, value: value, onChange: onValueChange, placeholder: placeholder, disabled: disabled, timeStep: timeStep, className: className, "aria-invalid": errorText ? true : undefined }), _jsx(FieldError, { text: errorText })] }));
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, children: _jsx(DateTimePickerButton, { id: id, value: value, onChange: onValueChange, placeholder: placeholder, disabled: disabled, timeStep: timeStep, className: className, "aria-invalid": invalidWhen(errorText) }) }));
 }

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

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import { 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.
+ */
+/** First error in `meta`, or `undefined` when there is no meta or no error. */
+export declare function metaErrorText(meta: FieldMetaState | undefined): string | undefined;
+/** `aria-invalid` for the control: `true` while there is error text. */
+export declare function invalidWhen(errorText: string | undefined): true | undefined;
+/**
+ * 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).
+ */
+export declare function FormFieldShell({ id, label, labelAction, errorText, children, }: {
+    id: string;
+    label: string;
+    labelAction?: ReactNode;
+    errorText: string | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/form/field-shell.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Label } from "../label.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.
+ */
+/** 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;
+}
+/** `aria-invalid` for the control: `true` while there is error text. */
+export function invalidWhen(errorText) {
+    return errorText ? true : undefined;
+}
+/**
+ * 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).
+ */
+export function FormFieldShell({ id, label, labelAction, errorText, children, }) {
+    const labelNode = _jsx(Label, { htmlFor: id, children: label });
+    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [labelAction ? (_jsxs("div", { className: "flex items-center justify-between gap-2", children: [labelNode, labelAction] })) : (labelNode), children, _jsx(FieldError, { text: errorText })] }));
+}

package/dist/form/markdown-field.js

@@ -1,13 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
-import { Label } from "../label.js";
 import { Markdown } from "../markdown.js";
 import { Textarea } from "../textarea.js";
 import { ToggleGroup, ToggleGroupItem } from "../toggle-group.js";
 import { fieldSurface } from "../internal/styles.js";
 import { cn, onInputChange } from "../utils.js";
-import { FieldError, getFieldErrorMessage } from "./field-error.js";
+import { FormFieldShell, invalidWhen, metaErrorText } from "./field-shell.js";
 /**
  * GFM body field: Write is a textarea, Preview is the sanitized Markdown
  * renderer. String-in/string-out — not a WYSIWYG document model.
@@ -15,13 +14,11 @@ import { FieldError, getFieldErrorMessage } from "./field-error.js";
 export function FormMarkdownField({ field, id = field.name, label, placeholder = "Markdown supported", rows = 5, showError = true, }) {
     const [mode, setMode] = useState("write");
     const onChange = onInputChange(field.handleChange);
-    const errorText = showError
-        ? getFieldErrorMessage(field.state.meta.errors[0])
-        : undefined;
+    const errorText = showError ? metaErrorText(field.state.meta) : undefined;
     const trimmed = field.state.value.trim();
     function handleModeChange(value) {
         if (value === "write" || value === "preview")
             setMode(value);
     }
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx(Label, { htmlFor: id, children: label }), _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", children: "Preview" })] })] }), mode === "write" ? (_jsx(Textarea, { id: id, value: field.state.value, onChange: onChange, onBlur: field.handleBlur, placeholder: placeholder, rows: rows, "aria-invalid": errorText ? true : undefined })) : (_jsx("div", { className: cn(fieldSurface, "min-h-16"), "aria-live": "polite", children: trimmed ? (_jsx(Markdown, { content: trimmed })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: "Nothing to preview" })) })), showError ? _jsx(FieldError, { text: errorText }) : null] }));
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, 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", children: "Preview" })] }), children: mode === "write" ? (_jsx(Textarea, { id: id, value: field.state.value, onChange: onChange, onBlur: field.handleBlur, placeholder: placeholder, rows: rows, "aria-invalid": invalidWhen(errorText) })) : (_jsx("div", { className: cn(fieldSurface, "min-h-16"), "aria-live": "polite", children: trimmed ? (_jsx(Markdown, { content: trimmed })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: "Nothing to preview" })) })) }));
 }

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

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import { type FieldMetaState } from "./field-error.js";
+import type { FieldMetaState } from "./field-error.js";
 type Props = {
     value: string | undefined;
     meta?: FieldMetaState;

package/dist/form/select-field.js

@@ -1,12 +1,11 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId } from "react";
-import { Label } from "../label.js";
 import { Select, SelectContent, SelectTrigger, SelectValue } from "../select.js";
-import { FieldError, getFieldErrorMessage, } from "./field-error.js";
+import { 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, children, }) {
-    const errorText = meta ? getFieldErrorMessage(meta.errors[0]) : undefined;
+    const errorText = metaErrorText(meta);
     const id = useId();
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Label, { htmlFor: id, children: label }), _jsxs(Select, { value: value, onValueChange: onValueChange, children: [_jsx(SelectTrigger, { id: id, "aria-invalid": errorText ? true : undefined, children: _jsx(SelectValue, { placeholder: placeholder }) }), _jsx(SelectContent, { children: children })] }), _jsx(FieldError, { text: errorText })] }));
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, children: _jsxs(Select, { value: value, onValueChange: onValueChange, children: [_jsx(SelectTrigger, { id: id, "aria-invalid": invalidWhen(errorText), children: _jsx(SelectValue, { placeholder: placeholder }) }), _jsx(SelectContent, { children: children })] }) }));
 }

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

@@ -1,4 +1,4 @@
-import { type FieldMetaState } from "./field-error.js";
+import type { FieldMetaState } from "./field-error.js";
 export type TextFieldApi = {
     name: string;
     state: {

package/dist/form/text-field.js

@@ -1,15 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Input } from "../input.js";
-import { Label } from "../label.js";
 import { Textarea } from "../textarea.js";
 import { onInputChange } from "../utils.js";
-import { FieldError, getFieldErrorMessage, } from "./field-error.js";
+import { 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, }) {
     const onChange = onInputChange(field.handleChange);
-    const errorText = showError
-        ? getFieldErrorMessage(field.state.meta.errors[0])
-        : undefined;
+    const errorText = showError ? metaErrorText(field.state.meta) : undefined;
     const controlProps = {
         id,
         value: field.state.value,
@@ -19,7 +16,7 @@ export function FormTextField({ field, id = field.name, label, placeholder, desc
         autoComplete,
         required,
         minLength,
-        "aria-invalid": errorText ? true : undefined,
+        "aria-invalid": invalidWhen(errorText),
     };
-    return (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Label, { htmlFor: id, children: label }), description ? (_jsx("p", { className: "text-xs text-muted-foreground", children: description })) : null, multiline ? (_jsx(Textarea, { ...controlProps, rows: rows })) : (_jsx(Input, { ...controlProps, type: inputType, autoFocus: autoFocus })), showError ? _jsx(FieldError, { text: errorText }) : null] }));
+    return (_jsxs(FormFieldShell, { id: id, label: label, errorText: errorText, children: [description ? (_jsx("p", { className: "text-xs text-muted-foreground", children: description })) : null, multiline ? (_jsx(Textarea, { ...controlProps, rows: rows })) : (_jsx(Input, { ...controlProps, type: inputType, autoFocus: autoFocus }))] }));
 }

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

@@ -7,3 +7,12 @@
  * outline Button's purple selected wash.
  */
 export declare const formControlTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background";
+/**
+ * Date and date-time picker trigger: the form-control chrome, start-aligned,
+ * with muted text while empty (`data-empty`).
+ */
+export declare const pickerTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background justify-start data-[empty=true]:text-muted-foreground";
+/** Calendar popover body: fits the viewport height and scrolls inside it. */
+export declare const pickerContentClassName = "max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0";
+/** Gutter used when a calendar popover collides with the viewport. */
+export declare const PICKER_COLLISION_PADDING = 16;

package/dist/internal/form-control.js

@@ -7,3 +7,12 @@
  * outline Button's purple selected wash.
  */
 export const formControlTriggerClassName = "h-10 w-full border-input bg-background px-3 font-normal text-base tracking-normal shadow-xs normal-case md:text-sm hover:border-input hover:bg-background hover:text-foreground focus-visible:text-foreground aria-expanded:border-input aria-expanded:bg-background aria-expanded:text-foreground has-data-[icon=inline-start]:pl-3 has-data-[icon=inline-end]:pr-3 dark:hover:bg-background dark:aria-expanded:bg-background";
+/**
+ * Date and date-time picker trigger: the form-control chrome, start-aligned,
+ * with muted text while empty (`data-empty`).
+ */
+export const pickerTriggerClassName = `${formControlTriggerClassName} justify-start data-[empty=true]:text-muted-foreground`;
+/** Calendar popover body: fits the viewport height and scrolls inside it. */
+export const pickerContentClassName = "max-h-(--radix-popover-content-available-height) overflow-y-auto rounded-none p-0";
+/** Gutter used when a calendar popover collides with the viewport. */
+export const PICKER_COLLISION_PADDING = 16;

package/dist/internal/listbox-navigation.d.ts

@@ -1,2 +1,14 @@
 /** Return the next highlighted index for a listbox navigation key. */
 export declare function moveListboxHighlight(key: string, index: number, length: number): number | undefined;
+/**
+ * Option id for `aria-activedescendant`. Index-based because option values
+ * may contain spaces, which are not valid in an id reference.
+ */
+export declare function listboxOptionId(listId: string, index: number): string;
+/**
+ * Callback ref for the highlighted option. It runs when the option mounts
+ * (including when a popover first renders the list) and when the highlight
+ * moves, keeping the option in view inside the overflow list. Module-level,
+ * so the ref is stable without `useCallback`.
+ */
+export declare function scrollOptionIntoView(node: HTMLElement | null): void;

package/dist/internal/listbox-navigation.js

@@ -19,3 +19,19 @@ export function moveListboxHighlight(key, index, length) {
             return undefined;
     }
 }
+/**
+ * Option id for `aria-activedescendant`. Index-based because option values
+ * may contain spaces, which are not valid in an id reference.
+ */
+export function listboxOptionId(listId, index) {
+    return `${listId}-option-${index}`;
+}
+/**
+ * Callback ref for the highlighted option. It runs when the option mounts
+ * (including when a popover first renders the list) and when the highlight
+ * moves, keeping the option in view inside the overflow list. Module-level,
+ * so the ref is stable without `useCallback`.
+ */
+export function scrollOptionIntoView(node) {
+    node?.scrollIntoView({ block: "nearest" });
+}

package/dist/internal/styles.d.ts

@@ -37,6 +37,8 @@ export declare const selectedState: {
     /** Quiet buttons and toggles on hover. */
     hover: string;
 };
+/** The "No results" row of a listbox. */
+export declare const listboxEmpty = "px-3 py-4 text-center text-sm text-muted-foreground";
 /** Options in menus and listboxes. */
 export declare const optionState: {
     /** Highlight as focus moves: grey fill plus a 2px ring bar (the fill alone is 1.1:1). */

package/dist/internal/styles.js

@@ -37,6 +37,8 @@ export const selectedState = {
     /** Quiet buttons and toggles on hover. */
     hover: "hover:border-selected-foreground hover:bg-selected hover:text-selected-foreground",
 };
+/** The "No results" row of a listbox. */
+export const listboxEmpty = "px-3 py-4 text-center text-sm text-muted-foreground";
 /** Options in menus and listboxes. */
 export const optionState = {
     /** Highlight as focus moves: grey fill plus a 2px ring bar (the fill alone is 1.1:1). */

package/dist/search-picker.js

@@ -3,8 +3,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { Input } from "./input.js";
 import { Label } from "./label.js";
-import { moveListboxHighlight } from "./internal/listbox-navigation.js";
-import { optionState } from "./internal/styles.js";
+import { listboxOptionId, moveListboxHighlight, scrollOptionIntoView, } from "./internal/listbox-navigation.js";
+import { listboxEmpty, optionState } from "./internal/styles.js";
 import { cn } from "./utils.js";
 /**
  * Case-fold and strip combining marks so "nino" matches "Niño".
@@ -49,14 +49,19 @@ function SearchPicker({ items, getValue, getLabel, filter = defaultSearchFilter,
         return index >= 0 ? index : 0;
     }, [filtered, getValue, value]);
     const [highlight, setHighlight] = React.useState(selectedIndex);
-    React.useEffect(() => {
+    // Reset the highlight while rendering, not in an effect, when the query or
+    // the selected row changes: an effect commits every keystroke twice, once
+    // with the stale highlight and again with the reset.
+    const [highlightFor, setHighlightFor] = React.useState({
+        query,
+        selectedIndex,
+    });
+    if (highlightFor.query !== query ||
+        highlightFor.selectedIndex !== selectedIndex) {
+        setHighlightFor({ query, selectedIndex });
         setHighlight(query ? 0 : selectedIndex);
-    }, [query, selectedIndex]);
-    const optionId = (index) => `${listId}-option-${index}`;
+    }
     const active = filtered[highlight];
-    const scrollHighlightedOption = React.useCallback((node) => {
-        node?.scrollIntoView({ block: "nearest" });
-    }, []);
     const selectItem = (item) => {
         onSelect(item);
         setQuery("");
@@ -82,11 +87,11 @@ function SearchPicker({ items, getValue, getLabel, filter = defaultSearchFilter,
             event.currentTarget.blur();
         }
     };
-    return (_jsxs("div", { "data-slot": "search-picker", className: cn("flex flex-col gap-1.5", className), children: [_jsx(Label, { htmlFor: inputId, children: label }), _jsx(Input, { id: inputId, role: "combobox", "aria-expanded": true, "aria-controls": listId, "aria-autocomplete": "list", "aria-activedescendant": active ? optionId(highlight) : undefined, value: query, disabled: disabled, placeholder: placeholder, onChange: (event) => setQuery(event.target.value), onKeyDown: onKeyDown }), _jsx("ul", { id: listId, role: "listbox", "aria-label": listLabel ?? label, className: "max-h-60 overflow-y-auto border border-input bg-background", children: filtered.length === 0 ? (_jsx("li", { className: "px-3 py-4 text-center text-sm text-muted-foreground", children: emptyText })) : (filtered.map((item, index) => {
+    return (_jsxs("div", { "data-slot": "search-picker", className: cn("flex flex-col gap-1.5", className), children: [_jsx(Label, { htmlFor: inputId, children: label }), _jsx(Input, { id: inputId, role: "combobox", "aria-expanded": true, "aria-controls": listId, "aria-autocomplete": "list", "aria-activedescendant": active ? listboxOptionId(listId, highlight) : undefined, value: query, disabled: disabled, placeholder: placeholder, onChange: (event) => setQuery(event.target.value), onKeyDown: onKeyDown }), _jsx("ul", { id: listId, role: "listbox", "aria-label": listLabel ?? label, className: "max-h-60 overflow-y-auto border border-input bg-background", children: filtered.length === 0 ? (_jsx("li", { className: listboxEmpty, children: emptyText })) : (filtered.map((item, index) => {
                     const itemValue = getValue(item);
                     const isSelected = itemValue === value;
                     const isActive = index === highlight;
-                    return (_jsx("li", { role: "none", children: _jsx("button", { ref: isActive ? scrollHighlightedOption : undefined, id: optionId(index), type: "button", role: "option", "aria-selected": isSelected, disabled: disabled, className: cn("relative flex w-full cursor-default items-center rounded-none py-2 pr-3 pl-3 text-left text-sm outline-hidden select-none", isSelected && optionState.selected, isActive && optionState.active, isActive &&
+                    return (_jsx("li", { role: "none", children: _jsx("button", { ref: isActive ? scrollOptionIntoView : undefined, id: listboxOptionId(listId, index), type: "button", role: "option", "aria-selected": isSelected, disabled: disabled, className: cn("relative flex w-full cursor-default items-center rounded-none py-2 pr-3 pl-3 text-left text-sm outline-hidden select-none", isSelected && optionState.selected, isActive && optionState.active, isActive &&
                                 !isSelected &&
                                 "bg-accent text-accent-foreground"), onMouseEnter: () => setHighlight(index), onClick: () => selectItem(item), children: _jsx("span", { className: "truncate", children: getLabel(item) }) }) }, itemValue));
                 })) })] }));

package/dist/select.js

@@ -5,6 +5,7 @@ import { Select as SelectPrimitive } from "radix-ui";
 import { dataDisabledState, disabledState, fieldSurface, focusRing, invalidState, optionState, } from "./internal/styles.js";
 import { cn } from "./utils.js";
 import { ChevronDownIcon, CheckIcon, ChevronUpIcon } from "lucide-react";
+const scrollButtonClassName = "z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-3.5";
 function Select({ ...props }) {
     return _jsx(SelectPrimitive.Root, { "data-slot": "select", ...props });
 }
@@ -19,7 +20,7 @@ function SelectTrigger({ className, size = "default", children, ...props }) {
 }
 function SelectContent({ className, children, position = "popper", align = "center", sideOffset = 4, collisionPadding = 8, ...props }) {
     return (_jsx(SelectPrimitive.Portal, { children: _jsxs(SelectPrimitive.Content, { "data-slot": "select-content", "data-align-trigger": position === "item-aligned", className: cn("relative z-50 max-h-(--radix-select-content-available-height) min-w-(--radix-select-trigger-width) origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-none bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", position === "popper" &&
-                "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1", className), position: position, align: align, sideOffset: sideOffset, collisionPadding: collisionPadding, ...props, children: [_jsx(SelectScrollUpButton, {}), _jsx(SelectPrimitive.Viewport, { "data-position": position, className: cn("data-[position=popper]:h-(--radix-select-trigger-height) data-[position=popper]:w-full data-[position=popper]:min-w-(--radix-select-trigger-width)", position === "popper" && ""), children: children }), _jsx(SelectScrollDownButton, {})] }) }));
+                "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1", className), position: position, align: align, sideOffset: sideOffset, collisionPadding: collisionPadding, ...props, children: [_jsx(SelectScrollUpButton, {}), _jsx(SelectPrimitive.Viewport, { "data-position": position, className: "data-[position=popper]:h-(--radix-select-trigger-height) data-[position=popper]:w-full data-[position=popper]:min-w-(--radix-select-trigger-width)", children: children }), _jsx(SelectScrollDownButton, {})] }) }));
 }
 function SelectLabel({ className, ...props }) {
     return (_jsx(SelectPrimitive.Label, { "data-slot": "select-label", className: cn("px-3 py-2 text-xs font-semibold tracking-wider text-muted-foreground uppercase", className), ...props }));
@@ -31,9 +32,9 @@ function SelectSeparator({ className, ...props }) {
     return (_jsx(SelectPrimitive.Separator, { "data-slot": "select-separator", className: cn("pointer-events-none -mx-1.5 my-1.5 h-px bg-border/50", className), ...props }));
 }
 function SelectScrollUpButton({ className, ...props }) {
-    return (_jsx(SelectPrimitive.ScrollUpButton, { "data-slot": "select-scroll-up-button", className: cn("z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-3.5", className), ...props, children: _jsx(ChevronUpIcon, {}) }));
+    return (_jsx(SelectPrimitive.ScrollUpButton, { "data-slot": "select-scroll-up-button", className: cn(scrollButtonClassName, className), ...props, children: _jsx(ChevronUpIcon, {}) }));
 }
 function SelectScrollDownButton({ className, ...props }) {
-    return (_jsx(SelectPrimitive.ScrollDownButton, { "data-slot": "select-scroll-down-button", className: cn("z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-3.5", className), ...props, children: _jsx(ChevronDownIcon, {}) }));
+    return (_jsx(SelectPrimitive.ScrollDownButton, { "data-slot": "select-scroll-down-button", className: cn(scrollButtonClassName, className), ...props, children: _jsx(ChevronDownIcon, {}) }));
 }
 export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas-react-kit",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Shared React components and Tailwind theme for Atlas",
   "type": "module",
   "license": "MIT",