@veltra/sheet 2.0.0

package/src/tools/builtin.ts

@@ -0,0 +1,75 @@
+import { rangesEqual } from '../core/address'
+import { registerTool } from './registry'
+
+/**
+ * 内置工具（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])
+  }
+})

package/src/tools/context.ts

@@ -0,0 +1,106 @@
+import type { CellAddress, CellRange } from '../core/address'
+import type { CellData, CellValue } from '../core/cell-store'
+import type { HistoryState } from '../core/command/history'
+import type { SetCellValueItem } from '../core/command/set-cell-value'
+import type { CellInfo } from '../core/merge-manager'
+import type { SelectionState } from '../core/selection'
+import type { Sheet } from '../core/sheet'
+
+/**
+ * SheetContext：工具的唯一操作门面。
+ *
+ * 工具（内置与第三方）对表格的全部操作都经由此门面：
+ * - 读方法直达当前活动 sheet（语义与 Sheet 同名方法一致）
+ * - 写方法全部走命令系统，天然进入 undo 历史——扩展无法绕过命令系统
+ * - 不暴露 Sheet 实例本身，保证门面就是扩展能力的全部边界
+ * - USheet 切换 sheet tab 后，同一上下文自动指向新的活动 sheet
+ */
+export 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
+
+  // ─── 写入（全部经命令系统，可 undo） ───────────────────────
+  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
+
+  // ─── 事务（事务内多次写入合并为一个 undo 单元） ─────────────
+  beginTransaction(): void
+  commit(): void
+  rollback(): void
+
+  // ─── 历史 ────────────────────────────────────────────────
+  undo(): boolean
+  redo(): boolean
+  readonly canUndo: boolean
+  readonly canRedo: boolean
+
+  // ─── 事件订阅（订阅时绑定到当前活动 sheet；tab 切换后需重新订阅） ──
+  onSelectionChange(handler: (state: SelectionState) => void): () => void
+  onHistoryChange(handler: (state: HistoryState) => void): () => void
+}
+
+/**
+ * 创建工具上下文。
+ * @param resolveSheet 活动 sheet 解析器（USheet 传 `() => activeSheet`，
+ *   tab 切换后上下文自动指向当前 sheet）；也可直接传 Sheet 实例（无头 / 测试场景）
+ */
+export function createSheetContext(resolveSheet: Sheet | (() => Sheet)): SheetContext {
+  const sheet = typeof resolveSheet === 'function' ? resolveSheet : () => resolveSheet
+  return {
+    get sheetName() {
+      return sheet().name
+    },
+
+    getSelection: () => sheet().getSelection(),
+    selectCell: (addr) => sheet().selectCell(addr),
+    selectRange: (range) => sheet().selectRange(range),
+
+    getCellData: (addr) => sheet().getCellData(addr),
+    getDisplayValue: (addr) => sheet().getDisplayValue(addr),
+    getCellInfo: (addr) => sheet().getCellInfo(addr),
+
+    setCellValue: (addr, value) => sheet().setCellValue(addr, value),
+    setCellFormula: (addr, formula) => sheet().setCellFormula(addr, formula),
+    setCells: (items) => sheet().setCells(items),
+    mergeCells: (range) => sheet().mergeCells(range),
+    unmergeCells: (range) => sheet().unmergeCells(range),
+    executeCommand: <R = void>(commandId: string, params: unknown): R | undefined =>
+      sheet().executeCommand<R>(commandId, params),
+
+    beginTransaction: () => sheet().beginTransaction(),
+    commit: () => sheet().commit(),
+    rollback: () => sheet().rollback(),
+
+    undo: () => sheet().undo(),
+    redo: () => sheet().redo(),
+    get canUndo() {
+      return sheet().canUndo
+    },
+    get canRedo() {
+      return sheet().canRedo
+    },
+
+    onSelectionChange: (handler) => sheet().on('selection-change', handler),
+    onHistoryChange: (handler) => sheet().on('history-change', handler)
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,2 @@
+export * from './context'
+export * from './registry'

package/src/tools/registry.ts

@@ -0,0 +1,129 @@
+import { TypedEventEmitter } from '../core/events'
+import type { SheetContext } from './context'
+
+/**
+ * 工具注册表：USheet 工具栏的扩展点。
+ *
+ * - 工具是框架无关的纯定义（icon 由 vue 层渲染，故此处类型为 unknown）
+ * - 分组渲染：同组工具连续排列，组间渲染分隔符；
+ *   组序 = 各组最早注册位置，组内按 (order, 注册序) 升序
+ * - 同 id 重复注册 = 替换定义并保留原注册位置（HMR / 覆盖内置工具友好）
+ * - 默认注册表全局共享：所有 USheet 实例渲染同一组工具
+ *   （与 defaultCommandRegistry 同语义；每个实例的 SheetContext 各自绑定当前 sheet）
+ */
+
+/** 工具定义 */
+export interface SheetTool {
+  /** 唯一 id；同 id 重复注册视为替换（保留原位置） */
+  id: string
+  /** 按钮文本 */
+  title: string
+  /** 图标（Vue 组件，由 USheet 渲染；tools 层不依赖 vue 故为 unknown） */
+  icon?: unknown
+  /** 悬浮提示；缺省用 title */
+  tooltip?: string
+  /** 分组名（组间渲染分隔符）；缺省 'default' */
+  group?: string
+  /** 组内排序（升序，相同 order 按注册先后）；缺省 0 */
+  order?: number
+  /** 是否可见（工具栏状态刷新时求值）；缺省可见 */
+  visible?(ctx: SheetContext): boolean
+  /** 是否禁用（工具栏状态刷新时求值）；缺省可用 */
+  disabled?(ctx: SheetContext): boolean
+  /** 点击执行；ctx 是唯一操作入口（写操作全走命令系统，天然可撤销） */
+  onClick(ctx: SheetContext): void
+}
+
+/** 分组视图（供工具栏渲染） */
+export interface SheetToolGroup {
+  name: string
+  tools: SheetTool[]
+}
+
+/** 缺省分组名 */
+export const DEFAULT_TOOL_GROUP = 'default'
+
+type ToolEntry = { tool: SheetTool; seq: number }
+
+type ToolRegistryEvents = { change: null }
+
+export class ToolRegistry {
+  private entries = new Map<string, ToolEntry>()
+  private seq = 0
+  private emitter = new TypedEventEmitter<ToolRegistryEvents>()
+
+  /** 注册工具；同 id 重复注册 = 替换定义并保留原注册位置 */
+  register(tool: SheetTool): void {
+    if (!tool.id) throw new Error('工具注册失败：id 不能为空')
+    if (!tool.title) throw new Error(`工具注册失败：${tool.id} 缺少 title`)
+    if (typeof tool.onClick !== 'function') {
+      throw new Error(`工具注册失败：${tool.id} 缺少 onClick`)
+    }
+    const prev = this.entries.get(tool.id)
+    this.entries.set(tool.id, { tool, seq: prev?.seq ?? this.seq++ })
+    this.emitter.emit('change', null)
+  }
+
+  /** 注销工具；id 不存在时返回 false（不触发 change） */
+  unregister(id: string): boolean {
+    const existed = this.entries.delete(id)
+    if (existed) this.emitter.emit('change', null)
+    return existed
+  }
+
+  get(id: string): SheetTool | undefined {
+    return this.entries.get(id)?.tool
+  }
+
+  has(id: string): boolean {
+    return this.entries.has(id)
+  }
+
+  get size(): number {
+    return this.entries.size
+  }
+
+  /** 分组视图：组序 = 各组最早注册位置；组内按 (order, 注册序) 升序 */
+  getGroups(): SheetToolGroup[] {
+    const groups = new Map<string, { entries: ToolEntry[]; firstSeq: number }>()
+    for (const entry of this.entries.values()) {
+      const name = entry.tool.group ?? DEFAULT_TOOL_GROUP
+      let group = groups.get(name)
+      if (!group) {
+        group = { entries: [], firstSeq: entry.seq }
+        groups.set(name, group)
+      }
+      group.entries.push(entry)
+    }
+    return [...groups.entries()]
+      .sort((a, b) => a[1].firstSeq - b[1].firstSeq)
+      .map(([name, group]) => ({
+        name,
+        tools: group.entries
+          .slice()
+          .sort((a, b) => (a.tool.order ?? 0) - (b.tool.order ?? 0) || a.seq - b.seq)
+          .map((entry) => entry.tool)
+      }))
+  }
+
+  /** 订阅注册表变化（register / unregister），返回取消订阅函数 */
+  onChange(handler: () => void): () => void {
+    return this.emitter.on('change', handler)
+  }
+}
+
+/**
+ * 全局默认注册表（USheet 默认渲染这里的工具；内置工具也注册于此）。
+ * 工具是应用级扩展：注册一次，所有 USheet 实例共享。
+ */
+export const defaultToolRegistry = new ToolRegistry()
+
+/** 注册工具到默认注册表 */
+export function registerTool(tool: SheetTool): void {
+  defaultToolRegistry.register(tool)
+}
+
+/** 从默认注册表注销工具；id 不存在时返回 false */
+export function unregisterTool(id: string): boolean {
+  return defaultToolRegistry.unregister(id)
+}

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from './sheet'

package/src/types/sheet.ts

@@ -0,0 +1,41 @@
+import type { DeconstructValue } from '@veltra/utils'
+import type { ComputedRef } from 'vue'
+
+import type { Sheet } from '../core/sheet'
+import type { Workbook } from '../core/workbook'
+import type { SheetGrid } from '../grid/sheet-grid'
+import type { SheetContext } from '../tools/context'
+
+/** 电子表格组件属性 */
+export interface SheetProps {
+  /** 工作簿实例（多 sheet / 跨表公式的载体）；缺省内部自建（单 sheet） */
+  workbook?: Workbook
+  /** 渲染行数，默认 100 */
+  rows?: number
+  /** 渲染列数，默认 26（A..Z） */
+  cols?: number
+  /** 是否显示工具栏，默认 true */
+  showToolbar?: boolean
+  /** 是否显示底部 sheet 标签栏，默认 true */
+  showTabs?: boolean
+}
+
+export interface SheetEmits {
+  /** 激活 sheet 切换（点击 tab 或宿主调用 workbook.activateSheet） */
+  (name: 'active-sheet-change', payload: { sheet: Sheet; index: number }): void
+}
+
+/** 在组件内部引用 */
+export interface _SheetExposed {
+  /** 当前工作簿（props.workbook 缺省时为内部自建实例） */
+  workbook: ComputedRef<Workbook>
+  /** 当前活动 sheet */
+  getActiveSheet: () => Sheet
+  /** 工具上下文（与工具栏工具同一门面；tab 切换后自动指向当前 sheet） */
+  getContext: () => SheetContext
+  /** 底层 SheetGrid（调试/测试用） */
+  getGrid: () => SheetGrid | undefined
+}
+
+/** 电子表格组件暴露的属性和方法 */
+export type SheetExposed = DeconstructValue<_SheetExposed>

package/src/vue/__test__/sheet-component.test.ts

@@ -0,0 +1,267 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { createApp, h, nextTick, ref, type App } from 'vue'
+
+import { Workbook } from '../../core/workbook'
+import { USheet } from '../../index'
+import { registerTool, unregisterTool } from '../../tools/registry'
+import type { SheetExposed } from '../../types'
+
+const apps: App[] = []
+const containers: HTMLElement[] = []
+
+function mount(
+  props: () => Record<string, unknown> = () => ({}),
+  exposedRef?: { value: SheetExposed | undefined }
+) {
+  const el = document.createElement('div')
+  el.style.width = '800px'
+  el.style.height = '600px'
+  document.body.appendChild(el)
+  containers.push(el)
+  const app = createApp({
+    render: () =>
+      h(USheet, {
+        ...props(),
+        ref: (value: unknown) => {
+          if (exposedRef) exposedRef.value = value as SheetExposed | undefined
+        }
+      })
+  })
+  app.mount(el)
+  apps.push(app)
+  return { app, el }
+}
+
+function createWorkbook() {
+  const workbook = new Workbook()
+  workbook.addSheet('Sheet2')
+  return workbook
+}
+
+function toolButton(el: HTMLElement, title: string): HTMLButtonElement | undefined {
+  return [...el.querySelectorAll<HTMLButtonElement>('.u-sheet__tool')].find((button) =>
+    button.textContent?.includes(title)
+  )
+}
+
+function tabs(el: HTMLElement): HTMLButtonElement[] {
+  return [...el.querySelectorAll<HTMLButtonElement>('.u-sheet__tab')]
+}
+
+afterEach(() => {
+  while (apps.length) apps.pop()!.unmount()
+  while (containers.length) containers.pop()!.remove()
+})
+
+describe('USheet 组件', () => {
+  it('挂载：工具栏渲染内置工具（分组 + 分隔符），tabs 显示 sheet 列表，grid 挂载', async () => {
+    const { el } = mount(() => ({ workbook: createWorkbook(), rows: 10, cols: 6 }))
+    await nextTick()
+
+    const tools = [...el.querySelectorAll('.u-sheet__tool')].map((button) =>
+      button.textContent?.trim()
+    )
+    expect(tools).toEqual(['撤销', '重做', '合并', '取消合并'])
+    // history 与 cell 两组之间一个分隔符
+    expect(el.querySelectorAll('.u-sheet__toolbar-divider')).toHaveLength(1)
+
+    expect(tabs(el).map((tab) => tab.textContent?.trim())).toEqual(['Sheet1', 'Sheet2'])
+    expect(tabs(el)[0]!.classList.contains('is-active')).toBe(true)
+
+    // VTable 已挂载到 grid 容器
+    expect(el.querySelector('.u-sheet__grid canvas')).not.toBeNull()
+  })
+
+  it('内置 undo/redo 按钮随 history-change 置灰，点击等效快捷键', async () => {
+    const workbook = createWorkbook()
+    const sheet = workbook.activeSheet
+    const { el } = mount(() => ({ workbook, rows: 10, cols: 6 }))
+    await nextTick()
+
+    const undoButton = toolButton(el, '撤销')!
+    const redoButton = toolButton(el, '重做')!
+    expect(undoButton.disabled).toBe(true)
+    expect(redoButton.disabled).toBe(true)
+
+    sheet.setCellValue({ row: 0, col: 0 }, 'x')
+    await nextTick()
+    expect(undoButton.disabled).toBe(false)
+    expect(redoButton.disabled).toBe(true)
+
+    undoButton.click()
+    await nextTick()
+    expect(sheet.getCellData({ row: 0, col: 0 })).toBeUndefined()
+    expect(undoButton.disabled).toBe(true)
+    expect(redoButton.disabled).toBe(false)
+
+    redoButton.click()
+    await nextTick()
+    expect(sheet.getCellData({ row: 0, col: 0 })).toEqual({ v: 'x', t: 's' })
+  })
+
+  it('tab 切换：active 样式移动，工具上下文指向当前 sheet', async () => {
+    const workbook = createWorkbook()
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(() => ({ workbook, rows: 10, cols: 6 }), exposed)
+    await nextTick()
+
+    expect(exposed.value?.getActiveSheet().name).toBe('Sheet1')
+    expect(exposed.value?.getContext().sheetName).toBe('Sheet1')
+
+    tabs(el)[1]!.click()
+    await nextTick()
+
+    expect(tabs(el)[1]!.classList.contains('is-active')).toBe(true)
+    // grid 重建：旧 VTable 已 release，容器内只有一个 canvas
+    expect(el.querySelectorAll('.u-sheet__grid canvas')).toHaveLength(1)
+    expect(exposed.value?.getActiveSheet().name).toBe('Sheet2')
+    // 工具上下文（与工具按钮同一门面）指向切换后的 sheet
+    expect(exposed.value?.getContext().sheetName).toBe('Sheet2')
+
+    // grid 已重建到 Sheet2：写入 Sheet2 应在表格可见
+    workbook.getSheet('Sheet2')!.setCellValue({ row: 0, col: 0 }, 's2')
+    await nextTick()
+    expect(exposed.value?.getGrid()?.getTable().getCellValue(1, 1)).toBe('s2')
+  })
+
+  it('props 变更响应：showToolbar/showTabs 显隐，rows 变化重建 grid', async () => {
+    const workbook = createWorkbook()
+    const state = ref({ rows: 10, showToolbar: true, showTabs: true })
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(
+      () => ({
+        workbook,
+        rows: state.value.rows,
+        cols: 6,
+        showToolbar: state.value.showToolbar,
+        showTabs: state.value.showTabs
+      }),
+      exposed
+    )
+    await nextTick()
+
+    const gridBefore = exposed.value?.getGrid()
+    expect(gridBefore).toBeDefined()
+
+    state.value = { ...state.value, showToolbar: false, showTabs: false }
+    await nextTick()
+    expect(el.querySelector('.u-sheet__toolbar')).toBeNull()
+    expect(el.querySelector('.u-sheet__tabs')).toBeNull()
+
+    state.value = { ...state.value, rows: 20 }
+    await nextTick()
+    const gridAfter = exposed.value?.getGrid()
+    expect(gridAfter).toBeDefined()
+    expect(gridAfter).not.toBe(gridBefore)
+  })
+
+  it('workbook prop 变更：tabs 与 grid 切到新工作簿', async () => {
+    const workbook1 = createWorkbook()
+    const workbook2 = new Workbook()
+    workbook2.addSheet('数据表')
+    const current = ref(workbook1)
+    const { el } = mount(() => ({ workbook: current.value, rows: 10, cols: 6 }))
+    await nextTick()
+    expect(tabs(el).map((tab) => tab.textContent?.trim())).toEqual(['Sheet1', 'Sheet2'])
+
+    current.value = workbook2
+    await nextTick()
+    expect(tabs(el).map((tab) => tab.textContent?.trim())).toEqual(['Sheet1', '数据表'])
+    expect(el.querySelector('.u-sheet__grid canvas')).not.toBeNull()
+  })
+
+  it('注册表联动：运行时 register/unregister 工具即时增删按钮', async () => {
+    const { el } = mount(() => ({ workbook: createWorkbook(), rows: 10, cols: 6 }))
+    await nextTick()
+    expect(toolButton(el, '临时工具')).toBeUndefined()
+
+    registerTool({ id: 'temp-tool', title: '临时工具', onClick: () => {} })
+    await nextTick()
+    expect(toolButton(el, '临时工具')).toBeDefined()
+
+    expect(unregisterTool('temp-tool')).toBe(true)
+    await nextTick()
+    expect(toolButton(el, '临时工具')).toBeUndefined()
+  })
+
+  it('无 props 默认挂载：内部自建工作簿（单 sheet），工具栏/tabs 正常', async () => {
+    const { el } = mount()
+    await nextTick()
+    expect(tabs(el).map((tab) => tab.textContent?.trim())).toEqual(['Sheet1'])
+    expect(el.querySelectorAll('.u-sheet__tool').length).toBeGreaterThan(0)
+    expect(el.querySelector('.u-sheet__grid canvas')).not.toBeNull()
+  })
+
+  it('多实例并存：共享注册表，工具点击只作用于各自实例的活动 sheet', async () => {
+    const workbook1 = new Workbook()
+    const workbook2 = new Workbook()
+    const first = mount(() => ({ workbook: workbook1, rows: 10, cols: 6 }))
+    const second = mount(() => ({ workbook: workbook2, rows: 10, cols: 6 }))
+    await nextTick()
+
+    registerTool({
+      id: 'mark-active',
+      title: '标记当前格',
+      onClick: (ctx) => {
+        const active = ctx.getSelection().activeCell ?? { row: 0, col: 0 }
+        ctx.setCellValue(active, 'marked')
+      }
+    })
+    await nextTick()
+
+    // 两个实例都渲染该工具（注册表全局共享）
+    const button1 = toolButton(first.el, '标记当前格')
+    const button2 = toolButton(second.el, '标记当前格')
+    expect(button1).toBeDefined()
+    expect(button2).toBeDefined()
+
+    // 点击实例 2 的工具 → 只写实例 2 的 sheet（各自 SheetContext 绑定各自工作簿）
+    workbook2.activeSheet.selectCell({ row: 2, col: 1 })
+    await nextTick()
+    button2!.click()
+    await nextTick()
+    expect(workbook2.activeSheet.getCellData({ row: 2, col: 1 })).toEqual({ v: 'marked', t: 's' })
+    expect(workbook1.activeSheet.getCellData({ row: 2, col: 1 })).toBeUndefined()
+
+    // 该写入经命令系统：实例 2 的 undo 可用且可撤销
+    expect(workbook2.activeSheet.canUndo).toBe(true)
+    workbook2.activeSheet.undo()
+    expect(workbook2.activeSheet.getCellData({ row: 2, col: 1 })).toBeUndefined()
+
+    unregisterTool('mark-active')
+  })
+
+  it('合并/取消合并按钮随选区联动，点击生效且可 undo', async () => {
+    const workbook = new Workbook()
+    const sheet = workbook.activeSheet
+    const { el } = mount(() => ({ workbook, rows: 10, cols: 6 }))
+    await nextTick()
+
+    const mergeButton = toolButton(el, '合并')!
+    const unmergeButton = toolButton(el, '取消合并')!
+    // 无选区：两者禁用
+    expect(mergeButton.disabled).toBe(true)
+    expect(unmergeButton.disabled).toBe(true)
+
+    // 拖选区域（经模型 API 模拟 grid 拖选回写）
+    sheet.selectRange({ start: { row: 0, col: 0 }, end: { row: 1, col: 1 } })
+    await nextTick()
+    expect(mergeButton.disabled).toBe(false)
+
+    mergeButton.click()
+    await nextTick()
+    expect(sheet.getCellInfo({ row: 1, col: 1 }).kind).toBe('merged-covered')
+
+    // 选中合并锚点 → 取消合并可用
+    sheet.selectCell({ row: 0, col: 0 })
+    await nextTick()
+    expect(unmergeButton.disabled).toBe(false)
+
+    unmergeButton.click()
+    await nextTick()
+    expect(sheet.getCellInfo({ row: 1, col: 1 }).kind).toBe('normal')
+
+    sheet.undo()
+    expect(sheet.getCellInfo({ row: 1, col: 1 }).kind).toBe('merged-covered')
+  })
+})

package/src/vue/index.ts

@@ -0,0 +1 @@
+export { default as USheet } from './sheet.vue'