elements-kit 0.18.2 → 0.19.0

package/dist/utilities/form-object.test.mjs

@@ -0,0 +1,408 @@
+import { f as it, l as describe, o as afterEach } from "../benchmark.CX_oY03V-CSLAXL5f.mjs";
+import { t as globalExpect } from "../test.BmQO5GaM-Ddz9cDxc.mjs";
+import { FormObject, defaultTransforms, dropUnchecked, skipButtons, skipEmpty, uncheckedAs } from "./form-object.mjs";
+//#region src/utilities/form-object.test.ts
+afterEach(() => {
+	document.body.innerHTML = "";
+});
+/** Build a form from an HTML string and attach it to the document. */
+function makeForm(html) {
+	const form = document.createElement("form");
+	form.innerHTML = html;
+	document.body.appendChild(form);
+	return form;
+}
+describe("FormObject.toObject", () => {
+	it("reads flat fields into a flat object", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="email" value="a@b.com" />
+      <input name="age" value="30" />
+    `)).toObject()).toEqual({
+			email: "a@b.com",
+			age: "30"
+		});
+	});
+	it("nests dot-notation names into nested objects", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="user.name" value="Wael" />
+      <input name="user.address.city" value="Tunis" />
+    `)).toObject()).toEqual({ user: {
+			name: "Wael",
+			address: { city: "Tunis" }
+		} });
+	});
+	it("builds arrays from numeric segments", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="tags.0" value="a" />
+      <input name="tags.1" value="b" />
+    `)).toObject()).toEqual({ tags: ["a", "b"] });
+	});
+	it("builds arrays of objects from mixed numeric + key segments", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="items.0.id" value="1" />
+      <input name="items.1.id" value="2" />
+    `)).toObject()).toEqual({ items: [{ id: "1" }, { id: "2" }] });
+	});
+	it("reads textarea values", () => {
+		globalExpect(new FormObject(makeForm(`<textarea name="bio">hello</textarea>`)).toObject()).toEqual({ bio: "hello" });
+	});
+	it("uses a checked checkbox's value, defaulting to 'on'", () => {
+		globalExpect(new FormObject(makeForm(`<input type="checkbox" name="agree" checked />`)).toObject()).toEqual({ agree: "on" });
+	});
+	it("omits an unchecked checkbox by default", () => {
+		globalExpect(new FormObject(makeForm(`<input type="checkbox" name="agree" />`)).toObject()).toEqual({});
+	});
+	it("includes an unchecked checkbox as false via uncheckedAs", () => {
+		globalExpect(new FormObject(makeForm(`<input type="checkbox" name="agree" />`), { transforms: [skipButtons, uncheckedAs(false)] }).toObject()).toEqual({ agree: false });
+	});
+	it("collects a `[]` checkbox group into an array of checked values", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="checkbox" name="colors[]" value="red" checked />
+      <input type="checkbox" name="colors[]" value="green" />
+      <input type="checkbox" name="colors[]" value="blue" checked />
+    `)).toObject()).toEqual({ colors: ["red", "blue"] });
+	});
+	it("reads the selected radio value", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="radio" name="plan" value="free" />
+      <input type="radio" name="plan" value="pro" checked />
+    `)).toObject()).toEqual({ plan: "pro" });
+	});
+	it("reads a single select value", () => {
+		globalExpect(new FormObject(makeForm(`
+      <select name="country">
+        <option value="tn">Tunisia</option>
+        <option value="fr" selected>France</option>
+      </select>
+    `)).toObject()).toEqual({ country: "fr" });
+	});
+	it("reads a multiple select as an array", () => {
+		globalExpect(new FormObject(makeForm(`
+      <select name="langs" multiple>
+        <option value="js" selected>JS</option>
+        <option value="ts" selected>TS</option>
+        <option value="go">Go</option>
+      </select>
+    `)).toObject()).toEqual({ langs: ["js", "ts"] });
+	});
+	it("skips disabled controls by default", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="a" value="1" />
+      <input name="b" value="2" disabled />
+    `)).toObject()).toEqual({ a: "1" });
+	});
+	it("includes disabled controls when skipDisabled is omitted", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="a" value="1" />
+      <input name="b" value="2" disabled />
+    `), { transforms: [skipButtons, dropUnchecked] }).toObject()).toEqual({
+			a: "1",
+			b: "2"
+		});
+	});
+	it("skips unnamed controls", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input value="ignored" />
+      <input name="kept" value="ok" />
+    `)).toObject()).toEqual({ kept: "ok" });
+	});
+	it("yields File objects for file inputs", () => {
+		const form = makeForm(`<input type="file" name="doc" />`);
+		const input = form.elements.namedItem("doc");
+		const file = new File(["data"], "report.txt", { type: "text/plain" });
+		const dt = new DataTransfer();
+		dt.items.add(file);
+		input.files = dt.files;
+		const result = new FormObject(form).toObject();
+		globalExpect(result.doc).toBeInstanceOf(File);
+		globalExpect(result.doc.name).toBe("report.txt");
+	});
+});
+describe("FormObject same-name controls (bare name → last value wins)", () => {
+	it("keeps the last value when repeated text inputs share a bare name", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="x" value="a" />
+      <input name="x" value="b" />
+    `)).toObject()).toEqual({ x: "b" });
+	});
+	it("keeps the last value across mixed control kinds with a bare name", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="y" value="a" />
+      <select name="y"><option value="b" selected>b</option></select>
+    `)).toObject()).toEqual({ y: "b" });
+	});
+	it("keeps the last checked value for a bare checkbox group", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="checkbox" name="c" value="r" checked />
+      <input type="checkbox" name="c" value="g" checked />
+    `)).toObject()).toEqual({ c: "g" });
+	});
+	it("lets a checked checkbox override a preceding hidden fallback (idiom)", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="hidden" name="agree" value="0" />
+      <input type="checkbox" name="agree" value="1" checked />
+    `)).toObject()).toEqual({ agree: "1" });
+	});
+	it("keeps the hidden fallback when the checkbox is unchecked", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="hidden" name="agree" value="0" />
+      <input type="checkbox" name="agree" value="1" />
+    `)).toObject()).toEqual({ agree: "0" });
+	});
+	it("keeps a pure radio group as a scalar", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="radio" name="r" value="a" />
+      <input type="radio" name="r" value="b" checked />
+    `)).toObject()).toEqual({ r: "b" });
+	});
+});
+describe("FormObject `[]` array fields", () => {
+	it("wraps a single `[]` control in an array", () => {
+		globalExpect(new FormObject(makeForm(`<input type="checkbox" name="c[]" value="x" checked />`)).toObject()).toEqual({ c: ["x"] });
+	});
+	it("appends every surviving `[]` control in document order", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="checkbox" name="c[]" value="x" checked />
+      <input type="checkbox" name="c[]" value="y" checked />
+    `)).toObject()).toEqual({ c: ["x", "y"] });
+	});
+	it("yields an empty array for a declared-but-empty `[]` field", () => {
+		globalExpect(new FormObject(makeForm(`<input type="checkbox" name="c[]" value="x" />`)).toObject()).toEqual({ c: [] });
+	});
+	it("nests a `[]` array under a dot-path", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="user.tags[]" value="a" />
+      <input name="user.tags[]" value="b" />
+    `)).toObject()).toEqual({ user: { tags: ["a", "b"] } });
+	});
+	it("hidden + `[]` checkbox: array with both when checked, hidden-only when unchecked", () => {
+		const checked = makeForm(`
+      <input type="hidden" name="a[]" value="0" />
+      <input type="checkbox" name="a[]" value="1" checked />
+    `);
+		const unchecked = makeForm(`
+      <input type="hidden" name="a[]" value="0" />
+      <input type="checkbox" name="a[]" value="1" />
+    `);
+		globalExpect(new FormObject(checked).toObject()).toEqual({ a: ["0", "1"] });
+		globalExpect(new FormObject(unchecked).toObject()).toEqual({ a: ["0"] });
+	});
+	it("builds an array of objects via explicit indices", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="items.0.id" value="1" />
+      <input name="items.1.id" value="2" />
+    `)).toObject()).toEqual({ items: [{ id: "1" }, { id: "2" }] });
+	});
+});
+describe("FormObject disabled controls", () => {
+	it("skips a disabled checked checkbox under the default pipeline", () => {
+		globalExpect(new FormObject(makeForm(`<input type="checkbox" name="a" value="1" checked disabled />`)).toObject()).toEqual({});
+	});
+	it("includes a disabled checked checkbox when skipDisabled is omitted", () => {
+		globalExpect(new FormObject(makeForm(`<input type="checkbox" name="a" value="1" checked disabled />`), { transforms: [skipButtons, dropUnchecked] }).toObject()).toEqual({ a: "1" });
+	});
+	it("still drops a disabled UNCHECKED checkbox via dropUnchecked even without skipDisabled", () => {
+		globalExpect(new FormObject(makeForm(`<input type="checkbox" name="a" value="1" disabled />`), { transforms: [skipButtons, dropUnchecked] }).toObject()).toEqual({});
+	});
+	it("appends an included disabled member to a `[]` array", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="checkbox" name="g[]" value="1" checked />
+      <input type="checkbox" name="g[]" value="2" checked disabled />
+    `), { transforms: [skipButtons, dropUnchecked] }).toObject()).toEqual({ g: ["1", "2"] });
+	});
+	it("drops a disabled `[]` member under the default pipeline, keeping the array", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="checkbox" name="g[]" value="1" checked />
+      <input type="checkbox" name="g[]" value="2" checked disabled />
+    `)).toObject()).toEqual({ g: ["1"] });
+	});
+	it("a disabled bare checkbox leaves only the hidden value under the default pipeline", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="hidden" name="a" value="0" />
+      <input type="checkbox" name="a" value="1" checked disabled />
+    `)).toObject()).toEqual({ a: "0" });
+	});
+	it("an included disabled checkbox overrides the hidden value (bare, last wins)", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="hidden" name="a" value="0" />
+      <input type="checkbox" name="a" value="1" checked disabled />
+    `), { transforms: [skipButtons, dropUnchecked] }).toObject()).toEqual({ a: "1" });
+	});
+	it("does not write disabled controls in fromObject", () => {
+		const form = makeForm(`<input name="a" value="orig" disabled />`);
+		new FormObject(form).fromObject({ a: "changed" });
+		globalExpect(form.elements.namedItem("a").value).toBe("orig");
+	});
+});
+describe("FormObject path edge cases", () => {
+	it("does not pollute Object.prototype via __proto__ segments", () => {
+		globalExpect(new FormObject(makeForm(`<input name="__proto__.polluted" value="yes" />`)).toObject()).toEqual({});
+		globalExpect({}.polluted).toBeUndefined();
+	});
+	it("ignores constructor / prototype segments", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="constructor.prototype.x" value="bad" />
+      <input name="a.prototype.b" value="bad" />
+    `)).toObject()).toEqual({});
+	});
+	it("leaves gaps in sparse array indices as holes", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="t.0" value="a" />
+      <input name="t.2" value="c" />
+    `)).toObject()).toEqual({ t: [
+			"a",
+			void 0,
+			"c"
+		] });
+	});
+	it("builds deeply nested arrays of objects", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="a.0.b.0.c" value="1" />
+      <input name="a.0.b.1.c" value="2" />
+    `)).toObject()).toEqual({ a: [{ b: [{ c: "1" }, { c: "2" }] }] });
+	});
+	it("treats numeric top-level names as object keys, not an array", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="0" value="a" />
+      <input name="1" value="b" />
+    `)).toObject()).toEqual({
+			"0": "a",
+			"1": "b"
+		});
+	});
+});
+describe("FormObject transforms", () => {
+	it("skips named buttons by default", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="email" value="a@b.com" />
+      <button name="action" value="save">Save</button>
+      <input type="submit" name="submit" value="go" />
+    `)).toObject()).toEqual({ email: "a@b.com" });
+	});
+	it("drops unchecked checkboxes and radios by default", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="checkbox" name="agree" />
+      <input type="radio" name="plan" value="free" />
+      <input type="radio" name="plan" value="pro" />
+    `)).toObject()).toEqual({});
+	});
+	it("uncheckedAs(false) includes unchecked checkbox but still drops unchecked radio", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input type="checkbox" name="agree" />
+      <input type="radio" name="plan" value="free" />
+      <input type="radio" name="plan" value="pro" />
+    `), { transforms: [skipButtons, uncheckedAs(false)] }).toObject()).toEqual({ agree: false });
+	});
+	it("skipEmpty drops empty-string fields", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="filled" value="x" />
+      <input name="blank" value="" />
+    `), { transforms: [...defaultTransforms, skipEmpty] }).toObject()).toEqual({ filled: "x" });
+	});
+	it("runs a custom transform that rewrites the value", () => {
+		const form = makeForm(`<input name="name" value="  Wael  " />`);
+		const trim = (f) => ({
+			...f,
+			value: typeof f.value === "string" ? f.value.trim() : f.value
+		});
+		globalExpect(new FormObject(form, { transforms: [...defaultTransforms, trim] }).toObject()).toEqual({ name: "Wael" });
+	});
+	it("runs a custom transform that renames the field path", () => {
+		const form = makeForm(`<input name="legacy" value="v" />`);
+		const rename = (f) => f.name === "legacy" ? {
+			...f,
+			name: "modern"
+		} : f;
+		globalExpect(new FormObject(form, { transforms: [...defaultTransforms, rename] }).toObject()).toEqual({ modern: "v" });
+	});
+	it("with an empty pipeline emits everything (disabled, buttons, unchecked)", () => {
+		globalExpect(new FormObject(makeForm(`
+      <input name="a" value="1" disabled />
+      <button name="b" value="x">x</button>
+      <input type="checkbox" name="c" value="on" />
+    `), { transforms: [] }).toObject()).toEqual({
+			a: "1",
+			b: "x",
+			c: "on"
+		});
+	});
+});
+describe("FormObject.fromObject", () => {
+	it("writes nested values back onto controls", () => {
+		const form = makeForm(`
+      <input name="user.name" />
+      <input name="user.address.city" />
+    `);
+		new FormObject(form).fromObject({ user: {
+			name: "Wael",
+			address: { city: "Tunis" }
+		} });
+		globalExpect(form.elements.namedItem("user.name").value).toBe("Wael");
+		globalExpect(form.elements.namedItem("user.address.city").value).toBe("Tunis");
+	});
+	it("writes array values back into numeric-segment controls", () => {
+		const form = makeForm(`
+      <input name="tags.0" />
+      <input name="tags.1" />
+    `);
+		new FormObject(form).fromObject({ tags: ["a", "b"] });
+		globalExpect(form.elements.namedItem("tags.0").value).toBe("a");
+		globalExpect(form.elements.namedItem("tags.1").value).toBe("b");
+	});
+	it("round-trips a `[]` checkbox group through fromObject", () => {
+		const form = makeForm(`
+      <input type="checkbox" name="colors[]" value="red" />
+      <input type="checkbox" name="colors[]" value="green" />
+      <input type="checkbox" name="colors[]" value="blue" />
+    `);
+		new FormObject(form).fromObject({ colors: ["red", "blue"] });
+		globalExpect(new FormObject(form).toObject()).toEqual({ colors: ["red", "blue"] });
+	});
+	it("sets checkbox checked state from a boolean-ish value", () => {
+		const form = makeForm(`<input type="checkbox" name="agree" value="yes" />`);
+		new FormObject(form).fromObject({ agree: "yes" });
+		globalExpect(form.elements.namedItem("agree").checked).toBe(true);
+	});
+	it("selects the matching radio", () => {
+		const form = makeForm(`
+      <input type="radio" name="plan" value="free" />
+      <input type="radio" name="plan" value="pro" />
+    `);
+		new FormObject(form).fromObject({ plan: "pro" });
+		globalExpect(form.querySelector("input[name=plan]:checked")?.value).toBe("pro");
+	});
+	it("leaves controls untouched when the path is missing", () => {
+		const form = makeForm(`<input name="keep" value="original" />`);
+		new FormObject(form).fromObject({ other: "x" });
+		globalExpect(form.elements.namedItem("keep").value).toBe("original");
+	});
+	it("round-trips a form through toObject -> fromObject -> toObject", () => {
+		const html = `
+      <input name="user.name" value="Wael" />
+      <input name="tags.0" value="a" />
+      <input name="tags.1" value="b" />
+      <input type="checkbox" name="agree" checked />
+      <select name="country">
+        <option value="tn">Tunisia</option>
+        <option value="fr" selected>France</option>
+      </select>
+    `;
+		const source = new FormObject(makeForm(html)).toObject();
+		const target = makeForm(html);
+		new FormObject(target).clear();
+		globalExpect(new FormObject(target).fromObject(source).toObject()).toEqual(source);
+	});
+	it("returns this for chaining", () => {
+		const data = new FormObject(makeForm(`<input name="a" />`));
+		globalExpect(data.fromObject({ a: "1" })).toBe(data);
+		globalExpect(data.clear()).toBe(data);
+	});
+});
+describe("FormObject serialization", () => {
+	it("supports JSON.stringify via toJSON", () => {
+		const form = makeForm(`<input name="user.name" value="Wael" />`);
+		globalExpect(JSON.stringify(new FormObject(form))).toBe(JSON.stringify({ user: { name: "Wael" } }));
+	});
+});
+//#endregion
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "elements-kit",
   "type": "module",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "description": "A lightweight reactive UI library that transforms native HTMLElements into reactive components with signals. Ideal for framework-agnostic applications and web components.",
   "keywords": [
     "webcomponents",
@@ -90,15 +90,15 @@
       "types": "./dist/utilities/*.d.mts"
     },
     "./ui/overlay": {
-      "source": "./src/ui/overlay/gestures.ts",
-      "import": "./dist/ui/overlay/gestures.mjs",
-      "types": "./dist/ui/overlay/gestures.d.mts"
+      "source": "./src/ui/overlay/index.ts",
+      "import": "./dist/ui/overlay/index.mjs",
+      "types": "./dist/ui/overlay/index.d.mts"
     },
     "./ui/*": "./dist/ui/*"
   },
   "scripts": {
     "build": "tsdown",
-    "build:docs": "pnpm build && pnpm --filter elements-kit-docs build && pnpm build:storybook && rm -rf docs/dist/storybook && cp -R storybook/storybook-static docs/dist/storybook",
+    "build:docs": "pnpm build && pnpm --filter elements-kit-docs build",
     "build:storybook": "pnpm --filter elements-kit-storybook build",
     "storybook": "pnpm --filter elements-kit-storybook dev",
     "watch": "tsdown -w",