@veltra/sheet 2.0.0

package/dist/core/workbook.d.ts

@@ -0,0 +1,43 @@
+import { DependencyGraph } from "./formula/dependency-graph.js";
+import { Sheet } from "./sheet.js";
+//#region src/core/workbook.d.ts
+/**
+ * Workbook：多 Sheet 管理。
+ * 所有 sheet 共享一个公式依赖图（跨表引用与增量重算的中枢）。
+ */
+type WorkbookEvents = {
+  /** 激活 sheet 切换 */
+  'active-sheet-change': {
+    sheet: Sheet;
+    index: number;
+  };
+  /** sheet 增删 */
+  'sheets-change': {
+    sheets: Sheet[];
+  };
+};
+declare class Workbook {
+  private sheets;
+  private activeIndex;
+  private emitter;
+  /** 工作簿级公式依赖图（全部 sheet 共享） */
+  readonly formulaGraph: DependencyGraph;
+  constructor();
+  get sheetCount(): number;
+  get activeSheet(): Sheet;
+  get activeSheetIndex(): number;
+  getSheets(): Sheet[];
+  getSheet(name: string): Sheet | undefined;
+  /** 新增 sheet，名称缺省为 Sheet{n}（保证唯一） */
+  addSheet(name?: string): Sheet;
+  /** 删除 sheet；至少保留一个。删除激活项时激活相邻 sheet */
+  removeSheet(name: string): boolean;
+  /** 激活指定 sheet */
+  activateSheet(name: string): boolean;
+  on<K extends keyof WorkbookEvents>(type: K, handler: (payload: WorkbookEvents[K]) => void): () => void;
+  off<K extends keyof WorkbookEvents>(type: K, handler: (payload: WorkbookEvents[K]) => void): void;
+  private nextDefaultName;
+}
+//#endregion
+export { Workbook, WorkbookEvents };
+//# sourceMappingURL=workbook.d.ts.map

package/dist/core/workbook.js

@@ -0,0 +1,77 @@
+import { TypedEventEmitter } from "./events.js";
+import { DependencyGraph } from "./formula/dependency-graph.js";
+import { Sheet } from "./sheet.js";
+//#region src/core/workbook.ts
+var Workbook = class {
+	sheets = [];
+	activeIndex = 0;
+	emitter = new TypedEventEmitter();
+	/** 工作簿级公式依赖图（全部 sheet 共享） */
+	formulaGraph = new DependencyGraph();
+	constructor() {
+		this.addSheet();
+	}
+	get sheetCount() {
+		return this.sheets.length;
+	}
+	get activeSheet() {
+		return this.sheets[this.activeIndex];
+	}
+	get activeSheetIndex() {
+		return this.activeIndex;
+	}
+	getSheets() {
+		return [...this.sheets];
+	}
+	getSheet(name) {
+		return this.sheets.find((sheet) => sheet.name === name);
+	}
+	/** 新增 sheet，名称缺省为 Sheet{n}（保证唯一） */
+	addSheet(name) {
+		const sheet = new Sheet(name ?? this.nextDefaultName(), this.formulaGraph);
+		this.sheets.push(sheet);
+		this.emitter.emit("sheets-change", { sheets: this.getSheets() });
+		return sheet;
+	}
+	/** 删除 sheet；至少保留一个。删除激活项时激活相邻 sheet */
+	removeSheet(name) {
+		if (this.sheets.length <= 1) return false;
+		const index = this.sheets.findIndex((sheet) => sheet.name === name);
+		if (index < 0) return false;
+		const [removed] = this.sheets.splice(index, 1);
+		this.formulaGraph.unregisterSheet(removed);
+		if (this.activeIndex >= this.sheets.length) this.activeIndex = this.sheets.length - 1;
+		this.emitter.emit("sheets-change", { sheets: this.getSheets() });
+		this.emitter.emit("active-sheet-change", {
+			sheet: this.activeSheet,
+			index: this.activeIndex
+		});
+		return true;
+	}
+	/** 激活指定 sheet */
+	activateSheet(name) {
+		const index = this.sheets.findIndex((sheet) => sheet.name === name);
+		if (index < 0 || index === this.activeIndex) return false;
+		this.activeIndex = index;
+		this.emitter.emit("active-sheet-change", {
+			sheet: this.activeSheet,
+			index
+		});
+		return true;
+	}
+	on(type, handler) {
+		return this.emitter.on(type, handler);
+	}
+	off(type, handler) {
+		this.emitter.off(type, handler);
+	}
+	nextDefaultName() {
+		let n = this.sheets.length + 1;
+		while (this.getSheet(`Sheet${n}`)) n++;
+		return `Sheet${n}`;
+	}
+};
+//#endregion
+export { Workbook };
+
+//# sourceMappingURL=workbook.js.map

