@zeng-alt/formkit-form-builder 0.1.4 → 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.
Files changed (133) hide show
  1. package/LICENSE +168 -0
  2. package/README.md +236 -61
  3. package/dist/builder.css +2 -0
  4. package/dist/builder.es.js +40324 -0
  5. package/dist/builder.umd.js +496 -0
  6. package/dist/index.d.ts +807 -1
  7. package/package.json +33 -26
  8. package/dist/index.cjs +0 -422
  9. package/dist/index.mjs +0 -9403
  10. package/dist/src/builder/BuilderDropArea.d.ts +0 -4
  11. package/dist/src/builder/BuilderHeader.d.ts +0 -17
  12. package/dist/src/builder/BuilderMain.d.ts +0 -68
  13. package/dist/src/builder/BuilderPreview.d.ts +0 -5
  14. package/dist/src/builder/BuilderProvider.d.ts +0 -21
  15. package/dist/src/builder/ImportExportModal.d.ts +0 -9
  16. package/dist/src/components/ai-prompt/AiPrompt.d.ts +0 -2
  17. package/dist/src/components/sidebar-left/DraggableList.d.ts +0 -8
  18. package/dist/src/components/sidebar-left/NavMain.d.ts +0 -2
  19. package/dist/src/components/sidebar-left/SidebarLeft.d.ts +0 -2
  20. package/dist/src/components/sidebar-right/FormEditMain.d.ts +0 -2
  21. package/dist/src/components/sidebar-right/SidebarRight.d.ts +0 -2
  22. package/dist/src/components/sidebar-right/edits/EditsSection.d.ts +0 -2
  23. package/dist/src/components/sidebar-right/edits/ExpressionEditor.d.ts +0 -2
  24. package/dist/src/components/sidebar-right/edits/common/EditsLayout.d.ts +0 -21
  25. package/dist/src/components/sidebar-right/edits/common/JsonTextarea.d.ts +0 -14
  26. package/dist/src/components/sidebar-right/edits/common/LabelHelpSection.d.ts +0 -2
  27. package/dist/src/components/sidebar-right/edits/common/NaiveBasicSection.d.ts +0 -7
  28. package/dist/src/components/sidebar-right/edits/common/NameInput.d.ts +0 -2
  29. package/dist/src/components/sidebar-right/edits/common/OptionsTagsSection.d.ts +0 -5
  30. package/dist/src/components/sidebar-right/edits/common/PlaceholderSection.d.ts +0 -2
  31. package/dist/src/components/sidebar-right/edits/common/RangeInputs.d.ts +0 -16
  32. package/dist/src/components/sidebar-right/edits/common/SelectInput.d.ts +0 -15
  33. package/dist/src/components/sidebar-right/edits/common/SelectSwitchesSection.d.ts +0 -2
  34. package/dist/src/components/sidebar-right/edits/common/SwitchInput.d.ts +0 -12
  35. package/dist/src/components/sidebar-right/edits/common/TagsInput.d.ts +0 -11
  36. package/dist/src/components/sidebar-right/edits/common/TextInput.d.ts +0 -14
  37. package/dist/src/components/sidebar-right/edits/common/ToggleInput.d.ts +0 -15
  38. package/dist/src/components/sidebar-right/edits/common/TreeOptionsJsonSection.d.ts +0 -2
  39. package/dist/src/components/sidebar-right/edits/editors/CheckboxEditor.d.ts +0 -2
  40. package/dist/src/components/sidebar-right/edits/editors/ColorEditor.d.ts +0 -2
  41. package/dist/src/components/sidebar-right/edits/editors/DateLikeEditor.d.ts +0 -2
  42. package/dist/src/components/sidebar-right/edits/editors/DateTimeEditor.d.ts +0 -2
  43. package/dist/src/components/sidebar-right/edits/editors/FileEditor.d.ts +0 -2
  44. package/dist/src/components/sidebar-right/edits/editors/GroupEditor.d.ts +0 -2
  45. package/dist/src/components/sidebar-right/edits/editors/NaiveAvatarEditor.d.ts +0 -2
  46. package/dist/src/components/sidebar-right/edits/editors/NaiveBlockquoteEditor.d.ts +0 -2
  47. package/dist/src/components/sidebar-right/edits/editors/NaiveButtonEditor.d.ts +0 -2
  48. package/dist/src/components/sidebar-right/edits/editors/NaiveCascaderEditor.d.ts +0 -2
  49. package/dist/src/components/sidebar-right/edits/editors/NaiveCheckboxEditor.d.ts +0 -2
  50. package/dist/src/components/sidebar-right/edits/editors/NaiveDividerEditor.d.ts +0 -2
  51. package/dist/src/components/sidebar-right/edits/editors/NaiveH1Editor.d.ts +0 -2
  52. package/dist/src/components/sidebar-right/edits/editors/NaiveH2Editor.d.ts +0 -2
  53. package/dist/src/components/sidebar-right/edits/editors/NaiveH3Editor.d.ts +0 -2
  54. package/dist/src/components/sidebar-right/edits/editors/NaiveH4Editor.d.ts +0 -2
  55. package/dist/src/components/sidebar-right/edits/editors/NaiveH5Editor.d.ts +0 -2
  56. package/dist/src/components/sidebar-right/edits/editors/NaiveH6Editor.d.ts +0 -2
  57. package/dist/src/components/sidebar-right/edits/editors/NaiveHeaderEditor.d.ts +0 -2
  58. package/dist/src/components/sidebar-right/edits/editors/NaiveLiEditor.d.ts +0 -2
  59. package/dist/src/components/sidebar-right/edits/editors/NaiveLinkEditor.d.ts +0 -2
  60. package/dist/src/components/sidebar-right/edits/editors/NaiveMentionEditor.d.ts +0 -2
  61. package/dist/src/components/sidebar-right/edits/editors/NaiveOlEditor.d.ts +0 -2
  62. package/dist/src/components/sidebar-right/edits/editors/NaiveParagraphEditor.d.ts +0 -2
  63. package/dist/src/components/sidebar-right/edits/editors/NaiveRateEditor.d.ts +0 -2
  64. package/dist/src/components/sidebar-right/edits/editors/NaiveSwitchEditor.d.ts +0 -2
  65. package/dist/src/components/sidebar-right/edits/editors/NaiveTextEditor.d.ts +0 -2
  66. package/dist/src/components/sidebar-right/edits/editors/NaiveTreeSelectEditor.d.ts +0 -2
  67. package/dist/src/components/sidebar-right/edits/editors/NaiveUlEditor.d.ts +0 -2
  68. package/dist/src/components/sidebar-right/edits/editors/NumberEditor.d.ts +0 -2
  69. package/dist/src/components/sidebar-right/edits/editors/RadioEditor.d.ts +0 -2
  70. package/dist/src/components/sidebar-right/edits/editors/RangeEditor.d.ts +0 -2
  71. package/dist/src/components/sidebar-right/edits/editors/SelectEditor.d.ts +0 -2
  72. package/dist/src/components/sidebar-right/edits/editors/SubmitEditor.d.ts +0 -2
  73. package/dist/src/components/sidebar-right/edits/editors/TextLikeEditor.d.ts +0 -2
  74. package/dist/src/components/sidebar-right/validations/DoubleParamValidation.d.ts +0 -11
  75. package/dist/src/components/sidebar-right/validations/SingleParamValidation.d.ts +0 -8
  76. package/dist/src/components/sidebar-right/validations/SingleValueValidation.d.ts +0 -7
  77. package/dist/src/components/sidebar-right/validations/ValidationSection.d.ts +0 -2
  78. package/dist/src/components/sidebar-right/validations/index.d.ts +0 -3
  79. package/dist/src/components/ui/button/CustomButton.d.ts +0 -5
  80. package/dist/src/components/ui/formkit/NaiveAvatar.d.ts +0 -6
  81. package/dist/src/components/ui/formkit/NaiveCascader.d.ts +0 -6
  82. package/dist/src/components/ui/formkit/NaiveCheckbox.d.ts +0 -6
  83. package/dist/src/components/ui/formkit/NaiveCheckboxGroup.d.ts +0 -6
  84. package/dist/src/components/ui/formkit/NaiveColorPicker.d.ts +0 -6
  85. package/dist/src/components/ui/formkit/NaiveDatePicker.d.ts +0 -6
  86. package/dist/src/components/ui/formkit/NaiveDivider.d.ts +0 -6
  87. package/dist/src/components/ui/formkit/NaiveMention.d.ts +0 -6
  88. package/dist/src/components/ui/formkit/NaiveNumberInput.d.ts +0 -6
  89. package/dist/src/components/ui/formkit/NaiveRadioGroup.d.ts +0 -6
  90. package/dist/src/components/ui/formkit/NaiveRate.d.ts +0 -6
  91. package/dist/src/components/ui/formkit/NaiveSelect.d.ts +0 -6
  92. package/dist/src/components/ui/formkit/NaiveSlider.d.ts +0 -6
  93. package/dist/src/components/ui/formkit/NaiveSwitch.d.ts +0 -6
  94. package/dist/src/components/ui/formkit/NaiveTextInput.d.ts +0 -6
  95. package/dist/src/components/ui/formkit/NaiveTextarea.d.ts +0 -6
  96. package/dist/src/components/ui/formkit/NaiveTimePicker.d.ts +0 -6
  97. package/dist/src/components/ui/formkit/NaiveTreeSelect.d.ts +0 -6
  98. package/dist/src/components/ui/formkit/NaiveTypographyA.d.ts +0 -6
  99. package/dist/src/components/ui/formkit/NaiveTypographyBlockquote.d.ts +0 -6
  100. package/dist/src/components/ui/formkit/NaiveTypographyHeader.d.ts +0 -6
  101. package/dist/src/components/ui/formkit/NaiveTypographyHr.d.ts +0 -6
  102. package/dist/src/components/ui/formkit/NaiveTypographyLi.d.ts +0 -6
  103. package/dist/src/components/ui/formkit/NaiveTypographyOl.d.ts +0 -6
  104. package/dist/src/components/ui/formkit/NaiveTypographyP.d.ts +0 -6
  105. package/dist/src/components/ui/formkit/NaiveTypographyText.d.ts +0 -6
  106. package/dist/src/components/ui/formkit/NaiveTypographyUl.d.ts +0 -6
  107. package/dist/src/components/ui/formkit/NaiveUpload.d.ts +0 -6
  108. package/dist/src/components/ui/sonner/Sonner.d.ts +0 -3
  109. package/dist/src/components/ui/sonner/index.d.ts +0 -1
  110. package/dist/src/components/ui/theme-switcher/ThemeSwitcher.d.ts +0 -2
  111. package/dist/src/components/ui/validation-card/ValidationCard.d.ts +0 -21
  112. package/dist/src/components/ui/validation-card/ValidationSwitch.d.ts +0 -14
  113. package/dist/src/components/ui/validation-card/index.d.ts +0 -2
  114. package/dist/src/composables/form-fields.d.ts +0 -809
  115. package/dist/src/composables/schema-history.d.ts +0 -12
  116. package/dist/src/composables/use-config.d.ts +0 -5
  117. package/dist/src/formkit.config.d.ts +0 -11
  118. package/dist/src/formkit.theme.d.ts +0 -26
  119. package/dist/src/i18n/context.d.ts +0 -12
  120. package/dist/src/i18n/messages.d.ts +0 -332
  121. package/dist/src/index.d.ts +0 -7
  122. package/dist/src/style-entry.d.ts +0 -1
  123. package/dist/src/types/env.d.ts +0 -5
  124. package/dist/src/utils/custom-insert-plugin.d.ts +0 -17
  125. package/dist/src/utils/default-form-elements.d.ts +0 -1558
  126. package/dist/src/utils/expression-eval.d.ts +0 -10
  127. package/dist/src/utils/field-props.d.ts +0 -8
  128. package/dist/src/utils/format-schema.d.ts +0 -3
  129. package/dist/src/utils/utils.d.ts +0 -10
  130. package/dist/style.cjs +0 -0
  131. package/dist/style.css +0 -2
  132. package/dist/style.d.ts +0 -1
  133. package/dist/style.mjs +0 -0
