@yuneta/gobj-ui 7.2.5 → 7.4.0

package/src/c_g6_nodes_tree.js

@@ -31,6 +31,7 @@ import {
     gobj_read_attr,
     gobj_read_str_attr,
     gobj_read_bool_attr,
+    gobj_read_integer_attr,
     gobj_write_attr,
     gobj_write_str_attr,
     gobj_parent,
@@ -93,7 +94,7 @@ import {
     register,
 } from '@antv/g6';
 
-import {Circle as CircleGeometry} from '@antv/g';
+import {Circle as CircleGeometry, Rect as RectGeometry} from '@antv/g';
 import i18next, {t} from "i18next";
 
 import {inject_svg_icons} from "./lib_icons.js";
@@ -140,6 +141,14 @@ ensure_drag_canvas_patch();
  ***************************************************************/
 const GCLASS_NAME = "C_G6_NODES_TREE";
 
+/*  The highlight of a focused topic / a find match. It is drawn INTO the
+ *  node's own html, not with G6's `active` element state: every node here
+ *  is an `html` node, whose key shape is a DOM element — the state's
+ *  `stroke` / `halo` have nothing to paint on and the amber never
+ *  appeared, for the topic focus either.  */
+const HIGHLIGHT_COLOR = "#f0a020";
+const HIGHLIGHT_HALO  = "rgba(240,160,32,0.35)";
+
 /***************************************************************
  *  Internal layout and operation mode definitions
  ***************************************************************/
@@ -210,6 +219,7 @@ SDATA(data_type_t.DTP_BOOLEAN,  "with_treedb_tables",   0,  false,  "Include tre
 SDATA(data_type_t.DTP_BOOLEAN,  "with_gridline",        0,  true,   "Use gridline plugin"),
 SDATA(data_type_t.DTP_BOOLEAN,  "with_fullscreen",      0,  true,   "Use fullscreen plugin"),
 SDATA(data_type_t.DTP_BOOLEAN,  "with_toolbar",         0,  true,   "Use toolbar plugin"),
+SDATA(data_type_t.DTP_INTEGER,  "minimap_min_nodes",    0,  30,     "Show the minimap from this many nodes on (0 = never). A minimap of a graph that fits on screen is decoration; one of two hundred cards is the only way to know where you are"),
 SDATA(data_type_t.DTP_STRING,   "toolbar_position",     0,  "right-top",
     "Toolbar position: top-left, top-right, bottom-left, bottom-right, left-top, right-top"),
 SDATA(data_type_t.DTP_LIST,     "layout_names",         sdata_flag_t.SDF_RD,
@@ -2113,6 +2123,7 @@ function graph_focus_topic(gobj, topic)
             states[id] = ['active'];
         }
     }
+    let prev_ids = priv._focus_ids || [];
     priv._focus_ids = ids;
     priv._focus_topic = topic || null;
 
@@ -2120,6 +2131,7 @@ function graph_focus_topic(gobj, topic)
         if(typeof graph.setElementState === "function") {
             graph.setElementState(states);
         }
+        apply_node_highlight(gobj, prev_ids, ids);
         if(ids.length && typeof graph.focusElement === "function") {
             graph.focusElement(ids);
         }
@@ -2194,6 +2206,7 @@ function graph_find_nodes(gobj, term)
         }
     }
 
+    let prev_ids = priv._focus_ids || [];
     priv._focus_ids = ids;
     priv._focus_topic = null;       /*  a find takes over the highlight  */
 
@@ -2201,6 +2214,7 @@ function graph_find_nodes(gobj, term)
         if(typeof graph.setElementState === "function") {
             graph.setElementState(states);
         }
+        apply_node_highlight(gobj, prev_ids, ids);
         if(ids.length && typeof graph.focusElement === "function") {
             graph.focusElement(ids);
         }
@@ -4469,6 +4483,154 @@ function show_node_detail_popover(gobj, node_id)
  *  not re-themed by setTheme()) are regenerated; structural
  *  junction diamonds get their neutral fill/stroke re-themed.
  ************************************************************/
