@vaadin/upload 25.1.0-alpha1 → 25.1.0-alpha2

package/src/vaadin-upload-drop-zone.js

@@ -0,0 +1,215 @@
+/**
+ * @license
+ * Copyright (c) 2000 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { html, LitElement } from 'lit';
+import { defineCustomElement } from '@vaadin/component-base/src/define.js';
+import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
+import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
+import { LumoInjectionMixin } from '@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { uploadDropZoneStyles } from './styles/vaadin-upload-drop-zone-base-styles.js';
+import { getFilesFromDropEvent } from './vaadin-upload-helpers.js';
+import { UploadManager } from './vaadin-upload-manager.js';
+
+/**
+ * `<vaadin-upload-drop-zone>` is a Web Component that can be used as a drop zone
+ * for file uploads. When files are dropped on the drop zone, they are added to
+ * a linked UploadManager.
+ *
+ * ```html
+ * <vaadin-upload-drop-zone>
+ *   <p>Drop files here</p>
+ * </vaadin-upload-drop-zone>
+ * ```
+ *
+ * The drop zone must be linked to an UploadManager by setting the
+ * `manager` property:
+ *
+ * ```javascript
+ * const dropZone = document.querySelector('vaadin-upload-drop-zone');
+ * dropZone.manager = uploadManager;
+ * ```
+ *
+ * ### Styling
+ *
+ * The component has no styling by default. When files are dragged over,
+ * the `dragover` attribute is set and the component uses a hover effect.
+ * To override the hover effect, use `vaadin-upload-drop-zone[dragover]::after`
+ * selector to style the pseudo-element covering the drop zone during dragover.
+ *
+ * Attribute          | Description
+ * -------------------|--------------------------------------------
+ * `dragover`         | Set when files are being dragged over the element
+ * `disabled`         | Set when the drop zone is explicitly disabled
+ * `max-files-reached`| Set when the manager has reached maxFiles
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
+ * @customElement
+ * @extends HTMLElement
+ * @mixes ElementMixin
+ * @mixes ThemableMixin
+ */
+class UploadDropZone extends ElementMixin(ThemableMixin(PolylitMixin(LumoInjectionMixin(LitElement)))) {
+  static get is() {
+    return 'vaadin-upload-drop-zone';
+  }
+
+  static get styles() {
+    return uploadDropZoneStyles;
+  }
+
+  static get lumoInjector() {
+    return { ...super.lumoInjector, includeBaseStyles: true };
+  }
+
+  static get properties() {
+    return {
+      /**
+       * Reference to an UploadManager.
+       * When set, dropped files will be automatically added to the manager.
+       * @type {Object | null}
+       */
+      manager: {
+        type: Object,
+        value: null,
+        observer: '__managerChanged',
+      },
+
+      /**
+       * Whether the drop zone is disabled.
+       * @type {boolean}
+       */
+      disabled: {
+        type: Boolean,
+        value: false,
+        reflect: true,
+      },
+
+      /**
+       * True when max files has been reached on the manager.
+       * @type {boolean}
+       * @readonly
+       */
+      maxFilesReached: {
+        type: Boolean,
+        value: false,
+        reflect: true,
+        attribute: 'max-files-reached',
+      },
+
+      /** @private */
+      __dragover: {
+        type: Boolean,
+        value: false,
+        reflect: true,
+        attribute: 'dragover',
+      },
+    };
+  }
+
+  constructor() {
+    super();
+    this.__onMaxFilesReachedChanged = this.__onMaxFilesReachedChanged.bind(this);
+  }
+
+  /** @protected */
+  ready() {
+    super.ready();
+
+    this.addEventListener('dragover', this.__onDragover.bind(this));
+    this.addEventListener('dragleave', this.__onDragleave.bind(this));
+    this.addEventListener('drop', this.__onDrop.bind(this));
+  }
+
+  /** @protected */
+  disconnectedCallback() {
+    super.disconnectedCallback();
+
+    // Clean up manager listener to prevent memory leaks
+    if (this.manager instanceof UploadManager) {
+      this.manager.removeEventListener('max-files-reached-changed', this.__onMaxFilesReachedChanged);
+    }
+  }
+
+  /** @protected */
+  connectedCallback() {
+    super.connectedCallback();
+
+    // Re-attach manager listener when reconnected to DOM
+    if (this.manager instanceof UploadManager) {
+      this.manager.addEventListener('max-files-reached-changed', this.__onMaxFilesReachedChanged);
+
+      // Sync maxFilesReached state with current manager state
+      this.maxFilesReached = !!this.manager.maxFilesReached;
+    }
+  }
+
+  /** @protected */
+  render() {
+    return html`<slot></slot>`;
+  }
+
+  /** @private */
+  __onDragover(event) {
+    event.preventDefault();
+    const effectiveDisabled = this.disabled || this.maxFilesReached;
+    if (!effectiveDisabled) {
+      this.__dragover = true;
+    }
+    event.dataTransfer.dropEffect = effectiveDisabled ? 'none' : 'copy';
+  }
+
+  /** @private */
+  __onDragleave(event) {
+    event.preventDefault();
+    // Only remove dragover if we're actually leaving the drop zone
+    // (not just entering a child element)
+    if (event.relatedTarget && this.contains(event.relatedTarget)) {
+      return;
+    }
+    this.__dragover = false;
+  }
+
+  /** @private */
+  async __onDrop(event) {
+    event.preventDefault();
+    this.__dragover = false;
+
+    // If we have a manager and not disabled, add the files
+    const effectiveDisabled = this.disabled || this.maxFilesReached;
+    if (!effectiveDisabled && this.manager instanceof UploadManager) {
+      const files = await getFilesFromDropEvent(event);
+      this.manager.addFiles(files);
+    }
+  }
+
+  /** @private */
+  __managerChanged(manager, oldManager) {
+    // Remove listener from old manager
+    if (oldManager instanceof UploadManager) {
+      oldManager.removeEventListener('max-files-reached-changed', this.__onMaxFilesReachedChanged);
+    }
+
+    // Add listener to new manager
+    if (this.isConnected && manager instanceof UploadManager) {
+      manager.addEventListener('max-files-reached-changed', this.__onMaxFilesReachedChanged);
+
+      // Sync initial state if manager has maxFilesReached property
+      this.maxFilesReached = !!manager.maxFilesReached;
+    } else {
+      this.maxFilesReached = false;
+    }
+  }
+
+  /** @private */
+  __onMaxFilesReachedChanged(event) {
+    this.maxFilesReached = event.detail.value;
+  }
+}
+
+defineCustomElement(UploadDropZone);
+
+export { UploadDropZone };

