@element-editor/ui 0.0.0-stage → 0.2.1

package/dist/hooks/useAdapterControls.d.ts

@@ -0,0 +1,280 @@
+import { FeatureCollection, FeatureCollectionInput, FeaturePatch, FlyToOptions, GeoJSONFeature, GeoJSONFeatureInput, Schema } from '@element-editor/core';
+import { DrawTool } from '../contexts/ElementEditorConfigContext.js';
+/**
+ * `useAdapterControls` — single source of truth for the editor-shell wiring
+ * shared by `@element-editor/adapter-leaflet`, `@element-editor/adapter-maplibre`, and
+ * `@element-editor/react`.
+ *
+ * Owns:
+ *   - prop → store sync (readonly / tools / maxFeatures / layout; network-disabled tools)
+ *   - one-time mounts (initialData, schema)
+ *   - data-change subscription (onChange / per-feature callbacks / selection)
+ *   - onZoomChange + onFeatureSelect subscriptions
+ *   - the FC-shaped imperative API (return value — caller wires it through
+ *     `useImperativeHandle`)
+ *
+ * Caller still owns: bounds / maxBounds (different APIs across map libs),
+ * the map-bridge wiring, the layer tree, and any wrapper-only concerns
+ * (slots, tile layer, theme persistence, dev affordances).
+ */
+export interface ImportResult {
+    /** Features skipped due to unsupported geometry type. */
+    skipped: number;
+    /** Features skipped because their id collided with an existing feature. */
+    duplicates: number;
+    /** True if the import was capped by `maxFeatures` / internal safety limits. */
+    truncated: boolean;
+}
+/**
+ * Options of the ref's data-changing methods (`addFeature`, `updateFeature(s)`, `removeFeatures`).
+ */
+export interface MutationOptions {
+    /**
+     * Default `true`: the change is one undo step, like the same edit made by the user.
+     * `false` (e.g. applying a change from your server): no undo step, and the change is also
+     * applied to every undo/redo snapshot, so undoing an earlier user edit doesn't revert it.
+     */
+    undoable?: boolean;
+}
+/** Options of `ref.setFeatureCollection`. */
+export interface SetFeatureCollectionOptions {
+    /**
+     * Default `false`: the load fires `onChange` (and `onFeatureAdd` / `onFeatureUpdate` /
+     * `onFeatureDelete`) like any other change. `true`: those callbacks don't fire for this load,
+     * so data you just fetched from your backend isn't saved straight back. `onSelectionChange`
+     * still fires when the load clears a selection.
+     */
+    silent?: boolean;
+    /**
+     * Default `true`: the load is one undo step (undo restores the previous data). `false`: no undo
+     * step, and the undo/redo history is cleared, so the user can't undo back past the loaded data
+     * (what `initialData` does).
+     */
+    undoable?: boolean;
+}
+/** What `ref.validate()` returns. */
+export interface ValidationReport {
+    /** `true` when no feature has a validation error. */
+    valid: boolean;
+    /**
+     * Error messages per feature id, only for features that have errors (e.g.
+     * `'Missing required property: Owner'`): the same object `onValidationError` receives.
+     */
+    errors: Record<string, string[]>;
+}
+/**
+ * Imperative handle of `<ElementEditor ref>` and both adapters' `<ElementEditorControls ref>`.
+ * Coordinates are GeoJSON order, `[lng, lat]`, unless a method says otherwise.
+ * Map methods (`flyTo`, `setZoom`, `fitBounds`, `select`'s `fit`) do nothing until the map has mounted.
+ *
+ * Data-changing methods go through the same store actions as the UI: `maxFeatures`, schema
+ * validation, undo and the `onChange` / `onFeature*` / `onSelectionChange` callbacks behave as
+ * for the user's own edits (callbacks fire synchronously, before the method returns). They work
+ * in `readonly` mode too (the host app is in charge); only `setTool` is refused there.
+ *
+ * `TMap` is the engine's map type: `maplibregl.Map` on `@element-editor/react` and
+ * `@element-editor/adapter-maplibre`, `L.Map` on `@element-editor/react/leaflet` and
+ * `@element-editor/adapter-leaflet`.
+ */
+export interface ElementEditorImperativeAPI<TMap = unknown> {
+    /**
+     * Snapshot of the current data as a FeatureCollection: every feature (hidden ones included,
+     * internal validation state stripped) plus `metadata.schemas` / `metadata.groups`.
+     */
+    getFeatureCollection: () => FeatureCollection;
+    /**
+     * One feature by id, as `getFeatureCollection()` would return it (hidden features included), or
+     * `null` for an unknown id.
+     */
+    getFeature: (id: string) => GeoJSONFeature | null;
+    /**
+     * Replaces all data with `data` (like `importGeoJSON(data, 'replace')`). Plain GeoJSON is fine:
+     * missing ids get UUIDs, no `metadata` means the default schema. Features without a usable
+     * geometry (`geometry: null`, unknown types) are skipped and reported through `onError` /
+     * the `error` event.
+     *
+     * By default this fires `onChange` (and `onFeatureAdd` / `onFeatureDelete`) like any change and is
+     * one undo step. When you load data from your backend and save it in `onChange`, pass
+     * `{ silent: true }` so the load isn't saved straight back (see `SetFeatureCollectionOptions`).
+     *
+     * ```ts
+     * const fc = await (await fetch('/api/map')).json()
+     * ref.current?.setFeatureCollection(fc, { silent: true, undoable: false })
+     * ```
+     */
+    setFeatureCollection: (data: FeatureCollectionInput, options?: SetFeatureCollectionOptions) => void;
+    /** The current data serialised as a GeoJSON string (what "Export" downloads). */
+    exportGeoJSON: () => string;
+    /** Triggers a browser download of the current data. Only `'geojson'` is supported. */
+    exportAs: (format: 'geojson') => void;
+    /**
+     * Imports a FeatureCollection (or anything parseable as one). `'replace'` (default) swaps the
+     * data, `'merge'` appends. It is one undo step (undo restores the previous features, schemas and
+     * groups; no file backup). Returns counts of skipped (unsupported
+     * geometry) / duplicate (repeated id) features and whether the import was truncated
+     * (`maxFeatures` or the internal 50,000-feature limit).
+     */
+    importGeoJSON: (raw: FeatureCollectionInput | unknown, mode?: 'replace' | 'merge') => ImportResult;
+    /**
+     * Updates many features in one commit: one store update, one `onChange`, and `onFeatureUpdate`
+     * once per feature whose geometry or properties changed. Each `patch` may set `properties`
+     * (replaces the whole object), `geometry`, `schemaId` or `hidden`; features are re-validated
+     * against their schema. The batch is one undo step (see `MutationOptions.undoable`). Unknown ids
+     * and malformed patches are skipped (with a development warning).
+     *
+     * ```ts
+     * ref.current.updateFeatures(ids.map((id) => ({ id, patch: { properties: { ...props(id), status: 'done' } } })))
+     * ```
+     */
+    updateFeatures: (updates: ReadonlyArray<{
+        id: string;
+        patch: FeaturePatch;
+    }>, options?: MutationOptions) => void;
+    /**
+     * Adds a feature and returns it as stored (with its `id`; a missing id gets a UUID), or `null`
+     * when nothing was added: the geometry isn't valid GeoJSON, the id is already used (both warn
+     * in development), or `maxFeatures` is reached (reported like a user add). The feature goes on
+     * top of the layer list; the selection is left alone. `groupId` is kept only if that group exists.
+     * Fires `onFeatureAdd` and `onChange`.
+     */
+    addFeature: (feature: GeoJSONFeatureInput, options?: MutationOptions) => GeoJSONFeature | null;
+    /**
+     * Updates one feature. `patch` may set `properties` (replaces the whole object), `geometry`,
+     * `schemaId` or `hidden`; other keys are ignored. The feature is re-validated against its schema
+     * (schema errors don't block the write). Returns `false`, changing nothing, for an unknown id or
+     * a malformed patch (both warn in development). Fires `onFeatureUpdate` and `onChange`.
+     */
+    updateFeature: (id: string, patch: FeaturePatch, options?: MutationOptions) => boolean;
+    /**
+     * Removes the features with these ids in one undo step and returns how many were removed
+     * (unknown ids are skipped, with a development warning). Removed ids leave the selection.
+     * Fires `onFeatureDelete` per feature and `onChange` once.
+     */
+    removeFeatures: (ids: string[], options?: MutationOptions) => number;
+    /** Ids of the selected features (a copy). */
+    getSelection: () => string[];
+    /**
+     * Replaces the selection with these features (`[]` clears it) and fires `onSelectionChange`.
+     * Unknown ids, group ids and hidden features (or features in a hidden group) are left out, with a
+     * development warning. `fit: true` also fits the map to the selected features.
+     */
+    select: (ids: string[], options?: {
+        fit?: boolean;
+    }) => void;
+    /**
+     * Turns a drawing tool on, as its toolbar button does (an unfinished shape of another tool is
+     * discarded); `null` turns the active tool off. Returns `false`, changing nothing, when the tool
+     * isn't available: unknown or `'search'`, left out by `tools`, `maxFeatures` reached (tools that
+     * add features), or `readonly` (every tool but `'measure'`, which the readonly toolbar keeps).
+     */
+    setTool: (tool: DrawTool | null) => boolean;
+    /**
+     * The drawing tool that is on (as `setTool` takes it), or `null` when none is. Shape operations
+     * (cut, slice, simplify, smooth, buffer) aren't tools: `null` while they run.
+     */
+    getTool: () => DrawTool | null;
+    /** `true` when `undo()` would change something (there is an edit to undo). */
+    canUndo: () => boolean;
+    /** `true` when `redo()` would change something (there is an undone edit to redo). */
+    canRedo: () => boolean;
+    /**
+     * Validates every feature against its schema (required fields, number `min` / `max`) and its
+     * geometry (zero-area polygons), and returns the result. Changes nothing and calls no callback:
+     * use it to check before your own save, or to show errors. `submit()` runs the same check.
+     *
+     * ```ts
+     * const { valid, errors } = ref.current!.validate()
+     * if (!valid) ref.current!.select(Object.keys(errors), { fit: true })
+     * ```
+     */
+    validate: () => ValidationReport;
+    /**
+     * The underlying map: `maplibregl.Map` or `L.Map` (see `TMap`), or `null` until the map has
+     * mounted (the MapLibre drop-in creates it once its basemap style has loaded).
+     *
+     * On a MapLibre map, switch basemaps with the `basemap` prop or `setBasemap`: they keep your
+     * layers. After your own `map.setStyle()` Element restores its own layers; re-add yours on `style.load`.
+     */
+    getMap: () => TMap | null;
+    /**
+     * Animates the map to a centre and zoom.
+     *
+     * - `flyTo({ center: [lng, lat], zoom? })` — preferred; GeoJSON order. Zoom defaults to 15.
+     * - `flyTo([lat, lng], zoom?)` — deprecated `[lat, lng]` tuple form; still works, warns once
+     *   in development.
+     */
+    flyTo: {
+        (options: FlyToOptions): void;
+        /** @deprecated `[lat, lng]` order. Use `flyTo({ center: [lng, lat], zoom })`. */
+        (latlng: [number, number], zoom?: number): void;
+    };
+    /**
+     * Sets the zoom immediately (no animation), clamped to the map's min/max zoom.
+     * Returns `false` when the map is not mounted yet (nothing happened), `true` otherwise.
+     */
+    setZoom: (zoom: number) => boolean;
+    /**
+     * Animates the map to fit a box, with padding, never zooming in past 16. Accepts:
+     *
+     * - a GeoJSON bbox `[minLng, minLat, maxLng, maxLat]` (= `[west, south, east, north]`), or
+     * - an array of `[lng, lat]` points (fits their bounding box).
+     *
+     * Empty input or input without finite coordinates is ignored.
+     */
+    fitBounds: (target: [number, number][] | [number, number, number, number]) => void;
+    /**
+     * Validates every feature (as `validate()` does), then submits. Returns `false` if any feature
+     * has validation errors: `onValidationError` is called with them (keyed by feature id) and
+     * `onSubmit` is not. Returns `true` when the data is valid: `onSubmit` (if set) is called
+     * with the current FeatureCollection.
+     */
+    submit: () => boolean;
+    /** Undoes the last edit (no-op when there is nothing to undo; see `canUndo`). */
+    undo: () => void;
+    /** Redoes the last undone edit (no-op when there is nothing to redo; see `canRedo`). */
+    redo: () => void;
+    /** Deselects all features. */
+    clearSelection: () => void;
+}
+export interface UseAdapterControlsOptions {
+    /**
+     * Plain GeoJSON is fine (see `FeatureCollectionInput`); a single Feature is wrapped in a collection.
+     * Applied on mount. A value that arrives later (`null` / `undefined` → data, e.g. after a fetch) is
+     * applied once too, if the editor is still empty and unedited; any other change is ignored, with a
+     * development warning.
+     */
+    initialData?: FeatureCollectionInput | GeoJSONFeatureInput | null;
+    schema?: Schema;
+    layout?: 'panel' | 'minimal' | 'split';
+    readonly?: boolean;
+    tools?: DrawTool[] | null;
+    maxFeatures?: number;
+    /**
+     * The map engine; the adapters pass it. With it, the tools `config.network` turns off are
+     * synced to `uiStore.unavailableTools` (the Picker needs Overpass only on Leaflet).
+     */
+    engine?: 'leaflet' | 'maplibre';
+    onChange?: (data: FeatureCollection) => void;
+    onSubmit?: (data: FeatureCollection) => void;
+    onValidationError?: (errors: Record<string, string[]>) => void;
+    onFeatureAdd?: (feature: GeoJSONFeature) => void;
+    onFeatureUpdate?: (id: string, feature: GeoJSONFeature) => void;
+    onFeatureDelete?: (id: string) => void;
+    onSelectionChange?: (ids: string[]) => void;
+    onFeatureSelect?: (feature: GeoJSONFeature | null) => void;
+    onZoomChange?: (zoom: number) => void;
+    /** Called with the tool that turned on (as `ref.getTool()` reports it), or `null` when it turned off. */
+    onToolChange?: (tool: DrawTool | null) => void;
+    /**
+     * @internal Called after `initialData` was applied: `late` is true for data that arrived after
+     * mount. The drop-in uses it to fit the late data.
+     */
+    onInitialDataApplied?: (data: FeatureCollectionInput, late: boolean) => void;
+}
+/** The tools `network` turns off: no routing → Route, no geocoder → search, no Overpass → Picker on Leaflet (MapLibre still picks from the vector tiles). */
+export declare function networkUnavailableTools(network: {
+    routing?: unknown;
+    nominatim?: unknown;
+    overpass?: unknown;
+}, engine: 'leaflet' | 'maplibre'): string[];
+export declare function useAdapterControls<TMap = unknown>(opts: UseAdapterControlsOptions): ElementEditorImperativeAPI<TMap>;

