@agile-team/mach-report 2.8.3 → 2.9.0

package/dist/index.d.cts

@@ -1,3 +1,15 @@
+declare interface AggregateDefinition {
+    /** Output column; valueField defaults to this field. */
+    field: string;
+    op: AggregateOperation;
+    valueField?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+
+declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
+
 /** 复制发生变化的页/组件/行；原计划保持不变，并拒绝覆盖已改变的单元格。 */
 export declare function applyReportCellEdit(plan: RenderPlan, edit: ReportCellEdit): RenderPlan;
 
@@ -158,9 +170,22 @@ export declare interface ComponentStyle {
     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[];
+}
+
 /** 页级视口虚拟化；单次计算入口保留兼容，预览内部复用已建立的几何索引。 */
 export declare function computePageWindow(input: PageWindowInput): PageWindow;
 
+/** Counting pass does not keep page grids, components or a RenderPlan alive. */
+export declare function countTemplatePages(template: ReportTemplate, datasets: DatasetRows, options?: PaginateOptions): number;
+
 /**
  * 浏览器 Canvas 测量器：用真实字体 metrics 校准宽度（可选注入）。
  * 无 2D 环境时自动回退启发式（Node/SSR 安全）。
@@ -204,6 +229,7 @@ export declare function createReportSource(reports: ReportRegistry, options?: {
     onWarning?: (message: string) => void;
     onDatasets?: (reportId: string, datasets: DatasetRows, template: ReportTemplate) => void;
     maxPages?: number;
+    maxCells?: number;
 }): ReportSource;
 
 /**
@@ -218,6 +244,12 @@ export declare function createTemplate(): TemplateBuilder;
 export declare function createTemplateManager(store: ReportTemplateStore, options?: {
     migrate?: (input: unknown) => unknown | Promise<unknown>;
     now?: () => Date;
+    /** Optional publication gate; receives explicit draft snapshots and never replaces CAS. */
+    beforePublish?: (context: {
+        document: ReportTemplateDocument;
+        previous?: ReportTemplateDocument;
+        signal?: AbortSignal;
+    }) => ReportTemplateReview | Promise<ReportTemplateReview>;
 }): ReportTemplateManager;
 
 /** 存储无关的模板目录；后台 CRUD、权限、发布审批与持久化由宿主接入。 */
@@ -275,6 +307,14 @@ export declare function defineReportTemplate(document: Omit<ReportTemplateDocume
     schemaVersion?: typeof REPORT_TEMPLATE_DOCUMENT_VERSION;
 }): ReportTemplateDocument;
 
+/** Semantic column identities keep a reorder distinct from deleting or rebinding a field. */
+export declare function diffReportTemplates(previous: ReportTemplateDocument, next: ReportTemplateDocument, options?: {
+    maxChanges?: number;
+}): ReportTemplateDiff;
+
+/** Conservative cell allocation estimate; relation validation rejects duplicate master keys before rendering. */
+export declare function estimateListLayoutCells(list: ListComponent, datasets: DatasetRows, options?: Pick<PaginateOptions, "formula" | "signal">): number;
+
 /**
  * 规则求值语义：
  * - 空值（null/undefined/""）永不命中（避免 Number("")===0 把空当 0 的隐式陷阱）
@@ -285,6 +325,13 @@ export declare function evalStyleRule(row: Record<string, unknown>, when: StyleR
 /** A tiny arithmetic parser: no functions, property access, globals, assignments or executable source. */
 export declare function evaluateReportAggregateExpression(expression: string, values: Readonly<Record<string, number>>): number;
 
+declare interface ExpressionOptions {
+    numeric?: "number" | "decimal";
+    digits?: number;
+    nulls?: "propagate" | "error";
+    divisionByZero?: "null" | "error";
+}
+
 /** 同步 text/raw value，所有输出后端读取同一份更新后的 RenderPlan。 */
 export declare function formatReportCellEdit(context: ReportCellContext, value: ReportCellValue): string;
 
@@ -299,6 +346,15 @@ export declare function formatReportClipboard(rows: readonly (readonly string[])
  */
 export declare function formatValue(value: unknown, format?: ColumnFormat): string;
 
+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 type Geometry = Partial<Pick<PlanComponent, "leftMm" | "topMm" | "widthMm" | "heightMm">>;
 
 export declare function getReportCellContext(plan: RenderPlan, address: ReportCellAddress): ReportCellContext | null;
@@ -408,6 +464,9 @@ export 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"];
 }
 
 export declare interface ListComponent {
@@ -442,15 +501,38 @@ export 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;
 }
 
