matterviz 0.3.5 → 0.3.6

package/dist/src/lib/plot/adaptive-density.ts

@@ -0,0 +1,316 @@
+import type { Point2D, Vec2 } from '$lib/math'
+
+export type NumericArray = ArrayLike<number>
+
+export interface DensePointSeries<Metadata = Record<string, unknown>> {
+  id?: string | number
+  label?: string
+  x: NumericArray
+  y: NumericArray
+  metadata?: Metadata[] | Metadata
+  point_ids?: ArrayLike<string | number>
+  size_values?: ArrayLike<number | null>
+  color?: string
+}
+
+export interface DenseInternalPoint<Metadata = Record<string, unknown>> {
+  x: number
+  y: number
+  series_idx: number
+  point_idx: number
+  metadata?: Metadata
+  point_id?: string | number
+  size_value?: number | null
+  cx: number
+  cy: number
+}
+
+export interface DensityBinResult {
+  counts: Uint32Array
+  first_point_idxs: Int32Array
+  first_series_idxs: Int32Array
+  max_count: number
+  visible_count: number
+  x_bins: number
+  y_bins: number
+}
+
+export interface DensityBin {
+  x_bin: number
+  y_bin: number
+  count: number
+  x_range: Vec2
+  y_range: Vec2
+}
+
+export interface PickNearestOptions {
+  x_range: Vec2
+  y_range: Vec2
+  x_scale: (value: number) => number
+  y_scale: (value: number) => number
+  radius_px?: number
+}
+
+export interface PickIndex<Metadata = Record<string, unknown>> {
+  cells: Map<string, DenseInternalPoint<Metadata>[]>
+  cell_size: number
+  radius_px: number
+}
+
+export interface PlotRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export const get_metadata_at = <Metadata>(
+  metadata: DensePointSeries<Metadata>[`metadata`],
+  point_idx: number,
+): Metadata | undefined => (Array.isArray(metadata) ? metadata[point_idx] : metadata)
+
+const cell_key = (x_bin: number, y_bin: number): string => `${x_bin},${y_bin}`
+
+export const range_bounds = (range: Vec2): Vec2 =>
+  range[0] <= range[1] ? range : [range[1], range[0]]
+
+const in_bounds = (value: number, min: number, max: number): boolean =>
+  Number.isFinite(value) && value >= min && value <= max
+
+const value_bin = (value: number, min: number, span: number, bins: number): number =>
+  Math.min(bins - 1, Math.max(0, Math.floor(((value - min) / span) * bins)))
+
+const series_length = (srs: Pick<DensePointSeries, `x` | `y`>): number =>
+  Math.min(srs.x.length, srs.y.length)
+
+const padded_extent = (min: number, max: number): Vec2 => {
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return [0, 1]
+  if (min === max) return [min - 0.5, max + 0.5]
+  const padding = (max - min) * 0.05
+  return [min - padding, max + padding]
+}
+
+export function series_extents(series: readonly DensePointSeries[]): { x: Vec2; y: Vec2 } {
+  let x_min = Infinity
+  let x_max = -Infinity
+  let y_min = Infinity
+  let y_max = -Infinity
+
+  for (const srs of series) {
+    const n_points = series_length(srs)
+    for (let idx = 0; idx < n_points; idx++) {
+      const x = srs.x[idx]
+      const y = srs.y[idx]
+      if (Number.isFinite(x)) {
+        if (x < x_min) x_min = x
+        if (x > x_max) x_max = x
+      }
+      if (Number.isFinite(y)) {
+        if (y < y_min) y_min = y
+        if (y > y_max) y_max = y
+      }
+    }
+  }
+
+  return { x: padded_extent(x_min, x_max), y: padded_extent(y_min, y_max) }
+}
+
+export function bin_points(
+  series: readonly DensePointSeries[],
+  x_range: Vec2,
+  y_range: Vec2,
+  x_bins: number,
+  y_bins: number,
+): DensityBinResult {
+  const counts = new Uint32Array(x_bins * y_bins)
+  const first_point_idxs = new Int32Array(counts.length)
+  const first_series_idxs = new Int32Array(counts.length)
+  const [x_min, x_max] = range_bounds(x_range)
+  const [y_min, y_max] = range_bounds(y_range)
+  const x_span = x_max - x_min || 1
+  const y_span = y_max - y_min || 1
+  const x_bin_scale = x_bins / x_span
+  const y_bin_scale = y_bins / y_span
+  const last_x_bin = x_bins - 1
+  const last_y_bin = y_bins - 1
+  let visible_count = 0
+  let max_count = 0
+
+  for (let series_idx = 0; series_idx < series.length; series_idx++) {
+    const srs = series[series_idx]
+    const n_points = series_length(srs)
+    for (let point_idx = 0; point_idx < n_points; point_idx++) {
+      const x = srs.x[point_idx]
+      const y = srs.y[point_idx]
+      if (
+        !Number.isFinite(x) ||
+        !Number.isFinite(y) ||
+        x < x_min ||
+        x > x_max ||
+        y < y_min ||
+        y > y_max
+      )
+        continue
+
+      const raw_x_bin = Math.floor((x - x_min) * x_bin_scale)
+      const raw_y_bin = Math.floor((y - y_min) * y_bin_scale)
+      const x_bin = raw_x_bin > last_x_bin ? last_x_bin : raw_x_bin
+      const y_bin = raw_y_bin > last_y_bin ? last_y_bin : raw_y_bin
+      const idx = y_bin * x_bins + x_bin
+      const count = ++counts[idx]
+      if (count === 1) {
+        first_series_idxs[idx] = series_idx
+        first_point_idxs[idx] = point_idx
+      }
+      visible_count++
+      if (count > max_count) max_count = count
+    }
+  }
+
+  return {
+    counts,
+    first_point_idxs,
+    first_series_idxs,
+    max_count,
+    visible_count,
+    x_bins,
+    y_bins,
+  }
+}
+
+export function density_bin_at_point(
+  density: DensityBinResult,
+  pointer: Point2D,
+  plot_rect: PlotRect,
+  x_range: Vec2,
+  y_range: Vec2,
+): DensityBin | null {
+  const rel_x = pointer.x - plot_rect.x
+  const rel_y = pointer.y - plot_rect.y
+  if (rel_x < 0 || rel_y < 0 || rel_x >= plot_rect.width || rel_y >= plot_rect.height) {
+    return null
+  }
+
+  const x_bin = value_bin(rel_x, 0, plot_rect.width || 1, density.x_bins)
+  // Screen coordinates grow downward, while density bins use bottom-up data Y.
+  const y_bin = density.y_bins - 1 - value_bin(rel_y, 0, plot_rect.height || 1, density.y_bins)
+  const count = density.counts[y_bin * density.x_bins + x_bin]
+  if (!count) return null
+
+  const [x_min, x_max] = range_bounds(x_range)
+  const [y_min, y_max] = range_bounds(y_range)
+  const x_step = (x_max - x_min || 1) / density.x_bins
+  const y_step = (y_max - y_min || 1) / density.y_bins
+  return {
+    x_bin,
+    y_bin,
+    count,
+    x_range: [x_min + x_bin * x_step, x_min + (x_bin + 1) * x_step],
+    y_range: [y_min + y_bin * y_step, y_min + (y_bin + 1) * y_step],
+  }
+}
+
+export function should_render_points(
+  visible_count: number,
+  plot_area_px: number,
+  max_points: number,
+  max_points_per_px: number,
+): boolean {
+  return (
+    visible_count <= max_points ||
+    (plot_area_px > 0 && visible_count / plot_area_px <= max_points_per_px)
+  )
+}
+
+const internal_point = <Metadata>(
+  srs: DensePointSeries<Metadata>,
+  series_idx: number,
+  point_idx: number,
+  x_scale: (value: number) => number,
+  y_scale: (value: number) => number,
+): DenseInternalPoint<Metadata> => {
+  const x = srs.x[point_idx]
+  const y = srs.y[point_idx]
+  return {
+    x,
+    y,
+    cx: x_scale(x),
+    cy: y_scale(y),
+    series_idx,
+    point_idx,
+    metadata: get_metadata_at(srs.metadata, point_idx),
+    point_id: srs.point_ids?.[point_idx],
+    size_value: srs.size_values?.[point_idx],
+  }
+}
+
+export function build_pick_index<Metadata>(
+  series: readonly DensePointSeries<Metadata>[],
+  options: PickNearestOptions,
+): PickIndex<Metadata> {
+  const { x_range, y_range, x_scale, y_scale, radius_px = 12 } = options
+  const [x_min, x_max] = range_bounds(x_range)
+  const [y_min, y_max] = range_bounds(y_range)
+  const cell_size = Math.max(1, radius_px)
+  const cells = new Map<string, DenseInternalPoint<Metadata>[]>()
+
+  for (let series_idx = 0; series_idx < series.length; series_idx++) {
+    const srs = series[series_idx]
+    const n_points = series_length(srs)
+    for (let point_idx = 0; point_idx < n_points; point_idx++) {
+      const x = srs.x[point_idx]
+      const y = srs.y[point_idx]
+      if (!in_bounds(x, x_min, x_max) || !in_bounds(y, y_min, y_max)) continue
+
+      const point = internal_point(srs, series_idx, point_idx, x_scale, y_scale)
+      const key = cell_key(Math.floor(point.cx / cell_size), Math.floor(point.cy / cell_size))
+      const points = cells.get(key)
+      if (points) points.push(point)
+      else cells.set(key, [point])
+    }
+  }
+
+  return { cells, cell_size, radius_px }
+}
+
+export function pick_from_index<Metadata>(
+  index: PickIndex<Metadata>,
+  pointer: Point2D,
+): DenseInternalPoint<Metadata> | null {
+  const radius_sq = index.radius_px ** 2
+  const center_x = Math.floor(pointer.x / index.cell_size)
+  const center_y = Math.floor(pointer.y / index.cell_size)
+  const cell_radius = Math.ceil(index.radius_px / index.cell_size)
+  let best: DenseInternalPoint<Metadata> | null = null
+  let best_dist_sq = radius_sq
+
+  for (let y_bin = center_y - cell_radius; y_bin <= center_y + cell_radius; y_bin++) {
+    for (let x_bin = center_x - cell_radius; x_bin <= center_x + cell_radius; x_bin++) {
+      for (const point of index.cells.get(cell_key(x_bin, y_bin)) ?? []) {
+        const dx = pointer.x - point.cx
+        const dy = pointer.y - point.cy
+        const dist_sq = dx * dx + dy * dy
+        if (dist_sq > best_dist_sq) continue
+        best_dist_sq = dist_sq
+        best = point
+      }
+    }
+  }
+
+  return best
+}
+
+export function first_point_in_bin<Metadata>(
+  series: readonly DensePointSeries<Metadata>[],
+  density: DensityBinResult,
+  bin: Pick<DensityBin, `x_bin` | `y_bin`>,
+  x_scale: (value: number) => number,
+  y_scale: (value: number) => number,
+): DenseInternalPoint<Metadata> | null {
+  const idx = bin.y_bin * density.x_bins + bin.x_bin
+  if (!density.counts[idx]) return null
+  const series_idx = density.first_series_idxs[idx]
+  const point_idx = density.first_point_idxs[idx]
+  const srs = series[series_idx]
+  return srs ? internal_point(srs, series_idx, point_idx, x_scale, y_scale) : null
+}

