@sophistry/charts 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,67 @@
+/**
+ * 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";
+import type { ChartLayer } from "../context";
+import type { ChartLayerExtent } from "../frame/types";
+/** 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>;
+//# sourceMappingURL=ramp-cells.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ramp-cells.d.ts","sourceRoot":"","sources":["../../src/grids/ramp-cells.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAc,MAAM,gBAAgB,CAAC;AAInE,oEAAoE;AACpE,MAAM,WAAW,aAAa,CAAC,CAAC;IAC/B,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,aAAa,GAAG,SAAS,CAAC;IAChC,2EAA2E;IAC3E,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IACpB,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IAC3B,mEAAmE;IACnE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,IAAI,EAAE,gBAAgB,CAAC;IACvB,gHAAgH;IAChH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,oDAAoD;IACpD,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;IAClD,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,0DAA0D;AAC1D,MAAM,WAAW,SAAS,CAAC,CAAC;IAC3B,qGAAqG;IACrG,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IACpB,6BAA6B;IAC7B,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IACtB,uEAAuE;IACvE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,sDAAsD;IACtD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,uDAAuD;IACvD,QAAQ,EAAE,QAAQ,CAAC;IACnB,0DAA0D;IAC1D,IAAI,EAAE,SAAS,CAAC;IAChB,2GAA2G;IAC3G,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB,yFAAyF;IACzF,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,CAuE7E"}

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

@@ -0,0 +1,121 @@
+/**
+ * `triContour` and `triContourF`: iso-lines and filled bands of a field
+ * sampled at scattered points, each drawn as one path batch. Lines draw
+ * along their length level by level, bands fade in, lowest first.
+ */
+import type { ColorRampSpec } from "@sophistry/core";
+import type { RampScaleProps } from "../color-norm";
+import type { TriChartBaseProps } from "./tri-shared";
+/**
+ * Props of {@link triContour}.
+ *
+ * @category Charts
+ */
+export interface TriContourProps<T = unknown> extends TriChartBaseProps<T>, RampScaleProps {
+    /**
+     * 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 data's min and
+     * max: a colormap name, CSS stops or `(t) => colour`. Defaults to two theme series colours.
+     */
+    ramp?: ColorRampSpec;
+    /** One colour for every line, instead of the ramp. */
+    stroke?: string;
+    /** Line width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the lines. */
+    visible?: boolean;
+}
+/**
+ * Props of {@link triContourF}.
+ *
+ * @category Charts
+ */
+export interface TriContourFProps<T = unknown> extends TriChartBaseProps<T>, RampScaleProps {
+    /**
+     * 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 data's min and max.
+     * Defaults to two theme series colours.
+     */
+    ramp?: ColorRampSpec;
+    /** 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;
+    /** 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;
+}
+/**
+ * Iso-lines of a field sampled at scattered points: the points are triangulated (Delaunay, or
+ * your own `triangles`) and each level traced across the mesh. Revealed level by level, lowest
+ * first, each line along its length. Inside a `chart` or `axes`; drawn as one path batch. For
+ * gridded data use `contour`; for filled bands `triContourF`. See {@link tricontourLines} for
+ * the geometry alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, triContour } from "@sophistry/charts";
+ *
+ * const samples = Array.from({ length: 40 }, (_, i) => {
+ * 	const x = Math.cos(i * 2.4) * (i / 10);
+ * 	const y = Math.sin(i * 2.4) * (i / 10);
+ * 	return { x, y, v: x * y };
+ * });
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	children: [triContour.create({ data: samples, x: "x", y: "y", value: "v", levels: 6 })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const triContour: import("@sophistry/core").Definition<TriContourProps<any>, import("@sophistry/core/internal").CompositeNode<TriContourProps<any>>, keyof TriContourProps<any>>;
+/**
+ * Filled contours over scattered points: each triangle clipped into the bands between
+ * consecutive levels, one band an item, fading in lowest first. Paints under the axes by
+ * default (`zIndex` `UNDER_AXES_Z_INDEX`) and feeds a chart's `colorbar`. Drawn as one path
+ * batch. See {@link tricontourBands} for the geometry alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, triContourF } from "@sophistry/charts";
+ *
+ * const samples = Array.from({ length: 40 }, (_, i) => {
+ * 	const x = Math.cos(i * 2.4) * (i / 10);
+ * 	const y = Math.sin(i * 2.4) * (i / 10);
+ * 	return { x, y, v: x * y };
+ * });
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	colorbar: true,
+ * 	children: [triContourF.create({ data: samples, x: "x", y: "y", value: "v", ramp: "viridis" })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const triContourF: import("@sophistry/core").Definition<TriContourFProps<any>, import("@sophistry/core/internal").CompositeNode<TriContourFProps<any>>, keyof TriContourFProps<any>>;
+//# sourceMappingURL=tri-contour.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tri-contour.d.ts","sourceRoot":"","sources":["../../src/grids/tri-contour.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,aAAa,EAKb,MAAM,iBAAiB,CAAC;AAOzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAsBpD,OAAO,KAAK,EAAE,iBAAiB,EAAa,MAAM,cAAc,CAAC;AAKjE;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO,CAC3C,SAAQ,iBAAiB,CAAC,CAAC,CAAC,EAC3B,cAAc;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,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,mBAAmB;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO,CAC5C,SAAQ,iBAAiB,CAAC,CAAC,CAAC,EAC3B,cAAc;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,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,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAoMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,UAAU,gKAQrB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,WAAW,mKAQtB,CAAC"}

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

@@ -0,0 +1,62 @@
+/**
+ * Shared props and helpers of the unstructured-grid charts (`tripcolor`,
+ * `triContour`, `triContourF`), and the level ranks the grid contours share
+ * with them. Only the props type is public.
+ */
+import type { Channel, DateSink } from "../data/channels";
+import type { TriangleIndices } from "../math/tricontour";
+/**
+ * Props every tri-chart shares: one datum per point with its position and
+ * value, and optionally the triangles joining the points.
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export interface TriChartBaseProps<T> {
+    /** The sample points: one datum each. */
+    data: readonly T[];
+    /** The point's x, in data units: a key of `T` or `(d, i) => number`. */
+    x: Channel<T, number>;
+    /** The point's y, in data units: a key of `T` or `(d, i) => number`. */
+    y: Channel<T, number>;
+    /** The value sampled at the point. A triangle touching a non-finite value is left out. */
+    value: Channel<T, number>;
+    /**
+     * The mesh, as index triples into `data` (either winding); give your own to
+     * leave holes or follow a non-convex outline. An index past `data` throws.
+     * Omitted, the points are Delaunay-triangulated.
+     */
+    triangles?: readonly TriangleIndices[];
+    /** Reveal, 0..1; each chart documents its own animation. @default 1 */
+    progress?: number;
+    /** Fraction of the reveal spent staggering, 0..0.95. @default 0.5 */
+    stagger?: number;
+}
+/** A tri-chart's points as plain arrays. */
+export interface TriPoints {
+    xs: number[];
+    ys: number[];
+    zs: number[];
+}
+/**
+ * The points as plain arrays.
+ *
+ * @internal
+ */
+export declare function triPoints<T>(props: Pick<TriChartBaseProps<T>, "data" | "x" | "y" | "value">, dates: DateSink | null): TriPoints;
+/**
+ * The finite `[min, max]` of `values`, or `[0, 1]` when there is none.
+ *
+ * @internal
+ */
+export declare function valueExtent(values: readonly number[]): [number, number];
+/** Each level's place in ascending order (contours reveal lowest first), by level value. @internal */
+export declare function levelRanks(levels: readonly number[]): Map<number, number>;
+/**
+ * One item's share of a staggered reveal, or the whole `progress` when
+ * there is only one item.
+ *
+ * @internal
+ */
+export declare function triReveal(progress: number | undefined, rank: number, count: number, stagger: number | undefined): number;
+//# sourceMappingURL=tri-shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tri-shared.d.ts","sourceRoot":"","sources":["../../src/grids/tri-shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IACnC,yCAAyC;IACzC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IACnB,wEAAwE;IACxE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACtB,wEAAwE;IACxE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACtB,0FAA0F;IAC1F,KAAK,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACvC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,EAAE,EAAE,MAAM,EAAE,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAC1B,KAAK,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC,EAC/D,KAAK,EAAE,QAAQ,GAAG,IAAI,GACpB,SAAS,CAMX;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CASvE;AAED,sGAAsG;AACtG,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAGzE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACxB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,CAER"}

