# Line chart

Change over time. 2px lines, a 10% wash for areas, a gap where data is missing (never a bridged line). A crosshair snaps to the nearest point and the tooltip lists every series there; arrow keys step through points. Up to four series get end labels unless they'd collide.

- Registry name: `line-chart` (`@candor/line-chart`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/line-chart

## Install

```bash
npx candor-ui add line-chart
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/line-chart`.
It brings in: chart-frame, data, locale, scale.

## Example

```tsx
"use client"

import { LineChart } from "@/components/line-chart"
import type { Series } from "@/lib/data"

const weeks = ["Sep 8", "Sep 15", "Sep 22", "Sep 29", "Oct 6", "Oct 13", "Oct 20", "Oct 27", "Nov 3"]

const coverage: Series[] = [
  { id: "all", label: "All code", values: [0.68, 0.7, 0.69, null, 0.72, 0.74, 0.73, 0.76, 0.78] },
  { id: "changed", label: "Changed files", values: [0.55, 0.61, 0.66, null, 0.7, 0.79, 0.83, 0.86, 0.88] },
]

export default function Example() {
  return (
    <LineChart
      className="max-w-xl"
      title="Test coverage"
      subtitle="Weekly · api repository"
      x={weeks}
      series={coverage}
      format="percent"
      state={{ kind: "partial", note: "Sep 29 is missing: that week’s CI run didn’t finish." }}
    />
  )
}
```

## <LineChart>

Props:

- `title: string`: What the chart shows, above it.
- `subtitle?: string | undefined`: A line under the title, e.g. the period or unit.
- `x: string[]`: The labels along the x axis, one per point.
- `series: Series[]`: One value per x label per series; null leaves a gap.
- `area?: boolean | undefined` (default `false`): Fills under each line with a light wash.
- `format?: ValueFormat | undefined` (default `"number"`): How values are written: number, percent (0–1), currency (USD) or duration (seconds). Defaults to number.
- `zeroBased?: boolean | undefined` (default `false`): Starts the y axis at zero instead of fitting it to the data; areas always start at zero.
- `state?: ChartState | undefined`: Loading, empty, partial or error. Defaults to ready.
- `height?: number | undefined`: The plot's height in pixels. Defaults to 220.
- `className?: string | undefined`

## Strings (`lineChart`)

The fixed words, English by default. Override any of them under `lineChart` in `<LocaleProvider strings={{ lineChart: { … } }}>`; the table is exported as `lineChartStrings`.

- `noData`: No data
- `over`: {series} over {from} to {to}
- `chartValues`: Chart values; use the table view to read them all

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.