package/LICENSE ADDED
@@ -0,0 +1,168 @@
1
+ GNU LESSER GENERAL PUBLIC LICENSE
2
+ Version 3, 29 June 2007
3
+
4
+ Copyright (C) 2026 zengJiaJun
5
+ Project: formkit-form-builder
6
+ Repository: https://github.com/zeng-alt/formkit-form-builder
7
+
8
+ Everyone is permitted to copy and distribute verbatim copies
9
+ of this license document, but changing it is not allowed.
10
+
11
+
12
+ This version of the GNU Lesser General Public License incorporates
13
+ the terms and conditions of version 3 of the GNU General Public
14
+ License, supplemented by the additional permissions listed below.
15
+
16
+ 0. Additional Definitions.
17
+
18
+ As used herein, "this License" refers to version 3 of the GNU Lesser
19
+ General Public License, and the "GNU GPL" refers to version 3 of the GNU
20
+ General Public License.
21
+
22
+ "The Library" refers to a covered work governed by this License,
23
+ other than an Application or a Combined Work as defined below.
24
+
25
+ An "Application" is any work that makes use of an interface provided
26
+ by the Library, but which is not otherwise based on the Library.
27
+ Defining a subclass of a class defined by the Library is deemed a mode
28
+ of using an interface provided by the Library.
29
+
30
+ A "Combined Work" is a work produced by combining or linking an
31
+ Application with the Library. The particular version of the Library
32
+ with which the Combined Work was made is also called the "Linked
33
+ Version".
34
+
35
+ The "Minimal Corresponding Source" for a Combined Work means the
36
+ Corresponding Source for the Combined Work, excluding any source code
37
+ for portions of the Combined Work that, considered in isolation, are
38
+ based on the Application, and not on the Linked Version.
39
+
40
+ The "Corresponding Application Code" for a Combined Work means the
41
+ object code and/or source code for the Application, including any data
42
+ and utility programs needed for reproducing the Combined Work from the
43
+ Application, but excluding the System Libraries of the Combined Work.
44
+
45
+ 1. Exception to Section 3 of the GNU GPL.
46
+
47
+ You may convey a covered work under sections 3 and 4 of this License
48
+ without being bound by section 3 of the GNU GPL.
49
+
50
+ 2. Conveying Modified Versions.
51
+
52
+ If you modify a copy of the Library, and, in your modifications, a
53
+ facility refers to a function or data to be supplied by an Application
54
+ that uses the facility (other than as an argument passed when the
55
+ facility is invoked), then you may convey a copy of the modified
56
+ version:
57
+
58
+ a) under this License, provided that you make a good faith effort to
59
+ ensure that, in the event an Application does not supply the
60
+ function or data, the facility still operates, and performs
61
+ whatever part of its purpose remains meaningful, or
62
+
63
+ b) under the GNU GPL, with none of the additional permissions of
64
+ this License applicable to that copy.
65
+
66
+ 3. Object Code Incorporating Material from Library Header Files.
67
+
68
+ The object code form of an Application may incorporate material from
69
+ a header file that is part of the Library. You may convey such object
70
+ code under terms of your choice, provided that, if the incorporated
71
+ material is not limited to numerical parameters, data structure
72
+ layouts and accessors, or small macros, inline functions and templates
73
+ (ten or fewer lines in length), you do both of the following:
74
+
75
+ a) Give prominent notice with each copy of the object code that the
76
+ Library is used in it and that the Library and its use are
77
+ covered by this License.
78
+
79
+ b) Accompany the object code with a copy of the GNU GPL and this license
80
+ document.
81
+
82
+ 4. Combined Works.
83
+
84
+ You may convey a Combined Work under terms of your choice that,
85
+ taken together, effectively do not restrict modification of the
86
+ portions of the Library contained in the Combined Work and reverse
87
+ engineering for debugging such modifications, if you also do each of
88
+ the following:
89
+
90
+ a) Give prominent notice with each copy of the Combined Work that
91
+ the Library is used in it and that the Library and its use are
92
+ covered by this License.
93
+
94
+ b) Accompany the Combined Work with a copy of the GNU GPL and this license
95
+ document.
96
+
97
+ c) For a Combined Work that displays copyright notices during
98
+ execution, include the copyright notice for the Library among
99
+ these notices, as well as a reference directing the user to the
100
+ copies of the GNU GPL and this license document.
101
+
102
+ d) Do one of the following:
103
+
104
+ 0) Convey the Minimal Corresponding Source under the terms of this
105
+ License, and the Corresponding Application Code in a form
106
+ suitable for, and under terms that permit, the user to
107
+ recombine or relink the Application with a modified version of
108
+ the Linked Version to produce a modified Combined Work, in the
109
+ manner specified by section 6 of the GNU GPL for conveying
110
+ Corresponding Source.
111
+
112
+ 1) Use a suitable shared library mechanism for linking with the
113
+ Library. A suitable mechanism is one that (a) uses at run time
114
+ a copy of the Library already present on the user's computer
115
+ system, and (b) will operate properly with a modified version
116
+ of the Library that is interface-compatible with the Linked
117
+ Version.
118
+
119
+ e) Provide Installation Information, but only if you would otherwise
120
+ be required to provide such information under section 6 of the
121
+ GNU GPL, and only to the extent that such information is
122
+ necessary to install and execute a modified version of the
123
+ Combined Work produced by recombining or relinking the
124
+ Application with a modified version of the Linked Version. (If
125
+ you use option 4d0, the Installation Information must accompany
126
+ the Minimal Corresponding Source and Corresponding Application
127
+ Code. If you use option 4d1, you must provide the Installation
128
+ Information in the manner specified by section 6 of the GNU GPL
129
+ for conveying Corresponding Source.)
130
+
131
+ 5. Combined Libraries.
132
+
133
+ You may place library facilities that are a work based on the
134
+ Library side by side in a single library together with other library
135
+ facilities that are not Applications and are not covered by this
136
+ License, and convey such a combined library under terms of your
137
+ choice, if you do both of the following:
138
+
139
+ a) Accompany the combined library with a copy of the same work based
140
+ on the Library, uncombined with any other library facilities,
141
+ conveyed under the terms of this License.
142
+
143
+ b) Give prominent notice with the combined library that part of it
144
+ is a work based on the Library, and explaining where to find the
145
+ accompanying uncombined form of the same work.
146
+
147
+ 6. Revised Versions of the GNU Lesser General Public License.
148
+
149
+ The Free Software Foundation may publish revised and/or new versions
150
+ of the GNU Lesser General Public License from time to time. Such new
151
+ versions will be similar in spirit to the present version, but may
152
+ differ in detail to address new problems or concerns.
153
+
154
+ Each version is given a distinguishing version number. If the
155
+ Library as you received it specifies that a certain numbered version
156
+ of the GNU Lesser General Public License "or any later version"
157
+ applies to it, you have the option of following the terms and
158
+ conditions either of that published version or of any later version
159
+ published by the Free Software Foundation. If the Library as you
160
+ received it does not specify a version number of the GNU Lesser
161
+ General Public License, you may choose any version of the GNU Lesser
162
+ General Public License ever published by the Free Software Foundation.
163
+
164
+ If the Library as you received it specifies that a proxy can decide
165
+ whether future versions of the GNU Lesser General Public License shall
166
+ apply, that proxy's public statement of acceptance of any version is
167
+ permanent authorization for you to choose that version for the
168
+ Library.
package/README.md CHANGED
@@ -1,114 +1,290 @@
1
1
  # formkit-form-builder
