@shivaedev/form 0.0.0 → 0.6.2

package/src/messages.ts

@@ -0,0 +1,114 @@
+import { Option, Result, SchemaAST, SchemaIssue, type StandardSchema } from "effect";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import * as Atom from "effect/reactivity/Atom";
+
+export type FieldMessages = Readonly<Record<string, string>>;
+
+export const noMessages: FieldMessages = {};
+
+const REQUIRED = "Required";
+
+const MINIMUM_LENGTH = "effect/schema/isMinLength";
+
+function refusesEmpty(check: SchemaAST.Filter<unknown>): boolean {
+	const representation = check.annotations?.representation;
+	if (representation === undefined || representation.id !== MINIMUM_LENGTH) {
+		return false;
+	}
+	const payload = representation.payload;
+	if (typeof payload !== "object" || payload === null || !("minLength" in payload)) {
+		return false;
+	}
+	return payload.minLength === 1;
+}
+
+const checkHook: SchemaIssue.CheckHook = (issue) => SchemaIssue.defaultCheckHook(issue) ?? (refusesEmpty(issue.filter) ? REQUIRED : undefined);
+
+const formatIssue = SchemaIssue.makeFormatterStandardSchemaV1({ checkHook });
+
+function segmentKey(segment: PropertyKey | StandardSchema.StandardSchemaV1.PathSegment): string {
+	return typeof segment === "object" ? String(segment.key) : String(segment);
+}
+
+export function messagesByField(issue: SchemaIssue.Issue): FieldMessages {
+	const messages: Record<string, string> = Object.create(null);
+	for (const entry of formatIssue(issue).issues) {
+		const head = entry.path?.[0];
+		if (head === undefined) {
+			continue;
+		}
+		const name = segmentKey(head);
+		if (!Object.hasOwn(messages, name)) {
+			messages[name] = entry.message;
+		}
+	}
+	return messages;
+}
+
+export function messageAtPath(issue: SchemaIssue.Issue, path: readonly PropertyKey[]): string | undefined {
+	for (const entry of formatIssue(issue).issues) {
+		if (
+			path.every((segment, index) => {
+				const found = entry.path?.[index];
+				return found !== undefined && segment === (typeof found === "object" ? found.key : found);
+			})
+		) {
+			return entry.message;
+		}
+	}
+	return undefined;
+}
+
+export function withoutField(messages: FieldMessages, name: string): FieldMessages {
+	if (!Object.hasOwn(messages, name)) {
+		return messages;
+	}
+	const next: Record<string, string> = Object.create(null);
+	for (const [key, message] of Object.entries(messages)) {
+		if (key !== name) {
+			next[key] = message;
+		}
+	}
+	return next;
+}
+
+export function literalChoices(input: SchemaAST.AST): readonly SchemaAST.LiteralValue[] | undefined {
+	const ast = SchemaAST.toEncoded(input);
+	if (ast._tag !== "Union") {
+		return undefined;
+	}
+	const choices: SchemaAST.LiteralValue[] = [];
+	for (const member of ast.types) {
+		if (member._tag !== "Literal") {
+			return undefined;
+		}
+		choices.push(member.literal);
+	}
+	return choices;
+}
+
+export function messageAt(messages: FieldMessages, name: string): string | undefined {
+	return Object.hasOwn(messages, name) ? messages[name] : undefined;
+}
+
+export function schemaFeedback<A, E>(decoded: Atom.Atom<AsyncResult.AsyncResult<Result.Result<A, SchemaIssue.Issue>, E>>) {
+	const messages = Atom.map(decoded, (result) =>
+		Option.match(AsyncResult.value(result), {
+			onNone: () => noMessages,
+			onSome: (value) => (Result.isFailure(value) ? messagesByField(value.failure) : noMessages),
+		}),
+	);
+	return {
+		at: (path: readonly PropertyKey[]) =>
+			Atom.map(decoded, (result): string | undefined => {
+				if (result.waiting) {
+					return undefined;
+				}
+				return Option.match(AsyncResult.value(result), {
+					onNone: () => undefined,
+					onSome: (value) => (Result.isFailure(value) ? messageAtPath(value.failure, path) : undefined),
+				});
+			}),
+		field: Atom.family((name: string) => Atom.map(messages, (value) => messageAt(value, name))),
+	};
+}

