matterviz 0.3.6 → 0.4.0

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

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

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

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

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

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