@gemboss/ui 0.2.0 → 0.3.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);

package/src/menu.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+// menu.tsx: the kit's action menu ("⋯") — a `<details>` disclosure, so it opens with no JavaScript and a
+// server-rendered surface (GemFactory, gemcare) can print it as plain markup. The surface is the shell's
+// `gemboss-popover-surface` and the rows share the account menu's row (shell.css), so every menu in the
+// fleet looks the same (§9.3). Where React hydrates, the menu closes itself like AccountMenu does: outside
+// click, Escape (focus back on the trigger), and a button row after its handler (review #3591: a React page
+// had no clean way to close it). The catalog renders its example from these components.
+import React, { useEffect, useRef } from "react";
+import { Icon } from "./icons";
+
+/** The trigger is an icon button (`label` is its accessible name). `end` aligns the list to the right edge. */
+export function Menu({ label, icon, end, children, className }: {
+  label: string;
+  icon?: React.ReactNode;
+  end?: boolean;
+  children?: React.ReactNode;
+  className?: string;
+}) {
+  const ref = useRef<HTMLDetailsElement>(null);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return undefined;
+    const onDoc = (e: MouseEvent) => { if (el.open && !el.contains(e.target as Node)) el.open = false; };
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape" && el.open) { el.open = false; el.querySelector("summary")?.focus(); } };
+    document.addEventListener("click", onDoc);
+    document.addEventListener("keydown", onKey);
+    return () => { document.removeEventListener("click", onDoc); document.removeEventListener("keydown", onKey); };
+  }, []);
+  return (
+    <details ref={ref} className={["ui-menu", end ? "ui-menu--end" : "", className ?? ""].filter(Boolean).join(" ")}>
+      <summary className="ui-btn ui-btn--icon" aria-label={label} title={label}>{icon ?? <Icon name="more" />}</summary>
+      <div className="ui-menu__list gemboss-popover-surface">{children}</div>
+    </details>
+  );
+}
+
+/** One row: a link (`href`) or a button. `hint` is the quiet text on the right; `danger` for destructive rows.
+ *  A disabled link is not a link: no href, aria-disabled, out of the tab order (an `<a disabled>` still follows
+ *  on Enter). A caller's `className` is added to the row's class, not put in its place. */
+export function MenuItem({ href, danger, hint, children, className, disabled, onClick, ...rest }: {
+  href?: string;
+  danger?: boolean;
+  hint?: React.ReactNode;
+  children?: React.ReactNode;
+  disabled?: boolean;
+  onClick?: React.MouseEventHandler<HTMLElement>;
+} & Omit<React.HTMLAttributes<HTMLElement>, "onClick"> & Pick<React.AnchorHTMLAttributes<HTMLAnchorElement>, "target" | "rel">) {
+  const cls = ["ui-menu__item", danger ? "ui-menu__item--danger" : "", className ?? ""].filter(Boolean).join(" ");
+  const body = <>{children}{hint ? <span className="ui-menu__hint">{hint}</span> : null}</>;
+  if (href) {
+    if (disabled) return <a className={cls} aria-disabled="true" tabIndex={-1} {...rest}>{body}</a>;
+    return <a className={cls} href={href} onClick={onClick} {...rest}>{body}</a>;
+  }
+  const close: React.MouseEventHandler<HTMLButtonElement> = (e) => {
+    onClick?.(e);
+    e.currentTarget.closest("details")?.removeAttribute("open");
+  };
+  return <button type="button" className={cls} disabled={disabled} onClick={close} {...rest}>{body}</button>;
+}
+
+export function MenuSeparator() {
+  return <hr className="ui-menu__sep" />;
+}

package/src/shell.css

@@ -100,20 +100,24 @@
 /* Account dropdown menu items (avatar chip) — CSS-driven hover/focus, replaces inline JS handlers. */
 /* min-height 44 (28/09/2026): 12px padding around a 13px line measured 42.84px — under the 44px control
    floor (CLAUDE.md §9.1), in the admin's own menu and in every surface wearing it through @gemboss/ui. */
