@element-editor/adapter-leaflet 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,80 @@
+# @element-editor/adapter-leaflet: guide for coding agents
+
+Adds the Element editing layer (drawing, selection, vertex editing, transform, snapping) to a react-leaflet `MapContainer` you already render. It renders no buttons: toolbars and panels come from `@element-editor/ui`. It is also what the Leaflet drop-in (`@element-editor/react/leaflet`) is built on.
+
+Use it when the app already has a Leaflet map. With no existing map, use the drop-in instead (`@element-editor/react`, MapLibre, or `@element-editor/react/leaflet`): it builds the map and the whole UI. The decision table, ref API, events and error codes are in `node_modules/@element-editor/react/AGENTS.md` (when that package is installed) and at https://elementeditor.dev/docs.
+
+## Install and CSS
+
+```bash
+pnpm add @element-editor/adapter-leaflet @element-editor/ui leaflet react-leaflet
+# types/helpers (FeatureCollection, getFeatureCollectionBBox): pnpm add @element-editor/core
+```
+
+Peers: `react`, `react-dom` `^19.2.0`; `leaflet` `^1.9.0`; `react-leaflet` `^5.0.0` (react-leaflet 4 does not work). Keep all `@element-editor/*` packages on one version and list every one you import from in your `package.json`.
+
+```tsx
+import '@element-editor/adapter-leaflet/style.css' // includes leaflet/dist/leaflet.css
+```
+
+## Example: your map, Element's toolbars
+
+`ElementEditorControls` goes inside `MapContainer` (it uses `useMap()`). The `@element-editor/ui` panels go outside `MapContainer`, as siblings in the same positioned `data-elm-theme` wrapper; inside it, Leaflet would treat their clicks and scrolls as map gestures. `FloatingToolbar`, `LayersPanel` and `DataTablePanel` position themselves against that wrapper; `EditingToolbar` and `ActiveDrawingToolbar` render in place, so give them an absolutely positioned wrapper of your own (adding `--elm-table-offset` keeps them above the open table). `zIndex: 0` on the map keeps Leaflet's panes (z-index 400+) under the panels.
+
+```tsx
+import { Suspense, useRef } from 'react'
+import { MapContainer, TileLayer } from 'react-leaflet'
+import {
+  ElementEditorUIProvider, GeoStoreProvider, ElementEditorControls, type ElementEditorControlsRef,
+} from '@element-editor/adapter-leaflet'
+import type { FeatureCollection } from '@element-editor/core'
+import { FloatingToolbar, EditingToolbar, ActiveDrawingToolbar, LayersPanel, DataTablePanel } from '@element-editor/ui'
+import '@element-editor/adapter-leaflet/style.css'
+
+export default function MyMap({ data }: { data: FeatureCollection | null }) {
+  const editorRef = useRef<ElementEditorControlsRef>(null)
+
+  return (
+    <ElementEditorUIProvider config={{ persistKey: 'my-map' }}>
+      <GeoStoreProvider>
+        <div data-elm-theme="light" style={{ position: 'relative', width: '100%', height: 600, overflow: 'hidden' }}>
+          {/* react-leaflet: center is [lat, lng] */}
+          <MapContainer center={[48.86, 2.35]} zoom={5} style={{ position: 'absolute', inset: 0, zIndex: 0 }}>
+            <TileLayer url="https://tile.openstreetmap.org/{z}/{x}/{y}.png" attribution="&copy; OpenStreetMap contributors" />
+            <ElementEditorControls ref={editorRef} initialData={data} onChange={(fc) => console.log(fc)} />
+          </MapContainer>
+          <FloatingToolbar />
+          {/* Not self-positioned: place them yourself (bottom centre here) */}
+          <div style={{ position: 'absolute', bottom: 'calc(var(--elm-table-offset, 0px) + 16px)', left: '50%', transform: 'translateX(-50%)', zIndex: 400, display: 'flex', gap: 8 }}>
+            <EditingToolbar />
+            <ActiveDrawingToolbar />
+          </div>
+          <LayersPanel />
+          <Suspense fallback={null}><DataTablePanel /></Suspense>
+        </div>
+      </GeoStoreProvider>
+    </ElementEditorUIProvider>
+  )
+}
+```
+
+`editorRef.current` is an `ElementEditorControlsRef`: the same methods as the drop-in's `ElementEditorRef` (`getFeatureCollection`, `setFeatureCollection`, `addFeature`, `select`, `setTool`, `flyTo`, `fitBounds`, `submit`, `undo`, …) without `getBasemap`/`setBasemap`. `getMap()` returns the `L.Map`. All of them take `[lng, lat]`.
+
+## `ElementEditorControls` props
+
+`initialData` (the starting data: applied at mount, or once when it first arrives while the editor is empty and unedited; later changes are ignored, use `setFeatureCollection`; the adapter never moves the map), `schema`, `tools`, `maxFeatures`, `readonly`, `layout` (`'panel' | 'minimal' | 'split'`), `bounds` (bbox `[west, south, east, north]`, `null` clears), `renderer` (`'canvas'` default, or `'svg'`), `getFeatureStyle` (may return Leaflet `PathOptions`), `onReady(map)`, and the callbacks `onChange`, `onSubmit`, `onValidationError`, `onFeatureAdd`, `onFeatureUpdate`, `onFeatureDelete`, `onSelectionChange`, `onFeatureSelect`, `onZoomChange`, `onToolChange`, `onEvent`, `onError`. `routingApiKey` is deprecated (`config.network.routing.apiKey`). There is no `children` prop (unlike the MapLibre adapter).
+
+Theme, accent, `config` (network, layout, units, `persistKey`), `onEvent` and `onError` also go on `ElementEditorUIProvider`.
+
+## Gotchas
+
+- `[lat, lng]` vs `[lng, lat]`: Leaflet and react-leaflet (`center`, `L.latLng`, `getBounds()`) use `[lat, lng]`; Element's data, `bounds` and ref methods use GeoJSON `[lng, lat]`. Convert at the boundary. `toLeaflet` / `toGeoJSON` are exported for that.
+- `ElementEditorUIProvider` is required (`ElementEditorControls` throws without it). One `GeoStoreProvider` per editor, wrapping the `MapContainer`. Everything (map and panels) inside a `data-elm-theme="light" | "dark"` element; for dark mode also set `ThemeContext` from `@element-editor/ui` to the same value.
+- Without the stylesheet, tiles and markers break silently and the UI is unstyled.
+- react-leaflet's `MapContainer` ignores prop changes after mount (`center`, `zoom`, …). Move the map imperatively: `editorRef.current?.flyTo({ center: [lng, lat], zoom })`, `getMap()`, or `useMap()` in a child.
+- Unselected features are drawn on one shared canvas by default; query feature data through the ref (`getFeatureCollection`, `getSelection`), not through `<path>` elements (or pass `renderer="svg"`).
+- Lazy UI (`DataTablePanel`, `SchemaModal`, `GeoJSONModal`, `SettingsModal`, `ShortcutsModal`, `BooleanOperations`) needs its own `<Suspense>` each.
+- Keep `getFeatureStyle` fast and stable (module level or `useCallback`).
+- Next.js: Leaflet touches `window` on import. Load the whole module that imports `react-leaflet` with `next/dynamic` and `ssr: false`, not only `ElementEditorControls`.
+
+Docs: https://elementeditor.dev/docs/quickstart/adapter-leaflet, https://elementeditor.dev/docs/reference/adapter-leaflet, https://elementeditor.dev/docs/guides/custom-ui-with-adapters, https://elementeditor.dev/docs/guides/nextjs. Markdown: append `.md`; everything at once: https://elementeditor.dev/llms-full.txt.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michal Acler and Element Editor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @element-editor/adapter-leaflet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Plug Element drawing and editing tools (vertex editing, snapping, a data table, a GeoJSON inspector, undo/redo) into an existing Leaflet / react-leaflet map. You keep the map; Element adds the editing layer.
+
+## Install
+
+```bash
+npm install @element-editor/adapter-leaflet @element-editor/ui leaflet react-leaflet
+npm install -D @types/leaflet # TypeScript only
+```
+
+Peer dependencies: `react` and `react-dom` `^19.2` (React 18 is not supported), `react-leaflet` `^5`, `leaflet` `^1.9`. `@element-editor/ui` (the toolbars and panels) comes with the adapter; list it yourself when you import from it, because strict package managers (pnpm) only resolve packages you declare. Keep all `@element-editor/*` packages on the same version.
+
+## Quick start
+
+```tsx
+import { MapContainer, TileLayer } from 'react-leaflet'
+import { ElementEditorUIProvider, GeoStoreProvider, ElementEditorControls } from '@element-editor/adapter-leaflet'
+import '@element-editor/adapter-leaflet/style.css' // includes Leaflet's CSS
+
+export default function MyMap() {
+  return (
+    <ElementEditorUIProvider>
+      <GeoStoreProvider>
+        <div data-elm-theme="light">
+          <MapContainer center={[48.86, 2.35]} zoom={12} style={{ height: 600 }}>
+            <TileLayer url="https://tile.openstreetmap.org/{z}/{x}/{y}.png" />
+            <ElementEditorControls onChange={(data) => console.log(data)} />
+          </MapContainer>
+        </div>
+      </GeoStoreProvider>
+    </ElementEditorUIProvider>
+  )
+}
+```
+
+`ElementEditorUIProvider` supplies the contexts the editor needs (and renders its own toast `<Toaster>`); `ElementEditorControls` throws without it. The `data-elm-theme` element scopes the editor's styles (the stylesheet doesn't reset your page) and its keyboard shortcuts.
+
+## Documentation
+
+- [Quick start](https://elementeditor.dev/docs/quickstart/adapter-leaflet)
+- [Adapter API reference](https://elementeditor.dev/docs/reference/adapter-leaflet)
+- [Custom UI with adapters](https://elementeditor.dev/docs/guides/custom-ui-with-adapters) · [Next.js](https://elementeditor.dev/docs/guides/nextjs)
+- [All docs](https://elementeditor.dev/docs) · [Changelog](https://github.com/spatibase/element/blob/main/CHANGELOG.md) · [Issues](https://github.com/spatibase/element/issues)
+
+MIT licence.

package/dist/ElementEditorControls.d.cts

@@ -0,0 +1,111 @@
+import { Map as LeafletMap } from 'leaflet';
+import { BoundsInput, FeatureCollection, FeatureCollectionInput, GeoJSONFeature, GeoJSONFeatureInput, Schema } from '@element-editor/core';
+import { ElementEditorImperativeAPI, ImportResult, ElementEditorEvent, ElementEditorErrorHandler } from '@element-editor/ui';
+import { FeatureRenderer } from './components/FeatureInteractionLayer.cjs';
+import { FeatureStyleFn } from './contexts/FeatureStyleContext.cjs';
+export type DrawingTool = 'polygon' | 'rectangle' | 'circle' | 'line' | 'point' | 'freehand' | 'route' | 'picker' | 'measure' | 'search';
+export type { ImportResult };
+/** Imperative handle exposed via `ref`. Same surface across adapters and `@element-editor/react`; `getMap()` returns the `L.Map`. */
+export type ElementEditorControlsRef = ElementEditorImperativeAPI<LeafletMap>;
+export interface ElementEditorControlsProps {
+    /** Pre-populate the editor with an existing FeatureCollection. Applied once on mount. */
+    initialData?: FeatureCollectionInput | GeoJSONFeatureInput | null;
+    /**
+     * Optional single Schema pushed into the store on mount. Safe to pass a
+     * stable object — re-renders that keep the same `schema.id` are no-ops.
+     */
+    schema?: Schema;
+    /** Called after every committed change with the full current FeatureCollection. */
+    onChange?: (data: FeatureCollection) => void;
+    /**
+     * Called by `ref.submit()` when all features pass validation. Receives a
+     * clean FeatureCollection (stripped of `_validation`).
+     */
+    onSubmit?: (data: FeatureCollection) => void;
+    /**
+     * Called by `ref.submit()` when one or more features have validation
+     * errors. Blocks `onSubmit` from firing.
+     */
+    onValidationError?: (errors: Record<string, string[]>) => void;
+    /**
+     * Receives every message the editor would show the user: `feature:deleted` / `features:deleted`
+     * (with `undo`), `feature:duplicated` / `features:duplicated`, `feature:broken`,
+     * `selection:copied`, `selection:pasted`, `undo`, `redo`, `error`, `warning` and `success`.
+     * When provided, the built-in toasts are suppressed: display them yourself. Tool changes and data
+     * commits are not events (use `onToolChange` and `onChange`). Wraps an EventProvider locally so
+     * you don't need a separate `<ElementEditorUIProvider onEvent={...}>`.
+     */
+    onEvent?: (event: ElementEditorEvent) => void;
+    /**
+     * Called first for every runtime failure with an `ElementEditorError` (`code`, `source`, honest
+     * English `message`): basemap, picker, routing, search, import, geometry, clipboard, `maxFeatures`.
+     * Return `false` to stop the built-in toast / `onEvent` error event, or a string to show that text
+     * instead. Wraps a local EventProvider (with `onEvent`) or hands on to the enclosing one.
+     */
+    onError?: ElementEditorErrorHandler;
+    /**
+     * Structural layout hint read by `@element-editor/ui` panels (LayersPanel,
+     * DataTablePanel, etc.). `'panel'` keeps the sidebar docked; `'split'`
+     * reserves the lower third for the data table; `'minimal'` hides them.
+     */
+    layout?: 'panel' | 'minimal' | 'split';
+    /** Restrict which drawing tools are available. Omit to allow all. */
+    tools?: DrawingTool[];
+    /** Maximum number of features allowed. Drawing is disabled when reached. */
+    maxFeatures?: number;
+    /** When true, all editing interactions are disabled. */
+    readonly?: boolean;
+    /** Called when a feature is added. */
+    onFeatureAdd?: (feature: GeoJSONFeature) => void;
+    /** Called when a feature's geometry or properties are updated. */
+    onFeatureUpdate?: (id: string, feature: GeoJSONFeature) => void;
+    /** Called when a feature is deleted. */
+    onFeatureDelete?: (id: string) => void;
+    /** Called when the selection changes. Fires with the array of selected feature ids. */
+    onSelectionChange?: (ids: string[]) => void;
+    /**
+     * Called with the single selected feature (or `null` when deselected or
+     * multi-selected). Convenience variant of `onSelectionChange` that gives
+     * you the full GeoJSONFeature for the common single-selection case.
+     */
+    onFeatureSelect?: (feature: GeoJSONFeature | null) => void;
+    /** Called when the map's zoom level changes. */
+    onZoomChange?: (zoom: number) => void;
+    /** Called with the tool that turned on (as `ref.getTool()` reports it), or `null` when it turned off. */
+    onToolChange?: (tool: DrawingTool | null) => void;
+    /**
+     * Leaflet max-bounds. When set, the user can't pan the map outside this box.
+     * A GeoJSON bbox `[west, south, east, north]`. The older `[[south, west], [north, east]]`
+     * form still works but is deprecated (dev warning). `null` clears.
+     */
+    bounds?: BoundsInput | null;
+    /** @deprecated Use `config.network.routing.apiKey` (it wins over this). OpenRouteService key for the Route tool. */
+    routingApiKey?: string;
+    /**
+     * Returns Leaflet PathOptions for a given feature (or `undefined`/`null` for the default look),
+     * applied to polygons, polylines and point pins (pins use `fillColor`, then `color`).
+     * `fillColor` falls back to `color`. Wins over `config.featureColor` per key; the selected /
+     * hovered looks win over both. Called on every render — keep it fast (no heavy computation inside).
+     *
+     * @example
+     * getFeatureStyle={(f) => ({
+     *   color: f.properties.color ?? '#475569',
+     *   fillOpacity: f.properties.opacity ?? 0.15,
+     * })}
+     */
+    getFeatureStyle?: FeatureStyleFn;
+    /**
+     * How unselected features are drawn. `'canvas'` (default) paints them on one
+     * shared `<canvas>`, which keeps panning and zooming smooth with thousands of
+     * features. `'svg'` gives every feature its own `<path>` element (useful if
+     * your app styles or queries feature paths via CSS/DOM). Selected features and
+     * editing handles are always SVG either way.
+     */
+    renderer?: FeatureRenderer;
+    /**
+     * Called once per map, as soon as Element's layers and panes are on it: the place to add your
+     * own layers.
+     */
+    onReady?: (map: LeafletMap) => void;
+}
+export declare const ElementEditorControls: import('react').ForwardRefExoticComponent<ElementEditorControlsProps & import('react').RefAttributes<ElementEditorControlsRef>>;

package/dist/ElementEditorControls.d.ts

@@ -0,0 +1,111 @@
+import { Map as LeafletMap } from 'leaflet';
+import { BoundsInput, FeatureCollection, FeatureCollectionInput, GeoJSONFeature, GeoJSONFeatureInput, Schema } from '@element-editor/core';
+import { ElementEditorImperativeAPI, ImportResult, ElementEditorEvent, ElementEditorErrorHandler } from '@element-editor/ui';
+import { FeatureRenderer } from './components/FeatureInteractionLayer.js';
+import { FeatureStyleFn } from './contexts/FeatureStyleContext.js';
+export type DrawingTool = 'polygon' | 'rectangle' | 'circle' | 'line' | 'point' | 'freehand' | 'route' | 'picker' | 'measure' | 'search';
+export type { ImportResult };
+/** Imperative handle exposed via `ref`. Same surface across adapters and `@element-editor/react`; `getMap()` returns the `L.Map`. */
+export type ElementEditorControlsRef = ElementEditorImperativeAPI<LeafletMap>;
+export interface ElementEditorControlsProps {
+    /** Pre-populate the editor with an existing FeatureCollection. Applied once on mount. */
+    initialData?: FeatureCollectionInput | GeoJSONFeatureInput | null;
+    /**
+     * Optional single Schema pushed into the store on mount. Safe to pass a
+     * stable object — re-renders that keep the same `schema.id` are no-ops.
+     */
+    schema?: Schema;
+    /** Called after every committed change with the full current FeatureCollection. */
+    onChange?: (data: FeatureCollection) => void;
+    /**
+     * Called by `ref.submit()` when all features pass validation. Receives a
+     * clean FeatureCollection (stripped of `_validation`).
+     */
+    onSubmit?: (data: FeatureCollection) => void;
+    /**
+     * Called by `ref.submit()` when one or more features have validation
+     * errors. Blocks `onSubmit` from firing.
+     */
+    onValidationError?: (errors: Record<string, string[]>) => void;
+    /**
+     * Receives every message the editor would show the user: `feature:deleted` / `features:deleted`
+     * (with `undo`), `feature:duplicated` / `features:duplicated`, `feature:broken`,
+     * `selection:copied`, `selection:pasted`, `undo`, `redo`, `error`, `warning` and `success`.
+     * When provided, the built-in toasts are suppressed: display them yourself. Tool changes and data
+     * commits are not events (use `onToolChange` and `onChange`). Wraps an EventProvider locally so
+     * you don't need a separate `<ElementEditorUIProvider onEvent={...}>`.
+     */
+    onEvent?: (event: ElementEditorEvent) => void;
+    /**
+     * Called first for every runtime failure with an `ElementEditorError` (`code`, `source`, honest
+     * English `message`): basemap, picker, routing, search, import, geometry, clipboard, `maxFeatures`.
+     * Return `false` to stop the built-in toast / `onEvent` error event, or a string to show that text
+     * instead. Wraps a local EventProvider (with `onEvent`) or hands on to the enclosing one.
+     */
+    onError?: ElementEditorErrorHandler;
+    /**
+     * Structural layout hint read by `@element-editor/ui` panels (LayersPanel,
+     * DataTablePanel, etc.). `'panel'` keeps the sidebar docked; `'split'`
+     * reserves the lower third for the data table; `'minimal'` hides them.
+     */
+    layout?: 'panel' | 'minimal' | 'split';
+    /** Restrict which drawing tools are available. Omit to allow all. */
+    tools?: DrawingTool[];
+    /** Maximum number of features allowed. Drawing is disabled when reached. */
+    maxFeatures?: number;
+    /** When true, all editing interactions are disabled. */
+    readonly?: boolean;
+    /** Called when a feature is added. */
+    onFeatureAdd?: (feature: GeoJSONFeature) => void;
+    /** Called when a feature's geometry or properties are updated. */
+    onFeatureUpdate?: (id: string, feature: GeoJSONFeature) => void;
+    /** Called when a feature is deleted. */
+    onFeatureDelete?: (id: string) => void;
+    /** Called when the selection changes. Fires with the array of selected feature ids. */
+    onSelectionChange?: (ids: string[]) => void;
+    /**
+     * Called with the single selected feature (or `null` when deselected or
+     * multi-selected). Convenience variant of `onSelectionChange` that gives
+     * you the full GeoJSONFeature for the common single-selection case.
+     */
+    onFeatureSelect?: (feature: GeoJSONFeature | null) => void;
+    /** Called when the map's zoom level changes. */
+    onZoomChange?: (zoom: number) => void;
+    /** Called with the tool that turned on (as `ref.getTool()` reports it), or `null` when it turned off. */
+    onToolChange?: (tool: DrawingTool | null) => void;
+    /**
+     * Leaflet max-bounds. When set, the user can't pan the map outside this box.
+     * A GeoJSON bbox `[west, south, east, north]`. The older `[[south, west], [north, east]]`
+     * form still works but is deprecated (dev warning). `null` clears.
+     */
+    bounds?: BoundsInput | null;
+    /** @deprecated Use `config.network.routing.apiKey` (it wins over this). OpenRouteService key for the Route tool. */
+    routingApiKey?: string;
+    /**
+     * Returns Leaflet PathOptions for a given feature (or `undefined`/`null` for the default look),
+     * applied to polygons, polylines and point pins (pins use `fillColor`, then `color`).
+     * `fillColor` falls back to `color`. Wins over `config.featureColor` per key; the selected /
+     * hovered looks win over both. Called on every render — keep it fast (no heavy computation inside).
+     *
+     * @example
+     * getFeatureStyle={(f) => ({
+     *   color: f.properties.color ?? '#475569',
+     *   fillOpacity: f.properties.opacity ?? 0.15,
+     * })}
+     */
+    getFeatureStyle?: FeatureStyleFn;
+    /**
+     * How unselected features are drawn. `'canvas'` (default) paints them on one
+     * shared `<canvas>`, which keeps panning and zooming smooth with thousands of
+     * features. `'svg'` gives every feature its own `<path>` element (useful if
+     * your app styles or queries feature paths via CSS/DOM). Selected features and
+     * editing handles are always SVG either way.
+     */
+    renderer?: FeatureRenderer;
+    /**
+     * Called once per map, as soon as Element's layers and panes are on it: the place to add your
+     * own layers.
+     */
+    onReady?: (map: LeafletMap) => void;
+}
+export declare const ElementEditorControls: import('react').ForwardRefExoticComponent<ElementEditorControlsProps & import('react').RefAttributes<ElementEditorControlsRef>>;