matterviz 0.3.4 → 0.3.6

package/dist/src/lib/plot/data-transform.ts

@@ -0,0 +1,69 @@
+import type { D3SymbolName } from '$lib/labels'
+import type { DataSeries, Point } from '$lib/plot'
+import { DEFAULT_SERIES_COLORS, DEFAULT_SERIES_SYMBOLS } from '$lib/plot/types'
+import { DEFAULTS } from '$lib/settings'
+
+// Get auto-cycling color for series at given index (wraps every 10)
+export const get_series_color = (series_idx: number): string =>
+  DEFAULT_SERIES_COLORS[series_idx % DEFAULT_SERIES_COLORS.length]
+
+// Get auto-cycling symbol for series at given index (wraps every 7)
+export const get_series_symbol = (series_idx: number): D3SymbolName =>
+  DEFAULT_SERIES_SYMBOLS[series_idx % DEFAULT_SERIES_SYMBOLS.length]
+
+// Extract the primary color from a series data object.
+// Checks line stroke, then point fill (handling arrays), with fallback to default blue.
+export const extract_series_color = (series_data: DataSeries): string =>
+  series_data.line_style?.stroke ||
+  (Array.isArray(series_data.point_style)
+    ? series_data.point_style[0]?.fill
+    : series_data.point_style?.fill) ||
+  `#4A9EFF`
+
+// Prepare legend data from series array
+export const prepare_legend_data = (
+  series: DataSeries[],
+): {
+  series_idx: number
+  label: string
+  visible: boolean
+  display_style: { symbol_type: D3SymbolName; symbol_color: string }
+}[] =>
+  series.map((series_data, series_idx) => ({
+    series_idx,
+    label: series_data.label ?? `Series ${series_idx + 1}`,
+    visible: series_data.visible ?? true,
+    display_style: {
+      // Prefer the series’ symbol when present, falling back to settings
+      symbol_type: !Array.isArray(series_data.point_style)
+        ? (series_data.point_style?.symbol_type ?? DEFAULTS.scatter.symbol_type)
+        : DEFAULTS.scatter.symbol_type,
+      symbol_color: extract_series_color(series_data),
+    },
+  }))
+
+// Create data points from series for analysis
+export const create_data_points = (
+  series: DataSeries[],
+  filter_fn?: (series: DataSeries) => boolean,
+): Point[] =>
+  series
+    .filter(filter_fn ?? ((srs) => srs.visible ?? true))
+    .flatMap(({ x: xs, y: ys }, series_idx) => {
+      const length = Math.min(xs.length, ys.length)
+      if (xs.length !== ys.length) {
+        console.warn(
+          `length mismatch in series ${series_idx}: x.length=${xs.length} vs y.length=${ys.length}`,
+        )
+      }
+      return xs.slice(0, length).map((x, idx) => ({ x, y: ys[idx] }))
+    })
+
+// Process array or scalar properties for indexed access.
+// If prop is an array, returns the element at the given index.
+// If prop is a scalar, returns the scalar (applied to all indices).
+// Returns undefined if prop is null/undefined.
+export function process_prop<T>(prop: T[] | T | undefined | null, idx: number): T | undefined {
+  if (prop == null) return undefined
+  return Array.isArray(prop) ? prop[idx] : prop
+}

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

@@ -0,0 +1,9 @@
+// Shared axis defaults across plot components (single source of truth)
+export const AXIS_DEFAULTS = {
+  format: ``,
+  scale_type: `linear` as const,
+  ticks: 5,
+  label_shift: { x: 0, y: 0 },
+  tick: { label: { shift: { x: 0, y: 0 }, inside: false } },
+  range: [null, null] as [number | null, number | null],
+}

package/dist/src/lib/plot/fill-utils.ts

