@yuneta/gobj-ui 7.23.29 → 7.23.30

package/src/gobj_tree_model.js

@@ -0,0 +1,436 @@
+/***********************************************************************
+ *          gobj_tree_model.js
+ *
+ *          The gobj tree of a yuno, as plain data.
+ *
+ *          The view (C_YUI_GOBJ_TREE_JS) draws NODE DESCRIPTORS, never
+ *          gobjs. There are two producers of a descriptor, because the
+ *          view has to show the gobjs of the BACKEND too:
+ *
+ *            - describe_js_gobj()      the gobj tree of THIS browser yuno
+ *            - describe_backend_tree() the answer of the backend command
+ *                                      `view-gobj-tree` of another yuno
+ *
+ *          Both answer the SAME shape, and that shape is the backend's:
+ *          the field names are the ones `gobj2json()` writes in
+ *          `kernel/c/gobj-c/src/gobj.c` (fullname, shortname, gclass,
+ *          name, parent, state, running, playing, service, disabled,
+ *          volatil, bottom_gobj, gobj_flags, commands, gobj_trace_level).
+ *          Anything the browser runtime cannot answer is simply absent,
+ *          and every reader here treats absent as "not known", never as
+ *          false.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {
+    gobj_gclass_name,
+    gobj_name,
+    gobj_short_name,
+    gobj_full_name,
+    gobj_parent,
+    gobj_current_state,
+    gobj_is_running,
+    gobj_is_playing,
+    gobj_is_service,
+    gobj_is_pure_child,
+    gobj_is_volatil,
+    gobj_bottom_gobj,
+} from "@yuneta/gobj-js";
+
+
+                    /******************************
+                     *      Roles and status
+                     ******************************/
+
+
+/*  What a node IS. One value: a gobj is drawn once, so it gets one
+ *  colour. The order is the order of specificity, and the yuno wins
+ *  over everything because the root is the yuno by construction.  */
+const ROLES = ["yuno", "service", "volatil", "pure", "child"];
+
+/*  What a node is DOING. `disabled` is not one of these -- a disabled
+ *  gobj is still stopped or running, so it travels as its own mark.  */
+const STATUSES = ["stopped", "running", "playing"];
+
+
+/************************************************************
+ *  The role of a node: "yuno" | "service" | "volatil" | "pure" | "child"
+ ************************************************************/
+function node_role(d)
+{
+    if(!d) {
+        return "child";
+    }
+    if(d.is_yuno) {
+        return "yuno";
+    }
+    if(d.service) {
+        return "service";
+    }
+    if(d.volatil) {
+        return "volatil";
+    }
+    if(d.pure_child) {
+        return "pure";
+    }
+    return "child";
+}
+
+/************************************************************
+ *  What the node is doing: "stopped" | "running" | "playing"
+ ************************************************************/
+function node_status(d)
+{
+    if(!d || !d.running) {
+        return "stopped";
+    }
+    return d.playing? "playing": "running";
+}
+
+/************************************************************
+ *  The i18n key of the status, which is NOT the status itself:
+ *  a gobj that runs and does not play is PAUSED to the reader,
+ *  and "running" alone never said which of the two it was.
+ ************************************************************/
+function node_status_key(d)
+{
+    switch(node_status(d)) {
+        case "playing":
+            return "playing";
+        case "running":
+            return "running (paused)";
+        default:
+            return "stopped";
+    }
+}
+
+
+                    /******************************
+                     *      Producers
+                     ******************************/
+
+
+/************************************************************
+ *  A descriptor of a LIVE gobj of this browser yuno, children
+ *  included (the whole subtree, depth-first).
+ *
+ *  `is_root` marks the yuno itself: the JS runtime has no
+ *  gobj_flag_yuno test of its own.
+ ************************************************************/
+function describe_js_gobj(target_gobj, is_root)
+{
+    if(!target_gobj) {
+        return null;
+    }
+
+    let parent_gobj = gobj_parent(target_gobj);
+    let bottom = gobj_bottom_gobj(target_gobj);
+
+    let d = {
+        gclass:     gobj_gclass_name(target_gobj) || "",
+        name:       gobj_name(target_gobj) || "",
+        shortname:  gobj_short_name(target_gobj) || "",
+        fullname:   gobj_full_name(target_gobj) || "",
+        parent:     parent_gobj? (gobj_short_name(parent_gobj) || ""): "",
+        state:      gobj_current_state(target_gobj) || "",
+        running:    !!gobj_is_running(target_gobj),
+        playing:    !!gobj_is_playing(target_gobj),
+        service:    !!gobj_is_service(target_gobj),
+        volatil:    !!gobj_is_volatil(target_gobj),
+        pure_child: !!gobj_is_pure_child(target_gobj),
+
+        /*  gobj-js exports no gobj_is_disabled() (the function exists,
+         *  the export list does not carry it), so the flag is read from
+         *  the instance the way gobj_enable/gobj_disable write it. The
+         *  backend answers the same name in `view-gobj-tree`.  */
+        disabled:   !!target_gobj.disabled,
+
+        bottom_gobj: bottom? (gobj_short_name(bottom) || ""): "",
+        commands:   !!(target_gobj.gclass && target_gobj.gclass.command_table),
+        is_yuno:    !!is_root,
+        children:   [],
+    };
+
+    let children = target_gobj.dl_children || [];
+    for(let child of children) {
+        let cd = describe_js_gobj(child, false);
+        if(cd) {
+            d.children.push(cd);
+        }
+    }
+
+    return d;
+}
+
+/************************************************************
+ *  A descriptor from ONE node of the `view-gobj-tree` answer
+ *  of a backend yuno.
+ *
+ *  `shortname` is the key the node hangs from in that answer;
+ *  the node itself repeats it, so the argument is only the
+ *  fallback for a filtered answer that dropped the field.
+ ************************************************************/
+function describe_backend_node(shortname, node, is_root)
+{
+    if(!node || typeof node !== "object") {
+        return null;
+    }
+
+    let flags = Array.isArray(node.gobj_flags)? node.gobj_flags: [];
+    let has = (flag) => flags.indexOf(flag) !== -1;
+
+    let d = {
+        gclass:     node.gclass || "",
+        name:       node.name || "",
+        shortname:  node.shortname || shortname || "",
+        fullname:   node.fullname || "",
+        parent:     node.parent || "",
+        state:      node.state || "",
+        running:    !!node.running,
+        playing:    !!node.playing,
+        service:    !!node.service || has("gobj_flag_service") ||
+                        has("gobj_flag_default_service"),
+        volatil:    !!node.volatil || has("gobj_flag_volatil"),
+        pure_child: has("gobj_flag_pure_child"),
+        disabled:   !!node.disabled,
+        bottom_gobj: node.bottom_gobj || "",
+        commands:   !!node.commands,
+        gobj_flags: flags,
+        gobj_trace_level: Array.isArray(node.gobj_trace_level)?
+                            node.gobj_trace_level: [],
+        is_yuno:    (is_root !== undefined)?
+                        !!is_root: has("gobj_flag_yuno"),
+        children:   [],
+    };
+
+    let children = (node.children && typeof node.children === "object")?
+        node.children: null;
+    if(children) {
+        for(let key of Object.keys(children)) {
+            let cd = describe_backend_node(key, children[key], false);
+            if(cd) {
+                d.children.push(cd);
+            }
+        }
+    }
+
+    return d;
+}
+
+/************************************************************
+ *  The whole `view-gobj-tree` answer -> the root descriptor.
+ *
+ *  That answer is a dict of ONE key (the shortname of the gobj
+ *  the command was asked about) even though it is shaped as a
+ *  dict all the way down. Returns null for anything else, and
+ *  the caller reports it: an empty tree and a malformed answer
+ *  must not look the same.
+ ************************************************************/
+function describe_backend_tree(data)
+{
+    if(!data || typeof data !== "object" || Array.isArray(data)) {
+        return null;
+    }
+    let keys = Object.keys(data);
+    if(keys.length === 0) {
+        return null;
+    }
+    return describe_backend_node(keys[0], data[keys[0]], true);
+}
+
+
+                    /******************************
+                     *      Readouts
+                     ******************************/
+
+
+/************************************************************
+ *  The i18n key of a role. Two of the five roles are not the
+ *  word the reader wants ("pure" and "volatil" alone say
+ *  nothing), so the map is explicit.
+ ************************************************************/
+function role_i18n_key(role)
+{
+    switch(role) {
+        case "yuno":
+            return "yuno";
+        case "service":
+            return "service";
+        case "volatil":
+            return "volatil child";
+        case "pure":
+            return "pure child";
+        default:
+            return "child";
+    }
+}
+
+/************************************************************
+ *  The marks a node carries besides its role: what the reader
+ *  would otherwise have to open the popover to learn.
+ *
+ *  Returns i18n KEYS, in a fixed order, so the card and the
+ *  popover cannot disagree about what a node is.
+ ************************************************************/
+function node_badge_keys(d)
+{
+    let badges = [];
+    if(!d) {
+        return badges;
+    }
+
+    let role = node_role(d);
+    if(role !== "child") {
+        badges.push(role_i18n_key(role));
+    }
+
+    if(d.disabled) {
+        badges.push("disabled");
+    }
+    if(d.bottom_gobj) {
+        badges.push("bottom");
+    }
+    if(d.commands) {
+        badges.push("commands");
+    }
+
+    return badges;
+}
+
+/************************************************************
+ *  The vocabulary of this view, translated.
+ *
+ *  Written as literal t("...") calls and not as t(key): a key
+ *  reached through a variable is invisible to the locale
+ *  validator, which is how a fixed vocabulary ships in one
+ *  language and never changes it.
+ ************************************************************/
+function node_labels(t)
+{
+    if(typeof t !== "function") {
+        t = (k) => k;
+    }
+    return {
+        role: {
+            "yuno":          t("yuno"),
+            "service":       t("service"),
+            "volatil child": t("volatil child"),
+            "pure child":    t("pure child"),
+            "child":         t("child"),
+        },
+        /*  The precise words, for the popover, which has room.  */
+        status: {
+            "playing":           t("playing"),
+            "running (paused)":  t("running (paused)"),
+            "stopped":           t("stopped"),
+        },
+        /*  The glanceable ones, for the pill on the card, which has
+         *  not: "Ejecutando (en pausa)" pushes the FSM state off its
+         *  own row. The colour carries the rest, and the pill's
+         *  `title` says it in full.  */
+        status_short: {
+            "playing":  t("playing"),
+            "running":  t("running"),
+            "stopped":  t("stopped"),
+        },
+        badge: {
+            "yuno":          t("yuno"),
+            "service":       t("service"),
+            "volatil child": t("volatil child"),
+            "pure child":    t("pure child"),
+            "disabled":      t("disabled"),
+            "bottom":        t("bottom"),
+            "commands":      t("commands"),
+        },
+        field: {
+            gclass:      t("gclass"),
+            name:        t("name"),
+            full_name:   t("full name"),
+            role:        t("role"),
+            status:      t("status"),
+            state:       t("state"),
+            disabled:    t("disabled"),
+            parent:      t("parent"),
+            bottom_gobj: t("bottom gobj"),
+            commands:    t("commands"),
+            traces:      t("traces"),
+            flags:       t("flags"),
+            children:    t("children"),
+            yes:         t("yes"),
+            collapsed:   t("(collapsed)"),
+        },
+    };
+}
+
+/************************************************************
+ *  The rows of the popover: [label, value], both translated.
+ *
+ *  `t` is the app's translator -- the library has none of its
+ *  own. Values that are a fixed vocabulary (the role, the
+ *  status, yes) go through it too; free text does not.
+ ************************************************************/
+function node_info_rows(d, t)
+{
+    let rows = [];
+    if(!d) {
+        return rows;
+    }
+    let L = node_labels(t);
+    let f = L.field;
+
+    rows.push([f.gclass, d.gclass || "\u2014"]);
+    rows.push([f.name,   d.name   || "\u2014"]);
+
+    if(d.fullname && d.fullname !== d.shortname) {
+        rows.push([f.full_name, d.fullname]);
+    }
+
+    rows.push([f.role,   L.role[role_i18n_key(node_role(d))]]);
+    rows.push([f.status, L.status[node_status_key(d)]]);
+    rows.push([f.state,  d.state || "\u2014"]);
+
+    if(d.disabled) {
+        rows.push([f.disabled, f.yes]);
+    }
+    if(d.parent) {
+        rows.push([f.parent, d.parent]);
+    }
+    if(d.bottom_gobj) {
+        rows.push([f.bottom_gobj, d.bottom_gobj]);
+    }
+    if(d.commands) {
+        rows.push([f.commands, f.yes]);
+    }
+    if(Array.isArray(d.gobj_trace_level) && d.gobj_trace_level.length > 0) {
+        rows.push([f.traces, d.gobj_trace_level.join(", ")]);
+    }
+    if(Array.isArray(d.gobj_flags) && d.gobj_flags.length > 0) {
+        rows.push([f.flags, d.gobj_flags.join(", ")]);
+    }
+
+    let kids = Array.isArray(d.children)? d.children.length: 0;
+    if(kids > 0) {
+        rows.push([
+            f.children,
+            d.is_collapsed? (kids + " " + f.collapsed): String(kids)
+        ]);
+    }
+
+    return rows;
+}
+
+export {
+    ROLES,
+    STATUSES,
+    node_role,
+    node_status,
+    node_status_key,
+    node_badge_keys,
+    node_labels,
+    node_info_rows,
+    role_i18n_key,
+    describe_js_gobj,
+    describe_backend_node,
+    describe_backend_tree,
+};

