suneditor 3.0.0-rc.4 → 3.0.0

package/src/langs/tr.js

@@ -126,6 +126,7 @@
 		link_modal_url: "Bağlantı URL'si",
 		link_modal_relAttribute: 'Rel niteliği',
 		list: 'Liste',
+		markdownView: 'Markdown görünümü',
 		math: 'Matematik',
 		math_modal_fontSizeLabel: 'Yazı Tipi Boyutu',
 		math_modal_inputLabel: 'Matematiksel Simgeler',
@@ -187,6 +188,7 @@
 		tableProperties: 'Tablo özellikleri',
 		tags: 'Etiketler',
 		tag_blockquote: 'Alıntı',
+		codeBlock: 'Kod Bloğu',
 		tag_div: 'Normal (DIV)',
 		tag_h: 'Başlık',
 		tag_p: 'Paragraf',
@@ -205,6 +207,13 @@
 		video_modal_title: 'Video Ekle',
 		video_modal_url: "Medya Ekleme URL'si (YouTube/Vimeo)",
 		width: 'Genişlik',
+		codeLanguage: 'Dil',
+		codeLanguage_none: 'Hiçbiri',
+		finder_matchCase: 'Kibrit Kutusu',
+		finder_wholeWord: 'Tüm Kelime',
+		finder_regex: 'Düzenli İfade',
+		finder_prev: 'Önceki Maç',
+		finder_next: 'Sonraki Maç',
 		message_copy_success: 'Panoya kopyalandı',
 		message_copy_fail: 'Kopyalama başarısız oldu. Lütfen manuel olarak kopyalayın.',
 	};

package/src/langs/uk.js

@@ -126,6 +126,7 @@
 		link_modal_url: 'Посилання',
 		link_modal_relAttribute: 'Атрибут rel',
 		list: 'Список',
+		markdownView: 'Перегляд Markdown',
 		math: 'Формула',
 		math_modal_fontSizeLabel: 'Розмір шрифту',
 		math_modal_inputLabel: 'Математична запис',
@@ -187,6 +188,7 @@
 		tableProperties: 'Властивості таблиці',
 		tags: 'Теги',
 		tag_blockquote: 'Цитата',
+		codeBlock: 'Блок коду',
 		tag_div: 'Базовий',
 		tag_h: 'Заголовок',
 		tag_p: 'Абзац',
@@ -205,6 +207,13 @@
 		video_modal_title: 'Вставити відео',
 		video_modal_url: 'Посилання на відео, Youtube, Vimeo',
 		width: 'Ширина',
+		codeLanguage: 'Мова',
+		codeLanguage_none: 'Жоден',
+		finder_matchCase: 'Зіставте регістр',
+		finder_wholeWord: 'Ціле слово',
+		finder_regex: 'Регулярний вираз',
+		finder_prev: 'Попередній матч',
+		finder_next: 'Наступний матч',
 		message_copy_success: 'Скопійовано в буфер обміну',
 		message_copy_fail: 'Не вдалося скопіювати. Будь ласка, скопіюйте вручну.',
 	};

package/src/langs/ur.js

@@ -126,6 +126,7 @@
 		link_modal_url: 'لنک کرنے کے لیے URL',
 		link_modal_relAttribute: 'Rel وصف',
 		list: 'فہرست',
+		markdownView: 'مارک ڈاؤن منظر',
 		math: 'ریاضی',
 		math_modal_fontSizeLabel: 'حرف کا سائز',
 		math_modal_inputLabel: 'ریاضیاتی اشارے',
@@ -187,6 +188,7 @@
 		tableProperties: 'ٹیبل کی خصوصیات',
 		tags: 'ٹیگز',
 		tag_blockquote: 'اقتباس',
+		codeBlock: 'کوڈ بلاک',
 		tag_div: 'عام (div)',
 		tag_h: 'ہیڈر',
 		tag_p: 'پیراگراف',
