@yuneta/gobj-ui 7.23.28 → 7.23.30

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

package/src/lib_graph.css

@@ -273,6 +273,34 @@
  *  wherever a graph is.
  */
 
+/*
+ *  The gobj tree's popover close button, for a FINGER.
+ *
+ *  It is an 18px glyph with 4px of padding either side -- about 26x18
+ *  of target, which a mouse hits and a thumb does not. The popover
+ *  opens on a tap, so the thing that closes it has to be reachable by
+ *  the same thumb that opened it.
+ *
+ *  44px is the size every touch guideline settles on, and it is applied
+ *  only under `(pointer: coarse)`: on a mouse the small button is fine
+ *  and a 44px square in a 26px header row would not be.
+ *
+ *  `!important` because the button carries an inline `cssText` -- a
+ *  media query has no way to win against one, and the size of a target
+ *  is not a preference.
+ */
+@media (pointer: coarse) {
+    .GOBJ_TREE_POPOVER_CLOSE {
+        min-width: 44px !important;
+        min-height: 44px !important;
+        font-size: 26px !important;
+        padding: 0 !important;
+        display: inline-flex !important;
+        align-items: center !important;
+        justify-content: center !important;
+    }
+}
+
 /*
  *  Picking the node to anchor: the pointer says a click is expected,
  *  which is otherwise announced only by a button at the far end of a
@@ -299,12 +327,20 @@
  *  things down one channel. `outline` draws OUTSIDE the box, so it
  *  cannot move a single row.
  *
+ *  DASHED, and the same dash the treedb graph draws inline for its own
+ *  cards: there, amber already means a find match or a focused topic
+ *  and blue means the selection, so a third SOLID ring would be a third
+ *  thing to learn in one channel. A dash is a different channel, and it
+ *  reads as the provisional thing a camera state is. One feature, one
+ *  drawing, in all three viewers.
+ *
  *  Amber, the same "this one, right now" the toolbar's arming state
  *  uses, and not one of the palette's action colours -- it is not an
  *  action.
  */