@@ -0,0 +1,494 @@
+// Fill-between utility functions for ScatterPlot fill regions
+// Handles interpolation, boundary resolution, and path generation
+
+import type { CurveFactory } from 'd3-shape'
+import {
+  area,
+  curveBasis,
+  curveCardinal,
+  curveCatmullRom,
+  curveLinear,
+  curveMonotoneX,
+  curveMonotoneY,
+  curveNatural,
+  curveStep,
+  curveStepAfter,
+  curveStepBefore,
+} from 'd3-shape'
+import type {
+  DataSeries,
+  ErrorBand,
+  FillBoundary,
+  FillCurveType,
+  FillGradient,
+  FillRegion,
+  ScaleType,
+} from './types'
+
+// Epsilon value for log scale clamping (to avoid log(0) = -Infinity)
+export const LOG_EPSILON = 1e-10
+
+// Data point type for fill path generation
+export interface FillPathPoint {
+  x: number
+  y1: number
+  y2: number
+}
+
+type FillPathArrays = Record<keyof FillPathPoint, number[]>
+
+// Result type for interpolated series
+export interface InterpolatedSeries {
+  x: number[]
+  y_a: number[]
+  y_b: number[]
+}
+
+// Result type for range-filtered data
+export interface FilteredFillData extends FillPathArrays {
+  // Original indices before filtering (for mapping back)
+  original_indices: number[]
+}
+
+// Result type for where-conditioned data (may have multiple segments)
+export interface ConditionedFillData {
+  segments: FillPathPoint[][]
+}
+
+// Result type for log-scale clamped data
+export interface ClampedFillData extends FillPathArrays {
+  // Track which points were clamped (for optional warnings)
+  clamped_indices: number[]
+}
+
+// Resolves a series reference (by index or id) to the actual DataSeries
+// Returns null if the reference cannot be resolved
+export function resolve_series_ref(
+  ref: { type: `series`; series_idx?: number; series_id?: string | number },
+  series: readonly DataSeries[],
+): DataSeries | null {
+  if (`series_idx` in ref && typeof ref.series_idx === `number`) {
+    const idx = ref.series_idx
+    if (idx >= 0 && idx < series.length) {
+      return series[idx]
+    }
+    return null
+  }
+
+  if (`series_id` in ref && ref.series_id !== undefined) {
+    const found = series.find((data_series) => data_series.id === ref.series_id)
+    return found ?? null
+  }
+
+  return null
+}
+
+// Helper: linear interpolation at a specific x value
+function interpolate_at(
+  x_values: readonly number[],
+  y_values: readonly number[],
+  target_x: number,
+): number {
+  // Find bracketing indices
+  let [left_idx, right_idx] = [-1, -1]
+  for (let idx = 0; idx < x_values.length; idx++) {
+    if (x_values[idx] <= target_x) left_idx = idx
+    if (x_values[idx] >= target_x && right_idx === -1) right_idx = idx
+  }
+
+  // Handle edge cases: exact match, before all, after all
+  if (left_idx >= 0 && x_values[left_idx] === target_x) return y_values[left_idx]
+  if (left_idx === -1) return y_values[0]
+  if (right_idx === -1) return y_values[y_values.length - 1]
+
+  // Linear interpolation
+  const x_left = x_values[left_idx]
+  const x_right = x_values[right_idx]
+  const y_left = y_values[left_idx]
+  const y_right = y_values[right_idx]
+  return x_right === x_left
+    ? y_left
+    : y_left + ((target_x - x_left) / (x_right - x_left)) * (y_right - y_left)
+}
+
+// Helper: step interpolation at a specific x value
+function step_interpolate_at(
+  x_values: readonly number[],
+  y_values: readonly number[],
+  target_x: number,
+): number {
+  // Find the last x value <= target_x
+  let last_idx = -1
+  for (let idx = 0; idx < x_values.length; idx++) {
+    if (x_values[idx] <= target_x) last_idx = idx
+    else break
+  }
+
+  // Before all x values, use first y value
+  if (last_idx === -1) return y_values[0]
+
+  return y_values[last_idx]
+}
+
+// Interpolates two series to have matching x-values
+// Returns arrays with the union of all x-values, sorted
+export function interpolate_series(
+  series_a: { x: readonly number[]; y: readonly number[] },
+  series_b: { x: readonly number[]; y: readonly number[] },
+  method: `linear` | `step` = `linear`,
+): InterpolatedSeries {
+  // Create union of x-values
+  const x_set = new Set<number>()
+  for (const curr_x of series_a.x) x_set.add(curr_x)
+  for (const curr_x of series_b.x) x_set.add(curr_x)
+
+  // Sort x-values
+  const all_x = Array.from(x_set).sort((val_a, val_b) => val_a - val_b)
+
+  const interpolate_fn = method === `step` ? step_interpolate_at : interpolate_at
+
+  // Interpolate y values for each x
+  const y_a = all_x.map((target_x) => interpolate_fn(series_a.x, series_a.y, target_x))
+  const y_b = all_x.map((target_x) => interpolate_fn(series_b.x, series_b.y, target_x))
+
+  return { x: all_x, y_a, y_b }
+}
+
+// Domain context for boundary resolution
+interface DomainContext {
+  y_domain: [number, number]
+  y2_domain?: [number, number]
+}
+
+// Resolves a FillBoundary definition to an array of y-values at given x positions
+// Returns null if the boundary cannot be resolved
+export function resolve_boundary(
+  boundary: FillBoundary,
+  series: readonly DataSeries[],
+  x_values: readonly number[],
+  domains: DomainContext,
+): number[] | null {
+  // Handle shorthand number (constant value)
+  if (typeof boundary === `number`) {
+    return x_values.map(() => boundary)
+  }
+
+  if (boundary.type === `series`) {
+    const resolved = resolve_series_ref(boundary, series)
+    if (!resolved) return null
+    // Interpolate to match x_values
+    const interpolated = interpolate_series(
+      { x: x_values, y: x_values.map(() => 0) },
+      { x: resolved.x, y: resolved.y },
+      `linear`,
+    )
+    return interpolated.y_b
+  }
+  if (boundary.type === `constant`) return x_values.map(() => boundary.value)
+  if (boundary.type === `axis`) {
+    // For axis boundaries, return the edge value of the appropriate axis domain
+    const value =
+      boundary.value ??
+      (boundary.axis === `y2` ? domains.y2_domain?.[0] : undefined) ??
+      domains.y_domain[0]
+    return x_values.map(() => value)
+  }
+  if (boundary.type === `function`) return x_values.map((curr_x) => boundary.fn(curr_x))
+  if (boundary.type === `data`) {
+    if (boundary.values.length === 0) return Array(x_values.length).fill(NaN)
+    // If lengths match, use directly; otherwise interpolate
+    if (boundary.values.length === x_values.length) return [...boundary.values]
+    // Lengths don't match: truncate if values is longer, or extend last value if shorter
+    return x_values.map(
+      (_, idx) => boundary.values[idx] ?? boundary.values[boundary.values.length - 1],
+    )
+  }
+  return null
+}
+
+export function apply_range_constraints(
+  x_values: readonly number[],
+  y1_values: readonly number[],
+  y2_values: readonly number[],
+  region: Pick<FillRegion, `x_range` | `y_range`>,
+): FilteredFillData {
+  const [x_min, x_max] = region.x_range ?? [null, null]
+  const [y_min, y_max] = region.y_range ?? [null, null]
+
+  // Helper to clamp value within optional bounds
+  const clamp = (val: number) => Math.min(y_max ?? Infinity, Math.max(y_min ?? -Infinity, val))
+
+  const result = {
+    x: [] as number[],
+    y1: [] as number[],
+    y2: [] as number[],
+    original_indices: [] as number[],
+  }
+
+  for (let idx = 0; idx < x_values.length; idx++) {
+    const [curr_x, curr_y1, curr_y2] = [x_values[idx], y1_values[idx], y2_values[idx]]
+
+    // Skip if outside x range
+    if ((x_min !== null && curr_x < x_min) || (x_max !== null && curr_x > x_max)) continue
+
+    // Skip if fill region doesn't overlap y range
+    const [fill_min, fill_max] = [Math.min(curr_y1, curr_y2), Math.max(curr_y1, curr_y2)]
+    if ((y_min !== null && fill_max < y_min) || (y_max !== null && fill_min > y_max)) {
+      continue
+    }
+
+    result.x.push(curr_x)
+    result.y1.push(clamp(curr_y1))
+    result.y2.push(clamp(curr_y2))
+    result.original_indices.push(idx)
+  }
+
+  return result
+}
+
+// Helper: find x-coordinate where condition changes (linear interpolation)
+function find_crossing(
+  x1: number,
+  y1_upper: number,
+  y1_lower: number,
+  x2: number,
+  y2_upper: number,
+  y2_lower: number,
+  condition: (x: number, y_upper: number, y_lower: number) => boolean,
+): number | null {
+  const cond1 = condition(x1, y1_upper, y1_lower)
+  const cond2 = condition(x2, y2_upper, y2_lower)
+
+  if (cond1 === cond2) return null
+
+  // Binary search for crossing point
+  let left = x1
+  let right = x2
+  const tolerance = (x2 - x1) * 0.001
+
+  for (let iter = 0; iter < 20; iter++) {
+    const mid = (left + right) / 2
+    const weight = (mid - x1) / (x2 - x1)
+    const mid_upper = y1_upper + weight * (y2_upper - y1_upper)
+    const mid_lower = y1_lower + weight * (y2_lower - y1_lower)
+    const mid_cond = condition(mid, mid_upper, mid_lower)
+
+    if (mid_cond === cond1) {
+      left = mid
+    } else {
+      right = mid
+    }
+
+    if (right - left < tolerance) break
+  }
+
+  return (left + right) / 2
+}
+
+export function apply_where_condition(
+  x_values: readonly number[],
+  y1_values: readonly number[],
+  y2_values: readonly number[],
+  region: Pick<FillRegion, `where`>,
+): ConditionedFillData {
+  if (!region.where) {
+    // No condition - return single segment with all points
+    const points: FillPathPoint[] = x_values.map((curr_x, idx) => ({
+      x: curr_x,
+      y1: y1_values[idx],
+      y2: y2_values[idx],
+    }))
+    return { segments: [points] }
+  }
+
+  const segments: FillPathPoint[][] = []
+  let current_segment: FillPathPoint[] = []
+
+  for (let idx = 0; idx < x_values.length; idx++) {
+    const curr_x = x_values[idx]
+    const curr_y1 = y1_values[idx]
+    const curr_y2 = y2_values[idx]
+    const passes = region.where(curr_x, curr_y1, curr_y2)
+
+    if (idx > 0) {
+      const prev_x = x_values[idx - 1]
+      const prev_y1 = y1_values[idx - 1]
+      const prev_y2 = y2_values[idx - 1]
+      const prev_passes = region.where(prev_x, prev_y1, prev_y2)
+
+      // Check for condition crossing between prev and current
+      if (passes !== prev_passes) {
+        const crossing_x = find_crossing(
+          prev_x,
+          prev_y1,
+          prev_y2,
+          curr_x,
+          curr_y1,
+          curr_y2,
+          region.where,
+        )
+
+        if (crossing_x !== null) {
+          // Interpolate y values at crossing point
+          const weight = (crossing_x - prev_x) / (curr_x - prev_x)
+          const crossing_y1 = prev_y1 + weight * (curr_y1 - prev_y1)
+          const crossing_y2 = prev_y2 + weight * (curr_y2 - prev_y2)
+
+          if (prev_passes) {
+            // End current segment at crossing
+            current_segment.push({ x: crossing_x, y1: crossing_y1, y2: crossing_y2 })
+            segments.push(current_segment)
+            current_segment = []
+          } else {
+            // Start new segment at crossing
+            current_segment.push({ x: crossing_x, y1: crossing_y1, y2: crossing_y2 })
+          }
+        }
+      }
+    }
+
+    if (passes) {
+      current_segment.push({ x: curr_x, y1: curr_y1, y2: curr_y2 })
+    } else if (current_segment.length > 0) {
+      segments.push(current_segment)
+      current_segment = []
+    }
+  }
+
+  // Don't forget the last segment
+  if (current_segment.length > 0) {
+    segments.push(current_segment)
+  }
+
+  return { segments }
+}
+
+export function clamp_for_log_scale(
+  x_values: readonly number[],
+  y1_values: readonly number[],
+  y2_values: readonly number[],
+  y_scale_type: ScaleType,
+  x_scale_type: ScaleType = `linear`,
+): ClampedFillData {
+  const result_x: number[] = []
+  const result_y1: number[] = []
+  const result_y2: number[] = []
+  const clamped_indices: number[] = []
+
+  for (let idx = 0; idx < x_values.length; idx++) {
+    let curr_x = x_values[idx]
+    let curr_y1 = y1_values[idx]
+    let curr_y2 = y2_values[idx]
+    let was_clamped = false
+
+    // Clamp x if x-axis is log scale
+    if (x_scale_type === `log` && curr_x <= 0) {
+      curr_x = LOG_EPSILON
+      was_clamped = true
+    }
+
+    // Clamp y values if y-axis is log scale
+    if (y_scale_type === `log`) {
+      if (curr_y1 <= 0) {
+        curr_y1 = LOG_EPSILON
+        was_clamped = true
+      }
+      if (curr_y2 <= 0) {
+        curr_y2 = LOG_EPSILON
+        was_clamped = true
+      }
+    }
+
+    result_x.push(curr_x)
+    result_y1.push(curr_y1)
+    result_y2.push(curr_y2)
+
+    if (was_clamped) {
+      clamped_indices.push(idx)
+    }
+  }
+
+  return {
+    x: result_x,
+    y1: result_y1,
+    y2: result_y2,
+    clamped_indices,
+  }
+}
+
+// Map FillCurveType to d3 curve factory
+const CURVE_MAP: Record<FillCurveType, CurveFactory> = {
+  linear: curveLinear,
+  monotoneX: curveMonotoneX,
+  monotoneY: curveMonotoneY,
+  step: curveStep,
+  stepBefore: curveStepBefore,
+  stepAfter: curveStepAfter,
+  basis: curveBasis,
+  cardinal: curveCardinal,
+  catmullRom: curveCatmullRom,
+  natural: curveNatural,
+}
+
+const get_curve = (curve_type: FillCurveType): CurveFactory =>
+  CURVE_MAP[curve_type] ?? curveMonotoneX
+
+// Generate SVG path string for a fill region
+// data should already be in pixel coordinates
+export function generate_fill_path(
+  data: readonly FillPathPoint[],
+  curve_type: FillCurveType = `monotoneX`,
+): string {
+  if (data.length === 0) return ``
+
+  const curve = get_curve(curve_type)
+
+  const area_generator = area<FillPathPoint>()
+    .x((point) => point.x)
+    .y0((point) => point.y1)
+    .y1((point) => point.y2)
+    .curve(curve)
+
+  return area_generator(data as FillPathPoint[]) ?? ``
+}
+
+// Helper to expand error definition to array
+const expand_error = (err: number | readonly number[], length: number): readonly number[] =>
+  typeof err === `number` ? Array(length).fill(err) : err
+
+// Convert an ErrorBand convenience type to a full FillRegion
+export function convert_error_band_to_fill_region(
+  error_band: ErrorBand,
+  series: readonly DataSeries[],
+  default_color?: string,
+): FillRegion | null {
+  const resolved = resolve_series_ref(error_band.series, series)
+  if (!resolved) return null
+
+  const { y } = resolved
+  const { error } = error_band
+
+  // Determine upper/lower error arrays
+  const [upper_err, lower_err] =
+    typeof error === `object` && `upper` in error
+      ? [expand_error(error.upper, y.length), expand_error(error.lower, y.length)]
+      : [expand_error(error, y.length), expand_error(error, y.length)]
+
+  return {
+    id: error_band.id,
+    label: error_band.label,
+    upper: { type: `data`, values: y.map((val, idx) => val + upper_err[idx]) },
+    lower: { type: `data`, values: y.map((val, idx) => val - lower_err[idx]) },
+    fill: error_band.fill ?? default_color ?? `#4e79a7`,
+    fill_opacity: error_band.fill_opacity ?? 0.3,
+    edge_upper: error_band.edge_style,
+    edge_lower: error_band.edge_style,
+    show_in_legend: error_band.show_in_legend ?? true,
+  }
+}
+
+// Type guard to check if fill is a gradient
+export const is_fill_gradient = (
+  fill: string | FillGradient | undefined,
+): fill is FillGradient =>
+  typeof fill === `object` && fill !== null && `type` in fill && `stops` in fill

