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

package/src/interfaces/contracts.js

@@ -0,0 +1,227 @@
+/**
+ * @fileoverview Contract interfaces for SunEditor plugins.
+ * These interfaces define callback methods that modules and editor core call on plugin instances.
+ * Use `@implements` to get type hints for these hooks in your plugin.
+ */
+
+// =====================================================================================================================================================
+// Modal Module Hooks
+// =====================================================================================================================================================
+
+/**
+ * Modal plugin hook methods interface.
+ * `modalAction` is required, other methods are optional.
+ * @interface
+ */
+export class ModuleModal {
+	/**
+	 * @abstract
+	 * This function is called when a form within a modal window is `submit`.
+	 * @returns {Promise<boolean>}
+	 * - `true`: modal and loading are closed
+	 * - `false`: only loading is closed
+	 * - `undefined`: only modal is closed
+	 */
+	async modalAction() {
+		return true;
+	}
+
+	/**
+	 * @optional
+	 * Executes the method that is called when a plugin's modal is opened.
+	 * @param {boolean} isUpdate - Indicates whether the modal is for editing an existing component (`true`) or registering a new one (`false`).
+	 * @returns {void}
+	 */
+	modalOn(isUpdate) {}
+
+	/**
+	 * @optional
+	 * This function is called before the modal window is opened, but before it is closed.
+	 * @returns {void}
+	 */
+	modalInit() {}
+
+	/**
+	 * @optional
+	 * Modal off callback.
+	 * @param {boolean} isUpdate - Indicates whether the modal is for editing an existing component (`true`) or registering a new one (`false`).
+	 * @returns {void}
+	 */
+	modalOff(isUpdate) {}
+
+	/**
+	 * @optional
+	 * Modal resize callback (optional).
+	 * @returns {void}
+	 */
+	modalResize() {}
+}
+
+// =====================================================================================================================================================
+// Controller Module Hooks
+// =====================================================================================================================================================
+
+/**
+ * Controller plugin hook methods interface.
+ * `controllerAction` is required, other methods are optional.
+ * @interface
+ */
+export class ModuleController {
+	/**
+	 * @abstract
+	 * Executes the method that is called when a button is clicked in the `controller`.
+	 * @param {HTMLButtonElement} target Action button element
+	 * @returns {void}
+	 */
+	controllerAction(target) {}
+
+	/**
+	 * @optional
+	 * This function is called after the `controller` is opened.
+	 * @param {HTMLFormElement} form Controller form element
+	 * @param {Node|Range} target Controller target element
+	 * @returns {void}
+	 */
+	controllerOn(form, target) {}
+
+	/**
+	 * @optional
+	 * This function is called before the `controller` is closed.
+	 * @returns {void}
+	 */
+	controllerClose() {}
+}
+
+// =====================================================================================================================================================
+// Browser Module Hooks
+// =====================================================================================================================================================
+
+/**
+ * Browser plugin hook methods interface.
+ * All methods are optional - implement only what you need.
+ * @interface
+ */
+export class ModuleBrowser {
+	/**
+	 * @optional
+	 * Executes the method that is called when a `Browser` module's is opened.
+	 * @returns {void}
+	 */
+	browserInit() {}
+}
+
+// =====================================================================================================================================================
+// ColorPicker Module Hooks
+// =====================================================================================================================================================
+
+/**
+ * ColorPicker plugin hook methods interface.
+ * All methods are optional - implement only what you need.
+ * @interface
+ */
+export class ModuleColorPicker {
+	/**
+	 * @optional
+	 * Executes the method called when a button of `ColorPicker` module is clicked.
+	 * - This plugin is by applying the `ColorPicker` module globally to the `dropdown` menu, the default `action` method is not called.
+	 * @param {SunEditor.Module.HueSlider.Color} color - Selected color information
+	 * @returns {void}
+	 */
+	colorPickerAction(color) {}
+
+	/**
+	 * @optional
+	 * Executes the method called when the `HueSlider` module is opened.
+	 * @returns {void}
+	 */
+	colorPickerHueSliderOpen() {}
+
+	/**
+	 * @optional
+	 * Executes the method called when the `HueSlider` module is closed.
+	 * @returns {void}
+	 */
+	colorPickerHueSliderClose() {}
+}
+
+// =====================================================================================================================================================
+// HueSlider Module Hooks
+// =====================================================================================================================================================
+
+/**
+ * HueSlider plugin hook methods interface.
+ * All methods are optional - implement only what you need.
+ * @interface
+ */
+export class ModuleHueSlider {
+	/**
+	 * @abstract
+	 * This method is called when the color is selected in the hue slider.
+	 * @returns {void}
+	 */
+	hueSliderAction() {}
+
+	/**
+	 * @optional
+	 * This method is called when the hue slider is closed.
+	 * @returns {void}
+	 */
+	hueSliderCancelAction() {}
+}
+
+// =====================================================================================================================================================
+// Editor Component Hooks
+// =====================================================================================================================================================
+
+/**
+ * Component plugin hook methods interface.
+ * `componentSelect` is required, other methods are optional.
+ *
+ * **`inst._element` Requirement:**
+ * Plugins with `static component` method must define a public `_element` property
+ * that references the currently controlled DOM element.
+ * - Used to detect clicks on the target element and prevent accidental `controller` closure.
+ *
+ * @interface
+ */
+export class EditorComponent {
+	/**
+	 * @abstract
+	 * Executes the method that is called when a component of a plugin is selected.
+	 * @param {HTMLElement} target - Target component element
+	 * @returns {void|boolean} - If return `true`, Special components that are not wrapping as `figure`
+	 */
+	componentSelect(target) {}
+
+	/**
+	 * @optional
+	 * Called when a container is deselected.
+	 * @param {HTMLElement} target - Target element
+	 * @returns {void}
+	 */
+	componentDeselect(target) {}
+
+	/**
+	 * @optional
+	 * Executes the method that is called when a component is being edited.
+	 * @param {HTMLElement} target - Target element
+	 * @returns {void}
+	 */
+	componentEdit(target) {}
+
+	/**
+	 * @optional
+	 * Method to delete a component of a plugin, called by the `FileManager`, `Controller` module.
+	 * @param {HTMLElement} target - Target element
+	 * @returns {Promise<void>}
+	 */
+	async componentDestroy(target) {}
+
+	/**
+	 * @optional
+	 * Executes the method that is called when a component copy is requested.
+	 * @param {SunEditor.HookParams.CopyComponent} params - Copy component event information
+	 * @returns {boolean|void} - If return `false`, the copy will be canceled
+	 */
+	componentCopy(params) {}
+}

