# fcharts

> A dependency-free TypeScript charting library that renders 100k+ data points at 60fps on a
> `<canvas>` while staying fully accessible — keyboard-navigable, screen-reader-announced,
> find-in-page-able — through a real-DOM overlay. Because the data lives in the DOM (not just
> canvas pixels), the same layer makes charts **machine-readable to AI agents**. Web platform
> only (browsers); ~21 KB gzip for the tree-shaken canvas core (~39 KB with everything
> included), zero runtime dependencies. npm package: `fcharts-js`.

This file is everything an agent needs to build on fcharts. Source of truth: the public
API below. Chart family today: time-series **line + area + candle** (multiple series, live
streaming, linked panes, time/log axes) on canvas, plus server-safe **SVG primitives**
(donut, scatter, sparkline, bars, progress, heatmap) and **React / Vue / Svelte / web
component** adapters, SSR hydration, and a no-code render CLI.

## Install

```sh
npm install fcharts-js
```
```html
<script src="https://unpkg.com/fcharts-js/dist/fcharts.umd.cjs"></script>
<script>const { FChart } = window.fcharts;</script>
```

## Minimal usage

```ts
import { FChart } from 'fcharts-js';

// The container must have a non-zero size (e.g. width:100%; height:420px). Styles auto-inject.
const chart = new FChart(document.getElementById('chart'), {
  series: [
    { name: 'Price', color: '#16a34a', type: 'area' },
    { name: 'VWAP', color: '#d97706' },
  ],
  options: { ariaLabel: 'Price vs VWAP', xLabel: 'time', yLabel: 'value' },
});

// x is shared and non-decreasing; one y per series, each the same length as x.
const N = 100_000;
const x = Float64Array.from({ length: N }, (_, i) => i);
chart.setData({ x, y: [seriesA, seriesB] }); // seriesA/B: Float64Array | number[] of length N
```

## Public API

```ts
new FChart(el: HTMLElement, config: FChartConfig)

interface FChartConfig {
  series: SeriesConfig[];
  data?: FChartData;             // optional; or call setData later
  options?: FChartOptions;
  annotations?: AnnotationSpec[]; // event/point markers, announced + agent-readable
}

interface SeriesConfig {
  name: string;                  // announced to SR, shown in legend/tooltip
  color: string;                 // CSS color
  type?: 'line' | 'area' | 'candle';  // default 'line'
  visible?: boolean;             // default true
  width?: number;                // stroke px, default 1.25
  fillAlpha?: number;            // area fill 0..1, default 0.15
  upColor?: string;              // candle body, close >= open (default palette green)
  downColor?: string;            // candle body, close < open (default palette red)
}

interface FChartData {
  x: Float64Array | readonly number[];        // shared, NON-DECREASING, finite
  y: (Float64Array | readonly number[])[];    // one per series slot (candle series take FOUR
                                              // arrays — open, high, low, close), each length
                                              // === x.length, finite
}

interface FChartOptions {
  ariaLabel?: string;            // accessible chart name (also the summary label)
  xLabel?: string; yLabel?: string;
  legend?: boolean;              // default true
  xType?: 'linear' | 'time';     // 'time': x = epoch ms, calendar-boundary ticks + date labels
  yScale?: 'linear' | 'log';     // 'log': base-10; needs positive data (<=0 clamps to bottom)
  exportControl?: boolean;       // visible "Download data (CSV)" button; default false
  maxDpr?: number;               // device-pixel-ratio cap, default 2
  yPadding?: number;             // y-extent padding fraction, default 0.06
  xInteger?: boolean;            // integer-stepped x ticks, default false
  xTickCount?: number;           // default 8
  yTickCount?: number;           // default 6
  locale?: string;               // BCP-47 tag: Intl-localized DEFAULT formatters (dates,
                                 // month names, decimal separators); formatX/formatY win
  formatX?: (v: number) => string;  // tick + readout x formatter
  formatY?: (v: number) => string;  // tick + readout y formatter
  reducedMotion?: boolean;       // else auto from prefers-reduced-motion
  highContrast?: boolean;        // else auto from prefers-contrast
  strings?: Partial<FChartStrings>;  // localize fixed UI text (legend, keyboard help,
                                     // data summary, table caption) for non-English pages
}

// Methods (setData/update/renderSync return `this` for chaining)
chart.setData(data: FChartData): FChart            // replace data, reset view to full x-domain
chart.append(x: number, ys: number[]): FChart      // append one sample, amortized O(1) — streaming
chart.amendLast(ys: number[]): FChart              // rewrite the last sample in place — forming candles
chart.update(patch: Partial<FChartConfig>): FChart // patch series/options/data in place
chart.renderSync(domain?: readonly [number, number]): FChart  // synchronous render / programmatic zoom
chart.summary(): ChartSummary                      // structured machine-readable summary (see below)
chart.toCSV(): string                              // full dataset as CSV (candles → 4 OHLC columns)
chart.onDomainChange(cb): () => void               // x-domain change subscription (returns unsubscribe)
chart.destroy(): void                              // remove DOM, listeners, observers, timers
chart.renderPath: 'dom-overlay' | 'html-in-canvas' // getter; DOM-overlay is the default, no-flags path
chart.htmlInCanvas: { supported: boolean; via: string | null } // getter

interface ChartSummary {
  label: string; points: number; xStart: number; xEnd: number;
  series: SeriesSummary[];
  annotations?: AnnotationSummary[];   // present when the chart has annotations
}
interface SeriesSummary {
  name: string; visible: boolean;
  min: number; max: number; first: number; last: number; mean: number;
  changeAbs: number;   // last - first
  changePct: number;   // percent change vs first (range-relative when first is 0)
  trend: 'up' | 'down' | 'flat';  // derived from changePct; <1% is flat
}
```

