Axes & coordinates

Axes are derived from the active position scales; coordinate systems decide how scaled pixels project onto the canvas. The defaults are sensible enough that most charts need nothing here — you tune axes through .axes() and the coordinate system through .coord().

Axis configuration

.axes(spec) takes { x?, y?, y2? }, each an AxisSpec. y2 is the secondary right-hand axis — declare a y2 scale and opt layers in via useY2() to activate it.

Option	Type	Notes
title	string | { text, maxWidth? }	Object form clips with an ellipsis past maxWidth.
format	(value) => string	Tick formatter; receives number / Date / string per scale type.
ticks	TickSpec	See below.
tickValues	readonly number[]	Explicit tick positions; overrides ticks count.
gridLines	boolean	Draw gridlines for this axis.
gridDash	"solid" | "dashed" | "dotted" | number[]	Gridline dash style. Default "solid".
gridColor	Color	Override the theme gridline color.
gridWidth	number	Override the gridline width (px).
axisLine	boolean	Draw the spine. Default true.
label	{ maxWidth? }	Clip long tick labels with an ellipsis.
labelCollision	"auto"	Decimate tick labels until they stop overlapping.
side	"left" | "right"	Which side a vertical (y) axis renders on. Default "left". Ignored when y2 is active.
placement	"outside" | "inside"	Draw tick labels inside the panel over marks. Default "outside".
labelAnchor	"on-line" | "above-line" | "below-line"	Vertical label anchor for inside placement. Default "on-line".

plot<Row>({ data })
  .layer(line({ x: "date", y: "value" }))
  .axes({
    x: { title: "Date", ticks: "auto", gridLines: true },
    y: { title: { text: "Revenue", maxWidth: 120 }, format: (v: number) => `$${v}` },
  });

Ticks (TickSpec)

ticks is one of:

• a number — target tick count (default 5).
• "auto" — pick the count from the axis pixel span (~80px/tick horizontal, ~50px/tick vertical). Useful for time series, where dense per-day ticks decay to weeks / months / quarters as the view widens.
• a TickIntervalSpec — { interval: TimeIntervalUnit, step? } for explicit time intervals (time scales only). interval: "quarter" is sugar for month, step: 3.

Tick formatting

format is a plain function — return whatever string you want. For common cases, the core API exports siNumber, currency, percent, and fixed so you don’t have to roll your own:

import { currency } from "insomni-plot/core";

plot<Row>({ data })
  .layer(bar({ x: "month", y: "spend" }))
  .axes({ y: { format: (v: number) => currency(v, { symbol: "$" }) } });

Coordinate systems

.coord(coord) sets the coordinate system. Default is coordCartesian() — the identity transform you know and expect.

Factory	Projection
coordCartesian()	Identity — standard rectangular plot.
coordPolar(opts?)	(θ, r) → (cx + r·cosθ, cy + r·sinθ); angular ring + radial spokes.
coordRadial(opts?)	coordPolar with openAngle: 0 and innerRadius: 0 (full disk).

CoordPolarOptions: startAngle (default -π/2, top), endAngle, openAngle (gap for non-full-circle layouts), direction (1 CCW / -1 CW), innerRadius, outerRadius, angleChannel ("x" / "y", default "y"), quality (angular tessellation step), and gridShape ("circle" (default) / "polygon" — draws radar/spider N-gon concentric rings instead of circles).

import { coordPolar } from "insomni-plot";

plot<Row>({ data })
  .layer(bar({ x: "category", y: "value" }))
  .coord(coordPolar({ innerRadius: 40 }));

Note

Polar projection applies to position-based geoms (lines tessellate into arcs; bars under polar become annular sectors). Cartesian is the identity, so existing charts are unaffected by the abstraction.

Faceting

.facet(spec) splits the data into a grid of panels by a key — each panel gets the same geoms and shared scales, just a different slice of the data.

FacetSpec<T>:

Option	Type	Notes
by	Aes<T, unknown>	Column or accessor producing the facet key.
ncol / nrow	number	Grid shape. Default near-square (ceil(√n)).
scales	"fixed" | "free"	"fixed" (default) shares scales; "free" per-panel.
gap	number	Panel spacing in pixels. Default 12.
strip	{ height?, fontSize?, color?, background? }	Panel header style.
format	(key) => string	Strip label formatter.

plot<Row>({ data })
  .layer(point({ x: "weight", y: "mpg" }))
  .facet({ by: "origin", ncol: 3 });

The y-axis is drawn only on the leftmost column and the x-axis only on the bottom row of populated panels; MountedPlot.plotFrame reports the union of all panel frames.

Next

• Mount, render & export — turning the spec into pixels.
• Scales & aesthetics — the scales axes are built from.