@dou-ui/form-builder 0.0.0-stage → 0.1.0-alpha.0

package/dist/types/code/index.d.ts

@@ -0,0 +1,12 @@
+import type { FormBuilderExtension } from '../builder/extension';
+import CodeExpressionInput from './expression-input.vue';
+export { expressionCodeExtension } from './extension';
+export type { ExpressionCodeOptions, ExpressionFunctionInfo, ExpressionName } from './extension';
+export { formExpression } from './language';
+export { CodeExpressionInput };
+/**
+ * Writes the builder's expressions (formulas, checks, conditions as text)
+ * in `@dou-ui/code`'s code input: colored, with completions, parameter
+ * hints and problems underlined. Needs `@dou-ui/code` and its styles.
+ */
+export declare function codeExpressions(): FormBuilderExtension;

package/dist/types/code/language.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The form expression language for `@dou-ui/code`: `values` and its
+ * paths, strings, numbers, function calls and operators, colored as in
+ * the code editor.
+ */
+export declare const formExpression: import("@dou-ui/code").CodeLanguage<Record<string, never>>;

package/dist/types/collaboration/index.d.ts

@@ -0,0 +1,64 @@
+import { collaborationColors } from 'dou-ui';
+import * as Y from 'yjs';
+import type { FormDocument } from '../core/types';
+import type { FormBuilderExtension } from '../builder/extension';
+/** The part of an `Awareness` (`y-protocols/awareness`) the builder uses. */
+export interface AwarenessLike {
+    clientID: number;
+    getLocalState(): Record<string, unknown> | null;
+    setLocalStateField(field: string, value: unknown): void;
+    getStates(): Map<number, Record<string, unknown>>;
+    on(event: 'change', listener: (...args: unknown[]) => void): void;
+    off(event: 'change', listener: (...args: unknown[]) => void): void;
+}
+/** How the people editing together see each other. */
+export interface CollaborationUser {
+    name: string;
+    /** The color of this user's marks, any CSS color. Picked from the client id when left out. */
+    color?: string;
+}
+export interface CollaborationOptions {
+    /** Where the nodes live, e.g. `ydoc.getMap('nodes')`. */
+    nodes: Y.Map<unknown>;
+    /** Where the form's own settings live, e.g. `ydoc.getMap('settings')`; in the same `Y.Doc` as `nodes`. */
+    settings: Y.Map<unknown>;
+    /** Shares what each person has selected (`y-protocols/awareness`). */
+    awareness?: AwarenessLike;
+    /** This user, shown to the others. Needs `awareness`. */
+    user?: CollaborationUser;
+}
+/** What each person shares under the awareness field `formBuilder`. */
+export interface FormBuilderPresence {
+    selection: string[];
+}
+export { collaborationColors };
+/** Writes a form into empty maps, e.g. when a form so far saved as JSON starts being edited together. */
+export declare function fillMaps(maps: {
+    nodes: Y.Map<unknown>;
+    settings: Y.Map<unknown>;
+}, document: FormDocument): void;
+/**
+ * The form the maps hold. A node whose container is gone, e.g. one moved
+ * into a section while another person deleted the section, goes to the top
+ * of the form. So do containers two people moved into each other at once:
+ * the one with the smallest id goes to the top, the same for everyone.
+ * Both are listed in `lifted`.
+ */
+export declare function readMaps(maps: {
+    nodes: Y.Map<unknown>;
+    settings: Y.Map<unknown>;
+}): {
+    document: FormDocument;
+    lifted: string[];
+};
+/**
+ * Edit a form together through a Yjs document. Each node lives in `nodes`
+ * as its own `Y.Map`, each key on its own, with its container and an order
+ * key beside them; so two people changing different keys of one field both
+ * keep their change, and moving a node only writes that node. The form's
+ * settings live in `settings`. The builder's `v-model` only mirrors them:
+ * a form set through `v-model` from outside is not written back. Undo only
+ * takes back this user's own changes. With `awareness`, each person sees
+ * what the others have selected, marked in their colors.
+ */
+export declare function collaboration(options: CollaborationOptions): FormBuilderExtension;

