@sophistry/charts 0.0.0-stage → 0.0.1

package/dist/curves/regression.d.ts

@@ -0,0 +1,125 @@
+/**
+ * `regression`: a fitted trend (least squares or LOESS) with its confidence
+ * band, one per `series`, drawn as one path batch (per fit a closed band
+ * item, then an open line item) in a group whose clip the reveal sweeps.
+ */
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey } from "@sophistry/core/geometry";
+import type { Channel, PositionValue } from "../data/channels";
+import type { SeriesTransitionProps } from "../props";
+/**
+ * Props of {@link regressionPlot}: `x` and `y` default to the index and the
+ * datum when `data` is `number[]`; name them otherwise.
+ *
+ * @category Charts
+ */
+export interface RegressionProps<T = unknown> extends SeriesTransitionProps<T> {
+    /** The points the fit is through: one per datum. */
+    data: readonly T[];
+    /**
+     * Predictor, in data units (a `Date` reads as epoch ms). Defaults to the index when `data` is
+     * `number[]`; required otherwise.
+     */
+    x?: Channel<T, PositionValue>;
+    /**
+     * Response, in data units. Defaults to the datum when `data` is `number[]`; required otherwise.
+     * Pairs with a non-finite member are dropped.
+     */
+    y?: Channel<T, number>;
+    /**
+     * The fit: `"linear"`, `"poly"` (a polynomial of `degree`) or `"loess"` (a local smooth over
+     * `bandwidth` of the points).
+     * @default "linear"
+     */
+    method?: "linear" | "poly" | "loess";
+    /**
+     * Polynomial degree for `method="poly"`.
+     * @default 2
+     */
+    degree?: number;
+    /**
+     * Fraction of the points each local fit uses, for `method="loess"`.
+     * @default 0.3
+     */
+    bandwidth?: number;
+    /**
+     * Make a `method="loess"` smooth robust to outliers: `true` for 2 re-weighting passes, or a
+     * number of passes.
+     * @default false
+     */
+    robust?: boolean | number;
+    /**
+     * Confidence level of the band around the fit, 0..1 (0 for no band): the fitted mean's t-band
+     * for least squares, the standard-error band for LOESS (see {@link loessBand}).
+     * @default 0.95
+     */
+    level?: number;
+    /**
+     * How many x positions the fit is drawn through.
+     * @default 50
+     */
+    samples?: number;
+    /**
+     * The category of each datum: one fit per category, coloured through the chart's shared colour
+     * scale and legend. `color` wins.
+     */
+    series?: Channel<T, BandKey>;
+    /**
+     * Line and band colour. Defaults to the `series` colour, else the theme's first series colour.
+     */
+    color?: ColorInput;
+    /**
+     * Band fill opacity, 0..1.
+     * @default 0.2
+     */
+    bandOpacity?: number;
+    /** Line width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /**
+     * Reveal, 0..1: the line and its band sweep in left to right together.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * The data to transition to, fits matched by `series`: shared fits morph with their bands, new
+     * ones sweep in, leaving ones fade out. See {@link SeriesTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the fits. */
+    visible?: boolean;
+}
+/**
+ * A fitted trend with its confidence band over the data's x extent: least
+ * squares (a line or polynomial) or a LOESS smooth. Draw it over a
+ * `scatter` of the same data. See the `regression` and `loessBand` maths for
+ * the fits alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, regressionPlot, scatter } from "@sophistry/charts";
+ *
+ * const rows = [1, 2, 3, 4, 5, 6, 7, 8].map((x) => ({ x, y: Math.sqrt(x) + Math.sin(x) / 4 }));
+ * chart.create({
+ * 	width: 8,
+ * 	height: 4,
+ * 	children: [
+ * 		scatter.create({ data: rows, x: "x", y: "y" }),
+ * 		regressionPlot.create({ data: rows, x: "x", y: "y", method: "loess" }),
+ * 	],
+ * });
+ * ```
+ *
+ * Exported as `regressionPlot` (definition name `"Regression"`): the
+ * package entry already exports the `regression` fit from its maths.
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#lines-scatter-and-error-bars
+ * @category Charts
+ */
+export declare const regressionPlot: import("@sophistry/core").Definition<RegressionProps<any>, import("@sophistry/core/internal").CompositeNode<RegressionProps<any>>, keyof RegressionProps<any>>;
+//# sourceMappingURL=regression.d.ts.map

