GeoLeaf Core API - v3.0.0
    Preparing search index...

    Interface IMapAdapter

    Engine-agnostic map adapter interface.

    MaplibreAdapter implements this interface. All GeoLeaf modules interact with the map exclusively through this interface — no maplibregl.* references outside of the adapter implementation.

    Id-based management: Layers, markers, and cluster groups are managed by string identifiers. The adapter stores native engine objects internally — callers never interact with MapLibre overlays directly.

    Opaque handles: createPopup() returns unknown because the underlying type differs between engines. Callers must treat popup handles as opaque and pass them back to openPopup() / closePopup().

    // In a module's init():
    adapter.init({ container: 'map', center: { lat: 45.76, lng: 4.83 }, zoom: 13 });
    adapter.on('zoomend', () => console.log('zoom:', adapter.getZoom()));
    interface IMapAdapter {
        init(options: MapInitOptions): void;
        isReady(): boolean;
        destroy(): void;
        setView(center: GeoLeafLatLng, zoom: number): void;
        getCenter(): GeoLeafLatLng;
        getZoom(): number;
        setZoom(zoom: number): void;
        panTo(center: GeoLeafLatLng): void;
        flyTo(center: GeoLeafLatLng, zoom?: number): void;
        fitBounds(
            bounds: GeoLeafBounds,
            options?: { padding?: GeoLeafPoint; animate?: boolean },
        ): void;
        getBounds(): GeoLeafBounds;
        on(event: MapEvent, handler: (e: unknown) => void): void;
        off(event: MapEvent, handler: (e: unknown) => void): void;
        once(event: MapEvent, handler: (e: unknown) => void): void;
        addGeoJSONLayer(
            id: string,
            data: unknown,
            options?: GeoLeafLayerOptions,
        ): void;
        removeLayer(id: string): void;
        hasLayer(id: string): boolean;
        showLayer(id: string): void;
        hideLayer(id: string): void;
        updateLayerData(id: string, data: unknown): void;
        setFeatureState?(
            id: string,
            featureId: string | number,
            state: Record<string, unknown>,
        ): void;
        setLayerStyle(id: string, style: GeoLeafStyleOptions): void;
        setLayerFilter(id: string, filter: unknown): void;
        setLayerZoomRange(
            id: string,
            minZoom: number | null,
            maxZoom: number | null,
        ): void;
        createMarker(
            id: string,
            position: GeoLeafLatLng,
            options?: GeoLeafMarkerOptions,
        ): void;
        removeMarker(id: string): void;
        updateMarkerPosition(id: string, position: GeoLeafLatLng): void;
        getMarkerHandle?(id: string): GeoLeafMarkerHandle | null;
        createClusterGroup(
            id: string,
            options?: Record<string, unknown>,
        ): Promise<void>;
        createPopup(
            content: string | HTMLElement,
            options?: GeoLeafPopupOptions,
        ): unknown;
        openPopup(popup: unknown, position?: GeoLeafLatLng): void;
        closePopup(popup?: unknown): void;
        addControl(
            control: unknown,
            position: GeoLeafControlPosition,
        ): GeoLeafControl;
        removeControl(control: GeoLeafControl): void;
        latLngToPoint(latlng: GeoLeafLatLng): GeoLeafPoint;
        pointToLatLng(point: GeoLeafPoint): GeoLeafLatLng;
        getContainer(): HTMLElement;
        getNativeMap?(): unknown;
        buildStyleChangeTransform?(): unknown;
        reregisterStyleImages?(): void;
        addVectorTileLayer?(layerId: string, spec: VectorTileLayerSpec): string[];
        updateVectorTileLayerStyle?(
            layerId: string,
            subLayerIds: string[],
            style: VectorTileStyleInput,
        ): void;
    }

    Implemented by

    Index

    Methods

    init isReady destroy setView getCenter getZoom setZoom panTo flyTo fitBounds getBounds on off once addGeoJSONLayer removeLayer hasLayer showLayer hideLayer updateLayerData setFeatureState? setLayerStyle setLayerFilter setLayerZoomRange createMarker removeMarker updateMarkerPosition getMarkerHandle? createClusterGroup createPopup openPopup closePopup addControl removeControl latLngToPoint pointToLatLng getContainer getNativeMap? buildStyleChangeTransform? reregisterStyleImages? addVectorTileLayer? updateVectorTileLayerStyle?

    Methods

    • Returns true after init() has completed successfully. Methods that depend on a live map instance should guard on this flag.

      Returns boolean

    • 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.

      Parameters

      • event: MapEvent

        Event type token.

      • handler: (e: unknown) => void

        Callback invoked on each occurrence.

      Returns void

    • Unsubscribes a previously registered event handler. Silently does nothing if the handler was not registered.

      Parameters

      • event: MapEvent

        Event type token.

      • handler: (e: unknown) => void

        The exact function reference passed to on().

      Returns void

    • Subscribes to a map event for a single occurrence, then auto-unsubscribes.

      Parameters

      • event: MapEvent

        Event type token.

      • handler: (e: unknown) => void

        Callback invoked on the first occurrence.

      Returns void

    • Creates a GeoJSON layer from raw GeoJSON data and adds it to the map.

      The adapter stores the layer internally keyed by id. Use removeLayer(), setLayerVisibility(), updateLayerData(), and setLayerStyle() to manage it afterwards.

      Parameters

      • id: string

        Unique layer identifier.

      • data: unknown

        GeoJSON data (FeatureCollection, Feature, or Geometry). Validated by the adapter at runtime.

      • Optionaloptions: GeoLeafLayerOptions

        Optional layer display options.

      Returns void

    • Removes the layer identified by id from the map and disposes it.

      Parameters

      • id: string

        The layer identifier used in addGeoJSONLayer().

      Returns void

    • Returns true if a layer with the given id is currently managed by the adapter.

      Parameters

      • id: string

        Layer identifier to check.

      Returns boolean

    • Replaces the GeoJSON data of an existing layer.

      Internally clears the current features and adds the new data. The layer keeps its id, options, and style.

      Parameters

      • id: string

        Layer identifier.

      • data: unknown

        New GeoJSON data (FeatureCollection, Feature, or Geometry).

      Returns void

    • Sets feature-state on a layer's source feature, targeted by its promoted id — reactive paint (e.g. POI sync badge, hover/selection halo) without a source data rebuild. Maps to map.setFeatureState(). The source must declare promoteId for a string id to resolve.

      Parameters

      • id: string

        Layer identifier (resolves to the backing source).

      • featureId: string | number

        Promoted feature id to target.

      • state: Record<string, unknown>

        Feature-state key/values to set.

      Returns void

    • Applies a filter expression to an existing layer.

      Maps to map.setFilter() with a MapLibre expression array (e.g. ["==", ["get", "type"], "park"]).

      Parameters

      • id: string

        Layer identifier.

      • filter: unknown

        Engine-specific filter expression (unknown). Pass null to clear the filter.

      Returns void

    • Updates the zoom range of an existing layer, on every one of its sub-layers.

      Maps to map.setLayerZoomRange(). Needed because a scale bound converts to a zoom level THROUGH THE LATITUDE: the same 1:X sits at different zooms in Cayenne and in Tromsø. A range posted at load time therefore drifts as the user pans north or south, and has to be re-pushed — but never on zoom, which does not affect the conversion.

      Parameters

      • id: string

        Layer identifier.

      • minZoom: number | null

        Lowest zoom at which the layer renders, or null to clear.

      • maxZoom: number | null

        Highest zoom at which the layer renders, or null to clear.

      Returns void

    • Creates a marker at the given position and adds it to the map.

      The adapter stores the marker internally keyed by id.

      Parameters

      Returns void

      The options.icon field, if provided, must be a static hardcoded SVG string. Never pass user-provided or network-fetched content as icon — SVG can carry executable payloads (XSS).

    • Removes a marker from the map and releases its resources.

      Parameters

      • id: string

        The marker identifier used in createMarker().

      Returns void

    • Returns a handle on an existing marker, or null when no marker carries that id.

      The id-based surface above covers the common cases; this exists for the two things it cannot express — reading a marker's position after the user dragged it, and subscribing to its own events. Prefer updateMarkerPosition() and the map-level on() whenever they suffice.

      Optional: an adapter whose engine has no per-marker event model may omit it, and callers must handle undefined as they do for the other optional members.

      Parameters

      • id: string

        The marker identifier used in createMarker().

      Returns GeoLeafMarkerHandle | null

    • Creates a cluster group for grouping markers at low zoom levels.

      The adapter stores the cluster group internally keyed by id.

      Parameters

      • id: string

        Unique cluster group identifier.

      • Optionaloptions: Record<string, unknown>

        Clustering options (engine-specific, typed unknown). Each adapter validates the concrete options internally.

      Returns Promise<void>

    • Creates a popup with the given content.

      Returns an opaque handle (unknown) to pass to openPopup() / closePopup(). The popup is not opened automatically — call openPopup() after creation.

      Parameters

      • content: string | HTMLElement

        HTML string or DOM element to display inside the popup.

      • Optionaloptions: GeoLeafPopupOptions

      Returns unknown

      When content is a string, it must be sanitised by the caller before being passed here. The adapter does not sanitise content. Use GeoLeaf.Security.sanitize() or an equivalent helper.

    • Opens (displays) a popup on the map.

      Parameters

      • popup: unknown

        The opaque handle returned by createPopup().

      • Optionalposition: GeoLeafLatLng

        Geographic position at which to anchor the popup. When omitted, the popup opens at its previously stored position.

      Returns void

    • Closes a popup without destroying it. When popup is omitted, all open popups are closed.

      Parameters

      • Optionalpopup: unknown

        The opaque handle returned by createPopup(). Optional.

      Returns void

    • Returns the map's root DOM container element. Useful for positioning custom overlays or reading container dimensions.

      Returns HTMLElement

    • Returns the underlying native map instance (MapLibre GL Map object).

      Intended for low-level integrations that cannot be expressed through the standard adapter interface. Use sparingly — direct access bypasses the adapter contract and may break on engine upgrades.

      Returns unknown to avoid importing engine-specific types in this file.

      Returns unknown

    • Builds a transformStyle callback (setStyle option, depuis MapLibre v5) that preserves the adapter-owned sources and layers across a basemap style swap, so they survive natively rather than being torn down and re-injected. Returns null when nothing is owned yet.

      Called by the basemap registry immediately before setStyle(). The return type is intentionally opaque here to keep the contract engine-agnostic.

      Returns unknown

    • Re-registers runtime images (e.g. POI sprite icons) wiped by map.setStyle(). Sources and layers are preserved by the style transform; images are not part of the style spec and must be re-added after the swap.

      Called by the basemap registry inside the post-swap style.load handler.

      Returns void

    • Adds a native vector-tile source and its styled sub-layers (fill / line / circle / fill-extrusion / casing), registering them in the adapter's layer registry. Returns the created sub-layer ids (for interaction binding and layer bookkeeping). Engine-specific (vector tiles are a MapLibre-native concept) — a non-MapLibre adapter may omit it. Socle B.1: the vector-tiles capability resolves config/style and delegates all rendering here.

      Parameters

      Returns string[]

    Settings

    Member Visibility

    On This Page

    Methods