@veltra/sheet 2.1.1 → 2.3.0

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

@@ -0,0 +1,14 @@
+import { DatasetRecords } from "../types.js";
+import { ReportColWidthEntry } from "../export-xlsx.js";
+import { mapFilledColWidths } from "./builder.js";
+import { SheetSnapshot } from "@veltra/sheet-core";
+//#region src/report/render/index.d.ts
+/**
+ * 将 Report Template 按 Dataset 渲染为 Filled Report 快照。
+ * 基于显式展开方向与父格关系展开，不做坐标推断。
+ */
+declare function renderReport(template: SheetSnapshot, data: DatasetRecords): SheetSnapshot;
+/** 将设计态模板列宽映射为填充报表物理列宽（横向展开列继承父格列宽） */
+declare function resolveFilledColWidths(template: SheetSnapshot, data: DatasetRecords, templateColWidths: ReadonlyArray<ReportColWidthEntry>): ReportColWidthEntry[];
+//#endregion
+export { mapFilledColWidths, renderReport, resolveFilledColWidths };

package/dist/report/render/index.js

@@ -0,0 +1,21 @@
+import { buildTemplateIndex } from "./template-index.js";
+import { computeExpansionLayout } from "./coordinate.js";
+import { buildFilledReport, mapFilledColWidths } from "./builder.js";
+//#region src/report/render/index.ts
+/**
+* 将 Report Template 按 Dataset 渲染为 Filled Report 快照。
+* 基于显式展开方向与父格关系展开，不做坐标推断。
+*/
+function renderReport(template, data) {
+	const index = buildTemplateIndex(template);
+	const layout = computeExpansionLayout(index, data);
+	return buildFilledReport(template, index, layout, data);
+}
+/** 将设计态模板列宽映射为填充报表物理列宽（横向展开列继承父格列宽） */
+function resolveFilledColWidths(template, data, templateColWidths) {
+	const index = buildTemplateIndex(template);
+	const layout = computeExpansionLayout(index, data);
+	return mapFilledColWidths(templateColWidths, layout, index);
+}
+//#endregion
+export { mapFilledColWidths, renderReport, resolveFilledColWidths };

package/dist/report/render/style-resolver.js

@@ -0,0 +1,50 @@
+import { evaluateConditionalStyle } from "../rules/evaluate.js";
+import { StylePool } from "@veltra/sheet-core";
+import { mergeCellStyle } from "@veltra/sheet-core/core/command/set-cell-style";
+//#region src/report/render/style-resolver.ts
+/** 静态样式经 StylePool 复用 + 条件样式打平（含 `scope: 'row'` 两阶段叠加） */
+var StyleResolver = class {
+	template;
+	pool = new StylePool();
+	rowStyleByPhysRow = /* @__PURE__ */ new Map();
+	constructor(template) {
+		this.template = template;
+		if (template.styles.length > 0) this.pool.restore(template.styles);
+	}
+	/** 收集 `scope: 'row'` 命中样式，按物理行累加（须在输出静态格之前完成） */
+	collectRowStyle(physicalRow, ctx, rules) {
+		if (!rules?.some((rule) => rule.scope === "row")) return;
+		const patch = evaluateConditionalStyle(ctx, void 0, rules, "row");
+		if (!patch) return;
+		const existing = this.rowStyleByPhysRow.get(physicalRow);
+		this.rowStyleByPhysRow.set(physicalRow, mergeCellStyle(existing, patch) ?? patch);
+	}
+	/** 解析模板格基础样式 + `scope: 'cell'` 条件样式 */
+	resolveCell(templateRow, templateCol, ctx, rules) {
+		const tpl = this.template.cells.find((c) => c.row === templateRow && c.col === templateCol);
+		const baseStyle = tpl?.s !== void 0 ? this.pool.get(tpl.s) : void 0;
+		const merged = evaluateConditionalStyle(ctx, baseStyle, rules, "cell");
+		if (!merged) return tpl?.s;
+		if (merged === baseStyle) return tpl?.s;
+		return this.pool.intern(merged);
+	}
+	/** 无绑定的静态格：仅模板样式 */
+	resolveStatic(templateRow, templateCol) {
+		return this.template.cells.find((c) => c.row === templateRow && c.col === templateCol)?.s;
+	}
+	/** 将行级样式叠加到格级样式 id */
+	mergeRowStyle(styleId, physicalRow) {
+		const rowPatch = this.rowStyleByPhysRow.get(physicalRow);
+		if (!rowPatch) return styleId;
+		const base = styleId !== void 0 ? this.pool.get(styleId) : void 0;
+		const merged = mergeCellStyle(base, rowPatch);
+		if (!merged) return styleId;
+		if (merged === base) return styleId;
+		return this.pool.intern(merged);
+	}
+	snapshot() {
+		return this.pool.snapshot();
+	}
+};
+//#endregion
+export { StyleResolver };

