@reportwright/engine 0.0.0-stage → 0.12.0

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

@@ -0,0 +1,239 @@
+/**
+ * Render a report definition to a page model (pages, regions), the input of every exporter. Throws ReportError for a
+ * definition that cannot render at all; everything else is a warning in the model.
+ * @param {any} def0 the report definition (pagewright/report@1), or a saved report's JSON
+ * @param {RenderOptions} [opts]
+ * @returns {Promise<any>} the page model
+ */
+export function render(def0: any, opts?: RenderOptions): Promise<any>;
+export function baseContext(def: any, { params, now, timeZone, fnCount, clock }: {
+    params: any;
+    now: any;
+    timeZone: any;
+    fnCount: any;
+    clock: any;
+}): {
+    params: any;
+    globals: {
+        ExecutionTime: any;
+        ReportName: any;
+        PageNumber: number;
+        TotalPages: number;
+    };
+    dataSets: {};
+    fields: any;
+    locale: any;
+    currency: any;
+    nonFinite: any;
+    grouping: any;
+    nullPropagation: boolean;
+    doubles: boolean;
+    bandRows: any;
+    timeZone: any;
+    caseSensitive: boolean;
+    nullOrder: any;
+    collation: any;
+    naturalSort: boolean;
+    functions: {
+        byName: Map<string, any>;
+        count: {
+            n: number;
+        };
+    };
+    clock: any;
+    aggCache: WeakMap<object, any>;
+    fmtMemo: Map<any, any>;
+};
+/**
+ * Options for parameters that list values from a data set (cascading parameters:
+ * the data set may filter on other parameters).
+ * @returns {Promise<Record<string, {value: any, label: string}[]>>}
+ */
+export function parameterOptions(def: any, given?: {}, opts?: {}): Promise<Record<string, {
+    value: any;
+    label: string;
+}[]>>;
+/**
+ * Defaults, types and required checks for report parameters.
+ * @param {any} def @param {Record<string, any>} given the values the caller passed, by name
+ * @param {{ lenient?: boolean, now?: Date, timeZone?: string, locale?: string }} [o] lenient: a missing required value is not an error (the option lists); now, timeZone, locale: for defaults such as =Today()
+ * @returns {Record<string, any>}
+ */
+export function resolveParameters(def: any, given: Record<string, any>, o?: {
+    lenient?: boolean;
+    now?: Date;
+    timeZone?: string;
+    locale?: string;
+}): Record<string, any>;
+export class ReportError extends Error {
+    /** @param {string} msg @param {object} [extra] */
+    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.
+ */
+export type RenderOptions = {
+    /**
+     * filled in: how many times the report was laid out (tests, the bench)
+     */
+    stats?: {
+        layoutPasses?: number;
+    };
+    /**
+     * values of the report's parameters, by name (invariant form: 1234.5, 2026-03-05)
+     */
+    parameters?: Record<string, any>;
+    /**
+     * the fonts; share one across renders (a new one loads them again)
+     */
+    fontStore?: import("./text/fonts.js").FontStore;
+    /**
+     * loads a font the store does not have
+     */
+    loadFont?: (key: string) => Promise<ArrayBuffer | Uint8Array>;
+    /**
+     * fetch for data sources (default: the SSRF-guarded fetch, see unsafeFetch)
+     */
+    fetch?: typeof fetch;
+    /**
+     * the origin relative data URLs resolve against
+     */
+    baseUrl?: string;
+    /**
+     * data sources already loaded, by name (skips loading them)
+     */
+    sources?: Record<string, any>;
+    /**
+     * the render's clock: ExecutionTime and =Today() defaults (default: the current time)
+     */
+    now?: Date;
+    /**
+     * the saved report being rendered; the server runs its SQL sources for a browser render
+     */
+    reportId?: string;
+    /**
+     * runs SQL sources directly (server renders)
+     */
+    sql?: (src: any, params: Record<string, any>) => Promise<object[]>;
+    /**
+     * loads a saved report by id: subreports, masters, part libraries, stylesheets, themes
+     */
+    loadReport?: (id: string) => Promise<any>;
+    /**
+     * stop with a ReportError (status 504) when the render runs longer; subreports share it
+     */
+    timeoutMs?: number;
+    /**
+     * the same limit as an absolute time (ms since the epoch)
+     */
+    deadline?: number;
+    /**
+     * receives the loaded sources (the worker's first pages hand them to the full render)
+     */
+    onSources?: (sources: Record<string, any>) => void;
+    /**
+     * keep the table data (model.regions) and cell tags that Excel, CSV, Word, interactive HTML and accessible PDF rebuild tables from
+     */
+    exportData?: boolean;
+    /**
+     * the table data only (model.regions; pages is empty): no layout, for the data CSV
+     */
+    dataOnly?: boolean;
+    /**
+     * turn off the SSRF guard (data/guard.js): public http(s) hosts only by default
+     */
+    unsafeFetch?: boolean;
+    /**
+     * private hosts the guard may reach
+     */
+    allowHosts?: string[];
+    /**
+     * time limit per data fetch (default 30 s)
+     */
+    fetchTimeoutMs?: number;
+    /**
+     * size limit per data fetch, decoded (default 64 MB)
+     */
+    maxFetchBytes?: number;
+    /**
+     * lay out only enough rows for this many pages: a fast first look, not the final render
+     */
+    firstPages?: number;
+    /**
+     * which layers draw (default export)
+     */
+    target?: "screen" | "print" | "export";
+    /**
+     * the viewer's interactive state: sorts, toggles, selections
+     */
+    state?: Record<string, any>;
+    /**
+     * the zone dates show in, when the report sets none
+     */
+    timeZone?: string;
+    /**
+     * internal (subreports): the width the child body is laid out to
+     */
+    bodyWidth?: any;
+    /**
+     * internal (subreports): nesting level, at most 3
+     */
+    depth?: number;
+    /**
+     * internal (subreports): subreports rendered so far, all levels together
+     */
+    budget?: {
+        used: number;
+    };
+    /**
+     * internal (subreports): the reports this render sits inside, so one that reaches itself is skipped
+     */
+    chain?: string[];
+    /**
+     * internal (subreports): the body alone, no pages
+     */
+    bodyOnly?: boolean;
+    /**
+     * internal: reports loaded for this render and its subreports
+     */
+    reportCache?: Map<string, any>;
+    /**
+     * internal: items drawn through report parts so far
+     */
+    reuseBudget?: {
+        items: number;
+    };
+    /**
+     * internal: report function calls so far
+     */
+    fnCount?: {
+        n: number;
+    };
+    /**
+     * internal: the images drawn so far, shared with subreports
+     */
+    imageBudget?: any;
+    /**
+     * internal (paged.js): these pages are a window of a longer report: numbered from offset + 1 of total ('…' when not known
+     * yet); final: the window holds the report's last page; first: the report's first row; rowOffset: the rows before this
+     * window; cont: per group level, the group the window's first row continues (its first row), or null
+     */
+    pageWindow?: {
+        offset: number;
+        total?: number | null;
+        final: boolean;
+        first?: any;
+        rowOffset?: number;
+        cont?: ({
+            first: any;
+        } | null)[];
+    };
+};
+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 };

