@veltra/sheet 2.0.0

package/src/grid/sheet-grid.ts

@@ -0,0 +1,283 @@
+import { ListTable, register } from '@visactor/vtable'
+import type { ListTableConstructorOptions } from '@visactor/vtable'
+import { InputEditor } from '@visactor/vtable-editors'
+import type { EditContext } from '@visactor/vtable-editors'
+
+import type { CellAddress } from '../core/address'
+import { cellKey, colIndexToName, createRange } from '../core/address'
+import type { CellValue } from '../core/cell-store'
+import type { Sheet } from '../core/sheet'
+
+/**
+ * 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），其余格显示当前值 */
+class FormulaAwareInputEditor extends InputEditor {
+  /** 由 SheetGrid 注入：返回进入编辑时应显示的文本；undefined = 用 VTable 默认值 */
+  resolveEditText?: (col: number, row: number) => string | undefined
+
+  override onStart(context: EditContext<string>): void {
+    const text = this.resolveEditText?.(context.col, context.row)
+    super.onStart(text === undefined ? context : { ...context, value: text })
+  }
+}
+
+/** 编辑器按 grid 实例注册（hook 闭包各自 sheet），名称递增防冲突 */
+let editorSeq = 0
+
+export interface SheetGridOptions {
+  container: HTMLElement
+  sheet: Sheet
+  /** 渲染行数，默认 100 */
+  rows?: number
+  /** 渲染列数，默认 26（A..Z） */
+  cols?: number
+}
+
+export class SheetGrid {
+  private readonly sheet: Sheet
+  private readonly table: ListTable
+  private readonly container: HTMLElement
+  private readonly rows: number
+  private readonly cols: number
+  private readonly editorName: string
+  private readonly disposers: (() => void)[] = []
+  /** 编辑提交期间累积的模型变更（提交结束统一回推表格，覆盖公式派生格） */
+  private pendingTableSync: Map<number, CellAddress> | null = null
+  /** 实测坐标偏移（行号列数 / 列头行数），首次使用时测量 */
+  private offsets?: { colOffset: number; rowOffset: number }
+
+  constructor(options: SheetGridOptions) {
+    this.sheet = options.sheet
+    this.container = options.container
+    this.rows = options.rows ?? 100
+    this.cols = options.cols ?? 26
+
+    // 每个 grid 实例注册自己的编辑器（hook 闭包本实例的 sheet 与坐标换算）
+    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 undefined
+      const data = this.sheet.getCellData(this.sheet.merges.resolveAnchor(addr))
+      return data?.f ? `=${data.f}` : undefined
+    }
+    register.editor(this.editorName, editor)
+
+    this.table = new ListTable(options.container, this.buildOptions())
+    this.bindTableEvents()
+    this.bindSheetEvents()
+    this.bindKeyboard()
+  }
+
+  /** 底层 ListTable 实例（调试与测试用） */
+  getTable(): ListTable {
+    return this.table
+  }
+
+  /** 全量刷新（合并结构变化、批量数据变更后调用） */
+  refresh(): void {
+    this.table.setRecords(this.buildRecords())
+  }
+
+  /** 撤销一步（模型命令历史） */
+  undo(): boolean {
+    return this.sheet.undo()
+  }
+
+  /** 重做一步（模型命令历史） */
+  redo(): boolean {
+    return this.sheet.redo()
+  }
+
+  release(): void {
+    for (const dispose of this.disposers) dispose()
+    this.disposers.length = 0
+    this.table.release()
+  }
+
+  // ─── 坐标换算 ─────────────────────────────────────────────
+
+  /**
+   * 实测偏移：列头行数取 columnHeaderLevelCount；
+   * 行号列不被计入 rowHeaderLevelCount，用 isSeriesNumber 逐列探测。
+   * 结果缓存（表格实例不变，布局不变）。
+   */
+  private getOffsets(table: ListTable): { colOffset: number; rowOffset: number } {
+    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 */
+  private toSheetAddr(table: ListTable, col: number, row: number): CellAddress | null {
+    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 坐标 */
+  private toTableCoord(table: ListTable, addr: CellAddress): { col: number; row: number } {
+    const { colOffset, rowOffset } = this.getOffsets(table)
+    return { col: addr.col + colOffset, row: addr.row + rowOffset }
+  }
+
+  // ─── 模型 → VTable ────────────────────────────────────────
+
+  private buildColumns() {
+    return Array.from({ length: this.cols }, (_, col) => ({
+      field: String(col),
+      title: colIndexToName(col)
+    }))
+  }
+
+  private buildRecords(): Record<string, CellValue>[] {
+    const records: Record<string, CellValue>[] = 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
+  }
+
+  private buildOptions(): ListTableConstructorOptions {
+    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 as ListTable, col, row)
+        if (!addr) return undefined
+        const merge = this.sheet.merges.getMergeAt(addr)
+        if (!merge) return undefined
+        const anchorCoord = this.toTableCoord(table as ListTable, merge.start)
+        const recordValue = (table as ListTable).getCellOriginValue(
+          anchorCoord.col,
+          anchorCoord.row
+        )
+        return {
+          range: { start: anchorCoord, end: this.toTableCoord(table as ListTable, merge.end) },
+          // 关键 1：必须携带 text。VTable 的 getCellRange 仅在 text/customLayout/
+          // customRender 有效时才认这个自定义合并——没有 text 时选区与编辑不会
+          // 扩展为整个合并区域，且合并格渲染为空。
+          // 关键 2：text 必须读 VTable records 而非模型。编辑提交的顺序是
+          // 先更新 record → 重绘 → 最后才发 change_cell_value 回写模型；
+          // 若此时读模型，拿到的还是回写前的旧值（合并格显示旧文本）。
+          text: recordValue == null ? '' : String(recordValue)
+        }
+      }
+    }
+  }
+
+  // ─── 事件桥接 ─────────────────────────────────────────────
+
+  private bindTableEvents(): void {
+    this.table.on(ListTable.EVENT_TYPE.CHANGE_CELL_VALUE, (args) => {
+      const addr = this.toSheetAddr(this.table, args.col, args.row)
+      if (addr == null) return
+      // 编辑提交期间模型变更（含公式重算派生格）先入队列，提交结束统一回推。
+      // 被编辑格自身也入队：VTable 已把输入文本写进 record，公式格需回推计算值
+      this.pendingTableSync = 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))
+    })
+  }
+
+  private bindSheetEvents(): void {
+    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（显示值；公式格为计算缓存） */
+  private pushCellToTable(addr: CellAddress): void {
+    const { col, row } = this.toTableCoord(this.table, addr)
+    const value = this.sheet.getDisplayValue(addr)
+    this.table.changeCellValue(col, row, value as string | number | null, false, false)
+  }
+
+  /**
+   * 键盘绑定：Cmd/Ctrl+Z undo，Cmd/Ctrl+Shift+Z 与 Ctrl+Y redo。
+   * 编辑器打开时（事件来自编辑器 input）不拦截，保留文本编辑自身的撤销行为。
+   */
+  private bindKeyboard(): void {
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.target instanceof HTMLInputElement || event.target instanceof HTMLTextAreaElement) {
+        return
+      }
+      const mod = event.metaKey || event.ctrlKey
+      if (!mod) 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))
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+// 内置工具注册（undo/redo/合并/取消合并）：随包入口完成，
+// 与 core/command 的 default-registry 同构；深导入 core 子路径的无头场景不涉及
+import './tools/builtin'
+
+export * from './core/address'
+export * from './core/cell-store'
+export * from './core/merge-manager'
+export * from './core/selection'
+export * from './core/sheet'
+export * from './core/workbook'
+export * from './core/command'
+export * from './core/formula'
+export * from './grid/sheet-grid'
+export * from './tools'
+export * from './types'
+export * from './vue'

