@teamnovu/kit-vue-forms 0.1.20 → 0.1.22

package/src/composables/useSubform.ts

@@ -1,47 +1,47 @@
-import { computed, isRef, unref, type Ref } from "vue";
+import { computed, isRef, unref, type Ref } from 'vue'
 import type {
   FieldsTuple,
   Form,
   FormDataDefault,
   FormField,
-} from "../types/form";
-import type { EntityPaths, Paths, PickEntity, PickProps } from "../types/util";
-import type { ValidationResult, Validator } from "../types/validation";
+} 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 type { UseFormOptions } from "./useForm";
-import { useSubmitHandler } from "./useSubmitHandler";
+} from '../utils/path'
+import { makeSubmitHandler } from '../utils/submitHandler'
+import { useFieldArray } from './useFieldArray'
+import type { DefineFieldOptions } from './useFieldRegistry'
+import type { UseFormOptions } from './useForm'
 import {
   createValidator,
   SuccessValidationResult,
   type ValidatorOptions,
-} from "./useValidation";
+} 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>
-{
+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>;
+    const subFormData = getNestedValue(data, this.path) as PickEntity<T, P>
 
     if (!this.validator) {
-      return SuccessValidationResult;
+      return SuccessValidationResult
     }
 
-    const validationResult = await this.validator.validate(subFormData);
+    const validationResult = await this.validator.validate(subFormData)
 
     return {
       isValid: validationResult.isValid,
@@ -55,7 +55,7 @@ class NestedValidator<T extends FormDataDefault, P extends Paths<T>>
             )
           : {},
       },
-    };
+    }
   }
 }
 
@@ -63,22 +63,22 @@ export function createSubformInterface<
   T extends FormDataDefault,
   K extends EntityPaths<T>,
 >(
-  mainForm: Omit<Form<T>, "submitHandler">,
+  mainForm: Form<T>,
   path: K,
   formOptions?: UseFormOptions<T>,
   _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>;
+  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 data = getLens(mainForm.data, path) as Ref<ST>;
+  const data = getLens(mainForm.data, path) as Ref<ST>
 
   const initialData = computed(() => {
-    return getNestedValue(mainForm.initialData.value, path) as ST;
-  });
+    return getNestedValue(mainForm.initialData.value, path) as ST
+  })
 
   const adaptMainFormField = <S extends SP>(
     field: FormField<PickProps<T, ScopedMainPaths>, ScopedMainPaths>,
@@ -86,37 +86,37 @@ export function createSubformInterface<
     // 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 + ".", "")),
+      path: computed(() => unref(field.path).replace(path + '.', '')),
       setData: (newData: PickProps<ST, S>) => {
-        field.setData(newData as PickProps<T, ScopedMainPaths>);
+        field.setData(newData as PickProps<T, ScopedMainPaths>)
       },
-    } as unknown as FormField<PickProps<ST, S>, S>;
-  };
+    } 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);
+    const fullPath = joinPath(path, fieldPath)
+    const mainFormField = mainForm.getField(fullPath as ScopedMainPaths)
 
     if (!mainFormField) {
-      return {} as FormField<PickProps<ST, P>, P>;
+      return {} as FormField<PickProps<ST, P>, P>
     }
 
-    return adaptMainFormField<P>(mainFormField);
-  };
+    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 fullPath = joinPath(path, fieldOptions.path)
 
     const mainField = mainForm.defineField({
       ...fieldOptions,
       path: fullPath as ScopedMainPaths,
-    });
+    })
 
