suneditor 3.3.0 → 3.3.2

package/types/core/event/effects/ruleHelpers.d.ts

@@ -51,3 +51,59 @@ export function isRtlBidiMismatch(
 	detectedEdge: 'front' | 'end',
 	doc: Document,
 ): boolean;
+/**
+ * @description Whether the caret sits on a bare `<br>` that stands at the front/end edge of its `line`.
+ * @param {Range} range - The current range
+ * @param {Node} selectionNode - Current selection node
+ * @param {'front'|'end'} edge - Edge to test: `front` for Backspace, `end` for Delete
+ * @returns {boolean} `true` if the caret is on an edge `<br>`
+ */
+export function isEdgeBreakCaret(range: Range, selectionNode: Node, edge: 'front' | 'end'): boolean;
+/**
+ * @description The previous/next element in document order — crossing in and out of blocks (list, quote).
+ * - Out of list-cell ancestors (a nested list), stopping at a closure block (table cell).
+ * @param {EventPorts['format']} format - Format module
+ * @param {?HTMLElement} line - The caret's `line` element
+ * @param {'front'|'end'} edge - `front` for the previous element, `end` for the next one
+ * @returns {?HTMLElement} The adjacent element, or `null` at the document edge
+ */
+export function getAdjacentElement(
+	format: EventPorts['format'],
+	line: HTMLElement | null,
+	edge: 'front' | 'end',
+): HTMLElement | null;
+/**
+ * @description The previous/next `line` in document order — {@link getAdjacentElement} filtered to lines.
+ * - `null` means either the document edge or a non-`line` neighbour (a component); use
+ * {@link getAdjacentElement} when the two must be told apart.
+ * @param {EventPorts['format']} format - Format module
+ * @param {?HTMLElement} line - The caret's `line` element
+ * @param {'front'|'end'} edge - `front` for the previous line, `end` for the next one
+ * @returns {?HTMLElement} The adjacent line, or `null`
+ */
+export function getAdjacentLine(
+	format: EventPorts['format'],
+	line: HTMLElement | null,
+	edge: 'front' | 'end',
+): HTMLElement | null;
+/**
+ * @description The neighbouring `line` an empty line collapses into, or `null` when there is nothing to merge.
+ * - A cell owning a nested list belongs to {@link getNestedListTarget} instead.
+ * @param {EventPorts['format']} format - Format module
+ * @param {?HTMLElement} formatEl - The caret's `line` element
+ * @param {'front'|'end'} edge - `front` for Backspace (previous line), `end` for Delete (next line)
+ * @returns {?HTMLElement} The neighbouring line to merge into, or `null`
+ */
+export function getEmptyLineMergeTarget(
+	format: EventPorts['format'],
+	formatEl: HTMLElement | null,
+	edge: 'front' | 'end',
+): HTMLElement | null;
+/**
+ * @description The nested list a list-cell Backspace/Delete would lift, or `null` when there is none.
+ * - The rules gate their list branch on it so the branch can't claim the key with nothing to do.
+ * @param {HTMLElement} formatEl - The caret's list cell
+ * @param {HTMLElement} rangeEl - The list (`UL`/`OL`) the cell belongs to
+ * @returns {?HTMLElement} The element carrying the nested list, or `null`
+ */
+export function getNestedListTarget(formatEl: HTMLElement, rangeEl: HTMLElement): HTMLElement | null;

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

