@lionad/cx-comps-tanstack-charts 0.1.0-alpha.8 → 0.1.0

package/dist/index.mjs

@@ -1,10 +1,10 @@
 import { define } from "@lionad/cx-definition";
-import { Fragment, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createVNode, defineComponent, mergeProps, normalizeClass, normalizeStyle, onBeforeUnmount, onMounted, openBlock, renderList, unref, useAttrs } from "vue";
+import { Fragment, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createVNode, defineComponent, mergeProps, normalizeClass, normalizeStyle, onBeforeUnmount, onMounted, openBlock, ref, renderList, unref, useAttrs, useId, watch } from "vue";
 import { Chart } from "@tanstack/charts/vue";
 import { useCxBEM } from "@lionad/cx-vue";
-import { areaX, areaY, arrow, bandX, bandY, barX, barY, binX, binXY, binY, boxRows, boxX, boxY, cell, colorGradientLegend, colorLegend, cumulative, d3Curve, defaultChartTheme, defineChart, delta, deviation, differenceX, differenceY, dodgeX, dodgeY, dot, first, fold, frame, group, groupBy, hexagon, last, lineX, lineY, linearRegressionRowsX, linearRegressionRowsY, linearRegressionX, linearRegressionY, link, median, mosaicX, mosaicY, normalize, quantile, rank, ratio, rect, ridgelineX, ridgelineY, rollingWindow, ruleX, ruleY, select, stack, stackRowsX, stackRowsY, text, tickX, tickY, variance, vector, violinX, violinY, waffleX, waffleY, waterfall } from "@tanstack/charts";
+import { areaX, areaY, arrow, bandX, bandY, barX, barY, binX, binXY, binY, boxRows, boxX, boxY, cell, colorGradientLegend, colorLegend, colorLegendItems, cumulative, d3Curve, defaultChartTheme, defineChart, delta, deviation, differenceX, differenceY, dodgeX, dodgeY, dot, first, fold, frame, group, groupBy, hexagon, last, lineX, lineY, linearRegressionRowsX, linearRegressionRowsY, linearRegressionX, linearRegressionY, link, median, mosaicX, mosaicY, normalize, quantile, rank, ratio, rect, ridgelineX, ridgelineY, rollingWindow, ruleX, ruleY, select, stack, stackRowsX, stackRowsY, text, tickX, tickY, variance, vector, violinX, violinY, waffleX, waffleY, waterfall } from "@tanstack/charts";
 import { d3AreaXCurve } from "@tanstack/charts/d3/area-x";
-import { curveBasis, curveCatmullRom, curveLinear, curveLinearClosed, curveMonotoneX, curveNatural, curveStep, curveStepAfter, curveStepBefore } from "d3-shape";
+import { curveBasis, curveBumpX, curveCatmullRom, curveLinear, curveLinearClosed, curveMonotoneX, curveNatural, curveStep, curveStepAfter, curveStepBefore } from "d3-shape";
 import { scaleLinear } from "@tanstack/charts/scales/linear";
 import { scaleOrdinal } from "@tanstack/charts/scales/ordinal";
 import { scalePoint } from "@tanstack/charts/scales/point";
@@ -23,11 +23,16 @@ import { treeLayout } from "@tanstack/charts/hierarchy/tree";
 import { treemap } from "@tanstack/charts/hierarchy/treemap";
 import { forceLayout } from "@tanstack/charts/network/force";
 import { sankeyDiagram } from "@tanstack/charts/network/sankey";
-import { geoAlbersUsa, geoEqualEarth, geoIdentity, geoMercator, geoNaturalEarth1, geoOrthographic } from "d3-geo";
+import { geoAlbersUsa, geoEqualEarth, geoEquirectangular, geoIdentity, geoMercator, geoNaturalEarth1, geoOrthographic } from "d3-geo";
+import { decorative } from "@tanstack/charts/mark/decorative";
 import { tooltip } from "@tanstack/charts/tooltip";
+import { viewGrid } from "@tanstack/charts/view";
+import "@tanstack/charts/adapter";
+import { createChartRendererAdapter } from "@tanstack/charts/adapter/renderer";
+import { motion } from "@tanstack/charts/motion";
 import { compileTrigger, createTriggerRegistry } from "@lionad/cx-stream";
 //#region src/shared/chart-skeleton.vue
-const _sfc_main$6 = /*@__PURE__*/ defineComponent({
+const _sfc_main$8 = /*@__PURE__*/ defineComponent({
 	__name: "chart-skeleton",
 	props: { height: { default: 320 } },
 	setup(__props) {
@@ -118,6 +123,85 @@ const _sfc_main$6 = /*@__PURE__*/ defineComponent({
 	}
 });
 //#endregion
+//#region src/shared/chart-empty.vue
+const _sfc_main$7 = /*@__PURE__*/ defineComponent({
+	__name: "chart-empty",
+	props: { height: { default: 320 } },
+	setup(__props) {
+		const props = __props;
+		const ns = useCxBEM("tanstack-charts-chart-empty");
+		const normalizedHeight = computed(() => Number.isFinite(props.height) && props.height > 0 ? props.height : 320);
+		const shellStyle = computed(() => ({
+			display: "flex",
+			flexDirection: "column",
+			alignItems: "center",
+			justifyContent: "center",
+			gap: "0.375rem",
+			width: "100%",
+			boxSizing: "border-box",
+			height: `${normalizedHeight.value}px`,
+			border: "1px dashed rgba(148, 163, 184, 0.35)",
+			borderRadius: "0.75rem",
+			color: "rgba(148, 163, 184, 0.9)",
+			textAlign: "center"
+		}));
+		const iconStyle = {
+			width: "2rem",
+			height: "2rem",
+			opacity: .7
+		};
+		const titleStyle = {
+			margin: 0,
+			fontSize: "0.875rem",
+			fontWeight: 500
+		};
+		const descStyle = {
+			margin: 0,
+			fontSize: "0.75rem",
+			opacity: .75
+		};
+		return (_ctx, _cache) => {
+			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 图表终态空态：数据集占位/不可渲染时替换 Chart 占位（空壳 svg 无反馈等同未渲染）。\n       全 inline style：保持包零 css 分发契约（同 chart-skeleton 模式） "), createElementVNode("div", {
+				class: normalizeClass(unref(ns).b()),
+				style: normalizeStyle(shellStyle.value),
+				"data-testid": "cx-tanstack-charts-chart-empty",
+				role: "status"
+			}, [
+				(openBlock(), createElementBlock("svg", {
+					style: iconStyle,
+					viewBox: "0 0 24 24",
+					fill: "none",
+					stroke: "currentColor",
+					"stroke-width": "1.5",
+					"aria-hidden": "true"
+				}, [..._cache[0] || (_cache[0] = [
+					createElementVNode("circle", {
+						cx: "12",
+						cy: "12",
+						r: "9"
+					}, null, -1),
+					createElementVNode("line", {
+						x1: "12",
+						y1: "7.5",
+						x2: "12",
+						y2: "13",
+						"stroke-linecap": "round"
+					}, null, -1),
+					createElementVNode("circle", {
+						cx: "12",
+						cy: "16.5",
+						r: "0.9",
+						fill: "currentColor",
+						stroke: "none"
+					}, null, -1)
+				])])),
+				createElementVNode("p", { style: titleStyle }, "图表数据不可用"),
+				createElementVNode("p", { style: descStyle }, "数据集中缺少可渲染的数据，已跳过绘制")
+			], 6)], 2112);
+		};
+	}
+});
+//#endregion
 //#region src/shared/streaming.ts
 /**
 * 读取 trigger 注入的流式骨架标记（_cx_streaming，下划线前缀键不会透传物料）。
@@ -140,16 +224,20 @@ const HOST_PROP_KEYS = [
 	"className"
 ];
 /**
-* 命名数据集白名单（GenUI 数据顶层化契约）：
-* rows 恒为主数据集（流式 trigger arrayKey），nodes/links 承载关系型图双数据集；
-* 物料 data 顶层与 definition 平级的这三个数组字段分馏进 datasets 表，
-* 供 marks 内字符串引用解析。非数组值静默忽略（流式半值防御）。
+* 命名数据集分馏（GenUI 数据顶层化契约）：
+* 物料 data 顶层与 definition 平级的数组字段全量进 datasets 表——rows 恒为主
+* 数据集（流式 trigger arrayKey），其余按语义自由命名：关系型图 nodes/links、
+* geo 的 sphere/graticule/land、分层图 innerRows/outerRows、仪表 bandRows 等。
+* 非数组值静默忽略（流式半值防御）。
+* 排除集防串味：宿主 props（class/style Vue 绑定可为数组）、cx 内部键
+* （comp 运行时节点、data-* 编辑标记、_ 前缀编辑器键）不是数据集。
 */
