matterviz 0.3.5 → 0.3.7

package/dist/plot/auto-place.d.ts

@@ -0,0 +1,43 @@
+import type { Sides } from './layout';
+export declare const DECOR_GAP = 8;
+type Pt = {
+    x: number;
+    y: number;
+};
+type Size = {
+    width: number;
+    height: number;
+};
+export declare const has_explicit_position: (style?: string | null) => boolean;
+export declare const measured_footprint: (el: HTMLElement | null | undefined, fallback: Size) => Size;
+export declare function build_obstacles_norm(series: {
+    points: Pt[];
+    draws_line?: boolean;
+}[], base_w: number, base_h: number): Pt[];
+export declare function clip_bar(vertical: boolean, cross: number, a: number, b: number): {
+    points: Pt[];
+    draws_line: boolean;
+} | null;
+export type DecorationInput = {
+    footprint: Size;
+    clearance?: number;
+};
+export type DecorationLayout = {
+    pad: Required<Sides>;
+    legend_outside: boolean;
+    legend_pos: Pt;
+    colorbar_outside: boolean;
+    colorbar_style: string;
+};
+export declare function place_decorations(cfg: {
+    base_pad: Required<Sides>;
+    width: number;
+    height: number;
+    obstacles_norm: Pt[];
+    legend?: DecorationInput | null;
+    colorbar?: (DecorationInput & {
+        horizontal?: boolean;
+    }) | null;
+    gap?: number;
+}): DecorationLayout;
+export {};

package/dist/plot/auto-place.js

