@thomasfosterau/effect-forms-svelte 0.0.0

package/dist/FormStore.svelte.js

@@ -0,0 +1,986 @@
+import { validateData, validateField } from "./ClientValidate.js";
+import { computeDataApplication, objectToFormData, parseActionResult, resultToUpdate } from "./EnhanceCore.js";
+import { computeTainted, isAnyTainted, isTaintedAt, taintedLeafPaths } from "./Tainted.js";
+import { dispatchChange } from "./Listeners.js";
+import { Constraints, Errors, Field, Form, FormBuilder, Mode, Path, Validate } from "@thomasfosterau/effect-forms";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import { createAttachmentKey } from "svelte/attachments";
+//#region src/FormStore.svelte.ts
+/**
+* @copyright Thomas Foster
+*
+* The reactive Svelte 5 form store.
+*
+* {@link createForm} binds a schema to a reactive, rune-backed {@link FormStore}.
+* Give it either `{ schema, defaults }` (it wraps the core's `makeForm` to seed
+* an empty form) or a server-produced {@link FormState} to hydrate from. The
+* store exposes mutable `data` (bind inputs to it), typed `errors`
+* (`form.errors.name`), `submitting` / `delayed` / `message` / `valid`, tainted
+* tracking, and a spreadable {@link FormStore.props} for `<form {...form.props}>`
+* that wires progressive-enhancement submission (a Svelte attachment).
+*
+* Submission is handled one of two ways: an `onSubmit` handler the page
+* provides (full client-side / JS handling, with `cancel()` and an optional
+* returned result), or — by default — a POST to the form's action (e.g. a
+* derived SvelteKit action) whose result is applied back to the store.
+*
+* ## Validation engine v2
+*
+* `errors` merges two parallel trees (see {@link Errors.SourcedErrors}):
+* `server` (the last submission's response) and `client` (browser-side
+* validation — the schema, per-field validators, a builder's `refineEffect`
+* refinements). A field's value changing clears *only that field's* server
+* error — a `State.withError` uniqueness failure the user hasn't touched
+* survives a client revalidation of some other field. `clientErrors` /
+* `serverErrors` expose the per-source trees for a UI that wants to style
+* them differently.
+*
+* `validators` (keyed by {@link Path.toString}) attach per-field sync/async
+* validators (the `FieldValidators` shape — TanStack Form's `onChange(Async)`
+* / `onBlur(Async)` vocabulary). Async validators run as Effect fibers: a new
+* value interrupts the field's in-flight fiber before forking the next run —
+* debounce + "latest wins" cancellation fall out of that alone (see
+* {@link Validate.runAsyncFieldValidator}). `isValidating` /
+* {@link FormStore.isValidatingAt} reflect any fiber still running; supply
+* `layer` when a validator (or a builder's `refineEffect`) needs services.
+*
+* `Mode.RevalidateMode` (`options.mode.revalidate`, default `"onChange"`)
+* governs what happens *after* a failed post in `onSubmit` mode: fixing a
+* field re-validates it (clearing its error) without a resubmit.
+*
+* @module effect-forms-svelte/FormStore
+*/
+const { clearSourceAt, emptySourced, hasErrors, mergeSourced, noErrors, replaceAt, setSourceAt } = Errors;
+const { getAt, setAt } = Path;
+const makeForm = Form.make;
+/**
+* A typed, reactive handle to one field, returned by {@link FormStore.field}.
+* Bundles everything a single input needs — `bind:value={field.value}`,
+* `name={field.name}`, `onblur={field.handleBlur}`, `{...field.constraints}`,
+* `field.visibleErrors`, `field.meta` — instead of wiring each by hand against
+* an untyped {@link FormPath}. See {@link Path.FieldPath} for how the path is
+* type-checked.
+*/
+var FieldHandle = class {
+	#store;
+	#path;
+	/** The path in flat field-name notation — use as the input's `name` attribute. */
+	name;
+	constructor(store, path) {
+		this.#store = store;
+		this.#path = path;
+		this.name = Path.toString(path);
+	}
+	/** The field's current value. Assignable — `bind:value={field.value}` works. */
+	get value() {
+		return this.#store.valueAt(this.#path);
+	}
+	set value(next) {
+		this.#store.setValue(this.#path, next);
+	}
+	/** All messages currently attached to this field. */
+	get errors() {
+		return this.#store.errorsAt(this.#path);
+	}
+	/** This field's messages, gated by the form's validation mode (see {@link FormStore.shouldShowError}). */
+	get visibleErrors() {
+		return this.#store.visibleErrorsAt(this.#path);
+	}
+	/** Native validation attributes for this field — spread onto the `<input>`. */
+	get constraints() {
+		return this.#store.constraintAt(this.#path);
+	}
+	/** This field's {@link FieldMeta}. */
+	get meta() {
+		const isBlurred = this.#store.isTouchedAt(this.#path);
+		const isDirty = this.#store.isDirtyAt(this.#path);
+		return {
+			isTouched: isBlurred || isDirty,
+			isBlurred,
+			isDirty,
+			isDefaultValue: this.#store.isDefaultValueAt(this.#path)
+		};
+	}
+	/** Mark this field blurred — see {@link FormStore.handleBlur}. */
+	handleBlur = () => {
+		this.#store.handleBlur(this.#path);
+	};
+};
+const defaultSubmit = async (body, action) => {
+	const response = await fetch(action, {
+		method: "POST",
+		body,
+		headers: { accept: "application/json" }
+	});
+	let parsed;
+	try {
+		parsed = await response.json();
+	} catch {
+		return {
+			_tag: "Error",
+			status: response.status,
+			message: response.statusText || "Request failed"
+		};
+	}
+	return parseActionResult(parsed, response.status);
+};
+/** Whether `index` is a valid position in an array of `length`. */
+const inRange = (index, length) => index >= 0 && index < length;
+/** A reactive form, returned by {@link createForm}. */
+var FormStore = class {
+	/** The reactive form data — bind inputs to its fields. */
+	data = $state();
+	/** The current status message, if any. */
+	message = $state();
+	/** Native input constraints derived server-side. */
+	constraints = $state({});
+	/** Whether a submission is in flight. */
+	submitting = $state(false);
+	/** Whether the in-flight submission has passed `delayMs`. */
+	delayed = $state(false);
+	/** Whether the current state came from a submission. */
+	posted = $state(false);
+	/** Whether the last validation/submit was valid. */
+	valid = $state(false);
+	/** How many times {@link FormStore.enhance}'s submit handler has actually attempted a submission. */
+	submissionAttempts = $state(0);
+	/** The values sent by the last submission (for revert / changed-since-submit). */
+	#lastSubmitted = $state();
+	/**
+	* Per-field blurred flags, keyed by {@link Path.toString}. Drives `onBlur`
+	* display (via {@link shouldShowError}) and {@link FieldMeta.isBlurred}.
+	*/
+	#touched = $state({});
+	/**
+	* Per-field persistent dirty flags, keyed by {@link Path.toString}. Set once
+	* a field's value is changed away from its default via {@link setValue} or
+	* an array mutator (`append` / `removeItem` / `swap` / `move`), and never
+	* cleared except by {@link reset} — unlike {@link taintedAt}, a revert to the
+	* default value does not clear it. Backs {@link FieldMeta.isDirty}. Only
+	* tracks writes made through those methods — mutating `data` directly
+	* (`bind:value={form.data.x}`, bypassing {@link FormStore.field}) never marks
+	* a field dirty.
+	*/
+	#dirtied = $state({});
+	/** Parallel error trees — see {@link Errors.SourcedErrors}. `errors` is their merged view. */
+	#sourced = $state(emptySourced);
+	/** Whether *any* validation (whole-form or per-field) has run yet — see {@link canSubmit}. */
+	#hasValidated = $state(false);
+	/** Per-field / whole-form ("") async-validation-in-flight flags, keyed by `"<path>:<trigger>"` or `""`. */
+	#validating = $state({});
+	/** Per-key run counter guarding `#validating` writes — see {@link FormStore.#runValidatorFiber}. */
+	#validatingGeneration = {};
+	/** The outcome of the last completed submission, for {@link isSubmitSuccessful}. */
+	#lastSubmitOutcome = $state(void 0);
+	id;
+	/** The tainted baseline `tainted`/`isTainted` compare against — rebased on every successful submit. */
+	#initial;
+	#options;
+	#mode;
+	#attachmentKey = createAttachmentKey();
+	#runtime;
+	#autoSubmitNode;
+	#validateTimer;
+	/** Per-field-listener debounce timers, keyed by `"change:<path>"` / `"blur:<path>"`. */
+	#listenerTimers = /* @__PURE__ */ new Map();
+	/** Per-field validators, keyed by {@link Path.toString}; seeded from `options.validators`. */
+	#fieldValidators;
+	/** In-flight async-validator fibers, keyed by `"<path>:<trigger>"` (fields) or `""` (whole-form `refineEffect`). */
+	#fibers = {};
+	/** The error paths the last `refineEffect` run set, so the next run can clear exactly those before merging fresh ones. */
+	#lastRefinementPaths = [];
+	/** The data snapshot the field-tracking watcher last diffed against. */
+	#previousData;
+	/** The current nested error tree (server errors merged with client errors), typed to the form data's shape. */
+	errors = $derived.by(() => mergeSourced(this.#sourced));
+	/** Client-side-sourced errors only (schema, per-field validators, `refineEffect`). */
+	clientErrors = $derived.by(() => this.#sourced.client);
+	/** Server-sourced errors only (the last submission's response). */
+	serverErrors = $derived.by(() => this.#sourced.server);
+	/** Whether any async field validator or `refineEffect` run is currently in flight. */
+	isValidating = $derived(Object.values(this.#validating).some(Boolean));
+	/** Whether the form has ever been submitted (attempted). */
+	isSubmitted = $derived(this.submissionAttempts > 0);
+	/** Whether the most recently *completed* submission succeeded. `false` before any submit completes. */
+	isSubmitSuccessful = $derived(this.#lastSubmitOutcome === "success");
+	/**
+	* Whether the submit button should be enabled: not mid-submit, not
+	* mid-validation, and either nothing has been validated yet (a pristine
+	* form isn't presumptively invalid — the server gets the first look) or the
+	* last validation run said valid.
+	*/
+	canSubmit = $derived(!this.submitting && !this.isValidating && (!this.#hasValidated || this.valid));
+	/** The tainted-field tree, re-derived as `data` changes. */
+	tainted = $derived.by(() => computeTainted(this.#initial, this.data));
+	/** Whether any field has been changed since the form was seeded. */
+	isTainted = $derived(isAnyTainted(this.tainted));
+	/** The tree of fields changed since the last submission (empty before any submit). */
+	changedSinceSubmit = $derived.by(() => this.#lastSubmitted === void 0 ? {} : computeTainted(this.#lastSubmitted, this.data));
+	/** Whether anything has changed since the last submission. */
+	hasChangedSinceSubmit = $derived(isAnyTainted(this.changedSinceSubmit));
+	constructor(initial, options = {}) {
+		this.id = initial.id;
+		this.#initial = structuredClone(initial.data);
+		this.#previousData = structuredClone(initial.data);
+		this.#options = options;
+		this.#mode = Mode.parse(options.mode);
+		this.#runtime = ManagedRuntime.make(options.layer ?? Layer.empty);
+		this.#fieldValidators = { ...options.validators };
+		this.data = structuredClone(initial.data);
+		this.#sourced = {
+			client: noErrors,
+			server: initial.errors ?? noErrors
+		};
+		this.message = initial.message;
+		this.constraints = initial.constraints ?? (options.schema ? Constraints.constraintsFromSchema(options.schema) : {});
+		this.posted = initial.posted;
+		this.valid = initial.valid;
+		this.#hasValidated = initial.posted;
+	}
+	/**
+	* Spreadable attributes for the `<form>` element: `<form {...form.props}>`.
+	* Sets `method="post"` (and `action`, if configured) and attaches the
+	* progressive-enhancement submit handler via a Svelte attachment.
+	*/
+	get props() {
+		return {
+			method: "post",
+			...this.#options.action !== void 0 ? { action: this.#options.action } : {},
+			[this.#attachmentKey]: this.#enhanceAttachment
+		};
+	}
+	/** Whether the field at `path` (or anything beneath it) is tainted. */
+	taintedAt(path) {
+		return isTaintedAt(this.tainted, path);
+	}
+	/** The messages currently attached to `path` (for dynamic / nested paths). */
+	errorsAt(path) {
+		return Errors.getError(this.errors, path) ?? [];
+	}
+	/** Whether the async validator(s) at `path` are currently running. */
+	isValidatingAt(path) {
+		const key = Path.toString(path);
+		return this.#validating[`${key}:change`] === true || this.#validating[`${key}:blur`] === true;
+	}
+	/**
+	* Register (or replace) `path`'s validators — the option-driven equivalent
+	* of attaching `validators` at {@link createForm} time, for fields that
+	* don't exist until later (e.g. an appended array item).
+	*/
+	setFieldValidators(path, validators) {
+		this.#fieldValidators = {
+			...this.#fieldValidators,
+			[Path.toString(path)]: validators
+		};
+	}
+	/** Re-validate the whole form against the schema (if one was supplied), plus a builder's `refineEffect` refinements. */
+	validate() {
+		if (this.#options.schema) {
+			const clientErrors = validateData(this.#options.schema, this.data, this.#options.validationFormat);
+			this.#sourced = {
+				...this.#sourced,
+				client: clientErrors
+			};
+			this.#hasValidated = true;
+			this.#recomputeValid();
+		}
+		this.#runRefineEffect();
+		return this.valid;
+	}
+	/** Validate a single field against the schema, returning that field's messages. */
+	validateField(path) {
+		if (!this.#options.schema) return this.errorsAt(path);
+		return validateField(this.#options.schema, this.data, path, this.#options.validationFormat);
+	}
+	/** Set the value at `path` (path-addressed, immutable). Bind directly to `data` otherwise. */
+	setValue(path, value) {
+		this.data = setAt(this.data, path, value);
+		this.#markDirty(path);
+		this.#previousData = this.#detachedData();
+		this.#onFieldChanged(path);
+	}
+	/** Read the value at `path`. */
+	valueAt(path) {
+		return getAt(this.data, path);
+	}
+	/** Mark the field at `path` touched (defaults to `true`) — drives `onBlur` display. */
+	setTouched(path, touched = true) {
+		this.#touched = {
+			...this.#touched,
+			[Path.toString(path)]: touched
+		};
+	}
+	/** Whether the field at `path` has been touched. */
+	isTouchedAt(path) {
+		return this.#touched[Path.toString(path)] === true;
+	}
+	/**
+	* Once a change away from the default at `path` is seen (per the current
+	* `data`, against `taintedAt`), sticks until {@link reset}. Called after
+	* `data` has already been updated, by every method that writes it
+	* (`setValue` and the array mutators below) — writing `data` directly
+	* (`bind:value={form.data.x}`) bypasses this, same as it bypasses `tainted`
+	* recomputing off anything but `data` itself would.
+	*/
+	#markDirty(path) {
+		const key = Path.toString(path);
+		if (!this.#dirtied[key] && this.taintedAt(path)) this.#dirtied = {
+			...this.#dirtied,
+			[key]: true
+		};
+	}
+	/** Whether the field at `path` was ever changed away from its default — see {@link FieldMeta.isDirty}. */
+	isDirtyAt(path) {
+		return this.#dirtied[Path.toString(path)] === true;
+	}
+	/** Whether the field at `path` currently holds its default value — the negation of {@link taintedAt}. */
+	isDefaultValueAt(path) {
+		return !this.taintedAt(path);
+	}
+	/** The native validation attributes for `path` (a leaf of {@link constraints}). */
+	constraintAt(path) {
+		return Constraints.constraintAt(this.constraints, path);
+	}
+	/**
+	* A typed, reactive handle to the field at `path` — see {@link FieldHandle}.
+	* `path` is type-checked against the form data's shape (see {@link
+	* Path.FieldPath}); a typo'd segment or wrong-shaped path is a compile error.
+	*/
+	field(path) {
+		return new FieldHandle(this, Path.fromString(path));
+	}
+	/**
+	* Handle a field losing focus: mark it touched, run its `onBlur` /
+	* `onBlurAsync` validators (or, once posted, the revalidate-on-blur mode),
+	* fire that field's `onBlur` listener (if any, debounced per its config),
+	* and — in `onBlur` validation mode — validate the whole form
+	* (auto-submitting if configured and something changed since the last
+	* submit).
+	*/
+	handleBlur(path) {
+		this.setTouched(path, true);
+		this.#onFieldBlurred(path);
+		const key = Path.toString(path);
+		const field = this.#options.listeners?.fields?.[key];
+		if (field?.onBlur) {
+			const value = this.valueAt(path);
+			this.#scheduleListener(`blur:${key}`, field.debounce, () => field.onBlur?.({
+				path,
+				value
+			}));
+		}
+		if (this.#mode.validation === "onBlur") {
+			this.validate();
+			if (this.#mode.autoSubmit && this.valid && this.#hasUnsubmittedChanges()) this.#autoSubmit();
+		}
+	}
+	/** Run `run` now, or after `debounce` (per-key timer, replacing any pending run for that key). */
+	#scheduleListener(key, debounce, run) {
+		if (debounce === void 0) {
+			run();
+			return;
+		}
+		clearTimeout(this.#listenerTimers.get(key));
+		this.#listenerTimers.set(key, setTimeout(() => {
+			this.#listenerTimers.delete(key);
+			run();
+		}, Duration.toMillis(debounce)));
+	}
+	/**
+	* The listeners table to dispatch change events against, with each field's
+	* `onChange` wrapped in this store's own debounce timer — or `undefined` if
+	* nothing is configured to consume a change (an `onMount`-only config, say),
+	* so the deep watcher can skip diffing the data tree entirely. Built once
+	* per {@link enhance} call rather than per change, since the listener table
+	* itself doesn't change across the mount's lifetime.
+	*/
+	#buildDispatchListeners() {
+		const listeners = this.#options.listeners;
+		if (!listeners || listeners.onChange === void 0 && !listeners.fields) return void 0;
+		if (!listeners.fields) return listeners;
+		const fields = {};
+		for (const [key, field] of Object.entries(listeners.fields)) fields[key] = field.onChange ? {
+			...field,
+			onChange: (input) => this.#scheduleListener(`change:${key}`, field.debounce, () => field.onChange?.(input))
+		} : field;
+		return {
+			...listeners,
+			fields
+		};
+	}
+	/**
+	* Whether there are edits worth auto-submitting: before any submit, any
+	* change from the seeded values; afterwards, any change since the last
+	* submission. Stops `autoSubmit` from re-posting server-echoed data in a loop.
+	*/
+	#hasUnsubmittedChanges() {
+		return this.#lastSubmitted === void 0 ? this.isTainted : this.hasChangedSinceSubmit;
+	}
+	/**
+	* Whether an error at `path` should be shown yet, per the validation mode:
+	* always after a submit; in `onChange` once the field is tainted; in `onBlur`
+	* once it is touched; never in `onSubmit` before posting.
+	*/
+	shouldShowError(path) {
+		if (this.posted) return true;
+		if (this.#mode.validation === "onChange") return this.taintedAt(path);
+		if (this.#mode.validation === "onBlur") return this.isTouchedAt(path);
+		return false;
+	}
+	/** The messages at `path`, but only when {@link shouldShowError} allows it. */
+	visibleErrorsAt(path) {
+		return this.shouldShowError(path) ? this.errorsAt(path) : [];
+	}
+	/** Read the array at `path` (empty when absent). */
+	#arrayAt(path) {
+		return getAt(this.data, path) ?? [];
+	}
+	/** Append an item to the array at `path` (a blank item is derived when omitted). */
+	append(path, value) {
+		const current = this.#arrayAt(path);
+		const item = value !== void 0 ? value : this.#defaultItem(path);
+		this.data = setAt(this.data, path, [...current, item]);
+		this.#markDirty(path);
+		this.#previousData = this.#detachedData();
+		this.#onFieldChanged(path);
+	}
+	/**
+	* Insert an item into the array at `path` at `index` (clamped to the
+	* array's bounds; a non-finite `index` inserts at the end), shifting later
+	* items — and their per-index touched flags / errors — up by one. A blank
+	* item is derived when `value` is omitted.
+	*/
+	insertItem(path, index, value) {
+		const current = this.#arrayAt(path);
+		const at = Math.max(0, Math.min(Number.isFinite(index) ? index : current.length, current.length));
+		const item = value !== void 0 ? value : this.#defaultItem(path);
+		this.data = setAt(this.data, path, [
+			...current.slice(0, at),
+			item,
+			...current.slice(at)
+		]);
+		this.#markDirty(path);
+		this.#remapArrayIndices(path, Path.insertAt(at));
+	}
+	/**
+	* Replace the item at `index` in the array at `path` in place. Drops that
+	* index's own touched flag / errors (they described the old value); other
+	* indices are untouched.
+	*/
+	replaceItem(path, index, value) {
+		const current = this.#arrayAt(path);
+		if (!inRange(index, current.length)) return;
+		const next = [...current];
+		next[index] = value;
+		this.data = setAt(this.data, path, next);
+		this.#markDirty(path);
+		this.#remapArrayIndices(path, Path.replaceAt(index));
+	}
+	/** Remove every item from the array at `path`, dropping all of its per-index state. */
+	clearItems(path) {
+		this.data = setAt(this.data, path, []);
+		this.#markDirty(path);
+		this.#remapArrayIndices(path, Path.clearAll);
+	}
+	/**
+	* Remove the item at `index` from the array at `path`, shifting later
+	* items' per-index touched flags / errors down by one so they keep
+	* following their row.
+	*/
+	removeItem(path, index) {
+		const current = this.#arrayAt(path);
+		if (!inRange(index, current.length)) return;
+		this.data = setAt(this.data, path, current.filter((_, i) => i !== index));
+		this.#markDirty(path);
+		this.#remapArrayIndices(path, Path.removeAt(index));
+		this.#previousData = this.#detachedData();
+		this.#onFieldChanged(path);
+	}
+	/** Swap two items in the array at `path`, swapping their per-index touched flags / errors too. */
+	swap(path, indexA, indexB) {
+		const current = this.#arrayAt(path);
+		if (!inRange(indexA, current.length) || !inRange(indexB, current.length) || indexA === indexB) return;
+		const next = [...current];
+		[next[indexA], next[indexB]] = [next[indexB], next[indexA]];
+		this.data = setAt(this.data, path, next);
+		this.#markDirty(path);
+		this.#remapArrayIndices(path, Path.swapAt(indexA, indexB));
+		this.#previousData = this.#detachedData();
+		this.#onFieldChanged(path);
+	}
+	/** Move the item at `from` to `to` within the array at `path`, carrying its per-index state along. */
+	move(path, from, to) {
+		const current = this.#arrayAt(path);
+		if (!inRange(from, current.length) || to < 0 || to >= current.length || from === to) return;
+		const next = [...current];
+		const [item] = next.splice(from, 1);
+		next.splice(to, 0, item);
+		this.data = setAt(this.data, path, next);
+		this.#markDirty(path);
+		this.#remapArrayIndices(path, Path.moveAt(from, to));
+		this.#previousData = this.#detachedData();
+		this.#onFieldChanged(path);
+	}
+	/**
+	* Remap the per-index touched flags and errors under the array at `path`
+	* through `map`, so state recorded against a row follows it through an
+	* index-shifting mutation. See {@link Path.IndexMap}.
+	*/
+	#remapArrayIndices(path, map) {
+		const sourced = this.#sourcedSnapshot();
+		this.#sourced = {
+			client: Errors.remapIndices(sourced.client, path, map),
+			server: Errors.remapIndices(sourced.server, path, map)
+		};
+		this.#touched = Path.remapKeyedRecord(this.#touched, path, map);
+	}
+	/** Revert `data` to the values sent by the last submission (no-op before any submit). */
+	revertToLastSubmit() {
+		if (this.#lastSubmitted === void 0) return;
+		this.data = structuredClone($state.snapshot(this.#lastSubmitted));
+		this.#previousData = this.#detachedData();
+		this.#sourced = emptySourced;
+	}
+	/**
+	* Derive a blank item for the array field at `path`, at any nesting depth
+	* (e.g. `authors[0].emails`) — by walking the bound schema's AST there when
+	* one is available, falling back to a top-level {@link FormOptions.fields}
+	* lookup, else `""`.
+	*/
+	#defaultItem(path) {
+		if (this.#options.schema) return Field.defaultItemAt(this.#options.schema, path);
+		const fields = this.#options.fields;
+		if (fields && path.length === 1 && typeof path[0] === "string") {
+			const def = fields[path[0]];
+			if (def && Field.isArrayFieldDef(def)) return Field.defaultValue(def.itemSchema);
+		}
+		return "";
+	}
+	/** Submit via the enhanced node, if one is mounted and not already in flight. */
+	#autoSubmit() {
+		if (this.submitting || this.#autoSubmitNode === void 0) return;
+		this.#runSubmit(this.#autoSubmitNode);
+	}
+	/** Debounced (in `onChange`) whole-form validation, auto-submitting when valid. */
+	#scheduleValidation() {
+		const run = () => {
+			this.validate();
+			if (this.#mode.autoSubmit && this.valid && this.#hasUnsubmittedChanges()) this.#autoSubmit();
+		};
+		const ms = this.#mode.debounce;
+		if (ms !== null && ms > 0) {
+			clearTimeout(this.#validateTimer);
+			this.#validateTimer = setTimeout(run, ms);
+		} else run();
+	}
+	#recomputeValid() {
+		this.valid = !hasErrors(mergeSourced(this.#sourced));
+	}
+	/**
+	* A plain (non-`$state`-proxy) snapshot of `#sourced`. `clearSourceAt` /
+	* `setSourceAt` / `replaceAt` in the framework-neutral core `structuredClone`
+	* their `errors` argument — which throws `DataCloneError` on a live Svelte
+	* `$state` proxy — so anywhere `#sourced` (or one of its two branches) feeds
+	* one of those calls, snapshot it first.
+	*/
+	#sourcedSnapshot() {
+		return $state.snapshot(this.#sourced);
+	}
+	/** Whether {@link Mode.ParsedMode.revalidate} names this field trigger. */
+	#revalidatesOn(trigger) {
+		if (this.#mode.revalidate === "never") return false;
+		return this.#mode.revalidate === "onChange" ? trigger === "change" : trigger === "blur";
+	}
+	/** Interrupt (fire-and-forget) any fiber running under `key`, if one is in flight. */
+	#interruptFiber(key) {
+		const previous = this.#fibers[key];
+		if (previous) Effect.runFork(Fiber.interrupt(previous));
+		delete this.#fibers[key];
+	}
+	/**
+	* Fork `effect` under `key` as an interrupt-on-supersede fiber, toggling
+	* `#validating[key]` for its duration: any fiber already running under
+	* `key` is interrupted first (this — not a timer — is what gives "latest
+	* wins"; see {@link Validate.runAsyncFieldValidator}). The old and new
+	* fiber's `#validating` writes are guarded by a per-key generation counter
+	* — `Effect.runFork(Fiber.interrupt(previous))` is fire-and-forget, so the
+	* *old* fiber's `Effect.ensuring` finalizer can run after the *new* one has
+	* already flipped `#validating[key]` back to `true`; without the guard that
+	* finalizer would clear it while the new run is still genuinely in flight.
+	*/
+	#runValidatorFiber(key, effect) {
+		this.#interruptFiber(key);
+		const generation = (this.#validatingGeneration[key] ?? 0) + 1;
+		this.#validatingGeneration[key] = generation;
+		this.#validating = {
+			...this.#validating,
+			[key]: true
+		};
+		const program = effect.pipe(Effect.ensuring(Effect.sync(() => {
+			if (this.#validatingGeneration[key] === generation) this.#validating = {
+				...this.#validating,
+				[key]: false
+			};
+		})));
+		this.#fibers[key] = this.#runtime.runFork(program);
+	}
+	/**
+	* Handle a field's value actually changing: the field's server-sourced
+	* error (if any) is superseded — clear it — then run whichever validators
+	* apply for the `"change"` trigger.
+	*/
+	#onFieldChanged(path) {
+		this.#sourced = clearSourceAt(this.#sourcedSnapshot(), "server", path);
+		this.#runFieldTrigger(path, "change");
+		this.#recomputeValid();
+	}
+	/** Handle a field losing focus: run whichever validators apply for the `"blur"` trigger. */
+	#onFieldBlurred(path) {
+		this.#runFieldTrigger(path, "blur");
+		this.#recomputeValid();
+	}
+	/**
+	* Run `path`'s sync + async validators for `trigger` (resolved by {@link
+	* Validate.resolveFieldTrigger}). When neither is registered, falls back to
+	* a whole-schema {@link validateField} re-run once the form has been
+	* posted and {@link Mode.ParsedMode.revalidate} names this trigger — the
+	* "fixing a field clears its error without a resubmit" behaviour.
+	*/
+	#runFieldTrigger(path, trigger) {
+		const validators = this.#fieldValidators[Path.toString(path)];
+		const value = getAt(this.data, path);
+		const resolved = Validate.resolveFieldTrigger(validators, trigger);
+		if (resolved.sync) this.#applySyncFieldValidator(path, resolved.sync, value);
+		else if (this.#shouldFallBackToRevalidate(trigger)) this.#applyRevalidateFallback(path);
+		if (resolved.async) {
+			this.#hasValidated = true;
+			this.#runAsyncFieldValidator(path, trigger, resolved.async, value, resolved.asyncDebounceMs);
+		}
+	}
+	/** Run a field's registered sync validator and set its client messages. */
+	#applySyncFieldValidator(path, validator, value) {
+		this.#setClientMessagesAt(path, Validate.runSyncFieldValidator(validator, value));
+		this.#hasValidated = true;
+	}
+	/** Whether, absent a registered validator, a whole-schema fallback revalidation applies for `trigger`. */
+	#shouldFallBackToRevalidate(trigger) {
+		return this.posted && this.#revalidatesOn(trigger) && this.#options.schema !== void 0;
+	}
+	/** Re-run the whole-schema client validation and adopt just `path`'s messages. */
+	#applyRevalidateFallback(path) {
+		this.#sourced = setSourceAt(this.#sourcedSnapshot(), "client", path, this.validateField(path));
+		this.#hasValidated = true;
+	}
+	/** Replace `path`'s client messages with `issues`' messages (folding {@link FormIssue}s at the field's own path). */
+	#setClientMessagesAt(path, issues) {
+		this.#sourced = setSourceAt(this.#sourcedSnapshot(), "client", path, issues.map((issue) => issue.message));
+	}
+	/**
+	* Run `path`'s `trigger` async validator as an interrupt-on-supersede
+	* fiber (via {@link FormStore.#runValidatorFiber}) — the result (unless
+	* the fiber is itself later interrupted) replaces the field's client
+	* messages.
+	*/
+	#runAsyncFieldValidator(path, trigger, validator, value, debounceMs) {
+		const fiberKey = `${Path.toString(path)}:${trigger}`;
+		this.#runValidatorFiber(fiberKey, Validate.runAsyncFieldValidator(validator, value, debounceMs).pipe(Effect.tap((issues) => Effect.sync(() => {
+			this.#setClientMessagesAt(path, issues);
+			this.#recomputeValid();
+		}))));
+	}
+	/**
+	* Run the builder's `refineEffect` refinements (client-side, when the form
+	* was seeded from a {@link FormBuilder}) as a whole-form async validator —
+	* interrupt-on-supersede, same as a field's async validator (see {@link
+	* FormStore.#runValidatorFiber}). The previous run's issue *paths* are
+	* cleared before the fresh ones are merged in, so a superseded run can't
+	* leave stale messages behind without disturbing schema-derived client
+	* errors set by {@link validate} in between.
+	*/
+	#runRefineEffect() {
+		const builder = this.#options.builder;
+		if (!builder || FormBuilder.asyncRefinements(builder).length === 0) return;
+		this.#runValidatorFiber("", FormBuilder.runAsyncRefinements(builder, this.data).pipe(Effect.tap((issues) => Effect.sync(() => {
+			let client = this.#sourcedSnapshot().client;
+			for (const path of this.#lastRefinementPaths) client = replaceAt(client, path, []);
+			client = Errors.mergeErrors(client, Errors.issuesToErrors(issues));
+			this.#lastRefinementPaths = issues.map((issue) => issue.path);
+			this.#sourced = {
+				...this.#sourced,
+				client
+			};
+			this.#recomputeValid();
+		}))));
+	}
+	/**
+	* Reset `data`, `errors`, and `message` back to the tainted baseline. Pass
+	* `values` to re-seed that baseline first (e.g. adopting a different
+	* entity's values) instead of returning to the original seed.
+	*/
+	reset(values) {
+		if (values !== void 0) this.#initial = structuredClone(values);
+		for (const key of Object.keys(this.#fibers)) this.#interruptFiber(key);
+		this.data = structuredClone(this.#initial);
+		this.#previousData = this.#detachedData();
+		this.#sourced = emptySourced;
+		this.message = void 0;
+		this.valid = false;
+		this.posted = false;
+		this.#touched = {};
+		this.#dirtied = {};
+		this.#lastSubmitted = void 0;
+		this.#hasValidated = false;
+		this.#validating = {};
+		this.#lastRefinementPaths = [];
+		this.submissionAttempts = 0;
+		this.#lastSubmitOutcome = void 0;
+	}
+	/** A serialisable snapshot for SvelteKit's `snapshot` capture/restore. */
+	capture() {
+		return {
+			id: this.id,
+			valid: this.valid,
+			posted: this.posted,
+			data: this.#detachedData(),
+			errors: this.errors,
+			message: this.message,
+			constraints: this.constraints
+		};
+	}
+	/**
+	* An independent deep copy of `data`, detached from the live `$state`
+	* proxy. `structuredClone` can't clone the proxy directly (Node's
+	* structured-clone algorithm rejects it); take a plain snapshot first, per
+	* Svelte's own guidance for this exact case.
+	*/
+	#detachedData() {
+		return structuredClone($state.snapshot(this.data));
+	}
+	/** Restore from a {@link capture} snapshot (its merged tree becomes the server tree; the client tree clears). */
+	restore(snapshot) {
+		this.data = structuredClone(snapshot.data);
+		this.#previousData = this.#detachedData();
+		this.#sourced = {
+			client: noErrors,
+			server: snapshot.errors
+		};
+		this.message = snapshot.message;
+		this.valid = snapshot.valid;
+		this.posted = snapshot.posted;
+		this.constraints = snapshot.constraints ?? {};
+		this.#hasValidated = snapshot.posted;
+	}
+	/**
+	* Apply server-sourced `data` + `errors` directly, bypassing a submit
+	* round-trip — for glue code that repopulates the store from a derived
+	* result it received some other way (e.g.
+	* {@link module:effect-forms-svelte/SvelteKit}'s `applyActionResult`, from
+	* a SvelteKit form action's failure). Sets `posted` so
+	* {@link shouldShowError} shows the new errors immediately; `valid` is
+	* always `false` (the caller only reaches for this on a failure result).
+	*/
+	setServerState(data, errors) {
+		this.data = data;
+		this.#previousData = structuredClone(data);
+		this.#sourced = {
+			client: noErrors,
+			server: errors
+		};
+		this.valid = false;
+		this.posted = true;
+		this.#hasValidated = true;
+	}
+	#applyUpdate(update, result) {
+		this.#options.onUpdate?.({
+			update,
+			result
+		});
+		if (update.redirect !== void 0) return this.#applyRedirect(update.redirect);
+		if (update.error !== void 0) return this.#applyError(update.error);
+		if (update.data !== void 0) this.#applySubmittedData(update.data, result);
+		this.#sourced = {
+			client: noErrors,
+			server: update.errors ?? noErrors
+		};
+		this.#hasValidated = true;
+		this.message = update.message;
+		if (update.valid !== void 0) this.valid = update.valid;
+		this.#lastSubmitOutcome = this.valid ? "success" : "failure";
+		this.posted = true;
+		this.#options.onUpdated?.({ form: {
+			data: this.data,
+			errors: this.errors,
+			valid: this.valid
+		} });
+	}
+	#applyRedirect(location) {
+		this.#lastSubmitOutcome = "success";
+		if (this.#options.onRedirect) this.#options.onRedirect({ location });
+		else if (typeof window !== "undefined") window.location.assign(location);
+	}
+	#applyError(error) {
+		this.#lastSubmitOutcome = "failure";
+		this.#options.onError?.({ error });
+	}
+	/**
+	* Adopt (or discard) the submission's echoed data via {@link
+	* computeDataApplication} and rebase the tainted baseline. An
+	* auto-submitting (live-save) form keeps its local data as the source of
+	* truth: adopting the server's echo would discard keystrokes made during
+	* the round-trip and, when the echo isn't byte-identical (a trimmed or
+	* server-stamped field), retrigger the change watcher — an extra submit,
+	* or an endless loop for a non-idempotent echo. On a successful submit the
+	* tainted baseline still rebases to whatever `data` ends up holding, so
+	* `isTainted` (and the `beforeunload` guard it drives) reflects what was
+	* actually just saved, not the original seed.
+	*/
+	#applySubmittedData(data, result) {
+		const applied = computeDataApplication({
+			isSuccess: result._tag === "Success",
+			appliedData: data,
+			initial: this.#initial,
+			submittedData: $state.snapshot(this.#lastSubmitted ?? this.data),
+			resetForm: this.#options.resetForm ?? false,
+			autoSubmit: this.#mode.autoSubmit
+		});
+		if (applied.data !== void 0) this.data = structuredClone(applied.data);
+		if (applied.rebaseTo !== void 0) {
+			this.#initial = structuredClone(applied.rebaseTo);
+			this.#touched = {};
+		}
+		this.#previousData = this.#detachedData();
+	}
+	async #runSubmit(node, submitter = null) {
+		const formData = new FormData(node, submitter);
+		let cancelled = false;
+		let resolved;
+		await this.#options.onSubmit?.({
+			data: this.data,
+			formData,
+			form: node,
+			submitter,
+			cancel: () => {
+				cancelled = true;
+			},
+			resolve: (result) => {
+				resolved = result;
+			}
+		});
+		if (cancelled) return;
+		this.#lastSubmitted = this.#detachedData();
+		this.submissionAttempts++;
+		this.submitting = true;
+		const delayMs = this.#options.delayMs ?? 500;
+		const delayTimer = setTimeout(() => {
+			this.delayed = true;
+		}, delayMs);
+		try {
+			const submit = this.#options.submit ?? defaultSubmit;
+			const action = node.action || (typeof location !== "undefined" ? location.href : "");
+			let result;
+			if (resolved !== void 0) result = resolved;
+			else if (this.#options.handler) result = await this.#options.handler(this.data);
+			else result = await submit(formData, action, node);
+			this.#options.onResult?.({ result });
+			this.#applyUpdate(resultToUpdate(result), result);
+		} catch (cause) {
+			const message = cause instanceof Error ? cause.message : "Submission failed";
+			this.#lastSubmitOutcome = "failure";
+			this.#options.onError?.({ error: message });
+		} finally {
+			clearTimeout(delayTimer);
+			this.submitting = false;
+			this.delayed = false;
+		}
+	}
+	/**
+	* Progressive-enhancement form action. Use as `<form use:form.enhance>` (or
+	* spread {@link FormStore.props}). Intercepts submit, runs the `onSubmit`
+	* handler, then sends the body and applies the result. Without JavaScript the
+	* form posts normally.
+	*/
+	enhance = (node) => {
+		const handleSubmit = (event) => {
+			event.preventDefault();
+			this.#runSubmit(node, event.submitter);
+		};
+		node.addEventListener("submit", handleSubmit);
+		const beforeUnload = (event) => {
+			if (this.#options.taintedMessage && this.isTainted) event.preventDefault();
+		};
+		if (this.#options.taintedMessage && typeof window !== "undefined") window.addEventListener("beforeunload", beforeUnload);
+		this.#autoSubmitNode = node;
+		this.#options.listeners?.onMount?.({ data: $state.snapshot(this.data) });
+		const dispatchListeners = this.#buildDispatchListeners();
+		let stopWatching;
+		if (this.#mode.validation === "onChange" || dispatchListeners !== void 0) {
+			let previous = $state.snapshot(this.data);
+			stopWatching = $effect.root(() => {
+				$effect(() => {
+					const snapshot = $state.snapshot(this.data);
+					if (this.#mode.validation === "onChange" && (this.isTainted || this.posted)) this.#scheduleValidation();
+					if (dispatchListeners !== void 0) dispatchChange(previous, snapshot, dispatchListeners);
+					previous = snapshot;
+				});
+			});
+		}
+		const stopFieldWatching = $effect.root(() => {
+			$effect(() => {
+				const snapshot = $state.snapshot(this.data);
+				const changed = taintedLeafPaths(computeTainted(this.#previousData, snapshot));
+				this.#previousData = snapshot;
+				for (const path of changed) this.#onFieldChanged(path);
+			});
+		});
+		return { destroy: () => {
+			node.removeEventListener("submit", handleSubmit);
+			if (typeof window !== "undefined") window.removeEventListener("beforeunload", beforeUnload);
+			stopWatching?.();
+			stopFieldWatching?.();
+			clearTimeout(this.#validateTimer);
+			for (const timer of this.#listenerTimers.values()) clearTimeout(timer);
+			this.#listenerTimers.clear();
+			for (const key of Object.keys(this.#fibers)) this.#interruptFiber(key);
+			if (this.#autoSubmitNode === node) this.#autoSubmitNode = void 0;
+		} };
+	};
+	/** Attachment form of {@link FormStore.enhance} for {@link FormStore.props}. */
+	#enhanceAttachment = (node) => this.enhance(node).destroy;
+	/** Build a {@link FormData} body from the current data (SPA / manual submit). */
+	toFormData() {
+		return objectToFormData(this.data);
+	}
+};
+function createForm(source, options = {}) {
+	if (FormBuilder.isFormBuilder(source)) {
+		const schema = FormBuilder.buildSchema(source);
+		return new FormStore(Form.fromBuilder(source, {
+			...options.defaults !== void 0 ? { defaults: options.defaults } : {},
+			...options.id !== void 0 ? { id: options.id } : {}
+		}).empty(), {
+			...options,
+			schema,
+			fields: source.fields,
+			builder: source
+		});
+	}
+	if ("defaults" in source && "schema" in source) {
+		const seed = source;
+		return new FormStore(makeForm(seed.schema, {
+			defaults: seed.defaults,
+			...seed.id !== void 0 ? { id: seed.id } : {}
+		}).empty(), {
+			...options,
+			schema: seed.schema
+		});
+	}
+	return new FormStore(source, options);
+}
+//#endregion
+export { FieldHandle, FormStore, createForm };
+
+//# sourceMappingURL=FormStore.svelte.js.map