bunch of comments

src/dnd/ElementDragging.ts

@@ -1,6 +1,12 @@
 import EmitterMixin from '../common/EmitterMixin'
 
-/* emits:
+/*
+An abstraction for a dragging interaction originating on an event.
+Does higher-level things than PointerDragger, such as possibly:
+- a "mirror" that moves with the pointer
+- a minimum number of pixels or other criteria for a true drag to begin
+
+subclasses must emit:
 - pointerdown
 - dragstart
 - dragmove
@@ -19,12 +25,15 @@ export default abstract class ElementDragging {
   }
 
   setIgnoreMove(bool: boolean) {
+    // optional. used for optimization
   }
 
   setMirrorIsVisible(bool: boolean) {
+    // optional if subclass doesn't want to support a mirror
   }
 
   setMirrorNeedsRevert(bool: boolean) {
+    // optional if subclass doesn't want to support a mirror
   }
 
 }

src/dnd/ElementMirror.ts

@@ -2,6 +2,11 @@ import { removeElement, applyStyle } from '../util/dom-manip'
 import { computeRect } from '../util/dom-geom'
 import { whenTransitionDone } from '../util/dom-event'
 
+/*
+An effect in which an element follows the movement of a pointer across the screen.
+The moving element is a clone of some other element.
+Must call start + handleMove + stop.
+*/
 export default class ElementMirror {
 
   isVisible: boolean = false
@@ -12,6 +17,9 @@ export default class ElementMirror {
   sourceEl: HTMLElement
   mirrorEl: HTMLElement
   sourceElRect: any
+
+  // options that can be set directly by caller
+  // TODO: wire up
   revertDuration: number = 1000
 
   start(sourceEl, left, top) {
@@ -29,6 +37,7 @@ export default class ElementMirror {
     this.updateElPosition()
   }
 
+  // can be called before start
   setIsVisible(bool: boolean) {
     if (bool) {
       if (!this.isVisible) {
@@ -51,20 +60,20 @@ export default class ElementMirror {
   }
 
   // always async
-  stop(doRevertAnimation, callback) {
+  stop(needsRevertAnimation: boolean, callback: () => void) {
     let done = () => {
       this.cleanup()
       callback()
     }
 
-    if (doRevertAnimation && this.mirrorEl && this.isVisible) {
-      this.doAnimation(done)
+    if (needsRevertAnimation && this.mirrorEl && this.isVisible) {
+      this.doRevertAnimation(done)
     } else {
       setTimeout(done, 0)
     }
   }
 
-  doAnimation(callback) {
+  doRevertAnimation(callback: () => void) {
     let { mirrorEl } = this
 
     mirrorEl.style.transition =
@@ -136,6 +145,7 @@ export default class ElementMirror {
         //zIndex: this.options.zIndex
       })
 
+      // TODO: appendTo setting
       document.body.appendChild(mirrorEl)
     }
 

src/dnd/FeaturefulElementDragging.ts

@@ -3,14 +3,20 @@ import { preventSelection, allowSelection, preventContextMenu, allowContextMenu
 import ElementMirror from './ElementMirror'
 import ElementDragging from './ElementDragging'
 
-
+/*
+Monitors dragging on an element. Has a number of high-level features:
+- minimum distance required before dragging
+- minimum wait time ("delay") before dragging
+- a mirror element that follows the pointer
+*/
 export default class FeaturefulElementDragging extends ElementDragging {
 
   pointer: PointerDragging
   mirror: ElementMirror
   mirrorNeedsRevert: boolean = false
 
-  // options
+  // options that can be directly set by caller
+  // the caller can also set the PointerDragging's options as well
   delay: number
   minDistance: number = 0
   touchScrollAllowed: boolean = true
@@ -19,7 +25,6 @@ export default class FeaturefulElementDragging extends ElementDragging {
   isDragging: boolean = false // is it INTENTFULLY dragging? lasts until after revert animation
   isDelayEnded: boolean = false
   isDistanceSurpassed: boolean = false
-
   delayTimeoutId: number
   origX: number
   origY: number
@@ -94,7 +99,7 @@ export default class FeaturefulElementDragging extends ElementDragging {
     if (this.isWatchingPointer) { // if false, still waiting for previous drag's revert
       this.isWatchingPointer = false
 
-      this.emitter.trigger('pointerup', ev) // can potentially set needsRevert
+      this.emitter.trigger('pointerup', ev) // can potentially set mirrorNeedsRevert
 
       if (this.isDragging) {
         this.tryStopDrag(ev)
@@ -159,6 +164,8 @@ export default class FeaturefulElementDragging extends ElementDragging {
     this.emitter.trigger('dragend', ev)
   }
 
+  // fill in the implementations...
+
   setIgnoreMove(bool: boolean) {
     this.pointer.shouldIgnoreMove = bool
   }

src/dnd/PointerDragging.ts

@@ -13,7 +13,13 @@ export interface PointerDragEvent {
 }
 
 /*
-emitted events:
+Uses a "pointer" abstraction, which monitors UI events for both mouse and touch.
+Tracks when the pointer "drags" on a certain element, meaning down+move+up.
+
+Also, tracks if there was touch-scrolling.
+Also, can prevent touch-scrolling from happening.
+
+emits:
 - pointerdown
 - pointermove
 - pointerup
@@ -25,8 +31,8 @@ export default class PointerDragging {
   downEl: HTMLElement
   emitter: EmitterMixin
 
-  // options
-  selector: string
+  // options that can be directly assigned by caller
+  selector: string // will cause subjectEl in all emitted events to be this element
   handleSelector: string
   shouldIgnoreMove: boolean = false