@veltra/sheet 2.0.1 → 2.2.0

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 };

package/dist/report/export-xlsx.js

@@ -0,0 +1,95 @@
+import { rangeToHucre, styleToHucre } from "@veltra/sheet-core/core/io/export";
+import { writeXlsx } from "hucre/xlsx";
+//#region src/report/export-xlsx.ts
+/** 像素 → Excel points */
+function pxToPt(px) {
+	return px * .75;
+}
+/** VTable 像素列宽 → Excel 字符宽度（近似换算） */
+function pxToExcelColWidth(px) {
+	return Math.max(1, Math.round((px - 5) / 7));
+}
+/** 从列宽条目构建 hucre ColumnDef */
+function buildColumnDefs(colWidths) {
+	if (colWidths.length === 0) return [];
+	const maxCol = Math.max(...colWidths.map(([col]) => col));
+	const columns = Array.from({ length: maxCol + 1 }, () => ({}));
+	for (const [col, width] of colWidths) columns[col] = { width: pxToExcelColWidth(width) };
+	return columns;
+}
+/**
+* 将已填充的 Sheet（Filled Report）导出为保真 XLSX（合并 / 样式 / 行高 / 列宽）。
+* 条件样式颜色已在 renderReport 展开阶段打平进 StylePool（ADR-0001 决策 2）。
+*
+* 与 `exportWorkbookXlsx`（sheet-core）的差异：列宽未进 SheetSnapshot，
+* 只能经 VTable 运行时读取，故这里接收显式列宽并写入 columns 定义。
+*/
+async function exportFilledReportXlsx(sheet, colWidths) {
+	let maxRow = -1;
+	let maxCol = -1;
+	for (const [addr] of sheet.store.entries()) {
+		if (addr.row > maxRow) maxRow = addr.row;
+		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;
+	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);
+		}
+		if (data.f != null && data.f !== "") {
+			cell.formula = data.f;
+			if (data.v != null) cell.formulaResult = data.v;
+			row[addr.col] = data.v ?? null;
+			cells.set(key, cell);
+			continue;
+		}
+		if (data.t === "e") {
+			cell.value = data.v;
+			cell.type = "error";
+			row[addr.col] = null;
+			cells.set(key, cell);
+			continue;
+		}
+		if (data.t === "d") {
+			cell.value = data.v;
+			cell.type = "number";
+			cell.style = {
+				...cell.style,
+				numFmt: "yyyy-mm-dd"
+			};
+			row[addr.col] = null;
+			cells.set(key, cell);
+			continue;
+		}
+		row[addr.col] = data.v ?? null;
+		if (Object.keys(cell).length > 0) cells.set(key, cell);
+	}
+	const writeSheet = {
+		name: sheet.name || "报表",
+		rows,
+		...cells.size > 0 ? { cells } : {},
+		...sheet.merges.size > 0 ? { merges: sheet.merges.getMerges().map((range) => rangeToHucre(range)) } : {},
+		...colWidths.length > 0 ? { columns: buildColumnDefs(colWidths) } : {}
+	};
+	const frozen = sheet.frozen;
+	if (frozen.rows > 0 || frozen.cols > 0) writeSheet.freezePane = {
+		rows: frozen.rows,
+		columns: frozen.cols
+	};
+	const rowDefs = /* @__PURE__ */ new Map();
+	for (const [row, height] of sheet.getRowHeights()) rowDefs.set(row, { height: pxToPt(height) });
+	if (rowDefs.size > 0) writeSheet.rowDefs = rowDefs;
+	return writeXlsx({
+		sheets: [writeSheet],
+		activeSheet: 0
+	});
+}
+//#endregion
+export { buildColumnDefs, exportFilledReportXlsx, pxToExcelColWidth };

package/dist/report/filter-bar.d.ts

@@ -0,0 +1,10 @@
+import { ParamValues } from "./types.js";
+//#region src/report/filter-bar.d.ts
+/** 将运行时 date-range 参数值规范为 [from, to] 字符串元组 */
+declare function parseDateRangeValue(raw: unknown): [string, string];
+/** 将运行时 number 参数值规范为 UNumberInput 可接受的 number | undefined */
+declare function resolveNumberParamValue(raw: unknown): number | undefined;
+/** 合并单参数变更，保持其余参数值不变 */
+declare function patchParamValues(values: ParamValues, id: string, value: unknown): ParamValues;
+//#endregion
+export { parseDateRangeValue, patchParamValues, resolveNumberParamValue };

package/dist/report/filter-bar.js

