canvas-globe 0.1.0

package/src/scenes.js

@@ -0,0 +1,80 @@
+/**
+ * Scenes are whole compositions, not just palettes: a preset plus the layers,
+ * motion and overlays a given job needs. Presets answer "how should it look",
+ * scenes answer "what am I making".
+ */
+export const scenes = {
+  /** Live signups on a pricing or landing page. */
+  signups: {
+    preset: "hologram",
+    mode: "globe",
+    autoRotate: true,
+    rotateSpeed: 0.06,
+    cluster: true,
+    tooltip: true,
+    showViewer: true,
+    counter: { label: "signups this week", position: "top-left" },
+  },
+  /** A regional launch announcement, ready for country media. */
+  launch: {
+    preset: "atlas",
+    mode: "map",
+    landStyle: "fill",
+    graticule: false,
+    stars: false,
+    autoRotate: false,
+    focus: { isolate: true, outlineWidth: 2, dim: 1 },
+  },
+  /** "Trusted in N countries" with customer logos. */
+  logos: {
+    preset: "mono",
+    mode: "map",
+    markerStyle: "auto",
+    labels: false,
+    autoRotate: false,
+    graticule: false,
+    cluster: true,
+    clusterRadius: 54,
+  },
+  /** Where the team is, for a careers page. */
+  team: {
+    preset: "atlas",
+    mode: "map",
+    labels: "markers",
+    autoRotate: false,
+    graticule: false,
+    tooltip: true,
+  },
+  /** Campaign or revenue coverage by country. */
+  coverage: {
+    preset: "mono",
+    mode: "map",
+    countryColors: null,
+    labels: false,
+    autoRotate: false,
+    legend: { title: "Coverage", position: "bottom-left" },
+  },
+  /** Scroll-linked year in review. */
+  review: {
+    preset: "midnight",
+    mode: "globe",
+    autoRotate: false,
+    arcs: [],
+    counter: { label: "customers", position: "bottom-left" },
+  },
+  /** Traffic between regions. */
+  routes: {
+    preset: "blueprint",
+    mode: "globe",
+    autoRotate: true,
+    arcLift: 0.32,
+    orbits: 2,
+  },
+};
+
+/** Option keys a scene owns, so switching scenes cannot leak state. */
+export const sceneKeys = [
+  "preset", "mode", "landStyle", "graticule", "stars", "autoRotate", "rotateSpeed", "cluster",
+  "clusterRadius", "tooltip", "labels", "legend", "counter", "focus", "countryColors", "orbits",
+  "arcLift", "showViewer", "markerStyle",
+];

package/src/texture.js

