matterviz 0.3.6 → 0.4.0

package/dist/plot/box/quantile.d.ts

@@ -0,0 +1,3 @@
+export declare function quickselect(values: number[], kth: number): number;
+export declare function quantile_sorted(values: readonly number[], p: number): number;
+export declare function quantile_unordered(values: number[], p: number): number;

package/dist/plot/box/quantile.js

@@ -0,0 +1,53 @@
+// Shared quantile + selection helpers used by box-plot.ts and kde.ts.
+// quickselect partially sorts in place; quantile_unordered mutates its input
+// (quantile_sorted assumes an already-ascending array and never mutates).
+//
+// Unguarded contract: quickselect, quantile_sorted and quantile_unordered all assume
+// values.length > 0 and 0 <= p <= 1. Out-of-range inputs index past the array and
+// yield undefined/NaN — callers (box-plot.ts, kde.ts) must length- and p-range-check
+// before calling.
+export function quickselect(values, kth) {
+    let left = 0;
+    let right = values.length - 1;
+    while (left < right) {
+        const pivot = values[(left + right) >>> 1];
+        let scan_lo = left;
+        let scan_hi = right;
+        while (scan_lo <= scan_hi) {
+            while (values[scan_lo] < pivot)
+                scan_lo++;
+            while (values[scan_hi] > pivot)
+                scan_hi--;
+            if (scan_lo <= scan_hi) {
+                const tmp = values[scan_lo];
+                values[scan_lo] = values[scan_hi];
+                values[scan_hi] = tmp;
+                scan_lo++;
+                scan_hi--;
+            }
+        }
+        if (kth <= scan_hi)
+            right = scan_hi;
+        else if (kth >= scan_lo)
+            left = scan_lo;
+        else
+            return values[kth];
+    }
+    return values[kth];
+}
+export function quantile_sorted(values, p) {
+    const idx = (values.length - 1) * p;
+    const lo = Math.floor(idx);
+    const hi = Math.ceil(idx);
+    const frac = idx - lo;
+    const lo_val = values[lo];
+    return hi === lo ? lo_val : lo_val + (values[hi] - lo_val) * frac;
+}
+export function quantile_unordered(values, p) {
+    const idx = (values.length - 1) * p;
+    const lo = Math.floor(idx);
+    const hi = Math.ceil(idx);
+    const frac = idx - lo;
+    const lo_val = quickselect(values, lo);
+    return hi === lo ? lo_val : lo_val + (quickselect(values, hi) - lo_val) * frac;
+}

package/dist/plot/core/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/core/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 === 0 || 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/core/axis-utils.d.ts

@@ -0,0 +1,46 @@
+import type { AxisConfig, AxisLoadError, BarSeries, DataLoaderFn, DataSeries } from './types';
+export declare const AXIS_DEFAULTS: {
+    format: string;
+    scale_type: "linear";
+    ticks: number;
+    label_shift: {
+        x: number;
+        y: number;
+    };
+    tick: {
+        label: {
+            shift: {
+                x: number;
+                y: number;
+            };
+            inside: boolean;
+        };
+    };
+    range: [number | null, number | null];
+};
+type AxisType = `x` | `x2` | `y` | `y2`;
+export declare function merge_series_state<T extends DataSeries | BarSeries>(old_series: T[], new_series: T[]): T[];
+export interface AxisChangeState<T extends DataSeries | BarSeries> {
+    get_axis: (axis: AxisType) => AxisConfig;
+    set_axis: (axis: AxisType, config: AxisConfig) => void;
+    get_series: () => T[];
+    set_series: (series: T[]) => void;
+    get_loading: () => AxisType | null;
+    set_loading: (axis: AxisType | null) => void;
+}
+export declare const create_axis_change_handler: <T extends DataSeries | BarSeries>(state: AxisChangeState<T>, data_loader: DataLoaderFn<Record<string, unknown>, T> | undefined, on_axis_change?: (axis: AxisType, key: string, new_series: T[]) => void, on_error?: (error: AxisLoadError) => void) => ((axis: AxisType, key: string) => Promise<void>);
+export declare function create_axis_loader<T extends DataSeries | BarSeries>(state: AxisChangeState<T>, get_props: () => {
+    data_loader?: DataLoaderFn<Record<string, unknown>, T>;
+    on_axis_change?: (axis: AxisType, key: string, new_series: T[]) => void;
+    on_error?: (error: AxisLoadError) => void;
+}): {
+    handle_axis_change: (axis: AxisType, key: string) => Promise<void>;
+    try_auto_load: () => void;
+};
+export declare const AXIS_LABEL_CONTAINER: {
+    readonly width: 200;
+    readonly height: 24;
+    readonly x_offset: 100;
+    readonly y_offset: 12;
+};
+export {};

package/dist/plot/core/axis-utils.js

