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

package/src/helper/keyCodeMap.js

@@ -1,7 +1,3 @@
-/**
- * @fileoverview keyCode helper
- */
-
 const _arrow = 'ArrowLeft|ArrowUp|ArrowRight|ArrowDown';
 const _fN = 'F1|F2|F3|F4|F5|F6|F7|F8|F9|F10|F11|F12';
 // const DIR_KEYCODE = /^(3[7-9]|40)$/;
@@ -19,7 +15,7 @@ const NON_RESPONSE_CODE = `ControlLeft|ControlRight|AltLeft|AltRight|Pause|CapsL
 
 /** ------------------------------------------------------- [meta] -------------------------------------------------------  */
 /**
- * @description Shift check
+ * @description `Shift` check
  * @param {KeyboardEvent} e Event object
  * @returns {boolean}
  */
@@ -28,7 +24,7 @@ export function isShift(e) {
 }
 
 /**
- * @description [Ctrl|Meta] check
+ * @description [`Ctrl`|`Meta`] check
  * @param {KeyboardEvent} e Event object
  * @returns {boolean}
  */
@@ -39,7 +35,7 @@ export function isCtrl(e) {
 }
 
 /**
- * @description Alt check
+ * @description `Alt` check
  * @param {KeyboardEvent} e Event object
  * @returns {boolean}
  */
@@ -48,17 +44,18 @@ export function isAlt(e) {
 }
 
 /**
- * @description event.isComposing check
- * @param {KeyboardEvent} e Event object
+ * @description Check if the event is related to IME composition (in-progress or commit).
+ * @param {KeyboardEvent|InputEvent} e Event object
  * @returns {boolean}
  */
 export function isComposing(e) {
-	return e.isComposing || e.keyCode === 229;
+	// @ts-ignore
+	return e.isComposing || e.key === 'Process' || e.keyCode === 229;
 }
 
 /**
- * @description Backspace key check
- * @param {string} code Event.code
+ * @description `Backspace` key check
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isBackspace(code) {
@@ -67,8 +64,8 @@ export function isBackspace(code) {
 }
 
 /**
- * @description Tab key check
- * @param {string} code Event.code
+ * @description `Tab` key check
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isTab(code) {
@@ -77,8 +74,8 @@ export function isTab(code) {
 }
 
 /**
- * @description Enter key check
- * @param {string} code Event.code
+ * @description `Enter` key check
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isEnter(code) {
@@ -87,8 +84,8 @@ export function isEnter(code) {
 }
 
 /**
- * @description ESC key check
- * @param {string} code Event.code
+ * @description `ESC` key check
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isEsc(code) {
@@ -97,8 +94,8 @@ export function isEsc(code) {
 }
 
 /**
- * @description Space key check
- * @param {string} code Event.code
+ * @description `Space` key check
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isSpace(code) {
@@ -110,7 +107,7 @@ export function isSpace(code) {
 
 /**
  * @description Direction key check
- * @param {string} code Event.code
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isDirectionKey(code) {
@@ -118,8 +115,8 @@ export function isDirectionKey(code) {
 }
 
 /**
- * @description [delete, backspace] key check
- * @param {string} code Event.code
+ * @description [`delete`, `backspace`] key check
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isRemoveKey(code) {
@@ -128,7 +125,7 @@ export function isRemoveKey(code) {
 
 /**
  * @description Non-text key check
- * @param {string} code Event.code
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isNonTextKey(code) {
@@ -137,7 +134,7 @@ export function isNonTextKey(code) {
 
 /**
  * @description Check if the given key is relevant for history push
- * @param {string} code - Event.code
+ * @param {string} code - `Event.code`
  * @returns {boolean}
  */
 export function isHistoryRelevantKey(code) {
@@ -146,7 +143,7 @@ export function isHistoryRelevantKey(code) {
 
 /**
  * @description Document type observer key check
- * @param {string} code Event.code
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isDocumentTypeObserverKey(code) {
@@ -155,7 +152,7 @@ export function isDocumentTypeObserverKey(code) {
 
 /**
  * @description Non-response key check
- * @param {string} code Event.code
+ * @param {string} code `Event.code`
  * @returns {boolean}
  */
 export function isNonResponseKey(code) {
@@ -177,7 +174,7 @@ const keyCodeMap = {
 	isNonTextKey,
 	isHistoryRelevantKey,
 	isDocumentTypeObserverKey,
-	isNonResponseKey
+	isNonResponseKey,
 };
 
 export default keyCodeMap;

package/src/helper/numbers.js

@@ -1,7 +1,3 @@
-/**
- * @fileoverview Number-related helper functions
- */
-
 /**
  * @description Checks for numeric (with decimal point).
  * @param {*} text Text string or number
@@ -14,7 +10,7 @@ export function is(text) {
 /**
  * @description Get a number.
  * @param {string|number} value Text string or number
- * @param {number} [maxDec=0] Maximum number of decimal places (-1 : Infinity)
+ * @param {number} [maxDec=0] Maximum number of decimal places (`-1` : `Infinity`)
  * @returns {number}
  */
 export function get(value, maxDec = 0) {
@@ -28,8 +24,8 @@ export function get(value, maxDec = 0) {
 }
 
 /**
- * @description It compares the start and end indexes of 'a' and 'b' and returns the number of overlapping indexes in the range.
- * - e.g.) 1, 5, 4, 6 => '2' (4,5)
+ * @description It compares the start and end indexes of `a` and `b` and returns the number of overlapping indexes in the range.
+ * - e.g.) 1, 5, 4, 6 => `2` (4,5)
  * @param {number} aStart Start index of 'a'
  * @param {number} aEnd End index of 'a'
  * @param {number} bStart Start index of 'b'
@@ -66,7 +62,7 @@ const numbers = {
 	get,
 	getOverlapRangeAtIndex,
 	isEven,
-	isOdd
+	isOdd,
 };
 
 export default numbers;

package/src/helper/unicode.js

@@ -1,23 +1,19 @@
-/**
- * @fileoverview Unicode helper functions
- */
-
 const zwsp = 8203;
 
 /**
- * @description Unicode Character 'ZERO WIDTH SPACE' (\u200B)
+ * @description Unicode Character `ZERO WIDTH SPACE` (`\u200B`)
  * @type {string}
  */
 export const zeroWidthSpace = String.fromCharCode(zwsp);
 
 /**
- * @description Regular expression to find 'zero width space' (/\u200B/g)
+ * @description Regular expression to find `zero width space` (`/\u200B/g`)
  * @type {RegExp}
  */
 export const zeroWidthRegExp = new RegExp(String.fromCharCode(zwsp), 'g');
 
 /**
- * @description Regular expression to find only 'zero width space' (/\u200B/g)
+ * @description Regular expression to find only `zero width space` (`/\u200B/g`)
  * @type {RegExp}
  */
 export const onlyZeroWidthRegExp = new RegExp('^' + String.fromCharCode(zwsp) + '+$');
@@ -41,7 +37,7 @@ const unicode = {
 	zeroWidthSpace,
 	zeroWidthRegExp,
 	onlyZeroWidthRegExp,
-	escapeStringRegexp
+	escapeStringRegexp,
 };
 
 export default unicode;

package/src/hooks/base.js

@@ -0,0 +1,307 @@
+/**
+ * @fileoverview Editor interface definitions for SunEditor.
+ * These types define callback methods that Editor core calls on plugin instances.
+ */
+
+// ================================================================
+// EDITOR METHOD TYPES - Methods called by Editor core on plugins
+// ================================================================
+
+export const Event = {
+	/**
+	 * Executes the method that is called whenever the cursor position changes.
+	 * @description Executes the method that is called whenever the cursor position changes.
+	 * @param {?HTMLElement} element - Node element where the cursor is currently located
+	 * @param {?HTMLElement} target - The plugin's toolbar button element
+	 * @returns {boolean|void} - Whether the plugin is active
+	 * - If it returns `undefined`, it will no longer be called in this scope.
+	 */
+	Active(element, target) {},
+
+	/**
+	 * Executes the event function of `focus`.
+	 * @param {SunEditor.HookParams.FocusBlur} params - Event parameters
+	 * @returns {void}
+	 */
+	OnFocus(params) {},
+
+	/**
+	 * Executes the event function of `blur`.
+	 * @param {SunEditor.HookParams.FocusBlur} params - Event parameters
+	 * @returns {void}
+	 */
+	OnBlur(params) {},
+
+	/**
+	 * Executes the event function of `mousemove`.
+	 * @param {SunEditor.HookParams.MouseEvent} params - Mouse event information
+	 * @returns {void}
+	 */
+	OnMouseMove(params) {},
+
+	/**
+	 * Executes the event function of `scroll`.
+	 * @param {SunEditor.HookParams.Scroll} params - Event parameters
+	 * @returns {void}
+	 */
+	OnScroll(params) {},
+
+	// ====== Sync / Async Event Methods ======
+
+	// ------- Interruptible events (returning boolean stops event processing) ---
+
+	/**
+	 * Executes the event function of `keydown` (sync).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * @param {SunEditor.HookParams.KeyEvent} params - Key event information
+	 * @returns {void|boolean} - Return `false` to prevent the editor's `keydown` processing (shortcuts, actions)
+	 */
+	OnKeyDown(params) {},
+
+	/**
+	 * Executes the event function of `keydown` (async).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * @param {SunEditor.HookParams.KeyEvent} params - Key event information
+	 * @returns {Promise<void|boolean>} - Return `false` to prevent the editor's `keydown` processing (shortcuts, actions)
+	 */
+	async OnKeyDownAsync(params) {
+		return;
+	},
+
+	/**
+	 * Executes the event function of `keyup` (sync).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * @param {SunEditor.HookParams.KeyEvent} params - Key event information
+	 * @returns {void|boolean} - Return `false` to prevent adding to history
+	 */
+	OnKeyUp(params) {},
+
+	/**
+	 * Executes the event function of `keyup` (async).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * @param {SunEditor.HookParams.KeyEvent} params - Key event information
+	 * @returns {Promise<void|boolean>} - Return `false` to prevent adding to history
+	 */
+	async OnKeyUpAsync(params) {
+		return;
+	},
+
+	/**
+	 * Executes the event function of `mousedown` (sync).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * @param {SunEditor.HookParams.MouseEvent} params - Mouse event information
+	 * @returns {void|boolean} - Return `false` to prevent the editor's `mousedown` processing
+	 */
+	OnMouseDown(params) {},
+
+	/**
+	 * Executes the event function of `mousedown` (async).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * @param {SunEditor.HookParams.MouseEvent} params - Mouse event information
+	 * @returns {Promise<void|boolean>} - Return `false` to prevent the editor's `mousedown` processing
+	 */
+	async OnMouseDownAsync(params) {
+		return;
+	},
+
+	/**
+	 * Executes the event function of `click` (sync).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * @param {SunEditor.HookParams.MouseEvent} params - Mouse event information
+	 * @returns {void|boolean} - Return `false` to prevent the editor's `click` processing (component selection)
+	 */
+	OnClick(params) {},
+
+	/**
+	 * Executes the event function of `click` (async).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * @param {SunEditor.HookParams.MouseEvent} params - Mouse event information
+	 * @returns {Promise<void|boolean>} - Return `false` to prevent the editor's `click` processing (component selection)
+	 */
+	async OnClickAsync(params) {
+		return;
+	},
+
+	/**
+	 * Executes the event function of `paste` (sync).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * Returning `false` will stop event propagation and cancel the paste.
+	 * @param {SunEditor.HookParams.Paste} params - Paste event information
+	 * @returns {void|boolean}
+	 */
+	OnPaste(params) {},
+
+	/**
+	 * Executes the event function of `paste` (async).
+	 * Called sequentially on all plugins. Returning a boolean stops the loop.
+	 * Returning `false` will stop event propagation and cancel the paste.
+	 * @param {SunEditor.HookParams.Paste} params - Paste event information
+	 * @returns {Promise<void|boolean>}
+	 */
+	async OnPasteAsync(params) {
+		return;
+	},
+
+	// ------- Observation events (non-interruptible) ------
+
+	/**
+	 * Executes the event function of `beforeinput` (sync).
+	 * Called after validation but before the input is processed.
+	 * @param {SunEditor.HookParams.InputWithData} params - Event parameters
+	 * @returns {void}
+	 */
+	OnBeforeInput(params) {},
+
+	/**
+	 * Executes the event function of `beforeinput` (async).
+	 * Called after validation but before the input is processed.
+	 * @param {SunEditor.HookParams.InputWithData} params - Event parameters
+	 * @returns {Promise<void>}
+	 */
+	async OnBeforeInputAsync(params) {
+		return;
+	},
+
+	/**
+	 * Executes the event function of `input` (sync).
+	 * Called after the input has been processed.
+	 * @param {SunEditor.HookParams.InputWithData} params - Event parameters
+	 * @returns {void}
+	 */
+	OnInput(params) {},
+
+	/**
+	 * Executes the event function of `input` (async).
+	 * Called after the input has been processed.
+	 * @param {SunEditor.HookParams.InputWithData} params - Event parameters
+	 * @returns {Promise<void>}
+	 */
+	async OnInputAsync(params) {
+		return;
+	},
+
+	/**
+	 * Executes the event function of `mouseup` (sync).
+	 * @param {SunEditor.HookParams.MouseEvent} params - Mouse event information
+	 * @returns {void}
+	 */
+	OnMouseUp(params) {},
+
+	/**
+	 * Executes the event function of `mouseup` (async).
+	 * @param {SunEditor.HookParams.MouseEvent} params - Mouse event information
+	 * @returns {Promise<void>}
+	 */
+	async OnMouseUpAsync(params) {
+		return;
+	},
+
+	/**
+	 * Executes the event function of `mouseleave` (sync).
+	 * @param {SunEditor.HookParams.MouseEvent} params - Mouse event information
+	 * @returns {void}
+	 */
+	OnMouseLeave(params) {},
+
+	/**
+	 * Executes the event function of `mouseleave` (async).
+	 * @param {SunEditor.HookParams.MouseEvent} params - Mouse event information
+	 * @returns {Promise<void>}
+	 */
+	async OnMouseLeaveAsync(params) {
+		return;
+	},
+
+	/**
+	 * Executes when files are pasted or dropped into the editor (sync).
+	 * This event is called for each file. The paste/drop process is automatically stopped after processing all files.
+	 * @param {SunEditor.HookParams.FilePasteDrop} params - File paste/drop event information
+	 * @returns {void}
+	 */
+	OnFilePasteAndDrop(params) {},
+
+	/**
+	 * Executes when files are pasted or dropped into the editor (async).
+	 * This event is called for each file. The paste/drop process is automatically stopped after processing all files.
+	 * @param {SunEditor.HookParams.FilePasteDrop} params - File paste/drop event information
+	 * @returns {Promise<void>}
+	 */
+	async OnFilePasteAndDropAsync(params) {
+		return;
+	},
+};
+
+export const Component = {
+	/**
+	 * 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`
+	 */
+	Select(target) {},
+
+	/**
+	 * Called when a container is deselected.
+	 * @param {HTMLElement} target Target element
+	 * @returns {void}
+	 */
+	Deselect(target) {},
+
+	/**
+	 * Executes the method that is called when a component is being edited.
+	 * @param {HTMLElement} target - Target element
+	 * @returns {void}
+	 */
+	Edit(target) {},
+
+	/**
+	 * Method to delete a component of a plugin, called by the `FileManager`, `Controller` module.
+	 * @param {HTMLElement} target - Target element
+	 * @returns {Promise<void>}
+	 */
+	async Destroy(target) {
+		return;
+	},
+
+	/**
+	 * 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
+	 */
+	Copy(params) {},
+};
+
+export const Core = {
+	/**
+	 * This method is used to validate and preserve the format of the component within the editor.
+	 * - It ensures that the structure and attributes of the element are maintained and secure.
+	 * - The method checks if the element is already wrapped in a valid container and updates its attributes if necessary.
+	 * - If the element isn't properly contained, a new container is created to retain the format.
+	 * @returns {{query: string, method: (element: HTMLElement) => void}} The format retention object containing the query and method to process the element.
+	 * - query: The selector query to identify the relevant elements.
+	 * - method: The function to execute on the element to validate and preserve its format.
+	 */
+	RetainFormat() {
+		return { query: '', method: () => {} };
+	},
+
+	/**
+	 * Executes methods called by shortcut keys.
+	 * @param {SunEditor.HookParams.Shortcut} params - Information of the `shortcut` plugin
+	 * @returns {void}
+	 */
+	Shortcut(params) {},
+
+	/**
+	 * Executes the method called when the rtl, ltr mode changes. (`editor.ui.setDir`)
+	 * @param {string} dir - Direction (`rtl` or `ltr`)
+	 * @returns {void}
+	 */
+	SetDir(dir) {},
+
+	/**
+	 * Executes when the editor or plugin is initialized.
+	 * Called during editor initialization and when `resetOptions` is called.
+	 * @returns {void}
+	 */
+	Init() {},
+};

