@veltra/sheet 2.0.1 → 2.2.0

package/dist/components/report/use-report-designer.js

@@ -0,0 +1,360 @@
+import { REPORT_META_NAMESPACE, applyReportPreset, createReportBinding, formatCellAddress, inferColParentCandidate, inferDropPreset, inferRowParentCandidate, isHorizontalExpandBinding, isVerticalExpandBinding, listColParentCandidates, listRowParentCandidates } from "../../report/binding.js";
+import { buildParamDefs } from "../../report/params.js";
+import { assertCompatibleTemplateVersion, createReportTemplate, getTemplateDatasets, resolveParamDefaults } from "../../report/template.js";
+import { createBindingBadgeRenderer, createBindingBadgeStyleResolver } from "./binding-badge.js";
+import { computed, onScopeDispose, ref, watch } from "vue";
+import { Workbook } from "@veltra/sheet-core";
+//#region src/components/report/use-report-designer.ts
+/**
+* UReportDesigner 的 headless 编排：连接 / 数据集状态、绑定写 Cell Meta、
+* 角色徽章渲染 hook、`getTemplate()` 模板吐出。不持有 DOM / 网格引用。
+*/
+function useReportDesigner(options) {
+	const { props, connections } = options;
+	/** 设计态工作簿：宿主可注入（USheet / UReportViewer 先例），缺省内部自建 */
+	const internalWorkbook = new Workbook();
+	const workbook = computed(() => props.workbook ?? internalWorkbook);
+	const datasets = ref([]);
+	/** meta 变更计数：boundKeys 等派生状态的响应式触发（绑定经命令系统写入后由模型发 meta-change） */
+	const metaTick = ref(0);
+	const parentPick = ref(null);
+	const offMeta = workbook.value.activeSheet.on("meta-change", () => {
+		metaTick.value++;
+	});
+	onScopeDispose(offMeta);
+	/** 稳定选区地址引用（值未变时不替换对象，避免触发下游 watcher） */
+	const activeCell = ref(null);
+	function syncActiveCell() {
+		const next = workbook.value.activeSheet.getSelection().activeCell ?? null;
+		const prev = activeCell.value;
+		if (!next) {
+			activeCell.value = null;
+			return;
+		}
+		if (prev && prev.row === next.row && prev.col === next.col) return;
+		activeCell.value = {
+			row: next.row,
+			col: next.col
+		};
+	}
+	const offSelection = workbook.value.activeSheet.on("selection-change", syncActiveCell);
+	onScopeDispose(offSelection);
+	syncActiveCell();
+	const selectionLabel = computed(() => activeCell.value ? formatCellAddress(activeCell.value) : "—");
+	const catalog = computed(() => datasets.value.map((dataset) => ({
+		id: dataset.id,
+		label: dataset.label,
+		fields: (dataset.fields ?? []).map((field) => ({
+			...field,
+			label: dataset.fieldOverrides?.[field.name]?.label ?? field.label
+		}))
+	})));
+	/** 字段 label 的 O(1) 查找表（徽章 hook 性能契约） */
+	const fieldLabelMap = computed(() => {
+		const map = /* @__PURE__ */ new Map();
+		for (const dataset of catalog.value) for (const field of dataset.fields) map.set(`${dataset.id}:${field.name}`, field.label);
+		return map;
+	});
+	function resolveFieldLabel(datasetId, fieldName) {
+		return fieldLabelMap.value.get(`${datasetId}:${fieldName}`) ?? fieldName;
+	}
+	const boundKeys = computed(() => {
+		metaTick.value;
+		const keys = /* @__PURE__ */ new Set();
+		for (const [, namespace, payload] of workbook.value.activeSheet.entriesCellMeta()) {
+			if (namespace !== "report") continue;
+			const binding = payload;
+			keys.add(`${binding.dataset}:${binding.field}`);
+		}
+		return keys;
+	});
+	function getBindingAt(addr) {
+		return workbook.value.activeSheet.getCellMeta(addr, REPORT_META_NAMESPACE);
+	}
+	function bindField(datasetId, fieldName, addr) {
+		const dataset = catalog.value.find((item) => item.id === datasetId);
+		if (!dataset) return;
+		const field = dataset.fields.find((item) => item.name === fieldName);
+		const target = addr ?? workbook.value.activeSheet.getSelection().activeCell;
+		if (!target) return;
+		const preset = inferDropPreset(target, field?.type ?? "string", getBindingAt);
+		let binding = createReportBinding(dataset, fieldName);
+		binding = applyReportPreset(binding, preset);
+		const rowParent = inferRowParentCandidate(target, getBindingAt);
+		if (rowParent) binding.rowParent = rowParent;
+		const colParent = inferColParentCandidate(target, getBindingAt);
+		if (colParent) binding.colParent = colParent;
+		workbook.value.activeSheet.setCellMeta(target, REPORT_META_NAMESPACE, binding);
+	}
+	const activeBinding = computed(() => {
+		metaTick.value;
+		const cell = activeCell.value;
+		if (!cell) return void 0;
+		return getBindingAt(cell);
+	});
+	const activeFieldType = computed(() => {
+		const binding = activeBinding.value;
+		if (!binding) return "number";
+		return (catalog.value.find((item) => item.id === binding.dataset)?.fields.find((item) => item.name === binding.field))?.type ?? "number";
+	});
+	const activeDatasetFields = computed(() => {
+		const binding = activeBinding.value;
+		if (!binding) return [];
+		return catalog.value.find((item) => item.id === binding.dataset)?.fields ?? [];
+	});
+	const resolvedRowParentLabel = computed(() => {
+		metaTick.value;
+		const binding = activeBinding.value;
+		if (!binding?.rowParent) return "—";
+		return formatCellAddress(binding.rowParent);
+	});
+	const resolvedColParentLabel = computed(() => {
+		metaTick.value;
+		const binding = activeBinding.value;
+		if (!binding?.colParent) return "—";
+		return formatCellAddress(binding.colParent);
+	});
+	const rowParentCandidates = computed(() => {
+		metaTick.value;
+		const binding = activeBinding.value;
+		if (!binding) return [];
+		return listRowParentCandidates(binding, bindingEntries.value);
+	});
+	const colParentCandidates = computed(() => {
+		metaTick.value;
+		const binding = activeBinding.value;
+		if (!binding) return [];
+		return listColParentCandidates(binding, bindingEntries.value);
+	});
+	const bindingEntries = computed(() => {
+		metaTick.value;
+		const entries = [];
+		for (const [addr, namespace, payload] of workbook.value.activeSheet.entriesCellMeta()) {
+			if (namespace !== "report") continue;
+			entries.push({
+				addr,
+				binding: payload
+			});
+		}
+		return entries;
+	});
+	function patchActiveBinding(patch) {
+		const cell = activeCell.value;
+		const binding = activeBinding.value;
+		if (!cell || !binding) return;
+		const next = {
+			...binding,
+			...patch
+		};
+		if ("rowParent" in patch && patch.rowParent === void 0) delete next.rowParent;
+		if ("colParent" in patch && patch.colParent === void 0) delete next.colParent;
+		if (("aggregate" in patch || "expand" in patch) && !("preset" in patch)) delete next.preset;
+		workbook.value.activeSheet.setCellMeta(cell, REPORT_META_NAMESPACE, next);
+	}
+	function startParentPick(mode) {
+		const cell = activeCell.value;
+		if (!cell || !activeBinding.value) return;
+		parentPick.value = {
+			mode,
+			source: {
+				row: cell.row,
+				col: cell.col
+			}
+		};
+	}
+	function cancelParentPick() {
+		parentPick.value = null;
+	}
+	function pickParentAt(target) {
+		const pick = parentPick.value;
+		if (!pick) return;
+		if (target.row === pick.source.row && target.col === pick.source.col) return;
+		const sourceBinding = getBindingAt(pick.source);
+		const targetBinding = getBindingAt(target);
+		if (!sourceBinding || !targetBinding) return;
+		if (targetBinding.dataset !== sourceBinding.dataset) return;
+		if (pick.mode === "row" && !isVerticalExpandBinding(targetBinding)) return;
+		if (pick.mode === "col" && !isHorizontalExpandBinding(targetBinding)) return;
+		const patch = pick.mode === "row" ? { rowParent: { ...target } } : { colParent: { ...target } };
+		const next = {
+			...sourceBinding,
+			...patch
+		};
+		workbook.value.activeSheet.setCellMeta(pick.source, REPORT_META_NAMESPACE, next);
+		parentPick.value = null;
+		workbook.value.activeSheet.selectCell(pick.source);
+	}
+	function clearParent(mode) {
+		if (mode === "row") patchActiveBinding({ rowParent: void 0 });
+		else patchActiveBinding({ colParent: void 0 });
+	}
+	function removeActiveBinding() {
+		const cell = activeCell.value;
+		if (!cell) return;
+		workbook.value.activeSheet.clearCellMeta(cell, REPORT_META_NAMESPACE);
+	}
+	function addConnection(connection) {
+		connections.value = [...connections.value, connection];
+	}
+	function updateConnection(connection) {
+		connections.value = connections.value.map((item) => item.id === connection.id ? connection : item);
+	}
+	function removeConnection(connectionId) {
+		connections.value = connections.value.filter((item) => item.id !== connectionId);
+		datasets.value = datasets.value.filter((dataset) => dataset.connectionId !== connectionId);
+	}
+	let datasetSeq = 0;
+	function addDataset(connectionId) {
+		const dataset = {
+			id: `dataset-${Date.now()}-${datasetSeq++}`,
+			label: "新数据集",
+			connectionId,
+			sql: ""
+		};
+		datasets.value = [...datasets.value, dataset];
+		return dataset;
+	}
+	function updateDataset(datasetId, patch) {
+		datasets.value = datasets.value.map((item) => item.id === datasetId ? {
+			...item,
+			...patch
+		} : item);
+	}
+	function removeDataset(datasetId) {
+		datasets.value = datasets.value.filter((item) => item.id !== datasetId);
+	}
+	function resolveDatasetConnection(dataset) {
+		return connections.value.find((item) => item.id === dataset.connectionId);
+	}
+	function datasetNotFound() {
+		return {
+			ok: false,
+			error: {
+				code: "DATASET_NOT_FOUND",
+				message: "数据集不存在"
+			}
+		};
+	}
+	function connectionNotFound() {
+		return {
+			ok: false,
+			error: {
+				code: "CONNECTION_NOT_FOUND",
+				message: "数据集所属连接不存在"
+			}
+		};
+	}
+	function testConnection(connection) {
+		return props.connector.test(connection);
+	}
+	async function describeDataset(datasetId) {
+		const dataset = datasets.value.find((item) => item.id === datasetId);
+		if (!dataset) return datasetNotFound();
+		const connection = resolveDatasetConnection(dataset);
+		if (!connection) return connectionNotFound();
+		const sql = dataset.sql;
+		const result = await props.connector.describe(connection, sql);
+		if (result.ok) {
+			const current = datasets.value.find((item) => item.id === datasetId);
+			if (current && current.sql === sql) updateDataset(datasetId, { fields: result.data });
+		}
+		return result;
+	}
+	async function previewDataset(datasetId) {
+		const dataset = datasets.value.find((item) => item.id === datasetId);
+		if (!dataset) return datasetNotFound();
+		const connection = resolveDatasetConnection(dataset);
+		if (!connection) return connectionNotFound();
+		const values = resolveParamDefaults(buildParamDefs(dataset.sql, dataset.paramOverrides));
+		return props.connector.query(connection, dataset.sql, values);
+	}
+	const resolveCellStyle = createBindingBadgeStyleResolver(getBindingAt);
+	const resolveCellRenderer = createBindingBadgeRenderer(getBindingAt, resolveFieldLabel);
+	function getTemplate() {
+		const resolved = datasets.value.flatMap((dataset) => {
+			const connection = resolveDatasetConnection(dataset);
+			if (!connection) return [];
+			return [{
+				id: dataset.id,
+				label: dataset.label,
+				connection: { ...connection },
+				sql: dataset.sql,
+				...dataset.paramOverrides ? { paramOverrides: dataset.paramOverrides } : {},
+				...dataset.fieldOverrides ? { fieldOverrides: dataset.fieldOverrides } : {}
+			}];
+		});
+		return createReportTemplate(workbook.value.activeSheet.snapshot(), resolved);
+	}
+	/**
+	* 载入既有 Report Template 继续设计（`template` prop）：
+	* 快照恢复网格绑定（restore + restoreContent 与查看器同路径）；
+	* 内嵌数据集定义还原为设计态（connectionId 引用），内嵌连接按 id 合并进
+	* v-model 连接列表（仅缺省追加，宿主列表是单一事实源）；
+	* describe 恢复字段缓存（字段面板数据源），业务错误忽略（字段留空，可在数据中枢重试）。
+	*/
+	function loadTemplate(template) {
+		assertCompatibleTemplateVersion(template);
+		const sheet = workbook.value.activeSheet;
+		sheet.restore(template);
+		sheet.restoreContent(template);
+		sheet.history.clear();
+		syncActiveCell();
+		const defs = getTemplateDatasets(template);
+		datasets.value = defs.map((def) => ({
+			id: def.id,
+			label: def.label,
+			connectionId: def.connection.id,
+			sql: def.sql,
+			...def.paramOverrides ? { paramOverrides: def.paramOverrides } : {},
+			...def.fieldOverrides ? { fieldOverrides: def.fieldOverrides } : {}
+		}));
+		const missing = defs.map((def) => def.connection).filter((connection) => !connections.value.some((item) => item.id === connection.id));
+		if (missing.length > 0) connections.value = [...connections.value, ...missing.map((connection) => ({ ...connection }))];
+		for (const dataset of datasets.value) if (dataset.sql.trim()) describeDataset(dataset.id);
+	}
+	watch(() => props.template, (template) => {
+		if (template) loadTemplate(template);
+	}, { immediate: true });
+	return {
+		workbook,
+		connections,
+		datasets,
+		catalog,
+		boundKeys,
+		activeCell,
+		selectionLabel,
+		activeBinding,
+		activeFieldType,
+		activeDatasetFields,
+		resolvedRowParentLabel,
+		resolvedColParentLabel,
+		parentPick,
+		rowParentCandidates,
+		colParentCandidates,
+		bindingEntries,
+		metaTick,
+		getBindingAt,
+		resolveFieldLabel,
+		bindField,
+		patchActiveBinding,
+		startParentPick,
+		cancelParentPick,
+		pickParentAt,
+		clearParent,
+		removeActiveBinding,
+		resolveCellStyle,
+		resolveCellRenderer,
+		getTemplate,
+		addConnection,
+		updateConnection,
+		removeConnection,
+		addDataset,
+		updateDataset,
+		removeDataset,
+		testConnection,
+		describeDataset,
+		previewDataset
+	};
+}
+//#endregion
+export { useReportDesigner };

