@openpresentation/opf 0.12.1 → 0.13.0

package/README.md

@@ -22,7 +22,7 @@ pnpm add @openpresentation/opf
 # or: yarn add @openpresentation/opf
 ```
 
-Requires Node 24 starting with version 0.10.0. Earlier published versions retain their recorded runtime requirements.
+Requires Node 22 or later (`engines.node` `>=22`) from the release after 0.12.1. Versions 0.10.0 to 0.12.1 declared `24.x`, so npm on Node 22 or 26 silently installed an older release that matched (RR-20). Earlier published versions retain their recorded runtime requirements.
 
 ## Usage
 

package/dist/audit.d.ts

@@ -1,132 +1,11 @@
-import { C as CatalogKind } from './catalogs-BnI7JKcn.js';
-import { T as TextMeasurement } from './composition-DWbCiMwF.js';
-import { LintDiagnostic, LintSeverity } from './lint.js';
-import './schemas-BSjlG8-R.js';
-import './validator-DfG9yxba.js';
-import './presentation-DcF-MZcz.js';
-
-/** Same three levels as `lintSource`. */
-type AuditSeverity = LintSeverity;
-type AuditCategory = 'accessibility' | 'design' | 'content';
-/** One JSON Patch operation (RFC 6902 subset) a quick fix applies. Paths are JSON Pointers into the audited document. */
-interface AuditPatchOperation {
-    op: 'add' | 'replace' | 'remove';
-    path: string;
-    value?: unknown;
-}
-/**
- * A suggested repair. Core never applies it: a host shows it and applies it through its own undoable edit path.
- * `focus` fixes only name the field the author must fill in; `patch` fixes are small, deterministic and leave
- * every unrelated field untouched.
- */
-interface AuditFix {
-    /** Stable id within one diagnostic, such as `focus-alt` or `inherit-text-color`. */
-    id: string;
-    label: string;
-    kind: 'patch' | 'focus';
-    /** True when applying the fix cannot change the meaning of the content (a colour switched to a readable one, a field focused). */
-    safe: boolean;
-    patch?: AuditPatchOperation[];
-    /** For `focus`: the JSON Pointer of the field to edit and a hint of what it is. */
-    focus?: {
-        path: string;
-        field: 'alt' | 'title' | 'text' | 'link' | 'language' | 'fontSize';
-        value?: unknown;
-    };
-}
-interface AuditDiagnostic extends LintDiagnostic {
-    /** `audit/<rule>`; ids are stable across releases. */
-    ruleId: string;
-    /** Zero-based slide index when the finding belongs to one slide. */
-    slide?: number;
-    slideId?: string;
-    category: AuditCategory;
-    /** Measured values behind the finding (ratios, sizes, counts), for reporters and tests. */
-    measured?: Record<string, number | string | boolean | null>;
-    fixes?: AuditFix[];
-}
-interface AuditThresholds {
-    /** Minimum WCAG contrast ratio for normal text. WCAG 2.x AA: 4.5. */
-    contrastNormal: number;
-    /** Minimum ratio for large text (at least 18 pt, or 14 pt bold). WCAG 2.x AA: 3. */
-    contrastLarge: number;
-    /** Smallest rendered text size, in points, before `audit/min-font-size` reports. */
-    minFontSizePt: number;
-    /** Words on one slide above which `audit/slide-word-count` reports. */
-    maxWordsPerSlide: number;
-    /** Distinct font families across the deck above which `audit/font-family-count` reports. */
-    maxFontFamilies: number;
-    /** Minimum effective pixels per inch of an embedded raster image at its displayed size. */
-    minImagePpi: number;
-    /** Largest title offset between slides of the same layout, as a fraction of the slide width/height. */
-    titlePositionTolerance: number;
-    /** Smallest CIE76 colour difference between two chart series (after colour-vision simulation) before they count as confusable. */
-    minSeriesColorDifference: number;
-}
-interface AuditOptions {
-    /** Per-rule severity, or `off`. Keys are full ids (`audit/text-contrast`) or the bare name (`text-contrast`). */
-    rules?: Record<string, AuditSeverity | 'off'>;
-    /** Rules not to run (full ids or bare names). */
-    ignore?: readonly string[];
-    /** When set, run only these rules (full ids or bare names). */
-    only?: readonly string[];
-    /**
-     * Suppress a rule below a JSON Pointer prefix, for one accepted exception, for example
-     * `{rule: 'audit/text-contrast', path: '/slides/3'}`. A prefix matches whole path segments.
-     */
-    ignorePaths?: readonly {
-        rule: string;
-        path: string;
-    }[];
-    thresholds?: Partial<AuditThresholds>;
-    /** Loaded catalog records, consulted after the document's own `catalogs` and before the bundled ones. */
-    catalogs?: Partial<Record<CatalogKind, readonly unknown[]>>;
-    /**
-     * The host's measured fonts. Without it composition uses core's portable estimate; see docs/audit.md.
-     * A function receives the zero-based slide index, so a host can supply a script-aware measurement per slide.
-     */
-    textMeasurement?: TextMeasurement | ((slideIndex: number) => TextMeasurement | undefined);
-    /** Chart series palette (opaque `#RRGGBB`), in the engine's order. Default: the palette opf-render and opf-pptx use. */
-    chartPalette?: readonly string[];
-}
-interface AuditRuleInfo {
-    /** Stable `audit/<name>` id. */
-    id: string;
-    name: string;
-    category: AuditCategory;
-    /** Default severity. */
-    severity: AuditSeverity;
-    summary: string;
-    /** Why the rule exists. */
-    rationale: string;
-    /** The accessibility or design standard it follows, when there is one. */
-    standard?: string;
-    /** What the check cannot see or approximates. */
-    approximations?: string;
-    /** Threshold names (`AuditThresholds`) the rule reads. */
-    thresholds?: (keyof AuditThresholds)[];
-}
-interface AuditReport {
-    /** True when no finding has severity `error` (the same meaning as lint's `valid`). */
-    valid: boolean;
-    /** False when the document failed schema validation, so no design rule was run. */
-    documentValid: boolean;
-    diagnostics: AuditDiagnostic[];
-    counts: Record<AuditSeverity, number>;
-    /** Rule ids that ran, in registry order. */
-    rulesRun: string[];
-    slideCount: number;
-    thresholds: AuditThresholds;
-    checks: {
-        /** `estimated` unless the host supplied `textMeasurement`. */
-        textMeasurement: 'estimated' | 'provided';
-        /** Text contrast is computed against solid, gradient and pattern backgrounds; picture pixels are never read. */
-        backgroundPixels: 'not-read';
-        /** Image resolution reads only embedded `data:` images; URLs are never fetched. */
-        imageBytes: 'embedded-only';
-        nativeExport: 'not-checked';
-    };
-}
+import { A as AuditThresholds, a as AuditOptions, b as AuditReport, c as AuditRuleInfo } from './lint-B7azdiuE.js';
+export { d as AuditCategory, e as AuditDiagnostic, f as AuditFix, g as AuditPatchOperation, h as AuditSeverity } from './lint-B7azdiuE.js';
+import './catalogs-ywCamd8C.js';
+import './schemas-BbPonsTz.js';
+import './validator-CIylxoIm.js';
+import './presentation-mG-IYErQ.js';
+import './composition-D7we69Tr.js';
+import './chart-data-Cdr6rRVV.js';
 
 /**
  * The series palette opf-render and opf-pptx draw charts with (`CHART_COLORS`), in series order. A host with
@@ -153,4 +32,4 @@ declare function auditPresentation(document: unknown, options?: AuditOptions): A
 /** Audit JSON source text. Findings carry original-source UTF-16 ranges and one-based line/column, like `lintSource`. */
 declare function auditSource(source: string, options?: AuditOptions): AuditReport;
 
