@veltra/sheet 2.0.0

package/src/core/address.ts

@@ -0,0 +1,166 @@
+/**
+ * A1 地址系统（纯函数）。
+ *
+ * 坐标统一 0-based：`{ row: 0, col: 0 }` 即 A1。
+ * 区域为闭区间，且经过规范化：start 恒为左上角，end 恒为右下角。
+ */
+
+/** 单元格地址（0-based） */
+export interface CellAddress {
+  row: number
+  col: number
+}
+
+/** 单元格区域（闭区间，start 左上角，end 右下角） */
+export interface CellRange {
+  start: CellAddress
+  end: CellAddress
+}
+
+/**
+ * cellKey 的列基数（2^20）。
+ * key = row * COL_KEY_BASE + col，要求 col < COL_KEY_BASE；
+ * JS 安全整数范围内可容纳约 8.5e9 行，远超实际使用。
+ */
+export const COL_KEY_BASE = 2 ** 20
+
+/** 地址 → 数值 key（Map 索引用） */
+export function cellKey(addr: CellAddress): number {
+  return addr.row * COL_KEY_BASE + addr.col
+}
+
+/** 数值 key → 地址 */
+export function addressFromKey(key: number): CellAddress {
+  return { row: Math.floor(key / COL_KEY_BASE), col: key % COL_KEY_BASE }
+}
+
+/** 列号（0-based）→ 列名：0 → 'A'，25 → 'Z'，26 → 'AA' */
+export function colIndexToName(col: number): string {
+  if (!Number.isInteger(col) || col < 0) {
+    throw new RangeError(`列号必须是非负整数: ${col}`)
+  }
+  let name = ''
+  let n = col
+  do {
+    name = String.fromCharCode(65 + (n % 26)) + name
+    n = Math.floor(n / 26) - 1
+  } while (n >= 0)
+  return name
+}
+
+/** 列名 → 列号（0-based）：'A' → 0，'AA' → 26；非法列名返回 -1 */
+export function colNameToIndex(name: string): number {
+  if (!/^[A-Za-z]+$/.test(name)) return -1
+  let index = 0
+  for (const ch of name.toUpperCase()) {
+    index = index * 26 + (ch.charCodeAt(0) - 64)
+  }
+  return index - 1
+}
+
+const ADDRESS_RE = /^\$?([A-Za-z]+)\$?([1-9]\d*)$/
+
+/** 解析 A1 记法（兼容 `$A$1` 绝对引用写法）→ 地址；非法返回 null */
+export function parseAddress(text: string): CellAddress | null {
+  const match = ADDRESS_RE.exec(text.trim())
+  if (!match) return null
+  const col = colNameToIndex(match[1]!)
+  const row = Number.parseInt(match[2]!, 10) - 1
+  return { row, col }
+}
+
+/** 地址 → A1 记法：{ row: 1, col: 1 } → 'B2' */
+export function formatAddress(addr: CellAddress): string {
+  return `${colIndexToName(addr.col)}${addr.row + 1}`
+}
+
+/** 由两个角点构造规范化区域（start ≤ end） */
+export function createRange(a: CellAddress, b: CellAddress): CellRange {
+  return {
+    start: { row: Math.min(a.row, b.row), col: Math.min(a.col, b.col) },
+    end: { row: Math.max(a.row, b.row), col: Math.max(a.col, b.col) }
+  }
+}
+
+/** 解析区域记法：'B2' 或 'B2:D5'（兼容绝对引用）；非法返回 null */
+export function parseRange(text: string): CellRange | null {
+  const parts = text.trim().split(':')
+  if (parts.length > 2) return null
+  const start = parseAddress(parts[0]!)
+  if (!start) return null
+  if (parts.length === 1) return { start, end: { ...start } }
+  const end = parseAddress(parts[1]!)
+  if (!end) return null
+  return createRange(start, end)
+}
+
+/** 区域 → 记法：单格 → 'B2'，多格 → 'B2:D5' */
+export function formatRange(range: CellRange): string {
+  const start = formatAddress(range.start)
+  if (range.start.row === range.end.row && range.start.col === range.end.col) return start
+  return `${start}:${formatAddress(range.end)}`
+}
+
+/** 地址相等 */
+export function addressesEqual(a: CellAddress, b: CellAddress): boolean {
+  return a.row === b.row && a.col === b.col
+}
+
+/** 区域相等 */
+export function rangesEqual(a: CellRange, b: CellRange): boolean {
+  return addressesEqual(a.start, b.start) && addressesEqual(a.end, b.end)
+}
+
+/** 两区域是否相交 */
+export function rangesIntersect(a: CellRange, b: CellRange): boolean {
+  return (
+    a.start.row <= b.end.row &&
+    a.end.row >= b.start.row &&
+    a.start.col <= b.end.col &&
+    a.end.col >= b.start.col
+  )
+}
+
+/** 区域是否包含地址 */
+export function rangeContainsAddress(range: CellRange, addr: CellAddress): boolean {
+  return (
+    addr.row >= range.start.row &&
+    addr.row <= range.end.row &&
+    addr.col >= range.start.col &&
+    addr.col <= range.end.col
+  )
+}
+
+/** 区域是否完整包含另一区域 */
+export function rangeContainsRange(outer: CellRange, inner: CellRange): boolean {
+  return rangeContainsAddress(outer, inner.start) && rangeContainsAddress(outer, inner.end)
+}
+
+/** 一组区域的最小包围盒（至少传入一个区域） */
+export function boundingBox(ranges: readonly [CellRange, ...CellRange[]]): CellRange {
+  let minRow = Infinity
+  let minCol = Infinity
+  let maxRow = -Infinity
+  let maxCol = -Infinity
+  for (const range of ranges) {
+    minRow = Math.min(minRow, range.start.row)
+    minCol = Math.min(minCol, range.start.col)
+    maxRow = Math.max(maxRow, range.end.row)
+    maxCol = Math.max(maxCol, range.end.col)
+  }
+  return { start: { row: minRow, col: minCol }, end: { row: maxRow, col: maxCol } }
+}
+
+/** 按行主序遍历区域内的所有地址 */
+export function* iterateRange(range: CellRange): Generator<CellAddress, void, undefined> {
+  for (let row = range.start.row; row <= range.end.row; row++) {
+    for (let col = range.start.col; col <= range.end.col; col++) {
+      yield { row, col }
+    }
+  }
+}
+
+/** 区域内的单元格数量 */
+export function rangeSize(range: CellRange): number {
+  return (range.end.row - range.start.row + 1) * (range.end.col - range.start.col + 1)
+}

