=== JVM Simple Map ===
Contributors: jorisvanmontfort
Tags: map, leaflet, openstreetmap, contact, location
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A lightweight contact map block based on Leaflet. No Google Maps, no API key required to get started.

== Description ==

JVM Simple Map adds a single Gutenberg block that shows a contact map with a marker and an optional popup. Pick an address, coordinates are looked up automatically, and you are done. No Google account, no billing, no API key needed for the default setup.

**How it works**

* Add the "JVM Map" block to any page or post.
* Search the address in the block sidebar (uses the free, keyless PDOK Locatieserver for Dutch addresses) or enter latitude/longitude manually.
* Set zoom level, map height and popup text. The editor shows a live preview of the map.

**Tile providers (Settings → JVM Map)**

The map style is configured once per site and applies to all maps:

* **PDOK** (default): Dutch government geodata (Kadaster). Free, no API key.
* **PDOK vector**: sharper vector rendering of the same data. Free, no API key.
* **CARTO**: Voyager, Positron or Dark Matter raster tiles. Requires a free API key.
* **CARTO vector**: sharper vector rendering. Requires the same API key.
* **Stadia Maps**: several styles. Requires a free API key.
* **TopPlusOpen**: German government geodata. Free, no API key.
* **OpenStreetMap**: standard tiles, for development only (see usage policy).

Vector maps are rendered with MapLibre GL under the Leaflet API, so markers, popups and the scroll hint keep working exactly the same. Browsers without WebGL automatically fall back to raster tiles.

**Details**

* Custom marker icon (Media Library upload) with automatic scaling.
* Lazy loading: maps below the fold only download tiles once scrolled into view (can be disabled).
* "Use Ctrl + scroll to zoom" hint so the map never hijacks page scrolling.
* All libraries (Leaflet 1.9.4, MapLibre GL, gesture handling) are bundled locally: no CDN, no extra dependencies, no tracking.
* English with Dutch translation included (`languages/`).

== Installation ==

1. Upload the `jvm-simple-map` folder to `wp-content/plugins/` (or install the ZIP via Plugins → Add New → Upload).
2. Activate the plugin.
3. Optionally pick a tile provider under Settings → JVM Map (the PDOK default works immediately, no key needed).
4. Add the "JVM Map" block to a page, search the address, done.

== Frequently Asked Questions ==

= Do I need an API key? =
No. The default PDOK provider (raster and vector) is free and keyless. Only CARTO and Stadia Maps ask for a free key, which you paste once under Settings → JVM Map.

= Is my API key visible to visitors? =
Yes. Any browser-based map must send its key along with tile requests, so it appears in the page source. This is normal and unavoidable. Protect the key where it matters: restrict it to your own domain(s) in the provider dashboard (CARTO supports this), so a copied key is useless elsewhere.

= Raster or vector: which should I pick? =
Vector is sharper on every screen, stays up to date longer (CARTO is retiring raster), and needs no separate retina tiles. Raster is lighter (~40 KB vs ~280 KB of JavaScript) and works everywhere, including browsers without WebGL. When in doubt: PDOK vector for Dutch sites, PDOK raster for maximum compatibility.

= The map shows nothing / grey tiles =
Either the block has no coordinates yet (search an address in the block sidebar), or the provider rejects requests, typically a missing or invalid API key (CARTO/Stadia), visible as 401 errors in the browser console. Switch to keyless PDOK to verify.

= Does it work outside the Netherlands? =
The address search currently only covers the Netherlands (PDOK). Coordinates can still be entered manually for anywhere in the world, but note the PDOK background map itself only covers the Netherlands; use CARTO or Stadia for international maps.

== Screenshots ==

1. The JVM Map block with live preview in the editor.
2. Address search: pick a suggestion, coordinates are filled in.
3. Settings → JVM Map: provider, map style, marker icon and lazy loading.
4. Vector map on the frontend with custom marker and popup.

== External services ==

Depending on the configured tile provider (Settings → JVM Map), the visitor's browser contacts one of the following map services to download map images or vector tiles. This happens every time a page with a map is viewed. Like any web request, this exposes the visitor's IP address and browser user agent to that service; no cookies are set and no account or personal data is sent by this plugin. Only the active provider is ever contacted.

* **PDOK (default, raster and vector)** — Dutch government geodata by Kadaster. Used for the map background and, in the block editor only, for address search (the search text typed by the editor is sent to PDOK when the search button is used). Map data under CC-BY-4.0, attribution shown on the map. Terms: https://www.pdok.nl/pdc-afnemers-van-data — Privacy: https://www.kadaster.nl/privacy
* **CARTO (only when selected, requires API key)** — raster or vector basemap tiles, requested with your API key. Terms: https://carto.com/legal/basemap-terms — Privacy: https://carto.com/privacy/
* **Stadia Maps (only when selected, requires API key)** — raster map tiles, requested with your API key. Terms: https://stadiamaps.com/terms-of-service/ — Privacy: https://stadiamaps.com/privacy/
* **TopPlusOpen (only when selected)** — German government geodata (BKG) under the dl-de/by-2-0 licence: https://www.govdata.de/dl-de/by-2-0
* **OpenStreetMap (only when selected, development only)** — standard tiles, subject to the tile usage policy: https://operations.osmfoundation.org/policies/tiles/ — Privacy: https://wiki.osmfoundation.org/wiki/Privacy_Policy

== Third-party software ==

This plugin bundles the following unmodified libraries (all GPL-compatible):

* Leaflet 1.9.4 (BSD-2-Clause) by Vladimir Agafonkin, https://leafletjs.com
* MapLibre GL JS 5.24.0 (BSD-3-Clause), https://maplibre.org
* maplibre-gl-leaflet 0.1.3 (ISC License) by MapLibre and Mapbox, https://github.com/maplibre/maplibre-gl-leaflet
* leaflet-gesture-handling 1.2.2 (MIT) by A Marquis, https://github.com/elmarquis/leaflet-gesture-handling

== Changelog ==

= 1.0.2 =
* Review compliance: translators comment, stricter output escaping, cleanup of unused dependencies and attributes, uninstall routine, license URI header, third-party credits, External services documentation and correct Contributors entry.

= 1.0.1 =
* Initial release: Leaflet block with live editor preview, address search without dummy coordinates, central tile provider settings (PDOK default, keyless), raster and vector rendering, custom marker icon, lazy loading and Dutch translation.
