docs(drag-drop): add docs and live example for boundary functionality (#14438)

Adds a live example and some docs for the new `cdkDragBoundary` input.

Author: crisbeto

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

@@ -134,6 +134,16 @@ changed by setting the `orientation` property to `"horizontal".
 
 <!-- example(cdk-drag-drop-horizontal-sorting) -->
 
+### Restricting movement within an element
+
+If you want to stop the user from being able to drag a `cdkDrag` element outside of another element,
+you can pass a CSS selector to the `cdkDragBoundary` attribute. The attribute works by accepting a
+selector and looking up the DOM until it finds an element that matches it. If a match is found,
+it'll be used as the boundary outside of which the element can't be dragged. `cdkDragBoundary` can
+also be used when `cdkDrag` is placed inside a `cdkDropList`.
+
+<!-- example(cdk-drag-drop-boundary) -->
+
 ### Restricting movement along an axis
 By default, `cdkDrag` allows free movement in all directions. To restrict dragging to a
 specific axis, you can set `cdkDragLockAxis` on `cdkDrag` or `lockAxis` on `cdkDropList`

src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.css

@@ -0,0 +1,35 @@
+.example-box {
+  width: 200px;
+  height: 200px;
+  border: solid 1px #ccc;
+  color: rgba(0, 0, 0, 0.87);
+  cursor: move;
+  display: inline-flex;
+  justify-content: center;
+  align-items: center;
+  text-align: center;
+  background: #fff;
+  border-radius: 4px;
+  margin-right: 25px;
+  position: relative;
+  z-index: 1;
+  box-sizing: border-box;
+  padding: 10px;
+  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);
+}
+
+.example-boundary {
+  width: 400px;
+  height: 400px;
+  max-width: 100%;
+  border: dotted #ccc 2px;
+}

src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.html

@@ -0,0 +1,6 @@
+<div class="example-boundary">
+  <div class="example-box" cdkDragBoundary=".example-boundary" cdkDrag>
+    I can only be dragged within the dotted container
+  </div>
+</div>
+

src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.ts

@@ -0,0 +1,11 @@
+import {Component} from '@angular/core';
+
+/**
+ * @title Drag&Drop boundary
+ */
+@Component({
+  selector: 'cdk-drag-drop-boundary-example',
+  templateUrl: 'cdk-drag-drop-boundary-example.html',
+  styleUrls: ['cdk-drag-drop-boundary-example.css'],
+})
+export class CdkDragDropBoundaryExample {}