@rastr/pdf-template 0.0.0-stage → 0.1.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,324 @@
+type Locale = 'cs' | 'en';
+type Align = 'start' | 'center' | 'end';
+type Weight = 400 | 600 | 700;
+interface PageSetup {
+    readonly size: 'A4' | 'A3' | 'Letter';
+    readonly orientation: 'portrait' | 'landscape';
+    /** Top, right, bottom, left in mm. */
+    readonly margins: readonly [number, number, number, number];
+    readonly unit: 'mm';
+}
+interface FontRef {
+    readonly family: string;
+    readonly src: string;
+    readonly weight?: 400 | 700;
+}
+interface TextStyle {
+    readonly font?: string;
+    /** pt */
+    readonly size?: number;
+    readonly weight?: Weight;
+    readonly color?: string;
+    readonly background?: string;
+}
+type StyleRef = string | TextStyle;
+interface TextElement {
+    readonly type: 'text';
+    readonly text: string;
+    readonly x: number;
+    readonly y: number;
+    readonly w?: number;
+    readonly align?: Align;
+    readonly style?: StyleRef;
+}
+interface ImageElement {
+    readonly type: 'image';
+    readonly src: string;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h?: number;
+}
+interface LineElement {
+    readonly type: 'line';
+    readonly x1: number;
+    readonly y1: number;
+    readonly x2: number;
+    readonly y2: number;
+    readonly color?: string;
+    /** mm */
+    readonly width?: number;
+}
+interface RectElement {
+    readonly type: 'rect';
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly fill?: string;
+    readonly stroke?: string;
+    readonly strokeWidth?: number;
+}
+type Element = TextElement | ImageElement | LineElement | RectElement;
+interface ColumnOverride {
+    /** mm */
+    readonly width?: number;
+    readonly align?: Align;
+    readonly format?: string;
+    readonly caption?: string;
+}
+interface TableBand {
+    readonly columns: 'fromGrid' | readonly string[];
+    readonly overrides?: Readonly<Record<string, ColumnOverride>>;
+    readonly header?: {
+        readonly background?: string;
+        readonly repeatOnEachPage?: boolean;
+        readonly style?: StyleRef;
+    };
+    readonly zebra?: string;
+    readonly rowStyles?: readonly {
+        readonly when: string;
+        readonly style: StyleRef;
+    }[];
+    /** Validated, not rendered in v1 (grouping is v2). */
+    readonly groupHeader?: unknown;
+    /** Draws ReportInput.summaryRow as the bold last row of the table. */
+    readonly summary?: boolean;
+}
+interface Bands {
+    readonly reportHeader?: readonly Element[];
+    readonly pageHeader?: readonly Element[];
+    readonly table?: TableBand;
+    readonly reportFooter?: readonly Element[];
+    readonly pageFooter?: readonly Element[];
+}
+interface ReportTemplate {
+    readonly version: 1;
+    readonly page: PageSetup;
+    readonly fonts: readonly FontRef[];
+    readonly styles: Readonly<Record<string, TextStyle>>;
+    readonly bands: Bands;
+}
+
+interface TemplateIssue {
+    /** Path in the template, e.g. "bands.pageHeader[1].text". */
+    readonly path: string;
+    readonly message: string;
+}
+/** An invalid template, expression, condition or font; lists every issue found. */
+declare class TemplateError extends Error {
+    readonly issues: readonly TemplateIssue[];
+    constructor(issues: readonly TemplateIssue[]);
+}
+
+/** Validates a template (e.g. parsed JSON from storage); throws TemplateError listing every issue. */
+declare function validateTemplate(json: unknown): ReportTemplate;
+
+interface ExpressionFilter {
+    readonly name: string;
+    readonly args: readonly string[];
+}
+type ExpressionPart = {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'expr';
+    readonly path: readonly string[];
+    readonly filters: readonly ExpressionFilter[];
+};
+/** Splits text into literal parts and {{ path | filter:arg }} expressions; throws TemplateError. */
+declare function parseExpression(text: string): ExpressionPart[];
+declare function evaluateText(parts: readonly ExpressionPart[], scope: unknown, locale: Locale, timeZone: string): string;
+
+/** row.field (==|!=|<|<=|>|>=) literal, joined by && (binds tighter) and ||; no parentheses. */
+declare function compileCondition(source: string): (row: Readonly<Record<string, unknown>>) => boolean;
+
+/**
+ * Formats a value with a spec: currency[:CODE[:decimals]], number[:decimals], percent[:decimals],
+ * date, datetime. Values that do not fit the spec are returned as text; null and undefined are empty.
+ */
+declare function formatValue(value: unknown, spec: string, locale: Locale, timeZone: string): string;
+/** Text of a value without a format: numbers grouped, booleans Ano/Ne (Yes/No), objects empty. */
+declare function defaultText(value: unknown, locale: Locale): string;
+
+/** Horizontal metrics of a TrueType/OpenType font, enough to measure text without shaping. */
+interface FontMetrics {
+    readonly unitsPerEm: number;
+    readonly ascender: number;
+    readonly descender: number;
+    /** Glyph for a code point; 0 (.notdef) when the font has none. */
+    glyphId(codePoint: number): number;
+    advance(glyphId: number): number;
+}
+declare const MM_PER_PT: number;
+/** Reads head, hhea, hmtx and cmap (format 12 preferred, else format 4); kerning and shaping are not used. */
+declare function parseFontMetrics(data: Uint8Array): FontMetrics;
+/** Width of text in mm at a size in pt; code points without a glyph are measured as .notdef and listed. */
+declare function measureText(text: string, metrics: FontMetrics, sizePt: number): {
+    readonly widthMm: number;
+    readonly missing: readonly number[];
+};
+
+interface ReportColumn {
+    readonly field: string;
+    readonly caption: string;
+    /** Width from the grid in mm; null for a flexible column. */
+    readonly widthMm: number | null;
+    readonly align: Align;
+    readonly format?: string;
+}
+interface ReportInput {
+    readonly columns: readonly ReportColumn[];
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    /** Grid texts per row and field, used when the column has no format. */
+    readonly texts?: readonly Readonly<Record<string, string>>[];
+    /** Summary texts per field, drawn as the last table row when the template asks for it (table.summary). */
+    readonly summaryRow?: Readonly<Record<string, string>>;
+    /** company, user, filter, summary, printedAtUtc (ISO) … */
+    readonly context: Readonly<Record<string, unknown>>;
+    readonly locale: Locale;
+    readonly timeZone: string;
+    readonly imageSizes?: Readonly<Record<string, {
+        readonly width: number;
+        readonly height: number;
+    }>>;
+}
+type LayoutItem = {
+    readonly kind: 'text';
+    readonly x: number;
+    readonly y: number;
+    readonly baseline: number;
+    readonly text: string;
+    readonly font: string;
+    readonly weight: 400 | 700;
+    readonly size: number;
+    readonly color: string;
+} | {
+    readonly kind: 'rect';
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly fill: string | null;
+    readonly stroke: string | null;
+    readonly strokeWidth: number;
+} | {
+    readonly kind: 'line';
+    readonly x1: number;
+    readonly y1: number;
+    readonly x2: number;
+    readonly y2: number;
+    readonly color: string;
+    readonly width: number;
+} | {
+    readonly kind: 'image';
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly src: string;
+};
+interface LayoutPage {
+    readonly items: readonly LayoutItem[];
+}
+interface LayoutDocument {
+    readonly page: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly pages: readonly LayoutPage[];
+    readonly fonts: readonly FontRef[];
+    readonly warnings: readonly string[];
+}
+/** Half away from zero at 0.01 after 15 significant digits (C#: same formula). */
+declare function round2(value: number): number;
+/** Greedy word wrap at spaces (U+00A0 does not break); a word longer than the line breaks by characters. */
+declare function wrapText(text: string, widthMm: number, metrics: FontMetrics, sizePt: number): string[];
+/** Lays out a report: absolute boxes per page, ready for jsPDF or PDFsharp to draw. */
+declare function layoutReport(template: ReportTemplate, input: ReportInput, fonts: ReadonlyMap<string, FontMetrics>): LayoutDocument;
+/** The same layout, yielding to the event loop every few hundred rows so large reports do not freeze the page. */
+declare function layoutReportAsync(template: ReportTemplate, input: ReportInput, fonts: ReadonlyMap<string, FontMetrics>): Promise<LayoutDocument>;
+
+/** A stored template without its content (lists). */
+interface TemplateSummary {
+    readonly id: string;
+    readonly gridId: string;
+    readonly name: string;
+    readonly isDefault: boolean;
+    /** Visible to the whole company, otherwise only to its author; the server decides what that means. */
+    readonly shared: boolean;
+    /** ISO 8601 UTC. */
+    readonly updatedAtUtc: string;
+}
+interface StoredTemplate extends TemplateSummary {
+    /** Validate before use: it may come from an older version or be edited by hand. */
+    readonly template: unknown;
+}
+interface TemplateSave {
+    /** Without id a new template is created. */
+    readonly id?: string;
+    readonly gridId: string;
+    readonly name: string;
+    readonly isDefault: boolean;
+    readonly shared: boolean;
+    readonly template: ReportTemplate;
+}
+/** Report templates per grid; implemented over localStorage, REST (contracts/wire/pdf-templates.md) or by the application. */
+interface TemplateStore {
+    list(gridId: string): Promise<readonly TemplateSummary[]>;
+    load(id: string): Promise<StoredTemplate>;
+    save(input: TemplateSave): Promise<TemplateSummary>;
+    remove(id: string): Promise<void>;
+}
+/** A failed store operation; status is the HTTP status (404 unknown id, 400 invalid template with issues). */
+declare class TemplateStoreError extends Error {
+    readonly status: number;
+    readonly issues: readonly TemplateIssue[];
+    constructor(message: string, status: number, issues?: readonly TemplateIssue[]);
+}
+/** Templates in one localStorage key; keeps at most one default per grid. */
+declare function createLocalTemplateStore(options?: {
+    readonly storage?: Storage;
+    readonly key?: string;
+    readonly now?: () => Date;
+    readonly newId?: () => string;
+}): TemplateStore;
+/** Store over the REST contract in contracts/wire/pdf-templates.md. */
+declare function createRestTemplateStore(options: {
+    readonly url: string;
+    readonly fetch?: typeof fetch;
+    readonly headers?: () => HeadersInit;
+}): TemplateStore;
+/** For GridPdfOptions.template: the grid's default template, or null (the built-in look). */
+declare function templateLoader(store: TemplateStore, gridId: string): () => Promise<unknown | null>;
+
+/** A grid column the template can use (visible export columns, in grid order). */
+interface PreviewField {
+    readonly field: string;
+    readonly caption: string;
+    /** Width from the grid in mm; null for a flexible column. */
+    readonly widthMm: number | null;
+    /** Summary types of the column in the grid (sum, avg, min, max, count, custom), offered as summary.<type>.<field>. */
+    readonly summaries?: readonly string[];
+}
+interface PreviewImage {
+    readonly dataUrl: string;
+    readonly width: number;
+    readonly height: number;
+}
+/** Everything a live preview needs: sample rows with the export context, fonts and images. */
+interface PreviewData {
+    readonly input: ReportInput;
+    /** TrueType files by "family|400" / "family|700". */
+    readonly fonts: ReadonlyMap<string, Uint8Array>;
+    readonly metrics: ReadonlyMap<string, FontMetrics>;
+    /** Images by resolved src; missing ones could not be loaded. */
+    readonly images: ReadonlyMap<string, PreviewImage>;
+}
+/** Sample data for the template designer; @rastr/export-pdf builds one from a grid (gridPreviewSource). */
+interface PreviewSource {
+    fields(): readonly PreviewField[];
+    load(template: ReportTemplate, rows: number): Promise<PreviewData>;
+}
+
+export { type Align, type Bands, type ColumnOverride, type Element, type ExpressionFilter, type ExpressionPart, type FontMetrics, type FontRef, type ImageElement, type LayoutDocument, type LayoutItem, type LayoutPage, type LineElement, type Locale, MM_PER_PT, type PageSetup, type PreviewData, type PreviewField, type PreviewImage, type PreviewSource, type RectElement, type ReportColumn, type ReportInput, type ReportTemplate, type StoredTemplate, type StyleRef, type TableBand, TemplateError, type TemplateIssue, type TemplateSave, type TemplateStore, TemplateStoreError, type TemplateSummary, type TextElement, type TextStyle, type Weight, compileCondition, createLocalTemplateStore, createRestTemplateStore, defaultText, evaluateText, formatValue, layoutReport, layoutReportAsync, measureText, parseExpression, parseFontMetrics, round2, templateLoader, validateTemplate, wrapText };