feat: add file upload animation to ProgressBar and update documentation

Author: xdan

CHANGELOG.md

@@ -9,6 +9,16 @@
 > - :house: [Internal]
 > - :nail_care: [Polish]
 
+## 4.11.5
+
+#### :rocket: New Feature
+
+- `ProgressBar.showFileUploadAnimation(from?, to?)` — animated file icon that flies from a given point and fades out. Coordinates are relative to the editor container. Both `from` and `to` are optional with sensible defaults. The animation is automatically cleaned up on `destruct()`.
+  ```js
+  const editor = Jodit.make('#editor')
+  jodit.progressbar.showFileUploadAnimation();
+  ```
+
 ## 4.11.4
 
 #### :boom: Breaking Change

src/core/ui/progress-bar/README.md

@@ -1 +1,43 @@
 # Progress Bar UI element
+
+Displays a thin progress bar at the top of the editor workplace and provides a file upload animation.
+
+## Usage
+
+```typescript
+const bar = jodit.progressbar;
+
+// Show the progress bar
+bar.show();
+
+// Update progress (0–100)
+bar.progress(45);
+
+// Hide the progress bar
+bar.hide();
+```
+
+## File upload animation
+
+Animates a file icon that flies from a start point to an end point and fades out.
+Coordinates are relative to the editor container. The animation element is rendered
+in a separate container (like popups) so it is not clipped by `overflow` on the workplace.
+
+```typescript
+// Default: starts at top-center of the editor, flies up-right
+bar.showFileUploadAnimation();
+
+// Custom start position (relative to editor container)
+bar.showFileUploadAnimation({ x: 100, y: 50 });
+
+// Custom start and end positions
+bar.showFileUploadAnimation(
+    { x: 100, y: 50 },   // from
+    { x: 300, y: -100 }  // to
+);
+```
+
+If `from` is omitted, defaults to `{ x: containerWidth / 2, y: 0 }`.
+If `to` is omitted, defaults to `{ x: from.x + 60, y: from.y - 80 }`.
+
+Calling `destruct()` stops and removes any running animation.

src/core/ui/progress-bar/progress-bar.less

@@ -22,7 +22,7 @@
 
 .jodit-progress-bar {
 	position: absolute;
-	z-index: 2147483647;
+	z-index: var(--z-index-tooltip);
 	top: 0;
 	left: 0;
 	height: 2px;
@@ -63,4 +63,25 @@
 			clip: rect(-6px, 22px, 14px, var(--padding-default));
 		}
 	}
+
+	&__file-animation {
+		position: fixed;
+		width: 32px;
+		height: 32px;
+		opacity: 0.8;
+		pointer-events: none;
+		z-index: 2147483647;
+		transform: scale(1);
+		transition:
+			left 800ms ease-in,
+			top 800ms ease-in,
+			opacity 800ms ease-in,
+			transform 800ms ease-in;
+
+		svg {
+			width: 100%;
+			height: 100%;
+			fill: var(--color-background-progress);
+		}
+	}
 }

src/core/ui/progress-bar/progress-bar.test.js

