@teamnovu/kit-vue-forms 0.2.16 → 0.2.17

package/dist/index.js

@@ -290,7 +290,7 @@ function Pe(r, t, e) {
     s.set(o, i);
   }, v = (i) => {
     var o;
-    n != null && n.keepValuesOnUnmount || (o = s.get(i)) == null || o.reset(), s.delete(i);
+    h((n == null ? void 0 : n.keepValuesOnUnmount) ?? !0) || (o = s.get(i)) == null || o.reset(), s.delete(i);
   }, y = (i) => {
     var o;
     a.has(i) ? (o = a.get(i)) == null || o.inc() : a.set(i, new Re(() => v(i)));

package/docs/FormInput-example.md

@@ -16,43 +16,54 @@ In the example below we use a text field `TextField.vue`.
 
 Example:
 ```vue
-<!-- FormTextInput.vue -->
+<!-- FormTextField.vue -->
 <template>
   <FormFieldWrapper
     :component="TextField"
-    :component-props="$props"
-    :path="path"
+    :component-props="omit($props, 'form', 'path')"
     :form="form"
-  />
+    :path="path"
+  >
+    <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>
+  </FormFieldWrapper>
 </template>
 
-<script setup lang="ts" generic="TData extends object, TPath extends Paths<TData>">
-import type { TextFieldProps } from '#components/utils/form/plainInput/TextField.vue';
-import TextField from '#components/utils/form/plainInput/TextField.vue';
-import { type Paths, FormFieldWrapper } from '@teamnovu/kit-vue-forms';
-import type {
-  ExcludedFieldProps,
-  FormComponentProps,
-} from '#types/form/FormComponentProps';
+<script setup lang="ts" generic="TData extends object, TPath extends Paths<TData>, TDataOut = TData">
+import TextField, { type TextFieldProps } from '#components/utils/form/plainInput/TextField.vue'
+import { FormFieldWrapper, type ExcludedFieldProps, type FormComponentProps, type Paths } from '@teamnovu/kit-vue-forms'
+import { omit } from 'lodash-es'
 
-export type Props<TData extends object, TPath extends Paths<TData>> =
-  FormComponentProps<TData, TPath, TextFieldProps['modelValue']> & Omit<TextFieldProps, ExcludedFieldProps>;
+export type Props<
+  TData extends object,
+  TPath extends Paths<TData>,
+  TDataOut = TData,
+> = FormComponentProps<TData, TPath, TextFieldProps['modelValue'], TDataOut> & Omit<TextFieldProps, ExcludedFieldProps>
 
-defineProps<Props<TData, TPath>>();
+defineProps<Props<TData, TPath, TDataOut>>()
 </script>
 ```
-Note the usage of the generic types `TData` and `TPath` to make the component fully type-safe. With this, the `path` prop
+Note the usage of the generic types `TData`, `TPath`, and `TDataOut` to make the component fully type-safe. With this, the `path` prop
 will only allow valid paths of the form data. Moreover, it will throw a type error if the property at `path` of the `form`
 has the wrong type. This is ensured by using the `FormComponentProps` type above.
 
+The `omit($props, 'form', 'path')` ensures that only the underlying component's props are passed through.
+The slot forwarding pattern allows slots defined on the form input to be passed to the underlying plain input component.
+
 The usage of such a form input component is as follows (assuming the input should handle the "firstName" property of the form data):
 ```vue
-<FormTextInput 
+<FormTextField
   :form="form"
   path="firstName"
 />
 ```
-Here, `form` is the Form component that was created with [`useForm`](index.md#useform). All additional props are passed
+Here, `form` is the form object that was created with [`useForm`](./reference.md#composable-useform). All additional props are passed
 to the underlying plain input component, e.g. `label`, `placeholder`, etc.
 
 It is recommended to use this pattern of a styled "plain input" that works with v-model and a "form input" to work with form

package/docs/example.md

@@ -20,7 +20,7 @@ We can create a form like this:
 
 ```vue
 <template>
-  <form @submit.prevent="submit">
+  <form @submit="form.submitHandler(sendToBackend)">
     <!-- Simple form inputs -->
     <!-- the "label" prop is passed through the FormTextField to the underlying TextField -->
     <FormTextField
@@ -56,13 +56,15 @@ We can create a form like this:
       <FormAddressField :form="subform" />
     </FormPart>
 
-    <div v-for="(_, index) in unref(form.data).person.hobbies" :key="index" class="ml-4">
-      <!-- Note the path format of an array item. You just use the index number in the dot-path -->
+    <!-- Using getFieldArray for dynamic lists with add/remove functionality -->
+    <div v-for="field in hobbies.items.value" :key="field.id" class="ml-4">
       <FormTextField
           :form="form"
-          :path="`person.hobbies.${index}`"
+          :path="field.path"
       />
+      <button type="button" @click="hobbies.remove(field.id)">Remove</button>
     </div>
+    <button type="button" @click="hobbies.push('')">Add Hobby</button>
 
     <button type="button" @click="toggleComment">
       Toggle Comment
@@ -151,20 +153,12 @@ const form = useForm<{ // this type might be inferred automatically from the ini
   }),
 });
 
-const sendToBackend = async (data) => {
-  // send data object to backend
-};
-
-const submit = async () => {
-  // validate the form
-  // if the zod schema is not satisfied, isValid will be false and the errors will be set on the corresponding fields
-  // if your TextInput component handles errors correctly, it should be directly visible
-  const { isValid } = await form.validateForm();
+// getFieldArray for managing the hobbies list
+const hobbies = form.getFieldArray('person.hobbies');
 
-  // only submit if the form is valid
-  if (isValid) {
-    await sendToBackend(unref(form.data));
-  }
+const sendToBackend = async (data) => {
+  // send validated data object to backend
+  // note: data is the validated/transformed output type (TOut)
 };
 
 // To programmatically change form values, use form.getField to get a ref and a setter function

package/docs/index.md

@@ -16,9 +16,10 @@ but pass it down as a prop to guarantee type safety.
 ## Usage
 
 1. Wrap your plain input components into `FormFieldWrapper`, see [FormInput Example](./FormInput-example.md).
-2. Inside your parent component where you want to use a form, use the composable `useForm` to create a form object. 
-This object contains the form data, errors, and methods to define
-fields, validate the form, reset it, and create subforms for nested objects or arrays, see [here](./reference#composable-useform).
+2. Inside your parent component where you want to use a form, use the composable `useForm` to create a form object.
+This object contains the form data, errors, and methods to define fields, validate the form, reset it,
+create subforms for nested objects, and manage dynamic lists with `getFieldArray`.
+Use `submitHandler` for form submission with automatic validation, see [here](./reference#composable-useform).
 3. Pass this form object to any form input component together with a path to the property of the form data that this input
 should manage. You can also make subforms, pass the form down to child components, etc. See the examples for inspiration.
 4. See Reference documentation for all types and methods: [here](./reference.md).

package/docs/reference.md

@@ -2,35 +2,53 @@
 ## Composable `useForm`
 This is the main composable which creates the form. It has the following signature:
 ```typescript
-function useForm<T extends object>(options: {
+function useForm<T extends object, TOut = T>(options: {
   // the initial data of the form
   // reactive changes to this object will propagate to the form data
   initialData: MaybeRefOrGetter<T>
   // an ErrorBag object or ref of an ErrorBag object with external errors
   // this is used e.g. for server side validation errors
-  // these errors will be merged with the internal errors of the form based on validationFn below and/or the zod schema
+  // these errors will be merged with the internal errors of the form based on validateFn below and/or the zod schema
   errors?: MaybeRef<ErrorBag | undefined>
   // a zod schema of the form data
-  // this is validated based on the validationStrategy or by manually triggering validateForm on the form object 
-  schema?: MaybeRef<z.ZodType>
+  // this is validated based on the validation flags or by manually triggering validateForm on the form object
+  // TOut is inferred from the schema's output type if provided
+  schema?: MaybeRef<z.ZodType<TOut>>
   // a custom validation function which is called with the current form data
   // this is additional to the schema for custom validations
-  validateFn?: MaybeRef<ValidationFunction<T>>
+  validateFn?: MaybeRef<ValidationFunction<T, TOut>>
   // if the form data of a property should be reset or kept if all fields corresponding to this property are unmounted
+  // defaults to true
   keepValuesOnUnmount?: MaybeRef<boolean>
-  // when validation should be done (on touch, pre submit, etc.)
-  validationStrategy?: MaybeRef<ValidationStrategy>
-}): Form<T>
+  // validation flags before first submit (defaults: validateOnSubmit: true, all others: false)
+  validationBeforeSubmit?: ValidationFlags
+  // validation flags after first submit (defaults: validateOnSubmit: true, validateOnDataChange: true, validateOnFieldRegister: true)
+  validationAfterSubmit?: ValidationFlags
+}): Form<T, TOut>
 ```
-This composable returns a `Form<T>` object.
+This composable returns a `Form<T, TOut>` object.
 
-## Type `Form<T>`
+## Type `ValidationFlags`
+Controls when validation is triggered:
+```typescript
+interface ValidationFlags {
+  validateOnBlur?: MaybeRefOrGetter<boolean>
+  validateOnFormOpen?: MaybeRefOrGetter<boolean>
+  validateOnSubmit?: MaybeRefOrGetter<boolean>
+  validateOnDataChange?: MaybeRefOrGetter<boolean>
+  validateOnFieldRegister?: MaybeRefOrGetter<boolean>
+}
+```
+
+## Type `Form<T, TOut>`
 Here, `T` is the type of the form data, which is inferred from the `initialData` property of the options object passed to `useForm`.
+`TOut` is the output type after validation/transformation. When a zod schema is provided, `TOut` is a merge of `T` with the schema's output type,
+where the schema type takes precedence for properties it defines, and `T` provides types for properties unknown to the schema.
 You can also explicitly provide a type argument to `useForm<T>` if needed (useful if the initial data is an empty object `{}`).
 
 This object has the following properties and methods:
 ```typescript
-interface Form<T extends object> {
+interface Form<T extends object, TOut = T> {
   // the current working data of the form
   // this might differ from initialData if the user has changed some values
   data: Ref<T>
@@ -66,21 +84,35 @@ interface Form<T extends object> {
   // defines a custom validator for the form
   // with this, a subcomponent might add a validator function and/or schema to the form
   // without needing access to the initial useForm call
-  defineValidator: <TData extends T>(options: ValidatorOptions<TData> | Ref<Validator<TData>>) => Ref<Validator<TData> | undefined>
+  defineValidator: <TData extends T, TDataOut extends TOut>(
+    options: ValidatorOptions<TData, TDataOut> | Ref<Validator<TData, TDataOut>>
+  ) => Ref<Validator<TData, TDataOut> | undefined>
 
   // resets the form data and errors, as well as the dirty, touched etc. state of all fields
   reset: () => void
   // manually triggers validation of the form data based on schema and/or validateFn
-  validateForm: () => Promise<ValidationResult>
+  // returns the validation result with errors and parsed data (if valid)
+  validateForm: () => Promise<ValidationResult<TOut>>
+
+  // creates a submit handler that validates the form before calling onSubmit
+  // onSubmit receives the validated/transformed data (TOut)
+  submitHandler: (onSubmit: (data: TOut) => Awaitable<void>) => (event: SubmitEvent) => Promise<void>
 
   // creates a subform for a nested object or array property of the form data
-  // the subform is again a Form<T> object, where T is the type of the nested property
+  // the subform is again a Form object, where T is the type of the nested property
   // it will contain all errors that have paths starting with the path of the subform
   // changes to the subform data will propagate to the main form data and vice versa
   getSubForm: <P extends EntityPaths<T>>(
       path: P,
       options?: SubformOptions<PickEntity<T, P>>,
   ) => Form<PickEntity<T, P>>
+
+  // creates a field array for managing dynamic lists
+  // see the Field Arrays section below for details
+  getFieldArray: <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, K>
 }
 ```
 
@@ -98,6 +130,33 @@ interface ErrorBag {
 }
 ```
 
+## Field Arrays
+For managing dynamic lists (add, remove, reorder items), use `getFieldArray`. It provides stable IDs for each item,
+which is important for efficient Vue rendering with `v-for`.
+
+```typescript
+const hobbies = form.getFieldArray('person.hobbies')
+
+// add item
+hobbies.push('new hobby')
+
+// remove by id
+hobbies.remove(hobbies.items.value[0].id)
+```
+```vue
+<div v-for="field in hobbies.items.value" :key="field.id">
+  <FormTextField :form="form" :path="field.path" />
+  <button @click="hobbies.remove(field.id)">Remove</button>
+</div>
+```
+
+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', {
+  hashFn: (item) => item.id
+})
+```
+
 ## Component `FormPart`
 A component to define a subform part for a nested object or array property of the form data. This corresponds to the
 `getSubForm` method of the `Form<T>` object, but in component form to be easily used in the template. An example usage is as follows:

package/package.json

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

package/src/composables/useFieldRegistry.ts

@@ -82,7 +82,7 @@ export function useFieldRegistry<T extends FormDataDefault, TOut = T>(
 ) {
   const fieldReferenceCounter = new Map<Paths<T>, Rc>()
   const fields = shallowReactive(new Map()) as FieldRegistryCache<T>
-  const registryOptions = {
+  const registryOptions: FieldRegistryOptions = {
     ...optionDefaults,
     ...fieldRegistryOptions,
   }
@@ -95,7 +95,7 @@ export function useFieldRegistry<T extends FormDataDefault, TOut = T>(
   }
 
   const deregisterField = (path: Paths<T>) => {
-    if (!registryOptions?.keepValuesOnUnmount) {
+    if (!unref(registryOptions?.keepValuesOnUnmount ?? true)) {
       fields.get(path)?.reset()
     }
     fields.delete(path)

package/tests/useForm.test.ts

@@ -397,7 +397,9 @@ describe('useForm', () => {
       },
     })
 
-    effectScope().run(() => {
+    const scope = effectScope()
+
+    scope.run(() => {
       const nameField = form.defineField({ path: 'name' })
 
       expect(form.fields.value.length).toBe(1)
@@ -406,6 +408,8 @@ describe('useForm', () => {
       nameField.setData('Modified')
     })
 
+    scope.stop()
+
     expect(form.data.value.name).toBe('Modified')
   })