package/src/paths.ts

@@ -0,0 +1,63 @@
+import { Equal } from "effect";
+import type { Path } from "./shape.ts";
+
+type Key = (element: unknown) => PropertyKey;
+export type KeySelectors = ReadonlyMap<string, Key>;
+
+export interface PathMessage {
+	readonly message: string;
+	readonly path: Path;
+}
+
+export function keySelector(selector: unknown): Key;
+export function keySelector(selector: unknown): unknown {
+	return selector;
+}
+
+export function asPath(path: string | Path): Path {
+	return typeof path === "string" ? [path] : path;
+}
+
+function lookup(value: unknown, path: readonly PropertyKey[]): { readonly value: unknown } | undefined {
+	let current = value;
+	for (const [index, segment] of path.entries()) {
+		if (typeof current !== "object" || current === null) {
+			return undefined;
+		}
+		if (!Object.hasOwn(current, segment)) {
+			return index === path.length - 1 && !Array.isArray(current) ? { value: undefined } : undefined;
+		}
+		current = Reflect.get(current, segment);
+	}
+	return { value: current };
+}
+
+function uniqueIndex(values: readonly unknown[], key: PropertyKey, select: Key): number | undefined {
+	const matches = values.flatMap((value, index) => (select(value) === key ? [index] : []));
+	return matches.length === 1 ? matches[0] : undefined;
+}
+
+export function retainedPath(path: Path, previous: unknown, current: unknown, keys: KeySelectors): Path | undefined {
+	const select = keys.get(path[0]);
+	let next = path;
+	if (select !== undefined && typeof path[1] === "number") {
+		const before = lookup(previous, [path[0]])?.value;
+		const after = lookup(current, [path[0]])?.value;
+		if (!(Array.isArray(before) && Array.isArray(after) && Object.hasOwn(before, path[1]))) {
+			return undefined;
+		}
+		const key = select(before[path[1]]);
+		const index = uniqueIndex(after, key, select);
+		if (index === undefined || uniqueIndex(before, key, select) !== path[1]) {
+			return undefined;
+		}
+		next = [path[0], index, ...path.slice(2)];
+	}
+	const before = lookup(previous, path);
+	const after = lookup(current, next);
+	return before !== undefined && after !== undefined && Equal.equals(before.value, after.value) ? next : undefined;
+}
+
+export function pathMessageAt(messages: readonly PathMessage[], path: readonly PropertyKey[]): string | undefined {
+	return messages.find((entry) => path.every((segment, index) => segment === entry.path[index]))?.message;
+}

package/src/persistence.ts

