@dashforge/tw 1.6.0 → 1.7.1

package/CHANGELOG.md

@@ -12,6 +12,84 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > duplicated intentionally — no shared "lowest common denominator" headless
 > layer.
 
+## [1.7.1] — 2026-09-25
+
+Patch: closes the half of BUG 17 that never reached this package.
+
+### Fixed
+
+- **An explicit `helperText` no longer swallows the field's validation
+  message** (BUG 32). This package carries its own copy of the
+  validation resolver at
+  `src/components/_shared/resolveValidationState.ts`, and it kept the
+  inverted precedence that BUG 17 corrected on the MUI side back on
+  2026-09-15. The effect: any bridge-managed field given a constant
+  hint painted the danger state and set `aria-invalid="true"` while
+  still rendering the hint text, so the user saw a red field with no
+  stated reason. **Fourteen components route through that resolver**
+  (Autocomplete, Checkbox, DatePicker, DateRangePicker, DateTimePicker,
+  NumberField, OTPField, RadioGroup, Select, Slider, Switch, TextField,
+  Textarea, TimePicker), so a single line fixes all of them.
+  `helperText` now reads `autoMessage ?? explicitHelperText`: the
+  validation message wins while it is showing, the hint is the fallback
+  for the no-error state. The `error` boolean is unchanged — an
+  explicit prop still forces the visual.
+
+  The resolver's docstring previously advertised itself as matching the
+  MUI side "byte-for-byte", which is what let the divergence survive
+  ten days. It now carries an explicit warning that the two files are
+  hand-kept copies. New regression suite at
+  `src/components/_shared/resolveValidationState.test.ts` (7 assertions)
+  mirrors the MUI-side one, and each docstring points at the other.
+  See `README-BUG.md` § BUG 32.
+
+## [1.7.0] — 2026-09-22
+
+### Added
+
+- **`<Checkbox required>` and `<Switch required>`** — the last two
+  bridge-integrated field components in the package that did not
+  accept `required` (the other twelve — Autocomplete, DatePicker,
+  DateRangePicker, DateTimePicker, NumberField, OTPField, RadioGroup,
+  Select, Slider, TextField, Textarea, TimePicker — already did).
+  Fixes BUG 21 in `libs/dashforge/README-BUG.md`. Both components now
+  render a `*` marker at the end of the label (styled via a new
+  `requiredMark` slot in the variants recipe, colour tokens matching
+  `textField.variants.ts` `requiredMark`) and set `aria-required="true"`
+  on the underlying Radix Root button via a **ref + `useEffect`
+  post-mount DOM setter** (Radix v1.3.3's own internal
+  context-then-re-emit path for `aria-required` was verified to strip
+  the attribute in production browser builds, though jsdom did not
+  catch that; the ref-based fallback is Radix-version-agnostic). HTML5
+  `required` is still passed through to Radix so
+  `Radix.CheckboxBubbleInput` picks it up for native form validation.
+  The `requiredMark` slot accepts a `className` via `slotProps` for
+  per-instance overrides, and via `theme.components.<Name>.slotProps`
+  for design-system-wide overrides. Presentational only, per the
+  library-wide convention: form-submit enforcement still requires
+  `rules={{ required: … }}` or a resolver rule. Seven regression tests
+  in `src/components/_shared/checkboxSwitchRequired.test.tsx` pin the
+  marker, the aria-required attribute, the no-render-when-omitted
+  invariant, and the slot override plumbing.
+
+### Fixed
+
+- **14 field components now honour `bridge.shouldUnregister`** (BUG 22
+  cross-package fix). Autocomplete, Checkbox, DatePicker,
+  DateRangePicker, DateTimePicker, NumberField, OTPField, RadioGroup,
+  Select, Slider, Switch, TextField, Textarea, TimePicker — the
+  unmount cleanup that previously ran unconditionally
+  (`queueMicrotask` schedule of `bridge.unregister(name)`) now bails
+  out first with `if (!cap?.shouldUnregister) return;`. When
+  `bridge.shouldUnregister` is `false` (the new Dashforge default,
+  set in `DashFormProvider`) the field's row in `formState.values`
+  survives the unmount, which is what `<Stepper>` and tab-swap
+  patterns need. Requires `@dashforge/ui-core@≥1.2.0` (new bridge
+  field) and `@dashforge/forms@≥1.2.0` (bridge population). The
+  StrictMode-safe `queueMicrotask` + `isMountedRef` pattern is
+  preserved verbatim; the change only decides *whether* to run the
+  scheduled cleanup.
+
 ## [1.6.0] — 2026-09-15
 
 Minor release: three bug fixes (BUG 6 Dialog `actions` slot,

package/dist/index.esm.js

@@ -870,23 +870,33 @@ const tooltipVariants = tv({
 /**
  * Compute `error` + `helperText` for a bridge-managed field.
  *
- * **Renderer-agnostic** — copy of the MUI-side
- * `textField.validation.ts`. Promoted to a `_shared/` directory inside
- * `@dashforge/tw` so all form components (TextField + Checkbox +
- * Switch) reuse the same precedence logic without depending on a
+ * **Renderer-agnostic.** Mirrors the MUI-side
+ * `ui/src/components/TextField/textField.validation.ts`. Promoted to a
+ * `_shared/` directory inside `@dashforge/tw` so all 14 bridge-managed
+ * form components reuse the same precedence without depending on a
  * specific component folder.
  *
- * Precedence rules (matches MUI side byte-for-byte):
- *
- *  1. **Explicit props win.** If the user passed `error` / `helperText`
- *     explicitly, those values are used as-is.
- *  2. **Auto values are gated by interaction.** The bridge's error is
+ * ⚠️ This file is a COPY, not an import. The two sides have to be kept
+ * in step by hand, and once already were not: BUG 17 (2026-09-15)
+ * inverted the `helperText` precedence on the MUI side only, and this
+ * copy kept the broken order for ten days until BUG 32 caught it. The
+ * verification that missed it was a grep for imports of the MUI file,
+ * which by construction cannot reach a copy. **When you change the
+ * precedence here, change it there too — and vice versa.**
+ *
+ * Precedence rules:
+ *
+ *  1. **`error`: the explicit prop wins.** An author who passes `error`
+ *     is forcing the visual state, so it overrides the auto-gate.
+ *  2. **`helperText`: the validation message wins while it is showing;
+ *     the explicit prop is the fallback for the no-error state.** A
+ *     constant hint ("Unique, uppercase") must not swallow the reason a
+ *     required field was rejected — that leaves the user looking at a
+ *     red field with no explanation. See README-BUG.md § BUG 17 / § BUG 32.
+ *  3. **Auto values are gated by interaction.** The bridge's error is
  *     surfaced only when the field is `touched` OR the form has been
  *     submitted at least once (`submitCount > 0`). This prevents the
  *     "error spam while typing" anti-pattern.
- *  3. **`error === false` explicitly clears the bridge's error message
- *     text.** Useful for forcing a "valid" visual state regardless of
- *     bridge state.
  *
  * @param name         field name registered with the bridge
  * @param bridge       active `DashFormBridge` (guaranteed non-null at
@@ -899,8 +909,16 @@ const tooltipVariants = tv({
     const autoTouched = (_bridge_isTouched = bridge.isTouched(name)) != null ? _bridge_isTouched : false;
     const submitCount = (_bridge_submitCount = bridge.submitCount) != null ? _bridge_submitCount : 0;
     const allowAutoError = autoTouched || submitCount > 0;
+    // `error` still lets an explicit prop force the visual state.
     const error = explicitError != null ? explicitError : Boolean(autoErr) && allowAutoError;
-    const helperText = explicitHelperText != null ? explicitHelperText : allowAutoError ? autoErr == null ? void 0 : autoErr.message : undefined;
+    // BUG 32: the validation message wins over the explicit hint while it
+    // is showing. The previous order (`explicitHelperText ?? autoMessage`)
+    // short-circuited on the hint, so any field carrying one painted the
+    // danger state and `aria-invalid="true"` while still rendering the
+    // hint text — a red field with no stated reason. Identical inversion
+    // to the one BUG 17 landed on the MUI side.
+    const autoMessage = allowAutoError ? autoErr == null ? void 0 : autoErr.message : undefined;
+    const helperText = autoMessage != null ? autoMessage : explicitHelperText;
     return {
         error,
         helperText
@@ -1095,6 +1113,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);
@@ -1257,6 +1280,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'
     },
@@ -1365,13 +1392,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);
@@ -1381,6 +1408,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).
@@ -1398,6 +1451,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);
@@ -1486,9 +1544,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),
@@ -1505,10 +1573,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 ? [
@@ -1559,6 +1634,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'
     },
@@ -1605,19 +1683,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,
@@ -1633,6 +1737,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);
@@ -1708,9 +1817,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)
@@ -1719,10 +1832,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 ? [
@@ -1903,6 +2023,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);
@@ -2219,6 +2344,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);
@@ -2541,6 +2671,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);
@@ -2835,6 +2970,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);
@@ -3311,6 +3451,11 @@ function Autocomplete(props) {
         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);
@@ -4618,6 +4763,11 @@ 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);
@@ -4901,6 +5051,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);
@@ -5238,6 +5393,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);
@@ -5802,6 +5962,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);
@@ -9946,6 +10111,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);
@@ -10493,6 +10663,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);

package/dist/src/components/Autocomplete/Autocomplete.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Autocomplete.d.ts","sourceRoot":"","sources":["../../../../src/components/Autocomplete/Autocomplete.tsx"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,yBAAyB,CAAC;AA8FjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,IAAI,GAAG,IAAI,EACnB,IAAI,EAAE,WAAW,GAAG,IAAI,EACxB,OAAO,EAAE,WAAW,GAAG,IAAI,GAC1B,OAAO,CAGT;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAG,kBAAkB,EACvD,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,kDA6lClC"}
+{"version":3,"file":"Autocomplete.d.ts","sourceRoot":"","sources":["../../../../src/components/Autocomplete/Autocomplete.tsx"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,yBAAyB,CAAC;AA8FjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,IAAI,GAAG,IAAI,EACnB,IAAI,EAAE,WAAW,GAAG,IAAI,EACxB,OAAO,EAAE,WAAW,GAAG,IAAI,GAC1B,OAAO,CAGT;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAG,kBAAkB,EACvD,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,kDAkmClC"}

package/dist/src/components/Checkbox/Checkbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Checkbox.d.ts","sourceRoot":"","sources":["../../../../src/components/Checkbox/Checkbox.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA0DzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,kDA8M5C"}
+{"version":3,"file":"Checkbox.d.ts","sourceRoot":"","sources":["../../../../src/components/Checkbox/Checkbox.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA0DzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,kDAuQ5C"}

package/dist/src/components/Checkbox/checkbox.types.d.ts

@@ -42,6 +42,14 @@ export interface CheckboxSlotProps {
     errorText?: {
         className?: string;
     };
+    /**
+     * The `*` asterisk rendered next to the label when `required` is true.
+     * Themed by `checkboxVariants().requiredMark()`; override here to
+     * change colour / spacing. See README-BUG.md § BUG 21.
+     */
+    requiredMark?: {
+        className?: string;
+    };
 }
 /**
  * Props for the Dashforge TW `<Checkbox>` component.
@@ -85,6 +93,14 @@ export interface CheckboxProps {
     defaultChecked?: boolean;
     /** Disabled — combined with RBAC disabled via OR. */
     disabled?: boolean;
+    /**
+     * Renders a `*` asterisk next to the label and sets `aria-required="true"`
+     * on the underlying Radix control button. This is the visual + a11y marker
+     * for a mandatory consent box (privacy policy, terms of service).
+     * Presentational only: submit-time enforcement still requires
+     * `rules={{ required: … }}` or a resolver rule. See README-BUG.md § BUG 21.
+     */
+    required?: boolean;
     /**
      * Forces helper text below the control. When the bridge surfaces an
      * error and `helperText` is undefined, the bridge's error message

package/dist/src/components/Checkbox/checkbox.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkbox.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Checkbox/checkbox.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;AAElE,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAU,mBAAmB;QAC3B,QAAQ,CAAC,EAAE;YACT,QAAQ,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG;gBAAE,OAAO,CAAC,EAAE,gBAAgB,CAAA;aAAE,CAAC;YAC1E,SAAS,CAAC,EAAE,iBAAiB,CAAC;SAC/B,CAAC;KACH;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,UAAU,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEhC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IAEb,8EAA8E;IAC9E,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAE3B,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAE1C,0CAA0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,wBAAwB;IACxB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B,0EAA0E;IAC1E,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,oDAAoD;IACpD,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAE9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9C"}
+{"version":3,"file":"checkbox.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Checkbox/checkbox.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;AAElE,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAU,mBAAmB;QAC3B,QAAQ,CAAC,EAAE;YACT,QAAQ,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG;gBAAE,OAAO,CAAC,EAAE,gBAAgB,CAAA;aAAE,CAAC;YAC1E,SAAS,CAAC,EAAE,iBAAiB,CAAC;SAC/B,CAAC;KACH;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,UAAU,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC;;;;OAIG;IACH,YAAY,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAEhC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IAEb,8EAA8E;IAC9E,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAE3B,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAE1C,0CAA0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,wBAAwB;IACxB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B,0EAA0E;IAC1E,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,oDAAoD;IACpD,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAE9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9C"}

package/dist/src/components/Checkbox/checkbox.variants.d.ts

@@ -42,6 +42,7 @@ export declare const checkboxVariants: import("tailwind-variants").TVReturnType<
     control: string[];
     indicator: string;
     label: string;
+    requiredMark: string;
     helperText: string;
     errorText: string;
 }, undefined, {
@@ -72,6 +73,7 @@ export declare const checkboxVariants: import("tailwind-variants").TVReturnType<
     control: string[];
     indicator: string;
     label: string;
+    requiredMark: string;
     helperText: string;
     errorText: string;
 }, import("tailwind-variants").TVReturnType<{
@@ -102,6 +104,7 @@ export declare const checkboxVariants: import("tailwind-variants").TVReturnType<
     control: string[];
     indicator: string;
     label: string;
+    requiredMark: string;
     helperText: string;
     errorText: string;
 }, undefined, unknown, unknown, undefined>>;

package/dist/src/components/Checkbox/checkbox.variants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkbox.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/Checkbox/checkbox.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAqD3B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"checkbox.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/Checkbox/checkbox.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAyD3B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/dist/src/components/DatePicker/DatePicker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DatePicker.d.ts","sourceRoot":"","sources":["../../../../src/components/DatePicker/DatePicker.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAqD7D;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,kDAsPjD"}
+{"version":3,"file":"DatePicker.d.ts","sourceRoot":"","sources":["../../../../src/components/DatePicker/DatePicker.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAqD7D;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,kDA2PjD"}

package/dist/src/components/DateRangePicker/DateRangePicker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DateRangePicker.d.ts","sourceRoot":"","sources":["../../../../src/components/DateRangePicker/DateRangePicker.tsx"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAoQvE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,oBAAoB,kDA4N3D"}
+{"version":3,"file":"DateRangePicker.d.ts","sourceRoot":"","sources":["../../../../src/components/DateRangePicker/DateRangePicker.tsx"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAoQvE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,oBAAoB,kDAiO3D"}

package/dist/src/components/DateTimePicker/DateTimePicker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DateTimePicker.d.ts","sourceRoot":"","sources":["../../../../src/components/DateTimePicker/DateTimePicker.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AA8ErE;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,kDAyPzD"}
+{"version":3,"file":"DateTimePicker.d.ts","sourceRoot":"","sources":["../../../../src/components/DateTimePicker/DateTimePicker.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AA8ErE;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,kDA8PzD"}

package/dist/src/components/NumberField/NumberField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NumberField.d.ts","sourceRoot":"","sources":["../../../../src/components/NumberField/NumberField.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAuC/D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,kDAgRlD"}
+{"version":3,"file":"NumberField.d.ts","sourceRoot":"","sources":["../../../../src/components/NumberField/NumberField.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAuC/D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,kDAqRlD"}

package/dist/src/components/OTPField/OTPField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OTPField.d.ts","sourceRoot":"","sources":["../../../../src/components/OTPField/OTPField.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAgBvE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,kDAmN5C"}
+{"version":3,"file":"OTPField.d.ts","sourceRoot":"","sources":["../../../../src/components/OTPField/OTPField.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAgBvE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,kDAwN5C"}

package/dist/src/components/RadioGroup/RadioGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RadioGroup.d.ts","sourceRoot":"","sources":["../../../../src/components/RadioGroup/RadioGroup.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,kDA4QhD"}
+{"version":3,"file":"RadioGroup.d.ts","sourceRoot":"","sources":["../../../../src/components/RadioGroup/RadioGroup.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,kDAiRhD"}

package/dist/src/components/Select/Select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Select.d.ts","sourceRoot":"","sources":["../../../../src/components/Select/Select.tsx"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,YAAY,EAElB,MAAM,OAAO,CAAC;AAgBf,OAAO,KAAK,EAIV,WAAW,EACX,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAsmB3B;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,EAA8B,CAAC,CAAC,SAAS,WAAW,GAAG,MAAM,EAC9E,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAA;CAAE,KAC3D,YAAY,GAAG,IAAI,CAAC"}
+{"version":3,"file":"Select.d.ts","sourceRoot":"","sources":["../../../../src/components/Select/Select.tsx"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,YAAY,EAElB,MAAM,OAAO,CAAC;AAgBf,OAAO,KAAK,EAIV,WAAW,EACX,WAAW,EACZ,MAAM,mBAAmB,CAAC;AA2mB3B;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,EAA8B,CAAC,CAAC,SAAS,WAAW,GAAG,MAAM,EAC9E,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAA;CAAE,KAC3D,YAAY,GAAG,IAAI,CAAC"}

package/dist/src/components/Slider/Slider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Slider.d.ts","sourceRoot":"","sources":["../../../../src/components/Slider/Slider.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAEV,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAgE3B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,yGAyXjB,CAAC;AAOH,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"Slider.d.ts","sourceRoot":"","sources":["../../../../src/components/Slider/Slider.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAEV,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAgE3B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,yGA8XjB,CAAC;AAOH,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/src/components/Switch/Switch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Switch.d.ts","sourceRoot":"","sources":["../../../../src/components/Switch/Switch.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,kDAsJxC"}
+{"version":3,"file":"Switch.d.ts","sourceRoot":"","sources":["../../../../src/components/Switch/Switch.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,kDAyMxC"}

package/dist/src/components/Switch/switch.types.d.ts

@@ -37,6 +37,14 @@ export interface SwitchSlotProps {
     errorText?: {
         className?: string;
     };
+    /**
+     * The `*` asterisk rendered next to the label when `required` is true.
+     * Themed by `switchVariants().requiredMark()`; override here to change
+     * colour / spacing. See README-BUG.md § BUG 21.
+     */
+    requiredMark?: {
+        className?: string;
+    };
 }
 /**
  * Props for the Dashforge TW `<Switch>` component.
@@ -80,6 +88,13 @@ export interface SwitchProps {
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Renders a `*` asterisk next to the label and sets `aria-required="true"`
+     * on the underlying Radix control button. Presentational only: submit-time
+     * enforcement still requires `rules={{ required: … }}` or a resolver rule.
+     * See README-BUG.md § BUG 21.
+     */
+    required?: boolean;
     /** Helper line below the control. Auto-replaced by bridge error when invalid. */
     helperText?: ReactNode;
     /**

package/dist/src/components/Switch/switch.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"switch.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Switch/switch.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AAE9D,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAU,mBAAmB;QAC3B,MAAM,CAAC,EAAE;YACP,QAAQ,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG;gBAAE,OAAO,CAAC,EAAE,gBAAgB,CAAA;aAAE,CAAC;YACxE,SAAS,CAAC,EAAE,eAAe,CAAC;SAC7B,CAAC;KACH;CACF;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,UAAU,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAE9B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IAEb,sFAAsF;IACtF,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAE3B,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAE1C,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,iFAAiF;IACjF,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,uFAAuF;IACvF,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B,iFAAiF;IACjF,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,kDAAkD;IAClD,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B,gFAAgF;IAChF,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9C"}
+{"version":3,"file":"switch.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Switch/switch.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AAE9D,OAAO,QAAQ,sBAAsB,CAAC;IACpC,UAAU,mBAAmB;QAC3B,MAAM,CAAC,EAAE;YACP,QAAQ,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG;gBAAE,OAAO,CAAC,EAAE,gBAAgB,CAAA;aAAE,CAAC;YACxE,SAAS,CAAC,EAAE,eAAe,CAAC;SAC7B,CAAC;KACH;CACF;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,UAAU,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,SAAS,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC;;;;OAIG;IACH,YAAY,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAE9B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IAEb,sFAAsF;IACtF,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAE3B,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAE1C,gCAAgC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,iFAAiF;IACjF,UAAU,CAAC,EAAE,SAAS,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,uFAAuF;IACvF,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B,iFAAiF;IACjF,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,kDAAkD;IAClD,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B,gFAAgF;IAChF,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9C"}

package/dist/src/components/Switch/switch.variants.d.ts

@@ -38,6 +38,7 @@ export declare const switchVariants: import("tailwind-variants").TVReturnType<{
     control: string[];
     thumb: string[];
     label: string;
+    requiredMark: string;
     helperText: string;
     errorText: string;
 }, undefined, {
@@ -68,6 +69,7 @@ export declare const switchVariants: import("tailwind-variants").TVReturnType<{
     control: string[];
     thumb: string[];
     label: string;
+    requiredMark: string;
     helperText: string;
     errorText: string;
 }, import("tailwind-variants").TVReturnType<{
@@ -98,6 +100,7 @@ export declare const switchVariants: import("tailwind-variants").TVReturnType<{
     control: string[];
     thumb: string[];
     label: string;
+    requiredMark: string;
     helperText: string;
     errorText: string;
 }, undefined, unknown, unknown, undefined>>;

package/dist/src/components/Switch/switch.variants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"switch.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/Switch/switch.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAsDzB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,YAAY,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"switch.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/Switch/switch.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAyDzB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,YAAY,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/src/components/TextField/TextField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextField.d.ts","sourceRoot":"","sources":["../../../../src/components/TextField/TextField.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,kDAqO9C"}
+{"version":3,"file":"TextField.d.ts","sourceRoot":"","sources":["../../../../src/components/TextField/TextField.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,kDA0O9C"}

package/dist/src/components/Textarea/Textarea.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Textarea.d.ts","sourceRoot":"","sources":["../../../../src/components/Textarea/Textarea.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,kDAoL5C"}
+{"version":3,"file":"Textarea.d.ts","sourceRoot":"","sources":["../../../../src/components/Textarea/Textarea.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,kDAyL5C"}

package/dist/src/components/TimePicker/TimePicker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TimePicker.d.ts","sourceRoot":"","sources":["../../../../src/components/TimePicker/TimePicker.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAkB7D;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,kDAgPjD"}
+{"version":3,"file":"TimePicker.d.ts","sourceRoot":"","sources":["../../../../src/components/TimePicker/TimePicker.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAkB7D;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,kDAqPjD"}

package/dist/src/components/_shared/resolveValidationState.d.ts

@@ -14,23 +14,33 @@ export interface ValidationState {
 /**
  * Compute `error` + `helperText` for a bridge-managed field.
  *
- * **Renderer-agnostic** — copy of the MUI-side
- * `textField.validation.ts`. Promoted to a `_shared/` directory inside
- * `@dashforge/tw` so all form components (TextField + Checkbox +
- * Switch) reuse the same precedence logic without depending on a
+ * **Renderer-agnostic.** Mirrors the MUI-side
+ * `ui/src/components/TextField/textField.validation.ts`. Promoted to a
+ * `_shared/` directory inside `@dashforge/tw` so all 14 bridge-managed
+ * form components reuse the same precedence without depending on a
  * specific component folder.
  *
- * Precedence rules (matches MUI side byte-for-byte):
+ * ⚠️ This file is a COPY, not an import. The two sides have to be kept
+ * in step by hand, and once already were not: BUG 17 (2026-09-15)
+ * inverted the `helperText` precedence on the MUI side only, and this
+ * copy kept the broken order for ten days until BUG 32 caught it. The
+ * verification that missed it was a grep for imports of the MUI file,
+ * which by construction cannot reach a copy. **When you change the
+ * precedence here, change it there too — and vice versa.**
  *
- *  1. **Explicit props win.** If the user passed `error` / `helperText`
- *     explicitly, those values are used as-is.
- *  2. **Auto values are gated by interaction.** The bridge's error is
+ * Precedence rules:
+ *
+ *  1. **`error`: the explicit prop wins.** An author who passes `error`
+ *     is forcing the visual state, so it overrides the auto-gate.
+ *  2. **`helperText`: the validation message wins while it is showing;
+ *     the explicit prop is the fallback for the no-error state.** A
+ *     constant hint ("Unique, uppercase") must not swallow the reason a
+ *     required field was rejected — that leaves the user looking at a
+ *     red field with no explanation. See README-BUG.md § BUG 17 / § BUG 32.
+ *  3. **Auto values are gated by interaction.** The bridge's error is
  *     surfaced only when the field is `touched` OR the form has been
  *     submitted at least once (`submitCount > 0`). This prevents the
  *     "error spam while typing" anti-pattern.
- *  3. **`error === false` explicitly clears the bridge's error message
- *     text.** Useful for forcing a "valid" visual state regardless of
- *     bridge state.
  *
  * @param name         field name registered with the bridge
  * @param bridge       active `DashFormBridge` (guaranteed non-null at

package/dist/src/components/_shared/resolveValidationState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveValidationState.d.ts","sourceRoot":"","sources":["../../../../src/components/_shared/resolveValidationState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,EACtB,aAAa,EAAE,OAAO,GAAG,SAAS,EAClC,kBAAkB,EAAE,SAAS,GAAG,SAAS,GACxC,eAAe,CAYjB"}
+{"version":3,"file":"resolveValidationState.d.ts","sourceRoot":"","sources":["../../../../src/components/_shared/resolveValidationState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,EACtB,aAAa,EAAE,OAAO,GAAG,SAAS,EAClC,kBAAkB,EAAE,SAAS,GAAG,SAAS,GACxC,eAAe,CAoBjB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dashforge/tw",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.esm.js",
@@ -35,8 +35,8 @@
     "tailwind-merge": "^3.0.0",
     "tailwind-variants": "^3.1.1",
     "@dashforge/calendar-core": "1.0.0",
-    "@dashforge/ui-core": "1.1.0",
-    "@dashforge/forms": "1.1.0",
+    "@dashforge/forms": "1.2.0",
+    "@dashforge/ui-core": "1.2.0",
     "@dashforge/rbac": "1.0.0"
   },
   "peerDependencies": {