suneditor 3.2.5 → 3.3.0

package/types/core/logic/panel/menu.d.ts

@@ -118,6 +118,14 @@ declare class Menu {
 	 * @description Closes the currently open dropdown menu.
 	 */
 	dropdownOff(): void;
+	/**
+	 * @description Subscribe to be notified after a dropdown is turned off — i.e. a dropdown-free
+	 * plugin committed and closed itself via {@link dropdownOff}. Mirrors {@link Store#subscribe}:
+	 * returns an unsubscribe function.
+	 * @param {() => void} callback
+	 * @returns {() => void} Unsubscribe function
+	 */
+	subscribeDropdownOff(callback: () => void): () => void;
 	/**
 	 * @description Shows a previously hidden dropdown menu that is still in `on` state.
 	 * - Only works when a dropdown is active (`currentButton` exists)

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

@@ -231,6 +231,23 @@ declare class UIManager {
 	 * @param {SunEditor.FrameContext} [fc] - Frame context (defaults to current frameContext)
 	 */
 	_updatePlaceholder(fc?: SunEditor.FrameContext): void;
+	/**
+	 * @description Resolves the per-line placeholder text for an empty line from the `placeholder_line` option.
+	 * - String option: one hint for every empty line — except list cells and table cells (backward compatible).
+	 * - Object option: keyed by tag name or a category sentinel matching the editor's format classification
+	 *   ({@link Format#isNormalLine}, `isBrLine`, `isClosureBrLine`, `isBlock`, `isClosureBlock`, list cells).
+	 * @param {?Node} line - The (empty) line element.
+	 * @param {string|Object<string, string>} opt - The `placeholder_line` option value.
+	 * @returns {string} The resolved placeholder text (`''` = none).
+	 */
+	resolveLinePlaceholder(
+		line: Node | null,
+		opt:
+			| string
+			| {
+					[x: string]: string;
+			  },
+	): string;
 	/**
 	 * @internal
 	 * @description Synchronizes frame UI state after content changes.

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

@@ -33,7 +33,7 @@ import type {} from '../../typedef';
  * @property {HTMLTextAreaElement} markdown - Markdown view editing element (a <textarea>).
  * @property {HTMLTextAreaElement} markdownNumbers - Element displaying line numbers in markdown view mode.
  * @property {HTMLElement} placeholder - Placeholder element shown when the editor is empty.
- * @property {string} placeholder_line - Per-line placeholder text, rendered via a `::before` on the focused empty line.
+ * @property {string|Object<string, string>} placeholder_line - Per-line placeholder text, rendered via a `::before` on the focused empty line.
  * @property {HTMLElement} statusbar - Editor status bar element (for resizing, info, etc.).
  * @property {HTMLElement} navigation - Navigation element (e.g., for outline or bookmarks).
  * @property {HTMLElement} charWrapper - Wrapper for the character counter element.
@@ -216,7 +216,11 @@ export type FrameContextStore = {
 	/**
 	 * - Per-line placeholder text, rendered via a `::before` on the focused empty line.
 	 */
-	placeholder_line: string;
+	placeholder_line:
+		| string
+		| {
+				[x: string]: string;
+		  };
 	/**
 	 * - Editor status bar element (for resizing, info, etc.).
 	 */

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

@@ -56,8 +56,22 @@ export namespace DEFAULTS {
  * === Content & Editing ===
  * @property {string} [value=""] - Initial value for the editor.
  * @property {string} [placeholder=""] - Placeholder text shown when the whole editor is empty.
- * @property {string} [placeholder_line=""] - per-line placeholder shown on the focused
+ * @property {string|Object<string, string>} [placeholder_line=""] - per-line placeholder shown on the focused
  * line when that line is empty. Takes priority over `placeholder` while a line is focused.
+ * - **string**: one hint for every empty line (list cells and table cells excluded).
+ * - **object**: per-type hints keyed by tag name (`p`, `pre`, `blockquote`, ...) or a category sentinel
+ * matching the editor's format classification: `@line`, `@normalLine`, `@list`, `@brLine`, `@closureBrLine`,
+ * `@block`, `@closureBlock`. Resolved most-specific → least, like `tagStyles`:
+ * `<tag>` → `@list` → `@closureBrLine` → `@brLine` → block container (`<blockTag>` → `@closureBlock` → `@block`)
+ * → `@normalLine` → `@line`. A missing key = no placeholder for that type; an explicit `''` suppresses it.
+ * ```js
+ * // one hint everywhere
+ * placeholder_line: 'Type something…'
+ * // per-type
+ * placeholder_line: {
+ *   '@normalLine': 'Type…', '@list': 'List item', '@block': 'Quote…', '@closureBlock': 'Cell', pre: '// code'
+ * }
+ * ```
  * @property {Object<string, string>} [editableFrameAttributes={spellcheck: "false"}] - Attributes for the editable frame[.sun-editor-editable].
  * ```js
  * { editableFrameAttributes: { spellcheck: 'true', autocomplete: 'on' } }
@@ -403,6 +417,13 @@ export namespace DEFAULTS {
  * - Formats that include `line`, such as "Quote", still operate on a `line` basis.
  * - suneditor processes work in `line` units.
  * - When set to `br`, performance may decrease when editing a lot of data.
+ * @property {boolean} [lineBreakClearStyle=false] - When `true`, pressing Enter at the **end** of a line
+ * starts a fresh line that does not carry the caret's inline style nodes (e.g. bold/italic/color spans, links);
+ * the line-level element and its attributes are preserved.
+ * Only affects the end-of-line case — mid-line splits, start-of-line breaks, and Shift+Enter are unchanged.
+ * ```js
+ * { lineBreakClearStyle: true }
+ * ```
  * @property {string} [lineAttrReset=""] - Line properties that should be reset when changing lines. Delimiter: `"|"`.
  * ```js
  * { lineAttrReset: 'id|name' }
@@ -453,12 +474,16 @@ export namespace DEFAULTS {
  * { toolbar_innerWidth: 'auto' }
  * ```
  * @property {?HTMLElement} [toolbar_container] - Container element for the toolbar.
- * @property {number|{top: number, offset: number}} [toolbar_sticky=0] - Enables sticky toolbar.
+ * @property {number|{top: number, offset?: number, position?: "sticky"|"fixed"}} [toolbar_sticky=0] - Enables sticky toolbar.
  * - `number`: Sets the sticky top position (px). Use `-1` to disable sticky.
  * - `{top, offset}`: `top` is the sticky position when the page header is visible.
  * - `offset` is the sticky position when a virtual keyboard shifts the viewport (e.g., on tablets, touch devices).
  * - When the virtual keyboard is active, `offset` replaces `top` so the toolbar doesn't leave a gap
  * - for a page header that has scrolled out of view. Default `offset` is `0`.
+ * - `position` (default `"sticky"`): the positioning engine.
+ * - `"sticky"` uses native CSS `position: sticky` (with a JS `position: fixed` fallback where unsupported).
+ * `"fixed"` forces the JS `position: fixed` engine
+ * - even when CSS sticky is supported — for environments where CSS sticky silently misbehaves and can't be
  * ```js
  * // Basic usage — sticky at top with 0px offset
  * toolbar_sticky: 0
@@ -468,6 +493,9 @@ export namespace DEFAULTS {
  *
  * // 92px header on desktop, but 0px when virtual keyboard pushes the viewport
  * toolbar_sticky: { top: 92, offset: 0 }
+ *
+ * // Force the JS position:fixed engine (CSS sticky unreliable in this environment)
+ * toolbar_sticky: { top: 0, position: 'fixed' }
  * ```
  * @property {boolean} [toolbar_hide=false] - Hides toolbar initially.
  * @property {Object} [subToolbar={}] - Sub-toolbar configuration. A secondary toolbar that appears on text selection.
@@ -669,8 +697,26 @@ export type EditorFrameOptions = {
 	/**
 	 * - per-line placeholder shown on the focused
 	 * line when that line is empty. Takes priority over `placeholder` while a line is focused.
+	 * - **string**: one hint for every empty line (list cells and table cells excluded).
+	 * - **object**: per-type hints keyed by tag name (`p`, `pre`, `blockquote`, ...) or a category sentinel
+	 * matching the editor's format classification: `@line`, `@normalLine`, `@list`, `@brLine`, `@closureBrLine`,
+	 * `@block`, `@closureBlock`. Resolved most-specific → least, like `tagStyles`:
+	 * `<tag>` → `@list` → `@closureBrLine` → `@brLine` → block container (`<blockTag>` → `@closureBlock` → `@block`)
+	 * → `@normalLine` → `@line`. A missing key = no placeholder for that type; an explicit `''` suppresses it.
+	 * ```js
+	 * // one hint everywhere
+	 * placeholder_line: 'Type something…'
+	 * // per-type
+	 * placeholder_line: {
+	 * '@normalLine': 'Type…', '@list': 'List item', '@block': 'Quote…', '@closureBlock': 'Cell', pre: '// code'
+	 * }
+	 * ```
 	 */
-	placeholder_line?: string;
+	placeholder_line?:
+		| string
+		| {
+				[x: string]: string;
+		  };
 	/**
 	 * - Attributes for the editable frame[.sun-editor-editable].
 	 * ```js
@@ -1232,6 +1278,16 @@ export type EditorBaseOptions = {
 	 * - When set to `br`, performance may decrease when editing a lot of data.
 	 */
 	defaultLineBreakFormat?: 'line' | 'br';
+	/**
+	 * - When `true`, pressing Enter at the **end** of a line
+	 * starts a fresh line that does not carry the caret's inline style nodes (e.g. bold/italic/color spans, links);
+	 * the line-level element and its attributes are preserved.
+	 * Only affects the end-of-line case — mid-line splits, start-of-line breaks, and Shift+Enter are unchanged.
+	 * ```js
+	 * { lineBreakClearStyle: true }
+	 * ```
+	 */
+	lineBreakClearStyle?: boolean;
 	/**
 	 * - Line properties that should be reset when changing lines. Delimiter: `"|"`.
 	 * ```js
@@ -1325,6 +1381,10 @@ export type EditorBaseOptions = {
 	 * - `offset` is the sticky position when a virtual keyboard shifts the viewport (e.g., on tablets, touch devices).
 	 * - When the virtual keyboard is active, `offset` replaces `top` so the toolbar doesn't leave a gap
 	 * - for a page header that has scrolled out of view. Default `offset` is `0`.
+	 * - `position` (default `"sticky"`): the positioning engine.
+	 * - `"sticky"` uses native CSS `position: sticky` (with a JS `position: fixed` fallback where unsupported).
+	 * `"fixed"` forces the JS `position: fixed` engine
+	 * - even when CSS sticky is supported — for environments where CSS sticky silently misbehaves and can't be
 	 * ```js
 	 * // Basic usage — sticky at top with 0px offset
 	 * toolbar_sticky: 0
@@ -1334,13 +1394,17 @@ export type EditorBaseOptions = {
 	 *
 	 * // 92px header on desktop, but 0px when virtual keyboard pushes the viewport
 	 * toolbar_sticky: { top: 92, offset: 0 }
+	 *
+	 * // Force the JS position:fixed engine (CSS sticky unreliable in this environment)
+	 * toolbar_sticky: { top: 0, position: 'fixed' }
 	 * ```
 	 */
 	toolbar_sticky?:
 		| number
 		| {
 				top: number;
-				offset: number;
+				offset?: number;
+				position?: 'sticky' | 'fixed';
 		  };
 	/**
 	 * - Hides toolbar initially.
@@ -1654,6 +1718,7 @@ export type TransformedOptionKeys =
 	| 'toolbar_container'
 	| '_toolbar_sticky'
 	| '_toolbar_sticky_offset'
+	| '_toolbar_sticky_fixed'
 	| 'strictMode'
 	| 'lineAttrReset';
 export type StrictModeOptions = {
@@ -1707,6 +1772,7 @@ export type TransformedOptions = {
 	toolbar_container: HTMLElement | null;
 	_toolbar_sticky: number;
 	_toolbar_sticky_offset: number;
+	_toolbar_sticky_fixed: boolean;
 	strictMode: StrictModeOptions;
 	lineAttrReset: string[];
 };