@orkestrel/form 0.0.8 → 0.0.10

package/dist/src/core/index.js

@@ -1268,6 +1268,11 @@ var Form = class {
 	#touched = /* @__PURE__ */ new Set();
 	#disabled = /* @__PURE__ */ new Map();
 	#invalidations = /* @__PURE__ */ new Map();
+	#revisions = /* @__PURE__ */ new Map();
+	#captured = /* @__PURE__ */ new Map();
+	#submission;
+	#controller;
+	#preparing;
 	#resolvers = Promise.withResolvers();
 	#errors = Object.freeze([]);
 	#status = "editing";
@@ -1322,10 +1327,14 @@ var Form = class {
 		for (const [name, value] of Object.entries(this.#values)) defineEntry(values, name, value);
 		return Object.freeze(values);
 	}
-	/** Holds the answers the form opened with. */
+	/** Holds the acknowledged answers, initially the schema's defaults overlaid with seeded values. */
 	get baseline() {
 		return this.#baseline;
 	}
+	/** Holds the submission awaiting acknowledgement, or `undefined` when none is pending. */
+	get pending() {
+		return this.#submission;
+	}
 	/** Holds every error the last completed evaluation produced. */
 	get errors() {
 		return this.#errors;
@@ -1348,7 +1357,7 @@ var Form = class {
 	get valid() {
 		return this.#errors.length === 0;
 	}
-	/** Reports whether any answer has moved since the form opened. */
+	/** Reports whether any answer differs from its acknowledged baseline. */
 	get dirty() {
 		return !matchesValues(this.values, this.#baseline);
 	}
@@ -1393,6 +1402,7 @@ var Form = class {
 		this.#batch(() => {
 			const moved = [];
 			for (const [name, answer] of entries) {
+				this.#revisions.set(name, (this.#revisions.get(name) ?? 0) + 1);
 				if (this.#differs(name, answer)) moved.push(name);
 				if (answer === void 0) delete this.#values[name];
 				else defineEntry(this.#values, name, cloneValue(answer));
@@ -1415,26 +1425,34 @@ var Form = class {
 	touch(name) {
 		this.#gate();
 		this.#requireField(name);
-		this.#touched.add(name);
+		this.#batch(() => {
+			if (this.#touched.has(name)) return;
+			this.#touched.add(name);
+			this.#emitter.emit("touch", name);
+		});
 	}
 	/**
 	* Fails a field from outside, for what the rules cannot see.
 	*
 	* @param name - The field's name.
 	* @param message - What to tell the person.
+	* @param submission - The active receipt to check against the field's captured revision.
+	* @returns True if the failure was applied; false if the receipt or field revision is stale.
 	* @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();
+	invalidate(name, message, submission) {
+		if (submission === void 0) this.#gate();
 		this.#requireField(name);
+		if (submission !== void 0 && (this.#pending || submission !== this.#submission || !this.#captured.has(name) || this.#captured.get(name) !== (this.#revisions.get(name) ?? 0))) return false;
 		this.#batch(() => {
 			this.#invalidations.set(name, message);
 			if (this.#evaluate()) this.#emitter.emit("validate", this.#errors);
 		});
+		return true;
 	}
 	/**
 	* Takes one or more fields out of the form.
@@ -1478,6 +1496,7 @@ var Form = class {
 	*/
 	submit() {
 		this.#gate();
+		this.#gatePreparation();
 		return this.#batch(() => {
 			const changed = this.#evaluate();
 			const checked = this.#errors;
@@ -1497,12 +1516,16 @@ var Form = class {
 			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);
+				for (const field of this.#schema.fields) if (!disabled.has(field.name) && !this.#touched.has(field.name)) {
+					this.#touched.add(field.name);
+					this.#emitter.emit("touch", field.name);
+				}
 			}
 			if (stopped) return {
 				success: false,
 				error: errors
 			};
+			this.#gatePreparation();
 			const answers = this.#snapshot();
 			this.#status = "settled";
 			this.#resolvers.resolve(answers);
@@ -1514,20 +1537,143 @@ var Form = class {
 		});
 	}
 	/**
-	* Returns 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.
+	* Prepares an owned enabled snapshot for acknowledgement while leaving the form editable.
+	*
+	* @returns The submission on success, or the errors that prevented preparation.
+	* @remarks
+	* A failed check refuses its checked errors even if an observer repairs them. A passing check
+	* drains observer mutations through one further check. The receipt always carries that check's
+	* snapshot, including when its notifications produce later edits. A throwing validator creates
+	* no receipt. The pending identity is installed before `prepare` listeners run.
+	* @throws A {@link FormError} coded `PENDING` while another preparation or receipt is pending,
+	*   or when clear interrupts preparation; terminal forms retain their terminal refusals.
+	*/
+	prepare() {
+		this.#gate();
+		this.#gatePreparation();
+		const controller = new AbortController();
+		this.#preparing = controller;
+		return this.#batch(() => {
+			try {
+				let drained = false;
+				while (true) {
+					const values = this.values;
+					const disabled = this.disabled;
+					const captured = /* @__PURE__ */ new Map();
+					const touched = [];
+					for (const field of this.#schema.fields) {
+						if (disabled.has(field.name)) continue;
+						captured.set(field.name, this.#revisions.get(field.name) ?? 0);
+						if (!this.#touched.has(field.name)) touched.push(field.name);
+						this.#touched.add(field.name);
+					}
+					const before = this.#evaluation;
+					for (const name of touched) {
+						if (controller.signal.aborted || this.#pending) break;
+						this.#emitter.emit("touch", name);
+					}
+					this.#requirePreparation(controller);
+					const errors = this.#check(values, disabled);
+					const mutated = this.#evaluation !== before;
+					const changed = !mutated && this.#record(errors);
+					const evaluation = this.#evaluation;
+					if (changed) this.#emitter.emit("validate", this.#errors);
+					this.#requirePreparation(controller);
+					if (errors.length > 0) return {
+						success: false,
+						error: errors
+					};
+					if (!drained && (mutated || this.#evaluation !== evaluation)) {
+						drained = true;
+						continue;
+					}
+					const submission = Object.freeze({
+						values: this.#snapshot(values, disabled),
+						signal: controller.signal
+					});
+					this.#captured = captured;
+					this.#controller = controller;
+					this.#submission = submission;
+					this.#preparing = void 0;
+					this.#emitter.emit("prepare", submission);
+					return {
+						success: true,
+						value: submission
+					};
+				}
+			} finally {
+				if (this.#preparing === controller) this.#preparing = void 0;
+			}
+		});
+	}
+	/**
+	* Adopts the active submission's captured answers into the baseline without changing live state.
+	*
+	* @param submission - The receipt returned by preparation.
+	* @returns True if this active receipt was accepted; false otherwise, including after teardown.
+	*/
+	accept(submission) {
+		if (this.#pending || submission !== this.#submission) return false;
+		return this.#batch(() => {
+			const baseline = { ...this.#baseline };
+			for (const name of this.#captured.keys()) {
+				const value = Object.hasOwn(submission.values, name) ? submission.values[name] : void 0;
+				if (value === void 0) delete baseline[name];
+				else defineEntry(baseline, name, value);
+			}
+			this.#baseline = Object.freeze(baseline);
+			this.#submission = void 0;
+			this.#controller = void 0;
+			this.#captured = /* @__PURE__ */ new Map();
+			this.#emitter.emit("accept", submission);
+			return true;
+		});
+	}
+	/**
+	* Consumes the active submission and aborts its signal without changing answers or baseline.
+	*
+	* @param submission - The receipt returned by preparation.
+	* @returns True if this active receipt was aborted; false otherwise, including after teardown.
+	*/
+	abort(submission) {
+		if (this.#pending || submission !== this.#submission) return false;
+		this.#batch(() => {
+			const controller = this.#controller;
+			this.#submission = void 0;
+			this.#controller = void 0;
+			this.#captured = /* @__PURE__ */ new Map();
+			controller?.abort();
+			this.#emitter.emit("abort", submission);
+		});
+		return true;
+	}
+	/**
+	* Returns every answer to its acknowledged baseline and aborts pending acknowledgement.
 	*
 	* @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
 	*/
 	clear() {
 		this.#gate();
 		this.#batch(() => {
+			const submission = this.#submission;
+			const controller = this.#controller;
+			this.#submission = void 0;
+			this.#controller = void 0;
+			this.#captured = /* @__PURE__ */ new Map();
+			this.#preparing?.abort();
 			for (const name of Object.keys(this.#values)) delete this.#values[name];
 			for (const [name, value] of Object.entries(this.#baseline)) defineEntry(this.#values, name, value);
 			this.#touched.clear();
 			this.#disabled.clear();
 			this.#invalidations.clear();
-			const changed = this.#evaluate();
+			this.#revisions.clear();
+			let changed = false;
+			try {
+				changed = this.#evaluate();
+			} finally {
+				controller?.abort();
+				if (submission !== void 0) this.#emitter.emit("abort", submission);
+			}
 			this.#emitter.emit("clear");
 			if (changed) this.#emitter.emit("validate", this.#errors);
 		});
@@ -1550,6 +1696,13 @@ var Form = class {
 		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");
 	}
+	#gatePreparation() {
+		if (this.#preparing !== void 0 || this.#submission !== void 0) throw new FormError("PENDING", "The form has a pending preparation or submission");
+	}
+	#requirePreparation(controller) {
+		this.#gate();
+		if (controller.signal.aborted) throw new FormError("PENDING", "The preparation was interrupted by clear");
+	}
 	#requireField(name) {
 		const field = this.field(name);
 		if (field === void 0) throw new FormError("FIELD", `The schema declares no field named "${name}"`, { field: name });
@@ -1574,17 +1727,22 @@ var Form = class {
 	}
 	#evaluate() {
 		const disabled = this.disabled;
+		return this.#record(this.#check(this.values, disabled));
+	}
+	#check(values, disabled) {
 		const options = this.#messages === void 0 ? { disabled } : {
 			messages: this.#messages,
 			disabled
 		};
-		const errors = [...evaluateForm(this.#schema, this.values, options)];
+		const errors = [...evaluateForm(this.#schema, values, options)];
 		for (const [field, message] of this.#invalidations) if (!disabled.has(field)) errors.push(Object.freeze({
 			field,
 			message
 		}));
+		return Object.freeze(errors);
+	}
+	#record(next) {
 		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];
@@ -1606,12 +1764,11 @@ var Form = class {
 		};
 		if (this.#status === "abandoned") this.#gate();
 	}
-	#snapshot() {
+	#snapshot(values = this.#values, disabled = this.disabled) {
 		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) defineEntry(answers, field.name, value);
+			const value = Object.hasOwn(values, field.name) ? values[field.name] : void 0;
+			if (!disabled.has(field.name) && value !== void 0) defineEntry(answers, field.name, cloneValue(value));
 		}
 		return Object.freeze(answers);
 	}
@@ -1625,11 +1782,20 @@ var Form = class {
 		}
 	}
 	#teardown() {
-		if (this.#status === "editing") {
+		const submission = this.#submission;
+		const controller = this.#controller;
+		this.#submission = void 0;
+		this.#controller = void 0;
+		this.#captured = /* @__PURE__ */ new Map();
+		this.#preparing?.abort();
+		const abandoned = this.#status === "editing";
+		if (abandoned) {
 			this.#status = "abandoned";
 			this.#resolvers.reject(new FormError("ABANDONED", "The form was destroyed before it settled"));
-			this.#emitter.emit("abandon");
 		}
+		controller?.abort();
+		if (submission !== void 0) this.#emitter.emit("abort", submission);
+		if (abandoned) this.#emitter.emit("abandon");
 		this.#emitter.destroy();
 	}
 };