package/dist/grids/tripcolor.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `tripcolor`: a pseudocolour plot over scattered points, drawn as one path
+ * batch (one closed triangle per face). Faces fade in as a diagonal wave
+ * from the top-left; tooltips resolve per face through `event.item`.
+ */
+import type { ColorRampSpec } from "@sophistry/core";
+import type { RampScaleProps } from "../color-norm";
+import type { TooltipSpec } from "../tooltip";
+import type { TriChartBaseProps } from "./tri-shared";
+/**
+ * Props of {@link tripcolor}.
+ *
+ * @category Charts
+ */
+export interface TripcolorProps<T = unknown> extends TriChartBaseProps<T>, RampScaleProps {
+    /**
+     * How a face's 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 face value. */
+    rampMin?: number;
+    /** Value at the top of the ramp. Defaults to the largest face value. */
+    rampMax?: number;
+    /** Outline of every triangle, to show the mesh. Defaults to none. */
+    stroke?: string;
+    /** Width of the mesh outline. */
+    strokeWidth?: number;
+    /**
+     * Opacity of the faces, 0..1.
+     * @default 1
+     */
+    opacity?: number;
+    /**
+     * Hover tooltip: `true` for the face's value, or `(d, i) => string` given the face's first
+     * corner.
+     */
+    tooltip?: TooltipSpec<T>;
+    /**
+     * Paint order; higher draws later. Defaults to `UNDER_AXES_Z_INDEX` (above the grid, under the
+     * axes).
+     */
+    zIndex?: number;
+    /** Set to false to hide the faces. */
+    visible?: boolean;
+}
+/**
+ * A pseudocolour plot over scattered points: the points are triangulated (Delaunay, or your own
+ * `triangles`) and each triangle filled with the mean of its corners' values. `stroke` outlines
+ * the mesh. Reveals as a diagonal wave from the top-left. Inside a `chart` or `axes`; drawn as
+ * one path batch. See {@link tripcolorFaces} for the faces alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, tripcolor } from "@sophistry/charts";
+ *
+ * const samples = [
+ * 	{ x: 0, y: 0, v: 1 },
+ * 	{ x: 1, y: 0, v: 3 },
+ * 	{ x: 0, y: 1, v: 2 },
+ * 	{ x: 1, y: 1, v: 5 },
+ * ];
+ * chart.create({
+ * 	width: 6,
+ * 	height: 4,
+ * 	children: [tripcolor.create({ data: samples, x: "x", y: "y", value: "v", tooltip: true })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#heatmaps-and-contours
+ * @category Charts
+ */
+export declare const tripcolor: import("@sophistry/core").Definition<TripcolorProps<any>, import("@sophistry/core/internal").CompositeNode<TripcolorProps<any>>, keyof TripcolorProps<any>>;
+//# sourceMappingURL=tripcolor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tripcolor.d.ts","sourceRoot":"","sources":["../../src/grids/tripcolor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,aAAa,EAMb,MAAM,iBAAiB,CAAC;AAUzB,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,eAAe,CAAC;AAW/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,OAAO,KAAK,EAAE,iBAAiB,EAAa,MAAM,cAAc,CAAC;AAGjE;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO,CAC1C,SAAQ,iBAAiB,CAAC,CAAC,CAAC,EAC3B,cAAc;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAiLD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,SAAS,6JAmCpB,CAAC"}

