@openpresentation/opf 0.16.0 → 0.18.1

package/README.md

@@ -49,6 +49,20 @@ console.log(Object.keys(saved.catalogs.default.themes)); // ["classic"]
 console.log(Object.keys(defaultCatalog.tones));
 ```
 
+In Node (and Bun and Deno), the root adds files: `convert` turns one file into another (a deck to PDF, PNG, SVG or PPTX, a PowerPoint file to a deck, one deck form to another, or bytes with no output path), `open` reads a deck file or imports a `.pptx`, and `save` writes one. The same import works in every runtime, so one namespace import covers an application:
+
+```ts
+import * as opf from "@openpresentation/opf";
+
+await opf.convert("deck.opf.md", "deck.pdf");
+const deck = await opf.open("deck.opf.md");
+deck.slides.push({ title: "Q4" });
+await opf.save(deck, "deck.opf.md");
+const { files } = await opf.convert(deck, { format: "pptx" }); // bytes, nothing written
+```
+
+Drawing and PowerPoint go through the optional peers `@openpresentation/opf-render` and `@openpresentation/opf-pptx`, which core loads the first time a call needs them; npm does not install them for you. The root has conditional exports (OPF 0.18 removed `/node`): `node`, `bun` and `deno` get this full build, and `browser`, `worker`, `workerd` and `default` get a browser-safe build with the same names and the same types, where `open`, `save` and `convert` reject with `OPFApiError` code `node-only`. Every other subpath runs in a browser. `parseSlideSelection(3 | "1-3" | [1, 3], total)` reads slide selections in both. See [OPF files in Node](../../docs/node.md).
+
 Use focused imports when you only need one surface:
 
 ```ts
@@ -59,7 +73,7 @@ import { validate, assertValid, validationRules } from "@openpresentation/opf/va
 import type { Presentation, Audience, Tone } from "@openpresentation/opf/types";
 ```
 
-The root entry holds the application-level API: schemas, catalog references and their resolution (`resolveReference`, `embed`, `copySlides`, `updateFromCatalog`), validation, variables, pagination, data helpers, font policy, `stats` and `resolveSlideContext`. It carries no catalog records: the pinned pptx.gallery snapshot is the opt-in `@openpresentation/opf/catalog` (`defaultCatalog`, display metadata and layout previews), and every entry point that resolves references takes `{ catalogs }`, the catalogs the host registered; the first one is the default for documents that omit `catalogs.default`. See [catalogs and the default catalog](../../docs/default-catalog.md).
+The root entry holds the application-level API: schemas, catalog references and their resolution (`resolveReference`, `embed`, `copySlides`, `updateFromCatalog`), validation, variables, pagination, data helpers, font policy, `stats`, `resolveSlideContext` and `resolveSlideVariables`. Engines compose and draw `context.slide` from `resolveSlideContext(deck, index, { slideNumber, slideCount })`: the slide with the slide-scoped built-ins `{{slide.number}}`, `{{slide.section}}` and `{{deck.slideCount}}` substituted for the same numbers its `options` carry (`resolveSlideVariables(slide, { slideNumber, slideCount })` does that substitution alone). Header and footer text is substituted by `layoutFurniture`, which records each slide number in `FurnitureTextPart.fields`. See [templates and variables](../../docs/templates-and-variables.md#slide-scoped-built-ins). It carries no catalog records: the pinned pptx.gallery snapshot is the opt-in `@openpresentation/opf/catalog` (`defaultCatalog`, display metadata and layout previews), and every entry point that resolves references takes `{ catalogs }`, the catalogs the host registered; the first one is the default for documents that omit `catalogs.default`. See [catalogs and the default catalog](../../docs/default-catalog.md).
 
 The layout engine's names are not on the root. `composeSlide`, `fitText`, `layoutQuote` and the other `layoutX`/`fitX` functions, numbering, footnotes and citations, colour contrast, code syntax, pattern fills, metric trends, chart options, script fonts and text direction come from `@openpresentation/opf/composition`; the symbol-font tables come from `@openpresentation/opf/symbol-font-encodings`.
 
@@ -77,7 +91,7 @@ The layout engine's names are not on the root. `composeSlide`, `fitText`, `layou
 
 ### Reading and writing a deck in any form
 
