@agile-team/mach-report 2.13.0 → 2.14.0

package/dist/index.d.ts

@@ -16,6 +16,9 @@ export declare function applyReportCellEdit(plan: RenderPlan, edit: ReportCellEd
 /** Transactional from the caller's perspective: a later conflict never exposes earlier writes. */
 export declare function applyReportCellEditBatch(plan: RenderPlan, batch: Pick<ReportEditBatch, "edits">): RenderPlan;
 
+/** Styles affect report content only, never the surrounding designer/preview theme. */
+export declare function applyReportDocumentStyle(input: ReportTemplateDocument, pageIndex: number, indices: readonly number[], role: ReportDocumentStyle): ReportTemplateDocument;
+
 /** Refresh concurrency metadata without changing values, layout, or the host's source objects. */
 export declare function applyReportEditResult(plan: RenderPlan, batch: ReportEditBatch, result: void | ReportEditResult): RenderPlan;
 
@@ -102,6 +105,8 @@ export declare interface CanvasRenderResult {
     diagnostics: OutputDiagnostic[];
 }
 
+export declare function captureTemplateFragment(document: ReportTemplateDocument, pageIndex: number, indices: readonly number[], identity: Pick<ReportTemplateFragment, "id" | "name" | "revision">): ReportTemplateFragment;
+
 export declare function charWidthEm(ch: string): number;
 
 export declare type ClassKey = "root" | "page" | "comp" | "text" | "lines" | "line" | "rich" | "paragraph" | "segment" | "image" | "shape" | "grid" | "row" | "cell" | "unknown";
@@ -125,6 +130,9 @@ export declare interface CodeOptions {
     showText?: boolean;
 }
 
+/** A flat, indexed outline allows the UI to render a bounded search window. */
+export declare function collectTemplateOutline(template: ReportTemplate): TemplateOutlineEntry[];
+
 /**
  * 列值格式化（声明式、JSON 可序列化）。
  * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
@@ -490,6 +498,11 @@ export declare interface GridLayout {
     edges: GridEdge[];
 }
 
+export declare function hasValidDataExplanation(value: {
+    target?: unknown;
+    valueState?: unknown;
+}): boolean;
+
 /** 启发式测量器：无 Canvas 时的默认宽度估算 */
 export declare const heuristicMeasurer: TextMeasurer;
 
@@ -507,14 +520,32 @@ export declare interface ImageRenderResult {
     diagnostics: OutputDiagnostic[];
 }
 
+/** Row-major physical imposition. Record → copy → face order is preserved; no duplex reordering. */
+export declare function imposeLabelSheets(plan: RenderPlan, options: LabelSheetOptions): RenderPlan;
+
+/** Explicit replacement is atomic and preserves surrounding components and the document CAS revision. */
+export declare function insertTemplateFragment(input: ReportTemplateDocument, fragment: ReportTemplateFragment, options: TemplateFragmentInsertOptions): TemplateFragmentResult;
+
 export declare function inspectOutputCapabilities(plan: RenderPlan, format: OutputFormat): OutputDiagnostic[];
 
+/** Includes rule, aggregate, relation and formula references; never evaluates expressions. */
+export declare function inspectTemplateFieldUsage(template: ReportTemplate, dataset: string, field: string): TemplateFieldUsage[];
+
+export declare function inspectTemplateFragmentBindings(fragment: ReportTemplateFragment): {
+    dataset: string;
+    fields: string[];
+}[];
+
 export declare function isImageBackedComponent(comp: PlanComponent): boolean;
 
+export declare function isReportDataTarget(value: unknown): value is ReportDataTarget;
+
 export declare function isReportDate(value: string): boolean;
 
 export declare function isReportMonth(value: string): boolean;
 
+export declare function isReportValueState(value: unknown): value is ReportValueState;
+
 export declare function isReportYear(value: string): boolean;
 
 export declare function isRichText(comp: PlanComponent): boolean;
@@ -537,6 +568,44 @@ export declare type LabelReportDefinitionOptions = LabelReportDefinitionBase & (
 /** Named business row interfaces and readonly arrays need no index signature or conversion. */
 export declare type LabelReportRows = readonly object[];
 
+export declare class LabelSheetError extends Error {
+    readonly path: string;
+    readonly code = "label-sheet";
+    constructor(message: string, path: string);
+}
+
+export declare interface LabelSheetOptions {
+    /** A4 defaults to 210 × 297 mm; custom sizes are explicit physical millimetres. */
+    paper?: "a4" | {
+        widthMm: number;
+        heightMm: number;
+    };
+    columns: number;
+    rows: number;
+    marginMm?: number | {
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    };
+    gapMm?: number | {
+        horizontal: number;
+        vertical: number;
+    };
+    /** Empty slots on the first sheet only (zero based, row-major). */
+    startSlot?: number;
+    /** Printer calibration; geometry outside the physical sheet is rejected. */
+    offsetMm?: {
+        x: number;
+        y: number;
+    };
+    maxSheets?: number;
+    maxComponents?: number;
+    /** Independent plain JSON snapshot budget, default 64 MB. */
+    maxSnapshotBytes?: number;
+    signal?: AbortSignal;
+}
+
 export declare interface LabelTemplateOptions extends ReportTemplateRepeat {
     widthMm?: number;
     heightMm?: number;
@@ -1130,6 +1199,14 @@ export declare type ReportCellValue = string | number | boolean | null;
 
 export declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
 
+export declare interface ReportDataTarget {
+    datasetId: string;
+    field: string;
+    rowKey?: string | number;
+    /** Use table identity when the same dataset appears in several tables. */
+    tableId?: string;
+}
+
 /** Wire values deliberately remain strings in browsers, Workers and backend runtimes. */
 export declare interface ReportDateRange {
     start: string;
@@ -1162,6 +1239,16 @@ export declare interface ReportDiagnostic {
     message: string;
     path?: string;
     severity: "warning" | "error" | "info";
+    /** Optional explanation supplied by the business source, not inferred from blank cells. */
+    valueState?: ReportValueState;
+    target?: ReportDataTarget;
+}
+
+export declare interface ReportDocumentStyle {
+    id: string;
+    name: string;
+    style: ComponentStyle;
+    target?: "content" | "header";
 }
 
 export declare interface ReportEditBatch {
@@ -1231,7 +1318,8 @@ export declare interface ReportFetchInput extends ReportTaskMonitoring {
     signal?: AbortSignal;
     /** 本次分页与计划告警；未提供时使用数据源配置的告警通道。 */
     onWarning?: (message: string) => void;
-    onQueryResult?: (reportId: string, result: ReportQueryResult) => void;
+    /** Index scopes diagnostics when reports share datasets or a report ID is repeated. */
+    onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
 
 export declare interface ReportFieldContract {
@@ -1517,6 +1605,15 @@ export declare interface ReportTemplateFixture {
     params?: Record<string, string>;
 }
 
+/** Plain JSON, versioned by the host; inserting never links mutable library objects. */
+export declare interface ReportTemplateFragment {
+    id: string;
+    name: string;
+    revision: string;
+    components: TemplateComponent[];
+    repeatDataset?: string;
+}
+
 export declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
 
 export declare interface ReportTemplateManager {
@@ -1581,6 +1678,11 @@ export declare interface ReportTemplateReview {
     }>;
 }
 
+export declare interface ReportTemplateReviewAsyncOptions extends ReportTemplateReviewOptions {
+    signal?: AbortSignal;
+    onProgress?: (progress: ReportTemplateReviewProgress) => void;
+}
+
 export declare interface ReportTemplateReviewIssue {
     code: "template" | "compatibility" | "dataset" | "field" | "sample" | "layout" | "output" | "params";
     severity: "error" | "warning";
@@ -1606,6 +1708,13 @@ export declare interface ReportTemplateReviewOptions {
     strictOutputs?: boolean;
 }
 
+export declare interface ReportTemplateReviewProgress {
+    completed: number;
+    total: number;
+    stage: "template" | "baseline" | "bindings" | "fixture";
+    fixture?: string;
+}
+
 /** compareAndSwap 必须由宿主数据库/文件适配器保证原子性，不能用先读再无条件写替代。 */
 export declare interface ReportTemplateStore {
     read(id: string, signal?: AbortSignal): Promise<ReportTemplateRecord | undefined>;
@@ -1634,6 +1743,9 @@ export declare interface ReportTemplateVersion {
     restoredFrom?: string;
 }
 
+/** Optional business explanations never replace raw data or schema validation. */
+export declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
+
 /**
  * 边框开关解析：
  * - 未声明（undefined）→ 四边全开（与既有 rect 总有边框的行为兼容）
@@ -1702,6 +1814,9 @@ export declare function resolveTextColor(style: Pick<ComponentStyle, "color"> |
 /** Pure preflight uses explicit samples only; it never fetches business data or publishes a draft. */
 export declare function reviewReportTemplate(input: unknown, options?: ReportTemplateReviewOptions): ReportTemplateReview;
 
+/** Yields between structural/baseline checks and every bounded fixture; no fetching or persistence. */
+export declare function reviewReportTemplateAsync(input: unknown, options?: ReportTemplateReviewAsyncOptions): Promise<ReportTemplateReview>;
+
 export declare interface RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -1812,11 +1927,50 @@ export declare class TemplateBuilder {
 
 export declare type TemplateComponent = PlanComponent | ListComponent;
 
+export declare interface TemplateFieldUsage extends TemplateOutlineLocation {
+    dataset: string;
+    field: string;
+    kind: "display" | "calculation" | "binding";
+}
+
+export declare interface TemplateFragmentBindings {
+    datasets?: Record<string, string>;
+    fields?: Record<string, Record<string, string>>;
+}
+
+export declare interface TemplateFragmentInsertOptions {
+    pageIndex: number;
+    leftMm?: number;
+    topMm?: number;
+    bindings?: TemplateFragmentBindings;
+    replaceInstance?: string;
+}
+
+export declare interface TemplateFragmentResult {
+    document: ReportTemplateDocument;
+    componentIndices: number[];
+    instance: string;
+}
+
 export declare interface TemplateMutationOptions {
     expectedRevision: string | null;
     signal?: AbortSignal;
 }
 
+export declare interface TemplateOutlineEntry extends TemplateOutlineLocation {
+    kind: "page" | "component" | "field" | "calculation" | "binding";
+    title: string;
+    dataset?: string;
+    depth: number;
+}
+
+export declare interface TemplateOutlineLocation {
+    path: string;
+    pageIndex?: number;
+    componentIndex?: number;
+    field?: string;
+}
+
 export declare interface TemplatePage {
     widthMm: number;
     heightMm: number;
@@ -1832,6 +1986,8 @@ export declare interface TemplatePage {
     meta?: Record<string, unknown>;
 }
 
+export declare function templatePathLocation(path: string): Pick<TemplateOutlineLocation, "pageIndex" | "componentIndex">;
+
 export declare interface TemplateStoreWriteOptions {
     publication?: ReportTemplateVersion;
     signal?: AbortSignal;