@openpresentation/opf-editor 0.26.3 → 0.26.5

package/dist/source-ranges.js

@@ -14,15 +14,18 @@ export function lineColumn(text, offset) {
 }
 
 /**
- * The range of `segments` in the JSON `text`, or null (core's `locate`, which reads text that does not parse). `part`: "value" (default), "key" (the
- * property name), "entry" (key to the end of the value), "colon" (the key and its colon) or "open" (the first character of the value, the `{` of an
- * object). A path that is not there gives the range of its nearest container, with `exact: false`.
+ * The range of `segments` in `text` of `format` ("json", "yaml" or "md"), or null (core's `locate`, which reads text that does not parse). `part`:
+ * "value" (default), "key" (the property name), "entry" (key to the end of the value), "colon" (the key and its colon) or "open" (the first character
+ * of the value, the `{` of an object). A path that is not there gives the range of its nearest container, with `exact: false`.
  */
-export function locateJson(text, segments, part = "value") {
-  const range = locate(text, "json", segments.map(String), { part });
+export function locateText(format, text, segments, part = "value") {
+  const range = locate(text, format, segments.map(String), { part });
   return range ? { from: range.offset, to: range.offset + range.length, exact: range.exact !== false } : null;
 }
 
+/** `locateText` for JSON. */
+export const locateJson = (text, segments, part = "value") => locateText("json", text, segments, part);
+
 /** The part of the text a finding is about, by what it says (VALIDATOR-HINTS section 4). */
 export function partOf(finding) {
   const keyword = finding.validation?.keyword;

package/dist/source-references.js

@@ -0,0 +1,227 @@
+// Cross-references inside the document as completion values (artifacts/source-editor/SPEC.md, section 3.4): `asset:<id>` from `assets`, dataset ids
+// and column names from `datasets`, `var:<id>` and `{{name}}` from `variables`, `cite` ids from `references`, `beat` ids from the deck's narrative and
+// `region` names from the slide's layout. Which field takes which kind of reference is ONE table (`REFERENCE_RULES`) read against the schema: a rule
+// names the schema definitions whose fields are references (`Asset`, `DatasetId`, ...) and the property names, with a phrase the property's own
+// description must carry (any of `phrases`), for the fields written inline in their parent. test/source-completions-units.mjs checks every entry against the schema,
+// so a renamed definition or a reworded description fails the test instead of silently dropping a list. Plain functions, no DOM.
+import { parse as parseYaml } from "yaml";
+import { describeField } from "@openpresentation/opf/schema";
+
+/**
+ * The rules. `definitions`: a field whose own schema is that definition (`$defs` name). `keys` + `phrases`: a string field with one of those property
+ * names whose description contains one of the phrases. `item`: the field is a list (or a string or a list) and every entry is a reference.
+ */
+export const REFERENCE_RULES = Object.freeze([
+  { kind: "asset", definitions: ["Asset", "LogoSource", "ImageSource"], keys: ["src", "logo", "watermark"], phrases: ["asset:<id>", "or Asset"] },
+  { kind: "dataset", definitions: ["DatasetId"], keys: [], phrases: [] },
+  { kind: "datasetColumn", definitions: ["DatasetFields"], keys: ["category", "x", "series", "line", "secondaryAxis"], phrases: ["column"], item: true },
+  { kind: "cite", definitions: [], keys: ["cite"], phrases: ["references"], item: true },
+  { kind: "beat", definitions: [], keys: ["beat"], phrases: ["narrative"], item: true },
+  { kind: "region", definitions: [], keys: ["region"], phrases: ["template layout"] },
+  { kind: "color", definitions: ["ColorRef"], keys: ["color"], phrases: ["var:<id>"] },
+]);
+
+/** The promoted regions of a slide a block can be pinned to (the lower-case names the `region` pattern accepts). */
+export const PROMOTED_REGIONS = Object.freeze(["top", "middle", "bottom", "left", "center", "right"]);
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isIndex = (segment) => typeof segment === "number" || /^(?:0|[1-9]\d*)$/.test(String(segment));
+
+function ruleOf(info, key) {
+  if (!info?.known || !(info.types.includes("string") || info.types.includes("array"))) return null;
+  for (const rule of REFERENCE_RULES) {
+    if (info.definition && rule.definitions.includes(info.definition)) return rule;
+    if (key !== undefined && rule.keys.includes(key) && rule.phrases.some((phrase) => (info.fullDescription ?? info.description ?? "").includes(phrase))) return rule;
+  }
+  return null;
+}
+
+/**
+ * What the value at `path` of `document` references: `{ kind, path }` (`path` is the field, for a list entry the list's), or null. A list entry
+ * (`cite: ["a", |]`, `fields: [|]`) is the entry of the list field the rule names; a field that can only be a list takes its references one by one.
+ */
+export function referenceSiteAt(path, document) {
+  if (!Array.isArray(path) || !path.length) return null;
+  const last = path.at(-1);
+  const describe = (at) => { try { return describeField(at, document); } catch { return null; } };
+  if (!isIndex(last)) {
+    const info = describe(path);
+    const rule = ruleOf(info, String(last));
+    const listOnly = info?.types.length === 1 && info.types[0] === "array";
+    return rule && !listOnly ? { kind: rule.kind, path } : null;
+  }
+  // An entry whose own schema is a reference definition (`chart.colors[i]`: a ColorRef) is a reference whatever the list is called.
+  const own = describe(path);
+  const byDefinition = own?.known && own.definition ? REFERENCE_RULES.find((rule) => rule.definitions.includes(own.definition)) : undefined;
+  if (byDefinition && !own.types.every((type) => type === "array")) return { kind: byDefinition.kind, path };
+  const field = path.slice(0, -1);
+  while (field.length && isIndex(field.at(-1))) field.pop();
+  if (!field.length) return null;
+  const rule = ruleOf(describe(field), String(field.at(-1)));
+  return rule?.item ? { kind: rule.kind, path: field } : null;
+}
+
+// ---- the facts of a document -------------------------------------------------------------------------------------------------------
+const stringOf = (value) => (typeof value === "string" ? value : undefined);
+const columnName = (column) => (typeof column === "string" ? column : isObject(column) && typeof column.name === "string" ? column.name : undefined);
+
+/**
+ * The parts of a deck the references read, from the plain value of the top level (`assets`, `datasets`, `variables`, `references`, `narrative`):
+ * `{ assets: [{ id, detail }], datasets: [{ id, title, columns }], variables: [{ id, type }], references: [{ id, text }], narrative }`.
+ * Anything else the value holds, and anything malformed, is ignored: the text being edited is a draft.
+ */
+export function factsOf(deck) {
+  const out = { assets: [], datasets: [], variables: [], references: [], narrative: undefined };
+  if (!isObject(deck)) return out;
+  if (isObject(deck.assets)) {
+    for (const [id, asset] of Object.entries(deck.assets)) out.assets.push({ id, detail: stringOf(asset) ?? stringOf(asset?.src) ?? stringOf(asset?.title) ?? "" });
+  }
+  if (isObject(deck.datasets)) {
+    for (const [id, dataset] of Object.entries(deck.datasets)) {
+      const columns = Array.isArray(dataset?.columns) ? dataset.columns.map(columnName).filter(Boolean) : [];
+      out.datasets.push({ id, title: stringOf(dataset?.title) ?? "", columns });
+    }
+  }
+  if (isObject(deck.variables)) {
+    for (const [id, variable] of Object.entries(deck.variables)) {
+      // A hex string is shorthand for a color variable.
+      const type = typeof variable === "string" ? "color" : stringOf(variable?.type) ?? "color";
+      out.variables.push({ id, type });
+    }
+  }
+  if (Array.isArray(deck.references)) {
+    for (const reference of deck.references) if (isObject(reference) && typeof reference.id === "string" && reference.id) out.references.push({ id: reference.id, text: stringOf(reference.text) ?? "" });
+  }
+  out.narrative = stringOf(deck.narrative);
+  return out;
+}
+
+/** The top-level parts of a JSON draft the references read (`root` is a jsonc-parser tree), as a plain value for `factsOf`. */
+export function jsonDeckParts(root, getNodeValue) {
+  const deck = {};
+  if (root?.type !== "object") return deck;
+  for (const property of root.children ?? []) {
+    const key = property.children?.[0]?.value, value = property.children?.[1];
+    if (!value || !["assets", "datasets", "variables", "references", "narrative"].includes(key)) continue;
+    if (key === "datasets" && value.type === "object") {
+      // Only the names and the columns: the rows can be the bulk of a deck.
+      deck.datasets = {};
+      for (const entry of value.children ?? []) {
+        const id = entry.children?.[0]?.value, body = entry.children?.[1];
+        if (typeof id !== "string" || body?.type !== "object") continue;
+        const columns = (body.children ?? []).find((child) => child.children?.[0]?.value === "columns")?.children?.[1];
+        const title = (body.children ?? []).find((child) => child.children?.[0]?.value === "title")?.children?.[1];
+        deck.datasets[id] = { columns: columns ? getNodeValue(columns) : [], title: title?.type === "string" ? title.value : undefined };
+      }
+    } else deck[key] = getNodeValue(value);
+  }
+  return deck;
+}
+
+const TOP_LEVEL = ["assets", "datasets", "variables", "references", "narrative"];
+
+/** The text of the top-level blocks of a YAML text that hold the keys the references read, parsed (tolerant: a broken block gives nothing). */
+export function yamlDeckParts(text) {
+  const lines = text.split(/\r\n|\r|\n/);
+  const deck = {};
+  for (let number = 0; number < lines.length; number++) {
+    const match = /^([A-Za-z]+)\s*:/.exec(lines[number]);
+    if (!match || !TOP_LEVEL.includes(match[1])) continue;
+    let end = number + 1;
+    while (end < lines.length && (lines[end].trim() === "" || /^[ \t]/.test(lines[end]) || lines[end].startsWith("- "))) end++;
+    try {
+      const value = parseYaml(lines.slice(number, end).join("\n"), { strict: false, uniqueKeys: false });
+      if (isObject(value) && match[1] in value) deck[match[1]] = value[match[1]];
+    } catch { /* A block that does not parse offers nothing. */ }
+  }
+  return deck;
+}
+
+/** `value` at `path` of a plain document, or undefined. */
+export function valueAt(value, path) {
+  let current = value;
+  for (const step of path) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = current[step];
+  }
+  return current;
+}
+
+/**
+ * What a column field reads its names from: `{ dataset }` (the id of the dataset: a `dataset` beside the field, or the chart's `data.dataset`) or
+ * `{ inline }` (the `columns` of the chart's own `data`), looking outward from the field; null when the draft says neither. `read(path)` gives a
+ * value of the document.
+ */
+export function columnSourceFor(site, read) {
+  for (let depth = site.path.length - 1; depth >= 0; depth--) {
+    const owner = site.path.slice(0, depth);
+    const direct = read([...owner, "dataset"]);
+    if (typeof direct === "string") return { dataset: direct };
+    const via = read([...owner, "data", "dataset"]);
+    if (typeof via === "string") return { dataset: via };
+    const inline = read([...owner, "data", "columns"]);
+    if (Array.isArray(inline)) return { inline: inline.map(columnName).filter(Boolean) };
+  }
+  return null;
+}
+
+/** The names of the regions of a layout record a block can be pinned to (the title and the subtitle are not regions of the body). */
+export function regionNames(record) {
+  const names = [];
+  const walk = (regions) => {
+    for (const region of Array.isArray(regions) ? regions : []) {
+      if (typeof region?.name === "string" && region.name !== "title" && region.name !== "subtitle") names.push(region.name);
+      if (region?.regions) walk(region.regions);
+    }
+  };
+  walk(record?.regions);
+  return names;
+}
+
+/** The regions of a layout record in reading order (nested ones included) as `{ name, accepts }`. */
+export function flatRegions(record) {
+  const out = [];
+  const walk = (regions) => {
+    for (const region of Array.isArray(regions) ? regions : []) {
+      if (typeof region?.name === "string") out.push({ name: region.name, accepts: Array.isArray(region.accepts) ? region.accepts : [] });
+      if (region?.regions) walk(region.regions);
+    }
+  };
+  walk(record?.regions);
+  return out;
+}
+
+// The slide key that holds content of a kind a region accepts.
+const PAYLOAD_KEYS = { text: "text", list: "items", image: "image", video: "video", chart: "chart", table: "table", quote: "quote", code: "code", metric: "metric", timeline: "timeline" };
+
+/**
+ * The slide keys a layout's regions call for, in region order: a region named like a slide key (`title`, `items`) calls for that key; any other region
+ * that accepts one or two kinds of content (`media`: image, video) for the keys of those kinds. `keys` are the slide keys that exist.
+ */
+export function layoutKeys(record, keys) {
+  const wanted = [];
+  const add = (key) => { if (keys.includes(key) && !wanted.includes(key)) wanted.push(key); };
+  for (const region of flatRegions(record)) {
+    if (keys.includes(region.name)) add(region.name);
+    else if (region.accepts.length > 0 && region.accepts.length <= 2) for (const kind of region.accepts) add(PAYLOAD_KEYS[kind]);
+  }
+  return wanted;
+}
+
+/** The ids of the beats of a narrative record. */
+export function beatsOf(record) {
+  return (Array.isArray(record?.beats) ? record.beats : []).filter((beat) => isObject(beat) && typeof beat.id === "string").map((beat) => ({ id: beat.id, name: stringOf(beat.name) ?? "", description: stringOf(beat.description) ?? "" }));
+}
+
+/**
+ * The names of the variables a `{{` in text can reference: the document's own, with their type. (The built-in `organization.*`, `speaker.*` and
+ * `deck.*` variables are not offered: they are not declared in the document.)
+ */
+export function variableNames(facts) {
+  return facts.variables.map((variable) => ({ id: variable.id, type: variable.type }));
+}
+
+/** The slide a path of a deck sits in: `["slides", n]`, or null. */
+export function slidePath(path) {
+  return path[0] === "slides" && isIndex(path[1]) ? [path[0], Number(path[1])] : null;
+}

package/dist/source-snippets.js

@@ -2,6 +2,8 @@
 // OPF fragment with numbered placeholders and rendered per format (JSON here; YAML and Markdown follow in phase 2), then handed to CodeMirror's
 // snippet engine, which walks the tab stops. Plain functions, no DOM.
 
+import { Document as YamlDocument } from "yaml";
+
 const PLACEHOLDER = Symbol("opf-placeholder");
 
 /**
@@ -70,6 +72,20 @@ export const SNIPPETS = Object.freeze([
   { prefix: "reference", where: "reference", description: "A reference a slide can cite", fragment: { id: ph(1, "smith2020"), text: ph(2, "Citation") } },
   { prefix: "dataset", where: "dataset", description: "A table of data that charts and tables can share", name: ph(1, "sales"), fragment: { columns: [ph(2, "Category"), ph(3, "Value")], rows: [[ph(4, "A"), ph(5, "1", { raw: true })]] } },
   { prefix: "deck", where: "deck", description: "A starter deck", fragment: { name: ph(1, "Deck name"), slides: [{ title: ph(2, "Title") }] } },
+  // Speaker notes in Markdown: a `Note:` line (JSON and YAML have the `notes` property for it).
+  { prefix: "notes", where: "markdown", key: "notes", description: "Speaker notes for the slide", fragment: ph(1, "Speaker notes") },
+]);
+
+/**
+ * Snippets a KEY of the deck is accepted as (SPEC 5: `design`, `organization`, `speaker`): not items of the list on their own (`SNIPPETS` holds
+ * those), but what accepting the property writes, as VS Code does for a property with default snippets. The fragment is the value of the key. They hold
+ * the required members of the object, each a tab stop (SPEC 5 lists only `name` for the speaker; the Speaker schema requires an id too), and `design`
+ * opens the list of the catalog at each stop.
+ */
+export const KEY_SNIPPETS = Object.freeze([
+  { prefix: "design", where: "deck-key", key: "design", description: "The design of the deck: a theme, a color scheme and a font scheme", fragment: { theme: ph(1, "", { choice: true }), colorScheme: ph(2, "", { choice: true }), fontScheme: ph(3, "", { choice: true }) } },
+  { prefix: "organization", where: "deck-key", key: "organization", description: "The organization presenting the deck: an id and a name", fragment: { id: ph(1, "acme"), name: ph(2, "Acme Inc.") } },
+  { prefix: "speaker", where: "deck-key", key: "speaker", description: "The person presenting the deck: an id and a name", fragment: { id: ph(1, "alice"), name: ph(2, "Name") } },
 ]);
 
 /** The snippets that fit where the caret is: `where` and the path of the node (see source-json.js). */
@@ -84,10 +100,153 @@ export function snippetsFor(mode, path) {
   });
 }
 
