@sophistry/charts 0.0.0-stage → 0.0.1

package/dist/grids/barbs.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Wind barbs over a vector-field lattice: a fixed-length shaft with ticks for magnitude. Shares
+ * its sampling and colour ramp with core's `vectorField` (`createFieldEngine`). Magnitude is
+ * read in data units; direction follows the mapped vector, so flipped or log axes turn barbs as
+ * they bend arrows.
+ *
+ * One shape node per colour band (at most `bands`, 10 by default), as
+ * `vectorField` does: a band's shafts are strokes and its pennants are filled
+ * (`ShapeGeometry.fillFrom`), which a path batch item cannot express.
+ */
+import type { FieldProps } from "@sophistry/core";
+/**
+ * Props of {@link barbs}.
+ *
+ * @category Charts
+ */
+export interface BarbsProps extends FieldProps {
+    /**
+     * Shaft length, the same for every barb (magnitude lives in the ticks). Defaults to most of one
+     * lattice cell.
+     */
+    length?: number;
+    /** Spacing between successive ticks. Defaults to `length / 6`. */
+    barbSpacing?: number;
+    /** Tick length. Defaults to `length / 2`. */
+    barbLength?: number;
+}
+/**
+ * A lattice of wind barbs: `function` is sampled on a lattice (see `FieldProps`) and each
+ * vector, in data units, drawn as a barb whose half, full and pennant ticks encode magnitude.
+ * Zero or non-finite vectors draw nothing. One shape per colour band. See {@link barbGlyph}
+ * for the glyph alone.
+ *
+ * @example
+ * ```ts
+ * import { axes } from "@sophistry/core";
+ * import { barbs } from "@sophistry/charts";
+ *
+ * axes.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	xRange: [-3, 3, 1],
+ * 	yRange: [-2, 2, 1],
+ * 	children: [barbs.create({ function: (p) => ({ x: 20 - p.y * 8, y: p.x * 6 }), ramp: "viridis" })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/guides/charts/#marks
+ * @category Charts
+ */
+export declare const barbs: import("@sophistry/core").Definition<BarbsProps, import("@sophistry/core/internal").CompositeNode<BarbsProps>, keyof BarbsProps>;
+//# sourceMappingURL=barbs.d.ts.map

package/dist/grids/barbs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"barbs.d.ts","sourceRoot":"","sources":["../../src/grids/barbs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAGX,UAAU,EAMV,MAAM,iBAAiB,CAAC;AAqCzB;;;;GAIG;AACH,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC7C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAqGD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,KAAK,kIA4BhB,CAAC"}

package/dist/grids/cell-rects.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A gridded layer's cells as one instances node of `rect`s: `pcolormesh`,
+ * `hist2d`, `cells`, and `imshow` when it can't be an image. Each cell is an
+ * axis-aligned box in scene units, filled from the layer's ramp, with its
+ * own opacity (`cells`' reading-order fade) and its own `progress` (the
+ * reading-order reveal of `pcolormesh`, `hist2d` and `imshow`: the fill
+ * comes up, a stroke traces). Internal to the charts.
+ */
+import type { CoordinateSystem, RectProps, SceneNode } from "@sophistry/core";
+import type { Bounds, Point } from "@sophistry/core/geometry";
+import type { BatchedMark, BatchItem } from "../batch";
+/** One cell on one frame, in scene units. */
+export interface CellItem extends BatchItem {
+    center: Point;
+    width: number;
+    height: number;
+    fill: string;
+    /** The cell's opacity: the layer's `opacity`, times its fade where it fades. */
+    opacity: number;
+    /** The cell's arc-length reveal, 0..1, as a rect's `progress`. @default 1 */
+    progress?: number;
+}
+/** The rect instances node a cell layer draws through. */
+export type CellRects<D extends CellItem = CellItem> = BatchedMark<D, RectProps, SceneNode<RectProps>, keyof RectProps>;
+/**
+ * Makes the rect instances node of a cell layer. Call once, in `setup`.
+ * Entering cells fade in and leaving ones fade out under a `transition`.
+ */
+export declare function createCellRects<D extends CellItem = CellItem>(): CellRects<D>;
+/** The scene box between two data corners, grown by `bleed` on every side. */
+export declare function cellBox(coords: Pick<CoordinateSystem, "coordsToPoint">, x0: number, y0: number, x1: number, y1: number, bleed?: number): Bounds;
+/** A box's centre, width and height, for a {@link CellItem}. */
+export declare function boxPlacement(box: Bounds): {
+    center: Point;
+    width: number;
+    height: number;
+};
+//# sourceMappingURL=cell-rects.d.ts.map

