@thomasfosterau/effect-forms-svelte 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Foster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @thomasfosterau/effect-forms-svelte
+
+Svelte 5 (runes) bindings for [`@thomasfosterau/effect-forms`](../effect-forms). A reactive form store with progressive-enhancement submission, tainted tracking, lifecycle events, and optional client-side validation against the **same Effect Schema the server uses**.
+
+This package depends only on `svelte` (a peer) and the framework-neutral core — not SvelteKit — so it works in any Svelte 5 app.
+
+## Usage
+
+Server (`+page.server.ts` or any action) produces a `FormState` with the core's `makeForm`, and returns it to the page. The component hydrates it:
+
+```svelte
+<script lang="ts">
+  import { createForm } from "@thomasfosterau/effect-forms-svelte";
+  import { Signup } from "$lib/schemas";
+
+  let { data } = $props(); // data.form is the server FormState
+
+  const form = createForm(data.form, {
+    schema: Signup,        // enables client-side validation
+    resetForm: true,
+    taintedMessage: "You have unsaved changes.",
+    onUpdated: ({ form }) => form.valid && toast("Saved"),
+  });
+</script>
+
+<form method="post" use:form.enhance>
+  <input name="name" bind:value={form.data.name} />
+  {#each form.errorsAt(["name"]) as message}<small>{message}</small>{/each}
+
+  <button disabled={form.submitting}>
+    {form.delayed ? "Saving…" : "Save"}
+  </button>
+</form>
+```
+
+## The store
+
+`createForm(source, options)` returns a [`FormStore`](src/FormStore.svelte.ts). `source` is a server-produced `FormState`, a `{ schema, defaults }` seed, or a [`FormBuilder`](../effect-forms/src/FormBuilder.ts) — the builder derives its schema, blank defaults, and array-item defaults for you:
+
+```ts
+import { createForm } from "@thomasfosterau/effect-forms-svelte";
+import { signup } from "$lib/forms"; // a FormBuilder
+
+const form = createForm(signup, { mode: { validation: "onChange", debounce: 300 } });
+```
+
+**Reactive state** — `data` (mutable, bind inputs to it), `errors` (merged client + server), `clientErrors` / `serverErrors` (per-source views), `message`, `constraints`, `submitting`, `delayed`, `posted`, `valid`, `canSubmit`, `isValidating`, `isSubmitted`, `isSubmitSuccessful`, `submissionAttempts`, `tainted`, `isTainted`, and (against the last submission) `changedSinceSubmit` / `hasChangedSinceSubmit`.
+
+**Methods** — `enhance(node)` (the form action), `validate()` / `validateField(path)` (client-side, needs `schema`; also runs a builder's `refineEffect` refinements), `errorsAt(path)` / `taintedAt(path)` / `isValidatingAt(path)`, `setValue(path, v)` / `valueAt(path)`, `handleBlur(path)` / `setTouched(path)` / `isTouchedAt(path)`, `isDirtyAt(path)` / `isDefaultValueAt(path)` (persistent per-field dirty tracking — see [Field handles](#field-handles)), `setFieldValidators(path, validators)` (register a field's validators dynamically), `shouldShowError(path)` / `visibleErrorsAt(path)` (mode-aware display gating), `constraintAt(path)`, `revertToLastSubmit()`, `reset()`, `capture()` / `restore()` (SvelteKit snapshots), `setServerState(data, errors)` (apply a result received some other way), `toFormData()`.
+
+**Field arrays** — `append(path, value?)`, `insertItem(path, i, value?)`, `replaceItem(path, i, value)`, `removeItem(path, i)`, `clearItems(path)`, `swap(path, a, b)`, `move(path, from, to)` mutate the array at `path` immutably. `append` / `insertItem` derive a blank item by walking the bound schema's AST at `path` (any nesting depth, e.g. `authors[0].emails`), falling back to the top-level `FormBuilder` field when no schema is bound. Every index-shifting mutation (`insertItem` / `removeItem` / `swap` / `move` / `clearItems`) remaps per-index touched flags and errors so they keep following their row — `replaceItem` drops only the replaced index's own touched flag / errors.
+
+## Field handles
+
+`form.field(path)` (modelled on TanStack Form's `FieldApi`) returns a typed, reactive [`FieldHandle`](src/FormStore.svelte.ts) bundling everything one input needs, instead of wiring `bind:value` / `name` / `handleBlur` / `visibleErrorsAt` / `constraints` against the store separately:
+
+```svelte
+<script lang="ts">
+  const name = form.field("author.name"); // deep paths are type-checked
+</script>
+
+<input
+  name={name.name}
+  bind:value={name.value}
+  onblur={name.handleBlur}
+  {...name.constraints}
+/>
+{#each name.visibleErrors as message}<small>{message}</small>{/each}
+```
+
+`path` is checked against the form data's shape via `Path.FieldPath<A>` — a typo'd segment (`"authr.name"`) or a path into a field that doesn't exist is a compile error, and `field.value` is the leaf's actual type, not `unknown`. This replaced the core's unconsumed `FieldRef` seam.
+
+`field.meta` exposes TanStack-style field state: `isBlurred` (lost focus at least once), `isTouched` (`isBlurred || isDirty`), `isDirty` (changed away from the default at some point — **persistent**, unlike `taintedAt` it does not clear on reverting to the default; only `reset()` clears it), and `isDefaultValue` (current value equals the default — flips back on revert). `isDirty` only tracks writes made through `field.value = …` / `setValue` / the array mutators (`append` / `removeItem` / `swap` / `move`) — a form that still binds `bind:value={form.data.x}` directly, bypassing `field()`, never marks that field dirty.
+
+**Validation modes** — the `mode` option (see [`Mode`](../effect-forms/src/Mode.ts)) drives when the form validates: `onSubmit` (default), `onBlur` (call `handleBlur` from an input's blur), or `onChange` (debounced). `onBlur` / `onChange` may `autoSubmit`, turning the form into a live-saving surface. `revalidate` (`"onChange"` default / `"onBlur"` / `"never"`) governs what happens _after_ a failed post in `onSubmit` mode: fixing a field re-validates just that field, clearing its error without a resubmit. Errors are computed for the whole form; gate their display per field with `visibleErrorsAt(path)` (shown only once the field is tainted / touched, or after a submit).
+
+**Per-field validators** — the `validators` option (or `setFieldValidators`) attaches TanStack-Form-style `{ onChange?, onBlur?, onChangeAsync?, onBlurAsync?, asyncDebounceMs? }` per field, keyed by `Path.toString` (e.g. `"author.name"`, `"tags[0]"`). Sync validators return a `Schema.FilterOutput`; async ones are `Effect`s, run as a fiber per field — a new value interrupts the field's in-flight fiber before forking the next run, which is what gives the debounce + "latest wins" cancellation (no timer bookkeeping needed). Pass `layer` when a validator (or a builder's `refineEffect` refinement) needs services on its `R` channel:
+
+```ts
+const form = createForm(
+  { schema: Signup, defaults: { username: "" } },
+  {
+    validators: {
+      username: {
+        onChangeAsync: (value) => Api.checkUsernameAvailable(value as string),
+        asyncDebounceMs: 300,
+      },
+    },
+    layer: ApiClient.layer,
+  },
+);
+```
+
+**Error sources** — a field's server-reported error (from the last submission) survives a client-side revalidation of some _other_ field; it clears once _that_ field's own value changes (or the server clears it on the next submit). `errors` is the merged view; `clientErrors` / `serverErrors` expose the two trees separately for a UI that wants to style them differently.
+
+**Lifecycle options** — `onSubmit` (with `cancel()`), `onResult`, `onUpdate`, `onUpdated`, `onError`, `onRedirect`, plus `resetForm`, `taintedMessage`, `delayMs`, and a `submit` transport override (defaults to `fetch` to the form's action, parsing a JSON [`FormActionResult`](../effect-forms/src/Result.ts) or a bare `FormState`).
+
+## Layout
+
+The reactive store lives in `FormStore.svelte.ts` (rune-compiled, checked by `svelte-check`). Its logic is delegated to pure, unit-tested modules:
+
+| Module                                    | Purpose                                                                   |
+| ----------------------------------------- | ------------------------------------------------------------------------- |
+| [`Tainted`](src/Tainted.ts)               | Deep-diff the data to compute the tainted tree.                           |
+| [`ClientValidate`](src/ClientValidate.ts) | Validate the form / one field against the schema.                         |
+| [`EnhanceCore`](src/EnhanceCore.ts)       | Serialise data → form body, parse the response, compute the store update. |
+
+The store itself is mostly exercised only by `svelte-check`, but the submitter-aware enhanced submit path (`enhance` → `#runSubmit` → the posted `FormData`) is directly unit-tested in [`FormStore.svelte.test.ts`](tests/FormStore.svelte.test.ts) — a `.svelte.ts` rune file needs the Svelte compiler to run at all, hence the `.svelte.test.ts` extension and the `svelte()` plugin in `vite.config.ts` (scoped to a `happy-dom` DOM via a per-file `@vitest-environment` docblock, not the package default).
+
+## Development
+
+```sh
+vp exec svelte-check --tsconfig ./tsconfig.json   # typecheck (incl. runes)
+vp test run tests                                 # unit tests (pure modules + the submit path)
+```

package/dist/ClientValidate.d.ts

@@ -0,0 +1,18 @@
+import { Errors, Issues } from "@thomasfosterau/effect-forms";
+import * as Schema from "effect/Schema";
+//#region src/ClientValidate.d.ts
+type FormErrors = Errors.FormErrors;
+type FormPath = Issues.FormPath;
+type LeafFormatter = Issues.LeafFormatter;
+/** Validate the whole form's data, returning the nested error tree (empty when valid). */
+declare function validateData<S extends Schema.Top>(schema: S, data: unknown, format?: LeafFormatter): FormErrors;
+/**
+ * Validate the whole form and return just the messages at `path`. Validating
+ * the whole object (rather than the leaf in isolation) keeps cross-field rules
+ * working; the caller merges the result into its existing error tree for that
+ * field only.
+ */
+declare function validateField<S extends Schema.Top>(schema: S, data: unknown, path: FormPath, format?: LeafFormatter): readonly string[];
+//#endregion
+export { validateData, validateField };
+//# sourceMappingURL=ClientValidate.d.ts.map

package/dist/ClientValidate.js

@@ -0,0 +1,37 @@
+import { Errors, Validate } from "@thomasfosterau/effect-forms";
+//#region src/ClientValidate.ts
+/**
+* @copyright Thomas Foster
+*
+* Client-side validation helpers — validate the whole form or a single field
+* against the same Effect Schema the server uses, returning the nested
+* {@link FormErrors} tree (or one field's messages).
+*
+* Re-running the schema in the browser gives instant feedback; this is
+* the framework-neutral plumbing the Svelte store calls. Schemas used here must
+* have no decoding-service requirements (the common case for form schemas) so
+* validation can run synchronously in an event handler.
+*
+* @module effect-forms-svelte/ClientValidate
+*/
+const { getError, noErrors } = Errors;
+const { validateValueSync } = Validate;
+/** Validate the whole form's data, returning the nested error tree (empty when valid). */
+function validateData(schema, data, format) {
+	const result = validateValueSync(schema, data, format);
+	return result.valid ? noErrors : result.errors;
+}
+/**
+* Validate the whole form and return just the messages at `path`. Validating
+* the whole object (rather than the leaf in isolation) keeps cross-field rules
+* working; the caller merges the result into its existing error tree for that
+* field only.
+*/
+function validateField(schema, data, path, format) {
+	const errors = validateData(schema, data, format);
+	return getError(errors, path) ?? [];
+}
+//#endregion
+export { validateData, validateField };
+
+//# sourceMappingURL=ClientValidate.js.map

package/dist/ClientValidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientValidate.js","names":[],"sources":["../src/ClientValidate.ts"],"sourcesContent":["/**\n * @copyright Thomas Foster\n *\n * Client-side validation helpers — validate the whole form or a single field\n * against the same Effect Schema the server uses, returning the nested\n * {@link FormErrors} tree (or one field's messages).\n *\n * Re-running the schema in the browser gives instant feedback; this is\n * the framework-neutral plumbing the Svelte store calls. Schemas used here must\n * have no decoding-service requirements (the common case for form schemas) so\n * validation can run synchronously in an event handler.\n *\n * @module effect-forms-svelte/ClientValidate\n */\n\nimport { Errors, Issues, Validate } from \"@thomasfosterau/effect-forms\";\n\n// Terse local aliases onto the namespaced core exports.\ntype FormErrors = Errors.FormErrors;\ntype FormPath = Issues.FormPath;\ntype LeafFormatter = Issues.LeafFormatter;\nconst { getError, noErrors } = Errors;\nconst { validateValueSync } = Validate;\nimport type * as Schema from \"effect/Schema\";\n\n/** Validate the whole form's data, returning the nested error tree (empty when valid). */\nexport function validateData<S extends Schema.Top>(\n  schema: S,\n  data: unknown,\n  format?: LeafFormatter,\n): FormErrors {\n  const result = validateValueSync(schema, data, format);\n  return result.valid ? noErrors : result.errors;\n}\n\n/**\n * Validate the whole form and return just the messages at `path`. Validating\n * the whole object (rather than the leaf in isolation) keeps cross-field rules\n * working; the caller merges the result into its existing error tree for that\n * field only.\n */\nexport function validateField<S extends Schema.Top>(\n  schema: S,\n  data: unknown,\n  path: FormPath,\n  format?: LeafFormatter,\n): readonly string[] {\n  const errors = validateData(schema, data, format);\n  return getError(errors, path) ?? [];\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAqBA,MAAM,EAAE,UAAU,aAAa;AAC/B,MAAM,EAAE,sBAAsB;;AAI9B,SAAgB,aACd,QACA,MACA,QACY;CACZ,MAAM,SAAS,kBAAkB,QAAQ,MAAM,MAAM;CACrD,OAAO,OAAO,QAAQ,WAAW,OAAO;AAC1C;;;;;;;AAQA,SAAgB,cACd,QACA,MACA,MACA,QACmB;CACnB,MAAM,SAAS,aAAa,QAAQ,MAAM,MAAM;CAChD,OAAO,SAAS,QAAQ,IAAI,KAAK,CAAC;AACpC"}

package/dist/EnhanceCore.d.ts

@@ -0,0 +1,61 @@
+import { Errors, Result } from "@thomasfosterau/effect-forms";
+//#region src/EnhanceCore.d.ts
+type FormActionResult<A, Message = unknown> = Result.FormActionResult<A, Message>;
+type FormErrors = Errors.FormErrors;
+/** Flatten a nested data object into `[name, value]` entries using path notation. */
+declare function objectToEntries(data: unknown, prefix?: string): Array<[string, string]>;
+/** Serialise the store's data into a {@link FormData} body for submission. */
+declare function objectToFormData(data: unknown): FormData;
+/**
+ * Normalise a parsed JSON response body into a {@link FormActionResult}. The
+ * server may return a full action result (`{ _tag, … }`) or a bare
+ * {@link FormState} — a bare state maps to `Success` / `Failure` by its `valid`
+ * flag, using `status` for the failure code.
+ */
+declare function parseActionResult<A, Message>(body: unknown, status?: number): FormActionResult<A, Message>;
+/** The mutation a {@link FormActionResult} implies for the store. */
+interface FormUpdate<A, Message> {
+  readonly data?: A | undefined;
+  readonly errors?: FormErrors | undefined;
+  readonly message?: Message | undefined;
+  readonly redirect?: string | undefined;
+  readonly error?: string | undefined;
+  readonly valid?: boolean | undefined;
+}
+/**
+ * Compute the store update implied by a {@link FormActionResult}. Pure: the
+ * caller applies the returned fields to its reactive state and acts on
+ * `redirect` / `error`.
+ */
+declare function resultToUpdate<A, Message>(result: FormActionResult<A, Message>): FormUpdate<A, Message>;
+/** How a successful/failed submit's data should land on `data` and the tainted baseline. */
+interface DataApplication<A> {
+  /** The next value for `data`, or `undefined` to leave it untouched (an auto-submit keeps local edits). */
+  readonly data: A | undefined;
+  /** The next tainted baseline (`#initial`), or `undefined` when this isn't a successful submit. */
+  readonly rebaseTo: A | undefined;
+}
+/**
+ * Decide how a submit result's data applies to the store, given a defined
+ * `update.data` (redirects/errors never reach this — see {@link resultToUpdate}).
+ * Pure so the save-then-navigate baseline rebase is unit-testable without
+ * compiling the rune store: on a successful submit the tainted baseline
+ * rebases to whatever was actually persisted, so `isTainted` goes back to
+ * `false` for values that were just saved, not just the original seed. An
+ * auto-submitting (live-save) form keeps its local `data` as the source of
+ * truth while a request is in flight — adopting the server's echo would
+ * discard keystrokes made during the round-trip — but on success rebases to
+ * `submittedData` (the snapshot actually sent), not the live value, since the
+ * user may have typed further edits that haven't been submitted yet.
+ */
+declare function computeDataApplication<A>(params: {
+  readonly isSuccess: boolean;
+  readonly appliedData: A;
+  readonly initial: A;
+  readonly submittedData: A;
+  readonly resetForm: boolean;
+  readonly autoSubmit: boolean;
+}): DataApplication<A>;
+//#endregion
+export { DataApplication, FormUpdate, computeDataApplication, objectToEntries, objectToFormData, parseActionResult, resultToUpdate };
+//# sourceMappingURL=EnhanceCore.d.ts.map

package/dist/EnhanceCore.js

@@ -0,0 +1,123 @@
+import { Result } from "@thomasfosterau/effect-forms";
+//#region src/EnhanceCore.ts
+/**
+* @copyright Thomas Foster
+*
+* Pure plumbing for the `enhance` action: serialise the store's data back into
+* a form body, interpret a server response into a {@link FormActionResult}, and
+* compute the store update a result implies. Kept framework-free and side-
+* effect-free so it is unit-testable in isolation; the rune store
+* (`superForm.svelte.ts`) wires these to the DOM.
+*
+* @module effect-forms-svelte/EnhanceCore
+*/
+const { failure, success } = Result;
+/** Flatten a nested data object into `[name, value]` entries using path notation. */
+function objectToEntries(data, prefix = "") {
+	const out = [];
+	const push = (key, value) => {
+		if (value === void 0) return;
+		if (value === null) out.push([key, ""]);
+		else if (Array.isArray(value)) value.forEach((item, i) => out.push(...objectToEntries(item, `${key}[${i}]`)));
+		else if (typeof value === "object") out.push(...objectToEntries(value, key));
+		else out.push([key, String(value)]);
+	};
+	if (data !== null && typeof data === "object" && !Array.isArray(data)) for (const [key, value] of Object.entries(data)) push(prefix ? `${prefix}.${key}` : key, value);
+	else if (prefix) push(prefix, data);
+	return out;
+}
+/** Serialise the store's data into a {@link FormData} body for submission. */
+function objectToFormData(data) {
+	const formData = new FormData();
+	for (const [key, value] of objectToEntries(data)) formData.append(key, value);
+	return formData;
+}
+/** Whether a value looks like a {@link FormActionResult} (carries a known `_tag`). */
+function isActionResult(value) {
+	return typeof value === "object" && value !== null && typeof value._tag === "string" && [
+		"Success",
+		"Failure",
+		"Redirect",
+		"Error"
+	].includes(value._tag);
+}
+/** Whether a value looks like a bare {@link FormState}. */
+function isFormState(value) {
+	return typeof value === "object" && value !== null && "valid" in value && "data" in value && "errors" in value;
+}
+/**
+* Normalise a parsed JSON response body into a {@link FormActionResult}. The
+* server may return a full action result (`{ _tag, … }`) or a bare
+* {@link FormState} — a bare state maps to `Success` / `Failure` by its `valid`
+* flag, using `status` for the failure code.
+*/
+function parseActionResult(body, status = 200) {
+	if (isActionResult(body)) return body;
+	if (isFormState(body)) {
+		const state = body;
+		return state.valid ? success(state, status) : failure(state, status);
+	}
+	return {
+		_tag: "Error",
+		status,
+		message: "Unrecognised form response"
+	};
+}
+/**
+* Compute the store update implied by a {@link FormActionResult}. Pure: the
+* caller applies the returned fields to its reactive state and acts on
+* `redirect` / `error`.
+*/
+function resultToUpdate(result) {
+	switch (result._tag) {
+		case "Success": return {
+			data: result.state.data,
+			errors: result.state.errors,
+			message: result.state.message,
+			valid: true
+		};
+		case "Failure": return {
+			data: result.state.data,
+			errors: result.state.errors,
+			message: result.state.message,
+			valid: false
+		};
+		case "Redirect": return { redirect: result.location };
+		case "Error": return {
+			error: result.message,
+			valid: false
+		};
+	}
+}
+/**
+* Decide how a submit result's data applies to the store, given a defined
+* `update.data` (redirects/errors never reach this — see {@link resultToUpdate}).
+* Pure so the save-then-navigate baseline rebase is unit-testable without
+* compiling the rune store: on a successful submit the tainted baseline
+* rebases to whatever was actually persisted, so `isTainted` goes back to
+* `false` for values that were just saved, not just the original seed. An
+* auto-submitting (live-save) form keeps its local `data` as the source of
+* truth while a request is in flight — adopting the server's echo would
+* discard keystrokes made during the round-trip — but on success rebases to
+* `submittedData` (the snapshot actually sent), not the live value, since the
+* user may have typed further edits that haven't been submitted yet.
+*/
+function computeDataApplication(params) {
+	const { isSuccess, appliedData, initial, submittedData, resetForm, autoSubmit } = params;
+	if (resetForm && isSuccess) return {
+		data: initial,
+		rebaseTo: initial
+	};
+	if (autoSubmit) return {
+		data: void 0,
+		rebaseTo: isSuccess ? submittedData : void 0
+	};
+	return {
+		data: appliedData,
+		rebaseTo: isSuccess ? appliedData : void 0
+	};
+}
+//#endregion
+export { computeDataApplication, objectToEntries, objectToFormData, parseActionResult, resultToUpdate };
+
+//# sourceMappingURL=EnhanceCore.js.map

package/dist/EnhanceCore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnhanceCore.js","names":[],"sources":["../src/EnhanceCore.ts"],"sourcesContent":["/**\n * @copyright Thomas Foster\n *\n * Pure plumbing for the `enhance` action: serialise the store's data back into\n * a form body, interpret a server response into a {@link FormActionResult}, and\n * compute the store update a result implies. Kept framework-free and side-\n * effect-free so it is unit-testable in isolation; the rune store\n * (`superForm.svelte.ts`) wires these to the DOM.\n *\n * @module effect-forms-svelte/EnhanceCore\n */\n\nimport { Errors, Result, State } from \"@thomasfosterau/effect-forms\";\n\n// Terse local aliases onto the namespaced core exports.\ntype FormActionResult<A, Message = unknown> = Result.FormActionResult<A, Message>;\ntype FormErrors = Errors.FormErrors;\ntype FormState<A, Message = unknown> = State.FormState<A, Message>;\nconst { failure, success } = Result;\n\n/** Flatten a nested data object into `[name, value]` entries using path notation. */\nexport function objectToEntries(data: unknown, prefix = \"\"): Array<[string, string]> {\n  const out: Array<[string, string]> = [];\n  const push = (key: string, value: unknown): void => {\n    if (value === undefined) return;\n    if (value === null) {\n      out.push([key, \"\"]);\n    } else if (Array.isArray(value)) {\n      value.forEach((item, i) => out.push(...objectToEntries(item, `${key}[${i}]`)));\n    } else if (typeof value === \"object\") {\n      out.push(...objectToEntries(value, key));\n    } else {\n      out.push([key, String(value)]);\n    }\n  };\n\n  if (data !== null && typeof data === \"object\" && !Array.isArray(data)) {\n    for (const [key, value] of Object.entries(data as Record<string, unknown>)) {\n      push(prefix ? `${prefix}.${key}` : key, value);\n    }\n  } else if (prefix) {\n    push(prefix, data);\n  }\n  return out;\n}\n\n/** Serialise the store's data into a {@link FormData} body for submission. */\nexport function objectToFormData(data: unknown): FormData {\n  const formData = new FormData();\n  for (const [key, value] of objectToEntries(data)) formData.append(key, value);\n  return formData;\n}\n\n/** Whether a value looks like a {@link FormActionResult} (carries a known `_tag`). */\nfunction isActionResult(value: unknown): value is FormActionResult<unknown, unknown> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as { _tag?: unknown })._tag === \"string\" &&\n    [\"Success\", \"Failure\", \"Redirect\", \"Error\"].includes((value as { _tag: string })._tag)\n  );\n}\n\n/** Whether a value looks like a bare {@link FormState}. */\nfunction isFormState(value: unknown): value is FormState<unknown, unknown> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"valid\" in value &&\n    \"data\" in value &&\n    \"errors\" in value\n  );\n}\n\n/**\n * Normalise a parsed JSON response body into a {@link FormActionResult}. The\n * server may return a full action result (`{ _tag, … }`) or a bare\n * {@link FormState} — a bare state maps to `Success` / `Failure` by its `valid`\n * flag, using `status` for the failure code.\n */\nexport function parseActionResult<A, Message>(\n  body: unknown,\n  status = 200,\n): FormActionResult<A, Message> {\n  if (isActionResult(body)) return body as FormActionResult<A, Message>;\n  if (isFormState(body)) {\n    const state = body as FormState<A, Message>;\n    return state.valid ? success(state, status) : failure(state, status);\n  }\n  return { _tag: \"Error\", status, message: \"Unrecognised form response\" };\n}\n\n/** The mutation a {@link FormActionResult} implies for the store. */\nexport interface FormUpdate<A, Message> {\n  readonly data?: A | undefined;\n  readonly errors?: FormErrors | undefined;\n  readonly message?: Message | undefined;\n  readonly redirect?: string | undefined;\n  readonly error?: string | undefined;\n  readonly valid?: boolean | undefined;\n}\n\n/**\n * Compute the store update implied by a {@link FormActionResult}. Pure: the\n * caller applies the returned fields to its reactive state and acts on\n * `redirect` / `error`.\n */\nexport function resultToUpdate<A, Message>(\n  result: FormActionResult<A, Message>,\n): FormUpdate<A, Message> {\n  switch (result._tag) {\n    case \"Success\":\n      return {\n        data: result.state.data,\n        errors: result.state.errors,\n        message: result.state.message,\n        valid: true,\n      };\n    case \"Failure\":\n      return {\n        data: result.state.data,\n        errors: result.state.errors,\n        message: result.state.message,\n        valid: false,\n      };\n    case \"Redirect\":\n      return { redirect: result.location };\n    case \"Error\":\n      return { error: result.message, valid: false };\n  }\n}\n\n/** How a successful/failed submit's data should land on `data` and the tainted baseline. */\nexport interface DataApplication<A> {\n  /** The next value for `data`, or `undefined` to leave it untouched (an auto-submit keeps local edits). */\n  readonly data: A | undefined;\n  /** The next tainted baseline (`#initial`), or `undefined` when this isn't a successful submit. */\n  readonly rebaseTo: A | undefined;\n}\n\n/**\n * Decide how a submit result's data applies to the store, given a defined\n * `update.data` (redirects/errors never reach this — see {@link resultToUpdate}).\n * Pure so the save-then-navigate baseline rebase is unit-testable without\n * compiling the rune store: on a successful submit the tainted baseline\n * rebases to whatever was actually persisted, so `isTainted` goes back to\n * `false` for values that were just saved, not just the original seed. An\n * auto-submitting (live-save) form keeps its local `data` as the source of\n * truth while a request is in flight — adopting the server's echo would\n * discard keystrokes made during the round-trip — but on success rebases to\n * `submittedData` (the snapshot actually sent), not the live value, since the\n * user may have typed further edits that haven't been submitted yet.\n */\nexport function computeDataApplication<A>(params: {\n  readonly isSuccess: boolean;\n  readonly appliedData: A;\n  readonly initial: A;\n  readonly submittedData: A;\n  readonly resetForm: boolean;\n  readonly autoSubmit: boolean;\n}): DataApplication<A> {\n  const { isSuccess, appliedData, initial, submittedData, resetForm, autoSubmit } = params;\n  if (resetForm && isSuccess) return { data: initial, rebaseTo: initial };\n  if (autoSubmit) return { data: undefined, rebaseTo: isSuccess ? submittedData : undefined };\n  return { data: appliedData, rebaseTo: isSuccess ? appliedData : undefined };\n}\n"],"mappings":";;;;;;;;;;;;;AAkBA,MAAM,EAAE,SAAS,YAAY;;AAG7B,SAAgB,gBAAgB,MAAe,SAAS,IAA6B;CACnF,MAAM,MAA+B,CAAC;CACtC,MAAM,QAAQ,KAAa,UAAyB;EAClD,IAAI,UAAU,KAAA,GAAW;EACzB,IAAI,UAAU,MACZ,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;OACb,IAAI,MAAM,QAAQ,KAAK,GAC5B,MAAM,SAAS,MAAM,MAAM,IAAI,KAAK,GAAG,gBAAgB,MAAM,GAAG,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;OACxE,IAAI,OAAO,UAAU,UAC1B,IAAI,KAAK,GAAG,gBAAgB,OAAO,GAAG,CAAC;OAEvC,IAAI,KAAK,CAAC,KAAK,OAAO,KAAK,CAAC,CAAC;CAEjC;CAEA,IAAI,SAAS,QAAQ,OAAO,SAAS,YAAY,CAAC,MAAM,QAAQ,IAAI,GAClE,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAA+B,GACvE,KAAK,SAAS,GAAG,OAAO,GAAG,QAAQ,KAAK,KAAK;MAE1C,IAAI,QACT,KAAK,QAAQ,IAAI;CAEnB,OAAO;AACT;;AAGA,SAAgB,iBAAiB,MAAyB;CACxD,MAAM,WAAW,IAAI,SAAS;CAC9B,KAAK,MAAM,CAAC,KAAK,UAAU,gBAAgB,IAAI,GAAG,SAAS,OAAO,KAAK,KAAK;CAC5E,OAAO;AACT;;AAGA,SAAS,eAAe,OAA6D;CACnF,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAA6B,SAAS,YAC9C;EAAC;EAAW;EAAW;EAAY;CAAO,CAAC,CAAC,SAAU,MAA2B,IAAI;AAEzF;;AAGA,SAAS,YAAY,OAAsD;CACzE,OACE,OAAO,UAAU,YACjB,UAAU,QACV,WAAW,SACX,UAAU,SACV,YAAY;AAEhB;;;;;;;AAQA,SAAgB,kBACd,MACA,SAAS,KACqB;CAC9B,IAAI,eAAe,IAAI,GAAG,OAAO;CACjC,IAAI,YAAY,IAAI,GAAG;EACrB,MAAM,QAAQ;EACd,OAAO,MAAM,QAAQ,QAAQ,OAAO,MAAM,IAAI,QAAQ,OAAO,MAAM;CACrE;CACA,OAAO;EAAE,MAAM;EAAS;EAAQ,SAAS;CAA6B;AACxE;;;;;;AAiBA,SAAgB,eACd,QACwB;CACxB,QAAQ,OAAO,MAAf;EACE,KAAK,WACH,OAAO;GACL,MAAM,OAAO,MAAM;GACnB,QAAQ,OAAO,MAAM;GACrB,SAAS,OAAO,MAAM;GACtB,OAAO;EACT;EACF,KAAK,WACH,OAAO;GACL,MAAM,OAAO,MAAM;GACnB,QAAQ,OAAO,MAAM;GACrB,SAAS,OAAO,MAAM;GACtB,OAAO;EACT;EACF,KAAK,YACH,OAAO,EAAE,UAAU,OAAO,SAAS;EACrC,KAAK,SACH,OAAO;GAAE,OAAO,OAAO;GAAS,OAAO;EAAM;CACjD;AACF;;;;;;;;;;;;;;AAuBA,SAAgB,uBAA0B,QAOnB;CACrB,MAAM,EAAE,WAAW,aAAa,SAAS,eAAe,WAAW,eAAe;CAClF,IAAI,aAAa,WAAW,OAAO;EAAE,MAAM;EAAS,UAAU;CAAQ;CACtE,IAAI,YAAY,OAAO;EAAE,MAAM,KAAA;EAAW,UAAU,YAAY,gBAAgB,KAAA;CAAU;CAC1F,OAAO;EAAE,MAAM;EAAa,UAAU,YAAY,cAAc,KAAA;CAAU;AAC5E"}

