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

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

@@ -0,0 +1,149 @@
+---
+id: "g2-transform-jitter"
+title: "G2 Jitter 抖动变换（散开重叠点）"
+description: |
+  jitter 变换为分类轴上的数据点添加随机偏移，避免相同类别下数据点完全重叠。
+  jitter 同时抖动 X 和 Y，jitterX 只抖动 X（常用于条形图上的点），
+  jitterY 只抖动 Y。常与 point mark 配合展示分类数据分布。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "jitter"
+  - "抖动"
+  - "点图"
+  - "分布"
+  - "重叠"
+  - "beeswarm"
+  - "transform"
+
+related:
+  - "g2-mark-point-scatter"
+  - "g2-transform-dodgex"
+  - "g2-transform-stacky"
+
+use_cases:
+  - "展示各类别下数据点的分布密度（比箱线图更详细）"
+  - "类别轴上多个数据点防止重叠"
+  - "与箱线图叠加，同时显示统计摘要和原始数据"
+
+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/jitter"
+---
+
+## 最小可运行示例（jitter 防止分类散点图重叠）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'point',
+  data: [
+    { dept: '研发', salary: 18000 }, { dept: '研发', salary: 22000 },
+    { dept: '研发', salary: 15000 }, { dept: '研发', salary: 19000 },
+    { dept: '销售', salary: 12000 }, { dept: '销售', salary: 16000 },
+    { dept: '销售', salary: 14000 }, { dept: '销售', salary: 11000 },
+    { dept: '设计', salary: 17000 }, { dept: '设计', salary: 20000 },
+  ],
+  encode: {
+    x: 'dept',     // 分类轴（会在此方向抖动）
+    y: 'salary',
+    color: 'dept',
+  },
+  transform: [{ type: 'jitter' }],   // 在 x 和 y 方向添加随机抖动
+  style: { fillOpacity: 0.7, r: 4 },
+});
+
+chart.render();
+```
+
+## jitterX（仅水平抖动）
+
+```javascript
+// 适合竖向分类轴 — 仅在 x 方向展开，y 方向保持精确数值
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value', color: 'category' },
+  transform: [
+    {
+      type: 'jitterX',
+      padding: 0.1,    // 类别宽度比例（0~0.5），默认 0
+      random: Math.random,  // 自定义随机函数（可用固定种子）
+    },
+  ],
+});
+```
+
+## 与箱线图叠加
+
+```javascript
+chart.options({
+  type: 'view',
+  children: [
+    // 箱线图（显示统计摘要）
+    {
+      type: 'boxplot',
+      data,
+      encode: { x: 'dept', y: 'salary' },
+      style: { boxFill: 'transparent', lineWidth: 1.5 },
+    },
+    // 散点（显示原始数据分布）
+    {
+      type: 'point',
+      data,
+      encode: { x: 'dept', y: 'salary', color: 'dept' },
+      transform: [{ type: 'jitter', padding: 0.1 }],
+      style: { r: 3, fillOpacity: 0.6 },
+    },
+  ],
+});
+```
+
+## 配置项
+
+```javascript
+transform: [
+  {
+    type: 'jitter',    // 或 'jitterX' / 'jitterY'
+    padding: 0,        // 类别边界留白（0~0.5），默认 0
+    paddingX: 0,       // 单独设置 X 留白（覆盖 padding）
+    paddingY: 0,       // 单独设置 Y 留白（覆盖 padding）
+    random: Math.random, // 随机函数，可替换为固定种子伪随机
+  },
+]
+```
+
+## 常见错误与修正
+
+### 错误 1：在数值轴上使用 jitter——两个方向都是数值时效果混乱
+```javascript
+// ❌ 错误：x 和 y 都是数值时，jitter 会破坏精确的数值关系
+chart.options({
+  type: 'point',
+  encode: { x: 'price', y: 'sales' },  // 都是数值轴
+  transform: [{ type: 'jitter' }],      // ❌ 散点图本就不重叠，不需要
+});
+
+// ✅ jitter 应用于有分类轴的场景
+chart.options({
+  encode: { x: 'category', y: 'value' },  // x 是分类
+  transform: [{ type: 'jitter' }],         // ✅
+});
+```
+
+### 错误 2：point mark 数据量大时抖动效果不明显——padding 太小
+```javascript
+// ❌ 默认 padding: 0 时，所有点只在类别宽度极小范围内抖动
+transform: [{ type: 'jitter' }]  // padding 默认 0，抖动范围很小
+
+// ✅ 适当增大 padding
+transform: [{ type: 'jitter', padding: 0.15 }]  // 类别宽度 15% 作为抖动范围
+```

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

@@ -0,0 +1,177 @@
+---
+id: "g2-transform-jitterx"
+title: "G2 JitterX Transform"
+description: |
+  在 X 方向对数据进行抖动处理，避免点重叠。
+  常用于散点图中分类数据点的分散显示。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "抖动"
+  - "jitter"
+  - "散点图"
+  - "防重叠"
+  - "X轴"
+
+related:
+  - "g2-transform-jitter"
+  - "g2-transform-jittery"
+  - "g2-mark-point-scatter"
+
+use_cases:
+  - "分类散点图中避免点重叠"
+  - "展示分类数据的分布密度"
+  - "一维数据分布可视化"
+
+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/transform"
+---
+
+## 核心概念
+
+JitterX Transform 在 X 方向对数据点进行随机偏移，使重叠的点分散显示。这对于分类数据的散点图特别有用。
+
+**工作原理：**
+1. 根据 X 轴比例尺确定每个类别的范围
+2. 在范围内随机偏移每个点的 X 位置
+3. 通过 `padding` 控制偏移范围
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'point',
+  data: [
+    { category: 'A', value: 10 },
+    { category: 'A', value: 12 },
+    { category: 'A', value: 11 },
+    { category: 'B', value: 20 },
+    { category: 'B', value: 22 },
+  ],
+  encode: {
+    x: 'category',
+    y: 'value',
+  },
+  transform: [
+    { type: 'jitterX' },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 控制抖动范围
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  transform: [
+    {
+      type: 'jitterX',
+      padding: 0.2,  // 抖动范围比例，默认 0
+    },
+  ],
+});
+```
+
+### 自定义随机函数
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  transform: [
+    {
+      type: 'jitterX',
+      random: () => Math.random(),  // 默认 Math.random
+    },
+  ],
+});
+```
+
+### 结合 JitterY 使用
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'category2' },
+  transform: [
+    { type: 'jitterX' },
+    { type: 'jitterY' },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface JitterXTransform {
+  type: 'jitterX';
+  padding?: number;      // 抖动范围的内边距，默认 0
+  random?: () => number; // 随机数生成函数，默认 Math.random
+}
+```
+
+## 与 Jitter/JitterY 的对比
+
+| Transform | 抖动方向 | 常用场景 |
+|-----------|---------|---------|
+| jitter | X 和 Y | 二维分类数据 |
+| jitterX | 仅 X | X 轴分类数据 |
+| jitterY | 仅 Y | Y 轴分类数据 |
+
+## 常见错误与修正
+
+### 错误 1：对连续数据使用抖动
+
+```javascript
+// ❌ 不推荐：X 轴是连续数值时抖动可能造成误解
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'continuousValue', y: 'value' },
+  transform: [{ type: 'jitterX' }],
+});
+
+// ✅ 正确：X 轴是分类数据时使用
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  transform: [{ type: 'jitterX' }],
+});
+```
+
+### 错误 2：padding 值过大
+
+```javascript
+// ❌ 错误：padding 过大会导致点溢出到相邻类别
+transform: [{ type: 'jitterX', padding: 0.8 }]
+
+// ✅ 正确：合理的 padding 值
+transform: [{ type: 'jitterX', padding: 0.2 }]
+```

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

