docs: extend @fires JSDoc descriptions for upload events (#11604)

web-padawan · claude · web-flow · commit e819de8b9424 · 2026-04-29T16:53:20.000+03:00
Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/upload/src/vaadin-upload-file.d.ts b/packages/upload/src/vaadin-upload-file.d.ts
@@ -97,9 +97,9 @@ export interface UploadFileEventMap extends HTMLElementEventMap, UploadFileCusto
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
- * @fires {CustomEvent} file-abort - Fired when the abort button is pressed.
- * @fires {CustomEvent} file-retry - Fired when the retry button is pressed.
- * @fires {CustomEvent} file-start - Fired when the start button is pressed.
+ * @fires {CustomEvent} file-abort - Fired when the abort button is pressed. Listened by `vaadin-upload`, which aborts the upload in progress and removes the file from the list.
+ * @fires {CustomEvent} file-retry - Fired when the retry button is pressed. Listened by `vaadin-upload`, which starts a new upload of this file.
+ * @fires {CustomEvent} file-start - Fired when the start button is pressed. Listened by `vaadin-upload`, which starts a new upload of this file.
  */
 declare class UploadFile extends UploadFileMixin(ThemableMixin(HTMLElement)) {
   addEventListener<K extends keyof UploadFileEventMap>(
diff --git a/packages/upload/src/vaadin-upload-file.js b/packages/upload/src/vaadin-upload-file.js
@@ -77,9 +77,9 @@ import { UploadFileMixin } from './vaadin-upload-file-mixin.js';
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
- * @fires {CustomEvent} file-abort - Fired when the abort button is pressed.
- * @fires {CustomEvent} file-retry - Fired when the retry button is pressed.
- * @fires {CustomEvent} file-start - Fired when the start button is pressed.
+ * @fires {CustomEvent} file-abort - Fired when the abort button is pressed. Listened by `vaadin-upload`, which aborts the upload in progress and removes the file from the list.
+ * @fires {CustomEvent} file-retry - Fired when the retry button is pressed. Listened by `vaadin-upload`, which starts a new upload of this file.
+ * @fires {CustomEvent} file-start - Fired when the start button is pressed. Listened by `vaadin-upload`, which starts a new upload of this file.
  *
  * @customElement vaadin-upload-file
  * @extends HTMLElement
diff --git a/packages/upload/src/vaadin-upload.d.ts b/packages/upload/src/vaadin-upload.d.ts
@@ -197,19 +197,19 @@ export interface UploadEventMap extends HTMLElementEventMap, UploadCustomEventMa
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
- * @fires {CustomEvent} file-reject - Fired when a file cannot be added to the queue due to a constrain.
+ * @fires {CustomEvent} file-reject - Fired when a file cannot be added to the queue due to a constraint: file size, file type, or maxFiles.
  * @fires {CustomEvent} file-remove - Fired when a file is removed from the list.
  * @fires {CustomEvent} files-changed - Fired when the `files` property changes.
  * @fires {CustomEvent} max-files-reached-changed - Fired when the `maxFilesReached` property changes.
- * @fires {CustomEvent} upload-before - Fired before the XHR is opened.
+ * @fires {CustomEvent} upload-before - Fired before the XHR is opened. Useful for changing the request URL. If the default is prevented, the XHR is not opened.
  * @fires {CustomEvent} upload-start - Fired when the XHR is sent.
  * @fires {CustomEvent} upload-progress - Fired as many times as the progress is updated.
- * @fires {CustomEvent} upload-success - Fired in case the upload process succeeded.
- * @fires {CustomEvent} upload-error - Fired in case the upload process failed.
- * @fires {CustomEvent} upload-request - Fired when the XHR has been opened but not sent yet.
- * @fires {CustomEvent} upload-response - Fired when on the server response before analyzing it.
- * @fires {CustomEvent} upload-retry - Fired when retry upload is requested.
- * @fires {CustomEvent} upload-abort - Fired when upload abort is requested.
+ * @fires {CustomEvent} upload-success - Fired when the upload process succeeds.
+ * @fires {CustomEvent} upload-error - Fired when the upload process fails.
+ * @fires {CustomEvent} upload-request - Fired when the XHR has been opened but not sent yet. Useful for appending data to the FormData or modifying request parameters. If the default is prevented, the request is not sent.
+ * @fires {CustomEvent} upload-response - Fired when the server response is received, before the component analyzes it. If the default is prevented, the component returns and the listener can handle `xhr` and `file` directly; otherwise the normal flow checks `xhr.status` and `file.error`, which can be modified to force a custom outcome.
+ * @fires {CustomEvent} upload-retry - Fired when retry upload is requested. If the default is prevented, the retry is not performed.
+ * @fires {CustomEvent} upload-abort - Fired when upload abort is requested. If the default is prevented, the upload is not aborted.
  */
 declare class Upload extends UploadMixin(ThemableMixin(ElementMixin(HTMLElement))) {
   addEventListener<K extends keyof UploadEventMap>(
diff --git a/packages/upload/src/vaadin-upload.js b/packages/upload/src/vaadin-upload.js
@@ -88,19 +88,19 @@ import { UploadMixin } from './vaadin-upload-mixin.js';
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
- * @fires {CustomEvent} file-reject - Fired when a file cannot be added to the queue due to a constrain.
+ * @fires {CustomEvent} file-reject - Fired when a file cannot be added to the queue due to a constraint: file size, file type, or maxFiles.
  * @fires {CustomEvent} file-remove - Fired when a file is removed from the list.
  * @fires {CustomEvent} files-changed - Fired when the `files` property changes.
  * @fires {CustomEvent} max-files-reached-changed - Fired when the `maxFilesReached` property changes.
- * @fires {CustomEvent} upload-before - Fired before the XHR is opened.
+ * @fires {CustomEvent} upload-before - Fired before the XHR is opened. Useful for changing the request URL. If the default is prevented, the XHR is not opened.
  * @fires {CustomEvent} upload-start - Fired when the XHR is sent.
  * @fires {CustomEvent} upload-progress - Fired as many times as the progress is updated.
- * @fires {CustomEvent} upload-success - Fired in case the upload process succeeded.
- * @fires {CustomEvent} upload-error - Fired in case the upload process failed.
- * @fires {CustomEvent} upload-request - Fired when the XHR has been opened but not sent yet.
- * @fires {CustomEvent} upload-response - Fired when on the server response before analyzing it.
- * @fires {CustomEvent} upload-retry - Fired when retry upload is requested.
- * @fires {CustomEvent} upload-abort - Fired when upload abort is requested.
+ * @fires {CustomEvent} upload-success - Fired when the upload process succeeds.
+ * @fires {CustomEvent} upload-error - Fired when the upload process fails.
+ * @fires {CustomEvent} upload-request - Fired when the XHR has been opened but not sent yet. Useful for appending data to the FormData or modifying request parameters. If the default is prevented, the request is not sent.
+ * @fires {CustomEvent} upload-response - Fired when the server response is received, before the component analyzes it. If the default is prevented, the component returns and the listener can handle `xhr` and `file` directly; otherwise the normal flow checks `xhr.status` and `file.error`, which can be modified to force a custom outcome.
+ * @fires {CustomEvent} upload-retry - Fired when retry upload is requested. If the default is prevented, the retry is not performed.
+ * @fires {CustomEvent} upload-abort - Fired when upload abort is requested. If the default is prevented, the upload is not aborted.
  *
  * @customElement vaadin-upload
  * @extends HTMLElement

Original file line number	Diff line number	Diff line change
`@@ -97,9 +97,9 @@ export interface UploadFileEventMap extends HTMLElementEventMap, UploadFileCusto`
`97`	`97`	`*`
`98`	`98`	`* See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.`
`99`	`99`	`*`
`100`		`- * @fires {CustomEvent} file-abort - Fired when the abort button is pressed.`
`101`		`- * @fires {CustomEvent} file-retry - Fired when the retry button is pressed.`
`102`		`- * @fires {CustomEvent} file-start - Fired when the start button is pressed.`
	`100`	+ * @fires {CustomEvent} file-abort - Fired when the abort button is pressed. Listened by `vaadin-upload`, which aborts the upload in progress and removes the file from the list.
	`101`	+ * @fires {CustomEvent} file-retry - Fired when the retry button is pressed. Listened by `vaadin-upload`, which starts a new upload of this file.
	`102`	+ * @fires {CustomEvent} file-start - Fired when the start button is pressed. Listened by `vaadin-upload`, which starts a new upload of this file.
`103`	`103`	`*/`
`104`	`104`	`declare class UploadFile extends UploadFileMixin(ThemableMixin(HTMLElement)) {`
`105`	`105`	`addEventListener<K extends keyof UploadFileEventMap>(`
Original file line number	Diff line number	Diff line change
`@@ -77,9 +77,9 @@ import { UploadFileMixin } from './vaadin-upload-file-mixin.js';`
`77`	`77`	`*`
`78`	`78`	`* See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.`
`79`	`79`	`*`
`80`		`- * @fires {CustomEvent} file-abort - Fired when the abort button is pressed.`
`81`		`- * @fires {CustomEvent} file-retry - Fired when the retry button is pressed.`
`82`		`- * @fires {CustomEvent} file-start - Fired when the start button is pressed.`
	`80`	+ * @fires {CustomEvent} file-abort - Fired when the abort button is pressed. Listened by `vaadin-upload`, which aborts the upload in progress and removes the file from the list.
	`81`	+ * @fires {CustomEvent} file-retry - Fired when the retry button is pressed. Listened by `vaadin-upload`, which starts a new upload of this file.
	`82`	+ * @fires {CustomEvent} file-start - Fired when the start button is pressed. Listened by `vaadin-upload`, which starts a new upload of this file.
`83`	`83`	`*`
`84`	`84`	`* @customElement vaadin-upload-file`
`85`	`85`	`* @extends HTMLElement`