@askrjs/charts

Typed Canvas 2D plots for Askr applications, with the same immutable scene available for SVG and data export.

Version 0.1 is a clean break from the old CSS-first chart catalog. JavaScript comes from @askrjs/charts; structural and theme-token styles come from @askrjs/charts/styles. There are no component, core, default, per-chart CSS, template, or generator compatibility entrypoints.

Install

npm install @askrjs/charts

Import the styles once at the application boundary:

@import "@askrjs/charts/styles";

Quick start

Create a typed plot namespace once at module scope, then compose marks inside its root:

import { createPlot } from "@askrjs/charts";

type RevenueRow = {
  id: string;
  day: Date;
  revenue: number;
  target: number;
};

const RevenuePlot = createPlot<RevenueRow>();

const revenue: readonly RevenueRow[] = [
  { id: "mon", day: new Date("2026-07-13T00:00:00Z"), revenue: 42, target: 48 },
  { id: "tue", day: new Date("2026-07-14T00:00:00Z"), revenue: 58, target: 50 },
  { id: "wed", day: new Date("2026-07-15T00:00:00Z"), revenue: 51, target: 52 },
];

export function RevenueTrend() {
  return (
    <RevenuePlot.Root
      data={revenue}
      rowKey="id"
      label="Daily revenue"
      title="Revenue"
      description="Actual revenue and target for the current week."
    >
      <RevenuePlot.Bar x="day" y="revenue" />
      <RevenuePlot.Line x="day" y="target" />
      <RevenuePlot.Point x="day" y="target" />
    </RevenuePlot.Root>
  );
}

Row drives field-name inference. A numeric mark channel cannot name a string field, and a factory's primitives cannot be mixed into another factory's root. Fields, accessors, and expressions can be combined without giving up row typing.

Public surface

createPlot<Row>() returns a stable namespace containing:

• structure: Root, Scale, Axis, Grid
• marks: Bar, Line, Area, Point, Arc, Cell, Rect, Rule, Text
• interaction: Legend, Tooltip, Crosshair, Select, Zoom, Brush

The root owns responsive sizing, semantic labels, title and description, empty and summary states, controlled or uncontrolled view and selection, follow-latest behavior, activation, and export access through onApiChange.

Useful defaults are inferred from channels and mark context:

• numbers use linear scales
• Date values use local-time scales
• categorical positions use band or point scales
• categorical colors use ordinal scales; numeric colors use continuous scales
• Cartesian marks receive default axes and tooltip behavior

Add explicit scale, axis, grid, legend, or tooltip children when the composition needs different behavior. Named scales support mixed plots and dual axes.

Tooltip supports nearest-mark inspection and shared nearest-x inspection with mode="mark" | "x"; auto chooses shared x for compatible Cartesian marks. Add Select for click/tap and Enter/Space selection. Its single default replaces the selection, while toggle adds or removes source keys. Selection updates before the additive onActivate(row, key, target) callback.

Mounted plots always respond to their container. width is the SSR and initial-layout fallback, not a fixed browser width; use a sized container for a fixed mounted chart.

Data rules

• Signed finite numbers stay signed; negative values are not clamped to zero.
• null, undefined, invalid dates, and non-finite numbers are missing values, not zero.
• Log scales omit zero and negative values.
• diagnostics opts into omitted-value warnings, and summary receives omittedRowCount for accessible reporting.
• Stable row keys drive selection retention, transitions, and live updates.
• Use constant("...") for a literal string channel. Bare strings identify row fields.

Migration from the old catalog

There are no compatibility wrappers in 0.1.

| Removed 0.0 surface | 0.1 composition | Worked example | | ------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------- | | ChartShell | Plot.Root; keep product card or page chrome in the app | catalog | | ChartPanel | App-owned card/section plus Plot.Root title and description | catalog | | ChartEmptyState | Root empty="..."; keep loading and error ownership in the route | catalog | | ChartLegend | Plot.Legend | mark families | | AreaChart | Plot.Area | mark families | | BarChart | Plot.Bar | mark families | | LineChart | Plot.Line, optionally with Plot.Point | mark families | | DonutChart | Plot.Arc with innerRadius | mark families | | PieChart | Plot.Arc with innerRadius={0} | catalog recipes | | StackedBarChart | Plot.Bar stack="series"; use normalize for percent stacks | catalog recipes | | Sparkline | Compact Plot.Root with Plot.Line or Plot.Area | catalog recipes | | Heatmap | Plot.Cell | mark families | | Timeline | Plot.Rule, Plot.Point, and Plot.Text | mark families | | FlameGraph | Plot.Rect with partition(...) | mark families | | ProgressMeter | Bounded Plot.Bar plus Root meter={{ role: "meter", ... }} | mark families | | RadialGauge | Bounded Plot.Arc plus Root meter={{ role: "meter", ... }} | mark families | | @askrjs/charts/core | Helpers exported directly from @askrjs/charts | | @askrjs/charts/default or root CSS import | @askrjs/charts/styles | | Per-chart CSS, templates, and new:chart | One structural stylesheet and primitive composition |

More

• Charting contract
• Architecture and defaults
• Usage recipes
• Mixed histogram and trend
• All mark families
• Live data, interactions, and export

@askrjs/themes is optional. The stylesheet defines self-contained --ak-chart-* tokens and uses compatible Askr theme tokens when they are present.