@orkestrel/form 0.0.8 → 0.0.10

package/dist/src/browser/index.js

@@ -0,0 +1,916 @@
+import { attempt, isArray, isBoolean, isFiniteNumber, isInstance, isString, readArrayEntries } from "@orkestrel/contract";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/browser/errors.ts
+/** Reports an incompatible control, overlapping submission, or native DOM failure. */
+var FormBindingError = class extends Error {
+	code;
+	context;
+	/**
+	* Creates a native binding refusal.
+	* @param code - The refusal category.
+	* @param message - The explanation.
+	* @param context - The associated field or cause.
+	*/
+	constructor(code, message, context) {
+		super(message);
+		this.name = "FormBindingError";
+		this.code = code;
+		this.context = context === void 0 ? void 0 : Object.freeze({ ...context });
+	}
+};
+/**
+* Checks whether a value is a native binding refusal.
+* @param value - The value to inspect.
+* @returns True if the value is a native binding refusal; false otherwise.
+* @example
+* ```ts
+* isFormBindingError(new FormBindingError('CONTROL', 'Duplicate text controls')) // true
+* ```
+*/
+function isFormBindingError(value) {
+	return isInstance(value, FormBindingError);
+}
+Object.freeze([
+	"text",
+	"editor",
+	"password",
+	"number",
+	"date",
+	"time",
+	"datetime",
+	"color",
+	"confirm",
+	"select",
+	"checkbox",
+	"file"
+]);
+/** Lists the members every field declares, whatever its control. */
+var FIELD_BASE_KEYS = Object.freeze([
+	"control",
+	"name",
+	"label",
+	"help",
+	"group",
+	"hidden",
+	"disabled",
+	"locked",
+	"rule",
+	"meta"
+]);
+Object.freeze({
+	text: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"default",
+		"placeholder"
+	]),
+	editor: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"default",
+		"placeholder"
+	]),
+	password: Object.freeze([...FIELD_BASE_KEYS, "mask"]),
+	number: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"default",
+		"placeholder"
+	]),
+	date: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	time: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	datetime: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	color: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	confirm: Object.freeze([...FIELD_BASE_KEYS, "default"]),
+	select: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"choices",
+		"default",
+		"open"
+	]),
+	checkbox: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"choices",
+		"default"
+	]),
+	file: Object.freeze([
+		...FIELD_BASE_KEYS,
+		"accept",
+		"multiple"
+	])
+});
+Object.freeze([
+	"editing",
+	"settled",
+	"abandoned"
+]);
+Object.freeze({
+	required: "This field is required",
+	minimum: "Must be at least {limit}",
+	maximum: "Must be at most {limit}",
+	step: "Must be a multiple of {limit}",
+	pattern: "Must match the required format",
+	email: "Must be a valid email address",
+	url: "Must be a valid URL",
+	integer: "Must be an integer",
+	alphanumeric: "Must contain only letters and numbers"
+});
+Object.freeze(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);
+Object.freeze(/^https?:\/\/[^\s]+$/);
+Object.freeze(/^[A-Za-z0-9]+$/);
+Object.freeze(/^[+-]?\d+$/);
+/** Matches a six-digit hexadecimal color string. */
+var COLOR_PATTERN = Object.freeze(/^#[0-9A-Fa-f]{6}$/);
+/** Matches an ISO calendar date string in `YYYY-MM-DD` form. */
+var DATE_PATTERN = Object.freeze(/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/);
+/** Matches a 24-hour time string with optional seconds. */
+var TIME_PATTERN = Object.freeze(/^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/);
+/** Matches an ISO local date and time string with optional seconds. */
+var DATETIME_PATTERN = Object.freeze(/^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/);
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Checks whether a value has the shape required by one field control.
+*
+* @remarks
+* Every write and every seeded value passes through this gate, and it reads `STRING_LIMIT` and
+* `LIST_LIMIT` before it consults the control, so no regular expression sees an over-long value.
+*
+* @param field - The field that owns the value.
+* @param value - The unknown value to inspect.
+* @returns True if the control can hold the value; false otherwise.
+*/
+function matchesField(field, value) {
+	if (isString(value) && value.length > 65536) return false;
+	let entries;
+	if (isArray(value)) {
+		const length = attempt(() => value.length);
+		if (!length.success || length.value > 1024) return false;
+		const read = readArrayEntries(value);
+		if (!read.success || !read.value.dense) return false;
+		entries = read.value.entries;
+		if (entries.some((entry) => !isString(entry) || entry.length > 65536)) return false;
+	}
+	switch (field.control) {
+		case "text":
+		case "editor":
+		case "password": return isString(value);
+		case "number": return isFiniteNumber(value);
+		case "date": return isString(value) && DATE_PATTERN.test(value);
+		case "time": return isString(value) && TIME_PATTERN.test(value);
+		case "datetime": return isString(value) && DATETIME_PATTERN.test(value);
+		case "color": return isString(value) && COLOR_PATTERN.test(value);
+		case "confirm": return isBoolean(value);
+		case "select": return isString(value) && !field.choices.some((choice) => choice.value === value && choice.disabled === true) && (field.open === true || field.choices.some((choice) => choice.value === value && choice.disabled !== true));
+		case "checkbox": return entries !== void 0 && entries.every((entry) => isString(entry) && field.choices.some((choice) => choice.value === entry && choice.disabled !== true)) && new Set(entries).size === entries.length;
+		case "file": return entries !== void 0 && (field.multiple === true || entries.length <= 1);
+	}
+}
+/**
+* Decides whether a raw binding value projects to an answered field.
+*
+* @remarks
+* Bind with `fill(name, matchesAnswer(raw) ? raw : undefined)`. This projection treats an absent
+* value and a string containing only whitespace as unanswered. Every other field value is an
+* answer, including an empty list, `false`, and zero. Core evaluation does not use this projection:
+* its `required` rule remains presence-only.
+*
+* @param value - The raw field value, or absence.
+* @returns True if the binding preserves the value as an answer; false otherwise.
+*/
+function matchesAnswer(value) {
+	return value !== void 0 && (!isString(value) || value.trim().length > 0);
+}
+/**
+* Compares two field values by scalar identity or ordered list content.
+*
+* @param a - The first field value.
+* @param b - The second field value.
+* @returns True if both values contain the same answer; false otherwise.
+*/
+function matchesValue(a, b) {
+	if (isArray(a) || isArray(b)) return isArray(a) && isArray(b) && a.length === b.length && a.every((entry, index) => entry === b[index]);
+	return a === b;
+}
+//#endregion
+//#region src/browser/helpers.ts
+/**
+* Checks a native control population against a field's declared value shape.
+* @param field - The declared field.
+* @param controls - Associated controls sharing its name.
+* @returns True if the population has an unambiguous compatible shape; false otherwise.
+* @example
+* ```ts
+* matchesFormControls({ control: 'text', name: 'name' }, [document.createElement('input')]) // true
+* ```
+*/
+function matchesFormControls(field, controls) {
+	if (controls.length === 0) return true;
+	if (controls.length > 1 && field.control !== "checkbox" && field.control !== "select") return false;
+	return controls.every((control) => {
+		if (control instanceof HTMLTextAreaElement) return field.control === "editor" && controls.length === 1;
+		if (control instanceof HTMLSelectElement) return controls.length === 1 && (control.multiple ? field.control === "checkbox" : field.control === "select");
+		switch (field.control) {
+			case "text": return [
+				"text",
+				"search",
+				"email",
+				"url",
+				"tel",
+				"hidden"
+			].includes(control.type);
+			case "password": return control.type === "password";
+			case "number": return control.type === "number" || control.type === "range";
+			case "datetime": return control.type === "datetime-local";
+			case "confirm": return control.type === "checkbox";
+			case "checkbox": return control.type === "checkbox" && controls.every((entry) => entry instanceof HTMLInputElement);
+			case "select": return control.type === "radio" && controls.every((entry) => entry instanceof HTMLInputElement && entry.type === "radio");
+			case "editor": return false;
+			default: return control.type === field.control;
+		}
+	});
+}
+/**
+* Reads one compatible native population using the document's blank-to-absence semantics.
+* @param field - The field declaring the answer shape.
+* @param controls - Controls sharing the field's name, in native order.
+* @returns The native answer, or undefined for an absent answer or empty population.
+* @throws Thrown when the population or answer is incompatible, including numeric bad input.
+* @example
+* ```ts
+* const input = document.createElement('input')
+* input.value = 'Ada'
+* readFormControls({ control: 'text', name: 'name' }, [input]) // 'Ada'
+* ```
+*/
+function readFormControls(field, controls) {
+	if (!matchesFormControls(field, controls)) throw new FormBindingError("CONTROL", `Incompatible controls for "${field.name}"`, { field: field.name });
+	const first = controls[0];
+	if (first === void 0) return void 0;
+	let value;
+	if (field.control === "checkbox") value = first instanceof HTMLSelectElement ? Array.from(first.selectedOptions, (option) => option.value) : controls.filter((control) => control instanceof HTMLInputElement && control.checked).map((control) => control.value);
+	else if (field.control === "select" && first instanceof HTMLInputElement) value = controls.find((control) => control instanceof HTMLInputElement && control.checked)?.value;
+	else if (field.control === "confirm" && first instanceof HTMLInputElement) value = first.checked;
+	else if (field.control === "number" && first instanceof HTMLInputElement) {
+		if (first.validity.badInput) throw new FormBindingError("CONTROL", "Enter a number", { field: field.name });
+		value = first.value === "" ? void 0 : first.valueAsNumber;
+	} else if (field.control === "file" && first instanceof HTMLInputElement) value = Array.from(first.files ?? [], (file) => file.name);
+	else value = first.value;
+	if (!matchesAnswer(value)) return void 0;
+	if (value !== void 0 && !matchesField(field, value)) throw new FormBindingError("CONTROL", `Incompatible native answer for "${field.name}"`, { field: field.name });
+	return value;
+}
+//#endregion
+//#region src/browser/validators.ts
+/**
+* Checks whether a value is a native answer control.
+* @param value - The value to inspect.
+* @returns True if the value is an input, select, or textarea; false otherwise.
+* @example
+* ```ts
+* isFormControl(document.createElement('input')) // true
+* ```
+*/
+function isFormControl(value) {
+	return typeof HTMLInputElement !== "undefined" && isInstance(value, HTMLInputElement) || typeof HTMLSelectElement !== "undefined" && isInstance(value, HTMLSelectElement) || typeof HTMLTextAreaElement !== "undefined" && isInstance(value, HTMLTextAreaElement);
+}
+//#endregion
+//#region src/browser/FormBinding.ts
+/** Implements a controlled native form over a borrowed document. */
+var FormBinding = class {
+	#element;
+	#document;
+	#options;
+	#emitter;
+	#observer;
+	#listeners = new AbortController();
+	#attributes = /* @__PURE__ */ new Map();
+	#validity = /* @__PURE__ */ new Map();
+	#feedback = /* @__PURE__ */ new Map();
+	#excluded = /* @__PURE__ */ new Set();
+	#logical = /* @__PURE__ */ new Set();
+	#unreadable = /* @__PURE__ */ new Set();
+	#names = /* @__PURE__ */ new Map();
+	#refresh = this.#onState.bind(this);
+	#fill = this.#onFill.bind(this);
+	#disable = this.#onDisable.bind(this);
+	#enable = this.#onEnable.bind(this);
+	#clear = this.#onClear.bind(this);
+	#abandon = this.destroy.bind(this);
+	#controls = /* @__PURE__ */ new Map();
+	#summary;
+	#summaryText = "";
+	#destroyed = false;
+	#running = false;
+	#queued = false;
+	#reading = false;
+	#excluding;
+	#changed = false;
+	#notified = false;
+	#scheduled = false;
+	#submitting = false;
+	/**
+	* Binds existing controls to the supplied document's answers.
+	* @param element - The native form, including its externally associated controls.
+	* @param document - The borrowed answer document.
+	* @param options - Feedback destinations and listeners.
+	* @throws Thrown when controls contradict the schema or native initialization fails.
+	*/
+	constructor(element, document, options) {
+		this.#element = element;
+		this.#document = document;
+		this.#options = options;
+		this.#emitter = new Emitter(options);
+		this.#observer = new MutationObserver(() => this.#onDocument());
+		for (const name of document.disabled) this.#logical.add(name);
+		try {
+			this.#controls = this.#discover();
+			const signal = this.#listeners.signal;
+			element.addEventListener("submit", (event) => this.#onSubmit(event), { signal });
+			element.addEventListener("reset", (event) => this.#onReset(event), { signal });
+			element.ownerDocument.addEventListener("input", (event) => this.#onInput(event), { signal });
+			element.ownerDocument.addEventListener("change", (event) => this.#onInput(event), { signal });
+			element.ownerDocument.addEventListener("focusout", (event) => this.#onBlur(event), { signal });
+			element.ownerDocument.addEventListener("click", (event) => this.#onClick(event), { signal });
+			document.emitter.on("fill", this.#fill);
+			document.emitter.on("disable", this.#disable);
+			document.emitter.on("enable", this.#enable);
+			document.emitter.on("clear", this.#clear);
+			document.emitter.on("abandon", this.#abandon);
+			for (const event of [
+				"touch",
+				"validate",
+				"prepare",
+				"accept",
+				"abort",
+				"submit"
+			]) document.emitter.on(event, this.#refresh);
+			this.refresh();
+			if (!this.#destroyed) this.#observer.observe(element.ownerDocument, {
+				subtree: true,
+				childList: true,
+				attributes: true,
+				attributeFilter: [
+					"name",
+					"form",
+					"id",
+					"type",
+					"multiple",
+					"disabled",
+					"required",
+					"min",
+					"max",
+					"step",
+					"pattern",
+					"minlength",
+					"maxlength",
+					"value",
+					"hidden",
+					"inert",
+					"style",
+					"class"
+				]
+			});
+		} catch (error) {
+			this.destroy();
+			throw error;
+		}
+	}
+	/** Holds the native form. */
+	get element() {
+		return this.#element;
+	}
+	/** Holds the borrowed answer document. */
+	get document() {
+		return this.#document;
+	}
+	/** Reports whether the binding released its resources. */
+	get destroyed() {
+		return this.#destroyed;
+	}
+	/** Holds the binding's isolated event emitter. */
+	get emitter() {
+		return this.#emitter;
+	}
+	/** Imports mounted enabled controls without acknowledging their answers. */
+	read() {
+		if (this.#destroyed || this.#reading || this.#document.status !== "editing") return;
+		const controls = this.#discover();
+		const answers = /* @__PURE__ */ new Map();
+		for (const field of this.#document.schema.fields) {
+			const group = controls.get(field.name);
+			if (group === void 0 || field.locked || this.#logical.has(field.name)) continue;
+			const enabled = group.filter((control) => !this.#nativeDisabled(control));
+			if (enabled.length === 0) continue;
+			if (enabled.some((control) => control.validity.badInput)) {
+				this.#unreadable.add(field.name);
+				continue;
+			}
+			this.#unreadable.delete(field.name);
+			answers.set(field.name, readFormControls(field, enabled));
+		}
+		this.#controls = controls;
+		this.#reading = true;
+		try {
+			this.#exclusions();
+			for (const [name, value] of answers) {
+				if (this.#destroyed) break;
+				const values = this.#document.values;
+				const previous = Object.hasOwn(values, name) ? values[name] : void 0;
+				if (previous === void 0 || value === void 0 ? previous !== value : !matchesValue(previous, value)) this.#document.fill(name, value);
+			}
+		} finally {
+			this.#reading = false;
+			if (!this.#destroyed) this.#drain();
+		}
+	}
+	/** Rediscovers controls and projects the document into the native form. */
+	refresh() {
+		if (this.#destroyed) return;
+		this.#unreadable.clear();
+		this.#drain();
+	}
+	/** Releases owned DOM effects and listeners without destroying the document. */
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#observer.disconnect();
+		this.#listeners.abort();
+		this.#document.emitter.off("fill", this.#fill);
+		this.#document.emitter.off("disable", this.#disable);
+		this.#document.emitter.off("enable", this.#enable);
+		this.#document.emitter.off("clear", this.#clear);
+		this.#document.emitter.off("abandon", this.#abandon);
+		for (const event of [
+			"touch",
+			"validate",
+			"prepare",
+			"accept",
+			"abort",
+			"submit"
+		]) this.#document.emitter.off(event, this.#refresh);
+		for (const element of this.#attributes.keys()) this.#restore(element);
+		for (const control of this.#validity.keys()) this.#restoreValidity(control);
+		for (const node of this.#feedback.values()) node.remove();
+		this.#summary?.remove();
+		if (this.#document.status === "editing") {
+			for (const name of this.#excluded) if (!this.#logical.has(name)) try {
+				this.#document.enable(name);
+			} catch (error) {
+				this.#emitter.emit("error", error);
+			}
+		}
+		this.#excluded.clear();
+		this.#feedback.clear();
+		this.#names.clear();
+		this.#unreadable.clear();
+		this.#logical.clear();
+		this.#controls = /* @__PURE__ */ new Map();
+		this.#summary = void 0;
+		this.#emitter.destroy();
+	}
+	#drain() {
+		if (this.#destroyed) return;
+		this.#queued = true;
+		if (this.#running || this.#reading) return;
+		this.#running = true;
+		try {
+			let turns = 0;
+			while (this.#queued && !this.#destroyed && turns < 2) {
+				this.#queued = false;
+				this.#changed = false;
+				this.#controls = this.#discover();
+				this.#releaseRemoved();
+				this.#exclusions();
+				if (this.#destroyed) break;
+				this.#paint();
+				if (!this.#destroyed && (this.#changed || !this.#notified)) {
+					this.#notified = true;
+					this.#emitter.emit("render");
+				}
+				turns += 1;
+			}
+		} catch (error) {
+			this.#queued = false;
+			throw isFormBindingError(error) ? error : new FormBindingError("DOM", "Native form projection failed", { cause: error });
+		} finally {
+			this.#running = false;
+			if (this.#queued && !this.#destroyed && !this.#scheduled) {
+				this.#scheduled = true;
+				queueMicrotask(() => {
+					this.#scheduled = false;
+					if (!this.#destroyed) this.#onDocument();
+				});
+			}
+		}
+	}
+	#discover() {
+		const groups = /* @__PURE__ */ new Map();
+		for (const control of Array.from(this.#element.elements)) {
+			if (!isFormControl(control) || control.form !== this.#element || !this.#document.field(control.name)) continue;
+			if (control instanceof HTMLInputElement && [
+				"submit",
+				"reset",
+				"button",
+				"image"
+			].includes(control.type)) continue;
+			const group = groups.get(control.name) ?? [];
+			group.push(control);
+			groups.set(control.name, group);
+		}
+		for (const field of this.#document.schema.fields) {
+			const group = groups.get(field.name);
+			if (group !== void 0 && !matchesFormControls(field, group)) throw new FormBindingError("CONTROL", `Incompatible controls for "${field.name}"`, { field: field.name });
+		}
+		return groups;
+	}
+	#nativeDisabled(control) {
+		const owned = this.#attributes.get(control)?.get("disabled");
+		if (owned !== void 0 && control.getAttribute("disabled") === owned.value && owned.original === null) {
+			let ancestor = control.parentElement;
+			while (ancestor !== null) {
+				if (ancestor instanceof HTMLFieldSetElement && ancestor.disabled) {
+					const legend = Array.from(ancestor.children).find((child) => child instanceof HTMLLegendElement);
+					if (legend === void 0 || !legend.contains(control)) return true;
+				}
+				ancestor = ancestor.parentElement;
+			}
+			return false;
+		}
+		return control.matches(":disabled");
+	}
+	#exclusions() {
+		if (this.#document.status !== "editing") return;
+		for (const field of this.#document.schema.fields) {
+			if (this.#destroyed) return;
+			const group = this.#controls.get(field.name);
+			const excluded = group !== void 0 && group.every((control) => this.#nativeDisabled(control));
+			if (excluded && !this.#logical.has(field.name) && !this.#excluded.has(field.name)) {
+				this.#excluded.add(field.name);
+				this.#excluding = field.name;
+				try {
+					this.#document.disable(field.name);
+				} finally {
+					this.#excluding = void 0;
+				}
+			} else if (!excluded && this.#excluded.delete(field.name) && !this.#logical.has(field.name)) {
+				this.#excluding = field.name;
+				try {
+					this.#document.enable(field.name);
+				} finally {
+					this.#excluding = void 0;
+				}
+			}
+		}
+	}
+	#paint() {
+		this.#attribute(this.#element, "novalidate", "");
+		this.#attribute(this.#element, "aria-busy", this.#document.pending === void 0 ? "false" : "true");
+		const errors = [...this.#document.errors];
+		const values = this.#document.values;
+		for (const field of this.#document.schema.fields) {
+			if (this.#destroyed) return;
+			const group = this.#controls.get(field.name) ?? [];
+			for (const control of group) {
+				this.#metadata(field, control);
+				if (!this.#unreadable.has(field.name)) this.#value(field, control, Object.hasOwn(values, field.name) ? values[field.name] : void 0);
+				this.#restoreValidity(control);
+				if (!this.#document.disabled.has(field.name) && !control.validity.valid && control.willValidate) errors.push({
+					field: field.name,
+					message: control.validationMessage
+				});
+			}
+		}
+		for (const field of this.#document.schema.fields) {
+			if (this.#destroyed) return;
+			const message = [...new Set(errors.filter((error) => error.field === field.name).map((error) => error.message))].join("\n");
+			const visible = this.#document.touched.has(field.name) && !this.#document.disabled.has(field.name);
+			const group = this.#controls.get(field.name) ?? [];
+			let feedback = this.#feedback.get(field.name);
+			if (feedback === void 0 && (group.length > 0 || this.#options?.feedback?.has(field.name))) {
+				feedback = this.#element.ownerDocument.createElement("span");
+				feedback.id = `form-feedback-${crypto.randomUUID()}`;
+				feedback.dataset.formFeedback = field.name;
+				const destination = this.#options?.feedback?.get(field.name);
+				if (destination !== void 0) destination.append(feedback);
+				else (group.at(-1) ?? this.#element).insertAdjacentElement("afterend", feedback);
+				this.#feedback.set(field.name, feedback);
+			}
+			if (feedback !== void 0) {
+				if (feedback.textContent !== message) {
+					feedback.textContent = message;
+					this.#changed = true;
+				}
+				if (feedback.hidden !== (!visible || message === "")) {
+					feedback.hidden = !visible || message === "";
+					this.#changed = true;
+				}
+			}
+			for (const control of group) {
+				if (message !== "" && !control.validity.customError) {
+					this.#validity.set(control, {
+						original: "",
+						value: message
+					});
+					control.setCustomValidity(message);
+				}
+				this.#attribute(control, "aria-invalid", visible && message !== "" ? "true" : null);
+				if (feedback !== void 0) this.#description(control, feedback.id, visible && message !== "");
+			}
+		}
+		this.#paintSummary(errors.filter((error) => this.#document.touched.has(error.field) && !this.#document.disabled.has(error.field)));
+		for (const control of Array.from(this.#element.elements)) if (control instanceof HTMLButtonElement && control.type === "submit" || control instanceof HTMLInputElement && ["submit", "image"].includes(control.type)) this.#attribute(control, "aria-busy", this.#document.pending === void 0 ? "false" : "true");
+	}
+	#metadata(field, control) {
+		if (this.#logical.has(field.name)) this.#attribute(control, "disabled", "");
+		else this.#releaseAttribute(control, "disabled");
+		if (field.locked && !(control instanceof HTMLSelectElement) && !(control instanceof HTMLInputElement && [
+			"radio",
+			"checkbox",
+			"file",
+			"range",
+			"color"
+		].includes(control.type))) this.#attribute(control, "readonly", "");
+		if (field.rule?.required && ![
+			"confirm",
+			"checkbox",
+			"file"
+		].includes(field.control)) this.#attribute(control, "required", "");
+		if (field.control === "number" || field.control === "date" || field.control === "time" || field.control === "datetime") {
+			if (field.rule?.minimum !== void 0 && !control.hasAttribute("min")) this.#attribute(control, "min", String(field.rule.minimum));
+			if (field.rule?.maximum !== void 0 && !control.hasAttribute("max")) this.#attribute(control, "max", String(field.rule.maximum));
+			if (field.control === "number" && field.rule?.step !== void 0 && !control.hasAttribute("step")) this.#attribute(control, "step", String(field.rule.step));
+		}
+	}
+	#value(field, control, value) {
+		if (control instanceof HTMLInputElement && control.type === "file") {
+			const names = Array.from(control.files ?? [], (file) => file.name);
+			if (names.length > 0 && (value === void 0 || !matchesValue(names, value))) {
+				control.value = "";
+				this.#changed = true;
+			}
+			return;
+		}
+		if (control instanceof HTMLInputElement && (control.type === "checkbox" || control.type === "radio")) {
+			const checked = field.control === "confirm" ? value === true : Array.isArray(value) ? value.includes(control.value) : value === control.value;
+			if (control.checked !== checked) {
+				control.checked = checked;
+				this.#changed = true;
+			}
+		} else if (control instanceof HTMLSelectElement && control.multiple) for (const option of Array.from(control.options)) {
+			const selected = Array.isArray(value) && value.includes(option.value);
+			if (option.selected !== selected) {
+				option.selected = selected;
+				this.#changed = true;
+			}
+		}
+		else {
+			const text = value === void 0 ? "" : String(value);
+			if (control.value !== text || control instanceof HTMLInputElement && control.validity.badInput) {
+				const before = control.value;
+				const invalid = control.validity.badInput;
+				control.value = text;
+				if (control.value !== before || invalid) this.#changed = true;
+			}
+		}
+	}
+	#attribute(element, name, value) {
+		const attributes = this.#attributes.get(element) ?? /* @__PURE__ */ new Map();
+		const previous = attributes.get(name);
+		const current = element.getAttribute(name);
+		const original = previous === void 0 || previous.value !== current ? current : previous.original;
+		if (current !== value) {
+			if (value === null) element.removeAttribute(name);
+			else element.setAttribute(name, value);
+			this.#changed = true;
+		}
+		attributes.set(name, {
+			original,
+			value
+		});
+		this.#attributes.set(element, attributes);
+	}
+	#description(control, id, shown) {
+		const tokens = (control.getAttribute("aria-describedby") ?? "").split(/\s+/).filter((token) => token !== "" && token !== id);
+		if (shown) tokens.push(id);
+		this.#attribute(control, "aria-describedby", tokens.length === 0 ? null : tokens.join(" "));
+	}
+	#releaseAttribute(element, name) {
+		const attributes = this.#attributes.get(element);
+		const owned = attributes?.get(name);
+		if (owned === void 0) return;
+		if (element.getAttribute(name) === owned.value) {
+			if (owned.original === null) element.removeAttribute(name);
+			else element.setAttribute(name, owned.original);
+			this.#changed = true;
+		}
+		attributes?.delete(name);
+	}
+	#restore(element) {
+		for (const name of this.#attributes.get(element)?.keys() ?? []) this.#releaseAttribute(element, name);
+		const ids = new Set([...this.#feedback.values()].map((feedback) => feedback.id));
+		const description = element.getAttribute("aria-describedby");
+		if (description !== null) {
+			const tokens = description.split(/\s+/).filter((token) => token !== "" && !ids.has(token));
+			if (tokens.length === 0) element.removeAttribute("aria-describedby");
+			else if (tokens.join(" ") !== description) element.setAttribute("aria-describedby", tokens.join(" "));
+		}
+		this.#attributes.delete(element);
+	}
+	#restoreValidity(control) {
+		const owned = this.#validity.get(control);
+		if (owned !== void 0 && control.validity.customError && control.validationMessage === owned.value) control.setCustomValidity(owned.original);
+		this.#validity.delete(control);
+	}
+	#releaseRemoved() {
+		const live = new Set([...this.#controls.values()].flat());
+		for (const [control, name] of this.#names) if (!live.has(control) || control.name !== name) {
+			this.#restoreValidity(control);
+			this.#restore(control);
+			this.#names.delete(control);
+		}
+		for (const control of live) this.#names.set(control, control.name);
+		for (const element of this.#attributes.keys()) if ((isFormControl(element) || element instanceof HTMLButtonElement) && element.form !== this.#element) this.#restore(element);
+		for (const [name, feedback] of this.#feedback) if (!this.#controls.has(name) && !this.#options?.feedback?.has(name)) {
+			feedback.remove();
+			this.#feedback.delete(name);
+		}
+	}
+	#paintSummary(errors) {
+		const destination = this.#options?.summary;
+		if (destination === void 0) return;
+		const text = JSON.stringify(errors.map((error) => [
+			error.field,
+			error.message,
+			this.#focusable(error.field)?.id
+		]));
+		if (text === this.#summaryText) return;
+		this.#summaryText = text;
+		this.#changed = true;
+		this.#summary?.remove();
+		this.#summary = this.#element.ownerDocument.createElement("ul");
+		this.#summary.dataset.formSummary = "";
+		this.#summary.hidden = errors.length === 0;
+		for (const error of errors) {
+			const entry = this.#element.ownerDocument.createElement("li");
+			const target = this.#focusable(error.field);
+			const label = this.#document.field(error.field)?.label ?? error.field;
+			if (target === void 0) entry.textContent = `${label}: ${error.message}`;
+			else {
+				if (target.id === "") this.#attribute(target, "id", `form-control-${crypto.randomUUID()}`);
+				const link = this.#element.ownerDocument.createElement("a");
+				link.href = `#${target.id}`;
+				link.textContent = `${label}: ${error.message}`;
+				link.dataset.formField = error.field;
+				entry.append(link);
+			}
+			this.#summary.append(entry);
+		}
+		destination.append(this.#summary);
+	}
+	#focusable(name) {
+		return this.#controls.get(name)?.find((control) => !control.matches(":disabled") && control.closest("[inert]") === null && control.getClientRects().length > 0 && !["hidden", "collapse"].includes(getComputedStyle(control).visibility) && !(control instanceof HTMLInputElement && control.type === "hidden"));
+	}
+	#onDocument() {
+		if (this.#destroyed) return;
+		try {
+			this.#drain();
+		} catch (error) {
+			this.#emitter.emit("error", error);
+		}
+	}
+	#onFill(name) {
+		this.#unreadable.delete(name);
+		this.#onState();
+	}
+	#onState() {
+		this.#notified = false;
+		this.#onDocument();
+	}
+	#onDisable(name) {
+		if (this.#excluding !== name) this.#logical.add(name);
+		this.#onState();
+	}
+	#onEnable(name) {
+		if (this.#excluding !== name) {
+			this.#logical.delete(name);
+			this.#excluded.delete(name);
+		}
+		this.#onState();
+	}
+	#onClear() {
+		this.#logical.clear();
+		this.#excluded.clear();
+		this.#unreadable.clear();
+		for (const name of this.#document.disabled) this.#logical.add(name);
+		this.#onState();
+	}
+	#onInput(event) {
+		const control = event.target;
+		if (!isFormControl(control) || control.form !== this.#element || !this.#document.field(control.name) || this.#destroyed) return;
+		try {
+			this.read();
+		} catch (error) {
+			this.#emitter.emit("error", error);
+		}
+	}
+	#onClick(event) {
+		const control = event.target;
+		if (control instanceof Element) {
+			const link = control.closest("a[data-form-field]");
+			if (link instanceof HTMLAnchorElement && this.#summary?.contains(link) && link.dataset.formField !== void 0) {
+				event.preventDefault();
+				this.#focusable(link.dataset.formField)?.focus();
+			}
+		}
+		if (control instanceof HTMLInputElement && control.form === this.#element && this.#document.field(control.name)?.locked && [
+			"file",
+			"checkbox",
+			"radio",
+			"color"
+		].includes(control.type)) event.preventDefault();
+	}
+	#onBlur(event) {
+		const control = event.target;
+		if (!isFormControl(control) || control.form !== this.#element || !this.#document.field(control.name) || this.#destroyed || this.#document.status !== "editing") return;
+		try {
+			this.#document.touch(control.name);
+			this.#drain();
+		} catch (error) {
+			this.#emitter.emit("error", error);
+		}
+	}
+	#onSubmit(event) {
+		if (event.defaultPrevented || this.#destroyed) return;
+		event.preventDefault();
+		if (this.#submitting || this.#document.pending !== void 0) {
+			this.#emitter.emit("error", new FormBindingError("PENDING", "A submission is already pending"));
+			return;
+		}
+		this.#submitting = true;
+		try {
+			this.read();
+			if (this.#destroyed) return;
+			for (const field of this.#document.schema.fields) {
+				if (!this.#document.disabled.has(field.name)) this.#document.touch(field.name);
+				if (this.#destroyed) return;
+			}
+			this.#drain();
+			const native = [...this.#controls].filter(([name, controls]) => !this.#document.disabled.has(name) && controls.some((control) => control.willValidate && !control.validity.valid));
+			if (native.length > 0) {
+				for (const [name] of native) {
+					const target = this.#focusable(name);
+					if (target !== void 0) {
+						target.focus();
+						break;
+					}
+				}
+				return;
+			}
+			const result = this.#document.prepare();
+			if (this.#destroyed) return;
+			this.#drain();
+			if (result.success) {
+				if (!result.value.signal.aborted && this.#document.pending === result.value) this.#emitter.emit("submit", result.value, event.submitter ?? void 0);
+			} else for (const error of result.error) {
+				const target = this.#focusable(error.field);
+				if (target !== void 0) {
+					target.focus();
+					break;
+				}
+			}
+		} catch (error) {
+			this.#emitter.emit("error", error);
+		} finally {
+			this.#submitting = false;
+		}
+	}
+	#onReset(event) {
+		if (event.defaultPrevented || this.#destroyed) return;
+		event.preventDefault();
+		try {
+			this.#document.clear();
+			this.refresh();
+		} catch (error) {
+			this.#emitter.emit("error", error);
+		}
+	}
+};
+//#endregion
+//#region src/browser/factories.ts
+/**
+* Creates a native form binding exposed through its lifecycle interface.
+* @param element - The native form.
+* @param document - The borrowed answer document.
+* @param options - Feedback destinations and listeners.
+* @returns The initialized native binding.
+* @example
+* ```ts
+* const binding = createFormBinding(element, document)
+* binding.refresh()
+* ```
+*/
+function createFormBinding(element, document, options) {
+	return new FormBinding(element, document, options);
+}
+//#endregion
+export { FormBinding, FormBindingError, createFormBinding, isFormBindingError, isFormControl, matchesFormControls, readFormControls };
+
+//# sourceMappingURL=index.js.map