@jarenjs/forms 0.9.2 → 0.34.2

package/README.md

@@ -61,7 +61,7 @@ const result = validate(data); // { valid, errors: [{ instancePath, keyword, mes
 | `pointer` | JSON pointer into the data (`/user/name`) |
 | `label` | `title` or a humanized property name (`firstName` → "First Name") |
 | `kind` | `string` `number` `integer` `boolean` `enum` `const` `object` `array` |
-| `control` | Rendering hint: `text` `email` `url` `password` `textarea` `number` `checkbox` `select` `date` `color` `json` |
+| `control` | Rendering hint: `text` `email` `url` `password` `textarea` `number` `checkbox` `select` `date` `datetime-local` `time` `color` `json` |
 | `required` | Whether the parent object requires this property |
 | `constraints` | `minLength`/`maxLength`/`pattern`/`format`/`minimum`/`maximum`/`multipleOf`/`minItems`/... |
 | `rules` | The raw `x-form` rules annotation, if any (see below) |
@@ -71,6 +71,8 @@ const result = validate(data); // { valid, errors: [{ instancePath, keyword, mes
 
 Field kinds are inferred from structural keywords when `type` is absent, and `format` maps to input controls and placeholders through the same registry the preemptive validation uses (`getFormatInfo`).
 
+Which date formats get a **native** control is decided by the offset, not by convenience. HTML's `datetime-local` and `time` inputs cannot produce one, and RFC 3339 requires one — binding them to `date-time`/`time` would make the control emit values its own schema rejects, so those stay text inputs. The `iso-date-time`/`iso-time` formats leave the offset optional and are exactly what those inputs spell, so they map losslessly. `formatMinimum`/`formatMaximum` reach the field as constraints and become the control's `min`/`max`, so the picker itself refuses an out-of-range date; HTML has no exclusive date bounds, so `formatExclusive*` stays a submit-time check.
+
 ## Layer 1 — preemptive per-field validation
 
 `validateField(field, value)` returns `[{ keyword, message }]` using `@jarenjs/core` directly:
@@ -170,9 +172,9 @@ The same constraint can be spelled twice — `x-form.assert` for keystroke feedb
 ```javascript
 import { formRulesToQueryAssertions } from '@jarenjs/forms';
 
-// pure schema-to-schema transform: every x-form.assert is copied into a
-// root-level $query (joined to an existing one through allOf), with
-// value/pointer rebound to the field's location
+// pure schema-to-schema transform: every x-form.assert becomes its own
+// allOf branch { $query, errorMessage } on the root, with value/pointer
+// rebound to the field's location and the rule's message carried along
 const submitSchema = formRulesToQueryAssertions(schema);
 
 import { JarenValidator } from '@jarenjs/validate';                // app-side
@@ -180,17 +182,212 @@ const validate = new JarenValidator().compile(submitSchema);
 validate({ company: 'ACME', vatId: '' }); // false - the vatId assert, now authoritative
 ```
 