package/dist/report/render/template-index.d.ts

@@ -0,0 +1,24 @@
+import { ReportBinding } from "../types.js";
+import { CellAddress, CellRange, CellSnapshotItem, SheetSnapshot } from "@veltra/sheet-core";
+//#region src/report/render/template-index.d.ts
+interface IndexedBinding {
+  addr: CellAddress;
+  binding: ReportBinding;
+}
+/** 模板一次性索引：绑定直查、静态格直查、行/列父子树 */
+interface TemplateIndex {
+  readonly bindings: ReadonlyMap<number, IndexedBinding>;
+  readonly staticCells: ReadonlyMap<number, CellSnapshotItem>;
+  readonly rowChildren: ReadonlyMap<number, readonly CellAddress[]>;
+  readonly colChildren: ReadonlyMap<number, readonly CellAddress[]>;
+  readonly logicalRows: readonly number[];
+  readonly logicalCols: readonly number[];
+  readonly merges: readonly CellRange[];
+  bindingAt(addr: CellAddress): ReportBinding | undefined;
+  cellAt(addr: CellAddress): CellSnapshotItem | undefined;
+  bindingsOnRow(row: number): readonly IndexedBinding[];
+  bindingsOnCol(col: number): readonly IndexedBinding[];
+  isBindingAddr(addr: CellAddress): boolean;
+}
+//#endregion
+export { IndexedBinding, TemplateIndex };

package/dist/report/render/template-index.js