package/dist/types/src/engine/items/barcode.d.ts

@@ -0,0 +1,121 @@
+export function loadBarcodes(): Promise<void>;
+/**
+ * bwip-js options from an item's flat keys, for its symbology only.
+ * @param {Record<string, any>} item
+ */
+export function bwipOptions(item: Record<string, any>): Record<string, any>;
+/**
+ * Why a symbology cannot draw, with the id that was probably meant ("qr" → "qrcode"); null when it is known.
+ * @param {any} sym
+ */
+export function symbologyError(sym: any): string;
+/** Scale and move every coordinate of an SVG path (absolute and relative commands). */
+export function transformPath(d: any, sx: any, sy: any, tx: any, ty: any): string;
+/**
+ * @param {{ type?: string, text: any, x: number, y: number, w: number, h: number, color?: string, showText?: boolean,
+ *   textHeight?: number, captionAbove?: boolean, options?: Record<string, any> }} a
+ * @returns {{ items: any[], error?: string, twoD?: boolean }} paths in item-local coordinates
+ */
+export function paintBarcode({ type, text, x, y, w, h, color, showText, textHeight, captionAbove, options }: {
+    type?: string;
+    text: any;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color?: string;
+    showText?: boolean;
+    textHeight?: number;
+    captionAbove?: boolean;
+    options?: Record<string, any>;
+}): {
+    items: any[];
+    error?: string;
+    twoD?: boolean;
+};
+export const SYMBOLOGIES: {
+    id: any;
+    name: any;
+    sample: any;
+    max: number;
+    twoD: boolean;
+}[];
+/** Kept for older callers: the ids in the designer's list. */
+export const BARCODE_TYPES: any[];
+/**
+ * Per-symbology options, as flat item keys. Each is checked against a list or a range: nothing a report
+ * author types reaches bwip-js unchecked.
+ */
+export const BARCODE_OPTIONS: ({
+    key: string;
+    label: string;
+    for: string[];
+    opt: string;
+    enum: string[];
+    int?: undefined;
+    str?: undefined;
+    size?: undefined;
+    bool?: undefined;
+    num?: undefined;
+} | {
+    key: string;
+    label: string;
+    for: string[];
+    opt: string;
+    int: number[];
+    str: boolean;
+    enum?: undefined;
+    size?: undefined;
+    bool?: undefined;
+    num?: undefined;
+} | {
+    key: string;
+    label: string;
+    for: string[];
+    opt: string;
+    int: number[];
+    enum?: undefined;
+    str?: undefined;
+    size?: undefined;
+    bool?: undefined;
+    num?: undefined;
+} | {
+    key: string;
+    label: string;
+    for: string[];
+    opt: string;
+    size: boolean;
+    enum?: undefined;
+    int?: undefined;
+    str?: undefined;
+    bool?: undefined;
+    num?: undefined;
+} | {
+    key: string;
+    label: string;
+    for: string[];
+    opt: string;
+    bool: boolean;
+    enum?: undefined;
+    int?: undefined;
+    str?: undefined;
+    size?: undefined;
+    num?: undefined;
+} | {
+    key: string;
+    label: string;
+    for: string[];
+    opt: string;
+    num: number[];
+    enum?: undefined;
+    int?: undefined;
+    str?: undefined;
+    size?: undefined;
+    bool?: undefined;
+})[];
+/**
+ * Every symbology bwip-js draws (its symbolList bcids, kept here so a check needs no 1 MB import; a test compares).
+ * A report may use any of them; the designer offers SYMBOLOGIES.
+ */
+export const BWIP_IDS: Set<string>;
+export function isTwoD(id: string): boolean;

