@loom-framework/core 0.1.0-alpha.83 → 0.1.0-alpha.85

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-brushx-highlight.md

@@ -0,0 +1,186 @@
+---
+id: "g2-interaction-brushx-highlight"
+title: "G2 BrushXHighlight Interaction"
+description: |
+  X 轴方向刷选高亮交互。用户可以通过拖拽选择 X 轴范围，
+  高亮显示该范围内的数据元素。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "刷选"
+  - "高亮"
+  - "brush"
+  - "X轴"
+  - "数据探索"
+
+related:
+  - "g2-interaction-brush"
+  - "g2-interaction-brushy-highlight"
+  - "g2-interaction-brushx-filter"
+
+use_cases:
+  - "时间范围高亮"
+  - "X 轴区间选择高亮"
+  - "数据对比分析"
+
+anti_patterns:
+  - "需要过滤数据时改用 BrushXFilter"
+  - "需要 Y 轴方向选择时改用 BrushYHighlight"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction"
+---
+
+## 核心概念
+
+BrushXHighlight 交互允许用户在 X 轴方向拖拽选择一个区间，选区内的数据元素会被高亮显示，其他元素变暗。
+
+**特点：**
+- 只能在 X 轴方向选择
+- 高亮而非过滤数据
+- 适合数据探索和对比分析
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'interval',
+  data: [
+    { category: 'A', value: 100 },
+    { category: 'B', value: 150 },
+    { category: 'C', value: 80 },
+    { category: 'D', value: 200 },
+    { category: 'E', value: 120 },
+  ],
+  encode: {
+    x: 'category',
+    y: 'value',
+  },
+  interaction: {
+    brushXHighlight: true,
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 自定义刷选样式
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  interaction: {
+    brushXHighlight: {
+      brushStyle: {
+        fill: '#1890ff',
+        fillOpacity: 0.3,
+      },
+    },
+  },
+});
+```
+
+### 自定义高亮状态
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  interaction: {
+    brushXHighlight: {
+      selectedHandles: ['handle-e', 'handle-w'],  // 显示的拖拽手柄
+    },
+  },
+  state: {
+    active: {
+      fill: '#1890ff',
+      stroke: '#0050b3',
+      lineWidth: 2,
+    },
+    inactive: {
+      fillOpacity: 0.3,
+    },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface BrushXHighlightInteraction {
+  brushXHighlight: boolean | {
+    brushStyle?: {
+      fill?: string;
+      fillOpacity?: number;
+      stroke?: string;
+    };
+    selectedHandles?: string[];  // ['handle-e', 'handle-w']
+    // 其他配置继承自 BrushHighlight
+  };
+}
+```
+
+## 与 BrushHighlight/BrushYHighlight 的对比
+
+| Interaction | 选择方向 | 常用场景 |
+|-------------|---------|---------|
+| brushHighlight | 任意方向 | 通用高亮 |
+| brushXHighlight | 仅 X 方向 | 分类/时间范围高亮 |
+| brushYHighlight | 仅 Y 方向 | 数值范围高亮 |
+
+## 与 BrushXFilter 的区别
+
+| 特性 | BrushXHighlight | BrushXFilter |
+|------|-----------------|--------------|
+| 数据处理 | 高亮显示 | 过滤隐藏 |
+| 非选区数据 | 变暗但可见 | 完全隐藏 |
+| 适用场景 | 数据探索、对比 | 数据筛选、缩放 |
+
+## 常见错误与修正
+
+### 错误 1：与 Filter 交互混淆
+
+```javascript
+// ❌ 错误：想要过滤数据却用了 highlight
+interaction: { brushXHighlight: true }
+
+// ✅ 正确：根据需求选择
+// 需要高亮：brushXHighlight
+// 需要过滤：brushXFilter
+```
+
+### 错误 2：未配置 state 样式
+
+```javascript
+// ⚠️ 注意：默认高亮效果可能不明显
+// 建议配置 state 以获得更好的视觉效果
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'category', y: 'value' },
+  interaction: { brushXHighlight: true },
+  state: {
+    active: { fill: '#1890ff' },
+    inactive: { fillOpacity: 0.2 },
+  },
+});
+```

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-brushy-filter.md

