@agile-team/mach-report 2.10.0 → 2.11.0

package/dist/index.d.ts

@@ -108,6 +108,11 @@ export declare type ClassKey = "root" | "page" | "comp" | "text" | "lines" | "li
 
 export declare function classOf(key: ClassKey, options?: RenderOptions): string;
 
+export declare function cloneReportTemplate(document: ReportTemplateDocument, identity: {
+    id: string;
+    name: string;
+}): ReportTemplateDocument;
+
 /**
  * 列值格式化（声明式、JSON 可序列化）。
  * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
@@ -170,6 +175,15 @@ export declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+declare interface ComputedDatasetOptions {
+    fields: readonly ComputedField[];
+    formula?: FormulaAdapter;
+    maxRows?: number;
+    maxCells?: number;
+    signal?: AbortSignal;
+    onError?: "throw" | "null";
+}
+
 declare interface ComputedField extends ExpressionOptions {
     field: string;
     expression: ReportExpression | string;
@@ -205,6 +219,13 @@ export declare function createCanvasPager(plan: RenderPlan, options?: CanvasPage
 /** 兼容旧 API：默认启发式测量 */
 export declare function createHeuristicMeasurer(): TextMeasurer;
 
+/** Local catalog reference; an enterprise host supplies the same search/get contract with server filtering. */
+export declare function createLocalTemplateCatalog(input: Array<{
+    document: ReportTemplateDocument;
+    category?: string;
+    tags?: string[];
+}>): ReportTemplateCatalogProvider;
+
 /** 单进程参考适配器；多实例服务请实现具备数据库事务/CAS 的持久化适配器。 */
 export declare function createMemoryTemplateStore(): ReportTemplateStore;
 
