@molecule/app-maps-leaflet 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `@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.
+ *
+ * @example
+ * ```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()
+ * ```
+ *
+ * @remarks
+ * 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.
+ *
+ * @module
+ */
+export * from './provider.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,44 @@
+/**
+ * `@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.
+ *
+ * @example
+ * ```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()
+ * ```
+ *
+ * @remarks
+ * 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.
+ *
+ * @module
+ */
+export * from './provider.js';

package/dist/provider.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Leaflet implementation of the `@molecule/app-maps` `MapProvider`.
+ *
+ * Renders real slippy maps with OpenStreetMap raster tiles — no API key. See the
+ * module `@remarks` in `index.ts` for the required `leaflet/dist/leaflet.css`.
+ *
+ * @module
+ */
+import type { MapProvider } from '@molecule/app-maps';
+/**
+ * Creates a Leaflet-backed `MapProvider`.
+ *
+ * @returns A `MapProvider` that renders real OpenStreetMap-tiled maps.
+ */
+export declare const createProvider: () => MapProvider;
+/** The default Leaflet map provider, ready to bond with `setProvider(provider)`. */
+export declare const provider: MapProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAOV,WAAW,EAMZ,MAAM,oBAAoB,CAAA;AAmN3B;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAO,WAqBhC,CAAA;AAEF,oFAAoF;AACpF,eAAO,MAAM,QAAQ,EAAE,WAA8B,CAAA"}

package/dist/provider.js

