@agile-team/mach-report 1.2.2 → 2.1.0

package/dist/index.d.ts

@@ -1,14 +1,738 @@
-export * from './defaults';
-export * from './format';
-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';
+export declare function assertRenderPlan(input: unknown): PlanPage[];
+
+/** 盒子边框语义：四边开关 + 内部网格线（四边全关则内线不画） */
+export declare interface BoxBorders {
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+    left: boolean;
+    /** 网格内线（仅当任意外边开启） */
+    inner: boolean;
+}
+
+export declare interface CanvasPager {
+    /** 挂载到滚动容器（viewport，overflow:auto），接管其内容 */
+    attach(viewport: HTMLElement): void;
+    destroy(): void;
+    /** 当前实际渲染的页区间 */
+    window(): {
+        start: number;
+        end: number;
+    };
+}
+
+export declare interface CanvasPagerOptions extends CanvasRenderOptions {
+    /** 预渲染页数缓冲（窗口两侧各加 N 页），默认 1 */
+    overscan?: number;
+    /** 页间距 px，默认 18 */
+    gapPx?: number;
+    /** 每帧渲染页数上限（分帧，防长任务），默认 1 */
+    pagesPerFrame?: number;
+}
+
+export declare interface CanvasRenderOptions {
+    /** 设备像素比，默认取运行环境 devicePixelRatio */
+    dpr?: number;
+    dpi?: number;
+    /** 文本默认字体族 */
+    fontFamily?: string;
+    /** 文本测量器（默认启发式） */
+    measurer?: TextMeasurer;
+    /** 只渲染页区间（闭区间索引；缺省全渲染——仅小报表使用，大报表请用 createCanvasPager） */
+    start?: number;
+    end?: number;
+}
+
+export declare interface CanvasRenderResult {
+    canvases: HTMLCanvasElement[];
+}
+
+export declare function charWidthEm(ch: string): number;
+
+export declare type ClassKey = "root" | "page" | "comp" | "text" | "lines" | "line" | "rich" | "paragraph" | "segment" | "image" | "shape" | "grid" | "row" | "cell" | "unknown";
+
+export declare function classOf(key: ClassKey, options?: RenderOptions): string;
+
+/**
+ * 列值格式化（声明式、JSON 可序列化）。
+ * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
+ * 三后端（DOM/Canvas/PDF）零改动。
+ *
+ * 语义约定（v0.9 固化）：
+ * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
+ * - number.thousands 默认 false（千分位显式开启）
+ * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
+ *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
+ */
+export declare type ColumnFormat = {
+    kind: "number";
+    thousands?: boolean;
+    digits?: number;
+} | {
+    kind: "percent";
+    digits?: number;
+} | {
+    kind: "date";
+    pattern?: string;
+};
+
+export declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
+export declare interface ComponentStyle {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+
+/**
+ * 页级视口虚拟化：给定每页高度与滚动位置，返回需要真实渲染的页区间
+ * 与上下占位高度。start/end 为闭区间索引。
+ *
+ * 布局模型：每页占据 height + gap（gap 为页间距，默认 0），
+ * padTop/padBottom 同口径累计，保证 占位+渲染页+间距 还原总滚动高度。
+ * 内部用前缀和 + 二分定位覆盖页与可见终点。
+ */
+export declare function computePageWindow(input: PageWindowInput): PageWindow;
+
+/**
+ * 浏览器 Canvas 测量器：用真实字体 metrics 校准宽度（可选注入）。
+ * 无 2D 环境时自动回退启发式（Node/SSR 安全）。
+ */
+export declare function createCanvasMeasurer(getCtx2d: () => CanvasRenderingContext2D | null): TextMeasurer;
+
+/**
+ * Canvas 虚拟化分页器（大报表专用）：
+ * - 视口窗口化：只绘制窗口内页（computePageWindow 与 DOM 后端共用）
+ * - 画布池：固定数量 canvas 复用重绘，滚动零新增位图
+ * - 分帧：每帧最多 pagesPerFrame 页，滚动期间不产生长任务
+ *
+ * 内存从 O(总页数) 降到 O(窗口+2×overscan)。
+ */
+export declare function createCanvasPager(plan: RenderPlan, options?: CanvasPagerOptions): CanvasPager;
+
+/** 兼容旧 API：默认启发式测量 */
+export declare function createHeuristicMeasurer(): TextMeasurer;
+
+/**
+ * 框架无关的报表数据源：注册一次模板与取数，包内完成分页、校验、按 ID 顺序合并。
+ * 不缓存业务结果、不推断接口包装、不自动重试；鉴权与完整数据范围由宿主决定。
+ */
+export declare function createReportSource(reports: ReportRegistry, options?: {
+    onWarning?: (message: string) => void;
+}): ReportSource;
+
+/**
+ * 创建一页标准明细模板；分页与格式化继续由 paginateTemplate 处理。
+ * 固定列保持毫米宽度，自动列共享余量；全部固定列时表格宽度为列宽之和。
+ */
+export declare function createTableTemplate(options: TableTemplateOptions): ReportTemplate;
+
+export declare function createTemplate(): TemplateBuilder;
+
+export declare const CSS_DPI = 96;
+
+export declare type DatasetRows = Record<string, Record<string, unknown>[]>;
+
+/** 默认边框线宽（pt） */
+export declare const DEFAULT_BORDER_PT = 0.75;
+
+/** 默认字号（pt） */
+export declare const DEFAULT_FONT_PT = 10.5;
+
+/** 默认描边色 */
+export declare const DEFAULT_STROKE_COLOR = "#333333";
+
+/** 默认文本色 */
+export declare const DEFAULT_TEXT_COLOR = "#000000";
+
+/** 类型推导业务接口的响应，包内完成字段映射后交给同一分页流程。 */
+export declare function defineReport<TData>(definition: ReportDefinitionOptions<TData>): ReportDefinition;
+
+export declare function defineReport(definition: ReportDefinition): ReportDefinition;
+
+/**
+ * 规则求值语义：
+ * - 空值（null/undefined/""）永不命中（避免 Number("")===0 把空当 0 的隐式陷阱）
+ * - 数值比较：两侧均可数值化才比较；否则退化为字符串比较
+ */
+export declare function evalStyleRule(row: Record<string, unknown>, when: StyleRule["when"]): boolean;
+
+/**
+ * 应用格式化。非数值/无法解析时原样返回基础文本（降级不报错）：
+ * - number：digits 小数位 + 可选千分位（12,345.60；thousands 默认 false）
+ * - percent：×100 + % 后缀（digits 默认 2）
+ * - date：Date/日历日字符串 → pattern（默认 YYYY-MM-DD）；不可解析原样返回
+ */
+export declare function formatValue(value: unknown, format?: ColumnFormat): string;
+
+declare type Geometry = Partial<Pick<PlanComponent, "leftMm" | "topMm" | "widthMm" | "heightMm">>;
+
+export declare interface GridCell {
+    text?: string;
+    rawText?: string;
+    children?: PlanComponent[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle;
+}
+
+export declare 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 区间） */
+export declare interface GridEdge {
+    kind: "h" | "v";
+    pos: number;
+    from: number;
+    to: number;
+}
+
+export declare interface GridLayout {
+    columns: {
+        pos: number;
+        size: number;
+    }[];
+    rows: {
+        pos: number;
+        size: number;
+    }[];
+    cells: GridCellBox[];
+    /** 内部网格线段（不含外框；已跳过被 colSpan/rowSpan 跨越的边界，相邻段已合并） */
+    edges: GridEdge[];
+}
+
+/** 启发式测量器：无 Canvas 时的默认宽度估算 */
+export declare const heuristicMeasurer: TextMeasurer;
+
+export declare interface ImageRenderOptions extends CanvasRenderOptions {
+    /** 图片格式（默认 png；jpeg 体积更小但无透明） */
+    format?: "png" | "jpeg";
+    /** jpeg 质量 0-1（默认 0.92，仅 jpeg 生效） */
+    quality?: number;
+}
+
+export declare interface ImageRenderResult {
+    blobs: Blob[];
+}
+
+export declare function isImageBackedComponent(comp: PlanComponent): boolean;
+
+export declare function isRichText(comp: PlanComponent): boolean;
+
+/** 默认行高倍数（基线距 = 字号 × 该系数） */
+export declare const LINE_HEIGHT = 1.35;
+
+export declare interface ListColumn {
+    header: string;
+    field: string;
+    widthMm: number;
+    style?: ComponentStyle;
+    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
+    format?: ColumnFormat;
+    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
+    rules?: StyleRule[];
+}
+
+export declare 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;
+    /** 分组小计（组头/组尾小计/组头防孤行） */
+    groupBy?: ListGroupBy;
+    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
+    grandTotal?: ListGrandTotal;
+}
+
+export declare type ListGrandTotal = boolean | {
+    label?: string;
+    style?: ComponentStyle;
+    /** 合计列（缺省沿用 groupBy.subtotal） */
+    fields?: string[];
+};
+
+/** 分组小计配置（声明式，见 ListComponent.groupBy） */
+export declare interface ListGroupBy {
+    /** 分组字段（值变化即切组） */
+    field: string;
+    /** 组头文案模板，{value} 占位（默认 "{value}"） */
+    headerTemplate?: string;
+    headerStyle?: ComponentStyle;
+    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
+    subtotal?: string[];
+    subtotalStyle?: ComponentStyle;
+    subtotalLabel?: string;
+    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
+    keepWithNext?: boolean;
+}
+
+export declare function measurePageSizePx(page: Pick<PlanPage, "pageWidthMm" | "pageHeightMm">, dpi?: number): {
+    widthPx: number;
+    heightPx: number;
+};
+
+export declare function measureTextMm(text: string, options: TextMeasureOptions): number;
+
+export declare const MM_PER_INCH = 25.4;
+
+export declare function mmToPx(value: number, dpi?: number): number;
+
+export declare function mmToPxFactor(dpi?: number): number;
+
+export 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 type PageMargins = Partial<Pick<TemplatePage, "marginTopMm" | "marginBottomMm" | "marginLeftMm" | "marginRightMm">>;
+
+export declare interface PageOptions {
+    /** 横向（宽高互换） */
+    landscape?: boolean;
+    margins?: Partial<Pick<TemplatePage, "marginTopMm" | "marginBottomMm" | "marginLeftMm" | "marginRightMm">>;
+}
+
+export declare interface PageWindow {
+    start: number;
+    end: number;
+    padTopPx: number;
+    padBottomPx: number;
+}
+
+export declare interface PageWindowInput {
+    pageHeightsPx: number[];
+    viewportHeightPx: number;
+    scrollTopPx: number;
+    overscan?: number;
+    /** 页间距（px）。占位高度按“每页高度+间距”累计，与 margin-bottom 布局一致；默认 0 */
+    gapPx?: number;
+}
+
+export declare interface PaginateOptions {
+    /** 每行额外占高（mm），压测专用钩子 */
+    mmPerRow?: number;
+    /** 文本测量器（默认启发式；浏览器端可注入 canvas 测量校准） */
+    measurer?: TextMeasurer;
+}
+
+export declare interface PaginateResult {
+    plan: RenderPlan;
+    warnings: string[];
+}
+
+export declare function paginateTemplate(template: ReportTemplate, datasets: DatasetRows, optionsOrMmPerRow?: number | PaginateOptions): PaginateResult;
+
+export declare const PAPER_SIZES: Record<string, {
+    widthMm: number;
+    heightMm: number;
+}>;
+
+/** 纸张预设名（对齐 PAPER_SIZES 表） */
+export declare type PaperName = keyof typeof PAPER_SIZES;
+
+/** 日历日字符串 → 本地 Date（不含时间的纯日期，杜绝 UTC 偏移） */
+export declare function parseDateLocal(input: string): Date | null;
+
+export declare interface PlanComponent {
+    kind: ComponentKind;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph[];
+    imageData?: string;
+    grid?: PlanGrid;
+    style?: ComponentStyle;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+
+/** pt→px 换算（与 DOM 后端 units.ptToPx 同一真相源），供单测直接断言 */
+export declare function planFontSizePx(style: {
+    fontSizePx?: number;
+    fontSize?: number;
+} | undefined, dpi?: number): number;
+
+export declare interface PlanGrid {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+}
+
+export declare interface PlanPage {
+    pageWidthMm: number;
+    pageHeightMm: number;
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: PlanComponent[];
+}
+
+export declare function ptToPx(pt: number, dpi?: number): number;
+
+export declare function pxToMm(value: number, dpi?: number): number;
+
+export declare const RENDER_PLAN_SCHEMA_VERSION = "1.0.0-mach";
+
+export declare function renderComponent(comp: PlanComponent, dpi: number, options: RenderOptions, doc: Document): HTMLElement;
+
+export declare interface RenderOptions {
+    dpi?: number;
+    classNames?: Partial<Record<ClassKey, string>>;
+}
+
+export declare function renderPage(page: PlanPage, dpi: number, options: RenderOptions, doc: Document): HTMLElement;
+
+export declare interface RenderPlan {
+    schemaVersion: string;
+    pages: PlanPage[];
+}
+
+export declare function renderPlan(plan: RenderPlan, doc: Document, options?: RenderOptions): HTMLElement;
+
+/**
+ * RenderPlan → Canvas 位图页（顶点原点坐标系，与 DOM/PDF 一致）。
+ *
+ * ⚠️ 内存模型：A4 @dpr2 ≈ 14MB/页，全量渲染 100 页 ≈ 1.4GB。
+ * 大报表必须使用 createCanvasPager（窗口化 + 画布池 + 分帧渲染），
+ * 本函数适合页数少或已指定 start/end 区间的场景。
+ */
+export declare function renderPlanToCanvas(plan: RenderPlan, options?: CanvasRenderOptions): CanvasRenderResult;
+
+/**
+ * RenderPlan → 每页一张图片 Blob（浏览器环境）：
+ * 复用位图渲染管线（区间/dpr/字体/测量器均可配），再 toBlob 编码。
+ * 大报表建议配合 start/end 分批导出，避免一次性占用过多内存。
+ */
+export declare function renderPlanToImages(plan: RenderPlan, options?: ImageRenderOptions): Promise<ImageRenderResult>;
+
+export declare interface ReportDefinition {
+    template: ReportTemplate;
+    /** 静态数据；load 存在时优先使用 load 的结果。 */
+    datasets?: DatasetRows;
+    load?: (context: ReportLoadContext) => DatasetRows | Promise<DatasetRows>;
+    /** 覆盖模板参数定义，未提供时自动使用 template.params。 */
+    params?: ReportParamDef[];
+    pagination?: PaginateOptions;
+}
+
+export declare interface ReportDefinitionOptions<TData> extends Omit<ReportDefinition, "load" | "datasets"> {
+    load: (context: ReportLoadContext) => TData | Promise<TData>;
+    mapData: (data: TData, context: ReportLoadContext) => DatasetRows;
+}
+
+/** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
+export declare interface ReportFetcher {
+    (input: ReportFetchInput): Promise<RenderPlan>;
+    getParamDefs?: (reportIds: string[]) => ReportParamDef[];
+}
+
+export declare interface ReportFetchInput {
+    reportIds: string[];
+    params: Record<string, string>;
+    signal?: AbortSignal;
+    /** 本次分页与计划告警；未提供时使用数据源配置的告警通道。 */
+    onWarning?: (message: string) => void;
+}
+
+/** 取数与排版共同使用的请求上下文；取消只影响本次调用。 */
+export declare interface ReportLoadContext {
+    reportId: string;
+    params: Record<string, string>;
+    signal?: AbortSignal;
+}
+
+/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
+export declare interface ReportParamDef {
+    /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
+    field: string;
+    /** 显示名（缺省用 field） */
+    label?: string;
+    type?: "text" | "number" | "date" | "select";
+    /** select 选项 */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    defaultValue?: string;
+    required?: boolean;
+    placeholder?: string;
+}
+
+export declare type ReportRegistry = Record<string, ReportDefinition>;
+
+export declare interface ReportSource extends ReportFetcher {
+    getParamDefs(reportIds: string[]): ReportParamDef[];
+}
+
+export declare class ReportSourceError extends Error {
+    readonly code: "config" | "fetch" | "validate";
+    readonly cause?: unknown;
+    constructor(code: ReportSourceError["code"], message: string, cause?: unknown);
+}
+
+export declare interface ReportTemplate {
+    schemaVersion?: string;
+    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
+    params?: ReportParamDef[];
+    pages: TemplatePage[];
+}
+
+/**
+ * 边框开关解析：
+ * - 未声明（undefined）→ 四边全开（与既有 rect 总有边框的行为兼容）
+ * - 显式 false → 对应边关闭
+ * - 四边全关（如 list border:false）→ 内线也不画
+ */
+export declare function resolveBoxBorders(style: Pick<ComponentStyle, "borderTop" | "borderRight" | "borderBottom" | "borderLeft"> | undefined): BoxBorders;
+
+/** 解析后的字号（px 值已按 dpi 换算；pt 值供 PDF 使用） */
+export declare interface ResolvedFontSize {
+    fontSizePt: number;
+    fontSizePx: number;
+}
+
+/** 字号解析：fontSizePx 直通；否则 pt→px（与 units.ptToPx 同源） */
+export declare function resolveFontSize(style: Pick<ComponentStyle, "fontSizePx" | "fontSize"> | undefined, dpi?: number, defaultPt?: number): ResolvedFontSize;
+
+/**
+ * 网格几何统一解析（DOM/Canvas/PDF 三后端共用，单位真相源）：
+ * - 列宽：优先 colWidthsMm（等比缩放至组件宽），否则按列数均分
+ * - 行高：优先 rowHeightsMm（等比缩放至组件高），否则按行数均分
+ * - colSpan/rowSpan：占位矩阵展开，跨度取起止行列差；越界收敛到网格内
+ * - 行内 null/undefined 单元格视为占 1 列的空单元格（与 DOM 表格行为一致）
+ * - edges：内部网格线段，跳过被 span 跨越的边界（合并单元格中间无线）
+ * 产出为组件左上角顶点原点的 mm 坐标，各后端自行换算 px/pt。
+ */
+export declare function resolveGridLayout(grid: PlanGrid, compWidthMm: number, compHeightMm: number): GridLayout;
+
+/** 行高解析（倍数，基线距 = 字号 × lineHeight） */
+export declare function resolveLineHeight(style: Pick<ComponentStyle, "lineHeight"> | undefined): number;
+
+/** 解析纸张参数：数字按宽高使用；字符串查 PAPER_SIZES 预设；缺省 A4 纵向 */
+export declare function resolvePaper(paper: PaperName | {
+    widthMm: number;
+    heightMm: number;
+} | number, heightArg?: number, landscape?: boolean): {
+    widthMm: number;
+    heightMm: number;
+};
+
+/** 描边解析：颜色 + 线宽（pt） */
+export declare function resolveStroke(style: Pick<ComponentStyle, "borderColor" | "lineColor" | "lineWidthPt"> | undefined, fallbackColor?: string): {
+    color: string;
+    widthPt: number;
+};
+
+/** 文本颜色解析 */
+export declare function resolveTextColor(style: Pick<ComponentStyle, "color"> | undefined, fallback?: string): string;
+
+export declare interface RichParagraph {
+    segments: RichSegment[];
+    align?: ComponentStyle["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+
+export declare interface RichSegment {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle;
+}
+
+export declare function round(value: number, digits: number): number;
+
+/** RenderPlan 正式 schema 版本（core 分页引擎产出） */
+export declare const SCHEMA_VERSION_MACH = "1.0.0-mach";
+
+/** 条件格式规则求值（声明式，见 ListColumn.rules） */
+export declare interface StyleRule {
+    when: {
+        field: string;
+        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
+        value: number | string;
+    };
+    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
+    style: Record<string, unknown>;
+}
+
+/** 标准明细列：显式 widthMm 优先；其余列按 flex 分配剩余可用宽度。 */
+export declare type TableTemplateColumn = Omit<ListColumn, "widthMm"> & {
+    widthMm?: number;
+    /** 自动列的宽度权重，默认 1（有 widthMm 时不参与分配）。 */
+    flex?: number;
+};
+
+export declare type TableTemplateListOptions = Partial<Omit<ListComponent, "kind" | "leftMm" | "topMm" | "widthMm" | "dataset" | "columns">>;
+
+export declare interface TableTemplateOptions extends PageOptions {
+    title?: string;
+    /** 标题占高，默认 10mm；没有标题时不占空间。 */
+    titleHeightMm?: number;
+    /** 标题与表格间距，默认 4mm。 */
+    titleGapMm?: number;
+    titleStyle?: ComponentStyle;
+    dataset?: string;
+    columns: readonly TableTemplateColumn[];
+    /** 默认 A4；页边距各默认 10mm。 */
+    paper?: PaperName | {
+        widthMm: number;
+        heightMm: number;
+    };
+    params?: ReportTemplate["params"];
+    /** 沿用列表的字号、行高、重复表头、分组、小计与总计配置。 */
+    listOptions?: TableTemplateListOptions;
+}
+
+export declare class TemplateBuilder {
+    readonly pages: TemplatePage[];
+    private pending;
+    private templateParams;
+    /**
+     * 声明报表参数（链式，可放在 .page() 前后任意位置）：
+     * 渲染组件据此自动生成查询面板（也可由 paramDefs prop 提供，prop 优先）。
+     *
+     * ```ts
+     * createTemplate()
+     *   .params([
+     *     { field: "whCode", label: "仓库", type: "select", options: [...], required: true },
+     *     { field: "date", label: "日期", type: "date", defaultValue: "2026-09-30" }
+     *   ])
+     *   .page("a4").text(...).list(...)
+     *   .build();
+     * ```
+     */
+    params(defs: NonNullable<ReportTemplate["params"]>): this;
+    /**
+     * 新建页。纸张支持三种写法：
+     * - 预设名：.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;
+}
+
+export declare type TemplateComponent = PlanComponent | ListComponent;
+
+export declare interface TemplatePage {
+    widthMm: number;
+    heightMm: number;
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: TemplateComponent[];
+}
+
+/**
+ * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
+ *
+ * 测量模型可注入（TextMeasurer）：
+ * - 默认 createHeuristicMeasurer()：CJK/拉丁宽度启发式（零依赖、Node 可用）
+ * - 浏览器端可注入 createCanvasMeasurer()（真字体 metrics，消除三端折行差异）
+ */
+export declare interface TextMeasureOptions {
+    fontSizePt: number;
+    bold?: boolean;
+    letterSpacingPt?: number;
+}
+
+/** 宽度测量接口：返回文本在给定字号下的宽度（mm）。实现必须无副作用、可缓存。 */
+export declare interface TextMeasurer {
+    measureMm(text: string, options: TextMeasureOptions): number;
+}
+
+export declare function toNumber(value: unknown): number | null;
+
+export declare function validateComponent(comp: unknown, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
+
+export declare function validatePage(page: unknown, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
+
+export declare function validateRenderPlan(input: unknown): ValidationResult;
+
+export declare interface ValidationError {
+    path: string;
+    message: string;
+}
+
+export declare interface ValidationResult {
+    ok: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+
+/**
+ * 文本折行：
+ * - CJK 字符任意位置可断（与既有行为一致）
+ * - 连续拉丁/数字串视为一个词，仅在词间（空格/CJK 边界）断行；
+ *   单词本身超宽时按字符硬拆（兜底，不无限溢出）
+ * - 换行符强制断行；行首不保留折行产生的空格
+ * - 可注入 TextMeasurer（默认启发式）
+ */
+export declare function wrapText(text: string, maxWidthMm: number, options: TextMeasureOptions, measurer?: TextMeasurer): string[];
+
+export { }