@yuneta/gobj-ui 5.4.0 → 5.6.0

package/src/c_yui_shell.js

@@ -1542,10 +1542,8 @@ function build_view_gobj(gobj, entry, route, stage)
      *  (synthesized "cards" C_YUI_NAV) is SHELL-owned DOM built after
      *  the host's one-shot refresh_language — apply the registered
      *  translator, same policy as lazily-built dropdown panels. */
-    let priv = gobj.priv;
-    if(priv && typeof priv.translator === "function" &&
-            target.gclass === "C_YUI_NAV") {
-        refresh_language($view, priv.translator);
+    if(target.gclass === "C_YUI_NAV") {
+        yui_shell_translate(gobj, $view);
     }
     return view;
 }
@@ -1643,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.
  ************************************************************/
@@ -1650,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},
@@ -2050,9 +2100,7 @@ function open_toolbar_dropdown(gobj, item, action, $trigger)
     priv.layers.popup.appendChild($panel);
 
     /*  Translate the lazily-built panel (see the note above). */
-    if(typeof priv.translator === "function") {
-        refresh_language($panel, priv.translator);
-    }
+    yui_shell_translate(gobj, $panel);
 
     /*  Click-outside (capture-phase mousedown) closes the dropdown.
      *  Capture phase so a click on a sibling toolbar trigger lands
@@ -2857,10 +2905,7 @@ function yui_shell_set_submenu(shell_gobj, parent_item_id, items)
                 gobj_send_event(view, "EV_SET_ITEMS", {items: items}, shell_gobj);
                 /*  EV_SET_ITEMS rebuilt the DOM: re-apply the translator
                  *  (shell-owned DOM, same policy as build_view_gobj). */
-                let $view = gobj_read_attr(view, "$container");
-                if($view && typeof priv.translator === "function") {
-                    refresh_language($view, priv.translator);
-                }
+                yui_shell_translate(shell_gobj, gobj_read_attr(view, "$container"));
             }
         }
     }
@@ -3265,9 +3310,10 @@ function yui_shell_refresh_avatars(shell_gobj)
  *  Register the host's i18n translator (a t-function:
  *  key => translated string).  The host still translates the
  *  static shell tree itself via refresh_language($container, t);
- *  this is only so the shell can translate DOM it builds LAZILY
- *  and OUTSIDE $container — today the toolbar dropdown panel.
- *  Optional: with no translator the panel renders raw keys
+ *  this is only so the shell — and the library components that
+ *  build DOM under it — can translate DOM built LAZILY, after
+ *  that one-shot pass and often outside $container.
+ *  Optional: with no translator such DOM renders raw keys
  *  (the previous behaviour).
  ************************************************************/
 function yui_shell_set_translator(shell_gobj, t)
@@ -3279,6 +3325,39 @@ function yui_shell_set_translator(shell_gobj, t)
     priv.translator = (typeof t === "function") ? t : null;
 }
 
+/************************************************************
+ *  Apply the registered translator to a FRESHLY BUILT subtree.
+ *
+ *  Carrying the `i18n` key on a node is not enough for it to
+ *  render translated: the node is born holding the raw English
+ *  key, and the host's refresh_language() passes walk what
+ *  ALREADY exists — the shell tree at start up, document.body on
+ *  a language switch.  Anything built after that (a dropdown
+ *  panel, a nav a node renders when you walk into it) is reached
+ *  by neither, so it renders the key: lower-case English that
+ *  never changes language, i.e. exactly what a MISSING key looks
+ *  like.
+ *
+ *  The division of labour, unchanged: LIBRARY-built DOM is
+ *  translated through here; APP view gclasses translate their own
+ *  DOM (they own a `t` — see mount_view).
+ *
+ *  Silent no-op with no shell or no translator: an app that never
+ *  registered one keeps the previous behaviour instead of losing
+ *  its chrome.
+ ************************************************************/
+function yui_shell_translate(shell_gobj, $el)
+{
+    if(!$el || !shell_gobj || !is_gobj(shell_gobj)) {
+        return;
+    }
+    let priv = shell_gobj.priv;
+    if(!priv || typeof priv.translator !== "function") {
+        return;
+    }
+    refresh_language($el, priv.translator);
+}
+
 /************************************************************
  *  The app switched the language: re-translate the whole document (every
  *  node carrying data-i18n / data-i18n-title / data-i18n-aria-label) and
@@ -3341,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
@@ -3383,9 +3513,11 @@ export {
     yui_shell_set_avatar_provider,
     yui_shell_refresh_avatars,
     yui_shell_set_translator,
+    yui_shell_translate,
     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
 };