@loom-framework/core 0.1.0-alpha.9 → 0.1.0-alpha.91

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

@@ -0,0 +1,134 @@
+---
+id: "g2-mark-beeswarm"
+title: "G2 蜂群图（beeswarm）"
+description: |
+  beeswarm mark 将散点沿分类轴自动排布避免重叠，形如蜂巢，
+  每个点紧密排列但互不遮挡。适合展示分类变量下单维数值分布。
+  与 jitter transform 的随机偏移不同，beeswarm 使用力导向算法精确排布。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "beeswarm"
+  - "蜂群图"
+  - "点分布"
+  - "无重叠散点"
+  - "分布图"
+
+related:
+  - "g2-mark-point-scatter"
+  - "g2-transform-jitter"
+  - "g2-mark-box-boxplot"
+
+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/point/#beeswarm"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { dept: '研发', salary: 18000 }, { dept: '研发', salary: 22000 },
+  { dept: '研发', salary: 15000 }, { dept: '研发', salary: 25000 },
+  { dept: '研发', salary: 19000 }, { dept: '研发', salary: 21000 },
+  { dept: '销售', salary: 12000 }, { dept: '销售', salary: 16000 },
+  { dept: '销售', salary: 14000 }, { dept: '销售', salary: 11000 },
+  { dept: '设计', salary: 17000 }, { dept: '设计', salary: 20000 },
+  { dept: '设计', salary: 18500 }, { dept: '设计', salary: 23000 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'point',
+  data,
+  encode: {
+    x: 'dept',
+    y: 'salary',
+    color: 'dept',
+    shape: 'point',
+  },
+  // beeswarm 布局通过 layout 配置，而不是独立的 mark type
+  // 实际上是 point mark + 蜂群布局变换
+  style: { r: 5, fillOpacity: 0.8 },
+  // 用 jitter transform 近似蜂群效果（或使用 beeswarm data 变换）
+  transform: [{ type: 'jitter', padding: 0.1 }],
+});
+
+chart.render();
+```
+
+## 使用 beeswarm mark（独立类型）
+
+```javascript
+// G2 v5 也支持 type: 'beeswarm' 直接使用蜂群布局
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'point',
+  data,
+  encode: {
+    x: 'dept',
+    y: 'salary',
+    color: 'dept',
+  },
+  // beeswarm 通过力导向算法排布，点不重叠
+  style: { r: 4, fillOpacity: 0.75 },
+  layout: {
+    type: 'beeswarm',   // 使用蜂群布局
+    padding: 1,         // 点间距
+  },
+});
+```
+
+## 与箱线图叠加
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'boxplot',
+      encode: { x: 'dept', y: 'salary' },
+      style: { boxFill: 'transparent', boxStroke: '#999', lineWidth: 1.5 },
+    },
+    {
+      type: 'point',
+      encode: { x: 'dept', y: 'salary', color: 'dept' },
+      transform: [{ type: 'jitter', padding: 0.1 }],
+      style: { r: 3.5, fillOpacity: 0.65 },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：数据量太大用 beeswarm——布局计算慢且视觉拥挤
+```javascript
+// ❌ 千条以上数据用蜂群图会很慢且视觉饱和
+chart.options({
+  data: tenThousandRows,   // ❌ 数据太多
+  transform: [{ type: 'jitter' }],
+});
+
+// ✅ 大数据量改用密度图或带颜色的散点图
+// beeswarm 适合 < 500 条数据
+chart.options({
+  data: smallSample,
+  transform: [{ type: 'jitter', padding: 0.08 }],  // ✅ 小样本
+});
+```

package/builtin-skills/antv-g2-chart/references/marks/g2-mark-bi-directional-bar.md

@@ -0,0 +1,297 @@
+---
+id: "g2-mark-bi-directional-bar"
+title: "G2 Bi-Directional Bar Mark"
+description: |
+  双向柱状图 Mark。使用 interval 标记展示正向和反向的数据对比。
+  适用于正负数据对比、收入支出对比、完成/未完成对比等场景。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+tags:
+  - "双向柱状图"
+  - "正负条形图"
+  - "bi-directional"
+  - "对比"
+  - "人口金字塔"
+  - "butterfly chart"
+  - "对称条形图"
+
+related:
+  - "g2-mark-interval-basic"
+  - "g2-mark-interval-stacked"
+
+use_cases:
+  - "正负分类数据对比"
+  - "收入支出对比"
+  - "完成/未完成对比"
+  - "人口金字塔（男女对比）"
+  - "butterfly chart（左右对称条形图）"
+
+anti_patterns:
+  - "不含相反含义的数据不适合"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/mark/bi-directional-bar"
+---
+
+## 核心概念
+
+双向柱状图展示正向和反向的数据对比：
+- 使用 `interval` 标记
+- 通过负值表示反向数据
+- 配合 `transpose` 坐标变换
+
+**适用场景：**
+- 完成/未完成对比
+- 收入/支出对比
+- 正负数据对比
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+});
+
+const data = [
+  { department: '部门1', people: 37, type: 'completed' },
+  { department: '部门1', people: 9, type: 'uncompleted' },
+  { department: '部门2', people: 27, type: 'completed' },
+  { department: '部门2', people: 10, type: 'uncompleted' },
+];
+
+chart.options({
+  type: 'interval',
+  coordinate: { transform: [{ type: 'transpose' }] },
+  data,
+  encode: {
+    x: 'department',
+    y: (d) => (d.type === 'completed' ? d.people : -d.people),
+    color: 'department',
+  },
+  style: {
+    fill: ({ type }) => type === 'uncompleted' ? 'transparent' : undefined,
+    stroke: ({ type }) => type === 'uncompleted' ? '#1890ff' : undefined,
+    lineWidth: 2,
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 堆叠双向柱状图
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: { transform: [{ type: 'transpose' }] },
+  data,
+  transform: [{ type: 'stackY' }],
+  encode: {
+    x: 'question',
+    y: (d) =>
+      d.type === 'Disagree' || d.type === 'Strongly disagree'
+        ? -d.percentage
+        : d.percentage,
+    color: 'type',
+  },
+});
+```
+
+### 自定义 Y 轴标签
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: { transform: [{ type: 'transpose' }] },
+  data,
+  encode: { x: 'category', y: (d) => d.type === 'A' ? d.value : -d.value },
+  axis: {
+    y: {
+      labelFormatter: (d) => Math.abs(d),  // 显示绝对值
+    },
+  },
+});
+```
+
+### 分组显示
+
+```javascript
+chart.options({
+  type: 'interval',
+  coordinate: { transform: [{ type: 'transpose' }] },
+  data,
+  encode: {
+    x: 'group',
+    y: (d) => d.direction === 'forward' ? d.value : -d.value,
+    color: 'category',
+  },
+  style: {
+    maxWidth: 20,
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface BiDirectionalData {
+  category: string;      // 分类字段
+  value: number;         // 数值
+  direction: 'forward' | 'backward';  // 方向
+}
+
+interface BiDirectionalOptions {
+  type: 'interval';
+  coordinate: {
+    transform: [{ type: 'transpose' }];
+  };
+  encode: {
+    x: string;           // 分类字段
+    y: (d) => number;    // 根据方向返回正/负值
+    color?: string;
+  };
+}
+```
+
+## 双向柱状图 vs 柱状图
+
+| 特性 | 双向柱状图 | 柱状图 |
+|------|------------|--------|
+| 数据方向 | 正反两个方向 | 单一方向 |
+| 用途 | 对比相反含义 | 数值对比 |
+| 视觉效果 | 双向对称 | 单向 |
+
+## 人口金字塔（butterfly chart）
+
+人口金字塔是双向柱状图的典型场景——男女两侧数据方向相反，通过负值技巧实现，**无需 `createView`**。
+
+```javascript
+const data = [
+  { age: '0-4',   male: 5.3, female: 5.1 },
+  { age: '5-9',   male: 5.6, female: 5.4 },
+  { age: '10-14', male: 5.8, female: 5.5 },
+  // ...
+];
+
+// 宽表转长表：将 male/female 合并为一列
+const longData = data.flatMap((d) => [
+  { age: d.age, sex: 'Male',   population: d.male },
+  { age: d.age, sex: 'Female', population: d.female },
+]);
+
+chart.options({
+  type: 'interval',
+  data: longData,
+  coordinate: { transform: [{ type: 'transpose' }] },  // 横向条形图
+  encode: {
+    x: 'age',
+    // 关键：男性用负值，女性用正值 → 形成左右对称
+    y: (d) => d.sex === 'Male' ? -d.population : d.population,
+    color: 'sex',
+  },
+  axis: {
+    y: {
+      labelFormatter: (d) => Math.abs(d),  // 显示绝对值（不显示负号）
+      title: '人口占比 (%)',
+    },
+    x: { title: '年龄段' },
+  },
+  scale: {
+    color: { range: ['#5B8FF9', '#FF7875'] },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：缺少负值转换
+
+```javascript
+// ❌ 问题：所有值都是正值
+encode: { y: 'value' }
+
+// ✅ 正确：根据类型返回正/负值
+encode: { y: (d) => d.type === 'A' ? d.value : -d.value }
+```
+
+### 错误 2：缺少 transpose
+
+```javascript
+// ❌ 问题：默认是垂直方向
+coordinate: {}
+
+// ✅ 正确：添加 transpose
+coordinate: { transform: [{ type: 'transpose' }] }
+```
+
+### 错误 3：Y 轴标签显示负值
+
+```javascript
+// ❌ 问题：负值显示为负数
+axis: {}
+
+// ✅ 正确：格式化为绝对值
+axis: {
+  y: { labelFormatter: (d) => Math.abs(d) },
+}
+```
+
+### 错误 4：用 `chart.createView()` 实现人口金字塔
+
+这是最常见的错误——V4 时代用 `createView` 创建左右两个独立视图，V5 已移除此 API。正确做法是**负值技巧**（单一 `interval` + 负值编码）或 `spaceLayer`。
+
+```javascript
+// ❌ 禁止：V4 createView，V5 中不存在
+const leftView = chart.createView();
+leftView.options({
+  type: 'interval',
+  data: usData,
+  encode: { x: 'age', y: 'male' },
+});
+const rightView = chart.createView();
+rightView.options({ ... });
+
+// ✅ 方案一（推荐）：负值技巧——单一 interval，男性取负值
+chart.options({
+  type: 'interval',
+  data: combinedData,   // male/female 合并到一个数组
+  coordinate: { transform: [{ type: 'transpose' }] },
+  encode: {
+    x: 'age',
+    y: (d) => d.sex === 'Male' ? -d.population : d.population,
+    color: 'sex',
+  },
+  axis: { y: { labelFormatter: (d) => Math.abs(d) } },
+});
+
+// ✅ 方案二：spaceLayer（两侧需完全独立比例尺时使用）
+chart.options({
+  type: 'spaceLayer',
+  children: [
+    {
+      type: 'interval',
+      data: leftData,
+      coordinate: { transform: [{ type: 'transpose' }, { type: 'reflectX' }] },
+      encode: { x: 'age', y: 'male' },
+      axis: { y: { position: 'right' } },
+    },
+    {
+      type: 'interval',
+      data: rightData,
+      coordinate: { transform: [{ type: 'transpose' }] },
+      encode: { x: 'age', y: 'female' },
+      axis: { y: false },
+    },
+  ],
+});
+```

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

@@ -0,0 +1,163 @@
+---
+id: "g2-mark-box-boxplot"
+title: "G2 箱线图（Box Mark）"
+description: |
+  使用 Box Mark 创建箱线图（又称盒须图），展示数据的分位数分布：
+  最小值、Q1（25%分位）、中位数、Q3（75%分位）、最大值及异常值。
+  本文采用 Spec 模式。
+
+library: "g2"
+version: "5.x"
+category: "marks"
+subcategory: "box"
+tags:
+  - "箱线图"
+  - "盒须图"
+  - "Box"
+  - "boxplot"
+  - "分布"
+  - "分位数"
+  - "异常值"
+  - "spec"
+
+related:
+  - "g2-mark-point-scatter"
+  - "g2-core-encode-channel"
+
+use_cases:
+  - "展示数值数据的分布形态和离散程度"
+  - "对比多个分类的数据分布差异"
+  - "识别异常值（outliers）"
+
+anti_patterns:
+  - "数据量极少（< 5 个点）时箱线图无统计意义"
+  - "需要展示具体数据点分布时，改用小提琴图或散点图"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/statistics/boxplot"
+---
+
+## 核心概念
+
+Box Mark 需要 5 个数值通道：
+- `y`：中位数（Q2）
+- `y1`：Q1（25% 分位数）
+- `y2`：Q3（75% 分位数）
+- `y3`：下须（最小非异常值）
+- `y4`：上须（最大非异常值）
+
+**数据格式**：数据需预先计算分位数后传入，或使用原始数据配合 `boxplot` transform 自动计算。
+
+## 使用 boxplot transform 自动计算（推荐）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+// 原始数据，每个分类有多个观测值
+const rawData = [
+  { category: 'A', value: 10 },
+  { category: 'A', value: 25 },
+  { category: 'A', value: 30 },
+  { category: 'A', value: 45 },
+  { category: 'A', value: 50 },
+  { category: 'A', value: 55 },
+  { category: 'A', value: 80 },   // 异常值
+  { category: 'B', value: 20 },
+  { category: 'B', value: 35 },
+  { category: 'B', value: 40 },
+  { category: 'B', value: 48 },
+  { category: 'B', value: 52 },
+  { category: 'B', value: 65 },
+];
+
+chart.options({
+  type: 'boxplot',          // boxplot 是 box mark + boxplot transform 的组合快捷方式
+  data: rawData,
+  encode: {
+    x: 'category',
+    y: 'value',
+  },
+  style: {
+    fill: '#1890ff',
+    fillOpacity: 0.3,
+    stroke: '#1890ff',
+  },
+});
+
+chart.render();
+```
+
+## 预计算分位数数据
+
+```javascript
+// 数据已包含分位数字段
+chart.options({
+  type: 'box',
+  data: [
+    { category: 'A', min: 10, q1: 25, median: 45, q3: 55, max: 75 },
+    { category: 'B', min: 20, q1: 35, median: 48, q3: 58, max: 80 },
+    { category: 'C', min: 5,  q1: 20, median: 35, q3: 50, max: 65 },
+  ],
+  encode: {
+    x: 'category',
+    y: 'median',     // 中位数
+    y1: 'q1',        // 下四分位
+    y2: 'q3',        // 上四分位
+    y3: 'min',       // 下须
+    y4: 'max',       // 上须
+  },
+  style: {
+    fill: '#1890ff',
+    fillOpacity: 0.3,
+    stroke: '#1890ff',
+    lineWidth: 1.5,
+  },
+});
+```
+
+## 箱线图 + 散点（显示原始数据点）
+
+```javascript
+chart.options({
+  type: 'view',
+  data: rawData,
+  children: [
+    {
+      type: 'boxplot',
+      encode: { x: 'category', y: 'value' },
+      style: { fill: '#1890ff', fillOpacity: 0.2, stroke: '#1890ff' },
+    },
+    {
+      // 叠加原始数据点
+      type: 'point',
+      encode: { x: 'category', y: 'value' },
+      transform: [{ type: 'jitter' }],   // jitter 避免点重叠
+      style: { fill: '#1890ff', fillOpacity: 0.5, r: 3 },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：box mark 缺少 y1/y2/y3/y4 通道
+```javascript
+// ❌ 错误：box mark 需要 5 个 y 通道，缺少会渲染异常
+chart.options({
+  type: 'box',
+  encode: { x: 'category', y: 'median' },  // 缺少 y1-y4！
+});
+
+// ✅ 正确：使用 boxplot（自动计算）或补全所有通道
+chart.options({ type: 'boxplot', encode: { x: 'category', y: 'value' } });
+```