@trackunit/react-form-components 2.6.20 → 2.6.22

package/index.cjs.js

@@ -4880,19 +4880,38 @@ const FormFieldSelectAdapter = ({ className, "data-testid": dataTestId, helpText
     // eslint-disable-next-line @trackunit/no-typescript-assertion, @typescript-eslint/no-non-null-assertion
     react.useImperativeHandle(ref, () => innerRef.current, []);
     // Bridges a react-select pick back to the hidden native <select> so `register`/native form
-    // consumers see a real change event. It must fire only when the value actually changes: seeding
-    // the ref with the initial value means mounting with a value is not reported as a change, which
-    // would otherwise write to the consumer's form and mark it dirty with no user interaction.
+    // consumers see a real change event.
+    //
+    // Only picks are bridged. A value arriving from the `value` prop is something the parent already
+    // holds, so reporting it back would be an echo - and through `register(...).onChange` that echo
+    // is indistinguishable from typing, marking the consumer's form dirty with no user interaction.
     const lastNotifiedValueRef = react.useRef(innerValue);
+    // A box, not a bare value: `null` then unambiguously means "no pick pending", so the origin gate
+    // below cannot be satisfied by a parent-driven change that merely matches the ref's empty state.
+    const pendingUserPickRef = react.useRef(null);
     react.useEffect(() => {
-        if (innerValue === undefined || lastNotifiedValueRef.current === innerValue) {
+        if (lastNotifiedValueRef.current === innerValue) {
             return;
         }
         lastNotifiedValueRef.current = innerValue;
-        const event = new Event("change");
+        // Keep the hidden select in sync whatever the origin - this is state, not notification.
         if (innerValue === "" && innerRef.current) {
             innerRef.current.value = ""; // Set the desired option value
         }
+        // Keyed to the value the pick expected, not a boolean: react-select reports a re-pick of the
+        // current option, which leaves `innerValue` untouched and so never runs this effect. A boolean
+        // would still be set when the parent's next value arrives, and that value would be reported
+        // back as a user edit.
+        const pendingUserPick = pendingUserPickRef.current;
+        pendingUserPickRef.current = null;
+        const isUserChange = pendingUserPick !== null && pendingUserPick.value === innerValue;
+        // No `undefined` guard needed: a pick is always a string or number (react-select's clear maps
+        // to ""), so matching one narrows `innerValue` away from `undefined`. Only the parent can put
+        // `undefined` there, and the gate above already rejects parent-driven values.
+        if (!isUserChange) {
+            return;
+        }
+        const event = new Event("change");
         innerRef.current?.dispatchEvent(event);
         onChangeRef.current?.(event);
     }, [innerValue]);
@@ -4931,7 +4950,9 @@ const FormFieldSelectAdapter = ({ className, "data-testid": dataTestId, helpText
                     // If theres no value, set the inner value to an empty string
                     // A native select can not have a null value
                     // So even if react-select sends a null value, we need to convert it to an empty string
-                    setInnerValue(!e ? "" : e.value);
+                    const nextValue = !e ? "" : e.value;
+                    pendingUserPickRef.current = { value: nextValue };
+                    setInnerValue(nextValue);
                 },
                 "data-testid": dataTestId,
                 value: selectedOption,

package/index.esm.js

@@ -4879,19 +4879,38 @@ const FormFieldSelectAdapter = ({ className, "data-testid": dataTestId, helpText
     // eslint-disable-next-line @trackunit/no-typescript-assertion, @typescript-eslint/no-non-null-assertion
     useImperativeHandle(ref, () => innerRef.current, []);
     // Bridges a react-select pick back to the hidden native <select> so `register`/native form
-    // consumers see a real change event. It must fire only when the value actually changes: seeding
-    // the ref with the initial value means mounting with a value is not reported as a change, which
-    // would otherwise write to the consumer's form and mark it dirty with no user interaction.
+    // consumers see a real change event.
+    //
+    // Only picks are bridged. A value arriving from the `value` prop is something the parent already
+    // holds, so reporting it back would be an echo - and through `register(...).onChange` that echo
+    // is indistinguishable from typing, marking the consumer's form dirty with no user interaction.
     const lastNotifiedValueRef = useRef(innerValue);
+    // A box, not a bare value: `null` then unambiguously means "no pick pending", so the origin gate
+    // below cannot be satisfied by a parent-driven change that merely matches the ref's empty state.
+    const pendingUserPickRef = useRef(null);
     useEffect(() => {
-        if (innerValue === undefined || lastNotifiedValueRef.current === innerValue) {
+        if (lastNotifiedValueRef.current === innerValue) {
             return;
         }
         lastNotifiedValueRef.current = innerValue;
-        const event = new Event("change");
+        // Keep the hidden select in sync whatever the origin - this is state, not notification.
         if (innerValue === "" && innerRef.current) {
             innerRef.current.value = ""; // Set the desired option value
         }
+        // Keyed to the value the pick expected, not a boolean: react-select reports a re-pick of the
+        // current option, which leaves `innerValue` untouched and so never runs this effect. A boolean
+        // would still be set when the parent's next value arrives, and that value would be reported
+        // back as a user edit.
+        const pendingUserPick = pendingUserPickRef.current;
+        pendingUserPickRef.current = null;
+        const isUserChange = pendingUserPick !== null && pendingUserPick.value === innerValue;
+        // No `undefined` guard needed: a pick is always a string or number (react-select's clear maps
+        // to ""), so matching one narrows `innerValue` away from `undefined`. Only the parent can put
+        // `undefined` there, and the gate above already rejects parent-driven values.
+        if (!isUserChange) {
+            return;
+        }
+        const event = new Event("change");
         innerRef.current?.dispatchEvent(event);
         onChangeRef.current?.(event);
     }, [innerValue]);
@@ -4930,7 +4949,9 @@ const FormFieldSelectAdapter = ({ className, "data-testid": dataTestId, helpText
                     // If theres no value, set the inner value to an empty string
                     // A native select can not have a null value
                     // So even if react-select sends a null value, we need to convert it to an empty string
-                    setInnerValue(!e ? "" : e.value);
+                    const nextValue = !e ? "" : e.value;
+                    pendingUserPickRef.current = { value: nextValue };
+                    setInnerValue(nextValue);
                 },
                 "data-testid": dataTestId,
                 value: selectedOption,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-form-components",
-  "version": "2.6.20",
+  "version": "2.6.22",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -16,11 +16,11 @@
     "zod": "^3.25.76",
     "tailwind-merge": "^2.0.0",
     "@trackunit/css-class-variance-utilities": "1.14.19",
-    "@trackunit/react-components": "2.10.14",
+    "@trackunit/react-components": "2.10.15",
     "@trackunit/ui-icons": "1.14.18",
     "@trackunit/shared-utils": "1.16.22",
     "@trackunit/ui-design-tokens": "1.15.9",
-    "@trackunit/i18n-library-translation": "2.4.20",
+    "@trackunit/i18n-library-translation": "2.4.21",
     "string-ts": "^2.0.0",
     "es-toolkit": "^1.39.10"
   },

package/src/components/SelectField/FormFieldSelectAdapter.d.ts

@@ -32,6 +32,11 @@ export interface SelectFieldProps<TOption extends BaseOptionType = BaseOptionTyp
     /**
      * The onChange handler for the SelectField.
      *
+     * Called when the user picks a different option. It is not called when the `value` prop changes,
+     * since that value is one the parent already holds, and not when the user re-picks the option that
+     * is already selected. It is also forwarded to the hidden native `<select>`, so a change event
+     * dispatched on that node invokes it too.
+     *
      * @important
      */
     onChange?: (event: {