@fundar/data-chart-telling 1.0.0 → 1.2.0

package/dist/phases/transforms/TransformsPhase.js

@@ -1,8 +1,9 @@
 import { Transforms } from './Transforms';
+import { ValueSelection } from './ValueSelection';
+import { ProcessedPositions } from './ProcessedPositions';
 import { seriesIdOf } from '../../utils/grouping';
-import { PANEL_KEY } from '../facet/FacetPhase';
-import { resolveAccessor } from '../../plots/utils/accessors';
-import { isGapValue } from '../../plots/utils/gaps';
+import { PANEL_KEY } from '../facet/FacetPanels';
+import { resolveAccessor } from '../../utils/accessors';
 import { buildGroupedSeries } from '../../plots/utils/segments';
 import { PlotAxes } from '../data/PlotAxes';
 /** The field each processed row carries its series name under, for its color, legend and labels. */
@@ -20,7 +21,8 @@ const NOT_OPTIONS = new Set(['data', 'z', 'grouping', 'transforms', 'sort', 'fil
  * The "transforms" phase every axis-based plot shares: runs the plot-level
  * transforms once over every visible series' rows together, so a stack sees
  * every series and a bin keeps each series apart (both group by series), and
- * leaves the result in `state.processedData` for the plot's own marks. With
+ * leaves the result in `state.processedData` for the plot's own marks - and
+ * in `state.processedGroups`, split back into the visual groups they draw. With
  * facet panels, the transforms run once per panel's rows, so a stack never
  * combines two panels, and every row they return keeps its panel. A gap that
  * `styles.gaps` fills is read at its interpolated value, so it takes its place
@@ -29,8 +31,11 @@ const NOT_OPTIONS = new Set(['data', 'z', 'grouping', 'transforms', 'sort', 'fil
 export class TransformsPhase {
     phase = 'transforms';
     #options;
-    constructor(options = {}) {
+    #connect;
+    /** `connect`: whether a series' visual segments bridge into each other, as the kind's "data" phase splits them. */
+    constructor(options = {}, connect = true) {
         this.#options = options;
+        this.#connect = connect;
     }
     run = (state, ctx) => {
         const options = this.#options;
@@ -62,7 +67,7 @@ export class TransformsPhase {
         if (!transforms.length) {
             const channels = Object.fromEntries(Object.entries({ x, y }).filter(([, channel]) => channel !== undefined));
             const processedData = { data, channels, options: {}, transforms };
-            return { ...state, processedData };
+            return this.#withGroups({ ...state, processedData });
         }
         const out = TransformsPhase.#runByPanel(data, (rows) => Transforms.resolve({ data: rows, x, y, grouping: SERIES_ID_KEY, transforms }, rows));
         const channels = {};
@@ -89,8 +94,59 @@ export class TransformsPhase {
             options: markOptions,
             transforms
         };
-        return { ...state, processedData };
+        return this.#withGroups({ ...state, processedData });
     };
+    /**
+     * `state` with its processed rows split into the visual groups the kind's marks
+     * draw (`processedGroups`), and the rows its value labels are written for
+     * (`labelled`).
+     */
+    #withGroups(state) {
+        const processedGroups = this.#options.groups === 'runs'
+            ? TransformsPhase.#buildRuns(state)
+            : TransformsPhase.#buildGroups(state, this.#connect);
+        return { ...state, processedGroups, ...this.#labelled(state) };
+    }
+    /**
+     * The rows `styles.values` writes labels for, picked per facet panel - a
+     * panel's own last row, not the last of every panel - by the author's
+     * `select` and `series`, over the plot's own default. Left out while the
+     * labels are off, or when the plot picks no rows.
+     */
+    #labelled(state) {
+        const options = this.#options.labels;
+        const values = state.values;
+        if (!options || !(values?.show ?? options.show))
+            return {};
+        const processed = state.processedData;
+        const valueAxis = PlotAxes.valueOf(state);
+        const select = values?.select ?? options.select;
+        const selections = ValueSelection.transforms(select, values?.series, valueAxis);
+        const position = ProcessedPositions.of(processed, valueAxis);
+        const skip = options.skip?.(state);
+        const channels = {
+            x: position.x,
+            y: position.y,
+            group: options.group === 'category'
+                ? position[PlotAxes.categoryOf(state)]
+                : SERIES_ID_KEY
+        };
+        const panels = new Map();
+        for (const row of processed.data) {
+            if (skip?.(row))
+                continue;
+            const bucket = panels.get(row[PANEL_KEY]);
+            if (bucket)
+                bucket.push(row);
+            else
+                panels.set(row[PANEL_KEY], [row]);
+        }
+        const labelled = new Set([...panels.values()].flatMap((rows) => ValueSelection.pick(rows, selections, channels)));
+        return {
+            labelled: processed.data.filter((row) => labelled.has(row)),
+            labelSelects: ValueSelection.selectors(select)
+        };
+    }
     /** What a gap-filled row carries: its interpolated value and the kind of zone that filled it. */
     static #fillTags(fill) {
         return fill ? { [GAP_VALUE]: fill.value, [GAP_KIND]: fill.kind } : {};
@@ -100,7 +156,7 @@ export class TransformsPhase {
      * into its styled visual segments by `segments`, matched on the processed `x`.
      * Each series reads its rows through its value axis: a stack's top, a bin's start.
      */
-    static buildProcessedGroups(state, connect = true) {
+    static #buildGroups(state, connect) {
         const { data } = state.processedData;
         const series = (state.resolvedSeries ?? []).map((s) => TransformsPhase.#processedSeries(state, s, data.filter((row) => row[SERIES_ID_KEY] === seriesIdOf(s))));
         return buildGroupedSeries(series, state.segments, connect);
@@ -108,11 +164,11 @@ export class TransformsPhase {
     /**
      * The processed rows in their own order, split into runs of consecutive rows
      * from the same visible series, each cut into its styled visual segments like
-     * {@link TransformsPhase.buildProcessedGroups}. Drawn in turn, the runs keep the rows' order
+     * {@link TransformsPhase.#buildGroups}. Drawn in turn, the runs keep the rows' order
      * across series, so a transform that reorders rows (`sort`, `reverse`,
      * `shuffle`) decides which rows paint on top. Unreordered, each series is one run.
      */
-    static buildProcessedRuns(state) {
+    static #buildRuns(state) {
         const byId = new Map((state.resolvedSeries ?? []).map((s) => [seriesIdOf(s), s]));
         const runs = [];
         for (const row of state.processedData.data) {
@@ -127,54 +183,6 @@ export class TransformsPhase {
         }
         return buildGroupedSeries(runs, state.segments, false);
     }
-    /**
-     * Where a processed row sits: the top of its value (`y2`, or `y` - `x2`/`x`
-     * when `valueAxis` is `x`) and, on the other axis, its own position (or the
-     * middle of its `1`-`2` span, a bin's centre).
-     */
-    static processedPosition(processed, valueAxis = 'y') {
-        const { channels } = processed;
-        const read = (channel) => resolveAccessor(channel);
-        const along = (axis) => {
-            const own = channels[axis];
-            const from = channels[`${axis}1`];
-            const to = channels[`${axis}2`];
-            if (axis === valueAxis) {
-                const top = to ?? own;
-                return top !== undefined ? read(top) : () => undefined;
-            }
-            if (own !== undefined)
-                return read(own);
-            if (from === undefined || to === undefined)
-                return () => undefined;
-            return (row) => (Number(read(from)(row)) + Number(read(to)(row))) / 2;
-        };
-        return { x: along('x'), y: along('y') };
-    }
-    /**
-     * A processed row's span along `valueAxis`: from its `1` channel (a stack's
-     * bottom) or, with none, from `baseline`, to its top. `undefined` when the
-     * row has no value there. `stacked` tells a stack from plain values.
-     */
-    static processedSpan(processed, valueAxis, baseline = 0) {
-        const from = processed.channels[`${valueAxis}1`];
-        const stacked = from !== undefined && processed.channels[`${valueAxis}2`] !== undefined;
-        const top = TransformsPhase.processedPosition(processed, valueAxis)[valueAxis];
-        const bottom = stacked
-            ? resolveAccessor(from)
-            : () => baseline;
-        return {
-            stacked,
-            of: (row) => {
-                const end = top(row);
-                const start = bottom(row);
-                if (isGapValue(end) || isGapValue(start))
-                    return undefined;
-                const span = [Number(start), Number(end)];
-                return Number.isFinite(span[0]) && Number.isFinite(span[1]) ? span : undefined;
-            }
-        };
-    }
     /**
      * One series accessor shared by every series as-is, so a field key keeps
      * feeding svelteplot's axis-title inference; a per-series function otherwise.
@@ -234,6 +242,7 @@ export class TransformsPhase {
         return {
             name: source.name,
             ...(source.id !== undefined ? { id: source.id } : {}),
+            ...(source.panel !== undefined ? { panel: source.panel } : {}),
             x: read('x'),
             y: read('y'),
             data

package/dist/phases/transforms/ValueSelection.d.ts

@@ -0,0 +1,30 @@
+import type { ValueSelect } from '../../types/layout/styles';
+import type { MarkerTransform } from '../../types/transforms';
+import type { ProcessedRow } from '../../types/phases';
+/**
+ * Which rows of a plot a value label is written for: `styles.values.select`
+ * (or the plot's own default) and `series`, run as `filter` and `select`
+ * transforms over the processed rows. The labelled rows are the union of what
+ * each selector picks, returned as the rows themselves, in their own order.
+ */
+export declare class ValueSelection {
+    /** `select` as a list: none is every row. */
+    static selectors(select: ValueSelect | ValueSelect[] | undefined): ValueSelect[];
+    /**
+     * The transforms that pick the rows, one list per selector: the series filter,
+     * then the `select` of that selector, with `'min'` and `'max'` read on
+     * `valueAxis`. Without selectors, one list that only filters the series.
+     */
+    static transforms(select: ValueSelect | ValueSelect[] | undefined, series: string | string[] | undefined, valueAxis: 'x' | 'y'): MarkerTransform[][];
+    /**
+     * The rows of `rows` that any of `selections` picks, grouped by `group`
+     * (a field key or accessor) and compared on `x` and `y` - the value axis'
+     * channel is what `'min'` and `'max'` read. A transform returns copies of its
+     * rows, so each is traced back to the row it came from.
+     */
+    static pick(rows: ProcessedRow[], selections: MarkerTransform[][], channels: {
+        x: unknown;
+        y: unknown;
+        group: unknown;
+    }): ProcessedRow[];
+}

package/dist/phases/transforms/ValueSelection.js

@@ -0,0 +1,53 @@
+import { Transforms } from './Transforms';
+import { SERIES_KEY } from './TransformsPhase';
+/** The field a row carries its place in the rows picked from, under which a transform's copy of it is traced back. */
+const PLACE = '__place';
+/**
+ * Which rows of a plot a value label is written for: `styles.values.select`
+ * (or the plot's own default) and `series`, run as `filter` and `select`
+ * transforms over the processed rows. The labelled rows are the union of what
+ * each selector picks, returned as the rows themselves, in their own order.
+ */
+export class ValueSelection {
+    /** `select` as a list: none is every row. */
+    static selectors(select) {
+        return select === undefined ? [] : Array.isArray(select) ? select : [select];
+    }
+    /**
+     * The transforms that pick the rows, one list per selector: the series filter,
+     * then the `select` of that selector, with `'min'` and `'max'` read on
+     * `valueAxis`. Without selectors, one list that only filters the series.
+     */
+    static transforms(select, series, valueAxis) {
+        const names = series === undefined ? undefined : new Set([series].flat());
+        const filter = names
+            ? [{ type: 'filter', filter: (d) => names.has(String(d[SERIES_KEY])) }]
+            : [];
+        const selectors = ValueSelection.selectors(select);
+        if (selectors.length === 0)
+            return [filter];
+        return selectors.map((selector) => [
+            ...filter,
+            {
+                type: 'select',
+                select: selector === 'min' || selector === 'max' ? { [valueAxis]: selector } : selector
+            }
+        ]);
+    }
+    /**
+     * The rows of `rows` that any of `selections` picks, grouped by `group`
+     * (a field key or accessor) and compared on `x` and `y` - the value axis'
+     * channel is what `'min'` and `'max'` read. A transform returns copies of its
+     * rows, so each is traced back to the row it came from.
+     */
+    static pick(rows, selections, channels) {
+        const placed = rows.map((row, index) => ({ ...row, [PLACE]: index }));
+        const chosen = new Set();
+        for (const transforms of selections) {
+            const picked = Transforms.resolve({ data: placed, ...channels, grouping: channels.group, transforms }, placed);
+            for (const row of picked.data ?? placed)
+                chosen.add(row[PLACE]);
+        }
+        return rows.filter((_, index) => chosen.has(index));
+    }
+}

package/dist/plots/{heatmap → correlation/heatmap}/Plot.svelte

@@ -1,7 +1,10 @@
 <script lang="ts" generics="TData extends Record<string, unknown>">
-	import Plot from '../../layout/plot/Plot.svelte';
+	import Plot from '../../../layout/plot/Plot.svelte';
 	import { buildHeatmapDefaults } from './defaults';
-	import type { HeatmapPlotProps, HeatmapPlotCoreProps } from '../../types/plots/heatmap/props';
+	import type {
+		HeatmapPlotProps,
+		HeatmapPlotCoreProps
+	} from '../../../types/plots/correlation/heatmap/props';
 
 	/**
 	 * A categorical grid of value-colored cells. Draws from pre-built `series` or flat `data` rows.

package/dist/plots/{heatmap → correlation/heatmap}/Plot.svelte.d.ts

@@ -1,5 +1,5 @@
-import Plot from '../../layout/plot/Plot.svelte';
-import type { HeatmapPlotProps } from '../../types/plots/heatmap/props';
+import Plot from '../../../layout/plot/Plot.svelte';
+import type { HeatmapPlotProps } from '../../../types/plots/correlation/heatmap/props';
 declare function $$render<TData extends Record<string, unknown>>(): {
     props: HeatmapPlotProps<TData>;
     exports: {};

package/dist/plots/{heatmap → correlation/heatmap}/defaults.d.ts

@@ -1,5 +1,5 @@
-import type { AxisPlotDefaults } from '../../types/phases';
-import type { HeatmapPlotState, HeatmapPlotCtx } from '../../types/plots/heatmap/state';
+import type { AxisPlotDefaults } from '../../../types/phases';
+import type { HeatmapPlotState, HeatmapPlotCtx } from '../../../types/plots/correlation/heatmap/state';
 /**
  * HeatmapPlot on the shared pipeline: both axes are categories. A heatmap's
  * `color` is each cell's numeric value, which the "data" phase reads as a

package/dist/plots/{heatmap → correlation/heatmap}/defaults.js

@@ -1,6 +1,6 @@
-import { resolveColorScale } from '../../utils/color';
-import { resolveOpacityScale } from '../../utils/opacity';
-import { ContinuousDomain } from '../../utils/ContinuousDomain';
+import { ColorRamp } from '../../../utils/color';
+import { OpacityScale } from '../../../utils/OpacityScale';
+import { ContinuousDomain } from '../../../utils/ContinuousDomain';
 import { buildMarks, buildValueLabels } from './markers';
 /**
  * HeatmapPlot's own "scales" output, over the band axes the shared phase laid
@@ -17,7 +17,7 @@ function extendWithColorScales(state, ctx) {
     // active range) keeps the original domain - only which cells are hidden
     // changes (resolved in the "markers" phase).
     const effectiveDomain = ContinuousDomain.ramp(valueDomain, range);
-    const colorScale = resolveColorScale({ ...scales.color, domain: effectiveDomain }, effectiveDomain, [cfg.continuous.min, cfg.continuous.max]);
+    const colorScale = ColorRamp.continuous(cfg, scales.color, effectiveDomain);
     const resolveColor = (row) => colorScale(Number(colorAcc.accessor(row)));
     const opacityAcc = channels.opacity;
     let opacityDomainOut;
@@ -32,7 +32,7 @@ function extendWithColorScales(state, ctx) {
                 : [...new Set(rawVals.map(String))];
             if (allNumeric && rawVals.length)
                 opacityDomainOut = opacityDomain;
-            const opacityScale = resolveOpacityScale(scales.opacity, opacityDomain, cfg.continuous.opacityRange);
+            const opacityScale = OpacityScale.resolve(scales.opacity, opacityDomain, cfg.continuous.opacityRange);
             return (row) => opacityScale(opacityAcc.accessor(row));
         })()
         : undefined;

package/dist/plots/{heatmap → correlation/heatmap}/markers.d.ts

@@ -1,7 +1,7 @@
-import type { TextMarkerConfig } from '../../types/markers/common';
-import type { HeatmapPlotState, HeatmapPlotCtx } from '../../types/plots/heatmap/state';
-import type { ValueLabels } from '../../layout/styles/ValueLabels';
-import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+import type { TextMarkerConfig } from '../../../types/markers/common';
+import type { HeatmapPlotState, HeatmapPlotCtx } from '../../../types/plots/correlation/heatmap/state';
+import type { ValueLabels } from '../../../layout/styles/ValueLabels';
+import type { AxisBasedMarkersConfig } from '../../../types/markers/common';
 /**
  * HeatmapPlot's `styles.values` as one `'text'` marker over the same cells
  * the plot draws, each labelled with its own value and centred on it. Shown

package/dist/plots/{heatmap → correlation/heatmap}/markers.js

@@ -1,5 +1,6 @@
-import { DisabledStyle } from '../../layout/legend/DisabledStyle';
-import { resolveAccessor } from '../utils/accessors';
+import { LegendState } from '../../../layout/legend/LegendState.svelte';
+import { DisabledStyle } from '../../../layout/legend/DisabledStyle';
+import { resolveAccessor } from '../../../utils/accessors';
 /** A processed channel as a per-row function. */
 function readChannel(channel) {
     return resolveAccessor(channel);
@@ -98,7 +99,7 @@ export function buildMarks(state, ctx) {
         return map;
     })();
     function rangeFilteredStyle(base, value) {
-        if (range == null || (value >= range.min && value <= range.max))
+        if (range == null || LegendState.inRange(value, range))
             return base;
         return { ...base, ...DisabledStyle.fill(range.disabledStyle) };
     }

package/dist/plots/{scatter → correlation/scatter}/Plot.svelte

@@ -1,7 +1,10 @@
 <script lang="ts" generics="TData extends Record<string, unknown>">
-	import Plot from '../../layout/plot/Plot.svelte';
+	import Plot from '../../../layout/plot/Plot.svelte';
 	import { buildScatterDefaults } from './defaults';
-	import type { ScatterPlotProps, ScatterPlotCoreProps } from '../../types/plots/scatter/props';
+	import type {
+		ScatterPlotProps,
+		ScatterPlotCoreProps
+	} from '../../../types/plots/correlation/scatter/props';
 
 	/**
 	 * A point cloud on continuous x/y axes; `r` sizes each dot. Draws from pre-built `series` or flat `data` rows.

package/dist/plots/{scatter → correlation/scatter}/Plot.svelte.d.ts

@@ -1,5 +1,5 @@
-import Plot from '../../layout/plot/Plot.svelte';
-import type { ScatterPlotProps } from '../../types/plots/scatter/props';
+import Plot from '../../../layout/plot/Plot.svelte';
+import type { ScatterPlotProps } from '../../../types/plots/correlation/scatter/props';
 declare function $$render<TData extends Record<string, unknown>>(): {
     props: ScatterPlotProps<TData>;
     exports: {};

package/dist/plots/{scatter → correlation/scatter}/defaults.d.ts

@@ -1,4 +1,4 @@
-import type { AxisPlotDefaults } from '../../types/phases';
-import type { ScatterPlotState, ScatterPlotCtx } from '../../types/plots/scatter/state';
+import type { AxisPlotDefaults } from '../../../types/phases';
+import type { ScatterPlotState, ScatterPlotCtx } from '../../../types/plots/correlation/scatter/state';
 /** ScatterPlot on the shared pipeline: discrete dots, its own radius-padded scales, and its own markers. Its plot defaults to: hover the exact point. */
 export declare function buildScatterDefaults<TData extends Record<string, unknown>>(): AxisPlotDefaults<ScatterPlotState<TData>, ScatterPlotCtx>;

package/dist/plots/{scatter → correlation/scatter}/defaults.js

@@ -1,7 +1,7 @@
+import { ProcessedPositions } from '../../../phases/transforms/ProcessedPositions';
 import { buildMarks, buildValueLabels } from './markers';
-import { TransformsPhase } from '../../phases/transforms/TransformsPhase';
-import { Margins } from '../../layout/margins/Margins';
-import { MarkerAxisValues } from '../../phases/scales/MarkerAxisValues';
+import { Margins } from '../../../layout/margins/Margins';
+import { MarkerAxisValues } from '../../../phases/scales/MarkerAxisValues';
 /** Stand-in max render radius for a channel-bound `r` (svelteplot's own auto sqrt scale). */
 const AUTO_SCALED_RADIUS_ESTIMATE = 20;
 /**
@@ -28,7 +28,7 @@ function paddedDomain(values, radiusPx, sizePx) {
 function fitDomains(state, ctx) {
     const { scales, channels, groupedSeries } = state;
     const processed = state.processedData;
-    const position = TransformsPhase.processedPosition(processed);
+    const position = ProcessedPositions.of(processed);
     const extra = {
         x: MarkerAxisValues.of(state.markers ?? [], 'x'),
         y: MarkerAxisValues.of(state.markers ?? [], 'y')
@@ -53,7 +53,7 @@ function fitDomains(state, ctx) {
         const values = [...processed.data.map((d) => Number(position[axis](d))), ...extra[axis]];
         const domain = paddedDomain(values, radius, size);
         if (domain)
-            fit[axis] = { domain };
+            fit[axis] = { domain, fitted: true };
     }
     return fit;
 }
@@ -66,6 +66,7 @@ export function buildScatterDefaults() {
                 connect: false
             }
         },
+        transforms: { groups: 'runs' },
         scales: { fit: fitDomains },
         markers: { marks: buildMarks, valueLabels: buildValueLabels },
         hover: {

package/dist/plots/{scatter → correlation/scatter}/markers.d.ts

@@ -1,7 +1,7 @@
-import type { ScatterPlotState, ScatterPlotCtx } from '../../types/plots/scatter/state';
-import type { TextMarkerConfig } from '../../types/markers/common';
-import { ValueLabels } from '../../layout/styles/ValueLabels';
-import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+import type { ScatterPlotState, ScatterPlotCtx } from '../../../types/plots/correlation/scatter/state';
+import type { TextMarkerConfig } from '../../../types/markers/common';
+import { ValueLabels } from '../../../layout/styles/ValueLabels';
+import type { AxisBasedMarkersConfig } from '../../../types/markers/common';
 /**
  * ScatterPlot's `styles.values` as one `'text'` marker over the same
  * processed rows its dots draw, each labelled with its own `y` value. A label

package/dist/plots/{scatter → correlation/scatter}/markers.js

@@ -1,5 +1,6 @@
-import { SERIES_KEY, TransformsPhase } from '../../phases/transforms/TransformsPhase';
-import { ValueLabels } from '../../layout/styles/ValueLabels';
+import { ProcessedPositions } from '../../../phases/transforms/ProcessedPositions';
+import { SERIES_KEY } from '../../../phases/transforms/TransformsPhase';
+import { ValueLabels } from '../../../layout/styles/ValueLabels';
 /**
  * ScatterPlot's `styles.values` as one `'text'` marker over the same
  * processed rows its dots draw, each labelled with its own `y` value. A label
@@ -11,7 +12,7 @@ export function buildValueLabels(labels, state, ctx) {
     if (!processedData?.data.length)
         return [];
     const { font, format } = labels;
-    const position = TransformsPhase.processedPosition(processedData);
+    const position = ProcessedPositions.of(processedData);
     const nameOf = (d) => String(d[SERIES_KEY]);
     const valueOf = ValueLabels.valueOf(state);
     return [
@@ -89,7 +90,7 @@ export function buildMarks(state, ctx) {
         }
         : undefined;
     const markers = [];
-    TransformsPhase.buildProcessedRuns(state).forEach((group) => {
+    (state.processedGroups ?? []).forEach((group) => {
         const defaultColor = colorForSeries(group.series.name);
         const disabledDots = interaction?.dotsFor(group.series.name);
         for (const seg of group.visualSegments) {

package/dist/plots/distribution/box/BoxSummaries.d.ts

@@ -0,0 +1,19 @@
+import type { HoverPosition } from '../../../types/phases';
+import type { BoxPlotState, BoxSummaryRow } from '../../../types/plots/distribution/box/state';
+/**
+ * The boxes a box plot draws, one summary row per series, category and facet
+ * panel - the same quartiles and whiskers svelteplot's `BoxX`/`BoxY` compute,
+ * so its hover and tooltip read a box rather than every value inside it.
+ */
+export declare class BoxSummaries {
+    /** One summary per box, in the order the processed rows first reach it. */
+    static of<TData extends Record<string, unknown>>(state: BoxPlotState<TData>): BoxSummaryRow[];
+    /** Where a box's summary sits for hover: at its category, level with its median. */
+    static position<TData extends Record<string, unknown>>(state: BoxPlotState<TData>): HoverPosition;
+    /**
+     * How a hovered box reads by default: its series, when the plot groups its
+     * rows; its category; then its five numbers, highest first, and how many
+     * values fall past the whiskers.
+     */
+    static format<TData extends Record<string, unknown>>(state: BoxPlotState<TData>): (row: BoxSummaryRow) => string;
+}

package/dist/plots/distribution/box/BoxSummaries.js

@@ -0,0 +1,101 @@
+import { ProcessedPositions } from '../../../phases/transforms/ProcessedPositions';
+import { quantile } from 'd3-array';
+import { SERIES_ID_KEY, SERIES_KEY } from '../../../phases/transforms/TransformsPhase';
+import { PANEL_KEY } from '../../../phases/facet/FacetPanels';
+import { PlotAxes } from '../../../phases/data/PlotAxes';
+import { TooltipState } from '../../../layout/tooltip/TooltipState.svelte';
+import { isGapValue } from '../../utils/gaps';
+/** The whiskers reach this many interquartile ranges past the box, as svelteplot draws them. */
+const WHISKER_IQR = 1.5;
+/** A summary value as a tooltip shows it: at most two decimals. */
+const round = (value) => String(Math.round(value * 100) / 100);
+/**
+ * The boxes a box plot draws, one summary row per series, category and facet
+ * panel - the same quartiles and whiskers svelteplot's `BoxX`/`BoxY` compute,
+ * so its hover and tooltip read a box rather than every value inside it.
+ */
+export class BoxSummaries {
+    /** One summary per box, in the order the processed rows first reach it. */
+    static of(state) {
+        const processed = state.processedData;
+        if (!processed?.data.length)
+            return [];
+        const valueAxis = PlotAxes.valueOf(state);
+        const categoryAxis = PlotAxes.categoryOf(state);
+        const position = ProcessedPositions.of(processed, valueAxis);
+        const valueOf = position[valueAxis];
+        const categoryOf = position[categoryAxis];
+        const categoryField = processed.channels[categoryAxis];
+        const boxes = new Map();
+        for (const row of processed.data) {
+            const value = valueOf(row);
+            if (isGapValue(value))
+                continue;
+            const n = Number(value);
+            if (!Number.isFinite(n))
+                continue;
+            const key = JSON.stringify([
+                row[SERIES_ID_KEY],
+                row[PANEL_KEY] ?? null,
+                String(categoryOf(row))
+            ]);
+            const box = boxes.get(key);
+            if (box)
+                box.values.push(n);
+            else
+                boxes.set(key, { first: row, values: [n] });
+        }
+        return [...boxes.values()].map(({ first, values }) => {
+            const sorted = values.sort((a, b) => a - b);
+            const p25 = quantile(sorted, 0.25);
+            const median = quantile(sorted, 0.5);
+            const p75 = quantile(sorted, 0.75);
+            const reach = (p75 - p25) * WHISKER_IQR;
+            const inside = sorted.filter((v) => v >= p25 - reach && v <= p75 + reach);
+            const category = categoryOf(first);
+            return {
+                ...(typeof categoryField === 'string' ? { [categoryField]: category } : {}),
+                [SERIES_KEY]: first[SERIES_KEY],
+                [SERIES_ID_KEY]: first[SERIES_ID_KEY],
+                ...(first[PANEL_KEY] !== undefined ? { [PANEL_KEY]: first[PANEL_KEY] } : {}),
+                category,
+                min: inside[0] ?? p25,
+                p25,
+                median,
+                p75,
+                max: inside.at(-1) ?? p75,
+                count: sorted.length,
+                outliers: sorted.filter((v) => v < p25 - reach || v > p75 + reach)
+            };
+        });
+    }
+    /** Where a box's summary sits for hover: at its category, level with its median. */
+    static position(state) {
+        const valueAxis = PlotAxes.valueOf(state);
+        const at = {
+            [valueAxis]: (row) => row.median,
+            [PlotAxes.other(valueAxis)]: (row) => row.category
+        };
+        return at;
+    }
+    /**
+     * How a hovered box reads by default: its series, when the plot groups its
+     * rows; its category; then its five numbers, highest first, and how many
+     * values fall past the whiskers.
+     */
+    static format(state) {
+        const grouped = state.channels?.grouping !== undefined;
+        return (row) => {
+            const lines = grouped ? [String(row[SERIES_KEY])] : [];
+            lines.push(TooltipState.value(row.category));
+            lines.push(`max: ${round(row.max)}`);
+            lines.push(`p75: ${round(row.p75)}`);
+            lines.push(`median: ${round(row.median)}`);
+            lines.push(`p25: ${round(row.p25)}`);
+            lines.push(`min: ${round(row.min)}`);
+            if (row.outliers.length)
+                lines.push(`outliers: ${row.outliers.length}`);
+            return lines.join('\n');
+        };
+    }
+}

package/dist/plots/distribution/box/Plot.svelte

@@ -0,0 +1,42 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+	import Plot from '../../../layout/plot/Plot.svelte';
+	import { buildBoxDefaults } from './defaults';
+	import type { BoxPlotProps, BoxPlotCoreProps } from '../../../types/plots/distribution/box/props';
+
+	/**
+	 * A box plot: the distribution of each series' values per category - quartiles, whiskers and outliers - one box per category, upright, or sideways when the categories run along `y`. Draws from pre-built `series` or flat `data` rows.
+	 * Optional chrome (`title`, `subtitle`, `caption`, `header`, `footer`,
+	 * `legend`) frames it; `timeline` and `facet` slice its `data` rows.
+	 * `margins` is bindable: it reports the margin the plot settled on.
+	 */
+	let {
+		title,
+		subtitle,
+		caption,
+		header,
+		footer,
+		legend,
+		order,
+		timeline,
+		facet,
+		tooltip,
+		margins = $bindable(),
+		...core
+	}: BoxPlotProps<TData> = $props();
+</script>
+
+<Plot
+	core={core as BoxPlotCoreProps<TData>}
+	defaults={buildBoxDefaults}
+	bind:margins
+	{title}
+	{subtitle}
+	{caption}
+	{header}
+	{footer}
+	{legend}
+	{order}
+	{timeline}
+	{facet}
+	{tooltip}
+/>