package/dist/core/workbook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workbook.js","names":[],"sources":["../../src/core/workbook.ts"],"sourcesContent":["import { TypedEventEmitter } from './events'\nimport { DependencyGraph } from './formula/dependency-graph'\nimport { Sheet } from './sheet'\n\n/**\n * Workbook：多 Sheet 管理。\n * 所有 sheet 共享一个公式依赖图（跨表引用与增量重算的中枢）。\n */\n\nexport type WorkbookEvents = {\n  /** 激活 sheet 切换 */\n  'active-sheet-change': { sheet: Sheet; index: number }\n  /** sheet 增删 */\n  'sheets-change': { sheets: Sheet[] }\n}\n\nexport class Workbook {\n  private sheets: Sheet[] = []\n  private activeIndex = 0\n  private emitter = new TypedEventEmitter<WorkbookEvents>()\n  /** 工作簿级公式依赖图（全部 sheet 共享） */\n  readonly formulaGraph = new DependencyGraph()\n\n  constructor() {\n    this.addSheet()\n  }\n\n  get sheetCount(): number {\n    return this.sheets.length\n  }\n\n  get activeSheet(): Sheet {\n    return this.sheets[this.activeIndex]!\n  }\n\n  get activeSheetIndex(): number {\n    return this.activeIndex\n  }\n\n  getSheets(): Sheet[] {\n    return [...this.sheets]\n  }\n\n  getSheet(name: string): Sheet | undefined {\n    return this.sheets.find((sheet) => sheet.name === name)\n  }\n\n  /** 新增 sheet，名称缺省为 Sheet{n}（保证唯一） */\n  addSheet(name?: string): Sheet {\n    const sheet = new Sheet(name ?? this.nextDefaultName(), this.formulaGraph)\n    this.sheets.push(sheet)\n    this.emitter.emit('sheets-change', { sheets: this.getSheets() })\n    return sheet\n  }\n\n  /** 删除 sheet；至少保留一个。删除激活项时激活相邻 sheet */\n  removeSheet(name: string): boolean {\n    if (this.sheets.length <= 1) return false\n    const index = this.sheets.findIndex((sheet) => sheet.name === name)\n    if (index < 0) return false\n    const [removed] = this.sheets.splice(index, 1)\n    this.formulaGraph.unregisterSheet(removed!)\n    if (this.activeIndex >= this.sheets.length) {\n      this.activeIndex = this.sheets.length - 1\n    }\n    this.emitter.emit('sheets-change', { sheets: this.getSheets() })\n    this.emitter.emit('active-sheet-change', { sheet: this.activeSheet, index: this.activeIndex })\n    return true\n  }\n\n  /** 激活指定 sheet */\n  activateSheet(name: string): boolean {\n    const index = this.sheets.findIndex((sheet) => sheet.name === name)\n    if (index < 0 || index === this.activeIndex) return false\n    this.activeIndex = index\n    this.emitter.emit('active-sheet-change', { sheet: this.activeSheet, index })\n    return true\n  }\n\n  on<K extends keyof WorkbookEvents>(\n    type: K,\n    handler: (payload: WorkbookEvents[K]) => void\n  ): () => void {\n    return this.emitter.on(type, handler)\n  }\n\n  off<K extends keyof WorkbookEvents>(\n    type: K,\n    handler: (payload: WorkbookEvents[K]) => void\n  ): void {\n    this.emitter.off(type, handler)\n  }\n\n  private nextDefaultName(): string {\n    let n = this.sheets.length + 1\n    while (this.getSheet(`Sheet${n}`)) n++\n    return `Sheet${n}`\n  }\n}\n"],"mappings":";;;;AAgBA,IAAa,WAAb,MAAsB;CACpB,SAA0B,CAAC;CAC3B,cAAsB;CACtB,UAAkB,IAAI,kBAAkC;;CAExD,eAAwB,IAAI,gBAAgB;CAE5C,cAAc;EACZ,KAAK,SAAS;CAChB;CAEA,IAAI,aAAqB;EACvB,OAAO,KAAK,OAAO;CACrB;CAEA,IAAI,cAAqB;EACvB,OAAO,KAAK,OAAO,KAAK;CAC1B;CAEA,IAAI,mBAA2B;EAC7B,OAAO,KAAK;CACd;CAEA,YAAqB;EACnB,OAAO,CAAC,GAAG,KAAK,MAAM;CACxB;CAEA,SAAS,MAAiC;EACxC,OAAO,KAAK,OAAO,MAAM,UAAU,MAAM,SAAS,IAAI;CACxD;;CAGA,SAAS,MAAsB;EAC7B,MAAM,QAAQ,IAAI,MAAM,QAAQ,KAAK,gBAAgB,GAAG,KAAK,YAAY;EACzE,KAAK,OAAO,KAAK,KAAK;EACtB,KAAK,QAAQ,KAAK,iBAAiB,EAAE,QAAQ,KAAK,UAAU,EAAE,CAAC;EAC/D,OAAO;CACT;;CAGA,YAAY,MAAuB;EACjC,IAAI,KAAK,OAAO,UAAU,GAAG,OAAO;EACpC,MAAM,QAAQ,KAAK,OAAO,WAAW,UAAU,MAAM,SAAS,IAAI;EAClE,IAAI,QAAQ,GAAG,OAAO;EACtB,MAAM,CAAC,WAAW,KAAK,OAAO,OAAO,OAAO,CAAC;EAC7C,KAAK,aAAa,gBAAgB,OAAQ;EAC1C,IAAI,KAAK,eAAe,KAAK,OAAO,QAClC,KAAK,cAAc,KAAK,OAAO,SAAS;EAE1C,KAAK,QAAQ,KAAK,iBAAiB,EAAE,QAAQ,KAAK,UAAU,EAAE,CAAC;EAC/D,KAAK,QAAQ,KAAK,uBAAuB;GAAE,OAAO,KAAK;GAAa,OAAO,KAAK;EAAY,CAAC;EAC7F,OAAO;CACT;;CAGA,cAAc,MAAuB;EACnC,MAAM,QAAQ,KAAK,OAAO,WAAW,UAAU,MAAM,SAAS,IAAI;EAClE,IAAI,QAAQ,KAAK,UAAU,KAAK,aAAa,OAAO;EACpD,KAAK,cAAc;EACnB,KAAK,QAAQ,KAAK,uBAAuB;GAAE,OAAO,KAAK;GAAa;EAAM,CAAC;EAC3E,OAAO;CACT;CAEA,GACE,MACA,SACY;EACZ,OAAO,KAAK,QAAQ,GAAG,MAAM,OAAO;CACtC;CAEA,IACE,MACA,SACM;EACN,KAAK,QAAQ,IAAI,MAAM,OAAO;CAChC;CAEA,kBAAkC;EAChC,IAAI,IAAI,KAAK,OAAO,SAAS;EAC7B,OAAO,KAAK,SAAS,QAAQ,GAAG,GAAG;EACnC,OAAO,QAAQ;CACjB;AACF"}

package/dist/grid/sheet-grid.d.ts

@@ -0,0 +1,59 @@
+import { Sheet } from "../core/sheet.js";
+import { ListTable } from "@visactor/vtable";
+//#region src/grid/sheet-grid.d.ts
+interface SheetGridOptions {
+  container: HTMLElement;
+  sheet: Sheet;
+  /** 渲染行数，默认 100 */
+  rows?: number;
+  /** 渲染列数，默认 26（A..Z） */
+  cols?: number;
+}
+declare class SheetGrid {
+  private readonly sheet;
+  private readonly table;
+  private readonly container;
+  private readonly rows;
+  private readonly cols;
+  private readonly editorName;
+  private readonly disposers;
+  /** 编辑提交期间累积的模型变更（提交结束统一回推表格，覆盖公式派生格） */
+  private pendingTableSync;
+  /** 实测坐标偏移（行号列数 / 列头行数），首次使用时测量 */
+  private offsets?;
+  constructor(options: SheetGridOptions);
+  /** 底层 ListTable 实例（调试与测试用） */
+  getTable(): ListTable;
+  /** 全量刷新（合并结构变化、批量数据变更后调用） */
+  refresh(): void;
+  /** 撤销一步（模型命令历史） */
+  undo(): boolean;
+  /** 重做一步（模型命令历史） */
+  redo(): boolean;
+  release(): void;
+  /**
+   * 实测偏移：列头行数取 columnHeaderLevelCount；
+   * 行号列不被计入 rowHeaderLevelCount，用 isSeriesNumber 逐列探测。
+   * 结果缓存（表格实例不变，布局不变）。
+   */
+  private getOffsets;
+  /** VTable 坐标 → 模型地址；行号列/列头返回 null */
+  private toSheetAddr;
+  /** 模型地址 → VTable 坐标 */
+  private toTableCoord;
+  private buildColumns;
+  private buildRecords;
+  private buildOptions;
+  private bindTableEvents;
+  private bindSheetEvents;
+  /** 模型格 → 表格 record（显示值；公式格为计算缓存） */
+  private pushCellToTable;
+  /**
+   * 键盘绑定：Cmd/Ctrl+Z undo，Cmd/Ctrl+Shift+Z 与 Ctrl+Y redo。
+   * 编辑器打开时（事件来自编辑器 input）不拦截，保留文本编辑自身的撤销行为。
+   */
+  private bindKeyboard;
+}
+//#endregion
+export { SheetGrid, SheetGridOptions };
+//# sourceMappingURL=sheet-grid.d.ts.map

