suneditor 3.0.5 → 3.1.0

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

@@ -25,7 +25,10 @@ export type ModalAnchorEditorParams = {
 	 * - Default `rel` values auto-applied by condition.
 	 * `default` is always applied, `check_new_window` when "Open in new window" is checked, `check_bookmark` for bookmark links.
 	 * ```js
-	 * { relList: ['nofollow', 'noreferrer', 'noopener'], defaultRel: { default: 'noopener', check_new_window: 'noreferrer' } }
+	 * {
+	 * relList: ['nofollow', 'noreferrer', 'noopener'],
+	 * defaultRel: { default: 'noopener', check_new_window: 'noreferrer' }
+	 * }
 	 * ```
 	 */
 	defaultRel?: {
@@ -35,6 +38,18 @@ export type ModalAnchorEditorParams = {
 	};
 	/**
 	 * - File upload URL.
+	 * - The server must return:
+	 * ```js
+	 * {
+	 * "result": [
+	 * {
+	 * "url": "https://example.com/file.pdf",
+	 * "name": "file.pdf",
+	 * "size": 1048576
+	 * }
+	 * ]
+	 * }
+	 * ```
 	 */
 	uploadUrl?: string;
 	/**
@@ -70,9 +85,24 @@ export type ModalAnchorEditorParams = {
  * @property {{default?: string, check_new_window?: string, check_bookmark?: string}} [defaultRel={}] - Default `rel` values auto-applied by condition.
  * `default` is always applied, `check_new_window` when "Open in new window" is checked, `check_bookmark` for bookmark links.
  * ```js
- * { relList: ['nofollow', 'noreferrer', 'noopener'], defaultRel: { default: 'noopener', check_new_window: 'noreferrer' } }
+ * {
+ * 	  relList: ['nofollow', 'noreferrer', 'noopener'],
+ *    defaultRel: { default: 'noopener', check_new_window: 'noreferrer' }
+ * }
  * ```
  * @property {string} [uploadUrl] - File upload URL.
+ * - The server must return:
+ * ```js
+ * {
+ *   "result": [
+ *     {
+ *       "url": "https://example.com/file.pdf",
+ *       "name": "file.pdf",
+ *       "size": 1048576
+ *     }
+ *   ]
+ * }
+ * ```
  * @property {Object<string, string>} [uploadHeaders] - File upload headers.
  * @property {number} [uploadSizeLimit] - File upload size limit.
  * @property {number} [uploadSingleSizeLimit] - File upload single size limit.

package/types/plugins/browser/audioGallery.d.ts

@@ -7,6 +7,19 @@ export type AudioGalleryPluginOptions = {
 	data?: Array<SunEditor.Module.Browser.File>;
 	/**
 	 * - Server request URL
+	 * - The server must return:
+	 * ```js
+	 * {
+	 * "result": [
+	 * {
+	 * "src": "https://example.com/audio.mp3",
+	 * "name": "audio.mp3",
+	 * "thumbnail": "https://example.com/audio_icon.png",
+	 * "tag": ["music"]
+	 * }
+	 * ]
+	 * }
+	 * ```
 	 */
 	url?: string;
 	/**
@@ -24,6 +37,19 @@ export type AudioGalleryPluginOptions = {
  * @typedef {Object} AudioGalleryPluginOptions
  * @property {Array<SunEditor.Module.Browser.File>} [data] - Direct data without server calls
  * @property {string} [url] - Server request URL
+ * - The server must return:
+ * ```js
+ * {
+ *   "result": [
+ *     {
+ *       "src": "https://example.com/audio.mp3",
+ *       "name": "audio.mp3",
+ *       "thumbnail": "https://example.com/audio_icon.png",
+ *       "tag": ["music"]
+ *     }
+ *   ]
+ * }
+ * ```
  * @property {Object<string, string>} [headers] - Server request headers
  * @property {string|((item: SunEditor.Module.Browser.File) => string)} [thumbnail] - Default thumbnail
  */

package/types/plugins/browser/fileBrowser.d.ts

@@ -11,6 +11,26 @@ export type FileBrowserPluginOptions = {
 		| Array<any>;
 	/**
 	 * - Server request URL
+	 * - The server must return a nested folder structure.
+	 * - `_data`: array (inline) or string URL (lazy-loaded on folder click).
+	 * - `"default": true` sets the initially selected folder.
+	 * ```js
+	 * {
+	 * "result": {
+	 * "root": {
+	 * "name": "Root",
+	 * "default": true,
+	 * "_data": [
+	 * { "src": "https://example.com/file1.pdf", "name": "file1.pdf" }
+	 * ],
+	 * "documents": {
+	 * "name": "Documents",
+	 * "_data": "https://api.example.com/files/documents"
+	 * }
+	 * }
+	 * }
+	 * }
+	 * ```
 	 */
 	url?: string;
 	/**
@@ -23,6 +43,10 @@ export type FileBrowserPluginOptions = {
 	 * - Default thumbnail URL or a function that returns a thumbnail URL per item.
 	 */
 	thumbnail?: string | ((item: SunEditor.Module.Browser.File) => string);
+	/**
+	 * - Initial folder expand depth. `1` expands the first level, `Infinity` expands all. Default: `1`.
+	 */
+	expand?: number;
 	/**
 	 * - Additional tag names
 	 * ```js
@@ -35,8 +59,29 @@ export type FileBrowserPluginOptions = {
  * @typedef {Object} FileBrowserPluginOptions
  * @property {Object<string, *>|Array<*>} [data] - Direct data without server calls (bypasses URL fetch).
  * @property {string} [url] - Server request URL
+ * - The server must return a nested folder structure.
+ * - `_data`: array (inline) or string URL (lazy-loaded on folder click).
+ * - `"default": true` sets the initially selected folder.
+ * ```js
+ * {
+ *   "result": {
+ *     "root": {
+ *       "name": "Root",
+ *       "default": true,
+ *       "_data": [
+ *         { "src": "https://example.com/file1.pdf", "name": "file1.pdf" }
+ *       ],
+ *       "documents": {
+ *         "name": "Documents",
+ *         "_data": "https://api.example.com/files/documents"
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
  * @property {Object<string, string>} [headers] - Server request headers
  * @property {string|((item: SunEditor.Module.Browser.File) => string)} [thumbnail] - Default thumbnail URL or a function that returns a thumbnail URL per item.
+ * @property {number} [expand=1] - Initial folder expand depth. `1` expands the first level, `Infinity` expands all. Default: `1`.
  * @property {Array<string>} [props] - Additional tag names
  * ```js
  * { url: '/api/files', headers: { Authorization: 'Bearer token' }, thumbnail: (item) => item.thumbUrl }

package/types/plugins/browser/fileGallery.d.ts

@@ -7,6 +7,20 @@ export type FileGalleryPluginOptions = {
 	data?: Array<SunEditor.Module.Browser.File>;
 	/**
 	 * - Server request URL
+	 * - The server must return:
+	 * ```js
+	 * {
+	 * "result": [
+	 * {
+	 * "src": "https://example.com/doc.pdf",
+	 * "name": "doc.pdf",
+	 * "thumbnail": "https://example.com/pdf_icon.png",
+	 * "type": "file", // video, image ..[plugin name]
+	 * "tag": ["document"]
+	 * }
+	 * ]
+	 * }
+	 * ```
 	 */
 	url?: string;
 	/**
@@ -24,6 +38,20 @@ export type FileGalleryPluginOptions = {
  * @typedef {Object} FileGalleryPluginOptions
  * @property {Array<SunEditor.Module.Browser.File>} [data] - Direct data without server calls
  * @property {string} [url] - Server request URL
+ * - The server must return:
+ * ```js
+ * {
+ *   "result": [
+ *     {
+ *       "src": "https://example.com/doc.pdf",
+ *       "name": "doc.pdf",
+ *       "thumbnail": "https://example.com/pdf_icon.png",
+ *       "type": "file", // video, image ..[plugin name]
+ *       "tag": ["document"]
+ *     }
+ *   ]
+ * }
+ * ```
  * @property {Object<string, string>} [headers] - Server request headers
  * @property {string|((item: SunEditor.Module.Browser.File) => string)} [thumbnail] - Default thumbnail
  */

package/types/plugins/browser/imageGallery.d.ts

@@ -7,6 +7,20 @@ export type ImageGalleryPluginOptions = {
 	data?: Array<any>;
 	/**
 	 * - Server request URL
+	 * - The server must return:
+	 * ```js
+	 * {
+	 * "result": [
+	 * {
+	 * "src": "https://example.com/img.jpg",
+	 * "name": "img.jpg",
+	 * "thumbnail": "https://example.com/img_thumb.jpg",
+	 * "alt": "description",
+	 * "tag": ["nature"]
+	 * }
+	 * ]
+	 * }
+	 * ```
 	 */
 	url?: string;
 	/**
@@ -20,6 +34,20 @@ export type ImageGalleryPluginOptions = {
  * @typedef ImageGalleryPluginOptions
  * @property {Array<*>} [data] - Direct data without server calls
  * @property {string} [url] - Server request URL
+ * - The server must return:
+ * ```js
+ * {
+ *   "result": [
+ *     {
+ *       "src": "https://example.com/img.jpg",
+ *       "name": "img.jpg",
+ *       "thumbnail": "https://example.com/img_thumb.jpg",
+ *       "alt": "description",
+ *       "tag": ["nature"]
+ *     }
+ *   ]
+ * }
+ * ```
  * @property {Object<string, string>} [headers] - Server request headers
  */
 /**

package/types/plugins/browser/videoGallery.d.ts

@@ -7,6 +7,20 @@ export type VideoGalleryPluginOptions = {
 	data?: Array<SunEditor.Module.Browser.File>;
 	/**
 	 * - Server request URL
+	 * - The server must return:
+	 * ```js
+	 * {
+	 * "result": [
+	 * {
+	 * "src": "https://example.com/video.mp4",
+	 * "name": "video.mp4",
+	 * "thumbnail": "https://example.com/video_thumb.jpg",
+	 * "frame": "video",
+	 * "tag": ["tutorial"]
+	 * }
+	 * ]
+	 * }
+	 * ```
 	 */
 	url?: string;
 	/**
@@ -24,6 +38,20 @@ export type VideoGalleryPluginOptions = {
  * @typedef {Object} VideoGalleryPluginOptions
  * @property {Array<SunEditor.Module.Browser.File>} [data] - Direct data without server calls
  * @property {string} [url] - Server request URL
+ * - The server must return:
+ * ```js
+ * {
+ *   "result": [
+ *     {
+ *       "src": "https://example.com/video.mp4",
+ *       "name": "video.mp4",
+ *       "thumbnail": "https://example.com/video_thumb.jpg",
+ *       "frame": "video",
+ *       "tag": ["tutorial"]
+ *     }
+ *   ]
+ * }
+ * ```
  * @property {Object<string, string>} [headers] - Server request headers
  * @property {string|((item: SunEditor.Module.Browser.File) => string)} [thumbnail] - Default thumbnail
  */

package/types/plugins/command/fileUpload.d.ts

@@ -3,6 +3,18 @@ export default FileUpload;
 export type FileUploadPluginOptions = {
 	/**
 	 * - Server request URL for file upload
+	 * - The server must return:
+	 * ```js
+	 * {
+	 * "result": [
+	 * {
+	 * "url": "https://example.com/file.pdf",
+	 * "name": "file.pdf",
+	 * "size": 1048576
+	 * }
+	 * ]
+	 * }
+	 * ```
 	 */
 	uploadUrl: string;
 	/**
@@ -51,6 +63,18 @@ export type FileUploadPluginOptions = {
 /**
  * @typedef FileUploadPluginOptions
  * @property {string} uploadUrl - Server request URL for file upload
+ * - The server must return:
+ * ```js
+ * {
+ *   "result": [
+ *     {
+ *       "url": "https://example.com/file.pdf",
+ *       "name": "file.pdf",
+ *       "size": 1048576
+ *     }
+ *   ]
+ * }
+ * ```
  * @property {Object<string, string>} [uploadHeaders] - Server request headers
  * @property {number} [uploadSizeLimit] - Total upload size limit in bytes
  * @property {number} [uploadSingleSizeLimit] - Single file size limit in bytes

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

@@ -0,0 +1,177 @@
+import type {} from '../../typedef';
+export default Autocomplete;
+export type AutocompleteTriggerConfig = {
+	/**
+	 * - Static data array. Each item must have a `key` field. Mutually exclusive with `apiUrl`.
+	 * ```js
+	 * // data
+	 * [{ key: 'john', name: 'John Doe', url: '/users/john' }]
+	 * ```
+	 */
+	data?: Array<{
+		key: string;
+		[x: string]: any;
+	}>;
+	/**
+	 * - API endpoint URL. Supports `{key}` and `{limitSize}` placeholders. Mutually exclusive with `data`.
+	 */
+	apiUrl?: string;
+	/**
+	 * - HTTP headers for the API request.
+	 */
+	apiHeaders?: {
+		[x: string]: string;
+	};
+	/**
+	 * - Transforms parsed JSON response into an array of data items.
+	 */
+	transformResponse?: (
+		arg0: any,
+		arg1: XMLHttpRequest,
+	) => Array<{
+		key: string;
+	}>;
+	/**
+	 * - Override global `limitSize` for this trigger.
+	 */
+	limitSize?: number;
+	/**
+	 * - Override global `searchStartLength` for this trigger.
+	 */
+	searchStartLength?: number;
+	/**
+	 * - Override global `useCachingData` for this trigger.
+	 */
+	useCachingData?: boolean;
+	/**
+	 * - Override global `useCachingFieldData` for this trigger.
+	 */
+	useCachingFieldData?: boolean;
+	/**
+	 * - Custom dropdown item renderer. Receives `(item, triggerText)`, returns HTML string.
+	 */
+	renderItem?: (
+		arg0: {
+			key: string;
+			[x: string]: any;
+		},
+		arg1: string,
+	) => string;
+	/**
+	 * - Custom selection handler. Returns:
+	 * - `string`: inserted as text node
+	 * - `Element`: inserted as-is
+	 * - `{tag, attrs, text}`: creates element via `dom.utils.createElement`
+	 */
+	onSelect?: (
+		arg0: {
+			key: string;
+			[x: string]: any;
+		},
+		arg1: string,
+	) =>
+		| string
+		| Element
+		| {
+				tag: string;
+				attrs?: any;
+				text?: string;
+		  };
+};
+export type AutocompletePluginOptions = {
+	/**
+	 * - Debounce delay in ms before processing input.
+	 */
+	delayTime?: number;
+	/**
+	 * - Maximum number of items to display in the dropdown.
+	 */
+	limitSize?: number;
+	/**
+	 * - Minimum input length before triggering search.
+	 */
+	searchStartLength?: number;
+	/**
+	 * - Whether to cache query responses per trigger.
+	 */
+	useCachingData?: boolean;
+	/**
+	 * - Whether to cache selected items for priority display.
+	 */
+	useCachingFieldData?: boolean;
+	/**
+	 * - Per-trigger configurations keyed by trigger character.
+	 * ```js
+	 * // triggers
+	 * {
+	 * '@': { data: [...], renderItem: (item) => `...` },
+	 * '#': { apiUrl: '/api/tags?q={key}' }
+	 * }
+	 * ```
+	 */
+	triggers: {
+		[x: string]: AutocompleteTriggerConfig;
+	};
+};
+/**
+ * @typedef {Object} AutocompleteTriggerConfig
+ * @property {Array<{key: string, [x: string]: any}>} [data] - Static data array. Each item must have a `key` field. Mutually exclusive with `apiUrl`.
+ * ```js
+ * // data
+ * [{ key: 'john', name: 'John Doe', url: '/users/john' }]
+ * ```
+ * @property {string} [apiUrl] - API endpoint URL. Supports `{key}` and `{limitSize}` placeholders. Mutually exclusive with `data`.
+ * @property {Object<string, string>} [apiHeaders] - HTTP headers for the API request.
+ * @property {function(Object, XMLHttpRequest): Array<{key: string}>} [transformResponse] - Transforms parsed JSON response into an array of data items.
+ * @property {number} [limitSize] - Override global `limitSize` for this trigger.
+ * @property {number} [searchStartLength] - Override global `searchStartLength` for this trigger.
+ * @property {boolean} [useCachingData] - Override global `useCachingData` for this trigger.
+ * @property {boolean} [useCachingFieldData] - Override global `useCachingFieldData` for this trigger.
+ * @property {function({key: string, [x: string]: any}, string): string} [renderItem] - Custom dropdown item renderer. Receives `(item, triggerText)`, returns HTML string.
+ * @property {function({key: string, [x: string]: any}, string): (string|Element|{tag: string, attrs?: Object, text?: string})} [onSelect] - Custom selection handler. Returns:
+ *   - `string`: inserted as text node
+ *   - `Element`: inserted as-is
+ *   - `{tag, attrs, text}`: creates element via `dom.utils.createElement`
+ */
+/**
+ * @typedef {Object} AutocompletePluginOptions
+ * @property {number} [delayTime=120] - Debounce delay in ms before processing input.
+ * @property {number} [limitSize=5] - Maximum number of items to display in the dropdown.
+ * @property {number} [searchStartLength=0] - Minimum input length before triggering search.
+ * @property {boolean} [useCachingData=true] - Whether to cache query responses per trigger.
+ * @property {boolean} [useCachingFieldData=true] - Whether to cache selected items for priority display.
+ * @property {Object<string, AutocompleteTriggerConfig>} triggers - Per-trigger configurations keyed by trigger character.
+ * ```js
+ * // triggers
+ * {
+ *   '@': { data: [...], renderItem: (item) => `...` },
+ *   '#': { apiUrl: '/api/tags?q={key}' }
+ * }
+ * ```
+ */
+/**
+ * @class
+ * @description Autocomplete Plugin
+ * - A generic autocomplete plugin supporting multiple trigger characters.
+ * - Each trigger can have its own data source, rendering, and selection behavior.
+ * - Supports static data arrays and API-based data fetching.
+ * - Uses per-trigger caching for optimized performance.
+ */
+declare class Autocomplete extends PluginField {
+	/**
+	 * @constructor
+	 * @param {SunEditor.Kernel} kernel - The Kernel instance
+	 * @param {AutocompletePluginOptions} pluginOptions
+	 */
+	constructor(kernel: SunEditor.Kernel, pluginOptions: AutocompletePluginOptions);
+	title: any;
+	triggerContexts: Map<any, any>;
+	sortedTriggers: any[];
+	selectMenu: SelectMenu;
+	controller: Controller;
+	onInput(params: SunEditor.HookParams.InputWithData): Promise<void>;
+	#private;
+}
+import { PluginField } from '../../interfaces';
+import { Controller } from '../../modules/contract';
+import { SelectMenu } from '../../modules/ui';

package/types/plugins/index.d.ts

@@ -6,7 +6,7 @@ declare namespace _default {
 	export { fileUpload };
 	export { list_bulleted };
 	export { list_numbered };
-	export { mention };
+	export { autocomplete };
 	export { align };
 	export { font };
 	export { fontColor };
@@ -61,7 +61,7 @@ import paragraphStyle from './dropdown/paragraphStyle';
 import table from './dropdown/table';
 import template from './dropdown/template';
 import textStyle from './dropdown/textStyle';
-import mention from './field/mention';
+import autocomplete from './field/autocomplete';
 import fontSize from './input/fontSize';
 import pageNavigator from './input/pageNavigator';
 import audio from './modal/audio';
@@ -77,6 +77,7 @@ export {
 	anchor,
 	audio,
 	audioGallery,
+	autocomplete,
 	backgroundColor,
 	blockquote,
 	blockStyle,
@@ -100,7 +101,6 @@ export {
 	list_bulleted,
 	list_numbered,
 	math,
-	mention,
 	pageNavigator,
 	paragraphStyle,
 	table,

package/types/plugins/modal/audio.d.ts

@@ -20,6 +20,18 @@ export type AudioPluginOptions = {
 	createUrlInput?: boolean;
 	/**
 	 * - The URL to which files will be uploaded.
+	 * - The server must return:
+	 * ```js
+	 * {
+	 * "result": [
+	 * {
+	 * "url": "https://example.com/audio.mp3",
+	 * "name": "audio.mp3",
+	 * "size": 3145728
+	 * }
+	 * ]
+	 * }
+	 * ```
 	 */
 	uploadUrl?: string;
 	/**
@@ -71,6 +83,18 @@ export type AudioPluginOptions = {
  * @property {boolean} [createUrlInput] - Whether to create a URL input element.
  * - Defaults to `true`. Always `true` when `createFileInput` is `false`.
  * @property {string} [uploadUrl] - The URL to which files will be uploaded.
+ * - The server must return:
+ * ```js
+ * {
+ *   "result": [
+ *     {
+ *       "url": "https://example.com/audio.mp3",
+ *       "name": "audio.mp3",
+ *       "size": 3145728
+ *     }
+ *   ]
+ * }
+ * ```
  * @property {Object<string, string>} [uploadHeaders] - Headers to include in the file upload request.
  * @property {number} [uploadSizeLimit] - The total upload size limit in bytes.
  * @property {number} [uploadSingleSizeLimit] - The single file size limit in bytes.

package/types/plugins/modal/embed.d.ts

@@ -23,6 +23,18 @@ export type EmbedPluginOptions = {
 	percentageOnlySize?: boolean;
 	/**
 	 * - The URL for file uploads.
+	 * - The server must return:
+	 * ```js
+	 * {
+	 * "result": [
+	 * {
+	 * "url": "https://example.com/embed.html",
+	 * "name": "embed.html",
+	 * "size": 2048
+	 * }
+	 * ]
+	 * }
+	 * ```
 	 */
 	uploadUrl?: string;
 	/**
@@ -110,6 +122,18 @@ export type EmbedPluginOptions = {
  * @property {string} [defaultHeight] - The default height of the embed element (numeric value or with unit).
  * @property {boolean} [percentageOnlySize=false] - Whether to allow only percentage-based sizing.
  * @property {string} [uploadUrl] - The URL for file uploads.
+ * - The server must return:
+ * ```js
+ * {
+ *   "result": [
+ *     {
+ *       "url": "https://example.com/embed.html",
+ *       "name": "embed.html",
+ *       "size": 2048
+ *     }
+ *   ]
+ * }
+ * ```
  * @property {Object<string, string>} [uploadHeaders] - Headers to include in file upload requests.
  * @property {number} [uploadSizeLimit] - The total file upload size limit in bytes.
  * @property {number} [uploadSingleSizeLimit] - The single file upload size limit in bytes.

package/types/plugins/modal/image/index.d.ts

@@ -32,6 +32,18 @@ export type ImagePluginOptions = {
 	createUrlInput?: boolean;
 	/**
 	 * - The URL endpoint for image file uploads.
+	 * - The server must return:
+	 * ```js
+	 * {
+	 * "result": [
+	 * {
+	 * "url": "https://example.com/image.jpg",
+	 * "name": "image.jpg",
+	 * "size": 123456
+	 * }
+	 * ]
+	 * }
+	 * ```
 	 */
 	uploadUrl?: string;
 	/**
@@ -116,6 +128,18 @@ export type ImageState = {
  * @property {boolean} [createUrlInput] - Whether to create a URL input element for image insertion.
  * - Defaults to `true`. Always `true` when `createFileInput` is `false`.
  * @property {string} [uploadUrl] - The URL endpoint for image file uploads.
+ * - The server must return:
+ * ```js
+ * {
+ *   "result": [
+ *     {
+ *       "url": "https://example.com/image.jpg",
+ *       "name": "image.jpg",
+ *       "size": 123456
+ *     }
+ *   ]
+ * }
+ * ```
  * @property {Object<string, string>} [uploadHeaders] - Additional headers to include in the file upload request.
  * ```js
  * { uploadUrl: '/api/upload/image', uploadHeaders: { Authorization: 'Bearer token' } }