Improve documentation / Prepare leaflet.markercluster support (#25)

* First MarkerCluster idea

* Init some documentation for markercluster

* Update configKey / Polish doc / Polish module API

* Fix playground baseURL

* Improve documentation

* Add cover image

* Add Nuxt UI to improve playground

* Make markercluster client-side only

* Make markercluster more usable

* Update comment

* Add custom marker icon example

* Improve documentation

* Improve documentation

* Hide doc page temporarily for main merge

Author: Gugustinette

.nuxtrc

@@ -1,2 +1,2 @@
-imports.autoImport=false
+imports.autoImport=true
 typescript.includeWorkspace=true

README.md

@@ -1,3 +1,5 @@
+[![@nuxtjs/leaflet](./docs/public/cover.png)](https://leaflet.nuxtjs.org)
+
 # Nuxt Leaflet
 
 [![npm version][npm-version-src]][npm-version-href]

docs/.vitepress/config.ts

@@ -26,12 +26,13 @@ export default defineConfig({
         text: 'Guide',
         items: [
           { text: 'Using L', link: '/guide/using-l' },
-          { text: 'Accessing Map Instance', link: '/guide/accessing-map-instance' },
-          { text: 'Leaflet Draw (Experimental)', link: '/guide/leaflet-draw' }
+          { text: 'Accessing a map instance', link: '/guide/accessing-map-instance' }
+          // { text: 'Leaflet.markercluster', link: '/guide/marker-cluster' }
         ]
       },
       {
         text: 'Components',
+        collapsed: true,
         items: [
           { text: 'Introduction', link: '/components/introduction' },
           { text: 'LCircle', link: '/components/l-circle' },
@@ -57,7 +58,13 @@ export default defineConfig({
           { text: 'LTooltip', link: '/components/l-tooltip' },
           { text: 'LWmsTileLayer', link: '/components/l-wms-tile-layer' },
         ]
-      }
+      },
+      {
+        text: 'About',
+        items: [
+          { text: 'Q&A', link: '/about/q&a' },
+        ]
+      },
     ],
 
     socialLinks: [

docs/about/q&a.md

@@ -0,0 +1,37 @@
+# Q&A
+
+## Does the module support Nuxt 2 ?
+
+No, the module at least requires Nuxt 3.
+
+For Nuxt 2, you can use [this module](https://www.npmjs.com/package/nuxt-leaflet).
+
+## How does Leaflet compare to Mapbox ?
+
+[Mapbox](https://www.mapbox.com/) is a mapping platform that provides a suite of tools to create maps and location-based services. It includes similar features to Leaflet, but with paid plans for more advanced services.
+
+Think of Leaflet as an open-source technology, while Mapbox is a complete collection of advanced tools and services.
+
+Both are great choices, it depends on your needs and budget. To be fair, [the creator of Leaflet](https://github.com/mourner) also works at Mapbox.
+
+If you want to use Mapbox with Nuxt, you can use the [Nuxt Mapbox](https://nuxt.com/modules/nuxt-mapbox) module.
+
+## How does Leaflet compare to MapLibre ?
+
+[MapLibre](https://maplibre.org/) is a fork of the original Mapbox GL JS library. It has very similar features to Leaflet, and is also free and open-source.
+
+:::tip Quote from [MapLibre's Github repository](https://github.com/maplibre/maplibre-gl-js)
+MapLibre originated as an open-source fork of mapbox-gl-js, before their switch to a non-OSS license in December 2020.
+
+The library's initial versions (1.x) were intended to be a drop-in replacement for the Mapbox’s OSS version (1.x) with additional functionality, but have evolved a lot since then.
+:::
+
+If you want to use MapLibre with Nuxt, you can use the [Vue MapLibre](https://indoorequal.github.io/vue-maplibre-gl/) module which has some documentation for Nuxt.
+
+We are also working on a dedicated Nuxt module for MapLibre.
+
+## Will Leaflet.draw be supported in the future ?
+
+[Leaflet.draw](https://leaflet.github.io/Leaflet.draw/docs/leaflet-draw-latest.html) was created to provide a simple way to draw shapes on a map made with Leaflet.
+
+However, as the project is not maintained anymore (last update in 2018, see [Github repository](https://github.com/Leaflet/Leaflet.draw)), we choose not to include its support in the module.

docs/guide/accessing-map-instance.md

@@ -1,4 +1,4 @@
-# Accessing a Map Instance
+# Accessing a map instance
 
 The guide explains how to access a Leaflet map instance from a Vue component, as featured in the [original vue-leaflet library](https://github.com/vue-leaflet/vue-leaflet/blob/master/docs/faq/index.md#how-can-i-access-the-leaflet-map-object).
 
@@ -12,7 +12,7 @@ The guide explains how to access a Leaflet map instance from a Vue component, as
       :zoom="6"
       :max-zoom="18"
       :center="[47.21322, -1.559482]"
-      @ready="mapInitialized"
+      @ready="onMapReady"
     >
       <LTileLayer
         url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
@@ -31,7 +31,7 @@ const map = ref(null)
 </script>
 ```
 
-- Create a `mapInitialized` method that will be called when the map is ready.
+- Create a `onMapReady` method that will be called when the map is ready.
 
 You can now access the Leaflet map instance using `map.value.leafletObject`.
 
@@ -43,7 +43,7 @@ You can now access the Leaflet map instance using `map.value.leafletObject`.
       :zoom="6"
       :max-zoom="18"
       :center="[47.21322, -1.559482]"
-      @ready="mapInitialized"
+      @ready="onMapReady"
     >
       <LTileLayer
         url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
@@ -61,7 +61,7 @@ import { ref } from 'vue'
 const map = ref(null)
 
 // When the map is ready
-const mapInitialized = () => {
+const onMapReady = () => {
     // Access the Leaflet map instance
     console.log(map.value.leafletObject)
 }

docs/guide/leaflet-draw.md

@@ -0,0 +1,111 @@
+# Using Leaflet.markercluster
+
+The guide explains how to use the [Leaflet.markercluster](https://github.com/Leaflet/Leaflet.markercluster) plugin.
+A dedicated composable is available to help you use this plugin.
+
+Options for the markers are the same as the ones available in the [Leaflet documentation](https://leafletjs.com/reference.html#marker).
+
+::: warning
+This is only possible in a client-side environment. You should either :
+- Use a [Client-Only Page](https://nuxt.com/docs/guide/directory-structure/pages#client-only-pages).
+- Wrap your component inside the [ClientOnly](https://nuxt.com/docs/api/components/client-only) component.
+- Set your [rendering strategy](https://nuxt.com/docs/guide/concepts/rendering#client-side-rendering) to `ssr: false` for the appropriate route.
+:::
+
+## Installation
+
+- First install markercluster
+
+```bash
+npm install leaflet.markercluster
+```
+
+- Update your Nuxt config to activate the plugin
+
+```ts{3-5}
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/leaflet'],
+  leaflet: {
+    markerCluster: true
+  }
+})
+```
+
+- Use the `useMarkerCluster` composable in your component
+
+:::warning
+It is very important to keep the manual import of Leaflet and the `:use-global-leaflet="true"` as leaflet.markercluster requires Leaflet to be loaded globally.
+:::
+
+```vue{9,23,28-61,65-68}
+<template>
+  <div style="height:100vh; width:100vw">
+    <h1>Marker Cluster</h1>
+    <LMap
+      ref="map"
+      :zoom="6"
+      :max-zoom="18"
+      :center="[47.21322, -1.559482]"
+      :use-global-leaflet="true"
+      @ready="onMapReady"
+    >
+      <LTileLayer
+        url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
+        attribution="&amp;copy; <a href=&quot;https://www.openstreetmap.org/&quot;>OpenStreetMap</a> contributors"
+        layer-type="base"
+        name="OpenStreetMap"
+      />
+    </LMap>
+  </div>
+</template>
+
+<script setup lang="ts">
+import L from 'leaflet'
+import { ref } from 'vue';
+
+const map = ref(null) as any;
+
+// Create locations data (20 locations around Nantes)
+const locations = [
+  { name: 'Nantes', lat: 47.218371, lng: -1.553621, options: {
+    // Standard Leaflet Marker options
+    draggable: true,
+    icon: L.icon({
+      iconUrl: '/my-icon.png',
+      iconSize: [30, 30],
+    })
+  } },
+  {
+    // name is optional (no tooltip will be displayed if not provided)
+    /* name: 'Saint-Nazaire', */
+    lat: 47.273018, lng: -2.213733 
+  },
+  { name: 'La Baule', lat: 47.286835, lng: -2.393108 },
+  { name: 'Pornic', lat: 47.112, lng: -2.102 },
+  { name: 'Guérande', lat: 47.328, lng: -2.429 },
+  { name: 'Clisson', lat: 47.087, lng: -1.276 },
+  { name: 'Ancenis', lat: 47.366, lng: -1.176 },
+  { name: 'Châteaubriant', lat: 47.716, lng: -1.376 },
+  { name: 'Redon', lat: 47.652, lng: -2.084 },
+  { name: 'Pontchâteau', lat: 47.433, lng: -2.117 },
+  { name: 'Savenay', lat: 47.327, lng: -1.952 },
+  { name: 'Rezé', lat: 47.183, lng: -1.55 },
+  { name: 'Vertou', lat: 47.166, lng: -1.466 },
+  { name: 'Carquefou', lat: 47.283, lng: -1.5 },
+  { name: 'Orvault', lat: 47.283, lng: -1.633 },
+  { name: 'Saint-Herblain', lat: 47.216, lng: -1.65 },
+  { name: 'Sainte-Luce-sur-Loire', lat: 47.233, lng: -1.483 },
+  { name: 'Bouguenais', lat: 47.183, lng: -1.583 },
+  { name: 'Saint-Sébastien-sur-Loire', lat: 47.183, lng: -1.483 },
+  { name: 'Basse-Goulaine', lat: 47.2, lng: -1.483 }
+];
+
+// When the map is ready
+const onMapReady = () => {
+  useMarkerCluster({
+    leafletObject: map.value.leafletObject,
+    markers: locations
+  });
+}
+</script>
+```

docs/guide/marker-cluster.md

@@ -2,10 +2,13 @@
 
 You might want to access the Leaflet global variable in your Vue component. This can be useful if you want to use a Leaflet plugin that is not available as a Vue component.
 
-You can still import the `L` global variable from the `leaflet` package and use it in your Vue component. Here is an example of how you can access the `L` global variable in a Vue component.
+You can still import the `L` global variable from the `leaflet` package and use it in your Vue component. Here is an example :
 
 ::: warning
-This is only possible in a client-side environment. You should use the `client-only` component to ensure that the code is only executed on the client side or set your map route to `ssr: false`.
+This is only possible in a client-side environment. You should either :
+- Use a [Client-Only Page](https://nuxt.com/docs/guide/directory-structure/pages#client-only-pages).
+- Wrap your component inside the [ClientOnly](https://nuxt.com/docs/api/components/client-only) component.
+- Set your [rendering strategy](https://nuxt.com/docs/guide/concepts/rendering#client-side-rendering) to `ssr: false` for the appropriate route.
 :::
 
 ```vue{6,18,21-23}