@veltra/sheet 2.0.0 → 2.1.1

package/src/core/formula/tokenizer.ts

@@ -1,160 +0,0 @@
-/**
- * 公式分词器：数字 / 字符串 / 布尔 / 标识符（函数名、引用、表名）/ 带引号表名 / 运算符。
- *
- * 不做语义消歧：`A1`（引用）、`SUM`（函数名）、`Sheet2`（表名）统一产出 ident，
- * 由 parser 依据后随 token（`(` / `!` / `:` / 运算位）判定。
- */
-
-/** 解析失败异常（Sheet 层捕获 → 单元格记为 #ERROR!） */
-export class FormulaParseError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'FormulaParseError'
-  }
-}
-
-export type FormulaOperator =
-  | '+'
-  | '-'
-  | '*'
-  | '/'
-  | '^'
-  | '&'
-  | '%'
-  | '('
-  | ')'
-  | ','
-  | '!'
-  | ':'
-  | '='
-  | '<>'
-  | '<'
-  | '<='
-  | '>'
-  | '>='
-
-export type FormulaToken =
-  | { type: 'number'; value: number }
-  | { type: 'string'; value: string }
-  /** 标识符：函数名 / 单元格引用形态 / 裸表名（含 $ 绝对引用写法）；TRUE/FALSE 由 parser 归约为布尔 */
-  | { type: 'ident'; name: string }
-  /** 带单引号的表名（'' 转义为字面单引号） */
-  | { type: 'quoted-name'; name: string }
-  | { type: 'op'; op: FormulaOperator }
-
-const NUMBER_RE = /^(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?/
-
-/** 标识符首字符：字母 / _ / $ / 非 ASCII（中文表名等） */
-function isIdentStart(ch: string): boolean {
-  return /[A-Za-z_$]/.test(ch) || ch.charCodeAt(0) >= 0x80
-}
-
-/** 标识符后续字符：首字符集 + 数字 + . */
-function isIdentPart(ch: string): boolean {
-  return /[A-Za-z0-9_.$]/.test(ch) || ch.charCodeAt(0) >= 0x80
-}
-
-const TWO_CHAR_OPS = ['<>', '<=', '>='] as const
-const ONE_CHAR_OPS = [
-  '+',
-  '-',
-  '*',
-  '/',
-  '^',
-  '&',
-  '%',
-  '(',
-  ')',
-  ',',
-  '!',
-  ':',
-  '=',
-  '<',
-  '>'
-] as const
-
-/** 公式文本（不含 '='）→ token 序列；非法输入抛 FormulaParseError */
-export function tokenizeFormula(text: string): FormulaToken[] {
-  const tokens: FormulaToken[] = []
-  let i = 0
-  while (i < text.length) {
-    const ch = text[i]!
-    // 空白忽略（不支持 Excel 的空格交集运算符）
-    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
-      i++
-      continue
-    }
-    // 数字
-    if ((ch >= '0' && ch <= '9') || (ch === '.' && text[i + 1]! >= '0' && text[i + 1]! <= '9')) {
-      const match = NUMBER_RE.exec(text.slice(i))
-      if (!match) throw new FormulaParseError(`非法数字（位置 ${i + 1}）`)
-      tokens.push({ type: 'number', value: Number.parseFloat(match[0]) })
-      i += match[0].length
-      continue
-    }
-    // 字符串字面量（"..."，"" 转义）
-    if (ch === '"') {
-      let value = ''
-      let j = i + 1
-      for (;;) {
-        if (j >= text.length) throw new FormulaParseError('字符串缺少结束引号')
-        if (text[j] === '"') {
-          if (text[j + 1] === '"') {
-            value += '"'
-            j += 2
-            continue
-          }
-          break
-        }
-        value += text[j]
-        j++
-      }
-      tokens.push({ type: 'string', value })
-      i = j + 1
-      continue
-    }
-    // 带引号表名（'...'，'' 转义）
-    if (ch === "'") {
-      let name = ''
-      let j = i + 1
-      for (;;) {
-        if (j >= text.length) throw new FormulaParseError('表名缺少结束引号')
-        if (text[j] === "'") {
-          if (text[j + 1] === "'") {
-            name += "'"
-            j += 2
-            continue
-          }
-          break
-        }
-        name += text[j]
-        j++
-      }
-      tokens.push({ type: 'quoted-name', name })
-      i = j + 1
-      continue
-    }
-    // 标识符（函数名 / 引用 / 裸表名）
-    if (isIdentStart(ch)) {
-      let j = i + 1
-      while (j < text.length && isIdentPart(text[j]!)) j++
-      tokens.push({ type: 'ident', name: text.slice(i, j) })
-      i = j
-      continue
-    }
-    // 双字符运算符优先
-    const two = text.slice(i, i + 2)
-    if ((TWO_CHAR_OPS as readonly string[]).includes(two)) {
-      tokens.push({ type: 'op', op: two as FormulaOperator })
-      i += 2
-      continue
-    }
-    if ((ONE_CHAR_OPS as readonly string[]).includes(ch)) {
-      tokens.push({ type: 'op', op: ch as FormulaOperator })
-      i++
-      continue
-    }
-    throw new FormulaParseError(`无法识别的字符 "${ch}"（位置 ${i + 1}）`)
-  }
-  return tokens
-}