-Item-template asserts quantify with `$every` over the actual elements. Two divergences from the keystroke path are inherent to the copy: on submit an absent field binds `$value` to the empty sequence (not `null`), and `$pointer` for template elements stays the template pointer (element indexes are a render-time notion).
+Each branch's `errorMessage` carries the rule's `message` (inline string
+or `$msgid` form) with `params` merged over `{ pointer: <field pointer> }`
+— so every submit-time `$query` failure names its owning field in
+`params.pointer`, letting the UI place root-level `$query` errors onto
+fields, and renders the **same text** as the keystroke path (see below).
+
+**One rule, one meaning.** Whatever the keystroke evaluation says about a
+document, submit says too — the copy is not allowed to change what an author
+wrote. Three things enforce that, and each is a place the naive copy went
+wrong:
+
+- an **absent field binds `null`**, not the empty sequence, so `$ne`/`$eq`
+  cannot mean opposite things on the two sides (the binding is wrapped in
+  `$default`);
+- an **item-template assert quantifies over the ELEMENTS**, not over the
+  selected leaf values — quantifying over leaves silently skips an element
+  that lacks the member, where the keystroke path evaluates it with `null`;
+- an assert on a field with a `visible` rule is **guarded by it**, holding
+  vacuously while the field is hidden — which is what the keystroke path
+  already does, since `buildFormViewModel` drops hidden nodes and their
+  errors never render or count.
+
+One divergence remains, and is inherent: `$pointer` for template elements
+stays the template pointer, because element indexes are a render-time notion.
+
+A hidden field's *value* is a separate question, and the answer is explicit:
+values are kept while editing — a field that reappears must not have
+forgotten what the operator typed — and dropped only at the submit boundary,
+by a caller who asks:
+
+```javascript
+import { pruneHiddenValues } from '@jarenjs/forms';
+
+const submitted = pruneHiddenValues(compiledRules, session.data);
+```
+
+Visibility is evaluated once, against the incoming document. Hidden array
+elements are removed and their siblings renumber, which is right for a
+document being sent — and means the returned pointers no longer line up with
+the ones the view model rendered.
+
+## Messages & i18n
+
+Every `FieldError` is structured: `{ keyword, params, msgid, message }`.
+The `msgid` is `form/<keyword>` (field checks) or `x-form/assert` /
+the author's `$msgid` (rules); `message` is rendered eagerly —
+failure-only, cheap — through a **catalog** (see
+[ERROR-MESSAGES.md](../validate/docs/ERROR-MESSAGES.md) for the shared
+contract). `validateField`, `validateAllFields` and `evaluateFormRules`
+take an optional compiled catalog, default English:
+
+```javascript
+import { validateAllFields, compileMessageCatalog } from '@jarenjs/forms';
+import { nl } from '@jarenjs/locales';
+
+const catalog = compileMessageCatalog(nl);
+const errors = validateAllFields(model, data, catalog);
+// errors['/name'][0].message === 'Dit veld is verplicht'
+```
+
+### MessageSpec in `x-form.message`
+
+A rule's `message` may be a plain string (backward compatible — an inline
+template, `{pointer}` etc. interpolated) or a `$msgid` spec resolving
+through the catalog:
+
+```javascript
+{ "x-form": {
+    "assert": { "$or": [{ "$eq": ["$.company", ""] }, { "$ne": ["$.vatId", ""] }] },
+    "message": { "$msgid": "checkout.vat-required",
+                 "message": "A VAT id is required for companies" } } }
+```
+
+### One rule, one message — keystroke and submit
+
+The same rule renders the **identical string** per keystroke
+(`evaluateFormRules`) and at submit (the transformed schema's `$query`
+failure through the validator), in every locale:
+
+```javascript
+const compiled = compileFormRules(buildFormModel(schema));
+evaluateFormRules(compiled, data, catalog);      // keystroke: Dutch text
+
+const validate = new JarenValidator({ collectErrors: true })
+  .compile(formRulesToQueryAssertions(schema));  // app-side
+const result = validate(data);
+localizeErrors(result.errors, catalog);          // submit: the same Dutch text
+```
+
+### Static text — the l10n surface everyone forgets
+
+Labels, descriptions, placeholders and enum option labels resolve once at
+model-build time; `buildFormModel` takes a `t` hook (default: identity)
+receiving role-qualified message ids built from each field's base — its
+`x-msgid` annotation or its data pointer:
+
+```javascript
+const staticNl = {
+  '/firstName#label': 'Voornaam',
+  'account.country#label': 'Land',
+  'account.country#enum/nl': 'Nederland',
+};
+const model = buildFormModel(schema, {
+  t: (msgid, fallback) => staticNl[msgid] ?? fallback,
+});
+```
+
+Enum option labels come from the JSON Schema idiom
+`oneOf: [{ "const": "nl", "title": "Netherlands" }, ...]` (treated as an
+enum with per-option titles) or `String(value)`, each through
+`t('<base>#enum/<value>', fallback)`; the labels land on
+`field.enumLabels`, parallel to `field.enumValues`.
 
 ## Data helpers
 