+/**
+ * The snippets a key of the object at `path` is accepted as (the deck's `design`, `organization`, `speaker`): not items of their own in the list,
+ * but what accepting that property writes, as VS Code does for a property with default snippets.
+ */
+export function keySnippetsFor(path) {
+  return path.length === 0 ? KEY_SNIPPETS : [];
+}
+
 /** The JSON text of a snippet for insertion: `{ text, fields }`; a dataset is a `"name": { ... }` entry. */
 export function snippetJson(snippet, { comma = false } = {}) {
+  if (snippet.key !== undefined) {
+    const body = renderJson(snippet.fragment, { comma });
+    return { text: `${JSON.stringify(snippet.key)}: ${body.text}`, fields: body.fields };
+  }
   if (snippet.where !== "dataset") return renderJson(snippet.fragment, { comma });
   const body = renderJson(snippet.fragment, { comma });
   const key = `"${field(snippet.name)}"`;
   return { text: `${key}: ${body.text}`, fields: [{ index: snippet.name.index, text: snippet.name.text }, ...body.fields].sort((a, b) => a.index - b.index) };
 }
+
+// ---- YAML ------------------------------------------------------------------------------------------------------------------------------
+const yamlText = (text) => {
+  try { return new YamlDocument(text).toString({ lineWidth: 0 }).trimEnd(); } catch { return JSON.stringify(text); }
+};
+// A placeholder as YAML: its text between the markers, quoted when plain YAML would read it as another type or as syntax (`42`, `a: b`).
+function yamlField(placeholder) {
+  const marker = (text) => `\${${placeholder.index}${text ? `:${escapeText(text)}` : ""}}`;
+  const text = placeholder.text || (placeholder.choice ? (placeholder.value ?? "") : "");
+  if (placeholder.raw || !text) return marker(text);
+  return yamlText(text) === text ? marker(text) : `"${marker(JSON.stringify(text).slice(1, -1))}"`;
+}
+
+/** The lines of a mapping as `[{ depth, text }]` (block style; lists of lists and `columns` in flow style), recording placeholders in `fields`. */
+function yamlLines(mapping, depth, fields) {
+  const scalar = (value) => {
+    if (isPlaceholder(value)) {
+      fields.push({ index: value.index, text: value.text || (value.choice ? (value.value ?? "") : ""), ...(value.choice ? { choice: true } : {}) });
+      return yamlField(value);
+    }
+    if (value === null) return "null";
+    return typeof value === "string" ? yamlText(value) : String(value);
+  };
+  const flow = (value) => (Array.isArray(value) ? `[${value.map(flow).join(", ")}]` : scalar(value));
+  const isCollection = (value) => value !== null && typeof value === "object" && !isPlaceholder(value);
+  const lines = [];
+  for (const [key, item] of Object.entries(mapping)) {
+    if (!isCollection(item)) { lines.push({ depth, text: `${key}: ${scalar(item)}` }); continue; }
+    if (Array.isArray(item)) {
+      if (!item.length) { lines.push({ depth, text: `${key}: []` }); continue; }
+      if (key === "columns") { lines.push({ depth, text: `${key}: ${flow(item)}` }); continue; }
+      lines.push({ depth, text: `${key}:` });
+      for (const entry of item) {
+        if (Array.isArray(entry)) lines.push({ depth: depth + 1, text: `- ${flow(entry)}` });
+        else if (isCollection(entry)) {
+          const inner = yamlLines(entry, depth + 2, fields);
+          if (inner.length) inner[0] = { depth: depth + 1, text: `- ${inner[0].text}` };
+          lines.push(...inner);
+        } else lines.push({ depth: depth + 1, text: `- ${scalar(entry)}` });
+      }
+      continue;
+    }
+    if (!Object.keys(item).length) { lines.push({ depth, text: `${key}: {}` }); continue; }
+    lines.push({ depth, text: `${key}:` }, ...yamlLines(item, depth + 1, fields));
+  }
+  return lines;
+}
+
+/**
+ * `{ text, fields }`: a fragment as block-style YAML with CodeMirror snippet markers. The first line starts where the caret is (after a dash or
+ * at a key position); the others are indented relative to the line the caret is on, and `dash` more columns when the caret follows a list dash.
+ * `entry` writes the fragment as the value of that key; `name` (a placeholder) writes it under a key the author names.
+ */
+export function renderYaml(fragment, { dash = 0, entry, name } = {}) {
+  const fields = [];
+  let lines;
+  if (name !== undefined) {
+    fields.push({ index: name.index, text: name.text });
+    lines = [{ depth: 0, text: `${yamlField(name)}:` }, ...yamlLines(fragment, 1, fields)];
+  } else if (entry !== undefined) lines = yamlLines({ [entry]: fragment }, 0, fields);
+  else lines = yamlLines(fragment, 0, fields);
+  const pad = " ".repeat(dash);
+  const text = lines.map((line, index) => (index === 0 ? line.text : `${pad}${"  ".repeat(line.depth)}${line.text}`)).join("\n");
+  return { text: `${text}\${0}`, fields: fields.sort((a, b) => a.index - b.index) };
+}
+
+/** The YAML text of a snippet for insertion: `{ text, fields }`. `dash` is the width of the list dash the caret follows (2), else 0. */
+export function snippetYaml(snippet, { dash = 0 } = {}) {
+  if (snippet.key !== undefined) return renderYaml(snippet.fragment, { dash, entry: snippet.key });
+  if (snippet.where === "dataset") return renderYaml(snippet.fragment, { dash, name: snippet.name });
+  return renderYaml(snippet.fragment, { dash });
+}
+
+// ---- Markdown --------------------------------------------------------------------------------------------------------------------------
+// A placeholder as Markdown text: the marker with its text (a choice starts with its default, `column`).
+function mdField(placeholder, fields) {
+  const text = placeholder.text || (placeholder.choice ? (placeholder.value ?? "") : "");
+  fields.push({ index: placeholder.index, text, ...(placeholder.choice ? { choice: true } : {}) });
+  return `\${${placeholder.index}${text ? `:${escapeText(text)}` : ""}}`;
+}
+
+const SLIDE_OPTION_FIELDS = ["id", "type", "layout", "section", "tag"];
+
+/**
+ * `{ text, fields }`: a slide fragment as the Markdown dialect writes it (options comment, `#` title, blocks, `Note:`), with CodeMirror snippet
+ * markers. `separator` puts `---` and a blank line first (a slide after another). A `notes` snippet is one `Note:` line. The shape follows
+ * core's writer, so the result reads back as the slide the fragment describes.
+ */
+export function renderMarkdown(fragment, { separator = false, entry } = {}) {
+  const fields = [];
+  const value = (item) => (isPlaceholder(item) ? mdField(item, fields) : item === null || item === undefined ? "" : String(item));
+  if (entry === "notes") return { text: `Note: ${value(fragment)}\${0}`, fields };
+  const blocks = [];
+  const options = [];
+  for (const key of SLIDE_OPTION_FIELDS) if (typeof fragment[key] === "string" || isPlaceholder(fragment[key])) options.push(`${key}=${value(fragment[key])}`);
+  // The options comment sits directly above what follows it, as core writes it.
+  const lead = options.length ? `<!-- slide: ${options.join(" ")} -->` : "";
+  if (fragment.title !== undefined) blocks.push(`${lead ? `${lead}\n` : ""}# ${value(fragment.title)}`);
+  else if (lead) blocks.push(lead);
+  if (fragment.subtitle !== undefined) blocks.push(`## ${value(fragment.subtitle)}`);
+  const bullets = (items) => items.map((item) => `- ${value(item)}`).join("\n");
+  const csv = (rows) => rows.map((row) => row.map((cell) => value(cell)).join(",")).join("\n");
+  if (fragment.text !== undefined) blocks.push(value(fragment.text));
+  if (Array.isArray(fragment.items)) blocks.push(bullets(fragment.items));
+  for (const region of ["left", "right"]) {
+    if (fragment[region]) blocks.push(`<!-- block: region=${region} -->\n${bullets(fragment[region].items ?? [])}`);
+  }
+  if (fragment.image) blocks.push(`![${value(fragment.image.alt)}](${value(fragment.image.src)})`);
+  if (fragment.chart) blocks.push(`\`\`\`chart ${value(fragment.chart.type)}\n${csv([fragment.chart.data.columns, ...fragment.chart.data.rows])}\n\`\`\``);
+  if (fragment.quote) blocks.push(`> ${value(fragment.quote.text)}${fragment.quote.attribution === undefined ? "" : `\n> — ${value(fragment.quote.attribution)}`}`);
+  if (fragment.metric) blocks.push(`\`\`\`metric\nvalue: ${value(fragment.metric.value)}\nlabel: ${value(fragment.metric.label)}\n\`\`\``);
+  if (fragment.table) {
+    const row = (cells) => `| ${cells.map((cell) => value(cell)).join(" | ")} |`;
+    blocks.push([row(fragment.table.columns), row(fragment.table.columns.map(() => "---")), ...fragment.table.rows.map(row)].join("\n"));
+  }
+  if (fragment.code) blocks.push(`\`\`\`${value(fragment.code.language)}\n${value(fragment.code.source)}\n\`\`\``);
+  if (fragment.notes !== undefined) blocks.push(`Note: ${value(fragment.notes)}`);
+  const body = blocks.join("\n\n");
+  return { text: `${separator ? "---\n\n" : ""}${body}\${0}`, fields: fields.sort((a, b) => a.index - b.index) };
+}
+
+/** The Markdown text of a snippet for insertion at the start of a line: `{ text, fields }`. `separator`: a slide follows another. */
+export function snippetMarkdown(snippet, { separator = false } = {}) {
+  if (snippet.key !== undefined) return renderMarkdown(snippet.fragment, { entry: snippet.key });
+  return renderMarkdown(snippet.fragment, { separator });
+}
+
+/** The snippets of the Markdown body: a slide of each kind and the speaker notes. */
+export function snippetsForMarkdown() {
+  return SNIPPETS.filter((snippet) => snippet.where === "slide" || snippet.where === "markdown");
+}

