@yuneta/gobj-ui 7.23.28 → 7.23.30

package/src/gclass_describe.test.js

@@ -0,0 +1,125 @@
+import {describe, it, expect, beforeAll} from "vitest";
+import {
+    SDATA,
+    SDATA_END,
+    SDATACM,
+    data_type_t,
+    event_flag_t,
+    gclass_create,
+    gclass_flag_t,
+    sdata_flag_t,
+} from "@yuneta/gobj-js";
+
+import {bits2names, describe_local_gclass} from "./gclass_describe.js";
+
+/*  A gclass with one of everything the viewer draws.  */
+beforeAll(() => {
+    const attrs_table = [
+        SDATA(data_type_t.DTP_STRING, "title", sdata_flag_t.SDF_RD, "", "The title"),
+        SDATA(data_type_t.DTP_INTEGER, "timeout",
+            sdata_flag_t.SDF_WR|sdata_flag_t.SDF_PERSIST, 1000, "Timeout"),
+        SDATA(data_type_t.DTP_POINTER, "$container", 0, null, "The DOM node"),
+        SDATA_END(),
+    ];
+    const command_table = [
+        SDATACM(data_type_t.DTP_STRING, "help", ["h"], [
+            SDATA(data_type_t.DTP_STRING, "cmd", 0, "", "The command"),
+            SDATA_END(),
+        ], null, "Ask for help"),
+        SDATA_END(),
+    ];
+
+    gclass_create(
+        "C_TEST_DESCRIBE",
+        [
+            ["EV_GO",   0],
+            ["EV_DONE", event_flag_t.EVF_OUTPUT_EVENT|event_flag_t.EVF_NO_WARN_SUBS],
+        ],
+        [
+            ["ST_IDLE",    [["EV_GO", function ac_go() {}, "ST_WORKING"]]],
+            ["ST_WORKING", [["EV_DONE", function ac_done() {}, "ST_IDLE"]]],
+        ],
+        {mt_create: function() {}, mt_start: function() {}},
+        0,
+        attrs_table,
+        {},
+        0,
+        command_table,
+        0,
+        gclass_flag_t.gcflag_singleton
+    );
+});
+
+describe("bits2names", () => {
+    it("names every bit set, and nothing else", () => {
+        expect(bits2names(sdata_flag_t,
+            sdata_flag_t.SDF_RD|sdata_flag_t.SDF_PERSIST))
+            .toEqual(["SDF_RD", "SDF_PERSIST"]);
+        expect(bits2names(sdata_flag_t, 0)).toEqual([]);
+    });
+});
+
+describe("describe_local_gclass", () => {
+    it("an unregistered gclass is null, never an empty document", () => {
+        expect(describe_local_gclass("C_NOT_THERE")).toBe(null);
+        expect(describe_local_gclass("")).toBe(null);
+    });
+
+    it("answers the shape the backend view-gclass answers", () => {
+        let g = describe_local_gclass("C_TEST_DESCRIBE");
+        expect(Object.keys(g)).toEqual([
+            "id", "gcflag", "attrs", "commands", "gclass_methods",
+            "internal_methods", "FSM", "instances", "trace_levels",
+        ]);
+        expect(g.id).toBe("C_TEST_DESCRIBE");
+        expect(g.gcflag).toEqual(["gcflag_singleton"]);
+    });
+
+    it("names the type and the flags of every attr", () => {
+        let attrs = describe_local_gclass("C_TEST_DESCRIBE").attrs;
+        expect(attrs.length).toBe(3);
+        expect(attrs[0]).toEqual({
+            id: "title",
+            type: "DTP_STRING",
+            flag: ["SDF_RD"],
+            description: "The title",
+            default_value: "",
+        });
+        expect(attrs[1].flag).toEqual(["SDF_WR", "SDF_PERSIST"]);
+        expect(attrs[1].default_value).toBe(1000);
+    });
+
+    it("never prints a pointer default -- it names it", () => {
+        let attrs = describe_local_gclass("C_TEST_DESCRIBE").attrs;
+        let container = attrs.find(a => a.id === "$container");
+        expect(container.type).toBe("DTP_POINTER");
+        expect(container.default_value).toBe(null);
+    });
+
+    it("carries the commands with their parameters", () => {
+        let cmds = describe_local_gclass("C_TEST_DESCRIBE").commands;
+        expect(cmds.length).toBe(1);
+        expect(cmds[0].id).toBe("help");
+        expect(cmds[0].alias).toEqual(["h"]);
+        expect(cmds[0].parameters.map(p => p.id)).toEqual(["cmd"]);
+    });
+
+    it("lists only the methods the gclass implements", () => {
+        let g = describe_local_gclass("C_TEST_DESCRIBE");
+        expect(g.gclass_methods).toEqual(["mt_create", "mt_start"]);
+        expect(g.internal_methods).toEqual([]);
+    });
+
+    it("draws the FSM as events plus what each state does with them", () => {
+        let fsm = describe_local_gclass("C_TEST_DESCRIBE").FSM;
+        expect(fsm.events).toEqual([
+            {event_name: "EV_GO", event_flag: []},
+            {event_name: "EV_DONE",
+             event_flag: ["EVF_NO_WARN_SUBS", "EVF_OUTPUT_EVENT"]},
+        ]);
+        expect(Object.keys(fsm.states)).toEqual(["ST_IDLE", "ST_WORKING"]);
+        expect(fsm.states["ST_IDLE"]).toEqual([
+            {event_name: "EV_GO", action: "ac_go", next_state: "ST_WORKING"},
+        ]);
+    });
+});

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,
+};