@dashforge/tw 1.5.1 → 1.6.0

package/dist/index.esm.js

@@ -1,7 +1,7 @@
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import { useMemo, forwardRef, useContext, useState, useEffect, useRef, useId, useCallback, Fragment as Fragment$1, createContext, Children, isValidElement, memo, cloneElement, useLayoutEffect } from 'react';
 import { Slot } from '@radix-ui/react-slot';
-import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
+import { DashFormContext, useEngineVisibility, useWarnIfControlledInFormMode } from '@dashforge/ui-core';
 import { useComponentDefaults } from '@dashforge/tw-theme';
 import clsx from 'clsx';
 import { twMerge } from 'tailwind-merge';
@@ -13,8 +13,8 @@ import * as RadixTooltip from '@radix-ui/react-tooltip';
 import * as RadixCheckbox from '@radix-ui/react-checkbox';
 import * as RadixSwitch from '@radix-ui/react-switch';
 import * as RadixRadioGroup from '@radix-ui/react-radio-group';
-import { useCalendar, resolveCalendarKey, formatLongDate, parseISODate, formatTime, generateTimeOptions, timeStringToMinutes, getTodayISODate, useDateRange } from '@dashforge/calendar-core';
 import * as RadixPopover from '@radix-ui/react-popover';
+import { useCalendar, resolveCalendarKey, formatLongDate, parseISODate, formatTime, generateTimeOptions, timeStringToMinutes, getTodayISODate, useDateRange } from '@dashforge/calendar-core';
 import * as RadixDialog from '@radix-ui/react-dialog';
 import * as RadixSlider from '@radix-ui/react-slider';
 import * as RadixMenu from '@radix-ui/react-dropdown-menu';
@@ -350,6 +350,12 @@ Spinner.displayName = 'Spinner';
         'inline-flex items-center justify-center gap-2',
         'font-medium',
         'rounded-md',
+        // Pointer affordance — the browser UA cursor for `<button>` is
+        // `default`, not `pointer`. Applies to every non-disabled state
+        // (disabled + loading override below); `variant='link'` inherits
+        // this cursor too, matching what browsers show for anchors. See
+        // README-BUG § BUG 13.
+        'cursor-pointer',
         'select-none whitespace-nowrap',
         'transition-colors',
         'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2',
