@openpresentation/opf-editor 0.24.0 → 0.24.2

package/dist/json-options.js

@@ -1,7 +1,7 @@
 import { checkFormat, firstErrorMessage } from "./checks.js";
 import { listCatalogRecords } from "./catalogs.js";
-import { schemaAtPath, schemaVariants } from "./schema.js";
-import { findNodeAtOffset, getNodePath, parseTree } from "jsonc-parser";
+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" };
@@ -39,29 +39,9 @@ function describeOptions(choices, records, current, catalog) {
     const priority = option => option.source === "Document catalog" ? 2 : option.source === "Loaded catalog" ? 1 : 0;
     return choices.sort((a, b) => (catalog === "layouts" ? layoutGroups.indexOf(a.layoutGroup) - layoutGroups.indexOf(b.layoutGroup) : priority(b) - priority(a)) || a.label.localeCompare(b.label, "en", {numeric: true}) || String(a.value).localeCompare(String(b.value), "en"));
 }
-// The installed schema identifies fields; a document field merely named "layout"
-// inside arbitrary metadata is not mistaken for an OPF layout reference.
-export function getJsonFieldContext(source, position, loadedCatalogs = []) {
-    let presentation;
-    try {
-        presentation = JSON.parse(source);
-    }
-    catch {
-        return null;
-    }
-    const root = parseTree(source);
-    if (!root)
-        return null;
-    let node = findNodeAtOffset(root, position, true);
-    if (node?.parent?.type === "property" && node.parent.children?.[0] === node)
-        node = node.parent.children[1];
-    if (node?.type === "object")
-        node = node.children?.find(property => property.children?.[0]?.value === "id")?.children?.[1];
-    if (!node || !["string", "number", "boolean"].includes(node.type))
-        return null;
-    const path = getNodePath(node);
-    if (!path.length)
-        return null;
+// The choices a field offers, shared by the field menu and live completions: catalog records for a reference field (when the
+// value is a string), schema enum values and booleans otherwise.
+function fieldOptions(presentation, path, loadedCatalogs, { string, boolean }) {
     const schema = schemaAtPath(presentation, path.map(String));
     const variants = schemaVariants(schema);
     const catalog = catalogAtPath(path);
@@ -70,7 +50,7 @@ export function getJsonFieldContext(source, position, loadedCatalogs = []) {
     // A document group whose source no registered catalog matches: its records beyond the embedded ones are not available here.
     const registered = new Set((Array.isArray(loadedCatalogs) ? loadedCatalogs : []).map(entry => entry?.source));
     const unloadedSource = Boolean(catalog) && Object.entries(presentation.catalogs ?? {}).some(([name, group]) => name !== "custom" && group && typeof group === "object" && typeof group.source === "string" && !registered.has(group.source));
-    if (catalog && typeof node.value === "string") {
+    if (catalog && string) {
         const hostCatalogs = Array.isArray(loadedCatalogs) ? loadedCatalogs : [];
         // A draft whose own catalogs are malformed still offers the host's records; a malformed host list offers nothing.
         const attempt = (document) => { try { return listCatalogRecords(document, catalog, { catalogs: hostCatalogs }); } catch { return undefined; } };
@@ -87,11 +67,37 @@ export function getJsonFieldContext(source, position, loadedCatalogs = []) {
                 if (["string", "number", "boolean"].includes(typeof value))
                     options.set(JSON.stringify(value), { value, label: String(value), source: "Schema" });
             }
-        if (node.type === "boolean" && variants.some(variant => variant.type === "boolean" && variant.const === undefined)) {
+        if (boolean && variants.some(variant => variant.type === "boolean" && variant.const === undefined)) {
             for (const value of [true, false])
                 options.set(String(value), { value, label: String(value), source: "Schema" });
         }
     }
+    return { options, records, catalog, unloadedSource };
+}
+// The installed schema identifies fields; a document field merely named "layout"
+// inside arbitrary metadata is not mistaken for an OPF layout reference.
+export function getJsonFieldContext(source, position, loadedCatalogs = []) {
+    let presentation;
+    try {
+        presentation = JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+    const root = parseTree(source);
+    if (!root)
+        return null;
+    let node = findNodeAtOffset(root, position, true);
+    if (node?.parent?.type === "property" && node.parent.children?.[0] === node)
+        node = node.parent.children[1];
+    if (node?.type === "object")
+        node = node.children?.find(property => property.children?.[0]?.value === "id")?.children?.[1];
+    if (!node || !["string", "number", "boolean"].includes(node.type))
+        return null;
+    const path = getNodePath(node);
+    if (!path.length)
+        return null;
+    const { options, records, catalog, unloadedSource } = fieldOptions(presentation, path, loadedCatalogs, { string: typeof node.value === "string", boolean: node.type === "boolean" });
     if (!options.size)
         return null;
     const choices = [...options.values()];
@@ -122,3 +128,97 @@ export function fieldOptionEdit(context, value) {
     while (to > from && end > from && source[to - 1] === next[end - 1]) { to--; end--; }
     return {from, to, insert: next.slice(from, end)};
 }
+
+// ---- Live completions ----------------------------------------------------------------------------------------------------------
+// What the editor offers while you type: the property names the schema allows at the cursor's object, and the same enum, boolean and
+// catalog choices the field menu lists at a value. The draft is usually not valid JSON mid-keystroke, so the token under the cursor
+// is swapped for a placeholder string and the rest is read with the tolerant parser.
+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) {
+    const lineStart = Math.max(text.lastIndexOf("\n", position - 1), text.lastIndexOf("\r", position - 1)) + 1;
+    let open = -1;
+    for (let index = lineStart; index < position; index++) {
+        if (open >= 0) { if (text[index] === "\\") index++; else if (text[index] === '"') open = -1; }
+        else if (text[index] === '"') open = index;
+    }
+    if (open >= 0) {
+        let close = -1;
+        for (let index = position; index < text.length && text[index] !== "\n" && text[index] !== "\r"; index++) {
+            if (text[index] === "\\") index++;
+            else if (text[index] === '"') { close = index; break; }
+        }
+        return { quoted: true, closed: close >= 0, start: open, end: close >= 0 ? close + 1 : position, from: open + 1, to: close >= 0 ? close : position };
+    }
+    let start = position, end = position;
+    while (start > lineStart && WORD.test(text[start - 1])) start--;
+    while (end < text.length && WORD.test(text[end])) end++;
+    if (start === position && !explicit) return null;
+    let before = start - 1;
+    while (before >= lineStart && /\s/.test(text[before])) before--;
+    // A bare word starts a key or a value only after `{`, `,`, `:` or `[` (or at the start of an empty line).
+    const previous = before >= lineStart ? text[before] : (text.slice(0, lineStart).trimEnd().at(-1) ?? "");
+    if (!["{", ",", ":", "["].includes(previous)) return null;
+    return { quoted: false, closed: false, start, end, from: start, to: end };
+}
+
+// Schema descriptions run to paragraphs; the popup shows the first sentence, at most 200 characters.
+function brief(text) {
+    if (typeof text !== "string" || !text.trim()) return undefined;
+    const flat = text.replace(/\s+/g, " ").trim();
+    const sentence = /^.*?[.!?](?=\s|$)/.exec(flat)?.[0] ?? flat;
+    return sentence.length <= 200 ? sentence : `${sentence.slice(0, 199).trimEnd()}…`;
+}
+
+/**
+ * The completions at `position` of a JSON draft (it need not parse): `{ kind: "key" | "value", from, to, quoted, closed, options }`,
+ * or null when nothing is offered. `from` and `to` bound the text being typed (inside the quotes of a string); each option is
+ * `{ value, label, detail?, info?, boost }`. A key option's `value` is the property name; a value option's is the JSON value.
+ * `explicit` also offers choices where nothing has been typed yet.
+ */
+export function getJsonCompletions(source, position, loadedCatalogs = [], { explicit = false } = {}) {
+    const token = tokenAt(source, position, explicit);
+    if (!token) return null;
+    const draft = source.slice(0, token.start) + JSON.stringify(PLACEHOLDER) + source.slice(token.end);
+    const root = parseTree(draft, [], { allowTrailingComma: true });
+    if (!root) return null;
+    const node = findNodeAtOffset(root, token.start + 1, true);
+    if (node?.type !== "string" || node.value !== PLACEHOLDER) return null;
+    const presentation = parseJsonc(draft, [], { allowTrailingComma: true });
+    if (presentation === null || typeof presentation !== "object" || Array.isArray(presentation)) return null;
+    const range = { from: token.from, to: token.to, quoted: token.quoted, closed: token.closed };
+    try {
+        if (node.parent?.type === "property" && node.parent.children?.[0] === node) {
+            const object = node.parent.parent;
+            const present = new Set((object?.children ?? []).filter(property => property !== node.parent).map(property => property.children?.[0]?.value));
+            const properties = new Map();
+            for (const variant of schemaVariants(schemaAtPath(presentation, getNodePath(object).map(String))))
+                for (const [key, child] of Object.entries(variant.properties ?? {}))
+                    if (!present.has(key) && !properties.has(key)) properties.set(key, { child, required: (variant.required ?? []).includes(key) });
+            if (!properties.size) return null;
+            const options = [...properties].map(([key, { child, required }], index) => {
+                const resolved = resolveSchema(child);
+                const type = Array.isArray(resolved.type) ? resolved.type.join(" | ") : resolved.type ?? (resolved.enum ? "enum" : resolved.oneOf || resolved.anyOf ? "choice" : "");
+                return { value: key, label: key, detail: type || undefined, info: brief(child.description ?? resolved.description), boost: Math.max(-99, (required ? 50 : 0) - index) };
+            });
+            return { kind: "key", ...range, options };
+        }
+        const path = getNodePath(node);
+        if (!path.length) return null;
+        const { options: found, records, catalog } = fieldOptions(presentation, path, loadedCatalogs, { string: true, boolean: true });
+        if (!found.size) return null;
+        const choices = describeOptions([...found.values()], records, undefined, catalog);
+        const options = choices.map((option, index) => ({
+            value: option.value,
+            label: String(option.value),
+            detail: String(option.label) !== String(option.value) ? String(option.label) : option.sourceLabel,
+            info: [brief(option.description), option.regions].filter(Boolean).join("\n") || undefined,
+            boost: Math.max(-99, 50 - index),
+        }));
+        return { kind: "value", ...range, options };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/json-source.js

@@ -6,7 +6,8 @@ import {textInputMap,preferredLineEnding} from './text-input.js';
 // field, and store only removed newline spellings in its existing undo history.
 export const setJsonSource=StateEffect.define();
 const restoreEndings=StateEffect.define({map:(endings,changes)=>{
-  const mapped=endings.map(({position,ending})=>({position:changes.mapPos(position,1,MapMode.TrackDel),ending})).filter(item=>item.position!==null);
+  // A position past the end of the changed document (the text was deleted, then replaced from outside) cannot be placed: drop it.
+  const mapped=endings.map(({position,ending})=>({position:position<=changes.length?changes.mapPos(position,1,MapMode.TrackDel):null,ending})).filter(item=>item.position!==null);
   return mapped.length?mapped:undefined;
 }});
 export const jsonSource=StateField.define({

package/dist/slide-navigator.d.ts

@@ -0,0 +1,44 @@
+import type { EditorSession } from "./index.js";
+
+export interface SlideNavigatorLabels {
+  /** The accessible name of the control group. Default: "Slide navigation". */
+  navigation?: string;
+  /** Default: "Previous slide". */
+  previous?: string;
+  /** Default: "Next slide". */
+  next?: string;
+  /** The tooltip of the counter, for example "Slide 2 of 3". */
+  position?: (index: number, count: number) => string;
+}
+export interface SlideNavigatorOptions {
+  /** The editor session. The slide count follows it. */
+  editor?: EditorSession;
+  /** Without an editor: an OPF presentation, or a function returning the current one. Call `refresh()` after it changes. */
+  presentation?: { slides?: unknown[] } | (() => { slides?: unknown[] });
+  /** The slide shown first (0-based). Default 0. */
+  slideIndex?: number;
+  /** Called with the new index when the user moves, and when a shrinking deck clamps the index. Not called by `setSlide`. */
+  onChange?: (index: number) => void;
+  /** `"comfortable"` (32px controls, default) or `"touch"` (40px). */
+  density?: "comfortable" | "touch";
+  labels?: SlideNavigatorLabels;
+  /** False to stop following the editor on its own; call `refresh()` yourself. Default true. */
+  autoRefresh?: boolean;
+}
+export interface SlideNavigator {
+  readonly element: HTMLElement;
+  getSlide(): number;
+  /** Show another slide (clamped to the deck) without calling `onChange`. */
+  setSlide(index: number): void;
+  /** Read the slide count again. */
+  refresh(): void;
+  /**
+   * Page-level Left and Right arrows (default target: the document). They ignore typing in inputs, selects and editors, menus, dialogs, modified keys and
+   * events another handler already handled. Returns a function that removes the listener; `destroy()` removes every one.
+   */
+  bindKeys(target?: Document | HTMLElement | Window): () => void;
+  destroy(): void;
+}
+/** The counter text, for example "01 / 03": both numbers are zero-padded to two digits, or to the width of the slide count from 100 slides. */
+export declare function formatSlideCounter(index: number, count: number): string;
+export declare function createSlideNavigator(container: HTMLElement, options?: SlideNavigatorOptions): SlideNavigator;

package/dist/slide-navigator.js

@@ -0,0 +1,191 @@
+// Slide navigator (RR-98): previous and next buttons around a mono "01 / 03" counter. It owns no document state, only the slide index the host
+// shows; the slide count follows the editor session (or a presentation the host hands in). Plain DOM, no framework, no network.
+// Icons are the Lucide ChevronLeft and ChevronRight paths (ISC license), inlined.
+const SVG_NS = "http://www.w3.org/2000/svg";
+const CHEVRONS = { previous: "m15 18-6-6 6-6", next: "m9 18 6-6-6-6" };
+
+const DEFAULT_LABELS = {
+  navigation: "Slide navigation",
+  previous: "Previous slide",
+  next: "Next slide",
+  /** The accessible description of the position, for example "Slide 2 of 3". */
+  position: (index, count) => (count === 0 ? "No slides" : `Slide ${index + 1} of ${count}`),
+};
+
+/** The counter text: both numbers are zero-padded to two digits, or to the width of the slide count from 100 slides. */
+export function formatSlideCounter(index, count) {
+  const width = Math.max(2, String(Math.max(0, count)).length);
+  const pad = (value) => String(value).padStart(width, "0");
+  return `${pad(count === 0 ? 0 : index + 1)} / ${pad(count)}`;
+}
+
+function chevron(name) {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("class", "opf-nav-icon");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  svg.setAttribute("aria-hidden", "true");
+  svg.setAttribute("focusable", "false");
+  svg.setAttribute("fill", "none");
+  svg.setAttribute("stroke", "currentColor");
+  svg.setAttribute("stroke-width", "2");
+  svg.setAttribute("stroke-linecap", "round");
+  svg.setAttribute("stroke-linejoin", "round");
+  const path = document.createElementNS(SVG_NS, "path");
+  path.setAttribute("d", CHEVRONS[name]);
+  svg.append(path);
+  return svg;
+}
+
+/** True when a page-level key press belongs to something else: typing, an editor, a menu or a dialog. */
+function isInteractiveTarget(target) {
+  if (!target || typeof target.closest !== "function") return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+  return Boolean(target.closest('[contenteditable=""],[contenteditable="true"],.cm-editor,[role="textbox"],[role="combobox"],[role="listbox"],[role="menu"],[role="slider"],[role="spinbutton"],dialog[open],[role="dialog"]'));
+}
+
+/**
+ * Mount previous and next buttons with a "01 / 03" counter into `container`.
+ *
+ * Options: `editor` (an editor session; the slide count follows it) or `presentation` (an OPF object, or a function returning the current
+ * one), `slideIndex` (0-based, default 0), `onChange(index)` (called when the user moves, and when a shrinking deck clamps the index),
+ * `density` (`"comfortable"` 32px controls, or `"touch"` 40px), `labels` (`navigation`, `previous`, `next`, `position(index, count)`) and
+ * `autoRefresh` (default true: follow the editor's changes on its own).
+ *
+ * Returns `{ element, getSlide(), setSlide(index), refresh(), bindKeys(target?), destroy() }`.
+ */
+export function createSlideNavigator(container, options = {}) {
+  if (!container?.ownerDocument) throw new TypeError("A DOM container is required.");
+  const doc = container.ownerDocument;
+  const labels = { ...DEFAULT_LABELS, ...(options.labels ?? {}) };
+  const density = options.density === "touch" ? "touch" : "comfortable";
+  const { editor } = options;
+  const source = options.presentation;
+  let index = Math.max(0, Math.trunc(Number(options.slideIndex) || 0));
+  let disposed = false;
+  const unbinders = new Set();
+
+  const count = () => {
+    // The snapshot is cached between edits; `editor.presentation` clones the whole deck on every read.
+    const deck = editor ? (editor.snapshot?.().presentation ?? editor.presentation) : typeof source === "function" ? source() : source;
+    return Array.isArray(deck?.slides) ? deck.slides.length : 0;
+  };
+
+  const element = doc.createElement("div");
+  element.className = "opf-nav";
+  element.dataset.density = density;
+  element.setAttribute("role", "group");
+  element.setAttribute("aria-label", labels.navigation);
+  const button = (name) => {
+    const node = doc.createElement("button");
+    node.type = "button";
+    node.className = "opf-nav-button";
+    node.dataset.action = name;
+    node.setAttribute("aria-label", labels[name]);
+    node.title = labels[name];
+    node.append(chevron(name));
+    return node;
+  };
+  const previous = button("previous");
+  const next = button("next");
+  const counter = doc.createElement("span");
+  counter.className = "opf-nav-counter";
+  counter.setAttribute("role", "status");
+  counter.setAttribute("aria-atomic", "true");
+  element.append(previous, counter, next);
+  container.append(element);
+
+  function clamp(value, total) {
+    return total === 0 ? 0 : Math.max(0, Math.min(total - 1, value));
+  }
+  function paint() {
+    const total = count();
+    index = clamp(index, total);
+    counter.textContent = formatSlideCounter(index, total);
+    counter.title = labels.position(index, total);
+    element.dataset.count = String(total);
+    element.dataset.index = String(index);
+    const atStart = index <= 0;
+    const atEnd = index >= total - 1;
+    // A button that becomes disabled while it has focus would drop focus to the page: hand it to the other button.
+    const focused = doc.activeElement;
+    previous.disabled = total === 0 || atStart;
+    next.disabled = total === 0 || atEnd;
+    if (focused === previous && previous.disabled && !next.disabled) next.focus();
+    else if (focused === next && next.disabled && !previous.disabled) previous.focus();
+  }
+  function go(target, notify = true) {
+    const total = count();
+    const clamped = clamp(target, total);
+    if (clamped === index) return false;
+    index = clamped;
+    paint();
+    if (notify) options.onChange?.(index);
+    return true;
+  }
+
+  previous.addEventListener("click", () => go(index - 1));
+  next.addEventListener("click", () => go(index + 1));
+  // The arrow keys act when focus is inside the navigator. preventDefault marks the event as handled so a page-level `bindKeys` does not repeat it.
+  element.addEventListener("keydown", (event) => {
+    if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey || event.isComposing) return;
+    const rtl = doc.defaultView?.getComputedStyle(element).direction === "rtl";
+    const step = { ArrowLeft: rtl ? 1 : -1, ArrowRight: rtl ? -1 : 1, ArrowUp: -1, ArrowDown: 1 }[event.key];
+    if (step !== undefined) { event.preventDefault(); go(index + step); }
+    else if (event.key === "Home") { event.preventDefault(); go(0); }
+    else if (event.key === "End") { event.preventDefault(); go(count() - 1); }
+  });
+
+  paint();
+  const unsubscribe = editor && options.autoRefresh !== false && typeof editor.subscribe === "function" ? editor.subscribe(() => refresh()) : undefined;
+
+  function refresh() {
+    if (disposed) return;
+    const before = index;
+    paint();
+    // The deck shrank under the current slide: the host's index is stale too.
+    if (index !== before) options.onChange?.(index);
+  }
+
+  /**
+   * Page-level Left and Right arrows (default target: the document). Ignores typing in inputs, selects and editors, menus, dialogs, modified keys and
+   * events another handler already took. Returns a function that removes the listener; `destroy()` removes every one.
+   */
+  function bindKeys(target = doc) {
+    const handler = (event) => {
+      if (disposed || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey || event.isComposing) return;
+      if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
+      if (isInteractiveTarget(event.target) || isInteractiveTarget(doc.activeElement)) return;
+      const rtl = doc.defaultView?.getComputedStyle(element).direction === "rtl";
+      const step = event.key === "ArrowLeft" ? (rtl ? 1 : -1) : rtl ? -1 : 1;
+      if (go(index + step)) event.preventDefault();
+    };
+    target.addEventListener("keydown", handler);
+    const unbind = () => { target.removeEventListener("keydown", handler); unbinders.delete(unbind); };
+    unbinders.add(unbind);
+    return unbind;
+  }
+
+  return {
+    element,
+    /** The slide index the navigator shows. */
+    getSlide: () => index,
+    /** Show another slide without calling `onChange` (the host already knows). */
+    setSlide(value) {
+      if (disposed) return;
+      index = clamp(Math.trunc(Number(value) || 0), count());
+      paint();
+    },
+    /** Read the slide count again (it follows the session on its own unless `autoRefresh` is false). */
+    refresh,
+    bindKeys,
+    destroy() {
+      if (disposed) return;
+      disposed = true;
+      unsubscribe?.();
+      for (const unbind of [...unbinders]) unbind();
+      element.remove();
+    },
+  };
+}

package/dist/source-findings.js

@@ -0,0 +1,27 @@
+// Findings of the source pane (RR-98), kept apart from the DOM so they can be tested alone.
+
+/** Normalize one finding: core `Finding` objects, `{ path, message, severity, line? }` objects and plain strings. */
+export function normalizeFinding(input, kind) {
+  const finding = typeof input === "string" ? { message: input } : input ?? {};
+  const severity = finding.severity === "error" || finding.severity === "info" ? finding.severity : finding.severity === "warning" || finding.severity === "warn" ? "warning" : "error";
+  const out = { path: String(finding.path ?? ""), message: String(finding.message ?? ""), severity };
+  const line = finding.line ?? finding.location?.line;
+  if (Number.isInteger(line) && line > 0) out.line = line;
+  const own = finding.kind ?? kind;
+  if (own) out.kind = own;
+  if (finding.ruleId) out.ruleId = finding.ruleId;
+  return out;
+}
+
+/** The text of the first problem an error reports. */
+export const errorText = (error) => error?.issues?.[0]?.message ?? error?.message ?? String(error);
+
+/**
+ * The findings for an edit the session refused: one per issue of the thrown error (its validator findings, each with its JSON pointer
+ * `path`), so the list has the validator's count. An error without issues becomes one finding with its message.
+ */
+export function rejectionFindings(error) {
+  const issues = Array.isArray(error?.issues) ? error.issues.filter((issue) => issue && (typeof issue === "string" || typeof issue === "object")) : [];
+  if (!issues.length) return [normalizeFinding({ message: errorText(error) }, "rejected")];
+  return issues.map((issue) => normalizeFinding(typeof issue === "string" ? issue : { ...issue, severity: issue.severity ?? "error", kind: undefined }, "rejected"));
+}