@freereportjs/core 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -79,6 +79,11 @@ interface ElementBase {
      * of the band, so cells of a table row stay the same height.
      */
     stretch?: boolean;
+    /**
+     * Move down when an element above it grows (canGrow), by as much as that element grew, so
+     * long text pushes the rest of the band down instead of overlapping it. Default true.
+     */
+    shift?: boolean;
     /** Excel export: column name in "data" mode; ignored elsewhere. */
     name?: string;
 }
@@ -433,6 +438,8 @@ interface TextItem {
     /** Rotation in degrees around the box centre (watermarks). */
     rotate?: number;
     opacity?: number;
+    /** The text does not fit its box and is cut off (a box that cannot grow, or a page-sized band). */
+    overflow?: boolean;
     source?: ItemSource;
 }
 interface LineItem {
@@ -489,6 +496,21 @@ interface ReportPage {
     width: number;
     height: number;
     items: PageItem[];
+    /** Where each element with an id landed (only with the `anchors` layout option). */
+    anchors?: ElementAnchor[];
+}
+/** The box of one element instance on a page, in mm from the page's top-left corner. */
+interface ElementAnchor {
+    id: string;
+    band: BandKind;
+    /** Detail row index (detail band only). */
+    row?: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Its `visible` expression was false: the box it would have used. */
+    hidden?: boolean;
 }
 interface LayoutResult {
     pages: ReportPage[];
@@ -511,6 +533,11 @@ interface LayoutOptions {
     locale?: string;
     /** Stop after this many pages (safety net for runaway reports). Default 10000. */
     maxPages?: number;
+    /**
+     * Record the box of every element with an id on each page (`page.anchors`), including empty
+     * text and hidden elements. `report.anchors()` turns this on for you.
+     */
+    anchors?: boolean;
 }
 interface TextMeasurer {
     /** Width of the text in mm. */
@@ -749,6 +776,13 @@ interface ReportOptions extends LayoutOptions {
      */
     directPrint?: boolean | AgentPrintOptions;
 }
+/** Where an element landed: its box in mm on a page, with that page's size. */
+interface ReportAnchor extends ElementAnchor {
+    /** 1-based index of the page in the laid-out report (not the printed page number). */
+    page: number;
+    pageWidth: number;
+    pageHeight: number;
+}
 interface Report {
     readonly definition: ReportDefinition;
     /** Lay out (cached until data, params or the definition change). */
@@ -767,6 +801,12 @@ interface Report {
     toCsv(): Promise<Blob | null>;
     /** 한/글 document (.hwpx, KS X 6101) laid out like the printed pages. */
     toHwpx(): Promise<Blob | null>;
+    /**
+     * Boxes of the elements with an id, page by page (mm from the page's top-left corner), including
+     * empty text and hidden elements: for signature fields, form overlays and tests. `prefix` keeps
+     * only ids that start with it, e.g. "sp:".
+     */
+    anchors(prefix?: string): ReportAnchor[];
     /** SHA-256 of the printed text (원본 확인); also available as `docHash` when the definition sets `fingerprint`. */
     fingerprint(): string;
     /** Save a file through the browser's download. */
@@ -795,6 +835,21 @@ interface ViewerOptions extends ReportOptions {
     /** Show the parameter panel open at start (default: when the report has parameters without defaults). */
     paramsOpen?: boolean;
     fileName?: string;
+    /** After every successful run (start, 조회/Run, setData, setParams, setDefinition): page and row counts. */
+    onReady?: (e: ViewerReadyEvent) => void;
+    /** When the user submits the parameter panel, before the data is fetched. Return false to stay (e.g. failed validation), or return changed params. */
+    onParamsSubmit?: (params: Record<string, unknown>) => boolean | void | Record<string, unknown> | Promise<boolean | void | Record<string, unknown>>;
+    /** The page in view changed (1-based). */
+    onPageChange?: (page: number, total: number) => void;
+    /** Loading data, laying out, printing or saving failed. The viewer still shows its own message. */
+    onError?: (error: Error, during: 'data' | 'layout' | 'output') => void;
+}
+interface ViewerReadyEvent {
+    pages: number;
+    rows: number;
+    /** Layout time in milliseconds. */
+    ms: number;
+    params: Record<string, unknown>;
 }
 interface Viewer {
     readonly report: Report;
@@ -997,7 +1052,7 @@ declare function checkExpression(src: string): string | null;
  * Fill a text template: "Page {page} / {pages}", "{amount:#,##0} 원". The part after the last
  * top-level ":" is a format when it does not parse as part of the expression ("{a ? b : c}" works).
  */
-declare function interpolate(template: string, scope: Scope): string;
+declare function interpolate(template: string, scope: Scope, locale?: string): string;
 
 /**
  * Value formatting for report fields.
@@ -1130,7 +1185,7 @@ declare function verifyLicense(key: string, host: string, opts?: {
 declare function setLicenseKey(key: string): void;
 
 /** FreeReport version (kept in sync with releases.json by scripts/release.mjs). */
-declare const version = "0.8.0";
+declare const version = "0.10.0";
 
 type Lang = 'ko' | 'en';
 
@@ -1192,4 +1247,4 @@ declare function renderXlsx(def: ReportDefinition, data?: ReportData, opts?: Ser
     mode?: 'form' | 'data';
 }): Promise<Uint8Array>;
 
-export { AgentError, type AgentLogEntry, type AgentPrintOptions, type AgentPrintResult, type AgentPrinter, type AgentStatus, type Align, type Band, type BandKind, type BarcodeElement, type BorderInput, type BorderSide, type BoxItem, type ChartElement, type ChartSeries, type CrosstabElement, type Designer, type DesignerOptions, type ElementType, type Emboss, type Expr, FUNCTIONS, type FieldElement, type FontBytes, type FontEntry, type GroupDefinition, type ImageElement, type ImageItem, type ItemSource, type LayoutOptions, type LayoutResult, type LicenseInfo, type LineElement, type LineItem, type OutputEvent, type OutputKind, PAPER, type PageItem, type PageSetup, type PaperSize, type ParamDefinition, type PathCommand, type PathItem, type PdfFontSource, type PdfOptions, type PdfPermissions, type PdfSecurity, type PrintOptions, type RectElement, type Report, type ReportData, type ReportDefinition, type ReportElement, type ReportOptions, type ReportPage, type ResolvedBorder, type ResolvedFont, type ServerRenderOptions, type Style, type TableColumn, type TableElement, type TextElement, type TextItem, type TextLine, type TextMeasurer, type VAlign, type Viewer, type ViewerOptions, type Watermark, type XCell, type XCellStyle, type XSheet, agent, applyEmboss, blankReport, canonicalText, canvasMeasurer, checkExpression, compile, contentWidth, createDesigner, createReport, createViewer, dataToCsv, dataToXlsx, defaultMeasurer, embossImage, encodeCode128, encodeDataMatrix, encodeEan13, encodePdf417, encodeQr, ensureFonts, estimateMeasurer, evaluate, fingerprintPages, formatDate, formatNumber, formatValue, getFont, interpolate, koreanAmount, koreanNumber, layoutReport, loadFontBytes, loadFonts, pageGeometry, pageToSvg, pagesToHwpx, pagesToXlsx, paramValues, printPages, registerFont, renderPage, renderPdf, renderXlsx, resetMeasurer, rowsOf, saveFile, setLicenseKey, sha256Hex, ttfMeasurer, verifyLicense, version, wrapText, writePdf, writeXlsx };
+export { AgentError, type AgentLogEntry, type AgentPrintOptions, type AgentPrintResult, type AgentPrinter, type AgentStatus, type Align, type Band, type BandKind, type BarcodeElement, type BorderInput, type BorderSide, type BoxItem, type ChartElement, type ChartSeries, type CrosstabElement, type Designer, type DesignerOptions, type ElementAnchor, type ElementType, type Emboss, type Expr, FUNCTIONS, type FieldElement, type FontBytes, type FontEntry, type GroupDefinition, type ImageElement, type ImageItem, type ItemSource, type LayoutOptions, type LayoutResult, type LicenseInfo, type LineElement, type LineItem, type OutputEvent, type OutputKind, PAPER, type PageItem, type PageSetup, type PaperSize, type ParamDefinition, type PathCommand, type PathItem, type PdfFontSource, type PdfOptions, type PdfPermissions, type PdfSecurity, type PrintOptions, type RectElement, type Report, type ReportAnchor, type ReportData, type ReportDefinition, type ReportElement, type ReportOptions, type ReportPage, type ResolvedBorder, type ResolvedFont, type ServerRenderOptions, type Style, type TableColumn, type TableElement, type TextElement, type TextItem, type TextLine, type TextMeasurer, type VAlign, type Viewer, type ViewerOptions, type ViewerReadyEvent, type Watermark, type XCell, type XCellStyle, type XSheet, agent, applyEmboss, blankReport, canonicalText, canvasMeasurer, checkExpression, compile, contentWidth, createDesigner, createReport, createViewer, dataToCsv, dataToXlsx, defaultMeasurer, embossImage, encodeCode128, encodeDataMatrix, encodeEan13, encodePdf417, encodeQr, ensureFonts, estimateMeasurer, evaluate, fingerprintPages, formatDate, formatNumber, formatValue, getFont, interpolate, koreanAmount, koreanNumber, layoutReport, loadFontBytes, loadFonts, pageGeometry, pageToSvg, pagesToHwpx, pagesToXlsx, paramValues, printPages, registerFont, renderPage, renderPdf, renderXlsx, resetMeasurer, rowsOf, saveFile, setLicenseKey, sha256Hex, ttfMeasurer, verifyLicense, version, wrapText, writePdf, writeXlsx };