@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/radial/polar-area-chart.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `polarAreaChart`: a rose of equal-angle wedges whose radius carries the
+ * value.
+ *
+ * The wedges draw as one path batch (each item the native outline of a
+ * `sector`, with its own fill); per-wedge picking and accessible names
+ * go through its items. Wedge labels stay `label` nodes. Inside a chart the
+ * layer reports its series (for the legend) and its transition (for the
+ * staging); it fits no axes.
+ */
+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 { KeyedTransitionProps, RevealProps } from "../props.js";
+/** @category Charts */
+export interface PolarAreaChartBaseProps<T> extends KeyedTransitionProps<T>, RevealProps {
+    /** One wedge per datum. */
+    data: readonly T[];
+    /**
+     * The wedge'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 wedge).
+     */
+    value?: Channel<T, number>;
+    /**
+     * The wedge's visible label. Omitted, a rounded percentage. See `ariaLabel` for the accessible
+     * name.
+     */
+    label?: Channel<T, string>;
+    /**
+     * The chart's accessible name; each wedge is announced as `"<ariaLabel>: <wedge label>"`.
+     * Omitted, wedges are not exposed to assistive technology.
+     */
+    ariaLabel?: string;
+    /** Centre of the chart. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Radius a value of `maxValue` reaches.
+     * @default 1
+     */
+    radius?: number;
+    /**
+     * The value that reaches `radius`. Pin it to keep the scale fixed as `data` changes. Defaults
+     * to the greatest value in `data`.
+     */
+    maxValue?: number;
+    /**
+     * Angle the first wedge begins at, in radians from +x. The default is 12 o'clock.
+     * @default Math.PI / 2
+     */
+    startAngle?: number;
+    /**
+     * Whether wedges run clockwise.
+     * @default true
+     */
+    clockwise?: boolean;
+    /**
+     * Reveal, 0..1: one sweep round the chart from `startAngle`, uncovering wedges in data order.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the reveal spent staggering wedge after wedge, 0..0.95; 0 opens every wedge
+     * together. Defaults to one continuous sweep, `(n − 1) / n`.
+     */
+    stagger?: number;
+    /**
+     * The category of each wedge: colours wedges through the chart's shared colour scale and
+     * legend. `color` and `colors` win.
+     */
+    series?: Channel<T, BandKey>;
+    /** One colour for every wedge, or `(d, i) => colour`. Wins over `colors` and `series`. */
+    color?: ColorChannel<T>;
+    /**
+     * Colours cycled across the wedges by index. Wins over `series`. Defaults to the `series`
+     * colours, else the theme's categorical colours.
+     */
+    colors?: readonly ColorInput[];
+    /**
+     * Whether to draw wedge labels.
+     * @default true
+     */
+    labels?: boolean;
+    /** Label font size. */
+    labelFontSize?: number;
+    /** Label colour. Defaults to the theme background. */
+    labelColor?: ColorInput;
+    /**
+     * Each wedge's identity across transitions. See {@link KeyedTransitionProps}. Defaults to
+     * `label`, else the place within its `series`, else the index.
+     */
+    key?: Channel<T, BandKey>;
+    /**
+     * The data to transition to, matched to `data` by `key`: wedges reach out or draw in to their
+     * new value; leaving wedges narrow away and new ones open up as the rest make room. See {@link
+     * KeyedTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /** Wedge outline. Defaults to the theme background. */
+    stroke?: ColorInput;
+    /**
+     * Outline width.
+     * @default 0.02
+     */
+    strokeWidth?: number;
+    /** Fill opacity of the wedges, 0..1. */
+    fillOpacity?: number;
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the chart. */
+    visible?: boolean;
+}
+/**
+ * Props of {@link polarAreaChart}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export type PolarAreaChartProps<T> = PolarAreaChartBaseProps<T> & RequiredUnless<T, number, "value">;
+/**
+ * A polar area (rose) chart: wedges of equal angle whose radius carries the value, linear
+ * against `maxValue`. Draws in scene units; zero-value wedges are skipped. The wedges are one
+ * path batch. See {@link polarAreaSlices} for the wedge math alone.
+ *
+ * @example
+ * ```ts
+ * import { polarAreaChart } from "@sophistry/charts";
+ *
+ * polarAreaChart.create({ data: [4, 2, 3, 1], labels: false, stagger: 0.4 });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#pie-polar-area-and-radar
+ * @category Charts
+ */
+export declare const polarAreaChart: import("@sophistry/core").Definition<PolarAreaChartBaseProps<any>, import("@sophistry/core/internal").CompositeNode<PolarAreaChartBaseProps<any>>, keyof PolarAreaChartBaseProps<any>>;

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