package/src/core/cell-store.ts

@@ -0,0 +1,173 @@
+import type { CellAddress, CellRange } from './address'
+
+/**
+ * 稀疏矩阵存储：`Map<row, Map<col, CellData>>`。
+ * 空单元格 = 存储中不存在该 key（稀疏的第一原则）；
+ * rowCount/colCount 只是高水位，用于渲染行数，不分配空间。
+ */
+
+/** 单元格值类型：n=数字 s=字符串 b=布尔 str=公式结果字符串 e=错误 d=日期（序列数） */
+export type CellType = 'n' | 's' | 'b' | 'str' | 'e' | 'd'
+
+/** 单元格原始值 */
+export type CellValue = string | number | boolean | null
+
+/** 单元格数据（参考 univer ICellData 裁剪版） */
+export interface CellData {
+  /** 原始值（公式格为计算缓存值） */
+  v?: CellValue
+  /** 值类型，缺省按 v 推断 */
+  t?: CellType
+  /** 公式文本（不含 '='），如 'SUM(A1:B2)+Sheet2!C3' */
+  f?: string
+  // s?: StyleId —— 预留样式位，本期不实现
+}
+
+/** 序列化条目（snapshot/restore 用） */
+export interface CellSnapshotItem extends CellData {
+  row: number
+  col: number
+}
+
+/** 按原始值推断类型 */
+export function inferCellType(v: CellValue): CellType | undefined {
+  switch (typeof v) {
+    case 'number':
+      return 'n'
+    case 'boolean':
+      return 'b'
+    case 'string':
+      return 's'
+    default:
+      return undefined
+  }
+}
+
+/** 判定为空：无公式且值为 null/undefined/'' */
+export function isEmptyCellData(data: CellData | undefined): boolean {
+  if (!data) return true
+  if (data.f != null && data.f !== '') return false
+  return data.v == null || data.v === ''
+}
+
+/** CellData 相等（v/t/f 三字段逐一比较；命令系统据此跳过无实际变更的补丁） */
+export function cellDataEqual(a: CellData | undefined, b: CellData | undefined): boolean {
+  if (a === b) return true
+  if (!a || !b) return false
+  return a.v === b.v && a.t === b.t && a.f === b.f
+}
+
+export class CellStore {
+  private cells = new Map<number, Map<number, CellData>>()
+  private _rowCount = 0
+  private _colCount = 0
+
+  /** 行数高水位（只增不减，restore 时重算） */
+  get rowCount(): number {
+    return this._rowCount
+  }
+
+  /** 列数高水位 */
+  get colCount(): number {
+    return this._colCount
+  }
+
+  /** 真实存在的单元格数量 */
+  get size(): number {
+    let size = 0
+    for (const rowMap of this.cells.values()) size += rowMap.size
+    return size
+  }
+
+  /** 读取（返回副本，外部修改不影响存储） */
+  getCell(addr: CellAddress): CellData | undefined {
+    const data = this.cells.get(addr.row)?.get(addr.col)
+    return data ? { ...data } : undefined
+  }
+
+  /** 写入（存储副本）；空数据等价于删除 */
+  setCell(addr: CellAddress, data?: CellData): void {
+    if (isEmptyCellData(data)) {
+      this.deleteCell(addr)
+      return
+    }
+    let rowMap = this.cells.get(addr.row)
+    if (!rowMap) {
+      rowMap = new Map()
+      this.cells.set(addr.row, rowMap)
+    }
+    rowMap.set(addr.col, { ...data })
+    this._rowCount = Math.max(this._rowCount, addr.row + 1)
+    this._colCount = Math.max(this._colCount, addr.col + 1)
+  }
+
+  /** 便捷写入原始值，类型自动推断；空值等价于删除 */
+  setCellValue(addr: CellAddress, value: CellValue): void {
+    if (value == null || value === '') {
+      this.deleteCell(addr)
+      return
+    }
+    this.setCell(addr, { v: value, t: inferCellType(value) })
+  }
+
+  deleteCell(addr: CellAddress): boolean {
+    const rowMap = this.cells.get(addr.row)
+    if (!rowMap) return false
+    const deleted = rowMap.delete(addr.col)
+    if (rowMap.size === 0) this.cells.delete(addr.row)
+    return deleted
+  }
+
+  /** 只遍历真实存在的单元格（行主序） */
+  *entries(): Generator<[CellAddress, CellData], void, undefined> {
+    for (const [row, rowMap] of this.cells) {
+      for (const [col, data] of rowMap) {
+        yield [{ row, col }, { ...data }]
+      }
+    }
+  }
+
+  /** 只遍历区域内真实存在的单元格（行主序；公式区域展开用，空行/空格不分配不访问） */
+  *entriesInRange(range: CellRange): Generator<[CellAddress, CellData], void, undefined> {
+    for (let row = range.start.row; row <= range.end.row; row++) {
+      const rowMap = this.cells.get(row)
+      if (!rowMap) continue
+      for (let col = range.start.col; col <= range.end.col; col++) {
+        const data = rowMap.get(col)
+        if (data) yield [{ row, col }, { ...data }]
+      }
+    }
+  }
+
+  /** 序列化（只含真实存在的格） */
+  snapshot(): CellSnapshotItem[] {
+    const items: CellSnapshotItem[] = []
+    for (const [addr, data] of this.entries()) {
+      items.push({ row: addr.row, col: addr.col, ...data })
+    }
+    return items
+  }
+
+  /** 从序列化恢复（清空重建，重算高水位） */
+  restore(items: readonly CellSnapshotItem[]): void {
+    this.clear()
+    for (const item of items) {
+      const { row, col, ...data } = item
+      if (isEmptyCellData(data)) continue
+      let rowMap = this.cells.get(row)
+      if (!rowMap) {
+        rowMap = new Map()
+        this.cells.set(row, rowMap)
+      }
+      rowMap.set(col, { ...data })
+      this._rowCount = Math.max(this._rowCount, row + 1)
+      this._colCount = Math.max(this._colCount, col + 1)
+    }
+  }
+
+  clear(): void {
+    this.cells.clear()
+    this._rowCount = 0
+    this._colCount = 0
+  }
+}

