@teamnovu/kit-vue-forms 0.0.1

package/src/composables/useForm.ts

@@ -0,0 +1,54 @@
+import { computed, reactive, ref, toRef, 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'
+
+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 formData = ref<T>(cloneRefValue(initialData)) as Ref<T>
+
+  const state = reactive({
+    initialData: initialData,
+    formData,
+  })
+
+  const fields = useFieldRegistry(state)
+  const validationState = useValidation(state, options)
+  const formState = useFormState(state, fields)
+
+  const reset = () => {
+    formData.value = cloneRefValue(initialData)
+    fields.getFields().forEach(field => field.reset())
+  }
+
+  function getSubForm<K extends EntityPaths<T>>(
+    path: K,
+    options?: SubformOptions<PickEntity<T, K>>,
+  ): Form<PickEntity<T, K>> {
+    return createSubformInterface(formInterface, path, options)
+  }
+
+  const formInterface: Form<T> = {
+    ...fields,
+    ...validationState,
+    ...formState,
+    reset,
+    getSubForm,
+    initialData: toRef(state, 'initialData') as Form<T>['initialData'],
+    formData: toRef(state, 'formData') as Form<T>['formData'],
+  }
+
+  return formInterface
+}

package/src/composables/useFormData.ts

@@ -0,0 +1,16 @@
+import { ref, type Ref, unref, watch } from 'vue'
+import type { FormDataDefault } from '../types/form'
+
+export function useFormData<T extends FormDataDefault>(
+  initialData: Ref<T>,
+) {
+  const formData = ref(unref(initialData))
+
+  watch(initialData, (newData) => {
+    if (newData !== formData.value) {
+      formData.value = newData
+    }
+  })
+
+  return { formData }
+}

package/src/composables/useFormState.ts

@@ -0,0 +1,21 @@
+import { computed, unref } from 'vue'
+import type { FormDataDefault, FormState } from '../types/form'
+import type { FieldRegistry } from './useFieldRegistry'
+
+export function useFormState<T extends FormDataDefault>(
+  formState: FormState<T>,
+  formFieldRegistry: FieldRegistry<T>,
+) {
+  const isDirty = computed(() => {
+    return JSON.stringify(formState.formData) !== JSON.stringify(formState.initialData)
+  })
+
+  const isTouched = computed(() => {
+    return formFieldRegistry.getFields().some(field => unref(field.touched))
+  })
+
+  return {
+    isDirty,
+    isTouched,
+  }
+}

package/src/composables/useSubform.ts

