@yuneta/gobj-ui 1.0.1 → 2.2.0

package/src/pager_helpers.js

@@ -0,0 +1,138 @@
+/***********************************************************************
+ *          pager_helpers.js
+ *
+ *      Pure (DOM-free) navigation-stack logic for C_YUI_PAGER.
+ *      Kept apart so it is unit-testable with `node --test`
+ *      (same split as shell_toolbar_helpers.js).
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/***************************************************************
+ *  A stack entry is a plain object:
+ *      { id, title, discardable }
+ *  The DOM node bound to it is tracked by the gclass, never here.
+ ***************************************************************/
+
+/***************************************************************
+ *  Push an entry, returning a NEW stack (never mutates).
+ ***************************************************************/
+function pager_push(stack, entry)
+{
+    return stack.concat([entry]);
+}
+
+/***************************************************************
+ *  Pop the top entry.
+ *  Returns { stack, popped } or null when the stack is empty.
+ ***************************************************************/
+function pager_pop(stack)
+{
+    if(stack.length === 0) {
+        return null;
+    }
+    return {
+        stack:  stack.slice(0, -1),
+        popped: stack[stack.length - 1],
+    };
+}
+
+/***************************************************************
+ *  Replace the top entry (same depth).
+ *  Returns { stack, replaced }; on an empty stack it just pushes.
+ ***************************************************************/
+function pager_replace(stack, entry)
+{
+    if(stack.length === 0) {
+        return { stack: [entry], replaced: null };
+    }
+    return {
+        stack:    stack.slice(0, -1).concat([entry]),
+        replaced: stack[stack.length - 1],
+    };
+}
+
+/***************************************************************
+ *  Top entry or null.
+ ***************************************************************/
+function pager_top(stack)
+{
+    if(stack.length === 0) {
+        return null;
+    }
+    return stack[stack.length - 1];
+}
+
+/***************************************************************
+ *  What the header chrome must show for the current stack.
+ *
+ *      opts = { root_title, back_on_root, with_discard }
+ *
+ *  Returns { title, show_back, back_kind, show_discard, depth }.
+ *  back_kind:
+ *    "back"  — a deeper page: the affordance pops (icon: arrow)
+ *    "close" — the root page with back_on_root: it exits/closes
+ *              (icon: a cross, shown INSIDE the popup)
+ *    "none"  — root page, back_on_root false: no affordance
+ ***************************************************************/
+function pager_header_model(stack, opts)
+{
+    opts = opts || {};
+    let depth = stack.length;
+    let top   = pager_top(stack);
+
+    let title;
+    if(top && typeof top.title === "string" && top.title.length > 0) {
+        title = top.title;
+    } else {
+        title = opts.root_title || "";
+    }
+
+    let back_kind;
+    if(depth > 1) {
+        back_kind = "back";
+    } else if(opts.back_on_root) {
+        back_kind = "close";
+    } else {
+        back_kind = "none";
+    }
+
+    let show_discard = !!opts.with_discard && !!(top && top.discardable);
+
+    return {
+        title:        title,
+        show_back:    back_kind !== "none",
+        back_kind:    back_kind,
+        show_discard: show_discard,
+        depth:        depth,
+    };
+}
+
+/***************************************************************
+ *  Resolve what the "back" affordance must do.
+ *
+ *  Returns one of:
+ *      { type: "pop" }   — pop the top page
+ *      { type: "exit" }  — leave the pager (host should close)
+ *      { type: "noop" }  — nothing (root, back_on_root === false)
+ ***************************************************************/
+function pager_back_action(stack, back_on_root)
+{
+    if(stack.length > 1) {
+        return { type: "pop" };
+    }
+    if(back_on_root) {
+        return { type: "exit" };
+    }
+    return { type: "noop" };
+}
+
+export {
+    pager_push,
+    pager_pop,
+    pager_replace,
+    pager_top,
+    pager_header_model,
+    pager_back_action,
+};

package/src/pager_helpers.test.js