package/dist/EntityForm.d.ts

@@ -0,0 +1,158 @@
+import { Command } from "@thomasfosterau/effect-forms";
+import * as Schema from "effect/Schema";
+import { Component } from "svelte";
+//#region src/EntityForm.d.ts
+/** A render-time message thunk — pass the Paraglide function itself, uncalled. */
+type MessageThunk = () => string;
+/** Presentation options for a scalar text entry. */
+interface TextEntryOptions {
+  readonly label: MessageThunk;
+  /** Presentation `type` attribute (`url`, `date`). Omitted → text input. */
+  readonly type?: "text" | "url" | "date";
+  /** Keyboard hint for numeric text fields; defaults from the field's derived kind. */
+  readonly inputmode?: "numeric";
+  /** Force required-ness (defaults to the schema-derived constraint). */
+  readonly required?: boolean;
+  readonly placeholder?: MessageThunk;
+}
+/** A scalar field rendered by the shared text/textarea primitives. */
+interface ScalarEntry {
+  readonly _tag: "scalar";
+  readonly key: string;
+  readonly multiline: boolean;
+  readonly options: TextEntryOptions;
+}
+/** Presentation options for a `<select>` entry over a literal-union (`enum` kind) field. */
+interface SelectEntryOptions {
+  readonly label: MessageThunk;
+  readonly required?: boolean;
+  /**
+   * Per-option render-time label thunks, keyed by the field's derived option
+   * *value* (`Command.FieldPlan.options`, read via `fieldFor` — not declared
+   * here). `defineEntityForm` throws at definition time if a derived value has
+   * no matching thunk.
+   */
+  readonly optionLabels: Readonly<Record<string, MessageThunk>>;
+}
+/**
+ * A `<select>` field over a literal-union (`enum` kind) command field. Option
+ * *values* derive from the field's plan; this entry supplies only the
+ * per-option labels — `defineEntityForm` validates the field is `enum`-kind
+ * and that every derived value has a label.
+ */
+interface SelectEntry {
+  readonly _tag: "select";
+  readonly key: string;
+  readonly options: SelectEntryOptions;
+}
+/** Options for a widget entry (picker / rows list). */
+interface WidgetEntryOptions {
+  /** Gate the submit button while this field's value is empty (required pickers). */
+  readonly gate?: boolean;
+}
+/**
+ * A bespoke widget field. The renderer bridges the store to the widget through
+ * the stage-1 wrapper contract — `name`, `value`, `onChange`, `errors` — which
+ * are **reserved keys**: the bridge is spread last, so a `props()` thunk or a
+ * load-supplied field prop can never silently sever the store binding.
+ */
+interface WidgetEntry {
+  readonly _tag: "widget";
+  readonly key: string;
+  /** `"value"` bridges a string FK; `"rows"` bridges a controlled row list. */
+  readonly bridge: "value" | "rows";
+  readonly component: Component<any>;
+  readonly props: () => Record<string, unknown>;
+  readonly options: WidgetEntryOptions;
+}
+/** One ordered entry in an entity form definition. */
+type EntityFormEntry = ScalarEntry | WidgetEntry | SelectEntry;
+/** The per-mode submit labels. */
+interface SubmitMessages {
+  readonly create: MessageThunk;
+  readonly update: MessageThunk;
+}
+/** The runtime shape `defineEntityForm` accepts for a command struct. */
+interface CommandStructLike {
+  readonly fields: Record<string, Schema.Top>;
+}
+/** The value `defineEntityForm` returns — everything one renderer needs. */
+interface EntityFormDefinition {
+  readonly plan: Command.CommandPlan;
+  readonly entries: readonly EntityFormEntry[];
+  readonly createInput: Schema.Top;
+  readonly updateInput: Schema.Top;
+  readonly createDefaults: Readonly<Record<string, string>>;
+  readonly updateDefaults: Readonly<Record<string, string>>;
+  readonly adaptCreate: (input: Command.FormInputRecord) => Record<string, unknown>;
+  readonly adaptUpdate: (input: Command.FormInputRecord) => Record<string, unknown>;
+  readonly submit: SubmitMessages;
+  /** The create struct carries a client-generated id (idempotent retries). */
+  readonly clientId: boolean;
+  /** Entries visible in one mode, in declaration order. */
+  readonly entriesFor: (mode: "create" | "update") => readonly EntityFormEntry[];
+  /** The plan field behind an entry key. */
+  readonly fieldFor: (key: string) => Command.FieldPlan;
+}
+/** The writable command keys a definition may declare (the `id` key is renderer-owned). */
+type CommandKeys<C extends CommandStructLike, U extends CommandStructLike> = Exclude<Extract<keyof C["fields"] | keyof U["fields"], string>, "id">;
+/** The entry builders handed to the definition callback, key-typed to the command pair. */
+interface EntryBuilders<K extends string> {
+  /** A scalar field rendered by the shared `TextInputField`. */
+  text(key: K, options: TextEntryOptions): EntityFormEntry;
+  /** A scalar field rendered by the shared `TextAreaInputField`. */
+  textarea(key: K, options: TextEntryOptions): EntityFormEntry;
+  /**
+   * A `<select>` field over a literal-union (`enum` kind) command field.
+   * Option values are derived from the field's plan; `options.optionLabels`
+   * supplies each derived value's render-time label thunk.
+   */
+  select(key: K, options: SelectEntryOptions): EntityFormEntry;
+  /**
+   * A bespoke string-valued widget (an FK picker). The renderer supplies
+   * `name` / `value` / `onChange` / `errors`; `props()` supplies the rest at
+   * render time (labels stay thunk-resolved).
+   */
+  custom<P extends Record<string, unknown>>(key: K, component: Component<never>, props: () => P, options?: WidgetEntryOptions): EntityFormEntry;
+  /**
+   * A bespoke row-list widget (a contributor list). The renderer owns the row
+   * state and supplies `name` / `value` / `onChange` / `errors`; the widget
+   * owns the wire serialisation (its hidden input).
+   */
+  rows<P extends Record<string, unknown>>(key: K, component: Component<never>, props: () => P, options?: WidgetEntryOptions): EntityFormEntry;
+}
+/** Everything `defineEntityForm` needs beyond the entries. */
+interface DefineEntityFormOptions<C extends CommandStructLike, U extends CommandStructLike> {
+  readonly create: C;
+  readonly update: U;
+  readonly submit: SubmitMessages;
+  /** Per-field adapter overrides, per mode — the irregular-coercion escape hatch. */
+  readonly adaptOverrides?: {
+    readonly create?: Command.AdaptOverrides;
+    readonly update?: Command.AdaptOverrides;
+  };
+  /** Per-field Form-Input schema overrides, per mode (e.g. an optional create title with a server default). */
+  readonly inputOverrides?: {
+    readonly create?: Readonly<Record<string, Schema.Top>>;
+    readonly update?: Readonly<Record<string, Schema.Top>>;
+  };
+  /**
+   * Command fields deliberately absent from the standalone form (a carve-out,
+   * e.g. BookSeries' `editors` — managed through the Book form's inline-create
+   * path instead). Omitted fields are stripped from the create/update field
+   * records before `Command.plan` runs, so they need no entry, are never
+   * classified (a kind-less omitted field can't throw at definition time),
+   * and never appear in the derived input schema, defaults, or adapters.
+   */
+  readonly omit?: readonly CommandKeys<C, U>[];
+}
+/**
+ * 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.
+ */
+declare const defineEntityForm: <C extends CommandStructLike, U extends CommandStructLike>(options: DefineEntityFormOptions<C, U>, build: (f: EntryBuilders<CommandKeys<C, U>>) => readonly EntityFormEntry[]) => EntityFormDefinition;
+//#endregion
+export { CommandKeys, CommandStructLike, DefineEntityFormOptions, EntityFormDefinition, EntityFormEntry, EntryBuilders, MessageThunk, ScalarEntry, SelectEntry, SelectEntryOptions, SubmitMessages, TextEntryOptions, WidgetEntry, WidgetEntryOptions, defineEntityForm };
+//# sourceMappingURL=EntityForm.d.ts.map