suneditor 3.0.0-beta.9 → 3.0.0-rc.2

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

@@ -0,0 +1,131 @@
+import type {} from '../../../typedef';
+export default Shortcuts;
+export type ShortcutInfo = {
+	/**
+	 * - Whether the [Ctrl, Command] key is pressed.
+	 */
+	c: boolean;
+	/**
+	 * - Whether the [Shift] key is pressed.
+	 */
+	s: boolean;
+	/**
+	 * - Whether the [Space] key is pressed.
+	 */
+	space: boolean;
+	/**
+	 * - Whether the Enter key is pressed.
+	 */
+	enter: boolean;
+	/**
+	 * - The command key. (e.g. `bold`)
+	 */
+	command: string;
+	/**
+	 * - Whether the cursor is at the end of the line.
+	 */
+	edge: boolean;
+	/**
+	 * - The key pressed (e.g., `1.`).
+	 */
+	key?: string;
+	/**
+	 * - The keyEvent.code.
+	 */
+	keyCode?: string;
+	/**
+	 * - A plugin's `shortcut` method that is called instead of the default `editor.run` method.
+	 */
+	method?: string | ((...args: any) => any);
+	/**
+	 * - The plugin name.
+	 */
+	plugin: string;
+	/**
+	 * - Plugin's type. (`command`, `dropdown`, `modal`, `browser`, `input`, `field`, `popup`).
+	 */
+	type: string;
+	/**
+	 * - The plugin command button.
+	 */
+	button: Node;
+	/**
+	 * - An array of key codes generated with the reverseButtons option, used to reverse the action for a specific key combination.
+	 */
+	r: Array<string>;
+	/**
+	 * - Whether the event was triggered by a text input (e.g., mention like
+	 */
+	textTrigger: string;
+};
+/**
+ * @typedef {Object} ShortcutInfo
+ * @property {boolean} c - Whether the [Ctrl, Command] key is pressed.
+ * @property {boolean} s - Whether the [Shift] key is pressed.
+ * @property {boolean} space - Whether the [Space] key is pressed.
+ * @property {boolean} enter - Whether the Enter key is pressed.
+ * @property {string} command - The command key. (e.g. `bold`)
+ * @property {boolean} edge - Whether the cursor is at the end of the line.
+ * @property {string} [key] - The key pressed (e.g., `1.`).
+ * @property {string} [keyCode] - The keyEvent.code.
+ * @property {string|((...args: *) => *)} [method] - A plugin's `shortcut` method that is called instead of the default `editor.run` method.
+ * @property {string} plugin - The plugin name.
+ * @property {string} type - Plugin's type. (`command`, `dropdown`, `modal`, `browser`, `input`, `field`, `popup`).
+ * @property {Node} button - The plugin command button.
+ * @property {Array<string>} r - An array of key codes generated with the reverseButtons option, used to reverse the action for a specific key combination.
+ * @property {string} textTrigger - Whether the event was triggered by a text input (e.g., mention like @ab).
+ */
+/**
+ * @description Shortcuts class
+ */
+declare class Shortcuts {
+	/**
+	 * @constructor
+	 * @param {SunEditor.Kernel} kernel
+	 */
+	constructor(kernel: SunEditor.Kernel);
+	/**
+	 * @description Shortcuts key map
+	 * @type {Map<string, *>}
+	 */
+	keyMap: Map<string, any>;
+	/**
+	 * @description Shortcuts reverse key array
+	 * - An array of key codes generated with the reverseButtons option, used to reverse the action for a specific key combination.
+	 * @type {Set<string>}
+	 */
+	reverseKeys: Set<string>;
+	/**
+	 * @description If there is a shortcut function, run it.
+	 * @param {KeyboardEvent} event Keyboard event object
+	 * @param {boolean} ctrl Whether the Ctrl key is pressed
+	 * @param {boolean} shift Whether the Shift key is pressed
+	 * @param {string} keyCode The keyEvent.code.
+	 * @param {string} text The text content of the key
+	 * @param {boolean} edge Whether the cursor is at the end of the line
+	 * @param {HTMLElement} line The current line node
+	 * @param {Range} range The current range object
+	 * @returns {boolean} Whether to execute shortcuts
+	 */
+	command(event: KeyboardEvent, ctrl: boolean, shift: boolean, keyCode: string, text: string, edge: boolean, line: HTMLElement, range: Range): boolean;
+	/**
+	 * @description Disable the shortcut activation.
+	 */
+	disable(): void;
+	/**
+	 * @description Enable the shortcut activation.
+	 */
+	enable(): void;
+	/**
+	 * @internal
+	 * @description Registers custom shortcut keys (keys starting with `_`) into the shortcut map.
+	 * Called during initialization and when toolbar is reset.
+	 */
+	_registerCustomShortcuts(): void;
+	/**
+	 * @internal
+	 * @description Destroy the Shortcuts instance and release memory
+	 */
+	_destroy(): void;
+	#private;
+}

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

