@georapbox/files-dropzone-element 2.1.1 → 3.0.0

package/eslint.config.mjs

@@ -0,0 +1,42 @@
+import globals from 'globals';
+import pluginJs from '@eslint/js';
+import { configs as pluginWc } from 'eslint-plugin-wc';
+
+export default [
+  {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+        ...globals.chai,
+        ...globals.mocha
+      }
+    }
+  },
+  pluginJs.configs.recommended,
+  pluginWc['flat/recommended'],
+  pluginWc['flat/best-practice'],
+  {
+    rules: {
+      'no-use-before-define': [
+        'error',
+        {
+          functions: false
+        }
+      ],
+      curly: ['warn'],
+      eqeqeq: [
+        'error',
+        'always',
+        {
+          null: 'ignore'
+        }
+      ],
+      'wc/no-child-traversal-in-connectedcallback': 'off',
+      'wc/no-child-traversal-in-attributechangedcallback': 'off'
+    }
+  },
+  {
+    ignores: ['dist', 'docs/lib', 'coverage']
+  }
+];

package/package.json

@@ -1,31 +1,41 @@
 {
   "name": "@georapbox/files-dropzone-element",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "description": "A custom element that creates a drag and drop zone for files",
+  "type": "module",
   "main": "dist/files-dropzone.js",
-  "module": "dist/files-dropzone.js",
   "unpkg": "dist/files-dropzone.js",
-  "type": "module",
   "types": "dist/files-dropzone.d.ts",
-  "files": [
-    "/src",
-    "/dist"
-  ],
+  "customElements": "dist/custom-elements.json",
+  "exports": {
+    ".": {
+      "types": "./dist/files-dropzone.d.ts",
+      "import": "./dist/files-dropzone.js"
+    },
+    "./define": {
+      "types": "./dist/files-dropzone.d.ts",
+      "import": "./dist/files-dropzone-defined.js"
+    },
+    "./custom-elements.json": "./dist/custom-elements.json"
+  },
   "scripts": {
-    "lint": "eslint",
-    "format": "prettier --ignore-unknown --write .",
+    "start": "npm-run-all --parallel \"serve:dev -- {1}\" dev",
+    "dev": "npm-run-all clean dev:esbuild",
+    "dev:esbuild": "node ./scripts/dev.mjs",
+    "serve:dev": "web-dev-server --node-resolve --open /docs/ --watch",
+    "build": "npm-run-all clean build:esbuild",
+    "build:esbuild": "node ./scripts/build.mjs",
+    "build:docs": "npm-run-all build build:docs:copy",
+    "build:docs:copy": "node ./scripts/copy-build-to-docs.mjs",
     "test": "web-test-runner",
     "test:watch": "npm run test -- --watch",
     "test:coverage": "npm run test -- --coverage",
+    "lint": "eslint",
+    "format": "prettier --ignore-unknown --write .",
     "types": "tsc --project tsconfig.json",
-    "dev:esbuild": "node ./scripts/dev.mjs",
-    "dev": "npm-run-all clean dev:esbuild",
-    "serve:dev": "web-dev-server --node-resolve --open /docs/ --watch",
-    "start": "npm-run-all --parallel \"serve:dev -- {1}\" dev",
-    "build:esbuild": "node ./scripts/build.mjs",
-    "build": "npm-run-all clean build:esbuild",
+    "analyze": "custom-elements-manifest analyze",
     "clean": "rimraf dist",
-    "prepare": "npm-run-all clean lint test build types"
+    "prepublishOnly": "npm-run-all clean lint test build types analyze"
   },
   "keywords": [
     "custom element",
@@ -46,23 +56,35 @@
   },
   "homepage": "https://github.com/georapbox/files-dropzone-element#readme",
   "devDependencies": {
-    "@eslint/js": "~9.34.0",
-    "@esm-bundle/chai": "~4.3.4",
-    "@open-wc/testing": "~4.0.0",
-    "@web/dev-server": "~0.4.6",
-    "@web/test-runner": "~0.20.2",
-    "@web/test-runner-playwright": "~0.11.0",
-    "esbuild": "~0.25.9",
-    "eslint": "~9.34.0",
-    "eslint-plugin-wc": "~3.0.1",
-    "globals": "~16.3.0",
+    "@custom-elements-manifest/analyzer": "~0.11.0",
+    "@eslint/js": "~10.0.1",
+    "@esm-bundle/chai": "~4.3.4-fix.0",
+    "@open-wc/testing": "~5.0.0",
+    "@types/node": "~26.6.5",
+    "@web/dev-server": "~1.0.0",
+    "@web/test-runner": "~1.0.0",
+    "@web/test-runner-playwright": "~1.0.0",
+    "esbuild": "~0.28.2",
+    "eslint": "~10.14.0",
+    "eslint-plugin-wc": "~3.1.0",
+    "globals": "~17.13.0",
     "npm-run-all": "~4.1.5",
-    "prettier": "~3.6.2",
-    "rimraf": "~6.0.1",
-    "sinon": "~21.0.0",
-    "typescript": "~5.9.2"
+    "playwright": "~1.64.1",
+    "prettier": "~3.9.10",
+    "rimraf": "~6.1.3",
+    "sinon": "~22.1.0",
+    "typescript": "~7.0.2"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "engines": {
+    "node": ">=24",
+    "npm": ">=11.17.0"
+  },
+  "allowScripts": {
+    "esbuild@0.28.2": true,
+    "fsevents@2.3.2": true,
+    "rs-module-lexer@2.6.0": true
   }
 }

package/scripts/build.mjs

@@ -0,0 +1,32 @@
+import fs from 'fs/promises';
+import * as esbuild from 'esbuild';
+
+const PACKAGE_NAME = 'files-dropzone';
+
+const readPkg = async () => {
+  return JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url)));
+};
+
+const pkg = await readPkg();
+
+const makeBanner = pkg => `/*!
+ * ${pkg.name}
+ * ${pkg.description}
+ *
+ * @version ${pkg.version}
+ * @homepage ${pkg.homepage}
+ * @author ${pkg.author.name} <${pkg.author.email}>
+ * @license ${pkg.license}
+ */`;
+
+await esbuild.build({
+  entryPoints: [`src/${PACKAGE_NAME}.js`, `src/${PACKAGE_NAME}-defined.js`],
+  bundle: true,
+  minify: true,
+  sourcemap: true,
+  format: 'esm',
+  outdir: 'dist',
+  banner: {
+    js: makeBanner(pkg)
+  }
+});

