npm - formbuilder-plugin-group - Versions diffs - 1.0.0 - Mend

formbuilder-plugin-group 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Kevin Chappell
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,174 @@
+# formbuilder-plugin-group
+A **Group** field type for [formBuilder](https://formbuilder.online/) that bundles any number of
+registered child fields into a single, optionally-repeatable set.
+**▶ [Live demo](https://kevinchappell.github.io/formBuilder-plugin-group/)**
+---
+## Features
+- Drag a single **Group** field onto the builder stage — the whole set moves as one unit.
+- Inline child-field picker: add, reorder (drag handle), duplicate, or remove child fields
+  without leaving the builder.
+- Per-child edit panels powered by the formBuilder edit-panel hook (see [Requirement](#requirement-formbuilderwith-edit-panel-hook) below).
+- Clean nested serialisation: `getData()` returns `fields` as a proper JSON array, not a
+  stringified blob.
+- formRender support: static rendering and repeatable instances with Add / Remove buttons,
+  enforced `min` / `max`, and bracket-style child input naming (`group[0][child]`).
+---
+## Requirement: formBuilder with edit-panel hook
+The editor's per-child edit panels rely on a core hook (`generateAdvFields` /
+`getAttrVals` / `updatePreview` / `stage.fbInstance`) that is **not yet in the published
+npm package**. It will ship with formBuilder **>= 3.23.0**.
+Until that release:
+1. Clone and build the patched formBuilder branch locally:
+   ```bash
+   git clone https://github.com/kevinchappell/formBuilder.git ~/Dev/formBuilder
+   cd ~/Dev/formBuilder
+   git checkout feat/edit-panel-hook
+   npm install
+   npm run build:dev       # produces dist/form-builder.min.js
+   ```
+2. In your project, reference that local build instead of the npm package:
+   ```html
+   <script src="/path/to/formBuilder/dist/form-builder.min.js"></script>
+   ```
+   or, if you use a bundler, set up a path alias / `npm link`.
+> formRender (rendering only, no editor) works with the **published** npm package and does
+> **not** require the hook.
+---
+## Installation
+```bash
+npm install formbuilder-plugin-group
+```
+Or download `dist/group.umd.js` and include it via a `<script>` tag.
+---
+## Usage
+### Script tag (UMD)
+```html
+<!-- 1. jQuery -->
+<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+<!-- 2. formBuilder WITH edit-panel hook (see Requirement above) -->
+<script src="/path/to/form-builder.min.js"></script>
+<!-- 3. Group plugin — must load AFTER formBuilder -->
+<script src="node_modules/formbuilder-plugin-group/dist/group.umd.js"></script>
+<div id="build"></div>
+<script>
+  const fb = $('#build').formBuilder()
+</script>
+```
+For **formRender** only (no editor):
+```html
+<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+<script src="node_modules/formBuilder/dist/form-render.min.js"></script>
+<script src="node_modules/formbuilder-plugin-group/dist/group.umd.js"></script>
+<form id="form"></form>
+<script>
+  $('#form').formRender({
+    formData: [
+      {
+        type: 'group',
+        name: 'address',
+        label: 'Address',
+        repeatable: true,
+        min: 1,
+        max: 3,
+        addLabel: 'Add another address',
+        fields: [
+          { type: 'text', name: 'street', label: 'Street' },
+          { type: 'text', name: 'city',   label: 'City'   },
+        ],
+      },
+    ],
+  })
+</script>
+```
+### ESM (bundler)
+```js
+import 'formbuilder-plugin-group'   // registers the control via window.fbControls
+import $ from 'jquery'
+const fb = $('#build').formBuilder()
+```
+### Styles
+Styles are bundled into the plugin script and injected automatically when it loads — there is no
+separate stylesheet to include. To customise, override the `.group-editor`, `.group-child`,
+`.fb-group`, and `.fb-group-instance` classes in your own CSS after the plugin loads.
+---
+## Group field options
+These options appear in the formBuilder edit panel for a Group field and are also accepted
+directly in `formData` / `formRender`.
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | `"Group"` | Human-readable label shown above the group. |
+| `name` | `string` | auto | Field name; used as the bracket-notation prefix for child inputs in formRender (`name[i][child]`). |
+| `repeatable` | `boolean` | `false` | When `true`, the rendered group shows Add / Remove buttons so users can create multiple instances. |
+| `min` | `number` | `1` | Minimum number of instances (only relevant when `repeatable: true`). Remove is disabled when the instance count equals `min`. |
+| `max` | `number` | _(none)_ | Maximum number of instances (only relevant when `repeatable: true`). Add is disabled when the instance count equals `max`. Leave empty for unlimited. |
+| `addLabel` | `string` | `"Add another"` | Label text for the Add-instance button in formRender. |
+| `fields` | `array` | `[]` | Child field configurations (serialised as a JSON array). Managed via the inline editor in formBuilder; pass directly in `formData` for formRender. |
+---
+## v1 Non-goals
+The following features are intentionally **out of scope** for v1 and will not be
+implemented without a new major design:
+- **Nested groups** — a Group field cannot contain another Group field. The child-field
+  picker explicitly excludes `group` from the list of available types.
+- **Per-child grid / column layout** — all child fields stack vertically within a group
+  instance; custom grid positioning of individual children is not supported.
+- **Alternative naming schemes** — child input names always use bracket notation
+  (`group[i][child]`). Dot-notation or flat naming are not configurable.
+- **Group-level value binding** — the `value` and `placeholder` attributes are disabled
+  on the group control itself; values live in the individual child fields.
+---
+## Development
+```bash
+npm install
+npm run build   # produces dist/group.mjs + dist/group.umd.js
+npm test        # unit + integration tests via Vitest
+npm run lint    # ESLint
+```
+Demo pages in `demo/` load the UMD build directly; see `demo/MANUAL-VERIFICATION.md` for
+the human browser-verification checklist.
+---
+## License
+MIT

package/dist/group.mjs ADDED Viewed

@@ -0,0 +1,378 @@
+//#region src/group.css?inline
+var e = ".fields-wrap{display:none}.group-editor{box-sizing:border-box;border:1px dashed #b6b6b6;border-radius:4px;width:100%;padding:8px}.group-children{margin:0;padding:0;list-style:none}.group-child{background:#f7f7f7;border-radius:3px;margin-bottom:4px;padding:4px}.group-child .gc-handle{cursor:move}.group-child .gc-label{flex:1}.group-item-preview{align-items:center;gap:6px;display:flex}.group-item-preview .gc-btn{appearance:none;color:#8d8d8d;cursor:pointer;background:0 0;border:0;border-radius:3px;flex:none;width:20px;height:20px;padding:0;line-height:20px;transition:color .15s,background-color .15s;font-size:.85em!important}.group-item-preview .gc-btn:hover{color:#333;background-color:#0000000f}.group-item-preview .gc-remove:hover{color:#c10000}.group-child-edit{flex-basis:100%;margin-top:6px}.prev-holder .group-child-edit .form-group>label:not([class=formbuilder-checkbox-label]){display:block}.prev-holder .group-child-edit .form-group{margin-bottom:15px!important;font-size:.85em!important}.prev-holder .group-child-edit .form-group label{display:block!important}.prev-holder .group-child-edit .form-group .form-control{height:28px;font-size:inherit}.prev-holder .group-child-edit input[type=text],.prev-holder .group-child-edit input[type=number],.prev-holder .group-child-edit textarea,.prev-holder .group-child-edit select{box-shadow:none}.fb-group{border:1px solid #ddd;border-radius:4px;padding:12px}.fb-group-instance{border-bottom:1px solid #eee;padding:8px 0;position:relative}.fb-group-instance:last-child{border-bottom:none}.fb-group-remove{position:absolute;top:8px;right:0}";
+//#endregion
+//#region src/injectStyles.js
+function t(e) {
+	if (typeof document > "u" || !e || document.head.querySelector("style[data-formbuilder-group]")) return;
+	let t = document.createElement("style");
+	t.setAttribute("data-formbuilder-group", ""), t.textContent = e, document.head.appendChild(t);
+}
+//#endregion
+//#region src/lib/normalizeFields.js
+function n(e) {
+	if (Array.isArray(e)) return e;
+	if (typeof e == "string" && e.trim() !== "") try {
+		let t = JSON.parse(e);
+		return Array.isArray(t) ? t : [];
+	} catch {
+		return [];
+	}
+	return [];
+}
+//#endregion
+//#region src/render/buildRender.js
+function r(e) {
+	let t = e.label, n = e.markup("div", null, { className: "group-instances" }), r = [];
+	t && r.push(e.markup("legend", e.parsedHtml(t))), r.push(n);
+	let i = e.markup("fieldset", r, { className: "fb-group" });
+	return e._groupHost = n, {
+		field: i,
+		layout: "noLabel"
+	};
+}
+//#endregion
+//#region src/render/renderInstance.js
+function i(e, t, n) {
+	n(e).formRender({
+		formData: t,
+		container: e
+	});
+}
+//#endregion
+//#region src/lib/indexChildConfigs.js
+function a(e, t, n) {
+	return (e || []).map((e) => {
+		let r = structuredClone(e);
+		if (delete r.id, typeof r.name == "string" && r.name !== "") {
+			let e = r.name.endsWith("[]");
+			r.name = `${t}[${n}][${e ? r.name.slice(0, -2) : r.name}]${e ? "[]" : ""}`;
+		}
+		return r;
+	});
+}
+//#endregion
+//#region src/render/repeatable.js
+function o(e, t, n) {
+	let { fields: r, groupName: o, addLabel: s } = t, c = Number.isFinite(+t.min) && +t.min > 0 ? +t.min : 1, l = t.max === "" || t.max == null ? null : +t.max;
+	l !== null && l < c && (l = c);
+	let u = 0, d = 0, f = document.createElement("div");
+	f.className = "fb-group-controls";
+	let p = document.createElement("button");
+	p.type = "button", p.className = "fb-group-add", p.textContent = s || "Add another", f.appendChild(p);
+	function m() {
+		p.disabled = l != null && d >= l, e.querySelectorAll(".fb-group-remove").forEach((e) => {
+			e.disabled = d <= c;
+		});
+	}
+	function h() {
+		if (l != null && d >= l) return;
+		let t = u++, s = document.createElement("div");
+		s.className = "fb-group-instance";
+		let c = document.createElement("div");
+		s.appendChild(c);
+		let f = document.createElement("button");
+		f.type = "button", f.className = "fb-group-remove", f.textContent = "×", f.addEventListener("click", () => g(s)), s.appendChild(f), e.appendChild(s), i(c, a(r, o, t), n), d++, m();
+	}
+	function g(e) {
+		d <= c || (e.remove(), d--, m());
+	}
+	p.addEventListener("click", h), (e.parentNode || e).appendChild(f);
+	for (let e = 0; e < c; e++) h();
+	return {
+		addInstance: h,
+		removeInstance: g,
+		count: () => d
+	};
+}
+//#endregion
+//#region src/editor/groupState.js
+function s(e) {
+	let t = (e || []).map((e) => structuredClone(e));
+	return {
+		get: () => t.map((e) => structuredClone(e)),
+		set: (e) => {
+			t = e.map((e) => structuredClone(e));
+		},
+		add: (e) => {
+			t.push(structuredClone(e));
+		},
+		removeAt: (e) => {
+			t.splice(e, 1);
+		},
+		updateAt: (e, n) => {
+			t[e] = structuredClone(n);
+		},
+		moveTo: (e, n) => {
+			let [r] = t.splice(e, 1);
+			t.splice(n, 0, r);
+		}
+	};
+}
+//#endregion
+//#region src/editor/buildEditor.js
+function c(e) {
+	let t = e && e.closest(".form-field");
+	return t ? t.querySelector(".fld-fields") : null;
+}
+function l(e, t) {
+	e && (e.value = JSON.stringify(t.get()));
+}
+function u(e) {
+	let t = s(e.childFields), n = e.markup("ol", null, { className: "group-children" }), r = e.markup("div", null, { className: "group-add" }), i = e.markup("div", [n, r], { className: "group-editor" });
+	return e._groupEditor = {
+		state: t,
+		list: n,
+		pickerMount: r,
+		editor: i,
+		hidden: null
+	}, {
+		field: i,
+		layout: "noLabel"
+	};
+}
+//#endregion
+//#region src/editor/picker.js
+function d(e, t) {
+	let n = document.createElement("div");
+	n.className = "group-picker";
+	let r = document.createElement("select");
+	e.filter((e) => e.type !== "group").forEach((e) => {
+		let t = document.createElement("option");
+		t.value = e.type, t.textContent = e.label || e.type, r.appendChild(t);
+	});
+	let i = document.createElement("button");
+	return i.type = "button", i.className = "group-add-btn", i.textContent = "Add field", i.addEventListener("click", () => {
+		r.value && t(r.value);
+	}), n.append(r, i), n;
+}
+//#endregion
+//#region src/editor/palette.js
+function f(e) {
+	return e = String(e).replace(/[^\w\s\-\[\]]/gi, ""), e = e.replace(/\[([^\]]+)\]/g, "-$1"), e = e.replace(/([A-Z])/g, (e) => "-" + e.toLowerCase()), e.replace(/\s/g, "-").replace(/^-+/g, "");
+}
+function p(e) {
+	return JSON.parse(JSON.stringify(e));
+}
+var m = (() => {
+	let e, t = 0;
+	return (n) => {
+		let r = Date.now();
+		return r === e ? t++ : (t = 0, e = r), `${n.type || f(n.label)}-${r}-${t}`;
+	};
+})(), h = [
+	"text",
+	"number",
+	"file",
+	"date",
+	"select",
+	"textarea",
+	"autocomplete"
+];
+function g(e) {
+	return e.name ||= m(e), h.includes(e.type) && (e.className = e.className || "form-control"), e;
+}
+function _(e, t) {
+	let n = e && e.controls;
+	if (!n) return [g({
+		type: t,
+		label: t
+	})];
+	let r = (n.opts && n.opts.inputSets || []).find((e) => (e.name || f(e.label)) === t);
+	if (r) {
+		let e = [];
+		return r.showHeader && e.push(g({
+			type: "header",
+			subtype: "h2",
+			id: r.name,
+			label: r.label
+		})), (r.fields || []).forEach((t) => e.push(g(p(t)))), e;
+	}
+	let i = n.custom && n.custom.lookup(t);
+	if (i) {
+		let e = p(i);
+		return e.label = n.custom.label(t), [g(e)];
+	}
+	let a = n.getClass && n.getClass(t);
+	return [g({
+		type: t,
+		label: a && typeof a.label == "function" ? a.label(t) : t
+	})];
+}
+function v(e, t) {
+	let n = e && e.controls;
+	return n && Array.isArray(n.controlList) ? n.controlList.filter((e) => e !== "group").map((e) => {
+		let t = n.allControls && n.allControls[e];
+		return {
+			type: e,
+			label: (t && t.textContent ? t.textContent.trim() : "") || e
+		};
+	}) : (t && t.getRegistered ? t.getRegistered() : []).filter((e) => e !== "group").map((e) => ({
+		type: e,
+		label: e
+	}));
+}
+//#endregion
+//#region src/editor/childRow.js
+function y(e, t, n) {
+	let r = document.createElement("li");
+	r.className = "group-child", r.dataset.index = String(t);
+	let i = document.createElement("span");
+	i.className = "gc-handle", i.textContent = "⋮⋮";
+	let a = document.createElement("span");
+	a.className = "gc-label", a.textContent = `${e.type}: ${e.label || e.name || ""}`;
+	let o = (e, n, r, i) => {
+		let a = document.createElement("button");
+		return a.type = "button", a.className = `gc-btn ${e} ${n}`, a.title = r, a.setAttribute("aria-label", r), a.addEventListener("click", () => i(t)), a;
+	}, s = document.createElement("div");
+	return s.className = "group-item-preview", s.append(i, a, o("gc-edit", "formbuilder-icon-pencil", "Edit", n.onEdit), o("gc-duplicate", "formbuilder-icon-copy", "Duplicate", n.onDuplicate), o("gc-remove", "formbuilder-icon-cancel", "Remove", n.onRemove)), r.append(s), r;
+}
+//#endregion
+//#region src/editor/findInstance.js
+function b(e) {
+	let t = e;
+	for (; t;) {
+		if (t.fbInstance) return t.fbInstance;
+		t = t.parentElement;
+	}
+	return null;
+}
+//#endregion
+//#region src/editor/childEditor.js
+function x(e, t, n) {
+	let { state: r, hidden: i } = e._groupEditor, a = e._findInstance();
+	if (!a || typeof a.generateAdvFields != "function") return;
+	let o = n.querySelector(".group-child-edit");
+	if (o) {
+		o.remove();
+		return;
+	}
+	let s = r.get()[t], c = a.generateAdvFields(s), u = document.createElement("div");
+	u.className = "group-child-edit", u.appendChild(c), n.appendChild(u);
+	let d = () => {
+		let e = a.getAttrVals(c);
+		r.updateAt(t, {
+			type: s.type,
+			...e
+		}), l(i, r);
+	};
+	c.addEventListener("input", d), c.addEventListener("change", d);
+}
+//#endregion
+//#region src/group.control.js
+window.fbControls || (window.fbControls = []);
+function S(e, t) {
+	let a = e;
+	e.jsonAttrs && e.jsonAttrs.set("group", ["fields"]);
+	class s extends e {
+		static get definition() {
+			return {
+				icon: "▦",
+				i18n: { default: "Group" },
+				defaultAttrs: {
+					repeatable: {
+						label: "Repeatable",
+						type: "checkbox",
+						value: !1
+					},
+					min: {
+						label: "Min instances",
+						type: "number",
+						value: 1
+					},
+					max: {
+						label: "Max instances",
+						type: "number",
+						value: ""
+					},
+					addLabel: {
+						label: "Add button text",
+						type: "text",
+						value: "Add another"
+					},
+					fields: {
+						label: "",
+						type: "hidden",
+						value: "[]"
+					}
+				},
+				disabledAttrs: ["value", "placeholder"]
+			};
+		}
+		get childFields() {
+			return n(this.config.fields);
+		}
+		build() {
+			return this.preview ? this.buildEditor() : this.buildRender();
+		}
+		buildEditor() {
+			return u(this);
+		}
+		buildRender() {
+			return r(this);
+		}
+		onRender() {
+			if (this.preview) return this.onRenderEditor();
+			if (this._rendered) return;
+			this._rendered = !0;
+			let e = window.jQuery;
+			this.config.repeatable ? this.renderRepeatable(e) : i(this._groupHost, this.childFields, e);
+		}
+		renderRepeatable(e) {
+			o(this._groupHost, {
+				fields: this.childFields,
+				groupName: this.config.name,
+				min: this.config.min,
+				max: this.config.max,
+				addLabel: this.config.addLabel
+			}, e);
+		}
+		onRenderEditor() {
+			this._groupEditor.hidden = c(this.element);
+			let { state: e, list: t, pickerMount: n } = this._groupEditor, r = () => {
+				l(this._groupEditor.hidden, e), this.onRenderEditor();
+			};
+			t.replaceChildren(), e.get().forEach((n, i) => {
+				t.appendChild(y(n, i, {
+					onEdit: (e) => this.openChildEditor(e),
+					onDuplicate: (t) => {
+						e.add(e.get()[t]), r();
+					},
+					onRemove: (t) => {
+						e.removeAt(t), r();
+					}
+				}));
+			});
+			let i = window.jQuery;
+			i && i.fn.sortable && i(t).sortable({
+				handle: ".gc-handle",
+				items: "> li.group-child",
+				update: (n, a) => {
+					let o = Number(a.item.data("startIndex")), s = i(t).children().index(a.item);
+					!Number.isNaN(o) && o !== s && (e.moveTo(o, s), r());
+				},
+				start: (e, t) => t.item.data("startIndex", t.item.index())
+			});
+			let o = this._findInstance(), s = v(o, a);
+			n.replaceChildren(), n.appendChild(d(s, (t) => {
+				_(o, t).forEach((t) => e.add(t)), r();
+			}));
+		}
+		_findInstance() {
+			return b(this.element);
+		}
+		openChildEditor(e) {
+			let t = this._groupEditor.list.querySelector(`li.group-child[data-index="${e}"]`);
+			t && x(this, e, t);
+		}
+	}
+	return e.register("group", s), s;
+}
+window.fbControls.push(S);
+//#endregion
+//#region package.json
+var C = "0.1.0";
+//#endregion
+//#region src/index.js
+t(e);
+//#endregion
+export { C as VERSION };

package/dist/group.umd.js ADDED Viewed

@@ -0,0 +1 @@

package/package.json ADDED Viewed

@@ -0,0 +1,47 @@
+{
+  "name": "formbuilder-plugin-group",
+  "version": "1.0.0",
+  "description": "Group control plugin for formBuilder — bundle registered inputs into a draggable, repeatable set.",
+  "type": "module",
+  "main": "dist/group.umd.js",
+  "module": "dist/group.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/group.mjs",
+      "require": "./dist/group.umd.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "build:pages": "npm run build && bash scripts/build-pages.sh",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests",
+    "bundle": "bash scripts/bundle.sh",
+    "release": "semantic-release",
+    "prepare": "node scripts/install-hooks.js"
+  },
+  "peerDependencies": {
+    "formBuilder": ">=3.23.0",
+    "jquery": ">=3.4.1"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "21.0.2",
+    "@commitlint/config-conventional": "21.0.2",
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/exec": "7.1.0",
+    "@semantic-release/git": "10.0.1",
+    "eslint": "^9.0.0",
+    "formBuilder": "git+https://github.com/kevinchappell/formBuilder.git#feat/edit-panel-hook",
+    "jquery": "^3.7.1",
+    "jsdom": "^24.0.0",
+    "lefthook": "2.1.9",
+    "semantic-release": "25.0.5",
+    "vite": "8.0.16",
+    "vitest": "4.1.9"
+  },
+  "license": "MIT"
+}