@zeng-alt/formkit-form-builder 1.4.0 → 2.0.1

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 +45 -0
  2. package/README.md +325 -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,58 @@ 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**:
38
+
39
+ ```bash
40
+ pnpm i vue naive-ui @vueuse/core @formkit/core @formkit/vue @formkit/i18n
41
+ ```
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):
16
44
 
17
45
  ```bash
18
- pnpm i vue naive-ui @vueuse/core
46
+ pnpm i @codemirror/autocomplete @codemirror/commands @codemirror/lang-javascript @codemirror/language @codemirror/lint @codemirror/state @codemirror/theme-one-dark @codemirror/view
19
47
  ```
20
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'
27
57
  ```
28
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'
72
+ ```
73
+
74
+ The stylesheet uses CSS `@scope` to isolate the builder from the host page; use a browser that supports `@scope`.
75
+
76
+ 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.
77
+
78
+ Measured bundle size (`pnpm build-only` output, gzip):
79
+
80
+ | Artifact | First-screen static dependency total (gzip) |
81
+ | --- | --- |
82
+ | Full entry `.` (designer + renderer) | 167.2KB |
83
+ | Renderer entry `./renderer` | **70.3KB** |
84
+
85
+ For form-filling-only pages, switching to `/renderer` saves roughly 97KB (gzip) of designer-only code.
86
+
87
+ 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.
88
+
29
89
  ## Quick Start
30
90
 
31
91
  ### 1) Install and Register FormKit
@@ -34,12 +94,12 @@ Use the built-in `formkitConfig()` factory (auto-registers all built-in elements
34
94
 
35
95
  ```ts
36
96
  // 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";
97
+ import { createApp } from 'vue'
98
+ import { plugin as formkitPlugin } from '@formkit/vue'
99
+ import { formkitConfig } from '@zeng-alt/formkit-form-builder'
100
+ import App from './App.vue'
41
101
 
42
- createApp(App).use(formkitPlugin, formkitConfig()).mount("#app");
102
+ createApp(App).use(formkitPlugin, formkitConfig()).mount('#app')
43
103
  ```
44
104
 
45
105
  > Alternatively, use the one-step plugin `FormBuilderPlugin` (auto-configures FormKit + global config + element registration), see below.
@@ -48,14 +108,16 @@ createApp(App).use(formkitPlugin, formkitConfig()).mount("#app");
48
108
 
49
109
  ```vue
50
110
  <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";
111
+ import { ref } from 'vue'
112
+ import { FormBuilder, BuilderProvider } from '@zeng-alt/formkit-form-builder'
113
+ import type { FormDefinition } from '@zeng-alt/formkit-form-builder'
54
114
 
55
- const definition = ref<FormDefinition>();
115
+ const definition = ref<FormDefinition>()
56
116
  const config = {
57
- apiKey: "", // Optional: required for AI panel with OpenAI
58
- };
117
+ apiKey: '', // Optional: required for AI panel with OpenAI. Never ship a real key to
118
+ // the browser in production — point `aiBaseUrl` at your own server-side proxy instead.
119
+ // See "Security" below.
120
+ }
59
121
  </script>
60
122
 
61
123
  <template>
@@ -67,18 +129,20 @@ const config = {
67
129
 
68
130
  `FormBuilder` binds `FormDefinition` via `v-model` bidirectionally: preload existing forms and emit edits in real time, ready to save to backend.
69
131
 
132
+ > 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.
133
+
70
134
  ### 3) Render Forms
71
135
 
72
- `FormRenderer` (renamed from `FormSchemaRenderer`) renders `FormDefinition` into a fillable, submittable FormKit form:
136
+ `FormRenderer` renders `FormDefinition` into a fillable, submittable FormKit form:
73
137
 
74
138
  ```vue
75
139
  <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";
140
+ import { ref } from 'vue'
141
+ import { FormRenderer } from '@zeng-alt/formkit-form-builder'
142
+ import type { FormDefinition } from '@zeng-alt/formkit-form-builder'
79
143
 
80
- const definition = ref<FormDefinition>();
81
- const data = ref({});
144
+ const definition = ref<FormDefinition>()
145
+ const data = ref({})
82
146
  </script>
83
147
 
84
148
  <template>
@@ -92,7 +156,7 @@ const data = ref({});
92
156
  ```
93
157
 
94
158
  - `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).
