@teamnovu/kit-vue-forms 0.2.18 → 0.3.0

package/dist/types/form.d.ts

@@ -18,6 +18,13 @@ export interface FieldItem<Item, Path extends string> {
 export interface FieldArray<Item, Path extends string> {
     items: ShallowRef<FieldItem<Item, Path>[]>;
     push: (item: Item) => FieldItem<Item, Path>;
+    /**
+     * Pushes a new item and anchors its subtree as the baseline for that index
+     * (subtree-scoped `setInitialData`). The new item's subfields are clean from
+     * the moment they're registered, while the array field itself stays dirty
+     * because its baseline still reflects the external `initialData`.
+     */
+    pushPristine: (item: Item) => FieldItem<Item, Path>;
     remove: (id: string) => void;
     insert: (item: Item, index: number) => FieldItem<Item, Path>;
     field: FormField<Item[], Path>;
@@ -33,8 +40,15 @@ export interface FormField<T, P extends string> {
     /**
      * Sets the initial data for the field. If the field is not dirty, it also updates the current data.
      * @param newData - The new initial data to set.
+     * @param options - Optional. Pass `{ replace: true }` to replace the subtree entirely instead of deep-merging.
+     *   Pass `{ scope: 'subtree' }` to anchor the baseline only for this field and its descendants — ancestors
+     *   continue to read from the external initialData and stay dirty if the override changed the tree shape.
+     *   Defaults to `{ scope: 'tree' }`, which makes the override visible to ancestors as well.
      */
-    setInitialData: (newData: T) => void;
+    setInitialData: (newData: T, options?: {
+        replace?: boolean;
+        scope?: 'tree' | 'subtree';
+    }) => void;
     onBlur: () => void;
     onFocus: () => void;
     reset: () => void;

package/dist/utils/path.d.ts

@@ -10,5 +10,6 @@ export declare function setNestedValue<T, K extends Paths<T>>(obj: MaybeRef<T>,
 export declare const getLens: <T, K extends Paths<T>>(data: MaybeRef<T>, key: MaybeRef<K | SplitPath<K>>) => WritableComputedRef<PickProps<T, K>, PickProps<T, K>>;
 type JoinPath<Base extends string, Sub extends string> = `${Base}${Base extends '' ? '' : Sub extends '' ? '' : '.'}${Sub}`;
 export declare function joinPath<Base extends string, Sub extends string>(basePath: Base, subPath: Sub): JoinPath<Base, Sub>;
+export declare function dropOverridesAtAndBelow(overrides: Map<string, unknown>, path: string): void;
 export declare function filterErrorsForPath(errors: ErrorBag, path: string): ErrorBag;
 export {};

package/docs/reference.md

@@ -130,6 +130,56 @@ setInitialData(fetchedData.firstName)
 // If the field wasn't dirty, the current data is also updated
 ```
 
+### Calling `setInitialData` on a parent path
+Overrides set on a parent path propagate down to its subfields. The default behavior is a **deep merge** with the underlying `initialData`, so subfields that are not mentioned in the override fall through to the external value:
+
+```typescript
+const form = useForm({
+  initialData: { user: { name: 'A', email: 'x@x' } },
+})
+
+form.getField('user').setInitialData({ name: 'B' })
+
+form.getField('user.name').initialValue.value  // 'B'      (from override)
+form.getField('user.email').initialValue.value // 'x@x'    (from external)
+form.getField('user.name').dirty.value         // false
+```
+
+Pass `{ replace: true }` as the second argument to replace the subtree wholesale instead of merging — keys missing from the override resolve to `undefined`:
+
+```typescript
+form.getField('user').setInitialData({ name: 'B' }, { replace: true })
+
+form.getField('user.email').initialValue.value // undefined
+```
+
+### Scoping the override: `tree` (default) vs `subtree`
+`setInitialData` accepts a `scope` option that controls who sees the new baseline:
+
+- **`scope: 'tree'` (default)** — the override becomes part of the global baseline. Both the targeted path *and its ancestors* read it, so the form goes back to non-dirty if `data` matches. Use this when an async load gives you a value that should be treated as if it had been the original initial all along.
+- **`scope: 'subtree'`** — the override anchors the baseline only for the targeted path and its descendants. Strict ancestors keep reading the external `initialData`, so they stay dirty when the change altered the tree shape (e.g. a new array item). Use this when something was added that the user should still be warned about losing on navigation, but whose internal fields shouldn't be marked dirty from the get-go.
+
+```typescript
+const form = useForm({
+  initialData: { rows: [{ name: 'A' }] as { name: string }[] },
+})
+
+// Push a new row (array structure changes → form is dirty)
+form.data.value.rows.push({ name: 'new' })
+
+// Anchor the new row's subtree as its own baseline.
+form.getField('rows.1').setInitialData({ name: 'new' }, { scope: 'subtree' })
+
+form.getField('rows.1.name').dirty.value // false (reads the anchor)
+form.getField('rows').dirty.value         // true  (array baseline unchanged)
+form.isDirty.value                        // true
+```
+
+### Interaction with external `initialData` and other overrides
+- **External reassignment wipes overrides.** When the `initialData` ref passed to `useForm` is reassigned, all overrides applied via `setInitialData` are dropped — the form's baseline goes back to the external source.
+- **Cascade on ancestor write.** Calling `setInitialData` on a path drops any existing override on that path *or below* before applying the new one (e.g. setting an override on `user` clears a prior override on `user.name`).
+- **`form.reset()` keeps overrides.** Reset rebuilds `data` from the merged tree (external `initialData` + active overrides), so a `setInitialData` call is treated as the new programmatic baseline.
+
 ## Method `defineValidator`
 The `defineValidator` method allows subcomponents to add validation rules to a form without needing access to the initial `useForm` call. The validator is automatically removed when the component unmounts.
 
@@ -197,6 +247,21 @@ hobbies.remove(hobbies.items.value[0].id)
 </div>
 ```
 
+### `pushPristine` — add a new item without dirtying its subfields
+`pushPristine(item)` works like `push`, but additionally anchors the new index's subtree as its own baseline (a `setInitialData(item, { scope: 'subtree' })` on the new index path). The new item's subfields start non-dirty, while the array field itself stays dirty — its baseline still reflects the external `initialData`, so navigation guards / dirty checks still warn that something was added.
+
+```typescript
+const rows = form.getFieldArray('rows')
+
+rows.pushPristine({ name: '', email: '' })
+
+form.getField('rows.1.name').dirty.value // false (reads the subtree anchor)
+rows.field.dirty.value                   // true  (a new row exists)
+form.isDirty.value                       // true
+```
+
+Use `push` when the new item is a user edit you want flagged everywhere; use `pushPristine` when it's a blank/placeholder row whose internal fields shouldn't light up dirty/validation noise until the user actually touches them.
+
 For objects where identity should be based on a property (e.g. `id`) rather than reference equality, provide a `hashFn`:
 ```typescript
 const products = form.getFieldArray('products', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamnovu/kit-vue-forms",
-  "version": "0.2.18",
+  "version": "0.3.0",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/composables/useField.ts

@@ -1,5 +1,5 @@
 import type { Awaitable } from '@vueuse/core'
-import { computed, reactive, shallowRef, toRefs, unref, watch, type MaybeRef, type MaybeRefOrGetter, type Ref } from 'vue'
+import { computed, reactive, toRefs, unref, watch, type MaybeRef, type MaybeRefOrGetter, type Ref } from 'vue'
 import type { FormField } from '../types/form'
 import type { ValidationErrorMessage, ValidationErrors } from '../types/validation'
 import { cloneRefValue } from '../utils/general'
@@ -24,33 +24,20 @@ export function useField<T, K extends string>(fieldOptions: UseFieldOptions<T, K
     ...defaultOptions,
     ...fieldOptions,
   }
-  const initialValue = shallowRef(Object.freeze(cloneRefValue(options.initialValue))) as Ref<Readonly<T | undefined>>
-
   const state = reactive({
     value: options.value,
     path: options.path,
-    initialValue,
+    initialValue: options.initialValue,
     errors: options.errors,
     touched: false,
   })
 
-  watch(
-    shallowRef(options.initialValue),
-    () => {
-      initialValue.value = Object.freeze(cloneRefValue(options.initialValue))
-      if (state.value !== unref(options.initialValue)) {
-        state.value = cloneRefValue(options.initialValue)
-      }
-    },
-    { flush: 'sync' },
-  )
-
   watch(() => state.value, (newData) => {
     fieldOptions.onChange?.(newData as T)
   }, { deep: true })
 
   const dirty = computed(() => {
-    return JSON.stringify(state.value) !== JSON.stringify(state.initialValue)
+    return JSON.stringify(state.value) !== JSON.stringify(cloneRefValue(state.initialValue as T))
   })
 
   const setData = (newData: T): void => {
@@ -71,17 +58,21 @@ export function useField<T, K extends string>(fieldOptions: UseFieldOptions<T, K
   const reset = (): void => {
     const lastPathPart = state.path.split('.').at(-1) || ''
     if (unref(options.existsInForm) && !/^\d+$/.test(lastPathPart)) {
-      state.value = cloneRefValue(state.initialValue)
+      state.value = cloneRefValue(state.initialValue as T)
     }
     state.touched = false
     state.errors = []
   }
 
-  const setInitialData = (newData: T): void => {
+  // This method is replaced by the registry and should never be called directly.
+  // This only acts as a stub.
+  const setInitialData = (newData: T, _options?: { replace?: boolean }): void => {
     if (!dirty.value) {
       setData(cloneRefValue(newData))
     }
-    state.initialValue = newData
+    // Standalone-mode fallback: when no registry has replaced this method, keep
+    // the previous behavior of updating the local baseline directly.
+    state.initialValue = newData as typeof state.initialValue
   }
 
   const setErrors = (newErrors: ValidationErrorMessage[]): void => {

package/src/composables/useFieldArray.ts

@@ -132,6 +132,21 @@ export function useFieldArray<T extends FormDataDefault, K extends Paths<T>, TOu
     return items.value.at(-1)!
   }
 
+  const pushPristine = (item: Item) => {
+    const current = (arrayField.data.value ?? []) as Item[]
+    const newIndex = current.length
+    arrayField.setData([...current, item] as Items)
+
+    // Anchor the new item's subtree as its own baseline. Subtree scope keeps
+    // the array field (and any further ancestors) dirty against the external
+    // initialData, while the new index and its descendants read the anchor.
+    const newItemPath = `${path}.${newIndex}` as Paths<T>
+    const newItemField = form.getField(newItemPath) as unknown as FormField<Item, string>
+    newItemField.setInitialData(item, { scope: 'subtree' })
+
+    return items.value.at(-1)!
+  }
+
   const remove = (id: Id) => {
     const currentData = (arrayField.data.value ?? []) as Item[]
     const currentItem = items.value.findIndex(
@@ -165,6 +180,7 @@ export function useFieldArray<T extends FormDataDefault, K extends Paths<T>, TOu
   return {
     items,
     push,
+    pushPristine,
     remove,
     insert,
     field: arrayField,

package/src/composables/useFieldRegistry.ts

@@ -12,9 +12,14 @@ import {
 } from 'vue'
 import type { FieldsTuple, FormDataDefault, FormField } from '../types/form'
 import type { Paths, PickProps } from '../types/util'
-import { existsPath, getLens, getNestedValue } from '../utils/path'
+import { cloneRefValue } from '../utils/general'
+import { existsPath, getLens } from '../utils/path'
 import { Rc } from '../utils/rc'
 import { useField, type UseFieldOptions } from './useField'
+import type {
+  InitialDataOverride,
+  InitialDataOverrideSetOptions,
+} from './useInitialDataOverride'
 import type { ValidationState } from './useValidation'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -56,17 +61,18 @@ const optionDefaults = {
 
 // A computed that always reflects the latest value from the getter
 // This computed forces updates even if the value is the same (to trigger watchers)
-function initialDataSync<T extends FormDataDefault>(
-  formState: FormState<T>,
-  path: Paths<T>,
+function initialDataSync<T extends FormDataDefault, K extends Paths<T>>(
+  initialDataOverride: InitialDataOverride<T>,
+  path: K,
 ) {
-  const getNewValue = () => getNestedValue(formState.initialData, path)
-  const initialValueRef = shallowRef(getNewValue())
+  type FieldValue = PickProps<T, K>
+  const getNewValue = () => initialDataOverride.resolveAt(path) as FieldValue
+  const initialValueRef = shallowRef<FieldValue>(getNewValue())
 
   watch(
-    () => formState.initialData,
-    () => {
-      initialValueRef.value = getNewValue()
+    () => initialDataOverride.resolveAt(path),
+    (newValue) => {
+      initialValueRef.value = newValue as FieldValue
       triggerRef(initialValueRef)
     },
     { flush: 'sync' },
@@ -78,6 +84,7 @@ function initialDataSync<T extends FormDataDefault>(
 export function useFieldRegistry<T extends FormDataDefault, TOut = T>(
   formState: FormState<T>,
   validationState: ValidationState<T, TOut>,
+  initialDataOverride: InitialDataOverride<T>,
   fieldRegistryOptions?: FieldRegistryOptions,
 ) {
   const fieldReferenceCounter = new Map<Paths<T>, Rc>()
@@ -124,7 +131,7 @@ export function useFieldRegistry<T extends FormDataDefault, TOut = T>(
       const field = useField({
         path,
         value: getLens(toRef(formState, 'data'), path),
-        initialValue: initialDataSync(formState, path),
+        initialValue: initialDataSync(initialDataOverride, path),
         existsInForm: computed(() => existsPath(formState.data, unref(path))),
         errors: computed({
           get() {
@@ -154,6 +161,22 @@ export function useFieldRegistry<T extends FormDataDefault, TOut = T>(
         },
       })
 
+      // Replace setInitialData with a registry-provided version that writes to
+      // the override layer so subfields resolve their baseline from the merged
+      // tree.
+      field.setInitialData = (
+        newData: PickProps<T, K>,
+        setOptions?: InitialDataOverrideSetOptions,
+      ) => {
+        // Capture dirty state before the override write, since writing to the
+        // override layer synchronously updates this field's initialValue.
+        const wasDirty = field.dirty.value
+        initialDataOverride.set(path, newData, setOptions)
+        if (!wasDirty) {
+          field.setData(cloneRefValue(newData))
+        }
+      }
+
       registerField(field)
     }
 

package/src/composables/useForm.ts

@@ -15,6 +15,7 @@ import { makeSubmitHandler } from '../utils/submitHandler'
 import { useFieldArray } from './useFieldArray'
 import { useFieldRegistry } from './useFieldRegistry'
 import { useFormState } from './useFormState'
+import { useInitialDataOverride } from './useInitialDataOverride'
 import { createSubformInterface } from './useSubform'
 import {
   useValidation,
@@ -60,6 +61,7 @@ export function useForm<T extends FormDataDefault, TOut = T>(
 
   /* eslint-enable no-redeclare */
   const initialData = computed(() => cloneRefValue(options.initialData))
+  const initialDataOverride = useInitialDataOverride(initialData)
 
   const data = ref<T>(cloneRefValue(initialData)) as Ref<T>
 
@@ -77,7 +79,7 @@ export function useForm<T extends FormDataDefault, TOut = T>(
   )
 
   const validationState = useValidation(state, options)
-  const fieldRegistry = useFieldRegistry(state, validationState, {
+  const fieldRegistry = useFieldRegistry(state, validationState, initialDataOverride, {
     keepValuesOnUnmount: options.keepValuesOnUnmount,
     onBlur: async (path: string) => {
       validationState.validateStrategy('validateOnBlur', path)
@@ -92,7 +94,7 @@ export function useForm<T extends FormDataDefault, TOut = T>(
   const formState = useFormState(fieldRegistry)
 
   const reset = () => {
-    data.value = cloneRefValue(initialData)
+    data.value = cloneRefValue(initialDataOverride.effectiveInitialData)
     validationState.reset()
     for (const field of fieldRegistry.fields.value) {
       field.reset()

package/src/composables/useInitialDataOverride.ts

@@ -0,0 +1,130 @@
+import { merge } from 'lodash-es'
+import {
+  computed,
+  shallowReactive,
+  watch,
+  type ComputedRef,
+  type Ref,
+} from 'vue'
+import type { FormDataDefault } from '../types/form'
+import type { Paths, PickProps } from '../types/util'
+import { cloneRefValue } from '../utils/general'
+import {
+  dropOverridesAtAndBelow,
+  getNestedValue,
+  setNestedValue,
+} from '../utils/path'
+
+export type InitialDataOverrideScope = 'tree' | 'subtree'
+
+export interface InitialDataOverrideSetOptions {
+  replace?: boolean
+  scope?: InitialDataOverrideScope
+}
+
+export interface InitialDataOverride<T extends FormDataDefault> {
+  // Full merge of external initialData with all overrides regardless of scope.
+  // Used by form.reset() to rebuild the data tree.
+  effectiveInitialData: ComputedRef<T>
+  // Per-field baseline resolution. Honors scope: subtree-scoped overrides at
+  // paths strictly below `path` are invisible to that read, so ancestors keep
+  // their external baseline and stay dirty when descendants extend the tree.
+  resolveAt: (path: string) => unknown
+  set: (
+    path: string,
+    value: unknown,
+    options?: InitialDataOverrideSetOptions,
+  ) => void
+}
+
+interface OverrideEntry {
+  value: unknown
+  replace: boolean
+  scope: InitialDataOverrideScope
+}
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> => {
+  if (v === null || typeof v !== 'object') return false
+  const proto = Object.getPrototypeOf(v)
+  // Only treat literal `{}` / `Object.create(null)` as mergeable. Class
+  // instances, Date, Map, Set, RegExp, etc. have no enumerable own props for
+  // lodash.merge to copy and would silently collapse to `{}`.
+  return proto === Object.prototype || proto === null
+}
+
+const isStrictDescendant = (candidate: string, ancestor: string): boolean => {
+  if (ancestor === '') return candidate !== ''
+  return candidate.startsWith(ancestor + '.')
+}
+
+export function useInitialDataOverride<T extends FormDataDefault>(
+  initialData: Ref<T> | ComputedRef<T>,
+): InitialDataOverride<T> {
+  const overrides = shallowReactive(new Map<string, OverrideEntry>())
+
+  const buildTree = (readingPath?: string): T => {
+    const result = cloneRefValue(initialData)
+    const sortedEntries = [...overrides.entries()].sort(
+      ([a], [b]) => a.split('.').length - b.split('.').length,
+    )
+
+    for (const [path, entry] of sortedEntries) {
+      // For a per-field read, skip subtree-scoped overrides that live strictly
+      // below the reading path — those anchors must remain invisible to
+      // ancestors of their own subtree.
+      if (
+        readingPath !== undefined
+        && entry.scope === 'subtree'
+        && isStrictDescendant(path, readingPath)
+      ) {
+        continue
+      }
+
+      const typedPath = path as Paths<T>
+      const existing = getNestedValue<T, Paths<T>>(result, typedPath)
+
+      const nextValue = entry.replace || !isPlainObject(entry.value) || !isPlainObject(existing)
+        ? entry.value
+        : merge({}, existing, entry.value)
+
+      setNestedValue<T, Paths<T>>(
+        result,
+        typedPath,
+        nextValue as PickProps<T, Paths<T>>,
+      )
+    }
+
+    return result
+  }
+
+  const effectiveInitialData = computed<T>(() => buildTree())
+
+  const resolveAt = (path: string): unknown => {
+    const tree = buildTree(path)
+    if (path === '') return tree
+    return getNestedValue<T, Paths<T>>(tree, path as Paths<T>)
+  }
+
+  // External initialData reassignment wipes all overrides. Programmatic
+  // overrides via setInitialData stay scoped to their own subtrees.
+  watch(
+    initialData,
+    () => {
+      overrides.clear()
+    },
+    { flush: 'sync' },
+  )
+
+  return {
+    effectiveInitialData,
+    resolveAt,
+    set(path, value, options) {
+      dropOverridesAtAndBelow(overrides, path)
+      overrides.set(path, {
+        value,
+        replace: options?.replace ?? false,
+        scope: options?.scope ?? 'tree',
+      })
+    },
+  }
+}

package/src/types/form.ts

@@ -29,6 +29,13 @@ export interface FieldItem<Item, Path extends string> {
 export interface FieldArray<Item, Path extends string> {
   items: ShallowRef<FieldItem<Item, Path>[]>
   push: (item: Item) => FieldItem<Item, Path>
+  /**
+   * Pushes a new item and anchors its subtree as the baseline for that index
+   * (subtree-scoped `setInitialData`). The new item's subfields are clean from
+   * the moment they're registered, while the array field itself stays dirty
+   * because its baseline still reflects the external `initialData`.
+   */
+  pushPristine: (item: Item) => FieldItem<Item, Path>
   remove: (id: string) => void
   insert: (item: Item, index: number) => FieldItem<Item, Path>
   field: FormField<Item[], Path>
@@ -45,8 +52,18 @@ export interface FormField<T, P extends string> {
   /**
    * Sets the initial data for the field. If the field is not dirty, it also updates the current data.
    * @param newData - The new initial data to set.
+   * @param options - Optional. Pass `{ replace: true }` to replace the subtree entirely instead of deep-merging.
+   *   Pass `{ scope: 'subtree' }` to anchor the baseline only for this field and its descendants — ancestors
+   *   continue to read from the external initialData and stay dirty if the override changed the tree shape.
+   *   Defaults to `{ scope: 'tree' }`, which makes the override visible to ancestors as well.
    */
-  setInitialData: (newData: T) => void
+  setInitialData: (
+    newData: T,
+    options?: {
+      replace?: boolean
+      scope?: 'tree' | 'subtree'
+    },
+  ) => void
   onBlur: () => void
   onFocus: () => void
   reset: () => void

package/src/utils/path.ts

@@ -103,6 +103,17 @@ export function joinPath<Base extends string, Sub extends string>(
   return `${basePath}.${subPath}` as JoinPath<Base, Sub>
 }
 
+export function dropOverridesAtAndBelow(
+  overrides: Map<string, unknown>,
+  path: string,
+): void {
+  for (const key of [...overrides.keys()]) {
+    if (key === path || path === '' || key.startsWith(path + '.')) {
+      overrides.delete(key)
+    }
+  }
+}
+
 export function filterErrorsForPath(errors: ErrorBag, path: string): ErrorBag {
   // Handle empty path - return all errors
   if (!path) {

package/tests/formState.test.ts

@@ -1,8 +1,9 @@
 import { describe, expect, it } from 'vitest'
-import { reactive } from 'vue'
+import { reactive, toRef } from 'vue'
 import { useFieldRegistry } from '../src/composables/useFieldRegistry'
 import { useFormState } from '../src/composables/useFormState'
 import { useForm } from '../src'
+import { useInitialDataOverride } from '../src/composables/useInitialDataOverride'
 import { useValidation } from '../src/composables/useValidation'
 
 describe('useFormState', () => {
@@ -51,7 +52,8 @@ describe('useFormState', () => {
       initialData,
     })
     const validationState = useValidation(state, {})
-    const fields = useFieldRegistry(state, validationState)
+    const initialDataOverride = useInitialDataOverride(toRef(state, 'initialData'))
+    const fields = useFieldRegistry(state, validationState, initialDataOverride)
 
     const nameField = fields.defineField({ path: 'name' })
     fields.defineField({ path: 'email' })
@@ -74,7 +76,8 @@ describe('useFormState', () => {
       initialData,
     })
     const validationState = useValidation(state, {})
-    const fields = useFieldRegistry(state, validationState)
+    const initialDataOverride = useInitialDataOverride(toRef(state, 'initialData'))
+    const fields = useFieldRegistry(state, validationState, initialDataOverride)
 
     const formState = useFormState(fields)