@teamnovu/kit-vue-forms 0.1.14 → 0.1.16

package/dist/types/form.d.ts

@@ -1,9 +1,10 @@
+import { Awaitable } from '@vueuse/core';
 import { Ref } from 'vue';
 import { DefineFieldOptions } from '../composables/useFieldRegistry';
 import { SubformOptions } from '../composables/useSubform';
+import { ValidatorOptions } from '../composables/useValidation';
 import { EntityPaths, Paths, PickEntity, PickProps } from './util';
 import { ErrorBag, ValidationErrorMessage, ValidationErrors, ValidationResult, Validator } from './validation';
-import { ValidatorOptions } from '../composables/useValidation';
 export type FormDataDefault = object;
 export interface FormField<T, P extends string> {
     data: Ref<T>;
@@ -42,5 +43,6 @@ export interface Form<T extends FormDataDefault> {
     defineValidator: <TData extends T>(options: ValidatorOptions<TData> | Ref<Validator<TData>>) => Ref<Validator<TData> | undefined>;
     reset: () => void;
     validateForm: () => Promise<ValidationResult>;
+    submitHandler: (onSubmit: (data: T) => Awaitable<void>) => (event: SubmitEvent) => Promise<void>;
     getSubForm: <P extends EntityPaths<T>>(path: P, options?: SubformOptions<PickEntity<T, P>>) => Form<PickEntity<T, P>>;
 }

package/dist/utils/path.d.ts

@@ -1,11 +1,14 @@
 import { MaybeRef, WritableComputedRef } from 'vue';
 import { Paths, PickProps, SplitPath } from '../types/util';
 import { ErrorBag } from '../types/validation';
+import { FormField } from '../types/form';
 export declare function splitPath(path: string): string[];
+export declare function existsPath<T, K extends Paths<T>>(obj: T, path: K | SplitPath<K>): boolean;
+export declare function existsFieldPath<T, K extends Paths<T>>(field: FormField<T, K>): boolean;
 export declare function getNestedValue<T, K extends Paths<T>>(obj: T, path: K | SplitPath<K>): PickProps<T, K>;
 export declare function setNestedValue<T, K extends Paths<T>>(obj: MaybeRef<T>, path: K | SplitPath<K>, value: PickProps<T, K>): void;
 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}`;
+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 filterErrorsForPath(errors: ErrorBag, path: string): ErrorBag;
 export {};

package/docs/reference.md

@@ -17,10 +17,8 @@ function useForm<T extends object>(options: {
   // this is additional to the schema for custom validations
   validateFn?: MaybeRef<ValidationFunction<T>>
   // if the form data of a property should be reset or kept if all fields corresponding to this property are unmounted
-  // !! currently not implemented !!
   keepValuesOnUnmount?: MaybeRef<boolean>
   // when validation should be done (on touch, pre submit, etc.)
-  // !! currently not implemented !!
   validationStrategy?: MaybeRef<ValidationStrategy>
 }): Form<T>
 ```

package/package.json

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

package/src/components/FormFieldWrapper.vue

@@ -13,6 +13,14 @@
       @update:model-value="setData"
     >
       <slot />
+
+      <!-- https://vue-land.github.io/faq/forwarding-slots#passing-all-slots -->
+      <template
+        v-for="(_, slotName) in $slots"
+        #[slotName]="slotProps"
+      >
+        <slot :name="slotName" v-bind="slotProps ?? {}" />
+      </template>
     </component>
   </Field>
 </template>

package/src/composables/useField.ts

