@agile-team/mach-report 2.13.0 → 2.15.0

package/dist/index.d.ts

@@ -16,9 +16,15 @@ 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;
 
+/** Session-owned receipts survive reflow even when host rows have no concurrency fields. */
+export declare function applyReportSourceMetadata(plan: RenderPlan, metadata: ReadonlyMap<string, ReportEditResult>): RenderPlan;
+
 export declare function assertRenderPlan(input: unknown): PlanPage[];
 
 export declare function assertReportParams(defs: readonly ReportParamDef[], input?: Record<string, unknown>): Record<string, string>;
@@ -34,7 +40,7 @@ export declare interface AssetRenderBudget {
     maxDurationMs?: number;
 }
 
-export declare interface AssetRenderOptions extends OutputDiagnosticOptions {
+export declare interface AssetRenderOptions extends OutputDiagnosticOptions, ImageMediaOptions {
     assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
     assetBudget?: AssetRenderBudget;
     /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
@@ -102,6 +108,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 +133,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 之前，
@@ -267,6 +278,9 @@ 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;
 
+/** Revalidates the current cell on activation; returns only bounded scalar values and explicit return state. */
+export declare function createReportDrillRequest(plan: RenderPlan, address: ReportCellAddress, action: ReportDrillAction, params?: Readonly<Record<string, string>>): ReportDrillRequest;
+
 /** Optional standalone entry; normal createReportSource/createLocalFetcher already register it. */
 export declare function createReportEditSession(options: {
     template: ReportTemplate;
@@ -490,11 +504,29 @@ export declare interface GridLayout {
     edges: GridEdge[];
 }
 
+export declare function hasValidDataExplanation(value: {
+    target?: unknown;
+    valueState?: unknown;
+}): boolean;
+
 /** 启发式测量器：无 Canvas 时的默认宽度估算 */
 export declare const heuristicMeasurer: TextMeasurer;
 
 export declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
 
+/** Bounded binary image inspection shared by PDF, Excel and template import. No decoder is loaded. */
+declare interface ImageMediaOptions {
+    maxImageBytes?: number;
+    maxTotalImageBytes?: number;
+    maxImages?: number;
+    /** Decoded pixels per unique image, default 16 million. */
+    maxImagePixels?: number;
+    /** Total decoded pixels for unique media, default 64 million. */
+    maxTotalImagePixels?: number;
+    /** Maximum source dimension, default 16384 pixels. */
+    maxImageDimension?: number;
+}
+
 export declare interface ImageRenderOptions extends AsyncCanvasRenderOptions {
     /** 图片格式（默认 png；jpeg 体积更小但无透明） */
     format?: "png" | "jpeg";
@@ -507,14 +539,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 +587,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;
@@ -686,6 +774,9 @@ export declare interface LocalTemplateCatalogItem {
     tags?: string[];
 }
 
+/** O(action count), no row scans or listeners per cell; invoke for the focused cell only. */
+export declare function matchReportDrillActions(plan: RenderPlan, address: ReportCellAddress, actions: readonly ReportDrillAction[]): ReportDrillAction[];
+
 declare interface MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -725,7 +816,7 @@ export declare class OutputAssetError extends Error {
 }
 
 export declare interface OutputDiagnostic {
-    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "unsupported-style" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
+    code: "invalid-image-data" | "image-budget-exceeded" | "component-render-failed" | "unsupported-text" | "output-degraded" | "missing-image" | "unsupported-component" | "unsupported-image-format" | "unsupported-style" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
     severity: "warning";
     format: OutputFormat;
     pageIndex: number;
@@ -948,7 +1039,7 @@ 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. */
+/** Registers a bounded descriptor guard. Immutable strings are retained, never rescanned character by character. */
 export declare function registerReportEditSession(initial: RenderPlan, registration: ReportEditSessionRegistration): ReportEditSession;
 
 /** Reflow changes coordinates; history targets are resolved by business source every time. */
@@ -1111,6 +1202,8 @@ export declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" |
 
 /** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
 export declare interface ReportCellSource {
+    /** Source identity across report occurrences; sharing must be explicitly declared. */
+    sourceScope?: string;
     datasetId: string;
     rowKey: string | number;
     field: string;
@@ -1130,6 +1223,16 @@ 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;
+    /** Assigned by the source/runtime when several reports share dataset names. */
+    reportScope?: string;
+}
+
 /** Wire values deliberately remain strings in browsers, Workers and backend runtimes. */
 export declare interface ReportDateRange {
     start: string;
@@ -1137,6 +1240,8 @@ export declare interface ReportDateRange {
 }
 
 export declare interface ReportDefinition {
+    /** Explicitly shared editable data identity. Omit to isolate each report occurrence. */
+    sourceScope?: string;
     /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
     template: ReportTemplate | ReportTemplateLoader;
     /** 静态数据；load 存在时优先使用 load 的结果。 */
@@ -1162,6 +1267,56 @@ 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";
+}
+
+/** Serializable action metadata. URLs, scripts and automatic navigation are deliberately absent. */
+export declare interface ReportDrillAction {
+    id: string;
+    label: string;
+    target: {
+        field: string;
+        datasetId?: string;
+        reportScope?: string;
+        roles?: readonly string[];
+    };
+    params?: Readonly<Record<string, ReportDrillBinding>>;
+}
+
+export declare type ReportDrillBinding = {
+    value: string | number | boolean;
+} | {
+    from: "value" | "rowKey";
+} | {
+    from: "query" | "field";
+    field: string;
+};
+
+export declare class ReportDrillError extends Error {
+    readonly code: "config" | "missing-value" | "target";
+    constructor(code: "config" | "missing-value" | "target");
+}
+
+export declare interface ReportDrillRequest {
+    actionId: string;
+    params: Readonly<Record<string, string>>;
+    returnState: Readonly<ReportDrillReturnState>;
+}
+
+export declare interface ReportDrillReturnState {
+    params: Readonly<Record<string, string>>;
+    address: Readonly<ReportCellAddress>;
+    reportScope?: string;
+    source?: Readonly<Pick<ReportCellSource, "sourceScope" | "datasetId" | "rowKey" | "field">>;
 }
 
 export declare interface ReportEditBatch {
@@ -1199,6 +1354,7 @@ export declare interface ReportEditSession {
 declare interface ReportEditSessionPart {
     template: ReportTemplate;
     datasets: DatasetRows;
+    sourceScope?: string;
 }
 
 export declare interface ReportEditSessionRegistration {
@@ -1231,7 +1387,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 {
@@ -1288,6 +1445,10 @@ export declare interface ReportParamDef {
         label: string;
         value: string;
     }>;
+    /** Opaque host-resolved source key. No URL, credentials or executable code is stored. */
+    optionsSource?: string;
+    /** Select dependencies must be declared parameters; changing a parent clears descendants. */
+    dependsOn?: string[];
     defaultValue?: string;
     required?: boolean;
     placeholder?: string;
@@ -1305,7 +1466,7 @@ export declare interface ReportParamIssue {
     message: string;
 }
 
-export declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "minimum" | "maximum" | "minLength" | "maxLength";
+export declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength";
 
 /** 描述 typedValues 的 Draft 2020-12 Schema；日期区间额外保留 x-report-* 扩展。 */
 export declare function reportParamsJsonSchema(defs: readonly ReportParamDef[]): Record<string, unknown>;
@@ -1517,6 +1678,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 +1751,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 +1781,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 +1816,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 总有边框的行为兼容）
@@ -1690,6 +1875,9 @@ export declare interface ResolvePlanAssetsOptions extends AssetRenderOptions {
     end?: number;
 }
 
+/** Resolve a stable business cell after requery/reordering; missing rows never fall back to another row. */
+export declare function resolveReportDrillReturn(plan: RenderPlan, state: ReportDrillReturnState): ReportCellAddress | null;
+
 /** 描边解析：颜色 + 线宽（pt） */
 export declare function resolveStroke(style: Pick<ComponentStyle, "borderColor" | "lineColor" | "lineWidthPt"> | undefined, fallbackColor?: string): {
     color: string;
@@ -1702,6 +1890,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 +2003,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 +2062,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;
@@ -1917,6 +2149,8 @@ export declare function validateRenderPlan(input: unknown): ValidationResult;
 /** Check configuration before opening an input, including JSON/JavaScript callers. */
 export declare function validateReportCellFieldDefinition(context: ReportCellContext, field: ReportCellFieldOptions): void;
 
+export declare function validateReportDrillActions(actions: readonly ReportDrillAction[]): void;
+
 /** 模板参数配置错误也统一返回结构化问题，不让无效默认值或边界静默进入后端。 */
 export declare function validateReportParamDefinitions(defs: readonly ReportParamDef[]): ReportParamIssue[];