package/dist/hooks/useBalancedWrap.d.cts

@@ -0,0 +1,8 @@
+import { RefObject } from 'react';
+/**
+ * `text-wrap: balance` for a `flex-wrap` toolbar: when its buttons don't fit
+ * on one row, it's narrowed to the least width that still needs no more rows,
+ * so a narrow screen shows 4 + 4 buttons rather than 7 + a lone Delete.
+ * Re-runs when the room around it or `key` (what the toolbar holds) changes.
+ */
+export declare function useBalancedWrap(ref: RefObject<HTMLElement | null>, key: unknown): void;

package/dist/hooks/useBalancedWrap.d.ts

@@ -0,0 +1,8 @@
+import { RefObject } from 'react';
+/**
+ * `text-wrap: balance` for a `flex-wrap` toolbar: when its buttons don't fit
+ * on one row, it's narrowed to the least width that still needs no more rows,
+ * so a narrow screen shows 4 + 4 buttons rather than 7 + a lone Delete.
+ * Re-runs when the room around it or `key` (what the toolbar holds) changes.
+ */
+export declare function useBalancedWrap(ref: RefObject<HTMLElement | null>, key: unknown): void;

package/dist/hooks/useContextMenu.d.cts

@@ -0,0 +1,11 @@
+interface ContextMenuState<T> {
+    x: number;
+    y: number;
+    data: T;
+}
+export declare function useContextMenu<T>(): {
+    state: ContextMenuState<T> | null;
+    open: (x: number, y: number, data: T) => void;
+    close: () => void;
+};
+export {};

