@agile-team/mach-report 2.15.0 → 2.17.0

package/dist/vue/index.d.cts

@@ -74,6 +74,10 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
         type: PropType<ReportOutputOptions>;
         default: undefined;
     };
+    exportExecution: {
+        type: PropType<ReportExportExecutionOptions>;
+        default: undefined;
+    };
     assets: {
         type: PropType<AssetRenderOptions>;
         default: undefined;
@@ -244,6 +248,10 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
         type: PropType<ReportOutputOptions>;
         default: undefined;
     };
+    exportExecution: {
+        type: PropType<ReportExportExecutionOptions>;
+        default: undefined;
+    };
     assets: {
         type: PropType<AssetRenderOptions>;
         default: undefined;
@@ -325,6 +333,7 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
     showPdfWindow: boolean;
     showSettings: boolean;
     showParams: boolean;
+    exportExecution: ReportExportExecutionOptions;
     drill: ReportDrillOptions;
     loadParamOptions: ReportParamOptionsLoader;
     printOptions: ReportPrintOptions;
@@ -489,13 +498,42 @@ declare interface AssetRenderBudget {
     /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
     maxDurationMs?: number;
 }
+declare interface AssetRenderBudget_2 {
+    /** 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, ImageMediaOptions {
     assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    /** Explicit id/version registry; unbound components continue using assetRenderers by kind. */
+    assetRegistry?: ComponentAssetRegistry;
     assetBudget?: AssetRenderBudget;
     /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
     assetFailure?: "throw" | "placeholder";
     signal?: AbortSignal;
 }
+declare interface AssetRenderOptions_2 extends OutputDiagnosticOptions_2, ImageMediaOptions_2 {
+    assetRenderers?: Partial<Record<ImageComponentKind_2, ComponentImageRenderer_2>>;
+    /** Explicit id/version registry; unbound components continue using assetRenderers by kind. */
+    assetRegistry?: ComponentAssetRegistry_2;
+    assetBudget?: AssetRenderBudget_2;
+    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
+    assetFailure?: "throw" | "placeholder";
+    signal?: AbortSignal;
+}
+declare interface BrowserReportWorker {
+    postMessage(value: unknown, transfer?: Transferable[]): void;
+    terminate(): void;
+    addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    addEventListener(type: "error" | "messageerror", listener: (event: Event) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "error" | "messageerror", listener: (event: Event) => void): void;
+}
 /** 供 HTML/Word 导出的完整文档；打印路径逐页渲染，避免预先生成所有页。 */
 export declare function buildPrintDocument(p: RenderPlan, options?: ReportPrintOptions): PrintHtmlResult;
 export declare function buildWordHtml(p: RenderPlan): {
@@ -601,6 +639,14 @@ declare type ColumnFormat_3 = {
     kind: "date";
     pattern?: string;
 };
+declare interface ComponentAssetRegistry {
+    rendererFor(component: Readonly<PlanComponent>): ComponentImageRenderer | undefined;
+    hasExtension(id: string, version: string, kind: string): boolean;
+}
+declare interface ComponentAssetRegistry_2 {
+    rendererFor(component: Readonly<PlanComponent_2>): ComponentImageRenderer_2 | undefined;
+    hasExtension(id: string, version: string, kind: string): boolean;
+}
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
 declare interface ComponentBinding {
     field: string;
@@ -632,7 +678,15 @@ declare interface ComponentImageContext {
     readonly componentPath: readonly number[];
     readonly signal: AbortSignal;
 }
+declare interface ComponentImageContext_2 {
+    readonly component: Readonly<PlanComponent_2>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
 declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+declare type ComponentImageRenderer_2 = (context: ComponentImageContext_2) => string | Promise<string>;
 declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
 declare type ComponentKind_2 = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
 declare type ComponentKind_3 = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
@@ -907,6 +961,8 @@ declare interface FormulaAdapter {
     }): unknown;
 }
 declare interface GridCell {
+    /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
+    richParagraphs?: RichParagraph[];
     text?: string;
     rawText?: string;
     /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
@@ -930,6 +986,8 @@ declare interface GridCell {
     style?: ComponentStyle;
 }
 declare interface GridCell_2 {
+    /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
+    richParagraphs?: RichParagraph_2[];
     text?: string;
     rawText?: string;
     /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
@@ -953,6 +1011,8 @@ declare interface GridCell_2 {
     style?: ComponentStyle_2;
 }
 declare interface GridCell_3 {
+    /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
+    richParagraphs?: RichParagraph_3[];
     text?: string;
     rawText?: string;
     /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
@@ -984,6 +1044,7 @@ export declare type HostRequest = (config: {
     signal?: AbortSignal;
 }) => Promise<unknown>;
 declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+declare type ImageComponentKind_2 = "image" | "chart" | "barcode" | "qrcode";
 /** Bounded binary image inspection shared by PDF, Excel and template import. No decoder is loaded. */
 declare interface ImageMediaOptions {
     maxImageBytes?: number;
@@ -1422,6 +1483,8 @@ export declare interface MachReportController {
 }
 /** defaults 层可配置项（全部可选，均有内置缺省） */
 export declare interface MachReportDefaults {
+    /** Small encodes stay local; optional Worker isolation uses the same prepared plan for large output. */
+    exportExecution?: ReportExportExecutionOptions;
     drill?: ReportDrillOptions;
     loadParamOptions?: ReportParamOptionsLoader;
     printOptions?: ReportPrintOptions;
@@ -1778,6 +1841,57 @@ export declare interface MachReportToolbarOptions {
     /** 未传时显示全部已有出口；空数组表示不提供导出工具。 */
     exportFormats?: ReportExportFormat[];
 }
+declare interface MatrixAxisOptions {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+declare interface MatrixAxisOptions_2 {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder_2[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+declare interface MatrixAxisOptions_3 {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder_3[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+declare type MatrixDimensionOrder = "source" | "asc" | "desc";
+declare type MatrixDimensionOrder_2 = "source" | "asc" | "desc";
+declare type MatrixDimensionOrder_3 = "source" | "asc" | "desc";
+declare interface MatrixHierarchyOptions {
+    row?: MatrixAxisOptions;
+    column?: MatrixAxisOptions;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
+declare interface MatrixHierarchyOptions_2 {
+    row?: MatrixAxisOptions_2;
+    column?: MatrixAxisOptions_2;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
+declare interface MatrixHierarchyOptions_3 {
+    row?: MatrixAxisOptions_3;
+    column?: MatrixAxisOptions_3;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
 declare interface MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -1792,6 +1906,10 @@ declare interface MatrixTableOptions {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
 }
 declare interface MatrixTableOptions_2 {
     rowFields: readonly string[];
@@ -1807,6 +1925,10 @@ declare interface MatrixTableOptions_2 {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions_2;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
 }
 declare interface MatrixTableOptions_3 {
     rowFields: readonly string[];
@@ -1822,6 +1944,10 @@ declare interface MatrixTableOptions_3 {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions_3;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
 }
 export declare function normalizeReportIds(reportId: ReportIdInput): string[];
 /** Workers preserve stable error codes, not JavaScript class identity. Only known codes cross the UI boundary. */
@@ -1836,6 +1962,11 @@ declare interface OutputDiagnostic {
     componentPath?: readonly number[];
     kind: string;
     nid?: string;
+    /** Declarative extension identity only; no property values or business binding data enter diagnostics. */
+    extension?: {
+        id: string;
+        version: string;
+    };
     message: string;
 }
 declare interface OutputDiagnostic_2 {
@@ -1848,6 +1979,11 @@ declare interface OutputDiagnostic_2 {
     componentPath?: readonly number[];
     kind: string;
     nid?: string;
+    /** Declarative extension identity only; no property values or business binding data enter diagnostics. */
+    extension?: {
+        id: string;
+        version: string;
+    };
     message: string;
 }
 declare interface OutputDiagnosticOptions extends OutputTaskOptions {
@@ -1909,6 +2045,8 @@ export declare interface PdfExporter {
     }): Promise<Uint8Array>;
     /** 可选轻量字体检查；旧版自定义导出函数无需实现。取消时拒绝 AbortError。 */
     checkFont?: (signal?: AbortSignal) => Promise<PdfFontCheckResult>;
+    /** Optional resource preparation for isolated encoding; custom exporters without it keep their own pipeline. */
+    prepare?: (signal?: AbortSignal) => Promise<ReportPdfFontOptions>;
 }
 export declare interface PdfFontCheckResult {
     status: PdfFontStatus;
@@ -2110,6 +2248,16 @@ declare interface PlanTableFragment_3 {
 }
 /** Bounded concurrency, one stage timeout, and cancellation even for a hanging decoder. */
 export declare function preparePrintResources(doc: Document, options?: ReportPrintOptions, signal?: AbortSignal, base?: string): Promise<void>;
+declare interface PreviewEncoding {
+    pdf(plan: RenderPlan, exporter: PdfExporter, warning: (message: string) => void, task?: PreviewEncodingTask): Promise<Uint8Array>;
+    xlsx(plan: RenderPlan, options: XlsxRenderOptions, task: PreviewEncodingTask): Promise<{
+        buffer: Uint8Array;
+        warnings: string[];
+    }>;
+}
+declare type PreviewEncodingTask = OutputTaskOptions_2 & {
+    onDiagnostic?: (entry: OutputDiagnostic) => void;
+};
 export declare function printCalibration(options?: ReportPrintOptions): {
     x: number;
     y: number;
@@ -2462,8 +2610,36 @@ export declare interface ReportEmptyState {
     title?: string;
     description?: string;
 }
+export declare interface ReportExportDecision {
+    mode: "local" | "worker";
+    reason: ReportExportDecisionReason;
+    /** Lower bounds: traversal stops as soon as isolation is warranted. No font or image hashing. */
+    estimate: {
+        pages: number;
+        cells: number;
+        bytes: number;
+    };
+    hardCancellation: boolean;
+}
+declare type ReportExportDecisionReason = "small-task" | "threshold" | "scan-limit" | "explicit-local" | "explicit-worker" | "worker-unavailable" | "worker-start-failed" | "nonserializable-options";
+export declare interface ReportExportExecutionOptions {
+    mode?: "auto" | "worker" | "local";
+    /** A fresh bundler-managed module Worker for every call; never a shared worker. */
+    workerFactory?: () => BrowserReportWorker;
+    thresholds?: ReportExportThresholds;
+    /** Auto only. Startup unavailability may use local; encoding failures never retry. */
+    fallback?: "local" | "error";
+    timeoutMs?: number;
+    budget?: ReportRuntimeBudget;
+    onDecision?: (decision: ReportExportDecision) => void;
+}
 /** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
 export declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
+export declare interface ReportExportThresholds {
+    cells?: number;
+    pages?: number;
+    bytes?: number;
+}
 declare type ReportExpression = {
     field: string;
 } | {
@@ -2514,7 +2690,13 @@ declare interface ReportFetchInput extends ReportTaskMonitoring {
     /** Index scopes diagnostics when reports share datasets or a report ID is repeated. */
     onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
-declare interface ReportFieldContract {
+declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
+declare interface ReportFieldCalculation {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
+declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
     type: "text" | "number" | "boolean" | "date" | "decimal";
@@ -2528,6 +2710,16 @@ declare interface ReportFieldContract {
     semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
     unit?: string;
 }
+declare interface ReportFieldSemantics {
+    description?: string;
+    /** Explicit meaning of null/missing; does not convert blanks into zero. */
+    missingMeaning?: string;
+    /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
+    aggregation?: ReportFieldAggregation;
+    /** Shared presentation only; raw values and calculation precision remain unchanged. */
+    format?: ColumnFormat;
+    calculation?: ReportFieldCalculation;
+}
 export declare interface ReportFieldTarget {
     field: string;
     datasetId?: string;
@@ -2707,12 +2899,23 @@ export declare const ReportParamPanel: DefineComponent<__VLS_Props_3, {
     onQuery?: (() => any) | undefined;
     "onUpdate:modelValue"?: ((value: Record<string, string>) => any) | undefined;
 }>, {
+    issues: readonly ReportParamIssue[];
     disabled: boolean;
     loadOptions: ReportParamOptionsLoader;
-    issues: readonly ReportParamIssue[];
     showActions: boolean;
     showTitle: boolean;
 }>;
+/** Licensed local font bytes; never downloaded implicitly by the runtime. */
+declare interface ReportPdfFontOptions {
+    customFontBytes?: Uint8Array | ArrayBuffer;
+    customFontName?: string;
+    customFontFaces?: {
+        regular: Uint8Array | ArrayBuffer;
+        bold?: Uint8Array | ArrayBuffer;
+        italic?: Uint8Array | ArrayBuffer;
+        boldItalic?: Uint8Array | ArrayBuffer;
+    };
+}
 export declare interface ReportPreferencesAdapter {
     load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
     save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
@@ -2811,6 +3014,15 @@ declare interface ReportQueryResult {
     diagnostics?: ReportDiagnostic[];
 }
 declare type ReportRegistry = Record<string, ReportDefinition>;
+declare interface ReportRuntimeBudget {
+    maxRows?: number;
+    maxPages?: number;
+    maxCells?: number;
+    maxOutputBytes?: number;
+    /** Bound the plain JSON snapshot accepted by exportPrepared (default 64 MB). */
+    maxPreparedBytes?: number;
+    maxDurationMs?: number;
+}
 declare interface ReportSaveInput extends ReportLoadContext {
     requestId: string;
     expectedRevision?: string;
@@ -2928,6 +3140,7 @@ declare type ReportValueState_2 = "missing-source" | "not-applicable" | "not-cal
 export declare function resolveCalculationMessages(messages: Partial<ReportCalculationMessages>): ReportCalculationMessages;
 export declare function resolveConfig(config: MachReportConfig | null | undefined, presetName?: string): ResolvedConfig;
 export declare type ResolvedConfig = Required<Pick<MachReportDefaults, "showExport" | "showPrint" | "showPdfWindow" | "showSettings" | "showParams" | "gapPx">> & {
+    exportExecution?: ReportExportExecutionOptions;
     drill?: ReportDrillOptions;
     loadParamOptions?: ReportParamOptionsLoader;
     pdfFontUrl: string;
@@ -3187,6 +3400,8 @@ export declare function usePrintExport(plan: Ref<RenderPlan | null>, hooks: {
     /** Flush the active editor and await source-backed calculation/persistence before capturing the output plan. */
     beforeOutput?: () => boolean | Promise<boolean>;
     getPdfExporter: () => PdfExporter;
+    /** Optional prepared-plan encoders; legacy callers keep their injected exporter unchanged. */
+    encoding?: PreviewEncoding;
     onError: (message: string, code?: string) => void;
     onWarning?: (message: string) => void;
     onBusy?: (format: string | null) => void;
@@ -3247,7 +3462,7 @@ declare type XlsxImageOptions = ImageMediaOptions_2;
  *   目标是"财务能直接用的对账表"而非复刻版面）
  * - 原生 richText 保留基础字形；未支持组件、段落专有排版与单元格嵌套组件计入 diagnostics / warnings
  */
-declare interface XlsxRenderOptions extends OutputDiagnosticOptions_2, XlsxImageOptions {
+declare interface XlsxRenderOptions extends AssetRenderOptions_2, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */