@fundar/data-chart-telling 1.0.0 → 1.2.0

package/dist/plots/ranking/cleveland/ClevelandConnector.js

@@ -0,0 +1,140 @@
+import { ColorRamp } from '../../../utils/color';
+/**
+ * The connectors of a Cleveland-style plot as `styles.connector` styles them:
+ * what each one measures, its color, its thickness and its label. The plot's
+ * marks read each category's connector through it.
+ */
+export class ClevelandConnector {
+    style;
+    #defaults;
+    #colorOf;
+    constructor(style, defaults, entries) {
+        this.style = style ?? {};
+        this.#defaults = defaults;
+        this.#colorOf = ClevelandConnector.#colors(this.style.color, defaults, entries);
+    }
+    /** The series a plot's differences run between, from `styles.connector`. */
+    static ends(state) {
+        const { from, to } = state.styles?.connector ?? {};
+        return { from, to };
+    }
+    /** `styles.connector` of a plot's state, over the configuration's defaults and what `entries` measure. */
+    static of(state, defaults, entries) {
+        const style = state.styles?.connector;
+        return new ClevelandConnector(style, defaults, entries);
+    }
+    /** What `entry`'s connector measures, which every other setting reads. */
+    rangeOf(entry) {
+        return {
+            category: entry.category,
+            from: entry.from,
+            to: entry.to,
+            length: entry.to - entry.from,
+            difference: entry.difference,
+            span: entry.span,
+            series: entry.dots.length === 1 ? entry.dots[0].series : undefined
+        };
+    }
+    /** The color the author asks for `range`'s connector, if they do. */
+    color(range) {
+        return this.#colorOf?.(range);
+    }
+    /** The thickness the author asks for `range`'s connector, if they do, given the dots' radius. */
+    width(range, dotRadius) {
+        const { width } = this.style;
+        if (width === undefined)
+            return undefined;
+        if (width === 'dots')
+            return dotRadius * 2;
+        return typeof width === 'function' ? width(range) : width;
+    }
+    /** The opacity the author asks for `range`'s connector, if they do. */
+    opacity(range) {
+        const { opacity } = this.style;
+        return typeof opacity === 'function' ? opacity(range) : opacity;
+    }
+    /** How the part of a connector outside the `from`-`to` stretch looks, over the plot's neutral `fallback` color. */
+    outside(fallback) {
+        const { outside } = this.style;
+        const own = typeof outside === 'string' ? { color: outside } : (outside ?? {});
+        return {
+            stroke: own.color ?? fallback,
+            strokeOpacity: own.opacity ?? this.#defaults.outsideOpacity
+        };
+    }
+    /** The head of the arrow a connector is drawn as, `undefined` when it is a line. */
+    get arrow() {
+        const { arrow } = this.style;
+        if (!arrow)
+            return undefined;
+        const own = arrow === true ? {} : arrow;
+        return { ...this.#defaults.arrow, ...own };
+    }
+    /** The length (px) of the caps a connector draws at its ends, `undefined` when it draws none, given whether the plot draws them unless told otherwise. */
+    caps(byDefault) {
+        const { caps } = this.style;
+        const on = caps === undefined ? (byDefault ?? false) : caps !== false;
+        if (!on)
+            return undefined;
+        return (typeof caps === 'object' ? caps.length : undefined) ?? this.#defaults.capLength;
+    }
+    /** The label options: `undefined` without a label. */
+    get label() {
+        const { label } = this.style;
+        return label === undefined || label === false ? undefined : label === true ? {} : label;
+    }
+    /** What the label of `range`'s connector says, `undefined` when it has nothing to say (no difference). */
+    text(range) {
+        const label = this.label ?? {};
+        const what = label.text ?? 'difference';
+        if (typeof what === 'function')
+            return what(range);
+        const value = what === 'length' ? range.length : range.difference;
+        if (value === undefined || !Number.isFinite(value))
+            return undefined;
+        if (label.format)
+            return label.format(value, range);
+        const rounded = Math.round(value * 100) / 100;
+        return what === 'difference' && rounded > 0 ? `+${rounded}` : String(rounded);
+    }
+    /** The color function for `by`, over what `entries` measure, or `undefined` when no color is asked for. */
+    static #colors(color, defaults, entries) {
+        if (color === undefined)
+            return undefined;
+        if (typeof color === 'string')
+            return () => color;
+        if (typeof color === 'function')
+            return color;
+        if (color.by === 'sign') {
+            const { positive, negative, zero } = { ...defaults.sign, ...color };
+            return ({ difference }) => difference === undefined
+                ? zero
+                : difference > 0
+                    ? positive
+                    : difference < 0
+                        ? negative
+                        : zero;
+        }
+        const { by, ...config } = color;
+        const read = (range) => (by === 'length' ? range.length : range.difference);
+        const values = entries
+            .map((entry) => (by === 'length' ? entry.to - entry.from : entry.difference))
+            .filter((value) => value !== undefined && Number.isFinite(value));
+        if (values.length === 0)
+            return undefined;
+        const lo = Math.min(...values);
+        const hi = Math.max(...values);
+        const diverging = by === 'difference' && config.scheme === undefined;
+        const scale = ColorRamp.resolve({
+            ...(diverging ? { scheme: defaults.differenceScheme, pivot: 0 } : {}),
+            ...(by === 'length' && config.scheme === undefined
+                ? { scheme: defaults.lengthScheme }
+                : {}),
+            ...config
+        }, by === 'difference' ? [Math.min(lo, 0), Math.max(hi, 0)] : [lo, hi], by === 'length' ? defaults.lengthScheme : defaults.differenceScheme);
+        return (range) => {
+            const value = read(range);
+            return value === undefined ? undefined : scale(value);
+        };
+    }
+}