package/src/vaadin-upload-file-list-mixin.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+import type { I18nMixinClass } from '@vaadin/component-base/src/i18n-mixin.js';
+import type { UploadManager } from './vaadin-upload-manager.js';
+
+export interface UploadFileListI18n {
+  file?: {
+    retry?: string;
+    start?: string;
+    remove?: string;
+  };
+  error?: {
+    tooManyFiles?: string;
+    fileIsTooBig?: string;
+    incorrectFileType?: string;
+  };
+  uploading?: {
+    status?: {
+      connecting?: string;
+      stalled?: string;
+      processing?: string;
+      held?: string;
+    };
+    remainingTime?: {
+      prefix?: string;
+      unknown?: string;
+    };
+    error?: {
+      serverUnavailable?: string;
+      unexpectedServerError?: string;
+      forbidden?: string;
+    };
+  };
+  units?: {
+    size?: string[];
+    sizeBase?: number;
+  };
+  formatSize?(bytes: number): string;
+  formatTime?(seconds: number, split: number[]): string;
+}
+
+/**
+ * A mixin providing file list functionality.
+ */
+export declare function UploadFileListMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<UploadFileListMixinClass> & Constructor<I18nMixinClass<UploadFileListI18n>> & T;
+
+export declare class UploadFileListMixinClass {
+  /**
+   * If true, the user cannot interact with this element.
+   */
+  disabled: boolean;
+
+  /**
+   * Reference to an UploadManager to link this file list to.
+   * When set, the file list automatically:
+   * - Syncs files from the manager
+   * - Forwards retry/abort/start/remove events back to the manager
+   */
+  manager: UploadManager | null;
+
+  /**
+   * The object used to localize this component.
+   * To change the default localization, replace this with an object
+   * that provides all properties, or just the individual properties
+   * you want to change.
+   */
+  i18n: UploadFileListI18n;
+}

package/src/vaadin-upload-file-list-mixin.js