-const DATASET_KEYS = [
-	"rows",
-	"nodes",
-	"links"
-];
+const DATASET_EXCLUDE_KEYS = /* @__PURE__ */ new Set([
+	"definition",
+	"comp",
+	"class",
+	"style"
+]);
 /**
 * 分馏 <Chart> 宿主 props：标量白名单 + class/style + ariaLabel 回退。
 *
@@ -184,9 +272,11 @@ function useChartProps(attrs) {
 		spec: computed(() => attrs.definition ?? { marks: [] }),
 		datasets: computed(() => {
 			const table = {};
-			for (const key of DATASET_KEYS) {
-				const value = attrs[key];
-				if (Array.isArray(value)) table[key] = value;
+			for (const [key, value] of Object.entries(attrs)) {
+				if (!Array.isArray(value)) continue;
+				if (DATASET_EXCLUDE_KEYS.has(key)) continue;
+				if (key.startsWith("data-") || key.startsWith("_")) continue;
+				table[key] = value;
 			}
 			return table;
 		}),
@@ -283,6 +373,7 @@ function translateAxisPresentation(axis) {
 	if (axis === false) return false;
 	const presentation = {};
 	if (axis.label !== void 0) presentation.label = axis.label;
+	if (axis.line !== void 0) presentation.line = axis.line;
 	if (axis.ticks !== void 0) {
 		const ticks = {};
 		if (axis.ticks.count !== void 0) ticks.count = axis.ticks.count;
@@ -310,6 +401,80 @@ function translateAxis(spec, fallbackKind) {
 	return axis;
 }
 //#endregion
+//#region src/shared/translate/geometry.ts
+/**
+* 占位几何检测：LLM 在数据集缺席时可能产出 geometry 为占位字符串的示意 spec
+* （如 "…（命名数据集）…"），或只引用不提供数据集（resolveMarkData 回退空数组）。
+* 翻译层与渲染层对这些形态容错回退，占位字符串则被库静默忽略——都渲染为空壳
+* svg 且无任何反馈。本模块提供「渲染必然空壳」的判定与翻译期警告，让空壳显式化。
+*
+* 流式安全性：占位字符串只可能出现在完整闭合的 JSON 中（流式截断停在字符层，
+* 截断帧不可解析即不会产出 spec），检测不存在流式中间态误报面。
+*/
+/** 数据集为 GeoJSON Feature 数组（rows 平铺 features 与命名 geo 数据集同形态） */
+function isFeatureArray(rows) {
+	return rows.length > 0 && rows.every((f) => f?.type === "Feature");
+}
+/**
+* 单数据集整体不可渲染判定：Feature 数组且全部条目几何缺失或为占位字符串。
+* 混合场景（部分真实几何）不算——部分数据仍可渲染，整体空态会误杀；
+* geometry: null 是 GeoJSON 合法形态，但全部条目皆 null 时渲染结果同为空壳。
+*/
+function isPlaceholderGeometryDataset(rows) {
+	if (!isFeatureArray(rows)) return false;
+	return rows.every((f) => {
+		const geometry = f.geometry;
+		return geometry == null || typeof geometry === "string";
+	});
+}
+/**
+* 组件层空态判定：整图渲染必然空壳时为 true。
+*
+* 判定范围收敛在纯 geoShape 图（全部 marks 均为 geoShape）：geoShape 无独立于数据
+* 的渲染力（数据不可用即零图元），而其余 mark 类型总有独立形状；复合图只要存在
+* 一个非 geoShape mark 或一个可用 geo 数据集就返回 false，防「部分可渲染却整体
+* 空态」的误杀。覆盖三种不可用形态：
+* - 命名数据集占位（geometry 占位字符串/全 null）
+* - 命名数据集缺失（只引用不提供，resolveMarkData 回退空数组）
+* - mark 内联 data 数组本身占位（不占命名数据集表的形态）
+*/
+function isPlaceholderChartRender(spec, datasets) {
+	const marks = spec?.marks;
+	if (!marks?.length) return false;
+	if (marks.some((mark) => mark.type !== "geoShape")) return false;
+	return marks.every((mark) => {
+		const rows = typeof mark.data === "string" ? datasets?.[mark.data] : mark.data;
+		if (rows === void 0 || rows === null) return true;
+		if (!Array.isArray(rows)) return false;
+		if (rows.length === 0) return true;
+		return isPlaceholderGeometryDataset(rows);
+	});
+}
+/** 翻译期警告去重：数组引用（占位）与数据集名（缺失）各自只警告一次 */
+const warnedRows = /* @__PURE__ */ new WeakSet();
+const warnedMissing = /* @__PURE__ */ new Set();
+/**
+* 翻译期占位几何警告：数据集整体占位时 console.warn 指出空壳根因与修复方向。
+* 只挂在 geoShape（占位字符串的高发地——示意 spec 的外部轮廓数据集）；普通 mark
+* 的数据集在途是流式常态，warn 会成噪音。WeakSet 按引用去重，数据集内容更新
+* （新引用）视为新数据集重新警告。
+*/
+function warnPlaceholderGeometry(rows, datasetName, markType) {
+	if (!isPlaceholderGeometryDataset(rows) || warnedRows.has(rows)) return;
+	warnedRows.add(rows);
+	console.warn(`[cx-charts] ${markType} 数据集${datasetName ? ` "${datasetName}"` : ""} 的 geometry 全部缺失或为占位字符串，渲染为空壳——须以真实 GeoJSON 数据集整体替换示意占位（技能侧见「数据供给」表）。`);
+}
+/**
+* 翻译期数据集缺失警告：geoShape 按名引用了数据集表中不存在的键——与占位字符串
+* 同为「渲染空壳无反馈」的事故形态，区别只在根因（未提供 vs 提供了占位）。
+* 按名去重（缺失数据集无内容引用可作 WeakSet 键），命名数据集到达后不再命中。
+*/
+function warnMissingGeometryDataset(datasetName, markType) {
+	if (warnedMissing.has(datasetName)) return;
+	warnedMissing.add(datasetName);
+	console.warn(`[cx-charts] ${markType} 引用的数据集 "${datasetName}" 不存在，渲染为空壳——数据集须随物料 data 顶层提供（GenUI 数据顶层化契约）。`);
+}
+//#endregion
 //#region src/shared/translate/transforms.ts
 /**
 * 数据预处理管道翻译：spec 顶层 transforms 按序执行，产物以 name 注册进数据集表。
@@ -519,7 +684,6 @@ const SCALAR_KEYS = [
 	"positiveFillOpacity",
 	"negativeFillOpacity",
 	"comparisonStroke",
-	"cornerRadius",
 	"padAngle",
 	"radiusOffset",
 	"baseline",
@@ -587,7 +751,7 @@ function translateFrame(spec) {
 }
 /** channel 运行时校验：只接受字段名字符串（accessor 函数 JSON 不可表达） */
 function assertChannels(spec) {
-	const constantKeys = spec.type === "ruleX" ? /* @__PURE__ */ new Set(["x"]) : spec.type === "ruleY" ? /* @__PURE__ */ new Set(["y"]) : void 0;
+	const constantKeys = spec.type === "ruleX" ? /* @__PURE__ */ new Set(["x"]) : spec.type === "ruleY" ? /* @__PURE__ */ new Set(["y"]) : spec.type === "rect" ? /* @__PURE__ */ new Set(["x1", "y1"]) : void 0;
 	for (const key of CHANNEL_KEYS) {
 		const value = spec[key];
 		if (value !== void 0 && typeof value !== "string") {
@@ -597,7 +761,9 @@ function assertChannels(spec) {
 	}
 	for (const key of CHANNEL_FLEX_KEYS) {
 		const value = spec[key];
-		if (value !== void 0 && typeof value !== "string" && typeof value !== "number") throw new Error(`translateMark: channel "${key}" 只支持字段名或数值，收到 ${typeof value}`);
+		if (value !== void 0 && typeof value !== "string" && typeof value !== "number") {
+			if (!(Array.isArray(value) && value.length === 4 && value.every((n) => typeof n === "number" && Number.isFinite(n)))) throw new Error(`translateMark: channel "${key}" 只支持字段名、数值或四角数组，收到 ${typeof value}`);
+		}
 	}
 }
 /**
@@ -611,6 +777,21 @@ function resolveMarkData(data, datasets) {
 	if (typeof data !== "string") return data;
 	return datasets?.[data] ?? [];
 }
+/** 缺省半径像素上下界（sqrt 面积映射）：小值保可见、大值防巨泡覆盖全图 */
+const DEFAULT_R_RANGE = [2.5, 14];
+/**
+* rScale 注入：库缺省 rScale 是恒等映射（字段原始值直接当像素半径，大数据值
+* 渲染为巨泡）——r 为字段名时缺省注入 sqrt 映射（半径∝√值 ⇒ 面积∝值，气泡图
+* 感知编码约定），domain 由库从数据推断（includeZero）。数值常量 r 是显式像素
+* 意图不缩放；spec.rScale.range 覆盖缺省上下界。
+* 工厂形态（无 copy 的函数）让库推断 domain；实例形态库不推断（scale-input 契约）。
+* 返回 undefined 表示不注入（消费方判空挂 options）。
+*/
+function resolveRScaleOption(spec) {
+	if (typeof spec.r !== "string") return void 0;
+	const range = spec.rScale?.range ?? DEFAULT_R_RANGE;
+	return { scale: () => scaleSqrt().range([range[0], range[1]]) };
+}
 /** layout 声明式 → mark layout 工厂（stack/group/dodge 挂 mark.layout 字段） */
 function translateLayout(spec) {
 	switch (spec.kind) {
@@ -668,10 +849,18 @@ function translateMark(spec, datasets) {
 	if (!factory) throw new Error(`translateMark: 未知 mark type "${String(spec.type)}"`);
 	assertChannels(spec);
 	const options = {};
-	for (const key of CHANNEL_KEYS) if (spec[key] !== void 0) options[key] = spec[key];
+	for (const key of CHANNEL_KEYS) {
+		const value = spec[key];
+		if (value === void 0) continue;
+		options[key] = typeof value === "number" ? () => value : value;
+	}
+	if (options.key === void 0) options.key = (_datum, { index }) => index;
 	for (const key of CHANNEL_FLEX_KEYS) if (spec[key] !== void 0) options[key] = spec[key];
+	const rScale = resolveRScaleOption(spec);
+	if (rScale !== void 0) options.rScale = rScale;
 	for (const key of STYLE_KEYS) if (spec[key] !== void 0) options[key] = spec[key];
 	for (const key of SCALAR_KEYS) if (spec[key] !== void 0) options[key] = spec[key];
+	if ((spec.type === "barX" || spec.type === "barY") && spec.cornerRadius !== void 0 && spec.radius === void 0) options.radius = spec.cornerRadius;
 	if (spec.id !== void 0) options.id = spec.id;
 	if (spec.curve !== void 0) options.curve = spec.type === "violinY" ? translateAreaXCurve(spec.curve) : translateCurve(spec.curve);
 	if (spec.layout !== void 0) options.layout = translateLayout(spec.layout);
@@ -755,22 +944,46 @@ function translatePolarGuide(spec) {
 		"shape",
 		"labels",
 		"labelAngle",
-		"labelOffset"
+		"labelOffset",
+		"id",
+		"className",
+		"labelClassName",
+		"stroke",
+		"strokeOpacity",
+		"strokeWidth",
+		"strokeDasharray",
+		"fill",
+		"fillOpacity",
+		"labelFill",
+		"labelFontSize",
+		"labelAnchor",
+		"labelBaseline",
+		"labelDx",
+		"labelDy",
+		"labelRotate"
 	]) if (spec[key] !== void 0) options[key] = spec[key];
 	return factory(options);
 }
 /** polar axis 声明式（复用 scale 枚举；wrap 仅 angle 轴）→ PolarAngleOptions/PolarRadiusOptions */
-function translatePolarAxis(spec) {
+function translatePolarAxis(spec, { allowRange = false } = {}) {
 	if (!spec) return void 0;
 	const axis = {};
 	if (spec.scale) axis.scale = translateScale(spec.scale);
 	if (spec.nice !== void 0) axis.nice = spec.nice;
+	if (allowRange && spec.range !== void 0) {
+		const [r0, r1] = spec.range;
+		if (!Number.isFinite(r0) || !Number.isFinite(r1) || r0 < 0 || r1 < r0) throw new Error(`translatePolar: radiusAxis.range 须为有限非负且递增的比例对，收到 [${r0}, ${r1}]`);
+		axis.range = [ratioToLength(r0), ratioToLength(r1)];
+	}
 	return axis;
 }
 /**
 * polar 容器：{ type:'polar', marks:[radialXxx...], angleAxis, radiusAxis, radiusRatio,
 * startAngle, endAngle, inset, polarGuides } → polar({...})。
 * extraMarks：调用方预组装的 PolarMark（sunburst 等自包含层级 mark 不走 radial 直译）。
+* 0.18 契约：angle/radius scale 配置收进容器级 options.scales 保留通道
+* （resolvePolarLayout 读 options.scales 的 reserved angle/radius 条目），
+* 不再是顶层 angle/radius 字段；definition.scales 只需 x/y null 占位。
 */
 function translatePolar(spec, datasets, extraMarks = []) {
 	const options = { marks: [...(spec.marks ?? []).map((m) => translateRadialMark(m, datasets)), ...extraMarks] };
@@ -779,12 +992,28 @@ function translatePolar(spec, datasets, extraMarks = []) {
 	if (spec.endAngle !== void 0) options.endAngle = spec.endAngle;
 	if (spec.inset !== void 0) options.inset = spec.inset;
 	if (spec.id !== void 0) options.id = spec.id;
+	const MATERIALIZING_TYPES = /* @__PURE__ */ new Set([
+		"radialBarRadius",
+		"radialBarAngle",
+		"radialLine",
+		"radialArea",
+		"radialText",
+		"radialRule",
+		"radialDot"
+	]);
+	const marksSpecs = spec.marks ?? [];
+	const hasRadialBarRadius = marksSpecs.some((m) => m.type === "radialBarRadius");
+	const hasRadialBarAngle = marksSpecs.some((m) => m.type === "radialBarAngle");
+	const materializesChannel = marksSpecs.some((m) => MATERIALIZING_TYPES.has(m.type));
 	const angle = translatePolarAxis(spec.angleAxis);
-	const radius = translatePolarAxis(spec.radiusAxis);
-	const hasRadialBarRadius = (spec.marks ?? []).some((m) => m.type === "radialBarRadius");
-	const hasRadialBarAngle = (spec.marks ?? []).some((m) => m.type === "radialBarAngle");
-	options.angle = angle ?? { scale: () => hasRadialBarRadius ? scaleBand() : scalePoint() };
-	options.radius = radius ?? { scale: hasRadialBarAngle ? () => scaleBand() : scaleLinear };
+	const radius = translatePolarAxis(spec.radiusAxis, { allowRange: true });
+	options.scales = materializesChannel ? {
+		angle: angle ?? { scale: () => hasRadialBarRadius ? scaleBand() : scalePoint() },
+		radius: radius ?? { scale: hasRadialBarAngle ? () => scaleBand() : scaleLinear }
+	} : {
+		angle: angle ?? null,
+		radius: radius ?? null
+	};
 	if (spec.polarGuides?.length) options.guides = spec.polarGuides.map(translatePolarGuide);
 	return polar(options);
 }
@@ -850,6 +1079,27 @@ function hierarchyOptions(spec, idKey) {
 	};
 	throw new Error(`translateComposite: ${spec.type} 层级数据源必须声明 path 或 nodeId+parentId`);
 }
+/**
+* 层级布局节点的字段名通道（treemap/sunburst 的 color/z、tree 节点 dot 的 color/r）：
+* 库的 channelValues 在布局节点上平查 datum[field]，而 flatHierarchyNodeContext 把源行
+* 收纳在 data 下不展开——字段名物化为 data 取值 accessor，保持「字段名引用源数据」契约。
+* sankey 不在此列：其 marks 回调 channel 按设计锁定布局行字段（key/width 等 canonical）。
+*/
+function hierarchyFieldChannel(field) {
+	return (node) => node?.data?.[field];
+}
+/**
+* sankey 布局行顶层只有 canonical 字段（key/width/坐标），原 datum 收纳在 .data 下；
+* 声明式样式字段名（如 stroke:"色调"、color:"id"）须穿透到原 datum 解析，
+* 否则 channel 按顶层查表得 undefined 而静默退回默认样式。
+*/
+function sankeyDatumField(field) {
+	return (row) => {
+		const record = row;
+		if (record.data != null && field in record.data) return record.data[field];
+		return record[field];
+	};
+}
 /** sankey：固化 marks 回调 = link(布局连线) + rect(布局节点)，样式取自声明 */
 function translateSankey(spec, datasets) {
 	const nodes = resolveMarkData(spec.nodes, datasets);
@@ -862,25 +1112,30 @@ function translateSankey(spec, datasets) {
 		source: spec.source,
 		target: spec.target,
 		value: spec.value,
-		marks: (context) => [looseLink(context.links, {
-			x1: "x1",
-			y1: "y1",
-			x2: "x2",
-			y2: "y2",
-			key: "key",
-			strokeWidth: "width",
-			lineCap: "butt",
-			stroke: spec.stroke ?? void 0,
-			strokeOpacity: spec.strokeOpacity ?? .55
-		}), looseRect(context.nodes, {
-			x1: "x0",
-			x2: "x1",
-			y1: "y0",
-			y2: "y1",
-			key: "key",
-			color: spec.color ?? "key",
-			fillOpacity: spec.fillOpacity ?? void 0
-		})]
+		marks: (context) => {
+			const strokeField = typeof spec.stroke === "string" && context.links.some((l) => l?.data?.[spec.stroke] !== void 0) ? spec.stroke : null;
+			return [looseLink(context.links, {
+				x1: "x1",
+				y1: "y1",
+				x2: "x2",
+				y2: "y2",
+				key: "key",
+				strokeWidth: (row) => Math.max(1, Number(row.width) || 1),
+				lineCap: "butt",
+				curve: d3Curve(curveBumpX),
+				color: strokeField ? sankeyDatumField(strokeField) : void 0,
+				stroke: strokeField ? void 0 : spec.stroke ?? void 0,
+				strokeOpacity: spec.strokeOpacity ?? .55
+			}), looseRect(context.nodes, {
+				x1: "x0",
+				x2: "x1",
+				y1: "y0",
+				y2: "y1",
+				key: "key",
+				color: typeof spec.color === "string" ? sankeyDatumField(spec.color) : spec.color ?? "key",
+				fillOpacity: spec.fillOpacity ?? void 0
+			})];
+		}
 	};
 	if (spec.id !== void 0) options.id = spec.id;
 	if (spec.align !== void 0) options.align = spec.align;
@@ -900,8 +1155,8 @@ function translateSunburst(spec, datasets) {
 		value: spec.value
 	};
 	if (spec.id !== void 0) options.id = spec.id;
-	if (spec.color !== void 0) options.color = spec.color;
-	if (spec.z !== void 0) options.z = spec.z;
+	if (spec.color !== void 0) options.color = hierarchyFieldChannel(spec.color);
+	if (spec.z !== void 0) options.z = hierarchyFieldChannel(spec.z);
 	if (spec.visibleDepth !== void 0) options.visibleDepth = spec.visibleDepth;
 	if (spec.ringPadding !== void 0) options.ringPadding = spec.ringPadding;
 	for (const key of [
@@ -931,7 +1186,7 @@ function translateTreemap(spec, datasets) {
 		value: spec.value
 	};
 	if (spec.id !== void 0) options.id = spec.id;
-	if (spec.color !== void 0) options.color = spec.color;
+	if (spec.color !== void 0) options.color = hierarchyFieldChannel(spec.color);
 	if (spec.method !== void 0) options.method = spec.method;
 	if (spec.ratio !== void 0) options.ratio = spec.ratio;
 	if (spec.round !== void 0) options.round = spec.round;
@@ -957,6 +1212,7 @@ function translateTree(spec, datasets) {
 	if (spec.orientation !== void 0) options.orientation = spec.orientation;
 	if (spec.nodeSize !== void 0) options.nodeSize = spec.nodeSize;
 	const layout = treeLayout(rows, options);
+	const nodeRScale = resolveRScaleOption(spec);
 	return [looseLink(layout.links, {
 		x1: "x1",
 		y1: "y1",
@@ -970,9 +1226,10 @@ function translateTree(spec, datasets) {
 		x: "x",
 		y: "y",
 		key: "id",
-		r: spec.r ?? 4.5,
-		color: spec.color ?? void 0,
-		strokeWidth: 1.5
+		r: typeof spec.r === "string" ? hierarchyFieldChannel(spec.r) : spec.r ?? 4.5,
+		color: spec.color === void 0 ? void 0 : hierarchyFieldChannel(spec.color),
+		strokeWidth: 1.5,
+		...nodeRScale !== void 0 ? { rScale: nodeRScale } : {}
 	})];
 }
 /** 缺省力集：官方示例常规四力的常量形态（函数 accessor 不可 JSON，由库缺省接管） */
@@ -1012,6 +1269,7 @@ function translateForceGraph(spec, datasets) {
 	if (spec.iterations !== void 0) options.iterations = spec.iterations;
 	if (spec.domainPadding !== void 0) options.domainPadding = spec.domainPadding;
 	const graph = forceLayout(nodes, links, options);
+	const nodeRScale = resolveRScaleOption(spec);
 	return {
 		marks: [looseLink(graph.links, {
 			x1: "x1",
@@ -1027,36 +1285,49 @@ function translateForceGraph(spec, datasets) {
 			key: spec.nodeKey,
 			color: spec.color ?? void 0,
 			r: spec.r ?? 5,
-			strokeWidth: 1.5
+			strokeWidth: 1.5,
+			...nodeRScale !== void 0 ? { rScale: nodeRScale } : {}
 		})],
 		xDomain: [graph.xDomain[0], graph.xDomain[1]],
 		yDomain: [graph.yDomain[0], graph.yDomain[1]]
 	};
 }
-/** d3-geo 投影名称枚举 → 工厂（descriptor.type 形态：() => projection） */
+/** d3-geo 投影名称枚举 → 工厂（descriptor.type 形态：() => projection）；
+*  等距圆柱必须用 equirectangular 而非 identity：identity 的 stream 无 sphere 方法，
+*  fit/渲染 Sphere 几何（球面描边层）直接抛 TypeError */
 const GEO_PROJECTION_FACTORIES = {
 	mercator: geoMercator,
 	orthographic: geoOrthographic,
 	naturalEarth1: geoNaturalEarth1,
 	albersUsa: geoAlbersUsa,
 	equalEarth: geoEqualEarth,
+	equirectangular: geoEquirectangular,
 	identity: geoIdentity
 };
-/** geoShape：projection 名称枚举 → descriptor {type, fit, inset}；fit:'data' 由库拟合数据本体 */
+/** geoShape：projection 名称枚举 → descriptor {type, fit, inset}；fit:'data' 由库拟合数据本体，{data:'<name>'} 拟合另一命名数据集 */
 function translateGeoShape(spec, datasets) {
 	const rows = resolveMarkData(spec.data, datasets);
+	const datasetName = typeof spec.data === "string" ? spec.data : void 0;
+	if (datasetName && rows.length === 0 && !datasets?.[datasetName]) warnMissingGeometryDataset(datasetName, "geoShape");
+	else warnPlaceholderGeometry(rows, datasetName, "geoShape");
 	const projectionName = spec.projection ?? "mercator";
+	if (typeof projectionName === "object") throw new Error("translateGeoShape: projection {$by} 仅允许出现在 facet chart 子模板内");
 	const factory = GEO_PROJECTION_FACTORIES[projectionName];
 	if (!factory) throw new Error(`translateGeoShape: 未知投影 "${String(projectionName)}"`);
 	const options = { projection: {
 		type: factory,
-		fit: spec.fit ?? "data",
+		fit: typeof spec.fit === "object" && spec.fit !== null ? {
+			type: "FeatureCollection",
+			features: resolveMarkData(spec.fit.data, datasets)
+		} : spec.fit ?? "data",
 		...spec.inset !== void 0 ? { inset: spec.inset } : {}
 	} };
 	if (spec.id !== void 0) options.id = spec.id;
 	if (spec.key !== void 0) options.key = spec.key;
 	if (spec.color !== void 0) options.color = spec.color;
 	if (spec.r !== void 0) options.r = spec.r;
+	const rScale = resolveRScaleOption(spec);
+	if (rScale !== void 0) options.rScale = rScale;
 	for (const key of [
 		"fill",
 		"fillOpacity",
@@ -1069,6 +1340,25 @@ function translateGeoShape(spec, datasets) {
 	return geoShape(rows, options);
 }
 /**
+* facet 子模板按组实例化:深度遍历,把 {$by:{组名:值}} 形态字段替换为当前组映射值。
+* 未声明 $by 的字段原样保留;$by 表未命中当前组时抛错(静默回退会让分面悄悄同参)。
+*/
+function instantiateFacetTemplate(node, groupKey) {
+	if (Array.isArray(node)) return node.map((item) => instantiateFacetTemplate(item, groupKey));
+	if (node && typeof node === "object") {
+		const record = node;
+		const keys = Object.keys(record);
+		if (keys.length === 1 && keys[0] === "$by") {
+			const table = record.$by;
+			const hit = table[String(groupKey)];
+			if (hit === void 0) throw new Error(`instantiateFacetTemplate: $by 映射未命中分组 "${String(groupKey)}"(可用键: ${Object.keys(table).join(", ")})`);
+			return hit;
+		}
+		return Object.fromEntries(Object.entries(record).map(([k, v]) => [k, instantiateFacetTemplate(v, groupKey)]));
+	}
+	return node;
+}
+/**
 * facet：chart 回调固化为递归子 spec 翻译——translateChild 由 definition.ts 注入
 * （子 spec 翻译与顶层同路径，仅数据集换为 facet 分组行；规避 composite ↔ definition 循环 import）。
 * label 语义：true 显示分组 key 标签（库的函数形态不可 JSON，布尔即可覆盖声明式场景）。
@@ -1078,9 +1368,10 @@ function translateFacet(spec, datasets, translateChild) {
 	if (!spec.by) throw new Error("translateFacet: facet 必须声明 by 分组字段");
 	if (!spec.chart) throw new Error("translateFacet: facet 必须声明 chart 子 spec 模板");
 	const childTemplate = spec.chart;
+	const byField = spec.by;
 	const options = {
-		by: spec.by,
-		chart: (facetRows) => translateChild(childTemplate, facetRows)
+		by: byField,
+		chart: (facetRows) => translateChild(instantiateFacetTemplate(childTemplate, facetRows[0]?.[byField]), facetRows)
 	};
 	if (spec.id !== void 0) options.id = spec.id;
 	if (spec.columns !== void 0) options.columns = spec.columns;
@@ -1117,6 +1408,31 @@ function translateCompositeMark(spec, datasets, translateChild) {
 	}
 }
 //#endregion
+//#region src/shared/translate/view.ts
+function translateViewGrid(spec, datasets, hooks) {
+	const grid = spec.views;
+	const views = grid.items.map((item) => {
+		if (item.chart.views !== void 0) throw new Error(`translateViewGrid: 子视图 "${item.id}" 不支持嵌套 views`);
+		return {
+			id: item.id,
+			row: item.row,
+			column: item.column,
+			...item.share ? { share: item.share } : {},
+			...item.align ? { align: item.align } : {},
+			chart: hooks.buildChild(item.chart, datasets)
+		};
+	});
+	const composed = viewGrid({
+		rows: grid.rows,
+		columns: grid.columns,
+		...grid.gap !== void 0 ? { gap: grid.gap } : {},
+		...grid.rowGap !== void 0 ? { rowGap: grid.rowGap } : {},
+		...grid.columnGap !== void 0 ? { columnGap: grid.columnGap } : {},
+		views
+	});
+	return hooks.applyHost(composed, spec);
+}
+//#endregion
 //#region src/shared/translate/definition.ts
 /**
 * definition 组装：声明式 spec → DomChartDefinition（可直接喂给 <Chart>）。
@@ -1125,12 +1441,19 @@ function translateCompositeMark(spec, datasets, translateChild) {
 * - transforms 管道先于 marks 执行，产物注册进数据集表副本（marks 字符串引用在此解析）
 * - polar 族（polar/pie/sunburst 全为 polar 容器且无直角 channel）未显式声明 x/y 时
 *   置 null 显式无轴（库对 polar mark 的 scale 类型为 never，缺省 axis 注入会抛错）
+* - 纯 geoShape 场景同理置 null（geo mark 不物化直角 scale channel，缺省轴只剩
+*   0-1 无意义刻度；混合直角 channel mark 时保留缺省轴）
 * - tree/forceGraph 展开为多 mark；forceGraph 回传的轴域在 x/y 未显式声明时注入
 *   linear scale 实例（仿真坐标以 0 为中心，缺省推断 domain 不包含负半轴余量）
+* - spec.views 存在时分流 viewGrid 多视图组合（views 与 marks 互斥），各子视图以
+*   child 模式递归构建——host 权属字段（tooltip/pointer/keyboard/focus/focusRing）
+*   归外层组合定义持有（官方 assertChildDefinition 拒绝子 view 携带），child 模式
+*   下显式声明即抛错；theme 仅携带 spec 差异（defaultChartTheme.background 会触发
+*   库拒绝，外层 mergeTheme 负责补齐缺省）
 */
 /** color.legend 声明 → 图例实例；true 等价 { kind:'color' } 缺省配置 */
 function translateLegend(legend) {
-	const { kind, label, placement, itemWidth, steps, width } = legend === true ? {} : legend;
+	const { kind, label, placement, itemWidth, steps, width, items: itemSpec } = legend === true ? {} : legend;
 	if (kind === "gradient") {
 		const gradient = {};
 		if (label !== void 0) gradient.label = label;
@@ -1144,6 +1467,15 @@ function translateLegend(legend) {
 	if (placement !== void 0) items.placement = placement;
 	if (itemWidth !== void 0) items.itemWidth = itemWidth;
 	if (width !== void 0) items.width = width;
+	if (itemSpec !== void 0) {
+		const itemOptions = {};
+		if (itemSpec.justify !== void 0) itemOptions.justify = itemSpec.justify;
+		if (itemSpec.gap !== void 0) itemOptions.gap = itemSpec.gap;
+		if (itemSpec.rowGap !== void 0) itemOptions.rowGap = itemSpec.rowGap;
+		if (itemSpec.indicator !== void 0) itemOptions.indicator = itemSpec.indicator;
+		if (itemSpec.label !== void 0) itemOptions.label = itemSpec.label;
+		items.items = colorLegendItems(itemOptions);
+	}
 	return colorLegend(items);
 }
 /**
@@ -1163,7 +1495,8 @@ function translateTooltip(tooltip$1) {
 		"visibility",
 		"anchor",
 		"sort",
-		"items"
+		"items",
+		"className"
 	]) if (tooltip$1[key] !== void 0) options[key] = tooltip$1[key];
 	return {
 		use: tooltip,
@@ -1188,7 +1521,7 @@ function coerceTemporalChannels(spec, table) {
 		if (!set) fieldsByDataset.set(name, set = /* @__PURE__ */ new Set());
 		set.add(field);
 	};
-	for (const mark of spec.marks) {
+	for (const mark of spec.marks ?? []) {
 		if (xTemporal) for (const f of [
 			"x",
 			"x1",
@@ -1220,57 +1553,69 @@ function coerceTemporalChannels(spec, table) {
 	return changed ? next : table;
 }
 /**
-* 单 spec → definition 核心（facet 子 spec 复用）：返回原始 spec 对象而非
-* defineChart 产物——facet chart 回调要求返回 ChartSpec 字面量形态。
+* 单 spec → definition 核心（facet 子 spec、viewGrid 子视图复用）：返回原始 spec
+* 对象而非 defineChart 产物——facet chart 回调要求返回 ChartSpec 字面量形态。
 * rowsOverride：facet 分组行注入（子 spec marks 未声明 data 时绑定分组行）。
+* mode 'child'：viewGrid 子视图构建——剥除 host 权属字段（见文件头约定）。
 */
-function buildDefinition(spec, datasets, rowsOverride) {
+function buildDefinition(spec, datasets, rowsOverride, mode = "host") {
 	const base = { ...datasets };
 	if (rowsOverride !== void 0) base.rows = rowsOverride;
 	const table = coerceTemporalChannels(spec, spec.transforms?.length ? applyTransforms(spec.transforms, base) : base);
+	const markSpecs = spec.marks ?? [];
 	const marks = [];
 	let derivedXDomain;
 	let derivedYDomain;
-	let polarOnly = spec.marks.length > 0;
-	for (const mark of spec.marks) {
+	let polarOnly = markSpecs.length > 0;
+	let geoOnly = markSpecs.length > 0;
+	const pushMark = (specMark, runtimeMark) => {
+		marks.push(specMark.decorative === true ? decorative(runtimeMark) : runtimeMark);
+	};
+	for (const mark of spec.marks ?? []) {
 		const bound = rowsOverride !== void 0 && mark.data === void 0 ? {
 			...mark,
 			data: "rows"
 		} : mark;
 		if (!POLAR_FAMILY_TYPES.has(bound.type)) polarOnly = false;
-		if (bound.type === "polar") marks.push(translatePolar(bound, table));
-		else if (bound.type === "pie") marks.push(translatePie(bound, table));
+		if (bound.type !== "geoShape") geoOnly = false;
+		if (bound.type === "polar") pushMark(bound, translatePolar(bound, table));
+		else if (bound.type === "pie") pushMark(bound, translatePie(bound, table));
 		else if (COMPOSITE_TYPES.has(bound.type)) {
-			const result = translateCompositeMark(bound, table, (child, rows) => buildDefinition(child, void 0, rows));
-			marks.push(...result.marks);
+			const result = translateCompositeMark(bound, table, (child, rows) => buildDefinition(child, table, rows));
+			for (const expanded of result.marks) pushMark(bound, expanded);
 			if (result.xDomain) derivedXDomain = result.xDomain;
 			if (result.yDomain) derivedYDomain = result.yDomain;
-		} else marks.push(translateMark(bound, table));
+		} else pushMark(bound, translateMark(bound, table));
 	}
-	const definition = {
+	if (mode === "child" && spec.theme?.background !== void 0) throw new Error("translateViewGrid 子视图不得声明 theme.background（库拒绝子图持有场景背景；背景用子图内普通 mark 表达）");
+	if (mode === "child" && spec.gradients !== void 0) throw new Error("translateViewGrid 子视图不得声明 gradients（host 权属渐变资源，配置在外层 spec）");
+	const theme = mode === "child" ? spec.theme === void 0 ? void 0 : { ...spec.theme } : {
+		...defaultChartTheme,
+		...spec.theme
+	};
+	const definition = theme === void 0 ? { marks } : {
 		marks,
-		theme: {
-			...defaultChartTheme,
-			...spec.theme
-		}
+		theme
 	};
-	const xSpec = spec.x === void 0 && polarOnly ? null : spec.x;
-	const ySpec = spec.y === void 0 && polarOnly ? null : spec.y;
+	const axisless = polarOnly || geoOnly;
+	const xSpec = spec.x === void 0 && axisless ? null : spec.x;
+	const ySpec = spec.y === void 0 && axisless ? null : spec.y;
+	const scales = {};
 	const x = translateAxis(xSpec ?? void 0, "point");
 	const y = translateAxis(ySpec ?? void 0, "linear");
-	if (xSpec !== null && x) definition.x = x;
-	if (xSpec === null) definition.x = null;
-	if (ySpec !== null && y) definition.y = y;
-	if (ySpec === null) definition.y = null;
-	if (derivedXDomain && spec.x?.scale?.domain === void 0) definition.x = {
-		...definition.x,
+	scales.x = xSpec === null ? null : x;
+	scales.y = ySpec === null ? null : y;
+	definition.scales = scales;
+	if (derivedXDomain && spec.x?.scale?.domain === void 0) scales.x = {
+		...x,
 		scale: scaleLinear().domain(derivedXDomain)
 	};
-	if (derivedYDomain && spec.y?.scale?.domain === void 0) definition.y = {
-		...definition.y,
+	if (derivedYDomain && spec.y?.scale?.domain === void 0) scales.y = {
+		...y,
 		scale: scaleLinear().domain(derivedYDomain)
 	};
 	if (spec.margin !== void 0) definition.margin = spec.margin;
+	if (spec.gradients !== void 0) definition.gradients = spec.gradients;
 	if (spec.guides !== void 0) definition.guides = spec.guides;
 	else if (polarOnly) definition.guides = false;
 	if (spec.clip !== void 0) definition.clip = spec.clip;
@@ -1281,10 +1626,27 @@ function buildDefinition(spec, datasets, rowsOverride) {
 		if (spec.color.legend !== void 0) color.legend = translateLegend(spec.color.legend);
 		definition.color = color;
 	}
+	if (mode === "child") {
+		for (const key of [
+			"tooltip",
+			"pointer",
+			"keyboard",
+			"focusRing",
+			"focus",
+			"motion"
+		]) if (spec[key] !== void 0) throw new Error(`translateViewGrid 子视图不得声明 "${key}"（host 权属字段，配置在外层 spec）`);
+		return definition;
+	}
 	if (spec.pointer !== void 0) definition.pointer = spec.pointer;
 	if (spec.keyboard !== void 0) definition.keyboard = spec.keyboard;
 	if (spec.focusRing !== void 0) definition.focusRing = spec.focusRing;
 	if (spec.focus !== void 0) definition.focus = spec.focus;
+	if (spec.motion !== void 0) {
+		const timing = {};
+		if (spec.motion.transition !== void 0) timing.transition = spec.motion.transition;
+		if (spec.motion.delay !== void 0) timing.delay = spec.motion.delay;
+		definition.motion = timing;
+	}
 	const tooltip$2 = spec.tooltip === void 0 ? tooltip : translateTooltip(spec.tooltip);
 	if (tooltip$2 !== void 0) definition.tooltip = tooltip$2;
 	return definition;
@@ -1294,9 +1656,98 @@ function buildDefinition(spec, datasets, rowsOverride) {
 * datasets：命名数据集表（数据顶层化契约），marks 内字符串引用在此解析。
 */
 function translateChartSpec(spec, datasets) {
+	if (spec.views !== void 0) {
+		if (spec.marks?.length) throw new Error("translateChartSpec: views 与 marks 互斥——viewGrid 顶层不直接绘制 marks，图元属于各子视图");
+		return defineChart(translateViewGrid(spec, datasets, {
+			buildChild: (child, table) => defineChart(buildDefinition(child, table, void 0, "child")),
+			applyHost: (composed, outer) => {
+				const hosted = {
+					...composed,
+					theme: {
+						...defaultChartTheme,
+						...outer.theme
+					}
+				};
+				const tooltip$3 = outer.tooltip === void 0 ? tooltip : translateTooltip(outer.tooltip);
+				if (tooltip$3 !== void 0) hosted.tooltip = tooltip$3;
+				return hosted;
+			}
+		}));
+	}
 	return defineChart(buildDefinition(spec, datasets));
 }
 //#endregion
+//#region src/chart/src/motion-chart.vue
+const _hoisted_1 = ["innerHTML"];
+const _sfc_main$6 = /*@__PURE__*/ defineComponent({
+	__name: "motion-chart",
+	props: {
+		definition: {},
+		ariaLabel: {},
+		motionOptions: {},
+		height: {},
+		width: {},
+		aspectRatio: {},
+		className: {}
+	},
+	setup(__props) {
+		const props = __props;
+		const idPrefix = `ts-chart-${useId().replaceAll(/[^a-zA-Z0-9_-]/g, "")}`;
+		const hostStyle = computed(() => ({
+			position: "relative",
+			width: props.width === void 0 ? "100%" : `${props.width}px`,
+			height: props.height ?? (props.aspectRatio === void 0 ? 320 : void 0),
+			aspectRatio: props.height === void 0 ? props.aspectRatio : void 0
+		}));
+		/** host options 组装:与库 vue adapter toHostOptions 同构,renderer 固定为 motion() */
+		function toHostOptions() {
+			return {
+				definition: props.definition,
+				ariaLabel: props.ariaLabel,
+				height: props.height,
+				width: props.width,
+				aspectRatio: props.aspectRatio,
+				className: props.className,
+				idPrefix,
+				renderer: motion({
+					initial: props.motionOptions?.initial ?? "always",
+					resize: props.motionOptions?.resize
+				})
+			};
+		}
+		const adapter = createChartRendererAdapter(toHostOptions());
+		const initialMarkup = adapter.prerender();
+		const container = ref();
+		onMounted(() => {
+			if (!container.value) return;
+			adapter.update(toHostOptions());
+			adapter.mount(container.value);
+		});
+		watch(() => [
+			props.definition,
+			props.height,
+			props.width,
+			props.aspectRatio
+		], () => adapter.update(toHostOptions()));
+		onBeforeUnmount(() => adapter.destroy());
+		return (_ctx, _cache) => {
+			return openBlock(), createElementBlock("div", {
+				class: "ts-chart-host",
+				style: normalizeStyle(hostStyle.value)
+			}, [createCommentVNode(" 首帧 markup 只注入一次：mount 后 DOM 由 motion renderer 接管（含动画态),\n         若随重渲染重设 innerHTML 会摧毁动画状态，故用非响应式常量 "), createElementVNode("div", {
+				ref_key: "container",
+				ref: container,
+				class: "ts-chart-surface",
+				style: {
+					"width": "100%",
+					"height": "100%"
+				},
+				innerHTML: unref(initialMarkup)
+			}, null, 8, _hoisted_1)], 4);
+		};
+	}
+});
+//#endregion
 //#region src/chart/src/index.vue
 const _sfc_main$5 = /*@__PURE__*/ defineComponent({
 	name: "CxTanstackChartsChart",
@@ -1308,18 +1759,28 @@ const _sfc_main$5 = /*@__PURE__*/ defineComponent({
 		const { spec, datasets, hostProps, ariaLabel } = useChartProps(attrs);
 		const definition = computed(() => translateChartSpec(spec.value, datasets.value));
 		const isStreaming = computed(() => streamingFields(attrs).includes("definition"));
+		const hasStreamingFields = computed(() => streamingFields(attrs).length > 0);
+		const hasPlaceholderGeometry = computed(() => !hasStreamingFields.value && isPlaceholderChartRender(spec.value, datasets.value));
 		const skeletonHeight = computed(() => {
 			const h = Number(attrs.height);
 			return Number.isFinite(h) && h > 0 ? h : 320;
 		});
 		return (_ctx, _cache) => {
-			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根（host + tooltip Teleport），testid/BEM 类须由本层 wrapper 承担 "), createElementVNode("div", {
-				class: normalizeClass(unref(ns).b()),
+			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根（host + tooltip Teleport），testid/BEM 类须由本层 wrapper 承担。\n       cx-charts 为主题桥作用域类（cx-comps charts-theme 映射 design token 到 --ts-chart-N/--chart-N）：\n       随组件自动声明，宿主无需手动加类——shadcn 系 spec 的 var(--chart-N, ...) 引用在此获得色板 "), createElementVNode("div", {
+				class: normalizeClass([unref(ns).b(), "cx-charts"]),
 				"data-testid": "cx-tanstack-charts-chart"
-			}, [createCommentVNode(" definition 未闭合期间骨架占位：空壳帧的空 marks 只渲染不可见空 svg，无反馈等同未渲染 "), isStreaming.value ? (openBlock(), createBlock(_sfc_main$6, {
+			}, [createCommentVNode(" definition 未闭合期间骨架占位：空壳帧的空 marks 只渲染不可见空 svg，无反馈等同未渲染 "), isStreaming.value ? (openBlock(), createBlock(_sfc_main$8, {
 				key: 0,
 				height: skeletonHeight.value
-			}, null, 8, ["height"])) : (openBlock(), createBlock(unref(Chart), mergeProps({ key: 1 }, unref(hostProps), {
+			}, null, 8, ["height"])) : hasPlaceholderGeometry.value ? (openBlock(), createElementBlock(Fragment, { key: 1 }, [createCommentVNode(" 终态占位几何空态：全部 GeoJSON 数据集均占位/缺失时渲染必为空壳,显式降级为空态反馈 "), createVNode(_sfc_main$7, { height: skeletonHeight.value }, null, 8, ["height"])], 2112)) : unref(spec).motion !== void 0 ? (openBlock(), createElementBlock(Fragment, { key: 2 }, [createCommentVNode(" motion 声明走自研挂载分支：库 vue adapter 无 motion renderer 注入口子 "), createVNode(_sfc_main$6, mergeProps({
+				definition: definition.value,
+				ariaLabel: unref(ariaLabel),
+				"motion-options": unref(spec).motion
+			}, unref(hostProps)), null, 16, [
+				"definition",
+				"ariaLabel",
+				"motion-options"
+			])], 2112)) : (openBlock(), createBlock(unref(Chart), mergeProps({ key: 3 }, unref(hostProps), {
 				definition: definition.value,
 				"aria-label": unref(ariaLabel)
 			}), null, 16, ["definition", "aria-label"]))], 2)], 2112);
@@ -1382,8 +1843,9 @@ const initialRows = () => [
 ];
 var chart_default = define({
 	name: "图表",
-	description: "TanStack Charts 通用图表（cx-chart）：definition 为纯 JSON 声明式投影（marks/x/y/theme/tooltip 标量子集），数据顶层化——rows/nodes/links 命名数据集与 definition 平级、marks 内字符串引用，经翻译层组装渲染；scale/curve 以枚举声明，channel 为字段名。",
-	key: "cx-chart",
+	description: "TanStack Charts 通用图表（cx-data-chart）：definition 为纯 JSON 声明式投影（marks/x/y/theme/tooltip 标量子集），数据顶层化——rows/nodes/links 命名数据集与 definition 平级、marks 内字符串引用，经翻译层组装渲染；scale/curve 以枚举声明，channel 为字段名。旧 key cx-chart 经 aliasKeys 兼容（GenUI data-charts 轨改名，ADR 对齐），next major 移除。",
+	key: "cx-data-chart",
+	aliasKeys: ["cx-chart"],
 	icon: "i-tabler-chart-line",
 	component: _sfc_main$5,
 	props: {
@@ -1459,8 +1921,8 @@ const _sfc_main$4 = /*@__PURE__*/ defineComponent({
 		});
 		const definition = computed(() => translateChartSpec(spec.value));
 		return (_ctx, _cache) => {
-			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担 "), createElementVNode("div", {
-				class: normalizeClass(unref(ns).b()),
+			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担。\n       cx-charts 为主题桥作用域类：宿主无需手动加类（charts-theme 映射 design token 到 --ts-chart-N/--chart-N） "), createElementVNode("div", {
+				class: normalizeClass([unref(ns).b(), "cx-charts"]),
 				"data-testid": "cx-tanstack-charts-line"
 			}, [createVNode(unref(Chart), mergeProps(unref(hostProps), {
 				definition: definition.value,
@@ -1597,8 +2059,8 @@ const _sfc_main$3 = /*@__PURE__*/ defineComponent({
 		});
 		const definition = computed(() => translateChartSpec(spec.value));
 		return (_ctx, _cache) => {
-			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担 "), createElementVNode("div", {
-				class: normalizeClass(unref(ns).b()),
+			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担。\n       cx-charts 为主题桥作用域类：宿主无需手动加类（charts-theme 映射 design token 到 --ts-chart-N/--chart-N） "), createElementVNode("div", {
+				class: normalizeClass([unref(ns).b(), "cx-charts"]),
 				"data-testid": "cx-tanstack-charts-bar"
 			}, [createVNode(unref(Chart), mergeProps(unref(hostProps), {
 				definition: definition.value,
@@ -1681,8 +2143,8 @@ const _sfc_main$2 = /*@__PURE__*/ defineComponent({
 		});
 		const definition = computed(() => translateChartSpec(spec.value));
 		return (_ctx, _cache) => {
-			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担 "), createElementVNode("div", {
-				class: normalizeClass(unref(ns).b()),
+			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担。\n       cx-charts 为主题桥作用域类：宿主无需手动加类（charts-theme 映射 design token 到 --ts-chart-N/--chart-N） "), createElementVNode("div", {
+				class: normalizeClass([unref(ns).b(), "cx-charts"]),
 				"data-testid": "cx-tanstack-charts-area"
 			}, [createVNode(unref(Chart), mergeProps(unref(hostProps), {
 				definition: definition.value,
@@ -1782,8 +2244,8 @@ const _sfc_main$1 = /*@__PURE__*/ defineComponent({
 		});
 		const definition = computed(() => translateChartSpec(spec.value));
 		return (_ctx, _cache) => {
-			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担 "), createElementVNode("div", {
-				class: normalizeClass(unref(ns).b()),
+			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担。\n       cx-charts 为主题桥作用域类：宿主无需手动加类（charts-theme 映射 design token 到 --ts-chart-N/--chart-N） "), createElementVNode("div", {
+				class: normalizeClass([unref(ns).b(), "cx-charts"]),
 				"data-testid": "cx-tanstack-charts-dot"
 			}, [createVNode(unref(Chart), mergeProps(unref(hostProps), {
 				definition: definition.value,
@@ -1895,15 +2357,25 @@ function usePieChart(attrs) {
 			const clean = rows.filter((row) => row !== null && typeof row === "object" && Number.isFinite(Number(row[valueField])) && Number(row[valueField]) >= 0);
 			const slices = pie(clean, { value: (datum) => Number(datum[valueField]) });
 			const ratio = typeof attrs.innerRadiusRatio === "number" && Number.isFinite(attrs.innerRadiusRatio) ? Math.min(Math.max(attrs.innerRadiusRatio, 0), .95) : 0;
-			return defineChart({ marks: [polar({
-				inset: 8,
-				marks: [radialArc(slices, {
-					color: (datum) => String(datum[nameField]),
-					key: (datum) => String(datum[nameField]),
-					innerRadius: ratio > 0 ? ({ radius }) => radius * ratio : 0,
-					cornerRadius: 2
-				})]
-			})] });
+			return defineChart({
+				marks: [polar({
+					inset: 8,
+					scales: {
+						angle: null,
+						radius: null
+					},
+					marks: [radialArc(slices, {
+						color: (datum) => String(datum[nameField]),
+						key: (datum) => String(datum[nameField]),
+						innerRadius: ratio > 0 ? ({ radius }) => radius * ratio : 0,
+						cornerRadius: 2
+					})]
+				})],
+				scales: {
+					x: null,
+					y: null
+				}
+			});
 		}),
 		hostProps,
 		ariaLabel
@@ -1919,8 +2391,8 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 		const ns = useCxBEM("tanstack-charts-pie");
 		const { definition, hostProps, ariaLabel } = usePieChart(useAttrs());
 		return (_ctx, _cache) => {
-			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担 "), createElementVNode("div", {
-				class: normalizeClass(unref(ns).b()),
+			return openBlock(), createElementBlock(Fragment, null, [createCommentVNode(" 库根元素 inheritAttrs:false 且多根，testid/BEM 类由本层 wrapper 承担。\n       cx-charts 为主题桥作用域类：宿主无需手动加类（charts-theme 映射 design token 到 --ts-chart-N/--chart-N） "), createElementVNode("div", {
+				class: normalizeClass([unref(ns).b(), "cx-charts"]),
 				"data-testid": "cx-tanstack-charts-pie"
 			}, [createVNode(unref(Chart), mergeProps(unref(hostProps), {
 				definition: unref(definition),
@@ -2000,26 +2472,30 @@ var pie_default = define({
 *   arrayKey 恒为 'data'（单层字段名契约）；props 声明序通道字段（x/y/curve/
 *   name/value/innerRadiusRatio）前置、data 殿后——回放剧本序列化序使增量帧
 *   首行起即携带通道配置，尾随标量（height/ariaLabel）不入增量帧由终帧兜底。
-* - array 1 件：通用 chart 走数据顶层化契约，主数组是顶层 rows（逐行生长）；
-*   definition 序列化在 rows 前，rows 首行闭合时 definition 必然完整——图表
-*   以完整坐标系挂载、数据逐行生长（三段式：骨架→空坐标→行生长）。
+* - array 1 件：通用 chart 走通配主数组契约（arrayKey '*'）——data 下任意
+*   数组字段皆为主数组，逐字段按元素边界截断。图表数据形态多元：常规形态
+*   rows、关系型 nodes+links（桑基/力导向）、嵌套环 innerRows+outerRows、
+*   仪表 bandRows+tickRows、地图 land/sphere/graticule/route，通配使各形态
+*   统一获得流式效果且新增数据形态无需改触发器。definition 序列化在任何数据
+*   数组之前，首条数据闭合时坐标系必然完整——图表以完整坐标系挂载、数据逐条
+*   生长（三段式：骨架→空坐标→数据生长）。多数据集按序列化序接力生长
+*   （如 nodes 全量后 links 逐条），各自按自身传输进度截断、互不牵连。
 * - 不适用 0 件。计数校验：6 array + 0 scalar + 0 不适用（差集派生兜底）。
 *
 * produced 语义（增量提取器对中间态与终态走同一 buildPartial，实证
 * packages/stream/src/core/incremental.ts Step 5）：
-* - 出帧只由主数组匹配驱动；extraScanPaths（nodes/links）仅提供元素边界
-*   切分点，不驱动出帧——GenUI 契约据此锁死 rows 恒为主数据集在场
-*   （关系型图表 rows=节点行表、links 为边次数据集），无 rows 的 spec 永不
-*   出帧属契约外形态，由生成期校验门拦截。
-* - emptyPassthrough：rows=[] 空数组终态透传节点，由组件空态渲染接管，
-*   防流结束后 pending 永驻。
+* - 出帧由任一主数组的完整元素驱动；尚无完整元素时保持 pending（骨架期由
+*   渲染管线承担）。
+* - emptyPassthrough：任一数据数组闭合为空（如 rows=[]）时终态透传节点，
+*   由组件空态渲染接管，防流结束后 pending 永驻；判定据 parse 结果中的空
+*   数组字段（截断语义下「闭合的空数组」以 [] 在场、「未开始传输」缺席）。
 *
-* 骨架裁决：不设 skeletonFields——rows 首行闭合即出帧逐行生长，天然有实时
-* 反馈；首行前的 pending 期由渲染管线承担（与预设物料同语义），物料内骨架
+* 骨架裁决：不设 skeletonFields——首条数据闭合即出帧逐条生长，天然有实时
+* 反馈；首条前的 pending 期由渲染管线承担（与预设物料同语义），物料内骨架
 * 判定保留兼容上游 _cx_streaming 注入。
 *
 * fallback 从简：渲染链路不过 zod，包装层无模板直访（useAttrs 平铺 +
-* composable 全回退，缺席不 TypeError）；rows 缺席的中间态经翻译层
+* composable 全回退，缺席不 TypeError）；数据数组缺席的中间态经翻译层
 * resolveMarkData 回退空数组，translateChartSpec 组装不抛错（增量帧翻译
 * 实证进包内测试）。
 *
@@ -2038,47 +2514,56 @@ function keyOf(key) {
 	if (!comp) throw new Error(`tanstack-charts 物料定义缺失: ${key}`);
 	return comp._cx_meta.key;
 }
-const TANSTACK_CHARTS_STREAM_TRIGGERS = [{
-	key: keyOf("cx-chart"),
-	sections: [{
-		kind: "array",
-		arrayKey: "rows",
-		extraScanPaths: [[
-			"data",
-			"nodes",
-			"*"
-		], [
-			"data",
-			"links",
-			"*"
-		]]
-	}],
-	stateBranch: { emptyPassthrough: true },
-	frameStride: 10
-}, ...[
+const ARRAY_PRESET_KEYS = [
 	"cx-tanstack-charts-line",
 	"cx-tanstack-charts-bar",
 	"cx-tanstack-charts-area",
 	"cx-tanstack-charts-dot",
 	"cx-tanstack-charts-pie"
-].map((key) => ({
-	key: keyOf(key),
+];
+const CHART_STREAM_TRIGGER = {
+	key: keyOf("cx-data-chart"),
 	sections: [{
 		kind: "array",
-		arrayKey: "data"
+		arrayKey: "*"
 	}],
+	stateBranch: { emptyPassthrough: true },
 	frameStride: 10
-}))];
+};
+const TANSTACK_CHARTS_STREAM_TRIGGERS = [
+	CHART_STREAM_TRIGGER,
+	{
+		...CHART_STREAM_TRIGGER,
+		key: "cx-chart"
+	},
+	...ARRAY_PRESET_KEYS.map((key) => ({
+		key: keyOf(key),
+		sections: [{
+			kind: "array",
+			arrayKey: "data"
+		}],
+		frameStride: 10
+	}))
+];
 /** 装配 TanStack Charts 物料的 trigger 注册表（size 恒 6） */
 function createTanstackChartsTriggerRegistry() {
 	const registry = createTriggerRegistry();
 	for (const config of TANSTACK_CHARTS_STREAM_TRIGGERS) registry.register(config.key, compileTrigger(config));
 	return registry;
 }
-/** 增量节点的主数组（回放计数展示用）；非数组增长型物料或数组缺席时返回 null */
+/**
+* 增量节点的主数组（回放计数展示用）；非数组增长型物料或数组缺席时返回 null。
+* 通配主数组形态（arrayKey '*'）无单一主数组，取最长数组字段为主数据集
+* （如桑基的 links 之于 nodes）；并列时取序列化序靠前者。
+*/
 function mainArrayOf(node) {
 	const section = TANSTACK_CHARTS_STREAM_TRIGGERS.find((c) => c.key === node.key)?.sections.find((s) => s.kind === "array");
 	if (!section || section.kind !== "array") return null;
+	if (section.arrayKey === "*") {
+		let longest = null;
+		for (const value of Object.values(node.data ?? {})) if (Array.isArray(value) && (longest === null || value.length > longest.length)) longest = value;
+		return longest;
+	}
 	const arr = node.data?.[section.arrayKey];
 	return Array.isArray(arr) ? arr : null;
 }
@@ -2099,4 +2584,4 @@ const CxTanstackChartsBundle = {
 	materials: [...CxTanstackCharts]
 };
 //#endregion
-export { COMPOSITE_TYPES, CX_CHART_CURVE_NAMES, CxTanstackCharts, area_default as CxTanstackChartsArea, bar_default as CxTanstackChartsBar, CxTanstackChartsBundle, chart_default as CxTanstackChartsChart, dot_default as CxTanstackChartsDot, line_default as CxTanstackChartsLine, pie_default as CxTanstackChartsPie, POLAR_FAMILY_TYPES, TANSTACK_CHARTS_STREAM_TRIGGERS, applyTransforms, createTanstackChartsTriggerRegistry, mainArrayOf, resolveMarkData, translateAxis, translateChartSpec, translateCompositeMark, translateCurve, translateMark, translateOutputs, translatePie, translatePolar, translateReduce, translateScale, translateTransform };
+export { COMPOSITE_TYPES, CX_CHART_CURVE_NAMES, CxTanstackCharts, area_default as CxTanstackChartsArea, bar_default as CxTanstackChartsBar, CxTanstackChartsBundle, chart_default as CxTanstackChartsChart, dot_default as CxTanstackChartsDot, line_default as CxTanstackChartsLine, pie_default as CxTanstackChartsPie, POLAR_FAMILY_TYPES, TANSTACK_CHARTS_STREAM_TRIGGERS, applyTransforms, createTanstackChartsTriggerRegistry, isPlaceholderChartRender, isPlaceholderGeometryDataset, mainArrayOf, resolveMarkData, resolveRScaleOption, translateAxis, translateChartSpec, translateCompositeMark, translateCurve, translateMark, translateOutputs, translatePie, translatePolar, translateReduce, translateScale, translateTransform, warnMissingGeometryDataset, warnPlaceholderGeometry };