package/dist/curves/regression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regression.d.ts","sourceRoot":"","sources":["../../src/curves/regression.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAS,MAAM,0BAA0B,CAAC;AAI/D,OAAO,KAAK,EAAE,OAAO,EAAY,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAoBzE,OAAO,KAAK,EAAY,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAWhE;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,qBAAqB,CAAC,CAAC,CAAC;IAC7E,oDAAoD;IACpD,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IACnB;;;OAGG;IACH,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;IAC9B;;;OAGG;IACH,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;IAClB,mBAAmB;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAkTD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,cAAc,gKAuCzB,CAAC"}

package/dist/curves/shared.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What the line and area marks (`linePlot`, `stackPlot`, `fillBetween`,
+ * `stairs`, `ecdf`, `density`, `regression`) share: the one path batch each
+ * draws through (with the clip a sweep reveal needs), stable items so an
+ * outline that did not move is prepared once, and group colours across a
+ * keyed transition. Internal.
+ *
+ * Every curve mark draws one shape per group (a `series` category, or the
+ * one `WHOLE` group), and those shapes have outlines of their own, so the
+ * mark is one core `pathBatch` node: an item per line, band or region, each
+ * with its own stroke or fill and opacity. A `reveal="length"` draw hands
+ * each item its `progress` (the stroke traced along
+ * the outline, a closed outline's fill coming up with it), over the whole
+ * outline; the batch keeps an outline's arrays while only that changes, so
+ * the renderer measures their arc length once.
+ */
+import type { Bindable, PathBatchItem, PathBatchItemsProps, PathBatchNode, SceneNode } from "@sophistry/core";
+import type { Bounds } from "@sophistry/core/geometry";
+import type { ChartLayer } from "../context";
+import type { GroupJoin } from "../join";
+import type { GroupKey, SeriesState } from "../series";
+/**
+ * A group's colour from the series scale, across a keyed transition: while
+ * one runs, over both ends' categories (`data`'s first), so a category keeps
+ * its colour. Undefined for {@link WHOLE}, or when an explicit colour wins.
+ */
+export declare function groupColors(layer: ChartLayer, series: SeriesState, join: GroupJoin): (key: GroupKey) => string | undefined;
+/**
+ * The one path batch of a curve mark, inside a group whose clip a sweep
+ * reveal moves. Call once, in `setup`.
+ */
+export interface CurveBatch {
+    /** The node to return from the mark: the group holding the batch. */
+    readonly node: SceneNode;
+    /** The batch itself. */
+    readonly batch: PathBatchNode<PathBatchItemsProps>;
+    /**
+     * Writes one update's items (`[slot key, item]` pairs, in paint order),
+     * shared props and clip. An item equal to the one its slot held last time
+     * is handed over as that same object, one whose outline alone is equal
+     * (its `progress` or a paint changed) around the same outline arrays, and
+     * an unchanged list as the same array, so the batch re-prepares only
+     * outlines that moved.
+     */
+    update(items: readonly (readonly [unknown, PathBatchItem])[], shared: Bindable<Omit<PathBatchItemsProps, "items">>, clip?: Bounds | undefined): void;
+    /** The items as last written. */
+    readonly items: readonly PathBatchItem[];
+}
+/** Makes a mark's {@link CurveBatch}. */
+export declare function createCurveBatch(): CurveBatch;
+/** A group's slot key in a batch with more than one item per group (`"fill"`, `"line"`). */
+export declare function slotOf(key: GroupKey, part: string): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/curves/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/curves/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACX,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,SAAS,EACT,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAEX,MAAM,EAGN,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIvD;;;;GAIG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,SAAS,GACb,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,GAAG,SAAS,CASvC;AA0DD;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IACnD;;;;;;;OAOG;IACH,MAAM,CACL,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,EAAE,EACrD,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC,EACpD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,GACvB,IAAI,CAAC;IACR,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CACzC;AAED,yCAAyC;AACzC,wBAAgB,gBAAgB,IAAI,UAAU,CAwC7C;AAED,4FAA4F;AAC5F,wBAAgB,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/curves/stack-plot.d.ts

@@ -0,0 +1,141 @@
+/**
+ * `stackPlot`: a stacked area chart, drawn as one path batch (a closed item
+ * per band) in a group whose clip the `"x"` reveal sweeps; `reveal="length"`
+ * traces each band's outline (the item's `progress`), its fill coming up
+ * with it.
+ *
+ * Across a keyed transition each end is stacked on its own, a band one end
+ * lacks stands with no thickness on its seam, and the update morphs each
+ * band's bounds together, so adjacent bands stay touching on every frame.
+ */
+import type { PaintSpec } from "@sophistry/core";
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey, CurveKind } from "@sophistry/core/geometry";
+import type { Channel, PositionValue } from "../data/channels";
+import type { JoinStaging } from "../math/join";
+import type { StackOffset, StackOrder } from "../math/stack";
+import type { StackReveal, TransitionProps } from "../props";
+/**
+ * Props of {@link stackPlot}: `x` defaults to the index when `data` is
+ * `number[]`; name it otherwise.
+ *
+ * @category Charts
+ */
+export interface StackPlotProps<T = unknown> extends TransitionProps<T> {
+    /**
+     * Wide format (`y` a list): one row per x position. Long format (`y` one channel, with a
+     * `series`): one row per band per x position.
+     */
+    data: readonly T[];
+    /**
+     * X position, in data units (a `Date` reads as epoch ms). Defaults to the index when `data` is
+     * `number[]`; required otherwise.
+     */
+    x?: Channel<T, PositionValue>;
+    /**
+     * One channel per band, stacked in the order given (`y: ["north", "south"]`); or one channel,
+     * for long-format `data`, with `series` naming each row's band. Non-finite heights count as 0.
+     */
+    y: readonly Channel<T, number>[] | Channel<T, number>;
+    /**
+     * Which series each band is, colouring bands through the chart's shared colour scale and
+     * legend: with a list of `y` channels, one name per channel; with one `y` channel, a channel
+     * naming each row's band (rows missing at an x count as 0).
+     */
+    series?: readonly BandKey[] | Channel<T, BandKey>;
+    /**
+     * Colours cycled across bands by index. Defaults to the `series` colours, else the theme's
+     * categorical colours.
+     */
+    colors?: readonly ColorInput[];
+    /**
+     * Data-space y the first band stacks on, under the `"zero"` offset. Defaults to the axis
+     * baseline.
+     */
+    baseline?: number;
+    /**
+     * Where each x's stack is placed: `"zero"` on the baseline, `"normalize"` as shares of the
+     * total, `"center"` centred on zero, `"wiggle"` a streamgraph (needs ascending, evenly spaced
+     * x). See {@link StackOffset}.
+     * @default "zero"
+     */
+    offset?: StackOffset;
+    /**
+     * Which band sits at the bottom: `"appearance"`, `"reverse"`, `"sum"` (largest on top),
+     * `"insideOut"` (streamgraph order), or band indices bottom to top. Colours stay with their
+     * band.
+     * @default "appearance"
+     */
+    order?: StackOrder;
+    /**
+     * How `progress` reveals the stack: `"grow"` every band's height from the baseline together,
+     * `"x"` left to right behind one front, `"length"` each band's outline by arc length.
+     * @default "grow"
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    reveal?: StackReveal;
+    /**
+     * How band edges run between rows: `"linear"` or any {@link CurveKind} (`"monotone"` for a
+     * smooth stack). Adjacent bands still share their edge exactly.
+     * @default "linear"
+     */
+    curve?: CurveKind;
+    /**
+     * The data to transition to, bands matched by `series` (long format) or place in `y` (wide):
+     * each end is stacked on its own and shared bands morph between them, so every frame is a
+     * stack. Leaving bands shrink away, new ones grow in.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /**
+     * How the transition spends `blend`.
+     * @default "staged"
+     */
+    staging?: JoinStaging;
+    /**
+     * With `to`: fraction of the enter stage spent staggering arriving bands, bottom up, 0..0.95.
+     * @default 0
+     */
+    enterStagger?: number;
+    /** Band fill opacity 0..1. @default 0.85 */
+    fillOpacity?: number;
+    /** Band outline. @default "none" */
+    stroke?: PaintSpec;
+    /** Outline width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Reveal 0..1 (see `reveal`). @default 1 */
+    progress?: number;
+    /** Paint order (the bands paint under the axes of that order). */
+    zIndex?: number;
+    /** Set to false to hide the bands. */
+    visible?: boolean;
+}
+/**
+ * A stacked area chart: bands stacked atop a shared baseline, each shaded in
+ * its own colour. Use `offset` for 100% areas or streamgraphs. Inside a
+ * `chart` (or any `axes` whose y range covers the stacked total). See
+ * {@link stackedBands} for the stacking alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, stackPlot } from "@sophistry/charts";
+ *
+ * const rows = [
+ * 	{ year: 2022, north: 3, south: 2 },
+ * 	{ year: 2023, north: 4, south: 3 },
+ * 	{ year: 2024, north: 5, south: 3 },
+ * ];
+ * chart.create({
+ * 	width: 8,
+ * 	height: 4,
+ * 	children: [stackPlot.create({ data: rows, x: "year", y: ["north", "south"], series: ["North", "South"] })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#stacked-areas
+ * @category Charts
+ */
+export declare const stackPlot: import("@sophistry/core").Definition<StackPlotProps<any>, import("@sophistry/core/internal").CompositeNode<StackPlotProps<any>>, keyof StackPlotProps<any>>;
+//# sourceMappingURL=stack-plot.d.ts.map

