@gemboss/ui 0.13.0 → 0.25.0

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/segmented-click.ts

@@ -0,0 +1,20 @@
+/**
+ * What a click on one segment MEANS.
+ *
+ * A `.ts` beside the `.tsx` for the same reason `zoom-about.ts` sits beside `DesignCanvas.tsx`:
+ * `node:test` strips types but does NOT transform JSX, so anything importable from a component file
+ * is untestable here. A one-line decision left inline in a handler is a decision with no test.
+ *
+ * And it IS a decision: a click on the ALREADY-ACTIVE option clears when the caller offered
+ * `onClear`, and re-selects when it did not. Backwards, and you get a control that cannot be unset —
+ * which is exactly the behaviour the element inspector kept its own private copy of `Segmented` for.
+ */
+export function segmentedClick<T extends string>(
+  active: boolean,
+  value: T,
+  onChange: (v: T) => void,
+  onClear?: () => void,
+): void {
+  if (active && onClear) { onClear(); return; }
+  onChange(value);
+}

package/src/segmented.tsx

@@ -0,0 +1,98 @@
+import type { CSSProperties, ReactNode } from "react";
+import { segmentedClick } from "./segmented-click";
+
+/**
+ * Shared tool-UI segmented control — token-driven (`.ui-seg`), cross-surface. Two forms:
+ *  - <Segmented> text tabs (options + value)
+ *  - <IconSegmented> icon squares (e.g. a grid/list view toggle)
+ * The selected segment uses the accent-soft state.
+ *
+ * In the package since 0.20.0 (was the admin's components/ui/Segmented.tsx): the editor kit's `Seg` (editor/controls)
+ * draws through it too, so the inspector's field switches and the Studio's mode switch are one component, not two with
+ * one look. Its own module and subpath (`@gemboss/ui/segmented`): a surface that draws a switch does not load the shell.
+ *
+ * THE ONLY ONE (06/10/2026). Every "pick one of these" switch in the admin draws through here: the Studio's
+ * Funnel · Canvas · Page, the funnel lens, the canvas's device, the inspector's field switches, the
+ * post-purchase step and device. Before, the same control had nine looks (a dark pill, a dark joined group,
+ * a grey track with a raised tab, …) and two of them sat side by side in one bar. `no-hand-rolled-switch.test.ts`
+ * (in the admin) fails on a new `role="group"` of `aria-pressed` buttons anywhere else.
+ */
+export type SegmentedOption<T extends string> = {
+  value: T;
+  label: ReactNode;
+  /** Tooltip; also the reason when the option is off ("Pick a step with a page first"). */
+  title?: string;
+  /** The accessible name when the label alone is not the full sentence (a count badge, an icon). */
+  ariaLabel?: string;
+  disabled?: boolean;
+};
+
+export function Segmented<T extends string>({
+  options, value, onChange, ariaLabel, disabled, onClear, fill = false, className, style,
+}: {
+  options: SegmentedOption<T>[];
+  value: T | "";
+  onChange: (v: T) => void;
+  ariaLabel: string;
+  /** Greys the whole group while a write is in flight. */
+  disabled?: boolean;
+  /**
+   * Present ⇒ clicking the ALREADY-ACTIVE option clears the setting instead of re-selecting it.
+   *
+   * A separate callback rather than widening `onChange` to `(v: T | "")`. Widening would break the
+   * four surfaces already passing a `(v: T) => void` handler — under `strictFunctionTypes` that is
+   * not assignable — and the alternative, calling `onChange("" as T)`, is a lie about the type in a
+   * component four other surfaces read. A clearing control is a different verb; it gets its own prop.
+   */
+  onClear?: () => void;
+  /** Stretch to the row and share it equally: a field switch in the inspector's narrow column. */
+  fill?: boolean;
+  /** A hook class beside `ui-seg` (the editor kit's `gemboss-ei-seg`, which editor-plain.js finds). Never a look. */
+  className?: string;
+  /** On the group: the inspector narrows a two-option row with a max-width. */
+  style?: CSSProperties;
+}) {
+  return (
+    <div className={`ui-seg${fill ? " ui-seg--fill" : ""}${className ? ` ${className}` : ""}`} style={style} role="group" aria-label={ariaLabel || undefined}>
+      {options.map((o) => {
+        const active = value === o.value;
+        return (
+          <button
+            key={o.value}
+            type="button"
+            // What a page without React reads back (editor-plain.js): the label can be anything.
+            data-value={o.value}
+            disabled={disabled || o.disabled}
+            title={o.title}
+            aria-label={o.ariaLabel}
+            aria-pressed={active}
+            className={`is-text${active ? " active" : ""}`}
+            onClick={() => segmentedClick(active, o.value, onChange, onClear)}
+          >
+            {o.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+export function IconSegmented<T extends string>({
+  options, value, onChange, ariaLabel,
+}: {
+  /** `ariaLabel` is also the tooltip: an icon says nothing to a mouse until it is named. */
+  options: { value: T; icon: ReactNode; ariaLabel: string }[];
+  value: T;
+  onChange: (v: T) => void;
+  ariaLabel: string;
+}) {
+  return (
+    <div className="ui-seg" role="group" aria-label={ariaLabel}>
+      {options.map((o) => (
+        <button key={o.value} type="button" className={value === o.value ? "active" : ""} onClick={() => onChange(o.value)} aria-label={o.ariaLabel} title={o.ariaLabel} aria-pressed={value === o.value}>
+          {o.icon}
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/selection.tsx

@@ -0,0 +1,79 @@
+/**
+ * Selection for the collections (0.16.0), and the bulk bar that acts on it: the rules IndexTable and SelectableResourceList share, in one place (README
+ * "Collections"): own or controlled ids; Shift+click takes the range from the last box clicked (the anchor is an id, so
+ * a re-sort cannot move it; an anchor that left the rows starts over); select-all; Escape clears while focus is in the
+ * root, unless an open ⋯ menu or dialog inside it takes that Escape first. The ids handed out are in the rows' order and
+ * only the ones shown (a filtered-away id does not count).
+ *
+ * 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" };
+
+/** Escape belongs to these first, when they are OPEN and shown (a closed `<dialog>` or a hidden menu in a row does not take it). */
+export const ESCAPE_OWNERS = 'details[open], dialog[open], [role="dialog"], [role="menu"]';
+
+/** Is this Escape for a menu or a dialog in `root` rather than for the selection? */
+export function escapeTaken(root: Element, target: EventTarget | null): boolean {
+  const t = target as Element | null;
+  if (t && typeof t.closest === "function" && t.closest(ESCAPE_OWNERS)) return true;
+  return Array.from(root.querySelectorAll(ESCAPE_OWNERS)).some((e) => e.getClientRects().length > 0);
+}
+
+export function useSelection<R extends HTMLElement>(ids: string[], selectedProp: string[] | undefined, onSelectionChange: ((ids: string[]) => void) | undefined, enabled: boolean) {
+  const [own, setOwn] = useState<string[]>([]);
+  const selected = selectedProp ?? own;
+  const setSelected = useCallback((next: string[]) => { if (!selectedProp) setOwn(next); onSelectionChange?.(next); }, [selectedProp, onSelectionChange]);
+  const rootRef = useRef<R>(null);
+  const anchorRef = useRef<string | null>(null);
+  const selSet = new Set(selected);
+  const chosen = ids.filter((id) => selSet.has(id));
+  const n = chosen.length;
+  const all = n > 0 && n === ids.length, some = n > 0 && !all;
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root || !enabled) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape" || e.defaultPrevented || n === 0 || escapeTaken(root, e.target)) return;
+      setSelected([]);
+    };
+    root.addEventListener("keydown", onKey);
+    return () => root.removeEventListener("keydown", onKey);
+  }, [n, enabled, setSelected]);
+  const toggle = (i: number, on: boolean, shift: boolean) => {
+    const next = new Set(selected);
+    const from = anchorRef.current ? ids.indexOf(anchorRef.current) : -1;
+    if (shift && from > -1) {
+      for (let k = Math.min(from, i); k <= Math.max(from, i); k++) { if (on) next.add(ids[k]); else next.delete(ids[k]); }
+    } else if (on) next.add(ids[i]); else next.delete(ids[i]);
+    anchorRef.current = ids[i];
+    setSelected(ids.filter((x) => next.has(x)));
+  };
+  const toggleAll = (on: boolean) => { anchorRef.current = null; setSelected(on ? ids : []); };
+  return { rootRef, selSet, chosen, n, all, some, toggle, toggleAll };
+}
+
+/** The bulk bar: its own select-all box, "n selected", the actions (they get the chosen ids). `idle` says what it does
+ *  with nothing selected: "hide" (a table: it covers the header only while rows are selected) or "disable" (a list: it
+ *  is the list's header, there from the start, its actions off). */
+export function BulkBar({ actions, chosen, all, some, onToggleAll, selectedLabel, selectAllLabel, idle, boxDisabled }: {
+  actions: BulkAction[]; chosen: string[]; all: boolean; some: boolean; onToggleAll: (on: boolean) => void;
+  selectedLabel: (n: number) => React.ReactNode; selectAllLabel: string; idle: "hide" | "disable"; boxDisabled?: boolean }) {
+  const box = useRef<HTMLInputElement>(null);
+  useEffect(() => { if (box.current) box.current.indeterminate = some; }, [some]);
+  const n = chosen.length;
+  return (
+    <div className="ui-bulkbar" hidden={idle === "hide" && n === 0}>
+      <label className="ui-table__checkbox"><input ref={box} type="checkbox" checked={all} aria-label={selectAllLabel} disabled={boxDisabled} onChange={(e) => onToggleAll(e.target.checked)} /></label>
+      <span className="ui-bulkbar__count" aria-live="polite">{selectedLabel(n)}</span>
+      <span className="ui-bulkbar__actions">
+        {actions.map((b, i) => (
+          <button key={i} type="button" className={b.tone === "critical" ? "ui-btn ui-btn--sm ui-btn--critical" : "ui-btn ui-btn--sm"}
+            disabled={idle === "disable" && n === 0} onClick={() => b.onAction(chosen)}>{b.content}</button>
+        ))}
+      </span>
+    </div>
+  );
+}