@yuneta/gobj-ui 7.23.140 → 7.23.142

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuneta/gobj-ui",
-  "version": "7.23.140",
+  "version": "7.23.142",
   "type": "module",
   "main": "dist/gobj-ui.cjs.js",
   "module": "dist/gobj-ui.es.js",
@@ -20,7 +20,7 @@
     "src/",
     "vite-plugin-yuneta-html.js"
   ],
-  "description": "Yuneta UI Library \u2014 the active line: declarative shell (C_YUI_SHELL+NAV+PAGER+WIZARD) + windows, TreeDB views, forms, charts and maps.  Consumed by wattyzer and the yunetas JS yunos (gui_agent, gui_treedb).  The frozen legacy GClass GUI stack (C_YUI_MAIN/TABS/ROUTING) lives on the v1 branch, npm dist-tag 'legacy' (consumed by estadodelaire and hidraulia).",
+  "description": "Yuneta UI Library — the active line: declarative shell (C_YUI_SHELL+NAV+PAGER+WIZARD) + windows, TreeDB views, forms, charts and maps.  Consumed by wattyzer and the yunetas JS yunos (gui_agent, gui_treedb).  The frozen legacy GClass GUI stack (C_YUI_MAIN/TABS/ROUTING) lives on the v1 branch, npm dist-tag 'legacy' (consumed by estadodelaire and hidraulia).",
   "scripts": {
     "build": "vite build",
     "test": "vitest run",

package/src/c_g6_nodes_tree.js

@@ -13,8 +13,9 @@
  *          The graph opens FOLDED, like a JSON viewer.
  *
  *          Every record of every topic is fetched, but only the ones on
- *          screen become G6 nodes: the roots, `expand_depth` levels under
- *          them, one page (`fold_page_size`) of children per hook. Each
+ *          screen become G6 nodes: the roots, and the MAIN tree open to
+ *          the reader's level (`fold_level`, `expand_depth` until they
+ *          step it), one page (`fold_page_size`) of children per hook. Each
  *          card carries a pill per hook that has children -- `▸ devices
  *          142` -- which opens or folds that hook; an open hook with more
  *          children than its page ends in a `+N` chip that opens the next
