@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/bars/candlestick.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `candlestick`: candles (or OHLC bars) for price data. The wicks (and the
+ * OHLC ticks) are one instances node of `line`s, the bodies one of `rect`s.
+ *
+ * On reveal, each line's `progress` channel traces a wick from its low end
+ * and an OHLC tick out from its end, and a body grows from the open
+ * towards the close; a body not started is left out of the batch.
+ * Every wick paints under every body (candles don't overlap, so this
+ * looks the same as painting them candle by candle).
+ */
+import type { ColorInput } from "@sophistry/core/color";
+import type { BandKey } from "@sophistry/core/geometry";
+import type { Channel, PositionValue } from "../data/channels.js";
+import type { TooltipSpec } from "../tooltip.js";
+/**
+ * Props of {@link candlestick}.
+ *
+ * @category Charts
+ */
+export interface CandlestickProps<T = unknown> {
+    /** One candle per datum: a period. */
+    data: readonly T[];
+    /**
+     * The period: a `Date`, Temporal value or epoch ms on a time axis, a number, or a category on a
+     * band axis.
+     */
+    x: Channel<T, BandKey | PositionValue>;
+    /** Price at the period's open. */
+    open: Channel<T, number>;
+    /** Highest price in the period. */
+    high: Channel<T, number>;
+    /** Lowest price in the period. */
+    low: Channel<T, number>;
+    /** Price at the period's close. */
+    close: Channel<T, number>;
+    /**
+     * Body width: a fraction of the band on a band axis, or of the smallest gap between periods on
+     * a continuous one.
+     * @default 0.6
+     */
+    bodyWidth?: number;
+    /**
+     * Draw OHLC bars (open tick left, close tick right) instead of candles.
+     * @default false
+     */
+    ohlc?: boolean;
+    /** Colour of a period that closed up. Defaults to the theme's positive colour. */
+    upColor?: ColorInput;
+    /** Colour of a period that closed down. Defaults to the theme's negative colour. */
+    downColor?: ColorInput;
+    /** Wick and OHLC line width. */
+    strokeWidth?: number;
+    /**
+     * Reveal, 0..1: each wick draws from low to high, then its body grows from open to close.
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the reveal spent staggering period after period in time order, 0..0.95.
+     * @default 0
+     */
+    stagger?: number;
+    /**
+     * Hover tooltip: `true` for a row per channel (`x`, `open`, `high`, `low`, `close`), or a
+     * template, function or options. See {@link TooltipSpec}.
+     */
+    tooltip?: TooltipSpec<T>;
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * Candlesticks (or OHLC bars) for price data, inside a `chart` on a time
+ * axis (`xAxis: { scale: "utc" }`) or a category axis. Wicks span low to
+ * high, bodies open to close coloured by direction; the value axis fits the
+ * prices without forcing zero.
+ *
+ * @example
+ * ```ts
+ * import { candlestick, chart } from "@sophistry/charts";
+ *
+ * const prices = [
+ * 	{ day: new Date("2024-03-04"), o: 101, h: 106, l: 99, c: 104 },
+ * 	{ day: new Date("2024-03-05"), o: 104, h: 105, l: 97, c: 98 },
+ * 	{ day: new Date("2024-03-06"), o: 98, h: 103, l: 96, c: 102 },
+ * ];
+ * chart.create({
+ * 	width: 8,
+ * 	height: 4,
+ * 	xAxis: { scale: "utc" },
+ * 	children: [candlestick.create({ data: prices, x: "day", open: "o", high: "h", low: "l", close: "c" })],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#waterfalls-funnels-and-candlesticks
+ * @category Charts
+ */
+export declare const candlestick: import("@sophistry/core").Definition<CandlestickProps<any>, import("@sophistry/core/internal").CompositeNode<CandlestickProps<any>>, keyof CandlestickProps<any>>;

package/dist/bars/funnel.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `funnel`: how many make it through each stage of a process. A preset: a
+ * `chart` with a band y axis whose one layer (the internal `FunnelStages`)
+ * draws the stages as one instances node of `rect`s, the necks between them
+ * as one path batch (each neck is its own trapezoid), and the names and
+ * values as label nodes.
+ */
+import type { ColorInput } from "@sophistry/core/color";
+import type { Point } from "@sophistry/core/geometry";
+import type { Channel, ColorChannel } from "../data/channels.js";
+import type { TooltipSpec } from "../tooltip.js";
+/**
+ * Props of {@link funnel}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export interface FunnelProps<T = unknown> {
+    /** One stage per datum, widest (first) at the top. */
+    data: readonly T[];
+    /** How many reached this stage. Defaults to the datum when `data` is `number[]`. */
+    value?: Channel<T, number>;
+    /** The stage's name, drawn to its left. Omitted, no names are drawn. */
+    label?: Channel<T, string>;
+    /** 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;
+    /** One colour for every stage, or `(d, i) => colour`. Wins over `colors`. */
+    color?: ColorChannel<T>;
+    /** Colours cycled across the stages. Defaults to the theme's categorical colours. */
+    colors?: readonly ColorInput[];
+    /**
+     * Fill opacity of the stages, 0..1.
+     * @default 0.85
+     */
+    fillOpacity?: number;
+    /**
+     * Gap between stages, as a fraction of a stage's slot.
+     * @default 0.25
+     */
+    padding?: number;
+    /**
+     * Shade the narrowing between stages.
+     * @default true
+     */
+    connectors?: boolean;
+    /**
+     * What to write in each stage: `"value"`, `"percent"` (of the first stage), `"both"`, or
+     * `"none"`.
+     * @default "both"
+     */
+    show?: "value" | "percent" | "both" | "none";
+    /** Title above the chart. */
+    title?: string;
+    /**
+     * Reveal, 0..1: stage names first, then each stage widens out from the centre, top to bottom.
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the data reveal spent staggering stage after stage, 0..0.95.
+     * @default 0.5
+     */
+    stagger?: number;
+    /** Hover tooltip: `true` for "stage: value (pct)", or `(d, i) => string`. */
+    tooltip?: TooltipSpec<T>;
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * A funnel: how many make it through each stage of a process. Stages stack
+ * top-down, each centred with a width proportional to its value, shaded
+ * necks showing the loss between them. A `chart` with a band y axis and no
+ * value axis.
+ *
+ * @example
+ * ```ts
+ * import { createScene } from "@sophistry/core";
+ * import { funnel } from "@sophistry/charts";
+ *
+ * const scene = createScene({ host: document.querySelector("#figure")!, units: 10 });
+ * scene.add(funnel.create({ data: [1200, 640, 310, 95], width: 6, height: 4 }));
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#waterfalls-funnels-and-candlesticks
+ * @category Charts
+ */
+export declare const funnel: import("@sophistry/core").Definition<FunnelProps<any>, import("@sophistry/core/internal").CompositeNode<FunnelProps<any>>, keyof FunnelProps<any>>;

package/dist/bars/histogram.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `histogram`: values bucketed into equal-width bins, one touching bar per
+ * bin, drawn as one instances node of `rect`s keyed by the bin's place.
+ *
+ * The reveal and a transition's presence grow each bar's top from the
+ * baseline (geometry) or, on an axis without zero, fade it (per-item
+ * opacity); a bin not started is left out of the batch (it counts as
+ * `progress` 0).
+ */
+import type { ColorInput } from "@sophistry/core/color";
+import type { Range } from "@sophistry/core/geometry";
+import type { MarkTransition } from "../batch.js";
+import type { Channel } from "../data/channels.js";
+import type { RevealProps, TransitionProps } from "../props.js";
+/**
+ * Props of {@link histogram}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export interface HistogramProps<T = unknown> extends TransitionProps<T>, RevealProps {
+    /** One observation per datum. */
+    data: readonly T[];
+    /**
+     * The observed value, in data units. Defaults to the datum when `data` is `number[]`; required
+     * otherwise. Non-finite values and values outside `range` are not counted.
+     */
+    value?: Channel<T, number>;
+    /**
+     * Number of equal-width bins. Wins over a `range` step. Defaults to the count the `range` step
+     * implies, else 10.
+     */
+    binCount?: number;
+    /**
+     * `[min, max, step?]` spanned by the bins, in data units; `step` is the bin width when
+     * `binCount` is not given (`[0, 10, 2]` is five bins). Defaults to the finite extent of the
+     * values.
+     */
+    range?: Range;
+    /** Fill of every bar. Defaults to the theme's first series colour. */
+    color?: ColorInput;
+    /**
+     * Fill opacity, 0..1.
+     * @default 0.85
+     */
+    fillOpacity?: number;
+    /** Outline colour. @default "none" */
+    stroke?: string;
+    /** Outline width. */
+    strokeWidth?: number;
+    /** Opacity 0..1. @default 1 */
+    opacity?: number;
+    /**
+     * Reveal, 0..1: bars grow from the baseline (fading in when the axis has no zero).
+     * @default 1
+     */
+    progress?: number;
+    /**
+     * Fraction of the reveal spent staggering bin after bin, left to right, 0..0.95.
+     * @default 0
+     */
+    stagger?: number;
+    /**
+     * The data to transition to, bins matched by place: shared bins move their edges and counts, so
+     * every frame is a histogram; extra bins grow in or shrink away. See {@link TransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /**
+     * `to`'s bin count; `to={data}` with a new `toBinCount` re-bins as a transition. Defaults to
+     * `binCount`.
+     */
+    toBinCount?: number;
+    /** `to`'s binning range, as `range`. Defaults to `range`. */
+    toRange?: Range;
+    /**
+     * Fraction of a transition's enter stage spent staggering entering bins, left to right. See
+     * {@link TransitionProps}.
+     * @default 0
+     */
+    enterStagger?: number;
+    /**
+     * How bars move when `data` changes (outside a `to` blend): a tween or a
+     * spring in the node's tween bank. Omitted, data changes are instant.
+     */
+    transition?: MarkTransition;
+    /** Paint order; the bars paint at `zIndex + UNDER_AXES_Z_INDEX`. */
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * A histogram: values bucketed into equal-width bins, one touching bar per
+ * bin, its height the count. `progress` grows bars from the baseline
+ * (fading in when the axis has no zero). Inside a `chart` (which fits the
+ * counts) or an `axes`. See {@link histogramBins} for the binning rule (the
+ * last bin is right-inclusive). Drawn as one instances node of rects.
+ *
+ * @example
+ * ```ts
+ * import { chart, histogram } from "@sophistry/charts";
+ *
+ * const heights = [162, 170, 175, 168, 181, 159, 177, 173, 166, 185, 171, 169];
+ * chart.create({ width: 8, height: 4, children: [histogram.create({ data: heights, binCount: 12 })] });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#histograms
+ * @category Charts
+ */
+export declare const histogram: import("@sophistry/core").Definition<HistogramProps<any>, import("@sophistry/core/internal").CompositeNode<HistogramProps<any>>, keyof HistogramProps<any>>;

package/dist/bars/index.d.ts

@@ -0,0 +1,22 @@
+/** Family barrel: bars and their kin. Owned by its family; re-exported from the package entry. */
+export type { BarChartHandle, BarChartProps } from "./bar-chart.js";
+export { barChart, barChartHandle } from "./bar-chart.js";
+export type { BarLabelOptions } from "./bar-labels.js";
+export type { BarsHandle, BarsProps } from "./bars.js";
+export { bars, barsHandle } from "./bars.js";
+export type { BulletProps } from "./bullet.js";
+export { bullet, bulletTooltip } from "./bullet.js";
+export type { CandlestickProps } from "./candlestick.js";
+export { candlestick } from "./candlestick.js";
+export type { FunnelProps } from "./funnel.js";
+export { funnel } from "./funnel.js";
+export type { HistogramProps } from "./histogram.js";
+export { histogram } from "./histogram.js";
+export type { RankRaceOptions } from "./race.js";
+export { rankRace } from "./race.js";
+export type { RuleBaseProps, RuleXProps, RuleYProps } from "./rules.js";
+export { ruleX, ruleY } from "./rules.js";
+export type { BinnedRow, BinOptions, DodgedRow, DodgeOptions, GroupedRow, GroupOptions, JitterTransformOptions, NormalizeOptions, RollingTransformOptions, StackedRow, StackOptions, SummarizeOptions, SummaryRow, } from "./transforms.js";
+export { bin, dodge, group, jitter, normalize, rolling, stack, summarize, } from "./transforms.js";
+export type { WaterfallProps } from "./waterfall.js";
+export { waterfall } from "./waterfall.js";

package/dist/bars/race.d.ts

@@ -0,0 +1,28 @@
+/** `rankRace`: a bar chart race from long-format rows. */
+import type { BandKey } from "@sophistry/core/geometry";
+import type { Channel } from "../data/channels.js";
+import type { RaceOptions, RaceTimeline } from "../math/keyframes.js";
+/**
+ * Options for {@link rankRace}.
+ *
+ * @category Charts
+ */
+export interface RankRaceOptions<T> extends RaceOptions {
+    /** What races: a key of `T` or `(d, i) => key`. */
+    key: Channel<T, BandKey>;
+    /** When the row's value holds: a key of `T` or `(d, i) => number`. */
+    time: Channel<T, number>;
+    /** The value: a key of `T` or `(d, i) => number`. */
+    value: Channel<T, number>;
+}
+/**
+ * A bar chart race from long-format rows (one per key per moment): see
+ * {@link raceTimeline}. Missing keys count as 0; duplicate rows are summed.
+ * Pass `view(time)`'s `categories` and `slot` to the `chart`'s `yAxis` (with
+ * `clip`) so bars and names slide together, and pin colours with
+ * `chart.create({ color: { domain: race.keys } })`.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+ * @category Charts
+ */
+export declare function rankRace<T>(rows: readonly T[], options: RankRaceOptions<T>): RaceTimeline;

package/dist/bars/rules.d.ts

@@ -0,0 +1,121 @@
+/**
+ * `ruleX` / `ruleY`: reference lines across the plot, or segments between
+ * given ends, one per datum, drawn as one instances node of `line`s.
+ *
+ * Batched like every per-datum mark (see `points/scatter.ts`): each update
+ * builds one item per key (its two ends in scene units and its colour) and
+ * hands them to {@link createBatchedMark}. The reveal (and an entering or
+ * leaving rule's presence) is each item's `progress` channel: the line
+ * traces from its low end.
+ */
+import type { BandKey } from "@sophistry/core/geometry";
+import type { MarkTransition } from "../batch.js";
+import type { Channel, ColorChannel, PositionValue } from "../data/channels.js";
+import type { KeyedTransitionProps, RevealProps } from "../props.js";
+import type { TooltipSpec } from "../tooltip.js";
+/**
+ * Props every rule takes.
+ *
+ * @category Charts
+ */
+export interface RuleBaseProps<T> extends KeyedTransitionProps<T>, RevealProps {
+    /** One rule per datum. `ruleY.create({ data: [0] })` is a zero line. */
+    data: readonly T[];
+    /** Rule colour, constant or `(d, i) => colour`. Defaults to the theme foreground. */
+    color?: ColorChannel<T>;
+    /** Line width. */
+    strokeWidth?: number;
+    /** Dash pattern, as on any line: `[0.1, 0.08]`. */
+    dash?: number[];
+    opacity?: number;
+    /**
+     * Reveal, 0..1: each rule draws from its low end to its high end.
+     * @default 1
+     */
+    progress?: number;
+    /**
+     * Hover tooltip: `true` for the rule's value, or a template, function or options. See {@link
+     * TooltipSpec}.
+     */
+    tooltip?: TooltipSpec<T>;
+    /**
+     * How rules move when `data` changes (outside a `to` blend): a tween or a
+     * spring in the node's tween bank; new rules draw out of their low end,
+     * removed ones draw back into it. Omitted, data changes are instant.
+     */
+    transition?: MarkTransition;
+    zIndex?: number;
+    visible?: boolean;
+    /**
+     * The data to transition to, matched to `data` by `key`: rules slide and stretch to their new
+     * place; new ones draw out, removed ones draw back in. See {@link KeyedTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+}
+/**
+ * Props of {@link ruleX}: `x` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export interface RuleXProps<T = unknown> extends RuleBaseProps<T> {
+    /**
+     * Where the vertical rule stands: a number in data units (a `Date` reads as epoch ms) or a
+     * category on a band axis. Defaults to the datum when `data` is `number[]`.
+     */
+    x?: Channel<T, BandKey | PositionValue>;
+    /** Lower end, in data units. Defaults to the bottom of the plotting area. */
+    y1?: Channel<T, PositionValue>;
+    /** Upper end, in data units. Defaults to the top of the plotting area. */
+    y2?: Channel<T, PositionValue>;
+}
+/**
+ * Props of {@link ruleY}: `y` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export interface RuleYProps<T = unknown> extends RuleBaseProps<T> {
+    /**
+     * Height of the horizontal rule: a number in data units (a `Date` reads as epoch ms) or a
+     * category on a band axis. Defaults to the datum when `data` is `number[]`.
+     */
+    y?: Channel<T, BandKey | PositionValue>;
+    /** Left end, in data units. Defaults to the left of the plotting area. */
+    x1?: Channel<T, PositionValue>;
+    /** Right end, in data units. Defaults to the right of the plotting area. */
+    x2?: Channel<T, PositionValue>;
+}
+/**
+ * Vertical reference lines across the plot; `y1`/`y2` shorten them to
+ * segments (a lollipop's stick, a candle's wick). Inside a `chart` or
+ * `axes`. Drawn as one instances node of lines: `event.key` is the datum's
+ * key.
+ *
+ * @example
+ * ```ts
+ * import { chart, ruleX } from "@sophistry/charts";
+ *
+ * chart.create({ width: 8, height: 4, children: [ruleX.create({ data: [2, 5], dash: [0.1, 0.08] })] });
+ * ```
+ *
+ * @see https://sophistry.dev/guides/charts/#marks
+ * @category Charts
+ */
+export declare const ruleX: import("@sophistry/core").Definition<RuleXProps<any>, import("@sophistry/core/internal").CompositeNode<RuleXProps<any>>, keyof RuleXProps<any>>;
+/**
+ * Horizontal reference lines across the plot; `ruleY.create({ data: [0] })`
+ * is a zero line and `x1`/`x2` shorten them to segments. Inside a `chart`
+ * or `axes`. Drawn as one instances node of lines.
+ *
+ * @example
+ * ```ts
+ * import { chart, linePlot, ruleY } from "@sophistry/charts";
+ *
+ * const data = [-2, 1, 3, -1, 4];
+ * chart.create({ width: 8, height: 4, children: [linePlot.create({ data }), ruleY.create({ data: [0] })] });
+ * ```
+ *
+ * @see https://sophistry.dev/guides/charts/#marks
+ * @category Charts
+ */
+export declare const ruleY: import("@sophistry/core").Definition<RuleYProps<any>, import("@sophistry/core/internal").CompositeNode<RuleYProps<any>>, keyof RuleYProps<any>>;

package/dist/bars/shared.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Helpers the bar family shares: a label placed beside a point, box arithmetic, and the tooltip props a batched node
+ * takes. Internal to the family.
+ */
+import type { Bounds, Placement, Point, Vec2 } from "@sophistry/core";
+import type { TooltipState } from "../tooltip.js";
+/** The metrics style labels are measured in: the label defaults. */
+export declare function labelStyle(fontSize: number, fontFamily: string): {
+    fontSize: number;
+    fontFamily: string;
+    fontWeight: number;
+    italic: boolean;
+    letterSpacing: number;
+};
+/**
+ * Where a label goes to sit beside `at` (in `direction`, `gap` away) rather
+ * than centred on it, measured the same
+ * way core's axes place their end labels (the label's own width, one line
+ * height per font).
+ *
+ * @returns The label's `place`.
+ */
+export declare function besidePlace(text: string, at: Point, direction: Vec2, gap: number, fontSize: number, fontFamily: string): Placement;
+/** A box's centre. */
+export declare function boxCenter(box: Bounds): Point;
+/** The box spanned by two corners. */
+export declare function boxOfCorners(a: Point, b: Point): Bounds;
+/** Whether two boxes are equal field by field. */
+export declare function sameBox(a: Bounds | null, b: Bounds | null): boolean;
+/**
+ * The interaction props a batched node shares for item tooltips: the
+ * handlers when the chart has a tooltip and the mark (or the chart) asks for
+ * one, else none.
+ */
+export declare function tooltipProps(tooltip: TooltipState | null, own: unknown, handlers: {
+    readonly label?: string;
+    readonly onEnter?: unknown;
+    readonly onLeave?: unknown;
+    readonly onTap?: unknown;
+    readonly itemLabel?: unknown;
+}): Record<string, unknown>;