effect-atom-svelte 0.2.0 → 0.4.0

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

@@ -0,0 +1,26 @@
+import { Atom } from "effect/reactivity";
+import type { AtomRegistry } from "effect/reactivity";
+import { Engine } from "./engine.ts";
+import type { Definition } from "./types.ts";
+/** An engine for a form definition, from the options `useForm` and `Form.instance` take. */
+export declare const engineOf: (form: {
+    readonly definition: Definition;
+}, options: {
+    readonly registry: AtomRegistry.AtomRegistry;
+    readonly initialValues: unknown;
+    readonly validates: boolean;
+    readonly id: string;
+    readonly values?: Atom.Writable<unknown> | undefined;
+    readonly submit?: {
+        readonly atom: unknown;
+        readonly payload?: unknown;
+    } | undefined;
+    readonly mapError?: unknown;
+    readonly autoSubmit?: boolean | undefined;
+    readonly resetOnSuccess?: boolean | undefined;
+}) => Engine;
+/**
+ * The function that computes a form's initial values, when `initialValues` is one rather than the
+ * values themselves.
+ */
+export declare const initialGetter: (initial: unknown) => (() => unknown) | undefined;

package/dist/internal/form/engineOf.js

@@ -0,0 +1,43 @@
+// Builds a form engine from the public options. Internal: not exported from the package.
+import { Atom } from "effect/reactivity";
+import { Engine } from "./engine.js";
+/** An engine for a form definition, from the options `useForm` and `Form.instance` take. */
+export const engineOf = (form, options) => {
+    const { submit } = options;
+    const atom = submit?.atom;
+    const getAtom = typeof atom === "function" && !Atom.isAtom(atom) ? atom : () => atom;
+    return new Engine(form.definition, {
+        autoSubmit: options.autoSubmit,
+        id: options.id,
+        initialValues: options.initialValues,
+        // SAFETY: the overloads of useForm and Form.instance type mapError as taking the submit atom's
+        // error and returning errors for the form's values.
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the implementation signatures can't carry the overloads' types
+        mapError: options.mapError,
+        registry: options.registry,
+        resetOnSuccess: options.resetOnSuccess,
+        submit: submit === undefined
+            ? undefined
+            : {
+                // SAFETY: the overloads type the submit atom as a writable AsyncResult atom, or a
+                // function returning one; anything else that is a function is the second.
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a typeof check can't recover the function's signature
+                atom: getAtom,
+                // SAFETY: the overloads type payload as a function of the decoded values and the
+                // submit's arguments.
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the implementation signatures can't carry the overloads' types
+                payload: submit.payload,
+            },
+        validates: options.validates,
+        values: options.values,
+    });
+};
+/**
+ * The function that computes a form's initial values, when `initialValues` is one rather than the
+ * values themselves.
+ */
+export const initialGetter = (initial) => 
+// SAFETY: the overloads type initialValues as the values or a function of no arguments that
+// returns them, so a function here is the second.
+// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a typeof check can't recover the function's signature
+typeof initial === "function" ? initial : undefined;

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

@@ -0,0 +1,30 @@
+import type { Constraints } from "./constraints.ts";
+import type { Engine } from "./engine.ts";
+import type { IndexPath, KeyPath } from "./paths.ts";
+export declare class FieldImpl {
+    #private;
+    readonly keyPath: KeyPath;
+    constructor(engine: Engine, keyPath: KeyPath);
+    get path(): IndexPath;
+    get value(): unknown;
+    set value(value: unknown);
+    get error(): string | undefined;
+    get issue(): string | undefined;
+    get touched(): boolean;
+    set touched(touched: boolean);
+    get dirty(): boolean;
+    get validating(): boolean;
+    get id(): string;
+    get errorId(): string;
+    get name(): string;
+    get attrs(): {
+        readonly "aria-describedby": string | undefined;
+        readonly "aria-invalid": true | undefined;
+        readonly id: string;
+        readonly name: string;
+        readonly onblur: () => void;
+    };
+    get constraints(): Constraints;
+    /** What leaving the field does, for a custom control with no blur event of its own. */
+    blur(): void;
+}

package/dist/internal/form/field.js

