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

package/types/core/logic/dom/offset.d.ts

@@ -0,0 +1,335 @@
+import type {} from '../../../typedef';
+export default Offset;
+/**
+ * Bounding rectangle information of the selection range.
+ */
+export type RectsInfo = {
+	/**
+	 * - The left position of the selection.
+	 */
+	left: number;
+	/**
+	 * - The right position of the selection.
+	 */
+	right: number;
+	/**
+	 * - The top position of the selection.
+	 */
+	top: number;
+	/**
+	 * - The bottom position of the selection.
+	 */
+	bottom: number;
+	/**
+	 * - Whether the selection contains text.
+	 */
+	noText?: boolean;
+	/**
+	 * - The width of the selection.
+	 */
+	width?: number;
+	/**
+	 * - The height of the selection.
+	 */
+	height?: number;
+};
+export type OffsetInfo = {
+	/**
+	 * - The top position of the node relative to the entire document, including iframe offsets.
+	 */
+	top: number;
+	/**
+	 * - The left position of the node relative to the entire document, including iframe offsets.
+	 */
+	left: number;
+};
+export type OffsetLocalInfo = {
+	/**
+	 * - The top position of the node relative to the WYSIWYG editor.
+	 */
+	top: number;
+	/**
+	 * - The left position of the node relative to the WYSIWYG editor.
+	 */
+	left: number;
+	/**
+	 * - The right position of the node relative to the WYSIWYG editor.
+	 */
+	right: number;
+	/**
+	 * - The horizontal scroll offset inside the WYSIWYG editor.
+	 */
+	scrollX: number;
+	/**
+	 * - The vertical scroll offset inside the WYSIWYG editor.
+	 */
+	scrollY: number;
+	/**
+	 * - The vertical scroll height inside the WYSIWYG editor.
+	 */
+	scrollH: number;
+};
+export type OffsetGlobalInfo = {
+	/**
+	 * - The top position of the element relative to the entire document.
+	 */
+	top: number;
+	/**
+	 * - The left position of the element relative to the entire document.
+	 */
+	left: number;
+	/**
+	 * - The top position within the current viewport, without taking scrolling into account.
+	 */
+	fixedTop: number;
+	/**
+	 * - The left position within the current viewport, without taking scrolling into account.
+	 */
+	fixedLeft: number;
+	/**
+	 * - The total width of the element, including its content, padding, and border.
+	 */
+	width: number;
+	/**
+	 * - The total height of the element, including its content, padding, and border.
+	 */
+	height: number;
+};
+export type OffsetGlobalScrollInfo = {
+	/**
+	 * - Total top scroll distance
+	 */
+	top: number;
+	/**
+	 * - Total left scroll distance
+	 */
+	left: number;
+	/**
+	 * - Total width including scrollable area
+	 */
+	width: number;
+	/**
+	 * - Total height including scrollable area
+	 */
+	height: number;
+	/**
+	 * - Horizontal offset from the top reference element
+	 */
+	x: number;
+	/**
+	 * - Vertical offset from the top reference element
+	 */
+	y: number;
+	/**
+	 * - Element or window used as the vertical scroll reference
+	 */
+	ohOffsetEl: HTMLElement | Window | null;
+	/**
+	 * - Element or window used as the horizontal scroll reference
+	 */
+	owOffsetEl: HTMLElement | Window | null;
+	/**
+	 * - Height of the vertical scrollable area (clientHeight)
+	 */
+	oh: number;
+	/**
+	 * - Width of the horizontal scrollable area (clientWidth)
+	 */
+	ow: number;
+	/**
+	 * - Indicates if the vertical scroll reference is the editor area
+	 */
+	heightEditorRefer: boolean;
+	/**
+	 * - Indicates if the horizontal scroll reference is the editor area
+	 */
+	widthEditorRefer: boolean;
+	/**
+	 * - Top position of the height offset element relative to the viewport
+	 */
+	ts: number;
+	/**
+	 * - Left position of the width offset element relative to the viewport
+	 */
+	ls: number;
+};
+export type OffsetWWScrollInfo = {
+	/**
+	 * - The top scroll offset inside the WYSIWYG editor.
+	 */
+	top: number;
+	/**
+	 * - The left scroll offset inside the WYSIWYG editor.
+	 */
+	left: number;
+	/**
+	 * - The total width of the WYSIWYG editor's scrollable area.
+	 */
+	width: number;
+	/**
+	 * - The total height of the WYSIWYG editor's scrollable area.
+	 */
+	height: number;
+	/**
+	 * - The sum of `top` and `height`, representing the bottom-most scrollable position.
+	 */
+	bottom: number;
+};
+/**
+ * @typedef {Object} RectsInfo Bounding rectangle information of the selection range.
+ * @property {number} rects.left - The left position of the selection.
+ * @property {number} rects.right - The right position of the selection.
+ * @property {number} rects.top - The top position of the selection.
+ * @property {number} rects.bottom - The bottom position of the selection.
+ * @property {boolean} [rects.noText] - Whether the selection contains text.
+ * @property {number} [rects.width] - The width of the selection.
+ * @property {number} [rects.height] - The height of the selection.
+ */
+/**
+ * @typedef {Object} OffsetInfo
+ * @property {number} top - The top position of the node relative to the entire document, including iframe offsets.
+ * @property {number} left - The left position of the node relative to the entire document, including iframe offsets.
+ */
+/**
+ * @typedef {Object} OffsetLocalInfo
+ * @property {number} top - The top position of the node relative to the WYSIWYG editor.
+ * @property {number} left - The left position of the node relative to the WYSIWYG editor.
+ * @property {number} right - The right position of the node relative to the WYSIWYG editor.
+ * @property {number} scrollX - The horizontal scroll offset inside the WYSIWYG editor.
+ * @property {number} scrollY - The vertical scroll offset inside the WYSIWYG editor.
+ * @property {number} scrollH - The vertical scroll height inside the WYSIWYG editor.
+ */
+/**
+ * @typedef {Object} OffsetGlobalInfo
+ * @property {number} top - The top position of the element relative to the entire document.
+ * @property {number} left - The left position of the element relative to the entire document.
+ * @property {number} fixedTop - The top position within the current viewport, without taking scrolling into account.
+ * @property {number} fixedLeft - The left position within the current viewport, without taking scrolling into account.
+ * @property {number} width - The total width of the element, including its content, padding, and border.
+ * @property {number} height - The total height of the element, including its content, padding, and border.
+ */
+/**
+ * @typedef {Object} OffsetGlobalScrollInfo
+ * @property {number} top - Total top scroll distance
+ * @property {number} left - Total left scroll distance
+ * @property {number} width - Total width including scrollable area
+ * @property {number} height - Total height including scrollable area
+ * @property {number} x - Horizontal offset from the top reference element
+ * @property {number} y - Vertical offset from the top reference element
+ * @property {HTMLElement|Window|null} ohOffsetEl - Element or window used as the vertical scroll reference
+ * @property {HTMLElement|Window|null} owOffsetEl - Element or window used as the horizontal scroll reference
+ * @property {number} oh - Height of the vertical scrollable area (clientHeight)
+ * @property {number} ow - Width of the horizontal scrollable area (clientWidth)
+ * @property {boolean} heightEditorRefer - Indicates if the vertical scroll reference is the editor area
+ * @property {boolean} widthEditorRefer - Indicates if the horizontal scroll reference is the editor area
+ * @property {number} ts - Top position of the height offset element relative to the viewport
+ * @property {number} ls - Left position of the width offset element relative to the viewport
+ */
+/**
+ * @typedef {Object} OffsetWWScrollInfo
+ * @property {number} top - The top scroll offset inside the WYSIWYG editor.
+ * @property {number} left - The left scroll offset inside the WYSIWYG editor.
+ * @property {number} width - The total width of the WYSIWYG editor's scrollable area.
+ * @property {number} height - The total height of the WYSIWYG editor's scrollable area.
+ * @property {number} bottom - The sum of `top` and `height`, representing the bottom-most scrollable position.
+ */
+/**
+ * @description Offset class, get the position of the element
+ */
+declare class Offset {
+	/**
+	 * @constructor
+	 * @param {SunEditor.Kernel} kernel
+	 */
+	constructor(kernel: SunEditor.Kernel);
+	/**
+	 * @description Gets the position just outside the argument's internal editor (wysiwygFrame).
+	 * @param {Node} node Target node.
+	 * @returns {OffsetInfo} Position relative to the editor frame.
+	 */
+	get(node: Node): OffsetInfo;
+	/**
+	 * @description Gets the position inside the internal editor of the argument.
+	 * @param {Node} node Target node.
+	 * @returns {OffsetLocalInfo} Position relative to the WYSIWYG editor.
+	 */
+	getLocal(node: Node): OffsetLocalInfo;
+	/**
+	 * @description Returns the position of the argument relative to the global document.
+	 * This is a refactored version using getBoundingClientRect for better performance and accuracy.
+	 * @param {?Node} [node] Target element.
+	 * @returns {OffsetGlobalInfo} Global position and scroll values.
+	 */
+	getGlobal(node?: Node | null): OffsetGlobalInfo;
+	/**
+	 * @description Gets the current editor-relative scroll offset.
+	 * @param {?Node} [node] Target element.
+	 * @returns {OffsetGlobalScrollInfo} Global scroll information.
+	 */
+	getGlobalScroll(node?: Node | null): OffsetGlobalScrollInfo;
+	/**
+	 * @description Get the scroll info of the WYSIWYG area.
+	 * @returns {OffsetWWScrollInfo} Scroll information within the editor.
+	 */
+	getWWScroll(): OffsetWWScrollInfo;
+	/**
+	 * @description Sets the relative position of an element
+	 * @param {HTMLElement} element Element to position
+	 * @param {HTMLElement} e_container Element's root container
+	 * @param {HTMLElement} target Target element to position against
+	 * @param {HTMLElement} t_container Target's root container
+	 */
+	setRelPosition(element: HTMLElement, e_container: HTMLElement, target: HTMLElement, t_container: HTMLElement): void;
+	/**
+	 * @description Sets the absolute position of an element
+	 * @param {HTMLElement} element Element to position
+	 * @param {HTMLElement} target Target element
+	 * @param {Object} params Position parameters
+	 * @param {boolean} [params.isWWTarget=false] Whether the target is within the editor's WYSIWYG area
+	 * @param {{left:number, top:number}} [params.addOffset={left:0, top:0}] Additional offset
+	 * @param {"bottom"|"top"} [params.position="bottom"] Position ('bottom'|'top')
+	 * @param {*} params.inst Instance object of caller
+	 * @param {HTMLElement} [params.sibling=null] The sibling controller element
+	 * @returns {{position: "top" | "bottom"} | undefined} Success -> {position: current position}
+	 */
+	setAbsPosition(
+		element: HTMLElement,
+		target: HTMLElement,
+		params: {
+			isWWTarget?: boolean;
+			addOffset?: {
+				left: number;
+				top: number;
+			};
+			position?: 'bottom' | 'top';
+			inst: any;
+			sibling?: HTMLElement;
+		},
+	):
+		| {
+				position: 'top' | 'bottom';
+		  }
+		| undefined;
+	/**
+	 * @description Sets the position of an element relative to a range
+	 * @param {HTMLElement} element Element to position
+	 * @param {?Range} range Range to position against.
+	 * - if null, the current selection range is used
+	 * @param {Object} [options={}] Position options
+	 * @param {"bottom"|"top"} [options.position="bottom"] Position ('bottom'|'top')
+	 * @param {number} [options.addTop=0] Additional top offset
+	 * @returns {boolean} Success / Failure
+	 */
+	setRangePosition(
+		element: HTMLElement,
+		range: Range | null,
+		{
+			position,
+			addTop,
+		}?: {
+			position?: 'bottom' | 'top';
+			addTop?: number;
+		},
+	): boolean;
+	#private;
+}

