@agile-team/mach-report 2.14.0 → 2.15.0

package/dist/index.d.cts

@@ -22,6 +22,9 @@ export declare function applyReportDocumentStyle(input: 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>;
@@ -37,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. */
@@ -275,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;
@@ -508,6 +514,19 @@ 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";
@@ -755,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[];
@@ -794,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;
@@ -1017,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. */
@@ -1180,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;
@@ -1205,6 +1229,8 @@ export declare interface ReportDataTarget {
     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. */
@@ -1214,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 的结果。 */
@@ -1251,6 +1279,46 @@ export declare interface ReportDocumentStyle {
     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 {
     /** Idempotency identity; the server should bind it to the exact payload. */
     requestId: string;
@@ -1286,6 +1354,7 @@ export declare interface ReportEditSession {
 declare interface ReportEditSessionPart {
     template: ReportTemplate;
     datasets: DatasetRows;
+    sourceScope?: string;
 }
 
 export declare interface ReportEditSessionRegistration {
@@ -1376,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;
@@ -1393,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>;
@@ -1802,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;
@@ -2073,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[];
 

package/dist/index.d.ts

@@ -22,6 +22,9 @@ export declare function applyReportDocumentStyle(input: 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>;
@@ -37,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. */
@@ -275,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;
@@ -508,6 +514,19 @@ 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";
@@ -755,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[];
@@ -794,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;
@@ -1017,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. */
@@ -1180,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;
@@ -1205,6 +1229,8 @@ export declare interface ReportDataTarget {
     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. */
@@ -1214,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 的结果。 */
@@ -1251,6 +1279,46 @@ export declare interface ReportDocumentStyle {
     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 {
     /** Idempotency identity; the server should bind it to the exact payload. */
     requestId: string;
@@ -1286,6 +1354,7 @@ export declare interface ReportEditSession {
 declare interface ReportEditSessionPart {
     template: ReportTemplate;
     datasets: DatasetRows;
+    sourceScope?: string;
 }
 
 export declare interface ReportEditSessionRegistration {
@@ -1376,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;
@@ -1393,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>;
@@ -1802,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;
@@ -2073,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[];