GeoLeaf-JS — API Reference

Package: @geoleaf/coreVersion: 2.0.0 License: MIT

Auto-generated HTML docs: Run npm run docs:api in packages/core to generate the TypeDoc API reference at packages/core/docs/api/. This produces per-module HTML pages for all 31 named exports including full method signatures, parameter types, and return types.

ESM named exports (31)
GeoLeafAPI — top-level API
Core — map lifecycle
POI — points of interest
UI — interface controls
Filters — filter system
Route — routing
Table — data table
Legend — legend panel
LayerManager — GeoJSON layers
Baselayers — base tiles
Helpers
Validators
Themes — theme system
API sub-modules
Log
Errors — typed error classes
CONSTANTS
Utils
Config
Search — search engine
Geocoding — address search
Permalink — URL deep linking
Notifications — toast notifications
PWA — install prompt
Lazy loading system
Global namespace (window.GeoLeaf.*)

ESM named exports (31)

All symbols available via import { … } from "@geoleaf/core":

// Facade modules
import { Core } from "@geoleaf/core"; // Map lifecycle
import { GeoLeafAPI } from "@geoleaf/core"; // Unified top-level API
import { UI } from "@geoleaf/core"; // UI controls
import { POI } from "@geoleaf/core"; // Points of interest
import { Route } from "@geoleaf/core"; // Routing
import { Table } from "@geoleaf/core"; // Data table
import { Legend } from "@geoleaf/core"; // Legend panel
import { LayerManager } from "@geoleaf/core"; // GeoJSON layer management
import { Filters } from "@geoleaf/core"; // Filter panels
import { Baselayers } from "@geoleaf/core"; // Base tile layers
import { Helpers } from "@geoleaf/core"; // Utility helpers
import { Validators } from "@geoleaf/core"; // Input validators
import { Themes } from "@geoleaf/core"; // Theme system
import { Search } from "@geoleaf/core"; // Full-text POI search
import { Permalink } from "@geoleaf/core"; // URL deep linking
import { Events } from "@geoleaf/core"; // DOM event bus
import { Notifications } from "@geoleaf/core"; // Toast notifications
import { PWA } from "@geoleaf/core"; // PWA install prompt
import { Geocoding } from "@geoleaf/core"; // Geocoding / address search

// API sub-modules
import { APIController } from "@geoleaf/core";
import { APIFactoryManager } from "@geoleaf/core";
import { APIInitializationManager } from "@geoleaf/core";
import { APIModuleManager } from "@geoleaf/core";
import { PluginRegistry } from "@geoleaf/core";
import { BootInfo } from "@geoleaf/core";
import { showBootInfo } from "@geoleaf/core";

// Utilities
import { Log } from "@geoleaf/core"; // Logging
import { Errors } from "@geoleaf/core"; // Typed error classes
import { CONSTANTS } from "@geoleaf/core"; // Constants
import { Utils } from "@geoleaf/core"; // Utility modules
import { Config } from "@geoleaf/core"; // Config access

export default GeoLeaf; // default export: window.GeoLeaf (CDN/global passthrough)

GeoJSON is not a named export. GeoJSON layers are managed internally via LayerManager and JSON profiles. There is no GeoLeaf.GeoJSON public API.

GeoLeafAPI — top-level API

The top-level GeoLeaf API. Available as GeoLeaf (CDN/global) or GeoLeafAPI (ESM).

Methods

Method	Signature	Description
`init`	`(options: object) => Promise<void>`	Initialize GeoLeaf with a map container and options
`loadConfig`	`(input: string \| object) => Promise<void>`	Load config from URL or inline object
`setTheme`	`(theme: string) => void`	Apply a visual theme
`createMap`	`(id: string, options?: object) => object \| null`	Create a new managed map instance
`getMap`	`(id: string) => object \| null`	Get a map instance by container id
`getAllMaps`	`() => object[]`	Get all active map instances
`removeMap`	`(id: string) => boolean`	Destroy a managed map instance
`getModule`	`(name: string) => object \| null`	Get a registered module by name
`hasModule`	`(name: string) => boolean`	Check if a module is registered
`getNamespace`	`(name: string) => object \| null`	Get a top-level GeoLeaf namespace by name
`getHealth`	`() => object \| null`	Get APIController health/metrics
`getMetrics`	`() => object \| null`	Alias for `getHealth()`

