@yuneta/gobj-ui 7.3.0 → 7.4.0

package/dist/gobj-ui.cjs.js

@@ -18595,6 +18595,7 @@ var PRIVATE_DATA$4 = {
 	records: {},
 	gobj_nodes_tree: null,
 	find_timer: null,
+	focus_topic: "",
 	gobj_treedb_tables: null,
 	hook_data_viewer: null,
 	json_gobj: null,
@@ -18693,26 +18694,37 @@ function build_ui$4(gobj) {
 			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" },
-			$back ? [$back, $toolbar] : [$toolbar]
-		], [
-			"div",
-			{
-				class: `GRAPH_BODY is-flex-grow-1 ${padding}`,
-				style: "height:100%; min-height:0; overflow:hidden;"
-			},
-			[[
+		[
+			[
+				"div",
+				{ class: "GRAPH_TOOLBAR_ROW is-flex-grow-0 is-flex is-align-items-center" },
+				$back ? [$back, $toolbar] : [$toolbar]
+			],
+			[
 				"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;"
+					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;"
+					},
+					[]
+				]]
+			]
+		]
 	]);
 	(0, _yuneta_gobj_js.gobj_write_attr)(gobj, "$container", $container);
 	(0, _yuneta_gobj_js.refresh_language)($container, i18next.t);
@@ -18845,6 +18857,29 @@ function make_toolbar(gobj) {
 				(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_REFRESH_TREEDB", { evt }, gobj);
 			} }
 		],