package/src/tools/__test__/builtin.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest'
+
+import '../builtin'
+import { createRange } from '../../core/address'
+import { Sheet } from '../../core/sheet'
+import { createSheetContext } from '../context'
+import { defaultToolRegistry, type SheetTool } from '../registry'
+
+function mustGet(id: string): SheetTool {
+  const tool = defaultToolRegistry.get(id)
+  if (!tool) throw new Error(`内置工具未注册: ${id}`)
+  return tool
+}
+
+function isDisabled(tool: SheetTool, sheet: Sheet): boolean {
+  return tool.disabled?.(createSheetContext(sheet)) ?? false
+}
+
+describe('内置工具（dogfood 扩展机制）', () => {
+  it('注册布局：history 组（undo/redo）在前，cell 组（merge/unmerge）在后', () => {
+    const groups = defaultToolRegistry.getGroups()
+    expect(groups.map((group) => group.name)).toEqual(['history', 'cell'])
+    expect(groups[0]!.tools.map((tool) => tool.id)).toEqual(['undo', 'redo'])
+    expect(groups[1]!.tools.map((tool) => tool.id)).toEqual(['merge', 'unmerge'])
+  })
+
+  it('undo/redo 的 disabled 随 history 状态联动', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+    const undo = mustGet('undo')
+    const redo = mustGet('redo')
+
+    // 空历史：两者禁用
+    expect(undo.disabled?.(ctx)).toBe(true)
+    expect(redo.disabled?.(ctx)).toBe(true)
+
+    sheet.setCellValue({ row: 0, col: 0 }, 1)
+    expect(undo.disabled?.(ctx)).toBe(false)
+    expect(redo.disabled?.(ctx)).toBe(true)
+
+    undo.onClick(ctx)
+    expect(sheet.getCellData({ row: 0, col: 0 })).toBeUndefined()
+    expect(undo.disabled?.(ctx)).toBe(true)
+    expect(redo.disabled?.(ctx)).toBe(false)
+
+    redo.onClick(ctx)
+    expect(sheet.getCellData({ row: 0, col: 0 })).toEqual({ v: 1, t: 'n' })
+  })
+
+  it('merge：无选区/单格禁用，拖选区域可用，合并已有合并区域时禁用', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+    const merge = mustGet('merge')
+
+    // 无选区
+    expect(merge.disabled?.(ctx)).toBe(true)
+
+    // 单格选区
+    ctx.selectCell({ row: 0, col: 0 })
+    expect(merge.disabled?.(ctx)).toBe(true)
+
+    // 区域选区 → 可用
+    const range = createRange({ row: 0, col: 0 }, { row: 1, col: 1 })
+    ctx.selectRange(range)
+    expect(merge.disabled?.(ctx)).toBe(false)
+
+    merge.onClick(ctx)
+    expect(sheet.merges.getMergeAt({ row: 0, col: 0 })).toEqual(range)
+
+    // 选区恰好等于既有合并区域 → 禁用（避免空操作历史条目）
+    expect(merge.disabled?.(ctx)).toBe(true)
+
+    // 合并可 undo
+    ctx.undo()
+    expect(sheet.merges.getMergeAt({ row: 0, col: 0 })).toBeUndefined()
+  })
+
+  it('unmerge：活动格不在合并内禁用，在合并内可用且可 undo', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+    const unmerge = mustGet('unmerge')
+
+    const range = createRange({ row: 0, col: 0 }, { row: 1, col: 2 })
+    sheet.mergeCells(range)
+    sheet.history.clear()
+
+    // 无选区
+    expect(unmerge.disabled?.(ctx)).toBe(true)
+
+    // 普通格
+    ctx.selectCell({ row: 5, col: 5 })
+    expect(unmerge.disabled?.(ctx)).toBe(true)
+
+    // 被覆盖格 → 解析锚点后在合并内
+    ctx.selectCell({ row: 1, col: 2 })
+    expect(ctx.getSelection().activeCell).toEqual({ row: 0, col: 0 })
+    expect(unmerge.disabled?.(ctx)).toBe(false)
+
+    unmerge.onClick(ctx)
+    expect(sheet.merges.getMergeAt({ row: 0, col: 0 })).toBeUndefined()
+
+    ctx.undo()
+    expect(sheet.merges.getMergeAt({ row: 0, col: 0 })).toEqual(range)
+  })
+
+  it('visible 随选区联动（自定义工具）', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+    sheet.mergeCells(createRange({ row: 0, col: 0 }, { row: 1, col: 1 }))
+
+    // 只在活动格位于合并区域内时可见的工具
+    const tool: SheetTool = {
+      id: 'merged-only',
+      title: '合并格工具',
+      visible: (toolCtx) => {
+        const active = toolCtx.getSelection().activeCell
+        return !!active && !!toolCtx.getCellInfo(active).mergeRange
+      },
+      onClick: () => {}
+    }
+
+    expect(tool.visible?.(ctx)).toBe(false)
+    ctx.selectCell({ row: 1, col: 1 })
+    expect(tool.visible?.(ctx)).toBe(true)
+    ctx.selectCell({ row: 3, col: 3 })
+    expect(tool.visible?.(ctx)).toBe(false)
+  })
+})