package/dist/hooks/useContextMenu.d.ts

@@ -0,0 +1,11 @@
+interface ContextMenuState<T> {
+    x: number;
+    y: number;
+    data: T;
+}
+export declare function useContextMenu<T>(): {
+    state: ContextMenuState<T> | null;
+    open: (x: number, y: number, data: T) => void;
+    close: () => void;
+};
+export {};

package/dist/hooks/useDataChangeSubscription.d.cts

@@ -0,0 +1,9 @@
+import { StoreApi } from 'zustand';
+import { DataStore, DataChangeCallbacks } from '@element-editor/core';
+/**
+ * React wrapper around `subscribeToDataChanges`. Owns the callback ref
+ * plumbing so hosts can pass a fresh object each render without resubscribing.
+ *
+ * The subscription only tears down when `store` itself changes.
+ */
+export declare function useDataChangeSubscription(store: StoreApi<DataStore>, callbacks: DataChangeCallbacks): void;

package/dist/hooks/useDataChangeSubscription.d.ts

@@ -0,0 +1,9 @@
+import { StoreApi } from 'zustand';
+import { DataStore, DataChangeCallbacks } from '@element-editor/core';
+/**
+ * React wrapper around `subscribeToDataChanges`. Owns the callback ref
+ * plumbing so hosts can pass a fresh object each render without resubscribing.
+ *
+ * The subscription only tears down when `store` itself changes.
+ */
+export declare function useDataChangeSubscription(store: StoreApi<DataStore>, callbacks: DataChangeCallbacks): void;

