@openpresentation/opf-editor 0.26.1 → 0.26.3

package/README.md

@@ -117,14 +117,15 @@ Methods: `replaceDocument(document, { source?, format?, name?, meta? })` (below)
 - **JSON is canonical** and keeps the author's bytes: a YAML or Markdown edit rewrites only the changed JSON tokens (`exact-source`), and Undo restores the exact spelling.
 - **YAML and Markdown** are core's browser-safe converters, `@openpresentation/opf/yaml` and `/markdown`. Switching format writes the session's document in the new format. An edit parses back to the document and reaches the session as one `replace` patch, after a short delay (`applyDelay`, default 250 ms) so one burst of typing is one undo step. A syntax error, or an OPF rule the session refuses, is listed with its line and never reaches the document; Undo, Redo and outside edits replace a draft that did not parse.
 - **Nothing is lost silently.** Markdown writes what its dialect has no syntax for (a `design`, region keys, nested groups) as YAML in `opf-slide` and `opf-block` fences; each such part is a warning finding with its JSON Pointer and reason. Comments in YAML cannot survive a rewrite from the document: outside edits drop them and say how many. Format (below) never rewrites from the document, so it keeps them. A document that is not valid OPF cannot be written as YAML or Markdown; the pane stays in JSON and says so.
-- **Completions.** In JSON the pane offers property names and values as you type (`completions: false` keeps the field menu only): the keys the schema allows at the cursor's object, and the enum, boolean and catalog values of the field, from the same data as the field menu (`getJsonCompletions` in `/json-options`, which reads drafts that do not parse yet). Tab and Enter accept the selected item (at once, right after a keystroke too), Escape closes the list, and Ctrl+Space (Cmd+I on macOS) opens it, also right after a finished string. With several cursors the list stays closed. YAML and Markdown have no completions yet. `mountJsonCodeEditor` takes the same `completions` option, off by default there.
+- **Completions.** In JSON 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). YAML and Markdown have no completions yet. `mountJsonCodeEditor` takes the same `completions` option, off by default there.
+- **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.
 - **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.
 - **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.
-- **Accessibility.** The editor's `aria-invalid` is `true` while the findings include an error and `false` otherwise. The format button (`aria-label="Source format"`) opens a `role="menu"` of `menuitemradio` items: Arrow keys, Home, End, Enter, Escape (focus returns to the button) and Tab. The file name is a button that becomes a text input; Enter or Escape commits. Controls show a 2px `--opf-ui-ring` focus outline.
+- **Accessibility.** One polite live region (`.opf-source-live`) says how many suggestions there are when the list opens, the selected item and the first sentence of its documentation as you arrow (after a short pause), `Inserted design` when you accept, `Tab stop 2 of 3: ...` in a snippet, the problem when the caret enters a squiggle or `F8` reaches it, and `2 problems: 1 error, 1 warning` once the problems stop changing for 600 ms; hosts get every message through the `announce` option. Every suggestion has an accessible name with its kind and its place (`design, property, Design. 1 of 3`), the editor's `aria-description` says how to open the list and how to leave the editor (`Escape` then `Tab`, or `Ctrl+M`; `Ctrl+Shift+M` on macOS), and the problem rows start with the severity as text as well as a shape. The editor's `aria-invalid` is `true` while the findings include an error and `false` otherwise. The format button (`aria-label="Source format"`) opens a `role="menu"` of `menuitemradio` items: Arrow keys, Home, End, Enter, Escape (focus returns to the button) and Tab. The file name is a button that becomes a text input; Enter or Escape commits. Controls show a 2px `--opf-ui-ring` focus outline.
 - **Styles.** `src/styles/source-pane.css` uses only `--opf-ui-*` tokens under the `opf-source-` prefix. It ships in the editor's `styles.css` (`@openpresentation/opf-editor/styles.css`), which also defines the tokens.
 - **Dependency.** `yaml` (ISC; core already depends on it) formats YAML while keeping its comments. `@codemirror/lang-yaml` (MIT) highlights YAML; Markdown uses a small stream tokenizer built on `@codemirror/language`, so no Markdown, HTML, CSS or JavaScript grammar is added.
 
