hecks 3.10.0 → 3.12.0

data/lib/hecks/projections/site/cms_editor/templates/src/browser/blocks.js.tmpl

@@ -0,0 +1,500 @@
+__BANNER__
+
+// What a list of mixed blocks does with a script (the markup is ui/blocks.ts). Cards open and close;
+// a new card is made from the template the page carries for its kind; cards move up and down by
+// buttons, with the result announced in a polite live region and focus kept on the button that was
+// pressed; a card is removed after a question in a native dialog; and the cards are numbered again
+// after each change, renaming their fields so the form posts the list in the order it is shown.
+// A body inside a card gets its writing surface only when the card is first opened, so a page of
+// forty cards holds a handful of editors. A list written as a draft saves by itself (autosave.js),
+// and holds back while a card still lacks what its kind needs.
+//
+// The same script serves a page whose working copy is a value object (`data-draft-form` on the form):
+// the form as a whole saves by itself, whichever of its lists, pictures, writing surfaces and plain
+// inputs the person touches, and a picture outside any list opens the picker from its own group.
+import { retarget, safe } from "../ui/block_list.js";
+import { startDraft } from "./autosave.js";
+import { enhanceRows, firstProblem } from "./forms.js";
+import { mountMoments } from "./moments.js";
+import { mountPickers } from "./pickers.js";
+
+/** Loads the picture picker, or is null when the editor has no pictures to choose from. */
+const loadPicker = __PICKER_LOADER__;
+
+const pluralOf = (noun) => (/[^aeiou]y$/.test(noun) ? `${noun.slice(0, -1)}ies` : /(s|x|z|ch|sh)$/.test(noun) ? `${noun}es` : `${noun}s`);
+
+/** The attributes whose text names a field of a card, and so changes when the card's index does. */
+const NAMED = ["name", "id", "for", "aria-controls", "aria-describedby", "aria-labelledby", "href", "data-path", "data-name", "data-key", "data-alt"];
+
+/** Renames the fields of `card` (and the cards templates it carries) from index `was` to `at`. */
+function renumberFields(card, path, was, at) {
+  for (const element of [card, ...card.querySelectorAll("*")]) {
+    if (element.localName === "template") element.innerHTML = retarget(element.innerHTML, path, was, at);
+    for (const name of NAMED) {
+      if (element.hasAttribute(name)) element.setAttribute(name, retarget(element.getAttribute(name), path, was, at));
+    }
+  }
+}
+
+/** The cards of a group, in the order shown. */
+const cardsOf = (group) => [...group.querySelector(":scope > [data-cards]").children];
+
+/** The group a card is in. */
+const groupOf = (card) => card.closest("[data-group]");
+
+/** The list a group belongs to (the outermost group). */
+const listOf = (node) => node.closest("[data-block-list]");
+
+/** The working copies saved by the form as a whole, by form. */
+const formDrafts = new WeakMap();
+
+/** The polite line that speaks for `root`: a list's own, or a form's (made when it has none yet). */
+function lineOf(root) {
+  if (!root.matches("form")) return root.querySelector("[data-block-say]");
+  let line = root.querySelector(":scope > [data-form-say]");
+  if (!line) {
+    line = Object.assign(document.createElement("p"), { className: "sr-only" });
+    line.setAttribute("role", "status");
+    line.setAttribute("aria-live", "polite");
+    line.dataset.formSay = "";
+    root.append(line);
+  }
+  return line;
+}
+
+const say = (root, text) => {
+  const line = lineOf(root);
+  line.textContent = "";
+  setTimeout(() => { line.textContent = text; }, 30);
+};
+
+/** The controls of a card that are its own: not those of a card nested in it, nor a writing surface's fields. */
+const ownControls = (card) =>
+  [...card.querySelectorAll("input, select, textarea")].filter((control) => control.closest("[data-card]") === card && !control.closest("[data-body-editor]"));
+
+/** The one line that stands for a card: its first required text, else its longest text. */
+function summaryOf(card) {
+  const prefix = `${groupOf(card).dataset.path}.${card.dataset.index}.`;
+  const requires = (card.dataset.requires ?? "").split(" ").filter(Boolean).map((slot) => `${prefix}${slot}`);
+  const alt = card.dataset.summaryAlt ? `${prefix}${card.dataset.summaryAlt}` : null;
+  const named = (control) => requires.includes(control.name) || requires.some((slot) => control.name === `${slot}.value`);
+  const texts = ownControls(card)
+    .filter((control) => (control.type === "text" || control.type === "textarea") && control.value.trim() !== "" && (!control.closest("[data-picture]") || named(control) || control.name === alt))
+    .map((control) => ({ text: control.value.trim(), required: named(control), alt: control.name === alt }));
+  const chosen = texts.find((one) => one.alt) ?? texts.find((one) => one.required) ?? texts.reduce((best, one) => (!best || one.text.length > best.text.length ? one : best), null);
+  if (chosen) return chosen.text.length > 80 ? `${chosen.text.slice(0, 79)}…` : chosen.text;
+  const counts = [...card.querySelectorAll(":scope > [data-card-panel] > [data-group]")]
+    .map((group) => [group.dataset.noun, cardsOf(group).length])
+    .filter(([, count]) => count > 0)
+    .map(([noun, count]) => `${count} ${count === 1 ? noun : pluralOf(noun)}`);
+  return counts.join(", ");
+}
+
+const titleOf = (card) => {
+  const kind = card.querySelector(":scope > [data-card-head] [data-kind-badge]")?.textContent;
+  const number = card.querySelector(":scope > [data-card-head] [data-card-number]")?.textContent;
+  const noun = groupOf(card).dataset.noun;
+  const summary = card.querySelector(":scope > [data-card-head] [data-card-summary]")?.textContent;
+  return `${noun} ${number}${kind ? `, ${kind}` : ""}${summary ? `: ${summary}` : ""}`;
+};
+
+/** Sets the words that name a card to the tools and the toggle (they say which card they move, open or remove). */
+function nameTools(card) {
+  const noun = groupOf(card).dataset.noun;
+  const number = card.querySelector(":scope > [data-card-head] [data-card-number]").textContent;
+  const summary = card.querySelector(":scope > [data-card-head] [data-card-summary]").textContent;
+  const kind = card.querySelector(":scope > [data-card-head] [data-kind-badge]")?.textContent;
+  const what = `${noun} ${number}${kind ? `, ${kind}` : ""}${summary ? `, ${summary}` : ""}`;
+  const words = { up: "Move up", down: "Move down", remove: "Remove" };
+  for (const button of card.querySelectorAll(":scope > [data-card-head] [data-tools] button")) {
+    const label = `${words[button.dataset.action]} ${what}`;
+    button.setAttribute("aria-label", label);
+    button.title = label;
+  }
+}
+
+/** Numbers the group's cards again, and says which tools no longer apply. */
+function renumber(group) {
+  const path = group.dataset.path;
+  const cards = cardsOf(group);
+  cards.forEach((card, at) => {
+    if (card.dataset.index !== String(at)) {
+      renumberFields(card, path, card.dataset.index, String(at));
+      card.dataset.index = String(at);
+    }
+    card.querySelector(":scope > [data-card-head] [data-card-number]").textContent = String(at + 1);
+    const static_ = card.querySelector(":scope > [data-card-head] [data-card-static] span");
+    if (static_) static_.textContent = `${group.dataset.noun.charAt(0).toUpperCase()}${group.dataset.noun.slice(1)} ${at + 1}`;
+    card.querySelector('[data-action="up"]')?.setAttribute("aria-disabled", String(at === 0));
+    card.querySelector('[data-action="down"]')?.setAttribute("aria-disabled", String(at === cards.length - 1));
+    nameTools(card);
+  });
+  const count = group.querySelector(":scope > legend [data-count]");
+  if (count) count.textContent = `(${cards.length})`;
+  const empty = group.querySelector(":scope > [data-empty]");
+  if (empty) empty.hidden = cards.length > 0;
+  const max = Number(group.dataset.max ?? 0);
+  for (const add of group.querySelectorAll(":scope > [data-adder] [data-action=add], :scope > [data-action=add]")) {
+    add.setAttribute("aria-disabled", String(max > 0 && cards.length >= max));
+  }
+}
+
+/** Opens or closes a card. Opening mounts the writing surfaces inside it that are not yet mounted. */
+function toggle(card, open) {
+  const button = card.querySelector(':scope > [data-card-head] [data-action="toggle"]');
+  const panel = card.querySelector(":scope > [data-card-panel]");
+  const was = !panel.hidden;
+  const now = open ?? !was;
+  panel.hidden = !now;
+  button.setAttribute("aria-expanded", String(now));
+  button.querySelector("use")?.setAttribute("href", `#i-${now ? "chevron-down" : "chevron-right"}`);
+  if (now) mountEditors(panel);
+}
+
+/** Gives each visible rich-text body inside `scope` its writing surface, once. */
+function mountEditors(scope) {
+  const pending = [...scope.querySelectorAll("[data-body-editor]:not([data-mounted])")];
+  if (pending.length === 0) return;
+  for (const root of pending) {
+    const card = root.closest("[data-card]");
+    const noun = groupOf(card).dataset.noun;
+    root.dataset.base ??= root.dataset.label;
+    root.dataset.label = `${root.dataset.base} of ${noun} ${Number(card.dataset.index) + 1}`;
+  }
+  import("./body_editor.js").then((editor) => editor.mountWithin(scope));
+}
+
+/** Makes a card's script-only parts live: its toggle, its tools, and the cards nested in it. */
+function dress(card) {
+  card.querySelector(":scope > [data-card-head] [data-card-static]")?.setAttribute("hidden", "");
+  for (const node of card.querySelectorAll(":scope > [data-card-head] [data-tools], :scope > [data-card-head] [data-action=toggle]")) node.hidden = false;
+  const button = card.querySelector(':scope > [data-card-head] [data-action="toggle"]');
+  const open = card.hasAttribute("data-invalid") || card.hasAttribute("data-open");
+  const panel = card.querySelector(":scope > [data-card-panel]");
+  panel.hidden = !open;
+  button.setAttribute("aria-expanded", String(open));
+  button.querySelector("use")?.setAttribute("href", `#i-${open ? "chevron-down" : "chevron-right"}`);
+  for (const group of card.querySelectorAll(":scope > [data-card-panel] > [data-group]")) {
+    for (const add of group.querySelectorAll(":scope > [data-action=add]")) add.hidden = false;
+    for (const nested of cardsOf(group)) dress(nested);
+    renumber(group);
+  }
+}
+
+/** A new card for `group`, from the template of `kind` ("" for a nested group). */
+function create(group, kind) {
+  const template = [...group.querySelectorAll(":scope > template[data-card-template]")].find((one) => one.dataset.kind === kind);
+  if (!template) return null;
+  const cards = group.querySelector(":scope > [data-cards]");
+  const token = group.dataset.depth === "0" ? "ZZI0ZZ" : "ZZI1ZZ";
+  cards.insertAdjacentHTML("beforeend", template.innerHTML.split(token).join(String(cardsOf(group).length)));
+  const card = cards.lastElementChild;
+  dress(card);
+  enhanceRows(card);
+  mountPickers(card);
+  mountMoments(card);
+  return card;
+}
+
+/** Whether a card still lacks something its kind requires or a picture's description, with what. */
+function lacks(card) {
+  const prefix = `${groupOf(card).dataset.path}.${card.dataset.index}.`;
+  const names = (card.dataset.requires ?? "").split(" ").filter(Boolean);
+  const held = (slot) => [...card.querySelectorAll("input, select, textarea")].some((control) => {
+    const own = control.name === `${prefix}${slot}` || control.name.startsWith(`${prefix}${slot}.`);
+    return own && control.type !== "checkbox" && control.value.trim() !== "";
+  });
+  const missing = names.filter((slot) => !held(slot));
+  const own = [...card.querySelectorAll("[data-picture]")].filter((picture) => picture.closest("[data-card]") === card);
+  if (own.some(undescribed) && !missing.includes("alt")) missing.push("alt");
+  return missing;
+}
+
+/** Whether a picture names its file and has no description. */
+function undescribed(picture) {
+  const form = picture.closest("form") ?? document;
+  const key = form.querySelector(`[name="${CSS.escape(picture.dataset.key)}"]`);
+  const alt = form.querySelector(`[name="${CSS.escape(picture.dataset.alt)}"]`);
+  return Boolean(key?.value.trim()) && alt !== null && alt.value.trim() === "";
+}
+
+/** The card, and the nested cards under it, that lack something. */
+function incomplete(list) {
+  return [...list.querySelectorAll("[data-card]")].filter((card) => lacks(card).length > 0);
+}
+
+/** The pictures under `scope` that are in no list's card: a picture slot of a value object. */
+const loose = (scope) => [...scope.querySelectorAll("[data-picture]")].filter((picture) => !picture.closest("[data-card]"));
+
+/** Marks a picture's alt control invalid, with the line that says what to do, or clears the mark. */
+function markAlt(picture, show) {
+  const alt = picture.querySelector(`[name="${picture.dataset.alt}"]`);
+  if (!alt) return;
+  const id = `${alt.id}-error`;
+  picture.querySelector(`#${CSS.escape(id)}`)?.remove();
+  alt.removeAttribute("aria-invalid");
+  if (!show) return;
+  alt.setAttribute("aria-invalid", "true");
+  alt.setAttribute("aria-describedby", id);
+  alt.after(Object.assign(document.createElement("p"), { id, className: "text-xs font-semibold text-error", textContent: "Describe the picture for people who cannot see it." }));
+}
+
+/** The registered pictures' addresses by key, fetched once for the thumbnails. */
+let known = null;
+function pictures(url) {
+  known ??= fetch(url, { headers: { Accept: "application/json" }, credentials: "same-origin" })
+    .then((response) => (response.ok ? response.json() : { pictures: [] }))
+    .then((answer) => new Map(answer.pictures.map((picture) => [picture.key, picture.url])))
+    .catch(() => new Map());
+  return known;
+}
+
+/** Shows the thumbnail of the picture a card names, when it is a registered one. */
+async function thumb(picture) {
+  const url = picture.querySelector("[data-action=pick-picture]")?.dataset.media;
+  const image = picture.querySelector("[data-picture-thumb]");
+  const key = picture.querySelector(`[name="${picture.dataset.key}"]`)?.value.trim();
+  if (!url || !image) return;
+  const found = key ? (await pictures(url)).get(key) : null;
+  image.hidden = !found;
+  if (found) {
+    image.addEventListener("error", () => { image.hidden = true; }, { once: true });
+    image.src = found;
+  }
+}
+
+/** Opens the picture picker for a card's picture and puts the choice in its key and alt text. */
+async function pick(picture, list, afterwards) {
+  const button = picture.querySelector("[data-action=pick-picture]");
+  const key = picture.querySelector(`[name="${CSS.escape(picture.dataset.key)}"]`);
+  const alt = picture.querySelector(`[name="${CSS.escape(picture.dataset.alt)}"]`);
+  if (!loadPicker) return;
+  const { openPicker } = await loadPicker();
+  openPicker(picture, picture, {
+    url: button.dataset.media,
+    current: { mediaRef: key.value, alt: alt?.value ?? "" },
+    onPick: (chosen, text) => {
+      key.value = chosen;
+      if (alt) alt.value = text;
+      key.dispatchEvent(new Event("input", { bubbles: true }));
+      markAlt(picture, false);
+      known = null;
+      thumb(picture);
+      say(list, "Picture chosen.");
+      key.dispatchEvent(new Event("change", { bubbles: true }));
+    },
+    onClose: () => { button.focus(); afterwards(); },
+  });
+}
+
+function enhance(list) {
+  const form = list.closest("form");
+  let draft = null;
+  let asking = null;
+  const dialog = list.querySelector(":scope > [data-remove-dialog]");
+  const touch = () => (draft ?? formDrafts.get(form))?.touch();
+
+  const refresh = (card) => {
+    const line = card.querySelector(":scope > [data-card-head] [data-card-summary]");
+    if (line) line.textContent = summaryOf(card);
+    nameTools(card);
+    for (const parent of [card.parentElement?.closest("[data-card]")]) if (parent) refresh(parent);
+  };
+
+  const finish = (group, card, words) => {
+    renumber(group);
+    say(listOf(group), words);
+    touch();
+    return card;
+  };
+
+  const add = (group, kind) => {
+    const max = Number(group.dataset.max ?? 0);
+    const noun = group.dataset.noun;
+    if (max > 0 && cardsOf(group).length >= max) return say(list, `At most ${max} ${noun}s fit here.`);
+    const card = create(group, kind);
+    if (!card) return null;
+    renumber(group);
+    toggle(card, true);
+    refresh(card);
+    card.querySelector("input:not([type=hidden]), select, textarea")?.focus();
+    card.scrollIntoView({ block: "nearest" });
+    return finish(group, card, `Added ${titleOf(card)}. ${cardsOf(group).length} in the list.`);
+  };
+
+  const move = (card, step) => {
+    const group = groupOf(card);
+    const cards = cardsOf(group);
+    const at = cards.indexOf(card);
+    const to = at + step;
+    if (to < 0 || to >= cards.length) return say(list, `${titleOf(card)} is already ${step < 0 ? "first" : "last"}.`);
+    if (step < 0) cards[to].before(card);
+    else cards[to].after(card);
+    card.querySelector(`[data-action="${step < 0 ? "up" : "down"}"]`).focus();
+    finish(group, card, `Moved ${titleOf(card)} to position ${to + 1} of ${cards.length}.`);
+  };
+
+  const remove = (card) => {
+    const group = groupOf(card);
+    const cards = cardsOf(group);
+    const at = cards.indexOf(card);
+    const words = titleOf(card);
+    const next = cards[at + 1] ?? cards[at - 1];
+    card.remove();
+    renumber(group);
+    const target = next?.querySelector(':scope > [data-card-head] [data-action="toggle"]') ?? group.querySelector(":scope > [data-adder] select, :scope > [data-action=add]");
+    target?.focus();
+    finish(group, card, `Removed ${words}. ${cardsOf(group).length} left in the list.`);
+  };
+
+  list.addEventListener("click", (event) => {
+    const button = event.target.closest("[data-action]");
+    if (!button || listOf(button) !== list) return;
+    const card = button.closest("[data-card]");
+    const action = button.dataset.action;
+    if (action === "toggle") return toggle(card);
+    if (action === "up") return move(card, -1);
+    if (action === "down") return move(card, 1);
+    if (action === "pick-picture") return pick(button.closest("[data-picture]"), list, () => {});
+    if (action === "remove") {
+      asking = { card, opener: button };
+      dialog.querySelector("[data-remove-title]").textContent = `Remove ${titleOf(card)}?`;
+      return dialog.showModal();
+    }
+    if (action === "remove-cancel") return dialog.close();
+    if (action === "remove-confirm") {
+      const chosen = asking;
+      asking = null;
+      dialog.close();
+      return remove(chosen.card);
+    }
+    if (action === "add") {
+      const group = button.closest("[data-group]");
+      const kind = group.querySelector(":scope > [data-adder] [data-add-kind]")?.value ?? "";
+      add(group, kind);
+    }
+  });
+
+  form?.addEventListener("input", (event) => {
+    const card = event.target.closest?.("[data-card]");
+    if (card) refresh(card);
+    const picture = event.target.closest?.("[data-picture]");
+    if (picture && event.target.name === picture.dataset.key) thumb(picture);
+    touch();
+  });
+  form?.addEventListener("change", touch);
+  form?.addEventListener("editor:changed", (event) => {
+    const card = event.target.closest?.("[data-card]");
+    if (card) refresh(card);
+    touch();
+  });
+  form?.addEventListener("focusout", (event) => {
+    const picture = event.target.closest?.("[data-picture]");
+    if (picture && event.target.name === picture.dataset.alt) markAlt(picture, undescribed(picture));
+    (draft ?? formDrafts.get(form))?.blur();
+  });
+
+  dialog.addEventListener("close", () => {
+    if (asking) asking.opener.focus();
+    asking = null;
+  });
+  for (const card of cardsOf(list)) dress(card);
+  for (const node of list.querySelectorAll(":scope > [data-adder]")) node.hidden = false;
+  for (const group of [list, ...list.querySelectorAll("[data-group]")]) renumber(group);
+  for (const card of list.querySelectorAll("[data-card]")) refresh(card);
+  for (const picture of list.querySelectorAll("[data-picture]")) thumb(picture);
+  for (const open of list.querySelectorAll("[data-card][data-invalid] > [data-card-panel], [data-card][data-open] > [data-card-panel]")) mountEditors(open);
+
+  if (list.hasAttribute("data-draft")) {
+    draft = startDraft(list, {
+      form,
+      blocked: () => {
+        const first = incomplete(list)[0];
+        return first ? `${titleOf(first)} needs more before it can be saved. Complete it, or use Save draft to see what the domain says.` : null;
+      },
+      refused: (problems) => reveal(list, problems),
+    });
+  }
+}
+
+/** Opens the cards a refusal names, and the cards that hold them, so what is wrong can be seen. */
+function reveal(scope, problems) {
+  for (const problem of problems) {
+    let card = problem.name ? scope.querySelector(`#blk-${safe(problem.name)}`) : null;
+    while (card) {
+      toggle(card, true);
+      card = card.parentElement?.closest("[data-card]");
+    }
+  }
+}
+
+/** A form whose working copy is a value object saves as a whole, whichever part of it is touched. */
+function enhanceForm(form) {
+  const draft = startDraft(form, {
+    form,
+    blocked: () => {
+      const first = incomplete(form)[0];
+      if (first) return `${titleOf(first)} needs more before it can be saved. Complete it, remove it, or use Save draft to see what the domain says.`;
+      return loose(form).some(undescribed) ? "A picture needs its description before it can be saved." : null;
+    },
+    refused: (problems) => reveal(form, problems),
+  });
+  formDrafts.set(form, draft);
+  form.addEventListener("input", () => draft.touch());
+  form.addEventListener("change", () => draft.touch());
+  form.addEventListener("editor:changed", () => draft.touch());
+  form.addEventListener("focusout", () => draft.blur());
+}
+
+/**
+ * A form is not sent while a picture names its file and has no description: the group says so beside
+ * the field, the card that holds it opens, and focus goes there. (The domain refuses the same, in its
+ * own words, when this is not in the way, as for a request that does not come from this page.)
+ */
+function guardPictures(form) {
+  form.addEventListener("submit", (event) => {
+    const missing = [...form.querySelectorAll("[data-picture]")].filter(undescribed);
+    if (missing.length === 0) return;
+    event.preventDefault();
+    event.stopImmediatePropagation();
+    for (const picture of missing) {
+      let card = picture.closest("[data-card]");
+      while (card) {
+        toggle(card, true);
+        card = card.parentElement?.closest("[data-card]");
+      }
+      markAlt(picture, true);
+    }
+    const first = missing[0].querySelector(`[name="${missing[0].dataset.alt}"]`);
+    first?.scrollIntoView({ block: "center" });
+    first?.focus({ preventScroll: true });
+    say(form, "A picture needs its description before it can be saved.");
+  }, true);
+}
+
+/** A picture that is no card's (a slot of a value object) opens the picker from its own group. */
+function enhanceLoose(form) {
+  const own = (picture) => picture && !picture.closest("[data-card]");
+  if (loose(form).length === 0) return;
+  for (const picture of loose(form)) thumb(picture);
+  form.addEventListener("click", (event) => {
+    const picture = event.target.closest?.("[data-action=pick-picture]")?.closest("[data-picture]");
+    if (own(picture)) pick(picture, form, () => {});
+  });
+  form.addEventListener("input", (event) => {
+    const picture = event.target.closest?.("[data-picture]");
+    if (own(picture) && event.target.name === picture.dataset.key) thumb(picture);
+  });
+  form.addEventListener("focusout", (event) => {
+    const picture = event.target.closest?.("[data-picture]");
+    if (own(picture) && event.target.name === picture.dataset.alt) markAlt(picture, undescribed(picture));
+  });
+}
+
+export function enhanceBlocks() {
+  for (const form of document.querySelectorAll("form[data-draft-form]")) enhanceForm(form);
+  for (const list of document.querySelectorAll("[data-block-list]")) enhance(list);
+  for (const form of document.querySelectorAll("form")) enhanceLoose(form);
+  for (const form of document.querySelectorAll("form[data-form]")) guardPictures(form);
+  if (document.querySelector("[data-card][data-open], [data-card][data-invalid]")) firstProblem();
+}

