hecks 3.9.1 → 3.11.0

data/lib/hecks/projections/site/cms_editor/templates/src/ui/blocks.ts.tmpl

@@ -0,0 +1,275 @@
+__BANNER__
+
+// A list of mixed blocks (or of one kind of group, with no kind) as an ordered list of cards. Each
+// card is one block: its kind as a badge, one line that says what it holds, tools to move it up
+// and down and remove it, and, when open, only the slots its kind uses (see block_list.js). The
+// list is plain markup that posts the same dotted-path fields every value object does, so a
+// browser with no script still edits what it has; browser/blocks.js adds adding, removing,
+// reordering and opening cards. A card holds its repeated parts as groups of cards one level in.
+//
+// A new card is made from a `<template>` the page carries per kind, written with the index left
+// as `ZZI0ZZ` (and `ZZI1ZZ` one level in), so a new card is what the server would have drawn.
+// A group's members show all their slots, each required as its value object declares, within the
+// limits the holder's rules give (see `Limits` in the generator).
+import type { Aggregate, Attr, BlockList } from "../schema.ts";
+import { esc } from "./html.ts";
+import { icon } from "./icons.ts";
+import { filled, kindOf, lacking, slotsOf, summaryOf } from "./block_list.js";
+import { label, limitsNote, pluralOf, singular } from "./words.ts";
+
+/**
+ * A refused value object: where it is in the command's arguments (`path`) and in the form (`name`, the
+ * dotted name its fields share: `content.items.3` or `content.items.3.parts.1`), which of its
+ * parts are at fault, and why.
+ */
+export interface Problem {
+  path: (string | number)[];
+  name: string;
+  slots: string[];
+  message: string;
+}
+
+/** What the list needs from the form around it. */
+export interface Rendering {
+  /** One part's control: its markup at `prefix + part.name`, flagged with `message` when it is the one a refusal names. */
+  slot: (part: Attr, prefix: string, value: unknown, message?: string, required?: boolean, rows?: boolean) => string;
+  /** Whether the list saves a draft by itself (see browser/autosave.js). */
+  draft: boolean;
+  /** The blocks a refused command named. */
+  problems: Problem[];
+  /** The one-line caption of the list: its label, with a mark when it is required. */
+  caption: string;
+  /** Whether a picture picker is on offer (`data-media`'s address), else the key is typed. */
+  media?: string;
+  /** What the domain said about the list as a whole (its size), when it did. */
+  message?: string;
+}
+
+type Block = Record<string, unknown>;
+
+/** A part of a block as one kind shows it (see `slotsOf`). */
+interface Slot {
+  part: Attr;
+  required: boolean;
+  mentioned: boolean;
+}
+
+/** The index placeholders a card's template is written with, by how deep the card is. */
+const TOKEN = ["ZZI0ZZ", "ZZI1ZZ"];
+
+const safe = (text: string): string => text.replace(/[^A-Za-z0-9]+/g, "-");
+
+/** The control of the part that holds the kind: the kind as a hidden input, in the value object's own shape. */
+function kindInput(agg: Aggregate, list: BlockList, parts: Attr[], prefix: string, kind: string): string {
+  const part = parts.find((candidate) => candidate.name === list.discriminator);
+  const inner = part?.kind === "object" ? (agg.valueObjects[part.type] ?? [])[0]?.name : undefined;
+  const name = `${prefix}${list.discriminator}${inner ? `.${inner}` : ""}`;
+  return `<input type="hidden" name="${esc(name)}" value="${esc(kind)}" data-kind-input>`;
+}
+
+const tool = (action: string, glyph: string, text: string, what: string): string =>
+  `<button type="button" class="btn btn-ghost btn-square btn-sm" data-action="${action}" aria-label="${esc(`${text} ${what}`)}" title="${esc(`${text} ${what}`)}">${icon(glyph)}</button>`;
+
+/** The tools of a card: shown by the script, which is what makes them work. */
+function tools(noun: string, number: number | string, summary: string): string {
+  const what = `${noun} ${number}${summary ? `, ${summary}` : ""}`;
+  const move = [tool("up", "arrow-up", "Move up", what), tool("down", "arrow-down", "Move down", what)];
+  return `<div class="flex shrink-0 items-center" data-tools hidden>${[...move, tool("remove", "trash", "Remove", what)].join("")}</div>`;
+}
+
+interface Place {
+  /** The list's name, then the index, as the path of the card's fields. */
+  path: string;
+  index: number | string;
+  depth: number;
+  noun: string;
+  /** The value object a card of this place holds one of. */
+  type: string;
+  list: BlockList;
+  parts: Attr[];
+  /** True in a list of one kind of group: what a part is required to be is what its value object declares. */
+  declared: boolean;
+}
+
+function badge(kind: string | null): string {
+  return kind ? `<span class="badge badge-soft badge-neutral shrink-0 font-semibold" data-kind-badge>${esc(label(kind))}</span>` : "";
+}
+
+/** The slots of a card, each as its control, with a picture's parts and a repeated part drawn as groups. */
+function slotsOfCard(agg: Aggregate, place: Place, rendering: Rendering, block: Block, kind: string | null, flagged: Problem | undefined): string {
+  const prefix = `${place.path}.${place.index}.`;
+  const picture = place.list.pictures?.[place.type];
+  const plain = (part: Attr): Slot => ({ part, required: place.declared && !part.optional, mentioned: false });
+  const shown: Slot[] = kind === null ? place.parts.map(plain) : (slotsOf(place.list, place.parts, kind) as Slot[]);
+  const held = shown.filter((slot) => !(picture && (slot.part.name === picture.alt || slot.part.name === picture.caption)));
+  const draw = held.map(({ part, required, mentioned }) => {
+    const note = mentioned ? `<p class="-mt-3 mb-3 text-xs text-muted">A rule of this kind of ${esc(singular(place.noun))} reads this.</p>` : "";
+    const message = flagged?.slots.includes(part.name) ? flagged.message : undefined;
+    if (picture && part.name === picture.key) return pictureGroup(agg, place, rendering, block, picture, flagged, prefix);
+    if (place.depth === 0 && part.list && part.kind === "object") return group(agg, place, part, rendering, block, prefix, message);
+    const rows = place.depth >= 1 && part.list && part.kind === "object";
+    return `${rendering.slot(part, prefix, block[part.name], message, required, rows)}${note}`;
+  });
+  return draw.join("\n");
+}
+
+/** A picture's parts as one group: the key and the alt text and a button that opens the picker. */
+function pictureGroup(agg: Aggregate, place: Place, rendering: Rendering, block: Block, picture: { key: string; alt: string; caption?: string }, flagged: Problem | undefined, prefix: string): string {
+  const find = (name: string): Attr | undefined => place.parts.find((part) => part.name === name);
+  const key = find(picture.key);
+  const alt = find(picture.alt);
+  const caption = picture.caption ? find(picture.caption) : undefined;
+  const control = (part: Attr | undefined): string => (part ? rendering.slot(part, prefix, block[part.name], flagged?.slots.includes(part.name) ? flagged.message : undefined) : "");
+  const pick = rendering.media ? `<button type="button" class="btn btn-sm w-fit" data-action="pick-picture" data-media="${esc(rendering.media)}">${icon("image")}<span>Choose a picture</span></button>` : "";
+  const thumb = `<img class="size-20 shrink-0 border border-base-300 object-cover" alt="" width="80" height="80" data-picture-thumb hidden>`;
+  return `<div class="my-4 grid gap-1 border border-base-300 p-3" data-picture data-key="${esc(prefix + picture.key)}" data-alt="${esc(prefix + picture.alt)}">
+<p class="font-semibold">Picture</p>
+<div class="flex flex-wrap items-start gap-3">${thumb}<div class="grid min-w-0 flex-1 gap-1 max-sm:basis-full">${control(key)}${control(alt)}${control(caption)}${pick}</div></div>
+<p class="text-xs text-muted">A picture needs a description for people who cannot see it.</p>
+</div>`;
+}
+
+/** One card: its head and, in the panel, its slots. `kind` is null for a block with no kind (a repeated part). */
+function card(agg: Aggregate, place: Place, rendering: Rendering, block: Block, kind: string | null): string {
+  const id = `blk-${safe(place.path)}-${place.index}`;
+  const flagged = rendering.problems.find((problem) => problem.name === `${place.path}.${place.index}`);
+  const picture = place.list.pictures?.[place.type];
+  const summary = kind === null && !place.list ? "" : String(summaryOf(place.list, place.parts, block, picture) ?? "");
+  const holds = rendering.problems.some((problem) => problem.name.startsWith(`${place.path}.${place.index}.`));
+  const open = flagged || holds ? "" : " hidden";
+  const attention = flagged ? `<span class="badge badge-soft badge-error shrink-0 gap-1 font-semibold">${icon("alert")}Needs attention</span>` : "";
+  const problem = flagged && flagged.slots.length === 0 ? `<p class="text-sm font-semibold text-error" id="${id}-problem">${esc(flagged.message)}</p>` : "";
+  const describe = flagged && flagged.slots.length === 0 ? ` aria-describedby="${id}-problem"` : "";
+  const number = typeof place.index === "number" ? place.index + 1 : place.index;
+  const kindField = kind === null ? "" : kindInput(agg, place.list, place.parts, `${place.path}.${place.index}.`, kind);
+  const toggle = `<button type="button" class="btn btn-ghost h-auto min-h-11 min-w-0 flex-1 flex-wrap justify-start gap-x-2 gap-y-0 py-2 text-left font-normal" data-action="toggle" aria-expanded="${flagged || holds ? "true" : "false"}" aria-controls="${id}-panel"${describe} hidden>${icon("chevron-right")}<span class="shrink-0 font-semibold" data-card-title>${esc(label(place.noun))} <span data-card-number>${number}</span></span>${badge(kind)}<span class="min-w-0 flex-1 truncate text-muted max-sm:basis-full max-sm:pl-7" data-card-summary>${esc(summary)}</span>${attention}</button>`;
+  const plain = `<span class="flex min-w-0 flex-1 flex-wrap items-center gap-2 py-2" data-card-static><span class="font-semibold">${esc(label(place.noun))} ${number}</span>${badge(kind)}<span class="min-w-0 text-muted">${esc(summary)}</span>${attention}</span>`;
+  const heading = `<h${place.depth + 3} class="m-0 flex min-w-0 flex-1 text-base">${plain}${toggle}</h${place.depth + 3}>`;
+  const valid = `${flagged ? ` data-invalid` : ""}${holds ? ` data-open` : ""}`;
+  const required = kind === null ? (place.declared ? place.parts.filter((part) => !part.optional && !part.list) : []) : [];
+  const requires = kind === null ? required.map((part) => part.name).join(" ") : (place.list.rules?.[kind]?.requires ?? []).join(" ");
+  const needs = requires ? ` data-requires="${esc(requires)}"` : "";
+  const said = picture && place.declared && place.depth === 0 ? ` data-summary-alt="${esc(picture.alt)}"` : "";
+  return `<li class="min-w-0 border border-base-300 bg-base-100" id="${id}" data-card data-index="${place.index}" data-kind="${esc(kind ?? "")}"${needs}${said}${valid}>
+<div class="flex items-center gap-1 pl-2" data-card-head>${heading}${tools(place.noun, number, summary)}</div>
+<div id="${id}-panel" class="border-t border-base-300 px-4 pb-4 [&>*:first-child]:mt-2" data-card-panel>
+${problem}${kindField}
+${slotsOfCard(agg, place, rendering, block, kind, flagged)}
+</div>
+</li>`;
+}
+
+/** The blocks nested one level in a card (buttons, entries): a group of cards with one template. */
+function group(agg: Aggregate, place: Place, part: Attr, rendering: Rendering, block: Block, prefix: string, problem?: string): string {
+  const parts = agg.valueObjects[part.type] ?? [];
+  const noun = singular(part.name.replace(/([^aeiou])ies$/, "$1y").replace(/s$/, ""));
+  const path = `${prefix}${part.name}`;
+  const held = Array.isArray(block[part.name]) ? (block[part.name] as Block[]) : [];
+  const limit = part.max ?? place.list.limits?.[part.name];
+  const pictures = { ...place.list.pictures, ...(part.picture ? { [part.type]: part.picture } : {}) };
+  const nested: BlockList = { discriminator: "", kinds: [], pictures };
+  const inside = (index: number | string, item: Block): string => card(agg, { path, index, depth: 1, noun, type: part.type, list: nested, parts, declared: place.declared }, rendering, item, null);
+  const cards = held.map((item, index) => inside(index, item));
+  const blank = inside(TOKEN[1], {});
+  const max = limit ? ` data-max="${limit}"` : "";
+  const required = place.declared ? !part.optional : place.list.rules?.[kindOf(place.list, block)]?.requires.includes(part.name);
+  const note = limitsNote(part.min, limit);
+  const need = `${required ? "" : ` <span class="ml-1 text-xs font-normal text-muted">optional</span>`}${note ? ` <span class="ml-1 text-xs font-normal text-muted">${esc(note)}</span>` : ""}`;
+  const bad = problem ? ` aria-invalid="true" aria-describedby="blk-${safe(path)}-problem"` : "";
+  const why = problem ? `<p class="clear-both text-sm font-semibold text-error" id="blk-${safe(path)}-problem">${esc(problem)}</p>` : "";
+  return `<fieldset class="mt-6 border-t border-base-300 pt-3" data-group data-path="${esc(path)}" data-noun="${esc(noun)}"${max} data-depth="1"${bad}>
+<legend class="float-left mb-2 w-full text-base font-semibold">${esc(label(part.name))}${need}</legend>
+<ol class="clear-both grid list-none grid-cols-[minmax(0,1fr)] gap-2 p-0" data-cards>
+${cards.join("\n")}
+</ol>
+${why}
+<template data-card-template data-kind="">${blank}</template>
+<button type="button" class="btn btn-ghost btn-sm mt-2" data-action="add" hidden>${icon("plus")}<span>Add ${esc(noun)}</span></button>
+</fieldset>`;
+}
+
+/** What a list of one kind of group is drawn from: a block list that has no kind, its limits and its member's picture. */
+function plainList(attr: Attr): BlockList {
+  return { discriminator: "", kinds: [], pictures: attr.picture ? { [attr.type]: attr.picture } : undefined };
+}
+
+/** The add control and a template for each kind (or the one template, for a list that has no kinds). */
+function adder(agg: Aggregate, attr: Attr, name: string, rendering: Rendering, noun: string): { control: string; templates: string } {
+  const list = attr.blockList ?? plainList(attr);
+  const parts = agg.valueObjects[attr.type] ?? [];
+  const place: Place = { path: name, index: TOKEN[0], depth: 0, noun, type: attr.type, list, parts, declared: !attr.blockList };
+  const button = `<button type="button" class="btn btn-neutral" data-action="add">${icon("plus")}<span>Add ${esc(singular(noun))}</span></button>`;
+  if (!attr.blockList) {
+    return { control: `<div class="mt-4 flex flex-wrap items-end gap-2" data-adder hidden>${button}</div>`, templates: `<template data-card-template data-kind="">${card(agg, place, rendering, {}, null)}</template>` };
+  }
+  const options = list.kinds.map((kind) => `<option value="${esc(kind)}">${esc(label(kind))}</option>`).join("");
+  const id = `blk-${safe(name)}-kind`;
+  const control = `<div class="mt-4 flex flex-wrap items-end gap-2" data-adder hidden>
+<div class="grid gap-1"><label for="${id}" class="font-semibold">Kind of ${esc(singular(noun))} to add</label><select id="${id}" class="select" data-add-kind>${options}</select></div>
+${button}
+</div>`;
+  const templates = list.kinds.map((kind) => `<template data-card-template data-kind="${esc(kind)}">${card(agg, place, rendering, { [list.discriminator]: kindValue(agg, parts, list, kind) }, kind)}</template>`);
+  return { control, templates: templates.join("\n") };
+}
+
+/** A kind as the value the discriminator part holds: wrapped when the part is a one-part value object. */
+function kindValue(agg: Aggregate, parts: Attr[], list: BlockList, kind: string): unknown {
+  const part = parts.find((candidate) => candidate.name === list.discriminator);
+  const inner = part?.kind === "object" ? (agg.valueObjects[part.type] ?? [])[0]?.name : undefined;
+  return inner ? { [inner]: kind } : kind;
+}
+
+/** What the page says at the top of a refused list: how many blocks need attention and where each is. */
+function summaryOfProblems(name: string, noun: string, problems: Problem[], titles: Map<string, string>): string {
+  if (problems.length === 0) return "";
+  const items = problems.map((problem) => {
+    const rest = problem.name.slice(name.length + 1).split(".");
+    const id = `blk-${safe(name)}-${rest[0]}`;
+    const where = rest.length > 2 ? `, ${esc(label(rest[1]))} ${Number(rest[2]) + 1}` : "";
+    return `<li><a href="#${id}">${esc(titles.get(rest[0]) ?? "")}${where}</a>: ${esc(problem.message)}</li>`;
+  });
+  const words = problems.length === 1 ? `1 ${esc(singular(noun))} needs attention` : `${problems.length} ${esc(pluralOf(singular(noun)))} need attention`;
+  return `<div class="alert alert-error alert-soft mb-4 block" role="alert" tabindex="-1" data-block-problems><p class="font-semibold">${words}</p><ul class="mt-1 list-disc pl-5">${items.join("")}</ul></div>`;
+}
+
+/** An attribute that is a list of mixed blocks, or of one kind of group, as its cards, its add control and its templates. */
+export function blockList(agg: Aggregate, attr: Attr, name: string, value: unknown, rendering: Rendering): string {
+  const list = attr.blockList ?? plainList(attr);
+  const parts = agg.valueObjects[attr.type] ?? [];
+  const noun = singular(attr.type);
+  const plural = esc(pluralOf(noun));
+  const held = Array.isArray(value) ? (value as Block[]) : [];
+  const own = rendering.problems.filter((problem) => problem.name.startsWith(`${name}.`));
+  const place = (index: number): Place => ({ path: name, index, depth: 0, noun, type: attr.type, list, parts, declared: !attr.blockList });
+  const cards = held.map((block, index) => card(agg, place(index), rendering, block, kindOf(list, block) || null));
+  const titles = new Map(held.map((block, index) => [String(index), `${label(noun)} ${index + 1}${kindOf(list, block) ? ` (${label(kindOf(list, block))})` : ""}`]));
+  const adding = adder(agg, attr, name, rendering, noun);
+  const max = attr.max ? ` data-max="${attr.max}"` : "";
+  const draft = rendering.draft ? " data-draft" : "";
+  const id = `blk-${safe(name)}`;
+  const limits = limitsNote(attr.min, attr.max);
+  const help = `<p class="clear-both mb-3 text-sm text-muted" id="${id}-help">Open a ${esc(singular(noun))} to edit it. Move buttons change the order and Remove asks first. ${limits} Without scripts every ${esc(singular(noun))} stays open and cannot be added, moved or removed.</p>`;
+  const invalid = rendering.message ? ` aria-invalid="true"` : "";
+  const said = rendering.message ? `<p class="clear-both mb-3 text-sm font-semibold text-error" id="${id}-error">${esc(rendering.message)}</p>` : "";
+  const described = rendering.message ? `${id}-help ${id}-error` : `${id}-help`;
+  return `<fieldset class="mt-6 [&>legend+*]:clear-both" id="${id}" data-block-list data-group data-path="${esc(name)}" data-noun="${esc(noun)}" data-depth="0"${max}${draft}${invalid} aria-describedby="${described}">
+<legend class="float-left mb-2 w-full border-t border-base-300 pt-4 text-lg font-semibold">${rendering.caption} <span class="text-sm font-normal text-muted" data-count>(${held.length})</span></legend>
+${help}
+${said}
+${summaryOfProblems(name, noun, own, titles)}
+<ol class="grid list-none grid-cols-[minmax(0,1fr)] gap-3 p-0" data-cards>
+${cards.join("\n")}
+</ol>
+<p class="mt-2 text-sm text-muted" data-empty${held.length > 0 ? " hidden" : ""}>No ${plural} yet.</p>
+${adding.control}
+<p class="sr-only" role="status" aria-live="polite" data-block-say></p>
+${adding.templates}
+<dialog class="modal" id="${id}-remove" aria-labelledby="${id}-remove-title" data-remove-dialog>
+<div class="modal-box"><h2 id="${id}-remove-title" class="text-xl" data-remove-title>Remove ${esc(singular(noun))}?</h2>
+<p class="mt-2 text-muted">It is taken out of the list when the list is saved.</p>
+<div class="modal-action"><button type="button" class="btn btn-ghost" data-action="remove-cancel">Keep it</button><button type="button" class="btn btn-error" data-action="remove-confirm">Remove</button></div></div>
+</dialog>
+</fieldset>`;
+}
+
+export { filled, lacking };