-`readDeck(text, { format, filename, catalogs, validate })` and `writeDeck(presentation, { format | filename })` (the root and `@openpresentation/opf/deck`) read and write a deck as JSON (canonical), YAML or Markdown. The format is the `format` option, else the file name (`.opf.md` is Markdown, `.yaml` and `.yml` are YAML, anything else JSON; a plain `.md` is not a deck), and never the content. `readDeck` returns `{ presentation, format, valid, findings, counts, schemaValid, checks }`: the `validate` report of the deck, with every finding located in the text that was read (`opf/json-syntax`, `yaml/<rule>` or `markdown/<rule>` for syntax errors) and no exception for malformed content. It runs in a browser.
+`parse(text, { format, filename, catalogs })` and `stringify(presentation, { format | filename })` (the root and `@openpresentation/opf/deck`) read and write a deck as JSON (canonical), YAML or Markdown. The format is the `format` option, else the file name (`.opf.md` is Markdown, `.yaml` and `.yml` are YAML, anything else JSON; a plain `.md` is not a deck), and never the content. `parse` returns the presentation and throws `OPFValidationError` for a syntax, schema or reference error; the error's `report.findings` are located by line and column in the text (`opf/json-syntax`, `yaml/<rule>` or `markdown/<rule>` for syntax errors). Warnings do not throw: `validate(text)` returns the full report. Both run in a browser; files are the Node build's job (above).
 
 ### OPF as YAML
 

package/dist/browser.js

@@ -0,0 +1,38 @@
+import { OPFApiError } from './chunk-QLFWWHRF.js';
+export { OPFApiError, OPFExportError, OPFImportError, OPFMoveToCustomError, copySlides, edit, embed, fill, fillRecords, moveToCustom, parseSlideSelection, sameRecord, stats, updateFromCatalog } from './chunk-QLFWWHRF.js';
+export { specFileEntries, specFileKinds, specFilePaths } from './chunk-HXHOZ7AH.js';
+export { OPFDataImportError, ingest, parseTabularData } from './chunk-ZCFSDSUX.js';
+export { DECK_FORMATS, deckFormatOf, parse, stringify } from './chunk-ZOHFLP3O.js';
+export { fromMarkdown, toMarkdown } from './chunk-DBYZI75U.js';
+import './chunk-NS3VYB57.js';
+export { OPFMarkdownError } from './chunk-CJPDTLGD.js';
+export { diff, merge } from './chunk-YWXB4XAT.js';
+export { OPFPatchError, OPFPatchValidationError, applyPatch } from './chunk-YZXTXX2D.js';
+export { OPFFormatError, format } from './chunk-JXVS7BJK.js';
+export { OPFPaginationError, paginate, paginateSlide } from './chunk-64YSJZDH.js';
+import './chunk-VCGRMNY2.js';
+import './chunk-RAKEVM52.js';
+export { DEFAULT_CHART_PALETTE, DEFAULT_VALIDATION_THRESHOLDS, OPFValidationError, assertValid, assertValidCatalogRecord, findValidationRule, resolveSlideContext, validate, validateCatalogRecord, validationCategories, validationRules } from './chunk-JT3QXA22.js';
+export { CHART_TYPES, DEFAULT_VARIABLE_DATE_FORMAT, ENGINE_DEFAULT_CHART_TYPES, ENGINE_DEFAULT_COLOR_SCHEME, ENGINE_DEFAULT_FONT_SCHEME, ENGINE_DEFAULT_THEME, LANGUAGES, LOGO_SHAPES, OPFVariableError, SLIDE_SCOPED_BUILTINS, SOCIAL_PLATFORMS, VARIABLE_KINDS, chartNumber, coerceVariableValue, datasetDiagnostics, formatDataNumber, formatVariableNumber, fromExcelNumberFormat, hasContentVariables, inlineChartData, inlineDatasets, inlineTableData, isDatasetRef, isTemplate, isXYChartType, listBuiltinVariables, listVariables, normalizeLanguageFamily, numberFormatError, resolveChartData, resolveDesignRecords, resolveFontScheme, resolveSlideVariables, resolveTableData, resolveVariables, suggestChartNumberFix, tableCellDisplayValue, toExcelNumberFormat, unusedDatasets, variableDeclarations } from './chunk-MBU42S5Y.js';
+export { catalogDisplayKinds, catalogSchemaNames } from './chunk-TRDXRRQK.js';
+export { CATALOG_GROUP_PATTERN, CATALOG_REFERENCE_PATTERN, OPFCatalogsOptionError, OPFUnresolvedReferenceError, catalogGroupSource, catalogKinds, catalogRecords, catalogReferenceSites, parseReference, resolveReference, unresolvedReference } from './chunk-SPFV27O5.js';
+export { audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone } from './chunk-6WW2EDUW.js';
+export { FONT_POLICY, applyFontPolicyDecisions, fontAvailabilityDiagnostics, fontPolicyFor } from './chunk-WXSPETQ6.js';
+
+// src/browser.ts
+var nodeOnly = (name, message) => new OPFApiError(`\`${name}\` ${message}`, "node-only", { details: { function: name, build: "browser" } });
+var PARSE = "In a browser or a worker, read the text yourself and call parse(text, { filename }).";
+var STRINGIFY = "In a browser or a worker, call stringify(deck, { filename }) and store or download the text.";
+var CONVERT = "In a browser or a worker, change deck forms with parse and stringify (YAML, Markdown, JSON), and draw slides with @openpresentation/opf-render's /export-browser entry.";
+var open = async () => {
+  throw nodeOnly("open", `reads files and needs Node. ${PARSE}`);
+};
+var save = async () => {
+  throw nodeOnly("save", `writes files and needs Node. ${STRINGIFY}`);
+};
+var convert = (async (_input, output) => {
+  const inMemory = output !== null && typeof output === "object";
+  throw nodeOnly("convert", inMemory ? `needs Node in OPF 0.18, also for the in-memory convert(deck, { format }). ${CONVERT}` : `reads and writes files and needs Node. ${CONVERT}`);
+});
+
+export { convert, open, save };