package/dist/guides/colorbar.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `colorbar`: a ramp legend, a bar shaded low to high with ticks and numbers.
+ *
+ * The bar, each tick's line and number (keyed by value) and the title are
+ * kept across updates and hidden with `visible: false` when not shown; the ticks are recomputed only when the domain, scale or
+ * formatting change, the gradient only when the ramp or orientation do.
+ */
+import type { Colormap, ColorRampSpec } from "@sophistry/core";
+import type { Point, ScaleSpec, TickFormatterSpec } from "@sophistry/core/geometry";
+/**
+ * Props for {@link colorbar}.
+ *
+ * @category Charts
+ */
+export interface ColorbarProps {
+    /** The value range the colours span, `[low, high]`: low at the bar's start. */
+    domain: readonly [number, number];
+    /**
+     * The ramp: a colormap name (`"viridis"`), CSS stops, or `(t) => colour`. Defaults to the
+     * theme's ramp.
+     */
+    ramp?: ColorRampSpec | Colormap;
+    /** The bar's bottom-left corner (vertical) or top-left (horizontal). */
+    at: Point;
+    /**
+     * `"vertical"`: low at the bottom, numbers on the right. `"horizontal"`: low on the left,
+     * numbers below.
+     * @default "vertical"
+     */
+    orientation?: "vertical" | "horizontal";
+    /**
+     * Length of the bar along its values.
+     * @default 3
+     */
+    length?: number;
+    /**
+     * Thickness of the bar.
+     * @default 0.22
+     */
+    thickness?: number;
+    /** A title above the bar (vertical) or beside it (horizontal). */
+    label?: string;
+    /**
+     * How values map along the bar, as on an axis: `"linear"`, `"log"`, `"sqrt"`, `"symlog"`, or
+     * your own {@link Scale}. Ticks follow it; colour the data with the same scale.
+     * @default "linear"
+     */
+    scale?: ScaleSpec;
+    /**
+     * The log base when `scale` is `"log"`.
+     * @default 10
+     */
+    base?: number;
+    /**
+     * A diverging centre: this value sits mid-bar, each half through `scale`. Colour the data with
+     * the same `rampMidpoint`.
+     */
+    midpoint?: number;
+    /**
+     * How a tick's number is written, as on an axis: a function, a built-in name (`"si"`,
+     * `"percent"`, ...) or a format string (`",.1f"`). Defaults to the axes' formatting.
+     */
+    tickFormat?: TickFormatterSpec;
+    /**
+     * Target number of ticks.
+     * @default 5
+     */
+    ticks?: number;
+    /**
+     * Font size of the numbers and the title.
+     * @default 0.24
+     */
+    fontSize?: number;
+    /**
+     * Reveal, 0..1: the bar fades in, then its numbers.
+     * @default 1
+     */
+    progress?: number;
+    /** Paint order; higher draws later. */
+    zIndex?: number;
+    /** Set to `false` to hide the colour bar. */
+    visible?: boolean;
+}
+/**
+ * How wide a vertical {@link colorbar} is: the bar, its ticks and its widest number (or title).
+ *
+ * @internal
+ */
+export declare function colorbarWidth(props: Pick<ColorbarProps, "domain" | "scale" | "base" | "midpoint" | "thickness" | "label" | "tickFormat" | "ticks" | "fontSize">, fontFamily: string): number;
+/**
+ * A ramp legend: a bar shaded low to high with ticks and numbers, saying what each colour
+ * stands for. `chart` with `colorbar` draws one for its value-coloured layers; use this
+ * directly anywhere else.
+ *
+ * @example
+ * ```ts
+ * import { colorbar } from "@sophistry/charts";
+ *
+ * colorbar.create({
+ * 	at: { x: 4, y: -1.5 },
+ * 	domain: [0, 100],
+ * 	ramp: "viridis",
+ * 	label: "Density",
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/guides/charts/#color
+ * @category Charts
+ */
+export declare const colorbar: import("@sophistry/core").Definition<ColorbarProps, import("@sophistry/core/internal").CompositeNode<ColorbarProps>, keyof ColorbarProps>;
+//# sourceMappingURL=colorbar.d.ts.map

