canvas-globe 1.1.0 → 1.2.0

package/src/geo-globe.js

@@ -83,10 +83,24 @@ 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`;
@@ -141,6 +155,11 @@ export 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);
@@ -152,12 +171,138 @@ export 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;
@@ -714,9 +859,12 @@ export 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;
   }
@@ -734,6 +882,7 @@ export class GeoGlobe {
   destroy() {
     this._destroyed = true;
     cancelAnimationFrame(this._raf);
+    this.clearEffects();
     this.stopTour();
     this.stopStory();
     this.stopTimeline();
@@ -1188,6 +1337,15 @@ export 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;
@@ -1258,6 +1416,7 @@ export 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);
@@ -1438,13 +1597,20 @@ export 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;
@@ -1718,7 +1884,7 @@ export 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;
@@ -2272,7 +2438,7 @@ export 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";
@@ -3001,7 +3167,7 @@ export 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/src/license.js

@@ -24,9 +24,18 @@ const PRIVATE_HOST_PATTERNS = [
   /^::1$/,
 ];
 
+const OFFICIAL_SITE_HOSTS = new Set([
+  "canvasglobe.swiftools.com",
+  "canvas-globe-website.pages.dev",
+]);
+const OFFICIAL_PREVIEW_SUFFIX = ".canvas-globe-website.pages.dev";
+
 const normalizeLicenseKey = (value) =>
   typeof value === "string" ? value.trim() : "";
 
+const isOfficialSiteHost = (hostname) =>
+  OFFICIAL_SITE_HOSTS.has(hostname) || hostname.endsWith(OFFICIAL_PREVIEW_SUFFIX);
+
 /** Returns development, production or unknown for a browser location. */
 export function inspectRuntime(locationValue = globalThis.location) {
   if (!locationValue) return { kind: "unknown", hostname: "", public: false };
@@ -73,7 +82,7 @@ export function getLicensePresentation(
 ) {
   const status = inspectLicenseKey(value, mode);
   const runtime = inspectRuntime(locationValue);
-  if (!mode || status.valid || !runtime.public) {
+  if (!mode || status.valid || !runtime.public || isOfficialSiteHost(runtime.hostname)) {
     return { status, runtime, notice: null };
   }
   return {
@@ -93,6 +102,7 @@ export function reportLicenseStatus(value, mode = COMMERCIAL_LICENSE_MODE) {
   const presentation = getLicensePresentation(value, globalThis.location, mode);
   const { status } = presentation;
   if (typeof location === "undefined") return status;
+  if (!presentation.notice) return status;
   if (status.kind === "missing") {
     console.error(
       mode

package/src/places.js

@@ -0,0 +1,97 @@
+/**
+ * City search.
+ *
+ * An optional table of roughly 6,700 populated places  -  every national and
+ * state capital, plus the most populous cities worldwide. Import it only if
+ * you need it: it is about as large as the country geometry, and the core
+ * library already resolves countries and ~300 major cities for free through
+ * `geocode()`.
+ *
+ *   import { searchPlaces, placeSource } from "canvas-globe/places";
+ *   import { searchAndFly } from "canvas-globe/controls";
+ *
+ *   searchAndFly(globe, input, { source: placeSource() });
+ *
+ * For the long tail  -  every hamlet and village  -  point `source` at GeoNames,
+ * Nominatim or your own index instead. Nothing here needs to change.
+ */
+import { placeTable } from "./data/places.js";
+
+let index = null;
+
+/** Lowercase and strip accents, so "São Paulo" answers to "sao paulo". */
+export const fold = (s) =>
+  String(s)
+    .normalize("NFD")
+    .replace(/\p{Diacritic}/gu, "")
+    .toLowerCase()
+    .trim();
+
+const parse = () => {
+  if (index) return index;
+  index = [];
+  for (const row of placeTable.split(";")) {
+    const [name, lon, lat, country, pop, region] = row.split("|");
+    if (!name) continue;
+    index.push({
+      name,
+      key: fold(name),
+      lon: Number(lon) / 100,
+      lat: Number(lat) / 100,
+      country,
+      region: region || "",
+      population: Number(pop) * 1000,
+    });
+  }
+  return index;
+};
+
+const decorate = (p) => ({
+  ...p,
+  label: p.region ? `${p.name}, ${p.region}, ${p.country}` : `${p.name}, ${p.country}`,
+});
+
+/**
+ * Places matching `query`, best first.
+ *
+ * Names that start with the query always outrank names that merely contain
+ * it, so "york" still puts York above New York. Population breaks ties, which
+ * is what makes "london" mean the British one.
+ *
+ * At this table size a linear scan costs well under a millisecond, so there
+ * is no prefix tree to build or keep in sync. Build one only if you swap in a
+ * table an order of magnitude larger.
+ */
+export function searchPlaces(query, { limit = 8, country, contains = true } = {}) {
+  const q = fold(query);
+  if (!q) return [];
+  const hits = [];
+  for (const place of parse()) {
+    if (country && place.country !== country) continue;
+    const at = place.key.indexOf(q);
+    if (at < 0) continue;
+    if (at > 0 && !contains) continue;
+    hits.push({ place, tier: at === 0 ? 0 : 1, exact: place.key === q });
+  }
+  return hits
+    .sort((a, b) =>
+      a.tier - b.tier ||
+      b.exact - a.exact ||
+      b.place.population - a.place.population)
+    .slice(0, limit)
+    .map((h) => decorate(h.place));
+}
+
+/** Coordinate for an exact-ish name, matching the shape of `geocode()`. */
+export function placePoint(name, options) {
+  const [hit] = searchPlaces(name, { contains: false, ...options, limit: 1 });
+  return hit ? { lon: hit.lon, lat: hit.lat } : null;
+}
+
+/** Ready-made resolver for `searchAndFly({ source })`. */
+export function placeSource(options) {
+  return (query) => searchPlaces(query, options);
+}
+
+/** How many places the bundled table holds. */
+export const placeCount = () => parse().length;

package/src/recipes.js

@@ -0,0 +1,188 @@
+/**
+ * Recipes: complete looks, rather than single effects.
+ *
+ * Some things in the catalogue are not frame painters at all. They are a
+ * theme plus a few options plus, sometimes, a call into the imperative API
+ * (`tour`, `ping`, `playTimeline`). Shipping those as `use()`-able effects
+ * would hide the composition and give two ways to do the same thing, so they
+ * live here instead.
+ *
+ * A recipe is plain data:
+ *
+ *   { name, options, effects, start(globe) }
+ *
+ * which means you can read one, copy the parts you want, and ignore the rest.
+ *
+ *   import { createGlobe } from "canvas-globe";
+ *   import { applyRecipe, keynoteGlobe } from "canvas-globe/recipes";
+ *
+ *   const globe = createGlobe(canvas);
+ *   const stop = applyRecipe(globe, keynoteGlobe({ countries: 68 }));
+ */
+import { counterRoll, markerBloom } from "./fx/effects/data.js";
+import { glassSphere } from "./fx/effects/ambient.js";
+
+/**
+ * Applies a recipe and returns a function that undoes it: options are put
+ * back as they were, effects removed, and any timer the recipe started stopped.
+ */
+export function applyRecipe(globe, recipe) {
+  const { options, effects = [], start } = recipe;
+  const previous = {};
+  if (options) {
+    for (const key of Object.keys(options)) previous[key] = globe.o[key];
+    globe.setOptions(options);
+  }
+  for (const fx of effects) globe.use(fx);
+  const stop = start?.(globe);
+  return () => {
+    stop?.();
+    for (const fx of effects) globe.remove(fx);
+    if (options) globe.setOptions(previous);
+  };
+}
+
+/**
+ * Near-black sphere, violet landmass dots, arcs that bloom as they land.
+ * Ports catalogue effect BA.
+ */
+export const devPlatformGlobe = ({ hub, spokes = 9 } = {}) => ({
+  name: "devPlatformGlobe",
+  options: {
+    preset: "midnight",
+    landStyle: "dots",
+    dotSpacing: 2.1,
+    dotSize: 1.05,
+    autoRotate: true,
+    rotateSpeed: 0.055,
+    stars: false,
+    graticule: false,
+    theme: {
+      ocean: ["#0d1117", "#05070c"],
+      dot: "#a371f7",
+      land: "#a371f7",
+      arc: "#f778ba",
+      marker: "#58a6ff",
+    },
+  },
+  effects: [markerBloom()],
+  start(globe) {
+    const origin = hub || globe.markers[0];
+    if (!origin) return;
+    const previous = globe.o.arcs;
+    globe.setArcs(
+      globe.markers.slice(0, spokes).map((c, i) => ({
+        from: origin,
+        to: c,
+        duration: 1500 + i * 190,
+        width: 1.1,
+      }))
+    );
+    return () => globe.setArcs(previous);
+  },
+});
+
+/**
+ * Glossy charcoal sphere, hairline arcs, one enormous number, nothing else.
+ * Ports catalogue effect BB.
+ */
+export const keynoteGlobe = ({ hub, countries = 68, caption = "COUNTRIES" } = {}) => ({
+  name: "keynoteGlobe",
+  options: {
+    preset: "noir",
+    landStyle: "fill",
+    autoRotate: true,
+    rotateSpeed: 0.03,
+    stars: false,
+    graticule: false,
+    shade: true,
+    theme: {
+      ocean: ["#1c1c1e", "#000"],
+      land: "#3a3a3c",
+      border: "#48484a",
+      arc: "#ffffff",
+      marker: "#fff",
+    },
+  },
+  effects: [
+    glassSphere({ gloss: 0.16, rim: 0.2 }),
+    counterRoll({ to: countries, caption, size: 56, position: "bottom-center", hold: 1800 }),
+  ],
+  start(globe) {
+    const origin = hub || globe.markers[0];
+    if (!origin) return;
+    const previous = globe.o.arcs;
+    globe.setArcs(
+      globe.markers.slice(0, 7).map((c, i) => ({
+        from: origin,
+        to: c,
+        width: 0.8,
+        duration: 2600 + i * 200,
+      }))
+    );
+    return () => globe.setArcs(previous);
+  },
+});
+
+/**
+ * Great-circle rings that pass behind the sphere as it turns.
+ * Ports catalogue effect J, which is pure configuration.
+ */
+export const satelliteOrbits = ({ count = 3, preset = "neon", rotateSpeed = 0.08 } = {}) => ({
+  name: "satelliteOrbits",
+  options: { preset, orbits: count, autoRotate: true, rotateSpeed },
+});
+
+/**
+ * Markers appear as their date arrives across the range.
+ * Ports catalogue effect P, which drives the built-in timeline.
+ */
+export const growthOverTime = ({ duration = 4200, loop = true, preset = "midnight" } = {}) => ({
+  name: "growthOverTime",
+  options: { preset, mode: "map", autoRotate: false, markerStyle: "bubble" },
+  start(globe) {
+    globe.playTimeline({ duration, loop });
+    return () => globe.stopTimeline();
+  },
+});
+
+/**
+ * A repeating particle spray with a label at a milestone location.
+ * Ports catalogue effect R, which drives the built-in ping API.
+ */
+export const celebrationBurst = ({
+  at,
+  label = "10,000 users",
+  emoji = "🎉",
+  every = 3200,
+  burst = 26,
+} = {}) => ({
+  name: "celebrationBurst",
+  options: { preset: "neon", autoRotate: true, rotateSpeed: 0.05, markerStyle: "dot" },
+  start(globe) {
+    const where = at || globe.markers[0];
+    if (!where) return;
+    const fire = () => globe.ping({ ...where, emoji, label, burst, duration: 2600 });
+    fire();
+    const id = setInterval(fire, every);
+    return () => {
+      clearInterval(id);
+      globe.clearPings();
+    };
+  },
+});
+
+/**
+ * Spring-eased hops between locations on a timer.
+ * Ports catalogue effect V, which drives the built-in tour API.
+ */
+export const cityTour = ({ stops, dwell = 2000, zoom = 1.9 } = {}) => ({
+  name: "cityTour",
+  options: { preset: "atlas", autoRotate: false, labels: "markers" },
+  start(globe) {
+    const points = (stops || globe.markers).map((c) => ({ lon: c.lon, lat: c.lat }));
+    if (points.length < 2) return;
+    const handle = globe.tour(points, { dwell, zoom });
+    return () => handle.stop();
+  },
+});

package/src/version.js

@@ -1,2 +1,2 @@
 // Keep in sync with package.json. Release checks enforce this value.
-export const CANVAS_GLOBE_VERSION = "1.1.0";
+export const CANVAS_GLOBE_VERSION = "1.2.0";

package/types/charts.d.ts

@@ -0,0 +1,82 @@
+import type { GlobeEffect } from "./fx";
+
+/** Values keyed by ISO alpha-2 code or country name. */
+export type ValueMap = Record<string, number>;
+
+export declare function tilegram(options?: {
+  values?: ValueMap;
+  duration?: number;
+  hold?: number;
+  columns?: number;
+  tile?: number;
+  limit?: number;
+  hue?: number;
+}): GlobeEffect;
+
+export declare function chordDiagram(options?: {
+  regions?: string[];
+  /** `[fromIndex, toIndex, weight]` triples. */
+  flows?: [number, number, number][];
+  duration?: number;
+  hold?: number;
+  radius?: number;
+}): GlobeEffect;
+
+export declare function beeswarm(options?: {
+  values?: ValueMap;
+  duration?: number;
+  hold?: number;
+  dot?: number;
+  limit?: number;
+}): GlobeEffect;
+
+export declare function barRace(options?: {
+  values?: ValueMap;
+  duration?: number;
+  bars?: number;
+  accent?: string;
+  caption?: string;
+}): GlobeEffect;
+
+export declare function dotDensity(options?: {
+  values?: ValueMap;
+  duration?: number;
+  hold?: number;
+  per?: number;
+  color?: string;
+  seed?: number;
+}): GlobeEffect;
+
+export declare function cartogramMorph(options?: {
+  values?: ValueMap;
+  duration?: number;
+  hold?: number;
+  strength?: number;
+}): GlobeEffect;
+
+export declare function smallMultiples(options?: {
+  panels?: number;
+  columns?: number;
+  duration?: number;
+  labels?: (index: number) => string;
+  accent?: string;
+}): GlobeEffect;
+
+export declare function radarProfile(options?: {
+  axes?: string[];
+  series?: number[][];
+  duration?: number;
+  hold?: number;
+  colors?: string[];
+}): GlobeEffect;
+
+export declare function waffle(options?: {
+  total?: number;
+  filled?: number;
+  columns?: number;
+  cell?: number;
+  duration?: number;
+  hold?: number;
+  accent?: string;
+  caption?: string;
+}): GlobeEffect;