@veltra/sheet 2.2.0 → 2.3.0

package/dist/report/binding.d.ts

@@ -1,4 +1,4 @@
-import { DatasetCatalogItem, ReportBinding, ReportPreset } from "./types.js";
+import { DatasetCatalogItem, ReportAggregate, ReportBinding, ReportPreset } from "./types.js";
 import { CellAddress } from "@veltra/sheet-core";
 //#region src/report/binding.d.ts
 declare function setBindingCatalog(catalog: DatasetCatalogItem[]): void;
@@ -13,24 +13,55 @@ declare function applyReportPreset(binding: ReportBinding, preset: ReportPreset,
 }): ReportBinding;
 declare function isVerticalExpandBinding(binding: ReportBinding): boolean;
 declare function isHorizontalExpandBinding(binding: ReportBinding): boolean;
+declare function isRowGroupBinding(binding: ReportBinding): boolean;
+declare function isColGroupBinding(binding: ReportBinding): boolean;
+declare function isReductionAggregate(aggregate: ReportAggregate): boolean;
+/** 小计 / 汇总 / 交叉格的父格候选只列分组头 */
+declare function prefersGroupParent(binding: ReportBinding): boolean;
+/** 当前 expand / aggregate 是否仍属于已写入的预设族（同族内改聚合不掉到「自定义」） */
+declare function presetStillApplies(binding: ReportBinding): boolean;
+type GetBindingAt = (addr: CellAddress) => ReportBinding | undefined;
+interface InferParentOptions {
+  /** 小计落格：必须优先分组头，禁止把同列/同行明细当成父格 */
+  preferGroup?: 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 isExpansionBandRow(row: number, getBindingAt: GetBindingAt, scanCols?: number): boolean;
+/** 指定模板列是否含横向扩展绑定（展开带列） */
+declare function isExpansionBandCol(col: number, getBindingAt: GetBindingAt, scanRows?: number): boolean;
+/** 落格时推断预设：默认明细；数值字段且位于展开带正下方或正右相邻 → 小计 */
+declare function inferDropPreset(addr: CellAddress, fieldType: DatasetCatalogItem['fields'][number]['type'], getBindingAt: GetBindingAt): ReportPreset;
+interface ListParentCandidateOptions {
+  preferGroup?: boolean;
+}
 /** 同数据集纵向扩展绑定格（行方向父格下拉候选） */
 declare function listRowParentCandidates(binding: ReportBinding, entries: ReadonlyArray<{
   addr: CellAddress;
   binding: ReportBinding;
-}>): CellAddress[];
+}>, options?: ListParentCandidateOptions): 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;
+}>, options?: ListParentCandidateOptions): CellAddress[];
+/**
+ * 行方向父格推断：
+ * 1. 同行向左：先找分组头，否则最近纵向扩展格
+ * 2. 上方各行整行扫描：每行先找分组头，再退回任意纵向扩展格
+ * 小计（preferGroup）禁止把明细当成父格
+ */
+declare function inferRowParentCandidate(addr: CellAddress, getBindingAt: GetBindingAt, options?: InferParentOptions): CellAddress | null;
+/**
+ * 列方向父格推断（与行方向对称）：
+ * 1. 同列向上：先找列分组头，否则最近横向扩展格
+ * 2. 左侧各列整列扫描：每列先找列分组头
+ * 列小计（preferGroup）禁止把交叉格/明细当成列父格
+ */
+declare function inferColParentCandidate(addr: CellAddress, getBindingAt: GetBindingAt, options?: InferParentOptions): CellAddress | null;
+/**
+ * 按预设写入落格父格：明细/分组/交叉双方向推断；小计按「下方行小计 / 右侧列小计」只挂对应轴。
+ */
+declare function inferParentsForPreset(addr: CellAddress, preset: ReportPreset, getBindingAt: GetBindingAt): Pick<ReportBinding, 'rowParent' | 'colParent'>;
 /** 从绑定字段推断预设；不匹配任何预设时返回 null（自定义） */
 declare function inferReportPreset(binding: ReportBinding): ReportPreset | null;
 /** 默认明细 + 纵向扩展 */
