@veltra/sheet 2.0.1 → 2.1.1

package/dist/index.d.ts

@@ -1,29 +1,7 @@
-import { COL_KEY_BASE, CellAddress, CellRange, addressFromKey, addressesEqual, boundingBox, cellKey, colIndexToName, colNameToIndex, createRange, formatAddress, formatRange, iterateRange, parseAddress, parseRange, rangeContainsAddress, rangeContainsRange, rangeSize, rangesEqual, rangesIntersect } from "./core/address.js";
-import { CellData, CellSnapshotItem, CellStore, CellType, CellValue, cellDataEqual, inferCellType, isEmptyCellData } from "./core/cell-store.js";
-import { DEFAULT_HISTORY_CAPACITY, HistoryManager, HistoryState } from "./core/command/history.js";
-import { AstNode, AstReference, BinaryOperator, collectReferences } from "./core/formula/ast.js";
-import { DependencyGraph, FormulaDependency, FormulaNode } from "./core/formula/dependency-graph.js";
-import { CellInfo, MergeManager, MergeResult, MergedCellKind } from "./core/merge-manager.js";
-import { SelectionModel, SelectionState } from "./core/selection.js";
-import { Sheet, SheetEvents } from "./core/sheet.js";
-import { CellPatch, Command, CommandContext, CommandResult, MergePatch, Mutation, Patch, PatchDirection } from "./core/command/types.js";
-import { SetCellValueCommand, SetCellValueItem, SetCellValueParams } from "./core/command/set-cell-value.js";
-import { FillDirection, GenerateFillOptions, computeFillTargetRange, generateFill, shiftFormulaRefs } from "./core/fill.js";
-import { Workbook, WorkbookEvents } from "./core/workbook.js";
-import { CommandRegistry } from "./core/command/registry.js";
-import { SetCellFormulaCommand, SetCellFormulaParams } from "./core/command/set-cell-formula.js";
-import { MergeCellsCommand, MergeCellsParams, UnmergeCellsCommand, UnmergeCellsParams } from "./core/command/merge-cells.js";
-import { defaultCommandRegistry } from "./core/command/default-registry.js";
-import { FORMULA_ERROR_CODES, FormulaError, FormulaErrorCode, formulaError, isFormulaError, isFormulaErrorCode } from "./core/formula/errors.js";
-import { FormulaOperator, FormulaParseError, FormulaToken, tokenizeFormula } from "./core/formula/tokenizer.js";
-import { parseFormula } from "./core/formula/parser.js";
-import { EvalValue, FormulaEvalContext, ScalarValue, coerceToBoolean, coerceToNumber, coerceToText, compareScalars, evaluateAst } from "./core/formula/evaluator.js";
-import { FormulaFunction, getFormulaFunction, invokeFormulaFunction, registerFormulaFunction } from "./core/formula/functions.js";
-import { SheetGrid, SheetGridContextMenuInfo, SheetGridOptions } from "./grid/sheet-grid.js";
+import _sfc_main from "./vue/sheet.js";
 import { SheetContext, createSheetContext } from "./tools/context.js";
-import { DEFAULT_TOOL_GROUP, SheetTool, SheetToolGroup, ToolRegistry, defaultToolRegistry, registerTool, unregisterTool } from "./tools/registry.js";
+import { SheetTool, SheetToolGroup, SheetToolPopupType, defaultToolRegistry, registerTool, unregisterTool } from "./tools/registry.js";
 import { SheetEmits, SheetExposed, SheetProps, _SheetExposed } from "./types/sheet.js";
 import "./types/index.js";
