feat(cdk/drag-drop): adding method to set drag position (#24769)

Adds method `setFreeDragPosition` in Cdk `DragDrop` directive to set position in pixel on a drop container.
Also corrects some inaccurate types on a couple of freeDragPosition methods of the `DragDrop` directive.

Fixes #18530

Author: meriturva

src/cdk/drag-drop/directives/drag.spec.ts

@@ -1258,6 +1258,19 @@ describe('CdkDrag', () => {
       expect(dragInstance.getFreeDragPosition()).toEqual({x: 150, y: 300});
     }));
 
+    it('should be able to set the current position programmatically', fakeAsync(() => {
+      const fixture = createComponent(StandaloneDraggable);
+      fixture.detectChanges();
+
+      const dragElement = fixture.componentInstance.dragElement.nativeElement;
+      const dragInstance = fixture.componentInstance.dragInstance;
+
+      dragInstance.setFreeDragPosition({x: 50, y: 100});
+
+      expect(dragElement.style.transform).toBe('translate3d(50px, 100px, 0px)');
+      expect(dragInstance.getFreeDragPosition()).toEqual({x: 50, y: 100});
+    }));
+
     it('should be able to set the current position', fakeAsync(() => {
       const fixture = createComponent(StandaloneDraggable);
       fixture.componentInstance.freeDragPosition = {x: 50, y: 100};

src/cdk/drag-drop/directives/drag.ts

@@ -116,7 +116,7 @@ export class CdkDrag<T = any> implements AfterViewInit, OnChanges, OnDestroy {
    * Sets the position of a `CdkDrag` that is outside of a drop container.
    * Can be used to restore the element's position for a returning user.
    */
-  @Input('cdkDragFreeDragPosition') freeDragPosition: {x: number; y: number};
+  @Input('cdkDragFreeDragPosition') freeDragPosition: Point;
 
   /** Whether starting to drag this element is disabled. */
   @Input('cdkDragDisabled')
@@ -282,10 +282,18 @@ export class CdkDrag<T = any> implements AfterViewInit, OnChanges, OnDestroy {
   /**
    * Gets the pixel coordinates of the draggable outside of a drop container.
    */
-  getFreeDragPosition(): {readonly x: number; readonly y: number} {
+  getFreeDragPosition(): Readonly<Point> {
     return this._dragRef.getFreeDragPosition();
   }
 
+  /**
+   * Sets the current position in pixels the draggable outside of a drop container.
+   * @param value New position to be set.
+   */
+  setFreeDragPosition(value: Point): void {
+    this._dragRef.setFreeDragPosition(value);
+  }
+
   ngAfterViewInit() {
     // Normally this isn't in the zone, but it can cause major performance regressions for apps
     // using `zone-patch-rxjs` because it'll trigger a change detection when it unsubscribes.

tools/public_api_guard/cdk/drag-drop.md

@@ -67,14 +67,8 @@ export class CdkDrag<T = any> implements AfterViewInit, OnChanges, OnDestroy {
     readonly ended: EventEmitter<CdkDragEnd>;
     readonly entered: EventEmitter<CdkDragEnter<any>>;
     readonly exited: EventEmitter<CdkDragExit<any>>;
-    freeDragPosition: {
-        x: number;
-        y: number;
-    };
-    getFreeDragPosition(): {
-        readonly x: number;
-        readonly y: number;
-    };
+    freeDragPosition: Point;
+    getFreeDragPosition(): Readonly<Point>;
     getPlaceholderElement(): HTMLElement;
     getRootElement(): HTMLElement;
     _handles: QueryList<CdkDragHandle>;
@@ -93,6 +87,7 @@ export class CdkDrag<T = any> implements AfterViewInit, OnChanges, OnDestroy {
     readonly released: EventEmitter<CdkDragRelease>;
     reset(): void;
     rootElementSelector: string;
+    setFreeDragPosition(value: Point): void;
     readonly started: EventEmitter<CdkDragStart>;
     // (undocumented)
     static ɵdir: i0.ɵɵDirectiveDeclaration<CdkDrag<any>, "[cdkDrag]", ["cdkDrag"], { "data": "cdkDragData"; "lockAxis": "cdkDragLockAxis"; "rootElementSelector": "cdkDragRootElement"; "boundaryElement": "cdkDragBoundary"; "dragStartDelay": "cdkDragStartDelay"; "freeDragPosition": "cdkDragFreeDragPosition"; "disabled": "cdkDragDisabled"; "constrainPosition": "cdkDragConstrainPosition"; "previewClass": "cdkDragPreviewClass"; "previewContainer": "cdkDragPreviewContainer"; }, { "started": "cdkDragStarted"; "released": "cdkDragReleased"; "ended": "cdkDragEnded"; "entered": "cdkDragEntered"; "exited": "cdkDragExited"; "dropped": "cdkDragDropped"; "moved": "cdkDragMoved"; }, ["_previewTemplate", "_placeholderTemplate", "_handles"]>;