vccs 1.0.0-beta.2 → 1.0.0

package/README.md

@@ -76,6 +76,17 @@ export default defineConfig({
 })
 ```
 
+## Use vccs with an AI agent
+
+```sh
+npx skills add unovue/vue-charts      # add -g to install for every project
+```
+
+Then just ask for the chart — you run nothing yourself. Claude loads the skill when the request
+matches it, or you can invoke it explicitly with `/vccs-usage`:
+
+> add a card with weekly user retention by signup month
+
 ## Typed rows
 
 `defineChartComponents` binds your row type to the components you pick. A wrong `data-key` is

package/dist/es/cartesian/brush/Brush.mjs

@@ -55,8 +55,10 @@ var BrushView = /* @__PURE__ */ defineComponent({
 		const startIndex = computed(() => view.range?.startIndex ?? 0);
 		const endIndex = computed(() => view.range?.endIndex ?? Math.max(0, (chartData.value?.length ?? 0) - 1));
 		const calculatedY = computed(() => (y.value ?? 0) + (props.dy ?? 0));
+		let proposed;
 		function onChange(nextState) {
 			if (sameRange(nextState, view.range)) return;
+			proposed = nextState;
 			emit("update:range", nextState);
 			emit("change", nextState);
 			nextTick(restoreControlledPositions);
@@ -68,6 +70,8 @@ var BrushView = /* @__PURE__ */ defineComponent({
 		});
 		function restoreControlledPositions() {
 			if (!view.controlled()) return;
+			if (sameRange(view.range, proposed ?? null)) return;
+			proposed = void 0;
 			brushState.value.startX = brushState.value.scale?.(startIndex.value);
 			brushState.value.endX = brushState.value.scale?.(endIndex.value);
 		}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vccs",
   "type": "module",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0",
   "description": "Composable charting components for Vue 3 — an unofficial port of Recharts",
   "author": "rick-hup",
   "license": "MIT",
@@ -51,11 +51,15 @@
       ]
     }
   },
+  "bin": {
+    "vccs-usage": "./usage/vccs-usage.mjs"
+  },
   "files": [
     "./LICENSE",
     "./README.md",
     "./dist/**/*.d.ts",
-    "./dist/**/*.mjs"
+    "./dist/**/*.mjs",
+    "./usage"
   ],
   "peerDependencies": {
     "@nuxt/kit": "^4.0.0",

package/usage/catalog.json

@@ -0,0 +1,235 @@
+{
+  "schemaVersion": 1,
+  "guides": [
+    {
+      "id": "installation",
+      "title": "Installation and registration",
+      "description": "Install vccs in Vite or Nuxt 4, use explicit imports, auto-imports, or the Nuxt module.",
+      "category": "core",
+      "path": "guides/core/installation.md",
+      "components": [],
+      "useCases": ["Set up a new Vue or Nuxt chart", "Configure VccsResolver or vccs/nuxt"],
+      "keywords": ["install", "setup", "vite", "nuxt", "resolver", "auto-import", "安装", "自动导入"]
+    },
+    {
+      "id": "vue-api",
+      "title": "Vue API rules",
+      "description": "Use slots, events, Vue models, responsive sizing, data keys, and CSS theme variables correctly.",
+      "category": "core",
+      "path": "guides/core/vue-api.md",
+      "components": ["Tooltip", "Brush", "Legend"],
+      "useCases": ["Customize chart content", "Control active state", "Fix a Recharts-to-Vue API mismatch"],
+      "keywords": ["slots", "events", "v-model", "active-index", "brush", "tooltip", "responsive", "theme", "插槽", "事件", "主题"]
+    },
+    {
+      "id": "typed-rows",
+      "title": "Typed chart rows",
+      "description": "Make data-key and tooltip payload types follow the application's row type.",
+      "category": "core",
+      "path": "guides/core/typed-rows.md",
+      "components": [],
+      "useCases": ["Reject wrong data keys at compile time", "Type tooltip payloads"],
+      "keywords": ["typescript", "types", "generic", "defineChartComponents", "row", "类型", "类型安全"]
+    },
+    {
+      "id": "ssr-testing",
+      "title": "SSR and deterministic testing",
+      "description": "Render charts on the server and disable motion for stable SSR and geometry assertions.",
+      "category": "core",
+      "path": "guides/core/ssr-testing.md",
+      "components": [],
+      "useCases": ["Render charts in Nuxt SSR", "Write deterministic chart tests"],
+      "keywords": ["ssr", "server", "hydration", "test", "animation", "服务端渲染", "测试"]
+    },
+    {
+      "id": "area-chart",
+      "title": "AreaChart",
+      "description": "Show a filled trend, accumulated magnitude, or stacked total over an ordered axis.",
+      "category": "chart",
+      "path": "guides/charts/area-chart.md",
+      "components": ["AreaChart", "Area"],
+      "useCases": ["Show a filled trend over time", "Show stacked totals over an ordered axis", "用面积展示趋势或堆积总量"],
+      "keywords": ["area", "filled line", "stacked area", "trend", "time series", "面积图", "趋势", "堆积"]
+    },
+    {
+      "id": "bar-chart",
+      "title": "BarChart",
+      "description": "Compare categories with vertical or horizontal bars, including stacked and negative values.",
+      "category": "chart",
+      "path": "guides/charts/bar-chart.md",
+      "components": ["BarChart", "Bar"],
+      "useCases": ["Compare values across categories", "Rank categories or show a stacked composition", "用柱状图或条形图比较分类"],
+      "keywords": ["bar", "column", "comparison", "ranking", "stacked", "柱状图", "条形图", "对比", "排名"]
+    },
+    {
+      "id": "line-chart",
+      "title": "LineChart",
+      "description": "Show one or more trends over an ordered numeric or categorical axis.",
+      "category": "chart",
+      "path": "guides/charts/line-chart.md",
+      "components": ["LineChart", "Line"],
+      "useCases": ["Show a time series", "Compare trends across series", "用折线展示趋势"],
+      "keywords": ["line", "trend", "time series", "spark alternative", "折线图", "趋势", "时间序列"]
+    },
+    {
+      "id": "scatter-chart",
+      "title": "ScatterChart",
+      "description": "Show relationships between numeric variables with points or bubbles.",
+      "category": "chart",
+      "path": "guides/charts/scatter-chart.md",
+      "components": ["ScatterChart", "Scatter", "ZAxis"],
+      "useCases": ["Show correlation or distribution", "Encode a third numeric value as bubble size", "用散点展示相关性或分布"],
+      "keywords": ["scatter", "correlation", "distribution", "bubble", "散点图", "气泡图", "相关性"]
+    },
+    {
+      "id": "composed-chart",
+      "title": "ComposedChart",
+      "description": "Combine Bar, Line, Area, and Scatter series on shared Cartesian axes.",
+      "category": "chart",
+      "path": "guides/charts/composed-chart.md",
+      "components": ["ComposedChart", "Bar", "Line", "Area", "Scatter"],
+      "useCases": ["Compare actual bars with a target line", "Mix series types on one chart", "在同一坐标系混合柱状和折线"],
+      "keywords": ["composed", "mixed", "combo", "bar and line", "组合图", "混合图"]
+    },
+    {
+      "id": "funnel-chart",
+      "title": "FunnelChart",
+      "description": "Show values and drop-off across ordered conversion stages.",
+      "category": "chart",
+      "path": "guides/charts/funnel-chart.md",
+      "components": ["FunnelChart", "Funnel"],
+      "useCases": ["Show conversion across stages", "Expose drop-off in a process", "展示阶段转化和流失"],
+      "keywords": ["funnel", "conversion", "drop-off", "stages", "漏斗图", "转化率"]
+    },
+    {
+      "id": "pie-chart",
+      "title": "PieChart",
+      "description": "Show a small number of part-to-whole proportions as a pie or donut.",
+      "category": "chart",
+      "path": "guides/charts/pie-chart.md",
+      "components": ["PieChart", "Pie", "Cell"],
+      "useCases": ["Show proportions of a total", "Build a donut chart", "展示少量分类的占比"],
+      "keywords": ["pie", "donut", "proportion", "part-to-whole", "饼图", "环形图", "占比"]
+    },
+    {
+      "id": "radar-chart",
+      "title": "RadarChart",
+      "description": "Compare multivariate profiles across a shared set of dimensions.",
+      "category": "chart",
+      "path": "guides/charts/radar-chart.md",
+      "components": ["RadarChart", "Radar", "PolarAngleAxis", "PolarGrid"],
+      "useCases": ["Compare scores across dimensions", "Show a multivariate profile", "比较多维评分"],
+      "keywords": ["radar", "spider", "multivariate", "profile", "雷达图", "多维"]
+    },
+    {
+      "id": "radial-bar-chart",
+      "title": "RadialBarChart",
+      "description": "Show progress or category values as concentric or stacked radial bars.",
+      "category": "chart",
+      "path": "guides/charts/radial-bar-chart.md",
+      "components": ["RadialBarChart", "RadialBar"],
+      "useCases": ["Show progress toward a goal", "Compare values on polar tracks", "展示环形进度或径向分类值"],
+      "keywords": ["radial bar", "progress", "gauge", "polar bar", "径向条形图", "进度", "仪表盘"]
+    },
+    {
+      "id": "bar-list",
+      "title": "BarList",
+      "description": "Render a lightweight plain-HTML ranked list with inline value bars.",
+      "category": "chart",
+      "path": "guides/charts/bar-list.md",
+      "components": ["BarList"],
+      "useCases": ["Build a compact ranking list", "Show labeled values without SVG axes", "用 HTML 列表展示排行"],
+      "keywords": ["bar list", "ranking", "html", "leaderboard", "条形列表", "排行榜"]
+    },
+    {
+      "id": "sparkline",
+      "title": "Sparkline",
+      "description": "Place a tiny inline trend in a table, KPI tile, or dense dashboard row.",
+      "category": "chart",
+      "path": "guides/charts/sparkline.md",
+      "components": ["Sparkline"],
+      "useCases": ["Show a compact trend without axes", "Add a trend to a KPI or table row", "在指标卡或表格中展示迷你趋势"],
+      "keywords": ["sparkline", "mini line", "kpi", "inline trend", "火花线", "迷你趋势"]
+    },
+    {
+      "id": "tracker",
+      "title": "Tracker",
+      "description": "Show a compact sequence of discrete activity or status cells.",
+      "category": "chart",
+      "path": "guides/charts/tracker.md",
+      "components": ["Tracker"],
+      "useCases": ["Show service or activity status over a sequence", "Render compact status cells", "展示一组状态或活动点"],
+      "keywords": ["tracker", "status", "activity", "cells", "状态", "活动点", "追踪"]
+    },
+    {
+      "id": "heatmap",
+      "title": "Heatmap",
+      "description": "Show magnitude or density across two categorical dimensions.",
+      "category": "chart",
+      "path": "guides/charts/heatmap.md",
+      "components": ["Heatmap"],
+      "useCases": ["Show a matrix of values", "Find concentration across two categories", "展示两个分类维度的密度或强度"],
+      "keywords": ["heatmap", "matrix", "density", "intensity", "热力图", "矩阵", "密度"]
+    },
+    {
+      "id": "calendar-heatmap",
+      "title": "CalendarHeatmap",
+      "description": "Show daily activity or intensity on a calendar.",
+      "category": "chart",
+      "path": "guides/charts/calendar-heatmap.md",
+      "components": ["CalendarHeatmap"],
+      "useCases": ["Show daily activity over weeks or months", "Build a contribution calendar", "展示每日活动或贡献日历"],
+      "keywords": ["calendar heatmap", "daily", "contribution", "activity calendar", "日历热力图", "贡献图"]
+    },
+    {
+      "id": "cohort-chart",
+      "title": "CohortChart",
+      "description": "Show retention or another metric by cohort and elapsed period.",
+      "category": "chart",
+      "path": "guides/charts/cohort-chart.md",
+      "components": ["CohortChart"],
+      "useCases": ["Analyze retention by signup cohort", "Compare behavior across elapsed periods", "分析分群留存"],
+      "keywords": ["cohort", "retention", "signup", "period", "队列图", "留存", "分群"]
+    },
+    {
+      "id": "journey-sankey",
+      "title": "JourneySankey",
+      "description": "Show how entities move through ordered journey steps and where they drop off.",
+      "category": "chart",
+      "path": "guides/charts/journey-sankey.md",
+      "components": ["JourneySankey"],
+      "useCases": ["Visualize a user journey", "Compare paths through ordered steps", "展示用户旅程和路径流失"],
+      "keywords": ["journey", "path", "conversion", "sankey", "用户旅程", "路径", "桑基图"]
+    },
+    {
+      "id": "sankey",
+      "title": "Sankey",
+      "description": "Show weighted flows between arbitrary source and target nodes.",
+      "category": "chart",
+      "path": "guides/charts/sankey.md",
+      "components": ["Sankey"],
+      "useCases": ["Show transfers or flows between nodes", "Visualize weighted relationships in a network", "展示节点之间的加权流动"],
+      "keywords": ["sankey", "flow", "nodes", "links", "桑基图", "流量", "流向"]
+    },
+    {
+      "id": "treemap",
+      "title": "Treemap",
+      "description": "Show hierarchical part-to-whole values as nested rectangles.",
+      "category": "chart",
+      "path": "guides/charts/treemap.md",
+      "components": ["Treemap"],
+      "useCases": ["Show hierarchy and magnitude together", "Compare branches of a whole", "用嵌套矩形展示层级和占比"],
+      "keywords": ["treemap", "hierarchy", "nested rectangles", "矩形树图", "层级", "占比"]
+    },
+    {
+      "id": "sunburst-chart",
+      "title": "SunburstChart",
+      "description": "Show hierarchical part-to-whole values as concentric radial rings.",
+      "category": "chart",
+      "path": "guides/charts/sunburst-chart.md",
+      "components": ["SunburstChart"],
+      "useCases": ["Show hierarchy as radial rings", "Explore nested proportions", "用同心环展示层级和占比"],
+      "keywords": ["sunburst", "hierarchy", "radial rings", "旭日图", "层级", "环形"]
+    }
+  ]
+}

package/usage/guides/charts/area-chart.md

@@ -0,0 +1,56 @@
+# AreaChart
+
+Use `AreaChart` for a filled trend or a stacked total over an ordered axis. Use `LineChart` when the fill would overemphasize magnitude; use `BarChart` for discrete category comparisons.
+
+## Data shape
+
+- `data` is an array of flat rows on the chart root.
+- `XAxis data-key` names the ordered category or time value.
+- Each `Area data-key` selects one numeric series from the same row.
+- Use one `Area` per series and set `name` when the legend or tooltip needs a different label.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Area, AreaChart, CartesianGrid, Tooltip, XAxis, YAxis } from 'vccs'
+
+const data = [
+  { month: 'Jan', visitors: 186 },
+  { month: 'Feb', visitors: 305 },
+  { month: 'Mar', visitors: 237 },
+]
+</script>
+
+<template>
+  <AreaChart
+    :data="data"
+    :height="300"
+  >
+    <CartesianGrid />
+    <XAxis data-key="month" />
+    <YAxis />
+    <Tooltip :cursor="false" />
+    <Area
+      type="monotone"
+      data-key="visitors"
+      stroke="#f97316"
+      fill="#f97316"
+      :fill-opacity="0.3"
+    />
+  </AreaChart>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Keep all series on the shared root `data` array; do not put a separate array on each `Area`.
+- Give areas the same `stack-id` to stack them; omit it when the areas should remain independent.
+- Use `connect-nulls` only when a gap should be bridged; otherwise missing values stay visible as gaps.
+- Retrieve `composed-chart` when bars, lines, or scatter points must share the same axes.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `line-chart`, `bar-chart`, `composed-chart`.

package/usage/guides/charts/bar-chart.md

@@ -0,0 +1,60 @@
+# BarChart
+
+Use `BarChart` to compare or rank values across categories. Use `BarList` for a compact HTML ranking without axes; use `LineChart` when the main point is a continuous trend.
+
+## Data shape
+
+- `data` is an array of flat rows on the chart root.
+- `XAxis data-key` names the category for vertical bars.
+- Each `Bar data-key` selects one numeric series from the same row.
+- Use one `Bar` per series and set `name` when the legend or tooltip needs a different label.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Bar, BarChart, CartesianGrid, Legend, Tooltip, XAxis, YAxis } from 'vccs'
+
+const data = [
+  { month: 'Jan', desktop: 186, mobile: 80 },
+  { month: 'Feb', desktop: 305, mobile: 120 },
+  { month: 'Mar', desktop: 237, mobile: 160 },
+]
+</script>
+
+<template>
+  <BarChart
+    :data="data"
+    :height="300"
+  >
+    <CartesianGrid />
+    <XAxis data-key="month" />
+    <YAxis />
+    <Tooltip :cursor="false" />
+    <Legend />
+    <Bar
+      data-key="desktop"
+      name="Desktop"
+      fill="#f97316"
+    />
+    <Bar
+      data-key="mobile"
+      name="Mobile"
+      fill="#14b8a6"
+    />
+  </BarChart>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Keep grouped or stacked series on the shared root `data` array, with one `Bar` per numeric field.
+- Give bars the same `stack-id` to stack them; for stacks containing negative values, set `stack-offset="sign"` on `BarChart`.
+- Use `layout="vertical"` for horizontal bars, with a numeric `XAxis` and a categorical `YAxis` carrying the category `data-key`.
+- Use `bar-size` for a fixed bar width or `max-bar-size` for an upper limit.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `bar-list`, `line-chart`, `composed-chart`.

package/usage/guides/charts/bar-list.md

@@ -0,0 +1,46 @@
+# BarList
+
+Use `BarList` for a compact ranked list with labels and inline magnitude bars. It is plain HTML, not an SVG chart; use `BarChart` when you need axes, stacked values, or multiple series.
+
+## Data shape
+
+- `data` contains one row per item.
+- `name-key` selects the label and row identity; it defaults to `name`.
+- `data-key` selects the numeric value; it defaults to `value`.
+- Add `href-key` when a row field should turn its label into a link.
+- Bar length is the value divided by the largest value, not the share of the total.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { BarList } from 'vccs'
+
+const data = [
+  { name: '/', value: 1240, url: '/' },
+  { name: '/pricing', value: 820, url: '/pricing' },
+  { name: '/docs', value: 610, url: '/docs' },
+  { name: '/blog', value: 330, url: '/blog' },
+]
+</script>
+
+<template>
+  <BarList
+    :data="data"
+    href-key="url"
+    color="#f97316"
+  />
+</template>
+```
+
+## Chart-specific rules
+
+- Rows sort by descending value by default; use `sort="none"` to preserve input order.
+- Keep `name-key` stable across updates so a row keeps its identity when its rank changes.
+- Use `value-formatter` for display text and `locale` for the default number format.
+- Customize labels or values with the `#name` and `#value` slots, not function-valued render props.
+- Adjust the HTML rows with `row-height` and `gap`; do not add Cartesian axes or series children.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `bar-chart`, `tracker`.