159
+ - `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
160
  - Other optional props: `formName`, `labelPosition` (`'top' | 'left'`), `labelWidth`, `formClass`, `interactiveContainers`, etc.
97
161
  - **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
162
  - **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 +178,15 @@ Don't want to manually `app.use(plugin, formkitConfig())` + wrap `BuilderProvide
114
178
 
115
179
  ```ts
116
180
  // 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");
181
+ import { createApp } from 'vue'
182
+ import { FormBuilderPlugin } from '@zeng-alt/formkit-form-builder'
183
+ import App from './App.vue'
184
+
185
+ createApp(App)
186
+ .use(FormBuilderPlugin, {
187
+ config: { apiKey: '' },
188
+ })
189
+ .mount('#app')
124
190
  ```
125
191
 
126
192
  ```vue
@@ -131,6 +197,24 @@ createApp(App).use(FormBuilderPlugin, {
131
197
  </template>
132
198
  ```
133
199
 
200
+ ## Keyboard Shortcuts
201
+
202
+ 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.
203
+
204
+ | Action | Windows / Linux | macOS |
205
+ | ------------------------------------- | ----------------------------- | ---------------------------- |
206
+ | Delete selected element(s) | `Delete` / `Backspace` | `Delete` / `Backspace` |
207
+ | Undo | `Ctrl+Z` | `Cmd+Z` |
208
+ | Redo | `Ctrl+Shift+Z` or `Ctrl+Y` | `Cmd+Shift+Z` or `Cmd+Y` |
209
+ | Duplicate in place | `Ctrl+D` | `Cmd+D` |
210
+ | Copy | `Ctrl+C` | `Cmd+C` |
211
+ | Cut | `Ctrl+X` | `Cmd+X` |
212
+ | Paste | `Ctrl+V` | `Cmd+V` |
213
+ | Clear multi-selection | `Esc` | `Esc` |
214
+ | Toggle an element in/out of selection | `Shift`+click or `Ctrl`+click | `Shift`+click or `Cmd`+click |
215
+
216
+ 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.
217
+
134
218
  ## API
135
219
 
136
220
  ### Exports