-    return adaptMainFormField<P>(mainField);
-  };
+    return adaptMainFormField<P>(mainField)
+  }
 
   const fields = computed(<P extends SP>() => {
     return (
@@ -126,11 +126,11 @@ export function createSubformInterface<
       >[]
     )
       .filter((field) => {
-        const fieldPath = field.path.value;
-        return fieldPath.startsWith(path + ".") || fieldPath === path;
+        const fieldPath = field.path.value
+        return fieldPath.startsWith(path + '.') || fieldPath === path
       })
-      .map((field) => adaptMainFormField(field)) as FieldsTuple<ST, P>;
-  });
+      .map(field => adaptMainFormField(field)) as FieldsTuple<ST, P>
+  })
 
   // Helper function to get all fields without type parameter
   const getAllSubformFields = () => {
@@ -140,57 +140,54 @@ export function createSubformInterface<
         ScopedMainPaths
       >[]
     ).filter((field) => {
-      const fieldPath = field.path.value;
-      return fieldPath.startsWith(path + ".") || fieldPath === path;
-    });
-  };
+      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),
-  );
+    getAllSubformFields().some(field => field.dirty.value))
   const isTouched = computed(() =>
-    getAllSubformFields().some((field) => field.touched.value),
-  );
+    getAllSubformFields().some(field => field.touched.value))
 
   // Validation delegates to main form
-  const isValid = computed(() => mainForm.isValid.value);
-  const isValidated = computed(() => mainForm.isValidated.value);
+  const isValid = computed(() => mainForm.isValid.value)
+  const isValidated = computed(() => mainForm.isValidated.value)
   const errors = computed(() =>
-    filterErrorsForPath(unref(mainForm.errors), path),
-  );
+    filterErrorsForPath(unref(mainForm.errors), path))
 
-  const validateForm = () => mainForm.validateForm();
+  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>;
+    const fullPath = joinPath(path, subPath) as EntityPaths<T>
     return mainForm.getSubForm(
       fullPath,
       subOptions as SubformOptions<PickEntity<T, typeof fullPath>>,
-    ) as Form<PickEntity<ST, P>>;
-  };
+    ) as Form<PickEntity<ST, P>>
+  }
 
   // Reset scoped to this subform
-  const reset = () => getAllSubformFields().forEach((field) => field.reset());
+  const reset = () => getAllSubformFields().forEach(field => field.reset())
 
   const defineValidator = (
     options: ValidatorOptions<ST> | Ref<Validator<ST>>,
   ) => {
-    const subValidator = isRef(options) ? options : createValidator(options);
+    const subValidator = isRef(options) ? options : createValidator(options)
     const validator = computed(
       () => new NestedValidator<T, K>(path, unref(subValidator)),
-    );
+    )
 
-    mainForm.defineValidator(validator);
+    mainForm.defineValidator(validator)
 
-    return subValidator;
-  };
+    return subValidator
+  }
 
-  const subFormInterface: Omit<Form<ST>, "submitHandler"> = {
+  const subForm: Form<ST> = {
     data: data,
     fields,
     initialData,
@@ -205,12 +202,11 @@ export function createSubformInterface<
     reset,
     validateForm,
     getSubForm,
-  };
-
-  const submitHandler = useSubmitHandler(subFormInterface, formOptions ?? {});
+    submitHandler: onSubmit => makeSubmitHandler(subForm, formOptions ?? {})(onSubmit),
+    useFieldArray: (fieldArrayPath, fieldArrayOptions) => {
+      return useFieldArray(subForm, fieldArrayPath, fieldArrayOptions)
+    },
+  }
 
-  return {
-    ...subFormInterface,
-    submitHandler,
-  };
+  return subForm
 }

package/src/types/form.ts

