From 78bbc92ad24bbefd1ed1b479f0bb8a110219150d Mon Sep 17 00:00:00 2001
From: Kristiyan Kostadinov <crisbeto@users.noreply.github.com>
Date: Fri, 10 May 2019 16:31:09 -0400
Subject: [PATCH] docs(drag-drop): add docs for cdkDragFreeDragPosition
 (#15978)

Adds docs and a live example of the `cdkDragFreeDragPosition` input.
---
 src/cdk/drag-drop/drag-drop.md                | 10 +++++++-
 ...k-drag-drop-free-drag-position-example.css | 25 +++++++++++++++++++
 ...-drag-drop-free-drag-position-example.html |  7 ++++++
 ...dk-drag-drop-free-drag-position-example.ts | 17 +++++++++++++
 4 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.css
 create mode 100644 src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.html
 create mode 100644 src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.ts

diff --git a/src/cdk/drag-drop/drag-drop.md b/src/cdk/drag-drop/drag-drop.md
index 44dcb9ce334..5bd3b20ef03 100644
--- a/src/cdk/drag-drop/drag-drop.md
+++ b/src/cdk/drag-drop/drag-drop.md
@@ -73,7 +73,7 @@ by the directives:
 | `.cdk-drop-list`    | Corresponds to the `cdkDropList` container.                              |
 | `.cdk-drag`         | Corresponds to a `cdkDrag` instance.                                     |
 | `.cdk-drag-disabled`| Class that is added to a disabled `cdkDrag`.                             |
-| `.cdk-drag-handle`  | Class that is added to the host element of the cdkDragHandle directive.  | 
+| `.cdk-drag-handle`  | Class that is added to the host element of the cdkDragHandle directive.  |
 | `.cdk-drag-preview` | This is the element that will be rendered next to the user's cursor as they're dragging an item in a sortable list. By default the element looks exactly like the element that is being dragged. |
 | `.cdk-drag-placeholder` | This is element that will be shown instead of the real element as it's being dragged inside a `cdkDropList`. By default this will look exactly like the element that is being sorted. |
 | `.cdk-drop-list-dragging` | A class that is added to `cdkDropList` while the user is dragging an item.  |
@@ -199,3 +199,11 @@ will wait for the user to hold down their pointer for the specified number of mi
 moving the element.
 
 <!-- example(cdk-drag-drop-delay) -->
+
+### Changing the standalone drag position
+By default, standalone `cdkDrag` elements move from their normal DOM position only when manually
+moved by a user. The element's position can be explicitly set, however, via the
+`cdkDragFreeDragPosition` input. Applications commonly use this, for example, to restore a
+draggable's position after a user has navigated away and then returned.
+
+<!-- example(cdk-drag-drop-free-drag-position) -->
diff --git a/src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.css b/src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.css
new file mode 100644
index 00000000000..1e725e0ee13
--- /dev/null
+++ b/src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.css
@@ -0,0 +1,25 @@
+.example-box {
+  width: 200px;
+  height: 200px;
+  border: solid 1px #ccc;
+  color: rgba(0, 0, 0, 0.87);
+  cursor: move;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  text-align: center;
+  background: #fff;
+  border-radius: 4px;
+  position: relative;
+  z-index: 1;
+  transition: box-shadow 200ms cubic-bezier(0, 0, 0.2, 1);
+  box-shadow: 0 3px 1px -2px rgba(0, 0, 0, 0.2),
+              0 2px 2px 0 rgba(0, 0, 0, 0.14),
+              0 1px 5px 0 rgba(0, 0, 0, 0.12);
+}
+
+.example-box:active {
+  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);
+}
diff --git a/src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.html b/src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.html
new file mode 100644
index 00000000000..c51e3e5ce7a
--- /dev/null
+++ b/src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.html
@@ -0,0 +1,7 @@
+<p>
+  <button (click)="changePosition()">Change element position</button>
+</p>
+
+<div class="example-box" cdkDrag [cdkDragFreeDragPosition]="dragPosition">
+  Drag me around
+</div>
diff --git a/src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.ts b/src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.ts
new file mode 100644
index 00000000000..5303ff17601
--- /dev/null
+++ b/src/material-examples/cdk-drag-drop-free-drag-position/cdk-drag-drop-free-drag-position-example.ts
@@ -0,0 +1,17 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Programmatically setting the free drag position
+ */
+@Component({
+  selector: 'cdk-drag-drop-free-drag-position-example',
+  templateUrl: 'cdk-drag-drop-free-drag-position-example.html',
+  styleUrls: ['cdk-drag-drop-free-drag-position-example.css'],
+})
+export class CdkDragDropFreeDragPositionExample {
+  dragPosition = {x: 0, y: 0};
+
+  changePosition() {
+    this.dragPosition = {x: this.dragPosition.x + 50, y: this.dragPosition.y + 50};
+  }
+}