@@ -142,8 +226,7 @@ import {
142
226
  BuilderProvider, // Global config provider
143
227
  BuilderPreview, // Reusable preview modal component
144
228
  FormDefinitionPreview, // Standalone split preview: form left, live data right
145
- FormRenderer, // Form rendering component (renamed from FormSchemaRenderer)
146
- FormSchemaRenderer, // @deprecated use FormRenderer
229
+ FormRenderer, // Form rendering component
147
230
  FormBuilderPlugin, // One-step plugin
148
231
  formkitConfig, // FormKit config factory (accepts custom elements)
149
232
  registerElement, // Config-based element extension
@@ -153,91 +236,117 @@ import {
153
236
  provideFormBuilderConfig,
154
237
  createFormBuilderState, // Multi-designer instance state
155
238
  useFormBuilderState,
239
+ useOptionalFormBuilderState, // Nullable variant for components used outside a FormBuilder/FormRenderer subtree
156
240
  provideFormBuilderState,
157
241
  dslToSchema, // DSL → FormKit schema
158
242
  dslToOutputSchema, // DSL → nested group output schema
159
243
  schemaToDsl, // Raw schema → DSL
244
+ toPortableDefinition, // Strip frontend-only fields before persisting (see "DSL & Conversion")
160
245
  buildFormkitInputs,
161
- } from "@zeng-alt/formkit-form-builder";
246
+ buildElementSchemaLibrary, // Element $cmp → component library (advanced: custom schemaLibrary)
247
+ getElementCmpName, // Element type → its $cmp render name
248
+ CanvasActionsBar, // Default #toolbar content (import/export, language switch); reusable in #toolbar
249
+ } from '@zeng-alt/formkit-form-builder'
162
250
  ```
163
251
 
252
+ `FormKitFormBuilder` and `FormBuilderProvider` are plain aliases of `FormBuilder` and
253
+ `BuilderProvider`, exported for naming preference only — both pairs are the same component.
254
+ `setExprLocale` / `resolveTimeZoneForLocale` / `LOCALE_TIME_ZONES` are also exported (see
255
+ "i18n Overrides" below).
256
+
257
+ > Only need to render forms, not design them? `@zeng-alt/formkit-form-builder/renderer` exports
258
+ > the subset of the above needed for that (`FormRenderer`, `formkitConfig`, `FormBuilderPlugin`,
259
+ > `registerElement`/`registerElements`, the DSL utilities, the config composables) without the
260
+ > designer or its CodeMirror / drag-and-drop dependencies — see "Renderer-Only Entry" above.
261
+
262
+ `useFormBuilderState()` only works inside a `FormBuilder` / `FormRenderer` subtree (including
263
+ one set up via `provideFormBuilderState()`); calling it outside one throws instead of silently
264
+ falling back to a shared global instance. Components meant to be used standalone should call
265
+ `useOptionalFormBuilderState()` instead, which returns `null` outside such a subtree. In
266
+ particular, `BuilderPreview` used standalone (outside a `FormBuilder`) needs a `schema` prop —
267
+ without it there is no form definition to render.
268
+
164
269
  ---
165
270
 
166
271
  ### FormBuilder API
167
272
 
168
273
  #### Props
169
274
 
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.) |
275
+ | Prop | Type | Default | Description |
276
+ | ------------------------ | ------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
277
+ | `modelValue` | `FormDefinition` | - | Form definition: v-model bidirectional binding; preload existing form and emit edits in real time |
278
+ | `config` | `FormBuilderConfig` | - | Instance config; if provided, self-contained (registerElements + provide); otherwise falls back to injected `BuilderProvider` |
279
+ | `theme` | `BuilderTheme` (`'light' \| 'dark'`) | Auto (system) | Custom theme: maps to naive-ui's `darkTheme` / `lightTheme` |
280
+ | `...ConfigProviderProps` | `Partial<ConfigProviderProps>` | - | Pass-through for remaining naive-ui ConfigProvider props (`themeOverrides`, `breakpoints`, etc.) |
176
281
 
177
282
  #### Events
178
283
 
179
- | Event | Payload | Description |
180
- |-------|---------|-------------|
181
- | `update:modelValue` | `value: FormDefinition` | Emitted when form definition changes (v-model bidirectional binding) |
284
+ | Event | Payload | Description |
285
+ | ------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
286
+ | `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
287
 
183
288
  #### Slots
184
289
 
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 |
290
+ | Slot | Scope | Description |
291
+ | --------------- | ----- | ------------------------------------------------------------------------------------- |
292
+ | `header` | - | Entire header bar (including default content) |
293
+ | `header-left` | - | Header left area (clear / preview); uses default if not provided |
294
+ | `header-center` | - | Header center area (AI prompt); uses default if not provided |
295
+ | `header-right` | - | Header right area (undo/redo / theme); uses default if not provided |
296
+ | `empty` | - | Canvas empty state; uses default NEmpty if not provided |
297
+ | `toolbar` | - | Right sidebar actions (import/export / language switch); uses default if not provided |
193
298
 
194
299
  ---
195
300
 
196
- ### FormRenderer API (formerly FormSchemaRenderer)
301
+ ### FormRenderer API
197
302
 
198
303
  #### Props
