@agile-team/mach-report 2.8.3 → 2.9.0

package/dist/vue/index.d.cts

@@ -155,11 +155,11 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
     copySelection?(): string;
     pasteSelection?(text: string): Promise<boolean>;
 }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
-    warning: (message: string) => any;
     error: (message: string, detail?: {
         code: string;
         cause?: unknown;
     } | undefined) => any;
+    warning: (message: string) => any;
     task: (task: Readonly<ReportPreviewTask>) => any;
     diagnostic: (diagnostic: Readonly<ReportPreviewDiagnostic>) => any;
     loaded: (pageCount: number) => any;
@@ -276,11 +276,11 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
         default: null;
     };
 }>> & Readonly<{
-    onWarning?: ((message: string) => any) | undefined;
     onError?: ((message: string, detail?: {
         code: string;
         cause?: unknown;
     } | undefined) => any) | undefined;
+    onWarning?: ((message: string) => any) | undefined;
     onTask?: ((task: Readonly<ReportPreviewTask>) => any) | undefined;
     onDiagnostic?: ((diagnostic: Readonly<ReportPreviewDiagnostic>) => any) | undefined;
     onLoaded?: ((pageCount: number) => any) | undefined;
@@ -289,10 +289,10 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
     "onPreferences-change"?: ((preferences: Readonly<ReportPreviewPreferences>) => any) | undefined;
 }>, {
     editable: boolean | ReportEditingOptions;
+    params: Record<string, string>;
     output: ReportOutputOptions;
     height: string;
     gapPx: number;
-    params: Record<string, string>;
     reportId: string | string[] | null;
     assets: AssetRenderOptions;
     debug: boolean;
@@ -417,6 +417,36 @@ declare type __VLS_WithTemplateSlots_2<T, S> = T & {
         $slots: S;
     };
 };