@@ -0,0 +1,173 @@
+import { computed, isRef, unref, type Ref } from 'vue'
+import type { Form, FormDataDefault, FormField } from '../types/form'
+import type { EntityPaths, Paths, PickEntity, PickProps } from '../types/util'
+import type { ValidationResult, Validator } from '../types/validation'
+import { filterErrorsForPath, getLens, getNestedValue, joinPath } from '../utils/path'
+import type { DefineFieldOptions } from './useFieldRegistry'
+import { createValidator, SuccessValidationResult, type ValidatorOptions } from './useValidation'
+
+export interface SubformOptions<_T extends FormDataDefault> {
+  // Additional subform-specific options can be added here
+}
+
+class NestedValidator<T extends FormDataDefault, P extends Paths<T>> implements Validator<T> {
+  constructor(
+    private path: P,
+    private validator: Validator<PickEntity<T, P>> | undefined,
+  ) {
+  }
+
+  async validate(data: T): Promise<ValidationResult> {
+    const subFormData = getNestedValue(data, this.path) as PickEntity<T, P>
+
+    if (!this.validator) {
+      return SuccessValidationResult
+    }
+
+    const validationResult = await this.validator.validate(subFormData)
+
+    return {
+      isValid: validationResult.isValid,
+      errors: {
+        general: validationResult.errors.general || [],
+        propertyErrors: validationResult.errors.propertyErrors
+          ? Object.fromEntries(
+              Object.entries(validationResult.errors.propertyErrors).map(([key, errors]) => [
+                joinPath(this.path, key),
+                errors,
+              ]),
+            )
+          : {},
+      },
+    }
+  }
+}
+
+export function createSubformInterface<
+  T extends FormDataDefault,
+  K extends EntityPaths<T>,
+>(
+  mainForm: Form<T>,
+  path: K,
+  _options?: SubformOptions<PickEntity<T, K>>,
+): Form<PickEntity<T, K>> {
+  type ST = PickEntity<T, K>
+  type SP = Paths<ST>
+  type MP<P extends SP> = `${K}.${P}`
+  type ScopedMainPaths = Paths<T> & MP<SP>
+
+  // Create reactive data scoped to subform path
+  const formData = getLens(mainForm.formData, path) as Ref<ST>
+
+  const initialData = computed(() => {
+    return getNestedValue(mainForm.initialData.value, path) as ST
+  })
+
+  const adaptMainFormField = <S extends SP>(
+    field: FormField<PickProps<T, ScopedMainPaths>, ScopedMainPaths>,
+  ): FormField<PickProps<ST, S>, S> => {
+    // Where P ist the full path in the main form, we need to adapt it to the subform's path
+    return {
+      ...field,
+      path: computed(() => unref(field.path).replace(path + '.', '')),
+      setValue: (newValue: PickProps<ST, S>) => {
+        field.setValue(newValue as PickProps<T, ScopedMainPaths>)
+      },
+    } as unknown as FormField<PickProps<ST, S>, S>
+  }
+
+  const getField = <P extends SP>(fieldPath: P) => {
+    const fullPath = joinPath(path, fieldPath)
+    const mainFormField = mainForm.getField(fullPath as ScopedMainPaths)
+
+    if (!mainFormField) {
+      return
+    }
+
+    return adaptMainFormField<P>(mainFormField)
+  }
+
+  // Field operations with path transformation
+  const defineField = <P extends SP>(fieldOptions: DefineFieldOptions<ST, P>) => {
+    const fullPath = joinPath(path, fieldOptions.path)
+
+    const mainField = mainForm.defineField({
+      ...fieldOptions,
+      path: fullPath as ScopedMainPaths,
+    })
+
+    return adaptMainFormField<P>(mainField)
+  }
+
+  const getFields = <P extends SP>(): FormField<PickProps<ST, P>, P>[] => {
+    return (mainForm.getFields() as FormField<PickProps<T, ScopedMainPaths>, ScopedMainPaths>[])
+      .filter((field) => {
+        const fieldPath = field.path.value
+        return fieldPath.startsWith(path + '.') || fieldPath === path
+      })
+      .map(field => adaptMainFormField(field))
+  }
+
+  // Helper function to get all fields without type parameter
+  const getAllSubformFields = () => {
+    return (mainForm.getFields() as FormField<PickProps<T, ScopedMainPaths>, ScopedMainPaths>[])
+      .filter((field) => {
+        const fieldPath = field.path.value
+        return fieldPath.startsWith(path + '.') || fieldPath === path
+      })
+  }
+
+  // State computed from main form with path filtering
+  const isDirty = computed(() => getAllSubformFields().some(field => field.dirty.value))
+  const isTouched = computed(() => getAllSubformFields().some(field => field.touched.value))
+
+  // Validation delegates to main form
+  const isValid = computed(() => mainForm.isValid.value)
+  const isValidated = computed(() => mainForm.isValidated.value)
+  const errors = computed(() => filterErrorsForPath(unref(mainForm.errors), path))
+
+  const validateForm = () => mainForm.validateForm()
+
+  // Nested subforms
+  const getSubForm = <P extends EntityPaths<ST>>(
+    subPath: P,
+    subOptions?: SubformOptions<PickEntity<ST, P>>,
+  ) => {
+    const fullPath = joinPath(path, subPath) as EntityPaths<T>
+    return mainForm.getSubForm(
+      fullPath,
+      subOptions as SubformOptions<PickEntity<T, typeof fullPath>>,
+    ) as Form<PickEntity<ST, P>>
+  }
+
+  // Reset scoped to this subform
+  const reset = () => getAllSubformFields().forEach(field => field.reset())
+
+  const defineValidator = (options: ValidatorOptions<ST> | Ref<Validator<ST>>) => {
+    const subValidator = isRef(options) ? options : createValidator(options)
+    const validator = computed(
+      () => new NestedValidator<T, K>(path, unref(subValidator)),
+    )
+
+    mainForm.defineValidator(validator)
+
+    return subValidator
+  }
+
+  return {
+    formData,
+    initialData,
+    defineField,
+    getField,
+    getFields,
+    isDirty,
+    isTouched,
+    isValid,
+    isValidated,
+    errors,
+    defineValidator,
+    reset,
+    validateForm,
+    getSubForm,
+  }
+}

