matterviz 0.3.4 → 0.3.6

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

@@ -0,0 +1,119 @@
+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

@@ -0,0 +1,425 @@
+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
+}