nodality 1.1.13 → 1.1.15

package/lib/validate-nodes.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.1.13
+ * nodality v1.1.15
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -36,10 +36,20 @@ import { didYouMean, suggest } from "./suggest.js";
  * the runtime, which is why it has to be reported here.
  */
 const MORPH_FIELDS = [
-    "op", "target", "from", "to",
+    "op", "target", "from", "to", "chain",
     "effect", "duration", "back", "live", "fade",
 ];
 
+/**
+ * Every key an entry in `chain` reads. `from` and `to` make the edge; the
+ * rest are the node's own settings, overridable per edge — which is why
+ * this list is MORPH_FIELDS without `op`, `target` or `chain`, an edge
+ * being able to carry neither an op nor a nested chain of its own.
+ */
+const EDGE_FIELDS = [
+    "from", "to", "effect", "duration", "back", "live", "fade",
+];
+
 /** Node families, told apart exactly the way the runtime tells them apart. */
 const familyOf = (node) => {
     if (!node || typeof node !== "object") return "invalid";
@@ -96,8 +106,13 @@ export function validateNodes(nodes, elements) {
                 push("BAD_TARGET", at, t, [], ["an element id"]);
                 return;
             }
-            // Ids are written bare in E and may be written with a leading
-            // "#" in a node; accept both rather than inventing a rule.
+            // An id may be written bare ("home") or in selector form
+            // ("#home"). Both are accepted here because both are accepted
+            // by the runtime — `bareId` in morph-node.js reduces them to
+            // one key before anything is resolved. The two must agree: for
+            // a while this check tolerated "#home" while the runtime did
+            // not, so the validator passed a node that silently never
+            // morphed, which is the exact failure it exists to prevent.
             const bare = t.startsWith("#") ? t.slice(1) : t;
             if (idsKnown && !ids.includes(bare)) {
                 push("UNKNOWN_TARGET", at, t, suggest(bare, ids), ids);
@@ -121,37 +136,109 @@ export function validateNodes(nodes, elements) {
         if (family === "design") return;   // design nodes carry their own vocabulary
 
         if (family === "morph") {
-            // The morph node's own contract. `from` and `to` are what make
-            // it a morph; without them the node is inert.
-            if (typeof node.from !== "string") {
-                push("MISSING_FIELD", `${path}.from`, node.from, [],
-                    ["the id of the element that morphs"]);
-            } else {
-                checkTargets(node.from, `${path}.from`);
+            // `from` and `to` are what make a hop; without them it is
+            // inert. Factored out because a chain edge has exactly the
+            // same two ends as a single-hop node, and the diagnostics
+            // should not differ by where the edge was written.
+            const checkEnds = (o, at) => {
+                if (typeof o.from !== "string") {
+                    push("MISSING_FIELD", `${at}.from`, o.from, [],
+                        ["the id of the element that morphs"]);
+                } else {
+                    checkTargets(o.from, `${at}.from`);
+                }
+                if (o.to === undefined) {
+                    push("MISSING_FIELD", `${at}.to`, undefined, [],
+                        ["[\"id\", ...]", "{ \"Link label\": \"id\" }"]);
+                } else if (Array.isArray(o.to)) {
+                    checkTargets(o.to, `${at}.to`);
+                } else if (o.to && typeof o.to === "object") {
+                    for (const label in o.to) {
+                        checkTargets(o.to[label], `${at}.to.${label}`);
+                    }
+                } else {
+                    push("BAD_FIELD", `${at}.to`, o.to, [],
+                        ["an array of ids, or a map of link label to id"]);
+                }
+            };
+
+            // The settings, which are hoisted defaults on the node and
+            // overrides on an edge, so both are checked the same way.
+            // `back` and `live` are compared against `false`/`true` by
+            // identity in the runtime, which makes a STRING the dangerous
+            // mistake: `live: "true"` is not `=== true`, so the live
+            // backend silently stays off and the page still works, on the
+            // other backend, looking as though the flag took.
+            const checkOpts = (o, at) => {
+                if (o.duration !== undefined &&
+                    (typeof o.duration !== "number" || !(o.duration > 0))) {
+                    push("BAD_VALUE", `${at}.duration`, o.duration, [],
+                        ["a positive number of milliseconds"]);
+                }
+                if (o.effect !== undefined &&
+                    typeof o.effect !== "string" && !Array.isArray(o.effect)) {
+                    push("BAD_FIELD", `${at}.effect`, o.effect, [],
+                        ["a preset name, or an inline array of raster nodes"]);
+                }
+                for (const flag of ["back", "live"]) {
+                    if (o[flag] !== undefined && typeof o[flag] !== "boolean") {
+                        push("BAD_VALUE", `${at}.${flag}`, o[flag], [],
+                            ["true", "false"]);
+                    }
+                }
+                if (o.fade !== undefined && typeof o.fade !== "string") {
+                    push("BAD_FIELD", `${at}.fade`, o.fade, [],
+                        ["a fade mode, as a string"]);
+                }
+            };
+
+            // A node is either one hop or a chain, and the runtime decides
+            // by looking at `chain` FIRST: `normalizeEdges` takes a
+            // non-empty chain and never reads node-level `from`/`to`. The
+            // check mirrors that order, so what passes here is what runs.
+            const chained = Array.isArray(node.chain) && node.chain.length > 0;
+
+            if (node.chain !== undefined && !Array.isArray(node.chain)) {
+                push("BAD_FIELD", `${path}.chain`, node.chain, [],
+                    ["an array of edges: [{ from, to }, ...]"]);
+            } else if (Array.isArray(node.chain) && !node.chain.length) {
+                // The runtime does not reject this — it falls back to the
+                // single-hop fields — but it is never what was meant.
+                push("BAD_VALUE", `${path}.chain`, node.chain, [],
+                    ["at least one edge, or no `chain` key at all"]);
             }
-            if (node.to === undefined) {
-                push("MISSING_FIELD", `${path}.to`, undefined, [],
-                    ["[\"id\", ...]", "{ \"Link label\": \"id\" }"]);
-            } else if (Array.isArray(node.to)) {
-                checkTargets(node.to, `${path}.to`);
-            } else if (node.to && typeof node.to === "object") {
-                for (const label in node.to) {
-                    checkTargets(node.to[label], `${path}.to.${label}`);
+
+            checkOpts(node, path);
+
+            if (chained) {
+                // `from`/`to` written BESIDE a chain are dead, not merged.
+                // Worth reporting precisely because the page still works,
+                // using the chain, so the ignored pair looks as though it
+                // took effect.
+                for (const key of ["from", "to"]) {
+                    if (node[key] !== undefined) {
+                        push("IGNORED_FIELD", `${path}.${key}`, node[key], [],
+                            ["remove it, or drop `chain` and keep the single hop"]);
+                    }
                 }
+                node.chain.forEach((edge, j) => {
+                    const at = `${path}.chain[${j}]`;
+                    if (!edge || typeof edge !== "object" || Array.isArray(edge)) {
+                        push("BAD_FIELD", at, edge, [], ["{ from, to }"]);
+                        return;
+                    }
+                    checkEnds(edge, at);
+                    checkOpts(edge, at);
+                    for (const key in edge) {
+                        if (EDGE_FIELDS.includes(key)) continue;
+                        push("UNKNOWN_PARAM", `${at}.${key}`, key,
+                            suggest(key, EDGE_FIELDS), EDGE_FIELDS);
+                    }
+                });
             } else {
-                push("BAD_FIELD", `${path}.to`, node.to, [],
-                    ["an array of ids, or a map of link label to id"]);
-            }
-            if (node.duration !== undefined &&
-                (typeof node.duration !== "number" || !(node.duration > 0))) {
-                push("BAD_VALUE", `${path}.duration`, node.duration, [],
-                    ["a positive number of milliseconds"]);
-            }
-            if (node.effect !== undefined &&
-                typeof node.effect !== "string" && !Array.isArray(node.effect)) {
-                push("BAD_FIELD", `${path}.effect`, node.effect, [],
-                    ["a preset name, or an inline array of raster nodes"]);
+                checkEnds(node, path);
             }
+
             // Unknown keys, checked here for the same reason they are
             // checked on a raster node: a morph silently ignores what it
             // does not recognise, so `duraton: 900` produces a transition

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodality",
-  "version": "1.1.13",
+  "version": "1.1.15",
   "description": "A lightweight library for declarative UI elements.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",