vccs 1.0.0-beta.1 → 1.0.0

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

package/usage/guides/charts/tracker.md

@@ -0,0 +1,49 @@
+# Tracker
+
+Use `Tracker` for an ordered sequence of discrete statuses, such as daily service health or build results. Use `Sparkline` for a numeric trend and `Heatmap` for a two-dimensional value matrix.
+
+## Data shape
+
+- `data` contains one row per bar, ordered oldest first.
+- `data-key` selects the status and defaults to `status`.
+- `name-key` selects the label and bar identity; it defaults to `date`.
+- Built-in statuses are `up`, `degraded`, `down`, and `maintenance`; custom status strings need their own colors and labels.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Tooltip, Tracker } from 'vccs'
+
+const data = [
+  { date: '2026-08-01', status: 'up' },
+  { date: '2026-08-02', status: 'up' },
+  { date: '2026-08-03', status: 'degraded' },
+  { date: '2026-08-04', status: 'up' },
+  { date: '2026-08-05', status: 'down' },
+  { date: '2026-08-06', status: 'up' },
+  { date: '2026-08-07', status: 'maintenance' },
+]
+</script>
+
+<template>
+  <Tracker
+    :data="data"
+    :height="32"
+  >
+    <Tooltip :cursor="false" />
+  </Tracker>
+</template>
+```
+
+## Chart-specific rules
+
+- Keep input rows oldest first; the component does not sort them into time order.
+- Use a stable `name-key` so bars keep their identity when a moving window drops one row and appends another.
+- For custom statuses, set both `status-colors` and `status-labels`; unknown statuses otherwise use the muted color and their raw text.
+- Place `Tooltip` in the default slot. Cell events receive the original input row.
+- Use the `#cell` slot to replace a bar; its slot cell wraps the domain row rather than being the row itself.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`, `ssr-testing`, `sparkline`, `heatmap`, `calendar-heatmap`.

package/usage/guides/charts/treemap.md

@@ -0,0 +1,68 @@
+# Treemap
+
+Use `Treemap` to compare hierarchical part-to-whole values as rectangles, especially when there are many leaves. Use `PieChart` for a short flat list of proportions and `SunburstChart` when radial rings communicate the hierarchy better.
+
+## Data shape
+
+- `data` is an array of top-level nodes, not a single root object.
+- Each node has a `name` by default and may have a `children` array.
+- Leaves need a positive numeric `value`; `data-key` and `name-key` select different fields.
+- Parent values are derived by summing their descendants, so do not add totals to parent rows.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Tooltip, Treemap } from 'vccs'
+
+const data = [
+  {
+    name: 'Search',
+    children: [
+      { name: 'Google', value: 420 },
+      { name: 'Bing', value: 90 },
+    ],
+  },
+  {
+    name: 'Social',
+    children: [
+      { name: 'LinkedIn', value: 150 },
+      { name: 'Mastodon', value: 80 },
+    ],
+  },
+  {
+    name: 'Direct',
+    children: [
+      { name: 'Bookmarks', value: 160 },
+      { name: 'Newsletter', value: 110 },
+    ],
+  },
+]
+
+const colors = ['#f97316', '#14b8a6', '#f59e0b', '#06b6d4']
+</script>
+
+<template>
+  <Treemap
+    :data="data"
+    :height="320"
+    data-key="value"
+    :colors="colors"
+  >
+    <Tooltip :cursor="false" />
+  </Treemap>
+</template>
+```
+
+Animation is enabled by default; retrieve `ssr-testing` before taking screenshots or asserting exact geometry.
+
+## Chart-specific rules
+
+- The default `type="flat"` displays leaves. Their `colors` entry comes from their top-level group.
+- Set `type="nest"` for drill-down. Clicking a group shows its children and a breadcrumb trail for going back.
+- Use `stroke` to change the rectangle border color.
+- Customize rectangles and labels with the `#content` slot, not a function-valued `content` prop.
+
+## Related guides
+
+`installation`, `vue-api`, `ssr-testing`, `sunburst-chart`, `pie-chart`.

package/usage/guides/core/installation.md