199
304
 
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 |
305
+ | Prop | Type | Default | Description |
306
+ | ------------------------ | ------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
307
+ | `definition` | `FormDefinition` | - | **Primary input**: Versioned DSL form definition; internally converted via `dslToSchema` |
308
+ | `schema` | `FormKitSchemaFormKit[]` | - | **Alternative input**: Raw FormKit schema array; if both `definition` and `schema` provided, `definition` takes priority |
309
+ | `dataStructure` | `'flat' \| 'nested'` | `'flat'` | Output structure when `definition` provided: `flat` (flat) \| `nested` (containers as group nesting) |
310
+ | `modelValue` | `Record<string, unknown>` | `{}` | Form data v-model bidirectional binding |
311
+ | `actions` | `boolean` | `false` | Render default action bar (submit/reset buttons); `false` hides it, use `#actions` slot for custom |
312
+ | `submitLabel` | `string` | i18n: Submit | Default submit button label |
313
+ | `resetLabel` | `string` | i18n: Reset | Default reset button label |
314
+ | `submitAttrs` | `Record<string, unknown>` | - | Default submit button pass-through attrs (naive NButton props) |
315
+ | `resetAttrs` | `Record<string, unknown>` | - | Default reset button pass-through attrs (naive NButton props) |
316
+ | `actionsJustify` | `'start' \| 'center' \| 'end' \| 'space-between'` | `'start'` | Default action bar button alignment |
317
+ | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
318
+ | `formName` | `string` | - | Form name (priority: schema form.name > this prop) |
319
+ | `labelPosition` | `'top' \| 'left'` | `'top'` | Label position (priority: schema form.props.labelPosition > this prop) |
320
+ | `labelWidth` | `number` | `80` | Label width (priority: schema form.props.labelWidth > this prop) |
321
+ | `schemaLibrary` | `Record<string, Component>` | Built-in preview lib | Custom schema component library (overrides built-in preview components) |
322
+ | `interactiveContainers` | `boolean` | `true` | Enable interactions (add/remove rows) for list/card/input-group/button-group/tabs containers |
323
+ | `config` | `FormBuilderConfig` | - | Self-contained instance config (registers elements + provides locale/i18n/http); if omitted, falls back to an injected `BuilderProvider` / `FormBuilder` |
324
+ | `theme` | `BuilderTheme` (`'light' \| 'dark'`) | Auto (system) | Custom theme: maps to naive-ui's `darkTheme` / `lightTheme` |
325
+ | `http` | `AxiosInstance` | Built-in `axios` | Custom HTTP client used by JS binding code (`axios` variable) and `settings.submit`; takes priority over `config.http` |
326
+ | `disabled` | `boolean` | `false` | Disable the whole form (all inputs + the default action bar); ORed with `definition.settings.disabled` |
327
+ | `...ConfigProviderProps` | `Partial<ConfigProviderProps>` | - | Pass-through for remaining naive-ui ConfigProvider props |
220
328
 
221
329
  #### Events
