Updated ReadMe and package.json

README.md

@@ -1,16 +1,18 @@
 # react-file-uploader
 
-react-file-uploader is a set of components written in React.js which helps you to upload file easily. You can check out the [LIVE DEMO](http://23.254.164.88:3000) here.
+react-file-uploader is a set of highly customizable React components that helps you to build a file uploader in your application easily. 
 
-### Installation
+react-file-uploader is not production ready because it is not fully tested on all browsers, and the unit test coverage is just not good enough. However, it has been used in my cms project since v0.3.0.
+
+## Installation
 
 To install:
 
-```
+```sh
 npm install --save react-file-uploader
 ```
 
-### Documentation
+# Documentation
 
 this module currently contains 4 major entities, which are
 
@@ -19,99 +21,124 @@ this module currently contains 4 major entities, which are
 3. UploadHandler
 4. File Status
 
-### Receiver
+# Receiver
 
-Receiver helps you to manage file upload triggered by **_Drag and Drop_**. Once you mounted the **Receiver** component, the **_Drag and Drop_** function will be enabled.
+`Receiver` helps you to manage the **Drag and Drop** functionality. Once you mounted the `Receiver` component, your application will start listen to `dragenter`, `dragover`, `dragleave` and `drop` events.
 
 ```
 import { Receiver } from 'react-file-uploader';
 
 <Receiver
-	customClass={CLASS_STRING_OR_ARRAY}
-	style={STYLE_OBJECT}
-	isOpen={BOOLEAN}
-	onDragEnter={FUNCTION}
-	onDragOver={FUNCTION}
-	onDragLeave={FUNCTION}
-	onFileDrop={FUNCTION} >
-	<div>
-		visual layer of the receiver (drag & drop panel)
-	</div>
+  customClass={STRING_OR_ARRAY}
+  style={OBJECT}
+  isOpen={BOOLEAN}
+  onDragEnter={FUNCTION}
+  onDragOver={FUNCTION}
+  onDragLeave={FUNCTION}
+  onFileDrop={FUNCTION}
+>
+    <div>
+      visual layer of the receiver (drag & drop panel)
+    </div>
 </Receiver>
 ```
 
-#### Props
+## Props
 
 * customClass - `string | array`: the class name(s) for the `div` wrapper
 * style - `object`: the style for the `div` wrapper 
-* isOpen - `boolean` `required`: it enables you to control in the parent component whether the Receiver is opened.
-* onDragEnter - `function` `required`: this will be fired with the window event of `onDragEnter` once only when `isOpen` is `false`.
+* isOpen - `boolean` `required`: to control in the parent component whether the Receiver is visble.
+* onDragEnter - `function` `required`: when `isOpen` is `false`, this will be fired with the window event of `dragenter` once .
+
+You may make use of the drag & drop event callbacks.
 
 ```
-// @param e Object DragEnter Event
+// @param e Object DragEvent
 function onDragEnter(e) {
-	// your codes here
+	this.setState({ isReceiverOpen: true });
 }
 ```
 
-* onDragOver - `function`: this will be fired with the window event of `onDragOver`.
+* onDragOver - `function`: this will be fired with the window event of `dragover`.
 
 ```
-// @param e Object DragOver Event
+// @param e Object DragEvent
 function onDragOver(e) {
 	// your codes here
 }
 ```
 
-* onDragLeave - `function` `required`: this will be fired with the window event of `onDragLeave` once only when the drag event entirely left the client (i.e. `dragLevel` == 0).
+* onDragLeave - `function` `required`: when the drag event entirely left the client (i.e. `dragLevel === 0`), this will be fired with the window event of `dragleave` once.
 
 ```
-// @param e Object DragLeave Event
+// @param e Object DragEvent
 function onDragLeave(e) {
-	// your codes here
+	this.setState({ isReceiverOpen: false });
 }
 ```
 
 * onFileDrop - `function` `required`: this will be fired with the window event of `drop`. You may execute any validation / checking process here i.e. *size*, *file type*, etc.
 
 ```
-// @param target Object the target node of the drop event
+// @param e Object DragEvent
 // @param files Array the files dropped on the target node
-function onFileDrop(target, files) {
-	// your codes here
+function onFileDrop(e, files) {
+	// check if the files are drop on the targeted DOM
+	const node = ReactDOM.findDOMNode(this.refs.uploadPanel);
+	if (e.target !== node) {
+		return;
+	}
+	
+	files.forEach(file => {
+		// check file size
+		if (file.size > 1000 * 1000) {
+			file.error = 'file size exceeded 1MB';
+		}
+	})
+	
+	// put files into state/stores by setState/action
+	this.setState({
+		files: this.state.files.concat(files),
+	});
+	
+	// close the Receiver after file dropped
+	this.setState({ isReceiverOpen: false });
 }
 ```
 
-### UploadManager
+# UploadManager
 
-Upload Manager serves as a high order component which helps you to manage the upload related parameters and functions. It prepares the upload logic with [`superagent`](https://github.com/visionmedia/superagent) for the `UploadHandler` as its children, and helps you to update the lifecycle status of the uploading files.
+Upload Manager serves as a high order component which helps you to manage the upload related parameters and functions. It prepares the upload function with [`superagent`](https://github.com/visionmedia/superagent) the children elements, and helps you to update the lifecycle status of the uploading files.
 
 **_IMPORTANT: this high order component serves only for_ ** `UploadHandler`
 
 ```
 import { UploadManager } from 'react-file-uploader';
 
 <UploadManager
-	customClass={CLASS_STRING_OR_ARRAY}
-	style={STYLE_OBJECT}
-	files={FILES_OJBECT_ARRAY}
-	uploadUrl={UPLOAD_API_END_POINT_STRING}
-	onUpload={FUNCTION}
-	onUploadProgress={FUNCTION}
-	onUploadEnd={FUNCTION} >
+  customClass={STRING_OR_ARRAY}
+  style={OBJECT}
+  uploadUrl={STRING}
+  uploadHeader={OBJECT}
+  onUpload={FUNCTION}
+  onUploadProgress={FUNCTION}
+  onUploadEnd={FUNCTION}
+>
 	
 	// UploadHandler as children
-	<UploadHandle file={FILE_OBJECT} autoStart={BOOLEAN} />
-	
+	files.map(file => (
+		<UploadHandle key={file._id} file={FILE_INSTANCE} autoStart={BOOLEAN} />
+	))
 </UploadManager>
 ```
 
-#### Props
+## Props
 
-* customClass - `string | array`: the class name(s) for the `div` wrapper
-* style - `object`: the style for the `div` wrapper 
-* files - `array`: the array of files object that are **_uploaded / going to be uploaded_** to be shown in the file list.
+* component - `string`: the DOM tag name of the wrapper
+* customClass - `string | array`: the class name(s) for the wrapper
+* style - `object`: the style for the wrapper
 * uploadUrl - `string` `required`: the url of the upload end point from your server.
+* uploadHeader - `object`: the header object to be set as request header.
 * onUploadStart - `function`: this will be fired when the `POST` request is just sent.
 
 ```
@@ -121,7 +148,7 @@ function onUploadStart(file) {
 }
 ```
 
-* onUploadProgress - `function`: this will be fired when the `POST` request returns progress.
+* onUploadProgress - `function`: this will be fired when the `POST` request returns progress. A debounced function is **STRONGLY** recommaned to prevent from performance issue.
 
 ```
 // @param file Object the file object returned with UPLOADING status and n% progress.
@@ -133,14 +160,33 @@ function onUploadProgress(file) {
 * onUploadEnd - `function` `required`: this will be fired upon the end of `POST` request.
 
 ```
-// @param file Object the file object returned with either UPLOADED status and 100% progress
-// or FAILED status, 0% progress and error reason.
+// @param file Object the file object returned with either UPLOADED or FAILED status and 100% progress. When it is wilh FAILED status, error property should be also assigned to the file object.
 function onUploadEnd(file) {
 	// your codes here
 }
 ```
 
-### UploadHandler
+* errorHandler - `function`: this function is to process the arguments of `(err, res)` in `superagent.end()`. In this function, you can resolve the error and result according to your upload api response. Default implementation is available as defaultProps.
+
+```
+function errorHandler(err, res) {
+  let error = null;
+  const body = clone(res.body);
+
+  if (err) {
+  	error = err;
+  } else if (body && body.errors) {
+    error = body.errors;
+  }
+  
+  delete body.errors;
+  
+  return { error, result: body };
+}
+```
+
+
+# UploadHandler
 
 Upload Handler helps you to execute the upload lifecycle, which is `start`, `progress` and `end`. It also acts as the presentation layer of a file, showing users the info of the **_uploading / uploaded_** file.
 
@@ -152,13 +198,15 @@ import { UploadHandler } from 'react-file-uploader';
 	style={STYLE_OBJECT}
 	file={FILE_OBJECT}
 	autoStart={BOOLEAN}
-	upload={UPLOAD_FUNCTION} />
+	upload={UPLOAD_FUNCTION}
+/>
 ```
 
-#### Props
+## Props
 
-* `customClass` - `string | array`: the class name(s) for the `div` wrapper
-* `style` - `object`: the style for the `div` wrapper 
+* `component` - `string`: the DOM tag name of the wrapper
+* `customClass` - `string | array`: the class name(s) for the wrapper
+* `style` - `object`: the style for the wrapper 
 * `file` - `object` `required`: the file object that is **_uploaded / going to be uploaded_**.
 * `autoStart` - `boolean`: when `autoStart` is set to `true`, upon the UploadHandler component did mount, it will detect if the file i.e. *as props* is with the `PENDING` status and initialise a `POST` request which is sent to the `uploadUrl` you passed to the `UploadManager`.
 * `upload` - `function`: the function that contains the upload logic, you may pass it directly when you are using `UploadHandler` alone, or it could be prepared by `UploadManager`.
@@ -172,23 +220,23 @@ function upload(url, file) {
 }
 ```
 
-### File Status
+# File Status
 
 `react-file-uploader` defines a set of status constants to represent the file status. The corresponding status will be assign to a file object throughout the uploading life cycle.
 
 ```
 FAILED = -1
-PEDNING = 0
+PENDING = 0
 UPLOADING = 1
 UPLOADED = 2
 ```
 
-### TODOs
+# TODOs
 
-* add test cases
-* ~~add example~~
+* complete test cases
+* add real-world example
 * support optional data, i.e. custom image name and destination
 
-### License
+# License
 
 MIT

package.json

@@ -8,7 +8,7 @@
     "test": "jest",
     "test:report": "jest --coverage",
     "build:lib": "babel src --out-dir lib",
-    "build": "npm run eslint && npm run clean && npm run build:lib",
+    "build": "npm run eslint && npm run test && npm run clean && npm run build:lib",
     "eslint": "eslint ./src/*.js ./src/**/*.js"
   },
   "repository": {
@@ -18,7 +18,10 @@
   "keywords": [
     "react",
     "file",
-    "uploader"
+    "upload",
+    "uploader",
+    "file-upload",
+    "file-uploader"
   ],
   "author": "Marston Ng <[email protected]>",
   "license": "MIT",