GeoLeaf.Themes — Documentation du module Themes

Product Version: GeoLeaf Platform V2 — Version doc: 2.0.0

Fichier source : packages/core/src/modules/geoleaf.themes.tsImplémentation : packages/core/src/modules/built-in/themes/themes-api.tsDernière mise à jour : mars 2026

Le module GeoLeaf.Themes gère les thèmes visuels des couches cartographiques dans GeoLeaf Platform V2 sur MapLibre GL JS.

Un thème est associé à une couche GeoJSON identifiée par son layerId. Il permet de changer le style visuel d'une couche (couleurs, symbologie) sans rechargement de données.

Les thèmes sont définis dans des fichiers themes/index.json par couche/profil, chargés à la demande.

1. Rôle fonctionnel de GeoLeaf.Themes

Charger les thèmes disponibles pour une couche depuis data/profiles/{layerId}/themes/index.json.
Appliquer un thème à une couche GeoJSON identifiée.
Persister le choix de thème dans localStorage (optionnel).
Mettre en cache les index de thèmes pour éviter les requêtes répétées.
Basculer cycliquement entre les thèmes disponibles.

2. API publique de GeoLeaf.Themes

Méthode	Rôle
`init(options)`	Initialise le module Themes
`applyTheme(layerId, themeId)`	Applique un thème à une couche
`getCurrentTheme(layerId)`	Retourne le thème actif d'une couche
`getAvailableThemes(layerId, opts)`	Retourne les thèmes disponibles pour une couche
`initializeLayerTheme(layerId, opts)`	Initialise le thème par défaut d'une couche
`loadTheme(themeOrId)`	Charge les données d'un thème par ID
`toggleTheme(layerId)`	Bascule vers le thème suivant disponible
`clearRememberedThemes()`	Supprime les thèmes mémorisés du localStorage
`invalidateCache()`	Vide le cache des index de thèmes

3. `GeoLeaf.Themes.init(options)`

Initialise le module Themes.

GeoLeaf.Themes.init({
    rememberChoice: true, // Persiste le choix dans localStorage
});

Paramètres :

Paramètre	Type	Défaut	Description
`rememberChoice`	boolean	`false`	Mémorise le thème sélectionné par couche

Retour : true

4. `GeoLeaf.Themes.applyTheme(layerId, themeId)`

Applique un thème identifié à une couche GeoJSON.

await GeoLeaf.Themes.applyTheme("rivers", "dark");

Paramètres :

Paramètre	Type	Obligatoire	Description
`layerId`	string	oui	ID de la couche GeoJSON cible
`themeId`	string	oui	ID du thème à appliquer

Retour : Promise<boolean> — true si appliqué, false si couche introuvable.

Comportement :

Vérifie que la couche est enregistrée dans GeoJSONShared.
Met à jour l'état interne _layerThemes.
Auto-initialise le module si init() n'a pas été appelé.

Exemple

await GeoLeaf.Themes.applyTheme("rivers", "dark");
// La couche "rivers" passe au thème "dark"

5. `GeoLeaf.Themes.getCurrentTheme(layerId)`

Retourne le thème actuellement actif pour une couche.

const current = GeoLeaf.Themes.getCurrentTheme("rivers");
// → "dark" | null

Retour : string | null

6. `GeoLeaf.Themes.getAvailableThemes(layerId, options?)`

Retourne la liste des thèmes disponibles pour une couche (chargée depuis themes/index.json).

const themes = await GeoLeaf.Themes.getAvailableThemes("rivers");
// → [{ id: "light", label: "Clair" }, { id: "dark", label: "Sombre" }, ...]

Paramètres :

Paramètre	Type	Description
`layerId`	string	ID de la couche
`options.enabled`	boolean	Si `false`, retourne `[]` sans requête (désactivation rapide)
`options.directory`	string	Répertoire alternatif dans `data/profiles/` (défaut : `layerId`)

Retour : Promise<Array<{ id: string, label?: string, ... }>>

Mise en cache : Les résultats sont mis en cache par layerId. Utiliser invalidateCache() pour forcer le rechargement.

7. `GeoLeaf.Themes.initializeLayerTheme(layerId, options?)`

Initialise le thème par défaut d'une couche, en tenant compte des préférences mémorisées.

const appliedThemeId = await GeoLeaf.Themes.initializeLayerTheme("rivers", {
    default: "light",
    rememberChoice: true,
});

Paramètres :

Paramètre	Type	Description
`layerId`	string	ID de la couche
`options.default`	string	ID du thème par défaut
`options.defaultTheme`	string	Alias de `options.default`
`options.rememberChoice`	boolean	Mémorise le choix dans localStorage
`options.enabled`	boolean	Si `false`, ne fait rien

Retour : Promise<string | null> — ID du thème appliqué, ou null.

Logique de résolution du thème initial :

Thème mémorisé dans localStorage (clé gl-theme-{layerId}) si rememberChoice
Sinon : options.default ou options.defaultTheme
Sinon : premier thème disponible dans themes/index.json

8. `GeoLeaf.Themes.toggleTheme(layerId)`

Bascule vers le thème suivant dans la liste des thèmes disponibles (rotation cyclique).

await GeoLeaf.Themes.toggleTheme("rivers");
// light → dark → high-contrast → light → ...

Retour : Promise<boolean> — résultat de applyTheme().

9. `GeoLeaf.Themes.loadTheme(themeOrId)`

Charge les données d'un thème par son ID ou objet.

const themeData = await GeoLeaf.Themes.loadTheme("dark");
// → { id: "dark" }

Retour : Promise<{ id: string } | null>

10. `GeoLeaf.Themes.clearRememberedThemes()`

Supprime tous les thèmes mémorisés du localStorage (clés préfixées gl-theme-).

