GeoLeaf.UI — Documentation du module UI

Product Version: GeoLeaf Platform V2

Version : 2.0.0

Module : packages/core/src/modules/built-in/ui/ (façade : geoleaf.ui.ts)

Dernière mise à jour : mars 2026

Le module GeoLeaf.UI gère tous les aspects d'interface utilisateur de GeoLeaf. Il adopte une architecture modulaire avec des sous-modules spécialisés pour des responsabilités spécifiques.

Architecture du module UI

Le module UI est organisé en sous-modules TypeScript :

Fichier source	Responsabilités
`geoleaf.ui.ts` (façade)	Export de `UI` depuis `built-in/ui/ui-api.ts`
`ui-api.ts` (orchestrateur)	Délégation vers sous-modules thème, contrôles, filtres, notifications
`ui/theme.ts`	Thème light/dark : détection système, persistance, application classes CSS
`ui/controls.ts`	Contrôles MapLibre : fullscreen, géolocalisation, ajout POI, toggle thème
`ui/notifications.ts`	Système de toast notifications
`ui/filter-panel.ts`	Panneau de filtres (lazy-loaded)
`ui/filter-state-manager.ts`	Gestion des états de filtres
`ui/event-delegation.ts`	Délégation d'événements DOM
`ui/content-builder/`	Construction contenu POI (popups, panels, tooltips)

Documentation détaillée par composant :
GeoLeaf_UI_Components_README.md - Composants UI internes
content-builder/README.md - Content Builder

Responsabilités du module UI

GeoLeaf.UI gère 5 domaines fonctionnels :

1. Gestion des thèmes visuels

Application thème light/dark sur <body> et #geoleaf-map
Détection préférence système (prefers-color-scheme) via initAutoTheme()
Persistance dans localStorage (clé geoleaf_theme)
Toggle interactif via data-gl-role="theme-toggle"
Écoute continue de matchMedia pour le suivi des changements OS en mode auto

2. Construction de panneaux POI

Rendu side panel POI avec layouts JSON personnalisables (via content-builder/)
Résolution de champs dynamiques (dot notation : attributes.rating)
15+ types de champs supportés (title, text, image, gallery, rating, etc.)
Sections accordéon/plain

3. Panneaux de filtres

Construction interface filtres depuis configuration profil (lazy-loaded)
Intégration avec GeoLeaf.Filters
Gestion états filtres (catégories, tags, recherche, proximité)
Compteurs résultats dynamiques
Tags filtres actifs avec suppression

4. Contrôles MapLibre

Contrôle fullscreen personnalisé (initFullscreenControl)
Contrôle de géolocalisation (initGeolocationControl)
Contrôle d'ajout POI (initPoiAddControl)
Contrôle de toggle thème intégré à la carte (initThemeToggleControl)

5. Utilitaires DOM

Notifications toast (success, error, warning, info)
Délégation d'événements
Gestion de l'état de géolocalisation

Ce que GeoLeaf.UI NE gère PAS :
Fonds de carte (voir GeoLeaf.Baselayers)
Données POI/Routes (voir GeoLeaf.POI / GeoLeaf.Route)
Logique de filtrage (voir GeoLeaf.Filters)
GeoJSON (module interne, configuré via geojsonLayers dans profile.json)
Légende (voir GeoLeaf.Legend)

API Publique

API Thème

Fonction	Description	Retour
`getCurrentTheme()`	Retourne le thème actif (`"light"` ou `"dark"`)	`string`
`applyTheme(theme, persist?)`	Applique un thème (`"light"`, `"dark"`)	`void`
`toggleTheme()`	Bascule entre light/dark	`void`
`initThemeToggle(options)`	Initialise le bouton toggle thème	`void`
`initAutoTheme(themeConfig)`	Initialise le thème auto selon `ui.theme` du profil	`void`

Exemple :

// Appliquer thème sombre
GeoLeaf.UI.applyTheme("dark");

