@gemboss/ui 0.2.1 → 0.4.0

package/src/kit-plain.js

@@ -0,0 +1,179 @@
+/* kit-plain.js: the BEHAVIOUR half of kit-plain.css, for surfaces that render HTML on the server and have no React
+   (GemFactory, gemcare, gempress, partner-radar). Each of them wrote its own popup, toast and menu-closing code; the
+   popup's Tab trap, stacking and "ask before closing" were each found missing by a review on some surface first.
+   GemFactory's copy (server/ui-kit.mjs, 02/10/2026) had all three, so it is the source.
+
+   A classic script, not a module: a server-rendered page can inline it (readFileSync(require.resolve(
+   "@gemboss/ui/kit-plain.js"))) or load it with <script src>, and use `globalThis.gembossUI` from its own inline code.
+   Strings it writes are the caller's: `title`, `body` and `foot` are HTML (escape your text), toast text is TEXT.
+
+     const { openModal, toast, initMenus } = gembossUI;
+     initMenus();                       // details.ui-menu: outside click, item click, window blur and Escape close it
+     const m = openModal({ title: "Delete #12?", body: '<div class="ui-modal__body">…</div>', foot: "…" });
+     m.close(value);                    // onClose(value) runs once; Escape / backdrop / × close with null
+     toast("Saved");  toast("Could not save", { error: true });
+*/
+(function (g) {
+  "use strict";
+  if (g.gembossUI) return;
+  var CLOSE_SVG = '<svg viewBox="0 0 20 20" aria-hidden="true" focusable="false"><path d="M5 5l10 10M15 5L5 15" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" fill="none"/></svg>';
+  // `summary` is a control (a kit ui-menu's ⋯ button); anything with no box (inside a closed <details>, display:none,
+  // [hidden]) is not, or Shift+Tab would "focus" a hidden menu item and stick (review #3633).
+  var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), summary, iframe, [tabindex]:not([tabindex="-1"])';
+  var focusables = function (root) {
+    // checkVisibility knows a closed <details>' content (content-visibility: hidden still has boxes, so
+    // getClientRects alone counts its items); the box test is the fallback for browsers without it.
+    return Array.prototype.slice.call(root.querySelectorAll(FOCUSABLE)).filter(function (el) {
+      return el.checkVisibility ? el.checkVisibility({ visibilityProperty: true }) : el.getClientRects().length > 0;
+    });
+  };
+  var esc = function (s) { return String(s).replace(/[&<>"']/g, function (c) { return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]; }); };
+  var MODALS = [];
+  var seq = 0;
+  var savedOverflow = null; // the page's own body overflow, put back when the LAST popup closes
+
+  /* Popup: .ui-overlay + .ui-modal, the same markup as the admin's Modal.tsx. Escape, a click on the backdrop and the ×
+     close it; Tab stays inside; popups stack and only the TOP one takes keys. `title` empty = no header bar (then
+     `label` names the dialog for screen readers). `beforeClose(value)` may return a Promise<boolean>: false keeps it
+     open (unsaved changes); it gets the close value, so a Save that calls m.close(data) can skip the question, and a
+     guard that THROWS keeps the popup open (closing would throw away what it guards). Focus returns to whatever had it
+     when the popup opened, or to the popup below when that element is gone or sits under it. */
+  function openModal(o) {
+    var title = o.title || "", label = o.label || "", closeLabel = o.closeLabel || "Close";
+    var opener = document.activeElement;
+    var overlay = document.createElement("div");
+    overlay.className = "ui-overlay" + (o.overlayClass ? " " + o.overlayClass : "");
+    overlay.setAttribute("role", "presentation");
+    var tid = "gb-modal-title-" + ++seq;
+    overlay.innerHTML = '<div class="ui-modal' + (o.className ? " " + o.className : "") + '" role="dialog" aria-modal="true" ' +
+      (title ? 'aria-labelledby="' + tid + '"' : 'aria-label="' + esc(label) + '"') + ' tabindex="-1">' +
+      (title ? '<div class="ui-modal__head"><div class="ui-modal__title" id="' + tid + '">' + title + '</div><button type="button" class="ui-modal__close" aria-label="' + esc(closeLabel) + '">' + CLOSE_SVG + "</button></div>" : "") +
+      (o.body || "") + (o.foot ? '<div class="ui-modal__foot">' + o.foot + "</div>" : "") + "</div>";
+    var panel = overlay.firstChild;
+    var asking = false;
+    var m = {
+      panel: panel,
+      overlay: overlay,
+      close: function (value, opts) {
+        var force = opts && opts.force;
+        if (MODALS.indexOf(m) < 0) return Promise.resolve();
+        if (!force && o.beforeClose) {
+          if (asking) return Promise.resolve();
+          asking = true;
+          return Promise.resolve().then(function () { return o.beforeClose(value); }).catch(function (err) { console.error(err); return false; }).then(function (go) {
+            asking = false;
+            // Closed by force while asking (a navigation): closing again would splice the NEWEST popup instead.
+            if (go && MODALS.indexOf(m) >= 0) finish(value);
+          });
+        }
+        finish(value);
+        return Promise.resolve();
+      },
+    };
+    function finish(value) {
+      MODALS.splice(MODALS.indexOf(m), 1);
+      removeEventListener("keydown", onKey);
+      overlay.remove();
+      var top = MODALS[MODALS.length - 1];
+      if (!top) { document.body.style.overflow = savedOverflow || ""; savedOverflow = null; }
+      if (opener && opener.isConnected && opener.focus && (!top || top.panel.contains(opener))) opener.focus();
+      else if (top) top.panel.focus();
+      if (o.onClose) o.onClose(value);
+    }
+    function onKey(e) {
+      if (MODALS[MODALS.length - 1] !== m) return;
+      // Escape while an IME is composing (zh, ja, vi telex) cancels the composition, not the dialog.
+      if (e.key === "Escape") { if (e.isComposing || e.keyCode === 229) return; e.preventDefault(); m.close(null); return; }
+      if (e.key !== "Tab") return;
+      var f = focusables(panel);
+      if (!f.length) return;
+      var first = f[0], last = f[f.length - 1];
+      if (!panel.contains(document.activeElement)) { e.preventDefault(); first.focus(); }
+      else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+      else if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+    }
+    // Close on the backdrop only when the press STARTED there: selecting text in a field and releasing past the panel
+    // edge fires click on the overlay (the common ancestor) and would throw the form away.
+    var downOnBackdrop = false;
+    overlay.addEventListener("mousedown", function (e) { downOnBackdrop = e.target === overlay; });
+    overlay.addEventListener("click", function (e) { if (e.target === overlay && downOnBackdrop) m.close(null); downOnBackdrop = false; });
+    var x = panel.querySelector(".ui-modal__head .ui-modal__close");
+    if (x) x.onclick = function () { m.close(null); };
+    addEventListener("keydown", onKey);
+    if (!MODALS.length) savedOverflow = document.body.style.overflow;
+    MODALS.push(m);
+    document.body.append(overlay);
+    document.body.style.overflow = "hidden";
+    setTimeout(function () { (panel.querySelector("[autofocus]") || panel).focus(); }, 0);
+    return m;
+  }
+
+  /* Toast: the admin's pill (.gemboss-toast), bottom centre, red when `error`. Text, not HTML. The viewport is a polite
+     live region; an ERROR toast is role="alert" so it is announced at once. `duration: 0` = stays until its × is
+     pressed (`dismissLabel` names it). When the region is created by this very toast, the toast goes in one frame
+     later: a live region that appears together with its first message is often not announced at all. */
+  function toast(text, opts) {
+    opts = opts || {};
+    var vp = document.querySelector(".gemboss-toast-viewport"), fresh = !vp;
+    if (!vp) {
+      vp = document.createElement("div");
+      vp.className = "gemboss-toast-viewport";
+      vp.setAttribute("role", "status");
+      vp.setAttribute("aria-live", "polite");
+      document.body.append(vp);
+    }
+    var t = document.createElement("div");
+    t.className = "gemboss-toast" + (opts.error ? " is-error" : "");
+    if (opts.error) t.setAttribute("role", "alert");
+    var span = document.createElement("span");
+    span.className = "gemboss-toast-text";
+    span.textContent = String(text);
+    t.append(span);
+    var sticky = opts.duration === 0;
+    if (sticky) {
+      var x = document.createElement("button");
+      x.type = "button";
+      x.className = "gemboss-toast-dismiss";
+      x.setAttribute("aria-label", opts.dismissLabel || "Dismiss");
+      x.innerHTML = CLOSE_SVG;
+      x.onclick = function () { t.remove(); };
+      t.append(x);
+    }
+    // Toasts sent while the new region is still waiting queue behind the first, so they keep their order.
+    if (fresh) vp.dataset.readyAt = String(Date.now() + 50);
+    var wait = Math.max(0, Number(vp.dataset.readyAt || 0) - Date.now());
+    var put = function () { vp.append(t); };
+    if (wait) setTimeout(put, wait); else put();
+    if (!sticky) setTimeout(function () { t.remove(); }, wait + (opts.duration || (opts.error ? 6000 : 3500)));
+    return t;
+  }
+
+  /* Menus (details.ui-menu, kit-plain.css) open with no script; closing is the page's job: an outside click, a click on
+     an item, the window losing focus (a click inside an iframe never reaches this document), and Escape. Escape closes
+     the MENU first and stops there, so a menu inside a popup does not close the popup with it. Idempotent. */
+  var menusOn = false;
+  function closeMenus(except) {
+    document.querySelectorAll("details.ui-menu[open]").forEach(function (d) { if (d !== except) d.open = false; });
+  }
+  function initMenus() {
+    if (menusOn) return;
+    menusOn = true;
+    document.addEventListener("click", function (e) {
+      var d = e.target.closest && e.target.closest("details.ui-menu");
+      closeMenus(d);
+      if (d && e.target.closest(".ui-menu__item")) d.open = false;
+    });
+    addEventListener("blur", function () { closeMenus(); });
+    addEventListener("keydown", function (e) {
+      var d = e.key === "Escape" && !e.isComposing && document.querySelector("details.ui-menu[open]");
+      if (!d) return;
+      e.preventDefault();
+      e.stopImmediatePropagation();
+      d.open = false;
+      var s = d.querySelector("summary");
+      if (s) s.focus();
+    }, true);
+  }
+
+  g.gembossUI = { openModal: openModal, toast: toast, initMenus: initMenus, closeMenus: closeMenus, openModals: function () { return MODALS.length; } };
+})(globalThis);