@@ -0,0 +1,177 @@
+---
+id: "g2-transform-jittery"
+title: "G2 JitterY Transform"
+description: |
+  在 Y 方向对数据进行抖动处理，避免点重叠。
+  常用于散点图中分类数据点的分散显示。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "抖动"
+  - "jitter"
+  - "散点图"
+  - "防重叠"
+  - "Y轴"
+
+related:
+  - "g2-transform-jitter"
+  - "g2-transform-jitterx"
+  - "g2-mark-point-scatter"
+
+use_cases:
+  - "分类散点图中避免点重叠"
+  - "水平方向分类数据的分布展示"
+  - "转置坐标系下的抖动"
+
+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/transform"
+---
+
+## 核心概念
+
+JitterY Transform 在 Y 方向对数据点进行随机偏移，使重叠的点分散显示。与 JitterX 对称，适用于 Y 轴为分类数据的情况。
+
+**工作原理：**
+1. 根据 Y 轴比例尺确定每个类别的范围
+2. 在范围内随机偏移每个点的 Y 位置
+3. 通过 `padding` 控制偏移范围
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'point',
+  data: [
+    { value: 10, category: 'A' },
+    { value: 12, category: 'A' },
+    { value: 11, category: 'A' },
+    { value: 20, category: 'B' },
+    { value: 22, category: 'B' },
+  ],
+  encode: {
+    x: 'value',
+    y: 'category',
+  },
+  transform: [
+    { type: 'jitterY' },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 控制抖动范围
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'value', y: 'category' },
+  transform: [
+    {
+      type: 'jitterY',
+      padding: 0.2,  // 抖动范围比例
+    },
+  ],
+});
+```
+
+### 结合 JitterX 使用
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'categoryX', y: 'categoryY' },
+  transform: [
+    { type: 'jitterX' },
+    { type: 'jitterY' },
+  ],
+});
+```
+
+### 自定义随机函数
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'value', y: 'category' },
+  transform: [
+    {
+      type: 'jitterY',
+      random: () => Math.random(),
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface JitterYTransform {
+  type: 'jitterY';
+  padding?: number;      // 抖动范围的内边距，默认 0
+  random?: () => number; // 随机数生成函数，默认 Math.random
+}
+```
+
+## 与 Jitter/JitterX 的对比
+
+| Transform | 抖动方向 | 常用场景 |
+|-----------|---------|---------|
+| jitter | X 和 Y | 二维分类数据 |
+| jitterX | 仅 X | X 轴分类数据 |
+| jitterY | 仅 Y | Y 轴分类数据 |
+
+## 常见错误与修正
+
+### 错误 1：对连续数据使用抖动
+
+```javascript
+// ❌ 不推荐：Y 轴是连续数值时抖动可能造成误解
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'value', y: 'continuousValue' },
+  transform: [{ type: 'jitterY' }],
+});
+
+// ✅ 正确：Y 轴是分类数据时使用
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'value', y: 'category' },
+  transform: [{ type: 'jitterY' }],
+});
+```
+
+### 错误 2：padding 值过大
+
+```javascript
+// ❌ 错误：padding 过大会导致点溢出到相邻类别
+transform: [{ type: 'jitterY', padding: 0.8 }]
+
+// ✅ 正确：合理的 padding 值
+transform: [{ type: 'jitterY', padding: 0.2 }]
+```

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

@@ -0,0 +1,83 @@
+---
+id: "g2-transform-normalizey"
+title: "G2 NormalizeY 归一化变换"
+description: |
+  NormalizeY 将每个 x 分组内的 y 值归一化到 [0, 1]，
+  通常跟在 stackY 之后使用，用于创建百分比堆叠图表，
+  消除总量差异，聚焦占比分布。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "normalizeY"
+  - "归一化"
+  - "百分比"
+  - "transform"
+  - "百分比堆叠"
+  - "占比"
+  - "spec"
+
+related:
+  - "g2-mark-interval-normalized"
+  - "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/normalize-y"
+---
+
+## 基本用法（必须配合 stackY）
+
+```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: 'stackY' },       // 第一步：堆叠
+    { type: 'normalizeY' },   // 第二步：归一化（顺序不能颠倒！）
+  ],
+  axis: {
+    y: { labelFormatter: (v) => `${(v * 100).toFixed(0)}%` },
+  },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+transform: [
+  { type: 'stackY' },
+  {
+    type: 'normalizeY',
+    basis: 'max',    // 归一化基准：'max'（默认，每组最大值）| 'min' | 'first' | 'last' | 'mean' | 'median'
+    series: 'y',     // 指定归一化的通道，默认 'y'
+  },
+],
+```
+
+## 常见错误与修正
+
+### 错误：normalizeY 在 stackY 之前执行
+```javascript
+// ❌ 错误：先归一化再堆叠，得不到百分比堆叠效果
+transform: [{ type: 'normalizeY' }, { type: 'stackY' }],
+
+// ✅ 正确：先堆叠，再归一化
+transform: [{ type: 'stackY' }, { type: 'normalizeY' }],
+```