@gemboss/ui 0.34.3 → 0.35.0

package/src/settings-dialog.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+/**
+ * SettingsDialog — @gemboss/ui 0.35.0. Settings as ONE popup over the app, the admin's shape (apps/admin
+ * SettingsDialog, "Claude's and Shopify's settings"): sections in a rail on the left with a search box, the chosen
+ * section on the right, the close button in the corner; under 861px the rail becomes a strip above the section.
+ *
+ * Why in the package (Chris 12/10/2026, partner-radar: "settings thì bật popup theo chuẩn của gemboss ui"): the admin
+ * drew it with its own module CSS, GemWatcher copied that file (#400, and noted the package's Dialog could not do it
+ * because it always draws a title row), and partner-radar would have been the third copy.
+ *
+ * It is the SHELL only: no settings of its own, no data. The surface gives the sections and renders the active one as
+ * `children`. A section is a button (`onSelect`, the dialog keeps it on screen) or a link (`href` drawn with `linkAs`,
+ * for a surface whose sections are routes). Opening and closing go through the same hook as `Dialog` and `Sheet`
+ * (`useModalDialog`): Escape, a press on the backdrop, the inert page, focus back to the opener; the page behind holds
+ * still while it is open.
+ */
+import "./settings-dialog.css";
+import React, { useEffect, useId, useMemo, useState } from "react";
+import { Icon } from "./icons";
+import { useModalDialog } from "./dialog";
+
+const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
+
+export interface SettingsSectionItem {
+  id: string;
+  title: string;
+  /** Under the section's title in the pane head. */
+  description?: string;
+  /** Rail heading the section sits under; sections of one group are given together, in order. */
+  group?: string;
+  /** A 16px icon (`<Icon name="…" />`). */
+  icon?: React.ReactNode;
+  /** More words the search box matches (title, description and group are matched already). */
+  keywords?: string;
+  /** A link instead of a button: the surface's own route for the section, drawn with `linkAs`. */
+  href?: string;
+}
+
+interface SettingsDialogBase {
+  open: boolean;
+  /** Every way it closes: Escape, ✕, a press on the backdrop, a foot link, and `open` turning false. Keep it idempotent. */
+  onClose: () => void;
+  activeId: string;
+  /** What draws `href` sections and foot links (Next's Link); a plain <a> without it. Gets `href`, `className`, `aria-current`, `onClick`, `children`. */
+  linkAs?: React.ElementType;
+  /** Links at the foot of the rail (pages that live outside settings). Following one closes the popup. */
+  footLinks?: Array<{ href: string; title: string; icon?: React.ReactNode }>;
+  /** The active section. */
+  children?: React.ReactNode;
+  /** The measure of the section's content: `form` 662px (one column of fields), `default` 900px, `full` the pane. A form set
+   *  1,500px wide at 1920 is not a wider form, it is an unreadable one (the admin's own note). */
+  measure?: "form" | "default" | "full";
+  searchLabel?: string;
+  closeLabel?: string;
+  railLabel?: string;
+  /** The rail's line when nothing matches. */
+  noMatch?: (query: string) => React.ReactNode;
+  /** Where focus goes on close when the element that opened it is gone (a menu item, a palette row): a selector. */
+  returnFocusTo?: string;
+  className?: string;
+}
+
+/** Button sections need `onSelect`; a surface whose sections are all links (`href`) leaves it out. A button with nothing to
+ *  call would look chosen and do nothing (INERT), so the types refuse it. */
+export type SettingsDialogProps = SettingsDialogBase & (
+  | { sections: SettingsSectionItem[]; onSelect: (id: string) => void }
+  | { sections: Array<SettingsSectionItem & { href: string }>; onSelect?: undefined }
+);
+
+const MEASURE_CLASS = { form: "ui-settings__measure ui-settings__measure--form", default: "ui-settings__measure", full: "ui-settings__measure ui-settings__measure--full" };
+
+export function SettingsDialog({
+  open, onClose, sections, activeId, onSelect, linkAs: LinkAs = "a", footLinks = [], children, measure = "default",
+  searchLabel = "Search settings", closeLabel = "Close settings", railLabel = "Settings sections",
+  noMatch = (q) => <>No setting matches “{q}”.</>, returnFocusTo = "[data-settings-trigger]", className,
+}: SettingsDialogProps) {
+  // The popup itself takes focus on open (as Sheet): its first control would be ✕ or, on a phone, the search box that pulls
+  // up the keyboard. Tab goes to the search box next; ✕ is last in the order, drawn in the corner.
+  const [query, setQuery] = useState("");
+  // Each opening starts from the whole rail: a query typed (or autofilled) last time would hide every section (review #4073).
+  // Cleared when it CLOSES, not only when `open` turns true: the close event is a queued task, and a reopen that lands before
+  // the surface's onClose leaves `open` true throughout (measured in CI).
+  const { ref, onClick, onPointerDown } = useModalDialog(open, () => { setQuery(""); onClose(); }, { focusPanel: true, returnFocusTo });
+  const titleId = useId();
+  useEffect(() => { if (open) setQuery(""); }, [open]);
+  const groups = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    const out: Array<{ title: string; sections: SettingsSectionItem[] }> = [];
+    for (const s of sections as SettingsSectionItem[]) {
+      const g = s.group ?? "";
+      if (q && !`${s.title} ${s.description ?? ""} ${s.keywords ?? ""} ${g}`.toLowerCase().includes(q)) continue;
+      const last = out[out.length - 1];
+      if (last && last.title === g) last.sections.push(s);
+      else out.push({ title: g, sections: [s] });
+    }
+    return out;
+  }, [sections, query]);
+  // No silent fallback to the first section: the rail, the title and the popup's name would describe one section while the
+  // surface's children show another (review #4073).
+  const active = (sections as SettingsSectionItem[]).find((s) => s.id === activeId);
+  const close = () => ref.current?.close();
+  const item = (s: SettingsSectionItem) => {
+    const on = s.id === active?.id;
+    const inner = <>{s.icon}<span className="ui-settings__label">{s.title}</span></>;
+    const cls = cx("ui-settings__item", on && "ui-settings__item--active");
+    return s.href
+      ? <LinkAs key={s.id} href={s.href} className={cls} aria-current={on ? "page" : undefined}>{inner}</LinkAs>
+      : <button key={s.id} type="button" className={cls} aria-current={on ? "true" : undefined} onClick={() => onSelect?.(s.id)}>{inner}</button>;
+  };
+  return (
+    <dialog ref={ref} className={cx("ui-modal ui-modal--lg ui-settings", className)} aria-labelledby={titleId} tabIndex={-1} onClick={onClick} onPointerDown={onPointerDown}>
+      <div className="ui-settings__layout">
+        <nav className="ui-settings__rail" aria-label={railLabel}>
+          <div className="ui-settings__search">
+            {/* The kit's field made of parts: the label is the box (one 44px target under a thumb), the input draws nothing.
+                autoComplete off + its own name: Chrome filled the signed-in email into the admin's box (07/10/2026) and
+                the dialog opened on "No setting matches <email>". */}
+            <label className="gemboss-field gemboss-field--group">
+              <Icon name="search" size={16} />
+              <input className="gemboss-field__bare" type="search" name="settings-search" autoComplete="off" value={query}
+                onChange={(e) => setQuery(e.target.value)} placeholder={searchLabel} aria-label={searchLabel}
+                // A search field's own Escape only clears the words, and the popup needed a second press (the defect
+                // SearchDialog fixed in #3945): one Escape closes, as everywhere else in the popup.
+                onKeyDown={(e) => { if (e.key === "Escape") { e.preventDefault(); close(); } }} />
+            </label>
+          </div>
+          <div className="ui-settings__scroll">
+            {groups.length === 0 ? <p className="ui-settings__empty">{noMatch(query)}</p> : groups.map((g, i) => (
+              <div key={`${i}:${g.title}`} className="ui-settings__group">
+                {g.title ? <h3 className="ui-settings__group-title">{g.title}</h3> : null}
+                {g.sections.map(item)}
+              </div>
+            ))}
+          </div>
+          {footLinks.length ? (
+            <div className="ui-settings__foot">
+              {footLinks.map((l) => (
+                // A page outside settings: following it closes the popup, or it would stay over the new page (inert).
+                <LinkAs key={l.href} href={l.href} className="ui-settings__item" onClick={close}>{l.icon}<span className="ui-settings__label">{l.title}</span></LinkAs>
+              ))}
+            </div>
+          ) : null}
+        </nav>
+        <section className="ui-settings__pane" aria-labelledby={titleId}>
+          <div className="ui-settings__pane-head">
+            <h2 className="ui-settings__pane-title" id={titleId}>{active?.title}</h2>
+            {active?.description ? <p className="ui-settings__pane-sub">{active.description}</p> : null}
+          </div>
+          {/* Keyed by section: a new section opens at its top, not at the scroll position of the last one. */}
+          <div key={active?.id ?? ""} className="ui-settings__pane-body"><div className={MEASURE_CLASS[measure]}>{children}</div></div>
+        </section>
+      </div>
+      <button type="button" className="ui-modal__close ui-settings__close" aria-label={closeLabel} onClick={close}>
+        <Icon name="close" size={20} />
+      </button>
+    </dialog>
+  );
+}