@@ -0,0 +1,107 @@
+import { Clock, Effect, Schema, SchemaParser } from "effect";
+import type { DraftSession } from "./draftSession.ts";
+
+export interface DraftStorage {
+	readonly getItem: (key: string) => string | null;
+	readonly removeItem: (key: string) => void;
+	readonly setItem: (key: string, value: string) => void;
+}
+
+export interface PersistedDraftConfig {
+	readonly key: string;
+	readonly maxAgeMs?: number;
+	readonly maxBytes?: number;
+	readonly session?: DraftSession | undefined;
+	readonly storage: () => DraftStorage;
+}
+
+export interface Persistence<TValues> {
+	readonly clear: () => void;
+	readonly read: () => { readonly baseline: TValues; readonly edited: readonly string[]; readonly values: TValues } | undefined;
+	readonly write: (baseline: TValues, values: TValues, edited: readonly string[]) => void;
+}
+
+export function persistence<TSchema extends Schema.Constraint>(schema: TSchema, config: PersistedDraftConfig): Persistence<TSchema["Encoded"]> {
+	const encoded = Schema.toEncoded(schema);
+	const StoredDraft = Schema.Struct({
+		baseline: Schema.Unknown,
+		edited: Schema.Array(Schema.String),
+		session: Schema.String,
+		updatedAt: Schema.Number,
+		values: Schema.Unknown,
+		version: Schema.Literal(1),
+	});
+	const valid = Schema.is(StoredDraft);
+	const decode = SchemaParser.decodeUnknownSync(encoded, { disableChecks: true });
+	const maxAgeMs = config.maxAgeMs ?? 7 * 24 * 60 * 60 * 1000;
+	const maxBytes = config.maxBytes ?? 256 * 1024;
+	function bytes(value: string) {
+		return new TextEncoder().encode(value).byteLength;
+	}
+	const storage = config.storage;
+	const session = config.session?.id ?? "";
+	function active() {
+		return config.session?.active !== false;
+	}
+	function attempt<A>(run: () => A, failed?: () => void): A | undefined {
+		try {
+			return run();
+		} catch {
+			failed?.();
+			return undefined;
+		}
+	}
+	function clear() {
+		attempt(() => storage().removeItem(config.key));
+	}
+	config.session?.track(config.key, clear);
+	return {
+		clear: () => {
+			if (active()) {
+				clear();
+			}
+		},
+		read: () =>
+			attempt(() => {
+				if (!active()) {
+					return undefined;
+				}
+				const raw = storage().getItem(config.key);
+				if (raw === null) {
+					return undefined;
+				}
+				const value: unknown = bytes(raw) <= maxBytes ? JSON.parse(raw) : undefined;
+				const now = Effect.runSync(Clock.currentTimeMillis);
+				if (
+					valid(value)
+					&& value.session === session
+					&& Number.isFinite(maxAgeMs)
+					&& Number.isFinite(maxBytes)
+					&& maxAgeMs > 0
+					&& maxBytes > 0
+					&& now - value.updatedAt <= maxAgeMs
+					&& value.updatedAt <= now
+				) {
+					return { baseline: decode(value.baseline), edited: value.edited, values: decode(value.values) };
+				}
+				clear();
+				return undefined;
+			}, clear),
+		write: (baseline, values, edited) => {
+			if (!active()) {
+				return;
+			}
+			attempt(() => {
+				const raw = JSON.stringify({ baseline, edited, session, updatedAt: Effect.runSync(Clock.currentTimeMillis), values, version: 1 });
+				const parsed: unknown = JSON.parse(raw);
+				if (!(maxAgeMs > 0 && Number.isFinite(maxAgeMs) && Number.isFinite(maxBytes) && bytes(raw) <= maxBytes && valid(parsed))) {
+					clear();
+					return;
+				}
+				decode(parsed.baseline);
+				decode(parsed.values);
+				storage().setItem(config.key, raw);
+			}, clear);
+		},
+	};
+}

package/src/refs.ts

@@ -0,0 +1,34 @@
+import { Equal, Hash } from "effect";
+import * as Atom from "effect/reactivity/Atom";
+import * as AtomRef from "effect/reactivity/AtomRef";
+
+export function fromRef<TValue>(ref: AtomRef.ReadonlyRef<TValue>): Atom.Atom<TValue> {
+	return Atom.readable((get) => {
+		get.addFinalizer(ref.subscribe((value) => get.setSelf(value)));
+		return ref.value;
+	});
+}
+
+// Native prop refs retain removed keys; form fields must observe their absence.
+export function propertyRef<TValue, TKey extends keyof TValue>(parent: AtomRef.AtomRef<TValue>, name: TKey): AtomRef.AtomRef<TValue[TKey]> {
+	const read = parent.map((value) => value[name]);
+	const write = parent.prop(name);
+	const ref: AtomRef.AtomRef<TValue[TKey]> = {
+		[AtomRef.TypeId]: AtomRef.TypeId,
+		[Equal.symbol]: (other) => Equal.equals(read, other),
+		[Hash.symbol]: () => Hash.hash(read),
+		key: read.key,
+		map: (transform) => read.map(transform),
+		prop: (key) => propertyRef(ref, key),
+		set: (value) => {
+			write.set(value);
+			return ref;
+		},
+		subscribe: (listener) => read.subscribe(listener),
+		update: (transform) => ref.set(transform(read.value)),
+		get value() {
+			return read.value;
+		},
+	};
+	return ref;
+}

