@veltra/sheet 2.0.1 → 2.1.1

package/src/vue/use-sheet-state.ts

@@ -0,0 +1,161 @@
+import type { Sheet } from '@veltra/sheet-core/core/sheet'
+import { Workbook } from '@veltra/sheet-core/core/workbook'
+import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watch } from 'vue'
+
+import { createSheetContext } from '../tools/context'
+import { defaultToolRegistry } from '../tools/registry'
+import type { SheetProps } from '../types'
+
+/**
+ * useSheetState 与宿主组件的协作钩子。
+ * 弹层关闭 / 网格重建是宿主编排动作（由 use-tool-popup / use-sheet-grid 提供），
+ * 以钩子注入避免组合函数之间互相引用。
+ */
+export interface SheetStateHooks {
+  /** 活动 sheet 或工作簿切换前调用（关闭弹层并提交面板事务） */
+  onBeforeSheetChange: () => void
+  /** 需要重建网格（structure-change / 工作簿切换 / 导入替换）：清缓存 + 重建激活实例 */
+  rebuildGrid: () => void
+  /** tab 切换：优先复用 LRU 缓存实例（零重建），未命中才新建 */
+  activateGrid: () => void
+  /** sheet 列表变化（增删）后清理已删除 sheet 的缓存实例 */
+  pruneCache?: (sheets: ReadonlyArray<Sheet>) => void
+}
+
+type Emit = (event: 'active-sheet-change', payload: { sheet: Sheet; index: number }) => void
+
+/**
+ * USheet 的状态源（单一数据源，其余状态由此推导）：
+ * - workbook（外部传入或内部自建单 sheet 工作簿）、sheetList、activeIndex、activeSheet
+ * - SheetContext 工具门面（动态解析活动 sheet，tab 切换后自动指向当前 sheet）
+ * - stateTick：工具 visible/disabled/active 等纯函数的状态源版本号（bump 触发重算）
+ * - 工作簿 / 活动 sheet 的事件绑定（tab 切换、工作簿 prop 变更时重绑）
+ */
+export function useSheetState(props: SheetProps, emit: Emit, hooks: SheetStateHooks) {
+  /** 工作簿：外部传入或内部自建（单 sheet） */
+  const internalWorkbook = new Workbook()
+  const workbook = computed(() => props.workbook ?? internalWorkbook)
+
+  /** 激活 sheet 索引（镜像 workbook.activeSheetIndex，经事件同步） */
+  const activeIndex = ref(workbook.value.activeSheetIndex)
+  /** sheet 列表（tabs 渲染；由 sheets-change 同步） */
+  const sheetList = shallowRef<Sheet[]>(workbook.value.getSheets())
+  const activeSheet = computed(
+    () => sheetList.value[activeIndex.value] ?? workbook.value.activeSheet
+  )
+
+  /** 工具上下文：动态解析活动 sheet 与当前工作簿，tab 切换 / workbook prop 切换后自动指向最新值 */
+  const context = createSheetContext(
+    () => activeSheet.value,
+    () => workbook.value
+  )
+
+  /** 工具栏状态版本号：visible/disabled/active 是 (ctx) => boolean 纯函数，状态源变化时 bump 触发重算 */
+  const stateTick = ref(0)
+  const bump = (): void => {
+    stateTick.value++
+  }
+
+  let disposeSheetEvents: (() => void)[] = []
+  /** 订阅活动 sheet 的状态源（tab 切换 / 工作簿变更时重绑） */
+  function bindSheetEvents(sheet: Sheet): void {
+    for (const dispose of disposeSheetEvents) dispose()
+    // 高频变更（选区移动 / 批量写入逐补丁 cell-change）的 bump 合并到微任务：
+    // N 补丁 → 1 次 bump，工具栏 visible/disabled/active 整树重算每帧最多一次（#25）
+    let tickScheduled = false
+    const scheduleBump = (): void => {
+      if (tickScheduled) return
+      tickScheduled = true
+      queueMicrotask(() => {
+        tickScheduled = false
+        bump()
+      })
+    }
+    disposeSheetEvents = [
+      sheet.on('selection-change', bump),
+      sheet.on('history-change', bump),
+      sheet.on('cell-change', bump),
+      sheet.on('merge-change', bump),
+      sheet.on('frozen-change', bump),
+      // 整表内容替换（导入 / undo/redo 回放）：restore 静默不发 cell-change，
+      // 状态源需 bump（grid 层自行订阅 content-reset 全量刷新，此处不重建）
+      sheet.on('content-reset', scheduleBump),
+      // 行列插入/删除 → 重建网格（渲染行列数 = max(props, sheet.rows/cols)，
+      // 数据/选区/冻结/行高随重建恢复；低频操作直接重建）
+      sheet.on('structure-change', hooks.rebuildGrid)
+    ]
+  }
+
+  let disposeWorkbookEvents: (() => void)[] = []
+  function bindWorkbookEvents(wb: Workbook): void {
+    for (const dispose of disposeWorkbookEvents) dispose()
+    disposeWorkbookEvents = [
+      wb.on('sheets-change', ({ sheets }) => {
+        sheetList.value = sheets
+        // 删除的 sheet 不在列表中 → 及时释放其缓存实例（含事件订阅）
+        hooks.pruneCache?.(sheets)
+        bump()
+      }),
+      wb.on('sheet-rename', () => {
+        // sheet 对象未变（浅引用），换新数组引用触发 tab 文本重渲染
+        sheetList.value = workbook.value.getSheets()
+        bump()
+      }),
+      wb.on('active-sheet-change', ({ sheet, index }) => {
+        hooks.onBeforeSheetChange() // tab 切换：关闭弹层并提交面板事务
+        activeIndex.value = index
+        bindSheetEvents(sheet)
+        // tab 切换走实例缓存（命中零重建）；structure-change / 工作簿替换走 rebuildGrid
+        hooks.activateGrid()
+        // 删除激活 sheet 的联动：activateGrid 已切到新实例，此刻 prune 可释放
+        // 刚被替换的旧激活实例（sheets-change 先于 active-sheet-change 派发，
+        // 彼时旧实例仍是 active 被保留）
+        hooks.pruneCache?.(workbook.value.getSheets())
+        bump()
+        emit('active-sheet-change', { sheet, index })
+      })
+    ]
+  }
+
+  /**
+   * 工作簿内容被结构性替换后同步（如导入 xlsx 的 replaceWorkbook）：
+   * replaceWorkbook 未必触发 active-sheet-change（同 index），需显式同步 tabs、
+   * 重绑 sheet 事件并重建网格。
+   */
+  function syncFromWorkbook(): void {
+    sheetList.value = workbook.value.getSheets()
+    activeIndex.value = workbook.value.activeSheetIndex
+    bindSheetEvents(activeSheet.value)
+    hooks.rebuildGrid()
+    bump()
+  }
+
+  const offRegistryChange = defaultToolRegistry.onChange(bump)
+
+  onMounted(() => {
+    bindWorkbookEvents(workbook.value)
+    bindSheetEvents(activeSheet.value)
+  })
+
+  watch(
+    () => props.workbook,
+    (wb, prev) => {
+      if (wb === prev) return
+      hooks.onBeforeSheetChange() // 工作簿切换：关闭弹层并提交面板事务
+      activeIndex.value = workbook.value.activeSheetIndex
+      sheetList.value = workbook.value.getSheets()
+      bindWorkbookEvents(workbook.value)
+      bindSheetEvents(activeSheet.value)
+      hooks.rebuildGrid()
+      bump()
+    }
+  )
+
+  onBeforeUnmount(() => {
+    offRegistryChange()
+    for (const dispose of disposeWorkbookEvents) dispose()
+    for (const dispose of disposeSheetEvents) dispose()
+  })
+
+  return { workbook, activeIndex, sheetList, activeSheet, context, stateTick, syncFromWorkbook }
+}

