@thomasfosterau/effect-forms-svelte 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,27 @@
 # @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**.
+Svelte 5 (runes) bindings for [`@thomasfosterau/effect-forms`](../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.
+The root entry depends only on `svelte` and the framework-neutral core, not SvelteKit, so it works in any Svelte 5 app. The [`/kit` entry](#kit) (`@thomasfosterau/effect-forms-svelte/kit`) is the SvelteKit-only half: derived form actions, JSON:API error routing and `$app/forms` glue.
+
+## Install
+
+```sh
+pnpm add @thomasfosterau/effect-forms-svelte @thomasfosterau/effect-forms effect svelte
+# for the /kit entry
+pnpm add @sveltejs/kit
+```
+
+`effect` and `svelte` are required peers. `@sveltejs/kit` is an optional peer, required by `/kit`; `@thomasfosterau/effect-jsonapi` is an optional, type-only peer of `/kit`.
 
 ## 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:
+Server (`+page.server.ts` or any action) produces a `FormState` with the core's `Form.make(schema, …).validate(request)`, 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";
+  import { Signup } from "#lib/schemas";
 
   let { data } = $props(); // data.form is the server FormState
 
@@ -35,11 +45,11 @@ Server (`+page.server.ts` or any action) produces a `FormState` with the core's
 
 ## 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:
+`createForm(source, options)` returns a [`FormStore`](src/FormStore.svelte.ts). `source` is a server-produced `FormState`, a `{ schema, defaults }` seed, or a [`FormBuilder`](../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
+import { signup } from "#lib/forms"; // a FormBuilder
 
 const form = createForm(signup, { mode: { validation: "onChange", debounce: 300 } });
 ```
@@ -68,11 +78,11 @@ const form = createForm(signup, { mode: { validation: "onChange", debounce: 300
 {#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.
+`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`.
 
 `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).
+**Validation modes** — the `mode` option (see [`Mode`](../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:
 
@@ -93,23 +103,127 @@ const form = createForm(
 
 **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`).
+**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`](../forms/src/Result.ts) or a bare `FormState`).
 
-## Layout
+## API
 
-The reactive store lives in `FormStore.svelte.ts` (rune-compiled, checked by `svelte-check`). Its logic is delegated to pure, unit-tested modules:
+Everything below is exported flat from the root entry (`@thomasfosterau/effect-forms-svelte`).
 
-| 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. |
+| Module                                    | Exports                                                                                                                                                                                         |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`FormStore`](src/FormStore.svelte.ts)    | `createForm`, `FormStore`, `FieldHandle`, `FieldMeta`, `FormOptions`, `FormSeed` — the reactive store above.                                                                                    |
+| [`EntityForm`](src/EntityForm.ts)         | `defineEntityForm` — an ordered, key-checked field list over a core `Command.plan`, walked by one generic renderer component; its entry types (`ScalarEntry`, `SelectEntry`, `WidgetEntry`, …). |
+| [`SvelteKit`](src/SvelteKit.ts)           | `applyActionResult` — apply a SvelteKit `ActionResult` (`ServerActionResult`) to a store; returns whether it consumed a validation failure.                                                     |
+| [`Listeners`](src/Listeners.ts)           | `changeEvents` / `dispatchChange` and the `FormListeners` / `FieldListener` types — per-field and form-wide change listeners (linked fields).                                                   |
+| [`Tainted`](src/Tainted.ts)               | Deep-diff the data to compute the tainted tree.                                                                                                                                                 |
+| [`ClientValidate`](src/ClientValidate.ts) | `validateData` / `validateField` — validate the form, or 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).
+The reactive store (`FormStore.svelte.ts`, rune-compiled) delegates its logic to the pure, unit-tested modules. The store itself is type-checked as plain TypeScript; its submitter-aware submit path (`enhance` → the posted `FormData`) is unit-tested in [`FormStore.svelte.test.ts`](tests/FormStore.svelte.test.ts).
 
-## Development
+## /kit
 
-```sh
-vp exec svelte-check --tsconfig ./tsconfig.json   # typecheck (incl. runes)
-vp test run tests                                 # unit tests (pure modules + the submit path)
+`@thomasfosterau/effect-forms-svelte/kit` holds the SvelteKit form-action glue: the derived page action, the JSON:API error routing, the idempotent create retry, the `$app/forms` enhance, the `PageProps["form"]` readers, and failure routing for action-only routes. The root entry (`@thomasfosterau/effect-forms-svelte`) stays framework-neutral Svelte; only `/kit` imports `@sveltejs/kit` and `$app/forms`.
+
+| Export                                                     | What it does                                                                                                         |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `formAction(form, run, locationFor, options?)`             | A page action: validate, run the command, then `redirect(303)`, `fail(status, { form })` or `fail(500, { message })` |
+| `runFormAction(form, request, run, locationFor, options?)` | The same, as a framework-neutral `Result.FormActionResult`                                                           |
+| `fieldFromPointer(pointer)`                                | `/data/attributes/<field>…` → `Option<field>`                                                                        |
+| `idempotentCreate(create, fetchExisting)`                  | A 409 on the caller's own client id resolves as success                                                              |
+| `CommandFailure.*`, `jsonapiFailure`                       | Classify a command failure into routed JSON:API errors or a root message                                             |
+| `enhanceForm(store)`                                       | Spreadable `<form>` props on `$app/forms` `enhance`                                                                  |
+| `formStateOf` / `issuesFor` / `rootIssuesOf` / `valueOf`   | Total readers over `PageProps["form"]`                                                                               |
+| `userFixableMessage` / `withFailureParams`                 | Redirect-with-query failure routing for routes that have no page                                                     |
+
+### Peers
+
+- `@sveltejs/kit` (`^3.0.0`) is an **optional** peer of the package and **required** by `/kit`. SvelteKit 2 is not supported. The repository's tests run against SvelteKit 3.0.0, pinned in its `pnpm-workspace.yaml`.
+- `$app/forms` is a SvelteKit virtual module, not a dependency. It resolves because SvelteKit compiles this package (its `exports` carry the `svelte` condition), so `/kit` only works inside a SvelteKit build.
+- `@thomasfosterau/effect-jsonapi` (`>=0.16.0`) is an **optional** peer used **for its types only**. `CommandFailure.ErrorObject` is `Document.ErrorObject.Type`. At runtime a failure is recognised by its `_tag`, so an application's own `JsonapiError` with the same shape is recognised too.
+
+### Commands and failures
+
+A command is `(input, event) => Promise<O> | Effect<O, E>`. An Effect command must have no requirements left. Provide them first, e.g. with the application's `ManagedRuntime`. `locationFor(output, input)` builds the redirect, and must return a same-origin path such as `/organisations/${id}`. SvelteKit 3's `redirect` rejects an external location unless it is given `{ external }`, which `formAction` never passes, so an absolute URL on another origin (or a protocol-relative `//host/...`) makes the action throw an `Error` after the command has run. To send the user off-site, redirect to a same-origin route that performs the external redirect itself. `runFormAction` returns the location unchecked.
+
+`jsonapiFailure`, the default classifier, recognises:
+
+- `{ _tag: "JsonapiError", status, errors }`: effect-jsonapi's `ServerErrors.JsonapiError`, or any error of the same shape. Each error object goes to the field its `source.pointer` names, or to the root (`form.errors._errors`), at the cause's own status.
+- `{ _tag: "ErrorResponse", status, message, document }`: effect-jsonapi's client-side decoded error. The document's error objects are routed as above. With no document, the message goes to the root.
+- An `Error` with a numeric `status`, such as a transport's 413: its message goes to the root.
+
+Anything else is unexpected. By default it becomes `fail(500, { message })`. Pass `unrecognised: "throw"` to hand it to `handleError` instead. `classify` replaces the classifier; compose with `CommandFailure.jsonapiFailure` to extend it. `redact` runs on every state echoed back to the browser. `idempotent: { clientId, fetchExisting }` turns on the client-id retry.
+
+### Worked example: a login action
+
+A hand-written sign-in action typically hand-rolls validation, password blanking, 401 → generic message, a rethrow for anything else, and a same-origin redirect. With `/kit` it becomes:
+
+```ts
+// src/routes/login/+page.server.ts
+import { Form, State } from "@thomasfosterau/effect-forms";
+import { CommandFailure, formAction } from "@thomasfosterau/effect-forms-svelte/kit";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { SessionCallError } from "#lib/server/api/binding";
+import { safeRedirect } from "#lib/redirects";
+
+const SignInFields = Schema.Struct({
+  email: Schema.String,
+  _password: Schema.String,
+  redirectTo: Schema.optional(Schema.String),
+});
+
+const signInForm = Form.make(SignInFields, {
+  defaults: { email: "", _password: "", redirectTo: undefined },
+  id: "sign-in",
+});
+
+type SignIn = typeof SignInFields.Type;
+
+/** Blank the password before a state is echoed back to the browser. */
+const blankPassword = (state: State.FormState<SignIn>): State.FormState<SignIn> => ({
+  ...state,
+  data: { ...state.data, _password: "" },
+});
+
+/** A 401 → one generic whole-form message (never reveal whether the email exists). */
+const classify: CommandFailure.Classify = (cause) =>
+  cause instanceof SessionCallError && cause.status === 401
+    ? Option.some(CommandFailure.message(401, "Invalid email or password"))
+    : Option.none();
+
+export const actions = {
+  default: formAction(
+    signInForm,
+    (input, { locals }) =>
+      locals.session.signIn({ email: input.email, password: input._password, rememberMe: true }),
+    (_, input) => safeRedirect(input.redirectTo, "/"),
+    { classify, redact: blankPassword, unrecognised: "throw" },
+  ),
+};
 ```
+
+The runnable copy is [`packages/svelte/tests/kit/examples/login.page.server.ts`](tests/kit/examples/login.page.server.ts). [`login.example.test.ts`](tests/kit/login.example.test.ts) runs it against the real `@sveltejs/kit`, covering the success redirect, the off-site `redirectTo` guard, the 401 with a blanked password, and the rethrow.
+
+The page renders server state without a client store:
+
+```svelte
+<script lang="ts">
+  import { formStateOf, issuesFor, rootIssuesOf, valueOf } from "@thomasfosterau/effect-forms-svelte/kit";
+  let { form } = $props();
+  const state = $derived(formStateOf(form));
+</script>
+
+<form method="post">
+  {#each rootIssuesOf(state) as message}<p role="alert">{message}</p>{/each}
+  <input name="email" value={valueOf(state, "email")} />
+  {#each issuesFor(state, "email") as message}<small>{message}</small>{/each}
+  <input name="_password" type="password" />
+</form>
+```
+
+With a client store, spread `enhanceForm(form)` onto the `<form>` instead.
+
+## License
+
+[MIT](LICENSE)

package/dist/ClientValidate.d.ts

@@ -5,14 +5,13 @@ 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;
+export 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[];
+export 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

@@ -1,8 +1,6 @@
 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).