package/src/core/command/default-registry.ts

@@ -0,0 +1,15 @@
+import { MergeCellsCommand, UnmergeCellsCommand } from './merge-cells'
+import { CommandRegistry } from './registry'
+import { SetCellFormulaCommand } from './set-cell-formula'
+import { SetCellValueCommand } from './set-cell-value'
+
+/**
+ * 默认命令注册表：内置命令模块加载时注册一次，全局共享（命令无状态）。
+ * Sheet 默认经此表执行命令；阶段 4 工具扩展可继续注册自定义命令。
+ */
+export const defaultCommandRegistry = new CommandRegistry()
+
+defaultCommandRegistry.register(SetCellValueCommand)
+defaultCommandRegistry.register(SetCellFormulaCommand)
+defaultCommandRegistry.register(MergeCellsCommand)
+defaultCommandRegistry.register(UnmergeCellsCommand)

package/src/core/command/history.ts

@@ -0,0 +1,167 @@
+import { TypedEventEmitter } from '../events'
+import type { Mutation, Patch, PatchDirection } from './types'
+
+/**
+ * HistoryManager：undo/redo 栈 + 事务。
+ *
+ * - 一个 undo 单元 = 一次命令（或一次事务）的全部 Mutation
+ * - 事务：beginTransaction / commit，支持嵌套（深度计数，拍平到最外层）；
+ *   rollback 回滚缓冲区中已应用的变更并放弃事务
+ * - 容量上限（默认 200）：超出淘汰最旧条目
+ * - 新命令入栈即清空 redo 栈
+ */
+
+/** 历史栈容量默认值 */
+export const DEFAULT_HISTORY_CAPACITY = 200
+
+/** 历史状态（history-change 事件负载） */
+export interface HistoryState {
+  canUndo: boolean
+  canRedo: boolean
+}
+
+type HistoryEvents = { change: HistoryState }
+
+/** 一个 undo 单元 = 一组 Mutation */
+type HistoryEntry = Mutation[]
+
+export class HistoryManager {
+  private undoStack: HistoryEntry[] = []
+  private redoStack: HistoryEntry[] = []
+  /** 事务深度（>0 表示事务进行中） */
+  private transactionDepth = 0
+  /** 事务缓冲：commit 时合并为一个 undo 单元 */
+  private transactionBuffer: Mutation[] = []
+  private emitter = new TypedEventEmitter<HistoryEvents>()
+
+  constructor(
+    /** 补丁应用器（由 Sheet 注入，命令执行与回放共用） */
+    private readonly applyPatch: (patch: Patch, direction: PatchDirection) => void,
+    private readonly capacity: number = DEFAULT_HISTORY_CAPACITY
+  ) {}
+
+  get canUndo(): boolean {
+    return this.undoStack.length > 0
+  }
+
+  get canRedo(): boolean {
+    return this.redoStack.length > 0
+  }
+
+  /** undo 栈深度（调试/测试用） */
+  get undoSize(): number {
+    return this.undoStack.length
+  }
+
+  /** redo 栈深度（调试/测试用） */
+  get redoSize(): number {
+    return this.redoStack.length
+  }
+
+  /** 是否处于事务中 */
+  get inTransaction(): boolean {
+    return this.transactionDepth > 0
+  }
+
+  /** 命令执行产生的 mutation 入栈（事务中则缓冲）；空列表直接忽略 */
+  push(mutations: Mutation[]): void {
+    if (mutations.length === 0) return
+    if (this.transactionDepth > 0) {
+      this.transactionBuffer.push(...mutations)
+      return
+    }
+    this.pushEntry(mutations)
+  }
+
+  /** 开启事务（可嵌套，拍平到最外层） */
+  beginTransaction(): void {
+    this.transactionDepth++
+  }
+
+  /** 提交事务：缓冲的 mutation 合并为一个 undo 单元入栈 */
+  commit(): void {
+    if (this.transactionDepth === 0) {
+      throw new Error('HistoryManager.commit：没有进行中的事务')
+    }
+    this.transactionDepth--
+    if (this.transactionDepth === 0 && this.transactionBuffer.length > 0) {
+      const entry = this.transactionBuffer
+      this.transactionBuffer = []
+      this.pushEntry(entry)
+    }
+  }
+
+  /**
+   * 回滚事务：逆序应用缓冲区中各 mutation 的 undo 补丁还原模型，
+   * 丢弃缓冲并结束事务（含嵌套）；不动 undo/redo 栈。
+   */
+  rollback(): void {
+    if (this.transactionDepth === 0) return
+    const buffer = this.transactionBuffer
+    this.transactionBuffer = []
+    this.transactionDepth = 0
+    for (let i = buffer.length - 1; i >= 0; i--) {
+      for (const patch of buffer[i]!.undo) {
+        this.applyPatch(patch, 'undo')
+      }
+    }
+  }
+
+  /** 撤销一个单元；事务进行中或栈空时返回 false */
+  undo(): boolean {
+    if (this.transactionDepth > 0) return false
+    const entry = this.undoStack.pop()
+    if (!entry) return false
+    for (let i = entry.length - 1; i >= 0; i--) {
+      for (const patch of entry[i]!.undo) {
+        this.applyPatch(patch, 'undo')
+      }
+    }
+    this.redoStack.push(entry)
+    this.emitChange()
+    return true
+  }
+
+  /** 重做一个单元；事务进行中或栈空时返回 false */
+  redo(): boolean {
+    if (this.transactionDepth > 0) return false
+    const entry = this.redoStack.pop()
+    if (!entry) return false
+    for (const mutation of entry) {
+      for (const patch of mutation.redo) {
+        this.applyPatch(patch, 'redo')
+      }
+    }
+    this.undoStack.push(entry)
+    this.emitChange()
+    return true
+  }
+
+  /** 清空全部历史（含事务缓冲） */
+  clear(): void {
+    this.undoStack = []
+    this.redoStack = []
+    this.transactionBuffer = []
+    this.transactionDepth = 0
+    this.emitChange()
+  }
+
+  onChange(handler: (state: HistoryState) => void): () => void {
+    return this.emitter.on('change', handler)
+  }
+
+  private pushEntry(entry: HistoryEntry): void {
+    this.undoStack.push(entry)
+    if (this.undoStack.length > this.capacity) {
+      // 淘汰最旧条目；redo 栈不受影响（淘汰只发生在 undo 栈底部）
+      this.undoStack.shift()
+    }
+    // 新命令清空 redo 栈
+    this.redoStack = []
+    this.emitChange()
+  }
+
+  private emitChange(): void {
+    this.emitter.emit('change', { canUndo: this.canUndo, canRedo: this.canRedo })
+  }
+}

