@openpresentation/opf-editor 0.10.5 → 0.11.0

package/dist/numbering.js

@@ -0,0 +1,223 @@
+// List numbering (RR-33): the headless model behind the numbering control. A list payload (`items` or `bullets`) can
+// carry `numbering`: a style name, a { style, start, suffix } object, or an array with one entry per list level. Every
+// write goes through the session as a validated JSON Patch edit, so each change is one undoable edit. Importing this
+// module needs no DOM. Core is read from the namespace so an older core still loads this module; the writes then
+// throw "numbering-unavailable".
+import * as core from "@openpresentation/opf";
+import { OPFEditorError, getValueAtPath, opfPathToJsonPointer, splitOpfPath } from "./index.js";
+
+/** The number styles and how each draws, in the order a picker lists them. */
+export const NUMBERING_STYLE_OPTIONS = Object.freeze([
+  { value: "arabic", label: "1, 2, 3", sample: "1" },
+  { value: "roman-upper", label: "I, II, III", sample: "I" },
+  { value: "roman-lower", label: "i, ii, iii", sample: "i" },
+  { value: "alpha-upper", label: "A, B, C", sample: "A" },
+  { value: "alpha-lower", label: "a, b, c", sample: "a" },
+]);
+/** The suffixes: the text drawn after the number. */
+export const NUMBERING_SUFFIX_OPTIONS = Object.freeze([
+  { value: "period", label: "1.", sample: "." },
+  { value: "paren", label: "1)", sample: ")" },
+  { value: "paren-both", label: "(1)", sample: "()" },
+]);
+/** Largest list depth a native paragraph can carry, and so the most level entries `numbering` holds. */
+export const MAX_NUMBERING_LEVELS = 9;
+/** Largest start (and counted number) a native auto-number can hold. */
+export const MAX_NUMBERING_START = 32767;
+
+const DEFAULT_LEVEL = Object.freeze({ style: "arabic", start: 1, suffix: "period" });
+const STYLES = NUMBERING_STYLE_OPTIONS.map((option) => option.value);
+const SUFFIXES = NUMBERING_SUFFIX_OPTIONS.map((option) => option.value);
+const FIELDS = ["items", "bullets"];
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+function fail(code, message, details) {
+  return new OPFEditorError(code, message, details);
+}
+
+function checkEditor(editor) {
+  if (!editor || typeof editor.applyPatch !== "function" || typeof editor.subscribe !== "function") {
+    throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
+  }
+}
+
+/** True when the core this editor runs on composes numbered lists (the core that ships `numbering`). */
+export function numberingAvailable() {
+  return typeof core.listNumbers === "function" && typeof core.formatListNumber === "function";
+}
+
+function requireCore() {
+  if (!numberingAvailable()) throw fail("numbering-unavailable", "List numbering needs a core release that ships numbering (@openpresentation/opf after 0.11.4).");
+}
+
+/**
+ * Where a list lives for a path that points at it or into it: `slides.0.items`, `slides.0.items.2` or
+ * `slides.0.left.items.1.text` all resolve to the payload that owns the list. Returns undefined when the path is not
+ * inside a list.
+ */
+export function listPayloadAt(document, path) {
+  let segments;
+  try {
+    segments = splitOpfPath(path);
+  } catch {
+    return undefined;
+  }
+  for (let index = 0; index < segments.length; index++) {
+    if (!FIELDS.includes(segments[index])) continue;
+    const next = segments[index + 1];
+    if (next !== undefined && !/^\d+$/.test(next)) continue;
+    const payloadPath = segments.slice(0, index);
+    const payload = payloadPath.length ? getValueAtPath(document, payloadPath) : document;
+    if (!isObject(payload) || !Array.isArray(payload[segments[index]])) continue;
+    const entry = next === undefined ? undefined : Number(next);
+    return { payloadPath: payloadPath.join("."), field: segments[index], path: [...payloadPath, segments[index]].join("."), payload, entry };
+  }
+  return undefined;
+}
+
+const isRegionKey = (key) => /^(?:(?:top|middle|bottom)(?:\+(?:top|middle|bottom))*(?::(?:left|center|right)(?:\+(?:left|center|right))*)?|(?:left|center|right)(?:\+(?:left|center|right))*)$/.test(key);
+
+/** Every list (`items` or `bullets`) of a slide: its path, label, entry count and whether it is numbered. */
+export function findNumberableLists(document, slideIndex) {
+  const slide = document?.slides?.[slideIndex];
+  if (!isObject(slide)) return [];
+  const found = [];
+  const visit = (payload, base, label, depth = 0) => {
+    if (!isObject(payload) || depth > 32) return;
+    for (const field of FIELDS) {
+      if (Array.isArray(payload[field])) found.push({ path: `${base}.${field}`, payloadPath: base, field, label: found.some((entry) => entry.label === label) ? `${label} (${field})` : label, count: payload[field].length, numbered: payload.numbering !== undefined });
+    }
+    if (Array.isArray(payload.blocks)) payload.blocks.forEach((block, index) => visit(block, `${base}.blocks.${index}`, `${label} › Block ${index + 1}`, depth + 1));
+  };
+  const base = `slides.${slideIndex}`;
+  visit(slide, base, `Slide ${slideIndex + 1}`);
+  for (const key of Object.keys(slide)) if (isRegionKey(key)) visit(slide[key], `${base}.${key}`, `Slide ${slideIndex + 1} › ${key}`);
+  return found;
+}
+
+function resolveLevels(value) {
+  const list = Array.isArray(value) ? value : [value];
+  return list.map((entry) => (typeof entry === "string"
+    ? { ...DEFAULT_LEVEL, style: entry }
+    : { style: entry?.style ?? DEFAULT_LEVEL.style, start: entry?.start ?? DEFAULT_LEVEL.start, suffix: entry?.suffix ?? DEFAULT_LEVEL.suffix }));
+}
+
+const sameLevel = (a, b) => a.style === b.style && a.start === b.start && a.suffix === b.suffix;
+
+function levelEntry({ style, start, suffix }) {
+  const fields = { ...(style !== "arabic" ? { style } : {}), ...(start !== 1 ? { start } : {}), ...(suffix !== "period" ? { suffix } : {}) };
+  const names = Object.keys(fields);
+  if (!names.length) return "arabic";
+  return names.length === 1 && names[0] === "style" ? style : fields;
+}
+
+/**
+ * The shortest `numbering` value for a list of per-level settings: one entry when every level matches (a style name when
+ * only the style is not the default, else an object holding just the non-default fields), otherwise an array with the
+ * redundant trailing entries dropped (the last entry repeats for deeper levels).
+ */
+export function numberingValue(levels) {
+  const list = levels.map((level) => ({ ...DEFAULT_LEVEL, ...level }));
+  if (!list.length) throw fail("invalid-numbering", "Numbering needs at least one level.");
+  if (list.length > MAX_NUMBERING_LEVELS) throw fail("invalid-numbering", `Numbering holds at most ${MAX_NUMBERING_LEVELS} levels.`);
+  for (const [index, level] of list.entries()) {
+    if (!STYLES.includes(level.style)) throw fail("invalid-numbering", `Level ${index + 1}: unknown style '${level.style}'.`, { level: index });
+    if (!SUFFIXES.includes(level.suffix)) throw fail("invalid-numbering", `Level ${index + 1}: unknown suffix '${level.suffix}'.`, { level: index });
+    if (!Number.isInteger(level.start) || level.start < 1 || level.start > MAX_NUMBERING_START) throw fail("invalid-numbering", `Level ${index + 1}: start must be a whole number from 1 to ${MAX_NUMBERING_START}.`, { level: index });
+  }
+  while (list.length > 1 && sameLevel(list.at(-1), list.at(-2))) list.pop();
+  const entries = list.map(levelEntry);
+  return entries.length === 1 ? entries[0] : entries;
+}
+
+const maxLevelOf = (items) => items.reduce((max, item) => Math.max(max, isObject(item) && Number.isInteger(item.level) ? item.level : 0), 0);
+
+/**
+ * The numbering state of the list a path points at: whether it is numbered, its settings per level (one entry when the
+ * numbering applies to every level), the number of levels the list uses, the markers it draws and which entry (if any)
+ * the path selects with that entry's own `start`.
+ */
+export function numberingState(document, path) {
+  const target = listPayloadAt(document, path);
+  if (!target) return undefined;
+  const { payload, field, entry } = target;
+  const items = payload[field];
+  const numbering = payload.numbering;
+  const numbered = numbering !== undefined;
+  const levels = numbered ? resolveLevels(numbering) : [{ ...DEFAULT_LEVEL }];
+  const depth = Math.min(MAX_NUMBERING_LEVELS, maxLevelOf(items) + 1);
+  let markers = [];
+  if (numbered && numberingAvailable()) {
+    try {
+      markers = core.listNumbers(items, numbering).map((number) => ({ index: number.index, level: number.level, text: number.text, value: number.value, adapted: number.adapted }));
+    } catch {
+      markers = [];
+    }
+  }
+  const selected = entry === undefined ? undefined : items[entry];
+  return {
+    path: target.path,
+    payloadPath: target.payloadPath,
+    field,
+    count: items.length,
+    numbered,
+    perLevel: levels.length > 1,
+    levels,
+    depth,
+    value: numbering,
+    markers,
+    entry: entry === undefined || selected === undefined ? undefined : { index: entry, start: isObject(selected) ? selected.start : undefined, marker: markers[entry]?.text },
+  };
+}
+
+function numberingPointer(target) {
+  return opfPathToJsonPointer(target.payloadPath ? `${target.payloadPath}.numbering` : "numbering");
+}
+
+/**
+ * Number a list, change how it is numbered, or turn numbering off, as one undoable validated edit. `value` is a
+ * `numbering` value (see {@link numberingValue}), or `undefined` / `null` to remove it; turning numbering off also removes
+ * the entry `start` values, which mean nothing without it. `path` addresses the list or anything inside it.
+ */
+export function setNumbering(editor, path, value, meta = {}) {
+  requireCore();
+  checkEditor(editor);
+  const target = listPayloadAt(editor.document, path);
+  if (!target) throw fail("not-a-list", "Select a list (items or bullets) to number.", { path });
+  const patches = [];
+  const present = Object.hasOwn(target.payload, "numbering");
+  if (value === undefined || value === null) {
+    if (!present) return { document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+    patches.push({ op: "remove", path: numberingPointer(target) });
+    target.payload[target.field].forEach((item, index) => {
+      if (isObject(item) && item.start !== undefined) patches.push({ op: "remove", path: opfPathToJsonPointer(`${target.path}.${index}.start`) });
+    });
+  } else {
+    patches.push({ op: present ? "replace" : "add", path: numberingPointer(target), value: structuredClone(value) });
+  }
+  return editor.applyPatch(patches, { source: "list-numbering", rejectInvalid: true, ...meta });
+}
+
+/**
+ * Restart the numbering at an entry: the entry shows `start`, and the entries after it continue from it. `undefined` / `null`
+ * removes the restart. A plain entry (a string or runs) becomes the object form to carry it. One undoable validated edit.
+ */
+export function setEntryStart(editor, itemPath, start, meta = {}) {
+  requireCore();
+  checkEditor(editor);
+  const target = listPayloadAt(editor.document, itemPath);
+  if (!target || target.entry === undefined) throw fail("not-an-entry", "Select a list entry to restart its numbering.", { path: itemPath });
+  if (target.payload.numbering === undefined) throw fail("not-numbered", "Number the list first; an entry start has no effect on a bulleted list.", { path: itemPath });
+  const item = target.payload[target.field][target.entry];
+  const pointer = opfPathToJsonPointer(`${target.path}.${target.entry}`);
+  const patches = [];
+  if (start === undefined || start === null) {
+    if (isObject(item) && item.start !== undefined) patches.push({ op: "remove", path: `${pointer}/start` });
+  } else {
+    if (!Number.isInteger(start) || start < 1 || start > MAX_NUMBERING_START) throw fail("invalid-numbering", `An entry start is a whole number from 1 to ${MAX_NUMBERING_START}.`, { start });
+    if (isObject(item)) patches.push({ op: item.start === undefined ? "add" : "replace", path: `${pointer}/start`, value: start });
+    else patches.push({ op: "replace", path: pointer, value: { text: structuredClone(item), start } });
+  }
+  if (!patches.length) return { document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  return editor.applyPatch(patches, { source: "list-numbering-start", rejectInvalid: true, ...meta });
+}

package/dist/outline-view.d.ts

@@ -0,0 +1,17 @@
+import type { EditorSession } from "./index.js";
+
+export interface OutlineViewOptions {
+  editor: EditorSession;
+  /** Called when a row takes focus, so the host can show that slide in its inspector. */
+  onSelectSlide?: (slideIndex: number) => void;
+  getSlideIndex?: () => number;
+  /** Every message the outline announces in its live region. */
+  onStatus?: (message: string) => void;
+}
+export interface OutlineView {
+  /** Redraw from the session; the host calls this after document changes. */
+  render(): void;
+  focusSlide(slideIndex: number): void;
+  destroy(): void;
+}
+export declare function createOutlineView(container: HTMLElement, options: OutlineViewOptions): OutlineView;

package/dist/outline-view.js

@@ -0,0 +1,278 @@
+// Outline view (RR-21): the deck as an editable outline. Slide titles are the top level; each slide's text, bullets and subtitle sit beneath
+// it. Rows are native text inputs, so they work with screen readers, IME and the clipboard. Typing commits on Enter or when the row loses focus
+// as ONE undoable change; structure edits (Enter for a new line or slide, Alt+Shift+Left/Right to promote and demote, Alt+Up/Down to move)
+// are one undoable change each, built in `outline.js`. Content that is not text is shown as a read-only row, and formatted text stays
+// read-only here, so nothing is flattened away. Importing needs no DOM; mounting does.
+import {
+  applyOutlineChange, prepareAddOutlineBullet, prepareInsertOutlineItem, prepareInsertOutlineSlide, prepareMoveOutlineItem, prepareMoveOutlineSlide, prepareOutlineDemoteSlide,
+  prepareOutlinePromote, prepareRemoveOutlineItem, prepareSetOutlineText, prepareShiftOutlineItem, readOutline,
+} from "./outline.js";
+import { hasSections, prepareRemoveSlides } from "./slides.js";
+
+let instances = 0;
+function el(doc, tag, props = {}, ...children) {
+  const node = doc.createElement(tag);
+  for (const [key, value] of Object.entries(props)) {
+    if (value === undefined || value === null || value === false) continue;
+    if (key === "class") node.className = value;
+    else if (key === "text") node.textContent = value;
+    else node.setAttribute(key, value === true ? "" : String(value));
+  }
+  node.append(...children.filter((child) => child !== null && child !== undefined && child !== false));
+  return node;
+}
+const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+
+/**
+ * Mount the outline into `container`. Options: `editor`, `onSelectSlide(index)` (called when a row takes focus, so the host can follow),
+ * `getSlideIndex()` and `onStatus(message)`. Returns `{ render, focusSlide, destroy }`; the host calls `render()` after document changes.
+ */
+export function createOutlineView(container, options) {
+  const { editor } = options;
+  const doc = container.ownerDocument;
+  const id = `opf-outline-${++instances}`;
+  let rows = [];
+  let renderedKeys = "";
+  let lastSnapshot;
+  let activeKey;
+  let pendingFocus;
+  let keys = [];
+
+  container.classList.add("opf-outline");
+  const live = el(doc, "div", { class: "sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true" });
+  const help = el(doc, "p", { id: `${id}-help`, class: "outline-help", text: "Type to edit. Enter adds a line (or a slide after a title). Alt+Shift+Right demotes, Alt+Shift+Left promotes, Alt+Up and Alt+Down move the line or slide. Backspace on an empty line removes it." });
+  const bar = el(doc, "div", { class: "outline-toolbar", role: "toolbar", "aria-label": "Outline actions" });
+  const list = el(doc, "ul", { class: "outline-list", "aria-label": "Presentation outline" });
+  const tools = {};
+  for (const [name, label] of [["promote", "Promote"], ["demote", "Demote"], ["up", "Move up"], ["down", "Move down"], ["add", "Add line below"]]) {
+    const button = el(doc, "button", { type: "button", class: "secondary outline-tool", "data-action": name, text: label });
+    // Keep the row's text selected: a click on a tool must not drop the caret before the action reads the row.
+    button.addEventListener("mousedown", (event) => event.preventDefault());
+    button.addEventListener("click", () => perform(name));
+    tools[name] = button;
+    bar.append(button);
+  }
+  container.replaceChildren(bar, help, list, live);
+
+  const announce = (message) => {
+    live.textContent = "";
+    globalThis.setTimeout(() => { live.textContent = message; }, 20);
+    options.onStatus?.(message);
+  };
+  const report = (error) => announce(error?.issues?.[0]?.message ?? error?.message ?? String(error));
+  const rowByKey = (key) => rows.find((row) => row.key === key);
+  const inputFor = (key) => list.querySelector(`[data-key="${CSS.escape(key)}"] .outline-input`);
+
+  function label(row) {
+    const slide = `Slide ${row.slideIndex + 1}`;
+    if (row.kind === "slide") return `${slide} title`;
+    if (row.kind === "subtitle") return `${slide} subtitle`;
+    if (row.kind === "text") return `${slide} text${row.editable ? "" : " (formatted, edit it on the slide)"}`;
+    if (row.kind === "other") return `${slide} ${row.label}, not editable in the outline`;
+    return `${slide}, ${row.level > 1 ? `level ${row.level} ` : ""}bullet`;
+  }
+  function build(row) {
+    const input = el(doc, "input", { type: "text", class: "outline-input", "aria-label": label(row), spellcheck: row.editable ? "true" : "false", autocomplete: "off", value: row.kind === "other" ? row.label : row.text, "aria-describedby": `${id}-help` });
+    if (!row.editable) input.readOnly = true;
+    if (row.kind === "slide") input.placeholder = "Untitled slide";
+    const item = el(doc, "li", { class: "outline-row", "data-key": row.key, "data-kind": row.kind, "data-level": row.level });
+    item.style.setProperty("--level", String(row.level));
+    if (row.kind === "slide") item.append(el(doc, "span", { class: "outline-number", "aria-hidden": "true", text: String(row.slideIndex + 1) }));
+    else item.append(el(doc, "span", { class: "outline-bullet", "aria-hidden": "true", text: row.kind === "item" ? "•" : "" }));
+    item.append(input);
+    if (row.kind === "slide" && row.hidden) item.append(el(doc, "span", { class: "slide-badge", text: "Hidden" }));
+    input.addEventListener("focus", () => { activeKey = row.key; options.onSelectSlide?.(rowByKey(row.key)?.slideIndex ?? row.slideIndex); updateTools(); });
+    input.addEventListener("change", () => commit(row.key, input));
+    input.addEventListener("keydown", (event) => keydown(event, row.key, input));
+    return item;
+  }
+
+  function render() {
+    const snapshot = editor.snapshot();
+    const firstDraw = !lastSnapshot;
+    if (snapshot === lastSnapshot && !pendingFocus) return;
+    lastSnapshot = snapshot;
+    const document = editor.document;
+    rows = readOutline(document).rows;
+    const sections = hasSections(document);
+    const entries = [];
+    let lastSection;
+    for (const row of rows) {
+      if (sections && row.kind === "slide" && (row.section !== lastSection || entries.every((entry) => entry.kind !== "section"))) {
+        entries.push({ kind: "section", key: `section:${row.slideIndex}`, text: row.section ?? "No section" });
+        lastSection = row.section;
+      }
+      entries.push(row);
+    }
+    const nextKeys = entries.map((entry) => entry.key);
+    const joined = nextKeys.join("|");
+    const hadFocus = list.contains(doc.activeElement);
+    if (joined === renderedKeys && !firstDraw) {
+      // Same structure: update values in place so a click on another row is never lost to a rebuild.
+      for (const row of rows) {
+        const input = inputFor(row.key);
+        if (!input) continue;
+        const text = row.kind === "other" ? row.label : row.text;
+        if (input.value !== text && doc.activeElement !== input) input.value = text;
+        input.setAttribute("aria-label", label(row));
+        input.readOnly = !row.editable;
+      }
+      for (const entry of entries) if (entry.kind === "section") list.querySelector(`[data-key="${CSS.escape(entry.key)}"] .outline-section-name`).textContent = entry.text;
+      for (const row of rows) if (row.kind === "slide") {
+        const item = list.querySelector(`[data-key="${CSS.escape(row.key)}"]`);
+        item.querySelector(".slide-badge")?.remove();
+        if (row.hidden) item.append(el(doc, "span", { class: "slide-badge", text: "Hidden" }));
+      }
+    } else {
+      renderedKeys = joined;
+      keys = nextKeys;
+      list.replaceChildren(...entries.map((entry) => {
+        if (entry.kind === "section") return el(doc, "li", { class: "outline-section", "data-key": entry.key }, el(doc, "span", { class: "outline-section-name", text: entry.text }));
+        return build(entry);
+      }));
+    }
+    const target = pendingFocus ?? (hadFocus ? activeKey : undefined);
+    pendingFocus = undefined;
+    if (target) {
+      const input = inputFor(target);
+      if (input && doc.activeElement !== input) input.focus();
+    }
+    updateTools();
+  }
+
+  function activeRow() { return activeKey ? rowByKey(activeKey) : undefined; }
+  function updateTools() {
+    const row = activeRow();
+    const document = editor.document;
+    const can = { promote: false, demote: false, up: false, down: false, add: Boolean(row) };
+    if (row) {
+      try {
+        if (row.kind === "item") {
+          can.demote = prepareShiftOutlineItem(document, row, 1).changed;
+          can.promote = row.level > 1 ? prepareShiftOutlineItem(document, row, -1).changed : row.editable;
+          can.up = prepareMoveOutlineItem(document, row, -1).changed;
+          can.down = prepareMoveOutlineItem(document, row, 1).changed;
+        } else if (row.kind === "slide") {
+          can.up = row.slideIndex > 0;
+          can.down = row.slideIndex < document.slides.length - 1;
+          can.demote = row.slideIndex > 0;
+        }
+      } catch { /* a row that vanished mid-edit leaves the tools off */ }
+    }
+    for (const [name, button] of Object.entries(tools)) button.disabled = !can[name];
+  }
+
+  function commit(key, input) {
+    const row = rowByKey(key);
+    if (!row?.editable) return false;
+    if (input.value === row.text) return false;
+    try {
+      const prepared = prepareSetOutlineText(editor.document, row, input.value);
+      if (!prepared.changed) return false;
+      applyOutlineChange(editor, prepared);
+      render();
+      return true;
+    } catch (error) {
+      input.value = row.text;
+      report(error);
+      return false;
+    }
+  }
+
+  function apply(prepare, message) {
+    try {
+      const prepared = prepare();
+      if (!prepared.changed) { announce(prepared.reason ?? "Nothing to change"); return false; }
+      pendingFocus = prepared.focus ?? activeKey;
+      applyOutlineChange(editor, prepared);
+      lastSnapshot = undefined;
+      render();
+      announce(typeof message === "function" ? message(prepared) : message);
+      return true;
+    } catch (error) {
+      pendingFocus = undefined;
+      report(error);
+      return false;
+    }
+  }
+
+  // Commit what is typed in the row before an action reads it, so the typed text and the structure change are two honest steps.
+  function settle(input, key) { if (input) commit(key, input); return rowByKey(key); }
+
+  function perform(action, input) {
+    const key = activeKey;
+    const row = settle(input ?? inputFor(key), key);
+    if (!row) return;
+    const document = editor.document;
+    if (action === "add") {
+      if (row.kind === "item") apply(() => prepareInsertOutlineItem(document, row), "Line added");
+      else if (row.kind === "slide") apply(() => prepareAddOutlineBullet(document, row.slideIndex), "Bullet added under the slide title");
+      else announce("Add a line from a title or a bullet");
+    } else if (action === "demote") {
+      if (row.kind === "item") apply(() => prepareShiftOutlineItem(document, row, 1), () => "Demoted");
+      else if (row.kind === "slide") apply(() => prepareOutlineDemoteSlide(document, row.slideIndex), "Slide joined the slide before it as a bullet");
+      else announce("Only titles and bullets change level");
+    } else if (action === "promote") {
+      if (row.kind === "item") {
+        if (row.level > 1) apply(() => prepareShiftOutlineItem(document, row, -1), "Promoted");
+        else apply(() => prepareOutlinePromote(document, row), (prepared) => `Promoted to slide ${prepared.newSlideIndex + 1}`);
+      } else if (row.kind === "slide") announce("Slide titles are already the top level");
+      else announce("Only titles and bullets change level");
+    } else if (action === "up" || action === "down") {
+      const delta = action === "up" ? -1 : 1;
+      if (row.kind === "item") apply(() => prepareMoveOutlineItem(document, row, delta), `Moved ${action}`);
+      else if (row.kind === "slide") apply(() => prepareMoveOutlineSlide(document, row.slideIndex, delta), (prepared) => `Slide moved to position ${prepared.selection[0] + 1} of ${document.slides.length}`);
+      else announce("Move bullets or slides");
+    }
+  }
+
+  function keydown(event, key, input) {
+    const row = rowByKey(key);
+    if (!row) return;
+    const index = keys.indexOf(key);
+    const focusAt = (position) => {
+      for (let at = position; at >= 0 && at < keys.length; at += position > index ? 1 : -1) {
+        const target = list.querySelector(`[data-key="${CSS.escape(keys[at])}"] .outline-input`);
+        if (target) { target.focus(); return; }
+      }
+    };
+    if (event.altKey && event.shiftKey && (event.key === "ArrowRight" || event.key === "ArrowLeft")) { event.preventDefault(); perform(event.key === "ArrowRight" ? "demote" : "promote", input); return; }
+    if (event.altKey && !event.shiftKey && (event.key === "ArrowUp" || event.key === "ArrowDown")) { event.preventDefault(); perform(event.key === "ArrowUp" ? "up" : "down", input); return; }
+    if (event.key === "ArrowDown" && !event.altKey && !event.ctrlKey && !event.metaKey) { event.preventDefault(); focusAt(index + 1); return; }
+    if (event.key === "ArrowUp" && !event.altKey && !event.ctrlKey && !event.metaKey) { event.preventDefault(); focusAt(index - 1); return; }
+    if (event.key === "Enter" && !event.isComposing) {
+      event.preventDefault();
+      const settled = settle(input, key);
+      if (!settled) return;
+      const document = editor.document;
+      if (settled.kind === "item") apply(() => prepareInsertOutlineItem(document, settled), "Line added");
+      else if (settled.kind === "slide") apply(() => prepareInsertOutlineSlide(document, settled.slideIndex), (prepared) => `Slide ${prepared.index + 1} added`);
+      else focusAt(index + 1);
+      return;
+    }
+    if (event.key === "Backspace" && input.value === "" && input.selectionStart === 0 && !input.readOnly) {
+      if (row.kind === "item") { event.preventDefault(); apply(() => prepareRemoveOutlineItem(editor.document, row), "Line removed"); }
+      else if (row.kind === "slide" && !rows.some((other) => other.slideIndex === row.slideIndex && other.kind !== "slide")) {
+        event.preventDefault();
+        apply(() => {
+          const prepared = prepareRemoveSlides(editor.document, [row.slideIndex]);
+          return { ...prepared, focus: `slide:slides.${Math.max(0, row.slideIndex - 1)}` };
+        }, `Slide ${row.slideIndex + 1} removed`);
+      }
+    }
+  }
+
+  render();
+  return {
+    render,
+    /** Focus the title row of a slide. */
+    focusSlide(slideIndex) {
+      pendingFocus = `slide:slides.${slideIndex}`;
+      render();
+    },
+    destroy() {
+      container.replaceChildren();
+      container.classList.remove("opf-outline");
+    },
+  };
+}

package/dist/outline.d.ts

@@ -0,0 +1,56 @@
+import type { EditorChange, EditorSession, JsonPatchOperation } from "./index.js";
+import type { PreparedSlideChange } from "./slides.js";
+
+export type OutlineRowKind = "slide" | "subtitle" | "text" | "item" | "other";
+export interface OutlineRow {
+  /** Stable for a row across edits that do not move it (`kind:path`), for focus and keys. */
+  key: string;
+  kind: OutlineRowKind;
+  slideIndex: number;
+  /** 0 for a slide title; 1 for its text; 1 plus the nesting level for a list item. */
+  level: number;
+  /** The plain text (formatted text is flattened for display). */
+  text: string;
+  /** The document path of the text value (an `other` row: of the content). */
+  path: string;
+  /** False for formatted text and for content that is not text. */
+  editable: boolean;
+  /** item: the list (`slides.0.items`) and the item's index in it. */
+  listPath?: string;
+  itemIndex?: number;
+  /** other: the content kind ("Chart", "Table", ...). */
+  label?: string;
+  /** slide: whether the slide is hidden, its section and id. */
+  hidden?: boolean;
+  section?: string;
+  id?: string;
+}
+export interface Outline { rows: OutlineRow[] }
+
+/** An outline change: the slide patch report plus the key of the row to focus afterwards. */
+export interface PreparedOutlineChange extends Omit<PreparedSlideChange, "selection"> {
+  selection: number[];
+  /** The `key` of the row to focus after the change. */
+  focus?: string;
+  reason?: string;
+  newSlideIndex?: number;
+}
+export type OutlineChange = Omit<EditorChange, "document" | "patches"> & Omit<PreparedOutlineChange, "document" | "patches"> & { document: unknown; patches: JsonPatchOperation[] };
+
+export declare function readOutline(document: unknown): Outline;
+export declare function prepareSetOutlineText(document: unknown, row: OutlineRow, text: string): PreparedOutlineChange;
+export declare function setOutlineText(editor: EditorSession, row: OutlineRow, text: string, meta?: Record<string, unknown>): OutlineChange;
+/** Nest (`delta` 1) or un-nest (-1) a list item with the items under it. A top-level item reports `changed: false` and a `reason`. */
+export declare function prepareShiftOutlineItem(document: unknown, row: OutlineRow, delta: 1 | -1): PreparedOutlineChange;
+export declare function prepareMoveOutlineItem(document: unknown, row: OutlineRow, delta: 1 | -1): PreparedOutlineChange;
+export declare function prepareInsertOutlineItem(document: unknown, row: OutlineRow, text?: string): PreparedOutlineChange;
+export declare function prepareAddOutlineBullet(document: unknown, slideIndex: number, text?: string): PreparedOutlineChange;
+export declare function prepareRemoveOutlineItem(document: unknown, row: OutlineRow): PreparedOutlineChange;
+/** A top-level list item becomes the title of a new slide that takes the items after it. */
+export declare function prepareOutlinePromote(document: unknown, row: OutlineRow): PreparedOutlineChange;
+/** A plain slide becomes a bullet (with its text nested) of the slide before it. Throws `outline-row-not-supported` rather than dropping content. */
+export declare function prepareOutlineDemoteSlide(document: unknown, slideIndex: number): PreparedOutlineChange;
+export declare function prepareMoveOutlineSlide(document: unknown, slideIndex: number, delta: number): PreparedOutlineChange;
+export declare function prepareInsertOutlineSlide(document: unknown, slideIndex: number): PreparedOutlineChange;
+/** Apply any prepared outline change as one undoable step. */
+export declare function applyOutlineChange(editor: EditorSession, prepared: PreparedOutlineChange | PreparedSlideChange, meta?: Record<string, unknown>): OutlineChange;