package/src/composables/useValidation.ts

@@ -0,0 +1,227 @@
+import { computed, getCurrentScope, isRef, onBeforeUnmount, reactive, ref, toRefs, unref, watch, type MaybeRef, type Ref } from 'vue'
+import z from 'zod'
+import type { FormDataDefault } from '../types/form'
+import type { ErrorBag, ValidationFunction, ValidationResult, Validator } from '../types/validation'
+import { hasErrors, mergeErrors } from '../utils/validation'
+import { flattenError } from '../utils/zod'
+
+export interface ValidatorOptions<T> {
+  schema?: MaybeRef<z.ZodType>
+  validateFn?: MaybeRef<ValidationFunction<T>>
+}
+
+export interface ValidationOptions<T> extends ValidatorOptions<T> {
+  errors?: MaybeRef<ErrorBag>
+}
+
+export const SuccessValidationResult: ValidationResult = {
+  isValid: true,
+  errors: {
+    general: [],
+    propertyErrors: {},
+  },
+}
+
+class ZodSchemaValidator<T extends FormDataDefault> implements Validator<T> {
+  constructor(private schema?: z.ZodType<T>) {}
+
+  async validate(data: T): Promise<ValidationResult> {
+    if (!this.schema) {
+      return SuccessValidationResult
+    }
+
+    const result = await this.schema.safeParseAsync(data)
+
+    if (result.success) {
+      return SuccessValidationResult
+    }
+
+    const zodErrors = flattenError(result.error)
+
+    return {
+      isValid: false,
+      errors: {
+        general: zodErrors.general ?? [],
+        propertyErrors: zodErrors.propertyErrors ?? {},
+      },
+    }
+  }
+}
+
+class FunctionValidator<T extends FormDataDefault> implements Validator<T> {
+  constructor(private validateFn?: ValidationFunction<T>) {}
+
+  async validate(data: T): Promise<ValidationResult> {
+    if (!this.validateFn) {
+      return SuccessValidationResult
+    }
+
+    try {
+      const result = await this.validateFn(data)
+
+      if (result.isValid) {
+        return SuccessValidationResult
+      }
+
+      return result
+    } catch (error) {
+      return {
+        isValid: false,
+        errors: {
+          general: [(error as Error).message || 'Validation error'],
+          propertyErrors: {},
+        },
+      }
+    }
+  }
+}
+
+class CombinedValidator<T extends FormDataDefault> implements Validator<T> {
+  private schemaValidator: ZodSchemaValidator<T>
+  private functionValidator: FunctionValidator<T>
+
+  constructor(
+    private schema: z.ZodType<T>,
+    private validateFn: ValidationFunction<T>,
+  ) {
+    this.schemaValidator = new ZodSchemaValidator(this.schema)
+    this.functionValidator = new FunctionValidator(this.validateFn)
+  }
+
+  async validate(data: T): Promise<ValidationResult> {
+    const [schemaResult, functionResult] = await Promise.all([
+      this.schemaValidator.validate(data),
+      this.functionValidator.validate(data),
+    ])
+
+    const isValid = schemaResult.isValid && functionResult.isValid
+
+    return {
+      isValid,
+      errors: mergeErrors(schemaResult.errors, functionResult.errors),
+    }
+  }
+}
+
+export function createValidator<T extends FormDataDefault>(
+  options: ValidatorOptions<T>,
+): Ref<Validator<T> | undefined> {
+  return computed(() => new CombinedValidator(
+    unref(options.schema) as z.ZodType<T>,
+    unref(options.validateFn) as ValidationFunction<T>,
+  ))
+}
+
+export function useValidation<T extends FormDataDefault>(
+  formState: { formData: T },
+  options: ValidationOptions<T>,
+) {
+  const validationState = reactive({
+    validators: ref<Ref<Validator<T> | undefined>[]>([createValidator(options)]),
+    isValidated: false,
+    errors: unref(options.errors) ?? {
+      general: [],
+      propertyErrors: {},
+    },
+  })
+
+  // Watch for changes in the error bag and update validation state
+  watch(() => unref(options.errors), async () => {
+    const validationResults = await getValidationResults()
+
+    updateErrors(validationResults.errors)
+  }, { immediate: true })
+
+  // Watch for changes in validation function or schema
+  // to trigger validation. Only run if validation is already validated.
+  watch(
+    [() => validationState.validators],
+    async (validators) => {
+      if (!validationState.isValidated) {
+        return
+      }
+
+      if (validators) {
+        const validationResults = await getValidationResults()
+        validationState.errors = validationResults.errors
+      } else {
+        validationState.errors = SuccessValidationResult.errors
+      }
+    },
+    { immediate: true },
+  )
+
+  // Watch for changes in form data to trigger validation
+  watch(() => formState.formData, () => {
+    if (validationState.isValidated) {
+      validateForm()
+    }
+  })
+
+  const defineValidator = (options: ValidatorOptions<T> | Ref<Validator<T>>) => {
+    const validator = isRef(options) ? options : createValidator(options)
+
+    validationState.validators.push(validator)
+
+    if (getCurrentScope()) {
+      onBeforeUnmount(() => {
+        validationState.validators = validationState.validators.filter(
+          v => v !== validator,
+        )
+      })
+    }
+
+    return validator
+  }
+
+  async function getValidationResults() {
+    const validationResults = await Promise.all(
+      validationState.validators
+        .filter(validator => unref(validator) !== undefined)
+        .map(validator => unref(validator)!.validate(formState.formData)),
+    )
+
+    const isValid = validationResults.every(result => result.isValid)
+
+    let { errors } = SuccessValidationResult
+
+    if (!isValid) {
+      const validationErrors = validationResults.map(result => result.errors)
+
+      errors = mergeErrors(...validationErrors)
+    }
+
+    return {
+      errors,
+      isValid,
+    }
+  }
+
+  const updateErrors = (newErrors: ErrorBag) => {
+    validationState.errors = mergeErrors(unref(options.errors) ?? SuccessValidationResult.errors, newErrors)
+  }
+
+  const validateForm = async (): Promise<ValidationResult> => {
+    const validationResults = await getValidationResults()
+
+    updateErrors(validationResults.errors)
+
+    validationState.isValidated = true
+
+    return {
+      isValid: !hasErrors(validationResults.errors),
+      errors: validationState.errors,
+    }
+  }
+
+  const isValid = computed(() => !hasErrors(validationState.errors))
+
+  return {
+    ...toRefs(validationState),
+    validateForm,
+    defineValidator,
+    isValid,
+  }
+}
+
+export type ValidationState<T extends FormDataDefault> = ReturnType<typeof useValidation<T>>