package/src/core/merge-manager.ts

@@ -1,158 +0,0 @@
-import {
-  boundingBox,
-  cellKey,
-  createRange,
-  iterateRange,
-  rangesIntersect,
-  type CellAddress,
-  type CellRange
-} from './address'
-
-/**
- * 合并单元格管理器（只管几何，不管数据）。
- *
- * - 锚点恒为区域左上角，数据只存在锚点格（数据搬迁由 Sheet 编排）
- * - merges：anchorKey → CellRange
- * - coverIndex：coveredCellKey（不含锚点自身）→ anchorKey，O(1) 查询
- */
-
-/** 单元格在合并语义下的种类 */
-export type MergedCellKind = 'normal' | 'merged-anchor' | 'merged-covered'
-
-export interface CellInfo {
-  kind: MergedCellKind
-  /** 锚点地址；普通格为自身 */
-  anchor: CellAddress
-  /** 所在合并区域；普通格无 */
-  mergeRange?: CellRange
-}
-
-export interface MergeResult {
-  /** 最终生效的合并区域（与既有合并相交时取包围盒，可能大于入参） */
-  range: CellRange
-  /** 本次被解除的既有合并 */
-  removed: CellRange[]
-}
-
-export class MergeManager {
-  private merges = new Map<number, CellRange>()
-  private coverIndex = new Map<number, number>()
-
-  /**
-   * 计算合并结果（纯查询，不修改状态）：
-   * 1. 所有与 range 相交的既有合并将被解除
-   * 2. 新区域 = range 与被解除合并的包围盒
-   */
-  computeMerge(range: CellRange): MergeResult {
-    const removed: CellRange[] = []
-    for (const existing of this.merges.values()) {
-      if (rangesIntersect(existing, range)) removed.push(existing)
-    }
-    const finalRange =
-      removed.length > 0 ? boundingBox([range, ...removed]) : createRange(range.start, range.end)
-    return { range: finalRange, removed }
-  }
-
-  /** 合并区域（解除相交既有合并 + 包围盒，见 computeMerge） */
-  merge(range: CellRange): MergeResult {
-    const result = this.computeMerge(range)
-    for (const item of result.removed) this.unregister(item)
-    this.register(result.range)
-    return result
-  }
-
-  /**
-   * 精确登记一个合并区域（不做相交解除与包围盒）。
-   * 低层接口，供命令系统回放补丁使用；调用方需保证不与既有合并相交。
-   */
-  addMerge(range: CellRange): void {
-    this.register(range)
-  }
-
-  /** 精确移除一个合并区域（按锚点匹配）；不存在时为空操作 */
-  removeMerge(range: CellRange): void {
-    this.unregister(range)
-  }
-
-  /** 解除所有与 range 相交的合并，返回被解除的区域 */
-  unmerge(range: CellRange): CellRange[] {
-    const removed: CellRange[] = []
-    for (const existing of this.merges.values()) {
-      if (rangesIntersect(existing, range)) removed.push(existing)
-    }
-    for (const item of removed) this.unregister(item)
-    return removed
-  }
-
-  /** 地址解析到锚点：被覆盖格 → 锚点；锚点/普通格 → 自身 */
-  resolveAnchor(addr: CellAddress): CellAddress {
-    const merge = this.getMergeAt(addr)
-    return merge ? { ...merge.start } : { ...addr }
-  }
-
-  /** 是否在任意合并区域内（含锚点） */
-  isMerged(addr: CellAddress): boolean {
-    return this.getMergeAt(addr) !== undefined
-  }
-
-  /** 是否为被覆盖的非锚点格 */
-  isCovered(addr: CellAddress): boolean {
-    return this.coverIndex.has(cellKey(addr))
-  }
-
-  /** 所在合并区域（锚点与被覆盖格均可查）；不在任何合并内返回 undefined */
-  getMergeAt(addr: CellAddress): CellRange | undefined {
-    const key = cellKey(addr)
-    const asAnchor = this.merges.get(key)
-    if (asAnchor) return asAnchor
-    const anchorKey = this.coverIndex.get(key)
-    return anchorKey === undefined ? undefined : this.merges.get(anchorKey)
-  }
-
-  /** 合并语义下的单元格信息 */
-  getCellInfo(addr: CellAddress): CellInfo {
-    const merge = this.getMergeAt(addr)
-    if (!merge) return { kind: 'normal', anchor: { ...addr } }
-    const anchor = { ...merge.start }
-    if (addr.row === anchor.row && addr.col === anchor.col) {
-      return { kind: 'merged-anchor', anchor, mergeRange: merge }
-    }
-    return { kind: 'merged-covered', anchor, mergeRange: merge }
-  }
-
-  /** 全部合并区域（迭代 merges 的副本） */
-  getMerges(): CellRange[] {
-    return [...this.merges.values()].map((range) => ({
-      start: { ...range.start },
-      end: { ...range.end }
-    }))
-  }
-
-  get size(): number {
-    return this.merges.size
-  }
-
-  clear(): void {
-    this.merges.clear()
-    this.coverIndex.clear()
-  }
-
-  private register(range: CellRange): void {
-    const anchorKey = cellKey(range.start)
-    this.merges.set(anchorKey, range)
-    for (const addr of iterateRange(range)) {
-      if (addr.row !== range.start.row || addr.col !== range.start.col) {
-        this.coverIndex.set(cellKey(addr), anchorKey)
-      }
-    }
-  }
-
-  private unregister(range: CellRange): void {
-    this.merges.delete(cellKey(range.start))
-    for (const addr of iterateRange(range)) {
-      if (addr.row !== range.start.row || addr.col !== range.start.col) {
-        this.coverIndex.delete(cellKey(addr))
-      }
-    }
-  }
-}