package/src/interfaces/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Plugin hook interface exports for SunEditor.
+ * These types define plugin lifecycle hook methods.
+ */
+
+export * from './plugins';
+export * from './contracts';

package/src/interfaces/plugins.js

@@ -0,0 +1,239 @@
+/**
+ * @fileoverview Plugin interface definitions for SunEditor.
+ * These types define required methods for different plugin types.
+ */
+
+import KernelInjector from '../core/kernel/kernelInjector';
+
+/**
+ * @abstract
+ * Base class for all plugins - contains common properties
+ */
+class Base extends KernelInjector {
+	/** @type {string} - Plugin type (`browser`|`command`|`dropdown`|`field`|`input`|`modal`|`popup`) */
+	static type = '';
+
+	/** @type {string} - Unique plugin identifier */
+	static key = '';
+	/** @type {string} - CSS class name for the plugin button */
+	static className = '';
+
+	/**
+	 * Plugin-specific options
+	 * @type {{eventIndex?: number, isInputComponent?: boolean}}
+	 * @property {number} [eventIndex=0] - Plugin event handler execution priority (higher = later)
+	 * @property {boolean} [isInputComponent=false] - Allow keyboard input inside component (e.g., table cells), prevents auto-selection on arrow keys
+	 */
+	static options = {};
+
+	/**
+	 * @constructor
+	 * @param {SunEditor.Kernel} editor - The core kernel
+	 */
+	constructor(editor) {
+		super(editor);
+
+		// plugin basic properties
+		/** @type {string} */
+		this.title = '';
+		/** @type {string} */
+		this.icon = '';
+
+		/** @type {HTMLElement} */
+		this.beforeItem = null;
+		/** @type {HTMLElement} */
+		this.afterItem = null;
+		/** @type {HTMLElement} */
+		this.replaceButton = null;
+	}
+}
+
+// =====================================================================================================================================================
+
+/**
+ * @abstract
+ * @interface
+ * Base class for Browser plugins
+ * Child classes MUST implement open(), close(), and onSelectFile() methods
+ */
+export class PluginBrowser extends Base {
+	static type = 'browser';
+
+	/**
+	 * @abstract
+	 * @description Executes the method that is called when a `Browser` module's is opened.
+	 * @param {?(target: Node) => *} [onSelectfunction] - Method to be executed after selecting an item in the gallery
+	 * @returns {void}
+	 */
+	open(onSelectfunction) {
+		throw new Error(`[${this.constructor.name}] Abstract method 'open()' must be implemented`);
+	}
+
+	/**
+	 * @abstract
+	 * @description Executes the method that is called when a `Browser` module's is closed.
+	 * @returns {void}
+	 */
+	close() {
+		throw new Error(`[${this.constructor.name}] Abstract method 'close()' must be implemented`);
+	}
+}
+
+/**
+ * @abstract
+ * @interface
+ * Base class for Command plugins
+ * Child classes MUST implement the action() method
+ */
+export class PluginCommand extends Base {
+	static type = 'command';
+
+	/**
+	 * @abstract
+	 * @description Executes the main execution method of the plugin.
+	 * - It is executed by clicking a toolbar `command` button or calling an API.
+	 * - MUST be overridden by child classes
+	 * @param {HTMLElement} [target] - The plugin's toolbar button element
+	 * @returns {void | Promise<void>}
+	 */
+	action(target) {
+		throw new Error(`[${this.constructor.name}] Abstract method 'action()' must be implemented`);
+	}
+}
+
+/**
+ * @abstract
+ * @interface
+ * Base class for Dropdown plugins
+ * Child classes MUST implement the action() method
+ * Child classes MAY optionally implement on() and off() methods
+ */
+export class PluginDropdown extends Base {
+	static type = 'dropdown';
+
+	/**
+	 * @optional
+	 * @description Executes the method that is called when a plugin's dropdown menu is opened.
+	 * @param {HTMLElement} [target] - The dropdown target element
+	 * @returns {void}
+	 */
+	on(target) {}
+
+	/**
+	 * @abstract
+	 * @description Executes the main execution method of the plugin.
+	 * - Called when an item in the `dropdown` menu is clicked.
+	 * - MUST be overridden by child classes
+	 * @param {HTMLElement} target - The clicked dropdown item element
+	 * @returns {void | Promise<void>}
+	 */
+	action(target) {
+		throw new Error(`[${this.constructor.name}] Abstract method 'action()' must be implemented`);
+	}
+}
+
+/**
+ * @abstract
+ * @interface
+ * Base class for Dropdown-Free plugins
+ * These plugins handle their own event logic without automatic action() calls
+ * Typically used for complex UI components like ColorPicker or Table
+ * Child classes MAY optionally implement on() and off() methods
+ */
+export class PluginDropdownFree extends Base {
+	static type = 'dropdown-free';
+
+	/**
+	 * @optional
+	 * @description Executes the method that is called when a plugin's dropdown menu is opened.
+	 * @param {HTMLElement} [target] - The dropdown target element
+	 * @returns {void}
+	 */
+	on(target) {
+		void target;
+	}
+
+	/**
+	 * @optional
+	 * @description Executes the method that is called when a plugin's dropdown menu is closed.
+	 * @returns {void}
+	 */
+	off() {}
+}
+
+/**
+ * @abstract
+ * @interface
+ * Base class for Field plugins
+ * These plugins typically respond to input events in the wysiwyg area
+ *
+ * **Commonly used hooks:**
+ * - `onInput()` - Responds to input events in the editor (See: `mention` plugin)
+ * - Other event hooks can be used as needed (`onKeydown`, `onClick`, etc.)
+ *
+ * Child classes MAY optionally implement event hook methods
+ * @see {Mention} - Example implementation using onInput hook
+ */
+export class PluginField extends Base {
+	static type = 'field';
+
+	/**
+	 * @optional
+	 * @description Executes when user inputs text in the editor.
+	 * - Commonly used in field plugins to detect trigger characters or patterns
+	 * @type {SunEditor.Hook.Event.OnInput}
+	 * @type {SunEditor.Hook.Event.OnInputAsync}
+	 */
+	// onInput() {}
+}
+
+export class PluginInput extends Base {
+	static type = 'input';
+
+	/**
+	 * @optional
+	 * @description Executes the event function of toolbar's input tag - `keydown`.
+	 * @param {SunEditor.HookParams.ToolbarInputKeyDown} params - Input event information
+	 * @returns {void}
+	 */
+	toolbarInputKeyDown(params) {
+		void params;
+	}
+
+	/**
+	 * @optional
+	 * @description Executes the event function of toolbar's input tag - `change`.
+	 * @param {SunEditor.HookParams.ToolbarInputChange} params - Input event information
+	 * @returns {void}
+	 */
+	toolbarInputChange(params) {
+		void params;
+	}
+}
+
+export class PluginModal extends Base {
+	static type = 'modal';
+
+	/**
+	 * @abstract
+	 * Opens the modal window (Plugin's public API called by toolbar/external code)
+	 * @param {HTMLElement} [target] - The plugin's toolbar button element
+	 * @returns {void}
+	 */
+	open(target) {
+		throw new Error(`[${this.constructor.name}] Abstract method 'open()' must be implemented`);
+	}
+}
+
+export class PluginPopup extends Base {
+	static type = 'popup';
+
+	/**
+	 * @abstract
+	 * Called when a popup is shown
+	 * @returns {void}
+	 */
+	show() {
+		throw new Error(`[${this.constructor.name}] Abstract method 'show()' must be implemented`);
+	}
+}

