API change: connect(c => ...) => connectDragPreview etc

Author: cormacrelf

docs/Connecting-to-DOM.md

@@ -72,8 +72,8 @@ touching the inputs / selecting text / making unwanted changes.
 
 1. Create an image element with `const img = new Image(); img.src = "...";`
 2. Use `img.onload = () => { ... }` to wait for it to load. Inside the onload
-   callback, run `someDragSourceConnection.connect(c => c.dragPreview(img))`.
+   callback, run `someDragSourceConnection.connectDragPreview(img)`.
 
-See [[DragSource.connect]], and [[DragSourceConnector.dragPreview]] for options.
+See [[DragSource.connectDragPreview]] and [[DragPreviewOptions]] for options.
 
 

docs/Tutorial.md

@@ -733,7 +733,7 @@ export class KnightComponent {
         const img = new Image();
         img.src = // ... long 'data:image/png;base64' url
                   // regular 'https://' URLs work here too
-        img.onload = () => this.knightSource.connect(c => c.dragPreview(img));
+        img.onload = () => this.knightSource.connectDragPreview(img);
     }
 }
 ```

packages/angular-skyhook/src/connection-types.ts

@@ -8,7 +8,7 @@ import { DragSourceMonitor } from './source-monitor';
 import { TypeOrTypeArray } from './type-ish';
 import { Observable, TeardownLogic } from 'rxjs';
 import { DragLayerMonitor } from './layer-monitor';
-import { DropTargetConnector, DragSourceConnector } from './connectors';
+import { DropTargetConnector, DragSourceConnector, DragSourceOptions, DragPreviewOptions } from './connectors';
 import { Subscription, SubscriptionLike } from 'rxjs';
 
 /** @private */
@@ -84,17 +84,6 @@ export interface ConnectionBase<TMonitor> extends SubscriptionLike {
 
 /** @private */
 export interface Connection<TMonitor, TConnector> extends ConnectionBase<TMonitor> {
-
-  /** This function allows you to connect a DOM node to your `DragSource`. It
-   *  is formulated as a callback so that connecting may be deferred until the
-   *  connection has a type. You will not usually need to call this directly;
-   *  it is more easily handled by the directives.
-   *
-   *  To connect a DOM node, you must use one of the methods provided by the
-   *  `connector` object in the callback.
-   */
-  connect(fn: (connector: TConnector) => void): Subscription;
-
 }
 
 /**
@@ -116,6 +105,14 @@ export interface DropTarget extends Connection<DropTargetMonitor, DropTargetConn
   */
   setTypes(type: TypeOrTypeArray): void;
 
+  /** This function allows you to connect a DOM node to your `DropTarget`.
+   *  You will not usually need to call this directly;
+   *  it is more easily handled by the directives.
+   *
+   *  The subscription returned is automatically unsubscribed when the connection is made.
+   *  This may be immediate if the `DropTarget` already has a type.
+   */
+  connectDropTarget(elementOrNode: Node): Subscription;
 }
 
 /**
@@ -157,6 +154,31 @@ export interface DragSource extends Connection<DragSourceMonitor,
 
    */
   setType(type: string|symbol): void;
+
+  /** This function allows you to connect a DOM node to your `DragSource`.
+   *  You will not usually need to call this directly;
+   *  it is more easily handled by the directives.
+   *
+   *  The subscription returned is automatically unsubscribed when the connection is made.
+   *  This may be immediate if the `DragSource` already has a type.
+   */
+  connectDragSource(elementOrNode: Node, options?: DragSourceOptions): Subscription;
+
+  /** This function allows you to connect a DOM node to your `DragSource` as a **preview**.
+   *  You will not usually need to call this directly;
+   *  it is more easily handled by the directives.
+   *
+   *  You might use an `ElementRef.nativeElement`, or even an
+   *  [`Image`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image).
+   *
+   *      const img = new Image();
+   *      img.onload = this.source.connectDragPreview(img);
+   *      img.src = '...';
+   *
+   *  The subscription returned is automatically unsubscribed when the connection is made.
+   *  This may be immediate if the `DragSource` already has a type.
+   */
+  connectDragPreview(elementOrNode: Node, options?: DragPreviewOptions): Subscription;
 }
 
 /**

packages/angular-skyhook/src/connectors.ts

@@ -63,12 +63,12 @@ export interface DragPreviewOptions {
 
 }
 
-/** Connects a drop target to a DOM element */
+/** @private Connects a drop target to a DOM element */
 export interface DropTargetConnector {
   dropTarget  ( elementOrNode: any): void;
 }
 
-/** Connects a drag source to a DOM element, either as the source itself or as
+/** @private Connects a drag source to a DOM element, either as the source itself or as
  *  a drag preview */
 export interface DragSourceConnector {
 

packages/angular-skyhook/src/dnd.directive.ts

@@ -91,7 +91,7 @@ export class DropTargetDirective extends DndDirective {
   }
 
   protected callHooks(conn: DropTarget): Subscription {
-    return conn.connect(c => c.dropTarget(this.elRef.nativeElement));
+    return conn.connectDropTarget(this.elRef.nativeElement);
   }
 }
 
@@ -118,7 +118,7 @@ export class DragSourceDirective extends DndDirective {
   }
 
   protected callHooks(conn: DragSource): Subscription {
-    return conn.connect(c => c.dragSource(this.elRef.nativeElement, this.dragSourceOptions));
+    return conn.connectDragSource(this.elRef.nativeElement, this.dragSourceOptions);
   }
 
 }
@@ -138,7 +138,7 @@ export class DragPreviewDirective extends DndDirective {
   }
 
   protected callHooks(conn: DragSource) {
-    return conn.connect(c => c.dragPreview(this.elRef.nativeElement, this.dragPreviewOptions));
+    return conn.connectDragPreview(this.elRef.nativeElement, this.dragPreviewOptions);
   }
 }
 

packages/angular-skyhook/src/index.ts

@@ -21,7 +21,7 @@ export {
 } from './connection-types';
 
 export {
-  DropTargetConnector, DragSourceConnector, DragSourceOptions, DragPreviewOptions
+  DragSourceOptions, DragPreviewOptions
 } from './connectors';
 
 export { DRAG_DROP_BACKEND, DRAG_DROP_MANAGER } from './tokens';

packages/angular-skyhook/src/internal/connection-factory.ts

@@ -16,7 +16,7 @@ import { areCollectsEqual } from '../utils/areCollectsEqual';
 import { DropTargetMonitor } from '../target-monitor';
 import { DragSourceMonitor } from '../source-monitor';
 import * as t from '../connection-types';
-import { DropTargetConnector, DragSourceConnector } from '../connectors';
+import { DropTargetConnector, DragSourceConnector, DragSourceOptions, DragPreviewOptions } from '../connectors';
 import { scheduleMicroTaskAfter } from './scheduleMicroTaskAfter';
 
 export interface FactoryArgs<TMonitor, TConnector> {
@@ -139,6 +139,18 @@ function connectionFactory<TMonitor extends DragSourceMonitor | DropTargetMonito
       });
     }
 
+    connectDropTarget(node: Node): Subscription {
+      return this.connect(c => (c as any as DropTargetConnector).dropTarget(node));
+    }
+
+    connectDragSource(node: Node, options: DragSourceOptions): Subscription {
+      return this.connect(c => (c as any as DragSourceConnector).dragSource(node, options));
+    }
+
+    connectDragPreview(node: Node, options: DragPreviewOptions): Subscription {
+      return this.connect(c => (c as any as DragSourceConnector).dragPreview(node, options));
+    }
+
     setTypes(type: TypeOrTypeArray) {
       // must run inside skyhookZone, so things like timers firing after a long hover with touch backend
       // will cause change detection (via executing a macro or event task)

packages/examples/src/app/chessboard/knight.component.ts

@@ -31,7 +31,7 @@ export class KnightComponent {
     ngOnInit() {
         const img = new Image();
         img.src = horseImage;
-        img.onload = () => this.knightSource.connect(c => c.dragPreview(img));
+        img.onload = () => this.knightSource.connectDragPreview(img);
     }
 
     ngOnDestroy() {

packages/examples/src/app/customize/handles-previews/custom-preview.component.ts

@@ -35,7 +35,7 @@ export class CustomPreview {
     var img = new Image();
     img.onload = () => {
       console.log("connecting image");
-      this.source.connect(c => c.dragPreview(img));
+      this.source.connectDragPreview(img);
     }
     // img.src = "https://angular.io/assets/images/logos/angular/angular.png";
     img.src =

packages/examples/src/app/drag-layer/draggable-box/draggable-box.component.ts

@@ -32,10 +32,10 @@ export class DraggableBoxComponent {
   constructor(private dnd: SkyhookDndService) { }
 
   ngOnInit() {
-    this.source.connect(c => c.dragPreview(getEmptyImage(), {
+    this.source.connectDragPreview(getEmptyImage(), {
       // for ie11 compat with DragLayer
       captureDraggingState: true
-    }));
+    });
   }
 
   ngOnDestroy() {