@agile-team/mach-report 2.6.1 → 2.8.0

package/dist/index.d.ts

@@ -45,6 +45,9 @@ export declare interface BoxBorders {
     inner: boolean;
 }
 
+/** Read-only local analysis. Never changes the plan, formulas, datasets or business persistence. */
+export declare function calculateReportSelection(plan: RenderPlan, selection: ReportCalculationSelection, options?: ReportSelectionCalculationOptions): Promise<ReportSelectionCalculationResult>;
+
 export declare type CanvasImageLoader = (source: string, signal?: AbortSignal) => Promise<CanvasImageSource>;
 
 export declare interface CanvasPager {
@@ -279,6 +282,9 @@ export declare function defineReportTemplate(document: Omit<ReportTemplateDocume
  */
 export declare function evalStyleRule(row: Record<string, unknown>, when: StyleRule["when"]): boolean;
 
+/** 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;
+
 /** 同步 text/raw value，所有输出后端读取同一份更新后的 RenderPlan。 */
 export declare function formatReportCellEdit(context: ReportCellContext, value: ReportCellValue): string;
 
@@ -485,7 +491,7 @@ export declare class OutputAssetError extends Error {
 }
 
 export declare interface OutputDiagnostic {
-    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
+    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";
     format: OutputFormat;
     pageIndex: number;
@@ -497,13 +503,27 @@ export declare interface OutputDiagnostic {
     message: string;
 }
 
-export declare interface OutputDiagnosticOptions {
+export declare interface OutputDiagnosticOptions extends OutputTaskOptions {
     /** Structured fidelity diagnostics; rendering never silently invents missing content. */
     onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
+    /** Reject known unsupported content before creating an incomplete file. Default warn. */
+    fidelity?: "warn" | "strict";
+}
+
+export declare class OutputFidelityError extends Error {
+    readonly diagnostics: readonly OutputDiagnostic[];
+    readonly code = "output-fidelity";
+    constructor(diagnostics: readonly OutputDiagnostic[]);
 }
 
 export declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
 
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+export declare interface OutputTaskOptions {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+
 export declare class PageBuilder {
     private readonly parent;
     private readonly page;
@@ -579,6 +599,9 @@ export declare type PaperName = keyof typeof PAPER_SIZES;
 /** 日历日字符串 → 本地 Date（不含时间的纯日期，杜绝 UTC 偏移） */
 export declare function parseDateLocal(input: string): Date | null;
 
+/** Core type parsing is authoritative; field controls add restrictions, never coerce IDs or bypass readonly. */
+export declare function parseReportCellFieldInput(context: ReportCellContext, input: ReportCellValue, field?: ReportCellFieldOptions): ReportCellValue;
+
 /** 严格解析编辑输入；文本列不隐式推断数值，清空数值/布尔列得到 null。 */
 export declare function parseReportCellInput(context: ReportCellContext, input: ReportCellValue): ReportCellValue;
 
@@ -700,6 +723,20 @@ export declare function renderPlanToImages(plan: RenderPlan, options?: ImageRend
 /** 模板存储文档版本；与渲染计划版本独立演进。 */
 export declare const REPORT_TEMPLATE_DOCUMENT_VERSION = "1.0";
 
+export declare class ReportCalculationError extends Error {
+    readonly code: ReportCalculationErrorCode;
+    constructor(code: ReportCalculationErrorCode);
+}
+
+export declare type ReportCalculationErrorCode = "selection" | "limit" | "expression" | "division" | "overflow" | "precision";
+
+export declare type ReportCalculationOperation = "sum" | "average" | "min" | "max" | "count" | "median" | "expression";
+
+export declare interface ReportCalculationSelection {
+    anchor: ReportCellAddress;
+    focus: ReportCellAddress;
+}
+
 /** 预览中的物理坐标；合并单元格使用左上角坐标。 */
 export declare interface ReportCellAddress {
     pageIndex: number;
@@ -708,6 +745,11 @@ export declare interface ReportCellAddress {
     columnIndex: number;
 }
 
+export declare interface ReportCellChoice {
+    value: Exclude<ReportCellValue, null>;
+    label?: string;
+}
+
 export declare interface ReportCellContext {
     address: ReportCellAddress;
     cell: Readonly<GridCell>;
@@ -740,6 +782,45 @@ export declare type ReportCellEditErrorCode = "missing" | "readonly" | "number"
 
 export declare function reportCellEditKey(edit: Pick<ReportCellEdit, "address" | "source" | "table">): string;
 
+declare interface ReportCellFieldBase {
+    /** Presentation only; it never grants write permission. */
+    label?: string;
+    hint?: string;
+    unit?: string;
+    required?: boolean;
+}
+
+/** Shared structured validation for browser editors, pasted values and backend adapters. */
+export declare class ReportCellFieldError extends Error {
+    readonly code: ReportCellFieldErrorCode;
+    readonly field: ReportCellFieldOptions;
+    readonly expected?: string | number | undefined;
+    constructor(code: ReportCellFieldErrorCode, field: ReportCellFieldOptions, expected?: string | number | undefined);
+}
+
+export declare type ReportCellFieldErrorCode = "definition" | "type" | "required" | "min" | "max" | "precision" | "length" | "choice" | "date";
+
+export declare type ReportCellFieldOptions = ReportCellFieldBase & ({
+    type: "text";
+    maxLength?: number;
+} | {
+    type: "number";
+    min?: number;
+    max?: number;
+    precision?: number;
+} | {
+    type: "boolean";
+    trueLabel?: string;
+    falseLabel?: string;
+} | {
+    type: "enum";
+    options: readonly ReportCellChoice[];
+} | {
+    type: "date";
+    min?: string;
+    max?: string;
+});
+
 export declare interface ReportCellInput {
     address: ReportCellAddress;
     value: ReportCellValue;
@@ -824,7 +905,7 @@ export declare interface ReportFetcher {
     getParamDefs?: (reportIds: string[]) => ReportParamDef[];
 }
 
-export declare interface ReportFetchInput {
+export declare interface ReportFetchInput extends ReportTaskMonitoring {
     reportIds: string[];
     params: Record<string, string>;
     signal?: AbortSignal;
@@ -953,6 +1034,28 @@ export declare interface ReportSaveResult {
     diagnostics?: ReportDiagnostic[];
 }
 
+export declare interface ReportSelectionCalculationOptions {
+    operation?: ReportCalculationOperation;
+    /** Only aggregate names, finite numeric constants, + - * / and parentheses. No cell/Excel formulas. */
+    expression?: string;
+    precision?: number;
+    maxCells?: number;
+    maxScannedCells?: number;
+    signal?: AbortSignal;
+    /** Cooperative scheduler; default yields to the browser/Node event loop. */
+    yieldToHost?: () => Promise<void>;
+}
+
+export declare interface ReportSelectionCalculationResult {
+    value: number | null;
+    formatted: string;
+    numericCells: number;
+    excludedCells: number;
+    selectedCells: number;
+    /** IEEE-754 arithmetic; presentation rounding does not change source values. */
+    precision: number;
+}
+
 export declare interface ReportSource extends ReportFetcher {
     getParamDefs(reportIds: string[]): ReportParamDef[];
 }
@@ -963,6 +1066,25 @@ export declare class ReportSourceError extends Error {
     constructor(code: ReportSourceError["code"], message: string, cause?: unknown);
 }
 
+/** 阶段事件只包含可序列化值；不表示估算百分比，也不包含业务数据。 */
+export declare interface ReportTaskEvent {
+    taskId: string;
+    correlationId?: string;
+    stage: "query" | "validate" | "layout" | "encode";
+    status: "started" | "completed" | "failed";
+    reportId?: string;
+    completed?: number;
+    total?: number;
+}
+
+export declare interface ReportTaskMonitoring {
+    taskId?: string;
+    correlationId?: string;
+    onEvent?: ReportTaskObserver;
+}
+
+export declare type ReportTaskObserver = (event: ReportTaskEvent) => void;
+
 export declare interface ReportTemplate {
     schemaVersion?: string;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
@@ -1282,6 +1404,9 @@ export declare function validatePage(page: unknown, path: string, errors: Valida
 
 export declare function validateRenderPlan(input: unknown): ValidationResult;
 
+/** Check configuration before opening an input, including JSON/JavaScript callers. */
+export declare function validateReportCellFieldDefinition(context: ReportCellContext, field: ReportCellFieldOptions): void;
+
 /** 模板参数配置错误也统一返回结构化问题，不让无效默认值或边界静默进入后端。 */
 export declare function validateReportParamDefinitions(defs: readonly ReportParamDef[]): ReportParamIssue[];