@openpresentation/opf-editor 0.10.5 → 0.11.0

package/dist/template-panel.js

@@ -0,0 +1,377 @@
+// Fill template panel (RR-32): the DOM panel over the template model. It lists the document's variables with typed
+// inputs (text, number, date, color, URL, list, and an image source with an asset pick or an uploaded file), shows
+// which are filled and which still need a value, previews the result as values change, and fills the deck as one
+// undoable edit. A second section inserts a variable token into the host's selected text (declaring a new variable
+// in the same edit when asked). The panel owns no document state: values live in the fill session until applied.
+// Importing this module does not need a DOM; mounting does.
+import {
+  createTemplateFill,
+  insertVariableToken,
+  isTemplateDocument,
+  setTemplate,
+  suggestVariableId,
+  templatesAvailable,
+} from "./templates.js";
+
+const KIND_LABELS = { text: "Text", number: "Number", date: "Date", image: "Image", url: "Link", list: "List", color: "Color" };
+const STATUS_TEXT = { filled: "Filled", default: "Default value", unfilled: "Needs a value", optional: "Optional" };
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const NEW_VARIABLE_KINDS = ["text", "number", "date", "image", "url", "list"];
+
+let panelCounter = 0;
+
+function h(doc, tag, attributes = {}, ...children) {
+  const element = doc.createElement(tag);
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value === undefined || value === false) continue;
+    if (key === "class") element.className = value;
+    else if (key === "text") element.textContent = value;
+    else if (key.startsWith("on")) element.addEventListener(key.slice(2), value);
+    else element.setAttribute(key, value === true ? "" : String(value));
+  }
+  for (const child of children) if (child) element.append(child);
+  return element;
+}
+
+/**
+ * Mount the Fill template panel. Options: `editor` (a session), `renderPreview({document, variables, slideIndex})`
+ * returning an SVG string (or a promise of one) for the live preview (omit for no preview), `getSlideIndex`,
+ * `getTarget()` returning `{path, start?, end?}` for the text field a token is inserted into, `onStatus(message,
+ * {error})`, `onApply(result)`, `readFile(file)` (default: FileReader as a data URL) for image uploads.
+ */
+export function createTemplatePanel(container, options) {
+  if (!templatesAvailable()) throw new Error("The Fill template panel needs a core release that ships resolveVariables.");
+  const { editor, renderPreview, getTarget, onStatus, onApply } = options;
+  const doc = container.ownerDocument;
+  const fill = createTemplateFill(editor);
+  const id = `opf-template-${++panelCounter}`;
+  let previewSlide = options.getSlideIndex?.() ?? 0;
+  let previewToken = 0;
+  let destroyed = false;
+  const rows = new Map();
+
+  const root = h(doc, "section", { class: "opf-template-panel", "data-opf-component": "template-panel", "aria-label": "Fill template" });
+  const summary = h(doc, "p", { class: "opf-template-summary", id: `${id}-summary` });
+  const modeLabel = h(doc, "label", { class: "opf-template-mode" });
+  const modeBox = h(doc, "input", { type: "checkbox", id: `${id}-mode` });
+  modeLabel.append(modeBox, " This presentation is a template (it may have unfilled variables)");
+  const fieldList = h(doc, "div", { class: "opf-template-fields" });
+  const live = h(doc, "p", { class: "opf-template-live", role: "status", "aria-live": "polite" });
+  const applyButton = h(doc, "button", { type: "button", class: "opf-template-apply primary", text: "Fill the presentation" });
+  const partialButton = h(doc, "button", { type: "button", class: "opf-template-partial secondary", text: "Fill what is ready" });
+  const resetButton = h(doc, "button", { type: "button", class: "opf-template-reset quiet", text: "Clear values" });
+  const actions = h(doc, "div", { class: "opf-template-actions" }, applyButton, partialButton, resetButton);
+  const slideSelect = h(doc, "select", { id: `${id}-slide` });
+  const previewStatus = h(doc, "p", { class: "opf-template-preview-status", role: "status" });
+  const previewBox = h(doc, "div", { class: "opf-template-preview", "aria-label": "Preview with these values" });
+  const previewSection = renderPreview ? h(doc, "div", { class: "opf-template-preview-section" }, h(doc, "label", { for: `${id}-slide`, text: "Preview" }), slideSelect, previewStatus, previewBox) : null;
+
+  // Insert a variable into the selected text.
+  const insertSelect = h(doc, "select", { id: `${id}-insert-variable` });
+  const insertButton = h(doc, "button", { type: "button", class: "opf-template-insert secondary", text: "Insert into selected text" });
+  const newName = h(doc, "input", { type: "text", id: `${id}-new-name`, placeholder: "e.g. Client name" });
+  const newKind = h(doc, "select", { id: `${id}-new-kind` }, ...NEW_VARIABLE_KINDS.map((kind) => h(doc, "option", { value: kind, text: KIND_LABELS[kind] })));
+  const newSample = h(doc, "input", { type: "text", id: `${id}-new-sample`, placeholder: "Sample or current value" });
+  const newButton = h(doc, "button", { type: "button", class: "opf-template-new secondary", text: "Create and insert" });
+  const insertSection = getTarget
+    ? h(doc, "details", { class: "opf-template-insert-section" },
+      h(doc, "summary", { text: "Insert a variable into text" }),
+      h(doc, "p", { class: "opf-template-help", text: "Select a text field on the slide, then choose a variable. The token {{name}} is replaced by its value when the presentation is filled." }),
+      h(doc, "label", { for: `${id}-insert-variable`, text: "Variable" }), insertSelect, insertButton,
+      h(doc, "fieldset", { class: "opf-template-new-variable" },
+        h(doc, "legend", { text: "New variable" }),
+        h(doc, "label", { for: `${id}-new-name`, text: "Name" }), newName,
+        h(doc, "label", { for: `${id}-new-kind`, text: "Kind" }), newKind,
+        h(doc, "label", { for: `${id}-new-sample`, text: "Sample value" }), newSample, newButton))
+    : null;
+
+  root.append(summary, modeLabel, fieldList, actions, live);
+  if (previewSection) root.append(previewSection);
+  if (insertSection) root.append(insertSection);
+  container.append(root);
+
+  const say = (message, error = false) => {
+    live.textContent = message;
+    live.dataset.error = error ? "true" : "false";
+    onStatus?.(message, { error });
+  };
+  const messageOf = (error) => error?.issues?.[0]?.message ?? error?.message ?? String(error);
+
+  function readUpload(file) {
+    if (options.readFile) return Promise.resolve(options.readFile(file));
+    return new Promise((resolve, reject) => {
+      const reader = new (doc.defaultView.FileReader)();
+      reader.onload = () => resolve(String(reader.result));
+      reader.onerror = () => reject(new Error("The file could not be read."));
+      reader.readAsDataURL(file);
+    });
+  }
+
+  function control(field) {
+    const base = { id: `${id}-field-${field.id}`, "aria-describedby": `${id}-help-${field.id} ${id}-error-${field.id}` };
+    let input;
+    switch (field.kind) {
+      case "list":
+        input = h(doc, "textarea", { ...base, rows: 4, placeholder: field.placeholder });
+        break;
+      case "date":
+        input = h(doc, "input", { ...base, type: "date" });
+        break;
+      case "url":
+        input = h(doc, "input", { ...base, type: "url", placeholder: field.placeholder, inputmode: "url" });
+        break;
+      case "number":
+        input = h(doc, "input", { ...base, type: "text", inputmode: "decimal", placeholder: field.placeholder });
+        break;
+      case "color":
+        input = h(doc, "input", { ...base, type: "text", placeholder: field.placeholder || "#0F4C81", maxlength: 9 });
+        break;
+      default:
+        input = h(doc, "input", { ...base, type: "text", placeholder: field.placeholder });
+    }
+    input.value = field.text;
+    return input;
+  }
+
+  function buildRow(field) {
+    const input = control(field);
+    const error = h(doc, "p", { class: "opf-template-error", id: `${id}-error-${field.id}`, role: "alert", hidden: true });
+    const status = h(doc, "span", { class: "opf-template-status" });
+    const help = h(doc, "p", { class: "opf-template-help", id: `${id}-help-${field.id}` });
+    const useDefault = h(doc, "button", { type: "button", class: "opf-template-default quiet", text: "Use default" });
+    const extras = [];
+    let colorInput;
+    let assetSelect;
+    let fileInput;
+    if (field.kind === "color") {
+      colorInput = h(doc, "input", { type: "color", "aria-label": `${field.label} color picker` });
+      colorInput.addEventListener("input", () => {
+        input.value = colorInput.value.toUpperCase();
+        commit();
+      });
+      extras.push(colorInput);
+    }
+    if (field.kind === "image") {
+      const assets = editor.document.assets && typeof editor.document.assets === "object" ? Object.keys(editor.document.assets) : [];
+      if (assets.length) {
+        assetSelect = h(doc, "select", { "aria-label": `${field.label}: pick a registered asset` }, h(doc, "option", { value: "", text: "Pick an asset…" }), ...assets.map((key) => h(doc, "option", { value: `asset:${key}`, text: key })));
+        assetSelect.addEventListener("change", () => {
+          if (!assetSelect.value) return;
+          input.value = assetSelect.value;
+          commit();
+          assetSelect.value = "";
+        });
+        extras.push(assetSelect);
+      }
+      fileInput = h(doc, "input", { type: "file", accept: "image/*", "aria-label": `${field.label}: upload an image` });
+      fileInput.addEventListener("change", async () => {
+        const file = fileInput.files?.[0];
+        if (!file) return;
+        if (file.size > MAX_IMAGE_BYTES) {
+          showError(`That image is ${(file.size / 1048576).toFixed(1)} MB; the limit is 5 MB.`);
+          return;
+        }
+        try {
+          input.value = await readUpload(file);
+          commit();
+        } catch (failure) {
+          showError(messageOf(failure));
+        }
+      });
+      extras.push(fileInput);
+    }
+    const label = h(doc, "label", { for: input.id }, field.label, field.required ? h(doc, "span", { class: "opf-required", "aria-hidden": "true", text: " *" }) : null, h(doc, "span", { class: "opf-template-kind", text: ` (${KIND_LABELS[field.kind]})` }));
+    const element = h(doc, "div", { class: "opf-template-field", "data-variable": field.id, "data-kind": field.kind }, label, status, input, ...extras, help, error, useDefault);
+
+    function showError(message) {
+      error.hidden = !message;
+      error.textContent = message ?? "";
+      input.setAttribute("aria-invalid", message ? "true" : "false");
+    }
+    function commit() {
+      const parsed = fill.setText(field.id, input.value);
+      showError(parsed.ok ? undefined : parsed.message);
+    }
+    input.addEventListener("input", commit);
+    useDefault.addEventListener("click", () => {
+      input.value = "";
+      fill.clear(field.id);
+      showError(undefined);
+    });
+    return { element, input, status, help, useDefault, colorInput, showError };
+  }
+
+  function rebuild() {
+    fill.prune();
+    const fields = fill.fields();
+    rows.clear();
+    fieldList.replaceChildren();
+    if (!fields.length) {
+      fieldList.append(h(doc, "p", { class: "opf-template-empty", text: "This presentation has no variables yet. Declare variables in the source, or insert one from a text field below." }));
+    }
+    for (const field of fields) {
+      const row = buildRow(field);
+      rows.set(field.id, row);
+      fieldList.append(row.element);
+    }
+    insertSelect.replaceChildren(...fields.map((field) => h(doc, "option", { value: field.id, text: `${field.label} (${KIND_LABELS[field.kind]})` })));
+    slideSelect.replaceChildren(...(editor.document.slides ?? []).map((slide, index) => h(doc, "option", { value: String(index), text: `${index + 1}. ${typeof slide.title === "string" && slide.title ? slide.title : "Untitled"}` })));
+    previewSlide = Math.min(previewSlide, Math.max(0, (editor.document.slides?.length ?? 1) - 1));
+    slideSelect.value = String(previewSlide);
+    modeBox.checked = isTemplateDocument(editor.document);
+    update();
+  }
+
+  function update() {
+    const fields = fill.fields();
+    const status = fill.status();
+    for (const field of fields) {
+      const row = rows.get(field.id);
+      if (!row) continue;
+      row.element.dataset.status = field.status;
+      row.status.textContent = STATUS_TEXT[field.status];
+      row.useDefault.hidden = field.status !== "filled";
+      const uses = field.uses.length;
+      row.help.textContent = [
+        field.description,
+        uses ? `Used in ${uses} place${uses === 1 ? "" : "s"}.` : "Not used anywhere yet.",
+        field.kind === "list" ? "One entry per line." : undefined,
+        field.kind === "number" ? "Digits only, no thousands separators." : undefined,
+        field.kind === "date" ? "A calendar date." : undefined,
+        field.rich ? "Rich text: its formatting stays until you type a replacement." : undefined,
+        field.format ? `Shown as ${field.format}.` : undefined,
+      ].filter(Boolean).join(" ");
+      if (row.colorInput) {
+        const hex = /^#[0-9a-fA-F]{6}$/.test(row.input.value) ? row.input.value : /^#[0-9a-fA-F]{6}$/.test(field.placeholder) ? field.placeholder : "#000000";
+        row.colorInput.value = hex.toLowerCase();
+      }
+    }
+    const waiting = status.unfilled.length;
+    summary.textContent = status.fieldCount
+      ? waiting
+        ? `${status.filledRequiredCount} of ${status.requiredCount} required variables filled. Still needed: ${status.unfilled.join(", ")}.`
+        : `All ${status.requiredCount} required variables have a value.`
+      : "No variables.";
+    applyButton.disabled = !status.fieldCount || waiting > 0;
+    partialButton.disabled = !status.fieldCount || waiting === 0 || waiting === status.fieldCount;
+    resetButton.disabled = Object.keys(fill.values).length === 0;
+    insertButton.disabled = !insertSelect.options.length;
+    drawPreview();
+  }
+
+  async function drawPreview() {
+    if (!renderPreview) return;
+    const token = ++previewToken;
+    try {
+      const svg = await renderPreview({ document: editor.document, variables: fill.values, slideIndex: previewSlide });
+      if (token !== previewToken || destroyed) return;
+      previewBox.innerHTML = svg;
+      const preview = fill.preview();
+      const sample = preview.examplesUsed.length;
+      previewStatus.textContent = sample ? `Previewing with example values for: ${preview.examplesUsed.join(", ")}.` : "";
+    } catch (error) {
+      if (token !== previewToken || destroyed) return;
+      previewBox.replaceChildren();
+      previewStatus.textContent = `Preview unavailable: ${messageOf(error)}`;
+    }
+  }
+
+  async function apply(partial) {
+    try {
+      const result = fill.apply({ partial });
+      say(partial && !result.complete ? `Filled what was ready. Still needed: ${result.unfilled.join(", ")}.` : "Filled the presentation. Undo restores the template.");
+      onApply?.(result);
+    } catch (error) {
+      say(messageOf(error), true);
+    }
+  }
+  applyButton.addEventListener("click", () => apply(false));
+  partialButton.addEventListener("click", () => apply(true));
+  resetButton.addEventListener("click", () => {
+    fill.reset();
+    for (const row of rows.values()) {
+      row.input.value = "";
+      row.showError(undefined);
+    }
+    say("Cleared the values.");
+  });
+  slideSelect.addEventListener("change", () => {
+    previewSlide = Number(slideSelect.value) || 0;
+    drawPreview();
+  });
+  modeBox.addEventListener("change", () => {
+    try {
+      setTemplate(editor, modeBox.checked);
+      say(modeBox.checked ? "Marked as a template." : "Marked as a normal presentation.");
+    } catch (error) {
+      modeBox.checked = isTemplateDocument(editor.document);
+      say(messageOf(error), true);
+    }
+  });
+
+  function insertTarget() {
+    const target = getTarget?.();
+    if (!target?.path) {
+      say("Select a text field first.", true);
+      return undefined;
+    }
+    return target;
+  }
+  insertButton.addEventListener("click", () => {
+    const target = insertTarget();
+    if (!target || !insertSelect.value) return;
+    try {
+      const result = insertVariableToken(editor, target.path, insertSelect.value, { start: target.start, end: target.end });
+      say(`Inserted ${result.token}.`);
+    } catch (error) {
+      say(messageOf(error), true);
+    }
+  });
+  newButton.addEventListener("click", () => {
+    const target = insertTarget();
+    if (!target) return;
+    const name = newName.value.trim();
+    if (!name) {
+      say("Give the new variable a name.", true);
+      return;
+    }
+    const variableId = suggestVariableId(editor.document, name);
+    const kind = newKind.value;
+    const declaration = { type: kind, label: name };
+    const sample = newSample.value.trim();
+    if (sample) {
+      // A template keeps the sample as an example (the slot stays unfilled); a normal deck needs a real value.
+      const field = isTemplateDocument(editor.document) ? "example" : "value";
+      declaration[field] = kind === "number" && Number.isFinite(Number(sample)) ? Number(sample) : kind === "list" ? sample.split(/\r?\n|,/).map((entry) => entry.trim()).filter(Boolean) : sample;
+    }
+    try {
+      const result = insertVariableToken(editor, target.path, variableId, { start: target.start, end: target.end, declare: declaration });
+      newName.value = "";
+      newSample.value = "";
+      say(`Created ${variableId} and inserted ${result.token}.`);
+    } catch (error) {
+      say(messageOf(error), true);
+    }
+  });
+
+  const unsubscribeEditor = editor.subscribe(() => rebuild());
+  const unsubscribeFill = fill.subscribe(() => update());
+  rebuild();
+
+  return {
+    element: root,
+    fill,
+    /** Re-read the session (after the host changed the document or the slide). */
+    refresh() {
+      previewSlide = options.getSlideIndex?.() ?? previewSlide;
+      rebuild();
+    },
+    destroy() {
+      destroyed = true;
+      unsubscribeEditor();
+      unsubscribeFill();
+      root.remove();
+    },
+  };
+}
+

