@molecule/app-maps-leaflet 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,119 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-08-04T01:52:05.723Z
+-->
+
+# @molecule/app-maps-leaflet
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+`@molecule/app-maps-leaflet` — a Leaflet-backed provider for `@molecule/app-maps`.
+Renders real slippy maps with OpenStreetMap tiles (NO API key). Bond it once at
+startup and every `createMap` call shows a real map — the built-in default only
+paints a grey placeholder panel.
+
+## Quick Start
+
+```ts
+// In your app entry, ONCE — REQUIRED: import 'leaflet/dist/leaflet.css'
+// (without that CSS the tiles + markers are mispositioned):
+import { setProvider, createMap } from '@molecule/app-maps'
+import { provider } from '@molecule/app-maps-leaflet'
+setProvider(provider)
+
+// then anywhere (the container element needs an explicit height):
+const el = document.getElementById('map') as HTMLElement
+const map = await createMap({ container: el, center: { lat: 51.5, lng: -0.12 }, zoom: 12 })
+map.addMarker({ id: 'a', position: { lat: 51.5, lng: -0.12 }, popup: 'Here' })
+// …later, on unmount: map.destroy()
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/app-maps-leaflet @molecule/app-maps leaflet
+npm install -D @types/leaflet
+```
+
+## API
+
+### Functions
+
+#### `createProvider()`
+
+Creates a Leaflet-backed `MapProvider`.
+
+```typescript
+function createProvider(): MapProvider
+```
+
+**Returns:** A `MapProvider` that renders real OpenStreetMap-tiled maps.
+
+### Constants
+
+#### `provider`
+
+The default Leaflet map provider, ready to bond with `setProvider(provider)`.
+
+```typescript
+const provider: MapProvider
+```
+
+## Core Interface
+
+Implements `@molecule/app-maps` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/app-maps'
+import { provider } from '@molecule/app-maps-leaflet'
+
+export function setupMapsLeaflet(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/app-maps` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/app-maps`
+- `leaflet`
+
+TWO gotchas that decide whether the map is visible at all:
+
+- **Import `leaflet/dist/leaflet.css` once** (app entry). Without it, tiles and
+  markers are mispositioned — the #1 "my Leaflet map looks broken" cause.
+- **The container needs an explicit height** (e.g. `style={{ height: 400 }}`); a
+  zero-height container renders a blank map.
+
+Markers use a self-contained inline-SVG pin by default (no image-asset wiring —
+this sidesteps Leaflet's default-icon 404 under bundlers); pass `icon` for a
+custom URL. ALWAYS `destroy()` on unmount — Leaflet attaches DOM + resize
+listeners, and re-initialising over a live container throws "Map container is
+already initialized".
+
+`getSnapshot()` rejects (Leaflet has no built-in export) and `getCanvas()`
+returns a best-effort surface — both are WebGL-provider (Mapbox/MapLibre)
+concepts. Everything else (markers/polylines/polygons/circles/popups/viewport/
+fitBounds/project/events) renders for real.
+
+BROWSER-ONLY: draws to the DOM via Leaflet. Import + wire from app/client code.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@molecule/app-maps-leaflet",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Leaflet (OpenStreetMap) provider for @molecule/app-maps",
+  "homepage": "https://www.molecule.dev/packages/app-maps-leaflet",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +18,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -28,17 +30,18 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
     "directory": "packages/app/bonds/maps/leaflet"
   },
   "peerDependencies": {
-    "@molecule/app-maps": "^1.0.0"
+    "@molecule/app-maps": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/app-maps": "1.0.0",
+    "@molecule/app-maps": "1.0.2",
     "@types/leaflet": "1.9.21",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "dependencies": {
     "leaflet": "1.9.4"