@florasync/leaflet-geokit 0.6.0 → 0.8.0

package/README.md

@@ -26,6 +26,7 @@ Documentation quick-links
 
 - What you get
 - Install
+- Tile Providers
 - Build and compilation
 - Runtime and architecture overview
 - Public API (attributes, properties, methods, events)
@@ -118,6 +119,52 @@ Why choose external?
 
 ---
 
+## Tile Providers
+
+The `<leaflet-geokit>` web component supports multiple tile provider modes.
+
+### OpenStreetMap (Default)
+
+```html
+<leaflet-geokit tile-provider="osm"></leaflet-geokit>
+```
+
+### HERE Maps
+
+Requires a HERE API key ([get one here](https://developer.here.com/)):
+
+```html
+<leaflet-geokit
+  tile-provider="here"
+  tile-style="lite.day"
+  api-key="YOUR_HERE_API_KEY"
+></leaflet-geokit>
+```
+
+`api-key` is the canonical attribute. `here-api-key` is also accepted as a legacy alias.
+
+**Available HERE Styles**:
+
+- `lite.day` - Lightweight basemap (default)
+- `normal.day` - Standard street map
+- `satellite.day` - Satellite imagery
+
+### Custom Tile Server (Backward Compatible)
+
+You can still use custom tile URLs:
+
+```html
+<leaflet-geokit
+  tile-url="https://example.com/tiles/{z}/{x}/{y}.png"
+></leaflet-geokit>
+```
+
+### Security Note
+
+⚠️ For production use, **do not** expose API keys client-side. Use a server-side proxy to request tiles.
+
+---
+
 ## Build and compilation
 
 Tooling
@@ -317,6 +364,12 @@ map.tileAttribution = "..."; // string | undefined
 map.readOnly = true; // boolean
 map.preferCanvas = false; // boolean
 map.logLevel = "info"; // LogLevel
+map.toolHooks = {
+  "tool:move:pending": (detail) => console.log("pending move", detail),
+}; // optional integrated tool hooks
+map.toolEventEmitter = {
+  emit: (eventName, detail) => console.log(eventName, detail),
+}; // optional integrated tool event emitter
 
 // Theming
 map.themeCss = `
@@ -325,6 +378,122 @@ map.themeCss = `
 `;
 ```
 
+### Integrated Tool Hooks & Event Emitter
+
+GeoKit exposes tool lifecycle events through two optional integration points:
+
+- `map.toolHooks`: per-event callbacks keyed by event name
+- `map.toolEventEmitter`: generic emitter object with either:
+  - `emit(eventName, detail)`
+  - or `dispatchEvent(new CustomEvent(eventName, { detail }))`
+
+Both can be used together. If both are provided, both are called.
+
+```javascript
+const map = document.querySelector("leaflet-geokit");
+
+map.toolHooks = {
+  "tool:move:pending": (detail) => {
+    console.log("Move pending", detail.layerId);
+  },
+  "tool:ruler:units-changed": (detail) => {
+    console.log("Units changed", detail.previous, "->", detail.current);
+  },
+};
+
+map.toolEventEmitter = {
+  emit: (eventName, detail) => {
+    analytics.track(eventName, detail);
+  },
+};
+```
+
+Important behavior notes:
+
+- Hooks/emitter can be assigned before or after map initialization.
+- Re-assigning `toolHooks`/`toolEventEmitter` at runtime updates active observers immediately.
+- Assign `undefined` to clear either integration point.
+
+#### Supported integrated tool event names
+
+- `tool:polygon:created`
+- `tool:polyline:created`
+- `tool:rectangle:created`
+- `tool:circle:created`
+- `tool:marker:created`
+- `tool:layer-cake:session-started`
+- `tool:layer-cake:saved`
+- `tool:move:pending`
+- `tool:move:confirmed`
+- `tool:move:cancelled`
+- `tool:edit:applied`
+- `tool:delete:applied`
+- `tool:ruler:units-changed`
+
+#### Event detail payloads
+
+`tool:*:created` (polygon/polyline/rectangle/circle/marker):
+
+```ts
+{
+  id: string;
+  geoJSON: GeoJSON.Feature;
+}
+```
+
+`tool:layer-cake:session-started`:
+
+```ts
+{
+  center: { lat: number; lng: number; ... };
+  radius: number;
+}
+```
+
+`tool:layer-cake:saved`:
+
+```ts
+{
+  featureCollection: GeoJSON.FeatureCollection;
+}
+```
+
+`tool:move:pending` / `tool:move:confirmed`:
+
+```ts
+{
+  layerId?: string;
+  originalGeoJSON?: GeoJSON.Feature;
+  newGeoJSON?: GeoJSON.Feature;
+}
+```
+
+`tool:move:cancelled`:
+
+```ts
+{
+  layerId?: string;
+}
+```
+
+`tool:edit:applied` / `tool:delete:applied`:
+
+```ts
+{
+  ids: string[];
+  geoJSON: GeoJSON.FeatureCollection;
+}
+```
+
+`tool:ruler:units-changed`:
+
+```ts
+{
+  previous: "metric" | "imperial";
+  current: "metric" | "imperial";
+}
+```
+
 ### Methods
 
 All methods return Promises and should be awaited. Invoke on the element instance: