atlas-react-kit 1.2.1 → 1.2.2

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

@@ -1,18 +1,17 @@
-import type { ComponentProps, ReactNode } from "react";
+import { type ComponentProps, type ComponentType, type ReactNode } from "react";
 import type { DateLike, DatePickerCalendarProps } from "../date-picker.js";
 import type { AsChildProps } from "../internal/as-child.js";
 import { type ErrorTimingProps, type FieldMetaState, type FormFieldBaseProps, type FormFieldMetaProps } from "./field-error.js";
 /**
- * Not a public entry. The layout and error wiring every `form/*` field
- * shares, so a field only says which control it renders. Custom controls
- * get the same shell through the public `FormControlField`.
+ * The error text a `form/*` field shows (`metaErrorText`) and its control
+ * id. The id is generated per field, so two forms that share a field name
+ * (login and sign-up `email`) never share an id, and each label, hint, and
+ * error links to its own control.
  */
-/**
- * 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;
+export declare function useFormField(meta: FieldMetaState | undefined, timing: ErrorTimingProps): {
+    id: string;
+    errorText: string | undefined;
+};
 /**
  * ARIA for a field's control, from the ids `FormFieldShell` renders:
  * invalid while there is error text, described by the hint, the hidden
@@ -37,12 +36,6 @@ export declare function fieldAria(id: string, errorText: string | undefined, { d
  * `onValueChange`, and `placeholder`.
  */
 export type PickerFieldBaseProps = FormFieldBaseProps & FormFieldMetaProps & {
-    /**
-     * Id of the trigger the label points at. Defaults to a generated id;
-     * pass the field name (`id={field.name}`) so a submit handler such as
-     * `focusFirstInvalid` can find the control.
-     */
-    id?: string;
     /** Disables the trigger so no date can be picked. */
     disabled?: boolean;
     /** Marks the label and adds "Required" to the trigger's description. */
@@ -58,6 +51,23 @@ export type PickerFieldBaseProps = FormFieldBaseProps & FormFieldMetaProps & {
     /** Day Picker options forwarded to the calendar (disabled days, etc.). */
     calendarProps?: DatePickerCalendarProps;
 };
+/** The props a date or date-time field keeps for its shell, not the picker. */
+type PickerFieldOwnKey = "fieldName" | "label" | "meta" | "submitted" | "showError" | "required" | "fieldClassName";
+/**
+ * The date and date-time fields: `picker` (the trigger) in a
+ * `FormFieldShell`, given every prop of `field` the shell does not take. A
+ * button cannot carry `required`, so the trigger is described by the hidden
+ * "Required" text and reads "label, value".
+ */
+export declare function FormPickerField<P extends PickerFieldBaseProps>({ field, picker: Picker, }: {
+    /** The field's props. */
+    field: P;
+    /** The picker trigger. */
+    picker: ComponentType<Omit<P, PickerFieldOwnKey> & {
+        id: string;
+        "data-field-name"?: string;
+    } & ReturnType<typeof fieldAria>>;
+}): import("react").JSX.Element;
 /**
  * Every `form/*` field's wrapper (`data-slot="form-field"`): children with
  * the field spacing, then the error text. `asChild` makes the one child the
@@ -96,3 +106,4 @@ export declare function FormFieldShell({ id, label, labelAction, description, er
     required?: boolean;
     children: ReactNode;
 }): import("react").JSX.Element;
+export {};

package/dist/form/field-shell.js

@@ -1,6 +1,8 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, } from "react";
 import { Slot } from "radix-ui";
-import { pickerValueId } from "../internal/form-control.js";
+import { fieldNameProps, pickerValueId } from "../internal/form-control.js";
 import { Label } from "../label.js";
 import { cn } from "../utils.js";
 import { FieldError, getFieldErrorMessage, } from "./field-error.js";
@@ -14,13 +16,22 @@ import { FieldError, getFieldErrorMessage, } from "./field-error.js";
  * `showError` is false, or the field is untouched (`isTouched: false`)
  * and the form has not been submitted.
  */
-export function metaErrorText(meta, { submitted, showError = true } = {}) {
+function metaErrorText(meta, { submitted, showError = true } = {}) {
     if (!meta || !showError)
         return undefined;
     if (meta.isTouched === false && !submitted)
         return undefined;
     return getFieldErrorMessage(meta.errors[0]);
 }
+/**
+ * The error text a `form/*` field shows (`metaErrorText`) and its control
+ * id. The id is generated per field, so two forms that share a field name
+ * (login and sign-up `email`) never share an id, and each label, hint, and
+ * error links to its own control.
+ */
+export function useFormField(meta, timing) {
+    return { id: useId(), errorText: metaErrorText(meta, timing) };
+}
 /** Id of the label `FormFieldShell` renders for control `id`. */
 function labelIdFor(id) {
     return `${id}-label`;
@@ -65,6 +76,20 @@ export function fieldAria(id, errorText, { description, required, labelledBy, }
         }),
     };
 }