@@ -0,0 +1,240 @@
+/**
+ * Leaflet implementation of the `@molecule/app-maps` `MapProvider`.
+ *
+ * Renders real slippy maps with OpenStreetMap raster tiles — no API key. See the
+ * module `@remarks` in `index.ts` for the required `leaflet/dist/leaflet.css`.
+ *
+ * @module
+ */
+import L from 'leaflet';
+const OSM_TILES = 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png';
+const OSM_ATTRIBUTION = '© OpenStreetMap contributors';
+/**
+ * Default marker icon as an inline-SVG `divIcon`. Leaflet's PNG default icons
+ * 404 under most bundlers (they resolve relative to the CSS), so a self-contained
+ * SVG pin makes markers render out-of-the-box with zero asset wiring.
+ */
+const defaultIcon = (color = '#2563eb') => L.divIcon({
+    className: 'mol-map-marker',
+    html: `<svg width="26" height="38" viewBox="0 0 26 38" xmlns="http://www.w3.org/2000/svg">` +
+        `<path d="M13 0C5.8 0 0 5.8 0 13c0 9.2 13 25 13 25s13-15.8 13-25C26 5.8 20.2 0 13 0z" fill="${color}"/>` +
+        `<circle cx="13" cy="13" r="5" fill="#fff"/></svg>`,
+    iconSize: [26, 38],
+    iconAnchor: [13, 38],
+    popupAnchor: [0, -34],
+});
+const toLatLng = (c) => [c.lat, c.lng];
+const fromLatLng = (ll) => ({ lat: ll.lat, lng: ll.lng });
+const toLeafletBounds = (b) => [
+    [b.sw.lat, b.sw.lng],
+    [b.ne.lat, b.ne.lng],
+];
+/** Builds the Leaflet marker for a molecule `MarkerConfig`. */
+const buildMarker = (m) => {
+    const icon = m.icon
+        ? L.icon({
+            iconUrl: m.icon,
+            iconSize: m.iconSize ?? [26, 38],
+            iconAnchor: m.iconAnchor ?? [13, 38],
+        })
+        : defaultIcon(m.color);
+    const marker = L.marker(toLatLng(m.position), {
+        icon,
+        draggable: m.draggable ?? false,
+        opacity: m.opacity ?? 1,
+        title: m.title,
+    });
+    if (m.popup)
+        marker.bindPopup(m.popup);
+    return marker;
+};
+/** Resolves the container element from a `MapConfig` (id string or element). */
+const resolveContainer = (container) => {
+    if (typeof container === 'string') {
+        const el = document.getElementById(container);
+        if (!el)
+            throw new Error(`@molecule/app-maps-leaflet: container element "#${container}" not found`);
+        return el;
+    }
+    return container;
+};
+/** Wraps a live Leaflet map in the molecule `MapInstance` contract. */
+const wrapInstance = (map) => {
+    const markers = new Map();
+    const polylines = new Map();
+    const polygons = new Map();
+    const circles = new Map();
+    return {
+        getViewport() {
+            return { center: fromLatLng(map.getCenter()), zoom: map.getZoom() };
+        },
+        setViewport(viewport) {
+            const center = viewport.center ? toLatLng(viewport.center) : map.getCenter();
+            map.setView(center, viewport.zoom ?? map.getZoom());
+        },
+        flyTo(location) {
+            const center = location.center ? toLatLng(location.center) : map.getCenter();
+            map.flyTo(center, location.zoom ?? map.getZoom());
+        },
+        fitBounds(bounds, options) {
+            map.fitBounds(toLeafletBounds(bounds), {
+                padding: options?.padding ? [options.padding, options.padding] : undefined,
+                animate: options?.animate,
+            });
+        },
+        getBounds() {
+            const b = map.getBounds();
+            return { ne: fromLatLng(b.getNorthEast()), sw: fromLatLng(b.getSouthWest()) };
+        },
+        addMarker(marker) {
+            const existing = markers.get(marker.id);
+            if (existing)
+                existing.marker.remove();
+            const built = buildMarker(marker);
+            built.addTo(map);
+            markers.set(marker.id, { marker: built, config: marker });
+        },
+        removeMarker(id) {
+            markers.get(id)?.marker.remove();
+            markers.delete(id);
+        },
+        updateMarker(id, updates) {
+            const existing = markers.get(id);
+            if (!existing)
+                return;
+            const merged = { ...existing.config, ...updates };
+            existing.marker.remove();
+            const built = buildMarker(merged);
+            built.addTo(map);
+            markers.set(id, { marker: built, config: merged });
+        },
+        getMarkers() {
+            return [...markers.values()].map((m) => m.config);
+        },
+        clearMarkers() {
+            for (const { marker } of markers.values())
+                marker.remove();
+            markers.clear();
+        },
+        addPolyline(polyline) {
+            polylines.get(polyline.id)?.remove();
+            const line = L.polyline(polyline.path.map(toLatLng), {
+                color: polyline.strokeColor,
+                weight: polyline.strokeWidth,
+                opacity: polyline.strokeOpacity,
+                dashArray: polyline.dashArray?.join(','),
+            }).addTo(map);
+            polylines.set(polyline.id, line);
+        },
+        removePolyline(id) {
+            polylines.get(id)?.remove();
+            polylines.delete(id);
+        },
+        addPolygon(polygon) {
+            polygons.get(polygon.id)?.remove();
+            const poly = L.polygon(polygon.path.map(toLatLng), {
+                fillColor: polygon.fillColor,
+                fillOpacity: polygon.fillOpacity,
+            }).addTo(map);
+            polygons.set(polygon.id, poly);
+        },
+        removePolygon(id) {
+            polygons.get(id)?.remove();
+            polygons.delete(id);
+        },
+        addCircle(circle) {
+            circles.get(circle.id)?.remove();
+            const c = L.circle(toLatLng(circle.center), { radius: circle.radius }).addTo(map);
+            circles.set(circle.id, c);
+        },
+        removeCircle(id) {
+            circles.get(id)?.remove();
+            circles.delete(id);
+        },
+        openPopup(popup) {
+            L.popup({ maxWidth: popup.maxWidth })
+                .setLatLng(toLatLng(popup.position))
+                .setContent(popup.content)
+                .openOn(map);
+        },
+        closePopups() {
+            map.closePopup();
+        },
+        on(event, handler) {
+            const wrapped = (e) => handler(e);
+            map.on(event, wrapped);
+            return () => map.off(event, wrapped);
+        },
+        off(event, handler) {
+            map.off(event, handler);
+        },
+        onMarkerClick(markerId, handler) {
+            const entry = markers.get(markerId);
+            if (!entry)
+                return () => { };
+            const wrapped = () => handler(entry.config);
+            entry.marker.on('click', wrapped);
+            return () => entry.marker.off('click', wrapped);
+        },
+        project(coordinates) {
+            const p = map.latLngToContainerPoint(toLatLng(coordinates));
+            return { x: p.x, y: p.y };
+        },
+        unproject(point) {
+            return fromLatLng(map.containerPointToLatLng(L.point(point.x, point.y)));
+        },
+        resize() {
+            map.invalidateSize();
+        },
+        getContainer() {
+            return map.getContainer();
+        },
+        getCanvas() {
+            // Leaflet renders via SVG/DOM tile layers, not a single WebGL canvas. Return
+            // the map's canvas renderer surface if one exists, else a detached canvas —
+            // getCanvas() is a WebGL-provider (Mapbox/MapLibre) concept.
+            const found = map.getContainer().querySelector('canvas');
+            return found ?? document.createElement('canvas');
+        },
+        getSnapshot() {
+            return Promise.reject(new Error('@molecule/app-maps-leaflet: getSnapshot() is not supported (Leaflet has no built-in ' +
+                'export). Use a WebGL provider (Mapbox/MapLibre) or the leaflet-image plugin.'));
+        },
+        getInstance() {
+            return map;
+        },
+        destroy() {
+            map.remove();
+        },
+    };
+};
+/**
+ * Creates a Leaflet-backed `MapProvider`.
+ *
+ * @returns A `MapProvider` that renders real OpenStreetMap-tiled maps.
+ */
+export const createProvider = () => ({
+    getName: () => 'leaflet',
+    isLoaded: () => typeof L !== 'undefined' && typeof L.map === 'function',
+    getStyles: () => [{ id: 'osm', name: 'OpenStreetMap', url: OSM_TILES }],
+    createMap(config) {
+        const container = resolveContainer(config.container);
+        const map = L.map(container, {
+            center: config.center ? toLatLng(config.center) : [0, 0],
+            zoom: config.zoom ?? 2,
+            minZoom: config.minZoom,
+            maxZoom: config.maxZoom,
+            scrollWheelZoom: config.scrollZoom ?? true,
+            doubleClickZoom: config.doubleClickZoom ?? true,
+            touchZoom: config.touchZoomRotate ?? true,
+            dragging: config.dragPan ?? true,
+            keyboard: config.keyboard ?? true,
+        });
+        L.tileLayer(OSM_TILES, { attribution: OSM_ATTRIBUTION, maxZoom: 19 }).addTo(map);
+        if (config.maxBounds)
+            map.setMaxBounds(toLeafletBounds(config.maxBounds));
+        return wrapInstance(map);
+    },
+});
+/** The default Leaflet map provider, ready to bond with `setProvider(provider)`. */
+export const provider = createProvider();

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@molecule/app-maps-leaflet",
+  "version": "1.0.0",
+  "description": "Leaflet (OpenStreetMap) provider for @molecule/app-maps",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "maps",
+    "leaflet",
+    "openstreetmap"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "directory": "packages/app/bonds/maps/leaflet"
+  },
+  "peerDependencies": {
+    "@molecule/app-maps": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/app-maps": "1.0.0",
+    "@types/leaflet": "1.9.21",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "dependencies": {
+    "leaflet": "1.9.4"
+  }
+}