matterviz 0.4.0 → 0.4.2

package/dist/plot/box/BoxPlot.svelte.d.ts

@@ -1,4 +1,6 @@
+import type { Vec2 } from '../../math';
 import type { BandwidthOption, BasePlotProps, BoxHandlerProps, BoxPlotSeries, LegendConfig, Orientation, PanConfig, PlotConfig, RefLine, RefLineEvent, UserContentProps, ViolinKind, ViolinSide, WhiskerMode } from '..';
+import type { MarginalsProp } from '../core/marginals';
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 declare function $$render<Metadata extends Record<string, unknown> = Record<string, unknown>>(): {
@@ -30,7 +32,7 @@ declare function $$render<Metadata extends Record<string, unknown> = Record<stri
         };
         whisker_mode?: WhiskerMode;
         whisker_range?: number;
-        whisker_percentiles?: [number, number];
+        whisker_percentiles?: Vec2;
         show_outliers?: boolean;
         show_mean?: boolean;
         show_value_labels?: boolean;
@@ -69,9 +71,10 @@ declare function $$render<Metadata extends Record<string, unknown> = Record<stri
         on_ref_line_click?: (event: RefLineEvent) => void;
         on_ref_line_hover?: (event: RefLineEvent | null) => void;
         pan?: PanConfig;
+        marginals?: MarginalsProp;
     };
     exports: {};
-    bindings: "orientation" | "display" | "show_controls" | "fullscreen" | "series" | "hovered" | "ref_lines" | "controls_open" | "x_axis" | "y_axis" | "whisker_mode" | "x2_axis" | "y2_axis" | "show_outliers" | "show_mean" | "kind" | "side";
+    bindings: "display" | "orientation" | "show_controls" | "x2_axis" | "y_axis" | "y2_axis" | "fullscreen" | "series" | "hovered" | "ref_lines" | "controls_open" | "x_axis" | "kind" | "side" | "whisker_mode" | "show_outliers" | "show_mean";
     slots: {};
     events: {};
 };
@@ -79,7 +82,7 @@ declare class __sveltets_Render<Metadata extends Record<string, unknown> = Recor
     props(): ReturnType<typeof $$render<Metadata>>['props'];
     events(): ReturnType<typeof $$render<Metadata>>['events'];
     slots(): ReturnType<typeof $$render<Metadata>>['slots'];
-    bindings(): "orientation" | "display" | "show_controls" | "fullscreen" | "series" | "hovered" | "ref_lines" | "controls_open" | "x_axis" | "y_axis" | "whisker_mode" | "x2_axis" | "y2_axis" | "show_outliers" | "show_mean" | "kind" | "side";
+    bindings(): "display" | "orientation" | "show_controls" | "x2_axis" | "y_axis" | "y2_axis" | "fullscreen" | "series" | "hovered" | "ref_lines" | "controls_open" | "x_axis" | "kind" | "side" | "whisker_mode" | "show_outliers" | "show_mean";
     exports(): {};
 }
 interface $$IsomorphicComponent {

package/dist/plot/box/BoxPlotControls.svelte.d.ts

@@ -14,6 +14,6 @@ type $$ComponentProps = Omit<PlotControlsProps, `children` | `post_children`> &
         orientation: Orientation;
     } & Required<PlotConfig>]>;
 };
-declare const BoxPlotControls: import("svelte").Component<$$ComponentProps, {}, "orientation" | "display" | "show_controls" | "controls_open" | "x_axis" | "y_axis" | "whisker_mode" | "x2_axis" | "y2_axis" | "show_outliers" | "show_mean" | "kind" | "side">;
+declare const BoxPlotControls: import("svelte").Component<$$ComponentProps, {}, "display" | "orientation" | "show_controls" | "x2_axis" | "y_axis" | "y2_axis" | "controls_open" | "x_axis" | "kind" | "side" | "whisker_mode" | "show_outliers" | "show_mean">;
 type BoxPlotControls = ReturnType<typeof BoxPlotControls>;
 export default BoxPlotControls;

package/dist/plot/box/Violin.svelte.d.ts

@@ -26,7 +26,7 @@ declare const Violin: import("svelte").Component<import("svelte/elements").HTMLA
     } | undefined;
     whisker_mode?: import("./box-plot").WhiskerMode;
     whisker_range?: number;
