matterviz 0.3.6 → 0.3.7

package/dist/plot/interactions.js

@@ -0,0 +1,101 @@
+// Get relative coordinates from a mouse event
+export function get_relative_coords(evt) {
+    const current_target = evt.currentTarget;
+    if (!(current_target instanceof SVGElement))
+        return null;
+    const svg_box = current_target.getBoundingClientRect();
+    if (!svg_box)
+        return null;
+    return { x: evt.clientX - svg_box.left, y: evt.clientY - svg_box.top };
+}
+// Normalize Y2 sync config (handle shorthand string vs full object)
+export function normalize_y2_sync(sync) {
+    if (!sync || sync === `none`)
+        return { mode: `none` };
+    if (typeof sync === `string`)
+        return { mode: sync };
+    return sync;
+}
+// Helper to check if all values in ranges are finite
+const all_finite = (...ranges) => ranges.every(([a, b]) => Number.isFinite(a) && Number.isFinite(b));
+// Calculate synced y2 range based on sync mode
+export function sync_y2_range(y1_range, y2_base_range, sync) {
+    if (sync.mode === `none`)
+        return y2_base_range;
+    if (!all_finite(y1_range, y2_base_range))
+        return y2_base_range;
+    // Synced: Y2 has exact same range as Y1
+    if (sync.mode === `synced`) {
+        return [y1_range[0], y1_range[1]];
+    }
+    // Align: Position so align_val (default 0) is at same relative position on both axes
+    // Y2 range expands as needed to show all data while maintaining alignment
+    if (sync.mode === `align`) {
+        const align_val = sync.align_value ?? 0;
+        const y1_span = y1_range[1] - y1_range[0];
+        if (y1_span === 0)
+            return y2_base_range;
+        // Where is align_val in Y1's range? (0 = bottom, 1 = top)
+        const rel_pos = (align_val - y1_range[0]) / y1_span;
+        // Ensure Y2 range includes both align_val and all data
+        const y2_min_data = Math.min(y2_base_range[0], align_val);
+        const y2_max_data = Math.max(y2_base_range[1], align_val);
+        // Calculate minimum span needed to fit all data while keeping align_val at rel_pos
+        // Constraints: y2_min <= y2_min_data AND y2_max >= y2_max_data
+        let y2_span = y2_max_data - y2_min_data;
+        if (rel_pos > 0) {
+            y2_span = Math.max(y2_span, (align_val - y2_min_data) / rel_pos);
+        }
+        if (rel_pos < 1) {
+            y2_span = Math.max(y2_span, (y2_max_data - align_val) / (1 - rel_pos));
+        }
+        const y2_min_computed = align_val - rel_pos * y2_span;
+        const y2_max_computed = align_val + (1 - rel_pos) * y2_span;
+        // When align_val is outside y1_range (rel_pos < 0 or > 1), the formula can produce
+        // a range that omits y2_base_range or align_val. Ensure both are always included.
+        const y2_min = Math.min(y2_min_computed, y2_base_range[0], align_val);
+        const y2_max = Math.max(y2_max_computed, y2_base_range[1], align_val);
+        return [y2_min, y2_max];
+    }
+    return y2_base_range;
+}
+// Shift a range by a delta amount (no bounds constraint for free panning)
+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)
+        return 0;
+    const data_span = data_range[1] - data_range[0];
+    return (pixel_delta / pixel_range) * data_span;
+}
+// Threshold for distinguishing pinch-zoom from pan in touch gestures
+// Scale change > this value triggers zoom instead of pan
+export const PINCH_ZOOM_THRESHOLD = 0.1;
+// Helper to check if range is the default [0, 1] sentinel (no data)
+// Note: min === 0 handles -0 correctly since -0 === 0 in JavaScript
+const is_default_range = ([min, max]) => min === 0 && max === 1;
+// Adopt the new data range, unless all series were hidden (sentinel [0, 1] fallback).
+// NOTE: [0, 1] is the "no data" sentinel - when all series are hidden, auto ranges
+// fall back to [0, 1]. Actual data spanning exactly [0, 1] is a rare edge case.
+export function expand_range_if_needed(current, new_range) {
+    // Guard against NaN/Infinity - prefer valid range, fall back to sentinel [0, 1] if both invalid
+    const current_valid = all_finite(current);
+    const new_valid = all_finite(new_range);
+    if (!current_valid && !new_valid)
+        return { range: [0, 1], changed: true };
+    if (!new_valid)
+        return { range: current, changed: false };
+    if (!current_valid)
+        return { range: new_range, changed: true };
+    // When all series are hidden, auto ranges fall back to [0, 1] sentinel.
+    // Don't shrink to that — preserve the current view so it doesn't jump.
+    if (!is_default_range(current) && is_default_range(new_range)) {
+        return { range: current, changed: false };
+    }
+    // Otherwise adopt the new range directly (both expand and shrink)
+    const changed = new_range[0] !== current[0] || new_range[1] !== current[1];
+    return { range: new_range, changed };
+}

