@gemboss/ui 0.36.1 → 0.40.0

package/src/editor/index.ts

@@ -36,10 +36,10 @@ export {
   type FieldProps, type InspectorGroupProps, type PanelHeaderProps, type PanelTab, type PanelTabsProps,
 } from "./panel";
 export {
-  ChipButton, ColorControl, EdgeBox, ImageControl, RangeControl, Seg,
-  type ColorControlProps, type EdgeBoxProps, type EdgeSide, type ImageControlProps, type RangeControlProps, type SegOption, type SegProps,
+  ChipButton, ColorControl, EdgeBox, ImageControl, RangeControl, Seg, UnitField, ValueControl,
+  type ColorControlProps, type EdgeBoxProps, type EdgeSide, type ImageControlProps, type RangeControlProps, type SegOption, type SegProps, type UnitFieldProps, type ValueControlProps,
 } from "./controls";
-export { swatchState, type SwatchState } from "./swatch";
+export { swatchState, swatchWhy, type SwatchState } from "./swatch";
 export { cssUrl } from "./css-url";
 // Step 4 (0.22.0): the page's layers and the drawer (`layers`, stateless; the page editor draws them), a list whose rows
 // reorder (`sortable`, "use client": a drag holds state; no admin screen uses it), and the element outline (`tree`, the
@@ -48,5 +48,9 @@ export {
   EditorDrawer, LayerList, layerName,
   type EditorDrawerProps, type LayerItem, type LayerListProps,
 } from "./layers";
-export { SortableLayerList, type SortableLayerListProps } from "./sortable";
+export { SortableLayerList, type SortableLayerListProps, useRowDrag, dropIndex } from "./sortable";
+// 16/10/2026: a setting that is a list, as rows (drag, duplicate, fold); its own CSS part, editor-repeater.css.
+export { RepeaterList, useKeyedRows, type RepeaterListProps, type KeyedRows } from "./repeater";
+// 16/10/2026: a closed choice of shapes (an image's ratio, a layout) as picture tiles; its own CSS part, editor-tiles.css.
+export { ChoiceTiles, type ChoiceTile, type ChoiceTilesProps } from "./tiles";
 export { LayerTree, type LayerTreeProps, type LayerTreeRow } from "./tree";

package/src/editor/panel.tsx

@@ -5,7 +5,7 @@
 // InspectorGroup's own open/closed when the caller does not hold it. Controls (Seg, Color, Range, EdgeBox, Image) are
 // controls.tsx: their own module, because only a screen that edits values draws them.
 import "../editor.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
-import { useState } from "react";
+import { useId, useState } from "react";
 import type React from "react";
 
 // ── PanelTabs ───────────────────────────────────────────────────────────────────────────────────────────────────────