@@ -0,0 +1,143 @@
+/*!
+ * Jodit Editor (https://xdsoft.net/jodit/)
+ * Released under MIT see LICENSE.txt in the project root for license information.
+ * Copyright (c) 2013-2026 Valerii Chupurnov. All rights reserved. https://xdsoft.net
+ */
+
+describe('Test ProgressBar', () => {
+	const { ProgressBar } = Jodit.modules;
+
+	let editor;
+	beforeEach(() => {
+		editor = getJodit();
+	});
+
+	describe('show', () => {
+		it('should append progress bar to workplace', () => {
+			const bar = new ProgressBar(editor);
+			bar.show();
+			expect(editor.workplace.contains(bar.container)).to.be.true;
+			bar.destruct();
+		});
+	});
+
+	describe('hide', () => {
+		it('should remove progress bar from DOM', () => {
+			const bar = new ProgressBar(editor);
+			bar.show();
+			expect(editor.workplace.contains(bar.container)).to.be.true;
+			bar.hide();
+			expect(editor.workplace.contains(bar.container)).to.be.false;
+		});
+	});
+
+	describe('progress', () => {
+		it('should set container width as percentage', () => {
+			const bar = new ProgressBar(editor);
+			bar.show();
+			bar.progress(50);
+			expect(bar.container.style.width).eq('50%');
+			bar.destruct();
+		});
+
+		it('should return self for chaining', () => {
+			const bar = new ProgressBar(editor);
+			expect(bar.progress(10)).eq(bar);
+			bar.destruct();
+		});
+	});
+
+	describe('destruct', () => {
+		it('should remove progress bar from DOM on destruct', () => {
+			const bar = new ProgressBar(editor);
+			bar.show();
+			expect(editor.workplace.contains(bar.container)).to.be.true;
+			bar.destruct();
+			expect(editor.workplace.contains(bar.container)).to.be.false;
+		});
+	});
+
+	describe('showFileUploadAnimation', () => {
+		const sel = '.jodit-progress-bar__file-animation';
+
+		it('should create animation element in DOM', () => {
+			const bar = new ProgressBar(editor);
+			bar.showFileUploadAnimation();
+
+			expect(document.querySelector(sel)).is.not.null;
+			bar.destruct();
+		});
+
+		it('should contain an SVG icon inside animation element', () => {
+			const bar = new ProgressBar(editor);
+			bar.showFileUploadAnimation();
+
+			const svg = document.querySelector(sel + ' svg');
+			expect(svg).is.not.null;
+			bar.destruct();
+		});
+
+		it('should apply position based on editor container rect', () => {
+			const bar = new ProgressBar(editor);
+			const rect = editor.container.getBoundingClientRect();
+			bar.showFileUploadAnimation({ x: 100, y: 50 });
+
+			const animEl = document.querySelector(sel);
+			// End position = rect offset + to (default to = from + 60, from - 80)
+			expect(animEl.style.left).eq(rect.left + 160 + 'px');
+			expect(animEl.style.top).eq(rect.top + -30 + 'px');
+			bar.destruct();
+		});
+
+		it('should use custom from and to positions', () => {
+			const bar = new ProgressBar(editor);
+			const rect = editor.container.getBoundingClientRect();
+			bar.showFileUploadAnimation({ x: 10, y: 20 }, { x: 200, y: 300 });
+
+			const animEl = document.querySelector(sel);
+			expect(animEl.style.left).eq(rect.left + 200 + 'px');
+			expect(animEl.style.top).eq(rect.top + 300 + 'px');
+			bar.destruct();
+		});
+
+		it('should set opacity to 0 for fade out', () => {
+			const bar = new ProgressBar(editor);
+			bar.showFileUploadAnimation();
+
+			const animEl = document.querySelector(sel);
+			expect(animEl.style.opacity).eq('0');
+			bar.destruct();
+		});
+
+		it('should remove animation element on destruct', () => {
+			const bar = new ProgressBar(editor);
+			bar.showFileUploadAnimation();
+
+			expect(document.querySelector(sel)).is.not.null;
+			bar.destruct();
+			expect(document.querySelector(sel)).is.null;
+		});
+
+		it('should remove previous animation if called again', () => {
+			const bar = new ProgressBar(editor);
+			bar.showFileUploadAnimation();
+			bar.showFileUploadAnimation();
+
+			expect(document.querySelectorAll(sel).length).eq(1);
+			bar.destruct();
+		});
+
+		it('should remove element after transitionend event', () => {
+			const bar = new ProgressBar(editor);
+			bar.showFileUploadAnimation();
+
+			const animEl = document.querySelector(sel);
+			expect(animEl).is.not.null;
+
+			animEl.dispatchEvent(new Event('transitionend'));
+
+			expect(document.querySelector(sel)).is.null;
+			bar.destruct();
+		});
+	});
+});

src/core/ui/progress-bar/progress-bar.ts

@@ -10,9 +10,13 @@
  * @module ui/progress-bar
  */
 
-import type { IJodit, IProgressBar } from 'jodit/types';
+import type { IJodit, IProgressBar, Nullable } from 'jodit/types';
 import { Dom } from 'jodit/core/dom/dom';
+import { getContainer } from 'jodit/core/global';
+import { position } from 'jodit/core/helpers/size/position';
+import { css } from 'jodit/core/helpers/utils/css';
 import { UIElement } from 'jodit/core/ui/element';
+import { Icon } from 'jodit/core/ui/icon';
 
 import './progress-bar.less';
 
@@ -46,7 +50,70 @@ export class ProgressBar extends UIElement implements IProgressBar {
 		return this;
 	}
 
+	private __animationElement: Nullable<HTMLElement> = null;
+
+	showFileUploadAnimation(
+		from?: { x: number; y: number },
+		to?: { x: number; y: number }
+	): void {
+		this.__cleanUpAnimation();
+
+		const box = getContainer(this.j, ProgressBar);
+		const pos = position(this.j.container, this.j);
+
+		const el = this.j.c.div(this.getFullElName('file-animation'));
+
+		const iconSvg = Icon.get('file', '');
+		if (iconSvg) {
+			el.innerHTML = iconSvg;
+		}
+
+		const start = from ?? {
+			x: pos.width / 2,
+			y: 0
+		};
+
+		const end = to ?? {
+			x: start.x + 60,
+			y: start.y - 80
+		};
+
+		css(el, {
+			left: pos.left + start.x,
+			top: pos.top + start.y
+		});
+
+		box.appendChild(el);
+		this.__animationElement = el;
+
+		// Force reflow before starting transition
+		// eslint-disable-next-line no-unused-expressions
+		el.offsetWidth;
+
+		css(el, {
+			left: pos.left + end.x,
+			top: pos.top + end.y,
+			opacity: 0,
+			transform: 'scale(0.4)'
+		});
+
+		const onEnd = (): void => {
+			el.removeEventListener('transitionend', onEnd);
+			this.__cleanUpAnimation();
+		};
+
+		el.addEventListener('transitionend', onEnd);
+	}
+
+	private __cleanUpAnimation(): void {
+		if (this.__animationElement) {
+			Dom.safeRemove(this.__animationElement);
+			this.__animationElement = null;
+		}
+	}
+
 	override destruct(): any {
+		this.__cleanUpAnimation();
 		this.hide();
 		return super.destruct();
 	}

src/types/toolbar.d.ts

@@ -367,4 +367,12 @@ export interface IProgressBar extends IUIElement {
 	hide(): IProgressBar;
 
 	progress(percentage: number): IProgressBar;
+
+	/**
+	 * Show file upload animation - file icon flies from `from` to `to` and fades out
+	 */
+	showFileUploadAnimation(
+		from?: { x: number; y: number },
+		to?: { x: number; y: number }
+	): void;
 }