@yuneta/gobj-ui 5.2.0 → 5.3.0

package/src/node_tree_model.test.js

@@ -0,0 +1,282 @@
+/***********************************************************************
+ *          node_tree_model.test.js
+ *
+ *      Unit tests for the pure node-tree helpers.
+ ***********************************************************************/
+import { test, expect } from "vitest";
+import {
+    chrome_visible,
+    split_subpath,
+    head_tail,
+    join_route,
+    projection_renders,
+    child_nav_items,
+    normalize_spec,
+} from "./node_tree_model.js";
+
+
+/***************************************************************
+ *      subpath splitting
+ ***************************************************************/
+test("split_subpath drops empty segments", () => {
+    expect(split_subpath("a/b/c")).toEqual(["a", "b", "c"]);
+    expect(split_subpath("/a//b/")).toEqual(["a", "b"]);
+    expect(split_subpath("")).toEqual([]);
+    expect(split_subpath(null)).toEqual([]);
+});
+
+test("head_tail names the child and hands down the rest", () => {
+    expect(head_tail("energy/north/m1")).toEqual({head: "energy", tail: "north/m1"});
+    expect(head_tail("energy")).toEqual({head: "energy", tail: ""});
+    expect(head_tail("")).toEqual({head: "", tail: ""});
+});
+
+
+/***************************************************************
+ *      canonical routes
+ ***************************************************************/
+test("join_route builds the canonical route of a node", () => {
+    expect(join_route("/cards", ["energy", "north"])).toBe("/cards/energy/north");
+    expect(join_route("/cards", [])).toBe("/cards");
+    expect(join_route("/cards/", ["a"])).toBe("/cards/a");
+    expect(join_route("cards", ["a"])).toBe("/cards/a");
+    expect(join_route("/", ["a", "b"])).toBe("/a/b");
+});
+
+
+/***************************************************************
+ *      projections
+ ***************************************************************/
+test("no projection means: show my children as cards, no chrome", () => {
+    expect(projection_renders(undefined, "index")).toEqual([{layout: "cards"}]);
+    expect(projection_renders(undefined, "chrome")).toEqual([]);
+});
+
+test("a bare string or render object is the INDEX projection only", () => {
+    expect(projection_renders("vertical", "index")).toEqual([{layout: "vertical"}]);
+    expect(projection_renders("vertical", "chrome")).toEqual([]);
+    expect(projection_renders({layout: "cards", show_label: false}, "index"))
+        .toEqual([{layout: "cards", show_label: false}]);
+});
+
+test("index + chrome, chrome as an array (tabs on desktop, backbar on mobile)", () => {
+    let p = {
+        index: {layout: "cards"},
+        chrome: [
+            {layout: "tabs", show_on: ">=tablet"},
+            {layout: "backbar", show_on: "<tablet"}
+        ]
+    };
+    expect(projection_renders(p, "index")).toEqual([{layout: "cards"}]);
+    expect(projection_renders(p, "chrome")).toEqual([
+        {layout: "tabs", show_on: ">=tablet"},
+        {layout: "backbar", show_on: "<tablet"}
+    ]);
+});
+
+test("projection_renders returns copies, never the caller's objects", () => {
+    let p = {index: {layout: "cards"}};
+    let r = projection_renders(p, "index");
+    r[0].layout = "tabs";
+    expect(p.index.layout).toBe("cards");
+});
+
+
+/***************************************************************
+ *      children → nav items
+ ***************************************************************/
+test("child_nav_items builds C_YUI_NAV items with canonical routes", () => {
+    let children = [
+        {id: "a", label: "Alpha", icon: "yi-eye", tooltip: "", disabled: false},
+        {id: "b", label: "Beta",  icon: "",       tooltip: "hi", disabled: true},
+    ];
+    let items = child_nav_items(children, (id) => `/cards/${id}`);
+    expect(items).toEqual([
+        {id: "a", name: "Alpha", route: "/cards/a", icon: "yi-eye"},
+        {id: "b", name: "Beta",  route: "/cards/b", tooltip: "hi", disabled: true},
+    ]);
+});
+
+
+/***************************************************************
+ *      spec validation
+ ***************************************************************/
+test("normalize_spec fills defaults and recurses into children", () => {
+    let errors = [];
+    let spec = normalize_spec({
+        id: "root",
+        children: [
+            {id: "a", label: "Alpha", content: {gclass: "C_TEST_VIEW"}},
+            {id: "b"}
+        ]
+    }, errors, "/");
+
+    expect(errors).toEqual([]);
+    expect(spec.id).toBe("root");
+    expect(spec.label).toBe("root");            /*  label defaults to id  */
+    expect(spec.children.length).toBe(2);
+    expect(spec.children[0].content).toEqual({gclass: "C_TEST_VIEW", kw: {}});
+    expect(spec.children[1].label).toBe("b");
+    expect(spec.children[1].content).toBe(null);
+});
+
+test("an id is ONE url segment", () => {
+    let errors = [];
+    expect(normalize_spec({id: "a/b"}, errors, "/")).toBe(null);
+    expect(errors.length).toBe(1);
+    expect(errors[0]).toMatch(/contains '\/'/);
+});
+
+test("a node without id is rejected, loudly", () => {
+    let errors = [];
+    expect(normalize_spec({label: "no id"}, errors, "/")).toBe(null);
+    expect(errors[0]).toMatch(/has no 'id'/);
+});
+
+test("sibling ids must be unique — they are url segments", () => {
+    let errors = [];
+    expect(normalize_spec({
+        id: "root",
+        children: [{id: "dup"}, {id: "dup"}]
+    }, errors, "/")).toBe(null);
+    expect(errors.some((e) => /duplicated child id 'dup'/.test(e))).toBe(true);
+});
+
+test("an unknown layout is a config error, not a silent fallback", () => {
+    let errors = [];
+    expect(normalize_spec({id: "x", projection: "carousel"}, errors, "/")).toBe(null);
+    expect(errors[0]).toMatch(/unknown projection layout 'carousel'/);
+
+    errors = [];
+    expect(normalize_spec({
+        id: "x",
+        projection: {index: {layout: "grid"}}
+    }, errors, "/")).toBe(null);
+    expect(errors[0]).toMatch(/unknown projection.index layout 'grid'/);
+});
+
+test("content needs a gclass", () => {
+    let errors = [];
+    expect(normalize_spec({id: "x", content: {kw: {}}}, errors, "/")).toBe(null);
+    expect(errors[0]).toMatch(/'content.gclass' is required/);
+});
+
+test("errors name the offending node's path", () => {
+    let errors = [];
+    normalize_spec({
+        id: "root",
+        children: [{id: "energy", children: [{label: "orphan"}]}]
+    }, errors, "/");
+    expect(errors[0]).toMatch(/'\/root\/energy\/'/);
+});
+
+
+/***************************************************************
+ *      chrome depth
+ ***************************************************************/
+test("no declared chrome_depth means every ancestor paints its strip", () => {
+    expect(chrome_visible(1, null)).toBe(true);
+    expect(chrome_visible(5, null)).toBe(true);
+    expect(chrome_visible(3, undefined)).toBe(true);
+});
+
+test("chrome_depth caps how many strips are painted above the tip", () => {
+    /*  distance 1 is the tip's own parent  */
+    expect(chrome_visible(1, 1)).toBe(true);
+    expect(chrome_visible(2, 1)).toBe(false);
+    expect(chrome_visible(3, 1)).toBe(false);
+    expect(chrome_visible(1, 0)).toBe(false);      /*  no chrome at all  */
+    expect(chrome_visible(2, 2)).toBe(true);
+});
+
+test("chrome_depth is validated as a non-negative integer", () => {
+    let errors = [];
+    expect(normalize_spec({id: "x", chrome_depth: 2}, errors, "/").chrome_depth).toBe(2);
+    expect(normalize_spec({id: "x", chrome_depth: 0}, errors, "/").chrome_depth).toBe(0);
+    expect(normalize_spec({id: "x"}, errors, "/").chrome_depth).toBe(-1);   /*  inherit  */
+    expect(errors).toEqual([]);
+
+    expect(normalize_spec({id: "x", chrome_depth: -2}, errors, "/")).toBe(null);
+    expect(errors[0]).toMatch(/must be an integer >= 0/);
+});
+
+test("normalize_spec accepts its own output (every level re-normalizes)", () => {
+    let errors = [];
+    let once = normalize_spec({
+        id: "root",
+        chrome_depth: 1,
+        children: [{id: "a", children: [{id: "b"}]}]
+    }, errors, "/");
+    let twice = normalize_spec(once, errors, "/");
+    expect(errors).toEqual([]);
+    expect(twice).toEqual(once);
+});
+
+
+/***************************************************************
+ *      aliases — the tree's paths are a contract
+ ***************************************************************/
+test("aliases carry the former ids of a node", () => {
+    let errors = [];
+    let spec = normalize_spec({id: "north", aliases: ["hall1", "h1"]}, errors, "/");
+    expect(errors).toEqual([]);
+    expect(spec.aliases).toEqual(["hall1", "h1"]);
+    expect(normalize_spec({id: "x"}, errors, "/").aliases).toEqual([]);
+});
+
+test("an alias is one url segment, like an id", () => {
+    let errors = [];
+    expect(normalize_spec({id: "x", aliases: ["a/b"]}, errors, "/")).toBe(null);
+    expect(errors[0]).toMatch(/is not a valid id/);
+
+    errors = [];
+    expect(normalize_spec({id: "x", aliases: "hall1"}, errors, "/")).toBe(null);
+    expect(errors[0]).toMatch(/'aliases' must be an array/);
+});
+
+
+/***************************************************************
+ *      link — where structure ends and data begins
+ ***************************************************************/
+test("a link declares the data space and its viewer", () => {
+    let errors = [];
+    let spec = normalize_spec({
+        id: "m1",
+        link: {kind: "tranger", gclass: "C_TRANGER_VIEW", kw: {topic: "t"}}
+    }, errors, "/");
+    expect(errors).toEqual([]);
+    expect(spec.link).toEqual({
+        kind: "tranger", gclass: "C_TRANGER_VIEW", kw: {topic: "t"}
+    });
+    expect(normalize_spec({id: "x"}, errors, "/").link).toBe(null);
+});
+
+test("a link needs both what it points into and what reads it", () => {
+    let errors = [];
+    expect(normalize_spec({id: "m1", link: {gclass: "C_V"}}, errors, "/")).toBe(null);
+    expect(errors[0]).toMatch(/'link.kind' is required/);
+
+    errors = [];
+    expect(normalize_spec({id: "m1", link: {kind: "tranger"}}, errors, "/")).toBe(null);
+    expect(errors[0]).toMatch(/'link.gclass' is required/);
+});
+
+test("below a link there are no nodes — link + children is a contradiction", () => {
+    let errors = [];
+    expect(normalize_spec({
+        id: "m1",
+        link: {kind: "tranger", gclass: "C_V"},
+        children: [{id: "nope"}]
+    }, errors, "/")).toBe(null);
+    expect(errors.some((e) => /both 'link' and 'children'/.test(e))).toBe(true);
+});
+
+test("a link IS the node's content — declaring both is rejected", () => {
+    let errors = [];
+    expect(normalize_spec({
+        id: "m1",
+        content: {gclass: "C_OTHER"},
+        link: {kind: "tranger", gclass: "C_V"}
+    }, errors, "/")).toBe(null);
+    expect(errors.some((e) => /both 'link' and 'content'/.test(e))).toBe(true);
+});

