docs(drag-drop): add docs and live example for disabled sorting (#15426)

Documents the functionality from #15064 and adds a live example.

Author: crisbeto

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

@@ -179,3 +179,12 @@ using the `cdkDropListDisabled` input on a `cdkDropList` or a particular handle
 `cdkDragHandleDisabled` on `cdkDragHandle`.
 
 <!-- example(cdk-drag-drop-disabled) -->
+
+### Disabled sorting
+There are cases where draggable items can be dragged out of one list into another, however
+the user shouldn't be able to sort them within the source list. For these cases you can set the
+`cdkDropListSortingDisabled` input which will prevent the items in a `cdkDropList` from sorting,
+in addition to preserving the dragged item's initial position in the source list, if the user
+decides to return the item.
+
+<!-- example(cdk-drag-drop-disabled-sorting) -->

src/material-examples/cdk-drag-drop-disabled-sorting/cdk-drag-drop-disabled-sorting-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-disabled-sorting/cdk-drag-drop-disabled-sorting-example.html

@@ -0,0 +1,26 @@
+<div cdkDropListGroup>
+  <div class="example-container">
+    <h2>Available items</h2>
+
+    <div
+      cdkDropList
+      [cdkDropListData]="items"
+      class="example-list"
+      cdkDropListSortingDisabled
+      (cdkDropListDropped)="drop($event)">
+      <div class="example-box" *ngFor="let item of items" cdkDrag>{{item}}</div>
+    </div>
+  </div>
+
+  <div class="example-container">
+    <h2>Shopping basket</h2>
+
+    <div
+      cdkDropList
+      [cdkDropListData]="basket"
+      class="example-list"
+      (cdkDropListDropped)="drop($event)">
+      <div class="example-box" *ngFor="let item of basket" cdkDrag>{{item}}</div>
+    </div>
+  </div>
+</div>

src/material-examples/cdk-drag-drop-disabled-sorting/cdk-drag-drop-disabled-sorting-example.ts

@@ -0,0 +1,37 @@
+import {Component} from '@angular/core';
+import {CdkDragDrop, moveItemInArray, transferArrayItem} from '@angular/cdk/drag-drop';
+
+/**
+ * @title Drag&Drop disabled sorting
+ */
+@Component({
+  selector: 'cdk-drag-drop-disabled-sorting-example',
+  templateUrl: 'cdk-drag-drop-disabled-sorting-example.html',
+  styleUrls: ['cdk-drag-drop-disabled-sorting-example.css'],
+})
+export class CdkDragDropDisabledSortingExample {
+  items = [
+    'Carrots',
+    'Tomatoes',
+    'Onions',
+    'Apples',
+    'Avocados'
+  ];
+
+  basket = [
+    'Oranges',
+    'Bananas',
+    'Cucumbers'
+  ];
+
+  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);
+    }
+  }
+}