@@ -205,6 +207,13 @@
 		video_modal_title: 'ویڈیو داخل کریں',
 		video_modal_url: 'ذرائع ابلاغ کا یو آر ایل، یوٹیوب/ویمیو',
 		width: 'چوڑائی',
+		codeLanguage: 'زبان',
+		codeLanguage_none: 'کوئی نہیں۔',
+		finder_matchCase: 'میچ کیس',
+		finder_wholeWord: 'پورا کلام',
+		finder_regex: 'باقاعدہ اظہار',
+		finder_prev: 'پچھلا میچ',
+		finder_next: 'اگلا میچ',
 		message_copy_success: 'کلپ بورڈ میں کاپی ہو گیا',
 		message_copy_fail: 'کاپی ناکام۔ براہ کرم دستی طور پر کاپی کریں۔',
 	};

package/src/langs/zh_cn.js

@@ -126,6 +126,7 @@
 		link_modal_url: '网址',
 		link_modal_relAttribute: 'Rel 属性',
 		list: '列表',
+		markdownView: 'Markdown视图',
 		math: '数学',
 		math_modal_fontSizeLabel: '字号',
 		math_modal_inputLabel: '数学符号',
@@ -187,6 +188,7 @@
 		tableProperties: '表格属性',
 		tags: '标签',
 		tag_blockquote: '引用',
+		codeBlock: '代码块',
 		tag_div: '正文 (DIV)',
 		tag_h: '标题',
 		tag_p: '段落',
@@ -205,6 +207,13 @@
 		video_modal_title: '插入视频',
 		video_modal_url: '嵌入网址, Youtube,Vimeo',
 		width: '宽度',
+		codeLanguage: '语言',
+		codeLanguage_none: '没有任何',
+		finder_matchCase: '火柴盒',
+		finder_wholeWord: '整个单词',
+		finder_regex: '正则表达式',
+		finder_prev: '上一场比赛',
+		finder_next: '下一场比赛',
 		message_copy_success: '已复制到剪贴板',
 		message_copy_fail: '复制失败，请手动复制。',
 	};

package/src/modules/contract/Browser.js

@@ -29,7 +29,11 @@ import ApiManager from '../manager/ApiManager';
  * @property {string} [searchUrl] - File server search url. Optional. Can be overridden in browser.
  * @property {Object<string, string>} [searchUrlHeader] - File server search http header. Optional. Can be overridden in browser.
  * @property {string} [listClass] - Class name of list div. Required. Can be overridden in browser.
- * @property {(item: BrowserFile) => string} [drawItemHandler] - Function that defines the HTML of a file item. Required. Can be overridden in browser.
+ * @property {(item: BrowserFile) => string} [drawItemHandler] - Function that returns HTML string for rendering each file item. Required. Can be overridden in browser.
+ * ```js
+ * // drawItemHandler
+ * (item) => `<div><img src="${item.thumbnail}"><span>${item.name}</span></div>`
+ * ```
  * @property {Array<*>} [props] - `props` argument to `drawItemHandler` function. Optional. Can be overridden in browser.
  * @property {number} [columnSize] - Number of `div.se-file-item-column` to be created.
  * - Optional. Can be overridden in browser. Default: 4.
