matterviz 0.4.0 → 0.4.1

package/dist/plot/box/BoxPlot.svelte

@@ -36,21 +36,17 @@
     has_explicit_position,
     measured_footprint,
     place_decorations,
+    placed_coords,
   } from '../core/auto-place'
   import { compute_box_stats } from './box-plot'
   import { gaussian_kde, type KdeResult } from './kde'
-  import { create_dimension_tracker, create_hover_lock } from '../core/hover-lock.svelte'
+  import { create_placed_tween } from '../core/placed-tween.svelte'
+  import { create_pan_zoom } from '../core/pan-zoom.svelte'
   import { create_legend_visibility } from '../core/utils/series-visibility'
   import {
     axis_ranges_equal,
-    get_relative_coords,
-    MIN_TOUCH_DISTANCE_PIXELS,
-    pan_range_by_pixels,
-    PINCH_ZOOM_THRESHOLD,
-    remove_drag_listeners,
+    invert_rect_range,
     resolve_axis_ranges,
-    sorted_range,
-    zoom_range_by_factor,
   } from '../core/interactions'
   import {
     calc_auto_padding,
@@ -68,14 +64,12 @@
     get_nice_data_range,
     get_tick_label,
   } from '../core/scales'
-  import type { InitialRanges } from '../core/types'
   import { DEFAULT_SERIES_COLORS } from '../core/types'
   import { unique_id } from '../core/utils'
   import { DEFAULTS } from '../../settings'
   import type { Snippet } from 'svelte'
   import { onDestroy, untrack } from 'svelte'
   import type { HTMLAttributes } from 'svelte/elements'
-  import { Tween, type TweenOptions } from 'svelte/motion'
   import { SvelteMap } from 'svelte/reactivity'
   import PlotTooltip from '../core/components/PlotTooltip.svelte'
   import { violin_path } from '../core/svg'
@@ -176,7 +170,7 @@
     outlier_style?: OutlierStyle
     whisker_mode?: WhiskerMode
     whisker_range?: number
-    whisker_percentiles?: [number, number]
+    whisker_percentiles?: Vec2
     show_outliers?: boolean
     show_mean?: boolean
     show_value_labels?: boolean
@@ -586,178 +580,46 @@
     x2_max: measure_max_tick_width(ticks.x2, x2_axis.format ?? ``),
   })
 
