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 to 3.28  | 3.25 or above |
+| 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,28 @@
+# Adding a Dropzone
+
+For adding files to your queue via Drag and Drop you can use the `<FileDropzone>` component.
+
+To upload 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 if dropzone.supported}}
+      Drag and drop photos here to upload them
+    {{/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` |
+
+Control which files are added to the queue with [File Validation](file-validation.md).

docs/file-validation.md

@@ -0,0 +1,47 @@
+# 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.
+
+```hbs
+<input type="file" accept="image/*" {{queue.selectFile}}>
+```
+
+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,39 @@
+# 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|}}
+  Files in queue: {{queue.files.length}}
+{{/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,49 @@
+# 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}}
+```
+
+After a file is added to your queue, the `onFileAdded` callback will be called. You may then upload the file to a URL 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 that uploads continue in the background. A component may unmount while an upload is in progress. Consider the lifecycle of objects in your application 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 the progess of your uploads.
+
+| Property | Description |
+| ----- | ----- |
+| queue.size  | `number` – Total size of all files currently being uploaded in bytes. |
+| queue.loaded  | `number` – Number of bytes that have been uploaded to the server. |
+| queue.progress  | `number` – Current progress of all uploads, as a percentage in the range of 0 to 100. |
+
+```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).