package/src/shape.ts

@@ -0,0 +1,94 @@
+import { Data, type Duration, type Effect, type Schema, type Scope } from "effect";
+import type * as Atom from "effect/reactivity/Atom";
+import type * as AtomRef from "effect/reactivity/AtomRef";
+import type { AtomRegistry } from "effect/reactivity/AtomRegistry";
+import type { Reactivity } from "effect/reactivity/Reactivity";
+import type { FieldMessages } from "./messages.ts";
+import type { PersistedDraftConfig } from "./persistence.ts";
+
+export type Fields = Schema.Struct.Fields;
+
+export type Encoded<TFields extends Fields> = Schema.Struct.Encoded<TFields>;
+
+export type Decoded<TFields extends Fields> = Schema.Struct.Type<TFields>;
+
+export type Name<TFields extends Fields> = keyof Encoded<TFields> & string;
+
+export type Path<TName extends string = string> = readonly [TName, ...PropertyKey[]];
+
+export type ArrayKeys<TFields extends Fields> = {
+	readonly [TKey in Name<TFields>]?: NonNullable<Encoded<TFields>[TKey]> extends readonly (infer TElement)[]
+		? (element: TElement) => PropertyKey
+		: never;
+};
+
+export type Services<TFields extends Fields, R> = R | Schema.Struct.DecodingServices<TFields>;
+
+export class FieldFailure extends Data.TaggedError("FieldFailure")<{
+	readonly message: string;
+	readonly path: string;
+	readonly segments?: Path;
+}> {}
+
+export class Invalid extends Data.TaggedError("Invalid")<{
+	readonly messages: FieldMessages;
+}> {}
+
+export interface Submitter<TName extends string> {
+	readonly fail: (path: TName | Path<TName>, message: string) => Effect.Effect<never, FieldFailure>;
+}
+
+export type Checks<TFields extends Fields, R> = {
+	readonly [TKey in Name<TFields>]?: (value: Encoded<TFields>[TKey]) => Effect.Effect<string | undefined, never, R>;
+};
+
+export interface Config<TFields extends Fields, A, E, R, TRuntimeError> {
+	readonly arrayKeys?: ArrayKeys<TFields>;
+	readonly checks?: Checks<TFields, R>;
+	readonly debounce?: Duration.Input;
+	readonly initialValues: Encoded<TFields>;
+	readonly onSubmit: (
+		values: Decoded<TFields>,
+		submitter: Submitter<Name<TFields>>,
+		submitted: Encoded<TFields>,
+	) => Effect.Effect<A, E, R | Scope.Scope | AtomRegistry | Reactivity>;
+	readonly persistedDraft?: PersistedDraftConfig | undefined;
+	readonly runtime: Atom.AtomRuntime<Services<TFields, R>, TRuntimeError>;
+}
+
+export interface Form<TFields extends Fields, A, E, TRuntimeError> {
+	readonly blur: (name: Name<TFields>) => void;
+	readonly change: <TKey extends Name<TFields>>(name: TKey, value: Encoded<TFields>[TKey]) => void;
+	readonly choices: <TKey extends Name<TFields>>(name: TKey) => readonly Encoded<TFields>[TKey][] | undefined;
+	readonly dirty: Atom.Atom<boolean>;
+	readonly error: (name: Name<TFields>) => Atom.Atom<string | undefined>;
+	readonly errorAt: (path: Path<Name<TFields>>) => Atom.Atom<string | undefined>;
+	readonly field: <TKey extends Name<TFields>>(name: TKey) => AtomRef.AtomRef<Encoded<TFields>[TKey]>;
+	readonly receive: (values: Encoded<TFields>) => void;
+	readonly revert: () => void;
+	readonly submit: Atom.AtomResultFn<void, A, E | TRuntimeError | FieldFailure | Invalid>;
+	readonly submitting: Atom.Atom<boolean>;
+	readonly values: AtomRef.AtomRef<Encoded<TFields>>;
+}
+
+export type Holder = AtomRef.AtomRef<Readonly<Record<string, unknown>>>;
+
+export function holder(values: object): Holder;
+export function holder(values: object): unknown {
+	return values;
+}
+
+export function fieldOf<TValue>(ref: AtomRef.AtomRef<unknown>): AtomRef.AtomRef<TValue>;
+export function fieldOf(ref: AtomRef.AtomRef<unknown>): unknown {
+	return ref;
+}
+
+export function choicesOf<TValue>(choices: readonly unknown[] | undefined): readonly TValue[] | undefined;
+export function choicesOf(choices: readonly unknown[] | undefined): unknown {
+	return choices;
+}
+
+export function checkOf<R>(check: unknown): (value: unknown) => Effect.Effect<string | undefined, never, R>;
+export function checkOf(check: unknown): unknown {
+	return check;
+}

