Core (imperative) API

insomni-plot/core is the imperative layer the grammar is built on: raw scales, axis builders, mark builders, legends, formatters, palettes, the data viewport, and the data navigator. Reach for it when you want to hand-wire a render without the Chart builder — or when you need a single primitive (a scale, a formatter, a color palette) in isolation.

import { linearScale, bandScale, bottomAxis, leftAxis, pointMark } from "insomni-plot/core";

Everything below is re-exported from insomni-plot/core. Many type exports accompany the functions; the tables list the runtime values.

Scales

Export	Builds
`linearScale`	Continuous linear scale.
`logScale`	Log scale.
`sqrtScale`	Square-root scale.
`timeScale`	Time (Date) scale.
`bandScale`	Categorical band scale.
`groupedBandScale`	Nested band scale (for grouped / dodged layouts).
`timeTicks` / `timeTickFormat`	Time-axis tick generation and formatting.
`expansion`	ggplot2-style domain expansion: additive and/or multiplicative widening of inferred position-scale domains.

const x = linearScale([0, 100], [0, 640]);
const y = bandScale(["a", "b", "c"], [0, 480]);

Axis builders

bottomAxis, leftAxis, topAxis, rightAxis build axes against a scale and emit into a layer. truncateToWidth clips labels to a pixel budget. Tick configuration uses TickSpec / TickIntervalSpec (shared with the grammar’s AxisSpec.ticks).

Mark builders

The drawing primitives that geoms compose:

Export	Mark
`pointMark`	Scatter / glyph points.
`lineMark`	Polyline.
`barMark` / `categoricalBarMark`	Bars.
`groupedBarMark` / `stackedBarMark`	Multi-series bars.
`areaMark` / `stackedAreaMark`	Filled areas.
`stack`	Stack layout (`StackOffset` / `StackOrder`).
`resamplePoints`	Curve resampling for smoothing.
`defineCurve` / `cardinalCurve`	Custom line curves.
`DASHED_PATTERN` / `DOTTED_PATTERN`	Dash pattern constants.

Annotation marks: ruleMark, bandMark, valueLabelMark.

Legends

legend builds a legend; pointSwatch, lineSwatch, barSwatch, areaSwatch build individual swatch specs. colorBar renders a continuous color-bar legend.

Formatters

Tick / label formatters: siNumber, currency, fixed, percent — each takes (value, options?) and returns a string. See the axis tick-formatting example.

Color palettes & scales

colorScale builds a color scale; categoricalPalette / continuousPalette construct palettes. Named palettes are re-exported here too — categorical (category10, tableau10, set1/set2/set3, dark2, paired, pastel, accent) and continuous / diverging (viridis, magma, inferno, plasma, cividis, coolwarm, spectral, rdbu, brbg, piyg, prgn, puor, blues, greens, reds, oranges, purples, greys).

Data viewport

The viewport models a pan/zoomable visible window over data:

createDataViewport(options) → DataViewport — a continuous/band/time viewport with panBy, zoomAt, visible-domain queries, and pan bounds.
linkViewports(options) — keep multiple viewports in sync.
bindDataViewport(options) — wire pointer events on a canvas to a viewport.

This is what the grammar’s panZoom: true mount option drives internally; MountedPlot.viewport exposes the live instance.

Data navigator

createDataNavigator(options) → DataNavigator — an overview / minimap-style navigator with a draggable indicator window over the full data extent.

Range presets

createRangePresets(options) builds a controller for quick range buttons (e.g. “1D / 1W / 1M / YTD”). linearPreset, logPreset, and timePreset build individual presets. The grammar wraps this in MountedPlot.attachRangePresets(...).

Distribution statistics

Pure helpers for stat geoms and custom analysis: bin, binBy, binBreaks, binWithBreaks, boxStats, confidenceBand, groupBy, jitter, kde, linearFit, loessFit, polyFit, quantile, rollingWindow, histogramMeasureValue.

import { linearFit, kde } from "insomni-plot/core";

const fit = linearFit(xs, ys); // RegressionFit | null — slope at fit?.summary.slope
const density = kde(values, { bandwidth: "silverman" });

Heatmap producer

heatmapLayer(data, spec) produces a GPU heatmap layer (HeatmapProducer) for dense density / matrix rendering, separate from the grammar’s tile geom.

Data reshape helpers

Available from insomni-plot (not insomni-plot/core):

Export	Purpose
`fromMatrix`	Convert a 2D `values[row][col]` matrix into long-format rows for the `tile()` geom.
`pivotLonger`	Melt a wide table — one column per series — into long rows with a key column and a value column.

Dual-axis helper

useY2(geom) opts a geom into the secondary right-hand y2 scale. The chart must also declare .scale("y2", ...). Available from insomni-plot.

Categorical encoding combinators

distinguishable(options) generates maximally-distinct palettes across color, shape, and border-style channels simultaneously. palettes is a namespace of the built-in categorical palette identifiers it supports. Available from insomni-plot.

Default palette constants: DEFAULT_BORDER_STYLE_PALETTE, DEFAULT_OVERLAY_GLYPH_PALETTE — the baseline border-style and overlay-glyph sequences used when no palette override is supplied.

Gradient fills

linearGradient(stops, options?) builds a geometric linear gradient fill (screen-space, along "x" or "y"). isGradient(x) is a structural type guard. Available from insomni-plot.

Accessibility helpers

resolveTextColor(options) adjusts a text color to meet the active contrast target (WCAG or APCA). DEFAULT_ACCESSIBILITY is the library’s default Accessibility config. Available from insomni-plot.

Profiling hook

setRecorderHook(rec | null) injects a CPU/GPU timing recorder (e.g. devtools’ recordCpu / recordGpu). Pass null to reset to the no-op default. Available from insomni-plot.