@geoleaf/core

v2.1.8

Published

14 days ago

GeoLeaf — Modular JavaScript mapping library built on MapLibre GL JS. v2.0: WebGL rendering, native vector tiles, GPU clustering. Features: Security (XSS protection), Performance (WebGL pipeline), Typed Errors, Validators, and comprehensive TypeScript sup

GeoLeaf JS

Product Version: GeoLeaf Platform V2 Version: 2.0.0 License: MIT Description: Modern JavaScript mapping library built on MapLibre GL JS with advanced features for interactive web mapping applications.

Versioning policy
Product label: GeoLeaf Platform V2
Technical SemVer (packages/releases): 2.0.x
Details: docs/VERSIONING_POLICY.md
Release history: docs/CHANGELOG.md

Licence scope (important)
GeoLeaf Core (geoleaf, ce dépôt) : licence MIT (usage, modification, redistribution autorisés selon MIT)
Plugins premium (@geoleaf-plugins/storage, @geoleaf-plugins/addpoi) : licence commerciale distincte
Les plugins premium ne sont pas couverts par la licence MIT du core

🚀 Quick Start

Get started with GeoLeaf in less than 5 minutes:

Installation

Via NPM (recommended — ESM):

npm install @geoleaf/core maplibre-gl

// ES Modules (recommended) — full bundle
import { Core, POI, Filters } from "@geoleaf/core";
import "@geoleaf/core/dist/geoleaf.min.css";

Core.init({
    map: { target: "map", center: [46.5, 2.5], zoom: 6 },
});

ESM granulaire (tree-shaking) — Vite / Webpack :

Avec un bundler moderne, privilégiez le point d’entrée ESM pour ne charger que les modules utilisés. Les exports nommés permettent un tree-shaking optimal.

// Import ciblé — seuls Core, POI, Table et Log sont inclus dans le bundle final
import { Core, POI, Table, Log } from "@geoleaf/core";
import "@geoleaf/core/dist/geoleaf.min.css";

Core.init({ map: { target: "map", center: [46.5, 2.5], zoom: 6 } });
// POI.add(...), Table.init(...), etc.

Exports principaux disponibles : Core, GeoLeafAPI, UI, POI, Route, Table, Legend, LayerManager, Filters, Baselayers, Helpers, Validators, Log, Errors, CONSTANTS, Config, plus les sous-modules API (APIController, BootInfo, …). Voir la documentation API générée (TypeDoc) pour la liste complète.

Génération de la doc API : npm run docs:api (génère docs/api/).

Via CDN (ESM):

<!-- MapLibre GL JS (required dependency) -->
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/maplibre-gl.css" />
<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>

<!-- GeoLeaf -->
<link rel="stylesheet" href="https://unpkg.com/@geoleaf/[email protected]/dist/geoleaf.min.css" />
<script type="module" src="https://unpkg.com/@geoleaf/[email protected]/dist/geoleaf.esm.js"></script>

Your First Map

<!DOCTYPE html>
<html>
    <head>
        <link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/maplibre-gl.css" />
        <link rel="stylesheet" href="https://unpkg.com/@geoleaf/[email protected]/dist/geoleaf.min.css" />
        <style>
            #map {
                height: 600px;
            }
        </style>
    </head>
    <body>
        <div id="map"></div>

        <script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
        <script
            type="module"
            src="https://unpkg.com/@geoleaf/[email protected]/dist/geoleaf.esm.js"
        ></script>
        <script type="module">
            // Initialize map
            const map = GeoLeaf.init({
                map: {
                    target: "map",
                    center: [46.5, 2.5],
                    zoom: 6,
                },
            });

            // Add a POI marker
            GeoLeaf.POI.add({
                id: "poi-1",
                latlng: [48.8566, 2.3522],
                title: "Paris",
                category: "city",
            });
        </script>
    </body>
</html>

❓ Why GeoLeaf?

GeoLeaf vs Popular Alternatives

| Feature | Leaflet | Google Maps | Mapbox GL | GeoLeaf | | ----------------------------- | ------------- | -------------- | -------------- | ------------------- | | Security (XSS Protection) | ⚠️ Basic | ✅ Built-in | ⚠️ Basic | ✅ Advanced | | GeoJSON Multi-Style | ⚠️ Limited | ✅ Full | ✅ Full | ✅ Full | | Offline Support | ❌ No | ❌ No | ⚠️ Partial | ✅ Full (IndexedDB) | | POI Clustering | ⚠️ Via Plugin | ✅ Built-in | ✅ Built-in | ✅ Built-in | | Label System | ❌ No | ✅ Built-in | ✅ Built-in | ✅ Built-in | | Business Profiles | ❌ No | ❌ No | ❌ No | ✅ Multi-profile | | Open Source | ✅ BSD-2 | ❌ Proprietary | ✅ Proprietary | ✅ MIT | | Free for Production | ✅ Yes | ⚠️ Paid API | ⚠️ Paid | ✅ Yes | | Offline-First Ready | ❌ No | ❌ No | ❌ No | ✅ Yes | | TypeScript Support | ⚠️ Community | ✅ Official | ✅ Official | ✅ Full |