+export 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";
+}
+
 export declare type ListGrandTotal = boolean | {
     label?: string;
     style?: ComponentStyle;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
+    aggregates?: AggregateDefinition[];
 };
 
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
@@ -466,6 +548,25 @@ export declare interface ListGroupBy {
     subtotalLabel?: string;
     /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
     keepWithNext?: boolean;
+    aggregates?: AggregateDefinition[];
+    /** Repeat this group heading after page breaks within the group. */
+    repeatHeader?: boolean;
+}
+
+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;
 }
 
 export declare function measurePageSizePx(page: Pick<PlanPage, "pageWidthMm" | "pageHeightMm">, dpi?: number): {
@@ -564,6 +665,13 @@ export declare interface PageWindowInput {
     gapPx?: number;
 }
 
+export declare class PaginateCellLimitError extends Error {
+    readonly limit: number;
+    readonly actual: number;
+    readonly code = "cell-limit";
+    constructor(limit: number, actual: number);
+}
+
 export declare interface PaginateOptions {
     /** 每行额外占高（mm），压测专用钩子 */
     mmPerRow?: number;
@@ -571,6 +679,14 @@ export 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;
 }
 
 export declare class PaginatePageLimitError extends Error {
@@ -585,9 +701,12 @@ export declare interface PaginateResult {
     warnings: string[];
 }
 
-/** 模板遍历只编排静态组件和列表；行测量、分组、换页与汇总各自独立。 */
+/** Compatibility collector: the pagination engine is shared with the bounded page iterator. */
 export declare function paginateTemplate(template: ReportTemplate, datasets: DatasetRows, optionsOrMmPerRow?: number | PaginateOptions): PaginateResult;
 
+/** Genuine page-level layout. With total-page anchors, use knownTotalPages or a bounded counting pass. */
+export declare function paginateTemplatePages(template: ReportTemplate, datasets: DatasetRows, options?: PaginateOptions): Generator<PlanPage>;
+
 export declare const PAPER_SIZES: Record<string, {
     widthMm: number;
     heightMm: number;
@@ -612,6 +731,8 @@ export declare function parseReportClipboard(text: string, maxCells?: number): s
 export declare function parseReportTemplate(input: unknown): ReportTemplateDocument;
 
 export declare interface PlanComponent {
+    /** Template page furniture repeats per page and reserves its vertical band. */
+    pageAnchor?: "header" | "footer";
     kind: ComponentKind;
     leftMm: number;
     topMm: number;
@@ -679,6 +800,9 @@ export declare interface PlanTableFragment {
     };
 }
 
+/** Hides physical columns and projects merged headers using the same geometry in every output. */
+export declare function projectListColumns(list: ListComponent): ListComponent;
+
 export declare function ptToPx(pt: number, dpi?: number): number;
 
 export declare function pxToMm(value: number, dpi?: number): number;
@@ -899,6 +1023,19 @@ export declare interface ReportEditResult {
     conflicts?: readonly ReportEditConflict[];
 }
 
+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[];
+};
+
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 export declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
@@ -1092,6 +1229,22 @@ export declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+export declare interface ReportTemplateChange {
+    kind: "added" | "removed" | "modified" | "moved";
+    category: "metadata" | "structure" | "binding" | "calculation" | "format";
+    path: string;
+    before?: string;
+    after?: string;
+    breaking: boolean;
+}
+
+export declare interface ReportTemplateDiff {
+    changes: ReportTemplateChange[];
+    totalChanges: number;
+    truncated: boolean;
+    breakingChanges: number;
+}
+
 /** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
 export declare interface ReportTemplateDocument {
     schemaVersion: "1.0";
@@ -1108,6 +1261,12 @@ export declare class ReportTemplateError extends Error {
     constructor(errors: readonly ValidationError[]);
 }
 
+export declare interface ReportTemplateFixture {
+    name: string;
+    datasets: DatasetRows;
+    params?: Record<string, string>;
+}
+
 export declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
 
 export declare interface ReportTemplateManager {
@@ -1150,6 +1309,41 @@ export declare interface ReportTemplateRegistry {
     remove(id: string): boolean;
 }
 
+export declare interface ReportTemplateReview {
+    ok: boolean;
+    changes?: ReportTemplateDiff;
+    issues: ReportTemplateReviewIssue[];
+    samples: Array<{
+        name: string;
+        pages: number;
+        rows: number;
+        diagnostics: OutputDiagnostic[];
+    }>;
+}
+
+export declare interface ReportTemplateReviewIssue {
+    code: "template" | "compatibility" | "dataset" | "field" | "sample" | "layout" | "output";
+    severity: "error" | "warning";
+    path: string;
+    message: string;
+    fixture?: string;
+    pageIndex?: number;
+    componentIndex?: number;
+    field?: string;
+}
+
+export declare interface ReportTemplateReviewOptions {
+    previous?: ReportTemplateDocument;
+    dataSchemas?: Readonly<Record<string, DatasetContract>>;
+    fixtures?: readonly ReportTemplateFixture[];
+    formats?: readonly OutputFormat[];
+    maxPages?: number;
+    maxCells?: number;
+    maxSampleRows?: number;
+    allowBreakingChanges?: boolean;
+    strictOutputs?: boolean;
+}
+
 /** compareAndSwap 必须由宿主数据库/文件适配器保证原子性，不能用先读再无条件写替代。 */
 export declare interface ReportTemplateStore {
     read(id: string, signal?: AbortSignal): Promise<ReportTemplateRecord | undefined>;
@@ -1165,8 +1359,8 @@ export declare interface ReportTemplateStore {
 }
 
 export declare class ReportTemplateStoreError extends Error {
-    readonly code: "conflict" | "missing" | "draft" | "history";
-    constructor(code: "conflict" | "missing" | "draft" | "history", message: string);
+    readonly code: "conflict" | "missing" | "draft" | "history" | "review";
+    constructor(code: "conflict" | "missing" | "draft" | "history" | "review", message: string);
 }
 
 export declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
@@ -1240,6 +1434,9 @@ export declare function resolveStroke(style: Pick<ComponentStyle, "borderColor"
 /** 文本颜色解析 */
 export declare function resolveTextColor(style: Pick<ComponentStyle, "color"> | undefined, fallback?: string): string;
 
+/** Pure preflight uses explicit samples only; it never fetches business data or publishes a draft. */
+export declare function reviewReportTemplate(input: unknown, options?: ReportTemplateReviewOptions): ReportTemplateReview;
+
 export declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -1270,6 +1467,8 @@ export 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>;