@agile-team/mach-report 2.3.2 → 2.4.1

package/dist/vue/async.d.ts

@@ -30,6 +30,29 @@ declare type ColumnFormat =
 | { kind: "percent"; digits?: number }
 | { kind: "date"; pattern?: string };
 
+/**
+ * 列值格式化（声明式、JSON 可序列化）。
+ * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
+ * 三后端（DOM/Canvas/PDF）零改动。
+ *
+ * 语义约定（v0.9 固化）：
+ * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
+ * - number.thousands 默认 false（千分位显式开启）
+ * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
+ *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
+ */
+declare type ColumnFormat_2 = {
+    kind: "number";
+    thousands?: boolean;
+    digits?: number;
+} | {
+    kind: "percent";
+    digits?: number;
+} | {
+    kind: "date";
+    pattern?: string;
+};
+
 declare type ComponentKind =
 | "text"
 | "image"
@@ -40,6 +63,10 @@ declare type ComponentKind =
 | "rect"
 | "ellipse";
 
+declare type ComponentKind_2 = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
+declare type ComponentKind_3 = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
 declare interface ComponentStyle {
     fontSizePx?: number;
     fontSize?: number;
@@ -64,8 +91,136 @@ declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
+declare interface ComponentStyle_2 {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+
+declare interface ComponentStyle_3 {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+
 declare type DatasetRows = Record<string, Record<string, unknown>[]>;
 
+declare interface ExcelImportedSheet {
+    name: string;
+    /** Original, one-based workbook position. */
+    index: number;
+    range: string;
+    rowCount: number;
+    columnCount: number;
+    /** Zero-based index into template.pages. */
+    pageStart: number;
+    pageCount: number;
+}
+
+/** Limits apply to the selected rectangular ranges, including their empty cells. */
+declare interface ExcelImportLimits {
+    /** Compressed input, default 20 MiB. */
+    maxFileBytes?: number;
+    /** Declared ZIP uncompressed total, default 64 MiB. */
+    maxUncompressedBytes?: number;
+    /** Total selected cells across sheets, default 250,000; hard ceiling 1,000,000. */
+    maxCells?: number;
+    /** Rows per selected sheet, default 100,000; hard ceiling 1,048,576. */
+    maxRows?: number;
+    /** Columns per selected sheet, default 2,048; hard ceiling 16,384. */
+    maxColumns?: number;
+    /** Workbook sheets, default 32. */
+    maxSheets?: number;
+}
+
+/** Limits apply to the selected rectangular ranges, including their empty cells. */
+declare interface ExcelImportLimits_2 {
+    /** Compressed input, default 20 MiB. */
+    maxFileBytes?: number;
+    /** Declared ZIP uncompressed total, default 64 MiB. */
+    maxUncompressedBytes?: number;
+    /** Total selected cells across sheets, default 250,000; hard ceiling 1,000,000. */
+    maxCells?: number;
+    /** Rows per selected sheet, default 100,000; hard ceiling 1,048,576. */
+    maxRows?: number;
+    /** Columns per selected sheet, default 2,048; hard ceiling 16,384. */
+    maxColumns?: number;
+    /** Workbook sheets, default 32. */
+    maxSheets?: number;
+}
+
+declare interface ExcelImportOptions {
+    /** Sheet names or one-based workbook positions. Default: all visible sheets. */
+    sheets?: Array<string | number>;
+    /** A1 range for every sheet, or ranges keyed by exact sheet name. */
+    range?: string | Record<string, string>;
+    /** Wide preserves natural column widths. A3/A4 scale the complete width to paper. */
+    layout?: "wide" | "a3" | "a4";
+    /** Only applies to A3/A4; default landscape. */
+    landscape?: boolean;
+    /** Vertical preview segment limit, default 80, maximum 200. Merges remain intact. */
+    maxRowsPerPage?: number;
+    /** Optional resource limits; hard ceilings prevent unbounded allocations. */
+    limits?: ExcelImportLimits;
+}
+
+declare interface ExcelImportOptions_2 {
+    /** Sheet names or one-based workbook positions. Default: all visible sheets. */
+    sheets?: Array<string | number>;
+    /** A1 range for every sheet, or ranges keyed by exact sheet name. */
+    range?: string | Record<string, string>;
+    /** Wide preserves natural column widths. A3/A4 scale the complete width to paper. */
+    layout?: "wide" | "a3" | "a4";
+    /** Only applies to A3/A4; default landscape. */
+    landscape?: boolean;
+    /** Vertical preview segment limit, default 80, maximum 200. Merges remain intact. */
+    maxRowsPerPage?: number;
+    /** Optional resource limits; hard ceilings prevent unbounded allocations. */
+    limits?: ExcelImportLimits_2;
+}
+
+declare interface ExcelImportResult {
+    template: ReportTemplate_2;
+    warnings: string[];
+    sheets: ExcelImportedSheet[];
+}
+
 declare interface GridCell {
     text?: string;
     rawText?: string;
@@ -73,15 +228,62 @@ declare interface GridCell {
     value?: string | number | boolean | null;
     /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
     numberFormat?: string;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
     children?: PlanComponent[];
     colSpan?: number;
     rowSpan?: number;
     style?: ComponentStyle;
 }
 
+declare interface GridCell_2 {
+    text?: string;
+    rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent_2[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle_2;
+}
+
+declare interface GridCell_3 {
+    text?: string;
+    rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent_3[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle_3;
+}
+
 /** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
 declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
 
+/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
+declare type ListAlignment_2 = NonNullable<ComponentStyle_3["align"]> | "auto";
+
 declare interface ListColumn {
     header: string;
     field: string;
@@ -97,6 +299,31 @@ declare interface ListColumn {
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule[];
+    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
+    editable?: boolean;
+    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
+    valueType?: GridCell["valueType"];
+}
+
+declare interface ListColumn_2 {
+    header: string;
+    field: string;
+    widthMm: number;
+    style?: ComponentStyle_3;
+    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
+    align?: ListAlignment_2;
+    /** 独立的表头对齐，不改变内容对齐。 */
+    headerAlign?: ComponentStyle_3["align"];
+    /** 独立的表头样式，优先于列表级表头样式。 */
+    headerStyle?: ComponentStyle_3;
+    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
+    format?: ColumnFormat_2;
+    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
+    rules?: StyleRule_2[];
+    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
+    editable?: boolean;
+    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
+    valueType?: GridCell_3["valueType"];
 }
 
 declare interface ListComponent {
@@ -129,6 +356,36 @@ declare interface ListComponent {
     grandTotal?: ListGrandTotal;
 }
 
+declare interface ListComponent_2 {
+    kind: "list";
+    id?: string;
+    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
+    layout?: "page" | "wide";
+    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
+    title?: string;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    dataset: string;
+    columns: ListColumn_2[];
+    fontSizePt?: number;
+    headerBold?: boolean;
+    rowHeightMm?: number;
+    paddingMm?: number;
+    headerEveryPage?: boolean;
+    headerBackgroundColor?: string;
+    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
+    align?: ListAlignment_2;
+    /** 表头默认对齐，列配置可覆盖。 */
+    headerAlign?: ComponentStyle_3["align"];
+    headerStyle?: ComponentStyle_3;
+    border?: boolean;
+    /** 分组小计（组头/组尾小计/组头防孤行） */
+    groupBy?: ListGroupBy_2;
+    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
+    grandTotal?: ListGrandTotal_2;
+}
+
 declare type ListGrandTotal =
 | boolean
 | {
@@ -138,6 +395,13 @@ declare type ListGrandTotal =
     fields?: string[];
 };
 
+declare type ListGrandTotal_2 = boolean | {
+    label?: string;
+    style?: ComponentStyle_3;
+    /** 合计列（缺省沿用 groupBy.subtotal） */
+    fields?: string[];
+};
+
 /** 分组小计配置（声明式，见 ListComponent.groupBy） */
 declare interface ListGroupBy {
     /** 分组字段（值变化即切组） */
@@ -153,6 +417,21 @@ declare interface ListGroupBy {
     keepWithNext?: boolean;
 }
 
+/** 分组小计配置（声明式，见 ListComponent.groupBy） */
+declare interface ListGroupBy_2 {
+    /** 分组字段（值变化即切组） */
+    field: string;
+    /** 组头文案模板，{value} 占位（默认 "{value}"） */
+    headerTemplate?: string;
+    headerStyle?: ComponentStyle_3;
+    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
+    subtotal?: string[];
+    subtotalStyle?: ComponentStyle_3;
+    subtotalLabel?: string;
+    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
+    keepWithNext?: boolean;
+}
+
 declare const machReportAsyncPlugin: {
     install(app: App, options?: MachReportPluginOptions): void;
 };
@@ -184,13 +463,17 @@ declare interface MachReportDefaults {
     preview?: MachReportPreviewOptions;
     /** Excel 出口配置，按字段继承；不配置使用导出器默认值。 */
     xlsx?: XlsxRenderOptions;
+    /** 默认关闭；true 为本地草稿，对象可提供权限、校验和保存回调。 */
+    editable?: boolean | ReportEditingOptions;
+    /** 默认关闭；启用后提供导入按钮。ExcelJS 仅在导入时加载。 */
+    excelImport?: boolean | ExcelImportOptions;
 }
 
 /**
  * 结构化错误（code 分类，宿主可按码决定 UX：重试 / 提示 / 降级）。
  * error 事件契约保持 `(message: string)` 不变，新增第二参数 detail（可选）。
  */
-declare type MachReportErrorCode = "param" | "fetch" | "validate" | "render" | "pdf" | "print" | "export" | "config";
+declare type MachReportErrorCode = "param" | "fetch" | "validate" | "render" | "pdf" | "print" | "export" | "edit" | "import" | "config";
 
 /** 日志通道（默认 console；可注入 noop 静默或上报 collector） */
 declare type MachReportLogger = Pick<Console, "warn" | "info">;
@@ -242,6 +525,14 @@ declare interface MachReportMessages {
     paramRequired: string;
     /** 可选搜索进度文案，旧完整 messages 对象无需新增字段。 */
     searching?: string;
+    importExcel?: string;
+    importing?: string;
+    editCell?: string;
+    editingHint?: string;
+    saving?: string;
+    editInvalidNumber?: string;
+    editInvalidBoolean?: string;
+    editConflict?: string;
 }
 
 declare interface MachReportPluginOptions {
@@ -319,6 +610,14 @@ export declare const MachReportPreview: {
     type: BooleanConstructor;
     default: undefined;
     };
+    editable: {
+    type: PropType<boolean | ReportEditingOptions>;
+    default: undefined;
+    };
+    excelImport: {
+    type: PropType<boolean | ExcelImportOptions_2>;
+    default: undefined;
+    };
     fetcher: {
     type: PropType<PlanFetcher | null>;
     default: null;
@@ -330,6 +629,8 @@ export declare const MachReportPreview: {
     } | undefined) => any) | undefined;
     onLoaded?: ((pageCount: number) => any) | undefined;
     onWarning?: ((message: string) => any) | undefined;
+    "onCell-edit"?: ((edit: ReportCellEdit_2) => any) | undefined;
+    "onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
     }>, {
     reload: () => Promise<void>;
     print: () => Promise<void>;
@@ -340,6 +641,9 @@ export declare const MachReportPreview: {
     reload?: boolean;
     }) => Promise<void>;
     checkPdfFont: () => Promise<PdfFontCheckResult>;
+    importExcel: (input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2) => Promise<ExcelImportResult | null>;
+    getPlan: () => RenderPlan | null;
+    getChanges: () => ReportCellEdit_2[];
     state: ComputedRef<MachReportState>;
     }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
     error: (message: string, detail?: {
@@ -348,7 +652,10 @@ export declare const MachReportPreview: {
     } | undefined) => any;
     loaded: (pageCount: number) => any;
     warning: (message: string) => any;
+    "cell-edit": (edit: ReportCellEdit_2) => any;
+    "template-import": (result: ExcelImportResult) => any;
     }, PublicProps, {
+    editable: boolean | ReportEditingOptions;
     height: string;
     gapPx: number;
     params: Record<string, string>;
@@ -359,11 +666,13 @@ export declare const MachReportPreview: {
     showPdfWindow: boolean;
     showParams: boolean;
     messages: Partial<MachReportMessages>;
+    excelImport: boolean | ExcelImportOptions_2;
     autoLoad: boolean;
     preset: string;
     paramDefs: ReportParamDef[] | undefined;
     fetcher: PlanFetcher | null;
     }, true, {}, {}, { [K in keyof GlobalComponents]: GlobalComponents[K] }, { [K in keyof GlobalDirectives]: GlobalDirectives[K] }, string, {
+    importInputRef: HTMLInputElement;
     viewportRef: HTMLDivElement;
     containerRef: HTMLDivElement;
     thumbsRef: HTMLElement;
@@ -427,6 +736,14 @@ export declare const MachReportPreview: {
     type: BooleanConstructor;
     default: undefined;
     };
+    editable: {
+    type: PropType<boolean | ReportEditingOptions>;
+    default: undefined;
+    };
+    excelImport: {
+    type: PropType<boolean | ExcelImportOptions_2>;
+    default: undefined;
+    };
     fetcher: {
     type: PropType<PlanFetcher | null>;
     default: null;
@@ -438,6 +755,8 @@ export declare const MachReportPreview: {
     } | undefined) => any) | undefined;
     onLoaded?: ((pageCount: number) => any) | undefined;
     onWarning?: ((message: string) => any) | undefined;
+    "onCell-edit"?: ((edit: ReportCellEdit_2) => any) | undefined;
+    "onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
     }>, {
     reload: () => Promise<void>;
     print: () => Promise<void>;
@@ -448,8 +767,12 @@ export declare const MachReportPreview: {
     reload?: boolean;
     }) => Promise<void>;
     checkPdfFont: () => Promise<PdfFontCheckResult>;
+    importExcel: (input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2) => Promise<ExcelImportResult | null>;
+    getPlan: () => RenderPlan | null;
+    getChanges: () => ReportCellEdit_2[];
     state: ComputedRef<MachReportState>;
     }, {}, {}, {}, {
+    editable: boolean | ReportEditingOptions;
     height: string;
     gapPx: number;
     params: Record<string, string>;
@@ -460,6 +783,7 @@ export declare const MachReportPreview: {
     showPdfWindow: boolean;
     showParams: boolean;
     messages: Partial<MachReportMessages>;
+    excelImport: boolean | ExcelImportOptions_2;
     autoLoad: boolean;
     preset: string;
     paramDefs: ReportParamDef[] | undefined;
@@ -521,6 +845,14 @@ showParams: {
 type: BooleanConstructor;
 default: undefined;
 };
+editable: {
+type: PropType<boolean | ReportEditingOptions>;
+default: undefined;
+};
+excelImport: {
+type: PropType<boolean | ExcelImportOptions_2>;
+default: undefined;
+};
 fetcher: {
 type: PropType<PlanFetcher | null>;
 default: null;
@@ -532,6 +864,8 @@ cause?: unknown;
 } | undefined) => any) | undefined;
 onLoaded?: ((pageCount: number) => any) | undefined;
 onWarning?: ((message: string) => any) | undefined;
+"onCell-edit"?: ((edit: ReportCellEdit_2) => any) | undefined;
+"onTemplate-import"?: ((result: ExcelImportResult) => any) | undefined;
 }>, {
 reload: () => Promise<void>;
 print: () => Promise<void>;
@@ -542,6 +876,9 @@ setParams: (values: Record<string, string>, opts?: {
 reload?: boolean;
 }) => Promise<void>;
 checkPdfFont: () => Promise<PdfFontCheckResult>;
+importExcel: (input: ArrayBuffer | Uint8Array | Blob, options?: ExcelImportOptions_2) => Promise<ExcelImportResult | null>;
+getPlan: () => RenderPlan | null;
+getChanges: () => ReportCellEdit_2[];
 state: ComputedRef<MachReportState>;
 }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 error: (message: string, detail?: {
@@ -550,7 +887,10 @@ cause?: unknown;
 } | undefined) => any;
 loaded: (pageCount: number) => any;
 warning: (message: string) => any;
+"cell-edit": (edit: ReportCellEdit_2) => any;
+"template-import": (result: ExcelImportResult) => any;
 }, string, {
+editable: boolean | ReportEditingOptions;
 height: string;
 gapPx: number;
 params: Record<string, string>;
@@ -561,6 +901,7 @@ showPrint: boolean;
 showPdfWindow: boolean;
 showParams: boolean;
 messages: Partial<MachReportMessages>;
+excelImport: boolean | ExcelImportOptions_2;
 autoLoad: boolean;
 preset: string;
 paramDefs: ReportParamDef[] | undefined;
@@ -592,6 +933,10 @@ declare interface MachReportState {
     readonly canPrint: boolean;
     readonly error: Readonly<MachReportStateError> | null;
     readonly pdfFont: Readonly<PdfFontCheckResult>;
+    readonly editing?: boolean;
+    readonly saving?: boolean;
+    readonly importing?: boolean;
+    readonly dirty?: boolean;
 }
 
 declare interface MachReportStateError {
@@ -659,6 +1004,48 @@ declare interface PlanComponent {
     fallbackText?: string;
 }
 
+declare interface PlanComponent_2 {
+    kind: ComponentKind_2;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph_2[];
+    imageData?: string;
+    grid?: PlanGrid_2;
+    table?: PlanTableFragment_2;
+    style?: ComponentStyle_2;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+
+declare interface PlanComponent_3 {
+    kind: ComponentKind_3;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph_3[];
+    imageData?: string;
+    grid?: PlanGrid_3;
+    table?: PlanTableFragment_3;
+    style?: ComponentStyle_3;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+
 declare interface PlanFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
     getParamDefs?: ReportFetcher["getParamDefs"];
@@ -674,6 +1061,26 @@ declare interface PlanGrid {
     paddingMm?: number;
 }
 
+declare interface PlanGrid_2 {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell_2 | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+
+declare interface PlanGrid_3 {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell_3 | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+
 declare interface PlanPage {
     /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
     layout?: "page" | "wide";
@@ -699,6 +1106,32 @@ declare interface PlanTableFragment {
     title?: string;
 }
 
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment_2 {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+}
+
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment_3 {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+}
+
 /** 预取组件分片（路由 hover / 空闲时调用，正式渲染零等待） */
 export declare function preloadMachReport(): Promise<unknown>;
 
@@ -707,6 +1140,75 @@ declare interface RenderPlan {
     pages: PlanPage[];
 }
 
+/** 预览中的物理坐标；合并单元格使用左上角坐标。 */
+declare interface ReportCellAddress {
+    pageIndex: number;
+    componentIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+}
+
+/** 预览中的物理坐标；合并单元格使用左上角坐标。 */
+declare interface ReportCellAddress_2 {
+    pageIndex: number;
+    componentIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+}
+
+declare interface ReportCellContext {
+    address: ReportCellAddress;
+    cell: Readonly<GridCell_2>;
+    component: Readonly<PlanComponent_2>;
+    value: ReportCellValue;
+    valueType: ReportCellValueType;
+    table?: ReportCellTableIdentity;
+    editable: boolean;
+    readOnlyReason?: ReportCellReadOnlyReason;
+}
+
+declare interface ReportCellEdit {
+    address: ReportCellAddress;
+    table?: ReportCellTableIdentity;
+    previousValue: ReportCellValue;
+    previousText: string;
+    value: ReportCellValue;
+    text: string;
+}
+
+declare interface ReportCellEdit_2 {
+    address: ReportCellAddress_2;
+    table?: ReportCellTableIdentity_2;
+    previousValue: ReportCellValue_2;
+    previousText: string;
+    value: ReportCellValue_2;
+    text: string;
+}
+
+declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
+
+declare interface ReportCellTableIdentity {
+    id: string;
+    /** 逻辑表行索引；跨分页的同一行保持不变。 */
+    rowIndex: number;
+    role: PlanTableFragment_2["role"];
+    columnKey?: string;
+}
+
+declare interface ReportCellTableIdentity_2 {
+    id: string;
+    /** 逻辑表行索引；跨分页的同一行保持不变。 */
+    rowIndex: number;
+    role: PlanTableFragment["role"];
+    columnKey?: string;
+}
+
+declare type ReportCellValue = string | number | boolean | null;
+
+declare type ReportCellValue_2 = string | number | boolean | null;
+
+declare type ReportCellValueType = NonNullable<GridCell_2["valueType"]>;
+
 declare interface ReportDefinition {
     /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
     template: ReportTemplate | ReportTemplateLoader;
@@ -718,6 +1220,20 @@ declare interface ReportDefinition {
     pagination?: PaginateOptions;
 }
 
+/** Opt in with true for local drafts, or provide host validation and persistence. */
+declare interface ReportEditingOptions {
+    canEdit?(context: ReportCellContext): boolean;
+    /** Return an error message or throw to reject the edit. */
+    validate?(edit: Readonly<ReportCellEdit>, operation: ReportEditOperation): void | string | Promise<void | string>;
+    /** Called before applying the change. A rejection leaves the current report untouched. */
+    save?(edit: Readonly<ReportCellEdit>, operation: ReportEditOperation): void | Promise<void>;
+}
+
+declare interface ReportEditOperation {
+    /** Reload, another import or unmount aborts the operation. Save adapters should forward this signal. */
+    signal: AbortSignal;
+}
+
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
@@ -753,6 +1269,23 @@ declare interface ReportParamDef {
     placeholder?: string;
 }
 
+/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
+declare interface ReportParamDef_2 {
+    /** 参数名（传入 params，与数据集 SQL #{field} 绑定对应） */
+    field: string;
+    /** 显示名（缺省用 field） */
+    label?: string;
+    type?: "text" | "number" | "date" | "select";
+    /** select 选项 */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    defaultValue?: string;
+    required?: boolean;
+    placeholder?: string;
+}
+
 declare type ReportRegistry = Record<string, ReportDefinition>;
 
 declare interface ReportTemplate {
@@ -762,6 +1295,13 @@ declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+declare interface ReportTemplate_2 {
+    schemaVersion?: string;
+    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
+    params?: ReportParamDef_2[];
+    pages: TemplatePage_2[];
+}
+
 declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
 
 declare interface RichParagraph {
@@ -773,6 +1313,24 @@ declare interface RichParagraph {
     indentMm?: number;
 }
 
+declare interface RichParagraph_2 {
+    segments: RichSegment_2[];
+    align?: ComponentStyle_2["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+
+declare interface RichParagraph_3 {
+    segments: RichSegment_3[];
+    align?: ComponentStyle_3["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+
 declare interface RichSegment {
     kind?: "text" | "field";
     text?: string;
@@ -780,6 +1338,20 @@ declare interface RichSegment {
     style?: ComponentStyle;
 }
 
+declare interface RichSegment_2 {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle_2;
+}
+
+declare interface RichSegment_3 {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle_3;
+}
+
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 declare interface StyleRule {
     when: {
@@ -791,8 +1363,21 @@ declare interface StyleRule {
     style: Record<string, unknown>;
 }
 
+/** 条件格式规则求值（声明式，见 ListColumn.rules） */
+declare interface StyleRule_2 {
+    when: {
+        field: string;
+        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
+        value: number | string;
+    };
+    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
+    style: Record<string, unknown>;
+}
+
 declare type TemplateComponent = PlanComponent | ListComponent;
 
+declare type TemplateComponent_2 = PlanComponent_3 | ListComponent_2;
+
 declare interface TemplatePage {
     widthMm: number;
     heightMm: number;
@@ -805,6 +1390,18 @@ declare interface TemplatePage {
     components: TemplateComponent[];
 }
 
+declare interface TemplatePage_2 {
+    widthMm: number;
+    heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: TemplateComponent_2[];
+}
+
 /**
  * 文本测量与折行（分页/Canvas/PDF 共用的唯一折行真相源）。
  *