@@ -39,7 +70,14 @@ declare function createReportBinding(dataset: DatasetCatalogItem, fieldName: str
 declare function formatCellAddress(addr: CellAddress): string;
 /** A1 标签 → 设计地址；非法输入返回 null */
 declare function parseCellAddress(label: string): CellAddress | null;
+/** Binding Placeholder 分段文案（聚合标签 + 字段标签），供徽章分色渲染等场景使用 */
+declare function formatBindingPlaceholderParts(binding: ReportBinding, resolveLabel?: (datasetId: string, fieldName: string) => string): {
+  tag: string;
+  label: string;
+};
 /** Binding Placeholder 中文可读文案（如「分组 · 客户」） */
 declare function formatBindingPlaceholder(binding: ReportBinding, resolveLabel?: (datasetId: string, fieldName: string) => string): string;
+/** 父格下拉候选文案（如「分组 · 客户 (A2)」） */
+declare function formatParentCandidateLabel(addr: CellAddress, 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 };
+export { InferParentOptions, ListParentCandidateOptions, REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatBindingPlaceholderParts, formatCellAddress, formatParentCandidateLabel, inferColParentCandidate, inferDropPreset, inferParentsForPreset, inferReportPreset, inferRowParentCandidate, isColGroupBinding, isExpansionBandCol, isExpansionBandRow, isHorizontalExpandBinding, isReductionAggregate, isRowGroupBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, prefersGroupParent, presetBindingPatch, presetStillApplies, setBindingCatalog };

package/dist/report/binding.js

@@ -65,10 +65,34 @@ function isVerticalExpandBinding(binding) {
 	return binding.expand === "down" && (binding.aggregate === "group" || binding.aggregate === "list");
 }
 function isHorizontalExpandBinding(binding) {
+	return binding.expand === "right" && (binding.aggregate === "group" || binding.aggregate === "list");
+}
+function isRowGroupBinding(binding) {
+	return binding.expand === "down" && binding.aggregate === "group";
+}
+function isColGroupBinding(binding) {
 	return binding.expand === "right" && binding.aggregate === "group";
 }
+function isReductionAggregate(aggregate) {
+	return aggregate === "sum" || aggregate === "avg" || aggregate === "count" || aggregate === "max" || aggregate === "min";
+}
+/** 小计 / 汇总 / 交叉格的父格候选只列分组头 */
+function prefersGroupParent(binding) {
+	if (binding.preset === "subtotal" || binding.preset === "grandTotal" || binding.preset === "cross") return true;
+	return binding.expand === "none" && isReductionAggregate(binding.aggregate);
+}
+/** 当前 expand / aggregate 是否仍属于已写入的预设族（同族内改聚合不掉到「自定义」） */
+function presetStillApplies(binding) {
+	const preset = binding.preset;
+	if (!preset) return false;
+	if (preset === "groupHeader") return binding.aggregate === "group" && (binding.expand === "down" || binding.expand === "right");
+	if (preset === "detail") return binding.aggregate === "list" && (binding.expand === "down" || binding.expand === "right");
+	return binding.expand === "none" && isReductionAggregate(binding.aggregate);
+}
+const DEFAULT_SCAN_COLS = 64;
+const DEFAULT_SCAN_ROWS = 64;
 /** 指定模板行是否含纵向扩展绑定（展开带行） */
-function isExpansionBandRow(row, getBindingAt, scanCols = 64) {
+function isExpansionBandRow(row, getBindingAt, scanCols = DEFAULT_SCAN_COLS) {
 	for (let col = 0; col < scanCols; col++) {
 		const binding = getBindingAt({
 			row,
@@ -78,65 +102,186 @@ function isExpansionBandRow(row, getBindingAt, scanCols = 64) {
 	}
 	return false;
 }
-/** 落格时推断预设：默认明细；数值字段且位于展开带正下方相邻行 → 小计 */
+/** 指定模板列是否含横向扩展绑定（展开带列） */
+function isExpansionBandCol(col, getBindingAt, scanRows = DEFAULT_SCAN_ROWS) {
+	for (let row = 0; row < scanRows; row++) {
+		const binding = getBindingAt({
+			row,
+			col
+		});
+		if (binding && isHorizontalExpandBinding(binding)) return true;
+	}
+	return false;
+}
+/** 落格时推断预设：默认明细；数值字段且位于展开带正下方或正右相邻 → 小计 */
 function inferDropPreset(addr, fieldType, getBindingAt) {
-	if (fieldType === "number" && addr.row > 0 && isExpansionBandRow(addr.row - 1, getBindingAt)) return "subtotal";
+	if (fieldType !== "number") return "detail";
+	if (addr.row > 0 && isExpansionBandRow(addr.row - 1, getBindingAt)) return "subtotal";
+	if (addr.col > 0 && isExpansionBandCol(addr.col - 1, getBindingAt)) return "subtotal";
 	return "detail";
 }
 /** 同数据集纵向扩展绑定格（行方向父格下拉候选） */
-function listRowParentCandidates(binding, entries) {
+function listRowParentCandidates(binding, entries, options) {
+	const preferGroup = options?.preferGroup === true;
 	const candidates = [];
 	for (const entry of entries) {
 		if (entry.binding.dataset !== binding.dataset) continue;
-		if (!isVerticalExpandBinding(entry.binding)) continue;
+		if (preferGroup) {
+			if (!isRowGroupBinding(entry.binding)) continue;
+		} else if (!isVerticalExpandBinding(entry.binding)) continue;
 		candidates.push(entry.addr);
 	}
 	return candidates;
 }
 /** 同数据集横向扩展绑定格（列方向父格下拉候选） */
-function listColParentCandidates(binding, entries) {
+function listColParentCandidates(binding, entries, options) {
+	const preferGroup = options?.preferGroup === true;
 	const candidates = [];
 	for (const entry of entries) {
 		if (entry.binding.dataset !== binding.dataset) continue;
-		if (!isHorizontalExpandBinding(entry.binding)) continue;
+		if (preferGroup) {
+			if (!isColGroupBinding(entry.binding)) continue;
+		} else 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--) {
+function betterHit(current, next) {
+	if (!current) return true;
+	if (next.distance !== current.distance) return next.distance < current.distance;
+	return next.addr.col + next.addr.row < current.addr.col + current.addr.row;
+}
+function pickExpandHit(hits, preferGroup) {
+	let group = null;
+	let expand = null;
+	for (const hit of hits) {
+		if (hit.group && betterHit(group, hit)) group = hit;
+		if (betterHit(expand, hit)) expand = hit;
+	}
+	if (preferGroup) return group?.addr ?? null;
+	return group?.addr ?? expand?.addr ?? null;
+}
+function scanVerticalOnRow(row, originCol, colStart, colEnd, getBindingAt) {
+	const hits = [];
+	for (let col = colStart; col < colEnd; col++) {
 		const binding = getBindingAt({
 			row,
-			col: addr.col
+			col
+		});
+		if (!binding || !isVerticalExpandBinding(binding)) continue;
+		hits.push({
+			addr: {
+				row,
+				col
+			},
+			group: isRowGroupBinding(binding),
+			distance: Math.abs(col - originCol)
 		});
-		if (binding && isVerticalExpandBinding(binding)) return {
-			row,
-			col: addr.col
-		};
 	}
-	return null;
+	return hits;
 }
-/** 同行向左找最近的横向扩展绑定，作为 colParent 候选 */
-function inferColParentCandidate(addr, getBindingAt) {
-	for (let col = addr.col - 1; col >= 0; col--) {
+function scanHorizontalOnCol(col, originRow, rowStart, rowEnd, getBindingAt) {
+	const hits = [];
+	for (let row = rowStart; row < rowEnd; row++) {
 		const binding = getBindingAt({
-			row: addr.row,
+			row,
 			col
 		});
-		if (binding && isHorizontalExpandBinding(binding)) return {
-			row: addr.row,
-			col
-		};
+		if (!binding || !isHorizontalExpandBinding(binding)) continue;
+		hits.push({
+			addr: {
+				row,
+				col
+			},
+			group: isColGroupBinding(binding),
+			distance: Math.abs(row - originRow)
+		});
+	}
+	return hits;
+}
+/**
+* 行方向父格推断：
+* 1. 同行向左：先找分组头，否则最近纵向扩展格
+* 2. 上方各行整行扫描：每行先找分组头，再退回任意纵向扩展格
+* 小计（preferGroup）禁止把明细当成父格
+*/
+function inferRowParentCandidate(addr, getBindingAt, options) {
+	const preferGroup = options?.preferGroup === true;
+	const sameRow = pickExpandHit(scanVerticalOnRow(addr.row, addr.col, 0, addr.col, getBindingAt), preferGroup);
+	if (sameRow) return sameRow;
+	for (let row = addr.row - 1; row >= 0; row--) {
+		const found = pickExpandHit(scanVerticalOnRow(row, addr.col, 0, DEFAULT_SCAN_COLS, getBindingAt), preferGroup);
+		if (found) return found;
+	}
+	return null;
+}
+/**
+* 列方向父格推断（与行方向对称）：
+* 1. 同列向上：先找列分组头，否则最近横向扩展格
+* 2. 左侧各列整列扫描：每列先找列分组头
+* 列小计（preferGroup）禁止把交叉格/明细当成列父格
+*/
+function inferColParentCandidate(addr, getBindingAt, options) {
+	const preferGroup = options?.preferGroup === true;
+	const sameCol = pickExpandHit(scanHorizontalOnCol(addr.col, addr.row, 0, addr.row, getBindingAt), preferGroup);
+	if (sameCol) return sameCol;
+	for (let col = addr.col - 1; col >= 0; col--) {
+		const found = pickExpandHit(scanHorizontalOnCol(col, addr.row, 0, DEFAULT_SCAN_ROWS, getBindingAt), preferGroup);
+		if (found) return found;
 	}
 	return null;
 }
+function suggestsColumnSubtotal(above) {
+	if (!above) return false;
+	return isHorizontalExpandBinding(above) || !!above.colParent || above.preset === "cross";
+}
+function suggestsRowSubtotal(left) {
+	if (!left) return false;
+	return isVerticalExpandBinding(left) || !!left.rowParent || left.preset === "cross";
+}
+/**
+* 按预设写入落格父格：明细/分组/交叉双方向推断；小计按「下方行小计 / 右侧列小计」只挂对应轴。
+*/
+function inferParentsForPreset(addr, preset, getBindingAt) {
+	if (preset === "grandTotal") return {};
+	const preferGroup = preset === "subtotal" || preset === "cross";
+	const rowParent = inferRowParentCandidate(addr, getBindingAt, { preferGroup }) ?? void 0;
+	const colParent = inferColParentCandidate(addr, getBindingAt, { preferGroup }) ?? void 0;
+	if (preset !== "subtotal") return {
+		...rowParent ? { rowParent } : {},
+		...colParent ? { colParent } : {}
+	};
+	const above = addr.row > 0 ? getBindingAt({
+		row: addr.row - 1,
+		col: addr.col
+	}) : void 0;
+	const left = addr.col > 0 ? getBindingAt({
+		row: addr.row,
+		col: addr.col - 1
+	}) : void 0;
+	const belowBand = addr.row > 0 && isExpansionBandRow(addr.row - 1, getBindingAt);
+	const rightOfBand = addr.col > 0 && isExpansionBandCol(addr.col - 1, getBindingAt);
+	const columnSubtotal = suggestsColumnSubtotal(above) || rightOfBand && !suggestsRowSubtotal(left);
+	const rowSubtotal = suggestsRowSubtotal(left) || belowBand && !columnSubtotal;
+	const result = {};
+	if (rowSubtotal && rowParent) result.rowParent = rowParent;
+	if (columnSubtotal && colParent) result.colParent = colParent;
+	if (!rowSubtotal && !columnSubtotal) if (belowBand && rowParent) result.rowParent = rowParent;
+	else if (rightOfBand && colParent) result.colParent = colParent;
+	else {
+		if (rowParent) result.rowParent = rowParent;
+		if (colParent) result.colParent = colParent;
+	}
+	return result;
+}
 /** 从绑定字段推断预设；不匹配任何预设时返回 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.expand === "none" && isReductionAggregate(binding.aggregate)) {
+		if (binding.rowParent && binding.colParent) return "cross";
+		if (binding.rowParent || binding.colParent) return "subtotal";
+		return "grandTotal";
+	}
 	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;
@@ -167,9 +312,21 @@ function resolveFieldLabel(datasetId, fieldName, resolveLabel) {
 	if (override) return override;
 	return (bindingCatalog.find((d) => d.id === datasetId)?.fields.find((f) => f.name === fieldName))?.label ?? fieldName;
 }
+/** Binding Placeholder 分段文案（聚合标签 + 字段标签），供徽章分色渲染等场景使用 */
+function formatBindingPlaceholderParts(binding, resolveLabel) {
+	return {
+		tag: AGGREGATE_PLACEHOLDER_TAG[binding.aggregate],
+		label: resolveFieldLabel(binding.dataset, binding.field, resolveLabel)
+	};
+}
 /** Binding Placeholder 中文可读文案（如「分组 · 客户」） */
 function formatBindingPlaceholder(binding, resolveLabel) {
-	return `${AGGREGATE_PLACEHOLDER_TAG[binding.aggregate]} · ${resolveFieldLabel(binding.dataset, binding.field, resolveLabel)}`;
+	const { tag, label } = formatBindingPlaceholderParts(binding, resolveLabel);
+	return `${tag} · ${label}`;
+}
+/** 父格下拉候选文案（如「分组 · 客户 (A2)」） */
+function formatParentCandidateLabel(addr, binding, resolveLabel) {
+	return `${formatBindingPlaceholder(binding, resolveLabel)} (${formatCellAddress(addr)})`;
 }
 //#endregion
-export { REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatCellAddress, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, presetBindingPatch, setBindingCatalog };
+export { REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatBindingPlaceholderParts, formatCellAddress, formatParentCandidateLabel, inferColParentCandidate, inferDropPreset, inferParentsForPreset, inferReportPreset, inferRowParentCandidate, isColGroupBinding, isExpansionBandCol, isExpansionBandRow, isHorizontalExpandBinding, isReductionAggregate, isRowGroupBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, prefersGroupParent, presetBindingPatch, presetStillApplies, setBindingCatalog };

package/dist/report/connector.js

@@ -43,7 +43,7 @@ function toConnectorError(value) {
 function normalizeField(field) {
 	return {
 		name: field.name,
-		label: field.name,
+		label: field.label ?? field.name,
 		type: field.type ?? "string"
 	};
 }

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

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

package/dist/report/export-xlsx.js

@@ -20,11 +20,10 @@ function buildColumnDefs(colWidths) {
 /**
 * 将已填充的 Sheet（Filled Report）导出为保真 XLSX（合并 / 样式 / 行高 / 列宽）。
 * 条件样式颜色已在 renderReport 展开阶段打平进 StylePool（ADR-0001 决策 2）。
-*
-* 与 `exportWorkbookXlsx`（sheet-core）的差异：列宽未进 SheetSnapshot，
-* 只能经 VTable 运行时读取，故这里接收显式列宽并写入 columns 定义。
+* 列宽取自 sheet 模型（`getColWidths`）。
 */
-async function exportFilledReportXlsx(sheet, colWidths) {
+async function exportFilledReportXlsx(sheet) {
+	const widths = [...sheet.getColWidths()];
 	let maxRow = -1;
 	let maxCol = -1;
 	for (const [addr] of sheet.store.entries()) {
@@ -32,17 +31,15 @@ async function exportFilledReportXlsx(sheet, colWidths) {
 		if (addr.col > maxCol) maxCol = addr.col;
 	}
 	for (const [row] of sheet.getRowHeights()) if (row > maxRow) maxRow = row;
-	for (const [col] of colWidths) if (col > maxCol) maxCol = col;
+	for (const [col] of widths) if (col > maxCol) maxCol = col;
 	const rows = maxRow < 0 ? [] : Array.from({ length: maxRow + 1 }, () => Array.from({ length: maxCol + 1 }, () => null));
 	const cells = /* @__PURE__ */ new Map();
 	for (const [addr, data] of sheet.store.entries()) {
 		const row = rows[addr.row];
 		const key = `${addr.row},${addr.col}`;
 		const cell = {};
-		if (data.s != null) {
-			const style = sheet.stylePool.get(data.s);
-			if (style) cell.style = styleToHucre(style);
-		}
+		const style = sheet.getEffectiveStyle(addr);
+		if (style) cell.style = styleToHucre(style);
 		if (data.f != null && data.f !== "") {
 			cell.formula = data.f;
 			if (data.v != null) cell.formulaResult = data.v;
@@ -76,7 +73,7 @@ async function exportFilledReportXlsx(sheet, colWidths) {
 		rows,
 		...cells.size > 0 ? { cells } : {},
 		...sheet.merges.size > 0 ? { merges: sheet.merges.getMerges().map((range) => rangeToHucre(range)) } : {},
-		...colWidths.length > 0 ? { columns: buildColumnDefs(colWidths) } : {}
+		...widths.length > 0 ? { columns: buildColumnDefs(widths) } : {}
 	};
 	const frozen = sheet.frozen;
 	if (frozen.rows > 0 || frozen.cols > 0) writeSheet.freezePane = {

package/dist/report/index.d.ts

@@ -1,5 +1,5 @@
 import { ConditionalOperator, ConditionalRule, DatasetCatalogItem, DatasetField, DatasetRecords, ParamValues, QueryParamDef, QueryParamOption, QueryParamType, ReportAggregate, ReportBinding, ReportExpand, ReportPreset, ReportSort } from "./types.js";
-import { REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatCellAddress, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, presetBindingPatch, setBindingCatalog } from "./binding.js";
+import { InferParentOptions, ListParentCandidateOptions, REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatBindingPlaceholder, formatBindingPlaceholderParts, formatCellAddress, formatParentCandidateLabel, inferColParentCandidate, inferDropPreset, inferParentsForPreset, inferReportPreset, inferRowParentCandidate, isColGroupBinding, isExpansionBandCol, isExpansionBandRow, isHorizontalExpandBinding, isReductionAggregate, isRowGroupBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, parseCellAddress, prefersGroupParent, presetBindingPatch, presetStillApplies, setBindingCatalog } from "./binding.js";
 import { ConditionalEvalContext, evaluateCondition, evaluateConditionalStyle, resolveRuleCompareValue, toComparableNumber } from "./rules/evaluate.js";
 import "./rules/index.js";
 import { buildParamDefs, extractParamIds, resolveBoundDatasetParams } from "./params.js";
@@ -9,4 +9,4 @@ import { renderReport, resolveFilledColWidths } from "./render/index.js";
 import { ConnectionType, ConnectorError, CreateHttpConnectorOptions, DEFAULT_CONNECTION_PORTS, DataConnection, DataConnector, QueryResult, Result, createHttpConnector, resolvePortOnTypeChange } from "./connector.js";
 import { IncompatibleTemplateVersionError, REPORT_TEMPLATE_VERSION, ReportDatasetDef, ReportTemplate, assertCompatibleTemplateVersion, createReportTemplate, fetchTemplateRecords, getBoundDatasetIds, getTemplateDatasets, resolveParamDefaults, resolveTemplateParams } from "./template.js";
 import { parseDateRangeValue, patchParamValues, resolveNumberParamValue } from "./filter-bar.js";
-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, ReportExpand, ReportPreset, ReportSort, ReportTemplate, Result, applyReportPreset, assertCompatibleTemplateVersion, buildColumnDefs, buildParamDefs, createHttpConnector, createReportBinding, createReportTemplate, evaluateCondition, evaluateConditionalStyle, exportFilledReportXlsx, extractParamIds, fetchTemplateRecords, formatBindingPlaceholder, formatCellAddress, getBoundDatasetIds, getTemplateDatasets, inferColParentCandidate, inferDropPreset, inferReportPreset, inferRowParentCandidate, isExpansionBandRow, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, mapFilledColWidths, parseCellAddress, parseDateRangeValue, patchParamValues, presetBindingPatch, pxToExcelColWidth, renderReport, resolveBoundDatasetParams, resolveFilledColWidths, resolveNumberParamValue, resolveParamDefaults, resolvePortOnTypeChange, resolveRuleCompareValue, resolveTemplateParams, setBindingCatalog, toComparableNumber };
+export { type ConditionalEvalContext, ConditionalOperator, ConditionalRule, ConnectionType, ConnectorError, CreateHttpConnectorOptions, DEFAULT_CONNECTION_PORTS, DataConnection, DataConnector, DatasetCatalogItem, DatasetField, DatasetRecords, IncompatibleTemplateVersionError, InferParentOptions, ListParentCandidateOptions, ParamValues, QueryParamDef, QueryParamOption, QueryParamType, QueryResult, REPORT_META_NAMESPACE, REPORT_TEMPLATE_VERSION, ReportAggregate, ReportBinding, ReportColWidthEntry, ReportDatasetDef, ReportExpand, ReportPreset, ReportSort, ReportTemplate, Result, applyReportPreset, assertCompatibleTemplateVersion, buildColumnDefs, buildParamDefs, createHttpConnector, createReportBinding, createReportTemplate, evaluateCondition, evaluateConditionalStyle, exportFilledReportXlsx, extractParamIds, fetchTemplateRecords, formatBindingPlaceholder, formatBindingPlaceholderParts, formatCellAddress, formatParentCandidateLabel, getBoundDatasetIds, getTemplateDatasets, inferColParentCandidate, inferDropPreset, inferParentsForPreset, inferReportPreset, inferRowParentCandidate, isColGroupBinding, isExpansionBandCol, isExpansionBandRow, isHorizontalExpandBinding, isReductionAggregate, isRowGroupBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates, mapFilledColWidths, parseCellAddress, parseDateRangeValue, patchParamValues, prefersGroupParent, presetBindingPatch, presetStillApplies, pxToExcelColWidth, renderReport, resolveBoundDatasetParams, resolveFilledColWidths, resolveNumberParamValue, resolveParamDefaults, resolvePortOnTypeChange, resolveRuleCompareValue, resolveTemplateParams, setBindingCatalog, toComparableNumber };

package/dist/report/render/aggregate.js

@@ -25,7 +25,10 @@ function isRowExpanding(binding) {
 function isColExpanding(binding) {
 	return binding.expand === "right" && (binding.aggregate === "group" || binding.aggregate === "list");
 }
-function rowExpandingAncestors(binding, index) {
+function isReductionAggregate(aggregate) {
+	return aggregate === "sum" || aggregate === "avg" || aggregate === "count" || aggregate === "max" || aggregate === "min";
+}
+function rowExpandingAncestors(binding, index, groupsOnly) {
 	const chain = [];
 	let current = binding.rowParent;
 	while (current) {
@@ -36,9 +39,13 @@ function rowExpandingAncestors(binding, index) {
 		});
 		current = parentBinding?.rowParent;
 	}
-	return chain.filter((item) => isRowExpanding(item.binding));
+	return chain.filter((item) => {
+		if (!isRowExpanding(item.binding)) return false;
+		if (groupsOnly && item.binding.aggregate !== "group") return false;
+		return true;
+	});
 }
-function colExpandingAncestors(binding, index) {
+function colExpandingAncestors(binding, index, groupsOnly) {
 	const chain = [];
 	let current = binding.colParent;
 	while (current) {
@@ -49,7 +56,11 @@ function colExpandingAncestors(binding, index) {
 		});
 		current = parentBinding?.colParent;
 	}
-	return chain.filter((item) => isColExpanding(item.binding));
+	return chain.filter((item) => {
+		if (!isColExpanding(item.binding)) return false;
+		if (groupsOnly && item.binding.aggregate !== "group") return false;
+		return true;
+	});
 }
 function mergeFilters(rowFilter, colFilter) {
 	return {
@@ -61,7 +72,8 @@ function resolveAncestorFilters(binding, placement, index, data) {
 	const rowFilter = {};
 	const colFilter = {};
 	let parentFilter = {};
-	const rowAncestors = rowExpandingAncestors(binding, index);
+	const groupsOnly = isReductionAggregate(binding.aggregate);
+	const rowAncestors = rowExpandingAncestors(binding, index, groupsOnly);
 	for (let i = 0; i < rowAncestors.length; i++) {
 		const ancestor = rowAncestors[i];
 		if (ancestor.binding.dataset !== binding.dataset) continue;
@@ -74,7 +86,7 @@ function resolveAncestorFilters(binding, placement, index, data) {
 		parentFilter = instance.filter;
 	}
 	parentFilter = {};
-	const colAncestors = colExpandingAncestors(binding, index);
+	const colAncestors = colExpandingAncestors(binding, index, groupsOnly);
 	for (let i = 0; i < colAncestors.length; i++) {
 		const ancestor = colAncestors[i];
 		if (ancestor.binding.dataset !== binding.dataset) continue;
@@ -89,8 +101,8 @@ function resolveAncestorFilters(binding, placement, index, data) {
 	return mergeFilters(rowFilter, colFilter);
 }
 function resolveOwnGroupValue(binding, placement, index, data) {
-	const rowAncestors = rowExpandingAncestors(binding, index);
-	const colAncestors = colExpandingAncestors(binding, index);
+	const rowAncestors = rowExpandingAncestors(binding, index, false);
+	const colAncestors = colExpandingAncestors(binding, index, false);
 	let parentFilter = {};
 	for (let i = 0; i < rowAncestors.length; i++) {
 		const ancestor = rowAncestors[i];

package/dist/report/template.d.ts

@@ -3,7 +3,7 @@ import { DataConnection, DataConnector, Result } from "./connector.js";
 import { SheetSnapshot } from "@veltra/sheet-core";
 //#region src/report/template.d.ts
 /**
- * 模板内嵌的数据集定义（Dataset = Data Connection + SQL，ADR-0002 决策 2）。
+ * 模板内嵌的数据集定义
  * 与 playground DatasetDef 同构，connectionId 替换为内嵌的完整连接对象。
  */
 interface ReportDatasetDef {
@@ -16,7 +16,7 @@ interface ReportDatasetDef {
   /** 字段中文名覆盖（name → label）；查看器不消费，随模板序列化往返供设计器还原 */
   fieldOverrides?: Record<string, Partial<Pick<DatasetField, 'label'>>>;
 }
-/** 当前支持的报表模板版本（ADR-0005 决策 4） */
+/** 当前支持的报表模板版本 */
 declare const REPORT_TEMPLATE_VERSION = 1;
 /** 模板版本不兼容时抛出 */
 declare class IncompatibleTemplateVersionError extends Error {
@@ -25,8 +25,9 @@ declare class IncompatibleTemplateVersionError extends Error {
 /**
  * 自包含 Report Template：SheetSnapshot + 内嵌数据集定义 + 版本段。
  * 查看器仅凭 `template` + `connector` 即可完成「参数提取 → 取数 → 展开渲染」闭环；
- * 模板可 JSON 序列化流转（凭据随之流转，持久化与安全存储由下游负责，ADR-0003 决策 4）。
+ * 模板可 JSON 序列化流转。
  *
+ * `colWidths` 继承自 `SheetSnapshot.colWidths`（模型列索引 → 像素）。
  * 注意：`Sheet.snapshot()` 不产生 `datasets` / `version` 字段，经 `restore()`/`snapshot()` 往返会丢失，
  * 由设计器 `getTemplate()` 在吐出快照时重新附加。
  */
@@ -37,7 +38,10 @@ interface ReportTemplate extends SheetSnapshot {
 }
 /** 载入模板前校验版本：缺失或高于当前支持版本时抛可读错误 */
 declare function assertCompatibleTemplateVersion(template: ReportTemplate): void;
-/** 由工作簿快照构造带版本段的 Report Template */
+/**
+ * 由工作簿快照构造带版本段的 Report Template。
+ * `colWidths` 随 `snapshot` 展开（已在 `SheetSnapshot.colWidths`）。
+ */
 declare function createReportTemplate(snapshot: SheetSnapshot, datasets?: ReportDatasetDef[]): ReportTemplate;
 /** 读取模板内嵌的数据集定义（旧模板未内嵌时回退空数组） */
 declare function getTemplateDatasets(template: ReportTemplate): ReportDatasetDef[];

package/dist/report/template.js

@@ -1,7 +1,7 @@
 import "./binding.js";
 import { buildParamDefs } from "./params.js";
 //#region src/report/template.ts
-/** 当前支持的报表模板版本（ADR-0005 决策 4） */
+/** 当前支持的报表模板版本 */
 const REPORT_TEMPLATE_VERSION = 1;
 /** 模板版本不兼容时抛出 */
 var IncompatibleTemplateVersionError = class extends Error {
@@ -15,7 +15,10 @@ function assertCompatibleTemplateVersion(template) {
 	if (template.version === void 0) throw new IncompatibleTemplateVersionError("报表模板缺少 version 字段，请在设计器中重建模板后重试");
 	if (template.version > 1) throw new IncompatibleTemplateVersionError(`报表模板版本 ${template.version} 高于当前支持的版本 1，请升级组件库后重试`);
 }
-/** 由工作簿快照构造带版本段的 Report Template */
+/**
+* 由工作簿快照构造带版本段的 Report Template。
+* `colWidths` 随 `snapshot` 展开（已在 `SheetSnapshot.colWidths`）。
+*/
 function createReportTemplate(snapshot, datasets) {
 	return {
 		...snapshot,

package/dist/tools/apply-style.js

@@ -0,0 +1,29 @@
+//#region src/tools/apply-style.ts
+/**
+* 按选区相对渲染网格的跨度判定样式写入目标（对齐 Excel）：
+* - 跨满全部列且未跨满全部行 → 行默认样式（rowStyles）
+* - 跨满全部行且未跨满全部列 → 列默认样式（colStyles）
+* - 其余（含全表 / 局部）→ 单元格样式
+*/
+function classifySelectionStyleTarget(range, renderRows, renderCols) {
+	const cols = Math.max(renderCols, 1);
+	const rows = Math.max(renderRows, 1);
+	const spansAllCols = range.start.col === 0 && range.end.col >= cols - 1;
+	const spansAllRows = range.start.row === 0 && range.end.row >= rows - 1;
+	if (spansAllCols && !spansAllRows) return "row";
+	if (spansAllRows && !spansAllCols) return "col";
+	return "cell";
+}
+/** 整行/整列选区 → set-axis-style 写入项（partial）或清除项（clear） */
+function axisStyleItemsForRange(range, axis, patch) {
+	const start = axis === "row" ? range.start.row : range.start.col;
+	const end = axis === "row" ? range.end.row : range.end.col;
+	const items = [];
+	for (let index = start; index <= end; index++) items.push({
+		index,
+		...patch
+	});
+	return items;
+}
+//#endregion
+export { axisStyleItemsForRange, classifySelectionStyleTarget };