package/dist/curves/stack-plot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-plot.d.ts","sourceRoot":"","sources":["../../src/curves/stack-plot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAGX,SAAS,EAGT,MAAM,iBAAiB,CAAC;AAMzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAS,MAAM,0BAA0B,CAAC;AAI1E,OAAO,KAAK,EAAE,OAAO,EAAY,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAczE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAI7D,OAAO,KAAK,EAAY,WAAW,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAQvE;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,eAAe,CAAC,CAAC,CAAC;IACtE;;;OAGG;IACH,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IACnB;;;OAGG;IACH,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;IAC9B;;;OAGG;IACH,CAAC,EAAE,SAAS,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACtD;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAClD;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;OAKG;IACH,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,qBAAqB;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAgkBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS,6JAwCpB,CAAC"}

package/dist/curves/stairs.d.ts

@@ -0,0 +1,171 @@
+/**
+ * `stairs`: a step function held flat across each `[edges[i], edges[i + 1]]`
+ * interval, one open line per `series`, drawn as one path batch. Also the
+ * step-line drawing `ecdf` shares ({@link stepLineItems}): lines kept by
+ * group, coloured by the series scale unless `stroke` is set, revealed along
+ * x behind one front (or by arc length), and morphed as step functions
+ * across a keyed transition.
+ */
+import type { CoordinateSystem, PaintSpec, SceneNode } from "@sophistry/core";
+import type { BandKey, Point } from "@sophistry/core/geometry";
+import type { Channel } from "../data/channels";
+import type { ChartFrame } from "../frame/types";
+import type { GroupJoin } from "../join";
+import type { StepFunction } from "../math/morph";
+import type { CurveReveal, SeriesTransitionProps } from "../props";
+import type { GroupKey } from "../series";
+import type { CurveBatch } from "./shared";
+/**
+ * The stroke props every step line takes (`stairs`, `ecdf`).
+ *
+ * @category Charts
+ */
+export interface StepLineStyleProps {
+    /** Line colour (or gradient) for every line. Defaults to the `series` colour, else the theme's foreground. */
+    stroke?: PaintSpec;
+    /** Line width. Defaults to the theme's stroke width. */
+    strokeWidth?: number;
+    /** Dash pattern, in scene units. Solid when omitted. */
+    dash?: number[];
+    /** Offset into `dash`. @default 0 */
+    dashOffset?: number;
+    /** How line ends are capped. @default "round" */
+    lineCap?: CanvasLineCap;
+    /** How corners are joined. @default "round" */
+    lineJoin?: CanvasLineJoin;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /** Reveal 0..1 (see `reveal`). @default 1 */
+    progress?: number;
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the lines. */
+    visible?: boolean;
+}
+/**
+ * Props of {@link stairs}: `value` defaults to the datum when `data` is
+ * `number[]`; name it otherwise.
+ *
+ * @category Charts
+ */
+export interface StairsProps<T = unknown> extends SeriesTransitionProps<T>, StepLineStyleProps {
+    /** One step per datum. */
+    data: readonly T[];
+    /**
+     * Height of each step, in data units, held across `[edges[i], edges[i + 1]]`. Defaults to the
+     * datum when `data` is `number[]`; required otherwise.
+     */
+    value?: Channel<T, number>;
+    /**
+     * Step boundaries in data units, ascending, exactly one more than `data` (else throws). With a
+     * `series`, shared by every category. Defaults to `0..data.length`.
+     */
+    edges?: readonly number[];
+    /**
+     * The category of each datum: one step line per category, coloured through the chart's shared
+     * colour scale and legend. `stroke` wins.
+     */
+    series?: Channel<T, BandKey>;
+    /**
+     * How `progress` reveals the steps: `"x"` left to right at a constant rate, or `"length"` by
+     * arc length.
+     * @default "x"
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    reveal?: CurveReveal;
+    /**
+     * The data to transition to, lines matched by `series`: shared lines morph and stay step
+     * functions every frame, new ones sweep in, leaving ones fade out. See {@link
+     * SeriesTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+}
+/** The descriptor entries of {@link StepLineStyleProps}. */
+export declare const stepLineStyleDescriptor: {
+    readonly stroke: {
+        readonly invalidates: 64;
+    };
+    readonly strokeWidth: {
+        readonly invalidates: 64;
+    };
+    readonly dash: {
+        readonly invalidates: 64;
+    };
+    readonly dashOffset: {
+        readonly invalidates: 64;
+    };
+    readonly lineCap: {
+        readonly invalidates: 64;
+    };
+    readonly lineJoin: {
+        readonly invalidates: 64;
+    };
+    readonly opacity: {
+        readonly invalidates: 64;
+    };
+    readonly progress: {
+        readonly default: 1;
+        readonly invalidates: 64;
+    };
+    readonly zIndex: {
+        readonly invalidates: 64;
+    };
+    readonly visible: {
+        readonly invalidates: 64;
+    };
+};
+/** What a step-line drawing keeps between updates. */
+export interface StepLines {
+    scene: (deps: readonly unknown[], make: () => Map<GroupKey, Point[][]>) => Map<GroupKey, Point[][]>;
+    lines: CurveBatch;
+}
+/** Makes a {@link StepLines}. Call once, in `setup`. */
+export declare function createStepLines(): StepLines;
+/**
+ * Draws one step line per group (what `stairs` and `ecdf` share): each
+ * group's line in scene units on this frame (morphed as a step function on
+ * the update stage, entering ones swept in, leaving ones faded), cut at one
+ * front along x (or by arc length), as path batch items.
+ *
+ * @internal
+ */
+export declare function drawStepLines(own: StepLines, spec: {
+    props: StepLineStyleProps;
+    theme: {
+        palette: {
+            foreground: string;
+        };
+    };
+    frame: ChartFrame | null;
+    coords: CoordinateSystem;
+    /** `data`'s step functions, per group. */
+    steps: Map<GroupKey, StepFunction>;
+    /** `to`'s, while a transition runs. */
+    to: Map<GroupKey, StepFunction> | undefined;
+    join: GroupJoin;
+    colorOf: (key: GroupKey) => string | undefined;
+    progress: number | undefined;
+    alongX: boolean;
+}): SceneNode[];
+/**
+ * A step function held flat across each `[edges[i], edges[i + 1]]` interval,
+ * drawn as one open line: a histogram's outline without the fill. Inside a
+ * `chart` or `axes`. See {@link stairsPolyline} for the geometry alone.
+ *
+ * @example
+ * ```ts
+ * import { chart, stairs } from "@sophistry/charts";
+ *
+ * chart.create({
+ * 	width: 8,
+ * 	height: 4,
+ * 	children: [stairs.create({ data: [3, 5, 2, 6], edges: [0, 1, 2, 4, 5] })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#histograms
+ * @category Charts
+ */
+export declare const stairs: import("@sophistry/core").Definition<StairsProps<any>, import("@sophistry/core/internal").CompositeNode<StairsProps<any>>, keyof StairsProps<any>>;
+//# sourceMappingURL=stairs.d.ts.map

package/dist/curves/stairs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stairs.d.ts","sourceRoot":"","sources":["../../src/curves/stairs.ts"],"names":[],"mappings":"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"}