suneditor 3.0.0-beta.9 → 3.0.0-rc.2

package/src/plugins/command/fileUpload.js

@@ -1,20 +1,37 @@
-import EditorInjector from '../../editorInjector';
+import { PluginCommand } from '../../interfaces';
 import { dom, env, numbers } from '../../helper';
-import { FileManager, Figure, Controller } from '../../modules';
+import { Controller, Figure } from '../../modules/contract';
+import { FileManager } from '../../modules/manager';
 
 const { NO_EVENT } = env;
 
+/**
+ * @typedef FileUploadPluginOptions
+ * @property {string} uploadUrl - Server request URL for file upload
+ * @property {Object<string, string>} [uploadHeaders] - Server request headers
+ * @property {number} [uploadSizeLimit] - Total upload size limit in bytes
+ * @property {number} [uploadSingleSizeLimit] - Single file size limit in bytes
+ * @property {boolean} [allowMultiple=false] - Allow multiple file uploads
+ * @property {string} [acceptedFormats="*"] - Accepted file formats (e.g., 'image/*, .pdf')
+ * @property {string} [as="box"] - Specify the default form of the file component as `box` or `link`
+ * @property {Array<string>} [controls] - Additional controls to be added to the figure
+ * @property {SunEditor.ComponentInsertType} [insertBehavior] - Component insertion behavior for selection and cursor placement. [default: `options.get('componentInsertBehavior')`]
+ * - `auto`: Move cursor to the next line if possible, otherwise select the component.
+ * - `select`: Always select the inserted component.
+ * - `line`: Move cursor to the next line if possible, or create a new line and move there.
+ * - `none`: Do nothing.
+ */
+
 /**
  * @class
  * @description File upload plugin
  */
-class FileUpload extends EditorInjector {
+class FileUpload extends PluginCommand {
 	static key = 'fileUpload';
-	static type = 'command';
 	static className = '';
 	static options = { eventIndex: 10000 };
+
 	/**
-	 * @this {FileUpload}
 	 * @param {HTMLElement} node - The node to check.
 	 * @returns {HTMLElement|null} Returns a node if the node is a valid component.
 	 */
@@ -22,23 +39,18 @@ class FileUpload extends EditorInjector {
 		return dom.check.isAnchor(node) && node.hasAttribute('data-se-file-download') ? node : null;
 	}
 
+	#acceptedCheck;
+	#element = null;
+
 	/**
 	 * @constructor
-	 * @param {__se__EditorCore} editor - The root editor instance
-	 * @param {Object} pluginOptions - plugin options
-	 * @param {string} pluginOptions.uploadUrl - server request url
-	 * @param {Object<string, string>=} pluginOptions.uploadHeaders - server request headers
-	 * @param {string=} pluginOptions.uploadSizeLimit - upload size limit
-	 * @param {string=} pluginOptions.uploadSingleSizeLimit - upload single size limit
-	 * @param {boolean=} pluginOptions.allowMultiple - allow multiple files
-	 * @param {string=} pluginOptions.acceptedFormats - accepted formats
-	 * @param {string=} pluginOptions.as - Whether to use the 'Box' or 'Link' conversion button
-	 * @param {Array<string>} pluginOptions.controls - Additional controls to be added to the figure
+	 * @param {SunEditor.Kernel} editor - The core kernel
+	 * @param {FileUploadPluginOptions} pluginOptions - plugin options
 	 */
 	constructor(editor, pluginOptions) {
 		super(editor);
 		// plugin basic properties
-		this.title = this.lang.fileUpload;
+		this.title = this.$.lang.fileUpload;
 		this.icon = 'file_upload';
 
 		if (!pluginOptions.uploadUrl) console.warn('[SUNEDITOR.fileUpload.warn] "fileUpload" plugin must be have "uploadUrl" option.');
@@ -50,100 +62,75 @@ class FileUpload extends EditorInjector {
 		this.uploadSingleSizeLimit = numbers.get(pluginOptions.uploadSingleSizeLimit, 0);
 		this.allowMultiple = !!pluginOptions.allowMultiple;
 		this.acceptedFormats = typeof pluginOptions.acceptedFormats !== 'string' ? '*' : pluginOptions.acceptedFormats.trim() || '*';
-		this._acceptedCheck = this.acceptedFormats.split(', ');
 		this.as = pluginOptions.as || 'box';
+		this.insertBehavior = pluginOptions.insertBehavior;
 		this.input = dom.utils.createElement('input', { type: 'file', accept: this.acceptedFormats });
 		if (this.allowMultiple) {
 			this.input.setAttribute('multiple', 'multiple');
 		}
-		this._element = null;
+
+		this.#acceptedCheck = this.acceptedFormats.split(', ');
 
 		// figure
 		const customItems = {
 			'custom-download': {
 				command: 'download',
-				title: this.lang.download,
+				title: this.$.lang.download,
 				icon: 'download',
 				action: (target) => {
 					const url = target.getAttribute('href');
 					if (url) dom.utils.createElement('A', { href: url }, null).click();
-				}
+				},
 			},
 			'custom-as': {
 				command: 'as',
 				value: 'link', // 'block' or 'link'
-				title: this.lang.asLink,
+				title: this.$.lang.asLink,
 				icon: 'reduction',
 				action: (target, value) => {
 					this.convertFormat(target, value);
-				}
-			}
+				},
+			},
 		};
 
 		const figureControls = (pluginOptions.controls || [['custom-as', 'align', 'edit', 'custom-download', 'copy', 'remove']]).map((subArray) => subArray.map((item) => (item.startsWith('custom-') ? customItems[item] : item)));
-		this.figure = new Figure(this, figureControls, {});
+		this.figure = new Figure(this, this.$, figureControls, {});
 
 		// file manager
-		this.fileManager = new FileManager(this, {
+		this.fileManager = new FileManager(this, this.$, {
 			query: 'a[download][data-se-file-download]',
-			loadHandler: this.events.onFileLoad,
-			eventHandler: this.events.onFileAction
+			loadEventName: 'onFileLoad',
+			actionEventName: 'onFileAction',
 		});
 
 		// controller
 		if (/\bedit\b/.test(JSON.stringify(figureControls))) {
-			const controllerEl = CreateHTML_controller(this);
-			this.controller = new Controller(this, controllerEl, { position: 'bottom', disabled: true }, FileUpload.key);
+			const controllerEl = CreateHTML_controller(this.$);
+			this.controller = new Controller(this, this.$, controllerEl, { position: 'bottom', disabled: true }, FileUpload.key);
 			this.editInput = controllerEl.querySelector('input');
 		}
 
 		// init
-		this.eventManager.addEvent(this.input, 'change', this.#OnChangeFile.bind(this));
+		this.$.eventManager.addEvent(this.input, 'change', this.#OnChangeFile.bind(this));
 	}
 
 	/**
-	 * @editorMethod Editor.core
-	 * @description Executes the main execution method of the plugin.
-	 * - It is executed by clicking a toolbar "command" button or calling an API.
+	 * @override
+	 * @type {PluginCommand['action']}
 	 */
 	action() {
-		this.editor._preventBlur = true;
+		this.$.store.set('_preventBlur', true);
 		this.input.click();
 	}
 
 	/**
-	 * @editorMethod Editor.Component
-	 * @description Executes the method that is called when a component of a plugin is selected.
-	 * @param {HTMLElement} target Target component element
-	 */
-	select(target) {
-		this._element = target;
-		const asBtn = this.figure.controller.form.querySelector('[data-command="__c__as"]');
-		if (dom.check.isFigure(target.parentElement)) {
-			asBtn.innerHTML = this.icons.reduction + dom.utils.createTooltipInner(this.lang.asLink);
-			asBtn.setAttribute('data-value', 'link');
-			this.figure.open(target, { nonResizing: true, nonSizeInfo: true, nonBorder: true, figureTarget: true, __fileManagerInfo: false });
-		} else {
-			asBtn.innerHTML = this.icons.expansion + dom.utils.createTooltipInner(this.lang.asBlock);
-			asBtn.setAttribute('data-value', 'box');
-			this.figure.controllerOpen(target, { isWWTarget: true });
-			return true;
-		}
-	}
-
-	/**
-	 * @editorMethod Editor.EventManager
-	 * @description Executes the event function of "paste" or "drop".
-	 * @param {Object} params { frameContext, event, file }
-	 * @param {__se__FrameContext} params.frameContext Frame context
-	 * @param {ClipboardEvent} params.event Event object
-	 * @param {File} params.file File object
-	 * @returns {boolean} - If return false, the file upload will be canceled
+	 * @hook Editor.EventManager
+	 * @type {SunEditor.Hook.Event.OnFilePasteAndDrop}
 	 */
 	onFilePasteAndDrop({ file }) {
 		const fileType = file.type;
 		if (
-			!this._acceptedCheck.some((format) => {
+			!this.#acceptedCheck.some((format) => {
 				if (format.startsWith('*')) return true;
 				if (format.startsWith(fileType)) return true;
 			})
@@ -152,27 +139,12 @@ class FileUpload extends EditorInjector {
 		}
 
 		this.submitFile([file]);
-		this.editor.focus();
-
-		return false;
+		this.$.focusManager.focus();
 	}
 
 	/**
-	 * @editorMethod Modules.Controller
-	 * @description Executes the method that is called when a target component is edited.
-	 * @param {HTMLElement|Text} target Target element
-	 */
-	edit(target) {
-		this.editInput.value = target.textContent;
-		this.figure.controllerHide();
-		this.controller.open(target, null, { isWWTarget: !dom.check.isFigure(target.parentElement), initMethod: null, addOffset: null });
-		this.editInput.focus();
-	}
-
-	/**
-	 * @editorMethod Modules.Controller
-	 * @description Executes the method that is called when a button is clicked in the "controller".
-	 * @param {HTMLButtonElement} target Target button element
+	 * @hook Modules.Controller
+	 * @type {SunEditor.Hook.Controller.Action}
 	 */
 	controllerAction(target) {
 		const command = target.getAttribute('data-command');
@@ -180,39 +152,70 @@ class FileUpload extends EditorInjector {
 
 		if (command === 'edit') {
 			if (this.editInput.value.trim().length === 0) return;
-			this._element.textContent = this.editInput.value;
+			this.#element.textContent = this.editInput.value;
 		}
 
 		this.controller.close();
-		this.component.select(this._element, FileUpload.key);
+		this.$.component.select(this.#element, FileUpload.key);
 	}
 
 	/**
-	 * @editorMethod Editor.Component
-	 * @description Method to delete a component of a plugin, called by the "FileManager", "Controller" module.
-	 * @param {HTMLElement} target Target element
-	 * @returns {Promise<void>}
+	 * @hook Editor.Component
+	 * @type {SunEditor.Hook.Component.Select}
+	 */
+	componentSelect(target) {
+		this.#element = target;
+
+		const asBtn = this.figure.controller.form.querySelector('[data-command="__c__as"]');
+		if (!asBtn) return;
+
+		if (dom.check.isFigure(target.parentElement)) {
+			asBtn.innerHTML = this.$.icons.reduction + dom.utils.createTooltipInner(this.$.lang.asLink);
+			asBtn.setAttribute('data-value', 'link');
+			this.figure.open(target, { nonResizing: true, nonSizeInfo: true, nonBorder: true, figureTarget: true, infoOnly: false });
+		} else {
+			asBtn.innerHTML = this.$.icons.expansion + dom.utils.createTooltipInner(this.$.lang.asBlock);
+			asBtn.setAttribute('data-value', 'box');
+			this.figure.controllerOpen(target, { isWWTarget: true });
+			return true;
+		}
+	}
+
+	/**
+	 * @hook Editor.Component
+	 * @type {SunEditor.Hook.Component.Edit}
+	 */
+	componentEdit(target) {
+		this.editInput.value = target.textContent;
+		this.figure.controllerHide();
+		this.controller.open(target, null, { isWWTarget: !dom.check.isFigure(target.parentElement), initMethod: null, addOffset: null });
+		this.editInput.focus();
+	}
+
+	/**
+	 * @hook Editor.Component
+	 * @type {SunEditor.Hook.Component.Destroy}
 	 */
-	async destroy(target) {
+	async componentDestroy(target) {
 		if (!target) return;
 
 		const figure = Figure.GetContainer(target);
 		const containerTarget = dom.query.getParentElement(target, '.se-component') || target;
 
-		const message = await this.triggerEvent('onFileDeleteBefore', { element: figure.target, container: figure, url: figure.target.getAttribute('href') });
+		const message = await this.$.eventManager.triggerEvent('onFileDeleteBefore', { element: figure.target, container: figure, url: figure.target.getAttribute('href') });
 		if (message === false) return;
 
-		const isInlineComp = this.component.isInline(containerTarget);
+		const isInlineComp = this.$.component.isInline(containerTarget);
 		const focusEl = isInlineComp ? containerTarget.previousSibling || containerTarget.nextSibling : containerTarget.previousElementSibling || containerTarget.nextElementSibling;
 		dom.utils.removeItem(containerTarget);
-		this.ui._offCurrentController();
+		this.$.ui.offCurrentController();
 
-		this.editor.focusEdge(focusEl);
-		this.history.push(false);
+		this.$.focusManager.focusEdge(focusEl);
+		this.$.history.push(false);
 	}
 
 	/**
-	 * @description Create an "file" component using the provided files.
+	 * @description Create a `file` component using the provided files.
 	 * @param {File[]|FileList} fileList File object list
 	 * @returns {Promise<boolean>} If return false, the file upload will be canceled
 	 */
@@ -225,16 +228,16 @@ class FileUpload extends EditorInjector {
 		for (let i = 0, len = fileList.length, f, s; i < len; i++) {
 			f = fileList[i];
 			s = f.size;
-			if (slngleSizeLimit && slngleSizeLimit > s) {
+			if (slngleSizeLimit > 0 && s > slngleSizeLimit) {
 				const err = '[SUNEDITOR.fileUpload.fail] Size of uploadable single file: ' + slngleSizeLimit / 1000 + 'KB';
-				const message = await this.triggerEvent('onFileUploadError', {
+				const message = await this.$.eventManager.triggerEvent('onFileUploadError', {
 					error: err,
 					limitSize: slngleSizeLimit,
 					uploadSize: s,
-					file: f
+					file: f,
 				});
 
-				this.ui.alertOpen(message === NO_EVENT ? err : message || err, 'error');
+				this.$.ui.alertOpen(message === NO_EVENT ? err : message || err, 'error');
 
 				return false;
 			}
@@ -247,14 +250,14 @@ class FileUpload extends EditorInjector {
 		const currentSize = this.fileManager.getSize();
 		if (limitSize > 0 && fileSize + currentSize > limitSize) {
 			const err = '[SUNEDITOR.fileUpload.fail] Size of uploadable total files: ' + limitSize / 1000 + 'KB';
-			const message = await this.triggerEvent('onFileUploadError', {
+			const message = await this.$.eventManager.triggerEvent('onFileUploadError', {
 				error: err,
 				limitSize,
 				currentSize,
-				uploadSize: fileSize
+				uploadSize: fileSize,
 			});
 
-			this.ui.alertOpen(message === NO_EVENT ? err : message || err, 'error');
+			this.$.ui.alertOpen(message === NO_EVENT ? err : message || err, 'error');
 
 			return false;
 		}
@@ -262,18 +265,18 @@ class FileUpload extends EditorInjector {
 		const fileInfo = {
 			url: this.uploadUrl,
 			uploadHeaders: this.uploadHeaders,
-			files
+			files,
 		};
 
 		const handler = async function (uploadCallback, infos, newInfos) {
 			infos = newInfos || infos;
 			const xmlHttp = await this.fileManager.asyncUpload(infos.url, infos.uploadHeaders, infos.files);
 			uploadCallback(xmlHttp);
-		}.bind(this, this.#_uploadCallBack.bind(this), fileInfo);
+		}.bind(this, this.#uploadCallBack.bind(this), fileInfo);
 
-		const result = await this.triggerEvent('onFileUploadBefore', {
+		const result = await this.$.eventManager.triggerEvent('onFileUploadBefore', {
 			info: fileInfo,
-			handler
+			handler,
 		});
 
 		if (result === undefined) return true;
@@ -284,9 +287,9 @@ class FileUpload extends EditorInjector {
 	}
 
 	/**
-	 * @description Convert format to link or block
+	 * @description Convert format to `link` or `block`
 	 * @param {HTMLElement} target Target element
-	 * @param {string} value 'link' or 'block'
+	 * @param {string} value `link` or `block`
 	 */
 	convertFormat(target, value) {
 		if (value === 'link') {
@@ -299,14 +302,14 @@ class FileUpload extends EditorInjector {
 			target.setAttribute('contenteditable', 'false');
 			dom.utils.addClass(target, 'se-component|se-inline-component');
 
-			const line = dom.utils.createElement(this.options.get('defaultLine'), null, target);
+			const line = dom.utils.createElement(this.$.options.get('defaultLine'), null, target);
 			parent.insertBefore(line, next);
 			dom.utils.removeItem(container);
 		} else {
 			// block
-			this.selection.setRange(target, 0, target, 1);
-			const r = this.html.remove();
-			const s = this.nodeTransform.split(r.container, r.offset, 0);
+			this.$.selection.setRange(target, 0, target, 1);
+			const r = this.$.html.remove();
+			const s = this.$.nodeTransform.split(r.container, r.offset, 0);
 
 			if (s?.previousElementSibling && dom.check.isZeroWidth(s.previousElementSibling)) {
 				dom.utils.removeItem(s.previousElementSibling);
@@ -320,15 +323,15 @@ class FileUpload extends EditorInjector {
 			(s || r.container).parentElement.insertBefore(figure.container, s);
 		}
 
-		this.history.push(false);
-		this.component.select(target, FileUpload.key);
+		this.$.history.push(false);
+		this.$.component.select(target, FileUpload.key);
 	}
 
 	/**
 	 * @description Create file element
 	 * @param {string} url File URL
 	 * @param {File|{name: string, size: number}} file File object
-	 * @param {boolean} isLast Is last file
+	 * @param {boolean} isLast Indicates whether this is the last file in the batch (used for scroll and insert actions).
 	 */
 	create(url, file, isLast) {
 		const name = file.name || url;
@@ -341,68 +344,66 @@ class FileUpload extends EditorInjector {
 				'data-se-file-download': '',
 				contenteditable: 'false',
 				'data-se-non-focus': 'true',
-				'data-se-non-link': 'true'
+				'data-se-non-link': 'true',
 			},
-			name
+			name,
 		);
 
 		this.fileManager.setFileData(a, file);
 
 		if (this.as === 'link') {
 			a.className = 'se-component se-inline-component';
-			this.component.insert(a, { skipCharCount: false, skipSelection: false, skipHistory: false });
+			this.$.component.insert(a, { scrollTo: isLast ? true : false, insertBehavior: isLast ? this.insertBehavior : null });
 			return;
 		}
 
 		const figure = Figure.CreateContainer(a);
 		dom.utils.addClass(figure.container, 'se-file-figure|se-flex-component');
 
-		if (!this.component.insert(figure.container, { skipCharCount: false, skipSelection: isLast ? !this.options.get('componentAutoSelect') : true, skipHistory: false })) {
-			this.editor.focus();
+		if (!this.$.component.insert(figure.container, { scrollTo: isLast ? true : false, insertBehavior: isLast ? this.insertBehavior : null })) {
+			this.$.focusManager.focus();
 			return;
 		}
 
 		if (!isLast) return;
 
-		if (!this.options.get('componentAutoSelect')) {
-			const line = this.format.addLine(figure.container, null);
-			if (line) this.selection.setRange(line, 0, line, 0);
+		if (!this.$.options.get('componentInsertBehavior')) {
+			const line = this.$.format.addLine(figure.container, null);
+			if (line) this.$.selection.setRange(line, 0, line, 0);
 		} else {
-			this.component.select(a, FileUpload.key);
+			this.$.component.select(a, FileUpload.key);
 		}
 	}
 
 	/**
-	 * @private
 	 * @description Processes the server response after file upload.
 	 * - Registers the uploaded files in the editor.
 	 * @param {Object<string, *>} response - The response object from the server.
 	 */
-	_register(response) {
+	#register(response) {
 		response.result.forEach((file, i, a) => {
 			this.create(
 				file.url,
 				{
 					name: file.name,
-					size: file.size
+					size: file.size,
 				},
-				i === a.length - 1
+				i === a.length - 1,
 			);
 		});
 	}
 
 	/**
-	 * @private
 	 * @description Handles file upload errors.
 	 * - Displays an error message if the upload fails.
 	 * @param {Object<string, *>} response - The error response from the server.
 	 * @returns {Promise<void>}
 	 */
-	async _error(response) {
-		const message = await this.triggerEvent('onFileUploadError', { error: response });
+	async #error(response) {
+		const message = await this.$.eventManager.triggerEvent('onFileUploadError', { error: response });
 		if (message === false) return;
 		const err = message === NO_EVENT ? response.errorMessage : message || response.errorMessage;
-		this.ui.alertOpen(err, 'error');
+		this.$.ui.alertOpen(err, 'error');
 		console.error('[SUNEDITOR.plugin.fileUpload.error]', err);
 	}
 
@@ -411,12 +412,12 @@ class FileUpload extends EditorInjector {
 	 * - Parses the response and registers the uploaded file.
 	 * @param {XMLHttpRequest} xmlHttp - The completed XHR request.
 	 */
-	#_uploadCallBack(xmlHttp) {
+	#uploadCallBack(xmlHttp) {
 		const response = JSON.parse(xmlHttp.responseText);
 		if (response.errorMessage) {
-			this._error(response);
+			this.#error(response);
 		} else {
-			this._register(response);
+			this.#register(response);
 		}
 	}
 
@@ -432,6 +433,10 @@ class FileUpload extends EditorInjector {
 	}
 }
 
+/**
+ * @param {SunEditor.Deps} $ - Kernel dependencies
+ * @returns {HTMLElement}
+ */
 function CreateHTML_controller({ lang, icons }) {
 	const html = /*html*/ `
 		<div class="se-arrow se-arrow-up"></div>