@element-editor/react 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +429 -0
- package/LICENSE +21 -0
- package/README.md +49 -2
- package/dist/element-editor-leaflet.css +1 -0
- package/dist/element-editor.cjs +1 -0
- package/dist/element-editor.css +1 -0
- package/dist/element-editor.es.js +178 -0
- package/dist/index.d.cts +4 -0
- package/dist/index.d.ts +4 -0
- package/dist/leaflet/CompactAttribution.d.cts +23 -0
- package/dist/leaflet/CompactAttribution.d.ts +23 -0
- package/dist/leaflet/ElementEditor.d.cts +81 -0
- package/dist/leaflet/ElementEditor.d.ts +81 -0
- package/dist/leaflet/MapView.d.cts +28 -0
- package/dist/leaflet/MapView.d.ts +28 -0
- package/dist/leaflet/index.d.cts +3 -0
- package/dist/leaflet/index.d.ts +3 -0
- package/dist/leaflet.cjs +1 -0
- package/dist/leaflet.d.cts +2 -0
- package/dist/leaflet.d.ts +2 -0
- package/dist/leaflet.es.js +181 -0
- package/dist/maplibre/ElementEditor.d.cts +68 -0
- package/dist/maplibre/ElementEditor.d.ts +68 -0
- package/dist/maplibre/MapLibreMapView.d.cts +34 -0
- package/dist/maplibre/MapLibreMapView.d.ts +34 -0
- package/dist/maplibre/index.d.cts +2 -0
- package/dist/maplibre/index.d.ts +2 -0
- package/dist/shared.d.cts +13 -0
- package/dist/shared.d.ts +13 -0
- package/dist/shell/ElementEditorShell.d.cts +32 -0
- package/dist/shell/ElementEditorShell.d.ts +32 -0
- package/dist/shell/FileDropBox.d.cts +13 -0
- package/dist/shell/FileDropBox.d.ts +13 -0
- package/dist/shell/ShellControl.d.cts +19 -0
- package/dist/shell/ShellControl.d.ts +19 -0
- package/dist/shell/ShellPanels.d.cts +13 -0
- package/dist/shell/ShellPanels.d.ts +13 -0
- package/dist/shell/savedView.d.cts +49 -0
- package/dist/shell/savedView.d.ts +49 -0
- package/dist/shell/types.d.cts +253 -0
- package/dist/shell/types.d.ts +253 -0
- package/dist/shell/useAttributionAutoCollapse.d.cts +17 -0
- package/dist/shell/useAttributionAutoCollapse.d.ts +17 -0
- package/dist/shell/useBasemapState.d.cts +20 -0
- package/dist/shell/useBasemapState.d.ts +20 -0
- package/dist/shell/useDevChecks.d.cts +11 -0
- package/dist/shell/useDevChecks.d.ts +11 -0
- package/dist/shell/useResolvedTheme.d.cts +14 -0
- package/dist/shell/useResolvedTheme.d.ts +14 -0
- package/dist/shell/useSlotAutoLayout.d.cts +23 -0
- package/dist/shell/useSlotAutoLayout.d.ts +23 -0
- package/dist/store/StoreContext.d.cts +1 -0
- package/dist/store/StoreContext.d.ts +1 -0
- package/dist/types/geojson.d.cts +1 -0
- package/dist/types/geojson.d.ts +1 -0
- package/dist/useBasemapState-8bWJK84f.cjs +1 -0
- package/dist/useBasemapState-DChxz3lv.js +682 -0
- package/package.json +150 -3
package/AGENTS.md
ADDED
|
@@ -0,0 +1,429 @@
|
|
|
1
|
+
# @element-editor/react: guide for coding agents
|
|
2
|
+
|
|
3
|
+
Element is a React map editor for GeoJSON: drawing tools, vertex editing, snapping, boolean ops, a schema-driven property form, a data table and a GeoJSON inspector. This package is the drop-in `<ElementEditor />`: it creates and owns the map. Everything below is checked against the types in `dist/*.d.ts`; when in doubt, those win.
|
|
4
|
+
|
|
5
|
+
Full docs: https://elementeditor.dev/docs. For agents: https://elementeditor.dev/llms.txt (index) and https://elementeditor.dev/llms-full.txt (all docs in one file). Every docs page is also served as markdown at the same URL plus `.md` (e.g. https://elementeditor.dev/docs/guides/basemaps.md).
|
|
6
|
+
|
|
7
|
+
## Pick the package
|
|
8
|
+
|
|
9
|
+
| Situation | Import from | Map engine |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| No map yet, want a complete editor (default choice) | `@element-editor/react` | MapLibre GL, created by Element |
|
|
12
|
+
| No map yet, must be Leaflet | `@element-editor/react/leaflet` | Leaflet, created by Element |
|
|
13
|
+
| Existing `maplibregl.Map` (also MapTiler SDK; Mapbox GL with an `as any` cast) | `@element-editor/adapter-maplibre` + `@element-editor/ui` | yours |
|
|
14
|
+
| Existing react-leaflet `MapContainer` | `@element-editor/adapter-leaflet` + `@element-editor/ui` | yours |
|
|
15
|
+
| Types, stores, helpers only (no UI) | `@element-editor/core` | none |
|
|
16
|
+
|
|
17
|
+
The adapters render no buttons; you place toolbars and panels from `@element-editor/ui` yourself. Each adapter package has its own `AGENTS.md`. Pick MapLibre unless you need Leaflet: the Leaflet drop-in has raster basemaps only.
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
React and React DOM `^19.2` are required everywhere (React 18 is not supported). The engine peers are optional peers, so npm/pnpm will not install them for you.
|
|
22
|
+
|
|
23
|
+
| Entry | pnpm | npm |
|
|
24
|
+
|---|---|---|
|
|
25
|
+
| `@element-editor/react` | `pnpm add @element-editor/react maplibre-gl` | `npm install @element-editor/react maplibre-gl` |
|
|
26
|
+
| `@element-editor/react/leaflet` | `pnpm add @element-editor/react @element-editor/adapter-leaflet leaflet react-leaflet` | `npm install @element-editor/react @element-editor/adapter-leaflet leaflet react-leaflet` |
|
|
27
|
+
| MapLibre adapter | `pnpm add @element-editor/adapter-maplibre @element-editor/ui maplibre-gl` | `npm install @element-editor/adapter-maplibre @element-editor/ui maplibre-gl` |
|
|
28
|
+
| Leaflet adapter | `pnpm add @element-editor/adapter-leaflet @element-editor/ui leaflet react-leaflet` | `npm install @element-editor/adapter-leaflet @element-editor/ui leaflet react-leaflet` |
|
|
29
|
+
|
|
30
|
+
| Peer | Range |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `react`, `react-dom` | `^19.2.0` |
|
|
33
|
+
| `maplibre-gl` | `^5.5.0` (default entry, MapLibre adapter) |
|
|
34
|
+
| `leaflet` | `^1.9.0` (`/leaflet` entry, Leaflet adapter) |
|
|
35
|
+
| `react-leaflet` | `^5.0.0` (`/leaflet` entry, Leaflet adapter) |
|
|
36
|
+
|
|
37
|
+
`@element-editor/react` brings `@element-editor/core`, `@element-editor/ui` and `@element-editor/adapter-maplibre` as dependencies and re-exports the common types, so you rarely import those directly. With pnpm, add any `@element-editor/*` package you import from to your own `package.json`, on the same version.
|
|
38
|
+
|
|
39
|
+
## CSS
|
|
40
|
+
|
|
41
|
+
Import exactly one stylesheet, once (app entry or root layout). The JS entries import no CSS.
|
|
42
|
+
|
|
43
|
+
| Entry | Stylesheet | Includes the engine's CSS |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| `@element-editor/react` | `@element-editor/react/style.css` | yes (`maplibre-gl.css`) |
|
|
46
|
+
| `@element-editor/react/leaflet` | `@element-editor/react/leaflet/style.css` | yes (`leaflet.css`) |
|
|
47
|
+
| `@element-editor/adapter-maplibre` | `@element-editor/adapter-maplibre/style.css` | no: also import `maplibre-gl/dist/maplibre-gl.css` |
|
|
48
|
+
| `@element-editor/adapter-leaflet` | `@element-editor/adapter-leaflet/style.css` | yes (`leaflet.css`) |
|
|
49
|
+
|
|
50
|
+
The stylesheets do not reset your page; base styles apply only inside `[data-elm-theme]` (the drop-ins set it on their root). Mixing them up (MapLibre component + Leaflet stylesheet) gives a broken map with no error.
|
|
51
|
+
|
|
52
|
+
## Theming
|
|
53
|
+
|
|
54
|
+
`theme` is the mode only. Everything visual is CSS variables on the editor root (`[data-elm-theme]`), per mode, through your stylesheet or `style`; Element copies them onto its portals (modals, menus, tooltips, toasts) itself. Never restyle Tailwind class names.
|
|
55
|
+
|
|
56
|
+
- Brand: `--elm-accent` (or the `accentColor` prop) derives every accent shade; `--elm-primary-50…950` pins one.
|
|
57
|
+
- Design tokens: `--elm-font`, `--elm-font-mono`, `--elm-radius` (containers, 12px), `--elm-radius-control` (buttons/inputs, 6px), `--elm-shadow`, `--elm-shadow-raised`, `--elm-shadow-control`, `--elm-surface`, `--elm-surface-raised`, `--elm-surface-sunken`, `--elm-surface-hover`, `--elm-control-hover`, `--elm-text`, `--elm-text-secondary`, `--elm-text-muted`, `--elm-text-subtle`, `--elm-text-disabled`, `--elm-border`, `--elm-border-subtle`, `--elm-border-strong`, `--elm-focus-ring`, `--elm-tooltip`, `--elm-tooltip-text`.
|
|
58
|
+
- Rows (layers list + data table, opaque): `--elm-row-hover`, `--elm-row-selected`, `--elm-row-selected-hover`, `--elm-row-checked`, `--elm-row-checked-hover`.
|
|
59
|
+
- Map features are props, not tokens: `featureColor`, `getFeatureStyle`.
|
|
60
|
+
|
|
61
|
+
```css
|
|
62
|
+
.brand-editor[data-elm-theme] { --elm-accent: #c0582b; --elm-radius: 16px; --elm-font: "Inter", sans-serif; }
|
|
63
|
+
.brand-editor[data-elm-theme="light"] { --elm-surface: #fbf6ee; --elm-text: #3b2a1e; --elm-border: #e5d6c0; }
|
|
64
|
+
.brand-editor[data-elm-theme="dark"] { --elm-surface: #2a211b; --elm-text: #f6ece0; --elm-border: #4a3b30; }
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
```tsx
|
|
68
|
+
import { ElementEditor } from '@element-editor/react'
|
|
69
|
+
|
|
70
|
+
<ElementEditor className="brand-editor" />
|
|
71
|
+
// or inline, one value for both modes:
|
|
72
|
+
<ElementEditor style={{ '--elm-surface': '#fbf6ee', '--elm-text': '#3b2a1e' }} />
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Defaults and roles: https://elementeditor.dev/docs/guides/theming
|
|
76
|
+
|
|
77
|
+
## Minimal examples
|
|
78
|
+
|
|
79
|
+
The editor root is `width: 100%; height: 100%` of its parent: the parent needs a real height.
|
|
80
|
+
|
|
81
|
+
### MapLibre drop-in (default)
|
|
82
|
+
|
|
83
|
+
```tsx
|
|
84
|
+
import { ElementEditor, type FeatureCollection } from '@element-editor/react'
|
|
85
|
+
import '@element-editor/react/style.css'
|
|
86
|
+
|
|
87
|
+
const saved = localStorage.getItem('my-map')
|
|
88
|
+
|
|
89
|
+
export default function App() {
|
|
90
|
+
return (
|
|
91
|
+
<div style={{ width: '100%', height: '100vh' }}>
|
|
92
|
+
<ElementEditor
|
|
93
|
+
initialData={saved ? (JSON.parse(saved) as FeatureCollection) : null}
|
|
94
|
+
initialView={{ center: [14.42, 50.09], zoom: 12 }} // [lng, lat]
|
|
95
|
+
onChange={(data) => localStorage.setItem('my-map', JSON.stringify(data))}
|
|
96
|
+
/>
|
|
97
|
+
</div>
|
|
98
|
+
)
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Leaflet drop-in
|
|
103
|
+
|
|
104
|
+
Same component API; `tileLayer`, `renderer` and raster-only `basemaps` are Leaflet-specific.
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
import { ElementEditor } from '@element-editor/react/leaflet'
|
|
108
|
+
import '@element-editor/react/leaflet/style.css'
|
|
109
|
+
|
|
110
|
+
export default function App() {
|
|
111
|
+
return (
|
|
112
|
+
<div style={{ width: '100%', height: 600 }}>
|
|
113
|
+
<ElementEditor
|
|
114
|
+
initialView={{ center: [2.35, 48.86], zoom: 11 }} // still [lng, lat]
|
|
115
|
+
onChange={(data) => console.log(data.features.length)}
|
|
116
|
+
/>
|
|
117
|
+
</div>
|
|
118
|
+
)
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Existing MapLibre map (adapter)
|
|
123
|
+
|
|
124
|
+
Needs `ElementEditorUIProvider` (throws without it), one `GeoStoreProvider` per editor, and a `data-elm-theme` element around the map. `ElementEditorControls` adds layers to your map and renders no visible UI; pass `@element-editor/ui` components as its `children` to get toolbars and panels (see `node_modules/@element-editor/adapter-maplibre/AGENTS.md`).
|
|
125
|
+
|
|
126
|
+
```tsx
|
|
127
|
+
import { useEffect, useRef, useState } from 'react'
|
|
128
|
+
import maplibregl from 'maplibre-gl'
|
|
129
|
+
import 'maplibre-gl/dist/maplibre-gl.css'
|
|
130
|
+
import { ElementEditorUIProvider, GeoStoreProvider, ElementEditorControls } from '@element-editor/adapter-maplibre'
|
|
131
|
+
import '@element-editor/adapter-maplibre/style.css'
|
|
132
|
+
|
|
133
|
+
export default function MyMap() {
|
|
134
|
+
const containerRef = useRef<HTMLDivElement>(null)
|
|
135
|
+
const [map, setMap] = useState<maplibregl.Map | null>(null)
|
|
136
|
+
|
|
137
|
+
useEffect(() => {
|
|
138
|
+
if (!containerRef.current) return
|
|
139
|
+
const m = new maplibregl.Map({
|
|
140
|
+
container: containerRef.current,
|
|
141
|
+
style: 'https://demotiles.maplibre.org/style.json',
|
|
142
|
+
center: [2.35, 48.86],
|
|
143
|
+
zoom: 5,
|
|
144
|
+
})
|
|
145
|
+
m.on('load', () => setMap(m))
|
|
146
|
+
return () => { setMap(null); m.remove() }
|
|
147
|
+
}, [])
|
|
148
|
+
|
|
149
|
+
return (
|
|
150
|
+
<ElementEditorUIProvider>
|
|
151
|
+
<GeoStoreProvider>
|
|
152
|
+
<div data-elm-theme="light" style={{ position: 'relative', width: '100%', height: 600 }}>
|
|
153
|
+
<div ref={containerRef} style={{ width: '100%', height: '100%' }} />
|
|
154
|
+
{map && <ElementEditorControls map={map} onChange={(data) => console.log(data)} />}
|
|
155
|
+
</div>
|
|
156
|
+
</GeoStoreProvider>
|
|
157
|
+
</ElementEditorUIProvider>
|
|
158
|
+
)
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Existing Leaflet map (adapter)
|
|
163
|
+
|
|
164
|
+
Same three wrappers (`ElementEditorUIProvider`, `GeoStoreProvider`, `data-elm-theme` element), imported from `@element-editor/adapter-leaflet`, with `@element-editor/adapter-leaflet/style.css` (includes Leaflet's CSS). `ElementEditorControls` takes no `map` prop: render it as a child of react-leaflet's `MapContainer` (it calls `useMap()`), and render `@element-editor/ui` panels outside `MapContainer`. `MapContainer center` is `[lat, lng]`. Full example: `node_modules/@element-editor/adapter-leaflet/AGENTS.md`.
|
|
165
|
+
|
|
166
|
+
## Next.js (App Router)
|
|
167
|
+
|
|
168
|
+
All entries start with `'use client'`, but the map libraries still need the DOM (Leaflet touches `window` on import). Rules:
|
|
169
|
+
|
|
170
|
+
1. Load the editor with `next/dynamic` and `ssr: false`, inside a `'use client'` component (`ssr: false` is not allowed in Server Components).
|
|
171
|
+
2. Import the stylesheet in `app/layout.tsx`, not in the dynamically loaded component.
|
|
172
|
+
3. `react`/`react-dom` `^19.2`; works with Next.js 15 and 16. No `transpilePackages`, worker or webpack config needed. Do not override `react-data-grid` (pinned to `7.0.0-beta.57` for Next.js 15).
|
|
173
|
+
|
|
174
|
+
```tsx
|
|
175
|
+
// app/components/MapEditor.tsx
|
|
176
|
+
'use client'
|
|
177
|
+
|
|
178
|
+
import dynamic from 'next/dynamic'
|
|
179
|
+
|
|
180
|
+
const ElementEditor = dynamic(
|
|
181
|
+
() => import('@element-editor/react').then((m) => m.ElementEditor), // or '@element-editor/react/leaflet'
|
|
182
|
+
{ ssr: false, loading: () => <div style={{ height: '100vh' }}>Loading map...</div> },
|
|
183
|
+
)
|
|
184
|
+
|
|
185
|
+
export default function MapEditor() {
|
|
186
|
+
return (
|
|
187
|
+
<div style={{ width: '100%', height: '100vh' }}>
|
|
188
|
+
<ElementEditor onChange={console.log} />
|
|
189
|
+
</div>
|
|
190
|
+
)
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
```tsx
|
|
195
|
+
// app/layout.tsx
|
|
196
|
+
import '@element-editor/react/style.css' // '@element-editor/react/leaflet/style.css' for the Leaflet entry
|
|
197
|
+
|
|
198
|
+
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
|
199
|
+
return (
|
|
200
|
+
<html lang="en">
|
|
201
|
+
<body>{children}</body>
|
|
202
|
+
</html>
|
|
203
|
+
)
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
If you need a ref, `onMapReady`, or an adapter, write your own client component that imports Element statically and load that whole module with `dynamic(() => import('./ProjectEditor'), { ssr: false })`. Pages Router: same `dynamic` call, CSS in `pages/_app.tsx`.
|
|
208
|
+
|
|
209
|
+
## Loading and saving data
|
|
210
|
+
|
|
211
|
+
- `initialData` (`FeatureCollectionInput | GeoJSONFeatureInput | null`) is applied once: at mount, or, if it is `null`/`undefined`/empty at mount, the first time it becomes data while the editor is still empty and unedited (so `fetch` → `setState` → `initialData={data}` works). Later changes are ignored, with a dev warning. Loading it never fires `onChange`. Standard `@types/geojson` data type-checks (3D positions, 6-number bbox, `GeometryCollection`; null-geometry features are skipped and reported via `onError`). A plain RFC 7946 collection is fine: missing ids get UUIDs, a single Feature is wrapped. Invalid input reports an `'invalid-data'` error and the editor starts empty.
|
|
212
|
+
- Data that arrives after mount: render the editor once it has loaded (`data ? <ElementEditor initialData={data} /> : <Spinner />`), pass it as `initialData` once it arrives (see above), or call `ref.current?.setFeatureCollection(data, { silent: true })` (replace; keeps zoom; one undo step, or `undoable: false` to start a fresh history; `silent` skips `onChange`/`onFeature*` so loading from your backend doesn't echo a save). `ref.current?.importGeoJSON(data, 'merge')` appends.
|
|
213
|
+
- Clean slate for another project: remount with `key={projectId}`.
|
|
214
|
+
- Saving: `onChange(data: FeatureCollection)` fires after every committed edit (once at the end of a drag, not during it) with the full collection, including `metadata.schemas` / `metadata.groups`. Store it as is and pass it back as `initialData`.
|
|
215
|
+
- Large datasets: `onFeatureAdd` / `onFeatureUpdate` / `onFeatureDelete` give per-feature deltas.
|
|
216
|
+
- Save button instead of autosave: pass `onSubmit` (renders an "Apply changes" button; `onValidationError` gets schema errors keyed by feature id), or read `ref.current?.getFeatureCollection()` from your own button.
|
|
217
|
+
|
|
218
|
+
```tsx
|
|
219
|
+
import { useRef } from 'react'
|
|
220
|
+
import { ElementEditor, type ElementEditorRef, type FeatureCollectionInput } from '@element-editor/react'
|
|
221
|
+
import '@element-editor/react/style.css'
|
|
222
|
+
|
|
223
|
+
export function ProjectEditor({ initial }: { initial: FeatureCollectionInput | null }) {
|
|
224
|
+
const ref = useRef<ElementEditorRef>(null)
|
|
225
|
+
|
|
226
|
+
async function openProject(id: string) {
|
|
227
|
+
const res = await fetch(`/api/projects/${id}`)
|
|
228
|
+
ref.current?.setFeatureCollection((await res.json()) as FeatureCollectionInput, { silent: true })
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
async function save() {
|
|
232
|
+
const data = ref.current?.getFeatureCollection()
|
|
233
|
+
if (data) await fetch('/api/projects/current', { method: 'PUT', body: JSON.stringify(data) })
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
return (
|
|
237
|
+
<>
|
|
238
|
+
<div style={{ height: 600 }}>
|
|
239
|
+
<ElementEditor ref={ref} initialData={initial} />
|
|
240
|
+
</div>
|
|
241
|
+
<button onClick={() => openProject('42')}>Open</button>
|
|
242
|
+
<button onClick={save}>Save</button>
|
|
243
|
+
</>
|
|
244
|
+
)
|
|
245
|
+
}
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
## Ref API
|
|
249
|
+
|
|
250
|
+
`ElementEditorRef` from `@element-editor/react` (`getMap()` returns `maplibregl.Map`) or from `@element-editor/react/leaflet` (`L.Map`, basemap type `LeafletBasemap`). The adapters' `ElementEditorControlsRef` has the same methods minus `getBasemap`/`setBasemap`. Coordinates are `[lng, lat]`. `flyTo`, `fitBounds` and `select(ids, { fit: true })` frame the target in the part of the map the panels leave visible, so `map.getCenter()` can differ from the requested centre. Data methods work in `readonly` too, run the same store actions as user edits (undo, `maxFeatures`, validation) and fire the callbacks synchronously before returning. Map methods do nothing until the map has mounted.
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
interface ElementEditorRef {
|
|
254
|
+
getFeatureCollection: () => FeatureCollection
|
|
255
|
+
getFeature: (id: string) => GeoJSONFeature | null
|
|
256
|
+
setFeatureCollection: (data: FeatureCollectionInput, options?: SetFeatureCollectionOptions) => void // replace
|
|
257
|
+
exportGeoJSON: () => string
|
|
258
|
+
exportAs: (format: 'geojson') => void // browser download
|
|
259
|
+
importGeoJSON: (raw: FeatureCollectionInput | unknown, mode?: 'replace' | 'merge') => ImportResult
|
|
260
|
+
updateFeatures: (updates: ReadonlyArray<{ id: string; patch: FeaturePatch }>, options?: MutationOptions) => void
|
|
261
|
+
addFeature: (feature: GeoJSONFeatureInput, options?: MutationOptions) => GeoJSONFeature | null
|
|
262
|
+
updateFeature: (id: string, patch: FeaturePatch, options?: MutationOptions) => boolean
|
|
263
|
+
removeFeatures: (ids: string[], options?: MutationOptions) => number
|
|
264
|
+
getSelection: () => string[]
|
|
265
|
+
select: (ids: string[], options?: { fit?: boolean }) => void
|
|
266
|
+
setTool: (tool: DrawTool | null) => boolean // false if unavailable / readonly
|
|
267
|
+
getTool: () => DrawTool | null // also: onToolChange prop
|
|
268
|
+
getMap: () => TMap | null // null until mounted
|
|
269
|
+
flyTo: {
|
|
270
|
+
(options: FlyToOptions): void // { center: [lng, lat], zoom? }, zoom default 15
|
|
271
|
+
/** @deprecated [lat, lng] tuple */
|
|
272
|
+
(latlng: [number, number], zoom?: number): void
|
|
273
|
+
}
|
|
274
|
+
setZoom: (zoom: number) => boolean // false if the map isn't mounted
|
|
275
|
+
fitBounds: (target: [number, number][] | [number, number, number, number]) => void
|
|
276
|
+
validate: () => ValidationReport // schema check of every feature, no submit
|
|
277
|
+
submit: () => boolean // validate, then onSubmit or onValidationError
|
|
278
|
+
undo: () => void
|
|
279
|
+
redo: () => void
|
|
280
|
+
canUndo: () => boolean
|
|
281
|
+
canRedo: () => boolean
|
|
282
|
+
clearSelection: () => void
|
|
283
|
+
// drop-ins only:
|
|
284
|
+
getBasemap: () => BasemapInput // LeafletBasemap on /leaflet
|
|
285
|
+
setBasemap: (basemap: BasemapInput) => void // fires onBasemapChange
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
type FeaturePatch = Partial<Pick<GeoJSONFeature, 'properties' | 'geometry' | 'schemaId' | 'hidden'>> // properties replaces the whole object
|
|
289
|
+
interface MutationOptions { undoable?: boolean } // default true; false = no undo step, applied to history too (server sync)
|
|
290
|
+
interface SetFeatureCollectionOptions { silent?: boolean; undoable?: boolean } // silent default false; undoable default true (false clears history)
|
|
291
|
+
interface ValidationReport { valid: boolean; errors: Record<string, string[]> } // errors keyed by feature id
|
|
292
|
+
interface ImportResult { skipped: number; duplicates: number; truncated: boolean }
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
`FeaturePatch` is exported from `@element-editor/core`, not from `@element-editor/react`. `ImportResult`, `MutationOptions`, `SetFeatureCollectionOptions`, `ValidationReport`, `FeatureCollection`, `FeatureCollectionInput`, `GeoJSONFeature`, `GeoJSONFeatureInput`, `GeometryInput`, `Schema`, `DrawTool`, `FlyToOptions`, `BBox` and `BasemapInput` are.
|
|
296
|
+
|
|
297
|
+
## Events and errors
|
|
298
|
+
|
|
299
|
+
| Prop | Signature | Fires |
|
|
300
|
+
|---|---|---|
|
|
301
|
+
| `onChange` | `(data: FeatureCollection) => void` | after every committed change (add, update, delete, undo/redo) |
|
|
302
|
+
| `onFeatureAdd` | `(feature: GeoJSONFeature) => void` | once per new feature, after `onChange` |
|
|
303
|
+
| `onFeatureUpdate` | `(id: string, feature: GeoJSONFeature) => void` | geometry or properties changed (on commit) |
|
|
304
|
+
| `onFeatureDelete` | `(id: string) => void` | once per deleted feature |
|
|
305
|
+
| `onSelectionChange` | `(ids: string[]) => void` | selection changed (no `onChange`) |
|
|
306
|
+
| `onFeatureSelect` | `(feature: GeoJSONFeature \| null) => void` | single selection; `null` when none or several |
|
|
307
|
+
| `onZoomChange` | `(zoom: number) => void` | zoom changed |
|
|
308
|
+
| `onSubmit` | `(data: FeatureCollection) => void` | Apply changes / `ref.submit()` with valid data |
|
|
309
|
+
| `onValidationError` | `(errors: Record<string, string[]>) => void` | submit blocked by schema errors |
|
|
310
|
+
| `onEvent` | `(event: ElementEditorEvent) => void` | every user-facing message; when set, Element shows no toasts. Read once at mount |
|
|
311
|
+
| `onError` | `(error: ElementEditorError) => void \| false \| string` | every runtime failure, first |
|
|
312
|
+
| `onBasemapChange` | `(basemap) => void` | user picked a basemap or `ref.setBasemap()` |
|
|
313
|
+
| `onMapReady` | `(map) => void` | once per map, after Element's layers are on it |
|
|
314
|
+
| `onToolChange` | `(tool: DrawTool \| null) => void` | a drawing tool turned on (`null`: off), as `ref.getTool()` reports it |
|
|
315
|
+
|
|
316
|
+
`ElementEditorEvent['type']`: `'feature:deleted' | 'features:deleted' | 'feature:duplicated' | 'features:duplicated' | 'feature:broken' | 'selection:copied' | 'selection:pasted' | 'undo' | 'redo' | 'error' | 'warning' | 'success'`.
|
|
317
|
+
|
|
318
|
+
`onError` return value: nothing keeps the built-in toast, `false` suppresses it (and the `onEvent` error event), a string replaces the toast text. `ElementEditorError extends Error` with `code`, `source`, optional `featureId` and `cause`.
|
|
319
|
+
|
|
320
|
+
| `ErrorCode` | Meaning |
|
|
321
|
+
|---|---|
|
|
322
|
+
| `network` | request failed (offline, CORS, non-retryable HTTP status, lazy chunk) |
|
|
323
|
+
| `rate-limited` | HTTP 429 |
|
|
324
|
+
| `busy` | HTTP 502–504 |
|
|
325
|
+
| `timeout` | no answer in time (Overpass, geometry worker) |
|
|
326
|
+
| `unauthorized` | HTTP 401/403 (bad routing or style key) |
|
|
327
|
+
| `invalid-data` | unreadable input/response (bad JSON, not a FeatureCollection, broken style) |
|
|
328
|
+
| `too-large` | import file over the size cap |
|
|
329
|
+
| `limit-reached` | `maxFeatures` refused or truncated an add |
|
|
330
|
+
| `geometry` | geometry operation failed or produced an empty shape |
|
|
331
|
+
| `permission-denied` | browser refused geolocation / clipboard / file save |
|
|
332
|
+
| `unsupported` | missing browser or map capability |
|
|
333
|
+
| `crash` | render crash; the error boundary shows its fallback |
|
|
334
|
+
| `unknown` | anything else |
|
|
335
|
+
|
|
336
|
+
`ErrorSource`: `'basemap' | 'picker' | 'routing' | 'search' | 'import' | 'export' | 'clipboard' | 'geometry' | 'locate' | 'editor'`.
|
|
337
|
+
|
|
338
|
+
```tsx
|
|
339
|
+
import { ElementEditor, type ElementEditorError } from '@element-editor/react'
|
|
340
|
+
|
|
341
|
+
export function Editor() {
|
|
342
|
+
function handleError(e: ElementEditorError) {
|
|
343
|
+
console.error(e.code, e.source, e.message)
|
|
344
|
+
if (e.code === 'limit-reached') return false // show your own UI instead of the toast
|
|
345
|
+
}
|
|
346
|
+
return <div style={{ height: 600 }}><ElementEditor maxFeatures={100} onError={handleError} /></div>
|
|
347
|
+
}
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
Docs: https://elementeditor.dev/docs/reference/events
|
|
351
|
+
|
|
352
|
+
## Props
|
|
353
|
+
|
|
354
|
+
Shared by both drop-ins (`ElementEditorBaseProps`):
|
|
355
|
+
|
|
356
|
+
| Prop | Type | Notes |
|
|
357
|
+
|---|---|---|
|
|
358
|
+
| `initialData` | `FeatureCollectionInput \| GeoJSONFeatureInput \| null` | starting data: at mount, or once when it first arrives while the editor is empty and unedited; later changes ignored (see Loading and saving data) |
|
|
359
|
+
| `initialView` | `{ center: [lng, lat]; zoom: number } \| { bounds: BBox } \| 'data'` | read once; wins over the remembered view |
|
|
360
|
+
| `schema` | `Schema` | `{ id, name, fields: SchemaField[] }` |
|
|
361
|
+
| `tools` | `DrawTool[]` | omit for all: `'polygon' (Area tool) \| 'rectangle' \| 'circle' \| 'line' \| 'point' \| 'freehand' \| 'route' \| 'picker' \| 'measure' \| 'search'` |
|
|
362
|
+
| `maxFeatures` | `number` | enforced for every way of adding |
|
|
363
|
+
| `bounds` | `BoundsInput` | restricts panning; bbox `[west, south, east, north]`; reactive |
|
|
364
|
+
| `theme` | `'light' \| 'dark' \| 'auto'` | mode only; colours via `accentColor` or CSS variables in `style` (an object is ignored with a dev warning) |
|
|
365
|
+
| `accentColor` | `string` | any CSS colour; derives the primary scale |
|
|
366
|
+
| `featureColor` | `string` | default feature colour (slate `#475569`; `#94a3b8` on dark MapLibre basemaps) |
|
|
367
|
+
| `layout` | `'panel' \| 'minimal' \| 'split'` | default `'panel'` |
|
|
368
|
+
| `readonly` | `boolean` | default `false`; ref data methods still work |
|
|
369
|
+
| `fileDrop` | `boolean` | default `true`: dropping a `.geojson` / `.json` file imports it like `Cmd+O` (replace, one undo step, fits); off in `readonly` |
|
|
370
|
+
| `className`, `style` | `string`, `React.CSSProperties` | on the editor root; `style` takes CSS variables (`{ '--elm-accent': '#7c3aed' }`, `'--elm-primary-N'`, design tokens like `'--elm-surface'`; see Theming), also copied onto Element's portals |
|
|
371
|
+
| `slots` | `{ toolbar?, mapOverlay?, panelFooter?, topLeft?, topCenter?, topRight?, leftCenter?, rightCenter?, bottomLeft?, bottomCenter?, bottomRight? }` (all `React.ReactNode`) | your own UI |
|
|
372
|
+
| `config` | `ElementEditorConfig` | see below; flat props win over it |
|
|
373
|
+
| `routingApiKey` | `string` | deprecated: use `config.network.routing.apiKey` |
|
|
374
|
+
| callbacks | see Events | |
|
|
375
|
+
|
|
376
|
+
MapLibre entry only: `basemap?: BasemapInput` (controlled; pair with `onBasemapChange`), `defaultBasemap?: BasemapInput` (default `'auto'`), `basemaps?: BasemapInput[] | false` (picker choices; `false` hides it), `onBasemapChange`, `getFeatureStyle?: FeatureStyleFn`, `mapOptions?` (extra `maplibregl.MapOptions` minus the ones Element owns), `onMapReady?: (map: maplibregl.Map) => void`. `BasemapInput` = `'streets' | 'terrain' | 'light' | 'dark' | 'osm' | 'auto' | { style, id?, label?, thumbnail? } | { url, attribution, maxZoom?, id?, label?, thumbnail? }`.
|
|
377
|
+
|
|
378
|
+
Leaflet entry only: `tileLayer?: React.ReactNode` (any react-leaflet tile layer; disables the picker), `basemaps?: LeafletBasemap[]`, `basemap?`, `defaultBasemap?`, `onBasemapChange?` (`LeafletBasemap = RasterBasemap | 'osm'`), `renderer?: 'canvas' | 'svg'` (default `'canvas'`), `getFeatureStyle?`, `mapOptions?` (`L.MapOptions` minus owned ones), `onMapReady?: (map: L.Map) => void`.
|
|
379
|
+
|
|
380
|
+
`ElementEditorConfig` keys: `mode` (`'light' | 'dark' | 'system'`), `accentColor`, `featureColor`, `tools`, `persistKey` (namespace for localStorage; give each editor on an origin its own), `persist` (`false` = no localStorage), `network` (every third-party server: `vectorTiles`, `dem`, `osmRaster`, `glyphs`, `sprite`, `overpass`, `routing`, `nominatim`, `fetch`; `false` on a service hides what needs it), `ui` (visibility flags `hints`, `dataTable`, `layerList`, `schemaEditor`, `geojsonEditor`, `geojsonEditorOpen`, `settings`, `zoomToAll`, `zoomIndicator`, `locateButton`, plus `layout` and `keyboardShortcuts`), `toolbar.direction`, `units`. Move controls with `withLayout` (exported here): `config={{ ui: { layout: withLayout({ move: { table: 'topRight' }, hide: ['keyboard'] }) } }}`.
|
|
381
|
+
|
|
382
|
+
Removed or renamed in 0.2 (https://elementeditor.dev/docs/guides/migrating-to-0.2):
|
|
383
|
+
|
|
384
|
+
- The default entry is MapLibre now; the 0.1 Leaflet editor is `@element-editor/react/leaflet` with `/leaflet/style.css`.
|
|
385
|
+
- `tileLayer` / `renderer` on the default entry are ignored (dev warning).
|
|
386
|
+
- `spriteUrl` is gone: use `config.network.sprite`.
|
|
387
|
+
- `licenseKey` is gone (MIT).
|
|
388
|
+
- `routingApiKey` is deprecated: `config.network.routing.apiKey`.
|
|
389
|
+
- `config.ui.corners` and `config.toolbar.position` are removed: use `config.ui.layout` / `withLayout`.
|
|
390
|
+
- `bounds` takes a bbox `[west, south, east, north]` and `ref.flyTo` takes `{ center: [lng, lat], zoom }`; the old `[lat, lng]` forms still work with a dev warning.
|
|
391
|
+
- Shortcuts: data table `T` (was `V`), transform `A` (was `T`).
|
|
392
|
+
|
|
393
|
+
## Common mistakes
|
|
394
|
+
|
|
395
|
+
- **No stylesheet, or the wrong one.** Unstyled panels, missing controls, broken tiles. One stylesheet per entry (table above); MapLibre adapter also needs `maplibre-gl.css`.
|
|
396
|
+
- **Zero-height parent.** The root is 100% of its parent. Give the parent a height (`height: 600`, `100vh`, or `flex: 1; min-height: 0` in a flex column).
|
|
397
|
+
- **Coordinate order.** Element's API (data, `initialView.center`, `bounds`, `flyTo({ center })`, `fitBounds`) is GeoJSON `[lng, lat]`. Leaflet and react-leaflet (`MapContainer center`, `L.latLng`) are `[lat, lng]`. Convert at the boundary.
|
|
398
|
+
- **Missing or wrong peers.** `maplibre-gl` must be installed for the default entry (`^5.5`); `@element-editor/adapter-leaflet`, `leaflet ^1.9` and `react-leaflet ^5` for `/leaflet`. React 18 and react-leaflet 4 do not work.
|
|
399
|
+
- **SSR.** Render client-only (`next/dynamic` with `ssr: false`); `'use client'` alone is not enough.
|
|
400
|
+
- **Expecting `initialData` to be reactive.** Use the ref or a `key` remount (see Loading and saving data).
|
|
401
|
+
- **Adapters without providers.** `ElementEditorControls` throws outside `ElementEditorUIProvider`; it also needs a `GeoStoreProvider` (one per editor) and a `data-elm-theme="light" | "dark"` ancestor containing the map and all editor UI. Portaled UI of your own needs a `data-elm-portal` attribute.
|
|
402
|
+
- **`onEvent` set "just to log".** It silences every built-in toast. Use `onError` for logging.
|
|
403
|
+
- **Unstable `getFeatureStyle` or id-less inline basemap objects.** A new function re-sends every feature; a new id-less style object counts as a new basemap. Define them at module level or memoise.
|
|
404
|
+
- **Your own `map.setStyle()` on the MapLibre drop-in.** It drops your layers (Element restores its own). Switch basemaps with `basemap` / `ref.setBasemap()`, which keep your layers; images added with `map.addImage` are never kept across a style change.
|
|
405
|
+
- **Several editors on one origin.** They share `elm_*` localStorage keys (theme, view, basemap pick). Set `config.persistKey` per editor, or `config.persist: false`.
|
|
406
|
+
- **The map reopens where the user left it**, not at your data. Pass `initialView` (`'data'` to always fit `initialData`).
|
|
407
|
+
- **Production traffic on public services.** Defaults are OpenFreeMap/Mapterhorn tiles, Overpass, the OSRM demo router (car-only, not for production) and Nominatim. Configure `config.network` (https://elementeditor.dev/docs/guides/third-party-services).
|
|
408
|
+
- **Importing `@element-editor/ui/internal`.** Not covered by semver.
|
|
409
|
+
|
|
410
|
+
## Docs
|
|
411
|
+
|
|
412
|
+
| Topic | URL |
|
|
413
|
+
|---|---|
|
|
414
|
+
| Choosing a package | https://elementeditor.dev/docs/introduction/choosing-a-package |
|
|
415
|
+
| Quick start (drop-in) | https://elementeditor.dev/docs/quickstart/react |
|
|
416
|
+
| Quick start (adapters) | https://elementeditor.dev/docs/quickstart/adapter-maplibre, https://elementeditor.dev/docs/quickstart/adapter-leaflet |
|
|
417
|
+
| Component reference (props, ref, config) | https://elementeditor.dev/docs/reference/element-editor-react |
|
|
418
|
+
| Events and `onError` | https://elementeditor.dev/docs/reference/events |
|
|
419
|
+
| Types | https://elementeditor.dev/docs/reference/types |
|
|
420
|
+
| Next.js | https://elementeditor.dev/docs/guides/nextjs |
|
|
421
|
+
| Persisting data, live vs submit, large datasets | https://elementeditor.dev/docs/guides/persisting-data, https://elementeditor.dev/docs/guides/live-vs-submit, https://elementeditor.dev/docs/guides/saving-large-datasets |
|
|
422
|
+
| Schemas and validation | https://elementeditor.dev/docs/guides/schema-and-validation |
|
|
423
|
+
| Basemaps | https://elementeditor.dev/docs/guides/basemaps |
|
|
424
|
+
| Layout, tools, theming | https://elementeditor.dev/docs/guides/configuring-layout, https://elementeditor.dev/docs/guides/restricting-tools, https://elementeditor.dev/docs/guides/theming |
|
|
425
|
+
| Third-party services | https://elementeditor.dev/docs/guides/third-party-services |
|
|
426
|
+
| Custom UI with adapters | https://elementeditor.dev/docs/guides/custom-ui-with-adapters |
|
|
427
|
+
| Migrating from 0.1 | https://elementeditor.dev/docs/guides/migrating-to-0.2 |
|
|
428
|
+
|
|
429
|
+
Append `.md` to any docs URL for markdown; https://elementeditor.dev/llms-full.txt has everything in one file.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Michal Acler and Element Editor contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,50 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @element-editor/react
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A complete map editor in one React component: drawing tools, vertex editing, snapping, schema-driven property forms, a data table, a GeoJSON inspector, undo/redo and keyboard shortcuts. The default entry owns a MapLibre GL map with built-in basemaps; `@element-editor/react/leaflet` is the same editor on Leaflet.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @element-editor/react maplibre-gl
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Peer dependencies: `react` and `react-dom` `^19.2` (React 18 is not supported), `maplibre-gl` `^5.5`. If your app pins an older React (Next.js 15's `create-next-app` installs 19.1), upgrade it: `npm install react@^19.2 react-dom@^19.2`.
|
|
12
|
+
|
|
13
|
+
## Quick start
|
|
14
|
+
|
|
15
|
+
```tsx
|
|
16
|
+
import { ElementEditor } from '@element-editor/react'
|
|
17
|
+
import '@element-editor/react/style.css' // includes MapLibre's CSS
|
|
18
|
+
|
|
19
|
+
export default function App() {
|
|
20
|
+
return (
|
|
21
|
+
<div style={{ height: 600 }}>
|
|
22
|
+
<ElementEditor onChange={(data) => console.log(data)} />
|
|
23
|
+
</div>
|
|
24
|
+
)
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The editor fills its container, so give the parent a height. In Next.js, load it with `dynamic(..., { ssr: false })` ([Next.js guide](https://elementeditor.dev/docs/guides/nextjs)).
|
|
29
|
+
|
|
30
|
+
## Leaflet instead of MapLibre
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npm install @element-editor/react @element-editor/adapter-leaflet leaflet react-leaflet
|
|
34
|
+
npm install -D @types/leaflet # TypeScript only
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
```tsx
|
|
38
|
+
import { ElementEditor } from '@element-editor/react/leaflet'
|
|
39
|
+
import '@element-editor/react/leaflet/style.css' // includes Leaflet's CSS
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Documentation
|
|
43
|
+
|
|
44
|
+
- [Quick start](https://elementeditor.dev/docs/quickstart/react)
|
|
45
|
+
- [`<ElementEditor />` API reference](https://elementeditor.dev/docs/reference/element-editor-react)
|
|
46
|
+
- [Basemaps](https://github.com/spatibase/element/blob/main/docs/guides/basemaps.md) and [third-party services, self-hosting and CSP](https://github.com/spatibase/element/blob/main/docs/guides/third-party-services.md)
|
|
47
|
+
- [Migrating from a 0.1 pre-release build](https://github.com/spatibase/element/blob/main/docs/guides/migrating-to-0.2.md)
|
|
48
|
+
- [All docs](https://elementeditor.dev/docs) · [Changelog](https://github.com/spatibase/element/blob/main/CHANGELOG.md) · [Issues](https://github.com/spatibase/element/issues)
|
|
49
|
+
|
|
50
|
+
MIT licence.
|