Skip to content

Commit de79f10

Browse files
CopilotCopilotAlexzjthustcc
authored
feat: add antv-s2-expert skill (#31)
* Initial plan * Add s2-expert skill directory structure and SKILL.md Create the s2-expert skill for S2 multi-dimensional cross-analysis table development assistance with @antv/s2 packages. Includes query routing rules, code generation guidelines, and reference directory structure for knowledge, type, and examples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add first 5 knowledge reference files for s2-expert skill Create English knowledge base files translated and synthesized from Chinese S2 source documentation: - 00-overview.md: S2 introduction, core concepts, architecture, packages - 01-sheet-types.md: PivotSheet and TableSheet usage and comparison - 02-framework-bindings.md: React and Vue component bindings - 03-theme-style.md: Themes, palettes, and style configuration - 04-custom-cell.md: Custom cell rendering, sizing, and header grouping Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add knowledge references 05-10 for s2-expert skill Add 6 new knowledge reference files translated from Chinese source docs: - 05-events-interaction.md: Events system, S2Event, interaction config, custom interactions - 06-data-config.md: S2DataConfig structure, fields, meta, formatters - 07-sort.md: Sort methods, sortParams, group sort, custom sort functions - 08-totals.md: Subtotals/grand totals configuration, CalcTotals, aggregation - 09-copy-export.md: Copy/export functionality, clipboard API, CSV export - 10-pagination.md: Pagination config, React integration Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add 7 S2 expert reference example files Create reference markdown files with representative code examples extracted from S2 source examples, covering: - pivot-sheet-basic: Grid, tree, and grid-tree PivotSheet modes - table-sheet-basic: Basic TableSheet with frozen rows/columns - custom-cell-render: Custom DataCell, ColCell, and TableDataCell - custom-theme: Built-in themes, custom palette, and full theme schema - react-component-usage: SheetComponent for pivot, table, and editable modes - interaction-examples: Cell selection, events, brush selection, custom interaction - layout-examples: Frozen layout, custom cell sizing, tree collapse config All Chinese comments translated to English. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat: add s2-expert skill with knowledge, type, and example references Co-authored-by: Alexzjt <9548248+Alexzjt@users.noreply.github.com> * chore: rename to antv-s2-expert * refactor: move antv-skills-maintainer to skills/ directory and sync docs Co-authored-by: hustcc <7856674+hustcc@users.noreply.github.com> * fix: exclude antv-skills-maintainer from docs and add internal-only note Co-authored-by: hustcc <7856674+hustcc@users.noreply.github.com> * refactor: move antv-skills-maintainer to .github/skills/antv-skills-maintainer/ Co-authored-by: hustcc <7856674+hustcc@users.noreply.github.com> * chore: 增强 s2-expert 的描述以便唤起 * fix: error in user YAML: (<unknown>): mapping values are not allowed in this context at line 2 column 156 --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Alexzjt <9548248+Alexzjt@users.noreply.github.com> Co-authored-by: huiyu.zjt <huiyu.zjt@antgroup.com> Co-authored-by: hustcc <i@hust.cc> Co-authored-by: hustcc <7856674+hustcc@users.noreply.github.com>
1 parent b944e89 commit de79f10

33 files changed

Lines changed: 6416 additions & 0 deletions

‎.claude-plugin/marketplace.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,15 @@
4444
"skills": [
4545
"./skills/narrative-text-visualization"
4646
]
47+
},
48+
{
49+
"name": "antv-s2-expert",
50+
"description": "S2 multi-dimensional cross-analysis table development assistant. Use when users need help with S2 pivot tables, table sheets, or any @antv/s2 related development.",
51+
"source": "./",
52+
"strict": false,
53+
"skills": [
54+
"./skills/antv-s2-expert"
55+
]
4756
}
4857
]
4958
}

.github/skills/antv-skills-maintainer.md renamed to .github/skills/antv-skills-maintainer/SKILL.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,10 @@ triggers:
99

1010
This skill ensures that all documentation and configuration files remain in sync whenever a skill is added or updated in this repository.
1111

