chore: improve demo and README

teritorio · Aug 29, 2024 · 496b1fb · 496b1fb
1 parent f5299b6
commit 496b1fb
Show file tree

Hide file tree

Showing 6 changed files with 183 additions and 108 deletions.
diff --git a/README.md b/README.md
@@ -1,10 +1,14 @@
 # MapLibre GL Teritorio Cluster
 
-Render native MapLibre GL JS clusters as HTML marker. Render:
+Render native MapLibre GL JS clusters as HTML marker.
+
+Render:
 - HTML cluster
-- HTML group marked small cluster or last zoom level
+- HTML group marked as small cluster or last zoom level
+- Pin Marker on feature click
 
-Allow to see and interact with all map markers, even when superposed. Allow to see and interact with small cluster without the need to need to zoom or uncluster.
+Allow visualization and interaction with all markers, even when superposed.
+Can display and interact with small cluster without the need to zoom or TeritorioCluster.
 
 See the [Demo page](https://teritorio.github.io/maplibre-gl-teritorio-cluster/index.html).
 
@@ -14,47 +18,89 @@ See the [Demo page](https://teritorio.github.io/maplibre-gl-teritorio-cluster/in
 
 Add to you project (or use CDN).
 ```bash
-npm add maplibre-gl-teritorio-cluster
+yarn add maplibre-gl-teritorio-cluster
 ```
 
 > [!WARNING]
-> Set your GeoJson source with `clusterMaxZoom: 22` in order to let the plugin handle cluster/individual marker rendering.
+> Set your GeoJson source with `clusterMaxZoom: 22` in order to let the plugin handle cluster/individual marker rendering across all zoom level
 
 ```js
 import { Map } from "maplibre-gl"
-import UnCluster from 'maplibre-gl-teritorio-cluster'
+import { TeritorioCluster } from 'maplibre-gl-teritorio-cluster'
 
 const map = new Map({
-container: "map_dom_el_id",
-zoom: 0.3,
-center: [0, 20],
-style: 'https://api.maptiler.com/maps/openstreetmap/style.json?key=your_api_key'
+  container: "map_dom_el_id",
+  style: './style.json'
 });
 
-// Set `clusterMaxZoom` to force display unclustered points on a certain zoom level
-const clusterMaxZoom = 17
+map.on('load', () => {
+  const TeritorioCluster = new TeritorioCluster(map, 'your_source_name', options)
 
-const unCluster = new UnCluster(map, 'your_cluster_source', { clusterMaxZoom }, createClusterHTML, createSingleMarkerHTML)
+  // Get feature click event
+  TeritorioCluster.addEventListener('teritorioClick', (e) => {
+    console.log(e)
+  })
 
-map.on('data', (e) => {
-if (e.sourceId !== 'your_cluster_source' || !e.isSourceLoaded) return;
+  // Render feature on map data updates
+  map.on('data', (e) => {
+    if (e.sourceId !== 'your_source_name' || !e.isSourceLoaded)
+      return;
 
-map.on('move', unCluster.render);
-map.on('moveend', unCluster.render);
-unCluster.render()
-});
+    map.on('move', TeritorioCluster.render);
+    map.on('moveend', TeritorioCluster.render);
+    TeritorioCluster.render()
+  });
+})
 
 // Create whatever HTML element you want as Cluster
-const displayCluster = (): HTMLElement => {}
+const clusterMode = (element: HTMLDivElement, props: MapGeoJSONFeature['properties'], size?: number): void => {}
+
 // Create whatever HTML element you want as individual Marker
-const displayMarker = (): HTMLElement => {}
+const displayMarker = (element: HTMLDivElement, feature: MapGeoJSONFeature, size?: number): void => {}
+
+// Create whatever HTML element you want as Pin Marker
+const displayPinMarker = (coords: LngLatLike, offset: Point): Marker => {}
+```
+
+## API
+
+- [TeritorioCluster](#teritoriocluster)
+  - [Parameters](#parameters)
+  - [addEventListener](#addeventlistener)
+
+### TeritorioCluster
+
+Create a new Maplibre GL JS plugin for feature (cluster / individual marker) rendering
+
+#### Parameters
+
+  - `map`: [`maplibregl.Map`](https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/) The Map object represents the map on your page
+  - `source`: `string` The ID of the vector tile or GeoJSON source to query
+  - `options`: `object` Options to configure the plugin
+    - `options.clusterMaxZoom`: `number` The cluster's max zoom (optional, default `17`)
+    - `options.clusterMode`: `(element: HTMLDivElement, props: MapGeoJSONFeature['properties'], size?: number): void` Custom function for cluster rendering (optional)
+    - `options.clusterSize`: `number` Set the size for default cluster rendering mode (optional, default `38`)
+    - `options.markerMode`: `(element: HTMLDivElement, feature: MapGeoJSONFeature, size?: number): void` Custom function for individual marker rendering (optional)
+    - `options.markerSize`: `number` Set the size for default individual marker rendering mode (optional, default `24`)
+    - `options.teritorioClusterMode`: `'circle'` TeritorioCluster rendering preset (optional)
+    - `options.pinMarkerMode`: `(coords: LngLatLike, offset: Point): Marker` Custom function for pin marker rendering (optional)
+
+#### addEventListener
+
+Listen to feature click and returns it for external control.
+
+```js
+TeritorioCluster.addEventListener('teritorioClick', (e) => {
+  console.log(e.detail.selectedFeature)
+})
+
 ```
 
 ## Dev
 
-Install Maplibre GL JS as peer dependency (be seriously, you should already have it)
+Install Maplibre GL JS as peer dependency
 ```bash
-npm install maplibre-gl
+yarn add maplibre-gl
 ```
 
 Install dependencies

diff --git a/index.html b/index.html
@@ -5,15 +5,16 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <meta property="og:description" content="Show all cluster's points in one HTML element" />
-  <title>Maplibre GL - Uncluster</title>
+  <title>MapLibre GL Teritorio Cluster</title>
 </head>
 
 <body style="margin: 0; padding: 0;">
   <div id="map" style="height: 100vh;"></div>
+
   <script type="module">
     import 'maplibre-gl/dist/maplibre-gl.css'
     import { Map, NavigationControl, Marker } from "maplibre-gl"
-    import { UnCluster } from './src'
+    import { TeritorioCluster } from './src'
     import { buildCss } from './src/utils/helpers'
 
     // filters for classifying earthquakes into five categories based on magnitude
@@ -29,25 +30,13 @@
     const map = new Map({
       hash: true,
       container: "map",
-      zoom: 0.3,
-      center: [0, 20],
       style: 'https://api.maptiler.com/maps/openstreetmap/style.json?key=GIAfARJO9HDgKceZRlGv'
     });
 
     map.addControl(new NavigationControl());
 
     map.on('load', async () => {
       let geojson = await fetch('https://maplibre.org/maplibre-gl-js/docs/assets/earthquakes.geojson', { method: 'GET' }).then(res => res.json())
-      // const superposedGeojson = {
-      //   ...geojson,
-      //   features: geojson.features.map((f,index) => {
-      //     if (index < 20)
-      //       f.geometry.coordinates = [0,0]
-
-      //     return f
-      //   })
-      // }
-
 
       // add a clustered GeoJSON source for a sample set of earthquakes
       map.addSource('earthquakes', {
@@ -114,38 +103,44 @@
         }
       });
 
-      const unCluster = new UnCluster(
+      const teritorioCluster = new TeritorioCluster(
         map,
         'earthquakes',
         {
           clusterMode: displayCluster,
           markerMode: displayMarker,
-          unClusterMode: 'circle',
+          teritorioClusterMode: 'circle',
           pinMarkerMode: displayPinMarker
         },
       )
 
-      // Get selected marker ID
-      // Get Pin Marker instance
-      unCluster.addEventListener('teritorioClick', (e) => {
-        console.log(e)
+      teritorioCluster.render()
+
+      // Get feature click event
+      teritorioCluster.addEventListener('teritorioClick', (e) => {
+        console.log(e.detail.selectedFeature)
       })
 
       // after the GeoJSON data is loaded, update markers on the screen and do so on every map move/moveend
       map.on('data', (e) => {
-        if (e.sourceId !== 'earthquakes' || !e.isSourceLoaded) return;
+        if (e.sourceId !== 'earthquakes' || !e.isSourceLoaded)
+          return
+
+        map.on('move', teritorioCluster.render);
+        map.on('moveend', teritorioCluster.render);
 
-        map.on('move', unCluster.render);
-        map.on('moveend', unCluster.render);
-        unCluster.render()
+        teritorioCluster.render()
       });
     })
 
-    const displayPinMarker = (
-      coords,
-      offset
-    ) => {
-      return new Marker({ scale: 1.3, color: '#f44336', anchor: 'bottom' }).setLngLat(coords).setOffset(offset)
+    const displayPinMarker = (coords, offset) => {
+      return new Marker({
+        scale: 1.3,
+        color: '#f44336',
+        anchor: 'bottom'
+      })
+        .setLngLat(coords)
+        .setOffset(offset)
     }
 
     const displayMarker = (element, feature, size) => {

diff --git a/src/index.ts b/src/index.ts
@@ -1,3 +1,3 @@
-import { UnCluster } from "./uncluster";
+import { TeritorioCluster } from "./teritorioCluster";
 
-export { UnCluster }
+export { TeritorioCluster }