@agile-team/mach-report 2.9.1 → 2.11.0

package/dist/xlsx.d.ts

@@ -60,6 +60,10 @@ declare class Anchor implements IAnchor {
     	constructor(model?: IAnchor | object);
 }
 
+export declare type AnyExcelBindingDocumentResult = ExcelBindingDocumentResult | ExcelRegionBindingDocumentResult;
+
+export declare type AnyExcelBindingSession = ExcelBindingSession | ExcelRegionBindingSession;
+
 declare type AutoFilter = string | {
     	from: string | { row: number; column: number };
     	to: string | { row: number; column: number };
@@ -471,6 +475,17 @@ export declare function createExcelBindingSession(imported: ExcelImportResult, r
     name: string;
 }): ExcelBindingSession;
 
+export declare function createExcelRegionBindingDocument(imported: ExcelImportResult, recipe: ExcelRegionBindingRecipe, datasets: readonly ExcelBindingDataset[], identity: {
+    id: string;
+    name: string;
+}): ExcelRegionBindingDocumentResult;
+
+/** Draft sessions preserve exact incomplete mappings; applying still runs geometry and contract checks. */
+export declare function createExcelRegionBindingSession(source: ExcelImportResult, recipe: ExcelRegionBindingRecipe, identity: {
+    id: string;
+    name: string;
+}): ExcelRegionBindingSession;
+
 declare interface Csv {
     	/**
      	 * read from a file
@@ -600,6 +615,15 @@ declare enum ErrorValue {
     	Num = '#NUM!',
 }
 
+/** Convert graphical two-dimensional selection into exact, source-bounded coordinates. */
+export declare function excelBindingCellRange(imported: ExcelImportResult, sheetName: string, from: {
+    row: number;
+    column: number;
+}, to?: {
+    row: number;
+    column: number;
+}): string;
+
 export declare type ExcelBindingColumn = string | (Omit<ListColumn, "widthMm" | "header"> & {
     header?: string;
 });
@@ -845,6 +869,54 @@ declare namespace ExcelJS {
     }
 }
 
