@agile-team/mach-report 2.9.1 → 2.11.0

package/dist/index.d.cts

@@ -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;
 
@@ -221,6 +242,13 @@ export declare function createReportCellEditBatch(plan: RenderPlan, inputs: read
 /** Operation-scoped index: avoids repeated geometry work without caching mutable plans globally. */
 export declare function createReportCellResolver(plan: RenderPlan): (address: ReportCellAddress) => ReportCellContext | null;
 
+/** Optional standalone entry; normal createReportSource/createLocalFetcher already register it. */
+export declare function createReportEditSession(options: {
+    template: ReportTemplate;
+    datasets: DatasetRows;
+    pagination?: PaginateOptions;
+}): ReportEditSession;
+
 /**
  * 框架无关的报表数据源：注册一次模板与取数，包内完成分页、校验、按 ID 顺序合并。
  * 不缓存业务结果、不推断接口包装、不自动重试；鉴权与完整数据范围由宿主决定。
@@ -255,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;
@@ -312,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;
 
 /**
@@ -338,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）
@@ -359,6 +396,8 @@ declare type Geometry = Partial<Pick<PlanComponent, "leftMm" | "topMm" | "widthM
 
 export declare function getReportCellContext(plan: RenderPlan, address: ReportCellAddress): ReportCellContext | null;
 
+export declare function getReportEditSession(plan: RenderPlan): ReportEditSession | undefined;
+
 export declare interface GridCell {
     text?: string;
     rawText?: string;
@@ -366,11 +405,15 @@ 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。 */
     editable?: boolean;
     source?: ReportCellSource;
+    /** SDK 派生结果不映射业务来源，始终只读（包括覆盖同名源字段的计算）。 */
+    derived?: boolean;
     /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
     formula?: string;
     children?: PlanComponent[];
@@ -435,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;
 
 /** 默认行高倍数（基线距 = 字号 × 该系数） */
@@ -471,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";
@@ -480,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;
@@ -506,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. */
@@ -519,6 +574,9 @@ export declare interface ListDetail {
     parentKey: string;
     foreignKey: string;
     rowKey?: string;
+    /** 子表独立的并发契约；省略时不继承主表字段。 */
+    revisionField?: string;
+    sourceTokenField?: string;
     columns: ListColumn[];
     rowHeightMm?: number;
     header?: boolean;
@@ -727,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;
 
@@ -772,6 +833,7 @@ export declare interface PlanGrid {
 }
 
 export declare interface PlanPage {
+    meta?: Record<string, unknown>;
     /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
     layout?: "page" | "wide";
     pageWidthMm: number;
@@ -807,6 +869,12 @@ export declare function ptToPx(pt: number, dpi?: number): number;
 
 export declare function pxToMm(value: number, dpi?: number): number;
 
+/** Registers only context references/fingerprint. Read-only loads never deep-copy data or reflow. */
+export declare function registerReportEditSession(initial: RenderPlan, registration: ReportEditSessionRegistration): ReportEditSession;
+
+/** Reflow changes coordinates; history targets are resolved by business source every time. */
+export declare function relocateReportCellEdits(plan: RenderPlan, edits: readonly ReportCellEdit[], value: "previousValue" | "value"): ReportCellInput[];
+
 export declare const RENDER_PLAN_SCHEMA_VERSION = "1.0.0-mach";
 
 export declare function renderComponent(comp: PlanComponent, dpi: number, options: RenderOptions, doc: Document): HTMLElement;
@@ -820,6 +888,8 @@ export declare function renderPage(page: PlanPage, dpi: number, options: RenderO
 
 export declare interface RenderPlan {
     schemaVersion: string;
+    /** 编辑需要模板重算上下文；跨 Worker/JSON 保留要求，但不声明本地会话可用。 */
+    requiresRecalculation?: boolean;
     pages: PlanPage[];
 }
 
@@ -902,7 +972,7 @@ export declare class ReportCellEditError extends Error {
     constructor(code: ReportCellEditErrorCode);
 }
 
-export declare type ReportCellEditErrorCode = "missing" | "readonly" | "number" | "boolean" | "conflict" | "duplicate" | "limit" | "atomic" | "clipboard";
+export declare type ReportCellEditErrorCode = "missing" | "readonly" | "number" | "boolean" | "conflict" | "duplicate" | "limit" | "atomic" | "clipboard" | "recalculation";
 
 export declare function reportCellEditKey(edit: Pick<ReportCellEdit, "address" | "source" | "table">): string;
 
@@ -950,7 +1020,7 @@ export declare interface ReportCellInput {
     value: ReportCellValue;
 }
 
-export declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
+export declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure" | "derived";
 
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
 export declare interface ReportCellSource {
@@ -973,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;
@@ -1015,6 +1091,10 @@ export declare interface ReportEditConflict {
     revision?: string | number;
 }
 
+export declare interface ReportEditPreparationOptions {
+    signal?: AbortSignal;
+}
+
 export declare interface ReportEditResult {
     /** A successful result may advance concurrency tokens for the affected dataset. */
     revision?: string | number;
@@ -1023,6 +1103,22 @@ export declare interface ReportEditResult {
     conflicts?: readonly ReportEditConflict[];
 }
 
+export declare interface ReportEditSession {
+    readonly plan: RenderPlan;
+    prepare(plan: RenderPlan, batch: ReportEditBatch, options?: ReportEditPreparationOptions): Promise<ReportPreparedEdit>;
+    prepareHistory(plan: RenderPlan, edits: readonly ReportCellEdit[], value: "previousValue" | "value", requestId: string, options?: ReportEditPreparationOptions): Promise<ReportHistoryPreparation>;
+}
+
+declare interface ReportEditSessionPart {
+    template: ReportTemplate;
+    datasets: DatasetRows;
+}
+
+export declare interface ReportEditSessionRegistration {
+    parts: readonly ReportEditSessionPart[];
+    rebuild(parts: readonly ReportEditSessionPart[], signal?: AbortSignal): Promise<RenderPlan>;
+}
+
 declare type ReportExpression = {
     field: string;
 } | {
@@ -1066,6 +1162,20 @@ 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;
+    contexts: readonly ReportCellContext[];
+}
+
 /** 取数与排版共同使用的请求上下文；取消只影响本次调用。 */
 export declare interface ReportLoadContext {
     reportId: string;
@@ -1075,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;
@@ -1090,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;
@@ -1124,6 +1238,13 @@ export declare class ReportParamValidationError extends Error {
     constructor(issues: readonly ReportParamIssue[]);
 }
 
+export declare interface ReportPreparedEdit {
+    /** Calculated preview; no source/session state changes until commit succeeds. */
+    readonly plan: RenderPlan;
+    /** Call after persistence. A stale or repeated commit fails instead of publishing mixed state. */
+    commit(result?: void | ReportEditResult): RenderPlan;
+}
+
 /** 查询是唯一基础能力；权限、HTTP、数据库和事务都留在宿主适配器内。 */
 export declare interface ReportProvider {
     query(context: ReportLoadContext): ReportQueryResult | Promise<ReportQueryResult>;
@@ -1229,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";
@@ -1322,7 +1475,7 @@ export declare interface ReportTemplateReview {
 }
 
 export declare interface ReportTemplateReviewIssue {
-    code: "template" | "compatibility" | "dataset" | "field" | "sample" | "layout" | "output";
+    code: "template" | "compatibility" | "dataset" | "field" | "sample" | "layout" | "output" | "params";
     severity: "error" | "warning";
     path: string;
     message: string;
@@ -1559,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 {
@@ -1591,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或空数组掩盖接口结构错误。 */
@@ -1617,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;