package/dist/types/collaboration/order.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Order keys: strings that sort like the nodes they belong to. A key can
+ * always be made between two others, so moving or inserting a node only
+ * writes that node's key, never its neighbours'.
+ */
+/** A key after `a` and before `b`; either may be missing. Needs `a < b`. */
+export declare function keyBetween(a: string | null, b: string | null): string;
+/** `n` keys in order between `a` and `b`, kept short by splitting the range in halves. */
+export declare function keysBetween(a: string | null, b: string | null, n: number): string[];
+/**
+ * Which of `keys` (in their wanted order) can stay: the longest strictly
+ * increasing run. Missing keys (`null`) never stay. Returns the indexes.
+ */
+export declare function keptIndexes(keys: (string | null)[]): Set<number>;
+/**
+ * Order keys for items in their wanted order, given each one's current key
+ * (`null` when it has none). The longest run already in order keeps its
+ * keys; the others get fresh keys between their kept neighbours.
+ */
+export declare function orderKeys(keys: (string | null)[]): string[];

package/dist/types/core/check.d.ts

@@ -0,0 +1,68 @@
+import type { ExpressionProblem } from './expression';
+import type { FormDocument } from './types';
+import type { FormFieldType } from '../fields/define';
+export interface DocumentProblem {
+    code: 'version' | 'duplicate-id' | 'missing-name' | 'duplicate-name' | 'unknown-type' | 'misplaced-page' | 'not-a-page' | 'empty' | 'expression' | 'formula-cycle' | 'unknown-validator' | 'check-and-validator';
+    /** The node at fault; none for the document's own problems. */
+    nodeId?: string;
+    /**
+     * Where the problem is, as a path into the document, e.g.
+     * `nodes[1].children[0]` or `nodes[2].rules[0].check`; `version` for the
+     * version, and `''` for a problem of the whole.
+     */
+    path: string;
+    /** The property at fault, e.g. `visibleWhen`, for an expression. */
+    property?: string;
+    /** The id, name, type or expression source at fault, for the editor's message. */
+    text: string;
+    /** The expression's own problem, for `expression`. */
+    expression?: ExpressionProblem;
+    /** An English description, for logs. */
+    message: string;
+}
+export interface CheckDocumentOptions {
+    /** Field types besides the built-in ones, as given to the renderer. */
+    fields?: readonly FormFieldType<any>[];
+    /** Functions the expressions can call besides the built-in ones. */
+    functions?: readonly string[];
+    /**
+     * The names of the validators given to the renderer. Left out, a rule's
+     * `validator` is not checked against them.
+     */
+    validators?: readonly string[];
+}
+/**
+ * The problems of a document, for an editor to point at, before it is
+ * saved or rendered: ids used twice, fields without a name or sharing one,
+ * types nobody registered, pages outside tabs and steps, expressions that
+ * do not parse or read fields that are not there, formulas that read
+ * each other, and rules naming a validator nobody gave.
+ */
+export declare function checkDocument(document: FormDocument, options?: CheckDocumentOptions): DocumentProblem[];
+/**
+ * The document in the current version (`1`). Documents of an older
+ * version are upgraded step by step; there are none yet, so for now this
+ * only checks the version. A document without a version is read as
+ * version 1, as the renderer does. Throws for anything that is not a
+ * document and for a version it does not know.
+ */
+export declare function migrateDocument(document: unknown): FormDocument;
+/** A part of some data that is not shaped like a form document. */
+export interface DocumentShapeProblem {
+    /** Where, as a path into the data, e.g. `nodes[2].children[0].label`; `''` for the whole. */
+    path: string;
+    /** `type`: the value is of another kind; `required`: it is missing. */
+    code: 'type' | 'required';
+    /** What the value should be. */
+    expected: 'object' | 'array' | 'string' | 'number' | 'boolean' | 'span' | 'mark';
+    /** An English description, for logs. */
+    message: string;
+}
+/**
+ * Where some data, e.g. JSON pasted into an editor, is not shaped like a
+ * form document: a key holding the wrong kind of value, or a node without
+ * its `id`, `type` or `children`. Problems name the path to the value, so
+ * they can be found in the text. Run `checkDocument` on the result for
+ * the problems of a document that is shaped right.
+ */
+export declare function checkDocumentShape(data: unknown): DocumentShapeProblem[];

package/dist/types/core/document.d.ts