@@ -0,0 +1,31 @@
+//#region src/report/filter-bar.ts
+function toParamString(value) {
+	if (value == null || value === "") return "";
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+	return "";
+}
+/** 将运行时 date-range 参数值规范为 [from, to] 字符串元组 */
+function parseDateRangeValue(raw) {
+	if (Array.isArray(raw)) return [toParamString(raw[0]), toParamString(raw[1])];
+	if (raw && typeof raw === "object") {
+		const obj = raw;
+		return [toParamString(obj.from ?? obj.start), toParamString(obj.to ?? obj.end)];
+	}
+	return ["", ""];
+}
+/** 将运行时 number 参数值规范为 UNumberInput 可接受的 number | undefined */
+function resolveNumberParamValue(raw) {
+	if (raw === "" || raw == null) return void 0;
+	if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+/** 合并单参数变更，保持其余参数值不变 */
+function patchParamValues(values, id, value) {
+	return {
+		...values,
+		[id]: value
+	};
+}
+//#endregion
+export { parseDateRangeValue, patchParamValues, resolveNumberParamValue };

package/dist/report/index.d.ts

@@ -0,0 +1,12 @@
+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 { ConditionalEvalContext, evaluateCondition, evaluateConditionalStyle, resolveRuleCompareValue, toComparableNumber } from "./rules/evaluate.js";
+import "./rules/index.js";
+import { buildParamDefs, extractParamIds, resolveBoundDatasetParams } from "./params.js";
+import { ReportColWidthEntry, buildColumnDefs, exportFilledReportXlsx, pxToExcelColWidth } from "./export-xlsx.js";
+import { mapFilledColWidths } from "./render/builder.js";
+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 };

package/dist/report/params.d.ts

@@ -0,0 +1,13 @@
+import { QueryParamDef } from "./types.js";
+//#region src/report/params.d.ts
+/** 从 SQL 提取 `${param}` 占位符 id（ADR-0002 决策 2：前端纯函数） */
+declare function extractParamIds(sql: string): string[];
+/**
+ * 从 SQL 构建查询参数定义：提取 `${param}` 占位符 + 上下文类型推断，
+ * 再叠加数据集编辑器的元数据覆盖（label / 类型 / 默认值 / 选项）。
+ */
+declare function buildParamDefs(sql: string, overrides?: Record<string, Partial<Omit<QueryParamDef, 'id'>>>): QueryParamDef[];
+/** 按绑定的数据集 id 合并查询参数（同名参数先见为准） */
+declare function resolveBoundDatasetParams(queryParams: QueryParamDef[], boundDatasetIds: readonly string[], getDatasetParams: (datasetId: string) => QueryParamDef[]): QueryParamDef[];
+//#endregion
+export { buildParamDefs, extractParamIds, resolveBoundDatasetParams };

package/dist/report/params.js

@@ -0,0 +1,61 @@
+//#region src/report/params.ts
+/** 从 SQL 提取 `${param}` 占位符 id（ADR-0002 决策 2：前端纯函数） */
+function extractParamIds(sql) {
+	const ids = [];
+	const re = /\$\{([^}]+)\}/g;
+	let match;
+	while ((match = re.exec(sql)) !== null) {
+		const id = match[1].trim();
+		if (id && !ids.includes(id)) ids.push(id);
+	}
+	return ids;
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** 从 SQL 上下文推断参数控件类型（BETWEEN/LIKE/数值比较） */
+function inferParamTypeFromSql(sql, paramId) {
+	if (new RegExp(`\\bBETWEEN\\s+\\$\\{${escapeRegExp(paramId)}\\}(?!\\s+AND)`, "i").test(sql)) return "date-range";
+	const pairMatch = new RegExp(`\\bBETWEEN\\s+\\$\\{${escapeRegExp(paramId)}\\}\\s+AND\\s+\\$\\{([^}]+)\\}`, "i").exec(sql);
+	if (pairMatch && pairMatch[1].trim() !== paramId) return "date";
+	if (new RegExp(`\\bLIKE\\s+\\$\\{${escapeRegExp(paramId)}\\}`, "i").test(sql)) return "text";
+	if (new RegExp(`[<>=]+\\s+\\$\\{${escapeRegExp(paramId)}\\}|\\$\\{${escapeRegExp(paramId)}\\}\\s*[<>=]+`, "i").test(sql)) return "number";
+	return "text";
+}
+function defaultValueForType(type) {
+	switch (type) {
+		case "number": return 0;
+		case "date-range": return ["", ""];
+		case "select": return "";
+		default: return "";
+	}
+}
+/**
+* 从 SQL 构建查询参数定义：提取 `${param}` 占位符 + 上下文类型推断，
+* 再叠加数据集编辑器的元数据覆盖（label / 类型 / 默认值 / 选项）。
+*/
+function buildParamDefs(sql, overrides) {
+	return extractParamIds(sql).map((id) => {
+		const inferred = inferParamTypeFromSql(sql, id);
+		const override = overrides?.[id];
+		return {
+			id,
+			label: override?.label ?? id,
+			type: override?.type ?? inferred,
+			defaultValue: override?.defaultValue ?? defaultValueForType(override?.type ?? inferred),
+			options: override?.options
+		};
+	});
+}
+/** 按绑定的数据集 id 合并查询参数（同名参数先见为准） */
+function resolveBoundDatasetParams(queryParams, boundDatasetIds, getDatasetParams) {
+	const map = /* @__PURE__ */ new Map();
+	for (const datasetId of boundDatasetIds) {
+		const params = getDatasetParams(datasetId);
+		for (const param of params) if (!map.has(param.id)) map.set(param.id, param);
+	}
+	if (map.size > 0) return Array.from(map.values());
+	return queryParams;
+}
+//#endregion
+export { buildParamDefs, extractParamIds, resolveBoundDatasetParams };

