Merge pull request #104 from waynevanson/bugfix.multidrag1

Bugfix.multidrag1

Closes basically all the issues available.

Author: Wayne Van Son

README.md

@@ -8,11 +8,14 @@ Consider trying it out if you had any troubles earlier.
 
 ## Things still to do.
 
-We've released version 2.0,
+We've released version 2.0 but there are still some things to do. We needed public feedback and a major release was the easiest way to get it.
 
 - [x] Create examples from [SortableJS Examples](https://sortablejs.github.io/Sortable/)
-- [ ] Create all tests for examples (for 'ron)
-  - Currently weve got a few.
+- [ ] Examples with code underneath.
+- [ ] List Props in readme.
+- [ ] Allow React to manage class names. Halfway there.
+- [x] Write docs for plugins
+- [ ] Create all tests for examples (for 'ron). Started
 - [ ] Test the following UI component libraries:
   - [x] Styled Components
   - [ ] AntD
@@ -22,6 +25,40 @@ We've released version 2.0,
   - [ ] React Toolbox
   - [ ] Your suggestion? :)
 
+
+## Table of Contents
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Features](#features)
+  - [SortableJS](#sortablejs)
+  - [Component Specific](#component-specific)
+- [Installation](#installation)
+- [Learn](#learn)
+- [Usage/Examples](#usageexamples)
+  - [Function Component](#function-component)
+  - [Class Component](#class-component)
+- [Plugins](#plugins)
+- [Sortable API](#sortable-api)
+- [React API](#react-api)
+  - [id, className, style](#id-classname-style)
+  - [list](#list)
+  - [setList](#setlist)
+  - [clone](#clone)
+  - [tag](#tag)
+    - [HTML Element](#html-element)
+    - [Custom Component](#custom-component)
+- [How does it work?](#how-does-it-work)
+- [Caveats / Gotchas](#caveats--gotchas)
+  - [`key !== index`](#key--index)
+  - [Nesting](#nesting)
+    - [Problem](#problem)
+    - [What does work?](#what-does-work)
+    - [Solutions](#solutions)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Features
 
 ### SortableJS
@@ -43,16 +80,23 @@ If you find any features lacking, create an issue and/or pull request.
 ## Installation
 
 ```shell
-npm install --save react-sortablejs-typescript
+npm install --save react-sortablejs
 # OR
-yarn add react-sortablejs-typescript
+yarn add react-sortablejs
 ```
 
-## What you should endeavour to know.
+Please note that `sortablejs` is not required, as it's bundled in this component.
+
+## Learn
+
+Here is the TLDR of what sortable is:
 
-- Explore the [Sortable Options API](https://github.com/SortableJS/Sortable#options)
-- Array.map
-- React.forwardRef
+```md
+- Shopping List: # list of items / sortable. This represents `react-sortablejs`
+  - eggs # list item. These are all the items in the list and is what you move around.
+  - bread # list item
+  - milk # list item
+```
 
 ## Usage/Examples
 
@@ -112,34 +156,37 @@ export class BasicClass extends Component<{}, BasicClassState> {
 }
 ```
 
-### ReactSortable renders a `div` as the parent by default.
+## Plugins
 
-ReactSortable is a `div` element by default. This can be changed to be any HTML element (for example `ul`, `ol`)
-or can be a React component.
+Sortable has some pretty cool pplugins such as MultiDrag and Swap.
 
-This value, be the component or the HTML element should be passed down under `props.tag`.
+By Default:
 
-Let's explore both here.
+- AutoScroll is premounted and enabled.
+- OnSpill is premounted and NOT enabled.
+- MultiDrag and Swap and NOT premounted and NOT enabled
 
-#### HTML Element
-
-Here we will use a `ul`. You can use any HTML.
-Just add the string and ReactSortable will use a `li` instead of a `div`.
+You must mount mount the plugin with sortable **ONCE ONLY**.
 
 ```tsx
-import React, { FC, useState, forwardRef } from "react";
-import { ReactSortable } from "react-sortablejs-typescript";
+import React from "react";
+import { ReactSortable, Sortable, MultiDrag, Swap } from "react-sortablejs";
 
-interface ItemType {
-  id: string;
-  name: string;
-}
+// mount whatever plugins you'd like to. These are the only current options.
+Sortable.mount(new MultiDrag(), new Swap());
 
-export const BasicFunction: FC = props => {
-  const [state, setState] = useState<ItemType[]>([{ id: "1", name: "shrek" }]);
+const App = () => {
+  const [state, setState] = useState([
+    { id: 1, name: "shrek" },
+    { id: 2, name: "fiona" }
+  ]);
 
   return (
-    <ReactSortable tag="ul" list={state} setList={setState}>
+    <ReactSortable
+      multiDrag // enables mutidrag
+      // OR
+      swap // enables swap
+    >
       {state.map(item => (
         <div key={item.id}>{item.name}</div>
       ))}
@@ -148,44 +195,41 @@ export const BasicFunction: FC = props => {
 };
 ```
 
-#### Custom Component
-
-When using a custom component in the `tag` prop, the only component it allows is a `forwardRef` component.
-
-#### Solution
+## Sortable API
 
-If it doesn't have one, you can add one using `React.forwardRef()`.
-This fantastic API allows the ref to be visible when creating components.
-
-Use this when third party UI libraries.
+For a comprehensive list of options, please visit https://github.com/SortableJS/Sortable#options.
 
-**NOTE:** You may experience inconsistencies with this until we launch the proper version.
-
-> todo: Some third party UI components may have nested elements to create the look they're after.
-> This could be an issue and not sure how to fix.
+Those options are applied as follows.
 
 ```tsx
-import React, { FC, useState, forwardRef } from "react";
-import { ReactSortable } from "react-sortablejs-typescript";
+Sortable.create(element, {
+  group: " groupName",
+  animation: 200,
+  delayOnTouchStart: true,
+  delay: 2
+});
 
-interface ItemType {
-  id: string;
-  name: string;
-}
+// --------------------------
+// Will now be..
+// --------------------------
 
-// This is just like a normal component, but the
-const CustomComponent = forwardRef<HTMLDivElement, any>((props, ref) => {
-  return <div ref={ref}>{props.children}</div>;
-});
+import React from "react";
+import { ReactSortable } from "react-sortablejs";
 
-export const BasicFunction: FC = props => {
-  const [state, setState] = useState<ItemType[]>([
+const App = () => {
+  const [state, setState] = useState([
     { id: 1, name: "shrek" },
     { id: 2, name: "fiona" }
   ]);
 
   return (
-    <ReactSortable tag={CustomComponent} list={state} setList={setState}>
+    <ReactSortable
+      // here they are!
+      group="groupName"
+      animation={200}
+      delayOnTouchStart={true}
+      delay={2}
+    >
       {state.map(item => (
         <div key={item.id}>{item.name}</div>
       ))}
@@ -194,84 +238,98 @@ export const BasicFunction: FC = props => {
 };
 ```
 
-## How does it work?
+## React API
 
-Sortable affects the DOM, adding, and removing nodes/css when it needs to in order to achieve the smooth transitions we all know an love.
-This component reverses many of it's actions of the DOM so React can handle this when the state changes.
+### id, className, style
 
-## Caveats / Gotchas
+Thes are all defaults DOM attributes. Nothing special here.
 
-### `key !== index`
+### list
 
-DO NOT use the index as a key for your list items. Sorting will not work.
+The same as `state` in `const [ state, setState] = useState([{ id: 1}, {id: 2}])`
 
-In all the examples above, I used an object with an ID. You should do the same!
+`state` must be an array of items, with each item being an object that has the following shape:
 
-I may even enforce this into the design to eliminate errors.
+```ts
+  /** The unique id associated with your item. It's recommended this is the same as the key prop for your list item. */
+  id: string | number;
+  /** When true, the item is selected using MultiDrag */
+  selected?: boolean;
+  /** When true, the item is deemed "chosen", which basically just a mousedown event. */
+  chosen?: boolean;
+  /** When true, it will not be possible to pick this item up in the list. */
+  filtered?: boolean;
+  [property: string]: any;
+```
 
-### `setState()`
+### setList
 
-#### Problem
+The same as `setState` in `const [ state, setState] = useState([{ id: 1}, {id: 2}])`
 
-`setState` takes one argument only. If we look in the type defs, it does say that it has a second argument, but it is already deprecated. ReactSortable passes three arguments to `setState`.
+### clone
 
-If you pass the `setState` straight from a `useState` hook, it will work as expected. However, there will be a warning in the console:
+If you're using `{group: { name: 'groupName', pull: 'clone'}}`, this means your in 'clone' mode. You should provide a function for this.
 
-> Warning: State updates from the useState() and useReducer() Hooks don't support the second callback argument.
-> To execute a side effect after rendering, declare it in the component body with useEffect().
+Check out the source code of the clone example for more information. I'll write it here soon.
 
-It's just a warning and there's nothing to worry about. Nothing will break if you leave the messages there.
+### tag
+
+ReactSortable is a `div` element by default. This can be changed to be any HTML element (for example `ul`, `ol`)
+or can be a React component.
+
+This value, be the component or the HTML element should be passed down under `props.tag`.
+
+Let's explore both here.
+
+#### HTML Element
+
+Here we will use a `ul`. You can use any HTML.
+Just add the string and ReactSortable will use a `li` instead of a `div`.
 
 ```tsx
-import React, { FC, useState } from "react";
+import React, { FC, useState, forwardRef } from "react";
 import { ReactSortable } from "react-sortablejs-typescript";
 
-interface ItemType {
-  id: string;
-  name: string;
-}
-
 export const BasicFunction: FC = props => {
-  const [state, setState] = useState<ItemType[]>([{ id: "1", name: "shrek" }]);
+  const [state, setState] = useState([{ id: "1", name: "shrek" }]);
 
   return (
-    <ReactSortable
-      list={state}
-      // will cause warnings in dev mode only.
-      setList={setState}
-    >
+    <ReactSortable tag="ul" list={state} setList={setState}>
       {state.map(item => (
-        <div key={item.id}>{item.name}</div>
+        <li key={item.id}>{item.name}</li>
       ))}
     </ReactSortable>
   );
 };
 ```
 
-This is just a warning, but can be annoying when developing.
+#### Custom Component
+
+When using a custom component in the `tag` prop, the only component it allows is a `forwardRef` component.
+Currently we only support components who use the `React.forwardRef` API.
 
-Instead of passing `setState` in directly, be explicit in your callback:
+If it doesn't have one, you can add one using `React.forwardRef()`.
+
+> todo: Some third party UI components may have nested elements to create the look they're after.
+> This could be an issue and not sure how to fix.
 
 ```tsx
-import React, { FC, useState } from "react";
+import React, { FC, useState, forwardRef } from "react";
 import { ReactSortable } from "react-sortablejs-typescript";
 
-interface ItemType {
-  id: string;
-  name: string;
-}
+// This is just like a normal component, but now has a ref.
+const CustomComponent = forwardRef<HTMLDivElement, any>((props, ref) => {
+  return <div ref={ref}>{props.children}</div>;
+});
 
 export const BasicFunction: FC = props => {
-  const [state, setState] = useState<ItemType[]>([{ id: "1", name: "shrek" }]);
+  const [state, setState] = useState([
+    { id: 1, name: "shrek" },
+    { id: 2, name: "fiona" }
+  ]);
 
   return (
-    // `sortable` and `store` arguments are here just to show what arguments have been passed.
-    // They are not required to be used and you shouldn't really need them.
-    <ReactSortable
-      list={state}
-      // will not cause warnings in dev mode only.
-      setList={(newState, sortable, store) => setState(newState)}
-    >
+    <ReactSortable tag={CustomComponent} list={state} setList={setState}>
       {state.map(item => (
         <div key={item.id}>{item.name}</div>
       ))}
@@ -280,6 +338,21 @@ export const BasicFunction: FC = props => {
 };
 ```
 
+## How does it work?
+
+Sortable affects the DOM, adding, and removing nodes/css when it needs to in order to achieve the smooth transitions we all know an love.
+This component reverses many of it's actions of the DOM so React can handle this when the state changes.
+
+## Caveats / Gotchas
+
+### `key !== index`
+
+DO NOT use the index as a key for your list items. Sorting will not work.
+
+In all the examples above, I used an object with an ID. You should do the same!
+
+I may even enforce this into the design to eliminate errors.
+
 ### Nesting
 
 #### Problem

dist/index.d.ts

@@ -1,6 +1,4 @@
 export { ReactSortable } from "./react-sortable";
 export * from "./types";
-export { MultiDrag, Swap, DOMRect, Direction, GroupOptions, MoveEvent, Options, PullResult, PutResult, SortableEvent, SortableOptions, Utils } from "sortablejs";
-import SortableGlobal from "sortablejs";
-export declare const Sortable: typeof SortableGlobal;
+export { default as Sortable, MultiDrag, Swap, DOMRect, Direction, GroupOptions, MoveEvent, Options, PullResult, PutResult, SortableEvent, SortableOptions, Utils } from "sortablejs";
 //# sourceMappingURL=index.d.ts.map