@agile-team/mach-report 2.3.2 → 2.4.1

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+/** 复制发生变化的页/组件/行；原计划保持不变，并拒绝覆盖已改变的单元格。 */
+export declare function applyReportCellEdit(plan: RenderPlan, edit: ReportCellEdit): RenderPlan;
+
 export declare function assertRenderPlan(input: unknown): PlanPage[];
 
 /** 盒子边框语义：四边开关 + 内部网格线（四边全关则内线不画） */
@@ -124,6 +127,9 @@ export declare function createCanvasPager(plan: RenderPlan, options?: CanvasPage
 /** 兼容旧 API：默认启发式测量 */
 export declare function createHeuristicMeasurer(): TextMeasurer;
 
+/** 生成可供宿主持久化/审计的补丁；不修改 plan 或宿主业务对象。 */
+export declare function createReportCellEdit(plan: RenderPlan, address: ReportCellAddress, input: ReportCellValue): ReportCellEdit;
+
 /**
  * 框架无关的报表数据源：注册一次模板与取数，包内完成分页、校验、按 ID 顺序合并。
  * 不缓存业务结果、不推断接口包装、不自动重试；鉴权与完整数据范围由宿主决定。
@@ -176,6 +182,9 @@ export declare function defineReportTemplate(document: Omit<ReportTemplateDocume
  */
 export declare function evalStyleRule(row: Record<string, unknown>, when: StyleRule["when"]): boolean;
 
+/** 同步 text/raw value，所有输出后端读取同一份更新后的 RenderPlan。 */
+export declare function formatReportCellEdit(context: ReportCellContext, value: ReportCellValue): string;
+
 /**
  * 应用格式化。非数值/无法解析时原样返回基础文本（降级不报错）：
  * - number：digits 小数位 + 可选千分位（12,345.60；thousands 默认 false）
@@ -186,6 +195,9 @@ export declare function formatValue(value: unknown, format?: ColumnFormat): stri
 
 declare type Geometry = Partial<Pick<PlanComponent, "leftMm" | "topMm" | "widthMm" | "heightMm">>;
 
+/** 缺失、被合并覆盖、显式 null 占位不生成编辑目标。 */
+export declare function getReportCellContext(plan: RenderPlan, address: ReportCellAddress): ReportCellContext | null;
+
 export declare interface GridCell {
     text?: string;
     rawText?: string;
@@ -193,6 +205,12 @@ export declare interface GridCell {
     value?: string | number | boolean | null;
     /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
     numberFormat?: string;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
     children?: PlanComponent[];
     colSpan?: number;
     rowSpan?: number;
@@ -271,6 +289,10 @@ export declare interface ListColumn {
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule[];
+    /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
+    editable?: boolean;
+    /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
+    valueType?: GridCell["valueType"];
 }
 
 export declare interface ListComponent {
@@ -407,6 +429,9 @@ export declare type PaperName = keyof typeof PAPER_SIZES;
 /** 日历日字符串 → 本地 Date（不含时间的纯日期，杜绝 UTC 偏移） */
 export declare function parseDateLocal(input: string): Date | null;
 
+/** 严格解析编辑输入；文本列不隐式推断数值，清空数值/布尔列得到 null。 */
+export declare function parseReportCellInput(context: ReportCellContext, input: ReportCellValue): ReportCellValue;
+
 /** 校验文件 JSON 文本或接口返回的未知对象，返回独立模板快照。 */
 export declare function parseReportTemplate(input: unknown): ReportTemplateDocument;
 
@@ -513,6 +538,55 @@ export declare function renderPlanToImages(plan: RenderPlan, options?: ImageRend
 /** 模板存储文档版本；与渲染计划版本独立演进。 */
 export declare const REPORT_TEMPLATE_DOCUMENT_VERSION: "1.0";
 
+/** 预览中的物理坐标；合并单元格使用左上角坐标。 */
+export declare interface ReportCellAddress {
+    pageIndex: number;
+    componentIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+}
+
+export declare interface ReportCellContext {
+    address: ReportCellAddress;
+    cell: Readonly<GridCell>;
+    component: Readonly<PlanComponent>;
+    value: ReportCellValue;
+    valueType: ReportCellValueType;
+    table?: ReportCellTableIdentity;
+    editable: boolean;
+    readOnlyReason?: ReportCellReadOnlyReason;
+}
+
+export declare interface ReportCellEdit {
+    address: ReportCellAddress;
+    table?: ReportCellTableIdentity;
+    previousValue: ReportCellValue;
+    previousText: string;
+    value: ReportCellValue;
+    text: string;
+}
+
+export declare class ReportCellEditError extends Error {
+    readonly code: ReportCellEditErrorCode;
+    constructor(code: ReportCellEditErrorCode);
+}
+
+export declare type ReportCellEditErrorCode = "missing" | "readonly" | "number" | "boolean" | "conflict";
+
+export declare type ReportCellReadOnlyReason = "cell" | "formula" | "complex" | "structure";
+
+export declare interface ReportCellTableIdentity {
+    id: string;
+    /** 逻辑表行索引；跨分页的同一行保持不变。 */
+    rowIndex: number;
+    role: PlanTableFragment["role"];
+    columnKey?: string;
+}
+
+export declare type ReportCellValue = string | number | boolean | null;
+
+export declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
+
 export declare interface ReportDefinition {
     /** 静态模板或宿主提供的异步模板加载器；动态模板默认每次重新读取，不缓存版本。 */
     template: ReportTemplate | ReportTemplateLoader;