matterviz 0.3.4 → 0.3.6

package/dist/plot/interactions.js

@@ -1,100 +0,0 @@
-// 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 function pan_range(current, delta) {
-    return [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

@@ -1,60 +0,0 @@
-import type { AxisConfig, Sides } from './';
-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 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;
-    };
-    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 function rects_overlap(r1: Rect, r2: Rect): boolean;
-export declare function compute_element_placement(config: ElementPlacementConfig): ElementPlacementResult;

package/dist/plot/layout.js

@@ -1,230 +0,0 @@
-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;
-    if (!measurement_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 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
-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);
-}
-// 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);
-}
-// 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, axis_clearance = 40, 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;
-    // 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

@@ -1,60 +0,0 @@
-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 function 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 {};