package/src/sheet.css

@@ -0,0 +1 @@
+dialog.ui-modal.ui-sheet{margin:0 0 0 auto;inset-block:0;padding:0;box-sizing:border-box;width:min(560px,100%);max-width:100%;height:100dvh;max-height:100dvh;border-width:0 0 0 1px;border-radius:0}dialog.ui-modal.ui-sheet.ui-sheet--wide{width:min(760px,100%)}dialog.ui-modal.ui-sheet[open]{display:flex;flex-direction:column;animation:ui-sheet-in .2s cubic-bezier(.2,.8,.2,1)}dialog.ui-modal.ui-sheet>.ui-modal__head,dialog.ui-modal.ui-sheet>.ui-modal__foot{flex:none}dialog.ui-modal.ui-sheet>.ui-modal__body{flex:1 1 auto;min-height:0;overflow:auto;overscroll-behavior:contain}dialog.ui-modal.ui-sheet:focus{outline:none}dialog.ui-modal.ui-sheet::backdrop{background:#0000004d}@keyframes ui-sheet-in{0%{transform:translate(100%)}}@media (prefers-reduced-motion: reduce){dialog.ui-modal.ui-sheet[open]{animation:none}}@media (max-width: 47.9975em){dialog.ui-modal.ui-sheet,dialog.ui-modal.ui-sheet.ui-sheet--wide{width:100%;border-left-width:0}}

package/src/sheet.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+/**
+ * Sheet — @gemboss/ui 0.35.0. The kit popup docked to the right edge, full height: a record opened over the list
+ * it came from (a person, an organisation, an app), read, then closed back to the same scroll position. Chris
+ * 12/10/2026 on partner-radar: "bấm vào people của từng người nên trượt ra side popup".
+ *
+ * Why not one of the others: `Dialog` is centred and covers the middle of the list; `EditorDrawer` (@gemboss/ui/editor)
+ * has the right shape but is the editor's own (no Escape, focus stays behind, brings editor.css); the assistant's side
+ * panel belongs to the assistant.
+ *
+ * It IS `Dialog` (dialog.tsx), same markup and behaviour, with `ui-sheet` on it: sheet.css moves it to the right edge,
+ * the full height, slides it in, and makes it the whole screen on a phone. Two differences in what it asks of Dialog:
+ * the head's subtitle and actions (the link to the record's full page) are the common case here, and on open the panel
+ * itself takes focus, so the Enter that opened the row does not, pressed again, follow that link.
+ */
+import "./sheet.css";
+import React from "react";
+import { Dialog, type DialogProps } from "./dialog";
+
+const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
+
+export type SheetProps = Omit<DialogProps, "focusPanel">;
+
+/** `wide`: 760px instead of 560px, a record whose body holds a table. */
+export function Sheet({ wide = false, className, ...rest }: SheetProps) {
+  return <Dialog {...rest} className={cx("ui-sheet", wide && "ui-sheet--wide", className)} focusPanel />;
+}