canvas-globe 1.2.0 → 1.4.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;
@@ -217,6 +256,39 @@ export interface RecordingHandle {
   stop(): Promise<Blob>;
 }
 
+export interface TileCoordinate {
+  x: number;
+  y: number;
+  z: number;
+}
+
+export type TileSource = string | CanvasImageSource;
+export type TileProvider = (tile: TileCoordinate) => TileSource | Promise<TileSource>;
+
+/** Optional XYZ overview tiles. No request is made unless this option is set. */
+export interface TileLayerOptions {
+  /** URL template using {z}, {x}, {y}, and optional {-y}. */
+  url?: string;
+  /** Alias for a URL template or provider callback. */
+  source?: string | TileProvider;
+  /** Return a URL or drawable image for one XYZ tile. */
+  getTile?: TileProvider;
+  /** Fixed overview zoom. Default 2. */
+  zoom?: number;
+  /** Source tile width/height. Default 256. */
+  tileSize?: number;
+  /** Maximum composed texture width. Default 2048. */
+  maxWidth?: number;
+  /** Request ceiling. Default 64, which allows zoom 3. */
+  maxTiles?: number;
+  opacity?: number;
+  /** Painted into the canvas and every export. */
+  attribution?: string;
+  /** Image CORS mode. Default "anonymous"; null leaves it unset. */
+  crossOrigin?: string | null;
+  onError?: (error: Error, tile: TileCoordinate | null) => void;
+}
+
 /** Anything `drawImage` accepts, plus a URL or a live stream. */
 export type MediaSource = string | CanvasImageSource | MediaStream;
 
@@ -378,7 +450,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 +459,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"
@@ -408,6 +478,8 @@ export interface GeoGlobeOptions {
   texture?: string | CanvasImageSource | null;
   /** Pixel step for the texture pass; higher is faster. Default "auto". */
   textureQuality?: "auto" | number;
+  /** Optional XYZ overview tiles. The default configuration performs no requests. */
+  tileLayer?: string | TileProvider | TileLayerOptions | TileLayer | null;
   /** Frame a single country, optionally dropping the rest of the world. */
   focus?: string | FocusSpec | null;
   /** Media painted inside each country's outline, keyed by ISO, id or name. */
@@ -428,6 +500,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,13 +570,13 @@ 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;
@@ -563,6 +637,8 @@ export declare class GeoGlobe {
   setLandStyle(style: LandStyle): this;
   /** Equirectangular image painted onto the sphere; null removes it. */
   setTexture(source: string | CanvasImageSource | null): this;
+  /** Optional XYZ overview tiles; null removes the layer. */
+  setTileLayer(source: GeoGlobeOptions["tileLayer"]): this;
   /** Frames a country and, with `isolate`, drops the rest of the world away. */
   focusOn(country: string | FocusSpec | null, opts?: Partial<FocusSpec> & FlyToOptions): this;
   clearFocus(): this;
@@ -742,6 +818,18 @@ export declare class SphereTexture {
   readonly error: Error | null;
 }
 
+/** Cached XYZ tiles composed into the raster used by globe and map modes. */
+export declare class TileLayer {
+  constructor(source: string | TileProvider | TileLayerOptions, options?: { onLoad?: (layer: TileLayer) => void });
+  readonly ready: boolean;
+  readonly error: Error | null;
+  readonly attribution: string;
+  readonly stats: { loaded: number; failed: number; total: number; cached: number };
+  destroy(): void;
+}
+
+export declare function tileUrl(template: string, tile: TileCoordinate): string;
+
 /** A drawable media source: image, GIF, video, canvas or live stream. */
 export declare class Media {
   constructor(spec: MediaSource | MediaSpec, onReady?: (media: Media) => void);

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 }>;