@reportwright/engine 0.0.0-stage → 0.12.0

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

@@ -0,0 +1,212 @@
+/** A blank A4 report: header with title, empty body, footer with page numbers. */
+export function blankReport(name?: string): {
+    $schema: string;
+    name: string;
+    page: {
+        size: string;
+        orientation: string;
+        margins: number[];
+    };
+    parameters: any[];
+    dataSources: any[];
+    dataSets: any[];
+    styles: {
+        base: {
+            fontFamily: string;
+            fontSize: number;
+            color: string;
+        };
+    };
+    sections: {
+        pageHeader: {
+            height: number;
+            items: {
+                id: string;
+                type: string;
+                name: string;
+                x: number;
+                y: number;
+                w: number;
+                h: number;
+                value: string;
+                canGrow: boolean;
+                style: {
+                    fontSize: number;
+                    fontWeight: string;
+                };
+            }[];
+        };
+        body: {
+            height: number;
+            items: any[];
+        };
+        pageFooter: {
+            height: number;
+            items: {
+                id: string;
+                type: string;
+                name: string;
+                x: number;
+                y: number;
+                w: number;
+                h: number;
+                value: string;
+                canGrow: boolean;
+                style: {
+                    fontSize: number;
+                    color: string;
+                    textAlign: string;
+                };
+            }[];
+        };
+    };
+};
+/**
+ * A pageless dashboard: number tiles, two charts and a table on one page that grows to fit.
+ * The inline sample rows are there so the dashboard shows something at once; replace the data source.
+ */
+export function blankDashboard(name?: string): {
+    $schema: string;
+    name: string;
+    page: {
+        size: string;
+        width: number;
+        margins: number[];
+        minHeight: number;
+    };
+    parameters: any[];
+    dataSources: {
+        name: string;
+        type: string;
+        data: {
+            rows: {
+                month: number;
+                monthName: string;
+                region: string;
+                sales: number;
+                orders: number;
+            }[];
+        };
+    }[];
+    dataSets: {
+        name: string;
+        source: string;
+        path: string;
+    }[];
+    styles: {
+        base: {
+            fontFamily: string;
+            fontSize: number;
+            color: string;
+        };
+    };
+    sections: {
+        pageHeader: {
+            height: number;
+            items: any[];
+        };
+        body: {
+            height: number;
+            items: ({
+                type: string;
+                name: string;
+                x: any;
+                y: number;
+                w: number;
+                h: number;
+                value: any;
+                style: {
+                    fontSize: number;
+                    color: string;
+                    fontWeight?: undefined;
+                };
+            } | {
+                type: string;
+                name: any;
+                x: any;
+                y: number;
+                w: number;
+                h: number;
+                value: any;
+                style: {
+                    fontSize: number;
+                    fontWeight: string;
+                    color?: undefined;
+                };
+            } | {
+                type: string;
+                name: string;
+                x: number;
+                y: number;
+                w: number;
+                h: number;
+                chartType: string;
+                dataSet: string;
+                title: string;
+                category: string;
+                series: {
+                    name: string;
+                    value: string;
+                }[];
+                seriesGroup: string;
+                stacked: boolean;
+                legend: string;
+                valueFormat: string;
+                rowGroup?: undefined;
+                columnGroup?: undefined;
+                value?: undefined;
+                corner?: undefined;
+                columnSort?: undefined;
+            } | {
+                type: string;
+                name: string;
+                x: number;
+                y: number;
+                w: number;
+                h: number;
+                chartType: string;
+                dataSet: string;
+                title: string;
+                category: string;
+                series: {
+                    name: string;
+                    value: string;
+                }[];
+                legend: string;
+                valueFormat: string;
+                seriesGroup?: undefined;
+                stacked?: undefined;
+                rowGroup?: undefined;
+                columnGroup?: undefined;
+                value?: undefined;
+                corner?: undefined;
+                columnSort?: undefined;
+            } | {
+                type: string;
+                name: string;
+                x: number;
+                y: number;
+                w: number;
+                h: number;
+                dataSet: string;
+                rowGroup: string;
+                columnGroup: string;
+                value: string;
+                valueFormat: string;
+                corner: string;
+                columnSort: string;
+                chartType?: undefined;
+                title?: undefined;
+                category?: undefined;
+                series?: undefined;
+                seriesGroup?: undefined;
+                stacked?: undefined;
+                legend?: undefined;
+            })[];
+        };
+        pageFooter: {
+            height: number;
+            items: any[];
+        };
+    };
+};

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