@@ -0,0 +1,176 @@
+/**
+ * `radarChart`: one polygon per series on evenly spaced axes, over a grid of
+ * rings and spokes, with axis names outside.
+ *
+ * The series polygons draw as one path batch (each item a series' outline
+ * with its own fill and stroke colour; fill opacity and stroke width
+ * shared). Under `reveal="sweep"` the clip groups are one wedge that
+ * clips every series while the series' reveal plays, and a series coming or
+ * going (each series, under a staggered sweep) is clipped to its own wedge
+ * inside it. A path batch has one clip, so the series split into runs, each
+ * run a batch under its own pair of groups: one run (one batch) when no
+ * series has a wedge of its own. The grid rings and spokes stay
+ * `polygon` / `line` nodes: they reveal by tracing their stroke
+ * (`progress`), which a path batch does not do per item, and there are a
+ * handful of them. Axis names are `label` nodes.
+ */
+import type { ColorInput } from "@sophistry/core";
+import type { BandKey, ClosedCurveKind, Point } from "@sophistry/core/geometry";
+import type { Channel, ColorChannel, RequiredUnless } from "../data/channels.js";
+import type { KeyedTransitionProps, RadialReveal, RevealProps, StaggerOrder } from "../props.js";
+/** @category Charts */
+export interface RadarChartBaseProps<T> extends KeyedTransitionProps<T>, RevealProps {
+    /** One polygon per datum (a series), all read against the same axes and `maxValue`. */
+    data: readonly T[];
+    /**
+     * The series' value on each axis, one entry per axis. Defaults to the datum when `data` is
+     * `number[][]`; required otherwise.
+     */
+    axisValues?: Channel<T, readonly number[]>;
+    /**
+     * One name per axis, drawn outside the rings; when given, every non-empty group must have
+     * exactly that many values or the chart throws. `false` draws no names; `true` draws them even
+     * when only `toAxisLabels` names the axes.
+     */
+    axisLabels?: boolean | readonly string[];
+    /** Centre of the chart. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Radius a value of `maxValue` reaches.
+     * @default 1
+     */
+    radius?: number;
+    /**
+     * The value that reaches `radius`. Pin it to keep the scale fixed as `data` changes. Defaults
+     * to the greatest value across every series.
+     */
+    maxValue?: number;
+    /**
+     * Angle of the first axis, in radians from +x. The default is 12 o'clock.
+     * @default Math.PI / 2
+     */
+    startAngle?: number;
+    /**
+     * Whether axes run clockwise.
+     * @default true
+     */
+    clockwise?: boolean;
+    /**
+     * The category of each polygon: colours polygons through the chart's shared colour scale and
+     * legend. `color` and `colors` win.
+     */
+    series?: Channel<T, BandKey>;
+    /**
+     * Each polygon's identity across data changes and transitions. See {@link
+     * KeyedTransitionProps}. Defaults to the datum's place within its `series`, else its index.
+     */
+    key?: Channel<T, BandKey>;
+    /** One colour for every series, or `(d, i) => colour`. Wins over `colors` and `series`. */
+    color?: ColorChannel<T>;
+    /**
+     * Colours cycled across the series by index. Wins over `series`. Defaults to the `series`
+     * colours, else the theme's categorical colours.
+     */
+    colors?: readonly ColorInput[];
+    /**
+     * Fill opacity of each polygon.
+     * @default 0.25
+     */
+    fillOpacity?: number;
+    /**
+     * Outline width of each polygon.
+     * @default 0.02
+     */
+    strokeWidth?: number;
+    /**
+     * Number of concentric grid rings under the data.
+     * @default 4
+     */
+    gridRings?: number;
+    /**
+     * Whether to draw the grid rings and spokes.
+     * @default true
+     */
+    grid?: boolean;
+    /**
+     * Axis name font size.
+     * @default 0.28
+     */
+    labelFontSize?: number;
+    /**
+     * Space between the outer ring and each axis name, which is anchored by its side facing the
+     * chart.
+     * @default 0.12
+     */
+    labelGap?: number;
+    /** Colour of the grid rings and spokes. Defaults to the theme's grid colour. */
+    gridColor?: ColorInput;
+    /**
+     * Reveal, 0..1: grid and names first, then the series, which grow out of the centre
+     * (`reveal="grow"`) or are uncovered by a clockwise sweep (`"sweep"`).
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    reveal?: RadialReveal;
+    /**
+     * How each polygon runs between vertices: `"linear"` straight edges or `"catmull-rom"` a smooth
+     * closed spline. The grid stays polygonal.
+     * @default "linear"
+     */
+    curve?: ClosedCurveKind;
+    /**
+     * Fraction of the series' reveal spent staggering polygon after polygon in data order, 0..0.95.
+     * @default 0
+     */
+    stagger?: number;
+    /**
+     * The order `stagger` and `enterStagger` take. See {@link StaggerOrder}.
+     * @default "position"
+     */
+    staggerOrder?: StaggerOrder;
+    /**
+     * The data to transition to, matched to `data` by `key`: each vertex moves along its axis to
+     * its new value. Axes are joined by name (`axisLabels`/`toAxisLabels`), else by position; axes
+     * that come and go fold in and out. See {@link KeyedTransitionProps}.
+     * @see https://sophistry.dev/guides/chart-animation/#data-transitions
+     */
+    to?: readonly T[];
+    /** `to`'s axis names, one per value of each `to` group. Defaults to `axisLabels`. */
+    toAxisLabels?: readonly string[];
+    /** Paint order. */
+    zIndex?: number;
+    /** Set to false to hide the chart. */
+    visible?: boolean;
+}
+/**
+ * Props of {@link radarChart}: `axisValues` is required unless `data` is `number[][]`.
+ *
+ * @category Charts
+ */
+export type RadarChartProps<T> = RadarChartBaseProps<T> & RequiredUnless<T, readonly number[], "axisValues">;
+/**
+ * A radar (spider) chart: one polygon per series, its values on evenly spaced axes around a
+ * full turn, over a grid of rings and spokes. Draws in scene units; needs at least 3 axes.
+ * Pass `maxValue` when the data can change, so the scale stays fixed. The polygons are one
+ * path batch.
+ *
+ * @example
+ * ```ts
+ * import { radarChart } from "@sophistry/charts";
+ *
+ * radarChart.create({
+ * 	data: [
+ * 		{ team: "a", v: [3, 4, 5, 2] },
+ * 		{ team: "b", v: [4, 2, 3, 5] },
+ * 	],
+ * 	axisValues: "v",
+ * 	series: "team",
+ * 	axisLabels: ["Speed", "Power", "Range", "Cost"],
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#pie-polar-area-and-radar
+ * @category Charts
+ */
+export declare const radarChart: import("@sophistry/core").Definition<RadarChartBaseProps<any>, import("@sophistry/core/internal").CompositeNode<RadarChartBaseProps<any>>, keyof RadarChartBaseProps<any>>;

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

@@ -0,0 +1,116 @@
+/**
+ * `radialBarChart`: concentric ring bars, one per datum, the first outermost.
+ *
+ * Two path batches: the faint full-length tracks (one shared paint, faded in
+ * together) and the value arcs (each its own fill; hover, taps, tooltips
+ * and accessible names per ring through `event.item` and `itemLabel`). Ring
+ * names stay `label` nodes.
+ */
+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 { TooltipSpec } from "../tooltip.js";
+/** @category Charts */
+export interface RadialBarChartBaseProps<T> {
+    /** One ring per datum, the first outermost. */
+    data: readonly T[];
+    /**
+     * The ring's value. Defaults to the datum when `data` is `number[]`; required otherwise.
+     * Negative and non-finite values count as 0 (an empty ring).
+     */
+    value?: Channel<T, number>;
+    /** The ring's name, written at its start. */
+    label?: Channel<T, string>;
+    /**
+     * The value that fills a ring's whole `sweep`; larger values are drawn full. Defaults to the
+     * greatest value.
+     */
+    maxValue?: number;
+    /** Centre of the chart. Defaults to the origin. */
+    center?: Point;
+    /**
+     * Outer radius of the outermost ring.
+     * @default 1
+     */
+    radius?: number;
+    /** Inner radius of the innermost ring. Defaults to 0.3 × `radius`. */
+    innerRadius?: number;
+    /** Gap between rings. Defaults to a quarter of a ring's width. */
+    ringGap?: number;
+    /**
+     * Radians a ring of `maxValue` turns through, clockwise from 12 o'clock. The default, 270°,
+     * leaves the top-left quadrant for labels.
+     * @default 3 * Math.PI / 2
+     */
+    sweep?: number;
+    /**
+     * The category of each ring: colours rings through the chart's shared colour scale and legend.
+     * `color` and `colors` win.
+     */
+    series?: Channel<T, BandKey>;
+    /** One colour for every ring, or `(d, i) => colour`. Wins over `colors` and `series`. */
+    color?: ColorChannel<T>;
+    /**
+     * Colours cycled across the rings by index. Wins over `series`. Defaults to the `series`
+     * colours, else the theme's categorical colours.
+     */
+    colors?: readonly ColorInput[];
+    /**
+     * Colour of the faint full-length track behind each ring. Defaults to the theme's grid colour.
+     */
+    trackColor?: ColorInput;
+    /**
+     * Write each ring's `label` at its start.
+     * @default true
+     */
+    labels?: boolean;
+    /** Label font size. Defaults to 0.7 × a ring's width, at most 0.26. */
+    labelFontSize?: number;
+    /**
+     * Reveal, 0..1: tracks and labels fade in, then each ring sweeps clockwise, outermost first.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the bars' reveal spent staggering ring after ring, outer to inner, 0..0.95.
+     * @default 0.3
+     */
+    stagger?: number;
+    /** Hover tooltip: `true` for "label: value", or `(d, i) => string`. */
+    tooltip?: TooltipSpec<T>;
+    /** Paint order; higher draws later. */
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * Props of {@link radialBarChart}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export type RadialBarChartProps<T> = RadialBarChartBaseProps<T> & RequiredUnless<T, number, "value">;
+/**
+ * Concentric ring bars: a bar chart bent round a centre, one ring per datum (the first
+ * outermost), each arc its value over `maxValue`. Outer rings are longer at the same value, so
+ * compare angles, not lengths. Draws in scene units; needs no `chart`.
+ *
+ * @example
+ * ```ts
+ * import { radialBarChart } from "@sophistry/charts";
+ *
+ * radialBarChart.create({
+ * 	data: [
+ * 		{ goal: "Move", pct: 80 },
+ * 		{ goal: "Stand", pct: 50 },
+ * 	],
+ * 	value: "pct",
+ * 	label: "goal",
+ * 	maxValue: 100,
+ * 	tooltip: true,
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#gauges-bullets-waffles-mosaics-and-radial-bars
+ * @category Charts
+ */
+export declare const radialBarChart: import("@sophistry/core").Definition<RadialBarChartBaseProps<any>, import("@sophistry/core/internal").CompositeNode<RadialBarChartBaseProps<any>>, keyof RadialBarChartBaseProps<any>>;

package/dist/radial/shared.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Helpers shared by the radial charts (pie, polar area, radar, radial bars,
+ * gauge, chord, waffle): wedge outlines as path batch items, a per-key item
+ * cache (so an unchanged wedge keeps its prepared outline), keyed label
+ * lists, the far end's colour scale across a keyed transition, and the
+ * standalone tooltip state. Internal to the family.
+ */
+import type { CompositeContext, LabelProps, PathBatchItem, SceneNode } from "@sophistry/core";
+import type { Theme } from "@sophistry/core/themes";
+import type { OrdinalColorScale } from "../math/ordinal.js";
+import type { Category } from "../series.js";
+import type { TooltipState } from "../tooltip.js";
+/** Smallest sweep worth drawing, in radians: what `sector` and `annularSector` skip. */
+export declare const NO_SWEEP = 1e-9;
+/** What a wedge's outline is made from. */
+export interface WedgeShape {
+    cx: number;
+    cy: number;
+    /** 0 for a plain pie slice (`sector`), else a ring slice (`annularSector`). */
+    innerRadius: number;
+    outerRadius: number;
+    startAngle: number;
+    /** Signed sweep, radians; positive is counter-clockwise. */
+    angle: number;
+}
+/**
+ * A wedge as a path batch item: the same native curve geometry `sector` (no
+ * hole) or `annularSector` (a hole) build, so each item outlines exactly
+ * what the per-datum shape does. Undefined when the sweep is too small
+ * to draw (as those shapes draw nothing).
+ *
+ * @param annular - Draw a ring slice even when `innerRadius` is 0.
+ */
+export declare function wedgeItem(shape: WedgeShape, paints: Omit<PathBatchItem, "closed" | "polylines" | "curvePaths">, annular?: boolean): PathBatchItem | undefined;
+/**
+ * A per-key cache of path batch items: hands back last update's item while
+ * its inputs are equal (shallowly), so the batch reuses its prepared outline.
+ * Call `sweep()` after an update to forget keys that were not asked for.
+ */
+export declare function createItemCache<I>(): {
+    get(key: unknown, inputs: readonly unknown[], make: () => I): I;
+    sweep(): void;
+};
+/** One label of a keyed list: its key and the label's props. */
+export interface KeyedLabel {
+    key: unknown;
+    props: LabelProps;
+}
+/**
+ * Keyed `label` nodes for one list (`slot`): a node per key, created once
+ * and updated in place (equal values are no-ops on the node), disposed when
+ * its key leaves.
+ */
+export declare function labelList<P>(ctx: CompositeContext<P>, slot: string, labels: readonly KeyedLabel[]): SceneNode[];
+/**
+ * The colour scale `to`'s series colour through, across a keyed transition:
+ * the chart's shared scale inside a chart (`own`), else one over `to`'s own
+ * categories, as its plain chart has. Call once, in
+ * `setup`.
+ */
+export declare function createFarScale(): (inChart: boolean, toOf: readonly Category[] | undefined, own: OrdinalColorScale, theme: Theme) => OrdinalColorScale;
+/**
+ * The tooltip a standalone radial chart shows through: the enclosing
+ * chart's, else its own. Call once,
+ * in `setup`, and read the result in each `update`.
+ *
+ * Outside a chart the state is kept (handlers, accessible names, the item
+ * walked by the keys) and `overlay(ctx)` returns the panel drawing it, a
+ * {@link tooltipOverlay} bound to the scene's pointer and view: append it to the composite's children. Inside a
+ * chart it returns nothing, the frame's overlay draws the tooltip.
+ */
+export declare function createOwnTooltip(): OwnTooltip;
+/** What {@link createOwnTooltip} returns: the state, and its standalone panel. */
+export interface OwnTooltip {
+    <P>(ctx: CompositeContext<P>): TooltipState;
+    /** The panel to append to the children outside a chart; empty inside one. */
+    overlay<P>(ctx: CompositeContext<P>): SceneNode[];
+}

package/dist/radial/waffle.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `waffle`: a grid of unit cells coloured by category.
+ *
+ * Two instances nodes of `square`: the empty grid (one shared fill, faded
+ * in together) and the filled cells (keyed by their place in the grid, each
+ * its own fill; a cell grows from its centre as its turn in the fill
+ * comes). Hover,
+ * taps and tooltips resolve per cell (`event.item`), each telling its
+ * category. The legend's swatches and labels are single 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 { TooltipSpec } from "../tooltip.js";
+/** @category Charts */
+export interface WaffleBaseProps<T> {
+    /** One category per datum, filling cells in data order. */
+    data: readonly T[];
+    /**
+     * The category's value; only shares matter. Defaults to the datum when `data` is `number[]`;
+     * required otherwise. Negative and non-finite values count as 0.
+     */
+    value?: Channel<T, number>;
+    /** The category's name, for the legend and tooltips. */
+    label?: Channel<T, string>;
+    /**
+     * Rows of cells.
+     * @default 10
+     */
+    rows?: number;
+    /**
+     * Columns of cells.
+     * @default 10
+     */
+    columns?: number;
+    /**
+     * Width of the box the grid fits in; cells are the largest squares that fit with `height`.
+     * Ignored when `cellSize` is given.
+     */
+    width?: number;
+    /** Height of the box the grid fits in. */
+    height?: number;
+    /** Side of one cell. Wins over `width`/`height`. Defaults to 0.3 when none is given. */
+    cellSize?: number;
+    /**
+     * Space between cells.
+     * @default 0.05
+     */
+    gap?: number;
+    /** Centre of the grid (not counting the legend). Defaults to the origin. */
+    center?: Point;
+    /** One colour for every category, or `(d, i) => colour`. Wins over `colors`. */
+    color?: ColorChannel<T>;
+    /**
+     * Colours cycled across the categories by index. Defaults to the theme's categorical colours.
+     */
+    colors?: readonly ColorInput[];
+    /**
+     * Draw the empty grid behind the cells.
+     * @default true
+     */
+    track?: boolean;
+    /** Colour of the empty grid. Defaults to the theme's grid colour. */
+    trackColor?: ColorInput;
+    /**
+     * A row of swatches with each category's label and percentage.
+     * @default false
+     */
+    legend?: boolean;
+    /**
+     * Where the legend sits: under the grid or in a column to its right.
+     * @default "bottom"
+     */
+    legendPosition?: "bottom" | "right";
+    /**
+     * Legend font size.
+     * @default 0.22
+     */
+    legendFontSize?: number;
+    /**
+     * Reveal, 0..1: the empty grid fades in, then cells grow one after another in fill order.
+     * @default 1
+     * @see https://sophistry.dev/guides/chart-animation/#reveals
+     */
+    progress?: number;
+    /**
+     * Fraction of the cells' reveal spent staggering cell after cell, 0..0.95.
+     * @default 0.9
+     */
+    stagger?: number;
+    /**
+     * Hover tooltip over the cell under the pointer: `true` for "label: value (pct)", or `(d, i) =>
+     * string` for its category.
+     */
+    tooltip?: TooltipSpec<T>;
+    /** Paint order; higher draws later. */
+    zIndex?: number;
+    visible?: boolean;
+}
+/**
+ * Props of {@link waffle}: `value` is required unless `data` is `number[]`.
+ *
+ * @category Charts
+ */
+export type WaffleProps<T> = WaffleBaseProps<T> & RequiredUnless<T, number, "value">;
+/**
+ * A waffle chart: a grid of unit cells (10 × 10 by default, one cell per percent) coloured by
+ * category in proportion to each value, filling row by row from the bottom-left. Counts are
+ * rounded so they always fill the grid exactly. Draws in scene units; needs no `chart`. The
+ * cells are one instances node. See {@link waffleCells} for the cell assignment alone.
+ *
+ * @example
+ * ```ts
+ * import { waffle } from "@sophistry/charts";
+ *
+ * waffle.create({
+ * 	data: [
+ * 		{ name: "Yes", n: 62 },
+ * 		{ name: "No", n: 38 },
+ * 	],
+ * 	value: "n",
+ * 	label: "name",
+ * 	legend: true,
+ * });
+ * ```
+ *
+ * @see https://sophistry.dev/reference/chart-catalogue/#gauges-bullets-waffles-mosaics-and-radial-bars
+ * @category Charts
+ */
+export declare const waffle: import("@sophistry/core").Definition<WaffleBaseProps<any>, import("@sophistry/core/internal").CompositeNode<WaffleBaseProps<any>>, keyof WaffleBaseProps<any>>;

package/dist/raster.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Gridded colour layers as one image rather than one rectangle per cell.
+ *
+ * A 1000 × 1000 `<Imshow>` is a million cells. As shapes that is a million
+ * nodes; as an image it is one `drawImage` that the camera moves for free. The
+ * colours go through a 256-step lookup table of the layer's ramp (what
+ * matplotlib's colormaps are, too), so a million cells cost a million table
+ * reads instead of a million CSS colour strings.
+ */
+import type { CoordinateSystem, ImageGeometry } from "@sophistry/core";
+import type { Point } from "@sophistry/core/geometry";
+/** `LUT_SIZE` RGBA entries sampling `colorAt` over 0..1. */
+export declare function rampTable(colorAt: (unit: number) => string): Uint8ClampedArray;
+/**
+ * Colours a grid of values into RGBA pixels, row 0 first. Values off the norm
+ * (non-finite, or non-positive under a log norm) are transparent, the way
+ * those cells are not drawn as shapes.
+ */
+export declare function rasterize(values: readonly (readonly number[])[], ncols: number, unitOf: (value: number) => number, table: Uint8ClampedArray): Uint8ClampedArray;
+/**
+ * The scene frame of an axis-aligned data rectangle, if the coordinate system
+ * maps it affinely (linear axes): pixel corner `(0, 0)` at data `(x0, y0)`, the
+ * first row running to `x1`, the first column to `y1`. Null under a log or
+ * other non-linear axis, where an image would put cells in the wrong places —
+ * the caller then draws cells as shapes.
+ */
+export declare function affineFrame(coords: Pick<CoordinateSystem, "coordsToPoint">, x0: number, y0: number, x1: number, y1: number): Omit<ImageGeometry, "pixels"> | null;
+/**
+ * Projects many data points into scene units at once, into `out` (interleaved
+ * `x, y`). Under linear axes the coordinate system is an affine map, found
+ * from three probes and checked at a fourth, and every point is two multiply-
+ * adds; otherwise each point goes through `coordsToPoint`.
+ *
+ * @param xs - Data x per point.
+ * @param ys - Data y per point.
+ * @param out - Receives `2 * xs.length` numbers.
+ */
+export declare function projectPoints(coords: CoordinateSystem, xs: ArrayLike<number>, ys: ArrayLike<number>, out: Float64Array): void;
+/**
+ * Projects one run of data points into scene points: the run-of-objects
+ * counterpart of {@link projectPoints}, with the same affine fast path.
+ */
+export declare function projectRun(coords: Pick<CoordinateSystem, "coordsToPoint">, run: readonly Point[]): Point[];