package/dist/types/src/engine/items/cells.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A table row's cells by column (null where nothing starts). Two forms, both accepted:
+ * - one entry per column, null under a colSpan (ReportWright's own form);
+ * - RDL / HTML style: the row has fewer cells than columns and spans, the spanned cells are omitted.
+ * covered: [k, j] pairs, cell k (0-based, own form) sits under the colSpan of cell j; it is not drawn.
+ * @param {any} cells @param {number} ncols @returns {{ at: any[], covered: [number, number][] }}
+ */
+export function rowCells(cells: any, ncols: number): {
+    at: any[];
+    covered: [number, number][];
+};

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

@@ -0,0 +1,75 @@
+/** A palette by name, or a custom list of #hex colours. */
+export function paletteOf(p: any): any;
+/** WCAG contrast ratio of two #hex colours (1 when either is not a colour). */
+export function contrast(a: any, b: any): number;
+/** White or near-black, whichever reads better on the fill. */
+export function inkOn(fill: any): "#111827" | "#ffffff";
+/** "Nice" axis bounds and step (Heckbert). */
+export function niceScale(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. */
+export function logTicks(min: any, max: any): number[];
+/**
+ * An SVG path through points (in drawing order along the category axis).
+ * `along: 'y'` when the categories run down the page (a bar chart): the curve is then monotone in y.
+ * @param {{x:number,y:number}[]} pts
+ * @param {'straight'|'smooth'|'step'} mode
+ * @param {{along?: 'x'|'y', move?: boolean}} [o] move: false continues an existing path (L to the first point)
+ */
+export function curvePath(pts: {
+    x: number;
+    y: number;
+}[], mode?: "straight" | "smooth" | "step", { along, move }?: {
+    along?: "x" | "y";
+    move?: boolean;
+}): string;
+/**
+ * Least-squares trend through [x, y] pairs.
+ * @param {[number, number][]} pts
+ * @param {'linear'|'exp'|'poly'} kind
+ * @returns {{at: (x:number) => number, order: number} | null}
+ */
+export function fitTrend(pts: [number, number][], kind?: "linear" | "exp" | "poly", order?: number): {
+    at: (x: number) => number;
+    order: number;
+} | null;
+/** Trailing moving average: null until `period` values are in; a missing value starts the count again. */
+export function movingAverage(values: any, period: any): any[];
+export namespace CAPS {
+    let categories: number;
+    let series: number;
+    let points: number;
+    let overlays: number;
+    let period: number;
+}
+export namespace PALETTES {
+    let _default: string[];
+    export { _default as default };
+    export let office: string[];
+    export let colorblind: string[];
+    export let vivid: string[];
+    export let pastel: string[];
+    export let ocean: string[];
+    export let sunset: string[];
+    export let forest: string[];
+    export let berry: string[];
+    export let earth: string[];
+    export let grayscale: string[];
+    export let highContrast: string[];
+}
+export const DARK_INK: "#111827";
+/** Accepts label boxes that stay inside the plot and overlap no box placed before. Grid buckets keep it near linear. */
+export class LabelPlacer {
+    constructor(bounds: any, cell?: number);
+    b: any;
+    cell: number;
+    grid: Map<any, any>;
+    fits(r: any): boolean;
+    place(r: any): boolean;
+    keys(r: any): Generator<string, void, unknown>;
+}

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

@@ -0,0 +1,52 @@
+/** Legend entries for these types (the series legend does not fit them). */
+export function moreLegend(type: any, item: any, data: any, pal: any): {
+    name: any;
+    color: any;
+}[];
+export function paintMore(type: any, g: any): any;
+/**
+ * Squarified treemap (Bruls, Huizing, van Wijk): values sorted largest first, laid out in rows along the shorter side,
+ * a row closed when adding the next value would make its worst aspect ratio worse. Linear after the sort.
+ * @returns {{x:number,y:number,w:number,h:number,i:number}[]}
+ */
+export function squarify(items: any, x: any, y: any, w: any, h: any): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    i: number;
+}[];
+/** Bins over [lo, hi]: a count (default: Sturges) or a width. At most MORE_CAPS.bins; linear in the values. */
+export function binValues(vals: any, { binCount, binWidth }?: {}): {
+    lo: number;
+    hi: number;
+    width: number;
+    counts: any[];
+    capped: boolean;
+};
+/** Quartiles (linear interpolation, as Excel QUARTILE.INC), whiskers at the furthest values within 1.5 IQR, outliers beyond. */
+export function boxStats(sorted: any): {
+    min: any;
+    max: any;
+    q1: any;
+    med: any;
+    q3: any;
+    lo: any;
+    hi: any;
+    outliers: any[];
+    mean: number;
+    n: any;
+};
+/** Date ticks: the first step of day, week, month, quarter, year that gives at most `max` ticks. */
+export function dateTicks(lo: any, hi: any, max?: number): {
+    ticks: number[];
+    unit: string | number;
+} | {
+    ticks: any[];
+    unit: string;
+};
+export const MORE_TYPES: Set<string>;
+export namespace MORE_CAPS {
+    let bins: number;
+    let outliers: number;
+}

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

@@ -0,0 +1,28 @@
+export function arc(cx: any, cy: any, r: any, ri: any, a0: any, a1: any): string;
+export function paintRound(type: any, g: any): void;
+/**
+ * Outside pie labels: one column each side; on a side the labels keep their slice order and are pushed apart (down, then
+ * back up from the bottom) so none overlap. When a side has more labels than fit, the smallest slices lose theirs.
+ * Each label is joined to its slice: from the rim, out to an elbow, then across to the label.
+ */
+export function placeOutside(sides: any, { cx, cy, r, lw, lh, lo, hi, out, text, texts, fs, ink }: {
+    cx: any;
+    cy: any;
+    r: any;
+    lw: any;
+    lh: any;
+    lo: any;
+    hi: any;
+    out: any;
+    text: any;
+    texts: any;
+    fs: any;
+    ink: any;
+}): void;
+export const ROUND_TYPES: Set<string>;
+export namespace GAUGE_SHAPES {
+    let half: number[];
+    let threeQuarter: number[];
+    let full: number[];
+}
+export const GAUGE_INDICATORS: string[];

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

@@ -0,0 +1,42 @@
+/** Categories × series values from the data. */
+export function chartData(item: any, ctx: any, lc: any, pal?: any): {
+    categories: any[];
+    buckets: any[];
+    series: any[];
+    rows: any;
+};
+/**
+ * Paint the chart into item-local coordinates (x from item.x, y from 0).
+ * meta.alt receives the chart's generated alt text (its type, title, series and categories).
+ * @param {{ alt?: string }} [meta]
+ * @returns {any[]} page-model items
+ */
+export function paintChart(item: any, ctx: any, lc: any, base: any, meta?: {
+    alt?: string;
+}): any[];
+/** Overlays the legend lists (each unless legend: false), with the key each draws: a line (dashed for trends) or a band. */
+export function legendOverlays(item: any, type: any, data: any): ({
+    name: string;
+    color: any;
+    mark: string;
+    dash: boolean;
+} | {
+    name: string;
+    color: any;
+    mark: string;
+    dash?: undefined;
+})[];
+/**
+ * The robust window of a set of values: its 1st and 99th percentiles (nearest rank). extreme: the full spread is more
+ * than five times that window, so a few outliers would flatten the rest of the data.
+ * @param {number[]} vals
+ */
+export function robustWindow(vals: number[]): {
+    p1: number;
+    p99: number;
+    extreme: boolean;
+};
+export { niceScale };
+export const PALETTE: string[];
+export const CHART_TYPES: string[];
+import { niceScale } from './chart-kit.js';

package/dist/types/src/engine/items/hpage.d.ts

@@ -0,0 +1,33 @@
+/** The left edge of a page-model item. */
+export function itemLeft(it: any): any;
+/**
+ * @param {{ units: any[], height: number, headerCount: number, headerHeight: number, repeatHeader: boolean,
+ *   colX: number[], widths: number[], x: number, repeat: number, room: number, order: 'down' | 'across', pageH: number,
+ *   name: string, nextId: () => number, warn: (m: string, clip?: boolean) => void, shiftLocal: (items: any[], dy: number) => any[],
+ *   block?: number }} o  block: columns that move together (a pivot's value columns per measure), default 1
+ * @returns {{ height: number, units: any[], tables: any[], width: number } | null}  null when the columns fit
+ */
+export function sliceColumns(o: {
+    units: any[];
+    height: number;
+    headerCount: number;
+    headerHeight: number;
+    repeatHeader: boolean;
+    colX: number[];
+    widths: number[];
+    x: number;
+    repeat: number;
+    room: number;
+    order: "down" | "across";
+    pageH: number;
+    name: string;
+    nextId: () => number;
+    warn: (m: string, clip?: boolean) => void;
+    shiftLocal: (items: any[], dy: number) => any[];
+    block?: number;
+}): {
+    height: number;
+    units: any[];
+    tables: any[];
+    width: number;
+} | null;