@veltra/sheet 2.1.1 → 2.2.0

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

package/dist/report/render/builder.js

@@ -0,0 +1,139 @@
+import { physicalColSpan, physicalRowSpan } from "./coordinate.js";
+import { AggregateIndex, resolvePlacementRecord, resolvePlacementValue } from "./aggregate.js";
+import { StyleResolver } from "./style-resolver.js";
+import { cellKey } from "@veltra/sheet-core";
+//#region src/report/render/builder.ts
+function toCellValue(value) {
+	if (value === null || value === void 0) return { v: "" };
+	if (typeof value === "number" && !Number.isNaN(value)) return {
+		v: value,
+		t: "n"
+	};
+	if (typeof value === "boolean") return {
+		v: value,
+		t: "b"
+	};
+	if (typeof value === "string") return {
+		v: value,
+		t: "s"
+	};
+	if (value instanceof Date) return {
+		v: value.toISOString().slice(0, 10),
+		t: "s"
+	};
+	return {
+		v: JSON.stringify(value),
+		t: "s"
+	};
+}
+function rangeCells(range) {
+	const cells = [];
+	for (let row = range.start.row; row <= range.end.row; row++) for (let col = range.start.col; col <= range.end.col; col++) cells.push({
+		row,
+		col
+	});
+	return cells;
+}
+function placementSourceValue(placement, template, index, data, aggregateIndex) {
+	if (placement.binding) return resolvePlacementValue(placement, index, data, aggregateIndex);
+	return index.cellAt(placement.logical)?.v;
+}
+function colWidthSourceLogicalCol(placement) {
+	const binding = placement.binding;
+	if (binding?.colParent) return binding.colParent.col;
+	return placement.logical.col;
+}
+/**
+* 将模板列宽映射到填充报表物理列：横向展开列继承列方向父格所在模板列宽。
+*/
+function mapFilledColWidths(templateColWidths, layout, _index) {
+	if (templateColWidths.length === 0 || layout.colCount === 0) return [];
+	const widthByTemplateCol = /* @__PURE__ */ new Map();
+	for (const [col, width] of templateColWidths) widthByTemplateCol.set(col, width);
+	const physicalWidths = /* @__PURE__ */ new Map();
+	for (const placement of layout.placements) {
+		const sourceCol = colWidthSourceLogicalCol(placement);
+		const width = widthByTemplateCol.get(sourceCol);
+		if (width === void 0) continue;
+		const startCol = placement.physical.start.col;
+		const endCol = placement.physical.end.col;
+		for (let col = startCol; col <= endCol; col++) physicalWidths.set(col, width);
+	}
+	return [...physicalWidths.entries()].sort((a, b) => a[0] - b[0]);
+}
+function placementEvalContext(placement, value, template, index, data, aggregateIndex) {
+	const binding = placement.binding;
+	return {
+		cellValue: value,
+		bindingField: binding?.field ?? "",
+		record: binding ? resolvePlacementRecord(placement, index, data, aggregateIndex) : void 0
+	};
+}
+function collectRowConditionalStyles(layout, template, index, data, styles) {
+	const aggregateIndex = new AggregateIndex(data);
+	for (const placement of layout.placements) {
+		const binding = placement.binding;
+		if (!binding?.conditionalRules?.some((rule) => rule.scope === "row")) continue;
+		const ctx = placementEvalContext(placement, placementSourceValue(placement, template, index, data, aggregateIndex), template, index, data, aggregateIndex);
+		for (let row = placement.physical.start.row; row <= placement.physical.end.row; row++) styles.collectRowStyle(row, ctx, binding.conditionalRules);
+	}
+}
+/** 由扩展坐标布局组装 Filled Report 快照 */
+function buildFilledReport(template, index, layout, data) {
+	const styles = new StyleResolver(template);
+	collectRowConditionalStyles(layout, template, index, data, styles);
+	const aggregateIndex = new AggregateIndex(data);
+	const cells = [];
+	const merges = [...layout.mappedMerges];
+	const mergeKeys = new Set(merges.map((m) => cellKey(m.start)));
+	const pushMerge = (range) => {
+		const key = cellKey(range.start);
+		if (mergeKeys.has(key)) return;
+		mergeKeys.add(key);
+		merges.push(range);
+	};
+	const resolveStyleId = (placement, templateRow, templateCol, value, physicalRow) => {
+		const binding = placement.binding;
+		const ctx = placementEvalContext(placement, value, template, index, data, aggregateIndex);
+		const baseStyleId = binding ? styles.resolveCell(templateRow, templateCol, ctx, binding.conditionalRules) : styles.resolveStatic(templateRow, templateCol);
+		return styles.mergeRowStyle(baseStyleId, physicalRow);
+	};
+	for (const placement of layout.placements) {
+		const value = placementSourceValue(placement, template, index, data, aggregateIndex);
+		const { row: templateRow, col: templateCol } = placement.logical;
+		const rowSpan = physicalRowSpan(placement);
+		const colSpan = physicalColSpan(placement);
+		if (placement.mergeSpan && (rowSpan > 1 || colSpan > 1)) {
+			const item = {
+				row: placement.physical.start.row,
+				col: placement.physical.start.col,
+				...toCellValue(value)
+			};
+			const styleId = resolveStyleId(placement, templateRow, templateCol, value, placement.physical.start.row);
+			if (styleId !== void 0) item.s = styleId;
+			cells.push(item);
+			if (rowSpan > 1 || colSpan > 1) pushMerge(placement.physical);
+			continue;
+		}
+		for (const pos of rangeCells(placement.physical)) {
+			const item = {
+				row: pos.row,
+				col: pos.col,
+				...toCellValue(value)
+			};
+			const styleId = resolveStyleId(placement, templateRow, templateCol, value, pos.row);
+			if (styleId !== void 0) item.s = styleId;
+			cells.push(item);
+		}
+	}
+	return {
+		cells,
+		styles: styles.snapshot(),
+		merges,
+		frozen: template.frozen,
+		rows: layout.rowCount,
+		cols: Math.max(layout.colCount, template.cols)
+	};
+}
+//#endregion
+export { buildFilledReport, mapFilledColWidths };

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

@@ -0,0 +1,25 @@
+import { ReportBinding } from "../types.js";
+import "./template-index.js";
+import { CellAddress, CellRange } from "@veltra/sheet-core";
+//#region src/report/render/coordinate.d.ts
+/** 逻辑格 → 物理区间映射项（纯几何，不含取值） */
+interface PhysicalPlacement {
+  logical: CellAddress;
+  physical: CellRange;
+  rowPath: readonly number[];
+  colPath: readonly number[];
+  mergeSpan: boolean;
+  binding?: ReportBinding;
+  /** `list` 明细实例下标；非 list 时为 0 */
+  listIndex: number;
+}
+/** 扩展坐标系计算结果 */
+interface ExpansionLayout {
+  rowCount: number;
+  colCount: number;
+  placements: PhysicalPlacement[];
+  /** 模板合并区域映射到物理网格后的区间 */
+  mappedMerges: CellRange[];
+}
+//#endregion
+export { ExpansionLayout, PhysicalPlacement };