package/types/core/logic/dom/selection.d.ts

@@ -0,0 +1,165 @@
+import type {} from '../../../typedef';
+export default Selection_;
+/**
+ * @description Selection, Range related class
+ */
+declare class Selection_ {
+	/**
+	 * @constructor
+	 * @param {SunEditor.Kernel} kernel
+	 */
+	constructor(kernel: SunEditor.Kernel);
+	/** @type {Range} */
+	range: Range;
+	/** @type {HTMLElement|Text} */
+	selectionNode: HTMLElement | Text;
+	/** @internal */
+	__iframeFocus: boolean;
+	/**
+	 * @description Get window selection obejct
+	 * @returns {Selection}
+	 */
+	get(): Selection;
+	/**
+	 * @description Check if the range object is valid
+	 * @param {*} range Range object
+	 * @returns {range is Range}
+	 */
+	isRange(range: any): range is Range;
+	/**
+	 * @description Get current editor's range object
+	 * @returns {Range}
+	 */
+	getRange(): Range;
+	/**
+	 * @description Set current editor's range object and return.
+	 * @param {Node|Range} startCon Range object or The `startContainer` property of the selection object
+	 * @param {number} [startOff] The `startOffset` property of the selection object.
+	 * @param {Node} [endCon] The `endContainer` property of the selection object.
+	 * @param {number} [endOff] The `endOffset` property of the selection object.
+	 * @returns {Range}
+	 * @example
+	 * // Set range using container and offset
+	 * const textNode = editor.selection.getNode();
+	 * editor.selection.setRange(textNode, 0, textNode, 5);
+	 *
+	 * // Set range using Range object
+	 * const range = document.createRange();
+	 * range.selectNodeContents(someElement);
+	 * editor.selection.setRange(range);
+	 *
+	 * // Collapse cursor to start of element
+	 * editor.selection.setRange(element, 0, element, 0);
+	 */
+	setRange(startCon: Node | Range, startOff?: number, endCon?: Node, endOff?: number): Range;
+	/**
+	 * @description Remove range object and button effect
+	 */
+	removeRange(): void;
+	/**
+	 * @description Returns the range (container and offset) near the given target node.
+	 * - If the target node has a next sibling, it returns the next sibling with an offset of 0.
+	 * - If there is no next sibling but a previous sibling exists, it returns the previous sibling with an offset of 1.
+	 * @param {Node} target Target node whose neighboring range is to be determined.
+	 * @returns {{container: Node, offset: number}|null} An object containing the nearest container node and its offset.
+	 */
+	getNearRange(target: Node): {
+		container: Node;
+		offset: number;
+	} | null;
+	/**
+	 * @description If the `range` object is a non-editable area, add a line at the top of the editor and update the `range` object.
+	 * @param {Range} range core.getRange()
+	 * @param {?Node} [container] If there is `container` argument, it creates a line in front of the container.
+	 * @returns {Range} a new `range` or argument `range`.
+	 */
+	getRangeAndAddLine(range: Range, container?: Node | null): Range;
+	/**
+	 * @description Get current select node
+	 * @returns {HTMLElement|Text}
+	 */
+	getNode(): HTMLElement | Text;
+	/**
+	 * @description Get the Rects object.
+	 * @param {?(Range|Node)} target `Range` | `Node` | `null`
+	 * @param {"start"|"end"} position It is based on the position of the rect object to be returned in case of range selection.
+	 * @returns {{rects: import('./offset').RectsInfo, position: "start"|"end", scrollLeft: number, scrollTop: number}}
+	 * @example
+	 * // Get rects at start of selection
+	 * const { rects, position, scrollLeft, scrollTop } = editor.selection.getRects(null, 'start');
+	 * console.log(rects.left, rects.top, rects.right, rects.bottom);
+	 *
+	 * // Get rects for specific node
+	 * const node = editor.selection.getNode();
+	 * const rectsInfo = editor.selection.getRects(node, 'end');
+	 *
+	 * // Use rects for positioning UI elements
+	 * const { rects } = editor.selection.getRects(null, 'start');
+	 * tooltip.style.left = rects.left + 'px';
+	 * tooltip.style.top = rects.top + 'px';
+	 */
+	getRects(
+		target: (Range | Node) | null,
+		position: 'start' | 'end',
+	): {
+		rects: import('./offset').RectsInfo;
+		position: 'start' | 'end';
+		scrollLeft: number;
+		scrollTop: number;
+	};
+	/**
+	 * @description Get the custom range object of the event.
+	 * @param {DragEvent} e Event object
+	 * @returns {{sc: Node, so: number, ec: Node, eo: number}} {sc: `startContainer`, so: `startOffset`, ec: `endContainer`, eo: `endOffset`}
+	 */
+	getDragEventLocationRange(e: DragEvent): {
+		sc: Node;
+		so: number;
+		ec: Node;
+		eo: number;
+	};
+	/**
+	 * @description Scroll to the corresponding selection or range position.
+	 * @param {Selection|Range|Node} ref selection or range object
+	 * @param {Object<string, *>} [scrollOption] option of scrollTo
+	 * @example
+	 * // Scroll to current selection smoothly
+	 * editor.selection.scrollTo(editor.selection.get());
+	 *
+	 * // Scroll to specific node
+	 * const targetNode = document.querySelector('.target-element');
+	 * editor.selection.scrollTo(targetNode);
+	 *
+	 * // Scroll with custom options
+	 * editor.selection.scrollTo(editor.selection.getRange(), {
+	 *   behavior: 'auto',
+	 *   block: 'center'
+	 * });
+	 */
+	scrollTo(
+		ref: Selection | Range | Node,
+		scrollOption?: {
+			[x: string]: any;
+		},
+	): void;
+	/**
+	 * @description Normalizes and resets the selection range to properly target text nodes instead of element nodes for accurate text editing.
+	 * @returns {boolean} Returns `false` if there is no valid selection.
+	 */
+	resetRangeToTextNode(): boolean;
+	/**
+	 * @description Saving the range object and the currently selected node of editor
+	 */
+	init(): HTMLInputElement;
+	/**
+	 * @internal
+	 * @description Sets focus to the editor's wysiwyg contenteditable area and restores the last selection range within iframe context.
+	 */
+	__focus(): void;
+	/**
+	 * @internal
+	 * @description Initialize the scroll information when the editor first loads
+	 */
+	__init(): void;
+	#private;
+}