package/dist/grid/sheet-grid.js

@@ -0,0 +1,230 @@
+import { cellKey, colIndexToName, createRange } from "../core/address.js";
+import { ListTable, register } from "@visactor/vtable";
+import { InputEditor } from "@visactor/vtable-editors";
+//#region src/grid/sheet-grid.ts
+/**
+* VTable 适配层：数据模型完全自持有，ListTable 只做渲染与输入。
+*
+* - 模型 → VTable：records 由 store 行视图桥接；customMergeCell 闭包直读 MergeManager
+*   （VTable 逐格动态求值、无缓存，合并变更后 setRecords 重建场景树即生效）
+* - VTable → 模型：change_cell_value 回写 store；selected_cell 经 resolveAnchor 更新选区
+* - 公式：公式格 record 存计算缓存（显示值）；进入编辑时编辑器显示公式原文（'=f'）。
+*   编辑提交期间模型变更（含公式重算派生格）先入待同步队列，提交结束统一回推表格——
+*   VTable 自己只更新了被编辑格的 record（还是输入文本），派生格它不知道
+* - 键盘：容器 keydown 绑定 undo/redo（Cmd/Ctrl+Z、Cmd/Ctrl+Shift+Z、Ctrl+Y），
+*   编辑器 input 打开时不拦截
+* - 坐标换算：行号列不计入 rowHeaderLevelCount，偏移量在首个表格实例上
+*   用 columnHeaderLevelCount + isSeriesNumber 实测并缓存（见 getOffsets）
+*/
+/** 公式感知编辑器：进入编辑时公式格显示原文（同 Excel），其余格显示当前值 */
+var FormulaAwareInputEditor = class extends InputEditor {
+	/** 由 SheetGrid 注入：返回进入编辑时应显示的文本；undefined = 用 VTable 默认值 */
+	resolveEditText;
+	onStart(context) {
+		const text = this.resolveEditText?.(context.col, context.row);
+		super.onStart(text === void 0 ? context : {
+			...context,
+			value: text
+		});
+	}
+};
+/** 编辑器按 grid 实例注册（hook 闭包各自 sheet），名称递增防冲突 */
+let editorSeq = 0;
+var SheetGrid = class {
+	sheet;
+	table;
+	container;
+	rows;
+	cols;
+	editorName;
+	disposers = [];
+	/** 编辑提交期间累积的模型变更（提交结束统一回推表格，覆盖公式派生格） */
+	pendingTableSync = null;
+	/** 实测坐标偏移（行号列数 / 列头行数），首次使用时测量 */
+	offsets;
+	constructor(options) {
+		this.sheet = options.sheet;
+		this.container = options.container;
+		this.rows = options.rows ?? 100;
+		this.cols = options.cols ?? 26;
+		this.editorName = `veltra-sheet-input-${editorSeq++}`;
+		const editor = new FormulaAwareInputEditor();
+		editor.resolveEditText = (col, row) => {
+			const addr = this.toSheetAddr(this.table, col, row);
+			if (!addr) return void 0;
+			const data = this.sheet.getCellData(this.sheet.merges.resolveAnchor(addr));
+			return data?.f ? `=${data.f}` : void 0;
+		};
+		register.editor(this.editorName, editor);
+		this.table = new ListTable(options.container, this.buildOptions());
+		this.bindTableEvents();
+		this.bindSheetEvents();
+		this.bindKeyboard();
+	}
+	/** 底层 ListTable 实例（调试与测试用） */
+	getTable() {
+		return this.table;
+	}
+	/** 全量刷新（合并结构变化、批量数据变更后调用） */
+	refresh() {
+		this.table.setRecords(this.buildRecords());
+	}
+	/** 撤销一步（模型命令历史） */
+	undo() {
+		return this.sheet.undo();
+	}
+	/** 重做一步（模型命令历史） */
+	redo() {
+		return this.sheet.redo();
+	}
+	release() {
+		for (const dispose of this.disposers) dispose();
+		this.disposers.length = 0;
+		this.table.release();
+	}
+	/**
+	* 实测偏移：列头行数取 columnHeaderLevelCount；
+	* 行号列不被计入 rowHeaderLevelCount，用 isSeriesNumber 逐列探测。
+	* 结果缓存（表格实例不变，布局不变）。
+	*/
+	getOffsets(table) {
+		if (!this.offsets) {
+			const rowOffset = table.columnHeaderLevelCount;
+			let colOffset = 0;
+			while (colOffset < table.colCount && table.isSeriesNumber(colOffset, rowOffset)) colOffset++;
+			this.offsets = {
+				colOffset,
+				rowOffset
+			};
+		}
+		return this.offsets;
+	}
+	/** VTable 坐标 → 模型地址；行号列/列头返回 null */
+	toSheetAddr(table, col, row) {
+		const { colOffset, rowOffset } = this.getOffsets(table);
+		const addr = {
+			row: row - rowOffset,
+			col: col - colOffset
+		};
+		if (addr.row < 0 || addr.col < 0) return null;
+		return addr;
+	}
+	/** 模型地址 → VTable 坐标 */
+	toTableCoord(table, addr) {
+		const { colOffset, rowOffset } = this.getOffsets(table);
+		return {
+			col: addr.col + colOffset,
+			row: addr.row + rowOffset
+		};
+	}
+	buildColumns() {
+		return Array.from({ length: this.cols }, (_, col) => ({
+			field: String(col),
+			title: colIndexToName(col)
+		}));
+	}
+	buildRecords() {
+		const records = Array.from({ length: this.rows }, () => ({}));
+		for (const [addr, data] of this.sheet.store.entries()) if (addr.row < this.rows && addr.col < this.cols && data.v != null) records[addr.row][String(addr.col)] = data.v;
+		return records;
+	}
+	buildOptions() {
+		return {
+			records: this.buildRecords(),
+			columns: this.buildColumns(),
+			widthMode: "standard",
+			rowSeriesNumber: { width: 46 },
+			editor: this.editorName,
+			editCellTrigger: "doubleclick",
+			keyboardOptions: {
+				moveFocusCellOnTab: true,
+				editCellOnEnter: true,
+				moveFocusCellOnEnter: true,
+				moveEditCellOnArrowKeys: true,
+				selectAllOnCtrlA: true
+			},
+			customMergeCell: (col, row, table) => {
+				const addr = this.toSheetAddr(table, col, row);
+				if (!addr) return void 0;
+				const merge = this.sheet.merges.getMergeAt(addr);
+				if (!merge) return void 0;
+				const anchorCoord = this.toTableCoord(table, merge.start);
+				const recordValue = table.getCellOriginValue(anchorCoord.col, anchorCoord.row);
+				return {
+					range: {
+						start: anchorCoord,
+						end: this.toTableCoord(table, merge.end)
+					},
+					text: recordValue == null ? "" : String(recordValue)
+				};
+			}
+		};
+	}
+	bindTableEvents() {
+		this.table.on(ListTable.EVENT_TYPE.CHANGE_CELL_VALUE, (args) => {
+			const addr = this.toSheetAddr(this.table, args.col, args.row);
+			if (addr == null) return;
+			this.pendingTableSync = /* @__PURE__ */ new Map([[cellKey(addr), addr]]);
+			try {
+				this.sheet.setCellValue(addr, args.changedValue ?? null);
+			} finally {
+				const pending = this.pendingTableSync;
+				this.pendingTableSync = null;
+				if (pending) for (const pendingAddr of pending.values()) this.pushCellToTable(pendingAddr);
+			}
+		});
+		this.table.on(ListTable.EVENT_TYPE.SELECTED_CELL, (args) => {
+			const addr = this.toSheetAddr(this.table, args.col, args.row);
+			if (addr == null) return;
+			this.sheet.selectCell(addr);
+		});
+		this.table.on(ListTable.EVENT_TYPE.DRAG_SELECT_END, () => {
+			const range = this.table.getSelectedCellRanges()[0];
+			if (!range) return;
+			const start = this.toSheetAddr(this.table, range.start.col, range.start.row);
+			const end = this.toSheetAddr(this.table, range.end.col, range.end.row);
+			if (!start || !end) return;
+			this.sheet.selectRange(createRange(start, end));
+		});
+	}
+	bindSheetEvents() {
+		this.disposers.push(this.sheet.on("cell-change", ({ addr }) => {
+			if (this.pendingTableSync) {
+				this.pendingTableSync.set(cellKey(addr), addr);
+				return;
+			}
+			this.pushCellToTable(addr);
+		}));
+		this.disposers.push(this.sheet.on("merge-change", () => {
+			this.refresh();
+		}));
+	}
+	/** 模型格 → 表格 record（显示值；公式格为计算缓存） */
+	pushCellToTable(addr) {
+		const { col, row } = this.toTableCoord(this.table, addr);
+		const value = this.sheet.getDisplayValue(addr);
+		this.table.changeCellValue(col, row, value, false, false);
+	}
+	/**
+	* 键盘绑定：Cmd/Ctrl+Z undo，Cmd/Ctrl+Shift+Z 与 Ctrl+Y redo。
+	* 编辑器打开时（事件来自编辑器 input）不拦截，保留文本编辑自身的撤销行为。
+	*/
+	bindKeyboard() {
+		const onKeyDown = (event) => {
+			if (event.target instanceof HTMLInputElement || event.target instanceof HTMLTextAreaElement) return;
+			if (!(event.metaKey || event.ctrlKey)) return;
+			const key = event.key.toLowerCase();
+			if (key === "z" && !event.shiftKey) {
+				if (this.undo()) event.preventDefault();
+			} else if (key === "z" && event.shiftKey || key === "y" && event.ctrlKey) {
+				if (this.redo()) event.preventDefault();
+			}
+		};
+		this.container.addEventListener("keydown", onKeyDown);
+		this.disposers.push(() => this.container.removeEventListener("keydown", onKeyDown));
+	}
+};
+//#endregion
+export { SheetGrid };
+
+//# sourceMappingURL=sheet-grid.js.map