package/dist/src/lib/plot/hover-lock.svelte.ts

@@ -0,0 +1,60 @@
+// Shared utility for hover lock behavior on plot elements (legend, colorbar)
+// Prevents element repositioning while user is hovering, with debounced release
+
+export const HOVER_DEBOUNCE_MS = 300
+
+// Reactive wrapper that exposes state via a stable object reference
+interface ReactiveBoolean {
+  readonly current: boolean
+}
+
+// Creates hover lock state and handlers for a plot element
+export function create_hover_lock(): {
+  is_locked: ReactiveBoolean
+  set_locked: (locked: boolean) => void
+  cleanup: () => void
+} {
+  let is_locked = $state(false)
+  let timeout: ReturnType<typeof setTimeout> | null = null
+
+  // Stable object reference with getter - Svelte tracks the getter read
+  const locked_ref: ReactiveBoolean = {
+    get current() {
+      return is_locked
+    },
+  }
+
+  return {
+    is_locked: locked_ref,
+    set_locked(locked: boolean) {
+      if (locked) {
+        if (timeout) clearTimeout(timeout)
+        is_locked = true
+      } else {
+        timeout = setTimeout(() => (is_locked = false), HOVER_DEBOUNCE_MS)
+      }
+    },
+    // Clear pending timeout to prevent state updates after unmount
+    cleanup() {
+      if (timeout) clearTimeout(timeout)
+    },
+  }
+}
+
+// Tracks previous dimensions for resize detection
+export function create_dimension_tracker(): {
+  has_changed: (width: number, height: number) => boolean
+  update: (width: number, height: number) => void
+} {
+  let prev = $state<{ width: number; height: number } | null>(null)
+
+  return {
+    has_changed(width: number, height: number): boolean {
+      if (!prev) return true
+      return prev.width !== width || prev.height !== height
+    },
+    update(width: number, height: number) {
+      prev = { width, height }
+    },
+  }
+}

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