@@ -0,0 +1,129 @@
+/**
+ * Maps an equirectangular image onto the orthographic sphere, pixel by pixel.
+ *
+ * The per-pixel inverse projection is the whole cost, so it is rendered at a
+ * reduced resolution and upscaled: roughly 2 ms for a 430 px globe, which
+ * fits comfortably inside a 30 fps budget.
+ */
+import { D2R, R2D, clamp } from "./geo.js";
+
+const makeSurface = (w, h) => {
+  if (typeof OffscreenCanvas !== "undefined") return new OffscreenCanvas(w, h);
+  if (typeof document === "undefined") return null;
+  const c = document.createElement("canvas");
+  c.width = w;
+  c.height = h;
+  return c;
+};
+
+export class SphereTexture {
+  /** `source` is a URL, HTMLImageElement, ImageBitmap or canvas. */
+  constructor(source, { maxWidth = 2048, onLoad } = {}) {
+    this.ready = false;
+    this.error = null;
+    this._onLoad = onLoad;
+    this._maxWidth = maxWidth;
+    if (typeof source === "string") this._loadUrl(source);
+    else if (source) this._ingest(source);
+  }
+
+  _loadUrl(url) {
+    if (typeof Image === "undefined") return;
+    const img = new Image();
+    // Required so the pixels stay readable when the image is cross-origin.
+    img.crossOrigin = "anonymous";
+    img.onload = () => this._ingest(img);
+    img.onerror = () => {
+      this.error = new Error(`canvas-globe: could not load texture "${url}"`);
+      this._onLoad?.(this);
+    };
+    img.src = url;
+  }
+
+  _ingest(image) {
+    const sw = image.naturalWidth || image.width;
+    const sh = image.naturalHeight || image.height;
+    if (!sw || !sh) return;
+    const w = Math.min(this._maxWidth, sw);
+    const h = Math.round((w / sw) * sh);
+    const surface = makeSurface(w, h);
+    if (!surface) return;
+    const ctx = surface.getContext("2d", { willReadFrequently: true });
+    ctx.drawImage(image, 0, 0, w, h);
+    try {
+      const data = ctx.getImageData(0, 0, w, h);
+      this.pixels = data.data;
+      this.tw = w;
+      this.th = h;
+      this.ready = true;
+    } catch {
+      this.error = new Error("canvas-globe: texture is cross-origin and could not be read");
+    }
+    this._onLoad?.(this);
+  }
+
+  /** Paints the lit hemisphere into `ctx`, centred at cx,cy with radius r. */
+  draw(ctx, cx, cy, r, lon0, lat0, { step = 2, shade = true } = {}) {
+    if (!this.ready || r <= 0) return false;
+    const size = Math.max(2, Math.ceil((r * 2) / step));
+    if (!this._surface || this._size !== size) {
+      this._surface = makeSurface(size, size);
+      if (!this._surface) return false;
+      this._ctx = this._surface.getContext("2d");
+      this._image = this._ctx.createImageData(size, size);
+      this._size = size;
+    }
+    const out = this._image.data;
+    const { pixels, tw, th } = this;
+    const f0 = lat0 * D2R;
+    const s0 = Math.sin(f0), c0 = Math.cos(f0);
+    const inv = 2 / size;
+
+    for (let py = 0; py < size; py++) {
+      const yu = 1 - (py + 0.5) * inv;
+      const yu2 = yu * yu;
+      let o = py * size * 4;
+      for (let px = 0; px < size; px++, o += 4) {
+        const x = (px + 0.5) * inv - 1;
+        const q = x * x + yu2;
+        if (q > 1) {
+          out[o + 3] = 0;
+          continue;
+        }
+        const z = Math.sqrt(1 - q);
+        const ey = c0 * z - s0 * yu;
+        const ez = s0 * z + c0 * yu;
+        const lat = Math.asin(clamp(ez, -1, 1)) * R2D;
+        const lon = lon0 + Math.atan2(x, ey) * R2D;
+        let u = Math.floor((((lon + 180) % 360) + 360) % 360 * (tw / 360));
+        if (u >= tw) u -= tw;
+        const v = clamp(Math.floor(((90 - lat) / 180) * th), 0, th - 1);
+        const s = (v * tw + u) * 4;
+        const k = shade ? 0.55 + 0.45 * z : 1;
+        out[o] = pixels[s] * k;
+        out[o + 1] = pixels[s + 1] * k;
+        out[o + 2] = pixels[s + 2] * k;
+        out[o + 3] = 255;
+      }
+    }
+    this._ctx.putImageData(this._image, 0, 0);
+    ctx.drawImage(this._surface, cx - r, cy - r, r * 2, r * 2);
+    return true;
+  }
+
+  /** Paints the whole texture into a flat-map viewport. */
+  drawFlat(ctx, fwd, w, h) {
+    if (!this.ready || !this._surface2) {
+      if (!this.ready) return false;
+      this._surface2 = makeSurface(this.tw, this.th);
+      if (!this._surface2) return false;
+      const c = this._surface2.getContext("2d");
+      const img = c.createImageData(this.tw, this.th);
+      img.data.set(this.pixels);
+      c.putImageData(img, 0, 0);
+    }
+    const a = fwd(-180, 90), b = fwd(180, -90);
+    ctx.drawImage(this._surface2, a[0], a[1], b[0] - a[0], b[1] - a[1]);
+    return true;
+  }
+}

package/src/themes.js

