suneditor 3.1.3 → 3.2.0

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

@@ -25,6 +25,8 @@ export namespace DEFAULTS {
 	};
 	let CONTENT_STYLES: string;
 	let TAG_STYLES: {
+		'@text': string;
+		'@line': string;
 		'table|th|td': string;
 		'table|td': string;
 		tr: string;
@@ -36,8 +38,6 @@ export namespace DEFAULTS {
 		'img|video|iframe': string;
 		hr: string;
 	};
-	let SPAN_STYLES: string;
-	let LINE_STYLES: string;
 	let RETAIN_STYLE_MODE: string[];
 }
 /**
@@ -54,7 +54,9 @@ export namespace DEFAULTS {
  *
  * === Content & Editing ===
  * @property {string} [value=""] - Initial value for the editor.
- * @property {string} [placeholder=""] - Placeholder text.
+ * @property {string} [placeholder=""] - Placeholder text shown when the whole editor is empty.
+ * @property {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.
  * @property {Object<string, string>} [editableFrameAttributes={spellcheck: "false"}] - Attributes for the editable frame[.sun-editor-editable].
  * ```js
  * { editableFrameAttributes: { spellcheck: 'true', autocomplete: 'on' } }
@@ -65,6 +67,13 @@ export namespace DEFAULTS {
  * @property {string|number} [width="100%"] - Width for the editor.
  * @property {string|number} [minWidth=""] - Min width for the editor.
  * @property {string|number} [maxWidth=""] - Max width for the editor.
+ * @property {string} [innerWidth=""] - Optional max-width for the editor body (`.se-wrapper`).
+ * - **CSS length** (`"740px"`, `"60ch"`): editor body's content is clamped to this width and centered horizontally; scroll container stays full width (scrollbar at the outer edge, wheel/touch active over the whole area).
+ * - **`"auto"`** or **empty string** (default): no constraint — natural full-width layout with default content padding.
+ * - In `blockHandle` mode, the gutter handle tracks the centered text band.
+ * ```js
+ * { innerWidth: '740px' }
+ * ```
  * @property {string|number} [height="auto"] - Height for the editor.
  * @property {string|number} [minHeight=""] - Min height for the editor.
  * @property {string|number} [maxHeight=""] - Max height for the editor.
@@ -233,6 +242,22 @@ export namespace DEFAULTS {
  * === Modes & Themes ===
  * @property {boolean} [v2Migration=false] - Enables migration mode for SunEditor v2.
  * @property {"classic"|"inline"|"balloon"|"balloon-always"|"classic:bottom"|"inline:bottom"} [mode="classic"] - Toolbar mode: `classic`, `inline`, `balloon`, `balloon-always`. Append `:bottom` to place toolbar at the bottom (e.g. `classic:bottom`, `inline:bottom`).
+ * @property {Object} [blockHandle] - Block handle configuration. When provided, a per-line block handle UI is shown. Works independently of `mode`.
+ * @property {Array<string | { title: string, icon?: string, action: (deps: SunEditor.Deps, ctx: { block: HTMLElement }) => void }>} [blockHandle.menu] - Menu entries.
+ * - **String entries** — resolved via `ResolveButton`. Accepts the same values as toolbar `buttonList`:
+ *   - **Block format keys**: `p`, `h1`-`h6`, `heading` (H1-H6 submenu), `ul`, `ol`, `list` (UL/OL submenu), `blockquote`, `pre`.
+ *   - **Plugin names**: Any registered plugin name (e.g. `blockStyle`, `align`, `image`, `link`). Dropdown plugins display their items as a submenu. Modal plugins open the modal on click.
+ *   - **Built-in commands**: `bold`, `italic`, `underline`, `strike`, `undo`, `redo`, etc.
+ * - **Custom item objects** — `{ title, icon?, action }`. `icon` is an icon key from `$.icons` or a raw `<svg>` HTML string; `action` is invoked with `($, { block })`.
+ * - Defaults to `['p', 'heading', 'list', 'blockquote', 'pre']`.
+ * ```js
+ * blockHandle: {
+ *   menu: [
+ *     'p', 'heading', 'blockStyle',
+ *     { title: 'Duplicate', icon: 'copy', action: ($, { block }) => block.after(block.cloneNode(true)) },
+ *   ],
+ * }
+ * ```
  * @property {string} [type=""] - Editor type. Use `"document"` for a document-style layout, with optional sub-types after `:`.
  * ```js
  * // type
@@ -263,7 +288,7 @@ export namespace DEFAULTS {
  * - `classFilter`: Filters disallowed CSS class names (`allowedClassName`)
  * - `textStyleTagFilter`: Filters text style tags (b, i, u, span, etc.)
  * - `attrFilter`: Filters disallowed HTML attributes (`attributeWhitelist`/`attributeBlacklist`)
- * - `styleFilter`: Filters disallowed inline styles (`spanStyles`/`lineStyles`/`allUsedStyles`)
+ * - `styleFilter`: Filters disallowed inline styles (per-tag from `tagStyles`)
  * ```js
  * // disable only attribute and style filters
  * {
@@ -339,19 +364,23 @@ export namespace DEFAULTS {
  * ```js
  * { allUsedStyles: 'color|background-color|text-shadow' }
  * ```
- * @property {Object<string, string>} [tagStyles={}] - Specifies allowed styles for HTML tags. Key is tag name(s), value is pipe-delimited allowed styles.
+ * @property {Object<string, string>} [tagStyles={}] - Specifies allowed CSS styles per HTML tag.
+ * - Key is a tag name, multiple tags joined with `|`, or a category sentinel (`@text`, `@line`).
+ * - Value is a pipe-delimited list of allowed style names.
+ * - Resolution order when filtering an element: explicit tag entry → `@line` (for formatLine elements) → `@text` (for textStyleTags).
+ * - An explicit tag entry **replaces** the category default — include category styles in the value if you want both.
+ * - Merged with {@link DEFAULTS.TAG_STYLES}; user-supplied keys win.
  * ```js
  * {
  *   tagStyles: {
- *     'table|td': 'border|color|background-color',
- *     hr: 'border-top'
+ *     '@text': 'color|font-size|background-color',  // default for span, b, i, em, ...
+ *     '@line': 'text-align|margin|line-height',     // default for p, h1-h6, div, li, ...
+ *     'table|td': 'border|color|background-color',  // per-tag whitelist
+ *     div: 'color',                                   // explicit override; ignores `@line` default
+ *     hr: 'border-top',
  *   }
  * }
  * ```
- * @property {string} [spanStyles=CONSTANTS.SPAN_STYLES] - Specifies allowed styles for the `span` tag.
- * - The default follows {@link DEFAULTS.SPAN_STYLES}
- * @property {string} [lineStyles=CONSTANTS.LINE_STYLES] - Specifies allowed styles for the `line` element (p..).
- * - The default follows {@link DEFAULTS.LINE_STYLES}
  * @property {Array<string>} [fontSizeUnits=CONSTANTS.SIZE_UNITS] - Allowed font size units.
  * - The default follows {@link DEFAULTS.SIZE_UNITS}
  * @property {"repeat"|"always"|"none"} [retainStyleMode="repeat"] - Determines how inline elements (e.g. `<span>`, `<strong>`) are handled when deleting text.
@@ -412,6 +441,15 @@ export namespace DEFAULTS {
  * @property {boolean} [syncTabIndent=true] - Synchronizes tab indent with spaces.
  * @property {boolean} [tabDisable=false] - Disables tab key input.
  * @property {string} [toolbar_width="auto"] - Toolbar width.
+ * @property {string} [toolbar_innerWidth=""] - Center the toolbar's button row (`.se-btn-tray`) horizontally.
+ * - **CSS length** (e.g. `"500px"`, `"740px"`, `"60ch"`): toolbar background spans full width while the button row is capped at that width and centered. If buttons fit, the row stays on a single line; if they exceed the cap, they wrap inside it.
+ * - **`"auto"`**: no cap — the row is sized to its content and simply centered.
+ * - **Empty string** (default): no constraint.
+ * - **Note on `responsiveButtonList`**: thresholds compare against the toolbar's full width, not the band. When this option is set, calibrate `responsiveButtonList` keys around the toolbar size you actually want each button set to kick in at.
+ * ```js
+ * { toolbar_innerWidth: '740px' }
+ * { toolbar_innerWidth: 'auto' }
+ * ```
  * @property {?HTMLElement} [toolbar_container] - Container element for the toolbar.
  * @property {number|{top: number, offset: number}} [toolbar_sticky=0] - Enables sticky toolbar.
  * - `number`: Sets the sticky top position (px). Use `-1` to disable sticky.
@@ -546,6 +584,7 @@ export namespace DEFAULTS {
  * @property {import('../../plugins/modal/link.js').LinkPluginOptions} [link]
  * @property {import('../../plugins/modal/math.js').MathPluginOptions} [math]
  * @property {import('../../plugins/dropdown/paragraphStyle.js').ParagraphStylePluginOptions} [paragraphStyle]
+ * @property {import('../../plugins/field/slashCommand.js').SlashCommandPluginOptions} [slashCommand]
  * @property {import('../../plugins/dropdown/table/index.js').TablePluginOptions} [table]
  * @property {import('../../plugins/dropdown/template.js').TemplatePluginOptions} [template]
  * @property {import('../../plugins/dropdown/textStyle.js').TextStylePluginOptions} [textStyle]
@@ -570,8 +609,6 @@ export namespace DEFAULTS {
  * @property {string[]} [_reverseCommandArray] - Internal key shortcut matcher for reverse commands.
  * @property {string} [_subMode] - Sub toolbar mode (e.g., `balloon`).
  * @property {string[]} [_textStyleTags] - Tag names used for text styling, plus span/li.
- * @property {RegExp} [_textStylesRegExp] - Regex to match inline styles (e.g., fontSize, color).
- * @property {RegExp} [_lineStylesRegExp] - Regex to match line styles (e.g., text-align, padding).
  * @property {Object<string, string>} [_defaultStyleTagMap] - Mapping HTML tag => standard tag.
  * @property {Object<string, string>} [_styleCommandMap] - Mapping HTML tag => command (e.g., bold, underline).
  * @property {Object<string, string>} [_defaultTagCommand] - Mapping command => preferred tag.
@@ -624,9 +661,14 @@ export type EditorFrameOptions = {
 	 */
 	value?: string;
 	/**
-	 * - Placeholder text.
+	 * - Placeholder text shown when the whole editor is empty.
 	 */
 	placeholder?: string;