-Form data keeps plain JSON semantics — an untouched field is *absent*, not an empty string. Pointers parse and read through the [`@jarenjs/json`](../json) compiled pointer engine (RFC 6901, one implementation repo-wide); reads hit a compiled-getter cache and allocate nothing:
+Form data keeps plain JSON semantics — an untouched field is *absent*, not an empty string. Pointers parse, read AND write through the [`@jarenjs/json`](../json) engines (RFC 6901, one implementation repo-wide): reads hit a compiled-getter cache and allocate nothing, and writes run on the same copy-on-write kernel as the patch module (`compileJSONPointerSetter` with `parents: 'create'`), so untouched siblings are shared by reference on every keystroke — which feeds the JSLT memo and the view patcher's reference-equality fast path downstream:
 
 - `createInitialData(model)` — defaults and `const` values filled in, everything else absent
 - `parseFieldInput(field, raw)` — input coercion (`''` → undefined, numeric strings → numbers, enum options → typed values)
 - `getValueAtPointer` / `setValueAtPointer` / `appendItem` / `removeItemAt` — immutable updates addressed by JSON pointer
 - `createItemValue(field.item)` — starter value for a new array item
 
+## The view model — one render tree per instant
+
+`buildFormViewModel(model, data, options)` composes everything above — the field tree, the current data, per-field validation and `x-form` rule state — into **one plain-JSON render tree**: the "computed view" layer this README promised. Each node carries `pointer`, `label`, `control`, `value` (`x-form.computed` wins, `null` when absent), precomputed select `options` (with `selected`), localized `errors`, `enabled`, and the write discipline flags (`element`: array elements must be written with RFC 6902 `replace`, since `add` inserts; `removable`; `addValue` from `createItemValue`). Rule-hidden fields are *excluded* — a renderer cannot leak hidden data by accident. Array item templates expand per data element with concrete pointers (`/lines/2/amount`), matching the pointer keys of `evaluateFormRules` and `validateAllFields`.
+
+```javascript
+const model = buildFormModel(schema);
+const rules = compileFormRules(model);
+const tree = buildFormViewModel(model, data, { rules, validateFields: true, catalog });
+// tree.children[0] -> { pointer: '/email', control: 'email', value: 'a@b',
+//                       errors: ['Must be a valid email'], ... }
+```
+
+Render it with anything — a React component walking the tree, or **no framework at all**: the standard form rules of [`@jarenjs/app`](../app) are a shipped JSLT rule set that dispatches over exactly this shape and produces [`@jarenjs/view`](../view) vnodes, closing the loop from JSON Schema to live DOM without a single hand-written render function.
+
+Two node members exist because a **DOM control's value is a string** and not
+every field's value is: each select option carries `key`, its value as JSON
+text, and a `json`-control node carries `json`, its value as indented JSON
+text. A renderer puts those in the control and hands them back verbatim;
+`@jarenjs/app`'s `formEventFields()` decodes them. That keeps a `enum: [1, 2]`
+selection a number instead of `"2"`.
+
+### Re-evaluating only what changed
+
+Rules compile once and run per keystroke. On a wide form most of that work is
+wasted — a keystroke in one field cannot change what a rule reading two other
+fields concludes — so pass a **memo** and only the reachable rules re-run:
+
+```javascript
+import { createRuleMemo } from '@jarenjs/forms';
+
+const memo = createRuleMemo();                       // one per form session
+const tree = buildFormViewModel(model, data, { rules, memo, catalog });
+```
+
+Each rule's dependencies are derived at compile time from the root-anchored
+paths in its query documents (plus its own location). That over-approximates
+every read, and soundly: the only way into the document is such a path, and a
+`$let`/`$for` variable can only hold what one of them produced.
+
+The memo diffs the previous document against the new one — reference-equal
+subtrees are skipped whole, so an immutable edit costs O(change). A host that
+already knows what it wrote can skip even that with `memo.touch(pointer)`,
+which is a promise as much as an optimization: touch one pointer while
+changing another and the rules you did not name keep stale results.
+
+Measured on a 200-rule form (one `visible` + one `assert` each):
+
+| tick | cost |
+|---|---|
+| full evaluation | ~54 µs |
+| memo, one field changed (diffed) | ~13 µs |
+| memo, one field changed (declared) | ~4.7 µs |
+| memo, a field every rule reads | ~58 µs |
+
+The last row is the honest one: when a change reaches every rule there is
+nothing to skip, and the memo's bookkeeping makes it slightly *slower* than
+evaluating straight through. It pays when a form is wide and its rules are
+mostly local — which is what a large form usually is, and exactly when the
+full evaluation starts to hurt.
+
+### The form session — submit/draft lifecycle around one document
+
+Pass `options.session` and every node additionally carries `id` (a stable, **injective** accessible element id derived from the pointer — distinct pointers can never collide, because every character outside `[A-Za-z0-9]` (`-` and `_` themselves included) is escaped as `_<codepoint>_` *before* the segments are joined on `-`, so a member name containing the separator or an escape cannot forge another pointer's id: `/a/b` → `<prefix>--f-a-b`, `/a-b` → `<prefix>--f-a_45_b`. Member ids carry the `f-` marker so the `<prefix>--root` sentinel is disjoint from every member, a member literally named `root` included. Write the same escaping in your `<label for=…>` if you build an id by hand), `describedBy` (the id of the node's error text, or `null`), `dirty` (presence-aware deep compare against `session.initial` — adding or removing a member counts even when both sides read back `null`), `touched`, and `serverErrors` (kept distinct from client `errors`). The root gains a `session` summary:
+
+```javascript
+const tree = buildFormViewModel(model, data, {
+  rules, validateFields: true,
+  session: {
+    initial,                       // the baseline document
+    touched: ['/email'],           // pointers the operator visited
+    submitted: true,
+    submitStatus: 'pending',       // echoed verbatim
+    requestId: 'req-7',            // the in-flight submit's identity
+    serverErrors: { '/email': ['Al in gebruik.'] },
+    idPrefix: 'customer',          // ids become customer--…
+  },
+});
+tree.session;
+// { dirty, dirtyPaths, submitted, submitStatus, requestId,
+//   errorCount, serverErrorCount }
+```
+
+`session.dirty`/`session.dirtyPaths` are the **navigation-guard authority**: they come from a full JSON diff of `initial` against the current data — independent of what is rendered — so removed array tails, members removed or added (including explicit `null`), and values retained under rule-hidden fields all count, each contributing its pointer. The diff walks **own** keys only (`Object.hasOwn`), so hostile-but-legal member names like `constructor` or a JSON-parsed `__proto__` diff as data, never through the prototype chain, and it RFC 6901-encodes every member name as it builds the pointer (`~` → `~0`, `/` → `~1`, the same `encodeJSONPointerSegment` the model, rule and validation walks use) — so a key containing a slash or a tilde cannot collide with a nested path, and the entries of `dirtyPaths` feed straight back into `getValueAtPointer`. To keep the authority unconditional, a root-level `x-form` `visible` rule is rejected by `compileFormRules` with a `TypeError` — hiding the whole form would null the render tree *and* its summary; gate whole-form visibility at the mount boundary instead. The per-node `dirty`/`errors` members remain the render-layer, visible-only summary. Without `session`, the tree is byte-identical to the sessionless shape.
+
 ## Development
 