2
2
 
3
- 基于 Vue 3 + FormKit 的可视化表单 Schema 设计器(左侧物料库 / 中间画布 / 右侧属性面板),支持拖拽搭建、校验配置、预览,以及可选的 AI 生成 Schema。
3
+ [中文文档](./README-zh.md) | **English**
4
4
 
5
- ## 安装
5
+ A visual FormKit Schema designer based on Vue 3 + FormKit (left sidebar / center canvas / right property panel), supporting drag-and-drop building, validation configuration, preview, and optional AI-powered Schema generation.
6
+
7
+ Core concept: The designer outputs a **versioned DSL (`FormDefinition`)** rather than raw schema. The `FormRenderer` (internally using `dslToSchema` conversion) renders it into a FormKit form. The DSL is a JSON-safe structure that can be directly deserialized by backends (e.g., Java).
8
+
9
+ ## Installation
6
10
 
7
11
  ```bash
8
12
  pnpm i @zeng-alt/formkit-form-builder
9
13
  ```
10
14
 
11
- 本库依赖以下 peer 依赖(需要你在项目里自行安装,版本按你项目实际选择即可):
15
+ This library depends on the following peer dependencies (you need to install them in your project):
12
16
 
13
17
  ```bash
14
18
  pnpm i vue naive-ui @vueuse/core
15
19
  ```