package/src/statusOf.ts

@@ -0,0 +1,70 @@
+import { Equal } from "effect";
+import * as Atom from "effect/reactivity/Atom";
+import * as AtomRef from "effect/reactivity/AtomRef";
+import type { FieldMessages } from "./messages.ts";
+import { asPath, type KeySelectors, type PathMessage, retainedPath } from "./paths.ts";
+import { fromRef } from "./refs.ts";
+import type { Path } from "./shape.ts";
+
+interface State {
+	readonly failures: readonly PathMessage[];
+	readonly submitted: boolean;
+	readonly touched: Readonly<Record<string, true>>;
+}
+
+export function statusOf() {
+	const state = AtomRef.make<State>({
+		failures: [],
+		submitted: false,
+		touched: {},
+	});
+	const paths = fromRef(state.prop("failures"));
+	return {
+		attempt: (): void => {
+			state.update((current) => ({
+				...current,
+				failures: [],
+				submitted: true,
+			}));
+		},
+		failures: Atom.map(paths, (entries): FieldMessages => {
+			const messages: Record<string, string> = Object.create(null);
+			for (const { path, message } of entries) {
+				if (!Object.hasOwn(messages, path[0])) {
+					messages[path[0]] = message;
+				}
+			}
+			return messages;
+		}),
+		note: (input: string | Path, message: string): void => {
+			const path = asPath(input);
+			state.update((current) => ({
+				...current,
+				failures: [...current.failures.filter((entry) => !Equal.equals(entry.path, path)), { message, path }],
+			}));
+		},
+		paths,
+		rebase: (previous: unknown, next: unknown, keys: KeySelectors): void => {
+			state.update((current) => ({
+				...current,
+				failures: current.failures.flatMap((entry) => {
+					const path = retainedPath(entry.path, previous, next, keys);
+					return path === undefined ? [] : [{ ...entry, path }];
+				}),
+			}));
+		},
+		submitted: fromRef(state.prop("submitted")),
+		touch: (name: string): void => {
+			state.update((current) =>
+				current.touched[name] === true && !current.failures.some((entry) => entry.path.length === 1 && entry.path[0] === name)
+					? current
+					: {
+							...current,
+							failures: current.failures.filter((entry) => entry.path.length !== 1 || entry.path[0] !== name),
+							touched: { ...current.touched, [name]: true },
+						},
+			);
+		},
+		touched: fromRef(state.prop("touched")),
+	};
+}

package/src/trackRejections.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { asPath, keySelector, retainedPath } from "./paths.ts";
+import { FieldFailure, type Holder } from "./shape.ts";
+import type { statusOf } from "./statusOf.ts";
+
+export function trackRejections(values: Holder, selectors: Readonly<Record<string, unknown>> | undefined, status: ReturnType<typeof statusOf>) {
+	const keys = new Map(Object.entries(selectors ?? {}).map(([name, select]) => [name, keySelector(select)]));
+	let previous = values.value;
+	values.subscribe((next) => {
+		status.rebase(previous, next, keys);
+		previous = next;
+	});
+	return (submitted: unknown) =>
+		(cause: unknown): Effect.Effect<void> =>
+			Effect.sync(() => {
+				if (cause instanceof FieldFailure) {
+					const path = retainedPath(cause.segments ?? asPath(cause.path), submitted, values.value, keys);
+					if (path !== undefined) {
+						status.note(path, cause.message);
+					}
+				}
+			});
+}