effect-atom-svelte 0.2.0 → 0.4.0

package/dist/Form.js

@@ -0,0 +1,67 @@
+/**
+ * Forms driven by one Effect Schema. `Form.make` defines a form from a Schema whose encoded side is
+ * what inputs hold and whose decoded side is what a submit sends; `useForm` creates an instance in
+ * a component, and `Form.instance` creates one without Svelte. The module is headless: it gives
+ * values, errors and element attributes, and no components.
+ *
+ * @since 0.4.0
+ */
+import { Duration } from "effect";
+import { AtomRegistry } from "effect/reactivity";
+import { engineOf, initialGetter } from "./internal/form/engineOf.js";
+import { FormValidationError } from "./internal/form/validationError.js";
+// A const and a type of the same name, as in Effect's modules.
+/* oxlint-disable eslint/no-redeclare */
+/**
+ * Marks a value as a form definition: every definition has this key, set to this same string.
+ *
+ * @stability unstable
+ * @since 0.4.0
+ * @category type ids
+ */
+export const TypeId = "~effect-atom-svelte/Form";
+const definitionOf = (schema, options) => ({
+    checkHook: options.checkHook,
+    debounce: options.debounce === undefined ? 0 : Duration.toMillis(options.debounce),
+    leafHook: options.leafHook,
+    name: options.name,
+    revalidateOn: options.revalidateOn ?? "input",
+    runtime: options.runtime,
+    schema,
+    validateOn: options.validateOn ?? "blur",
+});
+export function make(schema, options = {}) {
+    return {
+        [TypeId]: TypeId,
+        definition: definitionOf(schema, options),
+        schema,
+    };
+}
+/**
+ * Whether a value is a form definition from `Form.make`.
+ *
+ * @stability unstable
+ * @since 0.4.0
+ * @category guards
+ */
+export const isForm = (u) => typeof u === "object" && u !== null && TypeId in u;
+/* oxlint-disable eslint/no-redeclare */
+/**
+ * Why `submit` didn't call the submit atom: the values didn't decode. `errors` lists what showed.
+ * Its `_tag` is `"FormValidationError"`, for `Effect.catchTag`.
+ *
+ * @stability unstable
+ * @since 0.4.0
+ * @category errors
+ */
+export const ValidationError = FormValidationError;
+export function instance(form, options) {
+    const initial = options.initialValues;
+    const getInitial = initialGetter(initial);
+    return engineOf(form, {
+        ...options,
+        initialValues: getInitial ? getInitial() : initial,
+        registry: options.registry ?? AtomRegistry.make(),
+        validates: true,
+    }).root;
+}

package/dist/Hooks.svelte.d.ts

@@ -4,8 +4,10 @@
  * @since 0.1.0
  */
 import { Exit } from "effect";
+import type { Schema } from "effect";
 import { AsyncResult, Atom } from "effect/reactivity";
 import type { AtomRef } from "effect/reactivity";
+import type * as Form from "./Form.ts";
 /**
  * An atom, or a getter so the hook follows the atom when reactive state picks a different one.
  *
@@ -122,12 +124,14 @@ export declare const useAtomMount: (input: AtomInput<Atom.Atom<unknown>>) => voi
  *
  * In `promise` and `promiseExit` modes the setter waits for the atom's next settled result. The
  * wait holds the atom, so a call still in flight keeps it running after the component is
- * destroyed, until it settles. The call's `signal` cancels only the wait: an `Atom.fn` already
+ * destroyed, until it settles, unless the `RegistryProvider` that created the registry is
+ * destroyed: that interrupts the call and settles it as interrupted. The call's `signal` cancels only the wait: an `Atom.fn` already
  * running keeps going (send `Atom.Interrupt` to stop it). A signal that is already aborted settles
  * the call as interrupted without writing, as `fetch` does. Calls on one `Atom.fn` share its single
  * result, so a new call supersedes one in flight and every pending call resolves with the latest
  * call's result. `Atom.Reset` has no result to wait for, so these modes leave it out of their
- * types and reject it; reset with a `value` mode setter.
+ * types and reject it; reset with a `value` mode setter. A reset written while a promise-mode call
+ * is pending settles that promise as interrupted. To cancel a call, send `Atom.Interrupt`.
  *
  * **Example** (Updating an atom from its current value)
  *
@@ -207,9 +211,10 @@ export declare const useAtomSubscribe: <A>(input: AtomInput<Atom.Atom<A>>, f: (v
  * an atom that can only compute in the browser can start from a value on the server.
  *
  * A value applies once while the atom is held, so a component mounted later, or a second
- * component with its own value, does not overwrite a value the atom has moved on from. Once nothing
- * holds the atom and the registry disposes it, the next component to start it applies its value
- * again. On the server a value lasts one render, so each request against a shared registry applies
+ * component with its own value, does not overwrite a value the atom has moved on from since the
+ * first applied one. An atom that is already in use without one, read by another component, is set
+ * to the value, as `@effect/atom-react` does. Once nothing holds the atom and the registry disposes
+ * it, the next component to start it applies its value again. On the server a value lasts one render, so each request against a shared registry applies
  * its own; requests rendering at the same time share the registry's atoms, and with them the value
  * the first one applied.
  *
@@ -232,8 +237,9 @@ export declare const useAtomSubscribe: <A>(input: AtomInput<Atom.Atom<A>>, f: (v
  */
 export declare const useAtomInitialValues: (initialValues: Iterable<readonly [Atom.Atom<unknown>, unknown]>) => void;
 /**
- * Reads an `AtomRef`, following it when the getter returns a different ref. For one property of a
- * ref, use `useAtomRefPropValue`.
+ * Reads an `AtomRef`, following it when the getter returns a different ref. For a writable ref,
+ * `current` can be assigned too, which sets the ref, so `bind:value={name.current}` works; a
+ * read-only ref, as from `map`, can't be. For one property of a ref, use `useAtomRefPropValue`.
  *
  * A ref has no registry. On the server, one created at module level is shared by every request,
  * so don't write a visitor's data to it there: see
@@ -253,7 +259,8 @@ export declare const useAtomInitialValues: (initialValues: Iterable<readonly [At
  * @since 0.1.0
  * @category hooks
  */
