@yuneta/gobj-ui 1.0.1 → 2.2.0

package/src/shell_modals.js

@@ -0,0 +1,445 @@
+/***********************************************************************
+ *          shell_modals.js
+ *
+ *      Modal / notification API on top of the layers C_YUI_SHELL
+ *      already creates (`priv.layers.notification`,
+ *      `priv.layers.modal`).  Naming convention:
+ *
+ *          yui_shell_show_*     — non-blocking notifications/modal
+ *          yui_shell_confirm_*  — blocking dialog, returns Promise
+ *
+ *      Bulma `.notification` / `.modal-card` markup is reused
+ *      verbatim so apps importing Bulma get the visual styling for
+ *      free.
+ *
+ *      Every blocking dialog and every modal pushes a close handler
+ *      onto the shell's Escape priority chain (see
+ *      yui_shell_push_escape / yui_shell_pop_escape) so Escape
+ *      closes the topmost overlay only.
+ *
+ *      The legacy display_* / get_yes* helpers in c_yui_main.js are
+ *      NOT changed — apps that ride on the legacy shell keep using
+ *      them (see SHELL.md §10 drift policy).
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+/* global document */
+
+import {
+    gobj_read_attr,
+    createElement2,
+    refresh_language,
+    empty_string,
+    log_warning,
+} from "@yuneta/gobj-js";
+
+import {
+    activate_focus_trap_on,
+} from "./shell_focus_trap.js";
+
+import {
+    yui_shell_push_escape,
+    yui_shell_pop_escape,
+} from "./c_yui_shell.js";
+
+
+/***************************************************************
+ *              Layer accessors
+ ***************************************************************/
+function notification_layer(shell)
+{
+    let priv = gobj_read_attr(shell, "priv");
+    return priv && priv.layers && priv.layers.notification;
+}
+
+function modal_layer(shell)
+{
+    let priv = gobj_read_attr(shell, "priv");
+    return priv && priv.layers && priv.layers.modal;
+}
+
+
+/***************************************************************
+ *  i18n bridge:
+ *      - `text` is rendered as the canonical English key.
+ *      - The hosting element is tagged with `data-i18n="<key>"`,
+ *        so a later `refresh_language(shell.$container, t)` call
+ *        retranslates the modal even if it was created BEFORE the
+ *        language was switched.
+ *      - If `opts.t` is a function, the helper translates the
+ *        node right after creating it — so a modal opened AFTER
+ *        the user has already toggled to ES renders in ES on the
+ *        first frame, not the canonical English key.
+ ***************************************************************/
+function maybe_apply_translator($node, opts)
+{
+    if(opts && typeof opts.t === "function") {
+        refresh_language($node, opts.t);
+    }
+}
+
+
+/***************************************************************
+ *              Notifications (Bulma .notification)
+ *
+ *      Non-blocking, auto-dismiss after `opts.timeout` ms (default
+ *      5000).  `opts.timeout = 0` disables auto-dismiss.
+ *      Returns `{ close() }` so callers can dismiss programmatically.
+ ***************************************************************/
+function show_notification(shell, kind, message, opts)
+{
+    let $layer = notification_layer(shell);
+    if(!$layer) {
+        log_warning("yui_shell_show_*: shell has no notification layer");
+        return { close: () => {} };
+    }
+
+    let p_attrs = (typeof message === "string")
+        ? {i18n: message}
+        : {};
+    let $note = createElement2(
+        ["div", {class: `notification yui-notification is-${kind} is-light`,
+                 role: kind === "danger" ? "alert" : "status"},
+            [
+                ["button", {class: "delete", "aria-label": "close"}],
+                ["p", p_attrs, message]
+            ]
+        ]
+    );
+    $layer.appendChild($note);
+    maybe_apply_translator($note, opts);
+
+    let timeout_id = null;
+    let closed = false;
+
+    let close = function() {
+        if(closed) {
+            return;
+        }
+        closed = true;
+        if(timeout_id) {
+            clearTimeout(timeout_id);
+            timeout_id = null;
+        }
+        if($note.parentNode) {
+            $note.parentNode.removeChild($note);
+        }
+    };
+
+    let $del = $note.querySelector(".delete");
+    if($del) {
+        $del.addEventListener("click", close);
+    }
+
+    let timeout = (opts && opts.timeout != null) ? opts.timeout : 5000;
+    if(timeout > 0) {
+        timeout_id = setTimeout(close, timeout);
+    }
+
+    return { close };
+}
+
+
+export function yui_shell_show_info(shell, message, opts)
+{
+    return show_notification(shell, "info", message, opts);
+}
+export function yui_shell_show_warning(shell, message, opts)
+{
+    return show_notification(shell, "warning", message, opts);
+}
+export function yui_shell_show_error(shell, message, opts)
+{
+    return show_notification(shell, "danger", message, opts);
+}
+
+
+/***************************************************************
+ *              Modal (Bulma .modal — non-blocking)
+ *
+ *      Drops a Bulma `.modal-content` overlay into the modal layer.
+ *      `content` may be a string (rendered inside a Bulma .box) or
+ *      an HTMLElement (rendered as-is).  Returns `{ close() }`.
+ *      The caller decides when to dismiss; click on background,
+ *      the `.modal-close` button, or `Escape` also close it.
+ ***************************************************************/
+export function yui_shell_show_modal(shell, content, opts)
+{
+    let $layer = modal_layer(shell);
+    if(!$layer) {
+        log_warning("yui_shell_show_modal: shell has no modal layer");
+        return { close: () => {} };
+    }
+
+    let inner = (typeof content === "string")
+        ? ["div", {class: "box"}, [["p", {i18n: content}, content]]]
+        : null;
+
+    /*  Adaptive DIALOG mode (`opts.dialog: true`): the standardized
+     *  "single window / popup" chrome — a centered card with the close X
+     *  at the top-right on desktop, and a full-screen sheet with a back
+     *  arrow at the top-left on mobile. A header bar carries `opts.title`
+     *  and BOTH dismiss controls; CSS shows the right one per breakpoint.
+     *  Both call close() — the app's on_close decides navigation (usually
+     *  history.back()), so gobj-ui stays routing-agnostic. */
+    let dialog = !!(opts && opts.dialog);
+    let title = (opts && opts.title) || "";
+
+    /*  The external Bulma `.modal-close is-large` sits at the
+     *  top-right of the viewport, outside the content box.  Callers
+     *  whose content provides its own in-box close (e.g. a
+     *  C_YUI_PAGER header) pass `with_close_button: false` to omit
+     *  it; Escape and the backdrop still close the modal. */
+    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"},
+                [["i", {class: "yi-arrow-left"}]]],
+            ["span", {class: "yui-dialog-title", i18n: title}, title],
+            ["button", {class: "yui-dialog-x", type: "button", "aria-label": "close"},
+                [["i", {class: "yi-xmark"}]]],
+        ]];
+        let body = ["div", {class: "yui-dialog-body"}, inner ? [inner] : []];
+        modal_children = [
+            ["div", {class: "modal-background"}],
+            ["div", {class: "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"},
+                inner ? [inner] : []
+            ]
+        ];
+        if(with_close) {
+            modal_children.push(
+                ["button", {class: "modal-close is-large",
+                            "aria-label": "close"}]
+            );
+        }
+    }
+
+    let $modal = createElement2(
+        ["div", {class: "modal yui-modal" + (dialog ? " yui-dialog" : "") + " is-active",
+                 role: "dialog", "aria-modal": "true"},
+            modal_children
+        ]
+    );
+    $layer.appendChild($modal);
+
+    if(!inner && content && typeof content.appendChild !== "undefined") {
+        let $content = dialog
+            ? $modal.querySelector(".yui-dialog-body")
+            : $modal.querySelector(".modal-content");
+        $content.appendChild(content);
+    }
+
+    maybe_apply_translator($modal, opts);
+
+    let closed = false;
+    let close_fn = null;
+    let release_focus = null;
+
+    let close = function() {
+        if(closed) {
+            return;
+        }
+        closed = true;
+        if(release_focus) {
+            release_focus();
+            release_focus = null;
+        }
+        if(close_fn) {
+            yui_shell_pop_escape(shell, close_fn);
+            close_fn = null;
+        }
+        if($modal.parentNode) {
+            $modal.parentNode.removeChild($modal);
+        }
+        if(opts && typeof opts.on_close === "function") {
+            try {
+                opts.on_close();
+            } catch(e) {
+                log_warning(`yui_shell_show_modal: on_close threw: ${e}`);
+            }
+        }
+    };
+    close_fn = close;
+
+    yui_shell_push_escape(shell, "modal", close);
+    /*  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
+     *  cycle among focusables that the caller put inside
+     *  .modal-content; the X button can only be clicked. */
+    release_focus = activate_focus_trap_on($modal);
+
+    if((opts == null || opts.dismiss_on_background !== false)) {
+        $modal.querySelector(".modal-background").addEventListener("click", close);
+    }
+    let $close_btn = $modal.querySelector(".modal-close");
+    if($close_btn) {
+        $close_btn.addEventListener("click", close);
+    }
+    if(dialog) {
+        let $back = $modal.querySelector(".yui-dialog-back");
+        if($back) {
+            $back.addEventListener("click", close);
+        }
+        let $x = $modal.querySelector(".yui-dialog-x");
+        if($x) {
+            $x.addEventListener("click", close);
+        }
+    }
+
+    return { close };
+}
+
+
+/***************************************************************
+ *              Blocking dialogs (Bulma .modal-card)
+ *
+ *      build_dialog returns a Promise that resolves with the
+ *      clicked button's `value`.  Escape, the close button and
+ *      the dismiss action all resolve with the LAST button's value
+ *      (cancel/no/ok by convention — the safe-default action).
+ ***************************************************************/
+function build_dialog(shell, message, buttons, opts)
+{
+    let $layer = modal_layer(shell);
+    if(!$layer) {
+        log_warning("yui_shell_confirm_*: shell has no modal layer");
+        return Promise.resolve(buttons[buttons.length - 1].value);
+    }
+
+    let title = (opts && opts.title) || "";
+    let dismiss_value = buttons[buttons.length - 1].value;
+
+    let $body_children = (typeof message === "string")
+        ? [["p", {i18n: message}, message]]
+        : [message];
+
+    let title_attrs = !empty_string(title)
+        ? {class: "modal-card-title", i18n: title}
+        : {class: "modal-card-title"};
+
+    let $footer_children = buttons.map(b => {
+        let cls = "button";
+        if(b.kind === "primary") {
+            cls += " is-link";
+        } else if(b.kind === "danger") {
+            cls += " is-danger";
+        }
+        let btn_attrs = {class: cls, type: "button",
+                         "data-modal-button-value": b.value};
+        if(typeof b.label === "string") {
+            btn_attrs.i18n = b.label;
+        }
+        return ["button", btn_attrs, b.label];
+    });
+
+    let $modal = createElement2(
+        ["div", {class: "modal yui-modal yui-confirm is-active",
+                 role: "dialog", "aria-modal": "true"},
+            [
+                ["div", {class: "modal-background"}],
+                ["div", {class: "modal-card"},
+                    [
+                        ["header", {class: "modal-card-head"},
+                            [
+                                ["p", title_attrs, title],
+                                ["button", {class: "delete",
+                                            "aria-label": "close"}]
+                            ]
+                        ],
+                        ["section", {class: "modal-card-body"}, $body_children],
+                        ["footer", {class: "modal-card-foot"}, $footer_children]
+                    ]
+                ]
+            ]
+        ]
+    );
+    $layer.appendChild($modal);
+    maybe_apply_translator($modal, opts);
+
+    return new Promise(resolve => {
+        let resolved = false;
+        let close_fn = null;
+        let release_focus = null;
+
+        let close = function(value) {
+            if(resolved) {
+                return;
+            }
+            resolved = true;
+            if(release_focus) {
+                release_focus();
+                release_focus = null;
+            }
+            if(close_fn) {
+                yui_shell_pop_escape(shell, close_fn);
+                close_fn = null;
+            }
+            if($modal.parentNode) {
+                $modal.parentNode.removeChild($modal);
+            }
+            resolve(value);
+        };
+        close_fn = () => close(dismiss_value);
+
+        yui_shell_push_escape(shell, "modal", close_fn);
+        release_focus = activate_focus_trap_on(
+            $modal.querySelector(".modal-card")
+        );
+
+        $modal.querySelector(".modal-background").addEventListener(
+            "click", () => close(dismiss_value)
+        );
+        $modal.querySelector(".modal-card-head .delete").addEventListener(
+            "click", () => close(dismiss_value)
+        );
+        let footer_buttons = $modal.querySelectorAll(
+            ".modal-card-foot button"
+        );
+        footer_buttons.forEach($btn => {
+            $btn.addEventListener("click", () => {
+                close($btn.getAttribute("data-modal-button-value"));
+            });
+        });
+    });
+}
+
+
+export function yui_shell_confirm_ok(shell, message, opts)
+{
+    let label = (opts && opts.ok_label) || "OK";
+    return build_dialog(shell, message, [
+        {label: label, value: "ok", kind: "primary"}
+    ], opts).then(() => undefined);
+}
+
+export function yui_shell_confirm_yesno(shell, message, opts)
+{
+    let yes_label = (opts && opts.yes_label) || "Yes";
+    let no_label  = (opts && opts.no_label)  || "No";
+    return build_dialog(shell, message, [
+        {label: yes_label, value: "yes", kind: "primary"},
+        {label: no_label,  value: "no"}
+    ], opts).then(v => v === "yes");
+}
+
+export function yui_shell_confirm_yesnocancel(shell, message, opts)
+{
+    let yes_label    = (opts && opts.yes_label)    || "Yes";
+    let no_label     = (opts && opts.no_label)     || "No";
+    let cancel_label = (opts && opts.cancel_label) || "Cancel";
+    return build_dialog(shell, message, [
+        {label: yes_label,    value: "yes", kind: "primary"},
+        {label: no_label,     value: "no"},
+        {label: cancel_label, value: "cancel"}
+    ], opts);
+}