## Real-time / streaming

`append(x, ys)` adds one sample without rebuilding anything (only the pyramid tail updates), so
cost stays flat as the series grows. `x` must be >= the current last x; pass one y per series
slot. `amendLast(ys)` rewrites the last sample in place (forming candle bucket). The view follows
the live tail when already showing it; a user panned back into history stays put. The library
never auto-updates on its own — if you drive `append` on a timer, provide a Pause/Stop control
and respect `prefers-reduced-motion` (WCAG 2.2.2).

## Agent-readable: how an AI agent reads the data

A canvas chart is opaque pixels. fcharts puts the data in the DOM, so an agent can read it
three ways (all inside the chart container):

1. **JS, if you hold the instance:** `chart.summary()` → `ChartSummary`.
2. **Embedded JSON, from the DOM:** `JSON.parse(container.querySelector('script[data-fcharts]').textContent)` → the same `ChartSummary`.
3. **Accessibility tree:** the focusable `[role="application"]` surface has `aria-describedby`
   pointing to a one-line natural-language summary (values + trend), `aria-details` pointing to
   a hidden `<table class="fc-table-alt">` of downsampled rows, and an `[aria-live="polite"]`
   region that announces the focused sample. Axis ticks are real text inside `.fc-ticks`.

To navigate values programmatically: focus the surface, dispatch ArrowLeft/Right/Up/Down/Home/End,
and read the `[aria-live]` element's textContent after each step.

Static SVGs produced by the primitives below embed the same summary as
`<script type="application/json" data-fcharts="summary">`.

## Interaction model

- Wheel = zoom x around the pointer · drag = pan.
- Focus the `[role="application"]` surface, then: `ArrowLeft`/`ArrowRight` move between samples,
  `ArrowUp`/`ArrowDown` switch series, `Home`/`End` jump to ends, hold `Shift` for fine (1-sample)
  steps, `+`/`-` zoom in/out (keyboard equivalent of the wheel), `Escape` dismisses the cursor
  (keeping focus). The focused sample is also exposed via the surface's `aria-describedby`
  (updated in lockstep), so agents can read the current point without listening to the live region.
- Legend buttons (`aria-pressed`) toggle series visibility.

## Server-side SVG (Node-safe, no DOM)

