@orkestrel/form 0.0.11 → 0.0.12

package/README.md

@@ -72,6 +72,11 @@ binding in ESM. Both include declarations. The binding supports password reveal,
 without duplicate native feedback, presented-control write notifications and touch, and optional
 blur deferral through footer presses. See [Native binding](./guides/form.md#native-binding).
 
+Use `control: 'list'` for free-text tags or recipient arrays. Its `required` rule requires an entry,
+`minimum` and `maximum` count entries, and `email: true` checks each address. Bind it to a native
+`select multiple` for repeated FormData values and authored-option reset. See
+[List fields](./guides/form.md#list).
+
 ## Development
 
 ```sh

package/dist/src/browser/index.d.ts

@@ -126,11 +126,12 @@ declare interface FieldError {
  * `minimum` and `maximum` measure whatever the control makes countable: characters for
  * `text`, `editor`, and `password`; magnitude for `number`; chronology for `date`, `time`,
  * and `datetime`, whose operand is a string written in that control's own format; and the
- * number of selections for `checkbox` and `file`.
+ * number of entries for `checkbox`, `list`, and `file`.
  *
  * `step` is the interval a numeric value must land on. `pattern` is regular-expression
  * source. `email`, `url`, `integer`, and `alphanumeric` each assert one shape over the whole
- * value. `custom` runs last and is the only rule that sees the rest of the form.
+ * value, or each entry of a `list`. `required` requires an entry for `list` and presence
+ * for other controls. `custom` runs last and is the only rule that sees the rest of the form.
  *
  * @example
  * ```ts
@@ -189,7 +190,7 @@ declare type FieldValidator = (value: FieldValue | undefined, values: FormValues
  *
  * @remarks
  * The variant follows the control: text-like controls hold a `string`, `number` holds a
- * `number`, `confirm` holds a `boolean`, and `checkbox` holds its checked values as a
+ * `number`, `confirm` holds a `boolean`, and `checkbox`, `list`, and `file` hold a
  * `readonly string[]`.
  */
 declare type FieldValue = string | number | boolean | readonly string[];
@@ -283,7 +284,7 @@ export declare interface FormBindingInterface {
 export declare interface FormBindingOptions {
     readonly feedback?: ReadonlyMap<string, HTMLElement>;
     readonly summary?: HTMLElement;
-    /** Maps native controls to focus targets whose departure touches the represented field. */
+    /** Maps native controls to feedback and summary focus targets whose departure touches the field. */
     readonly presentations?: ReadonlyMap<FormControl, HTMLElement>;
     /** Defers blur touch until a same-form button's primary pointer press finishes. Default: false. */
     readonly defer?: boolean;
@@ -339,7 +340,7 @@ declare type FormEventMap = {
  * }
  * ```
  */
-declare type FormField = TextField | EditorField | PasswordField | NumberField | DateField | TimeField | DatetimeField | ColorField | ConfirmField | SelectField | CheckboxField | FileField;
+declare type FormField = TextField | EditorField | PasswordField | NumberField | DateField | TimeField | DatetimeField | ColorField | ConfirmField | SelectField | CheckboxField | ListField | FileField;
 
 /**
  * Represents a named section of a form.
@@ -656,6 +657,26 @@ export declare function isFormBindingError(value: unknown): value is FormBinding
  */
 export declare function isFormControl(value: unknown): value is FormControl;
 
+/**
+ * Represents an ordered list of free-text strings.
+ *
+ * @remarks
+ * `required` requires at least one entry. `minimum` and `maximum` count entries.
+ * `pattern`, `email`, `url`, `integer`, and `alphanumeric` check each entry and name
+ * the failing value in its message. `custom` checks the whole list. Duplicates are retained.
+ *
+ * @example
+ * ```ts
+ * const to: ListField = {
+ * 	control: 'list', name: 'to', rule: { required: true, email: true },
+ * }
+ * ```
+ */
+declare interface ListField extends FieldBase {
+    readonly control: 'list';
+    readonly default?: readonly string[];
+}
+
 /**
  * Checks a native control population against a field's declared value shape.
  * @param field - The declared field.

package/dist/src/browser/index.js

@@ -42,6 +42,7 @@ Object.freeze([
 	"confirm",
 	"select",
 	"checkbox",
+	"list",
 	"file"
 ]);
 /** Lists the members every field declares, whatever its control. */
@@ -90,6 +91,7 @@ Object.freeze({
 		"choices",
 		"default"
 	]),
+	list: Object.freeze([...FIELD_BASE_KEYS, "default"]),
 	file: Object.freeze([
 		...FIELD_BASE_KEYS,
 		"accept",
@@ -161,6 +163,7 @@ function matchesField(field, 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 "list": return entries !== void 0;
 		case "file": return entries !== void 0 && (field.multiple === true || entries.length <= 1);
 	}
 }
@@ -171,7 +174,7 @@ function matchesField(field, value) {
 * 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.
+* its `required` rule remains presence-only except that `list` requires an entry.
 *
 * @param value - The raw field value, or absence.
 * @returns True if the binding preserves the value as an answer; false otherwise.
@@ -223,7 +226,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 +303,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 +348,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 +542,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 +699,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 +762,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 +805,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 +867,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 +920,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 +1086,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();
 		}
 	}
 };