suneditor 3.1.4 → 3.2.0

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

@@ -0,0 +1,165 @@
+import type {} from '../../typedef';
+export default SlashCommand;
+export type SlashCommandItem = {
+	/**
+	 * - Unique identifier for the item.
+	 */
+	key: string;
+	/**
+	 * - Display label.
+	 */
+	title: string;
+	/**
+	 * - Icon key from `$.icons` (e.g. `'h1'`) or a raw HTML string (e.g. `'<svg>...</svg>'`).
+	 */
+	icon?: string;
+	/**
+	 * - Extra search terms used in addition to the title.
+	 */
+	keywords?: string[];
+	/**
+	 * - Invoked when the item is selected.
+	 * The trigger string (e.g. `/hea`) is already removed from the editor and the caret restored to that position before `action` runs.
+	 * The action owns its history entry — calling an L3 wrapper (`$.html.*`, `$.format.*`, `$.inline.apply`) auto-pushes; otherwise call `$.history.push(false)` manually.
+	 */
+	action: (arg0: SunEditor.Deps, arg1: SlashCommandActionContext) => void | Promise<void>;
+};
+export type SlashCommandActionContext = {
+	/**
+	 * - The configured trigger character (e.g. `'/'`).
+	 */
+	triggerChar: string;
+	/**
+	 * - The text the user typed after the trigger (e.g. `'hea'`).
+	 */
+	query: string;
+	/**
+	 * - The selected item.
+	 */
+	item: SlashCommandItem;
+};
+export type SlashCommandPluginOptions = {
+	/**
+	 * - Character that opens the command menu. Single character recommended.
+	 */
+	triggerChar?: string;
+	/**
+	 * - Menu entries. Strings resolve via `ResolveButton`
+	 * (plugin names, built-in commands like `'bold'`); objects are custom items with their own `action`.
+	 * Required.
+	 */
+	items: Array<SlashCommandItem | string>;
+	/**
+	 * - Debounce delay (ms) before the input is inspected for the trigger.
+	 */
+	delayTime?: number;
+	/**
+	 * - Maximum number of items shown in the dropdown.
+	 */
+	limitSize?: number;
+	/**
+	 * - Message shown when no items match the query. If unset, the menu closes on no match.
+	 */
+	emptyMessage?: string;
+	/**
+	 * - Custom item HTML renderer.
+	 * Applied only to custom item objects; plugin-name entries always render with the canonical BlockHandle row.
+	 * ```js
+	 * SUNEDITOR.create('#editor', {
+	 * plugins: [slashCommand],
+	 * slashCommand: {
+	 * triggerChar: '/',
+	 * items: [
+	 * {
+	 * key: 'h1',
+	 * title: 'Heading 1',
+	 * icon: 'h1',
+	 * keywords: ['header', 'title'],
+	 * action: ($) => $.format.applyBlock(document.createElement('H1')),
+	 * },
+	 * 'bold',
+	 * 'image',
+	 * 'blockStyle',
+	 * ],
+	 * },
+	 * });
+	 * ```
+	 */
+	renderItem?: (
+		arg0: SlashCommandItem,
+		arg1: {
+			icons: any;
+		},
+	) => string;
+};
+/**
+ * @typedef {Object} SlashCommandItem
+ * @property {string} key - Unique identifier for the item.
+ * @property {string} title - Display label.
+ * @property {string} [icon] - Icon key from `$.icons` (e.g. `'h1'`) or a raw HTML string (e.g. `'<svg>...</svg>'`).
+ * @property {string[]} [keywords] - Extra search terms used in addition to the title.
+ * @property {function(SunEditor.Deps, SlashCommandActionContext): void | Promise<void>} action - Invoked when the item is selected.
+ *   The trigger string (e.g. `/hea`) is already removed from the editor and the caret restored to that position before `action` runs.
+ *   The action owns its history entry — calling an L3 wrapper (`$.html.*`, `$.format.*`, `$.inline.apply`) auto-pushes; otherwise call `$.history.push(false)` manually.
+ */
+/**
+ * @typedef {Object} SlashCommandActionContext
+ * @property {string} triggerChar - The configured trigger character (e.g. `'/'`).
+ * @property {string} query - The text the user typed after the trigger (e.g. `'hea'`).
+ * @property {SlashCommandItem} item - The selected item.
+ */
+/**
+ * @typedef {Object} SlashCommandPluginOptions
+ * @property {string} [triggerChar='/'] - Character that opens the command menu. Single character recommended.
+ * @property {Array<SlashCommandItem | string>} items - Menu entries. Strings resolve via `ResolveButton`
+ *   (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 {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.
+ * ```js
+ * SUNEDITOR.create('#editor', {
+ *   plugins: [slashCommand],
+ *   slashCommand: {
+ *     triggerChar: '/',
+ *     items: [
+ *       {
+ *         key: 'h1',
+ *         title: 'Heading 1',
+ *         icon: 'h1',
+ *         keywords: ['header', 'title'],
+ *         action: ($) => $.format.applyBlock(document.createElement('H1')),
+ *       },
+ *       'bold',
+ *       'image',
+ *       'blockStyle',
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+/**
+ * @class
+ * @description Slash Command plugin
+ * - Notion / Tiptap style "/" command menu. Triggered by the configured character (default `'/'`).
+ * - Menu rendering + dispatch is delegated to {@link CommandMenu}, which is also used by BlockHandle's
+ *   action menu — both menus share the exact same row HTML and dispatch behavior.
+ * - SlashCommand-specific concerns kept here: input watching, debounce, trigger detection,
+ *   trigger text deletion before dispatch, empty-state row.
+ */
+declare class SlashCommand extends PluginField {
+	/**
+	 * @constructor
+	 * @param {SunEditor.Kernel} kernel
+	 * @param {SlashCommandPluginOptions} pluginOptions
+	 */
+	constructor(kernel: SunEditor.Kernel, pluginOptions: SlashCommandPluginOptions);
+	controller: Controller;
+	onInput(params: SunEditor.HookParams.InputWithData): void;
+	onKeyDown(params: SunEditor.HookParams.KeyEvent): void | boolean;
+	#private;
+}
+import { PluginField } from '../../interfaces';
+import { Controller } from '../../modules/contract';

