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

package/builtin-skills/antv-g2-chart/references/scales/g2-scale-point.md

@@ -0,0 +1,242 @@
+---
+id: "g2-scale-point"
+title: "G2 Point Scale"
+description: |
+  点比例尺，将离散的类别映射到均匀分布的点上。
+  与 Band Scale 类似，但带宽固定为 0，常用于散点图的位置映射。
+
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "比例尺"
+  - "scale"
+  - "point"
+  - "离散"
+  - "位置"
+
+related:
+  - "g2-scale-band"
+  - "g2-scale-ordinal"
+  - "g2-mark-point-scatter"
+
+use_cases:
+  - "散点图的 X/Y 轴位置映射"
+  - "分类数据的位置映射"
+  - "需要均匀分布的离散数据"
+
+anti_patterns:
+  - "连续数值数据应使用 Linear Scale"
+  - "需要带宽的场景应使用 Band Scale"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/scale"
+---
+
+## 核心概念
+
+Point Scale 是一种离散比例尺：
+- 将类别映射到均匀分布的点位置
+- 带宽（bandwidth）固定为 0
+- 每个类别对应一个精确的位置点
+
+**与 Band Scale 的区别：**
+- Band Scale：每个类别占据一段区间（有带宽）
+- Point Scale：每个类别对应一个精确点（无带宽）
+
+## 最小可运行示例
+
+```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: 'B', value: 20 },
+    { category: 'C', value: 15 },
+  ],
+  encode: {
+    x: 'category',
+    y: 'value',
+  },
+  scale: {
+    x: { type: 'point' },
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 设置内边距
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  scale: {
+    x: {
+      type: 'point',
+      padding: 0.5,  // 两端的内边距，范围 [0, 1]
+    },
+  },
+});
+```
+
+### 设置对齐方式
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  scale: {
+    x: {
+      type: 'point',
+      align: 0.5,  // 0: 左对齐, 0.5: 居中, 1: 右对齐
+    },
+  },
+});
+```
+
+### 指定 domain
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  scale: {
+    x: {
+      type: 'point',
+      domain: ['A', 'B', 'C', 'D'],  // 显式指定类别顺序
+    },
+  },
+});
+```
+
+### 指定 range
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  scale: {
+    x: {
+      type: 'point',
+      range: [0.1, 0.9],  // 映射范围，默认 [0, 1]
+    },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface PointScaleOption {
+  type: 'point';
+  domain?: string[] | number[];  // 类别域
+  range?: [number, number];      // 输出范围，默认 [0, 1]
+  padding?: number;              // 内边距，默认 0
+  align?: number;                // 对齐方式，默认 0.5
+  round?: boolean;               // 是否四舍五入，默认 false
+}
+```
+
+## 与 Band Scale 的对比
+
+| 特性 | Point Scale | Band Scale |
+|------|-------------|------------|
+| 带宽 | 0 | 有带宽 |
+| 输出 | 精确点位置 | 区间起点 |
+| 适用 | 散点图、点图 | 柱状图、条形图 |
+| padding | 单一值 | paddingInner + paddingOuter |
+
+## 自动推断
+
+G2 会根据 mark 类型自动推断比例尺：
+- `interval` mark 的分类轴 → Band Scale
+- `point` mark 的分类轴 → Point Scale
+- `line` mark 的分类轴 → Band Scale
+
+```javascript
+// 自动推断为 Point Scale
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  // scale: { x: { type: 'point' } }  // 可省略
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：用于需要带宽的 mark（柱状图、热力图）
+
+`point` 比例尺 bandwidth = 0，`interval`（柱状图）和 `cell`（热力图）mark 依赖 bandwidth 来渲染有面积的图形。对这类 mark 使用 `point` 比例尺会导致柱体/格子宽度为 0，图形不可见。
+
+```javascript
+// ❌ 错误：柱状图用 point，柱体宽度为 0
+chart.options({
+  type: 'interval',
+  encode: { x: 'category', y: 'value' },
+  scale: { x: { type: 'point' } },  // ❌ bandwidth=0，柱子消失
+});
+
+// ❌ 错误：热力图用 point，格子宽度为 0（常见误用："确保均匀分布"）
+chart.options({
+  type: 'cell',
+  encode: { x: 'date', y: 'month', color: 'value' },
+  scale: {
+    x: { type: 'point' },  // ❌ cell 需要 bandwidth
+    y: { type: 'point' },  // ❌
+  },
+});
+
+// ✅ 正确：interval 和 cell 用 band（或省略，G2 自动推断）
+chart.options({
+  type: 'cell',
+  encode: { x: 'date', y: 'month', color: 'value' },
+  scale: {
+    x: { type: 'band' },   // ✅ 有带宽，格子可见
+    y: { type: 'band' },   // ✅
+  },
+  // 或直接省略 scale，cell mark 默认就是 band
+});
+```
+
+**适用 `point` 的 mark**：`point`（散点图）、`line`（折线图，用于分类 x 轴）。
+
+### 错误 2：padding 值过大
+
+```javascript
+// ❌ 错误：padding 超过范围
+scale: { x: { type: 'point', padding: 1.5 } }
+
+// ✅ 正确：padding 在 [0, 1] 范围内
+scale: { x: { type: 'point', padding: 0.5 } }
+```
+
+### 错误 3：align 值错误
+
+```javascript
+// ❌ 错误：align 超过范围
+scale: { x: { type: 'point', align: 2 } }
+
+// ✅ 正确：align 在 [0, 1] 范围内
+scale: { x: { type: 'point', align: 0.5 } }
+```

package/builtin-skills/antv-g2-chart/references/scales/g2-scale-pow-sqrt.md

@@ -0,0 +1,124 @@
+---
+id: "g2-scale-pow-sqrt"
+title: "G2 幂次比例尺（pow）和平方根比例尺（sqrt）"
+description: |
+  pow 比例尺将数值按幂函数（y = x^exponent）映射，exponent=0.5 时等同于 sqrt 比例尺。
+  sqrt 是 pow 的特例（exponent=0.5），将数值映射为平方根，
+  常用于面积编码（如气泡大小）确保视觉面积与数值成线性比例。
+
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "pow"
+  - "sqrt"
+  - "幂次"
+  - "平方根"
+  - "比例尺"
+  - "scale"
+  - "气泡图"
+
+related:
+  - "g2-scale-log"
+  - "g2-scale-linear"
+  - "g2-mark-point-bubble"
+
+use_cases:
+  - "气泡图 size 通道用 sqrt 比例尺（确保面积线性）"
+  - "数据轻微偏斜时用 pow 拉伸/压缩数值范围"
+  - "视觉编码中面积与数值的线性映射"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/scale/pow"
+---
+
+## 最小可运行示例（气泡图 sqrt 比例尺）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { country: '中国', gdp: 17.7, population: 141 },
+  { country: '美国', gdp: 25.5, population: 33 },
+  { country: '印度', gdp: 3.4,  population: 142 },
+  { country: '日本', gdp: 4.2,  population: 13 },
+  { country: '巴西', gdp: 1.8,  population: 22 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'point',
+  data,
+  encode: {
+    x: 'gdp',
+    y: 'country',
+    size: 'population',
+    color: 'country',
+  },
+  scale: {
+    size: {
+      type: 'sqrt',        // 平方根比例尺：面积与 population 成线性比例
+      range: [8, 60],      // 半径范围
+    },
+  },
+  style: { fillOpacity: 0.7 },
+});
+
+chart.render();
+```
+
+## pow 比例尺（自定义指数）
+
+```javascript
+// exponent = 2：数值越大差异越被放大（适合展示小差异）
+scale: {
+  y: {
+    type: 'pow',
+    exponent: 2,    // y = x^2，放大大值之间的差异
+  },
+}
+
+// exponent = 0.5：等同于 sqrt（压缩大值）
+scale: {
+  y: {
+    type: 'pow',
+    exponent: 0.5,  // 等同于 type: 'sqrt'
+  },
+}
+```
+
+## 为什么气泡大小要用 sqrt
+
+```javascript
+// ❌ 错误：用 linear 比例尺映射半径
+// 半径 r 与数值成线性，则面积 = πr²，面积与数值呈平方关系
+// 人口 100 和 400，视觉面积比是 1:16，误导读者
+scale: { size: { type: 'linear', range: [8, 60] } }  // ❌
+
+// ✅ 正确：用 sqrt 比例尺映射半径
+// 半径 r = sqrt(数值)，面积 = πr² = π×数值，面积与数值成线性
+// 人口 100 和 400，视觉面积比是 1:4，符合实际比例
+scale: { size: { type: 'sqrt', range: [8, 60] } }  // ✅
+```
+
+## 常见错误与修正
+
+### 错误：数据包含 0 或负数且 exponent < 1——sqrt(0) = 0 正常，但负数会得到 NaN
+```javascript
+// ❌ sqrt(-1) = NaN，数据中有负数时会报错
+chart.options({
+  scale: { y: { type: 'sqrt' } },
+   [{ y: -10 }],  // ❌ 负数
+});
+
+// ✅ sqrt 比例尺只适用于非负数
+// 如果有负数，先用 Math.abs 处理，或改用 linear
+chart.options({
+  scale: { y: { type: 'sqrt', domain: [0, 200] } },  // ✅ 确保 domain 非负
+});
+```

package/builtin-skills/antv-g2-chart/references/scales/g2-scale-quantile-quantize.md

@@ -0,0 +1,119 @@
+---
+id: "g2-scale-quantile-quantize"
+title: "G2 分位数比例尺（quantile）与分段比例尺（quantize）"
+description: |
+  quantile：按数据实际分布的分位数分组，每组数量相等（等频分组）。
+  quantize：按数值范围等分，每段区间宽度相等（等距分组）。
+  两者都将连续数值映射到离散输出（如颜色），常用于地图分级着色。
+  与 threshold 的区别是：threshold 手动指定断点，quantile/quantize 自动计算。
+
+library: "g2"
+version: "5.x"
+category: "scales"
+tags:
+  - "quantile"
+  - "quantize"
+  - "分位数"
+  - "等频"
+  - "等距"
+  - "比例尺"
+  - "scale"
+  - "分级着色"
+
+related:
+  - "g2-scale-threshold"
+  - "g2-scale-ordinal"
+  - "g2-mark-cell-heatmap"
+
+use_cases:
+  - "地图分级着色：按数据分布自动分组（quantile）"
+  - "等距分级着色（quantize）"
+  - "热力图的颜色分级"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/scale/quantile"
+---
+
+## quantile vs quantize vs threshold 对比
+
+| 比例尺 | 分组方式 | 适合场景 |
+|--------|---------|---------|
+| `threshold` | 手动指定断点 | 有业务含义的固定分级（如 60分=及格） |
+| `quantize` | 数值范围等距分段 | 均匀分布数据的等距分级 |
+| `quantile` | 数据实际分位数分组 | 偏斜分布数据的等频分级（每组数量相等） |
+
+## quantile 比例尺
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 640, height: 300 });
+
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'week', y: 'day', color: 'count' },
+  scale: {
+    color: {
+      type: 'quantile',
+      // 自动按数据分位数分组，每组记录数量相等
+      range: ['#ebedf0', '#c6e48b', '#7bc96f', '#196127'],
+      // domain 不需要指定，自动从数据中计算
+    },
+  },
+  style: { lineWidth: 2, stroke: '#fff' },
+});
+```
+
+## quantize 比例尺
+
+```javascript
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'hour', y: 'day', color: 'value' },
+  scale: {
+    color: {
+      type: 'quantize',
+      domain: [0, 100],  // 明确指定数值范围（会被等距分为 N 段）
+      range: ['#fee0d2', '#fc9272', '#de2d26'],  // 3 种颜色 = 3 段
+    },
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：quantile 数据极度偏斜时视觉效果差——用 threshold 手动设置
+```javascript
+// ⚠️  数据高度偏斜（如 95% 数据集中在低值），quantile 分组合理但视觉上
+// 大部分区域颜色相近，少数高值区域颜色鲜艳，不直观
+chart.options({ scale: { color: { type: 'quantile' } } });  // ⚠️  偏斜数据效果差
+
+// ✅ 偏斜数据改用 log 比例尺配合 sequential，或用 threshold 手动设置关键节点
+chart.options({
+  scale: {
+    color: {
+      type: 'threshold',
+      domain: [10, 100, 1000],  // 按对数级设置断点
+      range: ['#eee', '#fee', '#f66', '#c00'],
+    },
+  },
+});
+```
+
+### 错误：quantize 不指定 domain——自动从数据中推断，可能有边界问题
+```javascript
+// ⚠️  不指定 domain 时，quantize 从数据 min/max 推断，
+// 新数据超出范围时会超出色阶
+chart.options({ scale: { color: { type: 'quantize' } } });  // ⚠️  依赖数据范围
+
+// ✅ 明确指定业务含义的 domain
+chart.options({
+  scale: { color: { type: 'quantize', domain: [0, 100] } },  // ✅ 明确 0~100
+});
+```