From a274b18c18058d5074b9ce75244d7cfe0bf5968c Mon Sep 17 00:00:00 2001
From: crisbeto <crisbeto@abv.bg>
Date: Tue, 23 Oct 2018 22:50:08 +0200
Subject: [PATCH] docs(drag-drop): add doc section and live example for
 customizing the placeholder

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

Fixes #13765.
---
 src/cdk/drag-drop/drag-drop.md                |  8 +++
 ...k-drag-drop-custom-placeholder-example.css | 51 +++++++++++++++++++
 ...-drag-drop-custom-placeholder-example.html |  6 +++
 ...dk-drag-drop-custom-placeholder-example.ts | 27 ++++++++++
 4 files changed, 92 insertions(+)
 create mode 100644 src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.css
 create mode 100644 src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.html
 create mode 100644 src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.ts

diff --git a/src/cdk/drag-drop/drag-drop.md b/src/cdk/drag-drop/drag-drop.md
index f7e2a22d5f32..18172e721641 100644
--- a/src/cdk/drag-drop/drag-drop.md
+++ b/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".
diff --git a/src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.css b/src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.css
new file mode 100644
index 000000000000..ff2e445b8ccc
--- /dev/null
+++ b/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);
+}
diff --git a/src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.html b/src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.html
new file mode 100644
index 000000000000..68994b543234
--- /dev/null
+++ b/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>
diff --git a/src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.ts b/src/material-examples/cdk-drag-drop-custom-placeholder/cdk-drag-drop-custom-placeholder-example.ts
new file mode 100644
index 000000000000..474963cc6262
--- /dev/null
+++ b/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);
+  }
+}