222
330
 
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) |
331
+ | Event | Payload | Description |
332
+ | ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
333
+ | `update:modelValue` | `value: Record<string, unknown>` | Emitted when form data changes (v-model bidirectional binding) |
334
+ | `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
335
 
228
336
  #### Slots
229
337
 
230
- | Slot | Scope | Description |
231
- |------|-------|-------------|
232
- | `actions` | `{ submit: () => void, reset: () => void, loading: boolean }` | Custom action bar (overrides default submit/reset buttons) |
338
+ | Slot | Scope | Description |
339
+ | --------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- |
340
+ | `actions` | `{ submit: () => void, reset: () => void, loading: boolean, disabled: boolean }` | Custom action bar (overrides default submit/reset buttons) |
233
341
 
234
342
  #### Methods (via `defineExpose`)
235
343
 
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 |
344
+ | Method | Type | Description |
345
+ | ---------- | ------------------------ | -------------------------------------------------------------------------------------------------------- |
346
+ | `submit` | `() => void` | Submit form (does not trigger submit event if required validation fails) |
347
+ | `reset` | `() => void` | Reset form to initial values |
348
+ | `validate` | `() => Promise<boolean>` | Trigger validation and show error messages without submitting; resolves to whether all validation passed |
349
+ | `loading` | `Ref<boolean>` | Submit loading state |
241
350
 
242
351
  ---
243
352
 
@@ -245,45 +354,47 @@ import {
245
354
 
246
355
  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
356
 
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 |
357
+ | Component | Internal renderer | Layout |
358
+ | ----------------------- | ----------------- | --------------------------------------------------------- |
359
+ | `BuilderPreview` | `FormRenderer` | Single form; optional data panel below |
360
+ | `FormDefinitionPreview` | `FormRenderer` | Split view: form on the left, live form data on the right |
252
361
 
253
- Both expose `open` / `close` methods via `defineExpose`, and emit `update:show` + `submit` (`formData, id?, version?`).
362
+ 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
363
 
255
364
  #### BuilderPreview Props
256
365
 
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 |
366
+ | Prop | Type | Default | Description |
367
+ | ----------------------- | ------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
368
+ | `show` | `boolean` | - | Modal visibility; a `v-model:show` two-way binding |
369
+ | `schema` | `FormKitSchemaFormKit[]` | - | Raw schema to preview; if omitted, built from the current `FormDefinition` via `dslToSchema` |
370
+ | `title` | `string` | i18n: 表单预览 | Modal title |
371
+ | `description` | `string` | i18n: 预览表单并测试其功能 | Header subtitle |
372
+ | `showDataPanel` | `boolean` | `true` | Show the live form-data panel below the form |
373
+ | `initialData` | `Record<string, unknown>` | `{}` | Initial form data |
374
+ | `view` | `CanvasView` | Canvas state | Desktop / tablet / mobile preview container width |
375
+ | `actions` | `boolean` | `false` | Render default action bar (submit/reset) |
376
+ | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
377
+ | `interactiveContainers` | `boolean` | `true` | Enable list/card/group/tabs interactive add/remove rows |
378
+ | `resetOnSubmit` | `boolean` | `true` | Reset form data after submit |
379
+ | `disabled` | `boolean` | `false` | Disable the whole previewed form |
270
380
 
271
381
  #### FormDefinitionPreview Props
272
382
 
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`.
383
+ | Prop | Type | Default | Description |
384
+ | ----------------------- | ------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
385
+ | `show` | `boolean` | - | Modal visibility; a `v-model` two-way binding |
386
+ | `formDefinition` | `FormDefinition` | required | Versioned DSL form definition (result of the designer export), converted via `dslToSchema` internally |
387
+ | `title` | `string` | `''` | Modal title |
388
+ | `initialData` | `Record<string, unknown>` | `{}` | Initial form data |
389
+ | `actions` | `boolean` | `false` | Render the default action bar (submit/reset) |
390
+ | `formClass` | `string` | `'w-full !grid !grid-cols-12 gap-x-4 gap-y-2'` | Form root element class |
391
+ | `interactiveContainers` | `boolean` | `true` | Enable interactive containers |
392
+ | `showDataPanel` | `boolean` | `true` | Show the right-side live data panel |
393
+ | `dataPanelWidth` | `string` | `'320px'` | Right data panel width |
394
+ | `resetOnSubmit` | `boolean` | `true` | Reset form data after submit |
395
+ | `disabled` | `boolean` | `false` | Disable the whole previewed form |
396
+
397
+ `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
398
 
288
399
  ---
289
400
 
@@ -291,42 +402,76 @@ Both expose `open` / `close` methods via `defineExpose`, and emit `update:show`
291
402
 
292
403
  ```ts
293
404
  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)
