@zeng-alt/formkit-form-builder 1.4.0 → 2.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 (231) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/README.md +323 -137
  3. package/dist/builder.css +1 -1
  4. package/dist/builder.es.js +7922 -42834
  5. package/dist/builder.es.js.map +1 -0
  6. package/dist/builder.umd.js +58 -86
  7. package/dist/chunks/AiPrompt-CWUhBDH4.js +174 -0
  8. package/dist/chunks/AiPrompt-CWUhBDH4.js.map +1 -0
  9. package/dist/chunks/BadgeEditor-B1kB2DXg.js +133 -0
  10. package/dist/chunks/BadgeEditor-B1kB2DXg.js.map +1 -0
  11. package/dist/chunks/BuilderPreview-CKL5bqCP.js +142 -0
  12. package/dist/chunks/BuilderPreview-CKL5bqCP.js.map +1 -0
  13. package/dist/chunks/ButtonGroupEditor-C5pChDFz.js +55 -0
  14. package/dist/chunks/ButtonGroupEditor-C5pChDFz.js.map +1 -0
  15. package/dist/chunks/CardEditor-Bsbriwvu.js +61 -0
  16. package/dist/chunks/CardEditor-Bsbriwvu.js.map +1 -0
  17. package/dist/chunks/CheckboxEditor-CxNEvn_Y.js +23 -0
  18. package/dist/chunks/CheckboxEditor-CxNEvn_Y.js.map +1 -0
  19. package/dist/chunks/CollapseEditor-CUFTdj0V.js +36 -0
  20. package/dist/chunks/CollapseEditor-CUFTdj0V.js.map +1 -0
  21. package/dist/chunks/ColorEditor-Bo9QkLsR.js +17 -0
  22. package/dist/chunks/ColorEditor-Bo9QkLsR.js.map +1 -0
  23. package/dist/chunks/DataTableContainerPreview-phlGcigM.js +403 -0
  24. package/dist/chunks/DataTableContainerPreview-phlGcigM.js.map +1 -0
  25. package/dist/chunks/DataTableEditor-BTDWXdtk.js +473 -0
  26. package/dist/chunks/DataTableEditor-BTDWXdtk.js.map +1 -0
  27. package/dist/chunks/DataTableFieldPicker-qWxGmVxr.js +1579 -0
  28. package/dist/chunks/DataTableFieldPicker-qWxGmVxr.js.map +1 -0
  29. package/dist/chunks/DataTableRowCellInput-BLTM3I21.js +195 -0
  30. package/dist/chunks/DataTableRowCellInput-BLTM3I21.js.map +1 -0
  31. package/dist/chunks/DataTableSearchField-PU89hniM.js +81 -0
  32. package/dist/chunks/DataTableSearchField-PU89hniM.js.map +1 -0
  33. package/dist/chunks/DateLikeEditor-ZkCbMhpE.js +74 -0
  34. package/dist/chunks/DateLikeEditor-ZkCbMhpE.js.map +1 -0
  35. package/dist/chunks/DateTimeEditor-C-jZKTT5.js +73 -0
  36. package/dist/chunks/DateTimeEditor-C-jZKTT5.js.map +1 -0
  37. package/dist/chunks/EditorSection-BR3qdK2c.js +23 -0
  38. package/dist/chunks/EditorSection-BR3qdK2c.js.map +1 -0
  39. package/dist/chunks/EditsLayout-fueCrxZM.js +22 -0
  40. package/dist/chunks/EditsLayout-fueCrxZM.js.map +1 -0
  41. package/dist/chunks/ExprEditModal-CeXiPStM.js +540 -0
  42. package/dist/chunks/ExprEditModal-CeXiPStM.js.map +1 -0
  43. package/dist/chunks/FileEditor-BXELd_SD.js +35 -0
  44. package/dist/chunks/FileEditor-BXELd_SD.js.map +1 -0
  45. package/dist/chunks/FormRenderer-BwykpB3h.js +2625 -0
  46. package/dist/chunks/FormRenderer-BwykpB3h.js.map +1 -0
  47. package/dist/chunks/GroupEditor-DchDUDDY.js +13 -0
  48. package/dist/chunks/GroupEditor-DchDUDDY.js.map +1 -0
  49. package/dist/chunks/HistoryPanel-1p0-Obef.js +104 -0
  50. package/dist/chunks/HistoryPanel-1p0-Obef.js.map +1 -0
  51. package/dist/chunks/ImportExportModal-CTqkyp1s.js +266 -0
  52. package/dist/chunks/ImportExportModal-CTqkyp1s.js.map +1 -0
  53. package/dist/chunks/InlineEditableText-BO-dT5rp.js +68 -0
  54. package/dist/chunks/InlineEditableText-BO-dT5rp.js.map +1 -0
  55. package/dist/chunks/InputGroupEditor-D_5giZtN.js +13 -0
  56. package/dist/chunks/InputGroupEditor-D_5giZtN.js.map +1 -0
  57. package/dist/chunks/IssuesPanel-CW5bdwvC.js +82 -0
  58. package/dist/chunks/IssuesPanel-CW5bdwvC.js.map +1 -0
  59. package/dist/chunks/JsCodeEditor-CIPxhwZa.js +751 -0
  60. package/dist/chunks/JsCodeEditor-CIPxhwZa.js.map +1 -0
  61. package/dist/chunks/JsonTextarea-C3mnRwtG.js +54 -0
  62. package/dist/chunks/JsonTextarea-C3mnRwtG.js.map +1 -0
  63. package/dist/chunks/ListEditor-C1hn5yOi.js +25 -0
  64. package/dist/chunks/ListEditor-C1hn5yOi.js.map +1 -0
  65. package/dist/chunks/NaiveAlertEditor-DACimYS1.js +67 -0
  66. package/dist/chunks/NaiveAlertEditor-DACimYS1.js.map +1 -0
  67. package/dist/chunks/NaiveAutoCompleteEditor-CtCvPe7H.js +122 -0
  68. package/dist/chunks/NaiveAutoCompleteEditor-CtCvPe7H.js.map +1 -0
  69. package/dist/chunks/NaiveAvatarEditor-CmDUodoa.js +36 -0
  70. package/dist/chunks/NaiveAvatarEditor-CmDUodoa.js.map +1 -0
  71. package/dist/chunks/NaiveBackTopEditor-Iq-li1JT.js +69 -0
  72. package/dist/chunks/NaiveBackTopEditor-Iq-li1JT.js.map +1 -0
  73. package/dist/chunks/NaiveBasicSection-wNyhGLou.js +184 -0
  74. package/dist/chunks/NaiveBasicSection-wNyhGLou.js.map +1 -0
  75. package/dist/chunks/NaiveBlockquoteEditor-BfqWqKwF.js +13 -0
  76. package/dist/chunks/NaiveBlockquoteEditor-BfqWqKwF.js.map +1 -0
  77. package/dist/chunks/NaiveButtonEditor-B4Rp2T7n.js +168 -0
  78. package/dist/chunks/NaiveButtonEditor-B4Rp2T7n.js.map +1 -0
  79. package/dist/chunks/NaiveCascaderEditor-BtD6KRXl.js +26 -0
  80. package/dist/chunks/NaiveCascaderEditor-BtD6KRXl.js.map +1 -0
  81. package/dist/chunks/NaiveDividerEditor-B1dPteDV.js +52 -0
  82. package/dist/chunks/NaiveDividerEditor-B1dPteDV.js.map +1 -0
  83. package/dist/chunks/NaiveH1Editor-Can7c9mh.js +14 -0
  84. package/dist/chunks/NaiveH1Editor-Can7c9mh.js.map +1 -0
  85. package/dist/chunks/NaiveH2Editor-BRKeEVf4.js +14 -0
  86. package/dist/chunks/NaiveH2Editor-BRKeEVf4.js.map +1 -0
  87. package/dist/chunks/NaiveH3Editor-DCdyd3-n.js +14 -0
  88. package/dist/chunks/NaiveH3Editor-DCdyd3-n.js.map +1 -0
  89. package/dist/chunks/NaiveH4Editor-COFS6udv.js +14 -0
  90. package/dist/chunks/NaiveH4Editor-COFS6udv.js.map +1 -0
  91. package/dist/chunks/NaiveH5Editor-CQEe6s1O.js +14 -0
  92. package/dist/chunks/NaiveH5Editor-CQEe6s1O.js.map +1 -0
  93. package/dist/chunks/NaiveH6Editor-DHGzIUAl.js +14 -0
  94. package/dist/chunks/NaiveH6Editor-DHGzIUAl.js.map +1 -0
  95. package/dist/chunks/NaiveHeaderEditor-Cy02AmLI.js +12 -0
  96. package/dist/chunks/NaiveHeaderEditor-Cy02AmLI.js.map +1 -0
  97. package/dist/chunks/NaiveImageEditor-WyVYLNbT.js +201 -0
  98. package/dist/chunks/NaiveImageEditor-WyVYLNbT.js.map +1 -0
  99. package/dist/chunks/NaiveLiEditor-CC65rrna.js +13 -0
  100. package/dist/chunks/NaiveLiEditor-CC65rrna.js.map +1 -0
  101. package/dist/chunks/NaiveLinkEditor-DkjFrzEE.js +38 -0
  102. package/dist/chunks/NaiveLinkEditor-DkjFrzEE.js.map +1 -0
  103. package/dist/chunks/NaiveMentionEditor-BupocM2c.js +23 -0
  104. package/dist/chunks/NaiveMentionEditor-BupocM2c.js.map +1 -0
  105. package/dist/chunks/NaiveOlEditor-DYFqg6Sp.js +16 -0
  106. package/dist/chunks/NaiveOlEditor-DYFqg6Sp.js.map +1 -0
  107. package/dist/chunks/NaiveParagraphEditor-B3Ju6ZNI.js +104 -0
  108. package/dist/chunks/NaiveParagraphEditor-B3Ju6ZNI.js.map +1 -0
  109. package/dist/chunks/NaiveProgressEditor-CwpsZG2z.js +119 -0
  110. package/dist/chunks/NaiveProgressEditor-CwpsZG2z.js.map +1 -0
  111. package/dist/chunks/NaiveQrCodeEditor-YWWAozHe.js +77 -0
  112. package/dist/chunks/NaiveQrCodeEditor-YWWAozHe.js.map +1 -0
  113. package/dist/chunks/NaiveRateEditor-BVY1QiXv.js +44 -0
  114. package/dist/chunks/NaiveRateEditor-BVY1QiXv.js.map +1 -0
  115. package/dist/chunks/NaiveSwitchEditor-BP1v-oZf.js +17 -0
  116. package/dist/chunks/NaiveSwitchEditor-BP1v-oZf.js.map +1 -0
  117. package/dist/chunks/NaiveTextEditor-C38l4Q-j.js +107 -0
  118. package/dist/chunks/NaiveTextEditor-C38l4Q-j.js.map +1 -0
  119. package/dist/chunks/NaiveTransferEditor-BRH_5ioX.js +19 -0
  120. package/dist/chunks/NaiveTransferEditor-BRH_5ioX.js.map +1 -0
  121. package/dist/chunks/NaiveTreeSelectEditor-jX2DrMcT.js +26 -0
  122. package/dist/chunks/NaiveTreeSelectEditor-jX2DrMcT.js.map +1 -0
  123. package/dist/chunks/NaiveUlEditor-CMKofBid.js +16 -0
  124. package/dist/chunks/NaiveUlEditor-CMKofBid.js.map +1 -0
  125. package/dist/chunks/NumberEditor-0P2Li_GH.js +40 -0
  126. package/dist/chunks/NumberEditor-0P2Li_GH.js.map +1 -0
  127. package/dist/chunks/NumberInput-DU-FiLxW.js +37 -0
  128. package/dist/chunks/NumberInput-DU-FiLxW.js.map +1 -0
  129. package/dist/chunks/OptionsLayoutSection-C9gVadRA.js +21 -0
  130. package/dist/chunks/OptionsLayoutSection-C9gVadRA.js.map +1 -0
  131. package/dist/chunks/OptionsSourceTabs-3fsum0OI.js +628 -0
  132. package/dist/chunks/OptionsSourceTabs-3fsum0OI.js.map +1 -0
  133. package/dist/chunks/OptionsTagsSection-vKkxlWLw.js +31 -0
  134. package/dist/chunks/OptionsTagsSection-vKkxlWLw.js.map +1 -0
  135. package/dist/chunks/PasswordEditor-Igld1ak6.js +29 -0
  136. package/dist/chunks/PasswordEditor-Igld1ak6.js.map +1 -0
  137. package/dist/chunks/PlaceholderSection-BKOS-7Qu.js +26 -0
  138. package/dist/chunks/PlaceholderSection-BKOS-7Qu.js.map +1 -0
  139. package/dist/chunks/RadioEditor-CyJhILjI.js +23 -0
  140. package/dist/chunks/RadioEditor-CyJhILjI.js.map +1 -0
  141. package/dist/chunks/RangeEditor-PGOnGfuV.js +86 -0
  142. package/dist/chunks/RangeEditor-PGOnGfuV.js.map +1 -0
  143. package/dist/chunks/RichText-DqcMtoil.js +424 -0
  144. package/dist/chunks/RichText-DqcMtoil.js.map +1 -0
  145. package/dist/chunks/RichTextEditor-EfA6m9w2.js +81 -0
  146. package/dist/chunks/RichTextEditor-EfA6m9w2.js.map +1 -0
  147. package/dist/chunks/SelectEditor-mJ_zUivj.js +21 -0
  148. package/dist/chunks/SelectEditor-mJ_zUivj.js.map +1 -0
  149. package/dist/chunks/SelectInput-DY4Oi2Lp.js +31 -0
  150. package/dist/chunks/SelectInput-DY4Oi2Lp.js.map +1 -0
  151. package/dist/chunks/SignatureEditor-BNttg68X.js +52 -0
  152. package/dist/chunks/SignatureEditor-BNttg68X.js.map +1 -0
  153. package/dist/chunks/SignaturePad-qhmoMg1E.js +170 -0
  154. package/dist/chunks/SignaturePad-qhmoMg1E.js.map +1 -0
  155. package/dist/chunks/StepsEditor-C8U-ext8.js +63 -0
  156. package/dist/chunks/StepsEditor-C8U-ext8.js.map +1 -0
  157. package/dist/chunks/SubmitEditor-B9R984q8.js +168 -0
  158. package/dist/chunks/SubmitEditor-B9R984q8.js.map +1 -0
  159. package/dist/chunks/SwitchInput-DQrSTyW0.js +34 -0
  160. package/dist/chunks/SwitchInput-DQrSTyW0.js.map +1 -0
  161. package/dist/chunks/TabsEditor-DepUhmsz.js +100 -0
  162. package/dist/chunks/TabsEditor-DepUhmsz.js.map +1 -0
  163. package/dist/chunks/TagsInput-DeG3Om1R.js +36 -0
  164. package/dist/chunks/TagsInput-DeG3Om1R.js.map +1 -0
  165. package/dist/chunks/TemplatePickerModal-DPkdJJJs.js +440 -0
  166. package/dist/chunks/TemplatePickerModal-DPkdJJJs.js.map +1 -0
  167. package/dist/chunks/TextInput-D1EMeBPf.js +53 -0
  168. package/dist/chunks/TextInput-D1EMeBPf.js.map +1 -0
  169. package/dist/chunks/TextLikeEditor-Du0nHQWQ.js +56 -0
  170. package/dist/chunks/TextLikeEditor-Du0nHQWQ.js.map +1 -0
  171. package/dist/chunks/ToggleInput-DoZPwM0A.js +51 -0
  172. package/dist/chunks/ToggleInput-DoZPwM0A.js.map +1 -0
  173. package/dist/chunks/_plugin-vue_export-helper-BxNYtmDu.js +8 -0
  174. package/dist/chunks/axios-agM_iOnv.js +1589 -0
  175. package/dist/chunks/axios-agM_iOnv.js.map +1 -0
  176. package/dist/chunks/bind-runtime-CRyrBYCi.js +58 -0
  177. package/dist/chunks/bind-runtime-CRyrBYCi.js.map +1 -0
  178. package/dist/chunks/canvas-locate-CxDD4bDp.js +64 -0
  179. package/dist/chunks/canvas-locate-CxDD4bDp.js.map +1 -0
  180. package/dist/chunks/context-4zkSHwVA.js +2510 -0
  181. package/dist/chunks/context-4zkSHwVA.js.map +1 -0
  182. package/dist/chunks/create-form-builder-state-CoXaJhWO.js +358 -0
  183. package/dist/chunks/create-form-builder-state-CoXaJhWO.js.map +1 -0
  184. package/dist/chunks/date-family-BYkr1OaE.js +75 -0
  185. package/dist/chunks/date-family-BYkr1OaE.js.map +1 -0
  186. package/dist/chunks/evaluator-DqNftI0d.js +139 -0
  187. package/dist/chunks/evaluator-DqNftI0d.js.map +1 -0
  188. package/dist/chunks/expr-parse-u7_CxMWg.js +463 -0
  189. package/dist/chunks/expr-parse-u7_CxMWg.js.map +1 -0
  190. package/dist/chunks/expr-source-BRPYrxuB.js +118 -0
  191. package/dist/chunks/expr-source-BRPYrxuB.js.map +1 -0
  192. package/dist/chunks/form-builder-plugin-BCbiWZKT.js +280 -0
  193. package/dist/chunks/form-builder-plugin-BCbiWZKT.js.map +1 -0
  194. package/dist/chunks/form-fields-DjLk8iH2.js +877 -0
  195. package/dist/chunks/form-fields-DjLk8iH2.js.map +1 -0
  196. package/dist/chunks/form-layout-Dm4QeYrL.js +69 -0
  197. package/dist/chunks/form-layout-Dm4QeYrL.js.map +1 -0
  198. package/dist/chunks/grid-C8xMKll5.js +137 -0
  199. package/dist/chunks/grid-C8xMKll5.js.map +1 -0
  200. package/dist/chunks/keys-D4DlFgJT.js +61 -0
  201. package/dist/chunks/keys-D4DlFgJT.js.map +1 -0
  202. package/dist/chunks/media-family-B4Wijm18.js +178 -0
  203. package/dist/chunks/media-family-B4Wijm18.js.map +1 -0
  204. package/dist/chunks/misc-family-CQJhCKco.js +133 -0
  205. package/dist/chunks/misc-family-CQJhCKco.js.map +1 -0
  206. package/dist/chunks/rich-text-toolbar-CQidmjGI.js +32 -0
  207. package/dist/chunks/rich-text-toolbar-CQidmjGI.js.map +1 -0
  208. package/dist/chunks/rolldown-runtime-DMoxecvO.js +11 -0
  209. package/dist/chunks/schema-adapter-_sLPmdLy.js +2089 -0
  210. package/dist/chunks/schema-adapter-_sLPmdLy.js.map +1 -0
  211. package/dist/chunks/selection-family-T_wZGrXc.js +249 -0
  212. package/dist/chunks/selection-family-T_wZGrXc.js.map +1 -0
  213. package/dist/chunks/use-ai-prompt-focus-39DHK41R.js +14 -0
  214. package/dist/chunks/use-ai-prompt-focus-39DHK41R.js.map +1 -0
  215. package/dist/chunks/use-bind-events-C-H7jhW_.js +89 -0
  216. package/dist/chunks/use-bind-events-C-H7jhW_.js.map +1 -0
  217. package/dist/chunks/use-config-DTr8dhzM.js +16 -0
  218. package/dist/chunks/use-config-DTr8dhzM.js.map +1 -0
  219. package/dist/chunks/use-dictionary-BAN34x49.js +26 -0
  220. package/dist/chunks/use-dictionary-BAN34x49.js.map +1 -0
  221. package/dist/chunks/use-dynamic-options-DbGSz-3_.js +29 -0
  222. package/dist/chunks/use-dynamic-options-DbGSz-3_.js.map +1 -0
  223. package/dist/chunks/use-schema-render-data-DagOPKiy.js +33 -0
  224. package/dist/chunks/use-schema-render-data-DagOPKiy.js.map +1 -0
  225. package/dist/chunks/utils-DlUMv2vG.js +53 -0
  226. package/dist/chunks/utils-DlUMv2vG.js.map +1 -0
  227. package/dist/index.d.ts +243 -1060
  228. package/dist/renderer.d.ts +632 -0
  229. package/dist/renderer.es.js +6 -0
  230. package/dist/renderer.umd.js +34 -0
  231. package/package.json +48 -33