-.JSON_CARD_ANCHORED {
-    outline: 3px solid #fa8c16;
+.JSON_CARD_ANCHORED,
+.GOBJ_CARD_ANCHORED {
+    outline: 3px dashed #fa8c16;
     outline-offset: 2px;
 }
 

package/src/yui_gclass_view.js

@@ -0,0 +1,277 @@
+/***********************************************************************
+ *          yui_gclass_view.js
+ *
+ *          The gclass viewer: what a GClass IS, in a window.
+ *
+ *          The framework had no such viewer. The C kernel answers
+ *          `view-gclass` with a full description (attrs, commands,
+ *          methods, FSM) and the only reader of it was a terminal.
+ *          This one draws that same document with C_YUI_JSON, so the
+ *          FSM of a gclass is a graph and its attrs table is a tree,
+ *          and it takes the document from either side:
+ *
+ *            - a gclass of the browser yuno  -> describe_local_gclass()
+ *            - a gclass of a backend yuno    -> `opts.description`, the
+ *                                               answer of `view-gclass`
+ *
+ *          One window at a time per host: the caller keeps the handle
+ *          and closes it, the way the treedb graph keeps its raw-JSON
+ *          viewer.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {
+    clean_name,
+    gclass_find_by_name,
+    gobj_create_service,
+    gobj_destroy,
+    gobj_find_service,
+    gobj_is_running,
+    gobj_name,
+    gobj_read_pointer_attr,
+    gobj_short_name,
+    gobj_start,
+    gobj_stop,
+    is_gobj,
+    log_error,
+    log_warning,
+} from "@yuneta/gobj-js";
+
+import {describe_local_gclass} from "./gclass_describe.js";
+import {yui_shell_show_error, yui_shell_show_modal, yui_shell_popup_layer} from "./shell_modals.js";
+import {yui_shell_of} from "./c_yui_shell.js";
+
+import {t} from "i18next";
+
+
+/************************************************************
+ *  Can this app show a gclass at all?
+ *
+ *  The viewer is C_YUI_JSON, and an app registers only the
+ *  gclasses it mounts. The caller asks this BEFORE drawing a
+ *  button, so an app that does not carry the viewer shows no
+ *  control instead of a control that fails.
+ ************************************************************/
+function gclass_view_available()
+{
+    return !!gclass_find_by_name("C_YUI_JSON", false);
+}
+
+
+/************************************************************
+ *  Open the viewer on `gclass_name`.
+ *
+ *  opts:
+ *      description   the document to draw. Omitted, it is
+ *                    built from the browser registry.
+ *      title_prefix  what the window says before the gclass
+ *                    name (the yuno it belongs to).
+ *      on_close      called when the reader dismisses it.
+ *
+ *  Returns a handle for close_gclass_view(), or null (and a
+ *  logged reason) when there is nothing to show.
+ ************************************************************/
+function open_gclass_view(host, gclass_name, opts)
+{
+    opts = opts || {};
+
+    if(!host || !gclass_name) {
+        log_error(`yui_gclass_view: open without a host or a gclass name`);
+        return null;
+    }
+
+    let shell = yui_shell_of(host);
+
+    if(!gclass_view_available()) {
+        log_error(`${gobj_short_name(host)}: C_YUI_JSON not registered by the app`);
+        yui_shell_show_error(shell, "gclass viewer unavailable", {t: t});
+        return null;
+    }
+
+    let description = opts.description || describe_local_gclass(gclass_name);
+    if(!description) {
+        /*  Not an error: a gclass of a BACKEND yuno is not in this
+         *  registry and never will be. It is the caller's job to bring
+         *  the description; say which gclass could not be found.  */
+        log_warning(`${gobj_short_name(host)}: gclass not registered here: ${gclass_name}`);
+        yui_shell_show_error(shell, "gclass not registered in this yuno", {t: t});
+        return null;
+    }
+
+    let jv = gobj_create_service(
+        `gclass-view-${clean_name(gobj_name(host))}`,
+        "C_YUI_JSON",
+        {
+            /*  No `title`: the host titles it -- the window's title bar
+             *  on desktop, the dialog's header on mobile. The viewer's
+             *  own title would land INSIDE that host, doubling it.  */
+            json_data:  description,
+            subscriber: null,
+        },
+        host
+    );
+    if(!jv) {
+        log_error(`${gobj_short_name(host)}: cannot create the gclass viewer`);
+        return null;
+    }
+    gobj_start(jv);
+
+    let handle = {json_gobj: jv, win: null, modal: null};
+    let $box = gobj_read_pointer_attr(jv, "$container");
+
+    let on_close = () => {
+        if(typeof opts.on_close === "function") {
+            opts.on_close();
+        }
+    };
+
+    if(is_mobile()) {
+        if(!shell) {
+            log_error(`${gobj_short_name(host)}: no shell, cannot open the gclass sheet`);
+            close_gclass_view(handle);
+            return null;
+        }
+        handle.modal = yui_shell_show_modal(shell, $box, {
+            dialog:        true,
+            logical_class: "GCLASS_VIEW_SHEET",
+            title_prefix:  opts.title_prefix || "",
+            title:         gclass_name,
+            t:             t,
+            on_close:      on_close,
+        });
+        return handle;
+    }
+
+    let $win_parent = window_layer_of(host, shell);
+
+    handle.win = gobj_create_service(
+        `gclass-win-${clean_name(gobj_name(host))}`,
+        "C_YUI_WINDOW",
+        {
+            $parent:    $win_parent,
+            subscriber: null,
+            modal:      false,
+            showMax:    true,
+            showFooter: false,
+            resizable:  true,
+            center:     true,
+            auto_save_size_and_position: true,
+            width:      720,
+            height:     640,
+            logical_class: "GCLASS_VIEW_WINDOW",
+            title_prefix: opts.title_prefix || "",
+            title:      gclass_name,
+            icon:       "yi-code",
+            body:       $box,
+            /*  The same dock the other windows are on: raising a window
+             *  is the manager's job, and a viewer registered nowhere
+             *  cannot come to the front when the reader clicks it. `||
+             *  null` because gobj_find_service answers undefined when
+             *  absent, and an undefined attr logs "attr undefined".  */
+            manager:    gobj_find_service("__window_manager__", false) || null,
+            on_close:   on_close,
+        },
+        host
+    );
+    if(!handle.win) {
+        log_error(`${gobj_short_name(host)}: cannot create the gclass window`);
+        close_gclass_view(handle);
+        return null;
+    }
+    gobj_start(handle.win);
+
+    return handle;
+}
+
+/************************************************************
+ *  Close whatever open_gclass_view() opened. Safe on null and
+ *  on a handle whose window the reader already dismissed.
+ ************************************************************/
+function close_gclass_view(handle)
+{
+    if(!handle) {
+        return;
+    }
+
+    let jv = handle.json_gobj;
+    let win = handle.win;
+    let modal = handle.modal;
+
+    handle.json_gobj = null;
+    handle.win = null;
+    handle.modal = null;
+
+    if(win && is_gobj(win)) {
+        try {
+            /*  STOP, then destroy: gobj_destroy() raises the `destroying`
+             *  flag before it can stop a running gobj, so destroying it
+             *  straight logs two errors and skips mt_stop. The ✕ path
+             *  already stopped it (close_window) -- hence the guard.  */
+            if(gobj_is_running(win)) {
+                gobj_stop(win);
+            }
+            gobj_destroy(win);
+        } catch(e) {
+            log_warning(`yui_gclass_view: window already gone: ${e}`);
+        }
+    }
+    if(modal && typeof modal.close === "function") {
+        try {
+            modal.close();
+        } catch(e) {
+            log_warning(`yui_gclass_view: modal already gone: ${e}`);
+        }
+    }
+    if(jv && is_gobj(jv)) {
+        try {
+            if(gobj_is_running(jv)) {
+                gobj_stop(jv);
+            }
+            gobj_destroy(jv);
+        } catch(e) {
+            log_warning(`yui_gclass_view: viewer already gone: ${e}`);
+        }
+    }
+}
+
+/************************************************************
+ *  Where to mount the window: the SAME element the caller's
+ *  own window hangs from.
+ *
+ *  Not a preference -- a requirement. z-index only orders
+ *  siblings of one stacking context, so a viewer opened from a
+ *  window on `body` and mounted in the shell's popup layer
+ *  lands BEHIND its opener whatever number it is given, and
+ *  the button reads as one that did nothing.
+ ************************************************************/
+function window_layer_of(host, shell)
+{
+    let $c = gobj_read_pointer_attr(host, "$container");
+    if($c && typeof $c.closest === "function") {
+        let $win = $c.closest(".C_YUI_WINDOW");
+        if($win && $win.parentNode) {
+            return $win.parentNode;
+        }
+    }
+
+    return (typeof document !== "undefined" &&
+            document.getElementById("top-layer")) ||
+        (shell && yui_shell_popup_layer(shell)) ||
+        null;
+}
+
+/************************************************************
+ *  A window is not a sheet: below this width there is no room
+ *  for a title bar the reader can drag.
+ ************************************************************/
+function is_mobile()
+{
+    return typeof window !== "undefined" && window.innerWidth <= 768;
+}
+
+export {
+    gclass_view_available,
+    open_gclass_view,
+    close_gclass_view,
+};

package/src/yui_graph_camera.js

@@ -235,6 +235,66 @@ export function yui_graph_update_anchor($container, state)
  ************************************************************/
 const __centring__ = new WeakMap();
 
+/************************************************************
+ *   Put `node_id` at a GIVEN point of the viewport.
+ *
+ *   What "the graph does not jump when I fold something" is
+ *   made of: read where the card is, rebuild the layout, put
+ *   that card back where it was. Everything that did not move
+ *   in the layout stays put with it.
+ ************************************************************/
+export async function yui_graph_place_at(graph, node_id, viewport_xy)
+{
+    if(!graph || !node_id || !viewport_xy) {
+        return false;
+    }
+    try {
+        if(typeof graph.getElementPosition !== "function" ||
+                typeof graph.getCanvasCenter !== "function" ||
+                typeof graph.translateTo !== "function") {
+            return false;
+        }
+        let z = graph.getZoom() || 1;
+        let c = graph.getCanvasCenter();
+        let n = graph.getElementPosition(node_id);
+
+        /*
+         *  Same derivation as the centring below, with the target point
+         *  left free instead of fixed at the middle:
+         *
+         *      T = (canvasCentre - node) * zoom + (V - canvasCentre)
+         *
+         *  and putting V = canvasCentre gives the centring exactly.
+         */
+        await graph.translateTo([
+            (c[0] - n[0]) * z + (viewport_xy[0] - c[0]),
+            (c[1] - n[1]) * z + (viewport_xy[1] - c[1])
+        ]);
+        return true;
+    } catch(e) {
+        return false;   /*  the element is gone, or the graph is between renders  */
+    }
+}
+
+/************************************************************
+ *   Where `node_id` is right now, in viewport pixels.
+ *
+ *   The pair of the call above: read it before a rebuild, hand
+ *   it back after, and the node has not moved on screen even
+ *   though the layout under it changed.
+ ************************************************************/
+export function yui_graph_viewport_of(graph, node_id)
+{
+    if(!graph || !node_id) {
+        return null;
+    }
+    try {
+        return graph.getViewportByCanvas(graph.getElementPosition(node_id));
+    } catch(e) {
+        return null;
+    }
+}
+
 export async function yui_graph_center_on(graph, node_id)
 {
     if(!graph || !node_id) {