package/types/plugins/index.d.ts

@@ -7,6 +7,7 @@ declare namespace _default {
 	export { list_bulleted };
 	export { list_numbered };
 	export { autocomplete };
+	export { slashCommand };
 	export { align };
 	export { font };
 	export { fontColor };
@@ -62,6 +63,7 @@ import table from './dropdown/table';
 import template from './dropdown/template';
 import textStyle from './dropdown/textStyle';
 import autocomplete from './field/autocomplete';
+import slashCommand from './field/slashCommand';
 import fontSize from './input/fontSize';
 import pageNavigator from './input/pageNavigator';
 import audio from './modal/audio';
@@ -103,6 +105,7 @@ export {
 	math,
 	pageNavigator,
 	paragraphStyle,
+	slashCommand,
 	table,
 	template,
 	textStyle,

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

@@ -36,7 +36,10 @@ export type LinkOptions = {
 	 */
 	acceptedFormats?: string;
 };
-export type LinkPluginOptions = Omit<LinkOptions & import('../../modules/ui/ModalAnchorEditor').ModalAnchorEditorParams, ''>;
+export type LinkPluginOptions = Omit<
+	LinkOptions & import('../../modules/ui/ModalAnchorEditor').ModalAnchorEditorParams,
+	''
+>;
 /**
  * @typedef {Object} LinkOptions
  * @property {string} [uploadUrl] - The URL endpoint for file uploads.

package/types/typedef.d.ts

@@ -17,6 +17,20 @@ declare global {
 		type EventWysiwyg = HTMLElement & Window;
 		type WysiwygFrame = HTMLElement & HTMLIFrameElement;
 		type GlobalWindow = Window & typeof globalThis;
+		type ComponentLauncher = {
+			/**
+			 * - Delete hook (invoked by the selected-component keydown handler).
+			 */
+			componentDestroy?: (target: any) => void | Promise<void>;
+			/**
+			 * - Optional select hook.
+			 */
+			componentSelect?: (target: any) => boolean | void;
+			/**
+			 * - Optional deselect hook.
+			 */
+			componentDeselect?: (target: any) => void;
+		};
 		type ComponentInfo = {
 			/**
 			 * - The target element associated with the component.
@@ -53,9 +67,9 @@ declare global {
 			 */
 			isFile: boolean;
 			/**
-			 * - The element that triggered the component, if applicable.
+			 * - Hook object for non-plugin components (e.g. `pageBreak`), if applicable.
 			 */
-			launcher: HTMLElement | null;
+			launcher: SunEditor.ComponentLauncher | null;
 			/**
 			 * - Whether the component is an input component (e.g., table).
 			 */
@@ -117,35 +131,35 @@ declare global {
 				type Init = typeof import('./hooks/base').Core.Init;
 			}
 			namespace Component {
-				type Select = typeof import('./interfaces/contracts').EditorComponent.prototype.componentSelect;
-				type Deselect = typeof import('./interfaces/contracts').EditorComponent.prototype.componentDeselect;
-				type Edit = typeof import('./interfaces/contracts').EditorComponent.prototype.componentEdit;
-				type Destroy = typeof import('./interfaces/contracts').EditorComponent.prototype.componentDestroy;
-				type Copy = typeof import('./interfaces/contracts').EditorComponent.prototype.componentCopy;
+				type Select = import('./interfaces/contracts').EditorComponent['componentSelect'];
+				type Deselect = import('./interfaces/contracts').EditorComponent['componentDeselect'];
+				type Edit = import('./interfaces/contracts').EditorComponent['componentEdit'];
+				type Destroy = import('./interfaces/contracts').EditorComponent['componentDestroy'];
+				type Copy = import('./interfaces/contracts').EditorComponent['componentCopy'];
 			}
 			namespace Modal {
-				type Action = typeof import('./interfaces/contracts').ModuleModal.prototype.modalAction;
-				type On = typeof import('./interfaces/contracts').ModuleModal.prototype.modalOn;
-				type Init = typeof import('./interfaces/contracts').ModuleModal.prototype.modalInit;
-				type Off = typeof import('./interfaces/contracts').ModuleModal.prototype.modalOff;
-				type Resize = typeof import('./interfaces/contracts').ModuleModal.prototype.modalResize;
+				type Action = import('./interfaces/contracts').ModuleModal['modalAction'];
+				type On = import('./interfaces/contracts').ModuleModal['modalOn'];
+				type Init = import('./interfaces/contracts').ModuleModal['modalInit'];
+				type Off = import('./interfaces/contracts').ModuleModal['modalOff'];
+				type Resize = import('./interfaces/contracts').ModuleModal['modalResize'];
 			}
 			namespace Controller {
-				type Action = typeof import('./interfaces/contracts').ModuleController.prototype.controllerAction;
-				type On = typeof import('./interfaces/contracts').ModuleController.prototype.controllerOn;
-				type Close = typeof import('./interfaces/contracts').ModuleController.prototype.controllerClose;
+				type Action = import('./interfaces/contracts').ModuleController['controllerAction'];
+				type On = import('./interfaces/contracts').ModuleController['controllerOn'];
+				type Close = import('./interfaces/contracts').ModuleController['controllerClose'];
 			}
 			namespace Browser {
-				type Init = typeof import('./interfaces/contracts').ModuleBrowser.prototype.browserInit;
+				type Init = import('./interfaces/contracts').ModuleBrowser['browserInit'];
 			}
 			namespace ColorPicker {
-				type Action = typeof import('./interfaces/contracts').ModuleColorPicker.prototype.colorPickerAction;
-				type HueSliderOpen = typeof import('./interfaces/contracts').ModuleColorPicker.prototype.colorPickerHueSliderOpen;
-				type HueSliderClose = typeof import('./interfaces/contracts').ModuleColorPicker.prototype.colorPickerHueSliderClose;
+				type Action = import('./interfaces/contracts').ModuleColorPicker['colorPickerAction'];
+				type HueSliderOpen = import('./interfaces/contracts').ModuleColorPicker['colorPickerHueSliderOpen'];
+				type HueSliderClose = import('./interfaces/contracts').ModuleColorPicker['colorPickerHueSliderClose'];
 			}
 			namespace HueSlider {
-				type Action = typeof import('./interfaces/contracts').ModuleHueSlider.prototype.hueSliderAction;
-				type CancelAction = typeof import('./interfaces/contracts').ModuleHueSlider.prototype.hueSliderCancelAction;
+				type Action = import('./interfaces/contracts').ModuleHueSlider['hueSliderAction'];
+				type CancelAction = import('./interfaces/contracts').ModuleHueSlider['hueSliderCancelAction'];
 			}
 		}
 		export namespace HookParams {
@@ -261,7 +275,13 @@ declare global {
 			 * - `"#fix"`: RTL direction fix
 			 * - `"%100"|"%50"`: Responsive breakpoint (percentage)
 			 */
-			type ButtonSpecial = '|' | '/' | `-${'left' | 'right' | 'center'}` | '#fix' | `:${string}-${string}` | `%${number}`;
+			type ButtonSpecial =
+				| '|'
+				| '/'
+				| `-${'left' | 'right' | 'center'}`
+				| '#fix'
+				| `:${string}-${string}`
+				| `%${number}`;
 			/**
 			 * Plugin buttons available in the toolbar
 			 */
@@ -307,6 +327,7 @@ declare global {
 				| 'list_bulleted'
 				| 'list_numbered'
 				| 'autocomplete'
+				| 'slashCommand'
 				| 'align'
 				| 'font'
 				| 'fontColor'
@@ -339,7 +360,11 @@ declare global {
 			 * Button list configuration for the toolbar
 			 * Supports nested arrays, special controls, and responsive breakpoint configurations
 			 */
-			type ButtonItem = SunEditor.UI.ButtonCommand | SunEditor.UI.ButtonPlugin | SunEditor.UI.ButtonSpecial | string;
+			type ButtonItem =
+				| SunEditor.UI.ButtonCommand
+				| SunEditor.UI.ButtonPlugin
+				| SunEditor.UI.ButtonSpecial
+				| string;
 			/**
 			 * ///
 			 * ---[ End of auto-generated button types ]---