terra-draw 0.0.1-alpha.4 → 0.0.1-alpha.41

package/dist/util/geoms.d.ts

@@ -1,3 +1,3 @@
-import { Feature, LineString, Polygon, Position } from "geojson";
-export declare function createPolygon(coordinates?: Position[][]): Feature<Polygon>;
-export declare function createLineString(coordinates: Position[]): Feature<LineString>;
+import { Feature, LineString, Polygon, Position } from "geojson";
+export declare function createPolygon(coordinates?: Position[][]): Feature<Polygon>;
+export declare function createLineString(coordinates: Position[]): Feature<LineString>;

package/dist/util/id.d.ts

@@ -1 +1 @@
-export declare const uuid4: () => string;
+export declare const uuid4: () => string;

package/dist/util/styling.d.ts

@@ -1,2 +1,2 @@
-import { TerraDrawAdapterStyling } from "../common";
-export declare const getDefaultStyling: () => TerraDrawAdapterStyling;
+import { TerraDrawAdapterStyling } from "../common";
+export declare const getDefaultStyling: () => TerraDrawAdapterStyling;

package/{CONTRIBUTING.md → guides/CONTRIBUTING.md}

@@ -4,14 +4,14 @@
 
 This document will receive a more thorough update in the future. For the time being, if you wish to contribute to Terra Draw, we request that you:
 
-1) Make an issue on GitHub describing the bug you intend to fix or the feature you intend to add.
-2) Create a fork of the project, and work on a branch that represents the issue
-3) Ensure that the work you have done is unit tested, aiming for 80% code coverage
-4) Create a PR that represents this work. Please refer to the issue from the PR
-5) We will address the PR and give you feedback 
+1. Make an issue on GitHub describing the bug you intend to fix or the feature you intend to add.
+2. Create a fork of the project, and work on a branch that represents the issue
+3. Ensure that the work you have done is unit tested, aiming for 80% code coverage
+4. Create a PR that represents this work. Please refer to the issue from the PR
+5. We will address the PR and give you feedback
 
-Please note that we can not garauntee that all PRs will be merged. There are cases where a PR may deviate from the long-term vision for Terra Draw and hence we may have to decline it. Creating the issue in advance helps us discuss any potential issues upfront before the PR is made.
+Please note that we can not guarantee that all PRs will be merged. There are cases where a PR may deviate from the long-term vision for Terra Draw and hence we may have to decline it. Creating the issue in advance helps us discuss any potential issues upfront before the PR is made.
 
 ## Code of Conduct
 
-We have a code of conduct which we expect individuals interacting with the project to respect. Please see the [full Code of Conduct in the repository](./CODE_OF_CONDUCT.md).
+We have a code of conduct which we expect individuals interacting with the project to respect. Please see the [full Code of Conduct in the repository](./CODE_OF_CONDUCT.md).

package/guides/DEVELOPMENT.md

