@orkestrel/form 0.0.11 → 0.0.13

package/dist/src/browser/index.js

@@ -1,4 +1,5 @@
-import { attempt, isArray, isBoolean, isFiniteNumber, isInstance, isString, readArrayEntries } from "@orkestrel/contract";
+import { isInstance } from "@orkestrel/contract";
+import { formatMessage, matchesAnswer, matchesField, matchesValue } from "../core/index.js";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/browser/errors.ts
 /** Reports an incompatible control, overlapping submission, or native DOM failure. */
@@ -30,182 +31,6 @@ var FormBindingError = class extends Error {
 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"
-]);
-/** Holds the default failure copy for every named field rule. */
-var RULE_MESSAGES = 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;
-}
-/**
-* Resolves and interpolates one rule message.
-*
-* @remarks
-* A replacement in `messages` is read first and {@link RULE_MESSAGES} supplies the copy otherwise,
-* and `{limit}` in whichever text wins is replaced with the rule's operand.
-*
-* @param rule - The rule whose message to resolve.
-* @param limit - The optional operand substituted for `{limit}`.
-* @param messages - Optional rule-specific message replacements.
-* @returns The resolved failure text.
-*/
-function formatMessage(rule, limit, messages) {
-	const message = messages?.[rule] ?? RULE_MESSAGES[rule];
-	return limit === void 0 ? message : message.replaceAll("{limit}", String(limit));
-}
 //#endregion
 //#region src/browser/helpers.ts
 /**
@@ -223,7 +48,7 @@ function matchesFormControls(field, controls) {
 	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");
+		if (control instanceof HTMLSelectElement) return controls.length === 1 && (control.multiple ? field.control === "checkbox" || field.control === "list" : field.control === "select");
 		switch (field.control) {
 			case "text": return [
 				"text",
@@ -300,7 +125,8 @@ function readFormControls(field, controls) {
 	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);
+	if (field.control === "list" && first instanceof HTMLSelectElement) value = Array.from(first.selectedOptions).filter((option) => !option.matches(":disabled")).map((option) => option.value);
+	else 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) {
@@ -344,6 +170,8 @@ var FormBinding = class {
 	#unreadable = /* @__PURE__ */ new Set();
 	#names = /* @__PURE__ */ new Map();
 	#readings = /* @__PURE__ */ new Map();
+	#lists = /* @__PURE__ */ new Map();
+	#resets = /* @__PURE__ */ new Map();
 	#deferred = /* @__PURE__ */ new Set();
 	#refresh = this.#onState.bind(this);
 	#fill = this.#onFill.bind(this);
