From e7570a1bdb946724846953283582bd1c86892275 Mon Sep 17 00:00:00 2001
From: crisbeto <crisbeto@abv.bg>
Date: Sun, 9 Dec 2018 13:12:30 +0100
Subject: [PATCH] docs(drag-drop): add docs and live example for boundary
 functionality

Adds a live example and some docs for the new `cdkDragBoundary` input.
---
 src/cdk/drag-drop/drag-drop.md                | 10 ++++++
 .../cdk-drag-drop-boundary-example.css        | 35 +++++++++++++++++++
 .../cdk-drag-drop-boundary-example.html       |  6 ++++
 .../cdk-drag-drop-boundary-example.ts         | 11 ++++++
 4 files changed, 62 insertions(+)
 create mode 100644 src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.css
 create mode 100644 src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.html
 create mode 100644 src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.ts

diff --git a/src/cdk/drag-drop/drag-drop.md b/src/cdk/drag-drop/drag-drop.md
index f94cd978580c..76d8550bc226 100644
--- a/src/cdk/drag-drop/drag-drop.md
+++ b/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`
diff --git a/src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.css b/src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.css
new file mode 100644
index 000000000000..aa7b8cb7a090
--- /dev/null
+++ b/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;
+}
diff --git a/src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.html b/src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.html
new file mode 100644
index 000000000000..97f71478cd64
--- /dev/null
+++ b/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>
+
diff --git a/src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.ts b/src/material-examples/cdk-drag-drop-boundary/cdk-drag-drop-boundary-example.ts
new file mode 100644
index 000000000000..8959b7237d6d
--- /dev/null
+++ b/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 {}