@@ -0,0 +1,68 @@
+import { equals, getIn, nameOf, pathId } from "./paths.js";
+export class FieldImpl {
+    #engine;
+    keyPath;
+    #onblur = () => {
+        this.#engine.leave(this.keyPath);
+    };
+    constructor(engine, keyPath) {
+        this.#engine = engine;
+        this.keyPath = keyPath;
+    }
+    get path() {
+        return this.#engine.indexPath(this.keyPath) ?? [];
+    }
+    get value() {
+        const index = this.#engine.indexPath(this.keyPath);
+        return index === undefined ? undefined : getIn(this.#engine.values, index);
+    }
+    set value(value) {
+        this.#engine.setField(this.keyPath, value);
+    }
+    get error() {
+        return this.#engine.errorAt(this.keyPath);
+    }
+    get issue() {
+        return this.#engine.state.issues.get(pathId(this.keyPath));
+    }
+    get touched() {
+        return this.#engine.state.touched.has(pathId(this.keyPath));
+    }
+    set touched(touched) {
+        this.#engine.setTouched(this.keyPath, touched);
+    }
+    get dirty() {
+        const index = this.#engine.indexPath(this.keyPath);
+        return (index !== undefined &&
+            !equals(getIn(this.#engine.values, index), getIn(this.#engine.state.initial, index)));
+    }
+    get validating() {
+        return this.#engine.state.validating;
+    }
+    get id() {
+        return this.#engine.elementId(this.keyPath);
+    }
+    get errorId() {
+        return `${this.id}-error`;
+    }
+    get name() {
+        return nameOf(this.path);
+    }
+    get attrs() {
+        const invalid = this.error !== undefined;
+        return {
+            "aria-describedby": invalid ? this.errorId : undefined,
+            "aria-invalid": invalid ? true : undefined,
+            id: this.id,
+            name: this.name,
+            onblur: this.#onblur,
+        };
+    }
+    get constraints() {
+        return this.#engine.constraints(this.path);
+    }
+    /** What leaving the field does, for a custom control with no blur event of its own. */
+    blur() {
+        this.#onblur();
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { ArrayImpl } from "./array.ts";
+import type { Engine } from "./engine.ts";
+import type { FieldImpl } from "./field.ts";
+import type { IndexPath, KeyPath } from "./paths.ts";
+export declare class GroupImpl {
+    readonly engine: Engine;
+    readonly keyPath: KeyPath;
+    constructor(engine: Engine, keyPath: KeyPath);
+    get path(): IndexPath;
+    field(path: string | IndexPath): FieldImpl;
+    array(path: string | IndexPath): ArrayImpl;
+    at(path: string | IndexPath): GroupImpl;
+}

package/dist/internal/form/group.js

@@ -0,0 +1,20 @@
+export class GroupImpl {
+    engine;
+    keyPath;
+    constructor(engine, keyPath) {
+        this.engine = engine;
+        this.keyPath = keyPath;
+    }
+    get path() {
+        return this.engine.indexPath(this.keyPath) ?? [];
+    }
+    field(path) {
+        return this.engine.field(this.engine.resolve(this.keyPath, path));
+    }
+    array(path) {
+        return this.engine.array(this.engine.resolve(this.keyPath, path));
+    }
+    at(path) {
+        return this.engine.group(this.engine.resolve(this.keyPath, path));
+    }
+}

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

@@ -0,0 +1,41 @@
+import { Exit, Option } from "effect";
+import type { AsyncResult } from "effect/reactivity";
+import type { Engine } from "./engine.ts";
+import { GroupImpl } from "./group.ts";
+import type { IndexPath } from "./paths.ts";
+import type { ErrorsInput } from "./types.ts";
+export declare class InstanceImpl extends GroupImpl {
+    #private;
+    constructor(engine: Engine);
+    get values(): unknown;
+    get initialValues(): unknown;
+    get dirty(): boolean;
+    get valid(): boolean;
+    get validating(): boolean;
+    get submitting(): boolean;
+    get submitResult(): AsyncResult.AsyncResult<unknown, unknown>;
+    get rootError(): string | undefined;
+    get errors(): readonly {
+        readonly path: IndexPath;
+        readonly message: string;
+    }[];
+    get submitCount(): number;
+    get validationCount(): number;
+    get lastSubmitted(): Option.Option<{
+        readonly encoded: unknown;
+        readonly decoded: unknown;
+    }>;
+    get dirtySinceSubmit(): boolean;
+    get attrs(): {
+        readonly novalidate: true;
+        readonly onsubmit: (event: Event) => void;
+    };
+    submit(args?: unknown): Promise<Exit.Exit<unknown, unknown>>;
+    validate(paths?: readonly (string | IndexPath)[]): Promise<boolean>;
+    setValues(values: unknown): void;
+    reset(values?: unknown): void;
+    revertToLastSubmit(): void;
+    setErrors(errors: ErrorsInput): void;
+    focusFirstError(): void;
+    dispose(): void;
+}

package/dist/internal/form/instance.js

@@ -0,0 +1,135 @@
+// A form instance: the root group, with the form's state and actions. Internal: `Form.ts` types it.
+import { Cause, Exit, Option } from "effect";
+import { GroupImpl } from "./group.js";
+import { equals, fromPathId, pathId, toKeyPath } from "./paths.js";
+import { FormValidationError } from "./validationError.js";
+export class InstanceImpl extends GroupImpl {
+    #onsubmit = (event) => {
+        event.preventDefault();
+        void this.#submitAndFocus();
+    };
+    // oxlint-disable-next-line effecttsgo/async-function -- the form's submit handler, which awaits the Promise-facing submit, outside any Effect program
+    async #submitAndFocus() {
+        const exit = await this.submit();
+        if (Exit.isFailure(exit)) {
+            const error = Cause.findErrorOption(exit.cause);
+            if (Option.isSome(error) && error.value instanceof FormValidationError) {
+                this.focusFirstError();
+            }
+        }
+    }
+    constructor(engine) {
+        super(engine, []);
+    }
+    get values() {
+        return this.engine.values;
+    }
+    get initialValues() {
+        return this.engine.state.initial;
+    }
+    get dirty() {
+        return !equals(this.engine.values, this.engine.state.initial);
+    }
+    get valid() {
+        const { state } = this.engine;
+        const current = state.checked === this.engine.values && !state.validating;
+        return (current &&
+            state.failure === undefined &&
+            state.issues.size === 0 &&
+            state.external.size === 0);
+    }
+    get validating() {
+        return this.engine.state.validating;
+    }
+    get submitting() {
+        return this.engine.state.submitting;
+    }
+    get submitResult() {
+        return this.engine.state.submitResult;
+    }
+    get rootError() {
+        return this.engine.errorAt([]);
+    }
+    get errors() {
+        const { state } = this.engine;
+        const out = [];
+        const seen = new Set();
+        const add = (id) => {
+            if (seen.has(id)) {
+                return;
+            }
+            seen.add(id);
+            const keyPath = fromPathId(id);
+            const message = this.engine.errorAt(keyPath);
+            const path = this.engine.indexPath(keyPath);
+            if (message !== undefined && path !== undefined) {
+                out.push({ message, path });
+            }
+        };
+        add(pathId([]));
+        for (const id of state.issues.keys()) {
+            add(id);
+        }
+        for (const id of state.external.keys()) {
+            add(id);
+        }
+        return out;
+    }
+    get submitCount() {
+        return this.engine.state.submitCount;
+    }
+    get validationCount() {
+        return this.engine.state.validationCount;
+    }
+    get lastSubmitted() {
+        return this.engine.state.lastSubmitted;
+    }
+    get dirtySinceSubmit() {
+        const last = this.engine.state.lastSubmitted;
+        return (Option.isSome(last) && !equals(this.engine.values, last.value.encoded));
+    }
+    get attrs() {
+        return { novalidate: true, onsubmit: this.#onsubmit };
+    }
+    submit(args) {
+        return this.engine.submit(args);
+    }
+    validate(paths) {
+        return this.engine.validate(paths);
+    }
+    setValues(values) {
+        this.engine.setValues(values);
+    }
+    reset(values) {
+        this.engine.reset(values);
+    }
+    revertToLastSubmit() {
+        this.engine.revertToLastSubmit();
+    }
+    setErrors(errors) {
+        this.engine.setErrors(errors, "manual");
+    }
+    focusFirstError() {
+        if (typeof document === "undefined") {
+            return;
+        }
+        // The ids of the fields showing an error, as in `field.attrs`.
+        const selectors = [];
+        for (const { path } of this.errors) {
+            const keyPath = path.length === 0 ? undefined : toKeyPath(this.engine.state.keys, path);
+            if (keyPath !== undefined) {
+                selectors.push(`#${CSS.escape(this.engine.elementId(keyPath))}`);
+            }
+        }
+        if (selectors.length === 0) {
+            return;
+        }
+        // querySelector finds the first match in document order: the first on the page, which may not
+        // be the Schema's first, as for a `{ city, street }` laid out street first. A field whose
+        // element isn't on the page is skipped.
+        document.querySelector(selectors.join(","))?.focus();
+    }
+    dispose() {
+        this.engine.dispose();
+    }
+}

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

@@ -0,0 +1,23 @@
+import { SchemaIssue } from "effect";
+import type { IndexPath } from "./paths.ts";
+/** A message for a leaf issue, or `undefined` to fall back on Effect's. */
+export type LeafHook = (issue: SchemaIssue.Leaf) => string | undefined;
+/** A message for a failed check, or `undefined` to fall back on Effect's. */
+export type CheckHook = (issue: SchemaIssue.Filter) => string | undefined;
+/** One error from a decode: where it is, and what to show. */
+export interface PathIssue {
+    readonly path: IndexPath;
+    readonly message: string;
+}
+interface Hooks {
+    readonly leafHook?: LeafHook | undefined;
+    readonly checkHook?: CheckHook | undefined;
+}
+/**
+ * Every issue in a decode failure, as Effect's Standard Schema formatter walks them, but with the
+ * message chosen in this order: the Schema's annotation, then the caller's hook, then Effect's
+ * default. A check that carries a `message` annotation and points at a sub-path keeps that path;
+ * Effect's formatter would report it at the check's own path.
+ */
+export declare const toPathIssues: (issue: SchemaIssue.Issue, hooks: Hooks) => readonly PathIssue[];
+export {};

package/dist/internal/form/issues.js

@@ -0,0 +1,144 @@
+import { SchemaIssue } from "effect";
+// The lookup Effect's default hooks do (`findMessage` in SchemaIssue.ts, which is private): a
+// `message` annotation, or `messageMissingKey`/`messageUnexpectedKey` for those issues. Done here
+// so an annotated message wins over the caller's hooks, which would otherwise replace Effect's
+// default hooks and with them the annotation lookup.
+const messageKeys = {
+    MissingKey: "messageMissingKey",
+    UnexpectedKey: "messageUnexpectedKey",
+};
+const findMessage = (issue) => {
+    if (issue._tag === "Pointer") {
+        return undefined;
+    }
+    if (issue._tag === "Encoding") {
+        return findMessage(issue.issue);
+    }
+    let source;
+    if (issue._tag === "Filter") {
+        source = issue.filter;
+    }
+    else if ("annotations" in issue) {
+        source = issue;
+    }
+    else {
+        source = issue.ast;
+    }
+    const { annotations } = source;
+    const message = annotations?.[messageKeys[issue._tag] ?? "message"];
+    return typeof message === "string" ? message : undefined;
+};
+const effectFormatter = SchemaIssue.makeFormatterStandardSchemaV1();
+// Paths from Effect are PropertyKeys, or `{ key }` in Standard Schema's type; a form's paths are
+// object keys and array indexes.
+const normalize = (path) => path.map((segment) => {
+    const key = typeof segment === "object" ? segment.key : segment;
+    return typeof key === "number" ? key : String(key);
+});
+// The paths a check's issue points at, below `path`: a check on a Struct that returns
+// `{ path, issue }` wraps its issue in a Pointer.
+const pointedPaths = (issue, path) => {
+    switch (issue._tag) {
+        case "Pointer": {
+            return [[...path, ...issue.path]];
+        }
+        case "Composite":
+        case "AnyOf": {
+            return issue.issues.flatMap((inner) => pointedPaths(inner, path));
+        }
+        case "Encoding": {
+            return pointedPaths(issue.issue, path);
+        }
+        case "Filter":
+        case "Forbidden":
+        case "InvalidType":
+        case "InvalidValue":
+        case "MissingKey":
+        case "OneOf":
+        case "UnexpectedKey": {
+            return [];
+        }
+    }
+};
+// Effect's own message for an issue it formats with no hook, at `path`.
+const emitDefault = (issue, path, emit) => {
+    for (const formatted of effectFormatter(issue).issues) {
+        emit([...path, ...(formatted.path ?? [])], formatted.message);
+    }
+};
+const walkFilter = (issue, path, hooks, emit, walk) => {
+    const pointed = pointedPaths(issue.issue, path);
+    const annotated = findMessage(issue.issue) ?? findMessage(issue);
+    if (annotated !== undefined) {
+        for (const target of pointed.length > 0 ? pointed : [path]) {
+            emit(target, annotated);
+        }
+        return;
+    }
+    // A check that points at fields carries its own messages there ({ path, issue }), so the
+    // caller's hook doesn't replace them.
+    if (pointed.length > 0) {
+        walk(issue.issue, path);
+        return;
+    }
+    const hooked = hooks.checkHook?.(issue);
+    if (hooked !== undefined) {
+        emit(path, hooked);
+    }
+    else if (issue.issue._tag === "InvalidValue") {
+        emitDefault(issue, path, emit);
+    }
+    else {
+        walk(issue.issue, path);
+    }
+};
+/**
+ * Every issue in a decode failure, as Effect's Standard Schema formatter walks them, but with the
+ * message chosen in this order: the Schema's annotation, then the caller's hook, then Effect's
+ * default. A check that carries a `message` annotation and points at a sub-path keeps that path;
+ * Effect's formatter would report it at the check's own path.
+ */
+export const toPathIssues = (issue, hooks) => {
+    const out = [];
+    const emit = (path, message) => {
+        out.push({ message, path: normalize(path) });
+    };
+    const walk = (current, path) => {
+        switch (current._tag) {
+            case "Filter": {
+                walkFilter(current, path, hooks, emit, walk);
+                return;
+            }
+            case "Encoding": {
+                walk(current.issue, path);
+                return;
+            }
+            case "Pointer": {
+                walk(current.issue, [...path, ...current.path]);
+                return;
+            }
+            case "Composite":
+            case "AnyOf": {
+                if (current.issues.length === 0) {
+                    emitDefault(current, path, emit);
+                }
+                for (const inner of current.issues) {
+                    walk(inner, path);
+                }
+                return;
+            }
+            case "Forbidden":
+            case "InvalidType":
+            case "InvalidValue":
+            case "MissingKey":
+            case "OneOf":
+            case "UnexpectedKey": {
+                emit(path, findMessage(current) ??
+                    hooks.leafHook?.(current) ??
+                    SchemaIssue.defaultLeafHook(current));
+            }
+        }
+    };
+    walk(issue, []);
+    return out;
+};

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

@@ -0,0 +1,47 @@
+/** A path into a form's values: object keys, and numbers for array indexes. */
+export type IndexPath = readonly (string | number)[];
+/** A path with each array index replaced by that item's key. */
+export type KeyPath = readonly (string | number)[];
+/** Item keys per array, by the array's key path (as `pathId`). */
+export type Keys = ReadonlyMap<string, readonly number[]>;
+/** A string for a key path, to use as a map key. */
+export declare const pathId: (path: KeyPath) => string;
+/** Parses a `pathId` back into its path. */
+export declare const fromPathId: (id: string) => KeyPath;
+/** The value at `path`, or `undefined` when a step is missing. */
+export declare const getIn: (root: unknown, path: IndexPath) => unknown;
+/** A copy of `root` with `value` at `path`, sharing everything off the path. */
+export declare const setIn: (root: unknown, path: IndexPath, value: unknown) => unknown;
+/** Whether `path` starts with `prefix`. */
+export declare const startsWith: (path: KeyPath, prefix: KeyPath) => boolean;
+/**
+ * The key path for an index path, or `undefined` when an index has no item. A number segment is an
+ * index only where the value so far is an array; a record's numeric-looking keys are strings.
+ */
+export declare const toKeyPath: (keys: Keys, path: IndexPath) => KeyPath | undefined;
+/** The index path for a key path, or `undefined` when one of its items is gone. */
+export declare const toIndexPath: (keys: Keys, path: KeyPath) => IndexPath | undefined;
+/**
+ * Item keys for every array in `values`. Arrays that already have keys keep them, by position, and
+ * new positions take fresh keys from `next`; keys for arrays that are gone are dropped.
+ */
+export declare const reconcileKeys: (values: unknown, previous: Keys, next: () => number) => Map<string, readonly number[]>;
+/** Whether every item key in `path` still belongs to its array. */
+export declare const isLive: (keys: Keys, path: KeyPath) => boolean;
+/**
+ * Equality for form values. Arrays and plain objects compare by content, with a key set to
+ * `undefined` the same as a missing one; dates by time; values that implement Effect's `Equal`
+ * (`Option`, `HashMap`) by `Equal.equals`. Any other class instance compares by identity: a
+ * `File`, a `Map`, and also a `Data.Class` or `Schema.Class` value, which in Effect 4 doesn't
+ * implement `Equal`. So a fresh instance with the same content counts as a change.
+ */
+export declare const equals: (a: unknown, b: unknown) => boolean;
+/**
+ * A string for a key path that is safe in an element id and different for every path:
+ * `items-_7-qty`. Segments are joined with `-`, an item key is `_` and the number, and any other
+ * character of a key than a letter or a digit is escaped (`a-b` is `a_2d_b`), so a key can't
+ * produce a `-` or an item key's form.
+ */
+export declare const idSuffix: (path: KeyPath) => string;
+/** The `name` attribute for an index path: `items.0.qty`. */
+export declare const nameOf: (path: IndexPath) => string;