foldkit-viz

D3-quality visualisation primitives for FoldKit — no D3 dependency.

A pure-TypeScript data-transformation and geometry layer designed for use with FoldKit's TEA (The Elm Architecture) rendering model. All functions are pure, immutable, and framework-agnostic.

The runnable /request-diagnostics example shows these primitives inside a FoldKit state machine. The machine belongs to the consuming application; this package remains focused on chart geometry and chart-local state.

Installation

bun add @opsydyn/foldkit-viz

FoldKit compatibility

@opsydyn/foldkit-viz is tested with FoldKit 0.148.x. Consumers can use Command.define(name, { interrupt: true, ... }) to replace remote chart-data loads while this package remains focused on pure geometry, chart-local state, and rendering helpers. Chart views consume the render-scoped HtmlBuilder supplied by their parent; the package does not own application effects or remote-data policy.

This package remains framework-free and does not support server rendering. It does not import Astro, Request, foldkit/experimental/server, or Runtime.hydrate, and it does not own server Commands, request-derived Flags, or remote-data loading. Use @opsydyn/astro-foldkit's opt-in definePage path for the Astro server handoff, then pass the resulting model data to these pure chart primitives.

Modules

| Import path | Contents | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @opsydyn/foldkit-viz | Root barrel — all exports | | @opsydyn/foldkit-viz/math/scale | linear, log, band, point, sqrt, ordinal, scaleSequential, scaleQuantile, scaleQuantize, scalePow, scaleSymlog, linearInvertible, niceLinear | | @opsydyn/foldkit-viz/math/array | extent, sum, mean, median, variance, deviation, cumsum, group, rollup, bisect, pairs, zip, range | | @opsydyn/foldkit-viz/math/color | interpolateRgb, interpolateLab, interpolateHsl, interpolateRgbBasis, colorScale, divergingScale | | @opsydyn/foldkit-viz/math/schemes | tableau10, category10, wong, ibmCarbon, tolMuted, viridis, magma, inferno, plasma, cividis, diverging + sequential palettes | | @opsydyn/foldkit-viz/math/tween | tweenCreate, tweenStep, tweenValue, tweenPath, easeOutCubic, easeInOutCubic, easeOutElastic, + 5 more easings | | @opsydyn/foldkit-viz/math/time | scaleTime, timeTicks, timeFormat, timeParse, timeNice | | @opsydyn/foldkit-viz/math/stats | boxStats, kde, silvermanBandwidth, quantile | | @opsydyn/foldkit-viz/math/bin | bin — histogram binning | | @opsydyn/foldkit-viz/math/brush | BrushState, brushUpdate, brushExtent, brushContains, brushDomain | | @opsydyn/foldkit-viz/math/zoom | scaleAt, translateBy, constrainScale, rescaleDomain | | @opsydyn/foldkit-viz/interaction/selection | Selection, interval/key constructors, clamping, and membership helpers for parent-owned chart interaction state | | @opsydyn/foldkit-viz/shape/line | line — 14 curve types: linear, catmullRom, natural, basis, cardinal, step, stepBefore, stepAfter, + open/closed variants | | @opsydyn/foldkit-viz/shape/area | area — filled area between two line generators | | @opsydyn/foldkit-viz/shape/areaRadial | areaRadial, wedge — polar area shapes | | @opsydyn/foldkit-viz/shape/arc | arc, arcCentroid — pie/donut arc paths | | @opsydyn/foldkit-viz/shape/pie | pie — compute arc angles from data | | @opsydyn/foldkit-viz/shape/stack | stack — stacked series (D3 d3-shape parity) | | @opsydyn/foldkit-viz/shape/chord | chord, ribbon — chord diagram layout | | @opsydyn/foldkit-viz/shape/sankey | sankey — Sankey flow diagram layout | | @opsydyn/foldkit-viz/shape/geo | geoPath, geoEquirectangular, geoMercator, geoGraticule | | @opsydyn/foldkit-viz/shape/link | linkVertical, linkHorizontal | | @opsydyn/foldkit-viz/hierarchy | hierarchy, treeLayout, packLayout | | @opsydyn/foldkit-viz/simulation | Barnes-Hut force simulation (N-body) |

Parent-owned interaction state

Viz owns pure interaction values. Individual charts own their local gesture mechanics, while the consuming parent owns shared selection state and child-message coordination.

const selection = intervalSelection('x', [100, 300]);
const visible = allPoints.filter((point) => selectionContainsValue(selection, 'x', point.x));

keySelection is available for future hover or active-series interaction state. Hover and zoom are not implemented by this contract.

Quick start

import { linear, linearTicks } from '@opsydyn/foldkit-viz/math/scale';
import { extent } from '@opsydyn/foldkit-viz/math/array';
import { line } from '@opsydyn/foldkit-viz/shape/line';

const values = [10, 45, 23, 88, 67];
const [lo, hi] = extent(values) as [number, number];
const xScale = linear({ domain: [0, values.length - 1], range: [0, 400] });
const yScale = linear({ domain: [lo, hi], range: [200, 0] });

const points = values.map((v, i) => [xScale(i), yScale(v)] as const);
const pathD = line(points, { curve: 'catmullRom' });
// → "M0,148 C133.3,..."

Animation

Use math/tween with FoldKit's Subscription.animationFrame for smooth transitions:

import { tweenCreate, tweenStep, tweenValue, allTweensDone } from '@opsydyn/foldkit-viz/math/tween';
import { Subscription } from 'foldkit';

// In model.ts
const tween = tweenCreate(600 /* ms */, easeOutCubic);

// In subscription.ts
Subscription.animationFrame({
  isActive: (model) => !allTweensDone(model.tweens),
  toMessage: (dt) => Ticked({ dt }),
});

// In update.ts — on Tick:
tweenStep(model.tween, dt);

// In view.ts — bar height:
tweenValue(0, bar.value, model.tween);

Design principles

• No D3 dependency — pure TypeScript, tree-shakeable by module path
• Immutable — all functions return new values, never mutate
• TEA-native — designed for use in The Elm Architecture (state → message → update → view)
• D3 parity — faithful ports of D3's mathematical core; DOM-handling D3 packages are replaced by TEA patterns
• TypeScript strict — noUncheckedIndexedAccess, exactOptionalPropertyTypes

Documentation

bun run docs   # generates docs/ using TypeDoc

Testing

bun test       # 125 tests across 11 files

License

MIT — Alan P Currie