-  // === Interaction state (pan / zoom / touch) ===
-  let drag_state = $state<{
-    start: { x: number; y: number } | null
-    current: { x: number; y: number } | null
-    bounds: DOMRect | null
-  }>({ start: null, current: null, bounds: null })
-  let is_focused = $state(false)
-  let shift_held = $state(false)
-  let pan_drag_state = $state<InitialRanges & { start: { x: number; y: number } } | null>(null)
-  let touch_state = $state<InitialRanges & { start_touches: { x: number; y: number }[] } | null>(
-    null,
-  )
-
-  const on_window_mouse_move = (evt: MouseEvent) => {
-    if (!drag_state.start || !drag_state.bounds) return
-    drag_state.current = {
-      x: evt.clientX - drag_state.bounds.left,
-      y: evt.clientY - drag_state.bounds.top,
-    }
-  }
-  const on_window_mouse_up = () => {
-    if (drag_state.start && drag_state.current) {
-      const x1 = scales.x.invert(drag_state.start.x) as number
-      const x2 = scales.x.invert(drag_state.current.x) as number
-      const y1 = scales.y.invert(drag_state.start.y)
-      const y2 = scales.y.invert(drag_state.current.y)
-      const y2_1 = scales.y2.invert(drag_state.start.y)
-      const y2_2 = scales.y2.invert(drag_state.current.y)
-      const x2_1 = scales.x2.invert(drag_state.start.x) as number
-      const x2_2 = scales.x2.invert(drag_state.current.x) as number
-      const dx = Math.abs(drag_state.start.x - drag_state.current.x)
-      const dy = Math.abs(drag_state.start.y - drag_state.current.y)
-      if (dx > 5 && dy > 5 && Number.isFinite(x1) && Number.isFinite(x2)) {
-        x_axis = { ...x_axis, range: sorted_range(x1, x2) }
-        // the secondary value axis is x2 only in horizontal mode, y2 only in vertical
-        // (is_secondary keys off orientation); writing the off-orientation axis would
-        // store a phantom range from its [0, 1] sentinel scale into the bound prop
-        if (
-          has_secondary && orientation === `horizontal` &&
-          Number.isFinite(x2_1) && Number.isFinite(x2_2)
-        ) {
-          x2_axis_prop = { ...x2_axis_prop, range: sorted_range(x2_1, x2_2) }
-        }
-        y_axis = { ...y_axis, range: sorted_range(y1, y2) }
-        if (
-          has_secondary && orientation === `vertical` &&
-          Number.isFinite(y2_1) && Number.isFinite(y2_2)
-        ) {
-          y2_axis_prop = { ...y2_axis_prop, range: sorted_range(y2_1, y2_2) }
-        }
+  // Shared pan/zoom/touch/drag-rect interaction controller
+  const pan_zoom = create_pan_zoom({
+    ranges: () => ranges.current,
+    scale_type: (axis) => ({ x: x_axis, x2: x2_axis, y: y_axis, y2: y2_axis })[axis].scale_type,
+    plot_dims: () => ({ width: chart_width, height: chart_height }),
+    pan: () => pan,
+    set_range: (axis, range) => (ranges.current[axis] = range),
+    svg: () => svg_element,
+    on_rect_zoom: (start, current) => {
+      const next_x = invert_rect_range(scales.x, start.x, current.x)
+      if (!next_x) return
+      x_axis = { ...x_axis, range: next_x }
+      // the secondary value axis is x2 only in horizontal mode, y2 only in vertical
+      // (is_secondary keys off orientation); writing the off-orientation axis would
+      // store a phantom range from its [0, 1] sentinel scale into the bound prop
+      const next_x2 = has_secondary && orientation === `horizontal`
+        ? invert_rect_range(scales.x2, start.x, current.x)
+        : null
+      if (next_x2) x2_axis_prop = { ...x2_axis_prop, range: next_x2 }
+      const next_y = invert_rect_range(scales.y, start.y, current.y)
+      if (next_y) y_axis = { ...y_axis, range: next_y }
+      const next_y2 = has_secondary && orientation === `vertical`
+        ? invert_rect_range(scales.y2, start.y, current.y)
+        : null
+      if (next_y2) y2_axis_prop = { ...y2_axis_prop, range: next_y2 }
+    },
+    on_reset: () => {
+      ranges.current = {
+        x: [...ranges.initial.x] as Vec2,
+        x2: [...ranges.initial.x2] as Vec2,
+        y: [...ranges.initial.y] as Vec2,
+        y2: [...ranges.initial.y2] as Vec2,
       }
-    }
-    drag_state = { start: null, current: null, bounds: null }
-    window.removeEventListener(`mousemove`, on_window_mouse_move)
-    window.removeEventListener(`mouseup`, on_window_mouse_up)
-    document.body.style.cursor = `default`
-  }
-
-  // Pan/zoom all four axes from an interaction-start snapshot, each in its own
-  // scale's transform space (log axes pan by a constant factor, linear by a shift)
-  const pan_all_axes = (init: InitialRanges, dx_px: number, dy_px: number) => {
-    ranges.current.x = pan_range_by_pixels(init.initial_x_range, dx_px, chart_width, x_axis.scale_type)
-    ranges.current.x2 = pan_range_by_pixels(init.initial_x2_range, dx_px, chart_width, x2_axis.scale_type)
-    ranges.current.y = pan_range_by_pixels(init.initial_y_range, dy_px, chart_height, y_axis.scale_type)
-    ranges.current.y2 = pan_range_by_pixels(init.initial_y2_range, dy_px, chart_height, y2_axis.scale_type)
-  }
-  const zoom_all_axes = (init: InitialRanges, factor: number) => {
-    ranges.current.x = zoom_range_by_factor(init.initial_x_range, factor, x_axis.scale_type)
-    ranges.current.x2 = zoom_range_by_factor(init.initial_x2_range, factor, x2_axis.scale_type)
-    ranges.current.y = zoom_range_by_factor(init.initial_y_range, factor, y_axis.scale_type)
-    ranges.current.y2 = zoom_range_by_factor(init.initial_y2_range, factor, y2_axis.scale_type)
-  }
-
-  // Pan drag handler (drag direction inverted on x for natural pan feel)
-  const on_pan_move = (evt: MouseEvent) => {
-    if (!pan_drag_state) return
-    const sensitivity = pan?.drag_sensitivity ?? 1
-    pan_all_axes(
-      pan_drag_state,
-      -(evt.clientX - pan_drag_state.start.x) * sensitivity,
-      (evt.clientY - pan_drag_state.start.y) * sensitivity,
-    )
-  }
-  const on_pan_end = () => {
-    pan_drag_state = null
-    document.body.style.cursor = ``
-    window.removeEventListener(`mousemove`, on_pan_move)
-    window.removeEventListener(`mouseup`, on_pan_end)
-  }
-
-  // Tear down any window listeners + cursor override if the component unmounts mid-drag
-  // (mouseup/panend would otherwise never fire, leaking listeners and a stuck cursor).
-  // onDestroy also runs during SSR teardown, where window/document don't exist.
-  onDestroy(() => {
-    remove_drag_listeners([on_window_mouse_move, on_pan_move], [on_window_mouse_up, on_pan_end])
-    drag_state = { start: null, current: null, bounds: null }
-    pan_drag_state = null
+      x_axis = { ...x_axis, range: [null, null] }
+      x2_axis_prop = { ...x2_axis_prop, range: [null, null] }
+      y_axis = { ...y_axis, range: [null, null] }
+      y2_axis_prop = { ...y2_axis_prop, range: [null, null] }
+    },
   })
-
-  function handle_mouse_down(evt: MouseEvent) {
-    const coords = get_relative_coords(evt)
-    if (!coords || !svg_element) return
-    const pan_enabled = pan?.enabled !== false
-    if (pan_enabled && evt.shiftKey) {
-      evt.preventDefault()
-      pan_drag_state = {
-        start: { x: evt.clientX, y: evt.clientY },
-        initial_x_range: [...ranges.current.x] as Vec2,
-        initial_x2_range: [...ranges.current.x2] as Vec2,
-        initial_y_range: [...ranges.current.y] as Vec2,
-        initial_y2_range: [...ranges.current.y2] as Vec2,
-      }
-      document.body.style.cursor = `grabbing`
-      window.addEventListener(`mousemove`, on_pan_move)
-      window.addEventListener(`mouseup`, on_pan_end)
-      return
-    }
-    drag_state = { start: coords, current: coords, bounds: svg_element.getBoundingClientRect() }
-    window.addEventListener(`mousemove`, on_window_mouse_move)
-    window.addEventListener(`mouseup`, on_window_mouse_up)
-    evt.preventDefault()
-  }
-
-  function handle_wheel(evt: WheelEvent) {
-    const pan_enabled = pan?.enabled !== false
-    if (!pan_enabled || !is_focused || !shift_held) return
-    evt.preventDefault()
-    const sensitivity = pan?.wheel_sensitivity ?? 1
-    if (Math.abs(evt.deltaX) > Math.abs(evt.deltaY)) {
-      const dx = evt.deltaX * sensitivity
-      ranges.current.x = pan_range_by_pixels(ranges.current.x, dx, chart_width, x_axis.scale_type)
-      ranges.current.x2 = pan_range_by_pixels(ranges.current.x2, dx, chart_width, x2_axis.scale_type)
-    } else {
-      const dy = evt.deltaY * sensitivity
-      ranges.current.y = pan_range_by_pixels(ranges.current.y, dy, chart_height, y_axis.scale_type)
-      ranges.current.y2 = pan_range_by_pixels(ranges.current.y2, dy, chart_height, y2_axis.scale_type)
-    }
-  }
-
-  function handle_touch_start(evt: TouchEvent) {
-    const touch_enabled = pan?.enabled !== false && pan?.touch_enabled !== false
-    if (!touch_enabled || evt.touches.length !== 2) return
-    evt.preventDefault()
-    const touches = Array.from(evt.touches)
-    touch_state = {
-      start_touches: touches.map((touch) => ({ x: touch.clientX, y: touch.clientY })),
-      initial_x_range: [...ranges.current.x] as Vec2,
-      initial_x2_range: [...ranges.current.x2] as Vec2,
-      initial_y_range: [...ranges.current.y] as Vec2,
-      initial_y2_range: [...ranges.current.y2] as Vec2,
-    }
-  }
-  function handle_touch_move(evt: TouchEvent) {
-    if (!touch_state || evt.touches.length !== 2) return
-    evt.preventDefault()
-    const [t1, t2] = Array.from(evt.touches)
-    const [s1, s2] = touch_state.start_touches
-    const start_center = { x: (s1.x + s2.x) / 2, y: (s1.y + s2.y) / 2 }
-    const curr_center = { x: (t1.clientX + t2.clientX) / 2, y: (t1.clientY + t2.clientY) / 2 }
-    const dx = curr_center.x - start_center.x
-    const dy = curr_center.y - start_center.y
-    const start_dist = Math.hypot(s2.x - s1.x, s2.y - s1.y)
-    // ignore near-coincident touches so curr_dist / start_dist can't blow up the scale
-    if (start_dist < MIN_TOUCH_DISTANCE_PIXELS) return
-    const curr_dist = Math.hypot(t2.clientX - t1.clientX, t2.clientY - t1.clientY)
-    const scale = curr_dist / start_dist
-    // Pinch zoom about the view center (spread = zoom in, pinch = zoom out)
-    if (Math.abs(scale - 1) > PINCH_ZOOM_THRESHOLD && scale > Number.EPSILON) {
-      zoom_all_axes(touch_state, scale)
-    } else pan_all_axes(touch_state, -dx, dy)
-  }
-  const handle_touch_end = () => (touch_state = null)
+  onDestroy(() => pan_zoom.destroy())
 
   // === Legend ===
   let legend_data = $derived<LegendItem[]>(
@@ -787,10 +649,6 @@
   })
 
   let hovered_legend_series_idx = $state<number | null>(null)
-  const legend_hover = create_hover_lock()
-  const dim_tracker = create_dimension_tracker()
-  let has_initial_legend_placement = $state(false)
-  $effect(() => () => legend_hover.cleanup())
 
   let legend_placement = $derived.by(() => {
     if (!should_show_legend || !width || !height) return null
@@ -804,24 +662,13 @@
     })
   })
 
