feat: provide snapping to line as well as feature coordinates for polygon mode

development/src/index.ts

@@ -169,13 +169,19 @@ const getModes = () => {
 		}),
 		new TerraDrawPointMode(),
 		new TerraDrawLineStringMode({
-			insertCoordinates: {
-				strategy: "amount",
-				value: 10,
+			snapping: {
+				toCoordinate: true,
 			},
+			// insertCoordinates: {
+			// 	strategy: "amount",
+			// 	value: 10,
+			// },
 		}),
 		new TerraDrawPolygonMode({
-			snapping: true,
+			snapping: {
+				toLine: true,
+				toCoordinate: true,
+			},
 			validation: (feature, { updateType }) => {
 				if (updateType === "finish" || updateType === "commit") {
 					return ValidateNotSelfIntersecting(feature);

guides/4.MODES.md

@@ -137,6 +137,24 @@ You'll notice there are two arguments to the `validation` function, the first be
 
 Using these can help you write more customised behaviours, for example you may only want to run the validation when the update is a `finish` or `commit` type, ensuring that validation is not prematurely preventing user interactions to update the feature.
 
+#### Snapping
+
+Some specific modes support snapping, currently polygon and linestring mode. As of writing you can snap between features in the same mode. Currently polygon mode supports snapping to a the coordinates or line segments of existing features via the `toCoordinate` and/or `toLine` properties respectively:
+
+```typescript
+  new TerraDrawPolygonMode({
+    snapping: {
+      toLine: true,
+      toCoordinate: true,
+    },
+    validation: (feature, { updateType }) => {
+      if (updateType === "finish" || updateType === "commit") {
+        return ValidateNotSelfIntersecting(feature);
+      }
+      return { valid: true };
+    },
+  })
+```
 
 #### Projections in Drawing Modes
 

src/common.ts

@@ -29,6 +29,8 @@ export interface TerraDrawAdapterStyling {
 	zIndex: number;
 }
 
+export type CartesianPoint = { x: number; y: number };
+
 // Neither buttons nor touch/pen contact changed since last event	-1
 // Mouse move with no buttons pressed, Pen moved while hovering with no buttons pressed	—
 // Left Mouse, Touch Contact, Pen contact	0
@@ -62,7 +64,7 @@ export type SetCursor = (
 		| "move",
 ) => void;
 
-export type Project = (lng: number, lat: number) => { x: number; y: number };
+export type Project = (lng: number, lat: number) => CartesianPoint;
 export type Unproject = (x: number, y: number) => { lat: number; lng: number };
 export type GetLngLatFromEvent = (event: PointerEvent | MouseEvent) => {
 	lng: number;

src/geometry/calculate-relative-angle.ts

@@ -1,3 +1,4 @@
+import { CartesianPoint } from "../common";
 import { webMercatorBearing } from "./measure/bearing";
 
 /**
@@ -8,9 +9,9 @@ import { webMercatorBearing } from "./measure/bearing";
  * @returns The relative angle between the two lines
  */
 export function calculateRelativeAngle(
-	A: { x: number; y: number },
-	B: { x: number; y: number },
-	C: { x: number; y: number },
+	A: CartesianPoint,
+	B: CartesianPoint,
+	C: CartesianPoint,
 ): number {
 	const bearingAB = webMercatorBearing(A, B); // Bearing from A to B
 	const bearingBC = webMercatorBearing(B, C); // Bearing from B to C

src/geometry/clockwise.ts

@@ -1,7 +1,9 @@
+import { CartesianPoint } from "../common";
+
 export function isClockwiseWebMercator(
-	center: { x: number; y: number },
-	secondCoord: { x: number; y: number },
-	thirdCoord: { x: number; y: number },
+	center: CartesianPoint,
+	secondCoord: CartesianPoint,
+	thirdCoord: CartesianPoint,
 ): boolean {
 	// Calculate the vectors
 	const vector1 = { x: secondCoord.x - center.x, y: secondCoord.y - center.y };

src/geometry/determine-halfplane.ts

@@ -1,8 +1,10 @@
+import { CartesianPoint } from "../common";
+
 // Function to determine the relative position of a point to a line segment
 export function determineHalfPlane(
-	point: { x: number; y: number },
-	lineStart: { x: number; y: number },
-	lineEnd: { x: number; y: number },
+	point: CartesianPoint,
+	lineStart: CartesianPoint,
+	lineEnd: CartesianPoint,
 ): string {
 	// Calculate the vectors
 	const vectorLine = { x: lineEnd.x - lineStart.x, y: lineEnd.y - lineStart.y };

src/geometry/measure/bearing.ts

@@ -1,5 +1,6 @@
 import { Position } from "geojson";
 import { degreesToRadians, radiansToDegrees } from "../helpers";
+import { CartesianPoint } from "../../common";
 
 // Adapted from the @turf/bearing module which is MIT Licensed
 // https://github.com/Turfjs/turf/tree/master/packages/turf-bearing
@@ -18,8 +19,8 @@ export function bearing(start: Position, end: Position): number {
 }
 
 export function webMercatorBearing(
-	{ x: x1, y: y1 }: { x: number; y: number },
-	{ x: x2, y: y2 }: { x: number; y: number },
+	{ x: x1, y: y1 }: CartesianPoint,
+	{ x: x2, y: y2 }: CartesianPoint,
 ): number {
 	const deltaX = x2 - x1;
 	const deltaY = y2 - y1;

src/geometry/measure/destination.ts

@@ -4,6 +4,7 @@ import {
 	lengthToRadians,
 	radiansToDegrees,
 } from "../helpers";
+import { CartesianPoint } from "../../common";
 
 // Adapted from @turf/destination module which is MIT Licensed
 // https://github.com/Turfjs/turf/blob/master/packages/turf-desination/index.ts
@@ -36,10 +37,10 @@ export function destination(
 
 // Function to create a destination point in Web Mercator projection
 export function webMercatorDestination(
-	{ x, y }: { x: number; y: number },
+	{ x, y }: CartesianPoint,
 	distance: number,
 	bearing: number,
-): { x: number; y: number } {
+): CartesianPoint {
 	// Convert origin to Web Mercator
 	const bearingRad = degreesToRadians(bearing);
 

src/geometry/measure/pixel-distance-to-line.ts

@@ -1,18 +1,20 @@
+import { CartesianPoint } from "../../common";
+
 export const pixelDistanceToLine = (
-	point: { x: number; y: number },
-	linePointOne: { x: number; y: number },
-	linePointTwo: { x: number; y: number },
+	point: CartesianPoint,
+	linePointOne: CartesianPoint,
+	linePointTwo: CartesianPoint,
 ) => {
 	const square = (x: number) => {
 		return x * x;
 	};
-	const dist2 = (v: { x: number; y: number }, w: { x: number; y: number }) => {
+	const dist2 = (v: CartesianPoint, w: CartesianPoint) => {
 		return square(v.x - w.x) + square(v.y - w.y);
 	};
 	const distToSegmentSquared = (
-		p: { x: number; y: number },
-		v: { x: number; y: number },
-		w: { x: number; y: number },
+		p: CartesianPoint,
+		v: CartesianPoint,
+		w: CartesianPoint,
 	) => {
 		const l2 = dist2(v, w);
 

src/geometry/measure/pixel-distance.ts

@@ -1,6 +1,8 @@
+import { CartesianPoint } from "../../common";
+
 export const cartesianDistance = (
-	pointOne: { x: number; y: number },
-	pointTwo: { x: number; y: number },
+	pointOne: CartesianPoint,
+	pointTwo: CartesianPoint,
 ) => {
 	const { x: x1, y: y1 } = pointOne;
 	const { x: x2, y: y2 } = pointTwo;

src/geometry/point-on-line.spec.ts

@@ -0,0 +1,59 @@
+import { nearestPointOnLine } from "./point-on-line";
+
+describe("nearestPointOnLine", () => {
+	it("returns exact feature coordinate if source coordinate is that coordinate", () => {
+		const result = nearestPointOnLine(
+			[0, 1],
+			[
+				[
+					[0, 0],
+					[0, 1],
+				],
+				[
+					[0, 1],
+					[1, 1],
+				],
+				[
+					[1, 1],
+					[1, 0],
+				],
+				[
+					[1, 0],
+					[0, 0],
+				],
+			],
+		);
+
+		expect(result?.coordinate).toEqual([0, 1]);
+		expect(result?.distance).toEqual(0);
+	});
+
+	it("returns coordinate on line", () => {
+		const result = nearestPointOnLine(
+			[0, 2],
+			[
+				[
+					[0, 0],
+					[0, 1],
+				],
+				[
+					[0, 1],
+					[1, 1],
+				],
+				[
+					[1, 1],
+					[1, 0],
+				],
+				[
+					[1, 0],
+					[0, 0],
+				],
+			],
+		);
+
+		expect(result?.coordinate[0]).toBeCloseTo(0);
+		expect(result?.coordinate[1]).toBeCloseTo(1);
+
+		expect(result?.distance).toBeCloseTo(111.19492664455873);
+	});
+});