@@ -1,4 +1,5 @@
-import { computed, reactive, shallowRef, toRefs, watch, type MaybeRef, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from 'vue'
+import type { Awaitable } from '@vueuse/core'
+import { computed, reactive, shallowRef, 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'
@@ -7,10 +8,21 @@ export interface UseFieldOptions<T, K extends string> {
   value?: MaybeRef<T>
   initialValue?: MaybeRefOrGetter<Readonly<T>>
   path: K
-  errors?: WritableComputedRef<ValidationErrors>
+  errors?: Ref<ValidationErrors>
+  existsInForm?: MaybeRef<boolean>
+  onBlur?: () => Awaitable<void>
+  onFocus?: () => Awaitable<void>
 }
 
-export function useField<T, K extends string>(options: UseFieldOptions<T, K>): FormField<T, K> {
+export function useField<T, K extends string>(fieldOptions: UseFieldOptions<T, K>): FormField<T, K> {
+  const defaultOptions = {
+    existsInForm: true,
+  }
+
+  const options = {
+    ...defaultOptions,
+    ...fieldOptions,
+  }
   const initialValue = shallowRef(Object.freeze(cloneRefValue(options.initialValue))) as Ref<Readonly<T | undefined>>
 
   const state = reactive({
@@ -40,14 +52,20 @@ export function useField<T, K extends string>(options: UseFieldOptions<T, K>): F
 
   const onBlur = (): void => {
     state.touched = true
+    state.errors = []
+
+    options.onBlur?.()
   }
 
   const onFocus = (): void => {
-    // TODO: Implement focus logic if needed
+    options.onFocus?.()
   }
 
   const reset = (): void => {
-    state.value = cloneRefValue(state.initialValue)
+    const lastPathPart = state.path.split('.').at(-1) || ''
+    if (unref(options.existsInForm) && !/^\d+$/.test(lastPathPart)) {
+      state.value = cloneRefValue(state.initialValue)
+    }
     state.touched = false
     state.errors = []
   }

package/src/composables/useFieldRegistry.ts

@@ -1,23 +1,56 @@
-import { computed, onScopeDispose, shallowReactive, shallowRef, toRef, triggerRef, unref, watch, watchEffect, type MaybeRef, type WatchSource } from 'vue'
+import {
+  computed,
+  onScopeDispose,
+  shallowReactive,
+  shallowRef,
+  toRef,
+  triggerRef,
+  unref,
+  watchEffect,
+  type MaybeRef,
+} from 'vue'
 import type { FieldsTuple, FormDataDefault, FormField } from '../types/form'
 import type { Paths, PickProps } from '../types/util'
-import { getLens, getNestedValue } from '../utils/path'
+import { existsPath, getLens, getNestedValue } from '../utils/path'
 import { Rc } from '../utils/rc'
 import { useField, type UseFieldOptions } from './useField'
 import type { ValidationState } from './useValidation'
+import type { Awaitable } from '@vueuse/core'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type FieldRegistryCache<T> = Map<Paths<T>, FormField<any, string>>
 
-export type ResolvedFormField<T, K extends Paths<T>> = FormField<PickProps<T, K>, K>
-
-export type DefineFieldOptions<F, K extends string> = Pick<UseFieldOptions<F, K>, 'path'>
+export type ResolvedFormField<T, K extends Paths<T>> = FormField<
+  PickProps<T, K>,
+  K
+>
+
+export type DefineFieldOptions<F, K extends string> = Pick<
+  UseFieldOptions<F, K>,
+  'path'
+> & {
+  onBlur?: () => void
+  onFocus?: () => void
+}
 
-interface FormState<T extends FormDataDefault, TIn extends FormDataDefault = T> {
+interface FormState<
+  T extends FormDataDefault,
+  TIn extends FormDataDefault = T,
+> {
   data: T
   initialData: TIn
 }
 
+interface FieldRegistryOptions {
+  keepValuesOnUnmount?: MaybeRef<boolean>
+  onBlur?: (path: string) => Awaitable<void>
+  onFocus?: (path: string) => Awaitable<void>
+}
+
+const optionDefaults = {
+  keepValuesOnUnmount: true,
+}
+
 // 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 alwaysComputed<T>(getter: () => T) {
@@ -37,16 +70,26 @@ function alwaysComputed<T>(getter: () => T) {
 export function useFieldRegistry<T extends FormDataDefault>(
   formState: FormState<T>,
   validationState: ValidationState<T>,
+  fieldRegistryOptions?: FieldRegistryOptions,
 ) {
   const fieldReferenceCounter = new Map<Paths<T>, Rc>()
   const fields = shallowReactive(new Map()) as FieldRegistryCache<T>
+  const registryOptions = {
+    ...optionDefaults,
+    ...fieldRegistryOptions,
+  }
 
-  const registerField = <K extends Paths<T>>(field: ResolvedFormField<T, K>) => {
+  const registerField = <K extends Paths<T>>(
+    field: ResolvedFormField<T, K>,
+  ) => {
     const path = unref(field.path) as Paths<T>
     fields.set(path, field)
   }
 
   const deregisterField = (path: Paths<T>) => {
+    if (!registryOptions?.keepValuesOnUnmount) {
+      fields.get(path)?.reset()
+    }
     fields.delete(path)
   }
 
@@ -64,14 +107,18 @@ export function useFieldRegistry<T extends FormDataDefault>(
     }
   }
 
-  const getField = <K extends Paths<T>>(path: K): ResolvedFormField<T, K> => {
+  const getField = <K extends Paths<T>>(
+    options: DefineFieldOptions<PickProps<T, K>, K>,
+  ): ResolvedFormField<T, K> => {
+    const { path } = options
+
     if (!fields.has(path)) {
       const field = useField({
         path,
         value: getLens(toRef(formState, 'data'), path),
-        initialValue: alwaysComputed(
-          () => getNestedValue(formState.initialData, path),
-        ),
+        initialValue: alwaysComputed(() =>
+          getNestedValue(formState.initialData, path)),
+        existsInForm: computed(() => existsPath(formState.data, unref(path))),
         errors: computed({
           get() {
             return validationState.errors.value.propertyErrors[path] || []
@@ -80,6 +127,22 @@ export function useFieldRegistry<T extends FormDataDefault>(
             validationState.errors.value.propertyErrors[path] = newErrors
           },
         }),
+        onBlur: async () => {
+          await Promise.all(
+            [
+              registryOptions?.onBlur?.(unref(path)),
+              options.onBlur?.(),
+            ],
+          )
+        },
+        onFocus: async () => {
+          await Promise.all(
+            [
+              registryOptions?.onFocus?.(unref(path)),
+              options.onFocus?.(),
+            ],
+          )
+        },
       })
 
       registerField(field)
@@ -97,8 +160,10 @@ export function useFieldRegistry<T extends FormDataDefault>(
     return field
   }
 
-  const defineField = <K extends Paths<T>>(options: DefineFieldOptions<PickProps<T, K>, K>): ResolvedFormField<T, K> => {
-    const field = getField(options.path)
+  const defineField = <K extends Paths<T>>(
+    options: DefineFieldOptions<PickProps<T, K>, K>,
+  ): ResolvedFormField<T, K> => {
+    const field = getField(options)
 
     // TODO: If more options are ever needed than only the path we have to update the field
     // here with the new options
@@ -108,11 +173,13 @@ export function useFieldRegistry<T extends FormDataDefault>(
 
   return {
     fields: computed(() => [...fields.values()] as FieldsTuple<T>),
-    getField,
+    getField: <P extends Paths<T>>(path: P) => getField({ path }),
     registerField,
     deregisterField,
     defineField,
   }
 }
 
-export type FieldRegistry<T extends FormDataDefault> = ReturnType<typeof useFieldRegistry<T>>
+export type FieldRegistry<T extends FormDataDefault> = ReturnType<
+  typeof useFieldRegistry<T>
+>

package/src/composables/useForm.ts

@@ -1,52 +1,94 @@
-import { computed, reactive, ref, toRef, watch, type MaybeRef, type MaybeRefOrGetter, type Ref } from 'vue'
-import type { AnyField, Form, FormDataDefault } from '../types/form'
-import type { EntityPaths, PickEntity } from '../types/util'
-import type { ValidationStrategy } from '../types/validation'
-import { cloneRefValue } from '../utils/general'
-import { useFieldRegistry } from './useFieldRegistry'
-import { useFormState } from './useFormState'
-import { createSubformInterface, type SubformOptions } from './useSubform'
-import { useValidation, type ValidationOptions } from './useValidation'
+import type { Awaitable } from "@vueuse/core";
+import {
+  computed,
+  reactive,
+  ref,
+  toRef,
+  unref,
+  watch,
+  type MaybeRef,
+  type MaybeRefOrGetter,
+  type Ref,
+} from "vue";
+import type { Form, FormDataDefault } from "../types/form";
+import type { EntityPaths, PickEntity } from "../types/util";
+import type { ValidationStrategy } from "../types/validation";
+import { cloneRefValue } from "../utils/general";
+import { useFieldRegistry } from "./useFieldRegistry";
+import { useFormState } from "./useFormState";
+import { createSubformInterface, type SubformOptions } from "./useSubform";
+import { useValidation, type ValidationOptions } from "./useValidation";
 
 // TODO @Elias implement validation strategy handling
 
-export interface UseFormOptions<T extends FormDataDefault> extends ValidationOptions<T> {
-  initialData: MaybeRefOrGetter<T>
-  validationStrategy?: MaybeRef<ValidationStrategy>
-  keepValuesOnUnmount?: MaybeRef<boolean>
+export interface UseFormOptions<T extends FormDataDefault>
+  extends ValidationOptions<T> {
+  initialData: MaybeRefOrGetter<T>;
+  validationStrategy?: MaybeRef<ValidationStrategy>;
+  keepValuesOnUnmount?: MaybeRef<boolean>;
 }
 
 export function useForm<T extends FormDataDefault>(options: UseFormOptions<T>) {
-  const initialData = computed(() => Object.freeze(cloneRefValue(options.initialData)))
+  const initialData = computed(() =>
+    Object.freeze(cloneRefValue(options.initialData)),
+  );
 
-  const data = ref<T>(cloneRefValue(initialData)) as Ref<T>
+  const data = ref<T>(cloneRefValue(initialData)) as Ref<T>;
 
   const state = reactive({
     initialData,
     data,
-  })
+  });
 
-  watch(initialData, (newValue) => {
-    state.data = cloneRefValue(newValue)
-  }, { flush: 'sync' })
+  watch(
+    initialData,
+    (newValue) => {
+      state.data = cloneRefValue(newValue);
+    },
+    { flush: "sync" },
+  );
+
+  const validationState = useValidation(state, options);
+  const fieldRegistry = useFieldRegistry(state, validationState, {
+    keepValuesOnUnmount: options.keepValuesOnUnmount,
+    onBlur: async (path: string) => {
+      if (unref(options.validationStrategy) === "onTouch") {
+        // TODO: Only validate the specific field that was touched
+        validationState.validateField(path);
+      }
+    },
+  });
+  const formState = useFormState(fieldRegistry);
+
+  const submitHandler = (onSubmit: (data: T) => Awaitable<void>) => {
+    return async (event: SubmitEvent) => {
+      event.preventDefault();
+
+      if (unref(options.validationStrategy) !== "none") {
+        await validationState.validateForm();
+      }
 
-  const validationState = useValidation(state, options)
-  const fieldRegistry = useFieldRegistry(state, validationState)
-  const formState = useFormState(fieldRegistry)
+      if (!validationState.isValid.value) {
+        return;
+      }
+
+      await onSubmit(state.data);
+    };
+  };
 
   const reset = () => {
-    data.value = cloneRefValue(initialData)
-    validationState.reset()
-    fieldRegistry.fields.value.forEach(
-      (field: AnyField<T>) => field.reset(),
-    )
-  }
+    data.value = cloneRefValue(initialData);
+    validationState.reset();
+    for (const field of fieldRegistry.fields.value) {
+      field.reset();
+    }
+  };
 
   function getSubForm<K extends EntityPaths<T>>(
     path: K,
     options?: SubformOptions<PickEntity<T, K>>,
   ): Form<PickEntity<T, K>> {
-    return createSubformInterface(formInterface, path, options)
+    return createSubformInterface(formInterface, path, options);
   }
 
   const formInterface: Form<T> = {
@@ -55,9 +97,14 @@ export function useForm<T extends FormDataDefault>(options: UseFormOptions<T>) {
     ...formState,
     reset,
     getSubForm,
-    initialData: toRef(state, 'initialData') as Form<T>['initialData'],
-    data: toRef(state, 'data') as Form<T>['data'],
+    submitHandler,
+    initialData: toRef(state, "initialData") as Form<T>["initialData"],
+    data: toRef(state, "data") as Form<T>["data"],
+  };
+
+  if (unref(options.validationStrategy) === "onFormOpen") {
+    validationState.validateForm();
   }
 
-  return formInterface
+  return formInterface;
 }

package/src/composables/useValidation.ts

@@ -215,6 +215,22 @@ export function useValidation<T extends FormDataDefault>(
     }
   }
 
+  const validateField = async (path: string): Promise<ValidationResult> => {
+    const validationResults = await getValidationResults()
+
+    updateErrors({
+      general: validationResults.errors.general,
+      propertyErrors: {
+        [path]: validationResults.errors.propertyErrors[path],
+      },
+    })
+
+    return {
+      isValid: !hasErrors(validationResults.errors),
+      errors: validationState.errors,
+    }
+  }
+
   const isValid = computed(() => !hasErrors(validationState.errors))
 
   const reset = () => {
@@ -225,6 +241,7 @@ export function useValidation<T extends FormDataDefault>(
   return {
     ...toRefs(validationState),
     validateForm,
+    validateField,
     defineValidator,
     isValid,
     reset,

package/src/types/form.ts

@@ -1,9 +1,16 @@
+import type { Awaitable } from '@vueuse/core'
 import type { Ref } from 'vue'
 import type { DefineFieldOptions } from '../composables/useFieldRegistry'
 import type { SubformOptions } from '../composables/useSubform'
-import type { EntityPaths, Paths, PickEntity, PickProps } from './util'
-import type { ErrorBag, ValidationErrorMessage, ValidationErrors, ValidationResult, Validator } from './validation'
 import type { ValidatorOptions } from '../composables/useValidation'
+import type { EntityPaths, Paths, PickEntity, PickProps } from './util'
+import type {
+  ErrorBag,
+  ValidationErrorMessage,
+  ValidationErrors,
+  ValidationResult,
+  Validator,
+} from './validation'
 
 export type FormDataDefault = object
 
@@ -27,13 +34,13 @@ export interface FormField<T, P extends string> {
   clearErrors: () => void
 }
 
-export type FieldsTuple<T, TPaths = Paths<T>> = [...(
-  TPaths extends infer P
+export type FieldsTuple<T, TPaths = Paths<T>> = [
+  ...(TPaths extends infer P
     ? P extends string
       ? FormField<PickProps<T, P>, P>
       : never
-    : never
-)[]]
+    : never)[],
+]
 
 export type AnyField<T> = FormField<PickProps<T, Paths<T>>, Paths<T>>
 
@@ -45,7 +52,9 @@ export interface Form<T extends FormDataDefault> {
   fields: Ref<FieldsTuple<T>>
 
   // Field operations
-  defineField: <P extends Paths<T>>(options: DefineFieldOptions<PickProps<T, P>, P>) => FormField<PickProps<T, P>, P>
+  defineField: <P extends Paths<T>>(
+    options: DefineFieldOptions<PickProps<T, P>, P>,
+  ) => FormField<PickProps<T, P>, P>
   getField: <P extends Paths<T>>(path: P) => FormField<PickProps<T, P>, P>
 
   // State properties
@@ -55,12 +64,18 @@ export interface Form<T extends FormDataDefault> {
   isValidated: Ref<boolean>
   errors: Ref<ErrorBag>
 
-  defineValidator: <TData extends T>(options: ValidatorOptions<TData> | Ref<Validator<TData>>) => Ref<Validator<TData> | undefined>
+  defineValidator: <TData extends T>(
+    options: ValidatorOptions<TData> | Ref<Validator<TData>>,
+  ) => Ref<Validator<TData> | undefined>
 
   // Operations
   reset: () => void
   validateForm: () => Promise<ValidationResult>
 
+  submitHandler: (
+    onSubmit: (data: T) => Awaitable<void>,
+  ) => (event: SubmitEvent) => Promise<void>
+
   // Nested subforms
   getSubForm: <P extends EntityPaths<T>>(
     path: P,