Properties

Property	Type	Description
`version`	`string`	Current GeoLeaf version (e.g. `"2.0.0"`)
`CONSTANTS`	`object`	Reference to `GeoLeaf.CONSTANTS`
`BaseLayers`	`object`	Alias for `GeoLeaf.Baselayers` (backward compatibility)

Core — map lifecycle

Generated signatures: packages/core/docs/api/variables/Core.html (run npm run docs:api in packages/core)

import { Core } from "@geoleaf/core";
// or: GeoLeaf.Core (CDN/global)

Method	Signature	Description
`init`	`(options?: object) => IMapAdapter \| null`	Initialise the MapLibre map
`getMap`	`() => IMapAdapter \| null`	Return the current map adapter instance
`setTheme`	`(theme: string) => void`	Apply a theme to the map container
`getTheme`	`() => string`	Get the current theme name

Init options:

Core.init({
    mapId: "map", // DOM element id or HTMLElement
    center: [lat, lng], // Initial center [lat, lng]
    zoom: 12, // Initial zoom level
    theme: "light", // Theme name (default: "light")
    mapOptions: {}, // Additional MapLibre GL JS MapOptions (optional)
});

POI — points of interest

import { POI } from "@geoleaf/core";
// or: GeoLeaf.POI (CDN/global) — requires _loadModule("poi") in lazy mode

POI provides marker management, clustering, popup, and sidepanel functionality. The POI module is lazy-loaded and must be activated before use:

await GeoLeaf._loadModule("poi");
GeoLeaf.POI.init(config);

Method	Signature	Description
`init`	`(config: object) => void`	Initialise le module POI avec la configuration
`showPoiDetails`	`(poi: object, customLayout?: object) => Promise<void>`	Ouvre le panneau latéral sur un POI (avec layout custom optionnel)
`openSidePanel`	`(poi: object, customLayout?: object) => void`	Alias direct vers le panneau latéral POI

Sub-resources available after loading:

GeoLeaf.POI.Renderers.FieldRenderers — field rendering helpers
GeoLeaf.POI.Renderers.MediaRenderers — media (image/video) rendering helpers

UI — interface controls

import { UI } from "@geoleaf/core";
// or: GeoLeaf.UI (CDN/global)

UI manages controls, panels, content builder, and notification system.

Filters — filter system

import { Filters } from "@geoleaf/core";
// or: GeoLeaf.Filters (CDN/global)

Filters provides text filters, category filters, and geographic proximity filters.

Route — routing

import { Route } from "@geoleaf/core";
// or: GeoLeaf.Route (CDN/global) — requires _loadModule("route")

Route is lazy-loaded. Load before using:

await GeoLeaf._loadModule("route");
GeoLeaf.Route.init(config);

Method	Signature	Description
`init`	`(options?: object) => void`	Initialise le module avec la configuration routes
`loadGPX`	`(url: string) => Promise<void>`	Charge et affiche un tracé GPX depuis une URL
`loadGeoJSON`	`(geojson: object) => void`	Charge un objet GeoJSON directement
`loadFromConfig`	`(routes: RouteConfig[]) => Promise<void>`	Charge plusieurs routes depuis une configuration
`show`	`() => void`	Affiche la couche route
`hide`	`() => void`	Masque la couche route
`toggleVisibility`	`() => void`	Bascule la visibilité de la couche route
`clear`	`() => void`	Supprime tous les tracés chargés
`addWaypoint`	`(latlng: [number, number]) => void`	Ajoute un point de passage
`addSegment`	`(coords: [number, number][]) => void`	Ajoute un segment de tracé
`filterVisibility`	`(routes: string[]) => void`	Filtre la visibilité par IDs de routes
`isInitialized`	`() => boolean`	Retourne true si le module est initialisé
`isVisible`	`() => boolean`	Retourne true si la couche est visible

Table — data table

import { Table } from "@geoleaf/core";
// or: GeoLeaf.Table (CDN/global) — requires _loadModule("table")

Table is lazy-loaded:

await GeoLeaf._loadModule("table");
GeoLeaf.Table.init(config);

Not included in the Lite bundle (bundle-core-lite-entry.ts).