package/src/shell_show_on.js

@@ -0,0 +1,91 @@
+/***********************************************************************
+ *          shell_show_on.js
+ *
+ *      Pure breakpoint helpers used by C_YUI_SHELL to hide/show zones
+ *      via Bulma visibility classes.  Split out of c_yui_shell.js so
+ *      it can be unit-tested without a DOM.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/*  Bulma breakpoint order (low → high).  Used by show_on parser. */
+export const BULMA_BP_ORDER = ["mobile", "tablet", "desktop", "widescreen", "fullhd"];
+
+
+/************************************************************
+ *  Parse a `show_on` expression into the set of breakpoints
+ *  at which the element should be visible.
+ *
+ *      ""  |  "*"                always visible
+ *      "mobile"                  only at mobile
+ *      "mobile|tablet"           at mobile or tablet (OR)
+ *      ">=desktop"               from desktop up
+ *      "<desktop"                strictly below desktop
+ *      "<=tablet"                tablet and below
+ *      ">mobile"                 strictly above mobile
+ *
+ *  Returns { mobile:bool, tablet:bool, desktop:bool,
+ *            widescreen:bool, fullhd:bool }.
+ ************************************************************/
+export function breakpoints_from_expr(expr)
+{
+    let out = { mobile:false, tablet:false, desktop:false, widescreen:false, fullhd:false };
+    expr = String(expr == null ? "" : expr).trim();
+    if(expr === "*" || expr === "") {
+        for(let bp of BULMA_BP_ORDER) {
+            out[bp] = true;
+        }
+        return out;
+    }
+    let parts = expr.split("|").map(s => s.trim()).filter(s => s.length);
+    for(let p of parts) {
+        let m;
+        if((m = /^>=(\w+)$/.exec(p))) {
+            let idx = BULMA_BP_ORDER.indexOf(m[1]);
+            if(idx >= 0) {
+                for(let i=idx;i<BULMA_BP_ORDER.length;i++) {
+                    out[BULMA_BP_ORDER[i]] = true;
+                }
+            }
+        } else if((m = /^<(\w+)$/.exec(p))) {
+            let idx = BULMA_BP_ORDER.indexOf(m[1]);
+            if(idx > 0) {
+                for(let i=0;i<idx;i++) {
+                    out[BULMA_BP_ORDER[i]] = true;
+                }
+            }
+        } else if((m = /^<=(\w+)$/.exec(p))) {
+            let idx = BULMA_BP_ORDER.indexOf(m[1]);
+            if(idx >= 0) {
+                for(let i=0;i<=idx;i++) {
+                    out[BULMA_BP_ORDER[i]] = true;
+                }
+            }
+        } else if((m = /^>(\w+)$/.exec(p))) {
+            let idx = BULMA_BP_ORDER.indexOf(m[1]);
+            if(idx >= 0) {
+                for(let i=idx+1;i<BULMA_BP_ORDER.length;i++) {
+                    out[BULMA_BP_ORDER[i]] = true;
+                }
+            }
+        } else if(Object.prototype.hasOwnProperty.call(out, p)) {
+            out[p] = true;
+        }
+    }
+    return out;
+}
+
+
+/*  Map each Bulma breakpoint to the helper class that hides it. */
+export function bulma_hidden_class(bp)
+{
+    switch(bp) {
+        case "mobile":     return "yui-hidden-mobile";          /*  <769       */
+        case "tablet":     return "yui-hidden-tablet-only";     /*  769-1023   */
+        case "desktop":    return "yui-hidden-desktop-only";    /*  1024-1215  */
+        case "widescreen": return "yui-hidden-widescreen-only"; /*  1216-1407  */
+        case "fullhd":     return "yui-hidden-fullhd";          /*  ≥1408      */
+    }
+    return "";
+}