package/src/vue/use-sheet-tabs-bar.ts

@@ -0,0 +1,115 @@
+import {
+  applyWheelHorizontalScroll,
+  computeOverflowNavState,
+  scrollElementIntoView,
+  scrollViewportByStep
+} from '@veltra/utils'
+import { type Ref, nextTick, onBeforeUnmount, onMounted, shallowRef, watch } from 'vue'
+
+/** 模板 ref（useTemplateRef / shallowRef 均可） */
+type ElRef = { readonly value: HTMLElement | null | undefined }
+
+interface UseSheetTabsBarOptions {
+  viewportRef: ElRef
+  listRef: ElRef
+  /** sheet 列表（长度变化触发导航状态刷新） */
+  sheetList: Ref<readonly unknown[]>
+  /** 活动 tab 下标（number，非 string key） */
+  activeIndex: Ref<number>
+}
+
+/**
+ * Sheet 底部标签栏溢出滚动（滚动几何/滚轮转横滚/元素滚入视野共享
+ * @veltra/utils overflow-nav，见 #17；此处保留事件绑定与 watch 差异）：
+ * - showNav / canPrev / canNext
+ * - 箭头按视口宽度 ~80% 步进
+ * - 活动 tab 滚入视野
+ * - 纵向滚轮转横滚；触控板横滑不拦截
+ * - 原生 ResizeObserver（不引入 @veltra/compositions peer）
+ */
+export function useSheetTabsBar(options: UseSheetTabsBarOptions) {
+  const { viewportRef, listRef, sheetList, activeIndex } = options
+
+  const showNav = shallowRef(false)
+  const canPrev = shallowRef(false)
+  const canNext = shallowRef(false)
+
+  let resizeObserver: ResizeObserver | undefined
+
+  const updateNavState = () => {
+    const vp = viewportRef.value
+    if (!vp) return
+    const state = computeOverflowNavState(vp)
+    showNav.value = state.overflowing
+    canPrev.value = state.canPrev
+    canNext.value = state.canNext
+  }
+
+  const scrollByStep = (dir: 1 | -1) => {
+    const vp = viewportRef.value
+    if (!vp) return
+    scrollViewportByStep(vp, dir)
+  }
+
+  const ensureActiveVisible = () => {
+    const vp = viewportRef.value
+    const list = listRef.value
+    if (!vp || !list) return
+    const index = activeIndex.value
+    if (index < 0) return
+    const el = list.children[index] as HTMLElement | undefined
+    if (!el) return
+    scrollElementIntoView(vp, el)
+  }
+
+  /** 鼠标滚轮（纵向）驱动水平滚动；触控板横滑（已有 deltaX）不拦截 */
+  const handleWheel = (e: WheelEvent) => {
+    const vp = viewportRef.value
+    if (!vp) return
+    applyWheelHorizontalScroll(e, vp, showNav.value)
+  }
+
+  watch(activeIndex, async () => {
+    await nextTick()
+    ensureActiveVisible()
+    updateNavState()
+  })
+
+  watch(
+    sheetList,
+    async () => {
+      await nextTick()
+      updateNavState()
+      ensureActiveVisible()
+    },
+    { deep: false }
+  )
+
+  onMounted(() => {
+    const vp = viewportRef.value
+    const list = listRef.value
+    if (vp) {
+      vp.addEventListener('wheel', handleWheel, { passive: false })
+      vp.addEventListener('scroll', updateNavState, { passive: true })
+    }
+    if (typeof ResizeObserver !== 'undefined') {
+      resizeObserver = new ResizeObserver(() => updateNavState())
+      if (vp) resizeObserver.observe(vp)
+      if (list) resizeObserver.observe(list)
+    }
+    updateNavState()
+    nextTick(ensureActiveVisible)
+  })
+
+  onBeforeUnmount(() => {
+    const vp = viewportRef.value
+    if (vp) {
+      vp.removeEventListener('wheel', handleWheel)
+      vp.removeEventListener('scroll', updateNavState)
+    }
+    resizeObserver?.disconnect()
+    resizeObserver = undefined
+  })
+
+  return { showNav, canPrev, canNext, scrollByStep }
+}