@@ -0,0 +1,241 @@
+/** Built-in palettes. Pass your own object to `theme` to override any key. */
+export const themes = {
+  atlas: {
+    ocean: ["#c2e7fb", "#7cc0e8"],
+    land: "#cfe7b6",
+    border: "rgba(206,116,130,.55)",
+    graticule: "rgba(255,255,255,.2)",
+    atmosphere: "rgba(125,185,255,.45)",
+    rim: "rgba(255,255,255,.5)",
+    marker: "#6d28d9",
+    markerGlow: "rgba(109,40,217,.45)",
+    live: "#22c55e",
+    bubble: "#ffffff",
+    label: "#0f172a",
+    stars: "rgba(255,255,255,.75)",
+    dot: "#5b8c3a",
+    glow: "rgba(206,116,130,.9)",
+    orbit: "rgba(109,40,217,.35)",
+    arc: "#6d28d9",
+    arcHead: "#f97316",
+    night: "rgba(9,17,38,.42)",
+    cluster: "#4c1d95",
+    clusterLabel: "#ffffff",
+    focus: "#f59e0b",
+    countryHover: "rgba(255,255,255,.35)",
+    shade: true,
+  },
+  midnight: {
+    ocean: ["#16224a", "#070b18"],
+    land: "#39496b",
+    border: "rgba(148,163,184,.4)",
+    graticule: "rgba(148,163,184,.14)",
+    atmosphere: "rgba(129,140,248,.34)",
+    rim: "rgba(168,85,247,.6)",
+    marker: "#e879f9",
+    markerGlow: "rgba(232,121,249,.5)",
+    live: "#4ade80",
+    bubble: "#0f172a",
+    label: "#e2e8f0",
+    stars: "rgba(255,255,255,.8)",
+    dot: "#818cf8",
+    glow: "rgba(129,140,248,.9)",
+    orbit: "rgba(168,85,247,.4)",
+    arc: "#a78bfa",
+    arcHead: "#f0abfc",
+    night: "rgba(2,4,12,.5)",
+    cluster: "#7c3aed",
+    clusterLabel: "#f8fafc",
+    focus: "#fbbf24",
+    countryHover: "rgba(255,255,255,.16)",
+    shade: true,
+  },
+  mono: {
+    ocean: ["#f8fafc", "#e2e8f0"],
+    land: "#cbd5e1",
+    border: "rgba(100,116,139,.5)",
+    graticule: "rgba(100,116,139,.16)",
+    atmosphere: "rgba(148,163,184,.3)",
+    rim: "rgba(71,85,105,.45)",
+    marker: "#0f172a",
+    markerGlow: "rgba(15,23,42,.3)",
+    live: "#16a34a",
+    bubble: "#ffffff",
+    label: "#0f172a",
+    stars: "rgba(148,163,184,.6)",
+    dot: "#64748b",
+    glow: "rgba(71,85,105,.8)",
+    orbit: "rgba(71,85,105,.3)",
+    arc: "#334155",
+    arcHead: "#0f172a",
+    night: "rgba(15,23,42,.28)",
+    cluster: "#334155",
+    clusterLabel: "#ffffff",
+    focus: "#2563eb",
+    countryHover: "rgba(15,23,42,.16)",
+    shade: false,
+  },
+  /** Cyan dot-matrix earth on deep navy. */
+  hologram: {
+    ocean: ["rgba(10,26,53,.92)", "rgba(2,7,18,.98)"],
+    land: "rgba(56,189,248,.07)",
+    border: "rgba(56,189,248,.3)",
+    graticule: "rgba(56,189,248,.26)",
+    atmosphere: "rgba(56,189,248,.34)",
+    rim: "rgba(125,211,252,.85)",
+    marker: "#22d3ee",
+    markerGlow: "rgba(34,211,238,.5)",
+    live: "#5eead4",
+    bubble: "#04182b",
+    label: "#e0f2fe",
+    stars: "rgba(186,230,253,.7)",
+    dot: "#38bdf8",
+    glow: "rgba(56,189,248,.95)",
+    orbit: "rgba(125,211,252,.45)",
+    arc: "#22d3ee",
+    arcHead: "#a5f3fc",
+    night: "rgba(1,4,12,.45)",
+    cluster: "#0e7490",
+    clusterLabel: "#ecfeff",
+    focus: "#fbbf24",
+    countryHover: "rgba(56,189,248,.22)",
+    shade: false,
+  },
+  /** Magenta continents with a cyan rim: the "cyber network" look. */
+  neon: {
+    ocean: ["#180a2e", "#05010f"],
+    land: "rgba(236,72,153,.16)",
+    border: "#f472b6",
+    graticule: "rgba(168,85,247,.2)",
+    atmosphere: "rgba(168,85,247,.5)",
+    rim: "rgba(34,211,238,.9)",
+    marker: "#22d3ee",
+    markerGlow: "rgba(34,211,238,.55)",
+    live: "#f0abfc",
+    bubble: "#1a0b2e",
+    label: "#fae8ff",
+    stars: "rgba(240,171,252,.75)",
+    dot: "#f472b6",
+    glow: "rgba(236,72,153,1)",
+    orbit: "rgba(34,211,238,.4)",
+    arc: "#22d3ee",
+    arcHead: "#f0abfc",
+    night: "rgba(3,1,10,.5)",
+    cluster: "#a21caf",
+    clusterLabel: "#fdf4ff",
+    focus: "#fde047",
+    countryHover: "rgba(244,114,182,.25)",
+    shade: false,
+  },
+  /** Technical line-art on deep blue, for HUD-style dashboards. */
+  blueprint: {
+    ocean: ["#0c2b52", "#04101f"],
+    land: "rgba(125,211,252,.05)",
+    border: "#7dd3fc",
+    graticule: "rgba(125,211,252,.2)",
+    atmosphere: "rgba(59,130,246,.35)",
+    rim: "rgba(125,211,252,.55)",
+    marker: "#38bdf8",
+    markerGlow: "rgba(56,189,248,.45)",
+    live: "#4ade80",
+    bubble: "#0b2545",
+    label: "#e0f2fe",
+    stars: "rgba(148,197,255,.55)",
+    dot: "#7dd3fc",
+    glow: "rgba(125,211,252,.8)",
+    orbit: "rgba(125,211,252,.5)",
+    arc: "#38bdf8",
+    arcHead: "#e0f2fe",
+    night: "rgba(2,8,20,.45)",
+    cluster: "#1d4ed8",
+    clusterLabel: "#eff6ff",
+    focus: "#facc15",
+    countryHover: "rgba(125,211,252,.2)",
+    shade: false,
+  },
+  /** Green and violet, like a polar aurora. */
+  aurora: {
+    ocean: ["#04141c", "#01060a"],
+    land: "rgba(52,211,153,.08)",
+    border: "rgba(52,211,153,.35)",
+    graticule: "rgba(167,139,250,.16)",
+    atmosphere: "rgba(52,211,153,.32)",
+    rim: "rgba(167,139,250,.75)",
+    marker: "#a78bfa",
+    markerGlow: "rgba(167,139,250,.5)",
+    live: "#34d399",
+    bubble: "#03121a",
+    label: "#d1fae5",
+    stars: "rgba(209,250,229,.7)",
+    dot: "#34d399",
+    glow: "rgba(52,211,153,.9)",
+    orbit: "rgba(167,139,250,.45)",
+    arc: "#34d399",
+    arcHead: "#c4b5fd",
+    night: "rgba(1,5,9,.45)",
+    cluster: "#047857",
+    clusterLabel: "#ecfdf5",
+    focus: "#fbbf24",
+    countryHover: "rgba(52,211,153,.22)",
+    shade: false,
+  },
+  /** High-contrast black and white. */
+  noir: {
+    ocean: ["#101010", "#000000"],
+    land: "rgba(255,255,255,.05)",
+    border: "#fafafa",
+    graticule: "rgba(255,255,255,.1)",
+    atmosphere: "rgba(255,255,255,.16)",
+    rim: "rgba(255,255,255,.7)",
+    marker: "#ffffff",
+    markerGlow: "rgba(255,255,255,.35)",
+    live: "#ffffff",
+    bubble: "#000000",
+    label: "#ffffff",
+    stars: "rgba(255,255,255,.55)",
+    dot: "#fafafa",
+    glow: "rgba(255,255,255,.9)",
+    orbit: "rgba(255,255,255,.3)",
+    arc: "#ffffff",
+    arcHead: "#ffffff",
+    night: "rgba(0,0,0,.5)",
+    cluster: "#262626",
+    clusterLabel: "#ffffff",
+    focus: "#ffffff",
+    countryHover: "rgba(255,255,255,.2)",
+    shade: false,
+  },
+  /** Printed-atlas colours, made for per-country fills. */
+  political: {
+    ocean: ["#8fd0f0", "#3f8fc7"],
+    land: "#ece3c8",
+    border: "rgba(70,60,45,.5)",
+    graticule: "rgba(255,255,255,.32)",
+    atmosphere: "rgba(143,208,240,.5)",
+    rim: "rgba(255,255,255,.6)",
+    marker: "#b91c1c",
+    markerGlow: "rgba(185,28,28,.4)",
+    live: "#15803d",
+    bubble: "#ffffff",
+    label: "#1c1917",
+    stars: "rgba(255,255,255,.7)",
+    dot: "#78716c",
+    glow: "rgba(70,60,45,.7)",
+    orbit: "rgba(255,255,255,.4)",
+    arc: "#b91c1c",
+    arcHead: "#f59e0b",
+    night: "rgba(12,20,40,.38)",
+    cluster: "#7f1d1d",
+    clusterLabel: "#ffffff",
+    focus: "#1d4ed8",
+    countryHover: "rgba(255,255,255,.45)",
+    shade: true,
+  },
+};
+
+/** Distinct fills used by `countryColors: "auto"`. */
+export const countryPalette = [
+  "#e8c39e", "#a8c8a0", "#e5b8b8", "#c5b8dd", "#f0d9a0",
+  "#9fc6d4", "#d9c2a3", "#b9d4b0", "#efc9c0", "#c9bfa8",
+  "#a9bcd8", "#e0cfe6",
+];