@@ -12,9 +12,8 @@ declare class BlockHandle {
 	 * @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.
+	 * @param {Object|Array<*>|null} blockHandleOptions - The `blockHandle` option object (`{ menu, onPlusClick, maxHeight, minWidth }`).
+	 * - An array is accepted as a shorthand for `{ menu: [...] }`.
 	 */
 	constructor(
 		$: SunEditor.Deps,
@@ -22,19 +21,7 @@ declare class BlockHandle {
 		blockHandle: HTMLElement,
 		blockHandlePlus: HTMLElement,
 		blockHandleDrag: HTMLElement,
-		menuConfig: Array<
-			| string
-			| {
-					title: string;
-					icon?: string;
-					action: (
-						arg0: SunEditor.Deps,
-						arg1: {
-							block: HTMLElement;
-						},
-					) => void;
-			  }
-		> | null,
+		blockHandleOptions: any | Array<any> | null,
 	);
 	/**
 	 * @description Position the block handle for the given mouse target. Uses rAF throttle.

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

@@ -15,11 +15,6 @@ declare class UIManager {
 	toastPopup: HTMLElement;
 	toastContainer: Element;
 	toastMessage: HTMLSpanElement;
-	/**
-	 * @description Whether `SelectMenu` is open
-	 * @type {boolean}
-	 */
-	selectMenuOn: boolean;
 	/**
 	 * @description Currently open `Controller` info array
 	 * @type {Array<SunEditor.Module.Controller.Info>}
@@ -36,6 +31,20 @@ declare class UIManager {
 	 * @type {?HTMLElement}
 	 */
 	_figureContainer: HTMLElement | null;
+	/**
+	 * @description Whether any `SelectMenu` is currently open.
+	 * - Read-only: a menu announces itself through {@link setSelectMenuOpen}. Derived from the set of
+	 * open instances so an unrelated menu closing cannot clear the flag for a menu that is still open.
+	 * @returns {boolean}
+	 */
+	get selectMenuOn(): boolean;
+	/**
+	 * @internal
+	 * @description `SelectMenu` open-state notification. Called by `SelectMenu.open()` / `.close()`.
+	 * @param {*} instance The `SelectMenu` instance changing state
+	 * @param {boolean} open `true` on open, `false` on close
+	 */
+	setSelectMenuOpen(instance: any, open: boolean): void;
 	/**
 	 * @description Set editor frame styles.
 	 * - Define the style of the edit area

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

@@ -28,6 +28,7 @@ export namespace DEFAULTS {
 		'@text': string;
 		'@line': string;
 		'@component': string;
+		li: string;
 		'table|th|td': string;
 		'table|td': string;
 		tr: string;
@@ -270,9 +271,25 @@ export namespace DEFAULTS {
  *   menu: [
  *     'p', 'heading', 'blockStyle',
  *     { title: 'Duplicate', icon: 'copy', action: ($, { block }) => block.after(block.cloneNode(true)) },
+ *     // `'table'` as a string opens the size picker; a custom item inserts a default table directly
+ *     { title: 'Table', icon: 'table', action: ($) => $.plugins.table.insert(3, 3) },
  *   ],
  * }
  * ```
+ * @property {string} [blockHandle.maxHeight=""] - Max height of the menu list. Any CSS length; the list scrolls past it.
+ * - Unset by default: the menu grows with its items and is only clamped when it would overflow the viewport.
+ * @property {string} [blockHandle.minWidth="200px"] - Min width of the menu.
+ * @property {function(SunEditor.Deps, { block: HTMLElement, openMenu: function(): void }): void} [blockHandle.onPlusClick] - Runs after the plus button inserted a new line.
+ * - Adding the line is fixed behavior; this hook decides what happens next. Nothing does by default.
+ * - `block` is the new line, already focused. `openMenu()` opens the block handle's own `menu`.
+ * ```js
+ * blockHandle: {
+ *   // open the block handle menu
+ *   onPlusClick: ($, { openMenu }) => openMenu(),
+ *   // ...or the slash command menu
+ *   onPlusClick: ($, { block }) => $.plugins.slashCommand.open(block),
+ * }
+ * ```
  * @property {string} [type=""] - Editor type. Use `"document"` for a document-style layout, with optional sub-types after `:`.
  * ```js
  * // type
@@ -384,7 +401,7 @@ export namespace DEFAULTS {
  * - Value is a pipe-delimited list of allowed style names.
  * - Resolution order when filtering an element: `@component` (for `.se-component` containers) → explicit tag entry → `@line` (for formatLine elements) → `@text` (for textStyleTags).
  * - `@component` guards the inline sizing (`width`/`height`/`min-width`) the editor writes on a media component's container for percentage-based sizes; keep these so a clean() round-trip does not reset the component to full width.
- * - An explicit tag entry **replaces** the category default — include category styles in the value if you want both.
+ * - An explicit tag entry is **merged** with its category default when the tag belongs to one (`@line` for formatLine elements, else `@text` for textStyleTags) — the entry adds styles on top of the category's.
  * - Merged with {@link DEFAULTS.TAG_STYLES}; user-supplied keys win.
  * ```js
  * {
@@ -392,8 +409,8 @@ export namespace DEFAULTS {
  *     '@text': 'color|font-size|background-color',  // default for span, b, i, em, ...
  *     '@line': 'text-align|margin|line-height',     // default for p, h1-h6, div, li, ...
  *     'table|td': 'border|color|background-color',  // per-tag whitelist
- *     div: 'color',                                   // explicit override; ignores `@line` default
- *     hr: 'border-top',
+ *      div: 'color',                                 // merged with the `@line` default (div is a line element)
+ *      hr: 'border-top',
  *   }
  * }
  * ```
@@ -1056,6 +1073,15 @@ export type EditorBaseOptions = {
 					) => void;
 			  }
 		>;
+		maxHeight?: string;
+		minWidth?: string;
+		onPlusClick?: (
+			arg0: SunEditor.Deps,
+			arg1: {
+				block: HTMLElement;
+				openMenu: () => void;
+			},
+		) => void;
 	};
 	/**
 	 * - Editor type. Use `"document"` for a document-style layout, with optional sub-types after `:`.
@@ -1229,7 +1255,7 @@ export type EditorBaseOptions = {
 	 * - Value is a pipe-delimited list of allowed style names.
 	 * - Resolution order when filtering an element: `@component` (for `.se-component` containers) → explicit tag entry → `@line` (for formatLine elements) → `@text` (for textStyleTags).
 	 * - `@component` guards the inline sizing (`width`/`height`/`min-width`) the editor writes on a media component's container for percentage-based sizes; keep these so a clean() round-trip does not reset the component to full width.
-	 * - An explicit tag entry **replaces** the category default — include category styles in the value if you want both.
+	 * - An explicit tag entry is **merged** with its category default when the tag belongs to one (`@line` for formatLine elements, else `@text` for textStyleTags) — the entry adds styles on top of the category's.
 	 * - Merged with {@link DEFAULTS.TAG_STYLES}; user-supplied keys win.
 	 * ```js
 	 * {
@@ -1237,7 +1263,7 @@ export type EditorBaseOptions = {
 	 * '@text': 'color|font-size|background-color',  // default for span, b, i, em, ...
 	 * '@line': 'text-align|margin|line-height',     // default for p, h1-h6, div, li, ...
 	 * 'table|td': 'border|color|background-color',  // per-tag whitelist
-	 * div: 'color',                                   // explicit override; ignores `@line` default
+	 * div: 'color',                                 // merged with the `@line` default (div is a line element)
 	 * hr: 'border-top',
 	 * }
 	 * }

package/types/events.d.ts

@@ -35,7 +35,7 @@ export type ClipboardEvent = {
 	 */
 	maxCharCount: boolean;
 	/**
-	 * - `"SE"`|`"MS"`|`""` - source
+	 * - `"SE"`|`"MS"`|`"GOOGLE"`|`""` - source
 	 */
 	from: string;
 };
@@ -289,7 +289,7 @@ export type EventHandlers = {
  * @property {Event} event - event object
  * @property {string} data - drop data
  * @property {boolean} maxCharCount - is max char count
- * @property {string} from - `"SE"`|`"MS"`|`""` - source
+ * @property {string} from - `"SE"`|`"MS"`|`"GOOGLE"`|`""` - source
  */
 /**
  * @typedef {Object} FileManagementInfo

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

@@ -198,7 +198,8 @@ export function getEdgeChildNodes(
 };
 /**
  * @template {Node} T
- * @description Gets the previous sibling last child. If there is no sibling, then it'll take it from the closest ancestor with child
+ * @description Gets the previous sibling last child. If there is no sibling, then it'll take it from the closest ancestor with child.
+ * - Components (image, table, etc.) are treated as a single tag and not traversed into.
  * @param {Node} node Reference element
  * @param {?Node} [ceiling] Highest boundary allowed
  * @returns {T|null} Not found: `null`
@@ -206,7 +207,8 @@ export function getEdgeChildNodes(
 export function getPreviousDeepestNode<T extends Node>(node: Node, ceiling?: Node | null): T | null;
 /**
  * @template {Node} T
- * @description Gets the next sibling first child. If there is no sibling, then it'll take it from the closest ancestor with child
+ * @description Gets the next sibling first child. If there is no sibling, then it'll take it from the closest ancestor with child.
+ * - Components (image, table, etc.) are treated as a single tag and not traversed into.
  * @param {Node} node Reference element
  * @param {?Node} [ceiling] Highest boundary allowed
  * @returns {T|null} Not found: `null`

package/types/helper/googleDocs.d.ts

@@ -0,0 +1,19 @@
+import type {} from '../typedef';
+/**
+ * @description Whether the HTML string is a Google Docs clipboard payload.
+ * @param {string} html HTML string
+ * @returns {boolean}
+ */
+export function isGoogleDocs(html: string): boolean;
+/**
+ * @description Removes the Google Docs clipboard wrapper tags, keeping their children.
+ * - Only the guid-carrying inline wrappers (`b`/`span`) are unwrapped; real formatting tags inside are untouched.
+ * @param {string} html HTML string
+ * @returns {string} HTML string
+ */
+export function cleanHTML(html: string): string;
+declare namespace _default {
+	export { isGoogleDocs };
+	export { cleanHTML };
+}
+export default _default;

package/types/helper/index.d.ts

@@ -178,6 +178,10 @@ export const markdown: {
 export const msOffice: {
 	cleanHTML: typeof import('./msOffice').cleanHTML;
 };
+export const googleDocs: {
+	isGoogleDocs: typeof import('./googleDocs').isGoogleDocs;
+	cleanHTML: typeof import('./googleDocs').cleanHTML;
+};
 declare namespace _default {
 	export { env };
 	export { unicode };
@@ -188,5 +192,6 @@ declare namespace _default {
 	export { clipboard };
 	export { markdown };
 	export { msOffice };
+	export { googleDocs };
 }
 export default _default;

package/types/modules/ui/CommandMenu.d.ts

@@ -111,6 +111,13 @@ export type CommandMenuParams = {
 			icons: any;
 		},
 	) => string;
+	/**
+	 * - Optional owner hook run once,
+	 * - immediately before the user commits inside a dropdown-free flyout (SlashCommand uses it to delete the typed `/query`).
+	 * - A native submenu gets this for free — its commit routes back through `SelectMenu`'s select callback —
+	 * - but a flyout is the plugin's own DOM, so the moment has to be intercepted.
+	 */
+	prepareCommit?: () => void;
 };
 /**
  * @typedef {Object} CommandMenuItem
@@ -148,6 +155,10 @@ export type CommandMenuParams = {
  * @property {Object} selectMenuParams - Base SelectMenu params (`position`, `minWidth`, `keydownTarget`, etc.).
  * @property {function(CommandMenuItem, { icons: Object }): string} [renderCustomItem] - Optional renderer
  *   applied to custom (object) items only. Plugin-string items always render with `buildRowHTML`.
+ * @property {function(): void} [prepareCommit] - Optional owner hook run once,
+ * - immediately before the user commits inside a dropdown-free flyout (SlashCommand uses it to delete the typed `/query`).
+ * - A native submenu gets this for free — its commit routes back through `SelectMenu`'s select callback —
+ * - but a flyout is the plugin's own DOM, so the moment has to be intercepted.
  */
 /**
  * @class

package/types/modules/ui/SelectMenu.d.ts

@@ -31,11 +31,15 @@ export type SelectMenuParams = {
 	 */
 	closeMethod?: () => void;
 	/**
-	 * Optional owner hook invoked on ESC before the menu closes.
-	 * Return `true` if it dismissed an owner-managed sub-panel (e.g. CommandMenu's flyout), so ESC only
-	 * closes that sub-panel and keeps the menu open.
+	 * Optional owner hook that dismisses an owner-managed sub-panel (e.g. CommandMenu's dropdown-free flyout) and puts the cursor back on its row.
+	 * Return `true` when a sub-panel was actually dismissed.
 	 */
 	subEscMethod?: () => boolean;
+	/**
+	 * Optional owner hook answering "does the row at `index` own a sub-panel?".
+	 * - A query only — it must not open anything.
+	 */
+	subCheckMethod?: (index: number) => boolean;
 	/**
 	 * Optional max-height CSS value (e.g. `"200px"`). Enables scrolling when items exceed this height.
 	 */
@@ -66,9 +70,10 @@ export type SelectMenuParams = {
  * @property {number} [splitNum=0] Optional split number for horizontal positioning; defines how many items per row
  * @property {() => void} [openMethod] Optional method to call when the menu is opened
  * @property {() => void} [closeMethod] Optional method to call when the menu is closed
- * @property {() => boolean} [subEscMethod] Optional owner hook invoked on ESC before the menu closes.
- * Return `true` if it dismissed an owner-managed sub-panel (e.g. CommandMenu's flyout), so ESC only
- * closes that sub-panel and keeps the menu open.
+ * @property {() => boolean} [subEscMethod] Optional owner hook that dismisses an owner-managed sub-panel (e.g. CommandMenu's dropdown-free flyout) and puts the cursor back on its row.
+ * Return `true` when a sub-panel was actually dismissed.
+ * @property {(index: number) => boolean} [subCheckMethod] Optional owner hook answering "does the row at `index` own a sub-panel?".
+ * - A query only — it must not open anything.
  * @property {string} [maxHeight] Optional max-height CSS value (e.g. `"200px"`). Enables scrolling when items exceed this height.
  * @property {string} [minWidth] Optional min-width CSS value (e.g. `"130px"`).
  * @property {*} [keydownTarget]  Optional override for the keyboard navigation target. By default `on()` listens
@@ -104,6 +109,7 @@ declare class SelectMenu {
 	openMethod: () => void;
 	closeMethod: () => void;
 	subEscMethod: () => boolean;
+	subCheckMethod: (index: number) => boolean;
 	maxHeight: string;
 	minWidth: string;
 	/**
@@ -193,6 +199,6 @@ declare class SelectMenu {
 	 * @returns {boolean}
 	 */
 	hasOpenSubmenu(): boolean;
-	_onItem: Element;
+	_onItem: any;
 	#private;
 }

package/types/plugins/dropdown/table/index.d.ts

@@ -153,6 +153,17 @@ declare class Table extends PluginDropdownFree {
 	 * @description Closes table-related controllers and table figure
 	 */
 	_closeTableSelectInfo(): void;
+	/**
+	 * @description Insert a table of the given size at the caret and place the caret in its first cell.
+	 * @param {number} [cols=3] - Column count
+	 * @param {number} [rows=3] - Row count
+	 * @returns {boolean} `true` when the table was inserted
+	 * @example
+	 * // insert a 3x3 table without going through the size picker
+	 * editor.plugins.table.insert();
+	 * editor.plugins.table.insert(4, 2);
+	 */
+	insert(cols?: number, rows?: number): boolean;
 	#private;
 }
 import { PluginDropdownFree } from '../../../interfaces';

package/types/plugins/dropdown/table/shared/table.constants.d.ts

@@ -2,6 +2,7 @@ import type {} from '../../../../typedef';
 export const ROW_SELECT_MARGIN: 6;
 export const CELL_SELECT_MARGIN: 6;
 export const CELL_DECIMAL_END: 0;
+export const DEFAULT_SIZE: number[];
 export const RESIZE_CELL_CLASS: '.se-table-resize-line';
 export const RESIZE_CELL_PREV_CLASS: '.se-table-resize-line-prev';
 export const RESIZE_ROW_CLASS: '.se-table-resize-row';

package/types/plugins/field/slashCommand.d.ts

@@ -54,9 +54,18 @@ export type SlashCommandPluginOptions = {
 	 */
 	delayTime?: number;
 	/**
-	 * - Maximum number of items shown in the dropdown.
+	 * - Maximum number of items kept after filtering. `0` (default) keeps every match
+	 * - the list scrolls within `maxHeight`, so a cap only hides matches the user can no longer reach.
 	 */
 	limitSize?: number;
+	/**
+	 * - Max height of the menu list. Any CSS length; the list scrolls past it.
+	 */
+	maxHeight?: string;
+	/**
+	 * - Min width of the menu.
+	 */
+	minWidth?: string;
 	/**
 	 * - Message shown when no items match the query. If unset, the menu closes on no match.
 	 */
@@ -93,6 +102,15 @@ export type SlashCommandPluginOptions = {
 	 * // A container block (BLOCKQUOTE, DIV…): `applyBlock` WRAPS the selected lines → `<blockquote>…</blockquote>`.
 	 * action: ($) => $.format.applyBlock(document.createElement('BLOCKQUOTE')),
 	 * },
+	 * {
+	 * key: 'table',
+	 * title: 'Table',
+	 * icon: 'table',
+	 * // A plugin-name entry (`'table'`) opens that plugin's own UI — for table, the size picker,
+	 * // which is driven by the pointer. A custom item skips it and inserts straight away, which
+	 * // keeps the whole gesture on the keyboard: type the trigger, press Enter, done.
+	 * action: ($) => $.plugins.table.insert(3, 3),
+	 * },
 	 * 'bold',
 	 * 'image',
 	 * 'blockStyle',
@@ -131,7 +149,10 @@ export type SlashCommandPluginOptions = {
  *   (plugin names, built-in commands like `'bold'`); objects are custom items with their own `action`.
  *   Required.
  * @property {number} [delayTime=120] - Debounce delay (ms) before the input is inspected for the trigger.
- * @property {number} [limitSize=10] - Maximum number of items shown in the dropdown.
+ * @property {number} [limitSize=0] - Maximum number of items kept after filtering. `0` (default) keeps every match
+ *   - the list scrolls within `maxHeight`, so a cap only hides matches the user can no longer reach.
+ * @property {string} [maxHeight='320px'] - Max height of the menu list. Any CSS length; the list scrolls past it.
+ * @property {string} [minWidth='200px'] - Min width of the menu.
  * @property {string} [emptyMessage] - Message shown when no items match the query. If unset, the menu closes on no match.
  * @property {function(SlashCommandItem, { icons: Object }): string} [renderItem] - Custom item HTML renderer.
  *   Applied only to custom item objects; plugin-name entries always render with the canonical BlockHandle row.
@@ -164,6 +185,15 @@ export type SlashCommandPluginOptions = {
  *         // A container block (BLOCKQUOTE, DIV…): `applyBlock` WRAPS the selected lines → `<blockquote>…</blockquote>`.
  *         action: ($) => $.format.applyBlock(document.createElement('BLOCKQUOTE')),
  *       },
+ *       {
+ *         key: 'table',
+ *         title: 'Table',
+ *         icon: 'table',
+ *         // A plugin-name entry (`'table'`) opens that plugin's own UI — for table, the size picker,
+ *         // which is driven by the pointer. A custom item skips it and inserts straight away, which
+ *         // keeps the whole gesture on the keyboard: type the trigger, press Enter, done.
+ *         action: ($) => $.plugins.table.insert(3, 3),
+ *       },
  *       'bold',
  *       'image',
  *       'blockStyle',
@@ -191,6 +221,17 @@ declare class SlashCommand extends PluginField {
 	controller: Controller;
 	onInput(params: SunEditor.HookParams.InputWithData): void;
 	onKeyDown(params: SunEditor.HookParams.KeyEvent): void | boolean;
+	/**
+	 * @description Open the command menu programmatically, with no trigger character typed and the full tem list shown.
+	 * - Intended for host UI that wants the same menu without the `/` shortcut — e.g. the
+	 * - block handle's plus button:
+	 * ```js
+	 * blockHandle: { onPlusClick: ($, { block }) => $.plugins.slashCommand.open(block) }
+	 * ```
+	 * @param {Node} anchorNode - Node the menu anchors to (typically the line the caret sits on).
+	 * @returns {boolean} `true` if the menu was opened
+	 */
+	open(anchorNode: Node): boolean;
 	#private;
 }
 import { PluginField } from '../../interfaces';