vccs 1.0.0-beta.1 → 1.0.0

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`.

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

@@ -0,0 +1,58 @@
+# FunnelChart
+
+Use `FunnelChart` for values and drop-off across ordered conversion stages. Use `BarChart` for unordered categories; use `JourneySankey` when users can take branching paths instead of one shared sequence.
+
+## Data shape
+
+- Pass an array of flat rows to `Funnel data`; the chart root's `data` is the fallback when it is omitted.
+- Keep rows in process order, with one row per stage.
+- `data-key` selects the numeric stage value.
+- `name-key` selects the stage label and defaults to `name`.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Cell, Funnel, FunnelChart, Tooltip } from 'vccs'
+
+const data = [
+  { stage: 'Visited', users: 1000 },
+  { stage: 'Added to cart', users: 680 },
+  { stage: 'Reached checkout', users: 420 },
+  { stage: 'Purchased', users: 260 },
+]
+
+const colors = ['#f97316', '#14b8a6', '#f59e0b', '#06b6d4']
+</script>
+
+<template>
+  <FunnelChart :height="300">
+    <Tooltip :cursor="false" />
+    <Funnel
+      :data="data"
+      data-key="users"
+      name-key="stage"
+    >
+      <Cell
+        v-for="(entry, index) in data"
+        :key="entry.stage"
+        :fill="colors[index]"
+      />
+    </Funnel>
+  </FunnelChart>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Use one `Cell` per row for explicit segment colors; otherwise `fill` supplies the series color.
+- Place `LabelList` inside `Funnel` for stage values or custom labels.
+- Set `last-shape-type="rectangle"` to keep the final segment's width instead of narrowing to a point.
+- Set `:reversed="true"` to flip the funnel vertically; keep the source rows in process order.
+- Use `width` and the chart's `margin` for sizing. `Funnel` has no public `x` or `y` props; custom `#shape` geometry already applies the left offset to `x` and the top offset to `y`, so do not swap or re-add them.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `pie-chart`, `bar-chart`, `journey-sankey`.

package/usage/guides/charts/heatmap.md