@@ -0,0 +1,140 @@
+/***********************************************************************
+ *          pager_helpers.test.mjs
+ *
+ *      Unit tests for the pure navigation-stack logic of C_YUI_PAGER.
+ *      Run with: node --test tests/
+ ***********************************************************************/
+import { test, expect } from "vitest";
+import {
+    pager_push,
+    pager_pop,
+    pager_replace,
+    pager_top,
+    pager_header_model,
+    pager_back_action,
+} from "./pager_helpers.js";
+
+
+/*============================================================
+ *      pager_push / pager_pop / pager_replace are pure
+ *============================================================*/
+test("push does not mutate the input stack", () => {
+    const s0 = [];
+    const s1 = pager_push(s0, { id: "a", title: "A" });
+    expect(s0.length).toBe(0);
+    expect(s1.length).toBe(1);
+    expect(s1[0].id).toBe("a");
+});
+
+test("pop returns popped entry and a shorter new stack", () => {
+    const s = pager_push(pager_push([], { id: "a" }), { id: "b" });
+    const r = pager_pop(s);
+    expect(r.popped.id).toBe("b");
+    expect(r.stack.length).toBe(1);
+    expect(s.length).toBe(2); // original untouched
+});
+
+test("pop on empty stack returns null", () => {
+    expect(pager_pop([])).toBe(null);
+});
+
+test("replace swaps the top, keeps depth, reports replaced", () => {
+    const s = pager_push(pager_push([], { id: "a" }), { id: "b" });
+    const r = pager_replace(s, { id: "b2" });
+    expect(r.stack.length).toBe(2);
+    expect(r.stack[1].id).toBe("b2");
+    expect(r.replaced.id).toBe("b");
+});
+
+test("replace on empty stack just pushes", () => {
+    const r = pager_replace([], { id: "x" });
+    expect(r.stack.length).toBe(1);
+    expect(r.replaced).toBe(null);
+});
+
+test("pager_top returns the last entry or null", () => {
+    expect(pager_top([])).toBe(null);
+    expect(pager_top([{ id: "a" }, { id: "b" }]).id).toBe("b");
+});
+
+
+/*============================================================
+ *      pager_header_model
+ *============================================================*/
+test("root page: title falls back to root_title", () => {
+    const m = pager_header_model([{ id: "root", title: "" }], {
+        root_title: "Preferences",
+        back_on_root: true,
+    });
+    expect(m.title).toBe("Preferences");
+    expect(m.depth).toBe(1);
+});
+
+test("root page: show_back follows back_on_root", () => {
+    expect(pager_header_model([{ id: "r" }], { back_on_root: true }).show_back).toBe(true);
+    expect(pager_header_model([{ id: "r" }], { back_on_root: false }).show_back).toBe(false);
+});
+
+test("deep page: back always shown, title from top entry", () => {
+    const m = pager_header_model(
+        [{ id: "r", title: "Root" }, { id: "lang", title: "Language" }],
+        { root_title: "Root", back_on_root: false }
+    );
+    expect(m.show_back).toBe(true);
+    expect(m.title).toBe("Language");
+    expect(m.depth).toBe(2);
+});
+
+test("discard shown only when with_discard AND top.discardable", () => {
+    const top_yes = [{ id: "p", discardable: true }];
+    const top_no  = [{ id: "p", discardable: false }];
+    expect(pager_header_model(top_yes, { with_discard: true }).show_discard).toBe(true);
+    expect(pager_header_model(top_yes, { with_discard: false }).show_discard).toBe(false);
+    expect(pager_header_model(top_no, { with_discard: true }).show_discard).toBe(false);
+});
+
+test("empty stack: title is root_title, depth 0", () => {
+    const m = pager_header_model([], { root_title: "X" });
+    expect(m.title).toBe("X");
+    expect(m.depth).toBe(0);
+});
+
+test("back_kind: root+back_on_root -> 'close'", () => {
+    const m = pager_header_model([{ id: "r" }], { back_on_root: true });
+    expect(m.back_kind).toBe("close");
+    expect(m.show_back).toBe(true);
+});
+
+test("back_kind: root without back_on_root -> 'none'", () => {
+    const m = pager_header_model([{ id: "r" }], { back_on_root: false });
+    expect(m.back_kind).toBe("none");
+    expect(m.show_back).toBe(false);
+});
+
+test("back_kind: deeper page -> 'back'", () => {
+    const m = pager_header_model(
+        [{ id: "r" }, { id: "lang" }], { back_on_root: true }
+    );
+    expect(m.back_kind).toBe("back");
+    expect(m.show_back).toBe(true);
+});
+
+
+/*============================================================
+ *      pager_back_action
+ *============================================================*/
+test("back with depth>1 -> pop", () => {
+    expect(pager_back_action([{ id: "a" }, { id: "b" }], false)).toEqual({ type: "pop" });
+});
+
+test("back at root with back_on_root -> exit", () => {
+    expect(pager_back_action([{ id: "a" }], true)).toEqual({ type: "exit" });
+});
+
+test("back at root without back_on_root -> noop", () => {
+    expect(pager_back_action([{ id: "a" }], false)).toEqual({ type: "noop" });
+});
+
+test("back on empty stack without back_on_root -> noop", () => {
+    expect(pager_back_action([], false)).toEqual({ type: "noop" });
+});

package/src/route_resolver.js

