canvas-globe 1.1.1 → 1.3.0

package/types/index.d.ts

@@ -32,6 +32,20 @@ export interface ClusterMarker {
   lon: number;
 }
 
+/** Synthetic marker produced by the `hexBins` density layer. */
+export interface HexBinMarker {
+  hexBin: true;
+  /** Number of source markers in the cell. */
+  markerCount: number;
+  /** Number of source markers in the cell. */
+  count: number;
+  /** Sum of source marker `count` values, with missing values treated as 1. */
+  value: number;
+  markers: Marker[];
+  lat: number;
+  lon: number;
+}
+
 export type Coordinate = { lat: number; lon: number } | [lon: number, lat: number];
 
 export interface Arc {
@@ -178,7 +192,7 @@ export interface Handle {
   stop(): void;
 }
 
-export interface StoryStep extends Partial<GeoGlobeOptions> {
+export interface StoryStep extends Omit<Partial<GeoGlobeOptions>, "center" | "zoom"> {
   /** Scroll progress, 0-1. */
   at: number;
   center?: [lon: number, lat: number];
@@ -193,6 +207,31 @@ export interface HeatmapOptions {
   color?: string;
 }
 
+export interface HexBinOptions {
+  /** Hexagon radius in screen pixels. Default 18. */
+  radius?: number;
+  /** Ignore cells below this count or summed value. Default 1. */
+  minValue?: number;
+  /** Colour cells by summed marker values or marker count. Default "sum". */
+  value?: "sum" | "count";
+  /** Single base colour used when `colorRange` is omitted. */
+  color?: string;
+  /** Low-to-high colour ramp. */
+  colorRange?: string[];
+  /** Fill opacity, 0-1. Default 0.82. */
+  opacity?: number;
+  stroke?: string;
+  /** Cell outline width in px. Default 0.8. */
+  strokeWidth?: number;
+  /** Gap inside each cell in px. Default 1.5. */
+  padding?: number;
+  /** Draw the selected count/value inside each cell. Default false. */
+  showCount?: boolean;
+  labelColor?: string;
+  /** Hide individual markers beneath the bins. Default true. */
+  hideMarkers?: boolean;
+}
+
 export interface SpikeOptions {
   /** Tallest spike as a fraction of the globe radius. Default 0.28. */
   height?: number;
@@ -378,7 +417,7 @@ export interface RenderMarkerContext {
   globe: GeoGlobe;
 }
 
-export type TooltipKind = "marker" | "cluster" | "country";
+export type TooltipKind = "marker" | "cluster" | "hex-bin" | "country";
 
 export interface GeoGlobeOptions {
   /** Commercial license key supplied after purchase. */
@@ -387,8 +426,6 @@ export interface GeoGlobeOptions {
   mode?: "globe" | "map";
   /** Flat-map projection. Default "equirectangular". */
   projection?: MapProjection;
-  /** Built-in theme name or a partial theme object. Default "atlas". */
-  theme?: ThemeName | Partial<Theme>;
   /** Named bundle of theme + render style, applied under your own options. */
   preset?: PresetName;
   /** Theme name, a partial theme, "auto" for the OS colour scheme, or "css"
@@ -428,6 +465,8 @@ export interface GeoGlobeOptions {
   transparentBackground?: boolean;
   /** Additive density blobs instead of, or under, markers. */
   heatmap?: boolean | HeatmapOptions;
+  /** Screen-space hexagonal aggregation for dense marker datasets. */
+  hexBins?: boolean | HexBinOptions;
   /** Bars standing off the surface, scaled by each marker's `count`. */
   spikes?: boolean | SpikeOptions;
   /** Text labels with collision avoidance. */
@@ -496,16 +535,42 @@ export interface GeoGlobeOptions {
   /** Frame cap. Default 30. */
   fps?: number;
   /** Built-in tooltip. `true` uses the default text, or pass a formatter. */
-  tooltip?: boolean | ((target: Marker | ClusterMarker | CountryShape, kind: TooltipKind) => string);
+  tooltip?: boolean | ((target: Marker | ClusterMarker | HexBinMarker | CountryShape, kind: TooltipKind) => string);
   /** Honour `prefers-reduced-motion`. Default true. */
   respectReducedMotion?: boolean;
   /** Accessible name for the canvas. */
   ariaLabel?: string;
-  onHover?: (marker: Marker | ClusterMarker | null, position: { x: number; y: number } | null) => void;
-  onClick?: (marker: Marker | ClusterMarker, position: { x: number; y: number }) => void;
+  onHover?: (marker: Marker | ClusterMarker | HexBinMarker | null, position: { x: number; y: number } | null) => void;
+  onClick?: (marker: Marker | ClusterMarker | HexBinMarker, position: { x: number; y: number }) => void;
   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 +658,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/jsr-element.d.ts

@@ -1,8 +1,8 @@
-import type { Arc, CountryShape, GeoGlobe, GeoGlobeOptions, Marker, ClusterMarker, FlyToOptions } from "./index.js";
+import type { Arc, CountryShape, GeoGlobe, GeoGlobeOptions, Marker, ClusterMarker, HexBinMarker, 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-hover": CustomEvent<{ marker: Marker | ClusterMarker | HexBinMarker | null; pos: { x: number; y: number } | null }>;
+  "geo-click": CustomEvent<{ marker: Marker | ClusterMarker | HexBinMarker; 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 }>;

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;