package/src/index.ts

@@ -0,0 +1,11 @@
+// Main composable
+export { useForm } from './composables/useForm'
+export type { UseFormOptions } from './composables/useForm'
+
+// Field composable
+export { useField } from './composables/useField'
+export type { UseFieldOptions } from './composables/useField'
+
+// Types
+export type { ValidationStrategy, ValidationErrorMessage as ErrorMessage, ValidationResult, ErrorBag } from './types/validation'
+export type { DeepPartial, FormData } from './utils/type-helpers'

package/src/types/form.ts

@@ -0,0 +1,58 @@
+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'
+
+export type FormDataDefault = object
+
+export interface FormState<T extends FormDataDefault, TIn extends FormDataDefault = T> {
+  formData: T
+  initialData: TIn
+}
+
+export interface FormField<T, P extends string> {
+  value: Ref<T>
+  path: Ref<P>
+  initialValue: Readonly<Ref<T>>
+  errors: Ref<ValidationErrors>
+  touched: Ref<boolean>
+  dirty: Ref<boolean>
+  setValue: (newValue: T) => void
+  onBlur: () => void
+  onFocus: () => void
+  reset: () => void
+  setErrors: (newErrors: ValidationErrorMessage[]) => void
+  clearErrors: () => void
+}
+
+export interface Form<T extends FormDataDefault> {
+  // Data properties
+  formData: Ref<T>
+  initialData: Readonly<Ref<T>>
+
+  // Field operations
+  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> | undefined
+  getFields: () => FormField<PickProps<T, Paths<T>>, Paths<T>>[]
+
+  // State properties
+  isDirty: Ref<boolean>
+  isTouched: Ref<boolean>
+  isValid: Ref<boolean>
+  isValidated: Ref<boolean>
+  errors: Ref<ErrorBag>
+
+  defineValidator: (options: ValidatorOptions<T> | Ref<Validator<T>>) => Ref<Validator<T> | undefined>
+
+  // Operations
+  reset: () => void
+  validateForm: () => Promise<ValidationResult>
+
+  // Nested subforms
+  getSubForm: <P extends EntityPaths<T>>(
+    path: P,
+    options?: SubformOptions<PickEntity<T, P>>,
+  ) => Form<PickEntity<T, P>>
+}