@@ -0,0 +1,36 @@
+import type { FormContainerNode, FormDocument, FormFieldNode, FormListNode, FormNode, FormPageNode, FormSectionNode, FormStepsNode, FormTabsNode } from './types';
+/** A document with nothing in it. */
+export declare function emptyDocument(): FormDocument;
+/** Warn once, for the whole page, about a document of a version this package does not know. */
+export declare function checkVersion(document: FormDocument): void;
+/** A short id that is unique enough within one document, e.g. `f-lz3k9a-1`. */
+export declare function createId(prefix?: string): string;
+export declare const isSection: (node: FormNode) => node is FormSectionNode;
+export declare const isTabs: (node: FormNode) => node is FormTabsNode;
+export declare const isSteps: (node: FormNode) => node is FormStepsNode;
+export declare const isPage: (node: FormNode) => node is FormPageNode;
+export declare const isList: (node: FormNode) => node is FormListNode;
+/** Whether a node holds other nodes: a section, tabs, steps, a page or a list. */
+export declare const isContainer: (node: FormNode) => node is FormContainerNode;
+/** Whether a node is a field, of a built-in or a registered type. */
+export declare const isField: (node: FormNode) => node is FormFieldNode;
+/** Every node in document order, containers before their children, the fields of list items included. */
+export declare function walkNodes(nodes: readonly FormNode[]): Generator<FormNode>;
+/**
+ * The nodes that write a value of their own, in document order: fields
+ * with a `name` and lists. Fields inside a list belong to its items, so
+ * they are not among them.
+ */
+export declare function valueNodes(nodes: readonly FormNode[]): (FormFieldNode | FormListNode)[];
+/** The fields that write a value, in document order, outside lists. */
+export declare function fieldNodes(document: FormDocument): FormFieldNode[];
+/** The node with this id, anywhere in the document. */
+export declare function findNode(document: FormDocument, id: string): FormNode | undefined;
+/** The value at a dotted path, or `undefined` when part of it is missing. */
+export declare function getPath(model: unknown, path: string): unknown;
+/** Write a value at a dotted path, creating the objects on the way. */
+export declare function setPath(model: Record<string, unknown>, path: string, value: unknown): void;
+/** Remove the value at a dotted path, if it is there. */
+export declare function unsetPath(model: Record<string, unknown>, path: string): void;
+/** A deep copy of plain data, so a default is never shared between forms. */
+export declare function cloneValue<T>(value: T): T;

package/dist/types/core/expression.d.ts

