@yuneta/gobj-ui 5.5.0 → 5.7.0

package/README.md

@@ -464,6 +464,46 @@ host can use it to toggle. The tree is a **pure child of the window**, so every
 teardown path (the ✕, or the host destroying the window to toggle the entry
 off) takes it down too.
 
+### Toolbar badge — a count pinned to an item's icon
+
+```js
+/*  app_config.json — seeds the FIRST paint only  */
+{ "id": "alarms", "icon": "yi-triangle-exclamation", "align": "end",
+  "aria_label": "alarms", "badge": 0,
+  "action": {"type": "navigate", "route": "/alarms"} }
+
+/*  the interface that matters: a count is a RUNTIME fact  */
+yui_shell_set_toolbar_item_badge(shell, "alarms", 3);
+yui_shell_set_toolbar_item_badge(shell, "alarms", 0);   // clears it
+```
+
+An icon-only toolbar button is a link; the badge is what makes it a
+**signal**. Without a number, an alarm bell cannot say whether anything needs
+you — which is the reason to look at it at all.
+
+Rules baked in, all for the same reason (a badge that lies costs more than no
+badge):
+
+- **`0`, `""`, `null` and `false` all clear it.** A badge reading "0" is worse
+  than none: it draws the eye to say nothing.
+- **Over 99 renders `99+`.** The toolbar is a fixed-width row and a four-digit
+  pill pushes its neighbours off a phone screen.
+- **A string passes through** for the states that are not counts (`"!"`, `"…"`).
+- **Unknown item id is a silent no-op**, so an app whose toolbar has no such
+  item does not log an error on every tick of whatever feeds the number.
+- Writing the **same** value again touches no DOM: the badge is a
+  `role="status"` live region, and rewriting it would have a screen reader
+  announce the same number on every tick.
+
+`role="status"` and not `aria-hidden`, deliberately: the button carries an
+explicit `aria-label`, and an explicit label **replaces** an element's content
+for a screen reader — a badge inside it would otherwise be silent. As its own
+live region it is both read and announced when it changes.
+
+> `C_YUI_NAV` items do **not** have this. Its item contract listed `badge` for a
+> long time and nothing ever rendered it; the claim is gone. Implement it there
+> the day a menu entry needs one.
+
 ### Modals — `yui_shell_show_modal` and the `before_close` veto
 
 `yui_shell_show_modal(shell, $box, opts)` is the standard popup: pass

package/dist/gobj-ui.cjs.js

