@thomasfosterau/effect-forms-svelte 0.0.0

package/dist/EntityForm.js

@@ -0,0 +1,103 @@
+import { Command } from "@thomasfosterau/effect-forms";
+import * as Schema from "effect/Schema";
+//#region src/EntityForm.ts
+const builders = {
+	text: (key, options) => ({
+		_tag: "scalar",
+		key,
+		multiline: false,
+		options
+	}),
+	textarea: (key, options) => ({
+		_tag: "scalar",
+		key,
+		multiline: true,
+		options
+	}),
+	select: (key, options) => ({
+		_tag: "select",
+		key,
+		options
+	}),
+	custom: (key, component, props, options = {}) => ({
+		_tag: "widget",
+		key,
+		bridge: "value",
+		component,
+		props,
+		options
+	}),
+	rows: (key, component, props, options = {}) => ({
+		_tag: "widget",
+		key,
+		bridge: "rows",
+		component,
+		props,
+		options
+	})
+};
+/**
+* Validate an `f.select` entry against its plan field at definition time: the
+* field must be `enum`-kind (the only kind `Command.plan` derives option
+* values for), and every derived value must have a matching `optionLabels`
+* thunk.
+*/
+const validateSelectEntry = (entry, field) => {
+	if (field.kind !== "enum") throw new Error(`defineEntityForm: entry "${entry.key}" is f.select but its command field is "${field.kind}"-kind, not enum`);
+	const missingLabels = (field.options ?? []).filter((value) => !Object.prototype.hasOwnProperty.call(entry.options.optionLabels, value));
+	if (missingLabels.length > 0) throw new Error(`defineEntityForm: entry "${entry.key}" is missing optionLabels for: ${missingLabels.join(", ")}`);
+};
+/**
+* Build an entity-form definition from a command-struct pair and an ordered
+* entry list. Runs once at module load. Throws when the entries don't cover
+* the derivable command fields exactly (exhaustiveness) or name an unknown
+* key — a command-struct change must surface here, at definition time.
+*/
+const defineEntityForm = (options, build) => {
+	const omitted = new Set(options.omit ?? []);
+	const withoutOmitted = (struct) => {
+		if (omitted.size === 0) return struct;
+		const fields = {};
+		for (const key in struct.fields) if (!omitted.has(key)) fields[key] = struct.fields[key];
+		return { fields };
+	};
+	const plan = Command.plan(withoutOmitted(options.create), withoutOmitted(options.update));
+	const entries = build(builders);
+	const byKey = new Map(plan.fields.map((field) => [field.key, field]));
+	const declared = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		const field = byKey.get(entry.key);
+		if (field === void 0) throw new Error(`defineEntityForm: entry "${entry.key}" is not a field of either command struct`);
+		if (declared.has(entry.key)) throw new Error(`defineEntityForm: entry "${entry.key}" is declared twice`);
+		declared.add(entry.key);
+		if (entry._tag === "select") validateSelectEntry(entry, field);
+	}
+	const missing = plan.fields.filter((field) => !declared.has(field.key)).map((field) => field.key);
+	if (missing.length > 0) throw new Error(`defineEntityForm: command fields not declared by any entry: ${missing.join(", ")} — declare or explicitly widget them`);
+	const entriesFor = (mode) => entries.filter((entry) => {
+		const field = byKey.get(entry.key);
+		return field !== void 0 && (mode === "create" ? field.inCreate : field.inUpdate);
+	});
+	return {
+		plan,
+		entries,
+		createInput: Schema.Struct(Command.formInputFields(plan, "create", options.inputOverrides?.create)),
+		updateInput: Schema.Struct(Command.formInputFields(plan, "update", options.inputOverrides?.update)),
+		createDefaults: Command.blankDefaults(plan, "create"),
+		updateDefaults: Command.blankDefaults(plan, "update"),
+		adaptCreate: Command.createAdapter(plan, options.adaptOverrides?.create),
+		adaptUpdate: Command.updateAdapter(plan, options.adaptOverrides?.update),
+		submit: options.submit,
+		clientId: plan.clientId,
+		entriesFor,
+		fieldFor: (key) => {
+			const field = byKey.get(key);
+			if (field === void 0) throw new Error(`EntityFormDefinition: unknown field "${key}"`);
+			return field;
+		}
+	};
+};
+//#endregion
+export { defineEntityForm };
+
+//# sourceMappingURL=EntityForm.js.map

