suneditor 3.0.0-alpha.2 → 3.0.0-alpha.20

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

@@ -0,0 +1,102 @@
+export default Mention;
+/**
+ * @class
+ * @description Mention Plugin
+ * - A plugin that provides a mention feature using `@` or a custom trigger character.
+ * - Displays a mention list when the trigger character is typed.
+ * - Supports fetching mention data from an API or a predefined data array.
+ * - Uses caching for optimized performance.
+ */
+declare class Mention extends EditorInjector {
+	static key: string;
+	static type: string;
+	static className: string;
+	/**
+	 * @constructor
+	 * @param {__se__EditorCore} editor - The root editor instance
+	 * @param {Object} pluginOptions
+	 * @param {string=} [pluginOptions.triggerText="@"] The character that triggers the mention list. Default is '@'.
+	 * @param {number=} [pluginOptions.limitSize=5] The number of items to display in the mention list. Default is 5.
+	 * @param {number=} [pluginOptions.searchStartLength=0] The number of characters to start searching for the mention list. Default is 0.
+	 * @param {number=} [pluginOptions.delayTime=200] The time to wait before displaying the mention list. Default is 200ms.
+	 * @param {Array<{key: string, name: string, url: string}>=} pluginOptions.data Use data without using API.
+	 * @param {string=} pluginOptions.apiUrl The URL to call the mention list. Default is ''.
+	 * @param {Object<string, string>=} pluginOptions.apiHeaders The headers to send with the API call. Default is {}.
+	 * @param {boolean=} [pluginOptions.useCachingData=true] Whether to cache the mention list data. Default is true.
+	 * @param {boolean=} [pluginOptions.useCachingFieldData=true] Whether to cache the mention list data in the field. Default is true.
+	 */
+	constructor(
+		editor: __se__EditorCore,
+		pluginOptions: {
+			triggerText?: string | undefined;
+			limitSize?: number | undefined;
+			searchStartLength?: number | undefined;
+			delayTime?: number | undefined;
+			data?:
+				| Array<{
+						key: string;
+						name: string;
+						url: string;
+				  }>
+				| undefined;
+			apiUrl?: string | undefined;
+			apiHeaders?:
+				| {
+						[x: string]: string;
+				  }
+				| undefined;
+			useCachingData?: boolean | undefined;
+			useCachingFieldData?: boolean | undefined;
+		}
+	);
+	title: any;
+	icon: string;
+	triggerText: string;
+	limitSize: number;
+	searchStartLength: number;
+	delayTime: number;
+	directData: {
+		key: string;
+		name: string;
+		url: string;
+	}[];
+	apiUrl: string;
+	_delay: number;
+	_lastAtPos: number;
+	_anchorOffset: number;
+	_anchorNode: Node;
+	apiManager: ApiManager;
+	cachingData: Map<any, any>;
+	cachingFieldData: Map<string, any[]>;
+	selectMenu: SelectMenu;
+	controller: Controller;
+	/**
+	 * @editorMethod Editor.EventManager
+	 * @description Executes the event function of "input".
+	 * @returns {Promise<boolean>}
+	 */
+	onInput(): Promise<boolean>;
+	/**
+	 * @private
+	 * @description Generates the mention list based on user input.
+	 * - Fetches data from cache, direct data, or an API.
+	 * - Creates and opens the mention dropdown.
+	 * - Caches the fetched data for future use.
+	 * @param {string} value - The mention query text.
+	 * @param {Node} targetNode - The node where the mention is triggered.
+	 * @returns {Promise<boolean>} - Returns `true` if the mention list is displayed, `false` otherwise.
+	 */
+	private _createMentionList;
+	/**
+	 * @private
+	 * @description Constructs the API request URL with the mention query.
+	 * @param {string} key - The mention query text.
+	 * @returns {string} - The formatted API request URL.
+	 */
+	private _createUrl;
+	#private;
+}
+import EditorInjector from '../../editorInjector';
+import { ApiManager } from '../../modules';
+import { SelectMenu } from '../../modules';
+import { Controller } from '../../modules';

package/types/plugins/index.d.ts

