canvas-globe 1.1.1 → 1.3.0

package/dist/canvas-globe.umd.js

@@ -640,6 +640,76 @@ const withAlpha = (color, a) => {
   return color;
 };
 
+/**
+ * Aggregates projected points into a pointy-top hexagonal grid.
+ *
+ * The input is deliberately renderer-shaped (`{ x, y, depth, m }`) so the
+ * same helper works after either globe or flat-map projection. Each returned
+ * bin preserves its source markers for tooltips, clicks, and custom details.
+ */
+const hexBinPoints = (points = [], radius = 18) => {
+  const size = Math.max(1, Number(radius) || 18);
+  const sqrt3 = Math.sqrt(3);
+  const cells = new Map();
+
+  const roundAxial = (q, r) => {
+    let x = q;
+    let z = r;
+    let y = -x - z;
+    let rx = Math.round(x);
+    let ry = Math.round(y);
+    let rz = Math.round(z);
+    const dx = Math.abs(rx - x);
+    const dy = Math.abs(ry - y);
+    const dz = Math.abs(rz - z);
+    if (dx > dy && dx > dz) rx = -ry - rz;
+    else if (dy > dz) ry = -rx - rz;
+    else rz = -rx - ry;
+    return [rx, rz];
+  };
+
+  for (const point of points) {
+    if (!Number.isFinite(point?.x) || !Number.isFinite(point?.y)) continue;
+    const q = (sqrt3 / 3 * point.x - point.y / 3) / size;
+    const r = (2 * point.y / 3) / size;
+    const [hq, hr] = roundAxial(q, r);
+    const key = `${hq}:${hr}`;
+    let cell = cells.get(key);
+    if (!cell) {
+      cell = {
+        q: hq,
+        r: hr,
+        x: size * sqrt3 * (hq + hr / 2),
+        y: size * 1.5 * hr,
+        count: 0,
+        value: 0,
+        depth: 0,
+        lon: 0,
+        lat: 0,
+        weight: 0,
+        markers: [],
+      };
+      cells.set(key, cell);
+    }
+    const marker = point.m || {};
+    const value = Number(marker.count);
+    const weight = Number.isFinite(value) && value > 0 ? value : 1;
+    cell.count += 1;
+    cell.value += weight;
+    cell.depth = Math.max(cell.depth, Number(point.depth) || 0);
+    cell.lon += (Number(marker.lon) || 0) * weight;
+    cell.lat += (Number(marker.lat) || 0) * weight;
+    cell.weight += weight;
+    cell.markers.push(marker);
+  }
+
+  return [...cells.values()].map((cell) => ({
+    ...cell,
+    lon: cell.weight ? cell.lon / cell.weight : 0,
+    lat: cell.weight ? cell.lat / cell.weight : 0,
+  }));
+};
+
 const parseRGB = (color) => {
   if (color.startsWith("#")) {
     const hex = color.length === 4 ? color.replace(/#(.)(.)(.)/, "#$1$1$2$2$3$3") : color;
@@ -1314,7 +1384,7 @@ function drawFitted(ctx, media, box) {
 }
 
 // Keep in sync with package.json. Release checks enforce this value.
-const CANVAS_GLOBE_VERSION = "1.1.1";
+const CANVAS_GLOBE_VERSION = "1.3.0";
 
 /** Local license-key checks and production-use presentation helpers. */
 
@@ -1477,6 +1547,7 @@ const DEFAULTS = {
   timeline: null,
   transparentBackground: false,
   heatmap: false,
+  hexBins: false,
   spikes: false,
   labels: false,
   legend: null,
@@ -1520,13 +1591,28 @@ const DEFAULTS = {
   onCountryHover: null,
   onCountryClick: null,
   onRender: null,
+  effects: null,
 };
 
 const coord = (v) => (Array.isArray(v) ? [v[0], v[1]] : [v.lon ?? v.lng ?? v.longitude, v.lat ?? v.latitude]);
 
+const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+
+/**
+ * An effect's own 0→1 progress at a point on the shared clock. Derived purely
+ * from `ms`, so the same millisecond always renders the same frame.
+ */
+const phaseOf = (fx, ms) => {
+  const duration = Math.max(1, fx.duration ?? 1000);
+  const total = duration + (fx.hold ?? 0);
+  const elapsed = fx.loop === false ? Math.min(ms, total) : ((ms % total) + total) % total;
+  return Math.min(1, elapsed / duration);
+};
+
 const defaultTooltip = (target, kind) => {
   if (kind === "country") return target.name || String(target.id ?? "");
   if (kind === "cluster") return `${target.count} in this area`;
+  if (kind === "hex-bin") return `${target.markerCount} markers, value ${target.value}`;
   const name = target.city || target.name || target.label;
   const count = target.count != null ? `: ${target.count}` : "";
   return name ? `${name}${count}` : `${target.lat.toFixed(2)}, ${target.lon.toFixed(2)}${count}`;
@@ -1578,6 +1664,11 @@ class GeoGlobe {
     this._licenseHits = [];
     this._licenseDismissed = false;
     this._licenseHovered = false;
+    this._fx = [];
+    this._clock = null;
+    this._t0 = now();
+    this._spinBase = this.lon;
+    this.pointer = { x: 0, y: 0, lon: 0, lat: 0, over: false };
 
     this._applyWorld();
     this._applyMarkers(this.o.markers);
@@ -1589,12 +1680,138 @@ class GeoGlobe {
     this.resize();
     if (this.o.focus) this.focusOn(this.o.focus, { instant: true });
     if (this.o.showViewer) this._initViewer();
+    for (const fx of this.o.effects || []) this.use(fx);
     this._loop = this._loop.bind(this);
     this._raf = requestAnimationFrame(this._loop);
   }
 
   /* ------------------------------ public API ------------------------------ */
 
+  /* --------------------------------- effects ------------------------------- */
+
+  /** Installs an effect. Returns `this`, so calls chain. */
+  use(effect) {
+    if (!effect || typeof effect.frame !== "function") return this;
+    this._fx.push({ fx: effect, state: effect.setup?.(this) ?? {} });
+    this._fx.sort((a, b) => (a.fx.z ?? 0) - (b.fx.z ?? 0));
+    return this.invalidate();
+  }
+
+  /** Removes an effect by reference or by name. */
+  remove(effect) {
+    const i = this._fx.findIndex((e) => e.fx === effect || e.fx.name === effect);
+    if (i < 0) return this;
+    const [entry] = this._fx.splice(i, 1);
+    entry.fx.dispose?.(entry.state, this);
+    return this.invalidate();
+  }
+
+  clearEffects() {
+    while (this._fx.length) this.remove(this._fx[0].fx);
+    return this;
+  }
+
+  get effects() {
+    return this._fx.map((e) => e.fx);
+  }
+
+  /**
+   * Pins the effect clock to `ms`. Rendering becomes reproducible, which is
+   * what frame-exact export and seamless loops need. `play()` releases it.
+   */
+  seek(ms) {
+    // Capture where auto-rotation started from, so longitude can be derived
+    // from the clock instead of accumulated per frame. Only on the way in:
+    // seeking again while already seeked must not shift the origin.
+    if (this._clock == null) this._spinBase = wrapLon(this.lon - this._spinRate() * this._fxTime());
+    this._clock = Math.max(0, ms);
+    if (this._autoSpin()) this.lon = wrapLon(this._spinBase + this._spinRate() * this._clock);
+    return this.invalidate();
+  }
+
+  play() {
+    // Resume the timeline where it was paused rather than snapping back to 0.
+    if (this._clock != null) this._t0 = now() - this._clock;
+    this._clock = null;
+    return this.invalidate();
+  }
+
+  /** Draws the single frame that belongs at `ms` on the effect clock. */
+  renderFrame(ms) {
+    return this.seek(ms).render();
+  }
+
+  _fxTime() {
+    return this._clock != null ? this._clock : now() - this._t0;
+  }
+
+  /**
+   * Wall clock for looping scene animation. Pinned while seeking, so arcs,
+   * orbits and pulses land on the same phase every time a frame is redrawn.
+   */
+  _animTime() {
+    return this._clock != null ? this._clock : Date.now();
+  }
+
+  /** Degrees of auto-rotation per millisecond. */
+  _spinRate() {
+    return ((this.o.rotateSpeed || 0) * (this.o.fps || 30)) / 1000;
+  }
+
+  _runPasses(stage) {
+    if (!this._fx.length) return;
+    const ms = this._fxTime();
+    const { ctx } = this;
+    for (const entry of this._fx) {
+      if ((entry.fx.stage || "above") !== stage) continue;
+      ctx.save();
+      try {
+        entry.fx.frame(ctx, this, phaseOf(entry.fx, ms), entry.state);
+      } catch (err) {
+        // One bad effect must not take the render loop down with it.
+        if (!entry.failed) {
+          entry.failed = true;
+          console.error(`canvas-globe: effect "${entry.fx.name || "anonymous"}" failed`, err);
+        }
+      }
+      ctx.restore();
+    }
+  }
+
+  /** Land sample points as `[lon, lat]` pairs — what the dot matrix draws. */
+  landPoints(spacing) {
+    const prev = this.o.dotSpacing;
+    if (spacing != null) this.o.dotSpacing = spacing;
+    const flat = this._dotPoints();
+    this.o.dotSpacing = prev;
+    const out = [];
+    for (let i = 0; i < flat.length; i += 2) out.push([flat[i], flat[i + 1]]);
+    return out;
+  }
+
+  /** Traces a country outline into a path using the current projection. */
+  tracePath(shape, ctx = this.ctx, transform) {
+    const geom = shape?.geometry || shape;
+    if (!geom?.coordinates) return this;
+    const polys = geom.type === "Polygon" ? [geom.coordinates] : geom.coordinates;
+    for (const poly of polys) {
+      for (const ring of poly) {
+        let open = false;
+        for (const c of ring) {
+          const src = transform ? transform(c) : c;
+          const p = this.project(src[0], src[1]);
+          if (!p) {
+            open = false;
+            continue;
+          }
+          open ? ctx.lineTo(p.x, p.y) : (ctx.moveTo(p.x, p.y), (open = true));
+        }
+        if (open) ctx.closePath();
+      }
+    }
+    return this;
+  }
+
   setMarkers(markers = []) {
     this._applyMarkers(markers);
     this._focus = -1;
@@ -2151,9 +2368,12 @@ class GeoGlobe {
     const { w, h } = this._size();
     ctx.setTransform(this._dpr, 0, 0, this._dpr, 0, 0);
     ctx.clearRect(0, 0, w, h);
+    this._runPasses("beneath");
     this.hits = this.o.mode === "map" ? this._paintMap(w, h) : this._paintGlobe(w, h);
     this._dirty = false;
+    this._runPasses("above");
     this.o.onRender?.(this);
+    this._runPasses("post");
     this._paintLicenseNotice(w, h);
     return this;
   }
@@ -2171,6 +2391,7 @@ class GeoGlobe {
   destroy() {
     this._destroyed = true;
     cancelAnimationFrame(this._raf);
+    this.clearEffects();
     this.stopTour();
     this.stopStory();
     this.stopTimeline();
@@ -2625,6 +2846,15 @@ class GeoGlobe {
     this._onMove = (e) => {
       const [x, y] = this._local(e);
       this._pointer = { x: e.clientX, y: e.clientY };
+      this.pointer.x = x;
+      this.pointer.y = y;
+      this.pointer.over = true;
+      const at = this.unproject(x, y);
+      if (at) {
+        this.pointer.lon = at[0];
+        this.pointer.lat = at[1];
+      }
+      if (this._fx.length) this._dirty = true;
       const licenseHovered = this._licenseHitAt(x, y);
       if (licenseHovered !== this._licenseHovered) {
         this._licenseHovered = licenseHovered;
@@ -2678,7 +2908,7 @@ class GeoGlobe {
         this._cursor();
         this._dirty = true;
         const target = marker || this._hoveredCountry;
-        this._showTip(marker ? (marker.cluster ? "cluster" : "marker") : this._hoveredCountry ? "country" : null, target);
+        this._showTip(marker ? (marker.hexBin ? "hex-bin" : marker.cluster ? "cluster" : "marker") : this._hoveredCountry ? "country" : null, target);
       } else if (this._tipVisible) {
         this._placeTip();
       }
@@ -2695,6 +2925,7 @@ class GeoGlobe {
     this._onLeave = (e) => {
       this._onUp(e);
       this._pointer = null;
+      this.pointer.over = false;
       this._licenseHovered = false;
       if (this._hovered || this._hoveredCountry) {
         if (this._hovered) this.o.onHover?.(null, null);
@@ -2875,13 +3106,20 @@ class GeoGlobe {
 
   /* --------------------------------- loop --------------------------------- */
 
-  _spinning() {
+  /** Auto-rotation is configured and permitted, regardless of the clock. */
+  _autoSpin() {
     return !!this.o.autoRotate && !this._reducedMotion() && !this._drag && !this._vel && this.o.mode === "globe";
   }
 
+  /** Auto-rotation should advance on its own this frame. */
+  _spinning() {
+    return this._autoSpin() && this._clock == null;
+  }
+
   /** True while something on screen still needs to move. */
   _animating() {
     if (this._target || this._drag || this._vel) return true;
+    if (this._fx.length && this._clock == null) return true;
     if (this._spinning()) return true;
     if (this._reducedMotion()) return false;
     if (this._hasLive || this._pings.length) return true;
@@ -3155,7 +3393,7 @@ class GeoGlobe {
     const list = this._orbitList();
     if (!list.length) return;
     const { ctx } = this;
-    const spin = this._reducedMotion() ? 0 : (Date.now() / 1000) % 3600;
+    const spin = this._reducedMotion() ? 0 : (this._animTime() / 1000) % 3600;
     ctx.lineCap = "round";
     for (const orbit of list) {
       const inc = (orbit.inclination ?? 30) * D2R;
@@ -3709,7 +3947,7 @@ class GeoGlobe {
     const arcs = this.o.arcs;
     if (!arcs || !arcs.length) return;
     const { ctx } = this;
-    const now = Date.now();
+    const now = this._animTime();
     const still = this._reducedMotion();
     ctx.lineCap = "round";
     ctx.lineJoin = "round";
@@ -3858,6 +4096,87 @@ class GeoGlobe {
     ctx.restore();
   }
 
+  /** Aggregate projected markers into an interactive hexagonal density layer. */
+  _paintHexBins(pts, t, cx, cy, globeRadius, w, h) {
+    const o = this.o.hexBins === true ? {} : this.o.hexBins;
+    const { ctx } = this;
+    const radius = Math.max(4, o.radius ?? 18);
+    const padding = clamp(o.padding ?? 1.5, 0, radius * 0.45);
+    const drawRadius = radius - padding;
+    const minValue = Math.max(0, o.minValue ?? 1);
+    const metric = o.value === "count" ? "count" : "value";
+    const bins = hexBinPoints(pts, radius).filter((bin) => {
+      if (bin[metric] < minValue) return false;
+      if (this.o.mode === "globe") return Math.hypot(bin.x - cx, bin.y - cy) <= globeRadius + drawRadius;
+      return bin.x >= -drawRadius && bin.x <= w + drawRadius && bin.y >= -drawRadius && bin.y <= h + drawRadius;
+    });
+    const max = Math.max(1, ...bins.map((bin) => bin[metric]));
+    const range = Array.isArray(o.colorRange) && o.colorRange.length > 1
+      ? o.colorRange
+      : [t.ocean[0], o.color || t.marker];
+    const domain = range.map((_, index) => max * index / (range.length - 1));
+    const scale = colorScale(domain, range);
+    const hits = [];
+
+    ctx.save();
+    if (this.o.mode === "globe") {
+      ctx.beginPath();
+      ctx.arc(cx, cy, globeRadius, 0, TAU);
+      ctx.clip();
+    } else {
+      ctx.beginPath();
+      ctx.rect(0, 0, w, h);
+      ctx.clip();
+    }
+
+    ctx.lineJoin = "round";
+    for (const bin of bins) {
+      const value = bin[metric];
+      ctx.beginPath();
+      for (let i = 0; i < 6; i++) {
+        const angle = (60 * i - 30) * D2R;
+        const x = bin.x + drawRadius * Math.cos(angle);
+        const y = bin.y + drawRadius * Math.sin(angle);
+        i ? ctx.lineTo(x, y) : ctx.moveTo(x, y);
+      }
+      ctx.closePath();
+      ctx.globalAlpha = clamp(o.opacity ?? 0.82, 0, 1);
+      ctx.fillStyle = scale(value) || o.color || t.marker;
+      ctx.fill();
+      if ((o.strokeWidth ?? 0.8) > 0) {
+        ctx.globalAlpha = 1;
+        ctx.strokeStyle = o.stroke || withAlpha(t.label, 0.3);
+        ctx.lineWidth = o.strokeWidth ?? 0.8;
+        ctx.stroke();
+      }
+      if (o.showCount && drawRadius >= 10) {
+        ctx.globalAlpha = 1;
+        ctx.fillStyle = o.labelColor || t.label;
+        ctx.font = `600 ${Math.max(9, Math.min(13, drawRadius * 0.7))}px Inter,system-ui,sans-serif`;
+        ctx.textAlign = "center";
+        ctx.textBaseline = "middle";
+        ctx.fillText(String(value), bin.x, bin.y);
+      }
+      hits.push({
+        marker: {
+          hexBin: true,
+          count: bin.count,
+          value: bin.value,
+          markerCount: bin.count,
+          markers: bin.markers,
+          lon: bin.lon,
+          lat: bin.lat,
+        },
+        x: bin.x,
+        y: bin.y,
+        r: drawRadius,
+      });
+    }
+    ctx.restore();
+    this._lastHexBins = bins;
+    return hits;
+  }
+
   /** Spike height for a marker, as a fraction of the globe radius. */
   _spikeLift(m) {
     if (!this.o.spikes) return 0;
@@ -4238,9 +4557,11 @@ class GeoGlobe {
       pts.push({ m, x: cx + x, y: cy + y, depth: 0.65 + c * 0.35 });
     }
     if (this.o.heatmap) this._paintHeatmap(pts, t);
+    const binHits = this.o.hexBins ? this._paintHexBins(pts, t, cx, cy, r, w, h) : [];
     if (this.o.spikes) this._paintSpikes(t, cx, cy, r, w, h, null);
     this._paintViewerAccuracy(t, cx, cy, r, null);
-    const hits = this._paintMarkers(pts, t);
+    const showMarkers = !this.o.hexBins || (this.o.hexBins !== true && this.o.hexBins.hideMarkers === false);
+    const hits = [...binHits, ...(showMarkers ? this._paintMarkers(pts, t) : [])];
     if (this.o.labels) this._paintLabels(pts, t, cx, cy, r, w, h);
     this._paintAnnotations(t);
     this._paintPings(t);
@@ -4315,9 +4636,11 @@ class GeoGlobe {
       pts.push({ m, x, y, depth: 1 });
     }
     if (this.o.heatmap) this._paintHeatmap(pts, t);
+    const binHits = this.o.hexBins ? this._paintHexBins(pts, t, 0, 0, 0, w, h) : [];
     if (this.o.spikes) this._paintSpikes(t, 0, 0, 0, w, h, fwd);
     this._paintViewerAccuracy(t, 0, 0, 0, fwd);
-    const hits = this._paintMarkers(pts, t);
+    const showMarkers = !this.o.hexBins || (this.o.hexBins !== true && this.o.hexBins.hideMarkers === false);
+    const hits = [...binHits, ...(showMarkers ? this._paintMarkers(pts, t) : [])];
     if (this.o.labels) this._paintLabels(pts, t, 0, 0, 0, w, h);
     this._paintAnnotations(t);
     this._paintPings(t);
@@ -4438,7 +4761,7 @@ class GeoGlobe {
     }
 
     if (m.live && !this._reducedMotion()) {
-      const pulse = (Date.now() % 2200) / 2200;
+      const pulse = (this._animTime() % 2200) / 2200;
       ctx.globalAlpha = 1 - pulse;
       ctx.strokeStyle = t.live;
       ctx.lineWidth = 1.4 * scale;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-globe",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Build interactive 3D globes and flat world maps in JavaScript, React, Vue, Angular, or Svelte with Canvas 2D and no WebGL.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": {
@@ -66,6 +66,36 @@
       "import": "./src/react.js",
       "default": "./src/react.js"
     },
+    "./fx": {
+      "types": "./types/fx.d.ts",
+      "import": "./src/fx/index.js",
+      "default": "./src/fx/index.js"
+    },
+    "./fx/interaction": {
+      "types": "./types/fx-interaction.d.ts",
+      "import": "./src/fx/effects/interaction.js",
+      "default": "./src/fx/effects/interaction.js"
+    },
+    "./recipes": {
+      "types": "./types/recipes.d.ts",
+      "import": "./src/recipes.js",
+      "default": "./src/recipes.js"
+    },
+    "./charts": {
+      "types": "./types/charts.d.ts",
+      "import": "./src/charts.js",
+      "default": "./src/charts.js"
+    },
+    "./controls": {
+      "types": "./types/controls.d.ts",
+      "import": "./src/controls.js",
+      "default": "./src/controls.js"
+    },
+    "./places": {
+      "types": "./types/places.d.ts",
+      "import": "./src/places.js",
+      "default": "./src/places.js"
+    },
     "./data/world": {
       "types": "./types/data/world.d.ts",
       "import": "./src/data/world.js",
@@ -95,7 +125,9 @@
   "scripts": {
     "start": "node scripts/serve.mjs",
     "build": "node scripts/build.mjs",
-    "data": "node scripts/generate-data.mjs && node scripts/generate-timezones.mjs",
+    "data": "node scripts/generate-data.mjs && node scripts/generate-timezones.mjs && node scripts/generate-places.mjs",
+    "places": "node scripts/generate-places.mjs",
+    "audit:docs": "node scripts/audit-docs.mjs",
     "example": "node scripts/serve.mjs",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",