@yuneta/gobj-ui 3.0.0 → 4.0.0

package/src/route_map_model.test.js

@@ -0,0 +1,209 @@
+/***********************************************************************
+ *          route_map_model.test.js
+ *
+ *          Unit tests for the pure site-map (nav map) builder.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import { describe, test, expect } from "vitest";
+import { build_nav_map } from "./route_map_model.js";
+
+const view = (gclass) => ({ stage: "main", gclass: gclass });
+
+/*  A config + index shaped like a small wattyzer-style app:
+ *  toolbar (brand + account dropdown), a primary menu with a submenu,
+ *  a second menu, and a route table with URL-only routes. */
+function make_input(extra)
+{
+    const config = {
+        toolbar: { items: [
+            { type: "brand", id: "brand", wordmark: "demo",
+              action: { type: "navigate", route: "/" } },
+            { id: "theme", name: "theme",
+              action: { type: "event", event: "EV_TOGGLE_THEME" } },
+            { type: "avatar", id: "user", name: "account",
+              action: { type: "dropdown", items: [
+                  { id: "sitemap", name: "site map",
+                    action: { type: "navigate", route: "/sitemap" } },
+                  { type: "divider" },
+                  { id: "logout", name: "logout",
+                    action: { type: "event", event: "EV_LOGOUT" } }
+              ] } }
+        ] },
+        menu: {
+            primary: { items: [
+                { id: "reports", name: "reports", route: "/reports",
+                  submenu: { items: [
+                      { id: "a", name: "a", route: "/reports/a" }
+                  ] } },
+                { id: "form", name: "form", route: "/form" }
+            ] },
+            footer: { items: [
+                { id: "legal", name: "legal", route: "/legal" }
+            ] }
+        }
+    };
+    const item_index = {
+        "/":          { item: null, target: view("C_HOME") },
+        "/reports":   { item: config.menu.primary.items[0], target: null },
+        "/reports/a": { item: null, target: view("C_REPORT_A") },
+        "/form":      { item: null, target: view("C_FORM") },
+        "/legal":     { item: null, target: view("C_LEGAL") },
+        "/sitemap":   { item: null,
+                        target: { kind: "action", event: "EV_OPEN_SITEMAP",
+                                  redirect: "back" } },
+        "/hidden":    { item: null, target: view("C_HIDDEN") }
+    };
+    return Object.assign({
+        config: config,
+        item_index: item_index,
+        sub_routes: {},
+        event_handlers: {},
+        current_route: ""
+    }, extra || {});
+}
+
+describe("build_nav_map", () => {
+    test("brand + toolbar in declaration order, dividers skipped", () => {
+        const m = build_nav_map(make_input());
+        expect(m.brand).toEqual({ label: "demo", route: "/" });
+        expect(m.toolbar.map(n => n.id)).toEqual(["theme", "user"]);
+        expect(m.toolbar[1].children.map(n => n.id))
+            .toEqual(["sitemap", "logout"]);
+    });
+
+    test("action-route item shows the event it fires", () => {
+        const m = build_nav_map(make_input());
+        const sitemap = m.toolbar[1].children[0];
+        expect(sitemap.route).toBe("/sitemap");
+        expect(sitemap.event).toBe("EV_OPEN_SITEMAP");
+    });
+
+    test("primary menu flat; other menus as labelled groups", () => {
+        const m = build_nav_map(make_input());
+        expect(m.nav.map(n => n.id)).toEqual(["reports", "form", "footer"]);
+        const footer = m.nav[2];
+        expect(footer.kind).toBe("group");
+        expect(footer.children.map(n => n.route)).toEqual(["/legal"]);
+    });
+
+    test("other: uncovered route-table routes only, in index order", () => {
+        const m = build_nav_map(make_input());
+        /*  "/" is brand-covered; "/sitemap" is dropdown-covered;
+         *  "/legal" is footer-covered → only "/hidden" is left. */
+        expect(m.other.map(n => n.route)).toEqual(["/hidden"]);
+        expect(m.other[0].gclass).toBe("C_HIDDEN");
+    });
+
+    test("dynamic submenu children merged by parent id", () => {
+        const input = make_input();
+        input.item_index["/reports/rt1"] = {
+            item: { id: "rt1", name: "runtime tab" },
+            parent_item: input.config.menu.primary.items[0],
+            target: view("C_RT")
+        };
+        const m = build_nav_map(input);
+        const reports = m.nav[0];
+        expect(reports.children.map(n => n.route))
+            .toEqual(["/reports/a", "/reports/rt1"]);
+        /*  ...and a dynamic child is covered, not duplicated in other. */
+        expect(m.other.map(n => n.route)).toEqual(["/hidden"]);
+    });
+
+    test("sub_routes enrich their base node (and count as covered)", () => {
+        const input = make_input({
+            sub_routes: { "/reports/a": [
+                { route: "/reports/a/x", label: "x" }
+            ] }
+        });
+        const m = build_nav_map(input);
+        const a = m.nav[0].children[0];
+        expect(a.children.map(n => n.route)).toEqual(["/reports/a/x"]);
+    });
+
+    test("event handlers stamp the implementing gclass", () => {
+        const input = make_input({
+            event_handlers: { "EV_LOGOUT": ["C_APP"] }
+        });
+        const m = build_nav_map(input);
+        const logout = m.toolbar[1].children[1];
+        expect(logout.gclass).toBe("C_APP");
+    });
+
+    test("current: exact route marked", () => {
+        const m = build_nav_map(make_input({ current_route: "/form" }));
+        const form = m.nav[1];
+        expect(form.current).toBe(true);
+    });
+
+    test("current: deep subpath marks the longest base node", () => {
+        const m = build_nav_map(
+            make_input({ current_route: "/reports/a/topic/42" }));
+        expect(m.nav[0].children[0].current).toBe(true);   /*  /reports/a  */
+        expect(m.nav[0].current).toBeUndefined();
+    });
+
+    test("current: the brand's own route is markable (it renders as root)", () => {
+        const m = build_nav_map(make_input({ current_route: "/" }));
+        expect(m.brand.current).toBe(true);
+    });
+
+    test("current: a menu item beats the brand on the same route", () => {
+        const input = make_input({ current_route: "/" });
+        input.config.menu.primary.items.push(
+            { id: "home", name: "home", route: "/" });
+        const m = build_nav_map(input);
+        expect(m.nav.find(n => n.id === "home").current).toBe(true);
+        expect(m.brand.current).toBeUndefined();
+    });
+
+    /*  yui_shell_set_sub_routes stores the view's array BY REFERENCE, so a
+     *  builder that splices those objects in and stamps `current` on one
+     *  leaves the mark on a view-owned object forever: the next build shows
+     *  a second "you are here" and the viewer scrolls to the stale one. */
+    test("sub-route contributions are cloned, never marked in place", () => {
+        const sub_routes = { "/reports": [
+            { id: "", label: "a", icon: "", route: "/reports/topic",
+              event: "", gclass: "C_TOPIC", kind: "route", children: [] }
+        ] };
+        const marked = (m) => {
+            const out = [];
+            const visit = (n) => {
+                if(n.current) {
+                    out.push(n.route);
+                }
+                (n.children || []).forEach(visit);
+            };
+            m.toolbar.forEach(visit);
+            m.nav.forEach(visit);
+            m.other.forEach(visit);
+            return out;
+        };
+
+        const first = build_nav_map(
+            make_input({ sub_routes: sub_routes, current_route: "/reports/topic" }));
+        expect(marked(first)).toEqual(["/reports/topic"]);
+        /*  the caller's own object was never touched  */
+        expect(sub_routes["/reports"][0].current).toBeUndefined();
+
+        const second = build_nav_map(
+            make_input({ sub_routes: sub_routes, current_route: "/form" }));
+        expect(marked(second)).toEqual(["/form"]);
+    });
+
+    test("current: at most one node, none when nothing matches", () => {
+        const m = build_nav_map(make_input({ current_route: "/nope" }));
+        const marked = [];
+        const visit = (n) => {
+            if(n.current) {
+                marked.push(n.route);
+            }
+            (n.children || []).forEach(visit);
+        };
+        m.toolbar.forEach(visit);
+        m.nav.forEach(visit);
+        m.other.forEach(visit);
+        expect(marked).toEqual([]);
+    });
+});