package/src/vue/use-tool-groups.ts

@@ -0,0 +1,61 @@
+import { computed, type ComputedRef, type Ref } from 'vue'
+
+import type { SheetContext } from '../tools/context'
+import { defaultToolRegistry, type SheetTool } from '../tools/registry'
+
+/** 工具栏按钮视图模型 */
+export interface ToolGroupItem {
+  tool: SheetTool
+  disabled: boolean
+  active: boolean
+}
+
+/** 工具栏分组视图模型（组间渲染分隔符） */
+export interface ToolGroupView {
+  name: string
+  tools: ToolGroupItem[]
+}
+
+/**
+ * 内置组稳定顺序：history ｜ cell ｜ text ｜ edit ｜ insert ｜ file。
+ * 未列出的自定义组按注册先后排在已知组之后。
+ */
+const BUILTIN_GROUP_ORDER = ['history', 'cell', 'text', 'edit', 'insert', 'file'] as const
+
+/**
+ * 工具栏分组视图模型：工具的 visible/disabled/active 是 (ctx) => boolean 纯函数，
+ * 依赖 stateTick 版本号（选区 / 历史 / 单元格 / 合并 / 冻结 / 注册表变化时 bump）触发重算。
+ */
+export function useToolGroups(
+  context: SheetContext,
+  stateTick: Ref<number>
+): ComputedRef<ToolGroupView[]> {
+  return computed(() => {
+    void stateTick.value // 依赖状态源：选区 / 历史 / 单元格 / 合并 / 冻结 / 注册表
+    const groups = defaultToolRegistry
+      .getGroups()
+      .map((group) => ({
+        name: group.name,
+        tools: group.tools
+          .map((tool) => ({
+            tool,
+            visible: tool.visible?.(context) ?? true,
+            disabled: tool.disabled?.(context) ?? false,
+            active: tool.active?.(context) ?? false
+          }))
+          .filter((item) => item.visible)
+      }))
+      .filter((group) => group.tools.length > 0)
+
+    const orderIndex = new Map<string, number>(
+      BUILTIN_GROUP_ORDER.map((name, index) => [name, index])
+    )
+    return groups.sort((a, b) => {
+      const ai = orderIndex.get(a.name) ?? BUILTIN_GROUP_ORDER.length
+      const bi = orderIndex.get(b.name) ?? BUILTIN_GROUP_ORDER.length
+      if (ai !== bi) return ai - bi
+      // 未知组之间保持 getGroups() 注册序（已稳定）
+      return 0
+    })
+  })
+}