package/usage/guides/charts/calendar-heatmap.md

@@ -0,0 +1,55 @@
+# CalendarHeatmap
+
+Use `CalendarHeatmap` for daily activity arranged into weekdays and weeks, such as contributions or practice minutes. Use `Heatmap` for arbitrary categories and `Sparkline` when only the overall trend matters.
+
+## Data shape
+
+- `data` is a flat array of daily rows.
+- `date-key` defaults to `date` and accepts a valid `YYYY-MM-DD` string or a `Date` object.
+- `data-key` defaults to `value` and selects the numeric intensity.
+- Rows for the same day are summed; invalid dates are skipped.
+- Days without a source row are empty cells; do not pad the range with zero rows.
+- Set `start` and `end` for an explicit range. Otherwise the range ends on the latest data date and covers about 52 weeks.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { CalendarHeatmap, Tooltip } from 'vccs'
+
+const data = [
+  { date: '2025-01-02', value: 3 },
+  { date: '2025-01-04', value: 5 },
+  { date: '2025-01-07', value: 2 },
+  { date: '2025-01-10', value: 8 },
+  { date: '2025-01-13', value: 4 },
+  { date: '2025-01-16', value: 1 },
+  { date: '2025-01-20', value: 9 },
+  { date: '2025-01-24', value: 6 },
+]
+</script>
+
+<template>
+  <CalendarHeatmap
+    :data="data"
+    start="2025-01-01"
+    end="2025-01-31"
+    :week-start="1"
+    color="#14b8a6"
+  >
+    <Tooltip :cursor="false" />
+  </CalendarHeatmap>
+</template>
+```
+
+## Chart-specific rules
+
+- Prefer `YYYY-MM-DD` strings for unambiguous calendar days; a `Date` uses its local calendar date.
+- Explicit `start` and `end` keep a fixed example or server-rendered range independent of the current day.
+- `colors` is the complete scale from empty to full, so include the empty color as its first entry.
+- Use `:week-start="0"` for Sunday or `:week-start="1"` for Monday; `max` controls the value at full intensity.
+- Tooltip and cell-event payloads are `CalendarDay` objects with `date`, `value`, `level`, and source `rows`.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `heatmap`, `tracker`, `sparkline`.

package/usage/guides/charts/cohort-chart.md

@@ -0,0 +1,47 @@
+# CohortChart
+
+Use `CohortChart` for retention or another count by acquisition cohort and elapsed period. Use `Heatmap` for an arbitrary matrix and `LineChart` for one overall trend without cohort breakdown.
+
+## Data shape
+
+- `data` contains one row per cohort, ordered oldest first.
+- `cohort-key` selects the cohort name and defaults to `cohort`.
+- `values-key` selects a numeric array and defaults to `values`.
+- `values[0]` is the initial cohort size; `values[n]` is the count still active at period `n`.
+- Supply raw counts even in the default percentage mode. Omit periods a cohort has not reached instead of padding them with zero.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { CohortChart, Tooltip } from 'vccs'
+
+const data = [
+  { cohort: 'Jan', values: [1200, 610, 480, 410] },
+  { cohort: 'Feb', values: [940, 470, 370] },
+  { cohort: 'Mar', values: [1180, 650] },
+  { cohort: 'Apr', values: [860] },
+]
+</script>
+
+<template>
+  <CohortChart
+    :data="data"
+    color="#f97316"
+  >
+    <Tooltip :cursor="false" />
+  </CohortChart>
+</template>
+```
+
+## Chart-specific rules
+
+- The default `mode="percent"` calculates each cell from the raw count divided by `values[0]`; use `mode="count"` for raw counts.
+- Keep `values[0]` positive. A non-positive or invalid initial size cannot produce percentage cells.
+- Different cohorts may have different array lengths; shorter arrays leave unelapsed periods blank and form the expected triangle.
+- Use `period-formatter` for column headings. `value-formatter` receives the calculated percentage or the raw count according to `mode`.
+- Tooltip and cell-event payloads include the cohort source `row`, contributing `rows`, and elapsed `period`.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `heatmap`, `line-chart`.