+/**
+ * The date and date-time fields: `picker` (the trigger) in a
+ * `FormFieldShell`, given every prop of `field` the shell does not take. A
+ * button cannot carry `required`, so the trigger is described by the hidden
+ * "Required" text and reads "label, value".
+ */
+export function FormPickerField({ field, picker: Picker, }) {
+    const { fieldName, label, meta, submitted, showError, required, fieldClassName, ...pickerProps } = field;
+    const { id, errorText } = useFormField(meta, { submitted, showError });
+    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, required: required, className: fieldClassName, children: _jsx(Picker, { ...pickerProps, id: id, ...fieldNameProps(fieldName), ...fieldAria(id, errorText, {
+                required: required && "described",
+                labelledBy: "label-value",
+            }) }) }));
+}
 /**
  * Every `form/*` field's wrapper (`data-slot="form-field"`): children with
  * the field spacing, then the error text. `asChild` makes the one child the

package/dist/form/focus-first-invalid.d.ts

@@ -15,14 +15,17 @@ export type InvalidSubmitEvent = {
 /**
  * Invalid-submit handler that focuses the first field, in page order, whose
  * meta has errors. It reads the form state, not the rendered `aria-invalid`,
- * so it works before React has re-rendered. Fields are matched by control
- * id, so give each `form/*` field `id={field.name}` (`FormTextField`
- * defaults to it). The form library needs no focus API of its own.
+ * so it works before React has re-rendered. Fields are matched by the
+ * `data-field-name` each `form/*` field puts on its control: `FormTextField`
+ * and `FormMarkdownField` read `field.name`; the other fields take
+ * `fieldName={field.name}`. The lookup stays inside the form with id
+ * `formId`, so a second form with the same field names is never touched.
+ * The form library needs no focus API of its own.
  *
  * ```tsx
  * const form = useForm({ onSubmitInvalid: focusFirstInvalid("order-form") })
  * <form id="order-form" onSubmit={...}>
- *   <FormSelectField id={field.name} ... />
+ *   <FormSelectField fieldName={field.name} ... />
  * ```
  */
 export declare function focusFirstInvalid(formId: string): ({ formApi }: InvalidSubmitEvent) => void;

package/dist/form/focus-first-invalid.js

