terra-draw 0.0.1-alpha.6 → 0.0.1-alpha.60

package/.devcontainer/Dockerfile

@@ -0,0 +1,8 @@
+ARG NODE_MAJOR_VERSION
+
+FROM mcr.microsoft.com/devcontainers/javascript-node:${NODE_MAJOR_VERSION}
+
+ENV EDITOR="code -w" VISUAL="code -w" CHOKIDAR_USEPOLLING="1"
+
+# uncomment to install additional npm packages
+# RUN su node -c 'npm i -g cowsay@1.5.0'

package/.devcontainer/devcontainer.json

@@ -0,0 +1,21 @@
+{
+	"name": "terra-draw",
+	"dockerFile": "Dockerfile",
+	"build": {
+		"args": { "NODE_MAJOR_VERSION": "18" }
+	},
+	"postCreateCommand": [".devcontainer/post-create.sh"],
+	"portsAttributes": {
+		"3000": { "label": "Docs" },
+		"9000": { "label": "Development" }
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"dbaeumer.vscode-eslint",
+				"esbenp.prettier-vscode",
+				"mikestead.dotenv"
+			]
+		}
+	}
+}

package/.devcontainer/post-create.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+set -eo pipefail
+
+# when in a VS Code or GitHub Codespaces devcontainer
+if [ -n "${REMOTE_CONTAINERS}" ] || [ -n "${CODESPACES}" ]; then
+	this_dir=$(cd -P -- "$(dirname -- "$(command -v -- "$0")")" && pwd -P)
+	workspace_root=$(realpath ${this_dir}/..)
+
+	# perform additional one-time setup just after
+	# the devcontainer is created
+	npm ci --prefix "${workspace_root}"             # install lib node dependencies
+	npm ci --prefix "${workspace_root}/development" # install dev node dependencies
+	touch "${workspace_root}/development/.env"      # ensure dev .env file exists
+
+fi

package/README.md

