@veltra/sheet 2.0.0 → 2.1.1

package/src/vue/formula-bar.vue

@@ -0,0 +1,473 @@
+<template>
+  <div :class="cls.e('formula-bar')">
+    <input
+      v-model="nameDraft"
+      :class="cls.e('name-box')"
+      spellcheck="false"
+      autocomplete="off"
+      title="单元格地址或区域（如 B3 或 B3:D5），回车跳转"
+      @focus="nameFocused = true"
+      @blur="handleNameBlur"
+      @keydown="handleNameKeydown"
+    />
+    <span :class="cls.e('fx-label')">fx</span>
+    <div :class="cls.e('fx-editor')">
+      <!-- 文档流只占单行；面板绝对定位向下浮起，不撑开公式栏 -->
+      <div :class="[cls.e('fx-input-panel'), bem.is('expanded', fxExpanded)]">
+        <textarea
+          ref="fxRef"
+          v-model="fxDraft"
+          :class="cls.e('fx-input')"
+          :disabled="fxDisabled"
+          :readonly="mirroring"
+          rows="1"
+          spellcheck="false"
+          autocomplete="off"
+          title="活动单元格内容（'=' 开头为公式）；Enter 提交，Esc 取消"
+          @focus="handleFxFocus"
+          @blur="handleFxBlur"
+          @keydown="handleFxKeydown"
+          @input="handleFxInput"
+          @click="syncFxCursor"
+          @keyup="syncFxCursor"
+          @select="syncFxCursor"
+        />
+        <u-formula-suggest-list
+          :items="suggestItems"
+          :active-index="suggestIndex"
+          @select="confirmSuggest"
+          @hover="(i) => (suggestIndex = i)"
+        />
+      </div>
+    </div>
+    <button
+      v-if="editing"
+      type="button"
+      :class="cls.e('fx-btn')"
+      title="提交（Enter）"
+      @mousedown.prevent
+      @click="commitEdit"
+    >
+      ✓
+    </button>
+    <button
+      v-if="editing"
+      type="button"
+      :class="cls.e('fx-btn')"
+      title="取消（Esc）"
+      @mousedown.prevent
+      @click="cancelEdit"
+    >
+      ✗
+    </button>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { message } from '@veltra/desktop'
+import {
+  formatAddress,
+  formatRange,
+  parseRange,
+  type CellAddress,
+  type CellRange
+} from '@veltra/sheet-core/core/address'
+import type { SelectionState } from '@veltra/sheet-core/core/selection'
+import type { Sheet } from '@veltra/sheet-core/core/sheet'
+import { bem } from '@veltra/utils'
+import {
+  computed,
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  shallowRef,
+  useTemplateRef,
+  watch
+} from 'vue'
+
+import type { SheetContext } from '../tools/context'
+import UFormulaSuggestList from './formula-suggest-list.vue'
+import { insertRefText, isRefSelectContext } from './use-formula-ref-select'
+import {
+  applySuggest,
+  filterFormulaSuggestions,
+  getSuggestContext,
+  moveSuggestIndex,
+  type FormulaSuggestItem
+} from './use-formula-suggest'
+
+defineOptions({ name: 'UFormulaBar' })
+
+/**
+ * 公式栏（名称框 + fx 输入栏），USheet 顶部结构之一。
+ *
+ * - 名称框：显示当前选区（单格 A1 / 区域 A1:B2）；合法地址回车跳转。
+ * - fx 输入栏：活动格内容；Enter/✓ 提交、Esc/✗ 取消、失焦提交。
+ * - 函数补全：`=` 开头且光标在函数名 token 上时弹出候选（↑↓ / Tab / Enter / 点击）。
+ * - 引用选择：光标在运算符/`(`/`,` 后时，画布点选/拖选插入引用（blur 抑制防误提交）。
+ * - 网格编辑镜像：只读显示网格编辑器文本。
+ */
+const props = defineProps<{ sheet: Sheet; context: SheetContext }>()
+
+const cls = bem('sheet')
+
+const fxRef = useTemplateRef<HTMLTextAreaElement>('fxRef')
+
+const selection = shallowRef<SelectionState>({ activeCell: null, ranges: [] })
+const nameDraft = ref('')
+const nameFocused = ref(false)
+const editing = ref(false)
+let editAddr: CellAddress | null = null
+const mirroring = ref(false)
+let mirrorAddr: CellAddress | null = null
+const fxDraft = ref('')
+/** 输入面板是否因内容增高而浮出（文档流仍保持单行） */
+const fxExpanded = ref(false)
+/** textarea 光标（selectionStart）；输入/点击/方向键后同步 */
+const fxCursor = ref(0)
+
+/** 画布 pointerdown 置位：下一帧 blur 跳过提交（引用选择模式） */
+let suppressBlurCommit = false
+
+const suggestItems = shallowRef<FormulaSuggestItem[]>([])
+const suggestIndex = ref(0)
+const suggestOpen = computed(() => suggestItems.value.length > 0)
+
+const fxDisabled = computed(() => selection.value.activeCell == null)
+
+/** 编排层查询：fx 编辑中且光标处于可插入引用位置 */
+function isRefSelecting(): boolean {
+  return editing.value && !mirroring.value && isRefSelectContext(fxDraft.value, fxCursor.value)
+}
+
+/** 网格 pointerdown（capture）→ 挂起即将到来的 blur 提交 */
+function beginBlurSuppress(): void {
+  if (!isRefSelecting()) return
+  suppressBlurCommit = true
+}
+
+/** 选区拦截回调：插入 A1 / A1:B2 到光标处 */
+function handleRefSelect(range: CellRange): void {
+  if (!editing.value || mirroring.value) return
+  const rangeText = formatRange(range)
+  const el = fxRef.value
+  const selEnd = el?.selectionEnd ?? fxCursor.value
+  const result = insertRefText(fxDraft.value, fxCursor.value, rangeText, selEnd)
+  fxDraft.value = result.text
+  fxCursor.value = result.cursor
+  closeSuggest()
+  void nextTick(() => {
+    const input = fxRef.value
+    if (!input) return
+    input.focus()
+    input.setSelectionRange(result.cursor, result.cursor)
+    autosizeFx()
+  })
+}
+
+// ─── 显示文本 ──────────────────────────────────────────────
+
+function nameText(state: SelectionState): string {
+  const range = state.ranges[0]
+  if (range) return formatRange(range)
+  return state.activeCell ? formatAddress(state.activeCell) : ''
+}
+
+function cellText(addr: CellAddress): string {
+  const data = props.context.getCellData(addr)
+  if (data?.f != null) return `=${data.f}`
+  if (data?.v != null) return String(data.v)
+  return ''
+}
+
+function refreshName(): void {
+  nameDraft.value = nameText(selection.value)
+}
+
+function refreshFx(): void {
+  const active = selection.value.activeCell
+  fxDraft.value = active ? cellText(active) : ''
+  fxCursor.value = fxDraft.value.length
+  closeSuggest()
+  scheduleAutosize()
+}
+
+/** 每帧合并一次的 autosizeFx（批量 cell-change 同帧 N 次 nextTick → 1 次强制布局） */
+let autosizePending = false
+function scheduleAutosize(): void {
+  if (autosizePending) return
+  autosizePending = true
+  nextTick(() => {
+    autosizePending = false
+    autosizeFx()
+  })
+}
+
+/**
+ * 按内容增高浮出面板，不超过 CSS max-height。
+ * 增高走绝对定位，公式栏文档流高度始终单行。
+ */
+function autosizeFx(): void {
+  const el = fxRef.value
+  if (!el) return
+  el.style.height = '0px'
+  const styles = getComputedStyle(el)
+  const max = Number.parseFloat(styles.maxHeight)
+  const min = Number.parseFloat(styles.minHeight)
+  const content = el.scrollHeight
+  const next = Number.isFinite(max) && max > 0 ? Math.min(content, max) : content
+  el.style.height = `${next}px`
+  fxExpanded.value = Number.isFinite(min) ? next > min + 1 : next > 1
+}
+
+function syncFxCursor(): void {
+  const el = fxRef.value
+  if (!el) return
+  fxCursor.value = el.selectionStart
+  refreshSuggest()
+}
+
+function handleFxInput(): void {
+  syncFxCursor()
+  autosizeFx()
+}
+
+// ─── 函数补全 ──────────────────────────────────────────────
+
+function closeSuggest(): void {
+  suggestItems.value = []
+  suggestIndex.value = 0
+}
+
+function refreshSuggest(): void {
+  if (!editing.value || mirroring.value) {
+    closeSuggest()
+    return
+  }
+  const ctx = getSuggestContext(fxDraft.value, fxCursor.value)
+  if (!ctx) {
+    closeSuggest()
+    return
+  }
+  const items = filterFormulaSuggestions(ctx.prefix)
+  suggestItems.value = items
+  if (suggestIndex.value >= items.length) suggestIndex.value = 0
+}
+
+function confirmSuggest(item?: FormulaSuggestItem): void {
+  const pick = item ?? suggestItems.value[suggestIndex.value]
+  if (!pick) return
+  const ctx = getSuggestContext(fxDraft.value, fxCursor.value)
+  if (!ctx) return
+  const result = applySuggest(fxDraft.value, ctx.start, ctx.end, pick.name)
+  fxDraft.value = result.text
+  fxCursor.value = result.cursor
+  closeSuggest()
+  void nextTick(() => {
+    const el = fxRef.value
+    if (!el) return
+    el.focus()
+    el.setSelectionRange(result.cursor, result.cursor)
+    autosizeFx()
+    // 替换为 NAME() 后通常进入引用选择上下文，不再弹补全
+    refreshSuggest()
+  })
+}
+
+// ─── 名称框 ────────────────────────────────────────────────
+
+function handleNameKeydown(event: KeyboardEvent): void {
+  if (event.key === 'Enter') {
+    event.preventDefault()
+    commitName()
+  } else if (event.key === 'Escape') {
+    event.preventDefault()
+    refreshName()
+  }
+}
+
+function handleNameBlur(): void {
+  nameFocused.value = false
+  refreshName()
+}
+
+function commitName(): void {
+  const range = parseRange(nameDraft.value)
+  if (!range) {
+    message.warn('无效的单元格地址')
+    refreshName()
+    return
+  }
+  if (range.start.row === range.end.row && range.start.col === range.end.col) {
+    props.context.selectCell(range.start)
+  } else {
+    props.context.selectRange(range)
+  }
+  refreshName()
+}
+
+// ─── fx 输入栏 ─────────────────────────────────────────────
+
+function handleFxFocus(): void {
+  if (fxDisabled.value) return
+  mirroring.value = false
+  mirrorAddr = null
+  editing.value = true
+  editAddr = selection.value.activeCell
+  syncFxCursor()
+}
+
+/**
+ * 失焦提交；引用选择期间（画布 pointerdown 已挂起）跳过。
+ * ✓/✗ / 候选列表用 mousedown.prevent 拦截失焦。
+ */
+function handleFxBlur(): void {
+  if (!editing.value) return
+  if (suppressBlurCommit) {
+    suppressBlurCommit = false
+    return
+  }
+  commitEdit()
+}
+
+function handleFxKeydown(event: KeyboardEvent): void {
+  if (suggestOpen.value) {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault()
+      suggestIndex.value = moveSuggestIndex(suggestIndex.value, suggestItems.value.length, 1)
+      return
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      suggestIndex.value = moveSuggestIndex(suggestIndex.value, suggestItems.value.length, -1)
+      return
+    }
+    if (event.key === 'Enter' || event.key === 'Tab') {
+      event.preventDefault()
+      confirmSuggest()
+      return
+    }
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      closeSuggest()
+      return
+    }
+  }
+
+  if (event.key === 'Enter' && !event.shiftKey) {
+    event.preventDefault()
+    commitEdit()
+  } else if (event.key === 'Escape') {
+    event.preventDefault()
+    cancelEdit()
+  }
+}
+
+function commitEdit(): void {
+  if (!editing.value) return
+  const addr = editAddr
+  editing.value = false
+  editAddr = null
+  suppressBlurCommit = false
+  closeSuggest()
+  if (addr) props.context.setCellValue(addr, fxDraft.value)
+  refreshFx()
+}
+
+function cancelEdit(): void {
+  if (!editing.value) return
+  editing.value = false
+  editAddr = null
+  suppressBlurCommit = false
+  closeSuggest()
+  refreshFx()
+}
+
+// ─── 双向同步 ──────────────────────────────────────────────
+
+function handleSelectionChange(state: SelectionState): void {
+  selection.value = state
+  if (!nameFocused.value) refreshName()
+  if (editing.value) return
+  mirroring.value = false
+  mirrorAddr = null
+  refreshFx()
+}
+
+function handleCellChange({ addr }: { addr: CellAddress }): void {
+  if (editing.value) return
+  if (mirroring.value) {
+    if (mirrorAddr && addr.row === mirrorAddr.row && addr.col === mirrorAddr.col) {
+      mirroring.value = false
+      mirrorAddr = null
+      refreshFx()
+    }
+    return
+  }
+  // 公式栏只显示活动格：非活动格变更（批量写入的绝大多数补丁）直接忽略，
+  // 避免每个 cell-change 都 refreshFx + nextTick(autosizeFx) 强制同步布局（#5）
+  const active = selection.value.activeCell
+  if (!active || addr.row !== active.row || addr.col !== active.col) return
+  refreshFx()
+}
+
+function mirrorGridEdit(addr: CellAddress): void {
+  if (editing.value || fxDisabled.value) return
+  mirroring.value = true
+  mirrorAddr = addr
+  fxDraft.value = cellText(addr)
+  closeSuggest()
+}
+
+function exitMirror(addr: CellAddress): void {
+  if (!mirroring.value) return
+  if (mirrorAddr && addr.row === mirrorAddr.row && addr.col === mirrorAddr.col) {
+    mirroring.value = false
+    mirrorAddr = null
+    refreshFx()
+  }
+}
+
+defineExpose({ mirrorGridEdit, exitMirror, isRefSelecting, beginBlurSuppress, handleRefSelect })
+
+// ─── 生命周期 ──────────────────────────────────────────────
+
+let dispose: (() => void)[] = []
+function bindSheet(sheet: Sheet): void {
+  for (const off of dispose) off()
+  dispose = [
+    sheet.on('selection-change', handleSelectionChange),
+    sheet.on('cell-change', handleCellChange)
+  ]
+}
+
+watch(
+  () => props.sheet,
+  (sheet, prev) => {
+    if (sheet === prev) return
+    editing.value = false
+    editAddr = null
+    mirroring.value = false
+    mirrorAddr = null
+    suppressBlurCommit = false
+    closeSuggest()
+    bindSheet(sheet)
+    selection.value = sheet.getSelection()
+    refreshName()
+    refreshFx()
+  }
+)
+
+onMounted(() => {
+  bindSheet(props.sheet)
+  selection.value = props.sheet.getSelection()
+  refreshName()
+  refreshFx()
+})
+
+onBeforeUnmount(() => {
+  for (const off of dispose) off()
+  dispose = []
+})
+</script>