package/src/route_resolver.js

@@ -24,6 +24,29 @@
  *   - nothing matched                  → entry as found (may be
  *     null or a targetless submenu parent), subpath "".
  ************************************************************/
+/************************************************************
+ *  normalize_route — canonical form of a route: leading "/",
+ *  duplicate slashes collapsed, trailing slashes stripped
+ *  (root "/" stays "/").  Routes arrive from the outside
+ *  world (typed URLs, shared links, old bookmarks): "#/a/b/"
+ *  must resolve like "#/a/b" instead of missing the index
+ *  and falling into the unknown-route redirect.
+ ************************************************************/
+function normalize_route(route)
+{
+    if(!route) {
+        return "";
+    }
+    let s = String(route).replace(/\/{2,}/g, "/");
+    if(s.charAt(0) !== "/") {
+        s = "/" + s;
+    }
+    if(s.length > 1) {
+        s = s.replace(/\/+$/, "");
+    }
+    return s;
+}
+
 function resolve_route(item_index, route)
 {
     let entry = item_index[route];
@@ -50,4 +73,4 @@ function resolve_route(item_index, route)
     return { entry: entry, matched_route: matched_route, subpath: subpath };
 }
 
-export { resolve_route };
+export { resolve_route, normalize_route };

package/src/route_resolver.test.js

