@marktiderman/genesis-forms 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { a as FieldBlock, C as ContentBlock, P as PageBreakBlock, F as FormDefinition, H as HiddenInput, b as FormLayout, L as LogicRule, E as Ending, c as FormSettings, J as Json, d as Condition, B as Block, O as Operator } from './types-BBKBQ8sp.cjs';
 export { e as FormEvent, f as Operand } from './types-BBKBQ8sp.cjs';
-import { F as FormEngine } from './engine-CPLtKVew.cjs';
-export { C as CreateFormOptions, a as FormState, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-CPLtKVew.cjs';
+import { F as FormEngine } from './engine-BkNuzlna.cjs';
+export { C as CreateFormOptions, a as FormState, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-BkNuzlna.cjs';
 import { F as FieldValidator } from './validate-BXXqi0fq.cjs';
 export { R as REQUIRED_MESSAGE, S as StandardSchemaV1, v as validateField } from './validate-BXXqi0fq.cjs';
 
@@ -44,13 +44,45 @@ declare const f: {
     }) => FieldSpec<K, string>;
     email: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, string>;
     phone: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, string>;
+    /**
+     * A 1-to-`max` scale. `lowLabel` and `highLabel` are optional words under
+     * its ends ("Poor", "Great"); `display: "stars"` draws stars instead of numbers.
+     */
     rating: <K extends string>(key: K, o: FieldOptions & {
         max?: number | undefined;
+        lowLabel?: string | undefined;
+        highLabel?: string | undefined;
+        display?: "numbers" | "stars" | undefined;
+    }) => FieldSpec<K, number>;
+    /** A 0-to-10 Net Promoter Score. The end labels default to "Not likely" and "Very likely" in the renderer. */
+    nps: <K extends string>(key: K, o: FieldOptions & {
+        lowLabel?: string | undefined;
+        highLabel?: string | undefined;
     }) => FieldSpec<K, number>;
-    nps: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, number>;
     singleChoice: <K extends string, O extends string>(key: K, o: ChoiceFieldOptions<O>) => FieldSpec<K, O>;
     multiChoice: <K extends string, O extends string>(key: K, o: ChoiceFieldOptions<O>) => FieldSpec<K, O[]>;
     yesNo: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, boolean>;
+    /** One option from a compact menu: for a long list (a country, a class), where single choice would be a wall of buttons. */
+    dropdown: <K extends string, O extends string>(key: K, o: ChoiceFieldOptions<O>) => FieldSpec<K, O>;
+    /** A number, optionally between `min` and `max` and on a `step` (from `min`, else 0): `step: 1` for whole numbers. */
+    number: <K extends string>(key: K, o: FieldOptions & {
+        min?: number | undefined;
+        max?: number | undefined;
+        step?: number | undefined;
+    }) => FieldSpec<K, number>;
+    /** A calendar day, stored as `YYYY-MM-DD`, optionally between `min` and `max` (also `YYYY-MM-DD`). */
+    date: <K extends string>(key: K, o: FieldOptions & {
+        min?: string | undefined;
+        max?: string | undefined;
+    }) => FieldSpec<K, string>;
+    /**
+     * A single checkbox to agree to something. `text` is the checkbox's own
+     * words ("I agree to the terms"); the renderer defaults to "I agree".
+     * Checked stores `true`; unchecked is unanswered, so `required` means it must be checked.
+     */
+    consent: <K extends string>(key: K, o: FieldOptions & {
+        text?: string | undefined;
+    }) => FieldSpec<K, true>;
     /** Several short answers, one per line: goals, action items, three things that went well. */
     list: <K extends string>(key: K, o: FieldOptions & {
         min?: number | undefined;
@@ -58,6 +90,16 @@ declare const f: {
         itemMaxLength?: number | undefined;
         itemPlaceholder?: string | undefined;
     }) => FieldSpec<K, string[]>;
+    /**
+     * A value worked out from other answers and shown read-only, such as a
+     * total or a score: `formula` names answers by key (`hours * rate`,
+     * `sum(plan.cost)`). Stored with the answers; never required.
+     */
+    calculated: <K extends string>(key: K, o: Omit<FieldOptions, "required" | "placeholder"> & {
+        formula: string;
+        format?: "number" | "percent" | "text" | undefined;
+        decimals?: number | undefined;
+    }) => FieldSpec<K, string | number | boolean>;
     /**
      * A small table each answer fills row by row, one answer per column: an
      * action plan (What / Who / By when), pros and cons.
@@ -341,6 +383,26 @@ interface ChoiceOption {
     label?: string;
 }
 declare function choiceOptions(field: FieldBlock): ChoiceOption[];
+/** The optional words under the ends of a rating or NPS scale ("Poor", "Great"). */
+declare function scaleLabels(field: FieldBlock): {
+    low?: string;
+    high?: string;
+};
+/** How a rating is drawn: `"numbers"` (default) or `"stars"`. */
+declare function ratingDisplay(field: FieldBlock): "numbers" | "stars";
+/** A `number` field's limits: `min`, `max` and `step` (each optional; `step` is above 0). */
+declare function numberLimits(field: FieldBlock): {
+    min?: number;
+    max?: number;
+    step?: number;
+};
+/** `YYYY-MM-DD`, a real calendar day (no 2026-02-30), years 0001 to 9999. */
+declare function isIsoDate(value: string): boolean;
+/** A `date` field's earliest and latest days (`YYYY-MM-DD`), when set. */
+declare function dateLimits(field: FieldBlock): {
+    min?: string;
+    max?: string;
+};
 
 declare function listLimits(field: FieldBlock): {
     min: number;
@@ -393,6 +455,135 @@ declare const HIGHLIGHT_NOTE_MESSAGE = "Add a note to each highlight.";
  */
 declare const STRUCTURED_FIELD_TYPES: readonly ["list", "table", "media-notes", "text-highlights"];
 
+/**
+ * A small, safe formula language for `calculated` fields. It is parsed and
+ * evaluated here, never with `eval` or `Function`, and it can only read the
+ * answers it names.
+ *
+ * - Numbers: `12`, `0.5`. Text: `"High"` or `'High'`.
+ * - Answers by key: `hours`, and one column of a table: `plan.cost`.
+ * - Arithmetic: `+ - * /` (also `− × ÷`), unary minus, parentheses.
+ * - Comparisons: `== != < <= > >=` (also `= ≠ ≤ ≥`), giving true or false.
+ * - A choice: `cond ? a : b`.
+ * - `sum(...)`, `avg(...)`, `min(...)`, `max(...)` over numbers, lists and
+ *   table columns. Blanks and text that is not a number are skipped.
+ *
+ * An unanswered question reads as blank: arithmetic with a blank is blank
+ * (so a total stays empty until its answers are in), and so is dividing by
+ * zero. Text that holds a number ("12") counts as that number; yes / no
+ * counts as 1 / 0.
+ */
+
+type FormulaValue = number | string | boolean | null | FormulaValue[];
+/** An answer a formula reads: `key`, or `key.column` for one column of a table. */
+interface FormulaRef {
+    key: string;
+    column?: string;
+}
+type BinaryOp = "+" | "-" | "*" | "/" | "==" | "!=" | "<" | "<=" | ">" | ">=";
+declare const FORMULA_FUNCTIONS: readonly ["sum", "avg", "min", "max"];
+type FormulaFunction = (typeof FORMULA_FUNCTIONS)[number];
+type FormulaNode = {
+    kind: "number";
+    value: number;
+} | {
+    kind: "text";
+    value: string;
+} | {
+    kind: "ref";
+    key: string;
+    column?: string;
+    at: number;
+} | {
+    kind: "unary";
+    op: "-";
+    arg: FormulaNode;
+} | {
+    kind: "binary";
+    op: BinaryOp;
+    left: FormulaNode;
+    right: FormulaNode;
+} | {
+    kind: "if";
+    test: FormulaNode;
+    then: FormulaNode;
+    else: FormulaNode;
+} | {
+    kind: "call";
+    fn: FormulaFunction;
+    args: FormulaNode[];
+};
+type FormulaParseResult = {
+    ok: true;
+    ast: FormulaNode;
+    refs: FormulaRef[];
+} | {
+    ok: false;
+    message: string; /** Character offset of the problem. */
+    at: number;
+};
+/** Longest formula accepted. */
+declare const MAX_FORMULA_LENGTH = 2000;
+/**
+ * Parse a formula. Never throws: a mistake comes back as `{ ok: false,
+ * message, at }`, with the character offset of the problem.
+ */
+declare function parseFormula(source: string): FormulaParseResult;
+/** The answers a formula names, each once (none when it doesn't parse). */
+declare function formulaRefs(source: string): FormulaRef[];
+/**
+ * The formula with every reference to the answer `from` renamed to `to`.
+ * Column names, function names and text are left alone. Returned unchanged
+ * when it has a character a formula can't hold.
+ */
+declare function renameFormulaKey(source: string, from: string, to: string): string;
+/** A value as a number: numbers, numeric text ("1,200" too), yes / no as 1 / 0. Anything else is blank (`null`). */
+declare function formulaNumber(v: FormulaValue | Json | undefined): number | null;
+/** Reads an answer for `evaluateFormula`: its value, or `null` when unanswered or unknown. */
+type FormulaReader = (ref: FormulaRef) => FormulaValue;
+/** Evaluate a parsed formula. Never throws; a value it can't work out is `null`. */
+declare function evaluateFormula(ast: FormulaNode, read: FormulaReader): FormulaValue;
+
+/** The calculated field type's registry key. */
+declare const CALCULATED_TYPE = "calculated";
+/**
+ * Field types the builder offers only to a host that names them in its
+ * palette, like `STRUCTURED_FIELD_TYPES`: `calculated` shows a value worked
+ * out from other answers, so it is opt-in for hosts that want formulas.
+ */
+declare const COMPUTED_FIELD_TYPES: readonly ["calculated"];
+type CalculatedFormat = "number" | "percent" | "text";
+/** Most decimal places a calculated value may keep. */
+declare const MAX_CALCULATED_DECIMALS = 10;
+interface CalculatedProps {
+    formula: string;
+    format?: CalculatedFormat | undefined;
+    decimals?: number | undefined;
+}
+/** A calculated field's settings, with anything malformed left out. */
+declare function calculatedProps(field: FieldBlock): CalculatedProps;
+/**
+ * What a formula's result is stored as. `number` and `percent` keep a number
+ * (`0.25` for 25%), rounded to `decimals`; `text` keeps text. Without a
+ * format, numbers, text and true / false are kept as they are. A list, and
+ * anything the format can't hold, is no value (`undefined`).
+ */
+declare function calculatedValue(result: FormulaValue, field: FieldBlock): Json | undefined;
+/** A calculated value as shown: `12.5`, `25%`, the text, Yes / No. Empty when there is none. */
+declare function formatCalculated(value: Json | undefined, field: FieldBlock): string;
+/**
+ * Most items a formula reads from one answer (a list's items, a table's
+ * rows). A longer answer reads as blank, so one oversized value sent to the
+ * server can't make every formula over it slow.
+ */
+declare const MAX_FORMULA_ITEMS = 10000;
+/**
+ * The value a formula reads for an answer: numbers and text as they are, a
+ * list's items, one table column's cells. A list or table of more than
+ * `MAX_FORMULA_ITEMS` reads as blank.
+ */
+declare function formulaInput(value: Json | undefined, column?: string): FormulaValue;
+
 interface RecallScope {
     /** Fields by key. */
     fieldsByKey: Map<string, FieldBlock>;
@@ -475,4 +666,4 @@ declare function explain(source: FormEngine | ExplainInput, blockId: string, opt
 /** A condition as a plain-English clause: `contact_me is not Yes`. */
 declare function describeCondition(condition: Condition, def: FormDefinition, fields?: Map<string, FieldBlock>): string;
 
-export { type AnswersOf, Block, type ChoiceFieldOptions, type ChoiceOption, type CoerceHiddenOptions, type CoercedHidden, Condition, ContentBlock, Ending, type ExplainInput, type ExplainOptions, type Explanation, FieldBlock, type FieldOptions, type FieldSpec, type FieldTypeManifest, type FieldValidation, FieldValidator, type Form, FormDefinition, FormEngine, type FormInput, type FormIssue, FormLayout, FormSettings, HIGHLIGHT_NOTE_MESSAGE, HiddenInput, type Highlight, Json, type JumpTrace, type KeyResolver, LogicRule, MAX_HIDDEN_STRING_LENGTH, MAX_HIGHLIGHT_NOTE_LENGTH, MAX_HIGHLIGHT_QUOTE_LENGTH, MAX_TABLE_CELL_LENGTH, MAX_TABLE_COLUMNS, MAX_TIMESTAMP_SECONDS, type MediaNote, Operator, PageBreakBlock, type ParseResult, type PathResult, type RuleSpec, type RuleTrace, STRUCTURED_FIELD_TYPES, type TableColumn, canonicalJson, choiceOptions, coerceHidden, coerceHiddenValue, computePath, defineForm, describeCondition, evaluate, explain, f, fingerprint, formatTimestamp, getFieldType, isEmptyValue, isSensitive, listFieldTypes, listLimits, normalizeValue, parseForm, parseTimestamp, recall, registerFieldType, ruleVisible, steps, summarizeValue, tableColumns, tableLimits, when };
+export { type AnswersOf, Block, CALCULATED_TYPE, COMPUTED_FIELD_TYPES, type CalculatedFormat, type CalculatedProps, type ChoiceFieldOptions, type ChoiceOption, type CoerceHiddenOptions, type CoercedHidden, Condition, ContentBlock, Ending, type ExplainInput, type ExplainOptions, type Explanation, FORMULA_FUNCTIONS, FieldBlock, type FieldOptions, type FieldSpec, type FieldTypeManifest, type FieldValidation, FieldValidator, type Form, FormDefinition, FormEngine, type FormInput, type FormIssue, FormLayout, FormSettings, type FormulaFunction, type FormulaNode, type FormulaParseResult, type FormulaReader, type FormulaRef, type FormulaValue, HIGHLIGHT_NOTE_MESSAGE, HiddenInput, type Highlight, Json, type JumpTrace, type KeyResolver, LogicRule, MAX_CALCULATED_DECIMALS, MAX_FORMULA_ITEMS, MAX_FORMULA_LENGTH, MAX_HIDDEN_STRING_LENGTH, MAX_HIGHLIGHT_NOTE_LENGTH, MAX_HIGHLIGHT_QUOTE_LENGTH, MAX_TABLE_CELL_LENGTH, MAX_TABLE_COLUMNS, MAX_TIMESTAMP_SECONDS, type MediaNote, Operator, PageBreakBlock, type ParseResult, type PathResult, type RuleSpec, type RuleTrace, STRUCTURED_FIELD_TYPES, type TableColumn, calculatedProps, calculatedValue, canonicalJson, choiceOptions, coerceHidden, coerceHiddenValue, computePath, dateLimits, defineForm, describeCondition, evaluate, evaluateFormula, explain, f, fingerprint, formatCalculated, formatTimestamp, formulaInput, formulaNumber, formulaRefs, getFieldType, isEmptyValue, isIsoDate, isSensitive, listFieldTypes, listLimits, normalizeValue, numberLimits, parseForm, parseFormula, parseTimestamp, ratingDisplay, recall, registerFieldType, renameFormulaKey, ruleVisible, scaleLabels, steps, summarizeValue, tableColumns, tableLimits, when };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { a as FieldBlock, C as ContentBlock, P as PageBreakBlock, F as FormDefinition, H as HiddenInput, b as FormLayout, L as LogicRule, E as Ending, c as FormSettings, J as Json, d as Condition, B as Block, O as Operator } from './types-BBKBQ8sp.js';
 export { e as FormEvent, f as Operand } from './types-BBKBQ8sp.js';
-import { F as FormEngine } from './engine-DOrPgFDw.js';
-export { C as CreateFormOptions, a as FormState, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-DOrPgFDw.js';
+import { F as FormEngine } from './engine-Dz9J5ej2.js';
+export { C as CreateFormOptions, a as FormState, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-Dz9J5ej2.js';
 import { F as FieldValidator } from './validate-BjNwF1UE.js';
 export { R as REQUIRED_MESSAGE, S as StandardSchemaV1, v as validateField } from './validate-BjNwF1UE.js';
 
@@ -44,13 +44,45 @@ declare const f: {
     }) => FieldSpec<K, string>;
     email: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, string>;
     phone: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, string>;
+    /**
+     * A 1-to-`max` scale. `lowLabel` and `highLabel` are optional words under
+     * its ends ("Poor", "Great"); `display: "stars"` draws stars instead of numbers.
+     */
     rating: <K extends string>(key: K, o: FieldOptions & {
         max?: number | undefined;
+        lowLabel?: string | undefined;
+        highLabel?: string | undefined;
+        display?: "numbers" | "stars" | undefined;
+    }) => FieldSpec<K, number>;
+    /** A 0-to-10 Net Promoter Score. The end labels default to "Not likely" and "Very likely" in the renderer. */
+    nps: <K extends string>(key: K, o: FieldOptions & {
+        lowLabel?: string | undefined;
+        highLabel?: string | undefined;
     }) => FieldSpec<K, number>;
-    nps: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, number>;
     singleChoice: <K extends string, O extends string>(key: K, o: ChoiceFieldOptions<O>) => FieldSpec<K, O>;
     multiChoice: <K extends string, O extends string>(key: K, o: ChoiceFieldOptions<O>) => FieldSpec<K, O[]>;
     yesNo: <K extends string>(key: K, o: FieldOptions) => FieldSpec<K, boolean>;
+    /** One option from a compact menu: for a long list (a country, a class), where single choice would be a wall of buttons. */
+    dropdown: <K extends string, O extends string>(key: K, o: ChoiceFieldOptions<O>) => FieldSpec<K, O>;
+    /** A number, optionally between `min` and `max` and on a `step` (from `min`, else 0): `step: 1` for whole numbers. */
+    number: <K extends string>(key: K, o: FieldOptions & {
+        min?: number | undefined;
+        max?: number | undefined;
+        step?: number | undefined;
+    }) => FieldSpec<K, number>;
+    /** A calendar day, stored as `YYYY-MM-DD`, optionally between `min` and `max` (also `YYYY-MM-DD`). */
+    date: <K extends string>(key: K, o: FieldOptions & {
+        min?: string | undefined;
+        max?: string | undefined;
+    }) => FieldSpec<K, string>;
+    /**
+     * A single checkbox to agree to something. `text` is the checkbox's own
+     * words ("I agree to the terms"); the renderer defaults to "I agree".
+     * Checked stores `true`; unchecked is unanswered, so `required` means it must be checked.
+     */
+    consent: <K extends string>(key: K, o: FieldOptions & {
+        text?: string | undefined;
+    }) => FieldSpec<K, true>;
     /** Several short answers, one per line: goals, action items, three things that went well. */
     list: <K extends string>(key: K, o: FieldOptions & {
         min?: number | undefined;
@@ -58,6 +90,16 @@ declare const f: {
         itemMaxLength?: number | undefined;
         itemPlaceholder?: string | undefined;
     }) => FieldSpec<K, string[]>;
+    /**
+     * A value worked out from other answers and shown read-only, such as a
+     * total or a score: `formula` names answers by key (`hours * rate`,
+     * `sum(plan.cost)`). Stored with the answers; never required.
+     */
+    calculated: <K extends string>(key: K, o: Omit<FieldOptions, "required" | "placeholder"> & {
+        formula: string;
+        format?: "number" | "percent" | "text" | undefined;
+        decimals?: number | undefined;
+    }) => FieldSpec<K, string | number | boolean>;
     /**
      * A small table each answer fills row by row, one answer per column: an
      * action plan (What / Who / By when), pros and cons.
@@ -341,6 +383,26 @@ interface ChoiceOption {
     label?: string;
 }
 declare function choiceOptions(field: FieldBlock): ChoiceOption[];
+/** The optional words under the ends of a rating or NPS scale ("Poor", "Great"). */
+declare function scaleLabels(field: FieldBlock): {
+    low?: string;
+    high?: string;
+};
+/** How a rating is drawn: `"numbers"` (default) or `"stars"`. */
+declare function ratingDisplay(field: FieldBlock): "numbers" | "stars";
+/** A `number` field's limits: `min`, `max` and `step` (each optional; `step` is above 0). */
+declare function numberLimits(field: FieldBlock): {
+    min?: number;
+    max?: number;
+    step?: number;
+};
+/** `YYYY-MM-DD`, a real calendar day (no 2026-02-30), years 0001 to 9999. */
+declare function isIsoDate(value: string): boolean;
+/** A `date` field's earliest and latest days (`YYYY-MM-DD`), when set. */
+declare function dateLimits(field: FieldBlock): {
+    min?: string;
+    max?: string;
+};
 
 declare function listLimits(field: FieldBlock): {
     min: number;
@@ -393,6 +455,135 @@ declare const HIGHLIGHT_NOTE_MESSAGE = "Add a note to each highlight.";
  */
 declare const STRUCTURED_FIELD_TYPES: readonly ["list", "table", "media-notes", "text-highlights"];
 
+/**
+ * A small, safe formula language for `calculated` fields. It is parsed and
+ * evaluated here, never with `eval` or `Function`, and it can only read the
+ * answers it names.
+ *
+ * - Numbers: `12`, `0.5`. Text: `"High"` or `'High'`.
+ * - Answers by key: `hours`, and one column of a table: `plan.cost`.
+ * - Arithmetic: `+ - * /` (also `− × ÷`), unary minus, parentheses.
+ * - Comparisons: `== != < <= > >=` (also `= ≠ ≤ ≥`), giving true or false.
+ * - A choice: `cond ? a : b`.
+ * - `sum(...)`, `avg(...)`, `min(...)`, `max(...)` over numbers, lists and
+ *   table columns. Blanks and text that is not a number are skipped.
+ *
+ * An unanswered question reads as blank: arithmetic with a blank is blank
+ * (so a total stays empty until its answers are in), and so is dividing by
+ * zero. Text that holds a number ("12") counts as that number; yes / no
+ * counts as 1 / 0.
+ */
+
+type FormulaValue = number | string | boolean | null | FormulaValue[];
+/** An answer a formula reads: `key`, or `key.column` for one column of a table. */
+interface FormulaRef {
+    key: string;
+    column?: string;
+}
+type BinaryOp = "+" | "-" | "*" | "/" | "==" | "!=" | "<" | "<=" | ">" | ">=";
+declare const FORMULA_FUNCTIONS: readonly ["sum", "avg", "min", "max"];
+type FormulaFunction = (typeof FORMULA_FUNCTIONS)[number];
+type FormulaNode = {
+    kind: "number";
+    value: number;
+} | {
+    kind: "text";
+    value: string;
+} | {
+    kind: "ref";
+    key: string;
+    column?: string;
+    at: number;
+} | {
+    kind: "unary";
+    op: "-";
+    arg: FormulaNode;
+} | {
+    kind: "binary";
+    op: BinaryOp;
+    left: FormulaNode;
+    right: FormulaNode;
+} | {
+    kind: "if";
+    test: FormulaNode;
+    then: FormulaNode;
+    else: FormulaNode;
+} | {
+    kind: "call";
+    fn: FormulaFunction;
+    args: FormulaNode[];
+};
+type FormulaParseResult = {
+    ok: true;
+    ast: FormulaNode;
+    refs: FormulaRef[];
+} | {
+    ok: false;
+    message: string; /** Character offset of the problem. */
+    at: number;
+};
+/** Longest formula accepted. */
+declare const MAX_FORMULA_LENGTH = 2000;
+/**
+ * Parse a formula. Never throws: a mistake comes back as `{ ok: false,
+ * message, at }`, with the character offset of the problem.
+ */
+declare function parseFormula(source: string): FormulaParseResult;
+/** The answers a formula names, each once (none when it doesn't parse). */
+declare function formulaRefs(source: string): FormulaRef[];
+/**
+ * The formula with every reference to the answer `from` renamed to `to`.
+ * Column names, function names and text are left alone. Returned unchanged
+ * when it has a character a formula can't hold.
+ */
+declare function renameFormulaKey(source: string, from: string, to: string): string;
+/** A value as a number: numbers, numeric text ("1,200" too), yes / no as 1 / 0. Anything else is blank (`null`). */
+declare function formulaNumber(v: FormulaValue | Json | undefined): number | null;
+/** Reads an answer for `evaluateFormula`: its value, or `null` when unanswered or unknown. */
+type FormulaReader = (ref: FormulaRef) => FormulaValue;
+/** Evaluate a parsed formula. Never throws; a value it can't work out is `null`. */
+declare function evaluateFormula(ast: FormulaNode, read: FormulaReader): FormulaValue;
+
+/** The calculated field type's registry key. */
+declare const CALCULATED_TYPE = "calculated";
+/**
+ * Field types the builder offers only to a host that names them in its
+ * palette, like `STRUCTURED_FIELD_TYPES`: `calculated` shows a value worked
+ * out from other answers, so it is opt-in for hosts that want formulas.
+ */
+declare const COMPUTED_FIELD_TYPES: readonly ["calculated"];
+type CalculatedFormat = "number" | "percent" | "text";
+/** Most decimal places a calculated value may keep. */
+declare const MAX_CALCULATED_DECIMALS = 10;
+interface CalculatedProps {
+    formula: string;
+    format?: CalculatedFormat | undefined;
+    decimals?: number | undefined;
+}
+/** A calculated field's settings, with anything malformed left out. */
+declare function calculatedProps(field: FieldBlock): CalculatedProps;
+/**
+ * What a formula's result is stored as. `number` and `percent` keep a number
+ * (`0.25` for 25%), rounded to `decimals`; `text` keeps text. Without a
+ * format, numbers, text and true / false are kept as they are. A list, and
+ * anything the format can't hold, is no value (`undefined`).
+ */
+declare function calculatedValue(result: FormulaValue, field: FieldBlock): Json | undefined;
+/** A calculated value as shown: `12.5`, `25%`, the text, Yes / No. Empty when there is none. */
+declare function formatCalculated(value: Json | undefined, field: FieldBlock): string;
+/**
+ * Most items a formula reads from one answer (a list's items, a table's
+ * rows). A longer answer reads as blank, so one oversized value sent to the
+ * server can't make every formula over it slow.
+ */
+declare const MAX_FORMULA_ITEMS = 10000;
+/**
+ * The value a formula reads for an answer: numbers and text as they are, a
+ * list's items, one table column's cells. A list or table of more than
+ * `MAX_FORMULA_ITEMS` reads as blank.
+ */
+declare function formulaInput(value: Json | undefined, column?: string): FormulaValue;
+
 interface RecallScope {
     /** Fields by key. */
     fieldsByKey: Map<string, FieldBlock>;
@@ -475,4 +666,4 @@ declare function explain(source: FormEngine | ExplainInput, blockId: string, opt
 /** A condition as a plain-English clause: `contact_me is not Yes`. */
 declare function describeCondition(condition: Condition, def: FormDefinition, fields?: Map<string, FieldBlock>): string;
 
-export { type AnswersOf, Block, type ChoiceFieldOptions, type ChoiceOption, type CoerceHiddenOptions, type CoercedHidden, Condition, ContentBlock, Ending, type ExplainInput, type ExplainOptions, type Explanation, FieldBlock, type FieldOptions, type FieldSpec, type FieldTypeManifest, type FieldValidation, FieldValidator, type Form, FormDefinition, FormEngine, type FormInput, type FormIssue, FormLayout, FormSettings, HIGHLIGHT_NOTE_MESSAGE, HiddenInput, type Highlight, Json, type JumpTrace, type KeyResolver, LogicRule, MAX_HIDDEN_STRING_LENGTH, MAX_HIGHLIGHT_NOTE_LENGTH, MAX_HIGHLIGHT_QUOTE_LENGTH, MAX_TABLE_CELL_LENGTH, MAX_TABLE_COLUMNS, MAX_TIMESTAMP_SECONDS, type MediaNote, Operator, PageBreakBlock, type ParseResult, type PathResult, type RuleSpec, type RuleTrace, STRUCTURED_FIELD_TYPES, type TableColumn, canonicalJson, choiceOptions, coerceHidden, coerceHiddenValue, computePath, defineForm, describeCondition, evaluate, explain, f, fingerprint, formatTimestamp, getFieldType, isEmptyValue, isSensitive, listFieldTypes, listLimits, normalizeValue, parseForm, parseTimestamp, recall, registerFieldType, ruleVisible, steps, summarizeValue, tableColumns, tableLimits, when };
+export { type AnswersOf, Block, CALCULATED_TYPE, COMPUTED_FIELD_TYPES, type CalculatedFormat, type CalculatedProps, type ChoiceFieldOptions, type ChoiceOption, type CoerceHiddenOptions, type CoercedHidden, Condition, ContentBlock, Ending, type ExplainInput, type ExplainOptions, type Explanation, FORMULA_FUNCTIONS, FieldBlock, type FieldOptions, type FieldSpec, type FieldTypeManifest, type FieldValidation, FieldValidator, type Form, FormDefinition, FormEngine, type FormInput, type FormIssue, FormLayout, FormSettings, type FormulaFunction, type FormulaNode, type FormulaParseResult, type FormulaReader, type FormulaRef, type FormulaValue, HIGHLIGHT_NOTE_MESSAGE, HiddenInput, type Highlight, Json, type JumpTrace, type KeyResolver, LogicRule, MAX_CALCULATED_DECIMALS, MAX_FORMULA_ITEMS, MAX_FORMULA_LENGTH, MAX_HIDDEN_STRING_LENGTH, MAX_HIGHLIGHT_NOTE_LENGTH, MAX_HIGHLIGHT_QUOTE_LENGTH, MAX_TABLE_CELL_LENGTH, MAX_TABLE_COLUMNS, MAX_TIMESTAMP_SECONDS, type MediaNote, Operator, PageBreakBlock, type ParseResult, type PathResult, type RuleSpec, type RuleTrace, STRUCTURED_FIELD_TYPES, type TableColumn, calculatedProps, calculatedValue, canonicalJson, choiceOptions, coerceHidden, coerceHiddenValue, computePath, dateLimits, defineForm, describeCondition, evaluate, evaluateFormula, explain, f, fingerprint, formatCalculated, formatTimestamp, formulaInput, formulaNumber, formulaRefs, getFieldType, isEmptyValue, isIsoDate, isSensitive, listFieldTypes, listLimits, normalizeValue, numberLimits, parseForm, parseFormula, parseTimestamp, ratingDisplay, recall, registerFieldType, renameFormulaKey, ruleVisible, scaleLabels, steps, summarizeValue, tableColumns, tableLimits, when };