package/src/vue/use-tool-popup.ts

@@ -0,0 +1,150 @@
+import { onBeforeUnmount, onMounted, shallowRef } from 'vue'
+
+import type { SheetContext } from '../tools/context'
+import { defaultToolRegistry, type SheetTool } from '../tools/registry'
+
+/** 模板 ref 只读形态 */
+type ElRef = { readonly value: HTMLElement | null | undefined }
+
+/**
+ * 面板打开期间的写入是否合并为一个 undo 单元（关闭时提交）：
+ * 填充颜色 / 边框 / 字体颜色 / 字号参与事务；查找（每次替换独立 undo）、
+ * 导出（下载侧效应，无模型写入）不参与。导入无弹层，不经此路径。
+ */
+function joinsTransaction(tool: SheetTool): boolean {
+  return (
+    tool.popup === 'fill-color' ||
+    tool.popup === 'border' ||
+    tool.popup === 'font-color' ||
+    tool.popup === 'font-size'
+  )
+}
+
+/**
+ * 弹层型工具编排（填充颜色 / 边框 / 查找 / 插入图片 / 导出）：
+ * - popupTool：当前打开的弹层工具（null = 未打开）
+ * - popupAnchor：触发按钮元素（面板定位参照，见 sheet.vue 的 left 计算）
+ * - 打开 / 关闭时的事务包裹（面板期间写入合并为一个 undo 单元，关闭时提交）
+ * - 点击面板外关闭（面板内 @click.stop 不冒泡到 window）
+ * - Ctrl/Cmd+F 开合查找条（与工具按钮同一 toggle 逻辑）
+ * 导入在 sheet.vue 特殊处理（直接系统文件选择），不经弹层。
+ */
+export function useToolPopup(context: SheetContext, rootEl: ElRef) {
+  /** 当前打开的弹层工具（null = 未打开） */
+  const popupTool = shallowRef<SheetTool | null>(null)
+  /** 触发按钮元素（打开时的 currentTarget；用于面板 left 对齐按钮） */
+  const popupAnchor = shallowRef<HTMLElement | null>(null)
+  /** 延迟打开定时器（#23：组件卸载后不再执行 openPopup） */
+  let openTimer: ReturnType<typeof setTimeout> | null = null
+
+  function openPopup(tool: SheetTool, anchor?: HTMLElement | null): void {
+    closePopup()
+    popupTool.value = tool
+    popupAnchor.value = anchor ?? null
+    // 面板打开期间的所有写入合并为一个 undo 单元（关闭时提交）
+    if (joinsTransaction(tool)) context.beginTransaction()
+  }
+
+  /**
+   * 延迟到本次点击事件流结束后打开（setTimeout 宏任务，避开冒泡到 window 时
+   * onWindowClick 误关——queueMicrotask 会在事件传播中途的 microtask checkpoint
+   * 执行，面板会被同一 click 关闭）。保存 timer id，卸载/提前关闭时取消。
+   */
+  function scheduleOpen(tool: SheetTool, anchor?: HTMLElement | null): void {
+    if (openTimer !== null) clearTimeout(openTimer)
+    openTimer = setTimeout(() => {
+      openTimer = null
+      openPopup(tool, anchor)
+    }, 0)
+  }
+
+  /** 关闭弹层并提交面板期间的事务（无写入则空事务，不入历史） */
+  function closePopup(): void {
+    if (openTimer !== null) {
+      clearTimeout(openTimer)
+      openTimer = null
+    }
+    const tool = popupTool.value
+    if (!tool) return
+    popupTool.value = null
+    popupAnchor.value = null
+    if (!joinsTransaction(tool)) return
+    try {
+      context.commit()
+    } catch {
+      context.rollback()
+    }
+  }
+
+  function handleToolClick(tool: SheetTool, event?: MouseEvent): void {
+    if (tool.disabled?.(context)) return
+    if (tool.popup) {
+      // 弹层工具：同 id 再点 = 关闭；否则延迟打开（见 scheduleOpen）
+      if (popupTool.value?.id === tool.id) {
+        closePopup()
+        return
+      }
+      const anchor =
+        event?.currentTarget instanceof HTMLElement ? (event.currentTarget as HTMLElement) : null
+      scheduleOpen(tool, anchor)
+      return
+    }
+    tool.onClick(context)
+  }
+
+  /**
+   * 点击面板外任意处关闭。面板内部 @click.stop 不冒泡到 window；
+   * 触发按钮本身的点击由 handleToolClick 同步处理（打开/关闭 toggle），
+   * 冒泡到达这里时 popupTool 已更新，不会误关。
+   */
+  function onWindowClick(): void {
+    if (!popupTool.value) return
+    closePopup()
+  }
+
+  /** Ctrl/Cmd+F 打开 / 关闭查找条（与工具按钮同一 toggle 逻辑） */
+  function onGlobalKeydown(event: KeyboardEvent): void {
+    if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== 'f') return
+    // 仅当焦点/事件源落在本实例容器内才响应（#6）：容器外不得 preventDefault，
+    // 否则劫持浏览器原生查找（页面任意位置按 Ctrl+F 都被屏蔽）；同页多实例
+    // 也各只响应自己容器内的按键，不再每个实例都弹出查找条
+    const root = rootEl.value
+    if (root) {
+      const target = event.target instanceof Node ? event.target : null
+      const active = document.activeElement instanceof Node ? document.activeElement : null
+      const inside =
+        (target !== null && root.contains(target)) || (active !== null && root.contains(active))
+      // 例外：弹层 Teleport 到 body 级 #pop-container（不在 root 内），本实例弹层
+      // 打开期间焦点在弹层输入框里（如查找条内再按 Ctrl+F）——同样视为本实例的
+      // 按键，否则查找条无法 toggle 关闭，且放行浏览器原生查找盖在上面。
+      // （弹层打开期间点击容器外任意处会先经 onWindowClick 关闭弹层，故
+      // popupTool 非空时焦点必然属于本实例，多实例不会互相抢占）
+      if (!inside && popupTool.value === null) return
+    }
+    event.preventDefault()
+    const findTool = defaultToolRegistry.get('find')
+    if (!findTool) return
+    if (popupTool.value?.id === findTool.id) {
+      closePopup()
+      return
+    }
+    scheduleOpen(findTool)
+  }
+
+  onMounted(() => {
+    window.addEventListener('click', onWindowClick)
+    window.addEventListener('keydown', onGlobalKeydown)
+  })
+
+  onBeforeUnmount(() => {
+    if (openTimer !== null) {
+      clearTimeout(openTimer)
+      openTimer = null
+    }
+    closePopup()
+    window.removeEventListener('click', onWindowClick)
+    window.removeEventListener('keydown', onGlobalKeydown)
+  })
+
+  return { popupTool, popupAnchor, closePopup, handleToolClick }
+}