@@ -0,0 +1,175 @@
+/**
+ * A small expression language for form logic: show a field when another
+ * has some value, compute a total, check one date against another.
+ *
+ * Expressions come from stored form data, so they are parsed and run by
+ * this module and never handed to `eval` or `new Function`. They can read
+ * `values` (the whole form) and `value` (the field's own value), call the
+ * built-in functions and the ones the app registers, and nothing else.
+ *
+ *     values.type == 'laptop' && values.price > 5000
+ *     round(values.price * values.count, 2)
+ *     values.city in ['sh', 'bj'] ? 'east' : 'other'
+ */
+export type ExpressionErrorCode = 'unexpected-character' | 'unterminated-string' | 'unexpected-token' | 'unexpected-end' | 'unknown-name' | 'assignment' | 'too-deep' | 'too-long';
+/** Where and why an expression does not parse. `start` and `end` are offsets into the source. */
+export declare class ExpressionError extends Error {
+    readonly code: ExpressionErrorCode;
+    readonly start: number;
+    readonly end: number;
+    constructor(code: ExpressionErrorCode, message: string, start: number, end?: number);
+}
+/** The syntax tree of an expression. Each node keeps its place in the source. */
+export type ExpressionNode = {
+    kind: 'literal';
+    value: string | number | boolean | null;
+    start: number;
+    end: number;
+} | {
+    kind: 'list';
+    items: ExpressionNode[];
+    start: number;
+    end: number;
+} | {
+    kind: 'name';
+    name: 'values' | 'value' | 'item';
+    start: number;
+    end: number;
+} | {
+    kind: 'member';
+    object: ExpressionNode;
+    key: ExpressionNode;
+    start: number;
+    end: number;
+} | {
+    kind: 'call';
+    name: string;
+    args: ExpressionNode[];
+    start: number;
+    end: number;
+} | {
+    kind: 'unary';
+    operator: '!' | '-';
+    argument: ExpressionNode;
+    start: number;
+    end: number;
+} | {
+    kind: 'binary';
+    operator: BinaryOperator;
+    left: ExpressionNode;
+    right: ExpressionNode;
+    start: number;
+    end: number;
+} | {
+    kind: 'condition';
+    test: ExpressionNode;
+    whenTrue: ExpressionNode;
+    whenFalse: ExpressionNode;
+    start: number;
+    end: number;
+};
+export type BinaryOperator = '||' | '&&' | '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | '+' | '-' | '*' | '/' | '%';
+/** A function expressions can call. It gets the values of its arguments and should not change them. */
+export type FormFunction = (...args: any[]) => unknown;
+/** What an expression reads when it runs. */
+export interface ExpressionScope {
+    /** The whole form. Defaults to an empty one. */
+    values?: Record<string, unknown>;
+    /** The value of the field the expression belongs to. */
+    value?: unknown;
+    /** Inside a list, the item the field belongs to. */
+    item?: unknown;
+    /** Functions besides the built-in ones; one of the same name replaces the built-in function. */
+    functions?: Readonly<Record<string, FormFunction>>;
+}
+export interface CompiledExpression {
+    readonly source: string;
+    readonly ast: ExpressionNode;
+    /**
+     * The paths under `values` the expression reads, e.g. `['price', 'contact.phone']`.
+     * An empty string means it reads a key that is only known when it runs,
+     * so it may read anything.
+     */
+    readonly fields: readonly string[];
+    /** The paths under `item` it reads, like `fields` for `values`. */
+    readonly itemFields: readonly string[];
+    /** Whether it reads `value`. */
+    readonly readsValue: boolean;
+    /** The functions it calls. */
+    readonly calls: readonly string[];
+    /** Run it. A function that throws makes the result `null`. */
+    evaluate: (scope: ExpressionScope) => unknown;
+}
+/** Parse an expression. Throws an `ExpressionError` that says where it went wrong. */
+export declare function parseExpression(source: string): ExpressionNode;
+/** Whether a value counts as true: everything but `false`, `null`, `0`, `NaN`, `''` and `[]`. */
+export declare function truthy(value: unknown): boolean;
+/** Whether a value is empty: `null`, blank text, `[]` or `{}`. */
+export declare function isEmptyValue(value: unknown): boolean;
+/** Equal by value: lists and objects compare their items, `null` equals a missing value. */
+export declare function equalValues(a: unknown, b: unknown): boolean;
+/**
+ * The functions every expression can call:
+ *
+ * - `len(x)`: length of text, number of items or of keys; `0` for nothing.
+ * - `empty(x)`: whether `x` is `null`, blank text, `[]` or `{}`.
+ * - `number(x)`: `x` as a number, or `null` when it is not one.
+ * - `sum(list)`, `min(list)`, `max(list)`: over a list, or over the arguments;
+ *   `sum(list, 'key')` over one key of every item.
+ * - `round(x, digits?)`, `abs(x)`.
+ * - `today(offset?)`: today, or `offset` days from today, as `YYYY-MM-DD`.
+ * - `days(from, to)`: whole days from one date to the other.
+ * - `contains(list or text, x)`: like `x in list`.
+ */
+export declare const builtinFunctions: Readonly<Record<string, FormFunction>>;
+/**
+ * The `values` path a member chain reads, e.g. `contact.phone`, or
+ * `undefined` when the chain does not start at `values`. A key computed
+ * when it runs stops the path there: `values.rows[i].name` reads `rows`,
+ * and `values[key]` reads everything (`''`).
+ */
+export declare function pathOf(node: ExpressionNode, root?: 'values' | 'item'): string | undefined;
+/** The computed keys along a member chain, e.g. `i` in `values.rows[i]`. */
+export declare function computedKeys(node: ExpressionNode): ExpressionNode[];
+/**
+ * Parse an expression once and get a function that runs it. Results are
+ * cached by source text, so every field with the same expression shares
+ * one. Throws an `ExpressionError` when it does not parse.
+ */
+export declare function compileExpression(source: string): CompiledExpression;
+/**
+ * Like `compileExpression`, but warns once and gives `undefined` for an
+ * expression that does not parse, for code that renders whatever it is given.
+ */
+export declare function tryCompileExpression(source: string): CompiledExpression | undefined;
+/** Parse and run an expression in one go. */
+export declare function evaluateExpression(source: string, scope: ExpressionScope): unknown;
+export interface ExpressionProblem {
+    /** What is wrong; an editor shows its own words for each code. */
+    code: ExpressionErrorCode | 'unknown-field' | 'unknown-function';
+    /** An English description, for logs. */
+    message: string;
+    /** The source text at fault, e.g. the field path or function name, for the editor's message. */
+    text: string;
+    start: number;
+    end: number;
+}
+/**
+ * The problems of an expression, for an editor to point at: a syntax
+ * error, or a field or function that does not exist. `fields` are the
+ * names of the form's fields; a path inside one (`contact.phone` for a
+ * field `contact`) or around one (`contact` for `contact.phone`) counts.
+ */
+export interface CheckExpressionOptions {
+    /** The fields `values` can read; reading another is a problem. */
+    fields?: readonly string[];
+    /** The fields of a list item that `item` can read; an empty list where there is no item. */
+    itemFields?: readonly string[];
+    /** Functions besides the built-in ones. */
+    functions?: readonly string[];
+}
+export declare function checkExpression(source: string, options?: CheckExpressionOptions): ExpressionProblem[];
+/** Whether a read of `path` can see the field `name`: the same path, or one inside the other. */
+export declare function related(name: string, path: string): boolean;
+/** Today as `YYYY-MM-DD`, in local time. */
+export declare const formatToday: () => string;

