Deprecate FileUpload component and FileDropzone attribute args

ember-file-upload/addon/components/file-dropzone.ts

@@ -10,6 +10,8 @@ import Queue from '../queue';
 import UploadFile, { FileSource } from 'ember-file-upload/upload-file';
 import FileQueueService, { DEFAULT_QUEUE } from '../services/file-queue';
 import { modifier } from 'ember-modifier';
+import { deprecate } from '@ember/debug';
+import { isPresent } from '@ember/utils';
 
 interface FileDropzoneArgs {
   queue?: Queue;
@@ -18,6 +20,8 @@ interface FileDropzoneArgs {
    * Whether users can upload content from websites by dragging images from
    * another webpage and dropping it into your app. The default is `false`
    * to prevent cross-site scripting issues.
+   *
+   * @defaulValue false
    * */
   allowUploadsFromWebsites?: boolean;
 
@@ -27,9 +31,20 @@ interface FileDropzoneArgs {
    *
    * Corresponds to `DataTransfer.dropEffect`.
    * (https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer/dropEffect)
+   *
+   * @defaultValue 'copy'
    */
   cursor?: 'link' | 'none' | 'copy' | 'move';
 
+  /**
+   * Whether to add multiple files to the queue at once.
+   *
+   * If set to false only one file will be added when dropping mulitple files.
+   *
+   * @defaultValue true
+   */
+  multiple?: boolean;
+
   // actions
   filter?: (file: File, files: File[], index: number) => boolean;
 
@@ -51,35 +66,32 @@ interface FileDropzoneArgs {
   // old/deprecated API
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+   * @deprecated Use `@filter` instead.
    */
   accept?: string;
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+   * @deprecated If necessary, disable uploads in your own implementation.
    */
   disabled?: boolean;
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
-   */
-  multiple?: boolean;
-
-  /** @deprecated use `queue` instead */
+   * @deprecated Use `@queue` instead.
+   * */
   name?: string;
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+   * @deprecated Can be removed as it is non-functional.
    */
   capture?: string;
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+   * @deprecated Can be removed as it is non-functional.
    */
   for?: string;
 
   /**
-   * @deprecated use `onDrop()` instead
+   * @deprecated Use `onFileAdded` with {{file-queue}} helper or `@onDrop`.
    */
   onFileAdd: (file: UploadFile) => void;
 }
@@ -123,6 +135,82 @@ export default class FileDropzoneComponent extends Component<FileDropzoneArgs> {
     window.document &&
     'draggable' in document.createElement('span'))();
 
+  constructor(owner: unknown, args: FileDropzoneArgs) {
+    super(owner, args);
+
+    deprecate(
+      `\`@accept\` is deprecated. Use \`@filter\` instead.`,
+      !isPresent(args.accept),
+      {
+        for: 'ember-file-upload',
+        id: 'file-dropzone.accept',
+        since: { enabled: 'v5.0.0' },
+        until: 'v6.0.0',
+        url: 'https://ember-file-upload.pages.dev/docs/upgrade-guide#filedropzone-component',
+      }
+    );
+
+    deprecate(
+      `\`@disabled\` is deprecated. If necessary, disable uploads in your own implementation.`,
+      !isPresent(args.disabled),
+      {
+        for: 'ember-file-upload',
+        id: 'file-dropzone.disabled',
+        since: { enabled: 'v5.0.0' },
+        until: 'v6.0.0',
+        url: 'https://ember-file-upload.pages.dev/docs/upgrade-guide#filedropzone-component',
+      }
+    );
+
+    deprecate(
+      `\`@name\` is deprecated. Use \`@queue\` instead.`,
+      !isPresent(args.name),
+      {
+        for: 'ember-file-upload',
+        id: 'file-dropzone.name',
+        since: { enabled: 'v5.0.0' },
+        until: 'v6.0.0',
+        url: 'https://ember-file-upload.pages.dev/docs/upgrade-guide#filedropzone-component',
+      }
+    );
+
+    deprecate(
+      `\`@capture\` is deprecated. It can be removed as it is non-functional.`,
+      !isPresent(args.capture),
+      {
+        for: 'ember-file-upload',
+        id: 'file-dropzone.capture',
+        since: { enabled: 'v5.0.0' },
+        until: 'v6.0.0',
+        url: 'https://ember-file-upload.pages.dev/docs/upgrade-guide#filedropzone-component',
+      }
+    );
+
+    deprecate(
+      `\`@for\` is deprecated. It can be removed as it is non-functional.`,
+      !isPresent(args.for),
+      {
+        for: 'ember-file-upload',
+        id: 'file-dropzone.for',
+        since: { enabled: 'v5.0.0' },
+        until: 'v6.0.0',
+        url: 'https://ember-file-upload.pages.dev/docs/upgrade-guide#filedropzone-component',
+      }
+    );
+
+    deprecate(
+      `\`@onFileAdd\` is deprecated. Use \`onFileAdded\` with {{file-queue}} helper or \`@onDrop\`.`,
+      !isPresent(args.onFileAdd),
+      {
+        for: 'ember-file-upload',
+        id: 'file-dropzone.on-file-add',
+        since: { enabled: 'v5.0.0' },
+        until: 'v6.0.0',
+        url: 'https://ember-file-upload.pages.dev/docs/upgrade-guide#filedropzone-component',
+      }
+    );
+  }
+
   get queue() {
     if (this.args.queue) {
       return this.args.queue;

ember-file-upload/addon/components/file-upload.ts

@@ -6,6 +6,7 @@ import Queue from '../queue';
 import FileQueueService, { DEFAULT_QUEUE } from '../services/file-queue';
 import { guidFor } from '@ember/object/internals';
 import { next } from '@ember/runloop';
+import { deprecate } from '@ember/debug';
 
 interface FileUploadArgs {
   queue?: Queue;
@@ -18,36 +19,38 @@ interface FileUploadArgs {
 
   // old/deprecated API
 
-  /** @deprecated use `queue` instead */
+  /**
+   * @deprecated Use `@queue` instead.
+   */
   name?: string;
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+   * @deprecated Use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier.
    */
   multiple?: boolean;
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+   * @deprecated Use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier.
    */
   disabled?: boolean;
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+   * @deprecated Use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier.
    */
   accept?: string;
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+   * @deprecated Use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier.
    */
   capture?: string;
 
   /**
-   * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+   * @deprecated Use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier.
    */
   for?: string;
 
   /**
-   * @deprecated use `onFilesSelected()` instead
+   * @deprecated Use `onFileAdded` with {{file-queue}} helper or `@onDrop`.
    */
   onFileAdd: (file: UploadFile) => void;
 }
@@ -88,11 +91,27 @@ interface FileUploadArgs {
  * }
  * ```
  *
- * @deprecated use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier
+ * @deprecated Use `{{file-queue}}` helper with `{{queue.selectFile}}` modifier.
  */
 export default class FileUploadComponent extends Component<FileUploadArgs> {
   @service declare fileQueue: FileQueueService;
 
+  constructor(owner: unknown, args: FileUploadArgs) {
+    super(owner, args);
+
+    deprecate(
+      `\`<FileUpload>\` is deprecated. Use \`{{file-queue}}\` helper with \`{{queue.selectFile}}\` modifier.`,
+      false,
+      {
+        for: 'ember-file-upload',
+        id: 'file-upload',
+        since: { enabled: 'v5.0.0' },
+        until: 'v6.0.0',
+        url: 'https://ember-file-upload.pages.dev/docs/upgrade-guide#fileupload-component',
+      }
+    );
+  }
+
   get queue() {
     if (this.args.queue) {
       return this.args.queue;

ember-file-upload/addon/queue.ts

@@ -3,6 +3,7 @@ import { modifier, ModifierArgs } from 'ember-modifier';
 import { TrackedSet } from 'tracked-built-ins';
 import UploadFile, { FileSource, FileState } from './upload-file';
 import FileQueueService from './services/file-queue';
+import { deprecate } from '@ember/debug';
 
 export interface SelectFileModifierArgs extends ModifierArgs {
   named: {
@@ -70,6 +71,8 @@ export default class Queue {
    * `abort` method, the file will fail to upload, but will
    * be removed from the requeuing proccess, and will be
    * considered to be in a settled state.
+   *
+   * @defaultValue []
    */
   get files(): UploadFile[] {
     return [...this.#distinctFiles.values()];
@@ -127,9 +130,19 @@ export default class Queue {
     this.#listeners.delete(listener);
   }
 
-  /** @deprecated use `add()` instead */
+  /** @deprecated Use `add()` instead. */
   @action
   push(file: UploadFile) {
+    deprecate(
+      `\`Queue.push\` is deprecated. Use \`Queue.add\` instead.`,
+      false,
+      {
+        for: 'ember-file-upload',
+        id: 'queue.push',
+        since: { enabled: 'v5.0.0' },
+        until: 'v6.0.0',
+      }
+    );
     this.add(file);
   }
 

ember-file-upload/addon/services/file-queue.ts

@@ -57,12 +57,6 @@ export default class FileQueueService extends Service {
     return this.find(name) ?? this.create(name);
   }
 
-  //
-  // @TODO
-  // Everything below this line should be deprecated ?
-  // -------------------------------------------------
-  //
-
   /**
    * The list of all files in queues. This automatically gets
    * flushed when all the files in the queue have settled.
@@ -78,7 +72,6 @@ export default class FileQueueService extends Service {
    * considered to be in a settled state.
    *
    * @defaultValue []
-   * @deprecated use a named queue instead
    */
   get files(): UploadFile[] {
     return [...this.queues.values()].reduce((acc, queue) => {
@@ -90,7 +83,6 @@ export default class FileQueueService extends Service {
    * The total size of all files currently being uploaded in bytes.
    *
    * @defaultValue 0
-   * @deprecated use a named queue instead
    */
   get size(): number {
     return this.files.reduce((acc, { size }) => {
@@ -102,7 +94,6 @@ export default class FileQueueService extends Service {
    * The number of bytes that have been uploaded to the server.
    *
    * @defaultValue 0
-   * @deprecated use a named queue instead
    */
   get loaded(): number {
     return this.files.reduce((acc, { loaded }) => {
@@ -115,7 +106,6 @@ export default class FileQueueService extends Service {
    * range of 0 to 100.
    *
    * @defaultValue 0
-   * @deprecated use a named queue instead
    */
   get progress(): number {
     const percent = this.loaded / this.size || 0;