@gemboss/ui 0.13.0 → 0.25.0

package/src/editor/controls.tsx

@@ -0,0 +1,207 @@
+"use client";
+// The settings panel's CONTROLS (0.17.0, step 3 of 5 of the editor kit): segmented, colour, slider, the four-edge px box
+// and the image slot. Each takes a value and gives one back through `onChange`; nothing here knows what is edited, what
+// schema a value came from or where it is saved. Wrap each in `Field` (panel.tsx) for its label and hint.
+//
+// Moved from the admin (apps/admin: FieldRenderer.tsx, element-inspector-controls.tsx) with the markup, the class names
+// and the commit rules they had there, so the admin's editors draw and behave exactly as before:
+//   · text-like boxes keep a DRAFT and commit on blur, Enter blurs (a live preview is not hammered per keystroke);
+//   · the colour swatch commits on every change, the colour's text box on blur / Enter;
+//   · the slider commits on every change (its number);
+//   · the edge box hands each keystroke to the caller (`onChange(side, raw)`) and says when to commit (`onCommit`, on
+//     blur): the caller decides what an empty edge means, and the admin has three answers to that on purpose.
+import "../editor.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
+import { useEffect, useState } from "react";
+import type React from "react";
+import { cssUrl } from "./css-url";
+import { swatchState } from "./swatch";
+import { Segmented } from "../segmented";
+
+const blurOnEnter = (e: React.KeyboardEvent<HTMLInputElement>) => {
+  if (e.key === "Enter") { e.preventDefault(); (e.target as HTMLInputElement).blur(); }
+};
+
+// ── Seg ─────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface SegOption<T extends string = string> {
+  value: T;
+  /** Default: the value itself. */
+  label?: React.ReactNode;
+}
+
+export interface SegProps<T extends string = string> {
+  options: ReadonlyArray<SegOption<T>>;
+  /** The pressed option. A value that matches none presses none. */
+  value?: string;
+  onChange: (value: T) => void;
+  disabled?: boolean;
+  /** The group's accessible name (`role="group"`): the field's label, said again for a screen reader. */
+  label?: string;
+  /** On the group (the admin narrows two-option rows with a max-width). */
+  style?: React.CSSProperties;
+}
+
+/**
+ * The settings panel's switch: the kit's `Segmented` stretched to its row (`.ui-seg--fill`), the same look as every
+ * other switch in the editors (0.20.0; it was a grey track with a raised white tab of its own). `gemboss-ei-seg` stays on
+ * the group as the hook editor-plain.js finds, and each button carries its `data-value`.
+ */
+export function Seg<T extends string = string>({ options, value, onChange, disabled, label, style }: SegProps<T>) {
+  return (
+    <Segmented<T> fill className="gemboss-ei-seg" style={style} ariaLabel={label ?? ""} value={(value ?? "") as T | ""} onChange={onChange} disabled={disabled}
+      options={options.map((o) => ({ value: o.value, label: o.label ?? o.value }))} />
+  );
+}
+
+// ── ColorControl ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface ColorControlProps {
+  /** The text box's id (the Field's `htmlFor`). */
+  id?: string;
+  value: string;
+  /** A committed value: on every swatch change, and on the text box's blur / Enter. */
+  onChange: (value: string) => void;
+  disabled?: boolean;
+  /** The field's name; the swatch is announced as "<label> swatch". */
+  label: string;
+  placeholder?: string;
+}
+
+/**
+ * `.gemboss-ei-color`: a native swatch beside a text box. The swatch is DISABLED (with a title saying why) for anything
+ * but a 6-digit hex (`swatchState`): `<input type="color">` would show black for `#f00`, `rgba()`, `var()` or a gradient,
+ * and overwrite it with black on the first touch.
+ */
+export function ColorControl({ id, value, onChange, disabled, label, placeholder }: ColorControlProps) {
+  const [draft, setDraft] = useState(value);
+  useEffect(() => { setDraft(value); }, [value]);
+  const { swatch, usable } = swatchState(draft);
+  return (
+    <div className="gemboss-ei-color">
+      <input type="color" className="gemboss-ei-swatch" aria-label={`${label} swatch`} value={swatch}
+        disabled={disabled || !usable}
+        title={usable ? undefined : `${draft} — not a plain 6-digit hex; edit it in the box below`}
+        onChange={(e) => { setDraft(e.target.value); onChange(e.target.value); }} />
+      <input id={id} className="gemboss-field gemboss-ei-inp" placeholder={placeholder ?? "#000000 / var(--…)"} value={draft} disabled={disabled}
+        onChange={(e) => setDraft(e.target.value)} onBlur={() => onChange(draft)} onKeyDown={blurOnEnter} />
+    </div>
+  );
+}
+
+// ── RangeControl ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface RangeControlProps {
+  id?: string;
+  min: number;
+  max: number;
+  /** Default 1. */
+  step?: number;
+  value: number;
+  /** Every change (drag, ←/→, Home/End, PageUp/PageDown), as a number. */
+  onChange: (value: number) => void;
+  disabled?: boolean;
+}
+
+/** `input.gemboss-ei-range` (the native slider in the primary colour). Show its value with `Field`'s `labelValue`. */
+export function RangeControl({ id, min, max, step, value, onChange, disabled }: RangeControlProps) {
+  return (
+    <input id={id} type="range" className="gemboss-ei-range" min={min} max={max} step={step ?? 1}
+      value={value} disabled={disabled} onChange={(e) => onChange(Number(e.target.value))} />
+  );
+}
+
+// ── EdgeBox ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export type EdgeSide = "t" | "r" | "b" | "l";
+const SIDES: readonly EdgeSide[] = ["t", "r", "b", "l"];
+const SIDE_NAME: Record<EdgeSide, string> = { t: "top", r: "right", b: "bottom", l: "left" };
+
+export interface EdgeBoxProps {
+  /** The field's name; each box is announced as "<label> top / right / bottom / left". */
+  label: string;
+  /** What each box shows. A number, the raw text being typed, or empty. */
+  values: Partial<Record<EdgeSide, string | number>>;
+  /** Per side; default "0". The admin shows the inherited desktop value here while editing the phone override. */
+  placeholders?: Partial<Record<EdgeSide, string>>;
+  /** Every keystroke in one box. */
+  onChange: (side: EdgeSide, raw: string) => void;
+  /** A box lost focus (Enter blurs): commit what the boxes hold. */
+  onCommit: () => void;
+  disabled?: boolean;
+  /** `gemboss-field--narrow` on each box (the field family's tight lane). Default true. */
+  narrow?: boolean;
+  /** Ids for the boxes, per side. */
+  ids?: Partial<Record<EdgeSide, string>>;
+}
+
+/** `.gemboss-ei-edgebox`: four px boxes, T · R · B · L, mono and centred. */
+export function EdgeBox({ label, values, placeholders, onChange, onCommit, disabled, narrow = true, ids }: EdgeBoxProps) {
+  const cls = narrow ? "gemboss-field gemboss-field--narrow gemboss-ei-inp" : "gemboss-field gemboss-ei-inp";
+  return (
+    <div className="gemboss-ei-edgebox">
+      {SIDES.map((s) => (
+        <div className="gemboss-ei-edge" key={s}>
+          <input className={cls} inputMode="numeric" placeholder={placeholders?.[s] ?? "0"}
+            aria-label={`${label} ${SIDE_NAME[s]}`} id={ids?.[s]} value={values[s] ?? ""} disabled={disabled}
+            onChange={(e) => onChange(s, e.target.value)} onBlur={onCommit} onKeyDown={blurOnEnter} />
+          <span>{s.toUpperCase()}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ── ImageControl ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** A dashed pill button (`.gemboss-ei-addchip`): an image slot's Library / Generate / Clear, a panel's "＋ Add". */
+export function ChipButton({ disabled, expanded, onClick, children }: {
+  disabled?: boolean;
+  /** `aria-expanded`, for a chip that opens something under it (the Library grid). */
+  expanded?: boolean;
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
+  children: React.ReactNode;
+}) {
+  return <button type="button" className="gemboss-ei-addchip" disabled={disabled} aria-expanded={expanded} onClick={onClick}>{children}</button>;
+}
+
+export interface ImageControlProps {
+  /** The URL box's id. */
+  id?: string;
+  /** The committed URL: what the thumbnail shows. */
+  value: string;
+  /** A committed URL: on blur / Enter when the box differs from `value`, and "" from Clear. */
+  onChange: (url: string) => void;
+  disabled?: boolean;
+  placeholder?: string;
+  /**
+   * The URL box's text, when the caller holds it (to put a picked or generated URL in the box at once, before `value`
+   * comes back). Omitted, the control keeps its own draft and resets it whenever `value` changes.
+   */
+  draft?: string;
+  onDraftChange?: (text: string) => void;
+  /** Chips before Clear (`ChipButton`): Library, Generate. */
+  actions?: React.ReactNode;
+  /** Draw Clear while there is a value. Default true. */
+  clearable?: boolean;
+}
+
+/** `.gemboss-ei-img`: a 52px thumbnail (— when empty) beside the URL box and its chips. */
+export function ImageControl({ id, value, onChange, disabled, placeholder, draft, onDraftChange, actions, clearable = true }: ImageControlProps) {
+  const [own, setOwn] = useState(value);
+  useEffect(() => { setOwn(value); }, [value]);
+  const text = draft ?? own;
+  const setText = (next: string) => { if (draft === undefined) setOwn(next); onDraftChange?.(next); };
+  return (
+    <div className="gemboss-ei-img">
+      <div className="gemboss-ei-img-thumb" style={value ? { backgroundImage: cssUrl(value) } : undefined} aria-hidden>{value ? null : "—"}</div>
+      <div className="gemboss-ei-img-ctl">
+        <input id={id} className="gemboss-field gemboss-ei-inp" placeholder={placeholder ?? "Paste image URL…"} value={text} disabled={disabled}
+          onChange={(e) => setText(e.target.value)} onBlur={() => { if (text !== value) onChange(text); }} onKeyDown={blurOnEnter} />
+        <div className="gemboss-ei-img-actions">
+          {actions}
+          {clearable && value ? <ChipButton disabled={disabled} onClick={() => { setText(""); onChange(""); }}>Clear</ChipButton> : null}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/editor/css-url.ts

@@ -0,0 +1,11 @@
+// A CSS `url("…")` for any image URL (0.20.1). Plain TypeScript, no "use client": a server component may build a
+// background with it (also `@gemboss/ui/editor/css-url`).
+//
+// Unquoted, a URL holding ")" or a space ends the token early, the declaration is dropped, and the thumbnail shows
+// nothing. Quoted, only `"` and `\` need a backslash; a control character (tab, newline, …) is written as a hex escape
+// followed by a space, the one form CSS reads back as that character. (JSON.stringify is NOT this: CSS reads its `\n`
+// as "n" and its `\u0001` as the text "u0001".) editor-plain.js writes the same thing; editor-panel-browser.test.tsx
+// holds the two to one answer.
+export function cssUrl(url: string): string {
+  return `url("${url.replace(/["\\]/g, "\\$&").replace(/[\u0000-\u001f\u007f]/g, (c) => `\\${c.charCodeAt(0).toString(16)} `)}")`;
+}

package/src/editor/frame.tsx

@@ -0,0 +1,243 @@
+// What EVERY editor draws: EditorFrame, EditorTopbar (+ EditorBack, EditorSaveState) and DeviceToggle, kept in this one
+// module on purpose (the theme editor's own pane controls are panes.tsx; see index.ts). The device toggle is also drawn
+// by the plugin editor and the studio canvas, so together they ride in the chunk the toggle already had in the admin.
+// Split into one module per piece, the admin build grew a lazy chunk to place them (its runtime +52 bytes, every
+// screen's first load +20 B brotli). Measured 06/10/2026.
+import "../editor.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
+import type React from "react";
+
+/** Which half a phone shows (≤760px shows one at a time; wider shows both). Values are the CSS's `data-mobile-pane`. */
+export type EditorPane = "chat" | "preview";
+
+/** The seam between the left column and the preview: its width is the frame's, the drag/keyboard logic is the caller's. */
+export interface EditorSplit {
+  /** The left column's width in px. Written to `--gemboss-chat-w` on the body, and read out as the seam's `aria-valuenow`. */
+  width: number;
+  /** The seam's range for a screen reader. `max` should be the ceiling the box really allows, not a constant. */
+  min: number;
+  max: number;
+  /** The left column is hidden for a full-width preview: `--gemboss-chat-w` becomes 0 and the seam goes. */
+  collapsed?: boolean;
+  /** Start a drag (a POINTER event: touch is a pointer, a mouse event never fires for a finger). */
+  onPointerDown?: React.PointerEventHandler<HTMLDivElement>;
+  /** Arrow keys / Home / End: the seam is focusable, so a key must move it. */
+  onKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;
+  /** Accessible name of the seam. Default "Resize chat panel". */
+  label?: string;
+}
+
+export interface EditorFrameProps {
+  /** Added to `.gemboss-editor` (the admin's page and section editors add `gemboss-pageedit`). */
+  className?: string;
+  /** Mounted inside another surface instead of over the viewport (`.gemboss-editor--embedded`). */
+  embedded?: boolean;
+  /** Everything above the body, in order: the top bar, and any banner or notice that belongs under it. */
+  top?: React.ReactNode;
+  /** The left column. Its root is a `.gemboss-ec` (the chat / Configure column the frame sizes). */
+  left?: React.ReactNode;
+  /** The seam. Omit it for a fixed split. */
+  split?: EditorSplit;
+  /** The preview pane's content (the canvas and anything that floats over it). */
+  preview?: React.ReactNode;
+  /** The right column: a panel docked over the preview's right edge (`.gemboss-editor-dock`, 320px, ≤90%), e.g. the
+   *  theme editor's Global styles. Rendered first inside the pane, so the canvas and its overlays stack above it in
+   *  source order exactly as they did when each editor drew it inline. Nothing (null/false) draws nothing. */
+  right?: React.ReactNode;
+  /** Added to the dock (`.gemboss-editor-dock`). */
+  rightClassName?: string;
+  /** Phones: which pane shows (`data-mobile-pane`). Put an `EditorPaneTabs` first in `children` to let them switch. */
+  mobilePane?: EditorPane;
+  bodyRef?: React.Ref<HTMLDivElement>;
+  /** Added to `.gemboss-editor-body`. */
+  bodyClassName?: string;
+  previewRef?: React.Ref<HTMLDivElement>;
+  /** Added to `.gemboss-editor-preview-pane`. */
+  previewClassName?: string;
+  previewStyle?: React.CSSProperties;
+  /** After the body: the phone's pane switch, drawers, popups, anything laid over the whole editor. */
+  children?: React.ReactNode;
+}
+
+/**
+ * `div.gemboss-editor`: the editor, over the whole viewport (`position: fixed; inset: 0`) unless `embedded`.
+ * Markup, in order: `top` · `.gemboss-editor-body` (left · seam · preview pane, `right` docked first inside it) · `children`.
+ */
+export function EditorFrame({
+  className, embedded, top, left, split, preview, right, rightClassName, mobilePane,
+  bodyRef, bodyClassName, previewRef, previewClassName, previewStyle, children,
+}: EditorFrameProps) {
+  return (
+    <div className={["gemboss-editor", embedded && "gemboss-editor--embedded", className].filter(Boolean).join(" ")}>
+      {top}
+      <div className={["gemboss-editor-body", bodyClassName, split?.collapsed && "is-chat-collapsed"].filter(Boolean).join(" ")}
+        data-mobile-pane={mobilePane} ref={bodyRef}
+        style={split ? ({ "--gemboss-chat-w": `${split.collapsed ? 0 : split.width}px` } as React.CSSProperties) : undefined}>
+        {left}
+        {split ? (
+          <div className="gemboss-editor-resizer ui-resizer" onPointerDown={split.onPointerDown} onKeyDown={split.onKeyDown}
+            role="separator" aria-orientation="vertical" aria-label={split.label ?? "Resize chat panel"}
+            aria-valuenow={split.width} aria-valuemin={split.min} aria-valuemax={split.max} tabIndex={0} />
+        ) : null}
+        <div className={previewClassName ? `gemboss-editor-preview-pane ${previewClassName}` : "gemboss-editor-preview-pane"} ref={previewRef} style={previewStyle}>
+          {right != null && right !== false ? <div className={rightClassName ? `gemboss-editor-dock ${rightClassName}` : "gemboss-editor-dock"}>{right}</div> : null}
+          {preview}
+        </div>
+      </div>
+      {children}
+    </div>
+  );
+}
+
+// ── Top bar ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The bar's layout, by what sits in it (the CSS is written per variant):
+ *   theme → `--theme`: content-sized tracks above 1000px; the bar with a page picker and a Publish split button.
+ *   page  → `.gemboss-pageedit-top`: same tracks; a title, a type chip and a status beside ← (page and section editors).
+ *   guest → `--guest`: 1fr auto 1fr; a brand, a note, sign-in (the try door, no store yet).
+ */
+export type EditorTopbarVariant = "theme" | "page" | "guest";
+const VARIANT: Record<EditorTopbarVariant, string> = {
+  theme: "gemboss-editor-topbar--theme",
+  page: "gemboss-pageedit-top",
+  guest: "gemboss-editor-topbar--guest",
+};
+
+export interface EditorTopbarProps {
+  variant?: EditorTopbarVariant;
+  className?: string;
+  /** The way out, first in the bar: an `EditorBack`. */
+  back?: React.ReactNode;
+  /** Show / hide the left column (the frame's `split.collapsed`): an `EditorChatToggle`. Drawn between ← and the title. */
+  chatToggle?: React.ReactNode;
+  /** What is being edited: "Theme editor", "Page editor"… (`.gemboss-editor-tb-name`). */
+  title?: React.ReactNode;
+  /** After the title, in the left cluster: the page's name, a type chip, the save state, a mode switch. */
+  left?: React.ReactNode;
+  /** The centre cluster: page picker, `DeviceToggle`. */
+  center?: React.ReactNode;
+  /** The right cluster: tools, the ⋯ menu, Publish. */
+  right?: React.ReactNode;
+  /** A transient line under the bar (publish progress), floating top-right; `state` is a class: done | error | running.
+   *  Nothing is drawn while `message` is empty. */
+  status?: { state: string; message: React.ReactNode } | null;
+}
+
+/** `header.gemboss-editor-topbar`: three clusters (left · center · right), 52px. Returns the header and, when there is
+ *  one, the status line after it. */
+export function EditorTopbar({ variant = "page", className, back, chatToggle, title, left, center, right, status }: EditorTopbarProps) {
+  return (
+    <>
+      <header className={`gemboss-editor-topbar ${VARIANT[variant]}${className ? ` ${className}` : ""}`}>
+        <div className="gemboss-editor-tb-left">
+          {back}
+          {chatToggle}
+          {title != null && title !== false ? <span className="gemboss-editor-tb-name">{title}</span> : null}
+          {left}
+        </div>
+        <div className="gemboss-editor-tb-center">{center}</div>
+        <div className="gemboss-editor-tb-right">{right}</div>
+      </header>
+      {status && status.message != null && status.message !== false && status.message !== "" ? (
+        <div className={`gemboss-editor-statusbar ${status.state}`} role="status">{status.message}</div>
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * ← Back: `as={Link}` (plus `href`) for a router link, a `<button type="button">` with `onClick` by default.
+ * The arrow is the label's picture; the name a screen reader hears is `label` ("Back").
+ */
+export function EditorBack({ as: Comp = "button", label = "Back", ...rest }:
+  { as?: React.ElementType; label?: string } & Omit<React.AllHTMLAttributes<HTMLElement>, "as" | "label" | "className" | "children">) {
+  return <Comp {...(Comp === "button" ? { type: "button" } : null)} {...rest} className="gemboss-editor-back" aria-label={label}>←</Comp>;
+}
+
+/**
+ * The auto-save pill: "Saving…" with a spinner while an edit is in flight, "✓ Draft saved" once it lands.
+ * `idle` draws nothing unless `idleText` says what autosave means here (the section editor's "Autosaves", dimmed).
+ */
+export function EditorSaveState({
+  state, savedText = "✓ Draft saved", savingText = "Saving…", savingTitle = "Saving draft…",
+  savedTitle = "Every change is saved to the draft automatically", idleText,
+}: {
+  state: "idle" | "saving" | "saved";
+  savedText?: React.ReactNode; savingText?: React.ReactNode; savingTitle?: string; savedTitle?: string; idleText?: React.ReactNode;
+}) {
+  if (state === "idle") {
+    return idleText != null && idleText !== false ? <span className="gemboss-editor-savestate" title={savedTitle} style={{ opacity: 0.55 }}>{idleText}</span> : null;
+  }
+  return (
+    <span className={`gemboss-editor-savestate is-${state}`} role="status" aria-live="polite" title={state === "saving" ? savingTitle : savedTitle}>
+      {state === "saving" ? <><span className="gemboss-narr-spin" aria-hidden />{savingText}</> : savedText}
+    </span>
+  );
+}
+
+// ── Device toggle: moved from the admin's components/shell/DeviceToggle.tsx (0.14.0), unchanged. The theme, page and
+// section editors' device control, the plugin editor's, and the studio canvas's glyphs.
+
+/** Desktop / tablet / mobile — the breakpoints the responsive style overrides target. */
+export type PreviewBreakpoint = "desktop" | "tablet" | "mobile";
+
+/** The monitor and the phone, ONE drawing each for every device control (the editors' toggle, a canvas's Desktop ·
+ *  Mobile · Both). currentColor, so a pressed button's colour carries. */
+export function MonitorGlyph({ size = 15 }: { size?: number }) {
+  return (
+    <svg viewBox="0 0 24 24" width={size} height={size} fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <rect x="2.5" y="4" width="19" height="12" rx="2" /><line x1="9" y1="20.5" x2="15" y2="20.5" /><line x1="12" y1="16" x2="12" y2="20.5" />
+    </svg>
+  );
+}
+export function PhoneGlyph({ size = 15 }: { size?: number }) {
+  return (
+    <svg viewBox="0 0 24 24" width={size} height={size} fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <rect x="6.5" y="2.5" width="11" height="19" rx="2.5" /><line x1="10.5" y1="18.5" x2="13.5" y2="18.5" />
+    </svg>
+  );
+}
+
+/** Desktop / tablet / mobile preview toggle. The kit's segmented control (`.ui-seg`, 06/10/2026), the same look as every
+ *  other switch in the editors; `.gemboss-pv-devices` / `.gemboss-pv-device` stay as the hooks editor-plain.js finds. */
+export function DeviceToggle({ device, onChange }: { device: PreviewBreakpoint; onChange: (device: PreviewBreakpoint) => void }) {
+  return (
+    <div className="ui-seg gemboss-pv-devices" role="group" aria-label="Device">
+      <button
+        type="button"
+        className={`gemboss-pv-device${device === "desktop" ? " active" : ""}`}
+        aria-label="Desktop"
+        title="Desktop"
+        aria-pressed={device === "desktop"}
+        onClick={() => onChange("desktop")}
+      >
+        {/* Monitor SVG — the ▭/▯ box glyphs were indistinguishable and rendered as tofu on some fonts. */}
+        <MonitorGlyph />
+      </button>
+      <button
+        type="button"
+        className={`gemboss-pv-device${device === "tablet" ? " active" : ""}`}
+        aria-label="Tablet"
+        title="Tablet"
+        aria-pressed={device === "tablet"}
+        onClick={() => onChange("tablet")}
+      >
+        {/* Tablet SVG — a wider, landscape-ish slate to read distinctly from the phone. */}
+        <svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+          <rect x="4" y="3" width="16" height="18" rx="2" /><line x1="10.5" y1="18" x2="13.5" y2="18" />
+        </svg>
+      </button>
+      <button
+        type="button"
+        className={`gemboss-pv-device${device === "mobile" ? " active" : ""}`}
+        aria-label="Mobile"
+        title="Mobile"
+        aria-pressed={device === "mobile"}
+        onClick={() => onChange("mobile")}
+      >
+        {/* Phone SVG */}
+        <PhoneGlyph />
+      </button>
+    </div>
+  );
+}

package/src/editor/index.ts

@@ -0,0 +1,52 @@
+/**
+ * `@gemboss/ui/editor` (0.14.0, step 2 of 5 of the editor kit; the panel and its controls since 0.17.0, step 3): the
+ * EDITOR FRAME and its TOP BAR — the full-screen shell
+ * the admin's theme, page and section editors are drawn in, as React components. The look is `@gemboss/ui/editor.css`
+ * (step 1); this is the markup that look is written for, so a second editor (GemFactory's Builder) gets the same frame
+ * instead of a copy.
+ *
+ *   ┌ EditorTopbar ──────────────────────────────────────────────────────────────────────────────────────┐
+ *   │ ← [toggle] Title · left…        center (page picker, DeviceToggle)        right (tools, ⋯, Publish) │
+ *   ├ EditorFrame body ──────────────────────────────────────────────────────────────────────────────────┤
+ *   │ left (.gemboss-ec)  ║ seam ║  preview pane (preview + `right` docked over its right edge)            │
+ *   └────────────────────────────────────────────────────────────────── EditorPaneTabs (phones only) ─────┘
+ *
+ * FRAME ONLY. Every component is stateless and knows nothing of what is edited: the chat, the Configure dock, the
+ * canvas, the page picker, the menus and Publish are the editor's own and arrive as slots. State that belongs to the
+ * frame (the seam's width, which pane a phone shows, whether the left column is collapsed) is passed IN; the admin keeps
+ * it in `useResizableChatPanel`, a page without React gets it from `gembossUI.initEditorFrame()` (editor-plain.js).
+ *
+ * Its OWN entry, not part of `@gemboss/ui`: like editor.css, only a screen that shows an editor pays for it. Two modules
+ * behind it, grouped by who draws what (measured in the admin build, 06/10/2026): `frame` holds what every editor draws
+ * (and the device toggle the plugin editor shares), `panes` the chat toggle and the phone pane switch only the theme
+ * editor draws. One module for all of it cost the page and section editors ~0.3 KB of code they never run; one module
+ * per piece made the admin build grow a lazy chunk, and with it every screen's first load. No "use client": nothing
+ * here holds state.
+ */
+export {
+  DeviceToggle, EditorBack, EditorFrame, EditorSaveState, EditorTopbar, MonitorGlyph, PhoneGlyph,
+  type EditorFrameProps, type EditorPane, type EditorSplit, type EditorTopbarProps, type EditorTopbarVariant, type PreviewBreakpoint,
+} from "./frame";
+export { EditorChatToggle, EditorPaneTabs } from "./panes";
+// 0.17.0 (step 3): the settings panel (tabs, header, collapsible group, field row) and its controls. Two more modules,
+// by the same rule: `panel` is drawn by every editor's left column, `controls` only where values are edited. Both are
+// "use client" (InspectorGroup may hold its own open state; the text-like controls hold a draft).
+export {
+  Field, InspectorGroup, PanelAction, PanelHeader, PanelTabs,
+  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,
+} from "./controls";
+export { swatchState, 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
+// inspector's). Same rule: grouped by who draws what.
+export {
+  EditorDrawer, LayerList, layerName,
+  type EditorDrawerProps, type LayerItem, type LayerListProps,
+} from "./layers";
+export { SortableLayerList, type SortableLayerListProps } from "./sortable";
+export { LayerTree, type LayerTreeProps, type LayerTreeRow } from "./tree";

package/src/editor/layers.tsx

@@ -0,0 +1,136 @@
+// The editor's LAYERS and its DRAWER (step 4 of 5 of the editor kit): the page's sections as rows (LayerList) and the
+// panel that slides over the editor from a side (EditorDrawer). Moved from the admin's page editor (Layers, Page settings,
+// Edit content) with the markup and the classes they had, so those draw and behave exactly as before; the look is
+// editor.css (`.gemboss-layer*`, `.gemboss-settings*`, `.gemboss-picker-*`). Stateless, so no "use client".
+//
+// Reordering by drag and Alt+↑ / Alt+↓ is SortableLayerList (sortable.tsx, its own module): a list that does not reorder
+// (the admin's) does not carry that code. A section's elements as an indented outline (LayerTree) is tree.tsx.
+import "../editor.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
+import type React from "react";
+
+// ── LayerList ───────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface LayerItem {
+  id: string;
+  /** The row's first line (`.gemboss-layer-type`, 13px / 600, capitalised by CSS). */
+  title: React.ReactNode;
+  /** The second line, muted and cut with an ellipsis (`.gemboss-layer-head`). Drawn only when truthy. */
+  subtitle?: React.ReactNode;
+  /** The row's name for a screen reader where the title is not plain text ("Hide <name>", "Move <name>"). */
+  name?: string;
+  /** Nesting: each level indents the row by `indent` px. 0 / omitted draws no style. */
+  depth?: number;
+  /** Hidden on the page: the row is drawn faded (`.is-hidden`) and its eye button is pressed. */
+  hidden?: boolean;
+}
+
+export interface LayerListProps<T extends LayerItem = LayerItem> {
+  items: ReadonlyArray<T>;
+  /** The selected row (`.is-sel`, and its button says `aria-current`). */
+  selectedId?: string | null;
+  /** A click on a row's main button. */
+  onSelect?: (item: T, index: number) => void;
+  /** The row's own buttons, after the main one (`.gemboss-layer-acts`, 26px each). */
+  actions?: (item: T, index: number) => React.ReactNode;
+  /** Shown instead of the rows when there are none (`.gemboss-picker-empty`). */
+  empty?: React.ReactNode;
+  /** Hide / show, on when given: an eye button first among the row's actions (`aria-pressed` = hidden). */
+  onToggleHidden?: (item: T, hidden: boolean) => void;
+  /** Px per `depth` level. Default 14 (the element outline's step). */
+  indent?: number;
+  /** Extra props for a row's element and its main button, and what goes before the button: how SortableLayerList adds
+   *  dragging and keys without a second copy of the markup. */
+  rowProps?: (item: T, index: number) => React.HTMLAttributes<HTMLDivElement> & { "data-drop"?: string; className?: string };
+  mainProps?: (item: T, index: number) => React.ButtonHTMLAttributes<HTMLButtonElement>;
+  lead?: (item: T, index: number) => React.ReactNode;
+  /** The list element's ref. */
+  listRef?: React.Ref<HTMLDivElement>;
+}
+
+export const layerName = (it: LayerItem) => it.name ?? (typeof it.title === "string" ? it.title : it.id);
+const EYE = "M1.5 8s2.4-4.5 6.5-4.5S14.5 8 14.5 8s-2.4 4.5-6.5 4.5S1.5 8 1.5 8Z";
+
+/** `.gemboss-layers-list` › one `.gemboss-layer` per item: the main button (title · subtitle), then the actions. */
+export function LayerList<T extends LayerItem>({ items, selectedId, onSelect, actions, empty, onToggleHidden, indent = 14, rowProps, mainProps, lead, listRef }: LayerListProps<T>) {
+  return (
+    <div className="gemboss-layers-list" ref={listRef}>
+      {items.length === 0 ? (empty != null ? <div className="gemboss-picker-empty">{empty}</div> : null) : items.map((it, i) => {
+        const { className: extra, ...row } = rowProps?.(it, i) ?? {};
+        const cls = `gemboss-layer${selectedId === it.id ? " is-sel" : ""}${it.hidden ? " is-hidden" : ""}${extra ? ` ${extra}` : ""}`;
+        // The eye's name stays "Hide <name>" whichever way it is set: a toggle says its state with aria-pressed, and its
+        // tooltip says the same thing.
+        const eyeName = `Hide ${layerName(it)}`;
+        return (
+          <div key={it.id} className={cls} data-id={it.id} style={it.depth ? { paddingLeft: 6 + it.depth * indent } : undefined} {...row}>
+            {lead?.(it, i)}
+            <button type="button" className="gemboss-layer-main" aria-current={selectedId === it.id ? "true" : undefined}
+              onClick={onSelect ? () => onSelect(it, i) : undefined} {...mainProps?.(it, i)}>
+              <span className="gemboss-layer-type">{it.title}</span>
+              {it.subtitle ? <span className="gemboss-layer-head">{it.subtitle}</span> : null}
+            </button>
+            {actions || onToggleHidden ? (
+              <div className="gemboss-layer-acts">
+                {onToggleHidden ? (
+                  <button type="button" className="gemboss-layer-eye" aria-pressed={!!it.hidden} aria-label={eyeName}
+                    title={eyeName} onClick={() => onToggleHidden(it, !it.hidden)}>
+                    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.4" aria-hidden>
+                      <path d={EYE} /><circle cx="8" cy="8" r="2" />{it.hidden ? <path d="M2.5 13.5 13.5 2.5" data-gb-slash="" /> : null}
+                    </svg>
+                  </button>
+                ) : null}
+                {actions?.(it, i)}
+              </div>
+            ) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+// ── EditorDrawer ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface EditorDrawerProps {
+  /**
+   * `right` (default): `aside.gemboss-settings`, min(380px, 100%) wide (Page settings, Edit content). `left`:
+   * `aside.gemboss-layers`, 300px (Layers). Both full height, over a backdrop that closes them.
+   */
+  side?: "left" | "right";
+  /** The head's text (`.gemboss-picker-head`, 15px / 600) beside ✕. */
+  title: React.ReactNode;
+  onClose: () => void;
+  /** ✕'s accessible name. Default "Close". */
+  closeLabel?: string;
+  /** The drawer's accessible name. */
+  label?: string;
+  /** Added to the aside's class (the admin's `gemboss-page-section-content`). */
+  className?: string;
+  /** Above the head (the admin's "a newer revision exists" notice). */
+  before?: React.ReactNode;
+  /** The drawer's buttons, right-aligned at the bottom (`.gemboss-settings-foot`). */
+  footer?: React.ReactNode;
+  /** The body: a `.gemboss-settings-body` of `.gemboss-settings-field`s, a LayerList, … */
+  children?: React.ReactNode;
+}
+
+/**
+ * The panel that slides over the editor from a side, with a backdrop; ✕ and a click on the backdrop call `onClose`.
+ * Mount it while open (the caller holds whether it is): nothing is drawn while closed.
+ */
+export function EditorDrawer({ side = "right", title, onClose, closeLabel = "Close", label, className, before, footer, children }: EditorDrawerProps) {
+  const base = side === "left" ? "gemboss-layers" : "gemboss-settings";
+  return (
+    <>
+      <div className="gemboss-picker-backdrop" onClick={onClose} />
+      <aside className={className ? `${base} ${className}` : base} aria-label={label}>
+        {before}
+        <div className="gemboss-picker-head">
+          <span>{title}</span>
+          <button type="button" onClick={onClose} aria-label={closeLabel}>✕</button>
+        </div>
+        {children}
+        {footer ? <div className="gemboss-settings-foot">{footer}</div> : null}
+      </aside>
+    </>
+  );
+}