@openpresentation/opf-editor 0.10.6 → 0.11.1

package/dist/content-actions.js

@@ -0,0 +1,207 @@
+// Content actions (RR-26): list levels, grouping, regions, images between content and design, and slide
+// split and merge, as editor transactions. The pure transforms live in core (`@openpresentation/opf/convert`);
+// each action here finds its target in the document, calls the transform, turns the result into a guarded patch
+// (`test` of what was read, then `replace`, or per-slide `remove` and `add`), validates the document and, in the
+// apply form, applies it as ONE undoable step. Every prepare function returns `{ document, patches, changed,
+// lossless, loss, path }` without touching a session; a refusal throws `content-action-refused`.
+import {
+  OPFConversionError,
+  blocksToRegions,
+  demoteImage,
+  mergeSlides as mergeSlidesCore,
+  moveRegion,
+  promoteImage,
+  regionsToBlocks,
+  shiftListLevels,
+  splitSlide,
+  splitSlideOnOverflow as splitSlideOnOverflowCore,
+  unpaginate,
+  unwrapGroup,
+  wrapBlocks,
+} from "@openpresentation/opf/convert";
+import { applyJsonPatch, getValueAtPath, opfPathToJsonPointer, splitOpfPath, validateOpfDocument } from "./index.js";
+import { readBlockContent } from "./block-convert.js";
+import { checkedDocument, fail } from "./edit-helpers.js";
+
+const refuse = (message, details) => fail("content-action-refused", message, details);
+
+/** Run a core transform; a refusal becomes the editor's `content-action-refused`. */
+function core(action) {
+  try {
+    return action();
+  } catch (error) {
+    if (error instanceof OPFConversionError) throw refuse(error.message, { ...error.details, coreCode: error.code });
+    throw error;
+  }
+}
+
+function requireEditor(editor) {
+  if (!editor || typeof editor.applyPatch !== "function") throw fail("invalid-editor", "Expected an editor session created by createEditorSession.");
+}
+
+function slideParts(document, path, what) {
+  let parts;
+  try {
+    parts = splitOpfPath(path);
+  } catch {
+    parts = undefined;
+  }
+  if (!parts || parts[0] !== "slides" || !/^(0|[1-9][0-9]*)$/.test(parts[1] ?? "") || !document?.slides?.[Number(parts[1])]) throw refuse(`Choose ${what} on a slide.`, { path });
+  return { slideIndex: Number(parts[1]), relative: parts.slice(2), parts };
+}
+
+const asNumbers = (path) => path.map((part) => (/^(0|[1-9][0-9]*)$/.test(String(part)) ? Number(part) : part));
+const toDocumentPath = (slideIndex, relative) => ["slides", String(slideIndex), ...(relative ?? []).map(String)].join(".");
+
+/** Replace one value (a slide, a block, a list) as `test` + `replace`, validated like every other edit. */
+function replacePatches(document, parts, next) {
+  const pointer = opfPathToJsonPointer(parts);
+  return [
+    { op: "test", path: pointer, value: structuredClone(getValueAtPath(document, parts)) },
+    { op: "replace", path: pointer, value: next },
+  ];
+}
+// `validate: false` skips the whole-document check, for a dry run that only needs the loss report (core has already
+// validated the changed slide); applying always validates.
+function finish(document, patches, extra, validate = true) {
+  if (!validate) return { document: applyJsonPatch(document, patches), patches, ...extra };
+  const before = validateOpfDocument(document);
+  return { document: checkedDocument(document, patches, before), patches, ...extra };
+}
+function apply(editor, prepared, meta, source) {
+  if (!prepared.changed) return { ...prepared, document: editor.document, patches: [], inversePatches: [], validation: editor.validation };
+  const change = editor.applyPatch(prepared.patches, { ...meta, source: meta.source ?? source, path: prepared.path });
+  const extra = Object.fromEntries(["levels", "range", "slideCount", "pages"].filter((key) => prepared[key] !== undefined).map((key) => [key, prepared[key]]));
+  return { ...change, changed: true, lossless: prepared.lossless, loss: prepared.loss, path: prepared.path, ...extra };
+}
+const unchanged = (document, path, reason) => ({ document: structuredClone(document), patches: [], path, changed: false, lossless: true, loss: [], ...(reason ? { reason } : {}) });
+
+// --- list levels -------------------------------------------------------------------------------
+
+/** The index of the list item a selection points at (`slides.0.blocks.1.items.2.text` gives 2), or undefined. */
+export function listItemIndexForSelection(selectedPath, blockPath) {
+  if (typeof selectedPath !== "string" || typeof blockPath !== "string") return undefined;
+  const match = new RegExp(`^${blockPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:\\.items|\\.bullets)\\.(0|[1-9][0-9]*)(?:\\.|$)`).exec(selectedPath);
+  return match ? Number(match[1]) : undefined;
+}
+
+/**
+ * Compute the patch that moves the list items at `indices` of the list block at `blockPath` one level in
+ * (`delta` 1, Tab) or out (`delta` -1, Shift+Tab). A level never exceeds one more than the item above, the first
+ * item cannot be nested, and items under a moved item move with it (`options.withChildren`, default true).
+ * `changed` is false, with a `reason`, when nothing can move.
+ */
+export function prepareListShift(document, blockPath, indices, delta, options = {}) {
+  const found = readBlockContent(document, blockPath);
+  if (!found || found.kind !== "list") throw refuse("Choose a list block.", { path: blockPath });
+  const result = core(() => shiftListLevels(found.owner, indices, delta, options));
+  const path = found.path.join(".");
+  if (!result.changed) return unchanged(document, path, result.reason);
+  return finish(document, replacePatches(document, found.path, result.payload), { path, changed: true, lossless: result.lossless, loss: result.loss, levels: result.levels }, options.validate !== false);
+}
+/** Nest or un-nest list items as one undoable step. Returns the session change plus `changed`, `reason`, `levels`, `lossless` and `loss`. */
+export function shiftListItems(editor, blockPath, indices, delta, options = {}, meta = {}) {
+  requireEditor(editor);
+  return apply(editor, prepareListShift(editor.document, blockPath, indices, delta, options), meta, "list-level");
+}
+
+// --- structure inside one slide ----------------------------------------------------------------
+
+/** One slide-level transform as a guarded replace of that slide. */
+function slideAction(document, slideIndex, transform, targetPath, validate = true) {
+  const slide = document.slides[slideIndex];
+  const result = core(() => transform(slide));
+  const path = result.path ? toDocumentPath(slideIndex, result.path) : (targetPath ?? `slides.${slideIndex}`);
+  if (!result.changed) return unchanged(document, path);
+  const patches = replacePatches(document, ["slides", String(slideIndex)], result.slide);
+  return finish(document, patches, { path, changed: true, lossless: result.lossless, loss: result.loss }, validate);
+}
+
+/** Wrap the blocks at `indices` of the container at `containerPath` (a slide `slides.0`, a group or a region group) in a new group. */
+export function prepareGroupBlocks(document, containerPath, indices, options = {}) {
+  const { slideIndex, relative } = slideParts(document, containerPath, "a container");
+  return slideAction(document, slideIndex, (slide) => wrapBlocks(slide, indices, { container: asNumbers(relative), ...(options.composition ? { composition: options.composition } : {}) }), undefined, options.validate !== false);
+}
+/** Replace the group at `groupPath` by its blocks. What the group carried (composition, id) is reported in `loss`. */
+export function prepareUngroupBlock(document, groupPath, options = {}) {
+  const { slideIndex, relative } = slideParts(document, groupPath, "a group");
+  return slideAction(document, slideIndex, (slide) => unwrapGroup(slide, asNumbers(relative)), undefined, options.validate !== false);
+}
+/** Place every block of a slide in its own named region: `regions[i]` is block i's region (`left`, `right`, `top:left`, ...). */
+export function prepareBlocksToRegions(document, slideIndex, regions, options = {}) {
+  slideParts(document, `slides.${slideIndex}`, "a slide");
+  return slideAction(document, slideIndex, (slide) => blocksToRegions(slide, regions), undefined, options.validate !== false);
+}
+/** Turn the named regions of a slide into ordinary blocks in reading order. The regions' placement is reported in `loss`. */
+export function prepareRegionsToBlocks(document, slideIndex, options = {}) {
+  slideParts(document, `slides.${slideIndex}`, "a slide");
+  return slideAction(document, slideIndex, (slide) => regionsToBlocks(slide), undefined, options.validate !== false);
+}
+/** Move the content of region `from` to region `to`, or swap them when `to` is taken and `options.swap` is true. */
+export function prepareMoveRegion(document, slideIndex, from, to, options = {}) {
+  slideParts(document, `slides.${slideIndex}`, "a slide");
+  return slideAction(document, slideIndex, (slide) => moveRegion(slide, from, to, options), undefined, options.validate !== false);
+}
+/** Move the image block at `blockPath` into the slide's design as `slideImage`, `background` or `watermark`. */
+export function prepareImageToDesign(document, blockPath, target, options = {}) {
+  const { slideIndex, relative } = slideParts(document, blockPath, "an image block");
+  return slideAction(document, slideIndex, (slide) => promoteImage(slide, asNumbers(relative), target, options), `slides.${slideIndex}`, options.validate !== false);
+}
+/** Move a slide's own `slideImage`, `background` image or `watermark` back into its content as an image block. */
+export function prepareImageToContent(document, slideIndex, source, options = {}) {
+  slideParts(document, `slides.${slideIndex}`, "a slide");
+  return slideAction(document, slideIndex, (slide) => demoteImage(slide, source, options), undefined, options.validate !== false);
+}
+
+export const groupBlocks = (editor, containerPath, indices, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareGroupBlocks(editor.document, containerPath, indices, options), meta, "group-blocks"));
+export const ungroupBlock = (editor, groupPath, meta = {}) => (requireEditor(editor), apply(editor, prepareUngroupBlock(editor.document, groupPath), meta, "ungroup-block"));
+export const placeBlocksInRegions = (editor, slideIndex, regions, meta = {}) => (requireEditor(editor), apply(editor, prepareBlocksToRegions(editor.document, slideIndex, regions), meta, "blocks-to-regions"));
+export const regionsAsBlocks = (editor, slideIndex, meta = {}) => (requireEditor(editor), apply(editor, prepareRegionsToBlocks(editor.document, slideIndex), meta, "regions-to-blocks"));
+export const moveSlideRegion = (editor, slideIndex, from, to, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareMoveRegion(editor.document, slideIndex, from, to, options), meta, "move-region"));
+export const moveImageToDesign = (editor, blockPath, target, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareImageToDesign(editor.document, blockPath, target, options), meta, "image-to-design"));
+export const moveImageToContent = (editor, slideIndex, source, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareImageToContent(editor.document, slideIndex, source, options), meta, "image-to-content"));
+
+// --- slides ------------------------------------------------------------------------------------
+
+/**
+ * Per-slide patches for replacing `range.deleteCount` slides from `range.start` by `slides`: a `test` for every
+ * replaced slide, a `replace` for each one that changed, `remove` for the surplus old slides and `add` for the
+ * surplus new ones, so a split or merge stays one guarded, undoable transaction without rewriting the other slides.
+ */
+function slidePatches(document, range, slides) {
+  const old = document.slides.slice(range.start, range.start + range.deleteCount);
+  const patches = old.map((slide, offset) => ({ op: "test", path: `/slides/${range.start + offset}`, value: structuredClone(slide) }));
+  const common = Math.min(old.length, slides.length);
+  for (let offset = 0; offset < common; offset++) if (JSON.stringify(old[offset]) !== JSON.stringify(slides[offset])) patches.push({ op: "replace", path: `/slides/${range.start + offset}`, value: structuredClone(slides[offset]) });
+  for (let offset = old.length - 1; offset >= common; offset--) patches.push({ op: "remove", path: `/slides/${range.start + offset}` });
+  for (let offset = common; offset < slides.length; offset++) patches.push({ op: "add", path: `/slides/${range.start + offset}`, value: structuredClone(slides[offset]) });
+  return patches;
+}
+function slidesAction(document, result, extra = {}) {
+  const path = `slides.${result.range.start}`;
+  if (!result.changed) return unchanged(document, path, "Nothing to change.");
+  return finish(document, slidePatches(document, result.range, result.slides), { path, changed: true, lossless: result.lossless, loss: result.loss, range: result.range, slideCount: result.slides.length, ...extra });
+}
+
+/** Split a slide by its blocks (`options.at`: block indexes where a new slide starts, or `options.each`). See core's `splitSlide`. */
+export function prepareSplitSlide(document, slideIndex, options = {}) {
+  return slidesAction(document, core(() => splitSlide(document, slideIndex, options)));
+}
+/** Split a slide that overflows into pages with the existing pagination (`options`: text measurement, fonts, as for `paginatePresentation`). `pages` maps the new slides back for `prepareUnpaginate`. */
+export function prepareSplitSlideOnOverflow(document, slideIndex, options = {}) {
+  const result = core(() => splitSlideOnOverflowCore(document, slideIndex, options));
+  return slidesAction(document, result, { pages: result.pages });
+}
+/** Merge `count` consecutive slides from `start`. The first slide's id, headings and design win; what is dropped is reported in `loss`. */
+export function prepareMergeSlides(document, start, count = 2) {
+  return slidesAction(document, core(() => mergeSlidesCore(document, start, count)));
+}
+/** Put the continuation slides of a pagination back into one slide each. `pages` is the mapping `splitSlideOnOverflow` or `paginatePresentation` returned. */
+export function prepareUnpaginate(document, pages, options = {}) {
+  return slidesAction(document, core(() => unpaginate(document, pages, options)));
+}
+
+export const splitSlideByBlocks = (editor, slideIndex, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareSplitSlide(editor.document, slideIndex, options), meta, "split-slide"));
+export const splitSlideOnOverflow = (editor, slideIndex, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareSplitSlideOnOverflow(editor.document, slideIndex, options), meta, "split-slide-overflow"));
+export const mergeSlides = (editor, start, count = 2, meta = {}) => (requireEditor(editor), apply(editor, prepareMergeSlides(editor.document, start, count), meta, "merge-slides"));
+export const unpaginateSlides = (editor, pages, options = {}, meta = {}) => (requireEditor(editor), apply(editor, prepareUnpaginate(editor.document, pages, options), meta, "unpaginate-slides"));

