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

package/src/modules/FileManager.js

@@ -2,44 +2,79 @@ import CoreInjector from '../editorInjector/_core';
 import ApiManager from './ApiManager';
 
 /**
- *
- * @param {*} inst
- * @param {{ query: string, loadHandler: Function, eventHandler: Function, figure: Figure instance | null }} params
+ * @typedef {Object} FileStateInfo
+ * @property {string} src File source
+ * @property {number} index File index
+ * @property {string} name File name
+ * @property {number} size File size
  */
-const FileManager = function (inst, params) {
-	CoreInjector.call(this, inst.editor);
-
-	// members
-	inst.__fileManagement = this;
-	this.kind = inst.constructor.key || inst.constructor.name;
-	this.inst = inst;
-	this.component = inst.editor.component;
-	this.query = params.query;
-	this.loadHandler = params.loadHandler;
-	this.eventHandler = params.eventHandler;
-	this.infoList = [];
-	this.infoIndex = 0;
-	this.uploadFileLength = 0;
-	this.__updateTags = [];
-	// api manager
-	this.apiManager = new ApiManager(this, null);
-};
-
-FileManager.prototype = {
+
+/**
+ * @typedef {Object} FileStateParams
+ * @property {__se__EditorCore} editor - The root editor instance
+ * @property {Node} element File element
+ * @property {number} index File index
+ * @property {string} state File state ("create"|"update"|"delete")
+ * @property {FileStateInfo} info File information
+ * @property {number} remainingFilesCount Remaining file count
+ * @property {string} pluginName Plugin name
+ */
+
+/**
+ * @typedef {Object} FileManagerParams
+ * @property {string} query The query selector used to find file elements in the editor
+ * @property {(params: Array<FileStateInfo>) => void=} loadHandler A function to handle the loaded file information
+ * @property {(info: FileStateParams) => void=} eventHandler A function to handle file-related events
+ */
+
+/**
+ * @class
+ * @description This module manages the file information of the editor.
+ */
+class FileManager extends CoreInjector {
+	/**
+	 * @constructor
+	 * @param {*} inst The instance object that called the constructor.
+	 * @param {FileManagerParams} params FileManager options
+	 */
+	constructor(inst, params) {
+		super(inst.editor);
+		this.ui = this.editor.ui;
+
+		// members
+		inst.__fileManagement = this;
+		this.kind = inst.constructor.key || inst.constructor.name;
+		this.inst = inst;
+		this.component = inst.editor.component;
+		this.query = params.query;
+		this.loadHandler = params.loadHandler;
+		this.eventHandler = params.eventHandler;
+		this.infoList = [];
+		this.infoIndex = 0;
+		this.uploadFileLength = 0;
+		this.__updateTags = [];
+		// api manager
+		this.apiManager = new ApiManager(this, null);
+
+		// se-ts-ignore - call by editor
+		void this._resetInfo;
+		void this._checkInfo;
+	}
+
 	/**
 	 * @description Upload the file to the server.
 	 * @param {string} uploadUrl Upload server url
-	 * @param {Object|null} uploadHeader Request header
-	 * @param {Files|{FormData, size}} data FormData in body or Files array
-	 * @param {Function|null} callBack Success call back function
-	 * @param {Function|null} errorCallBack Error call back function
+	 * @param {?Object<string, string>} uploadHeader Request header
+	 * @param {FileList|File[]|{formData: FormData, size: number}} data FormData in body or Files array
+	 * @param {?(xmlHttp: XMLHttpRequest) => boolean=} callBack Success call back function
+	 * @param {?(res: *, xmlHttp: XMLHttpRequest) => string=} errorCallBack Error call back function
 	 */
 	upload(uploadUrl, uploadHeader, data, callBack, errorCallBack) {
-		this.editor.showLoading();
+		this.ui.showLoading();
 
 		let formData = null;
 		// create formData
-		if (data.length) {
+		if ('length' in data) {
 			formData = new FormData();
 			for (let i = 0, len = data.length; i < len; i++) {
 				formData.append('file-' + i, data[i]);
@@ -51,20 +86,21 @@ FileManager.prototype = {
 		}
 
 		this.apiManager.call({ method: 'POST', url: uploadUrl, headers: uploadHeader, data: formData, callBack, errorCallBack });
-	},
+	}
 
 	/**
 	 * @description Upload the file to the server.
 	 * @param {string} uploadUrl Upload server url
-	 * @param {Object|null} uploadHeader Request header
-	 * @param {Files|{FormData, size}} data FormData in body or Files array
+	 * @param {?Object<string, string>} uploadHeader Request header
+	 * @param {FileList|File[]|{formData: FormData, size: number}} data FormData in body or Files array
+	 * @returns {Promise<XMLHttpRequest>}
 	 */
 	async asyncUpload(uploadUrl, uploadHeader, data) {
-		this.editor.showLoading();
+		this.ui.showLoading();
 
 		let formData = null;
 		// create formData
-		if (data.length) {
+		if ('length' in data) {
 			formData = new FormData();
 			for (let i = 0, len = data.length; i < len; i++) {
 				formData.append('file-' + i, data[i]);
@@ -76,44 +112,52 @@ FileManager.prototype = {
 		}
 
 		return await this.apiManager.asyncCall({ method: 'POST', url: uploadUrl, headers: uploadHeader, data: formData });
-	},
+	}
 
+	/**
+	 * @description Set the file information to the element.
+	 * @param {Node} element File information element
+	 * @param {Object} params
+	 * @param {string} params.name File name
+	 * @param {number} params.size File size
+	 * @returns
+	 */
 	setFileData(element, { name, size }) {
 		if (!element) return;
-		element.setAttribute('data-se-file-name', name);
-		element.setAttribute('data-se-file-size', size);
-	},
+		/** @type {Element} */ (element).setAttribute('data-se-file-name', name);
+		/** @type {Element} */ (element).setAttribute('data-se-file-size', size + '');
+	}
 
 	/**
-	 * @description Create info object of file and add it to "infoList"
 	 * @private
-	 * @param {Element} element
-	 * @param {Object|null} file
+	 * @description Create info object of file and add it to "infoList"
+	 * @param {HTMLMediaElement} element
+	 * @param {{name: string, size: number}|null} file File information
 	 */
 	_setInfo(element, file) {
-		let dataIndex = GetAttr(element, 'index');
+		let dataIndex = Number(GetAttr(element, 'index'));
 		let info = null;
 		let state = '';
 
 		if (!file) {
 			file = {
 				name: GetAttr(element, 'file-name') || (typeof element.src === 'string' ? element.src.split('/').pop() : ''),
-				size: GetAttr(element, 'file-size') || 0
+				size: Number(GetAttr(element, 'file-size')) || 0
 			};
 		}
 
 		// create
-		if (!dataIndex || this._componentsInfoInit) {
+		if (!dataIndex || this.editor._componentsInfoInit) {
 			state = 'create';
 			dataIndex = this.infoIndex++;
 
-			element.setAttribute('data-se-index', dataIndex);
+			element.setAttribute('data-se-index', dataIndex + '');
 			element.setAttribute('data-se-file-name', file.name);
-			element.setAttribute('data-se-file-size', file.size);
+			element.setAttribute('data-se-file-size', file.size + '');
 
 			info = {
 				src: element.src,
-				index: dataIndex * 1,
+				index: dataIndex,
 				name: file.name,
 				size: file.size
 			};
@@ -141,31 +185,35 @@ FileManager.prototype = {
 
 			info.src = element.src;
 			info.name = GetAttr(element, 'file-name');
-			info.size = GetAttr(element, 'file-size') * 1;
+			info.size = Number(GetAttr(element, 'file-size'));
 		}
 
 		// method bind
 		info.element = element;
+
 		info.delete = function (el) {
 			if (typeof this.inst.destroy === 'function') this.inst.destroy.call(this.inst, el);
-			this._deleteInfo(GetAttr(el, 'index') * 1);
+			this._deleteInfo(Number(GetAttr(el, 'index')));
 		}.bind(this, element);
+		// se-ts-ignore
+		void this._deleteInfo;
+
 		info.select = function (el) {
 			el.scrollIntoView(this.options.get('componentScrollToOptions'));
 			const comp = this.component.get(el);
 			if (comp) {
-				this.component.select(comp.target, comp.pluginName, false);
+				this.component.select(comp.target, comp.pluginName);
 			} else if (typeof this.inst.select === 'function') {
 				this.inst.select(el);
 			}
 		}.bind(this, element);
 
-		const params = { editor: this.editor, element, index: dataIndex, state, info, remainingFilesCount: --this.uploadFileLength < 0 ? 0 : this.uploadFileLength };
+		const params = { editor: this.editor, element, index: dataIndex, state, info, remainingFilesCount: --this.uploadFileLength < 0 ? 0 : this.uploadFileLength, pluginName: this.kind };
 		if (typeof this.eventHandler === 'function') {
 			this.eventHandler(params);
 		}
 		this.triggerEvent('onFileManagerAction', { ...params, pluginName: this.kind });
-	},
+	}
 
 	/**
 	 * @description Gets the sum of the sizes of the currently saved files.
@@ -177,18 +225,19 @@ FileManager.prototype = {
 			size += this.infoList[i].size * 1;
 		}
 		return size;
-	},
+	}
 
 	/**
-	 * @description Checke the file's information and modify the tag that does not fit the format.
 	 * @private
+	 * @description Checke the file's information and modify the tag that does not fit the format.
+	 * @param {boolean} loaded Whether the editor is loaded
 	 */
 	_checkInfo(loaded) {
 		const tags = [].slice.call(this.editor.frameContext.get('wysiwyg').querySelectorAll(this.query));
 		const infoList = this.infoList;
 		if (tags.length === infoList.length) {
 			// reset
-			if (this._componentsInfoReset) {
+			if (this.editor._componentsInfoReset) {
 				for (let i = 0, len = tags.length; i < len; i++) {
 					this._setInfo(tags[i], null);
 				}
@@ -222,12 +271,12 @@ FileManager.prototype = {
 
 		while (tags.length > 0) {
 			const tag = tags.shift();
-			if (!GetAttr(tag, 'index') || !infoIndex.includes(GetAttr(tag, 'index') * 1)) {
+			if (!GetAttr(tag, 'index') || !infoIndex.includes(Number(GetAttr(tag, 'index')))) {
 				currentTags.push(this.infoIndex);
 				tag.removeAttribute('data-se-index');
 				this._setInfo(tag, null);
 			} else {
-				currentTags.push(GetAttr(tag, 'index') * 1);
+				currentTags.push(Number(GetAttr(tag, 'index')));
 			}
 		}
 
@@ -243,7 +292,7 @@ FileManager.prototype = {
 
 			infoList.splice(i, 1);
 
-			const params = { editor: this.editor, element: null, index: dataIndex, state: 'delete', info: null, remainingFilesCount: 0 };
+			const params = { editor: this.editor, element: null, index: dataIndex, state: 'delete', info: null, remainingFilesCount: 0, pluginName: this.kind };
 			if (typeof this.eventHandler === 'function') {
 				this.eventHandler(params);
 			}
@@ -251,16 +300,15 @@ FileManager.prototype = {
 
 			i--;
 		}
-	},
+	}
 
 	/**
-	 * @description Reset info object and "infoList = []", "infoIndex = 0"
-	 * @param {string} this.kind Plugin name
 	 * @private
+	 * @description Reset info object and "infoList = []", "infoIndex = 0"
 	 */
 	_resetInfo() {
 		const eh = typeof this.eventHandler === 'function';
-		const params = { editor: this.editor, element: null, state: 'delete', info: null, remainingFilesCount: 0 };
+		const params = { editor: this.editor, element: null, state: 'delete', info: null, remainingFilesCount: 0, pluginName: this.kind };
 		for (let i = 0, len = this.infoList.length; i < len; i++) {
 			if (eh) this.eventHandler({ ...params, index: this.infoList[i].index, pluginName: this.kind });
 			this.triggerEvent('onFileManagerAction', { ...params, index: this.infoList[i].index, pluginName: this.kind });
@@ -268,12 +316,12 @@ FileManager.prototype = {
 
 		this.infoList = [];
 		this.infoIndex = 0;
-	},
+	}
 
 	/**
+	 * @private
 	 * @description Delete info object at "infoList"
 	 * @param {number} index index of info object infoList[].index)
-	 * @private
 	 */
 	_deleteInfo(index) {
 		if (index >= 0) {
@@ -281,17 +329,21 @@ FileManager.prototype = {
 				if (index === this.infoList[i].index) {
 					this.infoList.splice(i, 1);
 					if (typeof this.eventHandler === 'function') {
-						this.eventHandler({ editor: this.editor, element: null, index, state: 'delete', info: null, remainingFilesCount: 0 });
+						this.eventHandler({ editor: this.editor, element: null, index, state: 'delete', info: null, remainingFilesCount: 0, pluginName: this.kind });
 					}
 					return;
 				}
 			}
 		}
-	},
-
-	constructor: FileManager
-};
+	}
+}
 
+/**
+ * @private
+ * @param {Element} element - Element
+ * @param {string} name - Attribute name
+ * @returns {string|null}
+ */
 function GetAttr(element, name) {
 	const seAttr = element.getAttribute(`data-se-${name}`);
 	if (seAttr) return seAttr;

package/src/modules/HueSlider.js

@@ -1,4 +1,8 @@
-import { domUtils, env } from '../helper';
+/**
+ * @fileoverview Implements HueSlider.
+ */
+
+import { dom, env } from '../helper';
 import Controller from './Controller';
 
 const { isMobile } = env;
@@ -41,9 +45,9 @@ function CreateSliderCtx() {
 	</div>
 	`;
 
-	const slider = domUtils.createElement('DIV', { class: 'se-hue-slider' }, html);
-	const wheelCanvas = slider.querySelector('.se-hue-wheel');
-	const gradientBarCanvas = slider.querySelector('.se-hue-gradient');
+	const slider = dom.utils.createElement('DIV', { class: 'se-hue-slider' }, html);
+	const wheelCanvas = /** @type {HTMLCanvasElement} */ (slider.querySelector('.se-hue-wheel'));
+	const gradientBarCanvas = /** @type {HTMLCanvasElement} */ (slider.querySelector('.se-hue-gradient'));
 	const currentColors = slider.querySelector('.se-hue-final-hex').children;
 
 	return {
@@ -52,71 +56,110 @@ function CreateSliderCtx() {
 		offscreenCtx: offscreenCanvas.getContext('2d'),
 		wheel: wheelCanvas,
 		wheelCtx: wheelCanvas.getContext('2d'),
-		wheelPointer: slider.querySelector('.se-hue-wheel-pointer'),
+		wheelPointer: /** @type {HTMLElement} */ (slider.querySelector('.se-hue-wheel-pointer')),
 		gradientBar: gradientBarCanvas,
-		gradientPointer: slider.querySelector('.se-hue-gradient-pointer'),
-		fanalColorHex: currentColors[0],
-		fanalColorBackground: currentColors[1]
+		gradientPointer: /** @type {HTMLElement} */ (slider.querySelector('.se-hue-gradient-pointer')),
+		fanalColorHex: /** @type {HTMLElement} */ (currentColors[0]),
+		fanalColorBackground: /** @type {HTMLElement} */ (currentColors[1])
 	};
 }
 
 /**
+ * @typedef {import('../modules/Controller').ControllerParams} ControllerParams_hueSlider
+ */
+
+/**
+ * @typedef {Object} HueSliderColor
+ * @property {string} hex - HEX color
+ * @property {number} r - Red color value
+ * @property {number} g - Green color value
+ * @property {number} b - Blue color value
+ * @property {number} h - Hue color value
+ * @property {number} s - Saturation color value
+ * @property {number} l - Lightness color value
+ */
+
+/**
+ * @typedef {Object} HueSliderParams
+ * @property {Node} [form] The form element to attach the hue slider.
+ * @property {boolean} [isNewForm] Whether to create a new form element.
+ * @property {ControllerParams_hueSlider} [controllerOptions] Controller options
+ */
+
+/**
+ * @class
  * @description Create a Hue slider. (only create one at a time)
- * When you call the .attach() method, the hue slider is appended to the form element.
+ * - When you call the .attach() method, the hue slider is appended to the form element.
  * It must be called every time it is used.
- * @param {{form: Element}} params {form: Element}
  */
-const HueSlider = function (inst, params, className) {
-	if (!params) params = {};
-
-	this.editor = inst.editor;
-	this.eventManager = inst.eventManager;
-	this.inst = inst;
-
-	// members
-	this.form = params.form;
-	this.ctx = {
-		wheelX: wheelX,
-		wheelY: wheelY,
-		lightness: LIGHTNESS,
-		wheelPointerX: '50%',
-		wheelPointerY: '50%',
-		gradientPointerX: 'calc(100% - 14px)',
-		color: DEFAULT_COLOR_VALUE
-	};
-	this.isOpen = false;
-	this.controlle = null;
-	this.__globalMouseDown = null;
-	this.__globalMouseMove = null;
-	this.__globalMouseUp = null;
-
-	// init default controller
-	if (!params.isNewForm) {
-		const hueController = CreateHTML_basicControllerForm(inst.editor, className);
-		this.form = hueController.querySelector('.se-hue');
-		this.controller = new Controller(this, hueController, { position: 'top', isWWTarget: false, ...params.controllerOptions });
-
-		// buttons
-		this.eventManager.addEvent(hueController.querySelector('.se-btn-success'), 'click', () => {
-			inst.hueSliderAction(this.get());
-			this.close();
-		});
-		this.eventManager.addEvent(hueController.querySelector('.se-btn-danger'), 'click', () => {
-			this.close();
-		});
+class HueSlider {
+	/**
+	 * @constructor
+	 * @param {*} inst The instance object that called the constructor.
+	 * @param {HueSliderParams} [params={}] Hue slider options
+	 * @param {string} [className=""] The class name of the hue slider.
+	 */
+	constructor(inst, params, className) {
+		if (!params) params = {};
+
+		this.editor = inst.editor;
+		this.eventManager = inst.eventManager;
+		this.inst = inst;
+
+		// members
+		this.form = params.form;
+		this.ctx = {
+			wheelX: wheelX,
+			wheelY: wheelY,
+			lightness: LIGHTNESS,
+			wheelPointerX: '50%',
+			wheelPointerY: '50%',
+			gradientPointerX: 'calc(100% - 14px)',
+			color: DEFAULT_COLOR_VALUE
+		};
+		this.isOpen = false;
+		this.controlle = null;
+		this.__globalMouseDown = null;
+		this.__globalMouseMove = null;
+		this.__globalMouseUp = null;
+
+		// init default controller
+		if (!params.isNewForm) {
+			const hueController = CreateHTML_basicControllerForm(inst.editor, className);
+			this.form = hueController.querySelector('.se-hue');
+			this.controller = new Controller(this, hueController, { position: 'top', isWWTarget: false, ...params.controllerOptions });
+
+			// buttons
+			this.eventManager.addEvent(hueController.querySelector('.se-btn-success'), 'click', () => {
+				inst.hueSliderAction(this.get());
+				this.close();
+			});
+			this.eventManager.addEvent(hueController.querySelector('.se-btn-danger'), 'click', () => {
+				this.close();
+			});
+		}
 	}
-};
 
-HueSlider.prototype = {
+	/**
+	 * @description Get the current color information.
+	 * @returns {HueSliderColor} color information
+	 */
 	get() {
 		return finalColor;
-	},
+	}
 
+	/**
+	 * @description Open the hue slider.
+	 * @param {Node} target The element to attach the hue slider.
+	 */
 	open(target) {
 		this.attach();
 		this.controller.open(target, null, { isWWTarget: false, initMethod: null, addOffset: null });
-	},
+	}
 
+	/**
+	 * @description Reset information and close the hue slider.
+	 */
 	off() {
 		this.ctx = {
 			gradientPointerX: gradientPointer.style.left,
@@ -130,13 +173,21 @@ HueSlider.prototype = {
 
 		this.controller.close();
 		this.init();
-	},
+	}
 
+	/**
+	 * @description Close the hue slider. (include off method)
+	 * - Call the instance's hueSliderCancelAction method.
+	 */
 	close() {
 		this.off();
 		this.inst.hueSliderCancelAction();
-	},
+	}
 
+	/**
+	 * @description Attach the hue slider to the form element.
+	 * @param {?Node=} form The element to attach the hue slider.
+	 */
 	attach(form) {
 		// drow
 		this.init();
@@ -176,12 +227,15 @@ HueSlider.prototype = {
 			moveEvent.func = OnTouchmove;
 		}
 
-		this.__globalMouseDown = this.eventManager.addGlobalEvent(downEvent.name, downEvent.func, { passive: false, useCapture: true });
+		this.__globalMouseDown = this.eventManager.addGlobalEvent(downEvent.name, downEvent.func, { passive: false, capture: true });
 		this.__globalMouseMove = this.eventManager.addGlobalEvent(moveEvent.name, moveEvent.func, true);
 		this.__globalMouseUp = this.eventManager.addGlobalEvent(upEvent.name, upEvent.func, true);
 		this.isOpen = true;
-	},
+	}
 
+	/**
+	 * @description Initialize the hue slider information.
+	 */
 	init() {
 		this.isOpen = false;
 		isWheelragging = false;
@@ -189,10 +243,8 @@ HueSlider.prototype = {
 		if (this.__globalMouseDown) this.__globalMouseDown = this.eventManager.removeGlobalEvent(this.__globalMouseDown);
 		if (this.__globalMouseMove) this.__globalMouseMove = this.eventManager.removeGlobalEvent(this.__globalMouseMove);
 		if (this.__globalMouseUp) this.__globalMouseUp = this.eventManager.removeGlobalEvent(this.__globalMouseUp);
-	},
-
-	constructor: HueSlider
-};
+	}
+}
 
 // init
 const { slider, offscreenCanvas, offscreenCtx, wheel, wheelCtx, wheelPointer, gradientBar, gradientPointer, fanalColorHex, fanalColorBackground } = CreateSliderCtx();
@@ -495,7 +547,7 @@ drawColorWheelToContext(offscreenCtx);
 drawColorWheel();
 
 function CreateHTML_basicControllerForm({ lang, icons }, className) {
-	const hueController = domUtils.createElement(
+	const hueController = dom.utils.createElement(
 		'DIV',
 		{ class: `se-controller ${className}` },
 		/*html*/ `