-Unit tests live in `test/forms/` at the repository root. See the repository [README](../../README.md) for the full Jaren documentation, and the [ROADMAP](../../ROADMAP.md) for planned forms work (rule dependency memoization, hidden-field pruning on submit, computed views through JSLT).
+Unit tests live in `test/forms/` at the repository root. See the repository [README](../../README.md) for the full Jaren documentation, and the [ROADMAP](../../docs/ROADMAP.md) for planned forms work (rule dependency memoization, hidden-field pruning on submit, computed views through JSLT).

package/dist/types/data.d.ts

@@ -15,10 +15,11 @@ export declare function parsePointer(pointer: string): string[];
 export declare function getValueAtPointer(data: any, pointer: string): any;
 /**
  * Return a copy of `data` with the value at `pointer` replaced.
- * Setting `undefined` REMOVES the property (array items become undefined
- * holes only when explicitly set; use removeItemAt to delete them).
- * Missing intermediate containers are created (objects for name segments,
- * arrays for numeric segments).
+ * Setting `undefined` REMOVES the location (deleting something that does
+ * not exist is a no-op returning `data` unchanged). Missing intermediate
+ * containers are created (objects for name segments, arrays for numeric
+ * segments), and untouched siblings are shared by reference — the same
+ * copy-on-write engine as `@jarenjs/json`'s patch and write modules.
  * @param {any} data
  * @param {string} pointer
  * @param {any} value
@@ -43,6 +44,24 @@ export declare function removeItemAt(data: any, pointer: string, index: number):
  * @returns {any}
  */
 export declare function appendItem(data: any, pointer: string, value: any): any;
