@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/join.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Keyed data transitions (`to` + `blend`) shared by chart marks: the join
+ * between the two datasets' keys and each stage's progress. A key in both
+ * ends updates (interpolates in data space), one only in `to` enters at its
+ * new place, one only in `data` exits at its old place. Stages come from the
+ * enclosing chart, or from the join alone outside one.
+ *
+ * Each is a factory called once in
+ * a composite's `setup` that returns a function to call in every `update`.
+ * The factory keeps last-input caches (keys compared by value), so a frame
+ * of a blend recomputes the stage progress and nothing else. Internal.
+ */
+import type { BandKey, Point } from "@sophistry/core/geometry";
+import type { Channel, DateSink } from "./data/channels.js";
+import type { AxisExtent, ColorExtent, LayerTransition } from "./frame/types.js";
+import type { JoinStages, JoinStaging, KeyedJoin } from "./math/join.js";
+import type { Category, GroupKey } from "./series.js";
+/** One update's view of a keyed join. See {@link createJoin}. */
+export interface JoinState {
+    /** True while a transition is requested (`to` given). */
+    active: boolean;
+    /** Every key to keep an item for: the union while active, else `data`'s keys. */
+    keys: readonly BandKey[];
+    /** The join, while active. */
+    join: KeyedJoin | undefined;
+    /** Where each key sits in `data`'s keys. */
+    fromSlots: Map<BandKey, number>;
+    /** Where each key sits in `to`'s keys, while active. */
+    toSlots: Map<BandKey, number> | undefined;
+    /** The blend, clamped (0 when inactive). */
+    t: number;
+    /** The stages in use, while active. */
+    stages: JoinStages | undefined;
+    /** Progress of the update stage, 0..1 (0 when inactive). */
+    update: number;
+    /** Progress of the enter stage, 0..1 (0 when inactive). */
+    enter: number;
+    /** One entering key's progress through the enter stage: its own sub-window under `enterStagger`, else `enter`. */
+    enterOf(key: BandKey): number;
+    /** Progress of the exit stage, 0..1 (0 when inactive). */
+    exit: number;
+    /** Whether anything enters or exits, including the mark's own `more` (false when inactive). */
+    flags: {
+        enters: boolean;
+        exits: boolean;
+    };
+}
+/** What {@link createJoin}'s function takes on each update. */
+export interface JoinSpec {
+    fromKeys: readonly BandKey[];
+    /** `to`'s keys, or undefined without a transition. */
+    toKeys: readonly BandKey[] | undefined;
+    blend: number | undefined;
+    staging: JoinStaging | undefined;
+    /** The enclosing chart's stages (`frame.join`), which win over the join's own. */
+    chartStages?: JoinStages | undefined;
+    /** Enters and exits beyond the keys (a radar's axes), so the stages make room. */
+    more?: {
+        enters?: boolean;
+        exits?: boolean;
+    } | undefined;
+    /** Fraction of the enter stage spent staggering entering keys, 0..0.95. */
+    enterStagger?: number | undefined;
+    /** Each entering key's stagger rank; defaults to `to`'s order. */
+    enterRanks?: (entering: readonly BandKey[], join: KeyedJoin) => readonly number[];
+}
+/**
+ * Makes a keyed join for one mark. Call once, in `setup`; call the result
+ * in every `update` with that update's keys and blend.
+ *
+ * @returns `(spec) => JoinState`, caching the join while the keys are equal
+ *   by value.
+ */
+export declare function createJoin(): (spec: JoinSpec) => JoinState;
+/** Which end of a transition a key's datum is read from. */
+export type JoinEnd = "from" | "to";
+/** What one key is on one frame of a keyed transition. See {@link joinFrame}. */
+export interface JoinFrame<S> {
+    /** Its state: `data`'s, `to`'s, or the two blended by the update stage. */
+    state: S;
+    /** 0..1 presence: `1 − exit` while leaving, `enter` while arriving, else 1. */
+    presence: number;
+    /** The end its datum is read from: the nearer one while it updates. */
+    end: JoinEnd;
+    /** That datum's index in its end's data. */
+    index: number;
+    /**
+     * While an axis changes kind, for a key in both ends mid-update: each end's
+     * own state and the update progress, so the mark can blend them in scene
+     * units; `state` is then only the data-unit blend.
+     */
+    pair?: {
+        a: S;
+        b: S;
+        u: number;
+    };
+}
+/**
+ * One key's frame: in both ends it blends from `a` to `b` on the update
+ * stage; only in `data` it stays at `a` as presence falls; only in `to` it
+ * stands at `b` as presence rises. Marks spend `presence` like their reveal
+ * spends `progress`, so exit is the reveal reversed.
+ *
+ * @param blend - Blends two states at update progress `u`.
+ * @param key - The key, so an entering one reads its staggered enter.
+ * @param pair - Keep both ends' states mid-swap: pass `space.swapping`.
+ * @returns The frame, or undefined when neither end has the key.
+ */
+export declare function joinFrame<S>(join: JoinState, a: {
+    state: S;
+    index: number;
+} | undefined, b: {
+    state: S;
+    index: number;
+} | undefined, blend: (a: S, b: S, u: number) => S, key?: BandKey, pair?: boolean): JoinFrame<S> | undefined;
+/** One update's keyed data: the join, plus where each key's datum is at each end. */
+export interface KeyedData extends JoinState {
+    /** Each `to` datum's category, with a `series` and a transition. */
+    toOf: Category[] | undefined;
+    /** A key's datum index in `data`, or -1 (entering). */
+    fromIndex(key: BandKey): number;
+    /** A key's datum index in `to`, or -1 (leaving, or no transition). */
+    toIndex(key: BandKey): number;
+}
+/** What {@link createKeyedData}'s function takes on each update. */
+export interface KeyedDataSpec<T> {
+    data: readonly T[];
+    to: readonly T[] | undefined;
+    key: Channel<T, BandKey> | undefined;
+    series: Channel<T, BandKey> | undefined;
+    /** `data`'s categories (the `series` channel read across it), if any. */
+    of: readonly Category[] | undefined;
+    /** The indices a dataset draws, in draw order; defaults to all. */
+    drawn?: (data: readonly T[]) => readonly number[];
+    blend: number | undefined;
+    staging: JoinStaging | undefined;
+    chartStages?: JoinStages | undefined;
+    more?: {
+        enters?: boolean;
+        exits?: boolean;
+    } | undefined;
+    enterStagger?: number | undefined;
+    /** As {@link JoinSpec.enterRanks}, also given each entering key's index in `to`. */
+    enterRanks?: (entering: readonly BandKey[], join: KeyedJoin, toIndex: (key: BandKey) => number) => readonly number[];
+    /** The chart's date sink, for channels reading dates. */
+    dates?: DateSink | null;
+}
+/**
+ * The keyed join of a per-datum mark (dots, stems, error bars, ticks): each
+ * end's keys (the `key` channel, else place within series, else index),
+ * restricted to what the mark draws. Call once, in `setup`; call the result
+ * in each `update`, draw its `keys` and read each key's frame with
+ * {@link joinFrame} (or all of them with {@link joinFrames}).
+ */
+export declare function createKeyedData<T>(): (spec: KeyedDataSpec<T>) => KeyedData;
+/**
+ * Every key's {@link joinFrame} for a per-datum mark, in key order.
+ * `stateOf(end, index)` reads one end's datum, or undefined where it draws
+ * nothing.
+ *
+ * @param pair - Mid-swap, keep both ends' states (`space.swapping`).
+ */
+export declare function joinFrames<S>(keyed: KeyedData, stateOf: (end: JoinEnd, index: number) => S | undefined, blend: (a: S, b: S, u: number) => S, pair?: boolean): Map<BandKey, JoinFrame<S>>;
+/** Each key's place in a per-datum mark's reveal order: `data`'s keys, then those only in `to`. */
+export declare function keyRanks(keys: readonly BandKey[]): Map<BandKey, number>;
+/**
+ * A layer's `transition` report: the far end's extents, the blend and what
+ * the join contains. Undefined without a transition.
+ *
+ * @param far - The `to` data's extents (omit axes the layer doesn't report),
+ * and `enters` / `exits` when the layer decides them rather than the join.
+ */
+export declare function layerTransition(join: JoinState, staging: JoinStaging | undefined, far: {
+    x?: AxisExtent;
+    y?: AxisExtent;
+    enters?: boolean;
+    exits?: boolean;
+}): LayerTransition | undefined;
+/**
+ * A layer's `color` report across a keyed transition: both ends' categories,
+ * `data`'s first (so colours hold still), with each end's as `ends` (so the
+ * legend fades entries). Otherwise the report as given.
+ */
+export declare function transitionColor(own: ColorExtent | undefined, toCategories: readonly Category[] | undefined): ColorExtent | undefined;
+/** The keyed join of a grouped mark (one shape per `series` category, or one {@link WHOLE} shape). */
+export interface GroupJoin extends JoinState {
+    /** Every group to draw: both ends' while a transition runs (`data`'s first), else `data`'s. */
+    groups: readonly GroupKey[];
+    /** The categories `to` draws (its groups, less {@link WHOLE}), while a transition runs. */
+    toCategories: readonly BandKey[] | undefined;
+    /** Whether a group is only in `to`: it enters, on the enter stage. */
+    entering(key: GroupKey): boolean;
+    /** A group's fade: `1 − exit` for one only `data` has (it leaves), else 1. */
+    fade(key: GroupKey): number;
+}
+/** What {@link createGroupJoin}'s function takes on each update. */
+export interface GroupJoinSpec {
+    fromGroups: readonly GroupKey[];
+    toGroups: readonly GroupKey[] | undefined;
+    blend: number | undefined;
+    staging: JoinStaging | undefined;
+    chartStages?: JoinStages | undefined;
+    enterStagger?: number | undefined;
+    enterRanks?: (entering: readonly BandKey[], join: KeyedJoin) => readonly number[];
+}
+/**
+ * The keyed join of a grouped mark: groups matched by category. A group in
+ * both ends morphs on the update stage, one only in `to` enters, one only
+ * in `data` exits. Without `to`, `groups` is `data`'s and every stage reads
+ * 0. Call once, in `setup`.
+ */
+export declare function createGroupJoin(): (spec: GroupJoinSpec) => GroupJoin;
+/**
+ * An entering shape swept in along x (along y when `vertical`): its lines
+ * and rings cut at the front `enter` of the way across their extent.
+ */
+export declare function sweepIn(shape: {
+    lines: readonly (readonly Point[])[];
+    rings: readonly (readonly Point[])[];
+}, enter: number, vertical?: boolean): {
+    lines: Point[][];
+    rings: Point[][];
+};

