@veltra/sheet 2.5.6 → 2.5.7

package/dist/tools/builtin.js

@@ -1,6 +1,6 @@
 import { registerTool } from "./registry.js";
 import { FontColor } from "@veltra/icons/colorful";
-import { AlignBottom, AlignCenter, AlignTop, Bold, Border, Download, Fill, FontSize, Italic, MergeCells, PictureRounded, Rollback, Rollfront, Search, Strikethrough, Underline, UnmergeCells, Upload, VerticalAlignCenter, VerticalAlignLeft, VerticalAlignRight, Wrap } from "@veltra/icons/normal";
+import { AlignBottom, AlignCenter, AlignTop, Bold, Border, Download, Fill, FontSize, Italic, MergeCells, PictureRounded, Rollback, Rollfront, Search, Strikethrough, Underline, UnmergeCells, Upload, Variable, VerticalAlignCenter, VerticalAlignLeft, VerticalAlignRight, Wrap } from "@veltra/icons/normal";
 import { rangesEqual } from "@veltra/sheet-core/core/address";
 //#region src/tools/builtin.ts
 /** 取活动格所在首选区；无选区返回 null */
@@ -310,6 +310,16 @@ registerTool({
 	popup: "find",
 	onClick: () => {}
 });
+registerTool({
+	id: "functions",
+	title: "函数",
+	icon: Variable,
+	tooltip: "按分类浏览并插入函数",
+	group: "edit",
+	order: 1,
+	popup: "functions",
+	onClick: () => {}
+});
 registerTool({
 	id: "insert-image",
 	title: "插入图片",

package/dist/tools/context.d.ts

@@ -19,7 +19,7 @@ import { SelectionState } from "@veltra/sheet-core/core/selection";
  * - 不暴露 Sheet 实例本身，保证门面就是扩展能力的全部边界
  * - USheet 切换 sheet tab 后，同一上下文自动指向新的活动 sheet
  */
-interface SheetContext {
+export interface SheetContext {
   /** 当前活动 sheet 名 */
   readonly sheetName: string;
   /**
@@ -108,7 +108,7 @@ interface SheetContext {
   }) => void): () => void;
 }
 /** createSheetContext 可选配置 */
-interface SheetContextOptions {
+export interface SheetContextOptions {
   /**
    * 当前渲染网格尺寸（与 SheetGrid / resolveRenderSize 一致）。
    * applyStyle / clearStyle 用其判定整行/整列；缺省时不走行列默认样式。
@@ -128,6 +128,5 @@ interface SheetContextOptions {
  *   workbook prop 后导出工具仍导出旧工作簿）
  * @param options.resolveGridSize 渲染尺寸解析器（整行/整列样式路由）
  */
-declare function createSheetContext(resolveSheet: Sheet | (() => Sheet), workbook?: Workbook | (() => Workbook), options?: SheetContextOptions): SheetContext;
-//#endregion
-export { SheetContext, SheetContextOptions, createSheetContext };
+export declare function createSheetContext(resolveSheet: Sheet | (() => Sheet), workbook?: Workbook | (() => Workbook), options?: SheetContextOptions): SheetContext;
+//#endregion

package/dist/tools/export.worker.d.ts

@@ -1,16 +1,15 @@
 import { SheetSnapshot } from "@veltra/sheet-core/core/sheet";
 //#region src/tools/export.worker.d.ts
-interface ExportWorkerPayload {
+export interface ExportWorkerPayload {
   sheets: {
     name: string;
     snapshot: SheetSnapshot;
   }[];
   activeIndex: number;
 }
-interface ExportWorkerResponse {
+export interface ExportWorkerResponse {
   ok: boolean;
   buffer?: Uint8Array;
   error?: string;
 }
-//#endregion
-export { ExportWorkerPayload, ExportWorkerResponse };
+//#endregion

package/dist/tools/registry.d.ts

@@ -11,9 +11,9 @@ import { SheetContext } from "./context.js";
  *   （与 defaultCommandRegistry 同语义；每个实例的 SheetContext 各自绑定当前 sheet）
  */
 /** 弹层型工具类型：vue 层按类型渲染弹层面板（面板交互走 SheetContext 命令入口） */
-type SheetToolPopupType = 'fill-color' | 'border' | 'font-color' | 'font-size' | 'find' | 'insert-image' | 'export';
+export type SheetToolPopupType = 'fill-color' | 'border' | 'font-color' | 'font-size' | 'find' | 'functions' | 'insert-image' | 'export';
 /** 工具定义 */
-interface SheetTool {
+export interface SheetTool {
   /** 唯一 id；同 id 重复注册视为替换（保留原位置） */
   id: string;
   /** 按钮文本 */
@@ -38,11 +38,11 @@ interface SheetTool {
   onClick(ctx: SheetContext): void;
 }
 /** 分组视图（供工具栏渲染） */
-interface SheetToolGroup {
+export interface SheetToolGroup {
   name: string;
   tools: SheetTool[];
 }
-declare class ToolRegistry {
+export declare class ToolRegistry {
   private entries;
   private seq;
   private emitter;
@@ -62,10 +62,9 @@ declare class ToolRegistry {
  * 全局默认注册表（USheet 默认渲染这里的工具；内置工具也注册于此）。
  * 工具是应用级扩展：注册一次，所有 USheet 实例共享。
  */
-declare const defaultToolRegistry: ToolRegistry;
+export declare const defaultToolRegistry: ToolRegistry;
 /** 注册工具到默认注册表 */
-declare function registerTool(tool: SheetTool): void;
+export declare function registerTool(tool: SheetTool): void;
 /** 从默认注册表注销工具；id 不存在时返回 false */
-declare function unregisterTool(id: string): boolean;
-//#endregion
-export { SheetTool, SheetToolGroup, SheetToolPopupType, ToolRegistry, defaultToolRegistry, registerTool, unregisterTool };
+export declare function unregisterTool(id: string): boolean;
+//#endregion

package/dist/types/sheet.d.ts

@@ -6,7 +6,7 @@ import { Workbook } from "@veltra/sheet-core/core/workbook";
 import { Sheet } from "@veltra/sheet-core/core/sheet";
 //#region src/types/sheet.d.ts
 /** 电子表格组件属性 */
-interface SheetProps {
+export interface SheetProps {
   /** 工作簿实例（多 sheet / 跨表公式的载体）；缺省内部自建（单 sheet） */
   workbook?: Workbook;
   /** 渲染行数，默认 100 */
@@ -40,7 +40,7 @@ interface SheetProps {
   /** 只读预览（关闭编辑回写、填充柄等写入口） */
   readonly?: boolean;
 }
-interface SheetEmits {
+export interface SheetEmits {
   /** 激活 sheet 切换（点击 tab 或宿主调用 workbook.activateSheet） */
   (name: 'active-sheet-change', payload: {
     sheet: Sheet;
@@ -48,7 +48,7 @@ interface SheetEmits {
   }): void;
 }
 /** 在组件内部引用 */
-interface _SheetExposed {
+export interface _SheetExposed {
   /** 当前工作簿（props.workbook 缺省时为内部自建实例） */
   workbook: ComputedRef<Workbook>;
   /** 当前活动 sheet */
@@ -59,6 +59,5 @@ interface _SheetExposed {
   getGrid: () => SheetGrid | undefined;
 }
 /** 电子表格组件暴露的属性和方法 */
-type SheetExposed = DeconstructValue<_SheetExposed>;
-//#endregion
-export { SheetEmits, SheetExposed, SheetProps, _SheetExposed };
+export type SheetExposed = DeconstructValue<_SheetExposed>;
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltra/sheet",
-  "version": "2.5.6",
+  "version": "2.5.7",
   "homepage": "https://github.com/cabinet-fe/ultra-ui#readme",
   "bugs": {
     "url": "https://github.com/cabinet-fe/ultra-ui/issues"
@@ -36,11 +36,11 @@
   "peerDependencies": {
     "@cat-kit/core": ">=1.2.1",
     "@cat-kit/fe": ">=1.2.1",
-    "@veltra/desktop": "^1.7.10",
+    "@veltra/desktop": "^1.7.14",
     "@veltra/icons": "^1.5.0",
-    "@veltra/sheet-core": "^2.5.6",
-    "@veltra/styles": "^1.7.10",
-    "@veltra/utils": "^1.7.10",
+    "@veltra/sheet-core": "^2.5.7",
+    "@veltra/styles": "^1.7.14",
+    "@veltra/utils": "^1.7.14",
     "vue": ">=3.5.42"
   }
 }

package/src/components/sheet/__test__/formula-bar.test.ts

@@ -1,5 +1,6 @@
 import { parseRange } from '@veltra/sheet-core/core/address'
 import { Workbook } from '@veltra/sheet-core/core/workbook'
+import type { SheetGrid } from '@veltra/sheet-core/grid'
 import { afterEach, describe, expect, it } from 'vitest'
 import { createApp, h, nextTick, type App } from 'vue'
 
@@ -342,6 +343,145 @@ function setFxText(el: HTMLElement, text: string): HTMLTextAreaElement {
   return input
 }
 
+function fxButton(el: HTMLElement): HTMLButtonElement {
+  return el.querySelector<HTMLButtonElement>('button.u-sheet__fx-label')!
+}
+
+/** 函数弹框 Teleport 到 body 级 #pop-container（fx 按钮与工具栏共用同一弹框组件） */
+function functionsPanel(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-panel')
+}
+
+/** 等待弹层渲染：watch flush + Teleport 挂载 */
+async function flushPopup(): Promise<void> {
+  await nextTick()
+  await nextTick()
+}
+
+describe('USheet 公式栏：fx 函数弹框', () => {
+  it('fx 渲染为可点击 button；无活动单元格时禁用且不打开弹框', async () => {
+    const sheet = new Workbook().activeSheet
+    const { el } = mountFormulaBar(sheet)
+    await nextTick()
+
+    // 清空选区（Sheet 构造默认选 A1）：与 fx 输入框同一禁用条件
+    sheet.selection.clear()
+    await nextTick()
+    const button = fxButton(el)
+    expect(button.tagName).toBe('BUTTON')
+    expect(button.disabled).toBe(true)
+    expect(fxInput(el).disabled).toBe(true)
+
+    button.click()
+    await flushPopup()
+    expect(functionsPanel()).toBeNull()
+
+    // 有活动格 → 可点击
+    sheet.selectCell({ row: 0, col: 0 })
+    await nextTick()
+    expect(button.disabled).toBe(false)
+  })
+
+  it('点击 fx 开弹框；再点 fx / 点击弹框外 / Esc 关闭；开关不改选区、单元格内容与草稿', async () => {
+    const sheet = new Workbook().activeSheet
+    sheet.setCellValue({ row: 0, col: 0 }, 'keep')
+    const { el } = mountFormulaBar(sheet)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    // 挂起草稿编辑（focus + 输入，不提交）
+    const input = setFxText(el, 'draft')
+    const button = fxButton(el)
+    const selectionBefore = sheet.getSelection()
+
+    // 点击 fx → 弹框打开
+    button.click()
+    await flushPopup()
+    expect(functionsPanel()).not.toBeNull()
+    // 开弹框不改选区 / 不写单元格 / 草稿保留
+    expect(sheet.getSelection()).toEqual(selectionBefore)
+    expect(sheet.getCellData({ row: 2, col: 0 })).toBeUndefined()
+    expect(input.value).toBe('draft')
+
+    // 再次点击 fx → 关闭
+    button.click()
+    await flushPopup()
+    expect(functionsPanel()).toBeNull()
+    expect(input.value).toBe('draft')
+
+    // 点击弹框外 → 关闭
+    button.click()
+    await flushPopup()
+    window.dispatchEvent(new MouseEvent('click'))
+    await flushPopup()
+    expect(functionsPanel()).toBeNull()
+    expect(input.value).toBe('draft')
+
+    // Esc → 关闭；全程单元格未被写入
+    button.click()
+    await flushPopup()
+    functionsPanel()!.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    await flushPopup()
+    expect(functionsPanel()).toBeNull()
+    expect(input.value).toBe('draft')
+    expect(sheet.getCellData({ row: 2, col: 0 })).toBeUndefined()
+    expect(sheet.getCellData({ row: 0, col: 0 })).toMatchObject({ v: 'keep' })
+  })
+
+  it('选中函数：进入编辑态输出 =SUM()，光标在括号内、焦点在 fx 输入框；Enter 提交到活动格', async () => {
+    const sheet = new Workbook().activeSheet
+    const { el } = mountFormulaBar(sheet)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    fxButton(el).click()
+    await flushPopup()
+    // 默认「常用」首项 SUM
+    document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-item')!.click()
+    await nextTick()
+    await nextTick()
+
+    const input = fxInput(el)
+    expect(input.value).toBe('=SUM()')
+    expect(input.selectionStart).toBe('=SUM()'.length - 1)
+    expect(input.selectionEnd).toBe('=SUM()'.length - 1)
+    expect(document.activeElement).toBe(input)
+    expect(el.querySelector('.u-sheet__fx-suggest')).toBeNull()
+
+    // 提交 → 写入进入编辑时的目标格（当前活动格 A3）
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    await nextTick()
+    expect(sheet.getCellData({ row: 2, col: 0 })).toMatchObject({ f: 'SUM()' })
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+  })
+
+  it('工具栏「函数」按钮打开同一弹框，选中行为与 fx 按钮一致', async () => {
+    const workbook = new Workbook()
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }))
+    await nextTick()
+
+    const toolbarButton = el.querySelector<HTMLButtonElement>('[data-tool-id="functions"]')!
+    toolbarButton.click()
+    await nextTick()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await flushPopup()
+    expect(functionsPanel()).not.toBeNull()
+
+    document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-item')!.click()
+    await nextTick()
+    await nextTick()
+    // 公式栏进入编辑态（默认选区 A1）
+    const input = fxInput(el)
+    expect(input.value).toBe('=SUM()')
+    expect(input.selectionStart).toBe('=SUM()'.length - 1)
+    expect(document.activeElement).toBe(input)
+    // 弹框随选中关闭
+    expect(functionsPanel()).toBeNull()
+  })
+})
+
 function suggestList(el: HTMLElement): HTMLElement | null {
   return el.querySelector('.u-sheet__fx-suggest')
 }
@@ -501,3 +641,175 @@ describe('USheet 公式栏：函数补全与引用选择', () => {
     expect(input.style.height).toBe('')
   })
 })
+
+// ─── 目标格选区高亮保持（弹框打开与参数点选期间）──────────────
+
+/** VTable 事件名（ListTable.EVENT_TYPE 常量值；@veltra/sheet 不直接依赖 @visactor/vtable，不做运行时引入） */
+const EVT_SELECTED_CELL = 'selected_cell'
+const EVT_DRAG_SELECT_END = 'drag_select_end'
+
+type GridTable = ReturnType<SheetGrid['getTable']>
+
+/** 模拟画布点选格（VTable 时序：selectCells → SELECTED_CELL） */
+function canvasClickCell(table: GridTable, col: number, row: number): void {
+  table.selectCells([{ start: { col, row }, end: { col, row } }])
+  table.fireListeners(EVT_SELECTED_CELL, { col, row })
+}
+
+/** 画布当前选区末尾项（表格坐标；VTable 范围对象含额外内部字段，按坐标匹配） */
+function lastCanvasRange(table: GridTable) {
+  return table.getSelectedCellRanges().at(-1)
+}
+
+describe('USheet 公式栏：目标格选区高亮保持', () => {
+  it('fx 弹框打开期间点选画布：目标格高亮与名称框保持、模型选区不变，不插入引用文本', async () => {
+    const workbook = new Workbook()
+    const sheet = workbook.activeSheet
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }), exposed)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    fxButton(el).click()
+    await flushPopup()
+    expect(functionsPanel()).not.toBeNull()
+
+    // 弹框打开期间点选画布 B2（表格坐标 (2,2)）
+    const table = exposed.value!.getGrid()!.getTable()
+    canvasClickCell(table, 2, 2)
+
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(sheet.getSelection().ranges[0]).toEqual({
+      start: { row: 2, col: 0 },
+      end: { row: 2, col: 0 }
+    })
+    // 画布选区回推为目标格 A3（表格坐标 (1,3)），名称框仍显示 A3
+    expect(lastCanvasRange(table)).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+    expect(nameBox(el).value).toBe('A3')
+    // 未处于引用选择上下文：不插入引用文本
+    expect(fxInput(el).value).toBe('')
+  })
+
+  it('选中函数后点选画布参数格：只插入引用文本、目标格选区不变；提交后选区与名称框仍指向目标格', async () => {
+    const workbook = new Workbook()
+    const sheet = workbook.activeSheet
+    sheet.setCellValue({ row: 0, col: 0 }, 1)
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }), exposed)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    // fx 弹框选中 SUM → 编辑态 =SUM()（目标 = 活动格 A3）
+    fxButton(el).click()
+    await flushPopup()
+    document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-item')!.click()
+    await nextTick()
+    await nextTick()
+    const input = fxInput(el)
+    expect(input.value).toBe('=SUM()')
+
+    // 点选参数格 A1（表格坐标 (1,1)）→ 只插入引用文本（括号随 =SUM() 模板闭合），目标格选区不变
+    const table = exposed.value!.getGrid()!.getTable()
+    canvasClickCell(table, 1, 1)
+    await nextTick()
+    expect(input.value).toBe('=SUM(A1)')
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(lastCanvasRange(table)).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+    expect(nameBox(el).value).toBe('A3')
+
+    // 提交 → 写入目标格 A3，选区与名称框仍指向 A3
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    await nextTick()
+    expect(sheet.getCellData({ row: 2, col: 0 })).toMatchObject({ f: 'SUM(A1)', v: 1 })
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(nameBox(el).value).toBe('A3')
+    expect(lastCanvasRange(table)).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+  })
+
+  it('工具栏「函数」入口与 fx 一致：弹框期间点选画布保持目标格；拖选参数后提交仍指向目标格', async () => {
+    const workbook = new Workbook()
+    const sheet = workbook.activeSheet
+    sheet.setCellValue({ row: 0, col: 0 }, 1)
+    sheet.setCellValue({ row: 1, col: 0 }, 2)
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }), exposed)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    el.querySelector<HTMLButtonElement>('[data-tool-id="functions"]')!.click()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await flushPopup()
+    expect(functionsPanel()).not.toBeNull()
+
+    // 弹框打开期间点选画布 B2：目标格 A3 高亮保持、模型选区不变、不插入文本
+    const table = exposed.value!.getGrid()!.getTable()
+    canvasClickCell(table, 2, 2)
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(lastCanvasRange(table)).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+    expect(fxInput(el).value).toBe('')
+
+    // 选中 SUM → 拖选参数区域 A1:A2（SELECTED_CELL → DRAG_SELECT_END 完整时序）
+    document.querySelector<HTMLElement>('#pop-container .u-sheet__functions-item')!.click()
+    await nextTick()
+    await nextTick()
+    const input = fxInput(el)
+    expect(input.value).toBe('=SUM()')
+    table.selectCells([{ start: { col: 1, row: 1 }, end: { col: 1, row: 2 } }])
+    table.fireListeners(EVT_SELECTED_CELL, { col: 1, row: 2 })
+    table.fireListeners(EVT_DRAG_SELECT_END, {})
+    await nextTick()
+    expect(input.value).toBe('=SUM(A1:A2)')
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(nameBox(el).value).toBe('A3')
+
+    // 提交 → 选区与名称框仍指向目标格 A3
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    await nextTick()
+    expect(sheet.getCellData({ row: 2, col: 0 })).toMatchObject({ f: 'SUM(A1:A2)', v: 3 })
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(nameBox(el).value).toBe('A3')
+  })
+
+  it('公式提交后选区与名称框仍指向目标格（编辑期间名称框跳转离开时回推）', async () => {
+    const workbook = new Workbook()
+    const sheet = workbook.activeSheet
+    const exposed: { value: SheetExposed | undefined } = { value: undefined }
+    const { el } = mount(() => ({ workbook, rows: 20, cols: 8 }), exposed)
+    await nextTick()
+    sheet.selectCell({ row: 2, col: 0 })
+    await nextTick()
+
+    // 编辑目标 A3；期间经名称框跳转到 B5（模型选区离开目标格）
+    const input = setFxText(el, '=1+1')
+    typeName(el, 'B5')
+    await nextTick()
+    expect(sheet.getSelection().activeCell).toEqual({ row: 4, col: 1 })
+    expect(nameBox(el).value).toBe('B5')
+
+    // 提交 → 写入 A3，模型选区 / 名称框 / 画布高亮回推目标格
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }))
+    await nextTick()
+    expect(sheet.getCellData({ row: 2, col: 0 })).toMatchObject({ f: '1+1', v: 2 })
+    expect(sheet.getSelection().activeCell).toEqual({ row: 2, col: 0 })
+    expect(nameBox(el).value).toBe('A3')
+    expect(lastCanvasRange(exposed.value!.getGrid()!.getTable())).toMatchObject({
+      start: { col: 1, row: 3 },
+      end: { col: 1, row: 3 }
+    })
+  })
+})

package/src/components/sheet/__test__/functions-popup.test.ts

@@ -0,0 +1,182 @@
+import {
+  listFormulaFunctions,
+  registerFormulaFunction
+} from '@veltra/sheet-core/core/formula/functions'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createApp, h, nextTick, type App } from 'vue'
+
+import USheetFunctionsPopup from '../popups/functions-popup.vue'
+import { COMMON_FORMULA_NAMES, FUNCTION_POPUP_CATEGORIES } from '../use-formula-suggest'
+
+vi.mock('@veltra/desktop', async () => {
+  const { defineComponent, h } = await import('vue')
+  return {
+    UInput: defineComponent({
+      name: 'UInputStub',
+      props: ['modelValue'],
+      emits: ['update:modelValue'],
+      setup(props, { emit }) {
+        return () =>
+          h('input', {
+            class: 'search-stub',
+            value: props.modelValue as string,
+            onInput: (e: Event) => emit('update:modelValue', (e.target as HTMLInputElement).value)
+          })
+      }
+    }),
+    UScroll: defineComponent({
+      name: 'UScrollStub',
+      setup(_, { slots }) {
+        return () => h('div', { class: 'scroll-stub' }, slots.default?.())
+      }
+    })
+  }
+})
+
+const apps: App[] = []
+const containers: HTMLElement[] = []
+
+function mountPopup(onSelect?: (name: string) => void) {
+  const el = document.createElement('div')
+  document.body.appendChild(el)
+  containers.push(el)
+  const app = createApp({
+    setup() {
+      return () => h(USheetFunctionsPopup, onSelect ? { onSelect } : undefined)
+    }
+  })
+  app.mount(el)
+  apps.push(app)
+  return { el }
+}
+
+async function typeKeyword(el: HTMLElement, keyword: string): Promise<void> {
+  const input = el.querySelector<HTMLInputElement>('.search-stub')!
+  input.value = keyword
+  input.dispatchEvent(new Event('input'))
+  await Promise.resolve()
+}
+
+/** 点击左侧分类导航项（等一帧渲染） */
+async function clickCategory(el: HTMLElement, category: string): Promise<void> {
+  const item = [...el.querySelectorAll<HTMLButtonElement>('.u-sheet__functions-nav-item')].find(
+    (button) => button.textContent?.trim() === category
+  )
+  item!.click()
+  await nextTick()
+}
+
+function signatures(el: HTMLElement): (string | null)[] {
+  return [...el.querySelectorAll('.u-sheet__functions-signature')].map((node) => node.textContent)
+}
+
+function items(el: HTMLElement): HTMLElement[] {
+  return [...el.querySelectorAll<HTMLElement>('.u-sheet__functions-item')]
+}
+
+afterEach(() => {
+  apps.splice(0).forEach((app) => app.unmount())
+  containers.splice(0).forEach((el) => el.remove())
+  vi.clearAllMocks()
+})
+
+describe('USheetFunctionsPopup', () => {
+  it('分类导航渲染固定集合（顺序一致）；默认「常用」列全部常用函数', () => {
+    const { el } = mountPopup()
+    const navLabels = [...el.querySelectorAll('.u-sheet__functions-nav-item')].map(
+      (node) => node.textContent
+    )
+    expect(navLabels).toEqual([...FUNCTION_POPUP_CATEGORIES])
+
+    // 「常用」= 前端固定清单（COMMON_FORMULA_NAMES 顺序），全部内置注册 → 一一列出
+    expect(signatures(el).map((sig) => sig?.split('(')[0])).toEqual([...COMMON_FORMULA_NAMES])
+    expect(el.querySelector('.u-sheet__functions-nav-item')!.classList.contains('is-active')).toBe(
+      true
+    )
+  })
+
+  it('「全部」列出全部已注册函数；分类项只列声明该分类的函数', async () => {
+    registerFormulaFunction('MYTESTFN', {
+      meta: { params: ['value'], description: '测试未分类自定义函数' },
+      impl: () => 1
+    })
+    const { el } = mountPopup()
+
+    await clickCategory(el, '全部')
+    expect(items(el).length).toBe(listFormulaFunctions().length)
+    // 未分类函数仅出现在「全部」
+    expect(signatures(el)).toContain('MYTESTFN(value)')
+
+    await clickCategory(el, '数学')
+    const expected = listFormulaFunctions().filter((fn) => fn.category === '数学')
+    expect(items(el).length).toBe(expected.length)
+    expect(signatures(el)).toContain('SUM(number1, number2, ...)')
+    expect(signatures(el)).not.toContain('MYTESTFN(value)')
+
+    // 「常用」也不含未分类自定义函数
+    await clickCategory(el, '常用')
+    expect(signatures(el)).not.toContain('MYTESTFN(value)')
+  })
+
+  it('搜索跨分类（含未分类函数）：名称 / 描述大小写不敏感；无匹配显空态', async () => {
+    registerFormulaFunction('MYTESTFN', {
+      meta: { params: ['value'], description: '测试未分类自定义函数' },
+      impl: () => 1
+    })
+    const { el } = mountPopup()
+    await clickCategory(el, '数学')
+
+    // 在「数学」分类下搜索未分类函数名 → 仍可命中（跨分类）
+    await typeKeyword(el, 'mytest')
+    let names = signatures(el).map((sig) => sig?.split('(')[0])
+    expect(names).toEqual(['MYTESTFN'])
+
+    // 中文描述过滤（SUM：求参数之和）
+    await typeKeyword(el, '之和')
+    names = signatures(el).map((sig) => sig?.split('(')[0])
+    expect(names).toEqual(['SUM'])
+
+    // 无匹配 → 空态
+    await typeKeyword(el, '不存在的关键字zzz')
+    expect(el.querySelectorAll('.u-sheet__functions-item').length).toBe(0)
+    expect(el.querySelector('.u-sheet__functions-empty')?.textContent).toContain('无匹配函数')
+
+    // 清空关键词 → 回到当前分类（数学）
+    await typeKeyword(el, '')
+    expect(items(el).length).toBe(
+      listFormulaFunctions().filter((fn) => fn.category === '数学').length
+    )
+  })
+
+  it('点击函数项 → emit select(name)', () => {
+    const selected: string[] = []
+    const { el } = mountPopup((name) => selected.push(name))
+
+    items(el)[0]!.click()
+    expect(selected).toEqual(['SUM'])
+  })
+
+  it('键盘路径：↑↓ 移动高亮（循环），Enter 确认选中', async () => {
+    const selected: string[] = []
+    const { el } = mountPopup((name) => selected.push(name))
+    const panel = el.querySelector<HTMLElement>('.u-sheet__functions-panel')!
+
+    // 初始高亮第一项（SUM）
+    expect(items(el)[0]!.classList.contains('is-active')).toBe(true)
+
+    panel.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown' }))
+    await nextTick()
+    expect(items(el)[1]!.classList.contains('is-active')).toBe(true)
+
+    panel.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }))
+    expect(selected).toEqual(['AVERAGE'])
+
+    // ↑ 回到第一项，再 ↑ 循环到最后一项
+    panel.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowUp' }))
+    await nextTick()
+    expect(items(el)[0]!.classList.contains('is-active')).toBe(true)
+    panel.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowUp' }))
+    await nextTick()
+    expect(items(el).at(-1)!.classList.contains('is-active')).toBe(true)
+  })
+})