@@ -0,0 +1,68 @@
+# Installation and registration
+
+vccs requires Vue `^3.5`, the `motion-v` `^2.4` peer, and an ESM bundler. The Nuxt module requires Nuxt 4; the Vite resolver requires `unplugin-vue-components` in the application's dev dependencies.
+
+## Install
+
+```sh
+pnpm add vccs motion-v
+```
+
+Install `motion-v` explicitly because not every package manager installs peers automatically.
+
+## Explicit imports in Vite
+
+Import components from `vccs` and compose them in the template. Retrieve the chart guide before choosing its children.
+
+```ts
+import { Bar, BarChart, Tooltip, XAxis, YAxis } from 'vccs'
+```
+
+Do not deep-import source files, runtime prop definitions, or internal helpers. The only public subpaths are `vccs/nuxt` and `vccs/resolver`.
+
+## Auto-imports in Vite
+
+```sh
+pnpm add -D unplugin-vue-components
+```
+
+```ts
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+import Components from 'unplugin-vue-components/vite'
+import { VccsResolver } from 'vccs/resolver'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    Components({ resolvers: [VccsResolver()] }),
+  ],
+})
+```
+
+The resolver imports a component only when the template uses it. Keep explicit imports for types and `defineChartComponents`.
+
+## Nuxt 4
+
+```ts
+export default defineNuxtConfig({
+  modules: ['vccs/nuxt'],
+})
+```
+
+The module registers every public component and composable. Import types and `defineChartComponents` from `vccs`.
+
+When another UI library also registers `Tooltip`, `Legend`, or `Label`, add a prefix:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['vccs/nuxt'],
+  vccs: { prefix: 'V' },
+})
+```
+
+This registers names such as `VBarChart` and `VLine`. Nuxt 3 is unsupported by the module; do not hide its build error with `transpile` or `ClientOnly` workarounds.
+
+## Related guides
+
+`vue-api`, `typed-rows`, `ssr-testing`.

package/usage/guides/core/ssr-testing.md

@@ -0,0 +1,50 @@
+# SSR and deterministic testing
+
+Server-rendered charts normally preserve their entrance start, then animate after hydration when they enter the viewport. Do not mistake that intended entrance state for missing SVG or a hydration failure.
+
+## Complete server HTML
+
+For a complete chart without client JavaScript, provide numeric `width` and `height` and disable animation on the chart root:
+
+```vue
+<AreaChart
+  :data="data"
+  :width="900"
+  :height="250"
+  :is-animation-active="false"
+>
+  <Area data-key="desktop" />
+</AreaChart>
+```
+
+Disabling animation alone does not reveal an unmeasured responsive chart. With only `height`, the server reserves a box using an initial width and the browser measures the real width later.
+
+Do not add `ClientOnly` to solve chart SSR. Use it only when the data itself exists exclusively in the browser.
+
+## Nuxt
+
+Retrieve `installation` and register `vccs/nuxt` under Nuxt 4. The module handles component and composable registration; fixed-size SSR needs no client-only wrapper.
+
+## Deterministic tests and screenshots
+
+Set `is-animation-active` to `false` on the chart root, or on an individual series when only that series must be still:
+
+```vue
+<BarChart
+  :data="rows"
+  :height="300"
+  :is-animation-active="false"
+>
+  <Bar data-key="desktop" />
+</BarChart>
+```
+
+The chart value supplies defaults to its items; an explicit series value overrides it. Disable animation before exact geometry assertions, screenshots, or pixel-exact SSR comparisons.
+
+In component tests, measure the container deliberately and assert library behavior through public classes such as `.v-charts-surface` and item attributes such as `data-v-charts-item-index`. Do not depend on generated SVG ids.
+
+Charts follow the operating system's reduced-motion setting, but tests must not depend on the host setting: disable animation explicitly.
+
+## Related guides
+
+`installation`, `vue-api`, `typed-rows`.

package/usage/guides/core/typed-rows.md

@@ -0,0 +1,47 @@
+# Typed chart rows
+
+A child component cannot infer the row type from its chart root's `data`. Create row-typed component aliases once when wrong `data-key` values or untyped tooltip rows should become compile-time errors.
+
+## Minimal example
+
+```vue
+<script setup lang="ts">
+import { Area, AreaChart, Tooltip, XAxis, defineChartComponents } from 'vccs'
+
+interface Visit {
+  date: string
+  desktop: number
+  mobile: number
+}
+
+defineProps<{ visits: Visit[] }>()
+
+const Chart = defineChartComponents<Visit>()({ AreaChart, Area, XAxis, Tooltip })
+</script>
+
+<template>
+  <Chart.AreaChart
+    :data="visits"
+    :height="300"
+  >
+    <Chart.XAxis data-key="date" />
+    <Chart.Area data-key="desktop" />
+    <Chart.Area data-key="mobile" />
+    <Chart.Tooltip />
+  </Chart.AreaChart>
+</template>
+```
+
+`Chart.Area data-key="tablet"` now fails typechecking because `tablet` is not a key of `Visit`. Tooltip content created through `Chart.Tooltip` receives payload entries whose `payload` is `Visit`.
+
+## Rules
+
+- Select every component used with that row type in one `defineChartComponents<Row>()({ ... })` call; use the resulting aliases in the template.
+- The runtime component references are unchanged. This helper narrows declarations, not behavior.
+- Only selected components are referenced by the consumer bundle.
+- Standalone charts can infer rows from `data`; use their retrieved guide's generic pattern when explicit aliases are unnecessary.
+- Import reusable model and payload types such as `BrushStartEndIndex`, `TooltipActiveIndex`, `TooltipPayloadEntry`, and `TooltipPayload` from `vccs`. Runtime `*VueProps` objects and internal context helpers are not public.
+
+## Related guides
+
+`installation`, `vue-api`, `ssr-testing`.

package/usage/guides/core/vue-api.md

@@ -0,0 +1,72 @@
+# Vue API rules
+
+vccs keeps Recharts component names but uses Vue rendering and reactivity contracts. Apply these rules only after retrieving the chart guide; supported slots and models are component-specific.
+
+## Slots replace render props
+
+Use named slots for custom shapes, dots, labels, ticks, tooltip content, and cursors. A function passed to a prop such as `dot` or `content` is not a Vue render contract.
+
+```vue
+<Tooltip>
+  <template #content="{ active, payload, label }">
+    <div v-if="active">
+      <strong>{{ label }}</strong>
+      <div>{{ payload?.[0]?.name }}: {{ payload?.[0]?.value }}</div>
+    </div>
+  </template>
+</Tooltip>
+```
+
+Do not spread tooltip slot props with `v-bind="tooltipProps"`; the project's ESLint auto-fix removes that spread. Destructure the slot instead. Each tooltip payload entry exposes the original row as `payload`.
+
+Common slot payloads:
+
+- Tooltip `content`: `{ active, payload, label, coordinate, accessibilityLayer }`. Payload entries carry `name`, `value`, `color`, `unit`, `dataKey`, and the original row as `payload`.
+- Line, Area, and Scatter `dot` / `activeDot`: `{ cx, cy, index, value, payload }` plus the series' presentation attributes. Render SVG at `cx` and `cy`.
+
+## Templates and events
+
+- Write `class`, not `className`.
+- Write SVG attributes in kebab-case, such as `stroke-width` and `stroke-dasharray`.
+- Use Vue events such as `@click`, not callback props such as `:on-click`.
+- Item event callbacks receive `(item, index, event)`.
+
+## Models
+
+- `v-model:active-index` is `number | null`; `null` means no active item. Never substitute `-1`.
+- `v-model:range` on `Brush` is `BrushStartEndIndex | null`; `null` selects all rows and replaces separate start/end models.
+- `v-model:hidden` on `Legend` controls hidden series keys.
+- A supplied model value is controlled state. An omitted model lets the component keep local state.
+
+Only bind a model documented by the retrieved chart guide. Do not infer that every chart root supports every model.
+
+## Responsive size
+
+Charts are responsive by default. Set a numeric `height` and let the chart fill its container's width; pass numeric `width` and `height` for a fixed box.
+
+```vue
+<LineChart
+  :data="rows"
+  :height="300"
+>
+  <!-- axes and series -->
+</LineChart>
+```
+
+Do not add `ResponsiveContainer`; it is deprecated and scheduled for removal in 2.0.
+
+## Data keys and missing values
+
+`data-key` accepts a field name, numeric index, or accessor function. Set `name` or `name-key` when an accessor function's series needs a readable label. `NaN` and `Infinity` are missing values, not finite coordinates.
+
+Retrieve `typed-rows` when wrong keys should become compile-time errors.
+
+## Theme and selectors
+
+A series without an explicit color uses `--v-charts-series-1` through `--v-charts-series-8`. Override those variables to theme a dashboard instead of repeating colors on every series.
+
+Library classes use the `v-charts-` prefix. Item marks expose `data-v-charts-item-index`; use these hooks for CSS and tests rather than Recharts class names.
+
+## Related guides
+
+`installation`, `typed-rows`, `ssr-testing`.