+	/**
+	 * - per-line placeholder shown on the focused
+	 * line when that line is empty. Takes priority over `placeholder` while a line is focused.
+	 */
+	placeholder_line?: string;
 	/**
 	 * - Attributes for the editable frame[.sun-editor-editable].
 	 * ```js
@@ -651,6 +693,16 @@ export type EditorFrameOptions = {
 	 * - Max width for the editor.
 	 */
 	maxWidth?: string | number;
+	/**
+	 * - Optional max-width for the editor body (`.se-wrapper`).
+	 * - **CSS length** (`"740px"`, `"60ch"`): editor body's content is clamped to this width and centered horizontally; scroll container stays full width (scrollbar at the outer edge, wheel/touch active over the whole area).
+	 * - **`"auto"`** or **empty string** (default): no constraint — natural full-width layout with default content padding.
+	 * - In `blockHandle` mode, the gutter handle tracks the centered text band.
+	 * ```js
+	 * { innerWidth: '740px' }
+	 * ```
+	 */
+	innerWidth?: string;
 	/**
 	 * - Height for the editor.
 	 */
@@ -939,6 +991,24 @@ export type EditorBaseOptions = {
 	 * - Toolbar mode: `classic`, `inline`, `balloon`, `balloon-always`. Append `:bottom` to place toolbar at the bottom (e.g. `classic:bottom`, `inline:bottom`).
 	 */
 	mode?: 'classic' | 'inline' | 'balloon' | 'balloon-always' | 'classic:bottom' | 'inline:bottom';
+	/**
+	 * - Block handle configuration. When provided, a per-line block handle UI is shown. Works independently of `mode`.
+	 */
+	blockHandle?: {
+		menu?: Array<
+			| string
+			| {
+					title: string;
+					icon?: string;
+					action: (
+						deps: SunEditor.Deps,
+						ctx: {
+							block: HTMLElement;
+						},
+					) => void;
+			  }
+		>;
+	};
 	/**
 	 * - Editor type. Use `"document"` for a document-style layout, with optional sub-types after `:`.
 	 * ```js
@@ -985,7 +1055,7 @@ export type EditorBaseOptions = {
 	 * - `classFilter`: Filters disallowed CSS class names (`allowedClassName`)
 	 * - `textStyleTagFilter`: Filters text style tags (b, i, u, span, etc.)
 	 * - `attrFilter`: Filters disallowed HTML attributes (`attributeWhitelist`/`attributeBlacklist`)
-	 * - `styleFilter`: Filters disallowed inline styles (`spanStyles`/`lineStyles`/`allUsedStyles`)
+	 * - `styleFilter`: Filters disallowed inline styles (per-tag from `tagStyles`)
 	 * ```js
 	 * // disable only attribute and style filters
 	 * {
@@ -1106,12 +1176,20 @@ export type EditorBaseOptions = {
 	 */
 	allUsedStyles?: string;
 	/**
-	 * - Specifies allowed styles for HTML tags. Key is tag name(s), value is pipe-delimited allowed styles.
+	 * - Specifies allowed CSS styles per HTML tag.
+	 * - Key is a tag name, multiple tags joined with `|`, or a category sentinel (`@text`, `@line`).
+	 * - Value is a pipe-delimited list of allowed style names.
+	 * - Resolution order when filtering an element: explicit tag entry → `@line` (for formatLine elements) → `@text` (for textStyleTags).
+	 * - An explicit tag entry **replaces** the category default — include category styles in the value if you want both.
+	 * - Merged with {@link DEFAULTS.TAG_STYLES}; user-supplied keys win.
 	 * ```js
 	 * {
 	 * tagStyles: {
-	 * 'table|td': 'border|color|background-color',
-	 * hr: 'border-top'
+	 * '@text': 'color|font-size|background-color',  // default for span, b, i, em, ...
+	 * '@line': 'text-align|margin|line-height',     // default for p, h1-h6, div, li, ...
+	 * 'table|td': 'border|color|background-color',  // per-tag whitelist
+	 * div: 'color',                                   // explicit override; ignores `@line` default
+	 * hr: 'border-top',
 	 * }
 	 * }
 	 * ```
@@ -1119,16 +1197,6 @@ export type EditorBaseOptions = {
 	tagStyles?: {
 		[x: string]: string;
 	};
-	/**
-	 * - Specifies allowed styles for the `span` tag.
-	 * - The default follows {@link DEFAULTS.SPAN_STYLES}
-	 */
-	spanStyles?: string;
-	/**
-	 * - Specifies allowed styles for the `line` element (p..).
-	 * - The default follows {@link DEFAULTS.LINE_STYLES}
-	 */
-	lineStyles?: string;
 	/**
 	 * - Allowed font size units.
 	 * - The default follows {@link DEFAULTS.SIZE_UNITS}
@@ -1231,6 +1299,18 @@ export type EditorBaseOptions = {
 	 * - Toolbar width.
 	 */
 	toolbar_width?: string;
+	/**
+	 * - Center the toolbar's button row (`.se-btn-tray`) horizontally.
+	 * - **CSS length** (e.g. `"500px"`, `"740px"`, `"60ch"`): toolbar background spans full width while the button row is capped at that width and centered. If buttons fit, the row stays on a single line; if they exceed the cap, they wrap inside it.
+	 * - **`"auto"`**: no cap — the row is sized to its content and simply centered.
+	 * - **Empty string** (default): no constraint.
+	 * - **Note on `responsiveButtonList`**: thresholds compare against the toolbar's full width, not the band. When this option is set, calibrate `responsiveButtonList` keys around the toolbar size you actually want each button set to kick in at.
+	 * ```js
+	 * { toolbar_innerWidth: '740px' }
+	 * { toolbar_innerWidth: 'auto' }
+	 * ```
+	 */
+	toolbar_innerWidth?: string;
 	/**
 	 * - Container element for the toolbar.
 	 */
@@ -1450,6 +1530,7 @@ export type EditorBaseOptions = {
 	link?: import('../../plugins/modal/link.js').LinkPluginOptions;
 	math?: import('../../plugins/modal/math.js').MathPluginOptions;
 	paragraphStyle?: import('../../plugins/dropdown/paragraphStyle.js').ParagraphStylePluginOptions;
+	slashCommand?: import('../../plugins/field/slashCommand.js').SlashCommandPluginOptions;
 	table?: import('../../plugins/dropdown/table/index.js').TablePluginOptions;
 	template?: import('../../plugins/dropdown/template.js').TemplatePluginOptions;
 	textStyle?: import('../../plugins/dropdown/textStyle.js').TextStylePluginOptions;
@@ -1501,14 +1582,6 @@ export type InternalBaseOptions = {
 	 * - Tag names used for text styling, plus span/li.
 	 */
 	_textStyleTags?: string[];
-	/**
-	 * - Regex to match inline styles (e.g., fontSize, color).
-	 */
-	_textStylesRegExp?: RegExp;
-	/**
-	 * - Regex to match line styles (e.g., text-align, padding).
-	 */
-	_lineStylesRegExp?: RegExp;
 	/**
 	 * - Mapping HTML tag => standard tag.
 	 */
@@ -1602,7 +1675,7 @@ export type StrictModeOptions = {
 	 */
 	attrFilter: boolean;
 	/**
-	 * - Filters disallowed inline styles (`spanStyles`/`lineStyles`/`allUsedStyles`)
+	 * - Filters disallowed inline styles (per-tag from `tagStyles`)
 	 */
 	styleFilter: boolean;
 };

package/types/core/section/constructor.d.ts

@@ -8,7 +8,14 @@ import type {} from '../../typedef';
  * @param {Array} rc `_reverseCommandArray` option
  * @param {Set} reverseKeys Reverse key array
  */
-export function CreateShortcuts(command: string, button: Element | null, values: Array<string>, keyMap: Map<string, any>, rc: any[], reverseKeys: Set<any>): void;
+export function CreateShortcuts(
+	command: string,
+	button: Element | null,
+	values: Array<string>,
+	keyMap: Map<string, any>,
+	rc: any[],
+	reverseKeys: Set<any>,
+): void;
 /**
  * @typedef {Object} InitOptionsReturnType
  * @property {Map<string, *>} o - Processed base options (`Map` containing {@link AllBaseOptions_constructor} keys)
@@ -55,6 +62,36 @@ export function CreateStatusbar(
 	wordWrapper: HTMLElement;
 	wordCounter: HTMLElement;
 };
+/**
+ * @description Resolves a button key to its toolbar metadata.
+ * Checks plugins first, then falls back to the default button list.
+ * Same resolution logic as `CreateToolBar`.
+ * @param {string} key Button name
+ * @param {?Object<string, *>} plugins Plugin instances
+ * @param {SunEditor.Options} options Options map
+ * @param {Object<string, string>} icons Icons
+ * @param {Object<string, string>} lang Language object
+ * @returns {{className: string, title: string, command: string, type: string, icon: string}|null}
+ */
+export function ResolveButton(
+	key: string,
+	plugins: {
+		[x: string]: any;
+	} | null,
+	options: SunEditor.Options,
+	icons: {
+		[x: string]: string;
+	},
+	lang: {
+		[x: string]: string;
+	},
+): {
+	className: string;
+	title: string;
+	command: string;
+	type: string;
+	icon: string;
+} | null;
 /**
  * @description Update a button state, attributes, and icons
  * @param {?HTMLElement} element Button element