matterviz 0.3.7 → 0.4.0

package/dist/plot/fill-utils.js

@@ -1,322 +0,0 @@
-// Fill-between utility functions for ScatterPlot fill regions
-// Handles interpolation, boundary resolution, and path generation
-import { area, curveBasis, curveCardinal, curveCatmullRom, curveLinear, curveMonotoneX, curveMonotoneY, curveNatural, curveStep, curveStepAfter, curveStepBefore, } from 'd3-shape';
-// Epsilon value for log scale clamping (to avoid log(0) = -Infinity)
-export const LOG_EPSILON = 1e-10;
-// Resolves a series reference (by index or id) to the actual DataSeries
-// Returns null if the reference cannot be resolved
-export function resolve_series_ref(ref, series) {
-    if (`series_idx` in ref && typeof ref.series_idx === `number`) {
-        const idx = ref.series_idx;
-        if (idx >= 0 && idx < series.length) {
-            return series[idx];
-        }
-        return null;
-    }
-    if (`series_id` in ref && ref.series_id !== undefined) {
-        const found = series.find((data_series) => data_series.id === ref.series_id);
-        return found ?? null;
-    }
-    return null;
-}
-// Helper: linear interpolation at a specific x value
-function interpolate_at(x_values, y_values, target_x) {
-    // Find bracketing indices
-    let [left_idx, right_idx] = [-1, -1];
-    for (let idx = 0; idx < x_values.length; idx++) {
-        if (x_values[idx] <= target_x)
-            left_idx = idx;
-        if (x_values[idx] >= target_x && right_idx === -1)
-            right_idx = idx;
-    }
-    // Handle edge cases: exact match, before all, after all
-    if (left_idx >= 0 && x_values[left_idx] === target_x)
-        return y_values[left_idx];
-    if (left_idx === -1)
-        return y_values[0];
-    if (right_idx === -1)
-        return y_values[y_values.length - 1];
-    // Linear interpolation
-    const x_left = x_values[left_idx];
-    const x_right = x_values[right_idx];
-    const y_left = y_values[left_idx];
-    const y_right = y_values[right_idx];
-    return x_right === x_left
-        ? y_left
-        : y_left + ((target_x - x_left) / (x_right - x_left)) * (y_right - y_left);
-}
-// Helper: step interpolation at a specific x value
-function step_interpolate_at(x_values, y_values, target_x) {
-    // Find the last x value <= target_x
-    let last_idx = -1;
-    for (let idx = 0; idx < x_values.length; idx++) {
-        if (x_values[idx] <= target_x)
-            last_idx = idx;
-        else
-            break;
-    }
-    // Before all x values, use first y value
-    if (last_idx === -1)
-        return y_values[0];
-    return y_values[last_idx];
-}
-// Interpolates two series to have matching x-values
-// Returns arrays with the union of all x-values, sorted
-export function interpolate_series(series_a, series_b, method = `linear`) {
-    // Create union of x-values
-    const x_set = new Set();
-    for (const curr_x of series_a.x)
-        x_set.add(curr_x);
-    for (const curr_x of series_b.x)
-        x_set.add(curr_x);
-    // Sort x-values
-    const all_x = Array.from(x_set).sort((val_a, val_b) => val_a - val_b);
-    const interpolate_fn = method === `step` ? step_interpolate_at : interpolate_at;
-    // Interpolate y values for each x
-    const y_a = all_x.map((target_x) => interpolate_fn(series_a.x, series_a.y, target_x));
-    const y_b = all_x.map((target_x) => interpolate_fn(series_b.x, series_b.y, target_x));
-    return { x: all_x, y_a, y_b };
-}
-// Resolves a FillBoundary definition to an array of y-values at given x positions
-// Returns null if the boundary cannot be resolved
-export function resolve_boundary(boundary, series, x_values, domains) {
-    // Handle shorthand number (constant value)
-    if (typeof boundary === `number`) {
-        return x_values.map(() => boundary);
-    }
-    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];
-    const [y_min, y_max] = region.y_range ?? [null, null];
-    // Helper to clamp value within optional bounds
-    const clamp = (val) => Math.min(y_max ?? Infinity, Math.max(y_min ?? -Infinity, val));
-    const result = {
-        x: [],
-        y1: [],
-        y2: [],
-        original_indices: [],
-    };
-    for (let idx = 0; idx < x_values.length; idx++) {
-        const [curr_x, curr_y1, curr_y2] = [x_values[idx], y1_values[idx], y2_values[idx]];
-        // Skip if outside x range
-        if ((x_min !== null && curr_x < x_min) || (x_max !== null && curr_x > x_max))
-            continue;
-        // Skip if fill region doesn't overlap y range
-        const [fill_min, fill_max] = [Math.min(curr_y1, curr_y2), Math.max(curr_y1, curr_y2)];
-        if ((y_min !== null && fill_max < y_min) || (y_max !== null && fill_min > y_max)) {
-            continue;
-        }
-        result.x.push(curr_x);
-        result.y1.push(clamp(curr_y1));
-        result.y2.push(clamp(curr_y2));
-        result.original_indices.push(idx);
-    }
-    return result;
-}
-// Helper: find x-coordinate where condition changes (linear interpolation)
-function find_crossing(x1, y1_upper, y1_lower, x2, y2_upper, y2_lower, condition) {
-    const cond1 = condition(x1, y1_upper, y1_lower);
-    const cond2 = condition(x2, y2_upper, y2_lower);
-    if (cond1 === cond2)
-        return null;
-    // Binary search for crossing point
-    let left = x1;
-    let right = x2;
-    const tolerance = (x2 - x1) * 0.001;
-    for (let iter = 0; iter < 20; iter++) {
-        const mid = (left + right) / 2;
-        const weight = (mid - x1) / (x2 - x1);
-        const mid_upper = y1_upper + weight * (y2_upper - y1_upper);
-        const mid_lower = y1_lower + weight * (y2_lower - y1_lower);
-        const mid_cond = condition(mid, mid_upper, mid_lower);
-        if (mid_cond === cond1) {
-            left = mid;
-        }
-        else {
-            right = mid;
-        }
-        if (right - left < tolerance)
-            break;
-    }
-    return (left + right) / 2;
-}
-export function apply_where_condition(x_values, y1_values, y2_values, region) {
-    if (!region.where) {
-        // No condition - return single segment with all points
-        const points = x_values.map((curr_x, idx) => ({
-            x: curr_x,
-            y1: y1_values[idx],
-            y2: y2_values[idx],
-        }));
-        return { segments: [points] };
-    }
-    const segments = [];
-    let current_segment = [];
-    for (let idx = 0; idx < x_values.length; idx++) {
-        const curr_x = x_values[idx];
-        const curr_y1 = y1_values[idx];
-        const curr_y2 = y2_values[idx];
-        const passes = region.where(curr_x, curr_y1, curr_y2);
-        if (idx > 0) {
-            const prev_x = x_values[idx - 1];
-            const prev_y1 = y1_values[idx - 1];
-            const prev_y2 = y2_values[idx - 1];
-            const prev_passes = region.where(prev_x, prev_y1, prev_y2);
-            // Check for condition crossing between prev and current
-            if (passes !== prev_passes) {
-                const crossing_x = find_crossing(prev_x, prev_y1, prev_y2, curr_x, curr_y1, curr_y2, region.where);
-                if (crossing_x !== null) {
-                    // Interpolate y values at crossing point
-                    const weight = (crossing_x - prev_x) / (curr_x - prev_x);
-                    const crossing_y1 = prev_y1 + weight * (curr_y1 - prev_y1);
-                    const crossing_y2 = prev_y2 + weight * (curr_y2 - prev_y2);
-                    if (prev_passes) {
-                        // End current segment at crossing
-                        current_segment.push({ x: crossing_x, y1: crossing_y1, y2: crossing_y2 });
-                        segments.push(current_segment);
-                        current_segment = [];
-                    }
-                    else {
-                        // Start new segment at crossing
-                        current_segment.push({ x: crossing_x, y1: crossing_y1, y2: crossing_y2 });
-                    }
-                }
-            }
-        }
-        if (passes) {
-            current_segment.push({ x: curr_x, y1: curr_y1, y2: curr_y2 });
-        }
-        else if (current_segment.length > 0) {
-            segments.push(current_segment);
-            current_segment = [];
-        }
-    }
-    // Don't forget the last segment
-    if (current_segment.length > 0) {
-        segments.push(current_segment);
-    }
-    return { segments };
-}
-export function clamp_for_log_scale(x_values, y1_values, y2_values, y_scale_type, x_scale_type = `linear`) {
-    const result_x = [];
-    const result_y1 = [];
-    const result_y2 = [];
-    const clamped_indices = [];
-    for (let idx = 0; idx < x_values.length; idx++) {
-        let curr_x = x_values[idx];
-        let curr_y1 = y1_values[idx];
-        let curr_y2 = y2_values[idx];
-        let was_clamped = false;
-        // Clamp x if x-axis is log scale
-        if (x_scale_type === `log` && curr_x <= 0) {
-            curr_x = LOG_EPSILON;
-            was_clamped = true;
-        }
-        // Clamp y values if y-axis is log scale
-        if (y_scale_type === `log`) {
-            if (curr_y1 <= 0) {
-                curr_y1 = LOG_EPSILON;
-                was_clamped = true;
-            }
-            if (curr_y2 <= 0) {
-                curr_y2 = LOG_EPSILON;
-                was_clamped = true;
-            }
-        }
-        result_x.push(curr_x);
-        result_y1.push(curr_y1);
-        result_y2.push(curr_y2);
-        if (was_clamped) {
-            clamped_indices.push(idx);
-        }
-    }
-    return {
-        x: result_x,
-        y1: result_y1,
-        y2: result_y2,
-        clamped_indices,
-    };
-}
-// Map FillCurveType to d3 curve factory
-const CURVE_MAP = {
-    linear: curveLinear,
-    monotoneX: curveMonotoneX,
-    monotoneY: curveMonotoneY,
-    step: curveStep,
-    stepBefore: curveStepBefore,
-    stepAfter: curveStepAfter,
-    basis: curveBasis,
-    cardinal: curveCardinal,
-    catmullRom: curveCatmullRom,
-    natural: curveNatural,
-};
-const get_curve = (curve_type) => CURVE_MAP[curve_type] ?? curveMonotoneX;
-// Generate SVG path string for a fill region
-// data should already be in pixel coordinates
-export function generate_fill_path(data, curve_type = `monotoneX`) {
-    if (data.length === 0)
-        return ``;
-    const curve = get_curve(curve_type);
-    const area_generator = area()
-        .x((point) => point.x)
-        .y0((point) => point.y1)
-        .y1((point) => point.y2)
-        .curve(curve);
-    return area_generator(data) ?? ``;
-}
-// Helper to expand error definition to array
-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);
-    if (!resolved)
-        return null;
-    const { y } = resolved;
-    const { error } = error_band;
-    // Determine upper/lower error arrays
-    const [upper_err, lower_err] = typeof error === `object` && `upper` in error
-        ? [expand_error(error.upper, y.length), expand_error(error.lower, y.length)]
-        : [expand_error(error, y.length), expand_error(error, y.length)];
-    return {
-        id: error_band.id,
-        label: error_band.label,
-        upper: { type: `data`, values: y.map((val, idx) => val + upper_err[idx]) },
-        lower: { type: `data`, values: y.map((val, idx) => val - lower_err[idx]) },
-        fill: error_band.fill ?? default_color ?? `#4e79a7`,
-        fill_opacity: error_band.fill_opacity ?? 0.3,
-        edge_upper: error_band.edge_style,
-        edge_lower: error_band.edge_style,
-        show_in_legend: error_band.show_in_legend ?? true,
-    };
-}
-// Type guard to check if fill is a gradient
-export const is_fill_gradient = (fill) => typeof fill === `object` && fill !== null && `type` in fill && `stops` in fill;

package/dist/plot/interactions.d.ts

@@ -1,12 +0,0 @@
-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 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): {
-    range: Vec2;
-    changed: boolean;
-};

package/dist/plot/interactions.js

@@ -1,101 +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 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/svg.d.ts

@@ -1 +0,0 @@
-export declare function bar_path(x: number, y: number, w: number, h: number, r: number, vertical?: boolean): string;

package/dist/plot/svg.js

@@ -1,11 +0,0 @@
-// SVG path and rendering utilities for plot components.
-//
-// Generate SVG path for a bar with rounded corners on the "free" end (away from axis).
-// For vertical bars, rounds top corners. For horizontal bars, rounds right corners.
-export function bar_path(x, y, w, h, r, vertical = true) {
-    if (r <= 0)
-        return `M${x},${y}h${w}v${h}h${-w}Z`;
-    return vertical
-        ? `M${x},${y + h}V${y + r}A${r},${r} 0 0 1 ${x + r},${y}H${x + w - r}A${r},${r} 0 0 1 ${x + w},${y + r}V${y + h}Z`
-        : `M${x},${y}H${x + w - r}A${r},${r} 0 0 1 ${x + w},${y + r}V${y + h - r}A${r},${r} 0 0 1 ${x + w - r},${y + h}H${x}Z`;
-}

package/dist/plot/utils/series-visibility.d.ts

@@ -1,15 +0,0 @@
-import type { DataSeries } from '../types';
-export type StrRecord = Record<string, unknown>;
-type SeriesSource = [string, string, string, unknown, unknown];
-export type SeriesVisibilitySnapshot = {
-    visibility: boolean[];
-    source: SeriesSource[];
-};
-export declare function have_compatible_units<Metadata extends StrRecord = StrRecord>(series1: DataSeries<Metadata>, series2: DataSeries<Metadata>): boolean;
-export declare function toggle_series_visibility<Metadata extends StrRecord = StrRecord>(series: DataSeries<Metadata>[], series_idx: number): DataSeries<Metadata>[];
-export declare function toggle_group_visibility<Metadata extends StrRecord = StrRecord>(series: DataSeries<Metadata>[], series_indices: number[]): DataSeries<Metadata>[];
-export declare function handle_legend_double_click<Metadata extends StrRecord = StrRecord>(series: DataSeries<Metadata>[], idx: number, prev_snapshot: SeriesVisibilitySnapshot | null): {
-    series: DataSeries<Metadata>[];
-    prev_visibility: SeriesVisibilitySnapshot | null;
-};
-export {};

package/dist/plot/utils.d.ts

@@ -1 +0,0 @@
-export declare function calc_auto_range(values: number[]): [number, number];

package/dist/plot/utils.js

@@ -1,14 +0,0 @@
-export function calc_auto_range(values) {
-    const finite_values = values.filter(Number.isFinite);
-    if (finite_values.length === 0)
-        return [0, 1];
-    let [min_value, max_value] = [finite_values[0], finite_values[0]];
-    for (const value of finite_values) {
-        if (value < min_value)
-            min_value = value;
-        else if (value > max_value)
-            max_value = value;
-    }
-    const padding = (max_value - min_value) * 0.05 || 0.5;
-    return [min_value - padding, max_value + padding];
-}