@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/props.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Props shared by chart marks, documented once here: the data transition
+ * (`to`, `blend`, `staging`, `enterStagger`, `key`), the staggered reveal
+ * (`stagger`) and the named reveal styles. A mark re-declares a prop only
+ * where its meaning is narrower.
+ */
+import type { BandKey } from "@sophistry/core/geometry";
+import type { Channel } from "./data/channels.js";
+import type { JoinStaging } from "./math/join.js";
+/**
+ * Order for `stagger` and `enterStagger`: `"position"` follows the mark's own
+ * layout (along x, by value, by category); `"random"` shuffles by a hash of
+ * each datum's `key`, the same every frame, so it scrubs.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#reveals
+ * @category Charts
+ */
+export type StaggerOrder = "position" | "random";
+/**
+ * How a curve-like mark (`<LinePlot>`, `<Ecdf>`, `<Stairs>`, `<FillBetween>`)
+ * reveals: `"x"` sweeps left to right, `"length"` draws along its arc length.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#reveals
+ * @category Charts
+ */
+export type CurveReveal = "x" | "length";
+/** How `<Density>` reveals: `"x"` sweeps in along x, `"grow"` rises from the baseline. @category Charts */
+export type DensityReveal = "x" | "grow";
+/** How `<StackPlot>` reveals: `"grow"` from the baseline, `"x"` along x, `"length"` by arc length. @category Charts */
+export type StackReveal = "grow" | "x" | "length";
+/** How bars reveal: `"grow"` out of their foot, `"stack"` scaled about zero together, `"fade"` in place. @category Charts */
+export type BarReveal = "grow" | "stack" | "fade";
+/** How a radial mark (`<PieChart>`, `<RadarChart>`) reveals: `"grow"` out from the centre, `"sweep"` round the turn. @category Charts */
+export type RadialReveal = "grow" | "sweep";
+/** How a frame's layers reveal: `"layers"` each its own way, `"x"` behind one shared front. @category Charts */
+export type LayersReveal = "layers" | "x";
+/**
+ * A mark's data transition from `data` to `to`, driven by `blend`.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+ * @category Charts
+ */
+export interface TransitionProps<T> {
+    /**
+     * The data to transition to. Marks in both `data` and `to` move, marks only
+     * in `to` enter, marks only in `data` exit. At `blend` 0 the chart shows
+     * `data`, at 1 it shows `to`.
+     */
+    to?: readonly T[];
+    /** Transition progress from `data` (0) to `to` (1). @default 0 */
+    blend?: number;
+    /**
+     * How `blend` is spent: `"staged"` runs exit, then move, then enter, each
+     * eased (so drive `blend` linearly); `"together"` runs all at once, linearly.
+     * @default "staged"
+     */
+    staging?: JoinStaging;
+    /**
+     * Fraction of the enter stage spent staggering entering marks in `to`'s
+     * order, 0..0.95; 0 enters them together. Moves and exits never stagger.
+     * @default 0
+     */
+    enterStagger?: number;
+}
+/**
+ * {@link TransitionProps} for a per-datum mark, matching data between the
+ * two ends by `key`.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+ * @category Charts
+ */
+export interface KeyedTransitionProps<T> extends TransitionProps<T> {
+    /**
+     * Each mark's identity: a key of `T` or `(d, i) => key`. A datum with the
+     * same key keeps its mark across updates and transitions. Defaults to the datum's index.
+     */
+    key?: Channel<T, BandKey>;
+}
+/**
+ * {@link TransitionProps} for a mark drawing one shape per `series` (lines,
+ * curves, areas): shapes are matched by `series` and morphed.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+ * @category Charts
+ */
+export interface SeriesTransitionProps<T> extends TransitionProps<T> {
+    /** As {@link TransitionProps.staging}, with series morphing in the move stage. @default "staged" */
+    staging?: JoinStaging;
+    /**
+     * Fraction of the enter stage spent staggering entering series in `to`'s
+     * order, 0..0.95; each sweeps in over its own share. Moves and exits never
+     * stagger.
+     * @default 0
+     */
+    enterStagger?: number;
+}
+/**
+ * A mark's staggered reveal.
+ *
+ * @see https://sophistry.dev/guides/chart-animation/#reveals
+ * @category Charts
+ */
+export interface RevealProps {
+    /**
+     * Fraction of the reveal spent staggering one mark after the next, 0..0.95;
+     * 0 reveals all marks together.
+     * @default 0
+     */
+    stagger?: number;
+}
+/** Checks at compile time that a key list names every key of `P` and nothing else. */
+export declare const TRANSITION_KEYS: readonly ["to", "blend", "staging", "enterStagger"];
+/** {@link KeyedTransitionProps}' keys. */
+export declare const KEYED_TRANSITION_KEYS: readonly ["to", "blend", "staging", "enterStagger", "key"];
+/** {@link RevealProps}' keys. */
+export declare const REVEAL_KEYS: readonly ["stagger"];
+/**
+ * The datum type chart definitions are declared over. A definition is one
+ * value (`scatter`), not a generic function, so its props cannot follow the
+ * type of `data`; over `any`, a channel key is any string and a channel
+ * function receives the datum untyped. Annotate the function's parameter
+ * (`(d: Row) => d.sales`) for checked reads.
+ *
+ * @category Channels
+ */
+export type AnyDatum = any;

