suneditor 3.1.3 → 3.2.0

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

@@ -54,16 +54,16 @@ declare 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.
+	 * @param {?(((current: *) => 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: Node, validation?: (((current: Node) => boolean) | string) | null): void;
+	mergeNestedTags(element: Node, validation?: (((current: any) => boolean) | string) | null): void;
 	/**
 	 * @description Delete itself and all parent nodes that match the condition.
 	 * - Returns an {sc: previousSibling, ec: nextSibling}(the deleted node reference) or `null`.
 	 * @param {Node} item Node to be remove
-	 * @param {?(current: Node) => boolean} [validation] Validation function. default(Deleted if it only have `breakLine` and blanks)
+	 * @param {?(current: *) => boolean} [validation] Validation function. default(Deleted if it only have `breakLine` and blanks)
 	 * @param {?Node} [stopParent] Stop when the parent node reaches `stopParent`
 	 * @returns {{sc: Node|null, ec: Node|null}|null} {sc: previousSibling, ec: nextSibling} (the deleted node reference) or `null`.
 	 * @example
@@ -82,7 +82,7 @@ declare class NodeTransform {
 	 */
 	removeAllParents(
 		item: Node,
-		validation?: ((current: Node) => boolean) | null,
+		validation?: ((current: any) => boolean) | null,
 		stopParent?: Node | null,
 	): {
 		sc: Node | null;
@@ -98,7 +98,7 @@ declare class NodeTransform {
 	/**
 	 * @description Creates a nested node structure from the given array of nodes.
 	 * @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.
+	 * @param {?(current: *) => 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)
@@ -114,7 +114,7 @@ declare class NodeTransform {
 	 */
 	createNestedNode(
 		nodeArray: SunEditor.NodeCollection,
-		validate?: ((current: Node) => boolean) | null,
+		validate?: ((current: any) => boolean) | null,
 	): {
 		parent: Node;
 		inner: Node;

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

@@ -0,0 +1,64 @@
+import type {} from '../../../typedef';
+export default BlockHandle;
+/**
+ * @class
+ * @description Block handle UI — appears in the left gutter on block hover.
+ */
+declare class BlockHandle {
+	/**
+	 * @constructor
+	 * @param {SunEditor.Deps} $ - Kernel dependencies
+	 * @param {HTMLElement} blockHandleArea - Container (.se-block-handle-area)
+	 * @param {HTMLElement} blockHandle - Handle group (.se-block-handle)
+	 * @param {HTMLElement} blockHandlePlus - Plus button
+	 * @param {HTMLElement} blockHandleDrag - Drag button
+	 * @param {Array<string | { title: string, icon?: string, action: function(SunEditor.Deps, { block: HTMLElement }): void }>|null} menuConfig
+	 *   Menu entries. Strings resolve via `ResolveButton` (plugin names, built-in commands). Objects
+	 *   define a custom row whose `action` is invoked with the Deps bag and the current block element.
+	 */
+	constructor(
+		$: SunEditor.Deps,
+		blockHandleArea: HTMLElement,
+		blockHandle: HTMLElement,
+		blockHandlePlus: HTMLElement,
+		blockHandleDrag: HTMLElement,
+		menuConfig: Array<
+			| string
+			| {
+					title: string;
+					icon?: string;
+					action: (
+						arg0: SunEditor.Deps,
+						arg1: {
+							block: HTMLElement;
+						},
+					) => void;
+			  }
+		> | null,
+	);
+	/**
+	 * @description Position the block handle for the given mouse target. Uses rAF throttle.
+	 * Called from wysiwyg mousemove.
+	 * @param {Node} eventTarget - The element under the mouse cursor
+	 * @param {number} [mouseY] - Mouse clientY for nested list resolution
+	 */
+	positionForTarget(eventTarget: Node, mouseY?: number): void;
+	/**
+	 * @description Schedule hiding the block handle with a short delay.
+	 * @param {MouseEvent} e - Mouse event
+	 */
+	hide(e: MouseEvent): void;
+	/**
+	 * @description Immediately hide the block handle (no delay).
+	 */
+	hideNow(): void;
+	/**
+	 * @description Sync handle position on editor scroll. Closes menu if open.
+	 */
+	syncScroll(): void;
+	/**
+	 * @description Cleanup — remove listeners, destroy menus, null references.
+	 */
+	destroy(): void;
+	#private;
+}

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

@@ -0,0 +1,50 @@
+import type {} from '../../../typedef';
+/**
+ * @description Resolve any DOM node inside the editor to its owning block-level element.
+ * @param {Node|null} node - Any DOM node inside the editor
+ * @param {FormatAPI} format - Injected format methods (getLine, getBlock, isLine, isBlock)
+ * @param {HTMLElement} wysiwygFrame - The wysiwyg root element
+ * @param {number} [mouseY] - Mouse clientY for nested list resolution
+ * @returns {BlockInfo|null} Block information, or null if node is outside editable area
+ */
+export function resolveBlock(
+	node: Node | null,
+	format: FormatAPI,
+	wysiwygFrame: HTMLElement,
+	mouseY?: number,
+): BlockInfo | null;
+export type BlockInfo = {
+	/**
+	 * - The resolved block-level DOM element
+	 */
+	element: HTMLElement;
+	/**
+	 * - Block type: 'p', 'heading', 'list', 'blockquote', 'pre', 'figure', 'table', 'div'
+	 */
+	type: string;
+	/**
+	 * - Nesting level from wysiwyg root (0 = top-level)
+	 */
+	depth: number;
+	/**
+	 * - Parent block element, or null if top-level
+	 */
+	parent: HTMLElement | null;
+	/**
+	 * - Adjacent blocks at same depth
+	 */
+	siblings: {
+		prev: HTMLElement | null;
+		next: HTMLElement | null;
+	};
+	/**
+	 * - getBoundingClientRect() of the element (caller handles scroll/iframe offset)
+	 */
+	rect: DOMRect;
+};
+export type FormatAPI = {
+	getLine: (node: Node, validation?: (current: any) => boolean) => HTMLElement | null;
+	getBlock: (element: Node, validation?: (current: any) => boolean) => HTMLElement | null;
+	isLine: (element: Node) => boolean;
+	isBlock: (element: Node) => boolean;
+};

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

@@ -1,5 +1,62 @@
 import type {} from '../../../typedef';
 export default Menu;
+export type DropdownItem = {
+	/**
+	 * - `data-command` attribute value
+	 */
+	command: string;
+	/**
+	 * - `data-value` attribute value
+	 */
+	value?: string;
+	/**
+	 * - Title text (used for `title` and `aria-label`)
+	 */
+	title: string;
+	/**
+	 * - Button inner HTML content
+	 */
+	innerHTML: string;
+	/**
+	 * - Additional CSS class for the `<button>`
+	 */
+	className?: string;
+	/**
+	 * - Extra data attributes (e.g. `{ 'data-class': 'xxx' }`)
+	 */
+	attrs?: {
+		[x: string]: string;
+	};
+	/**
+	 * - Rendered button element (set by `initDropdownTarget`)
+	 */
+	_element?: HTMLElement;
+};
+/**
+ * @typedef {Object} DropdownItem
+ * @property {string} command - `data-command` attribute value
+ * @property {string} [value] - `data-value` attribute value
+ * @property {string} title - Title text (used for `title` and `aria-label`)
+ * @property {string} innerHTML - Button inner HTML content
+ * @property {string} [className] - Additional CSS class for the `<button>`
+ * @property {Object<string, string>} [attrs] - Extra data attributes (e.g. `{ 'data-class': 'xxx' }`)
+ * @property {HTMLElement} [_element] - Rendered button element (set by `initDropdownTarget`)
+ */
+/**
+ * @description Creates a dropdown menu element from standardized item objects.
+ * @param {Array<DropdownItem>} items - Menu items
+ * @param {Object} [options]
+ * @param {string} [options.className] - Additional class for the wrapper `<div>`
+ * @param {string} [options.prependHTML] - HTML to prepend inside the `<ul>` (e.g. default value items)
+ * @returns {HTMLElement}
+ */
+export function CreateDropdownMenu(
+	items: Array<DropdownItem>,
+	options?: {
+		className?: string;
+		prependHTML?: string;
+	},
+): HTMLElement;
 /**
  * @description Dropdown and container menu management class
  */
@@ -13,6 +70,10 @@ declare class Menu {
 	targetMap: {
 		[x: string]: HTMLElement;
 	};
+	/** @type {Object<string, Array<DropdownItem>>} Structured items keyed by plugin name */
+	itemsMap: {
+		[x: string]: DropdownItem[];
+	};
 	index: number;
 	menus: any[];
 	currentButton: HTMLButtonElement;
@@ -28,7 +89,11 @@ declare class Menu {
 	 * @description Method for managing dropdown element.
 	 * - You must add the `dropdown` element using this method at custom plugin.
 	 * @param {{key: string, type: string}} classObj Class object
-	 * @param {Node} menu Dropdown element
+	 * @param {Node|Array<DropdownItem>} menuOrItems Dropdown element or array of standardized items
+	 * @param {Object} [options] Options when passing items array
+	 * @param {string} [options.className] Additional CSS class for the wrapper element
+	 * @param {string} [options.prependHTML] HTML to prepend inside the `<ul>` (e.g. default/sub-list items)
+	 * @returns {HTMLElement} The registered menu element
 	 */
 	initDropdownTarget(
 		{
@@ -38,8 +103,12 @@ declare class Menu {
 			key: string;
 			type: string;
 		},
-		menu: Node,
-	): void;
+		menuOrItems: Node | Array<DropdownItem>,
+		options?: {
+			className?: string;
+			prependHTML?: string;
+		},
+	): HTMLElement;
 	/**
 	 * @description Opens the dropdown menu for the specified button.
 	 * @param {Node} button Dropdown's button element to call

package/types/core/logic/shell/commandDispatcher.d.ts

@@ -50,6 +50,14 @@ export default class CommandDispatcher {
 	 * @param {HTMLButtonElement} target - The associated command button.
 	 */
 	registerTargets(cmd: string, target: HTMLButtonElement): void;
+	/**
+	 * @description Inverse of {@link registerTargets}. Removes a previously registered target so
+	 * ephemeral participants (e.g. CommandMenu rows) can opt out of the active-state pass on close.
+	 * Drops the command entry when its target array empties.
+	 * @param {string} cmd - The command identifier.
+	 * @param {HTMLElement} target - The target previously registered.
+	 */
+	unregisterTargets(cmd: string, target: HTMLElement): void;
 	resetTargets(): void;
 	/**
 	 * @internal

package/types/core/logic/shell/component.d.ts

@@ -25,10 +25,12 @@ declare class Component {
 	 */
 	currentTarget: Node | null;
 	/**
-	 * @description Currently selected component plugin instance
-	 * @type {*}
+	 * @description Currently selected component plugin instance (a full plugin) or a
+	 * launcher stand-in for non-plugin components (e.g. `pageBreak`). Consumers call the
+	 * shared component hooks (`componentDestroy`/`componentSelect`/`componentDeselect`) on it.
+	 * @type {?SunEditor.ComponentLauncher}
 	 */
-	currentPlugin: any;
+	currentPlugin: SunEditor.ComponentLauncher | null;
 	/**
 	 * @description Currently selected component plugin name
 	 * @type {*}

package/types/core/logic/shell/shortcuts.d.ts

@@ -107,7 +107,16 @@ declare class Shortcuts {
 	 * @param {Range} range The current range object
 	 * @returns {boolean} Whether to execute shortcuts
 	 */
-	command(event: KeyboardEvent, ctrl: boolean, shift: boolean, keyCode: string, text: string, edge: boolean, line: HTMLElement, range: Range): boolean;
+	command(
+		event: KeyboardEvent,
+		ctrl: boolean,
+		shift: boolean,
+		keyCode: string,
+		text: string,
+		edge: boolean,
+		line: HTMLElement,
+		range: Range,
+	): boolean;
 	/**
 	 * @description Disable the shortcut activation.
 	 */

package/types/core/logic/shell/ui.d.ts

@@ -160,7 +160,12 @@ declare class UIManager {
 	/**
 	 * @param {SunEditor.FrameContext} rt Root target[key] FrameContext
 	 */
-	reset(rt: SunEditor.FrameContext): void;
+	/**
+	 * @description Block handle instance for external access.
+	 * @type {BlockHandle}
+	 */
+	get blockHandle(): BlockHandle;
+	reset(rt: any): void;
 	/**
 	 * @internal
 	 * @description Closes all open controllers except those marked as `fixed`.
@@ -259,3 +264,4 @@ declare class UIManager {
 	opendBrowser: any;
 	#private;
 }
+import BlockHandle from '../panel/blockHandle.js';

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

@@ -38,7 +38,13 @@ import type {} from '../../typedef';
  * @param {?Element} statusbarContainer - Status bar container element.
  * @returns {SunEditor.Context} - A map of key DOM nodes used throughout the editor.
  */
-export function CreateContext(toolbar: Element, toolbarContainer: Element | null, menuTray: Element, subbar: Element | null, statusbarContainer: Element | null): SunEditor.Context;
+export function CreateContext(
+	toolbar: Element,
+	toolbarContainer: Element | null,
+	menuTray: Element,
+	subbar: Element | null,
+	statusbarContainer: Element | null,
+): SunEditor.Context;
 /**
  * This object stores **global editor-level UI references** for a SunEditor instance.
  *

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

@@ -33,6 +33,7 @@ import type {} from '../../typedef';
  * @property {HTMLTextAreaElement} markdown - Markdown view editing element (a <textarea>).
  * @property {HTMLTextAreaElement} markdownNumbers - Element displaying line numbers in markdown view mode.
  * @property {HTMLElement} placeholder - Placeholder element shown when the editor is empty.
+ * @property {string} placeholder_line - Per-line placeholder text, rendered via a `::before` on the focused empty line.
  * @property {HTMLElement} statusbar - Editor status bar element (for resizing, info, etc.).
  * @property {HTMLElement} navigation - Navigation element (e.g., for outline or bookmarks).
  * @property {HTMLElement} charWrapper - Wrapper for the character counter element.
@@ -45,6 +46,10 @@ import type {} from '../../typedef';
  * === UI Utilities & Visual Components ===
  * @property {HTMLElement} lineBreaker_t - Top floating line-breaker UI element (for line insertion).
  * @property {HTMLElement} lineBreaker_b - Bottom floating line-breaker UI element (for line insertion).
+ * @property {?HTMLElement} blockHandleArea - Gutter container (`.se-block-handle-area`) holding the per-line block handle. `null` when the `blockHandle` option is disabled.
+ * @property {?HTMLElement} blockHandle - Block handle group (`.se-block-handle`) containing the plus and drag buttons. `null` when disabled.
+ * @property {?HTMLElement} blockHandlePlus - Plus button (`.se-block-handle-plus`) — inserts a new line after the current block. `null` when disabled.
+ * @property {?HTMLElement} blockHandleDrag - Drag button (`.se-block-handle-drag`) — opens the action menu / starts drag-to-reorder. `null` when disabled.
  * @property {HTMLElement} [_stickyDummy] - Placeholder element used for sticky toolbar behavior.
  * @property {HTMLElement} [_toolbarShadow] - Shadow element below the toolbar for visual effects.
  * @property {{main: HTMLElement, border: HTMLElement, display: HTMLElement, handles: HTMLElement[]}} [_figure] - Current active figure component (image, table, etc.).
@@ -88,8 +93,11 @@ import type {} from '../../typedef';
  * @param {HTMLElement} wwFrame Editor wysiwyg frame
  * @param {HTMLElement} codeWrapper Editor code view wrapper
  * @param {HTMLElement} codeFrame Editor code view frame
- * @param {{inner: HTMLElement, page: HTMLElement, pageMirror: HTMLElement}} documentTypeInner Document type elements
+ * @param {?HTMLElement} markdownWrapper Editor markdown view wrapper (only present when the markdown view button is enabled)
+ * @param {?HTMLElement} markdownFrame Editor markdown view frame (only present when the markdown view button is enabled)
  * @param {?HTMLElement} statusbar Editor statusbar
+ * @param {{inner: HTMLElement, page: HTMLElement, pageMirror: HTMLElement}} documentTypeInner Document type elements
+ * @param {?HTMLElement} blockHandleArea Block handle gutter (`.se-block-handle-area`). `null` when the `blockHandle` option is disabled.
  * @param {*} key root key
  * @returns {FrameContexType}
  */
@@ -103,14 +111,15 @@ export function CreateFrameContext(
 	wwFrame: HTMLElement,
 	codeWrapper: HTMLElement,
 	codeFrame: HTMLElement,
-	markdownWrapper: any,
-	markdownFrame: any,
+	markdownWrapper: HTMLElement | null,
+	markdownFrame: HTMLElement | null,
 	statusbar: HTMLElement | null,
 	documentTypeInner: {
 		inner: HTMLElement;
 		page: HTMLElement;
 		pageMirror: HTMLElement;
 	},
+	blockHandleArea: HTMLElement | null,
 	key: any,
 ): FrameContexType;
 /**
@@ -118,7 +127,10 @@ export function CreateFrameContext(
  * @param {HTMLElement} statusbar Statusbar element
  * @param {FrameContexType|import('../config/contextProvider').FrameContextMap} mapper FrameContext map
  */
-export function UpdateStatusbarContext(statusbar: HTMLElement, mapper: FrameContexType | import('../config/contextProvider').FrameContextMap): void;
+export function UpdateStatusbarContext(
+	statusbar: HTMLElement,
+	mapper: FrameContexType | import('../config/contextProvider').FrameContextMap,
+): void;
 /**
  * This object stores **all frame-specific states and DOM references** for a SunEditor instance.
  *
@@ -201,6 +213,10 @@ export type FrameContextStore = {
 	 * - Placeholder element shown when the editor is empty.
 	 */
 	placeholder: HTMLElement;
+	/**
+	 * - Per-line placeholder text, rendered via a `::before` on the focused empty line.
+	 */
+	placeholder_line: string;
 	/**
 	 * - Editor status bar element (for resizing, info, etc.).
 	 */
@@ -243,6 +259,22 @@ export type FrameContextStore = {
 	 * - Bottom floating line-breaker UI element (for line insertion).
 	 */
 	lineBreaker_b: HTMLElement;
+	/**
+	 * - Gutter container (`.se-block-handle-area`) holding the per-line block handle. `null` when the `blockHandle` option is disabled.
+	 */
+	blockHandleArea: HTMLElement | null;
+	/**
+	 * - Block handle group (`.se-block-handle`) containing the plus and drag buttons. `null` when disabled.
+	 */
+	blockHandle: HTMLElement | null;
+	/**
+	 * - Plus button (`.se-block-handle-plus`) — inserts a new line after the current block. `null` when disabled.
+	 */
+	blockHandlePlus: HTMLElement | null;
+	/**
+	 * - Drag button (`.se-block-handle-drag`) — opens the action menu / starts drag-to-reorder. `null` when disabled.
+	 */
+	blockHandleDrag: HTMLElement | null;
 	/**
 	 * - Placeholder element used for sticky toolbar behavior.
 	 */