@veltra/sheet 2.1.1 → 2.3.0

package/dist/tools/builtin.js

@@ -17,15 +17,15 @@ function selectionRange(ctx) {
 function toggleFontFlag(ctx, field) {
 	const sel = selectionRange(ctx);
 	if (!sel) return;
-	const on = ctx.getCellStyle(sel.activeCell)?.font?.[field] === true;
-	ctx.setCellStyle(sel.range, { font: { [field]: on ? null : true } });
+	const on = ctx.getEffectiveStyle(sel.activeCell)?.font?.[field] === true;
+	ctx.applyStyle(sel.range, { font: { [field]: on ? null : true } });
 }
 /** 对齐 toggle：点当前档 = 清除，点其它档 = 切换 */
 function toggleAlign(ctx, axis, value) {
 	const sel = selectionRange(ctx);
 	if (!sel) return;
-	if (ctx.getCellStyle(sel.activeCell)?.align?.[axis] === value) ctx.setCellStyle(sel.range, { align: { [axis]: null } });
-	else ctx.setCellStyle(sel.range, { align: { [axis]: value } });
+	if (ctx.getEffectiveStyle(sel.activeCell)?.align?.[axis] === value) ctx.applyStyle(sel.range, { align: { [axis]: null } });
+	else ctx.applyStyle(sel.range, { align: { [axis]: value } });
 }
 /**
 * 内置工具（dogfood 扩展机制）。
@@ -129,7 +129,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.font?.bold === true;
+		return !!active && ctx.getEffectiveStyle(active)?.font?.bold === true;
 	},
 	onClick: (ctx) => toggleFontFlag(ctx, "bold")
 });
@@ -143,7 +143,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.font?.italic === true;
+		return !!active && ctx.getEffectiveStyle(active)?.font?.italic === true;
 	},
 	onClick: (ctx) => toggleFontFlag(ctx, "italic")
 });
@@ -157,7 +157,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.font?.underline === true;
+		return !!active && ctx.getEffectiveStyle(active)?.font?.underline === true;
 	},
 	onClick: (ctx) => toggleFontFlag(ctx, "underline")
 });
@@ -171,7 +171,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.font?.strikethrough === true;
+		return !!active && ctx.getEffectiveStyle(active)?.font?.strikethrough === true;
 	},
 	onClick: (ctx) => toggleFontFlag(ctx, "strikethrough")
 });
@@ -207,7 +207,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.horizontal === "left";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.horizontal === "left";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "horizontal", "left")
 });
@@ -221,7 +221,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.horizontal === "center";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.horizontal === "center";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "horizontal", "center")
 });
@@ -235,7 +235,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.horizontal === "right";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.horizontal === "right";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "horizontal", "right")
 });
@@ -249,7 +249,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.vertical === "top";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.vertical === "top";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "vertical", "top")
 });
@@ -263,7 +263,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.vertical === "middle";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.vertical === "middle";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "vertical", "middle")
 });
@@ -277,7 +277,7 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.vertical === "bottom";
+		return !!active && ctx.getEffectiveStyle(active)?.align?.vertical === "bottom";
 	},
 	onClick: (ctx) => toggleAlign(ctx, "vertical", "bottom")
 });
@@ -291,13 +291,13 @@ registerTool({
 	disabled: (ctx) => !ctx.getSelection().activeCell,
 	active: (ctx) => {
 		const active = ctx.getSelection().activeCell;
-		return !!active && ctx.getCellStyle(active)?.align?.wrap === true;
+		return !!active && ctx.getEffectiveStyle(active)?.align?.wrap === true;
 	},
 	onClick: (ctx) => {
 		const sel = selectionRange(ctx);
 		if (!sel) return;
-		const on = ctx.getCellStyle(sel.activeCell)?.align?.wrap === true;
-		ctx.setCellStyle(sel.range, { align: { wrap: on ? null : true } });
+		const on = ctx.getEffectiveStyle(sel.activeCell)?.align?.wrap === true;
+		ctx.applyStyle(sel.range, { align: { wrap: on ? null : true } });
 	}
 });
 registerTool({

package/dist/tools/context.d.ts

@@ -2,13 +2,13 @@ import { CellAddress, CellRange } from "@veltra/sheet-core/core/address";
 import { CellStyle, CellStylePatch } from "@veltra/sheet-core/core/style/types";
 import { CellData, CellValue } from "@veltra/sheet-core/core/cell-store";
 import { Workbook } from "@veltra/sheet-core/core/workbook";
+import { FrozenState, Sheet } from "@veltra/sheet-core/core/sheet";
 import { HistoryState } from "@veltra/sheet-core/core/command/history";
 import { ImageUpdateFields } from "@veltra/sheet-core/core/command/image";
 import { SetCellValueItem } from "@veltra/sheet-core/core/command/set-cell-value";
 import { ImageInput, SheetImage } from "@veltra/sheet-core/core/image";
 import { CellInfo } from "@veltra/sheet-core/core/merge-manager";
 import { SelectionState } from "@veltra/sheet-core/core/selection";
-import { FrozenState, Sheet } from "@veltra/sheet-core/core/sheet";
 //#region src/tools/context.d.ts
 /**
  * SheetContext：工具的唯一操作门面。
@@ -37,12 +37,33 @@ interface SheetContext {
   getDisplayValue(addr: CellAddress): CellValue | undefined;
   /** 合并语义下的单元格信息（普通格 / 合并锚点 / 被覆盖格） */
   getCellInfo(addr: CellAddress): CellInfo;
-  /** 设置区域样式（部分合并语义，见 CellStylePatch）；空样式 = 删除 s 字段 */
+  /**
+   * 按选区形态写样式（Excel 语义）：
+   * 整行选区 → rowStyles；整列选区 → colStyles；其余 → 逐格。
+   * 判定依赖 createSheetContext 注入的渲染尺寸；未注入时一律走 setCellStyle。
+   */
+  applyStyle(range: CellRange, partial: CellStylePatch): void;
+  /**
+   * 选区样式目标（与 applyStyle 同一判定）；未注入渲染尺寸时恒为 'cell'。
+   */
+  resolveStyleTarget(range: CellRange): 'row' | 'col' | 'cell';
+  /**
+   * 按选区形态清除样式：整行/整列清对应默认样式；其余清单元格 s。
+   * 未注入渲染尺寸时一律走 clearCellStyle。
+   */
+  clearStyle(range: CellRange): void;
+  /** 设置区域单元格样式（部分合并语义，见 CellStylePatch）；空样式 = 删除 s 字段 */
   setCellStyle(range: CellRange, partial: CellStylePatch): void;
-  /** 清除区域样式（保留值 / 公式） */
+  /** 清除区域单元格样式（保留值 / 公式） */
   clearCellStyle(range: CellRange): void;
-  /** 读取单元格样式（原始存储语义：被覆盖格 → undefined） */
+  /** 设置行默认样式（部分合并，进 undo） */
+  setRowStyle(row: number, partial: CellStylePatch): void;
+  /** 设置列默认样式（部分合并，进 undo） */
+  setColStyle(col: number, partial: CellStylePatch): void;
+  /** 读取单元格样式（原始存储语义：被覆盖格 → undefined；不含行列默认） */
   getCellStyle(addr: CellAddress): CellStyle | undefined;
+  /** 有效样式：列 → 行 → 格字段级叠加（空格可继承行列默认） */
+  getEffectiveStyle(addr: CellAddress): CellStyle | undefined;
   setCellValue(addr: CellAddress, value: CellValue): void;
   setCellFormula(addr: CellAddress, formula: string): void;
   /** 批量写入（一次调用 = 一个 undo 单元） */
@@ -86,6 +107,17 @@ interface SheetContext {
     id?: string;
   }) => void): () => void;
 }
