graphein 0.20.0 → 0.22.0

package/dist/charts/bubbleMap.js

@@ -0,0 +1,951 @@
+import { contrastRatio, ordinalColorScale, parseColor, rgbaToCss, sequential, sequentialColorScale, withAlpha } from "../color/index.js";
+import { formatValue } from "../format/index.js";
+import { backOut } from "../animation/easing.js";
+import { staggerProgress } from "../animation/stagger.js";
+import { boxesOverlap, fitLabel } from "../render/labelLedger.js";
+import { overlayTextToCanvasCmd } from "../render/overlayText.js";
+import { fontString, measureText } from "../render/text.js";
+import { RoughPen } from "../rough/index.js";
+import { roundedRect } from "../shape/index.js";
+import { resolveSketch } from "../spec/sketch.js";
+import { accessor, inferType, toKey, toNumber } from "../util/data.js";
+import { FOCUS_VEIL, hoverFocusEnabled, paintCutoutVeil } from "../interaction/veil.js";
+import { resolvePalette } from "../runtime/categories.js";
+import { addOverlayText, drawCategoricalLegend, drawTitleBlock } from "./chrome.js";
+import { drawColorRampLegend } from "./colorRamp.js";
+import { rowAlpha } from "./emphasis.js";
+import { albersParallels, centralMeridianOf, fitBounds, polygonsOf, projector, wrapDegrees } from "./geo.js";
+import { compositeOver, contrastTarget, inkOn, knownBackdrop, toneForContrast } from "./legibility.js";
+import { lerp, mixColor, mixFill, morphInput, morphKeyed, rampAt, stashMorphFrame, switchAt } from "./morphFrame.js";
+import { drawNoData } from "./noData.js";
+const TAU = Math.PI * 2;
+const bubbleAlpha = (tokens) => tokens.dark ? 0.8 : 0.7;
+const MIN_RADIUS = 2;
+const HOLLOW_RADIUS = 3;
+const PALE_CONTRAST = 1.6;
+const RING_CONTRAST = 3;
+const HIT_SLOP = 6;
+const ENTRANCE_STAGGER = 0.45;
+const MAX_LABELS = 60;
+const LABEL_AREA = 14e3;
+const LABEL_GAP = 3;
+const clamp = (v, lo, hi) => v < lo ? lo : v > hi ? hi : v;
+function numeric(value) {
+  return typeof value === "number" || typeof value === "string" ? toNumber(value) : NaN;
+}
+function fieldOf(def) {
+  const field = def?.field;
+  return typeof field === "string" && field !== "" ? field : void 0;
+}
+function insetRect(rect, pad) {
+  const p = Math.max(0, Math.min(pad, rect.width / 4, rect.height / 4));
+  return { x: rect.x + p, y: rect.y + p, width: rect.width - p * 2, height: rect.height - p * 2 };
+}
+function applyPadding(rect, padding) {
+  if (!padding || typeof padding !== "object") return rect;
+  const p = padding;
+  const side = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0;
+  const [top, right, bottom, left] = [side(p.top), side(p.right), side(p.bottom), side(p.left)];
+  const out = { x: rect.x + left, y: rect.y + top, width: rect.width - left - right, height: rect.height - top - bottom };
+  return out.width >= 8 && out.height >= 8 ? out : rect;
+}
+function readObservations(map, planar) {
+  const rows = Array.isArray(map.data) ? map.data : [];
+  const lonField = fieldOf(map.encoding?.longitude);
+  const latField = fieldOf(map.encoding?.latitude);
+  if (!lonField || !latField) return [];
+  const readLon = accessor(lonField);
+  const readLat = accessor(latField);
+  const sizeField = fieldOf(map.encoding?.size);
+  const readSize = sizeField ? accessor(sizeField) : null;
+  const out = [];
+  rows.forEach((row, index) => {
+    if (row == null || typeof row !== "object") return;
+    const lon = numeric(readLon(row));
+    const lat = numeric(readLat(row));
+    if (!Number.isFinite(lon) || !Number.isFinite(lat)) return;
+    if (!planar && (Math.abs(lon) > 180 || Math.abs(lat) > 90)) return;
+    let size = null;
+    if (readSize) {
+      size = numeric(readSize(row));
+      if (!Number.isFinite(size)) return;
+    }
+    out.push({ row, index, lon, lat, size });
+  });
+  return out;
+}
+function basemapPolygons(geo, planar) {
+  const features = geo && Array.isArray(geo.features) ? geo.features : [];
+  const out = [];
+  for (const feature of features) {
+    if (!feature || typeof feature !== "object") continue;
+    const parts = polygonsOf(feature);
+    if (!Array.isArray(parts)) continue;
+    for (const polygon of parts) {
+      if (!Array.isArray(polygon)) continue;
+      const rings = [];
+      for (const ring of polygon) {
+        if (!Array.isArray(ring)) continue;
+        const points = [];
+        for (const pos of ring) {
+          if (!Array.isArray(pos)) continue;
+          const [x, y] = pos;
+          if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y)) continue;
+          if (!planar && (Math.abs(x) > 360 || Math.abs(y) > 90)) continue;
+          points.push([x, y]);
+        }
+        if (points.length) rings.push(points);
+      }
+      if (rings.length) out.push(rings);
+    }
+  }
+  return out;
+}
+function radiusLimits(map, mapRect) {
+  const extent = Math.max(0, Math.min(mapRect.width, mapRect.height));
+  const ceiling = Math.max(4, extent / 2);
+  const requested = typeof map.maxRadius === "number" && Number.isFinite(map.maxRadius) && map.maxRadius > 0 ? Math.min(map.maxRadius, ceiling) : null;
+  const rMax = requested ?? clamp(extent * 0.06, 4, 40);
+  return { rMax, rMin: Math.min(MIN_RADIUS, rMax), dot: requested ?? clamp(extent * 0.012, 4, 6) };
+}
+function paletteOf(map, tokens) {
+  const valid = (colors) => Array.isArray(colors) ? colors.filter((c) => typeof c === "string" && parseColor(c) != null) : [];
+  const resolved = valid(resolvePalette(map.palette, tokens));
+  if (resolved.length) return resolved;
+  const theme = valid(tokens.color.palette);
+  return theme.length ? theme : ["#3b82f6"];
+}
+function categoryLabel(value, format) {
+  const key = toKey(value);
+  return key === "" ? "(blank)" : formatValue(value, format) || key;
+}
+function resolveColors(map, observations, tokens) {
+  const palette = paletteOf(map, tokens);
+  const scheme = map.scheme ?? "teal";
+  const field = fieldOf(map.encoding?.color);
+  if (!field) {
+    const fill = palette[0];
+    return { mode: "none", domain: null, scheme, entries: [], fillOf: () => ({ fill, value: void 0, noData: false }) };
+  }
+  const read = accessor(field);
+  const rows = observations.map((o) => o.row);
+  const declared = map.encoding.color?.type;
+  if ((declared ?? inferType(rows, field)) === "quantitative") {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const row of rows) {
+      const v = numeric(read(row));
+      if (!Number.isFinite(v)) continue;
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+    const domain = min <= max ? [min, max] : null;
+    const scale2 = domain && sequentialColorScale({ domain, interpolator: sequential(scheme) });
+    const noData = tokens.color.textMuted;
+    return {
+      mode: "numeric",
+      domain,
+      scheme,
+      entries: [],
+      fillOf: (row) => {
+        const raw = read(row);
+        const v = numeric(raw);
+        if (!scale2 || !domain || !Number.isFinite(v)) return { fill: noData, value: raw, noData: true };
+        return { fill: rgbaToCss(scale2.map(v)), ramp: { scheme, at: rampAt(domain, v) }, value: v, noData: false };
+      }
+    };
+  }
+  const keys = [];
+  const raws = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const raw = read(row);
+    const key = toKey(raw);
+    if (!raws.has(key)) {
+      raws.set(key, raw);
+      keys.push(key);
+    }
+  }
+  const scale = ordinalColorScale({ domain: keys, palette });
+  const format = map.encoding.color?.format;
+  return {
+    mode: "categorical",
+    domain: null,
+    scheme,
+    entries: keys.map((key) => ({ label: categoryLabel(raws.get(key), format), color: rgbaToCss(scale.map(key)), symbol: "circle" })),
+    fillOf: (row) => {
+      const raw = read(row);
+      return { fill: rgbaToCss(scale.map(toKey(raw))), value: raw, noData: false };
+    }
+  };
+}
+function legendVisible(legend) {
+  if (legend === false) return false;
+  return !(legend && typeof legend === "object" && legend.show === false);
+}
+function legendPosition(map, area, bounds) {
+  const requested = map.legend && typeof map.legend === "object" ? map.legend.position : void 0;
+  if (requested === "top" || requested === "right" || requested === "bottom" || requested === "left") return requested;
+  if (!(area.width > 0) || !(area.height > 0)) return "bottom";
+  const spanX = bounds ? bounds.maxX - bounds.minX : 0;
+  const spanY = bounds ? bounds.maxY - bounds.minY : 0;
+  const mapAspect = spanX > 0 && spanY > 0 ? spanX / spanY : 1.5;
+  return mapAspect > area.width / area.height ? "bottom" : "right";
+}
+function boundsOf(points) {
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (const [x, y] of points) {
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+  }
+  return { minX, maxX, minY, maxY };
+}
+function pointBounds(projected, observations, project, planar) {
+  const b = boundsOf(projected);
+  const tolerance = 1e-9 * Math.max(1, Math.abs(b.minX), Math.abs(b.maxX), Math.abs(b.minY), Math.abs(b.maxY));
+  if (b.maxX - b.minX > tolerance || b.maxY - b.minY > tolerance) return b;
+  let halfX = 1;
+  let halfY = 1;
+  if (!planar) {
+    const { lon, lat } = observations[0];
+    const [x0, y0] = project([lon - 1, clamp(lat - 1, -89, 89)]);
+    const [x1, y1] = project([lon + 1, clamp(lat + 1, -89, 89)]);
+    halfX = Math.abs(x1 - x0) / 2 || 1;
+    halfY = Math.abs(y1 - y0) / 2 || 1;
+  }
+  const cx = (b.minX + b.maxX) / 2;
+  const cy = (b.minY + b.maxY) / 2;
+  return { minX: cx - halfX, maxX: cx + halfX, minY: cy - halfY, maxY: cy + halfY };
+}
+function resolveProjection(kind, basemap, observations) {
+  const planar = kind === "identity";
+  const cone = (lats) => {
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const lat of lats) {
+      if (lat < lo) lo = lat;
+      if (lat > hi) hi = lat;
+    }
+    return lo <= hi ? albersParallels([lo, hi]) : void 0;
+  };
+  if (basemap.length) {
+    const lons = [];
+    const lats = [];
+    for (const polygon of basemap) {
+      for (const ring of polygon) {
+        for (const [x, y] of ring) {
+          lons.push(x);
+          lats.push(y);
+        }
+      }
+    }
+    const lon02 = planar ? 0 : centralMeridianOf(lons);
+    const project2 = projector(kind, lon02, kind === "albers" ? cone(lats) : void 0);
+    const projected = [];
+    const all = [];
+    for (const polygon of basemap) {
+      const rings = [];
+      for (const ring of polygon) {
+        const pts = [];
+        for (const pos of ring) {
+          const p = project2(pos);
+          if (!Number.isFinite(p[0]) || !Number.isFinite(p[1])) continue;
+          pts.push(p);
+          all.push(p);
+        }
+        if (pts.length >= 3) rings.push(pts);
+      }
+      if (rings.length) projected.push(rings);
+    }
+    const bounds = boundsOf(all);
+    if (projected.length && bounds.maxX - bounds.minX > 0 && bounds.maxY - bounds.minY > 0) {
+      return { project: project2, lon0: lon02, basemap: projected, bounds };
+    }
+  }
+  const lon0 = planar ? 0 : centralMeridianOf(observations.map((o) => o.lon));
+  const project = projector(kind, lon0, kind === "albers" ? cone(observations.map((o) => o.lat)) : void 0);
+  return { project, lon0, basemap: null, bounds: null };
+}
+const GRATICULE_STEPS = [0.1, 0.2, 0.5, 1, 2, 5, 10, 15, 30];
+function graticuleLines(kind, project, fit, observations, lon0) {
+  if (kind === "identity" || observations.length === 0) return [];
+  let relMin = Infinity;
+  let relMax = -Infinity;
+  let latMin = Infinity;
+  let latMax = -Infinity;
+  for (const o of observations) {
+    const d = wrapDegrees(o.lon - lon0);
+    relMin = Math.min(relMin, d);
+    relMax = Math.max(relMax, d);
+    latMin = Math.min(latMin, o.lat);
+    latMax = Math.max(latMax, o.lat);
+  }
+  const span = Math.max(relMax - relMin, latMax - latMin, 2);
+  const step = GRATICULE_STEPS.find((s) => span / s <= 10) ?? 30;
+  const latLimit = kind === "mercator" ? 80 : 90;
+  const lonLo = lon0 + Math.max(-180, relMin - span * 3);
+  const lonHi = lon0 + Math.min(180, relMax + span * 3);
+  const latLo = Math.max(-latLimit, latMin - span * 3);
+  const latHi = Math.min(latLimit, latMax + span * 3);
+  const toScreen = (lon, lat) => {
+    const [x, y] = project([lon, lat]);
+    const sx = fit.x(x);
+    const sy = fit.y(y);
+    return Number.isFinite(sx) && Number.isFinite(sy) ? [sx, sy] : null;
+  };
+  const lines = [];
+  const add = (points) => {
+    const line = points.filter((p) => p != null);
+    if (line.length >= 2) lines.push(line);
+  };
+  const arcSteps = kind === "albers" ? 48 : 1;
+  for (let k = Math.ceil(lonLo / step); k * step <= lonHi && lines.length < 200; k += 1) {
+    add([toScreen(k * step, latLo), toScreen(k * step, latHi)]);
+  }
+  for (let k = Math.ceil(latLo / step); k * step <= latHi && lines.length < 400; k += 1) {
+    const lat = k * step;
+    add(Array.from({ length: arcSteps + 1 }, (_, i) => toScreen(lonLo + (lonHi - lonLo) * i / arcSteps, lat)));
+  }
+  return lines;
+}
+function paintGraticule(surface, tokens, lines, clip, pen) {
+  if (!lines.length) return;
+  const ctx = surface.marks.ctx;
+  ctx.save();
+  ctx.beginPath();
+  ctx.rect(clip.x, clip.y, clip.width, clip.height);
+  ctx.clip();
+  ctx.setLineDash([]);
+  ctx.globalAlpha = 1;
+  ctx.lineWidth = 1;
+  ctx.strokeStyle = tokens.color.grid;
+  for (const line of lines) {
+    if (pen) {
+      pen.polyline(line.map(([x, y]) => ({ x, y })), { stroke: tokens.color.grid, strokeWidth: 1 });
+      continue;
+    }
+    ctx.beginPath();
+    line.forEach(([x, y], i) => i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y));
+    ctx.stroke();
+  }
+  ctx.restore();
+}
+function niceFloor(value) {
+  if (!(value > 0) || !Number.isFinite(value)) return 0;
+  const unit = 10 ** Math.floor(Math.log10(value));
+  const clean = (n) => Number(n.toPrecision(12));
+  let nice = clean(Math.floor(value / unit + 1e-9) * unit);
+  if (nice < value * 0.7) nice = clean(Math.floor(value * 10 / unit + 1e-9) * (unit / 10));
+  return nice > 0 ? nice : value;
+}
+function legendFormat(format, largest) {
+  if (largest < 1e4) return format ?? (largest >= 1e3 ? "," : void 0);
+  if (format == null) return "s";
+  const plain = /^(\$)?,?(\.\d+)?[fd]?$/.exec(format.trim());
+  return plain ? `${plain[1] ?? ""}s` : format;
+}
+function formatLocation(b, planar, map) {
+  const lonFormat = map.encoding?.longitude?.format;
+  const latFormat = map.encoding?.latitude?.format;
+  if (planar) return `${formatValue(b.lon, lonFormat)}, ${formatValue(b.lat, latFormat)}`;
+  const deg = (v, pos, neg, format) => {
+    const text = format ? formatValue(Math.abs(v), format) : formatValue(Math.round(Math.abs(v) * 100) / 100);
+    return `${text}\xB0${v < 0 ? neg : v > 0 ? pos : ""}`;
+  };
+  return `${deg(b.lat, "N", "S", latFormat)}, ${deg(b.lon, "E", "W", lonFormat)}`;
+}
+const BUBBLE_MORPH = {
+  lerp: (a, b, t) => ({
+    key: b.key,
+    x: lerp(a.x, b.x, t),
+    y: lerp(a.y, b.y, t),
+    r: lerp(a.r, b.r, t),
+    ...mixFill(a, b, t),
+    stroke: mixColor(a.stroke, b.stroke, t),
+    outlined: switchAt(a.outlined, b.outlined, t),
+    hollow: switchAt(a.hollow, b.hollow, t),
+    label: b.label,
+    emph: lerp(a.emph, b.emph, t),
+    alpha: lerp(a.alpha, b.alpha, t)
+  }),
+  enter: (b, t) => ({ ...b, r: b.r * t, alpha: t }),
+  exit: (a, t) => ({ ...a, r: a.r * (1 - t), alpha: a.alpha * (1 - t) })
+};
+const toMark = (b) => ({
+  key: b.key,
+  x: b.x,
+  y: b.y,
+  r: b.r,
+  fill: b.fill,
+  ramp: b.ramp,
+  stroke: b.stroke,
+  outlined: b.outlined,
+  hollow: b.hollow,
+  label: b.label,
+  emph: b.emph,
+  alpha: b.alpha
+});
+function paintBubbles(surface, marks, clip, pen, fillAlpha) {
+  const ctx = surface.marks.ctx;
+  ctx.save();
+  ctx.beginPath();
+  ctx.rect(clip.x, clip.y, clip.width, clip.height);
+  ctx.clip();
+  ctx.setLineDash([]);
+  for (const m of marks) {
+    const a = m.emph * m.alpha;
+    if (!(m.r > 0) || !(a > 0) || !Number.isFinite(m.x) || !Number.isFinite(m.y)) continue;
+    const dimmed = m.emph < 1;
+    if (pen) {
+      ctx.globalAlpha = a;
+      pen.circle(m.x, m.y, m.r, m.hollow ? { stroke: m.stroke, strokeWidth: 1.5 } : { fill: m.fill, fillAlpha, stroke: m.stroke, strokeWidth: 1 });
+    } else {
+      ctx.beginPath();
+      ctx.arc(m.x, m.y, m.r, 0, TAU);
+      if (m.hollow) {
+        ctx.globalAlpha = a;
+        ctx.strokeStyle = m.stroke;
+        ctx.lineWidth = 1.5;
+        ctx.stroke();
+      } else {
+        ctx.globalAlpha = fillAlpha * a;
+        ctx.fillStyle = m.fill;
+        ctx.fill();
+        ctx.globalAlpha = a;
+        ctx.strokeStyle = m.stroke;
+        ctx.lineWidth = 1;
+        ctx.stroke();
+      }
+    }
+    if (m.hollow) {
+      surface.evidence?.mark("point", m.x - m.r - 0.75, m.y - m.r - 0.75, m.r * 2 + 1.5, m.r * 2 + 1.5, m.stroke, a, clip, 1, void 0, dimmed);
+    } else {
+      const boundary = m.outlined ? { color: m.stroke, opacity: a, width: 1 } : void 0;
+      surface.evidence?.mark("point", m.x - m.r, m.y - m.r, m.r * 2, m.r * 2, m.fill, fillAlpha * a, clip, 1, void 0, dimmed, boundary);
+    }
+  }
+  ctx.globalAlpha = 1;
+  ctx.restore();
+}
+function paintBasemap(surface, tokens, polygons, bg, pen) {
+  const ctx = surface.marks.ctx;
+  ctx.save();
+  ctx.lineJoin = "round";
+  ctx.setLineDash([]);
+  ctx.globalAlpha = 1;
+  ctx.fillStyle = withAlpha(tokens.color.textMuted, tokens.dark ? 0.2 : 0.13);
+  ctx.strokeStyle = bg;
+  ctx.lineWidth = 0.8;
+  for (const polygon of polygons) {
+    ctx.beginPath();
+    for (const ring of polygon) {
+      ring.forEach(([x, y], i) => i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y));
+      ctx.closePath();
+    }
+    ctx.fill("evenodd");
+    if (!pen) ctx.stroke();
+  }
+  if (pen) {
+    const stroke = withAlpha(tokens.color.textMuted, 0.45);
+    for (const polygon of polygons) {
+      for (const ring of polygon) pen.polygon(ring.map(([x, y]) => ({ x, y })), { stroke, strokeWidth: 0.8 });
+    }
+  }
+  ctx.restore();
+}
+function drawLeavingBubbles(surface, clip, fillAlpha, context) {
+  const morph = morphInput(context);
+  const leaving = morph && Array.isArray(morph.from) ? morphKeyed(morph.from, [], morph.t, BUBBLE_MORPH).exits : [];
+  stashMorphFrame(surface, "bubbleMap", leaving);
+  if (leaving.length) paintBubbles(surface, leaving, clip, null, fillAlpha);
+}
+function entranceMarks(marks, t) {
+  const n = marks.length;
+  const rank = new Array(n);
+  marks.map((_, i) => i).sort((a, b) => marks[a].x - marks[b].x || a - b).forEach((index, position) => rank[index] = position);
+  const stagger = n >= 3 ? ENTRANCE_STAGGER : 0;
+  return marks.map((m, i) => ({ ...m, r: m.r * Math.max(0, staggerProgress(t, rank[i], n, stagger, backOut)) }));
+}
+function intersectArea(a, b) {
+  const w = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);
+  const h = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
+  return w > 0 && h > 0 ? w * h : 0;
+}
+function pointInRing(x, y, ring) {
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i, i += 1) {
+    const [xi, yi] = ring[i];
+    const [xj, yj] = ring[j];
+    if (yi > y !== yj > y && x < (xj - xi) * (y - yi) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+function landShare(rect, polygons) {
+  if (!polygons?.length) return 0;
+  let hits = 0;
+  let total = 0;
+  for (let i = 0; i < 4; i += 1) {
+    for (let j = 0; j < 3; j += 1) {
+      const x = rect.x + (i + 0.5) / 4 * rect.width;
+      const y = rect.y + (j + 0.5) / 3 * rect.height;
+      total += 1;
+      if (polygons.some((polygon) => polygon.length > 0 && pointInRing(x, y, polygon[0]) && !polygon.slice(1).some((hole) => pointInRing(x, y, hole)))) hits += 1;
+    }
+  }
+  return hits / total;
+}
+function drawSizeLegend(surface, tokens, map, args) {
+  const { mapRect, bubbles, sMax, limits, basemap, bg, pen } = args;
+  const sizeDef = map.encoding?.size;
+  const sizeField = fieldOf(sizeDef);
+  if (!sizeField || !(sMax > 0) || limits.rMax < 6 || mapRect.width < 260 || mapRect.height < 150) return null;
+  const labelSize = tokens.font.size.tiny;
+  const labelH = labelSize * 1.2;
+  const radius = (v) => Math.max(limits.rMin, limits.rMax * Math.sqrt(v / sMax));
+  const refs = [];
+  for (let v = niceFloor(sMax); refs.length < 3 && v > 0; v = niceFloor(v / 4)) {
+    const r = radius(v);
+    const prev = refs[refs.length - 1];
+    if (prev && (2 * (prev.r - r) < labelH + 1 || r < 3)) break;
+    refs.push({ value: v, r });
+  }
+  if (!refs.length) return null;
+  const texts = refs.map((ref) => formatValue(ref.value, legendFormat(sizeDef?.format, refs[0].value)));
+  const font = fontString(labelSize, tokens.font.family, tokens.font.weight.normal);
+  const titleFont = fontString(labelSize, tokens.font.family, tokens.font.weight.medium);
+  const title = sizeDef?.title ?? sizeField;
+  const r1 = refs[0].r;
+  const padX = 8;
+  const padY = 6;
+  const gap = 8;
+  const labelW = Math.max(...texts.map((text) => measureText(text, font).width));
+  const width = Math.min(180, Math.max(r1 * 2 + gap + labelW, measureText(title, titleFont).width) + padX * 2);
+  const titleH = labelH * 1.5 + 2;
+  const height = padY * 2 + titleH + r1 * 2;
+  if (width > mapRect.width * 0.45 || height > mapRect.height * 0.6) return null;
+  const m = 6;
+  const corners = [
+    { x: mapRect.x + m, y: mapRect.y + mapRect.height - m - height, width, height },
+    { x: mapRect.x + mapRect.width - m - width, y: mapRect.y + mapRect.height - m - height, width, height },
+    { x: mapRect.x + m, y: mapRect.y + m, width, height },
+    { x: mapRect.x + mapRect.width - m - width, y: mapRect.y + m, width, height }
+  ];
+  let best = null;
+  let bestScore = Infinity;
+  let bestOverlap = 0;
+  for (const rect of corners) {
+    let overlap = 0;
+    for (const b of bubbles) overlap += intersectArea(rect, { x: b.x - b.r, y: b.y - b.r, width: b.r * 2, height: b.r * 2 });
+    const score = overlap + landShare(rect, basemap) * width * height * 0.25;
+    if (score < bestScore) {
+      best = rect;
+      bestScore = score;
+      bestOverlap = overlap;
+    }
+  }
+  if (!best || bestOverlap > width * height * 0.08) return null;
+  const ctx = surface.marks.ctx;
+  const muted = tokens.color.textMuted;
+  ctx.save();
+  ctx.globalAlpha = 1;
+  ctx.setLineDash([]);
+  ctx.beginPath();
+  roundedRect(ctx, best.x, best.y, best.width, best.height, 6);
+  ctx.fillStyle = withAlpha(bg, 0.88);
+  ctx.fill();
+  ctx.lineWidth = 1;
+  ctx.strokeStyle = tokens.color.border;
+  ctx.stroke();
+  const cx = best.x + padX + r1;
+  const baseY = best.y + best.height - padY;
+  const labelX = best.x + padX + r1 * 2 + gap;
+  refs.forEach(({ r }) => {
+    if (pen) {
+      pen.circle(cx, baseY - r, r, { stroke: muted, strokeWidth: 1 });
+    } else {
+      ctx.beginPath();
+      ctx.arc(cx, baseY - r, r, 0, TAU);
+      ctx.fillStyle = withAlpha(muted, 0.06);
+      ctx.fill();
+      ctx.strokeStyle = muted;
+      ctx.lineWidth = 1;
+      ctx.stroke();
+    }
+    ctx.beginPath();
+    ctx.moveTo(cx, baseY - r * 2);
+    ctx.lineTo(labelX - 3, baseY - r * 2);
+    ctx.globalAlpha = 0.6;
+    ctx.strokeStyle = muted;
+    ctx.lineWidth = 0.75;
+    ctx.stroke();
+    ctx.globalAlpha = 1;
+  });
+  ctx.restore();
+  addOverlayText(surface, tokens, {
+    left: best.x + padX,
+    top: best.y + padY,
+    text: title,
+    maxWidth: best.width - padX * 2,
+    color: muted,
+    size: labelSize,
+    weight: tokens.font.weight.medium,
+    role: "legend",
+    path: "/encoding/size"
+  });
+  refs.forEach(({ r }, i) => {
+    addOverlayText(surface, tokens, {
+      left: labelX,
+      top: baseY - r * 2 - labelH / 2,
+      text: texts[i],
+      color: muted,
+      size: labelSize,
+      role: "legend",
+      path: "/encoding/size"
+    });
+  });
+  return best;
+}
+function addHaloLabel(surface, tokens, o) {
+  if (o.halo && surface.headless) {
+    const font = fontString(o.size, tokens.font.family, o.weight);
+    const fitted = fitLabel(o.text, o.maxWidth, font);
+    const cmd = overlayTextToCanvasCmd({ left: o.left, top: o.top, text: fitted.text, color: o.color, size: o.size }, font);
+    const ctx = surface.marks.ctx;
+    ctx.save();
+    ctx.globalAlpha = 0.9 * o.opacity;
+    ctx.font = font;
+    ctx.textAlign = cmd.align ?? "left";
+    ctx.textBaseline = cmd.baseline ?? "top";
+    ctx.lineJoin = "round";
+    ctx.lineWidth = 3;
+    ctx.strokeStyle = o.halo;
+    ctx.strokeText(fitted.text, cmd.x, cmd.y);
+    ctx.restore();
+  }
+  const el = addOverlayText(surface, tokens, {
+    left: o.left,
+    top: o.top,
+    text: o.text,
+    maxWidth: o.maxWidth,
+    color: o.color,
+    size: o.size,
+    weight: o.weight,
+    opacity: o.opacity < 1 ? o.opacity : void 0,
+    role: "data-label",
+    background: o.background,
+    path: "/labels"
+  });
+  if (o.halo && el) el.style.textShadow = `0 0 1px ${o.halo}, 0 0 2px ${o.halo}, 0 0 3px ${o.halo}`;
+}
+function drawBubbleLabels(surface, tokens, args) {
+  const { marks, mapRect, obstacles, opacity, bg, backdrop, fillAlpha } = args;
+  const size = tokens.font.size.small;
+  const weight = tokens.font.weight.medium;
+  const font = fontString(size, tokens.font.family, weight);
+  const h = size * 1.2;
+  const maxWidth = Math.max(24, Math.min(160, mapRect.width * 0.4));
+  const bounds = { x: mapRect.x + 1, y: mapRect.y + 1, width: mapRect.width - 2, height: mapRect.height - 2 };
+  const within = (box) => box.x >= bounds.x && box.y >= bounds.y && box.x + box.width <= bounds.x + bounds.width && box.y + box.height <= bounds.y + bounds.height;
+  const placed = [...obstacles];
+  const omit = (reason, example) => surface.labels?.omit({ role: "data-label", reason, required: false, example, path: "/labels" });
+  const budget = Math.max(3, Math.min(MAX_LABELS, Math.round(mapRect.width * mapRect.height / LABEL_AREA)));
+  const covers = (box, self) => marks.some((o, j) => {
+    if (j === self || !(o.r > 0)) return false;
+    const dx = Math.max(box.x - o.x, 0, o.x - (box.x + box.width));
+    const dy = Math.max(box.y - o.y, 0, o.y - (box.y + box.height));
+    return dx * dx + dy * dy < Math.max(0, o.r - 1) ** 2 || dx === 0 && dy === 0;
+  });
+  const order = marks.map((_, i) => i).filter((i) => marks[i].label !== "" && marks[i].r > 0 && marks[i].emph * marks[i].alpha >= 0.5).sort((a, b) => marks[b].r - marks[a].r || a - b);
+  order.forEach((index, rank) => {
+    const m = marks[index];
+    if (rank >= budget) return omit("space", m.label);
+    const fitted = fitLabel(m.label, maxWidth, font);
+    if (!fitted.text || fitted.truncated && fitted.text.length < m.label.length * 0.5) return omit("unreadable", m.label);
+    const w = measureText(fitted.text, font).width;
+    const spots = [];
+    if (!m.hollow && Math.hypot(w / 2, h / 2) <= m.r - 1.5) spots.push({ x: m.x - w / 2, y: m.y - h / 2, inside: true });
+    spots.push(
+      { x: m.x + m.r + LABEL_GAP, y: m.y - h / 2, inside: false },
+      { x: m.x - m.r - LABEL_GAP - w, y: m.y - h / 2, inside: false },
+      { x: m.x - w / 2, y: m.y - m.r - LABEL_GAP + 1 - h, inside: false },
+      { x: m.x - w / 2, y: m.y + m.r + LABEL_GAP - 1, inside: false }
+    );
+    const spot = spots.find((s) => {
+      const box = { x: s.x, y: s.y, width: w, height: h };
+      return within(box) && !placed.some((p) => boxesOverlap(p, box, -1)) && !covers(box, index);
+    });
+    if (!spot) return omit("collision", m.label);
+    placed.push({ x: spot.x, y: spot.y, width: w, height: h });
+    let color = tokens.color.text;
+    let background = bg;
+    if (spot.inside) {
+      const fill = parseColor(m.fill);
+      const under = fill && backdrop ? compositeOver(fill, fillAlpha * m.emph * m.alpha, backdrop) : null;
+      if (under) {
+        color = inkOn(under, tokens);
+        background = rgbaToCss(under);
+      }
+    }
+    addHaloLabel(surface, tokens, {
+      left: spot.x,
+      top: spot.y,
+      text: m.label,
+      maxWidth,
+      color,
+      size,
+      weight,
+      opacity,
+      halo: spot.inside ? null : bg,
+      background
+    });
+  });
+}
+function tooltipFor(map, b, planar) {
+  const enc = map.encoding;
+  const location = formatLocation(b, planar, map);
+  const rows = [];
+  const sizeField = fieldOf(enc.size);
+  const colorField = fieldOf(enc.color);
+  if (sizeField && b.size != null) {
+    const value = formatValue(b.size, enc.size?.format);
+    rows.push({ swatch: b.hollow ? b.stroke : b.fill, label: enc.size?.title ?? sizeField, value: b.hollow ? `${value} (not sized)` : value });
+  }
+  if (colorField && colorField !== sizeField) {
+    rows.push({
+      swatch: rows.length ? void 0 : b.fill,
+      label: enc.color?.title ?? colorField,
+      value: b.colorNoData ? "no data" : formatValue(b.colorValue, enc.color?.format)
+    });
+  }
+  if (b.label) return { title: b.label, rows: [...rows, { label: "location", value: location, muted: true }] };
+  if (rows.length) return { title: location, rows };
+  return { rows: [{ swatch: b.fill, label: "location", value: location }] };
+}
+function pickFor(map, b) {
+  const labelField = fieldOf(map.encoding?.label);
+  if (labelField && toKey(b.rawLabel) !== "") return { kind: "point", fields: [labelField], tuples: [[b.rawLabel]] };
+  const lonField = fieldOf(map.encoding?.longitude);
+  const latField = fieldOf(map.encoding?.latitude);
+  if (!lonField || !latField) return null;
+  return { kind: "point", fields: [lonField, latField], tuples: [[accessor(lonField)(b.row), accessor(latField)(b.row)]] };
+}
+function buildInteraction(map, tokens, mapRect, bubbles, bg, planar) {
+  const tt = map.tooltip;
+  const tooltipOn = !(tt === false || tt && typeof tt === "object" && tt.show === false);
+  const focusOn = hoverFocusEnabled(map);
+  const hit = (px, py) => {
+    for (let i = bubbles.length - 1; i >= 0; i -= 1) {
+      const b = bubbles[i];
+      const dx = px - b.x;
+      const dy = py - b.y;
+      if (dx * dx + dy * dy <= b.r * b.r) return b;
+    }
+    let best = null;
+    let bestGap = HIT_SLOP;
+    for (const b of bubbles) {
+      const gap = Math.hypot(px - b.x, py - b.y) - b.r;
+      if (gap <= bestGap) {
+        best = b;
+        bestGap = gap;
+      }
+    }
+    return best;
+  };
+  const paintHover = (ictx, b, strength) => {
+    if (focusOn) {
+      paintCutoutVeil(ictx, mapRect, bg, FOCUS_VEIL * strength, (c) => {
+        c.moveTo(b.x + b.r + 1, b.y);
+        c.arc(b.x, b.y, b.r + 1, 0, TAU);
+      });
+    }
+    ictx.save();
+    ictx.globalAlpha = strength;
+    for (const [width, color] of [[3, bg], [1.5, tokens.color.text]]) {
+      ictx.beginPath();
+      ictx.arc(b.x, b.y, b.r + 1.5, 0, TAU);
+      ictx.lineWidth = width;
+      ictx.strokeStyle = color;
+      ictx.stroke();
+    }
+    ictx.restore();
+  };
+  return {
+    region: mapRect,
+    hitTest: (px, py) => {
+      if (!tooltipOn) return null;
+      const b = hit(px, py);
+      if (!b) return null;
+      return {
+        key: String(b.index),
+        anchorX: b.x,
+        anchorY: b.y,
+        content: tooltipFor(map, b, planar),
+        paint: (ictx, state) => paintHover(ictx, b, state.focus),
+        draw: (ictx) => paintHover(ictx, b, 1)
+      };
+    },
+    pick: (px, py) => {
+      const b = hit(px, py);
+      return b ? pickFor(map, b) : null;
+    }
+  };
+}
+function drawBubbleMap(surface, spec, tokens, size, context) {
+  surface.evidence?.begin("rows");
+  surface.evidence?.data(0);
+  const map = spec;
+  const content = drawTitleBlock(surface, tokens, size, map.title);
+  const kind = map.projection ?? "mercator";
+  const planar = kind === "identity";
+  const observations = readObservations(map, planar);
+  const bg = map.background ?? tokens.color.background;
+  const fillAlpha = bubbleAlpha(tokens);
+  if (content.width <= 0 || content.height <= 0) {
+    drawLeavingBubbles(surface, content, fillAlpha, context);
+    drawNoData(surface, tokens, content);
+    return;
+  }
+  const projection = resolveProjection(kind, basemapPolygons(map.geo, planar), observations);
+  const projected = observations.map((o) => projection.project([o.lon, o.lat]));
+  const bounds = projection.bounds ?? (projected.length ? pointBounds(projected, observations, projection.project, planar) : null);
+  const showLegend = legendVisible(map.legend);
+  const colors = resolveColors(map, observations, tokens);
+  let area = content;
+  let rampRect = null;
+  if (showLegend && colors.mode === "numeric" && colors.domain) {
+    const legendHeight = Math.ceil(tokens.font.size.small + 26);
+    area = { ...content, height: Math.max(10, content.height - legendHeight) };
+    rampRect = { x: content.x, y: area.y + area.height + 4, width: content.width, height: legendHeight };
+  } else if (showLegend && colors.mode === "categorical" && colors.entries.length) {
+    area = drawCategoricalLegend(surface, tokens, content, colors.entries, legendPosition(map, content, bounds));
+  }
+  const mapRect = applyPadding(area, map.padding);
+  const limits = radiusLimits(map, mapRect);
+  const sized = fieldOf(map.encoding?.size) != null;
+  const reach = sized ? limits.rMax : limits.dot;
+  const fitRect = insetRect(mapRect, (projection.basemap ? reach / 2 : reach) + 1);
+  if (!bounds) {
+    drawLeavingBubbles(surface, mapRect, fillAlpha, context);
+    if (rampRect) drawRamp(surface, tokens, map, colors, rampRect);
+    drawNoData(surface, tokens, content);
+    return;
+  }
+  const fit = fitBounds(bounds, fitRect, !planar);
+  const basemap = projection.basemap?.map((polygon) => polygon.map((ring) => ring.map(([x, y]) => [fit.x(x), fit.y(y)]))) ?? null;
+  const placed = [];
+  observations.forEach((o, i) => {
+    const x = fit.x(projected[i][0]);
+    const y = fit.y(projected[i][1]);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return;
+    if (x < mapRect.x || x > mapRect.x + mapRect.width || y < mapRect.y || y > mapRect.y + mapRect.height) return;
+    placed.push({ o, x, y });
+  });
+  let sMax = 0;
+  for (const { o } of placed) if (o.size != null && o.size > sMax) sMax = o.size;
+  const radiusOf = (s) => {
+    if (!sized || s == null) return limits.dot;
+    if (s < 0) return Math.min(HOLLOW_RADIUS, limits.rMax);
+    if (!(sMax > 0)) return limits.rMin;
+    return Math.max(limits.rMin, limits.rMax * Math.sqrt(s / sMax));
+  };
+  const backdrop = knownBackdrop(surface, tokens);
+  const target = contrastTarget(backdrop, tokens);
+  const tones = /* @__PURE__ */ new Map();
+  const toneOf = (fill) => {
+    let tone = tones.get(fill);
+    if (!tone) {
+      const rgba = parseColor(fill);
+      const faint = rgba && backdrop && contrastRatio(compositeOver(rgba, fillAlpha, backdrop), backdrop) < PALE_CONTRAST;
+      tone = {
+        pale: faint ? toneForContrast(fill, target, backdrop, PALE_CONTRAST) : null,
+        ring: toneForContrast(fill, target, backdrop, RING_CONTRAST)
+      };
+      tones.set(fill, tone);
+    }
+    return tone;
+  };
+  const emphasis = context?.emphasis ?? null;
+  const labelField = fieldOf(map.encoding?.label);
+  const readLabel = labelField ? accessor(labelField) : null;
+  const labelFormat = map.encoding?.label?.format;
+  const bubbles = placed.map(({ o, x, y }) => {
+    const color = colors.fillOf(o.row);
+    const hollow = sized && o.size != null && o.size < 0;
+    const tone = toneOf(color.fill);
+    const rawLabel = readLabel ? readLabel(o.row) : void 0;
+    const labelKey = toKey(rawLabel);
+    return {
+      key: labelKey !== "" ? `l\0${labelKey}` : `p\0${o.lon},${o.lat}`,
+      x,
+      y,
+      r: radiusOf(o.size),
+      fill: color.fill,
+      ramp: color.ramp,
+      stroke: hollow ? tone.ring : tone.pale ?? bg,
+      outlined: !hollow && tone.pale != null,
+      hollow,
+      label: labelKey === "" ? "" : formatValue(rawLabel, labelFormat),
+      emph: rowAlpha(emphasis, o.row),
+      alpha: 1,
+      row: o.row,
+      index: o.index,
+      lon: o.lon,
+      lat: o.lat,
+      size: o.size,
+      colorValue: color.value,
+      colorNoData: color.noData,
+      rawLabel
+    };
+  });
+  bubbles.sort((a, b) => b.r - a.r || a.index - b.index);
+  const finalMarks = bubbles.map(toMark);
+  const morph = morphInput(context);
+  const moved = morph && Array.isArray(morph.from) ? morphKeyed(morph.from, finalMarks, morph.t, BUBBLE_MORPH) : null;
+  const entrance = !moved && context?.entranceProgress != null && context.entranceProgress < 1 ? Math.max(0, context.entranceProgress) : null;
+  const frame = moved ? [...moved.exits, ...moved.items] : entrance != null ? entranceMarks(finalMarks, entrance) : finalMarks;
+  stashMorphFrame(surface, "bubbleMap", frame);
+  const sketch = resolveSketch(map);
+  const pen = sketch ? new RoughPen(surface.marks.ctx, sketch) : null;
+  if (basemap) paintBasemap(surface, tokens, basemap, bg, pen);
+  else paintGraticule(surface, tokens, graticuleLines(kind, projection.project, fit, observations, projection.lon0), mapRect, pen);
+  paintBubbles(surface, frame, mapRect, pen, fillAlpha);
+  surface.evidence?.data(bubbles.length);
+  if (rampRect) drawRamp(surface, tokens, map, colors, rampRect);
+  const sizeKey = showLegend ? drawSizeLegend(surface, tokens, map, { mapRect, bubbles, sMax, limits, basemap, bg, pen }) : null;
+  if (map.labels === true && readLabel) {
+    const labelOpacity = entrance == null ? 1 : clamp((entrance - 0.8) / 0.2, 0, 1);
+    if (labelOpacity > 0) {
+      drawBubbleLabels(surface, tokens, {
+        marks: moved ? moved.items : finalMarks,
+        mapRect,
+        obstacles: sizeKey ? [sizeKey] : [],
+        opacity: labelOpacity,
+        bg,
+        backdrop,
+        fillAlpha
+      });
+    }
+  }
+  if (bubbles.length === 0) drawNoData(surface, tokens, content);
+  return buildInteraction(map, tokens, mapRect, bubbles, bg, planar);
+}
+function drawRamp(surface, tokens, map, colors, rect) {
+  if (!colors.domain) return;
+  drawColorRampLegend(surface, tokens, rect, {
+    domain: colors.domain,
+    scheme: colors.scheme,
+    format: map.encoding?.color?.format,
+    widthRatio: 0.5,
+    minWidth: 120,
+    maxWidth: 240,
+    path: "/encoding/color"
+  });
+}
+export {
+  drawBubbleMap
+};
+//# sourceMappingURL=bubbleMap.js.map