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

|
|
@@ -390,4 +576,4 @@ pnpm version patch # 1.0.0 → 1.0.1
|
|
|
390
576
|
pnpm version minor # 1.0.0 → 1.1.0
|
|
391
577
|
pnpm version major # 1.0.0 → 2.0.0
|
|
392
578
|
pnpm publish
|
|
393
|
-
```
|
|
579
|
+
```
|