package/dist/plot/layout.d.ts

@@ -0,0 +1,78 @@
+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>;
+    x2_axis?: AxisConfig & {
+        tick_values?: (string | number)[];
+    };
+    y_axis?: AxisConfig & {
+        tick_values?: (string | number)[];
+    };
+    y2_axis?: AxisConfig & {
+        tick_values?: (string | number)[];
+    };
+    label_gap?: number;
+}
+export declare const measure_max_tick_width: (ticks: (string | number)[], format?: string) => number;
+export declare const TICK_LABEL_HEIGHT = 16;
+export declare const AXIS_LABEL_HEIGHT = 20;
+export declare const calc_auto_padding: ({ padding, default_padding, x2_axis, y_axis, y2_axis, label_gap, }: AutoPaddingConfig) => Required<Sides>;
+export declare function constrain_tooltip_position(cursor_x: number, cursor_y: number, tooltip_width: number, tooltip_height: number, viewport_width: number, viewport_height: number, options?: {
+    offset?: number;
+    offset_x?: number;
+    offset_y?: number;
+}): {
+    x: number;
+    y: number;
+};
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare const pad_rect: (rect: Rect, padding: number) => Rect;
+export declare const centered_rect: (center_x: number, top_y: number, width: number, height: number) => Rect;
+export declare const rect_within_rect: (rect: Rect, bounds: Rect) => boolean;
+export interface ElementPlacementConfig {
+    plot_bounds: Rect;
+    element_size: {
+        width: number;
+        height: number;
+    };
+    element?: HTMLElement | null;
+    axis_clearance?: number;
+    exclude_rects?: Rect[];
+    points: {
+        x: number;
+        y: number;
+    }[];
+    grid_resolution?: number;
+}
+export interface ElementPlacementResult {
+    x: number;
+    y: number;
+    score: number;
+}
+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

