@marktiderman/genesis-forms 0.4.2 → 0.5.0

package/dist/index.d.cts

@@ -1,9 +1,68 @@
-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-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';
+import { a as FieldBlock, J as Json, C as ContentBlock, P as PageBreakBlock, O as OptionsSource, F as FormDefinition, H as HiddenInput, b as FormLayout, L as LogicRule, E as Ending, c as FormSettings, d as Condition, B as Block } from './types-BhYUbLJ-.cjs';
+export { e as FormEvent, f as Operand, g as Operator } from './types-BhYUbLJ-.cjs';
+import { F as FormEngine, a as FormState } from './engine-BDq0XJ21.cjs';
+export { C as CreateFormOptions, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-BDq0XJ21.cjs';
+import { F as FieldValidator } from './validate-BsZ0YTQS.cjs';
+export { C as ChoiceOption, a as FieldTypeManifest, H as HostOptions, O as OTHER_MAX_LENGTH, R as REQUIRED_MESSAGE, S as StandardSchemaV1, c as choiceOptions, d as dateLimits, g as getFieldType, i as isEmptyValue, b as isIsoDate, e as isOtherValue, f as isSensitive, l as listFieldTypes, n as normalizeValue, h as numberLimits, o as optionsSource, j as otherOption, r as ratingDisplay, k as registerFieldType, s as scaleLabels, m as summarizeValue, v as validateField, w as withHostOptions } from './validate-BsZ0YTQS.cjs';
+
+/**
+ * The `photo` field type: a respondent attaches up to a few photos, such as a
+ * picture of broken equipment. The answer holds references the host's storage
+ * handed back (`PhotoRef`), never the bytes: the renderer uploads through the
+ * host (`onUpload` on genesis-forms-web's `Form`), so the engine and the
+ * server stay storage-agnostic. A host's server should check that each
+ * reference is a file it stored for this respondent before saving.
+ *
+ * Opt-in in a builder palette (`UPLOAD_FIELD_TYPES`), since a host must be
+ * able to store the files.
+ */
+declare const PHOTO_TYPE = "photo";
+/** Field types that need the host to store files; a builder offers them only when the host names them. */
+declare const UPLOAD_FIELD_TYPES: readonly ["photo"];
+/** One stored photo, as the host's upload returned it. */
+type PhotoRef = {
+    /** The host's id for the stored file. */
+    id: string;
+    /** The file's name on the respondent's device. */
+    name: string;
+    /** Its MIME type, such as `image/jpeg`. */
+    type: string;
+    /** Bytes. */
+    size: number;
+};
+type PhotoFormat = "jpeg" | "png" | "heic" | "webp";
+/** The MIME types each format covers. */
+declare const PHOTO_FORMATS: Record<PhotoFormat, readonly string[]>;
+declare const DEFAULT_PHOTO_FILES = 3;
+declare const MAX_PHOTO_FILES = 5;
+declare const DEFAULT_PHOTO_SIZE_MB = 10;
+declare const MAX_PHOTO_SIZE_MB = 25;
+/** The longest reference id and file name a photo answer may carry. */
+declare const MAX_PHOTO_ID_LENGTH = 200;
+declare const MAX_PHOTO_NAME_LENGTH = 255;
+declare const isPhotoFormat: (v: unknown) => v is PhotoFormat;
+interface PhotoLimits {
+    maxFiles: number;
+    maxSizeMb: number;
+    maxBytes: number;
+    formats: PhotoFormat[];
+    /** Every MIME type the formats cover. */
+    mimeTypes: string[];
+}
+/** A photo field's limits; a prop that is missing or out of range uses its default. */
+declare function photoLimits(field: FieldBlock): PhotoLimits;
+/** Whether `v` has a photo reference's shape (any type and size). */
+declare function isPhotoRef(v: unknown): v is PhotoRef;
+/** The well-formed references in a photo answer, as `{ id, name, type, size }` only. */
+declare function photoRefs(value: Json | undefined): PhotoRef[];
+/** "JPEG, PNG or WebP". */
+declare function photoFormatList(formats: readonly PhotoFormat[]): string;
+/** The message for a file of a type the field doesn't take. */
+declare const photoTypeMessage: (field: FieldBlock) => string;
+/** The message for a file over the field's size limit. */
+declare const photoSizeMessage: (field: FieldBlock) => string;
+/** The message for more photos than the field takes. */
+declare const photoCountMessage: (field: FieldBlock) => string;
 
 /** A field block that remembers its key and value type, for answer inference. */
 type FieldSpec<K extends string = string, V = unknown> = FieldBlock & {
@@ -24,10 +83,24 @@ interface FieldOptions {
     id?: string | undefined;
 }
 interface ChoiceFieldOptions<O extends string> extends FieldOptions {
-    options: readonly {
+    /** The options. Optional only with `optionsFrom`, whose options follow these. */
+    options?: readonly {
         value: O;
         label?: string;
-    }[];
+    }[] | undefined;
+    /**
+     * Options the app showing the form supplies, by key (`OptionsSource`), such
+     * as `{ source: "host", key: "coaches" }`; pass the lists as `hostOptions`
+     * to `createForm` and `validateSubmission`.
+     */
+    optionsFrom?: OptionsSource | undefined;
+    /**
+     * An "Other" option the respondent fills in (`true`, or `{ label }` to name it): their text is
+     * the answer (one more item on a multiple choice). See `otherOption`.
+     */
+    other?: boolean | {
+        label?: string;
+    } | undefined;
 }
 interface HiddenOptions {
     source?: HiddenInput["source"] | undefined;
@@ -137,6 +210,16 @@ declare const f: {
         quote: string;
         note: string;
     }[]>;
+    /**
+     * Up to a few photos (a picture of broken equipment). The answer holds the
+     * references the host's upload returned, never the bytes; `formats` from
+     * jpeg, png, heic and webp (default all four).
+     */
+    photo: <K extends string>(key: K, o: FieldOptions & {
+        maxFiles?: number | undefined;
+        maxSizeMb?: number | undefined;
+        formats?: readonly PhotoFormat[] | undefined;
+    }) => FieldSpec<K, PhotoRef[]>;
     /** Any registered field type, including plugins. */
     custom: <K extends string, V = Json>(type: string, key: K, o: FieldOptions & {
         props?: Record<string, Json>;
@@ -333,76 +416,38 @@ declare function computePath(def: FormDefinition, scope: EvalScope): PathResult;
 declare function ruleVisible(def: FormDefinition, blockId: string, scope: EvalScope): boolean;
 
 /**
- * A field type, without any UI. Renderers are registered separately per
- * platform (`genesis-forms-react`), so a manifest runs anywhere.
+ * How far a respondent has got, for saving answers as they go
+ * (`settings.saveProgress`) and for drop-off by question. Pure: reads a form's
+ * state, never changes it.
  */
-interface FieldTypeManifest {
-    type: string;
-    label: string;
-    category: "text" | "choice" | "scale" | "date" | "media" | "advanced";
-    /** `json: false` types must convert, so drafts and server replay never lose an answer. */
-    value: {
-        json: true;
-    } | {
-        json: false;
-        serialize: (value: unknown) => Json;
-        deserialize: (json: Json) => unknown;
-    };
-    operators: Operator[];
-    a11y: {
-        semantics: "control" | "group";
-        /** The HTML `autocomplete` token, such as `"email"` or `"tel"`. */
-        autocomplete?: string;
-        /** The HTML `inputmode` hint for on-screen keyboards, such as `"email"` or `"tel"`. */
-        inputMode?: "text" | "email" | "tel" | "numeric" | "decimal" | "url" | "search";
-    };
-    isEmpty?: (value: Json | undefined) => boolean;
-    /** Return an error message, or null when the (non-empty) value is valid. */
-    validate?: (value: Json, field: FieldBlock) => string | null;
-    /** Plain text for recall, exports and emails. */
-    summarize?: (value: Json, field: FieldBlock) => string;
+
+interface FormProgress {
     /**
-     * The form a (valid, non-empty) value is stored in, such as an email
-     * without surrounding spaces. Applied by `engine.answers()` and the server.
+     * The furthest block reached, 1-based, on the path as it is now (logic can
+     * lengthen or shorten the path, so store `fieldId`, not this). 0 before any.
      */
-    normalize?: (value: Json, field: FieldBlock) => Json;
-    /** Valid example answers, used by `coverage()` and other test tools to explore a path. */
-    samples?: (field: FieldBlock) => Json[];
-}
-declare function registerFieldType(manifest: FieldTypeManifest): void;
-declare function getFieldType(type: string): FieldTypeManifest | undefined;
-declare function listFieldTypes(): FieldTypeManifest[];
-declare function isEmptyValue(value: Json | undefined, field?: FieldBlock): boolean;
-/** A value in its stored form (see `FieldTypeManifest.normalize`). */
-declare function normalizeValue(value: Json, field: FieldBlock): Json;
-/** Whether a block holds personal or secret data: `sensitive: true`, or the `props.sensitive: true` alias. */
-declare function isSensitive(block: Block): boolean;
-declare function summarizeValue(value: Json | undefined, field: FieldBlock): string;
-interface ChoiceOption {
-    value: string;
-    label?: string;
+    step: number;
+    /** How many blocks the path has now. */
+    total: number;
+    /**
+     * The id of the furthest question (field) reached: shown in focus layout, or
+     * answered. Null before any. A content block on the way is not a question,
+     * so the question before it counts.
+     */
+    fieldId: string | null;
 }
-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;
-};
+/**
+ * The furthest block on the path the respondent has reached: the one on screen,
+ * one they went back from, or (in classic layout, where every question shows at
+ * once) the last one they answered. Null when the path is empty.
+ */
+declare function furthestReached(state: FormState, definition: FormDefinition): string | null;
+/**
+ * Where the respondent is: the furthest step and the furthest question reached.
+ * What genesis-forms-web's `onProgress` passes; `engine.answers()` has the
+ * answers so far.
+ */
+declare function formProgress(engine: Pick<FormEngine, "definition" | "getState">): FormProgress;
 
 declare function listLimits(field: FieldBlock): {
     min: number;
@@ -676,4 +721,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, 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_FORM_FORMULA_LENGTH, MAX_HIDDEN_STRING_LENGTH, MAX_HIGHLIGHT_NOTE_LENGTH, MAX_HIGHLIGHT_QUOTE_LENGTH, MAX_SETTLE_ITEMS, 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 };
+export { type AnswersOf, Block, CALCULATED_TYPE, COMPUTED_FIELD_TYPES, type CalculatedFormat, type CalculatedProps, type ChoiceFieldOptions, type CoerceHiddenOptions, type CoercedHidden, Condition, ContentBlock, DEFAULT_PHOTO_FILES, DEFAULT_PHOTO_SIZE_MB, Ending, type ExplainInput, type ExplainOptions, type Explanation, FORMULA_FUNCTIONS, FieldBlock, type FieldOptions, type FieldSpec, type FieldValidation, FieldValidator, type Form, FormDefinition, FormEngine, type FormInput, type FormIssue, FormLayout, type FormProgress, FormSettings, FormState, 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_FORM_FORMULA_LENGTH, MAX_HIDDEN_STRING_LENGTH, MAX_HIGHLIGHT_NOTE_LENGTH, MAX_HIGHLIGHT_QUOTE_LENGTH, MAX_PHOTO_FILES, MAX_PHOTO_ID_LENGTH, MAX_PHOTO_NAME_LENGTH, MAX_PHOTO_SIZE_MB, MAX_SETTLE_ITEMS, MAX_TABLE_CELL_LENGTH, MAX_TABLE_COLUMNS, MAX_TIMESTAMP_SECONDS, type MediaNote, OptionsSource, PHOTO_FORMATS, PHOTO_TYPE, PageBreakBlock, type ParseResult, type PathResult, type PhotoFormat, type PhotoLimits, type PhotoRef, type RuleSpec, type RuleTrace, STRUCTURED_FIELD_TYPES, type TableColumn, UPLOAD_FIELD_TYPES, calculatedProps, calculatedValue, canonicalJson, coerceHidden, coerceHiddenValue, computePath, defineForm, describeCondition, evaluate, evaluateFormula, explain, f, fingerprint, formProgress, formatCalculated, formatTimestamp, formulaInput, formulaNumber, formulaRefs, furthestReached, isPhotoFormat, isPhotoRef, listLimits, parseForm, parseFormula, parseTimestamp, photoCountMessage, photoFormatList, photoLimits, photoRefs, photoSizeMessage, photoTypeMessage, recall, renameFormulaKey, ruleVisible, steps, tableColumns, tableLimits, when };

package/dist/index.d.ts

@@ -1,9 +1,68 @@
-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-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';
+import { a as FieldBlock, J as Json, C as ContentBlock, P as PageBreakBlock, O as OptionsSource, F as FormDefinition, H as HiddenInput, b as FormLayout, L as LogicRule, E as Ending, c as FormSettings, d as Condition, B as Block } from './types-BhYUbLJ-.js';
+export { e as FormEvent, f as Operand, g as Operator } from './types-BhYUbLJ-.js';
+import { F as FormEngine, a as FormState } from './engine-Qzp6bX6O.js';
+export { C as CreateFormOptions, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-Qzp6bX6O.js';
+import { F as FieldValidator } from './validate-Bs1lyoOl.js';
+export { C as ChoiceOption, a as FieldTypeManifest, H as HostOptions, O as OTHER_MAX_LENGTH, R as REQUIRED_MESSAGE, S as StandardSchemaV1, c as choiceOptions, d as dateLimits, g as getFieldType, i as isEmptyValue, b as isIsoDate, e as isOtherValue, f as isSensitive, l as listFieldTypes, n as normalizeValue, h as numberLimits, o as optionsSource, j as otherOption, r as ratingDisplay, k as registerFieldType, s as scaleLabels, m as summarizeValue, v as validateField, w as withHostOptions } from './validate-Bs1lyoOl.js';
+
+/**
+ * The `photo` field type: a respondent attaches up to a few photos, such as a
+ * picture of broken equipment. The answer holds references the host's storage
+ * handed back (`PhotoRef`), never the bytes: the renderer uploads through the
+ * host (`onUpload` on genesis-forms-web's `Form`), so the engine and the
+ * server stay storage-agnostic. A host's server should check that each
+ * reference is a file it stored for this respondent before saving.
+ *
+ * Opt-in in a builder palette (`UPLOAD_FIELD_TYPES`), since a host must be
+ * able to store the files.
+ */
+declare const PHOTO_TYPE = "photo";
+/** Field types that need the host to store files; a builder offers them only when the host names them. */
+declare const UPLOAD_FIELD_TYPES: readonly ["photo"];
+/** One stored photo, as the host's upload returned it. */
+type PhotoRef = {
+    /** The host's id for the stored file. */
+    id: string;
+    /** The file's name on the respondent's device. */
+    name: string;
+    /** Its MIME type, such as `image/jpeg`. */
+    type: string;
+    /** Bytes. */
+    size: number;
+};
+type PhotoFormat = "jpeg" | "png" | "heic" | "webp";
+/** The MIME types each format covers. */
+declare const PHOTO_FORMATS: Record<PhotoFormat, readonly string[]>;
+declare const DEFAULT_PHOTO_FILES = 3;
+declare const MAX_PHOTO_FILES = 5;
+declare const DEFAULT_PHOTO_SIZE_MB = 10;
+declare const MAX_PHOTO_SIZE_MB = 25;
+/** The longest reference id and file name a photo answer may carry. */
+declare const MAX_PHOTO_ID_LENGTH = 200;
+declare const MAX_PHOTO_NAME_LENGTH = 255;
+declare const isPhotoFormat: (v: unknown) => v is PhotoFormat;
+interface PhotoLimits {
+    maxFiles: number;
+    maxSizeMb: number;
+    maxBytes: number;
+    formats: PhotoFormat[];
+    /** Every MIME type the formats cover. */
+    mimeTypes: string[];
+}
+/** A photo field's limits; a prop that is missing or out of range uses its default. */
+declare function photoLimits(field: FieldBlock): PhotoLimits;
+/** Whether `v` has a photo reference's shape (any type and size). */
+declare function isPhotoRef(v: unknown): v is PhotoRef;
+/** The well-formed references in a photo answer, as `{ id, name, type, size }` only. */
+declare function photoRefs(value: Json | undefined): PhotoRef[];
+/** "JPEG, PNG or WebP". */
+declare function photoFormatList(formats: readonly PhotoFormat[]): string;
+/** The message for a file of a type the field doesn't take. */
+declare const photoTypeMessage: (field: FieldBlock) => string;
+/** The message for a file over the field's size limit. */
+declare const photoSizeMessage: (field: FieldBlock) => string;
+/** The message for more photos than the field takes. */
+declare const photoCountMessage: (field: FieldBlock) => string;
 
 /** A field block that remembers its key and value type, for answer inference. */
 type FieldSpec<K extends string = string, V = unknown> = FieldBlock & {
@@ -24,10 +83,24 @@ interface FieldOptions {
     id?: string | undefined;
 }
 interface ChoiceFieldOptions<O extends string> extends FieldOptions {
-    options: readonly {
+    /** The options. Optional only with `optionsFrom`, whose options follow these. */
+    options?: readonly {
         value: O;
         label?: string;
-    }[];
+    }[] | undefined;
+    /**
+     * Options the app showing the form supplies, by key (`OptionsSource`), such
+     * as `{ source: "host", key: "coaches" }`; pass the lists as `hostOptions`
+     * to `createForm` and `validateSubmission`.
+     */
+    optionsFrom?: OptionsSource | undefined;
+    /**
+     * An "Other" option the respondent fills in (`true`, or `{ label }` to name it): their text is
+     * the answer (one more item on a multiple choice). See `otherOption`.
+     */
+    other?: boolean | {
+        label?: string;
+    } | undefined;
 }
 interface HiddenOptions {
     source?: HiddenInput["source"] | undefined;
@@ -137,6 +210,16 @@ declare const f: {
         quote: string;
         note: string;
     }[]>;
+    /**
+     * Up to a few photos (a picture of broken equipment). The answer holds the
+     * references the host's upload returned, never the bytes; `formats` from
+     * jpeg, png, heic and webp (default all four).
+     */
+    photo: <K extends string>(key: K, o: FieldOptions & {
+        maxFiles?: number | undefined;
+        maxSizeMb?: number | undefined;
+        formats?: readonly PhotoFormat[] | undefined;
+    }) => FieldSpec<K, PhotoRef[]>;
     /** Any registered field type, including plugins. */
     custom: <K extends string, V = Json>(type: string, key: K, o: FieldOptions & {
         props?: Record<string, Json>;
@@ -333,76 +416,38 @@ declare function computePath(def: FormDefinition, scope: EvalScope): PathResult;
 declare function ruleVisible(def: FormDefinition, blockId: string, scope: EvalScope): boolean;
 
 /**
- * A field type, without any UI. Renderers are registered separately per
- * platform (`genesis-forms-react`), so a manifest runs anywhere.
+ * How far a respondent has got, for saving answers as they go
+ * (`settings.saveProgress`) and for drop-off by question. Pure: reads a form's
+ * state, never changes it.
  */
-interface FieldTypeManifest {
-    type: string;
-    label: string;
-    category: "text" | "choice" | "scale" | "date" | "media" | "advanced";
-    /** `json: false` types must convert, so drafts and server replay never lose an answer. */
-    value: {
-        json: true;
-    } | {
-        json: false;
-        serialize: (value: unknown) => Json;
-        deserialize: (json: Json) => unknown;
-    };
-    operators: Operator[];
-    a11y: {
-        semantics: "control" | "group";
-        /** The HTML `autocomplete` token, such as `"email"` or `"tel"`. */
-        autocomplete?: string;
-        /** The HTML `inputmode` hint for on-screen keyboards, such as `"email"` or `"tel"`. */
-        inputMode?: "text" | "email" | "tel" | "numeric" | "decimal" | "url" | "search";
-    };
-    isEmpty?: (value: Json | undefined) => boolean;
-    /** Return an error message, or null when the (non-empty) value is valid. */
-    validate?: (value: Json, field: FieldBlock) => string | null;
-    /** Plain text for recall, exports and emails. */
-    summarize?: (value: Json, field: FieldBlock) => string;
+
+interface FormProgress {
     /**
-     * The form a (valid, non-empty) value is stored in, such as an email
-     * without surrounding spaces. Applied by `engine.answers()` and the server.
+     * The furthest block reached, 1-based, on the path as it is now (logic can
+     * lengthen or shorten the path, so store `fieldId`, not this). 0 before any.
      */
-    normalize?: (value: Json, field: FieldBlock) => Json;
-    /** Valid example answers, used by `coverage()` and other test tools to explore a path. */
-    samples?: (field: FieldBlock) => Json[];
-}
-declare function registerFieldType(manifest: FieldTypeManifest): void;
-declare function getFieldType(type: string): FieldTypeManifest | undefined;
-declare function listFieldTypes(): FieldTypeManifest[];
-declare function isEmptyValue(value: Json | undefined, field?: FieldBlock): boolean;
-/** A value in its stored form (see `FieldTypeManifest.normalize`). */
-declare function normalizeValue(value: Json, field: FieldBlock): Json;
-/** Whether a block holds personal or secret data: `sensitive: true`, or the `props.sensitive: true` alias. */
-declare function isSensitive(block: Block): boolean;
-declare function summarizeValue(value: Json | undefined, field: FieldBlock): string;
-interface ChoiceOption {
-    value: string;
-    label?: string;
+    step: number;
+    /** How many blocks the path has now. */
+    total: number;
+    /**
+     * The id of the furthest question (field) reached: shown in focus layout, or
+     * answered. Null before any. A content block on the way is not a question,
+     * so the question before it counts.
+     */
+    fieldId: string | null;
 }
-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;
-};
+/**
+ * The furthest block on the path the respondent has reached: the one on screen,
+ * one they went back from, or (in classic layout, where every question shows at
+ * once) the last one they answered. Null when the path is empty.
+ */
+declare function furthestReached(state: FormState, definition: FormDefinition): string | null;
+/**
+ * Where the respondent is: the furthest step and the furthest question reached.
+ * What genesis-forms-web's `onProgress` passes; `engine.answers()` has the
+ * answers so far.
+ */
+declare function formProgress(engine: Pick<FormEngine, "definition" | "getState">): FormProgress;
 
 declare function listLimits(field: FieldBlock): {
     min: number;
@@ -676,4 +721,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, 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_FORM_FORMULA_LENGTH, MAX_HIDDEN_STRING_LENGTH, MAX_HIGHLIGHT_NOTE_LENGTH, MAX_HIGHLIGHT_QUOTE_LENGTH, MAX_SETTLE_ITEMS, 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 };
+export { type AnswersOf, Block, CALCULATED_TYPE, COMPUTED_FIELD_TYPES, type CalculatedFormat, type CalculatedProps, type ChoiceFieldOptions, type CoerceHiddenOptions, type CoercedHidden, Condition, ContentBlock, DEFAULT_PHOTO_FILES, DEFAULT_PHOTO_SIZE_MB, Ending, type ExplainInput, type ExplainOptions, type Explanation, FORMULA_FUNCTIONS, FieldBlock, type FieldOptions, type FieldSpec, type FieldValidation, FieldValidator, type Form, FormDefinition, FormEngine, type FormInput, type FormIssue, FormLayout, type FormProgress, FormSettings, FormState, 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_FORM_FORMULA_LENGTH, MAX_HIDDEN_STRING_LENGTH, MAX_HIGHLIGHT_NOTE_LENGTH, MAX_HIGHLIGHT_QUOTE_LENGTH, MAX_PHOTO_FILES, MAX_PHOTO_ID_LENGTH, MAX_PHOTO_NAME_LENGTH, MAX_PHOTO_SIZE_MB, MAX_SETTLE_ITEMS, MAX_TABLE_CELL_LENGTH, MAX_TABLE_COLUMNS, MAX_TIMESTAMP_SECONDS, type MediaNote, OptionsSource, PHOTO_FORMATS, PHOTO_TYPE, PageBreakBlock, type ParseResult, type PathResult, type PhotoFormat, type PhotoLimits, type PhotoRef, type RuleSpec, type RuleTrace, STRUCTURED_FIELD_TYPES, type TableColumn, UPLOAD_FIELD_TYPES, calculatedProps, calculatedValue, canonicalJson, coerceHidden, coerceHiddenValue, computePath, defineForm, describeCondition, evaluate, evaluateFormula, explain, f, fingerprint, formProgress, formatCalculated, formatTimestamp, formulaInput, formulaNumber, formulaRefs, furthestReached, isPhotoFormat, isPhotoRef, listLimits, parseForm, parseFormula, parseTimestamp, photoCountMessage, photoFormatList, photoLimits, photoRefs, photoSizeMessage, photoTypeMessage, recall, renameFormulaKey, ruleVisible, steps, tableColumns, tableLimits, when };