@agile-team/mach-report 2.21.1 → 2.22.0

package/dist/index.d.ts

@@ -65,6 +65,9 @@ export declare interface AsyncCanvasRenderOptions extends CanvasRenderOptions, A
     imageLoader?: CanvasImageLoader;
 }
 
+/** Resolve host-owned text context by a stable meta.contextKey, preserving editable geometry. */
+export declare function bindReportTemplateContext(template: ReportTemplate, context: Readonly<Record<string, string>>): ReportTemplate;
+
 /** 盒子边框语义：四边开关 + 内部网格线（四边全关则内线不画） */
 export declare interface BoxBorders {
     top: boolean;
@@ -633,6 +636,9 @@ export declare function insertTemplateFragment(input: ReportTemplateDocument, fr
 
 export declare function inspectOutputCapabilities(plan: RenderPlan, format: OutputFormat): OutputDiagnostic[];
 
+/** Check before applying a stored template to a new host dataset. Missing provenance is explicit. */
+export declare function inspectReportTemplateCompatibility(template: ReportTemplate, target: ReportTemplateDataContract): ReportTemplateCompatibilityResult;
+
 /** Includes rule, aggregate, relation and formula references; never evaluates expressions. */
 export declare function inspectTemplateFieldUsage(template: ReportTemplate, dataset: string, field: string): TemplateFieldUsage[];
 
@@ -2056,6 +2062,8 @@ export declare type ReportTaskObserver = (event: ReportTaskEvent) => void;
 
 export declare interface ReportTemplate {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -2112,6 +2120,27 @@ export declare interface ReportTemplateChange {
     breaking: boolean;
 }
 
+export declare interface ReportTemplateCompatibilityIssue {
+    code: "contract" | "source" | "dataset" | "field" | "semantic" | "type" | "unit";
+    path: string;
+    message: string;
+    dataset?: string;
+    field?: string;
+}
+
+export declare interface ReportTemplateCompatibilityResult {
+    ok: boolean;
+    issues: ReportTemplateCompatibilityIssue[];
+}
+
+export declare interface ReportTemplateDataContract {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding[];
+    }>>;
+}
+
 export declare interface ReportTemplateDiff {
     changes: ReportTemplateChange[];
     totalChanges: number;
@@ -2135,6 +2164,15 @@ export declare class ReportTemplateError extends Error {
     constructor(errors: readonly ValidationError[]);
 }
 
+/** Stable business meaning is independent of a column's position and editable caption. */
+export declare interface ReportTemplateFieldBinding {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract["type"];
+    unit?: string;
+}
+
 export declare interface ReportTemplateFixture {
     name: string;
     datasets: DatasetRows;