package/usage/guides/charts/composed-chart.md

@@ -0,0 +1,70 @@
+# ComposedChart
+
+Use `ComposedChart` when different series need different marks on shared Cartesian axes. Use a specific chart root when every series has the same mark; do not combine incomparable units on one value axis.
+
+## Data shape
+
+- `data` is an array of flat rows on the chart root.
+- `XAxis data-key` names the shared ordered category or time value.
+- Each `Area`, `Bar`, or `Line` uses `data-key` to select a numeric field from the same row.
+- Set `name` on each series when the legend or tooltip needs a label different from the key.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Area, Bar, CartesianGrid, ComposedChart, Legend, Line, Tooltip, XAxis, YAxis } from 'vccs'
+
+const data = [
+  { month: 'Jan', desktop: 186, mobile: 80, total: 266 },
+  { month: 'Feb', desktop: 305, mobile: 120, total: 425 },
+  { month: 'Mar', desktop: 237, mobile: 160, total: 397 },
+]
+</script>
+
+<template>
+  <ComposedChart
+    :data="data"
+    :height="300"
+  >
+    <CartesianGrid />
+    <XAxis data-key="month" />
+    <YAxis />
+    <Tooltip :cursor="false" />
+    <Legend />
+    <Area
+      type="monotone"
+      data-key="total"
+      name="Total"
+      stroke="#f97316"
+      fill="#f97316"
+      :fill-opacity="0.3"
+    />
+    <Bar
+      data-key="desktop"
+      name="Desktop"
+      fill="#14b8a6"
+      :bar-size="20"
+    />
+    <Line
+      type="monotone"
+      data-key="mobile"
+      name="Mobile"
+      stroke="#f59e0b"
+    />
+  </ComposedChart>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Combine `Area`, `Bar`, `Line`, and `Scatter` children; retrieve their chart guides for series-specific props.
+- Keep `Area`, `Bar`, and `Line` series on the shared root `data` array; retrieve `scatter-chart` for scatter data and numeric axes.
+- Series paint in template order, so a later series can cover an earlier one.
+- The tooltip follows the category axis; add `Legend` when multiple series need visible labels.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `area-chart`, `bar-chart`, `line-chart`, `scatter-chart`.