GeoLeaf.Themes.clearRememberedThemes();

11. `GeoLeaf.Themes.invalidateCache()`

Vide le cache des index de thèmes chargés.

GeoLeaf.Themes.invalidateCache();

Utile après une modification de profil ou un rechargement de configuration.

12. Persistance

Le thème choisi par couche est sauvegardé dans localStorage lorsque rememberChoice: true :

localStorage.getItem("gl-theme-rivers"); // → 'dark'
localStorage.getItem("gl-theme-roads"); // → 'light'

13. Format `themes/index.json`

Le fichier d'index des thèmes d'une couche est situé à : data/profiles/{layerId}/themes/index.json

Format attendu :

json

{
    "themes": [
        { "id": "light", "label": "Clair" },
        { "id": "dark", "label": "Sombre" },
        { "id": "high-contrast", "label": "Contraste élevé" }
    ]
}

Ou sous forme de tableau direct :

json

[
    { "id": "light", "label": "Clair" },
    { "id": "dark", "label": "Sombre" }
]

14. Intégration dans un profil JSON

json

{
    "geojson": {
        "layers": [
            {
                "id": "rivers",
                "url": "data/rivers.geojson",
                "stylesConfig": {
                    "enabled": true,
                    "defaultTheme": "light",
                    "rememberChoice": true
                }
            }
        ]
    }
}

Chargement dans le boot de l'application :

// Charger et appliquer le thème par défaut d'une couche
await GeoLeaf.Themes.initializeLayerTheme("rivers", {
    default: "light",
    rememberChoice: true,
});

15. Exemples d'utilisation

Sélecteur de thème UI

// Charger les thèmes disponibles et construire un sélecteur
const themes = await GeoLeaf.Themes.getAvailableThemes("rivers");
const select = document.getElementById("theme-select");

themes.forEach((theme) => {
    const option = document.createElement("option");
    option.value = theme.id;
    option.textContent = theme.label || theme.id;
    select.appendChild(option);
});

// Appliquer au changement
select.addEventListener("change", async (e) => {
    await GeoLeaf.Themes.applyTheme("rivers", e.target.value);
});

Bouton toggle

document.getElementById("toggle-theme-btn").addEventListener("click", async () => {
    await GeoLeaf.Themes.toggleTheme("rivers");
    const current = GeoLeaf.Themes.getCurrentTheme("rivers");
    console.log("Thème actif :", current);
});

Thème selon la préférence système

// Détecter la préférence système (light/dark)
const systemDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
const defaultTheme = systemDark ? "dark" : "light";

await GeoLeaf.Themes.initializeLayerTheme("rivers", {
    default: defaultTheme,
    rememberChoice: true,
});

16. Architecture interne

GeoLeaf.Themes (API publique — themes-api.ts)
    ├── _loader           (chargement index.json par couche, cache interne)
    │   ├── load(layerId, options)
    │   ├── clearCache()
    │   └── getStylesBasePath()
    ├── _manager          (gestion état courant par layerId)
    │   ├── apply(layerId, themeId)
    │   └── getCurrent(layerId)
    └── _state            (état global)
        ├── initialized
        ├── options
        ├── _layerThemes  (Map<layerId, themeId>)
        └── _availableCache (Map<layerId, themes[]>)

17. Références

Code source : packages/core/src/modules/built-in/themes/themes-api.ts
Façade : packages/core/src/modules/geoleaf.themes.ts
État partagé GeoJSON : packages/core/src/modules/shared/geojson-state.ts
Module GeoJSON : docs/geojson/GeoLeaf_GeoJSON_README.md

GeoLeaf.Themes — Documentation du module Themes ​

1. Rôle fonctionnel de GeoLeaf.Themes ​

2. API publique de GeoLeaf.Themes ​

3. GeoLeaf.Themes.init(options) ​

4. GeoLeaf.Themes.applyTheme(layerId, themeId) ​

Exemple ​

5. GeoLeaf.Themes.getCurrentTheme(layerId) ​

6. GeoLeaf.Themes.getAvailableThemes(layerId, options?) ​

7. GeoLeaf.Themes.initializeLayerTheme(layerId, options?) ​

8. GeoLeaf.Themes.toggleTheme(layerId) ​

9. GeoLeaf.Themes.loadTheme(themeOrId) ​

10. GeoLeaf.Themes.clearRememberedThemes() ​

11. GeoLeaf.Themes.invalidateCache() ​

12. Persistance ​

13. Format themes/index.json ​

14. Intégration dans un profil JSON ​

15. Exemples d'utilisation ​

Sélecteur de thème UI ​

Bouton toggle ​

Thème selon la préférence système ​

16. Architecture interne ​

17. Références ​

GeoLeaf.Themes — Documentation du module Themes

1. Rôle fonctionnel de GeoLeaf.Themes

2. API publique de GeoLeaf.Themes

3. `GeoLeaf.Themes.init(options)`

4. `GeoLeaf.Themes.applyTheme(layerId, themeId)`

Exemple

5. `GeoLeaf.Themes.getCurrentTheme(layerId)`

6. `GeoLeaf.Themes.getAvailableThemes(layerId, options?)`

7. `GeoLeaf.Themes.initializeLayerTheme(layerId, options?)`

8. `GeoLeaf.Themes.toggleTheme(layerId)`

9. `GeoLeaf.Themes.loadTheme(themeOrId)`

10. `GeoLeaf.Themes.clearRememberedThemes()`

11. `GeoLeaf.Themes.invalidateCache()`

12. Persistance

13. Format `themes/index.json`

14. Intégration dans un profil JSON

15. Exemples d'utilisation

Sélecteur de thème UI

Bouton toggle

Thème selon la préférence système

16. Architecture interne

17. Références