fix(cdk/drag-drop): expose pickup position in constrainPosition callback (#25341)

Exposes the pickup position within the element to the `constrainPosition` callback so that users can account for it in their calculations.

Relates to #25154.

Author: crisbeto

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

@@ -1082,6 +1082,7 @@ describe('CdkDrag', () => {
         jasmine.objectContaining({x: 300, y: 300}),
         jasmine.any(DragRef),
         jasmine.anything(),
+        jasmine.objectContaining({x: jasmine.any(Number), y: jasmine.any(Number)}),
       );
 
       const elementRect = dragElement.getBoundingClientRect();
@@ -3685,6 +3686,7 @@ describe('CdkDrag', () => {
         jasmine.objectContaining({x: 200, y: 200}),
         jasmine.any(DragRef),
         jasmine.anything(),
+        jasmine.objectContaining({x: jasmine.any(Number), y: jasmine.any(Number)}),
       );
       expect(Math.floor(previewRect.top)).toBe(50);
       expect(Math.floor(previewRect.left)).toBe(50);

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

@@ -139,6 +139,7 @@ export class CdkDrag<T = any> implements AfterViewInit, OnChanges, OnDestroy {
     userPointerPosition: Point,
     dragRef: DragRef,
     dimensions: ClientRect,
+    pickupPositionInElement: Point,
   ) => Point;
 
   /** Class to be added to the preview element. */

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

@@ -365,6 +365,7 @@ export class DragRef<T = any> {
     userPointerPosition: Point,
     dragRef: DragRef,
     dimensions: ClientRect,
+    pickupPositionInElement: Point,
   ) => Point;
 
   constructor(
@@ -1239,7 +1240,7 @@ export class DragRef<T = any> {
   private _getConstrainedPointerPosition(point: Point): Point {
     const dropContainerLock = this._dropContainer ? this._dropContainer.lockAxis : null;
     let {x, y} = this.constrainPosition
-      ? this.constrainPosition(point, this, this._initialClientRect!)
+      ? this.constrainPosition(point, this, this._initialClientRect!, this._pickupPositionInElement)
       : point;
 
     if (this.lockAxis === 'x' || dropContainerLock === 'x') {

tools/public_api_guard/cdk/drag-drop.md

@@ -55,7 +55,7 @@ export class CdkDrag<T = any> implements AfterViewInit, OnChanges, OnDestroy {
     dropContainer: CdkDropListInternal,
     _document: any, _ngZone: NgZone, _viewContainerRef: ViewContainerRef, config: DragDropConfig, _dir: Directionality, dragDrop: DragDrop, _changeDetectorRef: ChangeDetectorRef, _selfHandle?: CdkDragHandle | undefined, _parentDrag?: CdkDrag<any> | undefined);
     boundaryElement: string | ElementRef<HTMLElement> | HTMLElement;
-    constrainPosition?: (userPointerPosition: Point, dragRef: DragRef, dimensions: ClientRect) => Point;
+    constrainPosition?: (userPointerPosition: Point, dragRef: DragRef, dimensions: ClientRect, pickupPositionInElement: Point) => Point;
     data: T;
     get disabled(): boolean;
     set disabled(value: BooleanInput);
@@ -359,7 +359,7 @@ export class DragDropRegistry<I extends {
 export class DragRef<T = any> {
     constructor(element: ElementRef<HTMLElement> | HTMLElement, _config: DragRefConfig, _document: Document, _ngZone: NgZone, _viewportRuler: ViewportRuler, _dragDropRegistry: DragDropRegistry<DragRef, DropListRefInternal>);
     readonly beforeStarted: Subject<void>;
-    constrainPosition?: (userPointerPosition: Point, dragRef: DragRef, dimensions: ClientRect) => Point;
+    constrainPosition?: (userPointerPosition: Point, dragRef: DragRef, dimensions: ClientRect, pickupPositionInElement: Point) => Point;
     data: T;
     get disabled(): boolean;
     set disabled(value: boolean);