@yuneta/gobj-ui 7.22.0 → 7.23.0

package/README.md

@@ -444,7 +444,16 @@ same two facilities the tree has: a **find box** (rate-limited, `EV_FIND_NODES`)
 that highlights matching rows and outlines the cards they are in and says how
 many matched, and **expand-all / collapse-all** (`EV_EXPAND_ALL` /
 `EV_COLLAPSE_ALL`) that fold every card but the root, marking each cut with
-`▸ N` so the shape stays legible and you can see where the rest went. A find
+`▸ N` so the shape stays legible and you can see where the rest went. Since
+`7.23.0` each card that HAS a branch also carries its own handle in its header
+(`▾` open, `▸ N` folded, `EV_TOGGLE_FOLD {path}`); a leaf gets a spacer instead,
+because a handle that does nothing is worse than none.
+
+The handle is delegated from the canvas mount in the **capture** phase, over
+`pointerdown`/`pointerup`/`mousedown`/`click`: the card is an `innerHTML`
+string so nothing can be bound to it directly, G6 binds on the node element
+below, and G6 builds its click from the POINTER sequence — swallowing `click`
+alone leaves the fold working and the card also reporting an item click. A find
 does not move the camera — a viewport that jumps on every keystroke is
 unusable — which is why the count is there.
 
@@ -491,11 +500,13 @@ Two layout facts the browser taught this component, both worth keeping:
   `"text"` / `"graph"`; **no mode advances** to the next view, which is what
   the two-view toggle did when the list was two long), plus `EV_REFRESH` /
   `EV_SHOW` / `EV_HIDE` / `EV_LANGUAGE_CHANGED`.
-- Output events: `EV_EXPAND_PATH {path, size}` (`EVF_OUTPUT_EVENT`) — the parent
-  must declare it in its own FSM (CHILD subscription model) — and
-  `EV_JSON_ITEM_CLICKED`, republished from the graph child so the host has one
-  contract and never has to know that child exists (`EVF_NO_WARN_SUBS`: most
-  hosts do not care).
+- Output event: `EV_EXPAND_PATH {path, size}` (`EVF_OUTPUT_EVENT`) — the parent
+  must declare it in its own FSM (CHILD subscription model). That is the ONLY
+  one, on purpose: this viewer is a child of its host and subscribes it to
+  everything it publishes, so every output event is a mandatory declaration in
+  every host's FSM. The graph child's `EV_JSON_ITEM_CLICKED` stops here
+  (`7.21.0` forwarded it and broke exactly that way); a host that wants node
+  clicks mounts `C_YUI_JSON_GRAPH` itself.
 - Internal (DOM → FSM): `EV_TOGGLE_NODE`, `EV_EXPAND_COLLAPSED`, `EV_SEARCH`,
   `EV_EXPAND_ALL`, `EV_COLLAPSE_ALL`, `EV_COPY_ALL`. Every kw carries only a
   `path` string — never a DOM node or gobj.

package/dist/gobj-ui.cjs.js

@@ -9473,6 +9473,12 @@ function ensure_drag_canvas_patch() {
 *              Constants
 ***************************************************************/
 var GCLASS_NAME$11 = "C_YUI_JSON_GRAPH";
+var FOLD_SWALLOWED_EVENTS = [
+	"pointerdown",
+	"pointerup",
+	"mousedown",
+	"click"
+];
 /***************************************************************
 *              Data
 ***************************************************************/
@@ -9497,6 +9503,7 @@ var PRIVATE_DATA$11 = {
 	collapsed: null,
 	match_count: 0,
 	find_timer: null,
+	fold_listener: null,
 	$find_input: null,
 	$find_result: null,
 	$find_count: null
@@ -9659,6 +9666,18 @@ function build_ui$10(gobj) {
 		]]
 	]);
 	(0, _yuneta_gobj_js.gobj_write_attr)(gobj, "$container", $container);