@@ -0,0 +1,137 @@
+import { formatCellAddress } from "../binding.js";
+import { cellKey } from "@veltra/sheet-core";
+//#region src/report/render/template-index.ts
+/** 模板结构约束违反时抛出（附 A1 标签） */
+var TemplateStructureError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "TemplateStructureError";
+	}
+};
+function addressesEqual(a, b) {
+	return a.row === b.row && a.col === b.col;
+}
+function collectLogicalRows(template) {
+	const rows = /* @__PURE__ */ new Set();
+	for (const cell of template.cells) rows.add(cell.row);
+	for (const item of template.meta ?? []) rows.add(item.row);
+	return [...rows].sort((a, b) => a - b);
+}
+function collectLogicalCols(template) {
+	const cols = /* @__PURE__ */ new Set();
+	for (const cell of template.cells) cols.add(cell.col);
+	for (const item of template.meta ?? []) cols.add(item.col);
+	return [...cols].sort((a, b) => a - b);
+}
+function validateParentExists(addr, parent, bindings, direction) {
+	if (!parent) return;
+	const label = formatCellAddress(addr);
+	const parentLabel = formatCellAddress(parent);
+	if (!bindings.has(cellKey(parent))) throw new TemplateStructureError(`单元格 ${label} 的${direction === "row" ? "行" : "列"}方向父格 ${parentLabel} 不存在绑定`);
+}
+function detectParentCycle(start, bindings, direction) {
+	const label = formatCellAddress(start);
+	const visited = /* @__PURE__ */ new Set();
+	let current = start;
+	while (current) {
+		const key = cellKey(current);
+		if (visited.has(key)) throw new TemplateStructureError(`单元格 ${label} 的${direction === "row" ? "行" : "列"}方向父链存在环`);
+		visited.add(key);
+		const entry = bindings.get(key);
+		if (!entry) break;
+		current = direction === "row" ? entry.binding.rowParent : entry.binding.colParent;
+	}
+}
+function appendChild(map, parentKey, child) {
+	const list = map.get(parentKey);
+	if (list) {
+		list.push(child);
+		return;
+	}
+	map.set(parentKey, [child]);
+}
+/** 由模板快照构建索引并校验结构约束（ADR-0005 决策 3） */
+function buildTemplateIndex(template) {
+	const bindings = /* @__PURE__ */ new Map();
+	const bindingAddrs = /* @__PURE__ */ new Set();
+	for (const item of template.meta ?? []) {
+		if (item.namespace !== "report") continue;
+		const addr = {
+			row: item.row,
+			col: item.col
+		};
+		const key = cellKey(addr);
+		if (bindings.has(key)) throw new TemplateStructureError(`单元格 ${formatCellAddress(addr)} 存在重复绑定`);
+		bindings.set(key, {
+			addr,
+			binding: item.payload
+		});
+		bindingAddrs.add(key);
+	}
+	const staticCells = /* @__PURE__ */ new Map();
+	for (const cell of template.cells) {
+		const key = cellKey({
+			row: cell.row,
+			col: cell.col
+		});
+		if (bindingAddrs.has(key)) continue;
+		staticCells.set(key, cell);
+	}
+	const rowChildren = /* @__PURE__ */ new Map();
+	const colChildren = /* @__PURE__ */ new Map();
+	for (const { addr, binding } of bindings.values()) {
+		validateParentExists(addr, binding.rowParent, bindings, "row");
+		validateParentExists(addr, binding.colParent, bindings, "col");
+		detectParentCycle(addr, bindings, "row");
+		detectParentCycle(addr, bindings, "col");
+		if (binding.rowParent) appendChild(rowChildren, cellKey(binding.rowParent), addr);
+		if (binding.colParent) appendChild(colChildren, cellKey(binding.colParent), addr);
+	}
+	const logicalRows = collectLogicalRows(template);
+	const logicalCols = collectLogicalCols(template);
+	const merges = template.merges ?? [];
+	const bindingsByRow = /* @__PURE__ */ new Map();
+	for (const entry of bindings.values()) {
+		const list = bindingsByRow.get(entry.addr.row);
+		if (list) list.push(entry);
+		else bindingsByRow.set(entry.addr.row, [entry]);
+	}
+	for (const list of bindingsByRow.values()) list.sort((a, b) => a.addr.col - b.addr.col);
+	const bindingsByCol = /* @__PURE__ */ new Map();
+	for (const entry of bindings.values()) {
+		const list = bindingsByCol.get(entry.addr.col);
+		if (list) list.push(entry);
+		else bindingsByCol.set(entry.addr.col, [entry]);
+	}
+	for (const list of bindingsByCol.values()) list.sort((a, b) => a.addr.row - b.addr.row);
+	return {
+		bindings,
+		staticCells,
+		rowChildren,
+		colChildren,
+		logicalRows,
+		logicalCols,
+		merges,
+		bindingAt(addr) {
+			return bindings.get(cellKey(addr))?.binding;
+		},
+		cellAt(addr) {
+			return staticCells.get(cellKey(addr));
+		},
+		bindingsOnRow(row) {
+			return bindingsByRow.get(row) ?? [];
+		},
+		bindingsOnCol(col) {
+			return bindingsByCol.get(col) ?? [];
+		},
+		isBindingAddr(addr) {
+			return bindings.has(cellKey(addr));
+		}
+	};
+}
+/** 判断两地址是否相同（供 coordinate 层使用） */
+function sameAddress(a, b) {
+	return addressesEqual(a, b);
+}
+//#endregion
+export { TemplateStructureError, buildTemplateIndex, sameAddress };

package/dist/report/rules/evaluate.d.ts

@@ -0,0 +1,25 @@
+import { ConditionalRule } from "../types.js";
+import { CellStyle } from "@veltra/sheet-core";
+//#region src/report/rules/evaluate.d.ts
+/** 条件样式求值上下文：当前展示值 + 可选同记录字段 */
+interface ConditionalEvalContext {
+  cellValue: unknown;
+  bindingField: string;
+  record?: Record<string, unknown>;
+}
+/** 按规则配置的求值字段从上下文取比较值 */
+declare function resolveRuleCompareValue(ctx: ConditionalEvalContext, rule: ConditionalRule): unknown;
+/** 将单元格值转为可比较的有限数值；无法转换时返回 null */
+declare function toComparableNumber(value: unknown): number | null;
+/**
+ * 评估单条条件规则是否命中。
+ * 数值比较运算符在双方均可解析为有限数时按数值比较；`eq` 在无法数值化时回退字符串相等。
+ */
+declare function evaluateCondition(cellValue: unknown, rule: ConditionalRule): boolean;
+/**
+ * 按规则数组顺序评估条件样式，将命中规则的 style 增量依次合并到 baseStyle。
+ * 无规则或未命中时原样返回 baseStyle。
+ */
+declare function evaluateConditionalStyle(ctx: ConditionalEvalContext, baseStyle: CellStyle | undefined, rules: readonly ConditionalRule[] | undefined, scope?: 'cell' | 'row'): CellStyle | undefined;
+//#endregion
+export { ConditionalEvalContext, evaluateCondition, evaluateConditionalStyle, resolveRuleCompareValue, toComparableNumber };

package/dist/report/rules/evaluate.js

@@ -0,0 +1,82 @@
+import { mergeCellStyle } from "@veltra/sheet-core/core/command/set-cell-style";
+//#region src/report/rules/evaluate.ts
+function ruleScope(rule) {
+	return rule.scope ?? "cell";
+}
+/** 按规则配置的求值字段从上下文取比较值 */
+function resolveRuleCompareValue(ctx, rule) {
+	if (rule.field !== void 0 && ctx.record !== void 0) return ctx.record[rule.field];
+	return ctx.cellValue;
+}
+/** 将单元格值转为可比较的有限数值；无法转换时返回 null */
+function toComparableNumber(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return null;
+}
+function isBetweenValue(value) {
+	return Array.isArray(value) && value.length === 2;
+}
+/**
+* 评估单条条件规则是否命中。
+* 数值比较运算符在双方均可解析为有限数时按数值比较；`eq` 在无法数值化时回退字符串相等。
+*/
+function evaluateCondition(cellValue, rule) {
+	const { operator, value: ruleValue } = rule;
+	switch (operator) {
+		case "gt":
+		case "gte":
+		case "lt":
+		case "lte":
+		case "eq": {
+			const left = toComparableNumber(cellValue);
+			const right = toComparableNumber(ruleValue);
+			if (left !== null && right !== null) {
+				if (operator === "gt") return left > right;
+				if (operator === "gte") return left >= right;
+				if (operator === "lt") return left < right;
+				if (operator === "lte") return left <= right;
+				return left === right;
+			}
+			if (operator === "eq") {
+				if (typeof cellValue === "string" && typeof ruleValue === "string") return cellValue === ruleValue;
+				return Object.is(cellValue, ruleValue);
+			}
+			return false;
+		}
+		case "between": {
+			if (!isBetweenValue(ruleValue)) return false;
+			const left = toComparableNumber(cellValue);
+			const min = toComparableNumber(ruleValue[0]);
+			const max = toComparableNumber(ruleValue[1]);
+			if (left === null || min === null || max === null) return false;
+			return left >= min && left <= max;
+		}
+		case "contains":
+			if (typeof cellValue !== "string") return false;
+			if (typeof ruleValue !== "string") return false;
+			return cellValue.includes(ruleValue);
+		default: return false;
+	}
+}
+/**
+* 按规则数组顺序评估条件样式，将命中规则的 style 增量依次合并到 baseStyle。
+* 无规则或未命中时原样返回 baseStyle。
+*/
+function evaluateConditionalStyle(ctx, baseStyle, rules, scope = "cell") {
+	if (!rules || rules.length === 0) return baseStyle;
+	let merged = baseStyle;
+	let matched = false;
+	for (const rule of rules) {
+		if (ruleScope(rule) !== scope) continue;
+		if (!evaluateCondition(resolveRuleCompareValue(ctx, rule), rule)) continue;
+		merged = mergeCellStyle(merged, rule.style);
+		matched = true;
+	}
+	return matched ? merged : baseStyle;
+}
+//#endregion
+export { evaluateCondition, evaluateConditionalStyle, resolveRuleCompareValue, toComparableNumber };

package/dist/report/rules/index.d.ts

@@ -0,0 +1,2 @@
+import { ConditionalEvalContext, evaluateCondition, evaluateConditionalStyle, resolveRuleCompareValue, toComparableNumber } from "./evaluate.js";
+export { type ConditionalEvalContext, evaluateCondition, evaluateConditionalStyle, resolveRuleCompareValue, toComparableNumber };

package/dist/report/template.d.ts

@@ -0,0 +1,63 @@
+import { DatasetField, DatasetRecords, ParamValues, QueryParamDef } from "./types.js";
+import { DataConnection, DataConnector, Result } from "./connector.js";
+import { SheetSnapshot } from "@veltra/sheet-core";
+//#region src/report/template.d.ts
+/**
+ * 模板内嵌的数据集定义
+ * 与 playground DatasetDef 同构，connectionId 替换为内嵌的完整连接对象。
+ */
+interface ReportDatasetDef {
+  id: string;
+  label: string;
+  connection: DataConnection;
+  sql: string;
+  /** 参数元数据覆盖（label / 类型 / 默认值 / 选项） */
+  paramOverrides?: Record<string, Partial<Omit<QueryParamDef, 'id'>>>;
+  /** 字段中文名覆盖（name → label）；查看器不消费，随模板序列化往返供设计器还原 */
+  fieldOverrides?: Record<string, Partial<Pick<DatasetField, 'label'>>>;
+}
+/** 当前支持的报表模板版本 */
+declare const REPORT_TEMPLATE_VERSION = 1;
+/** 模板版本不兼容时抛出 */
+declare class IncompatibleTemplateVersionError extends Error {
+  constructor(message: string);
+}
+/**
+ * 自包含 Report Template：SheetSnapshot + 内嵌数据集定义 + 版本段。
+ * 查看器仅凭 `template` + `connector` 即可完成「参数提取 → 取数 → 展开渲染」闭环；
+ * 模板可 JSON 序列化流转。
+ *
+ * `colWidths` 继承自 `SheetSnapshot.colWidths`（模型列索引 → 像素）。
+ * 注意：`Sheet.snapshot()` 不产生 `datasets` / `version` 字段，经 `restore()`/`snapshot()` 往返会丢失，
+ * 由设计器 `getTemplate()` 在吐出快照时重新附加。
+ */
+interface ReportTemplate extends SheetSnapshot {
+  /** 模板结构版本；当前值为 `REPORT_TEMPLATE_VERSION` */
+  version?: number;
+  datasets?: ReportDatasetDef[];
+}
+/** 载入模板前校验版本：缺失或高于当前支持版本时抛可读错误 */
+declare function assertCompatibleTemplateVersion(template: ReportTemplate): void;
+/**
+ * 由工作簿快照构造带版本段的 Report Template。
+ * `colWidths` 随 `snapshot` 展开（已在 `SheetSnapshot.colWidths`）。
+ */
+declare function createReportTemplate(snapshot: SheetSnapshot, datasets?: ReportDatasetDef[]): ReportTemplate;
+/** 读取模板内嵌的数据集定义（旧模板未内嵌时回退空数组） */
+declare function getTemplateDatasets(template: ReportTemplate): ReportDatasetDef[];
+/** 模板实际绑定的数据集 id（按绑定在 meta 中的出现顺序去重；绑定即真相，ADR-0002 决策 4） */
+declare function getBoundDatasetIds(template: SheetSnapshot): string[];
+/**
+ * Filter Bar 参数来源（ADR-0002 决策 4）：模板实际绑定的数据集的查询参数并集，
+ * 同名参数合并、先见数据集为准；绑定引用了模板未定义的数据集时跳过。
+ */
+declare function resolveTemplateParams(template: ReportTemplate): QueryParamDef[];
+/** 以参数定义的默认值生成 Filter Bar 初始运行时值 */
+declare function resolveParamDefaults(params: readonly QueryParamDef[]): ParamValues;
+/**
+ * 经数据连接器为模板实际绑定的数据集取数（并行），按数据集 id 折叠为 DatasetRecords。
+ * 任一数据集返回业务错误（`ok: false`）则整体透传该错误；绑定但未定义的数据集跳过。
+ */
+declare function fetchTemplateRecords(connector: DataConnector, template: ReportTemplate, values: ParamValues): Promise<Result<DatasetRecords>>;
+//#endregion
+export { IncompatibleTemplateVersionError, REPORT_TEMPLATE_VERSION, ReportDatasetDef, ReportTemplate, assertCompatibleTemplateVersion, createReportTemplate, fetchTemplateRecords, getBoundDatasetIds, getTemplateDatasets, resolveParamDefaults, resolveTemplateParams };

package/dist/report/template.js

@@ -0,0 +1,83 @@
+import "./binding.js";
+import { buildParamDefs } from "./params.js";
+//#region src/report/template.ts
+/** 当前支持的报表模板版本 */
+const REPORT_TEMPLATE_VERSION = 1;
+/** 模板版本不兼容时抛出 */
+var IncompatibleTemplateVersionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "IncompatibleTemplateVersionError";
+	}
+};
+/** 载入模板前校验版本：缺失或高于当前支持版本时抛可读错误 */
+function assertCompatibleTemplateVersion(template) {
+	if (template.version === void 0) throw new IncompatibleTemplateVersionError("报表模板缺少 version 字段，请在设计器中重建模板后重试");
+	if (template.version > 1) throw new IncompatibleTemplateVersionError(`报表模板版本 ${template.version} 高于当前支持的版本 1，请升级组件库后重试`);
+}
+/**
+* 由工作簿快照构造带版本段的 Report Template。
+* `colWidths` 随 `snapshot` 展开（已在 `SheetSnapshot.colWidths`）。
+*/
+function createReportTemplate(snapshot, datasets) {
+	return {
+		...snapshot,
+		version: 1,
+		datasets
+	};
+}
+/** 读取模板内嵌的数据集定义（旧模板未内嵌时回退空数组） */
+function getTemplateDatasets(template) {
+	return Array.isArray(template.datasets) ? template.datasets : [];
+}
+/** 模板实际绑定的数据集 id（按绑定在 meta 中的出现顺序去重；绑定即真相，ADR-0002 决策 4） */
+function getBoundDatasetIds(template) {
+	const ids = [];
+	for (const item of template.meta ?? []) {
+		if (item.namespace !== "report") continue;
+		const dataset = item.payload.dataset;
+		if (typeof dataset === "string" && dataset && !ids.includes(dataset)) ids.push(dataset);
+	}
+	return ids;
+}
+/**
+* Filter Bar 参数来源（ADR-0002 决策 4）：模板实际绑定的数据集的查询参数并集，
+* 同名参数合并、先见数据集为准；绑定引用了模板未定义的数据集时跳过。
+*/
+function resolveTemplateParams(template) {
+	const datasets = getTemplateDatasets(template);
+	const map = /* @__PURE__ */ new Map();
+	for (const datasetId of getBoundDatasetIds(template)) {
+		const dataset = datasets.find((item) => item.id === datasetId);
+		if (!dataset) continue;
+		for (const param of buildParamDefs(dataset.sql, dataset.paramOverrides)) if (!map.has(param.id)) map.set(param.id, param);
+	}
+	return Array.from(map.values());
+}
+/** 以参数定义的默认值生成 Filter Bar 初始运行时值 */
+function resolveParamDefaults(params) {
+	const values = {};
+	for (const param of params) values[param.id] = param.defaultValue;
+	return values;
+}
+/**
+* 经数据连接器为模板实际绑定的数据集取数（并行），按数据集 id 折叠为 DatasetRecords。
+* 任一数据集返回业务错误（`ok: false`）则整体透传该错误；绑定但未定义的数据集跳过。
+*/
+async function fetchTemplateRecords(connector, template, values) {
+	const datasets = getTemplateDatasets(template);
+	const targets = getBoundDatasetIds(template).map((datasetId) => datasets.find((item) => item.id === datasetId)).filter((dataset) => dataset !== void 0);
+	const results = await Promise.all(targets.map((dataset) => connector.query(dataset.connection, dataset.sql, values)));
+	const records = {};
+	for (let i = 0; i < targets.length; i++) {
+		const result = results[i];
+		if (!result.ok) return result;
+		records[targets[i].id] = result.data.rows;
+	}
+	return {
+		ok: true,
+		data: records
+	};
+}
+//#endregion
+export { IncompatibleTemplateVersionError, REPORT_TEMPLATE_VERSION, assertCompatibleTemplateVersion, createReportTemplate, fetchTemplateRecords, getBoundDatasetIds, getTemplateDatasets, resolveParamDefaults, resolveTemplateParams };

