suneditor 3.0.2 → 3.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "suneditor",
-	"version": "3.0.2",
+	"version": "3.0.3",
 	"description": "Vanilla JavaScript based WYSIWYG web editor",
 	"author": "Yi JiHong",
 	"license": "MIT",

package/src/assets/suneditor.css

@@ -916,13 +916,13 @@
 .sun-editor .se-toolbar.se-toolbar-bottom {
 	top: auto;
 	bottom: 0;
-	outline-offset: -1px;
 }
 
 /* Bottom toolbar: more layer opens above buttons */
 .sun-editor .se-toolbar.se-toolbar-bottom .se-btn-tray {
 	display: flex;
 	flex-wrap: wrap;
+	padding: 4px 3px;
 }
 
 .sun-editor .se-toolbar.se-toolbar-bottom .se-btn-tray > .se-toolbar-more-layer {
@@ -934,6 +934,7 @@
 .sun-editor .se-toolbar.se-toolbar-bottom .se-toolbar-more-layer .se-more-layer {
 	border-top: none;
 	border-bottom: 1px solid var(--se-main-divider-color);
+	margin-bottom: 4px;
 }
 
 /* JS fallback sticky for bottom */

package/src/core/event/eventOrchestrator.js

@@ -138,6 +138,21 @@ class EventOrchestrator extends KernelInjector {
 		}, 250);
 	}
 