package/dist/src/lib/plot/auto-place.ts

@@ -0,0 +1,184 @@
+import { compute_element_placement, sample_series_obstacle_points } from './layout'
+import type { Sides } 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
+
+type Pt = { x: number; y: number }
+type Size = { width: number; height: number }
+
+// 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?: string | null): boolean =>
+  /(^|[;{]\s*)(top|bottom|left|right)\s*:|position\s*:\s*absolute/.test(style ?? ``)
+
+// A decoration's pixel footprint: its rendered box once laid out, else `fallback` (offset dims read
+// 0 before first render). Used to decide crowding before the real size is known.
+export const measured_footprint = (el: HTMLElement | null | undefined, fallback: Size): Size =>
+  el?.offsetWidth && el?.offsetHeight
+    ? { width: el.offsetWidth, height: el.offsetHeight }
+    : fallback
+
+// Build the obstacle field in normalized [0,1] plot coords from one or more series. Callers pass
+// points already normalized to [0,1] with y=0 at the top. Built from data (not pixel scales) so the
+// crowding decision below is independent of any margins reserved for outside decorations — this
+// prevents a reserve -> data-shift -> re-decide oscillation loop.
+export function build_obstacles_norm(
+  series: { points: Pt[]; draws_line?: boolean }[],
+  base_w: number,
+  base_h: number,
+): Pt[] {
+  const step = 12 / Math.max(base_w, base_h, 1)
+  const out: Pt[] = []
+  for (const srs of series) {
+    // avoid out.push(...arr): a long series would overflow the call-stack arg limit
+    for (const pt of sample_series_obstacle_points(
+      srs.points,
+      srs.draws_line ?? false,
+      step,
+    )) {
+      if (isFinite(pt.x) && isFinite(pt.y)) out.push(pt)
+    }
+  }
+  return out
+}
+
+// Build an obstacle segment for one bar, clipped to the visible [0,1]x[0,1] box (null if off-plot).
+// Clipping is essential: when zoomed in, off-screen bars normalize to huge coords and would make
+// sample_series_obstacle_points emit millions of points. `cross` is the fixed bar position; `a`/`b`
+// are the span endpoints (baseline -> tip) along the other axis.
+export function clip_bar(
+  vertical: boolean,
+  cross: number,
+  a: number,
+  b: number,
+): { points: Pt[]; draws_line: boolean } | null {
+  if (!(cross >= 0 && cross <= 1)) return null
+  const lo = Math.max(0, Math.min(a, b))
+  const hi = Math.min(1, Math.max(a, b))
+  if (hi < lo) return null
+  const points = vertical
+    ? [
+        { x: cross, y: lo },
+        { x: cross, y: hi },
+      ]
+    : [
+        { x: lo, y: cross },
+        { x: hi, y: cross },
+      ]
+  return { points, draws_line: true }
+}
+
+// A decoration is "crowded out" only when even the emptiest interior spot is at least this dense
+// relative to the plot-wide average. A single clear region (e.g. one sparse quadrant) keeps the
+// decoration inside; a roughly uniformly-full plot pushes it out. Using a relative ratio (not "any
+// overlap") keeps the decision stable for wide decorations that merely clip a dense neighbor.
+const CROWDING_RATIO = 0.5
+
+// True when even the best interior spot for `footprint` (px) is too dense to host the decoration
+function is_crowded(
+  obstacles: Pt[],
+  footprint: Size,
+  base_w: number,
+  base_h: number,
+  clearance: number,
+): boolean {
+  if (!obstacles.length || base_w <= 0 || base_h <= 0) return false
+  const fw = footprint.width / base_w
+  const fh = footprint.height / base_h
+  if (fw >= 1 || fh >= 1) return true // too big to fit inside -> outside
+  const best = compute_element_placement({
+    plot_bounds: { x: 0, y: 0, width: 1, height: 1 },
+    element_size: { width: fw, height: fh },
+    axis_clearance: clearance / Math.min(base_w, base_h),
+    points: obstacles,
+  })
+  const in_box = obstacles.filter(
+    (pt) => pt.x >= best.x && pt.x <= best.x + fw && pt.y >= best.y && pt.y <= best.y + fh,
+  ).length
+  // expected count if obstacles were spread uniformly = total * box-area fraction
+  return in_box > CROWDING_RATIO * obstacles.length * fw * fh
+}
+
+export type DecorationInput = { footprint: Size; clearance?: number }
+
+export type DecorationLayout = {
+  pad: Required<Sides> // base_pad plus reservations for whatever moved outside
+  legend_outside: boolean
+  legend_pos: Pt // outside position (right or bottom margin; valid when legend_outside)
+  colorbar_outside: boolean
+  colorbar_style: string // wrapper style for the reserved margin ('' when interior)
+}
+
+// Decide which decorations must move outside (interior placement unavoidably overlaps data), the
+// reserved padding, and the outside positions/styles. `base_pad` must be decoration-independent so
+// the crowding decision can't see the reservation it produces.
+export function place_decorations(cfg: {
+  base_pad: Required<Sides>
+  width: number
+  height: number
+  obstacles_norm: Pt[]
+  legend?: DecorationInput | null // null = no auto-placeable legend
+  colorbar?: (DecorationInput & { horizontal?: boolean }) | null
+  gap?: number
+}): DecorationLayout {
+  const { base_pad, width, height, obstacles_norm, legend, colorbar, gap = DECOR_GAP } = cfg
+  const base_w = width - base_pad.l - base_pad.r
+  const base_h = height - base_pad.t - base_pad.b
+
+  const colorbar_outside =
+    colorbar != null &&
+    is_crowded(obstacles_norm, colorbar.footprint, base_w, base_h, colorbar.clearance ?? 15)
+  const cbar_horizontal = colorbar?.horizontal ?? false
+  const colorbar_takes_right = colorbar_outside && !cbar_horizontal // vertical colorbar -> right
+  const cbar_w = colorbar?.footprint.width ?? 0
+  const cbar_h = colorbar?.footprint.height ?? 0
+
+  const legend_outside =
+    legend != null &&
+    is_crowded(obstacles_norm, legend.footprint, base_w, base_h, legend.clearance ?? 12)
+  const legend_w = legend?.footprint.width ?? 0
+  const legend_h = legend?.footprint.height ?? 0
+  // Put a narrow/tall legend on the right (wastes less reserved margin than a wide bottom strip);
+  // a wide/short legend goes below. Skip the right side if a vertical colorbar already took it.
+  const legend_right =
+    legend_outside && !colorbar_takes_right && legend_h * base_w > legend_w * base_h
+  const legend_bottom = legend_outside && !legend_right
+
+  // colorbar: horizontal -> above (reserves top), vertical -> right. legend: right or bottom.
+  // A right legend replaces the plot's right margin (it sits flush at the edge), so reserve only its
+  // width + a gap on each side instead of stacking it on top of base_pad.r (which left a wide gap).
+  const pad: Required<Sides> = {
+    t: base_pad.t + (colorbar_outside && cbar_horizontal ? cbar_h + gap : 0),
+    l: base_pad.l,
+    b: base_pad.b + (legend_bottom ? legend_h + gap : 0),
+    r: legend_right
+      ? legend_w + 2 * gap
+      : base_pad.r + (colorbar_takes_right ? cbar_w + gap : 0),
+  }
+
+  const colorbar_style = !colorbar_outside
+    ? ``
+    : cbar_horizontal
+      ? `position: absolute; top: ${gap}px; inset-inline: 0; margin-inline: auto; width: calc(100% - ${
+          base_pad.l + base_pad.r
+        }px); max-width: 100%;`
+      : `position: absolute; right: ${gap}px; inset-block: 0; margin-block: auto; height: calc(100% - ${
+          base_pad.t + base_pad.b
+        }px); max-height: 100%;`
+
+  // right: flush to the right edge, vertically centered in the plot area; bottom: centered below
+  const legend_pos: Pt = legend_right
+    ? {
+        x: width - legend_w - gap,
+        y: base_pad.t + (height - base_pad.t - base_pad.b - legend_h) / 2,
+      }
+    : {
+        x: base_pad.l + (width - base_pad.l - base_pad.r - legend_w) / 2,
+        y: height - legend_h - gap,
+      }
+
+  return { pad, legend_outside, legend_pos, colorbar_outside, colorbar_style }
+}

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

@@ -0,0 +1,122 @@
+// Shared utilities for interactive axis functionality
+
+import type {
+  AxisConfig,
+  AxisLoadError,
+  BarSeries,
+  DataLoaderFn,
+  DataLoaderResult,
+  DataSeries,
+} from './types'
+
+type AxisType = `x` | `x2` | `y` | `y2`
+
+// Merge new series with preserved UI state from old series.
+// Matches by stable id first, then by index only for ordered id-less series.
+export function merge_series_state<T extends DataSeries | BarSeries>(
+  old_series: T[],
+  new_series: T[],
+): T[] {
+  // Build id lookup map for O(1) matching (string or number ids)
+  const by_id = new Map<string | number, T>()
+  for (const srs of old_series) {
+    if (srs.id !== undefined && srs.id !== ``) by_id.set(srs.id, srs)
+  }
+
+  return new_series.map((new_srs, idx) => {
+    const old_srs =
+      new_srs.id !== undefined && new_srs.id !== `` ? by_id.get(new_srs.id) : old_series[idx]
+    if (!old_srs) {
+      return new_srs
+    }
+
+    // Preserve UI state: visibility and styling from old series if not in new
+    const result: Record<string, unknown> = { ...new_srs }
+    result.visible ??= old_srs.visible
+
+    // Preserve style properties only when key exists in BOTH series (guards against
+    // cross-type injection when T is a union like DataSeries | BarSeries)
+    for (const key of [`point_style`, `line_style`, `color`]) {
+      if (key in old_srs && key in new_srs && result[key] === undefined) {
+        result[key] = old_srs[key as keyof typeof old_srs]
+      }
+    }
+    return result as T
+  })
+}
+
+// State accessors for axis change handler - enables sharing logic across plot components
+export interface AxisChangeState<T extends DataSeries | BarSeries> {
+  get_axis: (axis: AxisType) => AxisConfig
+  set_axis: (axis: AxisType, config: AxisConfig) => void
+  get_series: () => T[]
+  set_series: (series: T[]) => void
+  get_loading: () => AxisType | null
+  set_loading: (axis: AxisType | null) => void
+}
+
+// Handle axis property change - loads new data via data_loader
+// Returns a function bound to the component's state accessors
+export function create_axis_change_handler<T extends DataSeries | BarSeries>(
+  state: AxisChangeState<T>,
+  data_loader: DataLoaderFn<Record<string, unknown>, T> | undefined,
+  on_axis_change?: (axis: AxisType, key: string, new_series: T[]) => void,
+  on_error?: (error: AxisLoadError) => void,
+): (axis: AxisType, key: string) => Promise<void> {
+  return async (axis: AxisType, key: string) => {
+    if (!data_loader || state.get_loading()) return
+
+    const axis_config = state.get_axis(axis)
+    const prev_key = axis_config.selected_key
+
+    // Skip if key unchanged AND series already loaded (allows initial load when series empty)
+    if (prev_key === key && state.get_series().length > 0) return
+
+    // Update selected_key immediately for UI feedback
+    state.set_axis(axis, { ...axis_config, selected_key: key })
+    state.set_loading(axis)
+
+    try {
+      const result: DataLoaderResult<Record<string, unknown>, T> = await data_loader(
+        axis,
+        key,
+        state.get_series(),
+      )
+
+      // Merge new series with preserved state from old series
+      const merged = merge_series_state(state.get_series(), result.series)
+      state.set_series(merged)
+
+      // Update axis label/unit if provided
+      if (result.axis_label || result.axis_unit) {
+        const current = state.get_axis(axis)
+        state.set_axis(axis, {
+          ...current,
+          label: result.axis_label ?? current.label,
+          unit: result.axis_unit ?? current.unit,
+        })
+      }
+
+      on_axis_change?.(axis, key, merged)
+    } catch (err) {
+      console.error(`Failed to load data for ${axis}=${key}:`, err)
+
+      // Revert selection
+      state.set_axis(axis, { ...state.get_axis(axis), selected_key: prev_key })
+
+      const message = err instanceof Error ? err.message : String(err)
+      on_error?.({ axis, key, message })
+    } finally {
+      state.set_loading(null)
+    }
+  }
+}
+
+// Constants for axis label foreignObject positioning (all values in px)
+// Use minimal dimensions - overflow: visible handles any dropdown expansion
+export const AXIS_LABEL_CONTAINER = {
+  width: 200, // container width for centering; dropdown can overflow
+  height: 24, // single line height; dropdown options overflow downward
+  x_offset: 100, // half of width for horizontal centering
+  y_offset: 12, // half of height for vertical centering
+} as const

package/dist/src/lib/plot/binned-scatter-types.ts

@@ -0,0 +1,83 @@
+import type { D3ColorSchemeName, D3InterpolateName } from '$lib/colors'
+import type { DenseInternalPoint } from '$lib/plot/adaptive-density'
+import type ColorBar from '$lib/plot/ColorBar.svelte'
+import type { LabelPlacementConfig, ScaleType, ScatterHandlerProps } from '$lib/plot/types'
+import type { ComponentProps, Snippet } from 'svelte'
+
+export type BinnedColorScaleConfig =
+  | {
+      type?: ScaleType
+      scheme?: D3ColorSchemeName | D3InterpolateName
+      value_range?: [number, number]
+    }
+  | D3InterpolateName
+
+export type BinnedSizeScaleConfig = {
+  type?: ScaleType
+  radius_range?: [number, number]
+  value_range?: [number, number]
+  pick_radius?: number | `auto`
+}
+
+export type BinnedDensityConfig = {
+  bin_px?: number
+  color_scale?: BinnedColorScaleConfig
+  color_bar?: ComponentProps<typeof ColorBar> | null
+  auto_point_mode?: false | { max_points?: number; max_points_per_px?: number }
+  bin_click?: `zoom` | `point` | `none`
+}
+
+export type BinnedRefLine = {
+  x1: number
+  y1: number
+  x2: number
+  y2: number
+  color?: string
+  dash?: string
+  width?: number
+}
+
+export type BinnedOverlaysConfig = {
+  ref_lines?: BinnedRefLine[]
+}
+
+export type BinnedPointBasePayload<
+  Metadata extends Record<string, unknown> = Record<string, unknown>,
+> = ScatterHandlerProps<Metadata> & {
+  point: DenseInternalPoint<Metadata>
+  color?: string
+}
+
+export type BinnedPointDataFn<
+  Metadata extends Record<string, unknown> = Record<string, unknown>,
+  PointData extends Record<string, unknown> = Record<string, unknown>,
+> = (payload: BinnedPointBasePayload<Metadata>) => PointData | null | undefined
+
+export type BinnedPointPayload<
+  Metadata extends Record<string, unknown> = Record<string, unknown>,
+  PointData extends Record<string, unknown> = Record<string, unknown>,
+> = BinnedPointBasePayload<Metadata> & {
+  point_data?: PointData
+}
+
+export type BinnedPointTooltipPayload<
+  Metadata extends Record<string, unknown> = Record<string, unknown>,
+  PointData extends Record<string, unknown> = Record<string, unknown>,
+> = BinnedPointPayload<Metadata, PointData>
+
+export type BinnedPointLabelPlacementConfig = Partial<LabelPlacementConfig>
+
+export type BinnedPointLabelsConfig<
+  Metadata extends Record<string, unknown> = Record<string, unknown>,
+  PointData extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  render?: Snippet<[BinnedPointPayload<Metadata, PointData>]>
+  measure_text?: (payload: BinnedPointPayload<Metadata, PointData>) => string
+  font_size?: string
+  max_count?: number
+  gap_px?: number
+  placement?: BinnedPointLabelPlacementConfig
+  leaders?: {
+    min_length_px?: number
+  }
+}