package/dist/components/report/use-report-viewer.js

@@ -0,0 +1,50 @@
+import { renderReport } from "../../report/render/index.js";
+import { fetchTemplateRecords, resolveParamDefaults, resolveTemplateParams } from "../../report/template.js";
+import { computed, ref, shallowRef, watch } from "vue";
+//#region src/components/report/use-report-viewer.ts
+/**
+* UReportViewer 的 headless 编排：参数提取 → 取数 → renderReport 展开。
+* 不持有 DOM / 网格引用；填充快照经 `filledSnapshot` 交给组件壳应用。
+*/
+function useReportViewer(props) {
+	const loading = ref(false);
+	const error = shallowRef(null);
+	const filledSnapshot = shallowRef(null);
+	const params = computed(() => resolveTemplateParams(props.template));
+	const values = shallowRef({});
+	let fetchSeq = 0;
+	async function refresh() {
+		const current = ++fetchSeq;
+		const template = props.template;
+		loading.value = true;
+		error.value = null;
+		const result = await fetchTemplateRecords(props.connector, template, values.value);
+		if (current !== fetchSeq) return;
+		loading.value = false;
+		if (!result.ok) {
+			error.value = result.error;
+			return;
+		}
+		filledSnapshot.value = renderReport(template, result.data);
+	}
+	function setValues(next) {
+		values.value = next;
+		refresh();
+	}
+	watch(() => props.template, () => {
+		filledSnapshot.value = null;
+		values.value = resolveParamDefaults(params.value);
+		refresh();
+	}, { immediate: true });
+	return {
+		params,
+		values,
+		loading,
+		error,
+		filledSnapshot,
+		refresh,
+		setValues
+	};
+}
+//#endregion
+export { useReportViewer };