-export declare const useAtomRef: <A>(input: AtomInput<AtomRef.ReadonlyRef<A>>) => AtomValue<A>;
+export declare function useAtomRef<A>(input: AtomInput<AtomRef.AtomRef<A>>): AtomState<A>;
+export declare function useAtomRef<A>(input: AtomInput<AtomRef.ReadonlyRef<A>>): AtomValue<A>;
 /**
  * Returns `ref.prop(prop)`, the `AtomRef` for one property of an `AtomRef`. It takes the ref
  * itself, not a getter, and does not follow later changes to `ref` or `prop`; to read a property
@@ -276,7 +283,8 @@ export declare const useAtomRef: <A>(input: AtomInput<AtomRef.ReadonlyRef<A>>) =
 export declare const useAtomRefProp: <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K) => AtomRef.AtomRef<A[K]>;
 /**
  * Reads one property of an `AtomRef`, following the getter to a different ref. `prop` is taken
- * once, when the component starts, and is not followed.
+ * once, when the component starts, and is not followed. Assigning `current` sets the property, so
+ * `bind:checked={done.current}` works.
  *
  * **Example** (Reading one property of a ref)
  *
@@ -292,7 +300,7 @@ export declare const useAtomRefProp: <A, K extends keyof A>(ref: AtomRef.AtomRef
  * @since 0.1.0
  * @category hooks
  */
-export declare const useAtomRefPropValue: <A, K extends keyof A>(input: AtomInput<AtomRef.AtomRef<A>>, prop: K) => AtomValue<A[K]>;
+export declare const useAtomRefPropValue: <A, K extends keyof A>(input: AtomInput<AtomRef.AtomRef<A>>, prop: K) => AtomState<A[K]>;
 /**
  * Options for `useAtomResult`.
  *
@@ -394,3 +402,55 @@ export declare function useAtomSuspense<A, E>(input: AtomInput<Atom.Atom<AsyncRe
 export declare function useAtomSuspense<A, E>(input: AtomInput<Atom.Atom<AsyncResult.AsyncResult<A, E>>>, options?: SuspenseOptions & {
     readonly includeFailure?: boolean | undefined;
 }): AtomValue<Promise<A | AsyncResult.Success<A, E> | AsyncResult.Failure<A, E>>>;
+/**
+ * Creates an instance of a form from `Form.make` in a component. Its state lives in the
+ * component's registry and is released when the component is destroyed; a submit in flight keeps
+ * it, and keeps its atom running, until the submit settles, so a save finishes after a dialog
+ * closes. Share an instance by passing it down, or create it in the parent whose lifetime it
+ * should have, such as a wizard around its steps.
+ *
+ * Pass `id` from `$props.id()`: field ids are built from it, and must match between the server and
+ * the browser. On the server the form renders from `initialValues` and doesn't validate, so there
+ * is nothing to hydrate. A getter for `initialValues` is followed: when it changes, a clean form
+ * takes the new values and a dirty one keeps its edits.
+ *
+ * **Example** (A login form)
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { useForm } from "effect-atom-svelte";
+ *   import { Login, loginAtom } from "./forms.ts";
+ *
+ *   const id = $props.id();
+ *   const form = useForm(Login, {
+ *     id,
+ *     initialValues: { email: "", password: "" },
+ *     submit: { atom: loginAtom },
+ *     mapError: (error) =>
+ *       error._tag === "WrongPassword"
+ *         ? { form: "Wrong email or password" }
+ *         : undefined,
+ *   });
+ *   const email = form.field("email");
+ * </script>
+ *
+ * <form {...form.attrs}>
+ *   <label for={email.id}>Email</label>
+ *   <input {...email.attrs} bind:value={email.value} />
+ *   {#if email.error}
+ *     <p id={email.errorId}>{email.error}</p>
+ *   {/if}
+ *   {#if form.rootError}
+ *     <p role="alert">{form.rootError}</p>
+ *   {/if}
+ *   <button disabled={form.submitting}>Log in</button>
+ * </form>
+ * ```
+ *
+ * @see {@link https://atom.jarrednorris.dev/forms | Forms}
+ * @stability unstable
+ * @since 0.4.0
+ * @category hooks
+ */
+export declare function useForm<F extends Form.Form<Schema.Top>, A, E, W, Args = undefined>(form: F, options: Form.InstanceOptions<Form.Encoded<F>, Form.Decoded<F>, A, E, W, Args>): Form.Instance<Form.Encoded<F>, Form.Decoded<F>, A, E, Args>;
+export declare function useForm<F extends Form.Form<Schema.Top>>(form: F, options: Form.ValidateOnlyOptions<Form.Encoded<F>>): Form.Instance<Form.Encoded<F>, Form.Decoded<F>, Form.Decoded<F>, never, void>;