package/dist/{catalog-refs-_anZs-Qz.d.ts → catalog-refs-BSfGELpt.d.ts}

@@ -125,4 +125,4 @@ declare function catalogReferenceSites(document: unknown, options?: {
 /** Records a picker can offer for `kind`: the document's embedded records, then those of the registered catalogs its groups name, with the reference to write for each. */
 declare function catalogRecords(document: unknown, kind: CatalogKind, options?: CatalogOptions): ResolvedReference[];
 
-export { type Catalog as C, OPFCatalogsOptionError as O, type RecordProvenance as R, type UnresolvedReferenceDiagnostic as U, type CatalogKind as a, type CatalogOptions as b, CATALOG_GROUP_PATTERN as c, CATALOG_REFERENCE_PATTERN as d, type CatalogRecordMap as e, type CatalogRecords as f, type CatalogReferenceSite as g, OPFUnresolvedReferenceError as h, type ResolvedReference as i, catalogGroupSource as j, catalogKinds as k, catalogRecords as l, catalogReferenceSites as m, parseReference as p, resolveReference as r, unresolvedReference as u };
+export { type CatalogKind as C, OPFCatalogsOptionError as O, type RecordProvenance as R, type UnresolvedReferenceDiagnostic as U, type Catalog as a, type CatalogOptions as b, CATALOG_GROUP_PATTERN as c, CATALOG_REFERENCE_PATTERN as d, type CatalogRecordMap as e, type CatalogRecords as f, type CatalogReferenceSite as g, OPFUnresolvedReferenceError as h, type ResolvedReference as i, catalogGroupSource as j, catalogKinds as k, catalogRecords as l, catalogReferenceSites as m, parseReference as p, resolveReference as r, unresolvedReference as u };

package/dist/{catalog-schemas-BZCjgAxu.d.ts → catalog-schemas-CinPh5WA.d.ts}

@@ -1,4 +1,4 @@
-import { a as CatalogKind } from './catalog-refs-_anZs-Qz.js';
+import { C as CatalogKind } from './catalog-refs-BSfGELpt.js';
 import { SchemaName } from './schemas.js';
 
 /** Kinds of catalog display metadata: published by catalogs for pickers, never referenced by documents. */

package/dist/catalog.d.ts

@@ -1,5 +1,5 @@
-import { C as Catalog } from './catalog-refs-_anZs-Qz.js';
-import { C as CatalogDisplayKind } from './catalog-schemas-BZCjgAxu.js';
+import { a as Catalog } from './catalog-refs-BSfGELpt.js';
+import { C as CatalogDisplayKind } from './catalog-schemas-CinPh5WA.js';
 import './schemas.js';
 import './json-BFSdESOE.js';