16
20
 
17
- ## 样式引入
21
+ ## Style Import
22
+
23
+ The ESM entry automatically loads styles — no manual import needed. Only required when using UMD / script-tag:
18
24
 
19
25
  ```ts
20
- import "@zeng-alt/formkit-form-builder/style.css";
26
+ import "@zeng-alt/formkit-form-builder/builder.css";
21
27
  ```
22
28
 
23
- ## 快速开始
29
+ ## Quick Start
24
30
 
25
- ### 1) 安装并注册 FormKit
31
+ ### 1) Install and Register FormKit
26
32
 
27
- 示例(Vite + Vue 3):
33
+ Use the built-in `formkitConfig()` factory (auto-registers all built-in elements) to set up FormKit:
28
34
 
29
35
  ```ts
30
36
  // main.ts
31
37
  import { createApp } from "vue";
32
38
  import { plugin as formkitPlugin } from "@formkit/vue";
39
+ import { formkitConfig } from "@zeng-alt/formkit-form-builder";
33
40
  import App from "./App.vue";
34
- import formkitConfig from "./formkit.config";
35
41
 
36
- createApp(App).use(formkitPlugin, formkitConfig).mount("#app");
42
+ createApp(App).use(formkitPlugin, formkitConfig()).mount("#app");
37
43
  ```
