@dashforge/tw 1.5.2 → 1.7.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);
@@ -1081,6 +1095,11 @@ const tooltipVariants = tv({
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -1230,6 +1249,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',
@@ -1238,6 +1262,10 @@ const tooltipVariants = tv({
         ],
         indicator: 'flex items-center justify-center text-white',
         label: 'select-none cursor-pointer text-neutral-900',
+        // BUG 21: `*` marker after the label, matching the `textField.variants.ts`
+        // `requiredMark` slot so a consent box aligns visually with sibling
+        // required fields in a form.
+        requiredMark: 'text-danger-500 ml-0.5',
         helperText: 'text-sm text-neutral-600 mt-1',
         errorText: 'text-sm text-danger-600 mt-1'
     },
@@ -1346,13 +1374,13 @@ const tooltipVariants = tv({
  *    rather than MUI slot components.
  */ function Checkbox(props) {
     var _ref;
-    var _themeDefaults_defaults, _themeSlotProps_root, _slotProps_root, _themeSlotProps_control, _slotProps_control, _themeSlotProps_indicator, _slotProps_indicator, _themeSlotProps_label, _slotProps_label, _themeSlotProps_errorText, _slotProps_errorText, _themeSlotProps_helperText, _slotProps_helperText;
+    var _themeDefaults_defaults, _themeSlotProps_root, _slotProps_root, _themeSlotProps_control, _slotProps_control, _themeSlotProps_indicator, _slotProps_indicator, _themeSlotProps_label, _slotProps_label, _themeSlotProps_requiredMark, _slotProps_requiredMark, _themeSlotProps_errorText, _slotProps_errorText, _themeSlotProps_helperText, _slotProps_helperText;
     const themeDefaults = useComponentDefaults('Checkbox');
     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, visibleWhen, label, helperText, error, access, size, disabled, checked, defaultChecked, onCheckedChange, sx, slotProps } = merged;
+    const { name, rules, visibleWhen, label, helperText, error, access, size, disabled, required, checked, defaultChecked, onCheckedChange, sx, slotProps } = merged;
     // ───── Hooks (always called, unconditional) ─────
     const bridge = useContext(DashFormContext);
     const isVisible = useEngineVisibility(bridge == null ? void 0 : bridge.engine, visibleWhen);
@@ -1362,6 +1390,32 @@ const tooltipVariants = tv({
     const fieldMeta = useDashFieldMeta(name);
     const accessState = useAccessState(access);
     const controlId = useId();
+    // BUG 21 v2: local ref for the Radix Root DOM button. We use this to
+    // set `aria-required` post-mount because setting the attribute via a
+    // JSX prop on `RadixCheckbox.Root` does not reach the browser DOM in
+    // production builds (verified empirically in urbango on Radix v1.3.3;
+    // jsdom does not surface the same gap).
+    const buttonRef = useRef(null);
+    const setControlRef = (node)=>{
+        buttonRef.current = node;
+        const regRef = registration == null ? void 0 : registration.ref;
+        if (typeof regRef === 'function') {
+            regRef(node);
+        } else if (regRef && typeof regRef === 'object') {
+            regRef.current = node;
+        }
+    };
+    useEffect(()=>{
+        const node = buttonRef.current;
+        if (!node) return;
+        if (required) {
+            node.setAttribute('aria-required', 'true');
+        } else {
+            node.removeAttribute('aria-required');
+        }
+    }, [
+        required
+    ]);
     // StrictMode-safe unregister-on-unmount — mirrors MUI Checkbox.tsx
     // (the bridge identity changes on every keystroke, so we MUST NOT
     // re-run cleanup on deps changes — empty deps + ref pattern).
@@ -1379,6 +1433,11 @@ const tooltipVariants = tv({
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -1467,9 +1526,19 @@ const tooltipVariants = tv({
                 name: name
             }, radixStateProps, {
                 disabled: effectiveDisabled,
+                required: required,
                 onCheckedChange: handleCheckedChange,
                 onBlur: handleBlur,
-                ref: registration == null ? void 0 : registration.ref,
+                // BUG 21 v2: compose our own ref with `registration.ref` so we can
+                // ALSO set `aria-required` post-mount via a `useEffect` below. The
+                // JSX-level `aria-required` prop was verified empirically not to
+                // reach the DOM in a real browser (Radix v1.3.3 reads its own
+                // `required` prop into context and re-emits `aria-required` from
+                // the internal trigger, but the attribute is stripped somewhere
+                // in the production path — jsdom does not catch it). Post-mount
+                // ref-based setter is Radix-version-agnostic and lands on the
+                // element the browser actually shows.
+                ref: setControlRef,
                 className: cn(v.control(), themeSlotProps == null ? void 0 : (_themeSlotProps_control = themeSlotProps.control) == null ? void 0 : _themeSlotProps_control.className, slotProps == null ? void 0 : (_slotProps_control = slotProps.control) == null ? void 0 : _slotProps_control.className),
                 children: jsxs(RadixCheckbox.Indicator, {
                     className: cn(v.indicator(), 'group', themeSlotProps == null ? void 0 : (_themeSlotProps_indicator = themeSlotProps.indicator) == null ? void 0 : _themeSlotProps_indicator.className, slotProps == null ? void 0 : (_slotProps_indicator = slotProps.indicator) == null ? void 0 : _slotProps_indicator.className),
@@ -1486,10 +1555,17 @@ const tooltipVariants = tv({
             jsxs("div", {
                 className: "flex flex-col",
                 children: [
-                    label && jsx("label", {
+                    label && jsxs("label", {
                         htmlFor: controlId,
                         className: cn(v.label(), themeSlotProps == null ? void 0 : (_themeSlotProps_label = themeSlotProps.label) == null ? void 0 : _themeSlotProps_label.className, slotProps == null ? void 0 : (_slotProps_label = slotProps.label) == null ? void 0 : _slotProps_label.className),
-                        children: renderLabelWithTooltip(label, tooltipConfig)
+                        children: [
+                            renderLabelWithTooltip(label, tooltipConfig),
+                            required && jsx("span", {
+                                "aria-hidden": "true",
+                                className: cn(v.requiredMark(), themeSlotProps == null ? void 0 : (_themeSlotProps_requiredMark = themeSlotProps.requiredMark) == null ? void 0 : _themeSlotProps_requiredMark.className, slotProps == null ? void 0 : (_slotProps_requiredMark = slotProps.requiredMark) == null ? void 0 : _slotProps_requiredMark.className),
+                                children: "*"
+                            })
+                        ]
                     }),
                     resolvedHelperText && jsx("p", {
                         className: cn(resolvedError ? v.errorText() : v.helperText(), resolvedError ? [
@@ -1540,6 +1616,9 @@ const tooltipVariants = tv({
             'data-[state=unchecked]:translate-x-0'
         ],
         label: 'select-none cursor-pointer text-neutral-900',
+        // BUG 21: `*` marker after the label, same tokens as
+        // `checkboxVariants.requiredMark` for visual parity.
+        requiredMark: 'text-danger-500 ml-0.5',
         helperText: 'text-sm text-neutral-600 mt-1',
         errorText: 'text-sm text-danger-600 mt-1'
     },
@@ -1586,19 +1665,45 @@ const tooltipVariants = tv({
  *    translate-x distance so the knob lands flush at each end.
  */ function Switch(props) {
     var _ref;
-    var _themeDefaults_defaults, _themeSlotProps_root, _slotProps_root, _themeSlotProps_control, _slotProps_control, _themeSlotProps_thumb, _slotProps_thumb, _themeSlotProps_label, _slotProps_label, _themeSlotProps_errorText, _slotProps_errorText, _themeSlotProps_helperText, _slotProps_helperText;
+    var _themeDefaults_defaults, _themeSlotProps_root, _slotProps_root, _themeSlotProps_control, _slotProps_control, _themeSlotProps_thumb, _slotProps_thumb, _themeSlotProps_label, _slotProps_label, _themeSlotProps_requiredMark, _slotProps_requiredMark, _themeSlotProps_errorText, _slotProps_errorText, _themeSlotProps_helperText, _slotProps_helperText;
     const themeDefaults = useComponentDefaults('Switch');
     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, visibleWhen, label, helperText, error, access, size, disabled, checked, defaultChecked, onCheckedChange, sx, slotProps } = merged;
+    const { name, rules, visibleWhen, label, helperText, error, access, size, disabled, required, checked, defaultChecked, onCheckedChange, sx, slotProps } = merged;
     const bridge = useContext(DashFormContext);
     const isVisible = useEngineVisibility(bridge == null ? void 0 : bridge.engine, visibleWhen);
     // Reactive snapshot — see Checkbox.tsx for the same rationale.
     const fieldMeta = useDashFieldMeta(name);
     const accessState = useAccessState(access);
     const controlId = useId();
+    // BUG 21 v2: local ref + post-mount `aria-required` setter — same
+    // pattern as Checkbox.tsx. Radix.Switch.Root reads `required` prop
+    // into context but the JSX `aria-required` attribute does not reach
+    // the browser DOM in production builds. Setting via ref is
+    // Radix-version-agnostic. See README-BUG.md § BUG 21.
+    const buttonRef = useRef(null);
+    const setControlRef = (node)=>{
+        buttonRef.current = node;
+        const regRef = registration == null ? void 0 : registration.ref;
+        if (typeof regRef === 'function') {
+            regRef(node);
+        } else if (regRef && typeof regRef === 'object') {
+            regRef.current = node;
+        }
+    };
+    useEffect(()=>{
+        const node = buttonRef.current;
+        if (!node) return;
+        if (required) {
+            node.setAttribute('aria-required', 'true');
+        } else {
+            node.removeAttribute('aria-required');
+        }
+    }, [
+        required
+    ]);
     // StrictMode-safe unregister-on-unmount
     const unregisterRef = useRef({
         bridge,
@@ -1614,6 +1719,11 @@ const tooltipVariants = tv({
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -1689,9 +1799,13 @@ const tooltipVariants = tv({
                 name: name
             }, radixStateProps, {
                 disabled: effectiveDisabled,
+                required: required,
                 onCheckedChange: handleCheckedChange,
                 onBlur: handleBlur,
-                ref: registration == null ? void 0 : registration.ref,
+                // BUG 21 v2: `aria-required` set via `setControlRef` + `useEffect`
+                // above, not via JSX prop. See Checkbox.tsx for the same pattern
+                // and the reasoning.
+                ref: setControlRef,
                 className: cn(v.control(), themeSlotProps == null ? void 0 : (_themeSlotProps_control = themeSlotProps.control) == null ? void 0 : _themeSlotProps_control.className, slotProps == null ? void 0 : (_slotProps_control = slotProps.control) == null ? void 0 : _slotProps_control.className),
                 children: jsx(RadixSwitch.Thumb, {
                     className: cn(v.thumb(), themeSlotProps == null ? void 0 : (_themeSlotProps_thumb = themeSlotProps.thumb) == null ? void 0 : _themeSlotProps_thumb.className, slotProps == null ? void 0 : (_slotProps_thumb = slotProps.thumb) == null ? void 0 : _slotProps_thumb.className)
@@ -1700,10 +1814,17 @@ const tooltipVariants = tv({
             jsxs("div", {
                 className: "flex flex-col",
                 children: [
-                    label && jsx("label", {
+                    label && jsxs("label", {
                         htmlFor: controlId,
                         className: cn(v.label(), themeSlotProps == null ? void 0 : (_themeSlotProps_label = themeSlotProps.label) == null ? void 0 : _themeSlotProps_label.className, slotProps == null ? void 0 : (_slotProps_label = slotProps.label) == null ? void 0 : _slotProps_label.className),
-                        children: renderLabelWithTooltip(label, tooltipConfig)
+                        children: [
+                            renderLabelWithTooltip(label, tooltipConfig),
+                            required && jsx("span", {
+                                "aria-hidden": "true",
+                                className: cn(v.requiredMark(), themeSlotProps == null ? void 0 : (_themeSlotProps_requiredMark = themeSlotProps.requiredMark) == null ? void 0 : _themeSlotProps_requiredMark.className, slotProps == null ? void 0 : (_slotProps_requiredMark = slotProps.requiredMark) == null ? void 0 : _slotProps_requiredMark.className),
+                                children: "*"
+                            })
+                        ]
                     }),
                     resolvedHelperText && jsx("p", {
                         className: cn(resolvedError ? v.errorText() : v.helperText(), resolvedError ? [
@@ -1754,6 +1875,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'
@@ -1879,6 +2005,11 @@ const tooltipVariants = tv({
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -1889,6 +2020,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 +2276,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 +2301,8 @@ const tooltipVariants = tv({
         "onChange",
         "onBlur",
         "value",
-        "defaultValue"
+        "defaultValue",
+        "tooltip"
     ]);
     // ───── Hooks (unconditional) ─────
     const bridge = useContext(DashFormContext);
@@ -2181,6 +2326,11 @@ const tooltipVariants = tv({
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -2436,7 +2586,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 +2613,8 @@ const tooltipVariants = tv({
         "onChange",
         "onBlur",
         "value",
-        "defaultValue"
+        "defaultValue",
+        "tooltip"
     ]);
     // ───── Hooks (unconditional) ─────
     const bridge = useContext(DashFormContext);
@@ -2498,6 +2653,11 @@ const tooltipVariants = tv({
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -2792,6 +2952,11 @@ const tooltipVariants = tv({
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -3185,14 +3350,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
@@ -3231,6 +3433,11 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -3510,7 +3717,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 +3998,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));
+                                })
+                            })
                         })
                     })
                 ]
@@ -4409,12 +4745,26 @@ function CalendarIcon$2() {
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
             });
         };
     }, []);
+    // 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;
@@ -4683,6 +5033,11 @@ function ClockIcon() {
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -5020,6 +5375,11 @@ const DATETIME_PATTERN = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})/;
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -5584,6 +5944,11 @@ function formatRange(range, locale) {
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -9728,6 +10093,11 @@ const DEFAULT_STEP = 1;
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -10249,6 +10619,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,
@@ -10264,6 +10645,11 @@ Slider.displayName = 'Slider';
         return ()=>{
             isMountedRef.current = false;
             const { bridge: cap, name: capName } = unregisterRef.current;
+            // BUG 22: only release bridge state on unmount if the form
+            // is configured to forget unmounted fields. Default `false`
+            // keeps values in RHF so <Stepper> / tab-swap patterns can
+            // read earlier answers back on later steps. See README-BUG.md § BUG 22.
+            if (!(cap == null ? void 0 : cap.shouldUnregister)) return;
             queueMicrotask(()=>{
                 var _cap_unregister;
                 if (!isMountedRef.current) cap == null ? void 0 : (_cap_unregister = cap.unregister) == null ? void 0 : _cap_unregister.call(cap, capName);
@@ -15208,10 +15594,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 +15637,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 +15673,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'