+declare interface AggregateDefinition {
+    /** Output column; valueField defaults to this field. */
+    field: string;
+    op: AggregateOperation;
+    valueField?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+declare interface AggregateDefinition_2 {
+    /** Output column; valueField defaults to this field. */
+    field: string;
+    op: AggregateOperation_2;
+    valueField?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+declare interface AggregateDefinition_3 {
+    /** Output column; valueField defaults to this field. */
+    field: string;
+    op: AggregateOperation_3;
+    valueField?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+declare type AggregateOperation_2 = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+declare type AggregateOperation_3 = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
 declare interface AssetRenderBudget {
     /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
     maxAssets?: number;
@@ -586,6 +616,33 @@ declare interface ComponentStyle_3 {
     opacity?: number;
     rotateDeg?: number;
 }
+declare interface ComputedField extends ExpressionOptions {
+    field: string;
+    expression: ReportExpression | string;
+    /** Scope controls aggregate inputs; row expressions may reference the current row in any scope. */
+    scope?: "row" | "group" | "dataset";
+    groupBy?: readonly string[];
+    /** String adapter expressions cannot be inspected; declare dependencies explicitly. */
+    dependsOn?: readonly string[];
+}
+declare interface ComputedField_2 extends ExpressionOptions_2 {
+    field: string;
+    expression: ReportExpression_2 | string;
+    /** Scope controls aggregate inputs; row expressions may reference the current row in any scope. */
+    scope?: "row" | "group" | "dataset";
+    groupBy?: readonly string[];
+    /** String adapter expressions cannot be inspected; declare dependencies explicitly. */
+    dependsOn?: readonly string[];
+}
+declare interface ComputedField_3 extends ExpressionOptions_3 {
+    field: string;
+    expression: ReportExpression_3 | string;
+    /** Scope controls aggregate inputs; row expressions may reference the current row in any scope. */
+    scope?: "row" | "group" | "dataset";
+    groupBy?: readonly string[];
+    /** String adapter expressions cannot be inspected; declare dependencies explicitly. */
+    dependsOn?: readonly string[];
+}
 declare type ConfigRef = ComputedRef<MachReportConfig | null>;
 /**
  * 默认 PDF 导出器：
@@ -721,6 +778,24 @@ declare interface ExcelImportResult_2 {
     warnings: string[];
     sheets: ExcelImportedSheet_2[];
 }
+declare interface ExpressionOptions {
+    numeric?: "number" | "decimal";
+    digits?: number;
+    nulls?: "propagate" | "error";
+    divisionByZero?: "null" | "error";
+}
+declare interface ExpressionOptions_2 {
+    numeric?: "number" | "decimal";
+    digits?: number;
+    nulls?: "propagate" | "error";
+    divisionByZero?: "null" | "error";
+}
+declare interface ExpressionOptions_3 {
+    numeric?: "number" | "decimal";
+    digits?: number;
+    nulls?: "propagate" | "error";
+    divisionByZero?: "null" | "error";
+}
 export declare interface FetchRequestOptions {
     /** 网关前缀（默认空 = 同源） */
     baseUrl?: string;
@@ -731,6 +806,14 @@ export declare interface FetchRequestOptions {
     timeoutMs?: number;
 }
 declare function focusInvalid(): void;
+declare interface FormulaAdapter {
+    /** Explicit trusted engine; core never evaluates source code/macros/external workbook references. */
+    evaluate(expression: string, context: {
+        row: Readonly<Record<string, unknown>>;
+        rowIndex: number;
+        rows: readonly Record<string, unknown>[];
+    }): unknown;
+}
 declare interface GridCell {
     text?: string;
     rawText?: string;
@@ -825,6 +908,9 @@ declare interface ListColumn {
     valueType?: GridCell_2["valueType"];
     /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
     semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    hidden?: boolean;
+    /** Condition hides cell content, preserving its physical layout in preview and exports. */
+    visibleWhen?: StyleRule["when"];
 }
 declare interface ListColumn_2 {
     header: string;
@@ -847,6 +933,9 @@ declare interface ListColumn_2 {
     valueType?: GridCell["valueType"];
     /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
     semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    hidden?: boolean;
+    /** Condition hides cell content, preserving its physical layout in preview and exports. */
+    visibleWhen?: StyleRule_2["when"];
 }
 declare interface ListColumn_3 {
     header: string;
@@ -869,6 +958,9 @@ declare interface ListColumn_3 {
     valueType?: GridCell_3["valueType"];
     /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
     semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    hidden?: boolean;
+    /** Condition hides cell content, preserving its physical layout in preview and exports. */
+    visibleWhen?: StyleRule_3["when"];
 }
 declare interface ListComponent {
     kind: "list";
@@ -902,6 +994,15 @@ declare interface ListComponent {
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
+    /** Ordered outer-to-inner grouping; groupBy remains the single-level shorthand. */
+    groups?: ListGroupBy[];
+    computed?: ComputedField[];
+    /** Dynamic pivot of the current source dataset, with read-only derived identities. */
+    matrix?: MatrixTableOptions;
+    /** Explicit row visibility; hidden rows do not participate in summaries. */
+    rowVisibleWhen?: StyleRule["when"];
+    /** Master/detail relation is keyed by business identity, never by display row index. */
+    detail?: ListDetail;
     /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
     grandTotal?: ListGrandTotal;
 }
@@ -937,6 +1038,15 @@ declare interface ListComponent_2 {
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy_2;
+    /** Ordered outer-to-inner grouping; groupBy remains the single-level shorthand. */
+    groups?: ListGroupBy_2[];
+    computed?: ComputedField_2[];
+    /** Dynamic pivot of the current source dataset, with read-only derived identities. */
+    matrix?: MatrixTableOptions_2;
+    /** Explicit row visibility; hidden rows do not participate in summaries. */
+    rowVisibleWhen?: StyleRule_2["when"];
+    /** Master/detail relation is keyed by business identity, never by display row index. */
+    detail?: ListDetail_2;
     /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
     grandTotal?: ListGrandTotal_2;
 }
@@ -972,26 +1082,74 @@ declare interface ListComponent_3 {
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy_3;
+    /** Ordered outer-to-inner grouping; groupBy remains the single-level shorthand. */
+    groups?: ListGroupBy_3[];
+    computed?: ComputedField_3[];
+    /** Dynamic pivot of the current source dataset, with read-only derived identities. */
+    matrix?: MatrixTableOptions_3;
+    /** Explicit row visibility; hidden rows do not participate in summaries. */
+    rowVisibleWhen?: StyleRule_3["when"];
+    /** Master/detail relation is keyed by business identity, never by display row index. */
+    detail?: ListDetail_3;
     /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
     grandTotal?: ListGrandTotal_3;
 }
+declare interface ListDetail {
+    dataset: string;
+    parentKey: string;
+    foreignKey: string;
+    rowKey?: string;
+    columns: ListColumn[];
+    rowHeightMm?: number;
+    header?: boolean;
+    label?: string;
+    /** Unmatched children fail by default; opt-in ignore is explicit. */
+    unmatched?: "error" | "ignore";
+}
+declare interface ListDetail_2 {
+    dataset: string;
+    parentKey: string;
+    foreignKey: string;
+    rowKey?: string;
+    columns: ListColumn_2[];
+    rowHeightMm?: number;
+    header?: boolean;
+    label?: string;
+    /** Unmatched children fail by default; opt-in ignore is explicit. */
+    unmatched?: "error" | "ignore";
+}
+declare interface ListDetail_3 {
+    dataset: string;
+    parentKey: string;
+    foreignKey: string;
+    rowKey?: string;
+    columns: ListColumn_3[];
+    rowHeightMm?: number;
+    header?: boolean;
+    label?: string;
+    /** Unmatched children fail by default; opt-in ignore is explicit. */
+    unmatched?: "error" | "ignore";
+}
 declare type ListGrandTotal = boolean | {
     label?: string;
     style?: ComponentStyle_2;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
+    aggregates?: AggregateDefinition[];
 };
 declare type ListGrandTotal_2 = boolean | {
     label?: string;
     style?: ComponentStyle;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
+    aggregates?: AggregateDefinition_2[];
 };
 declare type ListGrandTotal_3 = boolean | {
     label?: string;
     style?: ComponentStyle_3;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
+    aggregates?: AggregateDefinition_3[];
 };
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
 declare interface ListGroupBy {
@@ -1006,6 +1164,9 @@ declare interface ListGroupBy {
     subtotalLabel?: string;
     /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
     keepWithNext?: boolean;
+    aggregates?: AggregateDefinition[];
+    /** Repeat this group heading after page breaks within the group. */
+    repeatHeader?: boolean;
 }
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
 declare interface ListGroupBy_2 {
@@ -1020,6 +1181,9 @@ declare interface ListGroupBy_2 {
     subtotalLabel?: string;
     /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
     keepWithNext?: boolean;
+    aggregates?: AggregateDefinition_2[];
+    /** Repeat this group heading after page breaks within the group. */
+    repeatHeader?: boolean;
 }
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
 declare interface ListGroupBy_3 {
@@ -1034,6 +1198,9 @@ declare interface ListGroupBy_3 {
     subtotalLabel?: string;
     /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
     keepWithNext?: boolean;
+    aggregates?: AggregateDefinition_3[];
+    /** Repeat this group heading after page breaks within the group. */
+    repeatHeader?: boolean;
 }
 export declare interface LocalTemplateEntry {
     template: ReportTemplate_2;
@@ -1429,6 +1596,51 @@ export declare interface MachReportToolbarOptions {
     /** 未传时显示全部已有出口；空数组表示不提供导出工具。 */
     exportFormats?: ReportExportFormat[];
 }
+declare interface MatrixTableOptions {
+    rowFields: readonly string[];
+    columnFields: readonly string[];
+    measures: readonly (AggregateDefinition & {
+        label?: string;
+    })[];
+    totals?: boolean;
+    rowHeader?: string;
+    columnWidthMm?: number;
+    rowWidthMm?: number;
+    maxRows?: number;
+    maxColumns?: number;
+    maxInputRows?: number;
+    maxCells?: number;
+}
+declare interface MatrixTableOptions_2 {
+    rowFields: readonly string[];
+    columnFields: readonly string[];
+    measures: readonly (AggregateDefinition_2 & {
+        label?: string;
+    })[];
+    totals?: boolean;
+    rowHeader?: string;
+    columnWidthMm?: number;
+    rowWidthMm?: number;
+    maxRows?: number;
+    maxColumns?: number;
+    maxInputRows?: number;
+    maxCells?: number;
+}
+declare interface MatrixTableOptions_3 {
+    rowFields: readonly string[];
+    columnFields: readonly string[];
+    measures: readonly (AggregateDefinition_3 & {
+        label?: string;
+    })[];
+    totals?: boolean;
+    rowHeader?: string;
+    columnWidthMm?: number;
+    rowWidthMm?: number;
+    maxRows?: number;
+    maxColumns?: number;
+    maxInputRows?: number;
+    maxCells?: number;
+}
 export declare function normalizeReportIds(reportId: ReportIdInput): string[];
 /** Workers preserve stable error codes, not JavaScript class identity. Only known codes cross the UI boundary. */
 export declare function normalizeReportLoadError(error: unknown): MachReportError;
@@ -1498,6 +1710,14 @@ declare interface PaginateOptions {
     measurer?: TextMeasurer;
     /** 可选页数上限；在追加超限页前终止，避免先分配全部页面再检查。 */
     maxPages?: number;
+    /** Actual grid cells, including repeated furniture and nested children; checked before each page is appended. */
+    maxCells?: number;
+    signal?: AbortSignal;
+    /** Streaming total-page anchors can skip the bounded counting pass when known. */
+    knownTotalPages?: number;
+    onWarning?: (warning: string) => void;
+    /** Trusted formula adapter is passed at execution time; it is never serialized in templates. */
+    formula?: FormulaAdapter;
 }
 /** PDF 导出器：RenderPlan → PDF 字节；第二参数可上报非致命保真告警。 */
 export declare interface PdfExporter {
@@ -1516,6 +1736,8 @@ export declare interface PdfFontCheckResult {
 /** available 仅表示字体资源可达；实际导出仍会校验文字能否编码。 */
 export declare type PdfFontStatus = "unchecked" | "checking" | "available" | "disabled" | "unverified" | "error";
 declare interface PlanComponent {
+    /** Template page furniture repeats per page and reserves its vertical band. */
+    pageAnchor?: "header" | "footer";
     kind: ComponentKind;
     leftMm: number;
     topMm: number;
@@ -1538,6 +1760,8 @@ declare interface PlanComponent {
     fallbackText?: string;
 }
 declare interface PlanComponent_2 {
+    /** Template page furniture repeats per page and reserves its vertical band. */
+    pageAnchor?: "header" | "footer";
     kind: ComponentKind_2;
     leftMm: number;
     topMm: number;
@@ -1560,6 +1784,8 @@ declare interface PlanComponent_2 {
     fallbackText?: string;
 }
 declare interface PlanComponent_3 {
+    /** Template page furniture repeats per page and reserves its vertical band. */
+    pageAnchor?: "header" | "footer";
     kind: ComponentKind_3;
     leftMm: number;
     topMm: number;
@@ -1942,6 +2168,42 @@ export declare interface ReportEmptyState {
 }
 /** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
 export declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
+declare type ReportExpression = {
+    field: string;
+} | {
+    value: string | number | boolean | null;
+} | {
+    aggregate: AggregateOperation;
+    field?: string;
+    weightField?: string;
+} | {
+    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    args: readonly ReportExpression[];
+};
+declare type ReportExpression_2 = {
+    field: string;
+} | {
+    value: string | number | boolean | null;
+} | {
+    aggregate: AggregateOperation_2;
+    field?: string;
+    weightField?: string;
+} | {
+    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    args: readonly ReportExpression_2[];
+};
+declare type ReportExpression_3 = {
+    field: string;
+} | {
+    value: string | number | boolean | null;
+} | {
+    aggregate: AggregateOperation_3;
+    field?: string;
+    weightField?: string;
+} | {
+    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    args: readonly ReportExpression_3[];
+};
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
@@ -2284,6 +2546,8 @@ declare interface StyleRule {
         field: string;
         op: ">" | ">=" | "<" | "<=" | "==" | "!=";
         value: number | string;
+        /** Explicit decimal comparisons retain decimal thresholds as text. */
+        numeric?: "number" | "decimal";
     };
     /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
     style: Record<string, unknown>;
@@ -2294,6 +2558,8 @@ declare interface StyleRule_2 {
         field: string;
         op: ">" | ">=" | "<" | "<=" | "==" | "!=";
         value: number | string;
+        /** Explicit decimal comparisons retain decimal thresholds as text. */
+        numeric?: "number" | "decimal";
     };
     /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
     style: Record<string, unknown>;
@@ -2304,6 +2570,8 @@ declare interface StyleRule_3 {
         field: string;
         op: ">" | ">=" | "<" | "<=" | "==" | "!=";
         value: number | string;
+        /** Explicit decimal comparisons retain decimal thresholds as text. */
+        numeric?: "number" | "decimal";
     };
     /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
     style: Record<string, unknown>;