package/dist/templates.d.ts

@@ -0,0 +1,126 @@
+import type { EditorSession } from "./index.js";
+
+export type TemplateVariableKind = "color" | "text" | "number" | "date" | "image" | "url" | "list";
+export type TemplateFieldStatus = "filled" | "default" | "unfilled" | "optional";
+
+/** The form control each variable kind uses. */
+export declare const TEMPLATE_INPUT_TYPES: Readonly<Record<TemplateVariableKind, TemplateVariableKind>>;
+
+export interface TemplateVariableUse {
+  id: string;
+  /** JSON pointer of the string carrying the token or reference. */
+  path: string;
+  form: "token" | "reference";
+}
+
+export interface TemplateField {
+  id: string;
+  kind: TemplateVariableKind;
+  input: TemplateVariableKind;
+  /** The declaration's `label`, or the id as words. */
+  label: string;
+  description?: string;
+  required: boolean;
+  format?: string;
+  example?: unknown;
+  /** The effective value: a supplied value, else the declared one. */
+  value?: unknown;
+  /** The declaration's own value (its default), if any. */
+  defaultValue?: unknown;
+  /** What a form control shows for a supplied value (empty when only the default applies). */
+  text: string;
+  /** Placeholder text: the default value, else the example. */
+  placeholder: string;
+  /** True when the value is rich text (formatting is kept until the field is edited). */
+  rich: boolean;
+  /** "filled" (supplied), "default" (declared value), "unfilled" (required, no value) or "optional". */
+  status: TemplateFieldStatus;
+  uses: TemplateVariableUse[];
+}
+
+export interface TemplateStatus {
+  template: boolean;
+  fieldCount: number;
+  requiredCount: number;
+  filledRequiredCount: number;
+  unfilled: string[];
+  complete: boolean;
+}
+
+export interface TemplatePreview {
+  presentation: Record<string, unknown>;
+  diagnostics: { code: string; severity: "error" | "warning" | "info"; path: string; id: string; message: string }[];
+  unfilled: string[];
+  examplesUsed: string[];
+  complete: boolean;
+}
+
+/** True when the core this editor runs on can resolve template variables. */
+export declare function templatesAvailable(): boolean;
+export declare function isTemplateDocument(document: unknown): boolean;
+/** True when the document is a template or declares a variable that is not a color. */
+export declare function hasTemplateVariables(document: unknown): boolean;
+export declare function valueToFieldText(kind: TemplateVariableKind, value: unknown): string;
+/** Parse a form control's text. A blank control clears the value. */
+export declare function fieldTextToValue(kind: TemplateVariableKind, text: string): { ok: true; value: unknown } | { ok: false; message: string };
+export declare function listTemplateFields(document: unknown, values?: Record<string, unknown>): TemplateField[];
+export declare function templateStatus(document: unknown, values?: Record<string, unknown>): TemplateStatus;
+/** The concrete deck for the values with each unfilled variable's example. Never throws for missing values. */
+export declare function previewTemplate(document: unknown, values?: Record<string, unknown>): TemplatePreview;
+
+export interface TemplateFillOptions {
+  /** Extra session meta for the fill edit. */
+  meta?: Record<string, unknown>;
+}
+export interface TemplateFillApplyResult {
+  document: unknown;
+  patches: unknown[];
+  inversePatches: unknown[];
+  validation: unknown;
+  unfilled: string[];
+  complete: boolean;
+  diagnostics: TemplatePreview["diagnostics"];
+}
+export interface TemplateFill {
+  readonly values: Record<string, unknown>;
+  fields(): TemplateField[];
+  status(): TemplateStatus;
+  preview(): TemplatePreview;
+  /** Set a typed value; `undefined` or `null` clears it. Throws on an unknown variable or a value of the wrong kind. */
+  set(id: string, value: unknown): TemplateFill;
+  /** Set from a form control's text. Returns `{ ok: false, message }` instead of throwing for bad text. */
+  setText(id: string, text: string): { ok: true; value: unknown } | { ok: false; message: string };
+  clear(id: string): TemplateFill;
+  /** Drop values for variables the document no longer declares. */
+  prune(): TemplateFill;
+  reset(): TemplateFill;
+  subscribe(listener: (fill: TemplateFill) => void): () => void;
+  /**
+   * Fill the document with the values as one undoable, validated edit. Unfilled required variables
+   * refuse the fill (`unfilled-variables`) unless `partial` is set.
+   */
+  apply(options?: { partial?: boolean; meta?: Record<string, unknown> }): TemplateFillApplyResult;
+}
+export declare function createTemplateFill(editor: EditorSession, options?: TemplateFillOptions): TemplateFill;
+
+/** `{{id}}`, or `{{id|format}}`. */
+export declare function variableToken(id: string, format?: string): string;
+export declare function suggestVariableId(document: unknown, label?: string): string;
+/** Declare a variable as one undoable edit. */
+export declare function declareVariable(editor: EditorSession, id: string, declaration: string | Record<string, unknown>, meta?: Record<string, unknown>): unknown;
+/** Mark the document as a template, or as a normal deck with `false`, as one undoable edit. */
+export declare function setTemplate(editor: EditorSession, enabled: boolean, meta?: Record<string, unknown>): unknown;
+export interface InsertVariableTokenOptions {
+  /** UTF-16 offsets into the string; a selection is replaced. Default: the end. */
+  start?: number;
+  end?: number;
+  /** For a TextRun[] field: which run (default the last). */
+  runIndex?: number;
+  /** A one-off format: `{{id|format}}`. */
+  format?: string;
+  /** Declare the variable in the same edit when it is not declared yet. */
+  declare?: string | Record<string, unknown>;
+  meta?: Record<string, unknown>;
+}
+/** Insert a variable token into a text field as one undoable edit. */
+export declare function insertVariableToken(editor: EditorSession, path: string, id: string, options?: InsertVariableTokenOptions): { token: string; document: unknown; patches: unknown[]; inversePatches: unknown[]; validation: unknown };