-  const tweened_legend_coords = new Tween(
-    { x: 0, y: 0 },
-    untrack(() => ({ duration: 400, ...legend?.tween })),
-  )
-  $effect(() => {
-    if (!width || !height || !legend_placement) return
-    const dims_changed = dim_tracker.has_changed(width, height)
-    if (dims_changed) dim_tracker.update(width, height)
-    const is_responsive = legend?.responsive ?? false
-    const should_update = dims_changed ||
-      (!legend_hover.is_locked.current && (is_responsive || !has_initial_legend_placement))
-    if (should_update) {
-      tweened_legend_coords.set(
-        { x: legend_placement.x, y: legend_placement.y },
-        has_initial_legend_placement ? undefined : { duration: 0 },
-      )
-      if (legend_element) has_initial_legend_placement = true
-    }
+  // Tweened legend coordinates with shared placement stability gating
+  const legend_tween = create_placed_tween({
+    placement: () => legend_placement,
+    dims: () => ({ width, height }),
+    responsive: () => legend?.responsive ?? false,
+    element: () => legend_element,
+    tween: () => legend?.tween,
   })
 
   // === Tooltip / hover ===
@@ -882,8 +729,8 @@
 </script>
 
 {#snippet seg(
-  p1: [number, number],
-  p2: [number, number],
+  p1: Vec2,
+  p2: Vec2,
   stroke: string,
   sw: number,
   dash?: string,
@@ -933,11 +780,9 @@
       evt.preventDefault()
       fullscreen = false
     }
-    if (evt.key === `Shift`) shift_held = true
-  }}
-  onkeyup={(evt) => {
-    if (evt.key === `Shift`) shift_held = false
+    pan_zoom.on_window_key_down(evt)
   }}