@@ -14,6 +14,24 @@ import type {
 
 export type FormDataDefault = object
 
+export type HashFn<H, I> = (item: I) => H
+
+export interface FieldArrayOptions<Item> {
+  hashFn?: HashFn<unknown, Item>
+}
+
+export interface FieldArray<Item> {
+  fields: Ref<{
+    id: string
+    item: Item
+  }[]>
+  push: (item: Item) => void
+  remove: (item: Item) => void
+  removeByIndex: (index: number) => void
+  errors: Ref<ValidationErrors>
+  dirty: Ref<boolean>
+}
+
 export interface FormField<T, P extends string> {
   data: Ref<T>
   path: Ref<P>
@@ -81,4 +99,12 @@ export interface Form<T extends FormDataDefault> {
     path: P,
     options?: SubformOptions<PickEntity<T, P>>,
   ) => Form<PickEntity<T, P>>
+
+  // Field arrays
+  useFieldArray: <K extends Paths<T>>(
+    path: PickProps<T, K> extends unknown[] ? K : never,
+    options?: FieldArrayOptions<
+      PickProps<T, K> extends (infer U)[] ? U : never
+    >,
+  ) => FieldArray<PickProps<T, K> extends (infer U)[] ? U : never>
 }

package/src/{composables/useSubmitHandler.ts → utils/submitHandler.ts}

@@ -7,8 +7,8 @@ interface SubmitHandlerOptions {
   validationStrategy?: MaybeRef<ValidationStrategy>
 }
 
-export function useSubmitHandler<T extends FormDataDefault>(
-  form: Omit<Form<T>, 'submitHandler'>,
+export function makeSubmitHandler<T extends FormDataDefault>(
+  form: Form<T>,
   options: SubmitHandlerOptions,
 ) {
   return (onSubmit: (data: T) => Awaitable<void>) => {

package/tests/useFieldArray.test.ts

@@ -0,0 +1,381 @@
+import { describe, expect, it } from 'vitest'
+import { nextTick } from 'vue'
+import { useForm } from '../src/composables/useForm'
+import { HashStore, useFieldArray } from '../src/composables/useFieldArray'
+
+describe('useFieldArray', () => {
+  describe('HashStore', () => {
+    it('should store and retrieve primitive values with identity hash', () => {
+      const store = new HashStore<string[]>()
+
+      store.set(5, ['id-1'])
+      expect(store.has(5)).toBe(true)
+      expect(store.get(5)).toEqual(['id-1'])
+
+      store.set(10, ['id-2'])
+      expect(store.get(10)).toEqual(['id-2'])
+      expect(store.get(5)).toEqual(['id-1'])
+    })
+
+    it('should store objects by reference with identity hash', () => {
+      const store = new HashStore<string[]>()
+      const obj1 = {
+        id: 1,
+        name: 'A',
+      }
+      const obj2 = {
+        id: 1,
+        name: 'A',
+      } // Same content, different reference
+
+      store.set(obj1, ['uuid-1'])
+
+      expect(store.has(obj1)).toBe(true)
+      expect(store.has(obj2)).toBe(false)
+      expect(store.get(obj1)).toEqual(['uuid-1'])
+      expect(store.get(obj2)).toBeUndefined()
+    })
+
+    it('should use custom hash function for semantic equality', () => {
+      const store = new HashStore<string[], { id: number }>(item => item.id)
+      const obj1 = {
+        id: 1,
+        name: 'A',
+      }
+      const obj2 = {
+        id: 1,
+        name: 'B',
+      } // Same ID, different name
+      const obj3 = {
+        id: 2,
+        name: 'A',
+      }
+
+      store.set(obj1, ['uuid-1'])
+
+      expect(store.has(obj2)).toBe(true)
+      expect(store.get(obj2)).toEqual(['uuid-1'])
+      expect(store.has(obj3)).toBe(false)
+    })
+
+    it('should overwrite value on subsequent set calls', () => {
+      const store = new HashStore<string[]>()
+      const item = { id: 1 }
+
+      store.set(item, ['id-1'])
+      expect(store.get(item)).toEqual(['id-1'])
+
+      store.set(item, ['id-1', 'id-2'])
+      expect(store.get(item)).toEqual(['id-1', 'id-2'])
+    })
+  })
+
+  describe('Core Functionality', () => {
+    it('should initialize with array data and generate IDs', () => {
+      const form = useForm({
+        initialData: {
+          items: [
+            {
+              id: 1,
+              name: 'Item 1',
+            },
+            {
+              id: 2,
+              name: 'Item 2',
+            },
+          ],
+        },
+      })
+      const fieldArray = useFieldArray(form, 'items')
+
+      expect(fieldArray.fields.value).toHaveLength(2)
+      expect(fieldArray.fields.value[0]).toHaveProperty('id')
+      expect(fieldArray.fields.value[0]).toHaveProperty('item')
+      expect(fieldArray.fields.value[0].item).toEqual({
+        id: 1,
+        name: 'Item 1',
+      })
+      expect(typeof fieldArray.fields.value[0].id).toBe('string')
+      expect(fieldArray.errors.value).toEqual([])
+      expect(fieldArray.dirty.value).toBe(false)
+    })
+
+    it('should push new items to the array', async () => {
+      const form = useForm({
+        initialData: {
+          items: [
+            {
+              id: 1,
+              name: 'First',
+            },
+          ],
+        },
+      })
+      const fieldArray = useFieldArray(form, 'items')
+
+      expect(fieldArray.fields.value).toHaveLength(1)
+
+      fieldArray.push({
+        id: 2,
+        name: 'Second',
+      })
+      await nextTick()
+
+      expect(fieldArray.fields.value).toHaveLength(2)
+      expect(fieldArray.fields.value[1].item).toEqual({
+        id: 2,
+        name: 'Second',
+      })
+      expect(fieldArray.dirty.value).toBe(true)
+    })
+
+    it('should remove item by reference', async () => {
+      const form = useForm({
+        initialData: {
+          items: [
+            {
+              id: 1,
+              name: 'Keep',
+            },
+            {
+              id: 2,
+              name: 'Remove',
+            },
+          ],
+        },
+      })
+      const fieldArray = useFieldArray(form, 'items')
+      const itemToRemove = fieldArray.fields.value[1].item
+
+      fieldArray.remove(itemToRemove)
+      await nextTick()
+
+      expect(fieldArray.fields.value).toHaveLength(1)
+      expect(fieldArray.fields.value[0].item.name).toBe('Keep')
+      expect(fieldArray.dirty.value).toBe(true)
+    })
+
+    it('should remove item by index', async () => {
+      const form = useForm({
+        initialData: {
+          items: [
+            {
+              id: 1,
+              name: 'First',
+            },
+            {
+              id: 2,
+              name: 'Second',
+            },
+            {
+              id: 3,
+              name: 'Third',
+            },
+          ],
+        },
+      })
+      const fieldArray = useFieldArray(form, 'items')
+
+      fieldArray.removeByIndex(1)
+      await nextTick()
+
+      expect(fieldArray.fields.value).toHaveLength(2)
+      expect(fieldArray.fields.value[0].item.name).toBe('First')
+      expect(fieldArray.fields.value[1].item.name).toBe('Third')
+    })
+  })
+
+  describe('ID Persistence', () => {
+    it('should maintain IDs when items are reordered', async () => {
+      const form = useForm({
+        initialData: {
+          items: [
+            {
+              id: 1,
+              name: 'First',
+            },
+            {
+              id: 2,
+              name: 'Second',
+            },
+            {
+              id: 3,
+              name: 'Third',
+            },
+          ],
+        },
+      })
+      const fieldArray = useFieldArray(form, 'items', {
+        hashFn: (item: { id: number }) => item.id,
+      })
+
+      // Capture initial IDs
+      const id1 = fieldArray.fields.value[0].id
+      const id2 = fieldArray.fields.value[1].id
+      const id3 = fieldArray.fields.value[2].id
+
+      // Reverse the array
+      const arrayField = form.getField('items')
+      arrayField.setData([...arrayField.data.value].reverse())
+      await nextTick()
+
+      // Verify order changed but IDs followed the items
+      expect(fieldArray.fields.value[0].item.name).toBe('Third')
+      expect(fieldArray.fields.value[0].id).toBe(id3)
+      expect(fieldArray.fields.value[1].item.name).toBe('Second')
+      expect(fieldArray.fields.value[1].id).toBe(id2)
+      expect(fieldArray.fields.value[2].item.name).toBe('First')
+      expect(fieldArray.fields.value[2].id).toBe(id1)
+    })
+
+    it('should maintain IDs based on custom hash function', async () => {
+      const form = useForm({
+        initialData: {
+          products: [
+            {
+              sku: 'ABC',
+              name: 'Widget',
+              price: 10,
+            },
+            {
+              sku: 'DEF',
+              name: 'Gadget',
+              price: 20,
+            },
+          ],
+        },
+      })
+      const fieldArray = useFieldArray(form, 'products', {
+        hashFn: (item: { sku: string }) => item.sku,
+      })
+
+      const idABC = fieldArray.fields.value[0].id
+      const idDEF = fieldArray.fields.value[1].id
+
+      // Update price and swap order
+      const arrayField = form.getField('products')
+      arrayField.setData([
+        {
+          sku: 'DEF',
+          name: 'Gadget',
+          price: 25,
+        },
+        {
+          sku: 'ABC',
+          name: 'Widget',
+          price: 15,
+        },
+      ])
+      await nextTick()
+
+      // IDs should persist because SKUs didn't change
+      expect(fieldArray.fields.value[0].id).toBe(idDEF)
+      expect(fieldArray.fields.value[1].id).toBe(idABC)
+
+      // Change SKU - should get new ID
+      arrayField.setData([
+        {
+          sku: 'XYZ',
+          name: 'Widget',
+          price: 15,
+        },
+        {
+          sku: 'DEF',
+          name: 'Gadget',
+          price: 25,
+        },
+      ])
+      await nextTick()
+
+      expect(fieldArray.fields.value[0].id).not.toBe(idABC)
+      expect(fieldArray.fields.value[1].id).toBe(idDEF)
+    })
+
+    it('should assign IDs in order for items with same hash', async () => {
+      // When multiple items share the same hash, IDs are assigned in order
+      // from the stored ID list. This means reordering items with same hash
+      // will NOT preserve ID-to-item mapping (IDs follow position, not identity).
+      const form = useForm({
+        initialData: {
+          items: [
+            {
+              type: 'tag',
+              value: 'vue',
+            },
+            {
+              type: 'tag',
+              value: 'react',
+            },
+            {
+              type: 'tag',
+              value: 'svelte',
+            },
+          ],
+        },
+      })
+      // Hash by type only - all items have same hash 'tag'
+      const fieldArray = useFieldArray(form, 'items', {
+        hashFn: (item: { type: string }) => item.type,
+      })
+
+      // All items get unique IDs despite same hash
+      const [id1, id2, id3] = fieldArray.fields.value.map(f => f.id)
+      expect(new Set([id1, id2, id3]).size).toBe(3)
+
+      // Reorder: move last item to first position
+      const arrayField = form.getField('items')
+      arrayField.setData([
+        {
+          type: 'tag',
+          value: 'svelte',
+        },
+        {
+          type: 'tag',
+          value: 'vue',
+        },
+        {
+          type: 'tag',
+          value: 'react',
+        },
+      ])
+      await nextTick()
+
+      // IDs are assigned in order from stored list, NOT following items
+      // This is expected behavior with hash collisions
+      expect(fieldArray.fields.value[0].id).toBe(id1) // svelte gets id1 (was vue's)
+      expect(fieldArray.fields.value[1].id).toBe(id2) // vue gets id2 (was react's)
+      expect(fieldArray.fields.value[2].id).toBe(id3) // react gets id3 (was svelte's)
+
+      // The values confirm the reorder happened
+      expect(fieldArray.fields.value[0].item.value).toBe('svelte')
+      expect(fieldArray.fields.value[1].item.value).toBe('vue')
+      expect(fieldArray.fields.value[2].item.value).toBe('react')
+    })
+  })
+
+  describe('Form Integration', () => {
+    it('should track dirty state correctly', async () => {
+      const form = useForm({
+        initialData: { items: [{ name: 'Item' }] },
+      })
+      const fieldArray = useFieldArray(form, 'items')
+
+      expect(form.isDirty.value).toBe(false)
+      expect(fieldArray.dirty.value).toBe(false)
+
+      // Make a change
+      fieldArray.push({ name: 'New Item' })
+      await nextTick()
+
+      expect(form.isDirty.value).toBe(true)
+      expect(fieldArray.dirty.value).toBe(true)
+
+      // Reset form
+      form.reset()
+      await nextTick()
+
+      expect(form.isDirty.value).toBe(false)
+      expect(fieldArray.dirty.value).toBe(false)
+    })
+  })
+})