@reportwright/engine 0.12.0 → 0.13.0

package/dist/pdfstreamworker.js

@@ -21,7 +21,7 @@ parentPort.on('message', async (/** @type {any} */ job) => {
     const m = await render(job.def, { ...job.opts, fontStore, sources: { __rows: { rows: job.rows } }, pageWindow: job.pageWindow });
     // a writer of its own for the names and glyphs (nothing is written): the pages' links name pages by placeholder
     const rec = createPdfStream({ write() {} }, { fontStore });
-    const env = paintEnv(rec, fontStore, { drillBase: job.drillBase, pageRef: (i) => `@@P${i}@@` });
+    const env = paintEnv(rec, fontStore, { drillBase: job.drillBase, pageRef: (i) => `@@P${i}@@`, embedAll: job.embedAll });
     const pages = [], transfer = [];
     for (let k = 0; k < Math.min(job.keep, m.pages.length); k++) {
       const pg = m.pages[k];
@@ -31,7 +31,7 @@ parentPort.on('message', async (/** @type {any} */ job) => {
       pages.push({ deflated: z, annots, width: pg.width, height: pg.height, firstRow: pg.firstRow, rowHead: pg.rowHead, headLevel: pg.headLevel });
     }
     parentPort.postMessage({ id: job.id, count: m.pages.length, nextFirst: m.pages[job.keep]?.firstRow, pages, used: rec.used(),
-      shaped: [...env.shaped].map(([k, g]) => [k, [...g]]), bookmarks: m.bookmarks, headings: m.headings, warnings: m.warnings, ms: Date.now() - t0 }, transfer);
+      shaped: [...env.shaped].map(([k, g]) => [k, [...g]]), embedded: [...env.embedded || []], bookmarks: m.bookmarks, headings: m.headings, warnings: m.warnings, ms: Date.now() - t0 }, transfer);
   } catch (e) {
     parentPort.postMessage({ id: job.id, error: { message: String(/** @type {any} */ (e)?.message || e), status: /** @type {any} */ (e)?.status, timeout: /** @type {any} */ (e)?.timeout } });
   }

package/dist/types/packages/engine/entry.d.ts

@@ -8,6 +8,7 @@
 export function defaultFontStore(opts?: {
     fontsUrl?: string;
 }): FontStore;
+export function render(def0: any, opts?: import("../../src/engine/index.js").RenderOptions): Promise<any>;
 /**
  * @typedef {Omit<NonNullable<Parameters<typeof exportPdfFull>[2]>, 'subset' | 'pdfa'> & {
  *   fonts?: FontStore, subset?: false | NonNullable<Parameters<typeof exportPdfFull>[2]>['subset'],
@@ -49,10 +50,17 @@ export function exportPptx(model: any, options?: NonNullable<Parameters<typeof e
     fonts?: FontStore;
 }, ...args: any[]): Promise<Uint8Array>;
 /**
- * @typedef {RenderOptions & Omit<PdfOptions, 'fonts'> & { fonts?: FontStore, tagged?: { lang?: string },
- *   window?: number, parallel?: number, maxRows?: number, id?: string }} PdfStreamOptions
+ * @typedef {RenderOptions & Omit<PdfOptions, 'fonts'> & { fonts?: FontStore, tagged?: { lang?: string, maxElements?: number },
+ *   window?: number, parallel?: number, maxRows?: number, id?: string, presorted?: boolean, signal?: AbortSignal,
+ *   spill?: false | { dir?: string, maxMB?: number }, sorter?: (cmp: (a: any, b: any) => number) => any }} PdfStreamOptions
  *   render()'s options and exportPdf's, plus: window (rows laid out at once, 1000), parallel (Node: worker threads
- *   that lay out and paint pages, opt-in; the file is the same), maxRows (rows read, 5,000,000), id (the file ID).
+ *   that lay out and paint pages, opt-in; the file is the same, each thread costs memory), maxRows (rows read,
+ *   5,000,000), id (the file ID). presorted: the rows come in the report's order (its sort, its groups together), so
+ *   they are not sorted, only checked as they pass (a row out of order stops the export). spill: where a sort's runs go
+ *   (Node: the system temp folder, 2 GB at most; false sorts in memory); in a browser a sort is in memory.
+ *   timeoutMs: the whole export's time limit, waits for the sink included (504, code 'ETIMEDOUT'). signal: an
+ *   AbortSignal that stops the export at its next wait (rejects with the signal's reason, an AbortError); sqlRows gets
+ *   it as its third argument ({ signal }) so a database cursor can cancel its query.
  */
 /**
  * Report definition → PDF written to a sink as it is made, for reports too large to hold as a page model: a flowing
@@ -73,6 +81,66 @@ export function exportPdfStream(def: any, options: PdfStreamOptions, sink: {
     warnings: string[];
     why?: string;
 }>;
+/**
+ * Report definition → .docx written to a sink as its pages are laid out (exportPdfStream's sink, timeoutMs, signal,
+ * window, maxRows, sqlRows and spill): a flowing table report is never held whole; any other report is rendered whole
+ * and written in one piece (the result's why says why).
+ * @param {any} def @param {RenderOptions & { fonts?: FontStore, title?: string, lang?: string, figures?: boolean, timeoutMs?: number, signal?: AbortSignal,
+ *   window?: number, maxRows?: number, spill?: false | { dir?: string, maxMB?: number } }} options
+ * @param {{ write(bytes: Uint8Array): any, once?: (ev: string, cb: () => void) => any }} sink not closed
+ * @returns {Promise<{ streamed: boolean, pages?: number, warnings: string[], why?: string }>}
+ */
+export function exportDocxStream(def: any, options: RenderOptions & {
+    fonts?: FontStore;
+    title?: string;
+    lang?: string;
+    figures?: boolean;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    window?: number;
+    maxRows?: number;
+    spill?: false | {
+        dir?: string;
+        maxMB?: number;
+    };
+}, sink: {
+    write(bytes: Uint8Array): any;
+    once?: (ev: string, cb: () => void) => any;
+}): Promise<{
+    streamed: boolean;
+    pages?: number;
+    warnings: string[];
+    why?: string;
+}>;
+/**
+ * Report definition → .xlsx written to a sink row by row (exportPdfStream's sink, timeoutMs, signal, maxRows, sqlRows
+ * and spill); any other report is rendered whole and written in one piece (the result's why says why).
+ * @param {any} def @param {RenderOptions & { fonts?: FontStore, title?: string, currency?: string, formulas?: boolean, timeoutMs?: number, signal?: AbortSignal,
+ *   maxRows?: number, spill?: false | { dir?: string, maxMB?: number } }} options
+ * @param {{ write(bytes: Uint8Array): any, once?: (ev: string, cb: () => void) => any }} sink not closed
+ * @returns {Promise<{ streamed: boolean, rows?: number, warnings: string[], why?: string }>}
+ */
+export function exportXlsxStream(def: any, options: RenderOptions & {
+    fonts?: FontStore;
+    title?: string;
+    currency?: string;
+    formulas?: boolean;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    maxRows?: number;
+    spill?: false | {
+        dir?: string;
+        maxMB?: number;
+    };
+}, sink: {
+    write(bytes: Uint8Array): any;
+    once?: (ev: string, cb: () => void) => any;
+}): Promise<{
+    streamed: boolean;
+    rows?: number;
+    warnings: string[];
+    why?: string;
+}>;
 export { validate } from "../../src/engine/schema/validate.js";
 export { exportHtml } from "../../src/exporters/html.js";
 export { exportCsv } from "../../src/exporters/csv.js";
@@ -95,17 +163,31 @@ export type PdfOptions = Omit<NonNullable<Parameters<typeof exportPdfFull>[2]>,
 };
 /**
  * render()'s options and exportPdf's, plus: window (rows laid out at once, 1000), parallel (Node: worker threads
- * that lay out and paint pages, opt-in; the file is the same), maxRows (rows read, 5,000,000), id (the file ID).
+ * that lay out and paint pages, opt-in; the file is the same, each thread costs memory), maxRows (rows read,
+ * 5,000,000), id (the file ID). presorted: the rows come in the report's order (its sort, its groups together), so
+ * they are not sorted, only checked as they pass (a row out of order stops the export). spill: where a sort's runs go
+ * (Node: the system temp folder, 2 GB at most; false sorts in memory); in a browser a sort is in memory.
+ * timeoutMs: the whole export's time limit, waits for the sink included (504, code 'ETIMEDOUT'). signal: an
+ * AbortSignal that stops the export at its next wait (rejects with the signal's reason, an AbortError); sqlRows gets
+ * it as its third argument ({ signal }) so a database cursor can cancel its query.
  */
 export type PdfStreamOptions = RenderOptions & Omit<PdfOptions, "fonts"> & {
     fonts?: FontStore;
     tagged?: {
         lang?: string;
+        maxElements?: number;
     };
     window?: number;
     parallel?: number;
     maxRows?: number;
     id?: string;
+    presorted?: boolean;
+    signal?: AbortSignal;
+    spill?: false | {
+        dir?: string;
+        maxMB?: number;
+    };
+    sorter?: (cmp: (a: any, b: any) => number) => any;
 };
 export type RenderOptions = import("../../src/engine/index.js").RenderOptions;
 import { FontStore } from '../../src/engine/index.js';
