nodality 1.3.4 → 1.3.6

package/layout/prerender-site.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/prerender.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/progress.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/row.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/scroll-video.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/side-bar.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/side-nav-bar.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/simple-bar.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/slider-2025.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/spacer.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/stack.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/svg.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/switcher.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/table.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/text-field.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/text.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/ulist.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -176,6 +176,21 @@ toCode(indent = 0) {
         const pad = " ".repeat(indent);
         let code = `${pad}new UList()`;
 
+        // The options, so the emitted source reproduces this instance. Without
+        // this the generator wrote `new UList()` and dropped every option that
+        // had been set on it -- and since Des.set() EXECUTES the emitted
+        // source, the page rendered from code that no longer described the
+        // list. The mapper was forwarding correctly the whole time; the loss
+        // was here, at the boundary the artefact is supposed to cross.
+        const opts = Object.fromEntries(
+            Object.entries(this.options || {}).filter(([, v]) =>
+                v !== undefined && v !== null && v !== ""),
+        );
+        if (Object.keys(opts).length) {
+            code += `\n${pad}  .set(${JSON.stringify(opts, null, 2)
+                .split("\n").join(`\n${pad}  `)})`;
+        }
+
         if (this.items && this.items.length) {
             code += `\n${pad}  .setItems([\n` +
                 this.items.map(c =>

package/layout/video.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/wrap.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/layout/zoom-card.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/agent-surface.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/card-getter.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/check-page.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/codegen.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/data.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/designer.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/element-mapper.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -125,9 +125,35 @@ const navEntry = (i) =>
 // The failure this guards is silent: a composite handed content in the slot it
 // does not read emits its placeholder template, so the page renders, nothing
 // throws, and the content is simply gone.
+// Kept byte-equal to `CONTENT_SLOT` in lib/validate-nodes.js, which cannot be
+// imported here: this file pulls in every layout component and therefore a DOM,
+// and the validator has to run in a bare Node process. Two copies is the price
+// of that, and they had already drifted -- `stack` was declared here and not
+// there -- so a unit test now pins them equal rather than trusting the comment.
+//
+// The per-type descriptions below are read by scripts/generate-schema.mjs. They
+// live here because the mapper is what decides how a slot is read; before they
+// existed the generator keyed descriptions by parameter NAME across every file
+// it scanned, first writer winning, so the picker's `items` documentation was
+// served for `cards`, `nav`, `sideNav`, `table` and `ulist` as well.
+// Names whose meaning is decided by the element type, not by whichever file
+// happened to document them first. See the SCOPED note in generate-schema.mjs.
+//@scoped items
+//@scoped type
+//@scoped id
+//@ type: The element type, which selects the mapper that builds it -- "h1", "cards", "form", and so on.
+//@ id: This element's DOM id. Also what a design node's `target` names, and what `parse` recovers an element by.
+//@ cards.items: The cards. Each entry is either a data object -- { title, link, img } -- or an ARRAY of element specs, which renders as one card containing them.
+//@ nav.items: The links, each `{ title, link }` -- or a plain string.
+//@ sideNav.items: The links, each `{ title, link }` -- or a plain string.
+//@ table.items: The rows. Each entry is a `{ title, link }` or `{ text, url }` data object, a `[value, text]` pair, or an element spec.
+//@ ulist.items: The list entries, each an element spec -- `{ type, ... }` -- or a plain string.
+//@ dropdown.items: The choices, each a `[value, text]` pair -- or a plain string used as both.
+//@ radio.items: The choices, each a plain string.
 const CONTENT_SLOT = Object.freeze({
     cards: "items", table: "items", ulist: "items",
     nav: "items", sideNav: "items",
+    dropdown: "items", picker: "items", radio: "items",
     row: "children", form: "children", stack: "children", wrap: "children",
 });
 
@@ -295,6 +321,17 @@ class ElementMapper { // 22:09:58 04/11/2024
        // return new Text("Hello").set({size: "S3"});
 
         return new FlexRow().set({
+                         // Everything the author declared. Without it a row's
+                         // options were the node lookups alone, every one of
+                         // them `undefined` when no node targets this element,
+                         // so FlexRow.toCode() -- which correctly strips
+                         // undefined -- emitted `.set({})` and the emitted
+                         // source carried nothing. The empty object was the
+                         // symptom; this is the cause.
+                         ...this.elOpts(el, [
+                             "stroke", "gradient", "animation", "shadow", "span",
+                             "backgroundOp", "marginOp", "transform", "filtera", "raster",
+                         ]),
                          stroke: this.filtero("blast", el.id, obj.customOptions),
                          gradient: this.filtero("gradient", el.id, obj.customOptions),
                          animation: this.filtero("animation", el.id, obj.customOptions),
@@ -1624,6 +1661,27 @@ let elo = new Polygon({ id: "hex" })
 
         return new Text(el.text || el.value)
             .set({
+                // Everything the author declared, first, so that every option
+                // Text reads is reachable from a spec. Hand-listing the
+                // forwards left 36 of this type's 56 documented options
+                // settable only on the emitted component -- `background`,
+                // `align`, `width`, `opacity`, `radius` among them -- so a
+                // page could declare one, validate clean, and render without
+                // it. The note on `tag` below was one instance of that gap,
+                // closed one option at a time; this closes the rest.
+                //
+                // The spread comes FIRST and every assignment below overrides
+                // it, so nothing the mapper computes can be displaced by a
+                // field of the same name. The drop list is the keys this
+                // method derives from the NODE array: they belong to N, they
+                // are resolved by `filtero` below, and letting E supply them
+                // would both cross the two halves of the format and let an
+                // empty lookup overwrite an author's value with `undefined`.
+                ...this.elOpts(el, [
+                    "value",                                   // constructor argument, above
+                    "stroke", "gradient", "animation", "shadow", "span",
+                    "backgroundOp", "marginOp", "transform", "filtera", "raster",
+                ]),
                 id: el.id,
                 class: el.class,
                 color: el.color,
@@ -1662,7 +1720,14 @@ let elo = new Polygon({ id: "hex" })
 
         return new Image(el.url)
         .set({
-            ...el,
+            // elOpts rather than a raw `...el`: the raw spread put `type`,
+                // `children` and `items` into the component's OPTIONS, where
+                // they mean nothing, and -- now that toCode() serialises
+                // options -- writes them into the emitted source as well. The
+                // artefact is meant to be code a developer reads and owns, so
+                // it should not carry the specification's own bookkeeping.
+                ...this.elOpts(el),
+            url: el.url,          // skipped by elOpts; the raw spread carried it
             isFull:el.isFull,
          //   index: obj.i + "",
             animation: this.filtero("animation", el.id, obj.customOptions),
@@ -1857,12 +1922,28 @@ const blast    = this.filtero("blast", el.id, obj.customOptions);
   
 
 
+    // The author's own options, serialised into the emitted source. This
+    // mapper returns SOURCE rather than an instance, so there is nothing to
+    // spread onto -- the equivalent of `...elOpts(el)` here is to write the
+    // entries into the `.set({...})` literal being generated.
+    //
+    // They come AFTER the four template defaults and BEFORE the node ops, and
+    // that order is the contract: a default is a starting point an author may
+    // overrule, so `{type:"cards", gap:"2rem"}` wins over `gap:"1rem"`; a node
+    // is the N half of the format addressing this element by id, so it wins
+    // over E. Before this, every one of these keys was accepted by the
+    // validator, advertised by the schema, and silently dropped on the floor.
+    const authored = Object.entries(this.elOpts(obj.el, [
+      "backgroundCard",                          // consumed above, to pick the template
+      "gradient", "animation", "shadow", "marginOp", "filtera", "blast", "raster",
+    ])).map(([k, v]) => `,\n      ${JSON.stringify(k)}: ${JSON.stringify(v)}`).join("");
+
     return ` new FlexGrid()
     .set({
       colat: "700px",
       wrap: true,
       align: "center",
-      gap: "1rem"
+      gap: "1rem"${authored}
        ${
         gradient !== undefined ? `,\n      gradient: ${JSON.stringify(gradient)}` : ""
       }${
@@ -2118,7 +2199,13 @@ static form(obj){
         // slice on a word. A caller-supplied `size` still passes through.
         const wrapper = new Wrapper(kind)
             .set({
-                ...el,
+                // elOpts rather than a raw `...el`: the raw spread put `type`,
+                // `children` and `items` into the component's OPTIONS, where
+                // they mean nothing, and -- now that toCode() serialises
+                // options -- writes them into the emitted source as well. The
+                // artefact is meant to be code a developer reads and owns, so
+                // it should not carry the specification's own bookkeeping.
+                ...this.elOpts(el),
                 font: el.font ?? "Arial",
                 stroke: this.filtero("blast", el.id, obj.customOptions),
                 gradient: this.filtero("gradient", el.id, obj.customOptions),
@@ -2158,7 +2245,13 @@ static form(obj){
         // output of getElType on a non-heading type.
         const list = new UList(kind)
             .set({
-                ...el,
+                // elOpts rather than a raw `...el`: the raw spread put `type`,
+                // `children` and `items` into the component's OPTIONS, where
+                // they mean nothing, and -- now that toCode() serialises
+                // options -- writes them into the emitted source as well. The
+                // artefact is meant to be code a developer reads and owns, so
+                // it should not carry the specification's own bookkeeping.
+                ...this.elOpts(el),
                 font: el.font ?? "Arial",
                 stroke: this.filtero("blast", el.id, obj.customOptions),
                 gradient: this.filtero("gradient", el.id, obj.customOptions),

package/lib/element-params.generated.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/keyframe-animation.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/link-getter.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/morph-node.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/normalize-spec.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/parse-html.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/raster-inspect.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/raster-ops.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/raster-presets.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/resolve-refs.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/scroll-video.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/seo.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/stacker.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/suggest.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/theme.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/transform-anim.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/transition.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */

package/lib/validate-nodes.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.3.4
+ * nodality v1.3.6
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -158,9 +158,18 @@ const familyOf = (node) => {
 // be demonstrated is absent, and absent means silent: reporting a slot that
 // might work would stop `preview` rendering a page that renders, which 1.2.7
 // established is the costlier direction to be wrong in.
+//
+// Four types had that evidence and were missing anyway. `stack` was declared in
+// the mapper's copy of this table and not in this one, so the two had already
+// drifted -- which is what the comment on SPEC_ITEMS below warns about, one
+// table over. `dropdown`, `picker` and `radio` read `items` as choices and were
+// in neither. The omission was invisible to the drift test because the test
+// iterated THIS map, so a type absent from it was a type it never checked; the
+// test now iterates the element registry instead.
 export const CONTENT_SLOT = {
     cards: "items", nav: "items", sideNav: "items", table: "items", ulist: "items",
-    row: "children", form: "children", wrap: "children",
+    dropdown: "items", picker: "items", radio: "items",
+    row: "children", form: "children", stack: "children", wrap: "children",
 };
 
 // Of the types that read `items`, which read the entries as ELEMENT SPECS
@@ -172,6 +181,41 @@ export const CONTENT_SLOT = {
 // drifted before 1.2.8.
 export const SPEC_ITEMS = new Set(["ulist"]);
 
+// Of the types that read `items` but NOT as flat element specs, what an entry
+// may be. Measured by rendering every shape against every type rather than read
+// off the mappers, because the mappers disagree: `table` takes an element spec,
+// `cards` takes one only inside a nested array, and `nav` takes neither.
+//
+// This guards the expensive kind of failure rather than the cheap one. An entry
+// carrying `type` IS a well-formed element spec, so nothing here is a typo and
+// near-miss detection cannot reach it: `cards` renders an empty card, `nav`
+// drops the entry, both pages render, and the content is simply gone. That is
+// the "validates and is wrong" case, and it is the one shape a generator
+// reaches for first, because every other slot in the format takes element
+// specs.
+//
+// `keys` are the fields that prove an entry was MEANT as data. A report fires
+// only when none of them is present -- i.e. only when the entry cannot render
+// anything at all -- because a false report does not annotate the page, it
+// prevents it.
+export const ITEM_SHAPE = {
+    cards: {
+        nest: true, keys: ["title", "link", "img"],
+        valid: 'a data object -- { title, link, img } -- or an ARRAY of element specs, which renders as one card containing them',
+    },
+    nav: {
+        nest: false, keys: ["title", "link"],
+        valid: '{ title, link }, or a plain string',
+    },
+    sideNav: {
+        nest: false, keys: ["title", "link"],
+        valid: '{ title, link }, or a plain string',
+    },
+    dropdown: { nest: false, keys: [], valid: 'a plain string, or a [value, text] pair' },
+    picker:   { nest: false, keys: [], valid: 'a plain string, or a [value, text] pair' },
+    radio:    { nest: false, keys: [], valid: 'a plain string' },
+};
+
 export function validateNodes(nodes, elements, defs) {
     const errors = [];
     const push = (code, path, got, suggestions, valid) => {
@@ -433,6 +477,43 @@ export function validateNodes(nodes, elements, defs) {
                         }
                     });
                 }
+
+                // Phase S8: an entry in the wrong SHAPE for a type that reads
+                // `items` as something other than element specs. The sibling
+                // check above walks entries that ARE specs; this one reports
+                // entries that are specs where a spec renders nothing.
+                //
+                // Fires only when the entry carries none of the fields the type
+                // reads, so an entry meant as data is never reported, and a
+                // `$ref` -- resolved later -- is left alone. The suggestion
+                // hands back the replacement rather than describing it, which
+                // 8.7.4 measured as the difference between a report a model can
+                // act on and one it cannot.
+                const shape = ITEM_SHAPE[el.type];
+                if (shape && Array.isArray(el.items)) {
+                    el.items.forEach((entry, k) => {
+                        const at = `${p}.items[${k}]`;
+                        if (entry === null || typeof entry !== "object") return;
+                        if (Array.isArray(entry)) return;   // nested spec, or a [value, text] pair
+                        if (isRef(entry)) return;
+                        if (shape.keys.some((key) => entry[key] !== undefined)) return;
+
+                        const text = ["text", "title", "label"]
+                            .map((key) => entry[key]).find((v) => typeof v === "string");
+                        const suggestions = [];
+                        if (shape.nest && typeof entry.type === "string") {
+                            suggestions.push(JSON.stringify([entry]));
+                        } else if (shape.keys.length) {
+                            suggestions.push(JSON.stringify({
+                                title: text === undefined ? "..." : text,
+                                link: entry.url || entry.link || "#",
+                            }));
+                        } else if (text !== undefined) {
+                            suggestions.push(JSON.stringify(text));
+                        }
+                        push("WRONG_ITEM_SHAPE", at, entry, suggestions, [shape.valid]);
+                    });
+                }
             });
         };
         walkEls(toWalk, "elements");