feat(LayerSwitcher) : Mise en place de tooltips HTML avancés au survol des couches (#420)

Author: lowzonenose

DRAFT_CHANGELOG.md

@@ -18,6 +18,7 @@ __DATE__
   - Territories : Ajout d'un menu option pour permettre de charger une configuration des territoires (#408)
   - LayerSwitcher : Possibilité d'ajouter des outils externes (#418)
   - LayerSwitcher : Option pour verrouiller une couche (#414)
+  - LayerSwitcher : Tooltips avancés en HTML sur le survol des couches (#420)
 
 * 🔨 [Changed]
 

doc/NOTE-LAYERSWITCHER.md

@@ -68,6 +68,181 @@ layerSwitcher.on("layerswitcher:change:visibility", e => console.log("Visibilit
 `LayerSwitcher` facilite la gestion interactive des couches sur une carte OpenLayers, 
 tout en offrant de nombreuses options de personnalisation et une API d’événements riche pour les développeurs.
 
+## Voici un résumé des principales options disponibles pour le contrôle **LayerSwitcher**
+
+- **id** : Identifiant unique du widget (utile si plusieurs LayerSwitcher sur la même page).
+- **collapsed** *(booléen, défaut : true)* : Définit si le widget est replié (caché) ou déplié au chargement.
+- **draggable** *(booléen)* : Permet de déplacer le panneau du LayerSwitcher à la souris.
+- **counter** *(booléen)* : Affiche un compteur du nombre de couches visibles.
+- **panel** *(booléen)* : Affiche un en-tête (header) dans le panneau du LayerSwitcher.
+- **gutter** *(booléen)* : Ajoute ou retire l’espace (gutter) autour du panneau.
+- **allowEdit** *(booléen, défaut : true)* : Affiche le bouton d’édition pour les couches éditables (vecteur).
+- **allowGrayScale** *(booléen, défaut : true)* : Affiche le bouton N&B (niveaux de gris) pour les couches compatibles.
+- **allowTooltips** *(booléen, défaut : false)* : Active l’affichage des info-bulles (tooltips) sur les éléments du widget.
+- **advancedTools** *(array)* : Liste d’outils personnalisés à afficher pour chaque couche (boutons d’action, icônes, callbacks, etc.).
+- **layers** *(array)* : Liste des couches à configurer à l’initialisation, chaque entrée pouvant contenir :
+  - **layer** : Objet `ol.layer.Layer` à gérer.
+  - **config** : Métadonnées associées (titre, description, légendes, métadonnées, quicklookUrl, etc.).
+
+---
+
+**Résumé** :  
+Les options du LayerSwitcher permettent de personnaliser l’apparence, le comportement, les fonctionnalités et les actions disponibles pour chaque couche, afin d’adapter le widget à vos besoins cartographiques et ergonomiques.
+
+## Voici un exemple complet d’utilisation du contrôle **LayerSwitcher** avec OpenLayers
+
+````javascript
+import 'ol/ol.css';
+import Map from 'ol/Map';
+import View from 'ol/View';
+import TileLayer from 'ol/layer/Tile';
+import OSM from 'ol/source/OSM';
+import VectorLayer from 'ol/layer/Vector';
+import VectorSource from 'ol/source/Vector';
+import {fromLonLat} from 'ol/proj';
+import LayerSwitcher from 'src/packages/Controls/LayerSwitcher/LayerSwitcher.js';
+
+// Création des couches
+const osmLayer = new TileLayer({
+    source: new OSM(),
+    visible: true,
+    opacity: 1,
+    title: 'Fond OpenStreetMap'
+});
+
+const vectorLayer = new VectorLayer({
+    source: new VectorSource(),
+    visible: true,
+    opacity: 0.7,
+    title: 'Annotations'
+});
+
+// Création de la carte
+const map = new Map({
+    target: 'map',
+    layers: [osmLayer, vectorLayer],
+    view: new View({
+        center: fromLonLat([2.35, 48.85]), // Paris
+        zoom: 12
+    })
+});
+
+// Ajout du LayerSwitcher avec options et métadonnées
+const layerSwitcher = new LayerSwitcher({
+    layers: [
+        {
+            layer: osmLayer,
+            config: {
+                title: "Fond OpenStreetMap",
+                description: "Fond cartographique OSM",
+                locked: true // couche verrouillée
+            }
+        },
+        {
+            layer: vectorLayer,
+            config: {
+                title: "Annotations",
+                description: "Couches d’annotations éditables"
+            }
+        }
+    ],
+    options: {
+        collapsed: false,
+        panel: true,
+        counter: true,
+        allowEdit: true,
+        allowGrayScale: true,
+        allowTooltips: true,
+        advancedTools: [
+            {
+                label: 'Exporter',
+                icon: '📤',
+                cb: (e, instance, layer, options) => {
+                    alert("Export de la couche : " + layer.get("title"));
+                }
+            },
+            {
+                label: 'Info',
+                icon: '<svg width="16" height="16" fill="currentColor"><circle cx="8" cy="8" r="7" stroke="black" stroke-width="1" fill="none"/><text x="8" y="12" text-anchor="middle" font-size="10" fill="black">i</text></svg>',
+                // Pas de cb : déclenche l'événement layerswitcher:custom
+            }
+        ]
+    }
+});
+
+map.addControl(layerSwitcher);
+
+// Exemple d’écoute d’événements
+layerSwitcher.on("layerswitcher:add", function (e) {
+    console.log("Couche ajoutée :", e.layer);
+});
+layerSwitcher.on("layerswitcher:remove", function (e) {
+    console.log("Couche supprimée :", e.layer);
+});
+layerSwitcher.on("layerswitcher:edit", function (e) {
+    alert("Edition de la couche : " + e.layer.get("title"));
+});
+layerSwitcher.on("layerswitcher:custom", function (e) {
+    alert("Action personnalisée sur : " + e.layer.get("title") + " (" + e.action + ")");
+});
+````
+
+**À placer dans une page HTML avec un conteneur** :
+
+```html
+<div id="map" style="width:100%;height:600px;"></div>
+<script type="module" src="example-layerswitcher.js"></script>
+```
+
+---
+
+**Ce que montre cet exemple :**
+- Création de couches raster et vecteur,
+- Ajout de métadonnées (titre, description, verrouillage),
+- Activation des options avancées (édition, N&B, tooltips, outils personnalisés),
+- Gestion des événements du LayerSwitcher,
+- Utilisation d’outils avancés avec ou sans callback.
+
+Cet exemple est prêt à l’emploi pour tester toutes les fonctionnalités principales du LayerSwitcher.
+
+## Voici une explication sur l’objet `layerOptions` dans le LayerSwitcher
+
+### Fonctionnement de l’objet `layerOptions`
+
+L’objet `layerOptions` est une structure centrale utilisée en interne par le LayerSwitcher pour stocker toutes les informations et états associés à chaque couche affichée dans le widget.
+
+### Où est-il créé ?
+`layerOptions` est construit dans la méthode privée `_createLayerDiv(layerOptions)` et lors de l’ajout d’une couche via `addLayer` ou `_addMapLayers`.  
+Il regroupe à la fois :
+- les propriétés de la couche OpenLayers (`layer`, `id`, `opacity`, `visibility`, etc.),
+- les métadonnées de configuration (titre, description, légendes, etc.),
+- les états d’interface (editable, grayable, inRange, locked, etc.),
+- les références DOM (div associée à la couche).
+
+### Principaux champs de `layerOptions` :
+
+- **layer** : la référence à l’objet `ol.layer.Layer` concerné.
+- **id** : identifiant unique de la couche dans le LayerSwitcher.
+- **name, service, type** : informations complémentaires (souvent pour les couches Geoportail).
+- **opacity, visibility, grayscale, locked** : états d’affichage de la couche.
+- **inRange** : indique si la couche est visible dans la vue courante (zoom/emprise).
+- **title, description** : informations affichées dans la liste et les tooltips.
+- **legends, metadata, quicklookUrl** : ressources associées à la couche.
+- **editable, grayable** : indique si la couche est éditable ou peut passer en N&B.
+- **advancedTools** : liste des outils personnalisés à afficher pour la couche.
+- **div** : référence à la div DOM représentant la couche dans le LayerSwitcher.
+
+### Utilité
+
+- Permet de centraliser toutes les informations nécessaires à l’affichage, à l’interaction et à la gestion de chaque couche dans le widget.
+- Facilite la synchronisation entre l’état de la carte, la configuration utilisateur et l’interface graphique.
+- Sert de point d’accès unique pour toutes les opérations (édition, suppression, changement d’opacité, etc.).
+
+---
+
+**Résumé :**  
+`layerOptions` est l’objet de référence pour chaque couche dans le LayerSwitcher : il regroupe toutes les données, états et références nécessaires à la gestion et à l’affichage de la couche dans le widget.
+
 ## Voici une explication sur la notion de couches « grisées » (hors plage de visibilité, via `isInRange`) dans la classe `LayerSwitcher`
 
 ### Couches grisées (isInRange)
@@ -230,7 +405,7 @@ const layerSwitcher = new LayerSwitcher({
 **Résumé :**  
 Le mode N&B dans le LayerSwitcher permet d’afficher certaines couches en niveaux de gris, offrant ainsi une meilleure lisibilité et une personnalisation avancée de la carte pour l’utilisateur.
 
-## Voici une explication à ajouter à votre documentation concernant les **actions utilisateurs via l’option `advancedTools`** dans le LayerSwitcher
+## Voici une explication concernant les **actions utilisateurs via l’option `advancedTools`** dans le LayerSwitcher
 
 ### Actions utilisateurs via l’option `advancedTools`
 
@@ -348,6 +523,21 @@ Voici quelques exemples concrets :
   }
   ```
 
+- **Bouton avec un icone dsfr**  
+  Permet d'utiliser les icones du DSFR :
+  ```javascript
+  {
+      label: 'Exporter',
+      icon: 'fr-icon-export',
+      cb: (e, instance, layer, options) => {
+          alert("Export de la couche : " + layer.get("title"));
+      },
+      styles: {
+          color: "blue"
+      }
+  }
+  ```
+
 Si l’option `cb` n’est pas renseignée dans un objet `advancedTools`, le bouton est tout de même affiché et, lors du clic, **un événement personnalisé est déclenché** par le LayerSwitcher (généralement `layerswitcher:custom`).  
 Cet événement contient les informations sur le bouton cliqué, la couche concernée, etc.
 
@@ -366,3 +556,49 @@ Cela permet de centraliser la gestion des actions non définies directement par
 
 **Résumé :**  
 L’option `advancedTools` du LayerSwitcher permet d’ajouter facilement des boutons d’action personnalisés pour chaque couche, afin d’enrichir l’interface et de proposer des fonctionnalités avancées adaptées à vos besoins.
+
+## Voici une explication détaillée du fonctionnement des **tooltips** dans le LayerSwitcher
+
+---
+
+### Fonctionnement des tooltips dans le LayerSwitcher
+
+Le LayerSwitcher propose une option `allowTooltips` qui permet d’afficher des info-bulles (tooltips) sur les éléments de l’interface, afin d’améliorer l’ergonomie et l’accessibilité.
+
+### Initialisation
+
+- Lors de l’ajout du contrôle à la carte (`setMap`), si l’option `allowTooltips` est activée, le module `ToolTips` initialise un conteneur HTML dédié pour les info-bulles.
+- Ce conteneur est un `<div>` positionné en absolu, stylisé pour ressembler à une info-bulle classique.
+
+### Activation sur les éléments
+
+- Chaque nom de couche du LayerSwitcher recoit un attribut `data-tooltip` contenant le texte à afficher.
+- Le module `ToolTips` ajoute des écouteurs d’événements `mouseenter` et `mouseleave` sur ces éléments :
+  - Au survol (`mouseenter`), le contenu du tooltip est affiché près du curseur.
+  - À la sortie (`mouseleave`), le tooltip disparaît.
+
+### Contenu des tooltips
+
+- Pour le nom d’une couche, le tooltip affiche généralement le titre complet ou la description.
+- Pour les couches hors plage ou verrouillées, un message spécifique explique la raison de l’état.
+
+### Utilité
+
+- **Accessibilité** : Les tooltips aident à comprendre la fonction de chaque élément, même sans documentation.
+- **Aide contextuelle** : Ils fournissent des explications sur l’état ou l’action possible.
+- **Ergonomie** : Ils évitent la surcharge visuelle tout en offrant une aide à la demande.
+
+### Exemple d’activation
+
+```javascript
+const layerSwitcher = new LayerSwitcher({
+    options: {
+        allowTooltips: true // Active l’affichage des tooltips
+    }
+});
+```
+
+---
+
+**Résumé :**  
+Les tooltips dans le LayerSwitcher sont des info-bulles contextuelles qui s’affichent au survol des éléments, facilitant la compréhension et l’utilisation du gestionnaire de couches, notamment pour les utilisateurs novices ou en situation de handicap.

package.json

@@ -1,8 +1,8 @@
 {
   "name": "geopf-extensions-openlayers",
   "description": "French Geoportal Extensions for OpenLayers libraries",
-  "version": "1.0.0-beta.5-421",
-  "date": "28/07/2025",
+  "version": "1.0.0-beta.5-420",
+  "date": "25/07/2025",
   "module": "src/index.js",
   "directories": {},
   "engines": {

samples-src/pages/tests/LayerSwitcher/pages-ol-layerswitcher-modules-dsfr-tooltips.html

@@ -0,0 +1,80 @@
+{{#extend "ol-sample-modules-dsfr-layout"}}
+
+{{#content "vendor"}}
+
+        <link rel="stylesheet" href="{{ baseurl }}/dist/modules/GpfExtOlLayerSwitcher.css" />
+        <script src="{{ baseurl }}/dist/modules/GpfExtOlLayerSwitcher.js"></script>
+        <script src="{{ baseurl }}/dist/modules/GpfExtOlLayers.js"></script>
+{{/content}}
+
+{{#content "head"}}
+        <title>Sample openlayers LayerSwitcher</title>
+{{/content}}
+
+{{#content "style"}}
+        <style>
+            div#map {
+                width: 100%;
+                height: 500px;
+            }
+        </style>
+{{/content}}
+
+{{#content "body"}}
+            <h2>Ajout du gestionnaire de couches avec les options par défaut</h2>
+            <!-- map -->
+            <div id="map">
+            </div>
+{{/content}}
+
+{{#content "js"}}
+            <script type="text/javascript">
+                var map;
+                var createMap = function () {
+                    // on cache l'image de chargement du Géoportail.
+                    document.getElementById('map').style.backgroundImage = 'none';
+                    
+                    map = new ol.Map({
+                        target : "map",
+                        view : new ol.View({
+                            center : [288074.8449901076, 6247982.515792289],
+                            zoom : 16
+                        }),
+                        layers : [
+                            new ol.layer.GeoportalWMTS({
+                                layer : "GEOGRAPHICALGRIDSYSTEMS.PLANIGNV2"
+                            })
+                        ]
+                    });
+
+                    var layerSwitcher = new ol.control.LayerSwitcher({
+                        options :{
+                            panel: true,
+                            allowTooltips: true
+                        }
+                    });
+                    map.addControl(layerSwitcher);
+                    
+                    // Couches
+                    var plan = new ol.layer.GeoportalMapBox({
+                        layer : "PLAN.IGN"
+                    });
+                    plan.on("mapbox:style:loaded", (e) => {
+                        console.log(e);
+                    });
+                    map.addLayer(plan);
+                };
+                Gp.Services.getConfig({
+                    customConfigFile : "{{ resources }}/data/configuration/config-catalog.json",
+                    callbackSuffix : "",
+                    // apiKey: "{{ apikey }}",
+                    timeOut : 20000,
+                    onSuccess : createMap,
+                    onFailure : (e) => {
+                        console.error(e);
+                    }
+                });
+           </script>
+{{/content}}
+
+{{/extend}}