package/src/vue/formula-suggest-list.vue

@@ -0,0 +1,64 @@
+<template>
+  <div v-if="items.length > 0" :class="cls.e('fx-suggest')" role="listbox" @mousedown.prevent>
+    <!-- 滚动用 desktop UScroll（自定义滚动条；原生 overflow 滚动条在浮层里常看不见） -->
+    <u-scroll :height="scrollHeight" :class="cls.e('fx-suggest-scroll')">
+      <ul :class="cls.e('fx-suggest-list')">
+        <li
+          v-for="(item, index) in items"
+          :key="item.name"
+          :ref="(el) => setItemRef(index, el)"
+          :class="[cls.e('fx-suggest-item'), bem.is('active', index === activeIndex)]"
+          role="option"
+          :aria-selected="index === activeIndex"
+          @mousedown.prevent="emit('select', item)"
+          @mouseenter="emit('hover', index)"
+        >
+          <span :class="cls.e('fx-suggest-sig')">{{ item.signature }}</span>
+          <span v-if="item.description" :class="cls.e('fx-suggest-desc')">{{
+            item.description
+          }}</span>
+        </li>
+      </ul>
+    </u-scroll>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { UScroll } from '@veltra/desktop'
+import { bem } from '@veltra/utils'
+import { computed, nextTick, watch } from 'vue'
+
+import type { FormulaSuggestItem } from './use-formula-suggest'
+
+defineOptions({ name: 'UFormulaSuggestList' })
+
+const props = defineProps<{ items: FormulaSuggestItem[]; activeIndex: number }>()
+
+const emit = defineEmits<{ select: [item: FormulaSuggestItem]; hover: [index: number] }>()
+
+const cls = bem('sheet')
+// bem.is 挂在工厂函数上，与 cls.e 分开用
+
+/** 候选列表最大可视高度；内容更短时收缩，避免空前缀少量项时大片留白 */
+const SUGGEST_MAX_HEIGHT = 240
+/** 单项约高（含 padding + 签名/描述两行）；用于估算 UScroll height */
+const SUGGEST_ITEM_HEIGHT = 48
+
+const scrollHeight = computed(() =>
+  Math.min(Math.max(props.items.length, 1) * SUGGEST_ITEM_HEIGHT, SUGGEST_MAX_HEIGHT)
+)
+
+const itemEls: (HTMLElement | null)[] = []
+
+function setItemRef(index: number, el: unknown): void {
+  itemEls[index] = el instanceof HTMLElement ? el : null
+}
+
+watch(
+  () => [props.activeIndex, props.items] as const,
+  async ([index]) => {
+    await nextTick()
+    itemEls[index]?.scrollIntoView({ block: 'nearest' })
+  }
+)
+</script>