@@ -1033,7 +1039,14 @@ const tooltipVariants = tv({
     const themeSlotProps = themeDefaults == null ? void 0 : themeDefaults.slotProps;
     // Option C deep-merge: instance `tooltip` over `theme…defaults.tooltip`.
     const tooltipConfig = resolveFieldTooltip(props.tooltip, themeDefaults == null ? void 0 : (_themeDefaults_defaults = themeDefaults.defaults) == null ? void 0 : _themeDefaults_defaults.tooltip);
-    const { name, rules, visibleWhen, layout = 'stacked', size, label, helperText, required, error, disabled, fullWidth, access, sx, slotProps, placeholder, type, onChange: userOnChange, onBlur: userOnBlur, value: userValue, defaultValue } = merged, rest = _object_without_properties_loose(merged, [
+    const { name, rules, visibleWhen, layout = 'stacked', size, label, helperText, required, error, disabled, fullWidth, access, sx, slotProps, placeholder, type, onChange: userOnChange, onBlur: userOnBlur, value: userValue, defaultValue, // Consume `tooltip` here so it does not leak into `...rest` and
+    // end up as an unknown HTML attribute on the rendered <input>.
+    // React 19 passes lowercase unknown attrs through silently, so
+    // the value would ship as `tooltip="…"` on the DOM without any
+    // console signal. Also strips the object form (`{ content, side, … }`)
+    // whose default stringification is `[object Object]`.
+    // See README-BUG § BUG 9.
+    tooltip: _tooltip } = merged, rest = _object_without_properties_loose(merged, [
         "name",
         "rules",
         "visibleWhen",
@@ -1053,7 +1066,8 @@ const tooltipVariants = tv({
         "onChange",
         "onBlur",
         "value",
-        "defaultValue"
+        "defaultValue",
+        "tooltip"
     ]);
     // ───── Hooks (unconditional) ─────
     const bridge = useContext(DashFormContext);
@@ -1230,6 +1244,11 @@ const tooltipVariants = tv({
             'rounded border bg-neutral-50',
             'border-neutral-300',
             'transition-colors',
+            // Radix.Checkbox.Root renders a `<button>`, whose UA cursor is
+            // `default`. The label already reads `cursor-pointer`, but the
+            // control itself needs the same affordance when the pointer
+            // sits directly on the box. See README-BUG § BUG 13.
+            'cursor-pointer',
             'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-primary-500',
             // Radix data-state hooks
             'data-[state=checked]:bg-primary-500 data-[state=checked]:border-primary-500',
@@ -1754,6 +1773,11 @@ const tooltipVariants = tv({
             'rounded-full border bg-neutral-50',
             'border-neutral-300',
             'transition-colors',
+            // Radix.RadioGroup.Item renders a `<button>`, whose UA cursor
+            // is `default`. optionLabel already reads `cursor-pointer`, but
+            // the control itself needs the same affordance when the pointer
+            // sits directly on the circle. See README-BUG § BUG 13.
+            'cursor-pointer',
             'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-primary-500',
             'data-[state=checked]:border-primary-500',
             'data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed'
@@ -1889,6 +1913,15 @@ const tooltipVariants = tv({
     // must run before the visibility early-returns so hook ordering is
     // consistent across renders. See #113 / useStandaloneFieldWarning.
     useStandaloneFieldWarning('RadioGroup', name, Boolean(bridge == null ? void 0 : bridge.register), explicitValue, onValueChange);
+    // Mirror of the above: warn if under a <DashFormProvider> AND the
+    // consumer passed controlled-mode props (silently ignored in form
+    // mode). See BUG 2 in libs/dashforge/README-BUG.md. Zero cost in
+    // production.
+    useWarnIfControlledInFormMode('RadioGroup', name, {
+        value: explicitValue,
+        defaultValue,
+        onValueChange
+    });
     // ───── Early returns ─────
     if (!isVisible) return null;
     if (!groupAccessState.visible) return null;
@@ -2136,7 +2169,11 @@ const tooltipVariants = tv({
     const themeSlotProps = themeDefaults == null ? void 0 : themeDefaults.slotProps;
     // Option C deep-merge: instance `tooltip` over `theme…defaults.tooltip`.
     const tooltipConfig = resolveFieldTooltip(props.tooltip, themeDefaults == null ? void 0 : (_themeDefaults_defaults = themeDefaults.defaults) == null ? void 0 : _themeDefaults_defaults.tooltip);
-    const { name, rules, visibleWhen, layout = 'stacked', size, resize, label, helperText, required, error, disabled, fullWidth, access, sx, slotProps, placeholder, rows = 3, onChange: userOnChange, onBlur: userOnBlur, value: userValue, defaultValue } = merged, rest = _object_without_properties_loose(merged, [
+    const { name, rules, visibleWhen, layout = 'stacked', size, resize, label, helperText, required, error, disabled, fullWidth, access, sx, slotProps, placeholder, rows = 3, onChange: userOnChange, onBlur: userOnBlur, value: userValue, defaultValue, // Consume `tooltip` here so it does not leak into `...rest` and
+    // end up as an unknown HTML attribute on the rendered <textarea>
+    // (React 19 forwards lowercase unknown attrs silently). See
+    // README-BUG § BUG 9.
+    tooltip: _tooltip } = merged, rest = _object_without_properties_loose(merged, [
         "name",
         "rules",
         "visibleWhen",
@@ -2157,7 +2194,8 @@ const tooltipVariants = tv({
         "onChange",
         "onBlur",
         "value",
-        "defaultValue"
+        "defaultValue",
+        "tooltip"
     ]);
     // ───── Hooks (unconditional) ─────
     const bridge = useContext(DashFormContext);
@@ -2436,7 +2474,11 @@ const tooltipVariants = tv({
     const themeSlotProps = themeDefaults == null ? void 0 : themeDefaults.slotProps;
     // Option C deep-merge: instance `tooltip` over `theme…defaults.tooltip`.
     const tooltipConfig = resolveFieldTooltip(props.tooltip, themeDefaults == null ? void 0 : (_themeDefaults_defaults = themeDefaults.defaults) == null ? void 0 : _themeDefaults_defaults.tooltip);
-    const { name, rules, visibleWhen, layout = 'stacked', size, label, helperText, required, error, disabled, fullWidth, access, sx, slotProps, placeholder, min, max, step = 1, showStepper = false, onChange: userOnChange, onBlur: userOnBlur, value: userValue, defaultValue } = merged, rest = _object_without_properties_loose(merged, [
+    const { name, rules, visibleWhen, layout = 'stacked', size, label, helperText, required, error, disabled, fullWidth, access, sx, slotProps, placeholder, min, max, step = 1, showStepper = false, onChange: userOnChange, onBlur: userOnBlur, value: userValue, defaultValue, // Consume `tooltip` here so it does not leak into `...rest` and
+    // end up as an unknown HTML attribute on the rendered <input>
+    // (React 19 forwards lowercase unknown attrs silently). See
+    // README-BUG § BUG 9.
+    tooltip: _tooltip } = merged, rest = _object_without_properties_loose(merged, [
         "name",
         "rules",
         "visibleWhen",
@@ -2459,7 +2501,8 @@ const tooltipVariants = tv({
         "onChange",
         "onBlur",
         "value",
-        "defaultValue"
+        "defaultValue",
+        "tooltip"
     ]);
     // ───── Hooks (unconditional) ─────
     const bridge = useContext(DashFormContext);
@@ -3185,14 +3228,51 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
  * (case-insensitive). Multi-select, free-solo text, generic option
  * shapes, and async runtime options (`optionsFromFieldData`) are
  * deferred to F5-A-bis.
- */ function Autocomplete(props) {
-    var _themeDefaults_defaults, _themeSlotProps_root, _slotProps_root, _themeSlotProps_label, _slotProps_label, _themeSlotProps_requiredMark, _slotProps_requiredMark, _themeSlotProps_inputWrapper, _slotProps_inputWrapper, _themeSlotProps_chipsList, _slotProps_chipsList, _themeSlotProps_input, _slotProps_input, _themeSlotProps_clearButton, _slotProps_clearButton, _themeSlotProps_trigger, _slotProps_trigger, _themeSlotProps_popover, _slotProps_popover, _themeSlotProps_listBox, _slotProps_listBox, _themeSlotProps_emptyState, _slotProps_emptyState, _themeSlotProps_emptyState1, _slotProps_emptyState1, _themeSlotProps_errorText, _slotProps_errorText, _themeSlotProps_helperText, _slotProps_helperText;
+ */ /**
+ * Is this event ours?
+ *
+ * "Ours" is the root PLUS the listbox, and the second half is the whole
+ * point. Since the listbox was portaled to `document.body` it is no
+ * longer inside the component's DOM subtree, so `root.contains(target)`
+ * answers FALSE for the options themselves — and two separate pieces of
+ * code used that question to mean "is this mine?":
+ *
+ *   the click-outside handler, which closed the popover and reset the
+ *   input on a mousedown over an option, before the option's own
+ *   `onClick` could run (mouse selection broken, keyboard fine);
+ *
+ *   Radix's `DismissableLayer`, which dismissed on the focus that the
+ *   combobox input itself receives.
+ *
+ * Both are BUG 7 and BUG 8 in `libs/dashforge/README-BUG.md`. The
+ * predicate exists so the rule has ONE definition and a test can pin
+ * it — `rootRef` does not span the whole widget any more, and anything
+ * here that reasons about containment has to say so out loud.
+ */ function isWithinCombobox(target, root, listbox) {
+    if (!target) return false;
+    return Boolean(root == null ? void 0 : root.contains(target)) || Boolean(listbox == null ? void 0 : listbox.contains(target));
+}
+function Autocomplete(props) {
+    var _themeDefaults_defaults, _themeSlotProps_root, _slotProps_root, _themeSlotProps_label, _slotProps_label, _themeSlotProps_requiredMark, _slotProps_requiredMark, _themeSlotProps_inputWrapper, _slotProps_inputWrapper, _themeSlotProps_chipsList, _slotProps_chipsList, _themeSlotProps_input, _slotProps_input, _themeSlotProps_clearButton, _slotProps_clearButton, _themeSlotProps_trigger, _slotProps_trigger, _themeSlotProps_input1, _slotProps_input1, _themeSlotProps_clearButton1, _slotProps_clearButton1, _themeSlotProps_trigger1, _slotProps_trigger1, _themeSlotProps_popover, _slotProps_popover, _themeSlotProps_listBox, _slotProps_listBox, _themeSlotProps_emptyState, _slotProps_emptyState, _themeSlotProps_emptyState1, _slotProps_emptyState1, _themeSlotProps_errorText, _slotProps_errorText, _themeSlotProps_helperText, _slotProps_helperText;
     const themeDefaults = useComponentDefaults('Autocomplete');
     const merged = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, props);
     const themeSlotProps = themeDefaults == null ? void 0 : themeDefaults.slotProps;
     // Option C deep-merge: instance `tooltip` over `theme…defaults.tooltip`.
     const tooltipConfig = resolveFieldTooltip(props.tooltip, themeDefaults == null ? void 0 : (_themeDefaults_defaults = themeDefaults.defaults) == null ? void 0 : _themeDefaults_defaults.tooltip);
     const { name, rules, options, visibleWhen, layout = 'stacked', size, label, helperText, required, error, disabled, fullWidth, access, sx, slotProps, placeholder, value: explicitValue, defaultValue, onValueChange, emptyMessage = 'No matching options', getOptionValue = defaultGetOptionValue, getOptionLabel = defaultGetOptionLabel, getOptionDisabled = defaultGetOptionDisabled, getOptionKey, multiple, freeSolo, loadOptions, loadDebounceMs = 250, loadingMessage = 'Loading…' } = merged;
+    // Dev-mode warning: if this Autocomplete is running under a
+    // <DashFormProvider> AND the consumer has passed any of the
+    // controlled / uncontrolled value props, warn once per
+    // (component, name, prop) that those props are silently ignored
+    // in form mode. See BUG 2 in libs/dashforge/README-BUG.md — the
+    // type-side split can only catch the `rules + defaultValue` combo
+    // at compile time; this runtime rete covers the common case where
+    // consumers pass no `rules`. Zero cost in production.
+    useWarnIfControlledInFormMode('Autocomplete', name, {
+        value: explicitValue,
+        defaultValue,
+        onValueChange
+    });
     const isMulti = Boolean(multiple);
     // Default the React-key accessor to `getOptionValue` (typical case:
     // value is unique). Consumers override only when distinct option
@@ -3510,7 +3590,9 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
         const handlePointerDown = (event)=>{
             const root = rootRef.current;
             if (!root) return;
-            if (root.contains(event.target)) return;
+            // The listbox counts as ours even though it is portaled out of
+            // the root — see `isWithinCombobox`.
+            if (isWithinCombobox(event.target, root, listboxRef.current)) return;
             closePopover();
             // Multi mode: just clear the filter query (chips remain).
             // Single + free-solo: commit the typed text as the value (the
@@ -3789,127 +3871,254 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
                     children: "*"
                 }))
             }),
-            jsxs("div", {
-                className: cn(v.inputWrapper(), // Multi mode: let chips wrap and replace the fixed `h-*`
-                // with `min-h-*` so the wrapper grows with selections.
-                isMulti && 'flex-wrap min-h-[var(--ac-min-h,2.5rem)] !h-auto py-1', themeSlotProps == null ? void 0 : (_themeSlotProps_inputWrapper = themeSlotProps.inputWrapper) == null ? void 0 : _themeSlotProps_inputWrapper.className, slotProps == null ? void 0 : (_slotProps_inputWrapper = slotProps.inputWrapper) == null ? void 0 : _slotProps_inputWrapper.className),
+            jsxs(RadixPopover.Root, {
+                open: isOpen,
+                onOpenChange: (next)=>{
+                    if (!next) setIsOpen(false);
+                },
+                modal: false,
                 children: [
-                    isMulti && selectedKeys.size > 0 && jsx("div", {
-                        className: cn(v.chipsList(), themeSlotProps == null ? void 0 : (_themeSlotProps_chipsList = themeSlotProps.chipsList) == null ? void 0 : _themeSlotProps_chipsList.className, slotProps == null ? void 0 : (_slotProps_chipsList = slotProps.chipsList) == null ? void 0 : _slotProps_chipsList.className),
-                        children: Array.from(selectedKeys).map((key)=>{
-                            var _labelAsString;
-                            var _themeSlotProps_chip, _slotProps_chip, _themeSlotProps_chipRemove, _slotProps_chipRemove;
-                            const opt = options.find((o)=>getOptionValue(o) === key);
-                            const labelNode = opt ? getOptionLabel(opt) : key;
-                            const labelText = opt ? (_labelAsString = labelAsString(opt)) != null ? _labelAsString : key : key;
-                            return jsxs("span", {
-                                className: cn(v.chip(), themeSlotProps == null ? void 0 : (_themeSlotProps_chip = themeSlotProps.chip) == null ? void 0 : _themeSlotProps_chip.className, slotProps == null ? void 0 : (_slotProps_chip = slotProps.chip) == null ? void 0 : _slotProps_chip.className),
-                                "data-chip-key": key,
-                                children: [
-                                    labelNode,
-                                    !effectiveDisabled && !effectiveReadOnly && jsx("button", {
-                                        type: "button",
-                                        onMouseDown: preventBlur,
-                                        onClick: ()=>{
-                                            var _inputRef_current;
-                                            commitSelection(key); // toggle removes
-                                            (_inputRef_current = inputRef.current) == null ? void 0 : _inputRef_current.focus();
-                                        },
-                                        "aria-label": `Remove ${labelText}`,
-                                        tabIndex: -1,
-                                        className: cn(v.chipRemove(), themeSlotProps == null ? void 0 : (_themeSlotProps_chipRemove = themeSlotProps.chipRemove) == null ? void 0 : _themeSlotProps_chipRemove.className, slotProps == null ? void 0 : (_slotProps_chipRemove = slotProps.chipRemove) == null ? void 0 : _slotProps_chipRemove.className),
-                                        children: jsx(CloseIcon, {})
+                    jsx(RadixPopover.Anchor, {
+                        asChild: true,
+                        children: jsxs("div", {
+                            className: cn(v.inputWrapper(), // Multi mode: let chips wrap and replace the fixed `h-*`
+                            // with `min-h-*` so the wrapper grows with selections.
+                            isMulti && 'flex-wrap min-h-[var(--ac-min-h,2.5rem)] !h-auto py-1', themeSlotProps == null ? void 0 : (_themeSlotProps_inputWrapper = themeSlotProps.inputWrapper) == null ? void 0 : _themeSlotProps_inputWrapper.className, slotProps == null ? void 0 : (_slotProps_inputWrapper = slotProps.inputWrapper) == null ? void 0 : _slotProps_inputWrapper.className),
+                            children: [
+                                isMulti && selectedKeys.size > 0 && jsx("div", {
+                                    className: cn(v.chipsList(), themeSlotProps == null ? void 0 : (_themeSlotProps_chipsList = themeSlotProps.chipsList) == null ? void 0 : _themeSlotProps_chipsList.className, slotProps == null ? void 0 : (_slotProps_chipsList = slotProps.chipsList) == null ? void 0 : _slotProps_chipsList.className),
+                                    children: Array.from(selectedKeys).map((key)=>{
+                                        var _labelAsString;
+                                        var _themeSlotProps_chip, _slotProps_chip, _themeSlotProps_chipRemove, _slotProps_chipRemove;
+                                        const opt = options.find((o)=>getOptionValue(o) === key);
+                                        const labelNode = opt ? getOptionLabel(opt) : key;
+                                        const labelText = opt ? (_labelAsString = labelAsString(opt)) != null ? _labelAsString : key : key;
+                                        return jsxs("span", {
+                                            className: cn(v.chip(), themeSlotProps == null ? void 0 : (_themeSlotProps_chip = themeSlotProps.chip) == null ? void 0 : _themeSlotProps_chip.className, slotProps == null ? void 0 : (_slotProps_chip = slotProps.chip) == null ? void 0 : _slotProps_chip.className),
+                                            "data-chip-key": key,
+                                            children: [
+                                                labelNode,
+                                                !effectiveDisabled && !effectiveReadOnly && jsx("button", {
+                                                    type: "button",
+                                                    onMouseDown: preventBlur,
+                                                    onClick: ()=>{
+                                                        var _inputRef_current;
+                                                        commitSelection(key); // toggle removes
+                                                        (_inputRef_current = inputRef.current) == null ? void 0 : _inputRef_current.focus();
+                                                    },
+                                                    "aria-label": `Remove ${labelText}`,
+                                                    tabIndex: -1,
+                                                    className: cn(v.chipRemove(), themeSlotProps == null ? void 0 : (_themeSlotProps_chipRemove = themeSlotProps.chipRemove) == null ? void 0 : _themeSlotProps_chipRemove.className, slotProps == null ? void 0 : (_slotProps_chipRemove = slotProps.chipRemove) == null ? void 0 : _slotProps_chipRemove.className),
+                                                    children: jsx(CloseIcon, {})
+                                                })
+                                            ]
+                                        }, key);
                                     })
-                                ]
-                            }, key);
+                                }),
+                                isMulti ? jsxs("div", {
+                                    className: cn(// `min-w-0` on the controls group (and on the input
+                                    // below) so the input can shrink when chips have taken
+                                    // most of the outer wrapper's width. Without it, the
+                                    // group's intrinsic min-content-size (input floor +
+                                    // shrink-0 buttons) pushed the chevron past the right
+                                    // edge by ~6px, which turned into a horizontal scrollbar
+                                    // inside a `<Dialog>` (whose body is `overflow-y-auto`
+                                    // and so computes `overflow-x: auto`). See BUG 5 in
+                                    // README-BUG.md — the regression from the BUG 3 fix.
+                                    'flex items-center flex-nowrap flex-1 min-w-0', // The gap keeps the clear × visually separated from the
+                                    // chevron when both are present.
+                                    hasAnySelection && !effectiveDisabled && !effectiveReadOnly && 'gap-0.5'),
+                                    children: [
+                                        jsx("input", {
+                                            ref: inputRef,
+                                            id: `${baseId}-input`,
+                                            name: name,
+                                            type: "text",
+                                            role: "combobox",
+                                            "aria-autocomplete": "list",
+                                            "aria-expanded": isOpen,
+                                            "aria-controls": isOpen ? listboxId : undefined,
+                                            "aria-activedescendant": activeOptionId,
+                                            "aria-labelledby": label ? labelId : undefined,
+                                            "aria-describedby": resolvedHelperText ? helperId : undefined,
+                                            "aria-invalid": resolvedError ? true : undefined,
+                                            "aria-required": required ? true : undefined,
+                                            placeholder: // In multi mode hide the placeholder once the user has
+                                            // at least one chip — chips already convey "something
+                                            // is selected".
+                                            selectedKeys.size > 0 ? undefined : placeholder,
+                                            value: displayInputValue,
+                                            onChange: handleInputChange,
+                                            onKeyDown: handleKeyDown,
+                                            onFocus: openPopover,
+                                            onBlur: handleBlur,
+                                            disabled: effectiveDisabled,
+                                            readOnly: effectiveReadOnly,
+                                            autoComplete: "off",
+                                            // `flex-1` inside the non-wrap controls row: the input
+                                            // expands to consume whatever the controls-row has left
+                                            // after the two buttons. `basis-24` is the *preferred*
+                                            // starting size; `min-w-0` lets the input shrink below
+                                            // that when chips have consumed most of the outer
+                                            // wrapper — same BUG 5 rationale as the group's
+                                            // `min-w-0`. Buttons stay `shrink-0` and always
+                                            // reachable; the input becomes narrow but still usable.
+                                            className: cn(v.input(), 'min-w-0 flex-1 basis-24', themeSlotProps == null ? void 0 : (_themeSlotProps_input = themeSlotProps.input) == null ? void 0 : _themeSlotProps_input.className, slotProps == null ? void 0 : (_slotProps_input = slotProps.input) == null ? void 0 : _slotProps_input.className)
+                                        }),
+                                        hasAnySelection && !effectiveDisabled && !effectiveReadOnly && jsx("button", {
+                                            type: "button",
+                                            onMouseDown: preventBlur,
+                                            onClick: handleClearClick,
+                                            "aria-label": "Clear selection",
+                                            tabIndex: -1,
+                                            className: cn(v.clearButton(), themeSlotProps == null ? void 0 : (_themeSlotProps_clearButton = themeSlotProps.clearButton) == null ? void 0 : _themeSlotProps_clearButton.className, slotProps == null ? void 0 : (_slotProps_clearButton = slotProps.clearButton) == null ? void 0 : _slotProps_clearButton.className),
+                                            children: jsx(CloseIcon, {})
+                                        }),
+                                        jsx("button", {
+                                            type: "button",
+                                            onMouseDown: preventBlur,
+                                            onClick: handleTriggerClick,
+                                            "aria-label": "Open",
+                                            "aria-haspopup": "listbox",
+                                            "aria-expanded": isOpen,
+                                            tabIndex: -1,
+                                            disabled: effectiveDisabled,
+                                            className: cn(v.trigger(), themeSlotProps == null ? void 0 : (_themeSlotProps_trigger = themeSlotProps.trigger) == null ? void 0 : _themeSlotProps_trigger.className, slotProps == null ? void 0 : (_slotProps_trigger = slotProps.trigger) == null ? void 0 : _slotProps_trigger.className),
+                                            children: jsx(ChevronDownIcon$1, {})
+                                        })
+                                    ]
+                                }) : jsxs(Fragment, {
+                                    children: [
+                                        jsx("input", {
+                                            ref: inputRef,
+                                            id: `${baseId}-input`,
+                                            name: name,
+                                            type: "text",
+                                            role: "combobox",
+                                            "aria-autocomplete": "list",
+                                            "aria-expanded": isOpen,
+                                            "aria-controls": isOpen ? listboxId : undefined,
+                                            "aria-activedescendant": activeOptionId,
+                                            "aria-labelledby": label ? labelId : undefined,
+                                            "aria-describedby": resolvedHelperText ? helperId : undefined,
+                                            "aria-invalid": resolvedError ? true : undefined,
+                                            "aria-required": required ? true : undefined,
+                                            placeholder: placeholder,
+                                            value: displayInputValue,
+                                            onChange: handleInputChange,
+                                            onKeyDown: handleKeyDown,
+                                            onFocus: openPopover,
+                                            onBlur: handleBlur,
+                                            disabled: effectiveDisabled,
+                                            readOnly: effectiveReadOnly,
+                                            autoComplete: "off",
+                                            className: cn(v.input(), themeSlotProps == null ? void 0 : (_themeSlotProps_input1 = themeSlotProps.input) == null ? void 0 : _themeSlotProps_input1.className, slotProps == null ? void 0 : (_slotProps_input1 = slotProps.input) == null ? void 0 : _slotProps_input1.className)
+                                        }),
+                                        hasAnySelection && !effectiveDisabled && !effectiveReadOnly && jsx("button", {
+                                            type: "button",
+                                            onMouseDown: preventBlur,
+                                            onClick: handleClearClick,
+                                            "aria-label": "Clear selection",
+                                            tabIndex: -1,
+                                            className: cn(v.clearButton(), themeSlotProps == null ? void 0 : (_themeSlotProps_clearButton1 = themeSlotProps.clearButton) == null ? void 0 : _themeSlotProps_clearButton1.className, slotProps == null ? void 0 : (_slotProps_clearButton1 = slotProps.clearButton) == null ? void 0 : _slotProps_clearButton1.className),
+                                            children: jsx(CloseIcon, {})
+                                        }),
+                                        jsx("button", {
+                                            type: "button",
+                                            onMouseDown: preventBlur,
+                                            onClick: handleTriggerClick,
+                                            "aria-label": "Open",
+                                            "aria-haspopup": "listbox",
+                                            "aria-expanded": isOpen,
+                                            tabIndex: -1,
+                                            disabled: effectiveDisabled,
+                                            className: cn(v.trigger(), themeSlotProps == null ? void 0 : (_themeSlotProps_trigger1 = themeSlotProps.trigger) == null ? void 0 : _themeSlotProps_trigger1.className, slotProps == null ? void 0 : (_slotProps_trigger1 = slotProps.trigger) == null ? void 0 : _slotProps_trigger1.className),
+                                            children: jsx(ChevronDownIcon$1, {})
+                                        })
+                                    ]
+                                })
+                            ]
                         })
                     }),
-                    jsx("input", {
-                        ref: inputRef,
-                        id: `${baseId}-input`,
-                        name: name,
-                        type: "text",
-                        role: "combobox",
-                        "aria-autocomplete": "list",
-                        "aria-expanded": isOpen,
-                        "aria-controls": isOpen ? listboxId : undefined,
-                        "aria-activedescendant": activeOptionId,
-                        "aria-labelledby": label ? labelId : undefined,
-                        "aria-describedby": resolvedHelperText ? helperId : undefined,
-                        "aria-invalid": resolvedError ? true : undefined,
-                        "aria-required": required ? true : undefined,
-                        placeholder: // In multi mode hide the placeholder once the user has at
-                        // least one chip — the chips already convey "something is
-                        // selected" and the placeholder would clutter the UI.
-                        isMulti && selectedKeys.size > 0 ? undefined : placeholder,
-                        value: displayInputValue,
-                        onChange: handleInputChange,
-                        onKeyDown: handleKeyDown,
-                        onFocus: openPopover,
-                        onBlur: handleBlur,
-                        disabled: effectiveDisabled,
-                        readOnly: effectiveReadOnly,
-                        autoComplete: "off",
-                        // Multi mode: give the input some min-width so it stays
-                        // clickable even with many chips, and let it shrink/grow with
-                        // the available row space.
-                        className: cn(v.input(), isMulti && 'min-w-[6rem] flex-1 basis-24', themeSlotProps == null ? void 0 : (_themeSlotProps_input = themeSlotProps.input) == null ? void 0 : _themeSlotProps_input.className, slotProps == null ? void 0 : (_slotProps_input = slotProps.input) == null ? void 0 : _slotProps_input.className)
-                    }),
-                    hasAnySelection && !effectiveDisabled && !effectiveReadOnly && jsx("button", {
-                        type: "button",
-                        onMouseDown: preventBlur,
-                        onClick: handleClearClick,
-                        "aria-label": "Clear selection",
-                        tabIndex: -1,
-                        className: cn(v.clearButton(), themeSlotProps == null ? void 0 : (_themeSlotProps_clearButton = themeSlotProps.clearButton) == null ? void 0 : _themeSlotProps_clearButton.className, slotProps == null ? void 0 : (_slotProps_clearButton = slotProps.clearButton) == null ? void 0 : _slotProps_clearButton.className),
-                        children: jsx(CloseIcon, {})
-                    }),
-                    jsx("button", {
-                        type: "button",
-                        onMouseDown: preventBlur,
-                        onClick: handleTriggerClick,
-                        "aria-label": "Open",
-                        "aria-haspopup": "listbox",
-                        "aria-expanded": isOpen,
-                        tabIndex: -1,
-                        disabled: effectiveDisabled,
-                        className: cn(v.trigger(), themeSlotProps == null ? void 0 : (_themeSlotProps_trigger = themeSlotProps.trigger) == null ? void 0 : _themeSlotProps_trigger.className, slotProps == null ? void 0 : (_slotProps_trigger = slotProps.trigger) == null ? void 0 : _slotProps_trigger.className),
-                        children: jsx(ChevronDownIcon$1, {})
-                    }),
-                    isOpen && jsx("ul", {
-                        ref: listboxRef,
-                        id: listboxId,
-                        role: "listbox",
-                        "aria-labelledby": label ? labelId : undefined,
-                        className: cn(v.popover(), 'absolute left-0 right-0 top-full', v.listBox(), themeSlotProps == null ? void 0 : (_themeSlotProps_popover = themeSlotProps.popover) == null ? void 0 : _themeSlotProps_popover.className, slotProps == null ? void 0 : (_slotProps_popover = slotProps.popover) == null ? void 0 : _slotProps_popover.className, themeSlotProps == null ? void 0 : (_themeSlotProps_listBox = themeSlotProps.listBox) == null ? void 0 : _themeSlotProps_listBox.className, slotProps == null ? void 0 : (_slotProps_listBox = slotProps.listBox) == null ? void 0 : _slotProps_listBox.className),
-                        children: isLoading ? jsx("li", {
-                            className: cn(v.emptyState(), themeSlotProps == null ? void 0 : (_themeSlotProps_emptyState = themeSlotProps.emptyState) == null ? void 0 : _themeSlotProps_emptyState.className, slotProps == null ? void 0 : (_slotProps_emptyState = slotProps.emptyState) == null ? void 0 : _slotProps_emptyState.className),
-                            "aria-live": "polite",
-                            "aria-busy": "true",
-                            children: loadingMessage
-                        }) : filteredOptions.length === 0 ? jsx("li", {
-                            className: cn(v.emptyState(), themeSlotProps == null ? void 0 : (_themeSlotProps_emptyState1 = themeSlotProps.emptyState) == null ? void 0 : _themeSlotProps_emptyState1.className, slotProps == null ? void 0 : (_slotProps_emptyState1 = slotProps.emptyState) == null ? void 0 : _slotProps_emptyState1.className),
-                            children: emptyMessage
-                        }) : filteredOptions.map((opt, idx)=>{
-                            var _themeSlotProps_listItem, _slotProps_listItem;
-                            const optValue = getOptionValue(opt);
-                            const optDisabled = getOptionDisabled(opt);
-                            const isHighlighted = idx === highlightedIndex;
-                            const isSelected = selectedKeys.has(optValue);
-                            return jsx("li", {
-                                id: `${optionIdPrefix}${optValue}`,
-                                role: "option",
-                                "aria-selected": isSelected,
-                                "aria-disabled": optDisabled || undefined,
-                                "data-focused": isHighlighted || undefined,
-                                "data-selected": isSelected || undefined,
-                                "data-disabled": optDisabled || undefined,
-                                onMouseDown: preventBlur,
-                                onClick: ()=>handleOptionClick(opt),
-                                onMouseEnter: ()=>setHighlightedIndex(idx),
-                                className: cn(v.listItem(), themeSlotProps == null ? void 0 : (_themeSlotProps_listItem = themeSlotProps.listItem) == null ? void 0 : _themeSlotProps_listItem.className, slotProps == null ? void 0 : (_slotProps_listItem = slotProps.listItem) == null ? void 0 : _slotProps_listItem.className),
-                                children: getOptionLabel(opt)
-                            }, resolveOptionKey(opt));
+                    isOpen && jsx(RadixPopover.Portal, {
+                        children: jsx(RadixPopover.Content, {
+                            asChild: true,
+                            side: "bottom",
+                            align: "start",
+                            sideOffset: 4,
+                            collisionPadding: 8,
+                            // Anchor width → listbox width (Radix exposes this CSS var).
+                            style: {
+                                width: 'var(--radix-popover-trigger-width)'
+                            },
+                            // Focus stays on the combobox input; Radix must not steal it.
+                            onOpenAutoFocus: (e)=>e.preventDefault(),
+                            onCloseAutoFocus: (e)=>e.preventDefault(),
+                            /*
+                              THE COMBOBOX INPUT IS NOT "OUTSIDE".
+                  
+                              In a combobox the focused element is the `<input>`, and the
+                              input is the ANCHOR — it lives outside `Popover.Content`.
+                              Radix's `DismissableLayer` does not know that: it sees a
+                              `focusin` on an element outside the layer and dismisses.
+                  
+                              The symptom is that the listbox opens on focus and closes
+                              about 10ms later, so the FIRST keystroke after clicking the
+                              field never shows suggestions and the field looks broken.
+                              Later keystrokes work, because they raise no new focus
+                              event — which makes it look intermittent rather than
+                              systematic.
+                  
+                              Both handlers guard on the component root, which contains
+                              the input, the chevron and the clear button. Anything
+                              genuinely outside still dismisses, so click-away is
+                              unaffected.
+                            */ onFocusOutside: (event)=>{
+                                if (isWithinCombobox(event.target, rootRef.current, listboxRef.current)) {
+                                    event.preventDefault();
+                                }
+                            },
+                            onInteractOutside: (event)=>{
+                                if (isWithinCombobox(event.target, rootRef.current, listboxRef.current)) {
+                                    event.preventDefault();
+                                }
+                            },
+                            children: jsx("ul", {
+                                ref: listboxRef,
+                                id: listboxId,
+                                role: "listbox",
+                                "aria-labelledby": label ? labelId : undefined,
+                                className: cn(v.popover(), v.listBox(), themeSlotProps == null ? void 0 : (_themeSlotProps_popover = themeSlotProps.popover) == null ? void 0 : _themeSlotProps_popover.className, slotProps == null ? void 0 : (_slotProps_popover = slotProps.popover) == null ? void 0 : _slotProps_popover.className, themeSlotProps == null ? void 0 : (_themeSlotProps_listBox = themeSlotProps.listBox) == null ? void 0 : _themeSlotProps_listBox.className, slotProps == null ? void 0 : (_slotProps_listBox = slotProps.listBox) == null ? void 0 : _slotProps_listBox.className),
+                                children: isLoading ? jsx("li", {
+                                    className: cn(v.emptyState(), themeSlotProps == null ? void 0 : (_themeSlotProps_emptyState = themeSlotProps.emptyState) == null ? void 0 : _themeSlotProps_emptyState.className, slotProps == null ? void 0 : (_slotProps_emptyState = slotProps.emptyState) == null ? void 0 : _slotProps_emptyState.className),
+                                    "aria-live": "polite",
+                                    "aria-busy": "true",
+                                    children: loadingMessage
+                                }) : filteredOptions.length === 0 ? jsx("li", {
+                                    className: cn(v.emptyState(), themeSlotProps == null ? void 0 : (_themeSlotProps_emptyState1 = themeSlotProps.emptyState) == null ? void 0 : _themeSlotProps_emptyState1.className, slotProps == null ? void 0 : (_slotProps_emptyState1 = slotProps.emptyState) == null ? void 0 : _slotProps_emptyState1.className),
+                                    children: emptyMessage
+                                }) : filteredOptions.map((opt, idx)=>{
+                                    var _themeSlotProps_listItem, _slotProps_listItem;
+                                    const optValue = getOptionValue(opt);
+                                    const optDisabled = getOptionDisabled(opt);
+                                    const isHighlighted = idx === highlightedIndex;
+                                    const isSelected = selectedKeys.has(optValue);
+                                    return jsx("li", {
+                                        id: `${optionIdPrefix}${optValue}`,
+                                        role: "option",
+                                        "aria-selected": isSelected,
+                                        "aria-disabled": optDisabled || undefined,
+                                        "data-focused": isHighlighted || undefined,
+                                        "data-selected": isSelected || undefined,
+                                        "data-disabled": optDisabled || undefined,
+                                        onMouseDown: preventBlur,
+                                        onClick: ()=>handleOptionClick(opt),
+                                        onMouseEnter: ()=>setHighlightedIndex(idx),
+                                        className: cn(v.listItem(), themeSlotProps == null ? void 0 : (_themeSlotProps_listItem = themeSlotProps.listItem) == null ? void 0 : _themeSlotProps_listItem.className, slotProps == null ? void 0 : (_slotProps_listItem = slotProps.listItem) == null ? void 0 : _slotProps_listItem.className),
+                                        children: getOptionLabel(opt)
+                                    }, resolveOptionKey(opt));
+                                })
+                            })
                         })
                     })
                 ]
@@ -4415,6 +4624,15 @@ function CalendarIcon$2() {
             });
         };
     }, []);
+    // Dev-mode warning: if under <DashFormProvider> AND the consumer
+    // passed controlled-mode props (silently ignored in form mode),
+    // fire once per (component, name, prop). Zero cost in prod. See
+    // BUG 2 in libs/dashforge/README-BUG.md.
+    useWarnIfControlledInFormMode('DatePicker', name, {
+        value: explicitValue,
+        defaultValue,
+        onChange
+    });
     // ───── Derived ─────
     const effectiveDisabled = Boolean(disabled) || accessState.disabled;
     const effectiveReadOnly = accessState.readonly;
@@ -10078,7 +10296,7 @@ Slider.displayName = 'Slider';
             'data-[disabled=true]:opacity-50 data-[disabled=true]:cursor-not-allowed'
         ],
         listItemIndicator: [
-            'shrink-0 w-4 text-primary-700',
+            'shrink-0 w-4 h-4 text-primary-700',
             'opacity-0 data-[selected=true]:opacity-100'
         ],
         emptyState: 'px-3 py-2 text-sm text-neutral-500',
@@ -10249,6 +10467,17 @@ Slider.displayName = 'Slider';
     const helperId = `${controlId}-help`;
     const isFormMode = Boolean(bridge == null ? void 0 : bridge.register);
     useStandaloneFieldWarning('Select', name, isFormMode, userValue, onChange);
+    // Mirror of useStandaloneFieldWarning: warn when running under a
+    // <DashFormProvider> AND the consumer passed controlled-mode props
+    // that are silently ignored in form mode. See BUG 2 in
+    // libs/dashforge/README-BUG.md — closes the case the type-side
+    // discriminant cannot see (React context is invisible at compile
+    // time). Zero cost in production.
+    useWarnIfControlledInFormMode('Select', name, {
+        value: userValue,
+        defaultValue,
+        onChange
+    });
     // StrictMode-safe unregister
     const unregisterRef = useRef({
         bridge,
@@ -15208,10 +15437,10 @@ VisuallyHidden.displayName = 'VisuallyHidden';
  * `useConfirm()` from `ConfirmDialog`). Use `<Dialog>` when you want
  * the control flow living in your component tree.
  */ function Dialog(props) {
-    var _themeSlotProps_overlay, _slotProps_overlay, _themeSlotProps_content, _slotProps_content, _themeSlotProps_title, _slotProps_title, _themeSlotProps_description, _slotProps_description, _themeSlotProps_body, _slotProps_body, _themeSlotProps_closeButton, _slotProps_closeButton;
+    var _themeSlotProps_overlay, _slotProps_overlay, _themeSlotProps_content, _slotProps_content, _themeSlotProps_title, _slotProps_title, _themeSlotProps_description, _slotProps_description, _themeSlotProps_body, _slotProps_body, _themeSlotProps_actions, _slotProps_actions, _themeSlotProps_closeButton, _slotProps_closeButton;
     const themeDefaults = useComponentDefaults('Dialog');
     const merged = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, props);
-    const { open, onOpenChange, children, title, description, showCloseButton = true, disableBackdropClose = false, disableEscapeClose = false, size = 'md', sx, slotProps } = merged;
+    const { open, onOpenChange, children, title, description, actions, showCloseButton = true, disableBackdropClose = false, disableEscapeClose = false, size = 'md', sx, slotProps } = merged;
     // Theme-level slotProps (Option C Track B). Theme classes go first,
     // instance classes second, so `tailwind-merge` picks the instance
     // where they collide.
@@ -15251,6 +15480,10 @@ VisuallyHidden.displayName = 'VisuallyHidden';
                             className: cn(v.body(), themeSlotProps == null ? void 0 : (_themeSlotProps_body = themeSlotProps.body) == null ? void 0 : _themeSlotProps_body.className, slotProps == null ? void 0 : (_slotProps_body = slotProps.body) == null ? void 0 : _slotProps_body.className),
                             children: children
                         }),
+                        actions != null && jsx("div", {
+                            className: cn(v.actions(), themeSlotProps == null ? void 0 : (_themeSlotProps_actions = themeSlotProps.actions) == null ? void 0 : _themeSlotProps_actions.className, slotProps == null ? void 0 : (_slotProps_actions = slotProps.actions) == null ? void 0 : _slotProps_actions.className),
+                            children: actions
+                        }),
                         showCloseButton && jsx(RadixDialog.Close, {
                             "aria-label": "Close",
                             className: cn(v.closeButton(), themeSlotProps == null ? void 0 : (_themeSlotProps_closeButton = themeSlotProps.closeButton) == null ? void 0 : _themeSlotProps_closeButton.className, slotProps == null ? void 0 : (_slotProps_closeButton = slotProps.closeButton) == null ? void 0 : _slotProps_closeButton.className),
@@ -15283,6 +15516,11 @@ const tabsVariants = tv({
         trigger: [
             'inline-flex items-center justify-center whitespace-nowrap',
             'text-sm font-medium transition-colors',
+            // Radix Tabs.Trigger renders a `<button>`, whose UA cursor is
+            // `default`. `disabled:pointer-events-none` neutralises it on
+            // the disabled state (no pointer events → no cursor swap). See
+            // README-BUG § BUG 13.
+            'cursor-pointer',
             'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
             'disabled:opacity-50 disabled:pointer-events-none',
             'motion-reduce:transition-none'
@@ -19406,6 +19644,6 @@ function SearchIcon(props) {
  */ // ───── Components ─────
 /**
  * Package version (synced with `package.json` at publish time).
- */ const VERSION = '1.5.1';
+ */ const VERSION = '1.5.2';
 
 export { AVATAR_SOFT_FALLBACK, AVATAR_TONE_FALLBACK, Accordion, Alert, AlertTitle, AppShell, AspectRatio, Autocomplete, Avatar, AvatarGroup, Badge, Box, Breadcrumbs, Button, Calendar, Card, CardActionArea, CardContent, Checkbox, Chip, ConfirmDialogProvider, Container, DRAWER_SIZE_PRESETS, DataGrid, DatePicker, DateRangePicker, DateTimePicker, Dialog, Divider, Drawer, Grid, ICON_BUTTON_BASE, ICON_BUTTON_SIZE_OVERRIDES, IconButton, Image, LeftNav, Link, Menu, MenuContent, MenuItem, MenuLabel, MenuSeparator, MenuSkeleton, MenuTrigger, NumberField, OTPField, Pagination, Popover, Progress, RadioGroup, RenderButton, RenderChip, RenderText, RenderTwoLine, RowActionsMenu, SPINNER_COLORS, SPINNER_STROKE_WIDTH, SPINNER_TRACK_OPACITY, Select, Skeleton, Slider, SnackbarProvider, Spinner, Stack, Step, Stepper, Switch, Table, Tabs, TextField, Textarea, TimePicker, Tooltip, TopBar, Typography, VERSION, Video, VisuallyHidden, accordionVariants, alertVariants, appShellVariants, autocompleteVariants, avatarVariants, badgeVariants, boxVariants, breadcrumbsVariants, buttonVariants, calendarDayVariants, calendarVariants, checkboxVariants, chipVariants, cn, confirmDialogVariants, containerVariants, dataGridVariants, datePickerVariants, dateRangeDayVariants, dateRangePickerVariants, dateTimePickerVariants, dialogVariants, dividerLineVariants, dividerVariants, drawerVariants, getNestedValue, gridVariants, imageVariants, leftNavVariants, linkVariants, menuVariants, numberFieldVariants, otpFieldVariants, paginationVariants, popoverVariants, progressVariants, radioGroupVariants, selectVariants, skeletonVariants, sliderVariants, snackbarVariants, spinnerVariants, stackVariants, stepperVariants, switchVariants, tableVariants, tabsVariants, textFieldVariants, textareaVariants, timePickerVariants, tooltipVariants, topBarVariants, typographyVariants, useAccessState, useConfirm, useSnackbar, useStep, videoVariants };