@@ -1,18 +1,42 @@
-<img src="docs/logo.png" alt="Terra Draw Logo" width="400"/>
+<img src="./logo.png" alt="Terra Draw Logo" width="400"/>
 
 ![Terra Draw CI Badge](https://github.com/JamesLMilner/terra-draw/actions/workflows/ci.yml/badge.svg)
+[![npm version](https://badge.fury.io/js/terra-draw.svg)](https://badge.fury.io/js/terra-draw)
 
 Frictionless map drawing across mapping libraries.
 
-TerraDraw centralises map drawing logic and provides a host of out the box drawing modes that work across map providers (currently Leaflet, Mapbox, Google) via adapters.
+Terra Draw centralizes map drawing logic and provides a host of out-of-the-box drawing modes that work across different JavaScript mapping libraries. It also allows you to bring your own modes!
 
-### Development
+![An example of drawing geodesic lines using Terra Draw with Leaflet](./readme.gif)
 
-Please see the [the development documentation](./DEVELOPMENT.md)
+### Library Support
 
-### Contributing
+Terra Draw uses the concept of 'adapters' to allow it to work with a host of different mapping libraries. Currently supported are:
 
-Please see the [the contributing documentation](./CONTRIBUTING.md)
+- [Leaflet](https://leafletjs.com/) v1
+- [OpenLayers](https://openlayers.org/) v7
+- [Mapbox GL JS](https://www.mapbox.com/mapbox-gljs) v2
+- [MapLibre](https://maplibre.org/projects/maplibre-gl-js/) v2/v3
+- [Google Maps JS API](https://developers.google.com/maps/documentation/javascript/overview) v3
+- [ArcGIS JavaScript SDK](https://developers.arcgis.com/javascript/latest/) v4 (MapView)
+
+### Getting Started
+
+Please see the [the getting started guide](./guides/1.GETTING_STARTED.md) - this provides a host of information on how to get up and running with Terra Draw.
+
+### Development & Contributing
+
+* For development, please see the [the development documentation](./guides/6.DEVELOPMENT.md)
+* For guidance on contributing, please see the [the contributing documentation](./guides/CONTRIBUTING.md)
+
+
+### Project Website
+
+You can check out the official Terra Draw website at [terradraw.io](https://www.terradraw.io). If you are interested in contributing to the website please see [this repository](https://www.github.com/JamesLMilner/terra-draw-website).
+
+### Contact
+
+Email: [contact@terradraw.io](mailto:contact@terradraw.io)
 
 ### License
 

package/dist/adapters/arcgis-maps-sdk.adapter.d.ts

@@ -0,0 +1,105 @@
+import { SetCursor, TerraDrawCallbacks, TerraDrawChanges, TerraDrawStylingFunction } from "../common";
+import { BaseAdapterConfig, TerraDrawBaseAdapter } from "./common/base.adapter";
+import MapView from "@arcgis/core/views/MapView";
+import Point from "@arcgis/core/geometry/Point";
+import Polyline from "@arcgis/core/geometry/Polyline";
+import Polygon from "@arcgis/core/geometry/Polygon";
+import GraphicsLayer from "@arcgis/core/layers/GraphicsLayer";
+import Graphic from "@arcgis/core/Graphic";
+import SimpleMarkerSymbol from "@arcgis/core/symbols/SimpleMarkerSymbol";
+import SimpleLineSymbol from "@arcgis/core/symbols/SimpleLineSymbol";
+import SimpleFillSymbol from "@arcgis/core/symbols/SimpleFillSymbol";
+import Color from "@arcgis/core/Color";
+type InjectableArcGISMapsSDK = {
+    GraphicsLayer: typeof GraphicsLayer;
+    Point: typeof Point;
+    Polyline: typeof Polyline;
+    Polygon: typeof Polygon;
+    SimpleLineSymbol: typeof SimpleLineSymbol;
+    SimpleMarkerSymbol: typeof SimpleMarkerSymbol;
+    SimpleFillSymbol: typeof SimpleFillSymbol;
+    Graphic: typeof Graphic;
+    Color: typeof Color;
+};
+export declare class TerraDrawArcGISMapsSDKAdapter extends TerraDrawBaseAdapter {
+    private readonly _lib;
+    private readonly _mapView;
+    private readonly _container;
+    private readonly _featureIdAttributeName;
+    private readonly _featureLayerName;
+    private readonly _featureLayer;
+    private _dragEnabled;
+    private _zoomEnabled;
+    private _dragHandler;
+    private _doubleClickHandler;
+    constructor(config: {
+        map: MapView;
+        lib: InjectableArcGISMapsSDK;
+    } & BaseAdapterConfig);
+    register(callbacks: TerraDrawCallbacks): void;
+    unregister(): void;
+    /**
+     * Returns the longitude and latitude coordinates from a given PointerEvent on the map.
+     * @param event The PointerEvent or MouseEvent  containing the screen coordinates of the pointer.
+     * @returns An object with 'lng' and 'lat' properties representing the longitude and latitude, or null if the conversion is not possible.
+     */
+    getLngLatFromEvent(event: PointerEvent | MouseEvent): {
+        lng: number;
+        lat: number;
+    };
+    /**
+     * Retrieves the HTML element of the ArcGIS element that handles interaction events
+     * @returns The HTMLElement representing the map container.
+     */
+    getMapEventElement(): HTMLElement;
+    /**
+     * Enables or disables the draggable functionality of the map.
+     * @param enabled Set to true to enable map dragging, or false to disable it.
+     */
+    setDraggability(enabled: boolean): void;
+    /**
+     * Converts longitude and latitude coordinates to pixel coordinates in the map container.
+     * @param lng The longitude coordinate to project.
+     * @param lat The latitude coordinate to project.
+     * @returns An object with 'x' and 'y' properties representing the pixel coordinates within the map container.
+     */
+    project(lng: number, lat: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Converts pixel coordinates in the map container to longitude and latitude coordinates.
+     * @param x The x-coordinate in the map container to unproject.
+     * @param y The y-coordinate in the map container to unproject.
+     * @returns An object with 'lng' and 'lat' properties representing the longitude and latitude coordinates.
+     */
+    unproject(x: number, y: number): {
+        lng: number;
+        lat: number;
+    };
+    /**
+     * Sets the cursor style for the map container.
+     * @param cursor The CSS cursor style to apply, or 'unset' to remove any previously applied cursor style.
+     */
+    setCursor(cursor: Parameters<SetCursor>[0]): void;
+    /**
+     * Enables or disables the double-click to zoom functionality on the map.
+     * @param enabled Set to true to enable double-click to zoom, or false to disable it.
+     */
+    setDoubleClickToZoom(enabled: boolean): void;
+    /**
+     * Renders GeoJSON features on the map using the provided styling configuration.
+     * @param changes An object containing arrays of created, updated, and unchanged features to render.
+     * @param styling An object mapping draw modes to feature styling functions
+     */
+    render(changes: TerraDrawChanges, styling: TerraDrawStylingFunction): void;
+    /**
+     * Clears the map and store of all rendered data layers
+     * @returns void
+     * */
+    clear(): void;
+    private removeFeatureById;
+    private addFeature;
+    private getColorFromHex;
+}
+export {};

package/dist/adapters/common/adapter-listener.d.ts

@@ -0,0 +1,22 @@
+export declare class AdapterListener<Callback extends (...args: any[]) => any> {
+    name: string;
+    callback: (...args: any[]) => any;
+    registered: boolean;
+    register: any;
+    unregister: any;
+    /**
+     * Creates a new AdapterListener instance with the provided configuration.
+     *
+     * @param {Object} config - The configuration object for the listener.
+     * @param {string} config.name - The name of the event listener.
+     * @param {Function} config.callback - The callback function to be called when the event is triggered.
+     * @param {Function} config.unregister - The function to unregister the event listeners.
+     * @param {Function} config.register - The function to register the event listeners.
+     */
+    constructor({ name, callback, unregister, register, }: {
+        name: string;
+        callback: Callback;
+        unregister: (callbacks: Callback) => void;
+        register: (callback: Callback) => void;
+    });
+}

package/dist/adapters/common/base.adapter.d.ts

@@ -0,0 +1,59 @@
+import { Project, Unproject, TerraDrawCallbacks, TerraDrawChanges, TerraDrawMouseEvent, SetCursor, TerraDrawStylingFunction, GetLngLatFromEvent } from "../../common";
+import { AdapterListener } from "./adapter-listener";
+type BasePointerListener = (event: PointerEvent) => void;
+type BaseKeyboardListener = (event: KeyboardEvent) => void;
+type BaseMouseListener = (event: MouseEvent) => void;
+export type BaseAdapterConfig = {
+    coordinatePrecision?: number;
+    minPixelDragDistanceDrawing?: number;
+    minPixelDragDistance?: number;
+    minPixelDragDistanceSelecting?: number;
+};
+export declare abstract class TerraDrawBaseAdapter {
+    constructor(config: BaseAdapterConfig);
+    protected _minPixelDragDistance: number;
+    protected _minPixelDragDistanceDrawing: number;
+    protected _minPixelDragDistanceSelecting: number;
+    protected _lastDrawEvent: TerraDrawMouseEvent | undefined;
+    protected _coordinatePrecision: number;
+    protected _heldKeys: Set<string>;
+    protected _listeners: AdapterListener<BasePointerListener | BaseKeyboardListener | BaseMouseListener>[];
+    protected _dragState: "not-dragging" | "pre-dragging" | "dragging";
+    protected _currentModeCallbacks: TerraDrawCallbacks | undefined;
+    protected abstract getMapEventElement(): HTMLElement;
+    protected getButton(event: PointerEvent | MouseEvent): "neither" | "left" | "middle" | "right";
+    protected getMapElementXYPosition(event: PointerEvent | MouseEvent): {
+        containerX: number;
+        containerY: number;
+    };
+    protected getDrawEventFromEvent(event: PointerEvent | MouseEvent): TerraDrawMouseEvent | null;
+    /**
+     * Registers the provided callbacks for the current drawing mode and attaches
+     * the necessary event listeners.
+     * @param {TerraDrawCallbacks} callbacks - An object containing callback functions
+     * for handling various drawing events in the current mode.
+     */
+    register(callbacks: TerraDrawCallbacks): void;
+    /**
+     * Gets the coordinate precision.
+     * @returns {number} The coordinate precision.
+     * @description The coordinate precision is the number of decimal places. Note that the precision will be overriden by the precision of the TerraDraw Adapter.
+     */
+    getCoordinatePrecision(): number;
+    private getAdapterListeners;
+    /**
+     * Unregisters the event listeners for the current drawing mode.
+     * This is typically called when switching between drawing modes or
+     * stopping the drawing process.
+     */
+    unregister(): void;
+    abstract clear(): void;
+    abstract project(...args: Parameters<Project>): ReturnType<Project>;
+    abstract unproject(...args: Parameters<Unproject>): ReturnType<Unproject>;
+    abstract setCursor(...args: Parameters<SetCursor>): ReturnType<SetCursor>;
+    abstract getLngLatFromEvent(...event: Parameters<GetLngLatFromEvent>): ReturnType<GetLngLatFromEvent>;
+    abstract setDraggability(enabled: boolean): void;
+    abstract setDoubleClickToZoom(enabled: boolean): void;
+    abstract render(changes: TerraDrawChanges, styling: TerraDrawStylingFunction): void;
+}
+export {};

package/dist/adapters/google-maps.adapter.d.ts

@@ -1,39 +1,90 @@
-/// <reference types="google.maps" />
-import { TerraDrawCallbacks, TerraDrawAdapter, TerraDrawModeRegisterConfig, TerraDrawAdapterStyling, TerraDrawChanges } from "../common";
-import { GeoJSONStoreFeatures } from "../store/store";
-export declare class TerraDrawGoogleMapsAdapter implements TerraDrawAdapter {
-    constructor(config: {
-        lib: typeof google.maps;
-        map: google.maps.Map;
-        coordinatePrecision?: number;
-    });
-    private _heldKeys;
-    private _cursor;
-    private _cursorStyleSheet;
-    private _coordinatePrecision;
-    private _lib;
-    private _map;
-    private _onMouseMoveListener;
-    private _onMouseMoveCallback;
-    private _onClickListener;
-    private _onRightClickListener;
-    private _onClickCallback;
-    private _onKeyUpListener;
-    private _onDragStartListener;
-    private _onDragListener;
-    private _onDragEndListener;
-    private _layers;
-    getMapContainer: () => HTMLElement;
-    unproject: (x: number, y: number) => {
-        lng: number;
-        lat: number;
-    };
-    project: TerraDrawModeRegisterConfig["project"];
-    setCursor: TerraDrawModeRegisterConfig["setCursor"];
-    private circlePath;
-    register(callbacks: TerraDrawCallbacks): void;
-    unregister(): void;
-    render(changes: TerraDrawChanges, styling: {
-        [mode: string]: (feature: GeoJSONStoreFeatures) => TerraDrawAdapterStyling;
-    }): void;
-}
+/// <reference types="google.maps" />
+import { TerraDrawChanges, SetCursor, TerraDrawStylingFunction, TerraDrawCallbacks } from "../common";
+import { BaseAdapterConfig, TerraDrawBaseAdapter } from "./common/base.adapter";
+export declare class TerraDrawGoogleMapsAdapter extends TerraDrawBaseAdapter {
+    constructor(config: {
+        lib: typeof google.maps;
+        map: google.maps.Map;
+    } & BaseAdapterConfig);
+    private _cursor;
+    private _cursorStyleSheet;
+    private _lib;
+    private _map;
+    private _overlay;
+    private _clickEventListener;
+    private _mouseMoveEventListener;
+    private get _layers();
+    /**
+     * Generates an SVG path string for a circle with the given center coordinates and radius.
+     * Based off this StackOverflow answer: https://stackoverflow.com/a/27905268/1363484
+     * @param cx The x-coordinate of the circle's center.
+     * @param cy The y-coordinate of the circle's center.
+     * @param r The radius of the circle.
+     * @returns The SVG path string representing the circle.
+     */
+    private circlePath;
+    register(callbacks: TerraDrawCallbacks): void;
+    unregister(): void;
+    /**
+     * Returns the longitude and latitude coordinates from a given PointerEvent on the map.
+     * @param event The PointerEvent or MouseEvent containing the screen coordinates of the pointer.
+     * @returns An object with 'lng' and 'lat' properties representing the longitude and latitude, or null if the conversion is not possible.
+     */
+    getLngLatFromEvent(event: PointerEvent | MouseEvent): {
+        lng: number;
+        lat: number;
+    } | null;
+    /**
+     * Retrieves the HTML element of the Google Map element that handles interaction events
+     * @returns The HTMLElement representing the map container.
+     */
+    getMapEventElement(): HTMLDivElement;
+    /**
+     * Converts longitude and latitude coordinates to pixel coordinates in the map container.
+     * @param lng The longitude coordinate to project.
+     * @param lat The latitude coordinate to project.
+     * @returns An object with 'x' and 'y' properties representing the pixel coordinates within the map container.
+     */
+    project(lng: number, lat: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Converts pixel coordinates in the map container to longitude and latitude coordinates.
+     * @param x The x-coordinate in the map container to unproject.
+     * @param y The y-coordinate in the map container to unproject.
+     * @returns An object with 'lng' and 'lat' properties representing the longitude and latitude coordinates.
+     */
+    unproject(x: number, y: number): {
+        lng: number;
+        lat: number;
+    };
+    /**
+     * Sets the cursor style for the map container.
+     * @param cursor The CSS cursor style to apply, or 'unset' to remove any previously applied cursor style.
+     */
+    setCursor(cursor: Parameters<SetCursor>[0]): void;
+    /**
+     * Enables or disables the double-click to zoom functionality on the map.
+     * @param enabled Set to true to enable double-click to zoom, or false to disable it.
+     */
+    setDoubleClickToZoom(enabled: boolean): void;
+    /**
+     * Enables or disables the draggable functionality of the map.
+     * @param enabled Set to true to enable map dragging, or false to disable it.
+     */
+    setDraggability(enabled: boolean): void;
+    private renderedFeatureIds;
+    /**
+     * Renders GeoJSON features on the map using the provided styling configuration.
+     * @param changes An object containing arrays of created, updated, and unchanged features to render.
+     * @param styling An object mapping draw modes to feature styling functions
+     */
+    render(changes: TerraDrawChanges, styling: TerraDrawStylingFunction): void;
+    private clearLayers;
+    /**
+     * Clears the map and store of all rendered data layers
+     * @returns void
+     * */
+    clear(): void;
+}

package/dist/adapters/leaflet.adapter.d.ts

@@ -1,33 +1,97 @@
-import { TerraDrawCallbacks, TerraDrawAdapter, TerraDrawModeRegisterConfig, TerraDrawAdapterStyling, TerraDrawChanges } from "../common";
-import L from "leaflet";
-import { GeoJSONStoreFeatures } from "../store/store";
-export declare class TerraDrawLeafletAdapter implements TerraDrawAdapter {
-    constructor(config: {
-        lib: typeof L;
-        map: L.Map;
-        coordinatePrecision?: number;
-    });
-    private _heldKeys;
-    private _lib;
-    private _coordinatePrecision;
-    private _map;
-    private _onMouseMoveListener;
-    private _onClickListener;
-    private _onKeyUpListener;
-    private _onKeyDownListener;
-    private _onDragStartListener;
-    private _onDragListener;
-    private _onDragEndListener;
-    private _layer;
-    private _panes;
-    project: TerraDrawModeRegisterConfig["project"];
-    unproject: TerraDrawModeRegisterConfig["unproject"];
-    setCursor: TerraDrawModeRegisterConfig["setCursor"];
-    getMapContainer: () => HTMLElement;
-    private createPaneStyleSheet;
-    register(callbacks: TerraDrawCallbacks): void;
-    unregister(): void;
-    render(changes: TerraDrawChanges, styling: {
-        [mode: string]: (feature: GeoJSONStoreFeatures) => TerraDrawAdapterStyling;
-    }): void;
-}
+import { TerraDrawChanges, SetCursor, TerraDrawStylingFunction, TerraDrawCallbacks } from "../common";
+import L from "leaflet";
+import { BaseAdapterConfig, TerraDrawBaseAdapter } from "./common/base.adapter";
+export declare class TerraDrawLeafletAdapter extends TerraDrawBaseAdapter {
+    constructor(config: {
+        lib: typeof L;
+        map: L.Map;
+    } & BaseAdapterConfig);
+    private _lib;
+    private _map;
+    private _panes;
+    private _container;
+    private _layers;
+    /**
+     * Creates a pane and its associated style sheet
+     * @param pane - The pane name
+     * @param zIndex - The zIndex value for the pane
+     * @returns The created style element
+     */
+    private createPaneStyleSheet;
+    /**
+     * Clears the panes created by the adapter
+     * @returns void
+     * */
+    private clearPanes;
+    /**
+     * Clears the leaflet layers created by the adapter
+     * @returns void
+     * */
+    private clearLayers;
+    /**
+     * Styles a GeoJSON layer based on the styling function
+     * @param styling - The styling function
+     * */
+    private styleGeoJSONLayer;
+    /**
+     * Returns the longitude and latitude coordinates from a given PointerEvent on the map.
+     * @param event The PointerEvent or MouseEvent  containing the screen coordinates of the pointer.
+     * @returns An object with 'lng' and 'lat' properties representing the longitude and latitude, or null if the conversion is not possible.
+     */
+    getLngLatFromEvent(event: PointerEvent | MouseEvent): {
+        lng: number;
+        lat: number;
+    } | null;
+    /**
+     * Retrieves the HTML element of the Leaflet element that handles interaction events
+     * @returns The HTMLElement representing the map container.
+     */
+    getMapEventElement(): HTMLElement;
+    /**
+     * Enables or disables the draggable functionality of the map.
+     * @param enabled Set to true to enable map dragging, or false to disable it.
+     */
+    setDraggability(enabled: boolean): void;
+    /**
+     * Converts longitude and latitude coordinates to pixel coordinates in the map container.
+     * @param lng The longitude coordinate to project.
+     * @param lat The latitude coordinate to project.
+     * @returns An object with 'x' and 'y' properties representing the pixel coordinates within the map container.
+     */
+    project(lng: number, lat: number): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Converts pixel coordinates in the map container to longitude and latitude coordinates.
+     * @param x The x-coordinate in the map container to unproject.
+     * @param y The y-coordinate in the map container to unproject.
+     * @returns An object with 'lng' and 'lat' properties representing the longitude and latitude coordinates.
+     */
+    unproject(x: number, y: number): {
+        lng: number;
+        lat: number;
+    };
+    /**
+     * Sets the cursor style for the map container.
+     * @param cursor The CSS cursor style to apply, or 'unset' to remove any previously applied cursor style.
+     */
+    setCursor(cursor: Parameters<SetCursor>[0]): void;
+    /**
+     * Enables or disables the double-click to zoom functionality on the map.
+     * @param enabled Set to true to enable double-click to zoom, or false to disable it.
+     */
+    setDoubleClickToZoom(enabled: boolean): void;
+    /**
+     * Renders GeoJSON features on the map using the provided styling configuration.
+     * @param changes An object containing arrays of created, updated, and unchanged features to render.
+     * @param styling An object mapping draw modes to feature styling functions
+     */
+    render(changes: TerraDrawChanges, styling: TerraDrawStylingFunction): void;
+    /**
+     * Clears the map and store of all rendered data layers
+     * @returns void
+     * */
+    clear(): void;
+    register(callbacks: TerraDrawCallbacks): void;
+}