@@ -536,6 +364,8 @@ var FormBinding = class {
 		this.#feedback.clear();
 		this.#names.clear();
 		this.#readings.clear();
+		this.#lists.clear();
+		this.#resets.clear();
 		this.#unreadable.clear();
 		this.#logical.clear();
 		this.#controls = /* @__PURE__ */ new Map();
@@ -691,12 +521,24 @@ var FormBinding = class {
 				}
 				this.#attribute(control, "aria-invalid", visible && message !== "" ? "true" : null);
 				if (feedback !== void 0) this.#description(control, feedback.id, visible && message !== "");
+				const presentation = this.#options?.presentations?.get(control);
+				if (presentation !== void 0) {
+					this.#attribute(presentation, "aria-invalid", visible && message !== "" ? "true" : null);
+					if (feedback !== void 0) this.#description(presentation, 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 (field.control === "list" && control instanceof HTMLSelectElement && !this.#lists.has(control)) {
+			const snapshot = control.cloneNode(true);
+			if (snapshot instanceof HTMLSelectElement) {
+				for (const [index, option] of Array.from(snapshot.options).entries()) option.selected = control.options[index]?.selected ?? false;
+				this.#lists.set(control, snapshot);
+			}
+		}
 		if (this.#logical.has(field.name)) this.#attribute(control, "disabled", "");
 		else this.#releaseAttribute(control, "disabled");
 		if (field.locked && !(control instanceof HTMLSelectElement) && !(control instanceof HTMLInputElement && [
@@ -742,6 +584,32 @@ var FormBinding = class {
 				control.checked = checked;
 				changed = true;
 			}
+		} else if (control instanceof HTMLSelectElement && field.control === "list") {
+			const remaining = Array.from(control.options).filter((option) => !option.matches(":disabled"));
+			const selected = [];
+			for (const entry of Array.isArray(value) ? value : []) {
+				const index = remaining.findIndex((option) => option.value === entry);
+				let option = index < 0 ? void 0 : remaining.splice(index, 1)[0];
+				if (option === void 0) {
+					option = control.ownerDocument.createElement("option");
+					option.value = entry;
+					option.text = entry;
+					control.append(option);
+					changed = true;
+				}
+				if (!option.selected) changed = true;
+				option.selected = true;
+				selected.push(option);
+			}
+			for (const option of remaining) {
+				if (option.selected) changed = true;
+				option.selected = false;
+			}
+			const ordered = Array.from(control.selectedOptions).filter((option) => !option.matches(":disabled"));
+			if (selected.some((option, index) => ordered[index] !== option)) {
+				control.append(...selected);
+				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) {
@@ -759,6 +627,13 @@ var FormBinding = class {
 			}
 		}
 		this.#readings.set(control, control.value);
+		if (control instanceof HTMLSelectElement) {
+			const before = this.#resets.get(control);
+			if (before !== void 0) {
+				this.#resets.delete(control);
+				changed = !matchesValue(before, Array.from(control.selectedOptions, (option) => option.value));
+			}
+		}
 		if (changed) {
 			this.#changed = true;
 			this.#emitter.emit("write", control);
@@ -814,14 +689,21 @@ var FormBinding = class {
 	}
 	#releaseRemoved() {
 		const live = new Set([...this.#controls.values()].flat());
+		const presentations = new Set([...live].map((control) => this.#options?.presentations?.get(control)));
 		for (const [control, name] of this.#names) if (!live.has(control) || control.name !== name) {
+			if (control instanceof HTMLSelectElement) {
+				this.#lists.delete(control);
+				this.#resets.delete(control);
+			}
+			const presentation = this.#options?.presentations?.get(control);
+			if (presentation !== void 0) this.#restore(presentation);
 			this.#restoreValidity(control);
 			this.#restore(control);
 			this.#names.delete(control);
 			this.#readings.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 element of this.#attributes.keys()) if (!presentations.has(element) && (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);
@@ -860,7 +742,7 @@ var FormBinding = class {
 		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"));
+		return this.#controls.get(name)?.filter((control) => !control.matches(":disabled")).map((control) => this.#options?.presentations?.get(control) ?? control)?.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(preserve = false) {
 		if (this.#destroyed) return;
@@ -1026,10 +908,30 @@ var FormBinding = class {
 		if (event.defaultPrevented || this.#destroyed) return;
 		event.preventDefault();
 		try {
-			this.#document.clear();
+			const lists = /* @__PURE__ */ new Map();
+			for (const [control, snapshot] of this.#lists) if (control.form === this.#element && control.name === snapshot.name && this.#document.field(control.name)?.control === "list") {
+				lists.set(control, snapshot);
+				this.#resets.set(control, Array.from(control.selectedOptions, (option) => option.value));
+			}
+			this.#reading = true;
+			try {
+				this.#document.clear();
+				for (const [control, snapshot] of lists) {
+					if (this.#destroyed) return;
+					if (control.form !== this.#element || control.name !== snapshot.name) continue;
+					control.replaceChildren(...Array.from(snapshot.childNodes, (node) => node.cloneNode(true)));
+					for (const [index, option] of Array.from(control.options).entries()) option.selected = snapshot.options[index]?.selected ?? false;
+					const field = this.#document.field(control.name);
+					if (field !== void 0) this.#document.fill(field.name, readFormControls(field, [control]));
+				}
+			} finally {
+				this.#reading = false;
+			}
 			this.refresh();
 		} catch (error) {
 			this.#emitter.emit("error", error);
+		} finally {
+			this.#resets.clear();
 		}
 	}
 };