vccs 1.0.0-beta.2 → 1.0.0

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

package/usage/vccs-usage.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- a command-line report */
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = dirname(fileURLToPath(import.meta.url))
+const packageJson = JSON.parse(readFileSync(join(root, '..', 'package.json'), 'utf8'))
+
+const chartIds = [
+  'area-chart',
+  'bar-chart',
+  'bar-list',
+  'calendar-heatmap',
+  'cohort-chart',
+  'composed-chart',
+  'funnel-chart',
+  'heatmap',
+  'journey-sankey',
+  'line-chart',
+  'pie-chart',
+  'radar-chart',
+  'radial-bar-chart',
+  'sankey',
+  'scatter-chart',
+  'sparkline',
+  'sunburst-chart',
+  'tracker',
+  'treemap',
+]
+
+export function loadCatalog() {
+  const catalog = JSON.parse(readFileSync(join(root, 'catalog.json'), 'utf8'))
+  return { ...catalog, vccsVersion: packageJson.version }
+}
+
+function normalize(value) {
+  return value.toLowerCase().replaceAll('_', '-').trim()
+}
+
+const stopwords = new Set(['a', 'an', 'and', 'are', 'build', 'by', 'chart', 'create', 'for', 'from', 'graph', 'how', 'in', 'is', 'make', 'need', 'of', 'on', 'plot', 'show', 'the', 'to', 'use', 'using', 'want', 'with'])
+
+function queryTokens(query) {
+  return normalize(query).split(/[^\p{L}\p{N}]+/u)
+    .filter(token => token.length > 1 && !stopwords.has(token))
+}
+
+function compact(value) {
+  return normalize(value).replace(/[^\p{L}\p{N}]/gu, '')
+}
+
+function summary(entry, score) {
+  return {
+    id: entry.id,
+    title: entry.title,
+    description: entry.description,
+    category: entry.category,
+    path: entry.path,
+    score,
+  }
+}
+
+function score(entry, query) {
+  const normalizedQuery = normalize(query)
+  if (!normalizedQuery)
+    return 0
+
+  const names = [entry.id, entry.title, ...entry.components]
+  const identity = normalize(names.join(' '))
+  const topics = normalize([entry.description, ...entry.useCases, ...entry.keywords].join(' '))
+  const exactName = names.some(name => compact(name) === compact(query))
+  let result = exactName ? 160 : identity.includes(normalizedQuery) ? 60 : 0
+
+  for (const token of queryTokens(query)) {
+    if (identity.includes(token))
+      result += 20
+    if (topics.includes(token))
+      result += 6
+  }
+  for (const phrase of [...entry.useCases, ...entry.keywords]) {
+    const normalizedPhrase = normalize(phrase)
+    if (normalizedPhrase.length > 1 && normalizedQuery.includes(normalizedPhrase))
+      result += 12
+  }
+  return result
+}
+
+export function searchCatalog(catalog, query, limit = 8) {
+  return catalog.guides
+    .map(entry => summary(entry, score(entry, query)))
+    .filter(entry => entry.score > 0)
+    .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+    .slice(0, limit)
+}
+
+export function retrieveGuides(catalog, ids) {
+  return ids.map((id) => {
+    const entry = catalog.guides.find(guide => guide.id === id)
+    if (!entry)
+      throw new Error(`Unknown guide "${id}". Run the list command to see valid ids.`)
+    return readFileSync(join(root, entry.path), 'utf8')
+  }).join('\n\n---\n\n')
+}
+
+export function validateCatalog(catalog) {
+  const errors = []
+  const seen = new Set()
+  for (const entry of catalog.guides) {
+    if (seen.has(entry.id))
+      errors.push(`Duplicate guide id: ${entry.id}`)
+    seen.add(entry.id)
+    for (const field of ['title', 'description', 'category', 'path']) {
+      if (!entry[field]) {
+        errors.push(`${entry.id}: missing ${field}`)
+      }
+    }
+    if (entry.path.includes('..') || !entry.path.startsWith('guides/'))
+      errors.push(`${entry.id}: unsafe guide path ${entry.path}`)
+    if (!existsSync(join(root, entry.path))) {
+      errors.push(`${entry.id}: missing file ${entry.path}`)
+      continue
+    }
+    if (entry.category === 'chart') {
+      const content = readFileSync(join(root, entry.path), 'utf8')
+      for (const marker of ['## Data shape', '## Minimal example', '## Chart-specific rules', '```vue']) {
+        if (!content.includes(marker)) {
+          errors.push(`${entry.id}: missing ${marker}`)
+        }
+      }
+      if (!content.includes(entry.components[0]))
+        errors.push(`${entry.id}: example does not name ${entry.components[0]}`)
+    }
+  }
+
+  const actualChartIds = catalog.guides.filter(entry => entry.category === 'chart').map(entry => entry.id).sort()
+  for (const id of chartIds) {
+    if (!actualChartIds.includes(id)) {
+      errors.push(`Missing chart guide: ${id}`)
+    }
+  }
+  for (const id of actualChartIds) {
+    if (!chartIds.includes(id)) {
+      errors.push(`Unexpected chart guide: ${id}`)
+    }
+  }
+  return errors
+}
+
+function usage() {
+  return 'Usage: vccs-usage <search "query" | list | retrieve "id[,id...]" | validate>'
+}
+
+function run(argv) {
+  const [command, argument] = argv
+  const catalog = loadCatalog()
+  if (command === 'search' && argument) {
+    const results = searchCatalog(catalog, argument)
+    if (!results.length)
+      throw new Error('No matching guides. Run the list command to browse all guides.')
+    console.log(JSON.stringify(results, null, 2))
+    return
+  }
+  if (command === 'list' && !argument) {
+    console.log(JSON.stringify(catalog.guides.map(entry => summary(entry, undefined)), null, 2))
+    return
+  }
+  if (command === 'retrieve' && argument) {
+    const ids = argument.split(',').map(id => id.trim()).filter(Boolean)
+    process.stdout.write(retrieveGuides(catalog, ids))
+    return
+  }
+  if (command === 'validate' && !argument) {
+    const errors = validateCatalog(catalog)
+    if (errors.length)
+      throw new Error(errors.join('\n'))
+    const chartCount = catalog.guides.filter(entry => entry.category === 'chart').length
+    console.log(`PASS: vccs ${catalog.vccsVersion}; ${catalog.guides.length} guides; ${chartCount} chart types; all chart guides have data and Vue examples.`)
+    return
+  }
+  throw new Error(usage())
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  try {
+    run(process.argv.slice(2))
+  }
+  catch (error) {
+    console.error(error.message)
+    process.exitCode = 1
+  }
+}