Skip to content

Commit ae95311

Browse files
kevinkosterrkevinkosterr
authored
Merge pull request #39 from kevinkosterr/updates
Updates
2 parents 971fd39 + 872c635 commit ae95311

40 files changed

+871
-214
lines changed

‎apps/docs/.vitepress/config.mts

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { defineConfig } from 'vitepress'
22
import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-icons'
3+
import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
34
import path from 'path'
45

56
// https://vitepress.dev/reference/site-config
@@ -11,6 +12,7 @@ export default defineConfig({
1112
markdown: {
1213
config(md) {
1314
md.use(groupIconMdPlugin)
15+
md.use(tabsMarkdownPlugin)
1416
}
1517
},
1618
themeConfig: {
@@ -41,7 +43,8 @@ export default defineConfig({
4143
{ text: 'useFieldEmits', link: '/guide/composables/useFieldEmits' },
4244
{ text: 'useFieldProps', link: '/guide/composables/useFieldProps' },
4345
{ text: 'useFieldValidate', link: '/guide/composables/useFieldValidate' },
44-
{ text: 'useFormModel', link: '/guide/composables/useFormModel' }
46+
{ text: 'useFormModel', link: '/guide/composables/useFormModel' },
47+
{ text: 'useValidation', link: '/guide/composables/useValidation' }
4548
]
4649
},
4750
{

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
11
import DefaultTheme from 'vitepress/theme'
22
import VueFormGenerator from '@/index'
33

4+
import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
5+
46
import './index.css'
57
import '@/scss/themes/basic.scss'
68
import 'virtual:group-icons.css'
79

810
export default {
911
extends: DefaultTheme,
1012
enhanceApp({ app }) {
13+
enhanceAppWithTabs(app)
1114
app.use(VueFormGenerator, {
1215
messages: {
1316
productCodeValidator: 'Your product code is invalid'

‎apps/docs/guide/composables/useFieldEmits.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,15 @@ const emits = defineEmits(useFieldEmits())
1313
</script>
1414
```
1515

16+
## TypeScript alternative
17+
```vue
18+
<script setup lang="ts">
19+
import type { FieldEmits } from '@kevinkosterr/vue3-form-generator'
20+
21+
const emits = defineEmits<FieldEmits>()
22+
</script>
23+
```
24+
1625
## Emits
1726

1827
### `onInput`

‎apps/docs/guide/composables/useFieldProps.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,20 @@ const { field, model } = toRefs(props)
1616
</script>
1717
```
1818

19+
## TypeScript alternative
20+
```vue
21+
<script setup lang="ts">
22+
import { toRefs } from 'vue'
23+
import type { FieldProps, FieldBase, FieldPropRefs } from '@kevinkosterr/vue3-form-generator'
24+
25+
type CustomField = FieldBase & {}
26+
27+
const props = defineProps<FieldProps<CustomField>>()
28+
29+
const { field, model }: FieldPropRefs<CustomField> = toRefs(props)
30+
</script>
31+
```
32+
1933
## Props
2034

2135
### `id` <Badge type="info" text="String"/>

‎apps/docs/guide/composables/useFieldValidate.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
---
22
outline: [2,3]
33
---
4-
# useFieldValidate <Badge type="tip" text="2.0.0+"/>
5-
> Used to validate a field against validators defined in a fields schema
4+
# useFieldValidate <Badge type="tip" text="2.0.0+"/> <Badge type="warning" text="deprecated"/>
5+
> Used to validate a field against validators defined in a field's schema
6+
::: warning
7+
This composable is deprecated, please use [`useValidation`](/guide/composables/useValidation) instead
8+
:::
69

710
## Usage
811
```vue

‎apps/docs/guide/composables/useValidation.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
outline: [2,3]
3+
---
4+
# useValidation <Badge type="tip" text=">=2.7.0"/>
5+
> Used to validate a field against validators defined in a field's schema
6+
7+
## Usage
8+
::: code-group
9+
```Vue [Vue]
10+
<script setup>
11+
import { toRefs } from 'vue'
12+
import {
13+
useValidation,
14+
useFieldProps,
15+
useFormModel,
16+
useFieldEmits,
17+
useFieldAttributes
18+
} from '@kevinkosterr/vue3-form-generator'
19+
20+
const props = defineProps(useFieldProps())
21+
const emits = defineEmits(useFieldEmits())
22+
23+
const { field, model } = toRefs(props)
24+
const { isRequired, isDisabled, isReadonly } = useFieldAttributes(model.value, field.value)
25+
const { currentModelValue } = useFormModel(model.value, field.value)
26+
27+
const { validate, errors, onChanged, onBlur } = useValidation(
28+
model.value,
29+
field.value,
30+
currentModelValue,
31+
props.formOptions,
32+
emits,
33+
isDisabled.value,
34+
isRequired.value,
35+
isReadonly.value
36+
)
37+
</script>
38+
```
39+
```Vue [Vue TS]
40+
<script setup lang="ts">
41+
import { toRefs } from 'vue'
42+
import {
43+
type FieldEmits,
44+
type FieldProps,
45+
type FieldBase,
46+
type FieldPropRefs,
47+
useValidation,
48+
useFieldAttributes,
49+
useFormModel
50+
} from '@kevinkosterr/vue3-form-generator'
51+
52+
type CustomField = FieldBase & {
53+
customAttr: string
54+
}
55+
56+
const props = defineProps<FieldProps<CustomField>>()
57+
const emits = defineEmits<FieldEmits>()
58+
59+
const { field, model }: FieldPropRefs<CustomField> = toRefs(props)
60+
const { isRequired, isDisabled, isReadonly } = useFieldAttributes(model.value, field.value)
61+
const { currentModelValue } = useFormModel(model.value, field.value)
62+
63+
const { validate, errors, onChanged, onBlur } = useValidation(
64+
model.value,
65+
field.value,
66+
currentModelValue,
67+
props.formOptions,
68+
emits,
69+
isDisabled.value,
70+
isRequired.value,
71+
isReadonly.value
72+
)
73+
</script>
74+
```
75+
:::
76+
77+
## Arguments
78+
79+
### `model` <Badge type="info" text="Object"/>
80+
Model object, as returned by the props
81+
82+
### `field` <Badge type="info" text="Object"/>
83+
Field schema object, as returned by the props
84+
85+
### `currentModelValue` <Badge type="info" text="Ref<any>"/>
86+
`Ref` of the current value from the field. Returned by [`useFormModel`](/guide/composables/useFormModel).
87+
88+
### `formOptions` <Badge type="info" text="Object"/>
89+
Form options object, as returned by the props.
90+
91+
### `emits` <Badge type="info" text="EmitFn<FieldEmits>"/>
92+
Emit function as returned by `defineEmits()`
93+
94+
### `isDisabled` <Badge type="info" text="Boolean"/>
95+
Whether the field is disabled, can be obtained from [`useFieldAttributes()`](/guide/composables/useFieldAttributes)
96+
97+
### `isRequired` <Badge type="info" text="Boolean"/>
98+
Whether the field is required, can be obtained from [`useFieldAttributes()`](/guide/composables/useFieldAttributes)
99+
100+
### `isReadonly` <Badge type="info" text="Boolean"/>
101+
Whether the field is readonly, can be obtained from [`useFieldAttributes()`](/guide/composables/useFieldAttributes)
102+
103+
## Returns
104+
105+
### `errors` <Badge type="info" text="string[]"/>
106+
An array of errors for the current field. Will be auto-updated on every validation cycle. Must be cleared
107+
manually when the value of a field has changed.
108+
109+
### `validate` <Badge type="info" text="Function"/>
110+
A validation function, meant to be called when a validation has to take place. Used when a field is always validated
111+
at the same moment and isn't affected by validation triggers, such as `'onChanged'` or `'onBlur'`.
112+
113+
### `onChanged` <Badge type="info" text="Function"/>
114+
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
115+
validation triggers.
116+
117+
### `onBlur` <Badge type="info" text="Function"/>
118+
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
119+
validation triggers.

‎apps/docs/guide/customization/custom-components.md

Lines changed: 51 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -15,35 +15,21 @@ To create a field component you make use of different composables ([?](https://v
1515
get the behaviour you want the component to have. Different composables handle different functionality inside the field
1616
component.
1717

18+
:::tabs
19+
== JavaScript
1820
Every component must at least use these composables to work properly:
1921
- [`useFieldEmits`](/guide/composables/useFieldEmits) - returns all events emitted by a field component;
2022
- [`useFieldProps`](/guide/composables/useFieldProps) - returns all props used by a field component;
2123
- [`useFormModel`](/guide/composables/useFormModel) - used to get the current model value for this field component.
2224

2325
Optional:
24-
- [`useFieldValidate`](/guide/composables/useFieldValidate) - used for validation of the field;
26+
- [`useValidation`](/guide/composables/useValidation) - used for validation of the field;
2527
- [`useFieldAttributes`](/guide/composables/useFieldAttributes) - holds different dynamic field attributes like `required` and `readonly`.
2628

2729

2830
### Basic example
2931
::: code-group
30-
```vue [template]
31-
<template>
32-
<input
33-
:id="id"
34-
class="field-input"
35-
type="text"
36-
:name="field.name"
37-
:required="isRequired"
38-
:disabled="isDisabled"
39-
:placeholder="field.placeholder"
40-
:autocomplete="field.autocomplete || 'off'"
41-
:value="currentModelValue"
42-
@input="onFieldValueChanged"
43-
@blur="onBlur"
44-
>
45-
</template>
46-
```
32+
<!--@include: @/parts/customization/custom-components-template-example.md-->
4733

4834
```vue [script setup]
4935
<script setup>
@@ -79,16 +65,62 @@ const onFieldValueChanged = ({ target }) => {
7965
errors.value = []
8066
emits('onInput', target.value)
8167
}
68+
<script/>
69+
```
70+
71+
==TypeScript
72+
You'll only need one composable to create a custom component:
73+
- [`useFormModel`](/guide/composables/useFormModel) - used to get the current model value for this field component.
74+
75+
Optional:
76+
- [`useValidation`](/guide/composables/useValidation) - used for validation of the field;
77+
- [`useFieldAttributes`](/guide/composables/useFieldAttributes) - holds different dynamic field attributes like `required` and `readonly`.
78+
79+
When using TypeScript you won't need the other composables to define proper emits and props. You'll be able to use types
80+
for that.
81+
82+
### Basic example
83+
:::code-group
84+
<!--@include: @/parts/customization/custom-components-template-example.md-->
85+
86+
```vue [script setup]
87+
<script setup lang="ts">
88+
import { toRefs } from 'vue'
89+
import type { FieldBase, FieldEmits, FieldProps, FieldPropRefs } from '@kevinkosterr/vue3-form-generator'
90+
import { useValidation, useFormModel, useFieldAttributes } from '@kevinkosterr/vue3-form-generator'
91+
92+
type CustomFieldType = FieldBase & {
93+
customAttribute: boolean
94+
}
95+
96+
const props = defineProps<FieldProps<CustomFieldType>>()
97+
const emits = defineEmits<FieldEmits>()
98+
const { model, field }: FieldPropRefs<CustomFieldType> = toRefs(props)
99+
100+
const { isDisabled, isRequired, isReadonly } = useFieldAttributes(model.value, field.value)
101+
const { currentModelValue } = useFormModel(model.value, field.value)
102+
const { errors, validate, onChanged: onFieldValueChanged, onBlur } = useValidation(
103+
model.value,
104+
field.value,
105+
currentModelValue,
106+
props.formOptions,
107+
emits,
108+
isDisabled.value,
109+
isRequired.value,
110+
isReadonly.value
111+
)
112+
</script>
82113
```
83114
:::
84115

116+
85117
### Advanced example
86118
For a more advanced example, you can take a look at the [`FieldSelect`](/guide/fields/FieldSelect) ([source](https://github.com/kevinkosterr/vue3-form-generator/blob/69cb6aeb8e8c82926ec3598e7d73be2d1146a3f2/src/fields/core/FieldSelect.vue)) component.
87119

88120
## Compatibility with validation
89121
::: info
90122
If you want your component to be compatible with validation, you'll need to expose the `errors` value that is returned
91-
by [`useFieldValidate`](/guide/composables/useFieldValidate)
123+
by [`useValidation`](/guide/composables/useValidation)
92124
:::
93125

94126
## Registering your component

‎apps/docs/guide/form-generator/props.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,10 @@ outline: [ 2,3 ]
1212
| `idPrefix` | `string` | Prefix for all the generated ids in the form |
1313

1414
## `formOptions`
15-
| Property | Type | Description |
16-
|---------------|----------|------------------------------------------------------|
17-
| `idPrefix` | `string` | Prefix for all the generated ids in the form |
15+
| Property | Type | Default | Description |
16+
|------------|--------------------------|--------|-----------------------------------------------------------------------------------------------------|
17+
| `idPrefix` | `string` | | Prefix for all the generated ids in the form |
18+
| `validate` | `'onChanged'` \| `'onBlur'` | `onBlur` | Method of validation, can be overwritten by individual fields. Can be either `onChanged` or `onBlur` |
1819

1920
## `model`
2021
Type: `Object`

‎apps/docs/parts/customization/custom-components-template-example.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
```vue [template]
2+
<template>
3+
<input
4+
:id="id"
5+
class="field-input"
6+
type="text"
7+
:name="field.name"
8+
:required="isRequired"
9+
:disabled="isDisabled"
10+
:placeholder="field.placeholder"
11+
:autocomplete="field.autocomplete || 'off'"
12+
:value="currentModelValue"
13+
@input="onFieldValueChanged"
14+
@blur="onBlur"
15+
>
16+
</template>
17+
```

‎apps/docs/parts/shared-field-properties.md

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,18 @@
1-
| Property | Default | Type | Description |
2-
|-------------|------------|---------------------------------------------|-------------------------------------------------------------------------------------------------|
3-
| name | - | `string` | Name of the field |
4-
| model | - | `string` | Key of model in the form schema model |
5-
| label | - | `string` | Label for the field |
6-
| type | - | `string` | Type of field, generally `input` if the field is an input. |
7-
| inputType | - | `string` | Type of input, only required when `type === 'input'` |
1+
| Property | Default | Type | Description |
2+
|-------------|-----------|---------------------------------------------|-------------------------------------------------------------------------------------------------|
3+
| name | - | `string` | Name of the field |
4+
| model | - | `string` | Key of model in the form schema model |
5+
| label | - | `string` | Label for the field |
6+
| type | - | `string` | Type of field, generally `input` if the field is an input. |
7+
| inputType | - | `string` | Type of input, only required when `type === 'input'` |
88
| id | _computed_ | `string` | `id` of the field |
9-
| visible | `true` | `Boolean \| Function` | Whether the field is visible, method will be passed the `model`, `field` and field component* |
10-
| required | `false` | `Boolean \| Function` | Whether the field is required, method will be passed the `model`, `field` and field component* |
11-
| readonly | `false` | `Boolean \| Function` | Whether the field is read only, method will be passed the `model`, `field` and field component* |
12-
| disabled | `false` | `Boolean \| Function` | Whether the field is disabled, method will be passed the `model`, `field` and field component* |
13-
| hint | - | `string \| Function` | Hint to display underneath the field, can be passed a method* |
9+
| visible | `true` | `Boolean \| Function` | Whether the field is visible, method will be passed the `model`, `field` and field component* |
10+
| required | `false` | `Boolean \| Function` | Whether the field is required, method will be passed the `model`, `field` and field component* |
11+
| readonly | `false` | `Boolean \| Function` | Whether the field is read only, method will be passed the `model`, `field` and field component* |
12+
| disabled | `false` | `Boolean \| Function` | Whether the field is disabled, method will be passed the `model`, `field` and field component* |
13+
| hint | - | `string \| Function` | Hint to display underneath the field, can be passed a method* |
1414
| validator | _computed_ | `Array<Function> \| Function \| undefined` | A (list of) validator(s) to be validating the field against. |
15-
| onValidated | - | `Function \| undefined` | Method to be called after validation has been completed. |
15+
| validate | `onBlur` | `'onChanged'` \| `'onBlur'` | Method of validation for the field. |
16+
| onValidated | - | `Function \| undefined` | Method to be called after validation has been completed. |
1617

1718
_*_ see [determineDynamicAttribute()](/guide/mixins/abstractField#determinedynamicattribute) for more information.

0 commit comments

Comments
 (0)