@loom-framework/core 0.1.0-alpha.84 → 0.1.0-alpha.86

package/builtin-skills/antv-g2-chart/references/marks/g2-mark-venn.md

@@ -0,0 +1,204 @@
+---
+id: "g2-mark-venn"
+title: "G2 Venn Diagram Mark"
+description: |
+  韦恩图 Mark。使用 path 标记配合 venn 转换，展示集合之间的交集、并集关系。
+  适用于用户群体分析、产品功能对比、技能重叠分析等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "韦恩图"
+  - "venn"
+  - "集合关系"
+  - "交集"
+
+related:
+  - "g2-mark-chord"
+  - "g2-mark-sankey"
+
+use_cases:
+  - "用户群体重叠分析"
+  - "产品功能对比"
+  - "技能重叠分析"
+
+anti_patterns:
+  - "集合数量 >4 应使用其他图表"
+  - "数值差异过大不适合"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/mark/venn"
+---
+
+## 核心概念
+
+韦恩图展示集合之间的交集关系：
+- 使用 `path` 标记
+- 配合 `venn` 数据转换
+- 重叠区域表示交集
+
+**数据格式：**
+- `sets`：集合名称数组
+- `size`：集合大小
+- `label`：显示标签
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  autoFit: true,
+});
+
+chart.options({
+  type: 'path',
+  data: {
+    type: 'inline',
+    value: [
+      { sets: ['微信'], size: 1200, label: '微信' },
+      { sets: ['微博'], size: 800, label: '微博' },
+      { sets: ['微信', '微博'], size: 300, label: '重叠' },
+    ],
+    transform: [{ type: 'venn' }],
+  },
+  encode: {
+    d: 'path',
+    color: 'key',
+  },
+  labels: [
+    { position: 'inside', text: (d) => d.label || '' },
+  ],
+  style: {
+    opacity: (d) => (d.sets.length > 1 ? 0.3 : 0.7),
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 三集合韦恩图
+
+```javascript
+chart.options({
+  type: 'path',
+  data: {
+    type: 'inline',
+    value: [
+      { sets: ['前端'], size: 12, label: '前端' },
+      { sets: ['后端'], size: 15, label: '后端' },
+      { sets: ['设计'], size: 8, label: '设计' },
+      { sets: ['前端', '后端'], size: 5, label: '全栈' },
+      { sets: ['前端', '设计'], size: 3 },
+      { sets: ['后端', '设计'], size: 2 },
+      { sets: ['前端', '后端', '设计'], size: 1 },
+    ],
+    transform: [{ type: 'venn' }],
+  },
+  encode: { d: 'path', color: 'key' },
+});
+```
+
+### 空心韦恩图
+
+```javascript
+chart.options({
+  type: 'path',
+  data: {
+    type: 'inline',
+    value: [...],
+    transform: [{ type: 'venn' }],
+  },
+  encode: {
+    d: 'path',
+    color: 'key',
+    shape: 'hollow',  // 空心样式
+  },
+  style: {
+    lineWidth: 3,
+  },
+});
+```
+
+### 带交互
+
+```javascript
+chart.options({
+  type: 'path',
+  data: { type: 'inline', value: [...], transform: [{ type: 'venn' }] },
+  encode: { d: 'path', color: 'key' },
+  state: {
+    inactive: { opacity: 0.2 },
+    active: { opacity: 0.9 },
+  },
+  interactions: [{ type: 'elementHighlight' }],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface VennData {
+  sets: string[];    // 集合名称数组
+  size: number;      // 集合大小
+  label?: string;    // 显示标签
+}
+
+interface VennOptions {
+  type: 'path';
+  data: {
+    type: 'inline';
+    value: VennData[];
+    transform: [{ type: 'venn' }];
+  };
+  encode: {
+    d: 'path';
+    color: 'key';
+  };
+}
+```
+
+## 韦恩图 vs 其他图表
+
+| 场景 | 推荐图表 |
+|------|----------|
+| 集合交集关系 | 韦恩图 |
+| 层次结构 | 旭日图 |
+| 流向关系 | 桑基图 |
+
+## 常见错误与修正
+
+### 错误 1：缺少 venn 转换
+
+```javascript
+// ❌ 问题：没有 venn 转换
+data: { type: 'inline', value: [...] }
+
+// ✅ 正确：添加 venn 转换
+data: { type: 'inline', value: [...], transform: [{ type: 'venn' }] }
+```
+
+### 错误 2：集合数量过多
+
+```javascript
+// ⚠️ 注意：集合数量建议不超过 4 个
+// 5 个以上集合会导致视觉混乱
+```
+
+### 错误 3：encode 配置错误
+
+```javascript
+// ❌ 问题：使用 x/y 编码
+encode: { x: 'sets', y: 'size' }
+
+// ✅ 正确：使用 d 编码 path
+encode: { d: 'path', color: 'key' }
+```

package/builtin-skills/antv-g2-chart/references/marks/g2-mark-violin.md

@@ -0,0 +1,307 @@
+---
+id: "g2-mark-violin"
+title: "G2 Violin Plot Mark"
+description: |
+  小提琴图 Mark。使用 density 和 boxplot 组合，结合核密度估计展示数据分布形状。
+  适用于多组数据分布比较、探索数据分布模式等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "小提琴图"
+  - "violin"
+  - "密度分布"
+  - "统计分析"
+
+related:
+  - "g2-mark-boxplot"
+  - "g2-mark-density"
+
+use_cases:
+  - "多组数据分布比较"
+  - "数据分布模式探索"
+  - "异常值检测"
+
+anti_patterns:
+  - "数据量少（<20）应使用箱形图"
+  - "离散数据不适合"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/mark/violin"
+---
+
+## 核心概念
+
+小提琴图结合了箱形图和核密度估计：
+- 展示完整的数据分布形状
+- 叠加箱形图的统计信息
+- 通过 KDE（核密度估计）生成密度轮廓
+
+**主要组成部分：**
+- 密度轮廓：展示数据分布密度
+- 箱形图：显示中位数、四分位数
+- 中位线：标示中位数位置
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  theme: 'classic',
+});
+
+chart.options({
+  type: 'view',
+  data: {
+    type: 'fetch',
+    value: 'https://assets.antv.antgroup.com/g2/species.json',
+  },
+  children: [
+    {
+      type: 'density',
+      data: {
+        transform: [
+          { type: 'kde', field: 'y', groupBy: ['x', 'species'] },
+        ],
+      },
+      encode: {
+        x: 'x',
+        y: 'y',
+        series: 'species',
+        color: 'species',
+        size: 'size',
+      },
+      tooltip: false,
+    },
+    {
+      type: 'boxplot',
+      encode: {
+        x: 'x',
+        y: 'y',
+        series: 'species',
+        color: 'species',
+        shape: 'violin',
+      },
+      style: {
+        opacity: 0.5,
+        strokeOpacity: 0.5,
+        point: false,
+      },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 极坐标小提琴图
+
+```javascript
+chart.options({
+  type: 'view',
+  coordinate: { type: 'polar' },
+  data: {
+    type: 'fetch',
+    value: 'https://assets.antv.antgroup.com/g2/species.json',
+  },
+  children: [
+    {
+      type: 'density',
+      data: { transform: [{ type: 'kde', field: 'y', groupBy: ['x', 'species'] }] },
+      encode: { x: 'x', y: 'y', series: 'species', color: 'species', size: 'size' },
+      tooltip: false,
+    },
+    {
+      type: 'boxplot',
+      encode: { x: 'x', y: 'y', series: 'species', color: 'species', shape: 'violin' },
+      style: { opacity: 0.5, strokeOpacity: 0.5, point: false },
+    },
+  ],
+});
+```
+
+### 纯密度图
+
+```javascript
+chart.options({
+  type: 'density',
+  data: {
+    type: 'fetch',
+    value: 'https://assets.antv.antgroup.com/g2/species.json',
+    transform: [
+      { type: 'kde', field: 'y', groupBy: ['x'], size: 20 },
+    ],
+  },
+  encode: {
+    x: 'x',
+    y: 'y',
+    color: 'x',
+    size: 'size',
+  },
+  tooltip: false,
+});
+```
+
+### 带异常值标记
+
+```javascript
+chart.options({
+  type: 'view',
+  data: {
+    type: 'fetch',
+    value: 'https://assets.antv.antgroup.com/g2/morley.json',
+  },
+  children: [
+    {
+      type: 'density',
+      data: { transform: [{ type: 'kde', field: 'Speed', groupBy: ['Expt'] }] },
+      encode: { x: 'Expt', y: 'Speed', size: 'size', color: 'Expt' },
+      style: { fillOpacity: 0.4 },
+      tooltip: false,
+    },
+    {
+      type: 'boxplot',
+      encode: { x: 'Expt', y: 'Speed', color: 'Expt', shape: 'violin' },
+      style: {
+        opacity: 0.8,
+        point: { fill: 'red', size: 3 },  // 异常值标记
+      },
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface ViolinOptions {
+  type: 'view';
+  data: any; // 原始数据源
+  children: [
+    {
+      type: 'density';
+      data: {
+        transform: [
+          {
+            type: 'kde';
+            field: string;      // 数值字段
+            groupBy: string[];  // 分组字段（必须包含x轴字段和分组字段）
+            size?: number;      // 采样点数，默认为10，建议设置为20~50以获得更平滑的曲线
+          }
+        ]
+      };
+      encode: {
+        x: string;
+        y: string;
+        size: 'size';
+        color?: string;
+        series: string;
+      };
+      tooltip?: boolean; // 推荐关闭，避免与boxplot重复
+    },
+    {
+      type: 'boxplot';
+      encode: {
+        x: string;
+        y: string;
+        shape: 'violin';
+        color?: string;
+        series: string;
+      };
+      style?: {
+        opacity?: number;
+        strokeOpacity?: number;
+        point?: boolean | object; // 是否显示异常点
+      };
+    }
+  ];
+}
+```
+
+## 小提琴图 vs 箱形图
+
+| 特性 | 小提琴图 | 箱形图 |
+|------|----------|--------|
+| 分布信息 | 完整密度 | 统计摘要 |
+| 多峰检测 | 支持 | 不支持 |
+| 简洁程度 | 较复杂 | 简洁 |
+
+## 常见错误与修正
+
+### 错误 1：缺少 KDE 转换
+
+```javascript
+// ❌ 问题：没有核密度估计
+data: { type: 'fetch', value: 'data.json' }
+
+// ✅ 正确：添加 kde 转换
+data: {
+  type: 'fetch',
+  value: 'data.json',
+  transform: [{ type: 'kde', field: 'y', groupBy: ['x', 'species'] }],
+}
+```
+
+### 错误 2：数据量过少
+
+```javascript
+// ⚠️ 注意：每个分组建议至少 20-30 个数据点
+// 数据量少时建议使用箱形图
+```
+
+### 错误 3：缺少 boxplot 叠加
+
+```javascript
+// ❌ 问题：只有密度图，缺少统计信息
+children: [{ type: 'density', ... }]
+
+// ✅ 正确：叠加 boxplot
+children: [
+  { type: 'density', ... },
+  { 
+    type: 'boxplot', 
+    encode: { 
+      shape: 'violin',
+      x: 'x',
+      y: 'y',
+      series: 'species',
+      color: 'species'
+    } 
+  },
+]
+```
+
+### 错误 4：KDE transform 配置错误
+
+```javascript
+// ❌ 问题：groupBy 字段不完整或缺失
+transform: [{ type: 'kde', field: 'y', groupBy: ['x'] }]
+
+// ✅ 正确：确保 groupBy 包含所有分组字段
+transform: [{ type: 'kde', field: 'y', groupBy: ['x', 'species'] }]
+```
+
+### 错误 5：encode 映射不完整
+
+```javascript
+// ❌ 问题：缺少必要的 encode 映射
+encode: { x: 'x', y: 'y' }
+
+// ✅ 正确：确保映射了所有必需字段
+encode: {
+  x: 'x',
+  y: 'y',
+  series: 'species',
+  color: 'species',
+  size: 'size'
+}
+```

package/builtin-skills/antv-g2-chart/references/marks/g2-mark-wordcloud.md

@@ -0,0 +1,155 @@
+---
+id: "g2-mark-wordcloud"
+title: "G2 词云图（wordCloud）"
+description: |
+  wordCloud mark 将词语按频率/权重排布成云状图，高频词字体更大。
+  数据需包含文本字段（text）和权重字段（value），
+  G2 内置词云布局算法，自动处理词语重叠。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "词云"
+  - "wordCloud"
+  - "word cloud"
+  - "文本可视化"
+  - "词频"
+
+related:
+  - "g2-mark-text"
+  - "g2-core-chart-init"
+
+use_cases:
+  - "展示文本数据的词频分布"
+  - "用户评论关键词可视化"
+  - "话题热度展示"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/other/#word-cloud"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { word: '数据可视化', count: 120 },
+  { word: '图表', count: 85 },
+  { word: '交互', count: 70 },
+  { word: 'JavaScript', count: 95 },
+  { word: '前端', count: 110 },
+  { word: 'AntV', count: 65 },
+  { word: 'G2', count: 100 },
+  { word: '分析', count: 78 },
+  { word: '用户', count: 55 },
+  { word: '体验', count: 60 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'wordCloud',
+  data,
+  encode: {
+    text: 'word',    // 显示的词语字段
+    color: 'word',   // 颜色编码（每个词不同颜色）
+    fontSize: {      // 字体大小映射（可用字段名或固定范围）
+      field: 'count',
+      range: [12, 60],  // 最小/最大字号
+    },
+  },
+  layout: {
+    spiral: 'archimedean',  // 布局螺旋形状：'archimedean' | 'rectangular'
+    padding: 2,             // 词语间距
+  },
+  style: {
+    fontFamily: 'Impact, sans-serif',
+    fontWeight: 'bold',
+  },
+});
+
+chart.render();
+```
+
+## 带旋转的词云
+
+```javascript
+chart.options({
+  type: 'wordCloud',
+  data,
+  encode: {
+    text: 'word',
+    color: 'count',
+    rotate: {
+      // 随机旋转角度：水平或垂直
+      callback: () => (Math.random() > 0.7 ? 90 : 0),
+    },
+    fontSize: { field: 'count', range: [14, 56] },
+  },
+  scale: {
+    color: { type: 'sequential', palette: 'blues' },
+  },
+  layout: { padding: 4 },
+});
+```
+
+## 固定词语颜色分组
+
+```javascript
+chart.options({
+  type: 'wordCloud',
+  data: wordsWithCategory,
+  encode: {
+    text: 'word',
+    color: 'category',  // 按类别着色（分类色板）
+    fontSize: { field: 'count', range: [16, 50] },
+  },
+  scale: {
+    color: { type: 'ordinal', palette: 'set2' },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：数据没有权重字段——所有词大小相同
+```javascript
+// ❌ 没有 fontSize 编码，所有词大小一样
+chart.options({
+  type: 'wordCloud',
+  data: [{ word: 'A' }, { word: 'B' }],  // ❌ 没有数值字段
+  encode: { text: 'word' },
+});
+
+// ✅ 必须提供权重字段并配置 fontSize
+chart.options({
+  encode: {
+    text: 'word',
+    fontSize: { field: 'count', range: [14, 60] },  // ✅
+  },
+});
+```
+
+### 错误 2：容器太小导致词语显示不全
+```javascript
+// ❌ 小容器下词云布局算法无法放置所有词
+const chart = new Chart({ container: 'container', width: 300, height: 200 });  // ❌ 太小
+
+// ✅ 词云推荐最小 400×300，多词时 600×400 以上
+const chart = new Chart({ container: 'container', width: 640, height: 480 });  // ✅
+```
+
+### 错误 3：词语太多字号设置太大——大量词语无法布局
+```javascript
+// ❌ 100+ 个词，最大字号 80px，大量词语被丢弃
+encode: { fontSize: { field: 'count', range: [20, 80] } }  // ❌ range 太大
+
+// ✅ 词多时缩小字号范围
+encode: { fontSize: { field: 'count', range: [10, 40] } }  // ✅
+```