package/src/core/command/index.ts

@@ -0,0 +1,7 @@
+export * from './types'
+export * from './registry'
+export * from './history'
+export * from './set-cell-value'
+export * from './set-cell-formula'
+export * from './merge-cells'
+export * from './default-registry'

package/src/core/command/merge-cells.ts

@@ -0,0 +1,74 @@
+import { iterateRange, rangesIntersect, type CellRange } from '../address'
+import { cellDataEqual, isEmptyCellData, type CellData } from '../cell-store'
+import type { CellPatch, Command, CommandResult, MergePatch, Patch } from './types'
+
+export interface MergeCellsParams {
+  range: CellRange
+}
+
+/**
+ * 合并命令。Patch 捕获完整 before 状态：
+ * - 被解除的既有合并记录（undo 时逐一恢复）
+ * - 包围盒内每一格的原数据（undo 时连被清空的值一起还原）
+ * 值保留规则同 Excel/univer：行主序第一个有值格的值写入新锚点，其余清空。
+ */
+export const MergeCellsCommand: Command<MergeCellsParams, CellRange> = {
+  id: 'sheet.command.merge-cells',
+
+  handler(ctx, params): CommandResult<CellRange> {
+    const { sheet } = ctx
+    const { range: finalRange, removed } = sheet.merges.computeMerge(params.range)
+
+    // 捕获包围盒内各格 before；同时按行主序找出第一个有值格
+    const cellPatches: CellPatch[] = []
+    let retained: CellData | undefined
+    let anchorPatch: CellPatch | undefined
+    for (const addr of iterateRange(finalRange)) {
+      const before = sheet.store.getCell(addr)
+      if (before && !retained && !isEmptyCellData(before)) retained = before
+      const patch: CellPatch = { kind: 'cell', addr, before, after: undefined }
+      if (addr.row === finalRange.start.row && addr.col === finalRange.start.col) {
+        anchorPatch = patch
+      }
+      cellPatches.push(patch)
+    }
+    if (retained && anchorPatch) {
+      anchorPatch.after = { ...retained }
+    }
+
+    const mergePatches: MergePatch[] = [
+      ...removed.map((range): MergePatch => ({ kind: 'merge', range, before: true, after: false })),
+      { kind: 'merge', range: finalRange, before: false, after: true }
+    ]
+
+    // 过滤无实际变化的 cell 补丁（如被覆盖格本就为空）
+    const patches: Patch[] = [
+      ...mergePatches,
+      ...cellPatches.filter((patch) => !cellDataEqual(patch.before, patch.after))
+    ]
+    for (const patch of patches) ctx.applyPatch(patch, 'redo')
+
+    return { mutations: [{ redo: patches, undo: [...patches].reverse() }], result: finalRange }
+  }
+}
+
+export interface UnmergeCellsParams {
+  range: CellRange
+}
+
+/** 取消合并命令：解除与 range 相交的所有合并；undo 恢复合并记录 */
+export const UnmergeCellsCommand: Command<UnmergeCellsParams> = {
+  id: 'sheet.command.unmerge-cells',
+
+  handler(ctx, params): CommandResult {
+    const removed: MergePatch[] = []
+    for (const range of ctx.sheet.merges.getMerges()) {
+      if (rangesIntersect(range, params.range)) {
+        removed.push({ kind: 'merge', range, before: true, after: false })
+      }
+    }
+    if (removed.length === 0) return { mutations: [] }
+    for (const patch of removed) ctx.applyPatch(patch, 'redo')
+    return { mutations: [{ redo: removed, undo: [...removed].reverse() }] }
+  }
+}

