Creates and mounts the map inside the given container. Must be called exactly once before any other method.
Map creation options.
Returns true after init() has completed successfully.
Methods that depend on a live map instance should guard on this flag.
Destroys the map instance and releases all resources. After destroy(), no other method may be called.
Sets the map center and zoom level without animation.
New geographic center.
New zoom level.
Returns the current geographic center of the map viewport.
Returns the current zoom level.
Sets the zoom level without changing the center.
New zoom level.
Pans the map to the given center without changing the zoom level.
MapLibre uses easeTo() without zoom change.
Target geographic center.
Smoothly animates the viewport to the target center and zoom level.
Target geographic center.
Optionalzoom: numberTarget zoom level (optional — keeps current zoom when omitted).
Adjusts the viewport to fit the given bounding box.
Geographic area to fit.
Optionaloptions: { padding?: GeoLeafPoint | Record<string, number>; animate?: boolean }Optional padding in screen pixels around the bounds.
Returns the current viewport as a geographic bounding box.
Subscribes to a map event.
The handler receives an engine-specific event object (unknown).
Adapters normalise geographic coordinates to GeoLeafLatLng within
the event object where applicable.
Event type token.
Callback invoked on each occurrence.
Unsubscribes a previously registered event handler. Silently does nothing if the handler was not registered.
Event type token.
The exact function reference passed to on().
Subscribes to a map event for a single occurrence, then auto-unsubscribes.
Event type token.
Callback invoked on the first occurrence.
Creates a GeoJSON source + fill/line/circle sub-layers for the given data.
Optionaloptions: GeoLeafLayerOptionsAdds a native vector-tile source + its styled sub-layers (socle B.1). The
vector-tiles capability resolves config/style and delegates rendering here,
mirroring addGeoJSONLayer. Returns the created sub-layer ids for the caller
to bind interactions and record in shared state.
Updates the paint of an existing vector-tile layer's sub-layers.
Removes all MapLibre layers and the source for the given GeoLeaf layer.
Returns true if the layer is registered in the adapter.
Shows all sub-layers for the given GeoLeaf layer.
Hides all sub-layers for the given GeoLeaf layer.
Replaces the GeoJSON data of an existing source.
Sets feature-state on a registered source's feature, targeted by its
promoted id. Used for reactive paint (POI sync badge, hover/selection halo)
without rebuilding the source data. No-op if the source is gone. The source
must declare promoteId for a string id to resolve.
Applies a style to an existing layer by updating paint properties on each sub-layer.
Applies a filter expression to a registered layer's sub-layers.
For cluster groups, filters the unclustered-point layer specifically.
Pass null to clear the filter.
Sets the zoom range on every sub-layer of a registered layer.
Iterates getSubLayerIds rather than subLayerTypes: only the former carries the
cluster sub-layers (they are registered via customSubLayerIds), and a cluster
left out of the range would keep rendering outside it.
Creates a DOM marker at the given position and adds it to the map.
Optionaloptions: GeoLeafMarkerOptionsRemoves a marker from the map and releases its resources.
The marker identifier used in createMarker().
Updates the geographic position of an existing marker.
The marker identifier used in createMarker().
New geographic position.
Returns the native marker registered under id, or null.
maplibregl.Marker structurally satisfies GeoLeafMarkerHandle (it exposes both
getLngLat() and on()), so the handle needs no wrapper — but the narrow return
type keeps the rest of the engine surface out of callers' reach.
Creates a clustered GeoJSON source with cluster circle/symbol layers.
Optionaloptions: Record<string, unknown>Creates a popup (not opened — call openPopup() after). Content must be pre-sanitised.
Optionaloptions: GeoLeafPopupOptionsOpens (displays) a popup on the map.
The opaque handle returned by createPopup().
Optionalposition: GeoLeafLatLngGeographic position at which to anchor the popup. When omitted, the popup opens at its previously stored position.
Closes a popup without destroying it.
When popup is omitted, all open popups are closed.
Optionalpopup: unknownThe opaque handle returned by createPopup(). Optional.
Adds a control (HTMLElement or native IControl) at the given position.
Removes a control from the map.
The GeoLeafControl handle returned by addControl().
Projects a geographic coordinate to a pixel point relative to the map container's top-left corner.
Geographic coordinate to project.
Unprojects a pixel point (relative to the map container) back to a geographic coordinate.
Pixel coordinate to unproject.
Returns the map's root DOM container element. Useful for positioning custom overlays or reading container dimensions.
Escape hatch — returns the underlying maplibregl.Map instance.
Builds a transformStyle callback that preserves the GeoLeaf-owned sources
and layers across a map.setStyle() basemap swap, so they survive natively
instead of being torn down and re-injected from JS (the former
geoleaf:style:rebuild dance — audit redundancy #1).
Snapshots ownership from the layer registry (GeoJSON sub-layers + sources),
the POI cluster ids, and the sentinel z-anchor. Returns null when nothing
is owned yet (e.g. a switch before any data layer exists), letting the caller
fall back to a plain setStyle().
Called by the basemap registry immediately before setStyle().
Re-registers runtime images wiped by map.setStyle(). The transformStyle
merge (see buildStyleChangeTransform) preserves sources and layers,
but images added via map.addImage() (POI sprite icons) are not part of the
style spec and are always cleared. Skipped when no profile sprite is present,
so sprite-less profiles pay nothing and log no warning.
Called by the basemap registry inside the post-swap style.load handler.
Returns the layer registry (read-only, for popup-tooltip event binding).
MapLibre GL JS adapter — implements
IMapAdapter. One instance per map.