gistda-sphere-react

TypeScript

Every component, hook, result and Sphere object is typed

The library is written in TypeScript and exports all of its types from the package root:

import type { Location, PoiResult, PolygonRef, RouteStep } from "gistda-sphere-react";

Common types

TypeShape
Location{ lon: number; lat: number }
Point{ x: number; y: number } (pixels)
Size{ width: number; height: number }
Range{ min: number; max: number }
Bound{ minLon; minLat; maxLon; maxLat }
Icon{ url?; urlHD?; html?; offset?; size? }
GeoJSON, GeoJSONFeature, GeoJSONGeometry…GeoJSON objects (RFC 7946).

Names used by props

These are string unions, so your editor completes them:

TypeValues
BuiltInLayer"SIMPLE", "STREETS", "STREETS_NIGHT", "HYBRID", "IMAGES", "TRAFFIC", "PM25", "HOTSPOT", "FLOOD", "DROUGHT"
LayerType"Vector", "XYZ", "WMS", "WMTS", "WMTS_REST", "TMS", "Tiles3D", "I3S"
FilterType"None", "Dark", "Light", "Protanopia", "Deuteranopia"
LineStyleType"Solid", "Dashed", "Dot"
PredefinedOverlay"cameras", "events", "aqi"
UiControlName"DPad", "Zoombar", "Geolocation", "Toolbar", "LayerSelector", "Fullscreen", "Crosshair", "Scale", "ContextMenu"
UiComponentMode"Full", "Mobile", "None"
RouteMode"Traffic", "Cost", "Distance", "Fly"
RouteType"Road", "Ferry", "Tollway", "All"
RouteLabelType"Distance", "Time", "Hide"
Language"th", "en"

The library converts these to the values Sphere expects at runtime, so you never deal with Sphere's internal enum values.

Results

TypeFrom
PoiResult, SuggestResult, SearchResult, AddressResultuseSearch
RouteStep, RouteSummary, RouteResult, RouteErrorInfo, RouteStatususeRoute
UseSuggestOptions, UseSuggestReturnuseSuggest
MapViewuseMapView, onViewChange and getView()
Cluster, MarkerClusterPropsMarkerCluster
LocalizedTagCategoryuseTagCategories
SphereServices, SphereServiceError, RouteServiceResult, ElevationPoint…Web services
SphereEventMap, EventNameEvent names and their handler arguments

Props and refs

Each component exports its props and ref types, such as SphereMapProps, SphereMapRef, MarkerProps, MarkerRef, PolygonProps and PolygonRef. Wrap components with the props type:

import { Marker, type MarkerProps } from "gistda-sphere-react";

function StoreMarker({ open, ...props }: MarkerProps & { open: boolean }) {
  return <Marker {...props} icon={{ url: open ? "/open.png" : "/closed.png" }} />;
}

Sphere objects

The raw Sphere objects are typed too: SphereMapInstance (sphere.Map), SphereMarker, SpherePolygon, SpherePolyline, SphereCircle, SphereDot, SphereRectangle, SpherePopup, SphereOverlay, SphereLayer and SphereNamespace (the global sphere). MapLibreMap covers the commonly used members of map.Renderer.

Sphere's methods both read and set a value. Called without arguments they return the value with its own type, and with an argument they return the object for chaining:

import type { SphereMapInstance } from "gistda-sphere-react";

function zoomIn(map: SphereMapInstance) {
  const zoom = map.zoom(); // number
  map.zoom(zoom + 1); // returns the map, for chaining
}

window.sphere and window.deck (Sphere's copy of deck.gl, typed loosely as DeckNamespace) are declared globally once you import the package. Both are optional, since they exist only after Sphere's script has loaded. See deck.gl layers.

On this page