@@ -117,9 +118,11 @@ import {
     fold_build_model,
     fold_new_state,
     fold_visible_set,
-    fold_expand_to_depth,
-    fold_expand_all,
-    fold_collapse_all,
+    fold_expand_to_level,
+    fold_open_levels,
+    fold_close_levels,
+    fold_level_clamp,
+    fold_is_hierarchical,
     fold_toggle,
     fold_show_more,
     fold_reveal,
@@ -299,14 +302,14 @@ const PORT_LINE_WIDTH = 2;
 const NODE_MODES = ['expanded', 'compact', 'shape'];
 
 const PILL_SIZE = {
-    hierarchical: [200, 30],
+    entity:       [200, 30],
     extended:     [180, 28],
     child:        [160, 26],
 };
 const PORT_R_PILL = 6;
 
 const SHAPE_SIZE = {
-    hierarchical: 32,
+    entity:       32,
     extended:     28,
     child:        22,
 };
@@ -434,7 +437,8 @@ SDATA(data_type_t.DTP_STRING,   "hook_port_position",   0,  "bottom",   "Hook po
 SDATA(data_type_t.DTP_STRING,   "fkey_port_position",   0,  "top",      "Fkey port position"),
 
 /*---------------- Folding ----------------*/
-SDATA(data_type_t.DTP_INTEGER,  "expand_depth",         0,  2,      "Levels open when a treedb loads: 1 = the roots alone, 2 = the roots and their children. Every open hook shows its first page"),
+SDATA(data_type_t.DTP_INTEGER,  "expand_depth",         0,  1,      "Levels open when a treedb loads, until the reader steps (`fold_level`): 1 = the roots alone (the default), 2 = the roots and their children. Every open hook shows its first page"),
+SDATA(data_type_t.DTP_INTEGER,  "fold_level",           0,  0,      "The level of the MAIN tree the toolbar's stepper stands on: 1 = its roots, N = N-1 levels under them; 0 = `expand_depth`. The host persists it and sends EV_SET_FOLD_LEVEL; it is published back in EV_LEGEND_STATE (`fold`) with the levels the tree has"),
 SDATA(data_type_t.DTP_INTEGER,  "fold_page_size",       0,  24,     "Children of one hook shown per page; the `+N` chip after the page opens the next one"),
 SDATA(data_type_t.DTP_LIST,     "hidden_topics",        0,  "[]",   "Topics left out of the tree: no card, no pill counts them, no edge reaches them"),
 SDATA(data_type_t.DTP_STRING,   "main_topic",           0,  "",     "The topic the tree hangs from; empty = deduced (the one whose hooks reach the most others). Its parentless records are the roots; a parentless record of a topic linked to it is LOOSE and shown only on request"),
@@ -542,7 +546,8 @@ let PRIVATE_DATA = {
     _nodes_placed:      0,          // ...of which carry a saved position
 
     /*---------------- folding ----------------*/
-    expand_depth:       2,
+    expand_depth:       1,
+    fold_level:         0,
     fold_page_size:     24,
     hidden_topics:      null,
     main_topic:         "",
@@ -1855,7 +1860,12 @@ function configure_behaviour(gobj)
 }
 
 /************************************************************
- *  Count hooks and fkeys in topic desc, classify node type
+ *  Count hooks and fkeys in topic desc, classify node type:
+ *  `child` (no hooks), `extended` (hooks, no fkeys), `entity`
+ *  (both). It sizes the card and nothing else. It used to be
+ *  called `hierarchical`, and that word means something else now:
+ *  a topic hooked to ITSELF, the only kind a tree can hang from
+ *  (treedb_fold_model).
  ************************************************************/
 function calculate_hooks_fkeys_counter(desc)
 {
@@ -1881,7 +1891,7 @@ function calculate_hooks_fkeys_counter(desc)
     } else if(desc.fkeys_counter === 0) {
         desc.node_treedb_type = 'extended';
     } else {
-        desc.node_treedb_type = 'hierarchical';
+        desc.node_treedb_type = 'entity';
     }
 }
 
@@ -2302,7 +2312,7 @@ function card_shape_of(gobj, desc, record, geometry, pills_html)
             desc.topic_name, true, record.id, false, false, false, pills_html
         );
     } else {
-        // Hierarchical entity (ROOT / container): largest tier.
+        // Entity, hooks and fkeys (ROOT / container): largest tier.
         style.innerHTML = build_node_innerHTML(
             paint.fill, priv.theme, record.icon, label,
             desc.topic_name, false, record.id, false, false, false, pills_html
@@ -2405,7 +2415,7 @@ function pill_shape_of(gobj, desc, record, geometry)
 {
     let priv = gobj.priv;
     let tier = desc.node_treedb_type;
-    let size = PILL_SIZE[tier] || PILL_SIZE.hierarchical;
+    let size = PILL_SIZE[tier] || PILL_SIZE.entity;
     let ports = build_ports(gobj, desc);
     let paint = node_paint_of(gobj, desc, geometry);
 
@@ -2468,7 +2478,7 @@ function figure_shape_of(gobj, desc, record, geometry, flags)
     let dark = (priv.theme === "dark");
     let f = flags || {};
     let tier = desc.node_treedb_type;
-    let side = SHAPE_SIZE[tier] || SHAPE_SIZE.hierarchical;
+    let side = SHAPE_SIZE[tier] || SHAPE_SIZE.entity;
     let labels = gobj_read_bool_attr(gobj, "node_labels");
     let figure = node_figure_of(gobj, desc, geometry || {});
     let paint = node_paint_of(gobj, desc, geometry);
@@ -7038,7 +7048,7 @@ function show_node_detail_popover(gobj, node_id)
 }
 
 /************************************************************
- *  Re-render every HTML (hierarchical) node so its card adopts
+ *  Re-render every HTML (entity) node so its card adopts
  *  the given theme: entity cards and leaf chips (baked innerHTML,
  *  not re-themed by setTheme()) are regenerated; structural
  *  junction diamonds get their neutral fill/stroke re-themed.
@@ -7254,7 +7264,7 @@ function refresh_minimap(gobj)
 
 /************************************************************
  *  The innerHTML of ONE node, in the given theme and highlight state.
- *  The three treedb tiers (hierarchical / extended / child) each have
+ *  The three treedb tiers (entity / 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.
@@ -7291,7 +7301,7 @@ function node_innerHTML_of(nd, theme, highlight, selected, anchored, pills_html)
                 desc.topic_name, true, record.id, highlight, selected, anchored,
                 pills_html
             );
-        case 'hierarchical':
+        case 'entity':
             return build_node_innerHTML(
                 fill, theme, record.icon, label,
                 desc.topic_name, false, record.id, highlight, selected, anchored,
@@ -7565,7 +7575,7 @@ function build_chip_innerHTML(color, theme, icon, label, key, highlight, selecte
 }
 
 /************************************************************
- *  Build innerHTML for hierarchical (HTML) nodes.
+ *  Build innerHTML for entity (HTML) nodes.
  *
  *  Card style modelled on the documentation schema graphs
  *  (docs gen_treedb_graphs.py): rounded card, soft tint of the
@@ -9534,13 +9544,24 @@ function publish_legend_state(gobj, visible)
             loose_shown: model.loose_shown.has(topic_name),
             hidden: model.hidden.has(topic_name),
             linked: model.linked.has(topic_name),
+            hierarchical: fold_is_hierarchical(priv.descs, topic_name),
         });
     }
 
     gobj_publish_event(gobj, "EV_LEGEND_STATE", {
         main_topic: model.main_topic,
-        main_chosen: !!gobj_read_str_attr(gobj, "main_topic"),
+        /*  CHOSEN only when the reader's pick is the one in force: a
+         *  pick the rule refuses (not hierarchical) is ignored.  */
+        main_chosen: !!model.main_topic &&
+                     gobj_read_str_attr(gobj, "main_topic") === model.main_topic,
         topics: topics,
+        /*  The toolbar's stepper: the tree it walks, where it stands,
+         *  and how deep it goes. `levels` 0 = nothing to step through.  */
+        fold: {
+            topic: model.main_topic,
+            level: current_fold_level(gobj),
+            levels: model.levels,
+        },
     });
 }
 