package/scripts/copy-build-to-docs.mjs

@@ -0,0 +1,17 @@
+import { copyFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const PACKAGE_NAME = 'files-dropzone';
+const files = [`${PACKAGE_NAME}.js`];
+const sourceDir = path.resolve('dist');
+const destinationDir = path.resolve('docs/lib');
+
+await mkdir(destinationDir, { recursive: true });
+
+const copyPromises = files.map(file => {
+  const source = path.join(sourceDir, file);
+  const destination = path.join(destinationDir, file);
+  return copyFile(source, destination);
+});
+
+await Promise.all(copyPromises);

package/scripts/dev.mjs

@@ -0,0 +1,24 @@
+import * as esbuild from 'esbuild';
+
+const PACKAGE_NAME = 'files-dropzone';
+
+const ctx = await esbuild.context({
+  entryPoints: [`src/${PACKAGE_NAME}.js`, `src/${PACKAGE_NAME}-defined.js`],
+  bundle: true,
+  sourcemap: true,
+  format: 'esm',
+  outdir: 'dist',
+  metafile: true,
+  plugins: [
+    {
+      name: 'rebuild-notify',
+      setup(build) {
+        build.onEnd(result => {
+          console.log(`Build ended with ${result.errors.length} errors`);
+        });
+      }
+    }
+  ]
+});
+
+await ctx.watch();

package/src/files-dropzone-defined.js

@@ -1,5 +1,5 @@
 import { FilesDropzone } from './files-dropzone.js';
 
-FilesDropzone.defineCustomElement();
+FilesDropzone.define();
 
 export { FilesDropzone };

package/src/files-dropzone.js

@@ -1,20 +1,13 @@
 // @ts-check
 
 /**
- * Represents a value that may be of type T, or null.
- *
- * @template T
- * @typedef {T | null} Nullable
- */
-
-/**
- * Stable identifier for error codes used in the `files-dropzone-error` event.
+ * Stable identifier for error codes used in the `dropzone-error` event.
  *
  * @typedef {typeof FilesDropzone.ERROR_CODES[keyof typeof FilesDropzone.ERROR_CODES]} FilesDropzoneErrorCode
  */
 
 /**
- * The detail payload for the `files-dropzone-error` event.
+ * The detail payload for the `dropzone-error` event.
  *
  * @typedef {Object} FilesDropzoneErrorDetail
  * @property {FilesDropzoneErrorCode} code - Stable identifier for the type of error that occurred.
@@ -27,12 +20,11 @@
  * @typedef {typeof FilesDropzone.REJECTION_CODES[keyof typeof FilesDropzone.REJECTION_CODES]} FilesDropzoneRejectionCode
  */
 
-import { isValidFile } from './utils/is-valid-file.js';
-import { getFilesFromEvent } from './utils/files-selector.js';
+import { isValidFile } from './is-valid-file.js';
+import { getFilesFromEvent } from './files-selector.js';
 
 const css = String.raw;
 const html = String.raw;
-const COMPONENT_NAME = 'files-dropzone';
 const template = document.createElement('template');
 
 const styles = css`
@@ -126,7 +118,7 @@ template.innerHTML = html`
  * @summary A custom element that allows users to drag and drop files into it.
  * @documentation https://github.com/georapbox/files-dropzone-element
  *
- * @tagname files-dropzone - This is the default tag name, unless overridden by the `defineCustomElement` method.
+ * @tagname files-dropzone - This is the default tag name, unless overridden by the `define` method.
  *
  * @property {string} accept - A comma-separated list of unique file type specifiers describing file types to allow.
  * @property {boolean} disabled - Determines whether the dropzone is disabled.
@@ -137,14 +129,14 @@ template.innerHTML = html`
  * @property {boolean} autoFocus - Automatically focuses the dropzone when it's connected to the DOM.
  * @property {boolean} noStyle - Prevents the dropzone from applying any styling.
  *
- * @attribute {string} accept - Reflects the accept property.
- * @attribute {boolean} disabled - Reflects the disabled property.
- * @attribute {number} max-files - Reflects the maxFiles property.
- * @attribute {number} max-size - Reflects the maxSize property.
- * @attribute {number} min-size - Reflects the minSize property.
- * @attribute {boolean} multiple - Reflects the multiple property.
- * @attribute {boolean} auto-focus - Reflects the autoFocus property.
- * @attribute {boolean} no-style - Reflects the noStyle property.
+ * @attribute {string} accept - A comma-separated list of unique file type specifiers describing file types to allow.
+ * @attribute {boolean} disabled - Determines whether the dropzone is disabled.
+ * @attribute {number} max-files - The maximum number of files allowed to be dropped.
+ * @attribute {number} max-size - The maximum file size allowed in bytes.
+ * @attribute {number} min-size - The minimum file size allowed in bytes.
+ * @attribute {boolean} multiple - Allows multiple files to be dropped.
+ * @attribute {boolean} auto-focus - Automatically focuses the dropzone when it's connected to the DOM.
+ * @attribute {boolean} no-style - Prevents the dropzone from applying any styling.
  *
  * @slot - The default slot content of the dropzone.
  *
@@ -167,15 +159,15 @@ template.innerHTML = html`
  * @cssproperty --dropzone-focus-box-shadow - The box shadow of the dropzone when focused.
  * @cssproperty --dropzone-transition-duration - The transition's duration for the dropzone area.
  *
- * @event files-dropzone-drop - Fired when files are dropped.
- * @event files-dropzone-drop-accepted - Fired when files dropped files are accepted.
- * @event files-dropzone-drop-rejected - Fired when files dropped files are rejected.
- * @event files-dropzone-dragenter - Fired when files are dragged into the dropzone.
- * @event files-dropzone-dragover - Fired when files are dragged over the dropzone.
- * @event files-dropzone-dragleave - Fired when files are dragged out of the dropzone.
- * @event files-dropzone-error - Fired when there is any error in the process of reading dropped files or directories.
+ * @event dropzone-drop - Dispatched when files are dropped.
+ * @event dropzone-drop-accepted - Dispatched when files dropped files are accepted.
+ * @event dropzone-drop-rejected - Dispatched when files dropped files are rejected.
+ * @event dropzone-dragenter - Dispatched when files are dragged into the dropzone.
+ * @event dropzone-dragover - Dispatched when files are dragged over the dropzone.
+ * @event dropzone-dragleave - Dispatched when files are dragged out of the dropzone.
+ * @event dropzone-error - Dispatched when there is any error in the process of reading dropped files or directories.
  *
- * @method defineCustomElement - Static method. Defines a custom element with the given name.
+ * @method define - Static method. Registers the custom element with the browser's CustomElementRegistry unless it has already been defined.
  * @method openFileDialog - Instance method. Opens the file dialog programmatically.
  */
 class FilesDropzone extends HTMLElement {
@@ -201,10 +193,10 @@ class FilesDropzone extends HTMLElement {
     INVALID_MIME_TYPE: 'INVALID_MIME_TYPE'
   });
 
-  /** @type {Nullable<HTMLInputElement>} */
+  /** @type {HTMLInputElement | null} */
   #fileInput = null;
 
-  /** @type {Nullable<HTMLElement>} */
+  /** @type {HTMLElement | null} */
   #dropzoneEl = null;
 
   constructor() {
@@ -216,7 +208,7 @@ class FilesDropzone extends HTMLElement {
     }
 
     if (this.shadowRoot) {
-      this.#fileInput = /** @type {Nullable<HTMLInputElement>} */ (this.shadowRoot.getElementById('file-input'));
+      this.#fileInput = /** @type {HTMLInputElement | null} */ (this.shadowRoot.getElementById('file-input'));
       this.#dropzoneEl = this.shadowRoot.getElementById('dropzone');
     }
   }
@@ -293,7 +285,8 @@ class FilesDropzone extends HTMLElement {
 
   /**
    * @type {string} - A comma-separated list of unique file type specifiers describing file types to allow.
-   * @attribute accept - Reflects the accept property.
+   * @attribute accept
+   * @default ''
    */
   get accept() {
     return this.getAttribute('accept') || '';
@@ -305,8 +298,8 @@ class FilesDropzone extends HTMLElement {
 
   /**
    * @type {boolean} - Determines whether the dropzone is disabled.
+   * @attribute disabled
    * @default false
-   * @attribute disabled - Reflects the disabled property.
    */
   get disabled() {
     return this.hasAttribute('disabled');
@@ -318,8 +311,8 @@ class FilesDropzone extends HTMLElement {
 
   /**
    * @type {number} - The maximum number of files allowed to be dropped.
+   * @attribute max-files
    * @default Infinity
-   * @attribute max-files - Reflects the maxFiles property.
    */
   get maxFiles() {
     const num = Number(this.getAttribute('max-files')) || 0;
@@ -337,8 +330,8 @@ class FilesDropzone extends HTMLElement {
 
   /**
    * @type {number} - The maximum file size allowed in bytes.
+   * @attribute max-size
    * @default Infinity
-   * @attribute max-size - Reflects the maxSize property.
    */
   get maxSize() {
     const value = this.getAttribute('max-size');
@@ -358,8 +351,8 @@ class FilesDropzone extends HTMLElement {
 
   /**
    * @type {number} - The minimum file size allowed in bytes.
+   * @attribute min-size
    * @default 0
-   * @attribute min-size - Reflects the minSize property.
    */
   get minSize() {
     const value = this.getAttribute('min-size');
@@ -379,8 +372,8 @@ class FilesDropzone extends HTMLElement {
 
   /**
    * @type {boolean} - Allows multiple files to be dropped.
+   * @attribute multiple
    * @default false
-   * @attribute multiple - Reflects the multiple property.
    */
   get multiple() {
     return this.hasAttribute('multiple');
@@ -392,8 +385,8 @@ class FilesDropzone extends HTMLElement {
 
   /**
    * @type {boolean} - Automatically focuses the dropzone when it's connected to the DOM.
+   * @attribute auto-focus
    * @default false
-   * @attribute auto-focus - Reflects the autoFocus property.
    */
   get autoFocus() {
     return this.hasAttribute('auto-focus');
@@ -405,8 +398,8 @@ class FilesDropzone extends HTMLElement {
 
   /**
    * @type {boolean} - Prevents the dropzone from applying any styling.
+   * @attribute no-style
    * @default false
-   * @attribute no-style - Reflects the noStyle property.
    */
   get noStyle() {
     return this.hasAttribute('no-style');
@@ -417,37 +410,19 @@ class FilesDropzone extends HTMLElement {
   }
 
   /**
-   * Emit a custom event with the given name and detail.
-   *
-   * @template D
-   * @param {string} name - The name of the event.
-   * @param {D} [detail] - The detail payload of the event.
-   * @param {CustomEventInit<D>} [init] - Override the default event initialization options.
-   * @returns {boolean} - Returns false if at least one event listener called `preventDefault()`, otherwise true.
-   */
-  #emitEvent(name, detail, init) {
-    const options = {
-      bubbles: true,
-      composed: true,
-      cancelable: false,
-      ...init,
-      detail
-    };
-    const evt = new CustomEvent(`${COMPONENT_NAME}-${name}`, options);
-    return this.dispatchEvent(evt);
-  }
-
-  /**
-   * Emit a standardized error event with typed detail.
+   * Dispatches an event, using CustomEvent when detail is provided.
    *
-   * @param {FilesDropzoneErrorCode} code - Stable identifier for the type of error that occurred.
-   * @param {unknown} error - The underlying error that triggered the event.
+   * @template T
+   * @param {string} type - The event type.
+   * @param {T} [detail] - Optional event detail.
+   * @param {{ cancelable?: boolean }} [options] - Event options.
+   * @returns {boolean} Whether the event was not canceled.
    */
-  #emitErrorEvent(code, error) {
-    /** @type {FilesDropzoneErrorDetail} */
-    const detail = { code, error };
+  #emit(type, detail, { cancelable = false } = {}) {
+    const options = { bubbles: true, composed: true, cancelable };
+    const event = detail === undefined ? new Event(type, options) : new CustomEvent(type, { ...options, detail });
 
-    this.#emitEvent('error', detail);
+    return this.dispatchEvent(event);
   }
 
   /**
@@ -459,7 +434,10 @@ class FilesDropzone extends HTMLElement {
     try {
       this.#handleFilesSelect(await getFilesFromEvent(evt));
     } catch (err) {
-      this.#emitErrorEvent(FilesDropzone.ERROR_CODES.FILE_INPUT_CHANGE_FAILED, err);
+      this.#emit('dropzone-error', {
+        code: FilesDropzone.ERROR_CODES.FILE_INPUT_CHANGE_FAILED,
+        error: err
+      });
     }
   };
 
@@ -471,7 +449,7 @@ class FilesDropzone extends HTMLElement {
       return;
     }
 
-    this.#emitEvent('dragenter');
+    this.#emit('dropzone-dragenter');
   };
 
   /**
@@ -494,7 +472,7 @@ class FilesDropzone extends HTMLElement {
       this.#dropzoneEl.part.add('dropzone--dragover');
     }
 
-    this.#emitEvent('dragover');
+    this.#emit('dropzone-dragover');
   };
 
   /**
@@ -510,7 +488,7 @@ class FilesDropzone extends HTMLElement {
       this.#dropzoneEl.part.remove('dropzone--dragover');
     }
 
-    this.#emitEvent('dragleave');
+    this.#emit('dropzone-dragleave');
   };
 
   /**
@@ -533,7 +511,10 @@ class FilesDropzone extends HTMLElement {
     try {
       this.#handleFilesSelect(await getFilesFromEvent(evt));
     } catch (err) {
-      this.#emitErrorEvent(FilesDropzone.ERROR_CODES.DROP_EVENT_PROCESSING_FAILED, err);
+      this.#emit('dropzone-error', {
+        code: FilesDropzone.ERROR_CODES.DROP_EVENT_PROCESSING_FAILED,
+        error: err
+      });
     }
   };
 
@@ -643,14 +624,14 @@ class FilesDropzone extends HTMLElement {
       }
     }
 
-    this.#emitEvent('drop', { acceptedFiles, rejectedFiles });
+    this.#emit('dropzone-drop', { acceptedFiles, rejectedFiles });
 
     if (acceptedFiles.length > 0) {
-      this.#emitEvent('drop-accepted', { acceptedFiles });
+      this.#emit('dropzone-drop-accepted', { acceptedFiles });
     }
 
     if (rejectedFiles.length > 0) {
-      this.#emitEvent('drop-rejected', { rejectedFiles });
+      this.#emit('dropzone-drop-rejected', { rejectedFiles });
     }
 
     if (this.#fileInput) {
@@ -673,7 +654,10 @@ class FilesDropzone extends HTMLElement {
       try {
         this.#fileInput.showPicker();
       } catch (err) {
-        this.#emitErrorEvent(FilesDropzone.ERROR_CODES.FILE_DIALOG_OPEN_FAILED, err);
+        this.#emit('dropzone-error', {
+          code: FilesDropzone.ERROR_CODES.FILE_DIALOG_OPEN_FAILED,
+          error: err
+        });
       }
       return;
     }
@@ -695,10 +679,9 @@ class FilesDropzone extends HTMLElement {
    * @param {'accept' | 'disabled' | 'maxFiles' | 'maxSize' | 'minSize' | 'multiple' | 'autoFocus' | 'noStyle'} prop - The property name to upgrade.
    */
   #upgradeProperty(prop) {
-    /** @type {any} */
-    const instance = this;
+    const instance = /** @type {HTMLElement & Record<string, unknown>} */ (this);
 
-    if (Object.prototype.hasOwnProperty.call(instance, prop)) {
+    if (Object.hasOwn(instance, prop)) {
       const value = instance[prop];
       delete instance[prop];
       instance[prop] = value;
@@ -706,18 +689,16 @@ class FilesDropzone extends HTMLElement {
   }
 
   /**
-   * Defines a custom element with the given name.
-   * The name must contain a dash (-).
-   *
-   * @param {string} [elementName='files-dropzone'] - The name of the custom element.
-   * @example
+   * Registers the custom element with the browser's CustomElementRegistry unless
+   * it has already been defined.
    *
-   * FilesDropzone.defineCustomElement('my-dropzone');
+   * @param {string} [tagName='files-dropzone'] - The tag name to use for the custom element.
    */
-  static defineCustomElement(elementName = COMPONENT_NAME) {
-    if (typeof window !== 'undefined' && !window.customElements.get(elementName)) {
-      window.customElements.define(elementName, FilesDropzone);
+  static define(tagName = 'files-dropzone') {
+    if (typeof window === 'undefined' || window.customElements.get(tagName)) {
+      return;
     }
+    window.customElements.define(tagName, FilesDropzone);
   }
 }
 

package/test/files-dropzone-upgrade.test.js

@@ -0,0 +1,39 @@
+import { expect, fixture, fixtureCleanup, html } from '@open-wc/testing';
+import { FilesDropzone } from '../src/files-dropzone.js';
+
+describe('files-dropzone upgrading', () => {
+  afterEach(() => {
+    fixtureCleanup();
+  });
+
+  it('should preserve properties set before the custom element is defined', async () => {
+    const container = await fixture(html`<div></div>`);
+    const el = document.createElement('files-dropzone');
+
+    // Set properties before upgrading
+    el.accept = 'image/*';
+    el.disabled = true;
+    el.maxFiles = 5;
+    el.maxSize = 1024 * 1024;
+    el.minSize = 1024;
+    el.multiple = true;
+    el.autoFocus = true;
+    el.noStyle = true;
+
+    // Define and explicitly upgrade the custom element
+    FilesDropzone.define();
+    customElements.upgrade(el);
+
+    // Connect the element so connectedCallback runs
+    container.appendChild(el);
+
+    expect(el.getAttribute('accept')).to.equal('image/*');
+    expect(el.getAttribute('disabled')).to.equal('');
+    expect(el.getAttribute('max-files')).to.equal('5');
+    expect(el.getAttribute('max-size')).to.equal('1048576');
+    expect(el.getAttribute('min-size')).to.equal('1024');
+    expect(el.getAttribute('multiple')).to.equal('');
+    expect(el.getAttribute('auto-focus')).to.equal('');
+    expect(el.getAttribute('no-style')).to.equal('');
+  });
+});