@@ -0,0 +1,261 @@
+import type {} from '../../../typedef';
+export default UIManager;
+/**
+ * @description The UI class is a class that handles operations related to the user interface of SunEditor.
+ * - This class sets the editor's style, theme, editor mode, etc., and controls the state of various UI elements.
+ */
+declare class UIManager {
+	/**
+	 * @constructor
+	 * @param {SunEditor.Kernel} kernel
+	 */
+	constructor(kernel: SunEditor.Kernel);
+	alertModal: HTMLElement;
+	alertMessage: HTMLSpanElement;
+	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>}
+	 */
+	opendControllers: Array<SunEditor.Module.Controller.Info>;
+	/**
+	 * @description Controller target's frame div (`editor.frameContext.get('topArea')`)
+	 * @type {?HTMLElement}
+	 */
+	controllerTargetContext: HTMLElement | null;
+	/**
+	 * @internal
+	 * @description Current Figure container.
+	 * @type {?HTMLElement}
+	 */
+	_figureContainer: HTMLElement | null;
+	/**
+	 * @description Set editor frame styles.
+	 * - Define the style of the edit area
+	 * - It can also be defined with the `setOptions` method, but the `setEditorStyle` method does not render the editor again.
+	 * @param {string} style Style string
+	 * @param {?SunEditor.FrameContext} [fc] Frame context
+	 */
+	setEditorStyle(style: string, fc?: SunEditor.FrameContext | null): void;
+	/**
+	 * @description Set the theme to the editor
+	 * @param {string} theme Theme name
+	 */
+	setTheme(theme: string): void;
+	/**
+	 * @description Set direction to `rtl` or `ltr`.
+	 * @param {string} dir `rtl` or `ltr`
+	 */
+	setDir(dir: string): void;
+	/**
+	 * @description Switch to or off `ReadOnly` mode.
+	 * @param {boolean} value `readOnly` boolean value.
+	 * @param {string} [rootKey] Root key
+	 */
+	readOnly(value: boolean, rootKey?: string): void;
+	/**
+	 * @description Disables the editor.
+	 * @param {string} [rootKey] Root key
+	 */
+	disable(rootKey?: string): void;
+	/**
+	 * @description Enables the editor.
+	 * @param {string} [rootKey] Root key
+	 */
+	enable(rootKey?: string): void;
+	/**
+	 * @description Shows the editor interface.
+	 * @param {string} [rootKey] Root key
+	 */
+	show(rootKey?: string): void;
+	/**
+	 * @description Hides the editor interface.
+	 * @param {string} [rootKey] Root key
+	 */
+	hide(rootKey?: string): void;
+	/**
+	 * @description Shows the loading spinner.
+	 * @param {string} [rootKey] Root key
+	 */
+	showLoading(rootKey?: string): void;
+	/**
+	 * @description Hides the loading spinner.
+	 * @param {string} [rootKey] Root key
+	 */
+	hideLoading(rootKey?: string): void;
+	/**
+	 * @description  Open the alert panel
+	 * @param {string} text alert message
+	 * @param {""|"error"|"success"} type alert type
+	 */
+	alertOpen(text: string, type: '' | 'error' | 'success'): void;
+	/**
+	 * @description  Close the alert panel
+	 */
+	alertClose(): void;
+	/**
+	 * @description Show toast
+	 * @param {string} message toast message
+	 * @param {number} [duration=1000] duration time(ms)
+	 * @param {""|"error"|"success"} [type=""] duration time(ms)
+	 */
+	showToast(message: string, duration?: number, type?: '' | 'error' | 'success'): void;
+	/**
+	 * @description Close toast
+	 */
+	closeToast(): void;
+	/**
+	 * @description This method disables or enables the toolbar buttons when the `controller` is activated or deactivated.
+	 * - When the `controller` is activated, the toolbar buttons are disabled; when the `controller` is deactivated, the buttons are enabled.
+	 * @param {boolean} active If `true`, the toolbar buttons will be disabled. If `false`, the toolbar buttons will be enabled.
+	 * @returns {boolean} The current state of the controller on disabled buttons.
+	 */
+	setControllerOnDisabledButtons(active: boolean): boolean;
+	/**
+	 * @description Set the controller target context to the current top area.
+	 */
+	onControllerContext(): void;
+	/**
+	 * @description Reset the controller target context.
+	 */
+	offControllerContext(): void;
+	/**
+	 * @description Activate the transparent background `div` so that other elements are not affected during resizing.
+	 * @param {string} cursor cursor css property
+	 */
+	enableBackWrapper(cursor: string): void;
+	/**
+	 * @description Disabled background `div`
+	 */
+	disableBackWrapper(): void;
+	/**
+	 * @description Closes the currently active controller by delegating to the component's deselect logic.
+	 * Use this method to close a single active controller from external code.
+	 * @see _offControllers - For closing all open controllers at once (internal use)
+	 */
+	offCurrentController(): void;
+	/**
+	 * @description Closes the currently open modal dialog.
+	 */
+	offCurrentModal(): void;
+	/**
+	 * @description Get the current figure container only if it is visible (active).
+	 * @returns {?HTMLElement} The active figure element or null.
+	 */
+	getVisibleFigure(): HTMLElement | null;
+	/**
+	 * @description Set the active figure element (image, video) being resized.
+	 * @param {?HTMLElement} figure
+	 */
+	setFigureContainer(figure: HTMLElement | null): void;
+	preventToolbarHide(allow: any): void;
+	get isPreventToolbarHide(): boolean;
+	/**
+	 * @param {SunEditor.FrameContext} rt Root target[key] FrameContext
+	 */
+	reset(rt: SunEditor.FrameContext): void;
+	/**
+	 * @internal
+	 * @description Closes all open controllers except those marked as `fixed`.
+	 * Iterates through `opendControllers`, calls `controllerClose` on each non-fixed controller,
+	 * hides their forms, and resets the controller state.
+	 * @see offCurrentController - Public method for closing a single controller via component deselect
+	 */
+	_offControllers(): void;
+	currentControllerName: string;
+	/**
+	 * @internal
+	 * @description Synchronizes floating UI element positions with the current scroll offset.
+	 * Called by eventManager when the wysiwyg area is scrolled.
+	 * - Adjusts balloon toolbar position based on scroll offset
+	 * - Closes controllers if scroll target changes
+	 * - Updates line breaker positions
+	 * @param {SunEditor.EventWysiwyg} eventWysiwyg - The scroll event source (Window or element with scroll data)
+	 */
+	_syncScrollPosition(eventWysiwyg: SunEditor.EventWysiwyg): void;
+	/**
+	 * @internal
+	 * @description Repositions all currently open controllers after scroll.
+	 * Called by eventManager during container scroll events.
+	 * - Triggers drag handle repositioning if active
+	 * - Calls _scrollReposition on each open controller
+	 */
+	_repositionControllers(): void;
+	/**
+	 * @internal
+	 * @description Visible controllers
+	 * @param {boolean} value hidden/show
+	 * @param {?boolean} [lineBreakShow] Line break hidden/show (default: Follows the value `value`.)
+	 */
+	_visibleControllers(value: boolean, lineBreakShow?: boolean | null): void;
+	setCurrentControllerContext: any;
+	/**
+	 * @internal
+	 * @description Set the disabled button list
+	 */
+	_initToggleButtons(): void;
+	/**
+	 * @internal
+	 * @description Toggle the disabled state of buttons reserved for Code View.
+	 * @param {boolean} isCodeView
+	 */
+	_toggleCodeViewButtons(isCodeView: boolean): void;
+	/**
+	 * @internal
+	 * @description Toggle the disabled state of buttons when a controller is active.
+	 * @param {boolean} isOpen
+	 */
+	_toggleControllerButtons(isOpen: boolean): void;
+	/**
+	 * @description Check if the button can be executed in the current state (ReadOnly, etc.)
+	 * @param {Node} button
+	 * @returns {boolean}
+	 */
+	isButtonDisabled(button: Node): boolean;
+	/**
+	 * @internal
+	 * @description Updates `placeholder` visibility based on editor state.
+	 * Shows `placeholder` when editor is empty, hides it in code view or when content exists.
+	 * @param {SunEditor.FrameContext} [fc] - Frame context (defaults to current frameContext)
+	 */
+	_updatePlaceholder(fc?: SunEditor.FrameContext): void;
+	/**
+	 * @internal
+	 * @description Synchronizes frame UI state after content changes.
+	 * Coordinates `iframe` height adjustment, `placeholder` visibility, and document type page sync.
+	 * @param {SunEditor.FrameContext} fc - Frame context to synchronize
+	 */
+	_syncFrameState(fc: SunEditor.FrameContext): void;
+	/**
+	 * @internal
+	 * @description Adjusts `iframe` height to match content height.
+	 * Handles `auto`-height `iframe`s and manages scrolling based on `maxHeight` option.
+	 * @param {SunEditor.FrameContext} fc - Frame context containing the `iframe`
+	 */
+	_iframeAutoHeight(fc: SunEditor.FrameContext): void;
+	/**
+	 * @internal
+	 * @description Emits the `onResizeEditor` event when editor height changes.
+	 * Calculates height from `ResizeObserverEntry` if not provided directly.
+	 * @param {SunEditor.FrameContext} fc - Frame context
+	 * @param {number} h - Height value (`-1` to calculate from `resizeObserverEntry`)
+	 * @param {ResizeObserverEntry|null} resizeObserverEntry - `ResizeObserver` entry for height calculation
+	 */
+	_emitResizeEvent(fc: SunEditor.FrameContext, h: number, resizeObserverEntry: ResizeObserverEntry | null): void;
+	init(): void;
+	/**
+	 * @internal
+	 * @description Destroy the UI instance and release memory
+	 */
+	_destroy(): void;
+	opendModal: any;
+	opendBrowser: any;
+	#private;
+}

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

