@yuneta/gobj-ui 5.5.0 → 5.6.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

@@ -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.
@@ -12943,7 +13020,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 +53704,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;

package/dist/gobj-ui.es.js

@@ -1651,17 +1651,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 (!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 (!empty_string(it.name)) children.push([
 		"span",
@@ -2672,6 +2714,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 || !is_gobj(shell_gobj) || empty_string(item_id)) return;
+	let $container = 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.
@@ -12938,7 +13015,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
@@ -53529,6 +53611,6 @@ function setup_frontend_view(self) {
 	return win;
 }
 //#endregion
-export { EditControl, MarkerControl, YUI_PERIODS, YUI_PERIODS_DEFAULT, YUI_ROLLING, addClasses, apply_dev_traces, attach_clear, build_dev_panel, dev_window_was_open, disableElements, enableElements, epoch_to_local_input, epoch_to_ms, expose_view_container, fmt_epoch, getStrokeColor, infer_period, info_traffic, inject_svg_icons, is_current_period, iso_week, local_input_to_epoch, ms_to_epoch, period_bounds, period_bounds_epoch, period_label, period_name, period_shift, period_spec, period_start, refresh_clear, register_c_g6_nodes_tree, register_c_yui_form, register_c_yui_gobj_tree_js, register_c_yui_json, register_c_yui_json_graph, register_c_yui_map, register_c_yui_nav, register_c_yui_pager, register_c_yui_period, register_c_yui_service_view, register_c_yui_shell, register_c_yui_treedb_graph, register_c_yui_treedb_schema, register_c_yui_treedb_topic_with_form, register_c_yui_treedb_topics, register_c_yui_uplot, register_c_yui_window, register_c_yui_window_manager, register_c_yui_wizard, removeChildElements, removeClasses, rolling_bounds, safe_locale, set_active_state, set_cancel_state, set_submit_state, setup_dev, setup_frontend_view, toggleClasses, yui_is_dark, yui_mount_service_view, yui_shell_close_drawer, yui_shell_close_dropdown, yui_shell_confirm_ok, yui_shell_confirm_yesno, yui_shell_confirm_yesnocancel, yui_shell_navigate, yui_shell_open_drawer, yui_shell_overlay_dismissed, yui_shell_pop_escape, yui_shell_push_escape, yui_shell_refresh_avatars, yui_shell_register_event_handler, yui_shell_register_overlay, yui_shell_set_avatar_provider, yui_shell_set_connection_state, yui_shell_set_sub_routes, yui_shell_set_toolbar_item_icon, yui_shell_set_translator, yui_shell_show_error, yui_shell_show_info, yui_shell_show_modal, yui_shell_show_route_map, yui_shell_show_warning, yui_shell_toggle_drawer, yui_shell_unpark_route, yui_theme_now, yui_toolbar, yui_watch_theme };
+export { EditControl, MarkerControl, YUI_PERIODS, YUI_PERIODS_DEFAULT, YUI_ROLLING, addClasses, apply_dev_traces, attach_clear, build_dev_panel, dev_window_was_open, disableElements, enableElements, epoch_to_local_input, epoch_to_ms, expose_view_container, fmt_epoch, getStrokeColor, infer_period, info_traffic, inject_svg_icons, is_current_period, iso_week, local_input_to_epoch, ms_to_epoch, period_bounds, period_bounds_epoch, period_label, period_name, period_shift, period_spec, period_start, refresh_clear, register_c_g6_nodes_tree, register_c_yui_form, register_c_yui_gobj_tree_js, register_c_yui_json, register_c_yui_json_graph, register_c_yui_map, register_c_yui_nav, register_c_yui_pager, register_c_yui_period, register_c_yui_service_view, register_c_yui_shell, register_c_yui_treedb_graph, register_c_yui_treedb_schema, register_c_yui_treedb_topic_with_form, register_c_yui_treedb_topics, register_c_yui_uplot, register_c_yui_window, register_c_yui_window_manager, register_c_yui_wizard, removeChildElements, removeClasses, rolling_bounds, safe_locale, set_active_state, set_cancel_state, set_submit_state, setup_dev, setup_frontend_view, toggleClasses, yui_is_dark, yui_mount_service_view, yui_shell_close_drawer, yui_shell_close_dropdown, yui_shell_confirm_ok, yui_shell_confirm_yesno, yui_shell_confirm_yesnocancel, yui_shell_navigate, yui_shell_open_drawer, yui_shell_overlay_dismissed, yui_shell_pop_escape, yui_shell_push_escape, yui_shell_refresh_avatars, yui_shell_register_event_handler, yui_shell_register_overlay, yui_shell_set_avatar_provider, yui_shell_set_connection_state, yui_shell_set_sub_routes, yui_shell_set_toolbar_item_badge, yui_shell_set_toolbar_item_icon, yui_shell_set_translator, yui_shell_show_error, yui_shell_show_info, yui_shell_show_modal, yui_shell_show_route_map, yui_shell_show_warning, yui_shell_toggle_drawer, yui_shell_unpark_route, yui_theme_now, yui_toolbar, yui_watch_theme };
 
 //# sourceMappingURL=gobj-ui.es.js.map

package/index.js

@@ -46,6 +46,7 @@ export {
     yui_shell_set_translator,
     yui_shell_set_connection_state,
     yui_shell_set_toolbar_item_icon,
+    yui_shell_set_toolbar_item_badge,
     yui_shell_close_dropdown,
     yui_shell_register_event_handler,
     yui_shell_set_sub_routes,

package/package.json

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

package/src/c_yui_nav.js

@@ -32,7 +32,12 @@
  *      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

package/src/c_yui_shell.css

@@ -449,6 +449,53 @@
     background-color: var(--bulma-scheme-main-bis, rgba(0,0,0,0.04));
 }
 
+/*------------------------------------------------------------
+ *      Toolbar badge — the count pinned to an item's icon
+ *
+ *  Anchored to the ICON and not to the button: with its label on
+ *  (desktop) the button is wide, and a badge in its corner would
+ *  float away from the glyph it counts.
+ *
+ *  `hidden` is honoured explicitly: the element is always in the
+ *  DOM (so the runtime setter has somewhere to write) and
+ *  [hidden] loses to `display:inline-flex` without this rule.
+ *
+ *  Danger colour on purpose — a badge exists to pull the eye.  It
+ *  is its own colour pair in both schemes rather than a Bulma
+ *  helper, so it keeps its contrast when the toolbar background
+ *  changes with the theme.  No transition: house rule.
+ *------------------------------------------------------------*/
+.yui-toolbar-icon {
+    position: relative;
+    overflow: visible;
+}
+.yui-toolbar-badge {
+    position: absolute;
+    top: -0.35em;
+    right: -0.55em;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    /*  A round dot for one digit, a pill from two on. */
+    min-width: 1.15em;
+    height: 1.15em;
+    padding: 0 0.3em;
+    border-radius: 999px;
+    font-size: 0.62em;
+    font-weight: 700;
+    line-height: 1;
+    font-family: inherit;
+    background-color: var(--bulma-danger, #f14668);
+    color: var(--bulma-danger-invert, #fff);
+    /*  Separates the pill from the glyph when they overlap. */
+    box-shadow: 0 0 0 0.12em var(--bulma-scheme-main, #fff);
+    pointer-events: none;
+}
+.yui-toolbar-badge[hidden] {
+    display: none;
+}
+
 /*============================================================
  *      Toolbar — type:"brand"
  *      Logo image + wordmark text. Renders as <button> when

package/src/c_yui_shell.js

@@ -1641,6 +1641,51 @@ 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 === undefined || 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.
  ************************************************************/
@@ -1648,8 +1693,15 @@ function build_toolbar_action_item(gobj, it)
 {
     let children = [];
     if(!empty_string(it.icon)) {
-        children.push(["span", {class: "icon"},
-            ["i", {class: it.icon, "aria-hidden": "true"}]]);
+        /*  The badge is anchored to the ICON, not to the button: with a
+         *  label on (desktop) the button is wide, and a badge pinned to
+         *  its corner would float far from the glyph it counts. */
+        children.push(["span", {class: "icon yui-toolbar-icon"},
+            [
+                ["i", {class: it.icon, "aria-hidden": "true"}],
+                badge_node(it.badge)
+            ]
+        ]);
     }
     if(!empty_string(it.name)) {
         children.push(["span", {class: "yui-toolbar-item-label", i18n: it.name},
@@ -3368,6 +3420,57 @@ function yui_shell_set_toolbar_item_icon(shell_gobj, item_id, 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 || !is_gobj(shell_gobj) || empty_string(item_id)) {
+        return;
+    }
+    let $container = 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;
+    }
+    /*  Do not touch the DOM when nothing changed: role="status" is a
+     *  live region, and rewriting the same number would have a screen
+     *  reader announce it again on every tick. */
+    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
@@ -3414,6 +3517,7 @@ export {
     yui_shell_language_changed,
     yui_shell_set_connection_state,
     yui_shell_set_toolbar_item_icon,
+    yui_shell_set_toolbar_item_badge,
     yui_shell_close_dropdown,
     yui_shell_set_submenu
 };