@valancex/common 0.13.0 → 0.15.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/index.d.ts

@@ -21,6 +21,8 @@ export type Appearance = ColorScheme | "system";
 /** Window size classes, the ones Material Design and iOS size classes agree on closely enough to design for. */
 export type Viewport = "compact" | "medium" | "expanded";
 export declare const FIELD: unique symbol;
+/** The brand of a state field that holds a form (`Form.field()`): the application then takes the person to the first field in error after a failed submit, with nothing written. */
+export declare const FORM: unique symbol;
 /** A state field: its type and its default, declared together. */
 export interface Field<A = unknown> {
     readonly [FIELD]: true;
@@ -68,27 +70,111 @@ export interface Component {
     readonly [COMPONENT]: true;
     readonly template: Template;
     /** Present when the component declares its props (an omitted side of a declared interface is none). Absent: the contract is inferred from the template and its uses. */
-    readonly props?: Readonly<Record<string, Schema.Schema<any, any, never>>>;
+    readonly props?: Readonly<Record<string, PropDeclaration>>;
     readonly events?: Readonly<Record<string, Schema.Schema<any, any, never>>>;
+    /** The prop that is the component's accessible name, when its template passes the name of whoever uses it through to a control (see `Contract.name`). */
+    readonly name?: string;
+    /** The state and commands of one occurrence of the component, when it has any (see `unit`). */
+    readonly unit?: Valance.Unit;
 }
+export declare const SNIPPET: unique symbol;
+/** A prop that is a piece of template: what an occurrence writes between its tags (`children`), or as a `{#snippet}` of that name among them. */
+export interface SnippetDeclaration {
+    readonly [SNIPPET]: true;
+    /** The types of the snippet's parameters, in order; `{@render name(a, b)}` passes exactly these. */
+    readonly params: ReadonlyArray<Schema.Schema<any, any, never>>;
+    /** Whether an occurrence may leave it out. Rendering it then needs `{#if has(name)}` around the render (`possibly-absent-snippet`). */
+    readonly isOptional: boolean;
+    /** The same snippet, which an occurrence may leave out: `snippet(Item).optional()`. */
+    optional(): SnippetDeclaration;
+}
+/**
+ * Declares a prop whose value is a snippet, with the types of its parameters: `children: snippet()` is the content written between the component's tags; `row: snippet(Item, Schema.Number)` is a
+ * `{#snippet row(item, index)}` an occurrence passes and the template renders with `{@render row(item, index)}`. The prop named `children` is reserved for the content between the tags and takes no
+ * parameters. A snippet is not data: it has no default, is not a field of a record or an event's payload, and is declared on a component that has a template. `snippet(...).optional()` is one an occurrence may leave out (an absent one draws nothing), and `children: snippet().optional()` is content an occurrence may leave out.
+ */
+export declare const snippet: (...params: ReadonlyArray<Schema.Schema<any, any, never>>) => SnippetDeclaration;
+/** Whether a declaration is a snippet's. */
+export declare const isSnippet: (value: unknown) => value is SnippetDeclaration;
+/** A prop is declared by its schema, by `field(schema, default)` when an occurrence that leaves it out should get a value, or by `snippet(…)` when it is a piece of template. */
+export type PropDeclaration = Schema.Schema<any, any, never> | Field<any> | SnippetDeclaration;
+/** Whether a prop is declared with a default. */
+export declare const isFormField: (value: unknown) => boolean;
+export declare const isField: (value: unknown) => value is Field;
 export interface Contract<P extends string, E extends string> {
     /**
-     * The inputs the template reads, each with its type. Optional when the schema admits `undefined`. A prop has no default: the model has none. With neither `props` nor `events` the contract is
-     * inferred; with either, the interface is exactly what is written (an omitted side is none).
+     * The inputs the template reads, each with its type. Optional when the schema admits `undefined`. `field(schema, default)` gives a prop a default: an occurrence of the component that leaves
+     * the prop out gets the default (for a component with a template; a primitive ignores it), and the prop may then be left out. A string-literal union (`Schema.Literal("a", "b")`) is a closed set:
+     * the model checks every literal written for it. With neither `props` nor `events` the contract is inferred; with either, the interface is exactly what is written (an omitted side is none).
      */
     readonly props?: {
-        readonly [K in P]: Schema.Schema<any, any, never>;
+        readonly [K in P]: PropDeclaration;
     };
     /** The events the template raises, each with its payload's schema; `Schema.Void` is no payload. */
     readonly events?: {
         readonly [K in E]: Schema.Schema<any, any, never>;
     };
+    /**
+     * The prop that is the component's accessible name: a component whose template draws a control and takes its name from whoever uses it (a labelled checkbox of the design system) says which
+     * prop that is, and the toolchain holds both sides to it. The prop must be a string every use writes (the model reports a use that omits it, where it is written), and the template must read it;
+     * a control in the template that has no name of its own (no `label`, not inside a `<label>`) is then not reported by `unnamed-control`, because the name arrives from the use.
+     */
+    readonly name?: P;
+    /**
+     * State that belongs to one occurrence of the component, such as whether a disclosure is open or which tab is chosen: `unit({ state, commands })`. The template reads its fields and runs its commands
+     * by name, like any others; the application never sees them. A component with a unit states its interface (`props` and `events`, empty if it has none).
+     */
+    readonly unit?: Valance.Unit;
 }
 /**
  * Defines a component: its template and an optional contract. Register it once, in `defineApp`'s `components`; the templates that write its tag use it, and nothing about its interface is
  * written again there. Where the toolchain has generated the template's type, a contract that disagrees with the template's keys is a compile-time error.
  */
 export declare function component<P extends string = string, E extends string = string>(template: Template<P, E>, contract?: Contract<NoInfer<P>, NoInfer<E>>): Component;
+/** What a unit's commands change: some of its fields. */
+type Changes<S> = Partial<S>;
+/** One command of a unit: a function of the state as the person saw it that returns the fields it changes, or the same with parameters and the events it announces. */
+export type UnitCommandSpec<S, P extends Schema.Struct.Fields = Schema.Struct.Fields> = ((state: S) => Changes<S>) | {
+    /** The command's parameters, in order: `{ n: Schema.Number }`. Each is a parameter of the command in the model. */
+    readonly params?: P;
+    readonly run: (state: S, args: Schema.Struct.Type<P>) => Changes<S>;
+    /** Events of the component the command announces to its caller, each with the payload it carries, worked out from the state the command leaves: `{ change: (next) => next.at }`. */
+    readonly raises?: Readonly<Record<string, (next: S, args: Schema.Struct.Type<P>) => unknown>>;
+};
+/** A command of a unit as `unit` takes it: any parameters (they are typed where the command is written, with `unitCommand`). */
+type UnitCommandInput<S> = ((state: S) => Changes<S>) | {
+    readonly params?: Schema.Struct.Fields;
+    readonly run: (state: S, args: any) => Changes<S>;
+    readonly raises?: Readonly<Record<string, (next: S, args: any) => unknown>>;
+};
+/** A command with parameters, typed: the parameters' types reach `run` and `raises`. */
+export declare const unitCommand: <S, P extends Schema.Struct.Fields>(spec: {
+    readonly params: P;
+    readonly run: (state: S, args: Schema.Struct.Type<P>) => Changes<S>;
+    readonly raises?: Readonly<Record<string, (next: S, args: Schema.Struct.Type<P>) => unknown>>;
+}) => UnitCommandSpec<S, P>;
+/**
+ * Declares the state and commands of one occurrence of a component (Tier 2; a component with no unit needs none of it). The state is typed with defaults, as application state is; a command is a
+ * pure function of the state as the person saw it that returns the fields it changes:
+ *
+ *   export default component(template, {
+ *     props: { label: Schema.String },
+ *     events: {},
+ *     unit: unit({ state: { open: field(Schema.Boolean, false) }, commands: { toggle: (state) => ({ open: !state.open }) } }),
+ *   });
+ *
+ * The template reads `open` and runs `toggle()`; the application holds neither. The state belongs to the occurrence: it follows its row when a keyed list is re-sorted, and starts again from the defaults
+ * when the occurrence leaves the page and returns. State that must outlive that (or that another part of the application reads) is application state, not a unit. A field named in `controllable` is
+ * owned by the caller when it writes a prop of the same name (the prop must be declared, optional and of the same type): the prop is then the value, the unit's change to it is not applied, and
+ * `raises` tells the caller what the person chose.
+ */
+export declare const unit: <F extends Fields>(definition: {
+    readonly state: F;
+    readonly commands: {
+        readonly [name: string]: UnitCommandInput<StateOf<F>>;
+    };
+    readonly controllable?: ReadonlyArray<Extract<keyof F, string>>;
+}) => Valance.Unit<StateOf<F>>;
 /**
  * What the document's title is made of. `page` is the page's own part (default: its title, from the Markdown front matter), `app` the application's name (default: the site's name), `status` what is
  * going on right now and is not part of any page (an unread count, "Saving…"): it is written first, in parentheses. The project's format in \`valance.json\` (`"title": "{page} · {site}"`) puts them
@@ -122,6 +208,12 @@ export interface AppDefinition<S extends StateInput = {}> {
     readonly components?: ReadonlyArray<Component>;
     /** Built-in components (`heading`, `runs`, …) you replace with your own template of the same name. */
     readonly override?: ReadonlyArray<Component>;
+    /**
+     * Which component a tag means when two share a name (Tier 2: nothing to write until there is a collision). A library's component has the qualified id `package/name` (`acme-ui/disclosure`); two
+     * libraries that both have a `disclosure`, or a library component named like a built-in, are a compile error that names both ids, and `resolve: { disclosure: "acme-ui/disclosure" }` says which one the
+     * tag is. The others are left out of the program, and a library template that writes the tag gets the one chosen. A built-in is replaced by the chosen library component, as `override` would.
+     */
+    readonly resolve?: Readonly<Record<string, string>>;
     /**
      * Application state beyond the page: `{ theme: field(Schema.Literal("light", "dark"), "light") }`. Its fields become names a layout can read. A hand-built `{ schema, initial }` is also accepted, for
      * hydration and shared schemas.
@@ -201,3 +293,4 @@ export declare const derivedOf: (author: {
     readonly derived?: AppDefinition<any>["derived"];
 } | undefined) => Readonly<Record<string, Derived<any>>>;
 export declare const defineApp: <S extends StateInput = {}>(definition: AppDefinition<S>) => DefinedApp;
+export * as Form from "./form.js";

package/dist/index.js

@@ -1,5 +1,9 @@
+import { UNIT } from "@valancex/valance";
+import { Schema } from "effect";
 // ---- state -------------------------------------------------------------------------------------------------------------------------------------------------
 export const FIELD = Symbol.for("valancex.common.field");
+/** The brand of a state field that holds a form (`Form.field()`): the application then takes the person to the first field in error after a failed submit, with nothing written. */
+export const FORM = Symbol.for("valancex.common.form");
 /**
  * Declares one field of the application's state with its type and its default in one place. The framework builds the state's schema and its initial value from the fields; the default is
  * checked against the type (by TypeScript, and again when the application is built).
@@ -8,6 +12,24 @@ export const DERIVED = Symbol.for("valancex.common.derived");
 const derive = (schema, from) => ({ [DERIVED]: true, schema: schema, from });
 export const field = (schema, initial) => ({ [FIELD]: true, schema: schema, initial });
 export const COMPONENT = Symbol.for("valancex.common.component");
+export const SNIPPET = Symbol.for("valancex.common.snippet");
+/**
+ * Declares a prop whose value is a snippet, with the types of its parameters: `children: snippet()` is the content written between the component's tags; `row: snippet(Item, Schema.Number)` is a
+ * `{#snippet row(item, index)}` an occurrence passes and the template renders with `{@render row(item, index)}`. The prop named `children` is reserved for the content between the tags and takes no
+ * parameters. A snippet is not data: it has no default, is not a field of a record or an event's payload, and is declared on a component that has a template. `snippet(...).optional()` is one an occurrence may leave out (an absent one draws nothing), and `children: snippet().optional()` is content an occurrence may leave out.
+ */
+export const snippet = (...params) => declare(params, false);
+const declare = (params, isOptional) => ({
+    [SNIPPET]: true,
+    params,
+    isOptional,
+    optional: () => declare(params, true),
+});
+/** Whether a declaration is a snippet's. */
+export const isSnippet = (value) => typeof value === "object" && value !== null && SNIPPET in value;
+/** Whether a prop is declared with a default. */
+export const isFormField = (value) => typeof value === "object" && value !== null && FORM in value;
+export const isField = (value) => typeof value === "object" && value !== null && FIELD in value;
 /**
  * Defines a component: its template and an optional contract. Register it once, in `defineApp`'s `components`; the templates that write its tag use it, and nothing about its interface is
  * written again there. Where the toolchain has generated the template's type, a contract that disagrees with the template's keys is a compile-time error.
@@ -18,11 +40,53 @@ export function component(template, contract = {}) {
         template,
         ...(contract.props === undefined ? {} : { props: contract.props }),
         ...(contract.events === undefined ? {} : { events: contract.events }),
+        ...(contract.name === undefined ? {} : { name: contract.name }),
+        ...(contract.unit === undefined ? {} : { unit: contract.unit }),
     };
 }
+/** A command with parameters, typed: the parameters' types reach `run` and `raises`. */
+export const unitCommand = (spec) => spec;
+/**
+ * Declares the state and commands of one occurrence of a component (Tier 2; a component with no unit needs none of it). The state is typed with defaults, as application state is; a command is a
+ * pure function of the state as the person saw it that returns the fields it changes:
+ *
+ *   export default component(template, {
+ *     props: { label: Schema.String },
+ *     events: {},
+ *     unit: unit({ state: { open: field(Schema.Boolean, false) }, commands: { toggle: (state) => ({ open: !state.open }) } }),
+ *   });
+ *
+ * The template reads `open` and runs `toggle()`; the application holds neither. The state belongs to the occurrence: it follows its row when a keyed list is re-sorted, and starts again from the defaults
+ * when the occurrence leaves the page and returns. State that must outlive that (or that another part of the application reads) is application state, not a unit. A field named in `controllable` is
+ * owned by the caller when it writes a prop of the same name (the prop must be declared, optional and of the same type): the prop is then the value, the unit's change to it is not applied, and
+ * `raises` tells the caller what the person chose.
+ */
+export const unit = (definition) => {
+    const entries = Object.entries(definition.state);
+    const fields = Object.fromEntries(entries.map(([name, each]) => [name, { schema: each.schema, initial: each.initial }]));
+    const schema = Schema.Struct(Object.fromEntries(entries.map(([name, each]) => [name, each.schema])));
+    return {
+        [UNIT]: true,
+        schema: schema,
+        fields,
+        controllable: definition.controllable ?? [],
+        commands: Object.fromEntries(Object.entries(definition.commands).map(([name, command]) => [
+            name,
+            typeof command === "function"
+                ? { run: command }
+                : {
+                    ...(command.params === undefined ? {} : { input: Schema.Struct(command.params) }),
+                    run: command.run,
+                    ...(command.raises === undefined ? {} : { raises: command.raises }),
+                },
+        ])),
+    };
+};
 /** The brand that says a value came from `defineApp`. */
 export const APP = Symbol.for("valancex.common");
 /** Declares the application's component tree, state and commands. It starts nothing; the framework runs it. */
 /** What `derived` makes, for the toolchain: the function is called with the one `derive`. */
 export const derivedOf = (author) => author?.derived?.(derive) ?? {};
 export const defineApp = (definition) => ({ ...definition, [APP]: true });
+// ---- forms ---------------------------------------------------------------------------------------------------------------------------------------------------
+export * as Form from "./form.js";

package/dist/internal.d.ts

@@ -11,3 +11,4 @@ export * from "./store.js";
 export * from "./open.js";
 export * from "./navigation.js";
 export * from "./platform.js";
+export { earlyHead, earlyShell, earlyShellLimit } from "./early.js";

package/dist/internal.js

@@ -13,3 +13,4 @@ export * from "./store.js";
 export * from "./open.js";
 export * from "./navigation.js";
 export * from "./platform.js";
+export { earlyHead, earlyShell, earlyShellLimit } from "./early.js";