@@ -0,0 +1,107 @@
+declare namespace _default {
+	export { blockquote };
+	export { exportPDF };
+	export { fileUpload };
+	export { list_bulleted };
+	export { list_numbered };
+	export { mention };
+	export { align };
+	export { font };
+	export { fontColor };
+	export { backgroundColor };
+	export { list };
+	export { table };
+	export { formatBlock };
+	export { hr };
+	export { layout };
+	export { lineHeight };
+	export { template };
+	export { paragraphStyle };
+	export { textStyle };
+	export { link };
+	export { image };
+	export { video };
+	export { audio };
+	export { embed };
+	export { math };
+	export { drawing };
+	export { imageGallery };
+	export { videoGallery };
+	export { audioGallery };
+	export { fileGallery };
+	export { fileBrowser };
+	export { fontSize };
+	export { pageNavigator };
+	export { anchor };
+}
+export default _default;
+import blockquote from './command/blockquote';
+import exportPDF from './command/exportPDF';
+import fileUpload from './command/fileUpload';
+import list_bulleted from './command/list_bulleted';
+import list_numbered from './command/list_numbered';
+import mention from './field/mention';
+import align from './dropdown/align';
+import font from './dropdown/font';
+import fontColor from './dropdown/fontColor';
+import backgroundColor from './dropdown/backgroundColor';
+import list from './dropdown/list';
+import table from './dropdown/table';
+import formatBlock from './dropdown/formatBlock';
+import hr from './dropdown/hr';
+import layout from './dropdown/layout';
+import lineHeight from './dropdown/lineHeight';
+import template from './dropdown/template';
+import paragraphStyle from './dropdown/paragraphStyle';
+import textStyle from './dropdown/textStyle';
+import link from './modal/link';
+import image from './modal/image';
+import video from './modal/video';
+import audio from './modal/audio';
+import embed from './modal/embed';
+import math from './modal/math';
+import drawing from './modal/drawing';
+import imageGallery from './browser/imageGallery';
+import videoGallery from './browser/videoGallery';
+import audioGallery from './browser/audioGallery';
+import fileGallery from './browser/fileGallery';
+import fileBrowser from './browser/fileBrowser';
+import fontSize from './input/fontSize';
+import pageNavigator from './input/pageNavigator';
+import anchor from './popup/anchor';
+export {
+	blockquote,
+	exportPDF,
+	fileUpload,
+	list_bulleted,
+	list_numbered,
+	mention,
+	align,
+	font,
+	fontColor,
+	backgroundColor,
+	list,
+	table,
+	formatBlock,
+	hr,
+	layout,
+	lineHeight,
+	template,
+	paragraphStyle,
+	textStyle,
+	link,
+	image,
+	video,
+	audio,
+	embed,
+	math,
+	drawing,
+	imageGallery,
+	videoGallery,
+	audioGallery,
+	fileGallery,
+	fileBrowser,
+	fontSize,
+	pageNavigator,
+	anchor
+};

package/types/plugins/input/fontSize.d.ts