package/src/langs/ckb.js

@@ -9,7 +9,7 @@
 						throw new Error('SUNEDITOR_LANG a window with a document');
 					}
 					return factory(w);
-			  };
+				};
 	} else {
 		factory(global);
 	}
@@ -206,7 +206,7 @@
 		video_modal_url: 'YouTube/Vimeo به‌سته‌ری له‌ناودانان وه‌ك ',
 		width: 'پانی',
 		message_copy_success: 'لە پەڕگەی لەبەرگرتووەدا هاوپەڕ کرا',
-		message_copy_fail: 'هاوپەڕکردن سەرکەوتوو نەبوو. تکایە بەدەست هاوپەڕ بکە.'
+		message_copy_fail: 'هاوپەڕکردن سەرکەوتوو نەبوو. تکایە بەدەست هاوپەڕ بکە.',
 	};
 
 	if (typeof noGlobal === typeof undefined) {
@@ -215,7 +215,7 @@
 				enumerable: true,
 				writable: false,
 				configurable: false,
-				value: {}
+				value: {},
 			});
 		}
 
@@ -223,7 +223,7 @@
 			enumerable: true,
 			writable: true,
 			configurable: true,
-			value: lang
+			value: lang,
 		});
 	}
 

package/src/langs/cs.js

@@ -9,7 +9,7 @@
 						throw new Error('SUNEDITOR_LANG a window with a document');
 					}
 					return factory(w);
