@yuneta/gobj-ui 7.26.37 → 7.26.38

package/README.md

@@ -3325,6 +3325,38 @@ keeps working afterwards. With no guard a modal closes exactly as it always
 did, and the returned `close()` always closes **unconditionally** — the veto is
 for the user's dismiss, not for the code's.
 
+**A guard that ASKS returns the question's promise** (7.26.38+). It is a veto
+too, and it tells the modal when the question is over: a browser Back that
+asked gets its history entry back THEN, below nothing. Opening the question and
+returning `false` put the entry back at once, above the question's own -- so the
+next Back, the one meant for the question, reached the modal, which asked
+again, and on a phone (where Back is a gesture) every Back stacked one more
+question.
+
+```js
+const sheet = yui_shell_show_modal(shell, $body, {
+    dialog:       true,
+    title:        "device settings",
+    t:            t,
+    before_close: () => {
+        const kw = {};
+        gobj_send_event(form, "EV_WINDOW_TO_CLOSE", kw, gobj);
+        if(!kw.abort_close) {
+            return true;
+        }
+        return yui_shell_confirm_yesnocancel(shell, "all changes will be lost", {t})
+            .then((answer) => {
+                if(answer === "yes") {
+                    gobj_send_event(gobj, "EV_CLOSE_SHEET", {}, gobj);  // its action: sheet.close()
+                }
+            });
+    },
+    on_close:     () => {
+        gobj_send_event(gobj, "EV_SHEET_CLOSED", {}, gobj);  // its action: destroy the form
+    }
+});
+```
+
 ### Confirmations — and the red one, `yui_shell_confirm_danger`
 
 `yui_shell_confirm_yesno(shell, message, opts)` asks a question and resolves to

package/dist/gobj-ui.cjs.js

@@ -3970,6 +3970,10 @@ function yui_shell_show_modal(shell, content, opts) {
 			(0, _yuneta_gobj_js.log_warning)(`yui_shell_show_modal: before_close threw: ${e}`);
 			allow = true;
 		}
