feat: add DrawLineStringByDraggingMode ("Pencil" mode)

docs/api-reference/modes/overview.md

@@ -113,6 +113,10 @@ User can draw a new `Polygon` feature with 90 degree corners (right angle) by cl
 
 User can draw a new `Polygon` feature by dragging (similar to the lasso tool commonly found in photo editing software).
 
+## [DrawLineStringByDraggingMode](https://github.com/uber/nebula.gl/blob/master/modules/edit-modes/src/lib/draw-line-string-by-dragging-mode.ts)
+
+User can draw a new `LineString` feature by dragging (similar to the pencil tool commonly found in sketching software).
+
 ### ModeConfig
 
 The following options can be provided in the `modeConfig` object:

docs/whats-new.md

@@ -10,6 +10,10 @@ Release date: TBD
 
 - new `DrawRectangleFromCenterMode`. User can draw a new rectangular `Polygon` feature by clicking the center, then along a corner of the rectangle.
 
+### Draw LineString by Dragging Mode
+
+- new `DrawLineStringByDraggingMode`. User can draw a `LineString` feature by dragging on the map, and releasing their cursor.
+
 ### Translate mode
 
 - `screenSpace` option can be provided in the `modeConfig` of Translate mode so the features will be translated without distortion in screen space.

examples/advanced/src/example.tsx

@@ -34,6 +34,7 @@ import {
   DrawRectangleUsingThreePointsMode,
   Draw90DegreePolygonMode,
   DrawPolygonByDraggingMode,
+  DrawLineStringByDraggingMode,
   MeasureDistanceMode,
   MeasureAreaMode,
   MeasureAngleMode,
@@ -105,6 +106,7 @@ const ALL_MODES: any = [
       { label: 'Draw Polygon', mode: DrawPolygonMode },
       { label: 'Draw 90° Polygon', mode: Draw90DegreePolygonMode },
       { label: 'Draw Polygon By Dragging', mode: DrawPolygonByDraggingMode },
+      { label: 'Draw LineString By Dragging', mode: DrawLineStringByDraggingMode },
       { label: 'Draw Rectangle', mode: DrawRectangleMode },
       { label: 'Draw Rectangle From Center', mode: DrawRectangleFromCenterMode },
       { label: 'Draw Rectangle Using 3 Points', mode: DrawRectangleUsingThreePointsMode },
@@ -966,6 +968,11 @@ export default class Example extends React.Component<
         ...modeConfig,
         throttleMs: 100,
       };
+    } else if (mode === DrawLineStringByDraggingMode) {
+      modeConfig = {
+        ...modeConfig,
+        throttleMs: 100,
+      };
     }
 
     // Demonstrate how to override sub layer properties

modules/edit-modes/src/index.ts

@@ -36,6 +36,7 @@ export { DrawEllipseUsingThreePointsMode } from './lib/draw-ellipse-using-three-
 export { DrawRectangleUsingThreePointsMode } from './lib/draw-rectangle-using-three-points-mode';
 export { Draw90DegreePolygonMode } from './lib/draw-90degree-polygon-mode';
 export { DrawPolygonByDraggingMode } from './lib/draw-polygon-by-dragging-mode';
+export { DrawLineStringByDraggingMode } from './lib/draw-line-string-by-dragging-mode';
 export { ImmutableFeatureCollection } from './lib/immutable-feature-collection';
 
 // Other modes

modules/edit-modes/src/lib/draw-line-string-by-dragging-mode.ts