-			  };
+				};
 	} else {
 		factory(global);
 	}
@@ -206,7 +206,7 @@
 		video_modal_url: 'URL pro vložení médií, YouTube/Vimeo',
 		width: 'Šířka',
 		message_copy_success: 'Zkopírováno do schránky',
-		message_copy_fail: 'Kopírování selhalo. Zkopírujte prosím ručně.'
+		message_copy_fail: 'Kopírování selhalo. Zkopírujte prosím ručně.',
 	};
 
 	if (typeof noGlobal === typeof undefined) {
@@ -215,7 +215,7 @@
 				enumerable: true,
 				writable: false,
 				configurable: false,
-				value: {}
+				value: {},
 			});
 		}
 
@@ -223,7 +223,7 @@
 			enumerable: true,
 			writable: true,
 			configurable: true,
-			value: lang
+			value: lang,
 		});
 	}
 

package/src/langs/da.js

@@ -9,7 +9,7 @@
 						throw new Error('SUNEDITOR_LANG a window with a document');
 					}
 					return factory(w);
-			  };
+				};
 	} else {
 		factory(global);
 	}
@@ -206,7 +206,7 @@
 		video_modal_url: 'Indlejr video / YouTube,Vimeo',
 		width: 'Bredde',
 		message_copy_success: 'Kopieret til udklipsholderen',