package/dist/source-undo-groups.js

@@ -0,0 +1,46 @@
+// One undo step for a suggestion and the value list it opened (artifacts/source-editor/SPEC.md, section 4.6, item 4; TEST-PLAN J-INS-017). Accepting a key
+// of a closed set of values writes `"key": ""` and opens the list of the values; accepting a value is a second edit. Each is an edit of its own in
+// CodeMirror's history, as every accepted suggestion is, so the pair is recorded here and Undo and Redo step over both: one Cmd+Z puts back the text
+// the author had typed before accepting the key (VS Code: "accept is one step with its typed prefix undoable"). Anything typed in between, or any
+// other edit after the pair, makes the pair void, so Undo is the plain one again. Plain functions over an editor view, no DOM.
+import { redo, undo, undoDepth, redoDepth } from "@codemirror/commands";
+
+const pending = new WeakMap();
+const pairs = new WeakMap();
+
+/** A suggestion that opens a list of values was accepted: the text before it and after it. */
+export function beginUndoGroup(view, before) {
+  pending.set(view, { before, after: view.state.doc });
+}
+
+/** A suggestion is about to be accepted: the pair it completes (the key accepted just before, with nothing typed since), or null. */
+export function takeUndoGroup(view) {
+  const link = pending.get(view);
+  pending.delete(view);
+  pairs.delete(view);
+  return link && link.after.eq(view.state.doc) ? link : null;
+}
+
+/** The value was accepted (and the history closed after it): the key and the value are one undo step from now on. */
+export function finishUndoGroup(view, link) {
+  pairs.set(view, { before: link.before, after: view.state.doc, depth: undoDepth(view.state), undone: false });
+}
+
+/** Whether Undo should step over the last pair; does it when so (returns true). Otherwise the caller does the plain undo. */
+export function undoPair(view) {
+  const pair = pairs.get(view);
+  if (!pair || pair.undone || undoDepth(view.state) !== pair.depth || !view.state.doc.eq(pair.after)) return false;
+  for (let step = 0; step < 3 && !view.state.doc.eq(pair.before); step++) if (!undo(view)) break;
+  pair.undone = view.state.doc.eq(pair.before);
+  pair.redoDepth = redoDepth(view.state);
+  return true;
+}
+
+/** The same for Redo: after the pair was undone, Redo puts both back. */
+export function redoPair(view) {
+  const pair = pairs.get(view);
+  if (!pair || !pair.undone || redoDepth(view.state) !== pair.redoDepth || !view.state.doc.eq(pair.before)) return false;
+  for (let step = 0; step < 3 && !view.state.doc.eq(pair.after); step++) if (!redo(view)) break;
+  pair.undone = !view.state.doc.eq(pair.after);
+  return true;
+}