package/dist/hooks/useDragWindow.d.cts

@@ -0,0 +1,9 @@
+interface Position {
+    x: number;
+    y: number;
+}
+export declare function useDragWindow(storageKey: string, defaultPos: Position): {
+    pos: Position;
+    onHandleMouseDown: (e: React.MouseEvent) => void;
+};
+export {};

package/dist/hooks/useDragWindow.d.ts

@@ -0,0 +1,9 @@
+interface Position {
+    x: number;
+    y: number;
+}
+export declare function useDragWindow(storageKey: string, defaultPos: Position): {
+    pos: Position;
+    onHandleMouseDown: (e: React.MouseEvent) => void;
+};
+export {};

package/dist/hooks/useFocusTrap.d.cts

@@ -0,0 +1,7 @@
+import { RefObject } from 'react';
+/**
+ * Traps keyboard focus within a container element.
+ * Tab and Shift+Tab cycle through focusable elements without leaving the container.
+ * Automatically focuses the first focusable element on mount.
+ */
+export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, enabled?: boolean): void;

package/dist/hooks/useFocusTrap.d.ts

@@ -0,0 +1,7 @@
+import { RefObject } from 'react';
+/**
+ * Traps keyboard focus within a container element.
+ * Tab and Shift+Tab cycle through focusable elements without leaving the container.
+ * Automatically focuses the first focusable element on mount.
+ */
+export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, enabled?: boolean): void;

