@gemboss/ui 0.21.0 → 0.30.2

package/src/search-dialog.tsx

@@ -0,0 +1,146 @@
+"use client";
+
+/**
+ * `SearchDialog` — @gemboss/ui (04/10/2026; its own module since 0.23.0, out of dialog.tsx).
+ *
+ * The Featurebase / admin command search. A topbar button (or ⌘K / Ctrl+K / "/")
+ * opens it; what to show before typing comes from `initial`, results while typing from `search`
+ * (debounced, the latest answer wins); ↑ ↓ move, Enter opens, Esc closes. Results are links, so a
+ * page without JavaScript loses only the popup, never the search itself (`fallbackHref`).
+ * Its look (`gb-search-*`) is in portal.css, which it imports: a surface that never shows it never loads it.
+ */
+import "./portal.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
+import React, { useCallback, useEffect, useId, useRef, useState } from "react";
+import { Icon } from "./icons";
+
+const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
+
+export type SearchItem = { href: string; title: string; meta?: React.ReactNode };
+export type SearchSection = { title: string; items: SearchItem[] };
+
+// One constant, not a default `= []`: a fresh array each render, read by an effect, re-ran it forever
+// ("Maximum update depth exceeded", review of 0.7.0 in Chromium).
+const NO_SECTIONS: SearchSection[] = [];
+
+export function SearchDialog({ search, initial = NO_SECTIONS, placeholder = "Search…", label = "Search", fallbackHref, shortcut = true, renderItem }: {
+  /** Results for a query. Called at most every 150 ms; an answer to an older query is dropped. */
+  search: (q: string) => Promise<SearchSection[]>;
+  /** What the popup shows before anything is typed (Featurebase: "Trending requests", "Latest updates"). */
+  initial?: SearchSection[];
+  placeholder?: string;
+  label?: string;
+  /** Where the topbar button goes without JavaScript (a search page), used as given. */
+  fallbackHref?: string;
+  /** ⌘K / Ctrl+K and "/" open it. */
+  shortcut?: boolean;
+  renderItem?: (item: SearchItem) => React.ReactNode;
+}) {
+  const [open, setOpen] = useState(false);
+  const [q, setQ] = useState("");
+  const [sections, setSections] = useState<SearchSection[]>(initial);
+  const [active, setActive] = useState(0);
+  const [busy, setBusy] = useState(false);
+  const ref = useRef<HTMLDialogElement>(null);
+  const input = useRef<HTMLInputElement>(null);
+  const seq = useRef(0);
+  const listId = useId();
+  const flat = sections.flatMap((s) => s.items);
+  // The latest `search` and `initial`, read when needed: a consumer's inline arrow or array (a new one
+  // each render) must not restart the debounce or the effect.
+  const searchRef = useRef(search);
+  const initialRef = useRef(initial);
+  searchRef.current = search;
+  initialRef.current = initial;
+
+  const show = useCallback(() => {
+    const d = ref.current;
+    if (d && !d.open) { d.showModal(); setOpen(true); requestAnimationFrame(() => input.current?.focus()); }
+  }, []);
+  useEffect(() => {
+    if (!shortcut) return undefined;
+    const onKey = (e: KeyboardEvent) => {
+      const t = e.target as HTMLElement | null;
+      const typing = !!t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName));
+      // A handler that already took the key (the admin's own ⌘K palette) keeps it.
+      if (e.defaultPrevented) return;
+      if ((e.key === "k" && (e.metaKey || e.ctrlKey)) || (e.key === "/" && !typing)) { e.preventDefault(); show(); }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [shortcut, show]);
+  useEffect(() => {
+    if (!open) return undefined;
+    const query = q.trim();
+    // Every change takes a new number: an answer still on its way for an older query is dropped,
+    // including when the box was just cleared (it used to land under an empty box).
+    const mine = ++seq.current;
+    if (!query) { setSections(initialRef.current); setActive(0); setBusy(false); return undefined; }
+    setBusy(true);
+    const t = setTimeout(async () => {
+      try {
+        const res = await searchRef.current(query);
+        if (mine === seq.current) { setSections(res); setActive(0); }
+      } catch {
+        if (mine === seq.current) setSections(NO_SECTIONS);
+      } finally {
+        if (mine === seq.current) setBusy(false);
+      }
+    }, 150);
+    return () => { clearTimeout(t); if (mine === seq.current) setBusy(false); };
+  }, [q, open]);
+  // Before anything is typed, show the latest suggestions the page passed.
+  useEffect(() => { if (open && !q.trim()) setSections(initial); }, [initial, open, q]);
+  // The highlighted result stays in view as the arrows move it.
+  useEffect(() => {
+    if (!open) return;
+    document.getElementById(`${listId}-${active}`)?.scrollIntoView({ block: "nearest" });
+  }, [active, open, listId]);
+
+  const go = (item: SearchItem | undefined) => { if (item) window.location.assign(item.href); };
+  let n = -1;
+  return (
+    <>
+      <a className="gb-search-trigger" href={fallbackHref ?? "#"} aria-label={label} aria-haspopup="dialog"
+        onClick={(e) => { e.preventDefault(); show(); }}>
+        <Icon name="search" size={18} />
+      </a>
+      <dialog ref={ref} className="ui-modal gb-search" aria-label={label}
+        onClose={() => { setOpen(false); setQ(""); }}
+        onClick={(e) => { if (e.target === e.currentTarget) e.currentTarget.close(); }}>
+        <div className="gb-search-box">
+          <Icon name="search" size={18} className="gb-search-icon" />
+          <input ref={input} className="gb-search-input" type="search" placeholder={placeholder} aria-label={label}
+            value={q} onChange={(e) => setQ(e.target.value)} role="combobox" aria-expanded="true" aria-controls={listId}
+            aria-activedescendant={flat[active] ? `${listId}-${active}` : undefined} autoComplete="off"
+            onKeyDown={(e) => {
+              if (e.key === "ArrowDown") { e.preventDefault(); setActive((a) => Math.min(a + 1, flat.length - 1)); }
+              else if (e.key === "ArrowUp") { e.preventDefault(); setActive((a) => Math.max(a - 1, 0)); }
+              // Enter that confirms an IME composition (Vietnamese, Chinese) is not "open".
+              else if (e.key === "Enter" && !e.nativeEvent.isComposing && e.keyCode !== 229) { e.preventDefault(); go(flat[active]); }
+            }} />
+        </div>
+        <p className="gb-search-empty" aria-live="polite">
+          {sections.every((s) => !s.items.length) && q.trim() ? (busy ? "Searching…" : "Nothing matches.") : ""}
+        </p>
+        <div className="gb-search-results" id={listId} role="listbox" aria-busy={busy}>
+          {sections.filter((s) => s.items.length).map((s) => (
+            <div key={s.title} className="gb-search-section" role="group" aria-label={s.title}>
+              <div className="gb-search-section-title">{s.title}</div>
+              {s.items.map((it) => {
+                n += 1;
+                const i = n;
+                return (
+                  <a key={`${s.title}-${it.href}`} id={`${listId}-${i}`} href={it.href} role="option" aria-selected={i === active}
+                    className={cx("gb-search-item", i === active && "is-active")} onMouseMove={() => setActive(i)}>
+                    {renderItem ? renderItem(it) : (<><span className="gb-search-item-title">{it.title}</span>{it.meta ? <span className="gb-search-item-meta">{it.meta}</span> : null}</>)}
+                  </a>
+                );
+              })}
+            </div>
+          ))}
+        </div>
+        <div className="gb-search-foot" aria-hidden="true"><span>↵ open</span><span>↑↓ move</span><span>esc</span></div>
+      </dialog>
+    </>
+  );
+}

