suneditor 3.0.0-rc.4 → 3.0.0

package/src/core/logic/dom/nodeTransform.js

@@ -301,6 +301,8 @@ class NodeTransform {
 	 * @description Remove nested tags without other child nodes.
 	 * @param {Node} element Element object
 	 * @param {?(((current: Node) => boolean)|string)} [validation] Validation function / String(`tag1|tag2..`) / If `null`, all tags are applicable.
+	 * @example
+	 * editor.$.nodeTransform.mergeNestedTags(parentElement, (current) => current.nodeName === 'SPAN');
 	 */
 	mergeNestedTags(element, validation) {
 		if (typeof validation === 'string') {
@@ -419,6 +421,17 @@ class NodeTransform {
 	 * @param {SunEditor.NodeCollection} nodeArray An array of nodes to clone. The first node in the array will be the top-level parent.
 	 * @param {?(current: Node) => boolean} [validate] A validate function.
 	 * @returns {{ parent: Node, inner: Node }} An object containing the top-level parent node and the innermost child node.
+	 * @example
+	 * // [div, span, em] → <div><span><em></em></span></div> (cloned)
+	 * const { parent, inner } = editor.$.nodeTransform.createNestedNode([div, span, em]);
+	 * // parent = div (top), inner = em (innermost)
+	 *
+	 * // validate: skip nodes that fail the condition
+	 * const { parent, inner } = editor.$.nodeTransform.createNestedNode(
+	 *   [div, span, em],
+	 *   (node) => node.nodeName !== 'SPAN'
+	 * );
+	 * // Result: <div><em></em></div> (SPAN excluded)
 	 */
 	createNestedNode(nodeArray, validate) {
 		if (typeof validate !== 'function') validate = () => true;

package/src/core/logic/dom/offset.js

@@ -201,6 +201,7 @@ class Offset {
 	}
 
 	/**
+	 * @deprecated
 	 * @description Gets the current editor-relative scroll offset.
 	 * @param {?Node} [node] Target element.
 	 * @returns {OffsetGlobalScrollInfo} Global scroll information.
@@ -357,41 +358,67 @@ class Offset {
 	 * @param {HTMLElement} e_container Element's root container
 	 * @param {HTMLElement} target Target element to position against
 	 * @param {HTMLElement} t_container Target's root container
+	 * @param {Object} [opts] Options
+	 * @param {boolean} [opts.preferUp=false] Open upward by default (for bottom toolbar)
 	 */
-	setRelPosition(element, e_container, target, t_container) {
+	setRelPosition(element, e_container, target, t_container, { preferUp } = {}) {
 		const isFixedContainer = /^fixed$/i.test(_w.getComputedStyle(t_container).position);
 		const tGlobal = this.getGlobal(target);
 
 		// top
 		if (isFixedContainer) {
 			element.style.position = 'fixed';
-			element.style.top = `${tGlobal.fixedTop + tGlobal.height}px`;
+			if (preferUp) {
+				element.style.top = `${tGlobal.fixedTop - element.offsetHeight}px`;
+			} else {
+				element.style.top = `${tGlobal.fixedTop + tGlobal.height}px`;
+			}
 		} else {
 			element.style.position = '';
 
 			const isSameContainer = t_container.contains(element);
 			const containerTop = isSameContainer ? this.getGlobal(e_container).top : 0;
 			const elHeight = element.offsetHeight;
-			const scrollTop = this.getGlobalScroll().top;
+			const scrollTop = _w.scrollY;
 			const bt = tGlobal.top;
 
-			const menuHeight_bottom = getClientSize(_d).h - (containerTop - scrollTop + bt + target.offsetHeight);
-			if (menuHeight_bottom < elHeight) {
-				let menuTop = -1 * (elHeight - bt + 3);
-				const insTop = containerTop - scrollTop + menuTop;
-				const menuHeight_top = elHeight + (insTop < 0 ? insTop : 0);
-
-				if (menuHeight_top > menuHeight_bottom) {
-					element.style.height = `${menuHeight_top}px`;
-					menuTop = -1 * (menuHeight_top - bt + 3);
+			if (preferUp) {
+				// Try to open above
+				const menuHeight_top = containerTop - scrollTop + bt;
+				if (menuHeight_top < elHeight) {
+					// Not enough space above — try below
+					const menuHeight_bottom = getClientSize(_d).h - (containerTop - scrollTop + bt + target.offsetHeight);
+					if (menuHeight_bottom >= elHeight) {
+						element.style.top = `${bt + target.offsetHeight}px`;
+					} else if (menuHeight_bottom > menuHeight_top) {
+						element.style.height = `${menuHeight_bottom}px`;
+						element.style.top = `${bt + target.offsetHeight}px`;
+					} else {
+						element.style.height = `${menuHeight_top}px`;
+						element.style.top = `${-1 * (menuHeight_top - bt + 3)}px`;
+					}
 				} else {
-					element.style.height = `${menuHeight_bottom}px`;
-					menuTop = bt + target.offsetHeight;
+					element.style.top = `${bt - elHeight}px`;
 				}
-
-				element.style.top = `${menuTop}px`;
 			} else {
-				element.style.top = `${bt + target.offsetHeight}px`;
+				const menuHeight_bottom = getClientSize(_d).h - (containerTop - scrollTop + bt + target.offsetHeight);
+				if (menuHeight_bottom < elHeight) {
+					let menuTop = -1 * (elHeight - bt + 3);
+					const insTop = containerTop - scrollTop + menuTop;
+					const menuHeight_top = elHeight + (insTop < 0 ? insTop : 0);
+
+					if (menuHeight_top > menuHeight_bottom) {
+						element.style.height = `${menuHeight_top}px`;
+						menuTop = -1 * (menuHeight_top - bt + 3);
+					} else {
+						element.style.height = `${menuHeight_bottom}px`;
+						menuTop = bt + target.offsetHeight;
+					}
+
+					element.style.top = `${menuTop}px`;
+				} else {
+					element.style.top = `${bt + target.offsetHeight}px`;
+				}
 			}
 		}
 
@@ -425,15 +452,20 @@ class Offset {
 	 * @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 {{left:number, right:number, top:number}} [params.addOffset={left:0, right: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}
+	 * @example
+	 * const result = editor.$.offset.setAbsPosition(controller, targetElement, {
+	 *   position: 'bottom', inst: this, addOffset: { left: 0, right: 0, top: 0 }
+	 * });
 	 */
 	setAbsPosition(element, target, params) {
 		const addOffset = {
 			left: 0,
+			right: 0,
 			top: 0,
 			...params.addOffset,
 		};
@@ -478,7 +510,9 @@ class Offset {
 		const { rmt, rmb, bMargin, rt } = this.#getVMargin(tmtw, tmbw, toolbarH, clientSize, targetRect, isTextSelection, isToolbarTarget);
 		if ((isWWTarget && (rmb - statusBarH + targetH <= 0 || rmt + rt + targetH - (this.#$.toolbar.isSticky && isInlineTarget ? toolbarH : 0) <= 0)) || rmt + targetH < 0) return;
 
-		const isSticky = this.#$.toolbar.isSticky && this.#context.get('toolbar_main').style.display !== 'none' && (!headLess || this.#frameContext.get('topArea').getBoundingClientRect().top <= th);
+		const topAreaRect = this.#frameContext.get('topArea').getBoundingClientRect();
+		const isStickyVisible = this.#store.mode.isBottom ? topAreaRect.bottom >= _w.innerHeight - th : topAreaRect.top <= th;
+		const isSticky = this.#$.toolbar.isSticky && this.#context.get('toolbar_main').style.display !== 'none' && (!headLess || isStickyVisible);
 		let t = addOffset.top;
 		let y = 0;
 		let arrowDir = '';
@@ -504,7 +538,7 @@ class Offset {
 		else {
 			arrowDir = 'down';
 			t += targetRect.top - elH - ah + wScrollY;
-			y = (isSticky ? targetRect.top - toolbarH : rmt) - elH - ah;
+			y = (isSticky && !this.#store.mode.isBottom ? targetRect.top - toolbarH : rmt) - elH - ah;
 			// change to [bottom] position
 			if (y - siblingH < 0) {
 				arrowDir = 'up';
@@ -536,7 +570,7 @@ class Offset {
 			arrow.style.right = '';
 		}
 
-		let l = addOffset.left;
+		let l = addOffset.left || (addOffset.right ? (isLTR ? addOffset.right - element.offsetWidth : element.offsetWidth - addOffset.right) : 0);
 		let x = 0;
 		let ax = 0;
 		let awLimit = 0;
@@ -591,6 +625,9 @@ class Offset {
 	 * @param {"bottom"|"top"} [options.position="bottom"] Position ('bottom'|'top')
 	 * @param {number} [options.addTop=0] Additional top offset
 	 * @returns {boolean} Success / Failure
+	 * @example
+	 * const success = editor.$.offset.setRangePosition(toolbar, null, { position: 'bottom', addTop: 0 });
+	 * if (!success) toolbar.style.display = 'none';
 	 */
 	setRangePosition(element, range, { position, addTop } = {}) {
 		element.style.top = '-10000px';
@@ -604,12 +641,13 @@ class Offset {
 
 		const isFullScreen = this.#frameContext.get('isFullScreen');
 		const topArea = this.#frameContext.get('topArea');
+		const isInCarrier = this.#carrierWrapper.contains(element);
 		const rects = rectsObj.rects;
 		const scrollLeft = isFullScreen ? 0 : rectsObj.scrollLeft;
 		const scrollTop = isFullScreen ? 0 : rectsObj.scrollTop;
-		const editorWidth = topArea.offsetWidth;
+		const editorWidth = isInCarrier ? getClientSize(_d).w : topArea.offsetWidth;
 		const offsets = this.getGlobal(topArea);
-		const editorLeft = offsets.left;
+		const editorLeft = isInCarrier ? 0 : offsets.left;
 		const toolbarWidth = element.offsetWidth;
 		const toolbarHeight = element.offsetHeight;
 
@@ -733,33 +771,58 @@ class Offset {
 		bMargin = clientSize.h - targetRect.bottom;
 		const editorOffset = this.getGlobal();
 
+		const isBottom = this.#store.mode.isBottom;
 		if (!isTextSelection) {
 			const emt = editorOffset.fixedTop > 0 ? editorOffset.fixedTop : 0;
 			const emb = _w.innerHeight - (editorOffset.fixedTop + editorOffset.height);
 			rt = !isToolbarTarget && (this.#$.toolbar.isSticky || !this.#$.toolbar.isBalloonMode) ? toolbarH : 0;
-			rmt = tMargin - (!isToolbarTarget ? emt : 0) - rt;
-			rmb = bMargin - (emb > 0 ? emb : 0);
+			if (isBottom) {
+				rmt = tMargin - (!isToolbarTarget ? emt : 0);
+				rmb = bMargin - (emb > 0 ? emb : 0) - rt;
+			} else {
+				rmt = tMargin - (!isToolbarTarget ? emt : 0) - rt;
+				rmb = bMargin - (emb > 0 ? emb : 0);
+			}
 		} else {
 			rt = !isToolbarTarget && !this.#$.toolbar.isSticky && !this.#options.get('toolbar_container') ? toolbarH : 0;
 			const wst = !isIframe ? editorOffset.top - _w.scrollY + rt : 0;
 			const wsb = !isIframe ? this.#store.get('currentViewportHeight') - (editorOffset.top + editorOffset.height - _w.scrollY) : 0;
 			let st = wst;
-			if (toolbarH > wst) {
-				if (this.#$.toolbar.isSticky) {
-					st = toolbarH;
+			let sb = wsb;
+			if (isBottom) {
+				if (toolbarH > wsb) {
+					if (this.#$.toolbar.isSticky) {
+						sb = toolbarH;
+					} else {
+						sb = wsb + toolbarH;
+					}
+				} else if (this.#options.get('toolbar_container') && !this.#$.toolbar.isSticky) {
+					toolbarH = 0;
 				} else {
-					st = wst + toolbarH;
+					sb = wsb + toolbarH;
 				}
-			} else if (this.#options.get('toolbar_container') && !this.#$.toolbar.isSticky) {
-				toolbarH = 0;
+
+				rmt = targetRect.top - (wwRects.top - wst);
+				rmb = wwRects.bottom - (targetRect.bottom - sb) + toolbarH;
+				rmb = rmb > 0 ? rmb : rmb - toolbarH;
 			} else {
-				st = wst + toolbarH;
-			}
+				if (toolbarH > wst) {
+					if (this.#$.toolbar.isSticky) {
+						st = toolbarH;
+					} else {
+						st = wst + toolbarH;
+					}
+				} else if (this.#options.get('toolbar_container') && !this.#$.toolbar.isSticky) {
+					toolbarH = 0;
+				} else {
+					st = wst + toolbarH;
+				}
 
-			rmt = targetRect.top - (wwRects.top - st) + toolbarH;
-			rmb = wwRects.bottom - (targetRect.bottom - wsb);
-			// display margin
-			rmt = rmt > 0 ? rmt : rmt - toolbarH;
+				rmt = targetRect.top - (wwRects.top - st) + toolbarH;
+				rmb = wwRects.bottom - (targetRect.bottom - wsb);
+				// display margin
+				rmt = rmt > 0 ? rmt : rmt - toolbarH;
+			}
 		}
 
 		return {

package/src/core/logic/dom/selection.js

@@ -210,6 +210,9 @@ class Selection_ {
 	 * - 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.
+	 * @example
+	 * const nearRange = editor.$.selection.getNearRange(targetNode);
+	 * if (nearRange) editor.$.selection.setRange(nearRange.container, nearRange.offset, nearRange.container, nearRange.offset);
 	 */
 	getNearRange(target) {
 		const next = target.nextSibling;
@@ -249,6 +252,9 @@ class Selection_ {
 	/**
 	 * @description Get current select node
 	 * @returns {HTMLElement|Text}
+	 * @example
+	 * const node = editor.$.selection.getNode();
+	 * const line = editor.$.format.getLine(node);
 	 */
 	getNode() {
 		if (!this.#frameContext.get('wysiwyg').contains(this.selectionNode)) this.init();
@@ -286,10 +292,9 @@ class Selection_ {
 	getRects(target, position) {
 		const targetAbs = dom.check.isElement(/** @type {Node} */ (target)) ? _w.getComputedStyle(target).position === 'absolute' : false;
 		target = /** @type {Range} */ (!target || dom.check.isText(/** @type {Node} */ (target)) ? this.getRange() : target);
-		const globalScroll = this.#$.offset.getGlobalScroll();
 		let isStartPosition = position === 'start';
-		let scrollLeft = globalScroll.left;
-		let scrollTop = globalScroll.top;
+		let scrollLeft = _w.scrollX;
+		let scrollTop = _w.scrollY;
 
 		let rects = /** @type {*} */ (target).getClientRects();
 		rects = rects[isStartPosition ? 0 : rects.length - 1];
@@ -373,7 +378,7 @@ class Selection_ {
 	/**
 	 * @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
+	 * @param {ScrollIntoViewOptions & {noFocus?: boolean}} [scrollOption] Scroll options. Extends `ScrollIntoViewOptions` (`behavior`, `block`, `inline`) with `noFocus` to prevent focus change.
 	 * @example
 	 * // Scroll to current selection smoothly
 	 * editor.selection.scrollTo(editor.selection.get());
@@ -389,10 +394,18 @@ class Selection_ {
 	 * });
 	 */
 	scrollTo(ref, scrollOption) {
+		const noFocus = scrollOption?.noFocus;
+
 		if (this.#instanceCheck.isSelection(ref)) {
 			ref = ref.getRangeAt(0);
 		} else if (this.#instanceCheck.isNode(ref)) {
-			ref = this.setRange(ref, 1, ref, 1);
+			if (noFocus) {
+				const range = this.#frameContext.get('_wd').createRange();
+				range.selectNodeContents(ref);
+				ref = range;
+			} else {
+				ref = this.setRange(ref, 1, ref, 1);
+			}
 		} else if (typeof ref?.startContainer === 'undefined') {
 			console.warn('[SUNEDITOR.html.scrollTo.warn] "selectionRange" must be Selection or Range or Node object.', ref);
 		}
@@ -401,6 +414,7 @@ class Selection_ {
 		if (!el) return;
 
 		scrollOption = { behavior: 'smooth', block: 'nearest', inline: 'nearest', ...scrollOption };
+		delete scrollOption.noFocus;
 
 		const ww = this.#frameContext.get('_ww');
 		const wwFrame = this.#frameContext.get('wysiwygFrame');
@@ -408,6 +422,7 @@ class Selection_ {
 		const isAutoHeight = !this.#store.get('isScrollable')(this.#frameContext);
 		const viewportHeight = this.#store.get('currentViewportHeight');
 		const scrollY = isAutoHeight ? _w.scrollY : isIframe ? ww.scrollY : wwFrame.scrollTop;
+		const isBottom = this.#store.mode.isBottom;
 		const realToolbarHeight = this.#context.get('toolbar_main').offsetHeight;
 		const toolbarHeight = this.#$.toolbar.isSticky ? realToolbarHeight : 0;
 		const positionToolbarHeight = this.#$.toolbar.isSticky ? toolbarHeight + this.#options.get('toolbar_sticky') : toolbarHeight;
@@ -417,8 +432,18 @@ class Selection_ {
 			el?.scrollIntoView(scrollOption);
 
 			if (scrollOption?.behavior === 'auto' && scrollY !== _w.scrollY) {
-				if (positionToolbarHeight && scrollY > _w.scrollY) {
-					_w.scrollBy(0, -positionToolbarHeight);
+				if (positionToolbarHeight) {
+					if (isBottom) {
+						// bottom toolbar covers the bottom — scroll down more so the element clears the toolbar
+						if (scrollY < _w.scrollY) {
+							_w.scrollBy(0, positionToolbarHeight);
+						}
+					} else {
+						// top toolbar covers the top — scroll up more so the element clears the toolbar
+						if (scrollY > _w.scrollY) {
+							_w.scrollBy(0, -positionToolbarHeight);
+						}
+					}
 				} else if (isAutoHeight) {
 					_w.scrollBy(0, statusbarHeight);
 				}
@@ -429,55 +454,62 @@ class Selection_ {
 
 		// --- When there is no upper scroll and it is an iframe ---
 		const PADDING = this.#scrollMargin;
-		const viewHeight = isAutoHeight ? viewportHeight : wwFrame.offsetHeight;
-		const elH = el.offsetHeight || 0;
+		// Reduce effective viewport height by toolbar+offset when bottom toolbar is sticky
+		const viewHeight = isAutoHeight ? viewportHeight - (isBottom ? positionToolbarHeight : 0) : wwFrame.offsetHeight;
+
+		// Use range rect for accurate height — el.offsetHeight includes nested children (e.g. nested lists)
+		const refRect = ref?.getBoundingClientRect?.();
+		const elH = (refRect?.height > 0 ? refRect.height : el.offsetHeight) || 0;
 
 		const behavior = scrollOption?.behavior;
+		const topToolbarH = isBottom ? 0 : positionToolbarHeight;
 		if (isAutoHeight) {
 			if (isIframe) {
 				const rect = this.getRects(ref, 'end').rects;
-				const topMargin = rect.top + elH - positionToolbarHeight;
+				const topMargin = rect.top + elH - topToolbarH;
 				const bottomMargin = viewHeight - PADDING - (rect.top + elH);
 				if (topMargin >= 0 && bottomMargin >= 0) return;
 
 				const newScrollTop = scrollY - (topMargin < 0 ? -(topMargin - PADDING) : bottomMargin);
 				_w.scrollTo({
-					top: newScrollTop < scrollY ? newScrollTop - positionToolbarHeight : newScrollTop,
+					top: newScrollTop < scrollY ? newScrollTop - topToolbarH : newScrollTop,
 					behavior,
 				});
 			} else {
 				const rect = this.#$.offset.getGlobal(el);
 				const scrollMargin = viewHeight + scrollY - rect.top - elH;
 
-				if (scrollMargin - PADDING > 0 && viewHeight > scrollMargin + PADDING + positionToolbarHeight) return;
+				if (scrollMargin - PADDING > 0 && viewHeight > scrollMargin + PADDING + topToolbarH) return;
 
 				const newScrollTop = scrollMargin <= PADDING ? scrollY - scrollMargin + PADDING + statusbarHeight : scrollY - scrollMargin + (viewHeight - elH - PADDING);
 				_w.scrollTo({
-					top: newScrollTop < scrollY ? newScrollTop - positionToolbarHeight : newScrollTop,
+					top: newScrollTop < scrollY ? newScrollTop - topToolbarH : newScrollTop,
 					behavior,
 				});
 			}
 		} else {
-			// local scroll
-			const { rects } = this.getRects(el, 'start');
-			const { top } = this.#$.offset.getLocal(el);
-			const innerTop = top < 0 && rects.top < 0 ? top : rects.top;
+			// local scroll — use range rect for accurate position (el.getBoundingClientRect includes nested children)
+			const hasRefRect = refRect?.height > 0;
+			const targetTop = hasRefRect ? refRect.top : el.getBoundingClientRect().top;
+			const innerTop = isIframe ? targetTop : targetTop - wwFrame.getBoundingClientRect().top;
 
 			const keepLocalScroll = innerTop - PADDING > 0 && innerTop + PADDING <= viewHeight;
-			const rectScroll = innerTop - PADDING > 0 ? innerTop + PADDING - viewHeight : innerTop - (toolbarHeight + elH);
+			const rectScroll = isBottom ? (innerTop - PADDING > 0 ? innerTop + PADDING - viewHeight + toolbarHeight : innerTop - elH) : innerTop - PADDING > 0 ? innerTop + PADDING - viewHeight : innerTop - (toolbarHeight + elH);
 			let newScrollTop = scrollY + rectScroll;
 
 			// frame scroll
 			const gy = _w.scrollY;
 			const globalRect = this.#$.offset.getGlobal();
-			const topMargin = gy - globalRect.top + realToolbarHeight;
-			const bottomMargin = globalRect.top + globalRect.height - (gy + viewportHeight) + realToolbarHeight;
+			const topToolbarFrame = isBottom ? 0 : realToolbarHeight;
+			const bottomToolbarFrame = isBottom ? realToolbarHeight : 0;
+			const topMargin = gy - globalRect.top + topToolbarFrame;
+			const bottomMargin = globalRect.top + globalRect.height - (gy + viewportHeight) + bottomToolbarFrame;
 
 			// set frame scroll
 			if (topMargin > 0) {
 				const newFrameY = (keepLocalScroll ? innerTop : innerTop + scrollY - newScrollTop) - elH - PADDING - topMargin;
 				if (newFrameY < 0) {
-					newScrollTop += realToolbarHeight;
+					newScrollTop += topToolbarFrame;
 					_w.scrollTo({
 						top: gy + newFrameY,
 						behavior: 'smooth',
@@ -487,7 +519,7 @@ class Selection_ {
 			if (bottomMargin > 0) {
 				const newFrameY = (keepLocalScroll ? innerTop : innerTop + scrollY - newScrollTop) + elH + PADDING - (globalRect.height - bottomMargin);
 				if (newFrameY > 0) {
-					newScrollTop += statusbarHeight;
+					newScrollTop += isBottom ? bottomToolbarFrame : statusbarHeight;
 					_w.scrollTo({
 						top: gy + newFrameY,
 						behavior: 'smooth',