@fundar/data-chart-telling 0.0.25 → 0.0.26

package/dist/plots/scatter/Plot.svelte

@@ -0,0 +1,206 @@
+<script
+  lang="ts"
+  generics="TData extends Record<string, unknown>"
+>
+  import { resolveAccessor } from '../utils/accessors';
+  import { getConfiguration } from '../../configuration/config.svelte';
+  import { paletteColor } from '../../utils/color';
+  import { buildSeries } from '../../utils/grouping';
+  import { getLegendInteraction } from '../../layout/legend/interaction.svelte';
+  import { disabledDotsOverride } from '../utils/legendDisabled';
+  import { buildScatterMarkers } from './buildScatterMarkers';
+  import { resolveRadiusPaddedDomain } from './resolveRadiusPaddedDomain';
+  import BasePlotLayout from '../../layout/plot/BasePlotLayout.svelte';
+  import ValueLabels from './ValueLabels.svelte';
+  import { hasHoverMarker, resolveHoverStrategy, resolveHoverSync } from '../../layout/tooltip/utils';
+  import { buildGroupedSeries, validateSegments, buildScopedMarkerGroups } from '../utils/segments';
+  import { numericMargin } from '../../layout/plot/margins';
+  import type { BasePlotProps } from '../../types/plots/props';
+  import type { AxisValue, AxisBasedScalesConfig } from '../../types/layout/scales';
+  import type { Series } from '../../types/plots/data/common';
+  import type { ScatterDataProps } from '../../types/plots/data/scatter';
+  import type { BasePlotStylesConfig } from '../../types/layout/styles';
+  import type { ScatterSegmentStyle } from '../../types/plots/segments/common';
+  import type { AxisBasedMarkersConfig } from '../../types/markers/common';
+
+  /**
+   * A point cloud on continuous x/y axes. Accepts either a pre-built `series`
+   * array or flat `data/x/y/z` props — mirrors the line/bar plot contract so
+   * the chart-level container/timeline/facet/legend wrap it unchanged. `r`
+   * gives every dot a per-row radius (bubble sizing), independent of `z`
+   * grouping/coloring — see {@link ScatterDataProps} for its auto-scaling
+   * behavior.
+   */
+  type Props = BasePlotProps<
+    ScatterDataProps<TData>,
+    TData,
+    BasePlotStylesConfig,
+    ScatterSegmentStyle,
+    AxisBasedMarkersConfig,
+    AxisBasedScalesConfig<TData>
+  >;
+
+  let {
+    width,
+    height,
+    series,
+    data,
+    x,
+    y,
+    z,
+    r,
+    styles = {},
+    segments = {},
+    markers = [],
+    scales = {},
+    margins,
+    tooltip = undefined,
+  }: Props = $props();
+
+  const resolvedSeries = $derived(series ?? buildSeries(data!, x!, y!, z));
+  const legendInteraction = $derived(getLegendInteraction());
+
+  $effect(() => { validateSegments(segments); });
+
+  // A scatter point cloud is discrete (no connecting line), so adjacent
+  // segments never need a bridge point at their boundary — see
+  // buildGroupedSeries's own doc.
+  const groupedSeries = $derived(
+    buildGroupedSeries<Series<TData>, ScatterSegmentStyle>(resolvedSeries, segments, false),
+  );
+
+  const cfg = $derived(getConfiguration());
+  const showVals = $derived(styles.values?.show ?? false);
+  const fmtVal = $derived(styles.values?.format ?? ((v: number) => `${v}`));
+
+  const xAcc = $derived(resolveAccessor(resolvedSeries[0]?.x ?? ((d: TData) => d)));
+  const yAcc = $derived(resolveAccessor(resolvedSeries[0]?.y ?? ((d: TData) => d)));
+  const flat = $derived(resolvedSeries.flatMap((s) => s.data));
+
+  // A legend-disabled series is dimmed on the mark itself, but never surfaces
+  // in hover/tooltip — its points are simply absent from the candidate list.
+  const hoverPoints = $derived(
+    resolvedSeries.flatMap((s, idx) => {
+      if (legendInteraction?.disabledSeries.has(s.name)) return [];
+      const sx = resolveAccessor(s.x);
+      const sy = resolveAccessor(s.y);
+      return s.data.map((d) => ({
+        x: sx(d) as AxisValue,
+        y: Number(sy(d)),
+        row: d,
+        label: `${sx(d)}, ${sy(d)}`,
+        series: s.name,
+        color: paletteColor(idx, cfg.palette),
+      }));
+    }),
+  );
+
+  // Points scatter freely across x/y rather than sharing discrete x values —
+  // 'punctual' matches the single nearest point, not a whole column.
+  const hover = $derived({
+    active: tooltip != null || hasHoverMarker(markers),
+    points: hoverPoints,
+    label: (row: TData) => `${xAcc(row)}, ${yAcc(row)}`,
+    strategy: resolveHoverStrategy(tooltip?.strategy, markers, 'punctual'),
+    sync: resolveHoverSync(tooltip?.sync, markers),
+    tooltip,
+  });
+
+  const scatterMarkers = $derived(
+    buildScatterMarkers({
+      groupedSeries,
+      r,
+      disabledDotsFor: (name) => disabledDotsOverride(legendInteraction?.disabledSeries.get(name)),
+    }),
+  );
+
+  const scopedGroups = $derived(
+    buildScopedMarkerGroups<TData, Series<TData>, ScatterSegmentStyle>({
+      groupedSeries,
+      segments,
+      colorFor: (_series, seriesIndex) => paletteColor(seriesIndex, cfg.palette),
+      segmentColorFor: (style, defaultColor) => style?.dotFill ?? defaultColor,
+    }),
+  );
+
+  // svelteplot treats a per-row `r` (a field key or accessor function) as a
+  // proper channel bound to its own auto sqrt scale — the raw values it
+  // returns (e.g. a population in the millions) are data, not pixels, and
+  // get compressed into a modest, roughly data-magnitude-independent pixel
+  // range regardless of how large the raw numbers are. A literal constant
+  // `r` (or the theme/segment `dotRadius` fallback), by contrast, *is*
+  // already a literal pixel value. `AUTO_SCALED_RADIUS_ESTIMATE` stands in
+  // for whatever svelteplot's own r-scale ends up rendering at, since the
+  // real value isn't knowable until that scale is built.
+  const AUTO_SCALED_RADIUS_ESTIMATE = 20;
+
+  // The largest radius any dot actually renders at — pads the scale domain
+  // below so a point at the data extreme doesn't get its own circle clipped
+  // by the frame. svelteplot's own 'auto' margin only measures axis chrome,
+  // never mark geometry.
+  const maxDotRadius = $derived.by(() => {
+    let max = 0;
+    for (const marker of scatterMarkers) {
+      const rConst = typeof marker.r === 'number' ? marker.r : undefined;
+      const isChannel = typeof marker.r === 'function';
+      const fallbackR = marker.style?.dotRadius ?? cfg.scatter.dotRadius;
+      if (rConst !== undefined) {
+        max = Math.max(max, rConst);
+      } else if (isChannel) {
+        max = Math.max(max, AUTO_SCALED_RADIUS_ESTIMATE);
+      } else {
+        max = Math.max(max, fallbackR);
+      }
+    }
+    return max;
+  });
+
+  // Best-effort pre-render estimate of the plot's own inner content size —
+  // the real size isn't known until svelteplot measures its own axis
+  // chrome, so this is only used to convert a pixel radius into a domain
+  // padding amount, not as the actual rendered margin.
+  const estimatedMargins = $derived({ ...cfg.margins, ...margins });
+  const estimatedInnerWidth = $derived(
+    width - numericMargin('left', estimatedMargins.left) - numericMargin('right', estimatedMargins.right),
+  );
+  const estimatedInnerHeight = $derived(
+    height - numericMargin('top', estimatedMargins.top) - numericMargin('bottom', estimatedMargins.bottom),
+  );
+
+  const resolvedScales = $derived.by((): AxisBasedScalesConfig<TData> => {
+    if (maxDotRadius <= 0) return scales;
+    const xValues = flat.map((d) => Number(xAcc(d)));
+    const yValues = flat.map((d) => Number(yAcc(d)));
+    const paddedX = scales.x?.domain
+      ? undefined
+      : resolveRadiusPaddedDomain(xValues, maxDotRadius, estimatedInnerWidth);
+    const paddedY = scales.y?.domain
+      ? undefined
+      : resolveRadiusPaddedDomain(yValues, maxDotRadius, estimatedInnerHeight);
+    if (!paddedX && !paddedY) return scales;
+    return {
+      ...scales,
+      x: paddedX ? { ...scales.x, domain: paddedX } : scales.x,
+      y: paddedY ? { ...scales.y, domain: paddedY } : scales.y,
+    };
+  });
+</script>
+
+<BasePlotLayout
+  {width}
+  {height}
+  {styles}
+  data={flat}
+  getX={xAcc}
+  getY={(d) => Number(yAcc(d))}
+  {hover}
+  scales={resolvedScales}
+  {margins}
+  markers={[...scatterMarkers, ...markers]}
+  seriesData={resolvedSeries}
+  {scopedGroups}
+>
+  {#if showVals}
+    <ValueLabels data={flat} getX={xAcc} getY={(d) => Number(yAcc(d))} {fmtVal} values={styles.values} defaultColor={cfg.axis.color} />
+  {/if}
+</BasePlotLayout>

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

@@ -1,21 +1,10 @@
-import { BarX, BarY } from 'svelteplot';
-import type { Series } from '../../types/plots/data/common';
-import type { BarSegmentStyle } from '../../types/plots/segments/common';
-import type { VisualGroup } from '../../types/plots/segments/config';
-import type { BarLayout } from './layout.svelte';
+import type { BasePlotProps } from '../../types/plots/props';
+import type { AxisBasedScalesConfig } from '../../types/layout/scales';
+import type { ScatterDataProps } from '../../types/plots/data/scatter';
+import type { BasePlotStylesConfig } from '../../types/layout/styles';
+import type { AxisBasedMarkersConfig } from '../../types/markers/common';
 declare function $$render<TData extends Record<string, unknown>>(): {
-    props: {
-        group: VisualGroup<Series<TData>, BarSegmentStyle>;
-        seriesIndex: number;
-        barLayout: BarLayout<TData>;
-        isHorizontal: boolean;
-        BarMark: typeof BarX | typeof BarY;
-        defaultColor: string;
-        disabledFill?: {
-            fill?: string;
-            fillOpacity?: number;
-        };
-    };
+    props: BasePlotProps<ScatterDataProps<TData>, TData, BasePlotStylesConfig, import("../..").DotStyle, AxisBasedMarkersConfig, AxisBasedScalesConfig<TData>>;
     exports: {};
     bindings: "";
     slots: {};
@@ -35,6 +24,6 @@ interface $$IsomorphicComponent {
     <TData extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
-declare const BarSegments: $$IsomorphicComponent;
-type BarSegments<TData extends Record<string, unknown>> = InstanceType<typeof BarSegments<TData>>;
-export default BarSegments;
+declare const Plot: $$IsomorphicComponent;
+type Plot<TData extends Record<string, unknown>> = InstanceType<typeof Plot<TData>>;
+export default Plot;

package/dist/plots/scatter/ValueLabels.svelte

@@ -0,0 +1,106 @@
+<script lang="ts" generics="TData extends Record<string, unknown>">
+  import { Text, usePlot } from 'svelteplot';
+  import { SvelteMap } from 'svelte/reactivity';
+  import { resolveEdgeAwareAnchor, estimateTextWidth } from '../../utils/edgeAwareAnchor';
+  import type { AxisValue } from '../../types/layout/scales';
+  import type { ValuesStyle } from '../../types/layout/styles';
+
+  /**
+   * Renders every point's value label in one mark — scatter has no
+   * per-series endpoint to single out (unlike line), so this covers the
+   * whole flat dataset at once, mirroring heatmap's own `ValueLabels`.
+   * Labels the Y value, matching the "Y is the value axis" convention every
+   * other plot kind uses. Placement is edge-aware: a label whose default
+   * anchor/offset would push it past the plot's own content box flips to
+   * the opposite side instead of clipping. Deliberately read-only against
+   * `usePlot()`'s live scale — doesn't register into svelteplot's shared
+   * margin-auto-sizing context, which can spike CPU/memory into
+   * unresponsiveness when many `<Plot>` instances mount/unmount together
+   * (e.g. switching from a multi-story docs page to a single story).
+   */
+  let {
+    data,
+    getX,
+    getY,
+    fmtVal,
+    values,
+    defaultColor,
+  }: {
+    data: TData[];
+    getX: (d: TData) => AxisValue;
+    getY: (d: TData) => AxisValue;
+    fmtVal: (value: number, seriesName: string) => string;
+    values: ValuesStyle | undefined;
+    defaultColor: string;
+  } = $props();
+
+  const font = $derived(values?.fontStyle);
+  const preferredTextAnchor = $derived(
+    font?.textAnchor === 'outside' || font?.textAnchor === undefined ? 'start' : font.textAnchor,
+  );
+  const preferredLineAnchor = $derived(font?.lineAnchor ?? 'middle');
+  const gapX = $derived(Math.abs(font?.dx ?? 8));
+  const gapY = $derived(Math.abs(font?.dy ?? 0));
+  const fontSize = $derived(typeof font?.fontSize === 'number' ? font.fontSize : 11);
+
+  const plot = usePlot();
+
+  function textOf(d: TData): string {
+    return fmtVal(Number(getY(d)), '');
+  }
+
+  /** One placement per row, keyed by row reference — avoids recomputing the same scale/edge lookup for each of the four accessor channels below. */
+  const placements = $derived.by(() => {
+    const map = new SvelteMap<TData, ReturnType<typeof resolveEdgeAwareAnchor>>();
+    const xFn = plot.scales.x?.fn;
+    const yFn = plot.scales.y?.fn;
+    if (!xFn || !yFn) return map;
+    for (const d of data) {
+      const px = Number(xFn(getX(d) as never));
+      const py = Number(yFn(getY(d) as never));
+      const text = textOf(d);
+      map.set(
+        d,
+        resolveEdgeAwareAnchor({
+          px,
+          py,
+          width: plot.plotWidth,
+          height: plot.plotHeight,
+          textAnchor: preferredTextAnchor,
+          lineAnchor: preferredLineAnchor,
+          gapX,
+          gapY,
+          // Rough average glyph width — these labels are short numeric/formatted strings, not measured DOM text.
+          extent: { width: estimateTextWidth(text, fontSize), height: fontSize * 1.2 },
+        }),
+      );
+    }
+    return map;
+  });
+</script>
+
+<Text
+  {data}
+  x={getX}
+  y={getY}
+  text={(d: TData) => textOf(d)}
+  fill={font?.fill ?? defaultColor}
+  {fontSize}
+  fontWeight={font?.fontWeight ?? 500}
+  fontStyle={font?.fontStyle}
+  textAnchor={(d: TData) => placements.get(d)?.textAnchor ?? preferredTextAnchor}
+  lineAnchor={
+    // svelteplot's own `lineAnchor` accessor type isn't parameterized over the mark's row type like its siblings are.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (d: any) => placements.get(d)?.lineAnchor ?? preferredLineAnchor
+  }
+  dx={(d: TData) => placements.get(d)?.dx ?? gapX}
+  dy={(d: TData) => placements.get(d)?.dy ?? gapY}
+  lineHeight={font?.lineHeight}
+  rotate={font?.rotate}
+  stroke={font?.stroke}
+  strokeWidth={font?.strokeWidth}
+  paintOrder={font?.paintOrder}
+  class={font?.class}
+  textClass={font?.textClass}
+/>

package/dist/{layout/plot/GridLayout.svelte.d.ts → plots/scatter/ValueLabels.svelte.d.ts}

@@ -1,7 +1,13 @@
-import type { AxisBasedScalesConfig } from '../../types/plots/props';
+import type { AxisValue } from '../../types/layout/scales';
+import type { ValuesStyle } from '../../types/layout/styles';
 declare function $$render<TData extends Record<string, unknown>>(): {
     props: {
-        scales?: AxisBasedScalesConfig<TData>;
+        data: TData[];
+        getX: (d: TData) => AxisValue;
+        getY: (d: TData) => AxisValue;
+        fmtVal: (value: number, seriesName: string) => string;
+        values: ValuesStyle | undefined;
+        defaultColor: string;
     };
     exports: {};
     bindings: "";
@@ -22,6 +28,6 @@ interface $$IsomorphicComponent {
     <TData extends Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
-declare const GridLayout: $$IsomorphicComponent;
-type GridLayout<TData extends Record<string, unknown>> = InstanceType<typeof GridLayout<TData>>;
-export default GridLayout;
+declare const ValueLabels: $$IsomorphicComponent;
+type ValueLabels<TData extends Record<string, unknown>> = InstanceType<typeof ValueLabels<TData>>;
+export default ValueLabels;

package/dist/plots/scatter/buildScatterMarkers.d.ts

@@ -0,0 +1,11 @@
+import type { Series, Accessor } from '../../types/plots/data/common';
+import type { ScatterSegmentStyle } from '../../types/plots/segments/common';
+import type { VisualGroup } from '../../types/plots/segments/config';
+import type { DotStyle } from '../../types/plots/styling';
+import type { DotMarkerConfig } from '../../types/markers/common';
+/** Every `'dot'` marker for one ScatterPlot render: one per visual segment. */
+export declare function buildScatterMarkers<TData extends Record<string, unknown>>(args: {
+    groupedSeries: VisualGroup<Series<TData>, ScatterSegmentStyle>[];
+    r?: Accessor<TData, number> | number;
+    disabledDotsFor: (seriesName: string) => DotStyle | undefined;
+}): DotMarkerConfig[];

package/dist/plots/scatter/buildScatterMarkers.js

@@ -0,0 +1,37 @@
+import { resolveAccessor } from '../utils/accessors';
+import { paletteColor } from '../../utils/color';
+import { getConfiguration } from '../../configuration/config.svelte';
+/** Every `'dot'` marker for one ScatterPlot render: one per visual segment. */
+export function buildScatterMarkers(args) {
+    const { groupedSeries, r, disabledDotsFor } = args;
+    const cfg = getConfiguration();
+    const rFn = r === undefined || typeof r === 'number' ? r : resolveAccessor(r);
+    const markers = [];
+    groupedSeries.forEach((group, seriesIndex) => {
+        const defaultColor = paletteColor(seriesIndex, cfg.palette);
+        const disabledDots = disabledDotsFor(group.series.name);
+        const xFn = resolveAccessor(group.series.x);
+        const yFn = resolveAccessor(group.series.y);
+        for (const seg of group.visualSegments) {
+            const dotStyle = seg.style;
+            markers.push({
+                type: 'dot',
+                data: seg.data,
+                x: xFn,
+                y: yFn,
+                r: rFn,
+                style: {
+                    dotRadius: disabledDots?.dotRadius ?? dotStyle.dotRadius ?? cfg.scatter.dotRadius,
+                    dotFill: disabledDots?.dotFill ?? dotStyle.dotFill ?? defaultColor,
+                    dotSymbol: disabledDots?.dotSymbol ?? dotStyle.dotSymbol,
+                    dotStroke: disabledDots?.dotStroke ?? dotStyle.dotStroke,
+                    dotStrokeWidth: disabledDots?.dotStrokeWidth ?? dotStyle.dotStrokeWidth,
+                    dotFillOpacity: disabledDots?.dotFillOpacity ?? dotStyle.dotFillOpacity,
+                    dotStrokeOpacity: disabledDots?.dotStrokeOpacity ?? dotStyle.dotStrokeOpacity,
+                    dotStrokeDasharray: disabledDots?.dotStrokeDasharray ?? dotStyle.dotStrokeDasharray,
+                },
+            });
+        }
+    });
+    return markers;
+}

package/dist/plots/scatter/resolveRadiusPaddedDomain.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extends a `[min, max]` data domain so the largest rendered dot radius
+ * doesn't get clipped by the plot's own frame — svelteplot's own `'auto'`
+ * margin only measures axis chrome (tick labels), never mark geometry, so a
+ * point sitting at the domain edge with a non-trivial radius otherwise
+ * overflows past the frame. `innerSizePx` is an estimate (the real pixel
+ * range isn't known until the scale itself is built from this domain), so
+ * this errs generous rather than exact.
+ */
+export declare function resolveRadiusPaddedDomain(values: number[], maxRadiusPx: number, innerSizePx: number): [number, number] | undefined;

package/dist/plots/scatter/resolveRadiusPaddedDomain.js

@@ -0,0 +1,23 @@
+/**
+ * Extends a `[min, max]` data domain so the largest rendered dot radius
+ * doesn't get clipped by the plot's own frame — svelteplot's own `'auto'`
+ * margin only measures axis chrome (tick labels), never mark geometry, so a
+ * point sitting at the domain edge with a non-trivial radius otherwise
+ * overflows past the frame. `innerSizePx` is an estimate (the real pixel
+ * range isn't known until the scale itself is built from this domain), so
+ * this errs generous rather than exact.
+ */
+export function resolveRadiusPaddedDomain(values, maxRadiusPx, innerSizePx) {
+    const finite = values.filter((v) => Number.isFinite(v));
+    if (finite.length === 0 || innerSizePx <= 0 || maxRadiusPx <= 0)
+        return undefined;
+    const min = Math.min(...finite);
+    const max = Math.max(...finite);
+    if (min === max) {
+        // A degenerate single-value domain has no data-per-pixel ratio to pad by — fall back to a fixed unit either side.
+        return [min - 1, max + 1];
+    }
+    const dataPerPixel = (max - min) / innerSizePx;
+    const pad = maxRadiusPx * dataPerPixel;
+    return [min - pad, max + pad];
+}

package/dist/plots/utils/declutter.d.ts

@@ -45,55 +45,73 @@ export type Declutter1DResult<T> = {
  * that side, so a plain 50/50 blend would still ask the up-pass and
  * down-pass to pull the block symmetrically toward *both* edges before
  * `fitRunsWithinBounds` shifts/shrinks it back — the up-pass reaching for
- * room that was never really there. That round trip is exactly what makes
- * individual members travel far past their neighbours' original positions
- * (`laneAssignment`'s doc comment calls this out as the thing that forces an
- * unsafe, overlapping travel span), so a run near an edge leans toward
- * whichever pass already grows away from it instead — the block still
- * expands to clear `minGap` everywhere, just mostly in the one direction
- * that was actually available, the way a person sliding books apart on a
- * shelf pinned against one wall would.
+ * room that was never really there, needlessly widening how far members end
+ * up travelling from their original positions (`laneAssignment`'s own lane
+ * count grows with exactly that travel distance — see its doc comment) — so
+ * a run near an edge leans toward whichever pass already grows away from it
+ * instead — the block still expands to clear `minGap` everywhere, just
+ * mostly in the one direction that was actually available, the way a person
+ * sliding books apart on a shelf pinned against one wall would.
  */
 export declare function declutter1D<T extends {
     pos: number;
 }>(items: T[], minGap: number, bounds?: readonly [number, number]): Declutter1DResult<T>;
 /**
  * Groups `declutter1D`'s own `connected` flags into runs (maximal stretches
- * of consecutive connected pairs), then assigns each run member a lane by
- * *mirrored* position — the run's top and bottom member share lane 0, the
- * next-in-from-top and next-in-from-bottom share lane 1, and so on toward
- * the run's centre (an odd-sized run's exact middle member gets the
- * innermost lane alone) — but only after checking that a proposed pair's
- * *travel spans* (`[min(original, final), max(original, final)]`, the pixel
- * range a leader line's vertical segment actually sweeps through) don't
- * overlap. A pair that would collide is split into two lanes of its own
- * instead of one shared one, so correctness never depends on the pairing
- * being right — only on this check.
+ * of consecutive connected pairs), then gives every run member its own,
+ * unique lane — no two members ever share one, deliberately (see below) —
+ * ordered so that a leader line drawn through lane `rank` never crosses, or
+ * even draws visually flush against, one drawn through any other lane of
+ * the same run.
  *
- * Mirrored position is still the *first* thing tried, not span-overlap
- * colouring picking lanes on its own, because minimizing lane count isn't
- * actually the goal here — a run of `n` safely-non-overlapping members could
- * often be greedily packed into far fewer than `ceil(n / 2)` lanes, but
- * doing that defeats the point: it's what visually fans a pileup's leader
- * lines apart in the first place. Mirrored pairing keeps that fan-out
- * exactly where it's safe (the common case for `declutter1D`'s own output),
- * and only degrades — never breaks — where it isn't.
+ * Every member's leader line is the same three-segment elbow: a horizontal
+ * stub from the data point out to its lane, a vertical run up/down that
+ * lane to the label's height, then a final horizontal run in to the shared
+ * label column. Two such elbows, `i` (in the tighter of the two lanes) and
+ * `j` (further out), are safe from crossing *specifically* when neither of
+ * these can happen:
+ * - `j`'s own stub (at `j`'s original height) reaches out past `i`'s lane
+ *   while `i`'s vertical run passes through that height — `j`'s stub would
+ *   cut across `i`'s vertical segment.
+ * - `i`'s final run (at `i`'s label height) reaches past `i`'s own lane out
+ *   to the shared column, and in doing so crosses `j`'s lane while `j`'s
+ *   vertical run passes through *that* height — `i`'s own final segment
+ *   would cut across `j`'s vertical segment.
  *
- * A run whose members still end up with genuinely overlapping travel spans
- * (heavy, edge-adjacent compression) has no lane assignment that's both
- * crossing-free *and* touch-free under this shared-`px`/shared-`labelX`
- * elbow geometry — sharing draws two segments on top of each other, splitting
- * draws an actual crossing. `declutter1D`'s bounds-aware margin bias (see its
- * own doc comment) exists specifically to keep that from happening in the
- * first place, by keeping a run's displacement mostly one-directional when
- * it sits close to an edge, rather than papering over it here.
+ * Whether `i` can safely take the tighter lane depends on both members'
+ * *actual* pixel geometry — not simply on which one moved further — so each
+ * pair is checked directly per {@link saferNearer} rather than inferred from
+ * a single sort key. A pair with a clean, provable answer either way (the
+ * overwhelmingly common case for `declutter1D`'s own output) is ordered by
+ * that answer; a pair with no clean answer (both directions equally
+ * "unsafe," or, symmetrically, both fine) falls back to the same *travel
+ * distance* heuristic used before this per-pair check existed — furthest
+ * `|final - original|` first — which is what decides ties and keeps the
+ * "furthest traveller gets the tightest lane, so it starts bending
+ * immediately rather than reaching across everyone else's leader lines
+ * first" intent for every pair the geometry itself doesn't already settle.
+ *
+ * No sharing, ever, is the other half of this: two members can only have
+ * non-overlapping travel spans (and so pass the old, now-removed,
+ * share-a-lane check) by sitting far apart along the axis — but "far apart"
+ * is exactly the case with the most room to spare, so it never needed the
+ * lane it would save by sharing, while any pair close enough to actually be
+ * short on room has spans close enough together that sharing draws their
+ * two leader lines only a couple pixels apart — visually indistinguishable
+ * from one continuous line touching the next label down. A run of `n`
+ * members uses exactly `n` lanes; letting the lane count grow is the price
+ * of a fan that never has two leader lines touching *or* crossing, and
+ * `ValueLabels`' own auto-margin measurement (see its doc comment) already
+ * grows `margins.right` to fit however many lanes that turns out to be, so
+ * nothing has to be guessed up front.
  *
  * `rank` is the lane index (0-indexed) to drive a leader line's routing:
  * `rank` 0 bends right off the data point (a short first stub); higher
  * ranks travel further before bending (right up to the shared label
- * column). `lanesUsed` is the run's own total lane count (shared by every
- * member); `runSize` is the run's member count, for callers that just need
- * to know whether a given member belongs to a real run at all.
+ * column). `lanesUsed` is the run's own total lane count — always equal to
+ * `runSize` — shared by every member; `runSize` is the run's member count,
+ * for callers that just need to know whether a given member belongs to a
+ * real run at all.
  */
 export declare function laneAssignment(originals: number[], finals: number[], connected: boolean[]): {
     rank: number;