@agile-team/mach-report 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -1,344 +1,13 @@
-import { P as PlanPage, a as PlanComponent, C as ComponentStyle, T as TextMeasurer, R as RenderPlan, G as GridCell, b as PlanGrid } from './textwrap-DWzM7pt1.js';
-export { c as ComponentKind, d as GridPlanResponse, e as RENDER_PLAN_SCHEMA_VERSION, f as RichParagraph, g as RichSegment, h as TextMeasureOptions, i as charWidthEm, j as createCanvasMeasurer, k as createHeuristicMeasurer, l as heuristicMeasurer, m as isImageBackedComponent, n as isRichText, o as measureTextMm, t as toRenderPlan, w as wrapText } from './textwrap-DWzM7pt1.js';
-
-/**
- * 全引擎共享默认值（唯一真相源）。
- *
- * 修改这里的任何常量前请注意消费方：
- * - LINE_HEIGHT：分页行高估算 / Canvas / PDF 三处换算必须一致
- * - DEFAULT_FONT_PT / DEFAULT_BORDER_PT：三后端默认字号与线宽
- * - SCHEMA_VERSION_*：RenderPlan 版本标识（adapter 产出侧使用）
- *
- * 历史：这些值曾散落在 paginate/canvas/pdf/dom 四个文件中各写一份，
- * 是三后端漂移的温床，收敛于此。
- */
-/** 默认行高倍数（基线距 = 字号 × 该系数，与 jh4j 打印口径一致） */
-declare const LINE_HEIGHT = 1.35;
-/** 默认字号（pt），对齐 jh4j 模板缺省值 */
-declare const DEFAULT_FONT_PT = 10.5;
-/** 默认边框线宽（pt） */
-declare const DEFAULT_BORDER_PT = 0.75;
-/** 默认描边色（#333 与 jh4j 网格线一致） */
-declare const DEFAULT_STROKE_COLOR = "#333333";
-/** 默认文本色 */
-declare const DEFAULT_TEXT_COLOR = "#000000";
-/** RenderPlan 正式 schema 版本（core 分页引擎产出） */
-declare const SCHEMA_VERSION_MACH = "1.0.0-mach";
-/** 本地渲染适配器产出版本标识（vue/createLocalFetcher） */
-declare const SCHEMA_VERSION_LOCAL = "mach-local";
-/** jh4j gridPlan 兼容数据标识（vue/createJh4jGridPlanFetcher） */
-declare const SCHEMA_VERSION_JH4J = "jh4j-compatible";
-
-declare const MM_PER_INCH = 25.4;
-declare const CSS_DPI = 96;
-declare function mmToPxFactor(dpi?: number): number;
-declare function mmToPx(value: number, dpi?: number): number;
-declare function pxToMm(value: number, dpi?: number): number;
-declare function ptToPx(pt: number, dpi?: number): number;
-declare function round(value: number, digits: number): number;
-declare const PAPER_SIZES: Record<string, {
-    widthMm: number;
-    heightMm: number;
-}>;
-
-interface ValidationError {
-    path: string;
-    message: string;
-}
-interface ValidationResult {
-    ok: boolean;
-    errors: ValidationError[];
-    warnings: ValidationError[];
-}
-declare function validateComponent(comp: unknown, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
-declare function validatePage(page: unknown, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
-declare function validateRenderPlan(input: unknown): ValidationResult;
-declare function assertRenderPlan(input: unknown): PlanPage[];
-
-interface ListColumn {
-    header: string;
-    field: string;
-    widthMm: number;
-    style?: ComponentStyle;
-}
-interface ListComponent {
-    kind: "list";
-    id?: string;
-    leftMm: number;
-    topMm: number;
-    widthMm: number;
-    dataset: string;
-    columns: ListColumn[];
-    fontSizePt?: number;
-    headerBold?: boolean;
-    rowHeightMm?: number;
-    paddingMm?: number;
-    headerEveryPage?: boolean;
-    headerBackgroundColor?: string;
-    border?: boolean;
-}
-type TemplateComponent = PlanComponent | ListComponent;
-interface TemplatePage {
-    widthMm: number;
-    heightMm: number;
-    marginTopMm?: number;
-    marginBottomMm?: number;
-    marginLeftMm?: number;
-    marginRightMm?: number;
-    components: TemplateComponent[];
-}
-interface ReportTemplate {
-    schemaVersion?: string;
-    pages: TemplatePage[];
-}
-type DatasetRows = Record<string, Record<string, unknown>[]>;
-interface PaginateOptions {
-    /** 每行额外占高（mm），压测专用钩子 */
-    mmPerRow?: number;
-    /** 文本测量器（默认启发式；浏览器端可注入 canvas 测量校准） */
-    measurer?: TextMeasurer;
-}
-interface PaginateResult {
-    plan: RenderPlan;
-    warnings: string[];
-}
-declare function paginateTemplate(template: ReportTemplate, datasets: DatasetRows, optionsOrMmPerRow?: number | PaginateOptions): PaginateResult;
-
-interface GridCellBox {
-    ri: number;
-    ci: number;
-    cell: GridCell;
-    /** 相对组件左上角（mm，顶点原点） */
-    xMm: number;
-    yMm: number;
-    widthMm: number;
-    heightMm: number;
-}
-/** 网格线段：kind="h" 为水平线（pos=y，from/to=x 区间）；"v" 为垂直线（pos=x，from/to=y 区间） */
-interface GridEdge {
-    kind: "h" | "v";
-    pos: number;
-    from: number;
-    to: number;
-}
-interface GridLayout {
-    columns: {
-        pos: number;
-        size: number;
-    }[];
-    rows: {
-        pos: number;
-        size: number;
-    }[];
-    cells: GridCellBox[];
-    /** 内部网格线段（不含外框；已跳过被 colSpan/rowSpan 跨越的边界，相邻段已合并） */
-    edges: GridEdge[];
-}
-/**
- * 网格几何统一解析（DOM/Canvas/PDF 三后端共用，单位真相源）：
- * - 列宽：优先 colWidthsMm（等比缩放至组件宽），否则按列数均分
- * - 行高：优先 rowHeightsMm（等比缩放至组件高），否则按行数均分
- * - colSpan/rowSpan：占位矩阵展开，跨度取起止行列差；越界收敛到网格内
- * - 行内 null/undefined 单元格视为占 1 列的空单元格（与 DOM 表格行为一致）
- * - edges：内部网格线段，跳过被 span 跨越的边界（合并单元格中间无线）
- * 产出为组件左上角顶点原点的 mm 坐标，各后端自行换算 px/pt。
- */
-declare function resolveGridLayout(grid: PlanGrid, compWidthMm: number, compHeightMm: number): GridLayout;
-
-/**
- * 组件样式解析（三后端共享的唯一样式语义真相源）。
- *
- * DOM/Canvas/PDF 各自把 ComponentStyle 翻译成绘制语义时必须经过这里，
- * 禁止后端内联写 fontSize/颜色/线宽换算——历史上三处各写一份导致
- * Canvas 字号 2.13x、网格线口径不一致等漂移 bug。
- */
-
-/** 解析后的字号（px 值已按 dpi 换算；pt 值供 PDF 使用） */
-interface ResolvedFontSize {
-    fontSizePt: number;
-    fontSizePx: number;
-}
-/** 字号解析：fontSizePx 直通；否则 pt→px（与 units.ptToPx 同源） */
-declare function resolveFontSize(style: Pick<ComponentStyle, "fontSizePx" | "fontSize"> | undefined, dpi?: number, defaultPt?: number): ResolvedFontSize;
-/** 描边解析：颜色 + 线宽（pt） */
-declare function resolveStroke(style: Pick<ComponentStyle, "borderColor" | "lineColor" | "lineWidthPt"> | undefined, fallbackColor?: string): {
-    color: string;
-    widthPt: number;
-};
-/** 文本颜色解析 */
-declare function resolveTextColor(style: Pick<ComponentStyle, "color"> | undefined, fallback?: string): string;
-/** 行高解析（倍数，基线距 = 字号 × lineHeight） */
-declare function resolveLineHeight(style: Pick<ComponentStyle, "lineHeight"> | undefined): number;
-/** 盒子边框语义：四边开关 + 内部网格线（四边全关则内线不画） */
-interface BoxBorders {
-    top: boolean;
-    right: boolean;
-    bottom: boolean;
-    left: boolean;
-    /** 网格内线（仅当任意外边开启） */
-    inner: boolean;
-}
-/**
- * 边框开关解析：
- * - 未声明（undefined）→ 四边全开（与既有 rect 总有边框的行为兼容）
- * - 显式 false → 对应边关闭
- * - 四边全关（如 list border:false）→ 内线也不画
- */
-declare function resolveBoxBorders(style: Pick<ComponentStyle, "borderTop" | "borderRight" | "borderBottom" | "borderLeft"> | undefined): BoxBorders;
-
-interface RenderOptions {
-    dpi?: number;
-    classNames?: Partial<Record<ClassKey, string>>;
-}
-type ClassKey = "root" | "page" | "comp" | "text" | "lines" | "line" | "rich" | "paragraph" | "segment" | "image" | "shape" | "grid" | "row" | "cell" | "unknown";
-declare function classOf(key: ClassKey, options?: RenderOptions): string;
-declare function renderComponent(comp: PlanComponent, dpi: number, options: RenderOptions, doc: Document): HTMLElement;
-declare function renderPage(page: PlanPage, dpi: number, options: RenderOptions, doc: Document): HTMLElement;
-declare function renderPlan(plan: RenderPlan, doc: Document, options?: RenderOptions): HTMLElement;
-
-interface CanvasRenderOptions {
-    /** 设备像素比，默认取运行环境 devicePixelRatio */
-    dpr?: number;
-    dpi?: number;
-    /** 文本默认字体族 */
-    fontFamily?: string;
-    /** 文本测量器（默认启发式） */
-    measurer?: TextMeasurer;
-    /** 只渲染页区间（闭区间索引；缺省全渲染——仅小报表使用，大报表请用 createCanvasPager） */
-    start?: number;
-    end?: number;
-}
-declare function measurePageSizePx(page: Pick<PlanPage, "pageWidthMm" | "pageHeightMm">, dpi?: number): {
-    widthPx: number;
-    heightPx: number;
-};
-/** pt→px 换算（与 DOM 后端 units.ptToPx 同一真相源），供单测直接断言 */
-declare function planFontSizePx(style: {
-    fontSizePx?: number;
-    fontSize?: number;
-} | undefined, dpi?: number): number;
-interface CanvasRenderResult {
-    canvases: HTMLCanvasElement[];
-}
-/**
- * RenderPlan → Canvas 位图页（顶点原点坐标系，与 DOM/PDF 一致）。
- *
- * ⚠️ 内存模型：A4 @dpr2 ≈ 14MB/页，全量渲染 100 页 ≈ 1.4GB。
- * 大报表必须使用 createCanvasPager（窗口化 + 画布池 + 分帧渲染），
- * 本函数适合页数少或已指定 start/end 区间的场景。
- */
-declare function renderPlanToCanvas(plan: RenderPlan, options?: CanvasRenderOptions): CanvasRenderResult;
-interface CanvasPagerOptions extends CanvasRenderOptions {
-    /** 预渲染页数缓冲（窗口两侧各加 N 页），默认 1 */
-    overscan?: number;
-    /** 页间距 px，默认 18 */
-    gapPx?: number;
-    /** 每帧渲染页数上限（分帧，防长任务），默认 1 */
-    pagesPerFrame?: number;
-}
-interface CanvasPager {
-    /** 挂载到滚动容器（viewport，overflow:auto），接管其内容 */
-    attach(viewport: HTMLElement): void;
-    destroy(): void;
-    /** 当前实际渲染的页区间 */
-    window(): {
-        start: number;
-        end: number;
-    };
-}
-/**
- * Canvas 虚拟化分页器（大报表专用）：
- * - 视口窗口化：只绘制窗口内页（computePageWindow 与 DOM 后端共用）
- * - 画布池：固定数量 canvas 复用重绘，滚动零新增位图
- * - 分帧：每帧最多 pagesPerFrame 页，滚动期间不产生长任务
- *
- * 内存从 O(总页数) 降到 O(窗口+2×overscan)。
- */
-declare function createCanvasPager(plan: RenderPlan, options?: CanvasPagerOptions): CanvasPager;
-
-interface PageWindowInput {
-    pageHeightsPx: number[];
-    viewportHeightPx: number;
-    scrollTopPx: number;
-    overscan?: number;
-    /** 页间距（px）。占位高度按“每页高度+间距”累计，与 margin-bottom 布局一致；默认 0 */
-    gapPx?: number;
-}
-interface PageWindow {
-    start: number;
-    end: number;
-    padTopPx: number;
-    padBottomPx: number;
-}
-/**
- * 页级视口虚拟化：给定每页高度与滚动位置，返回需要真实渲染的页区间
- * 与上下占位高度。start/end 为闭区间索引。
- *
- * 布局模型：每页占据 height + gap（gap 为页间距，默认 0），
- * padTop/padBottom 同口径累计，保证 占位+渲染页+间距 还原总滚动高度。
- * 内部用前缀和 + 二分定位覆盖页与可见终点。
- */
-declare function computePageWindow(input: PageWindowInput): PageWindow;
-
-interface Jh4jImportResult {
-    template: ReportTemplate;
-    warnings: string[];
-}
-type Raw = Record<string, unknown>;
-/**
- * jh4j 模板 content（exportBackendPrintConfig 产物，见 docs/reverse-findings.md §6）
- * → MachReport ReportTemplate。单向转换，未知结构降级 + 告警，绝不抛错。
- */
-declare function importJh4jTemplateContent(content: string | Raw): Jh4jImportResult;
-
-type Geometry = Partial<Pick<PlanComponent, "leftMm" | "topMm" | "widthMm" | "heightMm">>;
-/** 纸张预设名（对齐 PAPER_SIZES 表） */
-type PaperName = keyof typeof PAPER_SIZES;
-interface PageOptions {
-    /** 横向（宽高互换） */
-    landscape?: boolean;
-    margins?: Partial<Pick<TemplatePage, "marginTopMm" | "marginBottomMm" | "marginLeftMm" | "marginRightMm">>;
-}
-type PageMargins = Partial<Pick<TemplatePage, "marginTopMm" | "marginBottomMm" | "marginLeftMm" | "marginRightMm">>;
-/** 解析纸张参数：数字按宽高使用；字符串查 PAPER_SIZES 预设；缺省 A4 纵向 */
-declare function resolvePaper(paper: PaperName | {
-    widthMm: number;
-    heightMm: number;
-} | number, heightArg?: number, landscape?: boolean): {
-    widthMm: number;
-    heightMm: number;
-};
-declare class TemplateBuilder {
-    readonly pages: TemplatePage[];
-    private pending;
-    /**
-     * 新建页。纸张支持三种写法：
-     * - 预设名：.page("a4", { landscape: true, margins: {...} })
-     * - 数字：.page(210, 297)（第三参数兼容旧 margins 对象或新 options）
-     * - 对象：.page({ widthMm: 210, heightMm: 297 })
-     */
-    page(paper?: PaperName | {
-        widthMm: number;
-        heightMm: number;
-    } | number, optionsOrHeight?: number | PageOptions, maybeOptions?: PageOptions | PageMargins): PageBuilder;
-    collect(): void;
-    build(): ReportTemplate;
-}
-declare class PageBuilder {
-    private readonly parent;
-    private readonly page;
-    private components;
-    constructor(parent: TemplateBuilder, page: Omit<TemplatePage, "components">);
-    text(content: string, geometry?: Geometry, style?: ComponentStyle): this;
-    list(dataset: string, geometry: Partial<Pick<ListComponent, "leftMm" | "topMm" | "widthMm">>, columns: ListColumn[], options?: Partial<Omit<ListComponent, "kind" | "leftMm" | "topMm" | "widthMm" | "dataset" | "columns">>): this;
-    rect(geometry: Required<Pick<PlanComponent, "leftMm" | "topMm" | "widthMm" | "heightMm">>, style?: ComponentStyle): this;
-    line(leftMm: number, topMm: number, widthMm: number, style?: ComponentStyle): this;
-    barcode(content: string, geometry: Required<Geometry>): this;
-    qrcode(content: string, sizeMm: number, leftMm: number, topMm: number): this;
-    buildPage(): TemplatePage;
-    done(): TemplateBuilder;
-    build(): ReportTemplate;
-}
-declare function createTemplate(): TemplateBuilder;
-
-export { type BoxBorders, CSS_DPI, type CanvasPager, type CanvasPagerOptions, type CanvasRenderOptions, type CanvasRenderResult, type ClassKey, ComponentStyle, DEFAULT_BORDER_PT, DEFAULT_FONT_PT, DEFAULT_STROKE_COLOR, DEFAULT_TEXT_COLOR, type DatasetRows, GridCell, type GridCellBox, type GridEdge, type GridLayout, type Jh4jImportResult, LINE_HEIGHT, type ListColumn, type ListComponent, MM_PER_INCH, PAPER_SIZES, PageBuilder, type PageOptions, type PageWindow, type PageWindowInput, type PaginateOptions, type PaginateResult, type PaperName, PlanComponent, PlanGrid, PlanPage, type RenderOptions, RenderPlan, type ReportTemplate, type ResolvedFontSize, SCHEMA_VERSION_JH4J, SCHEMA_VERSION_LOCAL, SCHEMA_VERSION_MACH, TemplateBuilder, type TemplateComponent, type TemplatePage, TextMeasurer, type ValidationError, type ValidationResult, assertRenderPlan, classOf, computePageWindow, createCanvasPager, createTemplate, importJh4jTemplateContent, measurePageSizePx, mmToPx, mmToPxFactor, paginateTemplate, planFontSizePx, ptToPx, pxToMm, renderComponent, renderPage, renderPlan, renderPlanToCanvas, resolveBoxBorders, resolveFontSize, resolveGridLayout, resolveLineHeight, resolvePaper, resolveStroke, resolveTextColor, round, validateComponent, validatePage, validateRenderPlan };
+export * from './defaults';
+export * from './units';
+export * from './schema/render-plan';
+export * from './schema/validate';
+export * from './layout/textwrap';
+export * from './layout/paginate';
+export * from './render/grid-geometry';
+export * from './render/style';
+export * from './render/dom';
+export * from './render/canvas';
+export * from './render/window';
+export * from './compat/jh4j-template';
+export * from './builder/template-builder';