package/src/gobj_tree_model.test.js

@@ -0,0 +1,184 @@
+import {describe, it, expect} from "vitest";
+import {
+    node_role,
+    node_status,
+    node_status_key,
+    node_badge_keys,
+    node_info_rows,
+    describe_backend_node,
+    describe_backend_tree,
+} from "./gobj_tree_model.js";
+
+/*  A `view-gobj-tree` answer, trimmed to what the view reads.  */
+const BACKEND_TREE = {
+    "Yuno^my_yuno": {
+        fullname: "Yuno^my_yuno",
+        shortname: "Yuno^my_yuno",
+        gclass: "C_YUNO",
+        name: "my_yuno",
+        parent: "",
+        state: "ST_IDLE",
+        running: true,
+        playing: true,
+        service: true,
+        disabled: false,
+        volatil: false,
+        commands: true,
+        gobj_flags: ["gobj_flag_yuno", "gobj_flag_service"],
+        gobj_trace_level: ["machine"],
+        children: {
+            "C_TIMER^timer": {
+                shortname: "C_TIMER^timer",
+                gclass: "C_TIMER",
+                name: "timer",
+                parent: "Yuno^my_yuno",
+                state: "ST_IDLE",
+                running: true,
+                playing: false,
+                service: false,
+                disabled: false,
+                volatil: false,
+                gobj_flags: ["gobj_flag_pure_child"],
+            },
+            "C_TCP^conn": {
+                shortname: "C_TCP^conn",
+                gclass: "C_TCP",
+                name: "conn",
+                state: "ST_STOPPED",
+                running: false,
+                playing: false,
+                service: false,
+                disabled: true,
+                volatil: true,
+                bottom_gobj: "C_TCP^raw",
+                gobj_flags: ["gobj_flag_volatil"],
+            },
+        },
+    },
+};
+
+describe("describe_backend_tree", () => {
+    it("reads the root and its children out of the command answer", () => {
+        let root = describe_backend_tree(BACKEND_TREE);
+        expect(root.gclass).toBe("C_YUNO");
+        expect(root.is_yuno).toBe(true);
+        expect(root.children.length).toBe(2);
+        expect(root.children.map(c => c.gclass).sort())
+            .toEqual(["C_TCP", "C_TIMER"]);
+    });
+
+    it("a malformed answer is null, not an empty tree", () => {
+        expect(describe_backend_tree(null)).toBe(null);
+        expect(describe_backend_tree({})).toBe(null);
+        expect(describe_backend_tree([])).toBe(null);
+    });
+
+    it("takes pure_child from gobj_flags, which has no boolean of its own", () => {
+        let root = describe_backend_tree(BACKEND_TREE);
+        let timer = root.children.find(c => c.gclass === "C_TIMER");
+        expect(timer.pure_child).toBe(true);
+        expect(timer.service).toBe(false);
+    });
+
+    it("a node with no children answers an empty list, not undefined", () => {
+        let d = describe_backend_node("C_X^x", {gclass: "C_X"}, false);
+        expect(d.children).toEqual([]);
+    });
+});
+
+describe("node_role", () => {
+    it("the yuno wins over every other mark", () => {
+        expect(node_role({is_yuno: true, service: true, volatil: true}))
+            .toBe("yuno");
+    });
+
+    it("orders service over volatil over pure", () => {
+        expect(node_role({service: true, volatil: true})).toBe("service");
+        expect(node_role({volatil: true, pure_child: true})).toBe("volatil");
+        expect(node_role({pure_child: true})).toBe("pure");
+        expect(node_role({})).toBe("child");
+    });
+});
+
+describe("node_status", () => {
+    it("tells the three states apart", () => {
+        expect(node_status({running: false, playing: false})).toBe("stopped");
+        expect(node_status({running: true, playing: false})).toBe("running");
+        expect(node_status({running: true, playing: true})).toBe("playing");
+    });
+
+    it("says PAUSED for the one that runs and does not play", () => {
+        expect(node_status_key({running: true, playing: false}))
+            .toBe("running (paused)");
+        expect(node_status_key({running: true, playing: true}))
+            .toBe("playing");
+    });
+
+    it("a gobj that plays without running cannot happen, and reads stopped", () => {
+        expect(node_status({running: false, playing: true})).toBe("stopped");
+    });
+});
+
+describe("node_badge_keys", () => {
+    it("marks the role and every extra fact, in a fixed order", () => {
+        let root = describe_backend_tree(BACKEND_TREE);
+        expect(node_badge_keys(root)).toEqual(["yuno", "commands"]);
+
+        let tcp = root.children.find(c => c.gclass === "C_TCP");
+        expect(node_badge_keys(tcp))
+            .toEqual(["volatil child", "disabled", "bottom"]);
+    });
+
+    it("a plain child carries no role badge", () => {
+        expect(node_badge_keys({})).toEqual([]);
+    });
+});
+
+describe("node_info_rows", () => {
+    const rows_of = (d) => {
+        let map = {};
+        for(let [label, value] of node_info_rows(d, null)) {
+            map[label] = value;
+        }
+        return map;
+    };
+
+    it("names the role and the status with the reader's words", () => {
+        let root = describe_backend_tree(BACKEND_TREE);
+        let timer = root.children.find(c => c.gclass === "C_TIMER");
+        let r = rows_of(timer);
+        expect(r["role"]).toBe("pure child");
+        expect(r["status"]).toBe("running (paused)");
+        expect(r["state"]).toBe("ST_IDLE");
+    });
+
+    it("shows the facts a card has no room for", () => {
+        let root = describe_backend_tree(BACKEND_TREE);
+        let tcp = root.children.find(c => c.gclass === "C_TCP");
+        let r = rows_of(tcp);
+        expect(r["disabled"]).toBe("yes");
+        expect(r["bottom gobj"]).toBe("C_TCP^raw");
+        expect(r["status"]).toBe("stopped");
+    });
+
+    it("carries the traces and the flags the backend reports", () => {
+        let r = rows_of(describe_backend_tree(BACKEND_TREE));
+        expect(r["traces"]).toBe("machine");
+        expect(r["flags"]).toBe("gobj_flag_yuno, gobj_flag_service");
+    });
+
+    it("omits every row whose fact is absent", () => {
+        let r = rows_of(describe_backend_node("C_X^x", {gclass: "C_X"}, false));
+        expect(r["bottom gobj"]).toBeUndefined();
+        expect(r["traces"]).toBeUndefined();
+        expect(r["disabled"]).toBeUndefined();
+        expect(r["children"]).toBeUndefined();
+    });
+
+    it("says how many children are hidden when the node is folded", () => {
+        let root = describe_backend_tree(BACKEND_TREE);
+        expect(rows_of(root)["children"]).toBe("2");
+        root.is_collapsed = true;
+        expect(rows_of(root)["children"]).toBe("2 (collapsed)");
+    });
+});