@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.
Files changed (58) hide show
  1. package/AGENTS.md +429 -0
  2. package/LICENSE +21 -0
  3. package/README.md +49 -2
  4. package/dist/element-editor-leaflet.css +1 -0
  5. package/dist/element-editor.cjs +1 -0
  6. package/dist/element-editor.css +1 -0
  7. package/dist/element-editor.es.js +178 -0
  8. package/dist/index.d.cts +4 -0
  9. package/dist/index.d.ts +4 -0
  10. package/dist/leaflet/CompactAttribution.d.cts +23 -0
  11. package/dist/leaflet/CompactAttribution.d.ts +23 -0
  12. package/dist/leaflet/ElementEditor.d.cts +81 -0
  13. package/dist/leaflet/ElementEditor.d.ts +81 -0
  14. package/dist/leaflet/MapView.d.cts +28 -0
  15. package/dist/leaflet/MapView.d.ts +28 -0
  16. package/dist/leaflet/index.d.cts +3 -0
  17. package/dist/leaflet/index.d.ts +3 -0
  18. package/dist/leaflet.cjs +1 -0
  19. package/dist/leaflet.d.cts +2 -0
  20. package/dist/leaflet.d.ts +2 -0
  21. package/dist/leaflet.es.js +181 -0
  22. package/dist/maplibre/ElementEditor.d.cts +68 -0
  23. package/dist/maplibre/ElementEditor.d.ts +68 -0
  24. package/dist/maplibre/MapLibreMapView.d.cts +34 -0
  25. package/dist/maplibre/MapLibreMapView.d.ts +34 -0
  26. package/dist/maplibre/index.d.cts +2 -0
  27. package/dist/maplibre/index.d.ts +2 -0
  28. package/dist/shared.d.cts +13 -0
  29. package/dist/shared.d.ts +13 -0
  30. package/dist/shell/ElementEditorShell.d.cts +32 -0
  31. package/dist/shell/ElementEditorShell.d.ts +32 -0
  32. package/dist/shell/FileDropBox.d.cts +13 -0
  33. package/dist/shell/FileDropBox.d.ts +13 -0
  34. package/dist/shell/ShellControl.d.cts +19 -0
  35. package/dist/shell/ShellControl.d.ts +19 -0
  36. package/dist/shell/ShellPanels.d.cts +13 -0
  37. package/dist/shell/ShellPanels.d.ts +13 -0
  38. package/dist/shell/savedView.d.cts +49 -0
  39. package/dist/shell/savedView.d.ts +49 -0
  40. package/dist/shell/types.d.cts +253 -0
  41. package/dist/shell/types.d.ts +253 -0
  42. package/dist/shell/useAttributionAutoCollapse.d.cts +17 -0
  43. package/dist/shell/useAttributionAutoCollapse.d.ts +17 -0
  44. package/dist/shell/useBasemapState.d.cts +20 -0
  45. package/dist/shell/useBasemapState.d.ts +20 -0
  46. package/dist/shell/useDevChecks.d.cts +11 -0
  47. package/dist/shell/useDevChecks.d.ts +11 -0
  48. package/dist/shell/useResolvedTheme.d.cts +14 -0
  49. package/dist/shell/useResolvedTheme.d.ts +14 -0
  50. package/dist/shell/useSlotAutoLayout.d.cts +23 -0
  51. package/dist/shell/useSlotAutoLayout.d.ts +23 -0
  52. package/dist/store/StoreContext.d.cts +1 -0
  53. package/dist/store/StoreContext.d.ts +1 -0
  54. package/dist/types/geojson.d.cts +1 -0
  55. package/dist/types/geojson.d.ts +1 -0
  56. package/dist/useBasemapState-8bWJK84f.cjs +1 -0
  57. package/dist/useBasemapState-DChxz3lv.js +682 -0
  58. package/package.json +150 -3