-.gemboss-account-menu-item {
+.gemboss-account-menu-item,
+.ui-menu__item {
   display: block; width: 100%; min-height: 44px; padding: 12px 16px; border: 0; background: transparent;
   font: inherit; font-size: 13px; color: var(--gemboss-text); text-align: left; text-decoration: none;
   cursor: pointer; transition: background var(--gemboss-transition-fast) ease, color var(--gemboss-transition-fast) ease;
 }
 
-.gemboss-account-menu-item:hover { background: var(--gemboss-hover); }
+.gemboss-account-menu-item:hover,
+.ui-menu__item:hover { background: var(--gemboss-hover); }
 
-.gemboss-account-menu-item:focus-visible { outline: 2px solid var(--gemboss-primary); outline-offset: -2px; background: var(--gemboss-hover); }
+.gemboss-account-menu-item:focus-visible,
+.ui-menu__item:focus-visible { outline: 2px solid var(--gemboss-primary); outline-offset: -2px; background: var(--gemboss-hover); }
 
 /* `--gemboss-danger` var(--gemboss-danger) is 4.25:1 on `--gemboss-hover` #eceef2, and this row takes that hover
    background two lines above — so the one moment the item is under the cursor is the moment its label
    drops below AA. `--gemboss-danger-strong` #b42318 is 5.66:1 there and 7.30:1 on white. */
-.gemboss-account-menu-item.danger { color: var(--gemboss-danger-strong); }
+.gemboss-account-menu-item.danger,
+.ui-menu__item--danger { color: var(--gemboss-danger-strong); }
 
 .gemboss-account-chip {
   width: 30px;

package/src/ui.css

@@ -154,7 +154,7 @@
   background-color: var(--p-color-input-bg-surface-hover, var(--gemboss-field-bg-hover));
 }
 .ui-select:focus { outline: none; }
-.ui-select:focus-visible {
+.ui-select:focus-visible:not(:disabled) {
   outline: 2px solid var(--p-color-border-focus, #005bd3); outline-offset: 1px;
   border-color: var(--p-color-input-border-active, var(--gemboss-field-line-active));
 }
@@ -300,12 +300,35 @@ a.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-offset:
    consumer belongs in that consumer's chunk (see SettingsDialog.module.css). */
 .ui-modal--lg { position: relative; }
 
+/* The kit's multi-line field joins the ONE field family (01/10/2026, Chris: "form control đồng bộ"):
+   same input-border token, hover and focus ring as `gemboss-field` and `.ui-select`. Before, it drew a
+   lighter --ui-border box at 14px with no focus ring, so on GemFactory's compose form a textarea sat
+   beside selects of a darker border and text fields of a third look (measured on prod). */
 .ui-textarea {
   width: 100%; min-height: 96px; resize: vertical; box-sizing: border-box;
-  background: var(--ui-surface); border: 1px solid var(--ui-border); border-radius: var(--ui-radius-md);
-  padding: 12px; color: var(--ui-text); font-size: 14px; font-family: inherit; outline: none;
+  background: var(--p-color-input-bg-surface, var(--gemboss-field-bg));
+  border: 1px solid var(--p-color-input-border, var(--gemboss-field-line)); border-radius: var(--ui-radius-md);
+  padding: 12px; color: var(--p-color-text, var(--gemboss-field-ink)); font-size: var(--ui-fs-body); line-height: 1.5; font-family: inherit;
+}
+.ui-textarea::placeholder { color: var(--p-color-text-secondary, var(--gemboss-field-placeholder)); }
+.ui-textarea:hover:not(:disabled) {
+  border-color: var(--p-color-input-border-hover, var(--gemboss-field-line-hover));
+  background-color: var(--p-color-input-bg-surface-hover, var(--gemboss-field-bg-hover));
+}
+.ui-textarea:focus { outline: none; }
+.ui-textarea:focus-visible:not(:disabled) {
+  outline: 2px solid var(--p-color-border-focus, #005bd3); outline-offset: 1px;
+  border-color: var(--p-color-input-border-active, var(--gemboss-field-line-active));
+}
+.ui-textarea:disabled { opacity: .5; cursor: not-allowed; }
+/* On a PHONE-WIDTH screen every field of the family reads 16px (iOS zooms the page on tap below that)
+   and a select is a 44px target — by WIDTH, as `gemboss-field` does, because a desktop browser at 320px
+   still reports pointer: fine. Measured on GemFactory at 390px before this: select 13px, textarea 14px. */
+@media (max-width: 47.9975em) {
+  .ui-select.ui-select, .ui-textarea { font-size: 16px; }
+  /* Height only for the full select: `--slim` is a density decision (table rows), as the coarse block keeps it. */
+  .ui-select:not(.ui-select--slim) { min-height: 44px; }
 }
-.ui-textarea:focus { border-color: var(--ui-accent); }
 
 /* ── Segmented control ────────────────────────────────────────────────────────
    Grouped toggle: icon squares (.ui-seg button) or text tabs (.is-text). The