Adding a multi drag pattern (#383)

Author: alexreardon

README.md

@@ -53,6 +53,7 @@ We have created upgrade instructions in our release notes to help you upgrade to
 - Movement between lists (▤ ↔ ▤)
 - Mouse 🐭, keyboard 🎹 and touch 👉📱 (mobile, tablet and so on) support
 - Auto scrolling - automatically scroll containers and the window as required during a drag (even with keyboard 🔥)
+- [Multi drag support](/docs/patterns/multi-drag.md)
 - Incredible screen reader support - we provide an amazing experience for english screen readers out of the box 📦. We also provide complete customisation control and internationalisation support for those who need it 💖
 - Conditional [dragging](https://github.com/atlassian/react-beautiful-dnd#props-1) and [dropping](https://github.com/atlassian/react-beautiful-dnd#conditionally-dropping)
 - Multiple independent lists on the one page
@@ -308,6 +309,12 @@ class App extends React.Component {
 }
 ```
 
+## Multi drag
+
+We have created a [multi drag pattern](/docs/patterns/multi-drag.md) that you can build on top of `react-beautiful-dnd` in order to support dragging multiple `Draggable` items at once.
+
+![multi drag demo](https://user-images.githubusercontent.com/2182637/37322724-7843a218-26d3-11e8-9ebb-8d5853387bb3.gif)
+
 ## Preset styles
 
 We apply a number of non-visible styles to facilitate the dragging experience. We do this using combination of styling targets and techniques. It is a goal of the library to provide unopinioned styling. However, we do apply some reasonable `cursor` styling on drag handles by default. This is designed to make the library work as simply as possible out of the box. If you want to use your own cursors you are more than welcome to. All you need to do is override our cursor style rules by using a rule with [higher specificity](https://css-tricks.com/specifics-on-css-specificity/).

docs/guides/how-we-use-dom-events.md

@@ -56,9 +56,11 @@ Some user events have a direct impact on a drag: such as a `mousemove` when drag
 
 ### Initial `mousedown`
 
-- `preventDefault()` not called on `mousedown`
+- `preventDefault()` **is called on `mousedown`** 😞
 
-When the user first performs a `mousedown` on a *drag handle* we are not sure if they are intending to click or drag. Because at this stage we are not sure, we do not call `preventDefault()` on the event.
+> This is the only known exception to our rule set. It is unfortunate that it is the first one to appear in this guide!
+
+When the user first performs a `mousedown` on a *drag handle* we are not sure if they are intending to click or drag. Ideally we would not call `preventDefault()` on this event as we are not sure if it is a part of a drag. However, we need to call `preventDefault()` in order to avoid the item obtaining focus as it has a `tabIndex`.
 
 ### We are not sure yet if a drag will start
 

docs/patterns/multi-drag.md

@@ -6,10 +6,7 @@ type Records = {
 
 const records: Records = {};
 
-const flag: string = '__react-beautiful-dnd-debug-hook__';
-
-// temp
-// window[flag] = true;
+const flag: string = '__react-beautiful-dnd-debug-timings-hook__';
 
 const isTimingsEnabled = (): boolean => Boolean(window[flag]);
 

src/debug/timings.js

@@ -170,7 +170,7 @@ export default class DragDropContext extends React.Component<Props> {
         this.styleMarshal.onPhaseChange(current);
       }
 
-      const isDragEnding: boolean = current.phase !== 'DRAGGING' && previousInThisExecution.phase === 'DRAGGING';
+      const isDragEnding: boolean = previousInThisExecution.phase === 'DRAGGING' && current.phase !== 'DRAGGING';
 
       // in the case that a drag is ending we need to instruct the dimension marshal
       // to stop listening to changes. Otherwise it will try to process

src/view/drag-drop-context/drag-drop-context.jsx

@@ -25,7 +25,7 @@ type State = {|
 |}
 
 // https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button
-const primaryButton = 0;
+const primaryButton: number = 0;
 const noop = () => { };
 
 // shared management of mousedown without needing to call preventDefault()
@@ -256,10 +256,16 @@ export default ({
     // Registering that this event has been handled.
     // This is to prevent parent draggables using this event
     // to start also.
-    // Not using preventDefault() as we are not sure
+    // Ideally we would not use preventDefault() as we are not sure
     // if this mouse down is part of a drag interaction
+    // Unfortunately we do to prevent the element obtaining focus (see below).
     mouseDownMarshal.handle();
 
+    // Unfortunately we do need to prevent the drag handle from getting focus on mousedown.
+    // This goes against our policy on not blocking events before a drag has started.
+    // See [How we use dom events](/docs/guides/how-we-use-dom-events.md).
+    event.preventDefault();
+
     const point: Position = {
       x: clientX,
       y: clientY,

src/view/drag-handle/sensor/create-mouse-sensor.js

@@ -0,0 +1,9 @@
+// @flow
+import React from 'react';
+import { storiesOf } from '@storybook/react';
+import TaskApp from './src/multi-drag/task-app';
+
+storiesOf('Multi drag', module)
+  .add('pattern', () => (
+    <TaskApp />
+  ));

stories/9-multi-drag-story.js

@@ -1,5 +1,5 @@
 // @flow
-import type { Task } from './types';
+import type { Task } from '../types';
 
 const tasks: Task[] = [
   {

stories/src/accessible/data.js

@@ -14,7 +14,7 @@ import type {
   DraggableLocation,
   HookProvided,
 } from '../../../src/';
-import type { Task } from './types';
+import type { Task } from '../types';
 
 type State = {|
   tasks: Task[],

stories/src/accessible/task-app.jsx

@@ -3,8 +3,8 @@ import React, { Component } from 'react';
 import styled from 'styled-components';
 import { Droppable } from '../../../src/';
 import Task from './task';
-import type { DroppableProvided, DroppableStateSnapshot } from '../../../src/';
-import type { Task as TaskType } from './types';
+import type { DroppableProvided } from '../../../src/';
+import type { Task as TaskType } from '../types';
 import { colors, grid, borderRadius } from '../constants';
 
 type Props = {|
@@ -14,7 +14,7 @@ type Props = {|
 
 const Container = styled.div`
   width: 300px;
-  background-color: ${colors.grey};
+  background-color: ${colors.grey.dark};
   border-radius: ${borderRadius}px;
 `;