@@ -0,0 +1,49 @@
1
+ import { PersistScope, BBox, BoundsInput, FeatureCollectionInput, GeoJSONFeatureInput } from '@element-editor/core';
2
+ /**
3
+ * Where the map starts: a centre (`[lng, lat]`) and zoom, a GeoJSON bbox to fit, or `'data'`
4
+ * (fit `initialData`).
5
+ */
6
+ export type InitialView = {
7
+ center: [number, number];
8
+ zoom: number;
9
+ } | {
10
+ bounds: BBox;
11
+ } | 'data';
12
+ /** A resolved start view: centre `[lng, lat]` + zoom, or a bbox to fit. */
13
+ export type ResolvedView = {
14
+ center: [number, number];
15
+ zoom: number;
16
+ } | {
17
+ bounds: BBox;
18
+ };
19
+ /** Used when nothing else gives a view: Europe. */
20
+ export declare const DEFAULT_VIEW: ResolvedView;
21
+ /** Fit options for a `{ bounds }` start view; same as `ref.fitBounds`. */
22
+ export declare const FIT_PADDING = 40;
23
+ export declare const FIT_MAX_ZOOM = 16;
24
+ /** Last saved view (`[lng, lat]` + zoom), or null when none is stored or persistence is off. */
25
+ export declare function loadSavedView(scope?: PersistScope): {
26
+ center: [number, number];
27
+ zoom: number;
28
+ } | null;
29
+ export declare function saveView(lat: number, lng: number, zoom: number, scope?: PersistScope): void;
30
+ type InitialData = FeatureCollectionInput | GeoJSONFeatureInput;
31
+ /**
32
+ * The view the map starts with. First that applies:
33
+ * 1. `initialView` (`'data'` with no usable geometry falls through),
34
+ * 2. the saved view (`elm_mapView`; none when `persist: false`),
35
+ * 3. a fit of `initialData`, when it has features (first visit: there was no saved view),
36
+ * 4. a fit of the `bounds` prop,
37
+ * 5. Europe ({@link DEFAULT_VIEW}).
38
+ */
39
+ export declare function resolveInitialView({ initialView, initialData, bounds }: {
40
+ initialView?: InitialView;
41
+ initialData?: InitialData | null;
42
+ bounds?: BoundsInput | null;
43
+ }, scope?: PersistScope): ResolvedView;
44
+ /**
45
+ * `mapOptions` minus the keys Element sets itself. Each dropped key warns once (dev) with what to
46
+ * use instead. The types already leave them out; this covers JS callers and casts.
47
+ */
48
+ export declare function pickMapOptions<T extends object>(options: T | undefined, owned: Record<string, string>, engine: string): Partial<T>;
49
+ export {};
@@ -0,0 +1,49 @@
1
+ import { PersistScope, BBox, BoundsInput, FeatureCollectionInput, GeoJSONFeatureInput } from '@element-editor/core';
2
+ /**
3
+ * Where the map starts: a centre (`[lng, lat]`) and zoom, a GeoJSON bbox to fit, or `'data'`
4
+ * (fit `initialData`).
5
+ */
6
+ export type InitialView = {
7
+ center: [number, number];
8
+ zoom: number;
9
+ } | {
10
+ bounds: BBox;
11
+ } | 'data';
12
+ /** A resolved start view: centre `[lng, lat]` + zoom, or a bbox to fit. */
13
+ export type ResolvedView = {
14
+ center: [number, number];
15
+ zoom: number;
16
+ } | {
17
+ bounds: BBox;
18
+ };
19
+ /** Used when nothing else gives a view: Europe. */
20
+ export declare const DEFAULT_VIEW: ResolvedView;
21
+ /** Fit options for a `{ bounds }` start view; same as `ref.fitBounds`. */
22
+ export declare const FIT_PADDING = 40;
23
+ export declare const FIT_MAX_ZOOM = 16;
24
+ /** Last saved view (`[lng, lat]` + zoom), or null when none is stored or persistence is off. */
25
+ export declare function loadSavedView(scope?: PersistScope): {
26
+ center: [number, number];
27
+ zoom: number;
28
+ } | null;
29
+ export declare function saveView(lat: number, lng: number, zoom: number, scope?: PersistScope): void;
30
+ type InitialData = FeatureCollectionInput | GeoJSONFeatureInput;
31
+ /**
32
+ * The view the map starts with. First that applies:
33
+ * 1. `initialView` (`'data'` with no usable geometry falls through),
34
+ * 2. the saved view (`elm_mapView`; none when `persist: false`),
35
+ * 3. a fit of `initialData`, when it has features (first visit: there was no saved view),
36
+ * 4. a fit of the `bounds` prop,
37
+ * 5. Europe ({@link DEFAULT_VIEW}).
38
+ */
39
+ export declare function resolveInitialView({ initialView, initialData, bounds }: {
40
+ initialView?: InitialView;
41
+ initialData?: InitialData | null;
42
+ bounds?: BoundsInput | null;
43
+ }, scope?: PersistScope): ResolvedView;
44
+ /**
45
+ * `mapOptions` minus the keys Element sets itself. Each dropped key warns once (dev) with what to
46
+ * use instead. The types already leave them out; this covers JS callers and casts.
47
+ */
48
+ export declare function pickMapOptions<T extends object>(options: T | undefined, owned: Record<string, string>, engine: string): Partial<T>;
49
+ export {};
@@ -0,0 +1,253 @@
1
+ import { default as React } from 'react';
2
+ import { FeatureCollection, FeatureCollectionInput, Schema, GeoJSONFeature, GeoJSONFeatureInput } from '../types/geojson.cjs';
3
+ import { BoundsInput } from '@element-editor/core';
4
+ import { InitialView } from './savedView.cjs';
5
+ import { ElementEditorEvent, ElementEditorErrorHandler, ElementEditorConfig, DrawTool } from '@element-editor/ui';
6
+ export interface ElementEditorBaseProps {
7
+ /**
8
+ * The starting data: any GeoJSON `FeatureCollection` (`@types/geojson`'s type-checks as is; ids,
9
+ * `properties` and `metadata` are optional) or a single `Feature`. Pass back what `onChange`
10
+ * gave you to restore schemas and groups too.
11
+ *
12
+ * Applied once, on mount, without an undo step. Data that arrives later (`null` / `undefined` →
13
+ * data, e.g. after a fetch) is applied once too, if the editor is still empty and the user
14
+ * hasn't edited yet; the map then fits it as on mount (see `initialView`). Any other change is
15
+ * ignored, with a development warning: to replace the data call
16
+ * `ref.setFeatureCollection(data, { silent: true })`, or remount with a new `key`.
17
+ *
18
+ * Invalid data doesn't crash the editor: it reports an `error` event and starts empty. Features
19
+ * without a usable geometry (`geometry: null`) are left out and reported the same way.
20
+ *
21
+ * @default undefined (an empty editor)
22
+ * @example
23
+ * const [data, setData] = useState<GeoJSON.FeatureCollection | null>(null)
24
+ * useEffect(() => { fetch('/api/map').then((r) => r.json()).then(setData) }, [])
25
+ * <ElementEditor initialData={data} onChange={save} />
26
+ */
27
+ initialData?: FeatureCollectionInput | GeoJSONFeatureInput | null;
28
+ /**
29
+ * Where the map starts: `{ center: [lng, lat], zoom }`, `{ bounds: [west, south, east, north] }`
30
+ * (fitted) or `'data'` (fit `initialData`). Wins over the view remembered from the last visit.
31
+ * Read once, when the map is created.
32
+ *
33
+ * Without it the map starts at the remembered view (none with `config.persist: false`), else
34
+ * fits `initialData` when it has features, else fits `bounds`, else shows Europe. `'data'` with
35
+ * no features falls back the same way.
36
+ *
37
+ * @example initialView={{ center: [14.42, 50.09], zoom: 12 }} // Prague
38
+ */
39
+ initialView?: InitialView;
40
+ /**
41
+ * A schema added on mount (and when a schema with a new `id` is passed later): the fields the
42
+ * feature panel and data table show for `feature.properties`. Features follow the schema their
43
+ * `schemaId` names, else the first one. Users can add more schemas in the editor. Schemas in
44
+ * `initialData.metadata.schemas` are loaded too.
45
+ *
46
+ * @default undefined (a built-in default schema)
47
+ * @example schema={{ id: 'parcel', name: 'Parcel', fields: [{ key: 'owner', label: 'Owner', type: 'text', required: true }] }}
48
+ */
49
+ schema?: Schema;
50
+ /**
51
+ * Tools to offer: drawing tools plus `'picker'`, `'measure'` and `'search'`. Tools left out
52
+ * disappear from the toolbar, and their keyboard shortcuts and `ref.setTool` are refused.
53
+ * Wins over `config.tools`.
54
+ *
55
+ * @default all tools (`config.tools`, default `'all'`)
56
+ * @example tools={['polygon', 'rectangle', 'point', 'measure']}
57
+ */
58
+ tools?: DrawTool[];
59
+ /**
60
+ * Most features the editor may hold. Every way of adding features respects it: drawing tools
61
+ * turn off at the limit, duplicate / paste are refused, imports are truncated (each refusal
62
+ * reports an `error` event, `code: 'limit-reached'`). Undo and redo are never blocked.
63
+ *
64
+ * @default undefined (no limit; imports are still capped at 50,000 features)
65
+ */
66
+ maxFeatures?: number;
67
+ /**
68
+ * Restricts panning to this box: the user can't drag the map outside it. The map starts fitted
69
+ * to it only when nothing else gives a start view (see `initialView`). A GeoJSON bbox `[west, south, east, north]`
70
+ * (`[lng, lat]` order, same as your data), on both engines. Reactive; `undefined` removes the
71
+ * restriction.
72
+ *
73
+ * Deprecated: the nested `[[south, west], [north, east]]` (`[lat, lng]`) form still works and
74
+ * logs a one-time dev warning with the bbox equivalent.
75
+ *
76
+ * @example bounds={[14.2, 49.9, 14.7, 50.2]} // Prague
77
+ */
78
+ bounds?: BoundsInput;
79
+ /**
80
+ * Light or dark mode. Colours are not set here: use `accentColor` for the brand colour, or
81
+ * `style` for CSS variables (`--elm-accent`, a single `--elm-primary-N` shade).
82
+ *
83
+ * - `'light'` / `'dark'`: that mode, always (the settings' theme picker can still switch it until
84
+ * the prop changes; the prop is never saved to localStorage).
85
+ * - `'auto'`: follows the OS (`prefers-color-scheme`).
86
+ *
87
+ * @default undefined: `config.mode` (default `'system'`, like `'auto'`), unless the user picked a theme in settings
88
+ * @example theme="dark"
89
+ */
90
+ theme?: 'light' | 'dark' | 'auto';
91
+ /**
92
+ * Brand accent: any CSS colour. The whole primary scale (buttons, active
93
+ * tools, selection, checkboxes, links, portals) is derived from it.
94
+ * Wins over `config.accentColor`. Default: blue.
95
+ */
96
+ accentColor?: string;
97
+ /**
98
+ * Default colour of every feature (polygon outline + fill, line, point): any CSS colour.
99
+ * Opacity and weight keep their defaults; `getFeatureStyle` and the selected / hovered
100
+ * looks win over it. Wins over `config.featureColor`. Default: slate `#475569`.
101
+ */
102
+ featureColor?: string;
103
+ /**
104
+ * Where feature details and the list live:
105
+ * - `'panel'`: a layers sidebar on the right (feature list, feature properties).
106
+ * - `'minimal'`: no sidebar; a selected feature's properties open in a floating window.
107
+ * - `'split'`: no sidebar; the bottom third is a panel with the data table on the left and the
108
+ * layers panel on its right (map controls sit above it).
109
+ *
110
+ * @default 'panel'
111
+ */
112
+ layout?: 'panel' | 'minimal' | 'split';
113
+ /**
114
+ * View-only mode for the user. Reactive.
115
+ *
116
+ * Still available: selecting features (map, layers list, table rows), zoom-to, the details panel
117
+ * (fields disabled), show/hide of features and groups, collapsing groups, measure, search, copy,
118
+ * export, the data table and the GeoJSON inspector (both read-only).
119
+ *
120
+ * Off: drawing tools and the picker, vertex edit, transform and drag, cut/slice/buffer/simplify/
121
+ * smooth, boolean ops, merge and break apart, delete, duplicate, paste, group/ungroup, renaming,
122
+ * layers drag-reorder, table cell edits / row delete / "Add new", the schema editor, import
123
+ * (Cmd+O and file drop), and undo/redo (buttons hidden, keys ignored).
124
+ *
125
+ * Your app is still in charge: the ref's data methods (`addFeature`, `updateFeature`,
126
+ * `setFeatureCollection`, …) keep working; only `ref.setTool` is refused (except `'measure'`).
127
+ *
128
+ * @default false
129
+ * @example readonly={!user.canEdit}
130
+ */
131
+ readonly?: boolean;
132
+ /**
133
+ * Dropping a `.geojson` / `.json` file on the editor imports it, like Cmd+O: replaces the data
134
+ * (one undo step; `maxFeatures` truncates) and fits the map to it. Off in `readonly`.
135
+ * Default: true.
136
+ */
137
+ fileDrop?: boolean;
138
+ /** Class added to the editor's root element (it already fills its parent: `width` / `height: 100%`). */
139
+ className?: string;
140
+ /**
141
+ * Inline styles merged onto the editor's root element (after Element's own and after
142
+ * `accentColor`, so they win). Its CSS variables are Element's theming hook:
143
+ * `'--elm-accent'` re-derives the whole primary scale (chrome, map selection and drawing
144
+ * colours), `'--elm-primary-N'` overrides one shade. They also reach Element's body-level
145
+ * portals (modals, menus, tooltips). CSS variables type-check without a cast. See the theming
146
+ * guide for every variable.
147
+ *
148
+ * @example style={{ '--elm-accent': '#7c3aed' }}
149
+ */
150
+ style?: React.CSSProperties | (React.CSSProperties & {
151
+ [cssVar: `--${string}`]: string | number | undefined;
152
+ });
153
+ /**
154
+ * Called after every committed change (an add, a finished drag, a property edit, an undo, an
155
+ * import, `ref` data methods) with the full current data: features without internal state plus
156
+ * `metadata` (schemas and groups), ready to store and pass back as `initialData`. Not called
157
+ * while a drag is in progress, nor for the `initialData` load. `ref.setFeatureCollection` calls it
158
+ * unless you pass `{ silent: true }`. For large data, prefer `onFeatureAdd` / `onFeatureUpdate` /
159
+ * `onFeatureDelete`, or debounce.
160
+ *
161
+ * @example
162
+ * onChange={(data) => localStorage.setItem('my-map', JSON.stringify(data))}
163
+ */
164
+ onChange?: (data: FeatureCollection) => void;
165
+ /**
166
+ * Called by the "Apply changes" button (shown only when this is set) or `ref.submit()` when every
167
+ * feature passes validation, with the full current data. When some don't, `onValidationError`
168
+ * is called instead.
169
+ */
170
+ onSubmit?: (data: FeatureCollection) => void;
171
+ /**
172
+ * Called instead of `onSubmit` when a submit finds validation errors (missing required fields,
173
+ * numbers out of range, zero-area polygons): error messages keyed by feature id. To check without
174
+ * submitting, use `ref.validate()`.
175
+ */
176
+ onValidationError?: (errors: Record<string, string[]>) => void;
177
+ /**
178
+ * Called with the selected feature when exactly one is selected, and with `null` when that ends
179
+ * (deselected, or a second feature joins the selection). Also called again when the selected
180
+ * feature itself changes (its geometry or properties are edited), so it suits a details panel
181
+ * that shows one feature. For the full selection (multi-select, lasso), use `onSelectionChange`.
182
+ */
183
+ onFeatureSelect?: (feature: GeoJSONFeature | null) => void;
184
+ /** Called with the new zoom level when the map's zoom changes (after the zoom ends). */
185
+ onZoomChange?: (zoom: number) => void;
186
+ /**
187
+ * Called with the tool that turned on (as `ref.getTool()` reports it), or `null` when the active
188
+ * tool turned off (finished, cancelled, or `ref.setTool(null)`), whether the user or your app
189
+ * changed it.
190
+ */
191
+ onToolChange?: (tool: DrawTool | null) => void;
192
+ /**
193
+ * Receives every message the editor would show the user (errors, warnings, confirmations,
194
+ * `feature:deleted` with an `undo`, …). With it set, the editor shows no toasts: your app
195
+ * displays them. Without it, the editor renders its own toaster. Read once, on mount.
196
+ */
197
+ onEvent?: (event: ElementEditorEvent) => void;
198
+ /**
199
+ * Called first for every runtime failure with an `ElementEditorError`: a stable `code`
200
+ * (`'rate-limited'`, `'timeout'`, `'limit-reached'`, …), a `source` (`'basemap'`, `'picker'`,
201
+ * `'routing'`, `'search'`, `'import'`, …) and an honest English `message`. Also fires with
202
+ * `onEvent` set, for failures that show no toast (a failed preview, the system clipboard, the
203
+ * search box) and for a render crash (`code: 'crash'`). Return nothing to keep the built-in toast,
204
+ * `false` to stop it (and the `onEvent` error event), or a string to show that text instead.
205
+ */
206
+ onError?: ElementEditorErrorHandler;
207
+ /** Called once per newly added feature. Avoids diffing full snapshots. */
208
+ onFeatureAdd?: (feature: GeoJSONFeature) => void;
209
+ /** Called when a feature's geometry or properties change (fires on commit, not during drag). */
210
+ onFeatureUpdate?: (id: string, feature: GeoJSONFeature) => void;
211
+ /** Called once per deleted feature, including bulk and group deletions. */
212
+ onFeatureDelete?: (id: string) => void;
213
+ /**
214
+ * Called with the ids of the selected features whenever the selection changes, including
215
+ * multi-select and lasso (`[]` when cleared). For one selected feature's data, see `onFeatureSelect`.
216
+ */
217
+ onSelectionChange?: (ids: string[]) => void;
218
+ /**
219
+ * @deprecated Use `config.network.routing.apiKey` (it wins over this; dev warning).
220
+ * OpenRouteService key for the Route tool's pedestrian routing.
221
+ */
222
+ routingApiKey?: string;
223
+ /**
224
+ * Named content slots for injecting custom UI.
225
+ *
226
+ * - `toolbar` — rendered inside the map area, right after the map element, with no
227
+ * positioning of its own (position it yourself, e.g. `position: absolute`). Hidden while the
228
+ * data table is fullscreen.
229
+ * - `mapOverlay` — absolute, full-map overlay above the map; `pointer-events: none` by default
230
+ * - `panelFooter` — rendered below the layers/feature panel (`layout="panel"`)
231
+ * - map slots (`topLeft`, `topCenter`, `topRight`, `leftCenter`, `rightCenter`, `bottomLeft`,
232
+ * `bottomCenter`, `bottomRight`) — rendered first in that slot, before the built-in
233
+ * controls placed there via `config.ui.layout`. The status-bar slots are not available.
234
+ */
235
+ slots?: {
236
+ toolbar?: React.ReactNode;
237
+ mapOverlay?: React.ReactNode;
238
+ panelFooter?: React.ReactNode;
239
+ topLeft?: React.ReactNode;
240
+ topCenter?: React.ReactNode;
241
+ topRight?: React.ReactNode;
242
+ leftCenter?: React.ReactNode;
243
+ rightCenter?: React.ReactNode;
244
+ bottomLeft?: React.ReactNode;
245
+ bottomCenter?: React.ReactNode;
246
+ bottomRight?: React.ReactNode;
247
+ };
248
+ /**
249
+ * Structured configuration object. Covers theme, tools, UI visibility, toolbar layout, and units.
250
+ * Flat props (tools, theme, accentColor, featureColor) take precedence over config when both are provided.
251
+ */
252
+ config?: ElementEditorConfig;
253
+ }
@@ -0,0 +1,253 @@
1
+ import { default as React } from 'react';
2
+ import { FeatureCollection, FeatureCollectionInput, Schema, GeoJSONFeature, GeoJSONFeatureInput } from '../types/geojson.js';
3
+ import { BoundsInput } from '@element-editor/core';
4
+ import { InitialView } from './savedView.js';
5
+ import { ElementEditorEvent, ElementEditorErrorHandler, ElementEditorConfig, DrawTool } from '@element-editor/ui';
6
+ export interface ElementEditorBaseProps {
7
+ /**
8
+ * The starting data: any GeoJSON `FeatureCollection` (`@types/geojson`'s type-checks as is; ids,
9
+ * `properties` and `metadata` are optional) or a single `Feature`. Pass back what `onChange`
10
+ * gave you to restore schemas and groups too.
11
+ *
12
+ * Applied once, on mount, without an undo step. Data that arrives later (`null` / `undefined` →
13
+ * data, e.g. after a fetch) is applied once too, if the editor is still empty and the user
14
+ * hasn't edited yet; the map then fits it as on mount (see `initialView`). Any other change is
15
+ * ignored, with a development warning: to replace the data call
16
+ * `ref.setFeatureCollection(data, { silent: true })`, or remount with a new `key`.
17
+ *
18
+ * Invalid data doesn't crash the editor: it reports an `error` event and starts empty. Features
19
+ * without a usable geometry (`geometry: null`) are left out and reported the same way.
20
+ *
21
+ * @default undefined (an empty editor)
22
+ * @example
23
+ * const [data, setData] = useState<GeoJSON.FeatureCollection | null>(null)
24
+ * useEffect(() => { fetch('/api/map').then((r) => r.json()).then(setData) }, [])
25
+ * <ElementEditor initialData={data} onChange={save} />
26
+ */
27
+ initialData?: FeatureCollectionInput | GeoJSONFeatureInput | null;
28
+ /**
29
+ * Where the map starts: `{ center: [lng, lat], zoom }`, `{ bounds: [west, south, east, north] }`
30
+ * (fitted) or `'data'` (fit `initialData`). Wins over the view remembered from the last visit.
31
+ * Read once, when the map is created.
32
+ *
33
+ * Without it the map starts at the remembered view (none with `config.persist: false`), else
34
+ * fits `initialData` when it has features, else fits `bounds`, else shows Europe. `'data'` with
35
+ * no features falls back the same way.
36
+ *
37
+ * @example initialView={{ center: [14.42, 50.09], zoom: 12 }} // Prague
38
+ */
39
+ initialView?: InitialView;
40
+ /**
41
+ * A schema added on mount (and when a schema with a new `id` is passed later): the fields the
42
+ * feature panel and data table show for `feature.properties`. Features follow the schema their
43
+ * `schemaId` names, else the first one. Users can add more schemas in the editor. Schemas in
44
+ * `initialData.metadata.schemas` are loaded too.
45
+ *
46
+ * @default undefined (a built-in default schema)
47
+ * @example schema={{ id: 'parcel', name: 'Parcel', fields: [{ key: 'owner', label: 'Owner', type: 'text', required: true }] }}
48
+ */
49
+ schema?: Schema;
50
+ /**
51
+ * Tools to offer: drawing tools plus `'picker'`, `'measure'` and `'search'`. Tools left out
52
+ * disappear from the toolbar, and their keyboard shortcuts and `ref.setTool` are refused.
53
+ * Wins over `config.tools`.
54
+ *
55
+ * @default all tools (`config.tools`, default `'all'`)
56
+ * @example tools={['polygon', 'rectangle', 'point', 'measure']}
57
+ */
58
+ tools?: DrawTool[];
59
+ /**
60
+ * Most features the editor may hold. Every way of adding features respects it: drawing tools
61
+ * turn off at the limit, duplicate / paste are refused, imports are truncated (each refusal
62
+ * reports an `error` event, `code: 'limit-reached'`). Undo and redo are never blocked.
63
+ *
64
+ * @default undefined (no limit; imports are still capped at 50,000 features)
65
+ */
66
+ maxFeatures?: number;
67
+ /**
68
+ * Restricts panning to this box: the user can't drag the map outside it. The map starts fitted
69
+ * to it only when nothing else gives a start view (see `initialView`). A GeoJSON bbox `[west, south, east, north]`
70
+ * (`[lng, lat]` order, same as your data), on both engines. Reactive; `undefined` removes the
71
+ * restriction.
72
+ *
73
+ * Deprecated: the nested `[[south, west], [north, east]]` (`[lat, lng]`) form still works and
74
+ * logs a one-time dev warning with the bbox equivalent.
75
+ *
76
+ * @example bounds={[14.2, 49.9, 14.7, 50.2]} // Prague
77
+ */
78
+ bounds?: BoundsInput;
79
+ /**
80
+ * Light or dark mode. Colours are not set here: use `accentColor` for the brand colour, or
81
+ * `style` for CSS variables (`--elm-accent`, a single `--elm-primary-N` shade).
82
+ *
83
+ * - `'light'` / `'dark'`: that mode, always (the settings' theme picker can still switch it until
84
+ * the prop changes; the prop is never saved to localStorage).
85
+ * - `'auto'`: follows the OS (`prefers-color-scheme`).
86
+ *
87
+ * @default undefined: `config.mode` (default `'system'`, like `'auto'`), unless the user picked a theme in settings
88
+ * @example theme="dark"
89
+ */
90
+ theme?: 'light' | 'dark' | 'auto';
91
+ /**
92
+ * Brand accent: any CSS colour. The whole primary scale (buttons, active
93
+ * tools, selection, checkboxes, links, portals) is derived from it.
94
+ * Wins over `config.accentColor`. Default: blue.
95
+ */
96
+ accentColor?: string;
97
+ /**
98
+ * Default colour of every feature (polygon outline + fill, line, point): any CSS colour.
99
+ * Opacity and weight keep their defaults; `getFeatureStyle` and the selected / hovered
100
+ * looks win over it. Wins over `config.featureColor`. Default: slate `#475569`.
101
+ */
102
+ featureColor?: string;
103
+ /**
104
+ * Where feature details and the list live:
105
+ * - `'panel'`: a layers sidebar on the right (feature list, feature properties).
106
+ * - `'minimal'`: no sidebar; a selected feature's properties open in a floating window.
107
+ * - `'split'`: no sidebar; the bottom third is a panel with the data table on the left and the
108
+ * layers panel on its right (map controls sit above it).
109
+ *
110
+ * @default 'panel'
111
+ */
112
+ layout?: 'panel' | 'minimal' | 'split';
113
+ /**
114
+ * View-only mode for the user. Reactive.
115
+ *
116
+ * Still available: selecting features (map, layers list, table rows), zoom-to, the details panel
117
+ * (fields disabled), show/hide of features and groups, collapsing groups, measure, search, copy,
118
+ * export, the data table and the GeoJSON inspector (both read-only).
119
+ *
120
+ * Off: drawing tools and the picker, vertex edit, transform and drag, cut/slice/buffer/simplify/
121
+ * smooth, boolean ops, merge and break apart, delete, duplicate, paste, group/ungroup, renaming,
122
+ * layers drag-reorder, table cell edits / row delete / "Add new", the schema editor, import
123
+ * (Cmd+O and file drop), and undo/redo (buttons hidden, keys ignored).
124
+ *
125
+ * Your app is still in charge: the ref's data methods (`addFeature`, `updateFeature`,
126
+ * `setFeatureCollection`, …) keep working; only `ref.setTool` is refused (except `'measure'`).
127
+ *
128
+ * @default false
129
+ * @example readonly={!user.canEdit}
130
+ */
131
+ readonly?: boolean;
132
+ /**
133
+ * Dropping a `.geojson` / `.json` file on the editor imports it, like Cmd+O: replaces the data
134
+ * (one undo step; `maxFeatures` truncates) and fits the map to it. Off in `readonly`.
135
+ * Default: true.
136
+ */
137
+ fileDrop?: boolean;
138
+ /** Class added to the editor's root element (it already fills its parent: `width` / `height: 100%`). */
139
+ className?: string;
140
+ /**
141
+ * Inline styles merged onto the editor's root element (after Element's own and after
142
+ * `accentColor`, so they win). Its CSS variables are Element's theming hook:
143
+ * `'--elm-accent'` re-derives the whole primary scale (chrome, map selection and drawing
144
+ * colours), `'--elm-primary-N'` overrides one shade. They also reach Element's body-level
145
+ * portals (modals, menus, tooltips). CSS variables type-check without a cast. See the theming
146
+ * guide for every variable.
147
+ *
148
+ * @example style={{ '--elm-accent': '#7c3aed' }}
149
+ */
150
+ style?: React.CSSProperties | (React.CSSProperties & {
151
+ [cssVar: `--${string}`]: string | number | undefined;
152
+ });
153
+ /**
154
+ * Called after every committed change (an add, a finished drag, a property edit, an undo, an
155
+ * import, `ref` data methods) with the full current data: features without internal state plus
156
+ * `metadata` (schemas and groups), ready to store and pass back as `initialData`. Not called
157
+ * while a drag is in progress, nor for the `initialData` load. `ref.setFeatureCollection` calls it
158
+ * unless you pass `{ silent: true }`. For large data, prefer `onFeatureAdd` / `onFeatureUpdate` /
159
+ * `onFeatureDelete`, or debounce.
160
+ *
161
+ * @example
162
+ * onChange={(data) => localStorage.setItem('my-map', JSON.stringify(data))}
163
+ */
164
+ onChange?: (data: FeatureCollection) => void;
165
+ /**
166
+ * Called by the "Apply changes" button (shown only when this is set) or `ref.submit()` when every
167
+ * feature passes validation, with the full current data. When some don't, `onValidationError`
168
+ * is called instead.
169
+ */
170
+ onSubmit?: (data: FeatureCollection) => void;
171
+ /**
172
+ * Called instead of `onSubmit` when a submit finds validation errors (missing required fields,
173
+ * numbers out of range, zero-area polygons): error messages keyed by feature id. To check without
174
+ * submitting, use `ref.validate()`.
175
+ */
176
+ onValidationError?: (errors: Record<string, string[]>) => void;
177
+ /**
178
+ * Called with the selected feature when exactly one is selected, and with `null` when that ends
179
+ * (deselected, or a second feature joins the selection). Also called again when the selected
180
+ * feature itself changes (its geometry or properties are edited), so it suits a details panel
181
+ * that shows one feature. For the full selection (multi-select, lasso), use `onSelectionChange`.
182
+ */
183
+ onFeatureSelect?: (feature: GeoJSONFeature | null) => void;
184
+ /** Called with the new zoom level when the map's zoom changes (after the zoom ends). */
185
+ onZoomChange?: (zoom: number) => void;
186
+ /**
187
+ * Called with the tool that turned on (as `ref.getTool()` reports it), or `null` when the active
188
+ * tool turned off (finished, cancelled, or `ref.setTool(null)`), whether the user or your app
189
+ * changed it.
190
+ */
191
+ onToolChange?: (tool: DrawTool | null) => void;
192
+ /**
193
+ * Receives every message the editor would show the user (errors, warnings, confirmations,
194
+ * `feature:deleted` with an `undo`, …). With it set, the editor shows no toasts: your app
195
+ * displays them. Without it, the editor renders its own toaster. Read once, on mount.
196
+ */
197
+ onEvent?: (event: ElementEditorEvent) => void;
198
+ /**
199
+ * Called first for every runtime failure with an `ElementEditorError`: a stable `code`
200
+ * (`'rate-limited'`, `'timeout'`, `'limit-reached'`, …), a `source` (`'basemap'`, `'picker'`,
201
+ * `'routing'`, `'search'`, `'import'`, …) and an honest English `message`. Also fires with
202
+ * `onEvent` set, for failures that show no toast (a failed preview, the system clipboard, the
203
+ * search box) and for a render crash (`code: 'crash'`). Return nothing to keep the built-in toast,
204
+ * `false` to stop it (and the `onEvent` error event), or a string to show that text instead.
205
+ */
206
+ onError?: ElementEditorErrorHandler;
207
+ /** Called once per newly added feature. Avoids diffing full snapshots. */
208
+ onFeatureAdd?: (feature: GeoJSONFeature) => void;
209
+ /** Called when a feature's geometry or properties change (fires on commit, not during drag). */
210
+ onFeatureUpdate?: (id: string, feature: GeoJSONFeature) => void;
211
+ /** Called once per deleted feature, including bulk and group deletions. */
212
+ onFeatureDelete?: (id: string) => void;
213
+ /**
214
+ * Called with the ids of the selected features whenever the selection changes, including
215
+ * multi-select and lasso (`[]` when cleared). For one selected feature's data, see `onFeatureSelect`.
216
+ */
217
+ onSelectionChange?: (ids: string[]) => void;
218
+ /**
219
+ * @deprecated Use `config.network.routing.apiKey` (it wins over this; dev warning).
220
+ * OpenRouteService key for the Route tool's pedestrian routing.
221
+ */
222
+ routingApiKey?: string;
223
+ /**
224
+ * Named content slots for injecting custom UI.
225
+ *
226
+ * - `toolbar` — rendered inside the map area, right after the map element, with no
227
+ * positioning of its own (position it yourself, e.g. `position: absolute`). Hidden while the
228
+ * data table is fullscreen.
229
+ * - `mapOverlay` — absolute, full-map overlay above the map; `pointer-events: none` by default
230
+ * - `panelFooter` — rendered below the layers/feature panel (`layout="panel"`)
231
+ * - map slots (`topLeft`, `topCenter`, `topRight`, `leftCenter`, `rightCenter`, `bottomLeft`,
232
+ * `bottomCenter`, `bottomRight`) — rendered first in that slot, before the built-in
233
+ * controls placed there via `config.ui.layout`. The status-bar slots are not available.
234
+ */
235
+ slots?: {
236
+ toolbar?: React.ReactNode;
237
+ mapOverlay?: React.ReactNode;
238
+ panelFooter?: React.ReactNode;
239
+ topLeft?: React.ReactNode;
240
+ topCenter?: React.ReactNode;
241
+ topRight?: React.ReactNode;
242
+ leftCenter?: React.ReactNode;
243
+ rightCenter?: React.ReactNode;
244
+ bottomLeft?: React.ReactNode;
245
+ bottomCenter?: React.ReactNode;
246
+ bottomRight?: React.ReactNode;
247
+ };
248
+ /**
249
+ * Structured configuration object. Covers theme, tools, UI visibility, toolbar layout, and units.
250
+ * Flat props (tools, theme, accentColor, featureColor) take precedence over config when both are provided.
251
+ */
252
+ config?: ElementEditorConfig;
253
+ }
@@ -0,0 +1,17 @@
1
+ /** How long the compact attribution stays expanded after load when nobody touches the map. */
2
+ export declare const ATTRIBUTION_COLLAPSE_MS = 5000;
3
+ /**
4
+ * The OSM Foundation attribution guidelines
5
+ * (https://osmfoundation.org/wiki/Licence/Attribution_Guidelines) let a map's attribution
6
+ * collapse to an "i" button only once the user has seen it: it must show expanded at load, and may
7
+ * collapse on the first map interaction (pan, click, zoom) or after five seconds.
8
+ *
9
+ * This runs `collapse` once, on whichever comes first: a pointer press, wheel or key press on
10
+ * `mapEl` (not on the attribution itself), or {@link ATTRIBUTION_COLLAPSE_MS} of the page being
11
+ * visible (a page opened in a background tab starts counting when it is shown). Engine-neutral:
12
+ * plain DOM events on the map container, so it catches drag, click, double-click, pinch, wheel
13
+ * and keyboard pan / zoom on both Leaflet and MapLibre, and ignores programmatic moves (the
14
+ * initial fit to data). The returned `stop()` cancels it: call it when the user opens or closes
15
+ * the attribution themselves, so a timer never closes what they just opened.
16
+ */
17
+ export declare function useAttributionAutoCollapse(mapEl: HTMLElement | null | undefined, collapse: () => void, enabled?: boolean): () => void;
@@ -0,0 +1,17 @@
1
+ /** How long the compact attribution stays expanded after load when nobody touches the map. */
2
+ export declare const ATTRIBUTION_COLLAPSE_MS = 5000;
3
+ /**
4
+ * The OSM Foundation attribution guidelines
5
+ * (https://osmfoundation.org/wiki/Licence/Attribution_Guidelines) let a map's attribution
6
+ * collapse to an "i" button only once the user has seen it: it must show expanded at load, and may
7
+ * collapse on the first map interaction (pan, click, zoom) or after five seconds.
8
+ *
9
+ * This runs `collapse` once, on whichever comes first: a pointer press, wheel or key press on
10
+ * `mapEl` (not on the attribution itself), or {@link ATTRIBUTION_COLLAPSE_MS} of the page being
11
+ * visible (a page opened in a background tab starts counting when it is shown). Engine-neutral:
12
+ * plain DOM events on the map container, so it catches drag, click, double-click, pinch, wheel
13
+ * and keyboard pan / zoom on both Leaflet and MapLibre, and ignores programmatic moves (the
14
+ * initial fit to data). The returned `stop()` cancels it: call it when the user opens or closes
15
+ * the attribution themselves, so a timer never closes what they just opened.
16
+ */
17
+ export declare function useAttributionAutoCollapse(mapEl: HTMLElement | null | undefined, collapse: () => void, enabled?: boolean): () => void;
@@ -0,0 +1,20 @@
1
+ /** Ref methods both drop-ins add for the basemap (`B` = the entry's basemap type). */
2
+ export interface BasemapRefAPI<B> {
3
+ /** The current basemap, as passed in `basemap` / `basemaps` (`'auto'` stays `'auto'`). */
4
+ getBasemap: () => B;
5
+ /**
6
+ * Switches the basemap like a user pick, except that it isn't remembered for the next visit.
7
+ * Fires `onBasemapChange`. With a controlled `basemap` it only fires `onBasemapChange`.
8
+ */
9
+ setBasemap: (basemap: B) => void;
10
+ }
11
+ /**
12
+ * Controlled (`value` set) / uncontrolled basemap choice shared by both drop-ins. `initial` (read
13
+ * once, uncontrolled only) gives the remembered pick or the default; `remember` stores a user pick
14
+ * (uncontrolled only). `pick(b, true)` is a picker click, `api.setBasemap` a programmatic one.
15
+ */
16
+ export declare function useBasemapState<B>(value: B | undefined, initial: () => B, onChange: ((basemap: B) => void) | undefined, remember: (basemap: B) => void, pickerShown: boolean): {
17
+ current: B;
18
+ pick: (b: B, fromUser: boolean) => void;
19
+ api: BasemapRefAPI<B>;
20
+ };