@@ -0,0 +1,53 @@
+/***********************************************************************
+ *          route_resolver.js
+ *
+ *          Pure route resolver for C_YUI_SHELL (no gobj, no DOM,
+ *          no imports) — kept apart so it is trivially unit-testable.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/************************************************************
+ *  resolve_route — given the route table (`item_index`) and a
+ *  requested route, return { entry, matched_route, subpath }:
+ *
+ *   - exact hit with a target          → that entry, subpath "".
+ *   - no exact target → walk ancestors (`/a/b/c` → `/a/b`),
+ *     return the nearest ancestor that HAS a target plus the
+ *     trailing `subpath` ("c", or "b/c"); lets a declared view
+ *     own a deeper, dynamic, deep-linkable level without
+ *     declaring runtime-only segments in app_config.
+ *   - root `/` is NEVER an ancestor catch-all (it only matches
+ *     exactly): otherwise every typo route would silently mount
+ *     the home view and the unknown-route diagnostic would die.
+ *   - nothing matched                  → entry as found (may be
+ *     null or a targetless submenu parent), subpath "".
+ ************************************************************/
+function resolve_route(item_index, route)
+{
+    let entry = item_index[route];
+    let matched_route = route;
+    let subpath = "";
+
+    if(!entry || !entry.target) {
+        let parts = route.split("/").filter(s => s.length > 0);
+        while(parts.length > 0 && (!entry || !entry.target)) {
+            parts.pop();
+            let cand = "/" + parts.join("/");
+            if(cand === "/") {
+                break;
+            }
+            let e = item_index[cand];
+            if(e && e.target) {
+                entry = e;
+                matched_route = cand;
+                subpath = route.slice(cand.length).replace(/^\/+/, "");
+            }
+        }
+    }
+
+    return { entry: entry, matched_route: matched_route, subpath: subpath };
+}
+
+export { resolve_route };

package/src/route_resolver.test.js

@@ -0,0 +1,82 @@
+/***********************************************************************
+ *          route_resolver.test.js
+ *
+ *          Unit tests for the pure shell route resolver.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import { describe, test, expect } from "vitest";
+import { resolve_route } from "./route_resolver.js";
+
+/*  Minimal route table shaped like C_YUI_SHELL.priv.item_index. */
+function make_index() {
+    const view = (gclass) => ({ stage: "main", gclass: gclass });
+    return {
+        "/":                 { item: null, target: view("C_WZ_VIEW") },
+        "/monitoring/realtime": { item: null, target: view("C_WZ_MONITORING") },
+        "/system":           { item: { submenu: { items: [] } }, target: null },
+        "/system/db/wattyzer": { item: null, target: view("C_WZ_TREEDB") },
+        "/user/preference":  { item: null, target: view("C_WZ_PREFERENCES") },
+        "/user/logout":      { item: null, target: { kind: "action", event: "EV_LOGOUT" } },
+    };
+}
+
+describe("resolve_route", () => {
+    const idx = make_index();
+
+    test("exact view hit → entry, no subpath", () => {
+        const r = resolve_route(idx, "/monitoring/realtime");
+        expect(r.matched_route).toBe("/monitoring/realtime");
+        expect(r.subpath).toBe("");
+        expect(r.entry.target.gclass).toBe("C_WZ_MONITORING");
+    });
+
+    test("exact root '/' matches exactly (not via walk)", () => {
+        const r = resolve_route(idx, "/");
+        expect(r.matched_route).toBe("/");
+        expect(r.subpath).toBe("");
+        expect(r.entry.target.gclass).toBe("C_WZ_VIEW");
+    });
+
+    test("3rd level → nearest declared ancestor + subpath", () => {
+        const r = resolve_route(idx, "/user/preference/language");
+        expect(r.matched_route).toBe("/user/preference");
+        expect(r.subpath).toBe("language");
+        expect(r.entry.target.gclass).toBe("C_WZ_PREFERENCES");
+    });
+
+    test("deeper dynamic tail is preserved whole", () => {
+        const r = resolve_route(idx, "/system/db/wattyzer/topic/42");
+        expect(r.matched_route).toBe("/system/db/wattyzer");
+        expect(r.subpath).toBe("topic/42");
+    });
+
+    test("action route resolves exactly, kind untouched", () => {
+        const r = resolve_route(idx, "/user/logout");
+        expect(r.matched_route).toBe("/user/logout");
+        expect(r.entry.target.kind).toBe("action");
+        expect(r.entry.target.event).toBe("EV_LOGOUT");
+    });
+
+    test("root is NOT an ancestor catch-all → unknown stays unknown", () => {
+        const r = resolve_route(idx, "/zzz");
+        expect(r.matched_route).toBe("/zzz");
+        expect(r.subpath).toBe("");
+        expect(r.entry).toBeUndefined();        /*  caller → default route */
+    });
+
+    test("unknown deep route never collapses onto '/'", () => {
+        const r = resolve_route(idx, "/nope/deeper/still");
+        expect(r.matched_route).toBe("/nope/deeper/still");
+        expect(r.entry).toBeUndefined();
+    });
+
+    test("targetless submenu parent is returned as-is (subpath empty)", () => {
+        const r = resolve_route(idx, "/system");
+        expect(r.matched_route).toBe("/system");
+        expect(r.subpath).toBe("");
+        expect(r.entry.target).toBeNull();
+        expect(r.entry.item.submenu).toBeTruthy();
+    });
+});