-import _default from "./vue/sheet.vue.js";
-import "./vue/index.js";
-export { AstNode, AstReference, BinaryOperator, COL_KEY_BASE, CellAddress, CellData, CellInfo, CellPatch, CellRange, CellSnapshotItem, CellStore, CellType, CellValue, Command, CommandContext, CommandRegistry, CommandResult, DEFAULT_HISTORY_CAPACITY, DEFAULT_TOOL_GROUP, DependencyGraph, EvalValue, FORMULA_ERROR_CODES, FillDirection, FormulaDependency, FormulaError, FormulaErrorCode, FormulaEvalContext, FormulaFunction, FormulaNode, FormulaOperator, FormulaParseError, FormulaToken, GenerateFillOptions, HistoryManager, HistoryState, MergeCellsCommand, MergeCellsParams, MergeManager, MergePatch, MergeResult, MergedCellKind, Mutation, Patch, PatchDirection, ScalarValue, SelectionModel, SelectionState, SetCellFormulaCommand, SetCellFormulaParams, SetCellValueCommand, SetCellValueItem, SetCellValueParams, Sheet, SheetContext, SheetEmits, SheetEvents, SheetExposed, SheetGrid, SheetGridContextMenuInfo, SheetGridOptions, SheetProps, SheetTool, SheetToolGroup, ToolRegistry, _default as USheet, UnmergeCellsCommand, UnmergeCellsParams, Workbook, WorkbookEvents, _SheetExposed, addressFromKey, addressesEqual, boundingBox, cellDataEqual, cellKey, coerceToBoolean, coerceToNumber, coerceToText, colIndexToName, colNameToIndex, collectReferences, compareScalars, computeFillTargetRange, createRange, createSheetContext, defaultCommandRegistry, defaultToolRegistry, evaluateAst, formatAddress, formatRange, formulaError, generateFill, getFormulaFunction, inferCellType, invokeFormulaFunction, isEmptyCellData, isFormulaError, isFormulaErrorCode, iterateRange, parseAddress, parseFormula, parseRange, rangeContainsAddress, rangeContainsRange, rangeSize, rangesEqual, rangesIntersect, registerFormulaFunction, registerTool, shiftFormulaRefs, tokenizeFormula, unregisterTool };
+import { ALIGN_STYLE_KEYS, AstNode, AstReference, BORDER_EDGE_DEFAULTS, BORDER_SIDES, BORDER_STYLE_WIDTH, BinaryOperator, BorderEdge, BorderLineStyle, BorderPreset, BorderPresetItem, BorderSide, CellAddress, CellAlign, CellData, CellFont, CellInfo, CellPatch, CellRange, CellSnapshotItem, CellStore, CellStyle, CellStylePatch, CellType, CellValue, Command, CommandContext, CommandResult, DependencyGraph, EvalValue, FONT_STYLE_KEYS, FORMULA_ERROR_CODES, FillDirection, FindMatch, FindOptions, FormulaDependency, FormulaError, FormulaErrorCode, FormulaEvalContext, FormulaFunction, FormulaFunctionMeta, FormulaNode, FormulaOperator, FormulaParseError, FormulaToken, FrozenState, GenerateFillOptions, HistoryManager, HistoryState, HorizontalAlign, ImageInput, ImagePatch, ImageUpdateFields, InsertCellsCommand, InsertCellsParams, InsertImageCommand, InsertImageParams, MergeCellsCommand, MergeCellsParams, MergeManager, MergePatch, MergeResult, MergedCellKind, Mutation, NUMERIC_TEXT_RE, Patch, PatchDirection, RemoveImageCommand, RemoveImageParams, ScalarValue, SelectionModel, SelectionState, SetCellFormulaCommand, SetCellFormulaParams, SetCellStyleCommand, SetCellStyleItem, SetCellStyleParams, SetCellValueCommand, SetCellValueItem, SetCellValueParams, Sheet, SheetEvents, SheetGrid, SheetGridContextMenuInfo, SheetGridContextMenuKind, SheetGridOptions, SheetImage, SheetImageAnchor, SheetImageType, SheetSnapshot, SnapshotPatch, StructureChange, StructurePatch, StyleId, StylePool, UnmergeCellsCommand, UnmergeCellsParams, UpdateImageCommand, UpdateImageParams, VerticalAlign, Workbook, WorkbookEvents, boundingBox, buildBorderPresetItems, cellDataEqual, cellKey, cloneImageAnchor, cloneSheetImage, coerceToBoolean, coerceToNumber, coerceToText, colIndexToName, colNameToIndex, collectReferences, computeFillTargetRange, createImageId, createRange, defaultCommandRegistry, evaluateAst, exportSheetCsv, exportWorkbookXlsx, findAll, findNext, findNextFrom, findPrev, findPrevFrom, formatAddress, formatRange, formulaError, generateFill, importCsv, importXlsx, inferCellType, invokeFormulaFunction, isEmptyCellData, isFormulaError, isFormulaErrorCode, iterateRange, listFormulaFunctions, normalizeInputValue, parseAddress, parseFormula, parseRange, rangeContainsAddress, rangesEqual, rangesIntersect, registerFormulaFunction, replaceWorkbook, tokenizeFormula } from "@veltra/sheet-core";
+export { ALIGN_STYLE_KEYS, type AstNode, type AstReference, BORDER_EDGE_DEFAULTS, BORDER_SIDES, BORDER_STYLE_WIDTH, type BinaryOperator, type BorderEdge, type BorderLineStyle, type BorderPreset, type BorderPresetItem, type BorderSide, type CellAddress, type CellAlign, type CellData, type CellFont, type CellInfo, type CellPatch, type CellRange, type CellSnapshotItem, CellStore, type CellStyle, type CellStylePatch, type CellType, type CellValue, type Command, type CommandContext, type CommandResult, DependencyGraph, type EvalValue, FONT_STYLE_KEYS, FORMULA_ERROR_CODES, type FillDirection, type FindMatch, type FindOptions, type FormulaDependency, type FormulaError, type FormulaErrorCode, type FormulaEvalContext, type FormulaFunction, type FormulaFunctionMeta, type FormulaNode, type FormulaOperator, FormulaParseError, type FormulaToken, type FrozenState, type GenerateFillOptions, HistoryManager, type HistoryState, type HorizontalAlign, type ImageInput, type ImagePatch, type ImageUpdateFields, InsertCellsCommand, type InsertCellsParams, InsertImageCommand, type InsertImageParams, MergeCellsCommand, type MergeCellsParams, MergeManager, type MergePatch, type MergeResult, type MergedCellKind, type Mutation, NUMERIC_TEXT_RE, type Patch, type PatchDirection, RemoveImageCommand, type RemoveImageParams, type ScalarValue, SelectionModel, type SelectionState, SetCellFormulaCommand, type SetCellFormulaParams, SetCellStyleCommand, type SetCellStyleItem, type SetCellStyleParams, SetCellValueCommand, type SetCellValueItem, type SetCellValueParams, Sheet, type SheetContext, type SheetEmits, type SheetEvents, type SheetExposed, SheetGrid, type SheetGridContextMenuInfo, type SheetGridContextMenuKind, type SheetGridOptions, type SheetImage, type SheetImageAnchor, type SheetImageType, type SheetProps, type SheetSnapshot, type SheetTool, type SheetToolGroup, type SheetToolPopupType, type SnapshotPatch, type StructureChange, type StructurePatch, type StyleId, StylePool, _sfc_main as USheet, UnmergeCellsCommand, type UnmergeCellsParams, UpdateImageCommand, type UpdateImageParams, type VerticalAlign, Workbook, type WorkbookEvents, type _SheetExposed, boundingBox, buildBorderPresetItems, cellDataEqual, cellKey, cloneImageAnchor, cloneSheetImage, coerceToBoolean, coerceToNumber, coerceToText, colIndexToName, colNameToIndex, collectReferences, computeFillTargetRange, createImageId, createRange, createSheetContext, defaultCommandRegistry, defaultToolRegistry, evaluateAst, exportSheetCsv, exportWorkbookXlsx, findAll, findNext, findNextFrom, findPrev, findPrevFrom, formatAddress, formatRange, formulaError, generateFill, importCsv, importXlsx, inferCellType, invokeFormulaFunction, isEmptyCellData, isFormulaError, isFormulaErrorCode, iterateRange, listFormulaFunctions, normalizeInputValue, parseAddress, parseFormula, parseRange, rangeContainsAddress, rangesEqual, rangesIntersect, registerFormulaFunction, registerTool, replaceWorkbook, tokenizeFormula, unregisterTool };