@@ -10003,14 +10024,13 @@ function ac_load_data(gobj, event, kw, src)
     }
 
     if(all_loaded && priv.graph) {
-        /*  The tree of the records, opened `expand_depth` levels: the
-         *  roots and their children by default. Only that much becomes
-         *  G6 nodes -- a treedb of a thousand records opens as a
-         *  handful of cards with a count on each cut.  */
+        /*  The tree of the records, the main one opened to the reader's
+         *  level: the roots and their children by default. Only that
+         *  much becomes G6 nodes -- a treedb of a thousand records opens
+         *  as a handful of cards with a count on each cut.  */
         rebuild_fold_model(gobj);
-        fold_expand_to_depth(
-            priv._fold_model, priv._fold_state,
-            gobj_read_integer_attr(gobj, "expand_depth")
+        fold_expand_to_level(
+            priv._fold_model, priv._fold_state, current_fold_level(gobj)
         );
 
         /*  Before the layout runs, and only now: whether anybody has
@@ -10622,21 +10642,62 @@ function ac_show_more(gobj, event, kw, src)
 }
 
 /************************************************************
- *  The whole treedb, every hook open on all its children. This
- *  is the reader asking for the pile on purpose; the pages are
- *  the other way in.
+ *  The level of the main tree the toolbar's stepper stands on:
+ *  `fold_level` once the reader has stepped, `expand_depth`
+ *  until then, clamped to the levels the tree has.
  ************************************************************/
-function ac_expand_all(gobj, event, kw, src)
+function current_fold_level(gobj)
 {
     let priv = gobj.priv;
+    let level = gobj_read_integer_attr(gobj, "fold_level");
 
+    if(!(level > 0)) {
+        level = gobj_read_integer_attr(gobj, "expand_depth");
+    }
     if(!priv._fold_model) {
-        log_error(`${gobj_short_name(gobj)}: expand all with no tree loaded`);
+        return level;
+    }
+    return fold_level_clamp(priv._fold_model, level);
+}
+
+/************************************************************
+ *  The toolbar's stepper: one level more or one less of the
+ *  MAIN tree (the host owns the number and persists it; this
+ *  applies it). Deeper opens the hooks above the new level,
+ *  shallower folds from it down -- a level is a floor, not a
+ *  picture, so what the reader opened by its pill stays (see
+ *  treedb_fold_model). Replaces expand all / collapse all
+ *  (7.23.141): the whole treedb at once was the pile, and
+ *  closing threw away everything the reader had opened.
+ ************************************************************/
+function ac_set_fold_level(gobj, event, kw, src)
+{
+    let priv = gobj.priv;
+    let level = Number(kw && kw.level);
+
+    if(!(level > 0)) {
+        log_error(`${gobj_short_name(gobj)}: fold level '${kw && kw.level}' is not a level`);
         return -1;
     }
+    if(!priv._fold_model) {
+        gobj_write_attr(gobj, "fold_level", level);
+        return 0;       /*  applied when the records arrive  */
+    }
+
+    let from = current_fold_level(gobj);
+    level = fold_level_clamp(priv._fold_model, level);
+    gobj_write_attr(gobj, "fold_level", level);
+    if(level === from) {
+        return 0;
+    }
+
     let keep = fold_keep_node(gobj);
     let vp = yui_graph_viewport_of(priv.graph, keep);
-    fold_expand_all(priv._fold_model, priv._fold_state);
+    if(level > from) {
+        fold_open_levels(priv._fold_model, priv._fold_state, level);
+    } else {
+        fold_close_levels(priv._fold_model, priv._fold_state, level);
+    }
     reconcile_fold(gobj, {keep: keep, keep_vp: vp});
 
     return 0;
@@ -10669,31 +10730,12 @@ function fold_keep_node(gobj)
     return "";
 }
 
-/************************************************************
- *  The roots alone.
- ************************************************************/
-function ac_collapse_all(gobj, event, kw, src)
-{
-    let priv = gobj.priv;
-
-    if(!priv._fold_model) {
-        log_error(`${gobj_short_name(gobj)}: collapse all with no tree loaded`);
-        return -1;
-    }
-    let keep = fold_keep_node(gobj);
-    let vp = yui_graph_viewport_of(priv.graph, keep);
-    fold_collapse_all(priv._fold_model, priv._fold_state);
-    reconcile_fold(gobj, {keep: keep, keep_vp: vp});
-
-    return 0;
-}
-
 /************************************************************
  *  The legend's three settings, from the host, which persists
  *  them. Each rebuilds the tree; the fold state is kept -- it is
  *  keyed by group, and a group that is gone is never read -- except
  *  for a new MAIN topic, whose roots are other roots: the tree
- *  opens again at `expand_depth`.
+ *  opens again at the reader's level, now counted from them.
  ************************************************************/
 function ac_set_hidden_topics(gobj, event, kw, src)
 {
@@ -10724,9 +10766,8 @@ function ac_set_main_topic(gobj, event, kw, src)
     let keep = fold_keep_node(gobj);
     let vp = yui_graph_viewport_of(priv.graph, keep);
     rebuild_fold_model(gobj);
-    fold_expand_to_depth(
-        priv._fold_model, priv._fold_state,
-        gobj_read_integer_attr(gobj, "expand_depth")
+    fold_expand_to_level(
+        priv._fold_model, priv._fold_state, current_fold_level(gobj)
     );
     reconcile_fold(gobj, {relayout: true, keep: keep, keep_vp: vp});
     return 0;
@@ -11404,8 +11445,7 @@ function create_gclass(gclass_name)
             ["EV_FIND_NODES",               ac_find_nodes,          null],
             ["EV_TOGGLE_FOLD",              ac_toggle_fold,         null],
             ["EV_SHOW_MORE",                ac_show_more,           null],
-            ["EV_EXPAND_ALL",               ac_expand_all,          null],
-            ["EV_COLLAPSE_ALL",             ac_collapse_all,        null],
+            ["EV_SET_FOLD_LEVEL",           ac_set_fold_level,      null],
             ["EV_SET_HIDDEN_TOPICS",        ac_set_hidden_topics,   null],
             ["EV_SET_MAIN_TOPIC",           ac_set_main_topic,      null],
             ["EV_SET_LOOSE_TOPICS",         ac_set_loose_topics,    null],
@@ -11472,8 +11512,7 @@ function create_gclass(gclass_name)
         ["EV_CAMERA_CHANGED",           event_flag_t.EVF_OUTPUT_EVENT|event_flag_t.EVF_NO_WARN_SUBS],
         ["EV_TOGGLE_FOLD",              0],
         ["EV_SHOW_MORE",                0],
-        ["EV_EXPAND_ALL",               0],
-        ["EV_COLLAPSE_ALL",             0],
+        ["EV_SET_FOLD_LEVEL",           0],
         ["EV_SET_HIDDEN_TOPICS",        0],
         ["EV_SET_MAIN_TOPIC",           0],
         ["EV_SET_LOOSE_TOPICS",         0],

package/src/c_yui_schema_editor.js

@@ -1061,6 +1061,13 @@ function render_topics(gobj, $body)
                     ? ["span", {class: "SCHEMA_TOPIC_SYSTEM tag ml-2",
                                 i18n: "system"}, t("system")]
                     : ["span", {}, ""],
+                /*  The schema's mark of the topic the tree hangs from: the
+                 *  same gold star the treedb graph's legend wears.  */
+                topic.main_topic
+                    ? ["span", {class: "SCHEMA_TOPIC_MAIN ml-2",
+                                style: "color:#d4a017;",
+                                title: t("main topic"), "data-i18n-title": "main topic"}, "★"]
+                    : ["span", {}, ""],
                 ambiguous
                     ? ["div", {class: "SCHEMA_TOPIC_ID is-size-7 yui-text-quiet"},
                         [["code", {}, `${topic.id}`]]]
@@ -1898,6 +1905,14 @@ function open_topic_form(gobj, treedb, topic)
                     ["span", {class: "ml-1", i18n: "system topic"}, t("system topic")]
                 ]]
             ]],
