Carte Facile

Une bibliothèque simple pour gérer les styles de cartes, surcouches et composants cartographiques.

La documentation officielle est disponible sur le site dédié : Documentation de Carte facile

Table des matières

• Carte Facile
  • Table des matières
  • Installation
  • Prérequis
  • Utilisation
    • Styles disponibles
    • Exemples d'utilisation
      • Ajouter une carte avec MapLibre
    • Ajouter une surcouche (overlay)
    • Ajouter le sélecteur de carte et surcouches
    • Gérer la visibilité des couches
  • Contribution
  • Développement
    • Mise en place de l'environnement de développement
    • Tests
    • Publication
    • Standards de code

Installation

npm install carte-facile

Prérequis

En plus de carte-facile, vous devez installer la bibliothèque de cartographie maplibre-gl.

# Pour MapLibre
npm install maplibre-gl

Utilisation

Styles disponibles

La bibliothèque fournit différents styles de cartes :

• simple : Style classique
• desaturated : Style désaturé
• aerial : Photographie aérienne

Pour récupérer une carte :

mapStyle.simple

Exemples d'utilisation

Créer un conteneur html pour la carte:

<!-- HTML nécessaire -->
<div id="map" style="height: 500px; width: 100%;"></div>

Ajouter une carte avec MapLibre

import { mapStyles } from 'carte-facile';
import maplibregl from 'maplibre-gl';
import 'carte-facile/carte-facile.css'; // Import du CSS pour les composants

const map = new maplibregl.Map({
  container: 'map',
  style: mapStyles.simple,
});

Ajouter une surcouche (overlay)

Vous pouvez ajouter une ou plusieurs surcouches (par exemple le cadastre ou les limites administratives) à votre carte :

import { addOverlay, Overlay } from 'carte-facile';

// Ajouter une seule surcouche
addOverlay(map, Overlay.administrativeBoundaries);

// Ou ajouter plusieurs surcouches en même temps
addOverlay(map, [Overlay.administrativeBoundaries, Overlay.cadastre]);

Le style de la surcouche s'adapte automatiquement au fond de carte utilisé.

Pour retirer une ou plusieurs surcouches :

import { removeOverlay } from 'carte-facile';

// Retirer une seule surcouche
removeOverlay(map, Overlay.administrativeBoundaries);

// Ou retirer plusieurs surcouches en même temps
removeOverlay(map, [Overlay.administrativeBoundaries, Overlay.cadastre]);

Pour obtenir la liste des surcouches disponibles :

import { Overlay } from 'carte-facile';

// Liste des surcouches disponibles
console.log(Overlay);

Ou utilisez l'autocomplétion de votre IDE avec Overlay..

Ajouter le sélecteur de carte et surcouches

Ce composant vous permet d'avoir immédiatement accès aux cartes et surcouches disponibles à travers une interface pour votre carte.

Pour ajouter le sélecteur de carte par défaut :

import { MapSelectorControl } from 'carte-facile';

map.addControl(new MapSelectorControl);

Pour préciser les cartes et surcouches que vous voulez afficher dans le composant, et préciser sa position :

import { MapSelectorControl } from 'carte-facile';

map.addControl(new MapSelectorControl({
  styles: ['simple', 'aerial'],
  overlays: ['administrativeBoundaries', 'cadastre']
}), 'bottom-left');

Gérer la visibilité des couches

Vous pouvez afficher ou masquer des groupes de couches :

import { showLayer, hideLayer, LayerGroup } from 'carte-facile';

// Afficher un seul groupe de couches
showLayer(map, LayerGroup.buildings);

// Ou afficher plusieurs groupes de couches
showLayer(map, [LayerGroup.buildings, LayerGroup.streets]);

// Masquer un seul groupe de couches
hideLayer(map, LayerGroup.streets);

// Ou masquer plusieurs groupes de couches
hideLayer(map, [LayerGroup.buildings, LayerGroup.streets]);

Pour obtenir la liste des groupes de couches disponibles :

import { LayerGroup } from 'carte-facile';

// Liste des groupes de couches disponibles
console.log(LayerGroup);

Ou utilisez l'autocomplétion de votre IDE avec LayerGroup..

Contribution

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou un pull request.

Développement

Mise en place de l'environnement de développement

1. Cloner le dépôt :

git clone https://github.com/fab-geocommuns/carte-facile.git
cd carte-facile

2. Installer les dépendances :

npm install

3. Lancer les tests :

npm run test

4. Compiler le projet :

npm run build

Note: Si vous modifiez le code source, n'oubliez pas de relancer npm run build pour mettre à jour le dossier dist. Vous pouvez aussi utiliser npm run dev pour un mode développement avec recompilation automatique.

Tests

Les tests sont écrits avec Jest. Pour ajouter de nouveaux tests :

1. Créer un fichier de test dans le dossier tests
2. Utiliser la convention de nommage *.test.ts
3. Lancer les tests avec npm run test

Publication

Pour publier une nouvelle version du package :

1. Mettre à jour la version sur la branche development :

npm version patch  # pour un bugfix (0.0.X)
# ou
npm version minor  # pour une nouvelle fonctionnalité (0.X.0)
# ou
npm version major  # pour un changement majeur (X.0.0)

2. Pousser les changements et le tag sur development :

git push origin development
git push origin --tags

3. Créer une Pull Request pour fusionner development dans main :

# Aller sur https://github.com/fab-geocommuns/carte-facile/pulls
# Cliquer sur "New pull request"
# Sélectionner development comme branche source et main comme branche cible
# Attendre que les checks passent et merger la PR

Note: Une fois la PR mergée sur main, le workflow GitHub Actions va automatiquement :

• Exécuter les tests
• Publier le package sur npm
• Créer une release sur GitHub

Note: Après chaque publication, il est recommandé de mettre à jour la branche development avec les changements de main :

git checkout development
git merge origin/main
git push origin development

Standards de code

• Utiliser TypeScript pour tout nouveau code.
• Documenter les nouvelles fonctionnalités dans la documentation de la librairie : Documentation de Carte facile.
• Ajouter des tests pour les nouvelles fonctionnalités.