+/** createSheetContext 可选配置 */
+interface SheetContextOptions {
+  /**
+   * 当前渲染网格尺寸（与 SheetGrid / resolveRenderSize 一致）。
+   * applyStyle / clearStyle 用其判定整行/整列；缺省时不走行列默认样式。
+   */
+  resolveGridSize?: () => {
+    rows: number;
+    cols: number;
+  };
+}
 /**
  * 创建工具上下文。
  * @param resolveSheet 活动 sheet 解析器（USheet 传 `() => activeSheet`，
@@ -94,7 +126,8 @@ interface SheetContext {
  *   支持传解析函数 `() => Workbook`——USheet 在 props.workbook 动态切换后，
  *   上下文始终解析到**当前**工作簿（#2：旧实现取构造时值快照，宿主切换
  *   workbook prop 后导出工具仍导出旧工作簿）
+ * @param options.resolveGridSize 渲染尺寸解析器（整行/整列样式路由）
  */
-declare function createSheetContext(resolveSheet: Sheet | (() => Sheet), workbook?: Workbook | (() => Workbook)): SheetContext;
+declare function createSheetContext(resolveSheet: Sheet | (() => Sheet), workbook?: Workbook | (() => Workbook), options?: SheetContextOptions): SheetContext;
 //#endregion