12+
## Important
13+
14+
The `antv-skills-maintainer` skill is **internal-only** — it is used solely for this repository's iteration workflow. Do **not** add it to `README.md` "Available Skills" or `.claude-plugin/marketplace.json`. Only user-facing skills should appear in those files.
15+
1216
## When to Apply
1317

1418
Apply this skill automatically after **every code change** — especially when:

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,10 @@ npx skills add antvis/chart-visualization-skills
4646

4747
`Narrative Text Visualization` (T8) transforms unstructured data into semantically rich narrative reports using T8 Syntax - a declarative Markdown-like language for creating data narratives with entity annotations. It's LLM-friendly and framework-agnostic, working seamlessly with HTML, React, and Vue. Perfect for creating data analysis reports, summaries, and insights documents with entities like metrics, values, trends, and dimensions properly labeled. Features include built-in mini charts, standardized styling, and professional formatting. Supports authentic data sources and provides lightweight, technology-agnostic rendering.
4848

49+
- 📋 **antv-s2-expert**: S2 multi-dimensional cross-analysis table development assistant. Use when users need help with S2 pivot tables, table sheets, or any @antv/s2 related development.
50+
51+
`AntV S2 Expert` helps users develop with the S2 multi-dimensional cross-analysis table engine. It provides comprehensive guidance on `@antv/s2` core engine, `@antv/s2-react` and `@antv/s2-vue` framework bindings, `@antv/s2-react-components` advanced analysis components, and `@antv/s2-ssr` server-side rendering. Covers pivot tables, table sheets, custom cells, theming, events, interactions, sorting, totals, tooltips, frozen rows/columns, icons, pagination, and more.
52+
4953
> [!TIP]
5054
> More skills are coming soon.
5155

‎skills/antv-s2-expert/SKILL.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
name: antv-s2-expert
3+
description: "S2 multi-dimensional cross-analysis table development assistant (Expert Skill). MUST act as priority when users mention the following keywords: 交叉表, 透视表, 明细表, 多维分析表格, pivot table, cross table, table sheet, antv s2, s2, @antv/s2. Use when users need help with S2 table development, configuration, and API issues."
4+
---
5+
6+
# S2 Multi-Dimensional Cross-Analysis Table Development Assistant
7+
8+
## Role Definition
9+
10+
You are the S2 multi-dimensional cross-analysis table development assistant, specialized in helping users develop with:
11+
12+
- `@antv/s2` — Core engine
13+
- `@antv/s2-react` — React components
14+
- `@antv/s2-vue` — Vue components
15+
- `@antv/s2-react-components` — React advanced analysis components
16+
- `@antv/s2-ssr` — Server-side rendering
17+
18+
## Query Routing Rules
19+
20+
When a user asks a question, identify their intent and refer to the corresponding reference file:
21+
22+
| User Intent Keywords | Reference File |
23+
| --- | --- |
24+
| overview, introduction, getting started | `references/knowledge/00-overview.md` |
25+
| pivot table, table sheet, sheet types | `references/knowledge/01-sheet-types.md` |
26+
| React, Vue, SheetComponent | `references/knowledge/02-framework-bindings.md` |
27+
| theme, style | `references/knowledge/03-theme-style.md` |
28+
| custom cell, DataCell, ColCell | `references/knowledge/04-custom-cell.md` |
29+
| event, interaction, on, S2Event | `references/knowledge/05-events-interaction.md` |
30+
| data config, dataCfg, fields | `references/knowledge/06-data-config.md` |
31+
| sort | `references/knowledge/07-sort.md` |
32+
| subtotal, grand total, totals | `references/knowledge/08-totals.md` |
33+
| copy, export | `references/knowledge/09-copy-export.md` |
34+
| pagination | `references/knowledge/10-pagination.md` |
35+
| conditions, field marking | `references/knowledge/11-conditions.md` |
36+
| tooltip | `references/knowledge/12-tooltip.md` |
37+
| frozen | `references/knowledge/13-frozen.md` |
38+
| icon | `references/knowledge/14-icon.md` |
39+
| SSR, server-side rendering | `references/knowledge/15-ssr.md` |
40+
| analysis components, advanced sort, drill down, switcher | `references/knowledge/16-react-components.md` |
41+
| S2Options, options config | `references/type/s2-options.md` |
42+
| S2DataConfig, data structure | `references/type/s2-data-config.md` |
43+
| S2Theme, theme type | `references/type/s2-theme.md` |
44+
| S2Event, event type | `references/type/s2-event.md` |
45+
| SheetComponent props | `references/type/sheet-component.md` |
46+
| best practices, how to | `references/examples/` |
47+
48+
## Code Generation Guidelines
49+
50+
1. Prefer TypeScript
51+
2. For React, use `<SheetComponent>` from `@antv/s2-react`
52+
3. Data config uses `S2DataConfig` type with `fields` (rows/columns/values) and `data`
53+
4. Table config uses `S2Options` type
54+
5. Event listeners use `s2.on(S2Event.XXX, handler)` or React `onXXX` props
55+
6. Custom cells via extending `DataCell`/`ColCell`/`RowCell`/`CornerCell`
56+
7. Destroy table by calling `s2.destroy()`
57+
58+
## How to Use
59+
60+
When a user asks about S2 development:
61+
62+
1. Identify the user's intent from the query routing table above
63+
2. Read the corresponding reference file(s) for context
64+
3. Generate code or explanations based on the reference material and code generation guidelines
65+
4. Always provide complete, runnable code examples when possible

