@jarenjs/forms 0.56.0 → 0.66.1

package/README.md

@@ -247,10 +247,11 @@ wrong:
 - 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.
+- an assert is **guarded by the field's own and ancestor `visible` rules**,
+  each with its own value/pointer bindings, holding vacuously while the
+  field is hidden — which is what the keystroke path already does, since
+  `buildFormViewModel` drops hidden subtrees and their errors never render
+  or count. Ordinary schema constraints still apply to retained values.
 
 One divergence remains, and is inherent: `$pointer` for template elements
 stays the template pointer, because element indexes are a render-time notion.
@@ -364,20 +365,23 @@ 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`.
+`field.enumLabels`, parallel to `field.enumValues`. An explicit `enum`
+supplies its own values and `String(value)` labels even when `oneOf` is
+also present. The view model selects object and array options by JSON
+equality, so values loaded from JSON keep their selection.
 
 ## Data helpers
 
 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
+- `createInitialData(model)` — defaults and `const` values filled in as own JSON members (including `__proto__`), 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`.
+`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.
 
 ```javascript
 const model = buildFormModel(schema);
@@ -459,6 +463,18 @@ tree.session;
 
 `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.
 
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.forms-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/forms` | JavaScript | declared |
+| `@jarenjs/forms/package.json` | metadata | — |
+<!--/fact-->
+
 ## 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).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/forms",
   "private": false,
-  "version": "0.56.0",
+  "version": "0.66.1",
   "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.56.0",
-    "@jarenjs/formats": "^0.56.0",
-    "@jarenjs/json": "^0.56.0",
-    "@jarenjs/validate": "^0.56.0"
+    "@jarenjs/core": "^0.66.1",
+    "@jarenjs/formats": "^0.66.1",
+    "@jarenjs/json": "^0.66.1",
+    "@jarenjs/validate": "^0.66.1"
   }
 }

package/src/data.js

@@ -13,7 +13,7 @@
  * cached by pointer string and reads are allocation-free.
  */
 