package/dist/index.js

@@ -1,26 +1,6 @@
-import { COL_KEY_BASE, addressFromKey, addressesEqual, boundingBox, cellKey, colIndexToName, colNameToIndex, createRange, formatAddress, formatRange, iterateRange, parseAddress, parseRange, rangeContainsAddress, rangeContainsRange, rangeSize, rangesEqual, rangesIntersect } from "./core/address.js";
-import { DEFAULT_TOOL_GROUP, ToolRegistry, defaultToolRegistry, registerTool, unregisterTool } from "./tools/registry.js";
+import { defaultToolRegistry, registerTool, unregisterTool } from "./tools/registry.js";
 import "./tools/builtin.js";
-import { CellStore, cellDataEqual, inferCellType, isEmptyCellData } from "./core/cell-store.js";
-import { computeFillTargetRange, generateFill, shiftFormulaRefs } from "./core/fill.js";
-import { MergeManager } from "./core/merge-manager.js";
-import { SelectionModel } from "./core/selection.js";
-import { MergeCellsCommand, UnmergeCellsCommand } from "./core/command/merge-cells.js";
-import { CommandRegistry } from "./core/command/registry.js";
-import { SetCellFormulaCommand } from "./core/command/set-cell-formula.js";
-import { SetCellValueCommand } from "./core/command/set-cell-value.js";
-import { defaultCommandRegistry } from "./core/command/default-registry.js";
-import { DEFAULT_HISTORY_CAPACITY, HistoryManager } from "./core/command/history.js";
-import { collectReferences } from "./core/formula/ast.js";
-import { FORMULA_ERROR_CODES, formulaError, isFormulaError, isFormulaErrorCode } from "./core/formula/errors.js";
-import { coerceToBoolean, coerceToNumber, coerceToText, compareScalars, evaluateAst } from "./core/formula/evaluator.js";
-import { getFormulaFunction, invokeFormulaFunction, registerFormulaFunction } from "./core/formula/functions.js";
-import { FormulaParseError, tokenizeFormula } from "./core/formula/tokenizer.js";
-import { parseFormula } from "./core/formula/parser.js";
-import { DependencyGraph } from "./core/formula/dependency-graph.js";
-import { Sheet } from "./core/sheet.js";
-import { Workbook } from "./core/workbook.js";
-import { SheetGrid } from "./grid/sheet-grid.js";
 import { createSheetContext } from "./tools/context.js";
 import _sfc_main from "./vue/sheet.js";
