@teamnovu/kit-vue-forms 0.2.17 → 0.3.0

package/src/composables/useValidation.ts

@@ -1,7 +1,26 @@
-import { computed, getCurrentScope, isRef, onBeforeUnmount, reactive, ref, toRefs, toValue, unref, watch, type MaybeRef, type MaybeRefOrGetter, type Ref } from 'vue'
-import z from 'zod'
+import {
+  computed,
+  getCurrentScope,
+  isRef,
+  onBeforeUnmount,
+  reactive,
+  ref,
+  toRefs,
+  toValue,
+  unref,
+  watch,
+  type MaybeRef,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+import type z from 'zod'
 import type { FormDataDefault } from '../types/form'
-import type { ErrorBag, ValidationFunction, ValidationResult, Validator } from '../types/validation'
+import type {
+  ErrorBag,
+  ValidationFunction,
+  ValidationResult,
+  Validator,
+} from '../types/validation'
 import { hasErrors, isValidResult, mergeErrors } from '../utils/validation'
 import { flattenError } from '../utils/zod'
 
@@ -35,7 +54,8 @@ export interface ValidatorOptions<T, TOut = T> {
   validateFn?: MaybeRef<ValidationFunction<T, TOut> | undefined>
 }
 
-export interface ValidationOptions<T, TOut = T> extends ValidatorOptions<T, TOut> {
+export interface ValidationOptions<T, TOut = T>
+  extends ValidatorOptions<T, TOut> {
   errors?: MaybeRef<ErrorBag | undefined>
   validationBeforeSubmit?: ValidationFlags
   validationAfterSubmit?: ValidationFlags
@@ -48,7 +68,8 @@ export const SuccessValidationResult: ValidationResult<never> = {
   },
 }
 
-class ZodSchemaValidator<T extends FormDataDefault, TOut = T> implements Validator<T, TOut> {
+class ZodSchemaValidator<T extends FormDataDefault, TOut = T>
+implements Validator<T, TOut> {
   constructor(private schema?: z.ZodType<TOut, T>) {}
 
   async validate(data: T): Promise<ValidationResult<TOut>> {
@@ -74,7 +95,8 @@ class ZodSchemaValidator<T extends FormDataDefault, TOut = T> implements Validat
   }
 }
 
-class FunctionValidator<T extends FormDataDefault, TOut = T> implements Validator<T, TOut> {
+class FunctionValidator<T extends FormDataDefault, TOut = T>
+implements Validator<T, TOut> {
   constructor(private validateFn?: ValidationFunction<T, TOut>) {}
 
   async validate(data: T): Promise<ValidationResult<TOut>> {
@@ -101,7 +123,8 @@ class FunctionValidator<T extends FormDataDefault, TOut = T> implements Validato
   }
 }
 
-class CombinedValidator<T extends FormDataDefault, TOut = T> implements Validator<T, TOut> {
+class CombinedValidator<T extends FormDataDefault, TOut = T>
+implements Validator<T, TOut> {
   private schemaValidator: ZodSchemaValidator<T, TOut>
   private functionValidator: FunctionValidator<T, TOut>
 
@@ -129,10 +152,13 @@ class CombinedValidator<T extends FormDataDefault, TOut = T> implements Validato
 export function createValidator<T extends FormDataDefault, TOut = T>(
   options: ValidatorOptions<T, TOut>,
 ): Ref<Validator<T, TOut> | undefined> {
-  return computed(() => new CombinedValidator(
-    unref(options.schema) as z.ZodType<TOut, T>,
-    unref(options.validateFn) as ValidationFunction<T, TOut>,
-  ))
+  return computed(
+    () =>
+      new CombinedValidator(
+        unref(options.schema) as z.ZodType<TOut, T>,
+        unref(options.validateFn) as ValidationFunction<T, TOut>,
+      ),
+  )
 }
 
 export function useValidation<T extends FormDataDefault, TOut = T>(
@@ -145,20 +171,29 @@ export function useValidation<T extends FormDataDefault, TOut = T>(
     errors: unref(options.errors) ?? SuccessValidationResult.errors,
   })
 
-  const updateErrors = (newErrors: ErrorBag = SuccessValidationResult.errors) => {
-    validationState.errors = mergeErrors(unref(options.errors) ?? SuccessValidationResult.errors, newErrors)
+  const updateErrors = (
+    newErrors: ErrorBag = SuccessValidationResult.errors,
+  ) => {
+    validationState.errors = mergeErrors(
+      unref(options.errors) ?? SuccessValidationResult.errors,
+      newErrors,
+    )
   }
 
   // Watch for changes in the error bag and update validation state
-  watch(() => unref(options.errors), async () => {
-    if (validationState.isValidated) {
-      const validationResults = await getValidationResults()
+  watch(
+    () => unref(options.errors),
+    async () => {
+      if (validationState.isValidated) {
+        const validationResults = await getValidationResults()
 
-      updateErrors(validationResults.errors)
-    } else {
-      updateErrors()
-    }
-  }, { immediate: true })
+        updateErrors(validationResults.errors)
+      } else {
+        updateErrors()
+      }
+    },
+    { immediate: true },
+  )
 
   // Watch for changes in validation function or schema
   // to trigger validation. Only run if validation is already validated.
@@ -187,11 +222,15 @@ export function useValidation<T extends FormDataDefault, TOut = T>(
   })
 
   const defineValidator = <TData extends T, TDataOut extends TOut>(
-    options: ValidatorOptions<TData, TDataOut> | Ref<Validator<TData, TDataOut>>,
+    options:
+      | ValidatorOptions<TData, TDataOut>
+      | Ref<Validator<TData, TDataOut>>,
   ) => {
     const validator = isRef(options) ? options : createValidator(options)
 
-    validationState.validators.push(validator as Ref<Validator<T, TOut> | undefined>)
+    validationState.validators.push(
+      validator as Ref<Validator<T, TOut> | undefined>,
+    )
 
     if (getCurrentScope()) {
       onBeforeUnmount(() => {
@@ -240,7 +279,9 @@ export function useValidation<T extends FormDataDefault, TOut = T>(
     }
   }
 
-  const validateField = async (path: string): Promise<ValidationResult<TOut>> => {
+  const validateField = async (
+    path: string,
+  ): Promise<ValidationResult<TOut>> => {
     const validationResults = await getValidationResults()
 
     updateErrors({
@@ -272,7 +313,10 @@ export function useValidation<T extends FormDataDefault, TOut = T>(
     return toValue(flags?.[flag] ?? false)
   }
 
-  const validateStrategy = <K extends keyof ValidationFlags>(flag: K, path: string) => {
+  const validateStrategy = <K extends keyof ValidationFlags>(
+    flag: K,
+    path: string,
+  ) => {
     if (!canValidate(flag)) {
       return
     }
@@ -292,4 +336,6 @@ export function useValidation<T extends FormDataDefault, TOut = T>(
   }
 }
 
-export type ValidationState<T extends FormDataDefault, TOut = T> = ReturnType<typeof useValidation<T, TOut>>
+export type ValidationState<T extends FormDataDefault, TOut = T> = ReturnType<
+  typeof useValidation<T, TOut>
+>

package/src/types/form.ts

@@ -5,11 +5,11 @@ import type { SubformOptions } from '../composables/useSubform'
 import type { ValidatorOptions } from '../composables/useValidation'
 import type { EntityPaths, Paths, PickEntity, PickProps } from './util'
 import type {
-    ErrorBag,
-    ValidationErrorMessage,
-    ValidationErrors,
-    ValidationResult,
-    Validator,
+  ErrorBag,
+  ValidationErrorMessage,
+  ValidationErrors,
+  ValidationResult,
+  Validator,
 } from './validation'
 
 export type FormDataDefault = object
@@ -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/types/util.ts

@@ -1,4 +1,3 @@
-import type { Prop } from 'vue'
 import type { FormDataDefault } from './form'
 
 /**

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/src/utils/submitHandler.ts

@@ -5,7 +5,7 @@ import { isValidResult } from './validation'
 
 export function makeSubmitHandler<T extends FormDataDefault, TOut = T>(
   form: Form<T, TOut>,
-  validationState: ValidationState<T, TOut>,
+  validationState: Pick<ValidationState<T, TOut>, 'canValidate'>,
 ) {
   return (onSubmit: (data: TOut) => Awaitable<void>) => {
     return async (event?: SubmitEvent) => {

package/src/utils/zod.ts

@@ -1,4 +1,4 @@
-import z from 'zod'
+import type z from 'zod'
 import type { ErrorBag } from '../types/validation'
 
 export function flattenError(error: z.ZodError): ErrorBag {
@@ -8,14 +8,17 @@ export function flattenError(error: z.ZodError): ErrorBag {
 
   const propertyErrors = error.issues
     .filter(issue => issue.path.length > 0)
-    .reduce((acc, issue) => {
-      const path = issue.path.join('.')
+    .reduce(
+      (acc, issue) => {
+        const path = issue.path.join('.')
 
-      return {
-        ...acc,
-        [path]: [...(acc[path] ?? []), issue.message],
-      }
-    }, {} as ErrorBag['propertyErrors'])
+        return {
+          ...acc,
+          [path]: [...(acc[path] ?? []), issue.message],
+        }
+      },
+      {} as ErrorBag['propertyErrors'],
+    )
 
   return {
     general,

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)