@@ -0,0 +1,273 @@
+import { format_value } from '../labels';
+import { euclidean_dist } from '../math';
+// Default gap between tick labels and axis labels
+export const LABEL_GAP_DEFAULT = 30;
+// Filter undefined values from padding to prevent overriding defaults when spreading
+// Guards against undefined/null padding inputs (common for optional props)
+export const filter_padding = (padding, defaults) => ({
+    ...defaults,
+    ...Object.fromEntries(Object.entries(padding ?? {}).filter(([, v]) => v !== undefined)),
+});
+// Measure text width using canvas (singleton pattern for performance)
+let measurement_canvas = null;
+export function measure_text_width(text, font = `12px sans-serif`) {
+    if (typeof document === `undefined`)
+        return 0;
+    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
+    : Math.max(...ticks.map((tick) => {
+        const label = typeof tick === `string` ? tick : format_value(tick, format);
+        return measure_text_width(label, `12px sans-serif`);
+    }));
+// Estimated height of a single tick label line (font-size 0.8em ≈ 12px + leading)
+export const TICK_LABEL_HEIGHT = 16;
+// Estimated height of an axis label (font-size ~14px + margin)
+export const AXIS_LABEL_HEIGHT = 20;
+export const calc_auto_padding = ({ padding, default_padding, x2_axis = {}, y_axis = {}, y2_axis = {}, label_gap = LABEL_GAP_DEFAULT, }) => {
+    const x2_ticks = x2_axis.tick_values ?? [];
+    const y_ticks = y_axis.tick_values ?? [];
+    const y_format = y_axis.format ?? ``;
+    const y2_ticks = y2_axis.tick_values ?? [];
+    const y2_format = y2_axis.format ?? ``;
+    return {
+        t: padding.t ??
+            (x2_ticks.length > 0
+                ? Math.max(default_padding.t, TICK_LABEL_HEIGHT + label_gap + (x2_axis.label ? AXIS_LABEL_HEIGHT : 0))
+                : default_padding.t),
+        b: padding.b ?? default_padding.b,
+        l: padding.l ??
+            Math.max(default_padding.l, measure_max_tick_width(y_ticks, y_format) + label_gap),
+        r: padding.r ??
+            Math.max(default_padding.r, measure_max_tick_width(y2_ticks, y2_format) + label_gap),
+    };
+};
+// Constrain tooltip position within bounds, flipping to opposite side if overflow
+// offset_x/offset_y control initial positioning: positive = right/down, negative = left/up
+export function constrain_tooltip_position(cursor_x, cursor_y, tooltip_width, tooltip_height, viewport_width, viewport_height, options = {}) {
+    const { offset = 10 } = options;
+    const offset_x = options.offset_x ?? offset;
+    const offset_y = options.offset_y ?? offset;
+    // Position to left of cursor if right-side placement overflows (and vice versa)
+    const flip_x = offset_x >= 0
+        ? cursor_x + offset_x + tooltip_width > viewport_width
+        : cursor_x + offset_x - tooltip_width < 0;
+    // Position above cursor if bottom placement overflows (and vice versa)
+    const flip_y = offset_y >= 0
+        ? cursor_y + offset_y + tooltip_height > viewport_height
+        : cursor_y + offset_y - tooltip_height < 0;
+    // Calculate position: apply offset, flip if needed
+    const abs_offset_x = Math.abs(offset_x);
+    const abs_offset_y = Math.abs(offset_y);
+    // Determine X position based on preferred side and flip state
+    let raw_x;
+    if (offset_x >= 0) {
+        // Prefer right side: flip to left if overflows
+        raw_x = flip_x ? cursor_x - abs_offset_x - tooltip_width : cursor_x + abs_offset_x;
+    }
+    else {
+        // Prefer left side: flip to right if overflows
+        raw_x = flip_x ? cursor_x + abs_offset_x : cursor_x - abs_offset_x - tooltip_width;
+    }
+    // Determine Y position based on preferred side and flip state
+    let raw_y;
+    if (offset_y >= 0) {
+        // Prefer bottom: flip to top if overflows
+        raw_y = flip_y ? cursor_y - abs_offset_y - tooltip_height : cursor_y + abs_offset_y;
+    }
+    else {
+        // Prefer top: flip to bottom if overflows
+        raw_y = flip_y ? cursor_y + abs_offset_y : cursor_y - abs_offset_y - tooltip_height;
+    }
+    // Clamp to viewport bounds
+    const x_pos = Math.max(0, Math.min(raw_x, viewport_width - tooltip_width));
+    const y_pos = Math.max(0, Math.min(raw_y, viewport_height - tooltip_height));
+    return { x: x_pos, y: y_pos };
+}
+export const pad_rect = (rect, padding) => ({
+    x: rect.x - padding,
+    y: rect.y - padding,
+    width: rect.width + 2 * padding,
+    height: rect.height + 2 * padding,
+});
+export const centered_rect = (center_x, top_y, width, height) => ({
+    x: center_x - width / 2,
+    y: top_y,
+    width,
+    height,
+});
+export const rect_within_rect = (rect, bounds) => rect.x >= bounds.x &&
+    rect.x + rect.width <= bounds.x + bounds.width &&
+    rect.y >= bounds.y &&
+    rect.y + rect.height <= bounds.y + bounds.height;
+// Scoring constants
+const EXCLUSION_PENALTY = 1000;
+const DISTANCE_WEIGHT = 0.001;
+// Strong corner preference: corners can have 3-4 more overlapping points and still win
+const CORNER_WEIGHT = 5.0;
+const MAX_SAMPLE_POINTS = 500;
+// Check if a point is inside a rectangle
+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 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:
+// 1. Number of data points overlapping the element bounds (fewer = better)
+// 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, 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);
+    // 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;
+    const valid_x_max = plot_bounds.x + plot_bounds.width - axis_clearance - elem_width;
+    const valid_y_max = plot_bounds.y + plot_bounds.height - axis_clearance - elem_height;
+    // Handle case where element is too large for the valid region
+    const effective_x_min = Math.min(valid_x_min, valid_x_max);
+    const effective_x_max = Math.max(valid_x_min, valid_x_max);
+    const effective_y_min = Math.min(valid_y_min, valid_y_max);
+    const effective_y_max = Math.max(valid_y_min, valid_y_max);
+    // Subsample points for performance
+    const sampled_points = points.length > MAX_SAMPLE_POINTS
+        ? Array.from({ length: MAX_SAMPLE_POINTS }, (_, idx) => points[Math.floor((idx * points.length) / MAX_SAMPLE_POINTS)])
+        : points;
+    let best_result = {
+        x: effective_x_min,
+        y: effective_y_min,
+        score: -Infinity,
+    };
+    // Sample candidate positions on a grid
+    const x_step = effective_x_max > effective_x_min
+        ? (effective_x_max - effective_x_min) / (grid_resolution - 1)
+        : 0;
+    const y_step = effective_y_max > effective_y_min
+        ? (effective_y_max - effective_y_min) / (grid_resolution - 1)
+        : 0;
+    // Precompute plot corners (constant across all candidates)
+    const plot_left = plot_bounds.x + axis_clearance;
+    const plot_right = plot_bounds.x + plot_bounds.width - axis_clearance;
+    const plot_top = plot_bounds.y + axis_clearance;
+    const plot_bottom = plot_bounds.y + plot_bounds.height - axis_clearance;
+    const max_corner_dist = euclidean_dist([plot_left, plot_top], [plot_right, plot_bottom]);
+    for (let grid_x = 0; grid_x < grid_resolution; grid_x++) {
+        for (let grid_y = 0; grid_y < grid_resolution; grid_y++) {
+            const cand_x = effective_x_min + grid_x * x_step;
+            const cand_y = effective_y_min + grid_y * y_step;
+            const cand_rect = {
+                x: cand_x,
+                y: cand_y,
+                width: elem_width,
+                height: elem_height,
+            };
+            // Check for overlap with exclusion rectangles first (early rejection)
+            let exclusion_penalty = 0;
+            for (const excl_rect of exclude_rects) {
+                if (rects_overlap(cand_rect, excl_rect)) {
+                    exclusion_penalty += EXCLUSION_PENALTY;
+                }
+            }
+            // Count points overlapping this candidate position
+            let overlap_count = 0;
+            let min_distance_sq = Infinity;
+            const center_x = cand_x + elem_width / 2;
+            const center_y = cand_y + elem_height / 2;
+            for (const point of sampled_points) {
+                if (point_in_rect(point, cand_rect)) {
+                    overlap_count++;
+                }
+                // Track distance to nearest point for tie-breaking
+                const dx = point.x - center_x;
+                const dy = point.y - center_y;
+                const dist_sq = dx * dx + dy * dy;
+                if (dist_sq < min_distance_sq) {
+                    min_distance_sq = dist_sq;
+                }
+            }
+            // Score: fewer overlaps = better (less negative)
+            // Add small distance bonus for tie-breaking
+            // When no points exist, min_distance_sq stays Infinity - treat as 0 (no distance bonus)
+            const min_distance = min_distance_sq === Infinity ? 0 : Math.sqrt(min_distance_sq);
+            // Corner preference: use element's actual corner (not center) for distance
+            // This ensures a wide element at the left edge gets proper corner credit
+            const elem_right = cand_x + element_size.width;
+            const elem_bottom = cand_y + element_size.height;
+            // Distance from element's matching corner to each plot corner
+            const min_corner_dist = Math.min(euclidean_dist([cand_x, cand_y], [plot_left, plot_top]), // top-left
+            euclidean_dist([elem_right, cand_y], [plot_right, plot_top]), // top-right
+            euclidean_dist([cand_x, elem_bottom], [plot_left, plot_bottom]), // bottom-left
+            euclidean_dist([elem_right, elem_bottom], [plot_right, plot_bottom]));
+            // Higher bonus for positions closer to corners (0 = at corner, 1 = far from all)
+            const corner_bonus = max_corner_dist > 0 ? (1 - min_corner_dist / max_corner_dist) * CORNER_WEIGHT : 0;
+            const score = -overlap_count + min_distance * DISTANCE_WEIGHT + corner_bonus - exclusion_penalty;
+            if (score > best_result.score) {
+                best_result = { x: cand_x, y: cand_y, score };
+            }
+        }
+    }
+    return best_result;
+}

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

