@agile-team/mach-report 2.8.4 → 2.9.0

package/dist/xlsx.d.ts

@@ -23,6 +23,18 @@ declare interface AddWorksheetOptions {
     	state: WorksheetState;
 }
 
+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";
+
 declare interface Alignment {
     	horizontal: 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
     	vertical: 'top' | 'middle' | 'bottom' | 'distributed' | 'justify';
@@ -412,6 +424,16 @@ 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[];
+}
+
 declare interface ConditionalFormattingBaseRule {
     	priority: number;
     	style?: Partial<Style>;
@@ -437,6 +459,18 @@ declare interface ContainsTextRuleType extends ConditionalFormattingBaseRule {
     	text?: string;
 }
 
+/** Compile only the selected sheet to a new template; all sample detail values are removed. */
+export declare function createExcelBindingDocument(imported: ExcelImportResult, recipe: ExcelBindingRecipe, datasets: readonly ExcelBindingDataset[], identity: {
+    id: string;
+    name: string;
+}): ExcelBindingDocumentResult;
+
+/** Persist this JSON beside the template to reopen exact regions/mappings without retaining File or runtime handles. */
+export declare function createExcelBindingSession(imported: ExcelImportResult, recipe: ExcelBindingRecipe, identity: {
+    id: string;
+    name: string;
+}): ExcelBindingSession;
+
 declare interface Csv {
     	/**
      	 * read from a file
@@ -570,6 +604,72 @@ export declare type ExcelBindingColumn = string | (Omit<ListColumn, "widthMm" |
     header?: string;
 });
 
+export declare interface ExcelBindingDataset {
+    id: string;
+    label?: string;
+    fields: readonly ExcelBindingField[];
+    rowKey?: string;
+    /** Optional representative API rows, used only for contract validation, never as live results. */
+    samples?: readonly Record<string, unknown>[];
+}
+
+export declare interface ExcelBindingDocumentResult {
+    document: ReportTemplateDocument;
+    recipe: ExcelBindingRecipe;
+    warnings: string[];
+}
+
+export declare interface ExcelBindingField extends ReportFieldContract {
+    /** Display precision is explicit business metadata; decimal text is never coerced to number. */
+    digits?: number;
+    sample?: string | number | boolean | null;
+}
+
+export declare interface ExcelBindingIssue {
+    path: string;
+    code: "schema" | "region" | "mapping" | "row-key" | "source";
+    message: string;
+}
+
+/** Explicit coordinates and mappings, independently persistable alongside the source asset. */
+export declare interface ExcelBindingRecipe {
+    version: "1.0";
+    sheet: string;
+    dataset: string;
+    regions: {
+        title?: string;
+        header: string;
+        detail: string;
+        footer?: string;
+    };
+    /** One mapping for every physical Excel column. Empty strings remain invalid until confirmed. */
+    fields: string[];
+    rowKey: string;
+}
+
+export declare type ExcelBindingRegion = "title" | "header" | "detail" | "footer";
+
+/** Row selection is graphical; this helper converts it to explicit full-width coordinates. */
+export declare function excelBindingRowRange(imported: ExcelImportResult, sheetName: string, from: number, to: number): string;
+
+export declare interface ExcelBindingSession {
+    version: "1.0";
+    /** Design source only. The compiled document never retains the sample detail rows. */
+    source: ExcelImportResult;
+    recipe: ExcelBindingRecipe;
+    identity: {
+        id: string;
+        name: string;
+    };
+}
+
+export declare interface ExcelBindingValidation {
+    ok: boolean;
+    issues: ExcelBindingIssue[];
+    mapped: number;
+    total: number;
+}
+
 export declare interface ExcelImportedSheet {
     name: string;
     /** Original, one-based workbook position. */
@@ -745,6 +845,46 @@ declare namespace ExcelJS {
     }
 }
 
+export declare interface ExcelSheetWindow {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+    source: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    columns: {
+        column: number;
+        name: string;
+    }[];
+    rows: {
+        row: number;
+        cells: ExcelSheetWindowCell[];
+    }[];
+}
+
+export declare interface ExcelSheetWindowCell {
+    address: string;
+    text: string;
+    row: number;
+    column: number;
+    rowSpan: number;
+    colSpan: number;
+    /** A merged master may be outside the current window; its visible fragment retains the label. */
+    continued: boolean;
+    style?: GridCell["style"];
+}
+
+export declare interface ExcelSheetWindowOptions {
+    row?: number;
+    column?: number;
+    rows?: number;
+    columns?: number;
+}
+
 export declare interface ExcelTableBinding {
     sheet: string;
     dataset?: string;
@@ -753,6 +893,8 @@ export declare interface ExcelTableBinding {
     /** 将整个样例明细区域替换为动态数据；缺省为表头下方全部行。 */
     detail?: string;
     columns: readonly ExcelBindingColumn[];
+    /** Disable sample-cell number-format inference when a business schema is authoritative. */
+    inferSampleFormats?: boolean;
     rowKey?: string;
     revisionField?: string;
     sourceTokenField?: string;
@@ -765,6 +907,27 @@ export declare interface ExcelTemplateBindingResult {
     warnings: string[];
 }
 
+export declare interface ExcelWorkbookInspection {
+    sheets: ExcelWorkbookSheet[];
+    warnings: string[];
+}
+
+export declare interface ExcelWorkbookSheet {
+    name: string;
+    index: number;
+    range: string;
+    rowCount: number;
+    columnCount: number;
+    visible: boolean;
+}
+
+declare interface ExpressionOptions {
+    numeric?: "number" | "decimal";
+    digits?: number;
+    nulls?: "propagate" | "error";
+    divisionByZero?: "null" | "error";
+}
+
 declare interface ExpressionRuleType extends ConditionalFormattingBaseRule {
     	type: 'expression';
     	formulae?: any[];
@@ -877,6 +1040,9 @@ declare enum FormulaType {
     	Shared = 2
 }
 
+/** Bounded two-dimensional source preview. Only intersecting import segments are inspected, never a workbook-sized DOM. */
+export declare function getExcelSheetWindow(imported: ExcelImportResult, sheetName: string, options?: ExcelSheetWindowOptions): ExcelSheetWindow;
+
 declare interface GradientStop {
     	position: number;
     	color: Partial<Color>;
@@ -991,6 +1157,9 @@ declare interface ImageRange {
  */
 export declare function importExcelTemplate(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions): Promise<ExcelImportResult>;
 
+/** Inspect sheet metadata before selecting a bounded import; does not construct any template grids. */
+export declare function inspectExcelWorkbook(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions): Promise<ExcelWorkbookInspection>;
+
 declare interface JSZipGeneratorOptions {
     	/**
      	 * @default DEFLATE
@@ -1028,6 +1197,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 ListComponent {
@@ -1062,15 +1234,38 @@ 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;
 }
 
+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 type ListGrandTotal = boolean | {
     label?: string;
     style?: ComponentStyle;
     /** 合计列（缺省沿用 groupBy.subtotal） */
     fields?: string[];
+    aggregates?: AggregateDefinition[];
 };
 
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
@@ -1086,6 +1281,9 @@ declare interface ListGroupBy {
     subtotalLabel?: string;
     /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
     keepWithNext?: boolean;
+    aggregates?: AggregateDefinition[];
+    /** Repeat this group heading after page breaks within the group. */
+    repeatHeader?: boolean;
 }
 
 declare interface Location_2 {
@@ -1104,6 +1302,22 @@ declare interface Margins {
     	footer: number;
 }
 
+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 Media {
     	type: string;	// image,background
     	name: string;
@@ -1303,7 +1517,11 @@ declare const enum PaperSize {
     	K16_197x273_mm = 119,
 }
 
+export declare function parseExcelBindingSession(input: unknown): ExcelBindingSession;
+
 declare interface PlanComponent {
+    /** Template page furniture repeats per page and reserves its vertical band. */
+    pageAnchor?: "header" | "footer";
     kind: ComponentKind;
     leftMm: number;
     topMm: number;
@@ -1455,6 +1673,34 @@ declare interface ReportCellSource {
     sourceToken?: string;
 }
 
+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 interface ReportFieldContract {
+    field: string;
+    label?: string;
+    type: "text" | "number" | "boolean" | "date" | "decimal";
+    required?: boolean;
+    nullable?: boolean;
+    enum?: readonly (string | number | boolean)[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    unit?: string;
+}
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
@@ -1484,6 +1730,17 @@ declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
+declare interface ReportTemplateDocument {
+    schemaVersion: "1.0";
+    id: string;
+    name: string;
+    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
+    revision?: string;
+    description?: string;
+    template: ReportTemplate;
+}
+
 declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -1765,6 +2022,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>;
@@ -1921,6 +2180,15 @@ declare interface Top10RuleType extends ConditionalFormattingBaseRule {
     	bottom: boolean;
 }
 
+/** Contract and mapping validation does not traverse imported grids. */
+export declare function validateExcelBindingFields(imported: ExcelImportResult, recipe: ExcelBindingRecipe, datasets: readonly ExcelBindingDataset[]): ExcelBindingValidation;
+
+/** Shared browser/Node validation. No header-name guessing, coercion, network or formula execution. */
+export declare function validateExcelBindingRecipe(imported: ExcelImportResult, recipe: ExcelBindingRecipe, datasets: readonly ExcelBindingDataset[]): ExcelBindingValidation;
+
+/** Region-only validation lets reactive consumers reuse the result while only mappings change. */
+export declare function validateExcelBindingRegions(imported: ExcelImportResult, recipe: ExcelBindingRecipe): ExcelBindingIssue[];
+
 declare enum ValueType {
     	Null = 0,
     	Merge = 1,