terra-draw 0.0.1-alpha.43 → 0.0.1-alpha.45

package/guides/COMMON_PATTERNS.md

@@ -0,0 +1,157 @@
+# Common Patterns
+
+### Changing Mode
+
+To change mode we need to set the current mode to match the name of the mode we want. You can see the name of the mode in each modes 'mode' property in the modes source file. For convenience here are the built in mode names listed out:
+
+* TerraDrawStaticMode - 'static' 
+* TerraDrawPolygonMode - 'polygon'
+* TerraDrawPointMode - 'point'
+* TerraDrawCircleMode - 'circle'
+* TerraDrawLineStringMode - 'linestring'
+* TerraDrawSelectMode - 'select'
+* TerraDrawLineStringMode - 'freehand'
+* TerraDraqwGreatCircleMode - 'greatcircle'
+
+We can then create these modes and change to them like so:
+
+```typescript
+const draw = new TerraDraw({
+	adapter: new TerraDrawLeafletAdapter({
+		lib: L,
+		map,
+		coordinatePrecision: 9,
+	}),
+	modes: [
+		new TerraDrawPolygonMode(), // Polygon mode has a builtin name 'polygon'
+		new TerraDrawRenderMode({ modeName: 'arbitary' }) // Render modes are given custom names
+	],
+});
+
+draw.start();
+
+// Change to our TerraDrawPolygonMode instance
+draw.setMode('polygon')
+
+// We can use our custom render mode name to change to it.
+draw.setMode('arbitary') 
+
+```
+
+
+### Loading in External Data
+
+It is common pattern to want to load in data from an external source (GeoJSON file, API call, etc). This can be achieved with the `addFeatures` method on the Terra Draw instance. The method call works out which mode to add the feature based on looking at its `mode` property in the Features `properties` property. All modes have a method called `validateFeature` that ensures that a given feature is valid for the mode. For example if you wanted to add a series of points to the TerraDrawPointMode you could do this by ensuring that the points you feed in have the `mode` property set to `point`.
+
+```javascript
+points.forEach((point) => {
+	point.properties.mode = "point";
+});
+
+draw.addFeatures(points);
+```
+
+### Render Contextual Data with TerraDrawRenderMode
+
+If you just want to render some data onto the map without needing to add drawing data to it, you can use `TerraDrawRenderMode` in combination with `addFeatures` like so:
+
+```javascript
+const draw = new TerraDraw({
+	adapter: new TerraDrawLeafletAdapter({
+		lib: L,
+		map,
+		coordinatePrecision: 9,
+	}),
+	modes: [new TerraDrawRenderMode({ modeName: 'arbitary' })],
+});
+
+draw.start();
+
+points.forEach((point) => {
+	point.properties.mode = "arbitary";
+});
+
+draw.addFeatures(points);
+
+// This will add the points to hte TerraDrawRenderMode 'arbitary' rendering them to the screen
+```
+
+### Styling Selected Data
+
+To style selected data you will want to past styles to the select mode you are using (probably TerraDrawSelectMode).
+
+```typescript
+const draw = new TerraDraw({
+	adapter: new TerraDrawMapboxGLAdapter({
+		map,
+		coordinatePrecision: 9,
+	}),
+	modes: [
+		new TerraDrawPolygonMode(),
+		new TerraDrawSelectMode({
+			flags: {
+				polygon: {
+					feature: {
+						draggable: true,
+						coordinates: {
+							midpoints: true,
+							draggable: true,
+							deletable: true,
+						},
+					},
+				},
+			},
+			styles: {
+				selectedPolygonColor: "#222222", // Any hex color you like
+				selectedPolygonFillOpacity: 0.7, // 0 - 1
+				selectedPolygonOutlineColor: "#333333", // Any hex color you like
+				selectedPolygonOutlineWidth: 2, // Integer
+			},
+		}),
+	]
+});
+
+draw.start();
+```
+
+Please note at the moment it is not possible to style against specific modes but only universally against geometry type (Point, LineString, Polygon)
+
+### Styling Specific Features
+
+Terra Draw supports styling overrides of individual features if required. This can be achieved by providing a styling function rather than a string or a number to a feature. As an example here we can style each polygon feature as a random color:
+
+```typescript
+// Function to generate a random hex color - can adjust as needed
+function getRandomColor() {
+	const letters = "0123456789ABCDEF";
+	let color = "#";
+	for (let i = 0; i < 6; i++) {
+		color += letters[Math.floor(Math.random() * 16)];
+	}
+	return color;
+}
+
+// Cache for each feature id mapped to a hex color string
+const colorCache: Record<string, HexColor> = {};
+
+const draw = new TerraDraw({
+	adapter: new TerraDrawMapboxGLAdapter({
+		map, // Assume this is defined further up
+		coordinatePrecision: 9,
+	}),
+	modes: [
+		new TerraDrawPolygonMode({
+			styles: {
+				fillColor: ({ id }) => {
+					// Get the color from the cache or generate a new one
+					colorCache[id] = colorCache[id] || getRandomColor();
+					return colorCache[id];
+				},
+			},
+		}),
+	]
+});
+
+// Ensure the color cache is clead up on deletion of features
+draw.on("delete", (ids) => ids.forEach((id) => delete cache[id]));
+```