@@ -0,0 +1,72 @@
+import throttle from 'lodash.throttle';
+import { DebouncedFunc } from 'lodash';
+import {
+  ClickEvent,
+  StartDraggingEvent,
+  StopDraggingEvent,
+  DraggingEvent,
+  ModeProps,
+} from '../types';
+import { LineString, FeatureCollection } from '../geojson-types';
+import { getPickedEditHandle } from '../utils';
+import { DrawLineStringMode } from './draw-line-string-mode';
+
+type DragHandler = (event: DraggingEvent, props: ModeProps<FeatureCollection>) => void;
+
+type ThrottledDragHandler = DebouncedFunc<DragHandler>;
+
+export class DrawLineStringByDraggingMode extends DrawLineStringMode {
+  handleDraggingThrottled: ThrottledDragHandler | DragHandler | null | undefined = null;
+
+  // Override the default behavior of DrawLineStringMode to not add a point when the user clicks on the map
+  handleClick(event: ClickEvent, props: ModeProps<FeatureCollection>) {
+    return;
+  }
+
+  handleStartDragging(event: StartDraggingEvent, props: ModeProps<FeatureCollection>) {
+    event.cancelPan();
+    if (props.modeConfig && props.modeConfig.throttleMs) {
+      this.handleDraggingThrottled = throttle(this.handleDraggingAux, props.modeConfig.throttleMs);
+    } else {
+      this.handleDraggingThrottled = this.handleDraggingAux;
+    }
+  }
+
+  handleStopDragging(event: StopDraggingEvent, props: ModeProps<FeatureCollection>) {
+    this.addClickSequence(event);
+    const clickSequence = this.getClickSequence();
+    if (this.handleDraggingThrottled && 'cancel' in this.handleDraggingThrottled) {
+      this.handleDraggingThrottled.cancel();
+    }
+
+    if (clickSequence.length > 2) {
+      const lineStringToAdd: LineString = {
+        type: 'LineString',
+        coordinates: clickSequence,
+      };
+
+      this.resetClickSequence();
+
+      const editAction = this.getAddFeatureAction(lineStringToAdd, props.data);
+      if (editAction) {
+        props.onEdit(editAction);
+      }
+    }
+  }
+
+  handleDraggingAux(event: DraggingEvent, props: ModeProps<FeatureCollection>) {
+    const { picks } = event;
+    const clickedEditHandle = getPickedEditHandle(picks);
+
+    if (!clickedEditHandle) {
+      // Don't add another point right next to an existing one.
+      this.addClickSequence(event);
+    }
+  }
+
+  handleDragging(event: DraggingEvent, props: ModeProps<FeatureCollection>) {
+    if (this.handleDraggingThrottled) {
+      this.handleDraggingThrottled(event, props);
+    }
+  }
+}

modules/edit-modes/test/lib/draw-line-string-by-dragging-mode.test.ts

@@ -0,0 +1,51 @@
+import { FeatureCollection } from '@nebula.gl/edit-modes';
+import { DrawLineStringByDraggingMode } from '../../src/lib/draw-line-string-by-dragging-mode';
+import {
+  createFeatureCollectionProps,
+  createStartDraggingEvent,
+  createPointerMoveEvent,
+  createStopDraggingEvent,
+  createDraggingEvent,
+} from '../test-utils';
+import { ModeProps } from '../../src';
+
+let props: ModeProps<FeatureCollection>;
+let mode: DrawLineStringByDraggingMode;
+
+describe('after drag', () => {
+  beforeEach(() => {
+    mode = new DrawLineStringByDraggingMode();
+    props = createFeatureCollectionProps({
+      data: {
+        type: 'FeatureCollection',
+        features: [],
+      },
+    });
+
+    mode.handleStartDragging(createStartDraggingEvent([2, 2], [1, 2]), props);
+  });
+
+  it("doesn't call onEdit on a very short line", () => {
+    mode.handleStopDragging(createStopDraggingEvent([4, 3], [1, 2]), props);
+    const mockedOnEdit = vi.mocked(props.onEdit);
+    expect(mockedOnEdit).toHaveBeenCalledTimes(0);
+  });
+
+  it('calls onEdit with new LineString feature', () => {
+    mode.handleDragging(createDraggingEvent([2, 3], [1, 2]), props);
+    mode.handleDragging(createDraggingEvent([3, 3], [1, 2]), props);
+    mode.handleStopDragging(createStopDraggingEvent([4, 3], [1, 2]), props);
+
+    const mockedOnEdit = vi.mocked(props.onEdit);
+    expect(mockedOnEdit).toHaveBeenCalledTimes(1);
+
+    expect(mockedOnEdit.mock.calls[0][0].editType).toEqual('addFeature');
+    const features = mockedOnEdit.mock.calls[0][0].updatedData.features;
+    expect(features.length).toBe(1);
+    expect(features[0].geometry.coordinates).toEqual([
+      [2, 3],
+      [3, 3],
+      [4, 3],
+    ]);
+  });
+});