-export { type AuditCategory, type AuditDiagnostic, type AuditFix, type AuditOptions, type AuditPatchOperation, type AuditReport, type AuditRuleInfo, type AuditSeverity, type AuditThresholds, DEFAULT_AUDIT_THRESHOLDS, DEFAULT_CHART_PALETTE, auditPresentation, auditRules, auditSource, findAuditRule };
+export { AuditOptions, AuditReport, AuditRuleInfo, AuditThresholds, DEFAULT_AUDIT_THRESHOLDS, DEFAULT_CHART_PALETTE, auditPresentation, auditRules, auditSource, findAuditRule };

package/dist/audit.js

@@ -1,7 +1,7 @@
-export { DEFAULT_AUDIT_THRESHOLDS, DEFAULT_CHART_PALETTE, auditPresentation, auditRules, auditSource, findAuditRule } from './chunk-6LZK2IZB.js';
-import './chunk-MWPMJE6P.js';
-import './chunk-JKVKYVWL.js';
-import './chunk-HOBSL7AJ.js';
+export { DEFAULT_AUDIT_THRESHOLDS, DEFAULT_CHART_PALETTE, auditPresentation, auditRules, auditSource, findAuditRule } from './chunk-7N4VMAT4.js';
+import './chunk-INU7ZNSB.js';
+import './chunk-IYCJUKWD.js';
+import './chunk-MPM7NRG7.js';
 import './chunk-S5W34SIJ.js';
 import './chunk-E34DJ5LL.js';