package/src/hooks/params.js

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Common parameter types used across SunEditor plugins and callbacks.
+ * These types define the structure of parameters passed to various plugin methods.
+ */
+
+// ================================================================
+// PARAMS - Common parameter types
+// ================================================================
+
+/**
+ * @typedef {{
+ *   file: File,
+ *   event: ClipboardEvent | DragEvent,
+ *   frameContext: SunEditor.FrameContext
+ * }} FilePasteDrop
+ * @description Parameters for file paste/drop events
+ */
+
+/**
+ * @typedef {{
+ *   frameContext: SunEditor.FrameContext,
+ *   event: FocusEvent
+ * }} FocusBlurEvent
+ * @description Parameters for focus and blur events
+ */
+
+/**
+ * @typedef {{
+ *   frameContext: SunEditor.FrameContext,
+ *   event: Event
+ * }} ScrollEvent
+ * @description Parameters for scroll events
+ */
+
+/**
+ * @typedef {{
+ *   frameContext: SunEditor.FrameContext,
+ *   event: InputEvent,
+ *   data: string
+ * }} InputEventWithData
+ * @description Parameters for beforeinput and input events
+ */
+
+/**
+ * @typedef {{
+ *   frameContext: SunEditor.FrameContext,
+ *   event: ClipboardEvent,
+ *   data: string,
+ *   doc: Document
+ * }} Paste
+ * @description Parameters for paste events
+ */
+
+/**
+ * @typedef {{
+ *   frameContext: SunEditor.FrameContext,
+ *   event: MouseEvent
+ * }} Mouse
+ * @description Parameters for mouse events
+ */
+
+/**
+ * @typedef {{
+ *   frameContext: SunEditor.FrameContext,
+ *   event: KeyboardEvent
+ * }} Keyboard
+ * @description Parameters for keyboard events
+ */
+
+/**
+ * @typedef {{
+ *   target: HTMLElement,
+ *   event: KeyboardEvent
+ * }} ToolbarInputKeyDown
+ * @description Parameters for toolbar input keydown events
+ */
+
+/**
+ * @typedef {{
+ *   target: HTMLElement,
+ *   value: string,
+ *   event: FocusEvent | MouseEvent
+ * }} ToolbarInputChange
+ * @description Parameters for toolbar input change events (triggered by blur or other input click)
+ */
+
+/**
+ * @typedef {{
+ *   event: ClipboardEvent,
+ *   cloneContainer: HTMLElement,
+ *   info: SunEditor.ComponentInfo
+ * }} CopyComponent
+ * @description Parameters for component copy events
+ */
+
+// ================================================================
+// PLUGIN EVENT PARAMS - Plugin hook event parameter types
+// ================================================================
+
+/**
+ * @typedef {{
+ *   frameContext: SunEditor.FrameContext,
+ *   event: MouseEvent
+ * }} MouseEventInfo
+ * @description Parameters for plugin mouse event hooks
+ */
+
+/**
+ * @typedef {{
+ *   frameContext: SunEditor.FrameContext,
+ *   event: KeyboardEvent,
+ *   range: Range,
+ *   line: HTMLElement
+ * }} KeyEventInfo
+ * @description Parameters for plugin keyboard event hooks
+ */
+
+/**
+ * @typedef {{
+ *   range: Range,
+ *   line: HTMLElement,
+ *   info: import('../core/logic/shell/shortcuts').ShortcutInfo,
+ *   event: KeyboardEvent,
+ *   keyCode: string,
+ *   $: SunEditor.Deps
+ * }} ShortcutInfo
+ * @description Information of the `shortcut` plugin hook
+ */
+
+export {};