canvas-globe 1.1.0 → 1.2.0

package/types/controls.d.ts

@@ -0,0 +1,54 @@
+import type { GeoGlobe } from "./index";
+
+/** Unbinds a control and restores whatever it changed. */
+export type Unbind = () => void;
+
+/** What a search resolves to: a coordinate, or a country to frame. */
+export interface PlaceHit {
+  lon?: number;
+  lat?: number;
+  label?: string;
+  shape?: unknown;
+}
+
+export declare function searchAndFly(
+  globe: GeoGlobe,
+  input: HTMLInputElement,
+  options?: {
+    zoom?: number;
+    /** Your own `{ "Ahmedabad": [72.58, 23.03] }` table. */
+    gazetteer?: Record<string, [number, number] | { lon: number; lat: number }>;
+    /** Async resolver for anything the bundled data cannot reach. */
+    source?: (query: string) => PlaceHit | PlaceHit[] | null | Promise<PlaceHit | PlaceHit[] | null>;
+    minLength?: number;
+    onMatch?: (hit: PlaceHit) => void;
+    onMiss?: (query: string) => void;
+  }
+): Unbind;
+
+export declare function timelineBrush(
+  globe: GeoGlobe,
+  slider: HTMLInputElement,
+  options?: {
+    field?: string;
+    onChange?: (shown: unknown[], upTo: Date) => void;
+  }
+): Unbind;
+
+export declare function thresholdFilter(
+  globe: GeoGlobe,
+  slider: HTMLInputElement,
+  options?: {
+    field?: string;
+    onChange?: (shown: unknown[], cutoff: number) => void;
+  }
+): Unbind;
+
+export declare function crossfilter(
+  globe: GeoGlobe,
+  container: HTMLElement,
+  options?: {
+    attribute?: string;
+    active?: string;
+  }
+): Unbind;

package/types/fx-interaction.d.ts

@@ -0,0 +1,16 @@
+export {
+  magneticMarkers,
+  measureTool,
+  lassoSelect,
+  hoverLift,
+  pingProbe,
+  parallaxTilt,
+  cursorLight,
+  drillDown,
+  radialMenu,
+  spinToWin,
+  serviceRadius,
+  timezoneOverlap,
+  compareCountries,
+  geoQuiz,
+} from "./fx";

package/types/fx.d.ts