-import './chunk-4LAM3N6S.js';
+import './chunk-7QBCWNWL.js';

package/dist/{catalogs-BnI7JKcn.d.ts → catalogs-ywCamd8C.d.ts}

@@ -1,4 +1,4 @@
-import { a as SchemaName } from './schemas-BSjlG8-R.js';
+import { a as SchemaName } from './schemas-BbPonsTz.js';
 
 /**
  * Schema for audience records in the pptx.gallery library. Each record names an audience archetype (e.g. 'executive', 'engineering-team', 'investor') and carries seniority, technical-fluency, decision-power, and attention-budget hints used by AI-driven generation. Audiences are referenced from OPF documents via audience; the engine resolves the reference against catalogs.audiences (inline) → catalogs.audiences.source → the default catalog at https://www.pptx.gallery/audiences. The audience field also accepts free-form strings; this catalog is for engine-aware audience archetypes that carry generation hints.

package/dist/catalogs.d.ts

@@ -1,2 +1,2 @@
-export { a as CatalogEntry, b as CatalogIndex, c as CatalogIndexRecord, C as CatalogKind, d as CatalogRecord, i as audiences, j as catalogEntries, k as catalogIndexes, l as catalogKinds, m as catalogSchemaNames, n as catalogs, o as chartTypes, p as colorSchemes, q as fontSchemes, r as languages, s as layouts, t as narratives, u as purposes, v as socialPlatforms, w as themes, x as tones } from './catalogs-BnI7JKcn.js';
-import './schemas-BSjlG8-R.js';
+export { a as CatalogEntry, b as CatalogIndex, c as CatalogIndexRecord, C as CatalogKind, d as CatalogRecord, i as audiences, j as catalogEntries, k as catalogIndexes, l as catalogKinds, m as catalogSchemaNames, n as catalogs, o as chartTypes, p as colorSchemes, q as fontSchemes, r as languages, s as layouts, t as narratives, u as purposes, v as socialPlatforms, w as themes, x as tones } from './catalogs-ywCamd8C.js';
+import './schemas-BbPonsTz.js';

package/dist/chart-data-Cdr6rRVV.d.ts

@@ -0,0 +1,177 @@
+/** A scalar data cell (chart data, dataset rows). */
+type DataCellValue = string | number | boolean | null;
+/** A named column with an optional number format. The string column form is `{ name }` with no format. */
+interface DataColumn {
+    name: string;
+    format?: string;
+}
+/** Provenance of inline data or a dataset. Engines never read, fetch or refresh it. */
+interface DataSourceRef {
+    src: string;
+    sheet?: string;
+    range?: string;
+    fields?: string[];
+    retrieved?: string;
+    description?: string;
+}
+/** One shared data table in the top-level `datasets` map. */
+interface Dataset {
+    title?: string;
+    description?: string;
+    columns: (string | DataColumn)[];
+    rows: DataCellValue[][];
+    source?: DataSourceRef;
+}
+/** Chart data (or, as `{ dataset, fields }`, a table) taken from a top-level dataset. */
+interface DatasetRef {
+    dataset: string;
+    fields?: string[];
+}
+/** `chart.mapping`: the category, X and series columns by name (after any `fields` selection). */
+interface ChartMapping {
+    category?: string;
+    x?: string;
+    series?: string[];
+}
+/** A text run as table cells and headers hold them (see the schema `TextRun`). */
+type DataTextRun = string | {
+    text: string;
+    [key: string]: unknown;
+};
+/** A table cell's value: a scalar or rich runs. */
+type DataTableValue = string | number | boolean | null | DataTextRun[];
+/** A styled or spanning table cell, optionally with a number format. */
+interface DataStyledCell {
+    value: DataTableValue;
+    style?: Record<string, unknown>;
+    colSpan?: number;
+    rowSpan?: number;
+    format?: string;
+}
+/** A table body cell. */
+type DataTableCell = DataTableValue | DataStyledCell;
+/** A table column header: a cell, or a DataColumn. */
+type DataTableHeader = DataTableCell | DataColumn;
+type DataDiagnosticCode = 'chart-value-not-numeric' | 'chart-data-source-unresolved' | 'dataset-unknown' | 'dataset-field-unknown' | 'data-column-duplicate' | 'chart-mapping-unknown-column' | 'chart-mapping-adapted' | 'number-format-invalid';
+interface DataDiagnostic {
+    code: DataDiagnosticCode;
+    severity: 'error' | 'warning';
+    /** JSON Pointer of the offending value: below the `path` option for the chart or table, or into `/datasets/<id>`. */
+    path: string;
+    message: string;
+}
+interface DataResolveOptions {
+    /** JSON Pointer of the chart or table object, used as the base of diagnostic paths. Default: "" (paths start at `/data` or `/rows`). */
+    path?: string;
+}
+type ResolvedChartData = {
+    ok: true;
+    /** Column names in canonical order: category, then (scatter only) X, then every series. */
+    columns: string[];
+    /**
+     * True when `columns[1]` is the X column: an XY chart with three or more resolved columns. An XY chart with two
+     * columns has no X column; its second column is the one series, plotted against row numbers (the legacy rule).
+     */
+    hasX: boolean;
+    /** The number format of each column (from its DataColumn), aligned with `columns`. */
+    formats: (string | undefined)[];
+    /** Category cells as authored; X and series cells (and a lone column, which has no category) passed through `chartNumber` (null is a gap). */
+    rows: DataCellValue[][];
+    source?: DataSourceRef;
+    /** The dataset id when the chart references one. */
+    dataset?: string;
+    diagnostics: DataDiagnostic[];
+} | {
+    ok: false;
+    reason: 'data-not-inline' | 'dataset-unknown' | 'no-rows' | 'no-columns';
+    message: string;
+    diagnostics: DataDiagnostic[];
+};
+interface ResolvedTableData {
+    /** Headers as authored (dataset tables: the dataset's columns after `fields`), or undefined for a table without headers. */
+    columns?: DataTableHeader[];
+    rows: DataTableCell[][];
+    /** The column number formats (DataColumn or header StyledTableCell `format`), by column index. */
+    formats: (string | undefined)[];
+    /** The dataset id when the table references one. */
+    dataset?: string;
+    diagnostics: DataDiagnostic[];
+}
+/**
+ * Strict chart number: finite numbers, and strings in strict decimal syntax (trimmed). Everything else is null (a gap):
+ * `"12%"`, `"$5"`, `"(5)"`, `"1,234"`, `"1.234,5"`, `"Q1"`, `""`, booleans and null. A plain digit string beyond the safe
+ * integer range is a gap too, as in data import (it is usually an identifier that would lose digits); a decimal or exponent
+ * form such as `"1e20"` is a number.
+ */
+declare function chartNumber(value: unknown): number | null;
+/** Why a NumberFormat is invalid, or undefined for a valid one. An absent format is valid (General). */
+declare function numberFormatError(format: unknown): string | undefined;
+/** Format a number with a NumberFormat; an absent or invalid format prints the General form (String(value)). */
+declare function formatDataNumber(value: number, format?: string): string;
+/** NumberFormat -> Excel format code ("General" when absent or invalid). Literal prefix/suffix text is quoted or escaped; placeholders are written '#' before '0' ("0#" -> "#0"). */
+declare function excelNumberFormat(format?: string): string;
+/** Excel format code -> NumberFormat, or undefined when the code has no exact NumberFormat equivalent (General, sections, scaling commas, and placeholder orders Excel reads by position such as "0#" or "0.#0"). */
+declare function numberFormatFromExcel(code: string): string | undefined;
+/** True when the value is a dataset reference (`{ dataset: "<id>" }`). */
+declare function isDatasetRef(value: unknown): value is DatasetRef;
+/** Diagnostics of the top-level datasets themselves: duplicate column names and invalid column formats. */
+declare function datasetDiagnostics(document: unknown): DataDiagnostic[];
+/**
+ * Pure: a copy of the document where every chart and table DatasetRef is replaced by inline data (columns as
+ * DataColumn when a format applies, rows copied; a chart also takes the dataset's `source`). `datasets` stays in
+ * place. Unknown ids (and references naming an unknown field) are left as they are.
+ */
+declare function inlineDatasets<T>(document: T): T;
+/** A table in inline form: a dataset-backed table is copied from the document's dataset; anything else is returned as is. */
+declare function inlineTableData<T>(table: T, document?: unknown): T;
+/** A chart in inline form: a dataset reference in `data` is copied from the document's dataset; anything else is returned as is. */
+declare function inlineChartData<T>(chart: T, document?: unknown): T;
+/** The ids of top-level datasets that no chart or table references, in declaration order. */
+declare function unusedDatasets(document: unknown): string[];
+/** True for a chart type with an X value axis (scatter; deprecated ids resolve through their replacement first). */
+declare function isXYChartType(type: unknown): boolean;
+/**
+ * Resolve a chart's data to the canonical positional table: [category, (x,) ...series].
+ * Category cells are kept as authored; X and series cells pass through chartNumber.
+ * Inline ChartData, a DatasetRef (needs the document) and mapping are resolved here.
+ */
+declare function resolveChartData(chart: unknown, document?: unknown, options?: DataResolveOptions): ResolvedChartData;
+/** One JSON Patch `replace` operation of a ChartNumberFix. */
+interface ChartNumberFixOperation {
+    op: 'replace';
+    path: string;
+    value: unknown;
+}
+/** A fix for a chart value column whose text cells all share one display style (`"12%"`, `"$1,234"`, `"1,234.5"`). */
+interface ChartNumberFix {
+    /**
+     * JSON Patch: one `replace` per text cell (with its number), then one for the column (a DataColumn with `format`).
+     * Paths are those of the `chart-value-not-numeric` diagnostics: below `options.path` for inline data, or into
+     * `/datasets/<id>` for a dataset (which every chart and table that uses it shares; their text is unchanged).
+     */
+    patches: ChartNumberFixOperation[];
+    /** Index of the column in the authored columns (`chart.data.columns`, or the dataset's columns). */
+    column: number;
+    /** The column name. */
+    name: string;
+    /** The NumberFormat that displays every number of the column exactly as its text was written. */
+    format: string;
+}
+interface ChartNumberFixOptions extends DataResolveOptions {
+    /** The column to fix, by authored index or name. Default: the first value column that has a fix. */
+    column?: number | string;
+}
+/**
+ * Migration help for the strict number rule: when every text cell of a chart value column is written in one display
+ * style that a NumberFormat reproduces exactly (`"12%"`/`"8.5%"` -> 0.12/0.085 with `0.#%`; `"$1,234"` -> 1234 with
+ * `$#,##0`; `"1,234"` -> 1234 with `#,##0`), the patch that stores the numbers and gives the column that format.
+ * Undefined when there is nothing to fix or no exact fix: mixed styles, accounting negatives `(5)`, `1.234,5`, units,
+ * a column that already has a format, or any value the format would display differently (number cells included).
+ */
+declare function suggestChartNumberFix(chart: unknown, document?: unknown, options?: ChartNumberFixOptions): ChartNumberFix | undefined;
+/** Resolve a table (inline or dataset-backed) to headers, rows and per-column formats. */
+declare function resolveTableData(table: unknown, document?: unknown, options?: DataResolveOptions): ResolvedTableData;
+/** Display value of a table cell: a number with a format (cell, else column) becomes formatted text; anything else is returned unchanged. */
+declare function tableCellDisplayValue(cell: DataTableCell, columnFormat?: string): DataTableCell;
+
+export { numberFormatFromExcel as A, resolveChartData as B, type ChartMapping as C, type DataCellValue as D, resolveTableData as E, suggestChartNumberFix as F, tableCellDisplayValue as G, unusedDatasets as H, type ResolvedChartData as R, type ChartNumberFix as a, type ChartNumberFixOperation as b, type ChartNumberFixOptions as c, type DataColumn as d, type DataDiagnostic as e, type DataDiagnosticCode as f, type DataResolveOptions as g, type DataSourceRef as h, type DataStyledCell as i, type DataTableCell as j, type DataTableHeader as k, type DataTableValue as l, type DataTextRun as m, type Dataset as n, type DatasetRef as o, type ResolvedTableData as p, chartNumber as q, datasetDiagnostics as r, excelNumberFormat as s, formatDataNumber as t, inlineChartData as u, inlineDatasets as v, inlineTableData as w, isDatasetRef as x, isXYChartType as y, numberFormatError as z };

