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

package/builtin-skills/antv-g2-chart/references/compositions/g2-comp-repeat-matrix.md

@@ -0,0 +1,171 @@
+---
+id: "g2-comp-repeat-matrix"
+title: "G2 重复矩阵（repeatMatrix）"
+description: |
+  G2 v5 repeatMatrix 组合类型将同一图表按两个维度字段重复排列成矩阵，
+  每个格子共享相同的 Mark 配置，x 轴和 y 轴分别对应一个分类字段，
+  适合展示多变量之间的两两关系（散点图矩阵）。
+
+library: "g2"
+version: "5.x"
+category: "compositions"
+tags:
+  - "重复矩阵"
+  - "repeatMatrix"
+  - "散点图矩阵"
+  - "多变量"
+  - "分面"
+  - "spec"
+
+related:
+  - "g2-comp-facet-rect"
+  - "g2-mark-point-scatter"
+  - "g2-core-view-composition"
+
+use_cases:
+  - "多变量两两散点图矩阵"
+  - "多维度数据的相关性探索"
+  - "对角线展示分布直方图"
+
+difficulty: "advanced"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/examples/general/matrix"
+---
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+  width: 800,
+  height: 800,
+});
+
+// 多维度数据（每行是一个样本，多个数值字段）
+const data = [
+  { sepalLength: 5.1, sepalWidth: 3.5, petalLength: 1.4, petalWidth: 0.2, species: 'setosa' },
+  { sepalLength: 4.9, sepalWidth: 3.0, petalLength: 1.4, petalWidth: 0.2, species: 'setosa' },
+  { sepalLength: 7.0, sepalWidth: 3.2, petalLength: 4.7, petalWidth: 1.4, species: 'versicolor' },
+  { sepalLength: 6.4, sepalWidth: 3.2, petalLength: 4.5, petalWidth: 1.5, species: 'versicolor' },
+  { sepalLength: 6.3, sepalWidth: 3.3, petalLength: 6.0, petalWidth: 2.5, species: 'virginica' },
+  // ...更多数据
+];
+
+chart.options({
+  type: 'repeatMatrix',
+  data,
+  encode: {
+    x: ['sepalLength', 'sepalWidth', 'petalLength'],   // 列变量
+    y: ['sepalLength', 'sepalWidth', 'petalLength'],   // 行变量
+  },
+  children: [
+    {
+      type: 'point',
+      encode: { color: 'species' },
+      style: { r: 3, fillOpacity: 0.7 },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 完整散点图矩阵（含对角线）
+
+```javascript
+chart.options({
+  type: 'repeatMatrix',
+  data,
+  encode: {
+    x: ['sepalLength', 'sepalWidth', 'petalLength', 'petalWidth'],
+    y: ['sepalLength', 'sepalWidth', 'petalLength', 'petalWidth'],
+  },
+  // 格子间距
+  padding: 10,
+  children: [
+    {
+      type: 'point',
+      encode: { color: 'species' },
+      style: { r: 2.5, fillOpacity: 0.6 },
+      legend: { color: { position: 'top' } },
+    },
+  ],
+});
+```
+
+## 与 facetRect 的对比
+
+```javascript
+// repeatMatrix：x/y encode 均为变量数组，自动排列成 n×n 矩阵
+chart.options({
+  type: 'repeatMatrix',
+  encode: {
+    x: ['var1', 'var2', 'var3'],
+    y: ['var1', 'var2', 'var3'],
+  },
+  children: [{ type: 'point', encode: { color: 'category' } }],
+});
+
+// facetRect：按单个分类字段的不同值分面（每个值一个格子，排成一行或一列）
+chart.options({
+  type: 'facetRect',
+  encode: { x: 'region' },   // 按 region 的不同值分成多列
+  children: [
+    {
+      type: 'interval',
+      encode: { x: 'month', y: 'sales' },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误 1：encode.x/y 写成单个字段而非数组
+
+```javascript
+// ❌ 错误：repeatMatrix 的 encode.x/y 必须是字段名数组
+chart.options({
+  type: 'repeatMatrix',
+  encode: {
+    x: 'sepalLength',   // ❌ 单个字段名
+    y: 'sepalWidth',
+  },
+});
+
+// ✅ 正确：x/y 都必须是数组
+chart.options({
+  type: 'repeatMatrix',
+  encode: {
+    x: ['sepalLength', 'sepalWidth', 'petalLength'],   // ✅ 数组
+    y: ['sepalLength', 'sepalWidth', 'petalLength'],
+  },
+});
+```
+
+### 错误 2：将散点图矩阵与普通分面混淆
+
+```javascript
+// ❌ 错误：想做散点图矩阵却用了 facetRect
+chart.options({
+  type: 'facetRect',
+  encode: {
+    x: ['sepalLength', 'sepalWidth'],   // ❌ facetRect 的 encode.x 只接受单个字段
+  },
+});
+
+// ✅ 正确：多变量两两比较用 repeatMatrix
+chart.options({
+  type: 'repeatMatrix',
+  encode: {
+    x: ['sepalLength', 'sepalWidth'],   // ✅
+    y: ['sepalLength', 'sepalWidth'],
+  },
+  children: [{ type: 'point', encode: { color: 'species' } }],
+});
+```

package/builtin-skills/antv-g2-chart/references/compositions/g2-comp-space-flex.md

@@ -0,0 +1,142 @@
+---
+id: "g2-comp-space-flex"
+title: "G2 弹性布局（spaceFlex）"
+description: |
+  spaceFlex 将多个子图按弹性比例（ratio）排列在行（row）或列（col）方向。
+  类似 CSS flexbox，每个子图的大小由 ratio 数组按比例分配画布空间。
+  适合制作不等宽的多图并排布局，比 repeatMatrix 更灵活。
+
+library: "g2"
+version: "5.x"
+category: "compositions"
+tags:
+  - "spaceFlex"
+  - "弹性布局"
+  - "多图"
+  - "flex"
+  - "并排"
+  - "composition"
+
+related:
+  - "g2-comp-space-layer"
+  - "g2-comp-facet-rect"
+  - "g2-comp-repeat-matrix"
+
+use_cases:
+  - "左宽右窄的双图布局（如 2:1 比例）"
+  - "多图等分排列（如 3 个等宽图表）"
+  - "不等宽的多图并排展示"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/composition/space-flex"
+---
+
+## 最小可运行示例（左右 2:1 布局）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({ container: 'container', width: 900, height: 400 });
+
+chart.options({
+  type: 'spaceFlex',
+  width: 900,
+  height: 400,
+  direction: 'row',      // 'row'（横向）或 'col'（纵向）
+  ratio: [2, 1],         // 左图占 2/3，右图占 1/3
+  padding: 20,           // 子图间距
+  children: [
+    // 左图：折线图（占 2/3 宽度）
+    {
+      type: 'line',
+       salesData,
+      encode: { x: 'month', y: 'value', color: 'city' },
+      title: '月度销售趋势',
+    },
+    // 右图：饼图（占 1/3 宽度）
+    {
+      type: 'interval',
+       categoryData,
+      encode: { y: 'value', color: 'type' },
+      transform: [{ type: 'stackY' }],
+      coordinate: { type: 'theta', outerRadius: 0.85 },
+      title: '类别占比',
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 纵向布局（上大下小）
+
+```javascript
+chart.options({
+  type: 'spaceFlex',
+  width: 640,
+  height: 700,
+  direction: 'col',      // 纵向排列
+  ratio: [3, 1],         // 上图占 3/4 高度，下图占 1/4
+  children: [
+    {
+      type: 'line',
+       timeData,
+      encode: { x: 'date', y: 'value', color: 'type' },
+    },
+    // 缩略轴图（底部小图）
+    {
+      type: 'line',
+       timeData,
+      encode: { x: 'date', y: 'value', color: 'type' },
+      style: { lineWidth: 1 },
+      axis: { y: false },
+    },
+  ],
+});
+```
+
+## 等分三图并排
+
+```javascript
+chart.options({
+  type: 'spaceFlex',
+  direction: 'row',
+  ratio: [1, 1, 1],   // 三图等宽
+  children: [chart1Config, chart2Config, chart3Config],
+});
+```
+
+## 常见错误与修正
+
+### 错误：ratio 数组长度与 children 不一致
+```javascript
+// ❌ 错误：3 个子图但 ratio 只有 2 个值
+chart.options({
+  type: 'spaceFlex',
+  ratio: [2, 1],       // ❌ 只有 2 个比例值
+  children: [c1, c2, c3],  // 3 个子图
+});
+
+// ✅ ratio 数组长度必须等于 children 数组长度
+chart.options({
+  ratio: [2, 1, 1],   // ✅ 3 个比例值对应 3 个子图
+  children: [c1, c2, c3],
+});
+```
+
+### 错误：子图没有设置宽高——spaceFlex 会自动计算，不需要子图单独设置
+```javascript
+// ⚠️  子图单独设置 width/height 会覆盖 spaceFlex 的自动布局
+children: [
+  { type: 'line', width: 400, height: 300, ... },  // ⚠️  不要单独设置
+]
+
+// ✅ 子图只设置内容，宽高由父级 spaceFlex 按 ratio 自动分配
+children: [
+  { type: 'line', data: ..., encode: { ... } },  // ✅ 不设置宽高
+]
+```

package/builtin-skills/antv-g2-chart/references/compositions/g2-comp-space-layer.md

@@ -0,0 +1,149 @@
+---
+id: "g2-comp-space-layer"
+title: "G2 图层叠加（spaceLayer / view 多 mark）"
+description: |
+  spaceLayer 将多个视图堆叠在同一区域（共享坐标轴），
+  实现折线图 + 柱状图叠加、折线图 + 散点图叠加等复合图表。
+  更常见的用法是在单个 view 中使用 children 数组配置多个 mark。
+
+library: "g2"
+version: "5.x"
+category: "compositions"
+tags:
+  - "spaceLayer"
+  - "图层"
+  - "叠加"
+  - "复合图表"
+  - "双轴图"
+  - "view"
+  - "children"
+
+related:
+  - "g2-core-view-composition"
+  - "g2-comp-facet-rect"
+
+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/composition/space-layer"
+---
+
+## 最小可运行示例（柱状图 + 折线图）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', sales: 200, growth: 15 },
+  { month: 'Feb', sales: 280, growth: 22 },
+  { month: 'Mar', sales: 320, growth: 8 },
+  { month: 'Apr', sales: 250, growth: -5 },
+  { month: 'May', sales: 410, growth: 18 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 400 });
+
+// 方式一：type: 'view' + children（推荐，最简洁）
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    // 柱状图：展示销售额
+    {
+      type: 'interval',
+      encode: { x: 'month', y: 'sales', color: '#5B8FF9' },
+      style: { fillOpacity: 0.8 },
+      axis: { y: { title: '销售额' } },
+    },
+    // 折线图：展示增长率（共享 x 轴）
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'growth' },
+      scale: { y: { independent: true } },  // 独立 y 轴（双 Y 轴）
+      style: { lineWidth: 2.5, stroke: '#F4664A' },
+      axis: { y: { position: 'right', title: '增长率 (%)' } },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 折线图 + 散点（mark 复合）
+
+```javascript
+chart.options({
+  type: 'view',
+  data,
+  children: [
+    {
+      type: 'line',
+      encode: { x: 'date', y: 'value', color: 'type' },
+      style: { lineWidth: 2 },
+    },
+    {
+      type: 'point',
+      encode: { x: 'date', y: 'value', color: 'type' },
+      style: { r: 4, lineWidth: 1, fill: '#fff' },
+    },
+  ],
+});
+```
+
+## 面积图 + 折线（置信区间）
+
+```javascript
+chart.options({
+  type: 'view',
+  data: confidenceData,
+  children: [
+    // 置信区间（面积）
+    {
+      type: 'area',
+      encode: { x: 'date', y: 'upper', y1: 'lower', color: '#5B8FF9' },
+      style: { fillOpacity: 0.2 },
+    },
+    // 中线（折线）
+    {
+      type: 'line',
+      encode: { x: 'date', y: 'mean' },
+      style: { lineWidth: 2, stroke: '#5B8FF9' },
+    },
+  ],
+});
+```
+
+## 常见错误与修正
+
+### 错误：双 Y 轴不设置 independent: true——两组数据被映射到同一 y 轴范围
+```javascript
+// ❌ sales（0~400）和 growth（-10~25）共用一个 y 轴，growth 曲线近乎水平
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'interval', encode: { x: 'month', y: 'sales' } },
+    { type: 'line',     encode: { x: 'month', y: 'growth' } },  // ❌ 没有独立 y 轴
+  ],
+});
+
+// ✅ 第二个 y 轴设置 independent: true
+chart.options({
+  type: 'view',
+  children: [
+    { type: 'interval', encode: { x: 'month', y: 'sales' } },
+    {
+      type: 'line',
+      encode: { x: 'month', y: 'growth' },
+      scale: { y: { independent: true } },  // ✅ 独立比例尺
+      axis: { y: { position: 'right' } },    // ✅ 放在右侧
+    },
+  ],
+});
+```

package/builtin-skills/antv-g2-chart/references/compositions/g2-comp-timing-keyframe.md

@@ -0,0 +1,91 @@
+---
+id: "g2-comp-timing-keyframe"
+title: "G2 timingKeyframe 关键帧动画组合"
+description: |
+  timingKeyframe 是 G2 v5 的组合类型，将多个图表视图按时序播放形成关键帧动画。
+  各子视图依次渲染并在相邻帧之间自动插值过渡，实现数据故事讲述效果。
+  参见 g2-animation-keyframe 获取详细配置和示例。
+
+library: "g2"
+version: "5.x"
+category: "compositions"
+tags:
+  - "timingKeyframe"
+  - "关键帧动画"
+  - "数据故事"
+  - "morphing"
+  - "composition"
+  - "动画组合"
+
+related:
+  - "g2-animation-keyframe"
+  - "g2-animation-intro"
+  - "g2-core-view-composition"
+
+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/composition/timing-keyframe"
+---
+
+## 核心概念
+
+`timingKeyframe` 是 composition 类型，每个 child 是一个"关键帧"视图。
+系统自动在相邻关键帧之间进行数据和图形的插值过渡动画。
+
+详细配置和示例请参见 [g2-animation-keyframe](./g2-animation-keyframe.md)。
+
+## 最小可运行示例
+
+```javascript
+import { Chart } from '@antv/g2';
+
+const data = [
+  { month: 'Jan', value: 83 },
+  { month: 'Feb', value: 60 },
+  { month: 'Mar', value: 95 },
+];
+
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'timingKeyframe',
+  duration: 1000,
+  iterationCount: 'infinite',
+  direction: 'alternate',
+  children: [
+    {
+      type: 'interval',
+      data,
+      encode: { x: 'month', y: 'value', color: 'month' },
+    },
+    {
+      type: 'line',
+      data,
+      encode: { x: 'month', y: 'value' },
+    },
+  ],
+});
+
+chart.render();
+```
+
+## 配置项速查
+
+```javascript
+chart.options({
+  type: 'timingKeyframe',
+  duration: 1000,                  // 关键帧间过渡时长（毫秒）
+  iterationCount: 1,               // 循环次数（'infinite' = 无限）
+  direction: 'normal',             // 'normal' | 'reverse' | 'alternate' | 'reverse-alternate'
+  easing: 'ease-in-out-sine',     // 缓动函数
+  children: [/* 各关键帧视图 */],
+});
+```