@valancex/common 0.12.0 → 0.14.0

package/dist/form.js

@@ -0,0 +1,388 @@
+// Forms from the schema (direction Bet 11). One description of valid: the schema the submitted command takes. A form reads it once for what a screen needs (a field's name, kind, title, constraints), keeps
+// what the person typed as text, and decides from the same schema what is wrong and when to say so. It is a model, not a primitive: the fields are drawn with the ordinary `textfield`, `checkbox` and
+// `radiogroup`, and the state is the application's own (a field of its state), so the command that submits reads every draft.
+//
+//   const Signup = Schema.Struct({ name: Schema.String.pipe(Schema.minLength(2)).annotations({ title: "Name", message: () => "Enter at least 2 characters" }), … });
+//   const signup = Form.make(Signup);
+//   defineApp({ state: { signup: signup.field() }, derived: (derive) => ({ form: signup.view(derive, (s) => s.signup) }), commands: (command) => signup.commands(command, { … }), … });
+//
+// What it keeps for each field: the text typed (`value`), whether the person has left the field (`touched`), and the message a server gave it (`remote`). `dirty` and the message are worked out. An error is
+// shown for a field when it is wrong and the person has left the field once or tried to submit (stricter than Angular's dirty-or-touched and Phoenix's used-input, so the first keystroke is not an error); once
+// shown it follows the typing. A failed submit touches every field. Tier 1: the defaults are the whole interface; the options (`initial`, `message`, `required`) are Tier 2.
+import { Either, Option, ParseResult, Schema, SchemaAST as AST } from "effect";
+import { FIELD, FORM } from "./index.js";
+/** A mistake in the schema a form is made from, said at the declaration and naming the field. */
+export class FormError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FormError";
+    }
+}
+/** The schema of a form's state: a struct with a named entry for each field (the model has no type for a record with free keys), so it can be a field of the application's state and be read in a template. */
+const stateSchemaOf = (fields) => Schema.Struct({
+    values: Schema.Struct(Object.fromEntries(fields.map((each) => [each.name, each.kind === "boolean" ? Schema.Boolean : Schema.String]))),
+    touched: Schema.Struct(Object.fromEntries(fields.map((each) => [each.name, Schema.optional(Schema.Literal(true))]))),
+    attempts: Schema.Number,
+    remote: Schema.Struct(Object.fromEntries(fields.map((each) => [each.name, Schema.optional(Schema.String)]))),
+});
+const FieldViewSchema = Schema.Struct({
+    name: Schema.String,
+    title: Schema.String,
+    kind: Schema.Literal("text", "password", "number", "boolean", "choice"),
+    input: Schema.String,
+    required: Schema.Boolean,
+    choices: Schema.Array(Schema.String),
+    value: Schema.String,
+    checked: Schema.Boolean,
+    invalid: Schema.Boolean,
+    error: Schema.String,
+    errorId: Schema.String,
+    touched: Schema.Boolean,
+    dirty: Schema.Boolean,
+});
+/** The type of `View`, for the derived value a template reads. */
+export const ViewSchema = Schema.Struct({
+    fields: Schema.Array(FieldViewSchema),
+    valid: Schema.Boolean,
+    message: Schema.String,
+    first: Schema.String,
+    submitted: Schema.Boolean,
+});
+export const fieldErrors = (errors) => ({ _tag: "FieldErrors", errors });
+// ---- describing a schema ----------------------------------------------------------------------------------------------------------------------------------------
+const SCHEMA_ID = AST.SchemaIdAnnotationId;
+/** The titles Effect gives a refinement or a keyword by itself: `minLength(2)`, `int`, `string`. An author's title is anything else. */
+const generated = (title) => /^\w+\(.*\)$/.test(title) || ["string", "number", "boolean", "int", "nonEmpty", "trimmed", "lowercased", "uppercased", "finite", "nonNaN"].includes(title);
+const titleOf = (node) => {
+    const given = node.annotations[AST.TitleAnnotationId];
+    return typeof given === "string" && !generated(given) ? given : undefined;
+};
+const unwrapOptional = (ast) => {
+    if (ast._tag !== "Union") {
+        return ast;
+    }
+    const rest = ast.types.filter((each) => each._tag !== "UndefinedKeyword");
+    return rest.length === 1 ? rest[0] : ast;
+};
+/** The encoded base of a type (what is typed) and its decoded base, the refinements met on the way down, and the titles. */
+const baseOf = (given, side, refinements = []) => {
+    const ast = unwrapOptional(given);
+    if (ast._tag === "Refinement") {
+        refinements.push(ast);
+        return baseOf(ast.from, side, refinements);
+    }
+    if (ast._tag === "Transformation") {
+        return baseOf(side === "encoded" ? ast.from : ast.to, side, refinements);
+    }
+    if (ast._tag === "Suspend") {
+        return baseOf(ast.f(), side, refinements);
+    }
+    return { base: ast, refinements };
+};
+const literalsOf = (ast) => {
+    if (ast._tag === "Literal") {
+        return typeof ast.literal === "bigint" || ast.literal === null ? undefined : [ast.literal];
+    }
+    if (ast._tag === "Union") {
+        const each = ast.types.map(literalsOf);
+        return each.every((one) => one !== undefined) ? each.flat() : undefined;
+    }
+    return undefined;
+};
+const describeField = (path, ps) => {
+    const name = path.join(".");
+    const encoded = baseOf(ps.type, "encoded");
+    const decoded = baseOf(ps.type, "decoded");
+    const chain = [...encoded.refinements, ...decoded.refinements.filter((each) => !encoded.refinements.includes(each))];
+    const title = titleOf(ps) ?? titleOf(ps.type) ?? chain.map(titleOf).find((each) => each !== undefined);
+    if (title === undefined) {
+        throw new FormError(`Form: the field "${name}" has no title: give the schema \`.annotations({ title: "…" })\`, the label the person reads (and the name a screen reader says)`);
+    }
+    const optional = ps.isOptional || (ps.type._tag === "Union" && ps.type.types.some((each) => each._tag === "UndefinedKeyword"));
+    const constraints = Object.assign({}, ...chain.map((each) => each.annotations[AST.JSONSchemaAnnotationId] ?? {}));
+    const hasMessage = chain.some((each) => each.annotations[AST.MessageAnnotationId] !== undefined) || ps.type.annotations[AST.MessageAnnotationId] !== undefined;
+    const typed = encoded.base;
+    const literals = literalsOf(typed);
+    let kind;
+    let choices = [];
+    let redacted = false;
+    if (typed._tag === "StringKeyword" && decoded.base._tag === "Declaration") {
+        kind = "password";
+        redacted = true;
+    }
+    else if (typed._tag === "StringKeyword") {
+        kind = decoded.base._tag === "NumberKeyword" ? "number" : "text";
+    }
+    else if (typed._tag === "NumberKeyword") {
+        kind = "number";
+    }
+    else if (typed._tag === "BooleanKeyword" || (literals !== undefined && literals.length === 1 && typeof literals[0] === "boolean")) {
+        kind = "boolean";
+    }
+    else if (literals !== undefined && literals.every((each) => typeof each === "string")) {
+        kind = "choice";
+        choices = literals;
+    }
+    else if (typed._tag === "TypeLiteral" || typed._tag === "TupleType") {
+        throw new FormError(`Form: the field "${name}" is ${typed._tag === "TupleType" ? "a list" : "a record"} where a value is needed (lists of fields are not supported yet; flat and nested records are)`);
+    }
+    else {
+        throw new FormError(`Form: the field "${name}" has a type a form cannot draw (${typed._tag}): text, a number typed as text, a boolean, a closed set of strings, or a secret`);
+    }
+    return { name, path, title, kind, required: !optional && kind !== "boolean", choices, constraints, redacted, hasMessage };
+};
+/** The message the author wrote on a field's type (or on the field), by field name: what the field says whichever of its checks fails. */
+const fieldMessagesOf = (ast, path = []) => {
+    const found = new Map();
+    const record = baseOf(ast, "decoded").base;
+    if (record._tag !== "TypeLiteral") {
+        return found;
+    }
+    for (const ps of record.propertySignatures) {
+        if (typeof ps.name !== "string") {
+            continue;
+        }
+        const here = [...path, ps.name];
+        const inner = baseOf(ps.type, "encoded").base;
+        if (inner._tag === "TypeLiteral") {
+            fieldMessagesOf(inner, here).forEach((value, key) => found.set(key, value));
+            continue;
+        }
+        const said = ps.annotations[AST.MessageAnnotationId] ?? unwrapOptional(ps.type).annotations[AST.MessageAnnotationId];
+        if (typeof said === "function") {
+            found.set(here.join("."), said);
+        }
+    }
+    return found;
+};
+const describe = (ast, path = []) => {
+    const { base } = baseOf(ast, "decoded");
+    const record = base._tag === "TypeLiteral" ? base : baseOf(ast, "encoded").base;
+    if (record._tag !== "TypeLiteral") {
+        throw new FormError("Form: a form is made from a struct: `Schema.Struct({ … })`");
+    }
+    return record.propertySignatures.flatMap((ps) => {
+        if (typeof ps.name !== "string") {
+            return [];
+        }
+        const here = [...path, ps.name];
+        const inner = baseOf(ps.type, "encoded").base;
+        return inner._tag === "TypeLiteral" ? describe(inner, here) : [describeField(here, ps)];
+    });
+};
+const leaves = (issue, path, spoken = false) => {
+    switch (issue._tag) {
+        case "Pointer":
+            return leaves(issue.issue, [...path, ...(Array.isArray(issue.path) ? issue.path : [issue.path]).map(String)], spoken);
+        case "Composite":
+            return (Array.isArray(issue.issues) ? issue.issues : [issue.issues]).flatMap((each) => leaves(each, path, spoken));
+        case "Refinement":
+            // A rule over a whole struct reports at the paths it names (a Pointer inside): those are the leaves, not the rule.
+            if (issue.kind === "From") {
+                return leaves(issue.issue, path, spoken);
+            }
+            return issue.issue._tag === "Pointer" || issue.issue._tag === "Composite" ? leaves(issue.issue, path, true) : [{ path, issue, spoken }];
+        case "Transformation":
+            return leaves(issue.issue, path, spoken);
+        default:
+            return [{ path, issue, spoken }];
+    }
+};
+const codeOf = (issue) => {
+    const ast = "ast" in issue ? issue.ast : undefined;
+    const id = ast?.annotations[SCHEMA_ID];
+    const params = ast?.annotations[AST.JSONSchemaAnnotationId] ?? {};
+    return { code: typeof id === "symbol" ? (id.description ?? "").replace(/^effect\/SchemaId\//, "") : issue._tag, params };
+};
+const summary = (descriptor) => {
+    const { minLength, maxLength, minimum, maximum } = descriptor.constraints;
+    if (descriptor.kind === "choice") {
+        return `Choose one of: ${descriptor.choices.join(", ")}`;
+    }
+    if (minimum !== undefined && maximum !== undefined) {
+        return `Enter a number from ${minimum} to ${maximum}`;
+    }
+    if (minLength !== undefined) {
+        return `Enter at least ${minLength} characters`;
+    }
+    if (maxLength !== undefined) {
+        return `Enter at most ${maxLength} characters`;
+    }
+    return descriptor.kind === "boolean" ? "This must be checked" : "Enter a valid value";
+};
+// ---- making a form ----------------------------------------------------------------------------------------------------------------------------------------------------
+const hash = (text) => {
+    let value = 5381;
+    for (let at = 0; at < text.length; at += 1) {
+        value = ((value << 5) + value + text.charCodeAt(at)) >>> 0;
+    }
+    return value.toString(36);
+};
+const setIn = (target, path, value) => {
+    let at = target;
+    for (const step of path.slice(0, -1)) {
+        at = (at[step] ??= {});
+    }
+    at[path[path.length - 1]] = value;
+};
+export function make(schema, options = {}) {
+    const fields = describe(schema.ast);
+    const byName = new Map(fields.map((each) => [each.name, each]));
+    const fieldMessages = fieldMessagesOf(schema.ast);
+    const warnings = fields
+        .filter((each) => !each.hasMessage && Object.keys(each.constraints).length > 0)
+        .map((each) => `${each.name}: its constraints (${Object.keys(each.constraints).join(", ")}) have no message of their own: add \`message\` to the schema, or a \`message\` function to the form's options`);
+    const stateSchema = stateSchemaOf(fields);
+    const given = (options.initial ?? {});
+    const valueOf = (descriptor) => {
+        const at = descriptor.path.reduce((value, step) => (typeof value === "object" && value !== null ? value[step] : undefined), given);
+        return typeof at === "boolean" ? at : at === undefined ? (descriptor.kind === "boolean" ? false : "") : String(at);
+    };
+    const initial = { values: Object.fromEntries(fields.map((each) => [each.name, valueOf(each)])), touched: {}, attempts: 0, remote: {} };
+    const version = hash(fields.map((each) => `${each.name}:${each.kind}`).join("|"));
+    const known = (name) => {
+        const found = byName.get(name);
+        if (found === undefined) {
+            throw new FormError(`Form: there is no field "${name}" (the fields: ${fields.map((each) => each.name).join(", ")})`);
+        }
+        return found;
+    };
+    /** What the schema says is wrong with what is typed: a message for each field (and `""` for the form as a whole), the first the schema gives. */
+    const problems = (state) => {
+        const encoded = {};
+        for (const each of fields) {
+            const value = state.values[each.name];
+            if (typeof value === "string" && value === "" && !each.required) {
+                continue;
+            }
+            if (each.kind === "choice" && value === "") {
+                continue;
+            }
+            setIn(encoded, each.path, value);
+        }
+        const result = Schema.decodeUnknownEither(schema, { errors: "all", onExcessProperty: "ignore" })(encoded);
+        if (Either.isRight(result)) {
+            return { value: result.right, errors: new Map() };
+        }
+        const errors = new Map();
+        for (const { path, issue, spoken } of leaves(result.left.issue, [])) {
+            const name = path.join(".");
+            if (errors.has(name)) {
+                continue;
+            }
+            const descriptor = byName.get(name);
+            const { code, params } = codeOf(issue);
+            const own = ("ast" in issue && issue.ast.annotations[AST.MessageAnnotationId] !== undefined) ||
+                (spoken && "message" in issue && (typeof issue.message === "string" || (Option.isOption(issue.message) && Option.isSome(issue.message))));
+            const ofField = fieldMessages.get(name);
+            const said = own || ofField === undefined || issue._tag === "Missing" ? undefined : ofField(issue);
+            const fromField = typeof said === "string" ? said : typeof said === "object" && said !== null && "message" in said ? String(said.message) : undefined;
+            // The author's message on the check, else on the field (it speaks for every check of the field), else "Required", the application's words, the schema's own words.
+            const message = (own ? ParseResult.TreeFormatter.formatIssueSync(issue) : undefined) ??
+                fromField ??
+                (issue._tag === "Missing" ? "Required" : undefined) ??
+                options.message?.({ path, code, params, actual: descriptor?.redacted === true ? undefined : issue.actual }) ??
+                (descriptor === undefined ? ParseResult.TreeFormatter.formatIssueSync(issue) : summary(descriptor));
+            errors.set(name, message);
+        }
+        return { errors };
+    };
+    const touchedAll = (state) => ({ ...state, attempts: state.attempts + 1, touched: Object.fromEntries(fields.map((each) => [each.name, true])) });
+    const view = ((state, from) => {
+        if (typeof state === "function") {
+            return state(ViewSchema, (application) => view(from(application)));
+        }
+        const found = problems(state).errors;
+        const shown = (name) => state.remote[name] ?? (state.touched[name] === true || state.attempts > 0 ? (found.get(name) ?? "") : "");
+        const views = fields.map((each) => {
+            const value = state.values[each.name];
+            const error = shown(each.name);
+            return {
+                name: each.name,
+                title: each.title,
+                kind: each.kind,
+                input: each.kind === "password" ? "password" : "text",
+                required: each.required,
+                choices: each.choices,
+                value: typeof value === "string" ? value : "",
+                checked: value === true,
+                invalid: error !== "",
+                error,
+                errorId: `${each.name.replace(/\./g, "-")}-error`,
+                touched: state.touched[each.name] === true,
+                dirty: value !== initial.values[each.name],
+            };
+        });
+        const count = views.filter((each) => each.invalid).length;
+        return {
+            fields: views,
+            valid: found.size === 0 && Object.keys(state.remote).length === 0,
+            message: state.attempts > 0 && count > 0 ? `${count} ${count === 1 ? "field needs" : "fields need"} attention` : "",
+            first: views.find((each) => each.invalid)?.name ?? "",
+            submitted: state.attempts > 0,
+        };
+    });
+    const without = (record, name) => Object.fromEntries(Object.entries(record).filter(([key]) => key !== name));
+    const form = {
+        fields,
+        initial,
+        standard: Schema.standardSchemaV1(schema),
+        warnings,
+        field: () => ({ [FIELD]: true, [FORM]: true, schema: stateSchema, initial }),
+        view,
+        edit: (state, name, value) => {
+            known(name);
+            return { ...state, values: { ...state.values, [name]: value }, remote: without(state.remote, name) };
+        },
+        check: (state, name, value) => {
+            known(name);
+            return { ...state, values: { ...state.values, [name]: value }, touched: { ...state.touched, [name]: true }, remote: without(state.remote, name) };
+        },
+        blur: (state, name) => {
+            known(name);
+            return { ...state, touched: { ...state.touched, [name]: true } };
+        },
+        submit: (state) => {
+            const attempted = touchedAll(state);
+            const { value, errors } = problems(attempted);
+            return value !== undefined && Object.keys(state.remote).length === 0 && errors.size === 0 ? { ok: true, value, state: attempted } : { ok: false, state: attempted };
+        },
+        reject: (state, { errors }) => {
+            for (const name of Object.keys(errors)) {
+                known(name);
+            }
+            return {
+                ...state,
+                attempts: state.attempts + 1,
+                touched: { ...state.touched, ...Object.fromEntries(Object.keys(errors).map((name) => [name, true])) },
+                remote: { ...state.remote, ...errors },
+            };
+        },
+        draft: (state) => ({ version, values: Object.fromEntries(fields.filter((each) => !each.redacted).map((each) => [each.name, state.values[each.name]])) }),
+        restore: (draft) => draft.version !== version
+            ? initial
+            : { ...initial, values: { ...initial.values, ...Object.fromEntries(Object.entries(draft.values).filter(([name]) => byName.has(name) && !byName.get(name).redacted)) } },
+        commands: (command, given) => {
+            const field = given.field;
+            const how = {
+                get: given.get ?? ((state) => state[field]),
+                set: given.set ?? ((state, form) => ({ ...state, [field]: form })),
+                submitted: given.submitted,
+            };
+            if (given.field === undefined && (given.get === undefined || given.set === undefined)) {
+                throw new FormError('Form: say where the form is: `field: "signup"`, or `get` and `set`');
+            }
+            return {
+                edit: command(Schema.Struct({ name: Schema.String, value: Schema.String }), ({ name, value }, current) => how.set(current, form.edit(how.get(current), name, value))),
+                check: command(Schema.Struct({ name: Schema.String, value: Schema.Boolean }), ({ name, value }, current) => how.set(current, form.check(how.get(current), name, value))),
+                blur: command(Schema.Struct({ name: Schema.String }), ({ name }, current) => how.set(current, form.blur(how.get(current), name))),
+                submit: command((current) => {
+                    const result = form.submit(how.get(current));
+                    const next = how.set(current, result.state);
+                    return (result.ok ? how.submitted(next, result.value) : next);
+                }),
+            };
+        },
+    };
+    return form;
+}

package/dist/http.d.ts

@@ -1,5 +1,6 @@
 import * as Nexus from "@valancex/nexus";
 import { Effect, Schema } from "effect";
+import type { StoreClient } from "./store.js";
 import type { HttpError, Interceptor, Method, TransportRequest } from "./transport.js";
 export type { HttpError, Interceptor, Method, Transport, TransportRequest, TransportResponse } from "./transport.js";
 /** One request: where, what is sent, and what the answer must be. */
@@ -62,4 +63,6 @@ export declare const refreshOn401: (refresh: () => Promise<void>) => Interceptor
 export declare const retryGet: (times: number) => Interceptor;
 export declare const webHttp: (options: WebHttpOptions) => HttpClient;
 /** The platform for a web page: the `Http` capability, made from `api.base`. Merged with the application's own by `Web.run`. */
-export declare const webPlatform: (options: WebHttpOptions) => Nexus.Application.Platform;
+export declare const webPlatform: (options: WebHttpOptions & {
+    readonly store?: StoreClient;
+}) => Nexus.Application.Platform;

package/dist/http.js

@@ -13,6 +13,8 @@
 // bounded in time and size, and its response is *decoded by a Schema* before it can reach state. A failure says what kind it was and never what it carried.
 import * as Nexus from "@valancex/nexus";
 import { Effect, FiberRef, Schema } from "effect";
+import { Open, webOpen } from "./open.js";
+import { Store } from "./store.js";
 /** The capability: ask for it in a command (`Http.request`), and the platform says whether it has one. */
 export const Http = Nexus.Capability.define("valance/http");
 /** Makes a request through the platform's client. Requires the `Http` capability. */
@@ -185,4 +187,8 @@ export const webHttp = (options) => {
     };
 };
 /** The platform for a web page: the `Http` capability, made from `api.base`. Merged with the application's own by `Web.run`. */
-export const webPlatform = (options) => Nexus.Capability.EnvironmentLive(new Map([[Http.id, { _tag: "Available", implementation: webHttp(options) }]]));
+export const webPlatform = (options) => Nexus.Capability.EnvironmentLive(new Map([
+    [Http.id, { _tag: "Available", implementation: webHttp(options) }],
+    [Open.id, { _tag: "Available", implementation: webOpen() }],
+    ...(options.store === undefined ? [] : [[Store.id, { _tag: "Available", implementation: options.store }]]),
+]));