modules/edit-modes/test/test-utils.ts

@@ -1,4 +1,4 @@
-import { Position, FeatureCollection } from '@nebula.gl/edit-modes';
+import { Position, FeatureCollection, DraggingEvent } from '@nebula.gl/edit-modes';
 import {
   ModeProps,
   ClickEvent,
@@ -285,7 +285,7 @@ export function getFeatureCollectionFeatures(options?: { [K: string]: any }) {
   ];
 }
 
-export function createFeatureCollection(options?: { [K: string]: any }) {
+export function createFeatureCollection(options?: { [K: string]: any }): FeatureCollection {
   return {
     type: 'FeatureCollection',
     features: getFeatureCollectionFeatures(options),
@@ -338,6 +338,25 @@ export function createStartDraggingEvent(
   };
 }
 
+export function createDraggingEvent(
+  mapCoords: Position,
+  pointerDownMapCoords: Position,
+  picks: Pick[] = []
+): DraggingEvent {
+  lastCoords = mapCoords;
+
+  return {
+    screenCoords: [-1, -1],
+    mapCoords,
+    picks,
+    pointerDownPicks: null,
+    pointerDownScreenCoords: [-1, -1],
+    pointerDownMapCoords,
+    cancelPan: vi.fn(),
+    sourceEvent: null,
+  };
+}
+
 export function createStopDraggingEvent(
   mapCoords: Position,
   pointerDownMapCoords: Position,
@@ -379,14 +398,13 @@ export function createFeatureCollectionProps(
   overrides: Partial<ModeProps<FeatureCollection>> = {}
 ): ModeProps<FeatureCollection> {
   return {
-    // @ts-ignore
     data: createFeatureCollection(),
     selectedIndexes: [],
-    // @ts-ignore
     lastPointerMoveEvent: createPointerMoveEvent(),
     modeConfig: null,
     onEdit: vi.fn(),
     onUpdateCursor: vi.fn(),
+    cursor: undefined,
     ...overrides,
   };
 }

modules/layers/src/layers/editable-geojson-layer.ts

@@ -26,6 +26,7 @@ import {
   DrawEllipseUsingThreePointsMode,
   Draw90DegreePolygonMode,
   DrawPolygonByDraggingMode,
+  DrawLineStringByDraggingMode,
   SnappableMode,
   TransformMode,
   EditAction,
@@ -260,6 +261,7 @@ const modeNameMapping = {
   drawEllipseUsing3Points: DrawEllipseUsingThreePointsMode,
   draw90DegreePolygon: Draw90DegreePolygonMode,
   drawPolygonByDragging: DrawPolygonByDraggingMode,
+  drawLineStringByDragging: DrawLineStringByDraggingMode,
 };
 
 // type State = {

modules/main/src/index.ts

@@ -57,6 +57,7 @@ export { DrawEllipseUsingThreePointsMode } from '@nebula.gl/edit-modes';
 export { DrawRectangleUsingThreePointsMode } from '@nebula.gl/edit-modes';
 export { Draw90DegreePolygonMode } from '@nebula.gl/edit-modes';
 export { DrawPolygonByDraggingMode } from '@nebula.gl/edit-modes';
+export { DrawLineStringByDraggingMode } from '@nebula.gl/edit-modes';
 export { ImmutableFeatureCollection } from '@nebula.gl/edit-modes';
 
 // Other modes

modules/react-map-gl-draw/src/index.ts

@@ -14,6 +14,7 @@ export {
   DrawPolygonMode,
   DrawRectangleMode,
   DrawPolygonByDraggingMode,
+  DrawLineStringByDraggingMode,
   MeasureDistanceMode,
   MeasureAreaMode,
   MeasureAngleMode,