@agile-team/mach-report 2.8.4 → 2.9.0

package/dist/vue/async.d.ts

@@ -1,4 +1,24 @@
 import { App } from 'vue';
+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 type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+declare type AggregateOperation_2 = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
 declare interface AssetRenderBudget {
     /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
     maxAssets?: number;
@@ -140,6 +160,24 @@ 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 DatasetContract {
     fields: readonly ReportFieldContract[];
     rowKey?: string;
@@ -225,6 +263,26 @@ declare interface ExcelImportResult {
     warnings: string[];
     sheets: ExcelImportedSheet[];
 }
+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 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;
@@ -308,6 +366,9 @@ declare interface ListColumn {
     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["when"];
 }
 declare interface ListColumn_2 {
     header: string;
@@ -330,6 +391,9 @@ declare interface ListColumn_2 {
     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_2["when"];
 }
 declare interface ListComponent {
     kind: "list";
@@ -363,6 +427,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;
 }
@@ -398,20 +471,55 @@ 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;
 }
+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 type ListGrandTotal = boolean | {
     label?: string;
     style?: ComponentStyle;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
+    aggregates?: AggregateDefinition[];
 };
 declare type ListGrandTotal_2 = boolean | {
     label?: string;
     style?: ComponentStyle_3;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
+    aggregates?: AggregateDefinition_2[];
 };
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
 declare interface ListGroupBy {
@@ -426,6 +534,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 {
@@ -440,6 +551,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;
 }
 declare const machReportAsyncPlugin: {
     install(app: App, options?: MachReportPluginOptions): void;
@@ -740,6 +854,36 @@ 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 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";
@@ -800,6 +944,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 字节；第二参数可上报非致命保真告警。 */
 declare interface PdfExporter {
@@ -818,6 +970,8 @@ declare interface PdfFontCheckResult {
 /** available 仅表示字体资源可达；实际导出仍会校验文字能否编码。 */
 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;
@@ -840,6 +994,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;
@@ -862,6 +1018,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;
@@ -1205,6 +1363,30 @@ declare interface ReportEmptyState {
 }
 /** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
 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[];
+};
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
@@ -1476,6 +1658,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>;
@@ -1486,6 +1670,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>;