@@ -120,6 +202,6 @@ import { paintEnv } from '../../src/exporters/pdfstream.js';
 import { latin1 } from '../../src/exporters/pdfpaint.js';
 import { exportPdf as exportPdfFull } from '../../src/exporters/pdf.js';
 export { fontFile, createSubsetter };
-export { render, FontStore, ITEMS, parameterOptions, resolveParameters } from "../../src/engine/index.js";
+export { FontStore, ITEMS, parameterOptions, resolveParameters } from "../../src/engine/index.js";
 export { blankReport, blankDashboard } from "../../src/engine/schema/template.js";
 export { tableFor, matrixFor } from "../../src/designer/tableGen.js";

package/dist/types/src/engine/data/guard.d.ts

@@ -16,11 +16,14 @@ export function redirectRequest(from: URL, to: URL, req: any, status: number): a
 /**
  * The guarded default fetch (see the top of this file). In Node every hop goes through nodeRequest (address pinned);
  * in a browser through `base` with redirects by hand (literal addresses checked; a browser has no DNS to ask).
- * @param {{ allowHosts?: string[] }} opt @param {typeof fetch} base
+ * @param {{ allowHosts?: string[], viaBase?: boolean }} opt viaBase: every hop through `base`, in Node too (the browser
+ *   viewer's fetch, which its tests run in Node)
+ * @param {typeof fetch} base
  * @returns {typeof fetch}
  */
 export function guardedFetch(opt: {
     allowHosts?: string[];
+    viaBase?: boolean;
 }, base: typeof fetch): typeof fetch;
 /**
  * Any fetch with the engine's time limit and byte cap.

package/dist/types/src/engine/data/index.d.ts

@@ -13,13 +13,26 @@ export function jsonPathRows(obj: any, path: any): {
  * A raw value as the field's type. Numbers in text are read the locale's way ("12,5" and "1.234,56" in de-DE, "1,234.5"
  * and "(1,234)" in en-US); dates without a zone are the wall clock of the report's zone. A value that does not read
  * is null, and opt.bad hears of it (the data set warns once).
- * @param {any} v @param {string} type @param {{ locale?: string, timeZone?: string, bad?: (v: any) => void }} [opt]
+ * @param {any} v @param {string} type @param {{ locale?: string, timeZone?: string, bad?: (v: any) => void, empty?: () => void }} [opt]
  */
 export function coerce(v: any, type: string, opt?: {
     locale?: string;
     timeZone?: string;
     bad?: (v: any) => void;
+    empty?: () => void;
 }): any;