@@ -12,6 +10,7 @@ import { Errors, Validate } from "@thomasfosterau/effect-forms";
 * have no decoding-service requirements (the common case for form schemas) so
 * validation can run synchronously in an event handler.
 *
+* @copyright Thomas Foster
 * @module effect-forms-svelte/ClientValidate
 */
 const { getError, noErrors } = Errors;

package/dist/ClientValidate.js.map

@@ -1 +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"}
+{"version":3,"file":"ClientValidate.js","names":[],"sources":["../src/ClientValidate.ts"],"sourcesContent":["/**\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 * @copyright Thomas Foster\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":";;;;;;;;;;;;;;;AAoBA,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

@@ -3,18 +3,18 @@ import { Errors, Result } from "@thomasfosterau/effect-forms";
 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]>;
+export 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;
+export 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>;
+export 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> {
+export interface FormUpdate<A, Message> {
   readonly data?: A | undefined;
   readonly errors?: FormErrors | undefined;
   readonly message?: Message | undefined;
@@ -27,9 +27,9 @@ interface FormUpdate<A, Message> {
  * 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>;
+export 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> {
+export 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. */
@@ -48,7 +48,7 @@ interface DataApplication<A> {
  * `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: {
+export declare function computeDataApplication<A>(params: {
   readonly isSuccess: boolean;
   readonly appliedData: A;
   readonly initial: A;
@@ -57,5 +57,4 @@ declare function computeDataApplication<A>(params: {
   readonly autoSubmit: boolean;
 }): DataApplication<A>;
 //#endregion
-export { DataApplication, FormUpdate, computeDataApplication, objectToEntries, objectToFormData, parseActionResult, resultToUpdate };
 //# sourceMappingURL=EnhanceCore.d.ts.map

package/dist/EnhanceCore.js

@@ -1,14 +1,13 @@
 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.
+* (`FormStore.svelte.ts`) wires these to the DOM.
 *
+* @copyright Thomas Foster
 * @module effect-forms-svelte/EnhanceCore
 */
 const { failure, success } = Result;

package/dist/EnhanceCore.js.map

@@ -1 +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"}
+{"version":3,"file":"EnhanceCore.js","names":[],"sources":["../src/EnhanceCore.ts"],"sourcesContent":["/**\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 * (`FormStore.svelte.ts`) wires these to the DOM.\n *\n * @copyright Thomas Foster\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":";;;;;;;;;;;;AAiBA,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

@@ -2,10 +2,10 @@ 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;
+/** A render-time message thunk — pass the message function itself, uncalled. */
+export type MessageThunk = () => string;
 /** Presentation options for a scalar text entry. */
-interface TextEntryOptions {
+export interface TextEntryOptions {
   readonly label: MessageThunk;
   /** Presentation `type` attribute (`url`, `date`). Omitted → text input. */
   readonly type?: "text" | "url" | "date";
@@ -16,14 +16,14 @@ interface TextEntryOptions {
   readonly placeholder?: MessageThunk;
 }
 /** A scalar field rendered by the shared text/textarea primitives. */
-interface ScalarEntry {
+export 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 {
+export interface SelectEntryOptions {
   readonly label: MessageThunk;
   readonly required?: boolean;
   /**
@@ -40,23 +40,23 @@ interface SelectEntryOptions {
  * per-option labels — `defineEntityForm` validates the field is `enum`-kind
  * and that every derived value has a label.
  */
-interface SelectEntry {
+export interface SelectEntry {
   readonly _tag: "select";
   readonly key: string;
   readonly options: SelectEntryOptions;
 }
 /** Options for a widget entry (picker / rows list). */
-interface WidgetEntryOptions {
+export 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
+ * the widget 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 {
+export interface WidgetEntry {
   readonly _tag: "widget";
   readonly key: string;
   /** `"value"` bridges a string FK; `"rows"` bridges a controlled row list. */
@@ -66,18 +66,18 @@ interface WidgetEntry {
   readonly options: WidgetEntryOptions;
 }
 /** One ordered entry in an entity form definition. */
-type EntityFormEntry = ScalarEntry | WidgetEntry | SelectEntry;
+export type EntityFormEntry = ScalarEntry | WidgetEntry | SelectEntry;
 /** The per-mode submit labels. */
-interface SubmitMessages {
+export interface SubmitMessages {
   readonly create: MessageThunk;
   readonly update: MessageThunk;
 }
 /** The runtime shape `defineEntityForm` accepts for a command struct. */
-interface CommandStructLike {
+export interface CommandStructLike {
   readonly fields: Record<string, Schema.Top>;
 }
 /** The value `defineEntityForm` returns — everything one renderer needs. */
-interface EntityFormDefinition {
+export interface EntityFormDefinition {
   readonly plan: Command.CommandPlan;
   readonly entries: readonly EntityFormEntry[];
   readonly createInput: Schema.Top;
@@ -95,9 +95,9 @@ interface EntityFormDefinition {
   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">;
+export 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> {
+export 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`. */
@@ -122,7 +122,7 @@ interface EntryBuilders<K extends string> {
   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> {
+export interface DefineEntityFormOptions<C extends CommandStructLike, U extends CommandStructLike> {
   readonly create: C;
   readonly update: U;
   readonly submit: SubmitMessages;
@@ -152,7 +152,6 @@ interface DefineEntityFormOptions<C extends CommandStructLike, U extends Command
  * 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;
+export 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

package/dist/EntityForm.js.map

@@ -1 +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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"}
+{"version":3,"file":"EntityForm.js","names":[],"sources":["../src/EntityForm.ts"],"sourcesContent":["/**\n * The typed entity-form definition builder.\n * `defineEntityForm(commands, (f) => [...])` pairs a `Command.plan`\n * derivation (form-input schemas, blank defaults, tri-state adapters — see\n * `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 * e.g. an i18n message function) resolved at render time, never at\n * module scope — module-scope resolution would freeze the import-time locale.\n *\n * @copyright Thomas Foster\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 message 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 widget 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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"}