@@ -4,28 +4,58 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { html, render } from 'lit';
+import { I18nMixin } from '@vaadin/component-base/src/i18n-mixin.js';
+import { UploadManager } from './vaadin-upload-manager.js';
+
+const DEFAULT_I18N = {
+  file: {
+    retry: 'Retry',
+    start: 'Start',
+    remove: 'Remove',
+  },
+  error: {
+    tooManyFiles: 'Too Many Files.',
+    fileIsTooBig: 'File is Too Big.',
+    incorrectFileType: 'Incorrect File Type.',
+  },
+  uploading: {
+    status: {
+      connecting: 'Connecting...',
+      stalled: 'Stalled',
+      processing: 'Processing File...',
+      held: 'Queued',
+    },
+    remainingTime: {
+      prefix: 'remaining time: ',
+      unknown: 'unknown remaining time',
+    },
+    error: {
+      serverUnavailable: 'Upload failed, please try again later',
+      unexpectedServerError: 'Upload failed due to server error',
+      forbidden: 'Upload forbidden',
+    },
+  },
+  units: {
+    size: ['B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'],
+  },
+};
 
 /**
  * @polymerMixin
+ * @mixes I18nMixin
  */
 export const UploadFileListMixin = (superClass) =>
-  class UploadFileListMixin extends superClass {
+  class UploadFileListMixin extends I18nMixin(DEFAULT_I18N, superClass) {
     static get properties() {
       return {
         /**
          * The array of files being processed, or already uploaded.
+         * @readonly
          */
         items: {
           type: Array,
         },
 
-        /**
-         * The object used to localize upload files.
-         */
-        i18n: {
-          type: Object,
-        },
-
         /**
          * If true, the user cannot interact with this element.
          */
@@ -34,27 +64,263 @@ export const UploadFileListMixin = (superClass) =>
           value: false,
           reflectToAttribute: true,
         },
+
+        /**
+         * Reference to an UploadManager to link this file list to.
+         * When set, the file list automatically:
+         * - Syncs files from the manager
+         * - Forwards retry/abort/start/remove events back to the manager
+         * @type {Object | null}
+         */
+        manager: {
+          type: Object,
+          value: null,
+          observer: '__managerChanged',
+        },
       };
     }
 
     static get observers() {
-      return ['__updateItems(items, i18n, disabled)'];
+      return ['__updateItems(items, __effectiveI18n, disabled)'];
+    }
+
+    constructor() {
+      super();
+      this.__onManagerFilesChanged = this.__onManagerFilesChanged.bind(this);
+      this.__onFileRetry = this.__onFileRetry.bind(this);
+      this.__onFileAbort = this.__onFileAbort.bind(this);
+      this.__onFileStart = this.__onFileStart.bind(this);
+      this.__onFileRemove = this.__onFileRemove.bind(this);
+    }
+
+    /** @protected */
+    ready() {
+      super.ready();
+
+      // Listen for file events to forward to the manager
+      this.addEventListener('file-retry', this.__onFileRetry);
+      this.addEventListener('file-abort', this.__onFileAbort);
+      this.addEventListener('file-start', this.__onFileStart);
+      this.addEventListener('file-remove', this.__onFileRemove);
+    }
+
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
+
+      // Clean up manager listener to prevent memory leaks
+      if (this.manager instanceof UploadManager) {
+        this.manager.removeEventListener('files-changed', this.__onManagerFilesChanged);
+      }
+    }
+
+    /** @protected */
+    connectedCallback() {
+      super.connectedCallback();
+
+      // Re-attach manager listener when reconnected to DOM
+      if (this.manager instanceof UploadManager) {
+        this.manager.addEventListener('files-changed', this.__onManagerFilesChanged);
+
+        // Sync state with current manager files
+        this.__syncFromManager();
+      }
+    }
+
+    /** @private */
+    __managerChanged(manager, oldManager) {
+      // Remove listeners from old manager
+      if (oldManager instanceof UploadManager) {
+        oldManager.removeEventListener('files-changed', this.__onManagerFilesChanged);
+      }
+
+      // Add listeners to new manager only when connected
+      if (this.isConnected && manager instanceof UploadManager) {
+        manager.addEventListener('files-changed', this.__onManagerFilesChanged);
+
+        // Sync initial state
+        this.__syncFromManager();
+      } else {
+        // Clear the list when manager is removed
+        this.items = [];
+      }
+    }
+
+    /** @private */
+    __onManagerFilesChanged() {
+      this.__syncFromManager();
+    }
+
+    /** @private */
+    __syncFromManager() {
+      if (this.manager instanceof UploadManager) {
+        this.items = [...this.manager.files];
+      }
+    }
+
+    /** @private */
+    __onFileRetry(event) {
+      if (this.manager instanceof UploadManager) {
+        event.stopPropagation();
+        this.manager.retryUpload(event.detail.file);
+      }
+    }
+
+    /** @private */
+    __onFileAbort(event) {
+      if (this.manager instanceof UploadManager) {
+        event.stopPropagation();
+        this.manager.abortUpload(event.detail.file);
+      }
+    }
+
+    /** @private */
+    __onFileStart(event) {
+      if (this.manager instanceof UploadManager) {
+        event.stopPropagation();
+        this.manager.uploadFiles(event.detail.file);
+      }
+    }
+
+    /** @private */
+    __onFileRemove(event) {
+      if (this.manager instanceof UploadManager) {
+        event.stopPropagation();
+        this.manager.removeFile(event.detail.file);
+      }
     }
 
     /** @private */
     __updateItems(items, i18n) {
       if (items && i18n) {
+        // Apply i18n formatting to each file
+        items.forEach((file) => this.__applyI18nToFile(file));
         this.requestContentUpdate();
       }
     }
 
