docs(drag-drop): add docs and live example for enter predicate (#13917)

Since we don't have much info on the `cdkDropListEnterPredicate`, these changes add a section about it in the docs, as well as a live example.

Author: crisbeto

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

@@ -133,3 +133,12 @@ the element that is moved as the user is dragging. This is useful for cases like
 draggable.
 
 <!-- example(cdk-drag-drop-root-element) -->
+
+### Controlling which items can be moved into a container
+By default, all `cdkDrag` items from one container can be moved into another connected container.
+If you want more fine-grained control over which items can be dropped, you can use the
+`cdkDropListEnterPredicate` which will be called whenever an item is about to enter a
+new container. Depending on whether the predicate returns `true` or `false`, the item may or may not
+be allowed into the new container.
+
+<!-- example(cdk-drag-drop-enter-predicate) -->

src/material-examples/cdk-drag-drop-enter-predicate/cdk-drag-drop-enter-predicate-example.css

@@ -0,0 +1,54 @@
+.example-container {
+  width: 400px;
+  max-width: 100%;
+  margin: 0 25px 25px 0;
+  display: inline-block;
+  vertical-align: top;
+}
+
+.example-list {
+  border: solid 1px #ccc;
+  min-height: 60px;
+  background: white;
+  border-radius: 4px;
+  overflow: hidden;
+  display: block;
+}
+
+.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-placeholder {
+  opacity: 0;
+}
+
+.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);
+}

src/material-examples/cdk-drag-drop-enter-predicate/cdk-drag-drop-enter-predicate-example.html

@@ -0,0 +1,38 @@
+<div class="example-container">
+  <h2>Available numbers</h2>
+
+  <div
+    id="all"
+    cdkDropList
+    [cdkDropListData]="all"
+    cdkDropListConnectedTo="even"
+    class="example-list"
+    (cdkDropListDropped)="drop($event)"
+    [cdkDropListEnterPredicate]="noReturnPredicate">
+    <div
+      class="example-box"
+      *ngFor="let number of all"
+      [cdkDragData]="number"
+      cdkDrag>{{number}}</div>
+  </div>
+</div>
+
+<div class="example-container">
+  <h2>Even numbers</h2>
+
+  <div
+    id="even"
+    cdkDropList
+    [cdkDropListData]="even"
+    cdkDropListConnectedTo="all"
+    class="example-list"
+    (cdkDropListDropped)="drop($event)"
+    [cdkDropListEnterPredicate]="evenPredicate">
+    <div
+      class="example-box"
+      *ngFor="let number of even"
+      cdkDrag
+      [cdkDragData]="number">{{number}}</div>
+  </div>
+</div>
+

src/material-examples/cdk-drag-drop-enter-predicate/cdk-drag-drop-enter-predicate-example.ts

@@ -0,0 +1,36 @@
+import {Component} from '@angular/core';
+import {CdkDragDrop, moveItemInArray, transferArrayItem, CdkDrag} from '@angular/cdk/drag-drop';
+
+/**
+ * @title Drag&Drop enter predicate
+ */
+@Component({
+  selector: 'cdk-drag-drop-enter-predicate-example',
+  templateUrl: 'cdk-drag-drop-enter-predicate-example.html',
+  styleUrls: ['cdk-drag-drop-enter-predicate-example.css'],
+})
+export class CdkDragDropEnterPredicateExample {
+  all = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+  even = [10];
+
+  drop(event: CdkDragDrop<string[]>) {
+    if (event.previousContainer === event.container) {
+      moveItemInArray(event.container.data, event.previousIndex, event.currentIndex);
+    } else {
+      transferArrayItem(event.previousContainer.data,
+                        event.container.data,
+                        event.previousIndex,
+                        event.currentIndex);
+    }
+  }
+
+  /** Predicate function that only allows even numbers to be dropped into a list. */
+  evenPredicate(item: CdkDrag<number>) {
+    return item.data % 2 === 0;
+  }
+
+  /** Predicate function that doesn't allow items to be dropped into a list. */
+  noReturnPredicate() {
+    return false;
+  }
+}