package/dist/plots/ranking/cleveland/ClevelandMarkers.d.ts

@@ -0,0 +1,33 @@
+import { ValueLabels } from '../../../layout/styles/ValueLabels';
+import type { ClevelandPlotState, ClevelandPlotCtx, ClevelandOptions } from '../../../types/plots/ranking/cleveland/state';
+import type { AxisBasedMarkersConfig, TextMarkerConfig } from '../../../types/markers/common';
+import type { EdgeBox } from '../../../types/layout/box';
+/**
+ * The marks of the Cleveland family of plots, which differ only by their
+ * {@link ClevelandOptions}: per category, a connector from its lowest to its
+ * highest value (from the baseline, for a lollipop) with a dot at each value.
+ * A category with one dot gets a stem in that dot's series color, restyled by
+ * the segment its dot belongs to; a category with several gets one neutral
+ * connector. The "markers" phase takes its `marks`, `valueLabels` and `reach`.
+ */
+export declare class ClevelandMarkers {
+    #private;
+    constructor(options: ClevelandOptions);
+    /** Forgets what was warned about; for tests. */
+    static resetWarnings(): void;
+    /** The plot's connectors, then its dots, which draw on top of them. */
+    marks: <TData extends Record<string, unknown>>(state: ClevelandPlotState<TData>, ctx: ClevelandPlotCtx) => AxisBasedMarkersConfig[];
+    /**
+     * The value labels of the dots `styles.values.of` picks, one `'text'` marker
+     * per place a dot can hold in its range - past the top end (above, or right
+     * of it), past the bottom end (below, or left of it) and, for the dots
+     * between, beside it - and per series, when they take their series' color.
+     */
+    valueLabels: <TData extends Record<string, unknown>>(labels: ValueLabels, state: ClevelandPlotState<TData>, ctx: ClevelandPlotCtx) => TextMarkerConfig[];
+    /**
+     * Room for the labels past the dots at the end of the value axis, so the
+     * farthest one fits inside the figure instead of crossing its edge. Only the
+     * dots at the top end of their range reach there, and only the picked ones.
+     */
+    reach: <TData extends Record<string, unknown>>(labels: ValueLabels, state: ClevelandPlotState<TData>) => EdgeBox[];
+}

package/dist/plots/ranking/cleveland/ClevelandMarkers.js

@@ -0,0 +1,375 @@
+import { PlotAxes } from '../../../phases/data/PlotAxes';
+import { ProcessedPositions } from '../../../phases/transforms/ProcessedPositions';
+import { SERIES_KEY } from '../../../phases/transforms/TransformsPhase';
+import { ValueLabels } from '../../../layout/styles/ValueLabels';
+import { ClevelandRanges } from './ClevelandRanges';
+import { ClevelandConnector } from './ClevelandConnector';
+/** The messages already warned about, so a plot that redraws warns once. */
+const warned = new Set();
+/**
+ * The marks of the Cleveland family of plots, which differ only by their
+ * {@link ClevelandOptions}: per category, a connector from its lowest to its
+ * highest value (from the baseline, for a lollipop) with a dot at each value.
+ * A category with one dot gets a stem in that dot's series color, restyled by
+ * the segment its dot belongs to; a category with several gets one neutral
+ * connector. The "markers" phase takes its `marks`, `valueLabels` and `reach`.
+ */
+export class ClevelandMarkers {
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Forgets what was warned about; for tests. */
+    static resetWarnings() {
+        warned.clear();
+    }
+    /** The plot's connectors, then its dots, which draw on top of them. */
+    marks = (state, ctx) => {
+        const { cfg, interaction } = ctx;
+        const style = cfg[this.#options.config];
+        const { isHorizontal } = ClevelandMarkers.#geometry(state);
+        const ranges = ClevelandRanges.of(state, this.#options.fromBaseline ?? false, ClevelandConnector.ends(state), this.#options.interval ?? false);
+        this.#validate(ranges);
+        const connector = ClevelandConnector.of(state, cfg.connector, ranges.entries);
+        const groups = state.processedGroups ?? [];
+        const segmentOf = new Map();
+        for (const group of groups) {
+            for (const segment of group.visualSegments) {
+                for (const row of segment.data) {
+                    segmentOf.set(row, { series: group.series.name, styles: segment.styles });
+                }
+            }
+        }
+        // Each category's connector: a row of its own look. A lone dot's stem takes its series'
+        // color and its segment's style; the legend dims it with the series.
+        const size = state.channels?.r;
+        const dotRadius = typeof size === 'number' ? size : style.dotRadius;
+        const neutral = style.connectorColor ?? cfg.axis.color;
+        const looks = ranges.entries.map((entry) => {
+            const range = connector.rangeOf(entry);
+            const owner = range.series === undefined ? undefined : segmentOf.get(entry.dots[0].row);
+            const stem = owner?.styles.stroke;
+            const disabled = owner && interaction?.strokeFor(owner.series);
+            const strokeWidth = disabled?.strokeWidth ??
+                stem?.strokeWidth ??
+                connector.width(range, dotRadius) ??
+                (style.stemWidth === 'dots' ? dotRadius * 2 : style.stemWidth);
+            // The stretch between the `from` and `to` dots, in the connector's look...
+            const [start, end] = range.span ?? [entry.from, entry.to];
+            const category = entry.category;
+            const span = {
+                category,
+                from: start,
+                to: end,
+                mid: (start + end) / 2,
+                stroke: disabled?.stroke ??
+                    stem?.stroke ??
+                    connector.color(range) ??
+                    (owner ? state.colorForSeries(owner.series) : neutral),
+                strokeWidth,
+                strokeOpacity: disabled?.strokeOpacity ?? stem?.strokeOpacity ?? connector.opacity(range) ?? 1
+            };
+            // ...as an arrow from one dot to the other, when the connector asks for one...
+            const arrow = connector.arrow;
+            const way = arrow && entry.change && entry.change[0] !== entry.change[1] ? entry.change : undefined;
+            const drawn = way
+                ? {
+                    category,
+                    start: way[0],
+                    end: way[1],
+                    stroke: span.stroke,
+                    strokeWidth: connector.width(range, dotRadius) ?? arrow.width,
+                    strokeOpacity: span.strokeOpacity
+                }
+                : undefined;
+            // ...and what runs on past either end of it, to the other series' dots.
+            const outside = connector.outside(neutral);
+            const beyond = [
+                [entry.from, start],
+                [end, entry.to]
+            ]
+                .filter(([from, to]) => to > from)
+                .map(([from, to]) => ({
+                category,
+                from,
+                to,
+                mid: (from + to) / 2,
+                ...outside,
+                strokeWidth
+            }));
+            return {
+                range,
+                row: span,
+                // A stretch drawn as an arrow is not one of the lines.
+                rows: drawn ? beyond : [span, ...beyond],
+                arrow: drawn,
+                dash: disabled?.strokeDasharray ?? stem?.strokeDasharray
+            };
+        });
+        // One rule marker per dash pattern, which a marker takes once for all its rows.
+        const byDash = new Map();
+        for (const look of looks)
+            byDash.set(look.dash, [...(byDash.get(look.dash) ?? []), look]);
+        const rules = [...byDash].map(([dash, group]) => ({
+            type: 'rule',
+            // A connector is not what the series look like: its dots are.
+            legend: false,
+            axis: isHorizontal ? 'y' : 'x',
+            data: group.flatMap((look) => look.rows),
+            value: 'category',
+            ...(isHorizontal ? { x1: 'from', x2: 'to' } : { y1: 'from', y2: 'to' }),
+            stroke: 'stroke',
+            strokeWidth: 'strokeWidth',
+            strokeOpacity: 'strokeOpacity',
+            ...(dash ? { styles: { strokeDasharray: dash } } : {})
+        }));
+        // The arrows, one marker per dash pattern like the lines, each from its `from` dot to its `to` dot.
+        const head = connector.arrow;
+        const arrows = [...byDash].flatMap(([dash, group]) => {
+            const rows = group.flatMap((look) => (look.arrow ? [look.arrow] : []));
+            if (rows.length === 0 || !head)
+                return [];
+            return [
+                {
+                    type: 'arrow',
+                    legend: false,
+                    data: rows,
+                    ...(isHorizontal
+                        ? { x1: 'start', x2: 'end', y1: 'category', y2: 'category' }
+                        : { y1: 'start', y2: 'end', x1: 'category', x2: 'category' }),
+                    headLength: head.headLength,
+                    headAngle: head.headAngle,
+                    // The shaft starts and ends at the edge of its dots, not under them.
+                    insetStart: dotRadius,
+                    insetEnd: dotRadius,
+                    stroke: 'stroke',
+                    strokeWidth: 'strokeWidth',
+                    strokeOpacity: 'strokeOpacity',
+                    ...(dash ? { styles: { strokeDasharray: dash } } : {})
+                }
+            ];
+        });
+        // Caps: a tick across each end of a connector, in its look - one marker per look, which a marker takes once for all its ticks.
+        const capLength = connector.caps(style.caps);
+        const caps = capLength === undefined ? [] : this.#caps(ranges.entries, looks, capLength, isHorizontal);
+        const { category, value } = ClevelandMarkers.#channels(state);
+        // A number is a literal pixel radius; a field or function sizes each dot by its row.
+        const r = size === undefined || typeof size === 'number' ? size : size.accessor;
+        const dots = groups.flatMap((group) => {
+            const name = group.series.name;
+            const color = state.colorForSeries(name);
+            const disabled = interaction?.dotsFor(name);
+            return group.visualSegments.map((segment) => {
+                const stem = segment.styles.stroke;
+                const dot = segment.styles.dots;
+                return {
+                    type: 'dot',
+                    series: name,
+                    data: segment.data,
+                    ...(isHorizontal ? { x: value, y: category } : { x: category, y: value }),
+                    r,
+                    styles: {
+                        dotRadius: disabled?.dotRadius ?? dot?.dotRadius ?? style.dotRadius,
+                        dotFill: disabled?.dotFill ?? dot?.dotFill ?? stem?.stroke ?? color,
+                        dotFillOpacity: disabled?.dotFillOpacity ?? dot?.dotFillOpacity,
+                        dotSymbol: disabled?.dotSymbol ?? dot?.dotSymbol,
+                        dotStroke: disabled?.dotStroke ?? dot?.dotStroke ?? 'none',
+                        dotStrokeWidth: disabled?.dotStrokeWidth ?? dot?.dotStrokeWidth,
+                        dotStrokeOpacity: disabled?.dotStrokeOpacity ?? dot?.dotStrokeOpacity
+                    }
+                };
+            });
+        });
+        return [
+            ...rules,
+            ...caps,
+            ...arrows,
+            ...dots,
+            ...this.#connectorLabels(state, ctx, connector, looks, isHorizontal)
+        ];
+    };
+    /** The caps of the connectors: a tick at each end of those that have a length, one marker per stroke look. */
+    #caps(entries, looks, length, isHorizontal) {
+        const byLook = new Map();
+        entries.forEach((entry, index) => {
+            if (!(entry.to > entry.from))
+                return;
+            const look = looks[index].row;
+            const key = [look.stroke, look.strokeWidth, look.strokeOpacity].join('|');
+            const group = byLook.get(key) ?? { look, rows: [] };
+            group.rows.push({ category: entry.category, end: entry.from }, { category: entry.category, end: entry.to });
+            byLook.set(key, group);
+        });
+        return [...byLook.values()].map(({ look, rows }) => ({
+            type: 'tick',
+            legend: false,
+            data: rows,
+            ...(isHorizontal ? { x: 'end', y: 'category' } : { x: 'category', y: 'end' }),
+            tickLength: length,
+            styles: {
+                stroke: look.stroke,
+                strokeWidth: look.strokeWidth,
+                strokeOpacity: look.strokeOpacity
+            }
+        }));
+    }
+    /** The label on each connector, when `styles.connector.label` asks for one: written at its middle, beside it or on it. */
+    #connectorLabels(state, ctx, connector, looks, isHorizontal) {
+        const label = connector.label;
+        if (!label)
+            return [];
+        const data = looks.flatMap(({ range, row }) => {
+            const text = connector.text(range);
+            return text === undefined ? [] : [{ ...row, text }];
+        });
+        if (data.length === 0)
+            return [];
+        const font = label.fontStyle;
+        // Beside a connector: clear of half its thickest, and a few px.
+        const clear = Math.max(...data.map((row) => Number(row.strokeWidth))) / 2 + ctx.cfg.connector.labelGap;
+        const inside = label.anchor === 'middle';
+        const at = inside
+            ? { dx: 0, dy: 0, textAnchor: 'middle', lineAnchor: 'middle' }
+            : isHorizontal
+                ? { dx: 0, dy: -clear, textAnchor: 'middle', lineAnchor: 'bottom' }
+                : { dx: clear, dy: 0, textAnchor: 'start', lineAnchor: 'middle' };
+        return [
+            {
+                type: 'text',
+                data,
+                ...(isHorizontal ? { x: 'mid', y: 'category' } : { x: 'category', y: 'mid' }),
+                text: 'text',
+                styles: {
+                    ...font,
+                    fill: font?.fill ?? ctx.cfg.axis.color,
+                    fontSize: font?.fontSize ?? ctx.cfg.connector.labelFontSize,
+                    dx: font?.dx ?? at.dx,
+                    dy: font?.dy ?? at.dy,
+                    textAnchor: font?.textAnchor && font.textAnchor !== 'outside' ? font.textAnchor : at.textAnchor,
+                    lineAnchor: font?.lineAnchor ?? at.lineAnchor
+                }
+            }
+        ];
+    }
+    /**
+     * The value labels of the dots `styles.values.of` picks, one `'text'` marker
+     * per place a dot can hold in its range - past the top end (above, or right
+     * of it), past the bottom end (below, or left of it) and, for the dots
+     * between, beside it - and per series, when they take their series' color.
+     */
+    valueLabels = (labels, state, ctx) => {
+        if (!state.processedData?.data.length)
+            return [];
+        const { isHorizontal } = ClevelandMarkers.#geometry(state);
+        const { category, value } = ClevelandMarkers.#channels(state);
+        const { font, format } = labels;
+        const read = ValueLabels.valueOf(state);
+        const valueOf = ProcessedPositions.of(state.processedData, PlotAxes.valueOf(state))[PlotAxes.valueOf(state)];
+        const gap = labels.offset(isHorizontal ? 'x' : 'y', ctx.cfg[this.#options.config].labelGap);
+        const nameOf = (d) => String(d[SERIES_KEY]);
+        const picked = this.#picked(state);
+        // Where a label sits from its dot, by role: along the range (past an end) or across it (between).
+        const placement = {
+            max: isHorizontal
+                ? { dx: gap, dy: 0, textAnchor: 'start', lineAnchor: 'middle' }
+                : { dx: 0, dy: -gap, textAnchor: 'middle', lineAnchor: 'bottom' },
+            min: isHorizontal
+                ? { dx: -gap, dy: 0, textAnchor: 'end', lineAnchor: 'middle' }
+                : { dx: 0, dy: gap, textAnchor: 'middle', lineAnchor: 'top' },
+            between: isHorizontal
+                ? { dx: 0, dy: -gap, textAnchor: 'middle', lineAnchor: 'bottom' }
+                : { dx: gap, dy: 0, textAnchor: 'start', lineAnchor: 'middle' }
+        };
+        // What fills the labels of a series: the one fill all share, its own color, or the axis'.
+        const fillOf = (series) => labels.fill ??
+            (labels.color === 'series' ? state.colorForSeries(series) : undefined) ??
+            ctx.cfg.axis.color;
+        const names = labels.color === 'series' && !labels.fill
+            ? (state.resolvedSeries ?? []).map((s) => s.name)
+            : [''];
+        return ['max', 'min', 'between'].flatMap((role) => names.flatMap((name) => {
+            const data = picked
+                .filter(({ entry, dot }) => ClevelandRanges.roleOf(entry, dot.value) === role &&
+                (name === '' || dot.series === name))
+                .map(({ dot }) => dot.row);
+            if (data.length === 0)
+                return [];
+            const at = placement[role];
+            return [
+                {
+                    type: 'text',
+                    data,
+                    ...(isHorizontal ? { x: value, y: category } : { x: category, y: value }),
+                    text: (d) => format(Number(read(d) ?? valueOf(d)), nameOf(d), d),
+                    styles: {
+                        ...font,
+                        fill: fillOf(name),
+                        fontSize: font?.fontSize ?? 12,
+                        dx: font?.dx ?? at.dx,
+                        dy: font?.dy ?? at.dy,
+                        textAnchor: labels.textAnchor ?? at.textAnchor,
+                        lineAnchor: font?.lineAnchor ?? at.lineAnchor
+                    }
+                }
+            ];
+        }));
+    };
+    /**
+     * Room for the labels past the dots at the end of the value axis, so the
+     * farthest one fits inside the figure instead of crossing its edge. Only the
+     * dots at the top end of their range reach there, and only the picked ones.
+     */
+    reach = (labels, state) => {
+        const gap = labels.config[this.#options.config].labelGap;
+        const top = this.#picked(state).filter(({ entry, dot }) => ClevelandRanges.roleOf(entry, dot.value) === 'max');
+        if (top.length === 0)
+            return [];
+        if (!state.axes?.isHorizontal) {
+            const at = { y: -labels.offset('y', gap) };
+            return [labels.edgeBox('0', { x: 'middle', y: 'before' }, at, ['top'])];
+        }
+        const at = { x: labels.offset('x', gap) };
+        const texts = new Set(top.map(({ dot }) => labels.format(dot.value, dot.series, dot.row)));
+        return [...texts].map((text) => labels.edgeBox(text, { x: 'after', y: 'middle' }, at, ['right']));
+    };
+    /**
+     * The dots `styles.values` labels, each with the category it sits in: the rows
+     * the "transforms" phase picked (`labelled`), traced back to the dots of each
+     * category by the series they belong to.
+     */
+    #picked(state) {
+        const categoryAxis = PlotAxes.categoryOf(state);
+        const position = ProcessedPositions.of(state.processedData, PlotAxes.valueOf(state));
+        const ranges = ClevelandRanges.of(state, this.#options.fromBaseline ?? false, {}, this.#options.interval ?? false);
+        const keyOf = (category, series) => `${String(category)}\u0000${series}`;
+        const chosen = new Set((state.labelled ?? []).map((row) => keyOf(position[categoryAxis](row), String(row[SERIES_KEY]))));
+        return ranges.entries.flatMap((entry) => entry.dots
+            .filter((dot) => chosen.has(keyOf(entry.category, dot.series)))
+            .map((dot) => ({ entry, dot })));
+    }
+    /** Warns, once, when the series layout is not one this plot is for. */
+    #validate(ranges) {
+        const problem = this.#options.validate?.(ranges.layout);
+        if (!problem)
+            return;
+        const message = `${this.#options.name}: ${problem}`;
+        if (warned.has(message))
+            return;
+        warned.add(message);
+        console.warn(message);
+    }
+    static #geometry(state) {
+        return { isHorizontal: state.axes?.isHorizontal ?? false };
+    }
+    /** How the plot hands its category and value to the marks: raw when the transforms left a plain channel (a field key keeps feeding svelteplot's axis-title inference), through the positions otherwise. */
+    static #channels(state) {
+        const valueAxis = PlotAxes.valueOf(state);
+        const categoryAxis = PlotAxes.categoryOf(state);
+        const { channels } = state.processedData;
+        const position = ProcessedPositions.of(state.processedData, valueAxis);
+        return {
+            category: (channels[categoryAxis] ?? position[categoryAxis]),
+            value: (channels[valueAxis] ?? position[valueAxis])
+        };
+    }
+}

package/dist/plots/ranking/cleveland/ClevelandRanges.d.ts

@@ -0,0 +1,31 @@
+import { PlotAxes } from '../../../phases/data/PlotAxes';
+import type { ProcessedData, ProcessedRow } from '../../../types/phases';
+import type { ClevelandPlotState, ClevelandEntry, ClevelandLayout, ClevelandRole } from '../../../types/plots/ranking/cleveland/state';
+/**
+ * Where the dots of a Cleveland-style plot sit category by category: each
+ * category's values - across every series that has one - and the range they
+ * span, with the baseline counted as one end when the plot asks for it.
+ * Built from the rows the "transforms" phase left, so a series the legend
+ * omits is not in it.
+ */
+export declare class ClevelandRanges {
+    readonly entries: readonly ClevelandEntry[];
+    readonly layout: ClevelandLayout;
+    private constructor();
+    /**
+     * The ranges of `state`'s rows; `fromBaseline` adds the plot's baseline to each
+     * category's values. A category's difference runs from the series `ends.from`
+     * to `ends.to` - by default the first and the last one the plot draws.
+     */
+    static of<TData extends Record<string, unknown>>(state: ClevelandPlotState<TData>, fromBaseline: boolean, ends?: {
+        from?: string;
+        to?: string;
+    }, interval?: boolean): ClevelandRanges;
+    /** The rows that cannot be labelled, because they have no value: for the "transforms" phase's `labels.skip`. */
+    static skipGaps(state: {
+        processedData?: ProcessedData;
+        axes?: PlotAxes;
+    }): (row: ProcessedRow) => boolean;
+    /** Where `value` sits in its category's range: the top end when it is the largest (or the only one), the bottom end when the smallest, else between. */
+    static roleOf(entry: ClevelandEntry, value: number): ClevelandRole;
+}