-    /**
-     * Requests an update for the `vaadin-upload-file` elements.
-     *
-     * It is not guaranteed that the update happens immediately (synchronously) after it is requested.
-     */
+    /** @private */
+    __applyI18nToFile(file) {
+      const i18n = this.__effectiveI18n;
+
+      // Always set size-related strings when total is available
+      if (file.total) {
+        this.__applyFileSizeStrings(file);
+      }
+
+      // Apply status messages based on file state
+      file.status = this.__getFileStatus(file, i18n);
+
+      // Translate error codes to i18n messages
+      this.__applyFileError(file, i18n);
+    }
+
+    /** @private */
+    __applyFileSizeStrings(file) {
+      file.totalStr = this.__formatSize(file.total);
+      file.loadedStr = this.__formatSize(file.loaded || 0);
+      // TODO: Remove elapsedStr in next major version - it's not used by vaadin-upload-file
+      if (file.elapsed != null) {
+        file.elapsedStr = this.__formatTime(file.elapsed, this.__splitTimeByUnits(file.elapsed));
+      }
+      if (file.remaining != null) {
+        file.remainingStr = this.__formatTime(file.remaining, this.__splitTimeByUnits(file.remaining));
+      }
+    }
+
+    /** @private */
+    __getFileStatus(file, i18n) {
+      if (file.held && !file.error) {
+        // File is queued and waiting
+        return i18n.uploading.status.held;
+      }
+      if (file.stalled) {
+        // File upload is stalled
+        return i18n.uploading.status.stalled;
+      }
+      if (file.uploading && file.indeterminate && !file.held) {
+        // File is uploading but progress is indeterminate (connecting or processing)
+        return file.progress === 100 ? i18n.uploading.status.processing : i18n.uploading.status.connecting;
+      }
+      if (file.uploading && file.progress < 100 && file.total) {
+        // File is uploading with known progress
+        return this.__formatFileProgress(file);
+      }
+      return file.status;
+    }
+
+    /** @private */
+    __applyFileError(file, i18n) {
+      if (file.errorKey && i18n.uploading.error[file.errorKey]) {
+        file.error = i18n.uploading.error[file.errorKey];
+      } else if (!file.errorKey && this.manager instanceof UploadManager) {
+        // Clear error when errorKey is reset (e.g., on retry) only when using manager
+        file.error = '';
+      }
+    }
+
+    /** @private */
+    __formatSize(bytes) {
+      const i18n = this.__effectiveI18n;
+      if (typeof i18n.formatSize === 'function') {
+        return i18n.formatSize(bytes);
+      }
+
+      // https://wiki.ubuntu.com/UnitsPolicy
+      const base = i18n.units.sizeBase || 1000;
+      const unit = Math.trunc(Math.log(bytes) / Math.log(base));
+      const dec = Math.max(0, Math.min(3, unit - 1));
+      const size = Number.parseFloat((bytes / base ** unit).toFixed(dec));
+      return `${size} ${i18n.units.size[unit]}`;
+    }
+
+    /** @private */
+    __splitTimeByUnits(time) {
+      const unitSizes = [60, 60, 24, Infinity];
+      const timeValues = [0];
+
+      for (let i = 0; i < unitSizes.length && time > 0; i++) {
+        timeValues[i] = time % unitSizes[i];
+        time = Math.floor(time / unitSizes[i]);
+      }
+
+      return timeValues;
+    }
+
+    /** @private */
+    __formatTime(seconds, split) {
+      const i18n = this.__effectiveI18n;
+      if (typeof i18n.formatTime === 'function') {
+        return i18n.formatTime(seconds, split);
+      }
+
+      // Fill HH:MM:SS with leading zeros
+      while (split.length < 3) {
+        split.push(0);
+      }
+
+      return split
+        .reverse()
+        .map((number) => {
+          return (number < 10 ? '0' : '') + number;
+        })
+        .join(':');
+    }
+
+    /** @private */
+    __formatFileProgress(file) {
+      const i18n = this.__effectiveI18n;
+      const remainingTime =
+        file.loaded > 0
+          ? i18n.uploading.remainingTime.prefix + file.remainingStr
+          : i18n.uploading.remainingTime.unknown;
+
+      return `${file.totalStr}: ${file.progress}% (${remainingTime})`;
+    }
+
+    /** @private */
     requestContentUpdate() {
-      const { items, i18n, disabled } = this;
+      const { items, __effectiveI18n: i18n, disabled } = this;
 
       render(
         html`

package/src/vaadin-upload-file-list.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2026 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { UploadFileListI18n, UploadFileListMixin } from './vaadin-upload-file-list-mixin.js';
+
+export { UploadFileListI18n };
+
+/**
+ * `<vaadin-upload-file-list>` is a Web Component that displays a list of uploaded files.
+ * It automatically syncs files from the manager and forwards file events back to it.
+ *
+ * ```html
+ * <vaadin-upload-file-list></vaadin-upload-file-list>
+ * ```
+ *
+ * The file list must be linked to an UploadManager by setting the `manager` property:
+ *
+ * ```javascript
+ * import { UploadManager } from '@vaadin/upload/vaadin-upload-manager.js';
+ *
+ * const manager = new UploadManager({ target: '/api/upload' });
+ * const fileList = document.querySelector('vaadin-upload-file-list');
+ * fileList.manager = manager;
+ * ```
+ *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name | Description
+ * ----------|-------------
+ * `list`    | The `<ul>` element wrapping the file items
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute  | Description
+ * -----------|-------------
+ * `disabled` | Set when the element is disabled
+ *
+ * The following custom CSS properties are available for styling:
+ *
+ * Custom CSS property                          |
+ * :--------------------------------------------|
+ * `--vaadin-upload-file-list-divider-color`    |
+ * `--vaadin-upload-file-list-divider-width`    |
+ * `--vaadin-upload-file-border-radius`         |
+ * `--vaadin-upload-file-button-background`     |
+ * `--vaadin-upload-file-button-border-color`   |
+ * `--vaadin-upload-file-button-border-radius`  |
+ * `--vaadin-upload-file-button-border-width`   |
+ * `--vaadin-upload-file-button-text-color`     |
+ * `--vaadin-upload-file-button-padding`        |
+ * `--vaadin-upload-file-done-color`            |
+ * `--vaadin-upload-file-error-color`           |
+ * `--vaadin-upload-file-error-font-size`       |
+ * `--vaadin-upload-file-error-font-weight`     |
+ * `--vaadin-upload-file-error-line-height`     |
+ * `--vaadin-upload-file-gap`                   |
+ * `--vaadin-upload-file-name-color`            |
+ * `--vaadin-upload-file-name-font-size`        |
+ * `--vaadin-upload-file-name-font-weight`      |
+ * `--vaadin-upload-file-name-line-height`      |
+ * `--vaadin-upload-file-padding`               |
+ * `--vaadin-upload-file-status-color`          |
+ * `--vaadin-upload-file-status-font-size`      |
+ * `--vaadin-upload-file-status-font-weight`    |
+ * `--vaadin-upload-file-status-line-height`    |
+ * `--vaadin-upload-file-warning-color`         |
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ */
+declare class UploadFileList extends UploadFileListMixin(ThemableMixin(HTMLElement)) {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-upload-file-list': UploadFileList;
+  }
+}
+
+export { UploadFileList };