@@ -0,0 +1,122 @@
+import { compute_element_placement, sample_series_obstacle_points } from './layout';
+// Shared "move a decoration (legend/colorbar) outside the plot when interior overlap is
+// unavoidable" logic, reused by every 2D plot (ScatterPlot/BarPlot/Histogram/BinnedScatterPlot).
+export const DECOR_GAP = 8; // px gap between an outside decoration and the plot edge
+// True when the user pinned a decoration via its style (an edge property or position:absolute),
+// in which case auto-placement must leave it alone.
+export const has_explicit_position = (style) => /(^|[;{]\s*)(top|bottom|left|right)\s*:|position\s*:\s*absolute/.test(style ?? ``);
+// A decoration's pixel footprint: its rendered box once laid out, else `fallback` (offset dims read
+// 0 before first render). Used to decide crowding before the real size is known.
+export const measured_footprint = (el, fallback) => el?.offsetWidth && el?.offsetHeight
+    ? { width: el.offsetWidth, height: el.offsetHeight }
+    : fallback;
+// Build the obstacle field in normalized [0,1] plot coords from one or more series. Callers pass
+// points already normalized to [0,1] with y=0 at the top. Built from data (not pixel scales) so the
+// crowding decision below is independent of any margins reserved for outside decorations — this
+// prevents a reserve -> data-shift -> re-decide oscillation loop.
+export function build_obstacles_norm(series, base_w, base_h) {
+    const step = 12 / Math.max(base_w, base_h, 1);
+    const out = [];
+    for (const srs of series) {
+        // avoid out.push(...arr): a long series would overflow the call-stack arg limit
+        for (const pt of sample_series_obstacle_points(srs.points, srs.draws_line ?? false, step)) {
+            if (isFinite(pt.x) && isFinite(pt.y))
+                out.push(pt);
+        }
+    }
+    return out;
+}
+// Build an obstacle segment for one bar, clipped to the visible [0,1]x[0,1] box (null if off-plot).
+// Clipping is essential: when zoomed in, off-screen bars normalize to huge coords and would make
+// sample_series_obstacle_points emit millions of points. `cross` is the fixed bar position; `a`/`b`
+// are the span endpoints (baseline -> tip) along the other axis.
+export function clip_bar(vertical, cross, a, b) {
+    if (!(cross >= 0 && cross <= 1))
+        return null;
+    const lo = Math.max(0, Math.min(a, b));
+    const hi = Math.min(1, Math.max(a, b));
+    if (hi < lo)
+        return null;
+    const points = vertical
+        ? [
+            { x: cross, y: lo },
+            { x: cross, y: hi },
+        ]
+        : [
+            { x: lo, y: cross },
+            { x: hi, y: cross },
+        ];
+    return { points, draws_line: true };
+}
+// A decoration is "crowded out" only when even the emptiest interior spot is at least this dense
+// relative to the plot-wide average. A single clear region (e.g. one sparse quadrant) keeps the
+// decoration inside; a roughly uniformly-full plot pushes it out. Using a relative ratio (not "any
+// overlap") keeps the decision stable for wide decorations that merely clip a dense neighbor.
+const CROWDING_RATIO = 0.5;
+// True when even the best interior spot for `footprint` (px) is too dense to host the decoration
+function is_crowded(obstacles, footprint, base_w, base_h, clearance) {
+    if (!obstacles.length || base_w <= 0 || base_h <= 0)
+        return false;
+    const fw = footprint.width / base_w;
+    const fh = footprint.height / base_h;
+    if (fw >= 1 || fh >= 1)
+        return true; // too big to fit inside -> outside
+    const best = compute_element_placement({
+        plot_bounds: { x: 0, y: 0, width: 1, height: 1 },
+        element_size: { width: fw, height: fh },
+        axis_clearance: clearance / Math.min(base_w, base_h),
+        points: obstacles,
+    });
+    const in_box = obstacles.filter((pt) => pt.x >= best.x && pt.x <= best.x + fw && pt.y >= best.y && pt.y <= best.y + fh).length;
+    // expected count if obstacles were spread uniformly = total * box-area fraction
+    return in_box > CROWDING_RATIO * obstacles.length * fw * fh;
+}
+// Decide which decorations must move outside (interior placement unavoidably overlaps data), the
+// reserved padding, and the outside positions/styles. `base_pad` must be decoration-independent so
+// the crowding decision can't see the reservation it produces.
+export function place_decorations(cfg) {
+    const { base_pad, width, height, obstacles_norm, legend, colorbar, gap = DECOR_GAP } = cfg;
+    const base_w = width - base_pad.l - base_pad.r;
+    const base_h = height - base_pad.t - base_pad.b;
+    const colorbar_outside = colorbar != null &&
+        is_crowded(obstacles_norm, colorbar.footprint, base_w, base_h, colorbar.clearance ?? 15);
+    const cbar_horizontal = colorbar?.horizontal ?? false;
+    const colorbar_takes_right = colorbar_outside && !cbar_horizontal; // vertical colorbar -> right
+    const cbar_w = colorbar?.footprint.width ?? 0;
+    const cbar_h = colorbar?.footprint.height ?? 0;
+    const legend_outside = legend != null &&
+        is_crowded(obstacles_norm, legend.footprint, base_w, base_h, legend.clearance ?? 12);
+    const legend_w = legend?.footprint.width ?? 0;
+    const legend_h = legend?.footprint.height ?? 0;
+    // Put a narrow/tall legend on the right (wastes less reserved margin than a wide bottom strip);
+    // a wide/short legend goes below. Skip the right side if a vertical colorbar already took it.
+    const legend_right = legend_outside && !colorbar_takes_right && legend_h * base_w > legend_w * base_h;
+    const legend_bottom = legend_outside && !legend_right;
+    // colorbar: horizontal -> above (reserves top), vertical -> right. legend: right or bottom.
+    // A right legend replaces the plot's right margin (it sits flush at the edge), so reserve only its
+    // width + a gap on each side instead of stacking it on top of base_pad.r (which left a wide gap).
+    const pad = {
+        t: base_pad.t + (colorbar_outside && cbar_horizontal ? cbar_h + gap : 0),
+        l: base_pad.l,
+        b: base_pad.b + (legend_bottom ? legend_h + gap : 0),
+        r: legend_right
+            ? legend_w + 2 * gap
+            : base_pad.r + (colorbar_takes_right ? cbar_w + gap : 0),
+    };
+    const colorbar_style = !colorbar_outside
+        ? ``
+        : cbar_horizontal
+            ? `position: absolute; top: ${gap}px; inset-inline: 0; margin-inline: auto; width: calc(100% - ${base_pad.l + base_pad.r}px); max-width: 100%;`
+            : `position: absolute; right: ${gap}px; inset-block: 0; margin-block: auto; height: calc(100% - ${base_pad.t + base_pad.b}px); max-height: 100%;`;
+    // right: flush to the right edge, vertically centered in the plot area; bottom: centered below
+    const legend_pos = legend_right
+        ? {
+            x: width - legend_w - gap,
+            y: base_pad.t + (height - base_pad.t - base_pad.b - legend_h) / 2,
+        }
+        : {
+            x: base_pad.l + (width - base_pad.l - base_pad.r - legend_w) / 2,
+            y: height - legend_h - gap,
+        };
+    return { pad, legend_outside, legend_pos, colorbar_outside, colorbar_style };
+}

package/dist/plot/axis-utils.js

@@ -1,6 +1,6 @@
 // Shared utilities for interactive axis functionality
-// Merge new series with preserved UI state from old series
-// Matches by id first (string or number), then falls back to index
+// Merge new series with preserved UI state from old series.
+// Matches by stable id first, then by index only for ordered id-less series.
 export function merge_series_state(old_series, new_series) {
     // Build id lookup map for O(1) matching (string or number ids)
     const by_id = new Map();
@@ -9,9 +9,7 @@ export function merge_series_state(old_series, new_series) {
             by_id.set(srs.id, srs);
     }
     return new_series.map((new_srs, idx) => {
-        // Match by id if available (string or number), otherwise fall back to index
-        const old_srs = (new_srs.id !== undefined && new_srs.id !== `` ? by_id.get(new_srs.id) : undefined) ??
-            old_series[idx];
+        const old_srs = new_srs.id !== undefined && new_srs.id !== `` ? by_id.get(new_srs.id) : old_series[idx];
         if (!old_srs) {
             return new_srs;
         }

package/dist/plot/binned-scatter-types.d.ts

@@ -0,0 +1,59 @@
+import type { D3ColorSchemeName, D3InterpolateName } from '../colors';
+import type { DenseInternalPoint } from './adaptive-density';
+import type ColorBar from './ColorBar.svelte';
+import type { LabelPlacementConfig, ScaleType, ScatterHandlerProps } from './types';
+import type { ComponentProps, Snippet } from 'svelte';
+export type BinnedColorScaleConfig = {
+    type?: ScaleType;
+    scheme?: D3ColorSchemeName | D3InterpolateName;
+    value_range?: [number, number];
+} | D3InterpolateName;
+export type BinnedSizeScaleConfig = {
+    type?: ScaleType;
+    radius_range?: [number, number];
+    value_range?: [number, number];
+    pick_radius?: number | `auto`;
+};
+export type BinnedDensityConfig = {
+    bin_px?: number;
+    color_scale?: BinnedColorScaleConfig;
+    color_bar?: ComponentProps<typeof ColorBar> | null;
+    auto_point_mode?: false | {
+        max_points?: number;
+        max_points_per_px?: number;
+    };
+    bin_click?: `zoom` | `point` | `none`;
+};
+export type BinnedRefLine = {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    color?: string;
+    dash?: string;
+    width?: number;
+};
+export type BinnedOverlaysConfig = {
+    ref_lines?: BinnedRefLine[];
+};
+export type BinnedPointBasePayload<Metadata extends Record<string, unknown> = Record<string, unknown>> = ScatterHandlerProps<Metadata> & {
+    point: DenseInternalPoint<Metadata>;
+    color?: string;
+};
+export type BinnedPointDataFn<Metadata extends Record<string, unknown> = Record<string, unknown>, PointData extends Record<string, unknown> = Record<string, unknown>> = (payload: BinnedPointBasePayload<Metadata>) => PointData | null | undefined;
+export type BinnedPointPayload<Metadata extends Record<string, unknown> = Record<string, unknown>, PointData extends Record<string, unknown> = Record<string, unknown>> = BinnedPointBasePayload<Metadata> & {
+    point_data?: PointData;
+};
+export type BinnedPointTooltipPayload<Metadata extends Record<string, unknown> = Record<string, unknown>, PointData extends Record<string, unknown> = Record<string, unknown>> = BinnedPointPayload<Metadata, PointData>;
+export type BinnedPointLabelPlacementConfig = Partial<LabelPlacementConfig>;
+export type BinnedPointLabelsConfig<Metadata extends Record<string, unknown> = Record<string, unknown>, PointData extends Record<string, unknown> = Record<string, unknown>> = {
+    render?: Snippet<[BinnedPointPayload<Metadata, PointData>]>;
+    measure_text?: (payload: BinnedPointPayload<Metadata, PointData>) => string;
+    font_size?: string;
+    max_count?: number;
+    gap_px?: number;
+    placement?: BinnedPointLabelPlacementConfig;
+    leaders?: {
+        min_length_px?: number;
+    };
+};

package/dist/plot/binned-scatter-types.js

@@ -0,0 +1 @@
+export {};

package/dist/plot/data-cleaning.js

@@ -696,7 +696,7 @@ export function clean_xyz(x_values, y_values, z_values, config = {}) {
         const bounds_kept = [];
         for (let idx = 0; idx < filtered.x.length; idx++) {
             const primary_val = filtered[primary][idx];
-            // Use x-axis value for dynamic bounds computation (e.g., max: (x) => x * 2)
+            // Use x-axis value for dynamic bounds computation (e.g., max: (x_val) => x_val * 2)
             if (is_in_bounds(primary_val, filtered.x[idx], bounds)) {
                 bounds_kept.push(idx);
             }

package/dist/plot/data-transform.js

@@ -26,7 +26,7 @@ export const prepare_legend_data = (series) => series.map((series_data, series_i
 }));
 // Create data points from series for analysis
 export const create_data_points = (series, filter_fn) => series
-    .filter(filter_fn || ((srs) => srs.visible ?? true))
+    .filter(filter_fn ?? ((srs) => srs.visible ?? true))
     .flatMap(({ x: xs, y: ys }, series_idx) => {
     const length = Math.min(xs.length, ys.length);
     if (xs.length !== ys.length) {

package/dist/plot/fill-utils.d.ts

@@ -5,24 +5,19 @@ export interface FillPathPoint {
     y1: number;
     y2: number;
 }
+type FillPathArrays = Record<keyof FillPathPoint, number[]>;
 export interface InterpolatedSeries {
     x: number[];
     y_a: number[];
     y_b: number[];
 }
-export interface FilteredFillData {
-    x: number[];
-    y1: number[];
-    y2: number[];
+export interface FilteredFillData extends FillPathArrays {
     original_indices: number[];
 }
 export interface ConditionedFillData {
     segments: FillPathPoint[][];
 }
-export interface ClampedFillData {
-    x: number[];
-    y1: number[];
-    y2: number[];
+export interface ClampedFillData extends FillPathArrays {
     clamped_indices: number[];
 }
 export declare function resolve_series_ref(ref: {
@@ -47,5 +42,5 @@ export declare function apply_where_condition(x_values: readonly number[], y1_va
 export declare function clamp_for_log_scale(x_values: readonly number[], y1_values: readonly number[], y2_values: readonly number[], y_scale_type: ScaleType, x_scale_type?: ScaleType): ClampedFillData;
 export declare function generate_fill_path(data: readonly FillPathPoint[], curve_type?: FillCurveType): string;
 export declare function convert_error_band_to_fill_region(error_band: ErrorBand, series: readonly DataSeries[], default_color?: string): FillRegion | null;
-export declare function is_fill_gradient(fill: string | FillGradient | undefined): fill is FillGradient;
+export declare const is_fill_gradient: (fill: string | FillGradient | undefined) => fill is FillGradient;
 export {};

package/dist/plot/fill-utils.js

@@ -84,46 +84,35 @@ export function resolve_boundary(boundary, series, x_values, domains) {
     if (typeof boundary === `number`) {
         return x_values.map(() => boundary);
     }
-    switch (boundary.type) {
-        case `series`: {
-            const resolved = resolve_series_ref(boundary, series);
-            if (!resolved)
-                return null;
-            // Interpolate to match x_values
-            const interpolated = interpolate_series({ x: x_values, y: x_values.map(() => 0) }, { x: resolved.x, y: resolved.y }, `linear`);
-            return interpolated.y_b;
-        }
-        case `constant`:
-            return x_values.map(() => boundary.value);
-        case `axis`: {
-            // For axis boundaries, return the edge value of the appropriate axis domain
-            let value;
-            if (boundary.value !== undefined) {
-                value = boundary.value;
-            }
-            else if (boundary.axis === `y2` && domains.y2_domain) {
-                value = domains.y2_domain[0];
-            }
-            else {
-                // Default: use bottom of y-domain (works for x-axis and y-axis)
-                value = domains.y_domain[0];
-            }
-            return x_values.map(() => value);
-        }
-        case `function`:
-            return x_values.map((curr_x) => boundary.fn(curr_x));
-        case `data`:
-            if (boundary.values.length === 0)
-                return Array(x_values.length).fill(NaN);
-            // If lengths match, use directly; otherwise interpolate
-            if (boundary.values.length === x_values.length) {
-                return [...boundary.values];
-            }
-            // Lengths don't match: truncate if values is longer, or extend last value if shorter
-            return x_values.map((_, idx) => boundary.values[idx] ?? boundary.values[boundary.values.length - 1]);
-        default:
+    if (boundary.type === `series`) {
+        const resolved = resolve_series_ref(boundary, series);
+        if (!resolved)
             return null;
+        // Interpolate to match x_values
+        const interpolated = interpolate_series({ x: x_values, y: x_values.map(() => 0) }, { x: resolved.x, y: resolved.y }, `linear`);
+        return interpolated.y_b;
     }
+    if (boundary.type === `constant`)
+        return x_values.map(() => boundary.value);
+    if (boundary.type === `axis`) {
+        // For axis boundaries, return the edge value of the appropriate axis domain
+        const value = boundary.value ??
+            (boundary.axis === `y2` ? domains.y2_domain?.[0] : undefined) ??
+            domains.y_domain[0];
+        return x_values.map(() => value);
+    }
+    if (boundary.type === `function`)
+        return x_values.map((curr_x) => boundary.fn(curr_x));
+    if (boundary.type === `data`) {
+        if (boundary.values.length === 0)
+            return Array(x_values.length).fill(NaN);
+        // If lengths match, use directly; otherwise interpolate
+        if (boundary.values.length === x_values.length)
+            return [...boundary.values];
+        // Lengths don't match: truncate if values is longer, or extend last value if shorter
+        return x_values.map((_, idx) => boundary.values[idx] ?? boundary.values[boundary.values.length - 1]);
+    }
+    return null;
 }
 export function apply_range_constraints(x_values, y1_values, y2_values, region) {
     const [x_min, x_max] = region.x_range ?? [null, null];
@@ -305,9 +294,7 @@ export function generate_fill_path(data, curve_type = `monotoneX`) {
     return area_generator(data) ?? ``;
 }
 // Helper to expand error definition to array
-function expand_error(err, length) {
-    return typeof err === `number` ? Array(length).fill(err) : err;
-}
+const expand_error = (err, length) => typeof err === `number` ? Array(length).fill(err) : err;
 // Convert an ErrorBand convenience type to a full FillRegion
 export function convert_error_band_to_fill_region(error_band, series, default_color) {
     const resolved = resolve_series_ref(error_band.series, series);
@@ -332,6 +319,4 @@ export function convert_error_band_to_fill_region(error_band, series, default_co
     };
 }
 // Type guard to check if fill is a gradient
-export function is_fill_gradient(fill) {
-    return typeof fill === `object` && fill !== null && `type` in fill && `stops` in fill;
-}
+export const is_fill_gradient = (fill) => typeof fill === `object` && fill !== null && `type` in fill && `stops` in fill;

package/dist/plot/index.d.ts

@@ -2,6 +2,10 @@ export { default as AxisLabel } from './AxisLabel.svelte';
 export { default as BarPlot } from './BarPlot.svelte';
 export { default as BarPlotControls } from './BarPlotControls.svelte';
 export { default as ColorBar } from './ColorBar.svelte';
+export { default as BinnedScatterPlot } from './BinnedScatterPlot.svelte';
+export type { BinnedColorScaleConfig, BinnedDensityConfig, BinnedOverlaysConfig, BinnedPointBasePayload, BinnedPointDataFn, BinnedPointLabelPlacementConfig, BinnedPointLabelsConfig, BinnedPointPayload, BinnedPointTooltipPayload, BinnedRefLine, BinnedSizeScaleConfig, } from './binned-scatter-types';
+export type { DensePointSeries } from './adaptive-density';
+export { default as PlotAxis } from './PlotAxis.svelte';
 export { default as ColorScaleSelect } from './ColorScaleSelect.svelte';
 export * from './data-cleaning';
 export { default as ElementScatter } from './ElementScatter.svelte';

package/dist/plot/index.js

@@ -2,6 +2,8 @@ export { default as AxisLabel } from './AxisLabel.svelte';
 export { default as BarPlot } from './BarPlot.svelte';
 export { default as BarPlotControls } from './BarPlotControls.svelte';
 export { default as ColorBar } from './ColorBar.svelte';
+export { default as BinnedScatterPlot } from './BinnedScatterPlot.svelte';
+export { default as PlotAxis } from './PlotAxis.svelte';
 export { default as ColorScaleSelect } from './ColorScaleSelect.svelte';
 export * from './data-cleaning';
 export { default as ElementScatter } from './ElementScatter.svelte';

package/dist/plot/interactions.d.ts

@@ -1,9 +1,9 @@
-import type { Vec2 } from '../math';
-import type { XyObj, Y2SyncConfig, Y2SyncMode } from './types';
-export declare function get_relative_coords(evt: MouseEvent): XyObj | null;
+import type { Point2D, Vec2 } from '../math';
+import type { Y2SyncConfig, Y2SyncMode } from './types';
+export declare function get_relative_coords(evt: MouseEvent): Point2D | null;
 export declare function normalize_y2_sync(sync: Y2SyncConfig | Y2SyncMode | undefined): Y2SyncConfig;
 export declare function sync_y2_range(y1_range: Vec2, y2_base_range: Vec2, sync: Y2SyncConfig): Vec2;
-export declare function pan_range(current: Vec2, delta: number): Vec2;
+export declare const pan_range: (current: Vec2, delta: number) => Vec2;
 export declare function pixels_to_data_delta(pixel_delta: number, data_range: Vec2, pixel_range: number): number;
 export declare const PINCH_ZOOM_THRESHOLD = 0.1;
 export declare function expand_range_if_needed(current: Vec2, new_range: Vec2): {

package/dist/plot/interactions.js

@@ -60,9 +60,10 @@ export function sync_y2_range(y1_range, y2_base_range, sync) {
     return y2_base_range;
 }
 // Shift a range by a delta amount (no bounds constraint for free panning)
-export function pan_range(current, delta) {
-    return [current[0] + delta, current[1] + delta];
-}
+export const pan_range = (current, delta) => [
+    current[0] + delta,
+    current[1] + delta,
+];
 // Convert pixel delta to data delta using current data range and pixel range
 export function pixels_to_data_delta(pixel_delta, data_range, pixel_range) {
     if (pixel_range === 0)

package/dist/plot/layout.d.ts

@@ -1,7 +1,17 @@
-import type { AxisConfig, Sides } from './';
+import type { AxisConfig } from './types';
+export type Sides = {
+    t?: number;
+    b?: number;
+    l?: number;
+    r?: number;
+};
 export declare const LABEL_GAP_DEFAULT = 30;
 export declare const filter_padding: (padding: Partial<Sides> | undefined | null, defaults: Required<Sides>) => Required<Sides>;
 export declare function measure_text_width(text: string, font?: string): number;
+export declare function measure_full_footprint(el: HTMLElement): {
+    width: number;
+    height: number;
+};
 export interface AutoPaddingConfig {
     padding: Partial<Sides>;
     default_padding: Required<Sides>;
@@ -43,6 +53,7 @@ export interface ElementPlacementConfig {
         width: number;
         height: number;
     };
+    element?: HTMLElement | null;
     axis_clearance?: number;
     exclude_rects?: Rect[];
     points: {
@@ -56,5 +67,12 @@ export interface ElementPlacementResult {
     y: number;
     score: number;
 }
-export declare function rects_overlap(r1: Rect, r2: Rect): boolean;
+export declare const rects_overlap: (r1: Rect, r2: Rect) => boolean;
+export declare function sample_series_obstacle_points(pixel_points: {
+    x: number;
+    y: number;
+}[], draws_line: boolean, step: number): {
+    x: number;
+    y: number;
+}[];
 export declare function compute_element_placement(config: ElementPlacementConfig): ElementPlacementResult;

package/dist/plot/layout.js

@@ -13,15 +13,30 @@ let measurement_canvas = null;
 export function measure_text_width(text, font = `12px sans-serif`) {
     if (typeof document === `undefined`)
         return 0;
-    if (!measurement_canvas) {
-        measurement_canvas = document.createElement(`canvas`);
-    }
+    measurement_canvas ??= document.createElement(`canvas`);
     const ctx = measurement_canvas.getContext(`2d`);
     if (!ctx)
         return 0;
     ctx.font = font;
     return ctx.measureText(text).width;
 }
+// Measure an element's full visual footprint, including descendants that overflow its
+// offset box. Colorbar tick labels are position:absolute outside the bar, so
+// offsetWidth/offsetHeight underestimate the space they actually occupy — which lets
+// auto-placement put the colorbar where its labels overlap the axes.
+export function measure_full_footprint(el) {
+    const root = el.getBoundingClientRect();
+    let right = root.right;
+    let bottom = root.bottom;
+    for (const child of el.querySelectorAll(`*`)) {
+        const rect = child.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0)
+            continue;
+        right = Math.max(right, rect.right);
+        bottom = Math.max(bottom, rect.bottom);
+    }
+    return { width: right - root.left, height: bottom - root.top };
+}
 // Measure the widest formatted tick label. Used for auto-padding and label placement.
 export const measure_max_tick_width = (ticks, format = ``) => ticks.length === 0
     ? 0
@@ -116,18 +131,41 @@ const DISTANCE_WEIGHT = 0.001;
 const CORNER_WEIGHT = 5.0;
 const MAX_SAMPLE_POINTS = 500;
 // Check if a point is inside a rectangle
-function point_in_rect(point, rect) {
-    return (point.x >= rect.x &&
-        point.x <= rect.x + rect.width &&
-        point.y >= rect.y &&
-        point.y <= rect.y + rect.height);
-}
+const point_in_rect = (point, rect) => point.x >= rect.x &&
+    point.x <= rect.x + rect.width &&
+    point.y >= rect.y &&
+    point.y <= rect.y + rect.height;
 // Check if two rectangles overlap
-export function rects_overlap(r1, r2) {
-    return !(r1.x + r1.width <= r2.x ||
-        r2.x + r2.width <= r1.x ||
-        r1.y + r1.height <= r2.y ||
-        r2.y + r2.height <= r1.y);
+export const rects_overlap = (r1, r2) => !(r1.x + r1.width <= r2.x ||
+    r2.x + r2.width <= r1.x ||
+    r1.y + r1.height <= r2.y ||
+    r2.y + r2.height <= r1.y);
+// Build placement obstacles for one series' pixel-space polyline. Always includes the finite
+// vertices; when the series draws a connecting line, also walks each segment between
+// consecutive finite vertices at ~step px so legend/colorbar auto-placement avoids the line,
+// not just sparse markers (e.g. a steep y=x^2 line has few markers but a long visible segment).
+export function sample_series_obstacle_points(pixel_points, draws_line, step) {
+    const obstacles = [];
+    let prev = null;
+    for (const point of pixel_points) {
+        if (!isFinite(point.x) || !isFinite(point.y)) {
+            prev = null; // non-finite breaks the line; don't sample across the gap
+            continue;
+        }
+        obstacles.push(point);
+        if (draws_line && prev && step > 0) {
+            const n_samples = Math.floor(Math.hypot(point.x - prev.x, point.y - prev.y) / step);
+            for (let idx = 1; idx < n_samples; idx++) {
+                const frac = idx / n_samples;
+                obstacles.push({
+                    x: prev.x + (point.x - prev.x) * frac,
+                    y: prev.y + (point.y - prev.y) * frac,
+                });
+            }
+        }
+        prev = point;
+    }
+    return obstacles;
 }
 // Find the best placement position using continuous grid sampling
 // Scores each candidate position by:
@@ -135,10 +173,15 @@ export function rects_overlap(r1, r2) {
 // 2. Overlap with exclusion rectangles (heavy penalty)
 // 3. Distance to nearest point (tie-breaker, farther = better)
 export function compute_element_placement(config) {
-    const { plot_bounds, element_size, axis_clearance = 40, exclude_rects = [], points, grid_resolution: raw_resolution = 10, } = config;
+    const { plot_bounds, element_size, element, axis_clearance = 12, exclude_rects = [], points, grid_resolution: raw_resolution = 10, } = config;
     // Ensure grid_resolution >= 2 to avoid division by zero in step calculation
     const grid_resolution = Math.max(2, raw_resolution);
-    const { width: elem_width, height: elem_height } = element_size;
+    // Measure the element's full footprint (incl. descendants that overflow its box,
+    // such as colorbar tick labels) once it's laid out; fall back to element_size before
+    // first render. Centralizing this keeps every plot's auto-placement overlap-free.
+    const { width: elem_width, height: elem_height } = element?.offsetWidth && element?.offsetHeight
+        ? measure_full_footprint(element)
+        : element_size;
     // Calculate valid placement region (plot bounds minus axis clearance)
     const valid_x_min = plot_bounds.x + axis_clearance;
     const valid_y_min = plot_bounds.y + axis_clearance;

package/dist/plot/reference-line.d.ts

@@ -50,7 +50,7 @@ export interface Scene3DParams {
     z_range: [number, number];
 }
 /** Apply span constraints or use full range as fallback */
-export declare function span_or(span: [number | null, number | null] | undefined, range: [number, number]): [number, number];
+export declare const span_or: (span: [number | null, number | null] | undefined, range: [number, number]) => [number, number];
 export declare function normalize_to_scene(value: number, [min_val, max_val]: [number, number], scene_size: number): number;
 export declare function create_to_threejs(params: Scene3DParams): (user_x: number, user_y: number, user_z: number) => {
     x: number;

package/dist/plot/reference-line.js

@@ -11,6 +11,14 @@ const Z_INDEX_KEY_MAP = {
     'below-points': `below_points`,
     'above-all': `above_all`,
 };
+const apply_span = (start_val, end_val, span) => {
+    if (!span)
+        return [start_val, end_val];
+    return [
+        span[0] !== null ? Math.max(start_val, span[0]) : start_val,
+        span[1] !== null ? Math.min(end_val, span[1]) : end_val,
+    ];
+};
 // Group indexed ref_lines by z-index for ordered rendering
 export function group_ref_lines_by_z(lines) {
     const groups = {
@@ -92,14 +100,6 @@ export function resolve_line_endpoints(ref_line, { x_min, x_max, y_min, y_max, }
     const is_x_visible = (x_val) => x_val >= x_min && x_val <= x_max;
     const is_y_visible = (y_val) => y_val >= y_min && y_val <= y_max;
     // Apply span constraints (works for both x and y)
-    const apply_span = (v1, v2, span) => {
-        if (!span)
-            return [v1, v2];
-        return [
-            span[0] !== null ? Math.max(v1, span[0]) : v1,
-            span[1] !== null ? Math.min(v2, span[1]) : v2,
-        ];
-    };
     const apply_x_span = (x1, x2) => apply_span(x1, x2, ref_line.x_span);
     const apply_y_span = (y1, y2) => apply_span(y1, y2, ref_line.y_span);
     // Relative to data coordinate conversion
@@ -290,9 +290,7 @@ export function calculate_annotation_position(x1, y1, x2, y2, annotation) {
     return { x: final_x, y: final_y, text_anchor, dominant_baseline, rotation };
 }
 /** Apply span constraints or use full range as fallback */
-export function span_or(span, range) {
-    return [span?.[0] ?? range[0], span?.[1] ?? range[1]];
-}
+export const span_or = (span, range) => [span?.[0] ?? range[0], span?.[1] ?? range[1]];
 // Normalize a data value to scene coordinates (centered around 0)
 export function normalize_to_scene(value, [min_val, max_val], scene_size) {
     const range = max_val - min_val;