38
44
 
39
- ### 2) 使用 FormBuilder
45
+ > Alternatively, use the one-step plugin `FormBuilderPlugin` (auto-configures FormKit + global config + element registration), see below.
46
+
47
+ ### 2) Use FormBuilder
40
48
 
41
49
  ```vue
42
50
  <script setup lang="ts">
43
- import { FormBuilder, BuilderProvider } from "formkit-form-builder";
44
- import "formkit-form-builder/style.css";
51
+ import { ref } from "vue";
52
+ import { FormBuilder, BuilderProvider } from "@zeng-alt/formkit-form-builder";
53
+ import type { FormDefinition } from "@zeng-alt/formkit-form-builder";
45
54
 
55
+ const definition = ref<FormDefinition>();
46
56
  const config = {
47
- locale: "zh-CN",
48
- apiKey: "",
57
+ apiKey: "", // Optional: required for AI panel with OpenAI
49
58
  };
50
59
  </script>
51
60
 
52
61
  <template>
53
62
  <BuilderProvider :config="config">
54
- <FormBuilder />
63
+ <FormBuilder v-model="definition" />
55
64
  </BuilderProvider>
56
65
  </template>
57
66
  ```
58
67
 
59
- ## API
68
+ `FormBuilder` binds `FormDefinition` via `v-model` bidirectionally: preload existing forms and emit edits in real time, ready to save to backend.
60
69
 
61
- ### 导出
70
+ ### 3) Render Forms
62
71
 
63
- ```ts
64
- import {
65
- FormBuilder,
66
- BuilderProvider,
67
- BuilderPreview,
68
- FormSchemaRenderer,
69
- FormBuilderProvider,
70
- useFormBuilderConfig,
71
- provideFormBuilderConfig,
72
- } from "formkit-form-builder";
73
- ```
74
-
75
- - `FormBuilder`:主组件(设计器 UI)。
76
- - `BuilderProvider / FormBuilderProvider`:提供全局配置(同一个组件,两个别名)。
77
- - `FormSchemaRenderer`:对外表单渲染组件(渲染 builder 产出的 schema)。
78
- - `BuilderPreview`:对外可复用的弹窗渲染组件(基于 FormSchemaRenderer)。
79
- - `useFormBuilderConfig / provideFormBuilderConfig`:低层配置注入工具(通常你只需要 `BuilderProvider`)。
80
-
81
- ### 表单渲染(对外)
72
+ `FormRenderer` (renamed from `FormSchemaRenderer`) renders `FormDefinition` into a fillable, submittable FormKit form:
82
73
 