package/src/vue/use-toolbar-scroll.ts

@@ -0,0 +1,95 @@
+import {
+  applyWheelHorizontalScroll,
+  computeOverflowNavState,
+  scrollViewportByStep
+} from '@veltra/utils'
+import { onBeforeUnmount, onMounted, shallowRef, watch, type Ref } from 'vue'
+
+/** 模板 ref（useTemplateRef / shallowRef 均可） */
+type ElRef = { readonly value: HTMLElement | null | undefined }
+
+interface UseToolbarScrollOptions {
+  /** 单行滚动视口（overflow-x: auto） */
+  viewportRef: ElRef
+  /** 工具列表容器（宽度随内容增长） */
+  listRef: ElRef
+  /** 内容源（工具组变化触发导航状态刷新） */
+  content: Ref<readonly unknown[]>
+}
+
+/**
+ * 工具栏溢出滚动（滚动几何/滚轮转横滚共享 @veltra/utils overflow-nav，见 #17；
+ * 无活动项跟随）：
+ * - 内容超出视口宽度时显示左右箭头（showNav / canPrev / canNext）
+ * - 箭头按视口宽度 ~80% 步进
+ * - 纵向滚轮转横滚；触控板横滑不拦截
+ * - 原生 ResizeObserver（不引入 @veltra/compositions peer）
+ */
+export function useToolbarScroll(options: UseToolbarScrollOptions) {
+  const { viewportRef, listRef, content } = options
+
+  const showNav = shallowRef(false)
+  const canPrev = shallowRef(false)
+  const canNext = shallowRef(false)
+
+  let resizeObserver: ResizeObserver | undefined
+
+  const updateNavState = () => {
+    const vp = viewportRef.value
+    if (!vp) return
+    const state = computeOverflowNavState(vp)
+    showNav.value = state.overflowing
+    canPrev.value = state.canPrev
+    canNext.value = state.canNext
+  }
+
+  const scrollByStep = (dir: 1 | -1) => {
+    const vp = viewportRef.value
+    if (!vp) return
+    scrollViewportByStep(vp, dir)
+  }
+
+  /** 鼠标滚轮（纵向）驱动水平滚动；触控板横滑（已有 deltaX）不拦截 */
+  const handleWheel = (e: WheelEvent) => {
+    const vp = viewportRef.value
+    if (!vp) return
+    applyWheelHorizontalScroll(e, vp, showNav.value)
+  }
+
+  // 工具显隐 / 分组变化后宽度改变 → 刷新导航状态（等 DOM 更新完成再测）
+  watch(
+    content,
+    async () => {
+      await Promise.resolve()
+      updateNavState()
+    },
+    { deep: false }
+  )
+
+  onMounted(() => {
+    const vp = viewportRef.value
+    if (vp) {
+      vp.addEventListener('wheel', handleWheel, { passive: false })
+      vp.addEventListener('scroll', updateNavState, { passive: true })
+    }
+    if (typeof ResizeObserver !== 'undefined') {
+      resizeObserver = new ResizeObserver(() => updateNavState())
+      if (vp) resizeObserver.observe(vp)
+      const list = listRef.value
+      if (list) resizeObserver.observe(list)
+    }
+    updateNavState()
+  })
+
+  onBeforeUnmount(() => {
+    const vp = viewportRef.value
+    if (vp) {
+      vp.removeEventListener('wheel', handleWheel)
+      vp.removeEventListener('scroll', updateNavState)
+    }
+    resizeObserver?.disconnect()
+    resizeObserver = undefined
+  })
+
+  return { showNav, canPrev, canNext, scrollByStep }
+}