+  onkeyup={pan_zoom.on_window_key_up}
 />
 
 <div
@@ -963,37 +808,25 @@
       aria-label={rest[`aria-label`] ??
       ([x_axis.label, y_axis.label].filter(Boolean).join(` vs `) || `Box plot`)}
       tabindex="0"
-      onfocusin={() => (is_focused = true)}
-      onfocusout={() => (is_focused = false)}
-      onmousedown={handle_mouse_down}
-      ondblclick={() => {
-        ranges.current.x = [...ranges.initial.x] as Vec2
-        ranges.current.x2 = [...ranges.initial.x2] as Vec2
-        ranges.current.y = [...ranges.initial.y] as Vec2
-        ranges.current.y2 = [...ranges.initial.y2] as Vec2
-        x_axis = { ...x_axis, range: [null, null] }
-        x2_axis_prop = { ...x2_axis_prop, range: [null, null] }
-        y_axis = { ...y_axis, range: [null, null] }
-        y2_axis_prop = { ...y2_axis_prop, range: [null, null] }
-      }}
+      onfocusin={() => pan_zoom.set_focused(true)}
+      onfocusout={() => pan_zoom.set_focused(false)}
+      onmousedown={pan_zoom.on_mouse_down}
+      ondblclick={pan_zoom.reset_view}
+      onkeydown={pan_zoom.on_key_down}
       onmouseleave={() => {
         hovered = false
         hover_info = null
         change(null)
         on_box_hover?.(null)
       }}
