@element-editor/ui 0.0.0-stage → 0.2.0

package/dist/hooks/dragShield.d.cts

@@ -0,0 +1,7 @@
+/**
+ * Runs `fn` (a layout change) with editor transitions off until it has been
+ * painted, so everything it moves jumps in the same frame instead of some
+ * parts sliding 200 ms after others.
+ */
+export declare function withoutTransitions(fn: () => void): void;
+export declare function startDragShield(cursor: string, handle?: HTMLElement): () => void;

package/dist/hooks/dragShield.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Runs `fn` (a layout change) with editor transitions off until it has been
+ * painted, so everything it moves jumps in the same frame instead of some
+ * parts sliding 200 ms after others.
+ */
+export declare function withoutTransitions(fn: () => void): void;
+export declare function startDragShield(cursor: string, handle?: HTMLElement): () => void;

package/dist/hooks/themeInputs.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Watch everything that can change the CSS variables resolved on an editor root:
+ * the root's `style` / `class` / `data-elm-theme`, `<html>`'s `style` / `class`,
+ * stylesheets added to, removed from or edited in `<head>`, and `<link>` loads.
+ * Calls `onChange` (the caller batches it). Shared by `useAccentPalette` and
+ * `useRootTokens`.
+ *
+ * ponytail: CSSOM edits (insertRule, adoptedStyleSheets, constructable sheets)
+ * and <style> outside <head> fire no event; re-set a token on the root to nudge it.
+ */
+/** The root's theme-relevant inputs as one string: class, mode and inline style minus layout vars. */
+export declare const themeInputs: (root: Element | null) => string;
+/** Start watching; returns the cleanup. `onChange` may fire several times per frame: batch it. */
+export declare function watchThemeInputs(root: Element | null, onChange: () => void): () => void;

package/dist/hooks/themeInputs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Watch everything that can change the CSS variables resolved on an editor root:
+ * the root's `style` / `class` / `data-elm-theme`, `<html>`'s `style` / `class`,
+ * stylesheets added to, removed from or edited in `<head>`, and `<link>` loads.
+ * Calls `onChange` (the caller batches it). Shared by `useAccentPalette` and
+ * `useRootTokens`.
+ *
+ * ponytail: CSSOM edits (insertRule, adoptedStyleSheets, constructable sheets)
+ * and <style> outside <head> fire no event; re-set a token on the root to nudge it.
+ */
+/** The root's theme-relevant inputs as one string: class, mode and inline style minus layout vars. */
+export declare const themeInputs: (root: Element | null) => string;
+/** Start watching; returns the cleanup. `onChange` may fire several times per frame: batch it. */
+export declare function watchThemeInputs(root: Element | null, onChange: () => void): () => void;

package/dist/hooks/useAccentPalette.d.cts

@@ -0,0 +1,15 @@
+import { AccentPalette } from '@element-editor/core';
+/**
+ * The palette in effect for `el`, as the CSS resolves it (accent and any
+ * `--elm-primary-N` override), for map renderers that need concrete colours
+ * (Leaflet SVG attributes, MapLibre paint). Re-reads, once per frame at most,
+ * when the `style`/`class` of the nearest `[data-elm-theme]` ancestor or
+ * `<html>` changes, when `<head>` gains/loses/edits a stylesheet, or when a
+ * `<link>` finishes loading. Returns the same object while nothing changed.
+ * HTML (divIcons, marker elements) can use `var(--color-primary-N)` directly.
+ *
+ * ponytail: CSSOM edits (insertRule, adoptedStyleSheets, constructable sheets)
+ * and <style> outside <head> fire no event; re-set the accent on the root to
+ * nudge it if a host does that.
+ */
+export declare function useAccentPalette(el: HTMLElement | null): AccentPalette;

package/dist/hooks/useAccentPalette.d.ts

@@ -0,0 +1,15 @@
+import { AccentPalette } from '@element-editor/core';
+/**
+ * The palette in effect for `el`, as the CSS resolves it (accent and any
+ * `--elm-primary-N` override), for map renderers that need concrete colours
+ * (Leaflet SVG attributes, MapLibre paint). Re-reads, once per frame at most,
+ * when the `style`/`class` of the nearest `[data-elm-theme]` ancestor or
+ * `<html>` changes, when `<head>` gains/loses/edits a stylesheet, or when a
+ * `<link>` finishes loading. Returns the same object while nothing changed.
+ * HTML (divIcons, marker elements) can use `var(--color-primary-N)` directly.
+ *
+ * ponytail: CSSOM edits (insertRule, adoptedStyleSheets, constructable sheets)
+ * and <style> outside <head> fire no event; re-set the accent on the root to
+ * nudge it if a host does that.
+ */
+export declare function useAccentPalette(el: HTMLElement | null): AccentPalette;

package/dist/hooks/useAccentStyle.d.cts