package/dist/types/core/formulas.d.ts

@@ -0,0 +1,44 @@
+import type { CompiledExpression, FormFunction } from './expression';
+import type { FormDocument, FormFieldNode, FormListNode } from './types';
+export interface FormulaField {
+    name: string;
+    expression: CompiledExpression;
+}
+/** Every formula of a document, worked out once. */
+export interface FormulaAnalysis {
+    /** The document's formulas that can run, in document order. */
+    formulas: FormulaField[];
+    /** The item formulas that can run, per list. */
+    items: Map<FormListNode, FormulaField[]>;
+    /** The circles, each as the formulas on it. */
+    cycles: {
+        node: FormFieldNode;
+        label: string;
+    }[][];
+    /** The ids of the fields on a circle, which are not worked out. */
+    blocked: Set<string>;
+}
+/**
+ * The fields whose formulas read one another in a circle, each circle as
+ * the names on it, e.g. `[['total', 'tax']]`. A formula reading its own
+ * field is a circle of one. The items' fields are named with their list's,
+ * e.g. `rows.total`; a circle can go through the document's formulas and
+ * the items' alike. Pass the form's `functions` (or their names) when it
+ * has its own `sum`, `min`, `max`, `len` or `empty`, which may read any key of the items.
+ */
+export declare function findFormulaCycles(document: FormDocument, functions?: Readonly<Record<string, FormFunction>> | readonly string[]): string[][];
+/**
+ * Every formula of a document, the items' included, as one set: a
+ * formula reading a list reads all its items' formulas, and an item's
+ * formula reading `values` reads the document's.
+ */
+export declare function analyseFormulas(document: FormDocument, functions?: Readonly<Record<string, FormFunction>> | readonly string[]): FormulaAnalysis;
+/**
+ * Works out every formula of the form at once, the items' included, and
+ * writes the results into `values`, going over them again until nothing
+ * changes. Formulas on a circle are left out. The renderer's watchers keep
+ * results up to date in the page; on the server, where watchers run only
+ * once, this gives the same values the page will have, so a formula reading
+ * the items' formulas is not left behind.
+ */
+export declare function settleFormulas(document: FormDocument, values: Record<string, unknown>, functions?: Readonly<Record<string, FormFunction>>, analysis?: FormulaAnalysis): void;

package/dist/types/core/rules.d.ts

@@ -0,0 +1,23 @@
+import type { FormRule } from 'dou-ui';
+import type { FormFunction } from './expression';
+import type { FormFieldNode, FormListNode, FormRuleSpec, FormValidator } from './types';
+/** One rule as data, as the form's own rule. */
+export declare function toFormRule(spec: FormRuleSpec, options?: RulesOptions): FormRule;
+export interface RulesOptions {
+    /** Whether the field is required, when that is decided elsewhere. Defaults to the node's `required`. */
+    required?: boolean;
+    /** What `check` expressions can call besides the built-in functions. */
+    functions?: Readonly<Record<string, FormFunction>>;
+    /** The checks a rule's `validator` names. */
+    validators?: Readonly<Record<string, FormValidator>>;
+    /** Inside a list, the item the field belongs to, read as `item` by `check`. */
+    item?: () => unknown;
+    /** The field's path in the form, handed to validators. */
+    path?: () => string;
+}
+/**
+ * The rules of a field node, `required` first. Cached per node while its
+ * `rules`, whether it is required and the other options stay the same, so
+ * re-renders hand the form item the same array.
+ */
+export declare function rulesOf(node: FormFieldNode | FormListNode, options?: RulesOptions): FormRule[];