Best For

Choose GeoLeaf if you need:

✅ Security-first mapping (XSS protection built-in)
✅ Offline-first applications (mobile, unreliable networks)
✅ Business context switching (profiles)
✅ Complex styling rules per layer
✅ Open source with MIT licensing
✅ Professional mapping without vendor lock-in

Use Leaflet/MapLibre directly if:

Lightweight, no-frills mapping
Maximum plugin ecosystem
Minimal dependencies

Use Google Maps if:

Enterprise support needed
Extensive street view/Street Data
Google services integration essential

✨ Features

🗺️ Multi-Profile System

Switch between different business contexts (Tourism, Custom…) with dedicated configurations, taxonomies, and UI presets.

📍 Advanced POI Management

Category-based organization with icons
Custom sidepanel layouts (JSON-driven)
Search, filters, and clustering
Add/Edit/Delete with validation

🎨 Dynamic Theming

Light/Dark mode with system detection
Primary & secondary theme switchers
Layer visibility presets per theme
CSS custom properties integration

📊 GeoJSON Layers

Load multiple GeoJSON layers from configuration
Style system with multiple presets per layer
Labels with scale-based visibility
Interactive shapes with tooltips/popups

🔄 Offline Cache

(via plugin premium Storage)

IndexedDB storage for profiles and data
Basemap tile caching for offline usage
Automatic cache management
Progress tracking and notifications

🏷️ Integrated Labels System

Style-based label configuration
Scale-dependent visibility
Dynamic field rendering
Toggle controls in layer manager

🎯 Smart Filters

Category/subcategory filtering
Tag-based filtering
Full-text search
Proximity/radius filtering
Result counters

📋 Data Table

Tabular view of layer features
Sortable columns
Export to CSV/Excel
Synchronized with map selection

🔒 Security

XSS protection via Content Security Policy
Input sanitization
Safe HTML rendering
CORS headers support

📖 Documentation

📚 Complete Documentation Index - Browse all documentation organized by category

Getting Started

Getting Started Guide - Your first map in 5 minutes
User Guide - Complete user documentation (10 sections)
Configuration Guide - JSON configuration reference (9 types)
Profiles Guide - Create custom business profiles (1,200+ lines)

Development

API Reference - Complete API documentation (80+ methods)
API Reference (TypeDoc) - Documentation API générée depuis les types TypeScript (npm run docs:api)
Contributing Guide - Contribution guidelines and standards
Architecture Guide - System architecture and design patterns

Guides & References

Profiles Guide - Create custom business profiles (1,200+ lines)
JSON Schemas - Validation schemas for profiles
Cookbook - Practical recipes and solutions
FAQ - Frequently asked questions

Module Documentation

Baselayers - Basemap management
Configuration - Profile loading
POI Management - Points of Interest
GeoJSON Layers - Vector layers
Labels System - Map labels
Themes - Theme system
UI Components - User interface
View all modules →

⚡ Performance Metrics

GeoLeaf is optimized for production performance:

Bundle Size: ESM entry ~1.73 KB gz (entry seule + chunks lazy on demand). Bundle complet : ~128 KB minifié. Lite (dist/esm-lite/) : ~84 KB minifié, sans table/labels/route.
Tree-Shaking: 75.7% code reduction in production build
Initialization: < 100ms on modern devices
Runtime Performance: Smooth interactions with 1000+ POI markers
Offline Support: Full app functionality without network
Browser Support: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+ (ES2020+)

Code Quality

Test Coverage: ~82% Vitest + Playwright e2e
Security: XSS protection, input sanitization, CSP headers
TypeScript: Full type definitions (772 lines)
ESLint: 0 warnings in production code

🏗️ Architecture

GeoLeaf is built with a modular architecture (v2.0.0) consisting of 200+ modules organized into functional domains:

geoleaf-js/
├── src/modules/          # Core modules
│   ├── core/               # Map initialization
│   ├── config/             # Profile loading
│   ├── poi/                # POI management
│   ├── geojson/            # GeoJSON layers
│   ├── labels/             # Label system
│   ├── themes/             # Theme system
│   ├── ui/                 # UI components
│   ├── storage/            # Offline storage
│   ├── filters/            # Filter engine
│   ├── security/           # XSS protection
│   └── utils/              # Utilities
├── profiles/               # Business profiles
│   └── tourism/            # Tourism profile
└── docs/                   # Documentation

