@agile-team/mach-report 2.1.0 → 2.3.0

package/dist/index.d.cts

@@ -102,14 +102,7 @@ export declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
-/**
- * 页级视口虚拟化：给定每页高度与滚动位置，返回需要真实渲染的页区间
- * 与上下占位高度。start/end 为闭区间索引。
- *
- * 布局模型：每页占据 height + gap（gap 为页间距，默认 0），
- * padTop/padBottom 同口径累计，保证 占位+渲染页+间距 还原总滚动高度。
- * 内部用前缀和 + 二分定位覆盖页与可见终点。
- */
+/** 页级视口虚拟化；单次计算入口保留兼容，预览内部复用已建立的几何索引。 */
 export declare function computePageWindow(input: PageWindowInput): PageWindow;
 
 /**
@@ -140,13 +133,16 @@ export declare function createReportSource(reports: ReportRegistry, options?: {
 }): ReportSource;
 
 /**
- * 创建一页标准明细模板；分页与格式化继续由 paginateTemplate 处理。
- * 固定列保持毫米宽度，自动列共享余量；全部固定列时表格宽度为列宽之和。
+ * 创建明细模板；分页与格式化继续由 paginateTemplate 处理。
+ * page 模式自动列共享纸张余量；wide 模式按自然列宽扩展，不缩小字号或压缩列。
  */
 export declare function createTableTemplate(options: TableTemplateOptions): ReportTemplate;
 
 export declare function createTemplate(): TemplateBuilder;
 
+/** 存储无关的模板目录；后台 CRUD、权限、发布审批与持久化由宿主接入。 */
+export declare function createTemplateRegistry(documents?: readonly ReportTemplateDocument[]): ReportTemplateRegistry;
+
 export declare const CSS_DPI = 96;
 
 export declare type DatasetRows = Record<string, Record<string, unknown>[]>;