-export { COL_KEY_BASE, CellStore, CommandRegistry, DEFAULT_HISTORY_CAPACITY, DEFAULT_TOOL_GROUP, DependencyGraph, FORMULA_ERROR_CODES, FormulaParseError, HistoryManager, MergeCellsCommand, MergeManager, SelectionModel, SetCellFormulaCommand, SetCellValueCommand, Sheet, SheetGrid, ToolRegistry, _sfc_main as USheet, UnmergeCellsCommand, Workbook, addressFromKey, addressesEqual, boundingBox, cellDataEqual, cellKey, coerceToBoolean, coerceToNumber, coerceToText, colIndexToName, colNameToIndex, collectReferences, compareScalars, computeFillTargetRange, createRange, createSheetContext, defaultCommandRegistry, defaultToolRegistry, evaluateAst, formatAddress, formatRange, formulaError, generateFill, getFormulaFunction, inferCellType, invokeFormulaFunction, isEmptyCellData, isFormulaError, isFormulaErrorCode, iterateRange, parseAddress, parseFormula, parseRange, rangeContainsAddress, rangeContainsRange, rangeSize, rangesEqual, rangesIntersect, registerFormulaFunction, registerTool, shiftFormulaRefs, tokenizeFormula, unregisterTool };
+import { ALIGN_STYLE_KEYS, BORDER_EDGE_DEFAULTS, BORDER_SIDES, BORDER_STYLE_WIDTH, CellStore, DependencyGraph, FONT_STYLE_KEYS, FORMULA_ERROR_CODES, FormulaParseError, HistoryManager, InsertCellsCommand, InsertImageCommand, MergeCellsCommand, MergeManager, NUMERIC_TEXT_RE, RemoveImageCommand, SelectionModel, SetCellFormulaCommand, SetCellStyleCommand, SetCellValueCommand, Sheet, SheetGrid, StylePool, UnmergeCellsCommand, UpdateImageCommand, Workbook, boundingBox, buildBorderPresetItems, cellDataEqual, cellKey, cloneImageAnchor, cloneSheetImage, coerceToBoolean, coerceToNumber, coerceToText, colIndexToName, colNameToIndex, collectReferences, computeFillTargetRange, createImageId, createRange, defaultCommandRegistry, evaluateAst, exportSheetCsv, exportWorkbookXlsx, findAll, findNext, findNextFrom, findPrev, findPrevFrom, formatAddress, formatRange, formulaError, generateFill, importCsv, importXlsx, inferCellType, invokeFormulaFunction, isEmptyCellData, isFormulaError, isFormulaErrorCode, iterateRange, listFormulaFunctions, normalizeInputValue, parseAddress, parseFormula, parseRange, rangeContainsAddress, rangesEqual, rangesIntersect, registerFormulaFunction, replaceWorkbook, tokenizeFormula } from "@veltra/sheet-core";
+export { ALIGN_STYLE_KEYS, BORDER_EDGE_DEFAULTS, BORDER_SIDES, BORDER_STYLE_WIDTH, CellStore, DependencyGraph, FONT_STYLE_KEYS, FORMULA_ERROR_CODES, FormulaParseError, HistoryManager, InsertCellsCommand, InsertImageCommand, MergeCellsCommand, MergeManager, NUMERIC_TEXT_RE, RemoveImageCommand, SelectionModel, SetCellFormulaCommand, SetCellStyleCommand, SetCellValueCommand, Sheet, SheetGrid, StylePool, _sfc_main as USheet, UnmergeCellsCommand, UpdateImageCommand, Workbook, boundingBox, buildBorderPresetItems, cellDataEqual, cellKey, cloneImageAnchor, cloneSheetImage, coerceToBoolean, coerceToNumber, coerceToText, colIndexToName, colNameToIndex, collectReferences, computeFillTargetRange, createImageId, createRange, createSheetContext, defaultCommandRegistry, defaultToolRegistry, evaluateAst, exportSheetCsv, exportWorkbookXlsx, findAll, findNext, findNextFrom, findPrev, findPrevFrom, formatAddress, formatRange, formulaError, generateFill, importCsv, importXlsx, inferCellType, invokeFormulaFunction, isEmptyCellData, isFormulaError, isFormulaErrorCode, iterateRange, listFormulaFunctions, normalizeInputValue, parseAddress, parseFormula, parseRange, rangeContainsAddress, rangesEqual, rangesIntersect, registerFormulaFunction, registerTool, replaceWorkbook, tokenizeFormula, unregisterTool };

package/dist/tools/builtin.js

@@ -1,16 +1,43 @@
-import { rangesEqual } from "../core/address.js";
 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 { rangesEqual } from "@veltra/sheet-core/core/address";
 //#region src/tools/builtin.ts