Method	Signature	Description
`init`	`(options: { map: any, config?: object }) => void`	Initialise le module table avec une instance de carte
`show`	`() => void`	Affiche le panneau table
`hide`	`() => void`	Masque le panneau table
`toggle`	`() => void`	Bascule la visibilité du panneau
`setLayer`	`(layerId: string \| null) => void`	Sélectionne une couche GeoJSON à afficher
`refresh`	`() => void`	Recharge les données de la couche courante
`sortByField`	`(field: string) => void`	Trie le tableau par un champ donné
`setSelection`	`(ids: any[], add?: boolean) => void`	Sélectionne des entités par ID (fusion si `add=true`)
`getSelectedIds`	`() => string[]`	Retourne les IDs des entités sélectionnées
`clearSelection`	`() => void`	Désélectionne toutes les entités
`zoomToSelection`	`() => void`	Zoome sur l'emprise des entités sélectionnées
`highlightSelection`	`(active: boolean) => void`	Active/désactive la surbrillance sur la carte
`exportSelection`	`() => void`	Télécharge les entités sélectionnées en CSV

Configuration (tableConfig dans ui.json) :

json

{
    "tableConfig": {
        "enabled": true,
        "defaultVisible": false,
        "pageSize": 50,
        "maxRowsPerLayer": 1000,
        "enableExportButton": true,
        "virtualScrolling": true,
        "defaultHeight": "40%",
        "minHeight": "20%",
        "maxHeight": "60%",
        "resizable": true
    }
}

Legend — legend panel

import { Legend } from "@geoleaf/core";
// or: GeoLeaf.Legend (CDN/global) — requires _loadModule("legend")

Legend is lazy-loaded.

Note: GeoLeaf.Legend and GeoLeaf.LayerManager are independent modules with separate implementations. Legend manages visual legend panels generated from layer style data. LayerManager manages GeoJSON layer loading and visibility controls.

Method	Signature	Description
`init`	`(mapInstance: any, options?: object) => boolean`	Initialise le module avec une instance de carte
`loadLayerLegend`	`(layerId: string, styleId: string, layerConfig: object) => void`	Charge et affiche la légende d'une couche
`setLayerVisibility`	`(layerId: string, visible: boolean) => void`	Masque / affiche une couche depuis la légende
`getAllLayers`	`() => Map<string, object>`	Retourne l'ensemble des couches connues de la légende
`hideLegend`	`() => void`	Masque le panneau légende
`removeLegend`	`() => void`	Supprime le panneau légende du DOM
`isLegendVisible`	`() => boolean`	Retourne la visibilité courante du panneau
`toggleAccordion`	`(layerId: string) => void`	Ouvre / ferme l'accordéon d'une couche dans la légende

LayerManager — GeoJSON layers

import { LayerManager } from "@geoleaf/core";
// or: GeoLeaf.LayerManager (CDN/global) — requires _loadModule("layerManager")

LayerManager manages GeoJSON layers loaded from profiles. It is the primary way to work with GeoJSON data in GeoLeaf.

Note: GeoLeaf.GeoJSON does not exist as a public API. Data access is exclusively through LayerManager and JSON profiles.

Baselayers — base tiles

import { Baselayers } from "@geoleaf/core";
// or: GeoLeaf.Baselayers (CDN/global)

Baselayers manages raster tile layers and vector tile layers (via MapLibre GL).

Helpers

import { Helpers } from "@geoleaf/core";
// or: GeoLeaf.Helpers (CDN/global)

Validators

import { Validators } from "@geoleaf/core";
// or: GeoLeaf.Validators (CDN/global)

Themes — theme system

import { Themes } from "@geoleaf/core"; // direct named export — lazy-loaded at runtime
// or: GeoLeaf.Themes (CDN/global) — requires _loadModule("themes")

API sub-modules

import {
    APIController,
    APIFactoryManager,
    APIInitializationManager,
    APIModuleManager,
    PluginRegistry,
    BootInfo,
    showBootInfo,
} from "@geoleaf/core";

PluginRegistry

GeoLeaf.PluginRegistry.isLoaded("storage"); // → boolean
GeoLeaf.PluginRegistry.getLoadedPlugins(); // → string[]
GeoLeaf.PluginRegistry.canActivate("addpoi"); // → boolean
GeoLeaf.PluginRegistry.register("name", metadata); // called by plugins
GeoLeaf.PluginRegistry.registerLazy("name", fn); // called by bundle-entry

