@agile-team/mach-report 2.5.0 → 2.7.0

package/dist/pdf.d.cts

@@ -1,3 +1,32 @@
+declare interface AssetRenderBudget {
+    /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
+    maxAssets?: number;
+    /** Maximum image payload bytes per new asset, default 32 MiB. */
+    maxImageBytes?: number;
+    /** Maximum total image payload bytes for new assets, default 128 MiB. */
+    maxTotalImageBytes?: number;
+    /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
+    maxDurationMs?: number;
+}
+
+declare interface AssetRenderOptions extends OutputDiagnosticOptions {
+    assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    assetBudget?: AssetRenderBudget;
+    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
+    assetFailure?: "throw" | "placeholder";
+    signal?: AbortSignal;
+}
+
+declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+
+declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+
 declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
 
 declare interface ComponentStyle {
@@ -24,6 +53,19 @@ declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+/** Exact font-byte width adapter. Import from /pdf to keep fontkit outside the core bundle. */
+export declare function createFontBytesMeasurer(options: FontBytesMeasureOptions): TextMeasurer_2;
+
+export declare interface FontBytesMeasureOptions {
+    regular: Uint8Array | ArrayBuffer;
+    bold?: Uint8Array | ArrayBuffer;
+    italic?: Uint8Array | ArrayBuffer;
+    boldItalic?: Uint8Array | ArrayBuffer;
+    /** Optional family guard: other font families use fallback instead of inaccurate metrics. */
+    fontFamily?: string;
+    fallback?: TextMeasurer_2;
+}
+
 export declare interface FontLoadOptions {
     /** 校验字体格式与可解析结构，失败抛出带 cause 的诊断；默认保留旧 API 的 null 降级。 */
     strict?: boolean;
@@ -40,6 +82,7 @@ declare interface GridCell {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -48,6 +91,8 @@ declare interface GridCell {
     style?: ComponentStyle;
 }
 
+declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+
 /** 删除已知无效的字体缓存；供字体解析失败后修正同 URL 并重试。 */
 export declare function invalidateFontCache(url: string): Promise<void>;
 
@@ -58,6 +103,34 @@ export declare function invalidateFontCache(url: string): Promise<void>;
  */
 export declare function loadFontWithCache(url: string, options?: FontLoadOptions): Promise<Uint8Array | null>;
 
+declare interface OutputDiagnostic {
+    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "unsupported-style" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
+    severity: "warning";
+    format: OutputFormat;
+    pageIndex: number;
+    componentIndex: number;
+    /** Nested grid child location as repeating [rowIndex, columnIndex, childIndex] triples. */
+    componentPath?: readonly number[];
+    kind: string;
+    nid?: string;
+    message: string;
+}
+
+declare interface OutputDiagnosticOptions extends OutputTaskOptions {
+    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
+    onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
+    /** Reject known unsupported content before creating an incomplete file. Default warn. */
+    fidelity?: "warn" | "strict";
+}
+
+declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
+
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+declare interface OutputTaskOptions {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+
 /**
  * PDF 文档句柄（不透明最小面）：结构化仅暴露 save()，
  * 避免在公共类型面泄漏 pdf-lib 类型（引擎保持零运行时依赖声明）。
@@ -66,10 +139,17 @@ export declare type PdfDocumentHandle = {
     save(): Promise<Uint8Array>;
 };
 
-export declare interface PdfRenderOptions {
+export declare interface PdfRenderOptions extends AssetRenderOptions, OutputTaskOptions {
     /** 嵌入字体字节（TTF，如黑体）；缺省用 Helvetica（不支持 CJK） */
     customFontBytes?: Uint8Array | ArrayBuffer;
     customFontName?: string;
+    /** Explicit faces preserve bold/italic; missing faces fall back to regular and emit a fidelity warning. */
+    customFontFaces?: {
+        regular: Uint8Array | ArrayBuffer;
+        bold?: Uint8Array | ArrayBuffer;
+        italic?: Uint8Array | ArrayBuffer;
+        boldItalic?: Uint8Array | ArrayBuffer;
+    };
     /** 文本测量器（默认启发式；与分页/Canvas 注入同一实例可消除折行差异） */
     measurer?: TextMeasurer;
 }
@@ -81,6 +161,7 @@ export declare interface PdfRenderResult {
     unsupportedTextCount: number;
     /** 保真度降级清单（富文本转纯文本、图片格式不支持等），供上层提示 */
     fidelityWarnings: string[];
+    diagnostics: OutputDiagnostic[];
 }
 
 declare interface PlanComponent {
@@ -96,6 +177,8 @@ declare interface PlanComponent {
     lines?: string[];
     richParagraphs?: RichParagraph[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid;
     table?: PlanTableFragment;
     style?: ComponentStyle;
@@ -137,6 +220,10 @@ declare interface PlanTableFragment {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
 }
 
 declare interface RenderPlan {
@@ -146,6 +233,15 @@ declare interface RenderPlan {
 
 export declare function renderPlanToPdf(plan: RenderPlan, options?: PdfRenderOptions): Promise<PdfRenderResult>;
 
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
 declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -171,7 +267,24 @@ declare interface RichSegment {
  */
 declare interface TextMeasureOptions {
     fontSizePt: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    letterSpacingPt?: number;
+}
+
+/**
+ * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
+ *
+ * 测量模型可注入（TextMeasurer）：
+ * - 默认 createHeuristicMeasurer()：CJK/拉丁宽度启发式（零依赖、Node 可用）
+ * - 浏览器端可注入 createCanvasMeasurer()（真字体 metrics，消除三端折行差异）
+ */
+declare interface TextMeasureOptions_2 {
+    fontSizePt: number;
+    fontFamily?: string;
     bold?: boolean;
+    italic?: boolean;
     letterSpacingPt?: number;
 }
 
@@ -180,4 +293,9 @@ declare interface TextMeasurer {
     measureMm(text: string, options: TextMeasureOptions): number;
 }
 
+/** 宽度测量接口：返回文本在给定字号下的宽度（mm）。实现必须无副作用、可缓存。 */
+declare interface TextMeasurer_2 {
+    measureMm(text: string, options: TextMeasureOptions_2): number;
+}
+
 export { }

package/dist/pdf.d.ts

@@ -1,3 +1,32 @@
+declare interface AssetRenderBudget {
+    /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
+    maxAssets?: number;
+    /** Maximum image payload bytes per new asset, default 32 MiB. */
+    maxImageBytes?: number;
+    /** Maximum total image payload bytes for new assets, default 128 MiB. */
+    maxTotalImageBytes?: number;
+    /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
+    maxDurationMs?: number;
+}
+
+declare interface AssetRenderOptions extends OutputDiagnosticOptions {
+    assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    assetBudget?: AssetRenderBudget;
+    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
+    assetFailure?: "throw" | "placeholder";
+    signal?: AbortSignal;
+}
+
+declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+
+declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+
 declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
 
 declare interface ComponentStyle {
@@ -24,6 +53,19 @@ declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+/** Exact font-byte width adapter. Import from /pdf to keep fontkit outside the core bundle. */
+export declare function createFontBytesMeasurer(options: FontBytesMeasureOptions): TextMeasurer_2;
+
+export declare interface FontBytesMeasureOptions {
+    regular: Uint8Array | ArrayBuffer;
+    bold?: Uint8Array | ArrayBuffer;
+    italic?: Uint8Array | ArrayBuffer;
+    boldItalic?: Uint8Array | ArrayBuffer;
+    /** Optional family guard: other font families use fallback instead of inaccurate metrics. */
+    fontFamily?: string;
+    fallback?: TextMeasurer_2;
+}
+
 export declare interface FontLoadOptions {
     /** 校验字体格式与可解析结构，失败抛出带 cause 的诊断；默认保留旧 API 的 null 降级。 */
     strict?: boolean;
@@ -40,6 +82,7 @@ declare interface GridCell {
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
+    source?: ReportCellSource;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -48,6 +91,8 @@ declare interface GridCell {
     style?: ComponentStyle;
 }
 
+declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+
 /** 删除已知无效的字体缓存；供字体解析失败后修正同 URL 并重试。 */
 export declare function invalidateFontCache(url: string): Promise<void>;
 
@@ -58,6 +103,34 @@ export declare function invalidateFontCache(url: string): Promise<void>;
  */
 export declare function loadFontWithCache(url: string, options?: FontLoadOptions): Promise<Uint8Array | null>;
 
+declare interface OutputDiagnostic {
+    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "unsupported-style" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
+    severity: "warning";
+    format: OutputFormat;
+    pageIndex: number;
+    componentIndex: number;
+    /** Nested grid child location as repeating [rowIndex, columnIndex, childIndex] triples. */
+    componentPath?: readonly number[];
+    kind: string;
+    nid?: string;
+    message: string;
+}
+
+declare interface OutputDiagnosticOptions extends OutputTaskOptions {
+    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
+    onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
+    /** Reject known unsupported content before creating an incomplete file. Default warn. */
+    fidelity?: "warn" | "strict";
+}
+
+declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
+
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+declare interface OutputTaskOptions {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+
 /**
  * PDF 文档句柄（不透明最小面）：结构化仅暴露 save()，
  * 避免在公共类型面泄漏 pdf-lib 类型（引擎保持零运行时依赖声明）。
@@ -66,10 +139,17 @@ export declare type PdfDocumentHandle = {
     save(): Promise<Uint8Array>;
 };
 
-export declare interface PdfRenderOptions {
+export declare interface PdfRenderOptions extends AssetRenderOptions, OutputTaskOptions {
     /** 嵌入字体字节（TTF，如黑体）；缺省用 Helvetica（不支持 CJK） */
     customFontBytes?: Uint8Array | ArrayBuffer;
     customFontName?: string;
+    /** Explicit faces preserve bold/italic; missing faces fall back to regular and emit a fidelity warning. */
+    customFontFaces?: {
+        regular: Uint8Array | ArrayBuffer;
+        bold?: Uint8Array | ArrayBuffer;
+        italic?: Uint8Array | ArrayBuffer;
+        boldItalic?: Uint8Array | ArrayBuffer;
+    };
     /** 文本测量器（默认启发式；与分页/Canvas 注入同一实例可消除折行差异） */
     measurer?: TextMeasurer;
 }
@@ -81,6 +161,7 @@ export declare interface PdfRenderResult {
     unsupportedTextCount: number;
     /** 保真度降级清单（富文本转纯文本、图片格式不支持等），供上层提示 */
     fidelityWarnings: string[];
+    diagnostics: OutputDiagnostic[];
 }
 
 declare interface PlanComponent {
@@ -96,6 +177,8 @@ declare interface PlanComponent {
     lines?: string[];
     richParagraphs?: RichParagraph[];
     imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
     grid?: PlanGrid;
     table?: PlanTableFragment;
     style?: ComponentStyle;
@@ -137,6 +220,10 @@ declare interface PlanTableFragment {
     columnKeys: string[];
     layout?: "page" | "wide";
     title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
 }
 
 declare interface RenderPlan {
@@ -146,6 +233,15 @@ declare interface RenderPlan {
 
 export declare function renderPlanToPdf(plan: RenderPlan, options?: PdfRenderOptions): Promise<PdfRenderResult>;
 
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
 declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -171,7 +267,24 @@ declare interface RichSegment {
  */
 declare interface TextMeasureOptions {
     fontSizePt: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    letterSpacingPt?: number;
+}
+
+/**
+ * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
+ *
+ * 测量模型可注入（TextMeasurer）：
+ * - 默认 createHeuristicMeasurer()：CJK/拉丁宽度启发式（零依赖、Node 可用）
+ * - 浏览器端可注入 createCanvasMeasurer()（真字体 metrics，消除三端折行差异）
+ */
+declare interface TextMeasureOptions_2 {
+    fontSizePt: number;
+    fontFamily?: string;
     bold?: boolean;
+    italic?: boolean;
     letterSpacingPt?: number;
 }
 
@@ -180,4 +293,9 @@ declare interface TextMeasurer {
     measureMm(text: string, options: TextMeasureOptions): number;
 }
 
+/** 宽度测量接口：返回文本在给定字号下的宽度（mm）。实现必须无副作用、可缓存。 */
+declare interface TextMeasurer_2 {
+    measureMm(text: string, options: TextMeasureOptions_2): number;
+}
+
 export { }