@agile-team/mach-report 2.10.0 → 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;
@@ -1065,6 +1137,8 @@ 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。 */
@@ -1216,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";
@@ -1225,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;
@@ -1251,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. */
@@ -1537,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";
@@ -1573,6 +1657,7 @@ declare interface PlanGrid {
 }
 
 declare interface PlanPage {
+    meta?: Record<string, unknown>;
     /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
     layout?: "page" | "wide";
     pageWidthMm: number;
@@ -1721,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;
@@ -1736,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;
@@ -2183,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 {
@@ -2200,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;
 
@@ -2209,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,