package/src/selection.tsx

@@ -7,6 +7,7 @@
  *
  * No "use client" of its own: only the two client modules import it (a server graph never reaches its hooks).
  */
+import "./collections.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
 import React, { useCallback, useEffect, useRef, useState } from "react";
 
 export type BulkAction = { content: React.ReactNode; onAction: (ids: string[]) => void; tone?: "critical" };

package/src/setup-guide.css

@@ -0,0 +1 @@
+.ui-setup,.ui-setup__inner{display:grid;gap:var(--ui-space-3, 12px)}.ui-setup__head,.ui-setup__row{display:flex;align-items:center;gap:var(--ui-space-3, 12px);list-style:none;cursor:pointer;border-radius:var(--ui-radius-md, 8px);color:inherit;transition:background-color .12s ease}.ui-setup__head::-webkit-details-marker,.ui-setup__row::-webkit-details-marker{display:none}div.ui-setup__head{cursor:auto}summary.ui-setup__head{padding:6px 8px;margin:-6px -8px 0}.ui-setup__title{margin:0;font-size:var(--ui-fs-body, 13px);line-height:20px;font-weight:650;color:var(--ui-text-strong, var(--ui-text))}.ui-setup__desc{margin:0;font-size:var(--ui-fs-body, 13px);line-height:20px;color:var(--ui-text-muted)}.ui-setup__row{padding:8px;margin:0 -8px}summary.ui-setup__head:hover,summary.ui-setup__row:hover{background:var(--ui-surface-2, #eceef2)}.ui-setup__row--static{cursor:auto}.ui-setup__row.ui-setup__row--static:after{content:none}summary.ui-setup__head:active,summary.ui-setup__row:active{background:var(--ui-border, #e5e7ea)}summary.ui-setup__head:focus-visible,summary.ui-setup__row:focus-visible{outline:2px solid var(--ui-focus, #5661f5);outline-offset:2px}summary.ui-setup__head:after,.ui-setup__row:after{content:"\25be";margin-left:auto;font-size:11px;color:var(--ui-text-muted);transition:transform .12s ease}.ui-setup:not([open])>summary.ui-setup__head:after,.ui-setup__step:not([open])>.ui-setup__row:after{transform:rotate(-90deg)}.ui-setup__bar{appearance:none;-webkit-appearance:none;display:block;width:100%;height:6px;border:0;border-radius:999px;overflow:hidden;background:var(--ui-border, #e5e7ea);color:var(--ui-accent, #1b1c1e)}.ui-setup__bar::-webkit-progress-bar{background:var(--ui-border, #e5e7ea);border-radius:inherit}.ui-setup__bar::-webkit-progress-value{background:currentColor;border-radius:inherit;transition:width .15s ease}.ui-setup__bar::-moz-progress-bar{background:currentColor;border-radius:inherit}.ui-setup__bar--done{color:var(--ui-success-fg, #007f5f)}.ui-setup__steps{display:grid;gap:2px}.ui-setup__mark{flex:0 0 16px;text-align:center;line-height:20px;color:var(--ui-text-muted)}.ui-setup__step[data-state=done] .ui-setup__mark{color:var(--ui-success-fg, #007f5f)}.ui-setup__label{min-width:0;overflow-wrap:anywhere;font-size:var(--ui-fs-body, 13px);line-height:20px;font-weight:550;color:var(--ui-text)}.ui-setup__step[data-state=done] .ui-setup__label{font-weight:450;color:var(--ui-text-muted)}.ui-setup__body{padding:4px 0 12px 28px;font-size:var(--ui-fs-body, 13px);line-height:20px;color:var(--ui-text)}.ui-setup__body>:first-child{margin-top:0}.ui-setup__body>:last-child{margin-bottom:0}@media (pointer: coarse),(max-width: 47.9975em){summary.ui-setup__head,.ui-setup__row{min-height:44px;box-sizing:border-box}}@media (prefers-reduced-motion: reduce){.ui-setup__head,.ui-setup__row,summary.ui-setup__head:after,.ui-setup__row:after,.ui-setup__bar::-webkit-progress-value{transition:none}}

package/src/setup-guide.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+/**
+ * Setup guide — @gemboss/ui 0.30.0. The admin's "Set up your store" card (apps/admin StoreChecklistCard, Shopify's own
+ * Setup guide) as a component any surface can give its steps to: a title with the count, a bar, and collapsed step
+ * rows of which one is open. Six steps expanded is a wall; collapsed rows scan in a second and the open one is the next
+ * thing worth doing.
+ *
+ * Why it moved here (08/10/2026): gemform's Telegram alerts page drew its own numbered steps (1 The bot, 2 Where alerts
+ * go), the admin has this one in Polaris, and a third surface with a "connect this, then that" page would write a third.
+ *
+ * Native `<details>` all the way down, so a page that writes the markup by hand gets the same behaviour with no script:
+ * the guide is a `<details>` whose `<summary>` folds it away, each step is a `<details name>` of one group, which the
+ * browser keeps to one open at a time. The ROW reveals; what changes something is a button the surface puts in the
+ * step's body (one gesture, one meaning, as in the admin). A step with no body is a plain row, not a toggle that opens
+ * nothing.
+ *
+ * The step open at first is the first one not done, decided ONCE, like the admin: a step's state changing while the
+ * person reads it must not slam it shut (finishing step 1 leaves its confirmation on screen). The bar is a <progress>,
+ * not a width in a style attribute, so it fills under a CSP that forbids inline style.
+ */
+import "./setup-guide.css"; // its own entry (0.30.0)
+import React, { useEffect, useId, useRef, useState } from "react";
+
+const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
+
+/** `unknown`: could not be read, so neither done nor to do; counted apart, never as progress. */
+export type SetupState = "todo" | "done" | "unknown";
+
+export interface SetupStep {
+  id: string;
+  title: React.ReactNode;
+  state?: SetupState;
+  /** What the open step shows: a sentence and the control that does it. Without one the row is not a toggle. */
+  body?: React.ReactNode;
+}
+
+const MARK: Record<SetupState, string> = { done: "✓", todo: "○", unknown: "?" };
+
+export function SetupGuide({ title, description, steps, open, collapsible = true, rememberKey, group, labels, className }: {
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  steps: readonly SetupStep[];
+  /** The step to show open at first; defaults to the first one not done. */
+  open?: string;
+  /** false: the head is a plain heading, the guide cannot be folded away. */
+  collapsible?: boolean;
+  /** Remember a folded guide in localStorage under this key, so someone not setting up today is not asked again on every
+   *  visit. Give each place its own key (folding it on one page is not folding it everywhere). */
+  rememberKey?: string;
+  /** The steps' shared `name`. Defaults to a useId(), unique within one React root; pass one when two guides render in
+   *  separate roots or separate static renders. */
+  group?: string;
+  labels?: { progress?: string; notMeasured?: (n: number) => string };
+  className?: string;
+}) {
+  const auto = useId();
+  const name = group ?? `gb-setup${auto}`;
+  // Decided once (see the header): later renders keep whatever the person opened.
+  const [first] = useState(() => open ?? steps.find((s) => s.state !== "done" && s.body)?.id);
+  const guide = useRef<HTMLDetailsElement>(null);
+  useEffect(() => {
+    const el = guide.current;
+    if (!el || !rememberKey) return undefined;
+    try { if (localStorage.getItem(rememberKey) === "folded") el.open = false; } catch { /* storage blocked: stay open */ }
+    const onToggle = () => { try { localStorage.setItem(rememberKey, el.open ? "open" : "folded"); } catch { /* ignore */ } };
+    el.addEventListener("toggle", onToggle);
+    return () => el.removeEventListener("toggle", onToggle);
+  }, [rememberKey]);
+
+  if (!steps.length) return null; // nothing to set up is no guide, not a "0/0" card
+  const total = steps.length;
+  const done = steps.filter((s) => s.state === "done").length;
+  const unknown = steps.filter((s) => s.state === "unknown").length;
+  const all = done === total;
+  const head = (
+    <>
+      <h2 className="ui-setup__title">{title}</h2>
+      <span className={cx("ui-badge", all ? "ui-badge--success" : "ui-badge--warning")}>{`${done}/${total}`}</span>
+      {unknown > 0 ? <span className="ui-badge">{labels?.notMeasured?.(unknown) ?? `${unknown} not measured`}</span> : null}
+    </>
+  );
+  // One wrapper for everything under the head: a <details> lays out its summary and ONE content slot, so a gap set on
+  // the guide never reaches between the description, the bar and the steps (measured in Chromium 148).
+  const inner = (
+    <div className="ui-setup__inner">
+      {description ? <p className="ui-setup__desc">{description}</p> : null}
+      <progress className={cx("ui-setup__bar", all && "ui-setup__bar--done")} value={done} max={total}
+        aria-label={labels?.progress ?? "Setup progress"}>{`${done}/${total}`}</progress>
+      <div className="ui-setup__steps">
+        {steps.map((s) => {
+          const state = s.state ?? "todo";
+          const row = (as: "summary" | "div") => React.createElement(as, { className: cx("ui-setup__row", as === "div" && "ui-setup__row--static") },
+            <span className="ui-setup__mark" aria-hidden="true">{MARK[state]}</span>,
+            <span className="ui-setup__label">{s.title}</span>);
+          if (!s.body) return <div key={s.id} className="ui-setup__step" data-state={state}>{row("div")}</div>;
+          return (
+            <details key={s.id} className="ui-setup__step" name={name} open={s.id === first} data-state={state}>
+              {row("summary")}
+              <div className="ui-setup__body">{s.body}</div>
+            </details>
+          );
+        })}
+      </div>
+    </div>
+  );
+  if (!collapsible) {
+    return <section className={cx("ui-card ui-setup", className)}><div className="ui-setup__head">{head}</div>{inner}</section>;
+  }
+  return (
+    <details className={cx("ui-card ui-setup", className)} open ref={guide}>
+      <summary className="ui-setup__head">{head}</summary>
+      {inner}
+    </details>
+  );
+}

package/src/theme-script.ts

@@ -0,0 +1,10 @@
+/**
+ * `themeScript` and `THEME_KEY` (@gemboss/ui 0.7.2; their own module since 0.23.0). The script goes in every root
+ * layout's <head>, so it must not bring `ThemeToggle`'s button styles (portal.css) to every route: it brings only the
+ * dark palette it switches on. theme.tsx says the rest.
+ */
+import "./theme-dark.css"; // the palette `data-theme="dark"` turns on (0.23.0)
+
+export const THEME_KEY = "gemboss-theme";
+
+export const themeScript = `(function(){try{var t=localStorage.getItem("${THEME_KEY}");if(t!=="dark"&&t!=="light"){t=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}document.documentElement.setAttribute("data-theme",t)}catch(e){}})();`;

package/src/theme.tsx

@@ -10,15 +10,15 @@
  * every kit class (cards, tags, fields, buttons, the topbar) follows without a rule of its own.
  *
  * Opt-in: a surface without the toggle (the admin) never gets the attribute and stays light.
- * `themeScript` goes in <head> (`<script dangerouslySetInnerHTML={{ __html: themeScript }} />`): it applies
+ * `themeScript` (theme-script.ts since 0.23.0, so a root layout that only needs the script does not take portal.css
+ * with it) goes in <head> (`<script dangerouslySetInnerHTML={{ __html: themeScript }} />`): it applies
  * the stored choice, else the OS's, before the first paint, so a dark page never flashes white.
  */
+import "./theme-dark.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
+import "./portal.css"; // ThemeToggle's button (.gb-theme-toggle) is drawn there
 import React, { useEffect, useState } from "react";
 import { Icon } from "./icons";
-
-export const THEME_KEY = "gemboss-theme";
-
-export const themeScript = `(function(){try{var t=localStorage.getItem("${THEME_KEY}");if(t!=="dark"&&t!=="light"){t=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}document.documentElement.setAttribute("data-theme",t)}catch(e){}})();`;
+import { THEME_KEY } from "./theme-script";
 
 export function ThemeToggle({ labels = { toDark: "Switch to dark mode", toLight: "Switch to light mode" } }: {
   labels?: { toDark: string; toLight: string };