@maptiler/geocoding-control 2.1.7 → 3.0.0-rc.2

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the MapTiler support team at `support [at] maptiler.com` . The support team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The support team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

package/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+## Contributing
+
+Thank you for considering contributing to MapTiler Geocoding Control package. It's people
+like you that make it to great tool.
+
+### Where do I go from here?
+
+If you've noticed a bug or have a feature request, [make one](https://github.com/maptiler/maptiler-geocoding-control/issues/new/choose)! It's
+generally best if you get confirmation of your bug or approval for your feature
+request this way before starting to code.
+
+If you have a general question about MapTiler Geocoding Control, you can reach out to the
+[MapTiler documentation portal](https://documentation.maptiler.com/hc/en-us/search?query=geocoding)
+or contact [our support](https://documentation.maptiler.com/hc/en-us/requests/new), the issue tracker is only for bugs and feature requests.
+
+### Fork & create a branch
+
+If this is something you think you can fix, then [create the fork](https://github.com/maptiler/maptiler-geocoding-control/fork) and create
+a branch with a descriptive name.
+
+A good branch name would be (where issue #325 is the ticket you're working on):
+
+```sh
+git checkout -b 325-add-poi-filter
+```
+
+### Get the test suite running
+
+Make sure you're using a recent version of NodeJS.
+
+Install the development dependencies:
+
+```sh
+npm install
+```
+
+Then run the development mode, make sure, you export the [MapTiler Key](https://docs.maptiler.com/cloud/api/authentication-key/) as environment variable
+
+```sh
+VITE_API_KEY=YOUR_MAPTILER_API_KEY_HERE npm run dev
+```
+
+### Implement your fix or feature
+
+At this point, you're ready to make your changes! Feel free to ask for help;
+everyone is a beginner at first :smile_cat:
+
+### Make a Pull Request
+
+At this point, you should switch back to your master branch and make sure it's
+up to date with MapTiler Geocoding Control main branch:
+
+```sh
+git remote add upstream git@github.com:maptiler/maptiler-geocoding-control.git
+git checkout main
+git pull upstream main
+```
+
+Then update your feature branch from your local copy of master, and push it!
+
+```sh
+git checkout 325-add-poi-filter
+git rebase main
+git push --set-upstream origin 325-add-poi-filter
+```
+
+Finally, go to GitHub and [make a Pull Request](https://github.com/maptiler/maptiler-geocoding-control/compare)
+
+## Final word
+
+Thank you one more time for your contribution. We try to deliver best user experience of geocoding, your contribution
+will make better experience to all users!

package/README.md

@@ -1,58 +1,59 @@
-<p align="center">
-<a href="https://www.maptiler.com/cloud/geocoding/">official page →</a><br>
-  <img src="images/maptiler-logo.svg" width="350px">
-</p>
+<img src="https://raw.githubusercontent.com/maptiler/maptiler-sdk-kotlin/main/Examples/maptiler-logo.png" alt="Company Logo" height="32"/>
 
-<p align="center" style="color: #AAA">
-  The Javascript & TypeScript Map Control component for <a href="https://www.maptiler.com/cloud/geocoding">MapTiler Geocoding</a> service! Easy to be integrated into any JavaScript mapping application.
-</p>
+# MapTiler Search and Geocoding control for MapTiler SDK, MapLibre GL JS, Leaflet and OpenLayers
 
-<p align="center">
-  <img src="images/JS-logo.svg" width="20px">
-  <img src="images/TS-logo.svg" width="20px">
-  <img src="images/react-logo.svg" width="20px">
-  <img src="images/svelte-logo.svg" width="20px">
-  <img src="https://img.shields.io/npm/v/@maptiler/geocoding-control"></img>
-  <img src="https://img.shields.io/twitter/follow/maptiler?style=social"></img>
-</p>
+The Javascript & TypeScript Map Control component for <a href="https://www.maptiler.com/cloud/geocoding">MapTiler Geocoding</a> service! Easy to be integrated into any JavaScript mapping application.
 
-# MapTiler Geocoding control for MapTiler SDK, MapLibre GL JS, Leaflet and OpenLayers
+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/)).
 
-## About
+> ⚠️ _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.
 
-A _Geocoding control_ for [MapTiler SDK](https://github.com/maptiler/maptiler-sdk-js),
-[MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js),
-[Leaflet](https://leafletjs.com) and [OpenLayers](https://openlayers.org) utilizes [MapTiler Cloud Geocoding
-API](https://www.maptiler.com/cloud/geocoding/). With this control, users of
-mapping application can find any place on Earth (States, Cities, Streets, Addresses, POIs, ...) down
-to the address level, restrict the search area to a specific country, highlight
-searched results on the map, autocomplete words while typing, and much more.
+[![](https://img.shields.io/npm/v/@maptiler/geocoding-control?style=for-the-badge&labelColor=D3DBEC&color=f2f6ff&logo=npm&logoColor=333359)](https://www.npmjs.com/package/@maptiler/geocoding-control)
+![](https://img.shields.io/badge/-white?style=for-the-badge&logo=javascript)![](https://img.shields.io/badge/-white?style=for-the-badge&logo=typescript)![](https://img.shields.io/badge/-white?style=for-the-badge&logo=react&logoColor=61dafb)![](https://img.shields.io/badge/-white?style=for-the-badge&logo=svelte&logoColor=FF3E00)
 
-The component can be used as an ES module or UMD module with or without bundler.
+---
+
+📖 [Documentation](https://docs.maptiler.com/sdk-js/modules/geocoding/) &nbsp; 📦 [NPM Package](https://www.npmjs.com/package/@maptiler/geocoding-control) &nbsp; 🌐 [Website](https://www.maptiler.com/search/) &nbsp; 🔑 [Get API Key](https://cloud.maptiler.com/account/keys/)
 
-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).
+---
 
-## Quick start
+<br>
 
-Install the Geocoding control unsing `npm`:
+<details> <summary><b>Table of Contents</b></summary>
+<ul>
+<li><a href="#-installation">Installation</a></li>
+<li><a href="#-basic-usage">Basic Usage</a></li>
+<li><a href="#-related-examples">Examples</a></li>
+<li><a href="#-api-reference">API Reference</a></li>
+<li><a href="#migration-guide">Migration Guide</a></li>
+<li><a href="#-support">Support</a></li>
+<li><a href="#-contributing">Contributing</a></li>
+<li><a href="#-license">License</a></li>
+<li><a href="#-acknowledgements">Acknowledgements</a></li>
+</ul>
+</details>
 
-**⚠️ Warning! ⚠️**
+<p align="center">   <img src="https://www.metalocator.com/wp-content/uploads/2022/07/maptiler-cloud-jp.jpg" alt="Demo Screenshot" width="80%"/>  <br />  <a href="#">See live interactive demo</a> </p>
+<br>
 
-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.
+## 📦 Installation
 
-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
 ```
 
-Use the component in your mapping application:
+<br>
+
+## 🚀 Basic Usage
+
+Use the component in your mapping application (MapTiler SDK as an example):
 
 ```js
 import * as maptilersdk from "@maptiler/sdk";
 import { GeocodingControl } from "@maptiler/geocoding-control/maptilersdk";
 import "@maptiler/sdk/dist/maptiler-sdk.css";
-import "@maptiler/geocoding-control/style.css";
 
 maptilersdk.config.apiKey = "YOUR_MAPTILER_API_KEY_HERE";
 
@@ -65,9 +66,9 @@ const gc = new GeocodingControl();
 map.addControl(gc);
 ```
 
-NOTE: Get your personal [MapTiler API key](https://docs.maptiler.com/cloud/api/authentication-key/) in the [MapTiler Cloud](https://cloud.maptiler.com).
+<br>
 
-## Installation and more usage examples
+## 💡 Related 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/)
@@ -77,17 +78,48 @@ NOTE: Get your personal [MapTiler API key](https://docs.maptiler.com/cloud/api/a
 - [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/)
 
-## API Documentation
+Check out the full list of [MapTiler geocoding examples](https://docs.maptiler.com/sdk-js/examples/?q=geocoding)
+
+<br>
+
+## 📘 API Reference
+
+For detailed guides, API reference, and advanced examples, visit our comprehensive documentation:
+
+[API documentation](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/)
+
+[Geocoding service API documentation](https://docs.maptiler.com/cloud/api/geocoding/)
+
+[UMD global variables](https://docs.maptiler.com/sdk-js/modules/geocoding/#umd-global-variables)
+
+<br>
+
+## 💬 Support
+
+- 📚 [Documentation](https://docs.maptiler.com/sdk-js/modules/geocoding/) - Comprehensive guides and API reference
+- ✉️ [Contact us](https://maptiler.com/contact) - Get in touch or submit a request
+- 🐦 [Twitter/X](https://twitter.com/maptiler) - Follow us for updates
+
+<br>
+
+---
 
-In addition to the details and examples provided in this `README.md` and our documentation, check out
+<br>
 
-- [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)
+## 🤝 Contributing
 
-## Development
+We love contributions from the community! Whether it's bug reports, feature requests, or pull requests, all contributions are welcome:
 
-### Building
+- Fork the repository and create your branch from `main`
+- If you've added code, add tests that cover your changes
+- Ensure your code follows our style guidelines
+- Give your pull request a clear, descriptive summary
+- Open a Pull Request with a comprehensive description
+- Read the [CONTRIBUTING](./CONTRIBUTING.md) file
+
+### Development
+
+#### Building
 
 ```bash
 npm install && npm run build
@@ -95,12 +127,52 @@ npm install && npm run build
 
 You will find compilation result in the `dist` directory.
 
-### Running in dev mode
+#### Running in dev mode
 
 ```bash
 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.
+
+<br>
+
+## 📄 License
+
+This project is licensed under the BSD 3-Clause License – see the [LICENSE](./LICENSE) file for details.
+
+<br>
+
+## 🙏 Acknowledgements
+
+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:
+
+- 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)
+- Autocomplete words while typing
+- and much more. Check out the [Geocoding Control API reference](https://docs.maptiler.com/sdk-js/modules/geocoding/api/api-reference/#options) to see all the options.
+
+The component can be used as an ES module or UMD module with or without bundler.
+
+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.
+
+<br>
+
+<p align="center" style="margin-top:20px;margin-bottom:20px;"> <a href="https://cloud.maptiler.com/account/keys/" style="display:inline-block;padding:12px 32px;background:#F2F6FF;color:#000;font-weight:bold;border-radius:6px;text-decoration:none;"> Get Your API Key <sup style="background-color:#0000ff;color:#fff;padding:2px 6px;font-size:12px;border-radius:3px;">FREE</sup><br /> <span style="font-size:90%;font-weight:400;">Start building with 100,000 free map loads per month ・ No credit card required.</span> </a> </p>
+
+<br>
+
+<p align="center"> 💜 Made with love by the <a href="https://www.maptiler.com/">MapTiler</a> team <br />
+<p align="center">
+  <a href="https://www.maptiler.com/search/">Website</a> •
+  <a href="https://docs.maptiler.com/sdk-js/modules/geocoding/">Documentation</a> •
+  <a href="https://github.com/maptiler/maptiler-geocoding-control">GitHub</a>
+</p>

package/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Supported Versions
+
+Following versions are supported with security updateds:
+
+| Version | Supported |
+| ------- | --------- |
+| 0.0.x   | ❌        |
+| 1.x.x   | ❌        |
+| 2.x.x   | ❌        |
+| 3.x.x   | ✅        |
+
+## Reporting a Vulnerability
+
+To report Vulnerability, add [new issue](https://github.com/maptiler/maptiler-geocoding-control/issues/new/choose) to the issues tracker