Merge pull request #42 from kevinkosterr/master

Pending release

Author: kevinkosterr

apps/docs/.vitepress/config.mts

@@ -1,5 +1,6 @@
 import { defineConfig } from 'vitepress'
 import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-icons'
+import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
 import path from 'path'
 
 // https://vitepress.dev/reference/site-config
@@ -11,6 +12,7 @@ export default defineConfig({
   markdown: {
     config(md) {
       md.use(groupIconMdPlugin)
+      md.use(tabsMarkdownPlugin)
     }
   },
   themeConfig: {
@@ -34,14 +36,22 @@ export default defineConfig({
           { text: 'Custom validators', link: '/guide/customization/custom-validators' }
         ]
       },
+      {
+        text: 'Components',
+        items: [
+          { text: 'FormLabel', link: '/guide/components/FormLabel' },
+        ]
+      },
       {
         text: 'Composables',
         items: [
           { text: 'useFieldAttributes', link: '/guide/composables/useFieldAttributes' },
           { text: 'useFieldEmits', link: '/guide/composables/useFieldEmits' },
           { text: 'useFieldProps', link: '/guide/composables/useFieldProps' },
           { text: 'useFieldValidate', link: '/guide/composables/useFieldValidate' },
-          { text: 'useFormModel', link: '/guide/composables/useFormModel' }
+          { text: 'useFormModel', link: '/guide/composables/useFormModel' },
+          { text: 'useLabelIcon', link: '/guide/composables/useLabelIcon' },
+          { text: 'useValidation', link: '/guide/composables/useValidation' }
         ]
       },
       {

apps/docs/.vitepress/theme/index.js

@@ -1,13 +1,16 @@
 import DefaultTheme from 'vitepress/theme'
 import VueFormGenerator from '@/index'
 
+import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
+
 import './index.css'
 import '@/scss/themes/basic.scss'
 import 'virtual:group-icons.css'
 
 export default {
   extends: DefaultTheme,
   enhanceApp({ app }) {
+    enhanceAppWithTabs(app)
     app.use(VueFormGenerator, {
       messages: {
         productCodeValidator: 'Your product code is invalid'

apps/docs/guide/components/FormLabel.md

@@ -0,0 +1,43 @@
+---
+outline: [2,3]
+---
+# FormLabel <Badge type="tip" text=">=2.7.0"/>
+> A label component that automatically handles the labelIcon property and position.
+
+## Usage
+:::code-group
+```vue [template]
+<template>
+  <FormLabel 
+      :label-icon="labelIcon" 
+      :label-icon-position="labelIconPosition" 
+      :label="field.label" 
+      :field-id="props.id"
+  />
+</template>
+```
+```vue [script setup]
+<script setup>
+import { toRefs } from 'vue'
+import { FormLabel, useLabelIcon, useFieldProps } from '@kevinkosterr/vue3-form-generator'
+
+const props = defineProps(useFieldProps())
+
+const { field, model } = toRefs(props)
+const { labelIcon, labelIconPosition } = useLabelIcon(field.value.labelIcon)
+</script>
+```
+:::
+
+## Props
+### `labelIcon` <Badge type="info" text="string | ComponentPublicInstance | null" />
+Either a string webfont class, a component or `LabelIconDefinition`.
+
+### `labelIconPosition` <Badge type="info" text="'left' | 'right' | null" />
+Either `'left'`, `'right'` or `null`
+
+### `label` <Badge type="info" text="string" />
+Label as set by the field schema.
+
+### `fieldId` <Badge type="info" text="string" />
+Computed field id, taken from props.

apps/docs/guide/composables/useFieldEmits.md

@@ -13,6 +13,15 @@ const emits = defineEmits(useFieldEmits())
 </script>
 ```
 
+## TypeScript alternative
+```vue
+<script setup lang="ts">
+import type { FieldEmits } from '@kevinkosterr/vue3-form-generator'
+  
+const emits = defineEmits<FieldEmits>()
+</script>
+```
+
 ## Emits
 
 ### `onInput`

apps/docs/guide/composables/useFieldProps.md

@@ -16,6 +16,20 @@ const { field, model } = toRefs(props)
 </script>
 ```
 
+## TypeScript alternative
+```vue
+<script setup lang="ts">
+import { toRefs } from 'vue'
+import type { FieldProps, FieldBase, FieldPropRefs } from '@kevinkosterr/vue3-form-generator'
+
+type CustomField = FieldBase & {}
+
+const props = defineProps<FieldProps<CustomField>>()
+  
+const { field, model }: FieldPropRefs<CustomField> = toRefs(props)
+</script>
+```
+
 ## Props
 
 ### `id` <Badge type="info" text="String"/>

apps/docs/guide/composables/useFieldValidate.md

@@ -1,8 +1,11 @@
 ---
 outline: [2,3]
 ---
-# useFieldValidate <Badge type="tip" text="2.0.0+"/>
-> Used to validate a field against validators defined in a fields schema
+# useFieldValidate <Badge type="tip" text="2.0.0+"/> <Badge type="warning" text="deprecated"/>
+> Used to validate a field against validators defined in a field's schema
+::: warning
+This composable is deprecated, please use [`useValidation`](/guide/composables/useValidation) instead
+:::
 
 ## Usage
 ```vue

apps/docs/guide/composables/useLabelIcon.md

@@ -0,0 +1,34 @@
+---
+outline: [2,3]
+---
+# useLabelIcon <Badge type="tip" text=">=2.7.0" />
+> Determines which icon to display and the position to display it in
+
+## Usage
+```vue
+<script setup>
+import { useLabelIcon } from '@kevinkosterr/vue3-form-generator'
+  
+const { labelIcon, labelIconPosition } = useLabelIcon(props.field.labelIcon)
+</script>
+```
+
+## Arguments
+### `iconDefinition` <Badge type="info" text="string | ComponentPublicInstance | LabelIconDefinition" />
+::: details LabelIconDefinition type
+```ts
+type LabelIconDefinition = {
+  icon: string | ComponentPublicInstance;
+  position: 'left' | 'right';
+}
+```
+:::
+Either a string webfont class, a component or `LabelIconDefinition`.
+
+## Returns
+
+### `labelIcon` <Badge type="info" text="ComputedRef<string | ComponentPublicInstance | null>" />
+Either the icon class or icon component as determined by the `labelIcon` property of a field schema. 
+
+### `labelIconPosition` <Badge type="info" text="ComputedRef<'left' | 'right' | null>" />
+Position of the label, defaults to `left`.

apps/docs/guide/composables/useValidation.md

@@ -0,0 +1,119 @@
+---
+outline: [2,3]
+---
+# useValidation <Badge type="tip" text=">=2.7.0"/>
+> Used to validate a field against validators defined in a field's schema
+
+## Usage
+::: code-group
+```Vue [Vue]
+<script setup>
+import { toRefs } from 'vue'
+import { 
+  useValidation, 
+  useFieldProps,
+  useFormModel,
+  useFieldEmits,
+  useFieldAttributes
+} from '@kevinkosterr/vue3-form-generator'
+
+const props = defineProps(useFieldProps())
+const emits = defineEmits(useFieldEmits())
+
+const { field, model } = toRefs(props)
+const { isRequired, isDisabled, isReadonly } = useFieldAttributes(model.value, field.value)
+const { currentModelValue } = useFormModel(model.value, field.value)
+  
+const { validate, errors, onChanged, onBlur } = useValidation(
+    model.value,
+    field.value,
+    currentModelValue,
+    props.formOptions,
+    emits,
+    isDisabled.value,
+    isRequired.value,
+    isReadonly.value
+)
+</script>
+```
+```Vue [Vue TS]
+<script setup lang="ts">
+import { toRefs } from 'vue'
+import { 
+  type FieldEmits, 
+  type FieldProps, 
+  type FieldBase,
+  type FieldPropRefs,
+  useValidation,
+  useFieldAttributes,
+  useFormModel
+} from '@kevinkosterr/vue3-form-generator'
+
+type CustomField = FieldBase & {
+  customAttr: string
+}
+
+const props = defineProps<FieldProps<CustomField>>()
+const emits = defineEmits<FieldEmits>()
+  
+const { field, model }: FieldPropRefs<CustomField> = toRefs(props)
+const { isRequired, isDisabled, isReadonly } = useFieldAttributes(model.value, field.value)
+const { currentModelValue } = useFormModel(model.value, field.value)
+
+const { validate, errors, onChanged, onBlur } = useValidation(
+    model.value,
+    field.value,
+    currentModelValue,
+    props.formOptions,
+    emits,
+    isDisabled.value,
+    isRequired.value,
+    isReadonly.value
+)
+</script>
+```
+:::
+
+## Arguments
+
+### `model` <Badge type="info" text="Object"/>
+Model object, as returned by the props
+
+### `field` <Badge type="info" text="Object"/>
+Field schema object, as returned by the props
+
+### `currentModelValue` <Badge type="info" text="Ref<any>"/>
+`Ref` of the current value from the field. Returned by [`useFormModel`](/guide/composables/useFormModel).
+
+### `formOptions` <Badge type="info" text="Object"/>
+Form options object, as returned by the props.
+
+### `emits` <Badge type="info" text="EmitFn<FieldEmits>"/>
+Emit function as returned by `defineEmits()`
+
+### `isDisabled` <Badge type="info" text="Boolean"/>
+Whether the field is disabled, can be obtained from [`useFieldAttributes()`](/guide/composables/useFieldAttributes)
+
+### `isRequired` <Badge type="info" text="Boolean"/>
+Whether the field is required, can be obtained from [`useFieldAttributes()`](/guide/composables/useFieldAttributes)
+
+### `isReadonly` <Badge type="info" text="Boolean"/>
+Whether the field is readonly, can be obtained from [`useFieldAttributes()`](/guide/composables/useFieldAttributes)
+
+## Returns
+
+### `errors` <Badge type="info" text="string[]"/>
+An array of errors for the current field. Will be auto-updated on every validation cycle. Must be cleared
+manually when the value of a field has changed.
+
+### `validate` <Badge type="info" text="Function"/>
+A validation function, meant to be called when a validation has to take place. Used when a field is always validated
+at the same moment and isn't affected by validation triggers, such as `'onChanged'` or `'onBlur'`.
+
+### `onChanged` <Badge type="info" text="Function"/>
+A wrapped validation function, only validates when `'onChanged'` validation is enabled. Should always be called if the value is changed, unless the field is unaffected by
+validation triggers.
+
+### `onBlur` <Badge type="info" text="Function"/>
+A wrapped validation function, only validates when `'onBlur'` validation is enabled (which is the default behavior). Should always be called if the value is changed, unless the field is unaffected by
+validation triggers.