83
74
  ```vue
84
75
  <script setup lang="ts">
85
76
  import { ref } from "vue";
86
- import { FormSchemaRenderer } from "formkit-form-builder";
77
+ import { FormRenderer } from "@zeng-alt/formkit-form-builder";
78
+ import type { FormDefinition } from "@zeng-alt/formkit-form-builder";
87
79
 
88
- const schema = ref([]);
80
+ const definition = ref<FormDefinition>();
89
81
  const data = ref({});
90
82
  </script>
91
83
 
92
84
  <template>
93
- <FormSchemaRenderer :schema="schema" v-model="data" @submit="(v) => console.log(v)" />
85
+ <FormRenderer
86
+ :definition="definition"
87
+ v-model="data"
88
+ :actions="true"
89
+ @submit="(v) => console.log(v)"
90
+ />
91
+ </template>
92
+ ```
93
+
94
+ - `definition`: Primary input (versioned DSL); alternatively pass raw FormKit schema via `schema` (choose one; `definition` takes priority if both provided).
95
+ - `dataStructure`: `'flat'` (default, flat output) | `'nested'` (containers converted to group nesting).
96
+ - Other optional props: `formName`, `labelPosition` (`'top' | 'left'`), `labelWidth`, `formClass`, `interactiveContainers`, etc.
97
+ - **Theming**: The single source of truth is `BuilderProvider` (renders an `n-config-provider`). Supports `theme` prop (`BuilderTheme`: `'light' | 'dark'`, defaults to system preference) + remaining `ConfigProviderProps` (`themeOverrides` / `breakpoints`, etc.) passed through. `FormBuilder` / `FormRenderer` as children inherit the Provider's theme, ensuring consistency; both also retain independent `theme` / `ConfigProviderProps` props (only effective when not wrapped by `BuilderProvider`, used standalone). Built-in `ThemeSwitcher` (dark / light / system) shares the same `useColorMode` data source as the `theme` prop, keeping naive-ui theme and UnoCSS `dark:` styles in sync.
98
+ - **i18n**: Reads runtime locale from the containing `BuilderProvider` / `FormBuilder` (default `zh-CN`), syncing FormKit submit button and validation messages; can also override via `:locale` / `:date-locale` with naive language packs.
99
+
100
+ `FormRenderer` can be used alongside `FormBuilder` inside `BuilderProvider` (sharing `config.locale` / element registration / theme). Configure theme once on Provider, both stay consistent:
101
+
102
+ ```vue
103
+ <BuilderProvider :config="config" :theme="isDark ? 'dark' : 'light'">
104
+ <div class="grid grid-cols-2">
105
+ <FormBuilder v-model="definition" />
106
+ <FormRenderer :definition="definition" />
107
+ </div>
108
+ </BuilderProvider>
109
+ ```
110
+
111
+ ## One-Step Plugin
112
+
113
+ Don't want to manually `app.use(plugin, formkitConfig())` + wrap `BuilderProvider`? Use `FormBuilderPlugin` to do it all in one step:
114
+
115
+ ```ts
116
+ // main.ts
117
+ import { createApp } from "vue";
118
+ import { FormBuilderPlugin } from "@zeng-alt/formkit-form-builder";
119
+ import App from "./App.vue";
120
+
121
+ createApp(App).use(FormBuilderPlugin, {
122
+ config: { apiKey: "" },
123
+ }).mount("#app");
124
+ ```
125
+
126
+ ```vue
127
+ <template>
128
+ <!-- No BuilderProvider needed, use directly -->
129
+ <FormBuilder v-model="definition" />
130
+ <FormRenderer :definition="definition" />
94
131
  </template>
95
132
  ```
96
133
 