-      onwheel={handle_wheel}
-      ontouchstart={handle_touch_start}
-      ontouchmove={handle_touch_move}
-      ontouchend={handle_touch_end}
-      ontouchcancel={handle_touch_end}
-      style:cursor={pan_drag_state
-      ? `grabbing`
-      : shift_held && pan?.enabled !== false
-      ? `grab`
-      : `crosshair`}
+      onwheel={pan_zoom.on_wheel}
+      ontouchstart={pan_zoom.on_touch_start}
+      ontouchmove={pan_zoom.on_touch_move}
+      ontouchend={pan_zoom.on_touch_end}
+      ontouchcancel={pan_zoom.on_touch_end}
+      style:cursor={pan_zoom.cursor}
     >
-      <ZoomRect start={drag_state.start} current={drag_state.current} />
+      <ZoomRect start={pan_zoom.drag_start} current={pan_zoom.drag_current} />
 
       {@render user_content?.({
         height,
@@ -1144,7 +977,7 @@
             {@const v_wl = val_scale(stats.whisker_low)}
             {@const v_wh = val_scale(stats.whisker_high)}
             {@const v_mean = val_scale(stats.mean)}
-            {@const pt = (cross: number, val: number): [number, number] =>
+            {@const pt = (cross: number, val: number): Vec2 =>
             vertical ? [cross, val] : [val, cross]}
             {@const [q1x, q1y] = pt(c_lo, v_q1)}
             {@const [q3x, q3y] = pt(c_hi, v_q3)}
@@ -1290,16 +1123,13 @@
     </svg>
 
     {#if legend && should_show_legend}
-      {@const legend_left = legend_auto_outside
-      ? legend_outside_x
-      : legend_placement
-      ? tweened_legend_coords.current.x
-      : pad.l + 10}
-      {@const legend_top = legend_auto_outside
-      ? legend_outside_y
-      : legend_placement
-      ? tweened_legend_coords.current.y
-      : pad.t + 10}
+      {@const legend_pos = placed_coords(
+      legend_auto_outside,
+      { x: legend_outside_x, y: legend_outside_y },
+      legend_placement,
+      legend_tween.coords.current,
+      { x: pad.l + 10, y: pad.t + 10 },
+    )}
       <PlotLegend
         bind:root_element={legend_element}
         {...legend}
@@ -1307,13 +1137,13 @@
         on_toggle={legend?.on_toggle ?? legend_vis.on_toggle}
         on_group_toggle={legend?.on_group_toggle ?? legend_vis.on_group_toggle}
         on_double_click={legend?.on_double_click ?? legend_vis.on_double_click}
-        on_hover_change={legend_hover.set_locked}
+        on_hover_change={legend_tween.set_locked}
         on_item_hover={(item) =>
           (hovered_legend_series_idx = item != null && item.series_idx >= 0
             ? item.series_idx
             : null)}
         active_series_idx={hover_info?.series_idx ?? hovered_legend_series_idx}
-        style={`position: absolute; left: ${legend_left}px; top: ${legend_top}px; pointer-events: auto; ${
+        style={`position: absolute; left: ${legend_pos.x}px; top: ${legend_pos.y}px; pointer-events: auto; ${
           legend?.style || ``
         }`}
       />

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

@@ -1,3 +1,4 @@
+import type { Vec2 } from '../../math';
 import type { BandwidthOption, BasePlotProps, BoxHandlerProps, BoxPlotSeries, LegendConfig, Orientation, PanConfig, PlotConfig, RefLine, RefLineEvent, UserContentProps, ViolinKind, ViolinSide, WhiskerMode } from '..';
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
@@ -30,7 +31,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;
@@ -71,7 +72,7 @@ declare function $$render<Metadata extends Record<string, unknown> = Record<stri
         pan?: PanConfig;
     };
     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 +80,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;

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,7 @@
 // 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';
 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);
@@ -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,7 +1,10 @@
 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 ?? ``);

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

@@ -59,7 +59,7 @@
     wrapper_style?: string
     tick_labels?: (string | number)[] | number
     tick_format?: string
-    range?: [number, number]
+    range?: Vec2
     // tick_side determines tick placement relative to orientation:
     // 'primary'   = bottom (horizontal) / right (vertical), outside bar
     // 'secondary' = top (horizontal) / left (vertical), outside bar
@@ -72,18 +72,18 @@
     steps?: number
     // computed "nice" range resulting from snapping ticks
     // https://github.com/d3/d3-scale/issues/86
-    nice_range?: [number, number]
+    nice_range?: Vec2
     // type of scale to use for ticks and potentially color (if color_scale_fn not provided)
     scale_type?: ScaleType
     // Optional pre-configured d3 color scale function
     color_scale_fn?: (value: number) => string
     // Optional domain for pre-configured color scale function
-    color_scale_domain?: [number, number]
+    color_scale_domain?: Vec2
     // Property selection options (makes title interactive)
     property_options?: AxisOption[]
     selected_property_key?: string
     data_loader?: ColorBarDataLoaderFn
-    on_property_change?: (key: string, range: [number, number]) => void
+    on_property_change?: (key: string, range: Vec2) => void
     // Color scale selection options
     color_scale_options?: ColorScaleOption[]
     selected_color_scale_key?: string
@@ -301,7 +301,7 @@
     // Use potentially adjusted min/max for domain (ascending)
     const lo = Math.min(min_val, max_val)
     const hi = Math.max(min_val, max_val)
-    const domain_for_scale: [number, number] = [lo, hi]
+    const domain_for_scale: Vec2 = [lo, hi]
 
     // For arcsinh, create a custom color scale
     if (type_name === `arcsinh`) {