@@ -0,0 +1,170 @@
+---
+id: "g2-interaction-brushy-filter"
+title: "G2 BrushYFilter Interaction"
+description: |
+  Y 轴方向刷选过滤交互。用户可以通过拖拽选择 Y 轴范围，
+  过滤显示该范围内的数据。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "刷选"
+  - "过滤"
+  - "brush"
+  - "Y轴"
+  - "数据筛选"
+
+related:
+  - "g2-interaction-brush-filter"
+  - "g2-interaction-brushx-filter"
+  - "g2-interaction-brushy-highlight"
+
+use_cases:
+  - "数值范围筛选"
+  - "Y 轴区间选择"
+  - "过滤异常值"
+
+anti_patterns:
+  - "需要 X 轴方向筛选时改用 BrushXFilter"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction"
+---
+
+## 核心概念
+
+BrushYFilter 交互允许用户在 Y 轴方向拖拽选择一个区间，图表会自动过滤并只显示该区间内的数据。
+
+**特点：**
+- 只能在 Y 轴方向选择
+- 选择后自动过滤数据
+- 适合数值范围筛选
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'point',
+  data: [
+    { x: 10, y: 100 },
+    { x: 20, y: 150 },
+    { x: 30, y: 80 },
+    { x: 40, y: 200 },
+    { x: 50, y: 120 },
+  ],
+  encode: {
+    x: 'x',
+    y: 'y',
+  },
+  interaction: {
+    brushYFilter: true,
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 自定义样式
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y' },
+  interaction: {
+    brushYFilter: {
+      brushStyle: {
+        fill: '#52c41a',
+        fillOpacity: 0.2,
+        stroke: '#52c41a',
+      },
+    },
+  },
+});
+```
+
+### 设置初始选区
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y' },
+  interaction: {
+    brushYFilter: {
+      selection: [0.3, 0.7],  // 初始选区比例 [start, end]
+    },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface BrushYFilterInteraction {
+  brushYFilter: boolean | {
+    brushStyle?: {
+      fill?: string;
+      fillOpacity?: number;
+      stroke?: string;
+      lineWidth?: number;
+    };
+    selection?: [number, number];  // [startRatio, endRatio]
+    // 其他配置继承自 BrushFilter
+  };
+}
+```
+
+## 与 BrushFilter/BrushXFilter 的对比
+
+| Interaction | 选择方向 | 常用场景 |
+|-------------|---------|---------|
+| brushFilter | 任意方向 | 通用筛选 |
+| brushXFilter | 仅 X 方向 | 时间范围筛选 |
+| brushYFilter | 仅 Y 方向 | 数值范围筛选 |
+
+## 常见错误与修正
+
+### 错误 1：与其他 brush 交互冲突
+
+```javascript
+// ❌ 错误：同时启用多个 brush 交互可能冲突
+interaction: {
+  brushXFilter: true,
+  brushYFilter: true,
+}
+
+// ✅ 正确：根据需求选择一个
+interaction: {
+  brushYFilter: true,
+}
+```
+
+### 错误 2：selection 参数格式错误
+
+```javascript
+// ❌ 错误：selection 应该是比例值 [0-1]
+interaction: {
+  brushYFilter: { selection: [100, 200] }
+}
+
+// ✅ 正确：使用比例值
+interaction: {
+  brushYFilter: { selection: [0.2, 0.6] }
+}
+```

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-brushy-highlight.md