package/dist/core/address.d.ts

@@ -1,60 +0,0 @@
-//#region src/core/address.d.ts
-/**
- * A1 地址系统（纯函数）。
- *
- * 坐标统一 0-based：`{ row: 0, col: 0 }` 即 A1。
- * 区域为闭区间，且经过规范化：start 恒为左上角，end 恒为右下角。
- */
-/** 单元格地址（0-based） */
-interface CellAddress {
-  row: number;
-  col: number;
-}
-/** 单元格区域（闭区间，start 左上角，end 右下角） */
-interface CellRange {
-  start: CellAddress;
-  end: CellAddress;
-}
-/**
- * cellKey 的列基数（2^20）。
- * key = row * COL_KEY_BASE + col，要求 col < COL_KEY_BASE；
- * JS 安全整数范围内可容纳约 8.5e9 行，远超实际使用。
- */
-declare const COL_KEY_BASE: number;
-/** 地址 → 数值 key（Map 索引用） */
-declare function cellKey(addr: CellAddress): number;
-/** 数值 key → 地址 */
-declare function addressFromKey(key: number): CellAddress;
-/** 列号（0-based）→ 列名：0 → 'A'，25 → 'Z'，26 → 'AA' */
-declare function colIndexToName(col: number): string;
-/** 列名 → 列号（0-based）：'A' → 0，'AA' → 26；非法列名返回 -1 */
-declare function colNameToIndex(name: string): number;
-/** 解析 A1 记法（兼容 `$A$1` 绝对引用写法）→ 地址；非法返回 null */
-declare function parseAddress(text: string): CellAddress | null;
-/** 地址 → A1 记法：{ row: 1, col: 1 } → 'B2' */
-declare function formatAddress(addr: CellAddress): string;
-/** 由两个角点构造规范化区域（start ≤ end） */
-declare function createRange(a: CellAddress, b: CellAddress): CellRange;
-/** 解析区域记法：'B2' 或 'B2:D5'（兼容绝对引用）；非法返回 null */
-declare function parseRange(text: string): CellRange | null;
-/** 区域 → 记法：单格 → 'B2'，多格 → 'B2:D5' */
-declare function formatRange(range: CellRange): string;
-/** 地址相等 */
-declare function addressesEqual(a: CellAddress, b: CellAddress): boolean;
-/** 区域相等 */
-declare function rangesEqual(a: CellRange, b: CellRange): boolean;
-/** 两区域是否相交 */
-declare function rangesIntersect(a: CellRange, b: CellRange): boolean;
-/** 区域是否包含地址 */
-declare function rangeContainsAddress(range: CellRange, addr: CellAddress): boolean;
-/** 区域是否完整包含另一区域 */
-declare function rangeContainsRange(outer: CellRange, inner: CellRange): boolean;
-/** 一组区域的最小包围盒（至少传入一个区域） */
-declare function boundingBox(ranges: readonly [CellRange, ...CellRange[]]): CellRange;
-/** 按行主序遍历区域内的所有地址 */
-declare function iterateRange(range: CellRange): Generator<CellAddress, void, undefined>;
-/** 区域内的单元格数量 */
-declare function rangeSize(range: CellRange): number;
-//#endregion
-export { COL_KEY_BASE, CellAddress, CellRange, addressFromKey, addressesEqual, boundingBox, cellKey, colIndexToName, colNameToIndex, createRange, formatAddress, formatRange, iterateRange, parseAddress, parseRange, rangeContainsAddress, rangeContainsRange, rangeSize, rangesEqual, rangesIntersect };
-//# sourceMappingURL=address.d.ts.map