@@ -0,0 +1,21 @@
+/** The nearest known name: a typo (2 edits) or the start of a longer one (noRows → noRowsText). */
+export function didYouMean(k: any, known: any): any;
+/**
+ * Structural checks. Errors stop the render; warnings do not. exprErrors: the errors that are an item's expression
+ * that does not parse. They are in `errors` too (the designer shows them), but render() goes on and draws #Error in
+ * that item or cell with a warning, as SSRS does.
+ * @param {any} def
+ */
+export function validate(def: any): {
+    errors: string[];
+    warnings: any[];
+    exprErrors: any[];
+    checkOnly: any[];
+} | {
+    errors: any[];
+    warnings: string[];
+    exprErrors: any[];
+    checkOnly: any[];
+};
+export const SCHEMA_ID: "pagewright/report@1";
+export const SCHEMA_ALIAS: "reportwright/report@1";

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

@@ -0,0 +1,54 @@
+/**
+ * An in-memory sorter (the browser, the CLI): the server passes one that spills runs to disk (server/spill.js).
+ * @param {(a: any, b: any) => number} cmp
+ */
+export function memorySorter(cmp: (a: any, b: any) => number): {
+    push(r: any): void;
+    drain(): AsyncGenerator<any, void, unknown>;
+    close(): Promise<void>;
+};
+/**
+ * @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,
+ *   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 } }>}
+ */
+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;
+} | {
+    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;
+    };
+}>;

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

@@ -0,0 +1,70 @@
+/**
+ * Merge style layers. Later layers win. Values that hold expressions
+ * are evaluated in the given context (conditional formatting).
+ * @param {(object|null|undefined)[]} layers @param {any} ctx
+ */
+export function resolveStyle(layers: (object | null | undefined)[], ctx: any): any;
+/** "1 solid #ccc" | "none" | {width, style, color} → {width, style, color} | null */
+export function parseBorder(b: any): {
+    width: any;
+    style: any;
+    color: any;
+};
+/** Four borders after side overrides. */
+export function borders(st: any): {
+    top: {
+        width: any;
+        style: any;
+        color: any;
+    };
+    right: {
+        width: any;
+        style: any;
+        color: any;
+    };
+    bottom: {
+        width: any;
+        style: any;
+        color: any;
+    };
+    left: {
+        width: any;
+        style: any;
+        color: any;
+    };
+};
+export namespace BASE_STYLE {
+    let fontFamily: string;
+    let fontSize: number;
+    let fontWeight: string;
+    let fontStyle: string;
+    let color: string;
+    let backgroundColor: any;
+    let backgroundImage: any;
+    let backgroundFit: string;
+    let textAlign: string;
+    let verticalAlign: string;
+    let padding: number;
+    let lineHeight: number;
+    let border: any;
+    let borderTop: any;
+    let borderRight: any;
+    let borderBottom: any;
+    let borderLeft: any;
+    let format: any;
+    let wrap: boolean;
+    let textDecoration: string;
+    let textDecorationColor: any;
+    let writingMode: string;
+    let fill: any;
+    let stroke: string;
+    let strokeWidth: number;
+    let strokeDash: string;
+    let radius: number;
+}
+export function padding(st: any): any;
+export namespace DASH {
+    let solid: any;
+    let dashed: number[];
+    let dotted: number[];
+}

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