package/src/viewer.js

@@ -0,0 +1,130 @@
+/**
+ * Locates the person looking at the globe, with no permission prompt, no
+ * network call and no API key.
+ *
+ * The browser's IANA time zone is always available and maps to a published
+ * coordinate, which puts the viewer within their time-zone region. That is
+ * region-accurate, not street-accurate: call `locateViewerPrecise()` to offer
+ * a GPS upgrade behind the usual permission prompt.
+ */
+import { zoneTable, zoneAliases } from "./data/timezones.js";
+
+let byZone = null;
+let byCountry = null;
+let byCity = null;
+let aliasOf = null;
+
+const parseZones = () => {
+  if (byZone) return;
+  byZone = new Map();
+  byCountry = new Map();
+  byCity = new Map();
+  aliasOf = new Map();
+  for (const row of zoneTable.split(";")) {
+    const [name, lon, lat, country] = row.split("|");
+    const entry = { lon: Number(lon) / 100, lat: Number(lat) / 100, country, timeZone: name };
+    byZone.set(name, entry);
+    if (!byCountry.has(country)) byCountry.set(country, entry);
+    // The last path segment is the zone's representative city.
+    const city = name.slice(name.lastIndexOf("/") + 1).replace(/_/g, " ").toLowerCase();
+    if (!byCity.has(city)) byCity.set(city, entry);
+  }
+  for (const link of zoneAliases.split(";")) {
+    const [alias, target] = link.split(">");
+    if (alias) aliasOf.set(alias, target);
+  }
+};
+
+/** Published coordinate for an IANA zone name, resolving legacy aliases. */
+export function timeZoneLocation(name) {
+  if (!name) return null;
+  parseZones();
+  return byZone.get(name) || byZone.get(aliasOf.get(name)) || null;
+}
+
+/** Representative coordinate for an ISO 3166-1 alpha-2 country code. */
+export function countryLocation(code) {
+  if (!code) return null;
+  parseZones();
+  return byCountry.get(String(code).toUpperCase()) || null;
+}
+
+/**
+ * Coordinate for a city name, drawn from the time-zone table's representative
+ * cities. Covers roughly 300 major cities with no extra payload; pass your own
+ * gazetteer to `fromRows` when you need more.
+ */
+export function placeLocation(name) {
+  if (!name) return null;
+  parseZones();
+  return byCity.get(String(name).trim().replace(/_/g, " ").toLowerCase()) || null;
+}
+
+const currentZone = () => {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+    return null;
+  }
+};
+
+const localeCountry = () => {
+  const tags = (typeof navigator !== "undefined" && (navigator.languages || [navigator.language])) || [];
+  for (const tag of tags) {
+    if (!tag) continue;
+    const region = String(tag).split("-")[1];
+    if (region && /^[A-Za-z]{2}$/.test(region)) return region.toUpperCase();
+  }
+  return null;
+};
+
+/**
+ * Best-effort viewer location, synchronously. Returns null only when the
+ * environment exposes neither a time zone nor a locale region.
+ *
+ * `accuracyMeters` is null here because a time zone says nothing about where
+ * inside it you are: the caller is expected to derive a radius from the
+ * region itself.
+ */
+export function locateViewer() {
+  const timeZone = currentZone();
+  const zone = timeZoneLocation(timeZone);
+  if (zone) return { ...zone, timeZone, source: "timezone", accuracy: "region", accuracyMeters: null };
+  const country = countryLocation(localeCountry());
+  if (country) return { ...country, timeZone, source: "locale", accuracy: "country", accuracyMeters: null };
+  return null;
+}
+
+/**
+ * Resolves to the precise coordinate if the viewer grants permission, and to
+ * the time-zone estimate otherwise. Never rejects.
+ */
+export function locateViewerPrecise({ timeout = 10000, maximumAge = 60000, enableHighAccuracy = true } = {}) {
+  const fallback = locateViewer();
+  const geo = typeof navigator !== "undefined" && navigator.geolocation;
+  if (!geo) return Promise.resolve(fallback);
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    setTimeout(() => done(fallback), timeout + 500);
+    geo.getCurrentPosition(
+      (pos) =>
+        done({
+          lat: pos.coords.latitude,
+          lon: pos.coords.longitude,
+          timeZone: currentZone(),
+          country: fallback?.country ?? null,
+          source: "geolocation",
+          accuracy: "precise",
+          // Metres, as reported by the device. Wi-Fi/IP fixes can be tens of km.
+          accuracyMeters: pos.coords.accuracy ?? null,
+        }),
+      () => done(fallback),
+      { timeout, maximumAge, enableHighAccuracy },
+    );
+  });
+}