@@ -7,7 +7,7 @@
  *          All Rights Reserved.
  ***********************************************************************/
 import { describe, test, expect } from "vitest";
-import { resolve_route } from "./route_resolver.js";
+import { resolve_route, normalize_route } from "./route_resolver.js";
 
 /*  Minimal route table shaped like C_YUI_SHELL.priv.item_index. */
 function make_index() {
@@ -80,3 +80,42 @@ describe("resolve_route", () => {
         expect(r.entry.item.submenu).toBeTruthy();
     });
 });
+
+describe("normalize_route", () => {
+    test("already canonical → unchanged", () => {
+        expect(normalize_route("/a/b")).toBe("/a/b");
+    });
+
+    test("trailing slash stripped", () => {
+        expect(normalize_route("/a/b/")).toBe("/a/b");
+    });
+
+    test("multiple trailing slashes stripped", () => {
+        expect(normalize_route("/a/b///")).toBe("/a/b");
+    });
+
+    test("duplicate inner slashes collapsed", () => {
+        expect(normalize_route("//a///b")).toBe("/a/b");
+    });
+
+    test("missing leading slash added", () => {
+        expect(normalize_route("a/b")).toBe("/a/b");
+    });
+
+    test("root stays root", () => {
+        expect(normalize_route("/")).toBe("/");
+        expect(normalize_route("///")).toBe("/");
+    });
+
+    test("empty stays empty (caller decides the error)", () => {
+        expect(normalize_route("")).toBe("");
+        expect(normalize_route(null)).toBe("");
+    });
+
+    test("normalized trailing-slash route resolves like the clean one", () => {
+        const idx = make_index();
+        const r = resolve_route(idx, normalize_route("/monitoring/realtime/"));
+        expect(r.matched_route).toBe("/monitoring/realtime");
+        expect(r.subpath).toBe("");
+    });
+});

package/src/shell_modals.js

@@ -41,6 +41,8 @@ import {
 import {
     yui_shell_push_escape,
     yui_shell_pop_escape,
+    yui_shell_register_overlay,
+    yui_shell_overlay_dismissed,
 } from "./c_yui_shell.js";
 
 
@@ -52,7 +54,7 @@ function notification_layer(shell)
     if(!shell) {
         return null;
     }
-    let priv = gobj_read_attr(shell, "priv");
+    let priv = shell.priv;
     return priv && priv.layers && priv.layers.notification;
 }
 
@@ -61,7 +63,7 @@ function modal_layer(shell)
     if(!shell) {
         return null;
     }
-    let priv = gobj_read_attr(shell, "priv");
+    let priv = shell.priv;
     return priv && priv.layers && priv.layers.modal;
 }
 
@@ -75,7 +77,7 @@ export function yui_shell_popup_layer(shell)
     if(!shell) {
         return null;
     }
-    let priv = gobj_read_attr(shell, "priv");
+    let priv = shell.priv;
     return (priv && priv.layers && priv.layers.popup) || null;
 }
 
