@georapbox/files-dropzone-element 2.1.1 → 3.0.0

package/.editorconfig

@@ -0,0 +1,15 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/.nvmrc

@@ -0,0 +1 @@
+24

package/.prettierignore

@@ -0,0 +1,6 @@
+**/*.html
+**/*.css
+**/*.md
+docs/lib/**
+.zed/
+.vscode/

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 120,
+  "singleQuote": true,
+  "semi": true,
+  "trailingComma": "none",
+  "singleAttributePerLine": false
+}

package/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint",
+    "editorconfig.editorconfig",
+    "typescriptteam.native-preview"
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "eslint.enable": true,
+  "eslint.run": "onType",
+  "eslint.validate": ["javascript", "html"],
+  "js/ts.experimental.useTsgo": true
+}

package/.zed/settings.json

@@ -0,0 +1,9 @@
+{
+  "languages": {
+    "JavaScript": {
+      "language_servers": ["typescript-ls", "eslint"],
+      "formatter": "prettier",
+      "format_on_save": "on"
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [3.0.0] - 2026-11-07
+
+### Breaking Changes
+
+- **Explicit Package Exports**: Added a formal `exports` map to `package.json`.
+  - **Supported entry points**: `@georapbox/files-dropzone-element`, `@georapbox/files-dropzone-element/define`, and `@georapbox/files-dropzone-element/custom-elements.json`.
+  - **Impact**: Direct imports from internal paths (e.g., `@georapbox/files-dropzone-element/dist/...`) are no longer part of the supported public API and may fail in environments that enforce package exports.
+- **Method Renaming**: Renamed the static `defineCustomElement()` method to `define()`.
+  - **Action Required**: Replace calls to `FilesDropzone.defineCustomElement()` with `FilesDropzone.define()`.
+- **Event Changes**:
+  - **Event Renaming**: Renamed all events from `files-dropzone-*` to `dropzone-*` (e.g., `files-dropzone-drop` to `dropzone-drop`).
+  - **Event Type Changes**: The `dropzone-dragenter`, `dropzone-dragover`, and `dropzone-dragleave` events are now dispatched as native `Event` instances instead of `CustomEvent` instances.
+  - **Action Required**: Update event listeners to use the new event names. Event handlers for drag events should no longer rely on `CustomEvent` or access `event.detail`.
+
+## [2.2.0] - 2026-02-16
+
+### Added
+
+- **Custom Elements Manifest Support**: Added support for generating a Custom Elements Manifest (CEM) using `@custom-elements-manifest/analyzer`.
+  - **Script**: Added the `analyze` script for generating the manifest.
+  - **Configuration**: Added `custom-elements-manifest.config.js`.
+  - **Package Metadata**: Added the `customElements` field to `package.json`.
+
+### Changed
+
+- **Node.js Version**: Updated `.nvmrc` to Node.js 24.
+- **JSDoc Documentation**: Refined attribute documentation for improved tooling and editor support.
+
+## [2.1.1] - 2025-08-26
+
+### Fixed
+
+- **File Dialog Compatibility**: Restored compatibility with browsers that do not support `HTMLInputElement.showPicker()` by falling back to programmatically clicking the hidden file input element.
+
+## [2.1.0] - 2025-08-24
+
+### Added
+
+- **File Dialog Error Event**: Added the `files-dropzone-error` event when opening the file dialog fails (e.g., without a user activation gesture).
+- **Error Codes**: Added a `code` field (stable error identifier) to the `files-dropzone-error` event detail.
+- **Static Constants**: Exposed `ERROR_CODES` and `REJECTION_CODES` as static properties on the `FilesDropzone` class for consumer reference.
+
+### Changed
+
+- **File Dialog Invocation**: Switched from `.click()` to `HTMLInputElement.showPicker()` for opening the file dialog.
+
+### Fixed
+
+- **Firefox Android Compatibility**: Fixed an issue where clicking directly on the default slotted text did not open the file dialog (`NotAllowedError`).
+  - **Solution**: Wrapped the default slot content in a `<span>` element to ensure consistent user activation across browsers.
+
+### Maintenance
+
+- **Event Dispatching**: Centralized custom event dispatch in a helper method to reduce code duplication.
+- **Dependencies**: Updated development dependencies.
+
+## [2.0.1] - 2024-08-22
+
+### Changed
+
+- **Build Tooling**: Replaced Parcel with esbuild for bundling.
+- **Linting**: Updated ESLint to use flat configuration.
+- **Formatting**: Switched to Prettier for code formatting.
+- **Dependencies**: Updated development dependencies.
+
+## [2.0.0] - 2024-02-12
+
+### Breaking Changes
+
+- **Removed Attributes**: Removed the `no-click`, `no-keyboard`, and `no-drag` attributes, as they are not recommended for accessibility or usability.
+  - **Reference**: See issue [#4](https://github.com/georapbox/files-dropzone-element/issues/4).
+
+### Changed
+
+- **Focus Delegation**: Set `delegatesFocus` to `true` when attaching the shadow root to the host element, allowing focus to be delegated to the first focusable element in the shadow root.
+- **Accessibility**: Improved the component's accessibility for screen readers.
+- **Dependencies**: Updated development dependencies.
+
+## [1.2.1] - 2023-12-12
+
+### Added
+
+- **MIME Type Support**: Added `.md` and `.markdown` file extensions to common MIME types.
+
+## [1.2.0] - 2023-12-11
+
+### Added
+
+- **Transition Duration**: Added the `--dropzone-transition-duration` CSS custom property to control the dropzone's transition duration.
+  - **Backward Compatibility**: The existing `--transition-duration` property remains supported.
+- **Hover Styling**: Added `--dropzone-border-color-hover`, `--dropzone-background-color-hover`, and `--dropzone-body-color-hover` CSS custom properties to customize the dropzone's hover state.
+- **Focus Styling**: Added the `--dropzone-focus-box-shadow` CSS custom property to customize the dropzone's focus box shadow.
+- **TypeScript Declarations**: Added a TypeScript declaration file.
+
+### Maintenance
+
+- **Dependencies**: Updated development dependencies.
+
+## 1.1.1 - 2023-06-12
+
+### Added
+
+- **MIME Type Support**: Added support for the `image/jxl` MIME type.
+
+### Maintenance
+
+- **Dependencies**: Updated development dependencies.
+
+## 1.1.0 - 2023-04-03
+
+### Added
+
+- **Auto Focus**: Added the `auto-focus` attribute to focus the dropzone when rendered.
+- **Focus Styling**: Added the `--dropzone-focus-shadow-rgb` CSS custom property to customize the focus shadow color.
+- **Transition Duration**: Added the `--transition-duration` CSS custom property to customize the dropzone's transition duration.
+
+### Changed
+
+- **Default Border Colors**: Updated the default values of `--dropzone-border-color` and `--dropzone-border-color-dragover`.
+
+## 1.0.0 - 2023-02-01
+
+### Added
+
+- **Initial Release**: First release of the project.
+
+[Unreleased]: https://github.com/georapbox/files-dropzone-element/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/georapbox/files-dropzone-element/compare/v2.2.0...v3.0.0
+[2.2.0]: https://github.com/georapbox/files-dropzone-element/compare/v2.1.1...v2.2.0
+[2.1.1]: https://github.com/georapbox/files-dropzone-element/compare/v2.1.0...v2.1.1
+[2.1.0]: https://github.com/georapbox/files-dropzone-element/compare/v2.0.1...v2.1.0
+[2.0.1]: https://github.com/georapbox/files-dropzone-element/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/georapbox/files-dropzone-element/compare/v1.2.1...v2.0.0
+[1.2.1]: https://github.com/georapbox/files-dropzone-element/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/georapbox/files-dropzone-element/releases/tag/v1.2.0

package/README.md

@@ -9,42 +9,136 @@
 
 A custom element that creates a drag and drop zone for files.
 
-Note that the element does not provide any functionality for uploading files. Once files are dropped, you are free to process them however you like. 
+> [!NOTE]
+> The element does not provide any functionality for uploading files.
+> Once files are dropped, you are free to process them however you like. 
 
 [API documentation](#api) • [Demo][demo]
 
-## Install
+## Usage
+
+### Installation
 
 ```sh
 $ npm install --save @georapbox/files-dropzone-element
 ```
 
-## Usage
+### Importing the component
+
+By default, the package exports the element class without registering it. This lets the application decide when the custom element is defined.
 
-### Script
+#### Manual definition
 
 ```js
-import { FilesDropzone } from './node_modules/@georapbox/files-dropzone-element/dist/files-dropzone.js';
+import { FilesDropzone } from '@georapbox/files-dropzone-element';
 
-// Manually define the element.
-FilesDropzone.defineCustomElement();
+// Define using the default tag name
+FilesDropzone.define();
 ```
 
-Alternatively, you can import the automatically defined custom element.
+#### Auto-defined (convenience)
+
+If you don't need control over registration, you can import the pre-defined build which immediately registers `<files-dropzone>`.
 
 ```js
-import './node_modules/@georapbox/files-dropzone-element/dist/files-dropzone-defined.js';
+import '@georapbox/files-dropzone-element/define';
 ```
 
-### Markup
+### Using the component in your HTML
+
+Once registered, you can use the <files-dropzone> element in your HTML:
 
 ```html
 <files-dropzone accept="image/*,.txt,application/pdf" multiple></files-dropzone>
 ```
 
-### Style
+### Component styling
+
+The component comes with default styling that can be customized using [CSS Parts](#css-parts) and [CSS Custom Properties](#css-custom-properties).
+
+### Complete example
+
+This example demonstrates how to customize the dropzone's appearance and handle accepted and rejected files.
+
+#### Markup
+
+```html
+<files-dropzone accept="image/png,image/jpeg" multiple>
+  <span>Drag 'n' drop files here, or click to select files</span>
+  <small>Accepted file types: <code>png</code>, <code>jpg</code></small>
+</files-dropzone>
+
+<h3>Accepted files</h3>
+<ul id="accepted-files"></ul>
+
+<h3>Rejected files</h3>
+<ul id="rejected-files"></ul>
+```
+
+#### Styling
+
+Customize the component using CSS custom properties and the `dropzone` CSS part.
+
+```css
+files-dropzone {
+  --dropzone-border-color: #dbdbdb;
+  --dropzone-border-color-dragover: #0096bfab;
+  --dropzone-background-color: #f7f7f7;
+  --dropzone-background-color-dragover: #efefef;
+  --dropzone-body-color: #363636;
+  --dropzone-body-color-dragover: #363636;
+}
+
+files-dropzone::part(dropzone) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+@media (prefers-color-scheme: dark) {
+  files-dropzone {
+    --dropzone-border-color: #526980;
+    --dropzone-border-color-dragover: #0096bfab;
+    --dropzone-background-color: #1a242f;
+    --dropzone-background-color-dragover: #161f27;
+    --dropzone-body-color: #dbdbdb;
+    --dropzone-body-color-dragover: #dbdbdb;
+  }
+}
+```
+
+### Handling events
+
+Listen for the `dropzone-drop` event to access accepted and rejected files.
+
+```js
+import { FilesDropzone } from 'https://unpkg.com/@georapbox/files-dropzone-element';
+
+FilesDropzone.define();
+
+const drozone = document.querySelector('files-dropzone');
+const acceptedFilesList = document.getElementById('accepted-files');
+const rejectedFilesList = document.getElementById('rejected-files');
+
+dropzone.addEventListener('dropzone-drop', evt => {
+  const { acceptedFiles, rejectedFiles } = evt.detail;
 
-By default, the component comes with basic styling. However, you can customise the styles of the various elements of the component using either [CSS Parts](#css-parts) or [CSS Custom Properties](#css-custom-properties).
+  acceptedFilesList.replaceChildren();
+  rejectedFilesList.replaceChildren();
+
+  acceptedFiles.forEach(file => {
+    const li = document.createElement('li');
+    li.textContent = `${file.name} - ${file.size} bytes`;
+    acceptedFilesList.appendChild(li);
+  });
+
+  rejectedFiles.forEach(({ file, errors }) => {
+    const li = document.createElement('li');
+    li.textContent = `${file.name} - ${file.size} bytes (${errors.map(error => error.message).join(', ')})`;
+    rejectedFilesList.appendChild(li);
+  });
+});
+```
 
 ## API
 
@@ -103,10 +197,10 @@ By default, the component comes with basic styling. However, you can customise t
 
 | Name | Type | Description | Arguments |
 | ---- | ---- | ----------- | --------- |
-| `defineCustomElement` | Static | Defines/registers the custom element with the name provided. If no name is provided, the default name is used. The method checks if the element is already defined, hence will skip trying to redefine it. | elementName='files-dropzone' |
-| `openFileDialog`<sup>1</sup> | Instance | Opens the native file dialog programmatically. The method will fail silently if the dropzone is disabled. Note that most browsers require a direct user interaction with the document, to open the file dialog, for security reasons. Therefore, if you are trying to call this method asynchronously, there's a good chance it's going to be blocked by the browser. For example in Safari 15.x, invoking this method inside a `setTimeout` with more that 1000ms delay, the dialog will not open. | - |
+| `define` | Static | Registers the custom element with the browser's CustomElementRegistry unless it has already been defined. | `tagName='files-dropzone'` |
+| `openFileDialog` | Instance | Opens the native file dialog programmatically. The method will fail silently if the dropzone is disabled. Note that most browsers require a direct user interaction with the document, to open the file dialog, for security reasons. Therefore, if you are trying to call this method asynchronously, there's a good chance it's going to be blocked by the browser. For example in Safari 15.x, invoking this method inside a `setTimeout` with more that 1000ms delay, the dialog will not open. | - |
 
-<sup>1</sup> Instance methods are only available after the component has been defined. To ensure the component is defined, you can use `whenDefined` method of the `CustomElementRegistry` interface, eg `customElements.whenDefined('files-dropzone').then(() => { /* call methods here */ });`
+Instance methods are only available after the custom element has been defined. Use [`customElements.whenDefined()`](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/whenDefined) to ensure the element is registered before calling these methods.
 
 ### Static Properties
 
@@ -119,93 +213,15 @@ Below are static properties exposed on the `FilesDropzone` class for consumer re
 
 ### Events
 
-| Name | Description | Event Detail |
-| ---- | ----------- | ------------ |
-| `files-dropzone-drop` | Emitted when one or more files are selected, either by using the native file dialog or dropping files in the dropzone area. The event is emitted regardless if the dropped files are accepted or rejected. Files are accepted or rejected based on the `accept`, `max-files`, `max-size`, `min-size` and `multiple` attributes. | `{acceptedFiles: Array<File>, rejectedFiles: Array<{file: File, errors: Array<{code: FilesDropzoneRejectionCode, message: string}>}>}` |
-| `files-dropzone-drop-accepted` | Emitted when one or more dropped files are accepted. If no files are accepted, the event is not emitted at all. | `{acceptedFiles: Array<File>}` |
-| `files-dropzone-drop-rejected` | Emitted when one or more dropped files are rejected. If no files are rejected, the event is not emitted at all. | `{rejectedFiles: Array<{file: File, errors: Array<{code: FilesDropzoneRejectionCode, message: string}>}>}` |
-| `files-dropzone-dragenter` | Emitted on `dragenter` event. The event is not emitted if `disabled` attribute is set. | - |
-| `files-dropzone-dragover` | Emitted on `dragover` event. The event is not emitted if `disabled` attribute is set. | - |
-| `files-dropzone-dragleave` | Emitted on `dragleave` event. The event is not emitted if `disabled` attribute is set. | - |
-| `files-dropzone-error` | Emitted if there is any error in the process of reading dropped files or directories. | `{error: unknown, code: FilesDropzoneErrorCode}` |
-
-## Usage example
-
-Below is a basic usage example of the custom element that also demonstrates styles customization.
-
-```html
-<head>
-  <style>
-    files-dropzone {
-      --dropzone-border-color: #dbdbdb;
-      --dropzone-border-color-dragover: #0096bfab;
-      --dropzone-background-color: #f7f7f7;
-      --dropzone-background-color-dragover: #efefef;
-      --dropzone-body-color: #363636;
-      --dropzone-body-color-dragover: #363636;
-    }
-
-    files-dropzone::part(dropzone) {
-      display: flex;
-      flex-direction: column;
-      gap: 0.5rem;
-    }
-
-    @media (prefers-color-scheme: dark) {
-      files-dropzone {
-        --dropzone-border-color: #526980;
-        --dropzone-border-color-dragover: #0096bfab;
-        --dropzone-background-color: #1a242f;
-        --dropzone-background-color-dragover: #161f27;
-        --dropzone-body-color: #dbdbdb;
-        --dropzone-body-color-dragover: #dbdbdb;
-      }
-    }
-  </style>
-</head>
-
-<body>
-  <files-dropzone accept="image/png,image/jpg" multiple>
-    <span>Drag 'n' drop files here, or click to select files</span>
-    <small>Accepted file types: <code>png</code>, <code>jpg</code></small>
-  </files-dropzone>
-
-  <h3>Accepted files</h3>
-  <ul id="accepted-files"></ul>
-
-  <h3>Rejected files</h3>
-  <ul id="rejected-files"></ul>
-
-  <script type="module">
-    import { FilesDropzone } from 'https://unpkg.com/@georapbox/files-dropzone-element';
-
-    FilesDropzone.defineCustomElement();
-
-    const drozone = document.querySelector('files-dropzone');
-    const acceptedFilesList = document.getElementById('accepted-files');
-    const rejectedFilesList = document.getElementById('rejected-files');
-
-    dropzone.addEventListener('files-dropzone-drop', evt => {
-      const { acceptedFiles, rejectedFiles } = evt.detail;
-
-      acceptedFilesList.replaceChildren();
-      rejectedFilesList.replaceChildren();
-
-      acceptedFiles.forEach(file => {
-        const li = document.createElement('li');
-        li.textContent = `${file.name} - ${file.size} bytes`;
-        acceptedFilesList.appendChild(li);
-      });
-
-      rejectedFiles.forEach(file => {
-        const li = document.createElement('li');
-        li.textContent = `${file.name} - ${file.size} bytes`;
-        rejectedFilesList.appendChild(li);
-      });
-    });
-  </script>
-</body>  
-```
+| Name | Type | Description | Event Detail |
+| ---- | ---- | ----------- | ------------ |
+| `dropzone-drop` | CustomEvent | Dispatched when one or more files are selected, either by using the native file dialog or dropping files in the dropzone area. The event is emitted regardless if the dropped files are accepted or rejected. Files are accepted or rejected based on the `accept`, `max-files`, `max-size`, `min-size` and `multiple` attributes. | `{acceptedFiles: Array<File>, rejectedFiles: Array<{file: File, errors: Array<{code: FilesDropzoneRejectionCode, message: string}>}>}` |
+| `dropzone-drop-accepted` | CustomEvent | Dispatched when one or more dropped files are accepted. If no files are accepted, the event is not emitted at all. | `{acceptedFiles: Array<File>}` |
+| `dropzone-drop-rejected` | CustomEvent | Dispatched when one or more dropped files are rejected. If no files are rejected, the event is not emitted at all. | `{rejectedFiles: Array<{file: File, errors: Array<{code: FilesDropzoneRejectionCode, message: string}>}>}` |
+| `dropzone-dragenter` | Event | Dispatched on `dragenter` event. The event is not emitted if `disabled` attribute is set. | - |
+| `dropzone-dragover` | Event | Dispatched on `dragover` event. The event is not emitted if `disabled` attribute is set. | - |
+| `dropzone-dragleave` | Event | Dispatched on `dragleave` event. The event is not emitted if `disabled` attribute is set. | - |
+| `dropzone-error` | CustomEvent | Dispatched if there is any error in the process of reading dropped files or directories. | `{error: unknown, code: FilesDropzoneErrorCode}` |
 
 ## Changelog
 
@@ -215,7 +231,7 @@ For API updates and breaking changes, check the [CHANGELOG][changelog].
 
 ### Prerequisites
 
-The project requires `Node.js` and `npm` to be installed on your environment. Preferrably, use [nvm](https://github.com/nvm-sh/nvm) Node Version Manager and use the version of Node.js specified in the `.nvmrc` file by running `nvm use`.
+The project requires `Node.js` and `npm` to be installed on your environment. Preferably, use [nvm](https://github.com/nvm-sh/nvm) Node Version Manager and use the version of Node.js specified in the `.nvmrc` file by running `nvm use`.
 
 ### Install dependencies
 

package/custom-elements-manifest.config.mjs

@@ -0,0 +1,48 @@
+// https://custom-elements-manifest.open-wc.org/analyzer/config/
+export default {
+  /** Globs to analyze */
+  globs: ['src/files-dropzone.js'],
+  /** Globs to exclude */
+  exclude: [],
+  /** Directory to output CEM to */
+  outdir: 'dist',
+  /** Run in dev mode, provides extra logging */
+  dev: false,
+  /** Run in watch mode, runs on file changes */
+  watch: false,
+  /** Include third party custom elements manifests */
+  dependencies: false,
+  /** Output CEM path to `package.json`, defaults to true */
+  packagejson: true,
+  /** Enable special handling for litelement */
+  litelement: false,
+  /** Enable special handling for catalyst */
+  catalyst: false,
+  /** Enable special handling for fast */
+  fast: false,
+  /** Enable special handling for stencil */
+  stencil: false,
+  /** Provide custom plugins */
+  plugins: [
+    {
+      name: 'fix-dynamic-tag-name',
+      moduleLinkPhase({ moduleDoc }) {
+        moduleDoc.exports?.forEach(ex => {
+          if (ex.kind === 'custom-element-definition' && ex.name === 'elementName') {
+            ex.name = 'files-dropzone'; // Force the manifest to show the default tag name
+          }
+        });
+      }
+    }
+  ],
+  /**
+   * Resolution options when using `dependencies: true`
+   * For detailed information about each option, please refer to the [oxc-resolver documentation](https://github.com/oxc-project/oxc-resolver?tab=readme-ov-file#options).
+   */
+  resolutionOptions: {
+    extensions: ['.js', '.ts'],
+    mainFields: ['module', 'main'],
+    conditionNames: ['import', 'require']
+    // ... other oxc-resolver options
+  }
+};