showBootInfo / BootInfo

import { showBootInfo } from "@geoleaf/core";
showBootInfo(); // prints boot diagnostics to console

Log

import { Log } from "@geoleaf/core";
// or: GeoLeaf.Log (CDN/global)

Log.info("message");
Log.warn("message");
Log.error("message", error);

Errors — typed error classes

import { Errors } from "@geoleaf/core";
// or: GeoLeaf.Errors (CDN/global)

9 typed error classes (see errors/GeoLeaf_Errors_README.md).

CONSTANTS

import { CONSTANTS } from "@geoleaf/core";
// or: GeoLeaf.CONSTANTS (CDN/global)

CONSTANTS.VERSION; // Current version string
CONSTANTS.DEFAULT_CENTER; // Default map center
CONSTANTS.DEFAULT_ZOOM; // Default zoom level
// … see constants/GeoLeaf_Constants_README.md for full list

Utils

import { Utils } from "@geoleaf/core";
// or: GeoLeaf.Utils (CDN/global)

13 utility sub-modules registered on GeoLeaf.Utils:

Sub-module	Description
`AnimationHelper`	CSS animation utilities
`DOMSecurity`	Safe DOM manipulation
`ErrorLogger`	Error logging utilities
`EventHelpers`	DOM event helpers
`EventListenerManager`	Managed event listeners
`EventBus`	Pub/sub event bus
`FetchHelper`	Fetch with cache/timeout
`FileValidator`	File type & size validation
`MapHelpers`	MapLibre GL JS map utilities
`PerformanceProfiler`	Timing/perf profiling
`LazyLoader`	Module lazy loader utilities
`TimerManager`	Managed timers/debounce
`ObjectUtils` / `ScaleUtils`	Object & scale helpers

Config

import { Config } from "@geoleaf/core";
// or: GeoLeaf.Config (CDN/global)

Config.get("map"); // Get a config section
Config.get("ui"); // Get UI config
Config.set("key", value); // Set a config value

Search — search engine

import { Search } from "@geoleaf/core";
// or: GeoLeaf.Search (CDN/global) — requires _loadModule("search")

Full-text POI search backed by FlexSearch (with native includes() fallback when FlexSearch is unavailable).

Method	Signature	Description
`isReady`	`() => boolean`	Returns `true` when the FlexSearch index is built
`query`	`(text: string) => Set<string>`	Returns a Set of matching POI IDs
`build`	`(pois: any[]) => void`	(Re)build the index from a POI array
`getEngine`	`() => "flexsearch" \| "native"`	Returns the active engine name
`clear`	`() => void`	Clears the index (e.g. on profile switch)

if (GeoLeaf.Search.isReady()) {
    const ids = GeoLeaf.Search.query("randonnée");
}

Auto-build: The index is built automatically on geoleaf:poi:loaded. build() is only needed for manual reloads.

Geocoding — address search

import { Geocoding } from "@geoleaf/core";
// or: GeoLeaf.Geocoding (CDN/global)

Controle de recherche d'adresse intégré à la carte. Supporte 4 providers (BAN/Addok, Nominatim, Photon, custom HTTPS). Activé via geocodingConfig.enabled: true dans le profil.