package/README.md CHANGED
@@ -4,7 +4,29 @@
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
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).
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 body is a JSON-safe structure that can be directly deserialized by backends (e.g., Java); `key` (canvas DnD identity) and `meta.rawSchema` (fallback for unregistered types) are frontend-only fields — strip them with `toPortableDefinition` before persisting (see "DSL & Conversion" below).
8
+
9
+ ## Upgrading from 1.x
10
+
11
+ Version 2.0 removes the deprecated `FormSchemaRenderer` name (use `FormRenderer`) and unused renderer-engine type exports. Remove the ineffective `FormSettings.layout`, `columns`, and `fullWidth` properties, and use `top` or `left` for `labelAlign`. Calls to `useFormBuilderState()` now require a designer context; use `useOptionalFormBuilderState()` when that context may be absent. Install the FormKit peer dependencies listed below.
12
+
13
+ See the [2.0.0 changelog and migration notes](./CHANGELOG.md) before upgrading.
14
+
15
+ ## Feature Overview
16
+
17
+ - **Elements**: three categories — field / container / static (full catalog in `src/elements/definitions/*`) — covering common inputs plus rich text, a signature pad, a collapsible panel, and a data table, among others.
18
+ - **Canvas**: drag-and-drop from the left palette, a floating toolbar on the selected element, a right-click context menu, copy / cut / paste, multi-select (Shift- or Ctrl/Cmd-click toggles an element; siblings in the same container only) with batch property edits, wrapping selected elements into a container, and converting an element to a compatible type.
19
+ - **Structure tree**: the left-side outline stays in sync with canvas selection.
20
+ - **Undo history panel**: browse past edits and jump back to any of them, in addition to Ctrl/Cmd+Z / Shift+Z.
21
+ - **Templates & empty-canvas onboarding**: built-in starter templates (leave request, contact form, employee registration, user registration, satisfaction survey) plus guidance on an empty canvas.
22
+ - **Form-level settings**: control size, disabled, readonly, success message / redirect after submit, reset button visibility, and submit/reset button text.
23
+ - **Conditional logic**: conditional visibility, conditional required / disabled / readonly, and expression-computed field values.
24
+ - **Validation rules**: a configurable rule library per field type (see `docs/dsl.md` / `docs/dsl.en.md` for the full rule list).
25
+ - **Form health check**: a one-click scan for common issues (e.g. a condition referencing a non-existent field), with click-to-locate on each issue.
26
+ - **Rename-sync**: renaming a field automatically rewrites every `visibleIf` / `requiredIf` / `disabledIf` / `readonlyIf` / `expr` that references it elsewhere in the form.
27
+ - **Import / export**: round-trip a form definition as JSON.
28
+ - **Multi-device preview**: preview the form at desktop / tablet / mobile widths.
29
+ - **Dark theme**: built-in light/dark/system theme switcher, kept in sync with UnoCSS `dark:` styles.
8
30
 