+	/**
+	 * @description Toggle toolbar-balloon with delay (debounced for selectionchange).
+	 */
+	#toggleToolbarBalloonDelay() {
+		if (this.#balloonDelay) {
+			_w.clearTimeout(this.#balloonDelay);
+		}
+
+		this.#balloonDelay = _w.setTimeout(() => {
+			_w.clearTimeout(this.#balloonDelay);
+			this.#balloonDelay = null;
+			this._toggleToolbarBalloon();
+		}, 250);
+	}
+
 	/**
 	 * @internal
 	 * @description Show or hide the toolbar-balloon.
@@ -909,17 +924,23 @@ class EventOrchestrator extends KernelInjector {
 	}
 
 	#OnResize_viewport() {
-		if (isMobile && this.#options.get('toolbar_sticky') > -1) {
+		if (isMobile && this.#options.get('_toolbar_sticky') > -1) {
 			this.#toolbar._resetSticky();
 			this.#menu.__restoreMenuPosition();
 		}
 
 		this.#scrollContainer();
+
+		const prevHeight = this.#store.get('currentViewportHeight');
 		this.__setViewportSize();
+
+		if (isMobile && prevHeight > 0 && prevHeight - _w.visualViewport.height > 100 && this.#store.get('hasFocus')) {
+			this.$.selection.scrollTo(this.$.selection.getRange(), { behavior: 'auto', block: 'nearest', inline: 'nearest' });
+		}
 	}
 
 	#OnScroll_window() {
-		if (this.#options.get('toolbar_sticky') > -1) {
+		if (this.#options.get('_toolbar_sticky') > -1) {
 			this.#toolbar._resetSticky();
 		}
 
@@ -938,7 +959,7 @@ class EventOrchestrator extends KernelInjector {
 	}
 
 	#OnMobileScroll_viewport() {
-		if (this.#options.get('toolbar_sticky') > -1) {
+		if (this.#options.get('_toolbar_sticky') > -1) {
 			this.#toolbar._resetSticky();
 			this.#menu.__restoreMenuPosition();
 		}
@@ -959,6 +980,11 @@ class EventOrchestrator extends KernelInjector {
 				this.$.selection.init();
 				this.applyTagEffect();
 
+				// balloon toolbar - touch devices
+				if (isTouchDevice && (this.#store.mode.isBalloon || this.#store.mode.isSubBalloon)) {
+					this.#toggleToolbarBalloonDelay();
+				}
+
 				// document type
 				if (root.has('documentType_use_header')) {
 					const el = dom.query.getParentElement(this.$.selection.selectionNode, this.$.format.isLine.bind(this.$.format));

package/src/core/event/ports.js

@@ -158,14 +158,14 @@ export function makePorts(inst, { _styleNodes }) {
 
 		// === enter event specific ===
 		/**
-		 * @description Scrolls the editor view to the caret position after pressing `Enter`. (Ignored on mobile devices)
+		 * @description Scrolls the editor view to the caret position after pressing `Enter`.
 		 * @param {Range} range Range object
 		 */
 		enterScrollTo(range) {
 			ui._iframeAutoHeight(frameContext);
 
 			// scroll to
-			if (isMobile && inst.scrollparents.length > 0) return;
+			// if (isMobile && inst.scrollparents.length > 0) return;
 			selection.scrollTo(range, { behavior: 'auto', block: 'nearest', inline: 'nearest' });
 		},
 		/**

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

@@ -2134,6 +2134,14 @@ function _isSafeURL(url) {
 	return _SAFE_URL_PROTOCOL.test(normalized) || !_RE_COLON.test(normalized);
 }
 
+/**
+ * @description Checks whether an HTML attribute string is safe from XSS injection.
+ * - Non-URL attributes (anything other than `href` or `src`) are always safe.
+ * - For URL attributes, extracts the URL value and delegates to {@link _isSafeURL}
+ *   to verify the protocol against the allowed whitelist.
+ * @param {string} attr A single attribute string (e.g. `href="https://example.com"`, `class="foo"`)
+ * @returns {boolean} `true` if the attribute is safe, `false` if it contains a dangerous URL protocol.
+ */
 function _isSafeAttribute(attr) {
 	if (!_URL_ATTR_PATTERN.test(attr)) return true;
 

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

@@ -503,7 +503,7 @@ class Offset {
 		const th = this.#context.get('toolbar_main').offsetHeight;
 		const containerToolbar = this.#options.get('toolbar_container');
 		const headLess = this.#store.mode.isBalloon || this.#store.mode.isInline || containerToolbar;
-		const toolbarH = (containerToolbar && globalTop - wScrollY - th > 0) || (!this.#$.toolbar.isSticky && headLess) ? 0 : th + (this.#$.toolbar.isSticky ? this.#options.get('toolbar_sticky') : 0);
+		const toolbarH = (containerToolbar && globalTop - wScrollY - th > 0) || (!this.#$.toolbar.isSticky && headLess) ? 0 : th + (this.#$.toolbar.isSticky ? this.#options.get('_toolbar_sticky') : 0);
 		const statusBarH = this.#frameContext.get('statusbar')?.offsetHeight || 0;
 
 		// check margin

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

@@ -425,7 +425,7 @@ class Selection_ {
 		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;
+		const positionToolbarHeight = this.#$.toolbar.isSticky ? toolbarHeight + this.#options.get('_toolbar_sticky') : toolbarHeight;
 		const statusbarHeight = this.#frameContext.get('statusbar')?.offsetHeight || 0;
 
 		if (this.#hasScrollParents) {

package/src/core/logic/panel/finder.js

@@ -154,7 +154,7 @@ class Finder {
 	 */
 	#updateStickyTop() {
 		if (!this.#isOpen || !this.#panel) return;
-		const stickyTop = this.#$.options.get('toolbar_sticky');
+		const stickyTop = this.#$.options.get('_toolbar_sticky');
 		if (this.#store.mode.isBottom) {
 			this.#panel.style.top = 'auto';
 			this.#panel.style.bottom = stickyTop >= 0 ? stickyTop + this.#$.context.get('toolbar_main').offsetHeight + 'px' : '0px';

package/src/core/logic/panel/toolbar.js

@@ -28,6 +28,7 @@ class Toolbar {
 
 	#useCSSSticky = false;
 	#_isStickyFlag = false;
+	#_cssStickyShifted = false;
 
 	/**
 	 * @constructor
@@ -88,7 +89,7 @@ class Toolbar {
 
 		// CSS sticky: non-balloon, non-inline, non-container, sticky enabled
 		const isStickyPosible = !this.isSub && !balloon && !inline;
-		const stickyTop = this.#options.get('toolbar_sticky');
+		const stickyTop = this.#options.get('_toolbar_sticky');
 
 		this.#useCSSSticky = isStickyPosible && stickyTop >= 0 && !this.#options.get('toolbar_container') && typeof CSS !== 'undefined' && CSS.supports('position', 'sticky');
 
@@ -119,14 +120,15 @@ class Toolbar {
 	 */
 	get isSticky() {
 		if (this.isSub) return false;
-		const stickyTop = this.#options.get('toolbar_sticky');
+		const stickyTop = this.#options.get('_toolbar_sticky');
 		if (stickyTop < 0) return false;
 
 		if (this.#useCSSSticky) {
 			const toolbar = this.#context.get(this.keyName.main);
 			if (!toolbar || toolbar.offsetWidth === 0 || toolbar.style.display === 'none') return false;
 			if (this.isBottomMode) {
-				return toolbar.getBoundingClientRect().bottom >= _w.innerHeight - stickyTop - 1;
+				const viewportHeight = this.#isViewPortSize ? _w.visualViewport.height : _w.innerHeight;
+				return toolbar.getBoundingClientRect().bottom >= viewportHeight - stickyTop - 1;
 			}
 			return toolbar.getBoundingClientRect().top <= stickyTop + 1;
 		}
@@ -254,13 +256,16 @@ class Toolbar {
 	 * @description Reset the sticky toolbar position based on the editor state.
 	 */
 	_resetSticky() {
-		if (this.#useCSSSticky) return;
+		if (this.#useCSSSticky) {
+			this.#resetCSSStickyOffset();
+			return;
+		}
 
 		const wrapper = this.#frameContext.get('wrapper');
 		if (!wrapper) return;
 
 		const toolbar = this.#context.get(this.keyName.main);
-		const stickyTop = this.#options.get('toolbar_sticky');
+		const stickyTop = this.#options.get('_toolbar_sticky');
 		if (this.#frameContext.get('isFullScreen') || toolbar.offsetWidth === 0 || stickyTop < 0) return;
 
 		const currentScrollY = this.#isViewPortSize ? _w.visualViewport.pageTop : _w.scrollY;
@@ -485,11 +490,11 @@ class Toolbar {
 		}
 
 		if (this.isBottomMode) {
-			const toolbarBottomPosition = this.#options.get('toolbar_sticky') + this.#getViewportTop();
+			const toolbarBottomPosition = this.#options.get('_toolbar_sticky') + this.#getViewportTop();
 			toolbar.style.bottom = `${toolbarBottomPosition}px`;
 			toolbar.style.top = 'auto';
 		} else {
-			const toolbarTopPosition = this.#options.get('toolbar_sticky') + inlineOffset + this.#getViewportTop();
+			const toolbarTopPosition = this.#options.get('_toolbar_sticky') + inlineOffset + this.#getViewportTop();
 			toolbar.style.top = `${toolbarTopPosition}px`;
 		}
 		toolbar.style.width = this.isInlineMode ? this.inlineToolbarAttr.width : toolbar.offsetWidth + 'px';
@@ -508,6 +513,43 @@ class Toolbar {
 		return 0;
 	}
 
+	/**
+	 * @description Adjust CSS sticky toolbar position when the mobile virtual keyboard changes the visual viewport.
+	 */
+	#resetCSSStickyOffset() {
+		if (!this.#isViewPortSize) return;
+		// When the editor is inside a scrollable container (e.g., modal),
+		// position:sticky is relative to that container, not the viewport.
+		if (this.#kernel._eventOrchestrator.scrollparents.length > 0) return;
+
+		const viewportOffset = Math.round(_w.visualViewport.offsetTop);
+		if (viewportOffset === 0 && !this.#_cssStickyShifted) return;
+
+		const toolbar = this.#context.get(this.keyName.main);
+		const stickyOffset = this.#options.get('_toolbar_sticky_offset');
+
+		if (viewportOffset > 0) {
+			this.#_cssStickyShifted = true;
+			if (this.isBottomMode) {
+				const viewportBottom = Math.round(_w.innerHeight - _w.visualViewport.height - viewportOffset);
+				toolbar.style.bottom = stickyOffset + viewportBottom + 'px';
+				toolbar.style.top = 'auto';
+			} else {
+				toolbar.style.top = stickyOffset + viewportOffset + 'px';
+			}
+		} else {
+			// restore original CSS sticky value
+			this.#_cssStickyShifted = false;
+			const stickyTop = this.#options.get('_toolbar_sticky');
+			if (this.isBottomMode) {
+				toolbar.style.bottom = stickyTop + 'px';
+				toolbar.style.top = 'auto';
+			} else {
+				toolbar.style.top = stickyTop > 0 ? stickyTop + 'px' : '';
+			}
+		}
+	}
+
 	/**
 	 * @description Disable `sticky` toolbar mode.
 	 */

package/src/core/logic/panel/viewer.js

@@ -411,7 +411,7 @@ class Viewer {
 				this.#toolbarParent = null;
 			}
 
-			if (this.#options.get('toolbar_sticky') > -1) {
+			if (this.#options.get('_toolbar_sticky') > -1) {
 				dom.utils.removeClass(toolbar, 'se-toolbar-sticky');
 			}
 

package/src/core/schema/options.js

@@ -460,7 +460,22 @@ export const DEFAULTS = {
  * @property {boolean} [tabDisable=false] - Disables tab key input.
  * @property {string} [toolbar_width="auto"] - Toolbar width.
  * @property {?HTMLElement} [toolbar_container] - Container element for the toolbar.
- * @property {number} [toolbar_sticky=0] - Enables sticky toolbar with optional offset.
+ * @property {number|{top: number, offset: number}} [toolbar_sticky=0] - Enables sticky toolbar.
+ * - `number`: Sets the sticky top position (px). Use `-1` to disable sticky.
+ * - `{top, offset}`: `top` is the sticky position when the page header is visible.
+ * - `offset` is the sticky position when a virtual keyboard shifts the viewport (e.g., on tablets, touch devices).
+ * - When the virtual keyboard is active, `offset` replaces `top` so the toolbar doesn't leave a gap
+ * - for a page header that has scrolled out of view. Default `offset` is `0`.
+ * ```js
+ * // Basic usage — sticky at top with 0px offset
+ * toolbar_sticky: 0
+ *
+ * // Account for a 92px fixed/sticky site header
+ * toolbar_sticky: 92
+ *
+ * // 92px header on desktop, but 0px when virtual keyboard pushes the viewport
+ * toolbar_sticky: { top: 92, offset: 0 }
+ * ```
  * @property {boolean} [toolbar_hide=false] - Hides toolbar initially.
  * @property {Object} [subToolbar={}] - Sub-toolbar configuration. A secondary toolbar that appears on text selection.
  * @property {SunEditor.UI.ButtonList} [subToolbar.buttonList] - List of Sub-toolbar buttons, grouped by sub-arrays.
@@ -754,7 +769,7 @@ export const OPTION_FIXED_FLAG = {
 };
 
 /**
- * @typedef {'formatClosureBrLine' | 'formatBrLine' | 'formatLine' | 'formatClosureBlock' | 'formatBlock' | 'toolbar_width' | 'toolbar_container' | 'toolbar_sticky' | 'strictMode' | 'lineAttrReset'} TransformedOptionKeys
+ * @typedef {'formatClosureBrLine' | 'formatBrLine' | 'formatLine' | 'formatClosureBlock' | 'formatBlock' | 'toolbar_width' | 'toolbar_container' | '_toolbar_sticky' | '_toolbar_sticky_offset' | 'strictMode' | 'lineAttrReset'} TransformedOptionKeys
  */
 
 /**
@@ -776,7 +791,8 @@ export const OPTION_FIXED_FLAG = {
  * @property {{ reg: RegExp, str: string }} formatBlock
  * @property {string} toolbar_width
  * @property {HTMLElement|null} toolbar_container
- * @property {number} toolbar_sticky
+ * @property {number} _toolbar_sticky
+ * @property {number} _toolbar_sticky_offset
  * @property {StrictModeOptions} strictMode
  * @property {string[]} lineAttrReset
  */

package/src/core/section/constructor.js

@@ -616,7 +616,20 @@ export function InitOptions(options, editorTargets, plugins) {
 	/** Toolbar */
 	o.set('toolbar_width', options.toolbar_width ? (numbers.is(options.toolbar_width) ? options.toolbar_width + 'px' : options.toolbar_width) : 'auto');
 	o.set('toolbar_container', options.toolbar_container && !/inline/i.test(o.get('mode')) ? (typeof options.toolbar_container === 'string' ? _d.querySelector(options.toolbar_container) : options.toolbar_container) : null);
-	o.set('toolbar_sticky', /balloon/i.test(o.get('mode')) ? -1 : options.toolbar_sticky === undefined ? 0 : numbers.is(options.toolbar_sticky) ? numbers.get(options.toolbar_sticky, 0) : -1);
+
+	const _stickyOpt = options.toolbar_sticky;
+	const _isBalloon = /balloon/i.test(o.get('mode'));
+	if (_isBalloon) {
+		o.set('_toolbar_sticky', -1);
+		o.set('_toolbar_sticky_offset', 0);
+	} else if (_stickyOpt !== null && typeof _stickyOpt === 'object') {
+		o.set('_toolbar_sticky', numbers.get(_stickyOpt.top, 0));
+		o.set('_toolbar_sticky_offset', numbers.get(_stickyOpt.offset, 0));
+	} else {
+		o.set('_toolbar_sticky', _stickyOpt === undefined ? 0 : numbers.is(_stickyOpt) ? _stickyOpt : -1);
+		o.set('_toolbar_sticky_offset', 0);
+	}
+
 	o.set('toolbar_hide', !!options.toolbar_hide);
 
 	/** subToolbar */

package/src/modules/manager/ApiManager.js

@@ -180,6 +180,7 @@ class ApiManager {
 	 * @returns
 	 */
 	#normalizeUrl(url) {
+		if (!url) return '';
 		return url.replace(/([^:])\/+/g, '$1/').replace(/\/(\?|#|$)/, '$1');
 	}
 

package/types/core/event/ports.d.ts

@@ -166,7 +166,7 @@ export function makePorts(
 	formatAttrsTempCache: (attrs: any) => any;
 	setOnShortcutKey: (v: any) => any;
 	/**
-	 * @description Scrolls the editor view to the caret position after pressing `Enter`. (Ignored on mobile devices)
+	 * @description Scrolls the editor view to the caret position after pressing `Enter`.
 	 * @param {Range} range Range object
 	 */
 	enterScrollTo(range: Range): void;

package/types/core/schema/options.d.ts

@@ -406,7 +406,22 @@ export namespace DEFAULTS {
  * @property {boolean} [tabDisable=false] - Disables tab key input.
  * @property {string} [toolbar_width="auto"] - Toolbar width.
  * @property {?HTMLElement} [toolbar_container] - Container element for the toolbar.
- * @property {number} [toolbar_sticky=0] - Enables sticky toolbar with optional offset.
+ * @property {number|{top: number, offset: number}} [toolbar_sticky=0] - Enables sticky toolbar.
+ * - `number`: Sets the sticky top position (px). Use `-1` to disable sticky.
+ * - `{top, offset}`: `top` is the sticky position when the page header is visible.
+ * - `offset` is the sticky position when a virtual keyboard shifts the viewport (e.g., on tablets, touch devices).
+ * - When the virtual keyboard is active, `offset` replaces `top` so the toolbar doesn't leave a gap
+ * - for a page header that has scrolled out of view. Default `offset` is `0`.
+ * ```js
+ * // Basic usage — sticky at top with 0px offset
+ * toolbar_sticky: 0
+ *
+ * // Account for a 92px fixed/sticky site header
+ * toolbar_sticky: 92
+ *
+ * // 92px header on desktop, but 0px when virtual keyboard pushes the viewport
+ * toolbar_sticky: { top: 92, offset: 0 }
+ * ```
  * @property {boolean} [toolbar_hide=false] - Hides toolbar initially.
  * @property {Object} [subToolbar={}] - Sub-toolbar configuration. A secondary toolbar that appears on text selection.
  * @property {SunEditor.UI.ButtonList} [subToolbar.buttonList] - List of Sub-toolbar buttons, grouped by sub-arrays.
@@ -1201,9 +1216,29 @@ export type EditorBaseOptions = {
 	 */
 	toolbar_container?: HTMLElement | null;
 	/**
-	 * - Enables sticky toolbar with optional offset.
+	 * - Enables sticky toolbar.
+	 * - `number`: Sets the sticky top position (px). Use `-1` to disable sticky.
+	 * - `{top, offset}`: `top` is the sticky position when the page header is visible.
+	 * - `offset` is the sticky position when a virtual keyboard shifts the viewport (e.g., on tablets, touch devices).
+	 * - When the virtual keyboard is active, `offset` replaces `top` so the toolbar doesn't leave a gap
+	 * - for a page header that has scrolled out of view. Default `offset` is `0`.
+	 * ```js
+	 * // Basic usage — sticky at top with 0px offset
+	 * toolbar_sticky: 0
+	 *
+	 * // Account for a 92px fixed/sticky site header
+	 * toolbar_sticky: 92
+	 *
+	 * // 92px header on desktop, but 0px when virtual keyboard pushes the viewport
+	 * toolbar_sticky: { top: 92, offset: 0 }
+	 * ```
 	 */
-	toolbar_sticky?: number;
+	toolbar_sticky?:
+		| number
+		| {
+				top: number;
+				offset: number;
+		  };
 	/**
 	 * - Hides toolbar initially.
 	 */
@@ -1513,7 +1548,18 @@ export type InternalBaseOptions = {
 };
 export type EditorInitOptions = EditorBaseOptions & PrivateBaseOptions & EditorFrameOptions;
 export type AllBaseOptions = EditorBaseOptions & PrivateBaseOptions & InternalBaseOptions;
-export type TransformedOptionKeys = 'formatClosureBrLine' | 'formatBrLine' | 'formatLine' | 'formatClosureBlock' | 'formatBlock' | 'toolbar_width' | 'toolbar_container' | 'toolbar_sticky' | 'strictMode' | 'lineAttrReset';
+export type TransformedOptionKeys =
+	| 'formatClosureBrLine'
+	| 'formatBrLine'
+	| 'formatLine'
+	| 'formatClosureBlock'
+	| 'formatBlock'
+	| 'toolbar_width'
+	| 'toolbar_container'
+	| '_toolbar_sticky'
+	| '_toolbar_sticky_offset'
+	| 'strictMode'
+	| 'lineAttrReset';
 export type StrictModeOptions = {
 	/**
 	 * - Filters disallowed HTML tags (`elementWhitelist`/`elementBlacklist`)
@@ -1563,7 +1609,8 @@ export type TransformedOptions = {
 	};
 	toolbar_width: string;
 	toolbar_container: HTMLElement | null;
-	toolbar_sticky: number;
+	_toolbar_sticky: number;
+	_toolbar_sticky_offset: number;
 	strictMode: StrictModeOptions;
 	lineAttrReset: string[];
 };