-		message_copy_fail: 'Kopiering mislykkedes. Kopiér venligst manuelt.'
+		message_copy_fail: 'Kopiering mislykkedes. Kopiér venligst manuelt.',
 	};
 
 	if (typeof noGlobal === typeof undefined) {
@@ -215,7 +215,7 @@
 				enumerable: true,
 				writable: false,
 				configurable: false,
-				value: {}
+				value: {},
 			});
 		}
 
@@ -223,7 +223,7 @@
 			enumerable: true,
 			writable: true,
 			configurable: true,
-			value: lang
+			value: lang,
 		});
 	}
 

package/src/langs/de.js

@@ -9,7 +9,7 @@
 						throw new Error('SUNEDITOR_LANG a window with a document');
 					}
 					return factory(w);
-			  };
+				};
 	} else {
 		factory(global);
 	}
@@ -206,7 +206,7 @@
 		video_modal_url: 'Video-URL, YouTube/Vimeo',
 		width: 'Breite',
 		message_copy_success: 'In die Zwischenablage kopiert',
-		message_copy_fail: 'Kopieren fehlgeschlagen. Bitte manuell kopieren.'
+		message_copy_fail: 'Kopieren fehlgeschlagen. Bitte manuell kopieren.',
 	};
 
 	if (typeof noGlobal === typeof undefined) {
@@ -215,7 +215,7 @@
 				enumerable: true,
 				writable: false,
 				configurable: false,
-				value: {}
+				value: {},
 			});
 		}
 
@@ -223,7 +223,7 @@
 			enumerable: true,
 			writable: true,
 			configurable: true,
-			value: lang
+			value: lang,
 		});
 	}
 

package/src/langs/en.js

@@ -8,7 +8,7 @@
 						throw new Error('SUNEDITOR_LANG a window with a document');
 					}
 					return factory(w);
-			  };
+				};
 	} else {
 		factory(global);
 	}
@@ -205,7 +205,7 @@
 		video_modal_url: 'Media embed URL, YouTube/Vimeo',
 		width: 'Width',
 		message_copy_success: 'Copied to clipboard',
-		message_copy_fail: 'Copy failed. Please copy manually.'
+		message_copy_fail: 'Copy failed. Please copy manually.',
 	};
 
 	if (typeof noGlobal === typeof undefined) {
@@ -214,7 +214,7 @@
 				enumerable: true,
 				writable: false,
 				configurable: false,
-				value: {}
+				value: {},
 			});
 		}
 
@@ -222,7 +222,7 @@
 			enumerable: true,
 			writable: true,
 			configurable: true,
-			value: lang
+			value: lang,
 		});
 	}
 

package/src/langs/es.js

@@ -9,7 +9,7 @@
 						throw new Error('SUNEDITOR_LANG a window with a document');
 					}
 					return factory(w);
-			  };
+				};
 	} else {
 		factory(global);
 	}
@@ -206,7 +206,7 @@
 		video_modal_url: 'URL del vídeo',
 		width: 'Ancho',
 		message_copy_success: 'Copiado al portapapeles',
-		message_copy_fail: 'Error al copiar. Por favor, copie manualmente.'
+		message_copy_fail: 'Error al copiar. Por favor, copie manualmente.',
 	};
 
 	if (typeof noGlobal === typeof undefined) {
@@ -215,7 +215,7 @@
 				enumerable: true,
 				writable: false,
 				configurable: false,
-				value: {}
+				value: {},
 			});
 		}
 
@@ -223,7 +223,7 @@
 			enumerable: true,
 			writable: true,
 			configurable: true,
-			value: lang
+			value: lang,
 		});
 	}