9
31
  ## Installation
10
32
 
@@ -12,20 +34,56 @@ Core concept: The designer outputs a **versioned DSL (`FormDefinition`)** rather
12
34
  pnpm i @zeng-alt/formkit-form-builder
13
35
  ```
14
36
 
15
- This library depends on the following peer dependencies (you need to install them in your project):
37
+ This library depends on the following peer dependencies (you need to install them in your project). They are **required**:
16
38
 
17
39
  ```bash
18
- pnpm i vue naive-ui @vueuse/core
40
+ pnpm i vue naive-ui @vueuse/core @formkit/core @formkit/vue @formkit/i18n
19
41
  ```
20
42
 
43
+ The following are only needed if you use the designer's expression / JS binding editors (they power the CodeMirror-based code editor panels):
44
+
45
+ ```bash
46
+ pnpm i @codemirror/autocomplete @codemirror/commands @codemirror/lang-javascript @codemirror/language @codemirror/lint @codemirror/state @codemirror/theme-one-dark @codemirror/view
47
+ ```
48
+
49
+ > Why are these `peerDependencies` instead of being bundled? So this library shares **the same instances** of FormKit / CodeMirror with your project. FormKit keeps a global node/plugin/input-type/i18n-locale registry per module instance — two copies of `@formkit/core` (yours + one bundled inside this library) would not recognize each other's registrations, and fields could silently fail to render or validate. CodeMirror actively detects multiple `@codemirror/state` instances in the same page and throws — the code editor would simply break. Installing these as regular dependencies of your app (as peers) guarantees there's only ever one copy loaded.
50
+
21
51
  ## Style Import
22
52
 
23
53
  The ESM entry automatically loads styles — no manual import needed. Only required when using UMD / script-tag:
24
54
 
25
55
  ```ts
