@volverjs/form-vue 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 24/Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+<div align="center">
+  
+[![volverjs](docs/static/volverjs-form.svg)](https://volverjs.github.io/form-vue)
+
+## @volverjs/form-vue
+
+`form` `form-field` `form-wrapper` `vue3` `zod` `validation`
+
+<br>
+
+#### proudly powered by
+
+<br>
+
+[![24/Consulting](docs/static/24consulting.svg)](https://24consulting.it)
+
+<br>
+
+</div>
+
+## Install
+
+```bash
+# pnpm
+pnpm add @volverjs/form-vue
+
+# yarn
+yarn add @volverjs/form-vue
+
+# npm
+npm install @volverjs/form-vue --save
+```
+
+## Usage
+
+`@volverjs/form-vue` allow you to create a Vue 3 form with [`@volverjs/ui-vue`](https://github.com/volverjs/ui-vue) components from a [Zod Object](https://zod.dev/?id=objects) schema. It provides three functions: `createForm`, `useForm` and `formFactory`.
+
+## Plugin
+
+`createForm` defines globally three components `VvForm`, `VvFormWrapper`, and `VvFormField` through a [Vue 3 Plugin](https://vuejs.org/guide/reusability/plugins.html).
+
+```typescript
+import { createApp } from 'vue'
+import { createForm } from '@volverjs/form-vue'
+import { z } from 'zod'
+
+const schema = z.object({
+  name: z.string(),
+  surname: z.string()
+})
+
+const app = createApp(App)
+const form = createForm({
+  schema
+  // lazyLoad: boolean - default false
+  // updateThrottle: number - default 500
+  // sideEffects?: (data: any) => void
+})
+
+app.use(form)
+app.mount('#app')
+```
+
+By default [`@volverjs/ui-vue`](https://github.com/volverjs/ui-vue) components must be defined globally but can be lazy loaded with `lazyLoad` option. If the schema is omitted, the plugin only share the options to the forms created with the [composable](https://github.com/volverjs/form-vue/#composable).
+
+### VvForm
+
+`VvForm` render a `form` tag and emit a `submit` event. Form data are validated on submit.
+A `valid` or `invalid` event is emitted when the form status changes.
+
+```vue
+<script lang="ts" setup>
+  const onSubmit = (formData) => {
+    // Do something with the form data
+  }
+</script>
+
+<template>
+  <VvForm @submit="onSubmit">
+    <!-- form fields -->
+    <button type="submit">Submit</button>
+  </VvForm>
+</template>
+```
+
+The submit can be triggered programmatically with the `submit()` method.
+
+```vue
+<script lang="ts" setup>
+  const formEl = ref(null)
+  const onSubmit = (formData) => {
+    // Do something with the form data
+  }
+  const submitForm = () => {
+    formEl.value.submit()
+  }
+</script>
+
+<template>
+  <VvForm @submit="onSubmit" ref="formEl">
+    <!-- form fields -->
+  </VvForm>
+  <button type="button" @click.stop="submitForm">Submit</button>
+</template>
+```
+
+Use the `v-model` directive (or only `:model-value` to set the initial value of form data) to bind the form data.
+The form data two way binding is throttled by default (500ms) to avoid performance issues.
+The throttle can be changed with the `updateThrottle` option.
+
+```vue
+<script lang="ts" setup>
+  import { ref } from 'vue'
+
+  const formData = ref({
+    name: '',
+    surname: ''
+  })
+</script>
+
+<template>
+  <VvForm v-model="formData">
+    <!-- form fields -->
+    <button type="submit">Submit</button>
+  </VvForm>
+</template>
+```
+
+### VvFormWrapper
+
+`VvFormWrapper` gives you the validation status of a part of your form.
+The wrapper status is invalid if at least one of the fields inside it is invalid.
+
+```vue
+<template>
+  <VvForm>
+    <VvFormWrapper #default="{ invalid }">
+      <div class="form-section-1">
+        <span v-if="invalid">There is a validation error</span>
+        <!-- form fields of section 1 -->
+      </div>
+    </VvFormWrapper>
+    <VvFormWrapper #default="{ invalid }">
+      <div class="form-section-2">
+        <span v-if="invalid">There is a validation error</span>
+        <!-- form fields of the section 2 -->
+      </div>
+    </VvFormWrapper>
+  </VvForm>
+</template>
+```
+
+### VvFormField
+
+`VvFormField` allow you to render a [`@volverjs/ui-vue`](https://github.com/volverjs/ui-vue) input component inside a form. It automatically bind the form data through the `name` attribute.
+
+```vue
+<template>
+  <VvForm>
+    <VvFormField type="text" name="name" label="Name" />
+    <VvFormField type="text" name="surname" label="Surname" />
+  </VvForm>
+</template>
+```
+
+For nested objects, use the `name` attribute with dot notation.
+
+```vue
+<template>
+  <VvForm>
+    <VvFormField type="text" name="shipping.address" label="Shipping address" />
+  </VvForm>
+</template>
+```
+
+The type of input component is defined by the `type` attribute.
+All the available input types are listed in the [VvFormField documentation](/docs/VvFormField.md).
+
+You can also use the `VvFormField` component to render a default slot without .
+
+```vue
+<template>
+  <VvForm>
+    <VvFormField
+      name="name"
+      #default="{
+        modelValue,
+        invalid,
+        invalidLabel,
+        formData,
+        formErrors,
+        erros,
+        onUpdate
+      }"
+    >
+      <label for="name">Name</label>
+      <input
+        id="name"
+        type="text"
+        :value="modelValue"
+        :aria-invalid="invalid"
+        :aria-errormessage="invalid ? 'name-alert' : undefined"
+        @input="onUpdate"
+      />
+      <small v-if="invalid" role="alert" id="name-alert">
+        {{ invalidLabel }}
+      </small>
+    </VvFormField>
+  </VvForm>
+</template>
+```
+
+Or a custom component.
+
+```vue
+<script lang="ts" setup>
+  import MyInput from './MyInput.vue'
+</script>
+
+<template>
+  <VvForm>
+    <VvFormField name="name" :is="MyInput" />
+  </VvForm>
+</template>
+```
+
+## Composable
+
+`useForm` can be used to create a form programmatically inside a Vue 3 Component.
+If the plugin is defined globally, the settings are inherited but can be customized.
+
+```vue
+<script lang="ts" setup>
+  import { useForm } from '@volverjs/form-vue'
+  import { z } from 'zod'
+
+  const schema = z.object({
+    name: z.string(),
+    surname: z.string()
+  })
+
+  const { VvForm, VvFormWrapper, VvFormField } = useForm(schema, {
+    // lazyLoad: boolean - default false
+    // updateThrottle: number - default 500
+    // sideEffects?: (formData: any) => void
+  })
+</script>
+
+<template>
+  <VvForm>
+    <VvFormField type="text" name="name" label="Name" />
+    <VvFormField type="text" name="surname" label="Surname" />
+  </VvForm>
+</template>
+```
+
+## Outside a Vue 3 Component
+
+`formFactory` can be used to create a form outside a Vue 3 Component.
+
+```ts
+import { formFactory } from '@volverjs/form-vue'
+import { z } from 'zod'
+
+const schema = z.object({
+  name: z.string(),
+  surname: z.string()
+})
+
+const { VvForm, VvFormWrapper, VvFormField } = formFactory(schema, {
+  // lazyLoad: boolean - default false
+  // updateThrottle: number - default 500
+  // sideEffects?: (data: any) => void
+})
+
+export default { VvForm, VvFormWrapper, VvFormField }
+```
+
+## License
+
+[MIT](http://opensource.org/licenses/MIT)

package/dist/VvForm.d.ts

@@ -0,0 +1,29 @@
+import { type InjectionKey } from 'vue';
+import type { AnyZodObject } from 'zod';
+import type { InjectedFormData } from './types';
+export declare enum FormStatus {
+    invalid = "invalid",
+    valid = "valid"
+}
+export declare const defineForm: (schema: AnyZodObject, provideKey: InjectionKey<InjectedFormData>, options?: {
+    updateThrottle?: number;
+}) => import("vue").DefineComponent<{
+    modelValue: {
+        type: ObjectConstructor;
+        default: () => {};
+    };
+}, {
+    submit: () => boolean;
+}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("valid" | "invalid" | "submit" | "update:modelValue")[], "valid" | "invalid" | "submit" | "update:modelValue", import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
+    modelValue: {
+        type: ObjectConstructor;
+        default: () => {};
+    };
+}>> & {
+    onValid?: ((...args: any[]) => any) | undefined;
+    onInvalid?: ((...args: any[]) => any) | undefined;
+    onSubmit?: ((...args: any[]) => any) | undefined;
+    "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
+}, {
+    modelValue: Record<string, any>;
+}>;

package/dist/VvFormField.d.ts

@@ -0,0 +1,3 @@
+import { type Component, type InjectionKey } from 'vue';
+import type { InjectedFormData, InjectedFormWrapperData, InjectedFormFieldData, FormComposableOptions } from './types';
+export declare const defineFormField: (formProvideKey: InjectionKey<InjectedFormData>, wrapperProvideKey: InjectionKey<InjectedFormWrapperData>, formFieldInjectionKey: InjectionKey<InjectedFormFieldData>, options?: FormComposableOptions) => Component;

package/dist/VvFormWrapper.d.ts

@@ -0,0 +1,33 @@
+import { type InjectionKey, type Ref } from 'vue';
+import type { InjectedFormData, InjectedFormWrapperData } from './types';
+export declare const defineFormWrapper: (formProvideKey: InjectionKey<InjectedFormData>, wrapperProvideKey: InjectionKey<InjectedFormWrapperData>) => import("vue").DefineComponent<{
+    name: {
+        type: StringConstructor;
+        required: true;
+    };
+    tag: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}, {
+    formProvided: InjectedFormData<Recrod<string | number, unknown>> | undefined;
+    invalid: import("vue").ComputedRef<boolean>;
+    fields: Ref<Set<string>>;
+    errors: Ref<Map<string, Record<string, {
+        _errors: string[];
+    }>>>;
+}, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("valid" | "invalid")[], "valid" | "invalid", import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
+    name: {
+        type: StringConstructor;
+        required: true;
+    };
+    tag: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}>> & {
+    onValid?: ((...args: any[]) => any) | undefined;
+    onInvalid?: ((...args: any[]) => any) | undefined;
+}, {
+    tag: string;
+}>;

package/dist/enums.d.ts

@@ -0,0 +1,23 @@
+export declare enum FormFieldType {
+    text = "text",
+    number = "number",
+    email = "email",
+    password = "password",
+    tel = "tel",
+    url = "url",
+    search = "search",
+    date = "date",
+    time = "time",
+    datetimeLocal = "datetimeLocal",
+    month = "month",
+    week = "week",
+    color = "color",
+    select = "select",
+    checkbox = "checkbox",
+    radio = "radio",
+    textarea = "textarea",
+    radioGroup = "radioGroup",
+    checkboxGroup = "checkboxGroup",
+    combobox = "combobox",
+    custom = "custom"
+}

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import { type InjectionKey, type Plugin } from 'vue';
+import type { AnyZodObject } from 'zod';
+import type { InjectedFormData, InjectedFormWrapperData, InjectedFormFieldData, FormComposableOptions, FormPluginOptions } from './types';
+export declare const formFactory: (schema: AnyZodObject, options?: FormComposableOptions) => {
+    VvForm: import("vue").DefineComponent<{
+        modelValue: {
+            type: ObjectConstructor;
+            default: () => {};
+        };
+    }, {
+        submit: () => boolean;
+    }, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("valid" | "invalid" | "submit" | "update:modelValue")[], "valid" | "invalid" | "submit" | "update:modelValue", import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
+        modelValue: {
+            type: ObjectConstructor;
+            default: () => {};
+        };
+    }>> & {
+        onValid?: ((...args: any[]) => any) | undefined;
+        onInvalid?: ((...args: any[]) => any) | undefined;
+        onSubmit?: ((...args: any[]) => any) | undefined;
+        "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
+    }, {
+        modelValue: Record<string, any>;
+    }>;
+    VvFormWrapper: import("vue").DefineComponent<{
+        name: {
+            type: StringConstructor;
+            required: true;
+        };
+        tag: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }, {
+        formProvided: InjectedFormData<Recrod<string | number, unknown>> | undefined;
+        invalid: import("vue").ComputedRef<boolean>;
+        fields: import("vue").Ref<Set<string>>;
+        errors: import("vue").Ref<Map<string, Record<string, {
+            _errors: string[];
+        }>>>;
+    }, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("valid" | "invalid")[], "valid" | "invalid", import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
+        name: {
+            type: StringConstructor;
+            required: true;
+        };
+        tag: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }>> & {
+        onValid?: ((...args: any[]) => any) | undefined;
+        onInvalid?: ((...args: any[]) => any) | undefined;
+    }, {
+        tag: string;
+    }>;
+    VvFormField: import("vue").Component<any, any, any, import("vue").ComputedOptions, import("vue").MethodOptions>;
+    formInjectionKey: InjectionKey<InjectedFormData<Recrod<string | number, unknown>>>;
+    formWrapperInjectionKey: InjectionKey<InjectedFormWrapperData>;
+    formFieldInjectionKey: InjectionKey<InjectedFormFieldData>;
+};
+export declare const pluginInjectionKey: InjectionKey<FormPluginOptions>;
+export declare const createForm: (options: FormPluginOptions) => Plugin & Partial<ReturnType<typeof useForm>>;
+export declare const useForm: (schema: AnyZodObject, options?: FormComposableOptions) => {
+    VvForm: import("vue").DefineComponent<{
+        modelValue: {
+            type: ObjectConstructor;
+            default: () => {};
+        };
+    }, {
+        submit: () => boolean;
+    }, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("valid" | "invalid" | "submit" | "update:modelValue")[], "valid" | "invalid" | "submit" | "update:modelValue", import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
+        modelValue: {
+            type: ObjectConstructor;
+            default: () => {};
+        };
+    }>> & {
+        onValid?: ((...args: any[]) => any) | undefined;
+        onInvalid?: ((...args: any[]) => any) | undefined;
+        onSubmit?: ((...args: any[]) => any) | undefined;
+        "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
+    }, {
+        modelValue: Record<string, any>;
+    }>;
+    VvFormWrapper: import("vue").DefineComponent<{
+        name: {
+            type: StringConstructor;
+            required: true;
+        };
+        tag: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }, {
+        formProvided: InjectedFormData<Recrod<string | number, unknown>> | undefined;
+        invalid: import("vue").ComputedRef<boolean>;
+        fields: import("vue").Ref<Set<string>>;
+        errors: import("vue").Ref<Map<string, Record<string, {
+            _errors: string[];
+        }>>>;
+    }, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("valid" | "invalid")[], "valid" | "invalid", import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{
+        name: {
+            type: StringConstructor;
+            required: true;
+        };
+        tag: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }>> & {
+        onValid?: ((...args: any[]) => any) | undefined;
+        onInvalid?: ((...args: any[]) => any) | undefined;
+    }, {
+        tag: string;
+    }>;
+    VvFormField: import("vue").Component<any, any, any, import("vue").ComputedOptions, import("vue").MethodOptions>;
+    formInjectionKey: InjectionKey<InjectedFormData<Recrod<string | number, unknown>>>;
+    formWrapperInjectionKey: InjectionKey<InjectedFormWrapperData>;
+    formFieldInjectionKey: InjectionKey<InjectedFormFieldData>;
+};
+export { FormFieldType } from './enums';
+export { defaultObjectBySchema } from './utils';
+export type { InjectedFormData, InjectedFormWrapperData, InjectedFormFieldData, FormComposableOptions, FormPluginOptions, };