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

package/dist/shared/chart-empty.vue.d.ts

@@ -0,0 +1,8 @@
+type __VLS_Props = {
+    height?: number;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    height: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,32 @@
+import type { CxChartDatasets, CxChartSpec } from './types';
+/**
+ * 单数据集整体不可渲染判定：Feature 数组且全部条目几何缺失或为占位字符串。
+ * 混合场景（部分真实几何）不算——部分数据仍可渲染，整体空态会误杀；
+ * geometry: null 是 GeoJSON 合法形态，但全部条目皆 null 时渲染结果同为空壳。
+ */
+export declare function isPlaceholderGeometryDataset(rows: readonly unknown[]): boolean;
+/**
+ * 组件层空态判定：整图渲染必然空壳时为 true。
+ *
+ * 判定范围收敛在纯 geoShape 图（全部 marks 均为 geoShape）：geoShape 无独立于数据
+ * 的渲染力（数据不可用即零图元），而其余 mark 类型总有独立形状；复合图只要存在
+ * 一个非 geoShape mark 或一个可用 geo 数据集就返回 false，防「部分可渲染却整体
+ * 空态」的误杀。覆盖三种不可用形态：
+ * - 命名数据集占位（geometry 占位字符串/全 null）
+ * - 命名数据集缺失（只引用不提供，resolveMarkData 回退空数组）
+ * - mark 内联 data 数组本身占位（不占命名数据集表的形态）
+ */
+export declare function isPlaceholderChartRender(spec: CxChartSpec | undefined, datasets: CxChartDatasets | undefined): boolean;
+/**
+ * 翻译期占位几何警告：数据集整体占位时 console.warn 指出空壳根因与修复方向。
+ * 只挂在 geoShape（占位字符串的高发地——示意 spec 的外部轮廓数据集）；普通 mark
+ * 的数据集在途是流式常态，warn 会成噪音。WeakSet 按引用去重，数据集内容更新
+ * （新引用）视为新数据集重新警告。
+ */
+export declare function warnPlaceholderGeometry(rows: readonly unknown[], datasetName: string | undefined, markType: string): void;
+/**
+ * 翻译期数据集缺失警告：geoShape 按名引用了数据集表中不存在的键——与占位字符串
+ * 同为「渲染空壳无反馈」的事故形态，区别只在根因（未提供 vs 提供了占位）。
+ * 按名去重（缺失数据集无内容引用可作 WeakSet 键），命名数据集到达后不再命中。
+ */
+export declare function warnMissingGeometryDataset(datasetName: string, markType: string): void;

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

@@ -2,13 +2,14 @@
  * 声明式 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';
-export { resolveMarkData, translateMark } from './mark';
+export { isPlaceholderChartRender, isPlaceholderGeometryDataset, warnMissingGeometryDataset, warnPlaceholderGeometry, } from './geometry';
+export { resolveMarkData, resolveRScaleOption, translateMark } from './mark';
 export { applyTransforms, translateOutputs, translateReduce, translateTransform } from './transforms';
 export { POLAR_FAMILY_TYPES, translatePie, translatePolar } from './polar';
 export { COMPOSITE_TYPES, translateCompositeMark } from './composite';

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

@@ -7,6 +7,15 @@ import type { CxChartDatasets, CxChartMarkSpec } from './types';
  * fallback 从简」契约一致）；笔误显式化归生成期校验（spec 渲染断言门）。
  */
 export declare function resolveMarkData(data: readonly unknown[] | string | undefined, datasets: CxChartDatasets | undefined): readonly unknown[];
+/**
+ * rScale 注入：库缺省 rScale 是恒等映射（字段原始值直接当像素半径，大数据值
+ * 渲染为巨泡）——r 为字段名时缺省注入 sqrt 映射（半径∝√值 ⇒ 面积∝值，气泡图
+ * 感知编码约定），domain 由库从数据推断（includeZero）。数值常量 r 是显式像素
+ * 意图不缩放；spec.rScale.range 覆盖缺省上下界。
+ * 工厂形态（无 copy 的函数）让库推断 domain；实例形态库不推断（scale-input 契约）。
+ * 返回 undefined 表示不注入（消费方判空挂 options）。
+ */
+export declare function resolveRScaleOption(spec: CxChartMarkSpec): unknown;
 /**
  * 单 mark 声明式 → ChartMark；多余样式键对 mark 工厂无害（按名读取）。
  * polar/pie/sankey 等容器与复合 type 不在此处（polar.ts / composite.ts 分支处理）。

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

@@ -4,6 +4,9 @@ import type { CxChartDatasets, CxChartMarkSpec } from './types';
  * 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 占位。
  */
 export declare function translatePolar(spec: CxChartMarkSpec, datasets: CxChartDatasets | undefined, extraMarks?: readonly unknown[]): ChartMark<unknown, any, any>;
 /**

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

@@ -38,13 +38,65 @@ export type CxChartScaleSpec = {
     kind: 'ordinal';
     domain?: string[];
 };
+/** 网格线/轴基线渲染中立描边样式（官方 ChartGuideLineStyle 的 JSON 投影） */
+export interface CxChartGuideLineStyle {
+    stroke?: string;
+    strokeOpacity?: number;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    lineCap?: 'butt' | 'round' | 'square';
+}
+/** 渐变 stop（0–1 objectBoundingBox；offset 回退时由渲染器向前钳制） */
+export interface CxChartGradientStop {
+    offset: number;
+    color: string;
+    opacity?: number;
+}
+/** 线性渐变：type 可省；坐标缺省垂直自底向上 (0,1)→(0,0) */
+export interface CxChartLinearGradient {
+    type?: 'linear';
+    id: string;
+    stops: CxChartGradientStop[];
+    x1?: number;
+    y1?: number;
+    x2?: number;
+    y2?: number;
+}
+/** 径向渐变：type 必填；cx/cy/r 缺省 0.5，fx/fy 缺省继承中心 */
+export interface CxChartRadialGradient {
+    type: 'radial';
+    id: string;
+    stops: CxChartGradientStop[];
+    cx?: number;
+    cy?: number;
+    r?: number;
+    fx?: number;
+    fy?: number;
+}
 export interface CxChartAxisSpec {
     scale?: CxChartScaleSpec;
     nice?: boolean | number;
     reverse?: boolean;
-    grid?: boolean;
+    /** true 画缺省网格；对象形态覆盖网格线描边呈现（0.18 ChartGuideLineStyle） */
+    grid?: boolean | CxChartGuideLineStyle;
+    /**
+     * 半径像素 range 的比例对（相对 polar 最终半径，0–1），仅 polar 容器的
+     * radiusAxis 消费；物化为官方 PolarLength 回调数组（resize 时随最终半径重解析）。
+     * 用途：rose/径向条等需要「语义零映射到内径偏移」而非物理圆心的场景。
+     */
+    range?: [number, number];
     axis?: false | {
-        label?: string;
+        /** 轴标题：字符串缺省呈现；对象形态定制字号/字重/填充/偏移（0.18 ChartAxisLabelOptions） */
+        label?: string | {
+            text: string;
+            offset?: number | 'auto';
+            fontSize?: number;
+            fontWeight?: number;
+            fill?: string;
+            opacity?: number;
+        };
+        /** 轴基线：缺省不画；true 画缺省基线，对象形态覆盖基线描边（0.18 axis.line） */
+        line?: boolean | CxChartGuideLineStyle;
         ticks?: {
             count?: number;
             size?: number;
@@ -89,7 +141,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 +163,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;
@@ -119,8 +172,23 @@ export interface CxChartMarkSpec {
     key?: string;
     text?: string;
     r?: string | number;
+    /**
+     * 半径缩放声明式（仅 r 为字段名时消费；数值常量 r 是显式像素意图，不缩放）。
+     * 库缺省 rScale 为恒等映射（原始值直接当像素半径），翻译层对字段名 r 缺省注入
+     * sqrt 面积映射（半径∝√值 ⇒ 面积∝值，气泡图感知编码约定），本字段覆盖其
+     * range 像素上下界；kind 不收（sqrt 是气泡半径的正确默认，线性半径会平方夸大差异）。
+     */
+    rScale?: {
+        range?: [number, number];
+    };
     angle?: string | number;
-    radius?: string | number;
+    /**
+     * 双语义：radial 系是 radius channel（字段名/数值常量）；直角 barX/barY 是圆角
+     * BarRadius——数值全角、[tl,tr,br,bl] 四角差异化（对象形态 {end,stack} 不收，
+     * 防与 channel 语义混淆）。cornerRadius 是 polar 族字段名（radialArc），直角系
+     * 由翻译层别名归一到本字段（显式 radius 优先）。
+     */
+    radius?: string | number | readonly [number, number, number, number];
     width?: string | number;
     height?: string | number;
     length?: string | number;
@@ -218,8 +286,12 @@ export interface CxChartMarkSpec {
     labelFontWeight?: number;
     orientation?: 'left' | 'right' | 'top' | 'bottom';
     nodeSize?: [number, number];
-    projection?: 'mercator' | 'orthographic' | 'naturalEarth1' | 'albersUsa' | 'equalEarth' | 'identity';
-    fit?: 'data' | 'sphere';
+    projection?: 'mercator' | 'orthographic' | 'naturalEarth1' | 'albersUsa' | 'equalEarth' | 'equirectangular' | 'identity' | {
+        $by: Record<string, 'mercator' | 'orthographic' | 'naturalEarth1' | 'albersUsa' | 'equalEarth' | 'equirectangular' | 'identity'>;
+    };
+    fit?: 'data' | 'sphere' | {
+        data: string;
+    };
     by?: string;
     axes?: 'outer' | 'cell';
     minWidth?: number;
@@ -236,6 +308,22 @@ export interface CxChartPolarGuideSpec {
     labels?: boolean;
     labelAngle?: number;
     labelOffset?: number;
+    id?: string;
+    className?: string;
+    labelClassName?: string;
+    stroke?: string;
+    strokeOpacity?: number;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    fill?: string;
+    fillOpacity?: number;
+    labelFill?: string;
+    labelFontSize?: number;
+    labelAnchor?: 'start' | 'middle' | 'end';
+    labelBaseline?: 'auto' | 'middle' | 'hanging';
+    labelDx?: number;
+    labelDy?: number;
+    labelRotate?: number;
 }
 /**
  * forceGraph 力集声明式：库 ForceDescriptor 的 JSON 子集。
@@ -421,10 +509,51 @@ export type CxChartTransformSpec = {
     startAngle?: number;
     endAngle?: number;
 };
-/** 命名数据集表：物料 data 顶层除 definition 外的数组字段（GenUI 契约 rows/nodes/links） */
+/** 命名数据集表：物料 data 顶层除 definition 外的数组字段全量分馏（rows 恒为主数据集，其余按语义自由命名：geo 的 sphere/land、分层图 innerRows/outerRows 等） */
 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>;
@@ -436,6 +565,12 @@ export interface CxChartSpec {
     };
     guides?: boolean;
     clip?: boolean;
+    /**
+     * 渐变资源（0.18 ChartGradient 投影）：mark 以 fill/stroke 'url(#id)' 引用。
+     * host 权属资源——views 子图声明即拒绝（官方 child 契约），归外层组合定义。
+     * 坐标与 stop offset 为 0–1 objectBoundingBox；linear 缺省垂直自底向上。
+     */
+    gradients?: (CxChartLinearGradient | CxChartRadialGradient)[];
     /** 数据预处理管道（顶层声明，marks 之前执行；产物注册进 datasets 表） */
     transforms?: CxChartTransformSpec[];
     /** color scale 声明式（domain/range 直可 JSON；legend 为图例声明） */
@@ -449,6 +584,24 @@ export interface CxChartSpec {
             itemWidth?: number;
             steps?: number;
             width?: number;
+            /** 条目子集定制（仅 kind:'color'；物化为 colorLegendItems，0.18 契约） */
+            items?: {
+                justify?: 'start' | 'center' | 'stretch';
+                gap?: number;
+                rowGap?: number;
+                indicator?: {
+                    shape?: 'dot' | 'square' | 'line' | 'line-dot';
+                    width?: number;
+                    height?: number;
+                    gap?: number;
+                };
+                label?: {
+                    fontSize?: number;
+                    fontWeight?: number;
+                    fill?: string;
+                    fillOpacity?: number;
+                };
+            };
         };
     };
     tooltip?: boolean | {
@@ -461,6 +614,9 @@ export interface CxChartSpec {
             y?: 'point' | 'pointer' | 'value' | 'group-center' | 'plot-top' | 'plot-center' | 'plot-bottom';
         };
         sort?: 'visual' | 'color-domain' | 'focus';
+        /** 追加到 tooltip 根元素的自定义类名(`ts-chart-tooltip <className>`),
+         *  供物料/宿主用 CSS 分化指示器等外壳样式 */
+        className?: string;
         items?: ('x' | 'y' | 'group' | {
             channel: 'x' | 'y' | 'group';
             label?: string;
@@ -471,6 +627,35 @@ export interface CxChartSpec {
     };
     pointer?: boolean;
     keyboard?: boolean;
-    focusRing?: boolean;
+    /** 焦点环：true/false 显隐；对象形态定制几何与描边填充（0.18 ChartFocusRingOptions） */
+    focusRing?: boolean | {
+        radius?: number;
+        fill?: string;
+        stroke?: string;
+        strokeWidth?: number;
+    };
     focus?: 'nearest' | 'nearest-x' | 'nearest-y' | 'group-x' | 'group-y';
+    /**
+     * 动效声明（可 JSON 化子集）。声明即走 motion 挂载分支：库 vue adapter 未暴露
+     * motion renderer 注入，cx 组件层自组装 renderer adapter。transition/delay 翻译为
+     * 库 definition.motion 的 chart 级默认时序；initial/resize 为 renderer 级选项。
+     * mark 级 per-datum motion 回调不可 JSON 化，不收。
+     */
+    motion?: {
+        transition?: {
+            type: 'tween';
+            duration?: number;
+            easing?: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';
+        } | {
+            type: 'spring';
+            stiffness?: number;
+            damping?: number;
+            mass?: number;
+            restSpeed?: number;
+            restDelta?: number;
+        };
+        delay?: number;
+        initial?: boolean | 'always';
+        resize?: boolean;
+    };
 }

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/dist/shared/use-chart-props.d.ts

@@ -9,7 +9,7 @@ export interface CxChartHostPartition {
 export interface CxChartPropsPartition extends CxChartHostPartition {
     /** 物料 JSON definition（声明式 spec，待翻译层组装） */
     spec: ComputedRef<CxChartSpec>;
-    /** 命名数据集表（rows/nodes/links 白名单分馏；marks 字符串引用在此解析） */
+    /** 命名数据集表（顶层数组字段全量分馏；marks 字符串引用在此解析） */
     datasets: ComputedRef<CxChartDatasets>;
 }
 /**

package/dist/stream-triggers.d.ts

@@ -2,7 +2,11 @@ import type { CxSpec, StreamTriggerConfig, TriggerRegistry } from '@lionad/cx-st
 export declare const TANSTACK_CHARTS_STREAM_TRIGGERS: StreamTriggerConfig[];
 /** 装配 TanStack Charts 物料的 trigger 注册表（size 恒 6） */
 export declare function createTanstackChartsTriggerRegistry(): TriggerRegistry<CxSpec>;
-/** 增量节点的主数组（回放计数展示用）；非数组增长型物料或数组缺席时返回 null */
+/**
+ * 增量节点的主数组（回放计数展示用）；非数组增长型物料或数组缺席时返回 null。
+ * 通配主数组形态（arrayKey '*'）无单一主数组，取最长数组字段为主数据集
+ * （如桑基的 links 之于 nodes）；并列时取序列化序靠前者。
+ */
 export declare function mainArrayOf(node: {
     key: string;
     data?: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionad/cx-comps-tanstack-charts",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.0",
   "description": "cx material components wrapping TanStack Charts (@tanstack/charts/vue)",
   "keywords": [
     "charts",
@@ -35,15 +35,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@lionad/cx-definition": "0.1.0-alpha.10",
-    "@lionad/cx-stream": "0.1.0-alpha.10",
-    "@lionad/cx-vue": "0.1.0-alpha.10",
+    "@lionad/cx-definition": "0.1.0",
+    "@lionad/cx-stream": "0.1.0",
+    "@lionad/cx-vue": "0.1.0",
     "d3-geo": "^3.1.1",
     "d3-scale": "^4.0.2",
     "d3-shape": "^3.2.0"
   },
   "devDependencies": {
-    "@tanstack/charts": "^0.14.0",
+    "@tanstack/charts": "^0.18.0",
     "@types/d3-geo": "^3.1.1",
     "@types/d3-scale": "^4.0.9",
     "@types/d3-shape": "^3.1.8",
@@ -53,7 +53,7 @@
     "vue-tsc": "^3.3.7"
   },
   "peerDependencies": {
-    "@tanstack/charts": "^0.14.0",
+    "@tanstack/charts": "^0.18.0",
     "@vueuse/core": "^13.0.0 || ^14.0.0",
     "vue": "^3.5.0"
   },