@@ -0,0 +1,96 @@
+/** The file behind a key, relative to /fonts: what the FontStore loader reads or fetches. */
+export function fontFile(key: any): string;
+/**
+ * Fonts uploaded to this server: [{ id, family, weight, style }], key "u-<id>", file "custom/<id>".
+ * Replaces the previous list. A family named like a bundled one is skipped (the server refuses those).
+ * @param {{ id: string, family: string, weight?: number, style?: string }[]} list
+ */
+export function setCustomFonts(list: {
+    id: string;
+    family: string;
+    weight?: number;
+    style?: string;
+}[]): void;
+/**
+ * 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]
+ */
+export function resolveFontKey(family?: string, weight?: string | number, style?: string): string;
+/** CSS description of a font key, for SVG/HTML output. */
+export function fontCss(key: any): {
+    family: string;
+    weight: number;
+    style: string;
+};
+/** The bundled fallback faces for `key` (one per script), for CSS font-family lists. */
+export function fallbackKeys(key: any): string[];
+/**
+ * CSS unicode-range for a bundled fallback face, else null: its script's blocks plus the marks, joiners and
+ * dotted circle a run in that font can carry. A browser then downloads the face only for text in that script
+ * (without it, a font-family list of fallbacks fetches every face before the one that has the glyph).
+ * @param {string} key
+ */
+export function unicodeRange(key: string): string;
+/** The bundled fallback face for a code point, in the weight and style of `key`; null when there is none. */
+export function fallbackKey(cp: any, key: any): string;
+/**
+ * The fallback faces (regular and bold, one per script) and the shaper that text in these strings will need. render()
+ * loads them before the layout: a face found missing during the layout means laying everything out again.
+ * ponytail: regular and bold only (italic text in a fallback script uses them too, see resolveFontKey).
+ * @param {Iterable<any>} texts
+ * @returns {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
+ */
+export function fontsForDef(def: any): string[];
+export function fontsFor(texts: any): any[];
+/** 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[]>} */
+export const FONT_FAMILIES: Record<string, Face[]>;
+export const BUNDLED_FAMILIES: string[];
+export const DEFAULT_FAMILY: "Inter";
+/** Loaded before every render. Fallback and uploaded fonts load when a report needs them. */
+export const ALL_FONT_KEYS: string[];
+/** The one face a render cannot do without: the fallback for every other face that is missing or failed. */
+export const CORE_FONT_KEY: "Inter-Regular";
+/** The bundled Latin faces, loaded before layout. The optional CJK and emoji faces (~40 MB once installed) stay lazy: loaded only when text needs them. */
+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 allFontKeys(): string[];
+/**
+ * Loads font files once and keeps the parsed fontkit objects; SHAPER loads the HarfBuzz shaper.
+ * The loader returns the bytes of fontFile(key) under /fonts.
+ */
+export class FontStore {
+    /** @param {(key: string) => Promise<ArrayBuffer|Uint8Array>} loader */
+    constructor(loader: (key: string) => Promise<ArrayBuffer | Uint8Array>);
+    loader: (key: string) => Promise<ArrayBuffer | Uint8Array>;
+    /** @type {Map<string, any>} */ fonts: Map<string, any>;
+    /** @type {Map<string, Uint8Array>} */ bytes: Map<string, Uint8Array>;
+    /** @type {Map<string, Promise<void>>} */ pending: Map<string, Promise<void>>;
+    /** keys that did not load: their text falls back to the default font @type {Set<string>} */ failed: Set<string>;
+    /** @type {any} */ shaper: any;
+    /** @type {Map<string, any>} HarfBuzz fonts by key */ hb: Map<string, any>;
+    /** @param {string[]} keys */
+    load(keys?: string[]): Promise<void>;
+    /** @param {string} key */
+    has(key: string): boolean;
+    /** The HarfBuzz font for a loaded key (the shaper must be loaded). @param {string} key */
+    hbFont(key: string): any;
+    /** @param {string} key */
+    get(key: string): any;
+}
+export type Face = {
+    key: string;
+    family: string;
+    weight: number;
+    style: "normal" | "italic";
+    file: string;
+};

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