package/src/types/util.ts

@@ -0,0 +1,73 @@
+import type { FormDataDefault } from './form'
+
+/**
+ * Takes a dot-connected path and returns a tuple of its parts.
+ */
+export type SplitPath<TPath extends string> =
+  TPath extends `${infer T1}.${infer T2}`
+    ? [T1, ...SplitPath<T2>]
+    : [TPath]
+
+/**
+ * Picks the exact type of the Entity at the nested PropertyKeys path.
+ */
+export type PickProps<Entity, PropertyKeys extends string> =
+  PropertyKeys extends `${infer TRoot}.${infer TRest}`
+    ? TRoot extends keyof Entity
+      ? TRest extends string
+        ? Entity[TRoot] extends object
+          ? PickProps<Entity[TRoot], TRest>
+          : never
+        : never
+      // We might have an array at hand but the key is a string with a number in it
+      : TRoot extends `${number}`
+        ? Entity extends unknown[]
+          ? TRest extends string
+            ? Entity[number] extends object
+              ? PickProps<Entity[number], TRest>
+              : never
+            : never
+          : never
+        : never
+    // We might have an array at hand but the key is a string with a number in it
+    : PropertyKeys extends keyof Entity
+      ? Entity[PropertyKeys]
+      : PropertyKeys extends `${number}`
+        ? Entity extends unknown[]
+          ? Entity[number]
+          : never
+        : never
+
+/**
+ * Resolves to a union of dot-connected paths of all nested properties of T.
+ */
+export type Paths<T, Seen = never> =
+  T extends Seen ? never :
+    T extends Array<infer ArrayType> ? `${number}` | `${number}.${Paths<ArrayType, Seen | T>}` :
+      T extends object
+        ? {
+            [K in keyof T]-?: `${Exclude<K, symbol>}${'' | `.${Paths<T[K], Seen | T>}`}`
+          }[keyof T]
+        : never
+
+/**
+ * Removes the last part of a dot-connected path.
+ */
+export type ButLast<T extends string> =
+  T extends `${infer Rest}.${infer Last}`
+    ? ButLast<Last> extends ''
+      ? Rest
+      : `${Rest}.${ButLast<Last>}`
+    : never
+
+/**
+ * Combines Paths<T> with ButLast<Paths<T>> to include all paths except the last part.
+ * The & Paths<T> ensures that there are no entity paths that are not also available in Paths<T>.
+ */
+export type EntityPaths<T> = ButLast<Paths<T>> & Paths<T>
+
+export type PickEntity<Entity, PropertyKeys extends string> =
+  PropertyKeys extends unknown ? PickProps<Entity, EntityPaths<Entity> & PropertyKeys> & FormDataDefault : never
+
+export type RestPath<T extends string, P extends string> =
+  P extends `${T}.${infer Rest}` ? Rest : never

package/src/types/validation.ts

@@ -0,0 +1,22 @@
+import type { FormDataDefault } from './form'
+
+export type ValidationStrategy = 'onTouch' | 'onFormOpen' | 'none' | 'preSubmit'
+
+export type ValidationErrorMessage = string
+export type ValidationErrors = ValidationErrorMessage[] | undefined
+
+export interface ErrorBag {
+  general: ValidationErrors
+  propertyErrors: Record<string, ValidationErrors>
+}
+
+export interface ValidationResult {
+  isValid: boolean
+  errors: ErrorBag
+}
+
+export interface Validator<T extends FormDataDefault = FormDataDefault> {
+  validate: (data: T) => Promise<ValidationResult>
+}
+
+export type ValidationFunction<T> = (data: T) => Promise<ValidationResult>

package/src/utils/general.ts

@@ -0,0 +1,7 @@
+import { toRaw, toValue, type MaybeRefOrGetter } from 'vue'
+
+export function cloneRefValue<T>(ref: MaybeRefOrGetter<T> | MaybeRefOrGetter<Readonly<T>>): T {
+  const unreffed = toValue(ref)
+  const raw = toRaw(unreffed)
+  return structuredClone(raw) as T
+}