@agile-team/mach-report 2.14.0 → 2.16.0

package/dist/designer.d.cts

@@ -43,7 +43,7 @@ declare interface AssetRenderBudget {
     /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
     maxDurationMs?: number;
 }
-declare interface AssetRenderOptions extends OutputDiagnosticOptions {
+declare interface AssetRenderOptions extends OutputDiagnosticOptions, ImageMediaOptions {
     assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
     assetBudget?: AssetRenderBudget;
     /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
@@ -85,6 +85,14 @@ declare const BASE_TEMPLATE_EDITOR_MESSAGES: {
     note: string;
     invalid: string;
 };
+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;
+}
 declare interface CanvasSelection {
     /** Ctrl/Command/Shift toggles the selection without changing the report schema. */
     additive?: boolean;
@@ -500,11 +508,11 @@ export declare const ExcelBindingWizard: DefineComponent<ExcelBindingWizardOptio
     apply: () => Promise<void>;
     cancel: () => void;
 }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
-    dirty: (value: boolean) => any;
     apply: (result: ExcelBindingWizardApply) => any;
+    dirty: (value: boolean) => any;
 }, string, MachReportVuePublicProps, Readonly<ExcelBindingWizardOptions> & Readonly<{
-    onDirty?: ((value: boolean) => any) | undefined;
     onApply?: ((result: ExcelBindingWizardApply) => any) | undefined;
+    onDirty?: ((value: boolean) => any) | undefined;
 }>, {}>;
 export declare type ExcelBindingWizardApply = AnyExcelBindingDocumentResult & {
     session: AnyExcelBindingSession;
@@ -655,6 +663,8 @@ declare interface ExpressionOptions_3 {
     divisionByZero?: "null" | "error";
 }
 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 绘制。 */
@@ -678,6 +688,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 绘制。 */
@@ -701,6 +713,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 绘制。 */
@@ -724,6 +738,18 @@ declare interface GridCell_3 {
     style?: ComponentStyle_3;
 }
 declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+/** Bounded binary image inspection shared by PDF, Excel and template import. No decoder is loaded. */
+declare interface ImageMediaOptions {
+    maxImageBytes?: number;
+    maxTotalImageBytes?: number;
+    maxImages?: number;
+    /** Decoded pixels per unique image, default 16 million. */
+    maxImagePixels?: number;
+    /** Total decoded pixels for unique media, default 64 million. */
+    maxTotalImagePixels?: number;
+    /** Maximum source dimension, default 16384 pixels. */
+    maxImageDimension?: number;
+}
 /** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
 declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
 /** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
@@ -1080,6 +1106,10 @@ declare interface ListGroupBy_3 {
 }
 /** defaults 层可配置项（全部可选，均有内置缺省） */
 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;
     showExport?: boolean;
     showPrint?: boolean;
@@ -1122,7 +1152,11 @@ declare type MachReportLogger = Pick<Console, "warn" | "info">;
  * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
-declare interface MachReportMessages extends Partial<ReportCalculationMessages>, ReportPrintMessages {
+declare interface MachReportMessages extends Partial<ReportCalculationMessages>, ReportPrintMessages, ReportParamOptionsMessages {
+    drillActions?: string;
+    drillOpening?: string;
+    drillMissingValue?: string;
+    drillFailed?: string;
     exportMenu?: string;
     exportMenuDescription?: string;
     clearSearch?: string;
@@ -1297,7 +1331,11 @@ declare interface MachReportMessages extends Partial<ReportCalculationMessages>,
  * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
-declare interface MachReportMessages_2 extends Partial<ReportCalculationMessages_2>, ReportPrintMessages_2 {
+declare interface MachReportMessages_2 extends Partial<ReportCalculationMessages_2>, ReportPrintMessages_2, ReportParamOptionsMessages_2 {
+    drillActions?: string;
+    drillOpening?: string;
+    drillMissingValue?: string;
+    drillFailed?: string;
     exportMenu?: string;
     exportMenuDescription?: string;
     clearSearch?: string;
@@ -1544,7 +1582,7 @@ declare interface MatrixTableOptions_3 {
     maxCells?: number;
 }
 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";
+    code: "invalid-image-data" | "image-budget-exceeded" | "component-render-failed" | "unsupported-text" | "output-degraded" | "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;
@@ -1556,7 +1594,7 @@ declare interface OutputDiagnostic {
     message: string;
 }
 declare interface OutputDiagnostic_2 {
-    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";
+    code: "invalid-image-data" | "image-budget-exceeded" | "component-render-failed" | "unsupported-text" | "output-degraded" | "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_2;
     pageIndex: number;
@@ -1604,6 +1642,13 @@ export declare const PARAM_EDITOR_MESSAGES: {
     paramMinLength: string;
     paramMaxLength: string;
     paramOptions: string;
+    paramOptionsMode: string;
+    paramOptionsStatic: string;
+    paramOptionsRemote: string;
+    paramOptionsSource: string;
+    paramDependencyUnavailable: string;
+    paramDependencies: string;
+    paramRemoteHint: string;
     paramOptionValue: string;
     paramOptionLabel: string;
     paramOptionAdd: string;
@@ -1816,6 +1861,13 @@ declare interface PlanTableFragment_3 {
     };
 }
 declare const PRODUCT_TEMPLATE_EDITOR_MESSAGES: {
+    toolTarget: string;
+    toolPreview: string;
+    toolPreviewHide: string;
+    toolChooseComponent: string;
+    previousColumns: string;
+    nextColumns: string;
+    columnWindow: string;
     paperAndPages: string;
     pageDirectory: string;
     pageName: string;
@@ -2194,6 +2246,8 @@ declare type ReportCellFieldOptions = ReportCellFieldBase & ({
 declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure" | "derived";
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
 declare interface ReportCellSource {
+    /** Source identity across report occurrences; sharing must be explicitly declared. */
+    sourceScope?: string;
     datasetId: string;
     rowKey: string | number;
     field: string;
@@ -2202,6 +2256,8 @@ declare interface ReportCellSource {
 }
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
 declare interface ReportCellSource_2 {
+    /** Source identity across report occurrences; sharing must be explicitly declared. */
+    sourceScope?: string;
     datasetId: string;
     rowKey: string | number;
     field: string;
@@ -2210,6 +2266,8 @@ declare interface ReportCellSource_2 {
 }
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
 declare interface ReportCellSource_3 {
+    /** Source identity across report occurrences; sharing must be explicitly declared. */
+    sourceScope?: string;
     datasetId: string;
     rowKey: string | number;
     field: string;
@@ -2232,6 +2290,49 @@ declare interface ReportDocumentStyle {
     style: ComponentStyle_2;
     target?: "content" | "header";
 }
+/** Serializable action metadata. URLs, scripts and automatic navigation are deliberately absent. */
+declare interface ReportDrillAction {
+    id: string;
+    label: string;
+    target: {
+        field: string;
+        datasetId?: string;
+        reportScope?: string;
+        roles?: readonly string[];
+    };
+    params?: Readonly<Record<string, ReportDrillBinding>>;
+}
+declare type ReportDrillBinding = {
+    value: string | number | boolean;
+} | {
+    from: "value" | "rowKey";
+} | {
+    from: "query" | "field";
+    field: string;
+};
+/** Trusted host-owned allowlist. Matching serialized metadata alone never executes an action. */
+declare interface ReportDrillOptions {
+    actions: readonly ReportDrillAction[];
+    open(request: ReportDrillRequest & {
+        signal: AbortSignal;
+        view: Readonly<{
+            zoom: number;
+            scrollTop: number;
+            scrollLeft: number;
+        }>;
+    }): void | Promise<void>;
+}
+declare interface ReportDrillRequest {
+    actionId: string;
+    params: Readonly<Record<string, string>>;
+    returnState: Readonly<ReportDrillReturnState>;
+}
+declare interface ReportDrillReturnState {
+    params: Readonly<Record<string, string>>;
+    address: Readonly<ReportCellAddress>;
+    reportScope?: string;
+    source?: Readonly<Pick<ReportCellSource, "sourceScope" | "datasetId" | "rowKey" | "field">>;
+}
 declare interface ReportEditBatch {
     /** Idempotency identity; the server should bind it to the exact payload. */
     requestId: string;
@@ -2271,8 +2372,36 @@ declare interface ReportEditResult {
     /** Any conflict rejects the entire client batch. A server must also transact atomically. */
     conflicts?: readonly ReportEditConflict[];
 }
+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";
+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;
+}
 /** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
 declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
+declare interface ReportExportThresholds {
+    cells?: number;
+    pages?: number;
+    bytes?: number;
+}
 declare type ReportExpression = {
     field: string;
 } | {
@@ -2393,6 +2522,10 @@ declare interface ReportParamDef {
         label: string;
         value: string;
     }>;
+    /** Opaque host-resolved source key. No URL, credentials or executable code is stored. */
+    optionsSource?: string;
+    /** Select dependencies must be declared parameters; changing a parent clears descendants. */
+    dependsOn?: string[];
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
@@ -2414,6 +2547,10 @@ declare interface ReportParamDef_2 {
         label: string;
         value: string;
     }>;
+    /** Opaque host-resolved source key. No URL, credentials or executable code is stored. */
+    optionsSource?: string;
+    /** Select dependencies must be declared parameters; changing a parent clears descendants. */
+    dependsOn?: string[];
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
@@ -2435,6 +2572,10 @@ declare interface ReportParamDef_3 {
         label: string;
         value: string;
     }>;
+    /** Opaque host-resolved source key. No URL, credentials or executable code is stored. */
+    optionsSource?: string;
+    /** Select dependencies must be declared parameters; changing a parent clears descendants. */
+    dependsOn?: string[];
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
@@ -2444,6 +2585,37 @@ declare interface ReportParamDef_3 {
     minLength?: number;
     maxLength?: number;
 }
+declare interface ReportParamOption {
+    readonly label: string;
+    readonly value: string;
+}
+declare interface ReportParamOptionsInput {
+    readonly source: string;
+    readonly field: string;
+    readonly query: string;
+    /** Only declared dependencies, captured at request start. Never the mutable form. */
+    readonly params: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+    readonly limit: number;
+}
+/** Resolve a trusted source key through the host's existing API/authentication. */
+declare type ReportParamOptionsLoader = (input: ReportParamOptionsInput) => Promise<readonly ReportParamOption[]>;
+declare interface ReportParamOptionsMessages {
+    paramOptionsLoading?: string;
+    paramOptionsEmpty?: string;
+    paramOptionsFailed?: string;
+    paramOptionsMissingLoader?: string;
+    paramOptionsDependencies?: string;
+    paramOptionsClear?: string;
+}
+declare interface ReportParamOptionsMessages_2 {
+    paramOptionsLoading?: string;
+    paramOptionsEmpty?: string;
+    paramOptionsFailed?: string;
+    paramOptionsMissingLoader?: string;
+    paramOptionsDependencies?: string;
+    paramOptionsClear?: string;
+}
 declare interface ReportPreferencesAdapter {
     load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
     save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
@@ -2496,6 +2668,15 @@ declare interface ReportPrintOptions {
     /** Physical translation only; no scaling or mutation of the report data/plan. */
     calibration?: ReportPrintCalibration;
 }
+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 ReportTemplate {
     schemaVersion?: string;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
@@ -2909,6 +3090,13 @@ declare interface StyleRule_3 {
     style: Record<string, unknown>;
 }
 export declare const TEMPLATE_EDITOR_MESSAGES: {
+    toolTarget: string;
+    toolPreview: string;
+    toolPreviewHide: string;
+    toolChooseComponent: string;
+    previousColumns: string;
+    nextColumns: string;
+    columnWindow: string;
     paperAndPages: string;
     pageDirectory: string;
     pageName: string;
@@ -3599,21 +3787,14 @@ declare type ValueFormat = ColumnFormat;
 declare type ValueFormat_2 = ColumnFormat_2;
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat_3 = ColumnFormat_3;
-declare interface XlsxImageOptions {
-    /** Decoded bytes per unique embedded image; default 16 MiB. */
-    maxImageBytes?: number;
-    /** Total decoded bytes of unique images in this workbook; default 32 MiB. */
-    maxTotalImageBytes?: number;
-    /** Unique embedded media limit, default 1000; repeated placements reuse the same media. */
-    maxImages?: number;
-}
+declare type XlsxImageOptions = ImageMediaOptions;
 /**
  * RenderPlan → xlsx 导出（B 端第二出口，对齐家族 @agile-team/mach-table-xlsx 路线）：
  * - 网格组件 → 真表格：列宽（mm→Excel 宽度）、行高（mm→pt）、colSpan/rowSpan 合并、
  *   加粗/对齐/底色/字号直译（resolveGridLayout 复用单真相源几何）
  * - 文本组件 → 合并标题行（顺序流式输出，保字号/加粗/对齐；非像素级定位，
  *   目标是"财务能直接用的对账表"而非复刻版面）
- * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
+ * - 原生 richText 保留基础字形；未支持组件、段落专有排版与单元格嵌套组件计入 diagnostics / warnings
  */
 declare interface XlsxRenderOptions extends OutputDiagnosticOptions, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */