@fuf-stack/uniform 1.19.5 → 1.20.2

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

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["useUniformField","useFormContext","flatArrayKey"],"sources":["../../../src/hooks/useUniformFieldArray/useUniformFieldArray.ts","../../../src/hooks/useUniformFieldArray/index.ts"],"sourcesContent":["import type { ReactNode } from 'react';\nimport type { ArrayPath, FieldValues, Path } from 'react-hook-form';\n\nimport { useEffect, useMemo, useRef, useState } from 'react';\nimport { useFieldArray as useRHFFieldArray } from 'react-hook-form';\n\nimport { useReducedMotion } from '@fuf-stack/pixel-motion';\n\nimport { flatArrayKey } from '../../helpers';\nimport { useFormContext } from '../useFormContext';\nimport { useUniformField } from '../useUniformField';\n\nexport interface UseUniformFieldArrayProps<\n  TFieldValues extends FieldValues = FieldValues,\n> {\n  /** Field name for the array */\n  name: ArrayPath<TFieldValues>;\n  /** Whether this is a flat array (array of primitives) */\n  flat?: boolean;\n  /** Initial value for new array elements */\n  elementInitialValue?: unknown;\n  /** Whether the last element cannot be removed (always maintain at least one element) */\n  lastElementNotRemovable?: boolean;\n  /** Disable the field */\n  disabled?: boolean;\n  /** Optional explicit test id used to build stable test ids */\n  testId?: string;\n  /** Optional label content */\n  label?: ReactNode;\n}\n\n/**\n * Enhanced useFieldArray hook with initialization and animation logic.\n * Based on React Hook Form's useFieldArray with additional features:\n * - Automatic initialization when lastElementNotRemovable is set\n * - Animation control (disabled during initialization)\n * - Support for flat arrays (arrays of primitives)\n *\n * Note: Automatic validation triggering on length change is disabled to prevent\n * triggering form-wide validation. Array validation still runs on form submission.\n *\n * @see https://react-hook-form.com/docs/usefieldarray\n */\nexport const useUniformFieldArray = <\n  TFieldValues extends FieldValues = FieldValues,\n>({\n  name,\n  flat = false,\n  elementInitialValue: _elementInitialValue = null,\n  lastElementNotRemovable = false,\n  disabled,\n  testId: explicitTestId,\n  label,\n}: UseUniformFieldArrayProps<TFieldValues>) => {\n  // Get uniform field state and utilities\n  const uniformField = useUniformField<TFieldValues>({\n    name: name as Path<TFieldValues> & string,\n    disabled,\n    testId: explicitTestId,\n    label,\n  });\n\n  const { control } = uniformField;\n\n  const { fields, append, remove, insert, move } = useRHFFieldArray({\n    control,\n    name,\n  });\n\n  const { trigger, setValue } = useFormContext<TFieldValues>();\n\n  // Determine if initialization is needed (initially or after reset).\n  // This flag automatically handles both scenarios:\n  // - Initial mount: fields.length starts at 0\n  // - Form reset: fields.length becomes 0 again\n  // Additional initialization conditions can be added here later (e.g., minElements > 0)\n  // Using useMemo ensures this value is properly tracked by React and effects can depend on it\n  const needsInitialize = useMemo(() => {\n    return lastElementNotRemovable && fields.length === 0;\n  }, [lastElementNotRemovable, fields.length]);\n\n  // Track whether initialization has completed. Initialized contextually:\n  // - If initialization IS needed (needsInitialize = true): starts as false, set to true after init\n  // - If initialization is NOT needed (needsInitialize = false): starts as true (already initialized)\n  // This ref is used to:\n  // 1. Skip validation during initialization/re-initialization\n  // 2. Gate animation enabling until after initialization\n  // 3. Gate motion preference effect until after initialization\n  const hasInitialized = useRef(!needsInitialize);\n\n  // Reset initialization flag when needsInitialize changes to true.\n  // This handles form reset: when fields become empty (needsInitialize becomes true),\n  // hasInitialized is reset to false, triggering re-initialization in the effect below.\n  useEffect(() => {\n    if (needsInitialize) {\n      hasInitialized.current = false;\n    }\n  }, [needsInitialize]);\n\n  // Validate array-level constraints (min/max items) when length changes.\n  // This ensures min/max errors appear instantly when user adds/removes items.\n  // Note: Child field validation also runs, but new empty fields won't show as invalid\n  // because useFormContext only sets invalid=true for touched fields or after form submission.\n  // Skip validation during initialization/re-initialization to avoid showing errors prematurely.\n  useEffect(() => {\n    if (hasInitialized.current) {\n      setTimeout(() => {\n        trigger(name as Path<TFieldValues>);\n      }, 200);\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [fields.length]);\n\n  // Animation control: Start with animations disabled to prevent animating in initial elements.\n  // Will be enabled after initialization completes (unless user prefers reduced motion).\n  const [disableAnimation, setDisableAnimation] = useState(true);\n\n  // Respond to user's motion preference changes (after initialization).\n  // During initialization, animations stay disabled regardless of preference.\n  const prefersReducedMotion = useReducedMotion();\n  useEffect(() => {\n    if (hasInitialized.current) {\n      setDisableAnimation(!!prefersReducedMotion);\n    }\n  }, [prefersReducedMotion]);\n\n  // Prepare initial element value based on mode\n  // - flat=true: arrays of primitives → object with flatArrayKey and null value by default\n  // - flat=false: arrays of objects → empty object by default\n  const elementInitialValue = useMemo(() => {\n    return flat\n      ? { [flatArrayKey]: _elementInitialValue ?? null }\n      : (_elementInitialValue ?? {});\n  }, [flat, _elementInitialValue]);\n\n  // Initialization/Re-initialization: Add initial element when needed.\n  // This handles both initial mount and form reset scenarios by reacting to needsInitialize.\n  // CRITICAL: This effect MUST be the LAST hook in this component.\n  // It sets hasInitialized.current = true, which acts as a gate for other effects.\n  // If this runs before other effects, hasInitialized will be true during their first run,\n  // causing them to execute logic meant only for post-initialization (e.g., validation,\n  // animation enabling). By placing this last, all other effects run first with\n  // hasInitialized = false, allowing them to skip initialization-phase logic.\n  useEffect(\n    () => {\n      if (needsInitialize) {\n        // use setValue instead of append to avoid focusing the added element\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        setValue(name as Path<TFieldValues>, [elementInitialValue] as any, {\n          shouldDirty: false,\n          shouldTouch: false,\n        });\n\n        // Mark initialization as complete\n        hasInitialized.current = true;\n\n        // Enable animations after a brief delay (unless user prefers reduced motion or animations are already enabled).\n        // This only runs on initial mount when animations start disabled.\n        // On reset, disableAnimation is typically false, so this setTimeout won't run and animations stay enabled.\n        if (!prefersReducedMotion && disableAnimation) {\n          setTimeout(() => {\n            setDisableAnimation(false);\n          }, 1);\n        }\n      }\n    },\n    // Run when needsInitialize changes (initial mount or reset)\n    // needsInitialize is memoized based on fields.length and lastElementNotRemovable\n    // Other dependencies are intentionally omitted:\n    // - append, setValue, trigger, setDisableAnimation are stable refs/functions\n    // - elementInitialValue, name, flat, prefersReducedMotion, disableAnimation are props/stable values\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [needsInitialize],\n  );\n\n  return {\n    // Field array methods and state\n    fields,\n    append,\n    remove,\n    insert,\n    move,\n    disableAnimation,\n    elementInitialValue,\n    // Uniform field state and utilities (spread all)\n    ...uniformField,\n  };\n};\n","/* v8 ignore start */\n\nexport * from './useUniformFieldArray';\n\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA2CA,MAAa,wBAEX,EACA,MACA,OAAO,OACP,qBAAqB,uBAAuB,MAC5C,0BAA0B,OAC1B,UACA,QAAQ,gBACR,YAC6C;CAE7C,MAAM,eAAeA,oCAAAA,gBAA8B;EAC3C;EACN;EACA,QAAQ;EACR;EACD,CAAC;CAEF,MAAM,EAAE,YAAY;CAEpB,MAAM,EAAE,QAAQ,QAAQ,QAAQ,QAAQ,UAAA,GAAA,gBAAA,eAA0B;EAChE;EACA;EACD,CAAC;CAEF,MAAM,EAAE,SAAS,aAAaC,uBAAAA,gBAA8B;CAQ5D,MAAM,mBAAA,GAAA,MAAA,eAAgC;AACpC,SAAO,2BAA2B,OAAO,WAAW;IACnD,CAAC,yBAAyB,OAAO,OAAO,CAAC;CAS5C,MAAM,kBAAA,GAAA,MAAA,QAAwB,CAAC,gBAAgB;AAK/C,EAAA,GAAA,MAAA,iBAAgB;AACd,MAAI,gBACF,gBAAe,UAAU;IAE1B,CAAC,gBAAgB,CAAC;AAOrB,EAAA,GAAA,MAAA,iBAAgB;AACd,MAAI,eAAe,QACjB,kBAAiB;AACf,WAAQ,KAA2B;KAClC,IAAI;IAGR,CAAC,OAAO,OAAO,CAAC;CAInB,MAAM,CAAC,kBAAkB,wBAAA,GAAA,MAAA,UAAgC,KAAK;CAI9D,MAAM,wBAAA,GAAA,wBAAA,mBAAyC;AAC/C,EAAA,GAAA,MAAA,iBAAgB;AACd,MAAI,eAAe,QACjB,qBAAoB,CAAC,CAAC,qBAAqB;IAE5C,CAAC,qBAAqB,CAAC;CAK1B,MAAM,uBAAA,GAAA,MAAA,eAAoC;AACxC,SAAO,OACH,GAAGC,sBAAAA,eAAe,wBAAwB,MAAM,GAC/C,wBAAwB,EAAE;IAC9B,CAAC,MAAM,qBAAqB,CAAC;AAUhC,EAAA,GAAA,MAAA,iBACQ;AACJ,MAAI,iBAAiB;AAGnB,YAAS,MAA4B,CAAC,oBAAoB,EAAS;IACjE,aAAa;IACb,aAAa;IACd,CAAC;AAGF,kBAAe,UAAU;AAKzB,OAAI,CAAC,wBAAwB,iBAC3B,kBAAiB;AACf,wBAAoB,MAAM;MACzB,EAAE;;IAUX,CAAC,gBAAgB,CAClB;AAED,QAAO;EAEL;EACA;EACA;EACA;EACA;EACA;EACA;EAEA,GAAG;EACJ"}
+{"version":3,"file":"index.cjs","names":["useUniformField","useFormContext","flatArrayKey"],"sources":["../../../src/hooks/useUniformFieldArray/useUniformFieldArray.ts","../../../src/hooks/useUniformFieldArray/index.ts"],"sourcesContent":["import type { ReactNode } from 'react';\nimport type { ArrayPath, FieldValues, Path } from 'react-hook-form';\n\nimport { useEffect, useMemo, useRef, useState } from 'react';\nimport { useFieldArray as useRHFFieldArray } from 'react-hook-form';\n\nimport { useReducedMotion } from '@fuf-stack/pixel-motion';\n\nimport { flatArrayKey } from '../../helpers';\nimport { useFormContext } from '../useFormContext';\nimport { useUniformField } from '../useUniformField';\n\nexport interface UseUniformFieldArrayProps<\n  TFieldValues extends FieldValues = FieldValues,\n> {\n  /** Field name for the array */\n  name: ArrayPath<TFieldValues>;\n  /** Whether this is a flat array (array of primitives) */\n  flat?: boolean;\n  /** Initial value for new array elements */\n  elementInitialValue?: unknown;\n  /** Whether the last element cannot be removed (always maintain at least one element) */\n  lastElementNotRemovable?: boolean;\n  /** Disable the field */\n  disabled?: boolean;\n  /** Optional explicit test id used to build stable test ids */\n  testId?: string;\n  /** Optional label content */\n  label?: ReactNode;\n}\n\n/**\n * Enhanced useFieldArray hook with initialization and animation logic.\n * Based on React Hook Form's useFieldArray with additional features:\n * - Automatic initialization when lastElementNotRemovable is set\n * - Animation control (disabled during initialization)\n * - Support for flat arrays (arrays of primitives)\n *\n * Note: Automatic validation triggering on length change is disabled to prevent\n * triggering form-wide validation. Array validation still runs on form submission.\n *\n * @see https://react-hook-form.com/docs/usefieldarray\n */\nexport const useUniformFieldArray = <\n  TFieldValues extends FieldValues = FieldValues,\n>({\n  name,\n  flat = false,\n  elementInitialValue: _elementInitialValue = null,\n  lastElementNotRemovable = false,\n  disabled,\n  testId: explicitTestId,\n  label,\n}: UseUniformFieldArrayProps<TFieldValues>) => {\n  // Get uniform field state and utilities\n  const uniformField = useUniformField<TFieldValues>({\n    name: name as Path<TFieldValues> & string,\n    disabled,\n    testId: explicitTestId,\n    label,\n  });\n\n  const { control } = uniformField;\n\n  const { fields, append, remove, insert, move } = useRHFFieldArray({\n    control,\n    name,\n  });\n\n  const { trigger, setValue } = useFormContext<TFieldValues>();\n\n  // Determine if initialization is needed (initially or after reset).\n  // This flag automatically handles both scenarios:\n  // - Initial mount: fields.length starts at 0\n  // - Form reset: fields.length becomes 0 again\n  // Additional initialization conditions can be added here later (e.g., minElements > 0)\n  // Using useMemo ensures this value is properly tracked by React and effects can depend on it\n  const needsInitialize = useMemo(() => {\n    return lastElementNotRemovable && fields.length === 0;\n  }, [lastElementNotRemovable, fields.length]);\n\n  // Track whether initialization has completed. Initialized contextually:\n  // - If initialization IS needed (needsInitialize = true): starts as false, set to true after init\n  // - If initialization is NOT needed (needsInitialize = false): starts as true (already initialized)\n  // This ref is used to:\n  // 1. Skip validation during initialization/re-initialization\n  // 2. Gate animation enabling until after initialization\n  // 3. Gate motion preference effect until after initialization\n  const hasInitialized = useRef(!needsInitialize);\n\n  // Reset initialization flag when needsInitialize changes to true.\n  // This handles form reset: when fields become empty (needsInitialize becomes true),\n  // hasInitialized is reset to false, triggering re-initialization in the effect below.\n  useEffect(() => {\n    if (needsInitialize) {\n      hasInitialized.current = false;\n    }\n  }, [needsInitialize]);\n\n  // Validate array-level constraints (min/max items) when length changes.\n  // This ensures min/max errors appear instantly when user adds/removes items.\n  // Note: Child field validation also runs, but new empty fields won't show as invalid\n  // because useFormContext only sets invalid=true for touched fields or after form submission.\n  // Skip validation during initialization/re-initialization to avoid showing errors prematurely.\n  useEffect(() => {\n    if (hasInitialized.current) {\n      setTimeout(() => {\n        trigger(name as Path<TFieldValues>);\n      }, 200);\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [fields.length]);\n\n  // Animation control: Start with animations disabled to prevent animating in initial elements.\n  // Will be enabled after initialization completes (unless user prefers reduced motion).\n  const [disableAnimation, setDisableAnimation] = useState(true);\n\n  // Respond to user's motion preference changes (after initialization).\n  // During initialization, animations stay disabled regardless of preference.\n  const prefersReducedMotion = useReducedMotion();\n  useEffect(() => {\n    if (hasInitialized.current) {\n      setDisableAnimation(!!prefersReducedMotion);\n    }\n  }, [prefersReducedMotion]);\n\n  // Prepare initial element value based on mode\n  // - flat=true: arrays of primitives → object with flatArrayKey and null value by default\n  // - flat=false: arrays of objects → empty object by default\n  const elementInitialValue = useMemo(() => {\n    return flat\n      ? { [flatArrayKey]: _elementInitialValue ?? null }\n      : (_elementInitialValue ?? {});\n  }, [flat, _elementInitialValue]);\n\n  // Initialization/Re-initialization: Add initial element when needed.\n  // This handles both initial mount and form reset scenarios by reacting to needsInitialize.\n  // CRITICAL: This effect MUST be the LAST hook in this component.\n  // It sets hasInitialized.current = true, which acts as a gate for other effects.\n  // If this runs before other effects, hasInitialized will be true during their first run,\n  // causing them to execute logic meant only for post-initialization (e.g., validation,\n  // animation enabling). By placing this last, all other effects run first with\n  // hasInitialized = false, allowing them to skip initialization-phase logic.\n  useEffect(\n    () => {\n      if (needsInitialize) {\n        // use setValue instead of append to avoid focusing the added element\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        setValue(name as Path<TFieldValues>, [elementInitialValue] as any, {\n          shouldDirty: false,\n          shouldTouch: false,\n        });\n\n        // Mark initialization as complete\n        hasInitialized.current = true;\n\n        // Enable animations after a brief delay (unless user prefers reduced motion or animations are already enabled).\n        // This only runs on initial mount when animations start disabled.\n        // On reset, disableAnimation is typically false, so this setTimeout won't run and animations stay enabled.\n        if (!prefersReducedMotion && disableAnimation) {\n          setTimeout(() => {\n            setDisableAnimation(false);\n          }, 1);\n        }\n      }\n    },\n    // Run when needsInitialize changes (initial mount or reset)\n    // needsInitialize is memoized based on fields.length and lastElementNotRemovable\n    // Other dependencies are intentionally omitted:\n    // - append, setValue, trigger, setDisableAnimation are stable refs/functions\n    // - elementInitialValue, name, flat, prefersReducedMotion, disableAnimation are props/stable values\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [needsInitialize],\n  );\n\n  return {\n    // Field array methods and state\n    fields,\n    append,\n    remove,\n    insert,\n    move,\n    disableAnimation,\n    elementInitialValue,\n    // Uniform field state and utilities (spread all)\n    ...uniformField,\n  };\n};\n","/* v8 ignore start */\n\nexport * from './useUniformFieldArray';\n\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA2CA,MAAa,wBAEX,EACA,MACA,OAAO,OACP,qBAAqB,uBAAuB,MAC5C,0BAA0B,OAC1B,UACA,QAAQ,gBACR,YAC6C;CAE7C,MAAM,eAAeA,oCAAAA,gBAA8B;EAC3C;EACN;EACA,QAAQ;EACR;CACF,CAAC;CAED,MAAM,EAAE,YAAY;CAEpB,MAAM,EAAE,QAAQ,QAAQ,QAAQ,QAAQ,UAAA,GAAA,gBAAA,eAA0B;EAChE;EACA;CACF,CAAC;CAED,MAAM,EAAE,SAAS,aAAaC,uBAAAA,eAA6B;CAQ3D,MAAM,mBAAA,GAAA,MAAA,eAAgC;EACpC,OAAO,2BAA2B,OAAO,WAAW;CACtD,GAAG,CAAC,yBAAyB,OAAO,MAAM,CAAC;CAS3C,MAAM,kBAAA,GAAA,MAAA,QAAwB,CAAC,eAAe;CAK9C,CAAA,GAAA,MAAA,iBAAgB;EACd,IAAI,iBACF,eAAe,UAAU;CAE7B,GAAG,CAAC,eAAe,CAAC;CAOpB,CAAA,GAAA,MAAA,iBAAgB;EACd,IAAI,eAAe,SACjB,iBAAiB;GACf,QAAQ,IAA0B;EACpC,GAAG,GAAG;CAGV,GAAG,CAAC,OAAO,MAAM,CAAC;CAIlB,MAAM,CAAC,kBAAkB,wBAAA,GAAA,MAAA,UAAgC,IAAI;CAI7D,MAAM,wBAAA,GAAA,wBAAA,kBAAwC;CAC9C,CAAA,GAAA,MAAA,iBAAgB;EACd,IAAI,eAAe,SACjB,oBAAoB,CAAC,CAAC,oBAAoB;CAE9C,GAAG,CAAC,oBAAoB,CAAC;CAKzB,MAAM,uBAAA,GAAA,MAAA,eAAoC;EACxC,OAAO,OACH,GAAGC,sBAAAA,eAAe,wBAAwB,KAAK,IAC9C,wBAAwB,CAAC;CAChC,GAAG,CAAC,MAAM,oBAAoB,CAAC;CAU/B,CAAA,GAAA,MAAA,iBACQ;EACJ,IAAI,iBAAiB;GAGnB,SAAS,MAA4B,CAAC,mBAAmB,GAAU;IACjE,aAAa;IACb,aAAa;GACf,CAAC;GAGD,eAAe,UAAU;GAKzB,IAAI,CAAC,wBAAwB,kBAC3B,iBAAiB;IACf,oBAAoB,KAAK;GAC3B,GAAG,CAAC;EAER;CACF,GAOA,CAAC,eAAe,CAClB;CAEA,OAAO;EAEL;EACA;EACA;EACA;EACA;EACA;EACA;EAEA,GAAG;CACL;AACF"}

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

@@ -1,2 +1,2 @@
-import { n as useUniformFieldArray, t as UseUniformFieldArrayProps } from "../../useUniformFieldArray-CDEagafl.cjs";
+import { n as useUniformFieldArray, t as UseUniformFieldArrayProps } from "../../useUniformFieldArray-BodQL2Ea.cjs";
 export { UseUniformFieldArrayProps, useUniformFieldArray };

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

@@ -1,2 +1,2 @@
-import { n as useUniformFieldArray, t as UseUniformFieldArrayProps } from "../../useUniformFieldArray-CMHoo4o3.js";
+import { n as useUniformFieldArray, t as UseUniformFieldArrayProps } from "../../useUniformFieldArray-CvlgXVBm.js";
 export { UseUniformFieldArrayProps, useUniformFieldArray };

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["useRHFFieldArray","useFormContext"],"sources":["../../../src/hooks/useUniformFieldArray/useUniformFieldArray.ts","../../../src/hooks/useUniformFieldArray/index.ts"],"sourcesContent":["import type { ReactNode } from 'react';\nimport type { ArrayPath, FieldValues, Path } from 'react-hook-form';\n\nimport { useEffect, useMemo, useRef, useState } from 'react';\nimport { useFieldArray as useRHFFieldArray } from 'react-hook-form';\n\nimport { useReducedMotion } from '@fuf-stack/pixel-motion';\n\nimport { flatArrayKey } from '../../helpers';\nimport { useFormContext } from '../useFormContext';\nimport { useUniformField } from '../useUniformField';\n\nexport interface UseUniformFieldArrayProps<\n  TFieldValues extends FieldValues = FieldValues,\n> {\n  /** Field name for the array */\n  name: ArrayPath<TFieldValues>;\n  /** Whether this is a flat array (array of primitives) */\n  flat?: boolean;\n  /** Initial value for new array elements */\n  elementInitialValue?: unknown;\n  /** Whether the last element cannot be removed (always maintain at least one element) */\n  lastElementNotRemovable?: boolean;\n  /** Disable the field */\n  disabled?: boolean;\n  /** Optional explicit test id used to build stable test ids */\n  testId?: string;\n  /** Optional label content */\n  label?: ReactNode;\n}\n\n/**\n * Enhanced useFieldArray hook with initialization and animation logic.\n * Based on React Hook Form's useFieldArray with additional features:\n * - Automatic initialization when lastElementNotRemovable is set\n * - Animation control (disabled during initialization)\n * - Support for flat arrays (arrays of primitives)\n *\n * Note: Automatic validation triggering on length change is disabled to prevent\n * triggering form-wide validation. Array validation still runs on form submission.\n *\n * @see https://react-hook-form.com/docs/usefieldarray\n */\nexport const useUniformFieldArray = <\n  TFieldValues extends FieldValues = FieldValues,\n>({\n  name,\n  flat = false,\n  elementInitialValue: _elementInitialValue = null,\n  lastElementNotRemovable = false,\n  disabled,\n  testId: explicitTestId,\n  label,\n}: UseUniformFieldArrayProps<TFieldValues>) => {\n  // Get uniform field state and utilities\n  const uniformField = useUniformField<TFieldValues>({\n    name: name as Path<TFieldValues> & string,\n    disabled,\n    testId: explicitTestId,\n    label,\n  });\n\n  const { control } = uniformField;\n\n  const { fields, append, remove, insert, move } = useRHFFieldArray({\n    control,\n    name,\n  });\n\n  const { trigger, setValue } = useFormContext<TFieldValues>();\n\n  // Determine if initialization is needed (initially or after reset).\n  // This flag automatically handles both scenarios:\n  // - Initial mount: fields.length starts at 0\n  // - Form reset: fields.length becomes 0 again\n  // Additional initialization conditions can be added here later (e.g., minElements > 0)\n  // Using useMemo ensures this value is properly tracked by React and effects can depend on it\n  const needsInitialize = useMemo(() => {\n    return lastElementNotRemovable && fields.length === 0;\n  }, [lastElementNotRemovable, fields.length]);\n\n  // Track whether initialization has completed. Initialized contextually:\n  // - If initialization IS needed (needsInitialize = true): starts as false, set to true after init\n  // - If initialization is NOT needed (needsInitialize = false): starts as true (already initialized)\n  // This ref is used to:\n  // 1. Skip validation during initialization/re-initialization\n  // 2. Gate animation enabling until after initialization\n  // 3. Gate motion preference effect until after initialization\n  const hasInitialized = useRef(!needsInitialize);\n\n  // Reset initialization flag when needsInitialize changes to true.\n  // This handles form reset: when fields become empty (needsInitialize becomes true),\n  // hasInitialized is reset to false, triggering re-initialization in the effect below.\n  useEffect(() => {\n    if (needsInitialize) {\n      hasInitialized.current = false;\n    }\n  }, [needsInitialize]);\n\n  // Validate array-level constraints (min/max items) when length changes.\n  // This ensures min/max errors appear instantly when user adds/removes items.\n  // Note: Child field validation also runs, but new empty fields won't show as invalid\n  // because useFormContext only sets invalid=true for touched fields or after form submission.\n  // Skip validation during initialization/re-initialization to avoid showing errors prematurely.\n  useEffect(() => {\n    if (hasInitialized.current) {\n      setTimeout(() => {\n        trigger(name as Path<TFieldValues>);\n      }, 200);\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [fields.length]);\n\n  // Animation control: Start with animations disabled to prevent animating in initial elements.\n  // Will be enabled after initialization completes (unless user prefers reduced motion).\n  const [disableAnimation, setDisableAnimation] = useState(true);\n\n  // Respond to user's motion preference changes (after initialization).\n  // During initialization, animations stay disabled regardless of preference.\n  const prefersReducedMotion = useReducedMotion();\n  useEffect(() => {\n    if (hasInitialized.current) {\n      setDisableAnimation(!!prefersReducedMotion);\n    }\n  }, [prefersReducedMotion]);\n\n  // Prepare initial element value based on mode\n  // - flat=true: arrays of primitives → object with flatArrayKey and null value by default\n  // - flat=false: arrays of objects → empty object by default\n  const elementInitialValue = useMemo(() => {\n    return flat\n      ? { [flatArrayKey]: _elementInitialValue ?? null }\n      : (_elementInitialValue ?? {});\n  }, [flat, _elementInitialValue]);\n\n  // Initialization/Re-initialization: Add initial element when needed.\n  // This handles both initial mount and form reset scenarios by reacting to needsInitialize.\n  // CRITICAL: This effect MUST be the LAST hook in this component.\n  // It sets hasInitialized.current = true, which acts as a gate for other effects.\n  // If this runs before other effects, hasInitialized will be true during their first run,\n  // causing them to execute logic meant only for post-initialization (e.g., validation,\n  // animation enabling). By placing this last, all other effects run first with\n  // hasInitialized = false, allowing them to skip initialization-phase logic.\n  useEffect(\n    () => {\n      if (needsInitialize) {\n        // use setValue instead of append to avoid focusing the added element\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        setValue(name as Path<TFieldValues>, [elementInitialValue] as any, {\n          shouldDirty: false,\n          shouldTouch: false,\n        });\n\n        // Mark initialization as complete\n        hasInitialized.current = true;\n\n        // Enable animations after a brief delay (unless user prefers reduced motion or animations are already enabled).\n        // This only runs on initial mount when animations start disabled.\n        // On reset, disableAnimation is typically false, so this setTimeout won't run and animations stay enabled.\n        if (!prefersReducedMotion && disableAnimation) {\n          setTimeout(() => {\n            setDisableAnimation(false);\n          }, 1);\n        }\n      }\n    },\n    // Run when needsInitialize changes (initial mount or reset)\n    // needsInitialize is memoized based on fields.length and lastElementNotRemovable\n    // Other dependencies are intentionally omitted:\n    // - append, setValue, trigger, setDisableAnimation are stable refs/functions\n    // - elementInitialValue, name, flat, prefersReducedMotion, disableAnimation are props/stable values\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [needsInitialize],\n  );\n\n  return {\n    // Field array methods and state\n    fields,\n    append,\n    remove,\n    insert,\n    move,\n    disableAnimation,\n    elementInitialValue,\n    // Uniform field state and utilities (spread all)\n    ...uniformField,\n  };\n};\n","/* v8 ignore start */\n\nexport * from './useUniformFieldArray';\n\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA2CA,MAAa,wBAEX,EACA,MACA,OAAO,OACP,qBAAqB,uBAAuB,MAC5C,0BAA0B,OAC1B,UACA,QAAQ,gBACR,YAC6C;CAE7C,MAAM,eAAe,gBAA8B;EAC3C;EACN;EACA,QAAQ;EACR;EACD,CAAC;CAEF,MAAM,EAAE,YAAY;CAEpB,MAAM,EAAE,QAAQ,QAAQ,QAAQ,QAAQ,SAASA,cAAiB;EAChE;EACA;EACD,CAAC;CAEF,MAAM,EAAE,SAAS,aAAaC,kBAA8B;CAQ5D,MAAM,kBAAkB,cAAc;AACpC,SAAO,2BAA2B,OAAO,WAAW;IACnD,CAAC,yBAAyB,OAAO,OAAO,CAAC;CAS5C,MAAM,iBAAiB,OAAO,CAAC,gBAAgB;AAK/C,iBAAgB;AACd,MAAI,gBACF,gBAAe,UAAU;IAE1B,CAAC,gBAAgB,CAAC;AAOrB,iBAAgB;AACd,MAAI,eAAe,QACjB,kBAAiB;AACf,WAAQ,KAA2B;KAClC,IAAI;IAGR,CAAC,OAAO,OAAO,CAAC;CAInB,MAAM,CAAC,kBAAkB,uBAAuB,SAAS,KAAK;CAI9D,MAAM,uBAAuB,kBAAkB;AAC/C,iBAAgB;AACd,MAAI,eAAe,QACjB,qBAAoB,CAAC,CAAC,qBAAqB;IAE5C,CAAC,qBAAqB,CAAC;CAK1B,MAAM,sBAAsB,cAAc;AACxC,SAAO,OACH,GAAG,eAAe,wBAAwB,MAAM,GAC/C,wBAAwB,EAAE;IAC9B,CAAC,MAAM,qBAAqB,CAAC;AAUhC,iBACQ;AACJ,MAAI,iBAAiB;AAGnB,YAAS,MAA4B,CAAC,oBAAoB,EAAS;IACjE,aAAa;IACb,aAAa;IACd,CAAC;AAGF,kBAAe,UAAU;AAKzB,OAAI,CAAC,wBAAwB,iBAC3B,kBAAiB;AACf,wBAAoB,MAAM;MACzB,EAAE;;IAUX,CAAC,gBAAgB,CAClB;AAED,QAAO;EAEL;EACA;EACA;EACA;EACA;EACA;EACA;EAEA,GAAG;EACJ"}
+{"version":3,"file":"index.js","names":["useRHFFieldArray","useFormContext"],"sources":["../../../src/hooks/useUniformFieldArray/useUniformFieldArray.ts","../../../src/hooks/useUniformFieldArray/index.ts"],"sourcesContent":["import type { ReactNode } from 'react';\nimport type { ArrayPath, FieldValues, Path } from 'react-hook-form';\n\nimport { useEffect, useMemo, useRef, useState } from 'react';\nimport { useFieldArray as useRHFFieldArray } from 'react-hook-form';\n\nimport { useReducedMotion } from '@fuf-stack/pixel-motion';\n\nimport { flatArrayKey } from '../../helpers';\nimport { useFormContext } from '../useFormContext';\nimport { useUniformField } from '../useUniformField';\n\nexport interface UseUniformFieldArrayProps<\n  TFieldValues extends FieldValues = FieldValues,\n> {\n  /** Field name for the array */\n  name: ArrayPath<TFieldValues>;\n  /** Whether this is a flat array (array of primitives) */\n  flat?: boolean;\n  /** Initial value for new array elements */\n  elementInitialValue?: unknown;\n  /** Whether the last element cannot be removed (always maintain at least one element) */\n  lastElementNotRemovable?: boolean;\n  /** Disable the field */\n  disabled?: boolean;\n  /** Optional explicit test id used to build stable test ids */\n  testId?: string;\n  /** Optional label content */\n  label?: ReactNode;\n}\n\n/**\n * Enhanced useFieldArray hook with initialization and animation logic.\n * Based on React Hook Form's useFieldArray with additional features:\n * - Automatic initialization when lastElementNotRemovable is set\n * - Animation control (disabled during initialization)\n * - Support for flat arrays (arrays of primitives)\n *\n * Note: Automatic validation triggering on length change is disabled to prevent\n * triggering form-wide validation. Array validation still runs on form submission.\n *\n * @see https://react-hook-form.com/docs/usefieldarray\n */\nexport const useUniformFieldArray = <\n  TFieldValues extends FieldValues = FieldValues,\n>({\n  name,\n  flat = false,\n  elementInitialValue: _elementInitialValue = null,\n  lastElementNotRemovable = false,\n  disabled,\n  testId: explicitTestId,\n  label,\n}: UseUniformFieldArrayProps<TFieldValues>) => {\n  // Get uniform field state and utilities\n  const uniformField = useUniformField<TFieldValues>({\n    name: name as Path<TFieldValues> & string,\n    disabled,\n    testId: explicitTestId,\n    label,\n  });\n\n  const { control } = uniformField;\n\n  const { fields, append, remove, insert, move } = useRHFFieldArray({\n    control,\n    name,\n  });\n\n  const { trigger, setValue } = useFormContext<TFieldValues>();\n\n  // Determine if initialization is needed (initially or after reset).\n  // This flag automatically handles both scenarios:\n  // - Initial mount: fields.length starts at 0\n  // - Form reset: fields.length becomes 0 again\n  // Additional initialization conditions can be added here later (e.g., minElements > 0)\n  // Using useMemo ensures this value is properly tracked by React and effects can depend on it\n  const needsInitialize = useMemo(() => {\n    return lastElementNotRemovable && fields.length === 0;\n  }, [lastElementNotRemovable, fields.length]);\n\n  // Track whether initialization has completed. Initialized contextually:\n  // - If initialization IS needed (needsInitialize = true): starts as false, set to true after init\n  // - If initialization is NOT needed (needsInitialize = false): starts as true (already initialized)\n  // This ref is used to:\n  // 1. Skip validation during initialization/re-initialization\n  // 2. Gate animation enabling until after initialization\n  // 3. Gate motion preference effect until after initialization\n  const hasInitialized = useRef(!needsInitialize);\n\n  // Reset initialization flag when needsInitialize changes to true.\n  // This handles form reset: when fields become empty (needsInitialize becomes true),\n  // hasInitialized is reset to false, triggering re-initialization in the effect below.\n  useEffect(() => {\n    if (needsInitialize) {\n      hasInitialized.current = false;\n    }\n  }, [needsInitialize]);\n\n  // Validate array-level constraints (min/max items) when length changes.\n  // This ensures min/max errors appear instantly when user adds/removes items.\n  // Note: Child field validation also runs, but new empty fields won't show as invalid\n  // because useFormContext only sets invalid=true for touched fields or after form submission.\n  // Skip validation during initialization/re-initialization to avoid showing errors prematurely.\n  useEffect(() => {\n    if (hasInitialized.current) {\n      setTimeout(() => {\n        trigger(name as Path<TFieldValues>);\n      }, 200);\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [fields.length]);\n\n  // Animation control: Start with animations disabled to prevent animating in initial elements.\n  // Will be enabled after initialization completes (unless user prefers reduced motion).\n  const [disableAnimation, setDisableAnimation] = useState(true);\n\n  // Respond to user's motion preference changes (after initialization).\n  // During initialization, animations stay disabled regardless of preference.\n  const prefersReducedMotion = useReducedMotion();\n  useEffect(() => {\n    if (hasInitialized.current) {\n      setDisableAnimation(!!prefersReducedMotion);\n    }\n  }, [prefersReducedMotion]);\n\n  // Prepare initial element value based on mode\n  // - flat=true: arrays of primitives → object with flatArrayKey and null value by default\n  // - flat=false: arrays of objects → empty object by default\n  const elementInitialValue = useMemo(() => {\n    return flat\n      ? { [flatArrayKey]: _elementInitialValue ?? null }\n      : (_elementInitialValue ?? {});\n  }, [flat, _elementInitialValue]);\n\n  // Initialization/Re-initialization: Add initial element when needed.\n  // This handles both initial mount and form reset scenarios by reacting to needsInitialize.\n  // CRITICAL: This effect MUST be the LAST hook in this component.\n  // It sets hasInitialized.current = true, which acts as a gate for other effects.\n  // If this runs before other effects, hasInitialized will be true during their first run,\n  // causing them to execute logic meant only for post-initialization (e.g., validation,\n  // animation enabling). By placing this last, all other effects run first with\n  // hasInitialized = false, allowing them to skip initialization-phase logic.\n  useEffect(\n    () => {\n      if (needsInitialize) {\n        // use setValue instead of append to avoid focusing the added element\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        setValue(name as Path<TFieldValues>, [elementInitialValue] as any, {\n          shouldDirty: false,\n          shouldTouch: false,\n        });\n\n        // Mark initialization as complete\n        hasInitialized.current = true;\n\n        // Enable animations after a brief delay (unless user prefers reduced motion or animations are already enabled).\n        // This only runs on initial mount when animations start disabled.\n        // On reset, disableAnimation is typically false, so this setTimeout won't run and animations stay enabled.\n        if (!prefersReducedMotion && disableAnimation) {\n          setTimeout(() => {\n            setDisableAnimation(false);\n          }, 1);\n        }\n      }\n    },\n    // Run when needsInitialize changes (initial mount or reset)\n    // needsInitialize is memoized based on fields.length and lastElementNotRemovable\n    // Other dependencies are intentionally omitted:\n    // - append, setValue, trigger, setDisableAnimation are stable refs/functions\n    // - elementInitialValue, name, flat, prefersReducedMotion, disableAnimation are props/stable values\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [needsInitialize],\n  );\n\n  return {\n    // Field array methods and state\n    fields,\n    append,\n    remove,\n    insert,\n    move,\n    disableAnimation,\n    elementInitialValue,\n    // Uniform field state and utilities (spread all)\n    ...uniformField,\n  };\n};\n","/* v8 ignore start */\n\nexport * from './useUniformFieldArray';\n\n/* v8 ignore stop */\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA2CA,MAAa,wBAEX,EACA,MACA,OAAO,OACP,qBAAqB,uBAAuB,MAC5C,0BAA0B,OAC1B,UACA,QAAQ,gBACR,YAC6C;CAE7C,MAAM,eAAe,gBAA8B;EAC3C;EACN;EACA,QAAQ;EACR;CACF,CAAC;CAED,MAAM,EAAE,YAAY;CAEpB,MAAM,EAAE,QAAQ,QAAQ,QAAQ,QAAQ,SAASA,cAAiB;EAChE;EACA;CACF,CAAC;CAED,MAAM,EAAE,SAAS,aAAaC,iBAA6B;CAQ3D,MAAM,kBAAkB,cAAc;EACpC,OAAO,2BAA2B,OAAO,WAAW;CACtD,GAAG,CAAC,yBAAyB,OAAO,MAAM,CAAC;CAS3C,MAAM,iBAAiB,OAAO,CAAC,eAAe;CAK9C,gBAAgB;EACd,IAAI,iBACF,eAAe,UAAU;CAE7B,GAAG,CAAC,eAAe,CAAC;CAOpB,gBAAgB;EACd,IAAI,eAAe,SACjB,iBAAiB;GACf,QAAQ,IAA0B;EACpC,GAAG,GAAG;CAGV,GAAG,CAAC,OAAO,MAAM,CAAC;CAIlB,MAAM,CAAC,kBAAkB,uBAAuB,SAAS,IAAI;CAI7D,MAAM,uBAAuB,iBAAiB;CAC9C,gBAAgB;EACd,IAAI,eAAe,SACjB,oBAAoB,CAAC,CAAC,oBAAoB;CAE9C,GAAG,CAAC,oBAAoB,CAAC;CAKzB,MAAM,sBAAsB,cAAc;EACxC,OAAO,OACH,GAAG,eAAe,wBAAwB,KAAK,IAC9C,wBAAwB,CAAC;CAChC,GAAG,CAAC,MAAM,oBAAoB,CAAC;CAU/B,gBACQ;EACJ,IAAI,iBAAiB;GAGnB,SAAS,MAA4B,CAAC,mBAAmB,GAAU;IACjE,aAAa;IACb,aAAa;GACf,CAAC;GAGD,eAAe,UAAU;GAKzB,IAAI,CAAC,wBAAwB,kBAC3B,iBAAiB;IACf,oBAAoB,KAAK;GAC3B,GAAG,CAAC;EAER;CACF,GAOA,CAAC,eAAe,CAClB;CAEA,OAAO;EAEL;EACA;EACA;EACA;EACA;EACA;EACA;EAEA,GAAG;CACL;AACF"}

package/dist/index-0zgyvkAF.d.cts

@@ -0,0 +1,224 @@
+//#region src/helpers/createOptionValueConverter/createOptionValueConverter.d.ts
+/**
+ * Creates a converter function that preserves the original type (string, number, or boolean)
+ * of option values when converting from string keys back to their original type.
+ *
+ * This is useful for radio/select components where the underlying UI library
+ * uses string keys internally, but we want to preserve number/boolean values in the form state.
+ *
+ * @param options - Array of options with a value property that can be string, number, or boolean
+ * @returns An object with:
+ *   - `convertToOriginalType`: Function to convert a string key back to its original type
+ *   - `numberValueKeys`: Set of string representations of number values (for internal use)
+ *   - `booleanValueKeys`: Map of string representations to boolean values (for internal use)
+ */
+declare const createOptionValueConverter: <T extends {
+  value: string | number | boolean;
+}>(options: T[]) => {
+  booleanValueKeys: Map<string, boolean>;
+  convertToOriginalType: (key: string | number | boolean) => string | number | boolean;
+  numberValueKeys: Set<string>;
+};
+//#endregion
+//#region src/helpers/nullishFields/nullishFields.d.ts
+/** Key used to wrap flat array elements when converting to form format */
+declare const flatArrayKey = "__FLAT__";
+/**
+ * Checks if a value is considered "empty" for validation display purposes.
+ *
+ * Used by useUniformField to determine when to show validation errors.
+ * Empty values don't trigger immediate error display (user must interact first).
+ *
+ * Handles:
+ * - Primitives: null, undefined, ''
+ * - Marker strings: __NULL__, __FALSE__, __ZERO__ (converted via fromNullishString)
+ * - Empty arrays: []
+ * - Objects with all empty values: {a: null, b: ''}
+ * - Flat array wrappers: {__FLAT__: null} or {__FLAT__: ''}
+ *
+ * @param value - The value to check (will be converted via fromNullishString first)
+ * @returns true if the value is empty
+ *
+ * @example
+ * isValueEmpty(null)                    // true
+ * isValueEmpty('')                      // true
+ * isValueEmpty('__NULL__')              // true (marker string)
+ * isValueEmpty([])                      // true (empty array)
+ * isValueEmpty({a: null})               // true (object with all empty values)
+ * isValueEmpty({__FLAT__: null})        // true (flat array wrapper with empty value)
+ * isValueEmpty({__FLAT__: ''})          // true
+ * isValueEmpty('hello')                 // false
+ * isValueEmpty([1, 2])                  // false
+ * isValueEmpty({a: 'value'})            // false
+ * isValueEmpty({__FLAT__: 'value'})     // false
+ */
+declare const isValueEmpty: (value: unknown) => boolean;
+/**
+ * Converts marker strings back to their original values when processing arrays
+ */
+declare const fromNullishString: (value: unknown) => unknown;
+/**
+ * Converts null/falsy values to marker strings for JSON processing
+ */
+declare const toNullishString: (value: unknown) => unknown;
+/**
+ * Converts field values to a format suitable for forms by:
+ * - Wrapping arrays of primitives as objects using the flatArrayKey `__FLAT__`
+ *   to satisfy RHF's requirement that array fields contain objects
+ * - Removing empty strings and null values from objects
+ *
+ * This conversion is required because React Hook Form does not support arrays with
+ * flat values (string, number, boolean, null). Array fields must contain objects.
+ * We work around this by wrapping primitive entries: `{ __FLAT__: <value> }`.
+ *
+ * @example
+ * const fields = {
+ *   name: 'John',
+ *   scores: [0, null, 75, false],
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     { score: null },
+ *     { score: 0 },
+ *     { score: false },
+ *     { score: '' },
+ *   ],
+ *   contact: {
+ *     email: '',
+ *     phone: null,
+ *     address: '123 Main St'
+ *   }
+ * };
+ *
+ * // Result:
+ * {
+ *   name: 'John',
+ *   scores: [
+ *     { __FLAT__: 0 },
+ *     { __FLAT__: null },
+ *     { __FLAT__: 75 },
+ *     { __FLAT__: false }
+ *   ],
+ *   // Arrays of objects are left as objects; empty/null properties are removed
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {}, // null score removed
+ *     { score: 0 },
+ *     { score: false },
+ *     {}, // empty string removed
+ *   ],
+ *   contact: {
+ *     address: '123 Main St'
+ *   }
+ * }
+ */
+declare const toFormFormat: (fields: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Converts form state to a format suitable for validation by:
+ * - Unwrapping flat array wrappers `{ __FLAT__: <value> }` back to primitives
+ * - Converting legacy string markers (__NULL__, __FALSE__, __ZERO__) back to their original values
+ * - Removing fields whose converted value is empty string or null
+ * - Removing empty arrays
+ *
+ * @example
+ * const formState = {
+ *   name: 'John',
+ *   scores: [
+ *     { __FLAT__: 75 },
+ *     { __FLAT__: 0 },
+ *     { __FLAT__: null },
+ *     { __FLAT__: false }
+ *   ],
+ *   emptyArray: [],
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {},
+ *     { score: 0 },
+ *     { score: false },
+ *     {},
+ *   ],
+ *   contact: {
+ *     address: '123 Main St',
+ *     fax: null
+ *   }
+ * };
+ *
+ * // Result:
+ * {
+ *   name: 'John',
+ *   scores: [75, 0, null, false],
+ *   // emptyArray is removed
+ *   // Objects inside arrays remain objects; empty entries remain empty objects
+ *   scoresDetailed: [
+ *     { score: 1 },
+ *     {},
+ *     { score: 0 },
+ *     { score: false },
+ *     {},
+ *   ],
+ *   contact: {
+ *     address: '123 Main St'
+ *   }
+ * }
+ */
+declare const toValidationFormat: (formState: Record<string, unknown> | null | undefined) => Record<string, unknown> | null | undefined;
+/**
+ * Converts form state to a format suitable for submission by:
+ * - Applying all transformations from toValidationFormat
+ * - Additionally removing empty objects from the result
+ * - Filtering empty objects from arrays
+ * - Recursively cleaning nested structures
+ *
+ * **Why separate from toValidationFormat?**
+ *
+ * Empty objects must be preserved during validation so that custom refinements
+ * can run. For example, a FieldCard with "at least email or phone required"
+ * validation needs the object to exist (even if empty) for the refine to execute.
+ *
+ * However, for submission, empty objects are meaningless and should be removed
+ * to produce clean data for APIs.
+ *
+ * @example
+ * const formState = {
+ *   name: 'John',
+ *   contact: {},           // Empty FieldCard - will be removed
+ *   tags: [{}, {}, {}],    // All empty - array will be removed
+ *   items: [
+ *     { value: 'a' },
+ *     {},                  // Empty entry - will be filtered out
+ *     { value: 'b' }
+ *   ],
+ *   nested: {
+ *     deep: {}             // Nested empty - will be removed recursively
+ *   }
+ * };
+ *
+ * // Result:
+ * {
+ *   name: 'John',
+ *   items: [{ value: 'a' }, { value: 'b' }]
+ * }
+ */
+declare const toSubmitFormat: (formState: Record<string, unknown> | null | undefined) => Record<string, unknown> | null | undefined;
+/**
+ * Converts a field name to a testId by removing flat array key segments and slugifying.
+ * Removes all occurrences of `flatArrayKey` from the field name and applies slugify transformation.
+ *
+ * This is used to generate stable testIds for form fields that don't include
+ * the internal `__FLAT__` marker used for flat arrays.
+ *
+ * @param name - The field name as a string (e.g., 'tags.0.__FLAT__') or array path (e.g., ['tags', '0', '__FLAT__'])
+ * @returns The slugified field name with all flat array key segments removed (e.g., 'tags_0')
+ *
+ * @example
+ * ```ts
+ * nameToTestId('tags.0.__FLAT__') // => 'tags_0'
+ * nameToTestId('array.0.__FLAT__') // => 'array_0'
+ * nameToTestId('nested.array.0.__FLAT__.field') // => 'nested_array_0_field'
+ * nameToTestId('simple.field') // => 'simple_field'
+ * nameToTestId(['tags', '0', '__FLAT__']) // => 'tags_0'
+ * ```
+ */
+declare const nameToTestId: (name: string | readonly string[]) => string;
+//#endregion
+export { toFormFormat as a, toValidationFormat as c, nameToTestId as i, createOptionValueConverter as l, fromNullishString as n, toNullishString as o, isValueEmpty as r, toSubmitFormat as s, flatArrayKey as t };
+//# sourceMappingURL=index-0zgyvkAF.d.cts.map

package/dist/index-0zgyvkAF.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-0zgyvkAF.d.cts","names":[],"sources":["../src/helpers/createOptionValueConverter/createOptionValueConverter.ts","../src/helpers/nullishFields/nullishFields.ts"],"mappings":";;AAeA;;;;;;;;;;;;cAAa,0BAAA;EACC,KAAA;AAAA,GAEZ,OAAA,EAAS,CAAA;;;;;;;;cCfE,YAAA;;;;;;;;;;;;;;;;;;;;;;;AAAb;;;;AAAyB;AAsCzB;;cAAa,YAAA,GAAgB,KAAc;;AAAA;AA0B3C;cAAa,iBAAA,GAAqB,KAAc;;;AAAA;cAsCnC,eAAA,GAAmB,KAAc;;;;AAAA;AA6E9C;;;;;;;;AAwB6C;AAmD7C;;;;;;;;AAES;AAuKT;;;;;;;;AAES;AA2BT;;;;AAA6D;;;;;;;;;;;;;;;cAjRhD,YAAA,GAAgB,MAAA,EAAQ,MAAA,sBAwBE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmDhC,kBAAA,GACX,SAAA,EAAW,MAAA,yCACV,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuKI,cAAA,GACX,SAAA,EAAW,MAAA,yCACV,MAAM;;;;;;;;;;;;;;;;;;;;cA2BI,YAAA,GAAgB,IAAgC"}

package/dist/{index-3ZtX9lF3.d.ts → index-3gVUFqgo.d.cts}

@@ -1,7 +1,5 @@
-import { t as TVReturnType } from "./index-1R5A9Hrq.js";
 import { TVClassName, TVProps } from "@fuf-stack/pixel-utils";
 import { CSSProperties, JSX, ReactNode } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/FieldArray/subcomponents/FieldArrayElement.d.ts
 interface FieldArrayElementMethods {
@@ -56,7 +54,7 @@ interface FieldArrayProps extends FieldArrayFeatures, VariantProps {
 }
 //#endregion
 //#region src/FieldArray/FieldArray.d.ts
-declare const fieldArrayVariants: TVReturnType<{
+declare const fieldArrayVariants: import("tailwind-variants").TVReturnType<{
   hasLabel: {
     false: {
       actionsMenuButton: string;
@@ -96,7 +94,7 @@ declare const fieldArrayVariants: TVReturnType<{
   listItemInner: string[]; /** class for the remove button */
   removeButton: string[]; /** class for the sort drag handle */
   sortDragHandle: string[];
-}, TVReturnType<{
+}, import("tailwind-variants").TVReturnType<{
   hasLabel: {
     false: {
       actionsMenuButton: string;
@@ -133,7 +131,7 @@ declare const FieldArray: ({
   name,
   sortable,
   ...uniformFieldProps
-}: FieldArrayProps) => _$react_jsx_runtime0.JSX.Element;
+}: FieldArrayProps) => import("react/jsx-runtime").JSX.Element;
 //#endregion
 export { FieldArrayProps as i, FieldArrayChildrenRenderFn as n, FieldArrayFeatures as r, FieldArray as t };
-//# sourceMappingURL=index-3ZtX9lF3.d.ts.map
+//# sourceMappingURL=index-3gVUFqgo.d.cts.map

package/dist/index-3gVUFqgo.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-3gVUFqgo.d.cts","names":[],"sources":["../src/FieldArray/subcomponents/FieldArrayElement.tsx","../src/FieldArray/types.ts","../src/FieldArray/FieldArray.tsx"],"mappings":";;;;UAiBiB,wBAAA;;EAEf,MAAA;EAFuC;EAIvC,SAAA;EAJuC;EAMvC,MAAA;EAFA;EAIA,MAAA;AAAA;;;KCpBG,YAAA,GAAe,OAAO,QAAQ,kBAAA;AAAA,KAC9B,SAAA,GAAY,WAAW,QAAQ,kBAAA;;KAGxB,0BAAA,IAA8B,IAAA;EDUxC,sDCRA,KAAA,UDYA;ECVA,MAAA,UDYM;ECVN,OAAA,EAAS,wBAAA;EAET,IAAA;EAEA,MAAA;AAAA,MACI,GAAA,CAAI,OAAO;AAAA,UAEA,kBAAA;EAjBG;EAmBlB,SAAA;EAlBG;EAoBH,WAAA;;EAEA,QAAA;AAAA;AAAA,UAGe,eAAA,SAAwB,kBAAA,EAAoB,YAAA;EAtBvB;EAwBpC,gBAAA;EAbe;EAef,QAAA,EAAU,0BAAA;EAtBV;EAwBA,SAAA,GAAY,SAAA;EAEZ,mBAAA;EAKA,mBAAA,GAAsB,aAAA;EAzBtB;EA2BA,IAAA;EA1BI;EA4BJ,KAAA,GAAQ,SAAA;EA5BO;EA8Bf,uBAAA;EA5Be;EA8Bf,IAAA;;EAEA,MAAA;AAAA;;;cCzCW,kBAAA,8BAAkB,YAAA;;;;;;;;;EFU7B,6DAEM;;;+BCpBS;mBAAG;kBACf;;sBAAiD;2BAGhB;0BAWrB;;;;;;;;;;;EAAA,6DAEkB;+BAAA;0BAIjC;+BAEQ;mBAGO;;yBAMH;sBAWJ;2BAjBmD;0BAAY;;;;;;;;;;;EAevE,6DAEQ;+BAIR;0BAEM;;;kBCiDN;yBAAA;;;;;;;;;cAKI,UAAA;EAAc,gBAAA;EAAA,QAAA;EAAA,SAAA,EAAA,UAAA;EAAA,SAAA;EAAA,mBAAA,EAAA,oBAAA;EAAA,mBAAA;EAAA,IAAA;EAAA,WAAA;EAAA,uBAAA;EAAA,IAAA;EAAA,QAAA;EAAA,GAAA;AAAA,GAajB,eAAA,iCAAe,GAAA,CAAA,OAAA"}

package/dist/{index-DVfzReu6.d.ts → index-65doPHAW.d.ts}

@@ -1,34 +1,33 @@
-import { n as ClassNameValue, t as TVReturnType } from "./index-1R5A9Hrq.js";
 import { TVClassName, TVProps } from "@fuf-stack/pixel-utils";
 import { ReactElement, ReactNode } from "react";
 
 //#region src/Radios/Radios.d.ts
-declare const radiosVariants: TVReturnType<{
+declare const radiosVariants: import("tailwind-variants").TVReturnType<{
   [key: string]: {
-    [key: string]: ClassNameValue | {
-      label?: ClassNameValue;
-      base?: ClassNameValue;
-      itemBase?: ClassNameValue;
-      itemControl?: ClassNameValue;
-      itemDescription?: ClassNameValue;
-      itemLabel?: ClassNameValue;
-      itemLabelWrapper?: ClassNameValue;
-      itemWrapper?: ClassNameValue;
-      wrapper?: ClassNameValue;
+    [key: string]: import("tailwind-merge").ClassNameValue | {
+      base?: import("tailwind-merge").ClassNameValue;
+      itemBase?: import("tailwind-merge").ClassNameValue;
+      itemControl?: import("tailwind-merge").ClassNameValue;
+      itemDescription?: import("tailwind-merge").ClassNameValue;
+      itemLabel?: import("tailwind-merge").ClassNameValue;
+      itemLabelWrapper?: import("tailwind-merge").ClassNameValue;
+      itemWrapper?: import("tailwind-merge").ClassNameValue;
+      label?: import("tailwind-merge").ClassNameValue;
+      wrapper?: import("tailwind-merge").ClassNameValue;
     };
   };
 } | {
   [x: string]: {
-    [x: string]: ClassNameValue | {
-      label?: ClassNameValue;
-      base?: ClassNameValue;
-      itemBase?: ClassNameValue;
-      itemControl?: ClassNameValue;
-      itemDescription?: ClassNameValue;
-      itemLabel?: ClassNameValue;
-      itemLabelWrapper?: ClassNameValue;
-      itemWrapper?: ClassNameValue;
-      wrapper?: ClassNameValue;
+    [x: string]: import("tailwind-merge").ClassNameValue | {
+      base?: import("tailwind-merge").ClassNameValue;
+      itemBase?: import("tailwind-merge").ClassNameValue;
+      itemControl?: import("tailwind-merge").ClassNameValue;
+      itemDescription?: import("tailwind-merge").ClassNameValue;
+      itemLabel?: import("tailwind-merge").ClassNameValue;
+      itemLabelWrapper?: import("tailwind-merge").ClassNameValue;
+      itemWrapper?: import("tailwind-merge").ClassNameValue;
+      label?: import("tailwind-merge").ClassNameValue;
+      wrapper?: import("tailwind-merge").ClassNameValue;
     };
   };
 } | {}, {
@@ -43,16 +42,16 @@ declare const radiosVariants: TVReturnType<{
   wrapper: string;
 }, undefined, {
   [key: string]: {
-    [key: string]: ClassNameValue | {
-      label?: ClassNameValue;
-      base?: ClassNameValue;
-      itemBase?: ClassNameValue;
-      itemControl?: ClassNameValue;
-      itemDescription?: ClassNameValue;
-      itemLabel?: ClassNameValue;
-      itemLabelWrapper?: ClassNameValue;
-      itemWrapper?: ClassNameValue;
-      wrapper?: ClassNameValue;
+    [key: string]: import("tailwind-merge").ClassNameValue | {
+      base?: import("tailwind-merge").ClassNameValue;
+      itemBase?: import("tailwind-merge").ClassNameValue;
+      itemControl?: import("tailwind-merge").ClassNameValue;
+      itemDescription?: import("tailwind-merge").ClassNameValue;
+      itemLabel?: import("tailwind-merge").ClassNameValue;
+      itemLabelWrapper?: import("tailwind-merge").ClassNameValue;
+      itemWrapper?: import("tailwind-merge").ClassNameValue;
+      label?: import("tailwind-merge").ClassNameValue;
+      wrapper?: import("tailwind-merge").ClassNameValue;
     };
   };
 } | {}, {
@@ -65,7 +64,7 @@ declare const radiosVariants: TVReturnType<{
   itemWrapper: string;
   label: string;
   wrapper: string;
-}, TVReturnType<unknown, {
+}, import("tailwind-variants").TVReturnType<unknown, {
   base: string;
   itemBase: string;
   itemControl: string;
@@ -120,4 +119,4 @@ declare const Radios: ({
 }: RadiosProps) => ReactElement;
 //#endregion
 export { RadiosProps as n, Radios as t };
-//# sourceMappingURL=index-DVfzReu6.d.ts.map
+//# sourceMappingURL=index-65doPHAW.d.ts.map

package/dist/index-65doPHAW.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-65doPHAW.d.ts","names":[],"sources":["../src/Radios/Radios.tsx"],"mappings":";;;;cAaa,cAAA,8BAAc,YAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkBtB,YAAA,GAAe,OAAO,QAAQ,cAAA;AAAA,KAC9B,SAAA,GAAY,WAAW,QAAQ,cAAA;AAAA,UAEnB,WAAA;;EAEf,QAAA;;EAEA,KAAA,GAAQ,SAAA;;EAER,IAAA,GAAO,SAAS;;EAEhB,MAAA;;EAEA,KAAA;AAAA;AAAA,UAGe,WAAA,SAAoB,YAAA;;EAEnC,SAAA;;EAEA,SAAA,GAAY,SAAA;;EAEZ,QAAA;;EAEA,MAAA;;EAEA,KAAA,GAAQ,SAAA;;EAER,IAAA;EA5BG;EA8BH,OAAA,EAAS,WAAA;;EAET,MAAA;AAAA;AAhC+C;;;AAAA,cAsC3C,MAAA;EAAU,SAAA;EAAA,MAAA;EAAA,IAAA;EAAA,OAAA;EAAA,GAAA;AAAA,GAMb,WAAA,KAAc,YAAA"}

package/dist/{index-BA6KNK9V.d.cts → index-B682jKQ_.d.ts}

@@ -1,32 +1,30 @@
-import { n as ClassNameValue, t as TVReturnType } from "./index-CgqESs42.cjs";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { TVClassName, TVProps } from "@fuf-stack/pixel-utils";
 import { ReactNode } from "react";
 //#region src/RadioBoxes/RadioBoxes.d.ts
-declare const radioBoxesVariants: TVReturnType<{
+declare const radioBoxesVariants: import("tailwind-variants").TVReturnType<{
   [key: string]: {
-    [key: string]: ClassNameValue | {
-      label?: ClassNameValue;
-      base?: ClassNameValue;
-      wrapper?: ClassNameValue;
-      boxBase?: ClassNameValue;
-      boxControl?: ClassNameValue;
-      boxDescription?: ClassNameValue;
-      boxLabel?: ClassNameValue;
-      boxLabelWrapper?: ClassNameValue;
+    [key: string]: import("tailwind-merge").ClassNameValue | {
+      base?: import("tailwind-merge").ClassNameValue;
+      label?: import("tailwind-merge").ClassNameValue;
+      wrapper?: import("tailwind-merge").ClassNameValue;
+      boxBase?: import("tailwind-merge").ClassNameValue;
+      boxControl?: import("tailwind-merge").ClassNameValue;
+      boxDescription?: import("tailwind-merge").ClassNameValue;
+      boxLabel?: import("tailwind-merge").ClassNameValue;
+      boxLabelWrapper?: import("tailwind-merge").ClassNameValue;
     };
   };
 } | {
   [x: string]: {
-    [x: string]: ClassNameValue | {
-      label?: ClassNameValue;
-      base?: ClassNameValue;
-      wrapper?: ClassNameValue;
-      boxBase?: ClassNameValue;
-      boxControl?: ClassNameValue;
-      boxDescription?: ClassNameValue;
-      boxLabel?: ClassNameValue;
-      boxLabelWrapper?: ClassNameValue;
+    [x: string]: import("tailwind-merge").ClassNameValue | {
+      base?: import("tailwind-merge").ClassNameValue;
+      label?: import("tailwind-merge").ClassNameValue;
+      wrapper?: import("tailwind-merge").ClassNameValue;
+      boxBase?: import("tailwind-merge").ClassNameValue;
+      boxControl?: import("tailwind-merge").ClassNameValue;
+      boxDescription?: import("tailwind-merge").ClassNameValue;
+      boxLabel?: import("tailwind-merge").ClassNameValue;
+      boxLabelWrapper?: import("tailwind-merge").ClassNameValue;
     };
   };
 } | {}, {
@@ -40,15 +38,15 @@ declare const radioBoxesVariants: TVReturnType<{
   wrapper: string;
 }, undefined, {
   [key: string]: {
-    [key: string]: ClassNameValue | {
-      label?: ClassNameValue;
-      base?: ClassNameValue;
-      wrapper?: ClassNameValue;
-      boxBase?: ClassNameValue;
-      boxControl?: ClassNameValue;
-      boxDescription?: ClassNameValue;
-      boxLabel?: ClassNameValue;
-      boxLabelWrapper?: ClassNameValue;
+    [key: string]: import("tailwind-merge").ClassNameValue | {
+      base?: import("tailwind-merge").ClassNameValue;
+      label?: import("tailwind-merge").ClassNameValue;
+      wrapper?: import("tailwind-merge").ClassNameValue;
+      boxBase?: import("tailwind-merge").ClassNameValue;
+      boxControl?: import("tailwind-merge").ClassNameValue;
+      boxDescription?: import("tailwind-merge").ClassNameValue;
+      boxLabel?: import("tailwind-merge").ClassNameValue;
+      boxLabelWrapper?: import("tailwind-merge").ClassNameValue;
     };
   };
 } | {}, {
@@ -60,7 +58,7 @@ declare const radioBoxesVariants: TVReturnType<{
   boxLabelWrapper: string;
   label: string;
   wrapper: string;
-}, TVReturnType<unknown, {
+}, import("tailwind-variants").TVReturnType<unknown, {
   base: string;
   boxBase: string;
   boxControl: string;
@@ -113,10 +111,10 @@ declare const RadioBoxes: ({
   name,
   options,
   ...uniformFieldProps
-}: RadioBoxesProps) => _$react_jsx_runtime0.JSX.Element;
+}: RadioBoxesProps) => import("react/jsx-runtime").JSX.Element;
 //#endregion
 //#region src/RadioBoxes/RadioBox.d.ts
-declare const radioBoxVariants: TVReturnType<{
+declare const radioBoxVariants: import("tailwind-variants").TVReturnType<{
   isDisabled: {
     true: {
       base: string;
@@ -152,7 +150,7 @@ declare const radioBoxVariants: TVReturnType<{
   icon: string;
   label: string;
   labelWrapper: string;
-}, TVReturnType<{
+}, import("tailwind-variants").TVReturnType<{
   isDisabled: {
     true: {
       base: string;
@@ -173,4 +171,4 @@ declare const radioBoxVariants: TVReturnType<{
 }, undefined, unknown, unknown, undefined>>;
 //#endregion
 export { RadioBoxes as n, RadioBoxesProps as r, radioBoxVariants as t };
-//# sourceMappingURL=index-BA6KNK9V.d.cts.map
+//# sourceMappingURL=index-B682jKQ_.d.ts.map

package/dist/index-B682jKQ_.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-B682jKQ_.d.ts","names":[],"sources":["../src/RadioBoxes/RadioBoxes.tsx","../src/RadioBoxes/RadioBox.tsx"],"mappings":";;;cAaa,kBAAA,8BAAkB,YAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgB1B,YAAA,GAAe,OAAO,QAAQ,kBAAA;AAAA,KAC9B,SAAA,GAAY,WAAW,QAAQ,kBAAA;AAAA,UAEnB,gBAAA;;EAEf,WAAA,GAAc,SAAA;;EAEd,QAAA;;EAEA,KAAA,GAAQ,SAAA;;EAER,IAAA,GAAO,SAAA;;EAEP,MAAA;;EAEA,KAAA;AAAA;AAAA,UAGe,eAAA,SAAwB,YAAA;;EAEvC,SAAA;;EAEA,SAAA,GAAY,SAAA;;EAEZ,QAAA;;EAEA,MAAA;EA1BG;EA4BH,KAAA,GAAQ,SAAA;;EAER,IAAA;EA9BmD;EAgCnD,OAAA,EAAS,gBAAA;EA/BG;EAiCZ,MAAA;AAAA;AAjCoD;AAEtD;;AAFsD,cAuChD,UAAA;EAAc,SAAA;EAAA,MAAA;EAAA,IAAA;EAAA,OAAA;EAAA,GAAA;AAAA,GAMjB,eAAA,iCAAe,GAAA,CAAA,OAAA;;;cClEL,gBAAA,8BAAgB,YAAA"}

package/dist/{index-Dj3NDj0T.d.ts → index-BFpoR6oH.d.ts}

@@ -1,6 +1,5 @@
-import { t as DebugModeSettings } from "./FormContext-B4KQxdl7.js";
+import { t as DebugModeSettings } from "./FormContext-DjXw7wN6.js";
 import { ReactNode } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { FieldValues, SubmitHandler } from "react-hook-form";
 import { VetoInstance } from "@fuf-stack/veto";
 
@@ -38,7 +37,7 @@ declare const Form: ({
   testId,
   validation,
   validationTrigger
-}: FormProps) => _$react_jsx_runtime0.JSX.Element;
+}: FormProps) => import("react/jsx-runtime").JSX.Element;
 //#endregion
 export { FormProps as n, Form as t };
-//# sourceMappingURL=index-Dj3NDj0T.d.ts.map
+//# sourceMappingURL=index-BFpoR6oH.d.ts.map

package/dist/index-BFpoR6oH.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-BFpoR6oH.d.ts","names":[],"sources":["../src/Form/Form.tsx"],"mappings":";;;;;;UAYiB,SAAA;;EAEf,QAAA,EAAU,SAAA,GAAY,SAAA;EAFE;EAIxB,SAAA;EAFU;EAIV,KAAA,GAAQ,iBAAA;EAAA;EAER,aAAA,GAAgB,WAAA;EAIQ;EAFxB,IAAA;EAMa;EAJb,QAAA,EAAU,aAAA,CAAc,WAAA;EAIC;EAFzB,MAAA;EAZU;EAcV,UAAA,GAAa,YAAA;EAZb;EAcA,iBAAA;AAAA;;;;cAMI,IAAA;EAAQ,QAAA;EAAA,SAAA;EAAA,KAAA;EAAA,aAAA;EAAA,IAAA;EAAA,QAAA;EAAA,MAAA;EAAA,UAAA;EAAA;AAAA,GAUX,SAAA,iCAAS,GAAA,CAAA,OAAA"}