@@ -262,8 +283,16 @@ export declare function createTemplateManager(store: ReportTemplateStore, option
 /** 存储无关的模板目录；后台 CRUD、权限、发布审批与持久化由宿主接入。 */
 export declare function createTemplateRegistry(documents?: readonly ReportTemplateDocument[]): ReportTemplateRegistry;
 
+/** O(n) identity index, iterative bounded traversal, no input mutation or recursive stack. */
+export declare function createTreeTable(input: readonly DataRow[], options: TreeTableOptions, execution?: {
+    signal?: AbortSignal;
+    computed?: ComputedDatasetOptions;
+}): TreeTable;
+
 export declare const CSS_DPI = 96;
 
+declare type DataRow = Record<string, unknown>;
+
 export declare interface DatasetContract {
     fields: readonly ReportFieldContract[];
     rowKey?: string;
@@ -319,7 +348,6 @@ export declare function diffReportTemplates(previous: ReportTemplateDocument, ne
     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;
 
 /**
@@ -345,6 +373,8 @@ export declare function formatReportCellEdit(context: ReportCellContext, value:
 /** TSV with Excel-compatible quoting; quoted line breaks remain inside their cells. */
 export declare function formatReportClipboard(rows: readonly (readonly string[])[]): string;
 
+export declare function formatReportDateRange(range: ReportDateRange): string;
+
 /**
  * 应用格式化。非数值/无法解析时原样返回基础文本（降级不报错）：
  * - number：digits 小数位 + 可选千分位（12,345.60；thousands 默认 false）
@@ -375,6 +405,8 @@ export 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。 */
@@ -446,6 +478,10 @@ export declare function isImageBackedComponent(comp: PlanComponent): boolean;
 
 export declare function isReportDate(value: string): boolean;
 
+export declare function isReportMonth(value: string): boolean;
+
+export declare function isReportYear(value: string): boolean;
+
 export declare function isRichText(comp: PlanComponent): boolean;
 
 /** 默认行高倍数（基线距 = 字号 × 该系数） */
@@ -482,6 +518,8 @@ export declare interface ListColumn {
 
 export 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";
@@ -491,6 +529,10 @@ export 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;
@@ -517,6 +559,8 @@ export 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. */
@@ -741,6 +785,9 @@ export declare function parseReportCellInput(context: ReportCellContext, input:
 /** Bounded parser for clipboard data; invalid quotes are rejected before edits are built. */
 export declare function parseReportClipboard(text: string, maxCells?: number): string[][];
 
+/** Only complete, ordered, real calendar dates are accepted; there is no timezone conversion. */
+export declare function parseReportDateRange(value: string): ReportDateRange | undefined;
+
 /** 校验文件 JSON 文本或接口返回的未知对象，返回独立模板快照。 */
 export declare function parseReportTemplate(input: unknown): ReportTemplateDocument;
 
@@ -786,6 +833,7 @@ export declare interface PlanGrid {
 }
 
 export declare interface PlanPage {
+    meta?: Record<string, unknown>;
     /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
     layout?: "page" | "wide";
     pageWidthMm: number;
@@ -995,6 +1043,12 @@ export declare type ReportCellValue = string | number | boolean | null;
 
 export declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
 
+/** Wire values deliberately remain strings in browsers, Workers and backend runtimes. */
+export declare interface ReportDateRange {
+    start: string;
+    end: string;
+}
+
 export declare interface ReportDefinition {
     /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
     template: ReportTemplate | ReportTemplateLoader;
@@ -1108,6 +1162,14 @@ export declare interface ReportFieldContract {
     unit?: string;
 }
 
+export 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;
+}
+
 export declare interface ReportHistoryPreparation {
     batch: ReportEditBatch;
     prepared: ReportPreparedEdit;
@@ -1123,13 +1185,17 @@ export declare interface ReportLoadContext {
 
 export declare function reportOutputDiagnostics(plan: RenderPlan, format: OutputFormat, options: OutputDiagnosticOptions): OutputDiagnostic[];
 
+export declare interface ReportPageFlow {
+    bands: ReportFlowBand[];
+}
+
 /** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
 export 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;
@@ -1138,7 +1204,7 @@ export 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;
@@ -1284,6 +1350,38 @@ export declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+export declare interface ReportTemplateCatalogEntry extends ReportTemplateSummary {
+    category?: string;
+    tags?: string[];
+    updatedAt?: string;
+}
+
+export declare interface ReportTemplateCatalogPage {
+    items: ReportTemplateCatalogEntry[];
+    next?: string;
+    categories?: Array<{
+        id: string;
+        label: string;
+        count?: number;
+    }>;
+}
+
+/** Discovery metadata is separate from executable templates and from enterprise account authorization. */
+export declare interface ReportTemplateCatalogProvider {
+    search(request: ReportTemplateCatalogQuery): Promise<ReportTemplateCatalogPage>;
+    get(id: string, context: {
+        signal?: AbortSignal;
+    }): Promise<ReportTemplateDocument | undefined>;
+}
+
+export declare interface ReportTemplateCatalogQuery {
+    query?: string;
+    category?: string;
+    cursor?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+
 export declare interface ReportTemplateChange {
     kind: "added" | "removed" | "modified" | "moved";
     category: "metadata" | "structure" | "binding" | "calculation" | "format";
@@ -1614,6 +1712,9 @@ export 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>;
 }
 
 export declare interface TemplateStoreWriteOptions {
@@ -1646,6 +1747,46 @@ export declare function toExcelNumberFormat(format?: ColumnFormat): string | und
 
 export declare function toNumber(value: unknown): number | null;
 
+export declare interface TreeRow {
+    row: DataRow;
+    original: DataRow;
+    key: string | number;
+    depth: number;
+    hasChildren: boolean;
+}
+
+export declare class TreeRowLimitError extends Error {
+    readonly limit: number;
+    readonly code = "tree-row-limit";
+    constructor(limit: number);
+}
+
+export declare interface TreeTable {
+    rows: DataRow[];
+    entries: TreeRow[];
+    leaves: DataRow[];
+}
+
+/** A serialized tree contract. Sibling and root order follow input order. */
+export 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;
+}
+
 export declare function validateComponent(comp: unknown, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
 
 /** 浏览器/Node共用的只读值校验；返回精确路径，不以0或空数组掩盖接口结构错误。 */
@@ -1672,6 +1813,9 @@ export declare function validateReportTemplate(input: unknown): ValidationResult
 
 export declare function validateReportTemplateDocument(input: unknown): ValidationResult;
 
+/** Validates runtime inputs too, so direct core calls cannot bypass template checks. */
+export declare function validateTreeOptions(options: TreeTableOptions): void;
+
 export declare interface ValidationError {
     path: string;
     message: string;