@@ -890,7 +890,7 @@ function mt_start$15(gobj) {
 	if (typeof shell_cfg.remember_section_position === "boolean") (0, _yuneta_gobj_js.gobj_write_attr)(gobj, "remember_section_position", shell_cfg.remember_section_position);
 	build_item_index(gobj, config);
 	instantiate_menus(gobj, config);
-	build_toolbar(gobj, config);
+	build_toolbar$1(gobj, config);
 	preinstantiate_eager_views(gobj);
 	if ((0, _yuneta_gobj_js.gobj_read_attr)(gobj, "use_hash")) {
 		priv.hash_handler = () => {
@@ -1616,7 +1616,7 @@ function safe_id(s) {
 *  Per-item `show_on` is honoured: each rendered item is wrapped with
 *  the same Bulma-helper logic as zones.
 ************************************************************/
-function build_toolbar(gobj, config) {
+function build_toolbar$1(gobj, config) {
 	let tb = config && config.toolbar;
 	if (!tb || !(0, _yuneta_gobj_js.is_array)(tb.items)) return;
 	let priv = gobj.priv;
@@ -1656,17 +1656,59 @@ function build_toolbar(gobj, config) {
 	$zone.appendChild($bar);
 }
 /************************************************************
+*  The badge node of a toolbar item — the little count pinned to
+*  the corner of its icon (unread notifications, active alarms).
+*
+*  ALWAYS rendered, hidden when empty, so the runtime setter has a
+*  node to write into and does not have to rebuild the button.
+*
+*  EMPTY IS 0, "" AND null ALIKE: a badge reading "0" is worse than
+*  no badge — it draws the eye to say nothing.  A count is only
+*  worth a pixel when there IS something.
+*
+*  Capped at 99+: the toolbar is a fixed-width row, and a four
+*  digit pill pushes the items next to it off a phone screen.
+*
+*  role="status" and NOT aria-hidden, deliberately.  The button
+*  carries an explicit aria-label, and an explicit label REPLACES
+*  the element's content for a screen reader — so a badge inside
+*  it would be silent.  As its own live region it is both read and
+*  announced when the count changes, which is the whole point of a
+*  badge that means "something needs you".
+************************************************************/
+function badge_text(value) {
+	if (value === null || value === void 0 || value === false) return "";
+	if (typeof value === "number") {
+		if (!isFinite(value) || value <= 0) return "";
+		return value > 99 ? "99+" : String(Math.floor(value));
+	}
+	return String(value).trim();
+}
+function badge_node(value) {
+	let text = badge_text(value);
+	let attrs = {
+		class: "yui-toolbar-badge",
+		role: "status"
+	};
+	if (!text) attrs.hidden = "hidden";
+	return [
+		"span",
+		attrs,
+		text
+	];
+}
+/************************************************************
 *  Renderer for the default ("action") item kind.
 ************************************************************/
 function build_toolbar_action_item(gobj, it) {
 	let children = [];
 	if (!(0, _yuneta_gobj_js.empty_string)(it.icon)) children.push([
 		"span",
-		{ class: "icon" },
-		["i", {
+		{ class: "icon yui-toolbar-icon" },
+		[["i", {
 			class: it.icon,
 			"aria-hidden": "true"
-		}]
+		}], badge_node(it.badge)]
 	]);
 	if (!(0, _yuneta_gobj_js.empty_string)(it.name)) children.push([
 		"span",
@@ -2677,6 +2719,41 @@ function yui_shell_set_toolbar_item_icon(shell_gobj, item_id, icon_class) {
 	if ($i) $i.className = icon_class;
 }
 /************************************************************
+*  Set (or clear) a toolbar item's badge — the count pinned to
+*  its icon.
+*
+*      yui_shell_set_toolbar_item_badge(shell, "alarms", 3);
+*      yui_shell_set_toolbar_item_badge(shell, "alarms", 0);   // hidden
+*
+*  This is the API that matters: a count is a RUNTIME fact.  The
+*  `badge` field of a toolbar item only seeds the first paint, and
+*  an app whose number never changes did not need a badge.
+*
+*  0 / "" / null / false all clear it, and a number over 99 renders
+*  "99+" — see badge_node().  Accepts a string for the states that
+*  are not counts ("!", "…").
+*
+*  Silent no-op on an unknown item id: a toolbar that does not
+*  declare the item (an app without alarms) must not be an error
+*  at every tick of whatever feeds the number.
+************************************************************/
+function yui_shell_set_toolbar_item_badge(shell_gobj, item_id, value) {
+	if (!shell_gobj || !(0, _yuneta_gobj_js.is_gobj)(shell_gobj) || (0, _yuneta_gobj_js.empty_string)(item_id)) return;
+	let $container = (0, _yuneta_gobj_js.gobj_read_attr)(shell_gobj, "$container");
+	if (!$container) return;
+	let $badge = $container.querySelector(`[data-toolbar-item-id="${item_id}"] .yui-toolbar-badge`);
+	if (!$badge) return;
+	let text = badge_text(value);
+	if (!text) {
+		$badge.textContent = "";
+		$badge.setAttribute("hidden", "hidden");
+		return;
+	}
+	if ($badge.textContent === text && !$badge.hasAttribute("hidden")) return;
+	$badge.textContent = text;
+	$badge.removeAttribute("hidden");
+}
+/************************************************************
 *  Programmatic close of any open toolbar dropdown.  Useful for
 *  external triggers (e.g. EV_LOGOUT firing from elsewhere) that
 *  want to dismiss whatever menu is on screen.
@@ -5683,6 +5760,59 @@ function refresh_clear($input) {
 	$btn.classList.toggle("is-visible", clear_visible($input));
 }
 //#endregion
+//#region src/form_toolbar_plan.js
+/***********************************************************************
+*          form_toolbar_plan.js
+*
+*      Which buttons the C_YUI_FORM toolbar shows, and where.
+*
+*      Pure, so it can be tested without a DOM: the gclass turns the
+*      plan into elements, this decides the plan.
+*
+*          Copyright (c) 2026, ArtGins.
+*          All Rights Reserved.
+***********************************************************************/
+var LEFT_BUTTONS = [
+	"save",
+	"undo",
+	"clear"
+];
+var RIGHT_BUTTONS = ["copy", "paste"];
+var DEFAULT_TOOLBAR = [
+	"save",
+	"undo",
+	"clear",
+	"copy",
+	"paste"
+];
+/***************************************************************
+*  plan_toolbar(wanted) -> {left, right, unknown}
+*
+*      wanted   an array of button names, in the order asked for.
+*               Anything that is not an array means "the default
+*               five", so a caller that sets nothing keeps exactly
+*               the toolbar this gclass always had.
+*               [] means no toolbar at all.
+*
+*      unknown  names that match no button.  They are reported and
+*               NOT silently dropped: a typo in the list would
+*               otherwise remove the save button with no trace.
+***************************************************************/
+function plan_toolbar(wanted) {
+	if (!Array.isArray(wanted)) wanted = DEFAULT_TOOLBAR;
+	let left = [];
+	let right = [];
+	let unknown = [];
+	for (let name of wanted) if (LEFT_BUTTONS.indexOf(name) >= 0) left.push(name);
+	else if (RIGHT_BUTTONS.indexOf(name) >= 0) right.push(name);
+	else unknown.push(name);
+	return {
+		left,
+		right,
+		unknown
+	};
+}
+//#endregion
 //#region src/yui_theme.js
 /***********************************************************************
 *          yui_theme.js
@@ -5814,6 +5944,13 @@ var attrs_table$13 = [
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_BOOLEAN, "with_checkbox", 0, false, "Show a first column with checkbox to select rows"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_BOOLEAN, "with_rownum", 0, false, "Print first column with row number"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_BOOLEAN, "with_delete_row_btn", 0, false, "Print last column with delete row button"),
+	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_JSON, "toolbar", 0, [
+		"save",
+		"undo",
+		"clear",
+		"copy",
+		"paste"
+	], "Toolbar buttons to show, in order: save, undo, clear, copy, paste. [] hides the toolbar"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_JSON, "tabulator_settings", 0, {
 		layout: "fitDataFill",
 		validationMode: "highlight",
@@ -5924,6 +6061,175 @@ async function readClipboard$1(gobj) {
 	}
 }
 /************************************************************
+*   Bottom toolbar, from the `toolbar` attr.
+*
+*   The five buttons it can show, and their order, are the
+*   caller's: a dialog with a single action asks for ["save"],
+*   and [] leaves no toolbar at all.  Default is the five it
+*   always had, so nothing moves for a caller that says nothing.
+************************************************************/
+function toolbar_button(gobj, name) {
+	switch (name) {
+		case "save": return [
+			"button",
+			{
+				class: "button p-1 button-save",
+				title: "save",
+				"aria-label": "save",
+				disabled: true
+			},
+			[[
+				"span",
+				{ class: "icon m-0" },
+				"<i class=\"yi-floppy-disk\"></i>"
+			], [
+				"span",
+				{
+					class: "is-hidden-mobile pl-1 pr-1",
+					i18n: "save"
+				},
+				"save"
+			]],
+			{ click: function(evt) {
+				evt.stopPropagation();
+				(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_SAVE_RECORD", {}, gobj);
+			} }
+		];
+		case "undo": return [
+			"button",
+			{
+				class: "button p-1 button-undo",
+				title: "undo",
+				"aria-label": "undo",
+				disabled: true
+			},
+			[[
+				"span",
+				{ class: "icon m-0" },
+				"<i class=\"yi-arrow-rotate-left\"></i>"
+			], [
+				"span",
+				{
+					class: "is-hidden-mobile pl-1 pr-1",
+					i18n: "undo"
+				},
+				"undo"
+			]],
+			{ click: function(evt) {
+				evt.stopPropagation();
+				(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_UNDO_RECORD", {}, gobj);
+			} }
+		];
+		case "clear": return [
+			"button",
+			{
+				class: "button p-1",
+				title: "clear",
+				"aria-label": "clear"
+			},
+			[[
+				"span",
+				{ class: "icon m-0" },
+				"<i class=\"yi-broom-wide\"></i>"
+			], [
+				"span",
+				{
+					class: "is-hidden-mobile pl-1 pr-1",
+					i18n: "clear"
+				},
+				"clear"
+			]],
+			{ click: function(evt) {
+				evt.stopPropagation();
+				(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_CLEAR_RECORD", {}, gobj);
+			} }
+		];
+		case "copy": return [
+			"button",
+			{
+				class: "button p-1",
+				title: "copy",
+				"aria-label": "copy"
+			},
+			[[
+				"span",
+				{ class: "icon m-0" },
+				"<i class=\"yi-copy\"></i>"
+			], [
+				"span",
+				{
+					class: "is-hidden-mobile pl-1 pr-1",
+					i18n: "copy"
+				},
+				"copy"
+			]],
+			{ click: function(evt) {
+				evt.stopPropagation();
+				(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_COPY_RECORD", {}, gobj);
+			} }
+		];
+		case "paste": return [
+			"button",
+			{
+				class: "button p-1",
+				title: "paste",
+				"aria-label": "paste"
+			},
+			[[
+				"span",
+				{ class: "icon m-0" },
+				"<i class=\"yi-paste\"></i>"
+			], [
+				"span",
+				{
+					class: "is-hidden-mobile pl-1 pr-1",
+					i18n: "paste"
+				},
+				"paste"
+			]],
+			{ click: async function(evt) {
+				evt.stopPropagation();
+				await readClipboard$1(gobj);
+			} }
+		];
+		default: return null;
+	}
+}
+function build_toolbar(gobj) {
+	const plan = plan_toolbar((0, _yuneta_gobj_js.gobj_read_attr)(gobj, "toolbar"));
+	for (let name of plan.unknown) (0, _yuneta_gobj_js.log_warning)(`${(0, _yuneta_gobj_js.gobj_short_name)(gobj)}: unknown toolbar button '${name}'`);
+	if (!plan.left.length && !plan.right.length) return [
+		"span",
+		{
+			class: "yui-toolbar-form-empty",
+			style: "display:none;"
+		},
+		""
+	];
+	return [
+		"div",
+		{
+			class: "yui-toolbar-form is-flex-shrink-0 is-flex is-flex-direction-row is-justify-content-space-between is-align-items-center",
+			style: "width:100%; flex-wrap:wrap; row-gap:6px;"
+		},
+		[[
+			"div",
+			{
+				class: "p-1 is-flex is-flex-direction-row is-align-items-center",
+				style: "column-gap:6px;"
+			},
+			plan.left.map((n) => toolbar_button(gobj, n))
+		], [
+			"div",
+			{
+				class: "p-1 is-flex is-flex-direction-row is-align-items-center",
+				style: "column-gap:6px;"
+			},
+			plan.right.map((n) => toolbar_button(gobj, n))
+		]]
+	];
+}
+/************************************************************
 *   Build UI
 ************************************************************/
 function build_ui$11(gobj) {
@@ -5940,149 +6246,7 @@ function build_ui$11(gobj) {
 				style: "overflow-y:auto; min-height:0;"
 			},
 			build_form(gobj)
-		], [
-			"div",
-			{
-				class: "yui-toolbar-form is-flex-shrink-0 is-flex is-flex-direction-row is-justify-content-space-between is-align-items-center",
-				style: "width:100%; flex-wrap:wrap; row-gap:6px;"
-			},
-			[[
-				"div",
-				{
-					class: "p-1 is-flex is-flex-direction-row is-align-items-center",
-					style: "column-gap:6px;"
-				},
-				[
-					[
-						"button",
-						{
-							class: "button p-1 button-save",
-							title: "save",
-							"aria-label": "save",
-							disabled: true
-						},
-						[[
-							"span",
-							{ class: "icon m-0" },
-							"<i class=\"yi-floppy-disk\"></i>"
-						], [
-							"span",
-							{
-								class: "is-hidden-mobile pl-1 pr-1",
-								i18n: "save"
-							},
-							"save"
-						]],
-						{ click: function(evt) {
-							evt.stopPropagation();
-							(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_SAVE_RECORD", {}, gobj);
-						} }
-					],
-					[
-						"button",
-						{
-							class: "button p-1 button-undo",
-							title: "undo",
-							"aria-label": "undo",
-							disabled: true
-						},
-						[[
-							"span",
-							{ class: "icon m-0" },
-							"<i class=\"yi-arrow-rotate-left\"></i>"
-						], [
-							"span",
-							{
-								class: "is-hidden-mobile pl-1 pr-1",
-								i18n: "undo"
-							},
-							"undo"
-						]],
-						{ click: function(evt) {
-							evt.stopPropagation();
-							(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_UNDO_RECORD", {}, gobj);
-						} }
-					],
-					[
-						"button",
-						{
-							class: "button p-1",
-							title: "clear",
-							"aria-label": "clear"
-						},
-						[[
-							"span",
-							{ class: "icon m-0" },
-							"<i class=\"yi-broom-wide\"></i>"
-						], [
-							"span",
-							{
-								class: "is-hidden-mobile pl-1 pr-1",
-								i18n: "clear"
-							},
-							"clear"
-						]],
-						{ click: function(evt) {
-							evt.stopPropagation();
-							(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_CLEAR_RECORD", {}, gobj);
-						} }
-					]
-				]
-			], [
-				"div",
-				{
-					class: "p-1 is-flex is-flex-direction-row is-align-items-center",
-					style: "column-gap:6px;"
-				},
-				[[
-					"button",
-					{
-						class: "button p-1",
-						title: "copy",
-						"aria-label": "copy"
-					},
-					[[
-						"span",
-						{ class: "icon m-0" },
-						"<i class=\"yi-copy\"></i>"
-					], [
-						"span",
-						{
-							class: "is-hidden-mobile pl-1 pr-1",
-							i18n: "copy"
-						},
-						"copy"
-					]],
-					{ click: function(evt) {
-						evt.stopPropagation();
-						(0, _yuneta_gobj_js.gobj_send_event)(gobj, "EV_COPY_RECORD", {}, gobj);
-					} }
-				], [
-					"button",
-					{
-						class: "button p-1",
-						title: "paste",
-						"aria-label": "paste"
-					},
-					[[
-						"span",
-						{ class: "icon m-0" },
-						"<i class=\"yi-paste\"></i>"
-					], [
-						"span",
-						{
-							class: "is-hidden-mobile pl-1 pr-1",
-							i18n: "paste"
-						},
-						"paste"
-					]],
-					{ click: async function(evt) {
-						evt.stopPropagation();
-						await readClipboard$1(gobj);
-					} }
-				]]
-			]]
-		]]
+		], build_toolbar(gobj)]
 	]);
 	(0, _yuneta_gobj_js.gobj_write_attr)(gobj, "$container", $container);
 	apply_form_mode(gobj, $container.querySelector("form"));
@@ -12943,7 +13107,12 @@ function cards_grid_descriptor(items, show_label) {
 *      container; build_ui re-applies them on every rebuild.
 *
 *      Each item supports:
-*          id, name, icon (CSS class or svg id), route, badge, disabled
+*          id, name, icon (CSS class or svg id), route, disabled
+*          (`badge` was listed here for a long time and NOTHING ever
+*           rendered it — a menu item cannot carry a count today. The
+*           toolbar can: `badge` on a toolbar item plus
+*           yui_shell_set_toolbar_item_badge(). Implement it here the
+*           day a menu entry needs one, rather than re-listing it.)
 *          class    — extra CSS class(es) on the item (tabs layout), e.g.
 *                     a per-item state colour like "yui-nav-disconnected"
 *          closable — render a trailing ✕ that emits EV_NAV_ITEM_CLOSE
@@ -53622,6 +53791,7 @@ exports.yui_shell_register_overlay = yui_shell_register_overlay;
 exports.yui_shell_set_avatar_provider = yui_shell_set_avatar_provider;
 exports.yui_shell_set_connection_state = yui_shell_set_connection_state;
 exports.yui_shell_set_sub_routes = yui_shell_set_sub_routes;
+exports.yui_shell_set_toolbar_item_badge = yui_shell_set_toolbar_item_badge;
 exports.yui_shell_set_toolbar_item_icon = yui_shell_set_toolbar_item_icon;
 exports.yui_shell_set_translator = yui_shell_set_translator;
 exports.yui_shell_show_error = yui_shell_show_error;