@@ -0,0 +1,110 @@
+// Shared utilities for interactive axis functionality
+import { to_error } from '../../utils';
+// Shared axis defaults across plot components (single source of truth)
+export const AXIS_DEFAULTS = {
+    format: ``,
+    scale_type: `linear`,
+    ticks: 5,
+    label_shift: { x: 0, y: 0 },
+    tick: { label: { shift: { x: 0, y: 0 }, inside: false } },
+    range: [null, null],
+};
+// 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();
+    for (const srs of old_series) {
+        if (srs.id !== undefined && srs.id !== ``)
+            by_id.set(srs.id, srs);
+    }
+    return new_series.map((new_srs, 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;
+        }
+        // Preserve UI state: visibility and styling from old series if not in new
+        const result = { ...new_srs };
+        result.visible ??= old_srs.visible;
+        // Preserve style properties only when key exists in BOTH series (guards against
+        // cross-type injection when T is a union like DataSeries | BarSeries)
+        for (const key of [`point_style`, `line_style`, `color`]) {
+            if (key in old_srs && key in new_srs && result[key] === undefined) {
+                result[key] = old_srs[key];
+            }
+        }
+        return result;
+    });
+}
+// Handle axis property change - loads new data via data_loader
+// Returns a function bound to the component's state accessors
+export const create_axis_change_handler = (state, data_loader, on_axis_change, on_error) => async (axis, key) => {
+    if (!data_loader || state.get_loading())
+        return;
+    const axis_config = state.get_axis(axis);
+    const prev_key = axis_config.selected_key;
+    // Skip if key unchanged AND series already loaded (allows initial load when series empty)
+    if (prev_key === key && state.get_series().length > 0)
+        return;
+    // Update selected_key immediately for UI feedback
+    state.set_axis(axis, { ...axis_config, selected_key: key });
+    state.set_loading(axis);
+    try {
+        const result = await data_loader(axis, key, state.get_series());
+        // Merge new series with preserved state from old series
+        const merged = merge_series_state(state.get_series(), result.series);
+        state.set_series(merged);
+        // Update axis label/unit if provided
+        if (result.axis_label || result.axis_unit) {
+            const current = state.get_axis(axis);
+            state.set_axis(axis, {
+                ...current,
+                label: result.axis_label ?? current.label,
+                unit: result.axis_unit ?? current.unit,
+            });
+        }
+        on_axis_change?.(axis, key, merged);
+    }
+    catch (err) {
+        console.error(`Failed to load data for ${axis}=${key}:`, err);
+        // Revert selection
+        state.set_axis(axis, { ...state.get_axis(axis), selected_key: prev_key });
+        const message = to_error(err).message;
+        on_error?.({ axis, key, message });
+    }
+    finally {
+        state.set_loading(null);
+    }
+};
+// Bundle axis change handler with one-shot auto-load of the first axis option.
+// get_props keeps callback props fresh; try_auto_load reads series/axis configs
+// through state getters so a component `$effect(try_auto_load)` tracks them reactively.
+export function create_axis_loader(state, get_props) {
+    let auto_load_attempted = false; // prevent infinite retries on failure
+    const handle_axis_change = (axis, key) => {
+        const { data_loader, on_axis_change, on_error } = get_props();
+        return create_axis_change_handler(state, data_loader, on_axis_change, on_error)(axis, key);
+    };
+    // Auto-load data if series is empty but options exist (runs once, x-axis first then y)
+    const try_auto_load = () => {
+        if (state.get_series().length > 0 || !get_props().data_loader || auto_load_attempted)
+            return;
+        for (const axis of [`x`, `y`]) {
+            const config = state.get_axis(axis);
+            if (config.options?.length) {
+                auto_load_attempted = true;
+                handle_axis_change(axis, config.selected_key ?? config.options[0].key).catch(() => { });
+                return;
+            }
+        }
+    };
+    return { handle_axis_change, try_auto_load };
+}
+// Constants for axis label foreignObject positioning (all values in px)
+// Use minimal dimensions - overflow: visible handles any dropdown expansion
+export const AXIS_LABEL_CONTAINER = {
+    width: 200, // container width for centering; dropdown can overflow
+    height: 24, // single line height; dropdown options overflow downward
+    x_offset: 100, // half of width for horizontal centering
+    y_offset: 12, // half of height for vertical centering
+};

package/dist/plot/core/components/AxisLabel.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+  import { AXIS_LABEL_CONTAINER } from '../axis-utils'
+  import type { AxisOption } from '../types'
+  import InteractiveAxisLabel from './InteractiveAxisLabel.svelte'
+
+  let {
+    x,
+    y,
+    rotate = false,
+    label = ``,
+    options,
+    selected_key,
+    color,
+    loading = false,
+    axis_type,
+    on_select,
+  }: {
+    x: number
+    y: number
+    rotate?: boolean
+    label?: string
+    options?: AxisOption[]
+    selected_key?: string
+    color?: string | null
+    loading?: boolean
+    axis_type: `x` | `x2` | `y` | `y2`
+    on_select?: (key: string) => void
+  } = $props()
+</script>
+
+<foreignObject
+  x={x - AXIS_LABEL_CONTAINER.x_offset}
+  y={y - AXIS_LABEL_CONTAINER.y_offset}
+  width={AXIS_LABEL_CONTAINER.width}
+  height={AXIS_LABEL_CONTAINER.height}
+  style="overflow: visible; pointer-events: none"
+  transform={rotate ? `rotate(-90, ${x}, ${y})` : undefined}
+>
+  <div xmlns="http://www.w3.org/1999/xhtml" style="pointer-events: auto">
+    <InteractiveAxisLabel
+      {label}
+      {options}
+      {selected_key}
+      {loading}
+      {axis_type}
+      {color}
+      {on_select}
+      class="axis-label {axis_type}-label"
+    />
+  </div>
+</foreignObject>

package/dist/plot/core/components/AxisLabel.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { AxisOption } from '../types';
+type $$ComponentProps = {
+    x: number;
+    y: number;
+    rotate?: boolean;
+    label?: string;
+    options?: AxisOption[];
+    selected_key?: string;
+    color?: string | null;
+    loading?: boolean;
+    axis_type: `x` | `x2` | `y` | `y2`;
+    on_select?: (key: string) => void;
+};
+declare const AxisLabel: import("svelte").Component<$$ComponentProps, {}, "">;
+type AxisLabel = ReturnType<typeof AxisLabel>;
+export default AxisLabel;