package/src/route_map_model.js

@@ -138,6 +138,45 @@ function collect_routes(nodes, into)
     }
 }
 
+/************************************************************
+ *  A route can be reached from more than one surface: the primary
+ *  menu, a drawer, an account dropdown.  Each occurrence rendered
+ *  its whole SUBTREE, so a branch reachable three ways was drawn
+ *  three times — bearable when a section had four children, noise
+ *  once a node tree hangs there with fourteen.
+ *
+ *  Exactly one occurrence owns the subtree; the others become
+ *  references (`ref: true`, no children) — still real, clickable
+ *  routes, just not repeated structure.
+ *
+ *  Who owns it: the first occurrence in the NAV, then in `other`,
+ *  then in the toolbar.  The nav is where the app's structure
+ *  lives; a toolbar entry pointing at the same route is a
+ *  shortcut — a non-structural edge — and hanging the tree off it
+ *  would bury the whole structure inside the account menu.
+ ************************************************************/
+function dedupe_subtrees(groups)
+{
+    let owner = {};
+    let visit = (node) => {
+        if(node.route) {
+            if(owner[node.route] === undefined) {
+                owner[node.route] = node;
+            } else if(owner[node.route] !== node) {
+                node.ref = true;
+                node.children = [];
+                return;   /*  a reference has no subtree to walk  */
+            }
+        }
+        if(Array.isArray(node.children)) {
+            node.children.forEach(visit);
+        }
+    };
+    for(let group of groups) {
+        group.forEach(visit);
+    }
+}
+
 /************************************************************
  *  Mark "you are here": the node whose route best matches
  *  current_route — exact hit wins, else the LONGEST declared
@@ -151,6 +190,11 @@ function mark_current(groups, current_route)
     }
     let best = null;
     let visit = (n) => {
+        /*  Never on a reference: the mark belongs on the occurrence
+         *  that carries the structure, not on a shortcut to it. */
+        if(n.ref) {
+            return;
+        }
         if(n.route) {
             if(n.route === current_route) {
                 if(!best || best.node.route !== current_route) {
@@ -303,6 +347,10 @@ function build_nav_map(input)
     }
     other.forEach(enrich);
 
+    /*  One subtree, one place.  Before marking "you are here", so the
+     *  mark lands on the occurrence that kept its children. */
+    dedupe_subtrees([nav, other, toolbar]);
+
     /*  The brand is rendered as the tree's ROOT row (shell_route_map),
      *  so it is markable like any other route — and it is the only
      *  rendered node in neither group, which left an app whose brand

package/src/route_map_model.test.js

@@ -207,3 +207,73 @@ describe("build_nav_map", () => {
         expect(marked).toEqual([]);
     });
 });
+
+
+/***************************************************************
+ *      one subtree per route
+ ***************************************************************/
+test("a route reachable from several surfaces keeps ONE subtree", () => {
+    let config = {
+        toolbar: {items: [
+            {id: "user", type: "action", action: {type: "dropdown", items: [
+                {id: "d-cards", name: "Go to Cards",
+                 action: {type: "navigate", route: "/cards"}}
+            ]}}
+        ]},
+        menu: {
+            primary: {items: [
+                {id: "cards", name: "Cards", route: "/cards", target: {gclass: "C_X"}}
+            ]},
+            quick: {items: [
+                {id: "cards", name: "Cards", route: "/cards"}
+            ]}
+        }
+    };
+    let map = build_nav_map({
+        config: config,
+        item_index: {"/cards": {item: {id: "cards"}, target: {gclass: "C_X"}}},
+        sub_routes: {"/cards": [
+            {route: "/cards/energy", label: "Energy", children: [
+                {route: "/cards/energy/north", label: "North", children: []}
+            ]}
+        ]},
+    });
+
+    /*  The NAV owns it: primary is the first occurrence there.  */
+    let primary = map.nav.find((n) => n.route === "/cards");
+    expect(primary.ref).toBeUndefined();
+    expect(primary.children.length).toBe(1);
+    expect(primary.children[0].children.length).toBe(1);
+
+    /*  The drawer copy (a group inside nav) and the account entry are
+     *  references: live routes, no repeated branch.  */
+    let quick = map.nav.find((n) => n.kind === "group" && n.id === "quick");
+    expect(quick.children[0].route).toBe("/cards");
+    expect(quick.children[0].ref).toBe(true);
+    expect(quick.children[0].children).toEqual([]);
+
+    let dropdown = map.toolbar[0].children[0];
+    expect(dropdown.route).toBe("/cards");
+    expect(dropdown.ref).toBe(true);
+    expect(dropdown.children).toEqual([]);
+});
+
+test("'you are here' lands on the owner, never on a reference", () => {
+    let config = {
+        toolbar: {items: [
+            {id: "user", type: "action", action: {type: "dropdown", items: [
+                {id: "d-cards", action: {type: "navigate", route: "/cards"}}
+            ]}}
+        ]},
+        menu: {primary: {items: [
+            {id: "cards", name: "Cards", route: "/cards", target: {gclass: "C_X"}}
+        ]}}
+    };
+    let map = build_nav_map({
+        config: config,
+        item_index: {"/cards": {item: {id: "cards"}, target: {gclass: "C_X"}}},
+        current_route: "/cards",
+    });
+    expect(map.nav.find((n) => n.route === "/cards").current).toBe(true);
+    expect(map.toolbar[0].children[0].current).toBeUndefined();
+});

package/src/route_resolver.js

@@ -21,6 +21,11 @@
  *   - root `/` is NEVER an ancestor catch-all (it only matches
  *     exactly): otherwise every typo route would silently mount
  *     the home view and the unknown-route diagnostic would die.
+ *     ONE exception, opt-in: an entry whose target declares
+ *     `owns_subtree` is a view that resolves the tail ITSELF and
+ *     says so when a segment names nothing — a C_YUI_NODE tree
+ *     rooted at `/`.  The diagnostic is not lost there, it moves
+ *     one layer down to whoever actually knows the names.
  *   - nothing matched                  → entry as found (may be
  *     null or a targetless submenu parent), subpath "".
  ************************************************************/
@@ -59,6 +64,12 @@ function resolve_route(item_index, route)
             parts.pop();
             let cand = "/" + parts.join("/");
             if(cand === "/") {
+                let root = item_index["/"];
+                if(root && root.target && root.target.owns_subtree) {
+                    entry = root;
+                    matched_route = "/";
+                    subpath = route.replace(/^\/+/, "");
+                }
                 break;
             }
             let e = item_index[cand];

package/src/shell_route_map.css

@@ -74,11 +74,21 @@
     flex: 1 1 auto;
     max-height: none;
 }
+/*  FOUR characters per level, house rule: the tree is read as
+ *  indentation and it has to be the same four everywhere (the JSON
+ *  viewer, the raw dumps, this map).  `ch` follows the row's own
+ *  monospace font, so the guides stay aligned with the routes. */
 .ROUTEMAP_UL {
     list-style: none;
     margin: 0;
-    padding-left: 1.1rem;
-    border-left: 1px dotted var(--bulma-border, #b5b5b5);
+    padding-left: 4ch;
+    /*  The guide is what makes the depth READABLE — at four levels the
+     *  eye follows the line, not the offset.  Dotted at 1px in the weak
+     *  border colour was almost invisible against the panel; solid, in
+     *  the stronger border shade, still reads as chrome but can be
+     *  followed.  Both shades are Bulma vars, so it re-shades itself in
+     *  the dark theme instead of turning into a black hairline. */
+    border-left: 1px solid var(--bulma-border-hover, #8c8c8c);
 }
 .ROUTEMAP_ROOT {
     padding-left: 0;
@@ -167,6 +177,30 @@ a.ROUTEMAP_LINK .ROUTEMAP_NAME {
     background: rgba(120, 150, 255, 0.16) !important;
     outline-color: rgba(120, 150, 255, 0.55);
 }
+/*--- reference row: this route's subtree is drawn where the nav owns
+ *    it, so the copy reachable from a drawer or the account menu is a
+ *    live link without the repeated branch.  Quiet on purpose: it is a
+ *    footnote, not a second structure. ---*/
+.ROUTEMAP_REFS_TOGGLE {
+    display: inline-flex;
+    align-items: center;
+    white-space: nowrap;
+    color: var(--bulma-text-weak, #7a7a7a);
+}
+
+.ROUTEMAP_REF {
+    font-size: 0.68rem;
+    letter-spacing: 0.03em;
+    padding: 0.02rem 0.4rem;
+    border-radius: 0.25rem;
+    border: 1px solid var(--bulma-border-weak, #dbdbdb);
+    color: var(--bulma-text-weak, #7a7a7a);
+    white-space: nowrap;
+}
+.ROUTEMAP_ROW.ROUTEMAP_IS_REF .ROUTEMAP_NAME {
+    font-weight: 400;
+}
+
 .ROUTEMAP_HERE {
     font-size: 0.68rem;
     font-weight: 700;