suneditor 3.0.0-rc.4 → 3.0.0

package/types/events.d.ts

@@ -239,6 +239,7 @@ export type EventHandlers = {
 	onShowController?: typeof onShowController | null;
 	onBeforeShowController?: typeof onBeforeShowController | null;
 	onToggleCodeView?: typeof onToggleCodeView | null;
+	onToggleMarkdownView?: typeof onToggleMarkdownView | null;
 	onToggleFullScreen?: typeof onToggleFullScreen | null;
 	onResizeEditor?: typeof onResizeEditor | null;
 	onSetToolbarButtons?: typeof onSetToolbarButtons | null;
@@ -554,6 +555,16 @@ declare function onBeforeShowController(params: { $: SunEditor.Deps; frameContex
  * @param {boolean} params.is - code view status
  */
 declare function onToggleCodeView(params: { $: SunEditor.Deps; frameContext: SunEditor.FrameContext; is: boolean }): void;
+/**
+ * @callback
+ * @description Fired when the editor switches between WYSIWYG view and markdown view.
+ * The `is` parameter indicates whether markdown view is now active (`true`) or WYSIWYG view is active (`false`).
+ * @param {Object} params
+ * @param {SunEditor.Deps} params.$ - Kernel dependencies
+ * @param {SunEditor.FrameContext} params.frameContext - frame context
+ * @param {boolean} params.is - markdown view status
+ */
+declare function onToggleMarkdownView(params: { $: SunEditor.Deps; frameContext: SunEditor.FrameContext; is: boolean }): void;
 /**
  * @callback
  * @description Fired when the editor enters or exits fullscreen mode.

package/types/helper/converter.d.ts

@@ -33,12 +33,16 @@ export function jsonToHtml(jsonData: { [x: string]: any }): string;
  * @description Convert HTML string to HTML Entity
  * @param {string} content
  * @returns {string} Content string
+ * @example
+ * converter.htmlToEntity('<div>'); // '&lt;div&gt;'
  */
 export function htmlToEntity(content: string): string;
 /**
  * @description Convert HTML Entity to HTML string
  * @param {string} content Content string
  * @returns {string}
+ * @example
+ * converter.entityToHTML('&lt;div&gt;'); // '<div>'
  */
 export function entityToHTML(content: string): string;
 /**
@@ -46,6 +50,9 @@ export function entityToHTML(content: string): string;
  * @param {(...args: *) => void} func function
  * @param {number} wait delay ms
  * @returns {*} executedFunction
+ * @example
+ * const debouncedSave = converter.debounce(() => save(), 300);
+ * input.addEventListener('input', debouncedSave);
  */
 export function debounce(func: (...args: any) => void, wait: number): any;
 /**
@@ -72,6 +79,9 @@ export function getValues(obj: any): Array<any>;
 /**
  * @description Convert the `CamelCase` To the `KebabCase`.
  * @param {string|Array<string>} param [Camel string]
+ * @example
+ * converter.camelToKebabCase('fontSize'); // 'font-size'
+ * converter.camelToKebabCase(['fontSize', 'fontFamily']); // ['font-size', 'font-family']
  */
 export function camelToKebabCase(param: string | Array<string>): any;
 /**
@@ -84,6 +94,8 @@ export function kebabToCamelCase(param: string): string;
  * @overload
  * @param {Array<string>} param - Array of `Kebab-case` strings.
  * @returns {Array<string>} Array of `CamelCase` strings.
+ * @example
+ * converter.kebabToCamelCase('font-size'); // 'fontSize'
  */
 export function kebabToCamelCase(param: Array<string>): Array<string>;
 /**
@@ -131,6 +143,9 @@ export function isHexColor(str: string): boolean;
  * @description Function to convert hex format to a `rgb` color
  * @param {string} rgba RGBA color format
  * @returns {string}
+ * @example
+ * converter.rgb2hex('rgb(255, 0, 0)'); // '#ff0000'
+ * converter.rgb2hex('rgba(255, 0, 0, 0.5)'); // '#ff000080'
  */
 export function rgb2hex(rgba: string): string;
 /**

package/types/helper/dom/domQuery.d.ts

@@ -29,6 +29,8 @@ export function getNodePath(
  * @param {Array<number>} offsets Position array, array obtained from `helper.dom.getNodePath`
  * @param {Node} parentNode Base parent element
  * @returns {T}
+ * @example
+ * const node = dom.query.getNodeFromPath([0, 1, 0], wysiwygElement);
  */
 export function getNodeFromPath<T extends Node>(offsets: Array<number>, parentNode: Node): T;
 /**
@@ -55,6 +57,8 @@ export function getListChildren<T extends HTMLElement>(element: Node, validation
  * @param {?(current: *) => boolean} validation Conditional function
  * @param {?number} depth Number of child levels to depth.
  * @returns {Array<T>}
+ * @example
+ * const allNodes = dom.query.getListChildNodes(container, (node) => node.nodeType === 3);
  */
 export function getListChildNodes<T extends Node>(element: Node, validation: ((current: any) => boolean) | null, depth: number | null): Array<T>;
 /**
@@ -69,6 +73,8 @@ export function getNodeDepth(node: Node): number;
  * @description Sort a node array by depth of element.
  * @param {Array<Node>} array Node array
  * @param {boolean} des `true`: descending order / `false`: ascending order
+ * @example
+ * const sorted = dom.query.sortNodeByDepth([nodeA, nodeB], true);
  */
 export function sortNodeByDepth(array: Array<Node>, des: boolean): void;
 /**
@@ -76,6 +82,9 @@ export function sortNodeByDepth(array: Array<Node>, des: boolean): void;
  * @param {Node} a Node to compare.
  * @param {Node} b Node to compare.
  * @returns {{ancestor: ?HTMLElement, a: Node, b: Node, result: number}} { ancesstor, a, b, result: (a > b ? 1 : a < b ? -1 : 0) };
+ * @example
+ * const result = dom.query.compareElements(nodeA, nodeB);
+ * // result: { ancestor: true, result: 0 } (same node), { ancestor: true, result: 1 } (a before b)
  */
 export function compareElements(
 	a: Node,
@@ -143,6 +152,9 @@ export function getEventTarget<T extends HTMLElement>(event: Event): T | null;
  * Not use it like jquery.
  * Only one condition can be entered at a time.
  * @returns {T|null} Not found: `null`
+ * @example
+ * const firstLeaf = dom.query.getEdgeChild(container, (n) => n.nodeType === 3, false);
+ * const lastLeaf = dom.query.getEdgeChild(container, (n) => n.nodeType === 3, true);
  */
 export function getEdgeChild<T extends Node>(node: Node, query: string | ((current: any) => boolean) | Node, last: boolean): T | null;
 /**

package/types/helper/dom/domUtils.d.ts

@@ -43,6 +43,8 @@ export function createTextNode(text: string): Text;
  * @param {Node} element Element object
  * @param {?Array<string>} exceptAttrs Array of attribute names to exclude from the result
  * @returns {string}
+ * @example
+ * const attrs = dom.utils.getAttributesToString(element, ['id', 'class']);
  */
 export function getAttributesToString(element: Node, exceptAttrs: Array<string> | null): string;
 /**
@@ -92,6 +94,8 @@ export function prevIndex(array: SunEditor.NodeCollection, item: Node): number;
  * @param {Node} originEl Origin element
  * @param {Node} copyEl Element to copy
  * @param {?Array<string>} [blacklist] Blacklist array(LowerCase)
+ * @example
+ * dom.utils.copyTagAttributes(newElement, originalElement, ['contenteditable']);
  */
 export function copyTagAttributes(originEl: Node, copyEl: Node, blacklist?: Array<string> | null): void;
 /**
@@ -109,6 +113,9 @@ export function removeItem(item: Node): void;
  * @description Replace element
  * @param {Node} element Target element
  * @param {string|Node} newElement String or element of the new element to apply
+ * @example
+ * dom.utils.changeElement(oldSpan, 'STRONG');
+ * dom.utils.changeElement(oldElement, newElement);
  */
 export function changeElement(element: Node, newElement: string | Node): void;
 /**
@@ -122,6 +129,9 @@ export function changeTxt(node: Node, txt: string): void;
  * @param {Node|Node[]} elements Element to set style
  * @param {string} styleName Style attribute name (`marginLeft`, `textAlign`...)
  * @param {string|number} value Style value
+ * @example
+ * dom.utils.setStyle(element, 'color', 'red');
+ * dom.utils.setStyle([el1, el2], 'display', 'none');
  */
 export function setStyle(elements: Node | Node[], styleName: string, value: string | number): void;
 /**
@@ -149,26 +159,33 @@ export function hasClass(element: Node | null, className: string): boolean;
  * @description Append the className value of the argument value element
  * @param {Node|SunEditor.NodeCollection} element Elements to add class name
  * @param {string} className Class name to be add
+ * @example
+ * dom.utils.addClass(element, 'active');
+ * dom.utils.addClass(element.children, 'highlight');
  */
 export function addClass(element: Node | SunEditor.NodeCollection, className: string): void;
 /**
  * @description Delete the className value of the argument value element
  * @param {Node|SunEditor.NodeCollection} element Elements to remove class name
  * @param {string} className Class name to be remove
+ * @example
+ * dom.utils.removeClass(element, 'active');
  */
 export function removeClass(element: Node | SunEditor.NodeCollection, className: string): void;
 /**
  * @description Argument value If there is no class name, insert it and delete the class name if it exists
  * @param {Node} element Element to replace class name
  * @param {string} className Class name to be change
- * @returns {boolean|undefined}
+ * @param {boolean} [force] If true, adds the class; if false, removes it.
  */
-export function toggleClass(element: Node, className: string): boolean | undefined;
+export function toggleClass(element: Node, className: string, force?: boolean): void;
 /**
  * @description Flash the class name of the argument value element for a certain time
  * @param {Node} element Element to flash class name
  * @param {string} className class name
  * @param {number} [duration=120] duration milliseconds
+ * @example
+ * dom.utils.flashClass(element, 'blink', 500);
  */
 export function flashClass(element: Node, className: string, duration?: number): void;
 /**
@@ -195,6 +212,8 @@ export function getViewportSize(): {
  * @param {boolean} includeWW Include the `wwTarget` element in the copy
  * @param {Iterable<string>} styles Style list - kamel case
  * @returns
+ * @example
+ * dom.utils.applyInlineStylesAll(wysiwygElement, true, ['font-family', 'font-size']);
  */
 export function applyInlineStylesAll(wwTarget: Node, includeWW: boolean, styles: Iterable<string>): HTMLElement;
 /**
@@ -202,6 +221,8 @@ export function applyInlineStylesAll(wwTarget: Node, includeWW: boolean, styles:
  * @param {Node} target Target element
  * @param {number} timeout Timeout milliseconds
  * @returns {Promise<void>}
+ * @example
+ * await dom.utils.waitForMediaLoad(imgElement, 5000);
  */
 export function waitForMediaLoad(target: Node, timeout?: number): Promise<void>;
 /**

package/types/helper/index.d.ts

@@ -170,6 +170,10 @@ export const keyCodeMap: {
 export const clipboard: {
 	write: typeof import('./clipboard').write;
 };
+export const markdown: {
+	jsonToMarkdown: typeof import('./markdown').jsonToMarkdown;
+	markdownToHtml: typeof import('./markdown').markdownToHtml;
+};
 declare namespace _default {
 	export { env };
 	export { unicode };
@@ -178,5 +182,6 @@ declare namespace _default {
 	export { numbers };
 	export { keyCodeMap };
 	export { clipboard };
+	export { markdown };
 }
 export default _default;

package/types/helper/markdown.d.ts

@@ -0,0 +1,27 @@
+import type {} from '../typedef';
+/**
+ * @description Converts a JSON tree (from htmlToJson) to a Markdown string.
+ * @param {Object} jsonNode JSON node from htmlToJson
+ * @returns {string} Markdown string
+ * @example
+ * const json = htmlToJson('<p><strong>Hello</strong> World</p>');
+ * const md = jsonToMarkdown(json);
+ * // '**Hello** World\n\n'
+ */
+export function jsonToMarkdown(jsonNode: any): string;
+/**
+ * @description Parses a Markdown string into an HTML string.
+ * - HTML tags in the markdown are passed through as-is (for fallback elements).
+ * @param {string} md Markdown string
+ * @param {string} [defaultLine='p'] Default block element tag
+ * @returns {string} HTML string
+ * @example
+ * markdownToHtml('# Hello\n\n**bold** text');
+ * // '<h1>Hello</h1><p><strong>bold</strong> text</p>'
+ */
+export function markdownToHtml(md: string, defaultLine?: string): string;
+export default markdown;
+declare namespace markdown {
+	export { jsonToMarkdown };
+	export { markdownToHtml };
+}

package/types/interfaces/plugins.d.ts

@@ -154,15 +154,17 @@ declare class Base extends KernelInjector {
 		eventIndex?: number;
 		isInputComponent?: boolean;
 	};
-	/** @type {string} */
+	/** @type {string}Toolbar button tooltip text (e.g., `this.$.lang.font`) */
 	title: string;
-	/** @type {string} */
+	/** @type {string} - Toolbar button icon HTML string (e.g., `this.$.icons.bold`) */
 	icon: string;
-	/** @type {HTMLElement} */
+	/** @type {string|HTMLElement|boolean|null} - Inner content of the toolbar button. HTML string for dropdown text labels, HTMLElement for input fields, or `false` to hide. */
+	inner: string | HTMLElement | boolean | null;
+	/** @type {HTMLElement} - Element inserted before the main toolbar button (e.g., decrease button in fontSize) */
 	beforeItem: HTMLElement;
-	/** @type {HTMLElement} */
+	/** @type {HTMLElement} - Element inserted after the main toolbar button (e.g., dropdown arrow, increase button) */
 	afterItem: HTMLElement;
-	/** @type {HTMLElement} */
+	/** @type {HTMLElement} - Replaces the entire default toolbar button with a custom element */
 	replaceButton: HTMLElement;
 }
 import KernelInjector from '../core/kernel/kernelInjector';

package/types/langs/_Lang.d.ts

@@ -110,6 +110,7 @@ export type _Lang = {
 	link_modal_url: string;
 	link_modal_relAttribute: string;
 	list: string;
+	markdownView: string;
 	math: string;
 	math_modal_fontSizeLabel: string;
 	math_modal_inputLabel: string;
@@ -171,6 +172,7 @@ export type _Lang = {
 	tableProperties: string;
 	tags: string;
 	tag_blockquote: string;
+	codeBlock: string;
 	tag_div: string;
 	tag_h: string;
 	tag_p: string;
@@ -189,6 +191,13 @@ export type _Lang = {
 	video_modal_title: string;
 	video_modal_url: string;
 	width: string;
+	codeLanguage: string;
+	codeLanguage_none: string;
+	finder_matchCase: string;
+	finder_wholeWord: string;
+	finder_regex: string;
+	finder_prev: string;
+	finder_next: string;
 	message_copy_success: string;
 	message_copy_fail: string;
 };

package/types/modules/contract/Browser.d.ts

@@ -97,7 +97,11 @@ export type BrowserParams = {
 	 */
 	listClass?: string;
 	/**
-	 * - Function that defines the HTML of a file item. Required. Can be overridden in browser.
+	 * - 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>`
+	 * ```
 	 */
 	drawItemHandler?: (item: BrowserFile) => string;
 	/**
@@ -140,7 +144,11 @@ export type BrowserParams = {
  * @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.
@@ -156,6 +164,17 @@ declare 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: any, $: SunEditor.Deps, params: BrowserParams);
 	useSearch: boolean;
@@ -226,6 +245,16 @@ declare 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?: {
 		listClass?: string;
@@ -249,6 +278,11 @@ declare 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: Array<BrowserFile>): Array<BrowserFile>;
 	/**

package/types/modules/contract/ColorPicker.d.ts

@@ -81,6 +81,12 @@ declare 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: Node | string, target: Node, stopCondition?: ((current: Node) => boolean) | null): void;
 	/**

package/types/modules/contract/Controller.d.ts

@@ -150,24 +150,40 @@ declare 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: Node | Range,
 		positionTarget?: Node,
 		{
 			isWWTarget,
+			passive,
 			initMethod,
 			disabled,
 			addOffset,
 		}?: {
 			isWWTarget?: boolean;
+			passive?: boolean;
 			initMethod?: () => void;
 			disabled?: boolean;
 			addOffset?: {
 				left?: number;
+				right?: number;
 				top?: number;
 			};
 		},
@@ -176,6 +192,12 @@ declare 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?: boolean): void;
 	/**
@@ -189,11 +211,23 @@ declare 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: boolean): void;
 	/**
 	 * @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?: Node): void;
 	/**

package/types/modules/contract/Figure.d.ts

@@ -242,6 +242,12 @@ declare 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: Node, className?: string): FigureInfo;
 	/**
@@ -249,6 +255,12 @@ declare 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: Node, className?: string): FigureInfo;
 	/**
@@ -269,6 +281,13 @@ declare 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: string | number,
@@ -285,6 +304,11 @@ declare 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: string | number,
@@ -372,6 +396,19 @@ declare 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: Node,
@@ -452,6 +489,13 @@ declare 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: Node | null, formatStyle: 'block' | 'inline'): HTMLElement;
 	controllerAction(target: HTMLButtonElement): void;
@@ -461,6 +505,13 @@ declare 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: Node, originEl: Node, anchorCover: Node, fileManagerInst?: import('../manager/FileManager').default): void;
 	/**
@@ -474,6 +525,12 @@ declare 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: Node, width: (string | number) | null, height: (string | number) | null, deg: number | null): void;
 	/**

package/types/modules/contract/Modal.d.ts

@@ -12,6 +12,12 @@ declare 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(
 		{

package/types/modules/manager/ApiManager.d.ts

@@ -71,6 +71,20 @@ declare 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 }: ApiManagerParams): void;
 	/**
@@ -82,6 +96,18 @@ declare 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,