```ts
import {
  renderSVG,                       // line/area/candle chart → standalone SVG string
  buildDonutSVG, buildScatterSVG,  // categorical primitives
  buildSparklineSVG, buildBarsSVG, buildProgressSVG, buildHeatmapSVG,
  buildSVG,                        // low-level scene primitive
  lightTheme, darkTheme, resolveTheme, STATUS_COLORS,
} from 'fcharts-js';

const svg = renderSVG(
  { series: [{ name: 'Price', color: '#16a34a' }], options: { ariaLabel: 'Price' } },
  { x, y: [price] },
  { width: 640, height: 320, theme: darkTheme },
);
```

Every builder outputs a self-contained accessible SVG (`role="img"`, `<title>`, embedded data
summary). For interactivity on a static SVG, `attachReadout(container, opts)` (client-side,
optional) adds the same `.fc-readout` hover tooltip the live `FChart` shows.
`buildHeatmapSVG({ rows, cols, cells }, { width })` renders a rows × cols matrix on a two-stop
sequential ramp (missing cells draw as outlined slots, values live in `<title>` + JSON).

Also available:
- **`hydrate(container, config)`** — swap a server-rendered `renderSVG` inside `container` for
  the live interactive chart, synchronously, with no layout shift.
- **`syncCharts([a, b, …])`** — link panes so zoom/pan on one moves the others (returns unlink).
- **`defineFChart()`** — register the `<f-chart>` web component (light DOM; configure via the
  `config` property).
- **`stringsDE` / `stringsFR` / `stringsES`** — complete UI-string translations for
  `options.strings`.
- **`fcharts-render` CLI** — `fcharts-render spec.json > chart.svg` (or stdin), spec =
  `{ config, data, svg: { width, height, theme } }`; no browser, no code.

## Framework adapters (`fcharts-js/react`, `fcharts-js/vue`, `fcharts-js/svelte`)

```tsx
import { FChart } from 'fcharts-js/react';   // React 18+ component
<FChart series={[{ name: 'Price', color: '#16a34a' }]} data={{ x, y: [price] }}
        options={{ ariaLabel: 'Price' }} style={{ height: 320 }} />
```
```ts
import { FChart } from 'fcharts-js/vue';     // Vue 3 component, same props
import { fchart } from 'fcharts-js/svelte';  // Svelte action: <div use:fchart={{ series, data }} />
```

All three are thin wrappers over the imperative class with the same contract: mount once,
forward identity-changed props via `chart.update()`, remount only when a construction-fixed
option (`legend`, `sonify`, `exportControl`, `strings`) changes, destroy on unmount. React and
Vue are optional peer dependencies (separate entries; the core never pulls them in); the Svelte
action imports nothing from Svelte. Pass stable `data`/`series`/`options` references — a new
`data` identity resets the view.

## Theming

CSS custom properties on the container or `:root` (a few examples; all have sensible defaults):
`--fc-ink` (DOM text), `--fc-tick-color`, `--fc-grid`, `--fc-axis`, `--fc-cursor`,
`--fc-focus` (focus ring), plus readout (tooltip) colors. SVG primitives take a `theme` object
(`lightTheme` / `darkTheme` / `resolveTheme(partial)`) instead.

## Data contract & gotchas

- `x` must be non-decreasing; every `y` must be the same length as `x`; values should be finite
  (non-finite y is skipped from stats and renders as a gap).
- One shared `x` across all series (columnar). A `candle` series consumes four consecutive
  arrays in `data.y` (open, high, low, close); `line`/`area` take one each.
- The container needs an explicit size; `height:100%` needs a definite-height ancestor (the
  chart warns once in the console when it measures zero height).
- Styles are injected once per document — no CSS import.
- HTML-in-Canvas is feature-detected; the DOM-overlay path is the default and works in stock
  Chrome/Firefox/Safari with no flags.

## Performance

- Render cost is O(viewport width), independent of point count: a precomputed min/max pyramid is
  picked per frame so per-frame work tracks pixels, not N. Frame cost is ~flat from 10k to 250k
  points (<16ms budget with large headroom).
- `setData` is O(N) once (builds the pyramid + stats); rendering never iterates raw N.
  `append` is amortized O(1); `amendLast` is O(log n).

## Compliance Pack (separate entry: `fcharts-js/compliance`)

The MIT renderer is accessible; the Compliance Pack proves it and keeps the proof current. Never
bundled into the core chart (it imports Playwright as a dev/peer dep).