Méthode	Signature	Description
`isEnabled`	`() => boolean`	Retourne `true` si le module geocoding est actif
`search`	`(query: string, limit?: number) => Promise<GeocodingResult[]>`	Recherche d'adresse et retourne les résultats
`selectResult`	`(result: GeocodingResult) => void`	Sélectionne un résultat (zoom + émission de l'événement)
`destroy`	`() => void`	Supprime le contrôle de la carte et nettoie les listeners

Type GeocodingResult :

interface GeocodingResult {
    label: string; // Adresse formattée
    lat: number; // Latitude WGS 84
    lng: number; // Longitude WGS 84
    bounds?: { north: number; south: number; east: number; west: number }; // Emprise optionnelle
    raw?: unknown; // Réponse brute du provider
}

Exemple :

if (GeoLeaf.Geocoding.isEnabled()) {
    const results = await GeoLeaf.Geocoding.search("Paris", 5);
    if (results.length > 0) {
        GeoLeaf.Geocoding.selectResult(results[0]); // zoom vers le premier résultat
    }
}

Configuration (dans geocodingConfig du profil) :

json

{
    "geocodingConfig": {
        "enabled": true,
        "provider": "addok",
        "position": "top-right",
        "placeholder": "Rechercher une adresse…",
        "minChars": 3,
        "resultLimit": 5,
        "debounceMs": 300,
        "flyToZoom": 15
    }
}

Providers disponibles : "addok" (BAN France, défaut), "nominatim" (OSM, mondial), "photon" (Komoot, mondial), ou une URL HTTPS custom.

Événement émis : geoleaf:geocoding:result avec payload { label, lat, lng, bounds } lors de la sélection d’un résultat.

import { Permalink } from "@geoleaf/core";
// or: GeoLeaf.Permalink (CDN/global)

Synchronises map state (center, zoom, active layers, filters) to the URL hash or query string. Enable in config: { "ui": { "permalink": { "enabled": true, "mode": "hash" } } }.

Method	Signature	Description
`init`	`(config: PermalinkConfig) => void`	Initialise with the `ui.permalink` config block
`readAndStore`	`() => void`	Parse current URL and cache the state
`applyStoredState`	`(map: any) => void`	Restore the cached state to a map instance
`startSync`	`(map: any) => void`	Begin continuous URL synchronisation on map move/zoom
`getState`	`() => PermalinkState \| null`	Return the last cached state (read-only)
`buildUrl`	`(state?: PermalinkState \| null) => string`	Serialise a state to a URL fragment/query string

// Typical lifecycle (handled automatically by the boot sequence):
Permalink.init(config.ui.permalink);
Permalink.readAndStore(); // before map creation
Permalink.applyStoredState(map); // after map + modules are ready
Permalink.startSync(map); // begin sync

Security: lat, lng, zoom are validated via validateNumber() / validateCoordinates(). Layer IDs are string-filtered (max 100 entries). Filter text is truncated to 200 chars.

Notifications — toast notifications

import { Notifications } from "@geoleaf/core";
// or: GeoLeaf.Notifications (CDN/global) — or shortcut: GeoLeaf.notify(msg, type)

Displays non-blocking toast messages. Queued automatically when the DOM is not yet ready.

Method	Signature	Description
`notify`	`(msg, type?, duration?) => void`	Display a toast (generic)
`success`	`(msg, opts?) => void`	Green success toast
`error`	`(msg, opts?) => void`	Red error toast (5 s default, persistent option)
`warning`	`(msg, opts?) => void`	Yellow warning toast
`info`	`(msg, opts?) => void`	Blue informational toast
`dismiss`	`(toastEl: HTMLElement) => void`	Dismiss a specific toast
`clearAll`	`() => void`	Remove all toasts and clear the queue
`getStatus`	`() => NotifyStatus`	Return current system state (activeToasts, queued)

Notifications.success("Données chargées");
Notifications.error("Échec du chargement", { persistent: true, dismissible: true });
Notifications.notify("Info", "info", { duration: 8000 });

PWA — install prompt

import { PWA } from "@geoleaf/core";
// or: GeoLeaf.PWA (CDN/global)

Manages the Progressive Web App install banner (iOS) and install prompt (Chrome/Android). Activated automatically by the boot sequence when pwa.installPrompt.enabled: true in config.

Method	Signature	Description
`init`	`(config: PWAConfig) => void`	Initialise PWA features (called by boot — opt-in only)

// Opt-in via geoleaf.config.json:
// { "pwa": { "installPrompt": { "enabled": true } } }

// Manual check (advanced):
GeoLeaf.PWA.init({ installPrompt: { enabled: true } });

Note: PWA features are opt-in. Without installPrompt.enabled: true, init() is a no-op.

Lazy loading system

See ARCHITECTURE_GUIDE.md for detailed documentation on _loadModule() and _loadAllSecondaryModules().

// Load a single module
await GeoLeaf._loadModule("poi");

// Load all secondary modules
await GeoLeaf._loadAllSecondaryModules();

Available module names: "poi", "poiCore", "poiRenderers", "poiExtras", "basemapSelector", "route", "layerManager", "legend", "labels", "themes", "table", "search".

Note — Lite build: bundle-core-lite-entry does not support "route", "labels", "table", or "search" — these are excluded from the lite bundle.

Global namespace (window.GeoLeaf.*)

After loading dist/geoleaf.esm.js via CDN (<script type="module">), the following properties are available on window.GeoLeaf (populated during boot B1→B11):

Property	Available since	Description
`GeoLeaf.Core`	Boot B11	Map lifecycle
`GeoLeaf.POI`	Boot B11 (lazy)	Points of interest
`GeoLeaf.UI`	Boot B11	UI controls
`GeoLeaf.Filters`	Boot B11	Filters
`GeoLeaf.Route`	Boot B11 (lazy)	Routing
`GeoLeaf.Table`	Boot B11 (lazy)	Data table
`GeoLeaf.Legend`	Boot B11 (lazy)	Legend panel
`GeoLeaf.LayerManager`	Boot B11 (lazy)	Layer management
`GeoLeaf.Baselayers`	Boot B11	Base tile layers
`GeoLeaf.Helpers`	Boot B11	Helpers
`GeoLeaf.Validators`	Boot B11	Validators
`GeoLeaf.Themes`	Boot B11 (lazy)	Theme system
`GeoLeaf.Labels`	Boot B11 (lazy)	Labels
`GeoLeaf.Utils`	Boot B2	Utilities
`GeoLeaf.CONSTANTS`	Boot B1	Constants
`GeoLeaf.Log`	Boot B1	Logging
`GeoLeaf.Errors`	Boot B1	Error classes
`GeoLeaf.Security`	Boot B1	XSS/CSRF protection
`GeoLeaf.Config`	Boot B4	Config access
`GeoLeaf.Search`	Boot B11 (lazy)	Full-text POI search
`GeoLeaf.Geocoding`	Boot B11	Recherche d'adresse
`GeoLeaf.Permalink`	Boot B4	URL deep linking
`GeoLeaf.Notifications`	Boot B4	Toast notifications
`GeoLeaf.PWA`	Boot B4	PWA install prompt
`GeoLeaf.Storage`	Runtime (plugin)	Storage plugin namespace
`GeoLeaf.PluginRegistry`	Boot B11	Plugin registry
`GeoLeaf._loadModule`	Boot ESM	Lazy load a module
`GeoLeaf._loadAllSecondaryModules`	Boot ESM	Load all lazy modules
`GeoLeaf._version`	Boot B1	Version string

TypeDoc (generated): Run npm run docs:api in packages/core to generate complete API documentation from TSDoc comments into docs/api/.

TypeScript types

@geoleaf/core ships TypeScript declarations. The canonical types entry point is:

// tsconfig.json path (built declarations)
"types": ["@geoleaf/core"]
// Resolves to: node_modules/@geoleaf/core/dist/types/bundle-esm-entry.d.ts

Key types exported from the package:

import type {
    GeoLeafBootOptions,
    GeoLeafConfig,
    GeoLeafProfile,
    GeoLeafEventMap,
    GeocodingConfig,
    GeocodingResult,
    PoiLike,
    LayerConfig,
    ThemeConfig,
} from "@geoleaf/core";

All public façades (GeoLeaf.*) are typed as the matching *Api interface found in packages/core/src/contracts/. See packages/core/index.d.ts at the package root for the legacy re-export shim, or use the full declarations in dist/types/.

GeoLeaf-JS — API Reference ​

Table of contents ​

ESM named exports (31) ​

GeoLeafAPI — top-level API ​

Methods ​

Properties ​

Core — map lifecycle ​

POI — points of interest ​

UI — interface controls ​

Filters — filter system ​

Route — routing ​

Table — data table ​

Legend — legend panel ​

LayerManager — GeoJSON layers ​

Baselayers — base tiles ​

Helpers ​

Validators ​

Themes — theme system ​

API sub-modules ​

PluginRegistry ​

showBootInfo / BootInfo ​

Log ​

Errors — typed error classes ​

CONSTANTS ​

Utils ​

Config ​

Search — search engine ​

Geocoding — address search ​

Notifications — toast notifications ​

PWA — install prompt ​

Lazy loading system ​

Global namespace (window.GeoLeaf.*) ​

TypeScript types ​