package/dist/hooks/useGeoJSONDrop.d.cts

@@ -0,0 +1,40 @@
+import { DragEvent as ReactDragEvent, ChangeEvent } from 'react';
+import { FeatureCollection, ParseGeoJSONError } from '@element-editor/core';
+export type GeoJSONDropError = {
+    kind: 'wrong-type';
+    file: File;
+} | ParseGeoJSONError;
+export interface UseGeoJSONDropOptions {
+    /** Called with the parsed FeatureCollection + original File handle. */
+    onImport: (fc: FeatureCollection, file: File) => void;
+    /** Called for any reject reason (wrong MIME/extension, too big, malformed, not a FC). */
+    onError?: (err: GeoJSONDropError) => void;
+    /** Max accepted byte length of the file. Defaults to core's DEFAULT_MAX_IMPORT_BYTES (100 MB). */
+    maxBytes?: number;
+    /** File extensions + MIME types to accept. Defaults to `.geojson`, `.json`, and their MIME equivalents. */
+    accept?: string[];
+    /** When true, drag/drop + file picker become no-ops and `isDragActive` stays false. */
+    disabled?: boolean;
+}
+export interface UseGeoJSONDropReturn {
+    getRootProps: () => {
+        onDragEnter: (e: ReactDragEvent) => void;
+        onDragOver: (e: ReactDragEvent) => void;
+        onDragLeave: (e: ReactDragEvent) => void;
+        onDrop: (e: ReactDragEvent) => void;
+    };
+    getInputProps: () => {
+        type: 'file';
+        accept: string;
+        style: {
+            display: 'none';
+        };
+        ref: (el: HTMLInputElement | null) => void;
+        onChange: (e: ChangeEvent<HTMLInputElement>) => void;
+    };
+    isDragActive: boolean;
+    isProcessing: boolean;
+    /** Programmatically open the native file picker. No-op when `disabled`. */
+    open: () => void;
+}
+export declare function useGeoJSONDrop(options: UseGeoJSONDropOptions): UseGeoJSONDropReturn;