package/src/core/command/registry.ts

@@ -0,0 +1,30 @@
+import type { Command, CommandContext, CommandResult } from './types'
+
+/**
+ * 命令注册表：register / execute。
+ * 命令无状态，可全局共享（见 default-registry）；阶段 4 工具扩展可注册自定义命令。
+ */
+export class CommandRegistry {
+  private commands = new Map<string, Command>()
+
+  /** 注册命令；同 id 重复注册视为错误 */
+  register(command: Command): void {
+    if (this.commands.has(command.id)) {
+      throw new Error(`命令重复注册: ${command.id}`)
+    }
+    this.commands.set(command.id, command)
+  }
+
+  get(id: string): Command | undefined {
+    return this.commands.get(id)
+  }
+
+  /** 执行命令；未注册的 id 抛错 */
+  execute<R>(ctx: CommandContext, id: string, params: unknown): CommandResult<R> | undefined {
+    const command = this.commands.get(id)
+    if (!command) {
+      throw new Error(`命令未注册: ${id}`)
+    }
+    return command.handler(ctx, params) as CommandResult<R> | undefined
+  }
+}

package/src/core/command/set-cell-formula.ts

@@ -0,0 +1,29 @@
+import type { CellAddress } from '../address'
+import type { CellData } from '../cell-store'
+import type { CellPatch, Command, CommandResult } from './types'
+
+export interface SetCellFormulaParams {
+  addr: CellAddress
+  /** 公式文本（不含 '='） */
+  formula: string
+}
+
+/**
+ * 公式写入命令：只登记公式原文（f）；计算缓存（v/t）由命令执行后的
+ * 增量重算以派生补丁填充（见 Sheet.executeCommand），重算波及的所有变更
+ * 与源补丁并入同一 undo 单元。
+ */
+export const SetCellFormulaCommand: Command<SetCellFormulaParams> = {
+  id: 'sheet.command.set-cell-formula',
+
+  handler(ctx, params): CommandResult {
+    const anchor = ctx.sheet.merges.resolveAnchor(params.addr)
+    const before = ctx.sheet.store.getCell(anchor)
+    // 同公式重复输入 = 无实际变更，不入历史
+    if (before?.f === params.formula) return { mutations: [] }
+    const after: CellData = { f: params.formula }
+    const patch: CellPatch = { kind: 'cell', addr: anchor, before, after }
+    ctx.applyPatch(patch, 'redo')
+    return { mutations: [{ redo: [patch], undo: [patch] }] }
+  }
+}