+/** 取活动格所在首选区；无选区返回 null */
+function selectionRange(ctx) {
+	const { activeCell, ranges } = ctx.getSelection();
+	const range = ranges[0];
+	if (!activeCell || !range) return null;
+	return {
+		activeCell,
+		range
+	};
+}
+/** 字体 toggle：以活动格当前值为基准，对选区统一翻转（Excel 语义） */
+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 } });
+}
+/** 对齐 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 } });
+}
 /**
-* 内置工具（dogfood 扩展机制）：undo/redo + 合并/取消合并。
+* 内置工具（dogfood 扩展机制）。
 *
+* 分组：history ｜ cell ｜ text ｜ edit ｜ insert ｜ file。
 * 与第三方工具走同一注册通道，可由宿主 unregisterTool 移除或同 id 覆盖。
-* 本模块由 tools/index.ts 引入（与 core/command 的 default-registry 同构）：
-* 经包入口导入即完成注册，无头使用 core 深导入不涉及此全局副作用。
+* 本模块由包入口引入：经包入口导入即完成注册。
 */
 registerTool({
 	id: "undo",
 	title: "撤销",
+	icon: Rollback,
 	tooltip: "撤销（Ctrl/Cmd+Z）",
 	group: "history",
 	order: 0,
@@ -22,6 +49,7 @@ registerTool({
 registerTool({
 	id: "redo",
 	title: "重做",
+	icon: Rollfront,
 	tooltip: "重做（Ctrl/Cmd+Shift+Z 或 Ctrl+Y）",
 	group: "history",
 	order: 1,
@@ -30,12 +58,35 @@ registerTool({
 		ctx.redo();
 	}
 });
+registerTool({
+	id: "border",
+	title: "边框",
+	icon: Border,
+	tooltip: "设置单元格边框",
+	group: "cell",
+	order: 0,
+	popup: "border",
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	onClick: () => {}
+});
+registerTool({
+	id: "fill-color",
+	title: "填充颜色",
+	icon: Fill,
+	tooltip: "设置单元格背景填充",
+	group: "cell",
+	order: 1,
+	popup: "fill-color",
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	onClick: () => {}
+});
 registerTool({
 	id: "merge",
 	title: "合并",
+	icon: MergeCells,
 	tooltip: "合并选中区域",
 	group: "cell",
-	order: 0,
+	order: 2,
 	disabled: (ctx) => {
 		const { activeCell, ranges } = ctx.getSelection();
 		const range = ranges[0];
@@ -53,9 +104,10 @@ registerTool({
 registerTool({
 	id: "unmerge",
 	title: "取消合并",
+	icon: UnmergeCells,
 	tooltip: "取消活动格所在合并",
 	group: "cell",
-	order: 1,
+	order: 3,
 	disabled: (ctx) => {
 		const { activeCell } = ctx.getSelection();
 		if (!activeCell) return true;
@@ -67,6 +119,225 @@ registerTool({
 		ctx.unmergeCells(ranges[0]);
 	}
 });
+registerTool({
+	id: "bold",
+	title: "加粗",
+	icon: Bold,
+	tooltip: "加粗",
+	group: "text",
+	order: 0,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.font?.bold === true;
+	},
+	onClick: (ctx) => toggleFontFlag(ctx, "bold")
+});
+registerTool({
+	id: "italic",
+	title: "斜体",
+	icon: Italic,
+	tooltip: "斜体",
+	group: "text",
+	order: 1,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.font?.italic === true;
+	},
+	onClick: (ctx) => toggleFontFlag(ctx, "italic")
+});
+registerTool({
+	id: "underline",
+	title: "下划线",
+	icon: Underline,
+	tooltip: "下划线",
+	group: "text",
+	order: 2,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.font?.underline === true;
+	},
+	onClick: (ctx) => toggleFontFlag(ctx, "underline")
+});
+registerTool({
+	id: "strikethrough",
+	title: "删除线",
+	icon: Strikethrough,
+	tooltip: "删除线",
+	group: "text",
+	order: 3,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.font?.strikethrough === true;
+	},
+	onClick: (ctx) => toggleFontFlag(ctx, "strikethrough")
+});
+registerTool({
+	id: "font-color",
+	title: "字体颜色",
+	icon: FontColor,
+	tooltip: "设置字体颜色",
+	group: "text",
+	order: 4,
+	popup: "font-color",
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	onClick: () => {}
+});
+registerTool({
+	id: "font-size",
+	title: "字号",
+	icon: FontSize,
+	tooltip: "设置字体大小",
+	group: "text",
+	order: 5,
+	popup: "font-size",
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	onClick: () => {}
+});
+registerTool({
+	id: "align-left",
+	title: "左对齐",
+	icon: VerticalAlignLeft,
+	tooltip: "水平左对齐",
+	group: "text",
+	order: 6,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.align?.horizontal === "left";
+	},
+	onClick: (ctx) => toggleAlign(ctx, "horizontal", "left")
+});
+registerTool({
+	id: "align-center",
+	title: "居中",
+	icon: VerticalAlignCenter,
+	tooltip: "水平居中",
+	group: "text",
+	order: 7,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.align?.horizontal === "center";
+	},
+	onClick: (ctx) => toggleAlign(ctx, "horizontal", "center")
+});
+registerTool({
+	id: "align-right",
+	title: "右对齐",
+	icon: VerticalAlignRight,
+	tooltip: "水平右对齐",
+	group: "text",
+	order: 8,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.align?.horizontal === "right";
+	},
+	onClick: (ctx) => toggleAlign(ctx, "horizontal", "right")
+});
+registerTool({
+	id: "valign-top",
+	title: "顶端对齐",
+	icon: AlignTop,
+	tooltip: "垂直顶端对齐",
+	group: "text",
+	order: 9,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.align?.vertical === "top";
+	},
+	onClick: (ctx) => toggleAlign(ctx, "vertical", "top")
+});
+registerTool({
+	id: "valign-middle",
+	title: "垂直居中",
+	icon: AlignCenter,
+	tooltip: "垂直居中对齐",
+	group: "text",
+	order: 10,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.align?.vertical === "middle";
+	},
+	onClick: (ctx) => toggleAlign(ctx, "vertical", "middle")
+});
+registerTool({
+	id: "valign-bottom",
+	title: "底端对齐",
+	icon: AlignBottom,
+	tooltip: "垂直底端对齐",
+	group: "text",
+	order: 11,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(active)?.align?.vertical === "bottom";
+	},
+	onClick: (ctx) => toggleAlign(ctx, "vertical", "bottom")
+});
+registerTool({
+	id: "wrap-text",
+	title: "自动换行",
+	icon: Wrap,
+	tooltip: "自动换行",
+	group: "text",
+	order: 12,
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	active: (ctx) => {
+		const active = ctx.getSelection().activeCell;
+		return !!active && ctx.getCellStyle(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 } });
+	}
+});
+registerTool({
+	id: "find",
+	title: "查找",
+	icon: Search,
+	tooltip: "查找与替换（Ctrl/Cmd+F）",
+	group: "edit",
+	order: 0,
+	popup: "find",
+	onClick: () => {}
+});
+registerTool({
+	id: "insert-image",
+	title: "插入图片",
+	icon: PictureRounded,
+	tooltip: "插入浮动图片",
+	group: "insert",
+	order: 0,
+	popup: "insert-image",
+	disabled: (ctx) => !ctx.getSelection().activeCell,
+	onClick: () => {}
+});
+registerTool({
+	id: "import",
+	title: "导入",
+	icon: Download,
+	tooltip: "从 .xlsx / .csv 文件导入",
+	group: "file",
+	order: 0,
+	onClick: () => {}
+});
+registerTool({
+	id: "export",
+	title: "导出",
+	icon: Upload,
+	tooltip: "导出为 Excel 或 CSV",
+	group: "file",
+	order: 1,
+	popup: "export",
+	onClick: () => {}
+});
 //#endregion
