@dashforge/tw 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -12,6 +12,37 @@ 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

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

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.7.0",
+  "version": "1.7.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.esm.js",
@@ -35,9 +35,9 @@
     "tailwind-merge": "^3.0.0",
     "tailwind-variants": "^3.1.1",
     "@dashforge/calendar-core": "1.0.0",
-    "@dashforge/rbac": "1.0.0",
     "@dashforge/forms": "1.2.0",
-    "@dashforge/ui-core": "1.2.0"
+    "@dashforge/ui-core": "1.2.0",
+    "@dashforge/rbac": "1.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",