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

package/dist/index.mjs

@@ -26,6 +26,7 @@ import { sankeyDiagram } from "@tanstack/charts/network/sankey";
 import { geoAlbersUsa, geoEqualEarth, 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 { compileTrigger, createTriggerRegistry } from "@lionad/cx-stream";
 //#region src/shared/chart-skeleton.vue
 const _sfc_main$6 = /*@__PURE__*/ defineComponent({
@@ -588,7 +589,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") {
@@ -669,7 +670,11 @@ 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;
+	}
 	for (const key of CHANNEL_FLEX_KEYS) if (spec[key] !== void 0) options[key] = spec[key];
 	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];
@@ -761,11 +766,16 @@ function translatePolarGuide(spec) {
 	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;
 }
 /**
@@ -781,7 +791,7 @@ function translatePolar(spec, datasets, extraMarks = []) {
 	if (spec.inset !== void 0) options.inset = spec.inset;
 	if (spec.id !== void 0) options.id = spec.id;
 	const angle = translatePolarAxis(spec.angleAxis);
-	const radius = translatePolarAxis(spec.radiusAxis);
+	const radius = translatePolarAxis(spec.radiusAxis, { allowRange: true });
 	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() };
@@ -1118,6 +1128,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>）。
@@ -1128,6 +1163,11 @@ function translateCompositeMark(spec, datasets, translateChild) {
 *   置 null 显式无轴（库对 polar mark 的 scale 类型为 never，缺省 axis 注入会抛错）
 * - 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) {
@@ -1189,7 +1229,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",
@@ -1221,22 +1261,24 @@ 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;
+	let polarOnly = markSpecs.length > 0;
 	const pushMark = (specMark, runtimeMark) => {
 		marks.push(specMark.decorative === true ? decorative(runtimeMark) : runtimeMark);
 	};
-	for (const mark of spec.marks) {
+	for (const mark of spec.marks ?? []) {
 		const bound = rowsOverride !== void 0 && mark.data === void 0 ? {
 			...mark,
 			data: "rows"
@@ -1245,18 +1287,20 @@ function buildDefinition(spec, datasets, rowsOverride) {
 		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));
+			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 pushMark(bound, translateMark(bound, table));
 	}
-	const definition = {
+	if (mode === "child" && spec.theme?.background !== void 0) throw new Error("translateViewGrid 子视图不得声明 theme.background（库拒绝子图持有场景背景；背景用子图内普通 mark 表达）");
+	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;
@@ -1285,6 +1329,16 @@ 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"
+		]) 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;
@@ -1298,6 +1352,24 @@ 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

package/dist/shared/translate/index.d.ts

@@ -2,9 +2,9 @@
  * 声明式 JSON → TanStack Charts 运行时定义的翻译层（桶文件）。
  * 模块分工：types（声明式契约）/ curve / scale / axis / mark（基础+spatial）/
  * transforms（数据预处理管道）/ polar（极坐标族）/ composite（七类命名复合）/
- * definition（translateChartSpec 组装入口）。
+ * view（viewGrid 多视图组合）/ definition（translateChartSpec 组装入口）。
  */
-export type { CxChartAxisSpec, CxChartCurveName, CxChartDatasets, CxChartForceSpec, CxChartLayoutSpec, CxChartMarkSpec, CxChartMarkType, CxChartPolarGuideSpec, CxChartReduce, CxChartScaleSpec, CxChartSpec, CxChartTransformOutputs, CxChartTransformSpec, } from './types';
+export type { CxChartAxisSpec, CxChartCurveName, CxChartDatasets, CxChartForceSpec, CxChartLayoutSpec, CxChartMarkSpec, CxChartMarkType, CxChartPolarGuideSpec, CxChartReduce, CxChartScaleSpec, CxChartSpec, CxChartTransformOutputs, CxChartTransformSpec, CxChartViewGridSpec, CxChartViewItem, CxChartViewLink, CxChartViewTrack, } from './types';
 export { CX_CHART_CURVE_NAMES, translateCurve } from './curve';
 export { translateScale } from './scale';
 export { translateAxis } from './axis';

package/dist/shared/translate/types.d.ts

@@ -43,6 +43,12 @@ export interface CxChartAxisSpec {
     nice?: boolean | number;
     reverse?: boolean;
     grid?: boolean;
+    /**
+     * 半径像素 range 的比例对（相对 polar 最终半径，0–1），仅 polar 容器的
+     * radiusAxis 消费；物化为官方 PolarLength 回调数组（resize 时随最终半径重解析）。
+     * 用途：rose/径向条等需要「语义零映射到内径偏移」而非物理圆心的场景。
+     */
+    range?: [number, number];
     axis?: false | {
         label?: string;
         ticks?: {
@@ -89,7 +95,8 @@ export type CxChartMarkType = 'lineY' | 'lineX' | 'areaY' | 'areaX' | 'barY' | '
 /**
  * 单 mark 声明式。平铺契约（LLM 友好）：专有标量字段全部可选、按名透传，
  * 不适用的字段被对应工厂忽略；channel 只接受字段名字符串（弹性 channel
- * angle/radius/width/height/length/rotate/r 另接受数值常量）。
+ * angle/radius/width/height/length/rotate/r 另接受数值常量；x1/y1 仅在
+ * rect 基线场景接受数值常量——对应官方直方图零基线写法 y1:()=>0）。
  */
 export interface CxChartMarkSpec {
     type: CxChartMarkType;
@@ -110,8 +117,8 @@ export interface CxChartMarkSpec {
     decorative?: boolean;
     x?: string;
     y?: string;
-    x1?: string;
-    y1?: string;
+    x1?: string | number;
+    y1?: string | number;
     x2?: string;
     y2?: string;
     z?: string;
@@ -423,8 +430,49 @@ export type CxChartTransformSpec = {
 };
 /** 命名数据集表：物料 data 顶层除 definition 外的数组字段（GenUI 契约 rows/nodes/links） */
 export type CxChartDatasets = Record<string, readonly unknown[] | undefined>;
+/** viewGrid 网格轨道：size 固定像素 / grow 按比例分配剩余空间（min/max 钳制） */
+export type CxChartViewTrack = {
+    id: string;
+    size: number;
+} | {
+    id: string;
+    grow: number;
+    min?: number;
+    max?: number;
+};
+/** viewGrid 轴链接目标：share 共享 scale（domain/序/方向/bandwidth 须一致，不一致显式失败）；align 仅对齐 plot 端点、domain 各自独立 */
+export interface CxChartViewLink {
+    x?: string;
+    y?: string;
+}
+export interface CxChartViewItem {
+    id: string;
+    /** 轨道引用：row/column 分别指向 views.rows/views.columns 的轨道 id */
+    row: string;
+    column: string;
+    share?: CxChartViewLink;
+    align?: CxChartViewLink;
+    /**
+     * 子视图 spec（marks/x/y/color/margin/guides/transforms 等归属子图）；
+     * host 权属字段（tooltip/pointer/keyboard/focus/focusRing）归外层组合定义，
+     * 子视图声明即拒绝（官方 assertChildDefinition 契约）；不支持嵌套 views。
+     */
+    chart: CxChartSpec;
+}
+/** viewGrid 多视图组合（非重叠网格；叠层/内嵌等组合形态官方 composeViews 支持、契约暂不暴露） */
+export interface CxChartViewGridSpec {
+    rows: CxChartViewTrack[];
+    columns: CxChartViewTrack[];
+    gap?: number;
+    rowGap?: number;
+    columnGap?: number;
+    items: CxChartViewItem[];
+}
 export interface CxChartSpec {
-    marks: CxChartMarkSpec[];
+    /** viewGrid 顶层省略（views 与 marks 互斥）；其余场景必填 */
+    marks?: CxChartMarkSpec[];
+    /** 多视图组合：存在时 marks 须为空，各子视图在网格单元内独立成图、共享外层 host */
+    views?: CxChartViewGridSpec;
     x?: CxChartAxisSpec | null;
     y?: CxChartAxisSpec | null;
     theme?: Partial<ChartTheme>;

package/dist/shared/translate/view.d.ts

@@ -0,0 +1,16 @@
+import type { CxChartDatasets, CxChartSpec } from './types';
+/**
+ * viewGrid 多视图组合：spec.views → 官方 viewGrid（命名视图 + 网格轨道 + 轴链接）。
+ *
+ * 权属分界（官方 assertChildDefinition 契约）：子 view 保留 marks/scales/guides/
+ * margin/color/clip；host 字段（tooltip/keyboard/pointer/focus/focusRing/motion/
+ * gradients/theme.background）只能由外层组合定义持有，子 view 携带即被库拒绝。
+ * 子 view 经 buildChild 以 child 模式递归构建（剥除 host 字段，见 definition.ts）；
+ * 顶层 host 字段（theme 合并、tooltip 缺省注入）由 applyHost 施加于组合产物。
+ * hooks 回调注入保持依赖单向（definition.ts → view.ts，同 composite 先例）。
+ */
+export interface CxChartViewGridHooks {
+    buildChild: (child: CxChartSpec, datasets: CxChartDatasets | undefined) => unknown;
+    applyHost: (composed: Record<string, unknown>, spec: CxChartSpec) => Record<string, unknown>;
+}
+export declare function translateViewGrid(spec: CxChartSpec, datasets: CxChartDatasets | undefined, hooks: CxChartViewGridHooks): Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionad/cx-comps-tanstack-charts",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "description": "cx material components wrapping TanStack Charts (@tanstack/charts/vue)",
   "keywords": [
     "charts",