package/dist/guides/colorbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colorbar.d.ts","sourceRoot":"","sources":["../../src/guides/colorbar.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACX,QAAQ,EACR,aAAa,EAOb,MAAM,iBAAiB,CAAC;AAUzB,OAAO,KAAK,EAEX,KAAK,EAEL,SAAS,EAET,iBAAiB,EACjB,MAAM,0BAA0B,CAAC;AAyBlC;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,+EAA+E;IAC/E,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,GAAG,QAAQ,CAAC;IAChC,wEAAwE;IACxE,EAAE,EAAE,KAAK,CAAC;IACV;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IACxC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AA0DD;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,IAAI,CACV,aAAa,EACX,QAAQ,GACR,OAAO,GACP,MAAM,GACN,UAAU,GACV,WAAW,GACX,OAAO,GACP,YAAY,GACZ,OAAO,GACP,UAAU,CACZ,EACD,UAAU,EAAE,MAAM,GAChB,MAAM,CAqBR;AAqBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,2IAkCnB,CAAC"}

package/dist/guides/index.d.ts

@@ -0,0 +1,12 @@
+/** Family barrel: guides. Owned by its family; re-exported from the package entry. */
+export type { SecondaryXProps, SecondaryYProps, } from "../frame/secondary-axes";
+export { secondaryX, secondaryY } from "../frame/secondary-axes";
+export type { TooltipOverlayProps } from "../frame/tooltip-overlay";
+export { layoutTooltip, tooltipOverlay } from "../frame/tooltip-overlay";
+export type { ColorbarProps } from "./colorbar";
+export { colorbar } from "./colorbar";
+export type { LegendEntry, LegendProps, LegendTransition } from "./legend";
+export { legend } from "./legend";
+export type { SizeLegendProps, SizeLegendTransition } from "./size-legend";
+export { sizeLegend } from "./size-legend";
+//# sourceMappingURL=index.d.ts.map

