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

package/builtin-skills/antv-g2-chart/references/transforms/g2-transform-diffy.md

@@ -0,0 +1,130 @@
+---
+id: "g2-transform-diffy"
+title: "G2 DiffY 差值区域变换"
+description: |
+  diffY 计算两条折线之间的差值区间（y0 到 y1），用于绘制差值面积图。
+  保持上方折线的 y 值不变，计算下方折线相对于上方的差值作为 y1，
+  视觉上展示两系列之间的正/负差异区域。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "diffY"
+  - "差值"
+  - "差异面积"
+  - "对比"
+  - "transform"
+  - "区间面积"
+
+related:
+  - "g2-mark-area-stacked"
+  - "g2-transform-stacky"
+  - "g2-mark-line-basic"
+
+use_cases:
+  - "展示两条折线之间的正/负差异区域"
+  - "实际值 vs 预测值的偏差可视化"
+  - "价格上下区间的差值展示"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform/diff-y"
+---
+
+## 最小可运行示例（实际 vs 预测差异）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', actual: 83,  forecast: 75 },
+  { month: 'Feb', actual: 60,  forecast: 70 },
+  { month: 'Mar', actual: 95,  forecast: 85 },
+  { month: 'Apr', actual: 72,  forecast: 80 },
+  { month: 'May', actual: 110, forecast: 100 },
+  { month: 'Jun', actual: 88,  forecast: 95 },
+];
+
+// 转换为长表格式
+const longData = data.flatMap(d => [
+  { month: d.month, value: d.actual,   type: '实际' },
+  { month: d.month, value: d.forecast, type: '预测' },
+]);
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'view',
+  children: [
+    // 差值面积（正差异：实际>预测 显示绿色，负差异：实际<预测 显示红色）
+    {
+      type: 'area',
+       longData,
+      encode: { x: 'month', y: 'value', color: 'type', series: 'type' },
+      transform: [{ type: 'diffY' }],   // 计算两系列间的差值区间
+      style: {
+        fillOpacity: 0.3,
+      },
+    },
+    // 主折线
+    {
+      type: 'line',
+       longData,
+      encode: { x: 'month', y: 'value', color: 'type' },
+      style: { lineWidth: 2 },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+transform: [
+  {
+    type: 'diffY',
+    groupBy: 'x',   // 按 x 通道分组对齐，默认 'x'
+  },
+]
+```
+
+## 常见错误与修正
+
+### 错误：数据没有两个系列——diffY 需要至少两个 series 才能计算差值
+```javascript
+// ❌ 只有一个系列，diffY 没有对比基准，差值为 0
+chart.options({
+  type: 'area',
+  data: singleSeriesData,
+  encode: { x: 'date', y: 'value' },  // ❌ 没有 series/color 区分两组
+  transform: [{ type: 'diffY' }],
+});
+
+// ✅ 必须有两个系列（通过 color/series 区分）
+chart.options({
+  type: 'area',
+  data: twoSeriesData,
+  encode: {
+    x: 'date',
+    y: 'value',
+    color: 'type',   // ✅ 区分两个系列
+    series: 'type',
+  },
+  transform: [{ type: 'diffY' }],
+});
+```
+
+### 错误：diffY 与 stackY 混淆——stackY 是累积，diffY 是差值
+```javascript
+// stackY：将多个系列的 y 值累积（适合堆叠图）
+transform: [{ type: 'stackY' }]
+
+// diffY：计算两个系列之间的差值区间（适合差值面积图）
+transform: [{ type: 'diffY' }]
+```

package/builtin-skills/antv-g2-chart/references/transforms/g2-transform-dodgex.md

@@ -0,0 +1,90 @@
+---
+id: "g2-transform-dodgex"
+title: "G2 DodgeX 分组变换"
+description: |
+  DodgeX 是 G2 v5 中用于分组展示的 Transform，
+  将同一 x 位置的多系列元素在水平方向上错开排列，
+  是分组柱状图的核心依赖。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "dodgeX"
+  - "分组"
+  - "并排"
+  - "transform"
+  - "分组柱状图"
+  - "spec"
+
+related:
+  - "g2-mark-interval-grouped"
+  - "g2-transform-stacky"
+
+use_cases:
+  - "创建分组柱状图（并排展示多系列）"
+  - "分组散点图"
+
+difficulty: "beginner"
+completeness: "partial"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform/dodge-x"
+---
+
+## 基本用法
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [{ type: 'dodgeX' }],
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: [...],
+  encode: { x: 'month', y: 'value', color: 'type' },
+  transform: [
+    {
+      type: 'dodgeX',
+      padding: 0,          // 组内各柱之间的间距（相对于每组宽度，0-1），默认 0
+      paddingOuter: 0.1,   // 整组与相邻组的外边距
+      reverse: false,      // 是否反转分组顺序
+    },
+  ],
+});
+```
+
+## 与 stackY 的区别
+
+```javascript
+// dodgeX：各系列并排展示，便于直接对比绝对值
+chart.options({ transform: [{ type: 'dodgeX' }] });
+
+// stackY：各系列堆叠展示，便于对比总量和占比
+chart.options({ transform: [{ type: 'stackY' }] });
+```
+
+## 常见错误与修正
+
+### 错误：transform 写成对象
+```javascript
+// ❌ 错误
+chart.options({ transform: { type: 'dodgeX' } });
+
+// ✅ 正确：必须是数组
+chart.options({ transform: [{ type: 'dodgeX' }] });
+```

package/builtin-skills/antv-g2-chart/references/transforms/g2-transform-flexx.md

@@ -0,0 +1,115 @@
+---
+id: "g2-transform-flexx"
+title: "G2 FlexX 弹性宽度变换（马赛克图 / 不等宽柱）"
+description: |
+  flexX 根据数据值动态调整 x 轴比例尺的 flex 属性，使每个柱的宽度与数值成比例。
+  常用于马赛克图（Marimekko chart）：柱宽表示一个维度，柱高表示另一个维度。
+  通过 field 指定控制宽度的字段，reducer 指定聚合方式。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "flexX"
+  - "不等宽柱"
+  - "马赛克图"
+  - "Marimekko"
+  - "弹性宽度"
+  - "transform"
+
+related:
+  - "g2-transform-stacky"
+  - "g2-mark-interval-stacked"
+
+use_cases:
+  - "马赛克图（双维度占比：柱宽 × 柱高）"
+  - "不等宽柱状图（柱宽代表样本量/权重）"
+  - "市场份额图（宽度=市场规模，高度=占比）"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform/flex-x"
+---
+
+## 最小可运行示例（马赛克图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 马赛克图：x 类别，y 子类别比例，value 控制柱宽（市场规模）
+const data = [
+  { region: '华北', type: '线上', revenue: 300, share: 0.6 },
+  { region: '华北', type: '线下', revenue: 300, share: 0.4 },
+  { region: '华东', type: '线上', revenue: 500, share: 0.7 },
+  { region: '华东', type: '线下', revenue: 500, share: 0.3 },
+  { region: '华南', type: '线上', revenue: 200, share: 0.5 },
+  { region: '华南', type: '线下', revenue: 200, share: 0.5 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+chart.options({
+  type: 'interval',
+  data,
+  encode: {
+    x: 'region',
+    y: 'share',
+    color: 'type',
+  },
+  transform: [
+    {
+      type: 'flexX',
+      field: 'revenue',    // 控制柱宽的字段
+      reducer: 'sum',      // 聚合方式（同一 x 类别可能有多行，需要 sum）
+    },
+    { type: 'stackY' },   // 再堆叠 y 方向（百分比）
+  ],
+  axis: {
+    y: { labelFormatter: (v) => `${(v * 100).toFixed(0)}%` },
+  },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+transform: [
+  {
+    type: 'flexX',
+    field: 'sampleSize',  // 控制宽度的字段名（每个 x 类别的权重）
+    channel: 'y',         // 依据哪个通道的值计算弹性（默认 'y'）
+    reducer: 'sum',       // 同一 x 类别下 field 值的聚合方式（'sum' 是最常用的）
+  },
+]
+```
+
+## 常见错误与修正
+
+### 错误：flexX 和 stackY 顺序错误——先 stackY 后 flexX
+```javascript
+// ❌ 错误：应该先 flexX 再 stackY
+transform: [
+  { type: 'stackY' },   // ❌ stackY 先执行，flexX 后调整宽度，比例关系出错
+  { type: 'flexX', field: 'revenue' },
+]
+
+// ✅ 正确顺序：先 flexX（设置宽度弹性），再 stackY（堆叠高度）
+transform: [
+  { type: 'flexX', field: 'revenue', reducer: 'sum' },  // ✅ 先设置弹性宽度
+  { type: 'stackY' },                                     // ✅ 再堆叠
+]
+```
+
+### 错误：没有设置 reducer——同一 x 有多行时宽度计算不一致
+```javascript
+// ❌ 未设置 reducer，同一 region 有多行（线上/线下），flexX 不知如何聚合宽度
+transform: [{ type: 'flexX', field: 'revenue' }]  // ❌ 缺少 reducer
+
+// ✅ 设置 reducer: 'sum' 对同一 x 的 field 求和
+transform: [{ type: 'flexX', field: 'revenue', reducer: 'sum' }]  // ✅
+```

package/builtin-skills/antv-g2-chart/references/transforms/g2-transform-group.md

@@ -0,0 +1,233 @@
+---
+id: "g2-transform-group"
+title: "G2 Group / GroupX / GroupY 分组聚合变换"
+description: |
+  Group、GroupX、GroupY 是 G2 v5 中用于分组聚合的 Transform。
+  Group 按 x 和 y 通道双维度分组；GroupX 按 x 通道分组；GroupY 按 y 通道分组。
+  支持 mean、sum、count、min、max、median、first、last 等聚合函数。
+  常用于直方图、统计柱状图、聚合折线图等场景。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "group"
+  - "groupX"
+  - "groupY"
+  - "分组聚合"
+  - "transform"
+  - "统计"
+  - "mean"
+  - "sum"
+
+related:
+  - "g2-transform-bin"
+  - "g2-transform-stacky"
+  - "g2-mark-interval-basic"
+
+use_cases:
+  - "按类别计算平均值（均值柱状图）"
+  - "按 X 分组后求和展示总量"
+  - "将明细数据聚合为统计摘要"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform/group-x"
+---
+
+## 核心概念
+
+| Transform | 分组维度 | 典型场景 |
+|-----------|----------|----------|
+| `groupX` | x 通道（+ color/series） | 同类别取均值/求和 |
+| `groupY` | y 通道 | 按 Y 分组聚合 |
+| `group` | x + y 双通道 | 二维分组聚合 |
+
+聚合函数通过 `y: 'mean'` 等形式指定，支持：
+`mean`（均值）、`sum`（求和）、`count`（计数）、`min`、`max`、`median`、`first`、`last`
+
+## GroupX 基本用法（按类别求均值）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { category: 'A', value: 10 },
+    { category: 'A', value: 20 },
+    { category: 'A', value: 30 },
+    { category: 'B', value: 40 },
+    { category: 'B', value: 50 },
+  ],
+  encode: { x: 'category', y: 'value' },
+  transform: [
+    {
+      type: 'groupX',
+      y: 'mean',   // 按 x 分组，y 取均值
+    },
+  ],
+});
+
+chart.render();
+// 结果：A 显示均值 20，B 显示均值 45
+```
+
+## GroupX 聚合函数一览
+
+```javascript
+chart.options({
+  type: 'interval',
+  data: rawData,
+  encode: { x: 'category', y: 'value' },
+  transform: [
+    {
+      type: 'groupX',
+      y: 'mean',      // 均值
+      // y: 'sum',    // 求和
+      // y: 'count',  // 计数（忽略 y 通道值，统计条数）
+      // y: 'max',    // 最大值
+      // y: 'min',    // 最小值
+      // y: 'median', // 中位数
+    },
+  ],
+});
+```
+
+## 统计计数（频率分布）
+
+```javascript
+// 统计各类别出现次数
+chart.options({
+  type: 'interval',
+  data: rawData,
+  encode: { x: 'category' },    // 无需 y 通道
+  transform: [
+    { type: 'groupX', y: 'count' },  // y 会自动生成为计数值
+  ],
+});
+```
+
+## GroupY 用法（按 Y 分组）
+
+```javascript
+// 水平方向按 y 分组求均值（常用于横向柱状图）
+chart.options({
+  type: 'interval',
+  data: rawData,
+  encode: { y: 'category', x: 'value' },
+  transform: [
+    { type: 'groupY', x: 'mean' },  // 按 y 分组，x 取均值
+  ],
+  coordinate: { transform: [{ type: 'transpose' }] },
+});
+```
+
+## 多字段聚合
+
+```javascript
+// 同时对多个字段聚合
+chart.options({
+  type: 'point',
+  data: rawData,
+  encode: { x: 'date', y: 'value', size: 'amount' },
+  transform: [
+    {
+      type: 'groupX',
+      y: 'mean',       // y 取均值
+      size: 'sum',     // size 通道取求和
+    },
+  ],
+});
+```
+
+## Cell 图表中的 Group 使用
+
+对于 `cell` 类型的图表，通常需要先对数据进行分组聚合再渲染。例如，按日期的 UTC 日和 UTC 月分组，并取最高温度的最大值：
+
+```javascript
+const chart = new Chart({
+  container: 'container',
+});
+
+chart.options({
+  type: 'cell',
+  height: 300,
+  data: {
+    type: 'inline',
+    value: [
+      { date: '2012-01-01', temp_max: 12.8 },
+      { date: '2012-01-02', temp_max: 10.6 },
+      // 更多数据...
+    ]
+  },
+  encode: {
+    x: (d) => new Date(d.date).getUTCDate(),
+    y: (d) => new Date(d.date).getUTCMonth(),
+    color: 'temp_max',
+  },
+  transform: [{ type: 'group', color: 'max' }],
+  scale: { color: { type: 'sequential', palette: 'gnBu' } },
+  style: { inset: 0.5 },
+});
+
+chart.render();
+```
+
+## 常见错误与修正
+
+### 错误 1：transform 写成对象而非数组
+```javascript
+// ❌ 错误
+chart.options({ transform: { type: 'groupX', y: 'mean' } });
+
+// ✅ 正确
+chart.options({ transform: [{ type: 'groupX', y: 'mean' }] });
+```
+
+### 错误 2：count 聚合时仍传 y encode
+```javascript
+// ❌ count 聚合时不需要 y 通道
+chart.options({
+  encode: { x: 'category', y: 'someField' },
+  transform: [{ type: 'groupX', y: 'count' }],  // y: 'count' 会忽略 encode.y
+});
+
+// ✅ count 聚合只需 x 通道
+chart.options({
+  encode: { x: 'category' },    // 不需要 y
+  transform: [{ type: 'groupX', y: 'count' }],
+});
+```
+
+### 错误 3：Cell 图表未正确使用 Group 聚合
+```javascript
+// ❌ 错误：没有对重复的 x/y 组合做聚合，导致渲染异常
+chart.options({
+  type: 'cell',
+  data: weatherData,
+  encode: {
+    x: (d) => new Date(d.date).getUTCDate(),
+    y: (d) => new Date(d.date).getUTCMonth(),
+    color: 'temp_max'
+  },
+  transform: []  // 缺少必要的 group 聚合
+});
+
+// ✅ 正确：使用 group 并指定 color 聚合方式
+chart.options({
+  type: 'cell',
+  data: weatherData,
+  encode: {
+    x: (d) => new Date(d.date).getUTCDate(),
+    y: (d) => new Date(d.date).getUTCMonth(),
+    color: 'temp_max'
+  },
+  transform: [{ type: 'group', color: 'max' }]  // 必须聚合 color 通道
+});
+```