docs: guides overhaul (#128)

* docs: guides overhaul

This PR is a complete overhaul of the `guides/` directory. While trying to wrap my head around the library, I found the existing Guides to be a bit confusing and lacking.

Using the existing Guides as a starting point, I have re-structured and added a lot of new content to make the Guides more useful and easier to navigate. I also paid attention to the style and formatting to make it easier to read and understand, while sticking to the existing style as much as possible.

This is _my_ understanding of the library, which I pieced together from the existing Guides, examples, API Docs and delving into the `src/` and `development/` source code. Props to TypeScript for helping out with the latter.

I am sure there are some errors and omissions, so feedback welcome and I am happy to make any changes as needed.

## Changes

In this new form, the `guides/` directory contains the following Markdown pages:

1. Getting Started
2. Adapters
3. Modes
4. Styling
5. Events
6. Development

### Restructuring / Navigation

- All pages in the `guides/` directory now have a numeric prefix to control the order in which they appear. The exception is the `CODE_OF_CONDUCT.md` file, which I have left as-is.
- At the end of each page there is a list of links to the other pages in the `guides/` directory, so it is easy to navigate between them.

### 1.Getting Started

- Added additional Key Concepts content:
  - Store
  - Adapters
  - Modes
- Improved Installation instructions.

### 2.Adapters

Added sections:

- Available Adapters
- Using Adapters
- Examples:
  - Leaflet
  - MapLibre
  - Google Maps
  - MapBox

### 3.Modes

Added sections:

- Mode Names
- Drawing Modes
- Selection Mode
- Render Mode
- Adding Modes
- Enabling Modes
- Loading Features

### 4.Styling

Added sections:

- Drawing Modes:
  - Points
  - Lines
  - Polygons
  - Freehand
  - Great Circle
  - Circle
  - Rectangle
- Selection Mode
  - Points
  - Lines
  - Polygons
  - Selection Points
  - Mid Points
- Render Mode
  - Points
  - Lines
  - Polygons

### 5.Events

Restructured sections into:

- Native Events
- Terra Draw Events

### 6.Development

Mostly minor tweaks and improvements.

### General / Other

- Added inline Alerts to highlight important information.
- Added lang to all code blocks.
- Lots of minor tweaks to improve formatting and readability.

### Removed

- `guides/COMMON_PATTERNS.md` - content broken up and moved to other pages.
- `guides/CONTRIBUTING.md` - content moved to `DEVELOPMENT.md#contributing`.

The README.md file in the root directory, as well as the `docs/index.html` has been updated to reflect these Guide location changes.

* Added extra content about Store feature retrieval and removal

* Added Missing Styling Specific Features

* Added extra detail about  getSnapshot

* Adapter Anatomy renamed to Adapter Interface

* Styling Colors CSS/Hex value correction

---------

Co-authored-by: Joe Hawes <>

README.md

@@ -22,11 +22,11 @@ Terra Draw uses the concept of 'adapters' to allow it to work with a host of dif
 
 ### Getting Started
 
-Please see the [the getting started guide](./guides/GETTING_STARTED.md) - this provides a host of information on how to get up and running with Terra Draw. You may also find some useful pointers for things you may be finding yourself wanting to do in the [common patterns guide](./guides/COMMON_PATTERNS.md).
+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
 
-Please see the [the development documentation](./guides/DEVELOPMENT.md)
+Please see the [the development documentation](./guides/6.DEVELOPMENT.md)
 
 ### Contributing
 

guides/1.GETTING_STARTED.md

@@ -0,0 +1,265 @@
+# Getting Started
+
+Terra Draw adds a number of geographical Feature drawing tools to popular mapping libraries. There are few key concepts that allow it to stay strongly decoupled and as library-agnostic as possible, let's walk through them.
+
+## Key Concepts
+
+> [!TIP]
+> TL;DR? Jump to the [Installation](./2.INSTALLATION.md) Guide to get started, or:
+>
+> ```javascript
+> npm install terra-draw
+> ```
+
+### Store
+
+The Store is the heart of the library and is responsible for managing the state of all Features that are added to the map. The Store is created when Terra Draw is instantiated:
+
+```javascript
+// Create a Terra Draw instance and assign it to a variable called `draw`
+const draw = new TerraDraw({ adapter, modes });
+```
+
+> [!IMPORTANT]
+> Throughout the documentation we will use the variable name `draw` to refer to the Terra Draw instance.
+
+Features are added to the Store when interacting with the Map using a number of available drawing Modes (such as `TerraDrawRectangleMode` or `TerraDrawPolygonMode`).
+
+Features can also be added to the Store programmatically using the `addFeatures` method:
+
+```javascript
+// Add a Point to the Store
+draw.addFeatures([
+  {
+    type: "Feature",
+    geometry: {
+      type: "Point",
+      coordinates: [-1.825859, 51.178867],
+    },
+    properties: {
+      mode: "point",
+    },
+  },
+]);
+```
+
+The Store is exposed via the `getSnapshot` method, which returns an Array of all given Feature geometries in the Store:
+
+```javascript
+// Get an Array of all Features in the Store
+const features = draw.getSnapshot();
+```
+
+> [!TIP]
+> The `getSnapshot` method returns a deep copy of the Store, so you can safely mutate the returned Array without affecting the Store.
+
+Features can also be retrieved from the Store using the `getFeaturesAtLngLat` and `getFeaturesAtPointerEvent` methods.
+
+To remove Features from the Store use the `removeFeatures` or `clear` methods:
+
+```javascript
+// Remove Feature from the Store by ID
+draw.removeFeatures(["id-1", "id-2", "id-3"]);
+
+// Remove all Features from the Store
+draw.clear();
+```
+
+See the `TerraDraw` [API Docs](https://jameslmilner.github.io/terra-draw/classes/TerraDraw.html) for more information.
+
+### Adapters
+
+Adapters are thin wrappers that contain map library specific logic, for creating and updating layers rendered by the mapping library.
+
+For example if you are using [MapLibre](https://maplibre.org/) you would use the `TerraDrawMapLibreGLAdapter` Adapter, for [Leaflet](https://leafletjs.com/) you would use the `TerraDrawLeafletAdapter` Adapter:
+
+```javascript
+// Create an Adapter for Leaflet
+const adapter = new TerraDrawLeafletAdapter({ map, lib });
+```
+
+> [!IMPORTANT]
+> Each Adapter must be instantiated with both `map` and `lib` properties.
+
+See the [Adapters](./2.ADAPTERS.md) section for more information.
+
+### Modes
+
+Modes represent the logic for a specific drawing tool, for example there are `TerraDrawRectangleMode`, `TerrDrawPolygonMode` and `TerraDrawLineStringMode` Modes which allow you to draw rectangles, polygons and lines on the map respectively.
+
+The `TerraDrawSelectMode` allows for the selection and manipulation of features on the Map, while the `TerraDrawRenderMode` is used to render uneditable features, for example contextual data.
+
+Modes are instantiated like so:
+
+```javascript
+const polygonMode = new TerraDrawPolygonMode();
+const rectangleMode = new TerraDrawRectangleMode();
+const renderMode = new TerraDrawRenderMode({
+  modeName: "auniquename",
+});
+```
+
+See the [Modes](./3.MODES.md) section for more information.
+
+## Installation
+
+Terra Draw can be added to your site either via the `<script>` tag, or using a package manager like NPM.
+
+### NPM
+
+> [!IMPORTANT]
+> We start with the assumption that you have both **Node.js** and **npm** [installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
+
+You can install the Terra Draw into your project like so:
+
+```shell
+npm install terra-draw
+```
+
+> [!WARNING]
+> 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`.
+
+```json
+"terra-draw": "0.0.1-alpha.50"
+```
+
+Once terra-draw is out of alpha this suggestion will be removed as we will aim to move to semantic versioning.
+
+View the [NPM package page](https://www.npmjs.com/package/terra-draw) for more information.
+
+#### Usage
+
+Once installed via NPM you can use Terra Draw in your project like so:
+
+```javascript
+// Import Terra Draw
+import {
+  TerraDraw,
+  TerraDrawMapLibreGLAdapter,
+  TerraDrawRectangleMode,
+} from "terra-draw";
+
+// Import MapLibreGL
+import { MapLibreGL as lib } from "maplibre-gl";
+
+// Create MapLibre Map, targetting <div id="map">
+const map = new MapLibreGL.Map({ container: "map" });
+
+// Create Terra Draw
+const draw = new TerraDraw({
+  // Using the MapLibre Adapter
+  adapter: new TerraDrawMapLibreGLAdapter({ map, lib }),
+
+  // Add the Rectangle Mode
+  modes: [new TerraDrawRectangleMode()],
+});
+
+// Start drawing
+draw.start();
+draw.setMode("rectangle");
+```
+
+### Script Tag
+
+To use Terra Draw without a build step, you can load the UMD (Universal Module Definition) bundle directly from a CDN (Content Delivery Network) like [unpkg](https://unpkg.com/).
+
+#### Usage
+
+For example if we were using Terra Draw with MapLibre we might do something like this in our `<head>` tag:
+
+```html
+<!-- MapLibre -->
+<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
+<link
+  href="https://unpkg.com/[email protected]/dist/maplibre-gl.css"
+  rel="stylesheet"
+/>
+<!-- Terra Draw -->
+<script src="https://unpkg.com/[email protected]/dist/terra-draw.umd.js"></script>
+```
+
+Later on in our JavaScript code we can access `terraDraw` globally like so:
+
+```javascript
+// Create Terra Draw instance
+const draw = new terraDraw.TerraDraw({
+  // Using the MapLibre Adapter
+  adapter: new terraDraw.TerraDrawMapLibreGLAdapter({ map, lib }),
+
+  // Add the Rectangle Mode
+  modes: [new terraDraw.TerraDrawRectangleMode()],
+});
+```
+
+#### Example
+
+Putting these concepts together we can create a simple map with freehand drawing enabled like so:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <!-- Required Styles & Script -->
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/[email protected]/dist/maplibre-gl.css"
+    />
+    <script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
+    <script src="https://unpkg.com/[email protected]/dist/terra-draw.umd.js"></script>
+  </head>
+  <body>
+    <!-- Map Container (must have dimensions set!) -->
+    <div id="map" style="height:420px;"></div>
+
+    <script>
+      // Create MapLibre Map, targetting <div id="map">
+      // See https://maplibre.org/maplibre-gl-js/docs/
+      var map = new maplibregl.Map({
+        container: "map",
+        style: "https://demotiles.maplibre.org/style.json",
+        center: [-4.49049, 54.189649], // [lng, lat]
+        zoom: 5,
+      });
+
+      // Create Terra Draw
+      const draw = new terraDraw.TerraDraw({
+        adapter: new terraDraw.TerraDrawMapLibreGLAdapter({
+          map: map,
+          lib: maplibregl,
+        }),
+        modes: [new terraDraw.TerraDrawFreehandMode()],
+      });
+
+      // Start drawing
+      draw.start();
+
+      // Set the mode to rectangle
+      draw.setMode("freehand");
+    </script>
+  </body>
+</html>
+```
+
+## API Docs
+
+You can find the full autogenerated [API docs on the terra draw website](https://terradraw.io/#/api).
+
+## 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](https://github.com/JamesLMilner/terra-draw/tree/main/development) - showcases all of Terra Draw Modes and 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 framework.
+- [Terra Draw Website](https://terradraw.io/) - 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). It's [Open Source](https://github.com/JamesLMilner/terra-draw-website) too!
+
+---
+
+**Guides**
+
+1. [x] Getting Started
+2. [ ] [Adapters](./2.ADAPTERS.md)
+3. [ ] [Modes](./3.MODES.md)
+4. [ ] [Styling](./4.STYLING.md)
+5. [ ] [Events](./5.EVENTS.md)
+6. [ ] [Development](./6.DEVELOPMENT.md)