@openpresentation/opf-editor 0.12.1 → 0.15.0

package/dist/catalogs.js

@@ -0,0 +1,217 @@
+// Catalogs (FA-23, OPF 0.15). The editor never ships or imports catalog data: the host registers its catalogs (`Catalog[]`,
+// the shape core's `CatalogOptions.catalogs` takes, for example `defaultCatalog` from `@openpresentation/opf/catalog`), on the
+// session (`createEditorSession(doc, { catalogs })`) or per call. `mergeCatalogs` is the one function that turns those into the
+// one list the editor hands to core (resolution, validation, embedding, copying, updates), to the renderer and to the exporter.
+// Pickers list core's `catalogRecords` and write the reference it gives (`id` or `name:id`); saving and exporting embed every
+// referenced record with core's `embed`, so a saved document renders the same with no catalog registered.
+import { catalogKinds, catalogRecords, embed, moveToCustom as coreMoveToCustom, updateFromCatalog } from "@openpresentation/opf";
+import { OPFEditorError } from "./index.js";
+
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * One catalog list from any number of lists (or single catalogs): the session's registration first, then each host list, in order.
+ * A catalog is identified by its `source`; the first catalog with a source wins and later ones with the same source are dropped,
+ * so the host default (the first entry) never moves. Entries that are not catalogs throw `invalid-catalogs` (core's
+ * `OPFCatalogsOptionError` code).
+ */
+export function mergeCatalogs(...lists) {
+  const merged = [];
+  const sources = new Set();
+  for (const list of lists) {
+    if (list === undefined || list === null) continue;
+    for (const catalog of Array.isArray(list) ? list : [list]) {
+      if (catalog === undefined || catalog === null) continue;
+      if (!isObject(catalog) || typeof catalog.source !== "string" || catalog.source === "")
+        throw new OPFEditorError("invalid-catalogs", "A registered catalog is an object with a non-empty source, such as defaultCatalog from @openpresentation/opf/catalog.", { catalog });
+      if (sources.has(catalog.source)) continue;
+      sources.add(catalog.source);
+      merged.push(catalog);
+    }
+  }
+  return Object.freeze(merged);
+}
+
+/** The catalogs for one operation: the session's registered list (when `editor` is given), then `options.catalogs`. */
+export function catalogsFor(editor, options = {}) {
+  return mergeCatalogs(editor?.catalogs, options?.catalogs);
+}
+
+/** The label a picker shows for a record: its name, then its gallery label, then the id. */
+export function catalogRecordLabel(record, id) {
+  const gallery = isObject(record?.["x-gallery"]) ? record["x-gallery"] : {};
+  for (const value of [record?.name, record?.title, record?.label, gallery.label, gallery.name]) if (typeof value === "string" && value) return value;
+  return String(id);
+}
+
+/**
+ * Every record a picker can offer for `kind`, from core's `catalogRecords`: the document's embedded records first, then the
+ * registered catalogs'. Each entry is `{ id, reference, label, description, record, group, source, origin }`; `id` and
+ * `reference` are the reference to write (`id` or `name:id`). A reference is listed once.
+ */
+export function listCatalogRecords(presentation, kind, options = {}) {
+  const seen = new Set();
+  const out = [];
+  for (const entry of catalogRecords(presentation ?? {}, kind, { catalogs: mergeCatalogs(options.catalogs) })) {
+    if (seen.has(entry.reference)) continue;
+    seen.add(entry.reference);
+    const record = isObject(entry.record) ? entry.record : {};
+    out.push({
+      id: entry.reference,
+      reference: entry.reference,
+      label: catalogRecordLabel(record, entry.id),
+      ...(typeof record.description === "string" ? { description: record.description } : {}),
+      record,
+      group: entry.group,
+      ...(entry.source !== undefined ? { source: entry.source } : {}),
+      origin: entry.origin,
+    });
+  }
+  return out;
+}
+
+/**
+ * The document to save or hand on: core's `embed` adds every record the document references, once, under its catalog group
+ * (with the records those reference, `x-*` display metadata stripped), so it renders the same with no catalog registered.
+ * Returns `{ document, added, unresolved }`; the input is not changed.
+ */
+export function prepareSave(presentation, options = {}) {
+  const result = embed(presentation, { catalogs: mergeCatalogs(options.catalogs) });
+  return { document: result.document, added: result.added ?? [], unresolved: result.unresolved ?? [] };
+}
+
+/** `prepareSave` for the session's document, with the session's catalogs and `options.catalogs`. The session is not changed. */
+export function saveDocument(editor, options = {}) {
+  assertSession(editor);
+  return prepareSave(editor.presentation, { catalogs: catalogsFor(editor, options) });
+}
+
+/**
+ * The "Update from catalog" check: core's `updateFromCatalog` compares every record embedded under `default` or a named group
+ * (never `custom`) with the registered catalog's current record. Returns `{ changes, patch }`; nothing is applied. `refs` limits
+ * the check to some references (`[{ kind, reference }]`).
+ */
+export function checkCatalogUpdates(presentation, options = {}) {
+  const update = updateFromCatalog(presentation, mergeCatalogs(options.catalogs), options.refs);
+  return { changes: update.changes ?? [], patch: update.patch ?? [] };
+}
+
+/**
+ * Apply an update the author approved, as ONE undoable step. `options.refs` names the approved changes (`[{ kind, reference }]`);
+ * the update is recomputed for exactly those against the session's current document, so a stale review never applies. Returns
+ * the session change plus `changes` (what was applied) and `changed`.
+ */
+export function applyCatalogUpdate(editor, options = {}) {
+  assertSession(editor);
+  if (!Array.isArray(options.refs) || !options.refs.length) throw new OPFEditorError("no-approved-updates", "Choose the catalog updates to apply.");
+  const update = checkCatalogUpdates(editor.presentation, { catalogs: catalogsFor(editor, options), refs: options.refs });
+  if (!update.patch.length) return { changed: false, changes: [], presentation: editor.presentation, patches: [], inversePatches: [], validation: editor.validation };
+  const change = editor.applyPatch(update.patch, { ...options.meta, source: options.meta?.source ?? "catalog-update", catalogRecordEdit: "in-place", catalogUpdate: update.changes.map(({ kind, reference }) => ({ kind, reference })) });
+  return { ...change, changed: true, changes: update.changes };
+}
+
+/**
+ * Core finding codes about catalog references and embedded records, which the editor surfaces next to its catalog controls:
+ * a reference that resolves nowhere, a prefix with no catalog group, and a record embedded under a catalog's group that the
+ * registered catalog does not publish (offer `moveToCustom`).
+ */
+export const REFERENCE_FINDING_CODES = Object.freeze(["opf/unresolved-reference", "opf/undeclared-catalog", "opf/catalog-record-not-in-source"]);
+
+/** The reference and embedded-record findings (`REFERENCE_FINDING_CODES`) of a validation report (the session's `validation`). */
+export function referenceFindings(validation) {
+  return (validation?.findings ?? []).filter((finding) => REFERENCE_FINDING_CODES.includes(finding.ruleId ?? finding.code));
+}
+
+function assertSession(editor) {
+  if (!editor || typeof editor.applyPatch !== "function" || typeof editor.subscribe !== "function")
+    throw new OPFEditorError("invalid-editor", "Expected an editor session created by createEditorSession.");
+}
+
+/**
+ * The record an `opf/catalog-record-not-in-source` finding names, from its path (`/catalogs/<group>/<kind>/<id>` or the dotted
+ * form): `{ group, kind, id }`, or undefined for a path that names no embedded record.
+ */
+export function catalogRecordAt(path) {
+  const parts = typeof path === "string" ? (path.startsWith("/") ? path.slice(1).split("/").map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~")) : path.split(".")) : [];
+  if (parts.length !== 4 || parts[0] !== "catalogs" || !catalogKinds.includes(parts[2])) return undefined;
+  return { group: parts[1], kind: parts[2], id: parts[3] };
+}
+
+const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * Move a record embedded under `default` or a named group into `catalogs.custom` (the fix the `opf/catalog-record-not-in-source`
+ * finding offers, and the fork an edit makes) with core's `moveToCustom`: the document owns it from then on. Every reference that
+ * resolved to it is rewritten to the custom id (`options.id`, else its id, `<id>-2` and up on a conflict), and references written
+ * inside it keep naming what they named. Returns `{ presentation, patches, changed, from, to, references }`.
+ */
+export function prepareMoveToCustom(presentation, target, options = {}) {
+  const { group, kind, id } = target ?? {};
+  const groups = isObject(presentation?.catalogs) ? presentation.catalogs : {};
+  const record = isObject(groups[group]?.[kind]) ? groups[group][kind][id] : undefined;
+  if (group === "custom" || record === undefined) throw new OPFEditorError("not-a-catalog-record", "Choose a record embedded under catalogs.default or a named catalog group.", { group, kind, id });
+  // Core's moveToCustom is the one implementation: references follow, the record's own references keep naming what they named.
+  const reference = group === "default" ? id : `${group}:${id}`;
+  const moved = coreMoveToCustom(presentation, { kind, reference }, { catalogs: mergeCatalogs(options.catalogs), ...(options.id ? { id: options.id } : {}) });
+  const patches = [{ op: "test", path: "/catalogs", value: structuredClone(presentation.catalogs) }, ...moved.patch];
+  return { presentation: moved.document, patches, changed: true, from: { group, kind, id }, to: { group: "custom", kind, id: moved.to.id }, references: moved.references ?? [] };
+}
+
+/**
+ * `prepareMoveToCustom` on the session's document, as ONE undoable step (`meta.source: "catalog-move-to-custom"`). `options.id` names
+ * the custom record (default: the record's id, `<id>-2` on a conflict).
+ */
+export function moveToCustom(editor, target, options = {}) {
+  assertSession(editor);
+  const prepared = prepareMoveToCustom(editor.presentation, target, { catalogs: catalogsFor(editor, options), ...(options.id ? { id: options.id } : {}) });
+  const change = editor.applyPatch(prepared.patches, { ...options.meta, source: options.meta?.source ?? "catalog-move-to-custom", catalogRecordEdit: "in-place" });
+  return { ...change, changed: true, from: prepared.from, to: prepared.to };
+}
+
+/** The record kinds a user edits, which an edit forks into `catalogs.custom` when they live under a catalog's group. */
+export const FORKED_RECORD_KINDS = Object.freeze(["layouts", "themes", "colorSchemes", "fontSchemes"]);
+
+/**
+ * Records under `catalogs.default` or a named group whose content an edit from `before` to `after` changed (present in both, not
+ * equal). An added or removed record is not an edit. Returns `[{ group, kind, id }]`.
+ */
+export function editedCatalogRecords(before, after) {
+  const out = [];
+  const groupsBefore = isObject(before?.catalogs) ? before.catalogs : {};
+  const groupsAfter = isObject(after?.catalogs) ? after.catalogs : {};
+  for (const [group, value] of Object.entries(groupsAfter)) {
+    if (group === "custom" || !isObject(value) || !isObject(groupsBefore[group])) continue;
+    for (const kind of FORKED_RECORD_KINDS) {
+      const was = isObject(groupsBefore[group][kind]) ? groupsBefore[group][kind] : {};
+      const now = isObject(value[kind]) ? value[kind] : {};
+      for (const id of Object.keys(now)) if (Object.hasOwn(was, id) && !sameJson(was[id], now[id])) out.push({ group, kind, id });
+    }
+  }
+  return out;
+}
+
+/** The notice an editor shows after a fork: the record is the deck's own now and no longer receives catalog updates. */
+export function forkNotice(fork) {
+  const label = { layouts: "layout", themes: "theme", colorSchemes: "color scheme", fontSchemes: "font scheme" }[fork.from.kind] ?? fork.from.kind;
+  return `The ${label} ${fork.from.id} is now this presentation's own (${fork.to.id}); it no longer receives catalog updates.`;
+}
+
+/**
+ * Owner rule (FA-23): editing a record that lives under `catalogs.default` or a named group forks it into `catalogs.custom` instead
+ * of changing the catalog's record in place. Given the document before and after an edit, returns the document after the forks
+ * (each edited record moved to custom as `<id>-custom`, or `forkIds[<group>:<kind>:<id>]`, every reference rewritten, the
+ * original dropped) and `forks: [{ from, to }]`. Nothing to fork returns `after` and `[]`.
+ */
+export function forkEditedRecords(before, after, options = {}) {
+  let document = after;
+  const forks = [];
+  for (const target of editedCatalogRecords(before, after)) {
+    const custom = isObject(document.catalogs?.custom?.[target.kind]) ? document.catalogs.custom[target.kind] : {};
+    let id = options.forkIds?.[`${target.group}:${target.kind}:${target.id}`] ?? `${target.id}-custom`;
+    for (let n = 2; Object.hasOwn(custom, id); n += 1) id = `${target.id}-custom-${n}`;
+    const moved = prepareMoveToCustom(document, target, { catalogs: options.catalogs, id });
+    document = moved.presentation;
+    forks.push({ from: moved.from, to: moved.to });
+  }
+  return { document, forks };
+}

package/dist/chart-data.d.ts

@@ -2,29 +2,29 @@ import type { EditorSession } from "./index.js";
 import type { GridAddress, GridCellEdit, GridChange, GridOptions, GridSortOptions, PreparedGridChange } from "./grid-model.js";
 
 /** Set chart cells from text or typed values: names and categories are text, series cells are numbers read in the number format (blank is a gap, never 0). One patch; every problem is in `error.issues`. */
-export declare function prepareChartCells(document: unknown, chartPath: string, edits: GridCellEdit[], options?: GridOptions): PreparedGridChange;
+export declare function prepareChartCells(presentation: unknown, chartPath: string, edits: GridCellEdit[], options?: GridOptions): PreparedGridChange;
 export declare function setChartCells(editor: EditorSession, chartPath: string, edits: GridCellEdit[], options?: GridOptions): GridChange;
-export declare function prepareChartPaste(document: unknown, chartPath: string, anchor: GridAddress, source: string | string[][], options?: GridOptions): PreparedGridChange;
+export declare function prepareChartPaste(presentation: unknown, chartPath: string, anchor: GridAddress, source: string | string[][], options?: GridOptions): PreparedGridChange;
 export declare function pasteChartText(editor: EditorSession, chartPath: string, anchor: GridAddress, source: string | string[][], options?: GridOptions): GridChange;
 /** Insert `count` empty rows (categories) so the first is row `at`. */
-export declare function prepareChartInsertRows(document: unknown, chartPath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function prepareChartInsertRows(presentation: unknown, chartPath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
 export declare function insertChartRows(editor: EditorSession, chartPath: string, at: number, count?: number, options?: GridOptions): GridChange;
-export declare function prepareChartDeleteRows(document: unknown, chartPath: string, indices: number[], options?: GridOptions): PreparedGridChange;
+export declare function prepareChartDeleteRows(presentation: unknown, chartPath: string, indices: number[], options?: GridOptions): PreparedGridChange;
 export declare function deleteChartRows(editor: EditorSession, chartPath: string, indices: number[], options?: GridOptions): GridChange;
-export declare function prepareChartMoveRows(document: unknown, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function prepareChartMoveRows(presentation: unknown, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
 export declare function moveChartRows(editor: EditorSession, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): GridChange;
 /** Insert `count` unnamed series so the first is column `at`. */
-export declare function prepareChartInsertColumns(document: unknown, chartPath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function prepareChartInsertColumns(presentation: unknown, chartPath: string, at: number, count?: number, options?: GridOptions): PreparedGridChange;
 export declare function insertChartColumns(editor: EditorSession, chartPath: string, at: number, count?: number, options?: GridOptions): GridChange;
-export declare function prepareChartDeleteColumns(document: unknown, chartPath: string, indices: number[], options?: GridOptions): PreparedGridChange;
+export declare function prepareChartDeleteColumns(presentation: unknown, chartPath: string, indices: number[], options?: GridOptions): PreparedGridChange;
 export declare function deleteChartColumns(editor: EditorSession, chartPath: string, indices: number[], options?: GridOptions): GridChange;
-export declare function prepareChartMoveColumns(document: unknown, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
+export declare function prepareChartMoveColumns(presentation: unknown, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): PreparedGridChange;
 export declare function moveChartColumns(editor: EditorSession, chartPath: string, from: number, to: number, count?: number, options?: GridOptions): GridChange;
 /** Sort the rows (categories) by a column, stably and by type. */
-export declare function prepareChartSort(document: unknown, chartPath: string, column: number, options?: GridSortOptions): PreparedGridChange;
+export declare function prepareChartSort(presentation: unknown, chartPath: string, column: number, options?: GridSortOptions): PreparedGridChange;
 export declare function sortChartRows(editor: EditorSession, chartPath: string, column: number, options?: GridSortOptions): GridChange;
 /** Swap categories and series: the first column's values become the series names and each series becomes a row. Numeric categories become text. */
-export declare function prepareChartTranspose(document: unknown, chartPath: string): PreparedGridChange;
+export declare function prepareChartTranspose(presentation: unknown, chartPath: string): PreparedGridChange;
 export declare function transposeChart(editor: EditorSession, chartPath: string, options?: { meta?: Record<string, unknown> }): GridChange;
 /** Rename a series: the label of data column `column` (1 or more). */
 export declare function renameChartSeries(editor: EditorSession, chartPath: string, column: number, name: string, options?: { meta?: Record<string, unknown> }): GridChange;

package/dist/chart-data.js

@@ -3,7 +3,7 @@
 // second). Cells are text for names and categories and numbers for values; a gap is null and stays a gap, never 0. Each operation is
 // one validated, undoable patch (grid-model.js has the implementation; grid-text.js documents number reading).
 //
-// `prepare*` computes `{ document, patches, changed }` without touching a session; the session forms apply it as one undo step.
+// `prepare*` computes `{ presentation, patches, changed }` without touching a session; the session forms apply it as one undo step.
 import {
   prepareGridCells,
   preparePaste,
@@ -26,64 +26,64 @@ import {
   prepareTranspose,
   transposeGridData,
 } from "./grid-model.js";
-export function prepareChartCells(document, chartPath, edits, options = {}) {
-  return prepareGridCells(document, chartPath, edits, { ...options, kind: "chart" });
+export function prepareChartCells(presentation, chartPath, edits, options = {}) {
+  return prepareGridCells(presentation, chartPath, edits, { ...options, kind: "chart" });
 }
 export function setChartCells(editor, chartPath, edits, options = {}) {
   return setGridCells(editor, chartPath, edits, { ...options, kind: "chart" });
 }
-export function prepareChartPaste(document, chartPath, anchor, source, options = {}) {
-  return preparePaste(document, chartPath, anchor, source, { ...options, kind: "chart" });
+export function prepareChartPaste(presentation, chartPath, anchor, source, options = {}) {
+  return preparePaste(presentation, chartPath, anchor, source, { ...options, kind: "chart" });
 }
 export function pasteChartText(editor, chartPath, anchor, source, options = {}) {
   return pasteGridText(editor, chartPath, anchor, source, { ...options, kind: "chart" });
 }
-export function prepareChartInsertRows(document, chartPath, at, count = 1, options = {}) {
-  return prepareInsertRows(document, chartPath, at, count, { ...options, kind: "chart" });
+export function prepareChartInsertRows(presentation, chartPath, at, count = 1, options = {}) {
+  return prepareInsertRows(presentation, chartPath, at, count, { ...options, kind: "chart" });
 }
 export function insertChartRows(editor, chartPath, at, count = 1, options = {}) {
   return insertGridRows(editor, chartPath, at, count, { ...options, kind: "chart" });
 }
-export function prepareChartDeleteRows(document, chartPath, indices, options = {}) {
-  return prepareDeleteRows(document, chartPath, indices, { ...options, kind: "chart" });
+export function prepareChartDeleteRows(presentation, chartPath, indices, options = {}) {
+  return prepareDeleteRows(presentation, chartPath, indices, { ...options, kind: "chart" });
 }
 export function deleteChartRows(editor, chartPath, indices, options = {}) {
   return deleteGridRows(editor, chartPath, indices, { ...options, kind: "chart" });
 }
-export function prepareChartMoveRows(document, chartPath, from, to, count = 1, options = {}) {
-  return prepareMoveRows(document, chartPath, from, to, count, { ...options, kind: "chart" });
+export function prepareChartMoveRows(presentation, chartPath, from, to, count = 1, options = {}) {
+  return prepareMoveRows(presentation, chartPath, from, to, count, { ...options, kind: "chart" });
 }
 export function moveChartRows(editor, chartPath, from, to, count = 1, options = {}) {
   return moveGridRows(editor, chartPath, from, to, count, { ...options, kind: "chart" });
 }
-export function prepareChartInsertColumns(document, chartPath, at, count = 1, options = {}) {
-  return prepareInsertColumns(document, chartPath, at, count, { ...options, kind: "chart" });
+export function prepareChartInsertColumns(presentation, chartPath, at, count = 1, options = {}) {
+  return prepareInsertColumns(presentation, chartPath, at, count, { ...options, kind: "chart" });
 }
 export function insertChartColumns(editor, chartPath, at, count = 1, options = {}) {
   return insertGridColumns(editor, chartPath, at, count, { ...options, kind: "chart" });
 }
-export function prepareChartDeleteColumns(document, chartPath, indices, options = {}) {
-  return prepareDeleteColumns(document, chartPath, indices, { ...options, kind: "chart" });
+export function prepareChartDeleteColumns(presentation, chartPath, indices, options = {}) {
+  return prepareDeleteColumns(presentation, chartPath, indices, { ...options, kind: "chart" });
 }
 export function deleteChartColumns(editor, chartPath, indices, options = {}) {
   return deleteGridColumns(editor, chartPath, indices, { ...options, kind: "chart" });
 }
-export function prepareChartMoveColumns(document, chartPath, from, to, count = 1, options = {}) {
-  return prepareMoveColumns(document, chartPath, from, to, count, { ...options, kind: "chart" });
+export function prepareChartMoveColumns(presentation, chartPath, from, to, count = 1, options = {}) {
+  return prepareMoveColumns(presentation, chartPath, from, to, count, { ...options, kind: "chart" });
 }
 export function moveChartColumns(editor, chartPath, from, to, count = 1, options = {}) {
   return moveGridColumns(editor, chartPath, from, to, count, { ...options, kind: "chart" });
 }
-export function prepareChartSort(document, chartPath, column, options = {}) {
-  return prepareSortRows(document, chartPath, column, { ...options, kind: "chart" });
+export function prepareChartSort(presentation, chartPath, column, options = {}) {
+  return prepareSortRows(presentation, chartPath, column, { ...options, kind: "chart" });
 }
 export function sortChartRows(editor, chartPath, column, options = {}) {
   return sortGridRows(editor, chartPath, column, { ...options, kind: "chart" });
 }
 
 /** Swap categories and series: the first column's values become the series names and each series becomes a row. See {@link prepareTranspose}. */
-export function prepareChartTranspose(document, chartPath) {
-  return prepareTranspose(document, chartPath);
+export function prepareChartTranspose(presentation, chartPath) {
+  return prepareTranspose(presentation, chartPath);
 }
 export function transposeChart(editor, chartPath, options = {}) {
   return transposeGridData(editor, chartPath, options);

package/dist/chart-options-panel.d.ts

@@ -7,8 +7,8 @@ export interface ChartOptionsPanelOptions {
   onStatus?: (message: string) => void;
 }
 export interface ChartOptionsPanel {
-  /** The panel's root element; undefined when the installed core has no chart option fields. */
-  element: HTMLElement | undefined;
+  /** The panel's root element (hidden while no chart is selected). */
+  element: HTMLElement;
   /** Re-read the selection and the chart; the panel also refreshes on every editor change. */
   refresh(): void;
   destroy(): void;

package/dist/chart-options-panel.js

@@ -1,14 +1,18 @@
-// The chart options panel (RR-35): axis titles, legend position and data labels for the selected chart.
+// The chart options panel (RR-35): axis titles, legend position and data labels for the selected chart, plus (FA-09) its alt text and
+// (FA-14) which series and categories to highlight.
 // It mounts into any host element over an editor session; every control commits one undoable change through
 // `setChartOptions` (src/chart-options.js), the canvas redraws, and Undo restores the chart. The panel shows only what
-// the selected chart type can show (core's support table), and hides itself when no chart is selected.
-import { CHART_LABEL_CONTENT, CHART_LEGEND_POSITIONS, chartOptionsAvailable, parseChartPath, readChartOptions, setChartOptions } from "./chart-options.js";
+// the selected chart type can show (core's support table), and hides itself when no chart is selected. On a combo chart
+// (FA-15) a "Series" group sets which series are lines and which lines use the secondary value axis, and a secondary axis
+// title field appears while a line uses that axis.
+import { CHART_LABEL_CONTENT, CHART_LEGEND_POSITIONS, parseChartPath, readChartOptions, setChartOptions } from "./chart-options.js";
 
 const LEGEND_LABELS = { default: "Default", none: "None", top: "Top", bottom: "Bottom", left: "Left", right: "Right" };
 const CONTENT_LABELS = { category: "Category", value: "Value", percent: "Percent" };
 const POSITION_LABELS = { auto: "Automatic", center: "Center", "inside-end": "Inside end", "inside-base": "Inside base", "outside-end": "Outside end", above: "Above", below: "Below", left: "Left", right: "Right" };
 
 let counter = 0;
+const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
 
 /**
  * Mount the panel in `host`. `getSelectedPath()` returns the selected OPF path (any path inside a chart selects it);
@@ -16,7 +20,6 @@ let counter = 0;
  * call `refresh()` when the selection changes (the panel also refreshes on every editor change).
  */
 export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatus = () => {} }) {
-  if (!chartOptionsAvailable()) return { refresh() {}, destroy() {}, element: undefined };
   const id = `opf-chart-options-${++counter}`;
   const root = document.createElement("section");
   root.className = "opf-chart-options";
@@ -24,10 +27,16 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
   root.hidden = true;
   root.innerHTML = `
     <h3 class="opf-co-title">Chart options</h3>
+    <div class="opf-co-group" data-group="alt">
+      <label class="opf-co-row"><span>Alt text</span><input type="text" id="${id}-alt" aria-label="Chart alt text" data-opf-chart-option="alt" autocomplete="off" placeholder="What the chart shows"></label>
+      <label class="opf-co-row opf-co-check"><input type="checkbox" id="${id}-decorative" aria-label="Decorative chart" data-opf-chart-option="alt.decorative"><span>Decorative (no alt text)</span></label>
+    </div>
     <div class="opf-co-group" data-group="axisTitles">
       <label class="opf-co-row" data-axis="category"><span>Category axis title</span><input type="text" id="${id}-category" aria-label="Category axis title" data-opf-chart-option="axisTitles.category" autocomplete="off"></label>
       <label class="opf-co-row" data-axis="value"><span>Value axis title</span><input type="text" id="${id}-value" aria-label="Value axis title" data-opf-chart-option="axisTitles.value" autocomplete="off"></label>
+      <label class="opf-co-row" data-axis="secondary"><span>Secondary axis title</span><input type="text" id="${id}-secondary" aria-label="Secondary axis title" data-opf-chart-option="axisTitles.secondary" autocomplete="off"></label>
     </div>
+    <fieldset class="opf-co-group opf-co-series" data-group="combo"><legend>Series</legend><div data-row="combo-series"></div></fieldset>
     <div class="opf-co-group" data-group="legend">
       <label class="opf-co-row"><span>Legend</span><select id="${id}-legend" aria-label="Legend" data-opf-chart-option="legend">${CHART_LEGEND_POSITIONS.map((value) => `<option value="${value}">${LEGEND_LABELS[value]}</option>`).join("")}</select></label>
     </div>
@@ -36,12 +45,18 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
       <fieldset class="opf-co-content"><legend>Label shows</legend>${CHART_LABEL_CONTENT.map((part) => `<label class="opf-co-check"><input type="checkbox" value="${part}" aria-label="Label shows ${CONTENT_LABELS[part].toLowerCase()}" data-opf-chart-option="dataLabels.content.${part}"><span>${CONTENT_LABELS[part]}</span></label>`).join("")}</fieldset>
       <label class="opf-co-row" data-row="position"><span>Label position</span><select id="${id}-position" aria-label="Label position" data-opf-chart-option="dataLabels.position"></select></label>
       <label class="opf-co-row" data-row="separator"><span>Separator</span><input type="text" id="${id}-separator" aria-label="Label separator" data-opf-chart-option="dataLabels.separator" autocomplete="off"></label>
+    </div>
+    <div class="opf-co-group" data-group="highlight">
+      <fieldset class="opf-co-highlight" data-part="series"><legend>Highlight series</legend><div class="opf-co-choices" data-choices="series"></div></fieldset>
+      <fieldset class="opf-co-highlight" data-part="categories"><legend>Highlight categories</legend><div class="opf-co-choices" data-choices="categories"></div></fieldset>
     </div>`;
   host.append(root);
   const $ = (selector) => root.querySelector(selector);
   const fields = {
-    category: $(`#${id}-category`), value: $(`#${id}-value`), legend: $(`#${id}-legend`), labels: $(`#${id}-labels`),
+    alt: $(`#${id}-alt`), decorative: $(`#${id}-decorative`), category: $(`#${id}-category`), value: $(`#${id}-value`), secondary: $(`#${id}-secondary`), legend: $(`#${id}-legend`), labels: $(`#${id}-labels`),
+    series: $("[data-row='combo-series']"),
     position: $(`#${id}-position`), separator: $(`#${id}-separator`), contents: [...root.querySelectorAll("[data-opf-chart-option^='dataLabels.content.']")],
+    highlight: { series: $("[data-choices='series']"), categories: $("[data-choices='categories']") },
   };
   let chartPath;
 
@@ -55,13 +70,34 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
       return;
     }
     chartPath = path;
-    const { fields: support, state } = readChartOptions(chart);
+    const { fields: support, state, choices, combo } = readChartOptions(chart, editor.presentation);
     root.hidden = false;
     const setValue = (input, value) => { if (input !== document.activeElement && input.value !== value) input.value = value; };
-    for (const axis of ["category", "value"]) {
-      $(`[data-axis="${axis}"]`).hidden = !support.axisTitles[axis];
+    setValue(fields.alt, state.alt);
+    fields.decorative.checked = state.decorative;
+    fields.alt.disabled = state.decorative;
+    const secondaryInUse = Boolean(combo?.series.some((entry) => entry.axis === "secondary"));
+    for (const axis of ["category", "value", "secondary"]) {
+      $(`[data-axis="${axis}"]`).hidden = !support.axisTitles[axis] || (axis === "secondary" && !secondaryInUse);
       setValue(fields[axis], state.axisTitles[axis]);
     }
+    // FA-15: one row per plotted series of a combo chart: "Line" and, for a line, "Secondary axis".
+    $("[data-group='combo']").hidden = !combo;
+    const series = combo?.series ?? [];
+    const signature = JSON.stringify(series.map((entry) => entry.name));
+    if (fields.series.dataset.series !== signature) {
+      fields.series.innerHTML = series.map((entry, index) => `<div class="opf-co-row opf-co-series-row" data-series="${index}"><span>${escapeHtml(entry.name)}</span>` +
+        `<label class="opf-co-check"><input type="checkbox" data-opf-chart-option="line" value="${escapeHtml(entry.name)}" aria-label="${escapeHtml(entry.name)} as a line"><span>Line</span></label>` +
+        `<label class="opf-co-check"><input type="checkbox" data-opf-chart-option="secondaryAxis" value="${escapeHtml(entry.name)}" aria-label="${escapeHtml(entry.name)} on the secondary axis"><span>Secondary axis</span></label></div>`).join("");
+      fields.series.dataset.series = signature;
+    }
+    series.forEach((entry, index) => {
+      const row = fields.series.querySelector(`[data-series="${index}"]`);
+      const line = row.querySelector("[data-opf-chart-option='line']"), secondary = row.querySelector("[data-opf-chart-option='secondaryAxis']");
+      line.checked = entry.role === "line";
+      secondary.checked = entry.axis === "secondary";
+      secondary.disabled = entry.role !== "line";
+    });
     $("[data-group='axisTitles']").hidden = !support.axisTitles.category && !support.axisTitles.value;
     $("[data-group='legend']").hidden = !support.legend;
     fields.legend.value = state.legend;
@@ -84,6 +120,31 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
     setValue(fields.separator, state.dataLabels.separator);
     fields.separator.disabled = off || state.dataLabels.content.length < 2;
     $("[data-row='separator']").hidden = support.dataLabels.content.length < 2;
+    // Highlight: one checkbox per plotted series and per category label the chart type can highlight.
+    for (const part of ["series", "categories"]) {
+      const offered = support.highlight[part] && choices[part].length > 0;
+      $(`[data-part='${part}']`).hidden = !offered;
+      const list = fields.highlight[part];
+      if (!offered) continue;
+      if (list.dataset.options !== JSON.stringify(choices[part])) {
+        list.replaceChildren(...choices[part].map((name) => {
+          const label = document.createElement("label");
+          label.className = "opf-co-check";
+          const input = document.createElement("input");
+          input.type = "checkbox";
+          input.value = name;
+          input.setAttribute("aria-label", `Highlight ${part === "series" ? "series" : "category"} ${name}`);
+          input.setAttribute("data-opf-chart-option", `highlight.${part}`);
+          const text = document.createElement("span");
+          text.textContent = name;
+          label.append(input, text);
+          return label;
+        }));
+        list.dataset.options = JSON.stringify(choices[part]);
+      }
+      for (const input of list.querySelectorAll("input")) input.checked = state.highlight[part].includes(input.value);
+    }
+    $("[data-group='highlight']").hidden = $("[data-part='series']").hidden && $("[data-part='categories']").hidden;
   }
 
   function commit(change, message) {
@@ -97,14 +158,27 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
     refresh();
   }
 
+  const checkedNames = (part) => [...fields.highlight[part].querySelectorAll("input:checked")].map((input) => input.value);
   const selectedContent = () => fields.contents.filter((input) => input.checked && !input.closest("label").hidden).map((input) => input.value);
   const listeners = [
+    [fields.alt, "change", () => commit({ alt: fields.alt.value }, "Changed the chart's alt text. Undo restores it.")],
+    [fields.decorative, "change", () => commit({ decorative: fields.decorative.checked }, fields.decorative.checked ? "Marked the chart decorative. Undo restores it." : "The chart is no longer decorative. Undo restores it.")],
     [fields.category, "change", () => commit({ axisTitles: { category: fields.category.value } }, "Changed the category axis title. Undo restores it.")],
     [fields.value, "change", () => commit({ axisTitles: { value: fields.value.value } }, "Changed the value axis title. Undo restores it.")],
+    [fields.secondary, "change", () => commit({ axisTitles: { secondary: fields.secondary.value } }, "Changed the secondary axis title. Undo restores it.")],
+    [fields.series, "change", () => {
+      const checked = (option) => [...fields.series.querySelectorAll(`[data-opf-chart-option='${option}']`)].filter((input) => input.checked).map((input) => input.value);
+      const line = checked("line");
+      commit({ line, secondaryAxis: checked("secondaryAxis").filter((name) => line.includes(name)) }, "Changed which series are lines. Undo restores them.");
+    }],
     [fields.legend, "change", () => commit({ legend: fields.legend.value }, "Changed the legend. Undo restores it.")],
     [fields.labels, "change", () => commit({ dataLabels: fields.labels.checked }, fields.labels.checked ? "Showing data labels. Undo restores the chart." : "Hid the data labels. Undo restores them.")],
     [fields.position, "change", () => commit({ dataLabels: { position: fields.position.value } }, "Moved the data labels. Undo restores them.")],
     [fields.separator, "change", () => commit({ dataLabels: { separator: fields.separator.value } }, "Changed the label separator. Undo restores it.")],
+    ...["series", "categories"].map((part) => [fields.highlight[part], "change", () => {
+      const names = checkedNames(part);
+      commit({ highlight: { [part]: names } }, names.length ? `Highlighted ${names.join(", ")}. Undo restores the colors.` : `Cleared the ${part} highlight. Undo restores it.`);
+    }]),
     ...fields.contents.map((input) => [input, "change", () => {
       const content = selectedContent();
       // A label always shows something: unticking the last part keeps it.

package/dist/chart-options.d.ts

@@ -9,7 +9,8 @@ export declare const CHART_LABEL_CONTENT: readonly ["category", "value", "percen
 
 /** What a chart type can show (core's `chartOptionSupport`). */
 export interface ChartOptionFields {
-  axisTitles: { category: boolean; value: boolean };
+  /** `secondary`: the type can title a secondary value axis (combo charts). */
+  axisTitles: { category: boolean; value: boolean; secondary: boolean };
   legend: boolean;
   dataLabels: {
     supported: boolean;
@@ -20,30 +21,55 @@ export interface ChartOptionFields {
     /** True for the constructs that label their marks by default (funnel, treemap). */
     defaultOn: boolean;
   };
+  /** What `chart.highlight` can name on this chart type: series, categories (one slice of a pie, one point of a line). */
+  highlight: { series: boolean; categories: boolean };
 }
-/** The three fields as form state. */
+/** The names a highlight can take on a chart, from its resolved data (empty when the data does not resolve). */
+export interface ChartHighlightChoices { series: string[]; categories: string[] }
+/** A plotted series of a combo chart: drawn as columns ("bar") or as a line, on the primary or secondary value axis (FA-15). */
+export interface ChartComboSeriesState {
+  name: string;
+  role: "bar" | "line";
+  axis: "primary" | "secondary";
+}
+/** The fields as form state. */
 export interface ChartOptionState {
-  axisTitles: { category: string; value: string };
+  /** The chart's text alternative (empty when absent or decorative). */
+  alt: string;
+  /** True when the chart is marked decorative (alt is the empty string). */
+  decorative: boolean;
+  axisTitles: { category: string; value: string; secondary: string };
   legend: ChartLegendChoice;
   dataLabels: { on: boolean; explicit: boolean; content: ChartLabelContent[]; position: ChartLabelPosition | "auto"; separator: string };
+  /** The series and categories `chart.highlight` names (empty lists when it is absent). */
+  highlight: { series: string[]; categories: string[] };
 }
 export interface ChartOptionChange {
-  axisTitles?: { category?: string; value?: string };
+  /** The text alternative: what the data shows. Trimmed; an empty string or null removes it. */
+  alt?: string | null;
+  /** true marks the chart decorative (alt ""); false removes an empty alt. */
+  decorative?: boolean;
+  axisTitles?: { category?: string; value?: string; secondary?: string };
+  /** Combo charts: the series drawn as lines, by name (at least one, and not every series). */
+  line?: string[];
+  /** Combo charts: the line series on the secondary value axis, by name. */
+  secondaryAxis?: string[];
   legend?: ChartLegendChoice;
   dataLabels?: boolean | null | { content?: ChartLabelContent[]; position?: ChartLabelPosition | "auto"; separator?: string };
+  /** `null` removes the highlight; a list replaces that part (an empty list removes it) and the other part is kept. */
+  highlight?: null | { series?: string[]; categories?: string[] };
 }
 export interface PreparedChartOptions {
   action: "chart-options";
   chartPath: string;
   changed: boolean;
   patches: JsonPatchOperation[];
-  document: unknown;
+  presentation: unknown;
 }
 
-/** True when the installed core knows the chart option fields. */
-export declare function chartOptionsAvailable(): boolean;
 /** The chart path a selection path points at, or undefined. */
 export declare function parseChartPath(path: string): string | undefined;
-export declare function readChartOptions(chart: unknown): { target: unknown; fields: ChartOptionFields; state: ChartOptionState };
-export declare function prepareChartOptions(document: unknown, chartPath: string, change: ChartOptionChange): PreparedChartOptions;
+/** `combo` is present on a combo chart: its plotted series in data order. Pass the `document` for a dataset-backed chart. */
+export declare function readChartOptions(chart: unknown, presentation?: unknown): { target: unknown; fields: ChartOptionFields; choices: ChartHighlightChoices; state: ChartOptionState; combo?: { series: ChartComboSeriesState[] } };
+export declare function prepareChartOptions(presentation: unknown, chartPath: string, change: ChartOptionChange): PreparedChartOptions;
 export declare function setChartOptions(editor: EditorSession, chartPath: string, change: ChartOptionChange, meta?: Record<string, unknown>): EditorChange & { action: "chart-options"; chartPath: string; changed: boolean };