@marktiderman/genesis-forms 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,374 @@
+import { F as FieldBlock, C as ContentBlock, P as PageBreakBlock, a 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, e as FieldValidator } from './validate-j8Z188mF.js';
+export { f as FormEvent, g as Operand, R as REQUIRED_MESSAGE, S as StandardSchemaV1, v as validateField } from './validate-j8Z188mF.js';
+import { F as FormEngine } from './engine-Cp5t2_Am.js';
+export { C as CreateFormOptions, a as FormState, c as createForm, i as isFormEvent, b as isJson, r as replay } from './engine-Cp5t2_Am.js';
+
+/** A field block that remembers its key and value type, for answer inference. */
+type FieldSpec<K extends string = string, V = unknown> = FieldBlock & {
+    readonly key: K;
+    /** Type-level only. */
+    readonly __value?: V;
+};
+interface FieldOptions {
+    label: string;
+    description?: string;
+    placeholder?: string;
+    required?: boolean;
+    /** Personal or secret data (see `isSensitive`). */
+    sensitive?: boolean;
+    /** Identifies the respondent (name, email, phone). Not asked when `settings.anonymous` is true. */
+    identifying?: boolean;
+    /** Defaults to the key. Set it before renaming a key on a live form, so answers stay linked. */
+    id?: string;
+}
+interface ChoiceFieldOptions<O extends string> extends FieldOptions {
+    options: readonly {
+        value: O;
+        label?: string;
+    }[];
+}
+interface HiddenOptions {
+    source?: HiddenInput["source"];
+    sensitive?: boolean;
+}
+declare const f: {
+    shortText: <K extends string>(key: K, o: FieldOptions & {
+        maxLength?: number;
+    }) => FieldSpec<K, string>;
+    longText: <K extends string>(key: K, o: FieldOptions & {
+        maxLength?: number;
+    }) => 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>;
+    rating: <K extends string>(key: K, o: FieldOptions & {
+        max?: number;
+    }) => 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>;
+    /** Any registered field type, including plugins. */
+    custom: <K extends string, V = Json>(type: string, key: K, o: FieldOptions & {
+        props?: Record<string, Json>;
+    }) => FieldSpec<K, V>;
+    heading: (id: string, text: string) => ContentBlock;
+    text: (id: string, text: string) => ContentBlock;
+    pageBreak: (id: string, title?: string) => PageBreakBlock;
+    hidden: {
+        string: (o?: HiddenOptions) => {
+            sensitive?: true | undefined;
+            type: "string";
+            source: "url" | "host" | "server";
+        };
+        number: (o?: HiddenOptions) => {
+            sensitive?: true | undefined;
+            type: "number";
+            source: "url" | "host" | "server";
+        };
+        boolean: (o?: HiddenOptions) => {
+            sensitive?: true | undefined;
+            type: "boolean";
+            source: "url" | "host" | "server";
+        };
+    };
+};
+/**
+ * Resolves a field key to its id. `"target"` (a show/hide target or a jump
+ * destination) also accepts the id of a content block.
+ */
+type KeyResolver = (key: string, as?: "field" | "target") => string;
+/** A rule written with field keys; `defineForm` resolves keys to ids. */
+interface RuleSpec {
+    readonly __rule: true;
+    build(resolve: KeyResolver, id: string): LogicRule;
+}
+type Effects = {
+    /** Show a field (by key) or a content block (by id). */
+    show(targetKey: string): RuleSpec;
+    /** Hide a field (by key) or a content block (by id). */
+    hide(targetKey: string): RuleSpec;
+    /** Jump from this field to a later field or content block, or to an ending. */
+    jumpTo(target: string | {
+        ending: string;
+    }): RuleSpec;
+};
+/** Start a rule on a field: `when("overall").lessThan(4).jumpTo("improve")`. */
+declare function when(key: string): {
+    is: (value: Json) => Effects;
+    isNot: (value: Json) => Effects;
+    lessThan: (n: number) => Effects;
+    atMost: (n: number) => Effects;
+    greaterThan: (n: number) => Effects;
+    atLeast: (n: number) => Effects;
+    isOneOf: (values: Json[]) => Effects;
+    includes: (value: Json) => Effects;
+    isAnswered: () => Effects;
+    isEmpty: () => Effects;
+};
+declare namespace when {
+    var condition: (condition: Condition, from?: string) => Effects;
+}
+type HiddenSpec = {
+    type: HiddenInput["type"];
+    source: HiddenInput["source"];
+    sensitive?: boolean;
+};
+type HiddenValue<T extends HiddenSpec["type"]> = T extends "number" ? number : T extends "boolean" ? boolean : string;
+type AnyBlock = FieldSpec<string, unknown> | ContentBlock | PageBreakBlock;
+type AnswersOf<B extends readonly AnyBlock[]> = {
+    [E in B[number] as E extends FieldSpec<infer K, unknown> ? K : never]?: E extends FieldSpec<string, infer V> ? V : never;
+};
+interface FormInput<B extends readonly AnyBlock[], H extends Record<string, HiddenSpec>> {
+    id: string;
+    title: string;
+    description?: string;
+    layout?: FormLayout;
+    /** Authoring sugar: a map of name → spec. Normalized to the canonical array. */
+    hidden?: H;
+    blocks: B;
+    logic?: RuleSpec[];
+    endings?: Ending[];
+    settings?: FormSettings;
+    meta?: Record<string, Json>;
+}
+interface Form<A = Record<string, unknown>, H = Record<string, unknown>> {
+    readonly definition: FormDefinition;
+    /** The canonical JSON, identical to what a builder would produce. */
+    toJSON(): FormDefinition;
+    /** Content fingerprint of the canonical JSON. */
+    hash(): string;
+    /** Type-level only: the answers, keyed by field key. */
+    readonly $answers: A;
+    /** Type-level only: the hidden inputs. */
+    readonly $hidden: H;
+}
+/**
+ * Define a form in code. The result's `definition` is the same canonical JSON
+ * a builder or `parseForm` produces; answer types are inferred from the blocks.
+ */
+declare function defineForm<const B extends readonly AnyBlock[], H extends Record<string, HiddenSpec> = Record<never, HiddenSpec>>(input: FormInput<B, H>): Form<AnswersOf<B>, {
+    [K in keyof H]?: HiddenValue<H[K]["type"]>;
+}>;
+
+interface FormIssue {
+    path: string;
+    message: string;
+}
+type ParseResult = {
+    ok: true;
+    form: FormDefinition;
+    warnings: FormIssue[];
+} | {
+    ok: false;
+    issues: FormIssue[];
+    warnings: FormIssue[];
+};
+/**
+ * Check a definition before it is stored or rendered: structure, the types of
+ * text fields, unique ids and keys, known field types, references that
+ * resolve, operators that fit the field type. Warnings flag things that work
+ * but are probably mistakes. Never throws, whatever the input.
+ */
+declare function parseForm(input: unknown): ParseResult;
+
+/** Longest string a hidden input accepts. Longer values are dropped. */
+declare const MAX_HIDDEN_STRING_LENGTH = 1000;
+interface CoerceHiddenOptions {
+    /** Coerce only inputs with these sources; the rest are reported in `ignored`. Default: all. */
+    sources?: readonly HiddenInput["source"][];
+}
+interface CoercedHidden {
+    /** Declared inputs, typed. */
+    values: Record<string, Json>;
+    /** Names dropped: undeclared, from another source, or not convertible to the declared type. */
+    ignored: string[];
+}
+/**
+ * Convert one raw value to a hidden input's declared type, or `undefined` when
+ * it cannot be. Only string, number and boolean primitives are accepted.
+ * - `string`: a string (at most 1000 characters), or a number or boolean as text.
+ * - `number`: a finite number, or a non-blank numeric string. `""` is not a number.
+ * - `boolean`: `true`/`false`, or the strings `"true"`/`"false"`.
+ */
+declare function coerceHiddenValue(value: unknown, type: HiddenInput["type"]): Json | undefined;
+/**
+ * Type raw hidden inputs (from a query string, the host app or the server)
+ * by the definition's declarations. `undefined` values are skipped silently.
+ */
+declare function coerceHidden(definition: FormDefinition, raw: Record<string, unknown> | undefined, options?: CoerceHiddenOptions): CoercedHidden;
+
+interface EvalScope {
+    values: Record<string, Json | undefined>;
+    hidden: Record<string, Json | undefined>;
+    fields: Map<string, FieldBlock>;
+}
+/**
+ * Evaluate a condition. Never throws. An empty value (unanswered, `null`,
+ * blank text, an empty list: see `isEmptyValue`) is unanswered: it fails
+ * every comparison, including `eq`, `in` and `contains`, and passes `neq`.
+ */
+declare function evaluate(condition: Condition, scope: EvalScope): boolean;
+/** Blocks a respondent steps through: fields and content, in order. */
+declare function steps(def: FormDefinition): Block[];
+interface PathResult {
+    /** Block ids the respondent will step through, given the answers on the path. */
+    path: string[];
+    /** The ending reached by a jump, or the default ending. */
+    ending: string | null;
+}
+/**
+ * The respondent's path, derived from the answers on the path, so the client,
+ * the server and a replay always agree. It is built in one forward pass: a
+ * block's show/hide rules, and the jumps from it, see only the fields already
+ * on the path before it (and, for a jump, the block itself). A field that is
+ * hidden, jumped over or later in the form reads as unanswered, whatever
+ * value it holds.
+ *
+ * A block jumped over is off the path and counts as hidden: it is not
+ * validated and its value is cleared on submit. A jump never revisits a block;
+ * a jump to an earlier block is ignored (the checker in `parseForm` reports it).
+ */
+declare function computePath(def: FormDefinition, scope: EvalScope): PathResult;
+/**
+ * Whether a block's show/hide rules let it be shown, ignoring jumps. The rules
+ * read the answers on the path before the block, as in `computePath`. A block
+ * with any `show` rule is hidden until one matches; a matching `hide` rule
+ * always wins.
+ */
+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.
+ */
+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;
+    /**
+     * The form a (valid, non-empty) value is stored in, such as an email
+     * without surrounding spaces. Applied by `engine.answers()` and the server.
+     */
+    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;
+}
+declare function choiceOptions(field: FieldBlock): ChoiceOption[];
+
+interface RecallScope {
+    /** Fields by key. */
+    fieldsByKey: Map<string, FieldBlock>;
+    values: Record<string, Json | undefined>;
+    hidden: Record<string, Json | undefined>;
+}
+/**
+ * Replace `{{field:key|fallback}}` and `{{hidden:name|fallback}}` tokens.
+ * An unanswered value renders its fallback (default empty); the text is
+ * never dropped.
+ */
+declare function recall(text: string, scope: RecallScope): string;
+
+/** JSON with object keys sorted, so equal definitions serialize identically. */
+declare function canonicalJson(value: unknown): string;
+/**
+ * A short content fingerprint (cyrb53, 14 hex characters). It detects drift
+ * between a definition and its published version; it is not a security hash.
+ */
+declare function fingerprint(value: Json | object): string;
+
+/**
+ * "Why is this hidden?" A structured trace of one block's visibility, for
+ * devtools and tests. Pure: it reads a definition and values, never an engine's
+ * internals, so it explains a stored response as well as a live one.
+ */
+
+interface ExplainInput {
+    definition: FormDefinition;
+    values: Record<string, Json | undefined>;
+    hidden?: Record<string, Json | undefined>;
+}
+interface RuleTrace {
+    ruleId: string;
+    effect: "show" | "hide";
+    /** The rule's condition, evaluated against the current values. */
+    matched: boolean;
+    /** "Hidden because contact_me is not Yes." */
+    sentence: string;
+}
+interface JumpTrace {
+    ruleId: string;
+    /** Block id the jump fired from. */
+    from: string;
+    to: string | {
+        ending: string;
+    };
+    sentence: string;
+}
+interface FieldValidation {
+    /** `not-checked`: the field is hidden, so it is neither validated nor stored. */
+    status: "valid" | "invalid" | "unanswered" | "not-checked";
+    message?: string;
+}
+interface Explanation {
+    blockId: string;
+    /** The field key, or the block id for content. */
+    key: string;
+    kind: "field" | "content" | "page-break";
+    /** On the respondent's path given the answers so far. */
+    onPath: boolean;
+    /** Visible by show/hide rules alone (ignoring jumps). */
+    ruleVisible: boolean;
+    /** What the respondent sees: on the path and rule-visible. */
+    visible: boolean;
+    /** The jump that carried the path past this block, if any. */
+    skippedBy?: JumpTrace;
+    /** Every show/hide rule targeting this block, in definition order. */
+    rules: RuleTrace[];
+    /** Fields only. */
+    validation?: FieldValidation;
+    /** One plain-English line: the main reason. */
+    summary: string;
+}
+interface ExplainOptions {
+    validators?: Record<string, FieldValidator>;
+}
+/** Explain a block's visibility. `blockId` may also be a field key. */
+declare function explain(source: FormEngine | ExplainInput, blockId: string, options?: ExplainOptions): Explanation;
+/** 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, HiddenInput, Json, type JumpTrace, type KeyResolver, LogicRule, MAX_HIDDEN_STRING_LENGTH, Operator, PageBreakBlock, type ParseResult, type PathResult, type RuleSpec, type RuleTrace, canonicalJson, choiceOptions, coerceHidden, coerceHiddenValue, computePath, defineForm, describeCondition, evaluate, explain, f, fingerprint, getFieldType, isEmptyValue, isSensitive, listFieldTypes, normalizeValue, parseForm, recall, registerFieldType, ruleVisible, steps, summarizeValue, when };