@@ -1,14 +1,18 @@
+import { FIELD_NAME_ATTRIBUTE } from "../internal/form-control.js";
 /**
  * Invalid-submit handler that focuses the first field, in page order, whose
  * meta has errors. It reads the form state, not the rendered `aria-invalid`,
- * so it works before React has re-rendered. Fields are matched by control
- * id, so give each `form/*` field `id={field.name}` (`FormTextField`
- * defaults to it). The form library needs no focus API of its own.
+ * so it works before React has re-rendered. Fields are matched by the
+ * `data-field-name` each `form/*` field puts on its control: `FormTextField`
+ * and `FormMarkdownField` read `field.name`; the other fields take
+ * `fieldName={field.name}`. The lookup stays inside the form with id
+ * `formId`, so a second form with the same field names is never touched.
+ * The form library needs no focus API of its own.
  *
  * ```tsx
  * const form = useForm({ onSubmitInvalid: focusFirstInvalid("order-form") })
  * <form id="order-form" onSubmit={...}>
- *   <FormSelectField id={field.name} ... />
+ *   <FormSelectField fieldName={field.name} ... />
  * ```
  */
 export function focusFirstInvalid(formId) {
@@ -19,8 +23,8 @@ export function focusFirstInvalid(formId) {
         const invalid = new Set(Object.entries(formApi.state.fieldMeta)
             .filter(([, meta]) => meta?.errors.length)
             .map(([name]) => name));
-        for (const element of form.elements) {
-            if (element instanceof HTMLElement && invalid.has(element.id)) {
+        for (const element of form.querySelectorAll(`[${FIELD_NAME_ATTRIBUTE}]`)) {
+            if (invalid.has(element.getAttribute(FIELD_NAME_ATTRIBUTE) ?? "")) {
                 element.focus();
                 return;
             }

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

@@ -3,7 +3,7 @@ import type { TextFieldBaseProps } from "./text-field.js";
  * GFM body field: Write is a textarea, Preview is the sanitized Markdown
  * renderer. String-in/string-out — not a WYSIWYG document model.
  */
-export declare function FormMarkdownField({ field, id, label, placeholder, rows, showError, submitted, required, className, fieldClassName, previewClassName, }: TextFieldBaseProps & {
+export declare function FormMarkdownField({ field, label, placeholder, rows, showError, submitted, required, className, fieldClassName, previewClassName, }: TextFieldBaseProps & {
     /** Write textarea placeholder. Default "Markdown supported". */
     placeholder?: string;
     /** Write textarea rows. Default 5. */

package/dist/form/markdown-field.js

@@ -4,9 +4,10 @@ import { lazy, Suspense, useState } from "react";
 import { Spinner } from "../spinner.js";
 import { Textarea } from "../textarea.js";
 import { ToggleGroup, ToggleGroupItem } from "../toggle-group.js";
+import { fieldNameProps } from "../internal/form-control.js";
 import { fieldSurface } from "../internal/styles.js";
 import { cn, onInputChange } from "../utils.js";
-import { fieldAria, FormFieldShell, metaErrorText } from "./field-shell.js";
+import { fieldAria, FormFieldShell, useFormField } from "./field-shell.js";
 // The renderer (react-markdown + remark-gfm) is fetched the first time
 // Preview is shown or hovered, so a form in Write mode stays light.
 const loadMarkdown = () => import("../markdown.js");
@@ -16,14 +17,17 @@ 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, submitted, required, className, fieldClassName, previewClassName, }) {
+export function FormMarkdownField({ field, label, placeholder = "Markdown supported", rows = 5, showError, submitted, required, className, fieldClassName, previewClassName, }) {
+    const { id, errorText } = useFormField(field.state.meta, {
+        submitted,
+        showError,
+    });
     const [mode, setMode] = useState("write");
     const onChange = onInputChange(field.handleChange);
-    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", 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, ...fieldAria(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, ...fieldNameProps(field.name), value: field.state.value, onChange: onChange, onBlur: field.handleBlur, placeholder: placeholder, rows: rows, required: required, className: className, ...fieldAria(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,4 +1,4 @@
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import type { FormFieldBaseProps, FormFieldMetaProps } from "./field-error.js";
 type Props = FormFieldBaseProps & FormFieldMetaProps & {
     /** The selected item's value, or `undefined` for none. */
@@ -7,12 +7,6 @@ type Props = FormFieldBaseProps & FormFieldMetaProps & {
     onValueChange: (value: string) => void;
     /** Trigger text while no item is selected. */
     placeholder?: string;
-    /**
-     * Id of the trigger the label points at. Defaults to a generated id;
-     * pass the field name (`id={field.name}`) so a submit handler such as
-     * `focusFirstInvalid` can find the control.
-     */
-    id?: string;
     /** Requires a value (native form validation) and marks the label. */
     required?: boolean;
     /** Forwarded to the select trigger. */
@@ -23,5 +17,5 @@ type Props = FormFieldBaseProps & FormFieldMetaProps & {
     children: ReactNode;
 };
 /** Select control with built-in field error text and invalid styling. */
-export declare function FormSelectField({ id: idProp, value, meta, submitted, showError, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }: Props): import("react").JSX.Element;
+export declare function FormSelectField({ fieldName, value, meta, submitted, showError, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }: Props): import("react").JSX.Element;
 export {};

package/dist/form/select-field.js

@@ -1,12 +1,10 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useId } from "react";
+import { fieldNameProps } from "../internal/form-control.js";
 import { Select, SelectContent, SelectTrigger, SelectValue } from "../select.js";
-import { fieldAria, FormFieldShell, metaErrorText } from "./field-shell.js";
+import { fieldAria, FormFieldShell, useFormField } from "./field-shell.js";
 /** Select control with built-in field error text and invalid styling. */
-export function FormSelectField({ id: idProp, value, meta, submitted, showError, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }) {
-    const errorText = metaErrorText(meta, { submitted, showError });
-    const generatedId = useId();
-    const id = idProp ?? generatedId;
-    return (_jsx(FormFieldShell, { id: id, label: label, errorText: errorText, required: required, className: fieldClassName, children: _jsxs(Select, { value: value, onValueChange: onValueChange, required: required, children: [_jsx(SelectTrigger, { id: id, className: className, ...fieldAria(id, errorText, { required }), children: _jsx(SelectValue, { placeholder: placeholder }) }), _jsx(SelectContent, { className: contentClassName, children: children })] }) }));
+export function FormSelectField({ fieldName, value, meta, submitted, showError, label, onValueChange, placeholder, required, className, fieldClassName, contentClassName, children, }) {
+    const { id, errorText } = useFormField(meta, { submitted, showError });
+    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, ...fieldNameProps(fieldName), className: className, ...fieldAria(id, errorText, { required }), children: _jsx(SelectValue, { placeholder: placeholder }) }), _jsx(SelectContent, { className: contentClassName, children: children })] }) }));
 }

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

@@ -1,6 +1,6 @@
 import type { FieldMetaState, FormFieldBaseProps } from "./field-error.js";
 export type TextFieldApi = {
-    /** Field name; the default control id. */
+    /** Field name; put on the control as `data-field-name` for `focusFirstInvalid`. */
     name: string;
     state: {
         /** Current text. */
@@ -20,12 +20,6 @@ export type TextFieldApi = {
 export type TextFieldBaseProps = FormFieldBaseProps & {
     /** The TanStack Form field (or the same shape) the control reads and writes. */
     field: TextFieldApi;
-    /**
-     * Control id the label points at. Defaults to `field.name`; pass a unique
-     * id when two forms on one page share a field name (login and sign-up
-     * `email`), or the second label focuses the first input.
-     */
-    id?: string;
     /** Sets `required` on the text control and marks the label. */
     required?: boolean;
     /** Forwarded to the text control (the input or textarea). */
@@ -35,7 +29,7 @@ export type TextFieldBaseProps = FormFieldBaseProps & {
  * Text input, or a textarea with `multiline`, bound to a TanStack Form
  * `field`, with a label, optional hint, and the `form/*` error text.
  */
-export declare function FormTextField({ field, id, label, placeholder, description, autoFocus, multiline, rows, inputType, showError, submitted, autoComplete, required, minLength, className, fieldClassName, }: TextFieldBaseProps & {
+export declare function FormTextField({ field, label, placeholder, description, autoFocus, multiline, rows, inputType, showError, submitted, autoComplete, required, minLength, className, fieldClassName, }: TextFieldBaseProps & {
     /** Text shown in the empty control. */
     placeholder?: string;
     /** Optional hint under the label (employer vs referrer, etc.). */

package/dist/form/text-field.js

@@ -1,18 +1,23 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Input } from "../input.js";
+import { fieldNameProps } from "../internal/form-control.js";
 import { Textarea } from "../textarea.js";
 import { onInputChange } from "../utils.js";
-import { fieldAria, FormFieldShell, metaErrorText } from "./field-shell.js";
+import { fieldAria, FormFieldShell, useFormField } from "./field-shell.js";
 /**
  * Text input, or a textarea with `multiline`, bound to a TanStack Form
  * `field`, with a label, optional hint, and the `form/*` error text.
  */
-export function FormTextField({ field, id = field.name, label, placeholder, description, autoFocus, multiline, rows = 3, inputType = "text", showError, submitted, autoComplete, required, minLength, className, fieldClassName, }) {
+export function FormTextField({ field, label, placeholder, description, autoFocus, multiline, rows = 3, inputType = "text", showError, submitted, autoComplete, required, minLength, className, fieldClassName, }) {
+    const { id, errorText } = useFormField(field.state.meta, {
+        submitted,
+        showError,
+    });
     const onChange = onInputChange(field.handleChange);
-    const errorText = metaErrorText(field.state.meta, { submitted, showError });
     const controlProps = {
         id,
+        ...fieldNameProps(field.name),
         value: field.state.value,
         onChange,
         onBlur: field.handleBlur,

package/dist/form/toggle-group-field.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import type { FormFieldBaseProps, FormFieldDescriptionProps, FormFieldMetaProps } from "./field-error.js";
 export type ToggleGroupFieldOption<T extends string> = {
     /** Value passed to `onValueChange` when this item is pressed. */
@@ -26,5 +26,5 @@ type Props<T extends string> = FormFieldBaseProps & FormFieldMetaProps & FormFie
  * One choice from a few as a joined outline toggle group (a segmented
  * control), with a visible label and the `form/*` error wiring.
  */
-export declare function FormToggleGroupField<T extends string>({ label, description, value, onValueChange, options, meta, submitted, showError, required, disabled, size, className, fieldClassName, }: Props<T>): import("react").JSX.Element;
+export declare function FormToggleGroupField<T extends string>({ fieldName, label, description, value, onValueChange, options, meta, submitted, showError, required, disabled, size, className, fieldClassName, }: Props<T>): import("react").JSX.Element;
 export {};

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

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

package/dist/info-tip.d.ts

@@ -13,7 +13,9 @@ export type InfoTipProps = {
     /**
      * `inline` sits in a line of text: the glyph is 1em, a quarter em after
      * the word, on the text's cap height, and keeps the line height; the 44px
-     * hit area overflows. Default `box`.
+     * hit area overflows. `box` is a 44px button; after a label (any earlier
+     * sibling) its glyph sits that same quarter em from the text, so leave the
+     * gap off the parent. Default `box`.
      */
     layout?: InfoTipLayout;
     /** Panel side. Default `top`; Radix still flips on collision. */

package/dist/info-tip.js

@@ -54,9 +54,12 @@ function InfoTip({ label, title, description, children, layout = "box", side = "
         }, children: [_jsx(PopoverTrigger, { asChild: true, children: _jsx("button", { ...props, type: "button", "aria-label": label, "data-slot": "info-tip-trigger", "data-layout": layout, className: cn(focusRing, "relative inline-flex shrink-0 items-center justify-center rounded-none text-muted-foreground", quietTextHover, 
                     // Inline: 1em scales with the sentence; -0.125em centres the
                     // glyph on the cap height without growing the line box.
+                    // Box: the 44px target leaves 12px either side of the 20px
+                    // glyph. After a label, pull it back over that padding so the
+                    // glyph sits the same quarter em from the text as it does inline.
                     inline
                         ? cn("ml-[0.25em] size-[1em] align-[-0.125em]", hitArea44)
-                        : "size-11", className), onMouseEnter: openFromHover, onMouseLeave: closeFromHover, onClick: (event) => {
+                        : "size-11 not-first:ml-[calc(0.25em-0.75rem)]", className), onMouseEnter: openFromHover, onMouseLeave: closeFromHover, onClick: (event) => {
                         // Hover already opened the panel; this click pins it instead of
                         // toggling it closed (Playwright and real mice both hover before
                         // they click). Preventing default skips Radix's toggle.

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

@@ -17,6 +17,12 @@ export declare const pickerTriggerClassName = "h-10 w-full border-input bg-backg
 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;
+/** Carries a field's name on its control, for `focusFirstInvalid`. */
+export declare const FIELD_NAME_ATTRIBUTE = "data-field-name";
+/** The props that mark a control with its field's name. */
+export declare function fieldNameProps(name: string | undefined): {
+    "data-field-name": string | undefined;
+};
 /**
  * Id of a picker trigger's value text. A form field lists it after the label
  * id in `aria-labelledby` so the trigger reads "label, value".

package/dist/internal/form-control.js

@@ -18,6 +18,12 @@ export const pickerTriggerClassName = `${formControlTriggerClassName} h-auto jus
 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;
+/** Carries a field's name on its control, for `focusFirstInvalid`. */
+export const FIELD_NAME_ATTRIBUTE = "data-field-name";
+/** The props that mark a control with its field's name. */
+export function fieldNameProps(name) {
+    return { [FIELD_NAME_ATTRIBUTE]: name };
+}
 /**
  * Id of a picker trigger's value text. A form field lists it after the label
  * id in `aria-labelledby` so the trigger reads "label, value".

package/dist/internal/kanban-layout.js

@@ -1,3 +1,4 @@
+import { clamp } from "./math.js";
 /** Drop zone ids for the drag-time action rail. */
 export const KANBAN_COMPLETE_ID = "__kanban_complete__";
 export const KANBAN_DELETE_ID = "__kanban_delete__";
@@ -45,7 +46,7 @@ export function resolveKanbanDrop(input, groups) {
         return null;
     const columnItems = groups[toColumnId] ?? [];
     const remaining = columnItems.filter((id) => id !== itemId);
-    const index = Math.max(0, Math.min(rawIndex ?? remaining.length, remaining.length));
+    const index = clamp(rawIndex ?? remaining.length, 0, remaining.length);
     if (initialGroup === toColumnId && index === columnItems.indexOf(itemId)) {
         return null;
     }

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

@@ -12,19 +12,19 @@ export declare function listboxOptionId(listId: string, index: number): string;
 export declare function scrollOptionIntoView(node: HTMLElement | null): void;
 /**
  * Shared keydown for a search input that drives a listbox: navigation keys
- * move the highlight, Enter picks the highlighted index. Returns `true` when
- * the key is handled (or an IME is composing, when every key belongs to the
- * IME), so the caller can stop; `false` leaves the key to the caller (for
- * example SearchPicker's Escape).
+ * move the highlight over `items`, Enter picks the highlighted item. Returns
+ * `true` when the key is handled (or an IME is composing, when every key
+ * belongs to the IME), so the caller can stop; `false` leaves the key to the
+ * caller (for example SearchPicker's Escape).
  */
-export declare function handleListboxKey(event: {
+export declare function handleListboxKey<T>(event: {
     key: string;
     keyCode: number;
     nativeEvent: KeyboardEvent;
     preventDefault: () => void;
-}, { highlight, length, setHighlight, onEnter, }: {
+}, { items, highlight, setHighlight, onPick, }: {
+    items: readonly T[];
     highlight: number;
-    length: number;
     setHighlight: (index: number) => void;
-    onEnter: (index: number) => void;
+    onPick: (item: T) => void;
 }): boolean;

package/dist/internal/listbox-navigation.js

@@ -1,23 +1,21 @@
+import { clamp } from "./math.js";
 /** Page keys move ten rows, a little more than one max-h-60 list viewport. */
 const PAGE_SIZE = 10;
+/** Rows each key moves the highlight; Home and End jump to the ends. */
+const keySteps = new Map([
+    ["ArrowDown", 1],
+    ["ArrowUp", -1],
+    ["PageDown", PAGE_SIZE],
+    ["PageUp", -PAGE_SIZE],
+    ["Home", -Infinity],
+    ["End", Infinity],
+]);
 /** Return the next highlighted index for a listbox navigation key. */
 function moveListboxHighlight(key, index, length) {
-    switch (key) {
-        case "ArrowDown":
-            return length === 0 ? 0 : Math.min(index + 1, length - 1);
-        case "ArrowUp":
-            return Math.max(index - 1, 0);
-        case "Home":
-            return 0;
-        case "End":
-            return length === 0 ? 0 : length - 1;
-        case "PageDown":
-            return length === 0 ? 0 : Math.min(index + PAGE_SIZE, length - 1);
-        case "PageUp":
-            return Math.max(index - PAGE_SIZE, 0);
-        default:
-            return undefined;
-    }
+    const step = keySteps.get(key);
+    if (step === undefined)
+        return undefined;
+    return clamp(index + step, 0, Math.max(length - 1, 0));
 }
 /**
  * Option id for `aria-activedescendant`. Index-based because option values
@@ -45,15 +43,15 @@ function isComposingKey(event) {
 }
 /**
  * Shared keydown for a search input that drives a listbox: navigation keys
- * move the highlight, Enter picks the highlighted index. Returns `true` when
- * the key is handled (or an IME is composing, when every key belongs to the
- * IME), so the caller can stop; `false` leaves the key to the caller (for
- * example SearchPicker's Escape).
+ * move the highlight over `items`, Enter picks the highlighted item. Returns
+ * `true` when the key is handled (or an IME is composing, when every key
+ * belongs to the IME), so the caller can stop; `false` leaves the key to the
+ * caller (for example SearchPicker's Escape).
  */
-export function handleListboxKey(event, { highlight, length, setHighlight, onEnter, }) {
+export function handleListboxKey(event, { items, highlight, setHighlight, onPick, }) {
     if (isComposingKey(event))
         return true;
-    const next = moveListboxHighlight(event.key, highlight, length);
+    const next = moveListboxHighlight(event.key, highlight, items.length);
     if (next !== undefined) {
         event.preventDefault();
         setHighlight(next);
@@ -61,7 +59,9 @@ export function handleListboxKey(event, { highlight, length, setHighlight, onEnt
     }
     if (event.key === "Enter") {
         event.preventDefault();
-        onEnter(highlight);
+        const item = items[highlight];
+        if (item !== undefined)
+            onPick(item);
         return true;
     }
     return false;

package/dist/internal/overlay-styles.d.ts

@@ -17,6 +17,11 @@ export declare const overlaySideSlide = "data-[side=bottom]:slide-in-from-top-2
 export declare const overlayFade = "duration-100 data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0";
 /** Fade plus a slight zoom, for panels (the backdrop only fades). */
 export declare const overlayFadeZoom = "duration-100 data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0 data-open:zoom-in-95 data-closed:zoom-out-95";
+/**
+ * A panel opened from a trigger (Popover, Select, DropdownMenu): the
+ * surface, sliding in from the trigger's side with a fade and zoom.
+ */
+export declare const anchoredPanel = "rounded-none bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 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 duration-100 data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0 data-open:zoom-in-95 data-closed:zoom-out-95";
 /**
  * Base of a menu or listbox row (SelectItem, DropdownMenuItem, Combobox and
  * SearchPicker options). Each component adds its own right padding and

package/dist/internal/overlay-styles.js

@@ -17,6 +17,11 @@ export const overlaySideSlide = "data-[side=bottom]:slide-in-from-top-2 data-[si
 export const overlayFade = "duration-100 data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0";
 /** Fade plus a slight zoom, for panels (the backdrop only fades). */
 export const overlayFadeZoom = `${overlayFade} data-open:zoom-in-95 data-closed:zoom-out-95`;
+/**
+ * A panel opened from a trigger (Popover, Select, DropdownMenu): the
+ * surface, sliding in from the trigger's side with a fade and zoom.
+ */
+export const anchoredPanel = `${overlaySurface} ${overlaySideSlide} ${overlayFadeZoom}`;
 /**
  * Base of a menu or listbox row (SelectItem, DropdownMenuItem, Combobox and
  * SearchPicker options). Each component adds its own right padding and

package/dist/internal/styles.d.ts

@@ -97,6 +97,11 @@ export declare const controlSize: {
  * tailwind-merge then drops the `text-xs`.
  */
 export declare const controlText = "text-xs font-semibold tracking-widest whitespace-nowrap uppercase";
+/**
+ * Secondary text under a title (CardDescription, PopoverDescription,
+ * DialogDescription, AlertDescription).
+ */
+export declare const descriptionText = "text-sm leading-relaxed text-muted-foreground";
 /** Field-label text (Label, FieldLegend, FieldTitle, PopoverTitle). */
 export declare const labelText = "text-xs font-semibold tracking-wide uppercase";
 /**

package/dist/internal/styles.js

@@ -97,6 +97,11 @@ export const controlSize = {
  * tailwind-merge then drops the `text-xs`.
  */
 export const controlText = "text-xs font-semibold tracking-widest whitespace-nowrap uppercase";
+/**
+ * Secondary text under a title (CardDescription, PopoverDescription,
+ * DialogDescription, AlertDescription).
+ */
+export const descriptionText = "text-sm leading-relaxed text-muted-foreground";
 /** Field-label text (Label, FieldLegend, FieldTitle, PopoverTitle). */
 export const labelText = "text-xs font-semibold tracking-wide uppercase";
 /**

package/dist/kanban.js

@@ -125,7 +125,7 @@ function KanbanColumnView({ column, count, emptyLabel, loading, className, child
         collisionPriority: COLUMN_DROP_PRIORITY,
     });
     const empty = count === 0;
-    return (_jsxs("div", { ref: ref, "data-slot": "kanban-column", "data-drop-target": isDropTarget || undefined, className: cn("flex snap-start flex-col gap-3 p-3", "bg-muted/40 ring-1 ring-foreground/5", "data-drop-target:bg-muted/60 data-drop-target:ring-2 data-drop-target:ring-ring/60", columnSize, className), children: [_jsxs("header", { "data-slot": "kanban-column-header", className: "flex items-start justify-between gap-2", children: [_jsxs("span", { className: "flex items-center gap-2 text-xs font-semibold tracking-widest uppercase", children: [column.color ? (_jsx("span", { "aria-hidden": true, className: "size-2 shrink-0 rounded-full", style: { backgroundColor: column.color } })) : null, _jsx("span", { className: "leading-tight", children: column.label })] }), _jsxs("span", { className: "flex shrink-0 flex-col items-end gap-0.5 text-muted-foreground tabular-nums", children: [_jsx("span", { className: "text-xs", children: count }), column.badge ? (_jsx("span", { className: "text-[10px] font-medium", children: column.badge })) : null] })] }), _jsx("div", { className: "flex min-h-32 flex-1 flex-col gap-2 overflow-y-auto pr-1", children: loading ? (_jsxs(_Fragment, { children: [_jsx(Skeleton, { className: "h-20" }), _jsx(Skeleton, { className: "h-16" })] })) : (_jsxs(_Fragment, { children: [children, _jsx("p", { "data-slot": "kanban-column-empty", "aria-hidden": !empty, className: cn("border border-dashed px-3 py-6 text-center text-xs text-muted-foreground", !empty && "hidden"), children: emptyLabel })] })) })] }));
+    return (_jsxs("div", { ref: ref, "data-slot": "kanban-column", "data-drop-target": isDropTarget || undefined, className: cn("flex snap-start flex-col gap-3 p-3", "bg-muted/40 ring-1 ring-foreground/5", "data-drop-target:bg-muted/60 data-drop-target:ring-2 data-drop-target:ring-ring/60", columnSize, className), children: [_jsxs("header", { "data-slot": "kanban-column-header", className: "flex flex-wrap items-start justify-between gap-x-2 gap-y-0.5", children: [_jsxs("span", { className: "flex max-w-full min-w-0 items-center gap-2 text-xs font-semibold tracking-widest uppercase", children: [column.color ? (_jsx("span", { "aria-hidden": true, className: "size-2 shrink-0 rounded-full", style: { backgroundColor: column.color } })) : null, _jsx("span", { className: "truncate leading-tight", title: column.label, children: column.label })] }), _jsxs("span", { className: "ml-auto flex max-w-full min-w-0 flex-col items-end gap-0.5 text-muted-foreground tabular-nums", children: [_jsx("span", { className: "text-xs", children: count }), column.badge ? (_jsx("span", { className: "max-w-full truncate text-[10px] font-medium", children: column.badge })) : null] })] }), _jsx("div", { className: "-m-1 mr-0 flex min-h-32 flex-1 flex-col gap-2 overflow-y-auto p-1", children: loading ? (_jsxs(_Fragment, { children: [_jsx(Skeleton, { className: "h-20" }), _jsx(Skeleton, { className: "h-16" })] })) : (_jsxs(_Fragment, { children: [children, _jsx("p", { "data-slot": "kanban-column-empty", "aria-hidden": !empty, className: cn("border border-dashed px-3 py-6 text-center text-xs text-muted-foreground", !empty && "hidden"), children: emptyLabel })] })) })] }));
 }
 const cardChrome = cn("flex border border-border bg-card text-card-foreground");
 const handleChrome = cn("flex shrink-0 items-center self-stretch border-r border-border", "bg-muted/30 px-1.5 text-muted-foreground");