405
+ apiKey?: string // AI service API key (recommended: only via a server-side proxy, never expose a real key to the browser)
406
+ aiBaseUrl?: string // OpenAI-compatible endpoint; default https://api.deepseek.com (point at your own proxy)
407
+ aiModel?: string // AI model name; default deepseek-chat (e.g. gpt-4o-mini for OpenAI)
408
+ aiSystemPrompt?: string // Custom AI system prompt; defaults to the built-in Instructions.txt
409
+ 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
410
+ locale?: string
411
+ localeFallback?: string // Fallback locale when `locale` isn't in `availableLocales`; default zh-CN
412
+ messages?: Record<string, any> // i18n overrides (same structure as default messages)
413
+ availableLocales?: string[] // Available locales; default ['zh-CN', 'en']
414
+ elements?: RegisterElementInput[] // Extended elements (config-based registration)
415
+ fetchDictionary?: (code: string) => Promise<DictionaryOption[]> // Look up a dictionary's options [{label,value}] by code (used when rendering dynamic-dictionary fields)
416
+ fetchDictionaryPage?: (params: DictionaryPageQuery) => Promise<DictionaryPageResult> // Paged dictionary search, used by the edit panel's dictionary picker
417
+ fetchTreeDictionary?: (code: string) => Promise<TreeDictionaryOption[]> // Look up a tree-shaped dictionary's options by code (tree-select / cascader)
418
+ fetchTreeDictionaryPage?: (params: TreeDictionaryPageQuery) => Promise<TreeDictionaryPageResult> // Paged tree-dictionary search, used by the edit panel's picker
298
419
  }
299
420
  ```
300
421
 
422
+ `locale` defaults to `zh-CN` when unset. The nested types (`DictionaryOption`,
423
+ `DictionaryPageQuery`, `DictionaryPageResult`, `TreeDictionaryOption`, `TreeDictionaryPageQuery`,
424
+ `TreeDictionaryPageResult`, defined in `src/types/env.ts`) are not currently re-exported from the
425
+ package entry point — TypeScript consumers can still get their shape through `FormBuilderConfig`'s
426
+ own field types, just not as standalone named imports. The `fetchDictionary*` /
427
+ `fetchTreeDictionary*` callbacks are only used by select / radio / checkbox / cascader /
428
+ tree-select fields whose `options` is a dynamic-dictionary reference (`{ dynamic: true, code }`)
429
+ rather than a static option list.
430
+
301
431
  ### DSL & Conversion
302
432
 
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.
433
+ 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
434
 
305
435
  ```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);
436
+ import {
437
+ dslToSchema,
438
+ schemaToDsl,
439
+ dslToOutputSchema,
440
+ toPortableDefinition,
441
+ } from '@zeng-alt/formkit-form-builder'
442
+ import type { FormDefinition } from '@zeng-alt/formkit-form-builder'
443
+
444
+ const schema = dslToSchema(definition) // DSL → FormKit schema, for rendering
445
+ const outputSchema = dslToOutputSchema(definition) // Same, but containers/layouts nest as groups (see below)
446
+ const backToDsl = schemaToDsl(schema) // FormKit schema → DSL (best-effort import)
447
+
448
+ // Before persisting to the backend, strip frontend-only fields (BaseNode.key, meta.rawSchema):
449
+ const portable = toPortableDefinition(definition)
450
+ await saveFormDefinition(portable)
312
451
  ```
313
452
 
453
+ For the full DSL reference aimed at backend integration — every field of `FormDefinition` /
454
+ `FormSettings` / node types, the expression AST and its built-in functions, validation rule
455
+ structure, event bindings, each container's data shape (and how `flat` vs `nested`
456
+ `dataStructure` changes the submitted JSON), what `toPortableDefinition` strips, and a complete
457
+ worked example — see **[docs/dsl.en.md](./docs/dsl.en.md)** (Chinese: [docs/dsl.md](./docs/dsl.md)).
458
+
314
459
  ### Extending Elements
315
460
 
316
461
  Register custom elements via `config.elements` or `registerElement(s)` (DSL registry + FormKit input + canvas/preview all at once):
317
462
 
318
463
  ```ts
319
- import { registerElement, formkitConfig } from "@zeng-alt/formkit-form-builder";
320
- import type { RegisterElementInput } from "@zeng-alt/formkit-form-builder";
464
+ import { registerElement, formkitConfig } from '@zeng-alt/formkit-form-builder'
465
+ import type { RegisterElementInput } from '@zeng-alt/formkit-form-builder'
321
466
 
322
467
  registerElement({
323
- type: "myField",
324
- category: "field",
325
- label: "Custom Field",
468
+ type: 'myField',
469
+ category: 'field',
470
+ label: 'Custom Field',
326
471
  // ... see RegisterElementInput type
327
- });
472
+ })
328
473
 