package/src/tools/__test__/context.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { createRange } from '../../core/address'
+import { Sheet } from '../../core/sheet'
+import { createSheetContext } from '../context'
+import type { SheetTool } from '../registry'
+
+describe('SheetContext', () => {
+  it('读写直达目标 sheet；写入经命令系统可 undo/redo', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+
+    ctx.setCellValue({ row: 0, col: 0 }, 'hello')
+    expect(sheet.getCellData({ row: 0, col: 0 })).toEqual({ v: 'hello', t: 's' })
+    expect(ctx.getDisplayValue({ row: 0, col: 0 })).toBe('hello')
+    expect(ctx.canUndo).toBe(true)
+
+    expect(ctx.undo()).toBe(true)
+    expect(sheet.getCellData({ row: 0, col: 0 })).toBeUndefined()
+    expect(ctx.canRedo).toBe(true)
+
+    expect(ctx.redo()).toBe(true)
+    expect(sheet.getCellData({ row: 0, col: 0 })).toEqual({ v: 'hello', t: 's' })
+  })
+
+  it('公式、合并、取消合并均经门面且可 undo', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+
+    ctx.setCellValue({ row: 0, col: 0 }, 2)
+    ctx.setCellFormula({ row: 0, col: 1 }, '=A1*3')
+    expect(ctx.getDisplayValue({ row: 0, col: 1 })).toBe(6)
+
+    const range = createRange({ row: 1, col: 0 }, { row: 2, col: 1 })
+    ctx.mergeCells(range)
+    expect(ctx.getCellInfo({ row: 2, col: 1 }).kind).toBe('merged-covered')
+
+    ctx.unmergeCells(range)
+    expect(ctx.getCellInfo({ row: 2, col: 1 }).kind).toBe('normal')
+
+    ctx.undo() // undo unmerge → 恢复合并
+    expect(ctx.getCellInfo({ row: 2, col: 1 }).kind).toBe('merged-covered')
+    ctx.undo() // undo merge
+    ctx.undo() // undo 公式
+    expect(sheet.getCellData({ row: 0, col: 1 })).toBeUndefined()
+  })
+
+  it('选区读写与 selection-change / history-change 订阅', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+
+    const onSelection = vi.fn()
+    const onHistory = vi.fn()
+    const offSelection = ctx.onSelectionChange(onSelection)
+    ctx.onHistoryChange(onHistory)
+
+    ctx.selectRange(createRange({ row: 0, col: 0 }, { row: 1, col: 2 }))
+    expect(onSelection).toHaveBeenCalledTimes(1)
+    expect(ctx.getSelection().activeCell).toEqual({ row: 0, col: 0 })
+    expect(ctx.getSelection().ranges[0]).toEqual({
+      start: { row: 0, col: 0 },
+      end: { row: 1, col: 2 }
+    })
+
+    ctx.setCellValue({ row: 0, col: 0 }, 1)
+    expect(onHistory).toHaveBeenCalledWith({ canUndo: true, canRedo: false })
+
+    offSelection()
+    ctx.selectCell({ row: 3, col: 3 })
+    expect(onSelection).toHaveBeenCalledTimes(1)
+  })
+
+  it('批量写入 + 事务 = 一个 undo 单元', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+
+    ctx.setCells([
+      { addr: { row: 0, col: 0 }, data: { v: 1, t: 'n' } },
+      { addr: { row: 0, col: 1 }, data: { v: 2, t: 'n' } }
+    ])
+    ctx.undo()
+    expect(sheet.getCellData({ row: 0, col: 0 })).toBeUndefined()
+    expect(sheet.getCellData({ row: 0, col: 1 })).toBeUndefined()
+
+    ctx.beginTransaction()
+    ctx.setCellValue({ row: 1, col: 0 }, 'a')
+    ctx.setCellValue({ row: 1, col: 1 }, 'b')
+    ctx.commit()
+    ctx.undo()
+    expect(sheet.getCellData({ row: 1, col: 0 })).toBeUndefined()
+    expect(sheet.getCellData({ row: 1, col: 1 })).toBeUndefined()
+  })
+
+  it('动态解析器：tab 切换后同一上下文指向新的活动 sheet', () => {
+    const sheet1 = new Sheet('Sheet1')
+    const sheet2 = new Sheet('Sheet2')
+    let active = sheet1
+    const ctx = createSheetContext(() => active)
+
+    expect(ctx.sheetName).toBe('Sheet1')
+    ctx.setCellValue({ row: 0, col: 0 }, 'one')
+
+    active = sheet2 // 模拟 tab 切换
+    expect(ctx.sheetName).toBe('Sheet2')
+    ctx.setCellValue({ row: 0, col: 0 }, 'two')
+
+    expect(sheet1.getCellData({ row: 0, col: 0 })).toEqual({ v: 'one', t: 's' })
+    expect(sheet2.getCellData({ row: 0, col: 0 })).toEqual({ v: 'two', t: 's' })
+
+    // undo 作用于当前活动 sheet
+    expect(ctx.undo()).toBe(true)
+    expect(sheet2.getCellData({ row: 0, col: 0 })).toBeUndefined()
+    expect(sheet1.getCellData({ row: 0, col: 0 })).toEqual({ v: 'one', t: 's' })
+  })
+
+  it('executeCommand 执行自定义命令', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+    // 内置命令走默认注册表
+    ctx.executeCommand('sheet.command.set-cell-value', {
+      items: [{ addr: { row: 0, col: 0 }, data: { v: 'x', t: 's' } }]
+    })
+    expect(sheet.getCellData({ row: 0, col: 0 })).toEqual({ v: 'x', t: 's' })
+    expect(ctx.canUndo).toBe(true)
+  })
+
+  it('自定义工具 onClick 内执行命令 → 可被 undo（扩展不绕过命令系统）', () => {
+    const sheet = new Sheet()
+    const ctx = createSheetContext(sheet)
+    sheet.setCellValue({ row: 0, col: 0 }, 'keep')
+    sheet.history.clear()
+
+    // 第三方工具：清空选区（批量写，一个 undo 单元）
+    const clearTool: SheetTool = {
+      id: 'clear-selection',
+      title: '清空选区',
+      onClick: (toolCtx) => {
+        const range = toolCtx.getSelection().ranges[0]
+        if (!range) return
+        const items = []
+        for (let row = range.start.row; row <= range.end.row; row++) {
+          for (let col = range.start.col; col <= range.end.col; col++) {
+            items.push({ addr: { row, col }, data: undefined })
+          }
+        }
+        toolCtx.setCells(items)
+      }
+    }
+
+    ctx.selectRange(createRange({ row: 0, col: 0 }, { row: 0, col: 0 }))
+    clearTool.onClick(ctx)
+    expect(sheet.getCellData({ row: 0, col: 0 })).toBeUndefined()
+
+    expect(ctx.undo()).toBe(true)
+    expect(sheet.getCellData({ row: 0, col: 0 })).toEqual({ v: 'keep', t: 's' })
+  })
+})

