@veltra/sheet 2.1.1 → 2.2.0

package/dist/{vue → components/sheet}/use-sheet-grid.js

@@ -2,7 +2,7 @@ import { buildBodyMenus, buildColHeaderMenus, buildRowHeaderMenus, ensureContext
 import { onBeforeUnmount, onMounted, watch } from "vue";
 import { contextmenu } from "@veltra/desktop";
 import { SheetGrid } from "@veltra/sheet-core/grid/sheet-grid";
-//#region src/vue/use-sheet-grid.ts
+//#region src/components/sheet/use-sheet-grid.ts
 /**
 * 缓存容量：最近 N 个 sheet 的 SheetGrid 实例常驻（tab 来回切换零重建）。
 * 大文件多 sheet 场景下切换卡顿的主因是每次重建 VTable（实例创建 + scenegraph
@@ -62,6 +62,10 @@ function useSheetGrid(options) {
 			sheet,
 			rows: props.rows,
 			cols: props.cols,
+			readonly: props.readonly,
+			resolveDisplayValue: props.resolveDisplayValue,
+			resolveCellStyle: props.resolveCellStyle,
+			resolveCellRenderer: props.resolveCellRenderer,
 			onContextMenu: handleContextMenu,
 			onEditStart: (addr) => formulaBarRef.value?.mirrorGridEdit(addr),
 			onEditEnd: (addr) => formulaBarRef.value?.exitMirror(addr),
@@ -165,7 +169,11 @@ function useSheetGrid(options) {
 		activateGrid();
 	}
 	onMounted(activateGrid);
-	watch(() => [props.rows, props.cols], rebuildGrid);
+	watch(() => [
+		props.rows,
+		props.cols,
+		props.readonly
+	], rebuildGrid);
 	onBeforeUnmount(() => {
 		invalidateAll();
 	});

package/dist/{vue → components/sheet}/use-sheet-state.js

@@ -1,8 +1,8 @@
-import { defaultToolRegistry } from "../tools/registry.js";
-import { createSheetContext } from "../tools/context.js";
+import { defaultToolRegistry } from "../../tools/registry.js";
+import { createSheetContext } from "../../tools/context.js";
 import { computed, onBeforeUnmount, onMounted, ref, shallowRef, watch } from "vue";
 import { Workbook } from "@veltra/sheet-core/core/workbook";
-//#region src/vue/use-sheet-state.ts
+//#region src/components/sheet/use-sheet-state.ts
 /**
 * USheet 的状态源（单一数据源，其余状态由此推导）：
 * - workbook（外部传入或内部自建单 sheet 工作簿）、sheetList、activeIndex、activeSheet

package/dist/{vue → components/sheet}/use-sheet-tabs-bar.js

@@ -1,6 +1,6 @@
 import { nextTick, onBeforeUnmount, onMounted, shallowRef, watch } from "vue";
 import { applyWheelHorizontalScroll, computeOverflowNavState, scrollElementIntoView, scrollViewportByStep } from "@veltra/utils";
-//#region src/vue/use-sheet-tabs-bar.ts
+//#region src/components/sheet/use-sheet-tabs-bar.ts
 /**
 * Sheet 底部标签栏溢出滚动（滚动几何/滚轮转横滚/元素滚入视野共享
 * @veltra/utils overflow-nav，见 #17；此处保留事件绑定与 watch 差异）：

package/dist/{vue → components/sheet}/use-tool-groups.js

@@ -1,6 +1,6 @@
-import { defaultToolRegistry } from "../tools/registry.js";
+import { defaultToolRegistry } from "../../tools/registry.js";
 import { computed } from "vue";
-//#region src/vue/use-tool-groups.ts
+//#region src/components/sheet/use-tool-groups.ts
 /**
 * 内置组稳定顺序：history ｜ cell ｜ text ｜ edit ｜ insert ｜ file。
 * 未列出的自定义组按注册先后排在已知组之后。

package/dist/{vue → components/sheet}/use-tool-popup.js

@@ -1,6 +1,6 @@
-import { defaultToolRegistry } from "../tools/registry.js";
+import { defaultToolRegistry } from "../../tools/registry.js";
 import { onBeforeUnmount, onMounted, shallowRef } from "vue";
-//#region src/vue/use-tool-popup.ts
+//#region src/components/sheet/use-tool-popup.ts
 /**
 * 面板打开期间的写入是否合并为一个 undo 单元（关闭时提交）：
 * 填充颜色 / 边框 / 字体颜色 / 字号参与事务；查找（每次替换独立 undo）、

package/dist/{vue → components/sheet}/use-toolbar-scroll.js

@@ -1,6 +1,6 @@
 import { onBeforeUnmount, onMounted, shallowRef, watch } from "vue";
 import { applyWheelHorizontalScroll, computeOverflowNavState, scrollViewportByStep } from "@veltra/utils";
-//#region src/vue/use-toolbar-scroll.ts
+//#region src/components/sheet/use-toolbar-scroll.ts
 /**
 * 工具栏溢出滚动（滚动几何/滚轮转横滚共享 @veltra/utils overflow-nav，见 #17；
 * 无活动项跟随）：

package/dist/index.d.ts

@@ -1,7 +1,21 @@
-import _sfc_main from "./vue/sheet.js";
+import _sfc_main$2 from "./components/sheet/sheet.js";
+import _sfc_main$1 from "./components/report/report-viewer.js";
+import _sfc_main from "./components/report/report-designer.js";
 import { SheetContext, createSheetContext } from "./tools/context.js";
 import { SheetTool, SheetToolGroup, SheetToolPopupType, defaultToolRegistry, registerTool, unregisterTool } from "./tools/registry.js";
 import { SheetEmits, SheetExposed, SheetProps, _SheetExposed } from "./types/sheet.js";
+import { ConditionalOperator, ConditionalRule, DatasetCatalogItem, DatasetField, DatasetRecords, ParamValues, QueryParamDef, QueryParamOption, QueryParamType, ReportAggregate, ReportBinding, ReportExpand, ReportPreset, ReportSort } from "./report/types.js";
+import { REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatCellAddress, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, presetBindingPatch, setBindingCatalog } from "./report/binding.js";
+import { ConditionalEvalContext, evaluateCondition, evaluateConditionalStyle, resolveRuleCompareValue, toComparableNumber } from "./report/rules/evaluate.js";
+import { buildParamDefs, extractParamIds, resolveBoundDatasetParams } from "./report/params.js";
+import { ReportColWidthEntry, buildColumnDefs, exportFilledReportXlsx, pxToExcelColWidth } from "./report/export-xlsx.js";
+import { mapFilledColWidths } from "./report/render/builder.js";
+import { renderReport, resolveFilledColWidths } from "./report/render/index.js";
+import { ConnectionType, ConnectorError, CreateHttpConnectorOptions, DEFAULT_CONNECTION_PORTS, DataConnection, DataConnector, QueryResult, Result, createHttpConnector, resolvePortOnTypeChange } from "./report/connector.js";
+import { IncompatibleTemplateVersionError, REPORT_TEMPLATE_VERSION, ReportDatasetDef, ReportTemplate, assertCompatibleTemplateVersion, createReportTemplate, fetchTemplateRecords, getBoundDatasetIds, getTemplateDatasets, resolveParamDefaults, resolveTemplateParams } from "./report/template.js";
+import { parseDateRangeValue, patchParamValues, resolveNumberParamValue } from "./report/filter-bar.js";
+import "./report/index.js";
+import { ReportViewerExposed, ReportViewerProps, _ReportViewerExposed } from "./types/report-viewer.js";
+import { ReportDesignerEmits, ReportDesignerExposed, ReportDesignerProps, _ReportDesignerExposed } from "./types/report-designer.js";
 import "./types/index.js";
-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 };
+export { type ConditionalEvalContext, ConditionalOperator, ConditionalRule, ConnectionType, ConnectorError, CreateHttpConnectorOptions, DEFAULT_CONNECTION_PORTS, DataConnection, DataConnector, DatasetCatalogItem, DatasetField, DatasetRecords, IncompatibleTemplateVersionError, ParamValues, QueryParamDef, QueryParamOption, QueryParamType, QueryResult, REPORT_META_NAMESPACE, REPORT_TEMPLATE_VERSION, ReportAggregate, ReportBinding, ReportColWidthEntry, ReportDatasetDef, type ReportDesignerEmits, type ReportDesignerExposed, type ReportDesignerProps, ReportExpand, ReportPreset, ReportSort, ReportTemplate, type ReportViewerExposed, type ReportViewerProps, Result, type SheetContext, type SheetEmits, type SheetExposed, type SheetProps, type SheetTool, type SheetToolGroup, type SheetToolPopupType, _sfc_main as UReportDesigner, _sfc_main$1 as UReportViewer, _sfc_main$2 as USheet, type _ReportDesignerExposed, type _ReportViewerExposed, type _SheetExposed, applyReportPreset, assertCompatibleTemplateVersion, buildColumnDefs, buildParamDefs, createHttpConnector, createReportBinding, createReportTemplate, createSheetContext, defaultToolRegistry, evaluateCondition, evaluateConditionalStyle, exportFilledReportXlsx, extractParamIds, fetchTemplateRecords, formatBindingPlaceholder, formatCellAddress, getBoundDatasetIds, getTemplateDatasets, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, mapFilledColWidths, parseCellAddress, parseDateRangeValue, patchParamValues, presetBindingPatch, pxToExcelColWidth, registerTool, renderReport, resolveBoundDatasetParams, resolveFilledColWidths, resolveNumberParamValue, resolveParamDefaults, resolvePortOnTypeChange, resolveRuleCompareValue, resolveTemplateParams, setBindingCatalog, toComparableNumber, unregisterTool };

package/dist/index.js

@@ -1,6 +1,16 @@
 import { defaultToolRegistry, registerTool, unregisterTool } from "./tools/registry.js";
 import "./tools/builtin.js";
 import { createSheetContext } from "./tools/context.js";
-import _sfc_main from "./vue/sheet.js";
-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 };
+import _sfc_main$2 from "./components/sheet/sheet.js";
+import { buildColumnDefs, exportFilledReportXlsx, pxToExcelColWidth } from "./report/export-xlsx.js";
+import { parseDateRangeValue, patchParamValues, resolveNumberParamValue } from "./report/filter-bar.js";
+import { REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatCellAddress, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, presetBindingPatch, setBindingCatalog } from "./report/binding.js";
+import { evaluateCondition, evaluateConditionalStyle, resolveRuleCompareValue, toComparableNumber } from "./report/rules/evaluate.js";
+import { mapFilledColWidths } from "./report/render/builder.js";
+import { renderReport, resolveFilledColWidths } from "./report/render/index.js";
+import { buildParamDefs, extractParamIds, resolveBoundDatasetParams } from "./report/params.js";
+import { IncompatibleTemplateVersionError, REPORT_TEMPLATE_VERSION, assertCompatibleTemplateVersion, createReportTemplate, fetchTemplateRecords, getBoundDatasetIds, getTemplateDatasets, resolveParamDefaults, resolveTemplateParams } from "./report/template.js";
+import _sfc_main$1 from "./components/report/report-viewer.js";
+import { DEFAULT_CONNECTION_PORTS, createHttpConnector, resolvePortOnTypeChange } from "./report/connector.js";
+import _sfc_main from "./components/report/report-designer.js";
+export { DEFAULT_CONNECTION_PORTS, IncompatibleTemplateVersionError, REPORT_META_NAMESPACE, REPORT_TEMPLATE_VERSION, _sfc_main as UReportDesigner, _sfc_main$1 as UReportViewer, _sfc_main$2 as USheet, applyReportPreset, assertCompatibleTemplateVersion, buildColumnDefs, buildParamDefs, createHttpConnector, createReportBinding, createReportTemplate, createSheetContext, defaultToolRegistry, evaluateCondition, evaluateConditionalStyle, exportFilledReportXlsx, extractParamIds, fetchTemplateRecords, formatBindingPlaceholder, formatCellAddress, getBoundDatasetIds, getTemplateDatasets, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, mapFilledColWidths, parseCellAddress, parseDateRangeValue, patchParamValues, presetBindingPatch, pxToExcelColWidth, registerTool, renderReport, resolveBoundDatasetParams, resolveFilledColWidths, resolveNumberParamValue, resolveParamDefaults, resolvePortOnTypeChange, resolveRuleCompareValue, resolveTemplateParams, setBindingCatalog, toComparableNumber, unregisterTool };

package/dist/report/binding.d.ts

@@ -0,0 +1,45 @@
+import { DatasetCatalogItem, ReportBinding, ReportPreset } from "./types.js";
+import { CellAddress } from "@veltra/sheet-core";
+//#region src/report/binding.d.ts
+declare function setBindingCatalog(catalog: DatasetCatalogItem[]): void;
+declare const REPORT_META_NAMESPACE = "report";
+/** 预设 → 绑定字段补丁（父格除 grandTotal 外均保留推断值） */
+declare function presetBindingPatch(preset: ReportPreset, options?: {
+  transpose?: boolean;
+}): Partial<ReportBinding>;
+/** 将预设写入绑定（grandTotal 清空双父格；其余保留既有父格） */
+declare function applyReportPreset(binding: ReportBinding, preset: ReportPreset, options?: {
+  transpose?: boolean;
+}): ReportBinding;
+declare function isVerticalExpandBinding(binding: ReportBinding): boolean;
+declare function isHorizontalExpandBinding(binding: ReportBinding): boolean;
+/** 指定模板行是否含纵向扩展绑定（展开带行） */
+declare function isExpansionBandRow(row: number, getBindingAt: (addr: CellAddress) => ReportBinding | undefined, scanCols?: number): boolean;
+/** 落格时推断预设：默认明细；数值字段且位于展开带正下方相邻行 → 小计 */
+declare function inferDropPreset(addr: CellAddress, fieldType: DatasetCatalogItem['fields'][number]['type'], getBindingAt: (addr: CellAddress) => ReportBinding | undefined): ReportPreset;
+/** 同数据集纵向扩展绑定格（行方向父格下拉候选） */
+declare function listRowParentCandidates(binding: ReportBinding, entries: ReadonlyArray<{
+  addr: CellAddress;
+  binding: ReportBinding;
+}>): CellAddress[];
+/** 同数据集横向扩展绑定格（列方向父格下拉候选） */
+declare function listColParentCandidates(binding: ReportBinding, entries: ReadonlyArray<{
+  addr: CellAddress;
+  binding: ReportBinding;
+}>): CellAddress[];
+/** 同列向上找最近的纵向扩展绑定，作为 rowParent 候选 */
+declare function inferRowParentCandidate(addr: CellAddress, getBindingAt: (addr: CellAddress) => ReportBinding | undefined): CellAddress | null;
+/** 同行向左找最近的横向扩展绑定，作为 colParent 候选 */
+declare function inferColParentCandidate(addr: CellAddress, getBindingAt: (addr: CellAddress) => ReportBinding | undefined): CellAddress | null;
+/** 从绑定字段推断预设；不匹配任何预设时返回 null（自定义） */
+declare function inferReportPreset(binding: ReportBinding): ReportPreset | null;
+/** 默认明细 + 纵向扩展 */
+declare function createReportBinding(dataset: DatasetCatalogItem, fieldName: string): ReportBinding;
+/** 设计地址 → A1 标签（支持多字母列） */
+declare function formatCellAddress(addr: CellAddress): string;
+/** A1 标签 → 设计地址；非法输入返回 null */
+declare function parseCellAddress(label: string): CellAddress | null;
+/** Binding Placeholder 中文可读文案（如「分组 · 客户」） */
+declare function formatBindingPlaceholder(binding: ReportBinding, resolveLabel?: (datasetId: string, fieldName: string) => string): string;
+//#endregion
+export { REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatCellAddress, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, presetBindingPatch, setBindingCatalog };

package/dist/report/binding.js

@@ -0,0 +1,175 @@
+import { formatAddress, parseAddress } from "@veltra/sheet-core";
+//#region src/report/binding.ts
+/** 字段 label 解析用的 catalog（由宿主注入） */
+let bindingCatalog = [];
+function setBindingCatalog(catalog) {
+	bindingCatalog = catalog;
+}
+const REPORT_META_NAMESPACE = "report";
+const AGGREGATE_PLACEHOLDER_TAG = {
+	list: "明细",
+	group: "分组",
+	sum: "求和",
+	avg: "平均",
+	count: "计数",
+	max: "最大",
+	min: "最小"
+};
+/** 预设 → 绑定字段补丁（父格除 grandTotal 外均保留推断值） */
+function presetBindingPatch(preset, options) {
+	const expand = options?.transpose ? "right" : "down";
+	switch (preset) {
+		case "groupHeader": return {
+			preset,
+			expand,
+			aggregate: "group"
+		};
+		case "detail": return {
+			preset,
+			expand,
+			aggregate: "list"
+		};
+		case "subtotal": return {
+			preset,
+			expand: "none",
+			aggregate: "sum"
+		};
+		case "grandTotal": return {
+			preset,
+			expand: "none",
+			aggregate: "sum",
+			rowParent: void 0,
+			colParent: void 0
+		};
+		case "cross": return {
+			preset,
+			expand: "none",
+			aggregate: "sum"
+		};
+	}
+}
+/** 将预设写入绑定（grandTotal 清空双父格；其余保留既有父格） */
+function applyReportPreset(binding, preset, options) {
+	const patch = presetBindingPatch(preset, options);
+	const next = {
+		...binding,
+		...patch
+	};
+	if (preset === "grandTotal") {
+		delete next.rowParent;
+		delete next.colParent;
+	}
+	return next;
+}
+function isVerticalExpandBinding(binding) {
+	return binding.expand === "down" && (binding.aggregate === "group" || binding.aggregate === "list");
+}
+function isHorizontalExpandBinding(binding) {
+	return binding.expand === "right" && binding.aggregate === "group";
+}
+/** 指定模板行是否含纵向扩展绑定（展开带行） */
+function isExpansionBandRow(row, getBindingAt, scanCols = 64) {
+	for (let col = 0; col < scanCols; col++) {
+		const binding = getBindingAt({
+			row,
+			col
+		});
+		if (binding && isVerticalExpandBinding(binding)) return true;
+	}
+	return false;
+}
+/** 落格时推断预设：默认明细；数值字段且位于展开带正下方相邻行 → 小计 */
+function inferDropPreset(addr, fieldType, getBindingAt) {
+	if (fieldType === "number" && addr.row > 0 && isExpansionBandRow(addr.row - 1, getBindingAt)) return "subtotal";
+	return "detail";
+}
+/** 同数据集纵向扩展绑定格（行方向父格下拉候选） */
+function listRowParentCandidates(binding, entries) {
+	const candidates = [];
+	for (const entry of entries) {
+		if (entry.binding.dataset !== binding.dataset) continue;
+		if (!isVerticalExpandBinding(entry.binding)) continue;
+		candidates.push(entry.addr);
+	}
+	return candidates;
+}
+/** 同数据集横向扩展绑定格（列方向父格下拉候选） */
+function listColParentCandidates(binding, entries) {
+	const candidates = [];
+	for (const entry of entries) {
+		if (entry.binding.dataset !== binding.dataset) continue;
+		if (!isHorizontalExpandBinding(entry.binding)) continue;
+		candidates.push(entry.addr);
+	}
+	return candidates;
+}
+/** 同列向上找最近的纵向扩展绑定，作为 rowParent 候选 */
+function inferRowParentCandidate(addr, getBindingAt) {
+	for (let row = addr.row - 1; row >= 0; row--) {
+		const binding = getBindingAt({
+			row,
+			col: addr.col
+		});
+		if (binding && isVerticalExpandBinding(binding)) return {
+			row,
+			col: addr.col
+		};
+	}
+	return null;
+}
+/** 同行向左找最近的横向扩展绑定，作为 colParent 候选 */
+function inferColParentCandidate(addr, getBindingAt) {
+	for (let col = addr.col - 1; col >= 0; col--) {
+		const binding = getBindingAt({
+			row: addr.row,
+			col
+		});
+		if (binding && isHorizontalExpandBinding(binding)) return {
+			row: addr.row,
+			col
+		};
+	}
+	return null;
+}
+/** 从绑定字段推断预设；不匹配任何预设时返回 null（自定义） */
+function inferReportPreset(binding) {
+	if (binding.preset) return binding.preset;
+	if (binding.expand === "none" && binding.aggregate === "sum" && binding.rowParent && binding.colParent) return "cross";
+	if (binding.expand === "none" && binding.aggregate === "sum" && !binding.rowParent && !binding.colParent) return "grandTotal";
+	if (binding.expand === "none" && binding.aggregate === "sum" && binding.rowParent && !binding.colParent) return "subtotal";
+	if (binding.aggregate === "group" && (binding.expand === "down" || binding.expand === "right")) return "groupHeader";
+	if (binding.aggregate === "list" && (binding.expand === "down" || binding.expand === "right")) return "detail";
+	return null;
+}
+/** 默认明细 + 纵向扩展 */
+function createReportBinding(dataset, fieldName) {
+	return {
+		dataset: dataset.id,
+		field: fieldName,
+		aggregate: "list",
+		expand: "down",
+		preset: "detail",
+		sort: "none",
+		conditionalRules: []
+	};
+}
+/** 设计地址 → A1 标签（支持多字母列） */
+function formatCellAddress(addr) {
+	return formatAddress(addr);
+}
+/** A1 标签 → 设计地址；非法输入返回 null */
+function parseCellAddress(label) {
+	return parseAddress(label);
+}
+/** 解析字段中文标签（找不到时回退字段名）；可传入报表配置中的 label */
+function resolveFieldLabel(datasetId, fieldName, resolveLabel) {
+	const override = resolveLabel?.(datasetId, fieldName);
+	if (override) return override;
+	return (bindingCatalog.find((d) => d.id === datasetId)?.fields.find((f) => f.name === fieldName))?.label ?? fieldName;
+}
+/** Binding Placeholder 中文可读文案（如「分组 · 客户」） */
+function formatBindingPlaceholder(binding, resolveLabel) {
+	return `${AGGREGATE_PLACEHOLDER_TAG[binding.aggregate]} · ${resolveFieldLabel(binding.dataset, binding.field, resolveLabel)}`;
+}
+//#endregion
+export { REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatCellAddress, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, presetBindingPatch, setBindingCatalog };

package/dist/report/connector.d.ts

@@ -0,0 +1,66 @@
+import { DatasetField, ParamValues } from "./types.js";
+//#region src/report/connector.d.ts
+/** 数据连接类型（ADR-0003 决策 3：收敛为 MySQL / PostgreSQL） */
+type ConnectionType = 'mysql' | 'postgresql';
+/** 各连接类型的默认端口 */
+declare const DEFAULT_CONNECTION_PORTS: Record<ConnectionType, number>;
+/**
+ * 切换连接类型时解析端口：若当前端口仍是上一类型的默认值（或 0），则切到新类型默认端口；
+ * 用户已自定义的端口保持不变。
+ */
+declare function resolvePortOnTypeChange(prevType: ConnectionType, nextType: ConnectionType, currentPort: number): number;
+/**
+ * 数据连接（纯序列化对象，仅驻留内存）。
+ * 凭据持久化与安全存储由下游负责（ADR-0003 决策 4）。
+ */
+interface DataConnection {
+  id: string;
+  label: string;
+  type: ConnectionType;
+  host: string;
+  port: number;
+  database: string;
+  username: string;
+  password: string;
+}
+/** 业务错误（`200 + { ok: false, error }`）或客户端传输层错误 */
+interface ConnectorError {
+  code: string;
+  message: string;
+}
+/** 统一结果：成功携带 data；失败携带 error（连接器不抛异常，调用方只处理一条错误路径） */
+type Result<T> = {
+  ok: true;
+  data: T;
+} | {
+  ok: false;
+  error: ConnectorError;
+};
+/** query 成功结果：字段 schema + 行记录（契约 `{ fields, rows }` 归一化后） */
+interface QueryResult {
+  fields: DatasetField[];
+  rows: Record<string, unknown>[];
+}
+/**
+ * 数据连接器（词汇表：Data Connector）：test / describe / query 三方法镜像 HTTP 契约三端点。
+ * 真实数据库访问由下游后端以任意语言实现（BYO）。
+ */
+interface DataConnector {
+  test(connection: DataConnection): Promise<Result<void>>;
+  describe(connection: DataConnection, sql: string): Promise<Result<DatasetField[]>>;
+  query(connection: DataConnection, sql: string, values: ParamValues): Promise<Result<QueryResult>>;
+}
+interface CreateHttpConnectorOptions {
+  /** 契约端点前缀，如 `https://api.example.com/report`；三端点 = `{endpoint}/test|describe|query`（无版本段） */
+  endpoint: string;
+}
+/**
+ * 创建 HTTP 数据连接器：三方法对应 `POST {endpoint}/test|describe|query`。
+ * - 请求体 JSON 序列化，`Content-Type: application/json`；
+ * - 网络异常与非 2xx（传输层错误）折叠为 `{ ok: false, error }`，不抛异常；
+ * - 业务错误（连接失败 / SQL 报错）由服务端以 `200 + { ok: false, error: { code, message } }` 返回并原样透传；
+ * - `describe` / `query` 的 fields 归一化为内核 `DatasetField`（label 回退 name，type 缺省 string）。
+ */
+declare function createHttpConnector({ endpoint }: CreateHttpConnectorOptions): DataConnector;
+//#endregion
+export { ConnectionType, ConnectorError, CreateHttpConnectorOptions, DEFAULT_CONNECTION_PORTS, DataConnection, DataConnector, QueryResult, Result, createHttpConnector, resolvePortOnTypeChange };

package/dist/report/connector.js

@@ -0,0 +1,159 @@
+//#region src/report/connector.ts
+/** 各连接类型的默认端口 */
+const DEFAULT_CONNECTION_PORTS = {
+	mysql: 3306,
+	postgresql: 5432
+};
+/**
+* 切换连接类型时解析端口：若当前端口仍是上一类型的默认值（或 0），则切到新类型默认端口；
+* 用户已自定义的端口保持不变。
+*/
+function resolvePortOnTypeChange(prevType, nextType, currentPort) {
+	if (prevType === nextType) return currentPort;
+	if (currentPort === DEFAULT_CONNECTION_PORTS[prevType] || currentPort === 0) return DEFAULT_CONNECTION_PORTS[nextType];
+	return currentPort;
+}
+/** 客户端错误：网络不可达 / 非 2xx / 响应不可解析（业务错误由服务端 200 透传） */
+function badResponse(message) {
+	return {
+		ok: false,
+		error: {
+			code: "BAD_RESPONSE",
+			message
+		}
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toConnectorError(value) {
+	if (isRecord(value)) {
+		const { code, message } = value;
+		if (typeof code === "string" && typeof message === "string") return {
+			code,
+			message
+		};
+	}
+	return {
+		code: "SERVER_ERROR",
+		message: "服务端返回未知错误"
+	};
+}
+/** 契约字段 → 内核 DatasetField（label 缺省回退 name，type 缺省 string） */
+function normalizeField(field) {
+	return {
+		name: field.name,
+		label: field.name,
+		type: field.type ?? "string"
+	};
+}
+/** 校验并归一化契约 fields；形状不合法返回 null */
+function normalizeFields(fields) {
+	if (!Array.isArray(fields)) return null;
+	const normalized = [];
+	for (const field of fields) {
+		if (!isRecord(field) || typeof field.name !== "string") return null;
+		normalized.push(normalizeField(field));
+	}
+	return normalized;
+}
+/**
+* 创建 HTTP 数据连接器：三方法对应 `POST {endpoint}/test|describe|query`。
+* - 请求体 JSON 序列化，`Content-Type: application/json`；
+* - 网络异常与非 2xx（传输层错误）折叠为 `{ ok: false, error }`，不抛异常；
+* - 业务错误（连接失败 / SQL 报错）由服务端以 `200 + { ok: false, error: { code, message } }` 返回并原样透传；
+* - `describe` / `query` 的 fields 归一化为内核 `DatasetField`（label 回退 name，type 缺省 string）。
+*/
+function createHttpConnector({ endpoint }) {
+	async function postJson(path, body) {
+		let response;
+		try {
+			response = await fetch(`${endpoint}${path}`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body)
+			});
+		} catch (error) {
+			return {
+				ok: false,
+				error: {
+					code: "NETWORK_ERROR",
+					message: error instanceof Error ? error.message : String(error)
+				}
+			};
+		}
+		if (!response.ok) return {
+			ok: false,
+			error: {
+				code: `HTTP_${response.status}`,
+				message: `请求失败（HTTP ${response.status}）`
+			}
+		};
+		let payload;
+		try {
+			payload = await response.json();
+		} catch {
+			return badResponse("响应不是合法 JSON");
+		}
+		if (!isRecord(payload)) return badResponse("响应不是 JSON 对象");
+		return {
+			ok: true,
+			data: payload
+		};
+	}
+	return {
+		async test(connection) {
+			const result = await postJson("/test", { connection });
+			if (!result.ok) return result;
+			if (result.data.ok === true) return {
+				ok: true,
+				data: void 0
+			};
+			return {
+				ok: false,
+				error: toConnectorError(result.data.error)
+			};
+		},
+		async describe(connection, sql) {
+			const result = await postJson("/describe", {
+				connection,
+				sql
+			});
+			if (!result.ok) return result;
+			if (result.data.ok !== true) return {
+				ok: false,
+				error: toConnectorError(result.data.error)
+			};
+			const fields = normalizeFields(result.data.fields);
+			if (!fields) return badResponse("describe 响应缺少合法的 fields 数组");
+			return {
+				ok: true,
+				data: fields
+			};
+		},
+		async query(connection, sql, values) {
+			const result = await postJson("/query", {
+				connection,
+				sql,
+				values
+			});
+			if (!result.ok) return result;
+			if (result.data.ok !== true) return {
+				ok: false,
+				error: toConnectorError(result.data.error)
+			};
+			const fields = normalizeFields(result.data.fields);
+			if (!fields) return badResponse("query 响应缺少合法的 fields 数组");
+			if (!Array.isArray(result.data.rows)) return badResponse("query 响应缺少 rows 数组");
+			return {
+				ok: true,
+				data: {
+					fields,
+					rows: result.data.rows
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { DEFAULT_CONNECTION_PORTS, createHttpConnector, resolvePortOnTypeChange };

package/dist/report/export-xlsx.d.ts

@@ -0,0 +1,19 @@
+import { Sheet } from "@veltra/sheet-core";
+import { ColumnDef } from "hucre";
+//#region src/report/export-xlsx.d.ts
+/** 列宽条目：模型列索引 → 像素宽（sheet-core 列宽未进 SheetSnapshot，导出时由调用方显式传入） */
+type ReportColWidthEntry = readonly [number, number];
+/** VTable 像素列宽 → Excel 字符宽度（近似换算） */
+declare function pxToExcelColWidth(px: number): number;
+/** 从列宽条目构建 hucre ColumnDef */
+declare function buildColumnDefs(colWidths: ReadonlyArray<ReportColWidthEntry>): ColumnDef[];
+/**
+ * 将已填充的 Sheet（Filled Report）导出为保真 XLSX（合并 / 样式 / 行高 / 列宽）。
+ * 条件样式颜色已在 renderReport 展开阶段打平进 StylePool（ADR-0001 决策 2）。
+ *
+ * 与 `exportWorkbookXlsx`（sheet-core）的差异：列宽未进 SheetSnapshot，
+ * 只能经 VTable 运行时读取，故这里接收显式列宽并写入 columns 定义。
+ */
+declare function exportFilledReportXlsx(sheet: Sheet, colWidths: ReadonlyArray<ReportColWidthEntry>): Promise<Uint8Array>;
+//#endregion
+export { ReportColWidthEntry, buildColumnDefs, exportFilledReportXlsx, pxToExcelColWidth };