@@ -119,11 +121,11 @@ function show_notification(shell, kind, message, opts)
         ? {i18n: message}
         : {};
     let $note = createElement2(
-        ["div", {class: `notification yui-notification is-${kind} is-light`,
+        ["div", {class: `TOAST notification yui-notification is-${kind} is-light`,
                  role: kind === "danger" ? "alert" : "status"},
             [
-                ["button", {class: "delete", "aria-label": "close"}],
-                ["p", p_attrs, message]
+                ["button", {class: "TOAST_CLOSE delete", "aria-label": "close"}],
+                ["p", {...p_attrs, class: "TOAST_MSG"}, message]
             ]
         ]
     );
@@ -205,6 +207,14 @@ export function yui_shell_show_modal(shell, content, opts)
      *  history.back()), so gobj-ui stays routing-agnostic. */
     let dialog = !!(opts && opts.dialog);
     let title = (opts && opts.title) || "";
+    /*  Optional DATA half of the title (a topic/service name), never
+     *  translated, shown before `title`. Same contract as C_YUI_WINDOW's
+     *  `title_prefix`, and for the same reason: composing
+     *  `${topic} · ${t("keys")}` into `title` yields a string that is not
+     *  an i18n key, so it never re-translates. Split, only the kind half
+     *  carries a key. The separator is CSS — createElement2 trims text
+     *  nodes and would eat the spaces around it. */
+    let title_prefix = (opts && opts.title_prefix) || "";
 
     /*  The external Bulma `.modal-close is-large` sits at the
      *  top-right of the viewport, outside the content box.  Callers
@@ -214,37 +224,47 @@ export function yui_shell_show_modal(shell, content, opts)
     let with_close = !(opts && opts.with_close_button === false);
     let modal_children;
     if(dialog) {
-        let header = ["div", {class: "yui-dialog-header"}, [
-            ["button", {class: "yui-dialog-back", type: "button", "aria-label": "back"},
+        let header = ["div", {class: "MODAL_HEADER yui-dialog-header"}, [
+            ["button", {class: "MODAL_BACK yui-dialog-back", type: "button", "aria-label": "back"},
                 [["i", {class: "yi-arrow-left"}]]],
-            ["span", {class: "yui-dialog-title", i18n: title}, title],
-            ["button", {class: "yui-dialog-x", type: "button", "aria-label": "close"},
+            ["span", {class: "MODAL_TITLE yui-dialog-title"},
+                (title_prefix ? [["span", {class: "MODAL_TITLE_PREFIX"}, title_prefix]] : [])
+                    .concat(title
+                        ? [["span", {class: "MODAL_TITLE_KIND", i18n: title}, title]]
+                        : [])],
+            ["button", {class: "MODAL_CLOSE yui-dialog-x", type: "button", "aria-label": "close"},
                 [["i", {class: "yi-xmark"}]]],
         ]];
-        let body = ["div", {class: "yui-dialog-body"}, inner ? [inner] : []];
+        let body = ["div", {class: "MODAL_BODY yui-dialog-body"}, inner ? [inner] : []];
         modal_children = [
-            ["div", {class: "modal-background"}],
-            ["div", {class: "modal-content yui-dialog-content"}, [header, body]]
+            ["div", {class: "MODAL_BACKDROP modal-background"}],
+            ["div", {class: "MODAL_CONTENT modal-content yui-dialog-content"}, [header, body]]
         ];
         /*  The header X replaces the external Bulma close button. */
         with_close = false;
     } else {
         modal_children = [
-            ["div", {class: "modal-background"}],
-            ["div", {class: "modal-content"},
+            ["div", {class: "MODAL_BACKDROP modal-background"}],
+            ["div", {class: "MODAL_CONTENT modal-content"},
                 inner ? [inner] : []
             ]
         ];
         if(with_close) {
             modal_children.push(
-                ["button", {class: "modal-close is-large",
+                ["button", {class: "MODAL_CLOSE modal-close is-large",
                             "aria-label": "close"}]
             );
         }
     }
 
+    /*  `opts.logical_class`: the CALLER's UPPER_SNAKE name for THIS modal
+     *  (e.g. TRANGER_KEYS_SHEET). Every modal shares the MODAL block names,
+     *  only this tells one popup from another in the Inspector or a selector. */
+    let logical = (opts && opts.logical_class) || "";
+
     let $modal = createElement2(
-        ["div", {class: "modal yui-modal" + (dialog ? " yui-dialog" : "") + " is-active",
+        ["div", {class: "MODAL" + (logical ? " " + logical : "") +
+                        " modal yui-modal" + (dialog ? " yui-dialog" : "") + " is-active",
                  role: "dialog", "aria-modal": "true"},
             modal_children
         ]
@@ -261,10 +281,13 @@ export function yui_shell_show_modal(shell, content, opts)
     maybe_apply_translator($modal, opts);
 
     let closed = false;
-    let close_fn = null;
     let release_focus = null;
+    let overlay = null;
+    let escape_handler = null;
 
-    let close = function() {
+    /*  Unconditional teardown. The returned close() maps here: a
+     *  programmatic close always closes, bypassing before_close. */
+    let do_close = function() {
         if(closed) {
             return;
         }
@@ -273,13 +296,16 @@ export function yui_shell_show_modal(shell, content, opts)
             release_focus();
             release_focus = null;
         }
-        if(close_fn) {
-            yui_shell_pop_escape(shell, close_fn);
-            close_fn = null;
+        if(escape_handler) {
+            yui_shell_pop_escape(shell, escape_handler);
+            escape_handler = null;
         }
         if($modal.parentNode) {
             $modal.parentNode.removeChild($modal);
         }
+        /*  Retire the browser-history entry (no-op when Back triggered
+         *  this close — the entry is already gone). */
+        yui_shell_overlay_dismissed(shell, overlay);
         if(opts && typeof opts.on_close === "function") {
             try {
                 opts.on_close();
@@ -288,9 +314,50 @@ export function yui_shell_show_modal(shell, content, opts)
             }
         }
     };
-    close_fn = close;
 
-    yui_shell_push_escape(shell, "modal", close);
+    /*  `opts.before_close`: a guard consulted on EVERY user-driven dismiss
+     *  (Escape, backdrop, the X / back-arrow, browser Back). Return false to
+     *  VETO — the modal stays up and the caller takes over (e.g. an
+     *  unsaved-changes prompt that calls close() itself on confirm). Return
+     *  true/undefined to let it close. Absent guard ⇒ always closes, so
+     *  existing callers are unaffected. */
+    let guarded_close = function(on_veto) {
+        if(closed) {
+            return;
+        }
+        let allow = true;
+        if(opts && typeof opts.before_close === "function") {
+            try {
+                allow = opts.before_close();
+            } catch(e) {
+                log_warning(`yui_shell_show_modal: before_close threw: ${e}`);
+                allow = true;
+            }
+        }
+        if(allow === false) {
+            if(typeof on_veto === "function") {
+                on_veto();
+            }
+            return;
+        }
+        do_close();
+    };
+    let request_close = function() {
+        guarded_close(null);
+    };
+    /*  Browser Back already consumed the history entry; if the guard vetoes,
+     *  re-arm a fresh entry so a later Back still targets this modal. */
+    let on_back = function() {
+        guarded_close(function() {
+            overlay = yui_shell_register_overlay(shell, on_back);
+        });
+    };
+
+    escape_handler = request_close;
+    yui_shell_push_escape(shell, "modal", request_close);
+    /*  Browser Back closes the top-most modal (see overlay history in
+     *  c_yui_shell.js).  Null when history integration is off. */
+    overlay = yui_shell_register_overlay(shell, on_back);
     /*  Trap on $modal (not on .modal-content) so the .modal-close
      *  button — rendered as a SIBLING of .modal-content — is
      *  reachable via Tab.  Without this, Tab/Shift+Tab can only
@@ -299,24 +366,24 @@ export function yui_shell_show_modal(shell, content, opts)
     release_focus = activate_focus_trap_on($modal);
 
     if((opts == null || opts.dismiss_on_background !== false)) {
-        $modal.querySelector(".modal-background").addEventListener("click", close);
+        $modal.querySelector(".modal-background").addEventListener("click", request_close);
     }
     let $close_btn = $modal.querySelector(".modal-close");
     if($close_btn) {
-        $close_btn.addEventListener("click", close);
+        $close_btn.addEventListener("click", request_close);
     }
     if(dialog) {
         let $back = $modal.querySelector(".yui-dialog-back");
         if($back) {
-            $back.addEventListener("click", close);
+            $back.addEventListener("click", request_close);
         }
         let $x = $modal.querySelector(".yui-dialog-x");
         if($x) {
-            $x.addEventListener("click", close);
+            $x.addEventListener("click", request_close);
         }
     }
 
-    return { close };
+    return { close: do_close };
 }
 
 
@@ -361,11 +428,11 @@ function build_dialog(shell, message, buttons, opts)
     let icon = CONFIRM_TYPE_ICONS[type] || CONFIRM_TYPE_ICONS["question"];
 
     let $body_children = (typeof message === "string")
-        ? [["p", {class: "yui-confirm-msg", i18n: message}, message]]
+        ? [["p", {class: "CONFIRM_MSG yui-confirm-msg", i18n: message}, message]]
         : [message];
 
     let $footer_children = buttons.map(b => {
-        let cls = "button px-5";
+        let cls = "CONFIRM_BTN button px-5";
         if(b.kind === "primary") {
             cls += " is-link";
         } else if(b.kind === "danger") {
@@ -380,29 +447,33 @@ function build_dialog(shell, message, buttons, opts)
     });
 
     let $card_children = [
-        ["div", {class: "yui-confirm-icon"},
+        ["div", {class: "CONFIRM_ICON yui-confirm-icon"},
             [["i", {class: icon, "aria-hidden": "true"}]]
         ]
     ];
     if(!empty_string(title)) {
         $card_children.push(
-            ["p", {class: "yui-confirm-title has-text-centered",
+            ["p", {class: "CONFIRM_TITLE yui-confirm-title has-text-centered",
                    i18n: title}, title]
         );
     }
     $card_children.push(
-        ["button", {class: "delete yui-confirm-x", "aria-label": "close"}],
-        ["section", {class: "modal-card-body has-text-centered"},
+        ["button", {class: "CONFIRM_CLOSE delete yui-confirm-x", "aria-label": "close"}],
+        ["section", {class: "CONFIRM_BODY modal-card-body has-text-centered"},
             $body_children],
-        ["footer", {class: "modal-card-foot"}, $footer_children]
+        ["footer", {class: "CONFIRM_FOOT modal-card-foot"}, $footer_children]
     );
 
+    /*  Caller's own UPPER_SNAKE name for THIS confirm, same contract as
+     *  yui_shell_show_modal's `logical_class`. */
+    let logical = (opts && opts.logical_class) ? " " + opts.logical_class : "";
+
     let $modal = createElement2(
-        ["div", {class: `modal yui-modal yui-confirm is-active is-${type}`,
+        ["div", {class: `CONFIRM${logical} modal yui-modal yui-confirm is-active is-${type}`,
                  role: "dialog", "aria-modal": "true"},
             [
-                ["div", {class: "modal-background"}],
-                ["div", {class: "modal-card"}, $card_children]
+                ["div", {class: "CONFIRM_BACKDROP modal-background"}],
+                ["div", {class: "CONFIRM_CARD modal-card"}, $card_children]
             ]
         ]
     );
@@ -413,6 +484,7 @@ function build_dialog(shell, message, buttons, opts)
         let resolved = false;
         let close_fn = null;
         let release_focus = null;
+        let overlay = null;
 
         let close = function(value) {
             if(resolved) {
@@ -430,11 +502,17 @@ function build_dialog(shell, message, buttons, opts)
             if($modal.parentNode) {
                 $modal.parentNode.removeChild($modal);
             }
+            /*  Retire the browser-history entry (no-op when Back
+             *  triggered this close). */
+            yui_shell_overlay_dismissed(shell, overlay);
             resolve(value);
         };
         close_fn = () => close(dismiss_value);
 
         yui_shell_push_escape(shell, "modal", close_fn);
+        /*  Browser Back dismisses the dialog with the safe-default value,
+         *  exactly like Escape. */
+        overlay = yui_shell_register_overlay(shell, close_fn);
         release_focus = activate_focus_trap_on(
             $modal.querySelector(".modal-card")
         );