@@ -0,0 +1,185 @@
+---
+id: "g2-interaction-brushy-highlight"
+title: "G2 BrushYHighlight Interaction"
+description: |
+  Y 轴方向刷选高亮交互。用户可以通过拖拽选择 Y 轴范围，
+  高亮显示该范围内的数据元素。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "刷选"
+  - "高亮"
+  - "brush"
+  - "Y轴"
+  - "数据探索"
+
+related:
+  - "g2-interaction-brush"
+  - "g2-interaction-brushx-highlight"
+  - "g2-interaction-brushy-filter"
+
+use_cases:
+  - "数值范围高亮"
+  - "Y 轴区间选择高亮"
+  - "异常值识别"
+
+anti_patterns:
+  - "需要过滤数据时改用 BrushYFilter"
+  - "需要 X 轴方向选择时改用 BrushXHighlight"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-26"
+updated: "2025-03-26"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction"
+---
+
+## 核心概念
+
+BrushYHighlight 交互允许用户在 Y 轴方向拖拽选择一个区间，选区内的数据元素会被高亮显示，其他元素变暗。
+
+**特点：**
+- 只能在 Y 轴方向选择
+- 高亮而非过滤数据
+- 适合数值范围的数据探索
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 640,
+  height: 480,
+});
+
+chart.options({
+  type: 'point',
+  data: [
+    { x: 10, y: 100 },
+    { x: 20, y: 150 },
+    { x: 30, y: 80 },
+    { x: 40, y: 200 },
+    { x: 50, y: 120 },
+  ],
+  encode: {
+    x: 'x',
+    y: 'y',
+  },
+  interaction: {
+    brushYHighlight: true,
+  },
+});
+
+chart.render();
+```
+
+## 常用变体
+
+### 自定义刷选样式
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y' },
+  interaction: {
+    brushYHighlight: {
+      brushStyle: {
+        fill: '#52c41a',
+        fillOpacity: 0.3,
+      },
+    },
+  },
+});
+```
+
+### 自定义高亮状态
+
+```javascript
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y' },
+  interaction: {
+    brushYHighlight: {
+      selectedHandles: ['handle-n', 'handle-s'],  // 显示的拖拽手柄
+    },
+  },
+  state: {
+    active: {
+      fill: '#52c41a',
+      r: 8,
+    },
+    inactive: {
+      fillOpacity: 0.3,
+    },
+  },
+});
+```
+
+## 完整类型参考
+
+```typescript
+interface BrushYHighlightInteraction {
+  brushYHighlight: boolean | {
+    brushStyle?: {
+      fill?: string;
+      fillOpacity?: number;
+      stroke?: string;
+    };
+    selectedHandles?: string[];  // ['handle-n', 'handle-s']
+    // 其他配置继承自 BrushHighlight
+  };
+}
+```
+
+## 与 BrushHighlight/BrushXHighlight 的对比
+
+| Interaction | 选择方向 | 常用场景 |
+|-------------|---------|---------|
+| brushHighlight | 任意方向 | 通用高亮 |
+| brushXHighlight | 仅 X 方向 | 分类/时间范围高亮 |
+| brushYHighlight | 仅 Y 方向 | 数值范围高亮 |
+
+## 与 BrushYFilter 的区别
+
+| 特性 | BrushYHighlight | BrushYFilter |
+|------|-----------------|--------------|
+| 数据处理 | 高亮显示 | 过滤隐藏 |
+| 非选区数据 | 变暗但可见 | 完全隐藏 |
+| 适用场景 | 数据探索、对比 | 数据筛选、缩放 |
+
+## 常见错误与修正
+
+### 错误 1：与 Filter 交互混淆
+
+```javascript
+// ❌ 错误：想要过滤数据却用了 highlight
+interaction: { brushYHighlight: true }
+
+// ✅ 正确：根据需求选择
+// 需要高亮：brushYHighlight
+// 需要过滤：brushYFilter
+```
+
+### 错误 2：未配置 state 样式
+
+```javascript
+// ⚠️ 注意：默认高亮效果可能不明显
+// 建议配置 state 以获得更好的视觉效果
+chart.options({
+  type: 'point',
+  data,
+  encode: { x: 'x', y: 'y' },
+  interaction: { brushYHighlight: true },
+  state: {
+    active: { fill: '#52c41a', r: 8 },
+    inactive: { fillOpacity: 0.2 },
+  },
+});
+```

