elements-kit 0.18.2 → 0.19.0

package/dist/utilities/form-object.mjs

@@ -0,0 +1,285 @@
+//#region src/utilities/form-object.ts
+/** True when the control is a button / submit / reset / image. */
+function isButton(control) {
+	if (control instanceof HTMLButtonElement) return true;
+	if (control instanceof HTMLInputElement) return control.type === "submit" || control.type === "reset" || control.type === "button" || control.type === "image";
+	return false;
+}
+/** Drop disabled controls (mirrors native `FormData`). */
+const skipDisabled = (field) => field.control.disabled ? null : field;
+/** Drop submit / reset / button / image controls and `<button>` elements. */
+const skipButtons = (field) => isButton(field.control) ? null : field;
+/** Drop fields whose control is an unchecked checkbox / radio. */
+const dropUnchecked = (field) => field.checked === false ? null : field;
+/**
+* Include unchecked **checkboxes** with the given `value` instead of dropping
+* them. Unchecked **radios** are still dropped (only the selected radio is
+* meaningful). Use this **in place of** {@link dropUnchecked}.
+*
+* @example transforms: [skipDisabled, skipButtons, uncheckedAs(false)]
+*/
+function uncheckedAs(value) {
+	return (field) => {
+		if (field.checked !== false) return field;
+		if (field.control instanceof HTMLInputElement && field.control.type === "radio") return null;
+		return {
+			...field,
+			value,
+			checked: void 0
+		};
+	};
+}
+/** Drop fields whose value is empty: `""`, `null`, or an empty array. */
+const skipEmpty = (field) => {
+	const v = field.value;
+	if (v === "" || v === null) return null;
+	if (Array.isArray(v) && v.length === 0) return null;
+	return field;
+};
+/** Default pipeline: skip disabled controls, buttons, and unchecked checkboxes/radios. */
+const defaultTransforms = [
+	skipDisabled,
+	skipButtons,
+	dropUnchecked
+];
+/** A non-negative integer string (e.g. "0", "12") — denotes an array index. */
+function isIndex(segment) {
+	return /^(0|[1-9]\d*)$/.test(segment);
+}
+/**
+* A trailing `[]` marks an auto-append array field (PHP / form-data-json
+* convention) — `colors[]` appends to the `colors` array, `a.b[]` to `a.b`.
+* Returns the dot-path without the suffix, or `null` when absent.
+*/
+function arrayFieldPath(name) {
+	return name.endsWith("[]") ? name.slice(0, -2) : null;
+}
+/**
+* Segments that could walk into an object's prototype. Writing through them
+* enables prototype-pollution; reading them leaks internal objects. Paths
+* containing any of these are ignored entirely.
+*/
+function hasUnsafeKey(keys) {
+	return keys.some((k) => k === "__proto__" || k === "prototype" || k === "constructor");
+}
+/**
+* Write `value` into `target` at the dot-notation `path`. Object segments
+* create plain objects; integer segments create/extend arrays. Paths
+* containing prototype-polluting segments are ignored.
+*
+* @example setPath(o, "user.tags.0", "a") // { user: { tags: ["a"] } }
+*/
+function setPath(target, path, value) {
+	const keys = path.split(".");
+	if (hasUnsafeKey(keys)) return;
+	let node = target;
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i];
+		if (i === keys.length - 1) {
+			node[key] = value;
+			return;
+		}
+		const nextKey = keys[i + 1];
+		const childShouldBeArray = isIndex(nextKey);
+		const existing = node[key];
+		if (existing === void 0 || typeof existing !== "object" || existing === null) node[key] = childShouldBeArray ? [] : {};
+		node = node[key];
+	}
+}
+/** Read the value at the dot-notation `path` from `source`, or `undefined`. */
+function getPath(source, path) {
+	const keys = path.split(".");
+	if (hasUnsafeKey(keys)) return void 0;
+	let node = source;
+	for (const key of keys) {
+		if (node === null || typeof node !== "object") return void 0;
+		node = node[key];
+	}
+	return node;
+}
+/** Extract one raw {@link Field} from a named control, pre-transform. */
+function extractField(control) {
+	if (control instanceof HTMLInputElement) {
+		const type = control.type;
+		if (type === "checkbox") return {
+			control,
+			name: control.name,
+			value: control.value || "on",
+			checked: control.checked
+		};
+		if (type === "radio") return {
+			control,
+			name: control.name,
+			value: control.value,
+			checked: control.checked
+		};
+		if (type === "file") {
+			const value = control.multiple ? Array.from(control.files ?? []) : control.files?.[0] ?? null;
+			return {
+				control,
+				name: control.name,
+				value
+			};
+		}
+		return {
+			control,
+			name: control.name,
+			value: control.value
+		};
+	}
+	if (control instanceof HTMLSelectElement && control.multiple) return {
+		control,
+		name: control.name,
+		value: Array.from(control.selectedOptions, (o) => o.value)
+	};
+	return {
+		control,
+		name: control.name,
+		value: control.value
+	};
+}
+/**
+* Extracts an {@link HTMLFormElement} into a nested plain object (and writes one
+* back) using dot-notation field names — `name="user.address.city"` nests into
+* objects, numeric segments like `name="tags.0"` build arrays. A static snapshot:
+* values are read/written at call time, no reactivity.
+*
+* Extraction runs each field through a composable {@link FormFieldTransform}
+* pipeline ({@link defaultTransforms} by default), which decides inclusion and
+* may rewrite names/values. Mirrors the ergonomics of the native `FormData`
+* constructor.
+*
+* @example
+* ```ts
+* import { FormObject, defaultTransforms, uncheckedAs }
+*   from "elements-kit/utilities/form-object";
+*
+* // <input name="user.name"> <input name="tags.0"> <input name="tags.1">
+* const data = new FormObject(form).toObject();
+* // => { user: { name: "..." }, tags: ["...", "..."] }
+*
+* // Replace the pipeline — include unchecked checkboxes as false
+* new FormObject(form, {
+*   transforms: [...defaultTransforms.slice(0, 2), uncheckedAs(false)],
+* }).toObject();
+*
+* new FormObject(form).fromObject({ user: { name: "Wael" }, tags: ["a", "b"] });
+* ```
+*/
+var FormObject = class {
+	#form;
+	#transforms;
+	constructor(form, options = {}) {
+		this.#form = form;
+		this.#transforms = options.transforms ?? defaultTransforms;
+	}
+	/** Run a field through the transform pipeline; `null` if any transform drops it. */
+	#applyTransforms(field) {
+		let current = field;
+		for (const transform of this.#transforms) {
+			if (current === null) return null;
+			current = transform(current);
+		}
+		return current;
+	}
+	/**
+	* Place a field into `result`. Array-ness is explicit, like form-data-json:
+	* a name ending in `[]` appends to an array at that path (so a single
+	* `colors[]` still yields `["x"]` and an empty one stays `[]`), while a bare
+	* name is scalar — if several controls share it, the **last value wins**.
+	* Use explicit indices (`tags.0`, `tags.1`) or `[]` to build arrays.
+	*/
+	#assign(result, field) {
+		const { name, value } = field;
+		const arrayPath = arrayFieldPath(name);
+		if (arrayPath !== null) {
+			let arr = getPath(result, arrayPath);
+			if (!Array.isArray(arr)) {
+				arr = [];
+				setPath(result, arrayPath, arr);
+			}
+			arr.push(value);
+			return;
+		}
+		setPath(result, name, value);
+	}
+	/** Snapshot the form into a nested object built from dot-notation names. */
+	toObject() {
+		const result = {};
+		for (const el of this.#form.elements) {
+			const control = el;
+			if (!control.name) continue;
+			const path = arrayFieldPath(control.name);
+			if (path !== null && getPath(result, path) === void 0) setPath(result, path, []);
+		}
+		for (const el of this.#form.elements) {
+			if (!el.name) continue;
+			const field = this.#applyTransforms(extractField(el));
+			if (field === null) continue;
+			this.#assign(result, field);
+		}
+		return result;
+	}
+	/** Alias for {@link toObject} — lets `JSON.stringify(instance)` work. */
+	toJSON() {
+		return this.toObject();
+	}
+	/** True when the control can be written/cleared (named and not disabled). */
+	#isWritable(el) {
+		const control = el;
+		return !!control.name && !control.disabled;
+	}
+	/** Write values from a nested object back onto the form's named controls. */
+	fromObject(data) {
+		for (const el of this.#form.elements) {
+			if (!this.#isWritable(el)) continue;
+			const control = el;
+			const value = getPath(data, arrayFieldPath(control.name) ?? control.name);
+			if (value === void 0) continue;
+			if (control instanceof HTMLInputElement) {
+				const type = control.type;
+				if (type === "checkbox") {
+					if (Array.isArray(value)) control.checked = value.includes(control.value);
+					else if (typeof value === "boolean") control.checked = value;
+					else control.checked = value === control.value || value === "on";
+					continue;
+				}
+				if (type === "radio") {
+					control.checked = control.value === value;
+					continue;
+				}
+				if (type === "file") continue;
+				control.value = value == null ? "" : String(value);
+				continue;
+			}
+			if (control instanceof HTMLSelectElement && control.multiple) {
+				const values = (Array.isArray(value) ? value : [value]).map(String);
+				for (const option of control.options) option.selected = values.includes(option.value);
+				continue;
+			}
+			control.value = value == null ? "" : String(value);
+		}
+		return this;
+	}
+	/** Reset every named control to its empty/default state. */
+	clear() {
+		for (const el of this.#form.elements) {
+			if (!this.#isWritable(el)) continue;
+			const control = el;
+			if (control instanceof HTMLInputElement) {
+				const type = control.type;
+				if (type === "checkbox" || type === "radio") control.checked = false;
+				else control.value = "";
+				continue;
+			}
+			if (control instanceof HTMLSelectElement) {
+				for (const option of control.options) option.selected = false;
+				continue;
+			}
+			control.value = "";
+		}
+		return this;
+	}
+};
+//#endregion
+export { FormObject, defaultTransforms, dropUnchecked, skipButtons, skipDisabled, skipEmpty, uncheckedAs };

package/dist/utilities/form-object.test.d.mts

@@ -0,0 +1 @@
+export { };