See Architecture Guide for detailed architecture documentation.

🎯 Use Cases

Tourism & Heritage

Display points of interest, tourist routes, climate data, and protected areas with category-based filtering and rich popups.

Custom Applications

Build your own business-specific mapping application using the flexible profile system.

🔧 Configuration

GeoLeaf uses a profile-based configuration system with JSON files:

Main Configuration (`geoleaf.config.json`)

{
    "debug": false,
    "data": {
        "activeProfile": "tourism",
        "profilesBasePath": "./profiles"
    }
}

Profile Configuration (`profiles/tourism/profile.json`)

{
  "id": "tourism",
  "label": "Tourism",
  "version": "1.0.0",
  "ui": {
    "showLegend": true,
    "showLayerManager": true,
    "showFilterPanel": true
  },
  "basemaps": { ... },
  "layers": { ... },
  "taxonomy": { ... },
  "themes": { ... }
}

See Configuration Guide for complete reference.

🛠️ Development

Prerequisites

Node.js 18+ and npm
Modern browser with ES6+ support

Setup

# Clone repository
git clone https://github.com/mattpottier-ship-it/GeoLeaf-Core.git
cd geoleaf-js

# Install dependencies
npm install

# Start development server
npm start

# Run tests
npm test

# Build for production
npm run build

Project Scripts

npm start - Start development server
npm test - Run test suite (Vitest)
npm run test:e2e - Run E2E tests (Playwright)
npm run build - Build production bundle
npm run lint - Lint code
npm run coverage - Generate coverage report

See Getting Started Guide for detailed setup instructions.

📦 Distribution

NPM Package

npm install @geoleaf/core maplibre-gl

import { Core } from "@geoleaf/core";
import "@geoleaf/core/dist/geoleaf.min.css";

CDN (jsDelivr)

<link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@geoleaf/[email protected]/dist/geoleaf.min.css"
/>
<script
    type="module"
    src="https://cdn.jsdelivr.net/npm/@geoleaf/[email protected]/dist/geoleaf.esm.js"
></script>

Build from Source

See Distribution Guide for packaging instructions.

🧪 Testing

Unit tests: Vitest 3 (150+ tests, ESM, Istanbul coverage)
Integration tests: Vitest with mock DOM
E2E tests: Playwright
Coverage: 75%+ target (actual ~82%)

npm test                    # Run all tests
npm run test:watch          # Watch mode
npm run test:coverage       # Generate coverage report
npm run test:e2e            # E2E tests

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for:

Code standards and conventions
Branch naming and PR process
Testing requirements
Documentation guidelines

📄 License

MIT License - see LICENCE file for details.

🙏 Credits

Built With

MapLibre GL JS - Interactive WebGL maps
Turf.js - Geospatial analysis
Modern JavaScript (ES6+)

Maintainers

Lead Developer: Mattieu Pottier

📞 Support

Documentation: docs/
Issues: GitHub Issues
Discussions: GitHub Discussions

📄 License & Legal

License: MIT (Open Source)

GeoLeaf Core is released under the MIT License - free for commercial and personal use.

See LICENSE for the complete license text
See NOTICE.md for third-party attributions

Using GeoLeaf

You can: Use in commercial projects, modify and redistribute, use for private projects, include in open source projects
You must: Include license and copyright notice, document changes
You cannot: Hold the author liable, use the author's name for endorsement

🗺️ Roadmap

See CHANGELOG.md for version history.

License

For more information about licensing and the distinction between GeoLeaf Core (open source) and premium plugins, see NOTICE.md.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

GeoLeaf JS

🚀 Quick Start

Installation

Your First Map

❓ Why GeoLeaf?

GeoLeaf vs Popular Alternatives

Best For

✨ Features

🗺️ Multi-Profile System

📍 Advanced POI Management

🎨 Dynamic Theming

📊 GeoJSON Layers

🔄 Offline Cache

🏷️ Integrated Labels System

🎯 Smart Filters

📋 Data Table

🔒 Security

📖 Documentation

Getting Started

Development

Guides & References

Module Documentation

⚡ Performance Metrics

Code Quality

🏗️ Architecture

🎯 Use Cases

Tourism & Heritage

Custom Applications

🔧 Configuration

Main Configuration (geoleaf.config.json)

Profile Configuration (profiles/tourism/profile.json)

🛠️ Development

Prerequisites

Setup

Project Scripts

📦 Distribution

NPM Package

CDN (jsDelivr)

Build from Source

🧪 Testing

🤝 Contributing

📄 License

🙏 Credits

Built With

Maintainers

📞 Support

📄 License & Legal

Using GeoLeaf

🗺️ Roadmap

License

Main Configuration (`geoleaf.config.json`)

Profile Configuration (`profiles/tourism/profile.json`)