+/** A row prototype is replaced, never copied into a generated business report. */
+export declare interface ExcelRegionBinding {
+    id: string;
+    /** One physical source row, with any contiguous subset of the sheet columns. */
+    range: string;
+    dataset: string;
+    /** record accepts zero or one row; repeat expands vertically and shifts following bands. */
+    mode: "record" | "repeat";
+    fields: string[];
+    rowKey: string;
+    revisionField?: string;
+    sourceTokenField?: string;
+    /** Optional immediately preceding header, with the same physical columns. */
+    headerRange?: string;
+}
+
+export declare interface ExcelRegionBindingDocumentResult {
+    document: ReportTemplateDocument;
+    recipe: ExcelRegionBindingRecipe;
+    warnings: string[];
+}
+
+/** Version 2 describes several independent, vertically ordered data regions on one Sheet. */
+export declare interface ExcelRegionBindingRecipe {
+    version: "2.0";
+    sheet: string;
+    regions: ExcelRegionBinding[];
+    /** Full-width source rows reserved on every page; excluded from flowing content. */
+    footerRange?: string;
+}
+
+export declare interface ExcelRegionBindingSession {
+    version: "2.0";
+    source: ExcelImportResult;
+    recipe: ExcelRegionBindingRecipe;
+    identity: {
+        id: string;
+        name: string;
+    };
+}
+
+export declare interface ExcelRegionBindingValidation {
+    ok: boolean;
+    issues: ExcelBindingIssue[];
+    mapped: number;
+    total: number;
+}
+
 export declare interface ExcelSheetWindow {
     top: number;
     bottom: number;
@@ -912,6 +984,16 @@ export declare interface ExcelWorkbookInspection {
     warnings: string[];
 }
 
+/** Parsing budgets are fixed at open; selections can change without reopening the workbook. */
+export declare type ExcelWorkbookSelectionOptions = Omit<ExcelImportOptions, "limits">;
+
+export declare interface ExcelWorkbookSession {
+    readonly disposed: boolean;
+    inspect(): ExcelWorkbookInspection;
+    importTemplate(options?: ExcelWorkbookSelectionOptions): Promise<ExcelImportResult>;
+    dispose(): void;
+}
+
 export declare interface ExcelWorkbookSheet {
     name: string;
     index: number;
@@ -1055,11 +1137,15 @@ declare interface GridCell {
     value?: string | number | boolean | null;
     /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
     numberFormat?: string;
+    /** Physical left inset for hierarchical labels; raw value stays unchanged. */
+    indentMm?: number;
     /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
     valueType?: "text" | "number" | "boolean";
     /** 单元格级编辑控制；预览仍需显式开启 editing。 */
     editable?: boolean;
     source?: ReportCellSource;
+    /** SDK 派生结果不映射业务来源，始终只读（包括覆盖同名源字段的计算）。 */
+    derived?: boolean;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -1204,6 +1290,8 @@ declare interface ListColumn {
 
 declare interface ListComponent {
     kind: "list";
+    /** Opaque serializable layout annotations; interpreted only by explicit optional adapters. */
+    meta?: Record<string, unknown>;
     id?: string;
     /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
     layout?: "page" | "wide";
@@ -1213,6 +1301,10 @@ declare interface ListComponent {
     topMm: number;
     widthMm: number;
     dataset: string;
+    /** Headerless record/region bindings do not allocate a synthetic list header. */
+    header?: boolean;
+    /** A fixed record region rejects multiple rows instead of dropping source data. */
+    cardinality?: "record";
     /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
     rowKey?: string;
     revisionField?: string;
@@ -1239,6 +1331,8 @@ declare interface ListComponent {
     computed?: ComputedField[];
     /** Dynamic pivot of the current source dataset, with read-only derived identities. */
     matrix?: MatrixTableOptions;
+    /** Full ordered hierarchy; source parent values and descendant-leaf rollups are explicit. */
+    tree?: TreeTableOptions;
     /** 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. */
@@ -1252,6 +1346,9 @@ declare interface ListDetail {
     parentKey: string;
     foreignKey: string;
     rowKey?: string;
+    /** 子表独立的并发契约；省略时不继承主表字段。 */
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn[];
     rowHeightMm?: number;
     header?: boolean;
@@ -1325,6 +1422,9 @@ declare interface Media {
     	buffer: Buffer_2;
 }
 
+/** One bounded workbook per owner. The caller releases it when replacing input or unmounting. */
+export declare function openExcelWorkbook(input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions): Promise<ExcelWorkbookSession>;
+
 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";
@@ -1519,6 +1619,8 @@ declare const enum PaperSize {
 
 export declare function parseExcelBindingSession(input: unknown): ExcelBindingSession;
 
+export declare function parseExcelRegionBindingSession(input: unknown): ExcelRegionBindingSession;
+
 declare interface PlanComponent {
     /** Template page furniture repeats per page and reserves its vertical band. */
     pageAnchor?: "header" | "footer";
@@ -1555,6 +1657,7 @@ declare interface PlanGrid {
 }
 
 declare interface PlanPage {
+    meta?: Record<string, unknown>;
     /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
     layout?: "page" | "wide";
     pageWidthMm: number;
@@ -1659,6 +1762,8 @@ declare enum RelationshipType {
 
 declare interface RenderPlan {
     schemaVersion: string;
+    /** 编辑需要模板重算上下文；跨 Worker/JSON 保留要求，但不声明本地会话可用。 */
+    requiresRecalculation?: boolean;
     pages: PlanPage[];
 }
 
@@ -1701,13 +1806,25 @@ declare interface ReportFieldContract {
     unit?: string;
 }
 
+declare interface ReportFlowBand {
+    /** Exact stable component IDs. Static components use nid, lists use id. */
+    componentIds: string[];
+    /** Source-template coordinates; following bands keep their original gap. */
+    topMm: number;
+    heightMm: number;
+}
+
+declare interface ReportPageFlow {
+    bands: ReportFlowBand[];
+}
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 declare interface ReportParamDef {
     /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
     /** select 选项 */
     options?: Array<{
         label: string;
@@ -1716,7 +1833,7 @@ declare interface ReportParamDef {
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
-    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    /** 数字上下界；日期/月/年使用对应规范字符串；dateRange 对两端使用 YYYY-MM-DD 边界（含边界）。 */
     min?: number | string;
     max?: number | string;
     minLength?: number;
@@ -2163,6 +2280,9 @@ declare interface TemplatePage {
     marginLeftMm?: number;
     marginRightMm?: number;
     components: TemplateComponent[];
+    /** Explicit vertical bands preserve source gaps as dynamic regions expand. */
+    flow?: ReportPageFlow;
+    meta?: Record<string, unknown>;
 }
 
 declare interface TimePeriodRuleType extends ConditionalFormattingBaseRule {
@@ -2180,6 +2300,26 @@ declare interface Top10RuleType extends ConditionalFormattingBaseRule {
     	bottom: boolean;
 }
 
+/** A serialized tree contract. Sibling and root order follow input order. */
+declare interface TreeTableOptions {
+    input: "flat" | "nested";
+    idField: string;
+    /** Flat roots have null/undefined parent values. */
+    parentField?: string;
+    /** Nested child arrays, defaults to children. Every node still needs an ID. */
+    childrenField?: string;
+    labelField: string;
+    indentMm?: number;
+    orphan?: "error" | "root";
+    /** Source preserves parent values; leaf-aggregate derives only parents from descendant leaves. */
+    parentValues?: "source" | "leaf-aggregate";
+    aggregates?: AggregateDefinition[];
+    maxRows?: number;
+    maxDepth?: number;
+    /** Bounded leaf-to-ancestor aggregate work; default one million. */
+    maxAggregationVisits?: number;
+}
+
 /** Contract and mapping validation does not traverse imported grids. */
 export declare function validateExcelBindingFields(imported: ExcelImportResult, recipe: ExcelBindingRecipe, datasets: readonly ExcelBindingDataset[]): ExcelBindingValidation;
 
@@ -2189,6 +2329,13 @@ export declare function validateExcelBindingRecipe(imported: ExcelImportResult,
 /** Region-only validation lets reactive consumers reuse the result while only mappings change. */
 export declare function validateExcelBindingRegions(imported: ExcelImportResult, recipe: ExcelBindingRecipe): ExcelBindingIssue[];
 
+export declare function validateExcelRegionBindings(imported: ExcelImportResult, recipe: ExcelRegionBindingRecipe, datasets: readonly ExcelBindingDataset[]): ExcelRegionBindingValidation;
+
+export declare function validateExcelRegionFields(recipe: ExcelRegionBindingRecipe, datasets: readonly ExcelBindingDataset[]): ExcelRegionBindingValidation;
+
+/** Geometry-only scan is separate so field-selection UI need not repeatedly traverse the source grid. */
+export declare function validateExcelRegionGeometry(imported: ExcelImportResult, recipe: ExcelRegionBindingRecipe): ExcelBindingIssue[];
+
 declare enum ValueType {
     	Null = 0,
     	Merge = 1,
@@ -2839,6 +2986,15 @@ declare interface Xlsx {
     	write(stream: Stream, options?: Partial<XlsxWriteOptions>): Promise<void>;
 }
 
+declare interface XlsxImageOptions {
+    /** Decoded bytes per unique embedded image; default 16 MiB. */
+    maxImageBytes?: number;
+    /** Total decoded bytes of unique images in this workbook; default 32 MiB. */
+    maxTotalImageBytes?: number;
+    /** Unique embedded media limit, default 1000; repeated placements reuse the same media. */
+    maxImages?: number;
+}
+
 declare interface XlsxReadOptions {
     	/**
      	 * The list of XML node names to ignore while parsing an XLSX file
@@ -2854,7 +3010,7 @@ declare interface XlsxReadOptions {
  *   目标是"财务能直接用的对账表"而非复刻版面）
  * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
  */
-export declare interface XlsxRenderOptions extends OutputDiagnosticOptions {
+export declare interface XlsxRenderOptions extends OutputDiagnosticOptions, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */