@fundar/data-chart-telling 1.17.0 → 1.19.0

package/dist/markers/labels/LabelMerge.js

@@ -0,0 +1,87 @@
+/** The label a merged row was written by. */
+export const LABEL_SOURCE = Symbol('labelSource');
+/** What may differ from one merged label to another, each row reading its own: a field key is a field, a text either. */
+const ROW_KEYS = {
+    x: 'field',
+    y: 'field',
+    dx: 'field',
+    dy: 'field',
+    text: 'either',
+    textAnchor: 'literal',
+    lineAnchor: 'literal'
+};
+const ROW_STYLE_KEYS = ['fill', 'fillOpacity', 'stroke', 'strokeWidth', 'fontWeight', 'fontStyle'];
+/** Functions of the row each row calls its own label's: handlers, and where its point sits. */
+const ROW_FUNCTIONS = ['origin', 'covers'];
+const dispatched = (key) => ROW_FUNCTIONS.includes(key) || (key.startsWith('on') && key !== 'onoverflow');
+const read = (value, row, as) => {
+    if (typeof value === 'function')
+        return value(row);
+    const key = typeof value === 'string' || typeof value === 'symbol';
+    if (!key || as === 'literal')
+        return value;
+    return as === 'field' || (row && value in row) ? row?.[value] : value;
+};
+/**
+ * Labels drawn as one `text` marker: those whose other options are alike merge, each row tagged with the label
+ * it comes from, so labels from several markers declutter together and draw as one.
+ */
+export class LabelMerge {
+    static merge(markers) {
+        const groups = new Map();
+        const ids = new Map();
+        for (const marker of markers) {
+            const key = LabelMerge.#signature(marker, ids);
+            groups.set(key, [...(groups.get(key) ?? []), marker]);
+        }
+        return [...groups.values()].map((group) => group.length === 1 ? group[0] : LabelMerge.#merged(group));
+    }
+    static #merged(sources) {
+        const data = sources.flatMap((source, i) => (source.data ?? []).map((row) => ({ ...row, [LABEL_SOURCE]: i })));
+        const sourceOf = (row) => sources[row[LABEL_SOURCE]];
+        const pick = (values, at, as) => values.every((value) => value === values[0])
+            ? values[0]
+            : (row) => read(at(sourceOf(row)), row, as);
+        const merged = { ...sources[0], data };
+        for (const [key, as] of Object.entries(ROW_KEYS)) {
+            merged[key] = pick(sources.map((source) => source[key]), (source) => source[key], as);
+        }
+        const stylesOf = (source) => (source.styles ?? {});
+        const styles = { ...stylesOf(sources[0]) };
+        for (const key of ROW_STYLE_KEYS) {
+            styles[key] = pick(sources.map((source) => stylesOf(source)[key]), (source) => stylesOf(source)[key], 'either');
+        }
+        merged.styles = styles;
+        for (const key of new Set(sources.flatMap((source) => Object.keys(source)))) {
+            if (!dispatched(key))
+                continue;
+            const own = sources.map((source) => source[key]);
+            if (own.every((fn) => fn === own[0]))
+                continue;
+            const call = (row, args) => sourceOf(row)[key]?.(...args);
+            merged[key] = ROW_FUNCTIONS.includes(key)
+                ? (row, scales) => call(row, [row, scales])
+                : (event, row, index) => call(row, [event, row, index]);
+        }
+        return merged;
+    }
+    /** What labels share to merge: every option but their rows and what each row reads on its own. */
+    static #signature(marker, ids) {
+        const shared = {};
+        for (const [key, value] of Object.entries(marker)) {
+            if (key === 'data' || key in ROW_KEYS || dispatched(key))
+                continue;
+            shared[key] = value;
+        }
+        const styles = (marker.styles ?? {});
+        shared.styles = Object.fromEntries(Object.entries(styles).filter(([key]) => !ROW_STYLE_KEYS.includes(key)));
+        // A function or a symbol is told apart by its identity.
+        return JSON.stringify(shared, (_, value) => {
+            if (typeof value !== 'function' && typeof value !== 'symbol')
+                return value;
+            if (!ids.has(value))
+                ids.set(value, ids.size);
+            return `#${ids.get(value)}`;
+        });
+    }
+}

package/dist/markers/labels/MarkerLabel.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+	import TextMarker from '../text/TextMarker.svelte';
+	import CurveLabel from './CurveLabel.svelte';
+	import { getConfiguration } from '../../configuration/config.svelte';
+	import { usePlot } from '../../layout/plot/usePlot';
+	import { MarkerLabels } from './MarkerLabels';
+	import { MARK_EVENTS } from '../../types/markers/channels/commonMarkerEvents';
+	import type { BoxedMarker } from '../../types/markers/labels/box';
+	import type { MarkerLabelConfig } from '../../types/markers/labels/common';
+
+	const { marker }: { marker: BoxedMarker & { label?: MarkerLabelConfig | MarkerLabelConfig[] } } =
+		$props();
+	const plot = usePlot();
+	const cfg = $derived(getConfiguration());
+
+	const labels = $derived(
+		MarkerLabels.build(marker, {
+			isHorizontal: plot.axes?.isHorizontal,
+			gap: cfg.text.label.gap,
+			scales: () => plot.svelteplot.scales as never
+		})
+	);
+	const curves = $derived(MarkerLabels.curves(marker));
+	// Without a handler of its own, a label leaves the pointer to its shape.
+	const listens = (label: (typeof labels)[number]) =>
+		MARK_EVENTS.some((name) => !!(label.marker as Record<string, unknown>)[name]);
+</script>
+
+{#each labels as label, i (i)}
+	<g pointer-events={listens(label) ? undefined : 'none'}>
+		<TextMarker marker={label.marker} box={label.box} />
+	</g>
+{/each}
+{#each curves as curve, i (i)}
+	<CurveLabel marker={marker as Record<string, unknown>} label={curve.label} shape={curve.shape} />
+{/each}

package/dist/markers/labels/MarkerLabel.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { BoxedMarker } from '../../types/markers/labels/box';
+import type { MarkerLabelConfig } from '../../types/markers/labels/common';
+type $$ComponentProps = {
+    marker: BoxedMarker & {
+        label?: MarkerLabelConfig | MarkerLabelConfig[];
+    };
+};
+declare const MarkerLabel: import("svelte").Component<$$ComponentProps, {}, "">;
+type MarkerLabel = ReturnType<typeof MarkerLabel>;
+export default MarkerLabel;

package/dist/markers/labels/MarkerLabels.d.ts

@@ -0,0 +1,52 @@
+import type { BoxLabelMarker, BoxScales, BoxedMarker } from '../../types/markers/labels/box';
+import type { LabelLayout, MarkerLabelConfig } from '../../types/markers/labels/common';
+import type { PathLabelConfig, PathShape } from '../../types/markers/labels/path';
+import type { TextMarkerConfig } from '../../types/markers/basic/text';
+type Labelled = BoxedMarker & {
+    label?: MarkerLabelConfig | MarkerLabelConfig[];
+};
+type LabelPlot = {
+    isHorizontal?: boolean;
+    scales?: () => BoxScales | undefined;
+    gap?: number;
+};
+/** A marker's labels, each laid out in its `layout` (else its kind's) on the geometry its kind gives it. */
+export declare class MarkerLabels {
+    static list(marker: {
+        label?: MarkerLabelConfig | MarkerLabelConfig[];
+    }): MarkerLabelConfig[];
+    /** Maps each label, keeping a single one single. */
+    static map<T>(marker: T, fn: (label: MarkerLabelConfig) => MarkerLabelConfig): T;
+    /** `undefined` when the kind does not support it. */
+    static layoutOf(marker: {
+        type?: string;
+    }, label: MarkerLabelConfig): LabelLayout | undefined;
+    /** Whether it is read on its shape's color. */
+    static isOnShape(marker: {
+        type?: string;
+    }, label: MarkerLabelConfig): boolean;
+    /** The `'box'` and `'path'` labels of a marker, drawn with its shapes. */
+    static build(marker: Labelled, plot?: LabelPlot): BoxLabelMarker[];
+    /** The `'path'` labels a marker writes along its curves - its lines, an area's edge, each dot's rim - with their shape. */
+    static curves(marker: {
+        type?: string;
+        label?: MarkerLabelConfig | MarkerLabelConfig[];
+    }): {
+        label: PathLabelConfig<string, string>;
+        shape: Exclude<PathShape, 'box'>;
+    }[];
+    /**
+     * `markers` without their `'point'` labels, and those labels as `text` markers, merged where alike so they
+     * declutter together. `rows` are what a marker with no `data` of its own draws.
+     */
+    static extractPoints<T extends object>(markers: T[], plot?: {
+        rows?: unknown[];
+        valueAxis?: 'x' | 'y';
+        isHorizontal?: boolean;
+        gap?: number;
+    }): {
+        markers: T[];
+        labels: TextMarkerConfig[];
+    };
+}
+export {};

package/dist/markers/labels/MarkerLabels.js

@@ -0,0 +1,97 @@
+import { MarkerKinds } from '../MarkerKinds';
+import { BoxGeometry } from './geometry/BoxGeometry';
+import { PointGeometry } from './geometry/PointGeometry';
+import { BoxLayout } from './layouts/BoxLayout';
+import { PathLayout } from './layouts/PathLayout';
+import { PointLayout } from './layouts/PointLayout';
+import { LabelMerge } from './LabelMerge';
+import { SERIES_KEY } from '../../phases/transforms/TransformsPhase';
+/** A marker's labels, each laid out in its `layout` (else its kind's) on the geometry its kind gives it. */
+export class MarkerLabels {
+    static list(marker) {
+        const { label } = marker;
+        return label === undefined ? [] : Array.isArray(label) ? label : [label];
+    }
+    /** Maps each label, keeping a single one single. */
+    static map(marker, fn) {
+        const { label } = marker;
+        if (label === undefined)
+            return marker;
+        return { ...marker, label: Array.isArray(label) ? label.map(fn) : fn(label) };
+    }
+    /** `undefined` when the kind does not support it. */
+    static layoutOf(marker, label) {
+        const traits = MarkerKinds.of(marker.type)?.labels;
+        if (!traits)
+            return undefined;
+        const layout = label.layout ?? traits.default;
+        return traits[layout] === undefined ? undefined : layout;
+    }
+    /** Whether it is read on its shape's color. */
+    static isOnShape(marker, label) {
+        const layout = MarkerLabels.layoutOf(marker, label);
+        return layout === 'box' || (layout === 'path' && label.side === 'inside');
+    }
+    /** The `'box'` and `'path'` labels of a marker, drawn with its shapes. */
+    static build(marker, plot = {}) {
+        const shape = MarkerKinds.of(marker.type)?.labels?.box;
+        if (!shape)
+            return [];
+        const options = { data: marker.data, scales: plot.scales, gap: plot.gap };
+        return MarkerLabels.list(marker).flatMap((label) => {
+            const layout = MarkerLabels.layoutOf(marker, label);
+            if (layout !== 'box' && layout !== 'path')
+                return [];
+            const geometry = BoxGeometry.of(shape, marker, plot);
+            if (!geometry)
+                return [];
+            const built = layout === 'box'
+                ? BoxLayout.build(label, geometry, options)
+                : PathLayout.build(label, geometry, options);
+            return built ? [built] : [];
+        });
+    }
+    /** The `'path'` labels a marker writes along its curves - its lines, an area's edge, each dot's rim - with their shape. */
+    static curves(marker) {
+        const shape = MarkerKinds.of(marker.type)?.labels?.path;
+        if (!shape || shape === 'box')
+            return [];
+        return MarkerLabels.list(marker)
+            .filter((label) => MarkerLabels.layoutOf(marker, label) === 'path')
+            .map((label) => ({ label: label, shape }));
+    }
+    /**
+     * `markers` without their `'point'` labels, and those labels as `text` markers, merged where alike so they
+     * declutter together. `rows` are what a marker with no `data` of its own draws.
+     */
+    static extractPoints(markers, plot = {}) {
+        const labels = [];
+        const stripped = markers.map((marker) => {
+            const own = marker;
+            const traits = MarkerKinds.of(own.type)?.labels;
+            const shape = traits?.point;
+            const all = MarkerLabels.list(own);
+            const points = all.filter((label) => MarkerLabels.layoutOf(own, label) === 'point');
+            if (points.length === 0)
+                return marker;
+            const point = shape && PointGeometry.of(shape, own, { box: traits.box, isHorizontal: plot.isHorizontal });
+            if (point) {
+                const rows = own.data ??
+                    (plot.rows ?? []).filter((row) => own.series === undefined ||
+                        row[SERIES_KEY] === own.series);
+                for (const label of points) {
+                    const text = PointLayout.build(label, point, rows, {
+                        grouping: own.grouping,
+                        valueAxis: plot.valueAxis,
+                        gap: plot.gap
+                    });
+                    if (text)
+                        labels.push(text);
+                }
+            }
+            const rest = all.filter((label) => !points.includes(label));
+            return { ...marker, label: rest.length > 0 ? rest : undefined };
+        });
+        return { markers: stripped, labels: LabelMerge.merge(labels) };
+    }
+}

package/dist/markers/labels/geometry/BoxGeometry.d.ts

@@ -0,0 +1,8 @@
+import type { BoxGeometryOf, BoxShape, BoxedMarker } from '../../../types/markers/labels/box';
+/** The box each row of a marker spans, as its kind's {@link BoxShape} tells it. */
+export declare class BoxGeometry {
+    #private;
+    static of(shape: BoxShape, marker: BoxedMarker, plot?: {
+        isHorizontal?: boolean;
+    }): BoxGeometryOf | undefined;
+}

package/dist/markers/labels/geometry/BoxGeometry.js

@@ -0,0 +1,101 @@
+const read = (edge) => (row) => typeof edge === 'function'
+    ? edge(row)
+    : typeof edge === 'string' || typeof edge === 'symbol'
+        ? row?.[edge]
+        : edge;
+const middle = (from, to) => from instanceof Date || to instanceof Date
+    ? new Date((Number(from) + Number(to)) / 2)
+    : (Number(from) + Number(to)) / 2;
+const bandwidth = (scale) => scale?.type === 'band' ? Number(scale.fn.bandwidth()) : undefined;
+const distance = (scale, from, to) => scale ? Math.abs(Number(scale.fn(to)) - Number(scale.fn(from))) : undefined;
+/** The box each row of a marker spans, as its kind's {@link BoxShape} tells it. */
+export class BoxGeometry {
+    static of(shape, marker, plot = {}) {
+        if (shape === 'cell')
+            return BoxGeometry.#cell(marker);
+        if (shape === 'band') {
+            return marker.role === 'hitArea'
+                ? undefined
+                : BoxGeometry.#band(marker, marker.isHorizontal ?? plot.isHorizontal ?? false);
+        }
+        return BoxGeometry.#edges(marker);
+    }
+    /** A style of the marker, only when it is a number. */
+    static #style(marker, name) {
+        const value = marker.styles?.[name];
+        return typeof value === 'number' ? value : undefined;
+    }
+    static #edges({ x, y, x1, x2, y1, y2 }) {
+        // A side with only a value runs from zero to it, as a bar does.
+        if (y1 === undefined &&
+            y2 === undefined &&
+            y !== undefined &&
+            x1 !== undefined &&
+            x2 !== undefined) {
+            [y1, y2] = [0, y];
+        }
+        if (x1 === undefined &&
+            x2 === undefined &&
+            x !== undefined &&
+            y1 !== undefined &&
+            y2 !== undefined) {
+            [x1, x2] = [0, x];
+        }
+        if ([x1, x2, y1, y2].some((edge) => edge === undefined))
+            return undefined;
+        const [left, right, top, bottom] = [x1, x2, y1, y2].map(read);
+        const size = (row, scales) => {
+            const [width, height] = [
+                distance(scales.x, left(row), right(row)),
+                distance(scales.y, top(row), bottom(row))
+            ];
+            return width === undefined || height === undefined ? undefined : { width, height };
+        };
+        return {
+            box: { x1, x2, y1, y2 },
+            size,
+            x: (row) => middle(left(row), right(row)),
+            y: (row) => middle(top(row), bottom(row))
+        };
+    }
+    static #cell(marker) {
+        if (marker.x === undefined || marker.y === undefined)
+            return undefined;
+        const inset = Number(BoxGeometry.#style(marker, 'inset') ?? 0.5);
+        const box = (_, scales) => {
+            const [width, height] = [bandwidth(scales.x), bandwidth(scales.y)];
+            return width === undefined || height === undefined
+                ? undefined
+                : { width: width - 2 * inset, height: height - 2 * inset };
+        };
+        return { box, size: box, x: marker.x, y: marker.y };
+    }
+    static #band(marker, isHorizontal) {
+        const [category, from, to] = isHorizontal
+            ? [marker.y, marker.x1, marker.x2]
+            : [marker.x, marker.y1, marker.y2];
+        const value = isHorizontal ? marker.x : marker.y;
+        const [start, end] = from !== undefined && to !== undefined ? [from, to] : [0, value];
+        if (category === undefined || end === undefined)
+            return undefined;
+        const [first, last] = [start, end].map(read);
+        const [before, after] = isHorizontal
+            ? [BoxGeometry.#style(marker, 'insetTop'), BoxGeometry.#style(marker, 'insetBottom')]
+            : [BoxGeometry.#style(marker, 'insetLeft'), BoxGeometry.#style(marker, 'insetRight')];
+        const middleOf = (row) => middle(first(row), last(row));
+        const box = (row, scales) => {
+            const band = bandwidth(isHorizontal ? scales.y : scales.x);
+            const length = distance(isHorizontal ? scales.x : scales.y, first(row), last(row));
+            if (band === undefined || length === undefined)
+                return undefined;
+            const thickness = marker.thickness ?? band * (1 - Number(before ?? 0) - Number(after ?? 0));
+            return isHorizontal
+                ? { width: length, height: thickness }
+                : { width: thickness, height: length };
+        };
+        const ends = { axis: isHorizontal ? 'x' : 'y', from: first, to: last };
+        return isHorizontal
+            ? { box, size: box, ends, x: middleOf, y: category }
+            : { box, size: box, ends, x: category, y: middleOf };
+    }
+}

package/dist/markers/labels/geometry/CurveGeometry.d.ts

@@ -0,0 +1,34 @@
+import type { BoxScales } from '../../../types/markers/labels/box';
+import type { CurveName } from '../../../types/layout/styles/curve';
+import type { CurvedLabel, PathLabelConfig, PathShape } from '../../../types/markers/labels/path';
+type CurvedMarker = {
+    data?: unknown[];
+    x?: unknown;
+    y?: unknown;
+    x1?: unknown;
+    x2?: unknown;
+    y1?: unknown;
+    y2?: unknown;
+    r?: unknown;
+    grouping?: unknown;
+    color?: unknown;
+    curve?: CurveName;
+    tension?: number;
+    isHorizontal?: boolean;
+    styles?: Record<string, unknown>;
+};
+/**
+ * The curves a marker writes its `'path'` labels along, in pixels: each line (one per `grouping`), the top or
+ * bottom edge of each area, or the rim of each dot, as its kind's {@link PathShape} tells it.
+ */
+export declare class CurveGeometry {
+    #private;
+    static build(shape: Exclude<PathShape, 'box'>, marker: CurvedMarker, label: PathLabelConfig<string, string>, plot: {
+        scales: BoxScales;
+        gap: number;
+        dotRadius?: number;
+        /** How wide a text is written, in pixels: a label centred near an end of its line is moved in to fit. */
+        measure?: (text: string) => number;
+    }): CurvedLabel[];
+}
+export {};

package/dist/markers/labels/geometry/CurveGeometry.js

@@ -0,0 +1,193 @@
+import { line } from 'd3-shape';
+import { DotRadius } from '../../dot/DotRadius';
+import { maybeCurve } from 'svelteplot/helpers/curves.js';
+const read = (channel) => (row) => typeof channel === 'function'
+    ? channel(row)
+    : typeof channel === 'string' || typeof channel === 'symbol'
+        ? row?.[channel]
+        : channel;
+const placed = (value) => value !== null && value !== undefined && !(typeof value === 'number' && Number.isNaN(value));
+/**
+ * The curves a marker writes its `'path'` labels along, in pixels: each line (one per `grouping`), the top or
+ * bottom edge of each area, or the rim of each dot, as its kind's {@link PathShape} tells it.
+ */
+export class CurveGeometry {
+    static build(shape, marker, label, plot) {
+        const rows = (marker.data ?? []).filter((row) => row !== null && row !== undefined);
+        const { scales } = plot;
+        const gap = label.gap ?? plot.gap;
+        const at = (axis, value) => {
+            const scale = scales[axis];
+            if (!scale || !placed(value))
+                return undefined;
+            const band = scale.type === 'band' ? Number(scale.fn.bandwidth()) / 2 : 0;
+            const px = Number(scale.fn(value)) + band;
+            return Number.isFinite(px) ? px : undefined;
+        };
+        const textOf = CurveGeometry.#text(label.text);
+        const colorOf = CurveGeometry.#color(marker, scales);
+        if (shape === 'rim') {
+            const side = label.side ?? 'outside';
+            const [x, y] = [read(marker.x), read(marker.y)];
+            return rows.flatMap((row) => {
+                const [cx, cy] = [at('x', x(row)), at('y', y(row))];
+                const r = DotRadius.of(marker, row, scales, plot.dotRadius ?? 5);
+                if (cx === undefined || cy === undefined)
+                    return [];
+                // From its bottom, clockwise: up its left, over its top - the side text reads upright on - and down its
+                // right, so a text centred on the top has half the circle free on either side.
+                const d = `M${cx},${cy + r}A${r},${r} 0 1 1 ${cx},${cy - r}A${r},${r} 0 1 1 ${cx},${cy + r}`;
+                return [
+                    {
+                        d,
+                        text: textOf(row),
+                        row,
+                        ...CurveGeometry.#along(label.offset, 0.5, 0.25),
+                        ...CurveGeometry.#across(side === 'outside' ? 'above' : side === 'inside' ? 'below' : 'on', gap),
+                        fill: colorOf(row)
+                    }
+                ];
+            });
+        }
+        const [x, y] = CurveGeometry.#channels(shape, marker, label);
+        const groupOf = read(marker.grouping);
+        const groups = new Map();
+        for (const row of rows) {
+            const key = marker.grouping === undefined ? undefined : groupOf(row);
+            groups.set(key, [...(groups.get(key) ?? []), row]);
+        }
+        // Text along a straight stretch's corners spreads its letters apart: a linear line is read along a smooth one
+        // through the same points, which never overshoots them.
+        const curve = !marker.curve || marker.curve === 'linear' ? 'monotone-x' : marker.curve;
+        const path = line().curve(maybeCurve(curve, marker.tension ?? 0));
+        return [...groups.values()].flatMap((members) => {
+            const points = members.flatMap((row) => {
+                const [px, py] = [at('x', x(row)), at('y', y(row))];
+                return px === undefined || py === undefined ? [] : [[px, py]];
+            });
+            if (points.length < 2)
+                return [];
+            // Text reads left to right: a line drawn the other way is written along its reverse.
+            if (points[0][0] > points[points.length - 1][0])
+                points.reverse();
+            const d = path(points);
+            if (!d)
+                return [];
+            const offset = label.offset === 'max' || label.offset === 'min'
+                ? CurveGeometry.#extreme(points, label.offset, marker.isHorizontal)
+                : label.offset;
+            const text = textOf(members[0]);
+            const along = CurveGeometry.#along(offset, 1);
+            return [
+                {
+                    d,
+                    text,
+                    row: members[0],
+                    ...along,
+                    ...CurveGeometry.#inside(along, plot.measure?.(text), CurveGeometry.#length(points)),
+                    ...CurveGeometry.#across(label.side ?? 'above', gap),
+                    fill: colorOf(members[0])
+                }
+            ];
+        });
+    }
+    /** A centred text moved in along its line just enough to fit whole on it: what falls past an end is not drawn. */
+    static #inside(along, width, length) {
+        if (!width || along.textAnchor !== 'middle' || length <= 0)
+            return {};
+        const half = Math.min(50, (width / 2 / length) * 100);
+        const at = Number.parseFloat(along.startOffset);
+        const fitted = Math.min(Math.max(at, half), 100 - half);
+        return fitted === at ? {} : { startOffset: `${Number(fitted.toFixed(3))}%` };
+    }
+    /** The length of the line through `points`, in pixels. */
+    static #length(points) {
+        let total = 0;
+        for (let i = 1; i < points.length; i++) {
+            total += Math.hypot(points[i][0] - points[i - 1][0], points[i][1] - points[i - 1][1]);
+        }
+        return total;
+    }
+    /**
+     * How far along `points` - as a share of their length - the one with the highest (`'max'`) or lowest value is:
+     * the one highest up the page, or furthest right on a horizontal area.
+     */
+    static #extreme(points, which, isHorizontal) {
+        const valueOf = ([px, py]) => (isHorizontal ? px : -py);
+        let at = 0;
+        points.forEach((point, i) => {
+            const better = which === 'max'
+                ? valueOf(point) > valueOf(points[at])
+                : valueOf(point) < valueOf(points[at]);
+            if (better)
+                at = i;
+        });
+        let total = 0;
+        let upTo = 0;
+        for (let i = 1; i < points.length; i++) {
+            total += Math.hypot(points[i][0] - points[i - 1][0], points[i][1] - points[i - 1][1]);
+            if (i === at)
+                upTo = total;
+        }
+        return `${total > 0 ? (upTo / total) * 100 : 50}%`;
+    }
+    /** The channels the curve runs through: a line's own, or an area's top or bottom edge. */
+    static #channels(shape, marker, label) {
+        if (shape === 'stroke')
+            return [read(marker.x), read(marker.y)];
+        const top = (label.edge ?? 'top') === 'top';
+        if (marker.isHorizontal) {
+            const edge = top ? (marker.x2 ?? marker.x) : (marker.x1 ?? 0);
+            return [read(edge), read(marker.y)];
+        }
+        const edge = top ? (marker.y2 ?? marker.y) : (marker.y1 ?? 0);
+        return [read(marker.x), read(edge)];
+    }
+    /**
+     * Where along the curve, as `startOffset` and `text-anchor`: `offset` runs over the stretch of it that starts at
+     * `from` and spans `extent` - a rim's upper half, from its left side to its right.
+     */
+    static #along(offset = 'middle', extent, from = 0) {
+        const share = (fraction) => `${Number(((from + fraction * extent) * 100).toFixed(3))}%`;
+        if (offset === 'start')
+            return { startOffset: share(0), textAnchor: 'start' };
+        if (offset === 'end')
+            return { startOffset: share(1), textAnchor: 'end' };
+        const percent = offset === 'middle' ? 50 : Number.parseFloat(offset);
+        const fraction = Number.isFinite(percent) ? Math.min(Math.max(percent / 100, 0), 1) : 0.5;
+        return { startOffset: share(fraction), textAnchor: 'middle' };
+    }
+    /** Which side of the curve, as the text reads it. */
+    static #across(side, gap) {
+        if (side === 'below')
+            return { dy: gap, baseline: 'hanging' };
+        if (side === 'on')
+            return { dy: 0, baseline: 'central' };
+        return { dy: -gap, baseline: 'auto' };
+    }
+    /** A label's text: a function of the row, a field of it, else the text itself. */
+    static #text(text) {
+        return (row) => {
+            if (typeof text === 'function')
+                return String(text(row) ?? '');
+            if (typeof text === 'string' && row && typeof row === 'object' && text in row) {
+                return String(row[text] ?? '');
+            }
+            return text === undefined || text === null ? '' : String(text);
+        };
+    }
+    /** The marker's own color for a row: its `color` channel's, else its stroke or fill when that is one color. */
+    static #color(marker, scales) {
+        const scale = scales.color;
+        if (marker.color !== undefined && scale) {
+            const color = read(marker.color);
+            return (row) => {
+                const value = scale.fn(color(row));
+                return typeof value === 'string' ? value : undefined;
+            };
+        }
+        const { stroke, fill, dotFill } = marker.styles ?? {};
+        const own = [stroke, fill, dotFill].find((value) => typeof value === 'string');
+        return () => own;
+    }
+}

package/dist/markers/labels/geometry/PointGeometry.d.ts

@@ -0,0 +1,9 @@
+import type { BoxShape, BoxedMarker } from '../../../types/markers/labels/box';
+import type { PointGeometryOf, PointShape } from '../../../types/markers/labels/point';
+/** The point each row of a marker is labelled at, as its kind's {@link PointShape} tells it. */
+export declare class PointGeometry {
+    static of(shape: PointShape, marker: BoxedMarker, plot?: {
+        box?: BoxShape;
+        isHorizontal?: boolean;
+    }): PointGeometryOf | undefined;
+}

package/dist/markers/labels/geometry/PointGeometry.js

@@ -0,0 +1,22 @@
+import { BoxGeometry } from './BoxGeometry';
+import { DotRadius } from '../../dot/DotRadius';
+/** The point each row of a marker is labelled at, as its kind's {@link PointShape} tells it. */
+export class PointGeometry {
+    static of(shape, marker, plot = {}) {
+        if (shape === 'box') {
+            const geometry = plot.box && BoxGeometry.of(plot.box, marker, plot);
+            return geometry && { x: geometry.x, y: geometry.y, size: geometry.size };
+        }
+        if (shape === 'dot') {
+            if (marker.x === undefined || marker.y === undefined)
+                return undefined;
+            const size = (row, scales) => {
+                const r = DotRadius.of(marker, row, scales);
+                return { width: 2 * r, height: 2 * r };
+            };
+            return { x: marker.x, y: marker.y, size, round: true };
+        }
+        const y = shape === 'top' ? (marker.y2 ?? marker.y) : marker.y;
+        return marker.x === undefined || y === undefined ? undefined : { x: marker.x, y };
+    }
+}

package/dist/markers/labels/layouts/BoxLayout.d.ts

@@ -0,0 +1,10 @@
+import type { BoxGeometryOf, BoxLabelConfig, BoxLabelMarker, BoxScales } from '../../../types/markers/labels/box';
+/** The `text` marker that writes a `'box'` label, anchored in the box of each shape. */
+export declare class BoxLayout {
+    #private;
+    static build(label: BoxLabelConfig, geometry: BoxGeometryOf, plot?: {
+        data?: unknown[];
+        scales?: () => BoxScales | undefined;
+        gap?: number;
+    }): BoxLabelMarker;
+}