RD-888 Refactored Geocoding Control (WIP)

.editorconfig

@@ -0,0 +1,13 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = LF
+charset = utf-8
+trim_trailing_whitespace = false
+insert_final_newline = true
+max_line_length = 180

.gitignore

@@ -7,11 +7,29 @@ yarn-error.log*
 pnpm-debug.log*
 lerna-debug.log*
 
-node_modules
-dist
-dist.svelte
-*.local
-.svelte-kit
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Dependency directories
+node_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
 
 # Editor directories and files
 .vscode/*
@@ -24,5 +42,4 @@ dist.svelte
 *.sln
 *.sw?
 
-*.tgz
-src/info.json
+dist

.lintstagedrc.json

@@ -1,4 +1,4 @@
 {
   "*": ["prettier --check"],
-  "*.{ts,svelte}": ["eslint"]
+  "*.{ts}": ["eslint"]
 }

.npmignore

@@ -0,0 +1,12 @@
+images
+demos
+public
+src
+!dist/src
+*.tgz
+.github
+.husky
+.vscode
+vite*
+.*
+tsconfig.json

.prettierrc

@@ -1,5 +1,4 @@
 {
-  "plugins": ["prettier-plugin-svelte", "prettier-plugin-organize-imports"],
-  "overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }],
+  "plugins": ["prettier-plugin-organize-imports"],
   "organizeImportsSkipDestructiveCodeActions": true
 }

.vscode/extensions.json

@@ -1,3 +1,3 @@
 {
-  "recommendations": ["svelte.svelte-vscode"]
+  "recommendations": ["runem.lit-plugin"]
 }

README.md

@@ -22,15 +22,15 @@
 
 The _MapTiler Geocoding control_ implements a powerful search box in your maps or online forms, enabling your application users to find any place on Earth down to individual addresses. Use the search box control with [MapTiler SDK JS](https://docs.maptiler.com/sdk-js/) (or other map libraries like [Leaflet](https://docs.maptiler.com/leaflet/), [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js), [OpenLayers](https://docs.maptiler.com/openlayers/)).
 
+> ⚠️ _MapTiler Geocoding control_ v3 support for _Leaflet_ (v1 and v2) and _OpenLayers_ is to be added soon. In the meantime, please use _MapTiler Geocoding control_ v2 with these map libraries.
+
 ## Why?
 
 The _Geocoding control_ uses the [MapTiler Geocoding API](https://www.maptiler.com/cloud/geocoding/). You can use the API directly from your web or backend applications or use the [API Client JS](https://docs.maptiler.com/client-js/) library.
 
-With this control, users of
-mapping application can:
+With this control, users of mapping application can:
 
-- Find any place on Earth (States, Cities, Streets, Addresses, POIs, ...) down
-  to the address level
+- Find any place on Earth (States, Cities, Streets, Addresses, POIs, ...) down to the address level
 - Find and identify objects or place names using a coordinate pair or a single mouse click (reverse geocoding)
 - Restrict the search area to a specific country, bounding box, or proximity
 - Highlight searched results on the map (marker or full geometry)
@@ -39,25 +39,19 @@ mapping application can:
 
 The component can be used as an ES module or UMD module with or without bundler.
 
-Geocoding control is also provided as [React component](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/react/) and [Svelte component](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/svelte/) and [other libraries](#installation-and-more-usage-examples).
+Geocoding control itself is provided as a [Web component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) which can be used with [React](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/react/), [Svelte](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/svelte/), and any other modern frontend library, or without any library at all.
 
 ## Install
 
-Install the Geocoding control unsing `npm`:
-
-**⚠️ Warning! ⚠️**
-
-The current version of Geocoding Control is only compatible with Svelte v4, this will potentially cause peer dependency issues when installing with certain versions of npm in Svelte projects (eg if you're using Svelte v5), or if you intend to import the Svelte component directly.
-
-If you are using a this library in a Svelte project you can npm install with `--force` or `--legacy-peer-deps` and use only the **pre-compiled `GeoLocatControl` vanilla module**, not the Svelte component.
+Install the Geocoding control unsing `npm`, together with your map library (MapTiler SDK as an example):
 
 ```shell
 npm install --save @maptiler/geocoding-control @maptiler/sdk
 ```
 
 ## Quick start
 
-Use the component in your mapping application:
+Use the component in your mapping application (MapTiler SDK as an example):
 
 ```js
 import * as maptilersdk from "@maptiler/sdk";
@@ -80,21 +74,22 @@ NOTE: Get your personal [MapTiler API key](https://docs.maptiler.com/cloud/api/a
 
 ## Installation and more usage examples
 
-- [With MapTiler SDK](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/sdk-js/)
-- [With MapLibre GL](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/maplibre-gl-js/)
-- [With Leaflet](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/leaflet/)
-- [With OpenLayers](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/openlayers/)
-- [As a React component](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/react/)
-- [As Svelte component](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/svelte/)
-- [As vanilla JavaScript module](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/vanilla-js/)
+- [As a standalone Geocoding component](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/standalone/) _(to be updated for v3)_
+- [With MapTiler SDK](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/sdk-js/) _(to be updated for v3)_
+- [With MapLibre GL](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/maplibre-gl-js/) _(to be updated for v3)_
+- [With Leaflet](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/leaflet/) _(to be updated for v3)_
+- [With OpenLayers](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/openlayers/) _(to be updated for v3)_
+- [As a React component](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/react/) _(to be updated for v3)_
+- [As Svelte component](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/svelte/) _(to be updated for v3)_
+- [As vanilla JavaScript module](https://docs.maptiler.com/sdk-js/modules/geocoding/api/usage/vanilla-js/) _(to be updated for v3)_
 
 ## API Documentation
 
 In addition to the details and examples provided in this `README.md` and our documentation, check out
 
 - [The complete Geocoding service API documentation](https://docs.maptiler.com/cloud/api/geocoding/)
-- [The complete Geocoding control reference](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/)
-- [UMD global variables](https://docs.maptiler.com/sdk-js/modules/geocoding/#umd-global-variables)
+- [The complete Geocoding control reference](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/) _(to be updated for v3)_
+- [UMD global variables](https://docs.maptiler.com/sdk-js/modules/geocoding/#umd-global-variables) _(to be updated for v3)_
 
 ## Development
 
@@ -112,6 +107,8 @@ You will find compilation result in the `dist` directory.
 npm install && VITE_API_KEY=YOUR_MAPTILER_API_KEY_HERE npm run dev
 ```
 
+Alternatively, you can provide your API key via `key` URL param.
+
 ### POI icons and bundlers
 
 POI icons are served from CDN per default. If there is an requirement to serve them from a different location and the control is used in the application which is built with Web Application bundler (like Webpack or Vite) then it is necessary to do some extra configuration. Icons are bundled in the library and you can find them in `node_modules/@maptiler/geocoding-control/icons`. Configure your bundler and/or provide `iconsBaseUrl` option for the icons to be properly resolved. You can also copy icons from that directory to your `public` directory.

SECURITY.md

@@ -4,9 +4,12 @@
 
 Following versions are supported with security updateds:
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.0.x   | :white_check_mark: |
+| Version | Supported |
+| ------- | --------- |
+| 0.0.x   | ❌        |
+| 1.x.x   | ❌        |
+| 2.x.x   | ❌        |
+| 3.x.x   | ✅        |
 
 ## Reporting a Vulnerability
 

demos/.env

@@ -0,0 +1,2 @@
+VITE_API_URL=https://api.maptiler.com/geocoding
+VITE_LIB_VERSION=$npm_package_version

demos/01-standalone.html

@@ -0,0 +1,18 @@
+<html>
+  <head>
+    <title>MapTiler Geocoding Control example</title>
+    <style>
+      body {
+        display: flex;
+        flex-direction: row;
+        justify-content: space-between;
+      }
+    </style>
+  </head>
+
+  <body>
+    <maptiler-geocoder class="first" iconsBaseUrl="/assets/icons/"></maptiler-geocoder>
+    <maptiler-geocoder class="second" iconsBaseUrl="/assets/icons/"></maptiler-geocoder>
+    <script type="module" src="/src/01-standalone.ts"></script>
+  </body>
+</html>

demos/02-maptiler-sdk.html

@@ -0,0 +1,29 @@
+<html>
+  <head>
+    <title>MapTiler Geocoding Control example</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+      }
+
+      #map {
+        position: absolute;
+        width: 100vw;
+        height: 100vh;
+        background: #ccc;
+      }
+
+      #style-picker-container {
+        position: absolute;
+        z-index: 2;
+        margin: 10px;
+      }
+    </style>
+  </head>
+
+  <body>
+    <div id="map"></div>
+    <script type="module" src="/src/02-maptiler-sdk.ts"></script>
+  </body>
+</html>

demos/03-maplibregl.html

@@ -0,0 +1,29 @@
+<html>
+  <head>
+    <title>MapTiler Geocoding Control example</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+      }
+
+      #map {
+        position: absolute;
+        width: 100vw;
+        height: 100vh;
+        background: #ccc;
+      }
+
+      #style-picker-container {
+        position: absolute;
+        z-index: 2;
+        margin: 10px;
+      }
+    </style>
+  </head>
+
+  <body>
+    <div id="map"></div>
+    <script type="module" src="/src/03-maplibregl.ts"></script>
+  </body>
+</html>

demos/04-react.html

@@ -0,0 +1,61 @@
+<html>
+  <head>
+    <title>MapTiler Geocoding Control example</title>
+    <link rel="stylesheet" href="https://unpkg.com/chota@latest" />
+    <style>
+      html,
+      body,
+      main {
+        height: 100%;
+        background-color: #eee;
+      }
+
+      main {
+        padding: 1em;
+        display: flex;
+        flex-direction: column;
+      }
+
+      .control-bar {
+        display: flex;
+        gap: 0.5em;
+        align-items: center;
+        flex-wrap: wrap;
+      }
+
+      .flex-grow {
+        flex-grow: 1;
+      }
+
+      .overflow-auto {
+        overflow: auto;
+      }
+
+      .logs {
+        display: grid;
+        column-gap: 1em;
+        grid-template-columns: auto 1fr;
+        height: 0px; /* fixes overflow */
+      }
+
+      .logs > div:nth-child(2n) {
+        text-wrap: nowrap;
+        color: blue;
+      }
+
+      select {
+        margin-right: 2ex;
+      }
+
+      button.is-small {
+        padding: 4px 8px;
+        font-size: 0.8em;
+      }
+    </style>
+  </head>
+
+  <body>
+    <main id="app"></main>
+    <script type="module" src="/src/04-react.tsx"></script>
+  </body>
+</html>

demos/eslint.config.js

@@ -0,0 +1,11 @@
+// @ts-nocheck
+
+import tseslint from "typescript-eslint";
+import baseConfig from "../eslint.config.js";
+
+export default tseslint.config(baseConfig, {
+  rules: {
+    "@typescript-eslint/no-unsafe-argument": "off",
+    "@typescript-eslint/no-unsafe-assignment": "off",
+  },
+});