+/************************************************************
+ *  Show or hide the minimap, deciding by the SIZE of the graph.
+ *
+ *  A minimap of a graph that already fits on screen is decoration; one
+ *  of two hundred cards is the only way to know where you are. So it is
+ *  not a preference the reader has to find and set — it appears when
+ *  there is something to be lost in, from `minimap_min_nodes` on.
+ *
+ *  Its shapes are drawn by hand. G6's minimap clones each element's key
+ *  shape into its own canvas, and every node here is an `html` node
+ *  whose key shape is a DOM element — the same reason the `active`
+ *  state never painted (see HIGHLIGHT_COLOR). A block in the topic's
+ *  colour is also what a minimap of cards SHOULD show: at that scale a
+ *  card is a rectangle anyway.
+ ************************************************************/
+function refresh_minimap(gobj)
+{
+    let priv = gobj.priv;
+    let graph = priv.graph;
+    if(!graph) {
+        return;
+    }
+
+    let threshold = gobj_read_integer_attr(gobj, "minimap_min_nodes");
+    let n = 0;
+    try {
+        let data = graph.getData() || {};
+        n = is_array(data.nodes)? data.nodes.length : 0;
+    } catch(e) {
+        n = 0;
+    }
+
+    if(!threshold || n < threshold) {
+        graph_remove_plugin(gobj, "minimap");
+        return;
+    }
+
+    if(graph_get_plugin(gobj, "minimap")) {
+        return;         /*  already up  */
+    }
+
+    graph_add_plugin(
+        gobj,
+        "minimap",
+        {
+            size: [200, 140],
+            position: "bottom-left",
+            shape: (id, element_type, element) => {
+                if(element_type !== "node") {
+                    return element;     /*  edges clone themselves fine  */
+                }
+                try {
+                    let nd = graph.getNodeData(id);
+                    let size = (nd && nd.style && nd.style.size) || [120, 60];
+                    let color = (nd && nd.data && nd.data.desc && nd.data.desc.color)
+                        || "#94a3b8";
+                    return new RectGeometry({
+                        style: {
+                            x: -size[0] / 2,
+                            y: -size[1] / 2,
+                            width: size[0],
+                            height: size[1],
+                            fill: color,
+                            radius: 4
+                        }
+                    });
+                } catch(e) {
+                    log_error(`${gobj_short_name(gobj)}: minimap shape failed: ${e}`);
+                    return element;
+                }
+            }
+        }
+    );
+}
+
+/************************************************************
+ *  The innerHTML of ONE node, in the given theme and highlight state.
+ *  The three treedb tiers (hierarchical / extended / child) each have
+ *  their own card, and both the theme refresh and the highlight need the
+ *  same three-way choice — it lived inline in the theme refresh and is
+ *  shared now. Returns null for a node that carries no desc.
+ ************************************************************/
+function node_innerHTML_of(nd, theme, highlight)
+{
+    if(!nd || !nd.data || !nd.data.desc) {
+        return null;
+    }
+    let desc = nd.data.desc;
+    let record = nd.data.record || {};
+    let label = node_label(desc, record);
+
+    switch(desc.node_treedb_type) {
+        case 'child':
+            return build_chip_innerHTML(
+                desc.color, theme, record.icon, label, record.id, highlight
+            );
+        case 'extended':
+            return build_node_innerHTML(
+                desc.color, theme, record.icon, label,
+                desc.topic_name, true, record.id, highlight
+            );
+        case 'hierarchical':
+            return build_node_innerHTML(
+                desc.color, theme, record.icon, label,
+                desc.topic_name, false, record.id, highlight
+            );
+    }
+    return null;
+}
+
+/************************************************************
+ *  Repaint the cards whose highlight state CHANGES: the ones that had it
+ *  and lose it, plus the ones that gain it. Only those — a treedb graph
+ *  is redrawn per keystroke of the find box otherwise.
+ ************************************************************/
+function apply_node_highlight(gobj, prev_ids, next_ids)
+{
+    let priv = gobj.priv;
+    let graph = priv.graph;
+    if(!graph) {
+        return;
+    }
+
+    let next = new Set(next_ids || []);
+    let touched = new Set([...(prev_ids || []), ...next]);
+    if(touched.size === 0) {
+        return;
+    }
+
+    let updates = [];
+    for(let id of touched) {
+        let nd = graph.getNodeData(id);
+        let html = node_innerHTML_of(nd, priv.theme, next.has(id));
+        if(html !== null) {
+            updates.push({id: id, style: {innerHTML: html}});
+        }
+    }
+    if(!updates.length) {
+        return;
+    }
+    try {
+        graph.updateNodeData(updates);
+        graph.draw();
+    } catch(e) {
+        log_error(`${gobj_short_name(gobj)}: cannot repaint the highlight: ${e}`);
+    }
+}
+
 function refresh_html_nodes_theme(gobj, theme)
 {
     let priv = gobj.priv;
@@ -4477,46 +4639,16 @@ function refresh_html_nodes_theme(gobj, theme)
         return;
     }
     let nodes = graph.getData().nodes || [];