package/src/shell_show_on.test.js

@@ -0,0 +1,86 @@
+/***********************************************************************
+ *          shell_show_on.test.mjs
+ *
+ *      Unit tests for the pure `show_on` expression parser used by
+ *      C_YUI_SHELL.  Run with:
+ *          node --test tests/
+ ***********************************************************************/
+import { test, expect } from "vitest";
+import {
+    BULMA_BP_ORDER,
+    breakpoints_from_expr,
+    bulma_hidden_class,
+} from "./shell_show_on.js";
+
+
+/*  Helpers */
+const VISIBLE   = { mobile:true,  tablet:true,  desktop:true,  widescreen:true,  fullhd:true  };
+const INVISIBLE = { mobile:false, tablet:false, desktop:false, widescreen:false, fullhd:false };
+
+
+test("empty expression ⇒ visible at every breakpoint", () => {
+    expect(breakpoints_from_expr("")).toEqual(VISIBLE);
+    expect(breakpoints_from_expr("  ")).toEqual(VISIBLE);
+    expect(breakpoints_from_expr("*")).toEqual(VISIBLE);
+    expect(breakpoints_from_expr(null)).toEqual(VISIBLE);
+    expect(breakpoints_from_expr(undefined)).toEqual(VISIBLE);
+});
+
+test("single breakpoint ⇒ only that one", () => {
+    expect(breakpoints_from_expr("mobile")).toEqual({ ...INVISIBLE, mobile: true });
+    expect(breakpoints_from_expr("desktop")).toEqual({ ...INVISIBLE, desktop: true });
+    expect(breakpoints_from_expr("fullhd")).toEqual({ ...INVISIBLE, fullhd: true });
+});
+
+test("OR combination with '|'", () => {
+    expect(breakpoints_from_expr("mobile|tablet")).toEqual({ ...INVISIBLE, mobile: true, tablet: true });
+    expect(breakpoints_from_expr("tablet | desktop | widescreen")).toEqual({ ...INVISIBLE, tablet: true, desktop: true, widescreen: true });
+});
+
+test(">=desktop means desktop and everything wider", () => {
+    expect(breakpoints_from_expr(">=desktop")).toEqual({ ...INVISIBLE, desktop: true, widescreen: true, fullhd: true });
+});
+
+test(">mobile is strictly wider than mobile", () => {
+    expect(breakpoints_from_expr(">mobile")).toEqual({ ...INVISIBLE, tablet: true, desktop: true, widescreen: true, fullhd: true });
+});
+
+test("<desktop is strictly narrower than desktop", () => {
+    expect(breakpoints_from_expr("<desktop")).toEqual({ ...INVISIBLE, mobile: true, tablet: true });
+});
+
+test("<=tablet includes tablet and everything narrower", () => {
+    expect(breakpoints_from_expr("<=tablet")).toEqual({ ...INVISIBLE, mobile: true, tablet: true });
+});
+
+test("< against the smallest breakpoint yields nothing", () => {
+    /*  Historical guard: '<mobile' should be empty, not the whole set. */
+    expect(breakpoints_from_expr("<mobile")).toEqual(INVISIBLE);
+});
+
+test("> against the widest breakpoint yields nothing", () => {
+    expect(breakpoints_from_expr(">fullhd")).toEqual(INVISIBLE);
+});
+
+test("unknown tokens are ignored (no throw)", () => {
+    expect(breakpoints_from_expr("phablet")).toEqual(INVISIBLE);
+    /*  Valid ones in the mix still apply. */
+    expect(breakpoints_from_expr("phablet|mobile")).toEqual({ ...INVISIBLE, mobile: true });
+});
+
+test("OR combining ranges is the union of ranges", () => {
+    expect(breakpoints_from_expr(">=desktop | mobile")).toEqual({ ...INVISIBLE, mobile: true, desktop: true, widescreen: true, fullhd: true });
+});
+
+test("BULMA_BP_ORDER is low→high and complete", () => {
+    expect(BULMA_BP_ORDER).toEqual(["mobile", "tablet", "desktop", "widescreen", "fullhd"]);
+});
+
+test("bulma_hidden_class maps each breakpoint correctly", () => {
+    expect(bulma_hidden_class("mobile")).toBe("yui-hidden-mobile");
+    expect(bulma_hidden_class("tablet")).toBe("yui-hidden-tablet-only");
+    expect(bulma_hidden_class("desktop")).toBe("yui-hidden-desktop-only");
+    expect(bulma_hidden_class("widescreen")).toBe("yui-hidden-widescreen-only");
+    expect(bulma_hidden_class("fullhd")).toBe("yui-hidden-fullhd");
+    expect(bulma_hidden_class("nonsense")).toBe("");
+});