package/dist/math/3d/bar3d.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 3D bar geometry: one box per index, anchored at `(x, y, z)` (not centred)
+ * and extended by `(width, height, depth)`. Each extent is a number for
+ * every bar or one per bar; arrays pair by index up to the shortest.
+ */
+/** @category Math */
+export interface BarSlotBox3D {
+    /** Index into the input arrays, keeping a `colors` array aligned past dropped entries. */
+    index: number;
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+    z0: number;
+    z1: number;
+}
+/**
+ * One box per index: anchored at `(xs[i], ys[i], zs[i])` and extended by
+ * that index's `(width, height, depth)`. Negative extents still give a
+ * well-formed box; non-finite components drop the entry.
+ *
+ * @param widths - Extent along x: one number for every bar, or one per bar.
+ * @param heights - Extent along y: one number for every bar, or one per bar.
+ * @param depths - Extent along z: one number for every bar, or one per bar.
+ * @category Math & helpers
+ */
+export declare function bar3dSlots(xs: readonly number[], ys: readonly number[], zs: readonly number[], widths: number | readonly number[], heights: number | readonly number[], depths: number | readonly number[]): BarSlotBox3D[];

package/dist/math/3d/quiver3d.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 3D vector field geometry: one arrow per index, tail at `(x, y, z)`,
+ * direction and length `(u, v, w) * scale` (not normalised; pre-normalise
+ * the components for equal lengths).
+ */
+import type { Point3 } from "@sophistry/core/internal";
+/** @category Math */
+export interface QuiverVector3 {
+    /** Index into the input arrays, keeping a `colors` array aligned past dropped entries. */
+    index: number;
+    origin: Point3;
+    vector: Point3;
+}
+/** @category Math */
+export interface QuiverOptions {
+    /** Multiplies `(u, v, w)` before it becomes the drawn vector. @default 1 */
+    scale?: number;
+}
+/**
+ * One vector per finite `(x, y, z, u, v, w)`, keeping its index; the six
+ * arrays pair by index.
+ *
+ * @param us - Vector x component, in data units (before `scale`).
+ * @category Math & helpers
+ */
+export declare function quiverVectors(xs: readonly number[], ys: readonly number[], zs: readonly number[], us: readonly number[], vs: readonly number[], ws: readonly number[], options?: QuiverOptions): QuiverVector3[];

