@teamnovu/kit-vue-forms 0.1.6 → 0.1.7

package/dist/index.js

@@ -1,6 +1,6 @@
 var T = Object.defineProperty;
 var G = (t, e, r) => e in t ? T(t, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : t[e] = r;
-var F = (t, e, r) => G(t, typeof e != "symbol" ? e + "" : e, r);
+var E = (t, e, r) => G(t, typeof e != "symbol" ? e + "" : e, r);
 import { toValue as L, toRaw as Z, computed as c, unref as d, reactive as D, toRefs as N, shallowReactive as q, toRef as _, onScopeDispose as H, ref as W, watch as w, isRef as k, getCurrentScope as Q, onBeforeUnmount as X, defineComponent as j, renderSlot as O, normalizeProps as z, guardReactiveProps as B, resolveComponent as Y, createBlock as $, openBlock as A, withCtx as C, resolveDynamicComponent as x, mergeProps as ee } from "vue";
 import { cloneDeep as re } from "lodash-es";
 import "zod";
@@ -18,15 +18,12 @@ function P(t, e) {
   );
 }
 function te(t, e, r) {
-  const s = Array.isArray(e) ? e : K(e);
-  if (s.length === 0)
-    throw new Error("Path cannot be empty");
-  const o = s.at(-1), n = s.slice(0, -1).reduce(
+  const s = Array.isArray(e) ? e : K(e), o = s.at(-1), n = s.slice(0, -1).reduce(
     (p, h) => p[h],
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     t
   );
-  n[o] = r;
+  n[o] = o ? r : n;
 }
 const U = (t, e) => c({
   get() {
@@ -55,7 +52,7 @@ function se(t, e) {
 }
 class ae {
   constructor(e) {
-    F(this, "rc", 1);
+    E(this, "rc", 1);
     this.drop = e;
   }
   inc() {
@@ -121,8 +118,8 @@ function ne(t, e) {
           get() {
             return e.errors.value.propertyErrors[a] || [];
           },
-          set(E) {
-            e.errors.value.propertyErrors[a] = E;
+          set(F) {
+            e.errors.value.propertyErrors[a] = F;
           }
         })
       });
@@ -258,8 +255,8 @@ class fe {
 }
 class pe {
   constructor(e, r) {
-    F(this, "schemaValidator");
-    F(this, "functionValidator");
+    E(this, "schemaValidator");
+    E(this, "functionValidator");
     this.schema = e, this.validateFn = r, this.schemaValidator = new de(this.schema), this.functionValidator = new fe(this.validateFn);
   }
   async validate(e) {
@@ -321,7 +318,7 @@ function he(t, e) {
     ), a = i.every((v) => v.isValid);
     let { errors: u } = m;
     if (!a) {
-      const v = i.map((E) => E.errors);
+      const v = i.map((F) => F.errors);
       u = S(...v);
     }
     return {
@@ -391,7 +388,7 @@ function me(t, e, r) {
   }).map((l) => n(l))), i = () => t.fields.value.filter((l) => {
     const f = l.path.value;
     return f.startsWith(e + ".") || f === e;
-  }), a = c(() => i().some((l) => l.dirty.value)), u = c(() => i().some((l) => l.touched.value)), v = c(() => t.isValid.value), E = c(() => t.isValidated.value), J = c(() => se(d(t.errors), e));
+  }), a = c(() => i().some((l) => l.dirty.value)), u = c(() => i().some((l) => l.touched.value)), v = c(() => t.isValid.value), F = c(() => t.isValidated.value), J = c(() => se(d(t.errors), e));
   return {
     data: s,
     fields: V,
@@ -401,7 +398,7 @@ function me(t, e, r) {
     isDirty: a,
     isTouched: u,
     isValid: v,
-    isValidated: E,
+    isValidated: F,
     errors: J,
     defineValidator: (l) => {
       const f = k(l) ? l : b(l), y = c(

package/docs/FormInput-example.md

@@ -0,0 +1,59 @@
+# FormInput Example
+
+To define a form input component you need a plain input component that has at least the following props and emits:
+```typescript
+interface Props {
+  modelValue: T
+  errors?: string[] | undefined // if the input should display errors
+}
+interface Emits {
+  'update:modelValue': [T]
+}
+```
+Then we can easily use the `FormFieldWrapper` component from this package.
+
+In the example below we use a text field `TextField.vue`.
+
+Example:
+```vue
+<!-- FormTextInput.vue -->
+<template>
+  <FormFieldWrapper
+    :component="TextField"
+    :component-props="$props"
+    :path="path"
+    :form="form"
+  />
+</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';
+
+export type Props<TData extends object, TPath extends Paths<TData>> =
+  FormComponentProps<TData, TPath, TextFieldProps['modelValue']> & Omit<TextFieldProps, ExcludedFieldProps>;
+
+defineProps<Props<TData, TPath>>();
+</script>
+```
+Note the usage of the generic types `TData` and `TPath` 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 usage of such a form input component is as follows (assuming the input should handle the "firstName" property of the form data):
+```vue
+<FormTextInput 
+  :form="form"
+  path="firstName"
+/>
+```
+Here, `form` is the Form component that was created with [`useForm`](index.md#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
+and path as props for all your form inputs. Like that, you can easily use the plain component outside of forms as well.

package/docs/example.md

@@ -0,0 +1,212 @@
+# Example
+
+The following example shows how to use this library for a more complicated form with nested objects and arrays.
+The data structure of the form is as follows:
+```typescript
+{
+  person: {
+    firstName: string,
+    lastName: string | undefined,
+    address: {
+      street: string,
+      city: string,
+    },
+    hobbies: string[]
+  }
+}
+```
+
+We can create a form like this:
+
+```vue
+<template>
+  <form @submit.prevent="submit">
+    <!-- Simple form inputs -->
+    <!-- the "label" prop is passed through the FormTextField to the underlying TextField -->
+    <FormTextField
+        :form="form"
+        path="person.firstName"
+        label="First Name"
+    />
+    <FormTextField
+        :form="form"
+        path="person.lastName"
+        label="Last Name"
+    />
+
+    <!-- Oh oh, my path was wrong here, the form type does not have a property "person.middleName" -->
+    <!-- I get a typescript error that this path is not allowed
+    <FormTextField
+      :form="form"
+      path="person.middleName"
+    />
+    -->
+    <!-- Oh oh, I used a Text component (which allows "string | number | null | undefined"), but the property at the path is a boolean  -->
+    <!-- I get a typescript error that this path and form combination is not allowed
+    <FormTextField
+      :form="form"
+      path="person.isMale"
+    />
+    -->
+
+    <!-- Nested forms in subcomponents -->
+    <!-- My FormAddressField handles forms of type { street: string, city: string } -->
+    <!-- so we can make a subform for the address property of our main form -->
+    <FormPart :form="form" path="person.address" #="{ subform }">
+      <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 -->
+      <FormTextField
+          :form="form"
+          :path="`person.hobbies.${index}`"
+      />
+    </div>
+
+    <button type="button" @click="toggleComment">
+      Toggle Comment
+    </button>
+
+    <!-- If you need other data, use the data ref of the form object; don't use getField here -->
+    <!-- Alternatively, in this case you could use the variable "isCommentEnabled" that was defined in the script setup -->
+    <FormTextField
+        v-if="unref(form.data).commentEnabled"
+        :form="form"
+        path="comment"
+    />
+
+    <!-- This is a one-off special thing; I don't really want to make a FormInput out of it -->
+    <!-- I can use the Field component, or I could use form.getField in the script setup -->
+    <Field v-slot="{ data, setData, errors }" path="person.parent" :form="form">
+      <div>
+        Father: {{ data.fatherName }}
+      </div>
+      <div>
+        Mother: {{ data.motherName }}
+      </div>
+      <!-- the "errors" will be an array of strings of the errors corresponding to the property with the given path (here "person.parent") -->
+      <InputError :errors="errors" />
+      <button type="button" @click="() => setData({ fatherName: 'New Father', motherName: 'New Mother' })">
+        Change Parent Names
+      </button>
+    </Field>
+
+    <button type="submit">
+      Submit Form
+    </button>
+    
+  </form>
+</template>
+
+<script setup lang="ts">
+import { Field, useForm, FormPart } from '@teamnovu/kit-vue-forms';
+import { z } from 'zod';
+import { unref } from 'vue';
+import FormTextField from '#components/utils/form/formInput/FormTextField.vue';
+import FormAddressField from '#/FormAddressField.vue';
+import InputError from '#components/utils/form/InputError.vue';
+
+const form = useForm<{ // this type might be inferred automatically from the initialData; but here, it would not work, because lastName is not defined in the initialData
+  person: {
+    firstName: string
+    lastName?: string | undefined
+    address: {
+      street: string
+      city: string
+    }
+    hobbies: string[]
+    parent: {
+      fatherName: string
+      motherName: string
+    }
+    isMale: boolean
+  }
+  commentEnabled?: boolean
+  comment: string
+}>({
+  initialData: {
+    person: {
+      firstName: '',
+      // I don't need to define an initial value for lastName here, because it's optional; the form will still handle it correctly
+      address: {
+        street: '',
+        city: '',
+      },
+      hobbies: ['cooking', 'coding'],
+      parent: {
+        fatherName: 'Hans Müller',
+        motherName: 'Hannah Schmidt',
+      },
+      isMale: false
+    },
+    commentEnabled: false,
+    comment: '',
+  },
+  // optional zod schema for validation; might also just define part of the schema if other properties should be ignored
+  schema: z.object({
+    person: z.object({
+      hobbies: z.array(z.string().min(1, 'Hobby cannot be empty')),
+    }),
+  }),
+});
+
+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();
+
+  // only submit if the form is valid
+  if (isValid) {
+    await sendToBackend(unref(form.data));
+  }
+};
+
+// To programmatically change form values, use form.getField to get a ref and a setter function
+// never modify form.data directly
+const { data: isCommentEnabled, setData: setCommentEnabled } = form.getField('commentEnabled');
+const toggleComment = () => {
+  setCommentEnabled(!unref(isCommentEnabled));
+};
+</script>
+
+```
+
+An example of the `FormAddressField` that was used above would be:
+```vue
+<!-- FormAddressField.vue -->
+<template>
+  <div>
+    <FormTextField
+      :form="form"
+      path="street"
+      label="Street Address"
+    />
+
+    <FormTextField
+      :form="form"
+      path="city"
+      label="City"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { Form } from '@teamnovu/kit-vue-forms';
+import FormTextField from '#components/utils/form/formInput/FormTextField.vue';
+
+interface Props {
+  form: Form<{
+    street: string
+    city: string
+  }>
+}
+
+defineProps<Props>();
+</script>
+```

package/docs/index.md

@@ -0,0 +1,26 @@
+# @teamnovu/kit-vue-forms
+
+A library for data and error handling of forms, including validation with zod schemas.
+
+## Installation
+
+```bash
+pnpm add @teamnovu/kit-vue-forms
+```
+
+## Purpose
+This package provides composables and some data components to simplify the data management of forms and associated errors.
+It was designed as a replacement of Vee-Validate with more flexibility and full type safety. We don't use a provided and injected form object,
+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).
+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).
+
+An example of the most common usages can be found [here](./example.md).

package/docs/info.json

@@ -0,0 +1,3 @@
+{
+    "name": "📋 Vue Forms"
+}

package/docs/reference.md

@@ -0,0 +1,136 @@
+# Reference
+## Composable `useForm`
+This is the main composable which creates the form. It has the following signature:
+```typescript
+function useForm<T extends object>(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
+  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>
+  // 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>>
+  // 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>
+```
+This composable returns a `Form<T>` object.
+
+## Type `Form<T>`
+Here, `T` is the type of the form data, which is inferred from the `initialData` property of the options object passed to `useForm`.
+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> {
+  // the current working data of the form
+  // this might differ from initialData if the user has changed some values
+  data: Ref<T>
+  // the initial data of the form as passed to useForm
+  initialData: Readonly<Ref<T>>
+
+  // all fields of the form that are currently managed
+  fields: Ref<FieldsTuple<T>>
+
+  // defines a field such that it will be managed by the form
+  // without this, the form will not track changes, touched state or validation for this field
+  // use this like a composable
+  defineField: <P extends Paths<T>>(options: DefineFieldOptions<PickProps<T, P>, P>) => FormField<PickProps<T, P>, P>
+  // gets an already defined field by its path
+  // note: if the field was not yet defined, it will be defined automatically
+  // the output is a reactive object containing the data, errors and states as well as some methods
+  // use this like a composable
+  getField: <P extends Paths<T>>(path: P) => FormField<PickProps<T, P>, P>
+
+  // true if the form has been modified from its initial state
+  isDirty: Ref<boolean>
+  // true if any field of the form has been touched (i.e. onBlur was called on any field)
+  isTouched: Ref<boolean>
+  // true if the form data is valid based on the schema and/or the validateFn
+  isValid: Ref<boolean>
+  // true if the form has been validated at least once
+  isValidated: Ref<boolean>
+  // the ErrorBag object containing all errors of the form
+  // this is a merge of internal errors based on schema/validateFn and external errors passed to useForm
+  // the errors are structured based on the paths of the form fields
+  errors: Ref<ErrorBag>
+
+  // 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>
+
+  // 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>
+
+  // 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
+  // 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>>
+}
+```
+
+## Type `ErrorBag`
+The errors in the form are structured in an `ErrorBag` object. Most errors are tied to properties in the form. However,
+there might be cases where there are errors, that cannot be tied to one property. To account for that the `ErrorBag` satisfies the following interface:
+```typescript
+interface ErrorBag {
+  // an array of general error messages not tied to a specific property
+  general: string[] | undefined
+  // a record of property paths to arrays of error messages
+  // nested properties are dot-separated and array indices are just numbers, e.g. "person.address.street" or "person.hobbies.0.name"
+  // for subforms the errors will be all errors that start with the path of the subform
+  propertyErrors: Record<string, ValidationErrorMessage[] | undefined>
+}
+```
+
+## 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:
+```vue
+<template>
+  <FormPart :form="form" path="person.address" #="{ subform }">
+    <MyAdddressComponent :form="subform" />
+  </FormPart>
+</template>
+```
+Here, the `subform` will be a `Form` object with the type of the `address` property of the `person` object of the main form data.
+Note that the errors of the subform will only contain the errors that start with the path of the subform.
+
+## Component `Field`
+This is a helper component to access form fields. It corresponds to the `defineField` method of the `Form<T>` object,
+but in component form to be easily used in the template.
+
+An example usage is as follows:
+```vue
+<template>
+    <Field :form="form" path="firstName" #="{ data, setData, onBlur, errors }">
+        <input :value="data" @input="setData" @blur="onBlur" />
+        <div v-if="errors.length > 0">
+            <span v-for="error in errors" :key="error">{{ error }}</span>
+        </div>
+    </Field>
+</template>
+```
+
+Note: it is recommended to use the `FormFieldWrapper` component and create a reusable form input component instead.
+
+## Component `FormFieldWrapper`
+This component is a helper component to easily create form input components based on plain input components.
+See the [FormInput Example](./FormInput-example.md) for details and an example implementation of a form input component.

package/package.json

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

package/src/utils/path.ts

@@ -19,9 +19,6 @@ export function getNestedValue<T, K extends Paths<T>>(obj: T, path: K | SplitPat
 
 export function setNestedValue<T, K extends Paths<T>>(obj: T, path: K | SplitPath<K>, value: PickProps<T, K>): void {
   const keys = Array.isArray(path) ? path : splitPath(path)
-  if (keys.length === 0) {
-    throw new Error('Path cannot be empty')
-  }
 
   const lastKey = keys.at(-1)!
   const target = keys
@@ -32,7 +29,7 @@ export function setNestedValue<T, K extends Paths<T>>(obj: T, path: K | SplitPat
       obj as Record<string, any>,
     )
 
-  target[lastKey] = value
+  target[lastKey] = lastKey ? value : target
 }
 
 export const getLens = <T, K extends Paths<T>>(data: MaybeRef<T>, key: MaybeRef<K | SplitPath<K>>) => {