package/dist/hooks/useGeoJSONDrop.d.ts

@@ -0,0 +1,40 @@
+import { DragEvent as ReactDragEvent, ChangeEvent } from 'react';
+import { FeatureCollection, ParseGeoJSONError } from '@element-editor/core';
+export type GeoJSONDropError = {
+    kind: 'wrong-type';
+    file: File;
+} | ParseGeoJSONError;
+export interface UseGeoJSONDropOptions {
+    /** Called with the parsed FeatureCollection + original File handle. */
+    onImport: (fc: FeatureCollection, file: File) => void;
+    /** Called for any reject reason (wrong MIME/extension, too big, malformed, not a FC). */
+    onError?: (err: GeoJSONDropError) => void;
+    /** Max accepted byte length of the file. Defaults to core's DEFAULT_MAX_IMPORT_BYTES (100 MB). */
+    maxBytes?: number;
+    /** File extensions + MIME types to accept. Defaults to `.geojson`, `.json`, and their MIME equivalents. */
+    accept?: string[];
+    /** When true, drag/drop + file picker become no-ops and `isDragActive` stays false. */
+    disabled?: boolean;
+}
+export interface UseGeoJSONDropReturn {
+    getRootProps: () => {
+        onDragEnter: (e: ReactDragEvent) => void;
+        onDragOver: (e: ReactDragEvent) => void;
+        onDragLeave: (e: ReactDragEvent) => void;
+        onDrop: (e: ReactDragEvent) => void;
+    };
+    getInputProps: () => {
+        type: 'file';
+        accept: string;
+        style: {
+            display: 'none';
+        };
+        ref: (el: HTMLInputElement | null) => void;
+        onChange: (e: ChangeEvent<HTMLInputElement>) => void;
+    };
+    isDragActive: boolean;
+    isProcessing: boolean;
+    /** Programmatically open the native file picker. No-op when `disabled`. */
+    open: () => void;
+}
+export declare function useGeoJSONDrop(options: UseGeoJSONDropOptions): UseGeoJSONDropReturn;

package/dist/hooks/useGeoJSONExport.d.cts