@@ -0,0 +1,51 @@
+# Heatmap
+
+Use `Heatmap` to compare magnitude across two categorical dimensions, such as visits by weekday and hour. Use `CalendarHeatmap` for calendar dates and `CohortChart` for retention by elapsed cohort period.
+
+## Data shape
+
+- `data` is a flat array with one column key, one row key, and one numeric value per row.
+- The default fields are `x`, `y`, and `value`; override them with `x-key`, `y-key`, and `data-key`.
+- Rows with the same x/y pair are summed into one cell.
+- Columns and rows follow first appearance by default; use `x-domain` and `y-domain` for explicit order or empty categories.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Heatmap, Tooltip } from 'vccs'
+
+const data = [
+  { x: '09:00', y: 'Mon', value: 42 },
+  { x: '12:00', y: 'Mon', value: 68 },
+  { x: '18:00', y: 'Mon', value: 51 },
+  { x: '09:00', y: 'Tue', value: 38 },
+  { x: '12:00', y: 'Tue', value: 74 },
+  { x: '18:00', y: 'Tue', value: 49 },
+  { x: '09:00', y: 'Wed', value: 45 },
+  { x: '12:00', y: 'Wed', value: 79 },
+  { x: '18:00', y: 'Wed', value: 56 },
+]
+</script>
+
+<template>
+  <Heatmap
+    :data="data"
+    color="#14b8a6"
+  >
+    <Tooltip :cursor="false" />
+  </Heatmap>
+</template>
+```
+
+## Chart-specific rules
+
+- Use `color` for the full-intensity color and `empty-color` for empty cells; `max` sets the value that reaches full intensity.
+- Use `colors` only as a complete scale from empty to full; it overrides `color`, `empty-color`, and `levels`.
+- Keep `fill-missing` enabled for a complete matrix, or disable it when absent x/y pairs should remain holes.
+- Tooltip and cell-event payloads are aggregated cells with `{ x, y, value, rows }`; read source rows from `rows`.
+- `active-index` identifies a rendered cell position, not an input row index.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `calendar-heatmap`, `cohort-chart`, `tracker`.

package/usage/guides/charts/journey-sankey.md

@@ -0,0 +1,49 @@
+# JourneySankey
+
+Use `JourneySankey` for whole journeys through ordered steps, including path highlighting and drop-off. Use `Sankey` instead for an arbitrary flow graph; use `FunnelChart` when only stage totals matter and individual paths do not.
+
+## Data shape
+
+- `data` is an array with one row per observed journey.
+- `path` is an ordered array of page or event names; `count` is the number of sessions that took that path.
+- `path-key` and `data-key` select different row fields when your names differ.
+- The same name at different steps represents different nodes.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { JourneySankey, Tooltip } from 'vccs'
+
+const journeys = [
+  { path: ['/', '/pricing'], count: 6 },
+  { path: ['/', '/pricing', '/signup'], count: 4 },
+  { path: ['/', '/docs'], count: 3 },
+  { path: ['/blog/launch', '/pricing', '/signup'], count: 2 },
+]
+</script>
+
+<template>
+  <JourneySankey
+    :data="journeys"
+    :height="320"
+    color="#f97316"
+  >
+    <Tooltip :cursor="false" />
+  </JourneySankey>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Keep complete paths as input. Do not pre-convert them into Sankey `nodes` and `links`; whole paths are what preserve drop-off and exact-journey pinning.
+- Set `steps` to limit the displayed columns. Longer journeys are cut to that many steps.
+- Set `:exits-known="false"` when journeys were truncated before you received them, so their endpoints are not presented as session exits.
+- Click a node or band to pin the largest journey through it. Use `v-model:pinned` with a `string[] | null` ref to read or control the pinned path.
+- Set `:headers="false"` to hide step headers; use `color` and `exit-color` to distinguish continuing sessions from exits.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `sankey`, `funnel-chart`.

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

@@ -0,0 +1,60 @@
+# LineChart
+
+Use `LineChart` for one or more trends over an ordered axis. Use `Sparkline` instead when the chart must be tiny and axes would add noise; use `AreaChart` when filled magnitude matters.
+
+## Data shape
+
+- `data` is an array of flat rows on the chart root.
+- `XAxis data-key` names the ordered category or time value.
+- Each `Line data-key` selects one numeric series from the same row.
+- Use one `Line` per series and set `name` when the legend or tooltip needs a label different from the key.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { CartesianGrid, Legend, Line, LineChart, 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>
+  <LineChart
+    :data="data"
+    :height="300"
+  >
+    <CartesianGrid stroke-dasharray="3 3" />
+    <XAxis data-key="month" />
+    <YAxis />
+    <Tooltip :cursor="false" />
+    <Legend />
+    <Line
+      type="monotone"
+      data-key="desktop"
+      stroke="#f97316"
+    />
+    <Line
+      type="monotone"
+      data-key="mobile"
+      stroke="#14b8a6"
+    />
+  </LineChart>
+</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 `Line`.
+- Customize points with the `dot` or `activeDot` slot on `Line`, not a function-valued `dot` prop.
+- Use `connect-nulls` only when a gap should be bridged; otherwise missing values stay visible as gaps.
+- Retrieve `composed-chart` when bars, areas, or scatter points must share the same axes.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `area-chart`, `sparkline`, `composed-chart`.

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

@@ -0,0 +1,59 @@
+# PieChart
+
+Use `PieChart` for a small number of part-to-whole proportions. Use `BarChart` instead when precise comparison matters or there are many categories; use `Treemap` or `SunburstChart` for hierarchical parts.
+
+## Data shape
+
+- Pass an array of flat rows to `Pie data`; the chart root's `data` is the fallback when it is omitted.
+- `data-key` selects the numeric value for each sector.
+- `name-key` selects the sector label and defaults to `name`.
+- Render one `Cell` per row when each sector needs an explicit color.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Cell, Pie, PieChart, Tooltip } from 'vccs'
+
+const data = [
+  { source: 'Organic search', visitors: 420 },
+  { source: 'Direct', visitors: 280 },
+  { source: 'Referral', visitors: 190 },
+  { source: 'Social', visitors: 110 },
+]
+
+const colors = ['#f97316', '#14b8a6', '#f59e0b', '#06b6d4']
+</script>
+
+<template>
+  <PieChart :height="300">
+    <Tooltip :cursor="false" />
+    <Pie
+      :data="data"
+      data-key="visitors"
+      name-key="source"
+      :outer-radius="100"
+    >
+      <Cell
+        v-for="(entry, index) in data"
+        :key="entry.source"
+        :fill="colors[index]"
+      />
+    </Pie>
+  </PieChart>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Set `inner-radius` above `0` for a donut; keep `outer-radius` larger than the inner radius.
+- Use `start-angle` and `end-angle` for partial pies such as semicircles.
+- Set `:label="true"` for default sector labels and `label-line` to control their connectors.
+- `PieChart` uses item tooltips, so hovering a sector shows that sector rather than an axis-wide payload.
+- Use `v-model:active-index` with a `number | null` when the active sector is controlled externally.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `bar-chart`, `funnel-chart`, `treemap`, `sunburst-chart`.

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

@@ -0,0 +1,69 @@
+# RadarChart
+
+Use `RadarChart` to compare multivariate profiles across a shared set of dimensions. Use `LineChart` for ordered trends and `BarChart` when dimensions have incompatible units or precise magnitude comparison is the main task.
+
+## Data shape
+
+- Put a flat array on the chart root's `data`, with one row per dimension.
+- `PolarAngleAxis data-key` selects the dimension label.
+- Each `Radar data-key` selects one numeric profile from those same rows.
+- Use one `Radar` per profile and set `name` when its legend or tooltip label should differ from the key.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Legend, PolarAngleAxis, PolarGrid, Radar, RadarChart, Tooltip } from 'vccs'
+
+const data = [
+  { dimension: 'Ease of use', current: 82, previous: 74 },
+  { dimension: 'Performance', current: 88, previous: 80 },
+  { dimension: 'Support', current: 76, previous: 72 },
+  { dimension: 'Reliability', current: 91, previous: 85 },
+  { dimension: 'Value', current: 79, previous: 75 },
+]
+</script>
+
+<template>
+  <RadarChart
+    :data="data"
+    cx="50%"
+    cy="50%"
+    :outer-radius="100"
+    :height="300"
+  >
+    <PolarGrid />
+    <PolarAngleAxis data-key="dimension" />
+    <Tooltip :cursor="false" />
+    <Legend />
+    <Radar
+      data-key="current"
+      name="Current"
+      stroke="#f97316"
+      fill="#f97316"
+      :fill-opacity="0.3"
+    />
+    <Radar
+      data-key="previous"
+      name="Previous"
+      stroke="#14b8a6"
+      fill="#14b8a6"
+      :fill-opacity="0.3"
+    />
+  </RadarChart>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Keep every profile on the same scale across all dimensions; the example uses scores from 0 to 100.
+- Set `grid-type="circle"` on `PolarGrid` for circular rings instead of the default polygon grid.
+- Set `:dot="true"` for default vertex dots; use the `dot` or `activeDot` slot for custom content.
+- Use `connect-nulls` only when missing vertices should be bridged.
+- The `dot`, `active-dot`, and `label` props accept booleans or presentation objects, not render functions.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `line-chart`, `bar-chart`, `radial-bar-chart`.

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

@@ -0,0 +1,54 @@
+# RadialBarChart
+
+Use `RadialBarChart` for circular progress or category values on concentric tracks. Use `BarChart` for precise comparisons across many categories; use `PieChart` when part-to-whole angle is more important than individual tracks.
+
+## Data shape
+
+- Put a flat array on the chart root's `data`; with one `RadialBar`, each row produces one bar.
+- `RadialBar data-key` selects the numeric value from each row.
+- A row can carry a `fill` color for its bar, as in the example.
+- Set the chart's `inner-radius` and `outer-radius` to bound the tracks.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { RadialBar, RadialBarChart, Tooltip } from 'vccs'
+
+const data = [
+  { name: 'Chrome', visitors: 275, fill: '#f97316' },
+  { name: 'Safari', visitors: 200, fill: '#14b8a6' },
+  { name: 'Firefox', visitors: 187, fill: '#f59e0b' },
+  { name: 'Edge', visitors: 173, fill: '#06b6d4' },
+]
+</script>
+
+<template>
+  <RadialBarChart
+    :data="data"
+    :inner-radius="30"
+    :outer-radius="120"
+    :height="300"
+  >
+    <RadialBar
+      data-key="visitors"
+      :background="true"
+    />
+    <Tooltip :cursor="false" />
+  </RadialBarChart>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Set `:background="true"` for default background arcs, or pass a presentation object to customize them.
+- Use the chart's `start-angle` and `end-angle` to control the sweep of every bar.
+- Give multiple `RadialBar` components the same `stack-id` to stack their values; each one still needs its own `data-key`.
+- Use `bar-size` for bar thickness and `corner-radius` for rounded arc ends.
+- Place `LabelList` inside `RadialBar` for default labels, or use `RadialBar`'s `#label` slot for custom content.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `bar-chart`, `pie-chart`, `radar-chart`.