package/dist/report/render/aggregate.js

@@ -0,0 +1,157 @@
+import { enumerateExpansionInstances } from "./coordinate.js";
+//#region src/report/render/aggregate.ts
+function filterRows(rows, filter) {
+	if (Object.keys(filter).length === 0) return rows;
+	return rows.filter((row) => Object.entries(filter).every(([field, value]) => row[field] === value));
+}
+/** 对数值集求聚合；`avg` 空集返回 `undefined`，`sum` 空集仍为 `0` */
+function aggregateField(rows, field, aggregate) {
+	if (aggregate === "count") return rows.length;
+	if (aggregate === "list" || aggregate === "group") return rows[0]?.[field];
+	const numbers = rows.map((row) => row[field]).map((value) => typeof value === "number" ? value : Number(value)).filter((value) => Number.isFinite(value));
+	if (numbers.length === 0) {
+		if (aggregate === "avg") return void 0;
+		return 0;
+	}
+	const sum = numbers.reduce((acc, value) => acc + value, 0);
+	if (aggregate === "avg") return sum / numbers.length;
+	if (aggregate === "max") return Math.max(...numbers);
+	if (aggregate === "min") return Math.min(...numbers);
+	return sum;
+}
+function isRowExpanding(binding) {
+	return binding.expand === "down" && (binding.aggregate === "group" || binding.aggregate === "list");
+}
+function isColExpanding(binding) {
+	return binding.expand === "right" && (binding.aggregate === "group" || binding.aggregate === "list");
+}
+function rowExpandingAncestors(binding, index) {
+	const chain = [];
+	let current = binding.rowParent;
+	while (current) {
+		const parentBinding = index.bindingAt(current);
+		if (parentBinding) chain.unshift({
+			addr: current,
+			binding: parentBinding
+		});
+		current = parentBinding?.rowParent;
+	}
+	return chain.filter((item) => isRowExpanding(item.binding));
+}
+function colExpandingAncestors(binding, index) {
+	const chain = [];
+	let current = binding.colParent;
+	while (current) {
+		const parentBinding = index.bindingAt(current);
+		if (parentBinding) chain.unshift({
+			addr: current,
+			binding: parentBinding
+		});
+		current = parentBinding?.colParent;
+	}
+	return chain.filter((item) => isColExpanding(item.binding));
+}
+function mergeFilters(rowFilter, colFilter) {
+	return {
+		...rowFilter,
+		...colFilter
+	};
+}
+function resolveAncestorFilters(binding, placement, index, data) {
+	const rowFilter = {};
+	const colFilter = {};
+	let parentFilter = {};
+	const rowAncestors = rowExpandingAncestors(binding, index);
+	for (let i = 0; i < rowAncestors.length; i++) {
+		const ancestor = rowAncestors[i];
+		if (ancestor.binding.dataset !== binding.dataset) continue;
+		const instances = enumerateExpansionInstances(ancestor.binding, data, parentFilter);
+		const pathIndex = placement.rowPath[i];
+		if (pathIndex === void 0) continue;
+		const instance = instances[pathIndex];
+		if (!instance) continue;
+		Object.assign(rowFilter, instance.filter);
+		parentFilter = instance.filter;
+	}
+	parentFilter = {};
+	const colAncestors = colExpandingAncestors(binding, index);
+	for (let i = 0; i < colAncestors.length; i++) {
+		const ancestor = colAncestors[i];
+		if (ancestor.binding.dataset !== binding.dataset) continue;
+		const instances = enumerateExpansionInstances(ancestor.binding, data, parentFilter);
+		const pathIndex = placement.colPath[i];
+		if (pathIndex === void 0) continue;
+		const instance = instances[pathIndex];
+		if (!instance) continue;
+		Object.assign(colFilter, instance.filter);
+		parentFilter = instance.filter;
+	}
+	return mergeFilters(rowFilter, colFilter);
+}
+function resolveOwnGroupValue(binding, placement, index, data) {
+	const rowAncestors = rowExpandingAncestors(binding, index);
+	const colAncestors = colExpandingAncestors(binding, index);
+	let parentFilter = {};
+	for (let i = 0; i < rowAncestors.length; i++) {
+		const ancestor = rowAncestors[i];
+		if (ancestor.binding.dataset !== binding.dataset) continue;
+		const instances = enumerateExpansionInstances(ancestor.binding, data, parentFilter);
+		const pathIndex = placement.rowPath[i];
+		if (pathIndex === void 0) continue;
+		const instance = instances[pathIndex];
+		if (instance) parentFilter = instance.filter;
+	}
+	for (let i = 0; i < colAncestors.length; i++) {
+		const ancestor = colAncestors[i];
+		if (ancestor.binding.dataset !== binding.dataset) continue;
+		const instances = enumerateExpansionInstances(ancestor.binding, data, parentFilter);
+		const pathIndex = placement.colPath[i];
+		if (pathIndex === void 0) continue;
+		const instance = instances[pathIndex];
+		if (instance) parentFilter = instance.filter;
+	}
+	const instances = enumerateExpansionInstances(binding, data, parentFilter);
+	const pathIndex = isRowExpanding(binding) ? placement.rowPath.at(-1) : placement.colPath.at(-1);
+	if (pathIndex === void 0) return void 0;
+	return instances[pathIndex]?.value;
+}
+/** 按分组字段建索引，避免交叉展开重复 filterRows */
+var AggregateIndex = class {
+	datasets = /* @__PURE__ */ new Map();
+	filterCache = /* @__PURE__ */ new Map();
+	constructor(data) {
+		for (const [datasetId, rows] of Object.entries(data)) this.datasets.set(datasetId, rows);
+	}
+	rowsFor(dataset, filter) {
+		const cacheKey = `${dataset}:${JSON.stringify(filter)}`;
+		const cached = this.filterCache.get(cacheKey);
+		if (cached) return cached;
+		const rows = filterRows(this.datasets.get(dataset) ?? [], filter);
+		this.filterCache.set(cacheKey, rows);
+		return rows;
+	}
+	aggregate(dataset, filter, field, aggregate) {
+		const rows = this.rowsFor(dataset, filter);
+		if (aggregate === "list") return rows[0]?.[field];
+		return aggregateField(rows, field, aggregate);
+	}
+};
+/** 解析单个物理落点的绑定取值 */
+function resolvePlacementValue(placement, index, data, aggregateIndex) {
+	const binding = placement.binding;
+	if (!binding) return void 0;
+	const filter = resolveAncestorFilters(binding, placement, index, data);
+	const rows = aggregateIndex.rowsFor(binding.dataset, filter);
+	if (binding.aggregate === "group") return filter[binding.field] ?? resolveOwnGroupValue(binding, placement, index, data);
+	if (binding.aggregate === "list") return rows[placement.listIndex]?.[binding.field];
+	return aggregateField(rows, binding.field, binding.aggregate);
+}
+/** 解析 `list` 明细落点对应的源数据行；非 list 绑定无单条记录上下文 */
+function resolvePlacementRecord(placement, index, data, aggregateIndex) {
+	const binding = placement.binding;
+	if (!binding || binding.aggregate !== "list") return void 0;
+	const filter = resolveAncestorFilters(binding, placement, index, data);
+	return aggregateIndex.rowsFor(binding.dataset, filter)[placement.listIndex];
+}
+//#endregion
+export { AggregateIndex, aggregateField, resolvePlacementRecord, resolvePlacementValue };

package/dist/report/render/builder.d.ts

@@ -0,0 +1,12 @@
+import "../types.js";
+import { ReportColWidthEntry } from "../export-xlsx.js";
+import { TemplateIndex } from "./template-index.js";
+import { ExpansionLayout } from "./coordinate.js";
+import { SheetSnapshot } from "@veltra/sheet-core";
+//#region src/report/render/builder.d.ts
+/**
+ * 将模板列宽映射到填充报表物理列：横向展开列继承列方向父格所在模板列宽。
+ */
+declare function mapFilledColWidths(templateColWidths: ReadonlyArray<ReportColWidthEntry>, layout: ExpansionLayout, _index: TemplateIndex): ReportColWidthEntry[];
+//#endregion
+export { mapFilledColWidths };