@jarenjs/forms 0.9.2 → 0.34.0

package/dist/types/rules.d.ts

@@ -12,11 +12,26 @@ export type RuleResult = {
      */
     computed?: any;
     /**
-     * `[{ keyword: 'x-form/assert', message }]` when the `assert` rule fails
-     * (the validateField error shape, so error rendering works unchanged)
+     * `[{ keyword: 'x-form/assert', params, msgid, message }]` when the
+     * `assert` rule fails (the validateField error shape, so error
+     * rendering works unchanged; `params` always carries the `pointer`)
      */
     errors?: Array<import('./validate.js').FieldError>;
 };
+export type CompiledRuleMessage = {
+    /**
+     * - Catalog key, or null for a plain inline message
+     */
+    msgid: string | null;
+    /**
+     * - Compiled inline template
+     */
+    render: ((params: object) => string) | null;
+    /**
+     * - Author params, merged into the error's params
+     */
+    params: object | null;
+};
 export type CompiledFieldRules = {
     /**
      * - The field's data pointer (template pointers keep `-`)
@@ -38,23 +53,16 @@ export type CompiledFieldRules = {
     enabled: Function | null;
     assert: Function | null;
     computed: Function | null;
-    message: string | null;
+    message: CompiledRuleMessage | null;
+    /**
+     * - Pointer prefixes this rule reads (deps.js);
+     * the memo re-runs it only when a change touches one of them
+     */
+    deps: string[];
 };
 export type CompiledRules = {
     rules: Array<CompiledFieldRules>;
 };
-/**
- * @typedef {object} CompiledFieldRules
- * @property {string} pointer - The field's data pointer (template pointers keep `-`)
- * @property {Array<string|symbol>} parts - Decoded segments; ITEM marks an array-item slot
- * @property {boolean} templated - Whether `parts` contains an ITEM slot
- * @property {((root: any) => any)|null} getValue - Compiled getter (non-template fields)
- * @property {function|null} visible
- * @property {function|null} enabled
- * @property {function|null} assert
- * @property {function|null} computed
- * @property {string|null} message
- */
 /**
  * @typedef {object} CompiledRules
  * @property {Array<CompiledFieldRules>} rules
@@ -92,14 +100,98 @@ export declare function compileFormRules(model: import('./model.js').FormField,
  * field declares. Rules on array item templates are evaluated once per
  * element of the actual array, keyed by the expanded pointer.
  *
+ * Pass a `memo` from {@link createRuleMemo} to re-evaluate only the
+ * rules a change can have affected. The memo diffs the previous
+ * document against this one — reference-equal subtrees are skipped
+ * whole, so an immutable edit costs O(change) — and re-runs a rule only
+ * when a changed pointer touches one of its declared dependencies
+ * (deps.js). The result is identical to an unmemoized evaluation.
+ *
+ * The memo OWNS the map it returns and patches it on later calls: a
+ * caller must read it before evaluating again, and must not keep it as
+ * a snapshot (`buildFormViewModel` reads it synchronously, which is the
+ * intended shape). Handing back a fresh map instead would put a write
+ * per rule back on the hot path — on a wide form, the rules that did
+ * NOT change are the work worth skipping.
+ *
  * @param {CompiledRules} compiled - From compileFormRules
  * @param {any} data - The form data root (the query input `$`)
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>} [catalog] - Optional compiled message catalog (see messages.js), default English
+ * @param {RuleMemo} [memo] - Reused across calls; mutated in place
  * @returns {Record<string, RuleResult>}
  * @example
  * const results = evaluateFormRules(compiled, { company: 'ACME', vatId: '' });
  * results['/vatId'].errors; // [{ keyword: 'x-form/assert', message: '...' }]
  */