+    /*  The highlight is part of the card's html, so a theme switch that
+     *  rebuilt every card without it would silently CLEAR the focus or the
+     *  find that is on screen. Carry it across. */
+    let highlighted = new Set(priv._focus_ids || []);
     let updates = [];
     for(let i = 0; i < nodes.length; i++) {
-        let nd = graph.getNodeData(nodes[i].id);
-        if(!nd || !nd.data || !nd.data.desc) {
-            continue;
-        }
-        let tt = nd.data.desc.node_treedb_type;
-        let record = nd.data.record || {};
-        if(tt === 'hierarchical') {
-            updates.push({
-                id: nodes[i].id,
-                style: {
-                    innerHTML: build_node_innerHTML(
-                        nd.data.desc.color, theme, record.icon,
-                        node_label(nd.data.desc, record),
-                        nd.data.desc.topic_name, false, record.id
-                    )
-                }
-            });
-        } else if(tt === 'child') {
-            updates.push({
-                id: nodes[i].id,
-                style: {
-                    innerHTML: build_chip_innerHTML(
-                        nd.data.desc.color, theme, record.icon,
-                        node_label(nd.data.desc, record), record.id
-                    )
-                }
-            });
-        } else if(tt === 'extended') {
-            updates.push({
-                id: nodes[i].id,
-                style: {
-                    innerHTML: build_node_innerHTML(
-                        nd.data.desc.color, theme, record.icon,
-                        node_label(nd.data.desc, record),
-                        nd.data.desc.topic_name, true, record.id
-                    )
-                }
-            });
+        let id = nodes[i].id;
+        let html = node_innerHTML_of(graph.getNodeData(id), theme, highlighted.has(id));
+        if(html !== null) {
+            updates.push({id: id, style: {innerHTML: html}});
         }
     }
     if(updates.length > 0) {
@@ -4559,7 +4691,7 @@ function refresh_default_edges_theme(gobj, theme)
  *  but lighter (1px border, no shadow, single line). The name is
  *  always legible (ellipsis + native title tooltip on overflow).
  ************************************************************/
-function build_chip_innerHTML(color, theme, icon, label, key)
+function build_chip_innerHTML(color, theme, icon, label, key, highlight)
 {
     let title = key || label;
     let dark = (theme === "dark");
@@ -4571,6 +4703,9 @@ function build_chip_innerHTML(color, theme, icon, label, key)
         ? `color-mix(in srgb, ${color} 85%, #ffffff)`
         : color;
     let text_color = dark ? "#e8eaed" : "#0f172a";
+    if(highlight) {
+        border = HIGHLIGHT_COLOR;
+    }
 
     let icon_html = "";
     if(icon) {
@@ -4586,7 +4721,8 @@ function build_chip_innerHTML(color, theme, icon, label, key)
     width: 100%;
     height: 100%;
     background: ${bg};
-    border: 1px solid ${border};
+    border: ${highlight? "3px" : "1px"} solid ${border};
+    ${highlight? `box-shadow: 0 0 0 4px ${HIGHLIGHT_HALO};` : ""}
     border-radius: 8px;
     color: ${text_color};
     font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
@@ -4613,7 +4749,7 @@ function build_chip_innerHTML(color, theme, icon, label, key)
  *  colour is kept (per-topic differentiation) but softened via
  *  color-mix instead of a harsh saturated fill. Theme-aware.
  ************************************************************/
-function build_node_innerHTML(color, theme, icon, label, topic_name, structural, key)
+function build_node_innerHTML(color, theme, icon, label, topic_name, structural, key, highlight)
 {
     let title = key || label;
     let dark = (theme === "dark");
@@ -4639,6 +4775,10 @@ function build_node_innerHTML(color, theme, icon, label, topic_name, structural,
             : color;
         border_style = "solid";
     }
+    if(highlight) {
+        border = HIGHLIGHT_COLOR;
+        border_style = "solid";
+    }
     let title_color = dark ? "#e8eaed" : "#0f172a";
     let sub_color = dark ? "#9aa4b2" : "#64748b";
     let shadow = dark
@@ -4670,9 +4810,9 @@ function build_node_innerHTML(color, theme, icon, label, topic_name, structural,
     width: 100%;
     height: 100%;
     background: ${bg};
-    border: 1.5px ${border_style} ${border};
+    border: ${highlight? "3px" : "1.5px"} ${border_style} ${border};
     border-radius: 10px;
-    box-shadow: ${shadow};
+    box-shadow: ${highlight? `0 0 0 4px ${HIGHLIGHT_HALO}, ${shadow}` : shadow};
     color: ${title_color};
     font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
     display: flex;
@@ -5623,6 +5763,9 @@ function ac_load_data(gobj, event, kw, src)
                     } else {
                         graph_remove_plugin(gobj, "history");
                     }
+                    /*  The graph knows its size now: a minimap appears only
+                     *  when there is something to be lost in. */
+                    refresh_minimap(gobj);
                     /*  Nodes exist and are positioned now: apply a focus
                      *  requested before the data was ready (deep link). */
                     if(priv._pending_focus_topic !== null) {

package/src/c_yui_treedb_graph.js

@@ -147,6 +147,8 @@ let PRIVATE_DATA = {
     topics:             [],
     records:            {},
     gobj_nodes_tree:    null,
+    find_timer:         null,       // rate-limits the find box (see make_toolbar)
+    focus_topic:        "",         // topic the graph is focused on (marks the legend)
     gobj_treedb_tables: null,
     hook_data_viewer:   null,
     json_gobj:          null,   /*  C_YUI_JSON viewer of the raw tranger (or null)  */
@@ -310,6 +312,14 @@ function mt_stop(gobj)
  ***************************************************************/
 function mt_destroy(gobj)
 {
+    let priv = gobj.priv;
+    /*  The find box rate-limits itself with a timer; a view torn down
+     *  between the keystroke and the send would fire an event into a
+     *  destroyed gobj. */
+    if(priv.find_timer) {
+        clearTimeout(priv.find_timer);
+        priv.find_timer = null;
+    }
     destroy_ui(gobj);
 }
 
@@ -345,6 +355,13 @@ function build_ui(gobj)
         // Don't use is-flex, don't work well with is-hidden
         ['div', {class: 'C_YUI_TREEDB_GRAPH', style: `height:100%; display:flex; flex-direction:column;`}, [
             ['div', {class: 'GRAPH_TOOLBAR_ROW is-flex-grow-0 is-flex is-align-items-center'}, row_items],
+            /*  Topic colour legend: a strip, not an overlay. It is opened to
+             *  be READ against the graph, and an overlay would cover the
+             *  thing it explains. Built on first open (the colours are the
+             *  child's, assigned when the schema arrives). */
+            ['div', {class: 'GRAPH_LEGEND is-hidden is-flex-grow-0',
+                     style: 'display:flex; flex-wrap:wrap; align-items:center; ' +
+                            'gap:.4rem; padding:.35rem .5rem;'}, []],
             ['div', {class: `GRAPH_BODY is-flex-grow-1 ${padding}`, style: 'height:100%; min-height:0; overflow:hidden;'}, [
                 ['div', {id: priv.canvas_id, class: `GRAPH_CANVAS graph-container`, style: 'height:100%; min-height:0;border: 1px solid var(--bulma-border-weak);border-radius:0.2rem;'}, [
                 ]]
@@ -487,6 +504,23 @@ function make_toolbar(gobj)
             }
         }],
 
+        /*  Which colour is which topic. The port colour of a node encodes
+         *  the topic it links to, which is the whole point of the graph and
+         *  which nothing on screen explained. Clicking an entry focuses that
+         *  topic, so the legend is also the way to say "show me these" —
+         *  and clicking the focused one again clears it.  */
+        ['button', {class: 'GRAPH_LEGEND_BTN button ml-2',
+                    title: t('legend'), 'aria-label': t('legend'),
+                    'data-i18n-title': 'legend', 'data-i18n-aria-label': 'legend'}, [
+            ['i', {class: 'yi-square'}],
+            ['span', {class: 'is-hidden-mobile', style: 'padding-left:5px;', i18n: 'legend'}, 'legend']
+        ], {
+            click: (evt) => {
+                evt.stopPropagation();
+                gobj_send_event(gobj, "EV_TOGGLE_LEGEND", {}, gobj);
+            }
+        }],
+
         /*  Inspect the treedb's raw tranger json in the lazy tree viewer
          *  (print-tranger on the C_NODE service). A treedb can be huge, so
          *  the viewer drills in on demand — see open_json_viewer.  */
@@ -530,14 +564,21 @@ function make_toolbar(gobj)
                 ['i', {class: 'yi-magnifying-glass'}]
             ]]
         ], {
+            /*  Rate-limited, not delayed for effect: a match repaints the
+             *  cards it lands on, and on a large treedb the first letter
+             *  typed can match hundreds. This is input plumbing — the
+             *  event still carries every action to the FSM, just not one
+             *  per keystroke. */
             input: (evt) => {
                 evt.stopPropagation();
-                gobj_send_event(
-                    gobj,
-                    "EV_FIND_NODES",
-                    {text: evt.target.value.trim()},
-                    gobj
-                );
+                let text = evt.target.value.trim();
+                if(priv.find_timer) {
+                    clearTimeout(priv.find_timer);
+                }
+                priv.find_timer = setTimeout(function() {
+                    priv.find_timer = null;
+                    gobj_send_event(gobj, "EV_FIND_NODES", {text: text}, gobj);
+                }, 250);
             }
         }],
         /*  Two spans, not one string: the number is DATA and "matches" is
@@ -2178,6 +2219,115 @@ function ac_set_operation_mode(gobj, event, kw, src)
  *  tree, which centres + highlights that topic's nodes (deferring
  *  until its data is loaded).
  ************************************************************/
+/************************************************************
+ *  Fill the legend strip with one entry per topic: a swatch in the
+ *  topic's colour and its name. The colours belong to the graph child —
+ *  it assigns them from its palette when the schema arrives — so they
+ *  are read from there and never guessed twice.
+ *
+ *  An entry is a BUTTON: clicking it focuses that topic, clicking the
+ *  focused one clears the focus. The focus travels the same way a topic
+ *  card's graph icon travels — as EV_TOPIC_SELECTED, which the host turns
+ *  into the URL, so what you are looking at stays linkable.
+ ************************************************************/
+function refresh_legend(gobj)
+{
+    let priv = gobj.priv;
+    let $container = gobj_read_attr(gobj, "$container");
+    if(!$container) {
+        return;
+    }
+    let $legend = $container.querySelector(".GRAPH_LEGEND");
+    if(!$legend) {
+        return;
+    }
+
+    let descs = priv.gobj_nodes_tree?
+        gobj_read_attr(priv.gobj_nodes_tree, "descs") : null;
+    $legend.textContent = "";
+    if(!descs) {
+        return;
+    }
+
+    for(const [topic_name, desc] of Object.entries(descs)) {
+        if(topic_name.substring(0, 2) === "__") {
+            continue;       /*  the internal topics are not drawn  */
+        }
+        if(!desc || !desc.color) {
+            continue;
+        }
+        let focused = (priv.focus_topic === topic_name);
+        let $item = createElement2(
+            ['button', {
+                class: 'GRAPH_LEGEND_ITEM button is-small' +
+                       (focused? ' is-primary' : ''),
+                title: topic_name,
+                'aria-label': topic_name,
+                'aria-pressed': focused? 'true' : 'false'
+            }, [
+                ['span', {class: 'GRAPH_LEGEND_SWATCH',
+                          style: `display:inline-block; width:.8rem; height:.8rem; ` +
+                                 `border-radius:3px; margin-right:.4rem; ` +
+                                 `background:${desc.color}; ` +
+                                 `border:1px solid rgba(0,0,0,.25);`}],
+                /*  The topic name is DATA: it carries no i18n key and is
+                 *  never translated. */
+                ['span', {}, topic_name]
+            ], {
+                click: (evt) => {
+                    evt.stopPropagation();
+                    gobj_send_event(gobj, "EV_LEGEND_TOPIC", {topic: topic_name}, gobj);
+                }
+            }]
+        );
+        $legend.appendChild($item);
+    }
+}
+
+/************************************************************
+ *
+ ************************************************************/
+function ac_toggle_legend(gobj, event, kw, src)
+{
+    let $container = gobj_read_attr(gobj, "$container");
+    if(!$container) {
+        return 0;
+    }
+    let $legend = $container.querySelector(".GRAPH_LEGEND");
+    if(!$legend) {
+        log_error(`${gobj_short_name(gobj)}: no legend strip to toggle`);
+        return -1;
+    }
+    if($legend.classList.contains("is-hidden")) {
+        refresh_legend(gobj);
+        $legend.classList.remove("is-hidden");
+    } else {
+        $legend.classList.add("is-hidden");
+    }
+    return 0;
+}
+
+/************************************************************
+ *  A legend entry was clicked: focus that topic, or clear the focus if
+ *  it was already the focused one. Published UP rather than applied
+ *  here, so the URL follows — the host owns the route.
+ ************************************************************/
+function ac_legend_topic(gobj, event, kw, src)
+{
+    let priv = gobj.priv;
+    let topic = (kw && kw.topic) || "";
+    if(!topic) {
+        log_error(`${gobj_short_name(gobj)}: legend click with no topic`);
+        return -1;
+    }
+    gobj_publish_event(
+        gobj,
+        "EV_TOPIC_SELECTED",
+        {topic: (priv.focus_topic === topic)? "" : topic}
+    );
+    return 0;
+}
+
 /************************************************************
  *  Forward the find down to the graph child.
  ************************************************************/
@@ -2226,14 +2376,22 @@ function ac_find_result(gobj, event, kw, src)
 function ac_set_focus_topic(gobj, event, kw, src)
 {
     let priv = gobj.priv;
+    priv.focus_topic = (kw && kw.topic) || "";
     if(priv.gobj_nodes_tree) {
         gobj_send_event(
             priv.gobj_nodes_tree,
             "EV_FOCUS_TOPIC",
-            {topic: kw && kw.topic},
+            {topic: priv.focus_topic},
             gobj
         );
     }
+    /*  Keep the legend's mark on the topic that is actually focused —
+     *  including when the focus arrives from the URL and not from a click. */
+    let $container = gobj_read_attr(gobj, "$container");
+    let $legend = $container? $container.querySelector(".GRAPH_LEGEND") : null;
+    if($legend && !$legend.classList.contains("is-hidden")) {
+        refresh_legend(gobj);
+    }
     return 0;
 }
 
@@ -2323,6 +2481,8 @@ function create_gclass(gclass_name)
             ["EV_SET_OPERATION_MODE",       ac_set_operation_mode,      null],
             ["EV_SET_FOCUS_TOPIC",          ac_set_focus_topic,         null],
             ["EV_FIND_NODES",               ac_find_nodes,              null],
+            ["EV_TOGGLE_LEGEND",            ac_toggle_legend,           null],
+            ["EV_LEGEND_TOPIC",             ac_legend_topic,            null],
             ["EV_FIND_RESULT",              ac_find_result,             null],
             ["EV_SHOW",                     ac_show,                    null],
             ["EV_HIDE",                     ac_hide,                    null],
@@ -2360,6 +2520,10 @@ function create_gclass(gclass_name)
         ["EV_SET_FOCUS_TOPIC",          0],
         ["EV_FIND_NODES",               0],
         ["EV_FIND_RESULT",              0],
+        ["EV_TOGGLE_LEGEND",            0],
+        ["EV_LEGEND_TOPIC",             0],
+        ["EV_TOPIC_SELECTED",
+            event_flag_t.EVF_OUTPUT_EVENT | event_flag_t.EVF_NO_WARN_SUBS],
         ["EV_OPERATION_MODE_CHANGED",
             event_flag_t.EVF_OUTPUT_EVENT | event_flag_t.EVF_NO_WARN_SUBS],
         ["EV_RECORD_WRITTEN",