@openpresentation/opf-editor 0.27.0 → 0.29.0

package/dist/layout-layers.js

@@ -1,10 +1,12 @@
 // The layers panel of the layout editor (RR-99): the tree outline of splits and regions in reading order (role="tree"). Select, rename,
 // drag to reorder or to move between splits, and see which nodes have findings; the findings are listed under the tree.
+// CE-18: the tree items, the tree keyboard, the drag controller and the drop place are the studio kit's (src/studio-kit/).
 import { createLayoutModel } from "./layout-model.js";
-import { LayoutOperationError, isHeading, isPrefix, isSplit, moveNodes, nodeAt, pathKey, samePath } from "./layout-tree.js";
-import { SIZE_LABEL, createDom, handleGlobalShortcut, handleSelectionShortcut, isTypingTarget, nextId, nodeMenuItems, openMenu } from "./layout-editor-ui.js";
-
-const DRAG_DISTANCE = 4;
+import { trialMove } from "./layout-adapter.js";
+import { isHeading, isPrefix, isSplit, nodeAt, pathKey, samePath } from "./layout-tree.js";
+import { SIZE_LABEL, createDom, handleGlobalShortcut, handleSelectionShortcut, isHandled, isTypingTarget, nextId, nodeMenuItems, openMenu } from "./layout-editor-ui.js";
+import { hitRow, rovingTabStop, rowDropMode, showTreeDrop, treeItem, treeKeyAction } from "./studio-kit/tree.js";
+import { createDragController } from "./studio-kit/drag.js";
 const parsePath = (text) => (text === "" || text === undefined ? [] : text.split(".").map(Number));
 
 /**
@@ -36,8 +38,6 @@ export function createLayoutTree(container, options = {}) {
   container.append(root);
 
   const collapsed = new Set();
-  let drag = null;
-  let pending = null;
   let menu = null;
   let renameInput = null;
 
@@ -46,10 +46,11 @@ export function createLayoutTree(container, options = {}) {
 
   function build(path, entry, level, direction, position) {
     const rootItem = path.length === 0, split = !rootItem && isSplit(entry);
-    const li = el("li", "opf-lx-item", { role: "treeitem", "aria-level": level, "data-path": pathKey(path), "data-kind": rootItem ? "layout" : split ? "split" : "region" });
-    li.setAttribute("aria-selected", String(isSelected(path)));
-    if (rootItem || split) li.setAttribute("aria-expanded", String(!collapsed.has(pathKey(path))));
-    if (!rootItem) { li.setAttribute("aria-setsize", String(position.size)); li.setAttribute("aria-posinset", String(position.index + 1)); }
+    const li = treeItem(dom, {
+      level, selected: isSelected(path), expanded: rootItem || split ? !collapsed.has(pathKey(path)) : undefined,
+      setsize: rootItem ? undefined : position.size, posinset: rootItem ? undefined : position.index + 1,
+      attributes: { "data-path": pathKey(path), "data-kind": rootItem ? "layout" : split ? "split" : "region" },
+    });
     const issues = model.findingsFor(path);
     const within = model.findingsWithin(path);
     const row = el("div", "opf-lx-row", { "data-selected": String(isSelected(path)), "data-finding": issues.length ? "error" : within.length ? "within" : "" });
@@ -96,7 +97,7 @@ export function createLayoutTree(container, options = {}) {
     list.replaceChildren(build([], model.record, 1, "column", { index: 0, size: 1 }));
     const primary = model.primary ?? [];
     const stop = itemOf(primary) ?? itemOf([]);
-    for (const item of list.querySelectorAll(".opf-lx-item")) item.tabIndex = item === stop ? 0 : -1;
+    rovingTabStop(list.querySelectorAll(".opf-lx-item"), stop);
     if (focusedKey !== undefined) { const next = itemOf(primary) ?? itemOf(parsePath(focusedKey)) ?? stop; next?.focus({ preventScroll: true }); }
     paintFindings();
     syncRename();
@@ -174,7 +175,7 @@ export function createLayoutTree(container, options = {}) {
   });
   list.addEventListener("focusin", (event) => {
     const item = event.target.closest?.(".opf-lx-item");
-    if (!item || event.target !== item || drag || pending) return;
+    if (!item || event.target !== item || dragger.active || dragger.pending) return;
     const path = parsePath(item.dataset.path);
     if (!path.length) { if (model.selection.length) model.select([]); } else if (!isSelected(path)) model.select([path]);
   });
@@ -197,76 +198,64 @@ export function createLayoutTree(container, options = {}) {
     const path = rowPath(event);
     if (!path?.length) return;
     const paths = model.selection.some((entry) => samePath(entry, path)) ? model.selection.map((entry) => [...entry]) : [path];
-    pending = { x: event.clientX, y: event.clientY, paths, id: event.pointerId };
+    dragger.press(event, { paths });
   });
-  list.addEventListener("pointermove", (event) => {
-    if (pending && !drag && Math.hypot(event.clientX - pending.x, event.clientY - pending.y) > DRAG_DISTANCE) startDrag();
-    if (drag) moveDrag(event);
+  list.addEventListener("pointermove", (event) => { dragger.move(event); });
+  list.addEventListener("pointerup", (event) => { dragger.release(event); });
+  list.addEventListener("pointercancel", () => { dragger.cancel(); });
+  list.addEventListener("touchmove", (event) => { if (dragger.active && event.cancelable) event.preventDefault(); }, { passive: false });
+  // The kit's drag controller: a press past 4px drags the rows; each move finds the drop place; the release moves once; Escape cancels.
+  const dragger = createDragController({
+    doc,
+    onStart(press) {
+      list.setPointerCapture?.(press.id);
+      return { paths: press.payload.paths, drop: null };
+    },
+    onStarted(drag) {
+      root.dataset.dragging = "true";
+      for (const path of drag.paths) itemOf(path)?.classList.add("is-dragging");
+    },
+    onMove(drag, event) {
+      const found = dropAt(drag, event);
+      drag.drop = found;
+      for (const node of list.querySelectorAll("[data-into]")) node.removeAttribute("data-into");
+      showTreeDrop(dropMark, scroller, found && { mode: found.mode, state: found.reason ? "refused" : found.noop ? "same" : "ok", reason: found.reason, box: found.box });
+      if (found?.mode === "into") found.item.setAttribute("data-into", "true");
+    },
+    onEnd() {
+      dropMark.hidden = true;
+      delete root.dataset.dragging;
+      for (const node of list.querySelectorAll(".is-dragging, [data-into]")) { node.classList.remove("is-dragging"); node.removeAttribute("data-into"); }
+    },
+    onDrop(drag) {
+      const outcome = drag.drop, paths = drag.paths;
+      if (!outcome || !paths) return;
+      if (outcome.reason) { model.notify(outcome.reason, "error"); return; }
+      if (outcome.noop) return;
+      model.move(paths, outcome.listPath, outcome.index);
+    },
+    onEscape: () => model.notify("Move cancelled."),
   });
-  list.addEventListener("pointerup", (event) => { if (drag) finishDrag(event); pending = null; });
-  list.addEventListener("pointercancel", () => { endDrag(); pending = null; });
-  list.addEventListener("touchmove", (event) => { if (drag && event.cancelable) event.preventDefault(); }, { passive: false });
-  function startDrag() {
-    drag = { paths: pending.paths, drop: null };
-    list.setPointerCapture?.(pending.id);
-    root.dataset.dragging = "true";
-    doc.addEventListener("keydown", dragKey, true);
-    for (const path of drag.paths) itemOf(path)?.classList.add("is-dragging");
-  }
-  function dropAt(event) {
+  function dropAt(drag, event) {
     const rows = [...list.querySelectorAll(".opf-lx-item")].map((item) => ({ item, path: parsePath(item.dataset.path), row: item.firstElementChild }));
-    const hit = rows.find(({ row }) => { const box = row.getBoundingClientRect(); return event.clientY >= box.top && event.clientY <= box.bottom; });
+    const hit = hitRow(rows, event.clientY);
     if (!hit || drag.paths.some((path) => isPrefix(path, hit.path))) return null;
     const box = hit.row.getBoundingClientRect();
     const fraction = (event.clientY - box.top) / (box.height || 1);
     const entry = hit.path.length ? nodeAt(model.record, hit.path) : model.record;
-    let listPath, index, mode;
-    if (!hit.path.length) { listPath = []; index = model.record.regions.length; mode = "into"; }
-    else if (isSplit(entry) && fraction >= 0.3 && fraction <= 0.7) { listPath = hit.path; index = (entry.regions ?? []).length; mode = "into"; }
-    else { listPath = hit.path.slice(0, -1); index = hit.path[hit.path.length - 1] + (fraction < 0.5 ? 0 : 1); mode = fraction < 0.5 ? "before" : "after"; }
-    let reason = "", noop = false;
-    try { noop = JSON.stringify(moveNodes(model.record, drag.paths, listPath, index).record) === JSON.stringify(model.record); } catch (error) { if (!(error instanceof LayoutOperationError)) throw error; reason = error.message; }
+    const mode = rowDropMode(fraction, { root: !hit.path.length, container: hit.path.length > 0 && isSplit(entry) });
+    let listPath, index;
+    if (!hit.path.length) { listPath = []; index = model.record.regions.length; }
+    else if (mode === "into") { listPath = hit.path; index = (entry.regions ?? []).length; }
+    else { listPath = hit.path.slice(0, -1); index = hit.path[hit.path.length - 1] + (mode === "before" ? 0 : 1); }
+    const { reason, noop } = trialMove(model.record, drag.paths, listPath, index);
     return { listPath, index, mode, reason, noop, box, item: hit.item };
   }
-  function moveDrag(event) {
-    const found = dropAt(event);
-    drag.drop = found;
-    for (const node of list.querySelectorAll("[data-into]")) node.removeAttribute("data-into");
-    if (!found) { dropMark.hidden = true; return; }
-    const parent = scroller.getBoundingClientRect();
-    dropMark.hidden = false;
-    dropMark.dataset.mode = found.mode;
-    dropMark.dataset.state = found.reason ? "refused" : found.noop ? "same" : "ok";
-    dropMark.title = found.reason;
-    const top = found.mode === "after" ? found.box.bottom : found.mode === "before" ? found.box.top : found.box.top;
-    dropMark.style.top = `${top - parent.top + scroller.scrollTop}px`;
-    dropMark.style.left = `${found.box.left - parent.left}px`;
-    dropMark.style.width = `${found.box.width}px`;
-    dropMark.style.height = found.mode === "into" ? `${found.box.height}px` : "0px";
-    if (found.mode === "into") found.item.setAttribute("data-into", "true");
-  }
-  function finishDrag() {
-    const outcome = drag?.drop, paths = drag?.paths;
-    endDrag();
-    if (!outcome || !paths) return;
-    if (outcome.reason) { model.notify(outcome.reason, "error"); return; }
-    if (outcome.noop) return;
-    model.move(paths, outcome.listPath, outcome.index);
-  }
-  function endDrag() {
-    doc.removeEventListener("keydown", dragKey, true);
-    dropMark.hidden = true;
-    delete root.dataset.dragging;
-    for (const node of list.querySelectorAll(".is-dragging, [data-into]")) { node.classList.remove("is-dragging"); node.removeAttribute("data-into"); }
-    drag = null;
-    pending = null;
-  }
-  function dragKey(event) { if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); endDrag(); model.notify("Move cancelled."); } }
 
   // --- keyboard (the WAI-ARIA tree pattern) -------------------------------------------------------------------------------------------------
   const visibleItems = () => [...list.querySelectorAll(".opf-lx-item")];
   list.addEventListener("keydown", (event) => {
-    if (event.opfLayoutHandled || event.target.closest?.(".opf-lx-rename")) return;
+    if (isHandled(event) || event.target.closest?.(".opf-lx-rename")) return;
     if (handleGlobalShortcut(event, model)) return;
     if (isTypingTarget(event.target)) return;
     const item = event.target.closest?.(".opf-lx-item");
@@ -275,31 +264,25 @@ export function createLayoutTree(container, options = {}) {
     if (event.key === "Escape") {
       event.preventDefault();
       if (menu) { menu.close(); return; }
-      if (drag) { endDrag(); return; }
+      if (dragger.active) { dragger.cancel(); return; }
       if (path.length) { const parent = path.slice(0, -1); model.select(parent.length ? [parent] : []); itemOf(parent)?.focus({ preventScroll: true }); }
       return;
     }
     if (path.length && handleSelectionShortcut(event, model, "layers")) return;
-    const items = visibleItems();
-    const at = items.indexOf(item);
-    const go = (target) => { event.preventDefault(); target?.focus(); };
-    if (event.key === "ArrowDown") go(items[Math.min(items.length - 1, at + 1)]);
-    else if (event.key === "ArrowUp") go(items[Math.max(0, at - 1)]);
-    else if (event.key === "Home") go(items[0]);
-    else if (event.key === "End") go(items[items.length - 1]);
-    else if (event.key === "ArrowRight") {
-      if (item.hasAttribute("aria-expanded")) {
-        if (item.getAttribute("aria-expanded") === "false") { event.preventDefault(); toggle(path); itemOf(path)?.focus(); } else go(item.querySelector(":scope > ul > .opf-lx-item"));
-      }
-    } else if (event.key === "ArrowLeft") {
-      if (item.getAttribute("aria-expanded") === "true" && (path.length || false)) { event.preventDefault(); toggle(path); itemOf(path)?.focus(); }
-      else if (path.length) go(itemOf(path.slice(0, -1)));
-    } else if (event.key === "Enter" || event.key === " ") {
-      event.preventDefault();
-      if (path.length) model.select([path]); else model.select([]);
-    } else if (event.key === "ContextMenu" || (event.key === "F10" && event.shiftKey)) {
-      if (!path.length) return;
-      event.preventDefault();
+    const action = treeKeyAction(event, item, visibleItems(), {
+      expandable: item.hasAttribute("aria-expanded"),
+      expanded: item.getAttribute("aria-expanded") === "true",
+      collapsible: path.length > 0,
+      parent: path.length ? itemOf(path.slice(0, -1)) : null,
+      firstChild: item.querySelector(":scope > ul > .opf-lx-item"),
+      menu: path.length > 0,
+    });
+    if (!action) return;
+    event.preventDefault();
+    if (action.type === "focus") action.target?.focus();
+    else if (action.type === "expand" || action.type === "collapse") { toggle(path); itemOf(path)?.focus(); }
+    else if (action.type === "activate") { if (path.length) model.select([path]); else model.select([]); }
+    else if (action.type === "menu") {
       const box = item.firstElementChild.getBoundingClientRect();
       openRowMenu({ x: box.left + 24, y: box.bottom }, item);
     }
@@ -308,7 +291,7 @@ export function createLayoutTree(container, options = {}) {
   const unsubscribe = model.subscribe((event) => {
     if (event.type === "notice" || event.type === "tool") return;
     if (event.type === "view") { root.dataset.density = model.density; return; }
-    if (drag && event.type === "record") return;
+    if (dragger.active && event.type === "record") return;
     render();
   });
   render();
@@ -322,7 +305,7 @@ export function createLayoutTree(container, options = {}) {
     beginRename(path) { model.requestRename(path, "layers"); },
     destroy() {
       unsubscribe();
-      endDrag();
+      dragger.cancel();
       menu?.close({ restore: false });
       root.remove();
       if (ownModel) model.destroy();

package/dist/layout-model.js

@@ -1,18 +1,21 @@
 // The state shared by the parts of the layout editor (RR-99): the record being edited, the selection, the active tool, live validation
 // by core, and the editor's own undo history. The palette, canvas, layers and inspector are views of one model, so a host that lays
 // them out differently only passes the same model to each. Every change goes through a command here, which runs a pure operation of
-// `layout-tree.js`, validates the result and records one history step. No DOM, no network.
+// `layout-tree.js`, validates the result and records one history step. The selection, the gesture and the snapshot history are the
+// studio kit's (CE-18), over the layout's index paths (src/layout-adapter.js). No DOM, no network.
 import { validateCatalogRecord } from "@openpresentation/opf";
 import { layoutTemplateIssues } from "@openpresentation/opf/composition";
 import {
-  LayoutOperationError, clone, deleteNodes, duplicateNodes, equalizePair, insertRegion, isSplit, listAt, moveIntoSibling, moveNodes, nodeAt, nodes, nudgePair,
+  LayoutOperationError, clone, deleteNodes, duplicateNodes, equalizePair, insertRegion, isSplit, moveIntoSibling, moveNodes, nodeAt, nodes, nudgePair,
   parentDirection, removeDesignHint, reorderNode, samePath, setLayoutProperty, setProperty, splitRegion, toggleHeading, unwrapNode, wrapNodes,
 } from "./layout-tree.js";
+import { createSelection } from "./studio-kit/selection.js";
+import { layoutSelectionAdapter } from "./layout-adapter.js";
+import { createGesture, createHistory } from "./studio-kit/gesture.js";
 
 /** The `$schema` of a layout record; core's catalog validation expects it. */
 export const LAYOUT_SCHEMA = "https://openpresentation.org/schema/opf-layout/v2";
 export const LAYOUT_TOOLS = Object.freeze(["select", "split-row", "split-column", "insert", "heading", "hand"]);