-export declare function evaluateFormRules(compiled: CompiledRules, data: any): Record<string, RuleResult>;
+export declare function evaluateFormRules(compiled: CompiledRules, data: any, catalog?: Readonly<Record<string, (params: object, error?: object) => string>>, memo?: RuleMemo): Record<string, RuleResult>;
+export type RuleMemo = {
+    data: any;
+    catalog: any;
+    results: Record<string, RuleResult> | null;
+    keys: string[][] | null;
+    /**
+     * - Pointers declared through
+     * {@link RuleMemo.touch}, consumed by the next evaluation
+     */
+    touched: string[] | null;
+    touch: (pointer: string) => RuleMemo;
+};
+/**
+ * The memo {@link evaluateFormRules} carries between keystrokes: the
+ * document it last saw, the results it produced, and which result keys
+ * each rule wrote (an item-template rule writes one per element, so the
+ * count is data-dependent and has to be recorded, not derived).
+ * @typedef {object} RuleMemo
+ * @property {any} data
+ * @property {any} catalog
+ * @property {Record<string, RuleResult>|null} results
+ * @property {string[][]|null} keys
+ * @property {string[]|null} touched - Pointers declared through
+ *   {@link RuleMemo.touch}, consumed by the next evaluation
+ * @property {(pointer: string) => RuleMemo} touch
+ */
+/**
+ * Create an empty rule memo. One per form session: it is bound to the
+ * document lineage it has seen, so sharing it between two forms would
+ * diff unrelated documents (correct, but pointlessly expensive).
+ *
+ * `memo.touch(pointer)` declares a write before the next evaluation.
+ * It is an optimization AND a promise: the evaluation then trusts the
+ * declaration instead of diffing, so a caller that touches one pointer
+ * while changing another gets stale results for the rules it did not
+ * name. Say nothing and the diff works it out.
+ * @returns {RuleMemo}
+ * @example
+ * const memo = createRuleMemo();
+ * data = setValueAtPointer(data, '/lines/2/amount', 9);
+ * const state = evaluateFormRules(compiled, data, catalog, memo.touch('/lines/2/amount'));
+ */
+export declare function createRuleMemo(): RuleMemo;
+/**
+ * Drop the values of fields their `visible` rules currently hide, for a
+ * caller about to submit.
+ *
+ * The policy this settles: hidden values are KEPT while editing (a
+ * field that reappears must not have forgotten what the operator typed)
+ * and dropped only here, at the submit boundary, by a caller who asked.
+ * Nothing prunes implicitly — `buildFormViewModel` still never touches
+ * the data, and this returns a copy.
+ *
+ * Visibility is evaluated ONCE against the incoming document, so a
+ * `visible` rule that reads a value this call removes still sees it.
+ * Hidden array ELEMENTS are removed and their siblings renumber, which
+ * is right for a document being sent but means the returned pointers no
+ * longer match the ones the view model rendered.
+ *
+ * @param {CompiledRules} compiled - From compileFormRules
+ * @param {any} data - The form data root
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>} [catalog]
+ * @returns {any} A copy without the hidden values (`data` itself when
+ *   nothing is hidden; untouched subtrees are shared)
+ * @example
+ * const submitted = pruneHiddenValues(compiled, session.data);
+ */
+export declare function pruneHiddenValues(compiled: CompiledRules, data: any, catalog?: Readonly<Record<string, (params: object, error?: object) => string>>): any;
 /**
  * Copy every `x-form.assert` of a schema into a `$query` assertion, so a
  * rule authored once for per-keystroke feedback is also enforced by the
@@ -107,23 +199,43 @@ export declare function evaluateFormRules(compiled: CompiledRules, data: any): R
  * Pure schema-to-schema transform - no validator import; the output only
  * spells the keyword.
  *
- * The `$query` lands on the ROOT schema (where the query input `$` is the
- * instance root, matching the rule context), with each assert wrapped to
- * rebuild its bindings: `value` binds to the field's location, `pointer`
- * to its pointer string. An assert on an array item template quantifies
- * with `$every` over the actual elements (`pointer` then stays the
- * template pointer - element indexes are a render-time notion). Multiple
- * asserts conjoin under `$and`; an existing root `$query` is preserved by
- * wrapping the new one in an `allOf` branch.
+ * The asserts land on the ROOT schema (where the query input `$` is the
+ * instance root, matching the rule context), each as its OWN `allOf`
+ * branch `{ "$query": <wrapped>, "errorMessage": { "$query": <spec> } }`
+ * so per-assert identity - and the rule's authored message - survives
+ * into submit validation. Each assert is wrapped to rebuild its bindings:
+ * `value` binds to the field's location, `pointer` to its pointer string.
+ * An assert on an array item template quantifies with `$every` over the
+ * actual elements (`pointer` then stays the template pointer - element
+ * indexes are a render-time notion). An existing root `$query` is left
+ * untouched on the root itself.
+ *
+ * The carried message spec is the rule's `x-form.message` - inline string
+ * as an inline `message`, `$msgid` form passed through - with `params`
+ * merged over `{ pointer: <field pointer> }`; a rule with no message gets
+ * `{ "$msgid": "x-form/assert", "params": { "pointer": ... } }`. EVERY
+ * submit-time `$query` failure therefore carries the owning field's
+ * pointer in `params`, which lets UIs map root-level `$query` errors onto
+ * fields.
  *
  * The transform follows the same structural spine as buildFormModel
  * (`properties`, `items`, `prefixItems`, `allOf`) but does not resolve
  * `$ref`s - a `$def`'s data location depends on its use site.
  *
+ * Absent fields bind exactly as they do per keystroke: `null`. A path
+ * that selects nothing is the empty sequence, which compares unequal to
+ * everything and would make `$ne`/`$eq` mean the opposite thing on the
+ * two sides of the same authored rule - so the binding is wrapped in a
+ * `$default` against `null`. For the same reason an item-template
+ * assert quantifies over the ELEMENTS rather than over the selected
+ * leaf values: quantifying over the leaves silently skips an element
+ * that lacks the member, where the keystroke path evaluates it with
+ * `null`.
+ *
  * @param {object|boolean} schema - The root JSON schema
  * @returns {object|boolean} A new root schema (input is not mutated;
- *   untouched subtrees are shared) with the collected `$query`, or the
- *   input itself when there is nothing to copy
+ *   untouched subtrees are shared) with the collected `$query` branches,
+ *   or the input itself when there is nothing to copy
  * @example
  * const submitSchema = formRulesToQueryAssertions(schema);
  * const validate = new JarenValidator().compile(submitSchema); // caller-side

package/dist/types/validate.d.ts

@@ -4,7 +4,15 @@ export type FieldError = {
      */
     keyword: string;
     /**
-     * - Human readable message
+     * - Structured, keyword-specific parameters
+     */
+    params: object;
+    /**
+     * - Stable message key (`form/<keyword>` or `x-form/assert`)
+     */
+    msgid: string;
+    /**
+     * - Human readable message (rendered through a catalog)
      */
     message: string;
 };