@@ -0,0 +1,156 @@
+# Development
+
+This file acts as a way to document how to develop the Terra Draw project locally.
+
+### Prerequisites
+
+A few things you will need to have installed in order to develop on this project:
+
+- git
+- Node LTS - currently v16
+- npm 8
+
+### Folder Structure
+
+- `.github` - used for all GitHub related configuration such as the GitHub Actions work flows
+- `.husky` - used to storing the precommit hooks that are used on the project
+- `src` - source files for the project
+- `dist` - the bundled distributed files of the project
+- `docs` - the demo app that is published to GitHub pages
+- `development` - the local development app that is used for developing locally (see below)
+- `common` - code that is used across `development` and `docs` folder`
+
+### Technologies Used
+
+Terra Draw
+
+- [TypeScript](https://www.typescriptlang.org/) - provides strong compile time typing for JavaScript
+- Jest - used for testing (see more information below)
+- microbundle - used for the production bundle
+- Webpack - used for bundling locally in development (`development` and `docs` folders)
+- esno - for running tests quickly without type checking
+
+### Precommit Hooks
+
+It is probably useful to be aware of the precommit hooks you will face when trying to run a git commit on the project. There are two currently in use, namely:
+
+- Uses pre-commit hook to run lint rules (eslint/prettier) on code before commit
+- Uses pre-commit hook to ensure [conventional commit messages](https://www.conventionalcommits.org/en/v1.0.0/) are used
+
+### Testing
+
+Terra Draw uses [jest](https://jestjs.io/) as it's testing framework. You can distinguish a test by it's `.spec.ts` prefix on the file name.
+
+To run the tests as they would run in CI:
+
+```
+npm run test
+```
+
+You can also check the coverage by running:
+
+```
+npm run test:coverage
+```
+
+For local development you may benefit from the `nocheck` option which allows you to avoid running TypeScript type checking when running the tests. This option also only checks files which are explicitly tested (i.e. have a spec file.)
+
+```
+npm run test:nocheck
+npm run test:nocheck:coverage
+```
+
+### Developing Locally
+
+A folder called `development` has been set up locally to allow you to test developing Terra Draw locally more easily. It allows you to run the different adapters and test different map providers in parallel, ensuring. You will need to update the .env file in the `development` folder in order to use the related adapters working. An example `.env` file in the `development` folder:
+
+```
+GOOGLE_API_KEY=YOUR_KEY_HERE
+MAPBOX_ACCESS_TOKEN=YOUR_KEY_HERE
+```
+
+## Terra Draw Concepts
+
+Terra Draw has a few elementary concepts that allow it to stay strongly decoupled and relatively map library agnostic. Lets walk through them:
+
+- **Store**: - at the heart of the library, where geometry data is stored, created, updated and deleted. Data is stored as standard GeoJSON.
+- **Adapters**: thin wrappers that contain map library specific logic, for creating and updating layers that can rendered by the mapping library
+- **Modes**: - modes represent the logic for a specific drawing tool, for example the point, line and polygon modes
+
+### Adapters Explained
+
+Adapters are a core aspect of Terra Draw - they are the layer between the core of the library and the external mapping libraries (Leaflet, Google Maps etc). In simple terms an adapter takes input events, passes them through to create geometries in the store and then passes them back to the adapter to be rendered specifically for the mapping library. For example, in the `LeafletAdapter` we create and update a GeoJSON layer that Leaflet knows how to render to the screen. In theory an adapter could be created for any mapping library that can fill out the Adapter abstract class (TerraDrawBaseAdapter). Namely these are methods that would need to be completed:
+
+```typescript
+	public project(...args: Parameters<Project>): ReturnType<Project>;
+
+	public unproject(
+		...args: Parameters<Unproject>
+	): ReturnType<Unproject>;
+
+	public setCursor(
+		...args: Parameters<SetCursor>
+	): ReturnType<SetCursor>;
+
+	public getLngLatFromEvent(event: PointerEvent | MouseEvent): {
+		lng: number;
+		lat: number;
+	} | null;
+
+	public setDraggability(enabled: boolean): void;
+
+	public setDoubleClickToZoom(enabled: boolean): void;
+
+	public getMapContainer(): HTMLElement;
+
+	public render(
+		changes: TerraDrawChanges,
+		styling: TerraDrawStylingFunction
+	): void;
+```
+
+### Modes Explained
+
+Modes are another important concept in Terra Draw. Modes are a way to encapsulate specific logic for drawing a certain entity. For example, there are built in modes for drawing points, lines, polygons, circles and rectangles.
+
+Modes can go beyond just drawing however, for example the built in `TerraDrawSelectMode` allows for selection and editing of geometries that have previously been drawn. Another example of a mode that is not explicitly just editing is `TerraDrawRenderMode` which can be considered to be a 'view only mode' and used if you wanted to show some contextual data in your application alongside data that you want to edit.
+
+Assuming that a mode extends from `TerraDrawBaseMode`
+
+```typescript
+	/** @internal */
+	start() {
+		this.setStarted();
+
+	}
+
+	/** @internal */
+	stop() {
+		this.setStopped();
+	}
+
+	/** @internal */
+	onClick(event: TerraDrawMouseEvent) {}
+
+	/** @internal */
+	onMouseMove(event: TerraDrawMouseEvent) {}
+
+	/** @internal */
+	onKeyDown(event: TerraDrawKeyboardEvent) {}
+
+	/** @internal */
+	onKeyUp(event: TerraDrawKeyboardEvent) {}
+
+
+	/** @internal */
+	onDragStart(event: TerraDrawMouseEvent) {}
+
+	/** @internal */
+	onDrag(event: TerraDrawMouseEvent) {}
+
+	/** @internal */
+	onDragEnd(event: TerraDrawMouseEvent) {}
+
+	/** @internal */
+	styleFeature(feature: GeoJSONStoreFeatures): TerraDrawAdapterStyling {}
+```

package/guides/GETTING_STARTED.md

@@ -0,0 +1,292 @@
+# Getting Started
+
+## Install
+
+We start with the assumption that you have [Node.js](https://nodejs.org/en) installed and [npm](https://www.npmjs.com/) (node package manager).
+
+You can install the Terra Draw into your project like so:
+
+```shell
+npm install terra-draw
+```
+
+Be aware Terra Draw is currently in alpha, the initial API is still being finalised. It is strongly advised to pin your installation to a specific version i.e. not using carat, asterix or tilde for versions but giving a version explicitly in your `package.json`
+
+```
+  "terra-draw": "0.0.1-alpha.22"
+```
+
+Once terra-draw is out of alpha this suggestion will be removed as we will aim to move to semantic versioning.
+
+## API Docs
+
+You can find the full autogenerated [API docs on the terra draw website](https://terradraw.io/#/api)
+
+## Using Terra Draw
+
+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).
+
+### Leaflet
+
+Here is some simple starter code for using Terra Draw with the popular open source mapping library Leaflet. It assumes you are going instantiate your map in a div with and id of `map`, which is assumed to exist within your HTML.
+
+```typescript
+// Import the leaflet mapping library
+import * as L from "leaflet";
+
+// Import Terra Draw, we will import the leaflet adapter, select mode and polygon mode
+import {
+	TerraDraw,
+	TerraDrawLeafletAdapter,
+	TerraDrawSelectMode,
+	TerraDrawPolygonMode,
+} from "terra-draw";
+
+// Initialize a new Leaflet map, providing the id of the div to display the map
+// Set the initial center (latitude, longitude) and the zoom level
+const leafletMap = L.map("map", {
+	center: [lat, lng],
+	zoom: 4, // starting zoom,
+	minZoom: 3,
+	maxZoom: 20,
+	tapTolerance: 10,
+});
+
+// Add a basemap from OpenStreetMap to the Leaflet map
+L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
+	maxZoom: 19,
+	attribution:
+		'&copy; <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>',
+}).addTo(leafletMap);
+
+// Instantiate the TerraDraw API with a Leaflet adapter and custom modes
+const draw = new TerraDraw({
+	adapter: new TerraDrawLeafletAdapter({
+		// The leaflet library object
+		lib: leaflet,
+
+		// The leaflet map object we created
+		map: leafletMap,
+
+		// The decimal precision of the coordinates created
+		coordinatePrecision: 9,
+	}),
+
+	// Modes is an object containing all the modes we wish to
+	// instantiate Terra Draw with
+	modes: {
+		select: new TerraDrawSelectMode({
+			flags: {
+				// Following flags determine what you can do in
+				// select mode for features of a given mode - in this case polygon
+				polygon: {
+					feature: {
+						scaleable: true,
+						rotateable: true,
+						draggable: true,
+						coordinates: {
+							midpoints: true,
+							draggable: true,
+							deletable: true,
+						},
+					},
+				},
+			},
+		}),
+		polygon: new TerraDrawPolygonMode({
+			allowSelfIntersections: false,
+			pointerDistance: 30,
+		}),
+	},
+});
+
+// Start drawing
+draw.start();
+
+// Set the mode to polygon
+draw.setMode("polygon");
+```
+
+### Google Maps API
+
+Here is some starter code for using Terra Draw with the Google Maps API. It assumes you are going instantiate your map in a div with and id of `map`, which is assumed to exist within your HTML.
+
+```typescript
+// Import the google maps api loader
+import { Loader } from "@googlemaps/js-api-loader";
+
+// Import Terra Draw, we will import the leaflet adapter, select mode and polygon mode
+import {
+	TerraDraw,
+	TerraDrawLeafletAdapter,
+	TerraDrawSelectMode,
+	TerraDrawPolygonMode,
+} from "terra-draw";
+
+const loader = new Loader({
+	apiKey: "INSERT_YOUR_API_KEY_HERE", // You need to provide your own API key here
+	version: "weekly",
+});
+
+// We need to await the google maps api
+loader.load().then((google) => {
+	// Create the map
+	const map = new google.maps.Map(document.getElementById("map"), {
+		disableDefaultUI: true,
+		center: { lat: this.lat, lng: this.lng },
+		zoom: this.zoom,
+
+		//Setting clickableIcons to false is used to disable the default behavior of the
+		// Google Maps API, which is to allow users to interact with clickable icons on the
+		// map, such as points of interest (POIs) or other interactive map elements.
+		clickableIcons: false,
+	});
+
+	// When using Google Maps, it's important to wrap the creation of custom overlays or other // map-related initializations inside the 'projection_changed' event listener to ensure
+	// that the map's projection is fully loaded before your code runs.
+	map.addListener("projection_changed", () => {
+		const draw = new TerraDraw({
+			adapter: new TerraDrawGoogleMapsAdapter({
+				lib: google.maps,
+				map,
+				coordinatePrecision: 9,
+			}),
+			modes: {
+				select: new TerraDrawSelectMode({
+					flags: {
+						// Following flags determine what you can do in
+						// select mode for features of a given mode - in this case polygon
+						polygon: {
+							feature: {
+								scaleable: true,
+								rotateable: true,
+								draggable: true,
+								coordinates: {
+									midpoints: true,
+									draggable: true,
+									deletable: true,
+								},
+							},
+						},
+					},
+				}),
+				polygon: new TerraDrawPolygonMode({
+					allowSelfIntersections: false,
+					pointerDistance: 30,
+				}),
+			},
+		});
+
+		// Start drawing
+		draw.start();
+
+		// Set the mode to polygon
+		draw.setMode("polygon");
+	});
+});
+```
+
+### OpenLayers
+
+Coming soon - please see development folder for example for now.
+
+### MapboxGL JS
+
+Coming soon - please see development folder for example for now.
+
+### MapLibreGL JS
+
+Coming soon - please see development folder for example for now.
+
+## Other Examples
+
+There are a few other working examples that you can use as points of reference for creating a new app using Terra Draw.
+
+### Development Example
+
+The [development folder features an example](https://github.com/JamesLMilner/terra-draw/tree/main/development) of using Terra Draw with all the adapters. It is meant for local development but can also be used as a guide of how to use Terra Draw with each adapter without any frame work.
+
+### Full Example
+
+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)

package/jest.config.ts

@@ -1,27 +1,27 @@
-
-let options = {}
+let options = {};
 
 if (process.env.NO_CHECK) {
-    options = {
-        "transform": {
-            "^.+\\.(t|j)sx?$": "@swc/jest"
-        },
-        "setupFilesAfterEnv": ["<rootDir>/src/test/jest.matchers.ts"],
-    }
+	options = {
+		transform: {
+			"^.+\\.(t|j)sx?$": "@swc/jest",
+		},
+		coveragePathIgnorePatterns: ["<rootDir>/src/test/"],
+		setupFilesAfterEnv: ["<rootDir>/src/test/jest.matchers.ts"],
+	};
 } else {
-    options = {
-        "preset": "ts-jest",
-        "testEnvironment": "node",
-        "coveragePathIgnorePatterns": ["<rootDir>/src/test/"],
-        "setupFilesAfterEnv": ["<rootDir>/src/test/jest.matchers.ts"],
-        "collectCoverage": true,
-        "collectCoverageFrom": ["./src/**"],
-        "coverageThreshold": {
-            "global": {
-                "lines": 65
-            }
-        }
-    }
+	options = {
+		preset: "ts-jest",
+		testEnvironment: "node",
+		coveragePathIgnorePatterns: ["<rootDir>/src/test/"],
+		setupFilesAfterEnv: ["<rootDir>/src/test/jest.matchers.ts"],
+		collectCoverage: true,
+		collectCoverageFrom: ["./src/**"],
+		coverageThreshold: {
+			global: {
+				lines: 65,
+			},
+		},
+	};
 }
 
-module.exports = options
+module.exports = options;