26
- import "@zeng-alt/formkit-form-builder/builder.css";
56
+ import '@zeng-alt/formkit-form-builder/builder.css'
57
+ ```
58
+
59
+ ## Renderer-Only Entry (form-filling pages)
60
+
61
+ If a page only needs to render a saved `FormDefinition` into a fillable, submittable form — no drag-and-drop canvas, no left/right property panels — use the runtime-only subpath `@zeng-alt/formkit-form-builder/renderer` instead:
62
+
63
+ ```ts
64
+ import {
65
+ FormRenderer,
66
+ formkitConfig,
67
+ registerElement,
68
+ dslToSchema,
69
+ useFormBuilderConfig,
70
+ } from '@zeng-alt/formkit-form-builder/renderer'
71
+ import type { FormDefinition } from '@zeng-alt/formkit-form-builder/renderer'
27
72
  ```
28
73
 
74
+ Styling still comes from the same `@zeng-alt/formkit-form-builder/builder.css` (no separate CSS file needed). This entry only exports what a form-filling page needs: `FormRenderer`, `formkitConfig`, `FormBuilderPlugin`, `registerElement`/`registerElements`, `buildFormkitInputs`/`buildElementSchemaLibrary`/`getElementCmpName`, the DSL conversion utilities (`dslToSchema`/`dslToOutputSchema`/`schemaToDsl`/`toPortableDefinition`/`setExprLocale`, etc.), the config composables, and their types — it excludes the designer (canvas, left/right panels), the drag-and-drop library `@formkit/drag-and-drop`, and the CodeMirror code editors. See `playground/renderer-only.html` for a working example.
75
+
76
+ Measured bundle size (`pnpm build-only` output, gzip):
77
+
78
+ | Artifact | First-screen static dependency total (gzip) |
79
+ | --- | --- |
80
+ | Full entry `.` (designer + renderer) | 167.2KB |
81
+ | Renderer entry `./renderer` | **70.3KB** |
82
+
83
+ For form-filling-only pages, switching to `/renderer` saves roughly 97KB (gzip) of designer-only code.
84
+
85
+ Heavier field/container components (date/time/file/color, cascader/tree-select/transfer/mention/autocomplete/rate, rich text/signature, slider/avatar/image, qr-code/progress/alert/back-to-top, and the data-table preview) are loaded on demand instead of being bundled eagerly — a form that only uses plain fields (text/select/checkbox/...) never downloads them at all. In a consuming app that only fills in text-like fields, this cuts the naive-ui portion of the page's first-screen JS from ~732KB to well under 300KB (gzip total first-screen JS drops from ~422KB to ~280KB); see the task report for the full before/after breakdown.
86
+
29
87
  ## Quick Start
30
88
 
31
89
  ### 1) Install and Register FormKit
@@ -34,12 +92,12 @@ Use the built-in `formkitConfig()` factory (auto-registers all built-in elements
34
92
 
35
93
  ```ts
36
94
  // main.ts
37
- import { createApp } from "vue";
38
- import { plugin as formkitPlugin } from "@formkit/vue";
39
- import { formkitConfig } from "@zeng-alt/formkit-form-builder";
40
- import App from "./App.vue";
95
+ import { createApp } from 'vue'
96
+ import { plugin as formkitPlugin } from '@formkit/vue'
97
+ import { formkitConfig } from '@zeng-alt/formkit-form-builder'
98
+ import App from './App.vue'
41
99
 
42
- createApp(App).use(formkitPlugin, formkitConfig()).mount("#app");
100
+ createApp(App).use(formkitPlugin, formkitConfig()).mount('#app')
43
101
  ```
44
102
 
45
103
  > Alternatively, use the one-step plugin `FormBuilderPlugin` (auto-configures FormKit + global config + element registration), see below.
@@ -48,14 +106,16 @@ createApp(App).use(formkitPlugin, formkitConfig()).mount("#app");
48
106
 
49
107
  ```vue
50
108
  <script setup lang="ts">
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";
109
+ import { ref } from 'vue'
110
+ import { FormBuilder, BuilderProvider } from '@zeng-alt/formkit-form-builder'
111
+ import type { FormDefinition } from '@zeng-alt/formkit-form-builder'
54
112
 
55
- const definition = ref<FormDefinition>();
113
+ const definition = ref<FormDefinition>()
56
114
  const config = {
57
- apiKey: "", // Optional: required for AI panel with OpenAI
58
- };
115
+ apiKey: '', // Optional: required for AI panel with OpenAI. Never ship a real key to
116
+ // the browser in production — point `aiBaseUrl` at your own server-side proxy instead.
117
+ // See "Security" below.
118
+ }
59
119
  </script>
60
120
 
61
121
  <template>
