@sindicum/libre-draw 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,149 @@
+# LibreDraw
+
+[![npm version](https://img.shields.io/npm/v/%40sindicum%2Flibre-draw.svg)](https://www.npmjs.com/package/@sindicum/libre-draw)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+A polygon drawing and editing library for [MapLibre GL JS](https://maplibre.org/).
+
+## Features
+
+- **Zero-config** — `new LibreDraw(map)` gives you a full toolbar and drawing capabilities out of the box
+- **Draw polygons** — Click/tap to place vertices, double-click/double-tap to finish
+- **Select & edit** — Click a polygon to select it, drag vertices to reshape, drag midpoints to add vertices
+- **Polygon drag** — Drag an entire selected polygon to reposition it
+- **Undo / Redo** — Full history support for all operations
+- **GeoJSON in/out** — Import and export standard GeoJSON FeatureCollections
+- **Touch-first** — Designed for mobile with proper touch targets (44px+), long-press support, and gesture handling
+- **Self-intersection prevention** — Invalid geometries are rejected during editing
+- **Framework-agnostic** — Works with vanilla JS, React, Vue, or any framework
+- **TypeScript** — Full type definitions included
+- **Headless mode** — Disable the toolbar and drive everything via API
+
+## Quick Start
+
+```bash
+npm install @sindicum/libre-draw maplibre-gl
+```
+
+```typescript
+import maplibregl from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+import { LibreDraw } from '@sindicum/libre-draw';
+
+const map = new maplibregl.Map({
+  container: 'map',
+  style: 'https://demotiles.maplibre.org/style.json',
+  center: [0, 0],
+  zoom: 2,
+});
+
+const draw = new LibreDraw(map);
+
+draw.on('create', (e) => {
+  console.log('Polygon created:', e.feature);
+});
+
+draw.on('update', (e) => {
+  console.log('Polygon updated:', e.feature);
+});
+```
+
+## API
+
+### Constructor
+
+```typescript
+new LibreDraw(map: maplibregl.Map, options?: LibreDrawOptions)
+```
+
+### Methods
+
+| Method                    | Description                                           |
+| ------------------------- | ----------------------------------------------------- |
+| `setMode(mode)`           | Set active mode: `'idle'`, `'draw'`, or `'select'`    |
+| `getMode()`               | Get the current mode                                  |
+| `getFeatures()`           | Get all features as an array                          |
+| `getFeatureById(id)`      | Get a single feature by ID                            |
+| `setFeatures(geojson)`    | Replace all features with a GeoJSON FeatureCollection |
+| `addFeatures(features)`   | Add an array of GeoJSON Feature objects               |
+| `deleteFeature(id)`       | Delete a feature by ID (undoable)                     |
+| `selectFeature(id)`       | Programmatically select a feature                     |
+| `clearSelection()`        | Clear the current selection                           |
+| `getSelectedFeatureIds()` | Get IDs of selected features                          |
+| `undo()`                  | Undo the last action                                  |
+| `redo()`                  | Redo the last undone action                           |
+| `on(event, callback)`     | Register an event listener                            |
+| `off(event, callback)`    | Remove an event listener                              |
+| `destroy()`               | Clean up all resources                                |
+
+### Events
+
+| Event             | Payload                  | Description           |
+| ----------------- | ------------------------ | --------------------- |
+| `create`          | `{ feature }`            | A polygon was created |
+| `update`          | `{ feature }`            | A polygon was updated |
+| `delete`          | `{ feature }`            | A polygon was deleted |
+| `selectionchange` | `{ selectedIds }`        | Selection changed     |
+| `modechange`      | `{ mode, previousMode }` | Active mode changed   |
+
+### Options
+
+```typescript
+interface LibreDrawOptions {
+  toolbar?:
+    | boolean
+    | {
+        position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+        controls?: {
+          draw?: boolean;
+          select?: boolean;
+          delete?: boolean;
+          undo?: boolean;
+          redo?: boolean;
+        };
+      };
+  historyLimit?: number; // Default: 100
+}
+```
+
+Set `toolbar: false` for headless mode (API-only, no UI).
+
+## Documentation
+
+Full documentation with interactive demos is available at:
+
+**https://sindicum.github.io/libre-draw/**
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run dev server with example
+npm run dev
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+
+# Documentation site
+npm run docs:dev
+```
+
+## Requirements
+
+- MapLibre GL JS >= 3.0.0, v3.x and v4.x supported (peer dependency)
+- Modern browser with WebGL support
+
+## License
+
+[MIT](./LICENSE)

package/dist/LibreDraw.d.ts

@@ -0,0 +1,359 @@
+import type { Map as MaplibreMap } from 'maplibre-gl';
+import type { LibreDrawFeature, LibreDrawEventMap, LibreDrawOptions } from './types';
+import type { ModeName } from './core/ModeManager';
+/**
+ * LibreDraw - A MapLibre GL JS polygon drawing and editing library.
+ *
+ * This is the main facade class that wires together all internal modules
+ * (event bus, feature store, history, modes, input, rendering, toolbar)
+ * and exposes a clean public API.
+ *
+ * @example
+ * ```ts
+ * const draw = new LibreDraw(map, { toolbar: true });
+ * draw.setMode('draw');
+ * draw.on('create', (e) => console.log('Created:', e.feature));
+ * ```
+ */
+export declare class LibreDraw {
+    private map;
+    private eventBus;
+    private featureStore;
+    private historyManager;
+    private modeManager;
+    private inputHandler;
+    private sourceManager;
+    private renderManager;
+    private toolbar;
+    private selectMode;
+    private destroyed;
+    /**
+     * Create a new LibreDraw instance attached to a MapLibre GL JS map.
+     *
+     * Initializes all internal modules and sets up map integration.
+     * The instance is ready to use once the map's style is loaded.
+     *
+     * @param map - The MapLibre GL JS map instance to draw on.
+     * @param options - Configuration options. Defaults to toolbar enabled
+     *   and 100-action history limit.
+     *
+     * @example
+     * ```ts
+     * const draw = new LibreDraw(map);
+     * // Or with options:
+     * const draw = new LibreDraw(map, {
+     *   toolbar: { position: 'top-right' },
+     *   historyLimit: 50,
+     * });
+     * ```
+     */
+    constructor(map: MaplibreMap, options?: LibreDrawOptions);
+    /**
+     * Set the active drawing mode.
+     *
+     * Switching modes deactivates the current mode (clearing any
+     * in-progress state) and activates the new mode. A `'modechange'`
+     * event is emitted on every transition.
+     *
+     * @param mode - `'idle'` (no interaction), `'draw'` (create polygons),
+     *   or `'select'` (select/edit existing polygons).
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * draw.setMode('draw');
+     * draw.on('modechange', (e) => {
+     *   console.log(`${e.previousMode} -> ${e.mode}`);
+     * });
+     * ```
+     */
+    setMode(mode: ModeName): void;
+    /**
+     * Get the current drawing mode.
+     *
+     * @returns The active mode name: `'idle'`, `'draw'`, or `'select'`.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * if (draw.getMode() === 'draw') {
+     *   console.log('Currently drawing');
+     * }
+     * ```
+     */
+    getMode(): ModeName;
+    /**
+     * Get all features as an array.
+     *
+     * Returns a snapshot of all polygon features currently in the store.
+     *
+     * @returns An array of all {@link LibreDrawFeature} objects.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * const features = draw.getFeatures();
+     * console.log(`${features.length} polygons on the map`);
+     * ```
+     */
+    getFeatures(): LibreDrawFeature[];
+    /**
+     * Replace all features in the store with the given GeoJSON FeatureCollection.
+     *
+     * Validates the input, clears the current store and history, and
+     * re-renders the map. Undo/redo history is reset after this call.
+     *
+     * @param geojson - A GeoJSON FeatureCollection containing Polygon features.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     * @throws {LibreDrawError} If the input is not a valid FeatureCollection
+     *   or contains invalid polygon geometries.
+     *
+     * @example
+     * ```ts
+     * draw.setFeatures({
+     *   type: 'FeatureCollection',
+     *   features: [{
+     *     type: 'Feature',
+     *     geometry: {
+     *       type: 'Polygon',
+     *       coordinates: [[[0,0],[10,0],[10,10],[0,10],[0,0]]]
+     *     },
+     *     properties: {}
+     *   }]
+     * });
+     * ```
+     */
+    setFeatures(geojson: unknown): void;
+    /**
+     * Add features to the store from an array of GeoJSON Feature objects.
+     *
+     * Each feature is validated and added. Unlike {@link setFeatures},
+     * this does not clear existing features or history.
+     *
+     * @param features - An array of GeoJSON Feature objects with Polygon geometry.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     * @throws {LibreDrawError} If any feature has invalid geometry.
+     *
+     * @example
+     * ```ts
+     * draw.addFeatures([{
+     *   type: 'Feature',
+     *   geometry: {
+     *     type: 'Polygon',
+     *     coordinates: [[[0,0],[5,0],[5,5],[0,5],[0,0]]]
+     *   },
+     *   properties: { name: 'Zone A' }
+     * }]);
+     * ```
+     */
+    addFeatures(features: unknown[]): void;
+    /**
+     * Get the IDs of currently selected features.
+     *
+     * Returns selected IDs in select mode. In other modes, returns
+     * an empty array since selection is cleared on mode transition.
+     *
+     * @returns An array of selected feature IDs.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * draw.on('selectionchange', (e) => {
+     *   const ids = draw.getSelectedFeatureIds();
+     *   console.log('Selected:', ids);
+     * });
+     * ```
+     */
+    getSelectedFeatureIds(): string[];
+    /**
+     * Get a feature by its ID.
+     *
+     * @param id - The unique identifier of the feature.
+     * @returns The feature, or `undefined` if not found.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * const feature = draw.getFeatureById('abc-123');
+     * if (feature) {
+     *   console.log(feature.geometry.coordinates);
+     * }
+     * ```
+     */
+    getFeatureById(id: string): LibreDrawFeature | undefined;
+    /**
+     * Delete a feature by its ID.
+     *
+     * Removes the feature from the store, records a {@link DeleteAction}
+     * in the history (making it undoable), and emits a `'delete'` event.
+     * If the feature is currently selected, the selection is also cleared.
+     *
+     * @param id - The unique identifier of the feature to delete.
+     * @returns The deleted feature, or `undefined` if not found.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * const deleted = draw.deleteFeature('abc-123');
+     * if (deleted) {
+     *   draw.undo(); // restores the deleted feature
+     * }
+     * ```
+     */
+    deleteFeature(id: string): LibreDrawFeature | undefined;
+    /**
+     * Programmatically select a feature by its ID.
+     *
+     * Switches to select mode if not already active. The feature
+     * must exist in the store.
+     *
+     * @param id - The unique identifier of the feature to select.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     * @throws {LibreDrawError} If no feature with the given ID exists.
+     *
+     * @example
+     * ```ts
+     * draw.selectFeature('abc-123');
+     * console.log(draw.getSelectedFeatureIds()); // ['abc-123']
+     * console.log(draw.getMode()); // 'select'
+     * ```
+     */
+    selectFeature(id: string): void;
+    /**
+     * Clear the current feature selection.
+     *
+     * Deselects all features, removes vertex handles, and emits
+     * a `'selectionchange'` event. No-op if nothing is selected.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * draw.selectFeature('abc-123');
+     * draw.clearSelection();
+     * console.log(draw.getSelectedFeatureIds()); // []
+     * ```
+     */
+    clearSelection(): void;
+    /**
+     * Undo the last action.
+     *
+     * Reverts the most recent action (create, update, or delete) and
+     * updates the map rendering. If a feature is selected and its
+     * geometry changes, vertex handles are refreshed.
+     *
+     * @returns `true` if an action was undone, `false` if nothing to undo.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * if (draw.undo()) {
+     *   console.log('Action undone');
+     * }
+     * ```
+     */
+    undo(): boolean;
+    /**
+     * Redo the last undone action.
+     *
+     * Re-applies the most recently undone action. The redo stack is
+     * cleared whenever a new action is performed.
+     *
+     * @returns `true` if an action was redone, `false` if nothing to redo.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * draw.undo();
+     * draw.redo(); // re-applies the undone action
+     * ```
+     */
+    redo(): boolean;
+    /**
+     * Register an event listener.
+     *
+     * Supported events: `'create'`, `'update'`, `'delete'`,
+     * `'selectionchange'`, `'modechange'`.
+     *
+     * @param type - The event type to listen for.
+     * @param listener - The callback to invoke when the event fires.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * draw.on('create', (e) => console.log('Created:', e.feature.id));
+     * draw.on('update', (e) => console.log('Updated:', e.feature.id));
+     * draw.on('delete', (e) => console.log('Deleted:', e.feature.id));
+     * draw.on('selectionchange', (e) => console.log('Selected:', e.selectedIds));
+     * draw.on('modechange', (e) => console.log(`${e.previousMode} -> ${e.mode}`));
+     * ```
+     */
+    on<K extends keyof LibreDrawEventMap>(type: K, listener: (payload: LibreDrawEventMap[K]) => void): void;
+    /**
+     * Remove an event listener.
+     *
+     * The listener must be the same function reference passed to {@link on}.
+     *
+     * @param type - The event type to stop listening for.
+     * @param listener - The callback to remove.
+     *
+     * @throws {LibreDrawError} If this instance has been destroyed.
+     *
+     * @example
+     * ```ts
+     * const handler = (e: CreateEvent) => console.log(e.feature);
+     * draw.on('create', handler);
+     * draw.off('create', handler);
+     * ```
+     */
+    off<K extends keyof LibreDrawEventMap>(type: K, listener: (payload: LibreDrawEventMap[K]) => void): void;
+    /**
+     * Destroy the LibreDraw instance, cleaning up all resources.
+     *
+     * Switches to idle mode, removes all map layers/sources, clears
+     * the event bus, history, and feature store, and removes the toolbar.
+     * After calling destroy, all other methods will throw
+     * {@link LibreDrawError}. Calling destroy on an already-destroyed
+     * instance is a no-op.
+     *
+     * @example
+     * ```ts
+     * draw.destroy();
+     * // draw.getFeatures(); // throws LibreDrawError
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Initialize rendering and input handling after the map is ready.
+     */
+    private initialize;
+    /**
+     * Render all features from the store to the map.
+     */
+    private renderAllFeatures;
+    /**
+     * Create the toolbar UI.
+     */
+    private createToolbar;
+    /**
+     * Update toolbar undo/redo button states.
+     */
+    private updateToolbarHistoryState;
+    /**
+     * Assert that this instance has not been destroyed.
+     * @throws LibreDrawError if destroyed.
+     */
+    private assertNotDestroyed;
+}

package/dist/core/EventBus.d.ts

@@ -0,0 +1,37 @@
+import type { LibreDrawEventMap } from '../types/events';
+/**
+ * A listener callback for a given event type.
+ */
+type Listener<T> = (payload: T) => void;
+/**
+ * Type-safe event bus for LibreDraw events.
+ *
+ * Supports registering, removing, and emitting events
+ * defined in LibreDrawEventMap.
+ */
+export declare class EventBus {
+    private listeners;
+    /**
+     * Register a listener for a specific event type.
+     * @param type - The event type to listen for.
+     * @param listener - The callback to invoke when the event fires.
+     */
+    on<K extends keyof LibreDrawEventMap>(type: K, listener: Listener<LibreDrawEventMap[K]>): void;
+    /**
+     * Remove a listener for a specific event type.
+     * @param type - The event type to stop listening for.
+     * @param listener - The callback to remove.
+     */
+    off<K extends keyof LibreDrawEventMap>(type: K, listener: Listener<LibreDrawEventMap[K]>): void;
+    /**
+     * Emit an event, invoking all registered listeners.
+     * @param type - The event type to emit.
+     * @param payload - The event payload.
+     */
+    emit<K extends keyof LibreDrawEventMap>(type: K, payload: LibreDrawEventMap[K]): void;
+    /**
+     * Remove all listeners for all event types.
+     */
+    removeAllListeners(): void;
+}
+export {};

package/dist/core/FeatureStore.d.ts

@@ -0,0 +1,68 @@
+import type { LibreDrawFeature, FeatureStoreInterface } from '../types/features';
+/**
+ * A GeoJSON FeatureCollection containing LibreDraw polygons.
+ */
+export interface FeatureCollection {
+    type: 'FeatureCollection';
+    features: LibreDrawFeature[];
+}
+/**
+ * Internal store for managing LibreDraw features.
+ *
+ * Features are stored in a Map keyed by their unique ID.
+ * Implements FeatureStoreInterface so that Action objects
+ * can manipulate the store.
+ */
+export declare class FeatureStore implements FeatureStoreInterface {
+    private features;
+    /**
+     * Add a feature to the store. If the feature has no ID,
+     * a new UUID will be generated.
+     * @param feature - The feature to add.
+     * @returns The added feature (with ID assigned).
+     */
+    add(feature: LibreDrawFeature): LibreDrawFeature;
+    /**
+     * Update a feature in the store by ID.
+     * @param id - The ID of the feature to update.
+     * @param feature - The new feature data.
+     */
+    update(id: string, feature: LibreDrawFeature): void;
+    /**
+     * Remove a feature from the store by ID.
+     * @param id - The ID of the feature to remove.
+     * @returns The removed feature, or undefined if not found.
+     */
+    remove(id: string): LibreDrawFeature | undefined;
+    /**
+     * Get all features in the store.
+     * @returns An array of all features.
+     */
+    getAll(): LibreDrawFeature[];
+    /**
+     * Get a feature by its ID.
+     * @param id - The feature ID.
+     * @returns The feature, or undefined if not found.
+     */
+    getById(id: string): LibreDrawFeature | undefined;
+    /**
+     * Remove all features from the store.
+     */
+    clear(): void;
+    /**
+     * Replace all features in the store with the given array.
+     * @param features - The features to set.
+     */
+    setAll(features: LibreDrawFeature[]): void;
+    /**
+     * Export all features as a GeoJSON FeatureCollection.
+     * @returns A GeoJSON FeatureCollection.
+     */
+    toGeoJSON(): FeatureCollection;
+    /**
+     * Create a deep clone of a feature suitable for history snapshots.
+     * @param feature - The feature to clone.
+     * @returns A deep-cloned feature.
+     */
+    static cloneFeature(feature: LibreDrawFeature): LibreDrawFeature;
+}

package/dist/core/HistoryManager.d.ts

@@ -0,0 +1,47 @@
+import type { Action, FeatureStoreInterface } from '../types/features';
+/**
+ * Manages undo/redo history using an action-based stack.
+ *
+ * Each action knows how to apply and revert itself on the feature store.
+ * A configurable limit prevents unbounded memory growth.
+ */
+export declare class HistoryManager {
+    private undoStack;
+    private redoStack;
+    private readonly limit;
+    /**
+     * Create a new HistoryManager.
+     * @param limit - Maximum number of actions to retain. Defaults to 100.
+     */
+    constructor(limit?: number);
+    /**
+     * Push a new action onto the history stack.
+     * Clears the redo stack since a new action invalidates any redo history.
+     * @param action - The action to record.
+     */
+    push(action: Action): void;
+    /**
+     * Undo the most recent action.
+     * @param store - The feature store to revert the action on.
+     * @returns True if an action was undone, false if the stack was empty.
+     */
+    undo(store: FeatureStoreInterface): boolean;
+    /**
+     * Redo the most recently undone action.
+     * @param store - The feature store to re-apply the action on.
+     * @returns True if an action was redone, false if the stack was empty.
+     */
+    redo(store: FeatureStoreInterface): boolean;
+    /**
+     * Whether there are actions that can be undone.
+     */
+    canUndo(): boolean;
+    /**
+     * Whether there are actions that can be redone.
+     */
+    canRedo(): boolean;
+    /**
+     * Clear all history.
+     */
+    clear(): void;
+}