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
| Type | Shape |
|---|---|
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:
| Type | Values |
|---|---|
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
| Type | From |
|---|---|
PoiResult, SuggestResult, SearchResult, AddressResult | useSearch |
RouteStep, RouteSummary, RouteResult, RouteErrorInfo, RouteStatus | useRoute |
UseSuggestOptions, UseSuggestReturn | useSuggest |
MapView | useMapView, onViewChange and getView() |
Cluster, MarkerClusterProps | MarkerCluster |
LocalizedTagCategory | useTagCategories |
SphereServices, SphereServiceError, RouteServiceResult, ElevationPoint… | Web services |
SphereEventMap, EventName | Event 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.