@@ -0,0 +1,104 @@
+import type {} from '../../typedef';
+/**
+ * @typedef {Object} ContextStore
+ *
+ * This object stores **global editor-level UI references** for a SunEditor instance.
+ *
+ * - Primarily manages **toolbar, menu tray, and status bar containers**.
+ * - Used by the editor to control **sticky behavior, sub-toolbars, and global layout**.
+ * - Shared across all frames in a multi-frame editor (unlike FrameContextStore which is per-frame).
+ * -----------------
+ *
+ * === Main UI Containers ===
+ * @property {HTMLElement} menuTray - The **top menu tray** that holds buttons, dropdowns, or custom menus.
+ * @property {HTMLElement} toolbar_main - The **main toolbar** element containing editor actions.
+ * @property {HTMLElement} toolbar_buttonTray - The **container for main toolbar buttons**.
+ * @property {HTMLElement} toolbar_arrow - The **arrow indicator** in the toolbar (used for dropdown/tool menu navigation).
+ * @property {HTMLElement} [toolbar_wrapper] - The **wrapper for the main toolbar and editor frame** (groups UI together).
+ *
+ * === Sub-Toolbar (Contextual/Balloon) ===
+ * @property {HTMLElement} [toolbar_sub_main] - The **sub-toolbar** element (used for contextual or balloon toolbars).
+ * @property {HTMLElement} [toolbar_sub_buttonTray] - The **container for sub-toolbar buttons**.
+ * @property {HTMLElement} [toolbar_sub_arrow] - The **arrow indicator** in the sub-toolbar.
+ * @property {HTMLElement} [toolbar_sub_wrapper] - The **wrapper for the sub-toolbar**, containing its structure.
+ *
+ * === Status Bar ===
+ * @property {HTMLElement} [statusbar_wrapper] - The **wrapper for the status bar** (footer area for resize handles, info, etc.).
+ *
+ * === Sticky Mode Helpers ===
+ * @property {HTMLElement} [_stickyDummy] - A **dummy placeholder** used when the toolbar is in sticky mode (to prevent layout shift).
+ * ================================================================================================================================
+ */
+/**
+ * @description Creates a context map of commonly accessed DOM elements for the editor.
+ * @param {Element} toolbar - Main toolbar element.
+ * @param {?Element} toolbarContainer - Container element for the toolbar.
+ * @param {Element} menuTray - Main menu tray element.
+ * @param {?Element} subbar - Sub-toolbar element.
+ * @param {?Element} statusbarContainer - Status bar container element.
+ * @returns {SunEditor.Context} - A map of key DOM nodes used throughout the editor.
+ */
+export function CreateContext(toolbar: Element, toolbarContainer: Element | null, menuTray: Element, subbar: Element | null, statusbarContainer: Element | null): SunEditor.Context;
+/**
+ * This object stores **global editor-level UI references** for a SunEditor instance.
+ *
+ * - Primarily manages **toolbar, menu tray, and status bar containers**.
+ * - Used by the editor to control **sticky behavior, sub-toolbars, and global layout**.
+ * - Shared across all frames in a multi-frame editor (unlike FrameContextStore which is per-frame).
+ * -----------------
+ *
+ * === Main UI Containers ===
+ */
+export type ContextStore = {
+	/**
+	 * - The **top menu tray** that holds buttons, dropdowns, or custom menus.
+	 */
+	menuTray: HTMLElement;
+	/**
+	 * - The **main toolbar** element containing editor actions.
+	 */
+	toolbar_main: HTMLElement;
+	/**
+	 * - The **container for main toolbar buttons**.
+	 */
+	toolbar_buttonTray: HTMLElement;
+	/**
+	 * - The **arrow indicator** in the toolbar (used for dropdown/tool menu navigation).
+	 */
+	toolbar_arrow: HTMLElement;
+	/**
+	 * - The **wrapper for the main toolbar and editor frame** (groups UI together).
+	 *
+	 * === Sub-Toolbar (Contextual/Balloon) ===
+	 */
+	toolbar_wrapper?: HTMLElement;
+	/**
+	 * - The **sub-toolbar** element (used for contextual or balloon toolbars).
+	 */
+	toolbar_sub_main?: HTMLElement;
+	/**
+	 * - The **container for sub-toolbar buttons**.
+	 */
+	toolbar_sub_buttonTray?: HTMLElement;
+	/**
+	 * - The **arrow indicator** in the sub-toolbar.
+	 */
+	toolbar_sub_arrow?: HTMLElement;
+	/**
+	 * - The **wrapper for the sub-toolbar**, containing its structure.
+	 *
+	 * === Status Bar ===
+	 */
+	toolbar_sub_wrapper?: HTMLElement;
+	/**
+	 * - The **wrapper for the status bar** (footer area for resize handles, info, etc.).
+	 *
+	 * === Sticky Mode Helpers ===
+	 */
+	statusbar_wrapper?: HTMLElement;
+	/**
+	 * - A **dummy placeholder** used when the toolbar is in sticky mode (to prevent layout shift).
+	 * ================================================================================================================================
+	 */
+	_stickyDummy?: HTMLElement;
+};