package/usage/guides/charts/sankey.md

@@ -0,0 +1,59 @@
+# Sankey
+
+Use `Sankey` for weighted flows between arbitrary nodes, such as energy distribution or budget transfers. Use `JourneySankey` instead for ordered session paths and drop-off; use `Treemap` for a part-to-whole hierarchy.
+
+## Data shape
+
+- `data` is one object containing `nodes` and `links` arrays.
+- Each node normally has a `name`; `name-key` selects another field for tooltip names.
+- Each link has numeric `source` and `target` indices into `nodes`, plus a numeric `value`.
+- Link width comes from `value`. Keep values positive and the graph acyclic.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Sankey, Tooltip } from 'vccs'
+
+const data = {
+  nodes: [
+    { name: 'Coal' },
+    { name: 'Gas' },
+    { name: 'Electricity' },
+    { name: 'Industry' },
+    { name: 'Homes' },
+  ],
+  links: [
+    { source: 0, target: 2, value: 30 },
+    { source: 1, target: 2, value: 20 },
+    { source: 2, target: 3, value: 28 },
+    { source: 2, target: 4, value: 22 },
+  ],
+}
+</script>
+
+<template>
+  <Sankey
+    :data="data"
+    :height="320"
+    node-fill="#f97316"
+    link-fill="#14b8a6"
+  >
+    <Tooltip :cursor="false" />
+  </Sankey>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Use numeric indices for `source` and `target`, not node names or object references.
+- Link widths always use `value`; `data-key` changes the tooltip data key, not the layout.
+- Invalid endpoints, non-positive values, and cyclic links are not rendered.
+- Customize nodes and links with the `#node` and `#link` slots, not function-valued props.
+- Adjust spacing with `node-width` and `node-padding`; use `margin` when labels need more room.
+
+## Related guides
+
+`installation`, `vue-api`, `ssr-testing`, `journey-sankey`, `treemap`.