package/dist/math/3d/scatter3d.d.ts

@@ -0,0 +1,15 @@
+/** 3D scatter geometry: one marker per finite `(x, y, z)` triple. */
+/** @category Math */
+export interface ScatterPoint3 {
+    /** Index into the input arrays, keeping `sizes`/`colors` aligned past dropped triples. */
+    index: number;
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * The finite `(x, y, z)` triples, paired by index, each keeping its index.
+ *
+ * @category Math & helpers
+ */
+export declare function scatterPoints3(xs: readonly number[], ys: readonly number[], zs: readonly number[]): ScatterPoint3[];

package/dist/math/3d/stem3d.d.ts

@@ -0,0 +1,22 @@
+/** 3D stem geometry: a drop line along world y (up) from `baseline`, and a marker, per finite `(x, y, z)`. */
+import type { Point3 } from "@sophistry/core/internal";
+/** @category Math */
+export interface StemPoint3 {
+    /** Index into the input arrays, keeping a `colors` array aligned past dropped triples. */
+    index: number;
+    /** `(x, baseline, z) → (x, y, z)`, in data coordinates. */
+    drop: [Point3, Point3];
+    marker: Point3;
+}
+/** @category Math */
+export interface Stem3DOptions {
+    /** The y (height) value each drop line starts from. @default 0 */
+    baseline?: number;
+}
+/**
+ * One drop line and marker per finite `(x, y, z)`, paired by index.
+ *
+ * @param ys - Heights; the drop runs along this axis.
+ * @category Math & helpers
+ */
+export declare function stemPoints3(xs: readonly number[], ys: readonly number[], zs: readonly number[], options?: Stem3DOptions): StemPoint3[];

package/dist/math/3d/surfaceGrid3d.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Structured-grid surfaces: `X`, `Y`, `Z` are three `nrows x ncols` arrays of
+ * world coordinates for one grid of points, computed by the caller. Quads
+ * are wound so `MeshFaces` sees them facing outward. Mismatched grid
+ * shapes throw.
+ */
+import type { Point3 } from "@sophistry/core/internal";
+/** @category Math */
+export interface SurfaceGridFace {
+    points: Point3[];
+}
+/**
+ * A rectangular grid of numbers (rows of columns).
+ *
+ * @category Math & helpers
+ */
+export type SurfaceGrid = readonly (readonly number[])[];
+/**
+ * One outward-wound quad per grid cell, `(nrows - 1) * (ncols - 1)` total.
+ *
+ * @param X - World x of each grid point, `X[row][col]`.
+ * @throws If the three grids differ in row count or any row's length.
+ * @category Math & helpers
+ */
+export declare function surfaceGridFaces(X: SurfaceGrid, Y: SurfaceGrid, Z: SurfaceGrid): SurfaceGridFace[];
+/**
+ * One polyline per grid row plus one per column: the wireframe.
+ *
+ * @param X - World x of each grid point, `X[row][col]`.
+ * @throws If the three grids differ in row count or any row's length.
+ * @category Math & helpers
+ */
+export declare function surfaceGridWireframe(X: SurfaceGrid, Y: SurfaceGrid, Z: SurfaceGrid): Point3[][];

package/dist/math/3d/trisurface.d.ts

@@ -0,0 +1,11 @@
+/** Triangulated surface faces: the xy-plane Delaunay triangulation, lifted to each point's `z`. */
+import type { Point3 } from "@sophistry/core/internal";
+/**
+ * The xy-plane Delaunay triangles, each as 3 world points with `zs` as height.
+ *
+ * @param zs - Heights per point; triangles with a non-finite height are skipped.
+ * @category Math & helpers
+ */
+export declare function trisurfaceFaces(xs: readonly number[], ys: readonly number[], zs: readonly number[]): {
+    points: Point3[];
+}[];

package/dist/math/3d/voxels.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Boolean voxel grid geometry: each `true` `filled[i][j][k]` occupies the unit
+ * cube `[i, i+1] x [j, j+1] x [k, k+1]`; ragged or missing entries are empty.
+ * Only exposed faces are emitted (faces between two filled voxels are
+ * culled), wound counter-clockwise from outside.
+ */
+import type { Point3 } from "@sophistry/core/internal";
+/** @category Math */
+export interface VoxelFace {
+    points: Point3[];
+}
+/**
+ * One quad per exposed face of every filled voxel.
+ *
+ * @category Math & helpers
+ */
+export declare function voxelFaces(filled: readonly (readonly (readonly boolean[])[])[]): VoxelFace[];

package/dist/math/aggregate.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Reducers and per-series maps: the arithmetic behind the `group`, `bin`,
+ * `rolling` and `normalize` transforms. Arrays of numbers in, numbers out.
+ */
+/**
+ * How a set of values becomes one number. Every reducer but `"count"` (which
+ * counts rows) drops non-finite values first. An empty set reduces to `NaN`
+ * (0 for `"count"` and `"sum"`).
+ *
+ * @category Math & helpers
+ */
+export type ReducerName = "count" | "sum" | "mean" | "median" | "min" | "max" | "first" | "last" | "deviation" | "variance";
+/**
+ * A named reducer, or your own function of the values.
+ *
+ * @category Math & helpers
+ */
+export type Reducer = ReducerName | ((values: number[]) => number);
+/**
+ * Reduces `values` to one number; see {@link ReducerName}.
+ *
+ * @category Math & helpers
+ */
+export declare function reduceValues(values: readonly number[], reducer: Reducer): number;
+/** @category Math */
+export interface RollingOptions {
+    /** Window size, in values. @default 3 */
+    k?: number;
+    /**
+     * Where each value sits in its window: `"middle"` (centred), `"start"`
+     * (looking ahead) or `"end"` (trailing).
+     * @default "middle"
+     */
+    anchor?: "start" | "middle" | "end";
+    /** @default "mean" */
+    reduce?: Reducer;
+    /**
+     * Only reduce full windows of finite values (elsewhere `NaN`). Off, windows
+     * cut short or holding non-finite values reduce what they have.
+     * @default false
+     */
+    strict?: boolean;
+}
+/**
+ * A moving-window reduction of `values`, a rolling mean by default.
+ *
+ * @returns One value per input value.
+ * @category Math & helpers
+ */
+export declare function rollingValues(values: readonly number[], options?: RollingOptions): number[];
+/**
+ * What {@link normalizeValues} divides by: `"first"` (growth from the first
+ * value), `"last"`, `"sum"`, `"mean"`, `"median"`, `"min"` or `"max"`;
+ * `"extent"` rescales min..max to 0..1; `"deviation"` gives z-scores; a
+ * number divides by itself.
+ *
+ * @category Math & helpers
+ */
+export type NormalizeBasis = "first" | "last" | "sum" | "mean" | "median" | "min" | "max" | "extent" | "deviation" | number;
+/**
+ * Normalizes a series against a basis. Non-finite values, and every value
+ * under a zero or non-finite basis, become `NaN`.
+ *
+ * @param basis - Defaults to `"first"`.
+ * @returns One value per input value.
+ * @category Math & helpers
+ */
+export declare function normalizeValues(values: readonly number[], basis?: NormalizeBasis): number[];

package/dist/math/bar.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A bar's box in data space: slot `index` occupies `[index, index + 1]`, the
+ * bar `barWidth` of it, centred.
+ *
+ * @category Math & helpers
+ */
+export interface BarSlotBox {
+    /** The bar's x extent (not the whole slot): `barWidth` wide, centred on the slot. */
+    x0: number;
+    x1: number;
+    /** The bar's y extent, sorted from `baseline` and `value`, so a negative value hangs below the baseline. */
+    y0: number;
+    y1: number;
+}
+/**
+ * Bar width as a fraction of the slot.
+ *
+ * @category Math & helpers
+ */
+export declare const DEFAULT_BAR_WIDTH = 0.6;
+/**
+ * One bar's box in data space at full height: `barWidth` of slot `[index,
+ * index + 1]`, centred at `index + 0.5`, spanning `baseline` to `value` in
+ * either order.
+ *
+ * @param baseline - The value the bar stands on (usually 0).
+ * @param barWidth - Fraction of the slot. Defaults to {@link DEFAULT_BAR_WIDTH}.
+ * @returns The box, or `null` when `value` is not finite.
+ * @category Math & helpers
+ */
+export declare function barSlot(index: number, value: number, baseline: number, barWidth?: number): BarSlotBox | null;

package/dist/math/barLabels.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Where a bar's value label goes, in scene units: centred inside the bar
+ * and whether it fits there, and which bar of a stack carries the stack's
+ * total past its outer end.
+ *
+ * @category Math & helpers
+ */
+import type { Bounds } from "@sophistry/core/geometry";
+/** A label's size in scene units: its advance width and ink height. */
+export interface BarLabelSize {
+    width: number;
+    height: number;
+}
+/** How far past first fitting (as a fraction of the label's length) the bar grows before its label is fully opaque. */
+export declare const INSIDE_LABEL_FADE = 0.5;
+/**
+ * How visible a label centred inside a bar is, 0..1: 0 while the bar is too
+ * small for the label plus `pad`, rising to 1 as it grows past that, and 1
+ * at full length whenever the label fits. A label never shows ahead of its
+ * growing segment.
+ *
+ * @param box - The bar now (mid-reveal or mid-transition).
+ * @param rest - The bar at full length on this frame.
+ * @param pad - Room kept between the label and each edge.
+ * @param vertical - Whether the bar runs up the y axis.
+ * @category Math & helpers
+ */
+export declare function insideLabelFit(box: Bounds, rest: Bounds, size: BarLabelSize, pad: number, vertical: boolean): number;
+/**
+ * One bar's share in its stack's total: the total of its side of zero, and
+ * whether it is that side's outermost segment (the one the total is
+ * written past).
+ *
+ * @category Math & helpers
+ */
+export interface StackTotal {
+    /** The sum of the segments on this bar's side of zero, in data units. */
+    total: number;
+    /** Whether this bar ends its side of the stack. */
+    outer: boolean;
+}
+/**
+ * Each stacked bar's {@link StackTotal}: segments grouped by category and
+ * sign, each side's total carried by the segment reaching furthest its way.
+ * Zero and non-finite segments belong to no side (`undefined`).
+ *
+ * @param own - Each bar's own signed value.
+ * @param ends - Where each bar ends on the value axis (the stack's `y2`).
+ * @category Math & helpers
+ */
+export declare function stackTotals(categories: readonly unknown[], own: readonly number[], ends: readonly number[]): (StackTotal | undefined)[];
+/** What a bar's labels read from its dataset. */
+export interface BarLabelSide {
+    /** Each bar's own value (a stacked segment's, not where it ends). */
+    own: readonly number[];
+    /** Where each bar ends. */
+    values: readonly number[];
+    /** Where each bar starts, when not at the baseline. */
+    bases: readonly number[] | undefined;
+    stacked: boolean;
+    /** Whether the stack is of shares (`offset="normalize"`). */
+    normalized: boolean;
+    /** Each stacked bar's side of its stack's total. */
+    totals: readonly (StackTotal | undefined)[] | undefined;
+}
+/** The numbers a bar's labels write: its own (a share, when normalized) and its stack's total when it ends its side. @internal */
+export declare function barLabelValues(side: BarLabelSide, index: number): {
+    share: number;
+    total: number | undefined;
+};
+/** Two ends' label values blended at `u`; a total carried at only one end shows while that end is nearer. @internal */
+export declare function mixBarLabelValues(from: {
+    share: number;
+    total: number | undefined;
+}, to: {
+    share: number;
+    total: number | undefined;
+}, u: number): {
+    share: number;
+    total: number | undefined;
+};
+/** Decimal places a value is written with, so a counting label keeps one width (`"1.5e-7"` has 8). @internal */
+export declare function decimalsOf(value: number): number;

package/dist/math/barbs.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Wind barb glyphs: a shaft with ticks near one end coding magnitude
+ * (pennant 50, full tick 10, half tick 5), built in a local frame (shaft
+ * along +x from the origin) for a caller to place, rotate and scale.
+ */
+import type { Point } from "@sophistry/core/geometry";
+/**
+ * One barb glyph: how many of each tick it decomposed to, and its geometry.
+ *
+ * @category Math & helpers
+ */
+export interface BarbGlyph {
+    pennants: number;
+    fullBarbs: number;
+    halfBarbs: number;
+    /** Polylines and polygons in the local frame: the shaft first, then each tick. */
+    segments: Point[][];
+}
+/** @category Math */
+export interface BarbGlyphOptions {
+    /** Shaft length, local units. @default 1 */
+    shaftLength?: number;
+    /** Spacing between successive ticks along the shaft. Defaults to `shaftLength / 6`. */
+    barbSpacing?: number;
+    /** Tick length, local units. Defaults to `shaftLength / 2`. */
+    barbLength?: number;
+}
+/**
+ * Local-frame geometry for a wind barb: a shaft from the origin to
+ * `(shaftLength, 0)` plus ticks stepping in from the far end, each at 45° on
+ * the `-y` side. Negative or `NaN` magnitudes draw a bare shaft (calm).
+ *
+ * @param magnitude - Wind speed in the tick values' units (conventionally knots).
+ * @category Math & helpers
+ */
+export declare function barbGlyph(magnitude: number, options?: BarbGlyphOptions): BarbGlyph;

package/dist/math/boxplot.d.ts

@@ -0,0 +1,36 @@
+/** Box-and-whisker statistics: quartiles, median, whiskers clipped to Tukey's fences, and outliers beyond them. */
+/** @category Math */
+export interface BoxplotStats {
+    min: number;
+    q1: number;
+    median: number;
+    q3: number;
+    max: number;
+    /** Lower whisker end — the smallest finite value still inside the fence. */
+    low: number;
+    /** Upper whisker end — the largest finite value still inside the fence. */
+    high: number;
+    /** Finite values outside `[q1 - whiskerScale * iqr, q3 + whiskerScale * iqr]`. */
+    outliers: number[];
+}
+/** @category Math */
+export interface BoxplotOptions {
+    /** How many IQRs past q1/q3 the whiskers may reach before a point is an outlier. @default 1.5 */
+    whiskerScale?: number;
+}
+/**
+ * `BoxplotOptions.whiskerScale`'s default.
+ *
+ * @category Math & helpers
+ */
+export declare const DEFAULT_WHISKER_SCALE = 1.5;
+/**
+ * Five-number summary of `values` by Tukey's rule: whiskers reach the most
+ * extreme value within `whiskerScale * iqr` of the box; anything further is
+ * an outlier.
+ *
+ * @param values - Raw samples; non-finite entries are dropped.
+ * @returns The summary, or `null` when no finite value remains.
+ * @category Math & helpers
+ */
+export declare function boxplotStats(values: readonly number[], options?: BoxplotOptions): BoxplotStats | null;