@yuneta/gobj-ui 7.23.140 → 7.23.141

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,10 @@ 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_toggle,
     fold_show_more,
     fold_reveal,
@@ -434,7 +436,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,  2,      "Levels open when a treedb loads, until the reader steps (`fold_level`): 1 = the roots alone, 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"),
@@ -543,6 +546,7 @@ let PRIVATE_DATA = {
 
     /*---------------- folding ----------------*/
     expand_depth:       2,
+    fold_level:         0,
     fold_page_size:     24,
     hidden_topics:      null,
     main_topic:         "",
@@ -9541,6 +9545,13 @@ function publish_legend_state(gobj, visible)
         main_topic: model.main_topic,
         main_chosen: !!gobj_read_str_attr(gobj, "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 +10014,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 +10632,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 +10720,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 +10756,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 +11435,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 +11502,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_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,
@@ -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.  */
@@ -2795,6 +2905,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 +3075,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 +3306,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 +3351,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/treedb_fold_model.js

@@ -281,7 +281,7 @@ export function fold_build_model(descs, records, opts)
         }
     }
 
-    return {
+    let model = {
         nodes: nodes,
         groups: groups,
         topics: topics,
@@ -291,7 +291,67 @@ export function fold_build_model(descs, records, opts)
         linked: linked,         /*  Set of topics the schema hangs from main  */
         loose: loose,           /*  {topic: [key, ...]} records that should hang and do not  */
         loose_shown: loose_shown,
+        level_of: null,         /*  Map<node_key, level> of the MAIN tree, see below  */
+        levels: 0,              /*  its deepest level (0 = no tree to step through)  */
     };
+    count_levels(model);
+    return model;
+}
+
+/************************************************************
+ *  The LEVELS of the main tree: the roots of the main topic --
+ *  and of the topics hung from it, whose roots are the loose
+ *  records the reader asked for -- are level 1, their children
+ *  level 2, and so on down every hook of every topic that is not
+ *  hidden. A node reached by two paths takes the shallowest.
+ *
+ *  With no main topic every topic is a tree of its own and all
+ *  of them count. A topic the schema does not tie to the main
+ *  one is a separate tree, and has no level: the stepper of the
+ *  toolbar speaks for the main tree and nothing else, those
+ *  trees are opened by their own pills.
+ ************************************************************/
+function count_levels(model)
+{
+    let level_of = new Map();
+    let queue = [];
+    let deepest = 0;
+
+    for(let topic_name of model.topics) {
+        if(model.main_topic && !model.linked.has(topic_name)) {
+            continue;
+        }
+        let roots = model.groups.get(fold_root_group_key(topic_name)) || [];
+        for(let key of roots) {
+            if(!level_of.has(key)) {
+                level_of.set(key, 1);
+                queue.push(key);
+            }
+        }
+    }
+    let head = 0;
+    while(head < queue.length) {
+        let key = queue[head++];
+        let lv = level_of.get(key);
+        if(lv > deepest) {
+            deepest = lv;
+        }
+        let node = model.nodes.get(key);
+        if(!node) {
+            continue;
+        }
+        for(let hook of Object.keys(node.hooks)) {
+            for(let child of node.hooks[hook]) {
+                if(!level_of.has(child)) {
+                    level_of.set(child, lv + 1);
+                    queue.push(child);
+                }
+            }
+        }
+    }
+
+    model.level_of = level_of;
+    model.levels = deepest;
 }
 
 /************************************************************
@@ -565,6 +625,78 @@ export function fold_expand_to_depth(model, state, depth)
     }
 }
 
+/************************************************************
+ *  The toolbar's STEPPER over the levels of the main tree (see
+ *  count_levels): level N shows the roots and N-1 levels under
+ *  them. A level is a floor of what is open, not a picture that
+ *  replaces it:
+ *
+ *      opening to N   opens, on its first page, every hook of
+ *                     every node above level N that is folded;
+ *                     what the reader opened, and every page
+ *                     already shown, stays
+ *      closing to N   folds every hook of every node at level N
+ *                     or below, and touches nothing above it
+ *
+ *  A separate tree (a topic not tied to the main one) has no
+ *  level, so neither ever touches it.
+ ************************************************************/
+export function fold_level_clamp(model, level)
+{
+    let top = (model.levels > 0)? model.levels : 1;
+    level = Math.floor(Number(level)) || 1;
+    if(level < 1) {
+        return 1;
+    }
+    if(level > top) {
+        return top;
+    }
+    return level;
+}
+
+export function fold_open_levels(model, state, level)
+{
+    for(let [key, lv] of model.level_of) {
+        if(lv >= level) {
+            continue;
+        }
+        let node = model.nodes.get(key);
+        if(!node) {
+            continue;
+        }
+        for(let hook of Object.keys(node.hooks)) {
+            let group_key = fold_group_key(key, hook);
+            if(node.hooks[hook].length > 0 && !fold_is_open(state, group_key)) {
+                state.shown.set(group_key, state.page_size);
+            }
+        }
+    }
+}
+
+export function fold_close_levels(model, state, level)
+{
+    for(let [key, lv] of model.level_of) {
+        if(lv < level) {
+            continue;
+        }
+        let node = model.nodes.get(key);
+        if(!node) {
+            continue;
+        }
+        for(let hook of Object.keys(node.hooks)) {
+            state.shown.delete(fold_group_key(key, hook));
+        }
+    }
+}
+
+/*  From scratch: the roots of every tree on their first page, and
+ *  the main tree open down to `level`. What a load opens.  */
+export function fold_expand_to_level(model, state, level)
+{
+    fold_collapse_all(model, state);
+    fold_open_levels(model, state, fold_level_clamp(model, level));
+}
+
 /************************************************************
  *  The set of node keys on screen, from the roots down through
  *  every open group -- and only through open groups whose parent