package/types/core/logic/panel/menu.d.ts

@@ -0,0 +1,93 @@
+import type {} from '../../../typedef';
+export default Menu;
+/**
+ * @description Dropdown and container menu management class
+ */
+declare class Menu {
+	/**
+	 * @constructor
+	 * @param {SunEditor.Kernel} kernel
+	 */
+	constructor(kernel: SunEditor.Kernel);
+	/** @type {Object<string, HTMLElement>} */
+	targetMap: {
+		[x: string]: HTMLElement;
+	};
+	index: number;
+	menus: any[];
+	currentButton: HTMLButtonElement;
+	currentDropdown: HTMLElement;
+	currentDropdownActiveButton: HTMLButtonElement;
+	currentDropdownName: string;
+	currentDropdownType: string;
+	currentContainer: HTMLElement;
+	currentContainerActiveButton: HTMLButtonElement;
+	currentContainerName: string;
+	currentDropdownPlugin: any;
+	/**
+	 * @description Method for managing dropdown element.
+	 * - You must add the `dropdown` element using this method at custom plugin.
+	 * @param {{key: string, type: string}} classObj Class object
+	 * @param {Node} menu Dropdown element
+	 */
+	initDropdownTarget(
+		{
+			key,
+			type,
+		}: {
+			key: string;
+			type: string;
+		},
+		menu: Node,
+	): void;
+	/**
+	 * @description Opens the dropdown menu for the specified button.
+	 * @param {Node} button Dropdown's button element to call
+	 */
+	dropdownOn(button: Node): void;
+	/**
+	 * @description Closes the currently open dropdown menu.
+	 */
+	dropdownOff(): void;
+	/**
+	 * @description Shows a previously hidden dropdown menu that is still in `on` state.
+	 * - Only works when a dropdown is active (`currentButton` exists)
+	 * - Re-displays the dropdown that was hidden by `dropdownHide()`
+	 * - Recalculates menu position by calling `dropdownOn()` again
+	 */
+	dropdownShow(): void;
+	/**
+	 * @description Temporarily hides the currently active dropdown menu without closing it.
+	 * - Unlike `dropdownOff()`, this does not clear the dropdown state or event listeners
+	 * - The dropdown remains `on` but visually hidden
+	 * - Use `dropdownShow()` to make it visible again
+	 */
+	dropdownHide(): void;
+	/**
+	 * @description Opens the menu container for the specified button.
+	 * @param {Node} button Container's button element to call
+	 */
+	containerOn(button: Node): void;
+	/**
+	 * @description Closes the currently open menu container.
+	 */
+	containerOff(): void;
+	/**
+	 * @internal
+	 * @description Reset the menu position.
+	 * @param {Node} element Button element
+	 * @param {HTMLElement} menu Menu element
+	 */
+	__resetMenuPosition(element: Node, menu: HTMLElement): void;
+	/**
+	 * @internal
+	 * @description Restore the last menu position using previously stored button and menu elements.
+	 */
+	__restoreMenuPosition(): void;
+	/**
+	 * @internal
+	 * @description Destroy the Menu instance and release memory
+	 */
+	_destroy(): void;
+	#private;
+}