package/src/tools/__test__/registry.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { SheetTool } from '../registry'
+import { DEFAULT_TOOL_GROUP, ToolRegistry } from '../registry'
+
+function tool(partial: Partial<SheetTool> & { id: string }): SheetTool {
+  return { title: partial.id, onClick: () => {}, ...partial }
+}
+
+describe('ToolRegistry', () => {
+  it('注册工具 → 出现在指定分组/顺序位；缺省进 default 组', () => {
+    const registry = new ToolRegistry()
+    registry.register(tool({ id: 'a', group: 'g1', order: 2 }))
+    registry.register(tool({ id: 'b' })) // 缺省分组
+    registry.register(tool({ id: 'c', group: 'g1', order: 1 }))
+    registry.register(tool({ id: 'd', group: 'g1' })) // 缺省 order 0
+    registry.register(tool({ id: 'e', group: 'g2' }))
+
+    const groups = registry.getGroups()
+    // 组序 = 各组最早注册位置：g1（a）→ default（b）→ g2（e）
+    expect(groups.map((group) => group.name)).toEqual(['g1', DEFAULT_TOOL_GROUP, 'g2'])
+    // g1 组内按 (order, 注册序)：d(0) → c(1) → a(2)
+    expect(groups[0]!.tools.map((t) => t.id)).toEqual(['d', 'c', 'a'])
+    expect(groups[1]!.tools.map((t) => t.id)).toEqual(['b'])
+    expect(groups[2]!.tools.map((t) => t.id)).toEqual(['e'])
+  })
+
+  it('同组同 order 按注册先后排序', () => {
+    const registry = new ToolRegistry()
+    registry.register(tool({ id: 'x' }))
+    registry.register(tool({ id: 'y' }))
+    registry.register(tool({ id: 'z' }))
+    expect(registry.getGroups()[0]!.tools.map((t) => t.id)).toEqual(['x', 'y', 'z'])
+  })
+
+  it('重复 id 注册 = 替换定义并保留原位置，触发 change', () => {
+    const registry = new ToolRegistry()
+    const onChange = vi.fn()
+    registry.onChange(onChange)
+    registry.register(tool({ id: 'a', title: 'A1' }))
+    registry.register(tool({ id: 'b' }))
+    onChange.mockClear()
+
+    registry.register(tool({ id: 'a', title: 'A2', order: 9 }))
+    expect(registry.size).toBe(2)
+    expect(registry.get('a')?.title).toBe('A2')
+    // 替换只保留注册序（同 order 时的次序）；order 变更仍按新值排序
+    expect(registry.getGroups()[0]!.tools.map((t) => t.id)).toEqual(['b', 'a'])
+    expect(onChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('重复 id 且 order 不变时严格原位替换', () => {
+    const registry = new ToolRegistry()
+    registry.register(tool({ id: 'a' }))
+    registry.register(tool({ id: 'b' }))
+    registry.register(tool({ id: 'a', title: 'A2' }))
+    expect(registry.getGroups()[0]!.tools.map((t) => t.id)).toEqual(['a', 'b'])
+    expect(registry.get('a')?.title).toBe('A2')
+  })
+
+  it('unregister：存在 → true + change；不存在 → false 且不触发 change', () => {
+    const registry = new ToolRegistry()
+    const onChange = vi.fn()
+    registry.onChange(onChange)
+    registry.register(tool({ id: 'a' }))
+    onChange.mockClear()
+
+    expect(registry.unregister('a')).toBe(true)
+    expect(registry.has('a')).toBe(false)
+    expect(onChange).toHaveBeenCalledTimes(1)
+
+    expect(registry.unregister('a')).toBe(false)
+    expect(registry.unregister('ghost')).toBe(false)
+    expect(onChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('注册校验：缺 id / title / onClick 抛错', () => {
+    const registry = new ToolRegistry()
+    expect(() => registry.register(tool({ id: '' }))).toThrow('id 不能为空')
+    expect(() => registry.register({ id: 'x', title: '', onClick: () => {} })).toThrow('title')
+    expect(() => registry.register({ id: 'x', title: 'X' } as unknown as SheetTool)).toThrow(
+      'onClick'
+    )
+  })
+
+  it('onChange 返回取消订阅函数', () => {
+    const registry = new ToolRegistry()
+    const onChange = vi.fn()
+    const off = registry.onChange(onChange)
+    off()
+    registry.register(tool({ id: 'a' }))
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('getGroups 返回副本：调用方改数组不影响注册表', () => {
+    const registry = new ToolRegistry()
+    registry.register(tool({ id: 'a' }))
+    const groups = registry.getGroups()
+    groups[0]!.tools.length = 0
+    expect(registry.getGroups()[0]!.tools).toHaveLength(1)
+  })
+})