effect-atom-svelte 0.2.0 → 0.4.0

package/dist/ScopedAtom.js

@@ -1,6 +1,4 @@
 import { createContext } from "svelte";
-// A const and a type of the same name, as in Effect's modules.
-/* oxlint-disable eslint/no-redeclare */
 /**
  * Marks a value as a `ScopedAtom`: every scoped atom has this key, set to this same string, as
  * Effect's own types carry a type id.
@@ -13,10 +11,11 @@ export const TypeId = "~effect-atom-svelte/ScopedAtom";
 /**
  * Creates a scoped atom from a factory, which runs once per providing component.
  *
- * Each provider gets its own atom, so a factory that adds `Atom.serializable` with a fixed key
- * gives every copy the same key: once two providers are on a page, reading them with
- * `useAtomResult` or `useAtomSuspense` throws, as two different atoms share the serialization
- * key. Put the input in the key, or leave scoped atoms unserialized.
+ * Each provider gets its own atom, so a factory that makes a serializable atom gives every copy of
+ * one input the same key, and two such providers on a server-rendered page make the render throw:
+ * two different atoms share the serialization key. For a value from the server, return a family's
+ * atom instead, `ScopedAtom.make((id: string) => userAtom(id))`, so every provider of one input
+ * holds the same atom.
  *
  * **Example** (A counter per subtree, started from an input)
  *
@@ -36,17 +35,27 @@ export const TypeId = "~effect-atom-svelte/ScopedAtom";
  */
 export const make = (f, options) => {
     const [get, set, has] = createContext();
-    const provide = (...args) => set(args.length === 0
-        ? f()
-        : f(args[0]));
+    const provide = (...args) => {
+        if (args.length === 1) {
+            return set(f(args[0]));
+        }
+        // SAFETY: `provide`'s type allows no input only when `Input` is never or includes undefined, so
+        // `f` is the factory without input or one whose input is optional.
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the union of factories can't be narrowed by the argument count
+        return set(f());
+    };
     return {
         [TypeId]: TypeId,
+        // SAFETY: `provide` takes no input or one, which every branch of the conditional type accepts;
+        // TypeScript can't pick a branch while `Input` is generic.
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the conditional type can't be narrowed for a generic `Input`
         provide: provide,
         use: () => {
             if (!has()) {
                 const name = options?.name;
-                const which = name ? `ScopedAtom "${name}"` : "ScopedAtom";
-                const call = name ? `${name}.provide()` : "its provide()";
+                const named = name !== undefined && name !== "";
+                const which = named ? `ScopedAtom "${name}"` : "ScopedAtom";
+                const call = named ? `${name}.provide()` : "its provide()";
                 throw new Error(`${which} used outside of the component that provides it. Call ${call} in a parent component's script.`);
             }
             return get();

package/dist/SvelteKit.d.ts

@@ -1,13 +1,3 @@
-/**
- * SvelteKit `handleError` hooks that keep an Effect error's `_tag`, so a `<svelte:boundary>`
- * `failed` snippet can tell typed errors apart. Import them from `effect-atom-svelte/sveltekit`.
- *
- * The module does not import SvelteKit: the hooks take the fields of SvelteKit's input they read
- * and return the fields they set, so they type-check against `HandleClientError` and
- * `HandleServerError` once `App.Error` declares `tag?: string`.
- *
- * @since 0.1.0
- */
 /**
  * The part of SvelteKit's `handleError` input that the hooks read. In SvelteKit 3, `kind` is
  * `"unknown"` for errors thrown by your code, `"app"` for `error(...)`, `"framework"` for
@@ -38,6 +28,27 @@ export interface EffectErrorBody {
     readonly message?: string;
     readonly tag?: string;
 }
+/**
+ * SvelteKit 2's `handleError` input: no `kind`, and always a message, which the hooks fall back on.
+ *
+ * @stability unstable
+ * @since 0.2.1
+ * @category models
+ */
+export interface CaughtErrorWithoutKind extends CaughtError {
+    readonly kind?: undefined;
+    readonly message: string;
+}
+/**
+ * What the hooks return for SvelteKit 2's input: always a message, as its `App.Error` requires one.
+ *
+ * @stability unstable
+ * @since 0.2.1
+ * @category models
+ */
+export interface EffectErrorBodyWithMessage extends EffectErrorBody {
+    readonly message: string;
+}
 /**
  * A client `handleError` hook (`src/hooks.client.ts`) that keeps the message and `_tag` of errors
  * thrown by your code, so a boundary's `failed` snippet shows them instead of
@@ -56,7 +67,8 @@ export interface EffectErrorBody {
  * @since 0.1.0
  * @category hooks
  */
-export declare const handleClientError: (input: CaughtError) => EffectErrorBody | undefined;
+export declare function handleClientError(input: CaughtErrorWithoutKind): EffectErrorBodyWithMessage;
+export declare function handleClientError(input: CaughtError): EffectErrorBody | undefined;
 /**
  * A server `handleError` hook (`src/hooks.server.ts`) that keeps the `_tag` of errors thrown by
  * your code but not their message, which could expose details of the server to users: the
@@ -75,4 +87,51 @@ export declare const handleClientError: (input: CaughtError) => EffectErrorBody
  * @since 0.1.0
  * @category hooks
  */
-export declare const handleServerError: (input: CaughtError) => EffectErrorBody | undefined;
+export declare function handleServerError(input: CaughtErrorWithoutKind): EffectErrorBodyWithMessage;
+export declare function handleServerError(input: CaughtError): EffectErrorBody | undefined;
+/**
+ * Options for `useUnsavedChangesGuard`.
+ *
+ * @stability unstable
+ * @since 0.4.0
+ * @category models
+ */
+export interface UnsavedChangesGuardOptions {
+    /**
+     * Asks whether to leave and lose the changes, resolving `true` to leave. Called for links,
+     * `goto`, form navigations and the back and forward buttons. Closing the tab, reloading and
+     * typing a URL show the browser's own dialog instead, as a page can't show its own then.
+     */
+    readonly confirm: () => boolean | Promise<boolean>;
+}
+/**
+ * Asks before the user navigates away from a page whose form is dirty, using SvelteKit's
+ * `beforeNavigate`. Call it while a component initializes, with any object that has `dirty`, such
+ * as a form instance from `useForm`.
+ *
+ * While the form is dirty, a navigation is cancelled and `confirm` asked; on yes it is retried, and
+ * the retry goes through. Closing the tab, reloading or typing a URL show the browser's own dialog
+ * instead. SvelteKit doesn't call `beforeNavigate` for back and forward over shallow history entries
+ * (from `pushState` or a hash change) or for links to a hash on the same page, so those aren't
+ * guarded.
+ *
+ * **Example** (Asking before leaving an edit page)
+ *
+ * ```ts
+ * import { useForm } from "effect-atom-svelte";
+ * import { useUnsavedChangesGuard } from "effect-atom-svelte/sveltekit";
+ *
+ * const form = useForm(EditProject, { id, initialValues, submit });
+ * useUnsavedChangesGuard(form, {
+ *   confirm: () => window.confirm("Leave without saving your changes?"),
+ * });
+ * ```
+ *
+ * @see {@link https://atom.jarrednorris.dev/forms | Forms}
+ * @stability unstable
+ * @since 0.4.0
+ * @category forms
+ */
+export declare const useUnsavedChangesGuard: (form: {
+    readonly dirty: boolean;
+}, options: UnsavedChangesGuardOptions) => void;

package/dist/SvelteKit.js

@@ -1,19 +1,26 @@
 /**
- * SvelteKit `handleError` hooks that keep an Effect error's `_tag`, so a `<svelte:boundary>`
- * `failed` snippet can tell typed errors apart. Import them from `effect-atom-svelte/sveltekit`.
+ * SvelteKit helpers. Import them from `effect-atom-svelte/sveltekit`.
  *
- * The module does not import SvelteKit: the hooks take the fields of SvelteKit's input they read
- * and return the fields they set, so they type-check against `HandleClientError` and
- * `HandleServerError` once `App.Error` declares `tag?: string`.
+ * `handleClientError` and `handleServerError` are `handleError` hooks that keep an Effect error's
+ * `_tag`, so a `<svelte:boundary>` `failed` snippet can tell typed errors apart. They take the
+ * fields of SvelteKit's input they read and return the fields they set, so they type-check against
+ * `HandleClientError` and `HandleServerError` once `App.Error` declares `tag?: string`. In
+ * SvelteKit 2, whose `App.Error` requires a message, they are typed to return one when there is no
+ * `kind`, as they then always set one.
+ *
+ * `useUnsavedChangesGuard` asks before leaving a page with a dirty form.
  *
  * @since 0.1.0
  */
-const tagOf = (error) => typeof error === "object" &&
-    error !== null &&
-    "_tag" in error &&
-    typeof error._tag === "string"
-    ? error._tag
-    : undefined;
+/// <reference types="@sveltejs/kit" />
+import { beforeNavigate, goto } from "$app/navigation";
+import { Effect } from "effect";
+const tagOf = (error) => {
+    if (typeof error !== "object" || error === null || !("_tag" in error)) {
+        return undefined;
+    }
+    return typeof error._tag === "string" ? error._tag : undefined;
+};
 const messageOf = (error) => {
     if (error instanceof Error) {
         return error.message;
@@ -26,57 +33,29 @@ const messageOf = (error) => {
 const fallbackMessage = (input) => input.kind === undefined ? input.message : undefined;
 // Leaves out empty fields, so SvelteKit's defaults apply, and returns nothing when both are empty.
 const body = (message, tag) => {
-    if (!(message || tag)) {
-        return undefined;
+    const fields = {};
+    if (message !== undefined && message !== "") {
+        fields.message = message;
     }
-    return { ...(message ? { message } : {}), ...(tag ? { tag } : {}) };
+    if (tag !== undefined && tag !== "") {
+        fields.tag = tag;
+    }
+    return fields.message === undefined && fields.tag === undefined
+        ? undefined
+        : fields;
 };
-/**
- * A client `handleError` hook (`src/hooks.client.ts`) that keeps the message and `_tag` of errors
- * thrown by your code, so a boundary's `failed` snippet shows them instead of
- * `{ status: 500, message: "Internal Error" }`. It logs those errors like SvelteKit's default
- * hook, and leaves `error(...)` and SvelteKit's own errors as they are. Made for SvelteKit 3:
- * SvelteKit 2 doesn't say which errors are its own, so there every error is kept and logged.
- *
- * **Example** (Using it as the client hook)
- *
- * ```ts
- * // src/hooks.client.ts
- * export { handleClientError as handleError } from "effect-atom-svelte/sveltekit";
- * ```
- *
- * @stability unstable
- * @since 0.1.0
- * @category hooks
- */
-export const handleClientError = (input) => {
+export function handleClientError(input) {
     // Destructured here, not in the parameter list, so the API reference shows a named parameter.
     const { error, kind = "unknown" } = input;
     if (kind !== "unknown") {
         return undefined;
     }
     console.error(error);
-    return body(messageOf(error) ?? fallbackMessage(input), tagOf(error));
-};
-/**
- * A server `handleError` hook (`src/hooks.server.ts`) that keeps the `_tag` of errors thrown by
- * your code but not their message, which could expose details of the server to users: the
- * message stays SvelteKit's `"Internal Error"`. It logs errors with `console.error`.
- * Server errors reach a boundary's `failed` snippet when it renders on the server. Made for
- * SvelteKit 3: SvelteKit 2 doesn't say which errors are its own, so there every error is logged.
- *
- * **Example** (Using it as the server hook)
- *
- * ```ts
- * // src/hooks.server.ts
- * export { handleServerError as handleError } from "effect-atom-svelte/sveltekit";
- * ```
- *
- * @stability unstable
- * @since 0.1.0
- * @category hooks
- */
-export const handleServerError = (input) => {
+    // An error with an empty message gets SvelteKit 2's instead.
+    const message = messageOf(error);
+    return body(message === undefined || message === "" ? fallbackMessage(input) : message, tagOf(error));
+}
+export function handleServerError(input) {
     const { error, issues, kind = "unknown" } = input;
     if (kind === "validation") {
         console.error("Remote function schema validation failed:", issues);
@@ -87,4 +66,104 @@ export const handleServerError = (input) => {
     }
     console.error(error);
     return body(fallbackMessage(input), tagOf(error));
+}
+// Waits for the next popstate, or a second, should none come.
+const nextPopState = () => Effect.runPromise(Effect.callback((resume) => {
+    const done = () => {
+        resume(Effect.undefined);
+    };
+    addEventListener("popstate", done, { once: true });
+    return Effect.sync(() => {
+        removeEventListener("popstate", done);
+    });
+}).pipe(Effect.timeoutOption("1 second")));
+// How long a "yes" lets the retried navigation through. The retry reaches beforeNavigate at once;
+// a navigation that never does, such as a link to a download, doesn't leave a bypass behind.
+const bypassFor = 2000;
+/**
+ * Asks before the user navigates away from a page whose form is dirty, using SvelteKit's
+ * `beforeNavigate`. Call it while a component initializes, with any object that has `dirty`, such
+ * as a form instance from `useForm`.
+ *
+ * While the form is dirty, a navigation is cancelled and `confirm` asked; on yes it is retried, and
+ * the retry goes through. Closing the tab, reloading or typing a URL show the browser's own dialog
+ * instead. SvelteKit doesn't call `beforeNavigate` for back and forward over shallow history entries
+ * (from `pushState` or a hash change) or for links to a hash on the same page, so those aren't
+ * guarded.
+ *
+ * **Example** (Asking before leaving an edit page)
+ *
+ * ```ts
+ * import { useForm } from "effect-atom-svelte";
+ * import { useUnsavedChangesGuard } from "effect-atom-svelte/sveltekit";
+ *
+ * const form = useForm(EditProject, { id, initialValues, submit });
+ * useUnsavedChangesGuard(form, {
+ *   confirm: () => window.confirm("Leave without saving your changes?"),
+ * });
+ * ```
+ *
+ * @see {@link https://atom.jarrednorris.dev/forms | Forms}
+ * @stability unstable
+ * @since 0.4.0
+ * @category forms
+ */
+export const useUnsavedChangesGuard = (form, options) => {
+    // The retry of a navigation the user agreed to: where it goes, whether it unloads the page, and
+    // until when to expect it.
+    let retry;
+    beforeNavigate((navigation) => {
+        // Let the retry through, once. Any other navigation is asked about as usual.
+        if (retry !== undefined &&
+            // oxlint-disable-next-line effecttsgo/global-date -- SvelteKit calls beforeNavigate synchronously, outside any Effect program
+            retry.until > Date.now() &&
+            (navigation.type === "leave"
+                ? retry.unloads
+                : navigation.to?.url.href === retry.href)) {
+            retry = undefined;
+            return;
+        }
+        if (!form.dirty) {
+            return;
+        }
+        // Closing the tab, reloading or typing a URL: cancelling shows the browser's dialog, and no
+        // code of ours can run before the page goes.
+        navigation.cancel();
+        const { to } = navigation;
+        if (navigation.type === "leave" || to === null) {
+            return;
+        }
+        // Cancelling back or forward makes SvelteKit undo the move with history.go, which finishes with
+        // a popstate. A retry before then would be lost to it, so the retry waits for it.
+        const undone = navigation.type === "popstate" ? nextPopState() : undefined;
+        // oxlint-disable-next-line effecttsgo/async-function -- awaits the app's confirm, which may return a Promise, from SvelteKit's beforeNavigate, outside any Effect program
+        void (async () => {
+            if (!(await options.confirm())) {
+                return;
+            }
+            retry = {
+                href: to.url.href,
+                unloads: navigation.type !== "popstate" && navigation.willUnload,
+                // oxlint-disable-next-line effecttsgo/global-date -- compared with Date.now in beforeNavigate, outside any Effect program
+                until: Date.now() + bypassFor,
+            };
+            if (navigation.type === "popstate") {
+                await undone;
+                history.go(navigation.delta);
+            }
+            else if (navigation.willUnload) {
+                // An external link, or one SvelteKit hands to the browser: goto can't follow it. The page
+                // unloading fires a "leave", which the bypass lets through.
+                location.href = to.url.href;
+            }
+            else {
+                // SvelteKit 3 warns in dev whenever the `replaceState` key is there, even false, so it is
+                // passed only when true.
+                await goto(to.url, to.url.href === location.href
+                    ? // oxlint-disable-next-line typescript/no-deprecated -- the peer range includes SvelteKit 2, whose goto has no `replace`, only `replaceState`
+                        { replaceState: true }
+                    : {});
+            }
+        })();
+    });
 };

package/dist/index.d.ts

@@ -40,6 +40,15 @@ export { default as RegistryProvider } from "./RegistryProvider.svelte";
  * @category scoped atoms
  */
 export * as ScopedAtom from "./ScopedAtom.ts";
+/**
+ * Forms driven by one Effect Schema: `Form.make` defines one, `useForm` creates an instance in a
+ * component.
+ *
+ * @stability unstable
+ * @since 0.4.0
+ * @category forms
+ */
+export * as Form from "./Form.ts";
 /**
  * Effect Atom's modules, so an app can import everything from one place.
  *
@@ -47,4 +56,4 @@ export * as ScopedAtom from "./ScopedAtom.ts";
  * @since 0.1.0
  * @category re-exports
  */
-export { AsyncResult, Atom, AtomHttpApi, AtomRef, AtomRegistry, AtomRpc, Hydration, } from "effect/reactivity";
+export { AsyncResult, Atom, AtomHttpApi, AtomRef, AtomRegistry, AtomRpc, Hydration, Reactivity, } from "effect/reactivity";

package/dist/index.js

@@ -40,6 +40,15 @@ export { default as RegistryProvider } from "./RegistryProvider.svelte";
  * @category scoped atoms
  */
 export * as ScopedAtom from "./ScopedAtom.js";
+/**
+ * Forms driven by one Effect Schema: `Form.make` defines one, `useForm` creates an instance in a
+ * component.
+ *
+ * @stability unstable
+ * @since 0.4.0
+ * @category forms
+ */
+export * as Form from "./Form.js";
 /**
  * Effect Atom's modules, so an app can import everything from one place.
  *
@@ -47,4 +56,4 @@ export * as ScopedAtom from "./ScopedAtom.js";
  * @since 0.1.0
  * @category re-exports
  */
-export { AsyncResult, Atom, AtomHttpApi, AtomRef, AtomRegistry, AtomRpc, Hydration, } from "effect/reactivity";
+export { AsyncResult, Atom, AtomHttpApi, AtomRef, AtomRegistry, AtomRpc, Hydration, Reactivity, } from "effect/reactivity";

package/dist/internal/awaitWrite.d.ts

@@ -0,0 +1,11 @@
+import { Exit } from "effect";
+import type { Cause } from "effect";
+import { AsyncResult } from "effect/reactivity";
+import type { Atom, AtomRegistry } from "effect/reactivity";
+/**
+ * A promise-mode setter's wait: as `awaitResult` with `suspendOnWaiting`, but a change to a result
+ * from before the call, which is what `Atom.Reset` from another setter leaves (an idle `Initial`,
+ * or an `Atom.fn`'s `initialValue`), ends it as interrupted. The reset interrupts the call, so
+ * otherwise the wait would hang until the next call, or settle with the initial value.
+ */
+export declare const awaitWrite: <A, E>(registry: AtomRegistry.AtomRegistry, atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>, start: number, signal: AbortSignal) => Promise<Exit.Exit<A, E | Cause.NoSuchElementError>>;

package/dist/internal/awaitWrite.js

@@ -0,0 +1,27 @@
+// Waiting for a write to an async atom to settle, for useAtomSet's promise modes and a form's
+// submit. Internal: not exported from the package.
+import { Effect, Exit } from "effect";
+import { AsyncResult } from "effect/reactivity";
+/**
+ * A promise-mode setter's wait: as `awaitResult` with `suspendOnWaiting`, but a change to a result
+ * from before the call, which is what `Atom.Reset` from another setter leaves (an idle `Initial`,
+ * or an `Atom.fn`'s `initialValue`), ends it as interrupted. The reset interrupts the call, so
+ * otherwise the wait would hang until the next call, or settle with the initial value.
+ */
+export const awaitWrite = (registry, atom, start, signal) => Effect.runPromiseExit(Effect.callback((resume) => {
+    const first = registry.get(atom);
+    if (first._tag !== "Initial" && !first.waiting) {
+        resume(AsyncResult.toExit(first));
+        return;
+    }
+    const cancel = registry.subscribe(atom, (result) => {
+        if (result.waiting) {
+            return;
+        }
+        cancel();
+        const reset = result._tag === "Initial" ||
+            (result._tag === "Success" && result.timestamp < start);
+        resume(reset ? Exit.interrupt() : AsyncResult.toExit(result));
+    });
+    return Effect.sync(cancel);
+}), { signal });

package/dist/internal/boundaries.d.ts

@@ -0,0 +1,9 @@
+import type { AtomRegistry } from "effect/reactivity";
+/**
+ * Per registry, key and queued value, how many live boundaries queued it. Boundaries given the
+ * same state, as a layout and its page might be, queue the same values, and one destroyed first
+ * must leave them for the other's children.
+ */
+export declare const queuedBy: WeakMap<AtomRegistry.AtomRegistry, Map<string, Map<unknown, number>>>;
+/** Whether a live boundary brought a value for the key: it sends that value to the browser itself. */
+export declare const queuedByBoundary: (registry: AtomRegistry.AtomRegistry, key: string) => boolean;

package/dist/internal/boundaries.js

@@ -0,0 +1,10 @@
+/**
+ * Per registry, key and queued value, how many live boundaries queued it. Boundaries given the
+ * same state, as a layout and its page might be, queue the same values, and one destroyed first
+ * must leave them for the other's children.
+ */
+export const queuedBy = new WeakMap();
+/** Whether a live boundary brought a value for the key: it sends that value to the browser itself. */
+export const queuedByBoundary = (registry, key) => 
+// oxlint-disable-next-line sonarjs/no-empty-collection -- HydrationBoundary.svelte fills it; this module only declares it
+queuedBy.get(registry)?.has(key) === true;

package/dist/internal/disposal.d.ts

@@ -0,0 +1,13 @@
+import type { AtomRegistry } from "effect/reactivity";
+/** Calls `f` once if `registry` is disposed of through `disposeRegistry`; returns the canceler. */
+export declare const onDispose: (registry: AtomRegistry.AtomRegistry, f: () => void) => (() => void);
+/**
+ * Disposes of `registry`, then runs what waited on it, even when a finalizer the disposal runs
+ * throws.
+ *
+ * In the browser that error is rethrown on a microtask, so it is still reported as uncaught but
+ * stays out of Svelte's teardown: thrown from the `onDestroy` of a component being destroyed, it
+ * escapes Svelte's flush and leaves every `$derived` on the page running again on every read. On
+ * the server it is thrown here.
+ */
+export declare const disposeRegistry: (registry: AtomRegistry.AtomRegistry) => void;

package/dist/internal/disposal.js

@@ -0,0 +1,43 @@
+import { BROWSER } from "esm-env";
+const callbacks = new WeakMap();
+/** Calls `f` once if `registry` is disposed of through `disposeRegistry`; returns the canceler. */
+export const onDispose = (registry, f) => {
+    let set = callbacks.get(registry);
+    if (set === undefined) {
+        set = new Set();
+        callbacks.set(registry, set);
+    }
+    set.add(f);
+    return () => {
+        set.delete(f);
+    };
+};
+/**
+ * Disposes of `registry`, then runs what waited on it, even when a finalizer the disposal runs
+ * throws.
+ *
+ * In the browser that error is rethrown on a microtask, so it is still reported as uncaught but
+ * stays out of Svelte's teardown: thrown from the `onDestroy` of a component being destroyed, it
+ * escapes Svelte's flush and leaves every `$derived` on the page running again on every read. On
+ * the server it is thrown here.
+ */
+export const disposeRegistry = (registry) => {
+    try {
+        registry.dispose();
+    }
+    catch (error) {
+        if (!BROWSER) {
+            throw error;
+        }
+        queueMicrotask(() => {
+            throw error;
+        });
+    }
+    finally {
+        const set = callbacks.get(registry);
+        callbacks.delete(registry);
+        for (const f of set ?? []) {
+            f();
+        }
+    }
+};

package/dist/internal/form/array.d.ts

@@ -0,0 +1,21 @@
+import type { Engine } from "./engine.ts";
+import type { FieldImpl } from "./field.ts";
+import type { GroupImpl } from "./group.ts";
+import type { IndexPath, KeyPath } from "./paths.ts";
+export declare class ArrayImpl {
+    #private;
+    readonly keyPath: KeyPath;
+    constructor(engine: Engine, keyPath: KeyPath);
+    get path(): IndexPath;
+    get items(): readonly {
+        readonly key: number;
+        readonly index: number;
+        readonly fields: GroupImpl;
+        readonly field: FieldImpl;
+    }[];
+    get error(): string | undefined;
+    append(item: unknown): void;
+    remove(index: number): void;
+    move(from: number, to: number): void;
+    replace(index: number, item: unknown): void;
+}

package/dist/internal/form/array.js

@@ -0,0 +1,57 @@
+import { pathId } from "./paths.js";
+export class ArrayImpl {
+    #engine;
+    keyPath;
+    constructor(engine, keyPath) {
+        this.#engine = engine;
+        this.keyPath = keyPath;
+    }
+    get path() {
+        return this.#engine.indexPath(this.keyPath) ?? [];
+    }
+    get items() {
+        const keys = this.#engine.state.keys.get(pathId(this.keyPath)) ?? [];
+        return keys.map((key, index) => ({
+            field: this.#engine.field([...this.keyPath, key]),
+            fields: this.#engine.group([...this.keyPath, key]),
+            index,
+            key,
+        }));
+    }
+    get error() {
+        return this.#engine.errorAt(this.keyPath);
+    }
+    append(item) {
+        this.#engine.updateArray(this.keyPath, (items, keys) => {
+            items.push(item);
+            keys.push(this.#engine.newKey());
+        });
+    }
+    remove(index) {
+        this.#engine.updateArray(this.keyPath, (items, keys) => {
+            if (index >= 0 && index < items.length) {
+                items.splice(index, 1);
+                keys.splice(index, 1);
+            }
+        });
+    }
+    move(from, to) {
+        this.#engine.updateArray(this.keyPath, (items, keys) => {
+            const inRange = (index) => index >= 0 && index < items.length;
+            if (!(inRange(from) && inRange(to)) || from === to) {
+                return;
+            }
+            items.splice(to, 0, ...items.splice(from, 1));
+            keys.splice(to, 0, ...keys.splice(from, 1));
+        });
+    }
+    replace(index, item) {
+        this.#engine.updateArray(this.keyPath, (items, keys) => {
+            if (index >= 0 && index < items.length) {
+                items[index] = item;
+                // A new item: the old one's errors and touched state don't carry over.
+                keys[index] = this.#engine.newKey();
+            }
+        });
+    }
+}

package/dist/internal/form/constraints.d.ts

@@ -0,0 +1,13 @@
+import { SchemaAST } from "effect";
+import type { IndexPath } from "./paths.ts";
+/** The attributes `field.constraints` can set. */
+export interface Constraints {
+    readonly required?: boolean | undefined;
+    readonly minlength?: number | undefined;
+    readonly maxlength?: number | undefined;
+    readonly min?: number | undefined;
+    readonly max?: number | undefined;
+    readonly pattern?: string | undefined;
+}
+/** The HTML constraints for the field at `path` in `schema`'s AST. */
+export declare const constraintsAt: (root: SchemaAST.AST, path: IndexPath) => Constraints;