@openpresentation/opf-editor 0.26.4 → 0.26.5

package/README.md

@@ -120,7 +120,8 @@ Methods: `replaceDocument(document, { source?, format?, name?, meta? })` (below)
 - **Completions.** In JSON, YAML and Markdown the pane offers what the schema and the catalogs say belongs at the caret (`completions: false` keeps the field menu only). *Keys*: the properties of the object at the caret, the required ones first, then the common ones in a curated order (a slide: `title`, `subtitle`, `layout`, `items`, `text`, `notes`, ...), then the rest; the promoted region keys of a slide (`top+middle:left+center`) show only once you type three characters of one. Keys already in the object are not offered. Accepting one writes the whole pair: a string key gets `"key": "|"`, a number `"key": |`, an array `"key": [|]`, an object `"key": {|}`, and an object with required members (`organization`: `id`, `name`) writes them one per line, each a tab stop that `Tab` walks (the last `Tab` leaves the braces). A key with a closed set of values (an enum, a catalog id, a boolean) opens the list of its values at once. A comma is added when a property follows, and not before `}`. *Values*: enum values and booleans, and catalog ids (layouts, themes, color and font schemes, narratives, audiences, purposes, tones: the document's own records first, then the registered catalogs', layouts in the order of their intents, each with its description and regions in the documentation panel); after a colon, `{}` and `[]` templates. *Snippets*: `slide`, `slide-text`, `slide-image`, `slide-chart`, `slide-quote`, `slide-metric`, `slide-table`, `slide-code`, `slide-two-column` and `section` in `slides`, `reference` in `references`, `dataset` in `datasets` and `deck` in a blank document, with tab stops (the chart type stop opens the list of chart types). *Triggers*: a quote or a word at a key or value place, `:` and the space after it, and `Ctrl+Space` (`Cmd+I` on macOS) anywhere the schema has something to offer, also right after a finished string; free text (titles, notes, alt text) and numbers never open a list on their own. *Keys in the list*: `Tab` and `Enter` accept (at once, right after a keystroke too), `Shift+Tab` and `Shift+Enter` accept too (an accepted item always replaces the whole token), `Escape` closes it, `Left`, `Right` and `Backspace` inside the word keep it open and filter by the text before the caret, `Ctrl+Space` with the list open shows or hides the documentation panel. With several cursors the accepted item goes in at each of them (as plain text). The data is core's (`describeField` and `catalogKindAt` of `@openpresentation/opf/schema`; `getJsonCompletions` of `/json-options` remains for hosts that want the plain list). `mountJsonCodeEditor` takes the same `completions` option, off by default there.
 - **Completions in YAML.** The same keys, values, ids, templates and snippets, from the same schema, in block and flow style. A line-and-indent reader (`source-yaml.js`) places the caret without parsing, so it works while the text is half typed: after `key: ` the values of that field, at a key place the keys of the mapping (never one already there, above or below the caret), after a list dash the keys of the item and, in `slides` and `references`, the item snippets, inside `[ ]` and `{ }` on one line the items and keys of that collection. Accepting a key writes it the way YAML spells it: `key: ` for a scalar (and the list of its values for an enum or a boolean), `key:` and an indented new line for a mapping (required members one per line, each a tab stop), `key:` and `- ` for a list; enum values and ids are plain scalars, quoted when YAML would read them as another type (`"true"`, `"12"`). Comments, block scalars and free text (titles, notes, numbers) never open a list. `Enter` indents one level after `key:` and `key: |`, aligns under the key after `- key: value`, goes on with the next `- ` after a list item that is a value, and leaves the list on an empty `- `. `[`, `{` and quotes pair (not `(` and not an apostrophe inside a word).
 - **Completions in Markdown.** The front matter and the YAML in `opf-slide` and `opf-block` fences are the YAML above (the front matter never offers `slides`); `<!-- ` offers `slide:` and `block:`; inside a slide options comment the keys (`id`, `type`, `layout`, `section`, `tag`, `hidden`, `beat`) and their values (layout ids, slide types, `true` and `false`), inside a block options comment `id`, `type`, `as` (`bullets`, `video`) and `region` (the regions of the slide's layout, then the promoted ones); after a fence's three backticks the fence kinds (`chart`, `metric`, `timeline`, `opf-block`, `opf-slide` and the code languages), after `chart ` the chart types, after the info word the attributes (`alt=`, `name=`, `description=`, `title=`); the keys and values of a `metric` fence and the status marks (`[x]`, `[>]`, `[ ]`) at the start of a `timeline` event; `{` after `]` the attributes of an inline span (`bold`, `color=`, `size=`, `font=`, `lang=`); and at the start of a line `Note:`, `Notes:` and the snippets (a slide of each kind, with its `---` separator and a blank line above it when it follows another slide). Code fences, chart data, speaker notes and plain comments never open a list, and prose does not either: a word at the start of a line opens one from the third letter on, only while it is the start of a keyword or a snippet (`Ctrl+Space` opens it anywhere). Hover (and `Cmd/Ctrl+K Cmd/Ctrl+I`) explains a front matter key or value and a slide option as in YAML, and the dialect's own syntax: the `#` of a title and the `##` of a subtitle, a list marker, `Note:`, a quote's `>`, the word of a `chart`, `metric`, `timeline`, `opf-slide` or `opf-block` fence, `slide:` and `block:`, and a `---` line, each with the schema's description of the field it writes and how it is written. The vocabulary is core's (`scanMarkdown`, `SLIDE_OPTION_KEYS`, `FENCE_KINDS`, ... of `@openpresentation/opf/source`).
-- **Hover and problems.** Hovering a key shows the schema's description, its type and its allowed values; hovering a catalog id shows the record (name, description, regions, where it comes from); `Cmd/Ctrl+K Cmd/Ctrl+I` shows the same at the caret and `Escape` hides it. Every finding that has a place in the text is underlined (errors, warnings and notes, in every format that gives core a range; JSON gets one for each schema and reference finding too), with a tooltip that says what is wrong, what could come next and how many quick fixes there are. JSON syntax errors come from core's recovery analyzer (`analyzeJsonSyntax` of `@openpresentation/opf/source`): one problem per cause, at the cause (a key with no value is reported on its own line, not at the next token), up to five, 150 ms after the last key; a problem is held back while a list of keys is open next to it, so typing `"des` never flashes red. The panel rows say `Ln 3, Col 5`, the message, `Next: ...`, the rule and the quick fix buttons. `F8` and `Shift+F8` select the next and the previous problem (and say it; they wrap), `Cmd/Ctrl+Shift+M` moves focus to the panel (arrows, Home and End move between rows, Enter selects the range and returns to the code, Escape returns, `Cmd/Ctrl+.` applies the first fix of the row), `Cmd/Ctrl+.` in the code lists the fixes at the caret (the safest first; arrows, Enter, Escape). A fix is one undo step. Quick fixes in this version: the syntax repairs (insert or remove a comma, add `{ }` or remove a key with no value, close a bracket, straight quotes, ...), "Change to ..." for an enum or a reference that resolves nowhere, "Rename to ..." and "Remove property" for an unknown key, "Add `slides`" and the like for a missing required property, "Wrap in a list", "Add a slide", "Remove the first/second" for a duplicate key, and the patch and focus fixes core ships (alt text, readable color, language). `pane.getProblems()`, `nextProblem()`, `previousProblem()`, `showProblem(index)` and `triggerCompletion()` expose the same to a host.
+- **References inside the document.** In all three formats the lists also offer the ids the document itself declares, read from the text being edited (a draft too): `asset:<id>` from `assets` (and `var:<id>` of image variables) where an image or other asset goes, dataset ids from `datasets` (`chart.data.dataset`, `table.dataset`), the column names of that dataset (or of the chart's own `data.columns`) in `fields`, `mapping`, `line`, `secondaryAxis` and `highlight.series`, `cite` ids from `references`, `beat` ids from the narrative the deck names (in a Markdown slide options comment too), `region` names from the slide's layout (then the promoted regions), `var:<id>` color variables where a color goes, and the variables of `variables` after `{{` in any text (`Tab` writes the name and the closing braces; speaker notes stay verbatim). Which field takes which kind is one table in `source-references.js`, checked against the schema by a unit test. A slide with a `layout` lists the keys that layout's regions call for first (after the required ones). A list of catalog records ends with the line "Records from catalog X are not loaded" when the document names a catalog group whose source the host did not register (its embedded records are still offered). Accepting a key of a closed set of values and then its value is one undo step. The deck's `design`, `organization` and `speaker` keys are accepted as snippets (a tab stop for each member; `design` opens the theme, color scheme and font scheme lists in turn). In YAML (and the YAML of Markdown) the list also works on the lines of a flow collection or a quoted scalar that runs over several lines.
+- **Hover and problems.** Hovering a key shows the schema's description, its type and its allowed values; hovering a catalog id shows the record (name, description, regions, where it comes from); `Cmd/Ctrl+K Cmd/Ctrl+I` shows the same at the caret and `Escape` hides it. Every finding that has a place in the text is underlined (errors, warnings and notes, in every format that gives core a range; JSON gets one for each schema and reference finding too), with a tooltip that says what is wrong, what could come next and how many quick fixes there are. JSON syntax errors come from core's recovery analyzer (`analyzeJsonSyntax` of `@openpresentation/opf/source`): one problem per cause, at the cause (a key with no value is reported on its own line, not at the next token), up to five, 150 ms after the last key; a problem is held back while a list of keys is open next to it, so typing `"des` never flashes red. The panel rows say `Ln 3, Col 5`, the message, `Next: ...`, the rule and the quick fix buttons. `F8` and `Shift+F8` select the next and the previous problem (and say it; they wrap), `Cmd/Ctrl+Shift+M` moves focus to the panel (arrows, Home and End move between rows, Enter selects the range and returns to the code, Escape returns, `Cmd/Ctrl+.` applies the first fix of the row), `Cmd/Ctrl+.` in the code lists the fixes at the caret (the safest first; arrows, Enter, Escape). A fix is one undo step. Quick fixes in this version: the syntax repairs (insert or remove a comma, add `{ }` or remove a key with no value, close a bracket, straight quotes, ...), "Change to ..." for an enum or a reference that resolves nowhere, "Rename to ..." and "Remove property" for an unknown key, "Add `slides`" and the like for a missing required property, "Wrap in a list", "Add a slide", "Remove the first/second" for a duplicate key, and the patch and focus fixes core ships (alt text, readable color, language). Phase 3 writes every problem in plain words from core (`describeFinding`: the schema keywords, all 77 `opf/*` rules, the YAML and Markdown readers; each with a `Next:` line) and adds a Details disclosure per row (`explain(ruleId)`: what the rule checks, why, how to fix it, an example). YAML and Markdown syntax problems have fixes too (`Convert tabs to spaces`, `Insert closing quote`, ``Insert ]``, `Add a colon`, `Quote the value`, `Insert ---`, `Insert closing fence`, `Insert -->`, `Rename to layout`, `Insert column`, ``Add `numbering` ``, ...), and every format gets `Move into extensions`, `Convert to string`, `Wrap in a list` and `Add a slide` as comment-preserving text edits. `pane.getProblems()`, `nextProblem()`, `previousProblem()`, `showProblem(index)` and `triggerCompletion()` expose the same to a host.
 - **Keyboard.** The keys are VS Code's. `Tab` accepts a suggestion when the list is open; otherwise it inserts spaces up to the next tab stop (replacing a selection inside one line; a selection over several lines, or a whole line, is indented line by line) and `Shift+Tab` outdents the line. The indentation unit is the document's (JSON: read once when a document is opened, two spaces if nothing is indented, or a tab; YAML and Markdown: two spaces) and typing never changes it. `Alt+Up` and `Alt+Down` move the line, `Shift+Alt+Up` and `Shift+Alt+Down` copy it, `Cmd/Ctrl+Shift+K` deletes it. `Cmd/Ctrl+D` adds the next occurrence, `Cmd/Ctrl+Shift+L` all of them, `Cmd/Ctrl+Alt+Up` and `Down` a cursor above or below, `Alt+click` a cursor, `Shift+Alt+drag` a column; `Escape` goes back to one cursor. The field menu (a searchable dialog of the choices of one field) is on `Alt+Shift+O`; `Tab` and `Shift+Tab` stay inside it and `Escape` returns to the editor. A paste inserts the clipboard text as it is, however many lines it has.
 - **Keyboard in YAML and Markdown.** `Enter` follows the text (see the two bullets above); in Markdown it continues `- `, `* `, `+ ` and `1. ` items (the number counts up), continues `> `, ends the list on an empty marker (one level out when it is nested), and keeps the indentation inside a code fence. `Tab` on a Markdown list item nests it one level (two spaces) and `Shift+Tab` brings it out; `Backspace` right after a marker takes the marker away. `Cmd/Ctrl+/` toggles `# ` on YAML lines and in the front matter, and wraps a Markdown line in `<!-- -->` (a slide or block options comment says it already is one). Typing `*`, `_`, `~` or `"` over a Markdown selection wraps it (`*` twice makes bold). `Cmd/Ctrl+Alt+[` and `]` fold and unfold a YAML mapping and, in Markdown, the front matter, a fenced block and a slide (a `---` inside a fence is not the end of one); the fold gutter and the chords for folding everything come with the navigation round. The squiggle, `F8`, the quick fix menu (`Cmd/Ctrl+.`) and the `Ln n, Col m` of the problems panel are at the right place in YAML and Markdown too: core's `locate` finds a field's key or value in the text (and a Markdown slide's title, list item or `layout=` token); the fixes (`Change to center`, `Rename to design`, `Remove property`, ``Add `name` ``) are text edits that keep the comments.
 - **Format document.** `Shift+Alt+F` (and `Cmd/Ctrl+Shift+F`) and the Format button do the same in JSON, YAML and Markdown, and change whitespace only, as one undo step with the cursor kept on its token. JSON is laid out token by token with the document's indentation, also while it does not parse; YAML keeps its comments, blank lines, quote styles, number spellings and key order (the pane says so and does nothing when the YAML has errors); Markdown gets at most one blank line between blocks (code fences untouched), its front matter formatted as YAML, and one newline at the end. A format that would change the document is refused. The pane does not rewrite the text from the document (`toYaml`, `toMarkdown`) any more, so it no longer drops comments.

package/dist/json-editor.js

@@ -11,6 +11,7 @@ import { findNodeAtOffset, getNodePath, parseTree } from "jsonc-parser";
 import {jsonSource,jsonSourceHistory,setJsonSource} from './json-source.js';
 import {textInputMap} from './text-input.js';
 import {detectIndent,formatJsonSource,whitespaceEdits} from './json-format.js';
+import { redoPair, undoPair } from "./source-undo-groups.js";
 import {a11yExtension,createAnnouncer} from './source-a11y.js';
 import { forEachDiagnostic } from "@codemirror/lint";
 import {createDiagnostics,editsTransaction} from './source-diagnostics.js';
@@ -338,8 +339,8 @@ function mountJsonCodeEditor(parent, options) {
     return loadOptions().then(() => (disposed || context.aborted ? null : completionResult(context)), (error) => { options.onError?.(error); return null; });
   }
   // Undo and Redo run CodeMirror's history first. When it has nothing left, the host's fallback may step further (the source pane routes a whole-document replace to the session); a fallback answers true when it did something.
-  const undoCommand = (target) => undo(target) || Boolean(options.historyFallback?.undo?.());
-  const redoCommand = (target) => redo(target) || Boolean(options.historyFallback?.redo?.());
+  const undoCommand = (target) => undoPair(target) || undo(target) || Boolean(options.historyFallback?.undo?.());
+  const redoCommand = (target) => redoPair(target) || redo(target) || Boolean(options.historyFallback?.redo?.());
   const historyBindings = historyKeymap.map((binding) => binding.run === undo ? { ...binding, run: undoCommand } : binding.run === redo ? { ...binding, run: redoCommand } : binding);
   // Accept with no minimum delay: the list is already valid for the typed text, so Tab or Enter right after a keystroke accepts (VS Code does).
   // Screen reader announcements and the problems drawn in the text (squiggles, F8, Cmd/Ctrl+.). The pane supplies the problems.

package/dist/source-a11y.js

@@ -77,7 +77,8 @@ export function a11yExtension(announcer, describe = () => "") {
       const open = completionStatus(state) === "active" && currentCompletions(state).length > 0;
       const selected = open ? selectedCompletion(state) : null;
       if (open && !this.open) {
-        announcer.say(plural(currentCompletions(state).length, "suggestion"));
+        const footer = currentCompletions(state).find((completion) => completion.opfFooter)?.opfFooter;
+        announcer.say(`${plural(currentCompletions(state).length, "suggestion")}${footer ? `. ${footer}` : ""}`);
       } else if (open && selected && selected !== this.selected) {
         clearTimeout(this.timer);
         this.timer = setTimeout(() => {
@@ -98,12 +99,28 @@ export function a11yExtension(announcer, describe = () => "") {
       const { view } = this, { state } = view;
       const completions = currentCompletions(state);
       if (!completions.length) return;
+      this.footer(completions);
       for (const node of view.dom.querySelectorAll(".cm-tooltip-autocomplete [role=option]")) {
         const index = Number(node.id.slice(node.id.lastIndexOf("-") + 1));
         const completion = completions[index];
         if (completion) node.setAttribute("aria-label", optionName(completion, index, completions.length));
       }
     }
+    // The line under a list of catalog records whose catalog is not loaded (SPEC 4.5): part of the list's own box, after the options.
+    footer(completions) {
+      const tooltip = this.view.dom.querySelector(".cm-tooltip-autocomplete");
+      if (!tooltip) return;
+      const text = completions.find((completion) => completion.opfFooter)?.opfFooter ?? "";
+      let node = tooltip.querySelector(":scope > .opf-completion-footer");
+      if (!text) { node?.remove(); return; }
+      if (!node) {
+        node = tooltip.ownerDocument.createElement("div");
+        node.className = "opf-completion-footer";
+        node.setAttribute("role", "note");
+      }
+      if (node.textContent !== text) node.textContent = text;
+      if (tooltip.lastElementChild !== node) tooltip.append(node);
+    }
     destroy() { clearTimeout(this.timer); clearTimeout(this.labelTimer); }
   });
 }

package/dist/source-completions.js

@@ -5,15 +5,18 @@ import { hasNextSnippetField, hasPrevSnippetField, pickedCompletion, snippet, st
 import { isolateHistory } from "@codemirror/commands";
 import { EditorSelection } from "@codemirror/state";
 import { describeField } from "@openpresentation/opf/schema";
-import { listCatalogRecords } from "./catalogs.js";
+import { listCatalogRecords, mergeCatalogs } from "./catalogs.js";
 import { LAYOUT_INTENT_GROUPS, layoutRegionSummary } from "./layout-templates.js";
-import { Document, parse as parseYamlDocument } from "yaml";
-import { pathAt } from "@openpresentation/opf/source";
+import { Document, parse as parseYamlDocument, parseDocument } from "yaml";
+import { pathAt, scanMarkdown } from "@openpresentation/opf/source";
+import { findNodeAtLocation, getNodeValue } from "jsonc-parser";
 import { contextAt, nextSignificant, nodeAt, skeleton, tokenAt } from "./source-json.js";
+import { PROMOTED_REGIONS, beatsOf, columnSourceFor, factsOf, jsonDeckParts, layoutKeys, referenceSiteAt, regionNames, slidePath, valueAt, variableNames, yamlDeckParts } from "./source-references.js";
+import { beginUndoGroup, finishUndoGroup, takeUndoGroup } from "./source-undo-groups.js";
 import { scalarValue, yamlContextAt } from "./source-yaml.js";
 import { markdownContextAt, markdownOptions, markdownPlan, markdownHoverAt } from "./source-markdown.js";
 import { childDoc, docNode, docText, fieldDoc } from "./source-docs.js";
-import { snippetJson, snippetYaml, snippetsFor } from "./source-snippets.js";
+import { keySnippetsFor, snippetJson, snippetYaml, snippetsFor } from "./source-snippets.js";
 
 export { contextAt, tokenAt };
 
@@ -114,16 +117,38 @@ function advancedShown(children, typed, explicit) {
   return children.some((child) => child.advanced && child.key.toLowerCase().startsWith(typed));
 }
 
-function keyOptions(context, text, caret, explicit) {
+/**
+ * The keys of an object in the order the list shows them (SPEC 4.4): the required ones first, then, for a slide with a layout, the keys the layout's
+ * regions call for that are not set yet, then the common order the schema gives (`children` arrives in that order and keeps it).
+ */
+function rankKeys(context, shown, catalogs) {
+  const slide = context.path.length === 2 && context.path[0] === "slides" ? valueAt(context.document, context.path) : undefined;
+  const layout = typeof slide?.layout === "string" ? slide.layout : undefined;
+  let wanted = [];
+  if (layout) {
+    try {
+      const record = listCatalogRecords(context.document, "layouts", { catalogs }).find((entry) => entry.id === layout)?.record;
+      wanted = layoutKeys(record, shown.map((child) => child.key));
+    } catch { wanted = []; }
+  }
+  const rank = (child) => (child.required ? 0 : wanted.includes(child.key) ? 1 : 2);
+  return shown.map((child, index) => ({ child, index })).sort((a, b) => rank(a.child) - rank(b.child) || (rank(a.child) === 1 ? wanted.indexOf(a.child.key) - wanted.indexOf(b.child.key) : a.index - b.index)).map((entry) => entry.child);
+}
+
+function keyOptions(context, text, caret, explicit, catalogs) {
   const info = describeField(context.path, context.document);
   const typed = text.slice(context.token.from, caret).toLowerCase();
   const options = [];
   if (info.known) {
     const free = info.children.filter((child) => !context.existing.has(child.key));
     const withAdvanced = advancedShown(free, typed, explicit);
-    const shown = free.filter((child) => !child.advanced || (withAdvanced && child.key.toLowerCase().startsWith(typed)));
+    const shown = rankKeys(context, free.filter((child) => !child.advanced || (withAdvanced && child.key.toLowerCase().startsWith(typed))), catalogs);
     // A blank document starts with a deck: its snippet comes first.
     if (context.blank) for (const entry of snippetsFor("value", [])) options.push(snippetOption(entry, 99));
+    // A key a snippet is written for (the deck's `design`, `organization`, `speaker`) is accepted as that snippet, as VS Code does for a property
+    // with default snippets: its members come with it, each a tab stop.
+    const keySnippets = snippetsFor("key", context.path);
+    const forKey = (key) => (context.flow ? undefined : keySnippetsFor(context.path).find((entry) => entry.key === key));
     shown.forEach((child, index) => options.push({
       label: child.key,
       type: "property",
@@ -131,10 +156,10 @@ function keyOptions(context, text, caret, explicit) {
       boost: boostAt(index + (context.blank ? 1 : 0)),
       opfRequired: child.required,
       opfDoc: child.description ?? "",
-      opf: { kind: "key", key: child.key },
+      opf: { kind: "key", key: child.key, ...(forKey(child.key) ? { snippet: child.key } : {}) },
       info: () => docNode(describeChild(context, child)),
     }));
-    for (const entry of snippetsFor("key", context.path)) options.push(snippetOption(entry, boostAt(options.length)));
+    for (const entry of keySnippets) options.push(snippetOption(entry, boostAt(options.length)));
     // A key right after a list dash is also the start of the item: the item snippets (a slide, a reference) fit there.
     if (context.itemStart) for (const entry of snippetsFor("item", context.path)) options.push(snippetOption(entry, boostAt(options.length)));
     return { options, advanced: withAdvanced };
@@ -183,12 +208,132 @@ function catalogOptions(kind, context, catalogs) {
   });
 }
 
-function valueOptions(context, catalogs) {
+// ---- cross references (SPEC 3.4) --------------------------------------------------------------------------------------------------------
+/**
+ * Where the references of the document are read from, for the context: `facts()` the assets, datasets, variables, references and the narrative
+ * (once), `read(path)` a value of the text being edited (a draft: undefined when the text does not say). `format` is the editor's: "json", "yaml"
+ * or "md" (the deck of a Markdown text is its front matter).
+ */
+export function referenceScope(context, text, format) {
+  let facts, parsed;
+  const deckParts = () => {
+    if (format === "json") return context.root ? jsonDeckParts(context.root, getNodeValue) : {};
+    if (format === "md") {
+      const front = scanMarkdown(text).frontMatter;
+      return front ? yamlDeckParts(text.slice(front.yamlFrom, front.yamlTo)) : {};
+    }
+    return yamlDeckParts(text);
+  };
+  return {
+    facts: () => (facts ??= factsOf(deckParts())),
+    read(path) {
+      if (format === "json") {
+        const node = context.root ? findNodeAtLocation(context.root, path) : undefined;
+        return node ? getNodeValue(node) : undefined;
+      }
+      if (parsed === undefined) {
+        try { parsed = parseDocument(context.sourceText ?? text, { strict: false, uniqueKeys: false }).toJS({ maxAliasCount: -1 }); } catch { parsed = null; }
+      }
+      return valueAt(parsed, path.slice(context.prefix?.length ?? 0));
+    },
+  };
+}
+
+const REFERENCE_LABELS = { asset: "asset", dataset: "dataset", datasetColumn: "dataset column", cite: "reference", beat: "narrative beat", region: "layout region", color: "color variable" };
+const referenceOption = (id, value, extra) => literalOption(id, JSON.stringify(value), { type: "reference", value, ...extra });
+
+function referenceOptions(site, context, catalogs, scope) {
+  const facts = scope.facts();
+  const options = [];
+  const add = (id, value, extra = {}) => options.push(referenceOption(id, value, { boost: boostAt(options.length), info: () => docNode({ title: id, type: REFERENCE_LABELS[site.kind], description: extra.doc || undefined, notes: [extra.detail].filter(Boolean) }), ...extra }));
+  switch (site.kind) {
+    case "asset":
+      for (const asset of facts.assets) add(`asset:${asset.id}`, `asset:${asset.id}`, { detail: asset.detail || "asset", doc: asset.detail });
+      for (const variable of facts.variables) if (variable.type === "image") add(`var:${variable.id}`, `var:${variable.id}`, { detail: "image variable" });
+      break;
+    case "dataset":
+      for (const dataset of facts.datasets) add(dataset.id, dataset.id, { detail: dataset.title || `${dataset.columns.length} columns`, doc: dataset.columns.join(", ") });
+      break;
+    case "datasetColumn": {
+      const source = columnSourceFor(site, (path) => scope.read(path));
+      const columns = source?.dataset !== undefined ? facts.datasets.find((entry) => entry.id === source.dataset)?.columns : source?.inline;
+      for (const column of columns ?? []) add(column, column, { detail: source.dataset !== undefined ? `column of ${source.dataset}` : "column" });
+      break;
+    }
+    case "cite":
+      for (const reference of facts.references) add(reference.id, reference.id, { detail: brief(reference.text) ?? "reference", doc: reference.text });
+      break;
+    case "beat": {
+      let record;
+      if (facts.narrative) {
+        try { record = listCatalogRecords(context.document, "narratives", { catalogs }).find((entry) => entry.id === facts.narrative)?.record; } catch { record = undefined; }
+      }
+      for (const beat of beatsOf(record)) add(beat.id, beat.id, { detail: beat.name || "beat", doc: brief(beat.description) });
+      break;
+    }
+    case "region": {
+      const slide = slidePath(context.path);
+      const layout = slide ? valueAt(context.document, slide)?.layout : undefined;
+      let names = [];
+      if (typeof layout === "string") {
+        try { names = regionNames(listCatalogRecords(context.document, "layouts", { catalogs }).find((entry) => entry.id === layout)?.record); } catch { names = []; }
+      }
+      for (const name of names) add(name, name, { detail: `region of ${layout}` });
+      for (const name of PROMOTED_REGIONS) if (!names.includes(name)) add(name, name, { detail: "promoted region" });
+      break;
+    }
+    case "color":
+      for (const variable of facts.variables) if (variable.type === "color") add(`var:${variable.id}`, `var:${variable.id}`, { detail: "color variable" });
+      break;
+    default:
+  }
+  return options;
+}
+
+// `{{name}}` in a text: the variables the document declares, offered once `{{` is typed. `before` is the text of the value before the caret.
+const VARIABLE_OPEN = /\{\{([A-Za-z0-9._-]*)$/;
+function variableOptions(scope) {
+  const options = [];
+  variableNames(scope.facts()).forEach((variable, index) => options.push({ label: variable.id, type: "reference", detail: `${variable.type} variable`, boost: boostAt(index), opfDoc: `The variable ${variable.id}`, opf: { kind: "variable", name: variable.id } }));
+  return options;
+}
+
+/** The result for a caret right after `{{` in a text value, or null: the variable names, replacing what is typed after the braces. */
+function variableResult(context, text, position, scope) {
+  const token = context.token;
+  if (!token || context.mode === "key") return null;
+  const open = VARIABLE_OPEN.exec(text.slice(token.from, Math.min(position, token.to)));
+  return open ? variableList(scope, position - open[1].length, position) : null;
+}
+
+function variableList(scope, from, position) {
+  const options = variableOptions(scope);
+  return options.length ? { from, to: position, filter: true, options, validFor: (typed) => /^[A-Za-z0-9._-]*$/.test(typed) } : null;
+}
+
+/**
+ * The line under a list of catalog records when a group of the document names a source no registered catalog matches (SPEC 4.5): its records
+ * beyond the embedded ones are not available here. Empty when every source is registered.
+ */
+export function unloadedFooter(document, catalogs) {
+  const groups = document && typeof document === "object" ? document.catalogs : undefined;
+  if (!groups || typeof groups !== "object") return "";
+  let registered = [];
+  try { registered = mergeCatalogs(catalogs).map((entry) => entry.source); } catch { registered = []; }
+  const names = Object.entries(groups).filter(([name, group]) => name !== "custom" && group && typeof group === "object" && typeof group.source === "string" && !registered.includes(group.source)).map(([name]) => name);
+  return names.length ? `Records from catalog ${names.join(", ")} are not loaded` : "";
+}
+
+function valueOptions(context, catalogs, scope) {
   const info = describeField(context.path, context.document);
   const options = [];
   if (!info.known) return { options };
   const variant = primaryVariant(info);
-  if (info.catalogKind) options.push(...catalogOptions(info.catalogKind, context, catalogs));
+  const site = scope ? referenceSiteAt(context.path, context.document) : null;
+  if (info.catalogKind) {
+    const footer = unloadedFooter(context.document, catalogs);
+    for (const option of catalogOptions(info.catalogKind, context, catalogs)) options.push(footer ? { ...option, opfFooter: footer } : option);
+  }
   else if (info.enum?.length) {
     // In the order VS Code lists them: by label.
     info.enum.forEach((entry) => options.push(literalOption(String(entry.value), JSON.stringify(entry.value), {
@@ -201,6 +346,7 @@ function valueOptions(context, catalogs) {
     const label = variant.type === "object" ? "{}" : "[]";
     options.push({ label, type: "keyword", detail: variant.type === "object" ? "object" : "list", boost: 99, opfDoc: info.description ?? "", opf: { kind: "template" }, info: () => docNode(fieldDoc(info, context.key ?? label)) });
   }
+  if (site) options.push(...referenceOptions(site, context, catalogs, scope));
   for (const entry of snippetsFor(context.mode, context.path)) options.push(snippetOption(entry, boostAt(options.length)));
   return { options };
 }
@@ -234,12 +380,15 @@ export function completionResult(state, position, { explicit, catalogs, format =
   const text = state.doc.toString();
   let context = contextFor(format, text, position, explicit);
   if (!context) return null;
-  if (context.format === "md") return markdownResult(context, text, position, { explicit, catalogs });
+  const scope = referenceScope(context, text, format);
+  if (context.format === "md") return context.region === "variable" ? variableList(scope, context.token.from, position) : markdownResult(context, text, position, { explicit, catalogs, scope });
   if (context.format === "yaml") {
     context = settleYamlContext(context, text);
     if (!context) return null;
   }
-  const { options, advanced } = context.mode === "key" ? keyOptions(context, text, position, explicit) : valueOptions(context, catalogs);
+  const variables = context.mode !== "key" ? variableResult(context, text, position, scope) : null;
+  if (variables || context.multiline) return variables;
+  const { options, advanced } = context.mode === "key" ? keyOptions(context, text, position, explicit, catalogs) : valueOptions(context, catalogs, scope);
   if (!options.length) return null;
   return listResult(context, options, advanced, { position, explicit });
 }
@@ -261,8 +410,8 @@ function listResult(context, options, advanced, { position, explicit }) {
   };
 }
 
-function markdownResult(context, text, position, { explicit, catalogs }) {
-  const built = markdownOptions(context, { catalogs, explicit, text, position, makers: { snippetOption, literalOption, boostAt, docNode, valueOptions, listCatalogRecords } });
+function markdownResult(context, text, position, { explicit, catalogs, scope }) {
+  const built = markdownOptions(context, { catalogs, explicit, text, position, scope, makers: { snippetOption, literalOption, boostAt, docNode, valueOptions, listCatalogRecords } });
   if (!built?.options.length) return null;
   const { token } = context;
   return {
@@ -289,9 +438,14 @@ const yamlKey = (key) => (/^[A-Za-z_$][A-Za-z0-9_.$+-]*(?::[A-Za-z0-9_.$+-]+)*$/
 const escapeTemplate = (text) => text.replace(/[\\{}]/g, (character) => `\\${character}`);
 
 /** What accepting a key writes in YAML: `key: ` for a scalar, `key:` and a new line for a mapping or a list. */
-function yamlKeyPlan(context, key, text, end) {
+function yamlKeyPlan(context, key, text, end, snippetKey) {
   const written = yamlKey(key);
   if (/^[ \t]*:/.test(text.slice(end))) return { template: escapeTemplate(written), fields: 0, chain: false };
+  const entry = snippetKey ? keySnippetsFor(context.path).find((candidate) => candidate.key === snippetKey) : undefined;
+  if (entry && !context.flow) {
+    const rendered = snippetYaml(entry, { dash: 0 });
+    return { template: rendered.text, fields: rendered.fields.length, chain: false, choices: rendered.fields };
+  }
   let info;
   try { info = describeField([...context.path, key], context.document); } catch { info = null; }
   const kind = info?.known ? variantKind(info) : "string";
@@ -313,7 +467,7 @@ function yamlKeyPlan(context, key, text, end) {
 /** What accepting `completion` writes in YAML: `{ start, end, template, fields, chain, choices }`. */
 function planYaml(context, completion, text, end) {
   const kind = completion.opf?.kind;
-  if (kind === "key") return yamlKeyPlan(context, completion.opf.key, text, end);
+  if (kind === "key") return yamlKeyPlan(context, completion.opf.key, text, end, completion.opf.snippet);
   if (kind === "literal") {
     const value = completion.opf.value;
     const prefix = context.needsSpace ? " " : "";
@@ -345,6 +499,11 @@ export function planCompletion(context, completion, text, end) {
     const key = completion.opf.key;
     const quoted = JSON.stringify(key);
     if (/^\s*:/.test(text.slice(end))) return { template: quoted, fields: 0, chain: false };
+    const entry = completion.opf.snippet ? keySnippetsFor(context.path).find((candidate) => candidate.key === completion.opf.snippet) : undefined;
+    if (entry) {
+      const rendered = snippetJson(entry, { comma: needsComma });
+      return { template: rendered.text, fields: rendered.fields.length, chain: false, choices: rendered.fields };
+    }
     let info;
     try { info = describeField([...context.path, key], context.document); } catch { info = null; }
     const value = info?.known ? valueTemplate(info) : { template: '"${1}"', fields: 1, chain: false };
@@ -363,7 +522,7 @@ export function planCompletion(context, completion, text, end) {
   if (kind === "snippet") {
     const entry = snippetsFor(context.mode, context.path).find((candidate) => candidate.prefix === completion.opf.prefix);
     if (!entry) return null;
-    const rendered = snippetJson(entry, { comma: needsComma && context.mode !== "key" });
+    const rendered = snippetJson(entry, { comma: needsComma && !/^\s*:/.test(text.slice(end)) });
     return { template: rendered.text, fields: rendered.fields.length, chain: false, choices: rendered.fields };
   }
   return null;
@@ -374,10 +533,26 @@ export function applyCompletion(view, completion, fallbackFrom, fallbackTo, say,
   const { state } = view;
   const text = state.doc.toString();
   const main = state.selection.main;
+  if (completion.opf?.kind === "variable") {
+    // `{{na|` becomes `{{name}}`: the name replaces what was typed after the braces and the closing braces are written unless they are there.
+    const to = text.startsWith("}}", fallbackTo) ? fallbackTo + 2 : fallbackTo;
+    const insert = `${completion.opf.name}}}`;
+    view.dispatch({ changes: { from: fallbackFrom, to, insert }, selection: { anchor: fallbackFrom + insert.length }, annotations: [pickedCompletion.of(completion), isolateHistory.of("full")], userEvent: "input.complete", scrollIntoView: true });
+    return;
+  }
+  // A value accepted right after the key that opened its list is one undo step with that key (R-CMP-14).
+  const group = takeUndoGroup(view);
   const context = contextFor(format, text, main.head, true);
   const token = context?.token;
   const start = token ? token.start : fallbackFrom, end = token ? token.end : fallbackTo;
   const plan = context ? planCompletion(context, completion, text, end) : null;
+  // Accepting is one undo step: what is typed next starts another.
+  const finish = (chain) => {
+    view.dispatch({ annotations: isolateHistory.of("full") });
+    if (group) finishUndoGroup(view, group);
+    // A key whose value is one of a closed set opens that list at once.
+    if (chain) { beginUndoGroup(view, state.doc); startCompletion(view); }
+  };
   if (!plan) {
     view.dispatch({ changes: { from: fallbackFrom, to: fallbackTo, insert: completion.label }, selection: { anchor: fallbackFrom + completion.label.length }, annotations: [pickedCompletion.of(completion)], userEvent: "input.complete" });
     return;
@@ -393,6 +568,7 @@ export function applyCompletion(view, completion, fallbackFrom, fallbackTo, say,
     if (next !== "" && !",}]".includes(next)) changes.push({ from: token.end, insert: "," });
     const caret = inSnippet ? token.from + inner.length : token.end + inner.length - (token.to - token.from);
     view.dispatch({ changes, selection: { anchor: caret }, annotations: [pickedCompletion.of(completion)], userEvent: "input.complete", scrollIntoView: true });
+    finish(false);
     return;
   }
   // YAML and Markdown values inside quotes: only the inside changes, and the caret ends after the closing quote.
@@ -400,6 +576,7 @@ export function applyCompletion(view, completion, fallbackFrom, fallbackTo, say,
     const insert = plan.template.replace(/\\([{}\\])/g, "$1");
     const caret = token.closed ? token.end + insert.length - (token.to - token.from) : token.from + insert.length;
     view.dispatch({ changes: { from: token.from, to: token.to, insert }, selection: { anchor: caret }, annotations: [pickedCompletion.of(completion)], userEvent: "input.complete", scrollIntoView: true });
+    finish(false);
     return;
   }
   const from = plan.replaceFrom ?? start, to = plan.replaceTo ?? end;
@@ -407,16 +584,13 @@ export function applyCompletion(view, completion, fallbackFrom, fallbackTo, say,
     snippet(plan.template)(view, completion, from, to);
     if (plan.choices) snippetRuns.set(view, { fields: plan.choices, index: -1 });
     else snippetRuns.delete(view);
-    if (plan.choices) snippetStep(view, true, { start: true, say });
+    if (plan.choices) snippetStep(view, true, { start: true, say: say && ((message) => say(`Inserted ${completion.label}. ${message}`)) });
   } else {
     const insert = plan.template.replace(/\\([{}\\])/g, "$1");
     view.dispatch({ changes: { from, to, insert }, selection: { anchor: from + insert.length }, annotations: [pickedCompletion.of(completion)], userEvent: "input.complete", scrollIntoView: true });
     snippetRuns.delete(view);
   }
-  // Accepting is one undo step: what is typed next starts another.
-  view.dispatch({ annotations: isolateHistory.of("full") });
-  // A key whose value is one of a closed set opens that list at once.
-  if (plan.chain) startCompletion(view);
+  finish(plan.chain);
 }
 
 // With several cursors the item goes in at each of them as plain text (no tab stops), each over its own token.

package/dist/source-details.js

@@ -0,0 +1,17 @@
+// The "Details" of a problem (artifacts/source-editor/VALIDATOR-HINTS.md, section 1): what the rule checks, why it matters, what to do and a small
+// example, from core's `explain(ruleId)`, behind a disclosure so the row itself stays one sentence and a hint. Pure data here; the pane draws it.
+import { explain } from "@openpresentation/opf/source";
+
+/**
+ * The details of a finding: `{ rule, summary, why, fix, example?, docs? }`, or null when core has nothing to say about the rule. A schema finding adds the
+ * keyword and the place in the schema it comes from.
+ */
+export function detailsFor(finding) {
+  const ruleId = finding?.ruleId;
+  if (!ruleId) return null;
+  let found;
+  try { found = explain(ruleId); } catch { found = undefined; }
+  if (!found) return null;
+  const schema = finding.validation?.keyword ? `The schema keyword is ${finding.validation.keyword}${finding.definition ? `; it is defined at ${finding.definition}` : ""}.` : "";
+  return { rule: found.id, summary: found.summary, why: found.rationale, fix: found.fix, ...(found.example ? { example: found.example } : {}), docs: finding.definition ?? found.docs, ...(schema ? { schema } : {}) };
+}