package/dist/content-controls.js

@@ -0,0 +1,326 @@
+// Content controls (RR-26): the DOM controls for the content actions, mounted by `createDesignControls` in its
+// "Selected content" and "Slide structure" sections. Each action is a native button or select with a visible label;
+// it shows what the change would not carry over BEFORE it is applied (a dry run through the same prepare function the
+// action uses), is disabled with its reason when it does not apply, and commits one undoable change through the
+// session. Nothing here owns document state: `sync` re-reads the session after every change, Undo and Redo included.
+import { BLOCK_KIND_LABELS, blockConversionTargets, convertBlock, metricGroupForSelection } from "./block-convert.js";
+import {
+  listItemIndexForSelection,
+  moveImageToContent,
+  moveImageToDesign,
+  placeBlocksInRegions,
+  prepareBlocksToRegions,
+  prepareGroupBlocks,
+  prepareImageToContent,
+  prepareImageToDesign,
+  prepareListShift,
+  prepareRegionsToBlocks,
+  prepareUngroupBlock,
+  regionsAsBlocks,
+  groupBlocks,
+  shiftListItems,
+  ungroupBlock,
+} from "./content-actions.js";
+
+/** Region layouts offered for a slide with this many blocks (each block gets its own region, none overlap). */
+export const REGION_LAYOUTS = Object.freeze({
+  2: [
+    { id: "left-right", label: "Side by side", regions: ["left", "right"] },
+    { id: "top-bottom", label: "Stacked", regions: ["top", "bottom"] },
+  ],
+  3: [
+    { id: "three-columns", label: "Three columns", regions: ["left", "center", "right"] },
+    { id: "top-two-columns", label: "One on top, two below", regions: ["top", "bottom:left", "bottom:right"] },
+    { id: "left-two-rows", label: "One on the left, two on the right", regions: ["left", "top:right", "bottom:right"] },
+  ],
+  4: [{ id: "grid", label: "Two by two", regions: ["top:left", "top:right", "bottom:left", "bottom:right"] }],
+});
+
+/** Where an image block can go in the slide's design. The value is `<target>` or `<target>:<position>`. */
+export const IMAGE_DESTINATIONS = Object.freeze([
+  { value: "slideImage:right", label: "Slide image, on the right", target: "slideImage", options: { position: "right" } },
+  { value: "slideImage:left", label: "Slide image, on the left", target: "slideImage", options: { position: "left" } },
+  { value: "slideImage:top", label: "Slide image, along the top", target: "slideImage", options: { position: "top" } },
+  { value: "slideImage:bottom", label: "Slide image, along the bottom", target: "slideImage", options: { position: "bottom" } },
+  { value: "slideImage:background", label: "Slide image, full slide behind the content", target: "slideImage", options: { position: "background" } },
+  { value: "background", label: "Slide background", target: "background", options: {} },
+  { value: "watermark", label: "Watermark", target: "watermark", options: {} },
+]);
+
+const REGION_KEY = /^(?:(?:top|middle|bottom)(?:\+(?:top|middle|bottom))*(?::(?:left|center|right)(?:\+(?:left|center|right))*)?|(?:left|center|right)(?:\+(?:left|center|right))*)$/;
+const regionKeysOfSlide = (slide) => Object.keys(slide).filter((key) => REGION_KEY.test(key));
+const DESIGN_IMAGE_LABELS = { slideImage: "slide image", background: "background image", watermark: "watermark" };
+const messageOf = (error) => error?.issues?.[0]?.message ?? error?.message ?? String(error);
+const lossText = (prepared) => (prepared.loss.length ? `Not carried over: ${prepared.loss.join(", ")}.` : "Nothing is lost.");
+
+/**
+ * Build the content controls. `ctx` supplies the panel's helpers: `editor`, `h` (element builder), `selectField`,
+ * `run(action, done)` (commit, report, restore on failure), `nextId`, `getSlide()` and `reselect(path)`.
+ * Returns the nodes to place and `sync(state)`, where `state` is `{ blockPath, content, selectedPath, slideIndex }`.
+ */
+export function createContentControls(ctx) {
+  const { editor, h, selectField, run, nextId, getSlide, reselect } = ctx;
+  const updaters = [];
+  const ctxState = { current: {} };
+
+  /** A button that shows the dry-run report under it before it is pressed and is disabled, with the reason, when it does not apply. */
+  function action(label, { prepare, apply, done, selectAfter, role }) {
+    const id = nextId("content-note");
+    const note = h("p", { class: "opf-dc-help", id, "data-role": `${role}-note` });
+    const button = h("button", { type: "button", class: "secondary", "aria-describedby": id, "data-role": role }, label);
+    button.addEventListener("click", () => {
+      run(
+        () => {
+          const change = apply();
+          if (selectAfter) reselect(selectAfter(change));
+          return change;
+        },
+        (change) => `${typeof done === "function" ? done(change) : done} ${lossText(change)}`,
+      );
+    });
+    const wrap = h("div", { class: "opf-dc-action" }, button, note);
+    let current = {};
+    const update = (state) => {
+      current = state;
+      let prepared;
+      try {
+        prepared = prepare(state);
+      } catch (error) {
+        button.disabled = true;
+        note.textContent = messageOf(error);
+        return;
+      }
+      button.disabled = !prepared.changed;
+      note.textContent = prepared.changed ? lossText(prepared) : (prepared.reason ?? "");
+    };
+    return { wrap, update, state: () => current };
+  }
+
+  // --- list levels ---------------------------------------------------------------------------------
+
+  const list = h("div", { class: "opf-dc-actions-block", role: "group", "aria-label": "List levels", "data-role": "list-levels" });
+  {
+    const index = (state) => listItemIndexForSelection(state.selectedPath, state.blockPath);
+    const prepare = (delta) => (state) => {
+      const item = index(state);
+      if (item === undefined) return { changed: false, loss: [], reason: "Select a list item to change its level." };
+      return prepareListShift(editor.document, state.blockPath, [item], delta, { validate: false });
+    };
+    const apply = (delta) => () => {
+      const state = ctxState.current;
+      return shiftListItems(editor, state.blockPath, [index(state)], delta);
+    };
+    const indent = action("Indent item", { role: "indent", prepare: prepare(1), apply: apply(1), done: "Item moved in." });
+    const outdent = action("Outdent item", { role: "outdent", prepare: prepare(-1), apply: apply(-1), done: "Item moved out." });
+    list.append(h("p", { class: "opf-dc-help" }, "Select an item, then change its level. Items under it move with it."), indent.wrap, outdent.wrap);
+    updaters.push((state) => {
+      list.hidden = state.content?.kind !== "list";
+      if (!list.hidden) {
+        indent.update(state);
+        outdent.update(state);
+      }
+    });
+  }
+
+  // --- a group of metrics --------------------------------------------------------------------------
+
+  const metrics = selectField("metric-group", "Group of metrics", {
+    empty: "Convert the group to…",
+    help: "Every block in this group is a metric. Converting keeps their labels, values, units and deltas.",
+    onChange: (value) => {
+      if (!value) return;
+      const path = ctxState.current.metricGroupPath;
+      run(
+        () => convertBlock(editor, path, value),
+        (change) => `Converted the group to ${BLOCK_KIND_LABELS[value]?.toLowerCase() ?? value}. ${lossText(change)}`,
+      );
+      reselect(path);
+    },
+  });
+  updaters.push((state) => {
+    metrics.wrap.hidden = !state.metricGroupPath;
+    if (!state.metricGroupPath) return;
+    const targets = blockConversionTargets(editor.document, state.metricGroupPath);
+    metrics.setOptions(
+      targets.map((target) => ({
+        value: target.kind,
+        label: target.available ? `${target.label}${target.lossless ? "" : ` (loses ${target.loss.join(", ")})`}` : `${target.label} (unavailable)`,
+        disabled: !target.available,
+        title: target.reason,
+      })),
+    );
+    metrics.set("");
+  });
+
+  // --- arrange the selected block -------------------------------------------------------------------
+
+  const arrange = h("div", { class: "opf-dc-actions-block", role: "group", "aria-label": "Arrange the selected block", "data-role": "arrange" });
+  {
+    const parts = (state) => state.blockPath?.split(".") ?? [];
+    const blockIndex = (state) => {
+      const found = parts(state);
+      return found.at(-2) === "blocks" && /^\d+$/.test(found.at(-1)) ? Number(found.at(-1)) : undefined;
+    };
+    const containerPath = (state) => parts(state).slice(0, -2).join(".");
+    const next = (state) => {
+      const index = blockIndex(state);
+      const blocks = index === undefined ? undefined : editor.get(`${containerPath(state)}.blocks`);
+      return Array.isArray(blocks) && index + 1 < blocks.length ? [index, index + 1] : undefined;
+    };
+    const group = action("Group with the next block", {
+      role: "group-next",
+      prepare: (state) => {
+        const indices = next(state);
+        if (!indices) return { changed: false, loss: [], reason: "There is no block after this one in its container." };
+        return prepareGroupBlocks(editor.document, containerPath(state), indices, { validate: false });
+      },
+      apply: () => {
+        const state = ctxState.current;
+        return groupBlocks(editor, containerPath(state), next(state));
+      },
+      selectAfter: (change) => change.path,
+      done: "Blocks grouped.",
+    });
+    const parentGroup = (state) => {
+      const found = parts(state);
+      return found.length >= 6 && found.at(-4) === "blocks" ? found.slice(0, -2).join(".") : undefined;
+    };
+    const ungroup = action("Ungroup these blocks", {
+      role: "ungroup",
+      prepare: (state) => {
+        const path = parentGroup(state);
+        if (!path) return { changed: false, loss: [], reason: "This block is not inside a group." };
+        return prepareUngroupBlock(editor.document, path, { validate: false });
+      },
+      apply: () => ungroupBlock(editor, parentGroup(ctxState.current)),
+      selectAfter: (change) => change.path,
+      done: "Group dissolved.",
+    });
+    const image = selectField("image-destination", "Use this image as", {
+      empty: "Choose where it goes…",
+      help: "Moves the image out of the content into the slide's design. Undo puts it back.",
+      onChange: (value) => {
+        const destination = IMAGE_DESTINATIONS.find((entry) => entry.value === value);
+        if (!destination) return;
+        const state = ctxState.current;
+        run(
+          () => moveImageToDesign(editor, state.blockPath, destination.target, destination.options),
+          (change) => `Image is now the ${destination.label.toLowerCase()}. ${lossText(change)}`,
+        );
+        reselect(`slides.${state.slideIndex}`);
+      },
+    });
+    arrange.append(group.wrap, ungroup.wrap, image.wrap);
+    updaters.push((state) => {
+      arrange.hidden = !state.content;
+      if (arrange.hidden) return;
+      group.update(state);
+      ungroup.update(state);
+      const isImage = state.imageBlock === true;
+      image.wrap.hidden = !isImage;
+      if (isImage) {
+        image.setOptions(
+          IMAGE_DESTINATIONS.map((entry) => {
+            try {
+              const prepared = prepareImageToDesign(editor.document, state.blockPath, entry.target, { ...entry.options, validate: false });
+              return { value: entry.value, label: `${entry.label}${prepared.loss.length ? ` (loses ${prepared.loss.join(", ")})` : ""}` };
+            } catch (error) {
+              return { value: entry.value, label: `${entry.label} (unavailable)`, disabled: true, title: messageOf(error) };
+            }
+          }),
+        );
+        image.set("");
+      }
+    });
+  }
+
+  // --- slide structure -----------------------------------------------------------------------------
+
+  const slideBox = h("div", { class: "opf-dc-actions-block", "data-role": "slide-structure" });
+  {
+    const layouts = selectField("region-layout", "Place the blocks in regions", {
+      empty: "Choose a layout…",
+      help: "Each block gets its own part of the slide. Undo returns them to one list.",
+      onChange: (value) => {
+        const slideIndex = getSlide();
+        const choice = REGION_LAYOUTS[blockCount(slideIndex)]?.find((entry) => entry.id === value);
+        if (!choice) return;
+        run(() => placeBlocksInRegions(editor, slideIndex, choice.regions), (change) => `Blocks placed: ${choice.label.toLowerCase()}. ${lossText(change)}`);
+        reselect(`slides.${slideIndex}`);
+      },
+    });
+    const toBlocks = action("Turn regions into blocks", {
+      role: "regions-to-blocks",
+      prepare: () => prepareRegionsToBlocks(editor.document, getSlide(), { validate: false }),
+      apply: () => regionsAsBlocks(editor, getSlide()),
+      done: "Regions are now blocks, in reading order.",
+    });
+    const designImages = Object.keys(DESIGN_IMAGE_LABELS).map((source) =>
+      action(`Move the ${DESIGN_IMAGE_LABELS[source]} into the content`, {
+        role: `back-${source}`,
+        prepare: () => prepareImageToContent(editor.document, getSlide(), source, { validate: false }),
+        apply: () => moveImageToContent(editor, getSlide(), source),
+        done: `The ${DESIGN_IMAGE_LABELS[source]} is now an image block.`,
+      }),
+    );
+    slideBox.append(layouts.wrap, toBlocks.wrap, ...designImages.map((entry) => entry.wrap));
+    updaters.push((state) => {
+      const slide = editor.document.slides?.[state.slideIndex];
+      if (!slide) return;
+      const regions = regionKeysOfSlide(slide);
+      const count = blockCount(state.slideIndex);
+      const choices = regions.length ? [] : (REGION_LAYOUTS[count] ?? []);
+      layouts.wrap.hidden = choices.length === 0;
+      if (choices.length) {
+        layouts.setOptions(
+          choices.map((choice) => {
+            try {
+              const prepared = prepareBlocksToRegions(editor.document, state.slideIndex, choice.regions, { validate: false });
+              return { value: choice.id, label: `${choice.label}${prepared.loss.length ? ` (loses ${prepared.loss.join(", ")})` : ""}` };
+            } catch (error) {
+              return { value: choice.id, label: `${choice.label} (unavailable)`, disabled: true, title: messageOf(error) };
+            }
+          }),
+        );
+        layouts.set("");
+      }
+      toBlocks.wrap.hidden = regions.length === 0;
+      if (regions.length) toBlocks.update(state);
+      Object.keys(DESIGN_IMAGE_LABELS).forEach((source, index) => {
+        const present = slide.design?.[source] !== undefined && slide.design[source] !== false;
+        designImages[index].wrap.hidden = !present;
+        if (present) designImages[index].update(state);
+      });
+    });
+  }
+
+  /** The number of blocks a slide can place in regions: its `blocks`, or the content fields it holds inline. */
+  function blockCount(slideIndex) {
+    const slide = editor.document.slides?.[slideIndex];
+    if (!slide) return 0;
+    if (Array.isArray(slide.blocks)) return slide.blocks.length;
+    return ["text", "items", "bullets", "image", "video", "chart", "table", "code", "metric", "quote", "timeline"].filter((key) => slide[key] !== undefined).length;
+  }
+
+  return {
+    /** Nodes for the "Selected content" section: list levels, the group-of-metrics conversion and the arrange actions. */
+    nodes: { list, metrics: metrics.wrap, arrange },
+    /** The node for the "Slide structure" section. */
+    slideNode: slideBox,
+    /** Update every control from the session and the current selection. */
+    sync(state) {
+      const slide = editor.document.slides?.[state.slideIndex];
+      const imageBlock = state.blockPath ? isImageBlock(editor, state.blockPath) : false;
+      const full = { ...state, imageBlock, metricGroupPath: state.selectedPath ? metricGroupForSelection(editor.document, state.selectedPath) : undefined, slide };
+      ctxState.current = full;
+      for (const update of updaters) update(full);
+    },
+  };
+}
+
+function isImageBlock(editor, blockPath) {
+  const block = editor.get(blockPath);
+  if (!block || typeof block !== "object" || Array.isArray(block)) return false;
+  const keys = Object.keys(block).filter((key) => key !== "id" && key !== "extensions" && key !== "type");
+  return keys.length === 1 && keys[0] === "image";
+}