data/lib/hecks/projections/site/cms_editor/templates/src/ui/body_model.js.tmpl

@@ -0,0 +1,123 @@
+__BANNER__
+
+// The structured document body (`blocks` of `spans` and `items`) as read-only HTML and as form
+// fields. Plain JavaScript with no dependencies, so the same file runs in node (the pages) and in
+// the browser (the widget). The domain's own tree is the only format: nothing here is an editor
+// format, and every text, address and attribute value is escaped on its way into markup.
+
+export const KINDS = ["paragraph", "heading", "quote", "bullet_list", "numbered_list", "image", "divider"];
+export const ALIGNS = ["left", "center", "right", "justify"];
+export const MARKS = ["bold", "italic", "underline", "strike", "code"];
+export const TAGS = { bold: "strong", italic: "em", underline: "u", strike: "s", code: "code" };
+export const MAX_INDENT = 8;
+export const MAX_DEPTH = 5;
+
+/** The body of a document with nothing in it. */
+export const emptyBody = () => ({ blocks: [] });
+
+/** Escapes text for an HTML body or a double-quoted attribute. */
+export function esc(value) {
+  return String(value ?? "").replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+}
+
+/**
+ * The address when it is one a link may carry: a path (not `//`), http://, https://, mailto: or
+ * tel:, with no whitespace or control characters; otherwise null.
+ */
+export function safeHref(value) {
+  const text = String(value ?? "");
+  if (text === "" || /[\u0000- \u007f-\u009f\\]/.test(text)) return null;
+  return /^(\/(?!\/)|https?:\/\/|mailto:|tel:)/i.test(text) ? text : null;
+}
+
+const markName = (mark) => (typeof mark === "string" ? mark : mark?.name);
+const whole = (value, low, high) => (Number.isInteger(Number(value)) && value !== "" && value !== null ? Math.min(high, Math.max(low, Number(value))) : null);
+const list = (value) => (Array.isArray(value) ? value : []);
+
+function wrap(span, inner) {
+  const names = list(span.marks).map(markName).filter((name) => MARKS.includes(name));
+  const marked = [...names].reverse().reduce((html, name) => `<${TAGS[name]}>${html}</${TAGS[name]}>`, inner);
+  const href = safeHref(span.href);
+  return href ? `<a href="${esc(href)}" rel="noopener noreferrer">${marked}</a>` : marked;
+}
+
+/** The spans as inline HTML; a span of "\n" is a line break. */
+export function spansToHtml(spans) {
+  return list(spans)
+    .map((span) => String(span?.text ?? "").split("\n").map((part, at) => wrap(span, (at > 0 ? "<br>" : "") + esc(part))).join(""))
+    .join("");
+}
+
+const attrs = (pairs) => pairs.filter(([, value]) => value !== null && value !== undefined).map(([name, value]) => ` ${name}="${esc(value)}"`).join("");
+
+function layout(block) {
+  const align = ALIGNS.includes(block.align) ? block.align : null;
+  return attrs([["data-align", align], ["data-indent", whole(block.indent, 0, MAX_INDENT)]]);
+}
+
+function itemHtml(item) {
+  const kind = KINDS.slice(3, 5).includes(item?.list_kind) ? item.list_kind : null;
+  const depth = whole(item?.depth, 0, MAX_DEPTH);
+  return `<li${attrs([["data-depth", depth], ["data-list-kind", kind]])}>${spansToHtml(item?.spans)}</li>`;
+}
+
+function imageHtml(block) {
+  const note = `<span class="body-media">image <code>${esc(block.media_ref ?? "")}</code>${block.alt ? ` ${esc(block.alt)}` : ""}</span>`;
+  const caption = block.caption ? `<figcaption>${esc(block.caption)}</figcaption>` : "";
+  return `<figure${attrs([["data-media-ref", block.media_ref ?? ""], ["data-alt", block.alt], ["data-caption", block.caption]])}>${note}${caption}</figure>`;
+}
+
+/**
+ * One block as HTML. An unknown kind is shown as a paragraph. `demote` moves a heading down that
+ * many levels (to at most 6), for a body shown inside a page that has its own headings above it.
+ */
+export function blockToHtml(block, demote = 0) {
+  const kind = block?.kind;
+  if (kind === "divider") return "<hr>";
+  if (kind === "image") return imageHtml(block);
+  if (kind === "bullet_list" || kind === "numbered_list") {
+    const tag = kind === "bullet_list" ? "ul" : "ol";
+    return `<${tag}${layout(block)}>${list(block.items).map(itemHtml).join("")}</${tag}>`;
+  }
+  const level = Math.min(6, (whole(block?.level, 1, 4) ?? 2) + demote);
+  const tag = kind === "heading" ? `h${level}` : kind === "quote" ? "blockquote" : "p";
+  return `<${tag}${layout(block ?? {})}>${spansToHtml(block?.spans)}</${tag}>`;
+}
+
+/** The body as HTML, one block after another; the same body gives the same text. */
+export function bodyToHtml(body, demote = 0) {
+  return list(body?.blocks).map((block) => blockToHtml(block, demote)).join("\n");
+}
+
+const present = (value) => value !== undefined && value !== null && value !== "";
+
+function spanFields(span, name) {
+  const marks = list(span.marks).map(markName).filter(present).map((mark, at) => [`${name}.marks.${at}.name`, mark]);
+  return [[`${name}.text`, span.text ?? ""], ...marks, ...(present(span.href) ? [[`${name}.href`, span.href]] : [])];
+}
+
+function itemFields(item, name) {
+  const spans = list(item.spans).flatMap((span, at) => spanFields(span, `${name}.spans.${at}`));
+  return [...spans, ...(present(item.depth) ? [[`${name}.depth`, item.depth]] : []), ...(present(item.list_kind) ? [[`${name}.list_kind`, item.list_kind]] : [])];
+}
+
+function blockFields(block, name) {
+  const spans = list(block.spans).flatMap((span, at) => spanFields(span, `${name}.spans.${at}`));
+  const items = list(block.items).flatMap((item, at) => itemFields(item, `${name}.items.${at}`));
+  const scalars = ["level", "align", "indent", "media_ref", "alt", "caption"].filter((key) => present(block[key])).map((key) => [`${name}.${key}`, block[key]]);
+  return [[`${name}.kind`, block.kind], ...scalars, ...spans, ...items];
+}
+
+/**
+ * The body as the form's own fields: `[name, value]` pairs named by dotted path under `name`
+ * (`body.blocks.0.spans.1.marks.0.name`), the encoding the editor's other value objects and lists
+ * use, which the server reads back into the tree the command takes.
+ */
+export function bodyToFields(body, name) {
+  return list(body?.blocks).flatMap((block, at) => blockFields(block, `${name}.blocks.${at}`));
+}
+
+/** The fields as hidden inputs. */
+export function fieldsToInputs(pairs) {
+  return pairs.map(([name, value]) => `<input type="hidden" name="${esc(name)}" value="${esc(value)}">`).join("\n");
+}