@@ -112,7 +112,7 @@ export function PanelAction({ label, title, disabled, onClick, children }: {
 // ── InspectorGroup ──────────────────────────────────────────────────────────────────────────────────────────────────
 
 export interface InspectorGroupProps {
-  /** The header: 11px / 700, uppercase, muted (`.gemboss-ei-gh`). */
+  /** The header: 13px / 650, sentence case (`.gemboss-ei-gh`). */
   title?: React.ReactNode;
   /** A short aside after the title, in the header's own line ("· all screens"). Collapsible groups only. */
   note?: React.ReactNode;
@@ -129,15 +129,21 @@ export interface InspectorGroupProps {
   collapsible?: boolean;
   /** A muted line after the body (`p.gemboss-ei-hint`). */
   hint?: React.ReactNode;
+  /**
+   * `data-*` attributes on the group itself (`.gemboss-ei-grp`, or the static `section`): what a page finds the group by, without a
+   * wrapper. A wrapper made every group the `:last-child` of its own parent, so the divider between groups was dropped (control
+   * standard §13b, 19/10/2026).
+   */
+  attrs?: Record<`data-${string}`, string>;
   children?: React.ReactNode;
 }
 
-export function InspectorGroup({ title, note, open, defaultOpen = true, onOpenChange, collapsible = true, hint, children }: InspectorGroupProps) {
+export function InspectorGroup({ title, note, open, defaultOpen = true, onOpenChange, collapsible = true, hint, attrs, children }: InspectorGroupProps) {
   const [own, setOwn] = useState(defaultOpen);
   const hintNode = hint ? <p className="gemboss-ei-hint">{hint}</p> : null;
   if (!collapsible) {
     return (
-      <section className="gemboss-ei-group">
+      <section className="gemboss-ei-group" {...attrs}>
         {title ? <h4 className="gemboss-ei-grouphead">{title}</h4> : null}
         {children}
         {hintNode}
@@ -146,7 +152,7 @@ export function InspectorGroup({ title, note, open, defaultOpen = true, onOpenCh
   }
   const isOpen = open ?? own;
   return (
-    <div className="gemboss-ei-grp">
+    <div className="gemboss-ei-grp" {...attrs}>
       <button type="button" className="gemboss-ei-gh" data-open={isOpen ? "open" : "closed"} aria-expanded={isOpen}
         onClick={() => { if (open === undefined) setOwn(!isOpen); onOpenChange?.(!isOpen); }}>
         <span className="gemboss-ei-chev" aria-hidden>{isOpen ? "▾" : "▸"}</span>{title}
@@ -161,29 +167,53 @@ export function InspectorGroup({ title, note, open, defaultOpen = true, onOpenCh
 // ── Field ───────────────────────────────────────────────────────────────────────────────────────────────────────────
 
 export interface FieldProps {
-  /** 13px / 500 above the control. `undefined` / `null` draws no label (a control named by its own aria-label). */
+  /** 13px above the control (beside it in a `row`). `undefined` / `null` draws no label (a control named by its own aria-label). */
   label?: React.ReactNode;
   /** The control's id, so a click on the label focuses it. */
   htmlFor?: string;
   /** A value shown at the label's right edge, bold and tabular (a range's current value: `.gemboss-ei-rangeval`). */
   labelValue?: React.ReactNode;
-  /** A muted line under the control (`p.gemboss-ei-hint`). Put it in `children` instead to place it elsewhere. */
+  /** The setting's help (`p.gemboss-ei-hint.gemboss-ei-help-text`). In a plugin's form a line under the control; inside an
+   *  inspector group (`InspectorGroup`) a ? beside the label opens and closes it (0.39.0). */
   hint?: React.ReactNode;
+  /** A one-value setting (a number, a select, a colour, chips): inside an inspector group the label goes LEFT and the control
+   *  right, one row (0.39.0). Outside a group nothing changes. */
+  row?: boolean;
   /** Added to `.gemboss-ei-fld` (the admin's `togrow`). */
   className?: string;
   style?: React.CSSProperties;
   children?: React.ReactNode;
 }
 
-/** One labelled row of a panel: `div.gemboss-ei-fld` › label · control · hint. 12px under each row but the last. */
-export function Field({ label, htmlFor, labelValue, hint, className, style, children }: FieldProps) {
+/**
+ * One labelled setting: `div.gemboss-ei-fld` › label · control · help. 12px under each but the last.
+ *
+ * INSIDE AN INSPECTOR GROUP (0.39.0, Chris 16/10/2026: the settings panel looked bigger than the kit and Polaris; research
+ * `_local/gemboss/research/inspector-density-2026-10-16.md`). The controls were Polaris-sized already (field 32, chips 28);
+ * the panel was long: a label line over every control (70px a setting) and help text under it, 22% of a countdown's panel.
+ * There a `row` is label left, control right (GemPages: 52px a setting), the label is quiet (bodyMd, secondary) and the help
+ * is behind a ? (GemPages, PageFly). Outside a group, a plugin's settings form, a help line under a wide field is the
+ * Polaris form and stays.
+ */
+export function Field({ label, htmlFor, labelValue, hint, row = false, className, style, children }: FieldProps) {
+  const helpId = useId();
+  const [helpOpen, setHelpOpen] = useState(false);
+  const cls = ["gemboss-ei-fld", row && label != null ? "gemboss-ei-fld--row" : "", className].filter(Boolean).join(" ");
+  const labelNode = label != null ? (
+    <label htmlFor={htmlFor}>{label}{labelValue != null ? <span className="gemboss-ei-rangeval">{labelValue}</span> : null}</label>
+  ) : null;
   return (
-    <div className={className ? `gemboss-ei-fld ${className}` : "gemboss-ei-fld"} style={style}>
-      {label != null ? (
-        <label htmlFor={htmlFor}>{label}{labelValue != null ? <span className="gemboss-ei-rangeval">{labelValue}</span> : null}</label>
-      ) : null}
+    <div className={cls} style={style}>
+      {/* A ? is a button, so it sits BESIDE the label, not in it (a label may hold no other labelable element). */}
+      {hint && labelNode ? (
+        <div className="gemboss-ei-lbl">
+          {labelNode}
+          <button type="button" className="gemboss-ei-help" aria-label={typeof label === "string" ? `About ${label}` : "About this setting"} aria-describedby={helpId} aria-expanded={helpOpen}
+            onClick={() => setHelpOpen((o) => !o)} onKeyDown={(e) => { if (e.key === "Escape") setHelpOpen(false); }}>?</button>
+        </div>
+      ) : labelNode}
       {children}
-      {hint ? <p className="gemboss-ei-hint">{hint}</p> : null}
+      {hint ? <p className="gemboss-ei-hint gemboss-ei-help-text" id={helpId}>{hint}</p> : null}
     </div>
   );
 }

package/src/editor/repeater.tsx

@@ -0,0 +1,322 @@
+"use client";
+// REPEATER LIST (Chris 16/10/2026: the panel was missing pickers; research
+// `_local/gemboss/research/pickers-2026-10-16/pickers.md` §9 and pattern P11). A setting that is a list (an accordion's items,
+// a pricing table's plans, choice cards) is the element's CONTENT, and the panel drew it as boxes always open, moved one place
+// at a time with ↑ ↓. PageFly and GemPages draw it as rows: a grip to drag, the row's name, duplicate, delete, folded until
+// opened. This is that, for every repeater the admin draws (the Canvas panel and the page editor), one look.
+//
+//   · the header is the row: a grip (drag it; HTML drag and drop does not start from a touch, so ↑ ↓ stay), the name (its
+//     first field, else "Item N") as the button that folds it, then ↑ ↓, duplicate and ✕;
+//   · with more than one row the list opens folded; a row that arrives later (added, duplicated) opens, it is the one
+//     being written;
+//   · Alt+↑ / Alt+↓ on a row's name move it, and the focus stays on it;
+//   · the count beside the list's name.
+// A row's body is drawn only while it is open: a folded row holds no controls (check:page-revision-touchable measures every
+// control the panel shows).
+//
+// Rows are kept by KEY (useKeyedRows), not by index: a row's open state and its controls' unsaved typing follow it when it
+// moves, and a field writes to its row by key. The drag is useRowDrag (sortable.tsx), the same rule as the Layers list.
+//
+// ITEMS IN A POPOVER (item management IM1a, Chris 20/10/2026, GemPages 7.5's "Item management" read in its code): with
+// `editIn="popover"` the list stays one line per row and the row picked shows its controls in a layer under the list (the
+// browser's top layer, placed like the kit's menus, menu-layer.ts), one row at a time; the other rows stay in view and a click
+// on one moves the layer to it. It closes on its ✕, on Escape (the focus goes back to the row) or on the row clicked again,
+// never on a click elsewhere: a row's controls open pickers and dialogs of their own. The host hears the row picked
+// (`onActive`), to show that item on the canvas. A row's picture (`thumb`, its first image) sits before its name.
+// One row: its controls show in place, open, as the inline list draws it (nothing to choose between; a layer would cost a click).
+// No popover API: the row picked opens in place, as the inline list does.
+import "../editor.css"; // the field and the 44px rule under a finger (`.gemboss-ei-fld`)
+import "../editor-repeater.css"; // its own part (16/10/2026): a surface that never draws a list never loads it
+import { useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import type React from "react";
+import { canFloatMenus, placeFloating } from "../menu-layer";
+import { useRowDrag } from "./sortable";
+
+let lastKey = 0;
+const freshKey = () => `row-${++lastKey}`;
+
+export interface KeyedRows<T> {
+  /** The rows shown: the stored list, or the one just written while its save is on the way. */
+  rows: readonly T[];
+  /** One stable key per row, in the same order. */
+  keys: readonly string[];
+  move: (from: number, to: number) => void;
+  /** A copy right after it, with a key of its own. */
+  duplicate: (index: number) => void;
+  remove: (index: number) => void;
+  add: (row: T) => void;
+  /**
+   * Change the row with this KEY, from its latest version: `change` gets the row as it is now, not as it was when the field
+   * was drawn. A control that commits late (a colour or a slider holds its write 250 ms, and flushes it when it unmounts)
+   * keeps the key it was drawn with, so a move in between changes the right row, and a removed row is not brought back (no
+   * row with that key: nothing is written). Review of #4506: by index and whole row, that write doubled one row and lost another.
+   */
+  patch: (key: string, change: (row: T) => T) => void;
+}
+
+/**
+ * A stored list with a stable key per row. Each change writes the WHOLE list (`commit`) and shows it at once.
+ *
+ *   · `commit` may answer (a Promise): `false` or a rejection puts the stored list back, unless a later write is on its way
+ *     (its answer decides). Without an answer what was written stays shown until the stored list says otherwise.
+ *   · the stored list is read by CONTENT: a caller that hands a new array each render (`rows ?? []`) does not reset what is
+ *     shown (review of #4506: a row added to an unset list vanished).
+ *   · a stored list equal to one of our writes is that write coming back: what is shown (maybe newer) stays; any other is a
+ *     change from elsewhere (an undo, the chat) and replaces it, the keys kept by position.
+ */
+export function useKeyedRows<T>(value: readonly T[], commit: (next: T[]) => void | PromiseLike<unknown>): KeyedRows<T> {
+  const [state, setState] = useState(() => ({ rows: value.slice(), keys: value.map(() => freshKey()) }));
+  const latest = useRef(state);
+  latest.current = state;
+  const seen = JSON.stringify(value);
+  // The stored list, its text, and the keys it is shown with: what a refused write goes back to.
+  const stored = useRef<{ rows: readonly T[]; json: string; keys: string[] }>({ rows: value, json: seen, keys: state.keys });
+  // Our writes on their way, oldest first.
+  const pending = useRef<Array<{ n: number; json: string; keys: string[] }>>([]);
+  const writes = useRef(0);
+  useEffect(() => {
+    if (seen === stored.current.json) return;
+    const mine = pending.current.findIndex((p) => p.json === seen);
+    if (mine >= 0) {
+      stored.current = { rows: value, json: seen, keys: pending.current[mine]!.keys };
+      pending.current = pending.current.slice(mine + 1);
+      return;
+    }
+    pending.current = [];
+    const keys = value.map((_, i) => latest.current.keys[i] ?? freshKey());
+    stored.current = { rows: value, json: seen, keys };
+    latest.current = { rows: value.slice(), keys };
+    setState(latest.current);
+    // By content (`seen`): a new array with the same rows is not a change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [seen]);
+  const refused = (n: number) => {
+    pending.current = pending.current.filter((p) => p.n !== n);
+    if (n !== writes.current) return;
+    latest.current = { rows: stored.current.rows.slice(), keys: stored.current.keys.slice() };
+    setState(latest.current);
+  };
+  const write = (rows: T[], keys: string[]) => {
+    const n = ++writes.current;
+    pending.current.push({ n, json: JSON.stringify(rows), keys });
+    latest.current = { rows, keys };
+    setState(latest.current);
+    const answer = commit(rows);
+    if (answer && typeof (answer as PromiseLike<unknown>).then === "function") {
+      (answer as PromiseLike<unknown>).then((ok) => { if (ok === false) refused(n); }, () => refused(n));
+    }
+  };
+  const splice = <X,>(xs: readonly X[], at: number, remove: number, ...add: X[]) => { const next = xs.slice(); next.splice(at, remove, ...add); return next; };
+  return {
+    rows: state.rows,
+    keys: state.keys,
+    move: (from, to) => {
+      const { rows, keys } = latest.current;
+      if (from === to || to < 0 || to >= rows.length) return;
+      const r = splice(rows, from, 1), k = splice(keys, from, 1);
+      write(splice(r, to, 0, rows[from]!), splice(k, to, 0, keys[from]!));
+    },
+    duplicate: (index) => {
+      const { rows, keys } = latest.current;
+      if (index < 0 || index >= rows.length) return;
+      write(splice(rows, index + 1, 0, JSON.parse(JSON.stringify(rows[index])) as T), splice(keys, index + 1, 0, freshKey()));
+    },
+    remove: (index) => {
+      const { rows, keys } = latest.current;
+      if (index < 0 || index >= rows.length) return;
+      write(rows.filter((_, n) => n !== index), keys.filter((_, n) => n !== index));
+    },
+    add: (row) => { const { rows, keys } = latest.current; write([...rows, row], [...keys, freshKey()]); },
+    patch: (key, change) => {
+      const { rows, keys } = latest.current;
+      const at = keys.indexOf(key);
+      if (at < 0) return;
+      const next = change(rows[at]!);
+      if (JSON.stringify(next) === JSON.stringify(rows[at])) return;
+      write(rows.map((r, n) => (n === at ? next : r)), keys.slice());
+    },
+  };
+}
+
+export interface RepeaterListProps {
+  /** The list's name ("Cards"), and the noun of its buttons' names ("Move Cards item 2 up"). */
+  label: string;
+  /** Under the name: the setting's sentence. */
+  hint?: React.ReactNode;
+  /** One per row, stable across moves (useKeyedRows). */
+  keys: readonly string[];
+  /** A row's name in its header (its first field); empty says "Item N". */
+  title: (index: number) => string;
+  /** A row's controls, drawn while it is open. */
+  body: (index: number) => React.ReactNode;
+  /** `to` is the index after the move. */
+  onMove: (from: number, to: number) => void;
+  onRemove: (index: number) => void;
+  /** Absent: no duplicate button (a list whose rows must differ). */
+  onDuplicate?: (index: number) => void;
+  /** Absent: no add button. */
+  onAdd?: () => void;
+  /** Default "+ Add item". */
+  addLabel?: string;
+  /** False: the add and duplicate buttons are off (a list at its limit). */
+  canAdd?: boolean;
+  disabled?: boolean;
+  /** Instead of the rows when there are none. Default "No items yet." */
+  empty?: React.ReactNode;
+  /** Attributes on a row's element (a page editor's `data-page-repeater-row`). */
+  rowAttrs?: (index: number) => Record<string, string | number | undefined>;
+  /** 44px buttons with a mouse too (`.gemboss-ei-rep--touch`): a surface whose every control is 44px (the page editor's
+   *  content panel, check:page-revision-touchable). Under a finger they are 44px everywhere. */
+  touch?: boolean;
+  /** A row's picture before its name (its first image field), 20px; empty: none. */
+  thumb?: (index: number) => string | undefined;
+  /** Where a row's controls show: folded open under its header (default), or one row at a time in a layer under the list. */
+  editIn?: "inline" | "popover";
+  /** Popover mode: the row picked (null when none), so the host can show that item. */
+  onActive?: (index: number | null) => void;
+}
+
+// A function, not an element built at import: a page that compiles JSX against a global React (the admin's gates) sets that
+// global after its imports run.
+const DuplicateIcon = () => <svg viewBox="0 0 16 16" width="13" height="13" aria-hidden fill="none" stroke="currentColor" strokeWidth="1.4"><rect x="5.5" y="5.5" width="8" height="8" rx="1.5" /><path d="M10.5 3.5v-.5A1.5 1.5 0 0 0 9 1.5H4A1.5 1.5 0 0 0 2.5 3v5A1.5 1.5 0 0 0 4 9.5h.5" /></svg>;
+
+/** `.gemboss-ei-fld.gemboss-ei-rep` › label (+ count) › `.gemboss-ei-rep-list` › one `.gemboss-ei-rep-item` per row › add. */
+export function RepeaterList({ label, hint, keys, title, body, onMove, onRemove, onDuplicate, onAdd, addLabel = "+ Add item", canAdd = true, disabled, empty, rowAttrs, touch, thumb, editIn = "inline", onActive }: RepeaterListProps) {
+  const uid = useId();
+  // The layer only where there is a row to choose: a list of one shows it in place.
+  const popover = editIn === "popover" && keys.length > 1;
+  // Popover mode: the row picked, by key; the layer floats only where the browser has the popover API (read after the first
+  // paint, so the server's markup and the first client render agree), else the row opens in place.
+  const [active, setActive] = useState<string | null>(null);
+  const [canFloat, setCanFloat] = useState(false);
+  useEffect(() => { setCanFloat(canFloatMenus()); }, []);
+  const activeKey = active !== null && keys.includes(active) ? active : null;
+  const pick = (key: string | null) => { setActive(key); onActive?.(key === null ? null : keys.indexOf(key)); };
+  // A row removed while picked: its layer goes, and the host hears it.
+  useEffect(() => { if (active !== null && !keys.includes(active)) { setActive(null); onActive?.(null); } }, [keys, active, onActive]);
+  const popRef = useRef<HTMLDivElement>(null);
+  const [open, setOpen] = useState<ReadonlySet<string>>(() => new Set(keys.length <= 1 ? keys : []));
+  // A row that arrives after the list was drawn opens. Compared by content: a caller may hand a new array each render.
+  const [seen, setSeen] = useState<readonly string[]>(keys);
+  if (seen.join("\n") !== keys.join("\n")) {
+    const fresh = keys.filter((k) => !seen.includes(k));
+    setSeen(keys);
+    if (fresh.length) setOpen((o) => new Set([...o, ...fresh]));
+  }
+  const toggle = (key: string) => popover
+    ? pick(activeKey === key ? null : key)
+    : setOpen((o) => { const next = new Set(o); if (!next.delete(key)) next.add(key); return next; });
+  const drag = useRowDrag(keys, onMove);
+  // A keyboard move keeps the focus on the moved row's name once it has landed (as SortableLayerList).
+  const refocus = useRef<{ key: string; from: number } | null>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const want = refocus.current;
+    if (!want) return;
+    const at = keys.indexOf(want.key);
+    if (at === want.from) return;
+    refocus.current = null;
+    if (at < 0) return;
+    const row = [...(listRef.current?.children ?? [])].find((r) => (r as HTMLElement).dataset.key === want.key);
+    row?.querySelector<HTMLButtonElement>(".gemboss-ei-rep-toggle")?.focus();
+  }, [keys]);
+  // The layer under the list: in the top layer, as wide as the list, placed again when the panel or the page scrolls or the
+  // window resizes (a scroll inside the layer does not count), so it never floats away from its list.
+  useLayoutEffect(() => {
+    const el = popRef.current, list = listRef.current;
+    if (!el || !list || activeKey === null) return;
+    if (el.getAttribute("popover") !== "manual") el.setAttribute("popover", "manual");
+    if (!el.matches(":popover-open")) el.showPopover();
+    const place = () => { el.style.width = `${Math.round(list.getBoundingClientRect().width)}px`; placeFloating(el, list); };
+    place();
+    el.focus({ preventScroll: true });
+    const onMove = (e: Event) => { if (e.target instanceof Node && el.contains(e.target)) return; place(); };
+    window.addEventListener("scroll", onMove, true);
+    window.addEventListener("resize", onMove);
+    return () => {
+      window.removeEventListener("scroll", onMove, true);
+      window.removeEventListener("resize", onMove);
+      if (el.matches(":popover-open")) el.hidePopover();
+    };
+  }, [activeKey, canFloat, keys.length]);
+  const closeLayer = () => {
+    const key = activeKey;
+    pick(null);
+    const row = [...(listRef.current?.children ?? [])].find((r) => (r as HTMLElement).dataset.key === key);
+    row?.querySelector<HTMLButtonElement>(".gemboss-ei-rep-toggle")?.focus();
+  };
+  const floating = popover && canFloat;
+  const rootClass = ["gemboss-ei-fld gemboss-ei-rep", touch ? "gemboss-ei-rep--touch" : "", popover ? "gemboss-ei-rep--pop" : ""].filter(Boolean).join(" ");
+
+  return (
+    <div className={rootClass}>
+      <label>{label}{keys.length ? <span className="gemboss-ei-rep-count">{keys.length}</span> : null}</label>
+      {hint}
+      {keys.length === 0 ? (empty ?? <p className="gemboss-ei-hint">No items yet.</p>) : (
+        <div className="gemboss-ei-rep-list" ref={listRef}>
+          {keys.map((key, i) => {
+            const picked = popover && activeKey === key;
+            // Inline: its own fold. Popover: the row picked opens in place only where nothing can float.
+            const isOpen = popover ? picked && !canFloat : open.has(key);
+            const name = title(i) || `Item ${i + 1}`;
+            const bodyId = `${uid}-${key}`;
+            const src = thumb?.(i);
+            return (
+              <div key={key} data-key={key} className={["gemboss-ei-rep-item", drag.dragging === key ? "is-dragging" : "", picked ? "is-active" : ""].filter(Boolean).join(" ")}
+                data-drop={drag.dropAt(key)} {...rowAttrs?.(i)}
+                // A list that went off mid-drag (a save started) takes no drop: the move would race that save.
+                onDragOver={disabled ? undefined : drag.over(key)} onDrop={disabled ? drag.end : drag.drop}>
+                <div className="gemboss-ei-rep-head">
+                  {/* Kept while the list is off (a write in flight), inert: taking it away moved every row's name 16px on each save. */}
+                  <span className="gemboss-ei-rep-grip" aria-hidden draggable={!disabled} title={disabled ? undefined : "Drag to reorder"}
+                    onDragStart={disabled ? undefined : (e) => { const row = e.currentTarget.closest(".gemboss-ei-rep-item"); if (row) e.dataTransfer.setDragImage(row, 12, 12); drag.start(key)(e); }}
+                    onDragEnd={drag.end}>⋮⋮</span>
+                  <button type="button" className="gemboss-ei-rep-toggle" aria-expanded={popover ? picked : isOpen}
+                    aria-controls={picked && floating ? `${uid}-pop` : isOpen ? bodyId : undefined}
+                    aria-keyshortcuts={disabled ? undefined : "Alt+ArrowUp Alt+ArrowDown"} onClick={() => toggle(key)}
+                    onKeyDown={(e) => {
+                      if (disabled || !e.altKey || (e.key !== "ArrowUp" && e.key !== "ArrowDown")) return;
+                      const to = e.key === "ArrowUp" ? i - 1 : i + 1;
+                      if (to < 0 || to >= keys.length) return;
+                      e.preventDefault();
+                      refocus.current = { key, from: i };
+                      onMove(i, to);
+                    }}>
+                    {src ? <img className="gemboss-ei-rep-thumb" src={src} alt="" loading="lazy" /> : null}
+                    <span className="gemboss-ei-rep-title">{name}</span>
+                  </button>
+                  <span className="gemboss-ei-rep-acts">
+                    <button type="button" title="Move up" aria-label={`Move ${label} item ${i + 1} up`} disabled={disabled || i === 0} onClick={() => onMove(i, i - 1)}>↑</button>
+                    <button type="button" title="Move down" aria-label={`Move ${label} item ${i + 1} down`} disabled={disabled || i === keys.length - 1} onClick={() => onMove(i, i + 1)}>↓</button>
+                    {onDuplicate ? (
+                      <button type="button" title="Duplicate" aria-label={`Duplicate ${label} item ${i + 1}`} disabled={disabled || !canAdd} onClick={() => onDuplicate(i)}><DuplicateIcon /></button>
+                    ) : null}
+                    <button type="button" title="Remove" aria-label={`Remove ${label} item ${i + 1}`} disabled={disabled} onClick={() => onRemove(i)}>✕</button>
+                  </span>
+                </div>
+                {isOpen ? <div id={bodyId} className="gemboss-ei-rep-body" role="group" aria-label={name}>{body(i)}</div> : null}
+              </div>
+            );
+          })}
+        </div>
+      )}
+      {onAdd ? <button type="button" className="ui-btn gemboss-ei-rep-add" disabled={disabled || !canAdd} onClick={onAdd}>{addLabel}</button> : null}
+      {floating && activeKey !== null ? (() => {
+        const i = keys.indexOf(activeKey);
+        const name = title(i) || `Item ${i + 1}`;
+        return (
+          // A child of the list in the DOM (Tab order, React context, the host's providers), painted in the top layer.
+          <div ref={popRef} id={`${uid}-pop`} className="gemboss-ei-rep-pop gemboss-popover-surface" role="dialog" aria-label={name} tabIndex={-1}
+            onKeyDown={(e) => { if (e.key === "Escape") { e.stopPropagation(); closeLayer(); } }}>
+            <div className="gemboss-ei-rep-pophead">
+              <span className="gemboss-ei-rep-title">{name}</span>
+              <span className="gemboss-ei-rep-popat">{i + 1} / {keys.length}</span>
+              <button type="button" aria-label={`Close ${name}`} onClick={closeLayer}>✕</button>
+            </div>
+            {body(i)}
+          </div>
+        );
+      })() : null}
+    </div>
+  );
+}

package/src/editor/sortable.tsx

@@ -7,18 +7,61 @@
 //     `onMove` answers later, after a server write: the focus waits for the row to reach its new place).
 // The drag is kept by the row's ID, so rows that change under it (a section added by the chat) do not move the wrong one.
 // HTML drag and drop does not start from a touch: a list that must reorder on a phone keeps ↑ / ↓ in its `actions`.
+//
+// The drag itself is `useRowDrag` (16/10/2026), shared with the settings panel's RepeaterList (repeater.tsx), so the two lists
+// reorder by one rule.
 import "../editor.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
 import { useEffect, useRef, useState } from "react";
 import type React from "react";
 import { LayerList, type LayerItem, type LayerListProps } from "./layers";
 
+/** Where a dragged row lands: before or after row `over`, as the index it has once it has left its place. */
+export function dropIndex(from: number, over: number, place: "before" | "after"): number {
+  return place === "before" ? (over > from ? over - 1 : over) : (over >= from ? over : over + 1);
+}
+
+/**
+ * A drag over rows kept by ID. `start(id)` on what is dragged, `over(id)` and `drop` on each row, `end` when it ends;
+ * `dropAt(id)` says which edge of row `id` shows the landing line, `dragging` which row is in the air. `onMove(from, to)`
+ * with `to` the index after the move, only when it moves.
+ */
+export function useRowDrag(ids: readonly string[], onMove: (from: number, to: number) => void) {
+  const [drag, setDrag] = useState<{ id: string; over: string; place: "before" | "after" } | null>(null);
+  const drop = () => {
+    if (!drag) return;
+    const from = ids.indexOf(drag.id), over = ids.indexOf(drag.over);
+    setDrag(null);
+    if (from < 0 || over < 0) return;
+    const to = dropIndex(from, over, drag.place);
+    if (to !== from) onMove(from, to);
+  };
+  return {
+    dragging: drag?.id ?? null,
+    dropAt: (id: string): "before" | "after" | undefined => (drag && drag.over === id && drag.id !== id ? drag.place : undefined),
+    start: (id: string) => (e: React.DragEvent) => {
+      e.dataTransfer.effectAllowed = "move";
+      e.dataTransfer.setData("text/plain", id);
+      setDrag({ id, over: id, place: "before" });
+    },
+    over: (id: string) => (e: React.DragEvent<HTMLElement>) => {
+      if (!drag) return;
+      e.preventDefault();
+      const r = e.currentTarget.getBoundingClientRect();
+      const place = e.clientY < r.top + r.height / 2 ? "before" : "after";
+      if (drag.over !== id || drag.place !== place) setDrag({ ...drag, over: id, place });
+    },
+    drop: (e: React.DragEvent) => { e.preventDefault(); drop(); },
+    end: () => setDrag(null),
+  };
+}
+
 export interface SortableLayerListProps<T extends LayerItem = LayerItem> extends Omit<LayerListProps<T>, "rowProps" | "mainProps" | "lead" | "listRef"> {
   /** A row moved: `to` is its index AFTER the move. */
   onMove: (item: T, to: number) => void;
 }
 
 export function SortableLayerList<T extends LayerItem>({ onMove, items, ...rest }: SortableLayerListProps<T>) {
-  const [drag, setDrag] = useState<{ id: string; over: string; place: "before" | "after" } | null>(null);
+  const drag = useRowDrag(items.map((it) => it.id), (from, to) => onMove(items[from], to));
   // A keyboard move: the row and the index it left. The focus goes back to it once it is somewhere else. Chromium keeps the
   // focus on a node React moves (measured: the Alt+↑/↓ tests pass without this); a browser that runs the DOM's focus
   // fixup on the re-insert would drop it to <body>, so it is put back.
@@ -35,34 +78,17 @@ export function SortableLayerList<T extends LayerItem>({ onMove, items, ...rest
     row?.querySelector<HTMLButtonElement>(".gemboss-layer-main")?.focus();
   }, [items]);
 
-  const indexOf = (id: string) => items.findIndex((it) => it.id === id);
-  const drop = () => {
-    if (!drag) return;
-    const from = indexOf(drag.id), over = indexOf(drag.over);
-    setDrag(null);
-    if (from < 0 || over < 0) return;
-    // The final index: landing before / after row `over`, counted once the dragged row has left its place.
-    const to = drag.place === "before" ? (over > from ? over - 1 : over) : (over >= from ? over : over + 1);
-    if (to !== from) onMove(items[from], to);
-  };
-
   return (
     <LayerList {...rest} items={items} listRef={listRef}
       lead={() => <span className="gemboss-layer-grip" aria-hidden>⋮⋮</span>}
       rowProps={(it) => ({
-        className: drag?.id === it.id ? "is-dragging" : undefined,
-        "data-drop": drag && drag.over === it.id && drag.id !== it.id ? drag.place : undefined,
+        className: drag.dragging === it.id ? "is-dragging" : undefined,
+        "data-drop": drag.dropAt(it.id),
         draggable: true,
-        onDragStart: (e) => { e.dataTransfer.effectAllowed = "move"; e.dataTransfer.setData("text/plain", it.id); setDrag({ id: it.id, over: it.id, place: "before" }); },
-        onDragOver: (e) => {
-          if (!drag) return;
-          e.preventDefault();
-          const r = e.currentTarget.getBoundingClientRect();
-          const place = e.clientY < r.top + r.height / 2 ? "before" : "after";
-          if (drag.over !== it.id || drag.place !== place) setDrag({ ...drag, over: it.id, place });
-        },
-        onDrop: (e) => { e.preventDefault(); drop(); },
-        onDragEnd: () => setDrag(null),
+        onDragStart: drag.start(it.id),
+        onDragOver: drag.over(it.id),
+        onDrop: drag.drop,
+        onDragEnd: drag.end,
       })}
       mainProps={(it, i) => ({
         "aria-keyshortcuts": "Alt+ArrowUp Alt+ArrowDown",

package/src/editor/swatch.ts

@@ -43,3 +43,23 @@ export function swatchState(value: string, whenEmpty = '#000000'): SwatchState {
   if (!value) return { swatch: whenEmpty, usable: true };
   return SWATCHABLE.test(value) ? { swatch: value, usable: true } : { swatch: '#000000', usable: false };
 }
+
+/** The theme's colour tokens a value may name (`var(--gem-color-accent)`), as a seller reads them. */
+const TOKEN_NAMES: Record<string, string> = { text: "Text", accent: "Accent", "accent-text": "Accent text", muted: "Muted", background: "Background",
+  surface: "Surface", border: "Border", success: "Success", warning: "Warning", danger: "Danger" };
+const tokenName = (t: string) => TOKEN_NAMES[t] ?? t.charAt(0).toUpperCase() + t.slice(1).replace(/-/g, " ");
+
+/**
+ * WHY THE SWATCH IS OFF, said where a seller sees it (Claude Design: a disabled control says why). The editors' selection toolbar
+ * writes the theme's own colours as tokens (`var(--gem-color-accent)`), so every colour picked there turned its field's swatch grey,
+ * with only a tooltip a finger or the keyboard never reaches (inventory of 19/10/2026). Null when the swatch shows the value.
+ */
+export function swatchWhy(value: string): string | null {
+  // Exactly when the swatch is off (swatchState's one rule): a padded hex is off too, and says so (review of #4636).
+  if (swatchState(value).usable) return null;
+  const v = value.trim();
+  const token = /^var\(\s*--gem-color-([a-z-]+)\s*\)$/i.exec(v)?.[1]?.toLowerCase();
+  if (token) return `Theme color: ${tokenName(token)}. Type a hex to use your own.`;
+  if (/^var\(/i.test(v)) return "A theme value. Type a hex to use your own.";
+  return "Kept as written: the swatch picks 6-digit hex colors only.";
+}

package/src/editor/tiles.tsx

@@ -0,0 +1,51 @@
+// CHOICE TILES (16/10/2026, Chris: the panel was missing pickers; research `_local/gemboss/research/pickers-2026-10-16/pickers.md`
+// §4 and pattern P9). A closed choice whose options are SHAPES (an image's ratio, a layout) drawn as picture tiles with their
+// name under them, as GemPages' layout selector and option illustrations do: the seller sees the shape before choosing it,
+// where a dropdown or a text box ("1-1, 4-3, 16-9") makes them read and imagine. The caller owns the value; one click writes.
+//
+//   · `.gemboss-ei-tiles[role=group]` › one `button.gemboss-ei-tile[aria-pressed]` per option › `.gemboss-ei-tile-pic`
+//     (`picture`, or a rectangle `shape` of w×h drawn to fit 26px) · `.gemboss-ei-tile-label`;
+//   · as many to a row as fit at 72px (4 in a 350px panel, 3 at a phone's 288px, 2 wide ones for a choice of two); a name
+//     wraps to two lines; under a finger every tile is at least 44px (min-height 56px always).
+// Its own part (`editor-tiles.css`): only a surface that draws tiles loads it.
+import "../editor-tiles.css";
+import type React from "react";
+
+export interface ChoiceTile {
+  value: string;
+  label: string;
+  /** A rectangle of these proportions, drawn to fit the tile's 26px picture box. */
+  shape?: { w: number; h: number };
+  /** Any other picture (an icon), when the choice is not a rectangle. */
+  picture?: React.ReactNode;
+}
+
+export interface ChoiceTilesProps {
+  /** The group's accessible name (the setting's label). */
+  label: string;
+  options: readonly ChoiceTile[];
+  /** The option that is on; null or a value no tile has: none is lit. */
+  value: string | null;
+  onChange: (value: string) => void;
+  disabled?: boolean;
+}
+
+const BOX = 26;
+const shapeStyle = ({ w, h }: { w: number; h: number }): React.CSSProperties =>
+  w >= h ? { width: BOX, height: Math.max(4, Math.round((BOX * h) / w)) } : { height: BOX, width: Math.max(4, Math.round((BOX * w) / h)) };
+
+export function ChoiceTiles({ label, options, value, onChange, disabled }: ChoiceTilesProps) {
+  return (
+    <div className="gemboss-ei-tiles" role="group" aria-label={label}>
+      {options.map((o) => (
+        <button key={o.value} type="button" className="gemboss-ei-tile" aria-pressed={o.value === value} disabled={disabled}
+          data-value={o.value} onClick={() => onChange(o.value)}>
+          <span className="gemboss-ei-tile-pic" aria-hidden>
+            {o.picture ?? (o.shape ? <span className="gemboss-ei-tile-shape" style={shapeStyle(o.shape)} /> : null)}
+          </span>
+          <span className="gemboss-ei-tile-label">{o.label}</span>
+        </button>
+      ))}
+    </div>
+  );
+}