@@ -0,0 +1,145 @@
+/**
+ * Grapheme clusters: where a too-long word may break. Intl.Segmenter when there is one; else code points with
+ * marks, joiners and variation selectors kept on the character before (and the character after a ZWJ).
+ * @param {string} s @param {boolean} [intl] false: the fallback (tests)
+ */
+export function clusters(s: string, intl?: boolean): string[];
+/**
+ * Where a line may break inside text written without spaces: the word boundaries ICU's dictionaries find
+ * (Node and browsers ship them for Thai, Lao, Khmer and Myanmar), as UTF-16 indices next to an SA character.
+ * Without a segmenter there are none (UAX #14 then treats SA as letters), and a word too long for its line
+ * breaks between grapheme clusters, as any long word does.
+ * @param {string} text @param {Intl.Segmenter|null} [segmenter]
+ * @returns {Set<number>}
+ */
+export function saBreaks(text: string, segmenter?: Intl.Segmenter | null): Set<number>;
+/**
+ * Last step of a layout: text items whose font did not load switch to the font they were measured in, and
+ * lines that need it get their runs. Mutates the items (they are fresh objects from the layout).
+ * @param {any[]} items @param {TextMeasurer} m
+ */
+export function finishText(items: any[], m: TextMeasurer): void;
+/**
+ * @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
+ *   in visual order, x from the start of the run, y up, cluster = UTF-16 index into `text`.
+ */
+export class TextMeasurer {
+    /** @param {import('./fonts.js').FontStore} store */
+    constructor(store: import("./fonts.js").FontStore);
+    store: import("./fonts.js").FontStore;
+    /** @type {Map<string, any>} per loaded face: its metrics and advances (see face()) */
+    faces: Map<string, any>;
+    /** text layouts of boxes in a static (frozen) style: style → width → text → layout (items/paint.js) */
+    boxes: WeakMap<object, any>;
+    boxCount: number;
+    /** a frozen style's font key, size, padding and line height (items/paint.js) */
+    looks: WeakMap<object, any>;
+    /** @type {Map<string, Map<number, boolean>>} */
+    cover: Map<string, Map<number, boolean>>;
+    /** @type {Map<string, any>} complex layouts at size 1 */
+    cache: Map<string, any>;
+    /** fonts (or the shaper) that text needed but the store has not loaded: render() loads them and lays out again @type {Set<string>} */
+    missing: Set<string>;
+    /** characters no font could draw @type {Set<string>} */
+    noGlyph: 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.
+     */
+    usable(key: any): any;
+    /**
+     * A loaded face's numbers, read once: fontkit's getters (unitsPerEm, ascent…) decode tables on every read.
+     * adv: advances per code point (-1 = not on the fast path); words: fast-path units per string (a table repeats them).
+     * @param {string} key a loaded key
+     */
+    face(key: string): any;
+    /** Font units of `text` on the fast path, or -1 when it needs the complex path. */
+    fast(text: any, key: any): any;
+    /**
+     * Advance width in points. @param {string} text @param {string} key @param {number} size
+     * @param {'ltr'|'rtl'} [dir] paragraph direction (default: from the first strong character)
+     */
+    width(text: string, key: string, size: number, dir?: "ltr" | "rtl"): number;
+    /**
+     * Where underline and strike-through go, from the font's own tables (post and OS/2), in points:
+     * y offsets of the stroke centre from the baseline (positive = down, as on the page) and thicknesses.
+     * A font without the tables falls back to proportions of its descent and x-height.
+     * @param {string} key @param {number} size
+     */
+    decoration(key: string, size: number): {
+        underlineY: number;
+        underlineWidth: number;
+        strikeY: number;
+        strikeWidth: number;
+    };
+    /**
+     * Superscript and subscript from the font's OS/2 table, in em: the size of the small text and how far its
+     * baseline moves (rise up for superscript, drop down for subscript). Fonts without the values get the
+     * proportions most fonts use.
+     * @param {string} key
+     */
+    script(key: string): {
+        supScale: any;
+        supRise: any;
+        subScale: any;
+        subDrop: any;
+    };
+    /** @param {string} key @param {number} size */
+    metrics(key: string, size: number): any;
+    /**
+     * The visually ordered runs of one line, or null when the line is simple (draw `text` as it is).
+     * @param {string} text @param {string} key @param {number} size @param {'ltr'|'rtl'} [dir]
+     * @returns {Run[]|null}
+     */
+    runs(text: string, key: string, size: number, dir?: "ltr" | "rtl"): Run[] | null;
+    /** Paragraph direction of text that needs shaping, bidi or CJK breaks, else undefined. */
+    direction(text: any, key: any): "ltr" | "rtl";
+    /**
+     * Greedy line breaking. Simple paragraphs break at spaces (a word longer than the line breaks by
+     * character), exactly as before. Others also break between CJK characters (kinsoku applied), never
+     * inside a grapheme cluster (a conjunct, a letter and its marks), and remember their direction.
+     * @param {string} text @param {string} key @param {number} size @param {number} maxWidth
+     * @returns {{text: string, width: number, dir?: 'ltr'|'rtl'}[]}
+     */
+    wrap(text: string, key: string, size: number, maxWidth: number): {
+        text: string;
+        width: number;
+        dir?: "ltr" | "rtl";
+    }[];
+    /** @param {string} para @param {string} key @param {number} size @param {number} maxWidth @param {'ltr'|'rtl'} dir @param {number} sp @param {any[]} out */
+    wrapComplex(para: string, key: string, size: number, maxWidth: number, dir: "ltr" | "rtl", sp: number, out: any[]): void;
+    /** Cut a line so it fits, then add "…". */
+    ellipsize(text: any, key: any, size: any, maxWidth: any, dir: any): any;
+    /** Does this font have a glyph for the character? */
+    has(key: any, cp: any): boolean;
+    /** The font for one character: the chosen one, else the bundled fallback for its script, else the one before. */
+    pick(cp: any, key: any, prev: any): any;
+    /**
+     * Bidi levels, a font per character, runs (one font, level, script, and space or not), shaping,
+     * then visual order. Cached at size 1.
+     * @param {string} text @param {string} key a loaded key @param {'ltr'|'rtl'|undefined} dir
+     * @returns {{ w: number, rtl: boolean, runs: Run[] }}
+     */
+    layout(text: string, key: string, dir: "ltr" | "rtl" | undefined): {
+        w: number;
+        rtl: boolean;
+        runs: Run[];
+    };
+    /** One run at size 1: HarfBuzz for complex scripts and right-to-left text, else character-map glyphs. @returns {Run} */
+    shapeRun(text: any, key: any, rtl: any, script: any): Run;
+    unshaped: boolean;
+}
+/**
+ * One font, one direction. x and w in points from the start of the line; glyphs: [id, x, y, cluster] per glyph
+ * in visual order, x from the start of the run, y up, cluster = UTF-16 index into `text`.
+ */
+export type Run = {
+    font: string;
+    x: number;
+    w: number;
+    text: string;
+    rtl?: boolean;
+    shaped?: boolean;
+    glyphs: number[];
+};

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