@@ -0,0 +1,69 @@
+import { FeatureCollection } from '@element-editor/core';
+/**
+ * Headless primitive for exporting the current Element state as GeoJSON.
+ * Symmetric to {@link useGeoJSONDrop}: the caller supplies a way to read the
+ * current FeatureCollection, the hook handles serialization, filename, Blob
+ * construction, and the programmatic anchor-click download.
+ *
+ * Three return shapes because different apps want different things:
+ *   - `exportToFile()` — trigger a browser download (the 99% path).
+ *   - `exportToString()` — POST the text to a backend, copy to clipboard, etc.
+ *   - `exportToBlob()` — wrap in FormData, upload as multipart, pipe to a
+ *     Worker, hand off to `navigator.share`, etc.
+ *
+ * All three share the same serialization and error handling.
+ */
+export type GeoJSONExportError = {
+    kind: 'empty';
+} | {
+    kind: 'serialization-error';
+    cause: Error;
+};
+export interface UseGeoJSONExportOptions {
+    /**
+     * Returns the FeatureCollection to export. Read lazily on every call so
+     * the hook doesn't re-render when features mutate. Typical usage:
+     * `() => ref.current?.getFeatureCollection()`.
+     */
+    getFeatureCollection: () => FeatureCollection | null | undefined;
+    /**
+     * File name (without extension) or a function of the FC. Default: "features".
+     * The `.geojson` extension is appended automatically.
+     */
+    filename?: string | ((fc: FeatureCollection) => string);
+    /**
+     * Called after the user has CONFIRMED the save (Chromium's
+     * `showSaveFilePicker` resolved with a chosen path). Great for toasts.
+     *
+     * Note: in Firefox / Safari the legacy `<a download>` flow has no
+     * confirmation signal, so `onExport` is NOT called there — a pre-mature
+     * "exported!" toast for an action the user may have cancelled in the OS
+     * Save dialog is worse than no toast. See {@link saveGeoJSONFile}.
+     */
+    onExport?: (fc: FeatureCollection, file: {
+        name: string;
+        bytes: number;
+    }) => void;
+    /** Called on empty FC or serialization errors. */
+    onError?: (err: GeoJSONExportError) => void;
+    /** Pretty-print indent. Default 2. Pass 0 for compact output. */
+    indent?: number;
+    /** When true, export methods become no-ops. Useful for readonly modes. */
+    disabled?: boolean;
+}
+export interface UseGeoJSONExportReturn {
+    /**
+     * Serialize, build a Blob, and trigger a browser download. Returns the
+     * suggested filename immediately (`null` only when there's nothing to
+     * export). Fires `onExport` ONLY after the user confirms the save in the
+     * OS dialog (Chromium); Firefox / Safari fall back to the legacy
+     * `<a download>` flow silently — see `onExport` doc above for why.
+     * Fires `onError({ kind: 'empty' })` when the FC has no features.
+     */
+    exportToFile: () => string | null;
+    /** Return the serialized GeoJSON text, or `null` if the FC is empty. */
+    exportToString: () => string | null;
+    /** Return a `Blob` of the serialized GeoJSON, or `null` if the FC is empty. */
+    exportToBlob: () => Blob | null;
+}
+export declare function useGeoJSONExport(options: UseGeoJSONExportOptions): UseGeoJSONExportReturn;

package/dist/hooks/useGeoJSONExport.d.ts

