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

@@ -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) -->

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);
+}

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>

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};
+  }
+}