@@ -0,0 +1,48 @@
+/**
+ * @param {string} html
+ * @param {{ baseSize?: number, warn?: (msg: string) => void }} [opt]
+ * @returns {{ blocks: RichBlock[] }}
+ */
+export function parseRich(html: string, opt?: {
+    baseSize?: number;
+    warn?: (msg: string) => void;
+}): {
+    blocks: RichBlock[];
+};
+export namespace RICH_LIMITS {
+    let maxLength: number;
+    let maxDepth: number;
+    let maxRuns: number;
+    let maxBlocks: number;
+    let maxBreaks: number;
+    let maxAttrs: number;
+    let maxDecls: number;
+}
+/** A link target rich text may use: the same allow-list as url actions (src/engine/url.js). */
+export const safeHref: typeof safeUrl;
+export type RichStyle = {
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string;
+    fontStyle?: string;
+    color?: string;
+    background?: string;
+    underline?: boolean;
+    strike?: boolean;
+    script?: "sup" | "sub";
+    href?: string;
+    align?: string;
+};
+export type RichRun = {
+    text: string;
+    st: RichStyle;
+};
+export type RichBlock = {
+    tag: string;
+    align?: string;
+    level: number;
+    marker?: string;
+    spaceAfter?: boolean;
+    runs: RichRun[];
+};
+import { safeUrl } from '../url.js';

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

@@ -0,0 +1,20 @@
+/** @param {Uint8Array} wasm */
+export function createShaper(wasm: Uint8Array): Promise<{
+    /**
+     * A HarfBuzz font for these bytes. It lives as long as the shaper: fonts are few and reused.
+     * @param {Uint8Array} bytes @returns {{ ptr: number, upem: number }}
+     */
+    font(bytes: Uint8Array): {
+        ptr: number;
+        upem: number;
+    };
+    /**
+     * Shape one run (one font, one script, one direction).
+     * @param {{ ptr: number }} font @param {string} text @param {boolean} rtl
+     * @param {boolean} [plain] kerning and ligatures off (a simple-script run in a right-to-left context)
+     * @returns {number[]} [glyph id, x advance, x offset, y offset, cluster (UTF-16 index)] per glyph, in visual order
+     */
+    shape(font: {
+        ptr: number;
+    }, text: string, rtl: boolean, plain?: boolean): number[];
+}>;