package/dist/EntityForm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityForm.js","names":[],"sources":["../src/EntityForm.ts"],"sourcesContent":["/**\n * @copyright Thomas Foster\n *\n * The typed entity-form definition builder — the composition layer of the\n * schema-driven form phase. `defineEntityForm(commands, (f) => [...])` pairs a\n * `Command.plan` derivation (form-input schemas, blank defaults, tri-state\n * adapters — see `effect-forms/Command`) with an ordered list of typed field\n * entries: shared scalar primitives by kind, and arbitrary widget components\n * for the bespoke fields (pickers, contributor lists). One generic renderer\n * component walks `definition.entries`; per-entity code shrinks to one\n * definition module.\n *\n * Field keys are type-constrained to the command structs' keys, and the\n * builder enforces exhaustiveness at definition time (a runtime check, kept\n * deliberately simple over deep conditional types): every derivable command\n * field must be declared exactly once, so adding a field to a command struct\n * breaks the entity's definition module until the form declares it.\n *\n * Labels and other message-bearing props are **thunks** (`() => string`,\n * Paraglide message function references) resolved at render time, never at\n * module scope — module-scope resolution would freeze the import-time locale.\n *\n * @module effect-forms-svelte/EntityForm\n */\n\nimport type { Component } from \"svelte\";\nimport { Command } from \"@thomasfosterau/effect-forms\";\nimport * as Schema from \"effect/Schema\";\n\n/** A render-time message thunk — pass the Paraglide function itself, uncalled. */\nexport type MessageThunk = () => string;\n\n/** Presentation options for a scalar text entry. */\nexport interface TextEntryOptions {\n  readonly label: MessageThunk;\n  /** Presentation `type` attribute (`url`, `date`). Omitted → text input. */\n  readonly type?: \"text\" | \"url\" | \"date\";\n  /** Keyboard hint for numeric text fields; defaults from the field's derived kind. */\n  readonly inputmode?: \"numeric\";\n  /** Force required-ness (defaults to the schema-derived constraint). */\n  readonly required?: boolean;\n  readonly placeholder?: MessageThunk;\n}\n\n/** A scalar field rendered by the shared text/textarea primitives. */\nexport interface ScalarEntry {\n  readonly _tag: \"scalar\";\n  readonly key: string;\n  readonly multiline: boolean;\n  readonly options: TextEntryOptions;\n}\n\n/** Presentation options for a `<select>` entry over a literal-union (`enum` kind) field. */\nexport interface SelectEntryOptions {\n  readonly label: MessageThunk;\n  readonly required?: boolean;\n  /**\n   * Per-option render-time label thunks, keyed by the field's derived option\n   * *value* (`Command.FieldPlan.options`, read via `fieldFor` — not declared\n   * here). `defineEntityForm` throws at definition time if a derived value has\n   * no matching thunk.\n   */\n  readonly optionLabels: Readonly<Record<string, MessageThunk>>;\n}\n\n/**\n * A `<select>` field over a literal-union (`enum` kind) command field. Option\n * *values* derive from the field's plan; this entry supplies only the\n * per-option labels — `defineEntityForm` validates the field is `enum`-kind\n * and that every derived value has a label.\n */\nexport interface SelectEntry {\n  readonly _tag: \"select\";\n  readonly key: string;\n  readonly options: SelectEntryOptions;\n}\n\n/** Options for a widget entry (picker / rows list). */\nexport interface WidgetEntryOptions {\n  /** Gate the submit button while this field's value is empty (required pickers). */\n  readonly gate?: boolean;\n}\n\n/**\n * A bespoke widget field. The renderer bridges the store to the widget through\n * the stage-1 wrapper contract — `name`, `value`, `onChange`, `errors` — which\n * are **reserved keys**: the bridge is spread last, so a `props()` thunk or a\n * load-supplied field prop can never silently sever the store binding.\n */\nexport interface WidgetEntry {\n  readonly _tag: \"widget\";\n  readonly key: string;\n  /** `\"value\"` bridges a string FK; `\"rows\"` bridges a controlled row list. */\n  readonly bridge: \"value\" | \"rows\";\n  // reason: the renderer composes arbitrary widgets; per-widget prop checking\n  // happens in the definition module via the builder's generic signature.\n  readonly component: Component<any>;\n  readonly props: () => Record<string, unknown>;\n  readonly options: WidgetEntryOptions;\n}\n\n/** One ordered entry in an entity form definition. */\nexport type EntityFormEntry = ScalarEntry | WidgetEntry | SelectEntry;\n\n/** The per-mode submit labels. */\nexport interface SubmitMessages {\n  readonly create: MessageThunk;\n  readonly update: MessageThunk;\n}\n\n/** The runtime shape `defineEntityForm` accepts for a command struct. */\nexport interface CommandStructLike {\n  readonly fields: Record<string, Schema.Top>;\n}\n\n/** The value `defineEntityForm` returns — everything one renderer needs. */\nexport interface EntityFormDefinition {\n  readonly plan: Command.CommandPlan;\n  readonly entries: readonly EntityFormEntry[];\n  readonly createInput: Schema.Top;\n  readonly updateInput: Schema.Top;\n  readonly createDefaults: Readonly<Record<string, string>>;\n  readonly updateDefaults: Readonly<Record<string, string>>;\n  readonly adaptCreate: (input: Command.FormInputRecord) => Record<string, unknown>;\n  readonly adaptUpdate: (input: Command.FormInputRecord) => Record<string, unknown>;\n  readonly submit: SubmitMessages;\n  /** The create struct carries a client-generated id (idempotent retries). */\n  readonly clientId: boolean;\n  /** Entries visible in one mode, in declaration order. */\n  readonly entriesFor: (mode: \"create\" | \"update\") => readonly EntityFormEntry[];\n  /** The plan field behind an entry key. */\n  readonly fieldFor: (key: string) => Command.FieldPlan;\n}\n\n/** The writable command keys a definition may declare (the `id` key is renderer-owned). */\nexport type CommandKeys<C extends CommandStructLike, U extends CommandStructLike> = Exclude<\n  Extract<keyof C[\"fields\"] | keyof U[\"fields\"], string>,\n  \"id\"\n>;\n\n/** The entry builders handed to the definition callback, key-typed to the command pair. */\nexport interface EntryBuilders<K extends string> {\n  /** A scalar field rendered by the shared `TextInputField`. */\n  text(key: K, options: TextEntryOptions): EntityFormEntry;\n  /** A scalar field rendered by the shared `TextAreaInputField`. */\n  textarea(key: K, options: TextEntryOptions): EntityFormEntry;\n  /**\n   * A `<select>` field over a literal-union (`enum` kind) command field.\n   * Option values are derived from the field's plan; `options.optionLabels`\n   * supplies each derived value's render-time label thunk.\n   */\n  select(key: K, options: SelectEntryOptions): EntityFormEntry;\n  /**\n   * A bespoke string-valued widget (an FK picker). The renderer supplies\n   * `name` / `value` / `onChange` / `errors`; `props()` supplies the rest at\n   * render time (labels stay thunk-resolved).\n   */\n  custom<P extends Record<string, unknown>>(\n    key: K,\n    component: Component<never>,\n    props: () => P,\n    options?: WidgetEntryOptions,\n  ): EntityFormEntry;\n  /**\n   * A bespoke row-list widget (a contributor list). The renderer owns the row\n   * state and supplies `name` / `value` / `onChange` / `errors`; the widget\n   * owns the wire serialisation (its hidden input).\n   */\n  rows<P extends Record<string, unknown>>(\n    key: K,\n    component: Component<never>,\n    props: () => P,\n    options?: WidgetEntryOptions,\n  ): EntityFormEntry;\n}\n\n/** Everything `defineEntityForm` needs beyond the entries. */\nexport interface DefineEntityFormOptions<C extends CommandStructLike, U extends CommandStructLike> {\n  readonly create: C;\n  readonly update: U;\n  readonly submit: SubmitMessages;\n  /** Per-field adapter overrides, per mode — the irregular-coercion escape hatch. */\n  readonly adaptOverrides?: {\n    readonly create?: Command.AdaptOverrides;\n    readonly update?: Command.AdaptOverrides;\n  };\n  /** Per-field Form-Input schema overrides, per mode (e.g. an optional create title with a server default). */\n  readonly inputOverrides?: {\n    readonly create?: Readonly<Record<string, Schema.Top>>;\n    readonly update?: Readonly<Record<string, Schema.Top>>;\n  };\n  /**\n   * Command fields deliberately absent from the standalone form (a carve-out,\n   * e.g. BookSeries' `editors` — managed through the Book form's inline-create\n   * path instead). Omitted fields are stripped from the create/update field\n   * records before `Command.plan` runs, so they need no entry, are never\n   * classified (a kind-less omitted field can't throw at definition time),\n   * and never appear in the derived input schema, defaults, or adapters.\n   */\n  readonly omit?: readonly CommandKeys<C, U>[];\n}\n\nconst builders: EntryBuilders<string> = {\n  text: (key, options) => ({ _tag: \"scalar\", key, multiline: false, options }),\n  textarea: (key, options) => ({ _tag: \"scalar\", key, multiline: true, options }),\n  select: (key, options) => ({ _tag: \"select\", key, options }),\n  custom: (key, component, props, options = {}) => ({\n    _tag: \"widget\",\n    key,\n    bridge: \"value\",\n    component: component as Component<any>,\n    props,\n    options,\n  }),\n  rows: (key, component, props, options = {}) => ({\n    _tag: \"widget\",\n    key,\n    bridge: \"rows\",\n    component: component as Component<any>,\n    props,\n    options,\n  }),\n};\n\n/**\n * Validate an `f.select` entry against its plan field at definition time: the\n * field must be `enum`-kind (the only kind `Command.plan` derives option\n * values for), and every derived value must have a matching `optionLabels`\n * thunk.\n */\nconst validateSelectEntry = (entry: SelectEntry, field: Command.FieldPlan): void => {\n  if (field.kind !== \"enum\") {\n    throw new Error(\n      `defineEntityForm: entry \"${entry.key}\" is f.select but its command field is \"${field.kind}\"-kind, not enum`,\n    );\n  }\n  const missingLabels = (field.options ?? []).filter(\n    (value) => !Object.prototype.hasOwnProperty.call(entry.options.optionLabels, value),\n  );\n  if (missingLabels.length > 0) {\n    throw new Error(\n      `defineEntityForm: entry \"${entry.key}\" is missing optionLabels for: ${missingLabels.join(\", \")}`,\n    );\n  }\n};\n\n/**\n * Build an entity-form definition from a command-struct pair and an ordered\n * entry list. Runs once at module load. Throws when the entries don't cover\n * the derivable command fields exactly (exhaustiveness) or name an unknown\n * key — a command-struct change must surface here, at definition time.\n */\nexport const defineEntityForm = <C extends CommandStructLike, U extends CommandStructLike>(\n  options: DefineEntityFormOptions<C, U>,\n  build: (f: EntryBuilders<CommandKeys<C, U>>) => readonly EntityFormEntry[],\n): EntityFormDefinition => {\n  const omitted = new Set<string>(options.omit ?? []);\n  const withoutOmitted = (struct: CommandStructLike): CommandStructLike => {\n    if (omitted.size === 0) return struct;\n    const fields: Record<string, Schema.Top> = {};\n    for (const key in struct.fields) if (!omitted.has(key)) fields[key] = struct.fields[key];\n    return { fields };\n  };\n  const plan = Command.plan(withoutOmitted(options.create), withoutOmitted(options.update));\n  const entries = build(builders as EntryBuilders<CommandKeys<C, U>>);\n\n  const byKey = new Map<string, Command.FieldPlan>(plan.fields.map((field) => [field.key, field]));\n  const declared = new Set<string>();\n  for (const entry of entries) {\n    const field = byKey.get(entry.key);\n    if (field === undefined) {\n      throw new Error(\n        `defineEntityForm: entry \"${entry.key}\" is not a field of either command struct`,\n      );\n    }\n    if (declared.has(entry.key)) {\n      throw new Error(`defineEntityForm: entry \"${entry.key}\" is declared twice`);\n    }\n    declared.add(entry.key);\n    if (entry._tag === \"select\") validateSelectEntry(entry, field);\n  }\n  const missing = plan.fields.filter((field) => !declared.has(field.key)).map((field) => field.key);\n  if (missing.length > 0) {\n    throw new Error(\n      `defineEntityForm: command fields not declared by any entry: ${missing.join(\", \")} — declare or explicitly widget them`,\n    );\n  }\n\n  const entriesFor = (mode: \"create\" | \"update\") =>\n    entries.filter((entry) => {\n      const field = byKey.get(entry.key);\n      return field !== undefined && (mode === \"create\" ? field.inCreate : field.inUpdate);\n    });\n\n  return {\n    plan,\n    entries,\n    createInput: Schema.Struct(\n      Command.formInputFields(plan, \"create\", options.inputOverrides?.create) as Record<\n        string,\n        never\n      >,\n    ),\n    updateInput: Schema.Struct(\n      Command.formInputFields(plan, \"update\", options.inputOverrides?.update) as Record<\n        string,\n        never\n      >,\n    ),\n    createDefaults: Command.blankDefaults(plan, \"create\"),\n    updateDefaults: Command.blankDefaults(plan, \"update\"),\n    adaptCreate: Command.createAdapter(plan, options.adaptOverrides?.create),\n    adaptUpdate: Command.updateAdapter(plan, options.adaptOverrides?.update),\n    submit: options.submit,\n    clientId: plan.clientId,\n    entriesFor,\n    fieldFor: (key: string) => {\n      const field = byKey.get(key);\n      if (field === undefined) throw new Error(`EntityFormDefinition: unknown field \"${key}\"`);\n      return field;\n    },\n  };\n};\n"],"mappings":"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"}