@@ -67,18 +127,20 @@ const config = {
67
127
 
68
128
  `FormBuilder` binds `FormDefinition` via `v-model` bidirectionally: preload existing forms and emit edits in real time, ready to save to backend.
69
129
 
130
+ > The definition emitted through `update:modelValue` is treated as immutable (in dev builds it is deeply frozen): don't mutate it in place — copy it first if you need a modified version. This lets the builder keep unchanged nodes' object identity across edits, which is what makes incremental re-rendering possible.
131
+
70
132
  ### 3) Render Forms
71
133
 
72
- `FormRenderer` (renamed from `FormSchemaRenderer`) renders `FormDefinition` into a fillable, submittable FormKit form:
134
+ `FormRenderer` renders `FormDefinition` into a fillable, submittable FormKit form:
73
135
 
74
136
  ```vue
75
137
  <script setup lang="ts">
76
- import { ref } from "vue";
77
- import { FormRenderer } from "@zeng-alt/formkit-form-builder";
78
- import type { FormDefinition } from "@zeng-alt/formkit-form-builder";
138
+ import { ref } from 'vue'
139
+ import { FormRenderer } from '@zeng-alt/formkit-form-builder'
140
+ import type { FormDefinition } from '@zeng-alt/formkit-form-builder'
79
141
 
80
- const definition = ref<FormDefinition>();
81
- const data = ref({});
142
+ const definition = ref<FormDefinition>()
143
+ const data = ref({})
82
144
  </script>
83
145
 
84
146
  <template>
@@ -92,7 +154,7 @@ const data = ref({});
92
154
  ```
93
155
 
94
156
  - `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).
157
+ - `dataStructure`: `'flat'` (default, flat output) | `'nested'` (containers converted to group nesting). Field references (`visibleIf` / `expr`) are resolved by field name across the whole form data tree, so behavior is consistent between `flat` and `nested` — when referencing a field across containers, keep field names globally unique (a duplicate name resolves to the first match found).
96
158
  - Other optional props: `formName`, `labelPosition` (`'top' | 'left'`), `labelWidth`, `formClass`, `interactiveContainers`, etc.
97
159
  - **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
160
  - **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.
@@ -114,13 +176,15 @@ Don't want to manually `app.use(plugin, formkitConfig())` + wrap `BuilderProvide
114
176
 
115
177
  ```ts
116
178
  // 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");
179
+ import { createApp } from 'vue'
180
+ import { FormBuilderPlugin } from '@zeng-alt/formkit-form-builder'
181
+ import App from './App.vue'
182
+
183
+ createApp(App)
184
+ .use(FormBuilderPlugin, {
185
+ config: { apiKey: '' },
186
+ })
187
+ .mount('#app')
124
188
  ```
125
189
 
126
190
  ```vue
@@ -131,6 +195,24 @@ createApp(App).use(FormBuilderPlugin, {
131
195
  </template>
132
196
  ```
133
197
 
198
+ ## Keyboard Shortcuts
199
+
200
+ Shortcuts apply while focus is inside the designer's canvas root (not while typing in a text field, code editor, or a modal). Deleting/duplicating/copying etc. act on the current selection.
201
+
202
+ | Action | Windows / Linux | macOS |
203
+ | ------------------------------------- | ----------------------------- | ---------------------------- |
204
+ | Delete selected element(s) | `Delete` / `Backspace` | `Delete` / `Backspace` |
205
+ | Undo | `Ctrl+Z` | `Cmd+Z` |
206
+ | Redo | `Ctrl+Shift+Z` or `Ctrl+Y` | `Cmd+Shift+Z` or `Cmd+Y` |
207
+ | Duplicate in place | `Ctrl+D` | `Cmd+D` |
208
+ | Copy | `Ctrl+C` | `Cmd+C` |
209
+ | Cut | `Ctrl+X` | `Cmd+X` |
210
+ | Paste | `Ctrl+V` | `Cmd+V` |
211
+ | Clear multi-selection | `Esc` | `Esc` |
212
+ | Toggle an element in/out of selection | `Shift`+click or `Ctrl`+click | `Shift`+click or `Cmd`+click |
213
+
214
+ The same actions are also available from the floating toolbar and the right-click context menu on the canvas (which additionally offer "wrap into container" and "convert to" another type), and from the header's undo/redo buttons.
215
+
134
216
  ## API
135
217
 
136
218
  ### Exports
@@ -142,8 +224,7 @@ import {
142
224
  BuilderProvider, // Global config provider
143
225
  BuilderPreview, // Reusable preview modal component
144
226
  FormDefinitionPreview, // Standalone split preview: form left, live data right
145
- FormRenderer, // Form rendering component (renamed from FormSchemaRenderer)
146
- FormSchemaRenderer, // @deprecated use FormRenderer
227
+ FormRenderer, // Form rendering component
147
228
  FormBuilderPlugin, // One-step plugin
148
229
  formkitConfig, // FormKit config factory (accepts custom elements)
149
230
  registerElement, // Config-based element extension
@@ -153,91 +234,117 @@ import {
153
234
  provideFormBuilderConfig,
154
235
  createFormBuilderState, // Multi-designer instance state
155
236
  useFormBuilderState,
237
+ useOptionalFormBuilderState, // Nullable variant for components used outside a FormBuilder/FormRenderer subtree
156
238
  provideFormBuilderState,
157
239
  dslToSchema, // DSL → FormKit schema
158
240
  dslToOutputSchema, // DSL → nested group output schema
159
241
  schemaToDsl, // Raw schema → DSL
242
+ toPortableDefinition, // Strip frontend-only fields before persisting (see "DSL & Conversion")
160
243
  buildFormkitInputs,
161
- } from "@zeng-alt/formkit-form-builder";
244
+ buildElementSchemaLibrary, // Element $cmp → component library (advanced: custom schemaLibrary)
245
+ getElementCmpName, // Element type → its $cmp render name
246
+ CanvasActionsBar, // Default #toolbar content (import/export, language switch); reusable in #toolbar
247
+ } from '@zeng-alt/formkit-form-builder'
162
248
  ```
163
249
 
250
+ `FormKitFormBuilder` and `FormBuilderProvider` are plain aliases of `FormBuilder` and
251
+ `BuilderProvider`, exported for naming preference only — both pairs are the same component.
252
+ `setExprLocale` / `resolveTimeZoneForLocale` / `LOCALE_TIME_ZONES` are also exported (see
253
+ "i18n Overrides" below).
254
+
255
+ > Only need to render forms, not design them? `@zeng-alt/formkit-form-builder/renderer` exports
256
+ > the subset of the above needed for that (`FormRenderer`, `formkitConfig`, `FormBuilderPlugin`,
257
+ > `registerElement`/`registerElements`, the DSL utilities, the config composables) without the
258
+ > designer or its CodeMirror / drag-and-drop dependencies — see "Renderer-Only Entry" above.
259
+
260
+ `useFormBuilderState()` only works inside a `FormBuilder` / `FormRenderer` subtree (including
261
+ one set up via `provideFormBuilderState()`); calling it outside one throws instead of silently
262
+ falling back to a shared global instance. Components meant to be used standalone should call
263
+ `useOptionalFormBuilderState()` instead, which returns `null` outside such a subtree. In
264
+ particular, `BuilderPreview` used standalone (outside a `FormBuilder`) needs a `schema` prop —
265
+ without it there is no form definition to render.
266
+
164
267
  ---
165
268
 
166
269
  ### FormBuilder API
167
270
 
168
271
  #### Props
169
272
 
170
- | Prop | Type | Default | Description |
171
- |------|------|---------|-------------|
172
- | `modelValue` | `FormDefinition` | - | Form definition: v-model bidirectional binding; preload existing form and emit edits in real time |
173
- | `config` | `FormBuilderConfig` | - | Instance config; if provided, self-contained (registerElements + provide); otherwise falls back to injected `BuilderProvider` |
174
- | `theme` | `BuilderTheme` (`'light' \| 'dark'`) | Auto (system) | Custom theme: maps to naive-ui's `darkTheme` / `lightTheme` |
175
- | `...ConfigProviderProps` | `Partial<ConfigProviderProps>` | - | Pass-through for remaining naive-ui ConfigProvider props (`themeOverrides`, `breakpoints`, etc.) |
273
+ | Prop | Type | Default | Description |
274
+ | ------------------------ | ------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
275
+ | `modelValue` | `FormDefinition` | - | Form definition: v-model bidirectional binding; preload existing form and emit edits in real time |
276
+ | `config` | `FormBuilderConfig` | - | Instance config; if provided, self-contained (registerElements + provide); otherwise falls back to injected `BuilderProvider` |
277
+ | `theme` | `BuilderTheme` (`'light' \| 'dark'`) | Auto (system) | Custom theme: maps to naive-ui's `darkTheme` / `lightTheme` |
278
+ | `...ConfigProviderProps` | `Partial<ConfigProviderProps>` | - | Pass-through for remaining naive-ui ConfigProvider props (`themeOverrides`, `breakpoints`, etc.) |
176
279
 
177
280
  #### Events
178
281
 
179
- | Event | Payload | Description |
180
- |-------|---------|-------------|
181
- | `update:modelValue` | `value: FormDefinition` | Emitted when form definition changes (v-model bidirectional binding) |
282
+ | Event | Payload | Description |
283
+ | ------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
284
+ | `update:modelValue` | `value: FormDefinition` | Emitted when form definition changes (v-model bidirectional binding). Treated as immutable — see note above; don't mutate it in place |
182
285
 
183
286
  #### Slots
184
287
 
185
- | Slot | Scope | Description |
186
- |------|-------|-------------|
187
- | `header` | - | Entire header bar (including default content) |
188
- | `header-left` | - | Header left area (clear / preview); uses default if not provided |
189
- | `header-center` | - | Header center area (AI prompt); uses default if not provided |
190
- | `header-right` | - | Header right area (undo/redo / theme); uses default if not provided |
191
- | `empty` | - | Canvas empty state; uses default NEmpty if not provided |
192
- | `toolbar` | - | Right sidebar actions (import/export / language switch); uses default if not provided |
288
+ | Slot | Scope | Description |
289
+ | --------------- | ----- | ------------------------------------------------------------------------------------- |
290
+ | `header` | - | Entire header bar (including default content) |
291
+ | `header-left` | - | Header left area (clear / preview); uses default if not provided |
292
+ | `header-center` | - | Header center area (AI prompt); uses default if not provided |
293
+ | `header-right` | - | Header right area (undo/redo / theme); uses default if not provided |
294
+ | `empty` | - | Canvas empty state; uses default NEmpty if not provided |
295
+ | `toolbar` | - | Right sidebar actions (import/export / language switch); uses default if not provided |
193
296
 
194
297
  ---
195
298
 
196
- ### FormRenderer API (formerly FormSchemaRenderer)
299
+ ### FormRenderer API
197
300
 
198
301
  #### Props
199
302
 
200
- | Prop | Type | Default | Description |
201
- |------|------|---------|-------------|
202
- | `definition` | `FormDefinition` | - | **Primary input**: Versioned DSL form definition; internally converted via `dslToSchema` |
203
- | `schema` | `FormKitSchemaFormKit[]` | - | **Alternative input**: Raw FormKit schema array; if both `definition` and `schema` provided, `definition` takes priority |
204
- | `dataStructure` | `'flat' \| 'nested'` | `'flat'` | Output structure when `definition` provided: `flat` (flat) \| `nested` (containers as group nesting) |
205
- | `modelValue` | `Record<string, unknown>` | `{}` | Form data v-model bidirectional binding |
206
- | `actions` | `boolean` | `false` | Render default action bar (submit/reset buttons); `false` hides it, use `#actions` slot for custom |
207
- | `submitLabel` | `string` | i18n: Submit | Default submit button label |
208
- | `resetLabel` | `string` | i18n: Reset | Default reset button label |
209
- | `submitAttrs` | `Record<string, unknown>` | - | Default submit button pass-through attrs (naive NButton props) |
210
- | `resetAttrs` | `Record<string, unknown>` | - | Default reset button pass-through attrs (naive NButton props) |
211
- | `actionsJustify` | `'start' \| 'center' \| 'end' \| 'space-between'` | `'start'` | Default action bar button alignment |
212
- | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
213
- | `formName` | `string` | - | Form name (priority: schema form.name > this prop) |
214
- | `labelPosition` | `'top' \| 'left'` | `'top'` | Label position (priority: schema form.props.labelPosition > this prop) |
215
- | `labelWidth` | `number` | `80` | Label width (priority: schema form.props.labelWidth > this prop) |
216
- | `schemaLibrary` | `Record<string, Component>` | Built-in preview lib | Custom schema component library (overrides built-in preview components) |
217
- | `interactiveContainers` | `boolean` | `true` | Enable interactions (add/remove rows) for list/card/input-group/button-group/tabs containers |
218
- | `theme` | `BuilderTheme` (`'light' \| 'dark'`) | Auto (system) | Custom theme: maps to naive-ui's `darkTheme` / `lightTheme` |
219
- | `...ConfigProviderProps` | `Partial<ConfigProviderProps>` | - | Pass-through for remaining naive-ui ConfigProvider props |
303
+ | Prop | Type | Default | Description |
304
+ | ------------------------ | ------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
305
+ | `definition` | `FormDefinition` | - | **Primary input**: Versioned DSL form definition; internally converted via `dslToSchema` |
306
+ | `schema` | `FormKitSchemaFormKit[]` | - | **Alternative input**: Raw FormKit schema array; if both `definition` and `schema` provided, `definition` takes priority |
307
+ | `dataStructure` | `'flat' \| 'nested'` | `'flat'` | Output structure when `definition` provided: `flat` (flat) \| `nested` (containers as group nesting) |
308
+ | `modelValue` | `Record<string, unknown>` | `{}` | Form data v-model bidirectional binding |
309
+ | `actions` | `boolean` | `false` | Render default action bar (submit/reset buttons); `false` hides it, use `#actions` slot for custom |
310
+ | `submitLabel` | `string` | i18n: Submit | Default submit button label |
311
+ | `resetLabel` | `string` | i18n: Reset | Default reset button label |
312
+ | `submitAttrs` | `Record<string, unknown>` | - | Default submit button pass-through attrs (naive NButton props) |
313
+ | `resetAttrs` | `Record<string, unknown>` | - | Default reset button pass-through attrs (naive NButton props) |
314
+ | `actionsJustify` | `'start' \| 'center' \| 'end' \| 'space-between'` | `'start'` | Default action bar button alignment |
315
+ | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
316
+ | `formName` | `string` | - | Form name (priority: schema form.name > this prop) |
317
+ | `labelPosition` | `'top' \| 'left'` | `'top'` | Label position (priority: schema form.props.labelPosition > this prop) |
318
+ | `labelWidth` | `number` | `80` | Label width (priority: schema form.props.labelWidth > this prop) |
319
+ | `schemaLibrary` | `Record<string, Component>` | Built-in preview lib | Custom schema component library (overrides built-in preview components) |
320
+ | `interactiveContainers` | `boolean` | `true` | Enable interactions (add/remove rows) for list/card/input-group/button-group/tabs containers |
321
+ | `config` | `FormBuilderConfig` | - | Self-contained instance config (registers elements + provides locale/i18n/http); if omitted, falls back to an injected `BuilderProvider` / `FormBuilder` |
322
+ | `theme` | `BuilderTheme` (`'light' \| 'dark'`) | Auto (system) | Custom theme: maps to naive-ui's `darkTheme` / `lightTheme` |
323
+ | `http` | `AxiosInstance` | Built-in `axios` | Custom HTTP client used by JS binding code (`axios` variable) and `settings.submit`; takes priority over `config.http` |
324
+ | `disabled` | `boolean` | `false` | Disable the whole form (all inputs + the default action bar); ORed with `definition.settings.disabled` |
325
+ | `...ConfigProviderProps` | `Partial<ConfigProviderProps>` | - | Pass-through for remaining naive-ui ConfigProvider props |
220
326
 
221
327
  #### Events
222
328
 
223
- | Event | Payload | Description |
224
- |-------|---------|-------------|
225
- | `update:modelValue` | `value: Record<string, unknown>` | Emitted when form data changes (v-model bidirectional binding) |
226
- | `submit` | `formData, id?, version?` | Emitted on form submit (not triggered if required validation fails) |
329
+ | Event | Payload | Description |
330
+ | ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
331
+ | `update:modelValue` | `value: Record<string, unknown>` | Emitted when form data changes (v-model bidirectional binding) |
332
+ | `submit` | `formData, id?, version?` | Emitted on form submit (not triggered if required validation fails, and not emitted when `definition.settings.submit` is set — that custom code runs instead) |
227
333
 
228
334
  #### Slots
229
335
 
230
- | Slot | Scope | Description |
231
- |------|-------|-------------|
232
- | `actions` | `{ submit: () => void, reset: () => void, loading: boolean }` | Custom action bar (overrides default submit/reset buttons) |
336
+ | Slot | Scope | Description |
337
+ | --------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- |
338
+ | `actions` | `{ submit: () => void, reset: () => void, loading: boolean, disabled: boolean }` | Custom action bar (overrides default submit/reset buttons) |
233
339
 
234
340
  #### Methods (via `defineExpose`)
235
341
 
236
- | Method | Type | Description |
237
- |--------|------|-------------|
238
- | `submit` | `() => void` | Submit form (does not trigger submit event if required validation fails) |
239
- | `reset` | `() => void` | Reset form to initial values |
240
- | `loading` | `Ref<boolean>` | Submit loading state |
342
+ | Method | Type | Description |
343
+ | ---------- | ------------------------ | -------------------------------------------------------------------------------------------------------- |
344
+ | `submit` | `() => void` | Submit form (does not trigger submit event if required validation fails) |
345
+ | `reset` | `() => void` | Reset form to initial values |
346
+ | `validate` | `() => Promise<boolean>` | Trigger validation and show error messages without submitting; resolves to whether all validation passed |
347
+ | `loading` | `Ref<boolean>` | Submit loading state |
241
348
 
242
349
  ---
243
350
 
@@ -245,45 +352,47 @@ import {
245
352
 
246
353
  Two ready-made preview components reuse `FormRenderer` internally to fill and test a form in a modal dialog (naive-ui `n-modal` + `n-scrollbar`). Both render the produced FormKit schema into a truly interactive, submittable form.
247
354
 
248
- | Component | Internal renderer | Layout |
249
- |-----------|-------------------|--------|
250
- | `BuilderPreview` | `FormSchemaRenderer` | Single form; optional data panel below |
251
- | `FormDefinitionPreview` | `FormSchemaRenderer` | Split view: form on the left, live form data on the right |
355
+ | Component | Internal renderer | Layout |
356
+ | ----------------------- | ----------------- | --------------------------------------------------------- |
357
+ | `BuilderPreview` | `FormRenderer` | Single form; optional data panel below |
358
+ | `FormDefinitionPreview` | `FormRenderer` | Split view: form on the left, live form data on the right |
252
359
 
253
- Both expose `open` / `close` methods via `defineExpose`, and emit `update:show` + `submit` (`formData, id?, version?`).
360
+ Both expose `open` / `close` / `validate` methods via `defineExpose` (`validate` triggers validation and returns whether it passed, same as `FormRenderer.validate`), and emit `update:show` + `submit` (`formData, id?, version?`).
254
361
 
255
362
  #### BuilderPreview Props
256
363
 
257
- | Prop | Type | Default | Description |
258
- |------|------|---------|-------------|
259
- | `show` | `boolean` | - | Modal visibility; a `v-model:show` two-way binding |
260
- | `schema` | `FormKitSchemaFormKit[]` | - | Raw schema to preview; if omitted, built from the current `FormDefinition` via `dslToSchema` |
261
- | `title` | `string` | i18n: 表单预览 | Modal title |
262
- | `description` | `string` | i18n: 预览表单并测试其功能 | Header subtitle |
263
- | `showDataPanel` | `boolean` | `true` | Show the live form-data panel below the form |
264
- | `initialData` | `Record<string, unknown>` | `{}` | Initial form data |
265
- | `view` | `CanvasView` | Canvas state | Desktop / tablet / mobile preview container width |
266
- | `actions` | `boolean` | `false` | Render default action bar (submit/reset) |
267
- | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
268
- | `interactiveContainers` | `boolean` | `true` | Enable list/card/group/tabs interactive add/remove rows |
269
- | `resetOnSubmit` | `boolean` | `true` | Reset form data after submit |
364
+ | Prop | Type | Default | Description |
365
+ | ----------------------- | ------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
366
+ | `show` | `boolean` | - | Modal visibility; a `v-model:show` two-way binding |
367
+ | `schema` | `FormKitSchemaFormKit[]` | - | Raw schema to preview; if omitted, built from the current `FormDefinition` via `dslToSchema` |
368
+ | `title` | `string` | i18n: 表单预览 | Modal title |
369
+ | `description` | `string` | i18n: 预览表单并测试其功能 | Header subtitle |
370
+ | `showDataPanel` | `boolean` | `true` | Show the live form-data panel below the form |
371
+ | `initialData` | `Record<string, unknown>` | `{}` | Initial form data |
372
+ | `view` | `CanvasView` | Canvas state | Desktop / tablet / mobile preview container width |
373
+ | `actions` | `boolean` | `false` | Render default action bar (submit/reset) |
374
+ | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
375
+ | `interactiveContainers` | `boolean` | `true` | Enable list/card/group/tabs interactive add/remove rows |
376
+ | `resetOnSubmit` | `boolean` | `true` | Reset form data after submit |
377
+ | `disabled` | `boolean` | `false` | Disable the whole previewed form |
270
378
 
271
379
  #### FormDefinitionPreview Props
272
380
 
273
- | Prop | Type | Default | Description |
274
- |------|------|---------|-------------|
275
- | `show` | `boolean` | - | Modal visibility; a `v-model` two-way binding |
276
- | `formDefinition` | `FormDefinition` | required | Versioned DSL form definition (result of the designer export), converted via `dslToSchema` internally |
277
- | `title` | `string` | `''` | Modal title |
278
- | `initialData` | `Record<string, unknown>` | `{}` | Initial form data |
279
- | `actions` | `boolean` | `false` | Render the default action bar (submit/reset) |
280
- | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
281
- | `interactiveContainers` | `boolean` | `true` | Enable interactive containers |
282
- | `showDataPanel` | `boolean` | `true` | Show the right-side live data panel |
283
- | `dataPanelWidth` | `string` | `'320px'` | Right data panel width |
284
- | `resetOnSubmit` | `boolean` | `true` | Reset form data after submit |
285
-
286
- `FormDefinitionPreview` additionally exposes a `reset` method. Both read the running locale / theme from the enclosing `BuilderProvider` / `FormBuilder`.
381
+ | Prop | Type | Default | Description |
382
+ | ----------------------- | ------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
383
+ | `show` | `boolean` | - | Modal visibility; a `v-model` two-way binding |
384
+ | `formDefinition` | `FormDefinition` | required | Versioned DSL form definition (result of the designer export), converted via `dslToSchema` internally |
385
+ | `title` | `string` | `''` | Modal title |
386
+ | `initialData` | `Record<string, unknown>` | `{}` | Initial form data |
387
+ | `actions` | `boolean` | `false` | Render the default action bar (submit/reset) |
388
+ | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
389
+ | `interactiveContainers` | `boolean` | `true` | Enable interactive containers |
390
+ | `showDataPanel` | `boolean` | `true` | Show the right-side live data panel |
391
+ | `dataPanelWidth` | `string` | `'320px'` | Right data panel width |
392
+ | `resetOnSubmit` | `boolean` | `true` | Reset form data after submit |
393
+ | `disabled` | `boolean` | `false` | Disable the whole previewed form |
394
+
395
+ `FormDefinitionPreview` additionally exposes a `reset` method (clears the local form data, distinct from `FormRenderer`'s `reset` which restores initial values). Both read the running locale / theme from the enclosing `BuilderProvider` / `FormBuilder`.
287
396
 
288
397
  ---
289
398
 
@@ -291,42 +400,76 @@ Both expose `open` / `close` methods via `defineExpose`, and emit `update:show`
291
400
 
292
401
  ```ts
293
402
  export interface FormBuilderConfig {
294
- apiKey?: string; // Required for AI panel with OpenAI
295
- locale?: string; // Default: zh-CN
296
- messages?: Record<string, any>; // i18n overrides (same structure as default messages)
297
- elements?: RegisterElementInput[]; // Extended elements (config-based registration)
403
+ apiKey?: string // AI service API key (recommended: only via a server-side proxy, never expose a real key to the browser)
404
+ aiBaseUrl?: string // OpenAI-compatible endpoint; default https://api.deepseek.com (point at your own proxy)
405
+ aiModel?: string // AI model name; default deepseek-chat (e.g. gpt-4o-mini for OpenAI)
406
+ aiSystemPrompt?: string // Custom AI system prompt; defaults to the built-in Instructions.txt
407
+ http?: AxiosInstance // Custom HTTP client for JS binding code's `axios` variable (canvas preview + renderer); defaults to a built-in axios instance. FormRenderer's `http` prop takes priority
408
+ locale?: string
409
+ localeFallback?: string // Fallback locale when `locale` isn't in `availableLocales`; default zh-CN
410
+ messages?: Record<string, any> // i18n overrides (same structure as default messages)
411
+ availableLocales?: string[] // Available locales; default ['zh-CN', 'en']
412
+ elements?: RegisterElementInput[] // Extended elements (config-based registration)
413
+ fetchDictionary?: (code: string) => Promise<DictionaryOption[]> // Look up a dictionary's options [{label,value}] by code (used when rendering dynamic-dictionary fields)
414
+ fetchDictionaryPage?: (params: DictionaryPageQuery) => Promise<DictionaryPageResult> // Paged dictionary search, used by the edit panel's dictionary picker
415
+ fetchTreeDictionary?: (code: string) => Promise<TreeDictionaryOption[]> // Look up a tree-shaped dictionary's options by code (tree-select / cascader)
416
+ fetchTreeDictionaryPage?: (params: TreeDictionaryPageQuery) => Promise<TreeDictionaryPageResult> // Paged tree-dictionary search, used by the edit panel's picker
298
417
  }
299
418
  ```
300
419
 
420
+ `locale` defaults to `zh-CN` when unset. The nested types (`DictionaryOption`,
421
+ `DictionaryPageQuery`, `DictionaryPageResult`, `TreeDictionaryOption`, `TreeDictionaryPageQuery`,
422
+ `TreeDictionaryPageResult`, defined in `src/types/env.ts`) are not currently re-exported from the
423
+ package entry point — TypeScript consumers can still get their shape through `FormBuilderConfig`'s
424
+ own field types, just not as standalone named imports. The `fetchDictionary*` /
425
+ `fetchTreeDictionary*` callbacks are only used by select / radio / checkbox / cascader /
426
+ tree-select fields whose `options` is a dynamic-dictionary reference (`{ dynamic: true, code }`)
427
+ rather than a static option list.
428
+
301
429
  ### DSL & Conversion
302
430
 
303
- 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.
431
+ DSL node types: `FormDefinition` / `FormNode` (`FieldNode` / `ContainerNode` / `StaticNode` / `LayoutNode`), `NodeCategory` (`field | container | layout | static`), `RenderKind` (`formkit | cmp | el`). The DSL body is JSON-safe and meant to be persisted and deserialized directly by a backend (e.g. Java).
304
432
 
305
433
  ```ts
306
- import { dslToSchema, schemaToDsl, dslToOutputSchema } from "@zeng-alt/formkit-form-builder";
307
- import type { FormDefinition } from "@zeng-alt/formkit-form-builder";
308
-
309
- const schema = dslToSchema(definition); // For rendering
310
- const outputSchema = dslToOutputSchema(definition); // Containers as group nesting (backend-model friendly)
311
- const backToDsl = schemaToDsl(schema);
434
+ import {
435
+ dslToSchema,
436
+ schemaToDsl,
437
+ dslToOutputSchema,
438
+ toPortableDefinition,
439
+ } from '@zeng-alt/formkit-form-builder'
440
+ import type { FormDefinition } from '@zeng-alt/formkit-form-builder'
441
+
442
+ const schema = dslToSchema(definition) // DSL → FormKit schema, for rendering
443
+ const outputSchema = dslToOutputSchema(definition) // Same, but containers/layouts nest as groups (see below)
444
+ const backToDsl = schemaToDsl(schema) // FormKit schema → DSL (best-effort import)
445
+
446
+ // Before persisting to the backend, strip frontend-only fields (BaseNode.key, meta.rawSchema):
447
+ const portable = toPortableDefinition(definition)
448
+ await saveFormDefinition(portable)
312
449
  ```
313
450
 
451
+ For the full DSL reference aimed at backend integration — every field of `FormDefinition` /
452
+ `FormSettings` / node types, the expression AST and its built-in functions, validation rule
453
+ structure, event bindings, each container's data shape (and how `flat` vs `nested`
454
+ `dataStructure` changes the submitted JSON), what `toPortableDefinition` strips, and a complete
455
+ worked example — see **[docs/dsl.en.md](./docs/dsl.en.md)** (Chinese: [docs/dsl.md](./docs/dsl.md)).
456
+
314
457
  ### Extending Elements
315
458
 
316
459
  Register custom elements via `config.elements` or `registerElement(s)` (DSL registry + FormKit input + canvas/preview all at once):
317
460
 
318
461
  ```ts
319
- import { registerElement, formkitConfig } from "@zeng-alt/formkit-form-builder";
320
- import type { RegisterElementInput } from "@zeng-alt/formkit-form-builder";
462
+ import { registerElement, formkitConfig } from '@zeng-alt/formkit-form-builder'
463
+ import type { RegisterElementInput } from '@zeng-alt/formkit-form-builder'
321
464
 
322
465
  registerElement({
323
- type: "myField",
324
- category: "field",
325
- label: "Custom Field",
466
+ type: 'myField',
467
+ category: 'field',
468
+ label: 'Custom Field',
326
469
  // ... see RegisterElementInput type
327
- });
470
+ })
328
471
 
329
- createApp(App).use(plugin, formkitConfig());
472
+ createApp(App).use(plugin, formkitConfig())
330
473
  ```
331
474
 
332
475
  ## i18n Overrides
@@ -335,17 +478,60 @@ createApp(App).use(plugin, formkitConfig());
335
478
 
336
479
  ```ts
337
480
  const config = {
338
- locale: "zh-CN",
481
+ locale: 'zh-CN',
339
482
  messages: {
340
- "zh-CN": {
483
+ 'zh-CN': {
341
484
  builder: {
342
- clearForm: "Clear current form", // Only overrides this key; other builder.* preserved
485
+ clearForm: 'Clear current form', // Only overrides this key; other builder.* preserved
343
486
  },
344
487
  },
345
488
  },
346
- };
489
+ }
347
490
  ```
348
491
 
492
+ The DSL expression function `today()` resolves its time zone from the currently active
493
+ runtime language (`zh-CN` → `Asia/Shanghai`, `ja` → `Asia/Tokyo`, etc.; `en` has no fixed
494
+ mapping and falls back to the browser's local time zone) instead of a fixed UTC offset,
495
+ avoiding an off-by-one-day result in the evening for users east of UTC. It syncs
496
+ automatically on language switch; hosts can also extend the mapping via
497
+ `LOCALE_TIME_ZONES`, or set the evaluation language manually with `setExprLocale` (useful
498
+ when using the DSL conversion utilities standalone, outside `FormBuilder` / `FormRenderer`).
499
+
500
+ ```ts
501
+ import { setExprLocale, LOCALE_TIME_ZONES } from '@zeng-alt/formkit-form-builder'
502
+
503
+ LOCALE_TIME_ZONES['fr'] = 'Europe/Paris' // extend the mapping
504
+ setExprLocale('zh-CN') // manual override (synced automatically inside FormBuilder/FormRenderer)
505
+ ```
506
+
507
+ ## Security
508
+
509
+ A `FormDefinition` can carry opaque JS strings in a few places: field/static-node
510
+ `events` (event bindings, e.g. `onClick`), `settings.submit` (custom submit logic),
511
+ and a data-table's `getData` / `createData` / `updateData` / `deleteData` (remote
512
+ data hooks). `FormRenderer` executes these client-side with `new Function`, and the
513
+ executed code can reach the injected `axios` instance — which by default carries
514
+ the page's same-origin credentials (cookies).
515
+
516
+ What this means: **whoever can edit a form definition can run arbitrary JS in the
517
+ browser of every user who fills that form.** This is a standard trade-off for a
518
+ low-code/no-code platform, not a bug — but if the people who design forms and the
519
+ people who fill them out sit in different trust zones (e.g. an internal ops team
520
+ authors forms that end customers fill in), an unreviewed `FormDefinition` is
521
+ equivalent to stored XSS.
522
+
523
+ Recommendations:
524
+
525
+ - When persisting a `FormDefinition` on the backend, apply an allow-list or a
526
+ signature check to `props.__bind` (event handlers), `settings.submit`, and the
527
+ data-table `getData`/`createData`/`updateData`/`deleteData` fields before
528
+ trusting them again.
529
+ - Only expose the designer (`FormBuilder`) to roles you trust to write JS; treat a
530
+ submitted `FormDefinition` from a lower-trust role as untrusted input.
531
+ - `config.apiKey` is sent straight from the browser to the AI endpoint. Never ship
532
+ a real key to production; point `config.aiBaseUrl` at your own server-side proxy
533
+ instead and keep the key there.
534
+
349
535
  ## Examples
350
536
 
351
537
  ![light](./img/light.png)
@@ -390,4 +576,4 @@ pnpm version patch # 1.0.0 → 1.0.1
390
576
  pnpm version minor # 1.0.0 → 1.1.0
391
577
  pnpm version major # 1.0.0 → 2.0.0
392
578
  pnpm publish
393
- ```
579
+ ```