+/**
+ * Counts, per field, the values that do not read as the field's type (and the empty ones), for one warning per field.
+ * Shared by the whole render (buildDataSets) and the streaming export, which both type rows with coerce().
+ * @param {string} dsName @param {(msg: string) => void} warn
+ */
+export function badValues(dsName: string, warn: (msg: string) => void): {
+    /** the row being typed, 1-based */
+    at: (n: number) => void;
+    /** coerce() options for one field, on top of base */
+    opt: (fd: any, base: any) => any;
+    done: () => void;
+};
 /**
  * Guess field names and types from sample rows. A string that looks like an ISO date (2024-01-31, 2024-01-31T10:00Z)
  * becomes a date field; dates: false (a data set's detectDates: false) keeps it text. To keep one field as text,

package/dist/types/src/engine/expr/evaluate.d.ts

@@ -92,6 +92,7 @@ export const OVER_TIME: "The report ran past its time limit.";
 export const ROW_PARENT: WeakMap<object, any>;
 /** The aggregates a streaming export folds row by row (aggregator). */
 export const FOLDS: Set<string>;
+export function isAggregate(name: any): boolean;
 export namespace FUNCTIONS {
     function format(ctx: any, v: any, f: any): any;
     function upper(ctx: any, s: any): any;

package/dist/types/src/engine/index.d.ts

@@ -70,8 +70,6 @@ export class ReportError extends Error {
     constructor(msg: string, extra?: object);
 }
 export const BAND_ITEMS: 250000;
-/** The start of the warning for CJK text without the optional CJK fonts (the viewer opens its warnings for it). */
-export const NO_CJK_FONTS: "Text in Japanese/Chinese/Korean needs the optional CJK fonts: npm run fonts:cjk";
 /**
  * Options for render(). All optional.
  */
@@ -90,6 +88,10 @@ export type RenderOptions = {
      * the fonts; share one across renders (a new one loads them again)
      */
     fontStore?: import("./text/fonts.js").FontStore;
+    /**
+     * the viewer: load only the core face up front; the other bundled faces when the layout first needs one
+     */
+    lazyFonts?: boolean;
     /**
      * loads a font the store does not have
      */
@@ -174,6 +176,11 @@ export type RenderOptions = {
      * the zone dates show in, when the report sets none
      */
     timeZone?: string;
+    /**
+     * the engine package's render() warns once (model.warnings, and the console once
+     * per process) when a data set has more rows than this, pointing at exportPdfStream (default 100000; 0 or false: no warning)
+     */
+    largeReportRows?: number | false;
     /**
      * internal (subreports): the width the child body is laid out to
      */
@@ -232,8 +239,9 @@ export type RenderOptions = {
         } | null)[];
     };
 };