package/dist/radial/chord.d.ts

@@ -0,0 +1,148 @@
+/**
+ * `chord`: flows between groups round a circle.
+ *
+ * Two path batches: the ribbons (each its own fill and fade, paint order
+ * under the ring) and the group arcs (each its own fill). Hover, taps,
+ * tooltips and accessible names resolve per ribbon and per arc through
+ * `event.item` / `itemLabel`. Group names are anchored `label` nodes.
+ */
+import type { ColorInput } from "@sophistry/core";
+import type { Point } from "@sophistry/core/geometry";
+import type { Channel, ColorChannel, RequiredUnless } from "../data/channels.js";
+import type { SankeyId } from "../math/sankey.js";
+import type { TooltipSpec } from "../tooltip.js";
+/** @category Charts */
+export interface ChordBaseProps<L, N> {
+    /** The flows, one per datum; flows between the same two groups (same direction) add up. */
+    data: readonly L[];
+    /** The group a flow leaves. */
+    source: Channel<L, SankeyId>;
+    /** The group a flow enters. */
+    target: Channel<L, SankeyId>;
+    /** The flow's size; non-finite and negative values count as 0. */
+    value: Channel<L, number>;
+    /**
+     * The groups, in the order they go round the circle and are coloured. Every id a flow names
+     * must be here (else throws). Defaults to the flows' endpoints in first-seen order.
+     */
+    nodes?: readonly N[];
+    /**
+     * A group's id, matched against `source`/`target`. Defaults to the datum itself, when `nodes`
+     * is `(string | number)[]`.
+     */
+    nodeId?: Channel<N, SankeyId>;
+    /** The text beside a group's arc. Defaults to its id. */
+    nodeLabel?: Channel<N, string>;
+    /** Centre of the diagram. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Outer radius of the ring; labels sit outside it.
+     * @default 2
+     */
+    radius?: number;
+    /** Thickness of the ring. Defaults to 0.08 × `radius`. */
+    thickness?: number;
+    /**
+     * Gap between neighbouring groups, in radians.
+     * @default 0.04
+     */
+    padAngle?: number;
+    /**
+     * Angle the first group begins at, in radians from +x. The default is 12 o'clock.
+     * @default Math.PI / 2
+     */
+    startAngle?: number;
+    /**
+     * Go round clockwise.
+     * @default true
+     */
+    clockwise?: boolean;
+    /**
+     * One chord per flow direction, and arcs sized by inflow plus outflow, so a group that only
+     * receives still shows. Otherwise one chord per pair of groups, arcs sized by outflow.
+     * @default false
+     */
+    directed?: boolean;
+    /**
+     * With `directed`: draw each chord's receiving end as an arrowhead.
+     * @default false
+     */
+    arrows?: boolean;
+    /** Length of an arrowhead. Defaults to 0.08 × `radius`. */
+    arrowSize?: number;
+    /** Group colours, cycled by group order. Defaults to the theme's categorical colours. */
+    colors?: readonly ColorInput[];
+    /**
+     * A chord's colour: its `"source"` group's (the larger end, or the sender when `directed`), its
+     * `"target"` group's, or a colour channel given the chord's first flow.
+     * @default "source"
+     */
+    ribbonColor?: "source" | "target" | ColorChannel<L>;
+    /**
+     * Fill opacity of the chords, 0..1.
+     * @default 0.55
+     */
+    ribbonOpacity?: number;
+    /**
+     * Draw group labels.
+     * @default true
+     */
+    labels?: boolean;
+    /**
+     * Font size of group labels.
+     * @default 0.22
+     */
+    labelFontSize?: number;
+    /**
+     * Reveal, 0..1: the ring sweeps round from `startAngle` with its labels, then the chords fade
+     * in.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the chords' reveal spent staggering them, 0..0.95.
+     * @default 0.5
+     */
+    stagger?: number;
+    /**
+     * Hover tooltip: `true` shows "A → B: value" on a chord and "name: value" on a group; a
+     * function replaces the chord text, given its first flow.
+     */
+    tooltip?: TooltipSpec<L>;
+    /** Paint order of the chords; the ring paints above them. */
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * Props of {@link chord}: `nodeId` is required when `nodes` holds records.
+ *
+ * @category Charts
+ */
+export type ChordProps<L, N = SankeyId> = ChordBaseProps<L, N> & RequiredUnless<N, SankeyId, "nodeId">;
+/**
+ * A chord diagram: flows between groups round a circle. Each group is an arc as long as its
+ * total, and each pair with any flow is joined by a ribbon as wide as the flow each way. Takes
+ * `source`/`target`/`value` like `sankey`; draws in scene units. Ribbons and arcs are one path
+ * batch each. See {@link chordLayout} and {@link chordRibbon} for the geometry alone.
+ *
+ * @example
+ * ```ts
+ * import { chord } from "@sophistry/charts";
+ *
+ * chord.create({
+ * 	data: [
+ * 		{ from: "north", to: "south", n: 5 },
+ * 		{ from: "south", to: "north", n: 3 },
+ * 	],
+ * 	source: "from",
+ * 	target: "to",
+ * 	value: "n",
+ * 	tooltip: true,
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#flows
+ * @category Charts
+ */
+export declare const chord: import("@sophistry/core").Definition<ChordBaseProps<any, any>, import("@sophistry/core/internal").CompositeNode<ChordBaseProps<any, any>>, keyof ChordBaseProps<any, any>>;

package/dist/radial/gauge.d.ts

@@ -0,0 +1,126 @@
+/**
+ * `gauge`: one value on an arc with a centre readout.
+ *
+ * One reading, so mostly single nodes: the track and the value arc
+ * (`annularSector`), the needle and its hub, the counting readout
+ * (`decimalNumber`) and the captions. The threshold bands, one outline each,
+ * draw as one path batch. Nodes are made once and shown or hidden; none is
+ * rebuilt while the reveal plays.
+ */
+import type { ColorInput } from "@sophistry/core";
+import type { Point } from "@sophistry/core/geometry";
+import type { TooltipSpec } from "../tooltip.js";
+/**
+ * One threshold zone of a {@link gauge}, given by where it *ends*.
+ *
+ * @category Charts
+ */
+export interface GaugeBand {
+    /**
+     * The value this band runs up to, in data units, starting where the previous band ends (or at
+     * `min`). `Infinity` means "to `max`".
+     */
+    to: number;
+    /** The band's colour. Defaults to the theme's categorical colours, by band index. */
+    color?: ColorInput;
+}
+/** @category Charts */
+export interface GaugeProps {
+    /**
+     * The reading, in data units. Drawn clamped to `[min, max]`; the readout shows it unclamped.
+     */
+    value: number;
+    /**
+     * The value at the start of the arc.
+     * @default 0
+     */
+    min?: number;
+    /**
+     * The value at the end of the arc.
+     * @default 100
+     */
+    max?: number;
+    /** Centre of the gauge. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Outer radius of the arc.
+     * @default 1
+     */
+    radius?: number;
+    /** Radial thickness of the arc. Defaults to 0.18 × `radius`. */
+    thickness?: number;
+    /**
+     * Where `min` sits, in radians from +x (counter-clockwise positive, as on `arc`). The default
+     * is 210°: with the default `endAngle`, a 240° arc open at the bottom.
+     * @default 7 * Math.PI / 6
+     */
+    startAngle?: number;
+    /**
+     * Where `max` sits, in radians from +x; less than `startAngle` reads clockwise.
+     * @default -Math.PI / 6
+     */
+    endAngle?: number;
+    /**
+     * Threshold zones in ascending order (`[{ to: 60 }, { to: 85 }, { to: 100 }]`), drawn as a thin
+     * track inside the arc. Unless `color` is given, the value arc takes its band's colour.
+     */
+    bands?: readonly GaugeBand[];
+    /**
+     * Colour of the value arc. Defaults to the value's band colour, else the theme's first series
+     * colour.
+     */
+    color?: ColorInput;
+    /** Colour of the empty track behind the value arc. Defaults to the theme's grid colour. */
+    trackColor?: ColorInput;
+    /**
+     * Draw a needle from the centre to the value.
+     * @default false
+     */
+    needle?: boolean;
+    /**
+     * Decimal places of the readout (and tooltip).
+     * @default 0
+     */
+    decimalPlaces?: number;
+    /** Suffix on the readout, e.g. `"%"` or `" ms"`. */
+    unit?: string;
+    /** Readout font size. Defaults to 0.36 × `radius`. */
+    valueFontSize?: number;
+    /** Caption under the readout. */
+    label?: string;
+    /** Font size of `label` and the range labels. Defaults to 0.14 × `radius`. */
+    labelFontSize?: number;
+    /**
+     * Write `min` and `max` at the ends of the arc.
+     * @default true
+     */
+    rangeLabels?: boolean;
+    /**
+     * Reveal, 0..1: track and bands sweep in first, then the value arc sweeps to the value while
+     * the readout counts up.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /** Hover tooltip on the value arc: `true` for "label: value", or `(value) => string`. */
+    tooltip?: TooltipSpec<number>;
+    /** Paint order; higher draws later. */
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * A gauge: one value on an arc with a centre readout, the KPI dial of a dashboard. Optional
+ * threshold `bands` colour the value by zone; `needle` adds a pointer. Draws in scene units;
+ * needs no `chart`.
+ *
+ * @example
+ * ```ts
+ * import { gauge } from "@sophistry/charts";
+ *
+ * gauge.create({ value: 72, unit: "%", label: "CPU", bands: [{ to: 60 }, { to: 85 }, { to: 100 }] });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#gauges-bullets-waffles-mosaics-and-radial-bars
+ * @category Charts
+ */
+export declare const gauge: import("@sophistry/core").Definition<GaugeProps, import("@sophistry/core/internal").CompositeNode<GaugeProps>, keyof GaugeProps>;

package/dist/radial/index.d.ts

@@ -0,0 +1,15 @@
+/** Family barrel: radial. Owned by its family; re-exported from the package entry. */
+export type { ChordBaseProps, ChordProps } from "./chord.js";
+export { chord } from "./chord.js";
+export type { GaugeBand, GaugeProps } from "./gauge.js";
+export { gauge } from "./gauge.js";
+export type { PieChartBaseProps, PieChartProps } from "./pie-chart.js";
+export { pieChart } from "./pie-chart.js";
+export type { PolarAreaChartBaseProps, PolarAreaChartProps, } from "./polar-area-chart.js";
+export { polarAreaChart } from "./polar-area-chart.js";
+export type { RadarChartBaseProps, RadarChartProps } from "./radar-chart.js";
+export { radarChart } from "./radar-chart.js";
+export type { RadialBarChartBaseProps, RadialBarChartProps, } from "./radial-bar-chart.js";
+export { radialBarChart } from "./radial-bar-chart.js";
+export type { WaffleBaseProps, WaffleProps } from "./waffle.js";
+export { waffle } from "./waffle.js";

package/dist/radial/pie-chart.d.ts

@@ -0,0 +1,143 @@
+/**
+ * `pieChart`: a pie (or doughnut) of one wedge per datum.
+ *
+ * The wedges draw as one path batch: each item is the native curve outline
+ * of a `sector` (or `annularSector`, with a hole), with its own
+ * fill; the stroke, its width and the fill opacity are shared. Per-wedge
+ * picking and accessible names go through the batch's items (`event.item`,
+ * `itemLabel`). Slice labels stay `label` nodes, one per present slice.
+ */
+import type { ColorInput } from "@sophistry/core";
+import type { BandKey, Point } from "@sophistry/core/geometry";
+import type { Channel, ColorChannel, RequiredUnless } from "../data/channels.js";
+import type { KeyedJoin } from "../math/join.js";
+import type { KeyedTransitionProps, RadialReveal } from "../props.js";
+/** @category Charts */
+export interface PieChartBaseProps<T> extends KeyedTransitionProps<T> {
+    /** One slice per datum. */
+    data: readonly T[];
+    /**
+     * The slice's value, in data units. Defaults to the datum when `data` is `number[]`; required
+     * otherwise. Negative and non-finite values count as 0 (an empty slice).
+     */
+    value?: Channel<T, number>;
+    /**
+     * The slice's visible label. Omitted, a rounded percentage. See `ariaLabel` for the accessible
+     * name.
+     */
+    label?: Channel<T, string>;
+    /**
+     * The chart's accessible name; each slice is announced as `"<ariaLabel>: <slice label>"`.
+     * Omitted, slices are not exposed to assistive technology.
+     */
+    ariaLabel?: string;
+    /** Centre of the chart. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Outer radius.
+     * @default 1
+     */
+    radius?: number;
+    /**
+     * Radius of a hole through the centre, making a doughnut chart. `0` draws a plain pie.
+     * @default 0
+     */
+    innerRadius?: number;
+    /**
+     * Reveal, 0..1: `reveal="grow"` opens every slice at once, keeping their true ratio, until they
+     * close the circle; `"sweep"` wipes round the pie, uncovering slices in data order.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    reveal?: RadialReveal;
+    /**
+     * Angle the first slice begins at, in radians from +x. The default is 12 o'clock.
+     * @default Math.PI / 2
+     */
+    startAngle?: number;
+    /**
+     * Whether slices run clockwise.
+     * @default true
+     */
+    clockwise?: boolean;
+    /** One colour for every slice, or `(d, i) => colour`. Wins over `colors`. */
+    color?: ColorChannel<T>;
+    /** Colours cycled across the slices by index. Defaults to the theme's categorical colours. */
+    colors?: readonly ColorInput[];
+    /**
+     * Whether to draw slice labels.
+     * @default true
+     */
+    labels?: boolean;
+    /** Label font size. */
+    labelFontSize?: number;
+    /** Label colour. Defaults to the theme background. */
+    labelColor?: ColorInput;
+    /**
+     * Each slice's identity across transitions. See {@link KeyedTransitionProps}. Defaults to
+     * `label`, else the index.
+     */
+    key?: Channel<T, BandKey>;
+    /**
+     * The data to transition to, matched to `data` by `key`: values blend and the pie is re-laid
+     * out every frame, so the slices always fill the turn; leaving slices shrink away, new ones
+     * open up. See {@link KeyedTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /** Slice outline. Defaults to the theme background. */
+    stroke?: ColorInput;
+    /**
+     * Outline width.
+     * @default 0.02
+     */
+    strokeWidth?: number;
+    /** Fill opacity of the slices, 0..1. */
+    fillOpacity?: number;
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the chart. */
+    visible?: boolean;
+}
+/**
+ * Props of {@link pieChart}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export type PieChartProps<T> = PieChartBaseProps<T> & RequiredUnless<T, number, "value">;
+/**
+ * A pie chart, or a doughnut with `innerRadius`: one slice per value, sized by its share of
+ * the total, separated by a thin background-coloured outline. Draws in scene units; nothing is
+ * drawn if every value is 0. The slices are one path batch (`event.item` is the slice's place
+ * among the drawn ones). See {@link pieSlices} for the angle math alone.
+ *
+ * @example
+ * ```ts
+ * import { pieChart } from "@sophistry/charts";
+ *
+ * pieChart.create({
+ * 	data: [
+ * 		{ lang: "Rust", share: 3 },
+ * 		{ lang: "Go", share: 2 },
+ * 	],
+ * 	value: "share",
+ * 	label: "lang",
+ * 	innerRadius: 0.4,
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#pie-polar-area-and-radar
+ * @category Charts
+ */
+export declare const pieChart: import("@sophistry/core").Definition<PieChartBaseProps<any>, import("@sophistry/core/internal").CompositeNode<PieChartBaseProps<any>>, keyof PieChartBaseProps<any>>;
+/** Both ends' ring orders. */
+export interface RingOrders {
+    from: readonly BandKey[];
+    to: readonly BandKey[];
+}
+/**
+ * The ring order at each end: one order unless the keys both ends have are
+ * reordered. Memoise it on the join (kept by identity while the keys hold).
+ */
+export declare function ringOrders(join: KeyedJoin | undefined, keys: readonly BandKey[]): RingOrders;