@fundar/data-chart-telling 0.0.24 → 0.0.25

package/dist/configuration/config.svelte.js

@@ -70,7 +70,17 @@ export const DEFAULT_CONFIG = {
     margins: { top: 'auto', right: 'auto', bottom: 'auto', left: 'auto' },
     palette: ['#4f46e5', '#e6580d', '#16a34a', '#dc2626', '#0891b2', '#9333ea', '#ca8a04', '#db2777'],
     continuous: { min: '#e0e7ff', max: '#4f46e5', labelColor: '#111827' },
-    line: { strokeWidth: 3, dotRadius: 4 },
+    line: {
+        strokeWidth: 3,
+        dotRadius: 4,
+        valueLabels: {
+            elbowGap: 10,
+            laneStep: 7,
+            labelGap: 6,
+            connectorColor: '#94a3b8',
+            connectorWidth: 0.5,
+        },
+    },
     timeline: { axisColor: 'currentColor', activeColor: '#e6580d', thickness: 60 },
     hover: {
         rule: { stroke: '#e6580d', strokeOpacity: 0.35, strokeWidth: 1.5, strokeDasharray: '4 4' },

package/dist/configuration/themes/index.d.ts

@@ -84,6 +84,13 @@ export declare const THEMES: {
         line?: {
             strokeWidth?: number | undefined;
             dotRadius?: number | undefined;
+            valueLabels?: {
+                elbowGap?: number | undefined;
+                laneStep?: number | undefined;
+                labelGap?: number | undefined;
+                connectorColor?: string | undefined;
+                connectorWidth?: number | undefined;
+            } | undefined;
         } | undefined;
         timeline?: {
             axisColor?: string | undefined;
@@ -207,6 +214,13 @@ export declare const THEMES: {
         line?: {
             strokeWidth?: number | undefined;
             dotRadius?: number | undefined;
+            valueLabels?: {
+                elbowGap?: number | undefined;
+                laneStep?: number | undefined;
+                labelGap?: number | undefined;
+                connectorColor?: string | undefined;
+                connectorWidth?: number | undefined;
+            } | undefined;
         } | undefined;
         timeline?: {
             axisColor?: string | undefined;
@@ -330,6 +344,13 @@ export declare const THEMES: {
         line?: {
             strokeWidth?: number | undefined;
             dotRadius?: number | undefined;
+            valueLabels?: {
+                elbowGap?: number | undefined;
+                laneStep?: number | undefined;
+                labelGap?: number | undefined;
+                connectorColor?: string | undefined;
+                connectorWidth?: number | undefined;
+            } | undefined;
         } | undefined;
         timeline?: {
             axisColor?: string | undefined;
@@ -453,6 +474,13 @@ export declare const THEMES: {
         line?: {
             strokeWidth?: number | undefined;
             dotRadius?: number | undefined;
+            valueLabels?: {
+                elbowGap?: number | undefined;
+                laneStep?: number | undefined;
+                labelGap?: number | undefined;
+                connectorColor?: string | undefined;
+                connectorWidth?: number | undefined;
+            } | undefined;
         } | undefined;
         timeline?: {
             axisColor?: string | undefined;

package/dist/plots/line/ValueLabels.svelte

@@ -1,33 +1,30 @@
 <script lang="ts" generics="TData extends Record<string, unknown>">
+  import { getContext } from 'svelte';
+  import { get } from 'svelte/store';
   import { SvelteMap } from 'svelte/reactivity';
+  import type { Writable } from 'svelte/store';
   import { Text, usePlot } from 'svelteplot';
   import { resolveAccessor } from '../utils/accessors';
   import { getConfiguration } from '../../configuration/config.svelte';
   import { paletteColor } from '../../utils/color';
-  import { declutter1D, mirrorRanks } from '../utils/declutter';
+  import { declutter1D, laneAssignment } from '../utils/declutter';
   import type { Series } from '../../types/plots/data/common';
   import type { ValuesStyle } from '../../types/plots/styles/common';
   import type { ValueAnchor } from '../../types/plots/constants';
 
-  // Elbow-routed leader line geometry (pixels) — a run's top/bottom pair
-  // share the shortest lane, its next-in pair the next lane out, and so on
-  // (see `mirrorRanks`'s doc comment for why sharing a lane is safe). Each
-  // lane is `LANE_STEP` further out than the last; `ELBOW_GAP` is the
-  // shortest lane (rank 0, right off the data point); `LABEL_GAP` is the
-  // small clearance between the outermost lane and the label text it feeds
-  // into.
-  const ELBOW_GAP = 10;
-  const LANE_STEP = 7;
-  const LABEL_GAP = 6;
-
-  // Default connector look — deliberately *not* each series' own colour or
-  // stroke weight: a leader line only needs to be traceable back to its
-  // label, and matching the data line's own styling reads as if it were
-  // more data, which is confusing right where several lines already
-  // converge. Neutral, thin, and solid keeps it legible as a leader — the
-  // colour and weight are still fully overridable via `values.strokeStyle`.
-  const DEFAULT_CONNECTOR_COLOR = '#94a3b8';
-  const DEFAULT_CONNECTOR_WIDTH = 0.5;
+  // svelteplot's own type for this context isn't part of its public export
+  // surface, but the context itself (keyed by this fixed string, set by its
+  // `<Plot>`) is — every axis mark already reads/writes it this way to
+  // auto-size margins around what it actually renders. Mirroring that here
+  // is what lets `margins.right: 'auto'` (the default) grow to fit these
+  // labels on its own, instead of the caller having to guess a fixed
+  // `margins.right` up front.
+  type AutoMarginStores = {
+    autoMarginTop: Writable<Map<string, number>>;
+    autoMarginLeft: Writable<Map<string, number>>;
+    autoMarginRight: Writable<Map<string, number>>;
+    autoMarginBottom: Writable<Map<string, number>>;
+  };
 
   /**
    * End-point value labels for `LinePlot` — one label per series at its last
@@ -46,6 +43,24 @@
   } = $props();
 
   const cfg = $derived(getConfiguration());
+
+  // Elbow-routed leader line geometry (pixels), configurable project-wide
+  // via `setConfiguration({ line: { valueLabels: {...} } })` — each lane a
+  // run's members get spread across (see `laneAssignment`'s doc comment for
+  // how lanes are picked without crossing) is `laneStep` further out than
+  // the last; `elbowGap` is the shortest lane (rank 0, right off the data
+  // point); `labelGap` is the small clearance between the outermost lane and
+  // the label text it feeds into. `connectorColor`/`connectorWidth` are the
+  // leader line's own default look — deliberately *not* each series' own
+  // colour or stroke weight (matching the data line reads as more data, not
+  // as a leader, right where several lines are already converging) — both
+  // still overridable per-plot via `values.strokeStyle`.
+  const elbowGap = $derived(cfg.line.valueLabels.elbowGap);
+  const laneStep = $derived(cfg.line.valueLabels.laneStep);
+  const labelGap = $derived(cfg.line.valueLabels.labelGap);
+  const defaultConnectorColor = $derived(cfg.line.valueLabels.connectorColor);
+  const defaultConnectorWidth = $derived(cfg.line.valueLabels.connectorWidth);
+
   const font = $derived(values?.fontStyle);
   const connector = $derived(values?.strokeStyle);
   const fmtVal = $derived(values?.format ?? ((v: number, name: string) => `${name} - ${v}`));
@@ -64,6 +79,53 @@
 
   const plot = usePlot();
 
+  // ── Auto margin ──────────────────────────────────────────────────────────
+  // Registers how far these labels (+ their leader lines) actually extend
+  // past the plot's own content box, on whichever side they grow toward, so
+  // `margins.{left,right}: 'auto'` (the default) sizes itself to fit them —
+  // the same mechanism svelteplot's own axis labels use, rather than a
+  // fixed margin the caller has to guess and hard-code up front.
+  const autoMargins = getContext<AutoMarginStores | undefined>('svelteplot/autoMargins');
+  const marginId = `line-value-labels-${Math.random().toString(36).slice(2)}`;
+  let groupEl: SVGGElement | undefined = $state();
+
+  $effect(() => {
+    // Depend on whatever actually changes the rendered label layout —
+    // getBBox() below is a plain DOM read, not itself tracked, so without
+    // this the effect would only ever measure once.
+    void lastPoints;
+    void values;
+    const el = groupEl;
+    if (!autoMargins || !el) return;
+    const xRange = plot.scales.x?.fn?.range?.()?.map(Number);
+    if (!xRange) return;
+    const plotLeft = Math.min(xRange[0], xRange[1]);
+    const plotRight = Math.max(xRange[0], xRange[1]);
+    // getBBox() is in the <svg>'s own user-space coordinates — the same
+    // pixel space `plot.scales.*.fn()` already produces everywhere else in
+    // this file, so no viewport/DOM conversion is needed here.
+    let box: { x: number; width: number };
+    try {
+      box = el.getBBox();
+    } catch {
+      return;
+    }
+    const overflowRight = Math.ceil(Math.max(0, box.x + box.width - plotRight));
+    const overflowLeft = Math.ceil(Math.max(0, plotLeft - box.x));
+    const rightMargins = get(autoMargins.autoMarginRight);
+    const leftMargins = get(autoMargins.autoMarginLeft);
+    if (rightMargins.get(marginId) !== overflowRight) rightMargins.set(marginId, overflowRight);
+    if (leftMargins.get(marginId) !== overflowLeft) leftMargins.set(marginId, overflowLeft);
+  });
+
+  $effect(() => {
+    return () => {
+      if (!autoMargins) return;
+      get(autoMargins.autoMarginRight).delete(marginId);
+      get(autoMargins.autoMarginLeft).delete(marginId);
+    };
+  });
+
   /**
    * Pixel-space collision fix-up for end-point labels: resolves each label's
    * true pixel Y through the plot's own live y-scale, then runs the shared
@@ -74,19 +136,18 @@
    * which would extend the y-scale's own domain and provoke an infinite
    * autoscale ↔ declutter feedback loop.
    *
-   * `inGroup`/`rank`/`depth` come from `mirrorRanks`, fed by `declutter1D`'s
-   * own `connected` record rather than re-inferred from positions — see
-   * both functions' doc comments for why that's the only reliable source:
-   * position-based heuristics either miss a series that only had to move
-   * because a neighbour got pushed into it, or wrongly bridge two unrelated
-   * clusters that each happened to need decluttering on their own. The
-   * elbow connector below turns `rank` into a lane index — mirrored
-   * top/bottom pairs share a lane, so a run only ever needs `ceil(depth / 2)`
-   * distinct ones. A series with nothing nearby is absent from the map, and
-   * its label renders with no extra offset.
+   * `inGroup`/`rank`/`lanesUsed` come from `laneAssignment`, fed by
+   * `declutter1D`'s own `connected` record rather than re-inferred from
+   * positions — see both functions' doc comments for why that's the only
+   * reliable source: position-based heuristics either miss a series that
+   * only had to move because a neighbour got pushed into it, or wrongly
+   * bridge two unrelated clusters that each happened to need decluttering
+   * on their own. The elbow connector below turns `rank` into a lane index.
+   * A series with nothing nearby is absent from the map, and its label
+   * renders with no extra offset.
    */
   const declutteredOffsets = $derived.by(() => {
-    const map = new SvelteMap<string, { extraDy: number; inGroup: boolean; rank: number; depth: number }>();
+    const map = new SvelteMap<string, { extraDy: number; inGroup: boolean; rank: number; lanesUsed: number }>();
     if (lastPoints.length < 2) return map;
     const yScale = plot.scales.y?.fn;
     if (!yScale) return map;
@@ -97,22 +158,28 @@
       pos: Number(yScale(Number(resolveAccessor(s.y)(lastRow)))),
     }));
     const sorted = [...items].sort((a, b) => a.pos - b.pos);
-    const { positions: spread, connected } = declutter1D(items, minGap);
+    const range = yScale.range?.().map(Number);
+    const bounds: [number, number] | undefined = range
+      ? [Math.min(range[0], range[1]), Math.max(range[0], range[1])]
+      : undefined;
+    const { positions: spread, connected } = declutter1D(items, minGap, bounds);
     const spreadByName = new Map(spread.map((d) => [d.name, d.pos]));
-    const ranks = mirrorRanks(connected);
+    const originals = sorted.map((item) => item.pos);
+    const finals = sorted.map((item) => spreadByName.get(item.name) ?? item.pos);
+    const ranks = laneAssignment(originals, finals, connected);
     sorted.forEach((item, i) => {
-      const final = spreadByName.get(item.name) ?? item.pos;
       map.set(item.name, {
-        extraDy: final - item.pos,
-        inGroup: ranks[i].depth > 1,
+        extraDy: finals[i] - originals[i],
+        inGroup: ranks[i].runSize > 1,
         rank: ranks[i].rank,
-        depth: ranks[i].depth,
+        lanesUsed: ranks[i].lanesUsed,
       });
     });
     return map;
   });
 </script>
 
+<g bind:this={groupEl}>
 {#each lastPoints as { series: s, lastRow, seriesIndex } (s.name)}
   {@const xFn = resolveAccessor(s.x)}
   {@const yFn = resolveAccessor(s.y)}
@@ -121,20 +188,20 @@
   {@const extraDy = offset?.inGroup ? offset.extraDy : 0}
   {@const baseDx = font?.dx ?? defaultDx}
   {@const dir = Math.sign(baseDx) || 1}
-  {@const numLanes = offset?.inGroup ? Math.ceil(offset.depth / 2) : 0}
+  {@const numLanes = offset?.inGroup ? offset.lanesUsed : 0}
   {@const labelDx = offset?.inGroup
-    ? dir * (ELBOW_GAP + (numLanes - 1) * LANE_STEP + LABEL_GAP)
+    ? dir * (elbowGap + (numLanes - 1) * laneStep + labelGap)
     : baseDx}
   {#if offset?.inGroup && plot.scales.x?.fn && plot.scales.y?.fn}
     {@const px = Number(plot.scales.x.fn(xFn(lastRow)))}
     {@const py = Number(plot.scales.y.fn(Number(yFn(lastRow))))}
-    {@const laneX = px + dir * (ELBOW_GAP + offset.rank * LANE_STEP)}
+    {@const laneX = px + dir * (elbowGap + offset.rank * laneStep)}
     {@const targetY = py + extraDy}
     <path
       d={`M ${px} ${py} H ${laneX} V ${targetY} H ${px + labelDx}`}
       fill="none"
-      stroke={connector?.stroke ?? DEFAULT_CONNECTOR_COLOR}
-      stroke-width={connector?.strokeWidth ?? DEFAULT_CONNECTOR_WIDTH}
+      stroke={connector?.stroke ?? defaultConnectorColor}
+      stroke-width={connector?.strokeWidth ?? defaultConnectorWidth}
       stroke-opacity={connector?.strokeOpacity ?? 1}
       stroke-dasharray={connector?.strokeDasharray}
       stroke-linecap={connector?.strokeLinecap ?? 'square'}
@@ -163,3 +230,4 @@
     paintOrder={font?.paintOrder}
   />
 {/each}
+</g>

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

@@ -26,46 +26,77 @@ export type Declutter1DResult<T> = {
  * already >= minGap and the average of two such gaps is too.
  *
  * Also records, per adjacent pair, whether either pass actually had to push
- * — the ground truth for "did these two really interact," which `mirrorRanks`
- * needs and can't reliably reconstruct from positions alone after the fact
- * (see its own doc comment).
+ * — the ground truth for "did these two really interact," which
+ * `laneAssignment` needs and can't reliably reconstruct from positions alone
+ * after the fact (see its own doc comment).
+ *
+ * `bounds`, if given, keeps every *run* (a maximal stretch of connected
+ * items — lone, unconnected items are left at their true position
+ * regardless) inside `[lo, hi]`: nothing pushed apart by this function is
+ * ever allowed to end up off the edge of whatever pixel range the caller
+ * considers in-bounds (typically the plot's own content box). A run that
+ * already fits is only shifted, never resized; a run too big to fit even
+ * at its natural spacing is shrunk just enough to fit, uniformly, so it's
+ * still evenly spaced — just tighter than `minGap` calls for. See
+ * `fitRunsWithinBounds` for the actual shift/shrink math.
+ *
+ * `bounds` also biases *which* pass a run's average leans on, via
+ * {@link runBiasWeights}: a run sitting close to one edge has little slack on
+ * 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.
  */
 export declare function declutter1D<T extends {
     pos: number;
-}>(items: T[], minGap: number): Declutter1DResult<T>;
+}>(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 within it: 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). `depth` is the run's own size, the same for every
- * member; the number of *distinct* lanes it actually needs is
- * `ceil(depth / 2)`.
+ * *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.
+ *
+ * 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.
  *
- * Deliberately doesn't re-derive connectivity from before/after positions —
- * an early version tried that (some mix of "both moved" and "final gap is
- * near minGap") and it's unreliable both ways: a real one-sided interaction
- * (an item that only moved because its neighbour got pushed into it) can
- * settle with more slack than minGap, so a gap-threshold check misses it;
- * and "both moved" over-connects, since two unrelated, far-apart clusters
- * that each independently needed to declutter still each have moved members
- * sitting next to each other in sort order, which a moved-only check can't
- * tell apart from a real interaction. `declutter1D`'s own `connected` array
- * has neither problem, because it's not inferred — it's the actual record
- * of which pushes happened.
+ * 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.
  *
- * Meant to drive a leader line's lane: `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, for a run's own centre member).
- * Two members sharing a lane never collide: by how `declutter1D` centers
- * its result, a run's top half only ever ends up at or above its original
- * spot and its bottom half only ever at or below, so paired members bend
- * away from each other — same lane, opposite direction, no shared space.
- * This also roughly halves the lane depth (and so the horizontal room) a
- * run needs, versus giving every member its own lane.
+ * `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.
  */
-export declare function mirrorRanks(connected: boolean[]): {
+export declare function laneAssignment(originals: number[], finals: number[], connected: boolean[]): {
     rank: number;
-    depth: number;
+    lanesUsed: number;
+    runSize: number;
 }[];

package/dist/plots/utils/declutter.js

@@ -15,11 +15,35 @@
  * already >= minGap and the average of two such gaps is too.
  *
  * Also records, per adjacent pair, whether either pass actually had to push
- * — the ground truth for "did these two really interact," which `mirrorRanks`
- * needs and can't reliably reconstruct from positions alone after the fact
- * (see its own doc comment).
+ * — the ground truth for "did these two really interact," which
+ * `laneAssignment` needs and can't reliably reconstruct from positions alone
+ * after the fact (see its own doc comment).
+ *
+ * `bounds`, if given, keeps every *run* (a maximal stretch of connected
+ * items — lone, unconnected items are left at their true position
+ * regardless) inside `[lo, hi]`: nothing pushed apart by this function is
+ * ever allowed to end up off the edge of whatever pixel range the caller
+ * considers in-bounds (typically the plot's own content box). A run that
+ * already fits is only shifted, never resized; a run too big to fit even
+ * at its natural spacing is shrunk just enough to fit, uniformly, so it's
+ * still evenly spaced — just tighter than `minGap` calls for. See
+ * `fitRunsWithinBounds` for the actual shift/shrink math.
+ *
+ * `bounds` also biases *which* pass a run's average leans on, via
+ * {@link runBiasWeights}: a run sitting close to one edge has little slack on
+ * 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.
  */
-export function declutter1D(items, minGap) {
+export function declutter1D(items, minGap, bounds) {
     const sorted = [...items].sort((a, b) => a.pos - b.pos);
     const n = sorted.length;
     const connected = new Array(Math.max(0, n - 1)).fill(false);
@@ -39,54 +63,157 @@ export function declutter1D(items, minGap) {
             connected[i] = true;
         }
     }
-    const positions = sorted.map((d, i) => ({ ...d, pos: (down[i] + up[i]) / 2 }));
+    const weights = bounds ? runBiasWeights(down, up, connected, bounds) : sorted.map(() => 0.5);
+    const averaged = sorted.map((_, i) => down[i] * weights[i] + up[i] * (1 - weights[i]));
+    const fitted = bounds ? fitRunsWithinBounds(averaged, connected, bounds) : averaged;
+    const positions = sorted.map((d, i) => ({ ...d, pos: fitted[i] }));
     return { positions, connected };
 }
+/**
+ * Per-run blend weight (applied to the down-pass; `1 - weight` goes to the
+ * up-pass) favouring whichever pass already grows away from the nearer edge
+ * — see {@link declutter1D}'s doc comment for why. `0.5` (the down/up
+ * midpoint, i.e. no bias) when a run's naturally-centred span has roughly
+ * equal room on both sides; sliding toward `1` (all down-pass) as room above
+ * vanishes, toward `0` (all up-pass) as room below vanishes. Every member of
+ * a run gets the *same* weight — the point is the block moving as one
+ * (mostly) one-directional piece, not each member picking its own bias.
+ */
+function runBiasWeights(down, up, connected, [lo, hi]) {
+    const weights = down.map(() => 0.5);
+    let i = 0;
+    while (i < down.length) {
+        let j = i;
+        while (j < connected.length && connected[j])
+            j++;
+        if (j > i) {
+            const center = ((down[i] + up[i]) / 2 + (down[j] + up[j]) / 2) / 2;
+            const roomAbove = Math.max(0, center - lo);
+            const roomBelow = Math.max(0, hi - center);
+            const total = roomAbove + roomBelow;
+            const weight = total > 0 ? roomBelow / total : 0.5;
+            for (let k = i; k <= j; k++)
+                weights[k] = weight;
+        }
+        i = j + 1;
+    }
+    return weights;
+}
+/**
+ * Shifts, and shrinks only if it must, each run of `connected` positions so
+ * it lands entirely inside `[lo, hi]`. A run's own relative spacing is
+ * preserved as-is (just translated) whenever it already fits in `hi - lo`;
+ * only a run wider than the available space gets uniformly scaled down
+ * around its centre first. Lone, unconnected positions pass through
+ * untouched — they were never pushed by `declutter1D` in the first place,
+ * so clamping one to the bounds would move a label away from the data point
+ * it's honestly reporting, for no collision-avoidance reason at all.
+ */
+function fitRunsWithinBounds(positions, connected, [lo, hi]) {
+    const out = [...positions];
+    const available = hi - lo;
+    let i = 0;
+    while (i < out.length) {
+        let j = i;
+        while (j < connected.length && connected[j])
+            j++;
+        if (j > i) {
+            const runMin = out[i];
+            const runMax = out[j];
+            if (runMin < lo || runMax > hi) {
+                const naturalSpan = runMax - runMin;
+                const scale = naturalSpan > 0 ? Math.min(1, available / naturalSpan) : 1;
+                const idealCenter = (runMin + runMax) / 2;
+                const newSpan = naturalSpan * scale;
+                const newCenter = Math.min(Math.max(idealCenter, lo + newSpan / 2), hi - newSpan / 2);
+                for (let k = i; k <= j; k++) {
+                    out[k] = newCenter + (out[k] - idealCenter) * scale;
+                }
+            }
+        }
+        i = j + 1;
+    }
+    return out;
+}
 /**
  * Groups `declutter1D`'s own `connected` flags into runs (maximal stretches
  * of consecutive connected pairs), then assigns each run member a lane by
- * *mirrored* position within it: 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). `depth` is the run's own size, the same for every
- * member; the number of *distinct* lanes it actually needs is
- * `ceil(depth / 2)`.
+ * *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.
+ *
+ * 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.
  *
- * Deliberately doesn't re-derive connectivity from before/after positions —
- * an early version tried that (some mix of "both moved" and "final gap is
- * near minGap") and it's unreliable both ways: a real one-sided interaction
- * (an item that only moved because its neighbour got pushed into it) can
- * settle with more slack than minGap, so a gap-threshold check misses it;
- * and "both moved" over-connects, since two unrelated, far-apart clusters
- * that each independently needed to declutter still each have moved members
- * sitting next to each other in sort order, which a moved-only check can't
- * tell apart from a real interaction. `declutter1D`'s own `connected` array
- * has neither problem, because it's not inferred — it's the actual record
- * of which pushes happened.
+ * 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.
  *
- * Meant to drive a leader line's lane: `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, for a run's own centre member).
- * Two members sharing a lane never collide: by how `declutter1D` centers
- * its result, a run's top half only ever ends up at or above its original
- * spot and its bottom half only ever at or below, so paired members bend
- * away from each other — same lane, opposite direction, no shared space.
- * This also roughly halves the lane depth (and so the horizontal room) a
- * run needs, versus giving every member its own lane.
+ * `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.
  */
-export function mirrorRanks(connected) {
+export function laneAssignment(originals, finals, connected) {
     const n = connected.length + 1;
-    const out = Array.from({ length: n }, () => ({ rank: 0, depth: 1 }));
+    const out = Array.from({ length: n }, () => ({ rank: 0, lanesUsed: 1, runSize: 1 }));
+    const span = (k) => {
+        const a = originals[k];
+        const b = finals[k];
+        return a < b ? [a, b] : [b, a];
+    };
+    const overlaps = (a, b) => a[0] < b[1] && b[0] < a[1];
     let i = 0;
     while (i < n) {
         let j = i;
         while (j < connected.length && connected[j])
             j++;
-        const runLength = j - i + 1;
-        if (runLength > 1) {
-            for (let k = i; k <= j; k++) {
-                const posInRun = k - i;
-                out[k] = { rank: Math.min(posInRun, runLength - 1 - posInRun), depth: runLength };
+        const runSize = j - i + 1;
+        if (runSize > 1) {
+            const rankOf = new Array(runSize);
+            let lo = 0;
+            let hi = runSize - 1;
+            let nextLane = 0;
+            while (lo <= hi) {
+                if (lo === hi) {
+                    rankOf[lo] = nextLane;
+                    nextLane += 1;
+                }
+                else if (!overlaps(span(i + lo), span(i + hi))) {
+                    rankOf[lo] = nextLane;
+                    rankOf[hi] = nextLane;
+                    nextLane += 1;
+                }
+                else {
+                    rankOf[lo] = nextLane;
+                    rankOf[hi] = nextLane + 1;
+                    nextLane += 2;
+                }
+                lo += 1;
+                hi -= 1;
+            }
+            const lanesUsed = nextLane;
+            for (let k = 0; k < runSize; k++) {
+                out[i + k] = { rank: rankOf[k], lanesUsed, runSize };
             }
         }
         i = j + 1;

package/dist/types/configuration/styling.d.ts

@@ -83,6 +83,23 @@ export type ChartConfig = {
     line: {
         strokeWidth: number;
         dotRadius: number;
+        /**
+         * End-of-line value-label declutter geometry and connector styling —
+         * `LinePlot`-specific, since only line charts spread colliding
+         * end-point labels apart with elbow-routed leader lines.
+         */
+        valueLabels: {
+            /** Shortest lane's distance (px) from the data point before a leader line bends. */
+            elbowGap: number;
+            /** Extra distance (px) each subsequent lane sits out from the last. */
+            laneStep: number;
+            /** Clearance (px) between the outermost lane and the label text it feeds into. */
+            labelGap: number;
+            /** Default leader-line colour — overridable per-plot via `styles.values.strokeStyle`. */
+            connectorColor: string;
+            /** Default leader-line width — overridable per-plot via `styles.values.strokeStyle`. */
+            connectorWidth: number;
+        };
     };
     /** Timeline gutter styling. */
     timeline: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fundar/data-chart-telling",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "type": "module",
   "files": [
     "dist"