@fuf-stack/uniform 1.6.4 → 1.7.0

package/dist/hooks/useInputValueTransform/index.d.ts

@@ -1,20 +1,20 @@
-interface InputValueTransform {
-    /** Transforms the form value to display value (e.g., 1000 → "$1,000") */
-    toDisplayValue: (value: string | number) => string | number;
-    /** Transforms the display value to form value (e.g., "$1,000" → 1000) */
-    toFormValue: (value: string) => string | number;
+interface InputValueTransform<TDisplay = unknown> {
+    /** Transforms the form value to display value (e.g., 1000 → "$1,000" or 'a' → ['a']) */
+    toDisplayValue: (value: unknown) => TDisplay;
+    /** Transforms the display value to form value (e.g., "$1,000" → 1000 or ['a'] → 'a') */
+    toFormValue: (value: TDisplay) => unknown;
 }
-interface UseInputValueTransformOptions {
+interface UseInputValueTransformOptions<TDisplay = unknown> {
     /** Input type for special number handling */
     type?: 'text' | 'number' | 'password';
     /** Value transformation functions */
-    transform?: InputValueTransform;
+    transform?: InputValueTransform<TDisplay>;
 }
-interface UseInputValueTransformReturn {
+interface UseInputValueTransformReturn<TDisplay = unknown> {
     /** Converts any form value to display value */
-    toDisplayValue: (formValue: string | number) => string | number;
+    toDisplayValue: (formValue: unknown) => TDisplay;
     /** Converts any display value to form value */
-    toFormValue: (displayValue: string | number) => string | number;
+    toFormValue: (displayValue: TDisplay) => unknown;
 }
 /**
  * Custom hook providing utility functions for value transformations between display and form values.
@@ -24,9 +24,11 @@ interface UseInputValueTransformReturn {
  * - Number inputs with special handling
  * - Date formatting (MM/DD/YYYY display vs ISO date stored)
  * - Phone number formatting ((555) 123-4567 display vs 5551234567 stored)
+ * - Array/Object transformations (single value ↔ array, nested structures)
  *
  * **Key Features:**
  * - Pure conversion functions (no state)
+ * - Generic support for any data type (strings, numbers, arrays, objects)
  * - Special number input handling (empty string preservation)
  * - Bidirectional value transformations
  * - Memoized functions for performance
@@ -38,8 +40,8 @@ interface UseInputValueTransformReturn {
  * ```tsx
  * // Currency formatting
  * const currencyTransform = {
- *   displayValue: (val) => val ? `$${Number(val).toLocaleString()}` : '',
- *   formValue: (val) => parseFloat(val.replace(/[$,]/g, '')) || 0
+ *   toDisplayValue: (val) => val ? `$${Number(val).toLocaleString()}` : '',
+ *   toFormValue: (val) => parseFloat(val.replace(/[$,]/g, '')) || 0
  * };
  *
  * const { toDisplayValue, toFormValue } = useInputValueTransform({
@@ -63,6 +65,22 @@ interface UseInputValueTransformReturn {
  *
  * @example
  * ```tsx
+ * // Array to single value (for single checkbox)
+ * const singleValueTransform = {
+ *   toDisplayValue: (val: string[]) => val?.[0] || '',
+ *   toFormValue: (val: string) => val ? [val] : []
+ * };
+ *
+ * const { toDisplayValue, toFormValue } = useInputValueTransform({
+ *   transform: singleValueTransform
+ * });
+ *
+ * const displayVal = toDisplayValue(['option1']); // "option1"
+ * const formVal = toFormValue("option2"); // ["option2"]
+ * ```
+ *
+ * @example
+ * ```tsx
  * // Integration with debouncing
  * const MyInput = ({ field, transform }) => {
  *   const transform = useInputValueTransform({ transform });
@@ -79,6 +97,6 @@ interface UseInputValueTransformReturn {
  * };
  * ```
  */
-declare const useInputValueTransform: ({ type, transform, }: UseInputValueTransformOptions) => UseInputValueTransformReturn;
+declare const useInputValueTransform: <TDisplay = unknown>({ type, transform, }: UseInputValueTransformOptions<TDisplay>) => UseInputValueTransformReturn<TDisplay>;
 
 export { type InputValueTransform, type UseInputValueTransformOptions, type UseInputValueTransformReturn, useInputValueTransform };

package/dist/hooks/useInputValueTransform/index.js

@@ -1,6 +1,6 @@
 import {
   useInputValueTransform
-} from "../../chunk-7KLFK2IT.js";
+} from "../../chunk-CNTOODUQ.js";
 import "../../chunk-K2V4ULA2.js";
 export {
   useInputValueTransform

package/dist/hooks/useUniformField/index.cjs

@@ -1,14 +1,16 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkSOQ6GCN3cjs = require('../../chunk-SOQ6GCN3.cjs');
+var _chunkOQUTHTOKcjs = require('../../chunk-OQUTHTOK.cjs');
+require('../../chunk-OE5BOGGX.cjs');
 require('../../chunk-NHEZXA4H.cjs');
-require('../../chunk-JMFDNTVC.cjs');
+require('../../chunk-7KEUEGRC.cjs');
 require('../../chunk-PCTYJUY7.cjs');
-require('../../chunk-OE5BOGGX.cjs');
-require('../../chunk-42NCLEX4.cjs');
+require('../../chunk-56TQOKG7.cjs');
+require('../../chunk-6LQ2O6SC.cjs');
+require('../../chunk-4L3JXJ62.cjs');
 require('../../chunk-Z353BLWI.cjs');
 require('../../chunk-555JRYCS.cjs');
 
 
-exports.useUniformField = _chunkSOQ6GCN3cjs.useUniformField;
+exports.useUniformField = _chunkOQUTHTOKcjs.useUniformField;
 //# sourceMappingURL=index.cjs.map

package/dist/hooks/useUniformField/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useUniformField/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,4DAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC;AACE;AACF,4DAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useUniformField/index.cjs"}
+{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useUniformField/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,4DAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC;AACE;AACF,4DAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useUniformField/index.cjs"}

package/dist/hooks/useUniformField/index.d.cts

@@ -1,12 +1,13 @@
 import { ReactNode } from 'react';
 import { FieldValues, Path, FieldError } from 'react-hook-form';
+import { InputValueTransform } from '../useInputValueTransform/index.cjs';
 import { useController } from '../useController/index.cjs';
 import { useFormContext } from '../useFormContext/index.cjs';
 import { useInput } from '@heroui/input';
 import '@fuf-stack/veto';
-import '../../FormContext-LRho0tno.cjs';
+import '../../FormContext-9Firwt4k.cjs';
 
-interface UseUniformFieldParams<TFieldValues extends FieldValues = FieldValues> {
+interface UseUniformFieldParams<TFieldValues extends FieldValues = FieldValues, TDisplay = unknown> {
     /** Form field name */
     name: Path<TFieldValues> & string;
     /** Disable the field */
@@ -15,6 +16,10 @@ interface UseUniformFieldParams<TFieldValues extends FieldValues = FieldValues>
     testId?: string;
     /** Optional label content; pass false to suppress label entirely */
     label?: ReactNode | false;
+    /** Input type for special number handling */
+    type?: 'text' | 'number' | 'password';
+    /** Optional value transformation between form and display values */
+    transform?: InputValueTransform<TDisplay>;
 }
 interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues> {
     /** react-hook-form control instance for advanced integrations */
@@ -29,7 +34,7 @@ interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues>
     error: FieldError[] | undefined;
     /** Pre-built errorMessage node to plug into components */
     errorMessage: ReactNode | null;
-    /** RHF controller field with nullish conversions applied */
+    /** RHF controller field with transformed value/onChange (use this for simple components) */
     field: ReturnType<typeof useController<TFieldValues>>['field'];
     /** Helper to spread standardized error message props to underlying components */
     getErrorMessageProps: ReturnType<typeof useInput>['getErrorMessageProps'];
@@ -45,7 +50,7 @@ interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues>
     label: ReactNode | null;
     /** onBlur handler from controller */
     onBlur: ReturnType<typeof useController<TFieldValues>>['field']['onBlur'];
-    /** onChange handler from controller (with nullish handling) */
+    /** onChange handler from controller (with transform applied) */
     onChange: ReturnType<typeof useController<TFieldValues>>['field']['onChange'];
     /** Ref to forward to underlying control */
     ref: ReturnType<typeof useController<TFieldValues>>['field']['ref'];
@@ -62,6 +67,12 @@ interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues>
  * Provides:
  * - Enhanced form context (validation-aware state, `testId`, value transforms)
  * - Controller field with nullish conversion handling
+ * - Value transformation via `transform` prop:
+ *   • Allows disentangled display and form values (e.g., string ↔ object, boolean ↔ array)
+ *   • Automatically applies `toDisplayValue` to field value for components
+ *   • Automatically applies `toFormValue` to display value when onChange is called
+ *   • Works with `type` prop for automatic number/string conversion
+ *   • Examples: storing objects while displaying strings, storing booleans as arrays, enriching values with metadata
  * - Debounced `invalid` state with smart timing:
  *   • `true` (field becomes invalid): applies immediately so errors show right away
  *   • `false` (field becomes valid): delayed 200ms to allow smooth exit animations
@@ -78,6 +89,6 @@ interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues>
  * - Presentation helpers: `getLabelProps`, `getErrorMessageProps`,
  *   `getHelperWrapperProps` for consistent wiring to underlying UI components
  */
-declare function useUniformField<TFieldValues extends FieldValues = FieldValues>(params: UseUniformFieldParams<TFieldValues>): UseUniformFieldReturn<TFieldValues>;
+declare function useUniformField<TFieldValues extends FieldValues = FieldValues, TDisplay = unknown>(params: UseUniformFieldParams<TFieldValues, TDisplay>): UseUniformFieldReturn<TFieldValues>;
 
 export { type UseUniformFieldParams, type UseUniformFieldReturn, useUniformField };

package/dist/hooks/useUniformField/index.d.ts

@@ -1,12 +1,13 @@
 import { ReactNode } from 'react';
 import { FieldValues, Path, FieldError } from 'react-hook-form';
+import { InputValueTransform } from '../useInputValueTransform/index.js';
 import { useController } from '../useController/index.js';
 import { useFormContext } from '../useFormContext/index.js';
 import { useInput } from '@heroui/input';
 import '@fuf-stack/veto';
-import '../../FormContext-LRho0tno.js';
+import '../../FormContext-9Firwt4k.js';
 
-interface UseUniformFieldParams<TFieldValues extends FieldValues = FieldValues> {
+interface UseUniformFieldParams<TFieldValues extends FieldValues = FieldValues, TDisplay = unknown> {
     /** Form field name */
     name: Path<TFieldValues> & string;
     /** Disable the field */
@@ -15,6 +16,10 @@ interface UseUniformFieldParams<TFieldValues extends FieldValues = FieldValues>
     testId?: string;
     /** Optional label content; pass false to suppress label entirely */
     label?: ReactNode | false;
+    /** Input type for special number handling */
+    type?: 'text' | 'number' | 'password';
+    /** Optional value transformation between form and display values */
+    transform?: InputValueTransform<TDisplay>;
 }
 interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues> {
     /** react-hook-form control instance for advanced integrations */
@@ -29,7 +34,7 @@ interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues>
     error: FieldError[] | undefined;
     /** Pre-built errorMessage node to plug into components */
     errorMessage: ReactNode | null;
-    /** RHF controller field with nullish conversions applied */
+    /** RHF controller field with transformed value/onChange (use this for simple components) */
     field: ReturnType<typeof useController<TFieldValues>>['field'];
     /** Helper to spread standardized error message props to underlying components */
     getErrorMessageProps: ReturnType<typeof useInput>['getErrorMessageProps'];
@@ -45,7 +50,7 @@ interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues>
     label: ReactNode | null;
     /** onBlur handler from controller */
     onBlur: ReturnType<typeof useController<TFieldValues>>['field']['onBlur'];
-    /** onChange handler from controller (with nullish handling) */
+    /** onChange handler from controller (with transform applied) */
     onChange: ReturnType<typeof useController<TFieldValues>>['field']['onChange'];
     /** Ref to forward to underlying control */
     ref: ReturnType<typeof useController<TFieldValues>>['field']['ref'];
@@ -62,6 +67,12 @@ interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues>
  * Provides:
  * - Enhanced form context (validation-aware state, `testId`, value transforms)
  * - Controller field with nullish conversion handling
+ * - Value transformation via `transform` prop:
+ *   • Allows disentangled display and form values (e.g., string ↔ object, boolean ↔ array)
+ *   • Automatically applies `toDisplayValue` to field value for components
+ *   • Automatically applies `toFormValue` to display value when onChange is called
+ *   • Works with `type` prop for automatic number/string conversion
+ *   • Examples: storing objects while displaying strings, storing booleans as arrays, enriching values with metadata
  * - Debounced `invalid` state with smart timing:
  *   • `true` (field becomes invalid): applies immediately so errors show right away
  *   • `false` (field becomes valid): delayed 200ms to allow smooth exit animations
@@ -78,6 +89,6 @@ interface UseUniformFieldReturn<TFieldValues extends FieldValues = FieldValues>
  * - Presentation helpers: `getLabelProps`, `getErrorMessageProps`,
  *   `getHelperWrapperProps` for consistent wiring to underlying UI components
  */
-declare function useUniformField<TFieldValues extends FieldValues = FieldValues>(params: UseUniformFieldParams<TFieldValues>): UseUniformFieldReturn<TFieldValues>;
+declare function useUniformField<TFieldValues extends FieldValues = FieldValues, TDisplay = unknown>(params: UseUniformFieldParams<TFieldValues, TDisplay>): UseUniformFieldReturn<TFieldValues>;
 
 export { type UseUniformFieldParams, type UseUniformFieldReturn, useUniformField };

package/dist/hooks/useUniformField/index.js

@@ -1,11 +1,13 @@
 import {
   useUniformField
-} from "../../chunk-D3JYMGTB.js";
+} from "../../chunk-EGFB5WEK.js";
+import "../../chunk-NTDKZW4E.js";
 import "../../chunk-ELYGQTXB.js";
-import "../../chunk-CK362NWK.js";
+import "../../chunk-GKP3ONKO.js";
 import "../../chunk-AHJJIANM.js";
-import "../../chunk-NTDKZW4E.js";
-import "../../chunk-NZ54JBSR.js";
+import "../../chunk-CNTOODUQ.js";
+import "../../chunk-U45RW4FC.js";
+import "../../chunk-LKR6D3RL.js";
 import "../../chunk-76KOVUDN.js";
 import "../../chunk-K2V4ULA2.js";
 export {

package/dist/hooks/useUniformFieldArray/index.cjs

@@ -1,15 +1,17 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-var _chunkMOVNWZX5cjs = require('../../chunk-MOVNWZX5.cjs');
-require('../../chunk-SOQ6GCN3.cjs');
+var _chunkIFBKJ5UZcjs = require('../../chunk-IFBKJ5UZ.cjs');
+require('../../chunk-OQUTHTOK.cjs');
+require('../../chunk-OE5BOGGX.cjs');
 require('../../chunk-NHEZXA4H.cjs');
-require('../../chunk-JMFDNTVC.cjs');
+require('../../chunk-7KEUEGRC.cjs');
 require('../../chunk-PCTYJUY7.cjs');
-require('../../chunk-OE5BOGGX.cjs');
-require('../../chunk-42NCLEX4.cjs');
+require('../../chunk-56TQOKG7.cjs');
+require('../../chunk-6LQ2O6SC.cjs');
+require('../../chunk-4L3JXJ62.cjs');
 require('../../chunk-Z353BLWI.cjs');
 require('../../chunk-555JRYCS.cjs');
 
 
-exports.useUniformFieldArray = _chunkMOVNWZX5cjs.useUniformFieldArray;
+exports.useUniformFieldArray = _chunkIFBKJ5UZcjs.useUniformFieldArray;
 //# sourceMappingURL=index.cjs.map

package/dist/hooks/useUniformFieldArray/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useUniformFieldArray/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,4DAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC;AACE;AACF,sEAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useUniformFieldArray/index.cjs"}
+{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useUniformFieldArray/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,4DAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC;AACE;AACF,sEAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useUniformFieldArray/index.cjs"}

package/dist/hooks/useUniformFieldArray/index.d.cts

@@ -5,7 +5,7 @@ import { FieldValues, ArrayPath } from 'react-hook-form';
 import { ReactNode } from 'react';
 import { useFormContext } from '../useFormContext/index.cjs';
 import '@fuf-stack/veto';
-import '../../FormContext-LRho0tno.cjs';
+import '../../FormContext-9Firwt4k.cjs';
 
 interface UseUniformFieldArrayProps<TFieldValues extends FieldValues = FieldValues> {
     /** Field name for the array */
@@ -43,7 +43,7 @@ declare const useUniformFieldArray: <TFieldValues extends FieldValues = FieldVal
     error: react_hook_form.FieldError[] | undefined;
     errorMessage: ReactNode | null;
     field: Omit<react_hook_form.ControllerRenderProps<TFieldValues>, "value" | "onChange"> & {
-        onChange: (... /** Initial value for new array elements */event: any[]) => void;
+        onChange: (...event: any[]) => void;
         value: string;
     };
     getErrorMessageProps: ReturnType<typeof _heroui_input.useInput>["getErrorMessageProps"];

package/dist/hooks/useUniformFieldArray/index.d.ts

@@ -5,7 +5,7 @@ import { FieldValues, ArrayPath } from 'react-hook-form';
 import { ReactNode } from 'react';
 import { useFormContext } from '../useFormContext/index.js';
 import '@fuf-stack/veto';
-import '../../FormContext-LRho0tno.js';
+import '../../FormContext-9Firwt4k.js';
 
 interface UseUniformFieldArrayProps<TFieldValues extends FieldValues = FieldValues> {
     /** Field name for the array */
@@ -43,7 +43,7 @@ declare const useUniformFieldArray: <TFieldValues extends FieldValues = FieldVal
     error: react_hook_form.FieldError[] | undefined;
     errorMessage: ReactNode | null;
     field: Omit<react_hook_form.ControllerRenderProps<TFieldValues>, "value" | "onChange"> & {
-        onChange: (... /** Initial value for new array elements */event: any[]) => void;
+        onChange: (...event: any[]) => void;
         value: string;
     };
     getErrorMessageProps: ReturnType<typeof _heroui_input.useInput>["getErrorMessageProps"];

package/dist/hooks/useUniformFieldArray/index.js

@@ -1,12 +1,14 @@
 import {
   useUniformFieldArray
-} from "../../chunk-FZQDAI7E.js";
-import "../../chunk-D3JYMGTB.js";
+} from "../../chunk-FND5Z5BW.js";
+import "../../chunk-EGFB5WEK.js";
+import "../../chunk-NTDKZW4E.js";
 import "../../chunk-ELYGQTXB.js";
-import "../../chunk-CK362NWK.js";
+import "../../chunk-GKP3ONKO.js";
 import "../../chunk-AHJJIANM.js";
-import "../../chunk-NTDKZW4E.js";
-import "../../chunk-NZ54JBSR.js";
+import "../../chunk-CNTOODUQ.js";
+import "../../chunk-U45RW4FC.js";
+import "../../chunk-LKR6D3RL.js";
 import "../../chunk-76KOVUDN.js";
 import "../../chunk-K2V4ULA2.js";
 export {

package/dist/hooks/useWatchUserChange/index.cjs

@@ -0,0 +1,11 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunk4F45XA7Ycjs = require('../../chunk-4F45XA7Y.cjs');
+require('../../chunk-6LQ2O6SC.cjs');
+require('../../chunk-4L3JXJ62.cjs');
+require('../../chunk-Z353BLWI.cjs');
+require('../../chunk-555JRYCS.cjs');
+
+
+exports.useWatchUserChange = _chunk4F45XA7Ycjs.useWatchUserChange;
+//# sourceMappingURL=index.cjs.map

package/dist/hooks/useWatchUserChange/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useWatchUserChange/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,4DAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC,oCAAiC;AACjC;AACE;AACF,kEAAC","file":"/home/runner/work/pixels/pixels/packages/uniform/dist/hooks/useWatchUserChange/index.cjs"}

package/dist/hooks/useWatchUserChange/index.d.cts

@@ -0,0 +1,73 @@
+import { FieldValues, Path, UseFormSetValue, UseFormResetField, UseFormReset } from 'react-hook-form';
+
+interface UseWatchUserChangeOptions<TFieldValues extends FieldValues> {
+    /** Field name to watch for user changes */
+    watch: Path<TFieldValues>;
+    /**
+     * Callback when watched field is changed by user input.
+     * Receives the new value and form helpers (setValue, resetField, reset).
+     */
+    onChange: (value: unknown, helpers: {
+        setValue: UseFormSetValue<TFieldValues>;
+        resetField: UseFormResetField<TFieldValues>;
+        reset: UseFormReset<TFieldValues>;
+    }) => void;
+}
+/**
+ * Hook that watches for user changes on a specific form field.
+ *
+ * Only triggers on manual user input (typing, clicking, selecting),
+ * NOT on programmatic changes like form.reset() or form.setValue().
+ *
+ * This hook subscribes to field changes at the source (useController),
+ * ensuring immediate and accurate detection of user interactions.
+ *
+ * Use cases:
+ * - Reset dependent fields when parent field changes
+ * - Set mode-specific default values when a toggle changes
+ * - Clear form sections based on user selections
+ * - Trigger side effects only on user interaction
+ *
+ * Note: To watch multiple fields, call this hook multiple times.
+ *
+ * @example
+ * ```tsx
+ * // Reset city and address when user changes country
+ * useWatchUserChange({
+ *   watch: 'country',
+ *   onChange: (value, { resetField }) => {
+ *     resetField('city');
+ *     resetField('address');
+ *   },
+ * });
+ *
+ * // Set defaults when user changes payment method
+ * useWatchUserChange({
+ *   watch: 'paymentMethod',
+ *   onChange: (value, { setValue }) => {
+ *     if (value === 'credit') {
+ *       setValue('installments', 3);
+ *     } else {
+ *       setValue('installments', 1);
+ *     }
+ *   },
+ * });
+ *
+ * // Watch multiple fields by calling the hook multiple times
+ * useWatchUserChange({
+ *   watch: 'category',
+ *   onChange: (value, { resetField }) => {
+ *     resetField('productId');
+ *   },
+ * });
+ * useWatchUserChange({
+ *   watch: 'brand',
+ *   onChange: (value, { resetField }) => {
+ *     resetField('productId');
+ *   },
+ * });
+ * ```
+ */
+declare const useWatchUserChange: <TFieldValues extends FieldValues = FieldValues>({ watch: watchField, onChange, }: UseWatchUserChangeOptions<TFieldValues>) => void;
+
+export { type UseWatchUserChangeOptions, useWatchUserChange };

package/dist/hooks/useWatchUserChange/index.d.ts

@@ -0,0 +1,73 @@
+import { FieldValues, Path, UseFormSetValue, UseFormResetField, UseFormReset } from 'react-hook-form';
+
+interface UseWatchUserChangeOptions<TFieldValues extends FieldValues> {
+    /** Field name to watch for user changes */
+    watch: Path<TFieldValues>;
+    /**
+     * Callback when watched field is changed by user input.
+     * Receives the new value and form helpers (setValue, resetField, reset).
+     */
+    onChange: (value: unknown, helpers: {
+        setValue: UseFormSetValue<TFieldValues>;
+        resetField: UseFormResetField<TFieldValues>;
+        reset: UseFormReset<TFieldValues>;
+    }) => void;
+}
+/**
+ * Hook that watches for user changes on a specific form field.
+ *
+ * Only triggers on manual user input (typing, clicking, selecting),
+ * NOT on programmatic changes like form.reset() or form.setValue().
+ *
+ * This hook subscribes to field changes at the source (useController),
+ * ensuring immediate and accurate detection of user interactions.
+ *
+ * Use cases:
+ * - Reset dependent fields when parent field changes
+ * - Set mode-specific default values when a toggle changes
+ * - Clear form sections based on user selections
+ * - Trigger side effects only on user interaction
+ *
+ * Note: To watch multiple fields, call this hook multiple times.
+ *
+ * @example
+ * ```tsx
+ * // Reset city and address when user changes country
+ * useWatchUserChange({
+ *   watch: 'country',
+ *   onChange: (value, { resetField }) => {
+ *     resetField('city');
+ *     resetField('address');
+ *   },
+ * });
+ *
+ * // Set defaults when user changes payment method
+ * useWatchUserChange({
+ *   watch: 'paymentMethod',
+ *   onChange: (value, { setValue }) => {
+ *     if (value === 'credit') {
+ *       setValue('installments', 3);
+ *     } else {
+ *       setValue('installments', 1);
+ *     }
+ *   },
+ * });
+ *
+ * // Watch multiple fields by calling the hook multiple times
+ * useWatchUserChange({
+ *   watch: 'category',
+ *   onChange: (value, { resetField }) => {
+ *     resetField('productId');
+ *   },
+ * });
+ * useWatchUserChange({
+ *   watch: 'brand',
+ *   onChange: (value, { resetField }) => {
+ *     resetField('productId');
+ *   },
+ * });
+ * ```
+ */
+declare const useWatchUserChange: <TFieldValues extends FieldValues = FieldValues>({ watch: watchField, onChange, }: UseWatchUserChangeOptions<TFieldValues>) => void;
+
+export { type UseWatchUserChangeOptions, useWatchUserChange };

package/dist/hooks/useWatchUserChange/index.js

@@ -0,0 +1,11 @@
+import {
+  useWatchUserChange
+} from "../../chunk-PY4GCAFN.js";
+import "../../chunk-U45RW4FC.js";
+import "../../chunk-LKR6D3RL.js";
+import "../../chunk-76KOVUDN.js";
+import "../../chunk-K2V4ULA2.js";
+export {
+  useWatchUserChange
+};
+//# sourceMappingURL=index.js.map

package/dist/hooks/useWatchUserChange/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}