@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/grids/heatmap.d.ts

@@ -0,0 +1,163 @@
+/**
+ * `heatmap`: the annotated heatmap preset, a `chart` around a `cells` layer;
+ * with `cluster`, a clustermap whose dendrograms stand in the chart's margin.
+ * The nodes are made once and updated in place.
+ */
+import type { ColorRampSpec, SceneNode } from "@sophistry/core";
+import type { BandKey, Point } from "@sophistry/core/geometry";
+import type { RampScaleName } from "../color-norm.js";
+import type { Channel } from "../data/channels.js";
+import type { ClusterLinkage, ClusterMetric } from "../math/cluster.js";
+import type { KeyedTransitionProps, RevealProps } from "../props.js";
+import type { TooltipSpec } from "../tooltip.js";
+/**
+ * Props of {@link heatmap}.
+ *
+ * @category Charts
+ */
+export interface HeatmapProps<T = unknown> extends KeyedTransitionProps<T>, RevealProps {
+    /** One cell per datum. */
+    data: readonly T[];
+    /** The cell's column: a category. */
+    x: Channel<T, BandKey>;
+    /** The cell's row: a category. */
+    y: Channel<T, BandKey>;
+    /** The number the cell's colour encodes. */
+    value: Channel<T, number>;
+    /**
+     * Column order; clustered columns are reordered. Defaults to the order first seen in `data`.
+     */
+    columns?: readonly BandKey[];
+    /**
+     * Row order, top to bottom; clustered rows are reordered. Defaults to the order first seen in
+     * `data`.
+     */
+    rows?: readonly BandKey[];
+    /**
+     * Cluster the rows, the columns, or both (`true`) by their values ({@link clusterRows}), laid
+     * out in dendrogram order so similar ones sit together. Missing cells are skipped.
+     * @default false
+     */
+    cluster?: boolean | "rows" | "columns";
+    /**
+     * How clusters are compared; see {@link ClusterLinkage}.
+     * @default "average"
+     */
+    linkage?: ClusterLinkage;
+    /**
+     * How rows (columns) are compared; see {@link ClusterMetric}.
+     * @default "euclidean"
+     */
+    metric?: ClusterMetric;
+    /**
+     * Draw each clustering's {@link dendrogram} in the margin: the rows' on the left (row names
+     * move right), the columns' above the grid. Defaults to true when clustering.
+     */
+    dendrogram?: boolean;
+    /**
+     * How far a dendrogram's root stands from its leaves.
+     * @default 0.8
+     */
+    dendrogramSize?: number;
+    /** Width of the plotting area. */
+    width: number;
+    /** Height of the plotting area. */
+    height: number;
+    /** Centre of the plotting area. Defaults to the origin. */
+    center?: Point;
+    /** Colormap name, 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;
+    /**
+     * How values spread over the ramp (`"log"`, `"symlog"`, `"sqrt"`).
+     * @default "linear"
+     */
+    rampScale?: RampScaleName;
+    /** A diverging centre: this value takes the ramp's middle. */
+    rampMidpoint?: number;
+    /**
+     * Write each value in its cell: `true`, `false`, or a channel for your own text.
+     * @default true
+     */
+    labels?: boolean | Channel<T, string>;
+    /** Font size of the cell text. */
+    labelFontSize?: number;
+    /** Title above the chart. */
+    title?: string;
+    /**
+     * A colour bar beside the grid.
+     * @default false
+     */
+    colorbar?: boolean;
+    /** A title above the colour bar. */
+    colorbarLabel?: string;
+    /** Title for the columns, placed past the right end of the x axis. */
+    xLabel?: string;
+    /** Title for the rows, placed above the y axis. */
+    yLabel?: string;
+    /**
+     * Reveal, 0..1: names first, then the cells in reading order.
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the cells' reveal spent staggering, 0..0.95.
+     * @default 0.5
+     */
+    stagger?: number;
+    /** Hover tooltip: `true` for "column · row: value", or `(d, i) => string`. */
+    tooltip?: TooltipSpec<T>;
+    /** Paint order of the chart; the cells paint under its guides. */
+    zIndex?: number;
+    /** Set to false to hide the heatmap. */
+    visible?: boolean;
+    /** Placed inside the chart's coordinate context, after the cells. */
+    children?: readonly SceneNode[];
+    /**
+     * Each cell's identity across transitions. See {@link KeyedTransitionProps}. Defaults to its
+     * (column, row) pair.
+     */
+    key?: Channel<T, BandKey>;
+    /**
+     * The data to transition to, cells matched by `key`: colours blend, unmatched cells fade,
+     * fitted columns and rows blend. Throws together with `cluster`. See {@link
+     * KeyedTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+}
+/**
+ * An annotated heatmap: a value per (column, row) pair, coloured through a ramp and written in
+ * its cell in a colour that reads on it. With `cluster`, a clustermap with dendrograms in the
+ * margin. A preset over `chart` and {@link cells}; use those to add other marks.
+ *
+ * @example
+ * ```ts
+ * import { heatmap } from "@sophistry/charts";
+ *
+ * const correlations = [
+ * 	{ a: "x", b: "x", r: 1 },
+ * 	{ a: "x", b: "y", r: -0.4 },
+ * 	{ a: "y", b: "x", r: -0.4 },
+ * 	{ a: "y", b: "y", r: 1 },
+ * ];
+ * heatmap.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	data: correlations,
+ * 	x: "a",
+ * 	y: "b",
+ * 	value: "r",
+ * 	ramp: "rdbu",
+ * 	rampMidpoint: 0,
+ * 	cluster: true,
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const heatmap: import("@sophistry/core").Definition<HeatmapProps<any>, import("@sophistry/core/internal").CompositeNode<HeatmapProps<any>>, keyof HeatmapProps<any>>;

package/dist/grids/hex-bin.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `hexBin`: hexagonal binning, drawn as one path batch. The hexagons are
+ * regular in data units, so under unequal axis scales (or a log axis) their
+ * scene outlines differ in shape: a path batch (one outline per item) rather
+ * than polygon instances, which only scale uniformly.
+ */
+import type { ColorRampSpec } from "@sophistry/core";
+import type { Point } from "@sophistry/core/geometry";
+import type { RampScaleProps } from "../color-norm.js";
+import type { Channel } from "../data/channels.js";
+/**
+ * Props of {@link hexBin}.
+ *
+ * @category Charts
+ */
+export interface HexBinProps<T = unknown> {
+    /** One observation per datum; data with a non-finite `x` or `y` are dropped. */
+    data: readonly T[];
+    /** X position, in data units. */
+    x: Channel<T, number>;
+    /** Y position, in data units. */
+    y: Channel<T, number>;
+    /**
+     * Hex centre-to-corner distance in data units, on both axes (see {@link hexbin}). Required: no
+     * default fits every axis scale.
+     */
+    radius: number;
+    /**
+     * Low-to-high count ramp: a colormap name, CSS stops or function. Defaults to the theme's ramp.
+     */
+    ramp?: ColorRampSpec;
+    /**
+     * Fraction of the reveal spent staggering the cells in reading order, 0..0.95. Defaults to 0.5
+     * (0 above 2000 cells).
+     */
+    stagger?: number;
+    /**
+     * How counts spread over the ramp: `"log"` (from the emptiest drawn cell), `"sqrt"` or
+     * `"symlog"` (from 0).
+     * @default "linear"
+     */
+    rampScale?: RampScaleProps["rampScale"];
+    /**
+     * The count at the ramp's low end. Under `rampScale="log"`, give a value below the emptiest
+     * cell (say 0.5) to lift every drawn cell off the floor. Defaults to 0 (the emptiest drawn
+     * cell's count under `"log"`).
+     */
+    rampMin?: number;
+    /** The count at the ramp's high end. Defaults to the fullest cell's. */
+    rampMax?: number;
+    /** Hexagon outline. @default "none" */
+    stroke?: string;
+    /** Outline width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Fill opacity 0..1, on top of `opacity`. @default 1 */
+    fillOpacity?: number;
+    /** Reveal 0..1: hexagons fade in in reading order, top row first. @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 hexagons. */
+    visible?: boolean;
+}
+/**
+ * The six corners of a pointy-top hexagon in data space, matching the `hexbin()` grid.
+ *
+ * @internal
+ */
+export declare function hexCorners(cx: number, cy: number, radius: number): Point[];
+/**
+ * A hexagonal binning heatmap: points binned into a hex grid in data space, one filled hexagon
+ * per occupied cell coloured by its count. With unequal axis scales the hexagons stretch. Paints
+ * under the axes by default (`zIndex` `UNDER_AXES_Z_INDEX`). Inside a `chart` or `axes`; drawn
+ * as one path batch. See {@link hexbin} for the binning alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, hexBin } from "@sophistry/charts";
+ *
+ * const points = Array.from({ length: 200 }, (_, i) => ({ x: Math.sin(i) * 3, y: Math.cos(i * 0.7) * 2 }));
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	children: [hexBin.create({ data: points, x: "x", y: "y", radius: 0.4, ramp: "magma" })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const hexBin: import("@sophistry/core").Definition<HexBinProps<any>, import("@sophistry/core/internal").CompositeNode<HexBinProps<any>>, keyof HexBinProps<any>>;

package/dist/grids/hist2d.d.ts

@@ -0,0 +1,107 @@
+/**
+ * `hist2d`: a 2D histogram, drawn as one instances node of `rect`s (see
+ * `cell-rects.ts`). Nonempty cells fade in in reading order.
+ */
+import type { ColorRampSpec } from "@sophistry/core";
+import type { Range } from "@sophistry/core/geometry";
+import type { MarkTransition } from "../batch.js";
+import type { RampScaleProps } from "../color-norm.js";
+import type { Channel } from "../data/channels.js";
+/**
+ * Props of {@link hist2d}.
+ *
+ * @category Charts
+ */
+export interface Hist2DProps<T = unknown> {
+    /** One observation per datum; data with a non-finite `x` or `y` are dropped. */
+    data: readonly T[];
+    /** X position, in data units. */
+    x: Channel<T, number>;
+    /** Y position, in data units. */
+    y: Channel<T, number>;
+    /**
+     * Number of equal-width bins along x. Wins over an `xRange` step. Defaults to the count the
+     * step implies, else 10.
+     */
+    xBins?: number;
+    /**
+     * Number of equal-width bins along y. Wins over a `yRange` step. Defaults to the count the step
+     * implies, else 10.
+     */
+    yBins?: number;
+    /**
+     * `[min, max, step?]` spanned by the x bins, in data units; `step` is the bin width when
+     * `xBins` is not given. Defaults to the finite extent of the x values.
+     */
+    xRange?: Range;
+    /**
+     * `[min, max, step?]` spanned by the y bins, in data units; `step` is the bin width when
+     * `yBins` is not given. Defaults to the finite extent of the y values.
+     */
+    yRange?: Range;
+    /**
+     * Colour ramp (colormap name, CSS stops or function) sampled by each cell's count relative to
+     * the largest. Defaults to the theme's ramp (background to first series colour).
+     */
+    ramp?: ColorRampSpec;
+    /**
+     * Fraction of the reveal spent staggering the cells in reading order, 0..0.95. Defaults to 0.5
+     * (0 above 2000 cells).
+     */
+    stagger?: number;
+    /**
+     * How counts spread over the ramp: `"log"` (from the emptiest drawn cell), `"sqrt"` or
+     * `"symlog"` (from 0).
+     * @default "linear"
+     */
+    rampScale?: RampScaleProps["rampScale"];
+    /**
+     * The count at the ramp's low end. Under `rampScale="log"`, give a value below the emptiest
+     * cell (say 0.5) to lift every drawn cell off the floor. Defaults to 0 (the emptiest drawn
+     * cell's count under `"log"`).
+     */
+    rampMin?: number;
+    /** The count at the ramp's high end. Defaults to the fullest cell's. */
+    rampMax?: number;
+    /**
+     * How cells change colour when `data` changes: a tween or a spring; new
+     * cells fade in, emptied ones fade out. Omitted, changes are instant.
+     */
+    transition?: MarkTransition;
+    /** Cell outline. @default "none" */
+    stroke?: string;
+    /** Outline width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Fill opacity 0..1, on top of `opacity`. @default 1 */
+    fillOpacity?: number;
+    /** Reveal 0..1: cells fade in in reading order, top row first. @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 cells. */
+    visible?: boolean;
+}
+/**
+ * A 2D histogram: points bucketed into a grid of equal-width cells, each nonempty cell coloured
+ * by its count. Empty cells are not drawn. Paints under the axes by default (`zIndex`
+ * `UNDER_AXES_Z_INDEX`). Inside a `chart` or `axes`; drawn as one instances node of
+ * rectangles. See {@link histogram2d} for the binning alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, hist2d } from "@sophistry/charts";
+ *
+ * const points = Array.from({ length: 200 }, (_, i) => ({ x: Math.sin(i) * 3, y: Math.cos(i * 0.7) * 2 }));
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	children: [hist2d.create({ data: points, x: "x", y: "y", xBins: 20, yBins: 12 })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const hist2d: import("@sophistry/core").Definition<Hist2DProps<any>, import("@sophistry/core/internal").CompositeNode<Hist2DProps<any>>, keyof Hist2DProps<any>>;

package/dist/grids/imshow.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `imshow`: a 2D array as one image node. The colours go through a 256-step
+ * lookup table of the ramp (`raster.ts`), so a million cells are a million
+ * table reads and one bitmap the camera moves for free.
+ *
+ * The reading-order fade stays: while a staggered reveal runs, each pixel's
+ * alpha is its cell's share of the fade (the stagger drops to 0 above 2,000
+ * cells, so this only rewrites small images per frame). Under a non-linear
+ * axis, where an image would put cells in the wrong places, or with a cell
+ * `stroke`, the cells are drawn as one instances node of `rect`s instead.
+ */
+import type { ColorRampSpec } from "@sophistry/core";
+import type { Range } from "@sophistry/core/geometry";
+import type { RampScaleProps } from "../color-norm.js";
+/**
+ * Props of {@link imshow}.
+ *
+ * @category Charts
+ */
+export interface ImshowProps extends RampScaleProps {
+    /** Rows × columns of values; ragged rows are tolerated. */
+    values: readonly (readonly number[])[];
+    /** `[min, max]` in data units the columns span. Defaults to `[0, ncols]`. */
+    xRange?: Range;
+    /** `[min, max]` in data units the rows span. Defaults to `[0, nrows]`. */
+    yRange?: Range;
+    /**
+     * Which edge row 0 sits on: `"upper"` (top) or `"lower"` (bottom).
+     * @default "upper"
+     */
+    rowOrigin?: "upper" | "lower";
+    /**
+     * Colour ramp sampled by each cell's value between `rampMin` and `rampMax`: CSS stops, a
+     * colormap name (`"viridis"`), or `(t) => colour`. Defaults to the theme's ramp (background to
+     * first series colour).
+     */
+    ramp?: ColorRampSpec;
+    /** Value at the bottom of the ramp. Defaults to the finite minimum of `values`. */
+    rampMin?: number;
+    /** Value at the top of the ramp. Defaults to the finite maximum of `values`. */
+    rampMax?: number;
+    /**
+     * Fraction of the reveal spent staggering the cells in reading order, 0..0.95. Defaults to 0.5
+     * (0 above 2000 cells).
+     */
+    stagger?: number;
+    /** Interpolate between pixels when magnified. @default false */
+    smoothing?: boolean;
+    /** Cell outline; given, the cells are drawn as rectangles rather than an image. */
+    stroke?: string;
+    /** Outline width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Reveal 0..1: cells fade in in reading order, top row first. @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 image. */
+    visible?: boolean;
+}
+/**
+ * A 2D array as an image: equal-sized cells over `xRange` × `yRange`, each finite value
+ * coloured on a ramp. Use {@link pcolormesh} for uneven cell coordinates. Paints under the
+ * axes by default (`zIndex` `UNDER_AXES_Z_INDEX`). Inside a `chart` or `axes`. Drawn as one
+ * image node (cells as rectangles under a non-linear axis or with a `stroke`). See
+ * {@link imshowCells}.
+ *
+ * @example
+ * ```ts
+ * import { chart, imshow } from "@sophistry/charts";
+ *
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	colorbar: true,
+ * 	children: [imshow.create({ values: [[0, 1, 2], [3, 4, 5]], ramp: "viridis" })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const imshow: import("@sophistry/core").Definition<ImshowProps, import("@sophistry/core/internal").CompositeNode<ImshowProps>, keyof ImshowProps>;

package/dist/grids/index.d.ts

@@ -0,0 +1,26 @@
+/** Family barrel: grids. Owned by its family; re-exported from the package entry. */
+export type { BarbsProps } from "./barbs.js";
+export { barbs } from "./barbs.js";
+export type { CellsProps } from "./cells.js";
+export { cells } from "./cells.js";
+export type { ContourProps } from "./contour.js";
+export { contour } from "./contour.js";
+export type { ContourFProps } from "./contour-f.js";
+export { contourF } from "./contour-f.js";
+export type { DendrogramProps } from "./dendrogram.js";
+export { dendrogram } from "./dendrogram.js";
+export type { HeatmapProps } from "./heatmap.js";
+export { heatmap } from "./heatmap.js";
+export type { HexBinProps } from "./hex-bin.js";
+export { hexBin } from "./hex-bin.js";
+export type { Hist2DProps } from "./hist2d.js";
+export { hist2d } from "./hist2d.js";
+export type { ImshowProps } from "./imshow.js";
+export { imshow } from "./imshow.js";
+export type { PcolormeshProps } from "./pcolormesh.js";
+export { pcolormesh } from "./pcolormesh.js";
+export type { TriContourFProps, TriContourProps } from "./tri-contour.js";
+export { triContour, triContourF } from "./tri-contour.js";
+export type { TriChartBaseProps } from "./tri-shared.js";
+export type { TripcolorProps } from "./tripcolor.js";
+export { tripcolor } from "./tripcolor.js";

package/dist/grids/pcolormesh.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `pcolormesh`: a coloured mesh over a rectilinear grid, drawn as one
+ * instances node of `rect`s (see `cell-rects.ts`). Cells fade in in reading
+ * order (`stagger`, dropped above 2,000 cells), through each item's opacity.
+ */
+import type { ColorRampSpec } from "@sophistry/core";
+import type { MarkTransition } from "../batch.js";
+import type { RampScaleProps } from "../color-norm.js";
+import type { PcolormeshCell } from "../math/pcolormesh.js";
+import type { CellItem } from "./cell-rects.js";
+import { cellBox } from "./cell-rects.js";
+import type { RampCells } from "./ramp-cells.js";
+/**
+ * Props of {@link pcolormesh}.
+ *
+ * @category Charts
+ */
+export interface PcolormeshProps extends RampScaleProps {
+    /** `ncols` centres or `ncols + 1` edges of the columns, in data units. */
+    xs: readonly number[];
+    /** `nrows` centres or `nrows + 1` edges of the rows, in data units. */
+    ys: readonly number[];
+    /** Rows × columns of values; ragged rows are tolerated. */
+    values: readonly (readonly number[])[];
+    /**
+     * Colour ramp sampled by each cell's value between `rampMin` and `rampMax`: CSS stops, a
+     * colormap name, or `(t) => colour`. Defaults to the theme's ramp (background to first series
+     * colour).
+     */
+    ramp?: ColorRampSpec;
+    /** Value at the bottom of the ramp. Defaults to the finite minimum of `values`. */
+    rampMin?: number;
+    /** Value at the top of the ramp. Defaults to the finite maximum of `values`. */
+    rampMax?: number;
+    /**
+     * Fraction of the reveal spent staggering the cells in reading order, 0..0.95. Defaults to 0.5
+     * (0 above 2000 cells).
+     */
+    stagger?: number;
+    /**
+     * How cells change colour when `values` changes: a tween or a spring in the
+     * node's tween bank; new cells fade in, removed ones fade out. Omitted,
+     * changes are instant.
+     */
+    transition?: MarkTransition;
+    /** Cell outline. @default "none" */
+    stroke?: string;
+    /** Outline width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Fill opacity 0..1, on top of `opacity`. @default 1 */
+    fillOpacity?: number;
+    /** Reveal 0..1: cells fade in in reading order, top row first. @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 mesh. */
+    visible?: boolean;
+}
+/** Each drawn cell's box and colour, for one fit of the axes. */
+export declare function placeGridCells(grid: RampCells<PcolormeshCell>, coords: Parameters<typeof cellBox>[0], bleed?: number): CellItem[];
+/**
+ * The placed cells at this frame of the reveal: each with the layer's
+ * `opacity` and its share of the reveal as its `progress`.
+ */
+export declare function revealCells(placed: readonly CellItem[], grid: Pick<RampCells<unknown>, "revealOf">, opacity: number | undefined): CellItem[];
+/**
+ * A coloured mesh over a rectilinear grid: `xs`/`ys` are per-axis centres or edges (uneven
+ * spacing allowed), `values` the cell values, each finite cell coloured on a ramp. Throws if
+ * `xs` or `ys` has the wrong length. Paints under the axes by default (`zIndex`
+ * `UNDER_AXES_Z_INDEX`). Inside a `chart` or `axes`. Drawn as one instances node of
+ * rectangles. See {@link pcolormeshCells}.
+ *
+ * @example
+ * ```ts
+ * import { chart, pcolormesh } from "@sophistry/charts";
+ *
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	colorbar: true,
+ * 	children: [pcolormesh.create({ xs: [0, 1, 3], ys: [0, 2], values: [[1, 2]], ramp: "viridis" })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const pcolormesh: import("@sophistry/core").Definition<PcolormeshProps, import("@sophistry/core/internal").CompositeNode<PcolormeshProps>, keyof PcolormeshProps>;

package/dist/grids/ramp-cells.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The plumbing the gridded colour layers share (`imshow`, `pcolormesh`,
+ * `hist2d`, `hexBin`): a colormap and norm over the cells' values, the
+ * layer's report to its chart (with its colour-bar ramp), and the cells'
+ * reading-order fade. Internal to the charts.
+ *
+ * Each piece is a factory called once in `setup` that returns a function to
+ * call in every `update`. Each step sits
+ * behind a last-input cache, so a frame of a reveal recomputes the fade and
+ * nothing else, and the colormap and norm keep their identity (the chart
+ * compares reports by value, colormaps and scales by identity).
+ */
+import type { ColorRampSpec, CoordinateSystem } from "@sophistry/core";
+import type { Colormap, Theme } from "@sophistry/core/themes";
+import type { ColorNorm, RampScaleOptions } from "../color-norm.js";
+import type { ChartLayer } from "../context.js";
+import type { ChartLayerExtent } from "../frame/types.js";
+/** What {@link createRampCells}'s function takes on each update. */
+export interface RampCellsSpec<C> {
+    layer: ChartLayer;
+    coords: CoordinateSystem;
+    theme: Theme;
+    ramp: ColorRampSpec | undefined;
+    /** Every cell, drawn or not; keep the same array while nothing changed. */
+    cells: readonly C[];
+    value: (cell: C) => number;
+    /** A cell's place for reading order (any point its row shares). */
+    at: (cell: C) => {
+        x: number;
+        y: number;
+    };
+    norm: RampScaleOptions;
+    /** The values the norm's automatic range reads (same array while unchanged); defaults to every cell's value. */
+    domain?: readonly number[];
+    /** The layer's report, less `covers` and `ramp`. */
+    extent: Omit<ChartLayerExtent, "ramp" | "covers">;
+    stagger: number | undefined;
+    /** The layer's own `progress`, before the chart's data phase. */
+    progress: number | undefined;
+}
+/** What {@link createRampCells}'s function hands back. */
+export interface RampCells<C> {
+    /** The cells to draw: those whose value has a place on the norm (finite; positive under `"log"`). */
+    cells: readonly C[];
+    /** A drawn cell's colour. */
+    fill(cell: C): string;
+    /** A value's place on the norm, 0..1 (non-finite when it has none). */
+    unitOf(value: number): number;
+    /** The ramp's colour at a place on the norm, 0..1. */
+    colorAt(unit: number): string;
+    /** The colormap, kept while the ramp and theme are. */
+    colormap: Colormap;
+    /** The norm, kept while the values and norm props are. */
+    norm: ColorNorm;
+    /** The layer's reveal, scaled by the chart's data phase (undefined outside a chart without `progress`). */
+    progress: number | undefined;
+    /** Whether the cells fade one after another (a stagger over more than one cell). */
+    staggered: boolean;
+    /** The `i`th drawn cell's reveal: its share of the reading-order fade when staggered. */
+    revealOf(i: number): number | undefined;
+}
+/**
+ * A gridded colour layer's cells, colours, report and fade. Call once, in
+ * `setup`; call the result in each `update` (it reports to the chart).
+ */
+export declare function createRampCells<C>(): (spec: RampCellsSpec<C>) => RampCells<C>;