@@ -0,0 +1,313 @@
+/** Type declarations for `canvas-globe/fx`. */
+import type { CountryShape, GeoGlobe, GlobeEffect } from "./index.js";
+
+export interface Coordinate {
+  lon: number;
+  lat: number;
+}
+
+/* -------------------------------- effects -------------------------------- */
+
+export declare function particleAssemble(options?: {
+  duration?: number; hold?: number; color?: string; spacing?: number; size?: number; seed?: number;
+}): GlobeEffect;
+
+export declare function radarSweep(options?: {
+  duration?: number; hold?: number; color?: string;
+}): GlobeEffect;
+
+export declare function markerCascade(options?: {
+  duration?: number; hold?: number; color?: string;
+}): GlobeEffect;
+
+export declare function scanlines(options?: {
+  duration?: number; color?: string; gap?: number; strength?: number;
+}): GlobeEffect;
+
+export declare function breathe(options?: {
+  duration?: number; color?: string; strength?: number;
+}): GlobeEffect;
+
+export declare function lightTrails(options?: {
+  duration?: number; fade?: number; strength?: number;
+}): GlobeEffect;
+
+export declare function torch(options?: {
+  radius?: number; darkness?: number; ring?: boolean;
+}): GlobeEffect;
+
+export declare function meshGradient(options?: {
+  duration?: number; colors?: string[]; background?: string;
+}): GlobeEffect;
+
+export declare function cityLights(options?: { duration?: number; warm?: string }): GlobeEffect;
+
+export declare function starfield(options?: {
+  duration?: number; layers?: number; per?: number; seed?: number;
+}): GlobeEffect;
+
+export declare function shineSweep(options?: {
+  duration?: number; width?: number; strength?: number;
+}): GlobeEffect;
+
+export declare function glassSphere(options?: {
+  tint?: string; rim?: number; gloss?: number;
+}): GlobeEffect;
+
+export declare function neonFlicker(options?: {
+  duration?: number; color?: string; strength?: number; seed?: number;
+}): GlobeEffect;
+
+export declare function arcLaunch(options?: {
+  from?: Coordinate;
+  to?: Coordinate[];
+  duration?: number;
+  hold?: number;
+  color?: string;
+  lift?: number;
+  steps?: number;
+}): GlobeEffect;
+
+export declare function spikesRising(options?: {
+  duration?: number; hold?: number; height?: number; width?: number; color?: string;
+}): GlobeEffect;
+
+export declare function pinDrop(options?: {
+  duration?: number; hold?: number; color?: string; drop?: number; size?: number;
+}): GlobeEffect;
+
+export declare function orbitSubject(options?: {
+  at?: Coordinate; duration?: number; lon?: number; lat?: number;
+}): GlobeEffect;
+
+export declare function markerBloom(options?: {
+  duration?: number; ring?: string; dot?: string; reach?: number;
+}): GlobeEffect;
+
+/* ------------------------- transitions and camera ------------------------- */
+
+export declare function trimPaths(options?: {
+  from?: Coordinate;
+  to?: Coordinate[];
+  duration?: number;
+  hold?: number;
+  steps?: number;
+  hue?: number;
+  width?: number;
+}): GlobeEffect;
+
+export declare function liquidWipe(options?: {
+  duration?: number; hold?: number; lobes?: number; wobble?: number;
+}): GlobeEffect;
+
+export declare function matchCut(options?: {
+  duration?: number; from?: Coordinate; to?: Coordinate; cycles?: number; maxZoom?: number;
+  fromLabel?: string; toLabel?: string; color?: string;
+}): GlobeEffect;
+
+export declare function dropFromOrbit(options?: {
+  duration?: number; hold?: number; at?: Coordinate; fromZoom?: number; toZoom?: number;
+}): GlobeEffect;
+
+export declare function dayNightSweep(options?: {
+  duration?: number; start?: number;
+}): GlobeEffect;
+
+/* --------------------------------- scene --------------------------------- */
+
+export declare function mapUnfold(options?: {
+  duration?: number; hold?: number; fill?: string; stroke?: string; background?: string;
+}): GlobeEffect;
+
+export declare function firework(options?: {
+  at?: Coordinate;
+  duration?: number;
+  hold?: number;
+  sparks?: number;
+  rise?: number;
+  seed?: number;
+  colors?: string[];
+}): GlobeEffect;
+
+export declare function glitch(options?: {
+  duration?: number; slices?: number; spread?: number; seed?: number;
+}): GlobeEffect;
+
+export declare function lowerThird(options?: {
+  title?: string; subtitle?: string; duration?: number; hold?: number; accent?: string;
+}): GlobeEffect;
+
+export declare function splitFlap(options?: {
+  to?: number;
+  duration?: number;
+  hold?: number;
+  caption?: string;
+  digits?: number;
+  accent?: string;
+  seed?: number;
+}): GlobeEffect;
+
+export declare function textOnCircle(options?: {
+  text?: string; duration?: number; color?: string; size?: number; offset?: number;
+}): GlobeEffect;
+
+export declare function countryMatte(options?: {
+  country?: string; duration?: number; stops?: string[]; outline?: string;
+}): GlobeEffect;
+
+export declare function ghostTrail(options?: {
+  duration?: number; hold?: number; ghosts?: number; color?: string;
+}): GlobeEffect;
+
+/** Advances particles from the previous frame; reproduces in sequential order. */
+export declare function windField(options?: {
+  count?: number; seed?: number; speed?: number; life?: number; fade?: number;
+}): GlobeEffect;
+
+export declare function aurora(options?: {
+  duration?: number; colors?: string[]; bands?: number; lat?: number;
+}): GlobeEffect;
+
+export declare function jellySquash(options?: {
+  duration?: number; amount?: number;
+}): GlobeEffect;
+
+export declare function dataDesk(options?: {
+  title?: string; standfirst?: string; source?: string; accent?: string;
+}): GlobeEffect;
+
+export declare function counterRoll(options?: {
+  to?: number; from?: number; duration?: number; hold?: number; caption?: string;
+  format?: (value: number) => string; size?: number; color?: string;
+  position?: "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+}): GlobeEffect;
+
+export declare function shockwave(options?: {
+  at?: Coordinate; duration?: number; hold?: number; color?: string; reach?: number; rings?: number;
+}): GlobeEffect;
+
+export declare function choroplethCascade(options?: {
+  values?: Record<string, number>; duration?: number; hold?: number; hue?: number;
+}): GlobeEffect;
+
+export declare function routeDashes(options?: {
+  routes?: { from: Coordinate; to: Coordinate }[];
+  duration?: number; hold?: number; color?: string; icon?: string; steps?: number;
+}): GlobeEffect;
+
+export declare function tally(options?: {
+  caption?: string; duration?: number; hold?: number; accent?: string;
+}): GlobeEffect;
+
+export declare function magneticMarkers(options?: {
+  reach?: number; pull?: number; color?: string;
+}): GlobeEffect;
+
+export declare function measureTool(options?: { color?: string; accent?: string }): GlobeEffect;
+
+export declare function lassoSelect<M = unknown>(options?: {
+  drawMode?: boolean;
+  color?: string; accent?: string; caption?: string;
+  value?: (hits: M[]) => string;
+  onSelect?: (hits: M[]) => void;
+}): GlobeEffect;
+
+export declare function hoverLift(options?: { color?: string; scale?: number }): GlobeEffect;
+
+export declare function pingProbe(options?: {
+  from?: Coordinate; color?: string; head?: string; duration?: number;
+}): GlobeEffect;
+
+export declare function parallaxTilt(options?: {
+  count?: number; depth?: number; seed?: number; camera?: number;
+}): GlobeEffect;
+
+export declare function cursorLight(options?: {
+  warmth?: number; darkness?: number; spec?: number;
+}): GlobeEffect;
+
+export declare function drillDown(options?: {
+  padding?: number;
+  color?: string;
+  onEnter?: (shape: CountryShape, globe: GeoGlobe) => void;
+  onExit?: (globe: GeoGlobe) => void;
+}): GlobeEffect;
+
+export declare function radialMenu(options?: {
+  items?: string[];
+  radius?: number;
+  color?: string;
+  onPick?: (item: string, at: [number, number] | null, globe: GeoGlobe) => void;
+}): GlobeEffect;
+
+export declare function spinToWin<M = unknown>(options?: {
+  color?: string;
+  caption?: string;
+  duration?: number;
+  turns?: number;
+  onLand?: (marker: M, globe: GeoGlobe) => void;
+}): GlobeEffect;
+
+export declare function serviceRadius(options?: {
+  km?: number; color?: string; caption?: string; at?: Coordinate;
+}): GlobeEffect;
+
+export declare function timezoneOverlap(options?: {
+  color?: string; warn?: string; dayStart?: number; dayEnd?: number;
+}): GlobeEffect;
+
+export declare function compareCountries(options?: {
+  color?: string;
+  accent?: string;
+  metric?: string;
+  values?: Record<string, number>;
+}): GlobeEffect;
+
+export declare function geoQuiz(options?: {
+  pool?: string[];
+  color?: string;
+  wrong?: string;
+  rounds?: number;
+  onAnswer?: (correct: boolean, shape: CountryShape, globe: GeoGlobe) => void;
+}): GlobeEffect;
+
+/* -------------------------------- runtime -------------------------------- */
+
+export declare const TAU: number;
+export declare function linear(t: number): number;
+export declare function easeIn(t: number): number;
+export declare function easeOut(t: number): number;
+export declare function easeInOut(t: number): number;
+export declare function backOut(t: number): number;
+export declare function pingPong(t: number): number;
+export declare function clamp01(t: number): number;
+export declare function lerp(a: number, b: number, t: number): number;
+export declare function stagger(t: number, index: number, count: number, overlap?: number): number;
+
+/** Deterministic RNG  -  effects must not call Math.random() per frame. */
+export declare function rng(seed?: number): () => number;
+export declare function particles<T>(count: number, seed: number, make: (random: () => number, i: number) => T): T[];
+
+export declare function scratch(globe: GeoGlobe, key?: string): { canvas: HTMLCanvasElement; ctx: CanvasRenderingContext2D } | null;
+export declare function releaseScratch(globe: GeoGlobe, key?: string): void;
+
+export declare function destination(lon: number, lat: number, bearing: number, degrees: number): [number, number];
+export declare function ring(lon: number, lat: number, degrees: number, steps?: number): [number, number][];
+export declare function drawPath(ctx: CanvasRenderingContext2D, globe: GeoGlobe, points: [number, number][], close?: boolean): void;
+export declare function centroid(shape: CountryShape | { coordinates: unknown }): [number, number];
+
+export declare function panel(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, options?: { fill?: string; stroke?: string; radius?: number }): void;
+export declare function label(ctx: CanvasRenderingContext2D, text: string, x: number, y: number, options?: { size?: number; weight?: number; color?: string; align?: CanvasTextAlign; font?: string }): void;
+export declare function readout(ctx: CanvasRenderingContext2D, x: number, y: number, caption: string, value: string, options?: { accent?: string; width?: number }): void;
+export declare function bar(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, fraction: number, options?: { fill?: string; track?: string; radius?: number }): void;
+
+/* -------------------------------- pointer -------------------------------- */
+
+export declare function onTap(globe: GeoGlobe, handler: (point: { x: number; y: number }, at: [number, number] | null, event: PointerEvent) => void, slop?: number): () => void;
+export declare function onDragPath(globe: GeoGlobe, handlers: {
+  start?: (path: { x: number; y: number }[]) => void;
+  move?: (path: { x: number; y: number }[]) => void;
+  end?: (path: { x: number; y: number }[]) => void;
+}, enabled?: () => boolean): () => void;
+export declare function nearest<T extends Coordinate>(globe: GeoGlobe, items: T[], x: number, y: number, radius?: number): T | null;
+export declare function pointInPath(x: number, y: number, path: { x: number; y: number }[]): boolean;

package/types/index.d.ts

@@ -506,6 +506,32 @@ export interface GeoGlobeOptions {
   onCountryHover?: (country: CountryShape | null, position: { x: number; y: number } | null) => void;
   onCountryClick?: (country: CountryShape, position: { x: number; y: number }) => void;
   onRender?: (instance: GeoGlobe) => void;
+  /** Effects installed when the globe is created. */
+  effects?: GlobeEffect[];
+}
+
+/** Where an effect paints relative to the globe itself. */
+export type EffectStage = "beneath" | "above" | "post";
+
+/**
+ * An effect derives its whole appearance from `t` (0→1), which is why
+ * `renderFrame()` can reproduce any frame exactly.
+ */
+export interface GlobeEffect<S = any> {
+  name?: string;
+  /** Default "above". */
+  stage?: EffectStage;
+  /** Paint order within a stage. Lower paints first. Default 0. */
+  z?: number;
+  /** Milliseconds for one cycle. Default 1000. */
+  duration?: number;
+  /** Milliseconds held at the end before looping. Default 0. */
+  hold?: number;
+  /** Default true. */
+  loop?: boolean;
+  setup?(globe: GeoGlobe): S;
+  frame(ctx: CanvasRenderingContext2D, globe: GeoGlobe, t: number, state: S): void;
+  dispose?(state: S, globe: GeoGlobe): void;
 }
 
 export interface FlyToOptions {
@@ -593,6 +619,28 @@ export declare class GeoGlobe {
   countryAt(x: number, y: number): CountryShape | null;
   /** Marks the next frame as needing a redraw. */
   invalidate(): this;
+
+  /** Pointer position in canvas pixels and the coordinate beneath it. */
+  readonly pointer: { x: number; y: number; lon: number; lat: number; over: boolean };
+  /** Effects currently installed, in paint order. */
+  readonly effects: GlobeEffect[];
+  use(effect: GlobeEffect): this;
+  remove(effect: GlobeEffect | string): this;
+  clearEffects(): this;
+  /** Pins the effect clock so a frame can be reproduced. */
+  seek(ms: number): this;
+  /** Releases the clock back to wall time. */
+  play(): this;
+  /** Draws the frame belonging at `ms` on the effect clock. */
+  renderFrame(ms: number): this;
+  /** Traces a country outline into a path using the current projection. */
+  tracePath(
+    shape: CountryShape | { coordinates: unknown },
+    ctx?: CanvasRenderingContext2D,
+    transform?: (coord: [number, number]) => [number, number],
+  ): this;
+  /** Land sample points as `[lon, lat]` pairs. */
+  landPoints(spacing?: number): [number, number][];
   resize(): this;
   render(): this;
   snapshot(type?: string, quality?: number): string;

package/types/places.d.ts

@@ -0,0 +1,43 @@
+/** A place from the bundled Natural Earth table. */
+export interface Place {
+  name: string;
+  /** Accent-folded, lowercase name used for matching. */
+  key: string;
+  lon: number;
+  lat: number;
+  /** ISO 3166-1 alpha-2 country code. */
+  country: string;
+  /** Admin-1 name, present only where it disambiguates a repeated name. */
+  region: string;
+  population: number;
+  /** `"Springfield, Illinois, US"`  -  ready to show in a results list. */
+  label: string;
+}
+
+/** Lowercases and strips accents, so "São Paulo" answers to "sao paulo". */
+export declare function fold(value: string): string;
+
+/** Places matching `query`, prefix matches first, then by population. */
+export declare function searchPlaces(
+  query: string,
+  options?: {
+    limit?: number;
+    country?: string;
+    /** Also match names that contain the query, not just start with it. */
+    contains?: boolean;
+  }
+): Place[];
+
+/** Coordinate for an exact-ish name, matching the shape of `geocode()`. */
+export declare function placePoint(
+  name: string,
+  options?: { country?: string }
+): { lon: number; lat: number } | null;
+
+/** Ready-made resolver for `searchAndFly({ source })`. */
+export declare function placeSource(
+  options?: { limit?: number; country?: string; contains?: boolean }
+): (query: string) => Place[];
+
+/** How many places the bundled table holds. */
+export declare function placeCount(): number;

package/types/recipes.d.ts

@@ -0,0 +1,54 @@
+import type { GeoGlobe, GlobeOptions, Coordinate } from "./index";
+import type { GlobeEffect } from "./fx";
+
+/**
+ * A complete look: options, effects, and optionally a call into the
+ * imperative API. Plain data, so it can be read and pulled apart.
+ */
+export interface GlobeRecipe {
+  name: string;
+  options?: Partial<GlobeOptions>;
+  effects?: GlobeEffect[];
+  /** Runs after the options and effects are applied. Returns a teardown. */
+  start?: (globe: GeoGlobe) => (() => void) | void;
+}
+
+/** Applies a recipe and returns a function that undoes it. */
+export declare function applyRecipe(globe: GeoGlobe, recipe: GlobeRecipe): () => void;
+
+export declare function devPlatformGlobe(options?: {
+  hub?: Coordinate;
+  spokes?: number;
+}): GlobeRecipe;
+
+export declare function keynoteGlobe(options?: {
+  hub?: Coordinate;
+  countries?: number;
+  caption?: string;
+}): GlobeRecipe;
+
+export declare function satelliteOrbits(options?: {
+  count?: number;
+  preset?: string;
+  rotateSpeed?: number;
+}): GlobeRecipe;
+
+export declare function growthOverTime(options?: {
+  duration?: number;
+  loop?: boolean;
+  preset?: string;
+}): GlobeRecipe;
+
+export declare function celebrationBurst(options?: {
+  at?: Coordinate;
+  label?: string;
+  emoji?: string;
+  every?: number;
+  burst?: number;
+}): GlobeRecipe;
+
+export declare function cityTour(options?: {
+  stops?: Coordinate[];
+  dwell?: number;
+  zoom?: number;
+}): GlobeRecipe;