matterviz 0.3.6 → 0.4.0

package/dist/src/lib/plot/interactions.ts

@@ -1,119 +0,0 @@
-import type { Point2D, Vec2 } from '$lib/math'
-import type { Y2SyncConfig, Y2SyncMode } from './types'
-
-// Get relative coordinates from a mouse event
-export function get_relative_coords(evt: MouseEvent): Point2D | null {
-  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: Y2SyncConfig | Y2SyncMode | undefined): Y2SyncConfig {
-  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: Vec2[]) =>
-  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: Vec2, y2_base_range: Vec2, sync: Y2SyncConfig): Vec2 {
-  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: Vec2, delta: number): Vec2 => [
-  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: number,
-  data_range: Vec2,
-  pixel_range: number,
-): number {
-  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]: Vec2) => 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: Vec2,
-  new_range: Vec2,
-): { range: Vec2; changed: boolean } {
-  // 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/src/lib/plot/layout.ts

@@ -1,425 +0,0 @@
-import { format_value } from '$lib/labels'
-import { euclidean_dist } from '$lib/math'
-import type { AxisConfig } from './types'
-
-export type Sides = { t?: number; b?: number; l?: number; r?: number }
-
-// Default gap between tick labels and axis labels
-export const LABEL_GAP_DEFAULT = 30
-
-// Filter undefined values from padding to prevent overriding defaults when spreading
-// Guards against undefined/null padding inputs (common for optional props)
-export const filter_padding = (
-  padding: Partial<Sides> | undefined | null,
-  defaults: Required<Sides>,
-): Required<Sides> =>
-  ({
-    ...defaults,
-    ...Object.fromEntries(Object.entries(padding ?? {}).filter(([, v]) => v !== undefined)),
-  }) as Required<Sides>
-
-// Measure text width using canvas (singleton pattern for performance)
-let measurement_canvas: HTMLCanvasElement | null = null
-
-export function measure_text_width(text: string, font: string = `12px sans-serif`) {
-  if (typeof document === `undefined`) return 0
-  measurement_canvas ??= document.createElement(`canvas`)
-  const ctx = measurement_canvas.getContext(`2d`)
-  if (!ctx) return 0
-  ctx.font = font
-  return ctx.measureText(text).width
-}
-
-// Measure an element's full visual footprint, including descendants that overflow its
-// offset box. Colorbar tick labels are position:absolute outside the bar, so
-// offsetWidth/offsetHeight underestimate the space they actually occupy — which lets
-// auto-placement put the colorbar where its labels overlap the axes.
-export function measure_full_footprint(el: HTMLElement): { width: number; height: number } {
-  const root = el.getBoundingClientRect()
-  let right = root.right
-  let bottom = root.bottom
-  for (const child of el.querySelectorAll(`*`)) {
-    const rect = child.getBoundingClientRect()
-    if (rect.width === 0 && rect.height === 0) continue
-    right = Math.max(right, rect.right)
-    bottom = Math.max(bottom, rect.bottom)
-  }
-  return { width: right - root.left, height: bottom - root.top }
-}
-
-// Calculate auto-adjusted padding based on tick label widths/heights
-// This ensures tick labels don't overlap with axis labels
-export interface AutoPaddingConfig {
-  padding: Partial<Sides> // User padding (undefined sides will be auto-calculated)
-  default_padding: Required<Sides> // Default padding to use as baseline
-  x2_axis?: AxisConfig & { tick_values?: (string | number)[] }
-  y_axis?: AxisConfig & { tick_values?: (string | number)[] }
-  y2_axis?: AxisConfig & { tick_values?: (string | number)[] }
-  label_gap?: number // Gap between tick labels and axis labels (default: LABEL_GAP_DEFAULT)
-}
-
-// Measure the widest formatted tick label. Used for auto-padding and label placement.
-export const measure_max_tick_width = (ticks: (string | number)[], format: string = ``) =>
-  ticks.length === 0
-    ? 0
-    : Math.max(
-        ...ticks.map((tick) => {
-          const label = typeof tick === `string` ? tick : format_value(tick, format)
-          return measure_text_width(label, `12px sans-serif`)
-        }),
-      )
-
-// Estimated height of a single tick label line (font-size 0.8em ≈ 12px + leading)
-export const TICK_LABEL_HEIGHT = 16
-// Estimated height of an axis label (font-size ~14px + margin)
-export const AXIS_LABEL_HEIGHT = 20
-
-export const calc_auto_padding = ({
-  padding,
-  default_padding,
-  x2_axis = {},
-  y_axis = {},
-  y2_axis = {},
-  label_gap = LABEL_GAP_DEFAULT,
-}: AutoPaddingConfig): Required<Sides> => {
-  const x2_ticks = x2_axis.tick_values ?? []
-  const y_ticks = y_axis.tick_values ?? []
-  const y_format = y_axis.format ?? ``
-  const y2_ticks = y2_axis.tick_values ?? []
-  const y2_format = y2_axis.format ?? ``
-
-  return {
-    t:
-      padding.t ??
-      (x2_ticks.length > 0
-        ? Math.max(
-            default_padding.t,
-            TICK_LABEL_HEIGHT + label_gap + (x2_axis.label ? AXIS_LABEL_HEIGHT : 0),
-          )
-        : default_padding.t),
-    b: padding.b ?? default_padding.b,
-    l:
-      padding.l ??
-      Math.max(default_padding.l, measure_max_tick_width(y_ticks, y_format) + label_gap),
-    r:
-      padding.r ??
-      Math.max(default_padding.r, measure_max_tick_width(y2_ticks, y2_format) + label_gap),
-  }
-}
-
-// Constrain tooltip position within bounds, flipping to opposite side if overflow
-// offset_x/offset_y control initial positioning: positive = right/down, negative = left/up
-export function constrain_tooltip_position(
-  cursor_x: number,
-  cursor_y: number,
-  tooltip_width: number,
-  tooltip_height: number,
-  viewport_width: number,
-  viewport_height: number,
-  options: { offset?: number; offset_x?: number; offset_y?: number } = {},
-): { x: number; y: number } {
-  const { offset = 10 } = options
-  const offset_x = options.offset_x ?? offset
-  const offset_y = options.offset_y ?? offset
-
-  // Position to left of cursor if right-side placement overflows (and vice versa)
-  const flip_x =
-    offset_x >= 0
-      ? cursor_x + offset_x + tooltip_width > viewport_width
-      : cursor_x + offset_x - tooltip_width < 0
-  // Position above cursor if bottom placement overflows (and vice versa)
-  const flip_y =
-    offset_y >= 0
-      ? cursor_y + offset_y + tooltip_height > viewport_height
-      : cursor_y + offset_y - tooltip_height < 0
-
-  // Calculate position: apply offset, flip if needed
-  const abs_offset_x = Math.abs(offset_x)
-  const abs_offset_y = Math.abs(offset_y)
-
-  // Determine X position based on preferred side and flip state
-  let raw_x: number
-  if (offset_x >= 0) {
-    // Prefer right side: flip to left if overflows
-    raw_x = flip_x ? cursor_x - abs_offset_x - tooltip_width : cursor_x + abs_offset_x
-  } else {
-    // Prefer left side: flip to right if overflows
-    raw_x = flip_x ? cursor_x + abs_offset_x : cursor_x - abs_offset_x - tooltip_width
-  }
-
-  // Determine Y position based on preferred side and flip state
-  let raw_y: number
-  if (offset_y >= 0) {
-    // Prefer bottom: flip to top if overflows
-    raw_y = flip_y ? cursor_y - abs_offset_y - tooltip_height : cursor_y + abs_offset_y
-  } else {
-    // Prefer top: flip to bottom if overflows
-    raw_y = flip_y ? cursor_y + abs_offset_y : cursor_y - abs_offset_y - tooltip_height
-  }
-
-  // Clamp to viewport bounds
-  const x_pos = Math.max(0, Math.min(raw_x, viewport_width - tooltip_width))
-  const y_pos = Math.max(0, Math.min(raw_y, viewport_height - tooltip_height))
-  return { x: x_pos, y: y_pos }
-}
-
-// Continuous placement algorithm with grid sampling and overlap scoring
-// Finds the optimal position for a legend/colorbar by sampling a grid of candidates
-// and scoring each by data point overlap and distance to exclusion zones
-
-// Common rectangle type for consistency
-export interface Rect {
-  x: number
-  y: number
-  width: number
-  height: number
-}
-
-export const pad_rect = (rect: Rect, padding: number): Rect => ({
-  x: rect.x - padding,
-  y: rect.y - padding,
-  width: rect.width + 2 * padding,
-  height: rect.height + 2 * padding,
-})
-
-export const centered_rect = (
-  center_x: number,
-  top_y: number,
-  width: number,
-  height: number,
-): Rect => ({
-  x: center_x - width / 2,
-  y: top_y,
-  width,
-  height,
-})
-
-export const rect_within_rect = (rect: Rect, bounds: Rect): boolean =>
-  rect.x >= bounds.x &&
-  rect.x + rect.width <= bounds.x + bounds.width &&
-  rect.y >= bounds.y &&
-  rect.y + rect.height <= bounds.y + bounds.height
-
-export interface ElementPlacementConfig {
-  // Bounds of the plot area (in SVG coordinates)
-  plot_bounds: Rect
-  // Fallback size of the element to place (used before `element` first renders)
-  element_size: { width: number; height: number }
-  // Element to place. When provided and laid out, its full visual footprint
-  // (including descendants that overflow the box, e.g. colorbar tick labels) is
-  // measured and overrides element_size — keeping placement overlap-free everywhere.
-  element?: HTMLElement | null
-  // Minimum distance from plot edges to avoid axis label overlap (default: 12)
-  axis_clearance?: number
-  // Rectangles to avoid (e.g., already-placed legend when placing colorbar)
-  exclude_rects?: Rect[]
-  // Data points to avoid overlapping
-  points: { x: number; y: number }[]
-  // Number of samples per axis (default: 10, meaning 10x10 = 100 candidates)
-  grid_resolution?: number
-}
-
-export interface ElementPlacementResult {
-  x: number
-  y: number
-  score: number // Higher is better (fewer overlaps, farther from points)
-}
-
-// Scoring constants
-const EXCLUSION_PENALTY = 1000
-const DISTANCE_WEIGHT = 0.001
-// Strong corner preference: corners can have 3-4 more overlapping points and still win
-const CORNER_WEIGHT = 5.0
-const MAX_SAMPLE_POINTS = 500
-
-// Check if a point is inside a rectangle
-const point_in_rect = (point: { x: number; y: number }, rect: Rect): boolean =>
-  point.x >= rect.x &&
-  point.x <= rect.x + rect.width &&
-  point.y >= rect.y &&
-  point.y <= rect.y + rect.height
-
-// Check if two rectangles overlap
-export const rects_overlap = (r1: Rect, r2: Rect): boolean =>
-  !(
-    r1.x + r1.width <= r2.x ||
-    r2.x + r2.width <= r1.x ||
-    r1.y + r1.height <= r2.y ||
-    r2.y + r2.height <= r1.y
-  )
-
-// Build placement obstacles for one series' pixel-space polyline. Always includes the finite
-// vertices; when the series draws a connecting line, also walks each segment between
-// consecutive finite vertices at ~step px so legend/colorbar auto-placement avoids the line,
-// not just sparse markers (e.g. a steep y=x^2 line has few markers but a long visible segment).
-export function sample_series_obstacle_points(
-  pixel_points: { x: number; y: number }[],
-  draws_line: boolean,
-  step: number,
-): { x: number; y: number }[] {
-  const obstacles: { x: number; y: number }[] = []
-  let prev: { x: number; y: number } | null = null
-  for (const point of pixel_points) {
-    if (!isFinite(point.x) || !isFinite(point.y)) {
-      prev = null // non-finite breaks the line; don't sample across the gap
-      continue
-    }
-    obstacles.push(point)
-    if (draws_line && prev && step > 0) {
-      const n_samples = Math.floor(Math.hypot(point.x - prev.x, point.y - prev.y) / step)
-      for (let idx = 1; idx < n_samples; idx++) {
-        const frac = idx / n_samples
-        obstacles.push({
-          x: prev.x + (point.x - prev.x) * frac,
-          y: prev.y + (point.y - prev.y) * frac,
-        })
-      }
-    }
-    prev = point
-  }
-  return obstacles
-}
-
-// Find the best placement position using continuous grid sampling
-// Scores each candidate position by:
-// 1. Number of data points overlapping the element bounds (fewer = better)
-// 2. Overlap with exclusion rectangles (heavy penalty)
-// 3. Distance to nearest point (tie-breaker, farther = better)
-export function compute_element_placement(
-  config: ElementPlacementConfig,
-): ElementPlacementResult {
-  const {
-    plot_bounds,
-    element_size,
-    element,
-    axis_clearance = 12,
-    exclude_rects = [],
-    points,
-    grid_resolution: raw_resolution = 10,
-  } = config
-
-  // Ensure grid_resolution >= 2 to avoid division by zero in step calculation
-  const grid_resolution = Math.max(2, raw_resolution)
-
-  // Measure the element's full footprint (incl. descendants that overflow its box,
-  // such as colorbar tick labels) once it's laid out; fall back to element_size before
-  // first render. Centralizing this keeps every plot's auto-placement overlap-free.
-  const { width: elem_width, height: elem_height } =
-    element?.offsetWidth && element?.offsetHeight
-      ? measure_full_footprint(element)
-      : element_size
-
-  // Calculate valid placement region (plot bounds minus axis clearance)
-  const valid_x_min = plot_bounds.x + axis_clearance
-  const valid_y_min = plot_bounds.y + axis_clearance
-  const valid_x_max = plot_bounds.x + plot_bounds.width - axis_clearance - elem_width
-  const valid_y_max = plot_bounds.y + plot_bounds.height - axis_clearance - elem_height
-
-  // Handle case where element is too large for the valid region
-  const effective_x_min = Math.min(valid_x_min, valid_x_max)
-  const effective_x_max = Math.max(valid_x_min, valid_x_max)
-  const effective_y_min = Math.min(valid_y_min, valid_y_max)
-  const effective_y_max = Math.max(valid_y_min, valid_y_max)
-
-  // Subsample points for performance
-  const sampled_points =
-    points.length > MAX_SAMPLE_POINTS
-      ? Array.from(
-          { length: MAX_SAMPLE_POINTS },
-          (_, idx) => points[Math.floor((idx * points.length) / MAX_SAMPLE_POINTS)],
-        )
-      : points
-
-  let best_result: ElementPlacementResult = {
-    x: effective_x_min,
-    y: effective_y_min,
-    score: -Infinity,
-  }
-
-  // Sample candidate positions on a grid
-  const x_step =
-    effective_x_max > effective_x_min
-      ? (effective_x_max - effective_x_min) / (grid_resolution - 1)
-      : 0
-  const y_step =
-    effective_y_max > effective_y_min
-      ? (effective_y_max - effective_y_min) / (grid_resolution - 1)
-      : 0
-
-  // Precompute plot corners (constant across all candidates)
-  const plot_left = plot_bounds.x + axis_clearance
-  const plot_right = plot_bounds.x + plot_bounds.width - axis_clearance
-  const plot_top = plot_bounds.y + axis_clearance
-  const plot_bottom = plot_bounds.y + plot_bounds.height - axis_clearance
-  const max_corner_dist = euclidean_dist([plot_left, plot_top], [plot_right, plot_bottom])
-
-  for (let grid_x = 0; grid_x < grid_resolution; grid_x++) {
-    for (let grid_y = 0; grid_y < grid_resolution; grid_y++) {
-      const cand_x = effective_x_min + grid_x * x_step
-      const cand_y = effective_y_min + grid_y * y_step
-      const cand_rect: Rect = {
-        x: cand_x,
-        y: cand_y,
-        width: elem_width,
-        height: elem_height,
-      }
-
-      // Check for overlap with exclusion rectangles first (early rejection)
-      let exclusion_penalty = 0
-      for (const excl_rect of exclude_rects) {
-        if (rects_overlap(cand_rect, excl_rect)) {
-          exclusion_penalty += EXCLUSION_PENALTY
-        }
-      }
-
-      // Count points overlapping this candidate position
-      let overlap_count = 0
-      let min_distance_sq = Infinity
-      const center_x = cand_x + elem_width / 2
-      const center_y = cand_y + elem_height / 2
-
-      for (const point of sampled_points) {
-        if (point_in_rect(point, cand_rect)) {
-          overlap_count++
-        }
-        // Track distance to nearest point for tie-breaking
-        const dx = point.x - center_x
-        const dy = point.y - center_y
-        const dist_sq = dx * dx + dy * dy
-        if (dist_sq < min_distance_sq) {
-          min_distance_sq = dist_sq
-        }
-      }
-
-      // Score: fewer overlaps = better (less negative)
-      // Add small distance bonus for tie-breaking
-      // When no points exist, min_distance_sq stays Infinity - treat as 0 (no distance bonus)
-      const min_distance = min_distance_sq === Infinity ? 0 : Math.sqrt(min_distance_sq)
-
-      // Corner preference: use element's actual corner (not center) for distance
-      // This ensures a wide element at the left edge gets proper corner credit
-      const elem_right = cand_x + element_size.width
-      const elem_bottom = cand_y + element_size.height
-
-      // Distance from element's matching corner to each plot corner
-      const min_corner_dist = Math.min(
-        euclidean_dist([cand_x, cand_y], [plot_left, plot_top]), // top-left
-        euclidean_dist([elem_right, cand_y], [plot_right, plot_top]), // top-right
-        euclidean_dist([cand_x, elem_bottom], [plot_left, plot_bottom]), // bottom-left
-        euclidean_dist([elem_right, elem_bottom], [plot_right, plot_bottom]), // bottom-right
-      )
-      // Higher bonus for positions closer to corners (0 = at corner, 1 = far from all)
-      const corner_bonus =
-        max_corner_dist > 0 ? (1 - min_corner_dist / max_corner_dist) * CORNER_WEIGHT : 0
-
-      const score =
-        -overlap_count + min_distance * DISTANCE_WEIGHT + corner_bonus - exclusion_penalty
-
-      if (score > best_result.score) {
-        best_result = { x: cand_x, y: cand_y, score }
-      }
-    }
-  }
-
-  return best_result
-}