@agile-team/mach-report 2.0.0 → 2.1.0

package/dist/pdf.d.cts

@@ -1,6 +1,155 @@
-/**
- * PDF 直出子路径入口（@agile-team/mach-report/pdf）：
- * 矢量 PDF 生成 + 字体缓存。pdf-lib 为常规依赖，
- * 仅当导入本子路径或触发懒加载导出时才进入产物图。
- */
-export * from './pdf/index';
+declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
+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;
+}
+
+export declare interface FontLoadOptions {
+    /** 校验字体格式与可解析结构，失败抛出带 cause 的诊断；默认保留旧 API 的 null 降级。 */
+    strict?: boolean;
+}
+
+declare interface GridCell {
+    text?: string;
+    rawText?: string;
+    children?: PlanComponent[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle;
+}
+
+/** 删除已知无效的字体缓存；供字体解析失败后修正同 URL 并重试。 */
+export declare function invalidateFontCache(url: string): Promise<void>;
+
+/**
+ * 字体加载（浏览器：IndexedDB 持久缓存 + 内存缓存；Node/SSR：内存缓存 + fetch）：
+ * 中文字体体积大（simhei ~9MB），首次 fetch 后缓存，后续导出零网络等待。
+ * 双环境兼容——同一引擎可在 Node 做无头导出（定时任务/归档）。
+ */
+export declare function loadFontWithCache(url: string, options?: FontLoadOptions): Promise<Uint8Array | null>;
+
+/**
+ * PDF 文档句柄（不透明最小面）：结构化仅暴露 save()，
+ * 避免在公共类型面泄漏 pdf-lib 类型（引擎保持零运行时依赖声明）。
+ */
+export declare type PdfDocumentHandle = {
+    save(): Promise<Uint8Array>;
+};
+
+export declare interface PdfRenderOptions {
+    /** 嵌入字体字节（TTF，如黑体）；缺省用 Helvetica（不支持 CJK） */
+    customFontBytes?: Uint8Array | ArrayBuffer;
+    customFontName?: string;
+    /** 文本测量器（默认启发式；与分页/Canvas 注入同一实例可消除折行差异） */
+    measurer?: TextMeasurer;
+}
+
+export declare interface PdfRenderResult {
+    pdfDoc: PdfDocumentHandle;
+    bytes: Uint8Array;
+    pageErrors: string[];
+    unsupportedTextCount: number;
+    /** 保真度降级清单（富文本转纯文本、图片格式不支持等），供上层提示 */
+    fidelityWarnings: string[];
+}
+
+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;
+}
+
+declare interface PlanGrid {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+}
+
+declare interface PlanPage {
+    pageWidthMm: number;
+    pageHeightMm: number;
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: PlanComponent[];
+}
+
+declare interface RenderPlan {
+    schemaVersion: string;
+    pages: PlanPage[];
+}
+
+export declare function renderPlanToPdf(plan: RenderPlan, options?: PdfRenderOptions): Promise<PdfRenderResult>;
+
+declare interface RichParagraph {
+    segments: RichSegment[];
+    align?: ComponentStyle["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+
+declare interface RichSegment {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle;
+}
+
+/**
+ * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
+ *
+ * 测量模型可注入（TextMeasurer）：
+ * - 默认 createHeuristicMeasurer()：CJK/拉丁宽度启发式（零依赖、Node 可用）
+ * - 浏览器端可注入 createCanvasMeasurer()（真字体 metrics，消除三端折行差异）
+ */
+declare interface TextMeasureOptions {
+    fontSizePt: number;
+    bold?: boolean;
+    letterSpacingPt?: number;
+}
+
+/** 宽度测量接口：返回文本在给定字号下的宽度（mm）。实现必须无副作用、可缓存。 */
+declare interface TextMeasurer {
+    measureMm(text: string, options: TextMeasureOptions): number;
+}
+
+export { }

package/dist/pdf.d.ts

@@ -1,6 +1,155 @@
-/**
- * PDF 直出子路径入口（@agile-team/mach-report/pdf）：
- * 矢量 PDF 生成 + 字体缓存。pdf-lib 为常规依赖，
- * 仅当导入本子路径或触发懒加载导出时才进入产物图。
- */
-export * from './pdf/index';
+declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
+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;
+}
+
+export declare interface FontLoadOptions {
+    /** 校验字体格式与可解析结构，失败抛出带 cause 的诊断；默认保留旧 API 的 null 降级。 */
+    strict?: boolean;
+}
+
+declare interface GridCell {
+    text?: string;
+    rawText?: string;
+    children?: PlanComponent[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle;
+}
+
+/** 删除已知无效的字体缓存；供字体解析失败后修正同 URL 并重试。 */
+export declare function invalidateFontCache(url: string): Promise<void>;
+
+/**
+ * 字体加载（浏览器：IndexedDB 持久缓存 + 内存缓存；Node/SSR：内存缓存 + fetch）：
+ * 中文字体体积大（simhei ~9MB），首次 fetch 后缓存，后续导出零网络等待。
+ * 双环境兼容——同一引擎可在 Node 做无头导出（定时任务/归档）。
+ */
+export declare function loadFontWithCache(url: string, options?: FontLoadOptions): Promise<Uint8Array | null>;
+
+/**
+ * PDF 文档句柄（不透明最小面）：结构化仅暴露 save()，
+ * 避免在公共类型面泄漏 pdf-lib 类型（引擎保持零运行时依赖声明）。
+ */
+export declare type PdfDocumentHandle = {
+    save(): Promise<Uint8Array>;
+};
+
+export declare interface PdfRenderOptions {
+    /** 嵌入字体字节（TTF，如黑体）；缺省用 Helvetica（不支持 CJK） */
+    customFontBytes?: Uint8Array | ArrayBuffer;
+    customFontName?: string;
+    /** 文本测量器（默认启发式；与分页/Canvas 注入同一实例可消除折行差异） */
+    measurer?: TextMeasurer;
+}
+
+export declare interface PdfRenderResult {
+    pdfDoc: PdfDocumentHandle;
+    bytes: Uint8Array;
+    pageErrors: string[];
+    unsupportedTextCount: number;
+    /** 保真度降级清单（富文本转纯文本、图片格式不支持等），供上层提示 */
+    fidelityWarnings: string[];
+}
+
+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;
+}
+
+declare interface PlanGrid {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+}
+
+declare interface PlanPage {
+    pageWidthMm: number;
+    pageHeightMm: number;
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: PlanComponent[];
+}
+
+declare interface RenderPlan {
+    schemaVersion: string;
+    pages: PlanPage[];
+}
+
+export declare function renderPlanToPdf(plan: RenderPlan, options?: PdfRenderOptions): Promise<PdfRenderResult>;
+
+declare interface RichParagraph {
+    segments: RichSegment[];
+    align?: ComponentStyle["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+
+declare interface RichSegment {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle;
+}
+
+/**
+ * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
+ *
+ * 测量模型可注入（TextMeasurer）：
+ * - 默认 createHeuristicMeasurer()：CJK/拉丁宽度启发式（零依赖、Node 可用）
+ * - 浏览器端可注入 createCanvasMeasurer()（真字体 metrics，消除三端折行差异）
+ */
+declare interface TextMeasureOptions {
+    fontSizePt: number;
+    bold?: boolean;
+    letterSpacingPt?: number;
+}
+
+/** 宽度测量接口：返回文本在给定字号下的宽度（mm）。实现必须无副作用、可缓存。 */
+declare interface TextMeasurer {
+    measureMm(text: string, options: TextMeasureOptions): number;
+}
+
+export { }