-
-//# sourceMappingURL=builtin.js.map

package/dist/tools/context.d.ts

@@ -1,10 +1,14 @@
-import { CellAddress, CellRange } from "../core/address.js";
-import { CellData, CellValue } from "../core/cell-store.js";
-import { HistoryState } from "../core/command/history.js";
-import { CellInfo } from "../core/merge-manager.js";
-import { SelectionState } from "../core/selection.js";
-import { Sheet } from "../core/sheet.js";
-import { SetCellValueItem } from "../core/command/set-cell-value.js";
+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 { 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：工具的唯一操作门面。
@@ -18,16 +22,27 @@ import { SetCellValueItem } from "../core/command/set-cell-value.js";
 interface SheetContext {
   /** 当前活动 sheet 名 */
   readonly sheetName: string;
+  /**
+   * 当前工作簿（导入导出等需要工作簿级操作的场景；无头/单 sheet 场景可能为 undefined）。
+   * 只读引用：sheet 增删改名等结构操作仍应经宿主直接操作 Workbook（Phase 3 门面边界）。
+   */
+  readonly workbook?: Workbook;
   getSelection(): SelectionState;
   /** 选中单格（被覆盖格自动定位锚点） */
   selectCell(addr: CellAddress): void;
-  selectRange(range: CellRange): void;
+  selectRange(range: CellRange, active?: CellAddress): void;
   /** 原始存储语义读取（被合并覆盖格 → undefined） */
   getCellData(addr: CellAddress): CellData | undefined;
   /** 锚点解析语义读取（被覆盖格 → 锚点的值） */
   getDisplayValue(addr: CellAddress): CellValue | undefined;
   /** 合并语义下的单元格信息（普通格 / 合并锚点 / 被覆盖格） */
   getCellInfo(addr: CellAddress): CellInfo;
+  /** 设置区域样式（部分合并语义，见 CellStylePatch）；空样式 = 删除 s 字段 */
+  setCellStyle(range: CellRange, partial: CellStylePatch): void;
+  /** 清除区域样式（保留值 / 公式） */
+  clearCellStyle(range: CellRange): void;
+  /** 读取单元格样式（原始存储语义：被覆盖格 → undefined） */
+  getCellStyle(addr: CellAddress): CellStyle | undefined;
   setCellValue(addr: CellAddress, value: CellValue): void;
   setCellFormula(addr: CellAddress, formula: string): void;
   /** 批量写入（一次调用 = 一个 undo 单元） */
@@ -43,15 +58,43 @@ interface SheetContext {
   redo(): boolean;
   readonly canUndo: boolean;
   readonly canRedo: boolean;
+  /** 当前冻结状态（rows = 冻结顶部行数，cols = 冻结左侧列数） */
+  readonly frozen: FrozenState;
+  /** 设置冻结行列数（不进 undo，同 rowHeights 先例） */
+  setFrozen(rows: number, cols: number): void;
+  /** 插入 count 行到 at 行之前 */
+  insertRows(at: number, count?: number): void;
+  /** 插入 count 列到 at 列之前 */
+  insertCols(at: number, count?: number): void;
+  /** 删除 [at, at+count) 行 */
+  deleteRows(at: number, count?: number): void;
+  /** 删除 [at, at+count) 列 */
+  deleteCols(at: number, count?: number): void;
+  /** 插入浮动图片；返回生成的 id */
+  insertImage(input: ImageInput): string;
+  /** 删除浮动图片；不存在则无操作 */
+  removeImage(id: string): void;
+  /** 更新浮动图片锚点/尺寸/文案；不存在或无变更则无操作 */
+  updateImage(id: string, patch: ImageUpdateFields): void;
+  /** 只读图片列表（快照副本） */
+  getImages(): readonly SheetImage[];
   onSelectionChange(handler: (state: SelectionState) => void): () => void;
   onHistoryChange(handler: (state: HistoryState) => void): () => void;
+  onFrozenChange(handler: (state: FrozenState) => void): () => void;
+  /** 图片集合变化（单图带 id；整表替换时 id 缺省） */
+  onImageChange(handler: (payload: {
+    id?: string;
+  }) => void): () => void;
 }
 /**
  * 创建工具上下文。
  * @param resolveSheet 活动 sheet 解析器（USheet 传 `() => activeSheet`，
  *   tab 切换后上下文自动指向当前 sheet）；也可直接传 Sheet 实例（无头 / 测试场景）
+ * @param workbook 当前工作簿（导入导出等工具需要；无头 / 单 sheet 场景可省略）。
+ *   支持传解析函数 `() => Workbook`——USheet 在 props.workbook 动态切换后，
+ *   上下文始终解析到**当前**工作簿（#2：旧实现取构造时值快照，宿主切换
+ *   workbook prop 后导出工具仍导出旧工作簿）
  */
-declare function createSheetContext(resolveSheet: Sheet | (() => Sheet)): SheetContext;
+declare function createSheetContext(resolveSheet: Sheet | (() => Sheet), workbook?: Workbook | (() => Workbook)): SheetContext;
 //#endregion
-export { SheetContext, createSheetContext };
-//# sourceMappingURL=context.d.ts.map
+export { SheetContext, createSheetContext };

package/dist/tools/context.js

@@ -3,16 +3,24 @@
 * 创建工具上下文。
 * @param resolveSheet 活动 sheet 解析器（USheet 传 `() => activeSheet`，
 *   tab 切换后上下文自动指向当前 sheet）；也可直接传 Sheet 实例（无头 / 测试场景）
+* @param workbook 当前工作簿（导入导出等工具需要；无头 / 单 sheet 场景可省略）。
+*   支持传解析函数 `() => Workbook`——USheet 在 props.workbook 动态切换后，
+*   上下文始终解析到**当前**工作簿（#2：旧实现取构造时值快照，宿主切换
+*   workbook prop 后导出工具仍导出旧工作簿）
 */
-function createSheetContext(resolveSheet) {
+function createSheetContext(resolveSheet, workbook) {
 	const sheet = typeof resolveSheet === "function" ? resolveSheet : () => resolveSheet;
+	const resolveWorkbook = typeof workbook === "function" ? workbook : workbook != null ? () => workbook : void 0;
 	return {
+		get workbook() {
+			return resolveWorkbook?.();
+		},
 		get sheetName() {
 			return sheet().name;
 		},
 		getSelection: () => sheet().getSelection(),
 		selectCell: (addr) => sheet().selectCell(addr),
-		selectRange: (range) => sheet().selectRange(range),
+		selectRange: (range, active) => sheet().selectRange(range, active),
 		getCellData: (addr) => sheet().getCellData(addr),
 		getDisplayValue: (addr) => sheet().getDisplayValue(addr),
 		getCellInfo: (addr) => sheet().getCellInfo(addr),
@@ -21,7 +29,22 @@ function createSheetContext(resolveSheet) {
 		setCells: (items) => sheet().setCells(items),
 		mergeCells: (range) => sheet().mergeCells(range),
 		unmergeCells: (range) => sheet().unmergeCells(range),
+		setCellStyle: (range, partial) => sheet().setCellStyle(range, partial),
+		clearCellStyle: (range) => sheet().clearCellStyle(range),
+		getCellStyle: (addr) => sheet().getCellStyle(addr),
 		executeCommand: (commandId, params) => sheet().executeCommand(commandId, params),
+		get frozen() {
+			return sheet().frozen;
+		},
+		setFrozen: (rows, cols) => sheet().setFrozen(rows, cols),
+		insertRows: (at, count) => sheet().insertRows(at, count),
+		insertCols: (at, count) => sheet().insertCols(at, count),
+		deleteRows: (at, count) => sheet().deleteRows(at, count),
+		deleteCols: (at, count) => sheet().deleteCols(at, count),
+		insertImage: (input) => sheet().insertImage(input),
+		removeImage: (id) => sheet().removeImage(id),
+		updateImage: (id, patch) => sheet().updateImage(id, patch),
+		getImages: () => sheet().getImages(),
 		beginTransaction: () => sheet().beginTransaction(),
 		commit: () => sheet().commit(),
 		rollback: () => sheet().rollback(),
@@ -34,10 +57,10 @@ function createSheetContext(resolveSheet) {
 			return sheet().canRedo;
 		},
 		onSelectionChange: (handler) => sheet().on("selection-change", handler),
-		onHistoryChange: (handler) => sheet().on("history-change", handler)
+		onHistoryChange: (handler) => sheet().on("history-change", handler),
+		onFrozenChange: (handler) => sheet().on("frozen-change", handler),
+		onImageChange: (handler) => sheet().on("image-change", handler)
 	};
 }
 //#endregion
 export { createSheetContext };
-
-//# sourceMappingURL=context.js.map

package/dist/tools/download.js

@@ -0,0 +1,68 @@
+import { saveBlob } from "@cat-kit/fe";
+import { exportSheetCsv, exportWorkbookXlsx } from "@veltra/sheet-core/core/io/export";
+//#region src/tools/download.ts
+/**
+* 大工作簿的 XLSX 导出（hucre 序列化 + ZIP 压缩为秒级同步重活）移入 Web Worker：
+* 主线程只采集快照（结构化克隆友好的纯数据，行高随 SheetSnapshot.rowHeights
+* 携带），序列化与压缩在 worker 线程进行。worker 不可用（极端环境 / 打包产物
+* 缺文件）回退主线程导出——与导入侧 parseXlsxAsync 同一模式。
+*/
+async function exportWorkbookXlsxAsync(workbook) {
+	let worker;
+	try {
+		const url = import.meta.env?.DEV ? new URL("./export.worker.ts", import.meta.url) : new URL("./export.worker.js", import.meta.url);
+		worker = new Worker(url, { type: "module" });
+	} catch {
+		return exportWorkbookXlsx(workbook);
+	}
+	const payload = {
+		sheets: workbook.getSheets().map((sheet) => ({
+			name: sheet.name,
+			snapshot: sheet.snapshot()
+		})),
+		activeIndex: workbook.activeSheetIndex
+	};
+	return await new Promise((resolve, reject) => {
+		let settled = false;
+		const fallback = () => {
+			if (settled) return;
+			settled = true;
+			worker.terminate();
+			resolve(exportWorkbookXlsx(workbook));
+		};
+		worker.onmessage = (e) => {
+			if (settled) return;
+			settled = true;
+			worker.terminate();
+			const data = e.data;
+			if (!data.ok || !data.buffer) {
+				reject(new Error(data.error ?? "worker 导出失败"));
+				return;
+			}
+			resolve(data.buffer);
+		};
+		worker.onerror = () => fallback();
+		worker.postMessage(payload);
+	});
+}
+/**
+* 导出当前工作簿为 .xlsx（无 workbook 时空操作）。
+* 下载动作复用 @cat-kit/fe 的 saveBlob（#28：不再自研 Object URL + a.click）。
+* hucre 1.0 起 writeXlsx 会校验 sheet 名（Excel 非法字符 / 超长 / 保留名）并抛
+* InvalidArgumentError——失败经返回的 Promise 传播，调用方（导出面板）负责提示。
+*/
+async function exportWorkbookFile(ctx) {
+	const workbook = ctx.workbook;
+	if (!workbook) return;
+	const buffer = await exportWorkbookXlsxAsync(workbook);
+	saveBlob(new Blob([buffer], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" }), `${workbook.activeSheet.name || "workbook"}.xlsx`);
+}
+/** 导出当前工作表为 .csv（无 workbook 时空操作；同步，异常直接抛给调用方） */
+function exportSheetCsvFile(ctx) {
+	const workbook = ctx.workbook;
+	if (!workbook) return;
+	const csv = exportSheetCsv(workbook.activeSheet);
+	saveBlob(new Blob([csv], { type: "text/csv;charset=utf-8" }), `${workbook.activeSheet.name || "sheet"}.csv`);
+}
+//#endregion
+export { exportSheetCsvFile, exportWorkbookFile };

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

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