+/**
+ * Every pointer whose value differs between two documents, in
+ * document order.
+ *
+ * Membership is significant: an added or removed member (or array tail
+ * slot) contributes its pointer even when both sides read back as
+ * `null` through a pointer lookup. Reference-equal subtrees are skipped
+ * whole, so over copy-on-write edits — which is how every writer in
+ * this package produces its next document — the walk costs O(change),
+ * not O(document).
+ *
+ * Two callers rely on it: the session's navigation-guard evidence
+ * (`dirtyPaths`) and the rule memo's invalidation set.
+ * @param {any} previous
+ * @param {any} current
+ * @returns {string[]}
+ */
+export declare function changedPointers(previous: any, current: any): string[];
 /**
  * Create initial data for a form model: schema defaults and const values
  * are filled in, everything else stays absent.

package/dist/types/deps.d.ts

@@ -0,0 +1,30 @@
+export type RuleDependencies = string[];
+/**
+ * The dependency set of a rule: pointer prefixes, or `ALL_POINTERS` for
+ * "any change matters" (a query that reads the whole document).
+ * @typedef {string[]} RuleDependencies
+ */
+/** A rule that reads the root depends on everything. */
+export declare const ALL_POINTERS: string[];
+/**
+ * Collect the data dependencies of one rule query document.
+ * @param {any} doc - The authored rule document
+ * @returns {RuleDependencies} Pointer prefixes, deduplicated
+ */
+export declare function queryDependencies(doc: any): RuleDependencies;
+/**
+ * Merge dependency sets, collapsing to {@link ALL_POINTERS} when any of
+ * them reads the root and dropping prefixes another already covers.
+ * @param {RuleDependencies[]} sets
+ * @returns {RuleDependencies}
+ */
+export declare function mergeDependencies(sets: RuleDependencies[]): RuleDependencies;
+/**
+ * Whether a change at `changed` can affect a rule depending on `dep`.
+ * True in BOTH nesting directions: a change inside a dependency
+ * (`/a` vs `/a/b`) alters what the rule reads, and a change ABOVE one
+ * (`/a/b` vs `/a`) can replace the container it reads through.
+ * @param {string} dep @param {string} changed
+ * @returns {boolean}
+ */
+export declare function dependencyTouched(dep: string, changed: string): boolean;

package/dist/types/index.d.ts

@@ -11,7 +11,9 @@
  * JSON pointer through the @jarenjs/json compiled pointer engine.
  */
 export { buildFormModel, resolveSchema, getFieldKind, humanizeKey, escapePointerKey, } from './model.js';