134
+ ## API
135
+
136
+ ### Exports
137
+
138
+ ```ts
139
+ import {
140
+ FormBuilder, // Main designer component
141
+ FormBuilderProvider, // BuilderProvider alias
142
+ BuilderProvider, // Global config provider
143
+ BuilderPreview, // Reusable preview modal component
144
+ FormRenderer, // Form rendering component (renamed from FormSchemaRenderer)
145
+ FormSchemaRenderer, // @deprecated use FormRenderer
146
+ FormBuilderPlugin, // One-step plugin
147
+ formkitConfig, // FormKit config factory (accepts custom elements)
148
+ registerElement, // Config-based element extension
149
+ registerElements,
150
+ setGlobalFormBuilderConfig, // Global config (plugin / no Provider scenarios)
151
+ useFormBuilderConfig,
152
+ provideFormBuilderConfig,
153
+ createFormBuilderState, // Multi-designer instance state
154
+ useFormBuilderState,
155
+ provideFormBuilderState,
156
+ dslToSchema, // DSL → FormKit schema
157
+ dslToOutputSchema, // DSL → nested group output schema
158
+ schemaToDsl, // Raw schema → DSL
159
+ buildFormkitInputs,
160
+ } from "@zeng-alt/formkit-form-builder";
161
+ ```
162
+
163
+ ---
164
+
165
+ ### FormBuilder API
166
+
167
+ #### Props
168
+
169
+ | Prop | Type | Default | Description |
170
+ |------|------|---------|-------------|
171
+ | `modelValue` | `FormDefinition` | - | Form definition: v-model bidirectional binding; preload existing form and emit edits in real time |
172
+ | `config` | `FormBuilderConfig` | - | Instance config; if provided, self-contained (registerElements + provide); otherwise falls back to injected `BuilderProvider` |
173
+ | `theme` | `BuilderTheme` (`'light' \| 'dark'`) | Auto (system) | Custom theme: maps to naive-ui's `darkTheme` / `lightTheme` |
174
+ | `...ConfigProviderProps` | `Partial<ConfigProviderProps>` | - | Pass-through for remaining naive-ui ConfigProvider props (`themeOverrides`, `breakpoints`, etc.) |
175
+
176
+ #### Events
177
+
178
+ | Event | Payload | Description |
179
+ |-------|---------|-------------|
180
+ | `update:modelValue` | `value: FormDefinition` | Emitted when form definition changes (v-model bidirectional binding) |
181
+
182
+ #### Slots
183
+
184
+ | Slot | Scope | Description |
185
+ |------|-------|-------------|
186
+ | `header` | - | Entire header bar (including default content) |
187
+ | `header-left` | - | Header left area (clear / preview); uses default if not provided |
188
+ | `header-center` | - | Header center area (AI prompt); uses default if not provided |
189
+ | `header-right` | - | Header right area (undo/redo / theme); uses default if not provided |
190
+ | `empty` | - | Canvas empty state; uses default NEmpty if not provided |
191
+ | `toolbar` | - | Right sidebar actions (import/export / language switch); uses default if not provided |
192
+
193
+ ---
194
+
195
+ ### FormRenderer API (formerly FormSchemaRenderer)
196
+
197
+ #### Props
198
+
199
+ | Prop | Type | Default | Description |
200
+ |------|------|---------|-------------|
201
+ | `definition` | `FormDefinition` | - | **Primary input**: Versioned DSL form definition; internally converted via `dslToSchema` |
202
+ | `schema` | `FormKitSchemaFormKit[]` | - | **Alternative input**: Raw FormKit schema array; if both `definition` and `schema` provided, `definition` takes priority |
203
+ | `dataStructure` | `'flat' \| 'nested'` | `'flat'` | Output structure when `definition` provided: `flat` (flat) \| `nested` (containers as group nesting) |
204
+ | `modelValue` | `Record<string, unknown>` | `{}` | Form data v-model bidirectional binding |
205
+ | `actions` | `boolean` | `false` | Render default action bar (submit/reset buttons); `false` hides it, use `#actions` slot for custom |
206
+ | `submitLabel` | `string` | i18n: Submit | Default submit button label |
207
+ | `resetLabel` | `string` | i18n: Reset | Default reset button label |
208
+ | `submitAttrs` | `Record<string, unknown>` | - | Default submit button pass-through attrs (naive NButton props) |
209
+ | `resetAttrs` | `Record<string, unknown>` | - | Default reset button pass-through attrs (naive NButton props) |
210
+ | `actionsJustify` | `'start' \| 'center' \| 'end' \| 'space-between'` | `'start'` | Default action bar button alignment |
211
+ | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
212
+ | `formName` | `string` | - | Form name (priority: schema form.name > this prop) |
213
+ | `labelPosition` | `'top' \| 'left'` | `'top'` | Label position (priority: schema form.props.labelPosition > this prop) |
214
+ | `labelWidth` | `number` | `80` | Label width (priority: schema form.props.labelWidth > this prop) |
215
+ | `schemaLibrary` | `Record<string, Component>` | Built-in preview lib | Custom schema component library (overrides built-in preview components) |
216
+ | `interactiveContainers` | `boolean` | `true` | Enable interactions (add/remove rows) for list/card/input-group/button-group/tabs containers |
217
+ | `theme` | `BuilderTheme` (`'light' \| 'dark'`) | Auto (system) | Custom theme: maps to naive-ui's `darkTheme` / `lightTheme` |
218
+ | `...ConfigProviderProps` | `Partial<ConfigProviderProps>` | - | Pass-through for remaining naive-ui ConfigProvider props |
219
+
220
+ #### Events
221
+
222
+ | Event | Payload | Description |
223
+ |-------|---------|-------------|
224
+ | `update:modelValue` | `value: Record<string, unknown>` | Emitted when form data changes (v-model bidirectional binding) |
225
+ | `submit` | `formData, id?, version?` | Emitted on form submit (not triggered if required validation fails) |
226
+
227
+ #### Slots
228
+
229
+ | Slot | Scope | Description |
230
+ |------|-------|-------------|
231
+ | `actions` | `{ submit: () => void, reset: () => void, loading: boolean }` | Custom action bar (overrides default submit/reset buttons) |
232
+
233
+ #### Methods (via `defineExpose`)
234
+
235
+ | Method | Type | Description |
236
+ |--------|------|-------------|
237
+ | `submit` | `() => void` | Submit form (does not trigger submit event if required validation fails) |
238
+ | `reset` | `() => void` | Reset form to initial values |
239
+ | `loading` | `Ref<boolean>` | Submit loading state |
240
+
241
+ ---
242
+
97
243
  ### FormBuilderConfig