@@ -0,0 +1,53 @@
+export { default as AxisLabel } from './AxisLabel.svelte'
+export { default as BarPlot } from './BarPlot.svelte'
+export { default as BarPlotControls } from './BarPlotControls.svelte'
+export { default as ColorBar } from './ColorBar.svelte'
+export { default as BinnedScatterPlot } from './BinnedScatterPlot.svelte'
+export type {
+  BinnedColorScaleConfig,
+  BinnedDensityConfig,
+  BinnedOverlaysConfig,
+  BinnedPointBasePayload,
+  BinnedPointDataFn,
+  BinnedPointLabelPlacementConfig,
+  BinnedPointLabelsConfig,
+  BinnedPointPayload,
+  BinnedPointTooltipPayload,
+  BinnedRefLine,
+  BinnedSizeScaleConfig,
+} from './binned-scatter-types'
+export type { DensePointSeries } from './adaptive-density'
+export { default as PlotAxis } from './PlotAxis.svelte'
+export { default as ColorScaleSelect } from './ColorScaleSelect.svelte'
+export * from './data-cleaning'
+export { default as ElementScatter } from './ElementScatter.svelte'
+export * from './fill-utils'
+export { default as FillArea } from './FillArea.svelte'
+export { default as Histogram } from './Histogram.svelte'
+export { default as HistogramControls } from './HistogramControls.svelte'
+export * from './interactions'
+export { default as InteractiveAxisLabel } from './InteractiveAxisLabel.svelte'
+export * from './layout'
+export { default as Line } from './Line.svelte'
+export { default as PlotControls } from './PlotControls.svelte'
+export { default as PlotLegend } from './PlotLegend.svelte'
+export { default as PlotTooltip } from './PlotTooltip.svelte'
+export { default as PortalSelect } from './PortalSelect.svelte'
+export * from './reference-line'
+export { default as ReferenceLine } from './ReferenceLine.svelte'
+export { default as ReferenceLine3D } from './ReferenceLine3D.svelte'
+export { default as ReferencePlane } from './ReferencePlane.svelte'
+export * from './scales'
+export { default as ScatterPlot } from './ScatterPlot.svelte'
+export { default as ScatterPlot3D } from './ScatterPlot3D.svelte'
+export { default as ScatterPlot3DControls } from './ScatterPlot3DControls.svelte'
+export { default as ScatterPlot3DScene } from './ScatterPlot3DScene.svelte'
+export { default as ScatterPlotControls } from './ScatterPlotControls.svelte'
+export { default as ScatterPoint } from './ScatterPoint.svelte'
+export { default as SpacegroupBarPlot } from './SpacegroupBarPlot.svelte'
+export { default as Surface3D } from './Surface3D.svelte'
+export * from './svg'
+export * from './types'
+export * from './utils'
+export { default as ZeroLines } from './ZeroLines.svelte'
+export { default as ZoomRect } from './ZoomRect.svelte'