package/src/core/selection.ts

@@ -1,66 +0,0 @@
-import { createRange, type CellAddress, type CellRange } from './address'
-import { TypedEventEmitter } from './events'
-
-/**
- * 选区模型：activeCell + ranges。
- * activeCell 永远指向锚点（构造时注入 resolveAnchor）。
- */
-
-export interface SelectionState {
-  /** 活动单元格（锚点语义）；未选中时为 null */
-  activeCell: CellAddress | null
-  /** 选中区域列表（本阶段单选区，预留多选区） */
-  ranges: CellRange[]
-}
-
-type SelectionEvents = { change: SelectionState }
-
-export class SelectionModel {
-  private state: SelectionState = { activeCell: null, ranges: [] }
-  private emitter = new TypedEventEmitter<SelectionEvents>()
-
-  constructor(private readonly resolveAnchor: (addr: CellAddress) => CellAddress) {}
-
-  get activeCell(): CellAddress | null {
-    return this.state.activeCell
-  }
-
-  get ranges(): CellRange[] {
-    return this.state.ranges
-  }
-
-  /** 选中单格；被覆盖格自动解析到锚点 */
-  selectCell(addr: CellAddress): void {
-    const anchor = this.resolveAnchor(addr)
-    this.setState({ activeCell: anchor, ranges: [createRange(anchor, anchor)] })
-  }
-
-  /** 选中区域；activeCell 取区域起点的锚点 */
-  selectRange(range: CellRange): void {
-    const anchor = this.resolveAnchor(range.start)
-    this.setState({ activeCell: anchor, ranges: [range] })
-  }
-
-  getState(): SelectionState {
-    return {
-      activeCell: this.state.activeCell ? { ...this.state.activeCell } : null,
-      ranges: this.state.ranges.map((range) => ({
-        start: { ...range.start },
-        end: { ...range.end }
-      }))
-    }
-  }
-
-  clear(): void {
-    this.setState({ activeCell: null, ranges: [] })
-  }
-
-  on(handler: (state: SelectionState) => void): () => void {
-    return this.emitter.on('change', handler)
-  }
-
-  private setState(state: SelectionState): void {
-    this.state = state
-    this.emitter.emit('change', this.getState())
-  }
-}