package/guides/GETTING_STARTED.md

@@ -22,7 +22,11 @@ Once terra-draw is out of alpha this suggestion will be removed as we will aim t
 
 You can find the full autogenerated [API docs on the terra draw website](https://terradraw.io/#/api)
 
-## Using Terra Draw
+## Common Patterns
+
+A selection of common things you may want to do with Terra Draw is available via the [common patterns guide in this folder](./COMMON_PATTERNS.md). If you think something is missing please raise an issue!
+
+## Adapters
 
 Terra Draw can be used with a set of different adapters to allow you to use it with your mapping library of choice. Each adapter has slightly different configuration but the API is the same for them all. For a deeper explanation about what adapters are and how to write you own see the [development guide](./DEVELOPMENT.md).
 
@@ -74,8 +78,8 @@ const draw = new TerraDraw({
 
 	// Modes is an object containing all the modes we wish to
 	// instantiate Terra Draw with
-	modes: {
-		select: new TerraDrawSelectMode({
+	modes: [
+		new TerraDrawSelectMode({
 			flags: {
 				// Following flags determine what you can do in
 				// select mode for features of a given mode - in this case polygon
@@ -93,11 +97,11 @@ const draw = new TerraDraw({
 				},
 			},
 		}),
-		polygon: new TerraDrawPolygonMode({
+		new TerraDrawPolygonMode({
 			allowSelfIntersections: false,
 			pointerDistance: 30,
 		}),
-	},
+	]
 });
 
 // Start drawing
@@ -151,8 +155,8 @@ loader.load().then((google) => {
 				map,
 				coordinatePrecision: 9,
 			}),
-			modes: {
-				select: new TerraDrawSelectMode({
+			modes: [
+				new TerraDrawSelectMode({
 					flags: {
 						// Following flags determine what you can do in
 						// select mode for features of a given mode - in this case polygon
@@ -170,11 +174,11 @@ loader.load().then((google) => {
 						},
 					},
 				}),
-				polygon: new TerraDrawPolygonMode({
+				new TerraDrawPolygonMode({
 					allowSelfIntersections: false,
 					pointerDistance: 30,
 				}),
-			},
+			]
 		});
 
 		// Start drawing
@@ -210,123 +214,3 @@ The [development folder features an example](https://github.com/JamesLMilner/ter
 
 The [Terra Draw official website](https://github.com/JamesLMilner/terra-draw-website) is open source acts as a full working implementation of how to use Terra Draw. In this case it is used with popular framework Preact (has very similar API to React).
 
-## Common Patterns
-
-### Loading in External Data
-
-It is common pattern to want to load in data from an external source (GeoJSON file, API call, etc). This can be achieved with the `addFeatures` method on the Terra Draw instance. The method call works out which mode to add the feature based on looking at its `mode` property in the Features `properties` property. All modes have a method called `validateFeature` that ensures that a given feature is valid for the mode. For example if you wanted to add a series of points to the TerraDrawPointMode you could do this by ensuring that the points you feed in have the `mode` property set to `point`.
-
-```javascript
-points.forEach((point) => {
-	point.properties.mode = "point";
-});
-
-draw.addFeatures(points);
-```
-
-### Render Only Modes with TerraDrawRenderMode
-
-If you just want to render some data onto the map without it being editable, you can use `TerraDrawRenderMode` in combination with `addFeatures` like so:
-
-```javascript
-const draw = new TerraDraw({
-	adapter: new TerraDrawLeafletAdapter({
-		lib: L,
-		map,
-		coordinatePrecision: 9,
-	}),
-	modes: {
-		arbitary: new TerraDrawRenderMode(),
-	},
-});
-
-draw.start();
-
-points.forEach((point) => {
-	point.properties.mode = "arbitary";
-});
-
-draw.addFeatures(points);
-
-// This will add the points to hte TerraDrawRenderMode 'arbitary' rendering them to the screen
-```
-
-### Styling Selected Data
-
-To style selected data you will want to past styles to the select mode you are using (probably TerraDrawSelectMode).
-
-```typescript
-const draw = new TerraDraw({
-	adapter: new TerraDrawMapboxGLAdapter({
-		map,
-		coordinatePrecision: 9,
-	}),
-	modes: {
-		polygon: new TerraDrawPolygonMode(),
-		select: new TerraDrawSelectMode({
-			flags: {
-				polygon: {
-					feature: {
-						draggable: true,
-						coordinates: {
-							midpoints: true,
-							draggable: true,
-							deletable: true,
-						},
-					},
-				},
-			},
-			styles: {
-				selectedPolygonColor: "#222222", // Any hex color you like
-				selectedPolygonFillOpacity: 0.7, // 0 - 1
-				selectedPolygonOutlineColor: "#333333", // Any hex color you like
-				selectedPolygonOutlineWidth: 2, // Integer
-			},
-		}),
-	},
-});
-
-draw.start();
-```
-
-Please note at the moment it is not possible to style against specific modes but only universally against geometry type (Point, LineString, Polygon)
-
-## Styling Specific Features
-
-Terra Draw supports styling overrides of individual features if required. This can be achieved by providing a styling function rather than a string or a number to a feature. As an example here we can style each polygon feature as a random color:
-
-```typescript
-// Function to generate a random hex color - can adjust as needed
-function getRandomColor() {
-	const letters = "0123456789ABCDEF";
-	let color = "#";
-	for (let i = 0; i < 6; i++) {
-		color += letters[Math.floor(Math.random() * 16)];
-	}
-	return color;
-}
-
-// Cache for each feature id mapped to a hex color string
-const colorCache: Record<string, HexColor> = {};
-
-const draw = new TerraDraw({
-	adapter: new TerraDrawMapboxGLAdapter({
-		map, // Assume this is defined further up
-		coordinatePrecision: 9,
-	}),
-	modes: {
-		polygon: new TerraDrawPolygonMode({
-			styles: {
-				fillColor: ({ id }) => {
-					// Get the color from the cache or generate a new one
-					colorCache[id] = colorCache[id] || getRandomColor();
-					return colorCache[id];
-				},
-			},
-		}),
-	},
-});
-
-// Ensure the color cache is clead up on deletion of features
-draw.on("delete", (ids) => ids.forEach((id) => delete cache[id]));
-```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "terra-draw",
-	"version": "0.0.1-alpha.43",
+	"version": "0.0.1-alpha.45",
 	"description": "Frictionless map drawing across mapping provider",
 	"scripts": {
 		"docs": "typedoc",
@@ -50,6 +50,7 @@
 		"maplibre"
 	],
 	"devDependencies": {
+		"@arcgis/core": "^4.27.6",
 		"@commitlint/cli": "^17.1.2",
 		"@commitlint/config-conventional": "^17.1.0",
 		"@googlemaps/js-api-loader": "^1.14.3",

package/scratch/release.sh

@@ -1,5 +1,5 @@
-npm run docs
-npm run build
-npm run release -- --prerelease --release-as 0.0.1-alpha.40
-git push origin main --tags
-npm publish
+
+
+
+npm run release -- --prerelease --release-as 0.0.1-alpha.45
+git push --follow-tags origin main

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

@@ -1,31 +0,0 @@
-import { Project, Unproject, TerraDrawCallbacks, TerraDrawChanges, TerraDrawMouseEvent, SetCursor, TerraDrawStylingFunction } from "../../common";
-import { AdapterListener } from "./adapter-listener";
-export declare abstract class TerraDrawAdapterBase {
-    constructor(config: {
-        coordinatePrecision?: number;
-        minPixelDragDistance?: number;
-    });
-    protected dragConter: number;
-    protected _minPixelDragDistance: number;
-    protected _lastDrawEvent: TerraDrawMouseEvent | undefined;
-    protected _coordinatePrecision: number;
-    protected _heldKeys: Set<string>;
-    protected listeners: AdapterListener[];
-    protected dragState: "not-dragging" | "pre-dragging" | "dragging";
-    protected currentModeCallbacks: TerraDrawCallbacks | undefined;
-    protected getButton(event: PointerEvent): "neither" | "left" | "middle" | "right";
-    protected getDrawEventFromPointerEvent(event: PointerEvent): TerraDrawMouseEvent;
-    abstract project(...args: Parameters<Project>): ReturnType<Project>;
-    abstract unproject(...args: Parameters<Unproject>): ReturnType<Unproject>;
-    abstract setCursor(...args: Parameters<SetCursor>): ReturnType<SetCursor>;
-    abstract getLngLatFromPointerEvent(event: PointerEvent): {
-        lng: number;
-        lat: number;
-    };
-    abstract setDraggability(enabled: boolean): void;
-    abstract setDoubleClickToZoom(enabled: boolean): void;
-    abstract getMapContainer(): HTMLElement;
-    abstract register(callbacks: TerraDrawCallbacks): void;
-    abstract unregister(): void;
-    abstract render(changes: TerraDrawChanges, styling: TerraDrawStylingFunction): void;
-}

package/dist/bundle.js

@@ -1,6 +0,0 @@
-/******/ (() => { // webpackBootstrap
-/******/ 	"use strict";
-/******/ 	
-/******/ 	
-/******/ })()
-;

package/dist/bundle.js.LICENSE.txt

@@ -1,4 +0,0 @@
-/* @preserve
- * Leaflet 1.8.0, a JS library for interactive maps. https://leafletjs.com
- * (c) 2010-2022 Vladimir Agafonkin, (c) 2010-2011 CloudMade
- */

package/dist/extend-types.d.ts

@@ -1,4 +0,0 @@
-import { GetLngLatFromEvent, Project, SetCursor, TerraDrawChanges, TerraDrawStylingFunction, Unproject } from "./common";
-import { BehaviorConfig } from "./modes/base.behavior";
-import { GeoJSONStoreFeatures } from "./store/store";
-export { BehaviorConfig, GeoJSONStoreFeatures, TerraDrawChanges, TerraDrawStylingFunction, Project, Unproject, SetCursor, GetLngLatFromEvent, };

package/dist/geometry/create-circle.d.ts

@@ -1,6 +0,0 @@
-import { Feature, Polygon } from "geojson";
-export declare function circle(options: {
-    center: [number, number];
-    radiusKilometers: number;
-    steps?: number;
-}): Feature<Polygon>;

package/dist/geometry/get-pixel-distance-to-line.d.ts

@@ -1,10 +0,0 @@
-export declare const getPixelDistanceToLine: (point: {
-    x: number;
-    y: number;
-}, linePointOne: {
-    x: number;
-    y: number;
-}, linePointTwo: {
-    x: number;
-    y: number;
-}) => number;

package/dist/geometry/get-pixel-distance.d.ts

@@ -1,7 +0,0 @@
-export declare const getPixelDistance: (pointOne: {
-    x: number;
-    y: number;
-}, pointTwo: {
-    x: number;
-    y: number;
-}) => number;

package/dist/geometry/haversine-distance.d.ts

@@ -1 +0,0 @@
-export declare function haversineDistanceKilometers(pointOne: [lng: number, lat: number], pointTwo: [lng: number, lat: number]): number;

package/dist/geometry/point-in-polygon.d.ts

@@ -1 +0,0 @@
-export declare function pointInPolygon(point: [number, number], rings: [number, number][][]): boolean;

package/dist/geometry/self-intersects.d.ts

@@ -1,2 +0,0 @@
-import { Feature, LineString, Polygon } from "geojson";
-export declare function selfIntersects(feature: Feature<Polygon> | Feature<LineString>): boolean;

package/dist/modes/circle.mode.d.ts

@@ -1,18 +0,0 @@
-import { TerraDrawMouseEvent, TerraDrawMode, TerraDrawModeRegisterConfig, TerraDrawAdapterStyling, TerraDrawKeyboardEvent } from "../common";
-export declare class TerraDrawCircleMode implements TerraDrawMode {
-    mode: string;
-    private store;
-    private project;
-    private center;
-    private clickCount;
-    private currentCircleId;
-    constructor(options?: {
-        styling?: Partial<TerraDrawAdapterStyling>;
-    });
-    styling: TerraDrawAdapterStyling;
-    register(config: TerraDrawModeRegisterConfig): void;
-    onClick(event: TerraDrawMouseEvent): void;
-    onMouseMove(event: TerraDrawMouseEvent): void;
-    onKeyPress(event: TerraDrawKeyboardEvent): void;
-    cleanUp(): void;
-}

package/dist/modes/freehand.mode.d.ts

@@ -1,20 +0,0 @@
-import { TerraDrawMouseEvent, TerraDrawMode, TerraDrawModeRegisterConfig, TerraDrawAdapterStyling, TerraDrawKeyboardEvent } from "../common";
-export declare class TerraDrawFreehandMode implements TerraDrawMode {
-    mode: string;
-    private store;
-    private project;
-    private startingClick;
-    private currentId;
-    private skip;
-    private everyNthMouseEvent;
-    constructor(options?: {
-        styling?: Partial<TerraDrawAdapterStyling>;
-        everyNthMouseEvent?: number;
-    });
-    styling: TerraDrawAdapterStyling;
-    register(config: TerraDrawModeRegisterConfig): void;
-    onMouseMove(event: TerraDrawMouseEvent): void;
-    onClick(event: TerraDrawMouseEvent): void;
-    onKeyPress(event: TerraDrawKeyboardEvent): void;
-    cleanUp(): void;
-}

package/dist/modes/line-string.mode.d.ts

@@ -1,21 +0,0 @@
-import { TerraDrawMouseEvent, TerraDrawMode, TerraDrawModeRegisterConfig, TerraDrawAdapterStyling, TerraDrawKeyboardEvent } from "../common";
-export declare class TerraDrawLineStringMode implements TerraDrawMode {
-    mode: string;
-    private store;
-    private project;
-    private pointerDistance;
-    private currentCoordinate;
-    private currentId;
-    private allowSelfIntersections;
-    constructor(options?: {
-        allowSelfIntersections?: boolean;
-        styling?: Partial<TerraDrawAdapterStyling>;
-        pointerDistance?: number;
-    });
-    styling: TerraDrawAdapterStyling;
-    register(config: TerraDrawModeRegisterConfig): void;
-    onMouseMove(event: TerraDrawMouseEvent): void;
-    onClick(event: TerraDrawMouseEvent): void;
-    onKeyPress(event: TerraDrawKeyboardEvent): void;
-    cleanUp(): void;
-}

package/dist/modes/point.mode.d.ts

@@ -1,14 +0,0 @@
-import { TerraDrawMouseEvent, TerraDrawMode, TerraDrawModeRegisterConfig, TerraDrawAdapterStyling } from "../common";
-export declare class TerraDrawPointMode implements TerraDrawMode {
-    mode: string;
-    private store;
-    constructor(options?: {
-        styling?: Partial<TerraDrawAdapterStyling>;
-    });
-    styling: TerraDrawAdapterStyling;
-    register(config: TerraDrawModeRegisterConfig): void;
-    onClick(event: TerraDrawMouseEvent): void;
-    onMouseMove(): void;
-    onKeyPress(): void;
-    cleanUp(): void;
-}

package/dist/modes/polygon/behaviors/start-end-point.behavior.d.ts

@@ -1,11 +0,0 @@
-import { Position } from "geojson";
-import { BehaviorConfig, TerraDrawModeBehavior } from "../../base.behavior";
-export declare class StartEndPointBehavior extends TerraDrawModeBehavior {
-    constructor(config: BehaviorConfig);
-    private _startEndPoints;
-    get ids(): string[];
-    set ids(_: string[]);
-    create(selectedCoords: Position[], mode: string): void;
-    delete(): void;
-    update(updatedCoordinates: Position[]): void;
-}

package/dist/modes/polygon.mode.d.ts

@@ -1,21 +0,0 @@
-import { TerraDrawMouseEvent, TerraDrawMode, TerraDrawModeRegisterConfig, TerraDrawAdapterStyling, TerraDrawKeyboardEvent } from "../common";
-export declare class TerraDrawPolygonMode implements TerraDrawMode {
-    mode: string;
-    private store;
-    private project;
-    private currentCoordinate;
-    private currentId;
-    private allowSelfIntersections;
-    private pointerDistance;
-    constructor(options?: {
-        allowSelfIntersections?: boolean;
-        styling?: Partial<TerraDrawAdapterStyling>;
-        pointerDistance?: number;
-    });
-    styling: TerraDrawAdapterStyling;
-    register(config: TerraDrawModeRegisterConfig): void;
-    onMouseMove(event: TerraDrawMouseEvent): void;
-    onClick(event: TerraDrawMouseEvent): void;
-    onKeyPress(event: TerraDrawKeyboardEvent): void;
-    cleanUp(): void;
-}

package/dist/modes/select.mode.d.ts

@@ -1,21 +0,0 @@
-import { TerraDrawMouseEvent, TerraDrawMode, TerraDrawModeRegisterConfig, TerraDrawKeyboardEvent, TerraDrawAdapterStyling } from "../common";
-export declare class TerraDrawSelectMode implements TerraDrawMode {
-    mode: string;
-    private store;
-    private project;
-    private selected;
-    private pointerDistance;
-    private selectionPoints;
-    constructor(options?: {
-        styling?: Partial<TerraDrawAdapterStyling>;
-        pointerDistance?: number;
-    });
-    styling: TerraDrawAdapterStyling;
-    onClick(event: TerraDrawMouseEvent): void;
-    onKeyPress(event: TerraDrawKeyboardEvent): void;
-    cleanUp(): void;
-    onMouseMove(): void;
-    register(config: TerraDrawModeRegisterConfig): void;
-    onDeselect(deselectedId: string): void;
-    onSelect(selectedId: string): void;
-}

package/dist/modes/static.mode.d.ts

@@ -1,10 +0,0 @@
-import { TerraDrawAdapterStyling, TerraDrawMode } from "../common";
-export declare class TerraDrawStaticMode implements TerraDrawMode {
-    mode: string;
-    styling: TerraDrawAdapterStyling;
-    register(): void;
-    onKeyPress(): void;
-    onClick(): void;
-    onMouseMove(): void;
-    cleanUp(): void;
-}