package/dist/grid/sheet-grid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sheet-grid.js","names":[],"sources":["../../src/grid/sheet-grid.ts"],"sourcesContent":["import { ListTable, register } from '@visactor/vtable'\nimport type { ListTableConstructorOptions } from '@visactor/vtable'\nimport { InputEditor } from '@visactor/vtable-editors'\nimport type { EditContext } from '@visactor/vtable-editors'\n\nimport type { CellAddress } from '../core/address'\nimport { cellKey, colIndexToName, createRange } from '../core/address'\nimport type { CellValue } from '../core/cell-store'\nimport type { Sheet } from '../core/sheet'\n\n/**\n * VTable 适配层：数据模型完全自持有，ListTable 只做渲染与输入。\n *\n * - 模型 → VTable：records 由 store 行视图桥接；customMergeCell 闭包直读 MergeManager\n *   （VTable 逐格动态求值、无缓存，合并变更后 setRecords 重建场景树即生效）\n * - VTable → 模型：change_cell_value 回写 store；selected_cell 经 resolveAnchor 更新选区\n * - 公式：公式格 record 存计算缓存（显示值）；进入编辑时编辑器显示公式原文（'=f'）。\n *   编辑提交期间模型变更（含公式重算派生格）先入待同步队列，提交结束统一回推表格——\n *   VTable 自己只更新了被编辑格的 record（还是输入文本），派生格它不知道\n * - 键盘：容器 keydown 绑定 undo/redo（Cmd/Ctrl+Z、Cmd/Ctrl+Shift+Z、Ctrl+Y），\n *   编辑器 input 打开时不拦截\n * - 坐标换算：行号列不计入 rowHeaderLevelCount，偏移量在首个表格实例上\n *   用 columnHeaderLevelCount + isSeriesNumber 实测并缓存（见 getOffsets）\n */\n\n/** 公式感知编辑器：进入编辑时公式格显示原文（同 Excel），其余格显示当前值 */\nclass FormulaAwareInputEditor extends InputEditor {\n  /** 由 SheetGrid 注入：返回进入编辑时应显示的文本；undefined = 用 VTable 默认值 */\n  resolveEditText?: (col: number, row: number) => string | undefined\n\n  override onStart(context: EditContext<string>): void {\n    const text = this.resolveEditText?.(context.col, context.row)\n    super.onStart(text === undefined ? context : { ...context, value: text })\n  }\n}\n\n/** 编辑器按 grid 实例注册（hook 闭包各自 sheet），名称递增防冲突 */\nlet editorSeq = 0\n\nexport interface SheetGridOptions {\n  container: HTMLElement\n  sheet: Sheet\n  /** 渲染行数，默认 100 */\n  rows?: number\n  /** 渲染列数，默认 26（A..Z） */\n  cols?: number\n}\n\nexport class SheetGrid {\n  private readonly sheet: Sheet\n  private readonly table: ListTable\n  private readonly container: HTMLElement\n  private readonly rows: number\n  private readonly cols: number\n  private readonly editorName: string\n  private readonly disposers: (() => void)[] = []\n  /** 编辑提交期间累积的模型变更（提交结束统一回推表格，覆盖公式派生格） */\n  private pendingTableSync: Map<number, CellAddress> | null = null\n  /** 实测坐标偏移（行号列数 / 列头行数），首次使用时测量 */\n  private offsets?: { colOffset: number; rowOffset: number }\n\n  constructor(options: SheetGridOptions) {\n    this.sheet = options.sheet\n    this.container = options.container\n    this.rows = options.rows ?? 100\n    this.cols = options.cols ?? 26\n\n    // 每个 grid 实例注册自己的编辑器（hook 闭包本实例的 sheet 与坐标换算）\n    this.editorName = `veltra-sheet-input-${editorSeq++}`\n    const editor = new FormulaAwareInputEditor()\n    editor.resolveEditText = (col, row) => {\n      const addr = this.toSheetAddr(this.table, col, row)\n      if (!addr) return undefined\n      const data = this.sheet.getCellData(this.sheet.merges.resolveAnchor(addr))\n      return data?.f ? `=${data.f}` : undefined\n    }\n    register.editor(this.editorName, editor)\n\n    this.table = new ListTable(options.container, this.buildOptions())\n    this.bindTableEvents()\n    this.bindSheetEvents()\n    this.bindKeyboard()\n  }\n\n  /** 底层 ListTable 实例（调试与测试用） */\n  getTable(): ListTable {\n    return this.table\n  }\n\n  /** 全量刷新（合并结构变化、批量数据变更后调用） */\n  refresh(): void {\n    this.table.setRecords(this.buildRecords())\n  }\n\n  /** 撤销一步（模型命令历史） */\n  undo(): boolean {\n    return this.sheet.undo()\n  }\n\n  /** 重做一步（模型命令历史） */\n  redo(): boolean {\n    return this.sheet.redo()\n  }\n\n  release(): void {\n    for (const dispose of this.disposers) dispose()\n    this.disposers.length = 0\n    this.table.release()\n  }\n\n  // ─── 坐标换算 ─────────────────────────────────────────────\n\n  /**\n   * 实测偏移：列头行数取 columnHeaderLevelCount；\n   * 行号列不被计入 rowHeaderLevelCount，用 isSeriesNumber 逐列探测。\n   * 结果缓存（表格实例不变，布局不变）。\n   */\n  private getOffsets(table: ListTable): { colOffset: number; rowOffset: number } {\n    if (!this.offsets) {\n      const rowOffset = table.columnHeaderLevelCount\n      let colOffset = 0\n      while (colOffset < table.colCount && table.isSeriesNumber(colOffset, rowOffset)) colOffset++\n      this.offsets = { colOffset, rowOffset }\n    }\n    return this.offsets\n  }\n\n  /** VTable 坐标 → 模型地址；行号列/列头返回 null */\n  private toSheetAddr(table: ListTable, col: number, row: number): CellAddress | null {\n    const { colOffset, rowOffset } = this.getOffsets(table)\n    const addr = { row: row - rowOffset, col: col - colOffset }\n    if (addr.row < 0 || addr.col < 0) return null\n    return addr\n  }\n\n  /** 模型地址 → VTable 坐标 */\n  private toTableCoord(table: ListTable, addr: CellAddress): { col: number; row: number } {\n    const { colOffset, rowOffset } = this.getOffsets(table)\n    return { col: addr.col + colOffset, row: addr.row + rowOffset }\n  }\n\n  // ─── 模型 → VTable ────────────────────────────────────────\n\n  private buildColumns() {\n    return Array.from({ length: this.cols }, (_, col) => ({\n      field: String(col),\n      title: colIndexToName(col)\n    }))\n  }\n\n  private buildRecords(): Record<string, CellValue>[] {\n    const records: Record<string, CellValue>[] = Array.from({ length: this.rows }, () => ({}))\n    for (const [addr, data] of this.sheet.store.entries()) {\n      if (addr.row < this.rows && addr.col < this.cols && data.v != null) {\n        records[addr.row]![String(addr.col)] = data.v\n      }\n    }\n    return records\n  }\n\n  private buildOptions(): ListTableConstructorOptions {\n    return {\n      records: this.buildRecords(),\n      columns: this.buildColumns(),\n      widthMode: 'standard',\n      rowSeriesNumber: { width: 46 },\n      editor: this.editorName,\n      editCellTrigger: 'doubleclick',\n      keyboardOptions: {\n        moveFocusCellOnTab: true,\n        editCellOnEnter: true,\n        moveFocusCellOnEnter: true,\n        moveEditCellOnArrowKeys: true,\n        selectAllOnCtrlA: true\n      },\n      customMergeCell: (col, row, table) => {\n        const addr = this.toSheetAddr(table as ListTable, col, row)\n        if (!addr) return undefined\n        const merge = this.sheet.merges.getMergeAt(addr)\n        if (!merge) return undefined\n        const anchorCoord = this.toTableCoord(table as ListTable, merge.start)\n        const recordValue = (table as ListTable).getCellOriginValue(\n          anchorCoord.col,\n          anchorCoord.row\n        )\n        return {\n          range: { start: anchorCoord, end: this.toTableCoord(table as ListTable, merge.end) },\n          // 关键 1：必须携带 text。VTable 的 getCellRange 仅在 text/customLayout/\n          // customRender 有效时才认这个自定义合并——没有 text 时选区与编辑不会\n          // 扩展为整个合并区域，且合并格渲染为空。\n          // 关键 2：text 必须读 VTable records 而非模型。编辑提交的顺序是\n          // 先更新 record → 重绘 → 最后才发 change_cell_value 回写模型；\n          // 若此时读模型，拿到的还是回写前的旧值（合并格显示旧文本）。\n          text: recordValue == null ? '' : String(recordValue)\n        }\n      }\n    }\n  }\n\n  // ─── 事件桥接 ─────────────────────────────────────────────\n\n  private bindTableEvents(): void {\n    this.table.on(ListTable.EVENT_TYPE.CHANGE_CELL_VALUE, (args) => {\n      const addr = this.toSheetAddr(this.table, args.col, args.row)\n      if (addr == null) return\n      // 编辑提交期间模型变更（含公式重算派生格）先入队列，提交结束统一回推。\n      // 被编辑格自身也入队：VTable 已把输入文本写进 record，公式格需回推计算值\n      this.pendingTableSync = new Map([[cellKey(addr), addr]])\n      try {\n        this.sheet.setCellValue(addr, args.changedValue ?? null)\n      } finally {\n        const pending = this.pendingTableSync\n        this.pendingTableSync = null\n        if (pending) {\n          for (const pendingAddr of pending.values()) this.pushCellToTable(pendingAddr)\n        }\n      }\n    })\n\n    this.table.on(ListTable.EVENT_TYPE.SELECTED_CELL, (args) => {\n      const addr = this.toSheetAddr(this.table, args.col, args.row)\n      if (addr == null) return\n      this.sheet.selectCell(addr)\n    })\n\n    // 拖选结束 → 选区同步为区域（合并等区域操作的前提）\n    this.table.on(ListTable.EVENT_TYPE.DRAG_SELECT_END, () => {\n      const range = this.table.getSelectedCellRanges()[0]\n      if (!range) return\n      const start = this.toSheetAddr(this.table, range.start.col, range.start.row)\n      const end = this.toSheetAddr(this.table, range.end.col, range.end.row)\n      if (!start || !end) return\n      this.sheet.selectRange(createRange(start, end))\n    })\n  }\n\n  private bindSheetEvents(): void {\n    this.disposers.push(\n      this.sheet.on('cell-change', ({ addr }) => {\n        if (this.pendingTableSync) {\n          this.pendingTableSync.set(cellKey(addr), addr)\n          return\n        }\n        this.pushCellToTable(addr)\n      })\n    )\n\n    this.disposers.push(\n      this.sheet.on('merge-change', () => {\n        this.refresh()\n      })\n    )\n  }\n\n  /** 模型格 → 表格 record（显示值；公式格为计算缓存） */\n  private pushCellToTable(addr: CellAddress): void {\n    const { col, row } = this.toTableCoord(this.table, addr)\n    const value = this.sheet.getDisplayValue(addr)\n    this.table.changeCellValue(col, row, value as string | number | null, false, false)\n  }\n\n  /**\n   * 键盘绑定：Cmd/Ctrl+Z undo，Cmd/Ctrl+Shift+Z 与 Ctrl+Y redo。\n   * 编辑器打开时（事件来自编辑器 input）不拦截，保留文本编辑自身的撤销行为。\n   */\n  private bindKeyboard(): void {\n    const onKeyDown = (event: KeyboardEvent): void => {\n      if (event.target instanceof HTMLInputElement || event.target instanceof HTMLTextAreaElement) {\n        return\n      }\n      const mod = event.metaKey || event.ctrlKey\n      if (!mod) return\n      const key = event.key.toLowerCase()\n      if (key === 'z' && !event.shiftKey) {\n        if (this.undo()) event.preventDefault()\n      } else if ((key === 'z' && event.shiftKey) || (key === 'y' && event.ctrlKey)) {\n        if (this.redo()) event.preventDefault()\n      }\n    }\n    this.container.addEventListener('keydown', onKeyDown)\n    this.disposers.push(() => this.container.removeEventListener('keydown', onKeyDown))\n  }\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { COL_KEY_BASE, CellAddress, CellRange, addressFromKey, addressesEqual, boundingBox, cellKey, colIndexToName, colNameToIndex, createRange, formatAddress, formatRange, iterateRange, parseAddress, parseRange, rangeContainsAddress, rangeContainsRange, rangeSize, rangesEqual, rangesIntersect } from "./core/address.js";
+import { CellData, CellSnapshotItem, CellStore, CellType, CellValue, cellDataEqual, inferCellType, isEmptyCellData } from "./core/cell-store.js";
+import { CellInfo, MergeManager, MergeResult, MergedCellKind } from "./core/merge-manager.js";
+import { SelectionModel, SelectionState } from "./core/selection.js";
+import { CellPatch, Command, CommandContext, CommandResult, MergePatch, Mutation, Patch, PatchDirection } from "./core/command/types.js";
+import { DEFAULT_HISTORY_CAPACITY, HistoryManager, HistoryState } from "./core/command/history.js";
+import { SetCellValueCommand, SetCellValueItem, SetCellValueParams } from "./core/command/set-cell-value.js";
+import { AstNode, AstReference, BinaryOperator, collectReferences } from "./core/formula/ast.js";
+import { DependencyGraph, FormulaDependency, FormulaNode } from "./core/formula/dependency-graph.js";
+import { Sheet, SheetEvents } from "./core/sheet.js";
+import { Workbook, WorkbookEvents } from "./core/workbook.js";
+import { CommandRegistry } from "./core/command/registry.js";
+import { SetCellFormulaCommand, SetCellFormulaParams } from "./core/command/set-cell-formula.js";
+import { MergeCellsCommand, MergeCellsParams, UnmergeCellsCommand, UnmergeCellsParams } from "./core/command/merge-cells.js";
+import { defaultCommandRegistry } from "./core/command/default-registry.js";
+import { FORMULA_ERROR_CODES, FormulaError, FormulaErrorCode, formulaError, isFormulaError, isFormulaErrorCode } from "./core/formula/errors.js";
+import { FormulaOperator, FormulaParseError, FormulaToken, tokenizeFormula } from "./core/formula/tokenizer.js";
+import { parseFormula } from "./core/formula/parser.js";
+import { EvalValue, FormulaEvalContext, ScalarValue, coerceToBoolean, coerceToNumber, coerceToText, compareScalars, evaluateAst } from "./core/formula/evaluator.js";
+import { FormulaFunction, getFormulaFunction, invokeFormulaFunction, registerFormulaFunction } from "./core/formula/functions.js";
+import { SheetGrid, SheetGridOptions } from "./grid/sheet-grid.js";
+import { SheetContext, createSheetContext } from "./tools/context.js";
+import { DEFAULT_TOOL_GROUP, SheetTool, SheetToolGroup, ToolRegistry, defaultToolRegistry, registerTool, unregisterTool } from "./tools/registry.js";
+import { SheetEmits, SheetExposed, SheetProps, _SheetExposed } from "./types/sheet.js";
+import "./types/index.js";
+import _default from "./vue/sheet.vue.js";
+import "./vue/index.js";
+export { AstNode, AstReference, BinaryOperator, COL_KEY_BASE, CellAddress, CellData, CellInfo, CellPatch, CellRange, CellSnapshotItem, CellStore, CellType, CellValue, Command, CommandContext, CommandRegistry, CommandResult, DEFAULT_HISTORY_CAPACITY, DEFAULT_TOOL_GROUP, DependencyGraph, EvalValue, FORMULA_ERROR_CODES, FormulaDependency, FormulaError, FormulaErrorCode, FormulaEvalContext, FormulaFunction, FormulaNode, FormulaOperator, FormulaParseError, FormulaToken, HistoryManager, HistoryState, MergeCellsCommand, MergeCellsParams, MergeManager, MergePatch, MergeResult, MergedCellKind, Mutation, Patch, PatchDirection, ScalarValue, SelectionModel, SelectionState, SetCellFormulaCommand, SetCellFormulaParams, SetCellValueCommand, SetCellValueItem, SetCellValueParams, Sheet, SheetContext, SheetEmits, SheetEvents, SheetExposed, SheetGrid, SheetGridOptions, SheetProps, SheetTool, SheetToolGroup, ToolRegistry, _default as USheet, UnmergeCellsCommand, UnmergeCellsParams, Workbook, WorkbookEvents, _SheetExposed, addressFromKey, addressesEqual, boundingBox, cellDataEqual, cellKey, coerceToBoolean, coerceToNumber, coerceToText, colIndexToName, colNameToIndex, collectReferences, compareScalars, createRange, createSheetContext, defaultCommandRegistry, defaultToolRegistry, evaluateAst, formatAddress, formatRange, formulaError, getFormulaFunction, inferCellType, invokeFormulaFunction, isEmptyCellData, isFormulaError, isFormulaErrorCode, iterateRange, parseAddress, parseFormula, parseRange, rangeContainsAddress, rangeContainsRange, rangeSize, rangesEqual, rangesIntersect, registerFormulaFunction, registerTool, tokenizeFormula, unregisterTool };

package/dist/index.js

@@ -0,0 +1,25 @@
+import { COL_KEY_BASE, addressFromKey, addressesEqual, boundingBox, cellKey, colIndexToName, colNameToIndex, createRange, formatAddress, formatRange, iterateRange, parseAddress, parseRange, rangeContainsAddress, rangeContainsRange, rangeSize, rangesEqual, rangesIntersect } from "./core/address.js";
+import { DEFAULT_TOOL_GROUP, ToolRegistry, defaultToolRegistry, registerTool, unregisterTool } from "./tools/registry.js";
+import "./tools/builtin.js";
+import { CellStore, cellDataEqual, inferCellType, isEmptyCellData } from "./core/cell-store.js";
+import { MergeManager } from "./core/merge-manager.js";
+import { SelectionModel } from "./core/selection.js";
+import { MergeCellsCommand, UnmergeCellsCommand } from "./core/command/merge-cells.js";
+import { CommandRegistry } from "./core/command/registry.js";
+import { SetCellFormulaCommand } from "./core/command/set-cell-formula.js";
+import { SetCellValueCommand } from "./core/command/set-cell-value.js";
+import { defaultCommandRegistry } from "./core/command/default-registry.js";
+import { DEFAULT_HISTORY_CAPACITY, HistoryManager } from "./core/command/history.js";
+import { collectReferences } from "./core/formula/ast.js";
+import { FORMULA_ERROR_CODES, formulaError, isFormulaError, isFormulaErrorCode } from "./core/formula/errors.js";
+import { coerceToBoolean, coerceToNumber, coerceToText, compareScalars, evaluateAst } from "./core/formula/evaluator.js";
+import { getFormulaFunction, invokeFormulaFunction, registerFormulaFunction } from "./core/formula/functions.js";
+import { FormulaParseError, tokenizeFormula } from "./core/formula/tokenizer.js";
+import { parseFormula } from "./core/formula/parser.js";
+import { DependencyGraph } from "./core/formula/dependency-graph.js";
+import { Sheet } from "./core/sheet.js";
+import { Workbook } from "./core/workbook.js";
+import { SheetGrid } from "./grid/sheet-grid.js";
+import { createSheetContext } from "./tools/context.js";
+import _sfc_main from "./vue/sheet.js";
+export { COL_KEY_BASE, CellStore, CommandRegistry, DEFAULT_HISTORY_CAPACITY, DEFAULT_TOOL_GROUP, DependencyGraph, FORMULA_ERROR_CODES, FormulaParseError, HistoryManager, MergeCellsCommand, MergeManager, SelectionModel, SetCellFormulaCommand, SetCellValueCommand, Sheet, SheetGrid, ToolRegistry, _sfc_main as USheet, UnmergeCellsCommand, Workbook, addressFromKey, addressesEqual, boundingBox, cellDataEqual, cellKey, coerceToBoolean, coerceToNumber, coerceToText, colIndexToName, colNameToIndex, collectReferences, compareScalars, createRange, createSheetContext, defaultCommandRegistry, defaultToolRegistry, evaluateAst, formatAddress, formatRange, formulaError, getFormulaFunction, inferCellType, invokeFormulaFunction, isEmptyCellData, isFormulaError, isFormulaErrorCode, iterateRange, parseAddress, parseFormula, parseRange, rangeContainsAddress, rangeContainsRange, rangeSize, rangesEqual, rangesIntersect, registerFormulaFunction, registerTool, tokenizeFormula, unregisterTool };

package/dist/tools/builtin.js

@@ -0,0 +1,72 @@
+import { rangesEqual } from "../core/address.js";
+import { registerTool } from "./registry.js";
+//#region src/tools/builtin.ts
+/**
+* 内置工具（dogfood 扩展机制）：undo/redo + 合并/取消合并。
+*
+* 与第三方工具走同一注册通道，可由宿主 unregisterTool 移除或同 id 覆盖。
+* 本模块由 tools/index.ts 引入（与 core/command 的 default-registry 同构）：
+* 经包入口导入即完成注册，无头使用 core 深导入不涉及此全局副作用。
+*/
+registerTool({
+	id: "undo",
+	title: "撤销",
+	tooltip: "撤销（Ctrl/Cmd+Z）",
+	group: "history",
+	order: 0,
+	disabled: (ctx) => !ctx.canUndo,
+	onClick: (ctx) => {
+		ctx.undo();
+	}
+});
+registerTool({
+	id: "redo",
+	title: "重做",
+	tooltip: "重做（Ctrl/Cmd+Shift+Z 或 Ctrl+Y）",
+	group: "history",
+	order: 1,
+	disabled: (ctx) => !ctx.canRedo,
+	onClick: (ctx) => {
+		ctx.redo();
+	}
+});
+registerTool({
+	id: "merge",
+	title: "合并",
+	tooltip: "合并选中区域",
+	group: "cell",
+	order: 0,
+	disabled: (ctx) => {
+		const { activeCell, ranges } = ctx.getSelection();
+		const range = ranges[0];
+		if (!activeCell || !range) return true;
+		if (range.start.row === range.end.row && range.start.col === range.end.col) return true;
+		const mergeRange = ctx.getCellInfo(activeCell).mergeRange;
+		return !!mergeRange && rangesEqual(mergeRange, range);
+	},
+	onClick: (ctx) => {
+		const range = ctx.getSelection().ranges[0];
+		if (!range) return;
+		ctx.mergeCells(range);
+	}
+});
+registerTool({
+	id: "unmerge",
+	title: "取消合并",
+	tooltip: "取消活动格所在合并",
+	group: "cell",
+	order: 1,
+	disabled: (ctx) => {
+		const { activeCell } = ctx.getSelection();
+		if (!activeCell) return true;
+		return !ctx.getCellInfo(activeCell).mergeRange;
+	},
+	onClick: (ctx) => {
+		const { activeCell, ranges } = ctx.getSelection();
+		if (!activeCell || !ranges[0]) return;
+		ctx.unmergeCells(ranges[0]);
+	}
+});
+//#endregion
+
+//# sourceMappingURL=builtin.js.map

package/dist/tools/builtin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin.js","names":[],"sources":["../../src/tools/builtin.ts"],"sourcesContent":["import { rangesEqual } from '../core/address'\nimport { registerTool } from './registry'\n\n/**\n * 内置工具（dogfood 扩展机制）：undo/redo + 合并/取消合并。\n *\n * 与第三方工具走同一注册通道，可由宿主 unregisterTool 移除或同 id 覆盖。\n * 本模块由 tools/index.ts 引入（与 core/command 的 default-registry 同构）：\n * 经包入口导入即完成注册，无头使用 core 深导入不涉及此全局副作用。\n */\n\nregisterTool({\n  id: 'undo',\n  title: '撤销',\n  tooltip: '撤销（Ctrl/Cmd+Z）',\n  group: 'history',\n  order: 0,\n  disabled: (ctx) => !ctx.canUndo,\n  onClick: (ctx) => {\n    ctx.undo()\n  }\n})\n\nregisterTool({\n  id: 'redo',\n  title: '重做',\n  tooltip: '重做（Ctrl/Cmd+Shift+Z 或 Ctrl+Y）',\n  group: 'history',\n  order: 1,\n  disabled: (ctx) => !ctx.canRedo,\n  onClick: (ctx) => {\n    ctx.redo()\n  }\n})\n\nregisterTool({\n  id: 'merge',\n  title: '合并',\n  tooltip: '合并选中区域',\n  group: 'cell',\n  order: 0,\n  disabled: (ctx) => {\n    const { activeCell, ranges } = ctx.getSelection()\n    const range = ranges[0]\n    if (!activeCell || !range) return true\n    // 单格无可合并\n    if (range.start.row === range.end.row && range.start.col === range.end.col) return true\n    // 选区恰好等于既有合并区域 → 无操作必要\n    const mergeRange = ctx.getCellInfo(activeCell).mergeRange\n    return !!mergeRange && rangesEqual(mergeRange, range)\n  },\n  onClick: (ctx) => {\n    const range = ctx.getSelection().ranges[0]\n    if (!range) return\n    ctx.mergeCells(range)\n  }\n})\n\nregisterTool({\n  id: 'unmerge',\n  title: '取消合并',\n  tooltip: '取消活动格所在合并',\n  group: 'cell',\n  order: 1,\n  disabled: (ctx) => {\n    const { activeCell } = ctx.getSelection()\n    if (!activeCell) return true\n    return !ctx.getCellInfo(activeCell).mergeRange\n  },\n  onClick: (ctx) => {\n    const { activeCell, ranges } = ctx.getSelection()\n    if (!activeCell || !ranges[0]) return\n    ctx.unmergeCells(ranges[0])\n  }\n})\n"],"mappings":";;;;;;;;;;AAWA,aAAa;CACX,IAAI;CACJ,OAAO;CACP,SAAS;CACT,OAAO;CACP,OAAO;CACP,WAAW,QAAQ,CAAC,IAAI;CACxB,UAAU,QAAQ;EAChB,IAAI,KAAK;CACX;AACF,CAAC;AAED,aAAa;CACX,IAAI;CACJ,OAAO;CACP,SAAS;CACT,OAAO;CACP,OAAO;CACP,WAAW,QAAQ,CAAC,IAAI;CACxB,UAAU,QAAQ;EAChB,IAAI,KAAK;CACX;AACF,CAAC;AAED,aAAa;CACX,IAAI;CACJ,OAAO;CACP,SAAS;CACT,OAAO;CACP,OAAO;CACP,WAAW,QAAQ;EACjB,MAAM,EAAE,YAAY,WAAW,IAAI,aAAa;EAChD,MAAM,QAAQ,OAAO;EACrB,IAAI,CAAC,cAAc,CAAC,OAAO,OAAO;EAElC,IAAI,MAAM,MAAM,QAAQ,MAAM,IAAI,OAAO,MAAM,MAAM,QAAQ,MAAM,IAAI,KAAK,OAAO;EAEnF,MAAM,aAAa,IAAI,YAAY,UAAU,CAAC,CAAC;EAC/C,OAAO,CAAC,CAAC,cAAc,YAAY,YAAY,KAAK;CACtD;CACA,UAAU,QAAQ;EAChB,MAAM,QAAQ,IAAI,aAAa,CAAC,CAAC,OAAO;EACxC,IAAI,CAAC,OAAO;EACZ,IAAI,WAAW,KAAK;CACtB;AACF,CAAC;AAED,aAAa;CACX,IAAI;CACJ,OAAO;CACP,SAAS;CACT,OAAO;CACP,OAAO;CACP,WAAW,QAAQ;EACjB,MAAM,EAAE,eAAe,IAAI,aAAa;EACxC,IAAI,CAAC,YAAY,OAAO;EACxB,OAAO,CAAC,IAAI,YAAY,UAAU,CAAC,CAAC;CACtC;CACA,UAAU,QAAQ;EAChB,MAAM,EAAE,YAAY,WAAW,IAAI,aAAa;EAChD,IAAI,CAAC,cAAc,CAAC,OAAO,IAAI;EAC/B,IAAI,aAAa,OAAO,EAAE;CAC5B;AACF,CAAC"}

package/dist/tools/context.d.ts

@@ -0,0 +1,57 @@
+import { CellAddress, CellRange } from "../core/address.js";
+import { CellData, CellValue } from "../core/cell-store.js";
+import { CellInfo } from "../core/merge-manager.js";
+import { SelectionState } from "../core/selection.js";
+import { HistoryState } from "../core/command/history.js";
+import { SetCellValueItem } from "../core/command/set-cell-value.js";
+import { Sheet } from "../core/sheet.js";
+//#region src/tools/context.d.ts
+/**
+ * SheetContext：工具的唯一操作门面。
+ *
+ * 工具（内置与第三方）对表格的全部操作都经由此门面：
+ * - 读方法直达当前活动 sheet（语义与 Sheet 同名方法一致）
+ * - 写方法全部走命令系统，天然进入 undo 历史——扩展无法绕过命令系统
+ * - 不暴露 Sheet 实例本身，保证门面就是扩展能力的全部边界
+ * - USheet 切换 sheet tab 后，同一上下文自动指向新的活动 sheet
+ */
+interface SheetContext {
+  /** 当前活动 sheet 名 */
+  readonly sheetName: string;
+  getSelection(): SelectionState;
+  /** 选中单格（被覆盖格自动定位锚点） */
+  selectCell(addr: CellAddress): void;
+  selectRange(range: CellRange): void;
+  /** 原始存储语义读取（被合并覆盖格 → undefined） */
+  getCellData(addr: CellAddress): CellData | undefined;
+  /** 锚点解析语义读取（被覆盖格 → 锚点的值） */
+  getDisplayValue(addr: CellAddress): CellValue | undefined;
+  /** 合并语义下的单元格信息（普通格 / 合并锚点 / 被覆盖格） */
+  getCellInfo(addr: CellAddress): CellInfo;
+  setCellValue(addr: CellAddress, value: CellValue): void;
+  setCellFormula(addr: CellAddress, formula: string): void;
+  /** 批量写入（一次调用 = 一个 undo 单元） */
+  setCells(items: SetCellValueItem[]): void;
+  mergeCells(range: CellRange): CellRange;
+  unmergeCells(range: CellRange): void;
+  /** 执行命令注册表中的自定义命令（高级扩展点） */
+  executeCommand<R = void>(commandId: string, params: unknown): R | undefined;
+  beginTransaction(): void;
+  commit(): void;
+  rollback(): void;
+  undo(): boolean;
+  redo(): boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  onSelectionChange(handler: (state: SelectionState) => void): () => void;
+  onHistoryChange(handler: (state: HistoryState) => void): () => void;
+}
+/**
+ * 创建工具上下文。
+ * @param resolveSheet 活动 sheet 解析器（USheet 传 `() => activeSheet`，
+ *   tab 切换后上下文自动指向当前 sheet）；也可直接传 Sheet 实例（无头 / 测试场景）
+ */
+declare function createSheetContext(resolveSheet: Sheet | (() => Sheet)): SheetContext;
+//#endregion
+export { SheetContext, createSheetContext };
+//# sourceMappingURL=context.d.ts.map