@@ -13,17 +21,20 @@ export type FieldError = {
  *
  * @param {import('./model.js').FormField} field - Field from buildFormModel
  * @param {any} value - The TYPED value (see parseFieldInput); undefined = absent
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>} [catalog] - Optional compiled message catalog (see messages.js), default English
  * @returns {FieldError[]} Empty when the value passes every per-field check
  * @example
  * const errors = validateField(emailField, 'not-an-email');
- * // [{ keyword: 'format', message: 'Must be a valid email' }]
+ * // [{ keyword: 'format', params: { format: 'email' },
+ * //    msgid: 'form/format', message: 'Must be a valid email' }]
  */
-export declare function validateField(field: import('./model.js').FormField, value: any): FieldError[];
+export declare function validateField(field: import('./model.js').FormField, value: any, catalog?: Readonly<Record<string, (params: object, error?: object) => string>>): FieldError[];
 /**
  * Validate every leaf field of a model against the current data.
  * Returns a map of data-pointer -> FieldError[] for fields that fail.
  * @param {import('./model.js').FormField} model - Root field from buildFormModel
  * @param {any} data - Current form data
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>} [catalog] - Optional compiled message catalog, default English
  * @returns {Record<string, FieldError[]>}
  */
-export declare function validateAllFields(model: import('./model.js').FormField, data: any): Record<string, FieldError[]>;
+export declare function validateAllFields(model: import('./model.js').FormField, data: any, catalog?: Readonly<Record<string, (params: object, error?: object) => string>>): Record<string, FieldError[]>;

