vccs 1.0.0-beta.1 → 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/bar/components/BarRectangles.mjs

@@ -148,7 +148,7 @@ var BarRectangles = /* @__PURE__ */ defineComponent({
 				emit("mouseenter", bar, index, event);
 			},
 			mouseleave: ({ bar, index }, _position, event) => {
-				tooltip.clear("hover");
+				tooltip.clear("hover", "item");
 				emit("mouseleave", bar, index, event);
 			}
 		});

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/dist/es/cartesian/funnel/Funnel.mjs

@@ -156,7 +156,7 @@ var FunnelView = /* @__PURE__ */ defineComponent({
 			});
 		}
 		function handleTrapezoidLeave() {
-			tooltip.clear("hover");
+			tooltip.clear("hover", "item");
 		}
 		return () => {
 			if (props.hide) return null;

package/dist/es/cartesian/scatter/Scatter.mjs

@@ -125,7 +125,7 @@ var ScatterView = /* @__PURE__ */ defineComponent({
 			});
 		};
 		const onMouseLeaveSymbol = () => {
-			tooltip.clear("hover");
+			tooltip.clear("hover", "item");
 		};
 		let symbolData = [];
 		const listeners = delegateItemEvents((index) => symbolData[index], {

package/dist/es/chart/CellGridLayer.mjs

@@ -203,7 +203,7 @@ var CellGridLayer = /* @__PURE__ */ defineComponent({
 				coordinate: void 0,
 				active: false
 			});
-			else tooltip.clear("hover");
+			else tooltip.clear("hover", "item");
 		}
 		function onEnter(cell, index, event) {
 			keyboard.value = false;

package/dist/es/chart/JourneySankey.mjs

@@ -369,7 +369,7 @@ function useJourneySankey(props, slots, emit) {
 	}
 	function leave() {
 		hover.value = void 0;
-		tooltip.clear("hover");
+		tooltip.clear("hover", "item");
 	}
 	function leaveNode(node, event) {
 		leave();

package/dist/es/chart/Sankey.mjs

@@ -292,11 +292,11 @@ function useSankey(props, slots, emit) {
 		emit("link-mouseenter", link, index, e);
 	}
 	function handleNodeMouseLeave(node, index, e) {
-		tooltip.clear("hover");
+		tooltip.clear("hover", "item");
 		emit("node-mouseleave", node, index, e);
 	}
 	function handleLinkMouseLeave(link, index, e) {
-		tooltip.clear("hover");
+		tooltip.clear("hover", "item");
 		emit("link-mouseleave", link, index, e);
 	}
 	function handleNodeClick(node, index, e) {

package/dist/es/chart/Sparkline.mjs

@@ -247,7 +247,7 @@ function useSparkline(props, emit) {
 	function setActive(index, keyboard = false) {
 		const point = index === null ? void 0 : points.value[index];
 		if (!point && !keyboard) {
-			tooltip.clear("hover");
+			tooltip.clear("hover", "item");
 			return;
 		}
 		const action = {

package/dist/es/chart/SunburstChart.mjs

@@ -201,7 +201,7 @@ function useSunburst(props, slots, emit) {
 		});
 	}
 	function handleMouseLeave(node, e) {
-		tooltip.clear("hover");
+		tooltip.clear("hover", "item");
 		emit("node-mouseleave", node, indexOf(node), e);
 	}
 	function handleClick(node, e) {

package/dist/es/chart/Treemap.mjs

@@ -278,7 +278,7 @@ function useTreemap(props, slots, emit) {
 		emit("node-mouseenter", node, index, e);
 	}
 	function handleNodeMouseLeave(node, index, e) {
-		tooltip.clear("hover");
+		tooltip.clear("hover", "item");
 		emit("node-mouseleave", node, index, e);
 	}
 	function handleNodeClick(node, index, e) {

package/dist/es/events/sync.mjs

@@ -10,8 +10,7 @@ function useTooltipChartSynchronisation(source, enabled) {
 	const activeDataKey = computed(() => tooltip.target.value?.entry?.value?.settings.dataKey);
 	const eventEmitterSymbol = presentation.emitter;
 	const syncId = presentation.syncId;
-	const tooltipState = computed(() => tooltip.syncInteraction.value);
-	const isReceivingSynchronisation = computed(() => tooltipState.value?.active);
+	const isReceivingSynchronisation = computed(() => tooltip.receivingSynchronisation.value);
 	watchEffect(() => {
 		if (!enabled()) return;
 		if (isReceivingSynchronisation.value) return;

package/dist/es/events/usePointEvents.mjs

@@ -30,7 +30,7 @@ function usePointEvents(emit) {
 				emit("mouseenter", entry, index, event);
 			},
 			onMouseleave: (event) => {
-				tooltip.clear("hover");
+				tooltip.clear("hover", "item");
 				emit("mouseleave", entry, index, event);
 			}
 		};

package/dist/es/model/tooltip.mjs

@@ -286,8 +286,9 @@ function createTooltip(inputs) {
 			coordinate: input.coordinate
 		};
 	}
-	function clear(channel) {
+	function clear(channel, scope) {
 		if (channel === "hover" && settings.value.trigger !== "hover") return;
+		if (scope === "item" && selection.value?.target.entry === void 0) return;
 		request(null);
 		if (channel === "keyboard") {
 			selection.value = null;
@@ -371,10 +372,7 @@ function createTooltip(inputs) {
 			index: selection.value.requestedIndex,
 			active: selection.value.active
 		} : noInteraction),
-		syncInteraction: computed(() => ({
-			...selection.value?.channel === "sync" ? interaction.value : noInteraction,
-			label: label.value
-		})),
+		receivingSynchronisation: computed(() => selection.value?.channel === "sync"),
 		activeIndexFor,
 		coordinateFor,
 		activate,

package/dist/es/polar/pie/Pie.mjs

@@ -139,7 +139,7 @@ var PieView = /* @__PURE__ */ defineComponent({
 			});
 		}
 		function handleSectorLeave() {
-			tooltip.clear("hover");
+			tooltip.clear("hover", "item");
 		}
 		let sectorList = items.value;
 		const listeners = delegateItemEvents((position) => sectorList[position]?.value, {

package/dist/es/polar/radial-bar/RadialBar.mjs

@@ -217,7 +217,7 @@ var RadialBarView = /* @__PURE__ */ defineComponent({
 					emit("mouseenter", sector, sector.index, event);
 				};
 				const onMouseleave = (event) => {
-					tooltip.clear("hover");
+					tooltip.clear("hover", "item");
 					emit("mouseleave", sector, sector.index, event);
 				};
 				if (slots.shape) return createVNode("g", mergeProps({ "key": items.value[i].key }, { [DATA_ITEM_INDEX_ATTRIBUTE_NAME]: sector.index }, {

package/dist/model/tooltip.d.ts

@@ -228,18 +228,11 @@ export declare function useTooltipController(): {
     entries: import('./registry.js').Registry<TooltipPayloadConfiguration>;
     announcement: import('vue').ShallowRef<string, string>;
     keyboardInteraction: ComputedRef<TooltipInteraction>;
-    syncInteraction: ComputedRef<{
-        label: string | undefined;
-        configuration?: TooltipPayloadConfiguration;
-        active: boolean;
-        index: TooltipActiveIndex;
-        dataKey: import('../types/base.js').ChartDataKey | undefined;
-        coordinate: Coordinate | undefined;
-    }>;
+    receivingSynchronisation: ComputedRef<boolean>;
     activeIndexFor: (entry: Entry) => ComputedRef<number | null>;
     coordinateFor: (candidate: Target | undefined, fallback?: Coordinate) => Coordinate | undefined;
     activate: (channel: Channel, input: TooltipTargetRequest) => void;
-    clear: (channel: Channel) => void;
+    clear: (channel: Channel, scope?: "item") => void;
 };
 export declare function useTooltipSource(): TooltipSource;
 export declare function provideTooltipEntry(entry: Entry): void;
@@ -435,17 +428,10 @@ export declare function createTooltip(inputs: TooltipInputs): {
     entries: import('./registry.js').Registry<TooltipPayloadConfiguration>;
     announcement: import('vue').ShallowRef<string, string>;
     keyboardInteraction: ComputedRef<TooltipInteraction>;
-    syncInteraction: ComputedRef<{
-        label: string | undefined;
-        configuration?: TooltipPayloadConfiguration;
-        active: boolean;
-        index: TooltipActiveIndex;
-        dataKey: import('../types/base.js').ChartDataKey | undefined;
-        coordinate: Coordinate | undefined;
-    }>;
+    receivingSynchronisation: ComputedRef<boolean>;
     activeIndexFor: (entry: Entry) => ComputedRef<number | null>;
     coordinateFor: (candidate: Target | undefined, fallback?: Coordinate) => Coordinate | undefined;
     activate: (channel: Channel, input: TooltipTargetRequest) => void;
-    clear: (channel: Channel) => void;
+    clear: (channel: Channel, scope?: "item") => void;
 };
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vccs",
   "type": "module",
-  "version": "1.0.0-beta.1",
+  "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`.