package/dist/{chunk-6LZK2IZB.js → chunk-7N4VMAT4.js}

@@ -1,6 +1,6 @@
-import { lintSource } from './chunk-MWPMJE6P.js';
-import { validatePresentation } from './chunk-JKVKYVWL.js';
-import { chartPaletteForFill, tableGrid, readingRows, visualReadingOrder, visitContentPayloads, intrinsicImageSize, textWidthMeasurer, normalizeHexColor, resolveColorRef, resolveScriptFonts, OPFCompositionError, resolveFontSchemeReference, DEFAULT_FONT_SCHEME, resolveCanvasDimensions, resolveFontFamilies, composeSlide } from './chunk-HOBSL7AJ.js';
+import { lintSource } from './chunk-INU7ZNSB.js';
+import { validatePresentation } from './chunk-IYCJUKWD.js';
+import { resolveChartData, chartPaletteForFill, tableGrid, readingRows, visualReadingOrder, visitContentPayloads, intrinsicImageSize, textWidthMeasurer, normalizeHexColor, resolveColorRef, resolveScriptFonts, OPFCompositionError, resolveFontSchemeReference, DEFAULT_FONT_SCHEME, resolveCanvasDimensions, resolveFontFamilies, composeSlide } from './chunk-MPM7NRG7.js';
 import { catalogs } from './chunk-E34DJ5LL.js';
 import { parseTree } from 'jsonc-parser';
 