@@ -0,0 +1,39 @@
+import { CSSProperties } from 'react';
+/**
+ * CSS custom properties the host set on the editor root (`<ElementEditor style>`), e.g.
+ * `--elm-accent` or a single `--elm-primary-N` shade. Body-level portals don't inherit
+ * them, so `useAccentStyle()` copies them onto each portal root. `<ElementEditor>`
+ * provides it; adapter users style their own root (see `useAccentStyle`).
+ */
+export declare const RootCssVarsContext: import('react').Context<CSSProperties | undefined>;
+/** Inline style that sets `--elm-accent`; undefined when no accent is configured (CSS default blue). */
+export declare function accentStyle(accent: string | undefined): CSSProperties | undefined;
+/**
+ * The editor root's theme for Element's body-level portals (modals, menus,
+ * tooltips, drag clones, toasts): `--elm-accent` and every design token
+ * (`--elm-surface`, `--elm-radius`, …) the integrator set. Portals sit outside
+ * the editor root and don't inherit its CSS variables, so each portal root
+ * spreads this into its `style`. The root must also carry `data-elm-theme`
+ * (or `data-elm-portal`): the shared.css blocks that hold the token defaults
+ * and derive `--color-primary-*` from `--elm-accent` are declared on those
+ * selectors, and a var only re-resolves where it's declared.
+ *
+ * Merges, later winning: `config.accentColor`; the tokens resolved on the
+ * editor root (RootTokensContext, so a stylesheet rule on the root such as
+ * `.my-editor[data-elm-theme="dark"] { --elm-surface: … }` reaches portals too);
+ * the CSS variables of `<ElementEditor style>` (RootCssVarsContext).
+ */
+export declare function useAccentStyle(): CSSProperties | undefined;
+/**
+ * Apply `config.accentColor` to the editor root for adapter users, whose
+ * themed root (`[data-elm-theme]`) is their own element, not one we render.
+ * `ElementEditorUIProvider` renders no DOM, so the provider can't style it; the
+ * adapters' `ElementEditorControls` call this with `map.getContainer()` instead,
+ * and the var goes on the nearest `[data-elm-theme]` ancestor (else the
+ * container). This finds the root wherever it sits in the host's tree.
+ *
+ * Skips when the root already has that exact inline value, e.g. `<ElementEditor>`
+ * sets it through React's `style`, so React keeps owning it there. Cleanup
+ * only removes a value this hook wrote.
+ */
+export declare function useApplyAccentToRoot(container: HTMLElement | null | undefined): void;

package/dist/hooks/useAccentStyle.d.ts

@@ -0,0 +1,39 @@
+import { CSSProperties } from 'react';
+/**
+ * CSS custom properties the host set on the editor root (`<ElementEditor style>`), e.g.
+ * `--elm-accent` or a single `--elm-primary-N` shade. Body-level portals don't inherit
+ * them, so `useAccentStyle()` copies them onto each portal root. `<ElementEditor>`
+ * provides it; adapter users style their own root (see `useAccentStyle`).
+ */
+export declare const RootCssVarsContext: import('react').Context<CSSProperties | undefined>;
+/** Inline style that sets `--elm-accent`; undefined when no accent is configured (CSS default blue). */
+export declare function accentStyle(accent: string | undefined): CSSProperties | undefined;
+/**
+ * The editor root's theme for Element's body-level portals (modals, menus,
+ * tooltips, drag clones, toasts): `--elm-accent` and every design token
+ * (`--elm-surface`, `--elm-radius`, …) the integrator set. Portals sit outside
+ * the editor root and don't inherit its CSS variables, so each portal root
+ * spreads this into its `style`. The root must also carry `data-elm-theme`
+ * (or `data-elm-portal`): the shared.css blocks that hold the token defaults
+ * and derive `--color-primary-*` from `--elm-accent` are declared on those
+ * selectors, and a var only re-resolves where it's declared.
+ *
+ * Merges, later winning: `config.accentColor`; the tokens resolved on the
+ * editor root (RootTokensContext, so a stylesheet rule on the root such as
+ * `.my-editor[data-elm-theme="dark"] { --elm-surface: … }` reaches portals too);
+ * the CSS variables of `<ElementEditor style>` (RootCssVarsContext).
+ */
+export declare function useAccentStyle(): CSSProperties | undefined;
+/**
+ * Apply `config.accentColor` to the editor root for adapter users, whose
+ * themed root (`[data-elm-theme]`) is their own element, not one we render.
+ * `ElementEditorUIProvider` renders no DOM, so the provider can't style it; the
+ * adapters' `ElementEditorControls` call this with `map.getContainer()` instead,
+ * and the var goes on the nearest `[data-elm-theme]` ancestor (else the
+ * container). This finds the root wherever it sits in the host's tree.
+ *
+ * Skips when the root already has that exact inline value, e.g. `<ElementEditor>`
+ * sets it through React's `style`, so React keeps owning it there. Cleanup
+ * only removes a value this hook wrote.
+ */
+export declare function useApplyAccentToRoot(container: HTMLElement | null | undefined): void;

package/dist/hooks/useAdapterControls.d.cts

@@ -0,0 +1,280 @@
+import { FeatureCollection, FeatureCollectionInput, FeaturePatch, FlyToOptions, GeoJSONFeature, GeoJSONFeatureInput, Schema } from '@element-editor/core';
+import { DrawTool } from '../contexts/ElementEditorConfigContext.cjs';
+/**
+ * `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>;