Chart views

Pro

Each view, in a fixed order, with whether the dataset allows it and, when not, why. A line needs an ordered axis and two points; a donut needs parts of one whole, one series and no negatives; stacking needs more than one series; bars and areas start at zero, so not below it; a heatmap needs series for its rows. The table is always allowed. Pass the words from useAllowedViews, or leave them out for English.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2 and 4.1.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/chart-views

Brings in: locale, tokens

Usage

TSX · The example above

"use client"

import * as React from "react"
import { BarChart } from "@/components/candor/bar-chart"
import type { ChartDatum } from "@/components/candor/chart-focus"
import { useAllowedViews } from "@/components/candor/chart-views"
import type { Series } from "@/lib/candor/data"

const repositories = ["api", "web", "billing", "workers"]
const runs: Series[] = [
  { id: "passed", label: "Passed", values: [212, 148, 96, 74] },
  { id: "failed", label: "Failed", values: [3, 0, 5, null] },
]

export default function Example() {
  const [filter, setFilter] = React.useState<ChartDatum | null>(null)
  // Repositories have no order of their own, and pass and fail counts aren't parts of one whole.
  const views = useAllowedViews({ categories: repositories.length, series: runs.length, ordered: false, partsOfWhole: false, negative: false })
  return (
    <div className="flex max-w-xl flex-col gap-3">
      <BarChart
        title="Tests by repository"
        categories={repositories}
        series={runs}
        stacked
        onSelect={setFilter}
        selected={filter}
        selectLabel={(d) => `Show the ${d.series.toLowerCase()} tests in ${d.category}`}
      />
      <p className="text-sm text-muted-foreground">{filter ? `Filtered to ${filter.series.toLowerCase()} tests in ${filter.category}.` : "Press a bar to filter."}</p>
      <ul className="flex flex-col gap-1 text-sm">
        {views.map((v) => (
          <li key={v.view}>
            <span className="font-medium">{v.label}</span>: {v.allowed ? "allowed" : v.reason}
          </li>
        ))}
      </ul>
    </div>
  )
}

Functions

allowedViews(shape: DatasetShape, words: (key: keyof ViewStrings) => string = (key) => chartViewsStrings[key])

useAllowedViews(shape: DatasetShape)

allowedViews in LocaleProvider's words.

Strings

The fixed words, in English by default. Change any of them under chartViews in <LocaleProvider strings={{ … }}>; the table is exported as chartViewsStrings.

Key	English
bar	Bars
stacked-bar	Stacked bars
line	Line
area	Area
donut	Donut
heatmap	Heatmap
table	Table
nothing	There is nothing to draw.
barsNegative	These bars start at zero and can't show values below it.
stackNeedsSeries	Stacking needs more than one series.
lineNeedsOrder	A line needs an ordered axis, such as time.
lineNeedsPoints	A line needs at least two points.
areaNegative	An area fills from zero and can't show values below it.
donutNeedsWhole	A donut needs parts of one whole.
donutNegative	A donut can't show values below zero.
donutOneSeries	A donut shows one series.
heatmapNeedsSeries	A heatmap needs more than one series, as its rows.

Types

ChartView: The views a dataset can be drawn in.; "bar" | "stacked-bar" | "line" | "area" | "donut" | "heatmap" | "table"
DatasetShape: What a dataset is like, which decides the views that tell the truth about it.; { /** How many categories (x positions, columns) there are. */ categories: number; /** How many series there are. */ series: number; /** Whether the categories have an order of their own, such as time; a line between unordered ones means nothing. */ ordered: boolean; /** Whether the values are parts of one whole, so a share of it means something. */ partsOfWhole: boolean; /** Whether any value is below zero. */ negative: boolean; }
ViewAllowance: One view and whether the dataset allows it; when it doesn't, `reason` says why.; { view: ChartView; label: string; allowed: boolean; reason?: string | undefined }