@openpresentation/opf-pptx 0.11.5 → 0.11.7

package/dist/index.d.ts

@@ -39,6 +39,8 @@ export interface MediaProvenanceDiagnostic { code: "media-provenance-omitted"; p
 export interface ChartDataUnplottableDiagnostic { code: "chart-data-unplottable"; path: string; message: string; reason: "data-not-inline" | "no-rows" | "no-columns" | "single-column-not-numeric" }
 /** Content with no PowerPoint export (an empty table, an unsupported payload) is replaced by a plain-language placeholder frame. */
 export interface ContentPlaceholderDiagnostic { code: "content-placeholder"; path: string; message: string; reason: "table-has-no-rows" | "unsupported-payload" }
+/** An image that has no embeddable raster. `reason: "unsupported-format"`: the embedded bytes are no readable PNG, JPEG, GIF or WebP (an SVG, for example); the preview's placeholder was exported instead (or no watermark, or the background colour). `strictAssets` throws `unsupported-image-dimensions` instead. */
+export interface UnresolvedAssetDiagnostic { code: "unresolved-asset"; path: string; message: string; reason?: "unsupported-format" }
 export interface WatermarkNotExportedDiagnostic { code: "watermark-not-exported"; path: string; message: string }
 /**
  * The chart data was reshaped to export a native chart: a single value column was plotted against row numbers; a one-series construct
@@ -47,7 +49,7 @@ export interface WatermarkNotExportedDiagnostic { code: "watermark-not-exported"
  * (`histogram-binned`).
  */
 export interface ChartDataAdaptedDiagnostic { code: "chart-data-adapted"; path: string; message: string; adaptation: "histogram-binned" | "row-numbers" | "series-dropped" | "chartex-fallback" }
-/** With `chartex: "native"`, a map chart (`world`) is exported as a chartex regionMap without cached geography: PowerPoint fetches the region shapes from Bing Maps online, so the map may show no regions offline. */
+/** With `chartex: "native"`, a map chart (`world`) is exported as a chartex regionMap (`Requires="cx4"`) without cached geography: PowerPoint must fetch the region shapes from its online map service and shows "There was a problem getting the information for your map chart" with an empty chart until it does. */
 export interface ChartMapGeodataDiagnostic { code: "chart-map-geodata"; path: string; message: string }
 
 export interface ToPptxOptions {
@@ -55,25 +57,32 @@ export interface ToPptxOptions {
   imageFormat?: "compatible" | "preserve";
   /**
    * How the chartex chart types (treemap, histogram, pareto, box-and-whisker, waterfall, funnel, world) are exported.
-   * "fallback" (default) writes the clustered column chart of the data and reports `chart-data-adapted` (`chartex-fallback`,
-   * `histogram-binned`). "native" writes Office 2016 chartex parts (`cx:chartSpace`, style parts, an `mc:AlternateContent`
-   * frame with the clustered column chart as fallback). Native chartex is opt-in pending native PowerPoint confirmation (FF-22b);
-   * the default flips once that check passes. Import of chartex parts is always on.
+   * "auto" (default) writes Office 2016 chartex parts (`cx:chartSpace`, style parts, an `mc:AlternateContent` frame with the
+   * clustered column chart as fallback) for the constructs desktop PowerPoint confirmed natively on 2026-09-30 (treemap,
+   * histogram, pareto, box-and-whisker, waterfall, funnel) and keeps `world` on the clustered column chart with
+   * `chart-data-adapted` (`chartex-fallback`) because the regionMap part, though accepted with `Requires="cx4"`, draws
+   * nothing until PowerPoint fetches map data online. "native" writes every chartex part, the map included (reports
+   * `chart-map-geodata`). "fallback" writes clustered columns only
+   * (`chartex-fallback`, `histogram-binned`), as releases before FF-22b did. Import of chartex parts is always on.
    */
-  chartex?: "native" | "fallback";
+  chartex?: "auto" | "native" | "fallback";
   /**
    * OPF_DOCUMENT_V1 / OPF_SLIDE_V1 customer-data tags that let fromPptx restore
-   * catalog references, layout ids and authoring metadata (docs/document-roundtrip.md).
+   * catalog references, layout ids, authoring metadata (`filename` and `extensions`
+   * included), `design.logo`, the asset registry, slide `section`/`extensions` and
+   * the slide content structure: nested groups, promoted regions, the root payload
+   * form, block ids and extensions, group composition (docs/document-roundtrip.md).
    * Tags are not shown in PowerPoint's UI. Default "full"; "references-only"
-   * stores catalog references without organization, speaker, free text, slide ids
-   * or assets; false writes no tags.
+   * stores catalog references without organization, speaker, free text, slide ids,
+   * assets or content structure; false writes no tags. Slide `section` labels are
+   * also written as PowerPoint's native section list whatever this option says.
    */
   provenance?: "full" | "references-only" | false;
   textMeasurement?: TextMeasurement;
   /** Match preview/pagination clearance around supplied vector text outlines; default 1. */
   textRasterPadding?: number;
   /** Layout diagnostics, `media-provenance-omitted` when video data cannot be stored, plus `unresolved-font-scheme` (once per reference path) when a font-scheme id matches no record and the default `aptos` scheme is used as the base. */
-  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ContentPlaceholderDiagnostic | WatermarkNotExportedDiagnostic) => void;
+  onDiagnostic?: (diagnostic: LayoutDiagnostic | FontSchemeDiagnostic | MediaProvenanceDiagnostic | ChartDataUnplottableDiagnostic | ChartDataAdaptedDiagnostic | ChartMapGeodataDiagnostic | ContentPlaceholderDiagnostic | UnresolvedAssetDiagnostic | WatermarkNotExportedDiagnostic) => void;
   baseDir?: string;
   compressionLevel?: number;
   imageResolver?: (src: string, context: ImageResolverContext) => ImageResolverResult | Promise<ImageResolverResult | null | undefined> | null | undefined;
@@ -97,12 +106,12 @@ export interface ToPptxOptions {
   date?: string;
   /** Host-supplied catalog records, as in opf-render. Currently consulted for socialPlatforms (generated socials furniture). */
   catalogs?: Record<string, { records?: unknown[] } | unknown[]>;
-  /** Records for document `catalogs.<kind>.source` URLs, as in opf-render. Currently consulted for socialPlatforms. */
+  /** Records for document `catalogs.<kind>.source` URLs (a single source or each entry of an ordered search path), as in opf-render. Currently consulted for socialPlatforms. */
   catalogSources?: Record<string, { records?: unknown[] } | unknown[]>;
 }
 
 export interface FromPptxOptions {
-  /** Reports native details that import cannot preserve, including code provenance fallback/reflow and grouped text transforms. Table paths identify native frame and row/cell indexes (including headers). Stored catalog references that no longer match the package report `design-reference-changed` / `layout-reference-changed` at the reference path; a slide layout id that resolves to no inline or bundled record reports `unresolved-layout-reference` (docs/document-roundtrip.md). */
+  /** Reports native details that import cannot preserve, including code provenance fallback/reflow and grouped text transforms. Table paths identify native frame and row/cell indexes (including headers). Stored catalog references that no longer match the package report `design-reference-changed` / `layout-reference-changed` at the reference path; a slide layout id that resolves to no inline or bundled record reports `unresolved-layout-reference`; a slide whose imported blocks no longer fit the stored content structure reports `content-structure-changed` at `slides.N`, a block id repeated by a duplicated slide `duplicate-block-id`, and a footer section text that disagrees with PowerPoint's section list `section-reference-changed` (docs/document-roundtrip.md). */
   onDiagnostic?: (diagnostic: {code: string; path: string; message: string}) => void;
   fallbackName?: string;
   schema?: string;