@formvk/vue 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,15 @@
1
+ # @formvk/vue
2
+
3
+ ## 1.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - 65c066c: 添加readme.md文档
8
+
9
+ ### Patch Changes
10
+
11
+ - Updated dependencies [65c066c]
12
+ - @formvk/core@1.0.0
13
+ - @formvk/reactive@1.0.0
14
+ - @formvk/schema@1.0.0
15
+ - @formvk/shared@1.0.0
package/README.md ADDED
@@ -0,0 +1,63 @@
1
+ # @formvk/vue
2
+
3
+ Vue 3 bindings for Formvk. It connects the `@formvk/core` form model and `@formvk/schema` to Vue components through reactive renderers and composables.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ pnpm add @formvk/vue vue
9
+ ```
10
+
11
+ `vue` (`^3.5.0`) is a peer dependency.
12
+
13
+ ## Usage
14
+
15
+ ```vue
16
+ <script setup lang="ts">
17
+ import { createForm, createFragment, createSchema, FormProvider, SchemaField } from '@formvk/vue'
18
+
19
+ import MyInput from './MyInput.vue'
20
+
21
+ const form = createForm({ values: { name: '' } })
22
+ const f = createFragment()
23
+ const schema = createSchema({
24
+ name: f.Field({ title: 'Name', component: 'Input' }),
25
+ })
26
+ </script>
27
+
28
+ <template>
29
+ <FormProvider :form="form">
30
+ <SchemaField :schema="schema" :components="{ Input: MyInput }" />
31
+ </FormProvider>
32
+ </template>
33
+ ```
34
+
35
+ The schema field can also pre-bind components with `createSchemaField`:
36
+
37
+ ```ts
38
+ import { createSchema, createSchemaField } from '@formvk/vue'
39
+
40
+ const { SchemaField, fragment: f } = createSchemaField({
41
+ components: { Input: MyInput },
42
+ })
43
+
44
+ const schema = createSchema({
45
+ name: f.Input({ title: 'Name' }),
46
+ })
47
+ ```
48
+
49
+ ## API
50
+
51
+ - **Components** — `FormProvider`, `SchemaField`, `createSchemaField`, `RecursionField`, `ExpressionScope`, `FormConsumer`.
52
+ - **Hooks** — `useForm`, `useField`, `useFieldSchema`, `useAttach`, `useFormEffects`, `useInjectionCleaner`, `useParentForm`.
53
+ - **Helpers** — `createForm`, `connect`, `mapProps`, `mapReadPretty`.
54
+ - **Schema** — re-exports `@formvk/schema` (`createFragment`, `createSchema`, `ISchema`, expression types, ...).
55
+
56
+ ## Documentation
57
+
58
+ - Vue API: https://formvk.github.io/core/api/vue
59
+ - Getting started: https://formvk.github.io/core/guide/getting-started
60
+
61
+ ## License
62
+
63
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@formvk/vue",
3
- "version": "0.1.0",
3
+ "version": "1.0.0",
4
4
  "description": "Formvk Vue Bindings",
5
5
  "keywords": [
6
6
  "form",
@@ -10,24 +10,28 @@
10
10
  ],
11
11
  "license": "MIT",
12
12
  "author": "yiyunwan",
13
+ "files": [
14
+ "dist",
15
+ "CHANGELOG.md"
16
+ ],
13
17
  "type": "module",
14
18
  "main": "dist/index.js",
15
19
  "module": "dist/index.js",
16
20
  "types": "dist/index.d.ts",
17
21
  "dependencies": {
18
- "@formvk/core": "^0.1.0",
19
- "@formvk/reactive": "^0.1.0",
20
- "@formvk/schema": "^0.1.0",
21
- "@formvk/shared": "^0.1.0"
22
+ "@formvk/core": "~1.0.0",
23
+ "@formvk/reactive": "~1.0.0",
24
+ "@formvk/schema": "~1.0.0",
25
+ "@formvk/shared": "~1.0.0"
22
26
  },
23
27
  "devDependencies": {
24
- "@vitejs/plugin-vue-jsx": "^5.1.1",
25
- "@vue/test-utils": "^2.4.6",
28
+ "@vitejs/plugin-vue-jsx": "^5.1.6",
29
+ "@vue/test-utils": "^2.6.0",
26
30
  "happy-dom": "^21.0.4",
27
- "vue": "3.6.0-rc.12"
31
+ "vue": "^3.6.0-rc.15"
28
32
  },
29
33
  "peerDependencies": {
30
- "vue": "^3.3.0"
34
+ "vue": "^3.5.0"
31
35
  },
32
36
  "scripts": {
33
37
  "build": "tsc --noEmit && vite build",
@@ -1,79 +0,0 @@
1
- import { describe, expect, test } from 'vitest'
2
- import { defineComponent, nextTick, reactive } from 'vue'
3
-
4
- import { ExpressionScope, SchemaField, createForm } from '..'
5
- import { Input, mountWithForm } from './shared'
6
-
7
- function createScopeWrapper(value: any) {
8
- return defineComponent({
9
- name: 'ScopeWrapper',
10
- setup(_, { slots }) {
11
- return () => <ExpressionScope value={value}>{slots.default?.()}</ExpressionScope>
12
- },
13
- })
14
- }
15
-
16
- function scopeSchema(expression: string) {
17
- return {
18
- type: 'object',
19
- properties: {
20
- v: {
21
- type: 'void',
22
- component: 'ScopeWrapper',
23
- properties: {
24
- target: {
25
- type: 'string',
26
- component: 'Input',
27
- componentProps: { placeholder: expression },
28
- },
29
- },
30
- },
31
- },
32
- }
33
- }
34
-
35
- describe('ExpressionScope', () => {
36
- test('内层 scope 与外层 SchemaField scope 叠加', () => {
37
- const form = createForm()
38
- const ScopeWrapper = createScopeWrapper({ $inner: 'inner' })
39
- const wrapper = mountWithForm(form, () => (
40
- <SchemaField
41
- components={{ Input, ScopeWrapper }}
42
- scope={{ $outer: 'outer' }}
43
- schema={scopeSchema('{{$inner + "-" + $outer}}')}
44
- />
45
- ))
46
-
47
- expect(wrapper.find('[data-testid="target"]').attributes('placeholder')).toBe('inner-outer')
48
- })
49
-
50
- test('内外层同名变量时内层优先', () => {
51
- const form = createForm()
52
- const ScopeWrapper = createScopeWrapper({ $shared: 'inner' })
53
- const wrapper = mountWithForm(form, () => (
54
- <SchemaField
55
- components={{ Input, ScopeWrapper }}
56
- scope={{ $shared: 'outer' }}
57
- schema={scopeSchema('{{$shared}}')}
58
- />
59
- ))
60
-
61
- expect(wrapper.find('[data-testid="target"]').attributes('placeholder')).toBe('inner')
62
- })
63
-
64
- test('ExpressionScope 值变化后表达式重新编译', async () => {
65
- const form = createForm()
66
- const innerScope = reactive({ $inner: 'v1' })
67
- const ScopeWrapper = createScopeWrapper(innerScope)
68
- const wrapper = mountWithForm(form, () => (
69
- <SchemaField components={{ Input, ScopeWrapper }} schema={scopeSchema('{{$inner}}')} />
70
- ))
71
-
72
- expect(wrapper.find('[data-testid="target"]').attributes('placeholder')).toBe('v1')
73
-
74
- innerScope.$inner = 'v2'
75
- await nextTick()
76
-
77
- expect(wrapper.find('[data-testid="target"]').attributes('placeholder')).toBe('v2')
78
- })
79
- })
@@ -1,185 +0,0 @@
1
- import { mount } from '@vue/test-utils'
2
- import { describe, expect, test, vi } from 'vitest'
3
- import { defineComponent, nextTick } from 'vue'
4
-
5
- import type { IFormConsumerSlotProps } from '..'
6
- import { FormConsumer, FormProvider, SchemaField, createForm, useField, useParentForm } from '..'
7
- import { Input, mountWithForm } from './shared'
8
-
9
- function simpleSchema(name: string, component = 'Input') {
10
- return {
11
- type: 'object',
12
- properties: {
13
- [name]: { type: 'string', component },
14
- },
15
- }
16
- }
17
-
18
- const ParentName = defineComponent({
19
- name: 'ParentName',
20
- setup() {
21
- const parent = useParentForm()
22
- const field = useField()
23
- return () => (
24
- <div class="parent-name" data-testid={field.value?.path?.toString()}>
25
- {parent.value?.displayName}
26
- </div>
27
- )
28
- },
29
- })
30
-
31
- describe('FormProvider 与表单上下文', () => {
32
- test('FormProvider 提供表单,挂载与卸载驱动 form 生命周期', () => {
33
- const form = createForm()
34
- const wrapper = mountWithForm(form, () => <SchemaField components={{ Input }} schema={simpleSchema('a')} />)
35
-
36
- const field = form.fields['a'] as any
37
- expect(form.mounted).toBe(true)
38
- expect(field.mounted).toBe(true)
39
-
40
- wrapper.unmount()
41
- expect(form.unmounted).toBe(true)
42
- expect(field.unmounted).toBe(true)
43
- })
44
-
45
- test('useParentForm 在 object schema 内返回最近的 ObjectField,void / 根级返回 Form', () => {
46
- const form = createForm()
47
- const wrapper = mountWithForm(form, () => (
48
- <SchemaField
49
- components={{ ParentName }}
50
- schema={{
51
- type: 'object',
52
- properties: {
53
- obj: {
54
- type: 'object',
55
- properties: {
56
- inner: { type: 'string', component: 'ParentName' },
57
- },
58
- },
59
- v: {
60
- type: 'void',
61
- properties: {
62
- inner: { type: 'string', component: 'ParentName' },
63
- },
64
- },
65
- root: { type: 'string', component: 'ParentName' },
66
- },
67
- }}
68
- />
69
- ))
70
-
71
- expect(wrapper.find('[data-testid="obj.inner"]').text()).toBe('ObjectField')
72
- // Field.path 会剔除 void 节点,因此 void 下的字段 path 是 inner 而非 v.inner
73
- expect(wrapper.find('[data-testid="inner"]').text()).toBe('Form')
74
- expect(wrapper.find('[data-testid="root"]').text()).toBe('Form')
75
- })
76
-
77
- test('useInjectionCleaner 阻止嵌套 FormProvider 的字段上下文串层', () => {
78
- const form = createForm()
79
- const wrapper = mount(
80
- defineComponent({
81
- setup() {
82
- return () => (
83
- <FormProvider form={form}>
84
- <SchemaField components={{ Input }} schema={simpleSchema('parent')} />
85
- <FormProvider form={form}>
86
- <SchemaField components={{ Input }} schema={simpleSchema('inner')} />
87
- </FormProvider>
88
- </FormProvider>
89
- )
90
- },
91
- })
92
- )
93
-
94
- expect(form.fields['parent']).toBeTruthy()
95
- expect(form.fields['inner']).toBeTruthy()
96
- expect(form.fields['parent.inner']).toBeUndefined()
97
- expect(wrapper.find('[data-testid="parent"]').exists()).toBe(true)
98
- expect(wrapper.find('[data-testid="inner"]').exists()).toBe(true)
99
- })
100
-
101
- test('FormConsumer 插槽读到 form.values,setValuesIn 后无需 observer 自动更新', async () => {
102
- const form = createForm({ values: { a: 'abc' } })
103
- const wrapper = mount(
104
- defineComponent({
105
- setup() {
106
- return () => (
107
- <FormProvider form={form}>
108
- <SchemaField components={{ Input }} schema={simpleSchema('a')} />
109
- <FormConsumer>
110
- {({ form }: IFormConsumerSlotProps) => <div class="consumer">{JSON.stringify(form.values)}</div>}
111
- </FormConsumer>
112
- </FormProvider>
113
- )
114
- },
115
- })
116
- )
117
-
118
- expect(wrapper.find('.consumer').text()).toBe('{"a":"abc"}')
119
-
120
- form.setValuesIn('a', 'xyz')
121
- await nextTick()
122
-
123
- expect(wrapper.find('.consumer').text()).toBe('{"a":"xyz"}')
124
- expect(wrapper.find('input').element.value).toBe('xyz')
125
- })
126
-
127
- test('form.display 置为 none 后字段值被清空并同步到 DOM', async () => {
128
- const form = createForm({ values: { a: 'abc' } })
129
- const wrapper = mount(
130
- defineComponent({
131
- setup() {
132
- return () => (
133
- <FormProvider form={form}>
134
- <SchemaField components={{ Input }} schema={simpleSchema('a')} />
135
- <FormConsumer>
136
- {({ form }: IFormConsumerSlotProps) => <div class="consumer">{JSON.stringify(form.values)}</div>}
137
- </FormConsumer>
138
- </FormProvider>
139
- )
140
- },
141
- })
142
- )
143
-
144
- form.setDisplay('none')
145
- await nextTick()
146
-
147
- expect(form.getValuesIn('a')).toBeUndefined()
148
- expect(wrapper.find('.consumer').text()).toBe('{}')
149
- expect(wrapper.find('input').exists()).toBe(false)
150
-
151
- form.setDisplay('visible')
152
- await nextTick()
153
-
154
- expect(form.getValuesIn('a')).toBe('abc')
155
- expect(wrapper.find('input').element.value).toBe('abc')
156
- })
157
-
158
- test('卸载 FormProvider 时触发字段 onUnmount', () => {
159
- const form = createForm()
160
- const wrapper = mountWithForm(form, () => <SchemaField components={{ Input }} schema={simpleSchema('a')} />)
161
-
162
- const field = form.fields['a'] as any
163
- const spy = vi.spyOn(field, 'onUnmount')
164
- wrapper.unmount()
165
-
166
- expect(spy).toHaveBeenCalledTimes(1)
167
- })
168
-
169
- test('FormConsumer 无默认插槽时渲染为空', () => {
170
- const form = createForm()
171
- const wrapper = mount(
172
- defineComponent({
173
- setup() {
174
- return () => (
175
- <FormProvider form={form}>
176
- <FormConsumer />
177
- </FormProvider>
178
- )
179
- },
180
- })
181
- )
182
-
183
- expect(wrapper.text()).toBe('')
184
- })
185
- })
@@ -1,230 +0,0 @@
1
- import { onFieldValueChange } from '@formvk/core'
2
- import { mount } from '@vue/test-utils'
3
- import { describe, expect, test, vi } from 'vitest'
4
- import { defineComponent, nextTick, provide, shallowRef } from 'vue'
5
-
6
- import {
7
- FormProvider,
8
- SchemaField,
9
- createForm,
10
- useAttach,
11
- useField,
12
- useFieldSchema,
13
- useForm,
14
- useFormEffects,
15
- useParentForm,
16
- } from '..'
17
- import { FieldSymbol, FormSymbol } from '../shared/context'
18
- import { Input, mountWithForm } from './shared'
19
-
20
- describe('hooks', () => {
21
- test('无 Provider 时 useForm / useField / useFieldSchema 返回空 ref 且不报错', () => {
22
- const Probe = defineComponent({
23
- name: 'EmptyProbe',
24
- setup() {
25
- const form = useForm()
26
- const field = useField()
27
- const schema = useFieldSchema()
28
- return () => (
29
- <div class="empty-probe">{`${String(form.value)}-${String(field.value)}-${String(schema.value)}`}</div>
30
- )
31
- },
32
- })
33
-
34
- const wrapper = mount(Probe)
35
- expect(wrapper.find('.empty-probe').text()).toBe('undefined-undefined-undefined')
36
- })
37
-
38
- test('useFieldSchema 在 RecursionField 内拿到当前节点 schema', () => {
39
- const SchemaProbe = defineComponent({
40
- name: 'SchemaProbe',
41
- setup() {
42
- const schemaRef = useFieldSchema()
43
- return () => (
44
- <div class="schema-probe">{`${String(schemaRef.value?.type)}:${String(schemaRef.value?.name)}`}</div>
45
- )
46
- },
47
- })
48
-
49
- const form = createForm()
50
- const wrapper = mountWithForm(form, () => (
51
- <SchemaField
52
- components={{ SchemaProbe }}
53
- schema={{
54
- type: 'object',
55
- properties: {
56
- a: { type: 'string', component: 'SchemaProbe' },
57
- },
58
- }}
59
- />
60
- ))
61
-
62
- expect(wrapper.find('.schema-probe').text()).toBe('string:a')
63
- })
64
-
65
- test('useFormEffects 注册 effects,卸载后移除生命周期', async () => {
66
- let count = 0
67
- const EffectsProbe = defineComponent({
68
- name: 'EffectsProbe',
69
- setup() {
70
- useFormEffects(() => {
71
- onFieldValueChange('*', () => {
72
- count++
73
- })
74
- })
75
- return () => <div class="effects-probe" />
76
- },
77
- })
78
-
79
- const form = createForm()
80
- const wrapper = mountWithForm(form, () => (
81
- <>
82
- <EffectsProbe />
83
- <SchemaField
84
- components={{ Input }}
85
- schema={{
86
- type: 'object',
87
- properties: {
88
- a: { type: 'string', component: 'Input' },
89
- },
90
- }}
91
- />
92
- </>
93
- ))
94
-
95
- form.setValuesIn('a', 'first')
96
- expect(count).toBe(1)
97
-
98
- wrapper.unmount()
99
- form.setValuesIn('a', 'second')
100
- expect(count).toBe(1)
101
- })
102
-
103
- test('form 实例替换后 effects 重新注册到新表单', async () => {
104
- const formA = createForm()
105
- const formB = createForm()
106
- const addA = vi.spyOn(formA, 'addEffects')
107
- const removeA = vi.spyOn(formA, 'removeEffects')
108
- const addB = vi.spyOn(formB, 'addEffects')
109
-
110
- const EffectsProbe = defineComponent({
111
- name: 'EffectsProbe',
112
- setup() {
113
- useFormEffects(() => {
114
- onFieldValueChange('*', () => {})
115
- })
116
- return () => <div class="effects-probe" />
117
- },
118
- })
119
-
120
- const current = shallowRef(formA)
121
- mount(
122
- defineComponent({
123
- setup() {
124
- return () => (
125
- <FormProvider form={current.value}>
126
- <EffectsProbe />
127
- </FormProvider>
128
- )
129
- },
130
- })
131
- )
132
-
133
- expect(addA).toHaveBeenCalledTimes(1)
134
-
135
- current.value = formB
136
- await nextTick()
137
-
138
- expect(removeA).toHaveBeenCalled()
139
- expect(addB).toHaveBeenCalledTimes(1)
140
- })
141
-
142
- test('useParentForm 响应字段引用替换', async () => {
143
- const form = createForm()
144
- const fieldRef = shallowRef<any>()
145
-
146
- const ParentProbe = defineComponent({
147
- name: 'ParentProbe',
148
- setup() {
149
- const parent = useParentForm()
150
- return () => <div class="parent-probe">{parent.value?.displayName}</div>
151
- },
152
- })
153
-
154
- const wrapper = mount(
155
- defineComponent({
156
- setup() {
157
- provide(FormSymbol, shallowRef(form))
158
- provide(FieldSymbol, fieldRef)
159
- return () => <ParentProbe />
160
- },
161
- })
162
- )
163
-
164
- fieldRef.value = form.createObjectField({ name: 'obj' })
165
- await nextTick()
166
- expect(wrapper.find('.parent-probe').text()).toBe('ObjectField')
167
-
168
- fieldRef.value = form.createField({ name: 'plain' })
169
- await nextTick()
170
- expect(wrapper.find('.parent-probe').text()).toBe('Form')
171
- })
172
-
173
- test('useAttach 切换 target 时旧值 onUnmount、新值 onMount', async () => {
174
- const targetA = { onMount: vi.fn(), onUnmount: vi.fn() }
175
- const targetB = { onMount: vi.fn(), onUnmount: vi.fn() }
176
- const targetRef = shallowRef(targetA)
177
-
178
- const AttachProbe = defineComponent({
179
- name: 'AttachProbe',
180
- setup() {
181
- useAttach(targetRef)
182
- return () => <div class="attach-probe" />
183
- },
184
- })
185
-
186
- const wrapper = mount(AttachProbe)
187
- expect(targetA.onMount).toHaveBeenCalledTimes(1)
188
-
189
- targetRef.value = targetB
190
- await nextTick()
191
- await nextTick()
192
-
193
- expect(targetA.onUnmount).toHaveBeenCalledTimes(1)
194
- expect(targetB.onMount).toHaveBeenCalledTimes(1)
195
-
196
- wrapper.unmount()
197
- expect(targetB.onUnmount).toHaveBeenCalled()
198
- })
199
-
200
- test('useAttach 目标置空时不报错', async () => {
201
- const targetRef = shallowRef<any>({ onMount: vi.fn(), onUnmount: vi.fn() })
202
- const DetachProbe = defineComponent({
203
- name: 'DetachProbe',
204
- setup() {
205
- useAttach(targetRef)
206
- return () => <div class="detach-probe" />
207
- },
208
- })
209
-
210
- const wrapper = mount(DetachProbe)
211
- targetRef.value = undefined
212
- await nextTick()
213
-
214
- expect(targetRef.value).toBeUndefined()
215
- wrapper.unmount()
216
- })
217
-
218
- test('useFormEffects 无表单上下文时安全跳过', () => {
219
- const EmptyEffectsProbe = defineComponent({
220
- name: 'EmptyEffectsProbe',
221
- setup() {
222
- useFormEffects(() => {})
223
- return () => <div class="empty-effects" />
224
- },
225
- })
226
-
227
- const wrapper = mount(EmptyEffectsProbe)
228
- expect(wrapper.find('.empty-effects').exists()).toBe(true)
229
- })
230
- })