@@ -168,6 +164,11 @@ export declare function defineReport<TData>(definition: ReportDefinitionOptions<
 
 export declare function defineReport(definition: ReportDefinition): ReportDefinition;
 
+/** 创建带文档版本的模板快照，使用侧无需记忆 schemaVersion 常量。 */
+export declare function defineReportTemplate(document: Omit<ReportTemplateDocument, "schemaVersion"> & {
+    schemaVersion?: typeof REPORT_TEMPLATE_DOCUMENT_VERSION;
+}): ReportTemplateDocument;
+
 /**
  * 规则求值语义：
  * - 空值（null/undefined/""）永不命中（避免 Number("")===0 把空当 0 的隐式陷阱）
@@ -188,6 +189,10 @@ declare type Geometry = Partial<Pick<PlanComponent, "leftMm" | "topMm" | "widthM
 export declare interface GridCell {
     text?: string;
     rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
     children?: PlanComponent[];
     colSpan?: number;
     rowSpan?: number;
@@ -248,11 +253,20 @@ export declare function isRichText(comp: PlanComponent): boolean;
 /** 默认行高倍数（基线距 = 字号 × 该系数） */
 export declare const LINE_HEIGHT = 1.35;
 
+/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
+export declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
+
 export declare interface ListColumn {
     header: string;
     field: string;
     widthMm: number;
     style?: ComponentStyle;
+    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
+    align?: ListAlignment;
+    /** 独立的表头对齐，不改变内容对齐。 */
+    headerAlign?: ComponentStyle["align"];
+    /** 独立的表头样式，优先于列表级表头样式。 */
+    headerStyle?: ComponentStyle;
     /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
@@ -262,6 +276,10 @@ export declare interface ListColumn {
 export declare interface ListComponent {
     kind: "list";
     id?: string;
+    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
+    layout?: "page" | "wide";
+    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
+    title?: string;
     leftMm: number;
     topMm: number;
     widthMm: number;
@@ -273,6 +291,11 @@ export declare interface ListComponent {
     paddingMm?: number;
     headerEveryPage?: boolean;
     headerBackgroundColor?: string;
+    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
+    align?: ListAlignment;
+    /** 表头默认对齐，列配置可覆盖。 */
+    headerAlign?: ComponentStyle["align"];
+    headerStyle?: ComponentStyle;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
@@ -351,7 +374,7 @@ export declare interface PageWindowInput {
     viewportHeightPx: number;
     scrollTopPx: number;
     overscan?: number;
-    /** 页间距（px）。占位高度按“每页高度+间距”累计，与 margin-bottom 布局一致；默认 0 */
+    /** 页间距（px），默认 0；与每页 margin-bottom 使用同一口径。 */
     gapPx?: number;
 }
 
@@ -380,6 +403,9 @@ export declare type PaperName = keyof typeof PAPER_SIZES;
 /** 日历日字符串 → 本地 Date（不含时间的纯日期，杜绝 UTC 偏移） */
 export declare function parseDateLocal(input: string): Date | null;
 
+/** 校验文件 JSON 文本或接口返回的未知对象，返回独立模板快照。 */
+export declare function parseReportTemplate(input: unknown): ReportTemplateDocument;
+
 export declare interface PlanComponent {
     kind: ComponentKind;
     leftMm: number;
@@ -394,6 +420,7 @@ export declare interface PlanComponent {
     richParagraphs?: RichParagraph[];
     imageData?: string;
     grid?: PlanGrid;
+    table?: PlanTableFragment;
     style?: ComponentStyle;
     meta?: Record<string, unknown>;
     /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
@@ -415,6 +442,8 @@ export declare interface PlanGrid {
 }
 
 export declare interface PlanPage {
+    /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
+    layout?: "page" | "wide";
     pageWidthMm: number;
     pageHeightMm: number;
     marginTopMm?: number;
@@ -424,6 +453,19 @@ export declare interface PlanPage {
     components: PlanComponent[];
 }
 
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+export declare interface PlanTableFragment {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+}
+
 export declare function ptToPx(pt: number, dpi?: number): number;
 
 export declare function pxToMm(value: number, dpi?: number): number;
@@ -462,12 +504,16 @@ export declare function renderPlanToCanvas(plan: RenderPlan, options?: CanvasRen
  */
 export declare function renderPlanToImages(plan: RenderPlan, options?: ImageRenderOptions): Promise<ImageRenderResult>;
 
+/** 模板存储文档版本；与渲染计划版本独立演进。 */
+export declare const REPORT_TEMPLATE_DOCUMENT_VERSION: "1.0";
+
 export declare interface ReportDefinition {
-    template: ReportTemplate;
+    /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
+    template: ReportTemplate | ReportTemplateLoader;
     /** 静态数据；load 存在时优先使用 load 的结果。 */
     datasets?: DatasetRows;
     load?: (context: ReportLoadContext) => DatasetRows | Promise<DatasetRows>;
-    /** 覆盖模板参数定义，未提供时自动使用 template.params。 */
+    /** 覆盖模板参数定义；动态模板应在此声明查询面板元数据，避免查询前先请求模板。 */
     params?: ReportParamDef[];
     pagination?: PaginateOptions;
 }
@@ -534,6 +580,37 @@ export declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
+export declare interface ReportTemplateDocument {
+    schemaVersion: typeof REPORT_TEMPLATE_DOCUMENT_VERSION;
+    id: string;
+    name: string;
+    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
+    revision?: string;
+    description?: string;
+    template: ReportTemplate;
+}
+
+export declare class ReportTemplateError extends Error {
+    readonly errors: readonly ValidationError[];
+    constructor(errors: readonly ValidationError[]);
+}
+
+export declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
+
+export declare interface ReportTemplateRegistry {
+    /** 返回独立快照，调用方编辑不会改变目录中的已注册模板。 */
+    get(id: string): ReportTemplateDocument | undefined;
+    list(): ReportTemplateSummary[];
+    /** 重复 ID 默认拒绝；更新必须显式 replace:true。 */
+    register(document: ReportTemplateDocument, options?: {
+        replace?: boolean;
+    }): void;
+    remove(id: string): boolean;
+}
+
+export declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
+
 /**
  * 边框开关解析：
  * - 未声明（undefined）→ 四边全开（与既有 rect 总有边框的行为兼容）
@@ -604,6 +681,9 @@ export declare function round(value: number, digits: number): number;
 /** RenderPlan 正式 schema 版本（core 分页引擎产出） */
 export declare const SCHEMA_VERSION_MACH = "1.0.0-mach";
 
+/** 格式化输出已校验的纯模板 JSON，不静默丢弃函数或非法数字。 */
+export declare function serializeReportTemplate(document: ReportTemplateDocument): string;
+
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 export declare interface StyleRule {
     when: {
@@ -615,16 +695,20 @@ export declare interface StyleRule {
     style: Record<string, unknown>;
 }
 
-/** 标准明细列：显式 widthMm 优先；其余列按 flex 分配剩余可用宽度。 */
+/** 明细列：显式 widthMm 优先；纸张模式按 flex 分余量，宽表模式按 flex 放大基准列宽。 */
 export declare type TableTemplateColumn = Omit<ListColumn, "widthMm"> & {
     widthMm?: number;
     /** 自动列的宽度权重，默认 1（有 widthMm 时不参与分配）。 */
     flex?: number;
 };
 
-export declare type TableTemplateListOptions = Partial<Omit<ListComponent, "kind" | "leftMm" | "topMm" | "widthMm" | "dataset" | "columns">>;
+export declare type TableTemplateListOptions = Partial<Omit<ListComponent, "kind" | "leftMm" | "topMm" | "widthMm" | "dataset" | "columns" | "layout" | "title">>;
 
 export declare interface TableTemplateOptions extends PageOptions {
+    /** page 保持旧版纸张布局；wide 按所有列的自然宽度扩展，纵向分段仅供预览与渲染。 */
+    layout?: "page" | "wide";
+    /** 宽表模式自动列的基准宽度，默认 30mm；widthMm 优先，flex 为基准宽度的倍数。 */
+    columnWidthMm?: number;
     title?: string;
     /** 标题占高，默认 10mm；没有标题时不占空间。 */
     titleHeightMm?: number;
@@ -633,7 +717,7 @@ export declare interface TableTemplateOptions extends PageOptions {
     titleStyle?: ComponentStyle;
     dataset?: string;
     columns: readonly TableTemplateColumn[];
-    /** 默认 A4；页边距各默认 10mm。 */
+    /** 纸张模式默认 A4；与 layout: "wide" 互斥；页边距各默认 10mm。 */
     paper?: PaperName | {
         widthMm: number;
         heightMm: number;
@@ -681,6 +765,8 @@ export declare type TemplateComponent = PlanComponent | ListComponent;
 export declare interface TemplatePage {
     widthMm: number;
     heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
     marginTopMm?: number;
     marginBottomMm?: number;
     marginLeftMm?: number;
@@ -706,6 +792,9 @@ export declare interface TextMeasurer {
     measureMm(text: string, options: TextMeasureOptions): number;
 }
 
+/** 数值型 Excel 导出的显示格式；日期/对象仍使用显示文本，不做隐式类型转换。 */
+export declare function toExcelNumberFormat(format?: ColumnFormat): string | undefined;
+
 export declare function toNumber(value: unknown): number | null;
 
 export declare function validateComponent(comp: unknown, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
@@ -714,6 +803,11 @@ export declare function validatePage(page: unknown, path: string, errors: Valida
 
 export declare function validateRenderPlan(input: unknown): ValidationResult;
 
+/** 对入库/导入模板做声明式校验，不执行分页或数据请求。 */
+export declare function validateReportTemplate(input: unknown): ValidationResult;
+
+export declare function validateReportTemplateDocument(input: unknown): ValidationResult;
+
 export declare interface ValidationError {
     path: string;
     message: string;

package/dist/index.d.ts

@@ -102,14 +102,7 @@ export declare interface ComponentStyle {
     rotateDeg?: number;
 }
 
-/**
- * 页级视口虚拟化：给定每页高度与滚动位置，返回需要真实渲染的页区间
- * 与上下占位高度。start/end 为闭区间索引。
- *
- * 布局模型：每页占据 height + gap（gap 为页间距，默认 0），
- * padTop/padBottom 同口径累计，保证 占位+渲染页+间距 还原总滚动高度。
- * 内部用前缀和 + 二分定位覆盖页与可见终点。
- */
+/** 页级视口虚拟化；单次计算入口保留兼容，预览内部复用已建立的几何索引。 */
 export declare function computePageWindow(input: PageWindowInput): PageWindow;
 
 /**
@@ -140,13 +133,16 @@ export declare function createReportSource(reports: ReportRegistry, options?: {
 }): ReportSource;
 
 /**
- * 创建一页标准明细模板；分页与格式化继续由 paginateTemplate 处理。
- * 固定列保持毫米宽度，自动列共享余量；全部固定列时表格宽度为列宽之和。
+ * 创建明细模板；分页与格式化继续由 paginateTemplate 处理。
+ * page 模式自动列共享纸张余量；wide 模式按自然列宽扩展，不缩小字号或压缩列。
  */
 export declare function createTableTemplate(options: TableTemplateOptions): ReportTemplate;
 
 export declare function createTemplate(): TemplateBuilder;
 
+/** 存储无关的模板目录；后台 CRUD、权限、发布审批与持久化由宿主接入。 */
+export declare function createTemplateRegistry(documents?: readonly ReportTemplateDocument[]): ReportTemplateRegistry;
+
 export declare const CSS_DPI = 96;
 
 export declare type DatasetRows = Record<string, Record<string, unknown>[]>;
@@ -168,6 +164,11 @@ export declare function defineReport<TData>(definition: ReportDefinitionOptions<
 
 export declare function defineReport(definition: ReportDefinition): ReportDefinition;
 
+/** 创建带文档版本的模板快照，使用侧无需记忆 schemaVersion 常量。 */
+export declare function defineReportTemplate(document: Omit<ReportTemplateDocument, "schemaVersion"> & {
+    schemaVersion?: typeof REPORT_TEMPLATE_DOCUMENT_VERSION;
+}): ReportTemplateDocument;
+
 /**
  * 规则求值语义：
  * - 空值（null/undefined/""）永不命中（避免 Number("")===0 把空当 0 的隐式陷阱）
@@ -188,6 +189,10 @@ declare type Geometry = Partial<Pick<PlanComponent, "leftMm" | "topMm" | "widthM
 export declare interface GridCell {
     text?: string;
     rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
     children?: PlanComponent[];
     colSpan?: number;
     rowSpan?: number;
@@ -248,11 +253,20 @@ export declare function isRichText(comp: PlanComponent): boolean;
 /** 默认行高倍数（基线距 = 字号 × 该系数） */
 export declare const LINE_HEIGHT = 1.35;
 
+/** auto：真实数字/显式数值格式居右，日期与布尔居中，其他内容居左。 */
+export declare type ListAlignment = NonNullable<ComponentStyle["align"]> | "auto";
+
 export declare interface ListColumn {
     header: string;
     field: string;
     widthMm: number;
     style?: ComponentStyle;
+    /** 内容对齐，优先于 style.align；数值字符串不会自动判为数字。 */
+    align?: ListAlignment;
+    /** 独立的表头对齐，不改变内容对齐。 */
+    headerAlign?: ComponentStyle["align"];
+    /** 独立的表头样式，优先于列表级表头样式。 */
+    headerStyle?: ComponentStyle;
     /** 值格式化（声明式）：千分位/小数位、百分比、日期 pattern */
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
@@ -262,6 +276,10 @@ export declare interface ListColumn {
 export declare interface ListComponent {
     kind: "list";
     id?: string;
+    /** 宽表标记用于连续 Excel；不改变低层列表的列宽和分页算法。 */
+    layout?: "page" | "wide";
+    /** 逻辑表名称，供 Excel Sheet 命名；不额外生成标题组件。 */
+    title?: string;
     leftMm: number;
     topMm: number;
     widthMm: number;
@@ -273,6 +291,11 @@ export declare interface ListComponent {
     paddingMm?: number;
     headerEveryPage?: boolean;
     headerBackgroundColor?: string;
+    /** 内容默认对齐，列配置可覆盖；低层模板缺省仍为 left。 */
+    align?: ListAlignment;
+    /** 表头默认对齐，列配置可覆盖。 */
+    headerAlign?: ComponentStyle["align"];
+    headerStyle?: ComponentStyle;
     border?: boolean;
     /** 分组小计（组头/组尾小计/组头防孤行） */
     groupBy?: ListGroupBy;
@@ -351,7 +374,7 @@ export declare interface PageWindowInput {
     viewportHeightPx: number;
     scrollTopPx: number;
     overscan?: number;
-    /** 页间距（px）。占位高度按“每页高度+间距”累计，与 margin-bottom 布局一致；默认 0 */
+    /** 页间距（px），默认 0；与每页 margin-bottom 使用同一口径。 */
     gapPx?: number;
 }
 
@@ -380,6 +403,9 @@ export declare type PaperName = keyof typeof PAPER_SIZES;
 /** 日历日字符串 → 本地 Date（不含时间的纯日期，杜绝 UTC 偏移） */
 export declare function parseDateLocal(input: string): Date | null;
 
+/** 校验文件 JSON 文本或接口返回的未知对象，返回独立模板快照。 */
+export declare function parseReportTemplate(input: unknown): ReportTemplateDocument;
+
 export declare interface PlanComponent {
     kind: ComponentKind;
     leftMm: number;
@@ -394,6 +420,7 @@ export declare interface PlanComponent {
     richParagraphs?: RichParagraph[];
     imageData?: string;
     grid?: PlanGrid;
+    table?: PlanTableFragment;
     style?: ComponentStyle;
     meta?: Record<string, unknown>;
     /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
@@ -415,6 +442,8 @@ export declare interface PlanGrid {
 }
 
 export declare interface PlanPage {
+    /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
+    layout?: "page" | "wide";
     pageWidthMm: number;
     pageHeightMm: number;
     marginTopMm?: number;
@@ -424,6 +453,19 @@ export declare interface PlanPage {
     components: PlanComponent[];
 }
 
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+export declare interface PlanTableFragment {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+}
+
 export declare function ptToPx(pt: number, dpi?: number): number;
 
 export declare function pxToMm(value: number, dpi?: number): number;
@@ -462,12 +504,16 @@ export declare function renderPlanToCanvas(plan: RenderPlan, options?: CanvasRen
  */
 export declare function renderPlanToImages(plan: RenderPlan, options?: ImageRenderOptions): Promise<ImageRenderResult>;
 
+/** 模板存储文档版本；与渲染计划版本独立演进。 */
+export declare const REPORT_TEMPLATE_DOCUMENT_VERSION: "1.0";
+
 export declare interface ReportDefinition {
-    template: ReportTemplate;
+    /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
+    template: ReportTemplate | ReportTemplateLoader;
     /** 静态数据；load 存在时优先使用 load 的结果。 */
     datasets?: DatasetRows;
     load?: (context: ReportLoadContext) => DatasetRows | Promise<DatasetRows>;
-    /** 覆盖模板参数定义，未提供时自动使用 template.params。 */
+    /** 覆盖模板参数定义；动态模板应在此声明查询面板元数据，避免查询前先请求模板。 */
     params?: ReportParamDef[];
     pagination?: PaginateOptions;
 }
@@ -534,6 +580,37 @@ export declare interface ReportTemplate {
     pages: TemplatePage[];
 }
 
+/** 可存入数据库/文件的纯 JSON 模板；数据、接口与鉴权仍由宿主提供。 */
+export declare interface ReportTemplateDocument {
+    schemaVersion: typeof REPORT_TEMPLATE_DOCUMENT_VERSION;
+    id: string;
+    name: string;
+    /** 宿主的发布版本/乐观锁标识，不由引擎自动递增。 */
+    revision?: string;
+    description?: string;
+    template: ReportTemplate;
+}
+
+export declare class ReportTemplateError extends Error {
+    readonly errors: readonly ValidationError[];
+    constructor(errors: readonly ValidationError[]);
+}
+
+export declare type ReportTemplateLoader = (context: ReportLoadContext) => ReportTemplate | Promise<ReportTemplate>;
+
+export declare interface ReportTemplateRegistry {
+    /** 返回独立快照，调用方编辑不会改变目录中的已注册模板。 */
+    get(id: string): ReportTemplateDocument | undefined;
+    list(): ReportTemplateSummary[];
+    /** 重复 ID 默认拒绝；更新必须显式 replace:true。 */
+    register(document: ReportTemplateDocument, options?: {
+        replace?: boolean;
+    }): void;
+    remove(id: string): boolean;
+}
+
+export declare type ReportTemplateSummary = Omit<ReportTemplateDocument, "template">;
+
 /**
  * 边框开关解析：
  * - 未声明（undefined）→ 四边全开（与既有 rect 总有边框的行为兼容）
@@ -604,6 +681,9 @@ export declare function round(value: number, digits: number): number;
 /** RenderPlan 正式 schema 版本（core 分页引擎产出） */
 export declare const SCHEMA_VERSION_MACH = "1.0.0-mach";
 
+/** 格式化输出已校验的纯模板 JSON，不静默丢弃函数或非法数字。 */
+export declare function serializeReportTemplate(document: ReportTemplateDocument): string;
+
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 export declare interface StyleRule {
     when: {
@@ -615,16 +695,20 @@ export declare interface StyleRule {
     style: Record<string, unknown>;
 }
 
-/** 标准明细列：显式 widthMm 优先；其余列按 flex 分配剩余可用宽度。 */
+/** 明细列：显式 widthMm 优先；纸张模式按 flex 分余量，宽表模式按 flex 放大基准列宽。 */
 export declare type TableTemplateColumn = Omit<ListColumn, "widthMm"> & {
     widthMm?: number;
     /** 自动列的宽度权重，默认 1（有 widthMm 时不参与分配）。 */
     flex?: number;
 };
 
-export declare type TableTemplateListOptions = Partial<Omit<ListComponent, "kind" | "leftMm" | "topMm" | "widthMm" | "dataset" | "columns">>;
+export declare type TableTemplateListOptions = Partial<Omit<ListComponent, "kind" | "leftMm" | "topMm" | "widthMm" | "dataset" | "columns" | "layout" | "title">>;
 
 export declare interface TableTemplateOptions extends PageOptions {
+    /** page 保持旧版纸张布局；wide 按所有列的自然宽度扩展，纵向分段仅供预览与渲染。 */
+    layout?: "page" | "wide";
+    /** 宽表模式自动列的基准宽度，默认 30mm；widthMm 优先，flex 为基准宽度的倍数。 */
+    columnWidthMm?: number;
     title?: string;
     /** 标题占高，默认 10mm；没有标题时不占空间。 */
     titleHeightMm?: number;
@@ -633,7 +717,7 @@ export declare interface TableTemplateOptions extends PageOptions {
     titleStyle?: ComponentStyle;
     dataset?: string;
     columns: readonly TableTemplateColumn[];
-    /** 默认 A4；页边距各默认 10mm。 */
+    /** 纸张模式默认 A4；与 layout: "wide" 互斥；页边距各默认 10mm。 */
     paper?: PaperName | {
         widthMm: number;
         heightMm: number;
@@ -681,6 +765,8 @@ export declare type TemplateComponent = PlanComponent | ListComponent;
 export declare interface TemplatePage {
     widthMm: number;
     heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
     marginTopMm?: number;
     marginBottomMm?: number;
     marginLeftMm?: number;
@@ -706,6 +792,9 @@ export declare interface TextMeasurer {
     measureMm(text: string, options: TextMeasureOptions): number;
 }
 
+/** 数值型 Excel 导出的显示格式；日期/对象仍使用显示文本，不做隐式类型转换。 */
+export declare function toExcelNumberFormat(format?: ColumnFormat): string | undefined;
+
 export declare function toNumber(value: unknown): number | null;
 
 export declare function validateComponent(comp: unknown, path: string, errors: ValidationError[], warnings?: ValidationError[]): void;
@@ -714,6 +803,11 @@ export declare function validatePage(page: unknown, path: string, errors: Valida
 
 export declare function validateRenderPlan(input: unknown): ValidationResult;
 
+/** 对入库/导入模板做声明式校验，不执行分页或数据请求。 */
+export declare function validateReportTemplate(input: unknown): ValidationResult;
+
+export declare function validateReportTemplateDocument(input: unknown): ValidationResult;
+
 export declare interface ValidationError {
     path: string;
     message: string;