docs: update docs/ markdown files with v5 syntax

Add a support matrix table to the README.

README.md

@@ -2,13 +2,17 @@
 
 Ember FileUpload is an ember addon that makes uploading files easy.
 
-Uploads continue in the background, even after a page transition. In other words they are persistent across routes in your application.
-
-[View the docs here.](https://adopted-ember-addons.github.io/ember-file-upload/docs/)
+Uploads can be managed through queues and continue in the background, even after a page transition. In other words they are persistent across routes in your application.
 
 ## Compatibility
 
-* Ember.js v3.16 or above
+| Support | v4.x | v5.0.0-beta.x |
+| ----- | ----- | ----- |
+| Ember.js  | 3.16 up to 3.28  | 3.25 or above including 4.x |
+| Embroider  | 🤷  | ✅  |
+| ember-auto-import |  | 2.0 or above |
+| Documentation | [Docsite](https://adopted-ember-addons.github.io/ember-file-upload/docs/) | (Docsite WIP) [Doc files](docs/getting-started.md)  |
+
 * Ember CLI v2.13 or above
 * Node.js v12 or above
 * Modern browsers. Internet Explorer 11 might work but is not offically supported.

docs/file-dropzone.md

@@ -0,0 +1,33 @@
+# Adding a Dropzone
+
+`<FileDropzone>` is a component that will allow users to upload files by drag and drop.
+
+For uploading files once they are added to the queue see [Uploading a file](uploading.md).
+
+```hbs
+{{#let (file-queue name="photos") as |queue|}}
+  <FileDropzone @queue={{queue}} as |dropzone|>
+    {{#if dropzone.active}}
+      Drop to upload
+    {{else if queue.files.length}}
+      Uploading {{queue.files.length}} files. ({{queue.progress}}%)
+    {{else}}
+      <h4>Upload Images</h4>
+      <p>
+        {{#if dropzone.supported}}
+          Drag and drop images onto this area to upload them or
+        {{/if}}
+      </p>
+    {{/if}}
+  </FileDropzone>
+{{/let}}
+```
+
+This component yields a some useful properties:
+
+| Property | Description |
+| ----- | ----- |
+| dropzone.supported  | `Boolean` – If the user's browser supports Drag and Drop |
+| dropzone.active  | `Boolean` – If files are being dragged over the `FileDropzone` |
+
+To control which files are added to the queue refer to [File Validation](file-validation.md).

docs/file-validation.md

@@ -0,0 +1,43 @@
+# File Validation
+
+## Accept attribute
+
+If you're only using the `queue.selectFile` modifer you may use the `accept` attribute to suggest which file types may be selected.
+
+Unforunately this is unreliable as it is not handled the same by all browsers.
+
+For more details see the [MDN accept attribute reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept).
+
+## Custom validation
+
+Both `queue.selectFile` and `<FileDropzone>` accept the `filter` argument with which you may implement custom validation of chosen files.
+
+Filter is called *after* files have been chosen and *before* `onFileAdded` is called by the queue. It runs once per selected file.
+
+See the example below where the same validation callback is used for both file-selection methods.
+
+Commonly validated file properties are `type`, `name` and `size`. For more details see the [MDN File reference](https://developer.mozilla.org/en-US/docs/Web/API/File).
+
+```hbs
+{{#let (file-queue name="photos") as |queue|}}
+  <FileDropzone
+    @queue={{queue}}
+    @filter={{this.validateFile}}
+    as |dropzone|
+  >
+    <input type="file" {{queue.selectFile filter=this.validateFile}}>
+  </FileDropzone>
+{{/let}}
+```
+
+```js
+const allowedTypes = ['image/gif', 'image/jpeg', 'image/png', 'image/webp'];
+
+export default class ExampleComponent extends Component {
+  validateFile(file) {
+    return allowedTypes.includes(file.type);
+  }
+}
+```
+
+To ensure your file validation is working correctly refer to [Testing](testing.md).

docs/getting-started.md

@@ -0,0 +1,38 @@
+# Getting started
+
+Ember FileUpload is an ember addon that makes uploading files easy.
+
+Uploads can be managed through queues and continue in the background, even after a page transition. In other words they are persistent across routes in your application.
+
+## Installation
+
+```sh
+ember install ember-file-upload
+```
+
+## Introducing queues
+
+Queues contain the state of file uploads as a user navigates around your application. They are the core of this addon.
+
+To access a queue in your templates compose the [`let` helper](https://guides.emberjs.com/release/components/helper-functions/#toc_the-let-helper) with the `file-queue` helper like this:
+
+```hbs
+{{#let (file-queue name='photos') as |queue|}}
+{{/let}}
+```
+
+The `name` property is optional but recommended as you may manage multiple queues in the future.
+
+> ℹ️ You can also access queues in your app JavaScript by injecting the `fileQueue` service.
+>
+> ```js
+> export default class ExampleComponent extends Component {
+>   @service fileQueue;
+>
+>   get queue() {
+>     return this.fileQueue.findOrCreate('photos');
+>   }
+> }
+> ```
+
+Next, let's learn how to [upload a file](uploading.md).

docs/testing.md

@@ -1,27 +1,52 @@
-# Acceptance Tests
+# Testing
 
-`ember-file-upload` provides a `selectFiles` helper for acceptance and integration tests:
+## `queue.selectFiles` modifer
 
-```javascript
+Use the `selectFiles` helper to simulate a user choosing one or more files from a file input.
+
+```js
+import { module } from 'qunit';
+import { setupApplicationTest } from 'ember-qunit';
 import { selectFiles } from 'ember-file-upload/test-support';
+
+module('Acceptance | uploading notes', function(hooks) {
+  setupApplicationTest(hooks);
+
+  test('uploading a note', async function (assert) {
+    let file = new File(['I can feel the money leaving my body'], 'douglas_coupland.txt', { type: 'text/plain' });
+    await selectFiles('input[type=file]', file);
+
+    assert.dom('.note').hasText('I can feel the money leaving my body');
+  });
+});
+```
+
+## `<FileDropzone>` component
+
+Similarly the `dragAndDrop` helper is available to simulate a user dropping one or more files onto a `<FileDropzone>`.
+
+```js
 import { module } from 'qunit';
 import { setupApplicationTest } from 'ember-qunit';
+import { dragAndDrop } from 'ember-file-upload/test-support';
 
-module('/notes', function(hooks) {
+module('Acceptance | drag and drop upload notes', function(hooks) {
   setupApplicationTest(hooks);
 
-  test('showing a note', async function (assert) {
+  test('drag and drop uploading a note', async function (assert) {
     let file = new File(['I can feel the money leaving my body'], 'douglas_coupland.txt', { type: 'text/plain' });
-    await selectFiles('#upload-note', file);
+    await dragAndDrop('input[type=file]', file);
 
     assert.dom('.note').hasText('I can feel the money leaving my body');
   });
 });
 ```
 
-It also integrates with `ember-cli-mirage` through an upload handler. This helper provides a way to realistically simulate file uploads, including progress events and failure states.
+## Mirage `upload` handler
+
+A mirage handler is provided which can realistically simulate file uploads, including progress events and failure states.
 
-```javascript
+```js
 // mirage/config.js
 
 import { upload } from 'ember-file-upload/mirage';
@@ -35,7 +60,7 @@ export default function () {
 }
 ```
 
-```javascript
+```js
 import { module, test } from 'qunit';
 import { setupApplicationTest } from 'ember-qunit';
 import { setupMirage } from 'ember-cli-mirage/test-support';
@@ -64,7 +89,7 @@ module('/photos', function(hooks) {
 
 The upload handler only works with valid images. You could create dummy images for tests using a `canvas` element:
 
-```javascript
+```js
 function getImageBlob() {
   return new Promise((resolve) => {
     let canvas = document.createElement('canvas');

docs/uploading.md

@@ -0,0 +1,43 @@
+# Uploading a file
+
+Bind a [file input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file) to your queue with the `queue.selectFile` modifier. Files selected from the input will be added to your queue. For example:
+
+```hbs
+{{#let (file-queue name='photos' onFileAdded=this.uploadPhoto) as |queue|}}
+  <label>
+    Choose a photo
+    <input type="file" {{queue.selectFile}} />
+  </label>
+{{/let}}
+```
+
+When a file is added to your queue, `onFileAdded` is called. You may trigger the upload by calling `file.upload()`. This returns a promise that is resolved when the file has finished uploading, or is rejected if the file couldn't be uploaded.
+
+```js
+export default class ExampleComponent extends Component {
+  @action
+  async uploadPhoto(file) {
+    try {
+      const response = await file.upload('/api/images/upload');
+    } catch (error) {
+      file.state = 'aborted';
+    }
+  }
+}
+```
+
+> ⚠️ Remember we said that uploads continue in the background. However a component may unmount while an upload is in progress. Consider the lifecycle of your objects when performing uploads from within them. In general it's safer to perform uploads in a long-lived object like a Service.
+
+## Displaying upload progress
+
+In addition to the file list, the queue tracks properties that indicate how many bytes have been uploaded (`loaded`), the total size of all files in bytes (`size`), and the percent progress of all files (`progress`). Using these, you may display upload progress in your templates.
+
+```hbs
+{{#if queue.files.length}}
+  Uploading {{queue.files.length}} files. ({{queue.progress}}%)
+{{/if}}
+```
+
+Another common scenario is to alert users that they still have pending uploads when they are about to leave the page. To do this, look at `queue.files.length` to see if there's any files uploading.
+
+You can also [add files via Drag and Drop](file-dropzone.md).