-export { SheetContext, createSheetContext };
+export { SheetContext, SheetContextOptions, createSheetContext };

package/dist/tools/context.js

@@ -1,3 +1,4 @@
+import { axisStyleItemsForRange, classifySelectionStyleTarget } from "./apply-style.js";
 //#region src/tools/context.ts
 /**
 * 创建工具上下文。
@@ -7,10 +8,16 @@
 *   支持传解析函数 `() => Workbook`——USheet 在 props.workbook 动态切换后，
 *   上下文始终解析到**当前**工作簿（#2：旧实现取构造时值快照，宿主切换
 *   workbook prop 后导出工具仍导出旧工作簿）
+* @param options.resolveGridSize 渲染尺寸解析器（整行/整列样式路由）
 */
-function createSheetContext(resolveSheet, workbook) {
+function createSheetContext(resolveSheet, workbook, options) {
 	const sheet = typeof resolveSheet === "function" ? resolveSheet : () => resolveSheet;
 	const resolveWorkbook = typeof workbook === "function" ? workbook : workbook != null ? () => workbook : void 0;
+	const resolveGridSize = options?.resolveGridSize;
+	const resolveTarget = (range) => {
+		const size = resolveGridSize?.();
+		return size ? classifySelectionStyleTarget(range, size.rows, size.cols) : "cell";
+	};
 	return {
 		get workbook() {
 			return resolveWorkbook?.();
@@ -29,9 +36,39 @@ function createSheetContext(resolveSheet, workbook) {
 		setCells: (items) => sheet().setCells(items),
 		mergeCells: (range) => sheet().mergeCells(range),
 		unmergeCells: (range) => sheet().unmergeCells(range),
+		applyStyle: (range, partial) => {
+			const target = resolveTarget(range);
+			if (target === "row" || target === "col") {
+				const items = axisStyleItemsForRange(range, target, { partial });
+				if (items.length === 0) return;
+				sheet().executeCommand("sheet.command.set-axis-style", {
+					axis: target,
+					items
+				});
+				return;
+			}
+			sheet().setCellStyle(range, partial);
+		},
+		resolveStyleTarget: (range) => resolveTarget(range),
+		clearStyle: (range) => {
+			const target = resolveTarget(range);
+			if (target === "row" || target === "col") {
+				const items = axisStyleItemsForRange(range, target, { clear: true });
+				if (items.length === 0) return;
+				sheet().executeCommand("sheet.command.set-axis-style", {
+					axis: target,
+					items
+				});
+				return;
+			}
+			sheet().clearCellStyle(range);
+		},
 		setCellStyle: (range, partial) => sheet().setCellStyle(range, partial),
 		clearCellStyle: (range) => sheet().clearCellStyle(range),
+		setRowStyle: (row, partial) => sheet().setRowStyle(row, partial),
+		setColStyle: (col, partial) => sheet().setColStyle(col, partial),
 		getCellStyle: (addr) => sheet().getCellStyle(addr),
+		getEffectiveStyle: (addr) => sheet().getEffectiveStyle(addr),
 		executeCommand: (commandId, params) => sheet().executeCommand(commandId, params),
 		get frozen() {
 			return sheet().frozen;

package/dist/types/index.d.ts

@@ -1,3 +1,4 @@
 import { SheetEmits, SheetExposed, SheetProps, _SheetExposed } from "./sheet.js";
-import "@veltra/sheet-core/core/image";
-export { SheetEmits, SheetExposed, SheetProps, _SheetExposed };
+import { ReportViewerExposed, ReportViewerProps, _ReportViewerExposed } from "./report-viewer.js";
+import { ReportDesignerEmits, ReportDesignerExposed, ReportDesignerProps, _ReportDesignerExposed } from "./report-designer.js";
+export { ReportDesignerEmits, ReportDesignerExposed, ReportDesignerProps, ReportViewerExposed, ReportViewerProps, SheetEmits, SheetExposed, SheetProps, _ReportDesignerExposed, _ReportViewerExposed, _SheetExposed };

package/dist/types/report-designer.d.ts

@@ -0,0 +1,38 @@
+import { DataConnection, DataConnector } from "../report/connector.js";
+import { ReportTemplate } from "../report/template.js";
+import "../report/index.js";
+import { DeconstructValue } from "@veltra/utils";
+import { Workbook } from "@veltra/sheet-core/core/workbook";
+//#region src/types/report-designer.d.ts
+/** 报表设计器组件属性（ADR-0003 决策 2） */
+interface ReportDesignerProps {
+  /** 数据连接器（如 `createHttpConnector({ endpoint })`）：数据中枢的测试连接 / 字段解析 / 记录预览均经它 */
+  connector: DataConnector;
+  /**
+   * 数据连接列表（`v-model:connections`）：纯序列化对象，仅驻留内存；
+   * 凭据的持久化与安全存储完全由宿主掌控（ADR-0003 决策 4）
+   */
+  connections?: DataConnection[];
+  /**
+   * 载入既有 Report Template 继续设计：恢复网格绑定与设计态数据集；
+   * 内嵌连接按 id 合并进 `v-model:connections`（仅缺省时追加，宿主列表是单一事实源）
+   */
+  template?: ReportTemplate;
+  /** 承载设计态的工作簿（USheet 先例：缺省内部自建单 sheet 工作簿） */
+  workbook?: Workbook;
+}
+/** 报表设计器组件定义的事件 */
+interface ReportDesignerEmits {
+  (e: 'update:connections', value: DataConnection[]): void;
+  /** 数据集增删改或数据中枢关闭：宿主可立即持久化工作区 */
+  (e: 'datasets-change'): void;
+}
+/** 在组件内部引用 */
+interface _ReportDesignerExposed {
+  /** 取回含 meta 绑定与内嵌数据集定义的可序列化 Report Template */
+  getTemplate: () => ReportTemplate;
+}
+/** 报表设计器组件暴露的方法 */
+type ReportDesignerExposed = DeconstructValue<_ReportDesignerExposed>;
+//#endregion
+export { ReportDesignerEmits, ReportDesignerExposed, ReportDesignerProps, _ReportDesignerExposed };

package/dist/types/report-viewer.d.ts

@@ -0,0 +1,38 @@
+import { ReportColWidthEntry } from "../report/export-xlsx.js";
+import { DataConnector } from "../report/connector.js";
+import { ReportTemplate } from "../report/template.js";
+import "../report/index.js";
+import { DeconstructValue } from "@veltra/utils";
+import { Workbook } from "@veltra/sheet-core/core/workbook";
+//#region src/types/report-viewer.d.ts
+/** 报表查看器组件属性（ADR-0003 决策 2） */
+interface ReportViewerProps {
+  /** 数据连接器（如 `createHttpConnector({ endpoint })`） */
+  connector: DataConnector;
+  /**
+   * 自包含 Report Template（SheetSnapshot + 内嵌数据集定义，见 `ReportTemplate`）：
+   * 查看器据此提取实际绑定数据集的查询参数并集生成 Filter Bar，并经连接器取数展开渲染
+   */
+  template: ReportTemplate;
+  /** 承载填充报表的工作簿（USheet 先例：缺省内部自建单 sheet 工作簿） */
+  workbook?: Workbook;
+  /**
+   * 列宽显式覆盖（可选）：优先于模板 `colWidths` / 展开映射结果写入模型与网格。
+   * 列宽已进 `SheetSnapshot.colWidths`，通常无需再传。
+   */
+  colWidths?: ReadonlyArray<ReportColWidthEntry>;
+}
+/** 在组件内部引用 */
+interface _ReportViewerExposed {
+  /** 重新取数并展开渲染（外部状态变化后主动刷新报表） */
+  refresh: () => Promise<void>;
+  /**
+   * 导出填充报表为 XLSX（取数完成前拒绝；内部读取填充 sheet 与运行时列宽）。
+   * 不内置导出按钮，工具栏由下游决定。
+   */
+  exportXlsx: () => Promise<void>;
+}
+/** 报表查看器组件暴露的方法 */
+type ReportViewerExposed = DeconstructValue<_ReportViewerExposed>;
+//#endregion
+export { ReportViewerExposed, ReportViewerProps, _ReportViewerExposed };

package/dist/types/sheet.d.ts

@@ -1,7 +1,7 @@
 import { SheetContext } from "../tools/context.js";
 import { ComputedRef } from "vue";
 import { DeconstructValue } from "@veltra/utils";
-import { SheetGrid } from "@veltra/sheet-core/grid/sheet-grid";
+import { ResolveCellRenderer, ResolveCellStyleHook, ResolveDisplayValue, SheetGrid } from "@veltra/sheet-core/grid/sheet-grid";
 import { Workbook } from "@veltra/sheet-core/core/workbook";
 import { Sheet } from "@veltra/sheet-core/core/sheet";
 //#region src/types/sheet.d.ts
@@ -13,12 +13,32 @@ interface SheetProps {
   rows?: number;
   /** 渲染列数，默认 26（A..Z） */
   cols?: number;
+  /**
+   * 显示值覆盖（设计态 Binding Placeholder 等）：覆盖 VTable record，不写 CellData.v
+   */
+  resolveDisplayValue?: ResolveDisplayValue;
+  /**
+   * 动态单元格样式：视口渲染时叠加条件样式补丁，不写 CellData.s / StylePool
+   */
+  resolveCellStyle?: ResolveCellStyleHook;
+  /**
+   * 动态单元格渲染（ADR-0004）：视口布局时按格自定义渲染形态（VTable
+   * customLayout，布局构建用 sheet-core 导出的 CustomLayout），返回 undefined
+   * 回落默认渲染；不写模型、不进快照
+   */
+  resolveCellRenderer?: ResolveCellRenderer;
   /** 是否显示工具栏，默认 true */
   showToolbar?: boolean;
   /** 是否显示顶部公式栏（名称框 + fx 输入栏），默认 true */
   showFormulaBar?: boolean;
   /** 是否显示底部 sheet 标签栏，默认 true */
   showTabs?: boolean;
+  /** 是否显示行号列，默认 true */
+  showRowHeader?: boolean;
+  /** 是否显示列字母表头，默认 true */
+  showColHeader?: boolean;
+  /** 只读预览（关闭编辑回写、填充柄等写入口） */
+  readonly?: boolean;
 }
 interface SheetEmits {
   /** 激活 sheet 切换（点击 tab 或宿主调用 workbook.activateSheet） */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veltra/sheet",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "files": [
     "dist",
     "src"
@@ -30,14 +30,12 @@
   "peerDependencies": {
     "@cat-kit/core": ">=1.1.8",
     "@cat-kit/fe": ">=1.1.8",
-    "@veltra/desktop": "^1.5.0",
+    "@veltra/compositions": "^1.6.0",
+    "@veltra/desktop": "^1.6.0",
     "@veltra/icons": "^1.5.0",
-    "@veltra/sheet-core": "^2.1.1",
-    "@veltra/styles": "^1.5.0",
-    "@veltra/utils": "^1.5.0",
+    "@veltra/sheet-core": "^2.3.0",
+    "@veltra/styles": "^1.6.0",
+    "@veltra/utils": "^1.6.0",
     "vue": ">=3.5.41"
-  },
-  "devDependencies": {
-    "@visactor/vtable": "^1.26.6"
   }
 }

package/src/components/report/__test__/conditional-rules-helpers.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+
+import type { ConditionalRule } from '../../../report/types'
+import {
+  cloneRulesFromDraft,
+  coerceValueForOperator,
+  createDraftItem,
+  defaultRuleValue,
+  initDraftFromRules,
+  operatorsForFieldType,
+  readBetweenValue,
+  resolveEvalFieldType,
+  ruleEvalFieldOptions,
+  RULE_SCOPE_OPTIONS,
+  writeBetweenValue
+} from '../designer/conditional-rules/helpers'
+
+describe('conditional-rules helpers', () => {
+  it('按字段类型返回运算符列表', () => {
+    expect(operatorsForFieldType('number').map((o) => o.value)).toEqual([
+      'gt',
+      'gte',
+      'lt',
+      'lte',
+      'eq',
+      'between'
+    ])
+    expect(operatorsForFieldType('string').map((o) => o.value)).toEqual(['eq', 'contains'])
+  })
+
+  it('运算符切换时重置比较值', () => {
+    expect(coerceValueForOperator('between', 'number', 42)).toEqual([0, 100])
+    expect(coerceValueForOperator('contains', 'string', 42)).toBe('')
+    expect(coerceValueForOperator('gt', 'number', '12')).toBe(12)
+  })
+
+  it('between 读写辅助', () => {
+    const value = defaultRuleValue('between', 'number')
+    expect(readBetweenValue(value, 0, 'number')).toBe(0)
+    expect(readBetweenValue(value, 1, 'number')).toBe(100)
+    expect(writeBetweenValue(value, 1, 250, 'number')).toEqual([0, 250])
+  })
+
+  it('草稿与规则互转保持深拷贝', () => {
+    const rules: ConditionalRule[] = [
+      { operator: 'gt', value: 10, style: { fill: { color: '#FFCCCC' }, font: { bold: true } } }
+    ]
+    const draft = initDraftFromRules(rules, 'number')
+    expect(draft).toHaveLength(1)
+
+    const cloned = cloneRulesFromDraft(draft)
+    expect(cloned[0]).toEqual(rules[0])
+    expect(cloned[0]).not.toBe(rules[0])
+
+    draft[0]!.rule.style.fill!.color = '#000000'
+    expect(rules[0]!.style.fill!.color).toBe('#FFCCCC')
+  })
+
+  it('新建草稿项带默认样式', () => {
+    const item = createDraftItem(undefined, 'string')
+    expect(item.rule.operator).toBe('eq')
+    expect(item.rule.value).toBe('')
+    expect(item.rule.style.fill?.color).toBeTruthy()
+  })
+
+  it('求值字段与作用范围选项', () => {
+    const fields = [
+      { name: 'amount', label: '金额', type: 'number' as const },
+      { name: 'region', label: '地区', type: 'string' as const }
+    ]
+    expect(ruleEvalFieldOptions('amount', fields).map((item) => item.label)).toEqual([
+      '本格字段',
+      '地区'
+    ])
+    expect(ruleEvalFieldOptions('amount', fields).map((item) => item.value)).toEqual(['', 'region'])
+    expect(RULE_SCOPE_OPTIONS.map((item) => item.label)).toEqual(['本格', '整行'])
+    expect(resolveEvalFieldType({ operator: 'eq', value: '', style: {} }, 'amount', fields)).toBe(
+      'number'
+    )
+    expect(
+      resolveEvalFieldType(
+        { operator: 'eq', value: '', style: {}, field: 'region' },
+        'amount',
+        fields
+      )
+    ).toBe('string')
+  })
+})

package/src/components/report/__test__/field-panel-helpers.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+
+import type { DatasetCatalogItem } from '../../../report/types'
+import {
+  fieldTypeGlyph,
+  filterDatasetsByQuery,
+  formatFieldDragPayload,
+  parseFieldDragPayload
+} from '../field-panel-helpers'
+
+// ---- 内联 fixtures ----
+
+const ORDERS: DatasetCatalogItem = {
+  id: 'orders',
+  label: '销售明细',
+  fields: [
+    { name: 'customer', label: '客户', type: 'string' },
+    { name: 'amount', label: '金额', type: 'number' }
+  ]
+}
+
+const INVENTORY: DatasetCatalogItem = {
+  id: 'inventory',
+  label: '库存',
+  fields: [
+    { name: 'sku', label: 'SKU', type: 'string' },
+    { name: 'qty', label: '数量', type: 'number' }
+  ]
+}
+
+describe('field-panel helpers', () => {
+  it('fieldTypeGlyph 按字段类型返回短标识', () => {
+    expect(fieldTypeGlyph('string')).toBe('文')
+    expect(fieldTypeGlyph('number')).toBe('#')
+    expect(fieldTypeGlyph('date')).toBe('日')
+  })
+
+  it('filterDatasetsByQuery 按中文名或英文字段名过滤', () => {
+    const datasets = [ORDERS, INVENTORY]
+
+    expect(filterDatasetsByQuery(datasets, '客户')).toEqual([
+      { ...ORDERS, fields: [ORDERS.fields[0]!] }
+    ])
+
+    expect(filterDatasetsByQuery(datasets, 'qty')).toEqual([
+      { ...INVENTORY, fields: [INVENTORY.fields[1]!] }
+    ])
+
+    expect(filterDatasetsByQuery(datasets, '  ')).toEqual(datasets)
+    expect(filterDatasetsByQuery(datasets, '不存在')).toEqual([])
+  })
+
+  it('字段拖拽负载编解码往返；非法负载返回 null', () => {
+    const payload = formatFieldDragPayload('orders', 'customer')
+    expect(payload).toBe('orders:customer')
+    expect(parseFieldDragPayload(payload)).toEqual({ datasetId: 'orders', fieldName: 'customer' })
+
+    // 字段名含冒号时按首个分隔符切分
+    expect(parseFieldDragPayload('orders:a:b')).toEqual({ datasetId: 'orders', fieldName: 'a:b' })
+
+    expect(parseFieldDragPayload('')).toBeNull()
+    expect(parseFieldDragPayload(':customer')).toBeNull()
+    expect(parseFieldDragPayload('orders:')).toBeNull()
+  })
+})

package/src/components/report/__test__/float-panel-position.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+
+import type { CellOverlayRect, GridOverlayLayout } from '../designer/cell-coords'
+import { resolveBindingFloatPanelPosition } from '../designer/use-grid-overlay'
+
+function cellRect(top: number, height = 24): CellOverlayRect {
+  const bottom = top + height
+  return {
+    left: 100,
+    top,
+    right: 180,
+    bottom,
+    width: 80,
+    height,
+    centerX: 140,
+    centerY: top + height / 2
+  }
+}
+
+const layout: GridOverlayLayout = { offsetX: 0, offsetY: 77, viewW: 640, viewH: 400 }
+
+describe('resolveBindingFloatPanelPosition', () => {
+  it('顶行格空间不足时改在单元格下方', () => {
+    const rect = cellRect(101)
+    const position = resolveBindingFloatPanelPosition(rect, layout, 320, 68, 640)
+
+    expect(position.placement).toBe('below')
+    expect(position.top).toBe(rect.bottom + 8)
+  })
+
+  it('中部格优先在单元格上方', () => {
+    const rect = cellRect(200)
+    const position = resolveBindingFloatPanelPosition(rect, layout, 320, 68, 640)
+
+    expect(position.placement).toBe('above')
+    expect(position.top).toBe(rect.top - 8)
+  })
+
+  it('水平居中并限制在宿主宽度内', () => {
+    const rect = cellRect(200)
+    const position = resolveBindingFloatPanelPosition(rect, layout, 320, 68, 340)
+
+    expect(position.left).toBe(170)
+  })
+})