package/builtin-skills/antv-g2-chart/references/interactions/g2-interaction-chart-index.md

@@ -0,0 +1,127 @@
+---
+id: "g2-interaction-chart-index"
+title: "G2 ChartIndex 联动游标线"
+description: |
+  chartIndex 在图表上渲染一条随鼠标移动的垂直游标线（参考线），
+  并可联动多个图表的游标，用于多图表横向对比同一时间点的数据。
+  适合时序数据多图联动、Dashboard 中多指标同步查看场景。
+
+library: "g2"
+version: "5.x"
+category: "interactions"
+tags:
+  - "chartIndex"
+  - "游标线"
+  - "联动"
+  - "参考线"
+  - "多图联动"
+  - "interaction"
+  - "crosshair"
+
+related:
+  - "g2-interaction-tooltip"
+  - "g2-mark-linex-liney"
+  - "g2-recipe-dashboard"
+
+use_cases:
+  - "多折线图联动查看同一时间点各指标值"
+  - "时序数据 Dashboard 中的十字游标"
+  - "对比两个时间序列的同期数据"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/interaction/chart-index"
+---
+
+## 核心概念
+
+`chartIndex` 在绘图区域渲染一条垂直参考线，随鼠标 X 轴位置移动。
+与 `shared: true` 的 Tooltip 配合，可实现多系列同时刻数据的联动高亮。
+
+## 单图游标线
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 800, height: 400 });
+
+chart.options({
+  type: 'line',
+  data: timeSeriesData,
+  encode: { x: 'date', y: 'value', color: 'type' },
+  interaction: {
+    chartIndex: true,          // 启用游标线
+    tooltip: { shared: true }, // 配合共享 Tooltip
+  },
+});
+
+chart.render();
+```
+
+## 配置项
+
+```javascript
+chart.options({
+  interaction: {
+    chartIndex: {
+      // 游标线样式
+      ruleStroke: '#aaa',          // 游标线颜色，默认 '#aaa'
+      ruleLineWidth: 1,            // 游标线宽度，默认 1
+      ruleLineDash: [4, 4],        // 游标线虚线样式
+      // 标签配置
+      labelDy: -8,                 // 标签垂直偏移
+      labelBackground: true,       // 是否显示标签背景
+      labelBackgroundFill: '#fff', // 标签背景色
+      // 性能控制
+      wait: 50,                    // 防抖时间（毫秒），默认 50
+      leading: true,               // 防抖前缘触发
+      trailing: false,             // 防抖后缘触发
+    },
+  },
+});
+```
+
+## 多图联动（相同容器父元素）
+
+```javascript
+// 通过共享 emit 事件实现多图游标联动
+// 两个图表使用同一 emitter（需要手动实现或使用 G2 的 on/emit API）
+const chart1 = new Chart({ container: 'container1', width: 800, height: 200 });
+const chart2 = new Chart({ container: 'container2', width: 800, height: 200 });
+
+[chart1, chart2].forEach((chart) => {
+  chart.options({
+    type: 'line',
+    data: timeSeriesData,
+    encode: { x: 'date', y: 'value' },
+    interaction: {
+      chartIndex: true,
+    },
+  });
+  chart.render();
+});
+```
+
+## 常见错误与修正
+
+### 错误：游标线出现但 Tooltip 不显示同时刻数据
+```javascript
+// ❌ 多系列图表，Tooltip 只显示当前鼠标最近的元素
+chart.options({
+  interaction: {
+    chartIndex: true,
+    // 缺少 tooltip shared 配置
+  },
+});
+
+// ✅ 开启 shared Tooltip，所有系列同时刻数据一起显示
+chart.options({
+  interaction: {
+    chartIndex: true,
+    tooltip: { shared: true },   // 必须配合
+  },
+});
+```