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

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

@@ -0,0 +1,164 @@
+---
+id: "g2-transform-pack"
+title: "G2 Pack Transform"
+description: |
+  打包布局 Transform，将多个图形元素均匀排列避免重叠。
+  常用于 Treemap、气泡图等需要自动布局的场景。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "打包"
+  - "pack"
+  - "布局"
+  - "防重叠"
+  - "网格"
+
+related:
+  - "g2-mark-pack"
+  - "g2-mark-treemap"
+
+use_cases:
+  - "多个图形元素的自动排列"
+  - "小多图网格布局"
+  - "避免图形重叠"
+
+anti_patterns:
+  - "单个图形不需要打包"
+  - "已有明确位置信息的数据"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/transform"
+---
+
+## 核心概念
+
+Pack Transform 通过变换（translate + scale）将多个图形元素均匀排列，避免重叠。它会自动计算每个元素的位置和缩放比例。
+
+**工作原理：**
+1. 计算每个元素的边界框
+2. 根据容器尺寸计算网格布局
+3. 对每个元素应用 translate 和 scale 变换
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'pack',
+   {
+    nodes: [
+      { name: 'A', value: 100 },
+      { name: 'B', value: 80 },
+      { name: 'C', value: 60 },
+    ],
+  },
+  encode: {
+    value: 'value',
+    color: 'value',
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 作为 Transform 使用
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  transform: [
+    {
+      type: 'pack',
+      padding: 5,        // 元素间距
+      direction: 'col',  // 排列方向: 'col' | 'row'
+    },
+  ],
+});
+```
+
+### 自定义间距
+
+```javascript
+chart.options({
+  type: 'pack',
+  data,
+  encode: { value: 'value', color: 'value' },
+  transform: [
+    {
+      type: 'pack',
+      padding: 10,  // 元素之间的间距
+    },
+  ],
+});
+```
+
+### 按行排列
+
+```javascript
+chart.options({
+  type: 'pack',
+  data,
+  encode: { value: 'value', color: 'value' },
+  transform: [
+    {
+      type: 'pack',
+      direction: 'row',  // 按行排列
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface PackTransform {
+  type: 'pack';
+  padding?: number;       // 元素间距，默认 0
+  direction?: 'col' | 'row';  // 排列方向，默认 'col'
+}
+```
+
+## 与 Pack Mark 的关系
+
+Pack Mark 内部使用 Pack Transform 进行布局：
+- **Pack Mark**：用于创建圆形打包图（Circle Packing）
+- **Pack Transform**：用于任意图形元素的网格排列
+
+## 常见错误与修正
+
+### 错误 1：padding 值过大
+
+```javascript
+// ❌ 错误：padding 过大会导致元素被过度压缩
+transform: [{ type: 'pack', padding: 50 }]
+
+// ✅ 正确：合理的 padding 值
+transform: [{ type: 'pack', padding: 5 }]
+```
+
+### 错误 2：direction 参数错误
+
+```javascript
+// ❌ 错误
+transform: [{ type: 'pack', direction: 'horizontal' }]
+
+// ✅ 正确
+transform: [{ type: 'pack', direction: 'row' }]
+```

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

@@ -0,0 +1,143 @@
+---
+id: "g2-transform-sample"
+title: "G2 Sample 数据采样变换"
+description: |
+  sample 变换在数据超过阈值（默认 2000 条）时自动对数据降采样，
+  避免大数据集渲染过慢或视觉过于密集。
+  支持 first、last、min、max、median、lttb（最大三角形，保留趋势）等多种策略。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "sample"
+  - "采样"
+  - "大数据"
+  - "性能优化"
+  - "lttb"
+  - "降采样"
+  - "transform"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-transform-filter"
+
+use_cases:
+  - "折线图数据超过 2000 条时保留视觉趋势的采样"
+  - "实时数据流的性能优化"
+  - "股票K线等大时间序列可视化"
+
+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/sample"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 模拟 5000 条时间序列数据
+const data = Array.from({ length: 5000 }, (_, i) => ({
+  time: new Date(2020, 0, 1 + Math.floor(i / 10)).toISOString(),
+  value: Math.sin(i / 50) * 100 + Math.random() * 20,
+}));
+
+const chart = new Chart({ container: 'container', width: 800, height: 400 });
+
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'time', y: 'value' },
+  transform: [
+    {
+      type: 'sample',
+      thresholds: 500,     // 超过 500 条才触发采样
+      strategy: 'lttb',   // 最大三角形采样，最佳保留视觉趋势
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 采样策略对比
+
+```javascript
+// lttb（推荐）：最大三角形三桶算法，视觉保真度最高
+transform: [{ type: 'sample', strategy: 'lttb', thresholds: 500 }]
+
+// median：取每桶中位数，平滑但可能丢失极值
+transform: [{ type: 'sample', strategy: 'median', thresholds: 1000 }]
+
+// min/max：保留每桶最小/最大值，适合保留极值场景
+transform: [{ type: 'sample', strategy: 'max', thresholds: 800 }]
+
+// first/last：取每桶第一/最后一条，性能最好但精度最低
+transform: [{ type: 'sample', strategy: 'first', thresholds: 2000 }]
+```
+
+## 多系列分组采样
+
+```javascript
+// groupBy 指定分组字段，每个系列独立采样
+chart.options({
+  type: 'line',
+  data: multiSeriesData,
+  encode: { x: 'time', y: 'value', color: 'series' },
+  transform: [
+    {
+      type: 'sample',
+      thresholds: 300,
+      strategy: 'lttb',
+      groupBy: ['series', 'color'],  // 按系列分组，每组独立降采样
+    },
+  ],
+});
+```
+
+## 配置项
+
+```javascript
+transform: [
+  {
+    type: 'sample',
+    strategy: 'median',   // 采样策略：'first'|'last'|'min'|'max'|'median'|'lttb'|function
+                          // 默认 'median'
+    thresholds: 2000,     // 触发采样的数据量阈值，默认 2000
+    groupBy: ['series', 'color'],  // 分组字段，默认 ['series', 'color']
+  },
+]
+```
+
+## 常见错误与修正
+
+### 错误 1：thresholds 设置太高——数据虽大但不触发采样
+```javascript
+// ❌ 10000 条数据，thresholds 是默认的 2000，但策略不对
+transform: [{ type: 'sample' }]  // 默认 thresholds: 2000，strategy: 'median'
+// ⚠️  对 10000 条数据只降到 2000 条，可能还是太多
+
+// ✅ 根据渲染目标明确设置 thresholds
+transform: [{ type: 'sample', thresholds: 300, strategy: 'lttb' }]
+```
+
+### 错误 2：对柱状图使用 sample——破坏完整分类
+```javascript
+// ❌ 柱状图采样后，某些分类会消失，视觉上有断层
+chart.options({
+  type: 'interval',
+  encode: { x: 'category', y: 'value' },
+  transform: [{ type: 'sample' }],  // ❌ 柱状图通常不需要采样
+});
+
+// ✅ sample 主要用于折线图等连续数据
+chart.options({
+  type: 'line',
+  encode: { x: 'time', y: 'value' },
+  transform: [{ type: 'sample', strategy: 'lttb' }],  // ✅
+});
+```

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

@@ -0,0 +1,147 @@
+---
+id: "g2-transform-select"
+title: "G2 Select / SelectX / SelectY 筛选变换"
+description: |
+  select 系列变换从分组数据中筛选出特定的数据行用于标注。
+  selectX 按 x 通道分组后筛选（常用于折线图末端标签），
+  selectY 按 y 通道分组后筛选。
+  selector 支持 'first'、'last'、'min'、'max' 等预设值或自定义函数。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "select"
+  - "selectX"
+  - "selectY"
+  - "筛选"
+  - "末端标签"
+  - "极值标注"
+  - "transform"
+
+related:
+  - "g2-mark-line-basic"
+  - "g2-mark-text"
+  - "g2-comp-annotation"
+
+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/select"
+---
+
+## 最小可运行示例（折线图末端标签）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', type: 'A', value: 83 },
+  { month: 'Feb', type: 'A', value: 90 },
+  { month: 'Mar', type: 'A', value: 76 },
+  { month: 'Jan', type: 'B', value: 50 },
+  { month: 'Feb', type: 'B', value: 65 },
+  { month: 'Mar', type: 'B', value: 72 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+// 主折线图
+chart.options({
+  type: 'view',
+  children: [
+    {
+      type: 'line',
+       data,
+      encode: { x: 'month', y: 'value', color: 'type' },
+    },
+    // 末端标签：text mark + selectX（取每条线的最后一个点）
+    {
+      type: 'text',
+       data,
+      encode: { x: 'month', y: 'value', color: 'type', text: 'type' },
+      transform: [
+        {
+          type: 'selectX',
+          selector: 'last',   // 取每组（每条线）x 最大的点
+        },
+      ],
+      style: { textAnchor: 'start', dx: 6 },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 标注最大值
+
+```javascript
+// 在折线图最高点添加标注
+{
+  type: 'point',
+  data,
+  encode: { x: 'date', y: 'value', color: 'type' },
+  transform: [
+    {
+      type: 'selectY',
+      selector: 'max',   // 每组取 y 值最大的点
+    },
+  ],
+  style: { r: 6, lineWidth: 2 },
+  labels: [{ text: (d) => `最高: ${d.value}`, position: 'top' }],
+}
+```
+
+## selector 速查
+
+```javascript
+// 取最后一个点（常用于末端标签）
+transform: [{ type: 'selectX', selector: 'last' }]
+
+// 取第一个点
+transform: [{ type: 'selectX', selector: 'first' }]
+
+// 取 y 值最大的点
+transform: [{ type: 'selectY', selector: 'max' }]
+
+// 取 y 值最小的点
+transform: [{ type: 'selectY', selector: 'min' }]
+
+// 自定义：取第 N 个点
+transform: [{ type: 'selectX', selector: (data) => data[Math.floor(data.length / 2)] }]
+```
+
+## 常见错误与修正
+
+### 错误：select 用在 line mark 自身——应用在独立的 text/point mark
+```javascript
+// ❌ 在 line mark 上用 selectX，整条线只剩一个点
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'value' },
+  transform: [{ type: 'selectX', selector: 'last' }],  // ❌ 会把折线变成单点
+});
+
+// ✅ select 用在额外的 text 或 point mark，与 line 并列
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'line', data, encode: { x: 'month', y: 'value' } },
+    {
+      type: 'text',
+      data,
+      encode: { x: 'month', y: 'value', text: 'value' },
+      transform: [{ type: 'selectX', selector: 'last' }],  // ✅ 独立 mark
+    },
+  ],
+});
+```

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

@@ -0,0 +1,179 @@
+---
+id: "g2-transform-selectx"
+title: "G2 SelectX Transform"
+description: |
+  按 X 通道选择数据子集。用于筛选每个 X 类别的特定数据点，
+  如最大值、最小值、首个、末个等。
+
+library: "g2"
+version: "5.x"
+category: "transforms"
+tags:
+  - "选择"
+  - "筛选"
+  - "X轴"
+  - "极值"
+
+related:
+  - "g2-transform-select"
+  - "g2-transform-selecty"
+
+use_cases:
+  - "只显示每个类别的最大值"
+  - "筛选每个 X 分组的首个/末个数据点"
+  - "突出显示极值点"
+
+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"
+---
+
+## 核心概念
+
+SelectX Transform 按 X 通道分组，然后从每组中选择特定的数据点。选择器支持：
+- `max`：Y 值最大的点
+- `min`：Y 值最小的点
+- `first`：首个数据点
+- `last`：末个数据点
+- 自定义选择函数
+
+## 最小可运行示例
+
+```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: 25 },
+    { category: 'A', value: 15 },
+    { category: 'B', value: 20 },
+    { category: 'B', value: 35 },
+    { category: 'B', value: 30 },
+  ],
+  encode: {
+    x: 'category',
+    y: 'value',
+  },
+  transform: [
+    {
+      type: 'selectX',
+      selector: 'max',  // 只保留每个类别的最大值点
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 选择最小值
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  transform: [
+    { type: 'selectX', selector: 'min' },
+  ],
+});
+```
+
+### 选择首个/末个
+
+```javascript
+// 选择每个类别的第一个数据点
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  transform: [
+    { type: 'selectX', selector: 'first' },
+  ],
+});
+
+// 选择每个类别的最后一个数据点
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  transform: [
+    { type: 'selectX', selector: 'last' },
+  ],
+});
+```
+
+### 自定义选择器
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'category', y: 'value' },
+  transform: [
+    {
+      type: 'selectX',
+      selector: (I, Y) => {
+        // I: 组内索引数组
+        // Y: Y 通道的值数组
+        // 返回选中的索引
+        return I.reduce((maxIdx, i) => Y[i] > Y[maxIdx] ? i : maxIdx, I[0]);
+      },
+    },
+  ],
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface SelectXTransform {
+  type: 'selectX';
+  selector: 'max' | 'min' | 'first' | 'last' | ((I: number[], Y: any[]) => number);
+}
+```
+
+## 与 Select/SelectY 的对比
+
+| Transform | 分组维度 | 常用场景 |
+|-----------|---------|---------|
+| select | 按指定通道 | 通用选择 |
+| selectX | 按 X 通道 | X 轴分类筛选 |
+| selectY | 按 Y 通道 | Y 轴分类筛选 |
+
+## 常见错误与修正
+
+### 错误 1：selector 拼写错误
+
+```javascript
+// ❌ 错误
+transform: [{ type: 'selectX', selector: 'maximum' }]
+
+// ✅ 正确
+transform: [{ type: 'selectX', selector: 'max' }]
+```
+
+### 错误 2：自定义选择器返回值错误
+
+```javascript
+// ❌ 错误：返回了值而非索引
+selector: (I, Y) => Math.max(...I.map(i => Y[i]))
+
+// ✅ 正确：返回索引
+selector: (I, Y) => I.reduce((maxIdx, i) => Y[i] > Y[maxIdx] ? i : maxIdx, I[0])
+```