@agile-team/mach-report 2.1.0 → 2.2.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;
 
 /**
@@ -147,6 +140,9 @@ export declare function createTableTemplate(options: TableTemplateOptions): Repo
 
 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;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
@@ -273,6 +287,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 +370,7 @@ export declare interface PageWindowInput {
     viewportHeightPx: number;
     scrollTopPx: number;
     overscan?: number;
-    /** 页间距（px）。占位高度按“每页高度+间距”累计，与 margin-bottom 布局一致；默认 0 */
+    /** 页间距（px），默认 0；与每页 margin-bottom 使用同一口径。 */
     gapPx?: number;
 }
 
@@ -380,6 +399,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;
@@ -462,12 +484,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 +560,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 +661,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: {
@@ -706,6 +766,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 +777,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;
 
 /**
@@ -147,6 +140,9 @@ export declare function createTableTemplate(options: TableTemplateOptions): Repo
 
 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;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
@@ -273,6 +287,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 +370,7 @@ export declare interface PageWindowInput {
     viewportHeightPx: number;
     scrollTopPx: number;
     overscan?: number;
-    /** 页间距（px）。占位高度按“每页高度+间距”累计，与 margin-bottom 布局一致；默认 0 */
+    /** 页间距（px），默认 0；与每页 margin-bottom 使用同一口径。 */
     gapPx?: number;
 }
 
@@ -380,6 +399,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;
@@ -462,12 +484,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 +560,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 +661,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: {
@@ -706,6 +766,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 +777,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;