package/dist/guides/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guides/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAGtF,YAAY,EACX,eAAe,EACf,eAAe,GACf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACzE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/guides/legend.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `legend`: a key to a chart's colours, a swatch and a name per entry.
+ *
+ * The nodes of an entry are kept for as long as the entry is listed (keyed
+ * by its `key`, else its label) and hidden with `visible: false` when
+ * not listed; the layout is measured once per change of the
+ * entries, title or font, not as `progress` or a transition's stages move.
+ */
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey, Point } from "@sophistry/core/geometry";
+import type { LegendMark } from "../frame/types";
+import type { LegendLayout } from "../math/legend";
+/**
+ * One legend entry.
+ *
+ * @category Charts
+ */
+export interface LegendEntry {
+    /** The category this entry stands for, if any. */
+    key?: BandKey;
+    /** The entry's text. */
+    label: string;
+    /** The swatch's colour. */
+    color: ColorInput;
+    /** The swatch's shape. Defaults to a filled square. */
+    mark?: LegendMark;
+}
+/**
+ * A legend's keyed transition: the entries each end lists, and how far each stage has got.
+ * `chart` passes one while a keyed transition runs.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+ * @category Charts
+ */
+export interface LegendTransition {
+    /** The keys of the entries listed at the start. An entry without a key is at both ends. */
+    from: readonly BandKey[];
+    /** The keys of the entries listed at the end. */
+    to: readonly BandKey[];
+    /** Progress of the exit stage, 0..1. */
+    exit: number;
+    /** Progress of the update stage, 0..1. */
+    update: number;
+    /** Progress of the enter stage, 0..1. */
+    enter: number;
+}
+/**
+ * Props for {@link legend}.
+ *
+ * @category Charts
+ */
+export interface LegendProps {
+    /** The entries, in order. */
+    entries: readonly LegendEntry[];
+    /** The legend's top-left corner, in scene units. */
+    at: Point;
+    /**
+     * `"column"`: one entry per row. `"row"`: side by side, wrapping at `maxWidth`.
+     * @default "column"
+     */
+    direction?: "column" | "row";
+    /** With `direction: "row"`: wrap before an entry that would run past this width. */
+    maxWidth?: number;
+    /** A title line above the entries. */
+    title?: string;
+    /**
+     * Font size of the labels.
+     * @default 0.28
+     */
+    fontSize?: number;
+    /**
+     * Reveal, 0..1: the entries fade in one after another.
+     * @default 1
+     */
+    progress?: number;
+    /** A keyed data transition in progress. See {@link LegendTransition}. */
+    transition?: LegendTransition;
+    /** Paint order; higher draws later. */
+    zIndex?: number;
+    /** Set to `false` to hide the legend. */
+    visible?: boolean;
+}
+/** Measurement options shared by {@link legend} and the frames that place one. */
+export interface LegendMetrics {
+    direction?: "column" | "row";
+    maxWidth?: number;
+    title?: string;
+    fontSize?: number;
+    fontFamily: string;
+}
+/**
+ * Lays a legend out, its labels measured with the theme's font and swatches sized to it.
+ *
+ * @internal
+ */
+export declare function measureLegend(entries: readonly LegendEntry[], metrics: LegendMetrics): LegendLayout;
+/**
+ * A key to a chart's colours: a swatch and a name per entry, each swatch showing the mark it
+ * stands for. `chart` draws one automatically from its colour scale; use this directly for
+ * charts without a frame or colours assigned by hand.
+ *
+ * @example
+ * ```ts
+ * import { legend } from "@sophistry/charts";
+ *
+ * legend.create({
+ * 	at: { x: 3, y: 2 },
+ * 	entries: [
+ * 		{ label: "North", color: "tomato" },
+ * 		{ label: "South", color: "steelblue", mark: { line: true, symbol: "circle" } },
+ * 	],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/guides/charts/#series-and-legends
+ * @category Charts
+ */
+export declare const legend: import("@sophistry/core").Definition<LegendProps, import("@sophistry/core/internal").CompositeNode<LegendProps>, keyof LegendProps>;
+//# sourceMappingURL=legend.d.ts.map

