@agile-team/mach-report 2.6.1 → 2.7.0

package/dist/designer.d.cts

@@ -1,753 +1,869 @@
-import { ComponentOptionsMixin } from 'vue';
-import { ComponentProvideOptions } from 'vue';
-import { DefineComponent } from 'vue';
-import { PublicProps } from 'vue';
-
-declare interface AssetRenderBudget {
-    /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
-    maxAssets?: number;
-    /** Maximum image payload bytes per new asset, default 32 MiB. */
-    maxImageBytes?: number;
-    /** Maximum total image payload bytes for new assets, default 128 MiB. */
-    maxTotalImageBytes?: number;
-    /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
-    maxDurationMs?: number;
-}
-
-declare interface AssetRenderOptions extends OutputDiagnosticOptions {
-    assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
-    assetBudget?: AssetRenderBudget;
-    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
-    assetFailure?: "throw" | "placeholder";
-    signal?: AbortSignal;
-}
-
-/**
- * 列值格式化（声明式、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 =
-| { kind: "number"; thousands?: boolean; digits?: number }
-| { kind: "percent"; digits?: number }
-| { kind: "date"; pattern?: string };
-
-declare interface ComponentImageContext {
-    readonly component: Readonly<PlanComponent>;
-    readonly pageIndex: number;
-    readonly componentIndex: number;
-    readonly componentPath: readonly number[];
-    readonly signal: AbortSignal;
-}
-
-declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
-
-declare type ComponentKind =
-| "text"
-| "image"
-| "barcode"
-| "qrcode"
-| "chart"
-| "line"
-| "rect"
-| "ellipse";
-
-declare interface ComponentStyle {
-    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>[]>;
-
-/** 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;
-}
-
-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 GridCell {
-    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;
-    source?: ReportCellSource;
-    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
-    formula?: string;
-    children?: PlanComponent[];
-    colSpan?: number;
-    rowSpan?: number;
-    style?: ComponentStyle;
-}
-
-declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
-
-/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
-declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
-
-declare interface ListColumn {
-    header: string;
-    field: string;
-    widthMm: number;
-    style?: ComponentStyle;
-    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
-    align?: ListAlignment;
-    /** 独立的表头对齐，不改变内容对齐。 */
-    headerAlign?: ComponentStyle["align"];
-    /** 独立的表头样式，优先于列表级表头样式。 */
-    headerStyle?: ComponentStyle;
-    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
-    format?: ColumnFormat;
-    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
-    rules?: StyleRule[];
-    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
-    editable?: boolean;
-    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
-    valueType?: GridCell["valueType"];
-    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
-    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
-}
-
-declare interface ListComponent {
-    kind: "list";
-    id?: string;
-    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
-    layout?: "page" | "wide";
-    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
-    title?: string;
-    leftMm: number;
-    topMm: number;
-    widthMm: number;
-    dataset: string;
-    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
-    rowKey?: string;
-    revisionField?: string;
-    sourceTokenField?: string;
-    columns: ListColumn[];
-    fontSizePt?: number;
-    headerBold?: boolean;
-    rowHeightMm?: number;
-    paddingMm?: number;
-    headerEveryPage?: boolean;
-    headerBackgroundColor?: string;
-    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
-    align?: ListAlignment;
-    /** 表头默认对齐，列配置可覆盖。 */
-    headerAlign?: ComponentStyle["align"];
-    headerStyle?: ComponentStyle;
-    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
-    headerGrid?: PlanGrid;
-    border?: boolean;
-    /** 分组小计（组头/组尾小计/组头防孤行） */
-    groupBy?: ListGroupBy;
-    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
-    grandTotal?: ListGrandTotal;
-}
-
-declare type ListGrandTotal =
-| boolean
-| {
-    label?: string;
-    style?: ComponentStyle;
-    /** 合计列（缺省沿用 groupBy.subtotal） */
-    fields?: string[];
-};
-
-/** 分组小计配置（声明式，见 ListComponent.groupBy） */
-declare interface ListGroupBy {
-    /** 分组字段（值变化即切组） */
-    field: string;
-    /** 组头文案模板，{value} 占位（默认 "{value}"） */
-    headerTemplate?: string;
-    headerStyle?: ComponentStyle;
-    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
-    subtotal?: string[];
-    subtotalStyle?: ComponentStyle;
-    subtotalLabel?: string;
-    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
-    keepWithNext?: boolean;
-}
-
-/** defaults 层可配置项（全部可选，均有内置缺省） */
-declare interface MachReportDefaults {
-    showExport?: boolean;
-    showPrint?: boolean;
-    showPdfWindow?: boolean;
-    /** 设置入口默认显示；可在其中按需启用阅读及输出工具。 */
-    showSettings?: boolean;
-    toolbar?: MachReportToolbarOptions;
-    interaction?: ReportInteractionOptions;
-    preferences?: ReportPreferencesOptions;
-    /** Prepare optional image/chart/QR/barcode adapters once for preview and all outputs. */
-    assets?: AssetRenderOptions;
-    /** 参数面板显隐（有参数定义且未显式关闭时显示；缺省 true） */
-    showParams?: boolean;
-    /** 页间距 px */
-    gapPx?: number;
-    /** PDF 导出中文字体 URL */
-    pdfFontUrl?: string;
-    theme?: Partial<MachReportTheme>;
-    messages?: Partial<MachReportMessages>;
-    /** 校验告警等内部日志通道（默认 console；静默传 { warn: () => {}, info: () => {} }） */
-    logger?: MachReportLogger;
-    preview?: MachReportPreviewOptions;
-    /** Excel 出口配置，按字段继承；不配置使用导出器默认值。 */
-    xlsx?: XlsxRenderOptions;
-    /** 默认关闭；true 为本地草稿，对象可提供权限、校验和保存回调。 */
-    editable?: boolean | ReportEditingOptions;
-    /** 默认关闭；启用后提供导入按钮。ExcelJS 仅在导入时加载。 */
-    excelImport?: boolean | ExcelImportOptions;
-}
-
-/** 日志通道（默认 console；可注入 noop 静默或上报 collector） */
-declare type MachReportLogger = Pick<Console, "warn" | "info">;
-
-/**
- * 配置中心（对齐 mach-table 的 defineMachTableConfig 体验）：
- * - 应用级：app.use(machReportPlugin, { config: defineMachReportConfig({...}) })
- * - 路由级叠加：provideMachReportConfig(overlay)（响应式，就近覆盖）
- * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
- */
-
-/** 工具栏与状态文案（默认简体中文；出海场景覆写） */
-declare interface MachReportMessages {
-    title: string;
-    prevPage: string;
-    nextPage: string;
-    /** 页码显示模板，{cur}/{total} 占位 */
-    pageInfo: string;
-    fitWidth: string;
-    exportHtml: string;
-    exportPdf: string;
-    exportExcel: string;
-    exportImage: string;
-    exportWord: string;
-    /** 导出进行中提示，{format} 占位 */
-    exporting: string;
-    print: string;
-    pdfWindow: string;
-    loading: string;
-    empty: string;
-    /** @deprecated 未被组件消费，将在下个大版本移除（保留仅为类型兼容） */
-    errorPrefix: string;
-    retry: string;
-    /** 可选新增文案，保留旧完整文案对象兼容。 */
-    pdfFontUnavailable?: string;
-    /** 搜索框占位文案 */
-    searchPlaceholder: string;
-    /** 搜索命中计数，{cur}/{total} 占位 */
-    matchInfo: string;
-    /** 上/下一个命中 */
-    prevMatch: string;
-    nextMatch: string;
-    /** 缩略图侧栏开关 */
-    thumbnails: string;
-    /** 参数面板 */
-    paramsTitle: string;
-    query: string;
-    reset: string;
-    /** 必填缺失提示（{label} 占位） */
-    paramRequired: string;
-    paramInvalid?: string;
-    paramPrompt?: string;
-    paramPromptDescription?: string;
-    paramSelectPlaceholder?: string;
-    paramTextPlaceholder?: string;
-    /** 可选搜索进度文案，旧完整 messages 对象无需新增字段。 */
-    searching?: string;
-    importExcel?: string;
-    importing?: string;
-    editCell?: string;
-    editingHint?: string;
-    saving?: string;
-    editInvalidNumber?: string;
-    editInvalidBoolean?: string;
-    editConflict?: string;
-    settings?: string;
-    settingsDisplay?: string;
-    settingsExport?: string;
-    settingsData?: string;
-    settingsUnavailable?: string;
-    settingsReset?: string;
-    settingsClose?: string;
-    search?: string;
-    closeSearch?: string;
-    prevSearchMatch?: string;
-    nextSearchMatch?: string;
-    zoom?: string;
-    settingsLocal?: string;
-    editingLocal?: string;
-    editingSaved?: string;
-    importLocal?: string;
-    emptyDescription?: string;
-    undo?: string;
-    redo?: string;
-    restoreChanges?: string;
-    changes?: string;
-    changesCount?: string;
-    changesEmpty?: string;
-    changesBefore?: string;
-    changesAfter?: string;
-    editAtomicRequired?: string;
-    clipboardLimit?: string;
-    preferencesError?: string;
-    freezeHeaders?: string;
-    frozenColumns?: string;
-    sections?: string;
-    locateField?: string;
-    locateFieldPlaceholder?: string;
-    locateFieldMissing?: string;
-    importSummary?: string;
-    importPreserved?: string;
-    importWarnings?: string;
-    importReadOnly?: string;
-    conflicts?: string;
-    editReadOnly?: string;
-    editMissing?: string;
-    editDuplicate?: string;
-    clipboardInvalid?: string;
-    editSaved?: string;
-    settingsPanes?: string;
-}
-
-/** 预览按需调优；默认已经启用正文/缩略图虚拟化及可取消的分片搜索。 */
-declare interface MachReportPreviewOptions {
-    /** 视口前后额外保留的正文页数，默认 1，归一化到 0~10 的整数。 */
-    overscanPages?: number;
-    /** 搜索输入防抖毫秒，默认 200，归一化到 0~2000。 */
-    searchDebounceMs?: number;
-}
-
-/** 主题变量（组件外壳注入的 --mrp-* CSS 自定义属性） */
-declare interface MachReportTheme {
-    shellBg: string;
-    shellFg: string;
-    toolbarBg: string;
-    toolbarBorder: string;
-    toolbarFg: string;
-    btnFg: string;
-    btnBorder: string;
-    btnHoverBg: string;
-    btnHoverFg: string;
-    btnActiveBg: string;
-}
-
-declare interface MachReportToolbarOptions {
-    search?: boolean;
-    thumbnails?: boolean;
-    zoom?: boolean;
-    /** 编辑能力由 editable 授权；此项仅设置初始交互偏好，默认 true（兼容旧行为）。 */
-    editing?: boolean;
-    /** 导入能力由 excelImport 授权；此项仅设置初始交互偏好，默认 true。 */
-    excelImport?: boolean;
-    /** 未传时显示全部已有出口；空数组表示不提供导出工具。 */
-    exportFormats?: ReportExportFormat[];
-}
-
-declare interface OutputDiagnostic {
-    code: "missing-image" | "unsupported-component" | "unsupported-image-format" | "rich-text-flattened" | "nested-components-omitted" | "async-image-required" | "image-decode-failed" | "asset-render-failed" | "asset-budget-exceeded";
-    severity: "warning";
-    format: OutputFormat;
-    pageIndex: number;
-    componentIndex: number;
-    /** Nested grid child location as repeating [rowIndex, columnIndex, childIndex] triples. */
-    componentPath?: readonly number[];
-    kind: string;
-    nid?: string;
-    message: string;
-}
-
-declare interface OutputDiagnosticOptions {
-    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
-    onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
-}
-
-declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
-
-declare interface PlanComponent {
-    kind: ComponentKind;
-    leftMm: number;
-    topMm: number;
-    widthMm: number;
-    heightMm: number;
-    nid?: string;
-    rkey?: string;
-    text?: string;
-    rawText?: string;
-    lines?: string[];
-    richParagraphs?: RichParagraph[];
-    imageData?: string;
-    /** 明确指定线段方向；省略保持历史水平线行为。 */
-    lineDirection?: "down" | "up";
-    grid?: PlanGrid;
-    table?: PlanTableFragment;
-    style?: ComponentStyle;
-    meta?: Record<string, unknown>;
-    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
-    fallbackText?: string;
-}
-
-declare interface PlanGrid {
-    /** 行内允许 null 空位；渲染器按空单元格处理 */
-    cells: (GridCell | null)[][];
-    colWidthsMm?: number[];
-    rowHeightsMm?: number[];
-    gapMm?: number;
-    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
-    paddingMm?: number;
-}
-
-/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
-declare interface PlanTableFragment {
-    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
-    id: string;
-    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
-    rowIndex: number;
-    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
-    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
-    columnKeys: string[];
-    layout?: "page" | "wide";
-    title?: string;
-    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
-    source?: Omit<ReportCellSource, "field" | "rowKey"> & { rowKey?: string | number };
-}
-
-/** 预览中的物理坐标；合并单元格使用左上角坐标。 */
-declare interface ReportCellAddress {
-    pageIndex: number;
-    componentIndex: number;
-    rowIndex: number;
-    columnIndex: number;
-}
-
-declare interface ReportCellContext {
-    address: ReportCellAddress;
-    cell: Readonly<GridCell>;
-    component: Readonly<PlanComponent>;
-    value: ReportCellValue;
-    valueType: ReportCellValueType;
-    table?: ReportCellTableIdentity;
-    /** Stable business identity. Physical row indices must never be used as database keys. */
-    source?: Readonly<ReportCellSource>;
-    editable: boolean;
-    readOnlyReason?: ReportCellReadOnlyReason;
-}
-
-declare interface ReportCellEdit {
-    address: ReportCellAddress;
-    table?: ReportCellTableIdentity;
-    source?: Readonly<ReportCellSource>;
-    previousValue: ReportCellValue;
-    previousText: string;
-    value: ReportCellValue;
-    text: string;
-}
-
-declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
-
-/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
-declare interface ReportCellSource {
-    datasetId: string;
-    rowKey: string | number;
-    field: string;
-    revision?: string | number;
-    sourceToken?: string;
-}
-
-declare interface ReportCellTableIdentity {
-    id: string;
-    /** 逻辑表行索引；跨分页的同一行保持不变。 */
-    rowIndex: number;
-    role: PlanTableFragment["role"];
-    columnKey?: string;
-}
-
-declare type ReportCellValue = string | number | boolean | null;
-
-declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
-
-declare interface ReportEditBatch {
-    /** Idempotency identity; the server should bind it to the exact payload. */
-    requestId: string;
-    edits: ReportCellEdit[];
-}
-
-declare interface ReportEditConflict {
-    source?: Readonly<ReportCellSource>;
-    address?: ReportCellAddress;
-    message: string;
-    currentValue?: ReportCellValue;
-    revision?: string | number;
-}
-
-/** 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 | ReportEditResult | Promise<void | ReportEditResult>;
-    /** Must commit all edits in one server transaction. Required for multi-cell persisted edits. */
-    saveBatch?(batch: Readonly<ReportEditBatch>, operation: ReportEditOperation): void | ReportEditResult | Promise<void | ReportEditResult>;
-    /** Restrict persistence to plans that supply stable datasetId/rowKey/field metadata. */
-    requireSource?: boolean;
-}
-
-declare interface ReportEditOperation {
-    /** Reload, another import or unmount aborts the operation. Save adapters should forward this signal. */
-    signal: AbortSignal;
-    requestId?: string;
-    action?: "edit" | "undo" | "redo" | "restore";
-}
-
-declare interface ReportEditResult {
-    /** A successful result may advance concurrency tokens for the affected dataset. */
-    revision?: string | number;
-    sourceToken?: string;
-    /** Any conflict rejects the entire client batch. A server must also transact atomically. */
-    conflicts?: readonly ReportEditConflict[];
-}
-
-/** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
-declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
-
-declare interface ReportInteractionOptions {
-    /** Screen-only frozen panes; exported geometry is unchanged. */
-    freezeHeaders?: boolean;
-    /** Leading identity columns, from 0 to 20. */
-    frozenColumns?: number;
-    /** Show workbook sheets / report sections when available. Default true. */
-    navigation?: boolean;
-}
-
-/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
-declare interface ReportParamDef {
-    /** 参数名（传入 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;
-    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
-    min?: number | string;
-    max?: number | string;
-    minLength?: number;
-    maxLength?: number;
-}
-
-declare interface ReportPreferencesAdapter {
-    load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
-    save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
-    remove?(key: string): void | Promise<void>;
-}
-
-declare interface ReportPreferencesOptions {
-    /** Host-scoped key; do not share one key between unrelated users/tenants. */
-    key: string;
-    adapter: ReportPreferencesAdapter;
-}
-
-declare type ReportPreviewPreferences = Record<ReportPreviewTool, boolean>;
-
-declare type ReportPreviewTool = "search" | "thumbnails" | "zoom" | ReportExportFormat | "print" | "pdfWindow" | "editing" | "import";
-
-declare interface ReportTemplate {
-    schemaVersion?: string;
-    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
-    params?: ReportParamDef[];
-    pages: TemplatePage[];
-}
-
-/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
-declare interface ReportTemplateDocument {
-    schemaVersion: "1.0";
-    id: string;
-    name: string;
-    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
-    revision?: string;
-    description?: string;
-    template: ReportTemplate;
-}
-
-export declare const ReportTemplateEditor: DefineComponent<TemplateEditorOptions, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
-"update:modelValue": (document: ReportTemplateDocument) => any;
-saved: (document: ReportTemplateDocument) => any;
-}, string, PublicProps, Readonly<TemplateEditorOptions> & Readonly<{
-"onUpdate:modelValue"?: ((document: ReportTemplateDocument) => any) | undefined;
-onSaved?: ((document: ReportTemplateDocument) => any) | undefined;
-}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLElement>;
-
-declare interface RichParagraph {
-    segments: RichSegment[];
-    align?: ComponentStyle["align"];
-    lineHeight?: number;
-    spaceBeforeMm?: number;
-    spaceAfterMm?: number;
-    indentMm?: number;
-}
-
-declare interface RichSegment {
-    kind?: "text" | "field";
-    text?: string;
-    field?: string;
-    style?: ComponentStyle;
-}
-
-/** 条件格式规则求值（声明式，见 ListColumn.rules） */
-declare interface StyleRule {
-    when: {
-        field: string;
-        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
-        value: number | string;
-    };
-    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
-    style: Record<string, unknown>;
-}
-
-/** 可选设计器独立文案，不把其依赖和配置强加给预览消费者。 */
-export declare const TEMPLATE_EDITOR_MESSAGES: {
-    title: string;
-    heading: string;
-    unpublished: string;
-    dirty: string;
-    reset: string;
-    saving: string;
-    save: string;
-    name: string;
-    description: string;
-    area: string;
-    page: string;
-    header: string;
-    field: string;
-    width: string;
-    semantic: string;
-    identifier: string;
-    dimension: string;
-    measure: string;
-    date: string;
-    text: string;
-    bodyAlign: string;
-    headerAlign: string;
-    auto: string;
-    left: string;
-    center: string;
-    right: string;
-    justify: string;
-    editable: string;
-    json: string;
-    applyJson: string;
-    note: string;
-    invalid: string;
-};
-
-declare type TemplateComponent = PlanComponent | ListComponent;
-
-export declare type TemplateEditorMessages = typeof TEMPLATE_EDITOR_MESSAGES;
-
-export declare interface TemplateEditorOptions {
-    modelValue: ReportTemplateDocument;
-    datasets?: DatasetRows;
-    readonly?: boolean;
-    messages?: Partial<TemplateEditorMessages>;
-    preview?: Pick<MachReportDefaults, "showExport" | "showPrint" | "showPdfWindow" | "theme" | "assets" | "pdfFontUrl" | "toolbar">;
-    save?: (document: ReportTemplateDocument, context: TemplateEditorSaveContext) => Promise<ReportTemplateDocument>;
-}
-
-export declare interface TemplateEditorSaveContext {
-    expectedRevision?: string;
-    signal: AbortSignal;
-}
-
-declare interface TemplatePage {
-    widthMm: number;
-    heightMm: number;
-    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
-    layout?: "page" | "wide";
-    marginTopMm?: number;
-    marginBottomMm?: number;
-    marginLeftMm?: number;
-    marginRightMm?: number;
-    components: TemplateComponent[];
-}
-
-/**
- * RenderPlan → xlsx 导出（B 端第二出口，对齐家族 @agile-team/mach-table-xlsx 路线）：
- * - 网格组件 → 真表格：列宽（mm→Excel 宽度）、行高（mm→pt）、colSpan/rowSpan 合并、
- *   加粗/对齐/底色/字号直译（resolveGridLayout 复用单真相源几何）
- * - 文本组件 → 合并标题行（顺序流式输出，保字号/加粗/对齐；非像素级定位，
- *   目标是"财务能直接用的对账表"而非复刻版面）
- * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
- */
-
-declare interface XlsxRenderOptions extends OutputDiagnosticOptions {
-    /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
-    sheetName?: (sheetIndex: number) => string;
-    /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
-    sheetMode?: "auto" | "pages" | "continuous";
-    /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
-    valueMode?: "text" | "raw";
-    /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
-    paperSize?: "auto" | "a3" | "a4" | "a5";
-}
-
-export { }
+import { ComponentOptionsMixin } from 'vue';
+import { DefineComponent } from 'vue';
+declare interface AssetRenderBudget {
+    /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
+    maxAssets?: number;
+    /** Maximum image payload bytes per new asset, default 32 MiB. */
+    maxImageBytes?: number;
+    /** Maximum total image payload bytes for new assets, default 128 MiB. */
+    maxTotalImageBytes?: number;
+    /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
+    maxDurationMs?: number;
+}
+declare interface AssetRenderOptions extends OutputDiagnosticOptions {
+    assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    assetBudget?: AssetRenderBudget;
+    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
+    assetFailure?: "throw" | "placeholder";
+    signal?: AbortSignal;
+}
+/** 可选设计器独立文案，不把其依赖和配置强加给预览消费者。 */
+declare const BASE_TEMPLATE_EDITOR_MESSAGES: {
+    title: string;
+    heading: string;
+    unpublished: string;
+    dirty: string;
+    reset: string;
+    saving: string;
+    save: string;
+    name: string;
+    description: string;
+    area: string;
+    page: string;
+    header: string;
+    field: string;
+    width: string;
+    semantic: string;
+    identifier: string;
+    dimension: string;
+    measure: string;
+    date: string;
+    text: string;
+    bodyAlign: string;
+    headerAlign: string;
+    auto: string;
+    left: string;
+    center: string;
+    right: string;
+    justify: string;
+    editable: string;
+    json: string;
+    applyJson: string;
+    note: string;
+    invalid: 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 = {
+    kind: "number";
+    thousands?: boolean;
+    digits?: number;
+} | {
+    kind: "percent";
+    digits?: number;
+} | {
+    kind: "date";
+    pattern?: string;
+};
+declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+declare interface ComponentStyle {
+    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>[]>;
+/** 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;
+}
+declare interface ExcelImportOptions extends OutputTaskOptions {
+    /** 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 GridCell {
+    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;
+    source?: ReportCellSource;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle;
+}
+declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
+declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
+declare interface ListColumn {
+    header: string;
+    field: string;
+    widthMm: number;
+    style?: ComponentStyle;
+    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
+    align?: ListAlignment;
+    /** 独立的表头对齐，不改变内容对齐。 */
+    headerAlign?: ComponentStyle["align"];
+    /** 独立的表头样式，优先于列表级表头样式。 */
+    headerStyle?: ComponentStyle;
+    /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
+    format?: ColumnFormat;
+    /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
+    rules?: StyleRule[];
+    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
+    editable?: boolean;
+    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
+    valueType?: GridCell["valueType"];
+    /** 字段语义用于 auto 对齐；明确声明编号，避免把数字编号当成度量。 */
+    semanticRole?: "identifier" | "dimension" | "measure" | "date" | "text";
+}
+declare interface ListComponent {
+    kind: "list";
+    id?: string;
+    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
+    layout?: "page" | "wide";
+    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
+    title?: string;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    dataset: string;
+    /** 数据集中稳定业务主键的字段名；省略时编辑仅有计划内坐标。 */
+    rowKey?: string;
+    revisionField?: string;
+    sourceTokenField?: string;
+    columns: ListColumn[];
+    fontSizePt?: number;
+    headerBold?: boolean;
+    rowHeightMm?: number;
+    paddingMm?: number;
+    headerEveryPage?: boolean;
+    headerBackgroundColor?: string;
+    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
+    align?: ListAlignment;
+    /** 表头默认对齐，列配置可覆盖。 */
+    headerAlign?: ComponentStyle["align"];
+    headerStyle?: ComponentStyle;
+    /** 可选多行合并表头；列宽按列表物理列对齐，供 Excel 业务模板复用。 */
+    headerGrid?: PlanGrid;
+    border?: boolean;
+    /** 分组小计（组头/组尾小计/组头防孤行） */
+    groupBy?: ListGroupBy;
+    /** 末尾总合计行（依赖 groupBy.subtotal 或显式 fields） */
+    grandTotal?: ListGrandTotal;
+}
+declare type ListGrandTotal = boolean | {
+    label?: string;
+    style?: ComponentStyle;
+    /** 合计列（缺省沿用 groupBy.subtotal） */
+    fields?: string[];
+};
+/** 分组小计配置（声明式，见 ListComponent.groupBy） */
+declare interface ListGroupBy {
+    /** 分组字段（值变化即切组） */
+    field: string;
+    /** 组头文案模板，{value} 占位（默认 "{value}"） */
+    headerTemplate?: string;
+    headerStyle?: ComponentStyle;
+    /** 需要小计的列字段（组尾输出合计行；数值列求和，其余输出首值/留空） */
+    subtotal?: string[];
+    subtotalStyle?: ComponentStyle;
+    subtotalLabel?: string;
+    /** 组头防孤行（默认 true：页尾放不下"组头+首行"时整体换页） */
+    keepWithNext?: boolean;
+}
+/** defaults 层可配置项（全部可选，均有内置缺省） */
+declare interface MachReportDefaults {
+    showExport?: boolean;
+    showPrint?: boolean;
+    showPdfWindow?: boolean;
+    /** 设置入口默认显示；可在其中按需启用阅读及输出工具。 */
+    showSettings?: boolean;
+    toolbar?: MachReportToolbarOptions;
+    interaction?: ReportInteractionOptions;
+    preferences?: ReportPreferencesOptions;
+    /** Protect local input and drafts before replacing a report. Default true. */
+    guardChanges?: boolean;
+    beforeDiscard?: ReportBeforeDiscard;
+    output?: ReportOutputOptions;
+    /** Prepare optional image/chart/QR/barcode adapters once for preview and all outputs. */
+    assets?: AssetRenderOptions;
+    /** 参数面板显隐（有参数定义且未显式关闭时显示；缺省 true） */
+    showParams?: boolean;
+    /** 页间距 px */
+    gapPx?: number;
+    /** PDF 导出中文字体 URL */
+    pdfFontUrl?: string;
+    theme?: Partial<MachReportTheme>;
+    messages?: Partial<MachReportMessages>;
+    /** 校验告警等内部日志通道（默认 console；静默传 { warn: () => {}, info: () => {} }） */
+    logger?: MachReportLogger;
+    preview?: MachReportPreviewOptions;
+    /** Excel 出口配置，按字段继承；不配置使用导出器默认值。 */
+    xlsx?: XlsxRenderOptions;
+    /** 默认关闭；true 为本地草稿，对象可提供权限、校验和保存回调。 */
+    editable?: boolean | ReportEditingOptions;
+    /** 默认关闭；启用后提供导入按钮。ExcelJS 仅在导入时加载。 */
+    excelImport?: boolean | ExcelImportOptions;
+}
+/** 日志通道（默认 console；可注入 noop 静默或上报 collector） */
+declare type MachReportLogger = Pick<Console, "warn" | "info">;
+/**
+ * 配置中心（对齐 mach-table 的 defineMachTableConfig 体验）：
+ * - 应用级：app.use(machReportPlugin, { config: defineMachReportConfig({...}) })
+ * - 路由级叠加：provideMachReportConfig(overlay)（响应式，就近覆盖）
+ * - 优先级：组件 props > 路由级叠加 > preset > defaults（props 永远最高）
+ */
+/** 工具栏与状态文案（默认简体中文；出海场景覆写） */
+declare interface MachReportMessages {
+    title: string;
+    prevPage: string;
+    nextPage: string;
+    /** 页码显示模板，{cur}/{total} 占位 */
+    pageInfo: string;
+    fitWidth: string;
+    exportHtml: string;
+    exportPdf: string;
+    exportExcel: string;
+    exportImage: string;
+    exportWord: string;
+    /** 导出进行中提示，{format} 占位 */
+    exporting: string;
+    print: string;
+    pdfWindow: string;
+    loading: string;
+    empty: string;
+    /** @deprecated 未被组件消费，将在下个大版本移除（保留仅为类型兼容） */
+    errorPrefix: string;
+    retry: string;
+    /** 可选新增文案，保留旧完整文案对象兼容。 */
+    pdfFontUnavailable?: string;
+    /** 搜索框占位文案 */
+    searchPlaceholder: string;
+    /** 搜索命中计数，{cur}/{total} 占位 */
+    matchInfo: string;
+    /** 上/下一个命中 */
+    prevMatch: string;
+    nextMatch: string;
+    /** 缩略图侧栏开关 */
+    thumbnails: string;
+    /** 参数面板 */
+    paramsTitle: string;
+    query: string;
+    reset: string;
+    /** 必填缺失提示（{label} 占位） */
+    paramRequired: string;
+    paramInvalid?: string;
+    paramPrompt?: string;
+    paramPromptDescription?: string;
+    paramSelectPlaceholder?: string;
+    paramTextPlaceholder?: string;
+    /** 可选搜索进度文案，旧完整 messages 对象无需新增字段。 */
+    searching?: string;
+    importExcel?: string;
+    importing?: string;
+    editCell?: string;
+    editingHint?: string;
+    saving?: string;
+    editInvalidNumber?: string;
+    editInvalidBoolean?: string;
+    editConflict?: string;
+    settings?: string;
+    settingsDisplay?: string;
+    settingsExport?: string;
+    settingsData?: string;
+    settingsUnavailable?: string;
+    settingsReset?: string;
+    settingsClose?: string;
+    search?: string;
+    closeSearch?: string;
+    prevSearchMatch?: string;
+    nextSearchMatch?: string;
+    zoom?: string;
+    settingsLocal?: string;
+    editingLocal?: string;
+    editingSaved?: string;
+    importLocal?: string;
+    emptyDescription?: string;
+    undo?: string;
+    redo?: string;
+    restoreChanges?: string;
+    changes?: string;
+    changesCount?: string;
+    changesEmpty?: string;
+    changesBefore?: string;
+    changesAfter?: string;
+    editAtomicRequired?: string;
+    clipboardLimit?: string;
+    preferencesError?: string;
+    freezeHeaders?: string;
+    frozenColumns?: string;
+    sections?: string;
+    locateField?: string;
+    locateFieldPlaceholder?: string;
+    locateFieldMissing?: string;
+    importSummary?: string;
+    importPreserved?: string;
+    importWarnings?: string;
+    importReadOnly?: string;
+    conflicts?: string;
+    editReadOnly?: string;
+    editMissing?: string;
+    editDuplicate?: string;
+    clipboardInvalid?: string;
+    editSaved?: string;
+    settingsPanes?: string;
+    columnDirectory?: string;
+    columnSearch?: string;
+    columnNoMatches?: string;
+    columnResults?: string;
+    columnGroup?: string;
+    discardTitle?: string;
+    discardDescription?: string;
+    discardKeep?: string;
+    discardProceed?: string;
+    taskQuery?: string;
+    taskValidate?: string;
+    taskLayout?: string;
+    taskAssets?: string;
+    taskEncode?: string;
+    taskDownload?: string;
+    taskPrint?: string;
+    taskCancel?: string;
+    taskCancelled?: string;
+    diagnosticsTitle?: string;
+    diagnosticsSearch?: string;
+    diagnosticsMore?: string;
+    diagnosticsLocate?: string;
+    diagnosticsLocation?: string;
+    diagnosticsStrict?: string;
+    diagnosticsDetails?: string;
+    diagnosticMissingImage?: string;
+    diagnosticUnsupported?: string;
+    diagnosticUnsupportedStyle?: string;
+    diagnosticImageFormat?: string;
+    diagnosticRichText?: string;
+    diagnosticNested?: string;
+    diagnosticImageAsync?: string;
+    diagnosticImageDecode?: string;
+    diagnosticAssetFailed?: string;
+    diagnosticAssetBudget?: string;
+}
+/** 预览按需调优；默认已经启用正文/缩略图虚拟化及可取消的分片搜索。 */
+declare interface MachReportPreviewOptions {
+    /** 视口前后额外保留的正文页数，默认 1，归一化到 0~10 的整数。 */
+    overscanPages?: number;
+    /** 搜索输入防抖毫秒，默认 200，归一化到 0~2000。 */
+    searchDebounceMs?: number;
+}
+/** 主题变量（组件外壳注入的 --mrp-* CSS 自定义属性） */
+declare interface MachReportTheme {
+    shellBg: string;
+    shellFg: string;
+    toolbarBg: string;
+    toolbarBorder: string;
+    toolbarFg: string;
+    btnFg: string;
+    btnBorder: string;
+    btnHoverBg: string;
+    btnHoverFg: string;
+    btnActiveBg: string;
+}
+declare interface MachReportToolbarOptions {
+    search?: boolean;
+    thumbnails?: boolean;
+    zoom?: boolean;
+    /** 编辑能力由 editable 授权；此项仅设置初始交互偏好，默认 true（兼容旧行为）。 */
+    editing?: boolean;
+    /** 导入能力由 excelImport 授权；此项仅设置初始交互偏好，默认 true。 */
+    excelImport?: boolean;
+    /** 未传时显示全部已有出口；空数组表示不提供导出工具。 */
+    exportFormats?: ReportExportFormat[];
+}
+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";
+    severity: "warning";
+    format: OutputFormat;
+    pageIndex: number;
+    componentIndex: number;
+    /** Nested grid child location as repeating [rowIndex, columnIndex, childIndex] triples. */
+    componentPath?: readonly number[];
+    kind: string;
+    nid?: string;
+    message: string;
+}
+declare interface OutputDiagnosticOptions extends OutputTaskOptions {
+    /** Structured fidelity diagnostics; rendering never silently invents missing content. */
+    onDiagnostic?: (diagnostic: OutputDiagnostic) => void;
+    /** Reject known unsupported content before creating an incomplete file. Default warn. */
+    fidelity?: "warn" | "strict";
+}
+declare type OutputFormat = "dom" | "canvas" | "pdf" | "xlsx";
+/** Stage counts are exact completed units; encoding libraries may remain indeterminate. */
+declare interface OutputTaskOptions {
+    signal?: AbortSignal;
+    onProgress?: (completed: number, total: number) => void;
+}
+declare interface PlanComponent {
+    kind: ComponentKind;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph[];
+    imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
+    grid?: PlanGrid;
+    table?: PlanTableFragment;
+    style?: ComponentStyle;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+declare interface PlanGrid {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
+}
+declare const PRODUCT_TEMPLATE_EDITOR_MESSAGES: {
+    undo: string;
+    redo: string;
+    columnsSearch: string;
+    columnsSelected: string;
+    selectVisible: string;
+    clearSelection: string;
+    noColumns: string;
+    batchBody: string;
+    batchHeader: string;
+    chooseAlignment: string;
+    discardTitle: string;
+    discardDescription: string;
+    keepEditing: string;
+    discard: string;
+    jsonPending: string;
+};
+/** Return false to keep the current report. Without a hook the preview asks inline. */
+declare type ReportBeforeDiscard = (context: Readonly<ReportBeforeDiscardContext>) => boolean | Promise<boolean>;
+declare interface ReportBeforeDiscardContext {
+    reason: ReportDiscardReason;
+    reportIds: readonly string[];
+    /** Local input or a local draft, never a synonym for persisted differences. */
+    pendingLocalChanges: true;
+}
+/** 预览中的物理坐标；合并单元格使用左上角坐标。 */
+declare interface ReportCellAddress {
+    pageIndex: number;
+    componentIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+}
+declare interface ReportCellChoice {
+    value: Exclude<ReportCellValue, null>;
+    label?: string;
+}
+declare interface ReportCellContext {
+    address: ReportCellAddress;
+    cell: Readonly<GridCell>;
+    component: Readonly<PlanComponent>;
+    value: ReportCellValue;
+    valueType: ReportCellValueType;
+    table?: ReportCellTableIdentity;
+    /** Stable business identity. Physical row indices must never be used as database keys. */
+    source?: Readonly<ReportCellSource>;
+    editable: boolean;
+    readOnlyReason?: ReportCellReadOnlyReason;
+}
+declare interface ReportCellEdit {
+    address: ReportCellAddress;
+    table?: ReportCellTableIdentity;
+    source?: Readonly<ReportCellSource>;
+    previousValue: ReportCellValue;
+    previousText: string;
+    value: ReportCellValue;
+    text: string;
+}
+declare interface ReportCellFieldBase {
+    /** Presentation only; it never grants write permission. */
+    label?: string;
+    hint?: string;
+    unit?: string;
+    required?: boolean;
+}
+declare type ReportCellFieldOptions = ReportCellFieldBase & ({
+    type: "text";
+    maxLength?: number;
+} | {
+    type: "number";
+    min?: number;
+    max?: number;
+    precision?: number;
+} | {
+    type: "boolean";
+    trueLabel?: string;
+    falseLabel?: string;
+} | {
+    type: "enum";
+    options: readonly ReportCellChoice[];
+} | {
+    type: "date";
+    min?: string;
+    max?: string;
+});
+declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+declare interface ReportCellTableIdentity {
+    id: string;
+    /** 逻辑表行索引；跨分页的同一行保持不变。 */
+    rowIndex: number;
+    role: PlanTableFragment["role"];
+    columnKey?: string;
+}
+declare type ReportCellValue = string | number | boolean | null;
+declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
+declare type ReportDiscardReason = "reload" | "import" | "replace" | "leave";
+declare interface ReportEditBatch {
+    /** Idempotency identity; the server should bind it to the exact payload. */
+    requestId: string;
+    edits: ReportCellEdit[];
+}
+declare interface ReportEditConflict {
+    source?: Readonly<ReportCellSource>;
+    address?: ReportCellAddress;
+    message: string;
+    currentValue?: ReportCellValue;
+    revision?: string | number;
+}
+/** Opt in with true for local drafts, or provide host validation and persistence. */
+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;
+    /** 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 | ReportEditResult | Promise<void | ReportEditResult>;
+    /** Must commit all edits in one server transaction. Required for multi-cell persisted edits. */
+    saveBatch?(batch: Readonly<ReportEditBatch>, operation: ReportEditOperation): void | ReportEditResult | Promise<void | ReportEditResult>;
+    /** Restrict persistence to plans that supply stable datasetId/rowKey/field metadata. */
+    requireSource?: boolean;
+}
+declare interface ReportEditOperation {
+    /** Reload, another import or unmount aborts the operation. Save adapters should forward this signal. */
+    signal: AbortSignal;
+    requestId?: string;
+    action?: "edit" | "undo" | "redo" | "restore";
+}
+declare interface ReportEditResult {
+    /** A successful result may advance concurrency tokens for the affected dataset. */
+    revision?: string | number;
+    sourceToken?: string;
+    /** Any conflict rejects the entire client batch. A server must also transact atomically. */
+    conflicts?: readonly ReportEditConflict[];
+}
+/** 输出能力仍由宿主授权；工具偏好只决定当前预览实例的可见与启用状态。 */
+declare type ReportExportFormat = "html" | "pdf" | "xlsx" | "png" | "word";
+declare interface ReportInteractionOptions {
+    /** Screen-only frozen panes; exported geometry is unchanged. */
+    freezeHeaders?: boolean;
+    /** Leading identity columns, from 0 to 20. */
+    frozenColumns?: number;
+    /** Show workbook sheets / report sections when available. Default true. */
+    navigation?: boolean;
+}
+declare interface ReportOutputOptions {
+    /** warn preserves supported output and shows diagnostics; strict rejects known fidelity loss. */
+    fidelity?: "warn" | "strict";
+}
+/** 报表参数定义（声明式，模板自描述参数面：渲染组件据此生成查询面板） */
+declare interface ReportParamDef {
+    /** 参数名（传入 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;
+    /** 数字上下界；date 参数使用 YYYY-MM-DD 字符串（含边界）。 */
+    min?: number | string;
+    max?: number | string;
+    minLength?: number;
+    maxLength?: number;
+}
+declare interface ReportPreferencesAdapter {
+    load(key: string): Partial<ReportPreviewPreferences> | null | Promise<Partial<ReportPreviewPreferences> | null>;
+    save(key: string, value: Readonly<Partial<ReportPreviewPreferences>>): void | Promise<void>;
+    remove?(key: string): void | Promise<void>;
+}
+declare interface ReportPreferencesOptions {
+    /** Host-scoped key; do not share one key between unrelated users/tenants. */
+    key: string;
+    adapter: ReportPreferencesAdapter;
+}
+declare type ReportPreviewPreferences = Record<ReportPreviewTool, boolean>;
+declare type ReportPreviewTool = "search" | "thumbnails" | "zoom" | ReportExportFormat | "print" | "pdfWindow" | "editing" | "import";
+declare interface ReportTemplate {
+    schemaVersion?: string;
+    /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
+    params?: ReportParamDef[];
+    pages: TemplatePage[];
+}
+/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
+declare interface ReportTemplateDocument {
+    schemaVersion: "1.0";
+    id: string;
+    name: string;
+    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
+    revision?: string;
+    description?: string;
+    template: ReportTemplate;
+}
+export declare const ReportTemplateEditor: DefineComponent<TemplateEditorOptions, {
+    pendingLocalChanges: boolean;
+    guardChanges: (reason?: TemplateEditorBeforeDiscardContext["reason"], replacement?: ReportTemplateDocument) => Promise<boolean>;
+    reset: () => Promise<void>;
+    save: () => Promise<void>;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+    "update:modelValue": (document: ReportTemplateDocument) => any;
+    saved: (document: ReportTemplateDocument) => any;
+}, string, MachReportVuePublicProps, Readonly<TemplateEditorOptions> & Readonly<{
+    "onUpdate:modelValue"?: ((document: ReportTemplateDocument) => any) | undefined;
+    onSaved?: ((document: ReportTemplateDocument) => any) | undefined;
+}>, {}>;
+declare interface RichParagraph {
+    segments: RichSegment[];
+    align?: ComponentStyle["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+declare interface RichSegment {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle;
+}
+/** 条件格式规则求值（声明式，见 ListColumn.rules） */
+declare interface StyleRule {
+    when: {
+        field: string;
+        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
+        value: number | string;
+    };
+    /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
+    style: Record<string, unknown>;
+}
+export declare const TEMPLATE_EDITOR_MESSAGES: {
+    undo: string;
+    redo: string;
+    columnsSearch: string;
+    columnsSelected: string;
+    selectVisible: string;
+    clearSelection: string;
+    noColumns: string;
+    batchBody: string;
+    batchHeader: string;
+    chooseAlignment: string;
+    discardTitle: string;
+    discardDescription: string;
+    keepEditing: string;
+    discard: string;
+    jsonPending: string;
+    title: string;
+    heading: string;
+    unpublished: string;
+    dirty: string;
+    reset: string;
+    saving: string;
+    save: string;
+    name: string;
+    description: string;
+    area: string;
+    page: string;
+    header: string;
+    field: string;
+    width: string;
+    semantic: string;
+    identifier: string;
+    dimension: string;
+    measure: string;
+    date: string;
+    text: string;
+    bodyAlign: string;
+    headerAlign: string;
+    auto: string;
+    left: string;
+    center: string;
+    right: string;
+    justify: string;
+    editable: string;
+    json: string;
+    applyJson: string;
+    note: string;
+    invalid: string;
+};
+declare type TemplateComponent = PlanComponent | ListComponent;
+export declare type TemplateEditorBeforeDiscard = (context: TemplateEditorBeforeDiscardContext) => boolean | Promise<boolean>;
+export declare interface TemplateEditorBeforeDiscardContext {
+    reason: "reset" | "replace";
+    /** Independent snapshot of the current draft; it may contain invalid field values. */
+    document: ReportTemplateDocument;
+    replacement?: ReportTemplateDocument;
+    pendingLocalChanges: true;
+}
+export declare interface TemplateEditorController {
+    readonly pendingLocalChanges: boolean;
+    guardChanges(reason?: TemplateEditorBeforeDiscardContext["reason"], replacement?: ReportTemplateDocument): Promise<boolean>;
+    reset(): Promise<void>;
+    save(): Promise<void>;
+}
+/** Newly introduced labels are optional for existing complete message dictionaries. */
+export declare type TemplateEditorMessages = typeof BASE_TEMPLATE_EDITOR_MESSAGES & Partial<typeof PRODUCT_TEMPLATE_EDITOR_MESSAGES>;
+export declare interface TemplateEditorOptions {
+    modelValue: ReportTemplateDocument;
+    datasets?: DatasetRows;
+    readonly?: boolean;
+    messages?: Partial<TemplateEditorMessages>;
+    preview?: Pick<MachReportDefaults, "showExport" | "showPrint" | "showPdfWindow" | "theme" | "assets" | "pdfFontUrl" | "toolbar">;
+    beforeDiscard?: TemplateEditorBeforeDiscard;
+    save?: (document: ReportTemplateDocument, context: TemplateEditorSaveContext) => Promise<ReportTemplateDocument>;
+}
+export declare interface TemplateEditorSaveContext {
+    expectedRevision?: string;
+    signal: AbortSignal;
+}
+declare interface TemplatePage {
+    widthMm: number;
+    heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
+    marginTopMm?: number;
+    marginBottomMm?: number;
+    marginLeftMm?: number;
+    marginRightMm?: number;
+    components: TemplateComponent[];
+}
+/**
+ * RenderPlan → xlsx 导出（B 端第二出口，对齐家族 @agile-team/mach-table-xlsx 路线）：
+ * - 网格组件 → 真表格：列宽（mm→Excel 宽度）、行高（mm→pt）、colSpan/rowSpan 合并、
+ *   加粗/对齐/底色/字号直译（resolveGridLayout 复用单真相源几何）
+ * - 文本组件 → 合并标题行（顺序流式输出，保字号/加粗/对齐；非像素级定位，
+ *   目标是"财务能直接用的对账表"而非复刻版面）
+ * - 未支持组件、富文本专有内容与单元格嵌套组件跳过并计入 warnings
+ */
+declare interface XlsxRenderOptions extends OutputDiagnosticOptions {
+    /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
+    sheetName?: (sheetIndex: number) => string;
+    /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */
+    sheetMode?: "auto" | "pages" | "continuous";
+    /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
+    valueMode?: "text" | "raw";
+    /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
+    paperSize?: "auto" | "a3" | "a4" | "a5";
+}
+export {};
+
+/** Stable public attrs shared by supported Vue versions. */
+type MachReportVuePublicProps = import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps;