@agile-team/mach-report 2.2.0 → 2.3.1

package/dist/index.d.ts

@@ -133,8 +133,8 @@ export declare function createReportSource(reports: ReportRegistry, options?: {
 }): ReportSource;
 
 /**
- * 创建一页标准明细模板；分页与格式化继续由 paginateTemplate 处理。
- * 固定列保持毫米宽度，自动列共享余量；全部固定列时表格宽度为列宽之和。
+ * 创建明细模板；校验、列宽分配、标题与页面装配分别处理。
+ * page 自动列共享纸张余量；wide 保留自然列宽，公开配置保持不变。
  */
 export declare function createTableTemplate(options: TableTemplateOptions): ReportTemplate;
 
@@ -276,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;
@@ -328,6 +332,9 @@ export declare function measurePageSizePx(page: Pick<PlanPage, "pageWidthMm" | "
 
 export declare function measureTextMm(text: string, options: TextMeasureOptions): number;
 
+/** Merge a declared style layer while keeping its explicit font unit authoritative. */
+export declare function mergeComponentStyles(base: ComponentStyle | undefined, override: ComponentStyle | undefined): ComponentStyle;
+
 export declare const MM_PER_INCH = 25.4;
 
 export declare function mmToPx(value: number, dpi?: number): number;
@@ -386,6 +393,7 @@ export declare interface PaginateResult {
     warnings: string[];
 }
 
+/** 模板遍历只编排静态组件和列表；行测量、分组、换页与汇总各自独立。 */
 export declare function paginateTemplate(template: ReportTemplate, datasets: DatasetRows, optionsOrMmPerRow?: number | PaginateOptions): PaginateResult;
 
 export declare const PAPER_SIZES: Record<string, {
@@ -416,6 +424,7 @@ export declare interface PlanComponent {
     richParagraphs?: RichParagraph[];
     imageData?: string;
     grid?: PlanGrid;
+    table?: PlanTableFragment;
     style?: ComponentStyle;
     meta?: Record<string, unknown>;
     /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
@@ -434,9 +443,13 @@ export declare interface PlanGrid {
     colWidthsMm?: number[];
     rowHeightsMm?: number[];
     gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
 }
 
 export declare interface PlanPage {
+    /** wide 表示完整自然列宽；页面仅为预览的垂直窗口分段。 */
+    layout?: "page" | "wide";
     pageWidthMm: number;
     pageHeightMm: number;
     marginTopMm?: number;
@@ -446,6 +459,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;
@@ -675,16 +701,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;
@@ -693,7 +723,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;
@@ -741,6 +771,8 @@ export declare type TemplateComponent = PlanComponent | ListComponent;
 export declare interface TemplatePage {
     widthMm: number;
     heightMm: number;
+    /** 宽表保持全列自然宽度，页高只控制内部纵向分段。 */
+    layout?: "page" | "wide";
     marginTopMm?: number;
     marginBottomMm?: number;
     marginLeftMm?: number;