suneditor 3.0.0-rc.4 → 3.0.0

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

@@ -13,14 +13,21 @@ export type FontSizePluginOptions = {
 	showDefaultSizeLabel?: boolean;
 	/**
 	 * - When `true`, displays increase and decrease buttons for font size adjustments.
+	 * - Defaults to `false`. Always `false` when `sizeUnit` is `'text'` (ignored).
 	 */
 	showIncDecControls?: boolean;
 	/**
 	 * - When `true`, disables the direct font size input box.
+	 * - Defaults to `true` when `sizeUnit` is `'text'`, otherwise `false`.
 	 */
 	disableInput?: boolean;
 	/**
-	 * - Optional object to override or extend the default unit mapping for font sizes.
+	 * - Override or extend the default unit mapping for font sizes.
+	 * Each key is a unit name (e.g., `'px'`, `'em'`). `default`: initial size, `inc`: step for inc/dec buttons, `min`/`max`: range limits, `list`: dropdown values.
+	 * When `sizeUnit` is `'text'`, list items use `{title: string, size: string}` instead of numbers.
+	 * ```js
+	 * { unitMap: { px: { default: 16, inc: 1, min: 8, max: 72, list: [8, 12, 16, 20, 24, 32, 48] } } }
+	 * ```
 	 */
 	unitMap?: {
 		[x: string]: {
@@ -38,9 +45,16 @@ export type FontSizePluginOptions = {
  * - Accepted values include: `'px'`, `'pt'`, `'em'`, `'rem'`, `'vw'`, `'vh'`, `'%'` or `'text'`.
  * - If `'text'` is used, a text-based font size list is applied.
  * @property {boolean} [showDefaultSizeLabel=true] - Determines whether the default size label is displayed in the dropdown menu.
- * @property {boolean} [showIncDecControls=false] - When `true`, displays increase and decrease buttons for font size adjustments.
- * @property {boolean} [disableInput=true] - When `true`, disables the direct font size input box.
- * @property {Object<string, {default: number, inc: number, min: number, max: number, list: Array<number>}>} [unitMap={}] - Optional object to override or extend the default unit mapping for font sizes.
+ * @property {boolean} [showIncDecControls] - When `true`, displays increase and decrease buttons for font size adjustments.
+ * - Defaults to `false`. Always `false` when `sizeUnit` is `'text'` (ignored).
+ * @property {boolean} [disableInput] - When `true`, disables the direct font size input box.
+ * - Defaults to `true` when `sizeUnit` is `'text'`, otherwise `false`.
+ * @property {Object<string, {default: number, inc: number, min: number, max: number, list: Array<number>}>} [unitMap={}] - Override or extend the default unit mapping for font sizes.
+ * Each key is a unit name (e.g., `'px'`, `'em'`). `default`: initial size, `inc`: step for inc/dec buttons, `min`/`max`: range limits, `list`: dropdown values.
+ * When `sizeUnit` is `'text'`, list items use `{title: string, size: string}` instead of numbers.
+ * ```js
+ * { unitMap: { px: { default: 16, inc: 1, min: 8, max: 72, list: [8, 12, 16, 20, 24, 32, 48] } } }
+ * ```
  */
 /**
  * @class

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

@@ -2,11 +2,11 @@ import type {} from '../../typedef';
 export default Audio_;
 export type AudioPluginOptions = {
 	/**
-	 * - The default width of the `AUDIO` tag (e.g., `"300px"`).
+	 * - The default width of the `AUDIO` tag.
 	 */
 	defaultWidth?: string;
 	/**
-	 * - The default height of the `AUDIO` tag (e.g., `"150px"`).
+	 * - The default height of the `AUDIO` tag.
 	 */
 	defaultHeight?: string;
 	/**
@@ -14,7 +14,8 @@ export type AudioPluginOptions = {
 	 */
 	createFileInput?: boolean;
 	/**
-	 * - Whether to create a URL input element (default is `true` if file input is not created).
+	 * - Whether to create a URL input element.
+	 * - Defaults to `true`. Always `true` when `createFileInput` is `false`.
 	 */
 	createUrlInput?: boolean;
 	/**
@@ -45,6 +46,9 @@ export type AudioPluginOptions = {
 	acceptedFormats?: string;
 	/**
 	 * - Additional attributes to set on the `AUDIO` tag.
+	 * ```js
+	 * { audioTagAttributes: { controls: 'true', preload: 'metadata' } }
+	 * ```
 	 */
 	audioTagAttributes?: {
 		[x: string]: string;
@@ -61,10 +65,11 @@ export type AudioPluginOptions = {
 };
 /**
  * @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 {string} [defaultWidth="300px"] - The default width of the `AUDIO` tag.
+ * @property {string} [defaultHeight="150px"] - The default height of the `AUDIO` tag.
  * @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 {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.
  * @property {Object<string, string>} [uploadHeaders] - Headers to include in the file upload request.
  * @property {number} [uploadSizeLimit] - The total upload size limit in bytes.
@@ -72,6 +77,9 @@ export type AudioPluginOptions = {
  * @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.
+ * ```js
+ * { audioTagAttributes: { controls: 'true', preload: 'metadata' } }
+ * ```
  * @property {SunEditor.ComponentInsertType} [insertBehavior] - Component insertion behavior for selection and cursor placement.
  * - [default: `options.get('componentInsertBehavior')`]
  * - `auto`: Move cursor to the next line if possible, otherwise select the component.

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

@@ -41,42 +41,45 @@ export type EmbedPluginOptions = {
 	uploadSingleSizeLimit?: number;
 	/**
 	 * - Additional attributes to set on the `IFRAME` tag.
+	 * ```js
+	 * { iframeTagAttributes: { allowfullscreen: 'true', loading: 'lazy' } }
+	 * ```
 	 */
 	iframeTagAttributes?: {
 		[x: string]: string;
 	};
 	/**
-	 * - YouTube query parameter.
+	 * - YouTube query parameter appended to the embed URL.
+	 * ```js
+	 * { query_youtube: 'autoplay=1&mute=1' }
+	 * ```
 	 */
 	query_youtube?: string;
 	/**
-	 * - Vimeo query parameter.
+	 * - Vimeo query parameter appended to the embed URL.
+	 * ```js
+	 * { query_vimeo: 'autoplay=1' }
+	 * ```
 	 */
 	query_vimeo?: string;
 	/**
-	 * - Additional URL patterns for embed.
+	 * - Additional URL patterns to recognize as embeddable content.
 	 */
 	urlPatterns?: Array<RegExp>;
 	/**
-	 * - Custom query objects for additional embedding services.
-	 * Example :
+	 * - Custom embed service definitions.
+	 * Each key is a service name, with `pattern` to match the URL, `action` to transform it into an embed URL, and `tag` for the output element.
+	 * ```js
 	 * {
+	 * embedQuery: {
 	 * facebook: {
-	 * pattern: /(?:https?:\/\/)?(?:www\.)?(?:facebook\.com)\/(.+)/i,
-	 * action: (url) => {
-	 * return `https://www.facebook.com/plugins/post.php?href=${encodeURIComponent(url)}&show_text=true&width=500`;
-	 * },
+	 * pattern: /(?:https?:\/\/)?(?:www\.)?facebook\.com\/(.+)/i,
+	 * action: (url) => `https://www.facebook.com/plugins/post.php?href=${encodeURIComponent(url)}`,
 	 * tag: 'iframe'
-	 * },
-	 * twitter: {
-	 * pattern: /(?:https?:\/\/)?(?:www\.)?(?:twitter\.com)\/(status|embed)\/(.+)/i,
-	 * action: (url) => {
-	 * return `https://platform.twitter.com/embed/Tweet.html?url=${encodeURIComponent(url)}`;
-	 * },
-	 * tag: 'iframe'
-	 * },
-	 * // Additional services...
 	 * }
+	 * }
+	 * }
+	 * ```
 	 */
 	embedQuery?: {
 		[x: string]: {
@@ -111,28 +114,31 @@ export type EmbedPluginOptions = {
  * @property {number} [uploadSizeLimit] - The total file upload size limit in bytes.
  * @property {number} [uploadSingleSizeLimit] - The single file upload size limit in bytes.
  * @property {Object<string, string>} [iframeTagAttributes] - Additional attributes to set on the `IFRAME` tag.
- * @property {string} [query_youtube] - YouTube query parameter.
- * @property {string} [query_vimeo] - Vimeo query parameter.
- * @property {Array<RegExp>} [urlPatterns] - Additional URL patterns for embed.
- * @property {Object<string, {pattern: RegExp, action: (url: string) => string, tag: string}>} [embedQuery] - Custom query objects for additional embedding services.
- * Example :
+ * ```js
+ * { iframeTagAttributes: { allowfullscreen: 'true', loading: 'lazy' } }
+ * ```
+ * @property {string} [query_youtube] - YouTube query parameter appended to the embed URL.
+ * ```js
+ * { query_youtube: 'autoplay=1&mute=1' }
+ * ```
+ * @property {string} [query_vimeo] - Vimeo query parameter appended to the embed URL.
+ * ```js
+ * { query_vimeo: 'autoplay=1' }
+ * ```
+ * @property {Array<RegExp>} [urlPatterns] - Additional URL patterns to recognize as embeddable content.
+ * @property {Object<string, {pattern: RegExp, action: (url: string) => string, tag: string}>} [embedQuery] - Custom embed service definitions.
+ * Each key is a service name, with `pattern` to match the URL, `action` to transform it into an embed URL, and `tag` for the output element.
+ * ```js
  * {
- *   facebook: {
- *     pattern: /(?:https?:\/\/)?(?:www\.)?(?:facebook\.com)\/(.+)/i,
- *     action: (url) => {
- *       return `https://www.facebook.com/plugins/post.php?href=${encodeURIComponent(url)}&show_text=true&width=500`;
- *     },
- *     tag: 'iframe'
- *   },
- *   twitter: {
- *     pattern: /(?:https?:\/\/)?(?:www\.)?(?:twitter\.com)\/(status|embed)\/(.+)/i,
- *     action: (url) => {
- *       return `https://platform.twitter.com/embed/Tweet.html?url=${encodeURIComponent(url)}`;
- *     },
- *     tag: 'iframe'
- *   },
- *   // Additional services...
+ *   embedQuery: {
+ *     facebook: {
+ *       pattern: /(?:https?:\/\/)?(?:www\.)?facebook\.com\/(.+)/i,
+ *       action: (url) => `https://www.facebook.com/plugins/post.php?href=${encodeURIComponent(url)}`,
+ *       tag: 'iframe'
+ *     }
+ *   }
  * }
+ * ```
  * @property {SunEditor.Module.Figure.Controls} [controls] - Figure controls.
  * @property {SunEditor.ComponentInsertType} [insertBehavior] - Component insertion behavior for selection and cursor placement.
  * - [default: `options.get('componentInsertBehavior')`]

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

@@ -27,6 +27,7 @@ export type ImagePluginOptions = {
 	createFileInput?: boolean;
 	/**
 	 * - Whether to create a URL input element for image insertion.
+	 * - Defaults to `true`. Always `true` when `createFileInput` is `false`.
 	 */
 	createUrlInput?: boolean;
 	/**
@@ -35,6 +36,9 @@ export type ImagePluginOptions = {
 	uploadUrl?: string;
 	/**
 	 * - Additional headers to include in the file upload request.
+	 * ```js
+	 * { uploadUrl: '/api/upload/image', uploadHeaders: { Authorization: 'Bearer token' } }
+	 * ```
 	 */
 	uploadHeaders?: {
 		[x: string]: string;
@@ -109,9 +113,13 @@ export type ImageState = {
  * @property {string} [defaultHeight="auto"] - The default height of the image. If a number is provided, `"px"` will be appended.
  * @property {boolean} [percentageOnlySize=false] - Whether to allow only percentage-based sizing.
  * @property {boolean} [createFileInput=true] - Whether to create a file input element for image uploads.
- * @property {boolean} [createUrlInput=true] - Whether to create a URL input element for image insertion.
+ * @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.
  * @property {Object<string, string>} [uploadHeaders] - Additional headers to include in the file upload request.
+ * ```js
+ * { uploadUrl: '/api/upload/image', uploadHeaders: { Authorization: 'Bearer token' } }
+ * ```
  * @property {number} [uploadSizeLimit] - The total upload size limit in bytes.
  * @property {number} [uploadSingleSizeLimit] - The single file upload size limit in bytes.
  * @property {boolean} [allowMultiple=false] - Whether multiple image uploads are allowed.

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

@@ -80,11 +80,15 @@ declare class Link extends PluginModal {
 		 */
 		noAutoPrefix?: boolean;
 		/**
-		 * - The `rel` attribute list of anchor tag.
+		 * - Available `rel` attribute values shown as checkboxes in the link modal.
 		 */
 		relList?: Array<string>;
 		/**
-		 * - Default `rel` attributes of anchor tag.
+		 * - 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' } }
+		 * ```
 		 */
 		defaultRel?: {
 			default?: string;

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

@@ -10,9 +10,17 @@ export type MathPluginOptions = {
 	 */
 	autoHeight?: boolean;
 	/**
-	 * - A list of font size options for rendering math expressions.
+	 * - A list of font size options for the math expression size selector.
+	 * ```js
+	 * // fontSizeList
+	 * [{ text: '1', value: '1em', default: true }, { text: '1.5', value: '1.5em' }, { text: '2', value: '2em' }]
+	 * ```
 	 */
-	fontSizeList?: Array<object>;
+	fontSizeList?: Array<{
+		text: string;
+		value: string;
+		default?: true;
+	}>;
 	/**
 	 * - A callback function to handle paste events in the math input area.
 	 */
@@ -33,11 +41,16 @@ export type MathPluginOptions = {
  * @typedef {Object} MathPluginOptions
  * @property {boolean} [canResize=true] - Whether the math modal can be resized.
  * @property {boolean} [autoHeight=false] - Whether to automatically adjust the height of the modal.
- * @property {Array<object>} [fontSizeList] - A list of font size options for rendering math expressions.
+ * @property {Array<{text: string, value: string, default?: true}>} [fontSizeList] - A list of font size options for the math expression size selector.
+ * ```js
+ * // fontSizeList
+ * [{ text: '1', value: '1em', default: true }, { text: '1.5', value: '1.5em' }, { text: '2', value: '2em' }]
+ * ```
  * @property {?(...args: *) => *} [onPaste] - A callback function to handle paste events in the math input area.
  * @property {Object} [formSize={}] - An object specifying the dimensions for the math modal.
  * @property {string} [formSize.width="460px"] - The default width of the math modal.
- * @property {string} [formSize.height="14em"] - The default height of the math modal.
+ * @property {string} [formSize.height] - The default height of the math modal.
+ * - Defaults to `"14em"`. When `autoHeight` is `true`, defaults to `formSize.minHeight`.
  * @property {string} [formSize.maxWidth] - The maximum width of the math modal.
  * @property {string} [formSize.maxHeight] - The maximum height of the math modal.
  * @property {string} [formSize.minWidth="400px"] - The minimum width of the math modal.
@@ -72,6 +85,7 @@ declare class Math_ extends PluginModal {
 			width: string;
 			/**
 			 * - The default height of the math modal.
+			 * - Defaults to `"14em"`. When `autoHeight` is `true`, defaults to `formSize.minHeight`.
 			 */
 			height: string;
 			/**
@@ -93,7 +107,11 @@ declare class Math_ extends PluginModal {
 		};
 		canResize: boolean;
 		autoHeight: boolean;
-		fontSizeList: any[];
+		fontSizeList: {
+			text: string;
+			value: string;
+			default?: true;
+		}[];
 		onPaste: (...args: any) => any;
 	};
 	defaultFontSize: any;

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

@@ -27,6 +27,7 @@ export type VideoPluginOptions = {
 	createFileInput?: boolean;
 	/**
 	 * - Whether to create a URL input element for video embedding.
+	 * - Defaults to `true`. Always `true` when `createFileInput` is `false`.
 	 */
 	createUrlInput?: boolean;
 	/**
@@ -56,7 +57,7 @@ export type VideoPluginOptions = {
 	 */
 	acceptedFormats?: string;
 	/**
-	 * - The default aspect ratio for the video (e.g., 16:9 is 0.5625).
+	 * - The default aspect ratio for the video (height/width, e.g. 16:9 → `9/16 = 0.5625`).
 	 */
 	defaultRatio?: number;
 	/**
@@ -64,31 +65,50 @@ export type VideoPluginOptions = {
 	 */
 	showRatioOption?: boolean;
 	/**
-	 * - Custom ratio options for video resizing.
+	 * - Custom ratio options for video resizing (value = height/width).
+	 * ```js
+	 * // ratioOptions
+	 * [{ name: '16:9', value: 0.5625 }, { name: '4:3', value: 0.75 }]
+	 * ```
 	 */
-	ratioOptions?: any[];
+	ratioOptions?: Array<{
+		name: string;
+		value: number;
+	}>;
 	/**
 	 * - Additional attributes to set on the `VIDEO` tag.
+	 * ```js
+	 * { videoTagAttributes: { controls: 'true', muted: 'true', playsinline: '' } }
+	 * ```
 	 */
 	videoTagAttributes?: {
 		[x: string]: string;
 	};
 	/**
 	 * - Additional attributes to set on the `IFRAME` tag.
+	 * ```js
+	 * { iframeTagAttributes: { allowfullscreen: 'true', loading: 'lazy' } }
+	 * ```
 	 */
 	iframeTagAttributes?: {
 		[x: string]: string;
 	};
 	/**
 	 * - Additional query parameters for YouTube embedding.
+	 * ```js
+	 * { query_youtube: 'autoplay=1&mute=1' }
+	 * ```
 	 */
 	query_youtube?: string;
 	/**
 	 * - Additional query parameters for Vimeo embedding.
+	 * ```js
+	 * { query_vimeo: 'autoplay=1' }
+	 * ```
 	 */
 	query_vimeo?: string;
 	/**
-	 * - Custom query objects for additional embedding services.
+	 * - Custom embed service definitions (see `EmbedPluginOptions.embedQuery`).
 	 */
 	embedQuery?: {
 		[x: string]: {
@@ -132,21 +152,38 @@ export type VideoState = {
  * @property {string} [defaultHeight] - The default height of the video element. If a number is provided, `"px"` will be appended.
  * @property {boolean} [percentageOnlySize=false] - Whether to allow only percentage-based sizing.
  * @property {boolean} [createFileInput=false] - Whether to create a file input element for video uploads.
- * @property {boolean} [createUrlInput=true] - Whether to create a URL input element for video embedding.
+ * @property {boolean} [createUrlInput] - Whether to create a URL input element for video embedding.
+ * - Defaults to `true`. Always `true` when `createFileInput` is `false`.
  * @property {string} [uploadUrl] - The URL endpoint for video file uploads.
  * @property {Object<string, string>} [uploadHeaders] - Additional headers to include in the video upload request.
  * @property {number} [uploadSizeLimit] - The total upload size limit for videos in bytes.
  * @property {number} [uploadSingleSizeLimit] - The single file upload size limit for videos in bytes.
  * @property {boolean} [allowMultiple=false] - Whether multiple video uploads are allowed.
  * @property {string} [acceptedFormats="video/*"] - Accepted file formats for video uploads (`"video/*"`).
- * @property {number} [defaultRatio=0.5625] - The default aspect ratio for the video (e.g., 16:9 is 0.5625).
+ * @property {number} [defaultRatio=0.5625] - The default aspect ratio for the video (height/width, e.g. 16:9 → `9/16 = 0.5625`).
  * @property {boolean} [showRatioOption=true] - Whether to display the ratio option in the modal.
- * @property {Array} [ratioOptions] - Custom ratio options for video resizing.
+ * @property {Array<{name: string, value: number}>} [ratioOptions] - Custom ratio options for video resizing (value = height/width).
+ * ```js
+ * // ratioOptions
+ * [{ name: '16:9', value: 0.5625 }, { name: '4:3', value: 0.75 }]
+ * ```
  * @property {Object<string, string>} [videoTagAttributes] - Additional attributes to set on the `VIDEO` tag.
+ * ```js
+ * { videoTagAttributes: { controls: 'true', muted: 'true', playsinline: '' } }
+ * ```
  * @property {Object<string, string>} [iframeTagAttributes] - Additional attributes to set on the `IFRAME` tag.
+ * ```js
+ * { iframeTagAttributes: { allowfullscreen: 'true', loading: 'lazy' } }
+ * ```
  * @property {string} [query_youtube=""] - Additional query parameters for YouTube embedding.
+ * ```js
+ * { query_youtube: 'autoplay=1&mute=1' }
+ * ```
  * @property {string} [query_vimeo=""] - Additional query parameters for Vimeo embedding.
- * @property {Object<string, {pattern: RegExp, action: (url: string) => string, tag: string}>} [embedQuery] - Custom query objects for additional embedding services.
+ * ```js
+ * { query_vimeo: 'autoplay=1' }
+ * ```
+ * @property {Object<string, {pattern: RegExp, action: (url: string) => string, tag: string}>} [embedQuery] - Custom embed service definitions (see `EmbedPluginOptions.embedQuery`).
  * @property {Array<RegExp>} [urlPatterns] - Additional URL patterns for video embedding.
  * @property {Array<string>} [extensions] - Additional file extensions to be recognized for video uploads.
  * @property {SunEditor.Module.Figure.Controls} [controls] - Figure controls.
@@ -208,7 +245,10 @@ declare class Video extends PluginModal {
 		acceptedFormats: string;
 		defaultRatio: number;
 		showRatioOption: boolean;
-		ratioOptions: any[];
+		ratioOptions: {
+			name: string;
+			value: number;
+		}[];
 		videoTagAttributes: {
 			[x: string]: string;
 		};

package/types/typedef.d.ts

@@ -179,7 +179,7 @@ declare global {
 				/**
 				 * Event listener
 				 */
-				listener: EventListenerOrEventListenerObject;
+				listener: any;
 				/**
 				 * Event useCapture option
 				 */
@@ -196,7 +196,7 @@ declare global {
 				/**
 				 * Event listener
 				 */
-				listener: (...args: any) => any;
+				listener: any;
 				/**
 				 * Use event capture
 				 */
@@ -279,6 +279,7 @@ declare global {
 				| 'fullScreen'
 				| 'showBlocks'
 				| 'codeView'
+				| 'markdownView'
 				| 'undo'
 				| 'redo'
 				| 'preview'
@@ -287,6 +288,7 @@ declare global {
 				| 'dir'
 				| 'dir_ltr'
 				| 'dir_rtl'
+				| 'finder'
 				| 'save'
 				| 'newDocument'
 				| 'selectAll'
@@ -299,6 +301,7 @@ declare global {
 			 */
 			type ButtonPlugin =
 				| 'blockquote'
+				| 'codeBlock'
 				| 'exportPDF'
 				| 'fileUpload'
 				| 'list_bulleted'