Axes & coordinates

Axes are derived from the active position scales; coordinate systems decide how scaled pixels project onto the canvas. Both have sensible defaults — you tune axes through .axes() and the coordinate system through .coord().

Axis configuration

.axes(spec) takes { x?, y? }, each an AxisSpec:

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.
gridLines	boolean	Draw gridlines for this axis.
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.

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. For common cases, the core API exports siNumber, currency, percent, and fixed:

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().

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"), and quality (angular tessellation step).

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. Panels share scales by default and reuse the chart’s geoms; only the data and sub-frame change per panel.

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.