package/dist/data-grid.d.ts

@@ -0,0 +1,37 @@
+import type { EditorSession } from "./index.js";
+import type { DataGridTarget } from "./grid-model.js";
+
+export * from "./grid-model.js";
+
+export interface DataGridOptions {
+  editor: EditorSession;
+  /** Bind to one chart or table path. */
+  path?: string;
+  /** Or follow the host's selection into a chart or table (call `refresh()` when it changes). */
+  getSelectedPath?: () => string | undefined;
+  /** How chart numbers are read and shown: "auto" (the locale's decimal separator, the default), "." or ",". */
+  numberFormat?: "auto" | "." | ",";
+  /** A BCP 47 tag for "auto" (default: the page's `lang`, then the browser's language). */
+  locale?: string;
+  /** CSS length of the scrolling area (default "320px"). */
+  maxHeight?: string;
+  /** Called after every committed change. */
+  onChange?: (change: unknown) => void;
+  /** Called with every status or error message the grid shows. */
+  onStatus?: (message: string, info: { error: boolean }) => void;
+  /** Called when the grid starts or stops showing a chart or table. */
+  onTargetChange?: (target: DataGridTarget | undefined) => void;
+}
+export interface DataGrid {
+  element: HTMLElement;
+  refresh(): void;
+  focus(): void;
+  readonly target: DataGridTarget | undefined;
+  readonly numberFormat: "auto" | "." | ",";
+  setNumberFormat(format: "auto" | "." | ","): void;
+  /** Paste TSV or CSV text at the selected cell, as Ctrl+V does. Returns whether it applied. */
+  paste(text: string): boolean;
+  destroy(): void;
+}
+/** Mount a spreadsheet-like grid for a chart's inline data or a table. Every edit is one undoable session patch. */
+export declare function createDataGrid(container: HTMLElement, options: DataGridOptions): DataGrid;