data/lib/hecks/projections/site/cms_editor/templates/src/browser/body_doc.js.tmpl

@@ -0,0 +1,175 @@
+__BANNER__
+
+// The domain's document body and the rich-text editor's document, converted one into the other. This
+// is the only place the two meet: the editor (body_editor.js) holds a Tiptap document while a person
+// writes, and every change is turned back into the body the domain takes and posted as the same
+// dotted-path form fields as any other value object. The editor's own format is never sent or stored.
+//
+// Plain JavaScript with no dependencies and no DOM, so the conversion runs the same in node (where
+// the specs hold it) and in the browser. The two models agree on lists because the editor's lists are
+// flat: each item is a block of its own with an `indent`, as a body's list item has a `depth`, so an
+// item converts to an item. A body list block becomes a run of items, and a run of adjacent items
+// with the same alignment and shift becomes one list block again (its kind is that of its first
+// item, and an item of the other kind carries `list_kind`). Where the editor's document holds
+// something the body cannot, it is reduced to the nearest thing the body holds.
+import { ALIGNS, MARKS, MAX_DEPTH, MAX_INDENT, safeHref } from "../ui/body_model.js";
+
+/** The editor's list item node for each kind of body list, and back. */
+const ITEMS = { bullet_list: "flatListItemUnordered", numbered_list: "flatListItemOrdered" };
+const KINDS = { flatListItemUnordered: "bullet_list", flatListItemOrdered: "numbered_list" };
+
+const whole = (value, low, high) => (Number.isInteger(Number(value)) && value !== "" && value !== null && value !== undefined ? Math.min(high, Math.max(low, Number(value))) : null);
+
+const list = (value) => (Array.isArray(value) ? value : []);
+
+const markName = (mark) => (typeof mark === "string" ? mark : mark?.name);
+
+/** The layout attributes of a block, as the editor's nodes carry them (`shift` is the block's indent). */
+function layoutAttrs(block) {
+  return { align: ALIGNS.includes(block.align) ? block.align : null, shift: whole(block.indent, 0, MAX_INDENT) };
+}
+
+/** The inline nodes of `spans`: text carrying its marks and address, and a hard break for a line break. */
+export function spansToInline(spans) {
+  const out = [];
+  for (const span of list(spans)) {
+    const names = MARKS.filter((name) => list(span?.marks).map(markName).includes(name));
+    const href = safeHref(span?.href);
+    const marks = [...names.map((type) => ({ type })), ...(href ? [{ type: "link", attrs: { href } }] : [])];
+    String(span?.text ?? "").split("\n").forEach((part, at) => {
+      if (at > 0) out.push({ type: "hardBreak" });
+      if (part !== "") out.push({ type: "text", text: part, ...(marks.length ? { marks } : {}) });
+    });
+  }
+  return out;
+}
+
+const paragraph = (spans, attrs = {}) => ({ type: "paragraph", attrs, content: spansToInline(spans) });
+
+/** The items of a body list block as flat items, numbering ordered ones as the editor does. */
+function itemsToNodes(block) {
+  const kind = block.kind;
+  const layout = layoutAttrs(block);
+  const counts = [];
+  let above = -1;
+  return list(block.items).map((item) => {
+    const depth = Math.min(whole(item?.depth, 0, MAX_DEPTH) ?? 0, above + 1);
+    above = depth;
+    counts.length = depth + 1;
+    const own = item?.list_kind in ITEMS ? item.list_kind : kind;
+    counts[depth] = own === "numbered_list" ? (counts[depth] ?? 0) + 1 : 0;
+    const attrs = { ...layout, ...(depth > 0 ? { indent: depth } : {}), ...(own === "numbered_list" ? { counter: counts[depth] } : {}) };
+    return { type: ITEMS[own], attrs, content: spansToInline(item?.spans) };
+  });
+}
+
+function blockToNodes(block) {
+  const kind = block?.kind;
+  if (kind === "divider") return [{ type: "horizontalRule" }];
+  if (kind === "image") return [{ type: "image", attrs: { mediaRef: block.media_ref ?? "", alt: block.alt ?? "", caption: block.caption ?? "" } }];
+  if (kind in ITEMS) return itemsToNodes(block);
+  const layout = layoutAttrs(block ?? {});
+  if (kind === "quote") return [{ type: "blockquote", attrs: layout, content: [paragraph(block.spans)] }];
+  if (kind === "heading") return [{ type: "heading", attrs: { level: whole(block.level, 1, 4) ?? 2, ...layout }, content: spansToInline(block.spans) }];
+  return [paragraph(block?.spans, layout)];
+}
+
+/** The editor's document for a body: a body with no blocks is one empty paragraph, as the editor needs. */
+export function bodyToDoc(body) {
+  const content = list(body?.blocks).flatMap(blockToNodes);
+  return { type: "doc", content: content.length ? content : [{ type: "paragraph", attrs: {} }] };
+}
+
+/** The mark names of an inline node, in the body's own order, and its address. */
+function marksOf(node) {
+  const held = list(node.marks);
+  const names = MARKS.filter((name) => held.some((mark) => mark.type === name));
+  const link = held.find((mark) => mark.type === "link");
+  return { marks: names.map((name) => ({ name })), href: safeHref(link?.attrs?.href) ?? undefined };
+}
+
+/** The spans of inline nodes: adjacent spans of the same marks and address become one, empty ones go. */
+export function inlineToSpans(nodes) {
+  const out = [];
+  for (const node of list(nodes)) {
+    const span = node.type === "hardBreak" ? { text: "\n", marks: [] } : node.type === "text" ? { text: node.text ?? "", ...marksOf(node) } : null;
+    if (!span || span.text === "") continue;
+    const last = out[out.length - 1];
+    const same = last && last.text !== "\n" && span.text !== "\n" && last.href === span.href && JSON.stringify(last.marks) === JSON.stringify(span.marks);
+    if (same) last.text += span.text;
+    else out.push({ text: span.text, marks: span.marks, ...(span.href ? { href: span.href } : {}) });
+  }
+  return out;
+}
+
+const withLayout = (node) => {
+  const attrs = node.attrs ?? {};
+  const shift = whole(attrs.shift, 0, MAX_INDENT);
+  return { ...(ALIGNS.includes(attrs.align) ? { align: attrs.align } : {}), ...(shift !== null && shift > 0 ? { indent: shift } : {}) };
+};
+
+const layoutKey = (node) => JSON.stringify(withLayout(node));
+
+/** Groups the run of flat items that starts `nodes[from]` into one list block; returns it and where it ends. */
+function listBlock(nodes, from) {
+  const first = nodes[from];
+  const kind = KINDS[first.type];
+  const items = [];
+  let at = from;
+  while (at < nodes.length && nodes[at].type in KINDS && layoutKey(nodes[at]) === layoutKey(first)) {
+    const node = nodes[at];
+    const above = items.length === 0 ? -1 : items[items.length - 1].depth;
+    const depth = Math.min(whole(node.attrs?.indent, 0, MAX_DEPTH) ?? 0, above + 1);
+    items.push({ spans: inlineToSpans(node.content), depth, ...(KINDS[node.type] !== kind ? { list_kind: KINDS[node.type] } : {}) });
+    at += 1;
+  }
+  return [{ kind, ...withLayout(first), items }, at];
+}
+
+function blockFromNode(node) {
+  switch (node.type) {
+    case "horizontalRule":
+      return [{ kind: "divider" }];
+    case "image":
+      return [{ kind: "image", ...(node.attrs?.mediaRef ? { media_ref: node.attrs.mediaRef } : {}), ...(node.attrs?.alt ? { alt: node.attrs.alt } : {}), ...(node.attrs?.caption ? { caption: node.attrs.caption } : {}) }];
+    case "heading":
+      return [{ kind: "heading", level: whole(node.attrs?.level, 1, 4) ?? 2, ...withLayout(node), spans: inlineToSpans(node.content) }];
+    case "blockquote":
+      return list(node.content).filter((child) => child.type === "paragraph").map((child) => ({ kind: "quote", ...withLayout(node), spans: inlineToSpans(child.content) }));
+    default:
+      return [{ kind: "paragraph", ...withLayout(node), spans: inlineToSpans(node.content) }];
+  }
+}
+
+const emptyParagraph = (block) => block.kind === "paragraph" && block.spans.length === 0 && !("align" in block) && !("indent" in block);
+
+/** The body for an editor document. Trailing empty paragraphs, which the editor keeps for typing, are not blocks. */
+export function docToBody(doc) {
+  const nodes = list(doc?.content);
+  const blocks = [];
+  for (let at = 0; at < nodes.length;) {
+    if (nodes[at].type in KINDS) {
+      const [made, next] = listBlock(nodes, at);
+      blocks.push(made);
+      at = next;
+    } else {
+      blocks.push(...blockFromNode(nodes[at]));
+      at += 1;
+    }
+  }
+  while (blocks.length > 0 && emptyParagraph(blocks[blocks.length - 1])) blocks.pop();
+  return { blocks };
+}
+
+/**
+ * What loading a body into the editor changes, so the editor can say so: a list item more than one
+ * level below the one above it is moved up, because the editor's lists cannot skip a level.
+ */
+export function reductions(body) {
+  const notes = [];
+  for (const block of list(body?.blocks)) {
+    const depths = list(block.items).map((item) => whole(item?.depth, 0, MAX_DEPTH) ?? 0);
+    if (depths.some((depth, at) => depth > (at === 0 ? 0 : depths[at - 1] + 1))) notes.push("a list item more than one level below the one above it was moved up to one level below");
+  }
+  return notes;
+}