@yuneta/gobj-ui 2.6.0 → 4.0.0

package/src/json_view_helpers.js

@@ -0,0 +1,214 @@
+/***********************************************************************
+ *          json_view_helpers.js
+ *
+ *      Pure, testable logic behind C_YUI_JSON (the lazy JSON tree
+ *      viewer).  Kept out of the gclass so it can be unit-tested with
+ *      no DOM: collapsed-sentinel detection, path (segments) algebra,
+ *      search matching, timestamp recognition/formatting and the JSON
+ *      type discriminator.
+ *
+ *      Path convention mirrors the C kernel (kw_collapse / kw_find_path
+ *      in kwid.c): segments are joined by the backtick delimiter, arrays
+ *      are indexed by their numeric position.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/*
+ *  Path delimiter, identical to the kernel's `delimiter` in kwid.c.
+ */
+export const JSON_PATH_DELIMITER = "`";
+
+/************************************************************
+ *   JSON type discriminator (viewer vocabulary)
+ ************************************************************/
+export function json_type(value)
+{
+    if(value === null) {
+        return "null";
+    }
+    if(Array.isArray(value)) {
+        return "array";
+    }
+    switch(typeof value) {
+        case "string":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "object":
+            return "object";
+        default:
+            return "unknown";
+    }
+}
+
+/************************************************************
+ *   Detect a kw_collapse() sentinel.
+ *
+ *   The kernel replaces an over-limit dict with:
+ *          { "__collapsed__": { "path": ..., "size": N } }
+ *   and an over-limit array with:
+ *          [ { "__collapsed__": { "path": ..., "size": N } } ]
+ *
+ *   Returns { size, path, is_array } or null.
+ ************************************************************/
+export function is_collapsed(value)
+{
+    if(value && typeof value === "object" && !Array.isArray(value)) {
+        let keys = Object.keys(value);
+        if(keys.length === 1 && keys[0] === "__collapsed__") {
+            let c = value.__collapsed__ || {};
+            return {size: c.size, path: c.path, is_array: false};
+        }
+        return null;
+    }
+    if(Array.isArray(value) && value.length === 1) {
+        let e = value[0];
+        if(e && typeof e === "object" && !Array.isArray(e) &&
+                Object.keys(e).length === 1 && e.__collapsed__)
+        {
+            let c = e.__collapsed__ || {};
+            return {size: c.size, path: c.path, is_array: true};
+        }
+    }
+    return null;
+}
+
+/************************************************************
+ *   Join / split absolute path segments (kernel convention)
+ ************************************************************/
+export function seg_join(segments)
+{
+    return segments.map(function(s) {
+        return String(s);
+    }).join(JSON_PATH_DELIMITER);
+}
+
+export function seg_split(path)
+{
+    if(path === "" || path === null || path === undefined) {
+        return [];
+    }
+    return path.split(JSON_PATH_DELIMITER);
+}
+
+/************************************************************
+ *   Walk a JSON tree by absolute segments; undefined if the
+ *   path does not resolve.
+ ************************************************************/
+export function get_by_segments(root, segments)
+{
+    let v = root;
+    for(let seg of segments) {
+        if(v === null || v === undefined) {
+            return undefined;
+        }
+        if(Array.isArray(v)) {
+            v = v[Number(seg)];
+        } else if(typeof v === "object") {
+            v = v[seg];
+        } else {
+            return undefined;
+        }
+    }
+    return v;
+}
+
+/************************************************************
+ *   Set a value at absolute segments (mutates root).
+ *
+ *   segments == [] means "replace the whole root" — the caller
+ *   must use the RETURNED value in that case (a primitive/array
+ *   root cannot be mutated in place).
+ ************************************************************/
+export function set_by_segments(root, segments, new_value)
+{
+    if(segments.length === 0) {
+        return new_value;
+    }
+    let parent = get_by_segments(root, segments.slice(0, -1));
+    if(parent === null || parent === undefined || typeof parent !== "object") {
+        return root;
+    }
+    let last = segments[segments.length - 1];
+    if(Array.isArray(parent)) {
+        parent[Number(last)] = new_value;
+    } else {
+        parent[last] = new_value;
+    }
+    return root;
+}
+
+/************************************************************
+ *   Does `value` (or any loaded descendant / its own key)
+ *   contain the lower-cased search term?
+ *
+ *   Collapsed (not-yet-loaded) subtrees can't be searched, so
+ *   they never match on content — only their key can match,
+ *   which the renderer checks separately.
+ ************************************************************/
+export function subtree_matches(value, term)
+{
+    if(!term) {
+        return true;
+    }
+    if(is_collapsed(value)) {
+        return false;
+    }
+    let type = json_type(value);
+    if(type === "object") {
+        for(let [k, v] of Object.entries(value)) {
+            if(String(k).toLowerCase().includes(term)) {
+                return true;
+            }
+            if(subtree_matches(v, term)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    if(type === "array") {
+        for(let v of value) {
+            if(subtree_matches(v, term)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    return String(value).toLowerCase().includes(term);
+}
+
+/************************************************************
+ *   Fields whose numeric value is an epoch timestamp.
+ *   Mirrors the timestampTag list wired into C_YUI_FORM's
+ *   jsoneditor control, so the two viewers agree.
+ ************************************************************/
+export function is_time_field(field)
+{
+    return field === "__t__" || field === "__tm__" ||
+        field === "tm" || field === "t" || field === "time" ||
+        field === "from_t" || field === "to_t" ||
+        field === "t_input" || field === "t_output" ||
+        field === "from_tm" || field === "to_tm";
+}
+
+/************************************************************
+ *   Format an epoch value as a local wall-clock string.
+ *   Accepts seconds or milliseconds; returns null when the
+ *   value is not a usable positive timestamp (0 == "unset").
+ ************************************************************/
+export function format_epoch(value)
+{
+    if(typeof value !== "number" || !isFinite(value) || value <= 0) {
+        return null;
+    }
+    let ms = Math.abs(value) < 1e12 ? value * 1000 : value;
+    let d = new Date(ms);
+    if(isNaN(d.getTime())) {
+        return null;
+    }
+    return d.toLocaleString();
+}

package/src/json_view_helpers.test.js

@@ -0,0 +1,135 @@
+/***********************************************************************
+ *          json_view_helpers.test.js
+ *
+ *      Unit tests for the pure logic of C_YUI_JSON.
+ *      Run with: npm test
+ ***********************************************************************/
+import { test, expect } from "vitest";
+import {
+    json_type,
+    is_collapsed,
+    seg_join,
+    seg_split,
+    get_by_segments,
+    set_by_segments,
+    subtree_matches,
+    is_time_field,
+    format_epoch,
+} from "./json_view_helpers.js";
+
+
+/*============================================================
+ *      json_type
+ *============================================================*/
+test("json_type discriminates every JSON kind", () => {
+    expect(json_type(null)).toBe("null");
+    expect(json_type("x")).toBe("string");
+    expect(json_type(3)).toBe("number");
+    expect(json_type(true)).toBe("boolean");
+    expect(json_type([])).toBe("array");
+    expect(json_type({})).toBe("object");
+});
+
+
+/*============================================================
+ *      is_collapsed — both kernel sentinel shapes
+ *============================================================*/
+test("is_collapsed detects the dict sentinel", () => {
+    let v = {__collapsed__: {path: "topics`nodes", size: 4231}};
+    let c = is_collapsed(v);
+    expect(c).not.toBeNull();
+    expect(c.size).toBe(4231);
+    expect(c.path).toBe("topics`nodes");
+    expect(c.is_array).toBe(false);
+});
+
+test("is_collapsed detects the array sentinel", () => {
+    let v = [{__collapsed__: {path: "topics`rows", size: 99}}];
+    let c = is_collapsed(v);
+    expect(c).not.toBeNull();
+    expect(c.size).toBe(99);
+    expect(c.is_array).toBe(true);
+});
+
+test("is_collapsed ignores ordinary dicts/arrays", () => {
+    expect(is_collapsed({a: 1, __collapsed__: 2})).toBeNull();
+    expect(is_collapsed({a: 1})).toBeNull();
+    expect(is_collapsed([1, 2])).toBeNull();
+    expect(is_collapsed([{a: 1}])).toBeNull();
+    expect(is_collapsed("x")).toBeNull();
+});
+
+
+/*============================================================
+ *      segments algebra
+ *============================================================*/
+test("seg_join / seg_split round-trip with the backtick delimiter", () => {
+    expect(seg_join(["topics", "nodes", 4])).toBe("topics`nodes`4");
+    expect(seg_split("topics`nodes`4")).toEqual(["topics", "nodes", "4"]);
+    expect(seg_split("")).toEqual([]);
+    expect(seg_join([])).toBe("");
+});
+
+test("get_by_segments walks dicts and arrays (numeric index)", () => {
+    let root = {a: {b: [{id: "x"}, {id: "y"}]}};
+    expect(get_by_segments(root, ["a", "b", "1", "id"])).toBe("y");
+    expect(get_by_segments(root, ["a", "nope"])).toBeUndefined();
+    expect(get_by_segments(root, [])).toBe(root);
+});
+
+test("set_by_segments splices a fetched subtree at a dict path", () => {
+    let root = {topics: {nodes: {__collapsed__: {path: "topics`nodes", size: 5}}}};
+    let full = {n1: {id: "n1"}, n2: {id: "n2"}};
+    set_by_segments(root, ["topics", "nodes"], full);
+    expect(root.topics.nodes).toBe(full);
+});
+
+test("set_by_segments splices at an array index", () => {
+    let root = {rows: [ [{__collapsed__: {path: "rows`0", size: 3}}] ]};
+    set_by_segments(root, ["rows", "0"], [10, 20, 30]);
+    expect(root.rows[0]).toEqual([10, 20, 30]);
+});
+
+test("set_by_segments with [] returns the replacement (root swap)", () => {
+    let out = set_by_segments({old: 1}, [], {fresh: 2});
+    expect(out).toEqual({fresh: 2});
+});
+
+
+/*============================================================
+ *      subtree_matches
+ *============================================================*/
+test("subtree_matches finds a term in keys and primitive values", () => {
+    let v = {alpha: {beta: "HELLO world"}};
+    expect(subtree_matches(v, "hello")).toBe(true);
+    expect(subtree_matches(v, "beta")).toBe(true);
+    expect(subtree_matches(v, "missing")).toBe(false);
+});
+
+test("subtree_matches never matches inside a collapsed subtree", () => {
+    let v = {__collapsed__: {path: "x", size: 9}};
+    expect(subtree_matches(v, "x")).toBe(false);
+});
+
+test("subtree_matches with empty term is always true", () => {
+    expect(subtree_matches({a: 1}, "")).toBe(true);
+});
+
+
+/*============================================================
+ *      time fields
+ *============================================================*/
+test("is_time_field matches the kernel timestamp field set", () => {
+    ["__t__", "t", "tm", "from_t", "to_t", "t_input"].forEach((f) => {
+        expect(is_time_field(f)).toBe(true);
+    });
+    expect(is_time_field("name")).toBe(false);
+});
+
+test("format_epoch handles seconds, milliseconds and the unset case", () => {
+    expect(format_epoch(0)).toBeNull();
+    expect(format_epoch(-5)).toBeNull();
+    expect(format_epoch("x")).toBeNull();
+    expect(typeof format_epoch(1700000000)).toBe("string");        // seconds
+    expect(typeof format_epoch(1700000000000)).toBe("string");     // milliseconds
+});

package/src/route_map_model.js

@@ -0,0 +1,317 @@
+/***********************************************************************
+ *          route_map_model.js
+ *
+ *          Pure nav-map builder for C_YUI_SHELL's site map (no gobj,
+ *          no DOM, no imports) — kept apart so it is trivially
+ *          unit-testable, like route_resolver.js.
+ *
+ *          build_nav_map() turns the shell's declarative surface into
+ *          an ordered tree for the site-map viewer / documentation:
+ *          toolbar (incl. the account dropdown), EVERY declared menu
+ *          (incl. live dynamic tabs), each mounted view's contributed
+ *          sub-routes, and the routes declared ONLY in the route table
+ *          (config.shell.routes) that no menu item points at — so the
+ *          map really is the WHOLE navigation surface, and an orphan
+ *          route is visible instead of silently unreachable.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/************************************************************
+ *  One node of the nav map from a declared config item, in
+ *  DECLARATION ORDER (never sorted). Recurses into static submenus
+ *  and toolbar dropdowns, and merges the LIVE dynamic submenu tabs
+ *  (added at runtime via yui_shell_set_submenu) by parent id.
+ ************************************************************/
+function nav_node_from_item(it, index)
+{
+    if(!it || it.type === "divider" || it.type === "header") {
+        return null;
+    }
+    let action = it.action || {};
+    let route = it.route ||
+        (action.type === "navigate" ? action.route : "") || "";
+    let event = (action.type === "event") ? action.event : "";
+    /*  Where it is implemented: the view GClass mounted at this route
+     *  (and, for an action route, the event it fires) — from item_index. */
+    let gclass = "";
+    if(route && index[route] && index[route].target) {
+        let tgt = index[route].target;
+        gclass = tgt.gclass || "";
+        if(!event && tgt.kind === "action" && tgt.event) {
+            event = tgt.event;
+        }
+    }
+    let node = {
+        id:       it.id || "",
+        label:    it.name || it.wordmark || it.id || route || "",
+        icon:     it.icon || "",
+        route:    route,
+        event:    event,
+        gclass:   gclass,
+        kind:     it.type || (route ? "route" : (event ? "action" :
+                  (action.type || "item"))),
+        children: []
+    };
+
+    /*  Static submenu (declared) and toolbar dropdown (the account menu). */
+    let sub_items = (it.submenu && Array.isArray(it.submenu.items)) ?
+        it.submenu.items :
+        ((action.type === "dropdown" && Array.isArray(action.items)) ?
+            action.items : null);
+    if(sub_items) {
+        for(let s of sub_items) {
+            let n = nav_node_from_item(s, index);
+            if(n) {
+                node.children.push(n);
+            }
+        }
+    }
+
+    /*  Live dynamic submenu children (runtime tabs) — item_index entries
+     *  whose parent is this item, in item_index (insertion) order, minus
+     *  any already added statically. */
+    if(it.id && index) {
+        for(let r of Object.keys(index)) {
+            let e = index[r];
+            if(e && e.parent_item && e.parent_item.id === it.id &&
+                    !node.children.some((c) => c.route === r)) {
+                node.children.push({
+                    id:       (e.item && e.item.id) || "",
+                    label:    (e.item && e.item.name) || r,
+                    icon:     (e.item && e.item.icon) || "",
+                    route:    r,
+                    event:    "",
+                    gclass:   (e.target && e.target.gclass) || "",
+                    kind:     "route",
+                    children: []
+                });
+            }
+        }
+    }
+    return node;
+}
+
+/************************************************************
+ *  Deep-copy contributed sub-route nodes.
+ *
+ *  yui_shell_set_sub_routes() stores the CALLER's array by
+ *  reference — those objects belong to the mounted view and
+ *  outlive this build.  Splicing them into the tree as-is made
+ *  build_nav_map() a mutator of its own input: mark_current()
+ *  stamped `current: true` on a view-owned object and nothing
+ *  ever cleared it, so every later build kept the stale mark and
+ *  the map grew a second "you are here" per visited sub-route.
+ ************************************************************/
+function clone_nodes(nodes)
+{
+    let out = [];
+    for(let n of nodes) {
+        if(!n) {
+            continue;
+        }
+        let c = Object.assign({}, n);
+        c.children = Array.isArray(n.children) ? clone_nodes(n.children) : [];
+        delete c.current;
+        out.push(c);
+    }
+    return out;
+}
+
+/************************************************************
+ *  Collect every route reachable from the given nodes (recursing
+ *  into children, sub-route contributions included).
+ ************************************************************/
+function collect_routes(nodes, into)
+{
+    for(let n of nodes) {
+        if(!n) {
+            continue;
+        }
+        if(n.route) {
+            into[n.route] = true;
+        }
+        if(Array.isArray(n.children) && n.children.length) {
+            collect_routes(n.children, into);
+        }
+    }
+}
+
+/************************************************************
+ *  Mark "you are here": the node whose route best matches
+ *  current_route — exact hit wins, else the LONGEST declared
+ *  route that is a path-prefix of it (the base view of a deep
+ *  subpath position).  At most one node is marked.
+ ************************************************************/
+function mark_current(groups, current_route)
+{
+    if(!current_route) {
+        return;
+    }
+    let best = null;
+    let visit = (n) => {
+        if(n.route) {
+            if(n.route === current_route) {
+                if(!best || best.node.route !== current_route) {
+                    best = {node: n, len: n.route.length};
+                }
+            } else if(current_route.startsWith(n.route + "/") &&
+                    (!best || (best.node.route !== current_route &&
+                               n.route.length > best.len))) {
+                best = {node: n, len: n.route.length};
+            }
+        }
+        if(Array.isArray(n.children)) {
+            n.children.forEach(visit);
+        }
+    };
+    for(let g of groups) {
+        g.forEach(visit);
+    }
+    if(best) {
+        best.node.current = true;
+    }
+}
+
+/************************************************************
+ *  build_nav_map({config, item_index, sub_routes, event_handlers,
+ *                 current_route}) →
+ *      { brand:{label,route,current?}, toolbar:[node…], nav:[node…],
+ *        other:[node…] }
+ *  where a node is {id,label,icon,route,event,gclass,kind,
+ *  children[], current?}.  `route` is a navigable hash (or "");
+ *  `event` is the action it fires; `gclass` is the view GClass
+ *  mounted at that route or the self-declared handler(s) of the
+ *  event (where it is implemented).
+ *
+ *  - `nav` walks EVERY declared menu in declaration order: the
+ *    `primary` menu contributes its items flat (the common case);
+ *    any other menu contributes a group node labelled by its key.
+ *  - `other` lists the routes declared only in the route table
+ *    (config.shell.routes) that no rendered node covers — root "/",
+ *    URL-only action routes, toolbar-less forms.  Brand-covered
+ *    and menu-covered routes are excluded.
+ *  - the node whose route best matches `current_route` is marked
+ *    `current: true` ("you are here") — the brand included, since it
+ *    renders as the tree's root row.
+ *
+ *  PURE: the returned tree is built fresh every call, contributed
+ *  sub-route nodes included (they are cloned, never spliced in by
+ *  reference — see clone_nodes).  Nothing the caller passed in is
+ *  mutated, so repeated builds cannot accumulate state.
+ ************************************************************/
+function build_nav_map(input)
+{
+    let config = (input && input.config) || {};
+    let index = (input && input.item_index) || {};
+    let sub = (input && input.sub_routes) || {};
+    let handlers = (input && input.event_handlers) || {};
+    let current_route = (input && input.current_route) || "";
+
+    let brand = {label: "", route: ""};
+    let toolbar = [];
+    let tb = config.toolbar && Array.isArray(config.toolbar.items) ?
+        config.toolbar.items : [];
+    for(let it of tb) {
+        if(it && it.type === "brand") {
+            let a = it.action || {};
+            brand = {
+                label: it.wordmark || it.alt || it.id || "",
+                route: it.route || (a.type === "navigate" ? a.route : "") || ""
+            };
+            continue;
+        }
+        let n = nav_node_from_item(it, index);
+        if(n) {
+            toolbar.push(n);
+        }
+    }
+
+    /*  Every declared menu, in declaration order.  `primary` stays flat
+     *  (backwards-compatible single-menu shape); any additional menu is
+     *  wrapped in a group node so its origin stays visible. */
+    let nav = [];
+    let menus = config.menu || {};
+    for(let menu_id of Object.keys(menus)) {
+        let m = menus[menu_id];
+        if(!m || !Array.isArray(m.items)) {
+            continue;
+        }
+        let nodes = [];
+        for(let it of m.items) {
+            let n = nav_node_from_item(it, index);
+            if(n) {
+                nodes.push(n);
+            }
+        }
+        if(menu_id === "primary") {
+            nav = nav.concat(nodes);
+        } else if(nodes.length) {
+            nav.push({
+                id: menu_id, label: menu_id, icon: "", route: "", event: "",
+                gclass: "", kind: "group", children: nodes
+            });
+        }
+    }
+
+    /*  Enrich the tree: merge each mounted view's declared sub-routes into
+     *  its base-route node, and stamp the handler gclass on action-event
+     *  nodes (where the action is implemented). */
+    let enrich = (node) => {
+        if(node.route && Array.isArray(sub[node.route]) && sub[node.route].length) {
+            node.children = (node.children || []).concat(
+                clone_nodes(sub[node.route]));
+        }
+        if(node.event && !node.gclass &&
+                Array.isArray(handlers[node.event]) && handlers[node.event].length) {
+            node.gclass = handlers[node.event].join(", ");
+        }
+        if(Array.isArray(node.children)) {
+            node.children.forEach(enrich);
+        }
+    };
+    toolbar.forEach(enrich);
+    nav.forEach(enrich);
+
+    /*  Routes declared in the index that no rendered node covers —
+     *  root "/", route-table-only action routes, toolbar-less forms.
+     *  Declaration (insertion) order, like everything else. */
+    let covered = {};
+    if(brand.route) {
+        covered[brand.route] = true;
+    }
+    collect_routes(toolbar, covered);
+    collect_routes(nav, covered);
+    let other = [];
+    for(let r of Object.keys(index)) {
+        if(covered[r]) {
+            continue;
+        }
+        let e = index[r];
+        let tgt = (e && e.target) || null;
+        other.push({
+            id:       (e && e.item && e.item.id) || "",
+            label:    (e && e.item && (e.item.name || e.item.id)) || r,
+            icon:     (e && e.item && e.item.icon) || "",
+            route:    r,
+            event:    (tgt && tgt.kind === "action" && tgt.event) || "",
+            gclass:   (tgt && tgt.gclass) || "",
+            kind:     (tgt && tgt.kind === "action") ? "action-route" : "route",
+            children: []
+        });
+    }
+    other.forEach(enrich);
+
+    /*  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
+     *  routes home unable to show "you are here" at all.  Marked LAST:
+     *  a menu item declaring the same route is the more useful hit, and
+     *  the first exact match wins.                                      */
+    mark_current([toolbar, nav, other, [brand]], current_route);
+
+    return {brand: brand, toolbar: toolbar, nav: nav, other: other};
+}
+
+export { build_nav_map };