package/types/element.d.ts

@@ -0,0 +1,41 @@
+import type { Arc, CountryShape, GeoGlobe, GeoGlobeOptions, Marker, ClusterMarker, FlyToOptions } from "./index.js";
+
+export interface GeoGlobeEventMap {
+  "geo-hover": CustomEvent<{ marker: Marker | ClusterMarker | null; pos: { x: number; y: number } | null }>;
+  "geo-click": CustomEvent<{ marker: Marker | ClusterMarker; pos: { x: number; y: number } }>;
+  "geo-country-hover": CustomEvent<{ country: CountryShape | null; pos: { x: number; y: number } | null }>;
+  "geo-country-click": CustomEvent<{ country: CountryShape; pos: { x: number; y: number } }>;
+  "geo-render": CustomEvent<{ globe: GeoGlobe }>;
+}
+
+
+declare class GeoGlobeElementInstance extends HTMLElement {
+  /** Underlying instance; available once the element is connected. */
+  globe: GeoGlobe | null;
+  markers: Marker[];
+  arcs: Arc[];
+  set options(value: Partial<GeoGlobeOptions>);
+  flyTo(lon: number, lat: number, opts?: FlyToOptions): this;
+  fitTo(bounds: [number, number, number, number], opts?: FlyToOptions & { padding?: number }): this;
+  snapshot(type?: string, quality?: number): string | undefined;
+  addEventListener<K extends keyof GeoGlobeEventMap>(
+    type: K,
+    listener: (this: GeoGlobeElementInstance, ev: GeoGlobeEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions
+  ): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+}
+
+export type GeoGlobeElement = GeoGlobeElementInstance;
+
+/** The element class, or null when there is no DOM. */
+export declare const GeoGlobeElement: (new () => GeoGlobeElementInstance) | null;
+
+/** Registers `<geo-globe>`. Returns null when there is no DOM. */
+export declare function defineGeoGlobe(tag?: string): (new () => GeoGlobeElementInstance) | null;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "geo-globe": GeoGlobeElementInstance;
+  }
+}