package/dist/guides/legend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legend.d.ts","sourceRoot":"","sources":["../../src/guides/legend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAqBH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAM/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAWrE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,kDAAkD;IAClD,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB,uDAAuD;IACvD,IAAI,CAAC,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,2FAA2F;IAC3F,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IACzB,iDAAiD;IACjD,EAAE,EAAE,SAAS,OAAO,EAAE,CAAC;IACvB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,6BAA6B;IAC7B,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC,oDAAoD;IACpD,EAAE,EAAE,KAAK,CAAC;IACV;;;OAGG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACnB;AAOD;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,OAAO,EAAE,aAAa,GACpB,YAAY,CAwBd;AAiCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,MAAM,qIA8BjB,CAAC"}

package/dist/guides/nodes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Small helpers the guides share for keeping child nodes across updates.
+ * A guide keeps its nodes for as long as what they stand for exists, hiding
+ * one with `visible: false` (no spec) when it is not shown, and writes only the props whose values changed. Internal to the
+ * guides.
+ */
+import type { SceneNode } from "@sophistry/core";
+/**
+ * Writes the props of `next` that differ by value from `node`'s current
+ * ones (points and point lists compared by structure), so a guide's update
+ * re-bakes only the children it moved.
+ */
+export declare function write<P extends object>(node: SceneNode<P>, next: Partial<P>): void;
+//# sourceMappingURL=nodes.d.ts.map

package/dist/guides/nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../src/guides/nodes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EACrC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,EAClB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GACd,IAAI,CAMN"}