@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.
- package/CHANGELOG.md +45 -0
- package/README.md +325 -137
- package/dist/builder.css +1 -1
- package/dist/builder.es.js +7922 -42834
- package/dist/builder.es.js.map +1 -0
- package/dist/builder.umd.js +58 -86
- package/dist/chunks/AiPrompt-CWUhBDH4.js +174 -0
- package/dist/chunks/AiPrompt-CWUhBDH4.js.map +1 -0
- package/dist/chunks/BadgeEditor-B1kB2DXg.js +133 -0
- package/dist/chunks/BadgeEditor-B1kB2DXg.js.map +1 -0
- package/dist/chunks/BuilderPreview-CKL5bqCP.js +142 -0
- package/dist/chunks/BuilderPreview-CKL5bqCP.js.map +1 -0
- package/dist/chunks/ButtonGroupEditor-C5pChDFz.js +55 -0
- package/dist/chunks/ButtonGroupEditor-C5pChDFz.js.map +1 -0
- package/dist/chunks/CardEditor-Bsbriwvu.js +61 -0
- package/dist/chunks/CardEditor-Bsbriwvu.js.map +1 -0
- package/dist/chunks/CheckboxEditor-CxNEvn_Y.js +23 -0
- package/dist/chunks/CheckboxEditor-CxNEvn_Y.js.map +1 -0
- package/dist/chunks/CollapseEditor-CUFTdj0V.js +36 -0
- package/dist/chunks/CollapseEditor-CUFTdj0V.js.map +1 -0
- package/dist/chunks/ColorEditor-Bo9QkLsR.js +17 -0
- package/dist/chunks/ColorEditor-Bo9QkLsR.js.map +1 -0
- package/dist/chunks/DataTableContainerPreview-phlGcigM.js +403 -0
- package/dist/chunks/DataTableContainerPreview-phlGcigM.js.map +1 -0
- package/dist/chunks/DataTableEditor-BTDWXdtk.js +473 -0
- package/dist/chunks/DataTableEditor-BTDWXdtk.js.map +1 -0
- package/dist/chunks/DataTableFieldPicker-qWxGmVxr.js +1579 -0
- package/dist/chunks/DataTableFieldPicker-qWxGmVxr.js.map +1 -0
- package/dist/chunks/DataTableRowCellInput-BLTM3I21.js +195 -0
- package/dist/chunks/DataTableRowCellInput-BLTM3I21.js.map +1 -0
- package/dist/chunks/DataTableSearchField-PU89hniM.js +81 -0
- package/dist/chunks/DataTableSearchField-PU89hniM.js.map +1 -0
- package/dist/chunks/DateLikeEditor-ZkCbMhpE.js +74 -0
- package/dist/chunks/DateLikeEditor-ZkCbMhpE.js.map +1 -0
- package/dist/chunks/DateTimeEditor-C-jZKTT5.js +73 -0
- package/dist/chunks/DateTimeEditor-C-jZKTT5.js.map +1 -0
- package/dist/chunks/EditorSection-BR3qdK2c.js +23 -0
- package/dist/chunks/EditorSection-BR3qdK2c.js.map +1 -0
- package/dist/chunks/EditsLayout-fueCrxZM.js +22 -0
- package/dist/chunks/EditsLayout-fueCrxZM.js.map +1 -0
- package/dist/chunks/ExprEditModal-CeXiPStM.js +540 -0
- package/dist/chunks/ExprEditModal-CeXiPStM.js.map +1 -0
- package/dist/chunks/FileEditor-BXELd_SD.js +35 -0
- package/dist/chunks/FileEditor-BXELd_SD.js.map +1 -0
- package/dist/chunks/FormRenderer-BwykpB3h.js +2625 -0
- package/dist/chunks/FormRenderer-BwykpB3h.js.map +1 -0
- package/dist/chunks/GroupEditor-DchDUDDY.js +13 -0
- package/dist/chunks/GroupEditor-DchDUDDY.js.map +1 -0
- package/dist/chunks/HistoryPanel-1p0-Obef.js +104 -0
- package/dist/chunks/HistoryPanel-1p0-Obef.js.map +1 -0
- package/dist/chunks/ImportExportModal-CTqkyp1s.js +266 -0
- package/dist/chunks/ImportExportModal-CTqkyp1s.js.map +1 -0
- package/dist/chunks/InlineEditableText-BO-dT5rp.js +68 -0
- package/dist/chunks/InlineEditableText-BO-dT5rp.js.map +1 -0
- package/dist/chunks/InputGroupEditor-D_5giZtN.js +13 -0
- package/dist/chunks/InputGroupEditor-D_5giZtN.js.map +1 -0
- package/dist/chunks/IssuesPanel-CW5bdwvC.js +82 -0
- package/dist/chunks/IssuesPanel-CW5bdwvC.js.map +1 -0
- package/dist/chunks/JsCodeEditor-CIPxhwZa.js +751 -0
- package/dist/chunks/JsCodeEditor-CIPxhwZa.js.map +1 -0
- package/dist/chunks/JsonTextarea-C3mnRwtG.js +54 -0
- package/dist/chunks/JsonTextarea-C3mnRwtG.js.map +1 -0
- package/dist/chunks/ListEditor-C1hn5yOi.js +25 -0
- package/dist/chunks/ListEditor-C1hn5yOi.js.map +1 -0
- package/dist/chunks/NaiveAlertEditor-DACimYS1.js +67 -0
- package/dist/chunks/NaiveAlertEditor-DACimYS1.js.map +1 -0
- package/dist/chunks/NaiveAutoCompleteEditor-CtCvPe7H.js +122 -0
- package/dist/chunks/NaiveAutoCompleteEditor-CtCvPe7H.js.map +1 -0
- package/dist/chunks/NaiveAvatarEditor-CmDUodoa.js +36 -0
- package/dist/chunks/NaiveAvatarEditor-CmDUodoa.js.map +1 -0
- package/dist/chunks/NaiveBackTopEditor-Iq-li1JT.js +69 -0
- package/dist/chunks/NaiveBackTopEditor-Iq-li1JT.js.map +1 -0
- package/dist/chunks/NaiveBasicSection-wNyhGLou.js +184 -0
- package/dist/chunks/NaiveBasicSection-wNyhGLou.js.map +1 -0
- package/dist/chunks/NaiveBlockquoteEditor-BfqWqKwF.js +13 -0
- package/dist/chunks/NaiveBlockquoteEditor-BfqWqKwF.js.map +1 -0
- package/dist/chunks/NaiveButtonEditor-B4Rp2T7n.js +168 -0
- package/dist/chunks/NaiveButtonEditor-B4Rp2T7n.js.map +1 -0
- package/dist/chunks/NaiveCascaderEditor-BtD6KRXl.js +26 -0
- package/dist/chunks/NaiveCascaderEditor-BtD6KRXl.js.map +1 -0
- package/dist/chunks/NaiveDividerEditor-B1dPteDV.js +52 -0
- package/dist/chunks/NaiveDividerEditor-B1dPteDV.js.map +1 -0
- package/dist/chunks/NaiveH1Editor-Can7c9mh.js +14 -0
- package/dist/chunks/NaiveH1Editor-Can7c9mh.js.map +1 -0
- package/dist/chunks/NaiveH2Editor-BRKeEVf4.js +14 -0
- package/dist/chunks/NaiveH2Editor-BRKeEVf4.js.map +1 -0
- package/dist/chunks/NaiveH3Editor-DCdyd3-n.js +14 -0
- package/dist/chunks/NaiveH3Editor-DCdyd3-n.js.map +1 -0
- package/dist/chunks/NaiveH4Editor-COFS6udv.js +14 -0
- package/dist/chunks/NaiveH4Editor-COFS6udv.js.map +1 -0
- package/dist/chunks/NaiveH5Editor-CQEe6s1O.js +14 -0
- package/dist/chunks/NaiveH5Editor-CQEe6s1O.js.map +1 -0
- package/dist/chunks/NaiveH6Editor-DHGzIUAl.js +14 -0
- package/dist/chunks/NaiveH6Editor-DHGzIUAl.js.map +1 -0
- package/dist/chunks/NaiveHeaderEditor-Cy02AmLI.js +12 -0
- package/dist/chunks/NaiveHeaderEditor-Cy02AmLI.js.map +1 -0
- package/dist/chunks/NaiveImageEditor-WyVYLNbT.js +201 -0
- package/dist/chunks/NaiveImageEditor-WyVYLNbT.js.map +1 -0
- package/dist/chunks/NaiveLiEditor-CC65rrna.js +13 -0
- package/dist/chunks/NaiveLiEditor-CC65rrna.js.map +1 -0
- package/dist/chunks/NaiveLinkEditor-DkjFrzEE.js +38 -0
- package/dist/chunks/NaiveLinkEditor-DkjFrzEE.js.map +1 -0
- package/dist/chunks/NaiveMentionEditor-BupocM2c.js +23 -0
- package/dist/chunks/NaiveMentionEditor-BupocM2c.js.map +1 -0
- package/dist/chunks/NaiveOlEditor-DYFqg6Sp.js +16 -0
- package/dist/chunks/NaiveOlEditor-DYFqg6Sp.js.map +1 -0
- package/dist/chunks/NaiveParagraphEditor-B3Ju6ZNI.js +104 -0
- package/dist/chunks/NaiveParagraphEditor-B3Ju6ZNI.js.map +1 -0
- package/dist/chunks/NaiveProgressEditor-CwpsZG2z.js +119 -0
- package/dist/chunks/NaiveProgressEditor-CwpsZG2z.js.map +1 -0
- package/dist/chunks/NaiveQrCodeEditor-YWWAozHe.js +77 -0
- package/dist/chunks/NaiveQrCodeEditor-YWWAozHe.js.map +1 -0
- package/dist/chunks/NaiveRateEditor-BVY1QiXv.js +44 -0
- package/dist/chunks/NaiveRateEditor-BVY1QiXv.js.map +1 -0
- package/dist/chunks/NaiveSwitchEditor-BP1v-oZf.js +17 -0
- package/dist/chunks/NaiveSwitchEditor-BP1v-oZf.js.map +1 -0
- package/dist/chunks/NaiveTextEditor-C38l4Q-j.js +107 -0
- package/dist/chunks/NaiveTextEditor-C38l4Q-j.js.map +1 -0
- package/dist/chunks/NaiveTransferEditor-BRH_5ioX.js +19 -0
- package/dist/chunks/NaiveTransferEditor-BRH_5ioX.js.map +1 -0
- package/dist/chunks/NaiveTreeSelectEditor-jX2DrMcT.js +26 -0
- package/dist/chunks/NaiveTreeSelectEditor-jX2DrMcT.js.map +1 -0
- package/dist/chunks/NaiveUlEditor-CMKofBid.js +16 -0
- package/dist/chunks/NaiveUlEditor-CMKofBid.js.map +1 -0
- package/dist/chunks/NumberEditor-0P2Li_GH.js +40 -0
- package/dist/chunks/NumberEditor-0P2Li_GH.js.map +1 -0
- package/dist/chunks/NumberInput-DU-FiLxW.js +37 -0
- package/dist/chunks/NumberInput-DU-FiLxW.js.map +1 -0
- package/dist/chunks/OptionsLayoutSection-C9gVadRA.js +21 -0
- package/dist/chunks/OptionsLayoutSection-C9gVadRA.js.map +1 -0
- package/dist/chunks/OptionsSourceTabs-3fsum0OI.js +628 -0
- package/dist/chunks/OptionsSourceTabs-3fsum0OI.js.map +1 -0
- package/dist/chunks/OptionsTagsSection-vKkxlWLw.js +31 -0
- package/dist/chunks/OptionsTagsSection-vKkxlWLw.js.map +1 -0
- package/dist/chunks/PasswordEditor-Igld1ak6.js +29 -0
- package/dist/chunks/PasswordEditor-Igld1ak6.js.map +1 -0
- package/dist/chunks/PlaceholderSection-BKOS-7Qu.js +26 -0
- package/dist/chunks/PlaceholderSection-BKOS-7Qu.js.map +1 -0
- package/dist/chunks/RadioEditor-CyJhILjI.js +23 -0
- package/dist/chunks/RadioEditor-CyJhILjI.js.map +1 -0
- package/dist/chunks/RangeEditor-PGOnGfuV.js +86 -0
- package/dist/chunks/RangeEditor-PGOnGfuV.js.map +1 -0
- package/dist/chunks/RichText-DqcMtoil.js +424 -0
- package/dist/chunks/RichText-DqcMtoil.js.map +1 -0
- package/dist/chunks/RichTextEditor-EfA6m9w2.js +81 -0
- package/dist/chunks/RichTextEditor-EfA6m9w2.js.map +1 -0
- package/dist/chunks/SelectEditor-mJ_zUivj.js +21 -0
- package/dist/chunks/SelectEditor-mJ_zUivj.js.map +1 -0
- package/dist/chunks/SelectInput-DY4Oi2Lp.js +31 -0
- package/dist/chunks/SelectInput-DY4Oi2Lp.js.map +1 -0
- package/dist/chunks/SignatureEditor-BNttg68X.js +52 -0
- package/dist/chunks/SignatureEditor-BNttg68X.js.map +1 -0
- package/dist/chunks/SignaturePad-qhmoMg1E.js +170 -0
- package/dist/chunks/SignaturePad-qhmoMg1E.js.map +1 -0
- package/dist/chunks/StepsEditor-C8U-ext8.js +63 -0
- package/dist/chunks/StepsEditor-C8U-ext8.js.map +1 -0
- package/dist/chunks/SubmitEditor-B9R984q8.js +168 -0
- package/dist/chunks/SubmitEditor-B9R984q8.js.map +1 -0
- package/dist/chunks/SwitchInput-DQrSTyW0.js +34 -0
- package/dist/chunks/SwitchInput-DQrSTyW0.js.map +1 -0
- package/dist/chunks/TabsEditor-DepUhmsz.js +100 -0
- package/dist/chunks/TabsEditor-DepUhmsz.js.map +1 -0
- package/dist/chunks/TagsInput-DeG3Om1R.js +36 -0
- package/dist/chunks/TagsInput-DeG3Om1R.js.map +1 -0
- package/dist/chunks/TemplatePickerModal-DPkdJJJs.js +440 -0
- package/dist/chunks/TemplatePickerModal-DPkdJJJs.js.map +1 -0
- package/dist/chunks/TextInput-D1EMeBPf.js +53 -0
- package/dist/chunks/TextInput-D1EMeBPf.js.map +1 -0
- package/dist/chunks/TextLikeEditor-Du0nHQWQ.js +56 -0
- package/dist/chunks/TextLikeEditor-Du0nHQWQ.js.map +1 -0
- package/dist/chunks/ToggleInput-DoZPwM0A.js +51 -0
- package/dist/chunks/ToggleInput-DoZPwM0A.js.map +1 -0
- package/dist/chunks/_plugin-vue_export-helper-BxNYtmDu.js +8 -0
- package/dist/chunks/axios-agM_iOnv.js +1589 -0
- package/dist/chunks/axios-agM_iOnv.js.map +1 -0
- package/dist/chunks/bind-runtime-CRyrBYCi.js +58 -0
- package/dist/chunks/bind-runtime-CRyrBYCi.js.map +1 -0
- package/dist/chunks/canvas-locate-CxDD4bDp.js +64 -0
- package/dist/chunks/canvas-locate-CxDD4bDp.js.map +1 -0
- package/dist/chunks/context-4zkSHwVA.js +2510 -0
- package/dist/chunks/context-4zkSHwVA.js.map +1 -0
- package/dist/chunks/create-form-builder-state-CoXaJhWO.js +358 -0
- package/dist/chunks/create-form-builder-state-CoXaJhWO.js.map +1 -0
- package/dist/chunks/date-family-BYkr1OaE.js +75 -0
- package/dist/chunks/date-family-BYkr1OaE.js.map +1 -0
- package/dist/chunks/evaluator-DqNftI0d.js +139 -0
- package/dist/chunks/evaluator-DqNftI0d.js.map +1 -0
- package/dist/chunks/expr-parse-u7_CxMWg.js +463 -0
- package/dist/chunks/expr-parse-u7_CxMWg.js.map +1 -0
- package/dist/chunks/expr-source-BRPYrxuB.js +118 -0
- package/dist/chunks/expr-source-BRPYrxuB.js.map +1 -0
- package/dist/chunks/form-builder-plugin-BCbiWZKT.js +280 -0
- package/dist/chunks/form-builder-plugin-BCbiWZKT.js.map +1 -0
- package/dist/chunks/form-fields-DjLk8iH2.js +877 -0
- package/dist/chunks/form-fields-DjLk8iH2.js.map +1 -0
- package/dist/chunks/form-layout-Dm4QeYrL.js +69 -0
- package/dist/chunks/form-layout-Dm4QeYrL.js.map +1 -0
- package/dist/chunks/grid-C8xMKll5.js +137 -0
- package/dist/chunks/grid-C8xMKll5.js.map +1 -0
- package/dist/chunks/keys-D4DlFgJT.js +61 -0
- package/dist/chunks/keys-D4DlFgJT.js.map +1 -0
- package/dist/chunks/media-family-B4Wijm18.js +178 -0
- package/dist/chunks/media-family-B4Wijm18.js.map +1 -0
- package/dist/chunks/misc-family-CQJhCKco.js +133 -0
- package/dist/chunks/misc-family-CQJhCKco.js.map +1 -0
- package/dist/chunks/rich-text-toolbar-CQidmjGI.js +32 -0
- package/dist/chunks/rich-text-toolbar-CQidmjGI.js.map +1 -0
- package/dist/chunks/rolldown-runtime-DMoxecvO.js +11 -0
- package/dist/chunks/schema-adapter-_sLPmdLy.js +2089 -0
- package/dist/chunks/schema-adapter-_sLPmdLy.js.map +1 -0
- package/dist/chunks/selection-family-T_wZGrXc.js +249 -0
- package/dist/chunks/selection-family-T_wZGrXc.js.map +1 -0
- package/dist/chunks/use-ai-prompt-focus-39DHK41R.js +14 -0
- package/dist/chunks/use-ai-prompt-focus-39DHK41R.js.map +1 -0
- package/dist/chunks/use-bind-events-C-H7jhW_.js +89 -0
- package/dist/chunks/use-bind-events-C-H7jhW_.js.map +1 -0
- package/dist/chunks/use-config-DTr8dhzM.js +16 -0
- package/dist/chunks/use-config-DTr8dhzM.js.map +1 -0
- package/dist/chunks/use-dictionary-BAN34x49.js +26 -0
- package/dist/chunks/use-dictionary-BAN34x49.js.map +1 -0
- package/dist/chunks/use-dynamic-options-DbGSz-3_.js +29 -0
- package/dist/chunks/use-dynamic-options-DbGSz-3_.js.map +1 -0
- package/dist/chunks/use-schema-render-data-DagOPKiy.js +33 -0
- package/dist/chunks/use-schema-render-data-DagOPKiy.js.map +1 -0
- package/dist/chunks/utils-DlUMv2vG.js +53 -0
- package/dist/chunks/utils-DlUMv2vG.js.map +1 -0
- package/dist/index.d.ts +243 -1060
- package/dist/renderer.d.ts +632 -0
- package/dist/renderer.es.js +6 -0
- package/dist/renderer.umd.js +34 -0
- 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
|
|
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
|
|
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
|
|
38
|
-
import { plugin as formkitPlugin } from
|
|
39
|
-
import { formkitConfig } from
|
|
40
|
-
import App from
|
|
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(
|
|
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
|
|
52
|
-
import { FormBuilder, BuilderProvider } from
|
|
53
|
-
import type { FormDefinition } from
|
|
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:
|
|
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`
|
|
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
|
|
77
|
-
import { FormRenderer } from
|
|
78
|
-
import type { FormDefinition } from
|
|
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
|
|
118
|
-
import { FormBuilderPlugin } from
|
|
119
|
-
import App from
|
|
120
|
-
|
|
121
|
-
createApp(App)
|
|
122
|
-
|
|
123
|
-
}
|
|
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
|
|
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
|
-
|
|
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
|
|
171
|
-
|
|
172
|
-
| `modelValue`
|
|
173
|
-
| `config`
|
|
174
|
-
| `theme`
|
|
175
|
-
| `...ConfigProviderProps` | `Partial<ConfigProviderProps>`
|
|
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
|
|
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
|
|
186
|
-
|
|
187
|
-
| `header`
|
|
188
|
-
| `header-left`
|
|
189
|
-
| `header-center` | -
|
|
190
|
-
| `header-right`
|
|
191
|
-
| `empty`
|
|
192
|
-
| `toolbar`
|
|
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
|
|
301
|
+
### FormRenderer API
|
|
197
302
|
|
|
198
303
|
#### Props
|
|
199
304
|
|
|
200
|
-
| Prop
|
|
201
|
-
|
|
202
|
-
| `definition`
|
|
203
|
-
| `schema`
|
|
204
|
-
| `dataStructure`
|
|
205
|
-
| `modelValue`
|
|
206
|
-
| `actions`
|
|
207
|
-
| `submitLabel`
|
|
208
|
-
| `resetLabel`
|
|
209
|
-
| `submitAttrs`
|
|
210
|
-
| `resetAttrs`
|
|
211
|
-
| `actionsJustify`
|
|
212
|
-
| `formClass`
|
|
213
|
-
| `formName`
|
|
214
|
-
| `labelPosition`
|
|
215
|
-
| `labelWidth`
|
|
216
|
-
| `schemaLibrary`
|
|
217
|
-
| `interactiveContainers`
|
|
218
|
-
| `
|
|
219
|
-
|
|
|
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
|
|
224
|
-
|
|
225
|
-
| `update:modelValue` | `value: Record<string, unknown>` | Emitted when form data changes (v-model bidirectional binding)
|
|
226
|
-
| `submit`
|
|
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
|
|
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
|
|
237
|
-
|
|
238
|
-
| `submit`
|
|
239
|
-
| `reset`
|
|
240
|
-
| `
|
|
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
|
|
249
|
-
|
|
250
|
-
| `BuilderPreview`
|
|
251
|
-
| `FormDefinitionPreview` | `
|
|
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
|
|
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
|
|
258
|
-
|
|
259
|
-
| `show`
|
|
260
|
-
| `schema`
|
|
261
|
-
| `title`
|
|
262
|
-
| `description`
|
|
263
|
-
| `showDataPanel`
|
|
264
|
-
| `initialData`
|
|
265
|
-
| `view`
|
|
266
|
-
| `actions`
|
|
267
|
-
| `formClass`
|
|
268
|
-
| `interactiveContainers` | `boolean`
|
|
269
|
-
| `resetOnSubmit`
|
|
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
|
|
274
|
-
|
|
275
|
-
| `show`
|
|
276
|
-
| `formDefinition`
|
|
277
|
-
| `title`
|
|
278
|
-
| `initialData`
|
|
279
|
-
| `actions`
|
|
280
|
-
| `formClass`
|
|
281
|
-
| `interactiveContainers` | `boolean`
|
|
282
|
-
| `showDataPanel`
|
|
283
|
-
| `dataPanelWidth`
|
|
284
|
-
| `resetOnSubmit`
|
|
285
|
-
|
|
286
|
-
|
|
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
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
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
|
|
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 {
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
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
|
|
320
|
-
import type { RegisterElementInput } from
|
|
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:
|
|
324
|
-
category:
|
|
325
|
-
label:
|
|
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:
|
|
483
|
+
locale: 'zh-CN',
|
|
339
484
|
messages: {
|
|
340
|
-
|
|
485
|
+
'zh-CN': {
|
|
341
486
|
builder: {
|
|
342
|
-
clearForm:
|
|
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
|

|
|
@@ -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
|
+
```
|