-const COALESCE_MS = 1500;
 const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
 /** A blank layout: a title and one content region. */
@@ -69,7 +72,6 @@ export function createLayoutModel(options = {}) {
   const listeners = new Set();
   const state = {
     record: normalize(options.record ?? blankLayoutRecord()),
-    selection: [],
     tool: "select",
     preview: false,
     density: options.density === "touch" ? "touch" : "comfortable",
@@ -78,37 +80,49 @@ export function createLayoutModel(options = {}) {
     notice: null,
     renaming: null,
   };
-  const history = { entries: [], index: 0 };
-  const limit = options.historyLimit ?? 200;
-  let gesture = null;
+  const history = createHistory({ limit: options.historyLimit ?? 200 });
   let destroyed = false;
   let onChange = options.onChange;
   state.findings = validateLayoutRecord(state.record);
-  history.entries.push({ record: clone(state.record), selection: [] });
+  history.reset({ record: clone(state.record), selection: [] });
 
   const emit = (event) => { if (!destroyed) for (const listener of [...listeners]) listener({ ...event, model }); };
   const notice = (message, kind = "info") => { state.notice = message ? { message, kind, at: Date.now() } : null; emit({ type: "notice" }); };
   const validate = () => { state.findings = validateLayoutRecord(state.record); };
-  const existing = (paths) => (paths ?? []).filter((path) => path.length && nodeAt(state.record, path));
-  const snapshot = () => ({ record: clone(state.record), selection: state.selection.map((path) => [...path]) });
+  const selection = createSelection(layoutSelectionAdapter(() => state.record), { onChange: ({ source }) => emit({ type: "selection", source }) });
+  const snapshot = () => ({ record: clone(state.record), selection: selection.snapshot() });
   const fire = () => { try { onChange?.(clone(state.record)); } catch (error) { console.error(error); } };
-
-  function push(snap, coalesce) {
-    const head = history.entries[history.index];
-    const now = Date.now();
-    if (coalesce && head?.coalesce === coalesce && now - head.time < COALESCE_MS && history.index === history.entries.length - 1 && history.index > 0) {
-      history.entries[history.index] = { ...snap, coalesce, time: now };
-      return;
-    }
-    history.entries.length = history.index + 1;
-    history.entries.push({ ...snap, coalesce, time: now });
-    if (history.entries.length > limit) history.entries.shift(); else history.index++;
-  }
+  const push = (snap, coalesce) => history.push(snap, coalesce);
+  // A drag is one step: drafts show the record (no history, no onChange); the end pushes one snapshot; a cancel puts the start back.
+  const gesture = createGesture({
+    snapshot: () => ({ record: state.record, selection: selection.items }),
+    preview(record, message) {
+      state.record = record;
+      validate();
+      state.notice = message ? { message, kind: "info", at: Date.now(), live: true } : state.notice;
+      emit({ type: "record", source: "gesture" });
+    },
+    commit(start, { message }) {
+      if (JSON.stringify(start.record) === JSON.stringify(state.record)) { emit({ type: "record", source: "gesture-end" }); return false; }
+      selection.prune();
+      push(snapshot());
+      state.notice = { message, kind: "info", at: Date.now() };
+      emit({ type: "record", source: "gesture-end", message: state.notice.message });
+      fire();
+      return true;
+    },
+    restore(start) {
+      state.record = start.record;
+      selection.replace(start.selection);
+      validate();
+      emit({ type: "record", source: "gesture-cancel" });
+    },
+  });
 
   /** Run `operation(record)` -> `{ record, selection }`; a refusal is a notice, and nothing changes. */
   function run(message, operation, { coalesce } = {}) {
     if (state.readOnly) { notice("This layout is read only.", "error"); return false; }
-    if (gesture) return false;
+    if (gesture.active) return false;
     let outcome;
     try { outcome = operation(state.record); } catch (error) {
       if (error instanceof LayoutOperationError) { notice(error.message, "error"); return false; }
@@ -116,8 +130,8 @@ export function createLayoutModel(options = {}) {
     }
     if (JSON.stringify(outcome.record) === JSON.stringify(state.record)) { if (outcome.selection) select(outcome.selection); return false; }
     state.record = outcome.record;
-    if (outcome.selection) state.selection = outcome.selection.filter((path) => nodeAt(state.record, path));
-    else state.selection = existing(state.selection);
+    if (outcome.selection) selection.replace(outcome.selection.filter((path) => nodeAt(state.record, path)));
+    else selection.prune();
     validate();
     push(snapshot(), coalesce);
     state.notice = message ? { message: typeof message === "function" ? message(outcome) : message, kind: "info", at: Date.now() } : null;
@@ -126,18 +140,12 @@ export function createLayoutModel(options = {}) {
     return true;
   }
 
-  function select(paths, { source } = {}) {
-    const next = existing(paths).map((path) => [...path]);
-    if (next.length === state.selection.length && next.every((path, index) => samePath(path, state.selection[index]))) return false;
-    state.selection = next;
-    emit({ type: "selection", source });
-    return true;
-  }
+  const select = (paths, options) => selection.set(paths, options);
 
   const model = {
     get record() { return state.record; },
-    get selection() { return state.selection; },
-    get primary() { return state.selection[state.selection.length - 1] ?? null; },
+    get selection() { return selection.items; },
+    get primary() { return selection.primary; },
     get tool() { return state.tool; },
     get preview() { return state.preview; },
     get density() { return state.density; },
@@ -145,7 +153,7 @@ export function createLayoutModel(options = {}) {
     get findings() { return state.findings; },
     get notice() { return state.notice; },
     get renaming() { return state.renaming; },
-    get gesturing() { return gesture !== null; },
+    get gesturing() { return gesture.active; },
 
     subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
     setOnChange(callback) { onChange = callback; },
@@ -153,45 +161,22 @@ export function createLayoutModel(options = {}) {
     /** Replace the record (a layout the host loaded). Resets the selection and, by default, the history; does not call `onChange`. */
     setRecord(record, { keepHistory = false } = {}) {
       state.record = normalize(record);
-      state.selection = [];
-      gesture = null;
+      selection.replace([]);
+      gesture.reset();
       state.renaming = null;
       validate();
-      if (keepHistory) { history.entries.length = history.index + 1; history.entries.push({ ...snapshot(), time: Date.now() }); history.index++; }
-      else { history.entries = [{ ...snapshot() }]; history.index = 0; }
+      if (keepHistory) history.append(snapshot());
+      else history.reset(snapshot());
       emit({ type: "load" });
     },
 
     select,
     /** Shift-click: add a sibling of the selection, else replace it. */
-    selectAdd(path) {
-      const current = state.selection;
-      if (!current.length || !existing([path]).length) return select([path]);
-      const parent = path.slice(0, -1);
-      if (!samePath(current[0].slice(0, -1), parent)) return select([path]);
-      const has = current.some((entry) => samePath(entry, path));
-      return select(has ? current.filter((entry) => !samePath(entry, path)) : [...current, path]);
-    },
-    selectParent() {
-      const path = model.primary;
-      if (!path) return false;
-      return select(path.length > 1 ? [path.slice(0, -1)] : []);
-    },
-    selectChild() {
-      const path = model.primary;
-      const node = path && nodeAt(state.record, path);
-      if (!node || !isSplit(node) || !node.regions?.length) return false;
-      return select([[...path, 0]]);
-    },
+    selectAdd: (path) => selection.add(path),
+    selectParent: () => selection.selectParent(),
+    selectChild: () => selection.selectChild(),
     /** Move the selection to a sibling (`delta` -1 or 1), or to the first entry when nothing is selected. */
-    selectSibling(delta) {
-      const path = model.primary;
-      if (!path) return select(state.record.regions.length ? [[0]] : []);
-      const list = listAt(state.record, path.slice(0, -1));
-      const at = path[path.length - 1] + delta;
-      if (!list || at < 0 || at >= list.length) return false;
-      return select([[...path.slice(0, -1), at]]);
-    },
+    selectSibling: (delta) => selection.selectSibling(delta),
     setTool(tool) {
       if (!LAYOUT_TOOLS.includes(tool) || state.tool === tool) return false;
       state.tool = tool;
@@ -224,42 +209,17 @@ export function createLayoutModel(options = {}) {
 
     // --- gestures: a drag is one step ---
     beginGesture(label) {
-      if (state.readOnly || gesture) return false;
-      gesture = { label, record: state.record, selection: state.selection };
-      return true;
+      if (state.readOnly || gesture.active) return false;
+      return gesture.begin(label);
     },
     /** Show a record while the gesture runs (no history, no `onChange`). */
-    updateGesture(record, message) {
-      if (!gesture) return;
-      state.record = record;
-      validate();
-      state.notice = message ? { message, kind: "info", at: Date.now(), live: true } : state.notice;
-      emit({ type: "record", source: "gesture" });
-    },
-    endGesture(message) {
-      if (!gesture) return false;
-      const { record, label } = gesture;
-      gesture = null;
-      if (JSON.stringify(record) === JSON.stringify(state.record)) { emit({ type: "record", source: "gesture-end" }); return false; }
-      state.selection = existing(state.selection);
-      push(snapshot());
-      state.notice = { message: message ?? label, kind: "info", at: Date.now() };
-      emit({ type: "record", source: "gesture-end", message: state.notice.message });
-      fire();
-      return true;
-    },
-    cancelGesture() {
-      if (!gesture) return;
-      state.record = gesture.record;
-      state.selection = gesture.selection;
-      gesture = null;
-      validate();
-      emit({ type: "record", source: "gesture-cancel" });
-    },
+    updateGesture(record, message) { gesture.update(record, message); },
+    endGesture: (message) => gesture.end(message),
+    cancelGesture() { gesture.cancel(); },
 
     // --- history ---
-    canUndo: () => history.index > 0 && !gesture,
-    canRedo: () => history.index < history.entries.length - 1 && !gesture,
+    canUndo: () => history.canUndo() && !gesture.active,
+    canRedo: () => history.canRedo() && !gesture.active,
     undo() { return jump(-1); },
     redo() { return jump(1); },
 
@@ -277,12 +237,11 @@ export function createLayoutModel(options = {}) {
   };
 
   function jump(step) {
-    const target = history.index + step;
-    if (gesture || target < 0 || target >= history.entries.length) return false;
-    history.index = target;
-    const entry = history.entries[target];
+    if (gesture.active) return false;
+    const entry = history.go(step);
+    if (!entry) return false;
     state.record = clone(entry.record);
-    state.selection = existing(entry.selection);
+    selection.replace(selection.existing(entry.selection));
     validate();
     state.notice = { message: step < 0 ? "Undid the last change" : "Redid the change", kind: "info", at: Date.now() };
     emit({ type: "record", source: "history", message: state.notice.message });

package/dist/layout-templates.d.ts

@@ -1,8 +1,13 @@
 import type { EditorSession, EditorChange, JsonPatchOperation } from "./index.js";
 
-export interface LayoutChoice { id: string; label: string; record?: Record<string, unknown> }
-export interface LayoutIntentGroup { name: string; ids: readonly string[] }
-export declare const LAYOUT_INTENT_GROUPS: readonly LayoutIntentGroup[];
+/** A layout a picker offers. `group` is the catalog group of a `listCatalogRecords` entry (`custom` is the deck's own layout); `origin` is `document` for a record the deck embeds. */
+export interface LayoutChoice { id: string; label: string; record?: Record<string, unknown>; group?: string; origin?: string }
+/** The group of layouts the catalogs do not group: a deck's or host's own layout, or a record with no tags. */
+export declare const CUSTOM_LAYOUTS_GROUP: "Custom layouts";
+/** The picker group of a layout: the first tag of its catalog record (the Gallery's index group), else `CUSTOM_LAYOUTS_GROUP`. */
+export declare function layoutGroupName(choice: LayoutChoice): string;
+/** The catalog's groups in picker order (the catalog's own layout order), without the custom group. */
+export declare function layoutGroupOrder(choices: readonly LayoutChoice[]): string[];
 export declare const LAYOUT_REGION_KINDS: readonly string[];
 export declare const LAYOUT_REGION_ROLES: readonly string[];
 export declare const LAYOUT_REGION_FLOWS: readonly string[];

package/dist/layout-templates.js

@@ -5,14 +5,32 @@ import { applyJsonPatch, createValuePatch, opfPathToJsonPointer } from "./index.
 import { checkedDocument, fail } from "./edit-helpers.js";
 import { checkFormat } from "./checks.js";
 
-export const LAYOUT_INTENT_GROUPS = Object.freeze([
-  { name: "Openers and closers", ids: ["cover", "section", "agenda", "statement", "closing"] },
-  { name: "Text", ids: ["text", "list", "quote", "two-column"] },
-  { name: "Groups of items", ids: ["pillars", "comparison", "process", "timeline", "faq"] },
-  { name: "Numbers", ids: ["metrics", "scorecard"] },
-  { name: "Visuals", ids: ["image", "image-beside", "gallery", "chart", "chart-beside", "table", "table-beside", "code"] },
-  { name: "Mixed", ids: ["hero", "dashboard", "team", "logos"] },
-]);
+/** The group of a layout the catalogs do not group: a deck's or host's own layout, or a catalog record with no group. */
+export const CUSTOM_LAYOUTS_GROUP = "Custom layouts";
+
+/**
+ * The picker group of one layout choice (`listCatalogRecords` entry, or a host's `{ id, label, record?, group? }`). A catalog
+ * record carries its group as its first tag (the Gallery publishes the same group in its layout index, and its tests keep the
+ * two equal), so a layout added to the catalog is grouped with no change here. A record with no tag, a choice with no record and a
+ * deck's own layout (catalog group `custom`) are `CUSTOM_LAYOUTS_GROUP`.
+ */
+export function layoutGroupName(choice) {
+  if (choice?.group === "custom") return CUSTOM_LAYOUTS_GROUP;
+  const tag = Array.isArray(choice?.record?.tags) ? choice.record.tags[0] : undefined;
+  return typeof tag === "string" && tag.trim() ? tag.trim() : CUSTOM_LAYOUTS_GROUP;
+}
+
+/**
+ * The catalog's groups in picker order, without the custom group: the order the catalog lists its layouts in (the Gallery lists
+ * them in its index order), so the groups follow the catalog. Records a deck embeds come after the registered catalogs' own.
+ */
+export function layoutGroupOrder(choices) {
+  const names = [];
+  const pass = (list) => { for (const choice of list) { const name = layoutGroupName(choice); if (name !== CUSTOM_LAYOUTS_GROUP && !names.includes(name)) names.push(name); } };
+  pass(choices.filter((choice) => choice.origin !== "document"));
+  pass(choices.filter((choice) => choice.origin === "document"));
+  return names;
+}
 
 export const LAYOUT_REGION_KINDS = Object.freeze(["text", "list", "image", "video", "chart", "table", "code", "metric", "quote", "timeline", "group"]);
 export const LAYOUT_REGION_ROLES = Object.freeze(["primary", "secondary", "media", "supporting"]);
@@ -20,15 +38,11 @@ export const LAYOUT_REGION_FLOWS = Object.freeze(["none", "grid", "column", "aut
 const RESERVED = new Set(["title", "subtitle", "tag", "auto", "left", "center", "right", "top", "middle", "bottom"]);
 const NAME = /^[a-z][a-z0-9-]*$/;
 
-/** Group registered layouts by the 28 built-in intents, then any deck or host layouts. */
+/** Group layouts by their catalog group (see `layoutGroupName`), in catalog order, then the custom ones. Choices keep their order within a group. */
 export function groupLayoutChoices(choices) {
-  const byId = new Map(choices.map((choice) => [choice.id, choice]));
-  const used = new Set();
-  const groups = LAYOUT_INTENT_GROUPS.map(({ name, ids }) => ({
-    name, choices: ids.map((id) => byId.get(id)).filter((choice) => { if (!choice || used.has(choice.id)) return false; used.add(choice.id); return true; }),
-  })).filter((group) => group.choices.length);
-  const custom = choices.filter((choice) => !used.has(choice.id));
-  if (custom.length) groups.push({ name: "Custom layouts", choices: custom });
+  const groups = layoutGroupOrder(choices).map((name) => ({ name, choices: choices.filter((choice) => layoutGroupName(choice) === name) }));
+  const custom = choices.filter((choice) => layoutGroupName(choice) === CUSTOM_LAYOUTS_GROUP);
+  if (custom.length) groups.push({ name: CUSTOM_LAYOUTS_GROUP, choices: custom });
   return groups;
 }
 

package/dist/numbering-panel.js

@@ -159,7 +159,7 @@ export function createNumberingPanel(container, options) {
     }
 
     if (enabled && state.entry) {
-      const start = h(doc, "input", { id: `${id}-entry-start`, type: "number", min: 1, max: MAX_NUMBERING_START, step: 1, value: state.entry.start ?? "", placeholder: state.entry.marker ?? "" });
+      const start = h(doc, "input", { id: `${id}-entry-start`, type: "number", min: 1, max: MAX_NUMBERING_START, step: 1, value: state.entry.start ?? "", placeholder: state.entry.marker ?? "", title: "Empty continues the count" });
       const apply = () => {
         const text = start.value.trim();
         try {
@@ -172,8 +172,7 @@ export function createNumberingPanel(container, options) {
       };
       start.addEventListener("change", apply);
       body.append(h(doc, "div", { class: "opf-numbering-entry" },
-        h(doc, "label", { for: start.id, text: `Entry ${state.entry.index + 1} starts at` }), start,
-        h(doc, "span", { class: "opf-numbering-help", text: "Leave empty to continue the count. Later entries carry on from it." })));
+        h(doc, "label", { for: start.id, text: `Entry ${state.entry.index + 1} starts at` }), start));
     }
   }