package/dist/grids/cell-rects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-rects.d.ts","sourceRoot":"","sources":["../../src/grids/cell-rects.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGvD,6CAA6C;AAC7C,MAAM,WAAW,QAAS,SAAQ,SAAS;IAC1C,MAAM,EAAE,KAAK,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,0DAA0D;AAC1D,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI,WAAW,CACjE,CAAC,EACD,SAAS,EACT,SAAS,CAAC,SAAS,CAAC,EACpB,MAAM,SAAS,CACf,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAgB7E;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CACtB,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,EAC/C,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,KAAK,SAAI,GACP,MAAM,CASR;AAED,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;IAC1C,MAAM,EAAE,KAAK,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CACf,CAMA"}

package/dist/grids/cells.d.ts

@@ -0,0 +1,131 @@
+/**
+ * `cells`: a grid of categorical cells coloured by a value, the categorical
+ * heatmap. The cells are one instances node of `rect`s keyed by datum key
+ * (per-cell picking through `event.key`, colour tweens through `transition`);
+ * their text, when asked for, is one `label` per cell (text does not batch).
+ * Keyed `to`/`blend` transitions slide cells with their bands and blend
+ * their colours, each end through its own ramp.
+ */
+import type { ColorRampSpec } from "@sophistry/core";
+import type { BandKey } from "@sophistry/core/geometry";
+import type { MarkTransition } from "../batch";
+import type { RampScaleProps } from "../color-norm";
+import type { Channel, ColorChannel } from "../data/channels";
+import type { KeyedTransitionProps, RevealProps } from "../props";
+import type { TooltipSpec } from "../tooltip";
+/**
+ * Props of {@link cells}.
+ *
+ * @category Charts
+ */
+export interface CellsProps<T = unknown> extends RampScaleProps, KeyedTransitionProps<T>, RevealProps {
+    /** One cell per datum. */
+    data: readonly T[];
+    /** The cell's column: a category on the band x axis. */
+    x: Channel<T, BandKey>;
+    /** The cell's row: a category on the band y axis. */
+    y: Channel<T, BandKey>;
+    /**
+     * The number the cell's colour encodes, through `ramp`. Non-finite values leave the cell out.
+     */
+    value?: Channel<T, number>;
+    /** A colour per cell, overriding `value`'s ramp: constant or `(d, i) => colour`. */
+    color?: ColorChannel<T>;
+    /**
+     * How `value` becomes colour: a colormap name (`"viridis"`), CSS stops, or `(t) => colour`.
+     * Defaults to the theme's ramp.
+     */
+    ramp?: ColorRampSpec;
+    /** Value at the bottom of the ramp. Defaults to the smallest value. */
+    rampMin?: number;
+    /** Value at the top of the ramp. Defaults to the largest value. */
+    rampMax?: number;
+    /**
+     * Text in each cell: `true` writes the value, a channel writes anything. Its colour is picked
+     * to read on the fill.
+     */
+    labels?: boolean | Channel<T, string>;
+    /**
+     * Font size of the labels.
+     * @default 0.22
+     */
+    labelFontSize?: number;
+    /**
+     * Gap left around each cell.
+     * @default 0.03
+     */
+    inset?: number;
+    /**
+     * Fill opacity, 0..1.
+     * @default 1
+     */
+    fillOpacity?: number;
+    /**
+     * Reveal, 0..1: cells fade in in reading order, top row first.
+     * @default 1
+     */
+    progress?: number;
+    /**
+     * Fraction of the reveal spent staggering across the cells, 0..0.95.
+     * @default 0.5
+     */
+    stagger?: number;
+    /**
+     * Hover tooltip: `true` for a row per channel (`x`, `y`, `value`), or a template, function or
+     * options. See {@link TooltipSpec}.
+     */
+    tooltip?: TooltipSpec<T>;
+    /**
+     * How cells move and change colour when `data` changes (outside a `to`
+     * blend): a tween or a spring in the node's tween bank; new cells fade in,
+     * removed ones fade out. Omitted, data changes are instant.
+     */
+    transition?: MarkTransition;
+    /**
+     * Paint order; the cells' text paints one above. Defaults to `UNDER_AXES_Z_INDEX` (above the
+     * grid, under the axes).
+     */
+    zIndex?: number;
+    /** Set to false to hide the cells. */
+    visible?: boolean;
+    /**
+     * Each cell's identity across transitions; give a key to follow a datum that moves to another
+     * cell. See {@link KeyedTransitionProps}. Defaults to its (column, row) pair.
+     */
+    key?: Channel<T, BandKey>;
+    /**
+     * The data to transition to, matched to `data` by `key`: shared cells blend colour (each end
+     * through its own ramp) and slide with their bands; others fade in or out. See {@link
+     * KeyedTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+}
+/**
+ * A grid of categorical cells coloured by a value: the categorical heatmap. Both axes become
+ * band axes with no gap; `labels` writes each value in a colour that reads on its cell. Must
+ * sit inside a `chart`. The cells are one instances node; tooltips resolve per cell.
+ *
+ * @example
+ * ```ts
+ * import { cells, chart } from "@sophistry/charts";
+ *
+ * const sales = [
+ * 	{ month: "Jan", region: "north", total: 12 },
+ * 	{ month: "Jan", region: "south", total: 7 },
+ * 	{ month: "Feb", region: "north", total: 9 },
+ * 	{ month: "Feb", region: "south", total: 11 },
+ * ];
+ * chart.create({
+ * 	width: 6,
+ * 	height: 3,
+ * 	colorbar: true,
+ * 	children: [cells.create({ data: sales, x: "month", y: "region", value: "total", labels: true })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const cells: import("@sophistry/core").Definition<CellsProps<any>, import("@sophistry/core/internal").CompositeNode<CellsProps<any>>, keyof CellsProps<any>>;
+//# sourceMappingURL=cells.d.ts.map

package/dist/grids/cells.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cells.d.ts","sourceRoot":"","sources":["../../src/grids/cells.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACX,aAAa,EAKb,MAAM,iBAAiB,CAAC;AAOzB,OAAO,KAAK,EAAE,OAAO,EAAU,MAAM,0BAA0B,CAAC;AAKhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,eAAe,CAAC;AAI/D,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAY,MAAM,kBAAkB,CAAC;AAaxE,OAAO,KAAK,EAAY,oBAAoB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAU9C;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO,CACtC,SAAQ,cAAc,EACrB,oBAAoB,CAAC,CAAC,CAAC,EACvB,WAAW;IACZ,0BAA0B;IAC1B,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IACnB,wDAAwD;IACxD,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACvB,qDAAqD;IACrD,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACvB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3B,oFAAoF;IACpF,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACtC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC1B;;;;;OAKG;IACH,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;CAClB;AA8XD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,KAAK,iJA4ChB,CAAC"}

package/dist/grids/contour-f.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `contourF`: filled contours of a gridded field, drawn as one path batch
+ * (one closed item per band, all its rings one outline). Bands come up
+ * together with their `progress` (a stroke traces),
+ * or fade in lowest first under `stagger`.
+ */
+import type { ColorRampSpec } from "@sophistry/core";
+import type { RampScaleProps } from "../color-norm";
+/**
+ * Props of {@link contourF}.
+ *
+ * @category Charts
+ */
+export interface ContourFProps extends RampScaleProps {
+    /** Column coordinates in data units, one per `values[row]` entry. */
+    xs: readonly number[];
+    /** Row coordinates in data units, one per `values` entry. */
+    ys: readonly number[];
+    /**
+     * `values[row][col]` is the sample at `(xs[col], ys[row])`; cells touching a non-finite sample
+     * are skipped.
+     */
+    values: readonly (readonly number[])[];
+    /**
+     * Explicit band boundaries, or a count of evenly spaced ones spanning the data's min and max
+     * (`N` levels make `N - 1` bands; spaced along `rampScale` when set).
+     * @default 8
+     */
+    levels?: readonly number[] | number;
+    /**
+     * Colour ramp a band's fill is sampled from, by its midpoint between the field's min and max:
+     * CSS stops, a colormap name, or `(t) => colour`. Defaults to two theme series colours.
+     */
+    ramp?: ColorRampSpec;
+    /**
+     * Fraction of `progress` spent staggering the bands, lowest first, 0..0.95; 0 draws every band
+     * at once.
+     * @default 0
+     */
+    stagger?: number;
+    /** One fill for every band, instead of the ramp. */
+    fill?: string;
+    /** Band outline. @default "none" */
+    stroke?: string;
+    /** Outline width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Reveal 0..1: the bands come up together (fade in one by one under `stagger`). @default 1 */
+    progress?: number;
+    /** Paint order. Defaults to `UNDER_AXES_Z_INDEX` (above the grid, under the axes). */
+    zIndex?: number;
+    /** Set to false to hide the bands. */
+    visible?: boolean;
+}
+/**
+ * Filled contours of a gridded field: one band between consecutive levels, coloured by the
+ * band's midpoint; samples outside the levels are left blank. Paints under the axes by default
+ * (`zIndex` `UNDER_AXES_Z_INDEX`). Inside a `chart` or `axes`; drawn as one path batch. For
+ * lines use `contour`. See {@link contourBands} for the geometry alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, contourF } from "@sophistry/charts";
+ *
+ * const xs = [-2, -1, 0, 1, 2];
+ * const ys = [-2, -1, 0, 1, 2];
+ * const values = ys.map((y) => xs.map((x) => Math.exp(-(x * x + y * y) / 2)));
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	colorbar: true,
+ * 	children: [contourF.create({ xs, ys, values, levels: 8, ramp: "viridis" })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const contourF: import("@sophistry/core").Definition<ContourFProps, import("@sophistry/core/internal").CompositeNode<ContourFProps>, keyof ContourFProps>;
+//# sourceMappingURL=contour-f.d.ts.map

package/dist/grids/contour-f.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contour-f.d.ts","sourceRoot":"","sources":["../../src/grids/contour-f.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACX,aAAa,EAKb,MAAM,iBAAiB,CAAC;AAQzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAuBpD;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc;IACpD,qEAAqE;IACrE,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;IACtB,6DAA6D;IAC7D,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACvC;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAqGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,QAAQ,2IAgCnB,CAAC"}

package/dist/grids/contour-shared.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What the contour layers share (`contour`, `contourF`, `triContour`,
+ * `triContourF`): the default two-colour ramp, the colour of a level or a
+ * band, and their path batch items. Lines and bands have an outline each, so
+ * every contour layer is one path batch: a line draws along its length (the
+ * item's `progress`), a band comes up with its
+ * `progress` or fades through its opacity. Internal to the charts.
+ */
+import type { ColorRampSpec, CoordinateSystem, PathBatchItem } from "@sophistry/core";
+import type { Point } from "@sophistry/core/geometry";
+import type { Colormap, Theme } from "@sophistry/core/themes";
+import type { ColorNorm } from "../color-norm";
+/** The contours' colormap: the given ramp, else two theme series colours. */
+export declare function contourRamp(spec: ColorRampSpec | undefined, theme: Theme): Colormap;
+/** A level's colour: its place on the norm, else between the field's min and max. */
+export declare function levelColor(ramp: Colormap, norm: ColorNorm | undefined, extent: readonly [number, number], level: number): string;
+/** A band's colour: its middle along the norm (a geometric mean on a log norm), else its midpoint between the field's min and max. */
+export declare function bandColor(ramp: Colormap, norm: ColorNorm | undefined, extent: readonly [number, number], lo: number, hi: number): string;
+/** One iso-line placed in scene units, with what its reveal reads. */
+export interface PlacedLine {
+    item: PathBatchItem;
+    level: number;
+}
+/** Iso-lines as open path batch items in scene units, stroked by level. */
+export declare function placeLines(lines: readonly {
+    level: number;
+    points: readonly Point[];
+}[], coords: Pick<CoordinateSystem, "coordsToPoint">, strokeOf: (level: number) => string): PlacedLine[];
+/**
+ * The lines at this frame of the reveal: whole at 1 (the placed items),
+ * traced along their length below it (the placed outline with that
+ * `progress`, so its arc length is measured once), left out at 0.
+ */
+export declare function revealLines(placed: readonly PlacedLine[], revealOf: (level: number) => number): PathBatchItem[];
+/** One band placed in scene units. */
+export interface PlacedBand {
+    item: PathBatchItem;
+    loLevel: number;
+}
+/** Bands as closed path batch items in scene units (all of a band's rings one item). */
+export declare function placeBands(bands: readonly {
+    loLevel: number;
+    hiLevel: number;
+    polygons: readonly (readonly Point[])[];
+}[], coords: Pick<CoordinateSystem, "coordsToPoint">, fillOf: (lo: number, hi: number) => string): PlacedBand[];
+/**
+ * The bands at this frame of a reveal: whole at 1, each band's fill coming
+ * up (and any stroke tracing) with its `progress` below it, left out at 0.
+ * Unstaggered `contourF` bands use it.
+ */
+export declare function revealBands(placed: readonly PlacedBand[], revealOf: (level: number) => number): PathBatchItem[];
+/** The bands at this frame of a fade: kept whole at 1, faded below it, left out at 0. */
+export declare function fadeBands(placed: readonly PlacedBand[], fadeOf: (level: number) => number): PathBatchItem[];
+//# sourceMappingURL=contour-shared.d.ts.map

package/dist/grids/contour-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contour-shared.d.ts","sourceRoot":"","sources":["../../src/grids/contour-shared.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACX,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG/C,6EAA6E;AAC7E,wBAAgB,WAAW,CAC1B,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,KAAK,EAAE,KAAK,GACV,QAAQ,CAKV;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CACzB,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,KAAK,EAAE,MAAM,GACX,MAAM,CAIR;AAED,sIAAsI;AACtI,wBAAgB,SAAS,CACxB,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACR,MAAM,CAKR;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CACzB,KAAK,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;CAAE,EAAE,EAC7D,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,EAC/C,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GACjC,UAAU,EAAE,CAWd;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAC1B,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GACjC,aAAa,EAAE,CAEjB;AAgBD,sCAAsC;AACtC,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CACzB,KAAK,EAAE,SAAS;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,CAAC,SAAS,KAAK,EAAE,CAAC,EAAE,CAAC;CACxC,EAAE,EACH,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC,EAC/C,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,GACxC,UAAU,EAAE,CASd;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAC1B,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GACjC,aAAa,EAAE,CAEjB;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CACxB,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAC/B,aAAa,EAAE,CAQjB"}

package/dist/grids/contour.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `contour`: iso-lines of a gridded field, drawn as one path batch (one open
+ * item per connected line, stroked by its level). The reveal draws each
+ * line along its length (the item's `progress`), staggered by level when
+ * asked.
+ */
+import type { ColorRampSpec } from "@sophistry/core";
+import type { Colormap } from "@sophistry/core/themes";
+import type { ColorNorm, RampScaleProps } from "../color-norm";
+/**
+ * Props of {@link contour}.
+ *
+ * @category Charts
+ */
+export interface ContourProps extends RampScaleProps {
+    /** Column coordinates in data units, one per `values[row]` entry. */
+    xs: readonly number[];
+    /** Row coordinates in data units, one per `values` entry. */
+    ys: readonly number[];
+    /**
+     * `values[row][col]` is the sample at `(xs[col], ys[row])`; cells touching a non-finite sample
+     * are skipped.
+     */
+    values: readonly (readonly number[])[];
+    /**
+     * Explicit iso-line values, or a count of evenly spaced levels strictly between the data's min
+     * and max (spaced along `rampScale` when set).
+     * @default 8
+     */
+    levels?: readonly number[] | number;
+    /**
+     * Colour ramp a level's colour is sampled from, by where it falls between the field's min and
+     * max: CSS stops, a colormap name, or `(t) => colour`. Defaults to two theme series colours.
+     */
+    ramp?: ColorRampSpec;
+    /**
+     * Fraction of `progress` spent staggering the levels, lowest first, 0..0.95; 0 draws every line
+     * at once.
+     * @default 0
+     */
+    stagger?: number;
+    /** One colour for every line, instead of the ramp. */
+    stroke?: string;
+    /** Line width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Reveal 0..1: each line draws along its length. @default 1 */
+    progress?: number;
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the lines. */
+    visible?: boolean;
+}
+/** The colour norm a contour layer asks for (a log or diverging scale), or undefined (linear). */
+export interface ContourColors {
+    norm: ColorNorm | undefined;
+    ramp: Colormap;
+    extent: [number, number];
+}
+/**
+ * Contour lines of a gridded field: one line per connected iso-line, coloured by its level.
+ * An explicit `stroke` colours every line the same. Inside a `chart` or `axes`; drawn as one
+ * path batch. For filled bands use `contourF`. See {@link contourLines} for the geometry
+ * alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, contour } from "@sophistry/charts";
+ *
+ * const xs = [-2, -1, 0, 1, 2];
+ * const ys = [-2, -1, 0, 1, 2];
+ * const values = ys.map((y) => xs.map((x) => x * x - y * y));
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	children: [contour.create({ xs, ys, values, levels: 6, ramp: "viridis" })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const contour: import("@sophistry/core").Definition<ContourProps, import("@sophistry/core/internal").CompositeNode<ContourProps>, keyof ContourProps>;
+//# sourceMappingURL=contour.d.ts.map

package/dist/grids/contour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contour.d.ts","sourceRoot":"","sources":["../../src/grids/contour.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACX,aAAa,EAKb,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAoB/D;;;;GAIG;AACH,MAAM,WAAW,YAAa,SAAQ,cAAc;IACnD,qEAAqE;IACrE,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;IACtB,6DAA6D;IAC7D,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;IACtB;;;OAGG;IACH,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACvC;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzB;AAwFD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,OAAO,wIA8BlB,CAAC"}

package/dist/grids/dendrogram.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `dendrogram`: a clustering's merge tree in a chart's margin, drawn as one
+ * path batch (one open item per bracket arm). Merges replay lowest first;
+ * each arm draws along its length (the item's `progress`).
+ */
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey } from "@sophistry/core/geometry";
+import type { ClusterNode } from "../math/cluster";
+/**
+ * Props of {@link dendrogram}.
+ *
+ * @category Charts
+ */
+export interface DendrogramProps {
+    /**
+     * The merge tree, from {@link clusterRows} or {@link linkageTree}: each leaf's `index` is a
+     * position in `categories`, each merge's `height` its linkage distance.
+     */
+    tree: ClusterNode | null | undefined;
+    /** The band-axis category of each clustered row: leaf `index` `i` stands at `categories[i]`. */
+    categories: readonly BandKey[];
+    /**
+     * The band axis the leaves stand on.
+     * @default "y"
+     */
+    axis?: "x" | "y";
+    /**
+     * Which side of the plotting area the dendrogram stands on, in the margin (it reserves room
+     * there). Move the axis names to the other side to keep the tree against the grid. Defaults to
+     * `"left"` for `axis="y"`, `"top"` for `axis="x"`.
+     */
+    side?: "left" | "right" | "top" | "bottom";
+    /**
+     * How far the root stands from the leaves.
+     * @default 0.8
+     */
+    size?: number;
+    /**
+     * Gap between the plotting area's edge and the leaves.
+     * @default 0.08
+     */
+    gap?: number;
+    /** Line colour. Defaults to the theme foreground. */
+    color?: ColorInput;
+    /**
+     * Line width.
+     * @default 0.02
+     */
+    strokeWidth?: number;
+    /**
+     * Line opacity, 0..1.
+     * @default 0.7
+     */
+    opacity?: number;
+    /**
+     * Reveal, 0..1: merges appear in clustering order, lowest first, each bracket rising to its
+     * height.
+     * @default 1
+     */
+    progress?: number;
+    /**
+     * Fraction of the reveal spent staggering the merges, 0..0.95.
+     * @default 0.6
+     */
+    stagger?: number;
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the tree. */
+    visible?: boolean;
+}
+/**
+ * A dendrogram in the margin of a `chart` with a band axis: a clustering's merge tree as
+ * elbow brackets, each leaf at its category's band and each merge as far out as its linkage
+ * distance. It reports its leaf order, so an unordered axis follows it. `heatmap` with
+ * `cluster` draws these for you; use this with `cells` to compose one by hand. Drawn as one
+ * path batch.
+ *
+ * @example
+ * ```ts
+ * import { cells, chart, clusterRows, dendrogram } from "@sophistry/charts";
+ *
+ * const rows = ["a", "b", "c"];
+ * const columns = ["x", "y"];
+ * const matrix = [
+ * 	[1, 2],
+ * 	[1.2, 1.9],
+ * 	[5, 0],
+ * ];
+ * const data = rows.flatMap((row, r) => columns.map((column, c) => ({ row, column, v: matrix[r][c] })));
+ * const { root } = clusterRows(matrix);
+ * chart.create({
+ * 	width: 4,
+ * 	height: 4,
+ * 	children: [
+ * 		cells.create({ data, x: "column", y: "row", value: "v" }),
+ * 		dendrogram.create({ tree: root, categories: rows, side: "left" }),
+ * 	],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const dendrogram: import("@sophistry/core").Definition<DendrogramProps, import("@sophistry/core/internal").CompositeNode<DendrogramProps>, keyof DendrogramProps>;
+//# sourceMappingURL=dendrogram.d.ts.map

package/dist/grids/dendrogram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dendrogram.d.ts","sourceRoot":"","sources":["../../src/grids/dendrogram.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAS,MAAM,0BAA0B,CAAC;AAK/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAYnD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,IAAI,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;IACrC,gGAAgG;IAChG,UAAU,EAAE,SAAS,OAAO,EAAE,CAAC;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC3C;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAuLD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,UAAU,iJA4BrB,CAAC"}