@orkestrel/form 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,1704 @@
+import { arrayOf, attempt, cloneJSONRecord, isArray, isBoolean, isBoundedJSONRecord, isContractError, isFiniteNumber, isFunction, isInteger, isRecord, isString, literalOf, parseNumber, readArrayEntries, recordOf, unionOf } from "@orkestrel/contract";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/core/constants.ts
+/** Every field control, in the order declared by the public contract. */
+var FIELD_CONTROLS = Object.freeze([
+	"text",
+	"editor",
+	"password",
+	"number",
+	"date",
+	"time",
+	"datetime",
+	"color",
+	"confirm",
+	"select",
+	"checkbox",
+	"file"
+]);
+/** Every form lifecycle status. */
+var FORM_STATUSES = Object.freeze([
+	"editing",
+	"settled",
+	"abandoned"
+]);
+/** 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"
+});
+/** A practical whole-address email shape. */
+var EMAIL_PATTERN = Object.freeze(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);
+/** An absolute HTTP or HTTPS URL shape. */
+var URL_PATTERN = Object.freeze(/^https?:\/\/[^\s]+$/);
+/** One or more ASCII letters or digits. */
+var ALPHANUMERIC_PATTERN = Object.freeze(/^[A-Za-z0-9]+$/);
+/** A signed or unsigned base-ten integer string. */
+var INTEGER_PATTERN = Object.freeze(/^[+-]?\d+$/);
+/** A six-digit hexadecimal color string. */
+var COLOR_PATTERN = Object.freeze(/^#[0-9A-Fa-f]{6}$/);
+/** 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])$/);
+/** A 24-hour time string with optional seconds. */
+var TIME_PATTERN = Object.freeze(/^(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d)?$/);
+/** 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)?$/);
+/** The maximum accepted source length for an authored regular expression. */
+var PATTERN_LIMIT = 256;
+/** The maximum number of fields one schema may declare. */
+var FIELD_LIMIT = 512;
+/** The maximum number of groups one schema may declare. */
+var GROUP_LIMIT = 64;
+/** The maximum number of choices one `select` or `checkbox` field may offer. */
+var CHOICE_LIMIT = 1024;
+/** The maximum number of entries one list-valued answer may hold. */
+var LIST_LIMIT = 1024;
+/** The maximum length, in UTF-16 code units, of a schema, group, or field name. */
+var NAME_LIMIT = 128;
+/** The maximum length, in UTF-16 code units, of any single retained string. */
+var STRING_LIMIT = 65536;
+/** The maximum total length, in UTF-16 code units, of every string one schema retains. */
+var TEXT_LIMIT = 1048576;
+/** The maximum total number of records, arrays, and leaves one schema retains. */
+var NODE_LIMIT = 16384;
+//#endregion
+//#region src/core/errors.ts
+/** An error raised by the form domain. */
+var FormError = class extends Error {
+	/** The machine-readable reason for this failure. */
+	code;
+	/** Structured values that locate or explain this failure. */
+	context;
+	/**
+	* Create a form error.
+	*
+	* @param code - The machine-readable reason.
+	* @param message - The human-readable failure text.
+	* @param context - Optional structured failure details.
+	*/
+	constructor(code, message, context) {
+		super(message);
+		this.name = "FormError";
+		this.code = code;
+		if (context !== void 0) this.context = context;
+	}
+};
+/**
+* Determine whether an unknown value is a form error.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a {@link FormError} instance.
+*/
+function isFormError(input) {
+	return input instanceof FormError;
+}
+//#endregion
+//#region src/core/validators.ts
+/**
+* Determine whether an unknown value is a declared field control.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a field control.
+*/
+function isFieldControl(input) {
+	return FIELD_CONTROLS.some((control) => control === input);
+}
+/**
+* Determine whether an unknown value is a form lifecycle status.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a form status.
+*/
+function isFormStatus(input) {
+	return FORM_STATUSES.some((status) => status === input);
+}
+/**
+* Determine whether an unknown value has a form field value shape.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a field value.
+*/
+function isFieldValue(input) {
+	return unionOf(isString, isFiniteNumber, isBoolean, arrayOf(isString))(input);
+}
+/**
+* Determine whether an unknown value is one exact field choice record.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a field choice.
+*/
+function isFieldChoice(input) {
+	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
+	if (!keys.success || !keys.value) return false;
+	return recordOf({
+		value: isString,
+		label: isString,
+		help: isString,
+		disabled: isBoolean
+	}, ["help", "disabled"])(input);
+}
+/**
+* Determine whether an unknown value is one exact field rule record.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a structurally valid field rule.
+*/
+function isFieldRule(input) {
+	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
+	if (!keys.success || !keys.value) return false;
+	return recordOf({
+		required: isBoolean,
+		minimum: unionOf(isFiniteNumber, isString),
+		maximum: unionOf(isFiniteNumber, isString),
+		step: isFiniteNumber,
+		pattern: isString,
+		email: isBoolean,
+		url: isBoolean,
+		integer: isBoolean,
+		alphanumeric: isBoolean,
+		custom: isFunction
+	}, true)(input);
+}
+/**
+* Determine whether an unknown value is one exact discriminated form field.
+*
+* @remarks
+* Metadata is admitted structurally as bounded JSON. An accessor-bearing metadata record is
+* refused later when {@link cloneFormField} takes ownership, because ownership accepts enumerable
+* data properties only.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a structurally valid form field.
+*/
+function isFormField(input) {
+	const outcome = attempt(() => {
+		if (!isRecord(input) || !Object.hasOwn(input, "control") || !Object.hasOwn(input, "name")) return false;
+		const control = input.control;
+		if (!isFieldControl(control)) return false;
+		if (!Reflect.ownKeys(input).every((key) => {
+			if (!isString(key)) return false;
+			switch (control) {
+				case "text":
+				case "editor": return [
+					"control",
+					"name",
+					"label",
+					"help",
+					"group",
+					"hidden",
+					"disabled",
+					"locked",
+					"rule",
+					"meta",
+					"default",
+					"placeholder"
+				].includes(key);
+				case "password": return [
+					"control",
+					"name",
+					"label",
+					"help",
+					"group",
+					"hidden",
+					"disabled",
+					"locked",
+					"rule",
+					"meta",
+					"mask"
+				].includes(key);
+				case "number": return [
+					"control",
+					"name",
+					"label",
+					"help",
+					"group",
+					"hidden",
+					"disabled",
+					"locked",
+					"rule",
+					"meta",
+					"default",
+					"placeholder"
+				].includes(key);
+				case "date":
+				case "time":
+				case "datetime":
+				case "color":
+				case "confirm": return [
+					"control",
+					"name",
+					"label",
+					"help",
+					"group",
+					"hidden",
+					"disabled",
+					"locked",
+					"rule",
+					"meta",
+					"default"
+				].includes(key);
+				case "select": return [
+					"control",
+					"name",
+					"label",
+					"help",
+					"group",
+					"hidden",
+					"disabled",
+					"locked",
+					"rule",
+					"meta",
+					"choices",
+					"default",
+					"open"
+				].includes(key);
+				case "checkbox": return [
+					"control",
+					"name",
+					"label",
+					"help",
+					"group",
+					"hidden",
+					"disabled",
+					"locked",
+					"rule",
+					"meta",
+					"choices",
+					"default"
+				].includes(key);
+				case "file": return [
+					"control",
+					"name",
+					"label",
+					"help",
+					"group",
+					"hidden",
+					"disabled",
+					"locked",
+					"rule",
+					"meta",
+					"accept",
+					"multiple"
+				].includes(key);
+			}
+		})) return false;
+		const name = input.name;
+		const hasLabel = Object.hasOwn(input, "label");
+		const label = hasLabel ? input.label : void 0;
+		const hasHelp = Object.hasOwn(input, "help");
+		const help = hasHelp ? input.help : void 0;
+		const hasGroup = Object.hasOwn(input, "group");
+		const group = hasGroup ? input.group : void 0;
+		const hasHidden = Object.hasOwn(input, "hidden");
+		const hidden = hasHidden ? input.hidden : void 0;
+		const hasDisabled = Object.hasOwn(input, "disabled");
+		const disabled = hasDisabled ? input.disabled : void 0;
+		const hasLocked = Object.hasOwn(input, "locked");
+		const locked = hasLocked ? input.locked : void 0;
+		const hasRule = Object.hasOwn(input, "rule");
+		const rule = hasRule ? input.rule : void 0;
+		const hasMeta = Object.hasOwn(input, "meta");
+		const meta = hasMeta ? input.meta : void 0;
+		if (!isString(name) || hasLabel && !isString(label) || hasHelp && !isString(help) || hasGroup && !isString(group) || hasHidden && !isBoolean(hidden) || hasDisabled && !isBoolean(disabled) || hasLocked && !isBoolean(locked) || hasRule && !isFieldRule(rule) || hasMeta && !isBoundedJSONRecord(meta)) return false;
+		switch (control) {
+			case "text":
+			case "editor": {
+				const hasDefault = Object.hasOwn(input, "default");
+				const fallback = hasDefault ? input.default : void 0;
+				const hasPlaceholder = Object.hasOwn(input, "placeholder");
+				const placeholder = hasPlaceholder ? input.placeholder : void 0;
+				return (!hasDefault || isString(fallback)) && (!hasPlaceholder || isString(placeholder));
+			}
+			case "password": {
+				const hasMask = Object.hasOwn(input, "mask");
+				const mask = hasMask ? input.mask : void 0;
+				return !hasMask || isString(mask);
+			}
+			case "number": {
+				const hasDefault = Object.hasOwn(input, "default");
+				const fallback = hasDefault ? input.default : void 0;
+				const hasPlaceholder = Object.hasOwn(input, "placeholder");
+				const placeholder = hasPlaceholder ? input.placeholder : void 0;
+				return (!hasDefault || isFiniteNumber(fallback)) && (!hasPlaceholder || isString(placeholder));
+			}
+			case "date":
+			case "time":
+			case "datetime":
+			case "color": {
+				const hasDefault = Object.hasOwn(input, "default");
+				const fallback = hasDefault ? input.default : void 0;
+				return !hasDefault || isString(fallback);
+			}
+			case "confirm": {
+				const hasDefault = Object.hasOwn(input, "default");
+				const fallback = hasDefault ? input.default : void 0;
+				return !hasDefault || isBoolean(fallback);
+			}
+			case "select": {
+				if (!Object.hasOwn(input, "choices")) return false;
+				const choices = input.choices;
+				const hasDefault = Object.hasOwn(input, "default");
+				const fallback = hasDefault ? input.default : void 0;
+				const hasOpen = Object.hasOwn(input, "open");
+				const open = hasOpen ? input.open : void 0;
+				return arrayOf(isFieldChoice)(choices) && (!hasDefault || isString(fallback)) && (!hasOpen || isBoolean(open));
+			}
+			case "checkbox": {
+				if (!Object.hasOwn(input, "choices")) return false;
+				const choices = input.choices;
+				const hasDefault = Object.hasOwn(input, "default");
+				const fallback = hasDefault ? input.default : void 0;
+				return arrayOf(isFieldChoice)(choices) && (!hasDefault || arrayOf(isString)(fallback));
+			}
+			case "file": {
+				const hasAccept = Object.hasOwn(input, "accept");
+				const accept = hasAccept ? input.accept : void 0;
+				const hasMultiple = Object.hasOwn(input, "multiple");
+				const multiple = hasMultiple ? input.multiple : void 0;
+				return (!hasAccept || arrayOf(isString)(accept)) && (!hasMultiple || isBoolean(multiple));
+			}
+		}
+	});
+	return outcome.success && outcome.value;
+}
+/**
+* Determine whether an unknown value is one exact form group record.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a form group.
+*/
+function isFormGroup(input) {
+	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
+	if (!keys.success || !keys.value) return false;
+	return recordOf({
+		name: isString,
+		label: isString,
+		help: isString
+	}, ["help"])(input);
+}
+/**
+* Determine whether an unknown value is one exact structural form schema.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a structurally valid form schema.
+*/
+function isFormSchema(input) {
+	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
+	if (!keys.success || !keys.value) return false;
+	return recordOf({
+		name: isString,
+		label: isString,
+		help: isString,
+		groups: arrayOf(isFormGroup),
+		fields: arrayOf(isFormField)
+	}, [
+		"name",
+		"label",
+		"help",
+		"groups"
+	])(input);
+}
+/**
+* Determine whether an unknown value is a record of field values.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a form values record.
+*/
+function isFormValues(input) {
+	const outcome = attempt(() => {
+		if (!isRecord(input)) return false;
+		return Reflect.ownKeys(input).every((key) => isString(key) && Object.hasOwn(input, key) && isFieldValue(input[key]));
+	});
+	return outcome.success && outcome.value;
+}
+/**
+* Determine whether an unknown value is one exact field error record.
+*
+* @param input - The value to inspect.
+* @returns Whether the value is a field error.
+*/
+function isFieldError(input) {
+	const keys = attempt(() => isRecord(input) && Reflect.ownKeys(input).every((key) => isString(key)));
+	if (!keys.success || !keys.value) return false;
+	return recordOf({
+		field: isString,
+		message: isString,
+		rule: literalOf("required", "minimum", "maximum", "step", "pattern", "email", "url", "integer", "alphanumeric")
+	}, ["rule"])(input);
+}
+//#endregion
+//#region src/core/cloners.ts
+function cloneValue(value) {
+	return isArray(value) ? Object.freeze(value.slice()) : value;
+}
+/**
+* Clone a field's choices into an owned frozen snapshot.
+*
+* @param choices - The choices to own.
+* @returns A frozen list of frozen choice records.
+*/
+function cloneChoices(choices) {
+	return Object.freeze(choices.map((choice) => Object.freeze({ ...choice })));
+}
+/**
+* Clone one form field into an owned frozen snapshot.
+*
+* @param field - The field to own.
+* @returns A frozen field with every nested collection owned.
+* @throws A {@link FormError} coded `SCHEMA` when accessor-bearing metadata cannot be owned.
+*/
+function cloneFormField(field) {
+	const rule = field.rule === void 0 ? {} : { rule: Object.freeze({ ...field.rule }) };
+	let meta = {};
+	if (field.meta !== void 0) try {
+		meta = { meta: cloneJSONRecord(field.meta) };
+	} catch (error) {
+		if (!isContractError(error)) throw error;
+		throw new FormError("SCHEMA", `Field "${field.name}" has metadata that cannot be owned`, { field: field.name });
+	}
+	switch (field.control) {
+		case "select": return Object.freeze({
+			...field,
+			...rule,
+			...meta,
+			choices: cloneChoices(field.choices)
+		});
+		case "checkbox": return Object.freeze({
+			...field,
+			...rule,
+			...meta,
+			choices: cloneChoices(field.choices),
+			...field.default === void 0 ? {} : { default: cloneValue(field.default) }
+		});
+		case "file": return Object.freeze({
+			...field,
+			...rule,
+			...meta,
+			...field.accept === void 0 ? {} : { accept: cloneValue(field.accept) }
+		});
+		case "text":
+		case "editor":
+		case "password":
+		case "number":
+		case "date":
+		case "time":
+		case "datetime":
+		case "color":
+		case "confirm": return Object.freeze({
+			...field,
+			...rule,
+			...meta
+		});
+	}
+}
+/**
+* Clone a form schema into an owned frozen snapshot.
+*
+* @param schema - The schema to own.
+* @returns A frozen schema with every nested record and list owned.
+*/
+function cloneFormSchema(schema) {
+	const groups = schema.groups;
+	return Object.freeze({
+		...schema,
+		...groups === void 0 ? {} : { groups: Object.freeze(groups.map((group) => Object.freeze({ ...group }))) },
+		fields: Object.freeze(schema.fields.map((field) => cloneFormField(field)))
+	});
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Check whether a value has the shape required by one field control.
+*
+* @param field - The field that owns the value.
+* @param value - The unknown value to inspect.
+* @returns Whether the control can hold the value.
+*/
+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);
+	}
+}
+/**
+* Decide 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 Whether the binding should preserve the value as an answer.
+*/
+function matchesAnswer(value) {
+	return value !== void 0 && (!isString(value) || value.trim().length > 0);
+}
+/**
+* Check whether a named rule applies to one field control.
+*
+* @remarks
+* The runtime control-membership check keeps this boundary total for JavaScript callers that
+* bypass the declared {@link FieldControl} contract.
+*
+* @param control - The field control to inspect.
+* @param rule - The named rule to inspect.
+* @returns Whether the control evaluates that rule.
+*/
+function appliesRule(control, rule) {
+	if (!FIELD_CONTROLS.some((candidate) => candidate === control)) return false;
+	switch (rule) {
+		case "required": return true;
+		case "minimum":
+		case "maximum": return control !== "color" && control !== "confirm" && control !== "select";
+		case "step": return control === "number";
+		case "pattern":
+		case "email":
+		case "url":
+		case "alphanumeric": return control !== "number" && control !== "confirm" && control !== "checkbox" && control !== "file";
+		case "integer": return control !== "confirm" && control !== "checkbox" && control !== "file";
+	}
+	return false;
+}
+/**
+* Evaluate one field rule against its current value.
+*
+* @param field - The field and rule to evaluate.
+* @param value - The current value, or absence.
+* @param values - Every value available to a custom rule.
+* @param messages - Optional rule-specific message replacements.
+* @returns Every failure in rule order.
+*/
+function evaluateField(field, value, values, messages) {
+	const errors = [];
+	const rule = field.rule;
+	if (value === void 0) {
+		if (rule?.required === true && appliesRule(field.control, "required")) errors.push(Object.freeze({
+			field: field.name,
+			message: formatMessage("required", void 0, messages),
+			rule: "required"
+		}));
+	}
+	if (rule === void 0) return Object.freeze(errors);
+	if (rule.minimum !== void 0 && appliesRule(field.control, "minimum")) {
+		let failed = false;
+		switch (field.control) {
+			case "text":
+			case "editor":
+			case "password":
+				failed = isString(value) && isFiniteNumber(rule.minimum) && value.length < rule.minimum;
+				break;
+			case "number":
+				failed = isFiniteNumber(value) && isFiniteNumber(rule.minimum) && value < rule.minimum;
+				break;
+			case "date":
+			case "time":
+			case "datetime":
+				failed = isString(value) && isString(rule.minimum) && value < rule.minimum;
+				break;
+			case "checkbox":
+			case "file": failed = isArray(value) && isFiniteNumber(rule.minimum) && value.length < rule.minimum;
+		}
+		if (failed) errors.push(Object.freeze({
+			field: field.name,
+			message: formatMessage("minimum", rule.minimum, messages),
+			rule: "minimum"
+		}));
+	}
+	if (rule.maximum !== void 0 && appliesRule(field.control, "maximum")) {
+		let failed = false;
+		switch (field.control) {
+			case "text":
+			case "editor":
+			case "password":
+				failed = isString(value) && isFiniteNumber(rule.maximum) && value.length > rule.maximum;
+				break;
+			case "number":
+				failed = isFiniteNumber(value) && isFiniteNumber(rule.maximum) && value > rule.maximum;
+				break;
+			case "date":
+			case "time":
+			case "datetime":
+				failed = isString(value) && isString(rule.maximum) && value > rule.maximum;
+				break;
+			case "checkbox":
+			case "file": failed = isArray(value) && isFiniteNumber(rule.maximum) && value.length > rule.maximum;
+		}
+		if (failed) errors.push(Object.freeze({
+			field: field.name,
+			message: formatMessage("maximum", rule.maximum, messages),
+			rule: "maximum"
+		}));
+	}
+	if (rule.step !== void 0 && appliesRule(field.control, "step") && isFiniteNumber(value)) {
+		const multiple = (value - (isFiniteNumber(rule.minimum) ? rule.minimum : 0)) / rule.step;
+		if (!isFiniteNumber(rule.step) || rule.step === 0 || !isFiniteNumber(multiple) || Math.abs(multiple - Math.round(multiple)) > 1e-9) errors.push(Object.freeze({
+			field: field.name,
+			message: formatMessage("step", rule.step, messages),
+			rule: "step"
+		}));
+	}
+	if (isString(value)) {
+		if (rule.pattern !== void 0 && appliesRule(field.control, "pattern")) {
+			const pattern = rule.pattern;
+			if (pattern.length > 256) errors.push(Object.freeze({
+				field: field.name,
+				message: formatMessage("pattern", void 0, messages),
+				rule: "pattern"
+			}));
+			else {
+				const outcome = attempt(() => new RegExp(pattern).test(value));
+				if (!outcome.success || !outcome.value) errors.push(Object.freeze({
+					field: field.name,
+					message: formatMessage("pattern", void 0, messages),
+					rule: "pattern"
+				}));
+			}
+		}
+		if (rule.email === true && appliesRule(field.control, "email") && !EMAIL_PATTERN.test(value)) errors.push(Object.freeze({
+			field: field.name,
+			message: formatMessage("email", void 0, messages),
+			rule: "email"
+		}));
+		if (rule.url === true && appliesRule(field.control, "url") && !URL_PATTERN.test(value)) errors.push(Object.freeze({
+			field: field.name,
+			message: formatMessage("url", void 0, messages),
+			rule: "url"
+		}));
+		if (rule.alphanumeric === true && appliesRule(field.control, "alphanumeric") && !ALPHANUMERIC_PATTERN.test(value)) errors.push(Object.freeze({
+			field: field.name,
+			message: formatMessage("alphanumeric", void 0, messages),
+			rule: "alphanumeric"
+		}));
+		if (rule.integer === true && appliesRule(field.control, "integer") && !INTEGER_PATTERN.test(value)) errors.push(Object.freeze({
+			field: field.name,
+			message: formatMessage("integer", void 0, messages),
+			rule: "integer"
+		}));
+	}
+	if (value !== void 0 && field.control === "number" && rule.integer === true && appliesRule(field.control, "integer") && !isInteger(value)) errors.push(Object.freeze({
+		field: field.name,
+		message: formatMessage("integer", void 0, messages),
+		rule: "integer"
+	}));
+	if (rule.custom !== void 0) {
+		const result = rule.custom(value, values);
+		if (isString(result)) errors.push(Object.freeze({
+			field: field.name,
+			message: result
+		}));
+	}
+	return Object.freeze(errors);
+}
+/**
+* Evaluate every active field in schema order.
+*
+* @param schema - The form schema to evaluate.
+* @param values - The values keyed by field name.
+* @param options - Optional message replacements and the effective disabled field set.
+* @returns Every field failure in schema and rule order.
+*/
+function evaluateForm(schema, values, options) {
+	const errors = [];
+	for (const field of schema.fields) if (options?.disabled === void 0 ? field.disabled !== true : !options.disabled.has(field.name)) {
+		const value = Object.hasOwn(values, field.name) ? values[field.name] : void 0;
+		errors.push(...evaluateField(field, value, values, options?.messages));
+	}
+	return Object.freeze(errors);
+}
+/**
+* Compute the values explicitly seeded by a schema.
+*
+* @param schema - The schema whose defaults to collect.
+* @returns A value record containing only fields with defaults.
+*/
+function computeDefaults(schema) {
+	const defaults = {};
+	for (const field of schema.fields) switch (field.control) {
+		case "checkbox":
+			if (field.default !== void 0) Object.defineProperty(defaults, field.name, {
+				value: cloneValue(field.default),
+				enumerable: true,
+				configurable: true,
+				writable: true
+			});
+			break;
+		case "password":
+		case "file": break;
+		case "text":
+		case "editor":
+		case "number":
+		case "date":
+		case "time":
+		case "datetime":
+		case "color":
+		case "confirm":
+		case "select": if (field.default !== void 0) Object.defineProperty(defaults, field.name, {
+			value: field.default,
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+	}
+	return Object.freeze(defaults);
+}
+/**
+* Compare two field values by scalar identity or ordered list content.
+*
+* @param a - The first field value.
+* @param b - The second field value.
+* @returns Whether both values contain the same answer.
+*/
+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;
+}
+/**
+* Extract the names whose answers differ between two form value records.
+*
+* @remarks
+* Presence is compared in both directions before present values are compared through
+* {@link matchesValue}. The returned set is a new snapshot, exposed as readonly because later
+* changes to either input never alter its membership.
+*
+* @param current - The values held now.
+* @param opened - The values held when the form opened.
+* @returns A readonly snapshot of changed field names.
+*/
+function extractChanges(current, opened) {
+	const names = /* @__PURE__ */ new Set([...Object.keys(current), ...Object.keys(opened)]);
+	const changed = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		if (Object.hasOwn(current, name) !== Object.hasOwn(opened, name)) {
+			changed.add(name);
+			continue;
+		}
+		const now = current[name];
+		const before = opened[name];
+		if (now === void 0 || before === void 0 || !matchesValue(now, before)) changed.add(name);
+	}
+	return changed;
+}
+/**
+* Compare two form value records by keys and value content.
+*
+* @param a - The first value record.
+* @param b - The second value record.
+* @returns Whether both records contain the same answers.
+*/
+function matchesValues(a, b) {
+	return extractChanges(a, b).size === 0;
+}
+/**
+* Resolve and interpolate one rule message.
+*
+* @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));
+}
+/**
+* Project a schema into JSON while removing custom validators and absent values.
+*
+* @param schema - The schema to project.
+* @returns A deep JSON copy of the serializable schema.
+* @throws A {@link FormError} coded `SCHEMA` when accessor-bearing metadata cannot be owned. A
+*   non-contract throw while reading metadata escapes unchanged.
+*/
+function serializeForm(schema) {
+	const output = {};
+	if (schema.name !== void 0) output.name = schema.name;
+	if (schema.label !== void 0) output.label = schema.label;
+	if (schema.help !== void 0) output.help = schema.help;
+	if (schema.groups !== void 0) output.groups = schema.groups.map((group) => {
+		const entry = {
+			name: group.name,
+			label: group.label
+		};
+		if (group.help !== void 0) entry.help = group.help;
+		return entry;
+	});
+	output.fields = schema.fields.map((field) => {
+		const entry = {
+			control: field.control,
+			name: field.name
+		};
+		if (field.label !== void 0) entry.label = field.label;
+		if (field.help !== void 0) entry.help = field.help;
+		if (field.group !== void 0) entry.group = field.group;
+		if (field.hidden !== void 0) entry.hidden = field.hidden;
+		if (field.disabled !== void 0) entry.disabled = field.disabled;
+		if (field.locked !== void 0) entry.locked = field.locked;
+		const meta = field.meta;
+		if (meta !== void 0) try {
+			entry.meta = cloneJSONRecord(meta);
+		} catch (error) {
+			if (!isContractError(error)) throw error;
+			throw new FormError("SCHEMA", `Field "${field.name}" has metadata that cannot be owned`, { field: field.name });
+		}
+		switch (field.control) {
+			case "text":
+			case "editor":
+			case "number":
+				if (field.default !== void 0) entry.default = field.default;
+				if (field.placeholder !== void 0) entry.placeholder = field.placeholder;
+				break;
+			case "password":
+				if (field.mask !== void 0) entry.mask = field.mask;
+				break;
+			case "date":
+			case "time":
+			case "datetime":
+			case "color":
+			case "confirm":
+				if (field.default !== void 0) entry.default = field.default;
+				break;
+			case "select":
+				entry.choices = field.choices.map((choice) => {
+					const option = {
+						value: choice.value,
+						label: choice.label
+					};
+					if (choice.help !== void 0) option.help = choice.help;
+					if (choice.disabled !== void 0) option.disabled = choice.disabled;
+					return option;
+				});
+				if (field.default !== void 0) entry.default = field.default;
+				if (field.open !== void 0) entry.open = field.open;
+				break;
+			case "checkbox":
+				entry.choices = field.choices.map((choice) => {
+					const option = {
+						value: choice.value,
+						label: choice.label
+					};
+					if (choice.help !== void 0) option.help = choice.help;
+					if (choice.disabled !== void 0) option.disabled = choice.disabled;
+					return option;
+				});
+				if (field.default !== void 0) entry.default = field.default;
+				break;
+			case "file":
+				if (field.accept !== void 0) entry.accept = field.accept;
+				if (field.multiple !== void 0) entry.multiple = field.multiple;
+		}
+		if (field.rule !== void 0) {
+			const rule = {};
+			if (field.rule.required !== void 0) rule.required = field.rule.required;
+			if (field.rule.minimum !== void 0) rule.minimum = field.rule.minimum;
+			if (field.rule.maximum !== void 0) rule.maximum = field.rule.maximum;
+			if (field.rule.step !== void 0) rule.step = field.rule.step;
+			if (field.rule.pattern !== void 0) rule.pattern = field.rule.pattern;
+			if (field.rule.email !== void 0) rule.email = field.rule.email;
+			if (field.rule.url !== void 0) rule.url = field.rule.url;
+			if (field.rule.integer !== void 0) rule.integer = field.rule.integer;
+			if (field.rule.alphanumeric !== void 0) rule.alphanumeric = field.rule.alphanumeric;
+			if (Object.keys(rule).length > 0) entry.rule = rule;
+		}
+		return entry;
+	});
+	return cloneJSONRecord(output);
+}
+/**
+* Select referenced groups in first-reference field order.
+*
+* @param schema - The schema whose group references to resolve.
+* @returns The referenced schema groups without duplicates.
+*/
+function extractGroups(schema) {
+	const groups = [];
+	if (schema.groups === void 0) return Object.freeze(groups);
+	for (const field of schema.fields) if (field.group !== void 0 && !groups.some((group) => group.name === field.group)) {
+		const group = schema.groups.find((entry) => entry.name === field.group);
+		if (group !== void 0) groups.push(group);
+	}
+	return Object.freeze(groups);
+}
+/**
+* Audit a structurally valid schema for domain invariants.
+*
+* @param schema - The form schema to audit.
+* @returns Human-readable invariant violations, or an empty list when the schema is sound.
+*/
+function auditSchema(schema) {
+	const faults = [];
+	const fields = /* @__PURE__ */ new Set();
+	const groups = /* @__PURE__ */ new Set();
+	let choiceExceeded;
+	let nameExceeded = schema.name !== void 0 && schema.name.length > 128;
+	if (schema.fields.length > 512) faults.push(`Schema declares more than 512 fields`);
+	if (schema.groups !== void 0 && schema.groups.length > 64) faults.push(`Schema declares more than 64 groups`);
+	if (schema.groups !== void 0) {
+		const count = Math.min(schema.groups.length, 65);
+		for (let index = 0; index < count; index += 1) {
+			const group = schema.groups[index];
+			if (group !== void 0 && group.name.length > 128) nameExceeded = true;
+		}
+	}
+	const fieldCount = Math.min(schema.fields.length, 513);
+	for (let index = 0; index < fieldCount; index += 1) {
+		const field = schema.fields[index];
+		if (field === void 0) continue;
+		if (field.name.length > 128 || field.group !== void 0 && field.group.length > 128) nameExceeded = true;
+		if (choiceExceeded === void 0 && (field.control === "select" || field.control === "checkbox") && field.choices.length > 1024) choiceExceeded = field.name;
+	}
+	if (choiceExceeded !== void 0) faults.push(`Field "${choiceExceeded}" offers more than ${CHOICE_LIMIT} choices`);
+	if (nameExceeded) faults.push(`Schema contains a name longer than 128`);
+	const pending = [schema];
+	const metadata = [false];
+	let position = 0;
+	let stringExceeded = false;
+	let textExceeded = false;
+	let nodeExceeded = false;
+	let text = 0;
+	while (position < pending.length) {
+		const node = pending[position];
+		const inMeta = metadata[position] === true;
+		position += 1;
+		if (isString(node)) {
+			if (node.length > 65536) stringExceeded = true;
+			text = Math.min(TEXT_LIMIT + 1, text + node.length);
+			if (text > 1048576) textExceeded = true;
+			continue;
+		}
+		if (isArray(node)) {
+			const length = attempt(() => node.length);
+			if (!length.success || length.value > 16384 - pending.length) {
+				nodeExceeded = true;
+				continue;
+			}
+			const read = readArrayEntries(node);
+			if (!read.success || !read.value.dense) continue;
+			for (let index = 0; index < read.value.entries.length; index += 1) {
+				const entry = read.value.entries[index];
+				if (entry !== void 0) {
+					pending.push(entry);
+					metadata.push(inMeta);
+				}
+			}
+			continue;
+		}
+		if (!isRecord(node)) continue;
+		const keys = attempt(() => Object.keys(node));
+		if (!keys.success) continue;
+		for (const key of keys.value) {
+			if (inMeta) {
+				if (key.length > 65536) stringExceeded = true;
+				text = Math.min(TEXT_LIMIT + 1, text + key.length);
+				if (text > 1048576) textExceeded = true;
+			}
+			const value = attempt(() => node[key]);
+			if (!value.success || value.value === void 0) continue;
+			if (pending.length >= 16384) {
+				nodeExceeded = true;
+				continue;
+			}
+			pending.push(value.value);
+			metadata.push(inMeta || key === "meta");
+		}
+	}
+	if (stringExceeded) faults.push(`Schema contains a string longer than ${STRING_LIMIT}`);
+	if (textExceeded) faults.push(`Schema retains more than ${TEXT_LIMIT} string code units`);
+	if (nodeExceeded) faults.push(`Schema retains more than ${NODE_LIMIT} nodes`);
+	if (schema.groups !== void 0) {
+		const count = Math.min(schema.groups.length, 65);
+		for (let index = 0; index < count; index += 1) {
+			const group = schema.groups[index];
+			if (group === void 0) continue;
+			if (groups.has(group.name)) faults.push(`Group "${group.name}" is declared more than once`);
+			groups.add(group.name);
+		}
+	}
+	for (let fieldIndex = 0; fieldIndex < fieldCount; fieldIndex += 1) {
+		const field = schema.fields[fieldIndex];
+		if (field === void 0) continue;
+		if (field.name.length === 0) faults.push("Field \"\" has an empty name");
+		if (field.name === "__proto__") faults.push("Field \"__proto__\" has a refused name");
+		if (fields.has(field.name)) faults.push(`Field "${field.name}" is declared more than once`);
+		fields.add(field.name);
+		if (field.group !== void 0 && !groups.has(field.group)) faults.push(`Field "${field.name}" references missing group "${field.group}"`);
+		switch (field.control) {
+			case "password":
+			case "file": break;
+			case "text":
+			case "editor":
+			case "number":
+			case "date":
+			case "time":
+			case "datetime":
+			case "color":
+			case "confirm":
+			case "select":
+			case "checkbox": if (field.default !== void 0 && !matchesField(field, field.default)) faults.push(`Field "${field.name}" has an invalid default`);
+		}
+		if (field.control === "select" || field.control === "checkbox") {
+			const choices = /* @__PURE__ */ new Set();
+			const count = Math.min(field.choices.length, CHOICE_LIMIT + 1);
+			let enabled = 0;
+			for (let index = 0; index < count; index += 1) {
+				const choice = field.choices[index];
+				if (choice === void 0) continue;
+				if (choice.disabled !== true) enabled += 1;
+				if (choices.has(choice.value)) faults.push(`Field "${field.name}" offers choice "${choice.value}" more than once`);
+				choices.add(choice.value);
+			}
+			if (field.control === "select" && field.rule?.required === true && field.open !== true && enabled === 0) faults.push(`Field "${field.name}" is required but offers no enabled choice`);
+			const minimum = field.rule?.minimum;
+			if (field.control === "checkbox" && isFiniteNumber(minimum) && minimum > 0 && minimum > enabled) faults.push(`Field "${field.name}" has minimum ${minimum} but offers only ${enabled} enabled ${enabled === 1 ? "choice" : "choices"}`);
+		}
+		const rule = field.rule;
+		if (rule === void 0) continue;
+		const temporal = field.control === "date" || field.control === "time" || field.control === "datetime";
+		if (rule.minimum !== void 0 && !appliesRule(field.control, "minimum")) faults.push(`Field "${field.name}" has minimum on ${field.control}`);
+		else if (isString(rule.minimum) && !temporal) faults.push(`Field "${field.name}" has a string minimum on ${field.control}`);
+		if (rule.maximum !== void 0 && !appliesRule(field.control, "maximum")) faults.push(`Field "${field.name}" has maximum on ${field.control}`);
+		else if (isString(rule.maximum) && !temporal) faults.push(`Field "${field.name}" has a string maximum on ${field.control}`);
+		if (isFiniteNumber(rule.minimum) && temporal) faults.push(`Field "${field.name}" has a numeric minimum on ${field.control}`);
+		if (isFiniteNumber(rule.maximum) && temporal) faults.push(`Field "${field.name}" has a numeric maximum on ${field.control}`);
+		if (isFiniteNumber(rule.maximum) && rule.maximum < 0 && (field.control === "text" || field.control === "editor" || field.control === "password" || field.control === "checkbox" || field.control === "file")) faults.push(`Field "${field.name}" has a negative maximum on ${field.control}`);
+		if (rule.step !== void 0 && !appliesRule(field.control, "step")) faults.push(`Field "${field.name}" has step on ${field.control}`);
+		if (rule.step !== void 0 && rule.step <= 0) faults.push(`Field "${field.name}" has a non-positive step`);
+		if (rule.pattern !== void 0 && !appliesRule(field.control, "pattern")) faults.push(`Field "${field.name}" has pattern on ${field.control}`);
+		if (rule.email === true && !appliesRule(field.control, "email")) faults.push(`Field "${field.name}" has email on ${field.control}`);
+		if (rule.url === true && !appliesRule(field.control, "url")) faults.push(`Field "${field.name}" has url on ${field.control}`);
+		if (rule.alphanumeric === true && !appliesRule(field.control, "alphanumeric")) faults.push(`Field "${field.name}" has alphanumeric on ${field.control}`);
+		if (rule.integer === true && !appliesRule(field.control, "integer")) faults.push(`Field "${field.name}" has integer on ${field.control}`);
+		if (rule.pattern !== void 0) {
+			if (rule.pattern.length > 256) faults.push(`Field "${field.name}" has a pattern longer than 256`);
+			else try {
+				RegExp(rule.pattern);
+			} catch {
+				faults.push(`Field "${field.name}" has an invalid pattern`);
+			}
+		}
+		if (isFiniteNumber(rule.minimum) && isFiniteNumber(rule.maximum) && rule.minimum > rule.maximum || isString(rule.minimum) && isString(rule.maximum) && rule.minimum > rule.maximum) faults.push(`Field "${field.name}" has minimum greater than maximum`);
+		if (field.control === "date") {
+			if (isString(rule.minimum) && !DATE_PATTERN.test(rule.minimum)) faults.push(`Field "${field.name}" has an invalid date minimum`);
+			if (isString(rule.maximum) && !DATE_PATTERN.test(rule.maximum)) faults.push(`Field "${field.name}" has an invalid date maximum`);
+		}
+		if (field.control === "time") {
+			if (isString(rule.minimum) && !TIME_PATTERN.test(rule.minimum)) faults.push(`Field "${field.name}" has an invalid time minimum`);
+			if (isString(rule.maximum) && !TIME_PATTERN.test(rule.maximum)) faults.push(`Field "${field.name}" has an invalid time maximum`);
+		}
+		if (field.control === "datetime") {
+			if (isString(rule.minimum) && !DATETIME_PATTERN.test(rule.minimum)) faults.push(`Field "${field.name}" has an invalid datetime minimum`);
+			if (isString(rule.maximum) && !DATETIME_PATTERN.test(rule.maximum)) faults.push(`Field "${field.name}" has an invalid datetime maximum`);
+		}
+	}
+	return Object.freeze(faults);
+}
+//#endregion
+//#region src/core/parsers.ts
+/**
+* Parse unknown wire data into an owned, semantically sound form schema.
+*
+* @param input - The unknown schema value to parse.
+* @returns An owned schema with custom rules removed, or `undefined` on refusal.
+*/
+function parseForm(input) {
+	const outcome = attempt(() => {
+		if (!isRecord(input)) return void 0;
+		const schema = {};
+		for (const key of Reflect.ownKeys(input)) {
+			if (!isString(key)) return void 0;
+			Object.defineProperty(schema, key, {
+				value: input[key],
+				enumerable: true,
+				configurable: true,
+				writable: true
+			});
+		}
+		const fields = schema.fields;
+		if (!isArray(fields)) return void 0;
+		const read = readArrayEntries(fields);
+		if (!read.success || !read.value.dense) return void 0;
+		const copies = [];
+		for (let index = 0; index < read.value.entries.length; index += 1) {
+			const field = read.value.entries[index];
+			if (!isRecord(field)) {
+				copies.push(field);
+				continue;
+			}
+			const copy = {};
+			for (const key of Reflect.ownKeys(field)) {
+				if (!isString(key)) return void 0;
+				Object.defineProperty(copy, key, {
+					value: field[key],
+					enumerable: true,
+					configurable: true,
+					writable: true
+				});
+			}
+			const rule = copy.rule;
+			if (isRecord(rule)) {
+				const projected = {};
+				for (const key of Reflect.ownKeys(rule)) {
+					if (!isString(key)) return void 0;
+					if (key !== "custom") Object.defineProperty(projected, key, {
+						value: rule[key],
+						enumerable: true,
+						configurable: true,
+						writable: true
+					});
+				}
+				copy.rule = projected;
+			}
+			copies.push(copy);
+		}
+		schema.fields = copies;
+		if (!isFormSchema(schema) || auditSchema(schema).length !== 0) return void 0;
+		const parsed = serializeForm(schema);
+		return isFormSchema(parsed) && auditSchema(parsed).length === 0 ? parsed : void 0;
+	});
+	return outcome.success ? outcome.value : void 0;
+}
+/**
+* Parse one answer against its field control.
+*
+* @param field - The field that defines the accepted value.
+* @param input - The unknown value to parse.
+* @returns The typed or lexically coerced field value, or `undefined` on refusal.
+*/
+function parseValue(field, input) {
+	const outcome = attempt(() => {
+		if (matchesField(field, input)) return cloneValue(input);
+		if (field.control === "number") {
+			if (isString(input) && input.length > 65536) return void 0;
+			const value = parseNumber(input);
+			return value !== void 0 && matchesField(field, value) ? value : void 0;
+		}
+		if (field.control === "confirm") {
+			if (input === "true") return true;
+			if (input === "false") return false;
+		}
+	});
+	return outcome.success ? outcome.value : void 0;
+}
+/**
+* Parse a strict answer record against the fields declared by a schema.
+*
+* @param schema - The schema that owns the accepted field names and controls.
+* @param input - The unknown answer record to parse.
+* @returns An owned answer record, or `undefined` when any key or value is refused.
+*/
+function parseValues(schema, input) {
+	const outcome = attempt(() => {
+		if (!isRecord(input)) return void 0;
+		const values = {};
+		for (const key of Reflect.ownKeys(input)) {
+			if (!isString(key) || !Object.hasOwn(input, key)) return void 0;
+			const field = schema.fields.find((candidate) => candidate.name === key);
+			if (field === void 0) return void 0;
+			const value = parseValue(field, input[key]);
+			if (value === void 0) return void 0;
+			Object.defineProperty(values, key, {
+				value,
+				enumerable: true,
+				configurable: false,
+				writable: false
+			});
+		}
+		return Object.freeze(values);
+	});
+	return outcome.success ? outcome.value : void 0;
+}
+//#endregion
+//#region src/core/Form.ts
+/**
+* A form: a schema, the answers given against it, and the errors they carry.
+*
+* @remarks
+* The form owns its schema, so a later edit to the schema the caller passed changes nothing here.
+*
+* `errors` is recomputed at construction and after every mutation whose evaluation completes,
+* and the `validate` event fires exactly when that list's content changes. A throwing custom
+* validator escapes after any preceding state changes and leaves the prior error list in place.
+* There is no separate check.
+*
+* `valid` and `dirty` are derived on read from the error list and answers respectively, never
+* stored.
+*
+* @example
+* ```ts
+* const form = new Form({
+* 	fields: [{ control: 'text', name: 'email', rule: { required: true, email: true } }],
+* })
+*
+* form.fill('email', 'ada@example.com')
+* const result = form.submit()
+* if (result.success) await form.answer
+* ```
+*/
+var Form = class {
+	#emitter;
+	#schema;
+	#messages;
+	#baseline;
+	#values;
+	#touched = /* @__PURE__ */ new Set();
+	#disabled = /* @__PURE__ */ new Map();
+	#invalidations = /* @__PURE__ */ new Map();
+	#resolvers = Promise.withResolvers();
+	#errors = Object.freeze([]);
+	#status = "editing";
+	#batchDepth = 0;
+	#evaluation = 0;
+	#pending = false;
+	/**
+	* Open a form against a schema.
+	*
+	* @param schema - The form to ask. It is copied, and the copy is what the form asks.
+	* @param options - The form's settings.
+	* @throws A {@link FormError} coded `SCHEMA` when the schema is malformed, `FIELD` when
+	*   `options.values` names a field the schema does not declare, and `CONTROL` when a seeded
+	*   value is one its field's control cannot hold.
+	*/
+	constructor(schema, options) {
+		const problems = isFormSchema(schema) ? auditSchema(schema) : ["The schema is not a form schema"];
+		if (problems.length > 0) throw new FormError("SCHEMA", `The form schema is unusable: ${problems.join("; ")}`, { problems: [...problems] });
+		this.#schema = cloneFormSchema(schema);
+		this.#messages = options?.messages === void 0 ? void 0 : Object.freeze({ ...options.messages });
+		const baseline = {};
+		for (const [name, value] of Object.entries(computeDefaults(this.#schema))) Object.defineProperty(baseline, name, {
+			value,
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+		for (const [name, value] of Object.entries(options?.values ?? {})) {
+			const field = this.#requireField(name);
+			if (!matchesField(field, value)) throw new FormError("CONTROL", `The ${field.control} field "${name}" cannot hold that value`, {
+				field: name,
+				control: field.control
+			});
+			Object.defineProperty(baseline, name, {
+				value: cloneValue(value),
+				enumerable: true,
+				configurable: true,
+				writable: true
+			});
+		}
+		this.#baseline = Object.freeze(baseline);
+		this.#values = {};
+		for (const [name, value] of Object.entries(baseline)) Object.defineProperty(this.#values, name, {
+			value,
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+		this.#resolvers.promise.catch(() => void 0);
+		this.#emitter = new Emitter(options);
+		this.#evaluate();
+	}
+	/** The form's event emitter. */
+	get emitter() {
+		return this.#emitter;
+	}
+	/** The schema this form asks, owned and frozen. */
+	get schema() {
+		return this.#schema;
+	}
+	/** The answers held right now. */
+	get values() {
+		const values = {};
+		for (const name of Object.keys(this.#values)) Object.defineProperty(values, name, {
+			value: this.#values[name],
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+		return Object.freeze(values);
+	}
+	/** The answers the form opened with. */
+	get baseline() {
+		return this.#baseline;
+	}
+	/** Every error the last completed evaluation produced. */
+	get errors() {
+		return this.#errors;
+	}
+	/** The names of the fields somebody has visited. */
+	get touched() {
+		return new Set(this.#touched);
+	}
+	/** The names of the fields currently out of the form. */
+	get disabled() {
+		const disabled = /* @__PURE__ */ new Set();
+		for (const field of this.#schema.fields) if ((this.#disabled.get(field.name) ?? field.disabled === true) === true) disabled.add(field.name);
+		return disabled;
+	}
+	/** Where the form sits in its life. */
+	get status() {
+		return this.#status;
+	}
+	/** Whether the last completed evaluation found no error. */
+	get valid() {
+		return this.#errors.length === 0;
+	}
+	/** Whether any answer has moved since the form opened. */
+	get dirty() {
+		return !matchesValues(this.values, this.#baseline);
+	}
+	/**
+	* The answers, once the form settles.
+	*
+	* @remarks
+	* It resolves with the submitted values on the first valid submit, and rejects with a
+	* {@link FormError} coded `ABANDONED` when teardown abandons the form before it settles.
+	*/
+	get answer() {
+		return this.#resolvers.promise;
+	}
+	/**
+	* Find one field by name.
+	*
+	* @param name - The field's name.
+	* @returns The field, or `undefined` when the schema declares no such name.
+	*/
+	field(name) {
+		return this.#schema.fields.find((field) => field.name === name);
+	}
+	/**
+	* Answer one field or several.
+	*
+	* @param input - One field's name, or the answers to write keyed by field name.
+	* @param value - The answer to write when `input` names one field.
+	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, `FIELD`
+	*   when a name is not declared, and `CONTROL` when a value is one its control cannot hold.
+	*   Every answer is checked before any is written, so a refused write changes nothing.
+	*/
+	fill(input, value) {
+		this.#gate();
+		const entries = isString(input) ? [[input, value]] : Object.entries(input);
+		for (const [name, answer] of entries) {
+			const field = this.#requireField(name);
+			if (answer !== void 0 && !matchesField(field, answer)) throw new FormError("CONTROL", `The ${field.control} field "${name}" cannot hold that value`, {
+				field: name,
+				control: field.control
+			});
+		}
+		this.#batch(() => {
+			const moved = [];
+			for (const [name, answer] of entries) {
+				if (this.#differs(name, answer)) moved.push(name);
+				if (answer === void 0) delete this.#values[name];
+				else Object.defineProperty(this.#values, name, {
+					value: cloneValue(answer),
+					enumerable: true,
+					configurable: true,
+					writable: true
+				});
+				this.#invalidations.delete(name);
+			}
+			for (const name of moved) {
+				const answer = Object.hasOwn(this.#values, name) ? this.#values[name] : void 0;
+				this.#emitter.emit("fill", name, answer);
+			}
+			if (this.#evaluate()) this.#emitter.emit("validate", this.#errors);
+		});
+	}
+	/**
+	* Record that somebody has visited a field.
+	*
+	* @param name - The field's name.
+	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
+	*   `FIELD` when the schema declares no such name.
+	*/
+	touch(name) {
+		this.#gate();
+		this.#requireField(name);
+		this.#touched.add(name);
+	}
+	/**
+	* Fail a field from outside, for what the rules cannot see.
+	*
+	* @param name - The field's name.
+	* @param message - What to tell the person.
+	* @remarks
+	* One field holds one external failure: a second call replaces the first. The failure lasts
+	* until that field is filled again or the form is cleared.
+	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
+	*   `FIELD` when the schema declares no such name.
+	*/
+	invalidate(name, message) {
+		this.#gate();
+		this.#requireField(name);
+		this.#batch(() => {
+			this.#invalidations.set(name, message);
+			if (this.#evaluate()) this.#emitter.emit("validate", this.#errors);
+		});
+	}
+	/**
+	* Take one or more fields out of the form.
+	*
+	* @param input - One field name, several names, or absence to select every field.
+	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
+	*   `FIELD` when the schema declares no requested name. Every name is checked before any field
+	*   moves.
+	*/
+	disable(input) {
+		this.#gate();
+		this.#change(input, true);
+	}
+	/**
+	* Put one or more fields back into the form.
+	*
+	* @param input - One field name, several names, or absence to select every field.
+	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
+	*   `FIELD` when the schema declares no requested name. Every name is checked before any field
+	*   moves.
+	*/
+	enable(input) {
+		this.#gate();
+		this.#change(input, false);
+	}
+	/**
+	* Check every answer and settle the form when they all pass.
+	*
+	* @returns The values on success, or every error that stopped them.
+	* @remarks
+	* A failed submit marks every enabled field touched, so a renderer can show the errors the
+	* person has not reached yet. A disabled field is neither checked nor submitted. When a changed
+	* evaluation notifies listeners and a listener writes, submit evaluates once more after those
+	* listeners return and decides from that state. Listener work that settled the form wins: that
+	* settlement is what this call returns, with no further evaluation, resolution, or `submit`
+	* emission. An evaluation that already failed refuses with the list it checked, even when a
+	* listener repaired or disabled the field that failed. An evaluation that passed decides from the
+	* state the drain left, which is why one further evaluation bounds the drain rather than a
+	* fixpoint loop.
+	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
+	*/
+	submit() {
+		this.#gate();
+		return this.#batch(() => {
+			const changed = this.#evaluate();
+			const checked = this.#errors;
+			const failed = checked.length > 0;
+			const evaluation = this.#evaluation;
+			if (changed) {
+				this.#emitter.emit("validate", this.#errors);
+				const settlement = this.#readSettlement();
+				if (settlement !== void 0) return settlement;
+				if (this.#evaluation !== evaluation && this.#evaluate()) {
+					this.#emitter.emit("validate", this.#errors);
+					const drained = this.#readSettlement();
+					if (drained !== void 0) return drained;
+				}
+			}
+			const errors = failed ? checked : this.#errors;
+			const stopped = errors.length > 0;
+			if (stopped) {
+				const disabled = this.disabled;
+				for (const field of this.#schema.fields) if (!disabled.has(field.name)) this.#touched.add(field.name);
+			}
+			if (stopped) return {
+				success: false,
+				error: errors
+			};
+			const answers = this.#snapshot();
+			this.#status = "settled";
+			this.#resolvers.resolve(answers);
+			this.#emitter.emit("submit", answers);
+			return {
+				success: true,
+				value: answers
+			};
+		});
+	}
+	/**
+	* Return every answer to the ones the form opened with: the schema's defaults, overlaid with
+	* any seeded `values`. Reset the runtime disabled state to the schema's declarations.
+	*
+	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
+	*/
+	clear() {
+		this.#gate();
+		this.#batch(() => {
+			for (const name of Object.keys(this.#values)) delete this.#values[name];
+			for (const [name, value] of Object.entries(this.#baseline)) Object.defineProperty(this.#values, name, {
+				value,
+				enumerable: true,
+				configurable: true,
+				writable: true
+			});
+			this.#touched.clear();
+			this.#disabled.clear();
+			this.#invalidations.clear();
+			const changed = this.#evaluate();
+			this.#emitter.emit("clear");
+			if (changed) this.#emitter.emit("validate", this.#errors);
+		});
+	}
+	/**
+	* Tear the form down, abandoning it when it has not settled.
+	*
+	* @remarks
+	* Destroying twice does nothing the second time. A settled form keeps its `settled` status and
+	* announces nothing. A request from inside a listener defers teardown until the outermost
+	* mutation batch closes, so an in-flight settlement can win and leave the form `settled` rather
+	* than `abandoned`. Every getter keeps answering afterwards; every write is refused.
+	*/
+	destroy() {
+		if (this.#pending) return;
+		this.#pending = true;
+		if (this.#batchDepth === 0) this.#teardown();
+	}
+	#gate() {
+		if (this.#status === "settled") throw new FormError("SETTLED", "The form has settled and cannot change");
+		if (this.#status === "abandoned" || this.#pending) throw new FormError("ABANDONED", "The form was abandoned and cannot change");
+	}
+	#requireField(name) {
+		const field = this.field(name);
+		if (field === void 0) throw new FormError("FIELD", `The schema declares no field named "${name}"`, { field: name });
+		return field;
+	}
+	#change(input, disabled) {
+		const names = new Set(input === void 0 ? this.#schema.fields.map((field) => field.name) : isString(input) ? [input] : input);
+		for (const name of names) this.#requireField(name);
+		const moved = [];
+		for (const field of this.#schema.fields) {
+			const active = names.has(field.name);
+			const current = this.#disabled.get(field.name) ?? field.disabled === true;
+			if (active && current !== disabled) moved.push(field.name);
+		}
+		if (moved.length === 0) return;
+		this.#batch(() => {
+			for (const name of names) this.#disabled.set(name, disabled);
+			for (const name of moved) if (disabled) this.#emitter.emit("disable", name);
+			else this.#emitter.emit("enable", name);
+			if (this.#evaluate()) this.#emitter.emit("validate", this.#errors);
+		});
+	}
+	#evaluate() {
+		const disabled = this.disabled;
+		const options = this.#messages === void 0 ? { disabled } : {
+			messages: this.#messages,
+			disabled
+		};
+		const errors = [...evaluateForm(this.#schema, this.values, options)];
+		for (const [field, message] of this.#invalidations) if (!disabled.has(field)) errors.push(Object.freeze({
+			field,
+			message
+		}));
+		const previous = this.#errors;
+		const next = Object.freeze(errors);
+		this.#errors = next;
+		const changed = next.length !== previous.length || next.some((error, index) => {
+			const before = previous[index];
+			return before === void 0 || before.field !== error.field || before.message !== error.message || before.rule !== error.rule;
+		});
+		this.#evaluation += 1;
+		return changed;
+	}
+	#differs(name, value) {
+		const current = Object.hasOwn(this.#values, name) ? this.#values[name] : void 0;
+		if (value === void 0) return current !== void 0;
+		if (current === void 0) return true;
+		return !matchesValue(current, value);
+	}
+	#readSettlement() {
+		if (this.#status === "settled") return {
+			success: true,
+			value: this.#snapshot()
+		};
+		if (this.#status === "abandoned") this.#gate();
+	}
+	#snapshot() {
+		const answers = {};
+		const disabled = this.disabled;
+		for (const field of this.#schema.fields) {
+			const value = Object.hasOwn(this.#values, field.name) ? this.#values[field.name] : void 0;
+			if (!disabled.has(field.name) && value !== void 0) Object.defineProperty(answers, field.name, {
+				value,
+				enumerable: true,
+				configurable: true,
+				writable: true
+			});
+		}
+		return Object.freeze(answers);
+	}
+	#batch(callback) {
+		this.#batchDepth += 1;
+		try {
+			return callback();
+		} finally {
+			this.#batchDepth -= 1;
+			if (this.#batchDepth === 0 && this.#pending) this.#teardown();
+		}
+	}
+	#teardown() {
+		if (this.#status === "editing") {
+			this.#status = "abandoned";
+			this.#resolvers.reject(new FormError("ABANDONED", "The form was destroyed before it settled"));
+			this.#emitter.emit("abandon");
+		}
+		this.#emitter.destroy();
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Open a form against a schema.
+*
+* @param schema - The form to ask. It is copied, and the copy is what the form asks.
+* @param options - The form's settings.
+* @returns A form open for answers.
+* @remarks
+* Prefer this at a call site that only needs {@link FormInterface}. `new Form(...)` is the same
+* construction and is what a class holding a form as its own field reaches for.
+* @throws A {@link FormError} coded `SCHEMA` when the schema is malformed, `FIELD` when
+*   `options.values` names a field the schema does not declare, and `CONTROL` when a seeded value
+*   is one its field's control cannot hold.
+* @example
+* ```ts
+* const form = createForm({
+* 	label: 'Sign up',
+* 	fields: [
+* 		{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
+* 		{ control: 'confirm', name: 'terms', label: 'I accept the terms', rule: { required: true } },
+* 	],
+* })
+*
+* form.fill({ email: 'ada@example.com', terms: true })
+* form.submit() // { success: true, value: { email: 'ada@example.com', terms: true } }
+* ```
+*/
+function createForm(schema, options) {
+	return new Form(schema, options);
+}
+//#endregion
+export { ALPHANUMERIC_PATTERN, CHOICE_LIMIT, COLOR_PATTERN, DATETIME_PATTERN, DATE_PATTERN, EMAIL_PATTERN, FIELD_CONTROLS, FIELD_LIMIT, FORM_STATUSES, Form, FormError, GROUP_LIMIT, INTEGER_PATTERN, LIST_LIMIT, NAME_LIMIT, NODE_LIMIT, PATTERN_LIMIT, RULE_MESSAGES, STRING_LIMIT, TEXT_LIMIT, TIME_PATTERN, URL_PATTERN, appliesRule, auditSchema, cloneChoices, cloneFormField, cloneFormSchema, cloneValue, computeDefaults, createForm, evaluateField, evaluateForm, extractChanges, extractGroups, formatMessage, isFieldChoice, isFieldControl, isFieldError, isFieldRule, isFieldValue, isFormError, isFormField, isFormGroup, isFormSchema, isFormStatus, isFormValues, matchesAnswer, matchesField, matchesValue, matchesValues, parseForm, parseValue, parseValues, serializeForm };
+
+//# sourceMappingURL=index.js.map