docs(drag-drop): add doc section and live example for customizing the placeholder (#13777)

Adds a paragraph about the `cdkDragPlaceholder` and sets up a live example.

Fixes #13765.

Author: crisbeto

src/cdk/drag-drop/drag-drop.md

@@ -104,6 +104,14 @@ This preview can be customized, though, by providing a custom template via `*cdk
 
 <!-- example(cdk-drag-drop-custom-preview) -->
 
+### Customizing the drag placeholder
+While a `cdkDrag` element is being dragged, the CDK will create a placeholder element that will
+show where it will be placed when it's dropped. By default the placeholder is a clone of the element
+that is being dragged, however you can replace it with a custom one using the `*cdkDragPlaceholder`
+directive:
+
+<!-- example(cdk-drag-drop-custom-placeholder) -->
+
 ### List orientation
 The `cdkDropList` directive assumes that lists are vertical by default. This can be
 changed by setting the `orientation` property to `"horizontal".

src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.css

@@ -0,0 +1,51 @@
+.example-list {
+  width: 500px;
+  max-width: 100%;
+  border: solid 1px #ccc;
+  min-height: 60px;
+  display: block;
+  background: white;
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+.example-box {
+  padding: 20px 10px;
+  border-bottom: solid 1px #ccc;
+  color: rgba(0, 0, 0, 0.87);
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: space-between;
+  box-sizing: border-box;
+  cursor: move;
+  background: white;
+  font-size: 14px;
+}
+
+.cdk-drag-preview {
+  box-sizing: border-box;
+  border-radius: 4px;
+  box-shadow: 0 5px 5px -3px rgba(0, 0, 0, 0.2),
+              0 8px 10px 1px rgba(0, 0, 0, 0.14),
+              0 3px 14px 2px rgba(0, 0, 0, 0.12);
+}
+
+.cdk-drag-animating {
+  transition: transform 250ms cubic-bezier(0, 0, 0.2, 1);
+}
+
+.example-box:last-child {
+  border: none;
+}
+
+.example-list.cdk-drop-list-dragging .example-box:not(.cdk-drag-placeholder) {
+  transition: transform 250ms cubic-bezier(0, 0, 0.2, 1);
+}
+
+.example-custom-placeholder {
+  background: #ccc;
+  border: dotted 3px #999;
+  min-height: 60px;
+  transition: transform 250ms cubic-bezier(0, 0, 0.2, 1);
+}

src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.html

@@ -0,0 +1,6 @@
+<div cdkDropList class="example-list" (cdkDropListDropped)="drop($event)">
+  <div class="example-box" *ngFor="let movie of movies" cdkDrag>
+    <div class="example-custom-placeholder" *cdkDragPlaceholder></div>
+    {{movie}}
+  </div>
+</div>

src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.ts

@@ -0,0 +1,27 @@
+import {Component} from '@angular/core';
+import {CdkDragDrop, moveItemInArray} from '@angular/cdk/drag-drop';
+
+/**
+ * @title Drag&Drop custom placeholer
+ */
+@Component({
+  selector: 'cdk-drag-drop-custom-placeholder-example',
+  templateUrl: 'cdk-drag-drop-custom-placeholder-example.html',
+  styleUrls: ['cdk-drag-drop-custom-placeholder-example.css'],
+})
+export class CdkDragDropCustomPlaceholderExample {
+  movies = [
+    'Episode I - The Phantom Menace',
+    'Episode II - Attack of the Clones',
+    'Episode III - Revenge of the Sith',
+    'Episode IV - A New Hope',
+    'Episode V - The Empire Strikes Back',
+    'Episode VI - Return of the Jedi',
+    'Episode VII - The Force Awakens',
+    'Episode VIII - The Last Jedi'
+  ];
+
+  drop(event: CdkDragDrop<string[]>) {
+    moveItemInArray(this.movies, event.previousIndex, event.currentIndex);
+  }
+}