@@ -0,0 +1,170 @@
+export default FontSize;
+/**
+ * @class
+ * @description FontSize Plugin
+ * - This plugin enables users to modify the font size of selected text within the editor.
+ * - It supports various measurement units (e.g., 'px', 'pt', 'em', 'rem', 'vw', 'vh', '%') and
+ * - provides multiple interfaces: dropdown menus, direct input, and optional increment/decrement buttons.
+ */
+declare class FontSize extends EditorInjector {
+	static key: string;
+	static type: string;
+	static className: string;
+	/**
+	 * @constructor
+	 * @param {__se__EditorCore} editor - The root editor instance
+	 * @param {Object} pluginOptions - Configuration options for the FontSize plugin.
+	 * @param {string=} [pluginOptions.sizeUnit='px'] - The unit for the font size.
+	 * - Accepted values include: 'px', 'pt', 'em', 'rem', 'vw', 'vh', '%' or 'text'.
+	 * - If 'text' is used, a text-based font size list is applied.
+	 * @param {boolean=} [pluginOptions.showDefaultSizeLabel=true] - Determines whether the default size label is displayed in the dropdown menu.
+	 * @param {boolean=} [pluginOptions.showIncDecControls=false] - When true, displays increase and decrease buttons for font size adjustments.
+	 * @param {boolean=} [pluginOptions.disableInput=true] - When true, disables the direct font size input box.
+	 * @param {Object<string, {default: number, inc: number, min: number, max: number, list: Array<number>}>} [pluginOptions.unitMap={}] - Optional object to override or extend the default unit mapping for font sizes.
+	 */
+	constructor(
+		editor: __se__EditorCore,
+		pluginOptions: {
+			sizeUnit?: string | undefined;
+			showDefaultSizeLabel?: boolean | undefined;
+			showIncDecControls?: boolean | undefined;
+			disableInput?: boolean | undefined;
+			unitMap?: {
+				[x: string]: {
+					default: number;
+					inc: number;
+					min: number;
+					max: number;
+					list: Array<number>;
+				};
+			};
+		}
+	);
+	unitMap: {
+		text: {
+			default: string;
+			list: {
+				title: string;
+				size: string;
+			}[];
+		};
+		px: {
+			default: number;
+			inc: number;
+			min: number;
+			max: number;
+			list: number[];
+		};
+		pt: {
+			default: number;
+			inc: number;
+			min: number;
+			max: number;
+			list: number[];
+		};
+		em: {
+			default: number;
+			inc: number;
+			min: number;
+			max: number;
+			list: number[];
+		};
+		rem: {
+			default: number;
+			inc: number;
+			min: number;
+			max: number;
+			list: number[];
+		};
+		vw: {
+			inc: number;
+			min: number;
+			max: number;
+			list: number[];
+		};
+		vh: {
+			default: number;
+			inc: number;
+			min: number;
+			max: number;
+			list: number[];
+		};
+		'%': {
+			default: number;
+			inc: number;
+			min: number;
+			max: number;
+			list: number[];
+		};
+	};
+	sizeUnit: any;
+	title: any;
+	inner: string | boolean;
+	beforeItem: HTMLElement;
+	afterItem: HTMLElement;
+	replaceButton: HTMLElement;
+	currentSize: string;
+	sizeList: NodeListOf<Element>;
+	hasInputFocus: boolean;
+	isInputActive: boolean;
+	_disableInput: boolean;
+	/**
+	 * @editorMethod Editor.EventManager
+	 * @description Executes the method that is called whenever the cursor position changes.
+	 * @param {?HTMLElement=} element - Node element where the cursor is currently located
+	 * @param {?HTMLElement=} target - The plugin's toolbar button element
+	 * @returns {boolean} - Whether the plugin is active
+	 */
+	active(element?: (HTMLElement | null) | undefined, target?: (HTMLElement | null) | undefined): boolean;
+	/**
+	 * @editorMethod Editor.Toolbar
+	 * @description Executes the event function of toolbar's input tag - "keydown".
+	 * @param {Object} params
+	 * @param {HTMLElement} params.target Input element
+	 * @param {KeyboardEvent} params.event Event object
+	 */
+	onInputKeyDown({ target, event }: { target: HTMLElement; event: KeyboardEvent }): void;
+	/**
+	 * @editorMethod Editor.Toolbar
+	 * @description Executes the event function of toolbar's input tag - "change".
+	 * @param {__se__PluginToolbarInputChangeEventInfo} params
+	 */
+	onInputChange({ target, value: changeValue, event }: __se__PluginToolbarInputChangeEventInfo): void;
+	/**
+	 * @editorMethod Modules.Dropdown
+	 * @description Executes the method that is called when a plugin's dropdown menu is opened.
+	 * @param {HTMLElement} target Line element at the current cursor position
+	 */
+	on(target: HTMLElement): void;
+	/**
+	 * @editorMethod Editor.core
+	 * @description Executes the main execution method of the plugin.
+	 * - Called when an item in the "dropdown" menu is clicked.
+	 * @param {HTMLElement} target - The plugin's toolbar button element
+	 */
+	action(target: HTMLElement): void;
+	/**
+	 * @private
+	 * @description Retrieves the default font size of the editor.
+	 * @returns {string} - The computed font size from the editor.
+	 */
+	private _getDefaultSize;
+	/**
+	 * @private
+	 * @description Extracts the font size and unit from the given element or input value.
+	 * @param {string|Element} target - The target input or element.
+	 * @returns {{ unit: string, value: number|string }} - An object containing:
+	 * - `unit` (string): The detected font size unit.
+	 * - `value` (number|string): The numeric font size value or text-based size.
+	 */
+	private _getSize;
+	/**
+	 * @private
+	 * @description Sets the font size in the toolbar input field or button label.
+	 * @param {HTMLElement} target - The target element in the toolbar.
+	 * @param {string|number} value - The font size value.
+	 * @returns {string|number} - The applied font size.
+	 */
+	private _setSize;
+}
+import EditorInjector from '../../editorInjector';

