vccs 1.0.0-beta.2 → 1.0.0

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

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

@@ -0,0 +1,62 @@
+# ScatterChart
+
+Use `ScatterChart` to show relationships or distributions across numeric variables, optionally with bubble size. Use `LineChart` for an ordered trend and `BarChart` for category comparisons.
+
+## Data shape
+
+- Give each `Scatter` its own `data` array when the series contain different points.
+- `XAxis data-key` and `YAxis data-key` select the numeric coordinates from each flat row.
+- Set `type="number"` on both axes for numeric positioning.
+- Add `ZAxis data-key` only when a third numeric field should control point size.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { CartesianGrid, Scatter, ScatterChart, Tooltip, XAxis, YAxis, ZAxis } from 'vccs'
+
+const data = [
+  { hours: 2, score: 62, students: 12 },
+  { hours: 4, score: 70, students: 18 },
+  { hours: 6, score: 79, students: 16 },
+  { hours: 8, score: 85, students: 22 },
+]
+</script>
+
+<template>
+  <ScatterChart :height="300">
+    <CartesianGrid />
+    <XAxis
+      data-key="hours"
+      type="number"
+    />
+    <YAxis
+      data-key="score"
+      type="number"
+    />
+    <ZAxis
+      data-key="students"
+      :range="[60, 400]"
+    />
+    <Tooltip :cursor="false" />
+    <Scatter
+      name="Classes"
+      :data="data"
+      fill="#f97316"
+    />
+  </ScatterChart>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Put `data` on each `Scatter` for multiple series; set `name` and add `Legend` to distinguish them.
+- `ZAxis range` sets the minimum and maximum dot size; omit `ZAxis` for uniform points.
+- The tooltip shows one point at a time rather than all series at a category.
+- Retrieve `composed-chart` when scatter points must share axes with bars, areas, or lines.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `line-chart`, `composed-chart`.

package/usage/guides/charts/sparkline.md

@@ -0,0 +1,51 @@
+# Sparkline
+
+Use `Sparkline` for a tiny trend inside a KPI tile, table row, or dense dashboard. Use `LineChart` when axes, multiple series, or a larger analytical view matter.
+
+## Data shape
+
+- `data` is an ordered array of numbers or object rows.
+- Object rows use `data-key="value"` by default; choose another numeric field with `data-key`.
+- Use `null` for a missing point that should remain a gap.
+- Set `name-key` to a date or another stable identifier when points must keep their identity across updates.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Sparkline, Tooltip } from 'vccs'
+
+const data = [
+  { day: 'Mon', value: 820 },
+  { day: 'Tue', value: 932 },
+  { day: 'Wed', value: 901 },
+  { day: 'Thu', value: 934 },
+  { day: 'Fri', value: 1090 },
+  { day: 'Sat', value: 1180 },
+]
+</script>
+
+<template>
+  <Sparkline
+    :data="data"
+    name-key="day"
+    type="area"
+    color="#f97316"
+    :height="40"
+  >
+    <Tooltip :cursor="false" />
+  </Sparkline>
+</template>
+```
+
+## Chart-specific rules
+
+- Use `type="line"`, `type="area"`, or `type="bar"`; `gap` and `radius` apply only to bars.
+- Give multiple sparklines the same `min` and `max` when their shapes must be comparable.
+- Use `name-key` for a moving time window; without it, points match by array position.
+- Place `Tooltip` in the default slot, or bind `v-model:active-index` to show the hovered point in your own markup.
+- The component fills its container width and defaults to 32px tall unless you set `height` or `aspect`.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `line-chart`, `area-chart`.

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

@@ -0,0 +1,66 @@
+# SunburstChart
+
+Use `SunburstChart` for two or three levels of a part-to-whole hierarchy as concentric rings. Use `PieChart` for one flat level and `Treemap` when many leaves need more readable areas and labels.
+
+## Data shape
+
+- `data` is one root object, not an array. The root is not drawn; its `children` form the inner ring.
+- Each node has a `name` by default and may have nested `children`.
+- Leaves need a numeric `value`; `data-key` and `name-key` select different fields.
+- Parent values are the sum of their children. A node may also provide `fill`.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { SunburstChart, Tooltip } from 'vccs'
+
+const data = {
+  name: 'Traffic',
+  children: [
+    {
+      name: 'Search',
+      fill: '#f97316',
+      children: [
+        { name: 'Google', value: 420 },
+        { name: 'Bing', value: 90 },
+      ],
+    },
+    {
+      name: 'Social',
+      fill: '#14b8a6',
+      children: [
+        { name: 'LinkedIn', value: 150 },
+        { name: 'Mastodon', value: 80 },
+      ],
+    },
+    { name: 'Direct', value: 160, fill: '#f59e0b' },
+  ],
+}
+</script>
+
+<template>
+  <SunburstChart
+    :data="data"
+    :height="320"
+    :inner-radius="40"
+    title="Traffic by source"
+  >
+    <Tooltip :cursor="false" />
+  </SunburstChart>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- Give the root at least one child; a root without `children` renders no sectors.
+- Set `fill` on a top-level group to color its branch. A child's own `fill` overrides its branch color.
+- Use `inner-radius` for the center hole and `outer-radius` when the automatic radius does not fit your layout.
+- Use `ring-padding` to separate rings and `padding` to separate sectors by angle.
+- Customize sectors with the `#content` slot, not a function-valued `content` prop.
+
+## Related guides
+
+`installation`, `vue-api`, `ssr-testing`, `treemap`, `pie-chart`.