// Récupérer thème actuel
const theme = GeoLeaf.UI.getCurrentTheme(); // "dark"

// Toggle
GeoLeaf.UI.toggleTheme(); // passe à "light"

// Initialiser depuis la config profil (appelé automatiquement par initApp)
GeoLeaf.UI.initAutoTheme("auto"); // détecte prefers-color-scheme

API Contrôles

Fonction	Description	Paramètres
`initFullscreenControl(map, container)`	Initialise le contrôle fullscreen	`map`: maplibre.Map, `container`: HTMLElement
`initGeolocationControl(map, options)`	Initialise la géolocalisation	`map`: maplibre.Map, `options`: Object
`initPoiAddControl(map, options)`	Initialise l'ajout POI	`map`: maplibre.Map, `options`: Object
`initThemeToggleControl(map, options)`	Contrôle thème intégré à la carte	`map`: maplibre.Map, `options`: Object

Exemple :

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

GeoLeaf.UI.initFullscreenControl(map, container);

API Notifications

Fonction	Description
`Notifications.init(config)`	Initialise le système de notifications
`Notifications.success(msg, dur?)`	Toast succès (vert)
`Notifications.error(msg, dur?)`	Toast erreur (rouge)
`Notifications.warning(msg, dur?)`	Toast avertissement (orange)
`Notifications.info(msg, dur?)`	Toast information (bleu)
`Notifications.clearAll()`	Supprime tous les toasts actifs

Exemple :

GeoLeaf.UI.Notifications.success("Données chargées !");
GeoLeaf.UI.Notifications.error("Erreur réseau", 8000);

API Panneaux Filtres

Fonction	Description	Paramètres
`buildFilterPanelFromActiveProfile(options)`	Construit le panneau filtres depuis profil actif	`options.container`: selector/HTMLElement, `options.onFilterChange`: callback

Exemple :

GeoLeaf.UI.buildFilterPanelFromActiveProfile({
    container: "#filters-panel",
    onFilterChange: (filterState) => {
        const filteredPois = GeoLeaf.Filters.filterPoiList(allPois, filterState);
        GeoLeaf.POI.displayPois(filteredPois);
    },
});

Initialisation

Via `GeoLeaf.UI.init()`

Fonction wrapper pour initialiser les composants UI principaux :

GeoLeaf.UI.init({
    buttonSelector: '[data-gl-role="theme-toggle"]', // Sélecteur bouton thème
    autoInitOnDomReady: true, // Init auto sur DOMContentLoaded
    map: mapInstance, // Instance MapLibre
    mapContainer: document.getElementById("map"), // Conteneur pour fullscreen
});

En pratique, init() est appelé automatiquement par GeoLeaf.initApp(). Il n'est pas nécessaire de l'appeler manuellement.

Intégration Configuration JSON

Le module UI lit la configuration depuis GeoLeaf.Config (profil actif) :

json

{
    "ui": {
        "theme": "auto",
        "showCoordinates": true,
        "showScale": true,
        "scaleType": "numeric",
        "permalink": {
            "enabled": true,
            "mode": "hash"
        }
    },
    "layouts": {
        "poiSidePanel": [
            { "type": "title", "field": "label" },
            { "type": "rating", "field": "attributes.rating" }
        ]
    },
    "filters": [
        {
            "id": "categories",
            "type": "select",
            "label": "Catégorie",
            "field": "categoryId"
        }
    ]
}

Intégration avec autres modules

UI ↔ Theme (sous-module)

// geoleaf.ui.ts délègue à ui/theme.ts
GeoLeaf.UI.applyTheme("dark");
// → ui/theme.ts applique les classes CSS sur <body> et #geoleaf-map
// → dispatch event "geoleaf:ui-theme-changed"

UI ↔ Filters

// UI construit l'interface, Filters exécute la logique
const filterState = { categoryIds: ["restaurant"], searchText: "pizza" };
const filtered = GeoLeaf.Filters.filterPoiList(allPois, filterState);
GeoLeaf.POI.displayPois(filtered);

