@jarenjs/forms 0.73.0 → 0.75.0

package/README.md

@@ -189,7 +189,7 @@ These two externals are the whole vocabulary: any other free name in a rule is a
 
 ### Array item templates
 
-A rule on an array item template (`/lines/-/amount`) compiles **once** and evaluates **per element** of the actual array, binding `$value`/`$pointer` per index — results are keyed by the expanded pointer (`/lines/2/amount`). That compiled-once/dispatch-per-node generalization now exists as the [`@jarenjs/json/jslt`](../json/docs/JSLT-FORMAT.md) `$apply` engine: a future forms computed-view layer can generalize `x-form.computed` into schema-dispatched view-model stylesheets without changing forms' validator-independent boundary.
+A rule on an array item template (`/lines/-/amount`) compiles **once** and evaluates **per element** of the actual array, binding `$value`/`$pointer` per index — results are keyed by the expanded pointer (`/lines/2/amount`). Rendering uses [`@jarenjs/json/jslt`](../json/docs/JSLT-FORMAT.md) rules over the composed view model. Composition retains the model, data and session cursors together; see the addressing measurement below.
 
 ### Schema literals in rules
 
@@ -383,6 +383,39 @@ Form data keeps plain JSON semantics — an untouched field is *absent*, not an
 
 `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`. A short tuple's `addValue` comes from its next prefix slot; the tail item template supplies starters only after the prefix is filled.
 