+	let $mount = $container.querySelector("#" + priv.canvas_id);
+	if ($mount) {
+		priv.fold_listener = function(evt) {
+			let $handle = evt.target && evt.target.closest ? evt.target.closest("[data-fold-path]") : null;
+			if (!$handle) return;
+			evt.stopPropagation();
+			evt.preventDefault();
+			if (evt.type !== "click") return;
+			(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_TOGGLE_FOLD", { path: $handle.getAttribute("data-fold-path") }, gobj);
+		};
+		for (let type of FOLD_SWALLOWED_EVENTS) $mount.addEventListener(type, priv.fold_listener, true);
+	} else (0, _yuneta_gobj_js.log_error)(`${(0, _yuneta_gobj_js.gobj_short_name)(gobj)}: no canvas mount, fold handles are dead`);
 	priv.$find_input = $container.querySelector(".JSON_GRAPH_FIND_INPUT");
 	priv.$find_result = $container.querySelector(".JSON_GRAPH_FIND_RESULT");
 	priv.$find_count = $container.querySelector(".JSON_GRAPH_FIND_COUNT");
@@ -9668,7 +9687,13 @@ function build_ui$10(gobj) {
 *   Destroy UI
 ************************************************************/
 function destroy_ui$6(gobj) {
+	let priv = gobj.priv;
 	let $container = (0, _yuneta_gobj_js.gobj_read_attr)(gobj, "$container");
+	if (priv.fold_listener) {
+		let $mount = $container ? $container.querySelector("#" + priv.canvas_id) : null;
+		if ($mount) for (let type of FOLD_SWALLOWED_EVENTS) $mount.removeEventListener(type, priv.fold_listener, true);
+		priv.fold_listener = null;
+	}
 	if ($container) {
 		if ($container.parentNode) $container.parentNode.removeChild($container);
 		(0, _yuneta_gobj_js.gobj_write_attr)(gobj, "$container", null);
@@ -9906,6 +9931,26 @@ function build_cell_html(key, value, type, dark, matched) {
 	return row;
 }
 /************************************************************
+*  The per-node fold handle, drawn in the card's header.
+*
+*  Only a card with a BRANCH gets one — a leaf has nothing to
+*  fold, and a handle that does nothing is worse than none.
+*  It carries the path in `data-fold-path`, which is what the
+*  delegated listener in build_ui reads; the card is an
+*  innerHTML string, so there is no other way to hang a
+*  handler on it.
+*
+*  Folded it shows the glyph AND the count of branches hidden
+*  under it; open, just the glyph.  No word, no title: a word
+*  inside this string could carry no i18n key.
+************************************************************/
+function fold_toggle_html(path, foldable, folded, branches) {
+	if (!foldable) return `<span style="width:1.1em; flex:0 0 auto;"></span>`;
+	let glyph = folded ? "&#9656;" : "&#9662;";
+	let text = folded ? `${glyph} ${branches}` : glyph;
+	return `<span data-fold-path="${(0, _yuneta_gobj_js.escapeHtml)(path)}" style="flex:0 0 auto; cursor:pointer; user-select:none; padding:0 .2em; min-width:1.1em; text-align:left;">${text}</span>`;
+}
+/************************************************************
 *  Does this key/value pair match the find term?
 *
 *  Scalars are matched on what the card SHOWS.  A complex value
@@ -9990,8 +10035,8 @@ function build_json_nodes(gobj, path, kw, nodes, edges, parent_id) {
 		});
 	}
 	let label = get_group_label(path) || (is_dict ? "{}" : "[]");
-	let folded = priv.collapsed.has(path) && pending_complex.length > 0;
-	if (folded) lines.push(`<span style="color:${type_color("number", dark)}; font-weight:bold;">&#9656; ${pending_complex.length}</span>`);
+	let foldable = pending_complex.length > 0;
+	let folded = foldable && priv.collapsed.has(path);
 	let colors = json_card_style(is_dict ? GROUP_COLORS.dict : GROUP_COLORS.list, dark);
 	let border_color = card_matched ? dark ? "#ffb300" : "#ff8f00" : colors.border;
 	let border_width = card_matched ? 2 : 1;
@@ -10012,8 +10057,10 @@ function build_json_nodes(gobj, path, kw, nodes, edges, parent_id) {
         font-weight: bold;
         font-size: 12px;
         padding: 3px 8px;
-        text-align: center;
-    ">${(0, _yuneta_gobj_js.escapeHtml)(label)}</div>
+        display: flex;
+        align-items: center;
+        gap: 6px;
+    ">${fold_toggle_html(path, foldable, folded, pending_complex.length)}<span style="flex:1 1 auto; text-align:center;">${(0, _yuneta_gobj_js.escapeHtml)(label)}</span></div>
     ${content_html}
 </div>`;
 	let node = {
@@ -10230,6 +10277,27 @@ function ac_refresh$5(gobj, event, kw, src) {
 }
 /************************************************************
 *  {theme: "dark"|"light"} — the app switched theme.
+*  EV_TOGGLE_FOLD { path } — fold or unfold ONE card.
+*
+*  The camera does not move: folding one branch is a local
+*  edit of the picture, and refitting the whole graph for it
+*  would throw away where the reader was looking.  The toolbar
+*  pair, which changes everything at once, does refit.
+************************************************************/
+function ac_toggle_fold(gobj, event, kw, src) {
+	let priv = gobj.priv;
+	let path = kw && kw.path || "";
+	if ((0, _yuneta_gobj_js.empty_string)(path)) {
+		(0, _yuneta_gobj_js.log_error)(`${(0, _yuneta_gobj_js.gobj_short_name)(gobj)}: EV_TOGGLE_FOLD with no path`);
+		return -1;
+	}
+	if (priv.collapsed.has(path)) priv.collapsed.delete(path);
+	else priv.collapsed.add(path);
+	refresh_json(gobj, { preserve_view: true });
+	update_find_result(gobj);
+	return 0;
+}
+/************************************************************
 *  EV_FIND_NODES { text }
 *
 *  The camera does NOT move: a find is a way of reading what is
@@ -10418,6 +10486,11 @@ function create_gclass$11(gclass_name) {
 			ac_find_nodes$2,
 			null
 		],
+		[
+			"EV_TOGGLE_FOLD",
+			ac_toggle_fold,
+			null
+		],
 		[
 			"EV_EXPAND_ALL",
 			ac_expand_all$2,
@@ -10478,6 +10551,7 @@ function create_gclass$11(gclass_name) {
 		["EV_LOAD_DATA", 0],
 		["EV_REFRESH", 0],
 		["EV_FIND_NODES", 0],
+		["EV_TOGGLE_FOLD", 0],
 		["EV_EXPAND_ALL", 0],
 		["EV_COLLAPSE_ALL", 0],
 		["EV_THEME", 0],
@@ -11681,11 +11755,20 @@ function ac_set_view_mode(gobj, event, kw, src) {
 /************************************************************
 *   EV_JSON_ITEM_CLICKED — from the hosted graph child.
 *
-*   Republished under this gclass's own name so the host has ONE
-*   contract and never has to know the child exists.
+*   It STOPS here, and that is deliberate.  7.21.0 republished
+*   it "so the host has one contract", which got the framework
+*   backwards: this viewer is a CHILD of its host and subscribes
+*   it to everything it publishes, so a new output event is a
+*   new MANDATORY declaration in every host's FSM.  None of the
+*   six that mount this viewer asked for node clicks, and every
+*   one of them answered a click on a graph card with
+*   "Event NOT DEFINED in state".
+*
+*   A host that wants node clicks mounts C_YUI_JSON_GRAPH
+*   itself — that gclass publishes them, and a host that mounts
+*   it has declared them.
 ************************************************************/
 function ac_json_item_clicked(gobj, event, kw, src) {
-	(0, _yuneta_gobj_js.gobj_publish_event)(gobj, "EV_JSON_ITEM_CLICKED", kw);
 	return 0;
 }
 /************************************************************
@@ -11858,7 +11941,7 @@ function create_gclass$10(gclass_name) {
 		["EV_COLLAPSE_ALL", 0],
 		["EV_COPY_ALL", 0],
 		["EV_SET_VIEW_MODE", 0],
-		["EV_JSON_ITEM_CLICKED", _yuneta_gobj_js.event_flag_t.EVF_OUTPUT_EVENT | _yuneta_gobj_js.event_flag_t.EVF_NO_WARN_SUBS],
+		["EV_JSON_ITEM_CLICKED", 0],
 		["EV_LANGUAGE_CHANGED", 0],
 		["EV_REFRESH", 0],
 		["EV_SHOW", 0],

package/dist/gobj-ui.es.js

@@ -9468,6 +9468,12 @@ function ensure_drag_canvas_patch() {
 *              Constants
 ***************************************************************/
 var GCLASS_NAME$11 = "C_YUI_JSON_GRAPH";
+var FOLD_SWALLOWED_EVENTS = [
+	"pointerdown",
+	"pointerup",
+	"mousedown",
+	"click"
+];
 /***************************************************************
 *              Data
 ***************************************************************/
@@ -9492,6 +9498,7 @@ var PRIVATE_DATA$11 = {
 	collapsed: null,
 	match_count: 0,
 	find_timer: null,
+	fold_listener: null,
 	$find_input: null,
 	$find_result: null,
 	$find_count: null
@@ -9654,6 +9661,18 @@ function build_ui$10(gobj) {
 		]]
 	]);
 	gobj_write_attr(gobj, "$container", $container);
+	let $mount = $container.querySelector("#" + priv.canvas_id);
+	if ($mount) {
+		priv.fold_listener = function(evt) {
+			let $handle = evt.target && evt.target.closest ? evt.target.closest("[data-fold-path]") : null;
+			if (!$handle) return;
+			evt.stopPropagation();
+			evt.preventDefault();
+			if (evt.type !== "click") return;
+			gobj_send_event(gobj, "EV_TOGGLE_FOLD", { path: $handle.getAttribute("data-fold-path") }, gobj);
+		};
+		for (let type of FOLD_SWALLOWED_EVENTS) $mount.addEventListener(type, priv.fold_listener, true);
+	} else log_error(`${gobj_short_name(gobj)}: no canvas mount, fold handles are dead`);
 	priv.$find_input = $container.querySelector(".JSON_GRAPH_FIND_INPUT");
 	priv.$find_result = $container.querySelector(".JSON_GRAPH_FIND_RESULT");
 	priv.$find_count = $container.querySelector(".JSON_GRAPH_FIND_COUNT");
@@ -9663,7 +9682,13 @@ function build_ui$10(gobj) {
 *   Destroy UI
 ************************************************************/
 function destroy_ui$6(gobj) {
+	let priv = gobj.priv;
 	let $container = gobj_read_attr(gobj, "$container");
+	if (priv.fold_listener) {
+		let $mount = $container ? $container.querySelector("#" + priv.canvas_id) : null;
+		if ($mount) for (let type of FOLD_SWALLOWED_EVENTS) $mount.removeEventListener(type, priv.fold_listener, true);
+		priv.fold_listener = null;
+	}
 	if ($container) {
 		if ($container.parentNode) $container.parentNode.removeChild($container);
 		gobj_write_attr(gobj, "$container", null);
@@ -9901,6 +9926,26 @@ function build_cell_html(key, value, type, dark, matched) {
 	return row;
 }
 /************************************************************
+*  The per-node fold handle, drawn in the card's header.
+*
+*  Only a card with a BRANCH gets one — a leaf has nothing to
+*  fold, and a handle that does nothing is worse than none.
+*  It carries the path in `data-fold-path`, which is what the
+*  delegated listener in build_ui reads; the card is an
+*  innerHTML string, so there is no other way to hang a
+*  handler on it.
+*
+*  Folded it shows the glyph AND the count of branches hidden
+*  under it; open, just the glyph.  No word, no title: a word
+*  inside this string could carry no i18n key.
+************************************************************/
+function fold_toggle_html(path, foldable, folded, branches) {
+	if (!foldable) return `<span style="width:1.1em; flex:0 0 auto;"></span>`;
+	let glyph = folded ? "&#9656;" : "&#9662;";
+	let text = folded ? `${glyph} ${branches}` : glyph;
+	return `<span data-fold-path="${escapeHtml(path)}" style="flex:0 0 auto; cursor:pointer; user-select:none; padding:0 .2em; min-width:1.1em; text-align:left;">${text}</span>`;
+}
+/************************************************************
 *  Does this key/value pair match the find term?
 *
 *  Scalars are matched on what the card SHOWS.  A complex value
@@ -9985,8 +10030,8 @@ function build_json_nodes(gobj, path, kw, nodes, edges, parent_id) {
 		});
 	}
 	let label = get_group_label(path) || (is_dict ? "{}" : "[]");
-	let folded = priv.collapsed.has(path) && pending_complex.length > 0;
-	if (folded) lines.push(`<span style="color:${type_color("number", dark)}; font-weight:bold;">&#9656; ${pending_complex.length}</span>`);
+	let foldable = pending_complex.length > 0;
+	let folded = foldable && priv.collapsed.has(path);
 	let colors = json_card_style(is_dict ? GROUP_COLORS.dict : GROUP_COLORS.list, dark);
 	let border_color = card_matched ? dark ? "#ffb300" : "#ff8f00" : colors.border;
 	let border_width = card_matched ? 2 : 1;
@@ -10007,8 +10052,10 @@ function build_json_nodes(gobj, path, kw, nodes, edges, parent_id) {
         font-weight: bold;
         font-size: 12px;
         padding: 3px 8px;
-        text-align: center;
-    ">${escapeHtml(label)}</div>
+        display: flex;
+        align-items: center;
+        gap: 6px;
+    ">${fold_toggle_html(path, foldable, folded, pending_complex.length)}<span style="flex:1 1 auto; text-align:center;">${escapeHtml(label)}</span></div>
     ${content_html}
 </div>`;
 	let node = {
@@ -10225,6 +10272,27 @@ function ac_refresh$5(gobj, event, kw, src) {
 }
 /************************************************************
 *  {theme: "dark"|"light"} — the app switched theme.
+*  EV_TOGGLE_FOLD { path } — fold or unfold ONE card.
+*
+*  The camera does not move: folding one branch is a local
+*  edit of the picture, and refitting the whole graph for it
+*  would throw away where the reader was looking.  The toolbar
+*  pair, which changes everything at once, does refit.
+************************************************************/
+function ac_toggle_fold(gobj, event, kw, src) {
+	let priv = gobj.priv;
+	let path = kw && kw.path || "";
+	if (empty_string(path)) {
+		log_error(`${gobj_short_name(gobj)}: EV_TOGGLE_FOLD with no path`);
+		return -1;
+	}
+	if (priv.collapsed.has(path)) priv.collapsed.delete(path);
+	else priv.collapsed.add(path);
+	refresh_json(gobj, { preserve_view: true });
+	update_find_result(gobj);
+	return 0;
+}
+/************************************************************
 *  EV_FIND_NODES { text }
 *
 *  The camera does NOT move: a find is a way of reading what is
@@ -10413,6 +10481,11 @@ function create_gclass$11(gclass_name) {
 			ac_find_nodes$2,
 			null
 		],
+		[
+			"EV_TOGGLE_FOLD",
+			ac_toggle_fold,
+			null
+		],
 		[
 			"EV_EXPAND_ALL",
 			ac_expand_all$2,
@@ -10473,6 +10546,7 @@ function create_gclass$11(gclass_name) {
 		["EV_LOAD_DATA", 0],
 		["EV_REFRESH", 0],
 		["EV_FIND_NODES", 0],
+		["EV_TOGGLE_FOLD", 0],
 		["EV_EXPAND_ALL", 0],
 		["EV_COLLAPSE_ALL", 0],
 		["EV_THEME", 0],
@@ -11676,11 +11750,20 @@ function ac_set_view_mode(gobj, event, kw, src) {
 /************************************************************
 *   EV_JSON_ITEM_CLICKED — from the hosted graph child.
 *
-*   Republished under this gclass's own name so the host has ONE
-*   contract and never has to know the child exists.
+*   It STOPS here, and that is deliberate.  7.21.0 republished
+*   it "so the host has one contract", which got the framework
+*   backwards: this viewer is a CHILD of its host and subscribes
+*   it to everything it publishes, so a new output event is a
+*   new MANDATORY declaration in every host's FSM.  None of the
+*   six that mount this viewer asked for node clicks, and every
+*   one of them answered a click on a graph card with
+*   "Event NOT DEFINED in state".
+*
+*   A host that wants node clicks mounts C_YUI_JSON_GRAPH
+*   itself — that gclass publishes them, and a host that mounts
+*   it has declared them.
 ************************************************************/
 function ac_json_item_clicked(gobj, event, kw, src) {
-	gobj_publish_event(gobj, "EV_JSON_ITEM_CLICKED", kw);
 	return 0;
 }
 /************************************************************
@@ -11853,7 +11936,7 @@ function create_gclass$10(gclass_name) {
 		["EV_COLLAPSE_ALL", 0],
 		["EV_COPY_ALL", 0],
 		["EV_SET_VIEW_MODE", 0],
-		["EV_JSON_ITEM_CLICKED", event_flag_t.EVF_OUTPUT_EVENT | event_flag_t.EVF_NO_WARN_SUBS],
+		["EV_JSON_ITEM_CLICKED", 0],
 		["EV_LANGUAGE_CHANGED", 0],
 		["EV_REFRESH", 0],
 		["EV_SHOW", 0],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuneta/gobj-ui",
-  "version": "7.22.0",
+  "version": "7.23.0",
   "type": "module",
   "main": "dist/gobj-ui.cjs.js",
   "module": "dist/gobj-ui.es.js",

package/src/c_yui_json.js

@@ -1175,12 +1175,21 @@ function ac_set_view_mode(gobj, event, kw, src)
 /************************************************************
  *   EV_JSON_ITEM_CLICKED — from the hosted graph child.
  *
- *   Republished under this gclass's own name so the host has ONE
- *   contract and never has to know the child exists.
+ *   It STOPS here, and that is deliberate.  7.21.0 republished
+ *   it "so the host has one contract", which got the framework
+ *   backwards: this viewer is a CHILD of its host and subscribes
+ *   it to everything it publishes, so a new output event is a
+ *   new MANDATORY declaration in every host's FSM.  None of the
+ *   six that mount this viewer asked for node clicks, and every
+ *   one of them answered a click on a graph card with
+ *   "Event NOT DEFINED in state".
+ *
+ *   A host that wants node clicks mounts C_YUI_JSON_GRAPH
+ *   itself — that gclass publishes them, and a host that mounts
+ *   it has declared them.
  ************************************************************/
 function ac_json_item_clicked(gobj, event, kw, src)
 {
-    gobj_publish_event(gobj, "EV_JSON_ITEM_CLICKED", kw);
     return 0;
 }
 
@@ -1307,7 +1316,7 @@ function create_gclass(gclass_name)
         ["EV_COLLAPSE_ALL",     0],
         ["EV_COPY_ALL",         0],
         ["EV_SET_VIEW_MODE",    0],
-        ["EV_JSON_ITEM_CLICKED", event_flag_t.EVF_OUTPUT_EVENT|event_flag_t.EVF_NO_WARN_SUBS],
+        ["EV_JSON_ITEM_CLICKED", 0],
         ["EV_LANGUAGE_CHANGED", 0],
         ["EV_REFRESH",          0],
         ["EV_SHOW",             0],

package/src/c_yui_json_graph.js

@@ -67,6 +67,13 @@ import { yui_is_dark, yui_theme_now, yui_watch_theme } from "./yui_theme.js";
  ***************************************************************/
 const GCLASS_NAME = "C_YUI_JSON_GRAPH";
 
+/*
+ *  What a click on a fold handle has to swallow so G6 never turns it
+ *  into a node click.  `click` is the one that ACTS; the rest are cut
+ *  because G6 assembles its own click from the pointer sequence.
+ */
+const FOLD_SWALLOWED_EVENTS = ["pointerdown", "pointerup", "mousedown", "click"];
+
 /***************************************************************
  *              Data
  ***************************************************************/
@@ -102,6 +109,7 @@ let PRIVATE_DATA = {
     collapsed:      null,   // Set<string> of paths whose children are hidden
     match_count:    0,      // matches of the last find, for the count chip
     find_timer:     null,   // rate-limits the find box
+    fold_listener:  null,   // delegated click on the card fold handles
     $find_input:    null,
     $find_result:   null,
     $find_count:    null,
@@ -303,6 +311,46 @@ function build_ui(gobj)
 
     gobj_write_attr(gobj, "$container", $container);
 
+    /*
+     *  The fold handles live inside an `innerHTML` string, so no handler
+     *  can be attached to them: the click is delegated from the canvas
+     *  mount, in the CAPTURE phase, over FOUR event types.
+     *
+     *  Capture because G6 binds on the html node ELEMENT, a descendant
+     *  of this one: in the bubble phase G6 has already run by the time
+     *  this listener sees the event, so stopping it there stops nothing.
+     *
+     *  Four types because G6 does not use the DOM `click` at all — it
+     *  builds its own from the POINTER sequence.  Swallowing `click`
+     *  alone left the fold working and the card ALSO reporting an item
+     *  click; `pointerdown`/`pointerup` are the pair that has to be cut,
+     *  and `mousedown` goes with them for a browser that still sends it.
+     *  Measured by instrumenting the mount, not guessed.
+     */
+    let $mount = $container.querySelector('#' + priv.canvas_id);
+    if($mount) {
+        priv.fold_listener = function(evt) {
+            let $handle = evt.target && evt.target.closest
+                ? evt.target.closest('[data-fold-path]')
+                : null;
+            if(!$handle) {
+                return;
+            }
+            evt.stopPropagation();
+            evt.preventDefault();
+            if(evt.type !== "click") {
+                return;     /*  swallowed so G6 never sees a node click  */
+            }
+            gobj_send_event(gobj, "EV_TOGGLE_FOLD",
+                {path: $handle.getAttribute('data-fold-path')}, gobj);
+        };
+        for(let type of FOLD_SWALLOWED_EVENTS) {
+            $mount.addEventListener(type, priv.fold_listener, true);
+        }
+    } else {
+        log_error(`${gobj_short_name(gobj)}: no canvas mount, fold handles are dead`);
+    }
+
     priv.$find_input = $container.querySelector('.JSON_GRAPH_FIND_INPUT');
     priv.$find_result = $container.querySelector('.JSON_GRAPH_FIND_RESULT');
     priv.$find_count = $container.querySelector('.JSON_GRAPH_FIND_COUNT');
@@ -315,7 +363,19 @@ function build_ui(gobj)
  ************************************************************/
 function destroy_ui(gobj)
 {
+    let priv = gobj.priv;
     let $container = gobj_read_attr(gobj, "$container");
+
+    if(priv.fold_listener) {
+        let $mount = $container? $container.querySelector('#' + priv.canvas_id): null;
+        if($mount) {
+            for(let type of FOLD_SWALLOWED_EVENTS) {
+                $mount.removeEventListener(type, priv.fold_listener, true);
+            }
+        }
+        priv.fold_listener = null;
+    }
+
     if($container) {
         if($container.parentNode) {
             $container.parentNode.removeChild($container);
@@ -598,6 +658,36 @@ function build_cell_html(key, value, type, dark, matched)
     return row;
 }
 
+/************************************************************
+ *  The per-node fold handle, drawn in the card's header.
+ *
+ *  Only a card with a BRANCH gets one — a leaf has nothing to
+ *  fold, and a handle that does nothing is worse than none.
+ *  It carries the path in `data-fold-path`, which is what the
+ *  delegated listener in build_ui reads; the card is an
+ *  innerHTML string, so there is no other way to hang a
+ *  handler on it.
+ *
+ *  Folded it shows the glyph AND the count of branches hidden
+ *  under it; open, just the glyph.  No word, no title: a word
+ *  inside this string could carry no i18n key.
+ ************************************************************/
+function fold_toggle_html(path, foldable, folded, branches)
+{
+    if(!foldable) {
+        /*  A spacer, so the label of a leaf card stays centred on the
+         *  same axis as the label of a foldable one.  */
+        return `<span style="width:1.1em; flex:0 0 auto;"></span>`;
+    }
+
+    let glyph = folded? "&#9656;": "&#9662;";       /*  right / down  */
+    let text = folded? `${glyph} ${branches}`: glyph;
+
+    return `<span data-fold-path="${escapeHtml(path)}" ` +
+        `style="flex:0 0 auto; cursor:pointer; user-select:none; ` +
+        `padding:0 .2em; min-width:1.1em; text-align:left;">${text}</span>`;
+}
+
 /************************************************************
  *  Does this key/value pair match the find term?
  *
@@ -725,17 +815,12 @@ function build_json_nodes(gobj, path, kw, nodes, edges, parent_id)
      *  Folded: keep the card, drop the branch, and SAY how much went
      *  with it.  A cut that is not marked reads as a document that ends
      *  there — the same rule the lazy tree follows for a `__collapsed__`
-     *  sentinel.  The badge is a glyph and a number on purpose: the card
+     *  sentinel.  The mark is a glyph and a number on purpose: the card
      *  is an innerHTML string, where a word could carry no i18n key and
      *  would sit there in English forever.
      */
-    let folded = priv.collapsed.has(path) && pending_complex.length > 0;
-    if(folded) {
-        lines.push(
-            `<span style="color:${type_color("number", dark)}; font-weight:bold;">` +
-            `&#9656; ${pending_complex.length}</span>`
-        );
-    }
+    let foldable = pending_complex.length > 0;
+    let folded = foldable && priv.collapsed.has(path);
     let colors = json_card_style(
         is_dict ? GROUP_COLORS.dict : GROUP_COLORS.list, dark
     );
@@ -766,8 +851,10 @@ function build_json_nodes(gobj, path, kw, nodes, edges, parent_id)
         font-weight: bold;
         font-size: 12px;
         padding: 3px 8px;
-        text-align: center;
-    ">${escapeHtml(label)}</div>
+        display: flex;
+        align-items: center;
+        gap: 6px;
+    ">${fold_toggle_html(path, foldable, folded, pending_complex.length)}<span style="flex:1 1 auto; text-align:center;">${escapeHtml(label)}</span></div>
     ${content_html}
 </div>`;
 
@@ -1097,6 +1184,35 @@ function ac_refresh(gobj, event, kw, src)
 
 /************************************************************
  *  {theme: "dark"|"light"} — the app switched theme.
+ *  EV_TOGGLE_FOLD { path } — fold or unfold ONE card.
+ *
+ *  The camera does not move: folding one branch is a local
+ *  edit of the picture, and refitting the whole graph for it
+ *  would throw away where the reader was looking.  The toolbar
+ *  pair, which changes everything at once, does refit.
+ ************************************************************/
+function ac_toggle_fold(gobj, event, kw, src)
+{
+    let priv = gobj.priv;
+    let path = (kw && kw.path) || "";
+
+    if(empty_string(path)) {
+        log_error(`${gobj_short_name(gobj)}: EV_TOGGLE_FOLD with no path`);
+        return -1;
+    }
+
+    if(priv.collapsed.has(path)) {
+        priv.collapsed.delete(path);
+    } else {
+        priv.collapsed.add(path);
+    }
+
+    refresh_json(gobj, {preserve_view: true});
+    update_find_result(gobj);
+    return 0;
+}
+
+/************************************************************
  *  EV_FIND_NODES { text }
  *
  *  The camera does NOT move: a find is a way of reading what is
@@ -1349,6 +1465,7 @@ function create_gclass(gclass_name)
             ["EV_LOAD_DATA",            ac_load_data,           null],
             ["EV_REFRESH",              ac_refresh,             null],
             ["EV_FIND_NODES",           ac_find_nodes,          null],
+            ["EV_TOGGLE_FOLD",          ac_toggle_fold,         null],
             ["EV_EXPAND_ALL",           ac_expand_all,          null],
             ["EV_COLLAPSE_ALL",         ac_collapse_all,        null],
             ["EV_THEME",                ac_theme,               null],
@@ -1370,6 +1487,7 @@ function create_gclass(gclass_name)
         ["EV_LOAD_DATA",            0],
         ["EV_REFRESH",              0],
         ["EV_FIND_NODES",           0],
+        ["EV_TOGGLE_FOLD",          0],
         ["EV_EXPAND_ALL",           0],
         ["EV_COLLAPSE_ALL",         0],
         ["EV_THEME",                0],