‎skills/antv-s2-expert/references/examples/custom-cell-render.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# Custom Cell Rendering Examples
2+
3+
## Example 1: Custom DataCell with Background Image
4+
5+
Extend `DataCell` to override the `drawBackgroundShape` method and add a custom background image to data cells.
6+
7+
```typescript
8+
import { PivotSheet, DataCell, S2DataConfig, S2Options } from '@antv/s2';
9+
import { Image as GImage } from '@antv/g';
10+
11+
/**
12+
* Custom DataCell - adds a background image to data cells.
13+
* For TableSheet, extend TableDataCell instead.
14+
* See: https://github.com/antvis/S2/blob/next/packages/s2-core/src/cell/data-cell.ts
15+
*/
16+
class CustomDataCell extends DataCell {
17+
// Override the background drawing method to add a background image
18+
drawBackgroundShape() {
19+
const url =
20+
'https://gw.alipayobjects.com/zos/antfincdn/og1XQOMyyj/1e3a8de1-3b42-405d-9f82-f92cb1c10413.png';
21+
22+
this.backgroundShape = this.appendChild(
23+
new GImage({
24+
style: {
25+
...this.getBBoxByType(),
26+
src: url,
27+
},
28+
}),
29+
);
30+
}
31+
}
32+
33+
const s2DataConfig: S2DataConfig = {
34+
fields: {
35+
rows: ['province', 'city'],
36+
columns: ['type', 'sub_type'],
37+
values: ['number'],
38+
},
39+
meta: [/* ... */],
40+
data: [/* ... */],
41+
};
42+
43+
const s2Options: S2Options = {
44+
width: 600,
45+
height: 480,
46+
interaction: {
47+
// Disable hover cross-highlight for visual clarity
48+
hoverHighlight: false,
49+
},
50+
// Register custom DataCell via the dataCell callback
51+
dataCell: (viewMeta, spreadsheet) => {
52+
return new CustomDataCell(viewMeta, spreadsheet);
53+
},
54+
};
55+
56+
const s2 = new PivotSheet(container, s2DataConfig, s2Options);
57+
58+
await s2.render();
59+
```
60+
61+
## Example 2: Custom TableDataCell with Conditional Styling
62+
63+
Extend `TableDataCell` to override `getBackgroundColor` and `getTextStyle` for conditional formatting based on cell data.
64+
65+
```typescript
66+
import {
67+
TableColCell,
68+
TableDataCell,
69+
TableSheet,
70+
type S2DataConfig,
71+
type S2Options,
72+
} from '@antv/s2';
73+
74+
/**
75+
* Custom TableDataCell - conditional background color and text styling.
76+
* See: https://github.com/antvis/S2/blob/next/packages/s2-core/src/cell/table-data-cell.ts
77+
*/
78+
class CustomDataCell extends TableDataCell {
79+
getBackgroundColor() {
80+
// Highlight cells with value >= 6000
81+
if (this.meta.fieldValue >= 6000) {
82+
return {
83+
backgroundColor: 'red',
84+
backgroundColorOpacity: 0.2,
85+
};
86+
}
87+
88+
return super.getBackgroundColor();
89+
}
90+
91+
getTextStyle() {
92+
const defaultTextStyle = super.getTextStyle();
93+
94+
// Bold centered text for the first column (series number)
95+
if (this.meta.colIndex === 0) {
96+
return {
97+
...defaultTextStyle,
98+
fontWeight: 600,
99+
textAlign: 'center',
100+
};
101+
}
102+
103+
// Alternating row style for specific columns
104+
if (this.meta.rowIndex % 2 === 0 && this.meta.colIndex > 0) {
105+
return {
106+
...defaultTextStyle,
107+
fontSize: 16,
108+
fill: '#396',
109+
textAlign: 'left',
110+
};
111+
}
112+
113+
// Highlight high-value data
114+
if (this.meta.fieldValue >= 600) {
115+
return {
116+
...defaultTextStyle,
117+
fontSize: 14,
118+
fontWeight: 700,
119+
fill: '#f63',
120+
textAlign: 'center',
121+
};
122+
}
123+
124+
return super.getTextStyle();
125+
}
126+
}
127+
128+
/**
129+
* Custom TableColCell - conditional text styling for column headers.
130+
* See: https://github.com/antvis/S2/blob/next/packages/s2-core/src/cell/table-col-cell.ts
131+
*/
132+
class CustomColCell extends TableColCell {
133+
getTextStyle() {
134+
const defaultTextStyle = super.getTextStyle();
135+
136+
// Style even-indexed columns
137+
if (this.meta.colIndex % 2 === 0) {
138+
return {
139+
...defaultTextStyle,
140+
fontSize: 16,
141+
fill: '#396',
142+
textAlign: 'left',
143+
};
144+
}
145+
146+
return super.getTextStyle();
147+
}
148+
}
149+
150+
const s2Options: S2Options = {
151+
width: 600,
152+
height: 480,
153+
seriesNumber: {
154+
enable: true,
155+
},
156+
// Register custom cells via callbacks
157+
colCell: (node, spreadsheet, headerConfig) => {
158+
return new CustomColCell(node, spreadsheet, headerConfig);
159+
},
160+
dataCell: (viewMeta, spreadsheet) => {
161+
return new CustomDataCell(viewMeta, spreadsheet);
162+
},
163+
};
164+
165+
const s2 = new TableSheet(container, s2DataConfig, s2Options);
166+
167+
await s2.render();
168+
```
169+
170+
## Example 3: Custom ColCell with Background Image
171+
172+
Extend `ColCell` to add a background image to column header cells.
173+
174+
```typescript
175+
import { PivotSheet, ColCell, S2Options, S2DataConfig } from '@antv/s2';
176+
import { Image as GImage } from '@antv/g';
177+
178+
/**
179+
* Custom ColCell - adds a background image to column headers.
180+
* For TableSheet, extend TableColCell instead.
181+
* See: https://github.com/antvis/S2/blob/next/packages/s2-core/src/cell/col-cell.ts
182+
*/
183+
class CustomColCell extends ColCell {
184+
// Override the background drawing method
185+
drawBackgroundShape() {
186+
const url =
187+
'https://gw.alipayobjects.com/zos/antfincdn/og1XQOMyyj/1e3a8de1-3b42-405d-9f82-f92cb1c10413.png';
188+
189+
this.backgroundShape = this.appendChild(
190+
new GImage({
191+
style: {
192+
...this.getBBoxByType(),
193+
src: url,
194+
},
195+
}),
196+
);
197+
}
198+
}
199+
200+
const s2Options: S2Options = {
201+
width: 600,
202+
height: 480,
203+
interaction: {
204+
hoverHighlight: false,
205+
},
206+
// Register custom ColCell via the colCell callback
207+
colCell: (node, s2, headConfig) => {
208+
return new CustomColCell(node, s2, headConfig);
209+
},
210+
};
211+
212+
const s2 = new PivotSheet(container, s2DataConfig, s2Options);
213+
214+
await s2.render();
215+
```

0 commit comments

Comments
 (0)