feat(leaflet): Add new Leaflet basemap module (#138)

docs/modules/leaflet/README.md

@@ -0,0 +1,8 @@
+# Overview
+
+:::danger
+The deck.gl-community repo is specifically set up to collect useful code that no longer has dedicated maintainers. This means that there is often no one who can respond quickly to issues. The vis.gl / Open Visualization team members who try to keep this running can only put a few hours into it every now and then. It is important to understand this limitation. If your project depends on timely fixes, and you are not able to contribute them yourself, deck.gl-community modules may not be the right choice for you.
+:::
+
+This module allows [deck.gl](https://deck.gl) to be used as a Leaflet custom layer.
+

docs/modules/leaflet/api-reference/deck-layer.md

@@ -0,0 +1,43 @@
+# DeckLayer
+
+### DeckLayer
+
+An implementation of [L.Layer](https://leafletjs.com/reference.html#layer).
+
+```js
+const deckLayer = new DeckLayer({
+  views: [
+    new MapView({ repeat: true }),
+  ],
+  layers: [...],
+});
+map.addLayer(deckLayer);
+```
+
+The constructor accepts a props object that is passed to the [Deck](https://deck.gl/docs/api-reference/core/deck) constructor. See the [limitations](#supported-features-and-limitations) section below for more details.
+
+The following [Deck methods](https://deck.gl/docs/api-reference/core/deck#methods) can be called directly from a `DeckLayer` instance:
+
+- `deckOverlay.setProps`
+- `deckOverlay.pickObject`
+- `deckOverlay.pickMultipleObjects`
+- `deckOverlay.pickObjects`
+
+## Supported Features and Limitations
+
+Supported deck.gl features:
+
+- Layers
+- Effects
+- Auto-highlighting
+- Attribute transitions
+- `onHover` and `onClick` callbacks
+- Tooltip
+
+Not supported features:
+
+- Tilting
+- Multiple views
+- Controller
+- React integration
+- Gesture event callbacks (e.g. `onDrag*`)

docs/modules/leaflet/developer-guide/get-started.md

@@ -0,0 +1,72 @@
+# @deck.gl-community/leaflet
+
+This module allows [deck.gl](https://deck.gl) to be used as a Leaflet custom layer.
+
+## Installation
+
+```bash
+npm install deck.gl @deck.gl-community/leaflet leaflet
+```
+
+## Usage
+
+```js
+import {DeckLayer} from '@deck.gl-community/leaflet';
+import {MapView} from '@deck.gl/core';
+import {GeoJsonLayer, ArcLayer} from '@deck.gl/layers';
+import * as L from 'leaflet';
+import 'leaflet/dist/leaflet.css';
+
+// source: Natural Earth http://www.naturalearthdata.com/ via geojson.xyz
+const AIR_PORTS =
+  'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_airports.geojson';
+
+// Create map
+const map = L.map(document.getElementById('map'), {
+  center: [51.47, 0.45],
+  zoom: 4,
+});
+L.tileLayer('https://tiles.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}@2x.png', {
+  maxZoom: 22,
+  attribution:
+    '© <a href="https://carto.com/about-carto/" target="_blank" rel="noopener">CARTO</a>, © <a href="http://www.openstreetmap.org/about/" target="_blank">OpenStreetMap</a> contributors',
+}).addTo(map);
+
+// Add deck.gl overlay
+const deckLayer = new DeckLayer({
+  views: [
+    new MapView({ repeat: true }),
+  ],
+  layers: [
+    new GeoJsonLayer({
+      id: 'airports',
+      data: AIR_PORTS,
+      // Styles
+      filled: true,
+      pointRadiusMinPixels: 2,
+      pointRadiusScale: 2000,
+      getPointRadius: (f) => 11 - f.properties.scalerank,
+      getFillColor: [200, 0, 80, 180],
+      // Interactive props
+      pickable: true,
+      autoHighlight: true,
+      onClick: (info) =>
+        // eslint-disable-next-line
+        info.object && alert(`${info.object.properties.name} (${info.object.properties.abbrev})`)
+    }),
+    new ArcLayer({
+      id: 'arcs',
+      data: AIR_PORTS,
+      dataTransform: (d: any) => d.features.filter((f) => f.properties.scalerank < 4),
+      // Styles
+      getSourcePosition: (f) => [-0.4531566, 51.4709959], // London
+      getTargetPosition: (f) => f.geometry.coordinates,
+      getSourceColor: [0, 128, 200],
+      getTargetColor: [200, 0, 80],
+      getWidth: 1
+    })
+  ],
+  getTooltip: (info) => info.object && info.object.properties.name
+});
+map.addLayer(deckLayer);
+```

docs/modules/leaflet/sidebar.json

@@ -0,0 +1,21 @@
+{
+  "type": "category",
+  "label": "@deck.gl-community/leaflet",
+  "items": [
+    "modules/leaflet/README",
+    {
+      "type": "category",
+      "label": "Developer Guide",
+      "items": [
+        "modules/leaflet/developer-guide/get-started"
+      ]
+    },
+    {
+      "type": "category",
+      "label": "Layers",
+      "items": [
+        "modules/leaflet/api-reference/deck-layer"
+      ]
+    }
+  ]
+}

examples/bing-maps/app.ts

@@ -1,5 +1,5 @@
 import {loadModule} from '@deck.gl-community/bing-maps';
-import {GeoJsonLayer, ArcLayer} from 'deck.gl';
+import {GeoJsonLayer, ArcLayer} from '@deck.gl/layers';
 
 // set your Bing Maps API key here
 const BING_MAPS_API_KEY = (import.meta as any).env.VITE_BING_MAPS_API_KEY;

examples/bing-maps/package.json

@@ -6,7 +6,7 @@
     "start-local": "vite --config ../vite.config.local.mjs"
   },
   "dependencies": {
-    "deck.gl": "^9.0.12"
+    "@deck.gl/layers": "^9.0.12"
   },
   "devDependencies": {
     "typescript": "^5.4.4",

examples/leaflet/README.md

@@ -0,0 +1,18 @@
+# Example: Use deck.gl with Leaflet
+
+This is an example integrating deck.gl with Leaflet using the @deck.gl-community/leaflet module.
+
+## Usage
+
+To install dependencies:
+
+```bash
+npm install
+# or
+yarn
+```
+
+Commands:
+
+- `npm start` is the development target, to serve the app and hot reload.
+- `npm run build` is the production target, to create the final bundle and write to disk.

examples/leaflet/app.ts

@@ -0,0 +1,58 @@
+import {DeckLayer} from '@deck.gl-community/leaflet';
+import {MapView} from '@deck.gl/core';
+import {GeoJsonLayer, ArcLayer} from '@deck.gl/layers';
+import * as L from 'leaflet';
+import 'leaflet/dist/leaflet.css';
+
+// source: Natural Earth http://www.naturalearthdata.com/ via geojson.xyz
+const AIR_PORTS =
+  'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_airports.geojson';
+
+// Create map
+const map = L.map(document.getElementById('map'), {
+  center: [51.47, 0.45],
+  zoom: 4,
+});
+L.tileLayer('https://tiles.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}@2x.png', {
+  maxZoom: 22,
+  attribution:
+    '© <a href="https://carto.com/about-carto/" target="_blank" rel="noopener">CARTO</a>, © <a href="http://www.openstreetmap.org/about/" target="_blank">OpenStreetMap</a> contributors',
+}).addTo(map);
+
+// Add deck.gl overlay
+const deckLayer = new DeckLayer({
+  views: [
+    new MapView({ repeat: true }),
+  ],
+  layers: [
+    new GeoJsonLayer({
+      id: 'airports',
+      data: AIR_PORTS,
+      // Styles
+      filled: true,
+      pointRadiusMinPixels: 2,
+      pointRadiusScale: 2000,
+      getPointRadius: (f) => 11 - f.properties.scalerank,
+      getFillColor: [200, 0, 80, 180],
+      // Interactive props
+      pickable: true,
+      autoHighlight: true,
+      onClick: (info) =>
+        // eslint-disable-next-line
+        info.object && alert(`${info.object.properties.name} (${info.object.properties.abbrev})`)
+    }),
+    new ArcLayer({
+      id: 'arcs',
+      data: AIR_PORTS,
+      dataTransform: (d: any) => d.features.filter((f) => f.properties.scalerank < 4),
+      // Styles
+      getSourcePosition: (f) => [-0.4531566, 51.4709959], // London
+      getTargetPosition: (f) => f.geometry.coordinates,
+      getSourceColor: [0, 128, 200],
+      getTargetColor: [200, 0, 80],
+      getWidth: 1
+    })
+  ],
+  getTooltip: (info) => info.object && info.object.properties.name
+});
+map.addLayer(deckLayer);

examples/leaflet/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html>
+    <head>
+        <meta charset="UTF-8" />
+        <title>deck.gl w/ Leaflet example</title>
+        <style>
+            #map {
+                position: absolute;
+                top: 0;
+                left: 0;
+                width: 100%;
+                height: 100%;
+            }
+            .deck-tooltip {
+                white-space: nowrap;
+            }
+        </style>
+    </head>
+    <body>
+        <div id="map"></div>
+        <script type="module" src="app.ts"></script>
+    </body>
+</html>

examples/leaflet/package.json

@@ -0,0 +1,18 @@
+{
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "start": "vite --open",
+    "start-local": "vite --config ../vite.config.local.mjs"
+  },
+  "dependencies": {
+    "@deck.gl/core": "^9.0.12",
+    "@deck.gl/layers": "^9.0.12",
+    "leaflet": "^1.9.4"
+  },
+  "devDependencies": {
+    "@types/leaflet": "^1.9.12",
+    "typescript": "^5.4.4",
+    "vite": "^5.2.8"
+  }
+}

examples/leaflet/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["./*.ts"]
+}