UI ↔ POI

// UI affiche détails POI dans side panel via Content Builder
GeoLeaf.POI.showPoiDetails(poi); // appelle internement le content-builder

UI ↔ Config

// UI lit profil actif pour layouts et filtres
const profile = GeoLeaf.Config.getActiveProfile();
const layout = profile.layouts?.poiSidePanel || [];

Bonnes Pratiques

A FAIRE

// 1. Utiliser applyTheme pour changements programmatiques
GeoLeaf.UI.applyTheme("dark");

// 2. Construire filtres depuis configuration
GeoLeaf.UI.buildFilterPanelFromActiveProfile({
    container: "#filters",
    onFilterChange: handleFilter,
});

// 3. Utiliser layouts pour personnaliser panneaux POI (via content-builder)
const layout = profile.layouts.poiSidePanel;
GeoLeaf.UI.renderPoiPanelWithLayout(poi, layout, container);

// 4. Déléguer logique filtrage à GeoLeaf.Filters
const filtered = GeoLeaf.Filters.filterPoiList(pois, filterState);

A EVITER

// 1. Manipuler directement les classes CSS thème
document.body.classList.add("gl-theme-dark"); // utiliser applyTheme()

// 2. Construire HTML POI manuellement
container.innerHTML = `<h2>${poi.label}</h2>`; // utiliser content-builder

// 3. Accéder directement aux sous-modules
import { _UITheme } from "ui/theme.ts"; // utiliser GeoLeaf.UI.applyTheme()

Résumé API Complète

Catégorie	Fonctions principales	Documentation
Thème	`getCurrentTheme()`, `applyTheme()`, `toggleTheme()`, `initThemeToggle()`, `initAutoTheme()`	Ce README
Contrôles	`initFullscreenControl()`, `initGeolocationControl()`, `initPoiAddControl()`, `initThemeToggleControl()`	Ce README
Notifications	`Notifications.success()`, `.error()`, `.warning()`, `.info()`, `.clearAll()`	Ce README
Filtres	`buildFilterPanelFromActiveProfile()`	Ce README
Content	`renderPoiPanelWithLayout()`	content-builder/README.md
Init	`init()`	Ce README

Voir Aussi

GeoLeaf_POI_README.md - Module POI
GeoLeaf_Filters_README.md - Module Filters
GeoLeaf_Config_README.md - Configuration
GeoLeaf_Core_README.md - Module Core

GeoLeaf.UI — Documentation du module UI ​

Architecture du module UI ​

Responsabilités du module UI ​

1. Gestion des thèmes visuels ​

2. Construction de panneaux POI ​

3. Panneaux de filtres ​

4. Contrôles MapLibre ​

5. Utilitaires DOM ​

API Publique ​

API Thème ​

API Contrôles ​

API Notifications ​

API Panneaux Filtres ​

Initialisation ​

Via GeoLeaf.UI.init() ​

Intégration Configuration JSON ​

Intégration avec autres modules ​

UI ↔ Theme (sous-module) ​

UI ↔ Filters ​

UI ↔ POI ​

UI ↔ Config ​

Bonnes Pratiques ​

A FAIRE ​

A EVITER ​

Résumé API Complète ​

Voir Aussi ​

GeoLeaf.UI — Documentation du module UI

Architecture du module UI

Responsabilités du module UI

1. Gestion des thèmes visuels

2. Construction de panneaux POI

3. Panneaux de filtres

4. Contrôles MapLibre

5. Utilitaires DOM

API Publique

API Thème

API Contrôles

API Notifications

API Panneaux Filtres

Initialisation

Via `GeoLeaf.UI.init()`

Intégration Configuration JSON

Intégration avec autres modules

UI ↔ Theme (sous-module)

UI ↔ Filters

UI ↔ POI

UI ↔ Config

Bonnes Pratiques

A FAIRE

A EVITER

Résumé API Complète

Voir Aussi