98
244
 
99
245
  ```ts
100
246
  export interface FormBuilderConfig {
101
- apiKey?: string;
102
- locale?: string;
103
- messages?: Record<string, any>;
247
+ apiKey?: string; // Required for AI panel with OpenAI
248
+ locale?: string; // Default: zh-CN
249
+ messages?: Record<string, any>; // i18n overrides (same structure as default messages)
250
+ elements?: RegisterElementInput[]; // Extended elements (config-based registration)
104
251
  }
105
252
  ```
106
253
 
107
- - `apiKey`:可选,AI 面板使用 OpenAI 时需要。
108
- - `locale`:可选,默认 `zh-CN`。
109
- - `messages`:可选,多语言覆写(结构与默认 messages 一致)。
254
+ ### DSL & Conversion
255
+
256
+ DSL node types: `FormDefinition` / `FormNode` (`FieldNode` / `ContainerNode` / `StaticNode` / `LayoutNode`), `NodeCategory` (`field | container | layout | static`), `RenderKind` (`formkit | cmp | el`). DSL is JSON-safe, serializable directly to backend.
257
+
258
+ ```ts
259
+ import { dslToSchema, schemaToDsl, dslToOutputSchema } from "@zeng-alt/formkit-form-builder";
260
+ import type { FormDefinition } from "@zeng-alt/formkit-form-builder";
261
+
262
+ const schema = dslToSchema(definition); // For rendering
263
+ const outputSchema = dslToOutputSchema(definition); // Containers as group nesting (backend-model friendly)
264
+ const backToDsl = schemaToDsl(schema);
265
+ ```
266
+
267
+ ### Extending Elements
110
268
 
111
- ## i18n 覆写
269
+ Register custom elements via `config.elements` or `registerElement(s)` (DSL registry + FormKit input + canvas/preview all at once):
270
+
271
+ ```ts
272
+ import { registerElement, formkitConfig } from "@zeng-alt/formkit-form-builder";
273
+ import type { RegisterElementInput } from "@zeng-alt/formkit-form-builder";
274
+
275
+ registerElement({
276
+ type: "myField",
277
+ category: "field",
278
+ label: "Custom Field",
279
+ // ... see RegisterElementInput type
280
+ });
281
+
282
+ createApp(App).use(plugin, formkitConfig());
283
+ ```
284
+
285
+ ## i18n Overrides
286
+
287
+ `messages[locale]` merges **recursively** with built-in copy (same structure). Provided keys override built-in; missing keys fall back to defaults (aligned with camunda7-ui semantics; arrays replaced wholesale). New locales can be injected; missing keys fall back to `en` during lookup.
112
288
 
113
289
  ```ts
114
290
  const config = {
@@ -116,49 +292,48 @@ const config = {
116
292
  messages: {
117
293
  "zh-CN": {
118
294
  builder: {
119
- clearForm: "清空当前表单",
295
+ clearForm: "Clear current form", // Only overrides this key; other builder.* preserved
120
296
  },
121
297
  },
122
298
  },
123
299
  };
124
300
  ```
125
301
 
126
- ## 示例
302
+ ## Examples
127
303
 
128
304
  ![light](./img/light.png)
129
305
  ![dark](./img/dark.png)
130
306
  ![preview](./img/preview.png)
131
307
 
132
- ## 发布到 npm(公共仓库)
308
+ ## Publish to npm (Public Registry)
133
309
 
134
- 1. 确认 `package.json`:
310
+ 1. Verify `package.json`:
311
+ - `name` is an available package name
312
+ - `version` updated (semver)
313
+ - `publishConfig.access = "public"`
314
+ - `private` removed
135
315
 
136
- - `name` 是未被占用的包名
137
- - `version` 已更新(遵循 semver)
138
- - `publishConfig.access = "public"`
139
- - `private` 已移除
140
-
141
- 2. 安装依赖并生成构建产物:
316
+ 2. Install deps and build:
142
317
 
143
318
  ```bash
144
319
  pnpm install --no-frozen-lockfile
145
320
  pnpm build
146
321
  ```
147
322
 
148
- 3. 登录并发布:
323
+ 3. Login and publish:
149
324
 
150
325
  ```bash
151
326
  npm login
152
327
  npm publish --access public
153
328
  ```
154
329
 
155
- 如果你用 pnpm:
330
+ Or with pnpm:
156
331
 
157
332
  ```bash
158
333
  pnpm publish --access public
159
334
  ```
160
335
 
161
- ## 开发(本仓库)
336
+ ## Development (This Repo)
162
337
 
163
338
  ```bash
164
339
  pnpm install
@@ -168,4 +343,4 @@ pnpm version patch # 1.0.0 → 1.0.1
168
343
  pnpm version minor # 1.0.0 → 1.1.0
169
344
  pnpm version major # 1.0.0 → 2.0.0
170
345
  pnpm publish
171
- ```
346
+ ```