-import { equalsJson } from '@jarenjs/core/object';
+import { equalsJson, setObjectMember } from '@jarenjs/core/object';
 import { createBoundedCache } from '@jarenjs/core/cache';
 import {
   parseJSONPointer,
@@ -243,7 +243,7 @@ export function createInitialData(field) {
     if (field.children) {
       for (const child of field.children) {
         const value = createInitialData(child);
-        if (value !== undefined) obj[child.key] = value;
+        if (value !== undefined) setObjectMember(obj, child.key, value);
       }
     }
     return obj;

package/src/model.js

@@ -293,7 +293,8 @@ function buildField(rawSchema, rootSchema, pointer, key, required, depth, t) {
   // data pointer (the root field's base is the empty pointer '').
   const base = typeof effective['x-msgid'] === 'string' ? effective['x-msgid'] : pointer;
 
-  const oneOfBranches = kind === 'enum' ? getOneOfConstBranches(effective) : null;
+  const oneOfBranches = kind === 'enum' && !Array.isArray(effective.enum)
+    ? getOneOfConstBranches(effective) : null;
   const enumValues = kind === 'enum'
     ? (Array.isArray(effective.enum)
       ? effective.enum

package/src/rules.js

@@ -737,7 +737,8 @@ function extendChunks(chunks, selector) {
  * absent location arrives as `null`, exactly as the keystroke path
  * binds it.
  *
- * A field that also declares `visible` has its assert guarded by it:
+ * A field's own and ancestor `visible` rules guard its assert, each
+ * with the value/pointer bindings of the field that owns the rule:
  * the assert holds vacuously while the field is hidden. That is what
  * the keystroke path already does — `buildFormViewModel` drops hidden
  * nodes, so their assert errors never render and never count — and an
@@ -747,9 +748,11 @@ function extendChunks(chunks, selector) {
  * @param {any} assert - The authored rule document
  * @param {string} pointer - The field's data pointer
  * @param {any} [visible] - The field's `visible` rule, when it has one
+ * @param {Array<{chunks: string[], pointer: string, visible: any}>} [ancestors]
+ *   Visibility rules of ancestor fields, in root-to-parent order
  * @returns {any} The wrapped query document
  */
-function assertQuery(chunks, assert, pointer, visible) {
+function assertQuery(chunks, assert, pointer, visible, ancestors = []) {
   const depth = chunks.length - 1;
   const at = (k) => k === 0 ? chunks[0] : `$${ITEM_VAR}${k - 1}${chunks[k]}`;
   const body = visible === undefined
@@ -759,6 +762,22 @@ function assertQuery(chunks, assert, pointer, visible) {
     $let: { value: { $default: [at(depth), { $const: null }] }, pointer: { $const: pointer } },
     $return: body,
   };
+  // Every enclosing item variable is in scope here. Bind an ancestor
+  // from its own path chunks, never from the descendant's value; a
+  // nested array's visibility must read its own row at each depth.
+  for (let i = ancestors.length - 1; i >= 0; i--) {
+    const ancestor = ancestors[i];
+    const level = ancestor.chunks.length - 1;
+    const path = level === 0 ? ancestor.chunks[0]
+      : `$${ITEM_VAR}${level - 1}${ancestor.chunks[level]}`;
+    query = { $or: [{ $not: {
+      $let: {
+        value: { $default: [path, { $const: null }] },
+        pointer: { $const: ancestor.pointer },
+      },
+      $return: ancestor.visible,
+    } }, query] };
+  }
   for (let k = depth - 1; k >= 0; k--)
     query = { $every: { [`${ITEM_VAR}${k}`]: at(k) }, $satisfies: query };
   return query;
@@ -768,7 +787,7 @@ function assertQuery(chunks, assert, pointer, visible) {
  * Depth-first collection of `x-form.assert` documents with the pointer
  * and the path chunks of their data location.
  */
-function collectAsserts(schema, pointer, chunks, out) {
+function collectAsserts(schema, pointer, chunks, out, ancestors = []) {
   if (schema == null || typeof schema !== 'object' || Array.isArray(schema))
     return;
 
@@ -776,27 +795,31 @@ function collectAsserts(schema, pointer, chunks, out) {
   if (rules != null && typeof rules === 'object' && !Array.isArray(rules)
       && rules.assert !== undefined) {
     out.push({
-      query: assertQuery(chunks, rules.assert, pointer, rules.visible),
+      query: assertQuery(chunks, rules.assert, pointer, rules.visible, ancestors),
       pointer,
       message: rules.message,
     });
   }
+  const parents = rules != null && typeof rules === 'object' && !Array.isArray(rules)
+      && rules.visible !== undefined
+    ? [...ancestors, { chunks, pointer, visible: rules.visible }]
+    : ancestors;
 
   if (schema.properties != null && typeof schema.properties === 'object') {
     for (const [key, sub] of Object.entries(schema.properties)) {
       collectAsserts(sub, `${pointer}/${escapePointerKey(key)}`,
-        extendChunks(chunks, pathNameSelector(key)), out);
+        extendChunks(chunks, pathNameSelector(key)), out, parents);
     }
   }
   if (Array.isArray(schema.prefixItems)) {
     for (let i = 0; i < schema.prefixItems.length; i++)
-      collectAsserts(schema.prefixItems[i], `${pointer}/${i}`, extendChunks(chunks, `[${i}]`), out);
+      collectAsserts(schema.prefixItems[i], `${pointer}/${i}`, extendChunks(chunks, `[${i}]`), out, parents);
   }
   if (schema.items != null && typeof schema.items === 'object' && !Array.isArray(schema.items))
-    collectAsserts(schema.items, `${pointer}/-`, [...extendChunks(chunks, '[*]'), ''], out);
+    collectAsserts(schema.items, `${pointer}/-`, [...extendChunks(chunks, '[*]'), ''], out, parents);
   if (Array.isArray(schema.allOf)) {
     for (const branch of schema.allOf)
-      collectAsserts(branch, pointer, chunks, out);
+      collectAsserts(branch, pointer, chunks, out, parents);
   }
 }
 

package/src/viewmodel.js

@@ -352,7 +352,7 @@ function buildNode(field, pointer, data, ruleState, fieldErrors, element, remova
       // number, boolean and null enums, which `String(v)` is not.
       key: JSON.stringify(v) ?? 'null',
       label: field.enumLabels?.[i] ?? String(v),
-      selected: v === node.value,
+      selected: equalsJson(v, node.value),
     }));
   }
 
@@ -408,15 +408,15 @@ function buildNode(field, pointer, data, ruleState, fieldErrors, element, remova
       if (built !== null) items.push(built);
     }
     node.items = items;
-    if (field.item !== null && field.item !== undefined) {
-      node.addValue = createItemValue(field.item) ?? null;
-    }
-    else if (field.tuple !== null && field.tuple !== undefined && array.length < field.tuple.length) {
+    if (field.tuple !== null && field.tuple !== undefined && array.length < field.tuple.length) {
       // a tuple shorter than its schema grows one slot at a time, each
       // starting from ITS OWN template — that is what makes a tuple
       // loaded short (or absent) fillable at all
       node.addValue = createItemValue(field.tuple[array.length]) ?? null;
     }
+    else if (field.item !== null && field.item !== undefined) {
+      node.addValue = createItemValue(field.item) ?? null;
+    }
   }
 
   return node;