package/dist/report/types.d.ts

@@ -0,0 +1,85 @@
+import { CellAddress, CellStylePatch } from "@veltra/sheet-core";
+//#region src/report/types.d.ts
+/** 报表绑定扩展方向 */
+type ReportExpand = 'down' | 'right' | 'none';
+/** 报表绑定聚合方式 */
+type ReportAggregate = 'list' | 'group' | 'sum' | 'avg' | 'count' | 'max' | 'min';
+/** 报表绑定排序 */
+type ReportSort = 'asc' | 'desc' | 'none';
+/**
+ * 设计器预设标签：引擎不读，仅用于 UI 展示与一键切换。
+ * 缺失时 Action Pill 显示「自定义」。
+ */
+type ReportPreset = 'groupHeader' | 'detail' | 'subtotal' | 'grandTotal' | 'cross';
+/** 条件样式比较运算符 */
+type ConditionalOperator = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'between' | 'contains';
+/** 条件样式规则：命中后叠加 CellStyle 增量 */
+interface ConditionalRule {
+  operator: ConditionalOperator;
+  /** 单值比较用标量；`between` 用 `[min, max]`（含端点） */
+  value: unknown;
+  style: CellStylePatch;
+  /** 求值字段；缺省取绑定格自身字段 */
+  field?: string;
+  /** 作用范围；缺省 `'cell'` */
+  scope?: 'cell' | 'row';
+}
+/** 设计格上的报表绑定（存于 Cell Meta namespace `report`） */
+interface ReportBinding {
+  dataset: string;
+  field: string;
+  expand: ReportExpand;
+  aggregate: ReportAggregate;
+  /** 纵向从属父格：本格数据受该格当前行实例的值约束 */
+  rowParent?: CellAddress;
+  /** 横向从属父格：本格数据受该格当前列实例的值约束 */
+  colParent?: CellAddress;
+  /** 扩展实例是否合并为单个单元格；缺省 true */
+  mergeSpan?: boolean;
+  /** 分组/明细排序；缺省视为 none */
+  sort?: ReportSort;
+  /** 条件样式规则（按数组顺序优先级依次求值并合并样式） */
+  conditionalRules?: ConditionalRule[];
+  /** 设计器预设；引擎不读 */
+  preset?: ReportPreset;
+}
+/**
+ * 字段 schema（来自数据集配置，非运行时推断）。
+ * - `name`：绑定键（写入 Binding.field，英文标识）
+ * - `label`：中文显示名（字段面板与占位可读名）
+ */
+interface DatasetField {
+  name: string;
+  label: string;
+  type: 'string' | 'number' | 'date';
+}
+/**
+ * 全局数据集目录项（catalog）：系统里可用的数据集定义。
+ * 与「本报表选用哪些」无关。
+ */
+interface DatasetCatalogItem {
+  id: string;
+  label: string;
+  fields: DatasetField[];
+}
+/** Dataset id → 行记录（渲染 Filled Report 用） */
+type DatasetRecords = Record<string, Record<string, unknown>[]>;
+/** 查询参数控件类型 */
+type QueryParamType = 'text' | 'number' | 'date' | 'date-range' | 'select';
+/** 下拉选项 */
+interface QueryParamOption {
+  label: string;
+  value: string;
+}
+/** 查询参数定义（从 SQL `${param}` 提取，可在数据集编辑器覆盖元数据） */
+interface QueryParamDef {
+  id: string;
+  label: string;
+  type: QueryParamType;
+  defaultValue: unknown;
+  options?: QueryParamOption[];
+}
+/** 运行时参数值 */
+type ParamValues = Record<string, unknown>;
+//#endregion
+export { ConditionalOperator, ConditionalRule, DatasetCatalogItem, DatasetField, DatasetRecords, ParamValues, QueryParamDef, QueryParamOption, QueryParamType, ReportAggregate, ReportBinding, ReportExpand, ReportPreset, ReportSort };

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