+import { NO_CJK_FONTS } from './notices.js';
 import { FontStore } from './text/fonts.js';
 import { TextMeasurer } from './text/measure.js';
 import { ITEMS } from './items/index.js';
 import { finishText } from './text/measure.js';
-export { FontStore, TextMeasurer, ITEMS, finishText };
+export { NO_CJK_FONTS, FontStore, TextMeasurer, ITEMS, finishText };

package/dist/types/src/engine/items/chart-kit.d.ts

@@ -10,6 +10,12 @@ export function niceScale(min: any, max: any, ticks?: number): {
     hi: number;
     step: number;
 };
+/** A nice scale whose step is the span over the ticks: niceScale rounds the span first, which can add a whole step. */
+export function niceScaleSpan(min: any, max: any, ticks?: number): {
+    lo: number;
+    hi: number;
+    step: number;
+};
 /** Ticks from lo to hi by step, rounded so 0.1 + 0.2 reads 0.3. At most 200 (a bad min/max cannot loop for ever). */
 export function linearTicks(lo: any, hi: any, step: any): any[];
 /** Powers of ten covering [min, max] (both > 0); at least two. */

package/dist/types/src/engine/lazylibs.d.ts

@@ -0,0 +1,46 @@
+/**
+ * pdf-lib and fontkit, loaded on first use rather than at import: evaluating them was most of the engine's import time
+ * (about 110 ms and 180 ms on an M2). await loadFontkit() (a font is parsed) or loadPdfLib() (exportPdf) first; the
+ * bindings below are set then (ES modules' live bindings: `import { PDFName } from './lazylibs.js'` sees them).
+ * Node: require() (both are CommonJS; import() of one costs ~60 ms more, its named exports read by Node's CJS lexer
+ * through every re-exported file). Elsewhere (a bundler, a browser): import(), which a bundler may split into a chunk.
+ */
+/** @typedef {typeof import('pdf-lib')} PdfLib */
+/** @typedef {import('pdf-lib').PDFDocument} PDFDocument */
+/** @typedef {import('pdf-lib').PDFName} PDFName */
+/** @typedef {import('pdf-lib').PDFString} PDFString */
+/** @typedef {import('pdf-lib').PDFHexString} PDFHexString */
+/** @typedef {import('pdf-lib').PDFRawStream} PDFRawStream */
+/** @typedef {import('pdf-lib').PDFStream} PDFStream */
+/** @typedef {import('pdf-lib').PDFArray} PDFArray */
+/** @typedef {import('pdf-lib').PDFDict} PDFDict */
+/** @typedef {import('pdf-lib').PDFNumber} PDFNumber */
+/** @typedef {import('pdf-lib').PDFBool} PDFBool */
+/** @type {any} @pdf-lib/fontkit */ export let fontkit: any;
+export type PDFDocument = import("pdf-lib").PDFDocument;
+/** @type {PdfLib['PDFDocument']} */ export let PDFDocument: PdfLib["PDFDocument"];
+export type PDFName = import("pdf-lib").PDFName;
+/** @type {PdfLib['PDFName']} */ export let PDFName: PdfLib["PDFName"];
+export type PDFString = import("pdf-lib").PDFString;
+/** @type {PdfLib['PDFString']} */ export let PDFString: PdfLib["PDFString"];
+export type PDFHexString = import("pdf-lib").PDFHexString;
+/** @type {PdfLib['PDFHexString']} */ export let PDFHexString: PdfLib["PDFHexString"];
+export type PDFRawStream = import("pdf-lib").PDFRawStream;
+/** @type {PdfLib['PDFRawStream']} */ export let PDFRawStream: PdfLib["PDFRawStream"];
+export type PDFStream = import("pdf-lib").PDFStream;
+/** @type {PdfLib['PDFStream']} */ export let PDFStream: PdfLib["PDFStream"];
+export type PDFArray = import("pdf-lib").PDFArray;
+/** @type {PdfLib['PDFArray']} */ export let PDFArray: PdfLib["PDFArray"];
+export type PDFDict = import("pdf-lib").PDFDict;
+/** @type {PdfLib['PDFDict']} */ export let PDFDict: PdfLib["PDFDict"];
+export type PDFNumber = import("pdf-lib").PDFNumber;
+/** @type {PdfLib['PDFNumber']} */ export let PDFNumber: PdfLib["PDFNumber"];
+export type PDFBool = import("pdf-lib").PDFBool;
+/** @type {PdfLib['PDFBool']} */ export let PDFBool: PdfLib["PDFBool"];
+/** @type {PdfLib['rgb']} */ export let rgb: PdfLib["rgb"];
+/** @type {PdfLib['pushGraphicsState']} */ export let pushGraphicsState: PdfLib["pushGraphicsState"];
+/** @type {PdfLib['popGraphicsState']} */ export let popGraphicsState: PdfLib["popGraphicsState"];
+/** @type {PdfLib['concatTransformationMatrix']} */ export let concatTransformationMatrix: PdfLib["concatTransformationMatrix"];
+export function loadFontkit(): Promise<void>;
+export function loadPdfLib(): Promise<void>;
+export type PdfLib = typeof import("pdf-lib");

