From 4cedacb2bc8de144b481986653a502021a05982d Mon Sep 17 00:00:00 2001 From: Jonathan Lurie Date: Wed, 8 Nov 2023 15:43:24 +0100 Subject: [PATCH] Making the ES module (#3) * ADD es * ADD better linting config and gh actions * FIX gh action * ADD lower case export --- .eslintrc.json | 13 + .github/pull_request_template.md | 11 + .github/workflows/format-lint.yml | 24 + .github/workflows/npm-publish.yml | 1 + .gitignore | 88 +- .npmignore | 9 + CHANGELOG.md | 136 +- LICENSE.md | 9 + README.md | 218 +- {examples => demos}/basic.html | 15 +- {examples => demos}/choropleth.html | 6 +- {examples => demos}/cluster.html | 4 +- {examples => demos}/custom_marker.html | 6 +- {examples => demos}/events.html | 4 +- {examples => demos}/geolocate.html | 6 +- demos/helpers.html | 62 + {examples => demos}/language.html | 8 +- {examples => demos}/leaf_marker.png | Bin {examples => demos}/leaf_shadow.png | Bin {examples => demos}/overlay.html | 6 +- {examples => demos}/us-states.js | 0 header.png => images/header.png | Bin images/leaflet-maptilersdk.jpg | Bin 0 -> 1005550 bytes images/sdk_helpers.jpg | Bin 0 -> 458499 bytes leaflet-maptilersdk.js | 372 -- leaflet-maptilersdk.js.d.ts | 35 - package-lock.json | 5898 ++++++++++++++++++++++++ package.json | 59 +- src/leaflet-maptilersdk.js | 422 ++ vite.config-es.js | 36 + vite.config-umd.js | 40 + 31 files changed, 6836 insertions(+), 652 deletions(-) create mode 100644 .eslintrc.json create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/format-lint.yml create mode 100644 .npmignore create mode 100644 LICENSE.md rename {examples => demos}/basic.html (77%) rename {examples => demos}/choropleth.html (96%) rename {examples => demos}/cluster.html (95%) rename {examples => demos}/custom_marker.html (91%) rename {examples => demos}/events.html (97%) rename {examples => demos}/geolocate.html (89%) create mode 100644 demos/helpers.html rename {examples => demos}/language.html (84%) rename {examples => demos}/leaf_marker.png (100%) rename {examples => demos}/leaf_shadow.png (100%) rename {examples => demos}/overlay.html (90%) rename {examples => demos}/us-states.js (100%) rename header.png => images/header.png (100%) create mode 100644 images/leaflet-maptilersdk.jpg create mode 100644 images/sdk_helpers.jpg delete mode 100644 leaflet-maptilersdk.js delete mode 100644 leaflet-maptilersdk.js.d.ts create mode 100644 package-lock.json create mode 100644 src/leaflet-maptilersdk.js create mode 100644 vite.config-es.js create mode 100644 vite.config-umd.js diff --git a/.eslintrc.json b/.eslintrc.json new file mode 100644 index 0000000..8f6a415 --- /dev/null +++ b/.eslintrc.json @@ -0,0 +1,13 @@ +{ + "env": { + "browser": true, + "es2021": true + }, + "extends": "eslint:recommended", + "parserOptions": { + "ecmaVersion": "latest", + "sourceType": "module" + }, + "rules": { + } +} diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..e18eade --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,11 @@ +## Objective +What is the goal? + +## Description +What changed, how and why? + +## Acceptance +How were changes tested? + +## Checklist +- [ ] I have added relevant info to the CHANGELOG.md \ No newline at end of file diff --git a/.github/workflows/format-lint.yml b/.github/workflows/format-lint.yml new file mode 100644 index 0000000..3359dd1 --- /dev/null +++ b/.github/workflows/format-lint.yml @@ -0,0 +1,24 @@ +name: Format and Lint + +on: [pull_request] + +jobs: + format-and-lint: + runs-on: ubuntu-latest + steps: + - name: Check out Git repository + uses: actions/checkout@v3 + + - name: Set up Node.js + uses: actions/setup-node@v3 + with: + node-version: 18 + + - name: Install Node.js dependencies + run: npm ci + + - name: Formatting with Prettier + run: npm run format + + - name: Linting with ESLint + run: npm run lint \ No newline at end of file diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml index 6291c70..26361a7 100644 --- a/.github/workflows/npm-publish.yml +++ b/.github/workflows/npm-publish.yml @@ -17,6 +17,7 @@ jobs: node-version: 18 registry-url: https://registry.npmjs.org/ - run: npm ci + - run: npm run make - run: npm publish --access public env: NODE_AUTH_TOKEN: ${{secrets.npm_token}} diff --git a/.gitignore b/.gitignore index 1856faf..b4a6f64 100644 --- a/.gitignore +++ b/.gitignore @@ -2,34 +2,112 @@ logs *.log npm-debug.log* +yarn-debug.log* +yarn-error.log* +lerna-debug.log* + +# Diagnostic reports (https://nodejs.org/api/report.html) +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json # Runtime data pids *.pid *.seed +*.pid.lock # Directory for instrumented libs generated by jscoverage/JSCover lib-cov # Coverage directory used by tools like istanbul coverage +*.lcov + +# nyc test coverage +.nyc_output -# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) .grunt +# Bower dependency directory (https://bower.io/) +bower_components + # node-waf configuration .lock-wscript -# Compiled binary addons (http://nodejs.org/api/addons.html) +# Compiled binary addons (https://nodejs.org/api/addons.html) build/Release -# Dependency directory -node_modules +# Dependency directories +node_modules/ +jspm_packages/ + + +# TypeScript v1 declaration files +typings/ + +# TypeScript cache +*.tsbuildinfo # Optional npm cache directory .npm +# Optional eslint cache +.eslintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + # Optional REPL history .node_repl_history -.DS_Store \ No newline at end of file +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variables file +.env +.env.test + +# parcel-bundler cache (https://parceljs.org/) +.cache + +# Next.js build output +.next + +# Nuxt.js build / generate output +.nuxt + + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and *not* Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# vuepress build output +.vuepress/dist + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port +.DS_Store + +tmp.txt + +tests/ +build/ +dist/ +docs/ \ No newline at end of file diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..cf24b6a --- /dev/null +++ b/.npmignore @@ -0,0 +1,9 @@ +src/ +docs +images +tests +vite* +.github +.eslintrc.json +demos +build \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index dcc746e..2912e57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,127 +1,17 @@ -# Change Log -All notable changes to this project will be documented in this file. +# MapTiler Client Changelog -The format is based on [Keep a Changelog](http://keepachangelog.com/) -and this project adheres to [Semantic Versioning](http://semver.org/). +## DEVEL +### New Features +### Bug Fixes +### Others -## 1.0.0 - 2023-05-08 +## 2.0.0 +### New Features +- Major rework of the library to nmake it fully compatible with ES module installable from NPM, yet designed to be fully backward compatible and still usable from CDN/UMD +- The custom layer exposes the MapTiler SDK layer helpers to make it easy to add polyline/point/polygon/heatmap layers +- The custom layer now has a "ready" event that happens when the internal MapTiler SDK Map instance is fully loaded -### Changed -- This fork is intended to support MapTiler SDK instead of MapLibre GL JS - -## Unreleased - -- Fix [#29](https://github.com/maplibre/maplibre-gl-leaflet/issues/29) - layer is mis-aligned with map when panning the map off screen ([#31](https://github.com/maplibre/maplibre-gl-leaflet/pulls/31)) - -## 0.0.19 - 2022-11-30 - -### Fixed - -- round CSS translate values to avoid blurry tiles ([#41](https://github.com/maplibre/maplibre-gl-leaflet/issues/41)). - -## 0.0.18 - 2022-11-11 - -### Fixed - -- import MapOptions instead of obsolete MapboxOptions for compatibility with neuer maplibre-gl versions ([#25](https://github.com/maplibre/maplibre-gl-leaflet/issues/25)). - -## 0.0.15 - 2021-07-08 - -### Added -- types definition - -## 0.0.14 - 2020-11-24 - -### Fixed - -- fix gl offset issue in low zoom level - -## 0.0.13 - 2020-08-31 - -### Added -- `.getPaneName()` method - -### Fixed -- Allow gl tiles to be added to a custom pane defined in options - -## 0.0.12 - 2020-03-27 - -### Fixed - -- `accessToken` is now optional - -## 0.0.11 - 2019-11-04 - -### Fixed - -- ensure gl map is added to leaflet TilePane - -## 0.0.10 - 2019-09-16 - -## Added - -- `.getContainer()`, `.getSize()`, `getBounds()` and `getCanvas()` methods. - -## Fixed - -- internal code changes to bring it closer to other overlay layers. - -## 0.0.9 - 2019-09-02 - -## Added - -- Added `interactive` option to make `mapbox-gl` map events handling possible. -- added public accessor to `mapbox-gl` map object - -## 0.0.8 - 2019-08-07 - -## Added - -- Added a `padding` option to fix the grey backgrougd flickering around the edges of the map while panning/zooming -- bumped the libraries in examples - -## 0.0.7 - 2019-07-01 - -### Fixed - -- Ensure no blank/gray area is displayed when zooming out. - -## 0.0.6 - 2019-05-07 - -### Fixed - -- `.git` directory removed from npm tarball. - -## 0.0.5 - 2019-05-01 - -### Added - -- `leaflet` and `mapbox-gl-js` are now declared as peerDependencies. - -## 0.0.4 - 2019-02-27 - -### Added - -- UMD wrapper -- support for `pane` in constructor - -### Fixed - -- webkitTransitionEnd event crash - -## 0.0.3 - 2017-04-18 - -### Added - -- Improved support for older versions of `mapbox-gl-js` - -## 0.0.2 - 2017-03-08 - -### Added - -- Introduced support for Leaflet `v1.0.x` - -## 0.7. - 2016-10-09 - -- Compatibility release for Leaflet `v0.7.x` +## 1.0.0 +### New Features +- First release. This was essentially a fork of the [MapLibre version](https://github.com/maplibre/maplibre-gl-leaflet) adapted to MapTiler SDK. \ No newline at end of file diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..37475a2 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,9 @@ +MapTiler Weather JS Module + +Copyright © 2023 MapTiler AG. All rights reserved. + +The software and files (collectively “Software”) in this repository are licensed for use only with MapTiler service(s). + +For the license terms, please reference [MapTiler General Terms and Conditions](https://www.maptiler.com/terms/) which incorporate MapTiler Weather JS Module Product [Terms (collectively “Terms”) and Privacy Policy at Privacy policy](https://www.maptiler.com/privacy-policy). + +This license allows users with an active MapTiler account to modify and integrate authorized portions of the Software for use with the relevant MapTiler service(s) in accordance with the MapTiler Terms. This license terminates automatically if a user no longer maintains a MapTiler account or their usage breaches MapTiler Terms. \ No newline at end of file diff --git a/README.md b/README.md index 18568f7..97c7d94 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,98 @@

- official page →
- + official page →
+

This is a binding from [MapTiler SDK JS/TS](https://docs.maptiler.com/sdk-js/) to the familiar -[Leaflet](http://leafletjs.com/) API. This is a fork of the [MapLibre version](https://github.com/maplibre/maplibre-gl-leaflet). +[Leaflet](http://leafletjs.com/) API. **MapTiler SDK JS** is an extension of MapLibre GL JS, fully backward compatible, tailored for MapTiler Cloud and with plenty of extra features! -## Code example -```javascript +![](images/leaflet-maptilersdk.jpg) -const map = L.map('map').setView([38.912753, -77.032194], 15); -L.marker([38.912753, -77.032194]) - .bindPopup("Hello Leaflet GL!
Whoa, it works!") - .addTo(map) - .openPopup(); +## Usage +### From ES module using `import` +For the following examples, we are using the [Vite vanilla JS app](https://vitejs.dev/guide/) as a starting point. -const mtLayer = L.maptilerLayer({ - style: "https://api.maptiler.com/maps/streets-v2/style.json?key=YOUR_MAPTILER_API_KEY", -}).addTo(map); +The typical Leaflet plugin usualy adds new elements directly in the global object `L` and even though this API design is now a bit dated and somewhat frown uppon, we did not want to disrupt the dev experiece for those used to this. For this reason, you will need to import the plugin but not a specific object from it, as `MaptilerLayer` is internally added to `L`: + +```js +// import Leaflet and its style +import L from "leaflet"; +import "leaflet/dist/leaflet.css"; + +// Import the Leaflet MapTiler Plugin +import "@maptiler/leaflet-maptilersdk"; + +// Import your custom style, +// depending on your configuration, you may have to change how this is done +import './style.css'; ``` -You can also use any of the MapTiler style shorthand alongside the `apiKey` option: -```javascript -const mtLayer = L.maptilerLayer({ +Then, in the Vite vanilla app, we would have to do exactely like in regular vanilla JS: +```js +// Center the map on Manhattan, zoom level 13 +const map = L.map("map").setView([40.7468, -73.98775], 13); + +// Center the map on Manhattan, zoom level 13 +L.marker([40.7468, -73.98775]) + .bindPopup("Hello Leaflet with MapTiler SDK") + .addTo(map) + .openPopup(); + +// Create a MapTiler Layer inside Leaflet +const mtLayer = new L.MaptilerLayer({ + // Get your free API key at https://cloud.maptiler.com apiKey: "YOUR_MAPTILER_API_KEY", - style: L.MaptilerStyle.STREETS, // optional }).addTo(map); ``` -Get an API key with the generous free plan at [cloud.maptiler.com](https://cloud.maptiler.com/) +If you would rather stick to more modern API design and do not feel like using the `L` object, we got you covered: + +```js +import { MaptilerLayer } from "@maptiler/leaflet-maptilersdk"; + +// ... + +const mtLayer = new MaptilerLayer( options ); +``` + +## From ES module, the *async* way +Some frontend frameworks always are very opinionated regarding Server-Side-rendering and will attemp to perform it, that's the case of [Next.js](https://nextjs.org/). But Leaflet does not play well with it because there are some direct calls to the global `window` object, and this would crash on a server. The fix consists in importing Leaflet dynamically, and then `@maptiler/leaflet-maptilersdk` can also be imported. + +The React lifecycle method `.componentDidMount()` of a class component is only called on the frontend so this is why we have decided to dynamically import from there, but feel free to adapt your code if you are using a function component or a non-React app: + +```js +componentDidMount() { + // assuming this was init with React.createRef() + const container = this.mapContainer.current; + + // A self-callable async function because importing packages dynamically is an async thing to do + (async () => { -Once you have created the leaflet layer, the MapTiler SDK `Map` instance can be accessed using -```javascript -const maptilerMap = mtLayer.getMaptilerMap(); + // dynamic import of Leaflet + const L = await import('leaflet'); -// add a source to the MapTiler SDK layer, just like you would do with the MapTiler SDK -mtLayer.getMaptilerMap().addSource({...}); + // dynamic import of the library + const leafletmaptilersdk = await import('@maptiler/leaflet-maptilersdk'); + + // Creating the Leaflet map + const map = L.map(container).setView([51.505, -0.09], 10); + + // Creating the MapTiler Layer + const mtLayer = new leafletmaptilersdk.MaptilerLayer({ + apiKey: "YOUR_API_KEY", + }).addTo(map); + + })() +} ``` -## Examples -The [examples](examples) folder of this repository is a good place to start! -## Installation -Add a script tag referencing leaflet-maptilersdk after adding leaflet and MapTiler SDK in your website: +### From CDN with the UMD bundle +The UDM *leaflet-maptilersdk* bundle is not package with Leaflet nor with MapTiler SDK, so those will have to be imported as ` - - + + ``` -## Motivation -This project makes it possible to easily add a MapTiler SDK JS layer in your Leaflet map. When using leaflet-maptilersdk, you won't be able to use some of the MapTiler SDK features. -Here are the main differences between a "pure" MapTiler SDK map and a Leaflet map using maptilesdk-leaflet: -- No rotation / bearing / pitch support -- Slower performances: When using leaflet-maptilersdk, MapTiler SDK is set as not interactive. Leaflet receives the touch/mouse events and updates the MapTiler SDK map behind the scenes. Because MapTiler SDK doesn't redraw as fast as Leaflet, the map can seem slower. -- Terrain elevation is possible but will create a parallax effect that will result in a missalignment of other Leaflet features (markers, overlays, etc.) +Then, in the HTML ``, decalre the container that will host the map: +```html +
+``` -On the bright side, the leaflet-maptilersdk binding will allow you to use all the leaflet features and plugins. +Finally, add a ` @@ -20,29 +22,34 @@ + + +
- + diff --git a/examples/choropleth.html b/demos/choropleth.html similarity index 96% rename from examples/choropleth.html rename to demos/choropleth.html index e3a61d3..5019a86 100644 --- a/examples/choropleth.html +++ b/demos/choropleth.html @@ -65,7 +65,7 @@
- + + + diff --git a/examples/events.html b/demos/events.html similarity index 97% rename from examples/events.html rename to demos/events.html index 042a3e6..56921df 100644 --- a/examples/events.html +++ b/demos/events.html @@ -22,7 +22,7 @@
- + + + + + + + + + + + + + +
+ + + + + diff --git a/examples/language.html b/demos/language.html similarity index 84% rename from examples/language.html rename to demos/language.html index c1dd1ee..6efb6f3 100644 --- a/examples/language.html +++ b/demos/language.html @@ -25,16 +25,16 @@
- + diff --git a/examples/leaf_marker.png b/demos/leaf_marker.png similarity index 100% rename from examples/leaf_marker.png rename to demos/leaf_marker.png diff --git a/examples/leaf_shadow.png b/demos/leaf_shadow.png similarity index 100% rename from examples/leaf_shadow.png rename to demos/leaf_shadow.png diff --git a/examples/overlay.html b/demos/overlay.html similarity index 90% rename from examples/overlay.html rename to demos/overlay.html index 306bd58..4175fee 100644 --- a/examples/overlay.html +++ b/demos/overlay.html @@ -10,7 +10,7 @@ - +