+		[
+			"button",
+			{
+				class: "GRAPH_LEGEND_BTN button ml-2",
+				title: (0, i18next.t)("legend"),
+				"aria-label": (0, i18next.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();
+				(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_TOGGLE_LEGEND", {}, gobj);
+			} }
+		],
 		[
 			"button",
 			{
@@ -19854,6 +19889,86 @@ function ac_set_operation_mode$1(gobj, event, kw, src) {
 *  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 = (0, _yuneta_gobj_js.gobj_read_attr)(gobj, "$container");
+	if (!$container) return;
+	let $legend = $container.querySelector(".GRAPH_LEGEND");
+	if (!$legend) return;
+	let descs = priv.gobj_nodes_tree ? (0, _yuneta_gobj_js.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;
+		if (!desc || !desc.color) continue;
+		let focused = priv.focus_topic === topic_name;
+		let $item = (0, _yuneta_gobj_js.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);`
+			}], [
+				"span",
+				{},
+				topic_name
+			]],
+			{ click: (evt) => {
+				evt.stopPropagation();
+				(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_LEGEND_TOPIC", { topic: topic_name }, gobj);
+			} }
+		]);
+		$legend.appendChild($item);
+	}
+}
+/************************************************************
+*
+************************************************************/
+function ac_toggle_legend(gobj, event, kw, src) {
+	let $container = (0, _yuneta_gobj_js.gobj_read_attr)(gobj, "$container");
+	if (!$container) return 0;
+	let $legend = $container.querySelector(".GRAPH_LEGEND");
+	if (!$legend) {
+		(0, _yuneta_gobj_js.log_error)(`${(0, _yuneta_gobj_js.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) {
+		(0, _yuneta_gobj_js.log_error)(`${(0, _yuneta_gobj_js.gobj_short_name)(gobj)}: legend click with no topic`);
+		return -1;
+	}
+	(0, _yuneta_gobj_js.gobj_publish_event)(gobj, "EV_TOPIC_SELECTED", { topic: priv.focus_topic === topic ? "" : topic });
+	return 0;
+}
+/************************************************************
 *  Forward the find down to the graph child.
 ************************************************************/
 function ac_find_nodes$1(gobj, event, kw, src) {
@@ -19882,7 +19997,11 @@ function ac_find_result(gobj, event, kw, src) {
 }
 function ac_set_focus_topic(gobj, event, kw, src) {
 	let priv = gobj.priv;
-	if (priv.gobj_nodes_tree) (0, _yuneta_gobj_js.gobj_send_event)(priv.gobj_nodes_tree, "EV_FOCUS_TOPIC", { topic: kw && kw.topic }, gobj);
+	priv.focus_topic = kw && kw.topic || "";
+	if (priv.gobj_nodes_tree) (0, _yuneta_gobj_js.gobj_send_event)(priv.gobj_nodes_tree, "EV_FOCUS_TOPIC", { topic: priv.focus_topic }, gobj);
+	let $container = (0, _yuneta_gobj_js.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;
 }
 /************************************************************
@@ -20050,6 +20169,16 @@ function create_gclass$4(gclass_name) {
 			ac_find_nodes$1,
 			null
 		],
+		[
+			"EV_TOGGLE_LEGEND",
+			ac_toggle_legend,
+			null
+		],
+		[
+			"EV_LEGEND_TOPIC",
+			ac_legend_topic,
+			null
+		],
 		[
 			"EV_FIND_RESULT",
 			ac_find_result,
@@ -20098,6 +20227,9 @@ function create_gclass$4(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", _yuneta_gobj_js.event_flag_t.EVF_OUTPUT_EVENT | _yuneta_gobj_js.event_flag_t.EVF_NO_WARN_SUBS],
 		["EV_OPERATION_MODE_CHANGED", _yuneta_gobj_js.event_flag_t.EVF_OUTPUT_EVENT | _yuneta_gobj_js.event_flag_t.EVF_NO_WARN_SUBS],
 		["EV_RECORD_WRITTEN", _yuneta_gobj_js.event_flag_t.EVF_OUTPUT_EVENT | _yuneta_gobj_js.event_flag_t.EVF_NO_WARN_SUBS],
 		["EV_SHOW", 0],
@@ -52704,6 +52836,7 @@ var attrs_table$1 = [
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_BOOLEAN, "with_gridline", 0, true, "Use gridline plugin"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_BOOLEAN, "with_fullscreen", 0, true, "Use fullscreen plugin"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_BOOLEAN, "with_toolbar", 0, true, "Use toolbar plugin"),
+	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.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"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_STRING, "toolbar_position", 0, "right-top", "Toolbar position: top-left, top-right, bottom-left, bottom-right, left-top, right-top"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_LIST, "layout_names", _yuneta_gobj_js.sdata_flag_t.SDF_RD, JSON.stringify(Object.keys(_layouts)), "Available layout names (read-only, for parent to query)"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_STRING, "hook_port_position", 0, "bottom", "Hook port position"),
@@ -55543,6 +55676,61 @@ function show_node_detail_popover(gobj, node_id) {
 *  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 graph = gobj.priv.graph;
+	if (!graph) return;
+	let threshold = (0, _yuneta_gobj_js.gobj_read_integer_attr)(gobj, "minimap_min_nodes");
+	let n = 0;
+	try {
+		let data = graph.getData() || {};
+		n = (0, _yuneta_gobj_js.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;
+	graph_add_plugin(gobj, "minimap", {
+		size: [200, 140],
+		position: "bottom-left",
+		shape: (id, element_type, element) => {
+			if (element_type !== "node") return element;
+			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 Rect({ style: {
+					x: -size[0] / 2,
+					y: -size[1] / 2,
+					width: size[0],
+					height: size[1],
+					fill: color,
+					radius: 4
+				} });
+			} catch (e) {
+				(0, _yuneta_gobj_js.log_error)(`${(0, _yuneta_gobj_js.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
@@ -56339,6 +56527,7 @@ function ac_load_data(gobj, event, kw, src) {
 			graph_layout(gobj).then(() => {
 				if (priv.edit_mode) graph_add_plugin(gobj, "history");
 				else graph_remove_plugin(gobj, "history");
+				refresh_minimap(gobj);
 				if (priv._pending_focus_topic !== null) {
 					let ft = priv._pending_focus_topic;
 					priv._pending_focus_topic = null;

package/dist/gobj-ui.es.js

@@ -18582,6 +18582,7 @@ var PRIVATE_DATA$4 = {
 	records: {},
 	gobj_nodes_tree: null,
 	find_timer: null,
+	focus_topic: "",
 	gobj_treedb_tables: null,
 	hook_data_viewer: null,
 	json_gobj: null,
@@ -18680,26 +18681,37 @@ function build_ui$4(gobj) {
 			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" },
-			$back ? [$back, $toolbar] : [$toolbar]
-		], [
-			"div",
-			{
-				class: `GRAPH_BODY is-flex-grow-1 ${padding}`,
-				style: "height:100%; min-height:0; overflow:hidden;"
-			},
-			[[
+		[
+			[
+				"div",
+				{ class: "GRAPH_TOOLBAR_ROW is-flex-grow-0 is-flex is-align-items-center" },
+				$back ? [$back, $toolbar] : [$toolbar]
+			],
+			[
 				"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;"
+					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;"
+					},
+					[]
+				]]
+			]
+		]
 	]);
 	gobj_write_attr(gobj, "$container", $container);
 	refresh_language($container, t);
@@ -18832,6 +18844,29 @@ function make_toolbar(gobj) {
 				gobj_send_event(gobj, "EV_REFRESH_TREEDB", { evt }, gobj);
 			} }
 		],
+		[
+			"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);
+			} }
+		],
 		[
 			"button",
 			{
@@ -19841,6 +19876,86 @@ function ac_set_operation_mode$1(gobj, event, kw, src) {
 *  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;
+		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);`
+			}], [
+				"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.
 ************************************************************/
 function ac_find_nodes$1(gobj, event, kw, src) {
@@ -19869,7 +19984,11 @@ function ac_find_result(gobj, event, kw, src) {
 }
 function ac_set_focus_topic(gobj, event, kw, src) {
 	let priv = gobj.priv;
-	if (priv.gobj_nodes_tree) gobj_send_event(priv.gobj_nodes_tree, "EV_FOCUS_TOPIC", { topic: kw && kw.topic }, gobj);
+	priv.focus_topic = kw && kw.topic || "";
+	if (priv.gobj_nodes_tree) gobj_send_event(priv.gobj_nodes_tree, "EV_FOCUS_TOPIC", { topic: priv.focus_topic }, gobj);
+	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;
 }
 /************************************************************
@@ -20037,6 +20156,16 @@ function create_gclass$4(gclass_name) {
 			ac_find_nodes$1,
 			null
 		],
+		[
+			"EV_TOGGLE_LEGEND",
+			ac_toggle_legend,
+			null
+		],
+		[
+			"EV_LEGEND_TOPIC",
+			ac_legend_topic,
+			null
+		],
 		[
 			"EV_FIND_RESULT",
 			ac_find_result,
@@ -20085,6 +20214,9 @@ function create_gclass$4(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", event_flag_t.EVF_OUTPUT_EVENT | event_flag_t.EVF_NO_WARN_SUBS],
 		["EV_SHOW", 0],
@@ -52691,6 +52823,7 @@ var attrs_table$1 = [
 	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, JSON.stringify(Object.keys(_layouts)), "Available layout names (read-only, for parent to query)"),
 	SDATA(data_type_t.DTP_STRING, "hook_port_position", 0, "bottom", "Hook port position"),
@@ -55530,6 +55663,61 @@ function show_node_detail_popover(gobj, node_id) {
 *  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 graph = gobj.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;
+	graph_add_plugin(gobj, "minimap", {
+		size: [200, 140],
+		position: "bottom-left",
+		shape: (id, element_type, element) => {
+			if (element_type !== "node") return element;
+			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 Rect({ 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
@@ -56326,6 +56514,7 @@ function ac_load_data(gobj, event, kw, src) {
 			graph_layout(gobj).then(() => {
 				if (priv.edit_mode) graph_add_plugin(gobj, "history");
 				else graph_remove_plugin(gobj, "history");
+				refresh_minimap(gobj);
 				if (priv._pending_focus_topic !== null) {
 					let ft = priv._pending_focus_topic;
 					priv._pending_focus_topic = null;

package/package.json

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

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";
@@ -218,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,
@@ -4481,6 +4483,81 @@ 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
@@ -5686,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

@@ -148,6 +148,7 @@ let PRIVATE_DATA = {
     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)  */
@@ -354,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;'}, [
                 ]]
@@ -496,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.  */
@@ -2194,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.
  ************************************************************/
@@ -2242,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;
 }
 
@@ -2339,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],
@@ -2376,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",