329
- createApp(App).use(plugin, formkitConfig());
474
+ createApp(App).use(plugin, formkitConfig())
330
475
  ```
331
476
 
332
477
  ## i18n Overrides
@@ -335,17 +480,60 @@ createApp(App).use(plugin, formkitConfig());
335
480
 
336
481
  ```ts
337
482
  const config = {
338
- locale: "zh-CN",
483
+ locale: 'zh-CN',
339
484
  messages: {
340
- "zh-CN": {
485
+ 'zh-CN': {
341
486
  builder: {
342
- clearForm: "Clear current form", // Only overrides this key; other builder.* preserved
487
+ clearForm: 'Clear current form', // Only overrides this key; other builder.* preserved
343
488
  },
344
489
  },
345
490
  },
346
- };
491
+ }
347
492
  ```
348
493
 
494
+ The DSL expression function `today()` resolves its time zone from the currently active
495
+ runtime language (`zh-CN` → `Asia/Shanghai`, `ja` → `Asia/Tokyo`, etc.; `en` has no fixed
496
+ mapping and falls back to the browser's local time zone) instead of a fixed UTC offset,
497
+ avoiding an off-by-one-day result in the evening for users east of UTC. It syncs
498
+ automatically on language switch; hosts can also extend the mapping via
499
+ `LOCALE_TIME_ZONES`, or set the evaluation language manually with `setExprLocale` (useful
500
+ when using the DSL conversion utilities standalone, outside `FormBuilder` / `FormRenderer`).
501
+
502
+ ```ts
503
+ import { setExprLocale, LOCALE_TIME_ZONES } from '@zeng-alt/formkit-form-builder'
504
+
505
+ LOCALE_TIME_ZONES['fr'] = 'Europe/Paris' // extend the mapping
506
+ setExprLocale('zh-CN') // manual override (synced automatically inside FormBuilder/FormRenderer)
507
+ ```
508
+
509
+ ## Security
510
+
511
+ A `FormDefinition` can carry opaque JS strings in a few places: field/static-node
512
+ `events` (event bindings, e.g. `onClick`), `settings.submit` (custom submit logic),
513
+ and a data-table's `getData` / `createData` / `updateData` / `deleteData` (remote
514
+ data hooks). `FormRenderer` executes these client-side with `new Function`, and the
515
+ executed code can reach the injected `axios` instance — which by default carries
516
+ the page's same-origin credentials (cookies).
517
+
518
+ What this means: **whoever can edit a form definition can run arbitrary JS in the
519
+ browser of every user who fills that form.** This is a standard trade-off for a
520
+ low-code/no-code platform, not a bug — but if the people who design forms and the
521
+ people who fill them out sit in different trust zones (e.g. an internal ops team
522
+ authors forms that end customers fill in), an unreviewed `FormDefinition` is
523
+ equivalent to stored XSS.
524
+
525
+ Recommendations:
526
+
527
+ - When persisting a `FormDefinition` on the backend, apply an allow-list or a
528
+ signature check to `props.__bind` (event handlers), `settings.submit`, and the
529
+ data-table `getData`/`createData`/`updateData`/`deleteData` fields before
530
+ trusting them again.
531
+ - Only expose the designer (`FormBuilder`) to roles you trust to write JS; treat a
532
+ submitted `FormDefinition` from a lower-trust role as untrusted input.
533
+ - `config.apiKey` is sent straight from the browser to the AI endpoint. Never ship
534
+ a real key to production; point `config.aiBaseUrl` at your own server-side proxy
535
+ instead and keep the key there.
536
+
349
537
  ## Examples
350
538
 
351
539
  ![light](./img/light.png)
@@ -390,4 +578,4 @@ pnpm version patch # 1.0.0 → 1.0.1
390
578
  pnpm version minor # 1.0.0 → 1.1.0
391
579
  pnpm version major # 1.0.0 → 2.0.0
392
580
  pnpm publish
393
- ```
581
+ ```