-    whisker_percentiles?: [number, number];
+    whisker_percentiles?: import("../..").Vec2;
     show_outliers?: boolean;
     show_mean?: boolean;
     show_value_labels?: boolean;
@@ -65,6 +65,7 @@ declare const Violin: import("svelte").Component<import("svelte/elements").HTMLA
     on_ref_line_click?: ((event: import("..").RefLineEvent) => void) | undefined;
     on_ref_line_hover?: ((event: import("..").RefLineEvent | null) => void) | undefined;
     pan?: import("..").PanConfig;
+    marginals?: import("..").MarginalsProp;
 }, {}, "series" | "kind">;
 type Violin = ReturnType<typeof Violin>;
 export default Violin;

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

@@ -1,3 +1,4 @@
+import type { Vec2 } from '../../math';
 import type { HandlerProps } from '../core/types';
 export type WhiskerMode = `tukey` | `minmax` | `percentile` | `std`;
 export type ViolinKind = `box` | `violin` | `violin+box`;
@@ -16,7 +17,7 @@ export interface BoxPlotSeries<Metadata = Record<string, unknown>> {
     y_axis?: `y1` | `y2`;
     whisker_mode?: WhiskerMode;
     whisker_range?: number;
-    whisker_percentiles?: [number, number];
+    whisker_percentiles?: Vec2;
     kind?: ViolinKind;
     side?: ViolinSide;
     bandwidth?: BandwidthOption;
@@ -47,7 +48,7 @@ export interface BoxStats {
 export interface BoxStatsOptions {
     whisker_mode?: WhiskerMode;
     whisker_range?: number;
-    whisker_percentiles?: [number, number];
+    whisker_percentiles?: Vec2;
     collect_outliers?: boolean;
 }
 export declare const WHISKER_MODES: readonly ["tukey", "minmax", "percentile", "std"];

package/dist/plot/box/box-plot.js

@@ -2,6 +2,8 @@
 // Single source of truth for the quantile math used by BoxPlot.svelte.
 import { ascending } from 'd3-array';
 import { quantile_unordered } from './quantile';
+import { DEFAULTS } from '../../settings';
+import { clamp01 } from '../../utils';
 export const WHISKER_MODES = [`tukey`, `minmax`, `percentile`, `std`];
 const WHISKER_MODE_SET = new Set(WHISKER_MODES);
 export const is_whisker_mode = (val) => WHISKER_MODE_SET.has(val);
@@ -17,7 +19,6 @@ const EMPTY_STATS = {
     outliers: [],
     n: 0,
 };
-const clamp01 = (val) => Math.max(0, Math.min(1, val));
 function collect_outliers_by_scan(values, low_bound, high_bound, collect) {
     if (!collect)
         return [];
@@ -56,7 +57,9 @@ function tukey_scan(values, low_bound, high_bound, collect, data_min, data_max)
 // Quartiles use type-7 linear interpolation, matching d3/numpy/pandas defaults.
 // Non-finite values are filtered out; the input array is never mutated.
 export function compute_box_stats(values, opts = {}) {
-    const { whisker_mode = `tukey`, whisker_range = 1.5, whisker_percentiles = [5, 95], collect_outliers = true, } = opts;
+    const { 
+    // Fallback derives from DEFAULTS.box so component and helper defaults can't drift
+    whisker_mode = DEFAULTS.box.whisker_mode, whisker_range = 1.5, whisker_percentiles = [5, 95], collect_outliers = true, } = opts;
     const vals = values.filter((val) => Number.isFinite(val));
     const n_vals = vals.length;
     if (n_vals === 0)
@@ -72,7 +75,7 @@ export function compute_box_stats(values, opts = {}) {
             data_max = val;
     }
     const mean = sum / n_vals;
-    const qtl = (p) => quantile_unordered(vals, p);
+    const qtl = (prob) => quantile_unordered(vals, prob);
     const collect_beyond = (lo, hi) => collect_outliers_by_scan(vals, lo, hi, collect_outliers);
     const q1 = qtl(0.25);
     const median = qtl(0.5);

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

@@ -1,3 +1,4 @@
+import type { Vec2 } from '../../math';
 export interface KdeResult {
     grid: number[];
     density: number[];
@@ -8,7 +9,7 @@ export interface KdeOptions {
     n_points?: number;
     cut?: number;
     clip?: [number | null, number | null];
-    range?: [number, number];
+    range?: Vec2;
     max_samples?: number;
 }
 export declare function silverman_bandwidth(sorted: readonly number[]): number;

package/dist/plot/box/kde.js

@@ -55,8 +55,8 @@ function exact_density(eval_samples, grid, band) {
         const g_val = grid[grid_idx];
         let sum = 0;
         for (const sample of eval_samples) {
-            const u = (g_val - sample) / band;
-            sum += Math.exp(-0.5 * u * u);
+            const z_score = (g_val - sample) / band;
+            sum += Math.exp(-0.5 * z_score * z_score);
         }
         density[grid_idx] = sum * norm;
     }
@@ -98,8 +98,8 @@ function binned_density(eval_samples, grid, band) {
             const count = counts[bin_idx];
             if (count === 0)
                 continue;
-            const u = (g_val - centers[bin_idx]) / band;
-            sum += count * Math.exp(-0.5 * u * u);
+            const z_score = (g_val - centers[bin_idx]) / band;
+            sum += count * Math.exp(-0.5 * z_score * z_score);
         }
         density[grid_idx] = sum * norm;
     }

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

@@ -1,5 +1,4 @@
 import type { Sides } from './layout';
-export declare const DECOR_GAP = 8;
 type Pt = {
     x: number;
     y: number;
@@ -8,6 +7,7 @@ type Size = {
     width: number;
     height: number;
 };
+export declare const placed_coords: (auto_outside: boolean, outside: Pt, placement: Pt | null, tweened: Pt, fallback: Pt) => Pt;
 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: {

package/dist/plot/core/auto-place.js

@@ -1,10 +1,13 @@
 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
+const DECOR_GAP = 8; // px gap between an outside decoration and the plot edge
+// Final on-screen position for an auto-placed decoration: explicit outside placement
+// wins, then the tweened auto placement, else a static padding fallback
+export const placed_coords = (auto_outside, outside, placement, tweened, fallback) => (auto_outside ? outside : placement ? tweened : fallback);
 // 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 ?? ``);
+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

package/dist/plot/core/axis-utils.d.ts

@@ -21,14 +21,19 @@ export declare const AXIS_DEFAULTS: {
 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;
+    axes: Record<AxisType, {
+        get: () => AxisConfig;
+        set: (config: AxisConfig) => void;
+    }>;
+    series: {
+        get: () => T[];
+        set: (series: T[]) => void;
+    };
+    loading: {
+        get: () => AxisType | null;
+        set: (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;

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

@@ -36,61 +36,61 @@ export function merge_series_state(old_series, new_series) {
         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.
+// Axis-change loader: `handle_axis_change` loads new data for an axis property change via the
+// data_loader (reading `get_props` fresh each call so callbacks stay current), and `try_auto_load`
+// loads the first axis option once when series start empty. Reads state through 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) => {
+    // No-op when already loading, or when the key is unchanged and series are already present
+    const handle_axis_change = async (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);
+        if (!data_loader || state.loading.get())
+            return;
+        const axis_config = state.axes[axis].get();
+        const prev_key = axis_config.selected_key;
+        if (prev_key === key && state.series.get().length > 0)
+            return;
+        state.axes[axis].set({ ...axis_config, selected_key: key }); // immediate UI feedback
+        state.loading.set(axis);
+        let merged = state.series.get();
+        let load_error;
+        try {
+            const result = await data_loader(axis, key, state.series.get());
+            merged = merge_series_state(state.series.get(), result.series);
+            state.series.set(merged);
+            // !== undefined (not truthiness) so a loader can intentionally clear a label/unit to ``
+            if (result.axis_label !== undefined || result.axis_unit !== undefined) {
+                const current = state.axes[axis].get();
+                state.axes[axis].set({
+                    ...current,
+                    label: result.axis_label ?? current.label,
+                    unit: result.axis_unit ?? current.unit,
+                });
+            }
+        }
+        catch (err) {
+            console.error(`Failed to load data for ${axis}=${key}:`, err);
+            state.axes[axis].set(axis_config); // revert every axis field mutated above, not just selected_key
+            load_error = { axis, key, message: to_error(err).message };
+        }
+        finally {
+            state.loading.set(null); // always clears, even if a consumer callback below throws
+        }
+        // callbacks run only after internal state is fully settled, so a throwing consumer callback
+        // can neither leave `loading` stuck nor trigger the loader rollback
+        if (load_error) {
+            on_error?.(load_error);
+            return;
+        }
+        on_axis_change?.(axis, key, merged);
     };
-    // Auto-load data if series is empty but options exist (runs once, x-axis first then y)
+    // Auto-load once if series is empty but options exist (x-axis first, then y)
     const try_auto_load = () => {
-        if (state.get_series().length > 0 || !get_props().data_loader || auto_load_attempted)
+        if (state.series.get().length > 0 || !get_props().data_loader || auto_load_attempted)
             return;
         for (const axis of [`x`, `y`]) {
-            const config = state.get_axis(axis);
+            const config = state.axes[axis].get();
             if (config.options?.length) {
                 auto_load_attempted = true;
                 handle_axis_change(axis, config.selected_key ?? config.options[0].key).catch(() => { });

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

@@ -14,6 +14,7 @@
     loading = false,
     axis_type,
     on_select,
+    width = AXIS_LABEL_CONTAINER.width,
   }: {
     x: number
     y: number
@@ -25,27 +26,88 @@
     loading?: boolean
     axis_type: `x` | `x2` | `y` | `y2`
     on_select?: (key: string) => void
+    // container width for centering/wrapping; wider lets long horizontal titles fit on one line
+    width?: number
   } = $props()
+
+  interface LabelSegment {
+    text: string
+    shift?: `sub` | `super`
+  }
+
+  const decode_text = (value: string, textarea?: HTMLTextAreaElement): string => {
+    // Strip only sub/sup markup so literal angle-bracket text like <100> survives
+    const without_tags = value.replaceAll(/<\/?(?:sub|sup)\b[^>]*>/gi, ``)
+    if (!textarea) return without_tags
+    textarea.innerHTML = without_tags
+    return textarea.value
+  }
+
+  const label_segments = (value: string): LabelSegment[] => {
+    const segments: LabelSegment[] = []
+    const tag_pattern = /<(?<tag>sub|sup)\b[^>]*>(?<inner>.*?)<\/\k<tag>>/gis
+    const textarea =
+      typeof document === `undefined` ? undefined : document.createElement(`textarea`)
+    let cursor = 0
+    for (const match of value.matchAll(tag_pattern)) {
+      const start = match.index ?? 0
+      const plain_text = decode_text(value.slice(cursor, start), textarea)
+      if (plain_text) segments.push({ text: plain_text })
+      const shifted_text = decode_text(match.groups?.inner ?? ``, textarea)
+      if (shifted_text) {
+        segments.push({
+          text: shifted_text,
+          shift: match.groups?.tag?.toLowerCase() === `sub` ? `sub` : `super`,
+        })
+      }
+      cursor = start + match[0].length
+    }
+    const tail_text = decode_text(value.slice(cursor), textarea)
+    if (tail_text) segments.push({ text: tail_text })
+    return segments
+  }
+
+  let use_svg_text = $derived(rotate && !options?.length && !loading)
+  let segments = $derived(use_svg_text ? label_segments(label) : [])
 </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}
+<g transform={rotate ? `rotate(-90, ${x}, ${y})` : undefined}>
+  {#if use_svg_text}
+    <text
       class="axis-label {axis_type}-label"
-    />
-  </div>
-</foreignObject>
+      dominant-baseline="central"
+      fill={color ?? `currentColor`}
+      pointer-events="none"
+      text-anchor="middle"
+      {x}
+      {y}
+    >
+      {#each segments as segment}
+        <tspan baseline-shift={segment.shift} font-size={segment.shift ? `75%` : undefined}
+          >{segment.text}</tspan
+        >
+      {/each}
+    </text>
+  {:else}
+    <foreignObject
+      x={x - width / 2}
+      y={y - AXIS_LABEL_CONTAINER.y_offset}
+      {width}
+      height={AXIS_LABEL_CONTAINER.height}
+      style="overflow: visible; pointer-events: none"
+    >
+      <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>
+  {/if}
+</g>

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

@@ -10,6 +10,7 @@ type $$ComponentProps = {
     loading?: boolean;
     axis_type: `x` | `x2` | `y` | `y2`;
     on_select?: (key: string) => void;
+    width?: number;
 };
 declare const AxisLabel: import("svelte").Component<$$ComponentProps, {}, "">;
 type AxisLabel = ReturnType<typeof AxisLabel>;