@@ -0,0 +1,60 @@
+import type { RefLine, RefLineValue } from './types';
+export type IndexedRefLine = RefLine & {
+    idx: number;
+};
+export declare function index_ref_lines(ref_lines: RefLine[] | undefined): IndexedRefLine[];
+export interface RefLinesByZIndex {
+    below_grid: IndexedRefLine[];
+    below_lines: IndexedRefLine[];
+    below_points: IndexedRefLine[];
+    above_all: IndexedRefLine[];
+}
+export declare function group_ref_lines_by_z(lines: IndexedRefLine[]): RefLinesByZIndex;
+export declare function normalize_value(value: RefLineValue): number;
+export declare const normalize_point: (point: [RefLineValue, RefLineValue]) => [number, number];
+export declare function resolve_line_endpoints(ref_line: RefLine, { x_min, x_max, y_min, y_max, }: {
+    x_min: number;
+    x_max: number;
+    y_min: number;
+    y_max: number;
+}, { x_scale, x2_scale, y_scale, y2_scale, }: {
+    x_scale: (val: number) => number;
+    x2_scale?: (val: number) => number;
+    y_scale: (val: number) => number;
+    y2_scale?: (val: number) => number;
+}): [number, number, number, number] | null;
+interface AnnotationPosition {
+    x: number;
+    y: number;
+    text_anchor: `start` | `middle` | `end`;
+    dominant_baseline: `auto` | `middle` | `hanging`;
+    rotation?: number;
+}
+export declare function calculate_annotation_position(x1: number, y1: number, x2: number, y2: number, annotation: {
+    position?: `start` | `center` | `end`;
+    side?: `above` | `below` | `left` | `right`;
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    gap?: number;
+    edge_padding?: number;
+    rotate?: boolean;
+}): AnnotationPosition;
+export interface Scene3DParams {
+    scene_x: number;
+    scene_y: number;
+    scene_z: number;
+    x_range: [number, number];
+    y_range: [number, number];
+    z_range: [number, number];
+}
+/** Apply span constraints or use full range as fallback */
+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;
+    y: number;
+    z: number;
+};
+export {};