package/src/shell_focus_trap.js

@@ -0,0 +1,123 @@
+/***********************************************************************
+ *          shell_focus_trap.js
+ *
+ *      Generic focus-trap helper used by C_YUI_SHELL for drawers,
+ *      modals and any other overlay that must capture keyboard
+ *      navigation while open.
+ *
+ *      Usage:
+ *          let release = activate_focus_trap_on($panel);
+ *          // ... when the overlay closes:
+ *          release();
+ *
+ *      The trap:
+ *          - captures Tab / Shift+Tab so focus cycles inside $panel,
+ *          - moves focus to the first focusable child on activate,
+ *          - restores focus to whatever element had it before
+ *            activation when release() runs.
+ *
+ *      Pure module — no gobj / Yuneta dependencies.  The optional
+ *      second argument lets callers inject a mock document object
+ *      for unit tests.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/*  Selector matching the elements typically considered focusable.
+ *  Kept conservative: items that are explicitly removed from the tab
+ *  order (`tabindex="-1"`) are excluded; everything else is in. */
+export const FOCUSABLE_SELECTOR =
+    "a[href], button:not([disabled]), input:not([disabled])," +
+    " select:not([disabled]), textarea:not([disabled])," +
+    " [tabindex]:not([tabindex=\"-1\"])";
+
+
+/*  Module-local LIFO stack of active traps.  Multiple overlays can
+ *  be open simultaneously (modal over drawer, popup over modal, …)
+ *  and each registers its own document-level keydown listener.
+ *  Without arbitration every Tab fires every listener, which forces
+ *  focus to the deepest trap's first/last on every press and makes
+ *  middle elements unreachable.  We keep one stack and only run the
+ *  topmost trap; the rest short-circuit. */
+const __trap_stack__ = [];
+
+
+/***************************************************************
+ *  Activate the focus-trap on $panel.
+ *
+ *  Returns a `release` function that must be called to tear the
+ *  trap down when the overlay closes.  Calling release() multiple
+ *  times is safe (becomes a no-op after the first call).
+ *
+ *  `doc` defaults to globalThis.document; pass a stub for tests.
+ ***************************************************************/
+export function activate_focus_trap_on($panel, doc)
+{
+    if(!doc) {
+        doc = globalThis.document;
+    }
+    if(!$panel || !doc) {
+        return function noop() {};
+    }
+
+    let saved = doc.activeElement || null;
+    let released = false;
+
+    let trap = function(ev) {
+        if(ev.key !== "Tab" && ev.keyCode !== 9) {
+            return;
+        }
+        /*  LIFO arbitration: only the topmost active trap acts.
+         *  Earlier-registered listeners fire too (capture phase),
+         *  but they short-circuit unless they own the top of the
+         *  stack. */
+        if(__trap_stack__[__trap_stack__.length - 1] !== trap) {
+            return;
+        }
+        let nodes = $panel.querySelectorAll(FOCUSABLE_SELECTOR);
+        if(nodes.length === 0) {
+            return;
+        }
+        let first = nodes[0];
+        let last  = nodes[nodes.length - 1];
+        let inside = $panel.contains(doc.activeElement);
+
+        if(ev.shiftKey) {
+            if(!inside || doc.activeElement === first) {
+                last.focus();
+                ev.preventDefault();
+            }
+        } else {
+            if(!inside || doc.activeElement === last) {
+                first.focus();
+                ev.preventDefault();
+            }
+        }
+    };
+    doc.addEventListener("keydown", trap, true);
+    __trap_stack__.push(trap);
+
+    /*  Move focus to the first focusable child of the panel. */
+    let firstFocusable = $panel.querySelector(FOCUSABLE_SELECTOR);
+    if(firstFocusable && typeof firstFocusable.focus === "function") {
+        firstFocusable.focus();
+    }
+
+    return function release_focus_trap() {
+        if(released) {
+            return;
+        }
+        released = true;
+        doc.removeEventListener("keydown", trap, true);
+        let idx = __trap_stack__.indexOf(trap);
+        if(idx >= 0) {
+            __trap_stack__.splice(idx, 1);
+        }
+        if(saved && typeof saved.focus === "function" &&
+           (!doc.body || !doc.body.contains || doc.body.contains(saved)))
+        {
+            saved.focus();
+        }
+    };
+}