-export { compileFormRules, evaluateFormRules, formRulesToQueryAssertions, } from './rules.js';
+export { compileFormRules, evaluateFormRules, formRulesToQueryAssertions, pruneHiddenValues, createRuleMemo, } from './rules.js';
 export { validateField, validateAllFields, } from './validate.js';
+export { formsMessagesEn, formChromeLabels, compileMessageTemplate, compileMessageCatalog, } from './messages.js';
 export { createInitialData, createItemValue, parseFieldInput, parsePointer, getValueAtPointer, setValueAtPointer, appendItem, removeItemAt, } from './data.js';
 export { FORM_FORMATS, getFormatInfo, } from './formats.js';
+export { buildFormViewModel, } from './viewmodel.js';

package/dist/types/messages.d.ts

@@ -0,0 +1,36 @@
+export { compileMessageTemplate, compileMessageCatalog, } from '@jarenjs/core/message';
+/**
+ * The built-in English forms catalog. Key set = exactly the `form/*` keys
+ * `validateField` emits, plus `x-form/assert` (the rules default). The
+ * strings are byte-identical to the historical inline template literals.
+ * @type {Record<string, string | ((params: object, error?: object) => string)>}
+ */
+export declare const formsMessagesEn: Record<string, string | ((params: object, error?: object) => string)>;
+/** The compiled built-in English catalog (module-level singleton). */
+export declare const formsMessages: Readonly<Record<string, (params: object, error?: object) => string>>;
+/**
+ * Resolve a message key through a caller catalog with built-in English
+ * fallback and render it.
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>|undefined} catalog - A compiled catalog, or undefined for English
+ * @param {string} msgid - The message key
+ * @param {object} params - The structured params
+ * @returns {string} The rendered message
+ */
+export declare function renderFormsMessage(catalog: Readonly<Record<string, (params: object, error?: object) => string>> | undefined, msgid: string, params: object): string;
+/**
+ * The localized chrome strings a form renderer needs: the accessible
+ * names of the array add/remove buttons.
+ *
+ * The stylesheet that renders a form is plain JSON built once, so it
+ * cannot look anything up at render time — the host resolves these and
+ * hands them to `createFormView`. Kept next to the error catalog on
+ * purpose: one keyspace, one parity gate across every locale pack.
+ * @param {Readonly<Record<string, (params: object, error?: object) => string>>} [catalog] - A compiled catalog, or undefined for English
+ * @returns {{addItem: string, removeItem: string}}
+ * @example
+ * createFormView({ labels: formChromeLabels(catalogs[locale]) });
+ */
+export declare function formChromeLabels(catalog?: Readonly<Record<string, (params: object, error?: object) => string>>): {
+    addItem: string;
+    removeItem: string;
+};

package/dist/types/model.d.ts