@@ -54,6 +58,17 @@ class Browser {
 	 * @param {*} host The instance object that called the constructor.
 	 * @param {SunEditor.Deps} $ Kernel dependencies
 	 * @param {BrowserParams} params Browser options
+	 * @example
+	 * // Inside a PluginBrowser constructor:
+	 * this.browser = new Browser(this, this.$, {
+	 *   title: this.$.lang.imageGallery,
+	 *   data: pluginOptions.data,
+	 *   url: pluginOptions.url,
+	 *   headers: pluginOptions.headers,
+	 *   selectorHandler: this.#OnSelect.bind(this),
+	 *   columnSize: 4,
+	 *   className: 'se-image-gallery',
+	 * });
 	 */
 	constructor(host, $, params) {
 		this.#$ = $;
@@ -136,6 +151,16 @@ class Browser {
 	 * @param {string} [params.title] - File browser window title. If not, use `this.title`.
 	 * @param {string} [params.url] - File server url. If not, use `this.url`.
 	 * @param {Object<string, string>} [params.urlHeader] - File server http header. If not, use `this.urlHeader`.
+	 * @example
+	 * // Open with default settings (configured at construction):
+	 * this.browser.open();
+	 *
+	 * // Open with runtime overrides:
+	 * this.browser.open({
+	 *   title: 'Select a video',
+	 *   url: '/api/videos',
+	 *   urlHeader: { Authorization: 'Bearer token' },
+	 * });
 	 */
 	open(params = {}) {
 		this.#addGlobalEvent();
@@ -199,6 +224,11 @@ class Browser {
 	 * @description Filter items by tag
 	 * @param {Array<BrowserFile>} items - Items to filter
 	 * @returns {Array<BrowserFile>}
+	 * @example
+	 * // Filter items by currently selected tags:
+	 * browser.selectedTags = ['photo', 'landscape'];
+	 * const filtered = browser.tagfilter(items);
+	 * // Returns only items whose `tag` array includes 'photo' or 'landscape'
 	 */
 	tagfilter(items) {
 		const selectedTags = this.selectedTags;

package/src/modules/contract/ColorPicker.js

@@ -143,6 +143,12 @@ class ColorPicker {
 	 * @param {?(current: Node) => boolean} [stopCondition] - A function used to stop traversing parent nodes while finding the color.
 	 * - When this function returns `true`, the traversal ends at that node.
 	 * - e.g., `(node) => this.format.isLine(node)` stops at line-level elements like <p>, <div>.
+	 * @example
+	 * // Initialize with a selected node and stop traversal at line-level elements
+	 * this.colorPicker.init(this.$.selection.getNode(), target, (current) => this.$.format.isLine(current));
+	 *
+	 * // Initialize with a color string directly (e.g., from a table cell style)
+	 * this.colorPicker.init(color?.value || '', button);
 	 */
 	init(nodeOrColor, target, stopCondition) {
 		this.targetButton = target;

package/src/modules/contract/Controller.js

@@ -6,6 +6,7 @@ const INDEX_00 = '2147483646';
 const INDEX_0 = '2147483645';
 const INDEX_S_1 = '2147483642';
 const INDEX_1 = '2147483641';
+const ADD_OFFSET_VALUE = { left: 0, right: 0, top: 0 };
 
 /**
  * Controller information object
@@ -46,11 +47,10 @@ class Controller {
 	#initMethod;
 	#globalEventHandlers;
 
-	#addOffset = { left: 0, top: 0 };
+	#addOffset = ADD_OFFSET_VALUE;
 	#reserveIndex = false;
 	#preventClose = false;
-	#shadowRootEventForm = null;
-	#shadowRootEventListener = null;
+	#bindShadowRootEvent = null;
 	#bindClose_key = null;
 	#bindClose_mouse = null;
 
@@ -124,13 +124,26 @@ class Controller {
 	 * @param {Node} [positionTarget] Position target element
 	 * @param {Object} [params={}] params
 	 * @param {boolean} [params.isWWTarget] If the controller is in the WYSIWYG area, set it to `true`.
+	 * @param {boolean} [params.passive] If `true`, opens the controller visually without affecting editor state
+	 * - (`_preventBlur`, `controlActive`, `onControllerContext`, `opendControllers`).
+	 * - Used for lightweight, non-intrusive display such as hover-triggered UI (e.g., codeLang selector on `<pre>` hover).
+	 * - Automatically set to `true` when opened during component hover selection (`ON_OVER_COMPONENT`).
 	 * @param {() => void} [params.initMethod] Method to be called when the controller is closed.
 	 * @param {boolean} [params.disabled] If `true`, When the `controller` is opened, buttons without the `se-component-enabled` class are disabled. (default: `this.disabled`)
-	 * @param {{left?: number, top?: number}} [params.addOffset] Additional offset values
+	 * @param {{left?: number, right?:number, top?: number}} [params.addOffset] Additional offset values
+	 * @example
+	 * // Open controller on a target element with default options
+	 * this.controller.open(target);
+	 *
+	 * // Open with explicit options and additional offset
+	 * this.controller.open(target, null, { isWWTarget: false, initMethod: null, addOffset: null });
+	 *
+	 * // Open on a Range target (e.g., text selection)
+	 * this.controller.open(this.$.selection.getRange());
 	 */
-	open(target, positionTarget, { isWWTarget, initMethod, disabled, addOffset } = {}) {
+	open(target, positionTarget, { isWWTarget, passive, initMethod, disabled, addOffset } = {}) {
 		if (_DragHandle.get('__overInfo') === ON_OVER_COMPONENT) {
-			return;
+			passive = true;
 		}
 
 		if (!target) {
@@ -142,35 +155,38 @@ class Controller {
 		this.form.removeAttribute('data-se-hidden-by-children');
 		this.#__hiddenByParents__.clear();
 
-		if (this.#$.store.mode.isBalloon) this.#$.toolbar.hide();
-		else if (this.#$.store.mode.isSubBalloon) this.#$.subToolbar.hide();
+		if (!passive) {
+			if (this.#$.store.mode.isBalloon) this.#$.toolbar.hide();
+			else if (this.#$.store.mode.isSubBalloon) this.#$.subToolbar.hide();
 
-		if (!this.#$.store.get('hasFocus')) {
-			if (disabled ?? this.disabled) {
-				this.#$.ui.setControllerOnDisabledButtons(true);
-			} else {
-				this.#$.ui.setControllerOnDisabledButtons(false);
+			if (!this.#$.store.get('hasFocus')) {
+				if (disabled ?? this.disabled) {
+					this.#$.ui.setControllerOnDisabledButtons(true);
+				} else {
+					this.#$.ui.setControllerOnDisabledButtons(false);
+				}
 			}
 		}
 
 		this.currentPositionTarget = positionTarget || target;
 		this.isWWTarget = isWWTarget ?? this.isWWTarget;
 		if (typeof initMethod === 'function') this.#initMethod = initMethod;
-		this.#$.ui.currentControllerName = this.kind;
+		if (!passive) this.#$.ui.currentControllerName = this.kind;
 
-		this.#addOffset = { left: 0, top: 0 };
-		if (addOffset) this.#addOffset = { ...this.#addOffset, ...addOffset };
+		this.#addOffset = { left: 0, right: 0, top: 0, ...addOffset };
 
-		const parents = this.isOutsideForm ? this.parentsForm : [];
-		this.#$.ui.opendControllers?.forEach((e) => {
-			if (!parents.includes(e.form)) e.form.style.zIndex = INDEX_1;
-		});
-
-		if (this.parentsHide) {
-			this.parentsForm.forEach((e) => {
-				e.style.display = 'none';
-				e.setAttribute('data-se-hidden-by-children', '1');
+		if (!passive) {
+			const parents = this.isOutsideForm ? this.parentsForm : [];
+			this.#$.ui.opendControllers?.forEach((e) => {
+				if (!parents.includes(e.form)) e.form.style.zIndex = INDEX_1;
 			});
+
+			if (this.parentsHide) {
+				this.parentsForm.forEach((e) => {
+					e.style.display = 'none';
+					e.setAttribute('data-se-hidden-by-children', '1');
+				});
+			}
 		}
 
 		this.#addGlobalEvent();
@@ -180,7 +196,7 @@ class Controller {
 
 		const isRangeTarget = this.#$.instanceCheck.isRange(target);
 		this.currentTarget = /** @type {HTMLElement} */ (isRangeTarget ? null : target);
-		this.#controllerOn(this.form, target, isRangeTarget);
+		this.#controllerOn(this.form, target, isRangeTarget, passive);
 		_w.setTimeout(() => _DragHandle.set('__overInfo', false), 0);
 	}
 
@@ -188,6 +204,12 @@ class Controller {
 	 * @description Close a modal plugin
 	 * - The plugin's `init` method is called.
 	 * @param {boolean} [force] If `true`, parent controllers are forcibly closed.
+	 * @example
+	 * // Close the controller (skips if not open or preventClose is set)
+	 * this.controller.close();
+	 *
+	 * // Force close, also closing parent controllers in the hierarchy
+	 * this.controller.close(true);
 	 */
 	close(force) {
 		if (!force && (!this.isOpen || this.#preventClose)) return;
@@ -201,7 +223,7 @@ class Controller {
 		this.isOpen = false;
 		this.#preventClose = false;
 		this.__offset = {};
-		this.#addOffset = { left: 0, top: 0 };
+		this.#addOffset = ADD_OFFSET_VALUE;
 
 		this.#removeGlobalEvent();
 
@@ -240,6 +262,12 @@ class Controller {
 	/**
 	 * @description Sets whether the element (form) should be brought to the top based on `z-index`.
 	 * @param {boolean} value - `true`: `'2147483646'`, `false`: `'2147483645'`.
+	 * @example
+	 * // Bring controller to the highest z-index layer (2147483646)
+	 * this.controller_cell.bringToTop(true);
+	 *
+	 * // Restore to the default top z-index (2147483645)
+	 * this.controller_cell.bringToTop(false);
 	 */
 	bringToTop(value) {
 		this.toTop = value;
@@ -249,6 +277,12 @@ class Controller {
 	/**
 	 * @description Reset controller position
 	 * @param {Node} [target]
+	 * @example
+	 * // Reposition using a new target element
+	 * this.controller_cell.resetPosition(tdElement);
+	 *
+	 * // Reposition using the previously set target
+	 * this.controller.resetPosition();
 	 */
 	resetPosition(target) {
 		this.#setControllerPosition(this.form, target || this.currentPositionTarget, true);
@@ -320,8 +354,9 @@ class Controller {
 	 * @param {HTMLFormElement} form Controller element
 	 * @param {Node|Range} target Controller target element
 	 * @param {boolean} isRangeTarget If the target is a `Range`, set it to `true`.
+	 * @param {boolean} [passive=false] If `true`, opens without affecting editor state (_preventBlur, controlActive, etc.)
 	 */
-	async #controllerOn(form, target, isRangeTarget) {
+	async #controllerOn(form, target, isRangeTarget, passive) {
 		/** @type {ControllerInfo} */
 		const info = {
 			position: this.position,
@@ -336,20 +371,21 @@ class Controller {
 
 		form.style.display = 'block';
 		if (this.#$.contextProvider.shadowRoot) {
-			this.#shadowRootEventForm = form;
-			this.#shadowRootEventListener = (e) => e.stopPropagation();
-			form.addEventListener('mousedown', this.#shadowRootEventListener);
+			this.#bindShadowRootEvent = this.#$.eventManager.addEvent(form, 'mousedown', (e) => e.stopPropagation());
 		}
 
-		this.#$.ui.onControllerContext();
+		if (!passive) {
+			this.#$.ui.onControllerContext();
+			this.#$.store.set('controlActive', true);
+		}
 
 		if (!this.isOpen) {
 			this.#$.ui.opendControllers.push(info);
 		}
 
-		this.isOpen = true;
 		this.#$.store.set('_preventBlur', true);
-		this.#$.store.set('controlActive', true);
+
+		this.isOpen = true;
 
 		this.host.controllerOn?.(form, target);
 		this.#$.eventManager.triggerEvent('onShowController', { caller: this.kind, frameContext: this.#$.frameContext, info });
@@ -374,10 +410,7 @@ class Controller {
 		_w.setTimeout(() => {
 			this.#$.store.set('controlActive', false);
 		}, 0);
-		if (this.#shadowRootEventForm) {
-			this.#shadowRootEventForm.removeEventListener('mousedown', this.#shadowRootEventListener);
-			this.#shadowRootEventForm = this.#shadowRootEventListener = null;
-		}
+		this.#bindShadowRootEvent &&= this.#$.eventManager.removeEvent(this.#bindShadowRootEvent);
 	}
 
 	/**
@@ -473,7 +506,7 @@ class Controller {
 
 	/**
 	 * @description Checks if the given target is within a form or controller.
-	 * @param {Node} target The target element.
+	 * @param {Element} target The target element.
 	 * @returns {boolean} `true` if the target is inside a form or controller.
 	 */
 	#checkForm(target) {
@@ -505,6 +538,11 @@ class Controller {
 		e.stopPropagation();
 		e.preventDefault();
 
+		if (target.getAttribute('data-command') === 'close') {
+			this.close();
+			return;
+		}
+
 		this.host.controllerAction(target);
 	}
 

package/src/modules/contract/Figure.js

@@ -233,6 +233,12 @@ class Figure {
 	 * @param {Node} element Target element
 	 * @param {string} [className] Class name of container (fixed: `se-component`)
 	 * @returns {FigureInfo} {target, container, cover, inlineCover, caption}
+	 * @example
+	 * const imgEl = document.createElement('IMG');
+	 * imgEl.src = imageUrl;
+	 * const figureInfo = Figure.CreateContainer(imgEl, 'se-image-container');
+	 * // figureInfo.container → <div class="se-component se-image-container">
+	 * // figureInfo.cover     → <figure> wrapping the imgEl
 	 */
 	static CreateContainer(element, className) {
 		dom.utils.createElement('DIV', { class: 'se-component' + (className ? ' ' + className : '') }, dom.utils.createElement('FIGURE', null, element));
@@ -244,6 +250,12 @@ class Figure {
 	 * @param {Node} element Target element
 	 * @param {string} [className] Class name of container (fixed: `se-component` `se-inline-component`)
 	 * @returns {FigureInfo} {target, container, cover, inlineCover, caption}
+	 * @example
+	 * const imgEl = document.createElement('IMG');
+	 * imgEl.src = imageUrl;
+	 * const figureInfo = Figure.CreateInlineContainer(imgEl, 'se-image-container');
+	 * // figureInfo.container    → <span class="se-component se-inline-component se-image-container">
+	 * // figureInfo.inlineCover  → same as container (inline mode)
 	 */
 	static CreateInlineContainer(element, className) {
 		dom.utils.createElement('SPAN', { class: 'se-component se-inline-component' + (className ? ' ' + className : '') }, element);
@@ -288,6 +300,13 @@ class Figure {
 	 * @param {string|number} h Height size
 	 * @param {?string} [defaultSizeUnit="px"] Default size unit (default: `"px"`)
 	 * @return {{w: number, h: number}}
+	 * @example
+	 * const ratio = Figure.GetRatio(200, 100, 'px');
+	 * // ratio → { w: 2, h: 0.5 }
+	 *
+	 * // Used with proportion-locked resizing
+	 * const ratio = Figure.GetRatio(inputX.value, inputY.value, sizeUnit);
+	 * const adjusted = Figure.CalcRatio(newWidth, newHeight, sizeUnit, ratio);
 	 */
 	static GetRatio(w, h, defaultSizeUnit) {
 		let rw = 0,
@@ -316,6 +335,11 @@ class Figure {
 	 * @param {string} defaultSizeUnit Default size unit (default: `"px"`)
 	 * @param {?{w: number, h: number}} [ratio] Ratio size (Figure.GetRatio)
 	 * @return {{w: string|number, h: string|number}}
+	 * @example
+	 * const ratio = Figure.GetRatio(200, 100, 'px');
+	 * // When width changes, recalculate height to maintain aspect ratio
+	 * const result = Figure.CalcRatio(inputX.value, inputY.value, 'px', ratio);
+	 * inputY.value = result.h; // adjusted height preserving ratio
 	 */
 	static CalcRatio(w, h, defaultSizeUnit, ratio) {
 		if (ratio?.w && ratio?.h && /\d+/.test(w + '') && /\d+/.test(h + '')) {
@@ -366,6 +390,19 @@ class Figure {
 	 * @param {boolean} [params.figureTarget=false] If `true`, the target is a figure element
 	 * @param {boolean} [params.infoOnly=false] If `true`, returns only the figure target info without opening the controller
 	 * @returns {FigureTargetInfo|undefined} figure target info
+	 * @example
+	 * // Open controller with full UI (resize handles, size info, border)
+	 * const info = this.figure.open(imgElement, {
+	 *   nonResizing: false, nonSizeInfo: false, nonBorder: false,
+	 *   figureTarget: false, infoOnly: false
+	 * });
+	 *
+	 * // Get figure info without opening the controller UI
+	 * const info = this.figure.open(oFrame, {
+	 *   nonResizing: false, nonSizeInfo: false, nonBorder: false,
+	 *   figureTarget: false, infoOnly: true
+	 * });
+	 * // info.width, info.height, info.ratio are available
 	 */
 	open(targetNode, { nonResizing, nonSizeInfo, nonBorder, figureTarget, infoOnly }) {
 		if (!targetNode) {
@@ -683,6 +720,13 @@ class Figure {
 	 * @param {?Node} targetNode Target element
 	 * @param {"block"|"inline"} formatStyle Format style
 	 * @returns {HTMLElement} New target element after conversion
+	 * @example
+	 * // Convert a block image to inline format
+	 * const newImgEl = this.figure.convertAsFormat(imgElement, 'inline');
+	 * // newImgEl is a cloned element inside a new inline container
+	 *
+	 * // Convert an inline image back to block format
+	 * const newImgEl = this.figure.convertAsFormat(imgElement, 'block');
 	 */
 	convertAsFormat(targetNode, formatStyle) {
 		targetNode ||= this._element;
@@ -849,6 +893,13 @@ class Figure {
 	 * @param {Node} originEl - The original element of the figure component.
 	 * @param {Node} anchorCover - The anchor cover element of the figure component.
 	 * @param {import('../manager/FileManager').default} [fileManagerInst=null] - FileManager module instance, if used.
+	 * @example
+	 * // Insert a new image figure, replacing the original element in the DOM
+	 * const figureInfo = Figure.CreateContainer(imgElement, 'se-image-container');
+	 * this.figure.retainFigureFormat(figureInfo.container, this.#element, null, this.fileManager);
+	 *
+	 * // Replace with anchor cover (e.g., image wrapped in a link)
+	 * this.figure.retainFigureFormat(container, this.#element, anchorEl, this.fileManager);
 	 */
 	retainFigureFormat(container, originEl, anchorCover, fileManagerInst) {
 		const isInline = this.#$.component.isInline(container);
@@ -910,6 +961,12 @@ class Figure {
 	 * @param {?string|number} width Element's width size
 	 * @param {?string|number} height Element's height size
 	 * @param {?number} deg rotate value
+	 * @example
+	 * // Rotate element 90 degrees clockwise
+	 * this.figure.setTransform(imgElement, 100, 50, 90);
+	 *
+	 * // Apply size without additional rotation (deg=0 preserves current rotation)
+	 * this.figure.setTransform(oFrame, width, height, 0);
 	 */
 	setTransform(node, width, height, deg) {
 		try {

package/src/modules/contract/Modal.js

@@ -80,6 +80,12 @@ class Modal {
 	 * - acceptedFormats: `"image/*, video/*, audio/*"`, etc.
 	 * - allowMultiple: `true` or `false`
 	 * @returns {string} HTML string
+	 * @example
+	 * // Inside a plugin's modal HTML template:
+	 * const html = Modal.CreateFileInput(
+	 *   { icons, lang },
+	 *   { acceptedFormats: 'image/*', allowMultiple: true }
+	 * );
 	 */
 	static CreateFileInput({ icons, lang }, { acceptedFormats, allowMultiple }) {
 		return /*html*/ `

package/src/modules/manager/ApiManager.js

@@ -51,6 +51,20 @@ class ApiManager {
 	/**
 	 * @description Call API
 	 * @param {ApiManagerParams} params
+	 * @example
+	 * // POST with FormData and callbacks
+	 * apiManager.call({
+	 *   method: 'POST', url: '/upload', headers: { 'x-custom': 'value' },
+	 *   data: formData,
+	 *   callBack: (xhr) => console.log(xhr.responseText),
+	 *   errorCallBack: (res, xhr) => res.errorMessage || 'Upload failed'
+	 * });
+	 *
+	 * // GET request with minimal params (uses constructor defaults for omitted options)
+	 * apiManager.call({
+	 *   method: 'GET', url: '/api/files',
+	 *   callBack: (xhr) => JSON.parse(xhr.responseText)
+	 * });
 	 */
 	call({ method, url, headers, data, callBack, errorCallBack, responseType }) {
 		this.cancel();
@@ -90,6 +104,18 @@ class ApiManager {
 	 * @param {*} [params.data] - API data
 	 * @param {XMLHttpRequestResponseType} [params.responseType] - XMLHttpRequest.responseType
 	 * @returns {Promise<XMLHttpRequest>}
+	 * @example
+	 * // POST FormData and await the response
+	 * const xhr = await apiManager.asyncCall({
+	 *   method: 'POST', url: '/upload',
+	 *   headers: { 'x-api-key': 'key' }, data: formData
+	 * });
+	 * const result = JSON.parse(xhr.responseText);
+	 *
+	 * // Send JSON data (uses constructor defaults for method/url)
+	 * const xhr = await apiManager.asyncCall({
+	 *   data: JSON.stringify({ fileName: 'doc.pdf', htmlContent })
+	 * });
 	 */
 	asyncCall({ method, url, headers, data, responseType }) {
 		this.cancel();
@@ -118,9 +144,9 @@ class ApiManager {
 						this.#$.ui.hideLoading();
 					}
 				} else {
+					console.error(`[SUNEDITOR.ApiManager[${this.kind}].upload.serverException]`, xhr);
 					try {
-						const res = !xhr.responseText ? xhr : JSON.parse(xhr.responseText);
-						reject(res);
+						reject(_parseErrorResponse(xhr));
 					} finally {
 						this.#$.ui.hideLoading();
 					}
@@ -177,12 +203,12 @@ class ApiManager {
 				// exception
 				console.error(`[SUNEDITOR.ApiManager[${this.kind}].upload.serverException]`, xmlHttp);
 				try {
-					const res = !xmlHttp.responseText ? xmlHttp : JSON.parse(xmlHttp.responseText);
+					const res = _parseErrorResponse(xmlHttp);
 					let message = '';
 					if (typeof errorCallBack === 'function') {
 						message = await errorCallBack(res, xmlHttp);
 					}
-					const err = `[SUNEDITOR.ApiManager[${this.kind}].upload.serverException] status: ${xmlHttp.status}, response: ${message || res.errorMessage || xmlHttp.responseText}`;
+					const err = `[SUNEDITOR.ApiManager[${this.kind}].upload.serverException] status: ${xmlHttp.status}, response: ${message || res.errorMessage || (typeof res === 'string' ? res : JSON.stringify(res))}`;
 					this.#$.ui.alertOpen(err, 'error');
 				} catch (error) {
 					throw Error(`[SUNEDITOR.ApiManager[${this.kind}].upload.errorCallBack.fail] ${error.message}`);
@@ -194,4 +220,27 @@ class ApiManager {
 	}
 }
 
+/**
+ * @description Parses error response from XMLHttpRequest.
+ * Safely handles non-text responseTypes (blob, arraybuffer, etc.) where accessing responseText throws.
+ * @param {XMLHttpRequest} xhr
+ * @returns {Object|string} Parsed JSON object, raw text, or status string as fallback
+ */
+function _parseErrorResponse(xhr) {
+	let text;
+	try {
+		text = xhr.responseText;
+	} catch {
+		return `status ${xhr.status}`;
+	}
+
+	if (!text) return `status ${xhr.status}`;
+
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+
 export default ApiManager;