-Icons are inline paths from [Lucide](https://lucide.dev) (ISC license). The harness is `examples/source-pane.html` (built by `pnpm run build:playground`); `pnpm run test:source-pane-browser` drives it, and `pnpm run test:source-keyboard-browser` runs the keyboard cases (real key events; `OPF_BROWSER_ENGINE=webkit` and `OPF_KEYBOARD_PLATFORM=win32|linux|darwin` pick the browser and the key map).
+Icons are inline paths from [Lucide](https://lucide.dev) (ISC license). The harness is `examples/source-pane.html` (built by `pnpm run build:playground`); `pnpm run test:source-pane-browser` drives it, and `pnpm run test:source-keyboard-browser` and `pnpm run test:source-keyboard-json-browser` run the keyboard cases (real key events; `OPF_BROWSER_ENGINE=webkit` and `OPF_KEYBOARD_PLATFORM=win32|linux|darwin` pick the browser and the key map).
 
 ## Layout editor (RR-99)
 

package/dist/json-editor.d.ts

@@ -1,7 +1,40 @@
 import type { JsonCatalogContext } from './json-options.js';
 
+/** One text edit of a quick fix, in source offsets of the text as it is when the fix is applied. */
+export interface SourceEdit { from: number; to: number; insert: string }
+/**
+ * A quick fix of a problem: `edits` are applied as one undoable change (`caret`, or `select: [from, to]`, is a position in the text after them),
+ * or `run(api, problem)` does something else (the source pane applies a patch through the session).
+ */
+export interface EditorFix {
+  id: string;
+  title: string;
+  /** Mechanical and unambiguous: offered first. */
+  safe?: boolean;
+  edits?: SourceEdit[];
+  caret?: number;
+  select?: [number, number];
+  run?(api: JsonEditorApi, problem: EditorProblem): void;
+}
+/** A problem drawn in the text: a squiggle over `from..to` (source offsets), its message, what could come next and its quick fixes. */
+export interface EditorProblem {
+  from: number;
+  to: number;
+  severity: "error" | "warning" | "info";
+  message: string;
+  /** What to do, without a leading "Next:". */
+  next?: string;
+  /** The rule id, shown as the source of the problem. */
+  rule?: string;
+  fixes?: EditorFix[];
+}
+
 /** All offsets address the original source in UTF-16, including CRLF pairs. */
 export interface JsonEditorApi {
+  /** Say `message` in the editor's live region (screen readers). */
+  say(message: string): void;
+  /** Apply several edits as one undoable change; `caret` or `select` is a position in the text after them. */
+  applyEdits(edits: SourceEdit[], options?: { caret?: number; select?: [number, number]; userEvent?: string }): void;
   getValue(): string;
   getSelection(): [number, number];
   hasFocus(): boolean;
@@ -32,9 +65,11 @@ export interface JsonCodeEditorOptions {
   language?: "json" | "yaml" | "markdown";
   readOnly?: boolean;
   /**
-   * Live completion list in JSON: property names and enum, boolean and catalog values at the cursor's JSON path, from the same data as the field
-   * menu (default false here; the source pane turns it on). Tab and Enter accept the selected item, Escape closes the list, and Ctrl+Space (Cmd+I on
-   * macOS) opens it. The field menu is on Alt+Shift+O; with `completions` off it is also on Ctrl+Space.
+   * Live completion list in JSON (default false here; the source pane turns it on): property names from the schema, ranked with the required and the
+   * common ones first, and values (enums, booleans, catalog ids, `{}` and `[]` templates with their required members, snippets for slides and the like)
+   * at the cursor's JSON path. Typing a quote, a word, `:` or the space after it opens the list; Ctrl+Space (Cmd+I on macOS) opens it anywhere (with
+   * the list open it shows or hides the documentation). Tab and Enter (and Shift+Tab, Shift+Enter) accept the selected item, Escape closes the list,
+   * Left, Right and Backspace inside the word keep it open. The field menu is on Alt+Shift+O; with `completions` off it is also on Ctrl+Space.
    */
   completions?: boolean;
   catalogs?: JsonCatalogContext;
@@ -51,6 +86,17 @@ export interface JsonCodeEditorOptions {
    * format JSON only.
    */
   onFormat?(): void;
+  /** Hover documentation over keys and catalog ids in JSON, and Cmd/Ctrl+K Cmd/Ctrl+I (default true). */
+  hover?: boolean;
+  /** Called with every message the live region says (hosts mirror them into a region of their own). */
+  announce?(message: string): void;
+  /**
+   * JSON syntax errors are underlined by the editor itself, one per cause, 300 ms after the last key (default true). A host that supplies every
+   * problem through `setProblems` (the source pane) turns it off.
+   */
+  syntaxProblems?: boolean;
+  /** Cmd/Ctrl+Shift+M: move focus to the host's problems list. Answer true when it did. */
+  onFocusProblems?(): boolean;
   onFocus?(): void;
   onHoverField?(path: string | null): void;
   onError?(error: unknown): void;
@@ -60,6 +106,22 @@ export interface JsonCodeEditor {
   /** Apply external source without emitting onChange or adding a local undo step. */
   update(code: string, invalid?: boolean, field?: string | null, describedBy?: string): void;
   setCatalogs(catalogs: JsonCatalogContext): void;
+  /** Draw the problems in the text (squiggles with their messages and quick fixes). Replaces the ones drawn before. */
+  setProblems(problems: readonly EditorProblem[]): void;
+  /** The problems drawn now, in position order, at their current source offsets. */
+  getProblems(): EditorProblem[];
+  /** F8: select the next problem and say what it is; wraps. */
+  nextProblem(): boolean;
+  /** Shift+F8. */
+  previousProblem(): boolean;
+  /** Cmd/Ctrl+.: the quick fixes of the problems at the caret. */
+  triggerQuickFix(): boolean;
+  /** Ctrl+Space: open the suggestion list at the caret. */
+  triggerCompletion(): boolean;
+  /** Whether a suggestion list is open or being asked for. */
+  isCompleting(): boolean;
+  /** Perform a quick fix. */
+  applyFix(fix: EditorFix, problem?: EditorProblem): void;
   setLanguage(language: "json" | "yaml" | "markdown"): void;
   setReadOnly(readOnly: boolean): void;
   /** Forget the typed edits CodeMirror can undo, for when the text they were typed against was replaced. The text is unchanged. */

package/dist/json-editor.js

@@ -1,17 +1,19 @@
 import { Annotation, ChangeSet, Compartment, EditorSelection, EditorState, Prec, StateEffect, StateField, Transaction, countColumn } from "@codemirror/state";
-import { Decoration, EditorView, crosshairCursor, drawSelection, keymap, lineNumbers, rectangularSelection } from "@codemirror/view";
-import { defaultKeymap, history, historyKeymap, indentLess, indentMore, insertNewlineAndIndent, isolateHistory, redo, undo, undoDepth } from "@codemirror/commands";
+import { Decoration, EditorView, activateHover, closeHoverTooltips, crosshairCursor, drawSelection, hasHoverTooltips, hoverTooltip, keymap, lineNumbers, rectangularSelection } from "@codemirror/view";
+import { defaultKeymap, deleteCharBackward, toggleTabFocusMode, history, historyKeymap, indentLess, indentMore, insertNewlineAndIndent, isolateHistory, redo, undo, undoDepth } from "@codemirror/commands";
 import { HighlightStyle, StreamLanguage, bracketMatching, codeFolding, foldKeymap, indentOnInput, indentUnit, syntaxHighlighting } from "@codemirror/language";
-import { json, jsonParseLinter } from "@codemirror/lang-json";
+import { json } from "@codemirror/lang-json";
 import { yaml } from "@codemirror/lang-yaml";
-import { acceptCompletion, autocompletion, closeBrackets, closeBracketsKeymap, completionKeymap, completionStatus, moveCompletionSelection, startCompletion } from "@codemirror/autocomplete";
+import { acceptCompletion, autocompletion, closeBrackets, closeBracketsKeymap, completionKeymap, completionStatus, currentCompletions, deleteBracketPair, hasNextSnippetField, hasPrevSnippetField, moveCompletionSelection, nextSnippetField, prevSnippetField, startCompletion } from "@codemirror/autocomplete";
 import { highlightSelectionMatches, search, searchKeymap } from "@codemirror/search";
-import { linter } from "@codemirror/lint";
 import { tags } from "@lezer/highlight";
 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 {a11yExtension,createAnnouncer} from './source-a11y.js';
+import { forEachDiagnostic } from "@codemirror/lint";
+import {createDiagnostics,editsTransaction} from './source-diagnostics.js';
 const external = Annotation.define();
 const hoverField = StateEffect.define();
 const activeField = StateField.define({ create: () => null, update: (value, tr) => tr.effects.reduce((value2, effect) => effect.is(hoverField) ? effect.value : value2, value) });
@@ -69,7 +71,7 @@ const markdownLanguage = StreamLanguage.define({
 function languageExtension(name, completions) {
   if (name === "yaml") return yaml();
   if (name === "markdown") return markdownLanguage;
-  return [json(), linter(jsonParseLinter(), { delay: 500 }), fieldDecorations, completions ?? []];
+  return [json(), fieldDecorations, completions ?? []];
 }
 // Tab or Enter pressed right after a keystroke can arrive before the completion query that keystroke started has answered (with the data
 // loaded it answers within a task or two). Accepting then waits for the answer instead of inserting whitespace or a line over a list that is
@@ -77,7 +79,7 @@ function languageExtension(name, completions) {
 function acceptOrFallBack(isReady, fallback) {
   return (view) => {
     if (acceptCompletion(view)) return true;
-    if (completionStatus(view.state) !== "pending" || !isReady()) return false;
+    if (completionStatus(view.state) !== "pending" || !isReady()) return fallback(view);
     let tries = 0;
     const settle = () => {
       if (!view.dom.isConnected) return;
@@ -88,37 +90,69 @@ function acceptOrFallBack(isReady, fallback) {
     return true;
   };
 }
-// Completion keys, as in VS Code: Tab and Enter accept the selected suggestion, Escape closes the list, Ctrl+Space (and Cmd+I on macOS) opens it
-// wherever the schema has something to offer, and the arrows, the Page keys and Ctrl+N and Ctrl+P (macOS) move the selection. Without a list,
-// none of them is taken: Tab then inserts whitespace and Enter inserts a line.
-function completionKeys(isReady) {
+// The documentation panel beside the selected item is shown by default (VS Code's `suggest.showInlineDetails`); Ctrl+Space with the list open
+// hides or shows it (`toggleSuggestionDetails`). The choice is the editor's, not the list's, so it stays across lists.
+function toggleDocs(view) {
+  const hidden = view.dom.classList.toggle("opf-docs-off");
+  view.dom.dataset.opfDocs = hidden ? "off" : "on";
+  return true;
+}
+const listIsOpen = (state) => completionStatus(state) === "active" && currentCompletions(state).length > 0;
+// Left and Right inside the word being completed move the caret and keep the list, which then filters by the text before the caret (VS Code).
+// A move that leaves the word (or the line) is the plain move, which closes the list. The move is dispatched as typing without a change, which
+// is the one transaction the completion state keeps its result for.
+function moveInToken(forward, tokenOf) {
+  return (view) => {
+    const { state } = view, range = state.selection.main;
+    if (!listIsOpen(state) || state.selection.ranges.length !== 1 || !range.empty) return false;
+    const target = view.moveByChar(range, forward);
+    if (target.head === range.head) return false;
+    const text = state.doc.toString(), here = tokenOf(text, range.head), there = tokenOf(text, target.head);
+    if (!here || !there || here.start !== there.start) return false;
+    view.dispatch({ selection: { anchor: target.head }, userEvent: "input.type", scrollIntoView: true });
+    // Ask again at the new caret, so the list filters by the text before it.
+    startCompletion(view);
+    return true;
+  };
+}
+// Backspace with the list open deletes and asks again, so the list widens as the word shrinks (the completion state alone closes the list
+// when the caret goes back past the place it was opened).
+function backspaceInToken(tokenOf) {
+  return (view) => {
+    if (!listIsOpen(view.state) || view.state.selection.ranges.length !== 1 || !view.state.selection.main.empty) return false;
+    if (!(deleteBracketPair(view) || deleteCharBackward(view))) return false;
+    const { state } = view;
+    if (tokenOf(state.doc.toString(), state.selection.main.head)) startCompletion(view);
+    return true;
+  };
+}
+// Completion keys, as in VS Code: Tab and Enter accept the selected suggestion (Shift+Tab and Shift+Enter accept it too: in a JSON string the
+// accepted item always replaces the whole token), Escape closes the list, Ctrl+Space (and Cmd+I on macOS) opens it wherever the schema has
+// something to offer and, with the list open, shows or hides its documentation, and the arrows, the Page keys and Ctrl+N and Ctrl+P (macOS)
+// move the selection. Without a list, none of them is taken: Tab then inserts whitespace (or walks the stops of a snippet) and Enter inserts
+// a line.
+function completionKeys(isReady, tokenOf, onStep) {
+  // Tab and Shift+Tab walk the tab stops of a snippet; the engine says which stop it is and opens the list at a stop that is a choice.
+  const walk = (forward, fallback) => (view) => {
+    if (forward ? hasNextSnippetField(view.state) && nextSnippetField(view) : hasPrevSnippetField(view.state) && prevSnippetField(view)) { onStep(view, forward); return true; }
+    return fallback(view);
+  };
+  const enter = (view) => nextStringItem(view) || insertNewlineAndIndent(view);
   return Prec.highest(keymap.of([
-    ...completionKeymap.filter((binding) => binding.key !== "Enter"),
-    { key: "Enter", run: acceptOrFallBack(isReady, (view) => nextStringItem(view) || insertNewlineAndIndent(view)) },
-    { key: "Tab", run: acceptOrFallBack(isReady, tabCommand) },
+    ...completionKeymap.filter((binding) => binding.key !== "Enter" && binding.key !== "Ctrl-Space"),
+    { key: "Ctrl-Space", run: (view) => (listIsOpen(view.state) ? toggleDocs(view) : startCompletion(view)) },
+    { key: "Enter", run: acceptOrFallBack(isReady, enter) },
+    { key: "Shift-Enter", run: acceptOrFallBack(isReady, insertNewlineAndIndent) },
+    { key: "Tab", run: acceptOrFallBack(isReady, walk(true, tabCommand)) },
+    { key: "Shift-Tab", run: acceptOrFallBack(isReady, walk(false, indentLess)) },
+    { key: "ArrowLeft", run: moveInToken(false, tokenOf) },
+    { key: "ArrowRight", run: moveInToken(true, tokenOf) },
+    { key: "Backspace", run: backspaceInToken(tokenOf) },
     { mac: "Mod-i", run: startCompletion },
     { mac: "Ctrl-n", run: moveCompletionSelection(true) },
     { mac: "Ctrl-p", run: moveCompletionSelection(false) },
   ]));
 }
-// Accept a completion by rewriting its whole token (quotes included), so a string key, a bare word and a changed value type all land
-// as valid JSON. A key adds ": " when none follows and then offers the values of that key. The quotes are read from the text when the
-// completion is applied, because the list is reused while the author keeps typing the same token.
-function completionApply(found, option) {
-  return (view, completion, from, to) => {
-    const { state } = view;
-    const start = found.quoted && state.sliceDoc(from - 1, from) === '"' ? from - 1 : from;
-    const end = found.quoted && state.sliceDoc(to, to + 1) === '"' ? to + 1 : to;
-    let insert = JSON.stringify(option.value);
-    const chain = found.kind === "key" && !/^\s*:/.test(state.sliceDoc(end, Math.min(state.doc.length, end + 200)));
-    if (chain) insert += ": ";
-    view.dispatch({ changes: { from: start, to: end, insert }, selection: { anchor: start + insert.length }, userEvent: "input.complete", scrollIntoView: true });
-    if (chain) setTimeout(() => startCompletion(view), 0);
-  };
-}
-// A quoted token keeps its list for any text between the quotes; a bare word for word characters only.
-const QUOTED_TEXT = /^[^"\\\n\r]*$/;
-const WORD_TEXT = /^[A-Za-z0-9_.-]*$/;
 const DEFAULT_INDENT = "  ";
 const tabWidth = (unit) => (unit === "\t" ? 4 : unit.length);
 // Tab without a completion list (VS Code's `tab`): whitespace goes in at the caret, up to the next tab stop, and replaces a selection inside
@@ -248,21 +282,41 @@ function mountJsonCodeEditor(parent, options) {
       menu=mountJsonFieldMenu(parent,api,catalogs,left,top,()=>{menu=null;});
     }catch(error){options.onError?.(error);}
   }
-  // Live completions (JSON only, `completions: true`): property names and values at the cursor's JSON path, from the same data as the field
-  // menu. The data loads with the field menu's chunk, at the first focus or the first query; once loaded, a query answers at once (no
-  // promise), and the list stays valid while the author types within the same token (`validFor`), so typing only refilters it.
+  // Live completions (JSON only, `completions: true`): property names and values at the cursor's JSON path, from the schema and the catalogs, with
+  // templates and snippets (source-completions.js). The engine loads at the first focus or the first query; once loaded, a query answers at once
+  // (no promise), and the list stays valid while the author types within the same token (`validFor`), so typing only refilters it.
   let optionsModule = null, optionsLoading = null;
-  const loadOptions = () => (optionsLoading ??= import('./json-options.js').then((module) => (optionsModule = module), (error) => { optionsLoading = null; throw error; }));
+  const loadOptions = () => (optionsLoading ??= import('./source-completions.js').then((module) => (optionsModule = module), (error) => { optionsLoading = null; throw error; }));
+  const applyOption = (target, completion, from, to) => optionsModule.applyCompletion(target, completion, from, to, say);
+  // Hover: the schema's words over a key, the record's over a catalog id. A problem under the pointer is the lint tooltip's (message, next, fixes).
+  const problemAt = (state, position) => { let hit = false; forEachDiagnostic(state, (_diagnostic, from, to) => { if (position >= from && position <= to) hit = true; }); return hit; };
+  const hoverExtension = options.hover === false ? [] : hoverTooltip(async (target, position) => {
+    if (disposed || languageName !== "json" || problemAt(target.state, position)) return null;
+    if (!optionsModule) { try { await loadOptions(); } catch { return null; } }
+    return optionsModule.hoverAt(target.state, position, { catalogs });
+  }, { hoverTime: 300 });
+  // Cmd/Ctrl+K Cmd/Ctrl+I shows the hover at the caret (VS Code), and says what it holds.
+  let chordStartedAt = 0;
+  const showHoverAtCaret = (target) => {
+    if (languageName !== "json" || options.hover === false) return false;
+    const run = () => {
+      const position = target.state.selection.main.head;
+      const found = optionsModule.hoverModelAt(target.state, position, { catalogs });
+      if (!found) { say("No hover information here"); return; }
+      activateHover(target, found.from, 1, { tooltip: hoverExtension, until: (tr) => tr.docChanged || (tr.selection !== undefined && tr.newSelection.main.head !== position) });
+      say(optionsModule.docText(found.model));
+    };
+    if (optionsModule) run(); else loadOptions().then(run, () => {});
+    return true;
+  };
   function completionResult(context) {
-    const found = optionsModule.getJsonCompletions(context.state.doc.toString(), context.pos, catalogs, { explicit: context.explicit });
+    const found = optionsModule.completionResult(context.state, context.pos, { explicit: context.explicit, catalogs });
     if (!found) return null;
-    return { from: found.from, to: found.to, filter: true, validFor: found.quoted ? QUOTED_TEXT : WORD_TEXT, options: found.options.map((option) => ({
-      label: option.label, detail: option.detail, info: option.info, boost: option.boost, type: found.kind === "key" ? "property" : "enum", apply: completionApply(found, option),
-    })) };
+    for (const option of found.options) option.apply = applyOption;
+    return found;
   }
   function completionSource(context) {
-    // One list for one cursor: with several, Tab and Enter keep their plain meaning at every cursor instead of completing at the main one only.
-    if (disposed || languageName !== "json" || context.state.selection.ranges.length > 1) return null;
+    if (disposed || languageName !== "json" || context.state.readOnly) return null;
     if (optionsModule) return completionResult(context);
     return loadOptions().then(() => (disposed || context.aborted ? null : completionResult(context)), (error) => { options.onError?.(error); return null; });
   }
@@ -271,12 +325,42 @@ function mountJsonCodeEditor(parent, options) {
   const redoCommand = (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).
-  const completionExtension = options.completions ? [autocompletion({ override: [completionSource], defaultKeymap: false, icons: false, maxRenderedOptions: 60, interactionDelay: 0, activateOnTypingDelay: 0 }), completionKeys(() => optionsModule !== null)] : null;
+  // Screen reader announcements and the problems drawn in the text (squiggles, F8, Cmd/Ctrl+.). The pane supplies the problems.
+  const announcer = createAnnouncer(parent, options.announce);
+  const say = (message) => announcer.say(message);
+  const applyProblemFix = (fix, problem) => {
+    if (disposed || view.state.readOnly) return;
+    if (typeof fix.run === "function") { fix.run(api, problem); return; }
+    if (fix.edits?.length) {
+      view.dispatch(editsTransaction(view.state, api.getValue(), fix.edits, { caret: fix.caret, select: fix.select }));
+      view.focus();
+      say(`${fix.title} applied`);
+    }
+  };
+  const diagnostics = createDiagnostics({ getSource: () => view.state.field(jsonSource), say, applyFix: applyProblemFix });
+  // On its own (no source pane to supply the problems) the editor underlines the syntax errors of JSON: one per cause, 300 ms after the last key.
+  let syntaxTimer = null;
+  function scheduleSyntax() {
+    if (options.syntaxProblems === false) return;
+    clearTimeout(syntaxTimer);
+    syntaxTimer = setTimeout(async () => {
+      if (disposed || languageName !== "json") return;
+      try {
+        const { analyzeSyntax } = await import('./source-syntax.js');
+        if (disposed || languageName !== "json") return;
+        const source = api.getValue();
+        diagnostics.draw(view, analyzeSyntax(source).map((problem) => ({ from: problem.range.from, to: problem.range.to, severity: "error", message: problem.message, next: problem.next, rule: problem.ruleId,
+          fixes: (problem.editFixes ?? []).filter((fix) => !fix.action).map((fix) => ({ id: fix.id, title: fix.title, safe: fix.safe, edits: fix.edits, caret: fix.caret })) })));
+      } catch (error) { options.onError?.(error); }
+    }, 300);
+  }
+  const completionExtension = options.completions ? [autocompletion({ override: [completionSource], defaultKeymap: false, icons: false, maxRenderedOptions: 60, interactionDelay: 0, activateOnTypingDelay: 0 }), completionKeys(() => optionsModule !== null, (text, position) => optionsModule?.tokenAt(text, position, false), (target, forward) => optionsModule?.snippetStep(target, forward, { say }))] : null;
   const contentAttributes = (invalid = options.invalid, describedBy = options.describedBy) => EditorView.contentAttributes.of({
     "aria-label": options.label,
     "aria-invalid": String(Boolean(invalid)),
     "aria-describedby": describedBy ?? "",
-    "aria-keyshortcuts": options.completions ? "Control+Space" : "Control+Space Alt+Shift+O",
+    "aria-keyshortcuts": options.completions ? "Control+Space F8 Shift+F8 Control+Period Alt+Shift+F" : "Control+Space Alt+Shift+O Alt+Shift+F",
+    "aria-description": options.completions ? "Press Control+Space for suggestions. Press F8 for the next problem. Press Escape then Tab to leave the editor." : "Press Escape then Tab to leave the editor.",
     spellcheck: "false",
     autocapitalize: "off",
     autocorrect: "off"
@@ -290,7 +374,14 @@ function mountJsonCodeEditor(parent, options) {
   // The field menu: Alt+Shift+O, a chord VS Code does not use.
   const isOptionsKey = (event) => event.altKey && event.shiftKey && !event.metaKey && !event.ctrlKey && letter(event, "o");
   const view = new EditorView({ parent, state: EditorState.create({ doc: options.code, extensions: [
+    // The problem menu's keys come before the list's: the two are never open together, and Enter must reach whichever is.
+    diagnostics.extension,
     language.of(languageExtension(languageName, completionExtension)),
+    hoverExtension,
+    Prec.high(keymap.of([
+      { key: "Escape", run: (target) => (hasHoverTooltips(target.state) ? (target.dispatch({ effects: closeHoverTooltips }), true) : false) },
+    ])),
+    a11yExtension(announcer, (completion) => completion.opfDoc ?? (typeof completion.info === "string" ? completion.info : "")),
     editable.of(editableExtension(options.readOnly)),
     jsonSource.init(()=>options.code),jsonSourceHistory,
     indent.of(indentExtension(languageName)),
@@ -323,6 +414,16 @@ function mountJsonCodeEditor(parent, options) {
         redoCommand(view);
         return true;
       }
+      // Cmd/Ctrl+K then Cmd/Ctrl+I (within two seconds) shows the hover at the caret. It is read here, not as a CodeMirror chord, because a chord
+      // that starts with Mod+K would also swallow Mod+Shift+K (delete line).
+      const mod = /Mac|iPhone|iPad/.test(navigator.platform) ? event.metaKey : event.ctrlKey;
+      if (mod && !event.altKey && !event.shiftKey && event.key.toLowerCase() === "k") { chordStartedAt = Date.now(); event.preventDefault(); return true; }
+      else if (mod && !event.altKey && !event.shiftKey && event.key.toLowerCase() === "i" && Date.now() - chordStartedAt < 2000) {
+        chordStartedAt = 0;
+        if (showHoverAtCaret(view)) { event.preventDefault(); return true; }
+      }
+      // The problems panel: Cmd+Shift+M on macOS, Ctrl+Shift+M elsewhere (read from the physical key, as the format chord is).
+      if (mod && event.shiftKey && !event.altKey && event.code === "KeyM" && options.onFocusProblems?.()) { event.preventDefault(); return true; }
       if (isFormatKey(event)) {
         event.preventDefault();
         runFormat();
@@ -343,6 +444,10 @@ function mountJsonCodeEditor(parent, options) {
       // it is also on Ctrl+Space, because the list is not there to take that key.
       ...(options.completions ? [] : [{ key: "Ctrl-Space", run: () => languageName === "json" && (void openOptions(), true) }, { key: "Mod-Space", run: () => languageName === "json" && (void openOptions(), true) }]),
       { key: "Tab", run: tabCommand, shift: indentLess },
+      // The problems panel (VS Code: Cmd+Shift+M on macOS, Ctrl+Shift+M elsewhere); Ctrl+M (Ctrl+Shift+M on macOS) is VS Code's switch for Tab leaving the editor.
+      // JSON has no comments: say so instead of doing nothing (YAML and Markdown comment their lines out).
+      { key: "Mod-/", run: () => { if (languageName !== "json") return false; say("JSON has no comments. Use YAML or Markdown for notes."); return true; } },
+      { key: "Ctrl-m", mac: "Ctrl-Shift-m", run: toggleTabFocusMode },
       ...closeBracketsKeymap,
       ...defaultKeymap,
       ...historyBindings,
@@ -373,6 +478,7 @@ function mountJsonCodeEditor(parent, options) {
       const busy = completionStatus(update.state) === "pending", dom = update.view.dom;
       if (busy !== (dom.dataset.opfBusy === "1")) { if (busy) dom.dataset.opfBusy = "1"; else delete dom.dataset.opfBusy; }
       if (update.docChanged && !update.transactions.every((tr) => tr.annotation(external))) options.onChange(update.state.field(jsonSource));
+      if (update.docChanged) scheduleSyntax();
     })
   ] }) });
   const api = {
@@ -393,6 +499,15 @@ function mountJsonCodeEditor(parent, options) {
     },
     /** The indentation unit now in effect: a tab character or some spaces. */
     indentUnit: () => view.state.facet(indentUnit),
+    /** Say `message` in the editor's live region. */
+    say,
+    /**
+     * Apply several edits as one undoable change. `edits` are `{ from, to, insert }` in source offsets of the text as it is now; `caret` (or
+     * `select: [from, to]`) is a position in the text after the edits.
+     */
+    applyEdits(edits, { caret, select, userEvent } = {}) {
+      view.dispatch(editsTransaction(view.state, api.getValue(), edits, { caret, select, userEvent }));
+    },
     coordinates: () => {
       const rect = view.coordsAtPos(view.state.selection.main.head) ?? parent.getBoundingClientRect();
       return { left: rect.left, top: rect.bottom + 8 };
@@ -434,6 +549,23 @@ function mountJsonCodeEditor(parent, options) {
     api,
     openOptions,
     setCatalogs(value){catalogs=value??[];closeOptions();},
+    /**
+     * Draw the problems in the text: `{ from, to, severity, message, next?, rule?, fixes? }` with source offsets into the current text. A fix is
+     * `{ id, title, safe?, edits?, caret?, select?, run? }`.
+     */
+    setProblems(problems){if(!disposed)diagnostics.draw(view,problems??[]);},
+    /** The problems drawn now, in position order, at their current source offsets. */
+    getProblems:()=>diagnostics.problems(view).map(({diagnostic,...problem})=>problem),
+    nextProblem:()=>diagnostics.next(view),
+    previousProblem:()=>diagnostics.previous(view),
+    /** Open the quick fix list for the problems at the caret (Cmd/Ctrl+.). */
+    triggerQuickFix:()=>diagnostics.openMenu(view),
+    /** Open the suggestion list at the caret (Ctrl+Space). */
+    triggerCompletion:()=>startCompletion(view),
+    /** Whether a suggestion list is open or being asked for. */
+    isCompleting:()=>completionStatus(view.state)!==null,
+    /** Perform a fix (its edits as one undoable change, or its own action). */
+    applyFix:(fix,problem)=>applyProblemFix(fix,problem),
     /** Switch the highlighting between "json" (with its parse linter, field highlights and option menu), "yaml" and "markdown". */
     setLanguage(name){
       if(name===languageName)return;
@@ -479,7 +611,7 @@ function mountJsonCodeEditor(parent, options) {
         annotations: [external.of(true), Transaction.addToHistory.of(false)]
       });
     },
-    destroy: () => {if(disposed)return;disposed=true;closeOptions();view.destroy();}
+    destroy: () => {if(disposed)return;disposed=true;clearTimeout(syntaxTimer);closeOptions();announcer.destroy();view.destroy();}
   };
 }
 export {

package/dist/json-options.js

@@ -3,22 +3,7 @@ import { listCatalogRecords } from "./catalogs.js";
 import { resolveSchema, schemaAtPath, schemaVariants } from "./schema.js";
 import { findNodeAtOffset, getNodePath, parse as parseJsonc, parseTree } from "jsonc-parser";
 import { LAYOUT_INTENT_GROUPS, layoutRegionSummary } from "./layout-templates.js";
-// The catalog kind a field references (OPF 0.15: every content kind is `id` or `name:id`), read from where the field sits.
-const ROOT_REFERENCES = { narrative: "narratives", audience: "audiences", purpose: "purposes", tone: "tones" };
-const DESIGN_REFERENCES = { theme: "themes", colorScheme: "colorSchemes", fontScheme: "fontSchemes" };
-function catalogAtPath(path) {
-    const parts = path.map(String);
-    // A reference's object form names its record with `id`; an audience array's entries are references too.
-    const field = parts.at(-1) === "id" ? parts.slice(0, -1) : parts;
-    const tail = /^\d+$/.test(field.at(-1) ?? "") && field.at(-2) === "audience" ? field.slice(0, -1) : field;
-    const key = tail.at(-1);
-    if (tail.length === 3 && tail[0] === "slides" && key === "layout") return "layouts";
-    if (tail.length === 1 && ROOT_REFERENCES[key]) return ROOT_REFERENCES[key];
-    if (DESIGN_REFERENCES[key] && ((tail.length === 2 && tail[0] === "design") || (tail.length === 4 && tail[0] === "slides" && tail[2] === "design"))) return DESIGN_REFERENCES[key];
-    // Inside an embedded record: a theme's colour or font scheme.
-    if (tail.length === 5 && tail[0] === "catalogs" && tail[2] === "themes" && (key === "colorScheme" || key === "fontScheme")) return DESIGN_REFERENCES[key];
-    return undefined;
-}
+import { catalogKindAt } from "@openpresentation/opf/schema";
 const sourceDetails = {
     "Loaded catalog": ["Provided by app", "Records from a catalog this app registered; nothing is fetched from a URL. Saving embeds the record in the document."],
     "Document catalog": ["In this document", "Embedded in this document’s catalogs. Takes precedence over the app’s records with the same reference."],
@@ -44,7 +29,8 @@ function describeOptions(choices, records, current, catalog) {
 function fieldOptions(presentation, path, loadedCatalogs, { string, boolean }) {
     const schema = schemaAtPath(presentation, path.map(String));
     const variants = schemaVariants(schema);
-    const catalog = catalogAtPath(path);
+    // A reference's object form names its record with `id`: the field is the reference.
+    const segments = path.map(String), catalog = catalogKindAt(segments.at(-1) === "id" ? segments.slice(0, -1) : segments, presentation);
     const options = new Map();
     const records = new Map();
     // A document group whose source no registered catalog matches: its records beyond the embedded ones are not available here.
@@ -136,7 +122,7 @@ export function fieldOptionEdit(context, value) {
 const PLACEHOLDER = "__opf_completion__";
 const WORD = /[A-Za-z0-9_.-]/;
 // The token being typed: inside a string (a quote opened earlier on this line) or a bare word. JSON strings never span lines.
-function tokenAt(text, position, explicit) {
+export function tokenAt(text, position, explicit) {
     const lineStart = Math.max(text.lastIndexOf("\n", position - 1), text.lastIndexOf("\r", position - 1)) + 1;
     let open = -1, last = null;
     for (let index = lineStart; index < position; index++) {