@@ -8,7 +8,11 @@ export type FormField = {
      */
     key: string;
     /**
-     * - Human friendly label (schema title or humanized key)
+     * - The field's message-id base: `x-msgid` annotation or the pointer (the root field's base is the empty pointer '')
+     */
+    msgid: string;
+    /**
+     * - Human friendly label (schema title or humanized key), through the `t` hook
      */
     label: string;
     description: string | undefined;
@@ -21,7 +25,7 @@ export type FormField = {
      */
     kind: string;
     /**
-     * - Suggested control: 'text'|'email'|'url'|'password'|'textarea'|'number'|'checkbox'|'select'|'date'|'color'|'json'
+     * - Suggested control: 'text'|'email'|'url'|'password'|'textarea'|'number'|'checkbox'|'select'|'date'|'datetime-local'|'time'|'color'|'json'
      */
     control: string;
     /**
@@ -33,6 +37,10 @@ export type FormField = {
      * - Options for a select control
      */
     enumValues: Array<any> | null;
+    /**
+     * - Display labels parallel to enumValues (oneOf const/title idiom, through the `t` hook)
+     */
+    enumLabels: Array<string> | null;
     /**
      * - Fixed value when the schema is a const
      */
@@ -60,29 +68,12 @@ export type FormField = {
      */
     tuple: Array<FormField> | null;
 };
-/**
- * @typedef {object} FormField
- * @property {string} pointer - JSON pointer into the DATA (e.g. '/user/name')
- * @property {string} key - Property name (or '-' for an array item template)
- * @property {string} label - Human friendly label (schema title or humanized key)
- * @property {string|undefined} description
- * @property {object} schema - The resolved subschema for this field
- * @property {string} kind - 'string'|'number'|'integer'|'boolean'|'enum'|'const'|'object'|'array'|'unknown'
- * @property {string} control - Suggested control: 'text'|'email'|'url'|'password'|'textarea'|'number'|'checkbox'|'select'|'date'|'color'|'json'
- * @property {boolean} required - Whether the parent object requires this property
- * @property {boolean} readOnly
- * @property {Array<any>|null} enumValues - Options for a select control
- * @property {any} constValue - Fixed value when the schema is a const
- * @property {any} defaultValue
- * @property {string|undefined} placeholder
- * @property {object} constraints - minLength/maxLength/pattern/minimum/... extracted for the UI
- * @property {object|null} rules - The raw `x-form` rules annotation, if any (see rules.js)
- * @property {Array<FormField>|null} children - Child fields for object kinds
- * @property {FormField|null} item - Template field for array items
- * @property {Array<FormField>|null} tuple - Fixed prefix fields for tuple arrays
- */
+export type TranslateHook = (msgid: string, fallback: string | undefined, params?: object) => string | undefined;
 /**
  * Convert 'firstName' / 'first_name' / 'first-name' to 'First Name'.
+ * Latin-script-oriented (word splitting on case/underscore/hyphen and
+ * ASCII capitalization); the `t` hook of buildFormModel is the override
+ * point for anything it mangles.
  * @param {string} key
  * @returns {string}
  */
@@ -104,7 +95,9 @@ export declare function resolveSchema(schema: object | boolean, rootSchema: obje
 export declare function getFieldKind(schema: object | boolean): string;
 /**
  * Encode a property name as an RFC 6901 reference token (`~` -> `~0`,
- * `/` -> `~1`), the write-side inverse of the shared parse.
+ * `/` -> `~1`), the write-side inverse of the shared parse. An alias of
+ * `encodeJSONPointerSegment` from `@jarenjs/json/pointer`, kept for
+ * compatibility.
  * @param {string} key
  * @returns {string}
  */
@@ -112,7 +105,16 @@ export declare function escapePointerKey(key: string): string;
 /**
  * Build the form model for a JSON schema.
  *
+ * Static text (labels, descriptions, placeholders, enum option labels) is
+ * resolved ONCE here, at model-build time - the right place for
+ * translation. The optional `t` hook receives role-qualified message ids
+ * built from each field's base (`x-msgid` annotation or data pointer):
+ * `<base>#label`, `<base>#description`, `<base>#placeholder`,
+ * `<base>#enum/<String(value)>` - and the schema-derived fallback text.
+ *
  * @param {object|boolean} schema - The root JSON schema
+ * @param {object} [options]
+ * @param {TranslateHook} [options.t] - Static-text translation hook, default the zero-cost identity `(id, fb) => fb`
  * @returns {FormField} The root field descriptor (kind 'object' for object schemas)
  * @example
  * const model = buildFormModel({
@@ -121,5 +123,12 @@ export declare function escapePointerKey(key: string): string;
  *   required: ['email'],
  * });
  * model.children[0].control; // 'email'
+ * @example
+ * // static-text i18n
+ * const nlModel = buildFormModel(schema, {
+ *   t: (msgid, fallback) => staticTextNl[msgid] ?? fallback,
+ * });
  */
-export declare function buildFormModel(schema: object | boolean): FormField;
+export declare function buildFormModel(schema: object | boolean, options?: {
+    t?: TranslateHook;
+}): FormField;