+            /*  A LABEL that wraps its control names it: no aria-label.  */
+            ["div", {class: "SCHEMA_TOPIC_FORM_MAIN field mb-3"}, [
+                ["label", {class: "checkbox"}, [
+                    ["input", el_attrs({type: "checkbox", "data-name": "main_topic",
+                               checked: record.main_topic ? "checked" : undefined})],
+                    ["span", {class: "ml-1", i18n: "main topic"}, t("main topic")]
+                ]]
+            ]],
             ["div", {class: "SCHEMA_TOPIC_FORM_ACTIONS is-flex mt-4",
                      style: "gap:.5rem; justify-content:flex-end;"}, [
                 ["button", {class: "SCHEMA_TOPIC_FORM_CANCEL button", type: "button"},
@@ -2501,6 +2516,7 @@ function topic_record(gobj, treedb, topic, values)
     record.tkey = values.tkey || "";
     record.topic_version = values.topic_version === "" ? 1 : Number(values.topic_version);
     record.system_topic = !!values.system_topic;
+    record.main_topic = !!values.main_topic;
 
     return record;
 }

package/src/c_yui_treedb_graph.js

@@ -82,7 +82,6 @@ import {
 
 import {attach_clear} from "./yui_inputs.js";
 import {register_c_g6_nodes_tree} from "./c_g6_nodes_tree.js";
-import {yui_graph_fold_items} from "./yui_graph_camera.js";
 import {yui_toolbar, yui_toolbar_icon, YUI_TOOLBAR_ICON_SIZE} from "./yui_toolbar.js";
 import {
     removeChildElements,
@@ -112,7 +111,7 @@ SDATA(data_type_t.DTP_LIST,     "operation_modes",  0,
 '["reading", "operation", "writing", "edition"]',
 "Available **permission** or behaviour modes. These operation modes are required to be accomplish by the graph handler (G6 child). TODO permissions must match treedb permissions."),
 SDATA(data_type_t.DTP_BOOLEAN,  "with_treedb_tables",0, false,  "Include treedb tables"),
-SDATA(data_type_t.DTP_INTEGER,  "expand_depth",     0,  2,      "Levels of the treedb open when it loads: 1 = the roots alone, 2 = the roots and their children. Forwarded to the G6 child"),
+SDATA(data_type_t.DTP_INTEGER,  "expand_depth",     0,  1,      "Levels of the treedb open when it loads, until the reader steps (`fold_level`): 1 = the roots alone (the default), 2 = the roots and their children. Forwarded to the G6 child"),
 SDATA(data_type_t.DTP_INTEGER,  "fold_page_size",   0,  24,     "Children of one hook shown per page in the graph; a `+N` chip opens the next page. Forwarded to the G6 child"),
 
 /*---------------- Forwarded to the G6 child (its own defaults) ----------------*/
@@ -137,6 +136,7 @@ SDATA(data_type_t.DTP_LIST,     "loose_topics",     sdata_flag_t.SDF_PERSIST, "[
 SDATA(data_type_t.DTP_STRING,   "node_mode",        sdata_flag_t.SDF_PERSIST, "expanded", "How the records are drawn: `expanded` = the cards with their pills and ports, `compact` = one-line pills with the name, `shape` = coloured figures, the topology alone. User preference"),
 SDATA(data_type_t.DTP_BOOLEAN,  "node_labels",      sdata_flag_t.SDF_PERSIST, true, "A `shape` node says its name under its figure. User preference"),
 SDATA(data_type_t.DTP_DICT,     "camera",           sdata_flag_t.SDF_PERSIST, "{}", "Where the reader left the viewport: {zoom, x, y}. Handed to the engine on creation and written back when a move settles, so the graph opens where it was left. User preference, per treedb"),
+SDATA(data_type_t.DTP_INTEGER,  "fold_level",       sdata_flag_t.SDF_PERSIST, 0, "The level of the MAIN tree the toolbar's stepper stands on: 1 = the main topic's roots, N = N-1 levels under them; 0 = never stepped, `expand_depth`. Handed to the engine on creation, so the graph opens at the level it was left. User preference, per treedb"),
 
 /*---------------- Remote Connection ----------------*/
 SDATA(data_type_t.DTP_POINTER,  "gobj_remote_yuno", 0,  null,   "Remote Yuno to request data"),
@@ -269,6 +269,7 @@ function mt_create(gobj)
             hook_port_position: "bottom",
             fkey_port_position: "top",
             expand_depth: gobj_read_integer_attr(gobj, "expand_depth"),
+            fold_level: gobj_read_integer_attr(gobj, "fold_level"),
             fold_page_size: gobj_read_integer_attr(gobj, "fold_page_size"),
             minimap_min_nodes: gobj_read_integer_attr(gobj, "minimap_min_nodes"),
             with_gridline: gobj_read_bool_attr(gobj, "with_gridline"),
@@ -671,6 +672,117 @@ function refresh_node_shape_buttons(gobj, $root)
     }
 }
 
+/************************************************************
+ *  The fold STEPPER: one level less, where the tree stands, one
+ *  level more.
+ *
+ *  It replaces the fold pair (7.23.141). `expand all` opened every
+ *  hook of the treedb -- the pile, on purpose, which on a treedb
+ *  of thousands is a pile nobody reads -- and `collapse all` threw
+ *  away everything the reader had opened. The stepper walks the
+ *  MAIN tree a level at a time, the way the frontend view opens
+ *  one level per press: `+` opens the next level under the main
+ *  topic's roots, through every topic that is not hidden; `-`
+ *  folds the deepest one. Pages and pills the reader opened stay.
+ *
+ *  The readout says what the two buttons act on, which no chevron
+ *  can: the main topic -- its swatch and its name, which is DATA
+ *  and never translated -- and `level/levels`. On a phone the name
+ *  goes and the numbers stay. The level is the reader's, per
+ *  treedb: persisted (`fold_level`) and handed to the engine on
+ *  creation, so a reload opens where it was left.
+ *
+ *  Both buttons are born disabled: nothing can be stepped until
+ *  the engine has said how deep the tree goes (EV_LEGEND_STATE).
+ ************************************************************/
+function fold_level_items(gobj, wide)
+{
+    let step_button = (cls, icon, key, event_name) => {
+        return ['button', {class: `${cls} button`, type: 'button',
+                           style: {height: wide, width: '2.5em'},
+                           disabled: true,
+                           title: t(key), 'data-i18n-title': key,
+                           'aria-label': t(key), 'data-i18n-aria-label': key},
+            yui_toolbar_icon(icon),
+            {
+                click: (evt) => {
+                    evt.stopPropagation();
+                    gobj_send_event(gobj, event_name, {}, gobj);
+                }
+            }
+        ];
+    };
+
+    return [
+        ['div', {class: 'GRAPH_FOLD_STEPPER buttons has-addons',
+                 style: 'margin:0; flex:0 0 auto; flex-wrap:nowrap; align-items:stretch;'}, [
+            /*  The same two chevrons the pills speak: `▸` folded, `▾` open.  */
+            step_button('GRAPH_FOLD_COLLAPSE', 'yi-chevron-right',
+                        'collapse one level', 'EV_COLLAPSE_LEVEL'),
+            /*  A `div` with the button skin, like the legend's main
+             *  chip: a readout between two buttons of one group, not
+             *  a third button, and at full strength -- `is-static`
+             *  is Bulma's grey of something switched off.  */
+            ['div', {class: 'GRAPH_FOLD_LEVEL button',
+                     style: {height: wide, cursor: 'default', gap: '.35rem'},
+                     role: 'status',
+                     title: t('fold level'), 'data-i18n-title': 'fold level'}, [
+                ['span', {class: 'GRAPH_FOLD_SWATCH',
+                          style: 'display:none; width:.8rem; height:.8rem; border-radius:3px; ' +
+                                 'flex:0 0 auto; border:1px solid rgba(0,0,0,.25);'}],
+                ['span', {class: 'GRAPH_FOLD_TOPIC is-hidden-mobile',
+                          style: 'max-width:10em; overflow:hidden; text-overflow:ellipsis; ' +
+                                 'white-space:nowrap; font-weight:600;'}],
+                /*  The WORD, not just the numbers: the legend chip under
+                 *  it says `departments 2/3` too, and there it means
+                 *  records on screen.  */
+                ['span', {class: 'GRAPH_FOLD_WORD', i18n: 'level'}, 'level'],
+                ['span', {class: 'GRAPH_FOLD_COUNT',
+                          style: 'font-variant-numeric:tabular-nums;'}, '–'],
+            ]],
+            step_button('GRAPH_FOLD_EXPAND', 'yi-chevron-down',
+                        'expand one level', 'EV_EXPAND_LEVEL'),
+        ]],
+    ];
+}
+
+/*  Paint the stepper from the engine's last word (EV_LEGEND_STATE).  */
+function refresh_fold_level(gobj)
+{
+    let priv = gobj.priv;
+    let $container = gobj_read_attr(gobj, "$container");
+    if(!$container) {
+        return;
+    }
+    let $readout = $container.querySelector('.GRAPH_FOLD_LEVEL');
+    if(!$readout) {
+        return;
+    }
+
+    let state = priv._legend_state || {};
+    let fold = state.fold || {};
+    let levels = (fold.levels > 0)? fold.levels : 0;
+    let level = (fold.level > 0)? fold.level : 0;
+    let topic = fold.topic || "";
+    let entry = (is_array(state.topics)? state.topics : []).find((e) => e.topic === topic);
+
+    let $swatch = $readout.querySelector('.GRAPH_FOLD_SWATCH');
+    $swatch.style.display = topic? 'inline-block' : 'none';
+    $swatch.style.background = (entry && entry.color) || '#94a3b8';
+    $readout.querySelector('.GRAPH_FOLD_TOPIC').textContent = topic;
+    $readout.querySelector('.GRAPH_FOLD_COUNT').textContent =
+        levels? `${level}/${levels}` : '–';
+
+    let $collapse = $container.querySelector('.GRAPH_FOLD_COLLAPSE');
+    let $expand = $container.querySelector('.GRAPH_FOLD_EXPAND');
+    if($collapse) {
+        $collapse.disabled = !(levels && level > 1);
+    }
+    if($expand) {
+        $expand.disabled = !(levels && level < levels);
+    }
+}
+
 function make_toolbar(gobj)
 {
     let priv = gobj.priv;
@@ -741,11 +853,9 @@ function make_toolbar(gobj)
      *  Center: how the graph is SHOWN.
      */
     let center_items = [
-        /*  The fold pair, the same two chevrons the JSON graph and the
-         *  lazy tree use: the graph opens folded (see the G6 child), and
-         *  these are the whole thing and the roots alone. Refresh is the
-         *  way back to the default depth.  */
-        ...yui_graph_fold_items(gobj, gobj_read_str_attr(gobj, "wide")),
+        /*  The fold stepper: one level less or more of the main tree,
+         *  and between the two, which tree and which level.  */
+        ...fold_level_items(gobj, gobj_read_str_attr(gobj, "wide")),
 
         /*  The view of the nodes -- full cards, one-line pills or
          *  figures -- and the name under a figure.  */
@@ -2589,6 +2699,11 @@ function refresh_legend(gobj)
         return String(a.topic).localeCompare(String(b.topic));
     });
 
+    /*  Only a topic hooked to ITSELF can be the main one, so only those
+     *  offer the star -- and only when there is more than one to pick
+     *  from: with a single hierarchical topic the choice is made.  */
+    let hierarchical_count = topics.filter((e) => e.hierarchical && !e.hidden).length;
+
     for(let entry of topics) {
         let topic_name = entry.topic;
         let is_main = (topic_name === state.main_topic);
@@ -2703,7 +2818,7 @@ function refresh_legend(gobj)
                                   style: 'padding:0 .5rem; cursor:default;',
                                   title: t('main topic'), 'data-i18n-title': 'main topic'},
                          [['span', {style: LEGEND_STAR_MAIN_STYLE}, '★']]]);
-        } else if(!hidden) {
+        } else if(!hidden && entry.hierarchical && hierarchical_count > 1) {
             extras.push(['button', {class: 'GRAPH_LEGEND_STAR button',
                                     type: 'button', style: 'padding:0 .5rem;',
                                     title: t('main topic'), 'data-i18n-title': 'main topic',
@@ -2795,6 +2910,7 @@ function ac_legend_state(gobj, event, kw, src)
     let priv = gobj.priv;
     priv._legend_state = kw || null;
     refresh_legend(gobj);
+    refresh_fold_level(gobj);
     return 0;
 }
 
@@ -2964,23 +3080,37 @@ function ac_find_nodes(gobj, event, kw, src)
 }
 
 /************************************************************
- *  The fold pair of the toolbar, forwarded to the G6 child,
- *  which owns the tree.
+ *  One press of the fold stepper (EV_EXPAND_LEVEL /
+ *  EV_COLLAPSE_LEVEL): the level moves by one, is SAVED (the
+ *  reader's, per treedb) and reaches the G6 child, which owns
+ *  the tree.
+ *
+ *  The readout moves at once, not when the engine speaks again:
+ *  a reconcile is asynchronous, and a second press that came
+ *  before it would step from the level already left -- two
+ *  presses, one level.
  ************************************************************/
-function ac_expand_all(gobj, event, kw, src)
+function ac_fold_level_step(gobj, event, kw, src)
 {
     let priv = gobj.priv;
-    if(priv.gobj_nodes_tree) {
-        gobj_send_event(priv.gobj_nodes_tree, "EV_EXPAND_ALL", {}, gobj);
+    let fold = priv._legend_state && priv._legend_state.fold;
+
+    if(!fold || !(fold.levels > 0)) {
+        log_error(`${gobj_short_name(gobj)}: ${event} with no tree to step through`);
+        return -1;
+    }
+    let level = fold.level + ((event === "EV_EXPAND_LEVEL")? 1 : -1);
+    if(level < 1 || level > fold.levels) {
+        log_error(`${gobj_short_name(gobj)}: ${event}: level ${level} out of 1..${fold.levels}`);
+        return -1;
     }
-    return 0;
-}
 
-function ac_collapse_all(gobj, event, kw, src)
-{
-    let priv = gobj.priv;
+    gobj_write_attr(gobj, "fold_level", level);
+    gobj_save_persistent_attrs(gobj, "fold_level");
+    fold.level = level;
+    refresh_fold_level(gobj);
     if(priv.gobj_nodes_tree) {
-        gobj_send_event(priv.gobj_nodes_tree, "EV_COLLAPSE_ALL", {}, gobj);
+        gobj_send_event(priv.gobj_nodes_tree, "EV_SET_FOLD_LEVEL", {level: level}, gobj);
     }
     return 0;
 }
@@ -3181,8 +3311,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_EXPAND_ALL",               ac_expand_all,              null],
-            ["EV_COLLAPSE_ALL",             ac_collapse_all,            null],
+            ["EV_EXPAND_LEVEL",             ac_fold_level_step,         null],
+            ["EV_COLLAPSE_LEVEL",           ac_fold_level_step,         null],
             ["EV_SET_NODE_MODE",            ac_set_node_mode,           null],
             ["EV_TOGGLE_NODE_LABELS",       ac_toggle_node_labels,      null],
             ["EV_LAYOUT_AUTOSET",           ac_layout_autoset,          null],
@@ -3226,8 +3356,8 @@ function create_gclass(gclass_name)
         ["EV_SET_OPERATION_MODE",       0],
         ["EV_SET_FOCUS_TOPIC",          0],
         ["EV_FIND_NODES",               0],
-        ["EV_EXPAND_ALL",               0],
-        ["EV_COLLAPSE_ALL",             0],
+        ["EV_EXPAND_LEVEL",             0],
+        ["EV_COLLAPSE_LEVEL",           0],
         ["EV_SET_NODE_MODE",            0],
         ["EV_TOGGLE_NODE_LABELS",       0],
         ["EV_FIND_RESULT",              0],

package/src/schema_import.js

@@ -38,7 +38,8 @@ import {
  *  the fkey, `order`) is composed, and `_geometry` belongs to whoever
  *  laid the graph out — an import must not move their boxes.  */
 const TOPIC_FIELDS = [
-    "pkey", "pkey2s", "system_flag", "tkey", "topic_version", "system_topic"
+    "pkey", "pkey2s", "system_flag", "tkey", "topic_version", "system_topic",
+    "main_topic"
 ];
 
 /*  Same for a `cols` record.  */