package/types/plugins/input/pageNavigator.d.ts

@@ -0,0 +1,28 @@
+export default PageNavigator;
+/**
+ * @class
+ * @description PageNavigator Plugin
+ * - This plugin provides functionality for navigating between pages within the editor's document.
+ * - It features an input field for entering the desired page number and a display element showing
+ * - the total number of pages. When the user changes the value in the input field, the plugin triggers
+ * - a page navigation event through the editor's document context.
+ */
+declare class PageNavigator extends EditorInjector {
+	static key: string;
+	static type: string;
+	static className: string;
+	title: any;
+	inner: HTMLInputElement;
+	afterItem: HTMLElement;
+	pageNum: number;
+	totalPages: number;
+	/**
+	 * @editorMethod Editor.documentType
+	 * @description Updates the displayed page number and total pages in the navigator.
+	 * @param {number} pageNum - The current page number to display.
+	 * @param {number} totalPages - The total number of pages in the document.
+	 */
+	display(pageNum: number, totalPages: number): void;
+	#private;
+}
+import EditorInjector from '../../editorInjector';

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

@@ -0,0 +1,269 @@
+export default Audio_;
+export type AudioInfo = import('../../core/base/events').AudioInfo;
+export type AudioPluginOptions = {
+	/**
+	 * - The default width of the audio tag (e.g., "300px").
+	 */
+	defaultWidth?: string;
+	/**
+	 * - The default height of the audio tag (e.g., "150px").
+	 */
+	defaultHeight?: string;
+	/**
+	 * - Whether to create a file input element.
+	 */
+	createFileInput?: boolean;
+	/**
+	 * - Whether to create a URL input element (default is true if file input is not created).
+	 */
+	createUrlInput?: boolean;
+	/**
+	 * - The URL to which files will be uploaded.
+	 */
+	uploadUrl?: string;
+	/**
+	 * - Headers to include in the file upload request.
+	 */
+	uploadHeaders?: {
+		[x: string]: string;
+	};
+	/**
+	 * - The total upload size limit in bytes.
+	 */
+	uploadSizeLimit?: number;
+	/**
+	 * - The single file size limit in bytes.
+	 */
+	uploadSingleSizeLimit?: number;
+	/**
+	 * - Whether to allow multiple file uploads.
+	 */
+	allowMultiple?: boolean;
+	/**
+	 * - Accepted file formats (default is "audio/*").
+	 */
+	acceptedFormats?: string;
+	/**
+	 * - Additional attributes to set on the audio tag.
+	 */
+	audioTagAttributes?: {
+		[x: string]: string;
+	};
+};
+/**
+ * @typedef {import('../../core/base/events').AudioInfo} AudioInfo
+ */
+/**
+ * @typedef {Object} AudioPluginOptions
+ * @property {string} [defaultWidth="300px"] - The default width of the audio tag (e.g., "300px").
+ * @property {string} [defaultHeight="150px"] - The default height of the audio tag (e.g., "150px").
+ * @property {boolean} [createFileInput] - Whether to create a file input element.
+ * @property {boolean} [createUrlInput] - Whether to create a URL input element (default is true if file input is not created).
+ * @property {string} [uploadUrl] - The URL to which files will be uploaded.
+ * @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.
+ * @property {boolean} [allowMultiple] - Whether to allow multiple file uploads.
+ * @property {string} [acceptedFormats="audio/*"] - Accepted file formats (default is "audio/*").
+ * @property {Object<string, string>} [audioTagAttributes] - Additional attributes to set on the audio tag.
+ */
+/**
+ * @class
+ * @description Audio modal plugin.
+ */
+declare class Audio_ extends EditorInjector {
+	static key: string;
+	static type: string;
+	static className: string;
+	/**
+	 * @this {Audio_}
+	 * @param {HTMLElement} node - The node to check.
+	 * @returns {HTMLElement|null} Returns a node if the node is a valid component.
+	 */
+	static component(this: Audio_, node: HTMLElement): HTMLElement | null;
+	/**
+	 * @constructor
+	 * @param {__se__EditorCore} editor - The root editor instance
+	 * @param {AudioPluginOptions} pluginOptions
+	 */
+	constructor(editor: __se__EditorCore, pluginOptions: AudioPluginOptions);
+	title: any;
+	icon: string;
+	pluginOptions: {
+		defaultWidth: string;
+		defaultHeight: string;
+		createFileInput: boolean;
+		createUrlInput: boolean;
+		uploadUrl: string;
+		uploadHeaders: {
+			[x: string]: string;
+		};
+		uploadSizeLimit: number;
+		uploadSingleSizeLimit: number;
+		allowMultiple: boolean;
+		acceptedFormats: string;
+		audioTagAttributes: {
+			[x: string]: string;
+		};
+	};
+	modal: Modal;
+	controller: Controller;
+	fileManager: FileManager;
+	figure: Figure;
+	/** @type {HTMLElement} */
+	fileModalWrapper: HTMLElement;
+	/** @type {HTMLInputElement} */
+	audioInputFile: HTMLInputElement;
+	/** @type {HTMLInputElement} */
+	audioUrlFile: HTMLInputElement;
+	/** @type {HTMLElement} */
+	preview: HTMLElement;
+	/** @type {HTMLAudioElement} */
+	_element: HTMLAudioElement;
+	defaultWidth: string;
+	defaultHeight: string;
+	urlValue: string;
+	/**
+	 * @editorMethod Modules.Modal
+	 * @description Executes the method that is called when a "Modal" module's is opened.
+	 */
+	open(): void;
+	/**
+	 * @editorMethod Modules.Modal
+	 * @description Executes the method that is called when a plugin's modal is opened.
+	 * @param {boolean} isUpdate "Indicates whether the modal is for editing an existing component (true) or registering a new one (false)."
+	 */
+	on(isUpdate: boolean): void;
+	/**
+	 * @editorMethod Editor.EventManager
+	 * @description Executes the event function of "paste" or "drop".
+	 * @param {Object} params { frameContext, event, file }
+	 * @param {__se__FrameContext} params.frameContext Frame context
+	 * @param {ClipboardEvent} params.event Event object
+	 * @param {File} params.file File object
+	 * @returns {boolean} - If return false, the file upload will be canceled
+	 */
+	onPastAndDrop({ file }: { frameContext: __se__FrameContext; event: ClipboardEvent; file: File }): boolean;
+	/**
+	 * @editorMethod Modules.Modal
+	 * @description This function is called when a form within a modal window is "submit".
+	 * @returns {Promise<boolean>} Success or failure
+	 */
+	modalAction(): Promise<boolean>;
+	/**
+	 * @editorMethod Modules.Modal
+	 * @description This function is called before the modal window is opened, but before it is closed.
+	 */
+	init(): void;
+	/**
+	 * @editorMethod Modules.Controller
+	 * @description Executes the method that is called when a button is clicked in the "controller".
+	 * @param {HTMLButtonElement} target Target button element
+	 */
+	controllerAction(target: HTMLButtonElement): void;
+	/**
+	 * @editorMethod Editor.core
+	 * @description This method is used to validate and preserve the format of the component within the editor.
+	 * - It ensures that the structure and attributes of the element are maintained and secure.
+	 * - The method checks if the element is already wrapped in a valid container and updates its attributes if necessary.
+	 * - If the element isn't properly contained, a new container is created to retain the format.
+	 * @returns {{query: string, method: (element: HTMLAudioElement) => void}} The format retention object containing the query and method to process the element.
+	 * - query: The selector query to identify the relevant elements (in this case, 'audio').
+	 * - method:The function to execute on the element to validate and preserve its format.
+	 * - The function takes the element as an argument, checks if it is contained correctly, and applies necessary adjustments.
+	 */
+	retainFormat(): {
+		query: string;
+		method: (element: HTMLAudioElement) => void;
+	};
+	/**
+	 * @editorMethod Editor.Component
+	 * @description Executes the method that is called when a component of a plugin is selected.
+	 * @param {HTMLElement} target Target component element
+	 */
+	select(target: HTMLElement): void;
+	/**
+	 * @private
+	 * @description Prepares the component for selection.
+	 * - Ensures that the controller is properly positioned and initialized.
+	 * - Prevents duplicate event handling if the component is already selected.
+	 * @param {HTMLElement} target - The selected element.
+	 */
+	private _ready;
+	/**
+	 * @editorMethod Editor.Component
+	 * @description Method to delete a component of a plugin, called by the "FileManager", "Controller" module.
+	 * @param {HTMLElement=} target Target element, if null current selected element
+	 * @returns {Promise<void>}
+	 */
+	destroy(target?: HTMLElement | undefined): Promise<void>;
+	/**
+	 * @private
+	 * @description Registers uploaded audio files and creates the corresponding audio elements.
+	 * - Iterates through the uploaded files and inserts them into the editor.
+	 * @param {AudioInfo} info - Upload metadata, including `isUpdate` flag and `element`.
+	 * @param {Object<string, *>} response - Server response containing uploaded file details.
+	 */
+	private _register;
+	/**
+	 * @description Create an "audio" component using the provided files.
+	 * @param {FileList|File[]} fileList File object list
+	 * @returns {Promise<boolean>} If return false, the file upload will be canceled
+	 */
+	submitFile(fileList: FileList | File[]): Promise<boolean>;
+	/**
+	 * @description Create an "audio" component using the provided url.
+	 * @param {string} url File url
+	 * @returns {Promise<boolean>}
+	 */
+	submitURL(url: string): Promise<boolean>;
+	/**
+	 * @private
+	 * @description Creates or updates an audio component within the editor.
+	 * - If `isUpdate` is `true`, updates the existing element's `src`.
+	 * - Otherwise, inserts a new audio component with the given file.
+	 * @param {HTMLAudioElement} element - The target audio element.
+	 * @param {string} src - The source URL of the audio file.
+	 * @param {{name: string, size: number}} file - The file metadata (name, size).
+	 * @param {boolean} isUpdate - Whether to update an existing element.
+	 */
+	private _createComp;
+	/**
+	 * @private
+	 * @description Creates a new `<audio>` element with default attributes.
+	 * - Applies width, height, and additional attributes from plugin options.
+	 * @returns {HTMLAudioElement} - The newly created `<audio>` element.
+	 */
+	private _createAudioTag;
+	/**
+	 * @private
+	 * @description Sets attributes on an audio element based on plugin options.
+	 * - Adds the `controls` attribute and applies any custom attributes.
+	 * @param {HTMLElement} element - The `<audio>` element to modify.
+	 */
+	private _setTagAttrs;
+	/**
+	 * @private
+	 * @description Uploads audio files to the server.
+	 * - Sends a request to the configured upload URL and processes the response.
+	 * @param {AudioInfo} info - Upload metadata, including `files` and `isUpdate`.
+	 * @param {FileList|File[]} files - The files to be uploaded.
+	 */
+	private _serverUpload;
+	/**
+	 * @private
+	 * @description Handles errors that occur during the audio upload process.
+	 * - Triggers the `onAudioUploadError` event to allow custom handling of errors.
+	 * - Displays an error message in the editor's UI.
+	 * - Logs the error to the console for debugging.
+	 * @param {Object<string, *>} response - The error response object from the server or upload process.
+	 * @returns {Promise<void>}
+	 */
+	private _error;
+	#private;
+}
+import EditorInjector from '../../editorInjector';
+import { Modal } from '../../modules';
+import { Controller } from '../../modules';
+import { FileManager } from '../../modules';
+import { Figure } from '../../modules';