package/dist/types/src/engine/notices.d.ts

@@ -0,0 +1 @@
+export const NO_CJK_FONTS: "Text in Japanese/Chinese/Korean needs the optional CJK fonts: npm i @reportwright/fonts-cjk, then npx reportwright-fonts-cjk (npm); in the app, npm run fonts:cjk";

package/dist/types/src/engine/options.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The warnings for the keys of opts that are not options, each with the nearest option (Levenshtein 2 at most) as
+ * "Did you mean". A key close to a security option (encrypt, prepare) throws instead: carrying on would write a file
+ * without the password or signature the caller asked for.
+ * @param {any} opts @param {Set<string>} [known]
+ * @returns {string[]}
+ */
+export function checkOptions(opts: any, known?: Set<string>): string[];
+/** every option the three functions (and what they pass on) read */
+export const KNOWN_OPTIONS: Set<string>;

package/dist/types/src/engine/schema/report.schema.d.ts

@@ -1210,6 +1210,9 @@ export namespace REPORT_SCHEMA {
                     fieldName: {
                         "x-ts": string;
                     };
+                    label: {
+                        "x-ts": string;
+                    };
                     value: {
                         "x-ts": string;
                     };

package/dist/types/src/engine/stream.d.ts

@@ -1,5 +1,5 @@
 /**
- * An in-memory sorter (the browser, the CLI): the server passes one that spills runs to disk (server/spill.js).
+ * An in-memory sorter (the browser, the CLI): the server passes one that spills runs to disk (exporters/spill.js; exportPdfStream's default in Node).
  * @param {(a: any, b: any) => number} cmp
  */
 export function memorySorter(cmp: (a: any, b: any) => number): {
@@ -11,43 +11,40 @@ export function memorySorter(cmp: (a: any, b: any) => number): {
  * @param {any} def0 the report definition
  * @param {{ format: 'csv'|'xlsx', parameters?: object, timeZone?: string, now?: Date, state?: any, loadReport?: (id: string) => Promise<any>,
  *   reportId?: string, fetch?: typeof fetch, baseUrl?: string, sql?: (src: any, p: any) => Promise<object[]>,
- *   sqlRows?: (src: any, p: any) => AsyncIterable<object[]>, sources?: Record<string, any>, sorter?: (cmp: (a: any, b: any) => number) => any,
+ *   sqlRows?: (src: any, p: any, o: { signal?: AbortSignal }) => AsyncIterable<object[]>, signal?: AbortSignal, sources?: Record<string, any>, sorter?: (cmp: (a: any, b: any) => number) => any, presorted?: boolean,
  *   deadline?: number, timeoutMs?: number, maxRows?: number, maxJsonRowBytes?: number, maxJsonWholeBytes?: number }} opts
- * @returns {Promise<{ why: string } | { why?: undefined, name: string, columns: number[], title: string, timeZone: string|null, locale: string|null, currency: string|null, warnings: string[], rows: () => AsyncGenerator<any>, records: () => AsyncGenerator<any>, grouped: () => AsyncGenerator<any>, stats: { rows: number } }>}
+ * @returns {Promise<{ why: string } | { why?: undefined, name: string, columns: number[], title: string, timeZone: string|null, locale: string|null, currency: string|null, warnings: string[], rows: () => AsyncGenerator<any>, records: () => AsyncGenerator<any>, grouped: () => AsyncGenerator<any>, fieldList: () => Promise<any[]>, stats: { rows: number } }>}
  */
-export function planStream(def0: any, opts: {
-    format: "csv" | "xlsx";
-    parameters?: object;
-    timeZone?: string;
-    now?: Date;
-    state?: any;
-    loadReport?: (id: string) => Promise<any>;
-    reportId?: string;
-    fetch?: typeof fetch;
-    baseUrl?: string;
-    sql?: (src: any, p: any) => Promise<object[]>;
-    sqlRows?: (src: any, p: any) => AsyncIterable<object[]>;
-    sources?: Record<string, any>;
-    sorter?: (cmp: (a: any, b: any) => number) => any;
-    deadline?: number;
-    timeoutMs?: number;
-    maxRows?: number;
-    maxJsonRowBytes?: number;
-    maxJsonWholeBytes?: number;
-}): Promise<{
-    why: string;
+/**
+ * The batches of a sqlRows source: an async or sync iterable of arrays of rows, each checked (a single row is a common slip).
+ * @param {Function} sqlRows @param {any} src @param {any} p @param {AbortSignal} [signal]
+ */
+export function sqlBatches(sqlRows: Function, src: any, p: any, signal?: AbortSignal): AsyncGenerator<any[], void, unknown>;
+export function planStream(def0: any, opts: any): Promise<{
+    why: any;
 } | {
-    why?: undefined;
-    name: string;
-    columns: number[];
-    title: string;
-    timeZone: string | null;
-    locale: string | null;
-    currency: string | null;
-    warnings: string[];
-    rows: () => AsyncGenerator<any>;
-    records: () => AsyncGenerator<any>;
-    grouped: () => AsyncGenerator<any>;
+    name: any;
+    columns: any;
+    title: any;
+    timeZone: any;
+    locale: any;
+    currency: any;
+    warnings: any[];
+    rows: () => AsyncGenerator<{
+        kind: any;
+        level: any;
+        cells: {
+            col: number;
+            value: any;
+            format: any;
+            bold: boolean;
+            span: number;
+            colIndex: number;
+        }[];
+    }, void, unknown>;
+    records: (grouped?: boolean) => AsyncGenerator<any, void, unknown>;
+    grouped: () => AsyncGenerator<any, void, unknown>;
+    fieldList: () => Promise<any>;
     stats: {
         rows: number;
     };

package/dist/types/src/engine/text/fonts.d.ts

@@ -11,12 +11,32 @@ export function setCustomFonts(list: {
     weight?: number;
     style?: string;
 }[]): void;
+/**
+ * The family a fontFamily value names: a registered family (any case), else the first of a CSS list that is one, else a
+ * generic name's family. Anything else is unknown: Inter, or JetBrains Mono for a monospace name, and `unknown` is the
+ * name the render warns about.
+ * @param {string} name @returns {{ family: string, unknown?: string }}
+ */
+export function familyOf(name: string): {
+    family: string;
+    unknown?: string;
+};
 /**
  * The face for a family, weight and style, matched as CSS does: style first (italic faces when asked
- * and there are some), then the nearest weight (CSS Fonts 4, §5.2). Unknown families use Inter.
- * @param {string} [family] @param {string|number} [weight] @param {string} [style]
+ * and there are some), then the nearest weight (CSS Fonts 4, §5.2). Unknown families use Inter (JetBrains Mono for a
+ * monospace name), and their names go into `unknown`, for the render's warning (N39).
+ * @param {string} [family] @param {string|number} [weight] @param {string} [style] @param {Set<string>} [unknown]
+ */
+export function resolveFontKey(family?: string, weight?: string | number, style?: string, unknown?: Set<string>): string;
+/**
+ * The embedded face that stands in for a standard font where one must be embedded (PDF/A, PDF/UA, form fields) and for
+ * the characters its encoding lacks: JetBrains Mono for Courier, else Inter, in the same weight and style. No
+ * metric-compatible face (Liberation, say) ships, so its widths differ. Any other key is returned as it is.
+ * @param {string} key
  */
-export function resolveFontKey(family?: string, weight?: string | number, style?: string): string;
+export function embeddedFace(key: string): string;
+/** The name Word, Excel and PowerPoint know for a font key's family (the standard fonts by their Windows equivalents). */
+export function officeFamily(key: any): any;
 /** CSS description of a font key, for SVG/HTML output. */
 export function fontCss(key: any): {
     family: string;
@@ -45,10 +65,12 @@ export function fallbackKey(cp: any, key: any): string;
  * The faces a report definition names before layout: every object with fontFamily, fontWeight or fontStyle (styles,
  * named styles, item and rich-text styles, table and group styles), and the bold face a chart's titles use. Loaded up
  * front, so a report that uses bold or italic lays out in one pass. Data (dataSources, inline data) is not read.
- * @param {any} def @returns {string[]} face keys
+ * Unknown family names go into `unknown` (the render warns about them).
+ * @param {any} def @param {Set<string>} [unknown] @returns {string[]} face keys
  */
-export function fontsForDef(def: any): string[];
+export function fontsForDef(def: any, unknown?: Set<string>): string[];
 export function fontsFor(texts: any): any[];
+export { isStandard };
 /** The optional families (scripts/fetch-fonts-cjk.mjs). */
 export const OPTIONAL_KEYS: string[];
 /** family → its faces: the bundled families, then the fonts uploaded to the server (setCustomFonts). @type {Record<string, Face[]>} */
@@ -63,6 +85,7 @@ export const CORE_FONT_KEY: "Inter-Regular";
 export const PRELOAD_KEYS: string[];
 /** The HarfBuzz shaper (WASM). FontStore loads it like a font, from /fonts/harfbuzz.wasm, once text needs shaping. */
 export const SHAPER: "harfbuzz";
+export function standardCss(key: string): string | null;
 export function allFontKeys(): string[];
 /**
  * Loads font files once and keeps the parsed fontkit objects; SHAPER loads the HarfBuzz shaper.
@@ -93,4 +116,6 @@ export type Face = {
     weight: number;
     style: "normal" | "italic";
     file: string;
+    standard?: boolean;
 };
+import { isStandard } from './standard.js';

package/dist/types/src/engine/text/measure.d.ts

@@ -19,6 +19,8 @@ export function saBreaks(text: string, segmenter?: Intl.Segmenter | null): Set<n
  * @param {any[]} items @param {TextMeasurer} m
  */
 export function finishText(items: any[], m: TextMeasurer): void;
+/** Unicode format characters (Cf): bidi marks and embeddings, joiners, soft hyphen. They have no shape of their own. */
+export const FORMAT_CHAR: RegExp;
 /**
  * @typedef {{ font: string, x: number, w: number, text: string, rtl?: boolean, shaped?: boolean, glyphs: number[] }} Run
  *   One font, one direction. x and w in points from the start of the line; glyphs: [id, x, y, cluster] per glyph
@@ -43,6 +45,10 @@ export class TextMeasurer {
     missing: Set<string>;
     /** characters no font could draw @type {Set<string>} */
     noGlyph: Set<string>;
+    /** font names the text asked for that are not available (resolveFontKey): the render warns @type {Set<string>} */
+    unknownFonts: Set<string>;
+    /** standard-font key → the characters its encoding lacks, drawn in embeddedFace(key): the render warns @type {Map<string, Set<string>>} */
+    substituted: Map<string, Set<string>>;
     /**
      * The key to measure with: `key` when loaded; else (not loaded yet, or failed) the bundled face of the same weight
      * and style when that is loaded, else the core regular face. A key not yet loaded is asked for in the next pass.

package/dist/types/src/engine/text/standard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A standard font as a fontkit-like object (unitsPerEm 1000). Loaded on first use: the metrics are about 130 KB.
+ * @param {string} key a PostScript name of STANDARD_FACES
+ */
+export function standardFont(key: string): Promise<{
+    standard: boolean;
+    postscriptName: string;
+    familyName: any;
+    unitsPerEm: number;
+    ascent: any;
+    descent: any;
+    capHeight: any;
+    xHeight: any;
+    italicAngle: number;
+    underlinePosition: any;
+    underlineThickness: any;
+    bbox: {
+        minX: any;
+        minY: any;
+        maxX: any;
+        maxY: any;
+    };
+    /** WinAnsi for the text fonts (Symbol and ZapfDingbats use their own built-in encodings) */
+    winAnsi: boolean;
+    widths: any[];
+    /** @param {number} cp */
+    hasGlyphForCodePoint: (cp: number) => boolean;
+    /** @param {number} cp */
+    glyphForCodePoint: (cp: number) => any;
+    getGlyph: (id: number) => any;
+}>;
+/**
+ * The 14 standard PDF fonts (Helvetica, Times, Courier in four faces each, Symbol, ZapfDingbats): every PDF reader has
+ * them, so a PDF names them and embeds nothing. Their metrics are Adobe's AFM files, as @pdf-lib/standard-fonts (pdf-lib's
+ * own dependency) ships them; this wraps one in the part of fontkit's font API the engine and the PDF exporters read, so
+ * layout measures with the widths the PDF's /Widths array gives. A glyph ID here is the character's code in the font's
+ * encoding (WinAnsi; Symbol and ZapfDingbats have their own), one byte; 0 = not in the encoding.
+ */
+/** [family, PostScript name, weight, style] */
+export const STANDARD_FACES: (string | number)[][];
+export const STANDARD_KEYS: Set<string>;
+export function isStandard(key: string): boolean;

package/dist/types/src/exporters/docx.d.ts

@@ -1,9 +1,12 @@
+/** The string cut into pieces of at most about max chars, each ending at a '>' (a tag boundary), so their join is s. */
+export function slices(s: any, max: any): any[];
 /** Left, right or centre, from where the lines sit in their box. */
 export function alignOf(it: any): "center" | "left" | "right" | "both";
 /**
  * @param {any} model render() output
  * @param {{ title?: string, author?: string, lang?: string, fontStore?: any, fetchImage?: (src: string) => Promise<Uint8Array|null>,
- *   rasterize?: (svg: string, w: number, h: number, scale: number) => Promise<Uint8Array|null>, figures?: boolean }} [opt]
+ *   rasterize?: (svg: string, w: number, h: number, scale: number) => Promise<Uint8Array|null>, figures?: boolean, xmlChunk?: number }} [opt]
+ *   xmlChunk: the document XML is written to the zip in pieces of about this many chars (default 4M; tests lower it)
  *   fontStore: text in pictures as outlines (else the reader's fallback font); fetchImage: pictures by URL;
  *   rasterize: the PNG fallback of a picture (default: a canvas in a browser, sharp in Node); figures: false leaves them out.
  * @returns {Promise<Uint8Array>}
@@ -16,4 +19,19 @@ export function exportDocx(model: any, opt?: {
     fetchImage?: (src: string) => Promise<Uint8Array | null>;
     rasterize?: (svg: string, w: number, h: number, scale: number) => Promise<Uint8Array | null>;
     figures?: boolean;
+    xmlChunk?: number;
 }): Promise<Uint8Array>;
+/**
+ * The .docx of pages as they come (an array, or an async iterable: exportDocxStream's pages, a window at a time), its
+ * zip bytes handed to put as they are made (awaited: back-pressure). Each page's XML goes into word/document.xml's
+ * deflater once the page is converted, so neither the pages nor the document XML are held whole; the parts that name
+ * the pictures follow the document. model: the model, or a paged plan's info (width, height; locale, name).
+ * @param {Iterable<any>|AsyncIterable<any>} pages @param {{ width: number, height: number, locale?: string, name?: string }} model
+ * @param {NonNullable<Parameters<typeof exportDocx>[1]>} opt @param {(bytes: Uint8Array) => any} put
+ */
+export function writeDocx(pages: Iterable<any> | AsyncIterable<any>, model: {
+    width: number;
+    height: number;
+    locale?: string;
+    name?: string;
+}, opt: NonNullable<Parameters<typeof exportDocx>[1]>, put: (bytes: Uint8Array) => any): Promise<void>;

package/dist/types/src/exporters/html.d.ts

@@ -4,12 +4,15 @@
  * drill-through opens the ReportWright viewer at drillBase (without one it is shown disabled).
  * Unless static, a file whose report has tables also gets a Tables view (htmldata.js): the tables as HTML, re-sorted on
  * their interactive-sort columns, groups opened and closed, rows filtered, by one inline script the file's CSP allows.
+ * exportHtml(model, { fonts, ...options }). The 0.7 form exportHtml(model, fontStore, options) still works (deprecated).
  * @param {any} model
- * @param {import('../engine/text/fonts.js').FontStore} fontStore
- * @param {{ title?: string, drillBase?: string, subset?: (font: Uint8Array, cps: Iterable<number>, o?: { layout?: boolean }) => Promise<Uint8Array>,
- *   static?: boolean, locale?: string, currency?: string, lang?: string, strings?: Partial<typeof DATA_STRINGS> }} [opt]
+ * @param {{ fonts?: import('../engine/text/fonts.js').FontStore, fontStore?: import('../engine/text/fonts.js').FontStore, title?: string, drillBase?: string, subset?: (font: Uint8Array, cps: Iterable<number>, o?: { layout?: boolean }) => Promise<Uint8Array>,
+ *   static?: boolean, locale?: string, currency?: string, lang?: string, strings?: Partial<typeof DATA_STRINGS>, timeoutMs?: number } | import('../engine/text/fonts.js').FontStore} [options]
+ * @param {any} [legacyOpt] the options of the 0.7 form
  */
-export function exportHtml(model: any, fontStore: import("../engine/text/fonts.js").FontStore, opt?: {
+export function exportHtml(model: any, options?: {
+    fonts?: import("../engine/text/fonts.js").FontStore;
+    fontStore?: import("../engine/text/fonts.js").FontStore;
     title?: string;
     drillBase?: string;
     subset?: (font: Uint8Array, cps: Iterable<number>, o?: {
@@ -20,5 +23,6 @@ export function exportHtml(model: any, fontStore: import("../engine/text/fonts.j
     currency?: string;
     lang?: string;
     strings?: Partial<typeof DATA_STRINGS>;
-}): any;
+    timeoutMs?: number;
+} | import("../engine/text/fonts.js").FontStore, legacyOpt?: any): Promise<string>;
 import { DATA_STRINGS } from './htmldata.js';