@maptiler/geocoding-control 2.1.6 → 3.0.0-rc.1

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

@@ -16,31 +16,42 @@
   <img src="https://img.shields.io/twitter/follow/maptiler?style=social"></img>
 </p>
 
-# MapTiler Geocoding control for MapTiler SDK, MapLibre GL JS, Leaflet and OpenLayers
+# MapTiler Search and Geocoding control for MapTiler SDK, MapLibre GL JS, Leaflet and OpenLayers
 
-## About
+## What?
 
-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.
+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 _OpenLayers_ is to be added soon. In the meantime, please use _MapTiler Geocoding control_ v2 with this map library.
+
+## 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:
+
+- 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 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.
 
-## Quick start
+## Install
 
-Install the Geocoding control unsing `npm`:
+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:
+## Quick start
+
+Use the component in your mapping application (MapTiler SDK as an example):
 
 ```js
 import * as maptilersdk from "@maptiler/sdk";
@@ -63,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
 
@@ -95,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.

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