@agile-team/mach-report 2.21.1 → 2.23.0

package/dist/vue/index.d.cts

@@ -71,6 +71,10 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
         type: PropType<ReportPreferencesOptions>;
         default: undefined;
     };
+    refresh: {
+        type: PropType<ReportRefreshOptions>;
+        default: undefined;
+    };
     guardChanges: {
         type: BooleanConstructor;
         default: undefined;
@@ -253,6 +257,10 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
         type: PropType<ReportPreferencesOptions>;
         default: undefined;
     };
+    refresh: {
+        type: PropType<ReportRefreshOptions>;
+        default: undefined;
+    };
     guardChanges: {
         type: BooleanConstructor;
         default: undefined;
@@ -358,6 +366,7 @@ declare const __VLS_component: DefineComponent<ExtractPropTypes<{
     toolbar: MachReportToolbarOptions;
     interaction: ReportInteractionOptions;
     preferences: ReportPreferencesOptions;
+    refresh: ReportRefreshOptions;
     guardChanges: boolean;
     beforeDiscard: ReportBeforeDiscard;
     messages: Partial<MachReportMessages>;
@@ -468,8 +477,30 @@ declare type __VLS_Props_6 = {
     state: ReportDataComparisonState;
     messages: ReportDataReviewMessages;
 };
+declare type __VLS_Props_7 = {
+    messages: MachReportMessages;
+    formats?: readonly ReportExportFormat[];
+    busy?: boolean;
+    /** 宿主附加出口仍复用菜单的焦点、键盘与忙碌行为。 */
+    actions?: readonly {
+        id: string;
+        label: string;
+        description?: string;
+        disabled?: boolean;
+    }[];
+};
+declare type __VLS_Props_8 = {
+    task: Readonly<ReportPreviewTask> | null;
+    messages?: MachReportMessages;
+};
 declare function __VLS_template(): {
     slots: {
+        export?(_: {
+            busy: boolean;
+            exportReport: (format: string) => Promise<void>;
+            formats: ReportExportFormat[];
+            messages: MachReportMessages;
+        }): any;
         settings?(_: {}): any;
         default?(_: {}): any;
     };
@@ -479,6 +510,11 @@ declare function __VLS_template_2(): {
     slots: {
         navigation?(_: {}): any;
         'data-tools'?(_: {}): any;
+        export?(_: {
+            messages: MachReportMessages;
+            formats: readonly ReportExportFormat[];
+            busy: boolean | undefined;
+        }): any;
     };
     refs: {
         searchToggleRef: HTMLButtonElement;
@@ -921,7 +957,7 @@ export declare function createProviderEditing(provider: ReportProvider, options:
 export declare function createReportStoragePreferences(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">): ReportPreferencesAdapter;
 declare type Current<T> = T | (() => T);
 declare interface DatasetContract {
-    fields: readonly ReportFieldContract[];
+    fields: readonly ReportFieldContract_2[];
     rowKey?: string;
 }
 declare type DatasetRows = Record<string, Record<string, unknown>[]>;
@@ -1638,6 +1674,7 @@ export declare interface MachReportDefaults {
     toolbar?: MachReportToolbarOptions;
     interaction?: ReportInteractionOptions;
     preferences?: ReportPreferencesOptions;
+    refresh?: ReportRefreshOptions;
     /** Protect local input and drafts before replacing a report. Default true. */
     guardChanges?: boolean;
     beforeDiscard?: ReportBeforeDiscard;
@@ -1717,6 +1754,7 @@ export declare type MachReportLogger = Pick<Console, "warn" | "info">;
  */
 /** 工具栏与状态文案（默认简体中文；出海场景覆写） */
 export declare interface MachReportMessages extends Partial<ReportCalculationMessages>, Partial<ReportDataReviewMessages>, ReportPrintMessages, ReportParamOptionsMessages {
+    previousSnapshot?: string;
     reviewTools?: string;
     validationTitle?: string;
     validationError?: string;
@@ -1809,6 +1847,20 @@ export declare interface MachReportMessages extends Partial<ReportCalculationMes
     importing?: string;
     editCell?: string;
     editingHint?: string;
+    editCellEditable?: string;
+    editCellReadOnly?: string;
+    editCellFormula?: string;
+    editCellProtected?: string;
+    editCellComplex?: string;
+    editCellStructure?: string;
+    editCellDerived?: string;
+    editCellPermission?: string;
+    editCellBusy?: string;
+    editHistoryLimited?: string;
+    changesSearch?: string;
+    changesAllDatasets?: string;
+    changesNoMatches?: string;
+    changesRange?: string;
     saving?: string;
     editInvalidNumber?: string;
     editInvalidBoolean?: string;
@@ -1938,6 +1990,8 @@ export declare interface MachReportPreviewOptions {
 /** 只读快照，由组件的同一套状态驱动；无需通过事件另建状态。 */
 export declare interface MachReportState {
     readonly loading: boolean;
+    /** A retained previous snapshot is readable while writes/output remain blocked. */
+    readonly stale?: boolean;
     readonly hasPlan: boolean;
     readonly pageCount: number;
     readonly currentPage: number;
@@ -1984,6 +2038,8 @@ export declare interface MachReportTheme {
     btnActiveBg: string;
 }
 export declare interface MachReportToolbarOptions {
+    /** Reasons explain host restrictions without granting capabilities. */
+    unavailableReasons?: Partial<Record<ReportPreviewTool, string>>;
     search?: boolean;
     thumbnails?: boolean;
     zoom?: boolean;
@@ -2444,7 +2500,7 @@ export declare function printPlans(plans: RenderPlan_2[], options?: {
  * 同名 preset 与 messages/theme 均按字段继承；组件 props 仍拥有最高优先级。
  */
 export declare function provideMachReportConfig(overlay: MachReportConfigInput | MachReportDefaults): void;
-export declare interface ProviderEditingOptions extends Pick<ReportEditingOptions, "canEdit" | "validate" | "requireSource"> {
+export declare interface ProviderEditingOptions extends Pick<ReportEditingOptions, "canEdit" | "readOnlyReason" | "history" | "fields" | "validate" | "validation" | "validateBatch" | "requireSource"> {
     reportId: Current<string>;
     params?: Current<Record<string, string>>;
     /** Getters are useful when query metadata is held by the host. Otherwise stable cell sources are used. */
@@ -3010,11 +3066,21 @@ declare interface ReportEditConflict {
     currentValue?: ReportCellValue;
     revision?: string | number;
 }
+export declare interface ReportEditHistoryOptions {
+    /** Retained undo/redo transactions. Default 100. Zero disables undo retention. */
+    maxSteps?: number;
+    /** Conservative retained transaction size in bytes. Default 8 MiB. */
+    maxBytes?: number;
+}
 /** Opt in with true for local drafts, or provide host validation and persistence. */
 export declare interface ReportEditingOptions {
     /** Optional field controls, keyed by source.field / table.columnKey; a resolver supports dataset-specific rules. */
     fields?: Readonly<Record<string, ReportCellFieldOptions>> | ((context: ReportCellContext) => ReportCellFieldOptions | undefined);
     canEdit?(context: ReportCellContext): boolean;
+    /** Optional explanation when canEdit rejects a cell. Does not grant editing access. */
+    readOnlyReason?(context: ReportCellContext): string | undefined;
+    /** Bounds undo/redo retention. Net differences and getChanges remain complete. */
+    history?: ReportEditHistoryOptions;
     /** Return an error message or throw to reject the edit. */
     validate?(edit: Readonly<ReportCellEdit>, operation: ReportEditOperation): void | string | Promise<void | string>;
     /** Same declarative rules can be run in Node via validateReportDataset. Requires a source-backed session. */
@@ -3071,6 +3137,13 @@ export declare interface ReportExportExecutionOptions {
 }
 /** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
 export declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
+export declare const ReportExportMenu: DefineComponent<__VLS_Props_7, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+    export: (format: ReportExportFormat) => any;
+    action: (id: string) => any;
+}, string, MachReportVuePublicProps, Readonly<__VLS_Props_7> & Readonly<{
+    onExport?: ((format: ReportExportFormat) => any) | undefined;
+    onAction?: ((id: string) => any) | undefined;
+}>, {}>;
 export declare interface ReportExportThresholds {
     cells?: number;
     pages?: number;
@@ -3136,11 +3209,23 @@ declare interface ReportFetchInput extends ReportTaskMonitoring {
     onQueryResult?: (reportId: string, result: ReportQueryResult, reportIndex?: number) => void;
 }
 declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
+declare type ReportFieldAggregation_2 = "sum" | "avg" | "min" | "max" | "count" | "none";
+declare type ReportFieldAggregation_3 = "sum" | "avg" | "min" | "max" | "count" | "none";
 declare interface ReportFieldCalculation {
     /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
     description: string;
     dependsOn: readonly string[];
 }
+declare interface ReportFieldCalculation_2 {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
+declare interface ReportFieldCalculation_3 {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
 declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
@@ -3155,6 +3240,34 @@ declare interface ReportFieldContract extends ReportFieldSemantics {
     semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
     unit?: string;
 }
+declare interface ReportFieldContract_2 extends ReportFieldSemantics_2 {
+    field: string;
+    label?: string;
+    type: "text" | "number" | "boolean" | "date" | "decimal";
+    required?: boolean;
+    nullable?: boolean;
+    enum?: readonly (string | number | boolean)[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    unit?: string;
+}
+declare interface ReportFieldContract_3 extends ReportFieldSemantics_3 {
+    field: string;
+    label?: string;
+    type: "text" | "number" | "boolean" | "date" | "decimal";
+    required?: boolean;
+    nullable?: boolean;
+    enum?: readonly (string | number | boolean)[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+    unit?: string;
+}
 declare interface ReportFieldSemantics {
     description?: string;
     /** Explicit meaning of null/missing; does not convert blanks into zero. */
@@ -3162,9 +3275,29 @@ declare interface ReportFieldSemantics {
     /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
     aggregation?: ReportFieldAggregation;
     /** Shared presentation only; raw values and calculation precision remain unchanged. */
-    format?: ColumnFormat;
+    format?: ColumnFormat_2;
     calculation?: ReportFieldCalculation;
 }
+declare interface ReportFieldSemantics_2 {
+    description?: string;
+    /** Explicit meaning of null/missing; does not convert blanks into zero. */
+    missingMeaning?: string;
+    /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
+    aggregation?: ReportFieldAggregation_2;
+    /** Shared presentation only; raw values and calculation precision remain unchanged. */
+    format?: ColumnFormat;
+    calculation?: ReportFieldCalculation_2;
+}
+declare interface ReportFieldSemantics_3 {
+    description?: string;
+    /** Explicit meaning of null/missing; does not convert blanks into zero. */
+    missingMeaning?: string;
+    /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
+    aggregation?: ReportFieldAggregation_3;
+    /** Shared presentation only; raw values and calculation precision remain unchanged. */
+    format?: ColumnFormat_3;
+    calculation?: ReportFieldCalculation_3;
+}
 export declare interface ReportFieldTarget {
     field: string;
     datasetId?: string;
@@ -3422,8 +3555,8 @@ declare type ReportPredicateScalar = string | number | boolean | null;
 declare type ReportPredicateScalar_2 = string | number | boolean | null;
 declare type ReportPredicateScalar_3 = string | number | boolean | null;
 export declare interface ReportPreferencesAdapter {
-    load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
-    save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
+    load(key: string): ReportStoredPreferences | null | Promise<ReportStoredPreferences | null>;
+    save(key: string, value: Readonly<ReportStoredPreferences>): void | Promise<void>;
     remove?(key: string): void | Promise<void>;
 }
 export declare interface ReportPreferencesOptions {
@@ -3553,6 +3686,17 @@ declare interface ReportQueryResult {
     sourceToken?: string;
     diagnostics?: ReportDiagnostic[];
 }
+/** Explicit refresh policy. The key identifies template/layout revisions outside query parameters. */
+export declare interface ReportRefreshOptions {
+    retainPrevious?: boolean;
+    key?: string;
+    /** Host API request preceding the preview reload. Blocks edits and output without discarding drafts. */
+    pending?: boolean;
+    /** The host retained an earlier snapshot after its own query failed or was cancelled. */
+    stale?: boolean;
+    /** Retry the host HTTP query when it owns the stale snapshot. The host updates its own state. */
+    retry?(): void | Promise<void>;
+}
 declare type ReportRegistry = Record<string, ReportDefinition>;
 declare interface ReportRuntimeBudget {
     maxRows?: number;
@@ -3586,6 +3730,10 @@ export declare interface ReportSection {
     label: string;
     pageIndex: number;
 }
+export declare interface ReportStoredPreferences extends Partial<ReportPreviewPreferences> {
+    zoomMode?: "fit" | number;
+    wideZoomMode?: "fit" | number;
+}
 /** 阶段事件只包含可序列化值；不表示估算百分比，也不包含业务数据。 */
 declare interface ReportTaskEvent {
     taskId: string;
@@ -3602,8 +3750,17 @@ declare interface ReportTaskMonitoring {
     onEvent?: ReportTaskObserver;
 }
 declare type ReportTaskObserver = (event: ReportTaskEvent) => void;
+export declare const ReportTaskStatus: DefineComponent<__VLS_Props_8, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+    cancel: () => any;
+}, string, MachReportVuePublicProps, Readonly<__VLS_Props_8> & Readonly<{
+    onCancel?: (() => any) | undefined;
+}>, {
+    messages: MachReportMessages;
+}>;
 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_2[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -3612,6 +3769,8 @@ declare interface ReportTemplate {
 }
 declare interface ReportTemplate_2 {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract_2;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef[];
     /** Fixed label pages repeat in record → copy → template-page order. */
@@ -3620,12 +3779,35 @@ declare interface ReportTemplate_2 {
 }
 declare interface ReportTemplate_3 {
     schemaVersion?: string;
+    /** Optional source identity and stable field meanings for safe stored-template reuse. */
+    dataContract?: ReportTemplateDataContract_3;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef_3[];
     /** Fixed label pages repeat in record → copy → template-page order. */
     repeat?: ReportTemplateRepeat_3;
     pages: TemplatePage_3[];
 }
+declare interface ReportTemplateDataContract {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding[];
+    }>>;
+}
+declare interface ReportTemplateDataContract_2 {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding_2[];
+    }>>;
+}
+declare interface ReportTemplateDataContract_3 {
+    /** Host-owned report/domain identity, without a query date or tenant credentials. */
+    source?: string;
+    datasets: Readonly<Record<string, {
+        fields: readonly ReportTemplateFieldBinding_3[];
+    }>>;
+}
 /** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
 declare interface ReportTemplateDocument {
     schemaVersion: "1.0";
@@ -3636,6 +3818,30 @@ declare interface ReportTemplateDocument {
     description?: string;
     template: ReportTemplate_2;
 }
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract["type"];
+    unit?: string;
+}
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding_2 {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract_2["type"];
+    unit?: string;
+}
+/** Stable business meaning is independent of a column's position and editable caption. */
+declare interface ReportTemplateFieldBinding_3 {
+    field: string;
+    label?: string;
+    semanticKey?: string;
+    type?: ReportFieldContract_3["type"];
+    unit?: string;
+}
 declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate_2 | Promise<ReportTemplate_2>;
 declare interface ReportTemplateProvider {
     list(context: {
@@ -3728,6 +3934,7 @@ export declare type ResolvedConfig = Required<Pick<MachReportDefaults, "showExpo
     toolbar: MachReportToolbarOptions;
     interaction: ReportInteractionOptions;
     preferences?: ReportPreferencesOptions;
+    refresh?: ReportRefreshOptions;
     assets?: AssetRenderOptions;
     guardChanges: boolean;
     beforeDiscard?: ReportBeforeDiscard;
@@ -4011,6 +4218,12 @@ declare type ValueFormat = ColumnFormat;
 declare type ValueFormat_2 = ColumnFormat_2;
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat_3 = ColumnFormat_3;
+/** 可序列化的附加工作表在编码前写入，浏览器与 Worker 共用同一声明。 */
+declare interface XlsxAdditionalSheet {
+    name: string;
+    rows: readonly (readonly (string | number | boolean | null)[])[];
+    columnWidths?: readonly number[];
+}
 declare type XlsxImageOptions = ImageMediaOptions_2;
 /**
  * RenderPlan → xlsx 导出（B 端第二出口，对齐家族 @agile-team/mach-table-xlsx 路线）：
@@ -4023,6 +4236,8 @@ declare type XlsxImageOptions = ImageMediaOptions_2;
 declare interface XlsxRenderOptions extends AssetRenderOptions_2, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
+    /** 可序列化命名，用于 Worker；未提供的项沿用默认名称。 */
+    sheetNames?: readonly string[];
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
     sheetMode?: "auto" | "pages" | "continuous";
     /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
@@ -4031,6 +4246,8 @@ declare interface XlsxRenderOptions extends AssetRenderOptions_2, XlsxImageOptio
     maxDataBars?: number;
     /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
     paperSize?: "auto" | "a3" | "a4" | "a5";
+    /** 在最终编码前追加说明、审计等标量工作表，可直接交给 Worker。 */
+    additionalSheets?: readonly XlsxAdditionalSheet[];
 }
 export {};