package/dist/types/core/types.d.ts

@@ -0,0 +1,211 @@
+import type { FormLabelAlign, FormLayout, FormModel, FormRequiredMark, FormValidatorResult, Size } from 'dou-ui';
+/** The form widths a responsive value switches at: 480, 640, 800 and 960px. */
+export type FormBreakpoint = 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * A value that may change with the width of the form (not of the
+ * viewport, so a form in a narrow dialog stacks like it would on a
+ * phone). Each breakpoint applies from its width up, until a larger one
+ * takes over; `base` applies below every breakpoint.
+ */
+export type FormResponsive<T> = T | ({
+    base?: T;
+} & Partial<Record<FormBreakpoint, T>>);
+/**
+ * A whole form, as plain data that survives `JSON.stringify`, so it can
+ * be stored, sent and edited by the builder.
+ */
+export interface FormDocument {
+    /** The shape of this data, for future migrations. Always `1` for now. */
+    version: 1;
+    /** Passed to the form: labels above (`vertical`), beside (`horizontal`) or a row of fields (`inline`). */
+    layout?: FormLayout;
+    labelAlign?: FormLabelAlign;
+    /** Width of the label column in the horizontal layout, in pixels. Defaults to 96. */
+    labelWidth?: number;
+    size?: Size;
+    requiredMark?: FormRequiredMark;
+    /** How many columns the layout grid has. Defaults to 12. */
+    columns?: number;
+    /** The fields and groups, in order. */
+    nodes: FormNode[];
+}
+export type FormNode = FormFieldNode | FormSectionNode | FormTabsNode | FormStepsNode | FormPageNode | FormListNode;
+/** The nodes that hold other nodes. */
+export type FormContainerNode = FormSectionNode | FormTabsNode | FormStepsNode | FormPageNode | FormListNode;
+interface FormNodeBase {
+    /** Unique within the document, and kept when the node moves or changes. */
+    id: string;
+    /** How many grid columns the node covers. Defaults to the whole row. */
+    span?: FormResponsive<number>;
+    /**
+     * An expression; the node shows only while it is true, e.g.
+     * `values.type == 'laptop'`. A hidden field is not checked on submit.
+     */
+    visibleWhen?: string;
+    /** An expression; the node, and everything in a group, is disabled while it is true. */
+    disabledWhen?: string;
+}
+export interface FormFieldNode extends FormNodeBase {
+    /** The field type, e.g. `input` or `select`, or one registered with `defineFormField`. */
+    type: string;
+    /**
+     * The path the value is written to, e.g. `name` or `contact.phone`.
+     * Needed by every field that holds a value; display-only types such as
+     * `text` or `divider` go without.
+     */
+    name?: string;
+    label?: string;
+    /** A hint shown below the field. */
+    help?: string;
+    /** The value the field starts with. Defaults to the type's empty value. */
+    default?: unknown;
+    /** Shorthand for a `{ required: true }` rule. */
+    required?: boolean;
+    /** An expression; the field is required while it is true. Takes over from `required`. */
+    requiredWhen?: string;
+    /**
+     * An expression whose result the field holds, e.g.
+     * `values.price * values.count`. It is worked out again whenever a value
+     * it reads changes, and the field cannot be edited.
+     */
+    formula?: string;
+    /**
+     * Where the options come from, for a type with options such as `select`:
+     * the name of a source given to the renderer's `sources`, and an
+     * expression for what to ask it, e.g. `{ name: 'cities', arg: 'values.province' }`.
+     * Asked again when the result of `arg` changes; a value the new options
+     * no longer offer is cleared, unless `keep` is set.
+     */
+    source?: FormOptionSource;
+    /** Checks the value must pass, besides `required`. */
+    rules?: FormRuleSpec[];
+    /** Settings of the field type: a placeholder, the options of a select, a range… */
+    props?: Record<string, unknown>;
+}
+/** A titled group of nodes with its own grid. */
+export interface FormSectionNode extends FormNodeBase {
+    type: 'section';
+    title?: string;
+    description?: string;
+    /** Draw a border around the group. */
+    bordered?: boolean;
+    /** Columns of the group's own grid. Defaults to the document's. */
+    columns?: number;
+    children: FormNode[];
+}
+export interface FormOptionSource {
+    /** The key of the source in the renderer's `sources`. */
+    name: string;
+    /**
+     * An expression; its result is handed to the source. To hand over
+     * several values, make it a list: `[values.province, values.kind]`.
+     */
+    arg?: string;
+    /** Keep the field's value when the options change and no longer offer it. */
+    keep?: boolean;
+}
+/** Pages shown one at a time, picked from a row of tabs. */
+export interface FormTabsNode extends FormNodeBase {
+    type: 'tabs';
+    /** The pages, one per tab. */
+    children: FormPageNode[];
+}
+/**
+ * Pages filled in one after another. Each page is checked before the
+ * next one opens; going back is always allowed.
+ */
+export interface FormStepsNode extends FormNodeBase {
+    type: 'steps';
+    /** The pages, one per step. */
+    children: FormPageNode[];
+}
+/** One page of `tabs` or `steps`. A hidden page (`visibleWhen`) is left out. */
+export interface FormPageNode extends FormNodeBase {
+    type: 'page';
+    /** The text of the tab or step. */
+    title: string;
+    description?: string;
+    /** Columns of the page's own grid. Defaults to the document's. */
+    columns?: number;
+    children: FormNode[];
+}
+/**
+ * A list of items that people add, remove and reorder, each made of the
+ * same fields, e.g. the people on a booking. The value at `name` is a
+ * list of objects; the fields inside name their own key in an item
+ * (`name: 'phone'` writes `item.phone`) and read the item in
+ * expressions as `item`.
+ */
+export interface FormListNode extends FormNodeBase {
+    type: 'list';
+    /** The path of the list, e.g. `guests`. */
+    name: string;
+    label?: string;
+    help?: string;
+    /** The items the list starts with. Defaults to `min` empty items. */
+    default?: Record<string, unknown>[];
+    /** Fewest items; below it items cannot be removed. */
+    min?: number;
+    /** Most items; at it no more can be added. */
+    max?: number;
+    /** Let people drag items into another order. Defaults to `true`. */
+    sortable?: boolean;
+    /** Text of the add button. Defaults to the locale's. */
+    addText?: string;
+    /** Checks of the list itself, e.g. `required` for at least one item. */
+    required?: boolean;
+    rules?: FormRuleSpec[];
+    /** Columns of each item's grid. Defaults to the document's. */
+    columns?: number;
+    /** The fields of one item. */
+    children: FormNode[];
+}
+/**
+ * A check as plain data. Turned into a `FormRule` of the form, so it
+ * behaves the same as rules written by hand.
+ */
+export interface FormRuleSpec {
+    /** The value must not be empty. */
+    required?: boolean;
+    type?: 'string' | 'number' | 'integer' | 'email' | 'url';
+    /** The least length of text, number of items, or number. */
+    min?: number;
+    /** The greatest length of text, number of items, or number. */
+    max?: number;
+    /** A regular expression text must match, as source text without slashes, e.g. `^\\d{6}$`. */
+    pattern?: string;
+    /** Flags for `pattern`, e.g. `i`. */
+    flags?: string;
+    /**
+     * An expression the value must make true, e.g. `value >= values.start`.
+     * `value` is the field's value and `values` the whole form. Like `min`
+     * and `pattern` it skips an empty value; that is `required`'s job.
+     */
+    check?: string;
+    /**
+     * The name of a check given to the renderer's `validators`, for what an
+     * expression cannot do, e.g. asking the server whether a name is taken.
+     * Skips an empty value too. Ignored when the rule has a `check`.
+     */
+    validator?: string;
+    /** Replaces the default message. */
+    message?: string;
+    trigger?: 'change' | 'blur';
+}
+/** What a validator gets besides the value. */
+export interface FormValidatorContext {
+    /** The whole form's values. */
+    values: FormModel;
+    /** Inside a list, the item the field belongs to; else `null`. */
+    item: unknown;
+    /** The path of the field, e.g. `username` or `guests.2.phone`. */
+    path: string;
+}
+/**
+ * A check of a field's value. Return `true` or nothing to pass, `false` to
+ * fail with the rule's `message`, or a string to fail with that string.
+ * May be async. Like the other checks of a rule, it is skipped while the
+ * value is empty; that is `required`'s job.
+ */
+export type FormValidator = (value: unknown, context: FormValidatorContext) => FormValidatorResult | Promise<FormValidatorResult>;
+export {};