@@ -0,0 +1,69 @@
+import { FeatureCollection } from '@element-editor/core';
+/**
+ * Headless primitive for exporting the current Element state as GeoJSON.
+ * Symmetric to {@link useGeoJSONDrop}: the caller supplies a way to read the
+ * current FeatureCollection, the hook handles serialization, filename, Blob
+ * construction, and the programmatic anchor-click download.
+ *
+ * Three return shapes because different apps want different things:
+ *   - `exportToFile()` — trigger a browser download (the 99% path).
+ *   - `exportToString()` — POST the text to a backend, copy to clipboard, etc.
+ *   - `exportToBlob()` — wrap in FormData, upload as multipart, pipe to a
+ *     Worker, hand off to `navigator.share`, etc.
+ *
+ * All three share the same serialization and error handling.
+ */
+export type GeoJSONExportError = {
+    kind: 'empty';
+} | {
+    kind: 'serialization-error';
+    cause: Error;
+};
+export interface UseGeoJSONExportOptions {
+    /**
+     * Returns the FeatureCollection to export. Read lazily on every call so
+     * the hook doesn't re-render when features mutate. Typical usage:
+     * `() => ref.current?.getFeatureCollection()`.
+     */
+    getFeatureCollection: () => FeatureCollection | null | undefined;
+    /**
+     * File name (without extension) or a function of the FC. Default: "features".
+     * The `.geojson` extension is appended automatically.
+     */
+    filename?: string | ((fc: FeatureCollection) => string);
+    /**
+     * Called after the user has CONFIRMED the save (Chromium's
+     * `showSaveFilePicker` resolved with a chosen path). Great for toasts.
+     *
+     * Note: in Firefox / Safari the legacy `<a download>` flow has no
+     * confirmation signal, so `onExport` is NOT called there — a pre-mature
+     * "exported!" toast for an action the user may have cancelled in the OS
+     * Save dialog is worse than no toast. See {@link saveGeoJSONFile}.
+     */
+    onExport?: (fc: FeatureCollection, file: {
+        name: string;
+        bytes: number;
+    }) => void;
+    /** Called on empty FC or serialization errors. */
+    onError?: (err: GeoJSONExportError) => void;
+    /** Pretty-print indent. Default 2. Pass 0 for compact output. */
+    indent?: number;
+    /** When true, export methods become no-ops. Useful for readonly modes. */
+    disabled?: boolean;
+}
+export interface UseGeoJSONExportReturn {
+    /**
+     * Serialize, build a Blob, and trigger a browser download. Returns the
+     * suggested filename immediately (`null` only when there's nothing to
+     * export). Fires `onExport` ONLY after the user confirms the save in the
+     * OS dialog (Chromium); Firefox / Safari fall back to the legacy
+     * `<a download>` flow silently — see `onExport` doc above for why.
+     * Fires `onError({ kind: 'empty' })` when the FC has no features.
+     */
+    exportToFile: () => string | null;
+    /** Return the serialized GeoJSON text, or `null` if the FC is empty. */
+    exportToString: () => string | null;
+    /** Return a `Blob` of the serialized GeoJSON, or `null` if the FC is empty. */
+    exportToBlob: () => Blob | null;
+}
+export declare function useGeoJSONExport(options: UseGeoJSONExportOptions): UseGeoJSONExportReturn;

package/dist/hooks/useGeoJSONFileImport.d.cts

@@ -0,0 +1,24 @@
+import { ErrorCode } from '@element-editor/core';
+type ImportFn = (raw: unknown, mode: 'replace' | 'merge') => {
+    skipped: number;
+    duplicates: number;
+};
+/** Reads, parses and imports (replace) a GeoJSON file. Exported for tests; the UI uses `useGeoJSONFileImport`. */
+export declare function importGeoJSONFromFile(file: File, importFn: ImportFn, countAfter: () => number): Promise<{
+    ok: true;
+    count: number;
+    skipped: number;
+    duplicates: number;
+} | {
+    ok: false;
+    code: ErrorCode;
+    reason: string;
+    cause?: unknown;
+}>;
+/**
+ * The one user-initiated file import (Cmd+O, dropping a file on the map): replaces the data in one
+ * undo step (`maxFeatures` truncates and reports), fits the map to what was imported, and reports
+ * the result as events (toasts). Refused in readonly.
+ */
+export declare function useGeoJSONFileImport(): (file: File) => Promise<void>;
+export {};

package/dist/hooks/useGeoJSONFileImport.d.ts

@@ -0,0 +1,24 @@
+import { ErrorCode } from '@element-editor/core';
+type ImportFn = (raw: unknown, mode: 'replace' | 'merge') => {
+    skipped: number;
+    duplicates: number;
+};
+/** Reads, parses and imports (replace) a GeoJSON file. Exported for tests; the UI uses `useGeoJSONFileImport`. */
+export declare function importGeoJSONFromFile(file: File, importFn: ImportFn, countAfter: () => number): Promise<{
+    ok: true;
+    count: number;
+    skipped: number;
+    duplicates: number;
+} | {
+    ok: false;
+    code: ErrorCode;
+    reason: string;
+    cause?: unknown;
+}>;
+/**
+ * The one user-initiated file import (Cmd+O, dropping a file on the map): replaces the data in one
+ * undo step (`maxFeatures` truncates and reports), fits the map to what was imported, and reports
+ * the result as events (toasts). Refused in readonly.
+ */
+export declare function useGeoJSONFileImport(): (file: File) => Promise<void>;
+export {};