GeoLeaf.Legend — Documentation du module Legend

Version : 2.0.0 Fichier source (monorepo) : packages/core/src/modules/optional/legend/legend-api.tsFacade publique : packages/core/src/modules/geoleaf.legend.tsDernière mise à jour : mars 2026

---

Rôle fonctionnel

Le module GeoLeaf.Legend gère l'affichage de la légende cartographique dans GeoLeaf. La légende est générée automatiquement depuis les fichiers de style des couches déclarées dans le profil JSON. Elle se positionne sur la carte (par défaut en bas à gauche) et affiche l'ensemble des couches visibles avec leurs entrées de style.

Ce module est distinct de GeoLeaf.LayerManager (voir section « Distinction » ci-dessous).

Architecture interne (v2.0.0)

optional/legend/
├── legend-api.ts       // Module principal — état, initialisation, API publique
├── legend-control.ts   // Contrôle MapLibre (rendu DOM de la légende)
├── legend-renderer.ts  // Rendu des items (symboles, accordéons)
└── legend-generator.ts // Génération des données légende depuis un style JSON

---

API publique

GeoLeaf.Legend.init(mapInstance, options?)

Initialise la légende et l'attache à la carte MapLibre.

Paramètres :

• mapInstance (maplibre.Map) : Instance MapLibre GL requis
• options (Object, optionnel) :
  • position : "bottomleft" (défaut), "bottomright", "topleft", "topright"
  • collapsible : true (défaut)
  • collapsed : false (défaut)
  • title : "Legend" (défaut)

Retourne : boolean (succès)

import maplibregl from "maplibre-gl";
const map = new maplibregl.Map({ container: "map", style: "..." });
GeoLeaf.Legend.init(map);

// Avec options
GeoLeaf.Legend.init(map, {
    position: "bottomright",
    collapsed: false,
    title: "Légende des couches",
});

Les paramètres sont aussi lus depuis legendConfig dans geoleaf.config.json :

{
    "legendConfig": {
        "position": "bottomleft",
        "collapsedByDefault": false,
        "title": "Légende des couches"
    }
}

---

GeoLeaf.Legend.loadLayerLegend(layerId, styleId, layerConfig)

Charge la légende d'une couche GeoJSON à partir de son fichier de style. Appelée automatiquement lors du chargement des couches GeoJSON.

Paramètres :

• layerId (string) : Identifiant de la couche
• styleId (string) : Identifiant du style actif
• layerConfig (Object) : Configuration de la couche (issue du profil JSON)

// Normalement appelée en interne par le module GeoJSON.
// Pour usage manuel avancé :
GeoLeaf.Legend.loadLayerLegend("parcs", "default", layerConfig);

---

GeoLeaf.Legend.setLayerVisibility(layerId, visible)

Contrôle la visibilité d'une couche dans la légende.

Paramètres :

• layerId (string) : Identifiant de la couche
• visible (boolean) : true = visible, false = cachée

// Cacher la couche "parcs" dans la légende
GeoLeaf.Legend.setLayerVisibility("parcs", false);

// Afficher la couche "zones" dans la légende
GeoLeaf.Legend.setLayerVisibility("zones", true);

---

GeoLeaf.Legend.getAllLayers()

Retourne toutes les couches enregistrées dans la légende.

Retourne : Map<string, LayerInfo> (Map JavaScript)

const layers = GeoLeaf.Legend.getAllLayers();
layers.forEach((info, layerId) => {
    console.log(layerId, info.visible, info.label);
});

---

GeoLeaf.Legend.hideLegend()

Masque la légende sans la supprimer.

GeoLeaf.Legend.hideLegend();

---

GeoLeaf.Legend.removeLegend()

Supprime complètement la légende de la carte et efface toutes les données de couches.

GeoLeaf.Legend.removeLegend();

---

GeoLeaf.Legend.isLegendVisible()

Indique si la légende est actuellement visible (contrôle présent + au moins une couche).

Retourne : boolean

if (GeoLeaf.Legend.isLegendVisible()) {
    console.log("La légende est affichée");
}

---

GeoLeaf.Legend.showLoadingOverlay() / GeoLeaf.Legend.hideLoadingOverlay()

Affiche ou masque l'overlay de chargement (spinner) sur la légende. Utilisé en interne lors du chargement asynchrone des styles.

GeoLeaf.Legend.showLoadingOverlay();
// ... chargement
GeoLeaf.Legend.hideLoadingOverlay();

---

Résumé de l'API

Méthode	Rôle
init(mapInstance, options?)	Initialise la légende sur la carte
loadLayerLegend(layerId, styleId, layerConfig)	Charge la légende d'une couche GeoJSON
setLayerVisibility(layerId, visible)	Affiche/masque une couche dans la légende
getAllLayers()	Retourne toutes les couches enregistrées
hideLegend()	Masque la légende
removeLegend()	Supprime la légende et efface les données
isLegendVisible()	Retourne si la légende est actuellement visible
showLoadingOverlay()	Affiche le spinner de chargement
hideLoadingOverlay()	Masque le spinner de chargement

---

Intégration avec le profil JSON

La légende est générée automatiquement à partir des couches déclarées dans geoleaf.config.json :

{
    "legendConfig": {
        "position": "bottomleft",
        "collapsedByDefault": false,
        "title": "Légende"
    },
    "geojsonLayers": [
        {
            "id": "parcs",
            "configFile": "layers/parcs.config.json",
            "geometryType": "Polygon"
        }
    ]
}

Séquence d'initialisation :

1. GeoLeaf.Config.load() lit le fichier JSON.
2. GeoLeaf.Core.init() crée la carte MapLibre.
3. GeoLeaf.Legend.init(map) s'initialise depuis legendConfig (ou défauts).
4. Le module GeoJSON charge les couches et appelle GeoLeaf.Legend.loadLayerLegend() automatiquement.
5. La légende charge le fichier de style associé et génère les entrées visuelles.
6. La légende s'affiche avec les accordéons de chaque couche visible.

---

Distinction Legend vs LayerManager

GeoLeaf expose deux modules distincts pour la gestion des couches :

Aspect	GeoLeaf.Legend	GeoLeaf.LayerManager
Facade	packages/core/src/modules/geoleaf.legend.ts	packages/core/src/modules/geoleaf.layer-manager.ts
Source	src/modules/optional/legend/legend-api.ts	src/modules/built-in/layer-manager/index.ts
Rôle	Légende cartographique automatique (générée depuis styles)	Gestionnaire de couches UI (panneau interactif MapLibre Control)
Gestion	Couches GeoJSON et leur rendu légendaire	Sections configurables (basemaps, couches, thèmes)
Chargement	Automatique depuis styles des couches	Manuel via sections JSON ou addSection()
Alias ?	Non — module indépendant	Non — module indépendant

Ces deux modules sont indépendants et non aliasés.

---

Modules liés

• GeoLeaf.Core : Fournit l'instance de carte
• GeoLeaf.LayerManager : Panneau de gestion des couches UI
• GeoLeaf.Themes : Thèmes visuels appliqués à la légende