package/src/core/sheet.ts

@@ -1,257 +0,0 @@
-import type { CellAddress, CellRange } from './address'
-import { inferCellType, CellStore, type CellData, type CellValue } from './cell-store'
-import { defaultCommandRegistry } from './command/default-registry'
-import { HistoryManager, type HistoryState } from './command/history'
-import { MergeCellsCommand, UnmergeCellsCommand } from './command/merge-cells'
-import { SetCellFormulaCommand } from './command/set-cell-formula'
-import { SetCellValueCommand, type SetCellValueItem } from './command/set-cell-value'
-import type { Mutation, Patch, PatchDirection } from './command/types'
-import { TypedEventEmitter } from './events'
-import { DependencyGraph } from './formula/dependency-graph'
-import { MergeManager, type CellInfo } from './merge-manager'
-import { SelectionModel, type SelectionState } from './selection'
-
-/**
- * Sheet = cell-store + merge-manager + selection + history 的组合，统一操作入口。
- *
- * 语义约定：
- * - `getCellData`：原始存储语义，被合并覆盖的非锚点格 → undefined
- * - `getDisplayValue`：锚点解析语义，被覆盖格返回锚点的值
- * - `setCellValue` / `selectCell`：内部先 resolveAnchor（用户操作永远落锚点）
- * - 一切写操作（setCellValue / setCell / setCells / setCellFormula / mergeCells / unmergeCells）
- *   都经命令系统执行（applyPatch 是唯一变更通道），天然获得 undo/redo 能力
- * - 公式：`setCellValue` 识别 '=' 前缀走 `setCellFormula`；命令执行后自动增量重算，
- *   重算派生变更（含跨表）并入同一 undo 单元
- */
-
-export type SheetEvents = {
-  /** 单元格数据变化（含删除） */
-  'cell-change': { addr: CellAddress }
-  /** 合并结构变化（合并/取消合并） */
-  'merge-change': { range: CellRange }
-  /** 选区变化 */
-  'selection-change': SelectionState
-  /** 历史栈变化（undo/redo 可用状态，供工具栏按钮置灰） */
-  'history-change': HistoryState
-}
-
-export class Sheet {
-  readonly store = new CellStore()
-  readonly merges = new MergeManager()
-  readonly selection: SelectionModel
-  /**  undo/redo 历史（命令系统） */
-  readonly history: HistoryManager
-  /** 公式依赖图（工作簿内多 sheet 共享；独立 Sheet 自建） */
-  readonly formulaGraph: DependencyGraph
-
-  name: string
-
-  private emitter = new TypedEventEmitter<SheetEvents>()
-
-  constructor(name = 'Sheet1', formulaGraph?: DependencyGraph) {
-    this.name = name
-    this.selection = new SelectionModel((addr) => this.merges.resolveAnchor(addr))
-    this.selection.on((state) => this.emitter.emit('selection-change', state))
-    this.history = new HistoryManager(this.boundApplyPatch)
-    this.history.onChange((state) => this.emitter.emit('history-change', state))
-    this.formulaGraph = formulaGraph ?? new DependencyGraph()
-    this.formulaGraph.registerSheet(this)
-  }
-
-  get rowCount(): number {
-    return this.store.rowCount
-  }
-
-  get colCount(): number {
-    return this.store.colCount
-  }
-
-  // ─── 单元格数据 ────────────────────────────────────────────
-
-  /** 原始存储语义读取（被覆盖格 → undefined） */
-  getCellData(addr: CellAddress): CellData | undefined {
-    return this.store.getCell(addr)
-  }
-
-  /** 锚点解析语义读取（被覆盖格 → 锚点的值） */
-  getDisplayValue(addr: CellAddress): CellValue | undefined {
-    const anchor = this.merges.resolveAnchor(addr)
-    return this.store.getCell(anchor)?.v ?? undefined
-  }
-
-  /** 写入原始值（解析到锚点；空值 = 清除）；'=' 前缀按公式处理；经命令执行，可撤销 */
-  setCellValue(addr: CellAddress, value: CellValue): void {
-    if (typeof value === 'string' && value.startsWith('=')) {
-      this.setCellFormula(addr, value)
-      return
-    }
-    const data = value == null || value === '' ? undefined : { v: value, t: inferCellType(value) }
-    this.setCells([{ addr, data }])
-  }
-
-  /** 写入完整 CellData（解析到锚点；空数据 = 清除）；经命令执行，可撤销 */
-  setCell(addr: CellAddress, data?: CellData): void {
-    this.setCells([{ addr, data }])
-  }
-
-  /**
-   * 写入公式（可带 '=' 前缀；空白公式 = 清除）；经命令执行，可撤销。
-   * 公式原文存 CellData.f，计算缓存（v/t）由增量重算填充；解析失败 → #ERROR!。
-   */
-  setCellFormula(addr: CellAddress, formula: string): void {
-    const text = formula.startsWith('=') ? formula.slice(1) : formula
-    if (text.trim() === '') {
-      this.setCells([{ addr, data: undefined }])
-      return
-    }
-    this.executeCommand(SetCellFormulaCommand.id, { addr, formula: text })
-  }
-
-  /** 批量写入（一次调用 = 一个 undo 单元，供粘贴/填充复用） */
-  setCells(items: SetCellValueItem[]): void {
-    this.executeCommand(SetCellValueCommand.id, { items })
-  }
-
-  // ─── 合并 ────────────────────────────────────────────────
-
-  /** 合并语义下的单元格信息（普通格 / 合并锚点 / 被覆盖格） */
-  getCellInfo(addr: CellAddress): CellInfo {
-    return this.merges.getCellInfo(addr)
-  }
-
-  /**
-   * 合并区域。值保留规则（同 Excel/univer）：
-   * 仅保留包围盒内按行主序第一个有值格的值，写入新锚点，其余被覆盖格清空。
-   * @returns 最终生效的合并区域（与既有合并相交时取包围盒）
-   */
-  mergeCells(range: CellRange): CellRange {
-    return this.executeCommand<CellRange>(MergeCellsCommand.id, { range })!
-  }
-
-  /** 解除与 range 相交的所有合并；仅原锚点保留值（被覆盖格本就无值） */
-  unmergeCells(range: CellRange): void {
-    this.executeCommand(UnmergeCellsCommand.id, { range })
-  }
-
-  // ─── 命令与历史 ──────────────────────────────────────────
-
-  /** 经默认注册表执行命令；产生的 mutation 与公式重算派生 mutation 一并推入历史 */
-  executeCommand<R = void>(commandId: string, params: unknown): R | undefined {
-    const result = defaultCommandRegistry.execute<R>(
-      { sheet: this, applyPatch: this.boundApplyPatch },
-      commandId,
-      params
-    )
-    if (result && result.mutations.length > 0) {
-      const mutations = [...result.mutations]
-      const recalcMutation = this.recalcAfterCommand(result.mutations)
-      if (recalcMutation) mutations.push(recalcMutation)
-      this.history.push(mutations)
-    }
-    return result?.result
-  }
-
-  /** 开启事务（事务内所有命令合并为一个 undo 单元；可嵌套，拍平到最外层） */
-  beginTransaction(): void {
-    this.history.beginTransaction()
-  }
-
-  /** 提交事务 */
-  commit(): void {
-    this.history.commit()
-  }
-
-  /** 回滚事务：还原缓冲中已应用的变更并放弃事务 */
-  rollback(): void {
-    this.history.rollback()
-  }
-
-  /** 撤销一步；无可撤销时返回 false */
-  undo(): boolean {
-    return this.history.undo()
-  }
-
-  /** 重做一步；无可重做时返回 false */
-  redo(): boolean {
-    return this.history.redo()
-  }
-
-  get canUndo(): boolean {
-    return this.history.canUndo
-  }
-
-  get canRedo(): boolean {
-    return this.history.canRedo
-  }
-
-  // ─── 选区 ────────────────────────────────────────────────
-
-  getSelection(): SelectionState {
-    return this.selection.getState()
-  }
-
-  /** 选中单格（被覆盖格自动定位锚点） */
-  selectCell(addr: CellAddress): void {
-    this.selection.selectCell(addr)
-  }
-
-  selectRange(range: CellRange): void {
-    this.selection.selectRange(range)
-  }
-
-  // ─── 事件 ────────────────────────────────────────────────
-
-  on<K extends keyof SheetEvents>(type: K, handler: (payload: SheetEvents[K]) => void): () => void {
-    return this.emitter.on(type, handler)
-  }
-
-  off<K extends keyof SheetEvents>(type: K, handler: (payload: SheetEvents[K]) => void): void {
-    this.emitter.off(type, handler)
-  }
-
-  // ─── 内部 ────────────────────────────────────────────────
-
-  private readonly boundApplyPatch = (patch: Patch, direction: PatchDirection): void => {
-    // 跨表重算的派生补丁路由到目标 sheet（回放经源 sheet 历史时同样按此路由）
-    const target = patch.kind === 'cell' ? (patch.sheet ?? this) : this
-    target.applyPatch(patch, direction)
-  }
-
-  /** 应用补丁：命令执行与 undo/redo 回放共用的唯一变更通道 */
-  private applyPatch(patch: Patch, direction: PatchDirection): void {
-    if (patch.kind === 'cell') {
-      const data = direction === 'redo' ? patch.after : patch.before
-      const previous = direction === 'redo' ? patch.before : patch.after
-      this.store.setCell(patch.addr, data)
-      // 公式依赖图同步（f 增/删/改 → 节点增/删/重建；undo/redo 回放同样覆盖）
-      this.formulaGraph.syncCell(this, patch.addr, previous, data)
-      this.emitter.emit('cell-change', { addr: patch.addr })
-      return
-    }
-    const exists = direction === 'redo' ? patch.after : patch.before
-    if (exists) {
-      this.merges.addMerge(patch.range)
-    } else {
-      this.merges.removeMerge(patch.range)
-    }
-    this.emitter.emit('merge-change', { range: patch.range })
-  }
-
-  /**
-   * 命令执行后的公式增量重算：从命令 mutation 提取变更格 → 依赖图标脏 +
-   * 拓扑序重算 → 派生补丁立即应用，作为附加 mutation 并入同一 undo 单元。
-   * undo/redo 纯补丁回放（不重算），图状态由 applyPatch 内的 syncCell 维持。
-   */
-  private recalcAfterCommand(mutations: Mutation[]): Mutation | undefined {
-    const changed: { sheet: Sheet; addr: CellAddress }[] = []
-    for (const mutation of mutations) {
-      for (const patch of mutation.redo) {
-        if (patch.kind === 'cell') changed.push({ sheet: patch.sheet ?? this, addr: patch.addr })
-      }
-    }
-    const derived = this.formulaGraph.recalc(changed)
-    if (derived.length === 0) return undefined
-    for (const patch of derived) this.boundApplyPatch(patch, 'redo')
-    return { redo: derived, undo: [...derived].reverse() }
-  }
-}