+The composition walk carries the current **raw data cursor** and the
+session's **initial cursor** down beside each field. It reads one pointer
+suffix per descent instead of starting from the document root per field;
+computed container values do not replace the raw cursor used by children.
+Missing baseline ancestors stay missing, preserving dirty-state detection.
+
+`$fold` can implement a second cursor with typed segments, but this alone
+is not a reason to replace the composer. The executable experiment in
+`benchmark/forms-composition.js` compares a fold-based JSLT rule with root
+pointer getters and carried cursors on the same expanded fields. Its
+parity tests include escaped keys, array indexes and missing ancestors.
+
+<!--fact:forms.addressing-->
+
+Measured on v24.19.0, linux/x64; median milliseconds per expanded-field projection. Compilation and field expansion are excluded from all contenders.
+
+| Depth | Nodes | Root pointers | Carried cursors | Fold stylesheet |
+|---|---|---|---|---|
+| 1 | 33 | 0.0043 | 0.0040 | 0.0817 |
+| 8 | 136 | 0.0314 | 0.0101 | 0.6325 |
+| 24 | 536 | 0.2811 | 0.0319 | 5.1716 |
+
+<!--/fact-->
+
+The shallow timings are close and do not justify a universal speedup
+claim; deeper trees benefit from carrying cursors. The fold stylesheet loses on every
+fixture even with expansion excluded. These measurements cover addressing
+only, not the complete session/validation/render pipeline. The production
+composer therefore keeps the JS walk. A complete stylesheet replacement
+still needs evidence for array-template expansion, hidden fields, enum
+values, errors and session state; first-class functions are not a
+prerequisite.
+
 ```javascript
 const model = buildFormModel(schema);
 const rules = compileFormRules(model);
@@ -478,3 +511,17 @@ Every subpath a consumer can import, derived from the manifest by
 ## 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](../../docs/ROADMAP.md) for planned forms work (rule dependency memoization, hidden-field pruning on submit, computed views through JSLT).
+
+## Form chrome policy
+
+`formChromeLabels(catalog)` supplies `addItem`, `removeItem` and
+`jsonPlaceholder`, with English fallbacks and translations in every
+locale pack. Pass them to `createFormView({ labels })`; the JSON hint is
+both an empty-editor placeholder and an accessible description. A label
+beginning with `$` remains literal text.
+
+The add/remove glyphs and required marker are decoration, not message
+keys: customize `addLabel`, `removeLabel` and `requiredMarker` on the
+stylesheet. Required controls carry `aria-required`; the decorative
+marker stays hidden from assistive technology. JSON syntax and the name
+“JSON” retain their wire spelling; instructions around them are localized.

package/dist/types/messages.d.ts

@@ -47,18 +47,19 @@ export declare function formatDisplayName(catalog: Readonly<Record<string, (para
 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.
+ * names of the array add/remove buttons and the JSON editor's hint.
  *
  * 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}}
+ * @returns {{addItem: string, removeItem: string, jsonPlaceholder: string}}
  * @example
  * createFormView({ labels: formChromeLabels(catalogs[locale]) });
  */
 export declare function formChromeLabels(catalog?: Readonly<Record<string, (params: object, error?: object) => string>>): {
     addItem: string;
     removeItem: string;
+    jsonPlaceholder: string;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/forms",
   "private": false,
-  "version": "0.73.0",
+  "version": "0.75.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -47,9 +47,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.73.0",
-    "@jarenjs/formats": "^0.73.0",
-    "@jarenjs/json": "^0.73.0",
-    "@jarenjs/validate": "^0.73.0"
+    "@jarenjs/core": "^0.75.0",
+    "@jarenjs/formats": "^0.75.0",
+    "@jarenjs/json": "^0.75.0",
+    "@jarenjs/validate": "^0.75.0"
   }
 }

package/src/messages.js

@@ -63,6 +63,7 @@ export const formsMessagesEn = {
   // message like every other string an operator can hear.
   'form/addItem': 'Add item',
   'form/removeItem': 'Remove item',
+  'form/jsonPlaceholder': 'Enter a JSON value',
 };
 
 /** The compiled built-in English catalog (module-level singleton). */
@@ -127,14 +128,14 @@ export function renderFormsMessage(catalog, msgid, params) {
 
 /**
  * The localized chrome strings a form renderer needs: the accessible
- * names of the array add/remove buttons.
+ * names of the array add/remove buttons and the JSON editor's hint.
  *
  * 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}}
+ * @returns {{addItem: string, removeItem: string, jsonPlaceholder: string}}
  * @example
  * createFormView({ labels: formChromeLabels(catalogs[locale]) });
  */
@@ -142,6 +143,7 @@ export function formChromeLabels(catalog = undefined) {
   return {
     addItem: renderFormsMessage(catalog, 'form/addItem', {}),
     removeItem: renderFormsMessage(catalog, 'form/removeItem', {}),
+    jsonPlaceholder: renderFormsMessage(catalog, 'form/jsonPlaceholder', {}),
   };
 }
 

package/src/viewmodel.js

@@ -184,7 +184,7 @@ export function buildFormViewModel(model, data, options = {}) {
   const session = options.session !== undefined
     ? compileSession(options.session, data)
     : null;
-  const root = buildNode(model, '', data, ruleState, fieldErrors, false, false, session);
+  const root = buildNode(model, '', data, ruleState, fieldErrors, false, false, session, session?.initial);
   if (root !== null && session !== null) {
     root.session = {
       dirty: session.dirtyPaths.length > 0,
@@ -286,19 +286,19 @@ function pointerId(prefix, pointer) {
  * @param {string} pointer - The concrete RFC 6901 pointer of this node
  *   (segments encoded with `encodeJSONPointerSegment`, the walk
  *   convention shared with the model, rule and validation pointers).
- * @param {any} data - The form data root.
+ * @param {any} raw - The data cursor at this field (before computed values).
  * @param {Record<string, any>} ruleState
  * @param {Record<string, any>} fieldErrors
  * @param {boolean} element
  * @param {boolean} removable
  * @param {ReturnType<typeof compileSession> | null} [session]
+ * @param {any} [initialValue] - The baseline cursor at this field.
  * @returns {FormViewNode|null}
  */
-function buildNode(field, pointer, data, ruleState, fieldErrors, element, removable, session = null) {
+function buildNode(field, pointer, raw, ruleState, fieldErrors, element, removable, session = null, initialValue = undefined) {
   const rs = ruleState[pointer];
   if (rs !== undefined && rs.visible === false) return null;
 
-  const raw = getValueAtPointer(data, pointer);
   let value = field.kind === 'const' ? field.constValue : raw;
   if (rs !== undefined && rs.computed !== undefined) value = rs.computed;
 
@@ -369,7 +369,6 @@ function buildNode(field, pointer, data, ruleState, fieldErrors, element, remova
     if (session.hasInitial) {
       // presence-aware: adding or removing a member whose value is
       // null is a membership change, so it is dirty
-      const initialValue = getValueAtPointer(session.initial, pointer);
       node.dirty = (initialValue === undefined) !== (raw === undefined)
         || (initialValue !== undefined && !equalsJson(initialValue, raw));
     }
@@ -381,9 +380,11 @@ function buildNode(field, pointer, data, ruleState, fieldErrors, element, remova
   if (field.children !== null && field.children !== undefined) {
     const children = [];
     for (const child of field.children) {
+      const segment = `/${encodeJSONPointerSegment(child.key)}`;
       const built = buildNode(
-        child, `${pointer}/${encodeJSONPointerSegment(child.key)}`, data, ruleState,
-        fieldErrors, false, false, session);
+        child, pointer + segment, getValueAtPointer(raw, segment), ruleState,
+        fieldErrors, false, false, session,
+        session?.hasInitial ? getValueAtPointer(initialValue, segment) : undefined);
       if (built !== null) children.push(built);
     }
     node.children = children;
@@ -404,7 +405,8 @@ function buildNode(field, pointer, data, ruleState, fieldErrors, element, remova
       // still valid is `minItems`' answer to give, not this layer's.
       const removable = !isTupleSlot || i === array.length - 1;
       const built = buildNode(
-        template, `${pointer}/${i}`, data, ruleState, fieldErrors, true, removable, session);
+        template, `${pointer}/${i}`, array[i], ruleState, fieldErrors, true, removable, session,
+        session?.hasInitial ? getValueAtPointer(initialValue, `/${i}`) : undefined);
       if (built !== null) items.push(built);
     }
     node.items = items;