@yuneta/gobj-ui 5.5.0 → 5.7.0

package/src/c_yui_form.js

@@ -57,6 +57,7 @@ import { createJSONEditor } from 'vanilla-jsoneditor';
 import "vanilla-jsoneditor/themes/jse-theme-dark.css";
 import "./c_yui_form.css";
 import {attach_clear, refresh_clear} from "./yui_inputs.js";
+import {plan_toolbar} from "./form_toolbar_plan.js";
 /*  Read at field-build time only — deliberately NOT watched: the hosting
  *  dialog rebuilds the form on every open, and re-rendering a form under
  *  the user mid-edit would throw away what they typed. */
@@ -96,6 +97,20 @@ SDATA(data_type_t.DTP_BOOLEAN,  "selectable",       0,  true,   "Rows selectable
 SDATA(data_type_t.DTP_BOOLEAN,  "with_checkbox",    0,  false,  "Show a first column with checkbox to select rows"),
 SDATA(data_type_t.DTP_BOOLEAN,  "with_rownum",      0,  false,  "Print first column with row number"),
 SDATA(data_type_t.DTP_BOOLEAN,  "with_delete_row_btn", 0,  false, "Print last column with delete row button"),
+/*
+ *  Which buttons the bottom toolbar shows, and in which order.  The
+ *  default is the five it has always shown, so nothing moves for a
+ *  caller that does not set it.
+ *
+ *  It exists because the toolbar was hardcoded: a three-field sign-up
+ *  dialog with ONE action still got save + undo + clear + copy + paste,
+ *  and the only way out was to not use this gclass at all.  `[]` hides
+ *  the toolbar entirely, for a caller that supplies its own buttons.
+ *
+ *  Unknown names are ignored, with a warning: a typo must not silently
+ *  drop the save button.
+ */
+SDATA(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"),
 /*
  *  Defaults for tabulator
  */
@@ -283,6 +298,90 @@ async function readClipboard(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();
+                    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();
+                    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();
+                    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();
+                    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(gobj);
+                }
+            }];
+        default:
+            return null;   /*  plan_toolbar() already warned  */
+    }
+}
+
+function build_toolbar(gobj)
+{
+    const plan = plan_toolbar(gobj_read_attr(gobj, "toolbar"));
+
+    for(let name of plan.unknown) {
+        /*  A typo must not silently drop the save button. */
+        log_warning(`${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
  ************************************************************/
@@ -314,81 +413,7 @@ function build_ui(gobj)
             /*----------------------------*
              *      Bottom toolbar
              *----------------------------*/
-            ['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;'}, [
-
-                /*----------------------------*
-                 *      Left buttons
-                 *----------------------------*/
-                ['div', {class: 'p-1 is-flex is-flex-direction-row is-align-items-center', style:'column-gap:6px;'}, [
-                    /*----------------------------*
-                     *      Save
-                     *----------------------------*/
-                    ['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();
-                            gobj_send_event(gobj, "EV_SAVE_RECORD", {}, gobj);
-                        }
-                    }],
-
-                    /*----------------------------*
-                     *      Undo
-                     *----------------------------*/
-                    ['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();
-                            gobj_send_event(gobj, "EV_UNDO_RECORD", {}, gobj);
-                        }
-                    }],
-
-                    /*----------------------------*
-                     *      Clear
-                     *----------------------------*/
-                    ['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();
-                            gobj_send_event(gobj, "EV_CLEAR_RECORD", {}, gobj);
-                        }
-                    }],
-                ]],
-
-                /*----------------------------*
-                 *      Right buttons
-                 *----------------------------*/
-                ['div', {class: 'p-1 is-flex is-flex-direction-row is-align-items-center', style:'column-gap:6px;'}, [
-                    /*----------------------------*
-                     *      Copy
-                     *----------------------------*/
-                    ['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();
-                            gobj_send_event(gobj, "EV_COPY_RECORD", {}, gobj);
-                        }
-                    }],
-
-                    /*----------------------------*
-                     *      Paste
-                     *----------------------------*/
-                    ['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(gobj);
-                        }
-                    }]
-                ]]
-            ]]
+            build_toolbar(gobj)
         ]]
     );
 

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
 };

package/src/form_toolbar_plan.js

@@ -0,0 +1,59 @@
+/***********************************************************************
+ *          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.
+ ***********************************************************************/
+
+/*  Save/undo/clear sit on the left of the bar, copy/paste on the right.
+ *  That split is what the layout has always drawn, and keeping it means
+ *  a caller who drops one group does not leave a hole in the middle. */
+const LEFT_BUTTONS  = ["save", "undo", "clear"];
+const RIGHT_BUTTONS = ["copy", "paste"];
+
+const 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};
+}
+
+
+export {plan_toolbar, DEFAULT_TOOLBAR};

package/src/form_toolbar_plan.test.js

@@ -0,0 +1,54 @@
+import {describe, it, expect} from "vitest";
+import {plan_toolbar, DEFAULT_TOOLBAR} from "./form_toolbar_plan.js";
+
+describe("plan_toolbar", () => {
+
+    it("says nothing -> the five buttons this gclass always had", () => {
+        const p = plan_toolbar(undefined);
+        expect(p.left).toEqual(["save", "undo", "clear"]);
+        expect(p.right).toEqual(["copy", "paste"]);
+        expect(p.unknown).toEqual([]);
+        expect(DEFAULT_TOOLBAR.length).toBe(5);
+    });
+
+    it("a non-array is not an empty toolbar: it is the default", () => {
+        /*  Reading a JSON attr that was never set must not silently
+         *  leave a form with no save button. */
+        for(const v of [null, "save", 0, {}]) {
+            expect(plan_toolbar(v).left).toContain("save");
+        }
+    });
+
+    it("[] leaves no toolbar at all", () => {
+        const p = plan_toolbar([]);
+        expect(p.left).toEqual([]);
+        expect(p.right).toEqual([]);
+        expect(p.unknown).toEqual([]);
+    });
+
+    it("one action: a dialog asks for save only", () => {
+        const p = plan_toolbar(["save"]);
+        expect(p.left).toEqual(["save"]);
+        expect(p.right).toEqual([]);
+    });
+
+    it("keeps the order asked for inside each side", () => {
+        const p = plan_toolbar(["clear", "save", "paste", "copy"]);
+        expect(p.left).toEqual(["clear", "save"]);
+        expect(p.right).toEqual(["paste", "copy"]);
+    });
+
+    it("an unknown name is REPORTED, never silently dropped", () => {
+        /*  A typo here would otherwise remove a button and leave no
+         *  trace of why it is missing. */
+        const p = plan_toolbar(["save", "sav", "undo"]);
+        expect(p.left).toEqual(["save", "undo"]);
+        expect(p.unknown).toEqual(["sav"]);
+    });
+
+    it("drops one whole side without disturbing the other", () => {
+        const p = plan_toolbar(["save", "undo", "clear"]);
+        expect(p.left).toEqual(["save", "undo", "clear"]);
+        expect(p.right).toEqual([]);
+    });
+});