package/dist/types/viewmodel.d.ts

@@ -0,0 +1,373 @@
+/**
+ * @file The form view model — the render tree.
+ *
+ * `buildFormViewModel` composes everything this package knows about a
+ * form at one instant — the field tree (model.js), the current data,
+ * per-field validation (validate.js) and `x-form` rule state (rules.js)
+ * — into ONE plain-JSON tree of render nodes. It is the "computed view"
+ * layer the package README promised: no DOM, no framework, just the
+ * document any renderer needs — a React component, a template engine,
+ * or a JSLT stylesheet (the standard form rules of `@jarenjs/app`
+ * dispatch over exactly this shape).
+ *
+ * Policies inherited from rules.js: a field whose rule state says
+ * `visible: false` is EXCLUDED from the tree (renderers cannot leak
+ * hidden data by accident); `enabled` and `computed` are carried on the
+ * node. Array item templates expand per element of the actual data, so
+ * node pointers are always concrete (`/lines/2/amount`), matching the
+ * pointer keys of `evaluateFormRules` and `validateAllFields`.
+ */
+export type FormField = import('./model.js').FormField;
+export type FormViewNode = {
+    /**
+     * - Concrete data pointer ('' for the root).
+     */
+    pointer: string;
+    /**
+     * - Property name, or the element index as a string.
+     */
+    key: string;
+    label: string;
+    description: string | null;
+    /**
+     * - The field kind (model.js).
+     */
+    kind: string;
+    /**
+     * - The rendering hint (model.js).
+     */
+    control: string;
+    required: boolean;
+    readOnly: boolean;
+    /**
+     * - `x-form.enabled`, defaulting true.
+     */
+    enabled: boolean;
+    placeholder: string | null;
+    /**
+     * - The current value (`x-form.computed` wins);
+     * `null` when the field is absent from the data.
+     */
+    value: any;
+    /**
+     *   Select options, `selected` precomputed against the current value.
+     *   `key` is the option's value as JSON text — what a string-valued
+     *   control (a DOM `<option>`) can carry and hand back losslessly.
+     */
+    options: Array<{
+        value: any;
+        key: string;
+        label: string;
+        selected: boolean;
+    }> | null;
+    /**
+     * - The value as indented JSON text, on
+     * `json`-control nodes only: the editable text for a structured
+     * value, precomputed like `options`.
+     */
+    json?: string;
+    /**
+     * - Localized messages: field validation
+     * first, then rule asserts.
+     */
+    errors: string[];
+    /**
+     * - True when this node is an array element
+     * (item or tuple slot). Writers need this: RFC 6902 `add` is
+     * set-or-replace for object members but INSERT for array indices, so
+     * element nodes must be written with `replace`.
+     */
+    element: boolean;
+    /**
+     * - True for item-template elements
+     * (tuple slots are fixed).
+     */
+    removable: boolean;
+    /**
+     * - Object members.
+     */
+    children: FormViewNode[] | null;
+    /**
+     * - Array elements, expanded.
+     */
+    items: FormViewNode[] | null;
+    /**
+     * - Starter value for a new array item
+     * (`createItemValue`); only on array nodes with an item template.
+     */
+    addValue: any;
+    /**
+     * - Stable accessible element id derived from
+     * the pointer (session forms only).
+     */
+    id?: string;
+    /**
+     * - The id of this node's error
+     * text (`aria-describedby` wiring), `null` when the node has no
+     * errors (session forms only).
+     */
+    describedBy?: string | null;
+    /**
+     * - Whether this node's value differs from
+     * the session's initial data — presence-aware: a member added or
+     * removed is dirty even when the compared values coincide as `null`
+     * (session forms only).
+     */
+    dirty?: boolean;
+    /**
+     * - Whether the session marked this
+     * pointer visited (session forms only).
+     */
+    touched?: boolean;
+    /**
+     * - Server-reported messages for
+     * this pointer, kept distinct from the client-side `errors` (session
+     * forms only).
+     */
+    serverErrors?: string[];
+    /**
+     * - The root summary (root
+     * node of session forms only).
+     */
+    session?: FormSessionSummary;
+};
+export type FormSessionOptions = {
+    /**
+     * - The baseline document; each node's
+     * `dirty` is a JSON deep-compare of its value against this.
+     */
+    initial?: any;
+    /**
+     * - Pointers
+     * the operator has visited.
+     */
+    touched?: string[] | Record<string, boolean>;
+    /**
+     * - Whether a submit was attempted;
+     * echoed in the root summary (renderers typically surface every
+     * error once true).
+     */
+    submitted?: boolean;
+    /**
+     * Server-reported messages by JSON Pointer; folded onto the matching
+     * nodes as `serverErrors`, never mixed into the client `errors`.
+     */
+    serverErrors?: Record<string, string | string[]> | Array<{
+        pointer: string;
+        message: string;
+    }>;
+    /**
+     * - The submit task status
+     * (e.g. 'idle'/'pending'/'done'/'error'); echoed in the root summary.
+     */
+    submitStatus?: string | null;
+    /**
+     * - The in-flight submit's request
+     * identity; echoed in the root summary.
+     */
+    requestId?: any;
+    /**
+     * - Prefix for the stable accessible ids
+     * (default 'form'); ids are `<prefix>--<pointer segments joined
+     * with ->` and `'<prefix>--root'` for the root.
+     */
+    idPrefix?: string;
+};
+export type FormSessionSummary = {
+    /**
+     * - Whether the current data differs from the
+     * initial document ANYWHERE.
+     */
+    dirty: boolean;
+    /**
+     * - Every changed pointer between the
+     * initial document and the current data, in diff-walk (document)
+     * order. A member added or removed — including an explicit-`null`
+     * membership change and a shortened array tail — contributes the
+     * pointer of the added/removed location.
+     */
+    dirtyPaths: string[];
+    submitted: boolean;
+    submitStatus: string | null;
+    requestId: any;
+    /**
+     * - Client-side error total.
+     */
+    errorCount: number;
+    /**
+     * - Server-reported error total.
+     */
+    serverErrorCount: number;
+};
+export type FormViewModelOptions = {
+    /**
+     * - Compiled rules from `compileFormRules`;
+     * when given, `x-form` state (visible/enabled/computed/asserts) is
+     * evaluated and folded into the tree.
+     */
+    rules?: object;
+    /**
+     * - Run `validateAllFields` and
+     * fold the per-field errors in (default false: pristine forms show
+     * no errors until the app opts in).
+     */
+    validateFields?: boolean;
+    /**
+     * - Compiled message catalog for error
+     * texts (compileMessageCatalog), default English.
+     */
+    catalog?: object;
+    /**
+     * - A memo from
+     * `createRuleMemo`, reused across calls so only the rules a change
+     * can reach are re-evaluated. Keep one per form session; the tree it
+     * produces is the same either way.
+     */
+    memo?: import('./rules.js').RuleMemo;
+    /**
+     * - Fold a form session
+     * (initial/touched/submitted/serverErrors/submit identity) into the
+     * tree: every node gains `id`/`describedBy`/`dirty`/`touched`/
+     * `serverErrors`, and the root gains a `session` summary. Absent, the
+     * tree is byte-identical to the sessionless shape.
+     */
+    session?: FormSessionOptions;
+};
+/**
+ * One node of the render tree. Everything is plain JSON.
+ * @typedef {Object} FormViewNode
+ * @property {string} pointer - Concrete data pointer ('' for the root).
+ * @property {string} key - Property name, or the element index as a string.
+ * @property {string} label
+ * @property {string|null} description
+ * @property {string} kind - The field kind (model.js).
+ * @property {string} control - The rendering hint (model.js).
+ * @property {boolean} required
+ * @property {boolean} readOnly
+ * @property {boolean} enabled - `x-form.enabled`, defaulting true.
+ * @property {string|null} placeholder
+ * @property {any} value - The current value (`x-form.computed` wins);
+ *   `null` when the field is absent from the data.
+ * @property {Array<{value: any, key: string, label: string, selected: boolean}>|null} options
+ *   Select options, `selected` precomputed against the current value.
+ *   `key` is the option's value as JSON text — what a string-valued
+ *   control (a DOM `<option>`) can carry and hand back losslessly.
+ * @property {string} [json] - The value as indented JSON text, on
+ *   `json`-control nodes only: the editable text for a structured
+ *   value, precomputed like `options`.
+ * @property {string[]} errors - Localized messages: field validation
+ *   first, then rule asserts.
+ * @property {boolean} element - True when this node is an array element
+ *   (item or tuple slot). Writers need this: RFC 6902 `add` is
+ *   set-or-replace for object members but INSERT for array indices, so
+ *   element nodes must be written with `replace`.
+ * @property {boolean} removable - True for item-template elements
+ *   (tuple slots are fixed).
+ * @property {FormViewNode[]|null} children - Object members.
+ * @property {FormViewNode[]|null} items - Array elements, expanded.
+ * @property {any} addValue - Starter value for a new array item
+ *   (`createItemValue`); only on array nodes with an item template.
+ * @property {string} [id] - Stable accessible element id derived from
+ *   the pointer (session forms only).
+ * @property {string|null} [describedBy] - The id of this node's error
+ *   text (`aria-describedby` wiring), `null` when the node has no
+ *   errors (session forms only).
+ * @property {boolean} [dirty] - Whether this node's value differs from
+ *   the session's initial data — presence-aware: a member added or
+ *   removed is dirty even when the compared values coincide as `null`
+ *   (session forms only).
+ * @property {boolean} [touched] - Whether the session marked this
+ *   pointer visited (session forms only).
+ * @property {string[]} [serverErrors] - Server-reported messages for
+ *   this pointer, kept distinct from the client-side `errors` (session
+ *   forms only).
+ * @property {FormSessionSummary} [session] - The root summary (root
+ *   node of session forms only).
+ */
+/**
+ * The submit/draft session of a form: the lifecycle state around one
+ * edited document. Everything is JSON — the
+ * session lives in app state; this option only folds it into the tree.
+ *
+ * Hidden-field policy: fields excluded by `x-form` `visible` rules keep
+ * their values in the data — the view model never prunes; whether a
+ * submit drops them is a product decision made at the submit boundary.
+ *
+ * @typedef {Object} FormSessionOptions
+ * @property {any} [initial] - The baseline document; each node's
+ *   `dirty` is a JSON deep-compare of its value against this.
+ * @property {string[] | Record<string, boolean>} [touched] - Pointers
+ *   the operator has visited.
+ * @property {boolean} [submitted] - Whether a submit was attempted;
+ *   echoed in the root summary (renderers typically surface every
+ *   error once true).
+ * @property {Record<string, string | string[]> | Array<{ pointer: string, message: string }>} [serverErrors]
+ *   Server-reported messages by JSON Pointer; folded onto the matching
+ *   nodes as `serverErrors`, never mixed into the client `errors`.
+ * @property {string | null} [submitStatus] - The submit task status
+ *   (e.g. 'idle'/'pending'/'done'/'error'); echoed in the root summary.
+ * @property {any} [requestId] - The in-flight submit's request
+ *   identity; echoed in the root summary.
+ * @property {string} [idPrefix] - Prefix for the stable accessible ids
+ *   (default 'form'); ids are `<prefix>--<pointer segments joined
+ *   with ->` and `'<prefix>--root'` for the root.
+ */
+/**
+ * The root summary of a session form (`root.session`) — the
+ * navigation-guard authority: derived from a full JSON comparison of
+ * the initial document against the current data, independent of what
+ * is rendered, so removed members, hidden retained values and
+ * missing-versus-`null` membership changes all count. The visible
+ * per-node `dirty`/`errors` members remain the render-layer summary.
+ * @typedef {Object} FormSessionSummary
+ * @property {boolean} dirty - Whether the current data differs from the
+ *   initial document ANYWHERE.
+ * @property {string[]} dirtyPaths - Every changed pointer between the
+ *   initial document and the current data, in diff-walk (document)
+ *   order. A member added or removed — including an explicit-`null`
+ *   membership change and a shortened array tail — contributes the
+ *   pointer of the added/removed location.
+ * @property {boolean} submitted
+ * @property {string | null} submitStatus
+ * @property {any} requestId
+ * @property {number} errorCount - Client-side error total.
+ * @property {number} serverErrorCount - Server-reported error total.
+ */
+/**
+ * Options for `buildFormViewModel`.
+ * @typedef {Object} FormViewModelOptions
+ * @property {object} [rules] - Compiled rules from `compileFormRules`;
+ *   when given, `x-form` state (visible/enabled/computed/asserts) is
+ *   evaluated and folded into the tree.
+ * @property {boolean} [validateFields] - Run `validateAllFields` and
+ *   fold the per-field errors in (default false: pristine forms show
+ *   no errors until the app opts in).
+ * @property {object} [catalog] - Compiled message catalog for error
+ *   texts (compileMessageCatalog), default English.
+ * @property {import('./rules.js').RuleMemo} [memo] - A memo from
+ *   `createRuleMemo`, reused across calls so only the rules a change
+ *   can reach are re-evaluated. Keep one per form session; the tree it
+ *   produces is the same either way.
+ * @property {FormSessionOptions} [session] - Fold a form session
+ *   (initial/touched/submitted/serverErrors/submit identity) into the
+ *   tree: every node gains `id`/`describedBy`/`dirty`/`touched`/
+ *   `serverErrors`, and the root gains a `session` summary. Absent, the
+ *   tree is byte-identical to the sessionless shape.
+ */
+/**
+ * Build the render tree for one form instant.
+ *
+ * @example
+ * const model = buildFormModel(schema);
+ * const rules = compileFormRules(model);
+ * const tree = buildFormViewModel(model, data, { rules, validateFields: true });
+ * // tree.children[0] -> { pointer: '/email', control: 'email',
+ * //                       value: 'a@b.c', errors: [], ... }
+ *
+ * @param {FormField} model - The field tree from `buildFormModel`.
+ * @param {any} data - The current form data.
+ * @param {FormViewModelOptions} [options]
+ * @returns {FormViewNode|null} The root render node (`null` only when a
+ *   root rule hides the whole form).
+ */
+export declare function buildFormViewModel(model: FormField, data: any, options?: FormViewModelOptions): FormViewNode | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/forms",
   "private": false,
-  "version": "0.9.2",
+  "version": "0.34.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -26,7 +26,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "publishConfig": {
     "access": "public",
@@ -47,8 +47,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.9.2",
-    "@jarenjs/formats": "^0.9.2",
-    "@jarenjs/json": "^0.9.2"
+    "@jarenjs/core": "^0.34.0",
+    "@jarenjs/formats": "^0.34.0",
+    "@jarenjs/json": "^0.34.0",
+    "@jarenjs/validate": "^0.34.0"
   }
 }