fix(drag-drop): allow preview z-index to be changed

The CDK drag preview has a `z-index` that works with the CDK overlay, but might be too low for other libraries. These changes add an option that allows consumers to override it.

Fixes angular#18902.

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

@@ -42,6 +42,7 @@ export interface DragDropConfig extends Partial<DragRefConfig> {
   sortingDisabled?: boolean;
   listAutoScrollDisabled?: boolean;
   listOrientation?: DropListOrientation;
+  zIndex?: number;
 }
 
 /**

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

@@ -1929,6 +1929,7 @@ describe('CdkDrag', () => {
       expect(previewRect.height).toBe(itemRect.height, 'Expected preview height to match element');
       expect(preview.style.pointerEvents)
           .toBe('none', 'Expected pointer events to be disabled on the preview');
+      expect(preview.style.zIndex).toBe('1000', 'Expected preview to have a high default zIndex.');
       // Use a regex here since some browsers normalize 0 to 0px, but others don't.
       expect(preview.style.margin).toMatch(/^0(px)?$/, 'Expected the preview margin to be reset.');
 
@@ -1942,6 +1943,22 @@ describe('CdkDrag', () => {
       expect(preview.parentNode).toBeFalsy('Expected preview to be removed from the DOM');
     }));
 
+    it('should be able to configure the preview z-index', fakeAsync(() => {
+      const fixture = createComponent(DraggableInDropZone, [{
+        provide: CDK_DRAG_CONFIG,
+        useValue: {
+          dragStartThreshold: 0,
+          zIndex: 3000
+        }
+      }]);
+      fixture.detectChanges();
+      const item = fixture.componentInstance.dragItems.toArray()[1].element.nativeElement;
+      startDraggingViaMouse(fixture, item);
+
+      const preview = document.querySelector('.cdk-drag-preview')! as HTMLElement;
+      expect(preview.style.zIndex).toBe('3000');
+    }));
+
     it('should create the preview inside the fullscreen element when in fullscreen mode',
       fakeAsync(() => {
         // Provide a limited stub of the document since we can't trigger fullscreen

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

@@ -198,7 +198,8 @@ export class CdkDrag<T = any> implements AfterViewInit, OnChanges, OnDestroy {
       dragStartThreshold: config && config.dragStartThreshold != null ?
           config.dragStartThreshold : 5,
       pointerDirectionChangeThreshold: config && config.pointerDirectionChangeThreshold != null ?
-          config.pointerDirectionChangeThreshold : 5
+          config.pointerDirectionChangeThreshold : 5,
+      zIndex: config?.zIndex
     });
     this._dragRef.data = this;
 

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

@@ -31,6 +31,9 @@ export interface DragRefConfig {
    * considers them to have changed the drag direction.
    */
   pointerDirectionChangeThreshold: number;
+
+  /** `z-index` for the absolutely-positioned elements that are created by the drag item. */
+  zIndex?: number;
 }
 
 /** Options that can be used to bind a passive event listener. */
@@ -909,7 +912,7 @@ export class DragRef<T = any> {
       position: 'fixed',
       top: '0',
       left: '0',
-      zIndex: '1000'
+      zIndex: `${this._config.zIndex || 1000}`
     });
 
     toggleNativeDragInteractions(preview, false);

tools/public_api_guard/cdk/drag-drop.d.ts

@@ -217,6 +217,7 @@ export interface DragDropConfig extends Partial<DragRefConfig> {
     previewClass?: string | string[];
     rootElementSelector?: string;
     sortingDisabled?: boolean;
+    zIndex?: number;
 }
 
 export declare class DragDropModule {
@@ -318,6 +319,7 @@ export declare class DragRef<T = any> {
 export interface DragRefConfig {
     dragStartThreshold: number;
     pointerDirectionChangeThreshold: number;
+    zIndex?: number;
 }
 
 export declare type DragStartDelay = number | {