package/src/vue/import-file.ts

@@ -0,0 +1,173 @@
+import { message, messageConfirm } from '@veltra/desktop'
+import {
+  importCsv,
+  importXlsx,
+  replaceWorkbookWithSnapshots
+} from '@veltra/sheet-core/core/io/import'
+import type { Sheet, SheetSnapshot } from '@veltra/sheet-core/core/sheet'
+import type { Workbook } from '@veltra/sheet-core/core/workbook'
+import { nextFrame } from '@veltra/utils'
+import type { Ref } from 'vue'
+
+import type { ImportWorkerResponse } from './popups/import.worker'
+
+/** 导入文件 accept（工具栏直接选文件） */
+export const IMPORT_FILE_ACCEPT = '.xlsx,.csv'
+
+/** 导入所需上下文（vue 层编排；tools 层不 import vue） */
+export interface ImportFileOptions {
+  workbook: Workbook
+  activeSheet: Sheet
+  /** xlsx worker 解析期 → grid 遮罩 */
+  parsing?: Ref<boolean>
+  /** worker 分片构建进度 */
+  parseProgress?: Ref<{ done: number; total: number }>
+  /** csv 导入完成（可能扩张尺寸，宿主需重建网格） */
+  onCsvImported?: () => void
+  /** xlsx 已替换工作簿（宿主需同步 tabs / 重绑 / 重建） */
+  onWorkbookReplaced?: () => void
+}
+
+type ParsedXlsx = { sheets: { name: string; snapshot: SheetSnapshot }[]; activeIndex: number }
+
+/**
+ * xlsx 解析（worker 优先）：importXlsx 是同步重活，主线程直接跑会冻结 UI。
+ * worker 返回纯数据快照；不可用时回退主线程解析。
+ */
+async function parseXlsxAsync(
+  buffer: ArrayBuffer,
+  parseProgress?: Ref<{ done: number; total: number }>
+): Promise<ParsedXlsx> {
+  let worker: Worker | undefined
+  try {
+    // new URL 模式：dev（vite）与 build（rolldown）都支持把 worker 提为独立 chunk
+    const url = import.meta.env?.DEV
+      ? new URL('./popups/import.worker.ts', import.meta.url)
+      : new URL('./popups/import.worker.js', import.meta.url)
+    worker = new Worker(url, { type: 'module' })
+  } catch {
+    return toSnapshotArray(await importXlsx(new Uint8Array(buffer)))
+  }
+  return await new Promise<ParsedXlsx>((resolve, reject) => {
+    let settled = false
+    const fallback = (): void => {
+      if (settled) return
+      settled = true
+      worker!.terminate()
+      void importXlsx(new Uint8Array(buffer))
+        .then((wb) => resolve(toSnapshotArray(wb)))
+        .catch((err: unknown) => reject(err))
+    }
+    worker!.onmessage = (e: MessageEvent<ImportWorkerResponse>) => {
+      const data = e.data
+      if (data.type === 'progress') {
+        if (parseProgress) parseProgress.value = { done: data.done, total: data.total }
+        return
+      }
+      if (settled) return
+      settled = true
+      if (!data.ok) {
+        worker!.terminate()
+        reject(new Error(data.error ?? 'worker 解析失败'))
+        return
+      }
+      worker!.terminate()
+      resolve({ sheets: data.sheets ?? [], activeIndex: data.activeIndex ?? 0 })
+    }
+    worker!.onerror = () => fallback()
+    // transfer 一份拷贝给 worker；主线程保留原 buffer 供降级解析
+    const transfer = buffer.slice(0)
+    worker!.postMessage({ buffer: transfer }, [transfer])
+  })
+}
+
+function toSnapshotArray(wb: Workbook): ParsedXlsx {
+  return {
+    sheets: wb.getSheets().map((s) => ({ name: s.name, snapshot: s.snapshot() })),
+    activeIndex: wb.activeSheetIndex
+  }
+}
+
+/**
+ * 从本地 File 导入：
+ * - .csv → importCsv 写入当前活动表
+ * - .xlsx → 解析后经 messageConfirm 确认再 replaceWorkbookWithSnapshots
+ */
+export function importFromFile(file: File, options: ImportFileOptions): void {
+  const { workbook, activeSheet, parsing, parseProgress, onCsvImported, onWorkbookReplaced } =
+    options
+
+  if (file.name.toLowerCase().endsWith('.csv')) {
+    void file.text().then((text) => {
+      importCsv(text, activeSheet)
+      onCsvImported?.()
+      message.success(`已从 ${file.name} 导入到工作表「${activeSheet.name}」`)
+    })
+    return
+  }
+
+  void file.arrayBuffer().then((buffer) => {
+    if (parsing) parsing.value = true
+    if (parseProgress) parseProgress.value = { done: 0, total: 0 }
+    void parseXlsxAsync(buffer, parseProgress)
+      .then((imported) => {
+        if (parsing) parsing.value = false
+        messageConfirm.danger(
+          `导入将替换当前工作簿（共 ${imported.sheets.length} 个工作表），确定吗？`,
+          {
+            confirmButtonText: '导入',
+            onClosed: (action) => {
+              if (action !== 'confirm') return
+              const loading = message({ message: '正在导入…', duration: 0 })
+              try {
+                replaceWorkbookWithSnapshots(workbook, imported.sheets, imported.activeIndex)
+                onWorkbookReplaced?.()
+                nextFrame(() => {
+                  message.success('导入完成')
+                  loading.close()
+                })
+              } catch (err) {
+                console.error('[sheet] 导入失败：', err)
+                message.error(`导入失败：${err instanceof Error ? err.message : String(err)}`)
+                loading.close()
+              }
+            }
+          }
+        )
+      })
+      .catch((err: unknown) => {
+        if (parsing) parsing.value = false
+        message.error(`文件解析失败：${err instanceof Error ? err.message : String(err)}`)
+      })
+  })
+}
+
+/**
+ * 拉起系统文件选择框（工具栏导入用；不用 UFilePicker——无编程式打开 API）。
+ * 选中文件后走 importFromFile。
+ */
+export function pickAndImportFile(options: ImportFileOptions): void {
+  const input = document.createElement('input')
+  input.type = 'file'
+  input.accept = IMPORT_FILE_ACCEPT
+  input.hidden = true
+  const cleanup = (): void => {
+    input.remove()
+  }
+  input.addEventListener('change', () => {
+    const file = input.files?.[0]
+    cleanup()
+    if (file) importFromFile(file, options)
+  })
+  window.addEventListener(
+    'focus',
+    () => {
+      setTimeout(() => {
+        if (document.body.contains(input) && !input.files?.length) cleanup()
+      }, 300)
+    },
+    { once: true }
+  )
+  document.body.appendChild(input)
+  input.click()
+}