+		if (allow && typeof allow.then === "function") {
+			if (typeof on_veto === "function") allow.then(on_veto, on_veto);
+			return;
+		}
 		if (allow === false) {
 			if (typeof on_veto === "function") on_veto();
 			return;
@@ -3981,7 +3985,7 @@ function yui_shell_show_modal(shell, content, opts) {
 	};
 	let on_back = function() {
 		guarded_close(function() {
-			overlay = yui_shell_register_overlay(shell, on_back);
+			if (!closed) overlay = yui_shell_register_overlay(shell, on_back);
 		});
 	};
 	escape_handler = request_close;
@@ -31549,19 +31553,19 @@ function open_form_dialog(gobj, mode, record) {
 }
 /************************************************************
 *  Unsaved-changes guard for the dialog's `before_close` hook.
-*  Returns true to allow the dismiss; false to VETO it (the form
-*  has pending edits) and pop the confirm — which, on "yes",
-*  closes the modal itself (EV_WINDOW_TO_CLOSE contract).
+*  Returns true to allow the dismiss; otherwise the form has
+*  pending edits, and it asks: the confirm's promise is a VETO
+*  that tells the dialog when the question is over (a Back that
+*  asked gets its history entry back then, below nothing). On
+*  "yes" the confirm closes the modal itself (EV_WINDOW_TO_CLOSE
+*  contract).
 ************************************************************/
 function form_may_close(gobj) {
 	let priv = gobj.priv;
 	if (priv.form) {
 		let kw = {};
 		(0, _yuneta_gobj_js.gobj_send_event)(priv.form, "EV_WINDOW_TO_CLOSE", kw, gobj);
-		if (kw.abort_close) {
-			confirm_then$1(gobj, kw.warning || "all changes will be lost", { what: "close_form" });
-			return false;
-		}
+		if (kw.abort_close) return confirm_then$1(gobj, kw.warning || "all changes will be lost", { what: "close_form" });
 	}
 	return true;
 }
@@ -31595,10 +31599,11 @@ function teardown_form_child(gobj) {
 *  it, and a gobj, a Tabulator row or a DOM node in there is a
 *  circular structure that breaks the very trace the FSM feeds.
 *
-*  Same shape as C_YUI_SCHEMA_EDITOR's confirm_then().
+*  Same shape as C_YUI_SCHEMA_EDITOR's confirm_then(). Answers
+*  the promise of the question, settled once it is over.
 ************************************************************/
 function confirm_then$1(gobj, message, kw) {
-	yui_shell_confirm_yesnocancel(yui_shell_of(gobj), message, {
+	return yui_shell_confirm_yesnocancel(yui_shell_of(gobj), message, {
 		t: i18next.t,
 		yes_label: "yes",
 		no_label: "no",

package/dist/gobj-ui.es.js

@@ -3965,6 +3965,10 @@ function yui_shell_show_modal(shell, content, opts) {
 			log_warning(`yui_shell_show_modal: before_close threw: ${e}`);
 			allow = true;
 		}
+		if (allow && typeof allow.then === "function") {
+			if (typeof on_veto === "function") allow.then(on_veto, on_veto);
+			return;
+		}
 		if (allow === false) {
 			if (typeof on_veto === "function") on_veto();
 			return;
@@ -3976,7 +3980,7 @@ function yui_shell_show_modal(shell, content, opts) {
 	};
 	let on_back = function() {
 		guarded_close(function() {
-			overlay = yui_shell_register_overlay(shell, on_back);
+			if (!closed) overlay = yui_shell_register_overlay(shell, on_back);
 		});
 	};
 	escape_handler = request_close;
@@ -31544,19 +31548,19 @@ function open_form_dialog(gobj, mode, record) {
 }
 /************************************************************
 *  Unsaved-changes guard for the dialog's `before_close` hook.
-*  Returns true to allow the dismiss; false to VETO it (the form
-*  has pending edits) and pop the confirm — which, on "yes",
-*  closes the modal itself (EV_WINDOW_TO_CLOSE contract).
+*  Returns true to allow the dismiss; otherwise the form has
+*  pending edits, and it asks: the confirm's promise is a VETO
+*  that tells the dialog when the question is over (a Back that
+*  asked gets its history entry back then, below nothing). On
+*  "yes" the confirm closes the modal itself (EV_WINDOW_TO_CLOSE
+*  contract).
 ************************************************************/
 function form_may_close(gobj) {
 	let priv = gobj.priv;
 	if (priv.form) {
 		let kw = {};
 		gobj_send_event(priv.form, "EV_WINDOW_TO_CLOSE", kw, gobj);
-		if (kw.abort_close) {
-			confirm_then$1(gobj, kw.warning || "all changes will be lost", { what: "close_form" });
-			return false;
-		}
+		if (kw.abort_close) return confirm_then$1(gobj, kw.warning || "all changes will be lost", { what: "close_form" });
 	}
 	return true;
 }
@@ -31590,10 +31594,11 @@ function teardown_form_child(gobj) {
 *  it, and a gobj, a Tabulator row or a DOM node in there is a
 *  circular structure that breaks the very trace the FSM feeds.
 *
-*  Same shape as C_YUI_SCHEMA_EDITOR's confirm_then().
+*  Same shape as C_YUI_SCHEMA_EDITOR's confirm_then(). Answers
+*  the promise of the question, settled once it is over.
 ************************************************************/
 function confirm_then$1(gobj, message, kw) {
-	yui_shell_confirm_yesnocancel(yui_shell_of(gobj), message, {
+	return yui_shell_confirm_yesnocancel(yui_shell_of(gobj), message, {
 		t,
 		yes_label: "yes",
 		no_label: "no",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuneta/gobj-ui",
-  "version": "7.26.37",
+  "version": "7.26.38",
   "type": "module",
   "main": "dist/gobj-ui.cjs.js",
   "module": "dist/gobj-ui.es.js",

package/src/c_yui_treedb_topic_with_form.js

@@ -2554,9 +2554,12 @@ function open_form_dialog(gobj, mode, record)
 
 /************************************************************
  *  Unsaved-changes guard for the dialog's `before_close` hook.
- *  Returns true to allow the dismiss; false to VETO it (the form
- *  has pending edits) and pop the confirm — which, on "yes",
- *  closes the modal itself (EV_WINDOW_TO_CLOSE contract).
+ *  Returns true to allow the dismiss; otherwise the form has
+ *  pending edits, and it asks: the confirm's promise is a VETO
+ *  that tells the dialog when the question is over (a Back that
+ *  asked gets its history entry back then, below nothing). On
+ *  "yes" the confirm closes the modal itself (EV_WINDOW_TO_CLOSE
+ *  contract).
  ************************************************************/
 function form_may_close(gobj)
 {
@@ -2570,9 +2573,8 @@ function form_may_close(gobj)
              *  a second key to define — and the one that was here had never
              *  been defined in any locale, which renders as the English
              *  sentence itself, in every language, for ever. */
-            confirm_then(gobj, /* i18n: C_YUI_FORM_I18N_KEYS */ kw.warning || "all changes will be lost",
+            return confirm_then(gobj, /* i18n: C_YUI_FORM_I18N_KEYS */ kw.warning || "all changes will be lost",
                 {what: "close_form"});
-            return false;
         }
     }
     return true;
@@ -2612,11 +2614,12 @@ function teardown_form_child(gobj)
  *  it, and a gobj, a Tabulator row or a DOM node in there is a
  *  circular structure that breaks the very trace the FSM feeds.
  *
- *  Same shape as C_YUI_SCHEMA_EDITOR's confirm_then().
+ *  Same shape as C_YUI_SCHEMA_EDITOR's confirm_then(). Answers
+ *  the promise of the question, settled once it is over.
  ************************************************************/
 function confirm_then(gobj, message, kw)
 {
-    yui_shell_confirm_yesnocancel(
+    return yui_shell_confirm_yesnocancel(
         yui_shell_of(gobj), message,
         {t: t, yes_label: "yes", no_label: "no", cancel_label: "cancel"}
     ).then(function(answer) {

package/src/modal_guard_back.wiring.test.js

@@ -0,0 +1,193 @@
+/***********************************************************************
+ *          modal_guard_back.wiring.test.js
+ *
+ *      A modal whose `before_close` guard ASKS (unsaved changes). The
+ *      browser Back takes the modal's history entry before the guard
+ *      runs; the guard opens a question, and the modal stays. When the
+ *      modal took its entry back at once, it went ABOVE the question's
+ *      own entry: the next Back -- the one meant for the question --
+ *      reached the modal, which asked again, and every Back stacked
+ *      one more question. A guard that asks answers the question's
+ *      promise, and the modal takes its entry back once the question
+ *      is over.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {describe, test, expect, beforeAll, beforeEach} from "vitest";
+import {install_dom_double} from "../test/dom_double.js";
+
+install_dom_double();
+
+const {
+    SDATA_END, gclass_create,
+    gobj_start_up, gobj_create_yuno, gobj_create, gobj_start,
+    set_log_callback,
+} = await import("@yuneta/gobj-js");
+const {register_c_yui_shell} = await import("./c_yui_shell.js");
+const {
+    yui_shell_show_modal,
+    yui_shell_confirm_yesnocancel,
+} = await import("./shell_modals.js");
+
+const logged = [];
+let yuno = null;
+let seq = 0;
+
+beforeAll(async () => {
+    const i18next = (await import("i18next")).default;
+    await i18next.init({lng: "en", resources: {}});
+    gobj_start_up(null, null, null, null, null, null, null);
+    set_log_callback((level, msg) => {
+        logged.push({level: String(level), msg: String(msg)});
+    });
+    gclass_create("C_TEST_GUARD_HOST", [], [["ST_IDLE", []]], {}, 0, [SDATA_END()], {}, 0, 0, 0, 0);
+    register_c_yui_shell();
+    yuno = gobj_create_yuno("guard_yuno", "C_TEST_GUARD_HOST", {});
+    gobj_start(yuno);
+});
+
+beforeEach(() => {
+    logged.length = 0;
+    /*  What a failed test left open belongs to its own shell.  */
+    for(const $n of document.querySelectorAll(".CONFIRM, .TEST_SHEET")) {
+        if($n.parentNode) {
+            $n.parentNode.removeChild($n);
+        }
+    }
+});
+
+function errors()
+{
+    return logged.filter((l) => l.level === "error").map((l) => l.msg);
+}
+
+/*  Same Back as window_veto_back: a Back off a marker lands on the entry
+ *  under it, which the shell stamped with the TOP overlay's id.  */
+function press_back(shell)
+{
+    const stack = shell.priv.overlay_stack;
+    const ev = new Event("popstate");
+    ev.state = {__yui_below__: stack.length ? stack[stack.length - 1].id : 0};
+    window.dispatchEvent(ev);
+}
+
+function settle()
+{
+    return new Promise(resolve => setTimeout(resolve, 0));
+}
+
+function sheets()
+{
+    return document.querySelectorAll(".TEST_SHEET").length;
+}
+
+function questions()
+{
+    return document.querySelectorAll(".CONFIRM").length;
+}
+
+/*  A shell, and a sheet over it whose guard asks while `state.dirty`.  */
+function open_guarded_sheet(state)
+{
+    seq++;
+    const app = gobj_create(`gapp${seq}`, "C_TEST_GUARD_HOST", {}, yuno);
+    gobj_start(app);
+    const shell = gobj_create(`gshell${seq}`, "C_YUI_SHELL",
+        {config: {shell: {}}, default_route: "/home", subscriber: app}, app);
+    gobj_start(shell);
+    logged.length = 0;     /*  the shell's own start: no route table here  */
+
+    const handle = yui_shell_show_modal(shell, "the sheet", {
+        dialog:        true,
+        logical_class: "TEST_SHEET",
+        title:         "settings",
+        before_close:  function() {
+            if(!state.dirty) {
+                return true;
+            }
+            state.asked++;
+            return yui_shell_confirm_yesnocancel(shell, "all changes will be lost", {
+                yes_label: "yes", no_label: "no", cancel_label: "cancel"
+            }).then(function(answer) {
+                if(answer === "yes") {
+                    handle.close();
+                }
+            });
+        }
+    });
+    return {shell, handle};
+}
+
+describe("a modal whose guard asks before it closes", () => {
+    test("Back asks ONCE, and the next Back takes the question, not the modal", async () => {
+        const state = {dirty: true, asked: 0};
+        const {shell, handle} = open_guarded_sheet(state);
+        expect(shell.priv.overlay_stack.length).toBe(1);
+
+        /*  Back: the guard asks. The modal stays, and only the question
+         *  is on the stack -- the modal's entry went with the Back.  */
+        press_back(shell);
+        expect(sheets()).toBe(1);
+        expect(questions()).toBe(1);
+        expect(state.asked).toBe(1);
+        expect(shell.priv.overlay_stack.length).toBe(1);
+
+        /*  Back again: it is the question that goes (its safe default,
+         *  cancel), and the modal takes its entry back only then.  */
+        press_back(shell);
+        await settle();
+        expect(questions()).toBe(0);
+        expect(sheets()).toBe(1);
+        expect(state.asked).toBe(1);
+        expect(shell.priv.overlay_stack.length).toBe(1);
+
+        /*  And a third Back asks again: one question, not two.  */
+        press_back(shell);
+        expect(questions()).toBe(1);
+        expect(state.asked).toBe(2);
+        press_back(shell);
+        await settle();
+        expect(questions()).toBe(0);
+        expect(sheets()).toBe(1);
+        expect(errors()).toEqual([]);
+
+        handle.close();
+        expect(sheets()).toBe(0);
+    });
+
+    test("the back arrow that asks leaves the modal's entry UNDER the question", async () => {
+        const state = {dirty: true, asked: 0};
+        const {shell, handle} = open_guarded_sheet(state);
+        const entry = shell.priv.overlay_stack[0];
+
+        document.querySelector(".TEST_SHEET .yui-dialog-back").click();
+        expect(questions()).toBe(1);
+        expect(shell.priv.overlay_stack.length).toBe(2);
+        expect(shell.priv.overlay_stack[0]).toBe(entry);
+
+        press_back(shell);
+        await settle();
+        expect(questions()).toBe(0);
+        expect(sheets()).toBe(1);
+        expect(shell.priv.overlay_stack).toEqual([entry]);
+        expect(errors()).toEqual([]);
+
+        handle.close();
+        expect(sheets()).toBe(0);
+    });
+
+    test("with nothing to lose, Back closes it at once", async () => {
+        const state = {dirty: false, asked: 0};
+        const {shell} = open_guarded_sheet(state);
+        expect(sheets()).toBe(1);
+
+        press_back(shell);
+        await settle();
+        expect(sheets()).toBe(0);
+        expect(questions()).toBe(0);
+        expect(state.asked).toBe(0);
+        expect(shell.priv.overlay_stack).toEqual([]);
+        expect(errors()).toEqual([]);
+    });
+});

package/src/shell_modals.js

@@ -386,7 +386,17 @@ export function yui_shell_show_modal(shell, content, opts)
      *  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. */
+     *  existing callers are unaffected.
+     *
+     *  A guard that ASKS first returns the question's PROMISE: a veto, and
+     *  the modal is told when the question is over. It matters on browser
+     *  Back, which took the modal's history entry before the guard ran:
+     *  the entry goes back once the question is gone, never above it.
+     *  Returned false after opening the question, the entry went back at
+     *  once, over the question's own, and the next Back -- the one meant
+     *  for the question -- reached the modal, which asked again: every
+     *  Back stacked one more question. Same contract as the `asking`
+     *  close of C_YUI_WINDOW. */
     let guarded_close = function(on_veto) {
         if(closed) {
             return;
@@ -400,6 +410,12 @@ export function yui_shell_show_modal(shell, content, opts)
                 allow = true;
             }
         }
+        if(allow && typeof allow.then === "function") {
+            if(typeof on_veto === "function") {
+                allow.then(on_veto, on_veto);
+            }
+            return;
+        }
         if(allow === false) {
             if(typeof on_veto === "function") {
                 on_veto();
@@ -412,10 +428,13 @@ export function yui_shell_show_modal(shell, content, opts)
         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. */
+     *  re-arm a fresh entry so a later Back still targets this modal --
+     *  unless the answer to its question closed it.  */
     let on_back = function() {
         guarded_close(function() {
-            overlay = yui_shell_register_overlay(shell, on_back);
+            if(!closed) {
+                overlay = yui_shell_register_overlay(shell, on_back);
+            }
         });
     };