@yuneta/gobj-ui 7.23.29 → 7.23.30

package/src/gclass_describe.js

@@ -0,0 +1,234 @@
+/***********************************************************************
+ *          gclass_describe.js
+ *
+ *          A gclass, as plain JSON, in the shape the BACKEND answers.
+ *
+ *          There is no gclass viewer in the framework: the C kernel
+ *          answers `view-gclass` with `gclass2json()`
+ *          (`kernel/c/gobj-c/src/gobj.c`) and nothing draws it. This
+ *          module builds the same document for a gclass of the BROWSER
+ *          yuno, out of the gobj-js registry, so one viewer can show a
+ *          gclass of either side:
+ *
+ *              {id, gcflag, attrs, commands, gclass_methods,
+ *               internal_methods, FSM: {events, states}}
+ *
+ *          Two keys the backend does not carry are added at the end,
+ *          because the browser can answer them for free and the reader
+ *          asks them first: `instances` and `trace_levels`.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {
+    data_type_t,
+    sdata_flag_t,
+    event_flag_t,
+    gclass_flag_t,
+    gclass_find_by_name,
+} from "@yuneta/gobj-js";
+
+
+/***************************************************************
+ *              Bit tables
+ ***************************************************************/
+const DATA_TYPE_NAMES = {
+    [data_type_t.DTP_STRING]:  "DTP_STRING",
+    [data_type_t.DTP_BOOLEAN]: "DTP_BOOLEAN",
+    [data_type_t.DTP_INTEGER]: "DTP_INTEGER",
+    [data_type_t.DTP_REAL]:    "DTP_REAL",
+    [data_type_t.DTP_LIST]:    "DTP_LIST",
+    [data_type_t.DTP_DICT]:    "DTP_DICT",
+    [data_type_t.DTP_JSON]:    "DTP_JSON",
+    [data_type_t.DTP_POINTER]: "DTP_POINTER",
+};
+
+/************************************************************
+ *  The names of the bits set in `bits`, in table order.
+ ************************************************************/
+function bits2names(table, bits)
+{
+    let names = [];
+    let value = Number(bits) || 0;
+
+    for(let name of Object.keys(table)) {
+        if((value & table[name]) !== 0) {
+            names.push(name);
+        }
+    }
+    return names;
+}
+
+/************************************************************
+ *  The name of a data type. An unknown type is reported as
+ *  the number it is -- silently drawing "DTP_STRING" for a
+ *  type nobody registered would be worse than saying "17".
+ ************************************************************/
+function data_type_name(type)
+{
+    return DATA_TYPE_NAMES[type] || String(type);
+}
+
+/************************************************************
+ *  One SDATA descriptor -> one row.
+ *
+ *  A DTP_POINTER default is a live object (a DOM node, a
+ *  gobj): it is never printed, only named, because a viewer
+ *  that serializes it would either throw or dump the page.
+ ************************************************************/
+function sdatadesc2json(it)
+{
+    let row = {
+        id:          it.name,
+        type:        data_type_name(it.type),
+        flag:        bits2names(sdata_flag_t, it.flag),
+        description: it.description || "",
+    };
+
+    if(it.type === data_type_t.DTP_POINTER) {
+        row.default_value = (it.default_value === null ||
+            it.default_value === undefined)? null: "<pointer>";
+    } else {
+        row.default_value = (it.default_value === undefined)?
+            null: it.default_value;
+    }
+
+    return row;
+}
+
+/************************************************************
+ *  The attrs table of a gclass.
+ ************************************************************/
+function attrs2json(attrs_table)
+{
+    let rows = [];
+    if(!Array.isArray(attrs_table)) {
+        return rows;
+    }
+    for(let it of attrs_table) {
+        if(!it || !it.name) {
+            continue;   /*  SDATA_END()  */
+        }
+        rows.push(sdatadesc2json(it));
+    }
+    return rows;
+}
+
+/************************************************************
+ *  The command table of a gclass, with the parameters of
+ *  each command (the `schema` slot of SDATACM).
+ ************************************************************/
+function commands2json(command_table)
+{
+    let rows = [];
+    if(!Array.isArray(command_table)) {
+        return rows;
+    }
+    for(let it of command_table) {
+        if(!it || !it.name) {
+            continue;   /*  SDATA_END()  */
+        }
+        let row = {
+            id:          it.name,
+            alias:       it.alias || [],
+            description: it.description || "",
+        };
+        if(Array.isArray(it.schema)) {
+            row.parameters = attrs2json(it.schema);
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+
+/************************************************************
+ *  The methods the gclass actually implements. A table of
+ *  every possible one, mostly empty, tells the reader nothing.
+ ************************************************************/
+function methods2json(mt)
+{
+    let names = [];
+    if(!mt || typeof mt !== "object") {
+        return names;
+    }
+    for(let key of Object.keys(mt)) {
+        if(typeof mt[key] === "function") {
+            names.push(key);
+        }
+    }
+    return names;
+}
+
+/************************************************************
+ *  The FSM: the events the gclass declares, and what each
+ *  state does with them.
+ ************************************************************/
+function fsm2json(gclass)
+{
+    let events = [];
+    for(let ev of (gclass.dl_events || [])) {
+        events.push({
+            event_name: ev.event_name,
+            event_flag: bits2names(event_flag_t, ev.event_flag),
+        });
+    }
+
+    let states = {};
+    for(let st of (gclass.dl_states || [])) {
+        let actions = [];
+        for(let ac of (st.dl_actions || [])) {
+            actions.push({
+                event_name: ac.event_name,
+                action:     ac.action? (ac.action.name || "action"): "",
+                next_state: ac.next_state || "",
+            });
+        }
+        states[st.state_name] = actions;
+    }
+
+    return {events: events, states: states};
+}
+
+/************************************************************
+ *  The description of a gclass REGISTERED IN THIS BROWSER YUNO,
+ *  or null when the registry does not know that name.
+ *
+ *  Null is the answer for a gclass of a BACKEND yuno too: the
+ *  browser registry carries the GUI gclasses and nothing else,
+ *  so the caller asks the backend `view-gclass` for those and
+ *  shows whatever it answers -- this same shape.
+ ************************************************************/
+function describe_local_gclass(gclass_name)
+{
+    if(!gclass_name) {
+        return null;
+    }
+
+    let gclass = gclass_find_by_name(gclass_name, false);
+    if(!gclass) {
+        return null;
+    }
+
+    return {
+        id:               gclass.gclass_name,
+        gcflag:           bits2names(gclass_flag_t, gclass.gclass_flag),
+        attrs:            attrs2json(gclass.attrs_table),
+        commands:         commands2json(gclass.command_table),
+        gclass_methods:   methods2json(gclass.gmt),
+        internal_methods: methods2json(gclass.lmt),
+        FSM:              fsm2json(gclass),
+        instances:        Number(gclass.instances) || 0,
+        trace_levels:     Array.isArray(gclass.s_user_trace_level)?
+                            gclass.s_user_trace_level: [],
+    };
+}
+
+export {
+    bits2names,
+    data_type_name,
+    attrs2json,
+    commands2json,
+    methods2json,
+    fsm2json,
+    describe_local_gclass,
+};

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