- **WCAG 2.2 AA evidence map** for the chart layer: 33 Supports / 2 Partially Supports / 20 Not
  Applicable across the 55 Level A+AA criteria, with `file:line` evidence
  (`compliance/scope-and-evidence-map.md`).
- **`buildModel()` + `renderAcr(model, 'md'|'html'|'json')`** — generate a VPAT/ACR for the
  `en301549` (EU), `wcag`, or `section508` edition from one dependency-free generator. Functional-
  performance rows are derived from the WCAG rows (can't contradict them). Unsigned → DRAFT; a
  real auditor signs the manual-attestation rows. Sample: `compliance/samples/`.
- **`fcharts-audit` CLI** (`runConformance` engine + `reduceToVerdicts`) — runs functional a11y
  checks (keyboard, zoom, Escape, live region, computed contrast, target size, DOM semantics)
  against a live chart, fails the build on any regression below the baseline, regenerates the ACR.
  Wire it in CI per `compliance/ci-gate.md`. Pure helpers (contrast math, the reducer, the
  baseline) are importable and unit-tested. Entry: `fcharts-js/compliance` (`buildModel`,
  `renderAcr`, `CRITERIA`, `runConformance`, contrast helpers).
- **Audit any chart** — `fcharts-audit --target <url> --selector <css>` points the same
  functional checks at a chart you don't own (Highcharts, ECharts, a bare canvas). Report-only
  (no baseline gate): it writes `audit-report.json` + a console tally showing exactly which
  keyboard/SR/contrast checks fail — the gap axe-core can't see.
- **Diff two ACRs** — `fcharts-audit --compare <old.json> <new.json>` (the `acr-<edition>.json`
  outputs) reports per-criterion conformance changes (improved / regressed / scope-changed /
  remarks-only) and exits 1 when a claim weakened. Pure JSON diff — needs neither Playwright nor
  Vite; `--help` and `--compare` work without any optional peer installed.
- **Real screen-reader CI** — `pnpm test:at` drives actual screen readers over a live chart via
  guidepup and asserts on the spoken phrases: NVDA runs green on every push to main (Windows
  runner); a VoiceOver sibling runs as macOS monitoring (`.github/workflows/at.yml`; both skip
  cleanly where screen-reader automation isn't available).

## Scope (today) and what's NOT included

- IN: canvas time-series line + area + candle with live streaming (`append`/`amendLast`),
  annotations, time/log axes, linked panes, and CSV export; wheel-zoom/drag-pan; keyboard
  cursor; legend; the accessibility + agent-readable layer (localized de/fr/es packs included);
  server-safe SVG primitives (donut, scatter, sparkline, bars, progress, heatmap) with themes;
  SSR hydration; React/Vue/Svelte/web-component adapters; a render CLI; the Compliance Pack
  (incl. audit-any-chart and a VoiceOver CI harness).
- NOT: treemap/geo, WebGL backend, worker rendering, brush/minimap, React Native. The
  renderer-agnostic `core/` (scales, ticks, pyramid, scheduler) is platform-agnostic, so those
  can slot in later, but they are not built. This is a web library.

## Links

- [Live demo + landing](https://fcharts.dev/): the hero chart — 120k points, streaming, keyboard-navigable
- [Playground](https://fcharts.dev/playground): configure a chart interactively and copy the config
- [Guide: accessible canvas charts](https://fcharts.dev/guides/accessible-canvas-charts): the real-DOM overlay pattern
- [Guide: WCAG requirements for charts](https://fcharts.dev/guides/wcag-chart-requirements): criterion by criterion
- [Guide: audit any chart](https://fcharts.dev/guides/audit-any-chart): the one-command functional audit
- [Sample chart-layer ACR](https://fcharts.dev/acr-en301549): the generated EN 301 549 conformance report
- [GitHub repository](https://github.com/Fbartoli/fcharts): source, README quickstart, benchmark harness under `bench/` with committed three-engine results
- [npm package](https://www.npmjs.com/package/fcharts-js): `fcharts-js`, published with provenance
- [fcharts-audit GitHub Action](https://github.com/marketplace/actions/fcharts-accessibility-audit): the audit as a CI step