@@ -309,8 +309,11 @@ function textValues(slide, slidePath) {
     if (Array.isArray(table.columns))
       table.columns.forEach((cell, c) => {
         const styled = rec(cell);
-        const value = Object.hasOwn(styled, "value") ? styled.value : cell;
-        push(at("table", "columns", c, ...Object.hasOwn(styled, "value") ? ["value"] : []), value, "table-header", "table");
+        if (!Object.hasOwn(styled, "value") && typeof styled.name === "string") push(at("table", "columns", c, "name"), styled.name, "table-header", "table");
+        else {
+          const value = Object.hasOwn(styled, "value") ? styled.value : cell;
+          push(at("table", "columns", c, ...Object.hasOwn(styled, "value") ? ["value"] : []), value, "table-header", "table");
+        }
       });
     if (Array.isArray(table.rows))
       table.rows.forEach((row, r) => {
@@ -864,8 +867,9 @@ var chartRules = [
       for (const slide of context.slides)
         for (const payload of slidePayloads(slide.slide, slide.path)) {
           const chart = rec(payload.node.chart);
-          const data = rec(chart.data);
-          if (!Array.isArray(data.columns) || !Array.isArray(data.rows)) continue;
+          const resolved = resolveChartData(chart, context.document);
+          if (!resolved.ok) continue;
+          const data = { columns: resolved.columns.filter((_, index) => !(resolved.hasX && index === 1)), rows: resolved.rows };
           const type = String(chart.type ?? "").toLowerCase();
           if (chartSkip.test(type)) continue;
           const slices = perCategory.test(type);