package/dist/FormStore.svelte.d.ts

@@ -0,0 +1,381 @@
+import { FormUpdate } from "./EnhanceCore.js";
+import { FormListeners } from "./Listeners.js";
+import { TaintedFields } from "./Tainted.js";
+import { Constraints, Errors, Field, FormBuilder, Issues, Mode, Path, Result, State, Validate } from "@thomasfosterau/effect-forms";
+import * as Schema from "effect/Schema";
+import * as Layer from "effect/Layer";
+//#region src/FormStore.svelte.d.ts
+type FormActionResult<A, Message = unknown> = Result.FormActionResult<A, Message>;
+type FormErrors = Errors.FormErrors;
+type FormPath = Issues.FormPath;
+type FormState<A, Message = unknown> = State.FormState<A, Message>;
+type TypedFormErrors<A> = Errors.TypedFormErrors<A>;
+type InputConstraint = Constraints.InputConstraint;
+type InputConstraints = Constraints.InputConstraints;
+type LeafFormatter = Issues.LeafFormatter;
+/** How a form validates (and optionally auto-submits, and revalidates after a post) as the user types. */
+type FormMode = Mode.FormMode;
+/** A field's sync / async validators — see {@link module:effect-forms/Validate}. */
+type FieldValidators<A, R = never> = Validate.FieldValidators<A, R>;
+/** Per-field state exposed on a {@link FieldHandle}, mirroring TanStack Form's field meta. */
+interface FieldMeta {
+  /** Changed at some point, or blurred (TanStack: `isTouched = isDirty || isBlurred`). */
+  readonly isTouched: boolean;
+  /** Has lost focus at least once — distinct from {@link isTouched}. */
+  readonly isBlurred: boolean;
+  /**
+   * Was changed away from its default value at some point, via `field.value =
+   * …` (or another {@link FormStore} write method). Persistent: unlike {@link
+   * isDefaultValue}, this does not flip back to `false` if the value is later
+   * reverted to the default — only {@link FormStore.reset} clears it.
+   */
+  readonly isDirty: boolean;
+  /** Whether the current value is (still, or again) equal to the field's default. */
+  readonly isDefaultValue: boolean;
+}
+/**
+ * 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.
+ */
+declare class FieldHandle<V> {
+  #private;
+  /** The path in flat field-name notation — use as the input's `name` attribute. */
+  readonly name: string;
+  constructor(store: FormStore<Schema.Top, object, unknown>, path: FormPath);
+  /** The field's current value. Assignable — `bind:value={field.value}` works. */
+  get value(): V;
+  set value(next: V);
+  /** All messages currently attached to this field. */
+  get errors(): readonly string[];
+  /** This field's messages, gated by the form's validation mode (see {@link FormStore.shouldShowError}). */
+  get visibleErrors(): readonly string[];
+  /** Native validation attributes for this field — spread onto the `<input>`. */
+  get constraints(): InputConstraint;
+  /** This field's {@link FieldMeta}. */
+  get meta(): FieldMeta;
+  /** Mark this field blurred — see {@link FormStore.handleBlur}. */
+  handleBlur: () => void;
+}
+/** Transport: turn a submission into a {@link FormActionResult}. Defaults to `fetch`. */
+type SubmitFn<A, Message> = (body: FormData, action: string, form: HTMLFormElement) => Promise<FormActionResult<A, Message>>;
+/** The submission passed to an {@link FormOptions.onSubmit} handler. */
+interface Submission<A, Message> {
+  /** The current (reactive) form data. */
+  readonly data: A;
+  /** The multipart body that would be posted. */
+  readonly formData: FormData;
+  /** The form element being submitted. */
+  readonly form: HTMLFormElement;
+  /**
+   * The submit button that triggered this submission (its `name`/`value` is
+   * already folded into {@link Submission.formData}, matching native
+   * `new FormData(form, submitter)` semantics), or `null` for an auto-submit
+   * (no button was clicked).
+   */
+  readonly submitter: HTMLElement | null;
+  /** Abort the submission entirely (no network request, no result applied). */
+  readonly cancel: () => void;
+  /**
+   * Resolve the submission with a result computed in JS (e.g. via an API
+   * client), instead of letting the default network POST run. The result is
+   * applied to the store exactly as a server response would be.
+   */
+  readonly resolve: (result: FormActionResult<A, Message>) => void;
+}
+/** Options for {@link createForm}. */
+interface FormOptions<S extends Schema.Top, A, Message, R = never> {
+  /** The schema to validate against in the browser (defaults to the bound schema). */
+  readonly schema?: S;
+  /**
+   * When the form validates as the user types (and whether it auto-submits) —
+   * see {@link module:effect-forms/Mode}. Defaults to `onSubmit`. `onChange` /
+   * `onBlur` auto-validate the form; use {@link FormStore.shouldShowError} /
+   * {@link FormStore.visibleErrorsAt} to gate display per field.
+   */
+  readonly mode?: FormMode;
+  /**
+   * The builder's field record, set automatically when {@link createForm} is
+   * given a {@link FormBuilder}. A fallback for deriving a blank array item
+   * when no `schema` is bound — with a schema, {@link FormStore.append} /
+   * {@link FormStore.insertItem} resolve the item (at any nesting depth) by
+   * walking the schema's AST instead.
+   */
+  readonly fields?: Field.FieldsRecord;
+  /**
+   * The builder itself, set automatically when {@link createForm} is given a
+   * {@link FormBuilder}. Its `refineEffect` refinements run client-side as a
+   * whole-form async validator whenever {@link FormStore.validate} runs.
+   */
+  readonly builder?: FormBuilder.FormBuilder<Field.FieldsRecord, R>;
+  /** The action URL the form posts to (defaults to the current page's action). */
+  readonly action?: string;
+  /** Reset `data` back to the initial values after a successful submit. */
+  readonly resetForm?: boolean;
+  /** Warn (via `beforeunload`) when navigating away with unsaved changes. */
+  readonly taintedMessage?: string | false;
+  /** Milliseconds before an in-flight submission flips `delayed` to `true`. */
+  readonly delayMs?: number;
+  /** Override the message rendering used by client-side validation. */
+  readonly validationFormat?: LeafFormatter;
+  /** Override how a submission is sent (default: `fetch` to the form's action). */
+  readonly submit?: SubmitFn<A, Message>;
+  /**
+   * Per-field sync/async validators, keyed by {@link Path.toString} (e.g.
+   * `"author.name"`, `"tags[0]"`). See {@link FormStore.setFieldValidators} to
+   * register these dynamically instead (e.g. once an array item exists).
+   */
+  readonly validators?: Record<string, FieldValidators<any, R>>;
+  /**
+   * Services an async field validator or a builder's `refineEffect`
+   * refinement needs on its `R` channel. A `ManagedRuntime` is built from
+   * this once per store and reused for every client-side Effect run.
+   */
+  readonly layer?: Layer.Layer<R>;
+  /**
+   * Handle the submission entirely in JS: given the current data, return the
+   * {@link FormActionResult} to apply (e.g. by calling an API client). When set,
+   * this runs instead of the network POST — the "handled using JS on the page"
+   * path. `onSubmit`'s `cancel()` / `resolve()` still take precedence.
+   */
+  readonly handler?: (data: A) => FormActionResult<A, Message> | Promise<FormActionResult<A, Message>>;
+  /**
+   * Handle the submission in JS on the page. Receives the data + form, can
+   * `cancel()` it or `resolve(result)` it directly; if it neither cancels nor
+   * resolves, the default network POST runs.
+   */
+  readonly onSubmit?: (input: Submission<A, Message>) => void | Promise<void>;
+  /** Called with the raw {@link FormActionResult} once the response is parsed. */
+  readonly onResult?: (input: {
+    readonly result: FormActionResult<A, Message>;
+  }) => void;
+  /** Called with the computed {@link FormUpdate} before it is applied. */
+  readonly onUpdate?: (input: {
+    readonly update: FormUpdate<A, Message>;
+    readonly result: FormActionResult<A, Message>;
+  }) => void;
+  /** Called after the update has been applied to the store. */
+  readonly onUpdated?: (input: {
+    readonly form: {
+      readonly data: A;
+      readonly errors: FormErrors;
+      readonly valid: boolean;
+    };
+  }) => void;
+  /** Called on an unexpected (non-user-fixable) error. */
+  readonly onError?: (input: {
+    readonly error: string;
+  }) => void;
+  /** Called on a redirect result (default: `window.location.assign`). */
+  readonly onRedirect?: (input: {
+    readonly location: string;
+  }) => void;
+  /**
+   * Field- and form-level listeners (onMount / onChange / onBlur) — see
+   * {@link module:effect-forms-svelte/Listeners}. Fire independent of
+   * `mode`'s validation, and tear down with {@link FormStore.enhance}'s
+   * `destroy`.
+   */
+  readonly listeners?: FormListeners;
+}
+/** A reactive form, returned by {@link createForm}. */
+declare class FormStore<S extends Schema.Top, A = S["Type"], Message = unknown, R = never> {
+  #private;
+  /** The reactive form data — bind inputs to its fields. */
+  data: A;
+  /** The current status message, if any. */
+  message: Message | undefined;
+  /** Native input constraints derived server-side. */
+  constraints: InputConstraints;
+  /** Whether a submission is in flight. */
+  submitting: boolean;
+  /** Whether the in-flight submission has passed `delayMs`. */
+  delayed: boolean;
+  /** Whether the current state came from a submission. */
+  posted: boolean;
+  /** Whether the last validation/submit was valid. */
+  valid: boolean;
+  /** How many times {@link FormStore.enhance}'s submit handler has actually attempted a submission. */
+  submissionAttempts: number;
+  readonly id: string;
+  /** The current nested error tree (server errors merged with client errors), typed to the form data's shape. */
+  readonly errors: TypedFormErrors<A>;
+  /** Client-side-sourced errors only (schema, per-field validators, `refineEffect`). */
+  readonly clientErrors: TypedFormErrors<A>;
+  /** Server-sourced errors only (the last submission's response). */
+  readonly serverErrors: TypedFormErrors<A>;
+  /** Whether any async field validator or `refineEffect` run is currently in flight. */
+  readonly isValidating: boolean;
+  /** Whether the form has ever been submitted (attempted). */
+  readonly isSubmitted: boolean;
+  /** Whether the most recently *completed* submission succeeded. `false` before any submit completes. */
+  readonly isSubmitSuccessful: boolean;
+  /**
+   * 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.
+   */
+  readonly canSubmit: boolean;
+  /** The tainted-field tree, re-derived as `data` changes. */
+  readonly tainted: TaintedFields;
+  /** Whether any field has been changed since the form was seeded. */
+  readonly isTainted: boolean;
+  /** The tree of fields changed since the last submission (empty before any submit). */
+  readonly changedSinceSubmit: TaintedFields;
+  /** Whether anything has changed since the last submission. */
+  readonly hasChangedSinceSubmit: boolean;
+  constructor(initial: FormState<A, Message>, options?: FormOptions<S, A, Message, R>);
+  /**
+   * 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(): Record<string | symbol, unknown>;
+  /** Whether the field at `path` (or anything beneath it) is tainted. */
+  taintedAt(path: FormPath): boolean;
+  /** The messages currently attached to `path` (for dynamic / nested paths). */
+  errorsAt(path: FormPath): readonly string[];
+  /** Whether the async validator(s) at `path` are currently running. */
+  isValidatingAt(path: FormPath): boolean;
+  /**
+   * 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: FormPath, validators: FieldValidators<unknown, R>): void;
+  /** Re-validate the whole form against the schema (if one was supplied), plus a builder's `refineEffect` refinements. */
+  validate(): boolean;
+  /** Validate a single field against the schema, returning that field's messages. */
+  validateField(path: FormPath): readonly string[];
+  /** Set the value at `path` (path-addressed, immutable). Bind directly to `data` otherwise. */
+  setValue(path: FormPath, value: unknown): void;
+  /** Read the value at `path`. */
+  valueAt(path: FormPath): unknown;
+  /** Mark the field at `path` touched (defaults to `true`) — drives `onBlur` display. */
+  setTouched(path: FormPath, touched?: boolean): void;
+  /** Whether the field at `path` has been touched. */
+  isTouchedAt(path: FormPath): boolean;
+  /** Whether the field at `path` was ever changed away from its default — see {@link FieldMeta.isDirty}. */
+  isDirtyAt(path: FormPath): boolean;
+  /** Whether the field at `path` currently holds its default value — the negation of {@link taintedAt}. */
+  isDefaultValueAt(path: FormPath): boolean;
+  /** The native validation attributes for `path` (a leaf of {@link constraints}). */
+  constraintAt(path: FormPath): InputConstraint;
+  /**
+   * 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<P extends Path.FieldPath<A>>(path: P): FieldHandle<Path.PathValue<A, P>>;
+  /**
+   * 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: FormPath): void;
+  /**
+   * 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: FormPath): boolean;
+  /** The messages at `path`, but only when {@link shouldShowError} allows it. */
+  visibleErrorsAt(path: FormPath): readonly string[];
+  /** Append an item to the array at `path` (a blank item is derived when omitted). */
+  append(path: FormPath, value?: unknown): void;
+  /**
+   * 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: FormPath, index: number, value?: unknown): void;
+  /**
+   * 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: FormPath, index: number, value: unknown): void;
+  /** Remove every item from the array at `path`, dropping all of its per-index state. */
+  clearItems(path: FormPath): void;
+  /**
+   * 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: FormPath, index: number): void;
+  /** Swap two items in the array at `path`, swapping their per-index touched flags / errors too. */
+  swap(path: FormPath, indexA: number, indexB: number): void;
+  /** Move the item at `from` to `to` within the array at `path`, carrying its per-index state along. */
+  move(path: FormPath, from: number, to: number): void;
+  /** Revert `data` to the values sent by the last submission (no-op before any submit). */
+  revertToLastSubmit(): void;
+  /**
+   * 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?: A): void;
+  /** A serialisable snapshot for SvelteKit's `snapshot` capture/restore. */
+  capture(): FormState<A, Message>;
+  /** Restore from a {@link capture} snapshot (its merged tree becomes the server tree; the client tree clears). */
+  restore(snapshot: FormState<A, Message>): void;
+  /**
+   * 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: A, errors: FormErrors): void;
+  /**
+   * 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: HTMLFormElement) => {
+    destroy: () => void;
+  };
+  /** Build a {@link FormData} body from the current data (SPA / manual submit). */
+  toFormData(): FormData;
+}
+/** A schema plus its blank-form defaults — what {@link createForm} wraps `makeForm` over. */
+interface FormSeed<S extends Schema.Top> {
+  readonly schema: S;
+  readonly defaults: S["Type"];
+  readonly id?: string;
+}
+/** The built-schema type a {@link FormBuilder} of `TFields` / `R` collapses to. */
+type BuiltSchema<TFields extends Field.FieldsRecord, R> = Schema.Codec<Field.DecodedFromFields<TFields>, Field.EncodedFromFields<TFields>, R>;
+/** Options for the {@link createForm} {@link FormBuilder} overload. */
+type FormBuilderOptions<TFields extends Field.FieldsRecord, R, Message> = FormOptions<BuiltSchema<TFields, R>, Field.EncodedFromFields<TFields>, Message, R> & {
+  /** Blank-form values. Defaults to a schema-derived encoded blank per field. */
+  readonly defaults?: Field.EncodedFromFields<TFields>;
+  /** Distinguishes multiple forms on a page. Defaults to `"default"`. */
+  readonly id?: string;
+};
+/**
+ * Create a reactive {@link FormStore}. Three sources are accepted:
+ *
+ * - a {@link FormBuilder} — the schema, blank defaults, and array-item defaults
+ *   are all derived from the builder (client validation, including
+ *   `refineEffect` refinements, is wired automatically);
+ * - `{ schema, defaults }` — seed a blank form (wrapping the core's `makeForm`);
+ * - a server-produced {@link FormState} — hydrate from it (schema in `options`).
+ */
+declare function createForm<TFields extends Field.FieldsRecord, R, Message = unknown>(builder: FormBuilder.FormBuilder<TFields, R>, options?: FormBuilderOptions<TFields, R, Message>): FormStore<BuiltSchema<TFields, R>, Field.EncodedFromFields<TFields>, Message, R>;
+declare function createForm<S extends Schema.Top, Message = unknown, R = never>(seed: FormSeed<S>, options?: FormOptions<S, S["Type"], Message, R>): FormStore<S, S["Type"], Message, R>;
+declare function createForm<S extends Schema.Top, A = S["Type"], Message = unknown, R = never>(initial: FormState<A, Message>, options: FormOptions<S, A, Message, R>): FormStore<S, A, Message, R>;
+//#endregion
+export { FieldHandle, FieldMeta, FieldValidators, FormBuilderOptions, FormMode, FormOptions, FormSeed, FormStore, Submission, SubmitFn, createForm };
+//# sourceMappingURL=FormStore.svelte.d.ts.map