@brandup/ui-richeditor 1.0.36 → 1.0.38

package/source/richeditor.ts

@@ -4,24 +4,31 @@ import { DOM, UIElementBound } from "@brandup/ui";
 import {
 	ALL_FORMAT_TOOLS,
 	HOTKEY_TOOLS,
+	clearAllFormat,
+	clearFormat,
 	defaultFormatMarkers,
 	deserialize,
 	ensureParagraphs,
+	hasAnyFormatting,
+	hasFormatting,
 	insertFormattedText,
 	isFormatActive,
+	mapCharOffset,
 	normalizeParagraphs,
 	normalizeWhitespace,
 	restoreSelection,
 	selectionCharBounds,
 	serialize,
 	toggleFormat,
+	type EditorAction,
 	type FormatMarkers,
 	type FormatStorage,
+	type ParagraphMode,
 	type FormatTool,
 } from "./format";
 import {
 	caretToEnd,
-	expandSelectionToWords,
+	expandRangeToWords,
 	insertParagraph,
 	insertPastedParagraphs,
 	insertSoftBreak,
@@ -68,6 +75,8 @@ export interface RichEditorOptions {
 	format?: boolean;
 	/** Состав инструментов (по умолчанию все). */
 	tools?: FormatTool[];
+	/** Кнопки действий в панели: очистка форматирования, отмена, повтор (по умолчанию нет). */
+	actions?: EditorAction[];
 	/** Формат хранения значения при форматировании. */
 	storage?: FormatStorage;
 	/** Переопределения markdown-маркеров. */
@@ -76,6 +85,8 @@ export interface RichEditorOptions {
 	placeholder?: string | null;
 	/** Многострочный режим. */
 	multiline?: boolean;
+	/** Что делает Enter: новый абзац (по умолчанию) или мягкий перенос, как в мессенджерах. */
+	paragraph?: ParagraphMode;
 	/** Только для чтения — запрещает ввод и изменение текста (но не выделение/копирование). */
 	readonly?: boolean;
 	/** Контейнер для панели форматирования; по умолчанию document.body (position: fixed над редактором). */
@@ -107,9 +118,11 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 	readonly editable: HTMLElement;
 	readonly format: boolean;
 	readonly formatTools: FormatTool[];
+	readonly editorActions: EditorAction[];
 	readonly formatStorage: FormatStorage;
 	readonly formatMarkers: FormatMarkers;
 	readonly multiline: boolean;
+	readonly paragraph: ParagraphMode;
 	readonly toolbarContainer: HTMLElement | null;
 
 	private __opts: RichEditorOptions;
@@ -125,6 +138,8 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 		const readonly = !!options.readonly;
 		// форматирование недоступно в режиме только для чтения
 		const tools = format && !readonly ? (options.tools ?? ALL_FORMAT_TOOLS.slice()) : [];
+		// действия подключаются явно — иначе панель у существующих хостов молча обзавелась бы кнопками
+		const actions = format && !readonly ? (options.actions ?? []) : [];
 
 		// тулбар общий и живёт в body (см. ./toolbar), поэтому обёртка не нужна —
 		// привязываем UIElement прямо к переданному элементу, он же и редактируемый
@@ -136,9 +151,11 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 		this.__opts = options;
 		this.format = format;
 		this.formatTools = tools;
+		this.editorActions = actions;
 		this.formatStorage = options.storage === "markdown" ? "markdown" : "html";
 		this.formatMarkers = Object.assign(defaultFormatMarkers(), options.markers);
 		this.multiline = multiline;
+		this.paragraph = options.paragraph ?? "block";
 		this.toolbarContainer = options.toolbarContainer ?? null;
 		// история включается вместе с форматированием
 		this.__history = format ? new EditorHistory(editable) : null;
@@ -177,11 +194,53 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 	}
 
 	setValue(value: string): void {
+		// каретка внутри относилась к прежнему содержимому — после замены ставим её в конец
+		const hadCaret = !!this.__innerSelection();
+
 		this.__render(value ?? "");
 		this.__normalize(false);
+		if (hadCaret) caretToEnd(this.editable, this.multiline);
+
 		this.__emitChange();
 	}
 
+	/**
+	 * Вставляет текст в каретку (или вместо выделения) с учётом ожидающих форматов режима набора.
+	 * Каретка сохраняется и после потери фокуса, поэтому метод работает и при вызове из кода —
+	 * например, кнопкой панели, которая не должна забирать фокус у редактора.
+	 */
+	insertText(text: string): void {
+		if (this.readonly || !text || !this.__innerSelection()) return;
+
+		// вставка — такой же ввод, как с клавиатуры, поэтому проходит через filterChar хоста
+		// (ограничения по типу поля и длине). Обход символов идёт по кодпойнтам, чтобы эмодзи
+		// проверялся целиком; длина сверяется с текущим содержимым, так что многосимвольная
+		// вставка ограничивается по первому символу — для одного символа проверка точная.
+		const filterChar = this.__opts.filterChar;
+		if (filterChar && !Array.from(text).every((char) => filterChar(char))) {
+			this.__reject();
+			return;
+		}
+
+		this.__history?.record("op");
+		this.__insertText(text);
+	}
+
+	/**
+	 * Показать панель вставки смайлика у своей кнопки — когда она живёт не в тулбаре, а в разметке
+	 * хоста (например справа от поля ввода). Вызывать из обработчика `click`, погасив всплытие:
+	 * иначе попап закроется тем же кликом, которым открылся.
+	 *
+	 * @param initiator Кнопка, у которой показывается панель.
+	 * @param container Куда монтировать панель; по умолчанию — родитель кнопки.
+	 */
+	openEmojiPicker(initiator: HTMLElement, container?: HTMLElement): void {
+		if (this.readonly) return;
+
+		const target = container ?? initiator.parentElement;
+		if (target) formatToolbar.openEmoji(this, initiator, target);
+	}
+
 	getLength(): number {
 		// textContent (а не innerText) корректно считает multiline и работает в jsdom
 		return this.editable.textContent?.length ?? 0;
@@ -195,22 +254,46 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 		this.on(CHANGE_EVENT, handler);
 	}
 
-	/** Переключить форматирование инструмента (вызывается общим тулбаром и хоткеями). */
-	applyFormat(tool: FormatTool): void {
-		if (!this.format || this.readonly || !this.formatTools.includes(tool)) return;
-
+	/**
+	 * Выделение, если оно находится внутри этого редактора. Браузер сохраняет выделение и после
+	 * blur, поэтому проверка работает и когда фокус ушёл на кнопку страницы.
+	 */
+	private __innerSelection(): Selection | null {
 		const selection = window.getSelection();
-		if (!selection || selection.rangeCount === 0) return;
-		if (!this.editable.contains(selection.anchorNode)) return;
+		if (!selection || selection.rangeCount === 0 || !this.editable.contains(selection.anchorNode)) return null;
 
-		// запоминаем исходное выделение, чтобы вернуть его после форматирования
-		const original = selectionCharBounds(this.editable, selection.getRangeAt(0));
+		return selection;
+	}
 
-		// форматируем слова целиком: и при курсоре без выделения, и при выделении части слова
-		expandSelectionToWords(this.editable, selection);
+	/**
+	 * Цель правки форматирования: выделение, расширенное до целых слов, плюс исходные границы
+	 * для восстановления. Диапазон отдельный от выделения — пока операция не решила, что будет
+	 * править, каретка пользователя не двигается. null — правка недоступна или выделение вне редактора.
+	 */
+	private __formatTarget(): { selection: Selection; range: Range; original: [number, number] } | null {
+		if (!this.format || this.readonly) return null;
+
+		const selection = this.__innerSelection();
+		if (!selection) return null;
+
+		const current = selection.getRangeAt(0);
+
+		return {
+			selection,
+			// форматируем слова целиком: и при курсоре без выделения, и при выделении части слова
+			range: expandRangeToWords(this.editable, current),
+			original: selectionCharBounds(this.editable, current),
+		};
+	}
 
-		const range = selection.getRangeAt(0);
-		if (range.collapsed) {
+	/** Переключить форматирование инструмента (вызывается общим тулбаром и хоткеями). */
+	applyFormat(tool: FormatTool): void {
+		if (!this.formatTools.includes(tool)) return;
+
+		const target = this.__formatTarget();
+		if (!target) return;
+
+		if (target.range.collapsed) {
 			// под кареткой нет слова — режим набора: формат для следующего ввода
 			if (this.__pendingFormats.has(tool)) this.__pendingFormats.delete(tool);
 			else this.__pendingFormats.add(tool);
@@ -222,24 +305,119 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 		this.__pendingFormats.clear();
 
 		this.__history?.record("op");
-		toggleFormat(this.editable, range, tool, selection, original);
+		toggleFormat(this.editable, target.range, tool, target.selection, target.original);
+
+		this.__emitChange();
+		formatToolbar.refresh();
+	}
+
+	/**
+	 * Снимает всё форматирование с выделения; без выделения — со слова под кареткой
+	 * (как и применение формата). Режим набора сбрасывается.
+	 */
+	clearFormat(): void {
+		const target = this.__formatTarget();
+		if (!target) return;
+
+		this.__clearPendingFormats();
+
+		// нечего очищать — не пишем в историю пустой шаг и не трогаем выделение
+		if (!hasFormatting(this.editable, target.range)) return;
+
+		this.__history?.record("op");
+		clearFormat(this.editable, target.range, target.selection, target.original);
+
+		this.__emitChange();
+		formatToolbar.refresh();
+	}
+
+	/** Снимает всё форматирование со всего содержимого (выделение не требуется). */
+	clearAllFormat(): void {
+		if (!this.format || this.readonly) return;
+
+		this.__clearPendingFormats();
+		if (!hasAnyFormatting(this.editable)) return;
+
+		// разворачивание тегов рвёт выделение — запоминаем по текстовым смещениям
+		const selection = this.__innerSelection();
+		const bounds = selection ? selectionCharBounds(this.editable, selection.getRangeAt(0)) : null;
+
+		this.__history?.record("op");
+		clearAllFormat(this.editable);
+
+		if (bounds && selection) restoreSelection(this.editable, bounds[0], bounds[1], selection);
 
 		this.__emitChange();
 		formatToolbar.refresh();
 	}
 
+	/** Доступна ли отмена (история ведётся только при включённом форматировании). */
+	get canUndo(): boolean {
+		return !this.readonly && !!this.__history?.canUndo;
+	}
+
+	/** Доступен ли повтор отменённого. */
+	get canRedo(): boolean {
+		return !this.readonly && !!this.__history?.canRedo;
+	}
+
 	/** Отменить последнее действие (история ведётся только при форматировании). */
-	private __undo(): void {
-		if (!this.__history?.undo()) return;
+	undo(): void {
+		if (this.readonly || !this.__history?.undo()) return;
 		this.__afterHistory();
 	}
 
 	/** Повторить отменённое действие. */
-	private __redo(): void {
-		if (!this.__history?.redo()) return;
+	redo(): void {
+		if (this.readonly || !this.__history?.redo()) return;
 		this.__afterHistory();
 	}
 
+	/** Выполнить действие панели (вызывается кнопками тулбара). */
+	applyAction(action: EditorAction): void {
+		if (!this.editorActions.includes(action)) return;
+
+		switch (action) {
+			case "erase":
+				this.clearFormat();
+				break;
+			case "undo":
+				this.undo();
+				break;
+			case "redo":
+				this.redo();
+				break;
+			case "emoji":
+				// панель вставки открывает тулбар: ей нужна кнопка как якорь попапа.
+				// Вставка символа приходит сюда через insertText.
+				break;
+		}
+	}
+
+	/** Доступно ли действие сейчас (для disabled-состояния кнопки тулбара). */
+	isActionEnabled(action: EditorAction): boolean {
+		switch (action) {
+			case "undo":
+				return this.canUndo;
+			case "redo":
+				return this.canRedo;
+			case "erase":
+				return this.__hasFormatting();
+			case "emoji":
+				return !this.readonly;
+		}
+	}
+
+	// Есть ли что очищать: ожидающий формат режима набора либо форматирование на цели очистки.
+	// Смотрим на тот же расширенный до слов диапазон, что возьмёт clearFormat, — иначе кнопка
+	// блокировалась бы в случаях, когда операция сработала бы (каретка на границе формата).
+	private __hasFormatting(): boolean {
+		if (this.__pendingFormats.size > 0) return true;
+
+		const target = this.__formatTarget();
+		return !!target && hasFormatting(this.editable, target.range);
+	}
+
 	private __afterHistory(): void {
 		this.__pendingFormats.clear();
 		this.__emitChange();
@@ -250,8 +428,8 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 	isToolActive(tool: FormatTool): boolean {
 		if (this.__pendingFormats.has(tool)) return true;
 
-		const selection = window.getSelection();
-		if (!selection || selection.rangeCount === 0 || !this.editable.contains(selection.anchorNode)) return false;
+		const selection = this.__innerSelection();
+		if (!selection) return false;
 
 		return isFormatActive(this.editable, selection.getRangeAt(0), tool);
 	}
@@ -274,14 +452,23 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 		DOM.empty(this.editable);
 		if (!value) return;
 
-		// multiline → <p>-абзацы; single-line → инлайновое содержимое
+		// multiline → <p>-абзацы; single-line → инлайновое содержимое.
+		// В режиме break абзацных блоков нет: значение — плоский текст, где каждый \n это <br>.
+		// Иначе `a\n\nb` рисовалось бы двумя <p>, а на экране (без отступов между абзацами)
+		// это неотличимо от одного переноса — значение расходилось бы с видимым текстом.
+		const paragraphs = this.multiline && this.paragraph === "block";
+
 		this.editable.innerHTML = deserialize(
 			value,
 			this.__valueStorage,
 			this.__valueTools,
 			this.formatMarkers,
-			this.multiline
+			paragraphs
 		);
+
+		// в break инлайновое содержимое оборачивается в единственный абзац — модель абзацев
+		// нужна редактированию (каретка, вставка), а разделителем строк остаётся <br>
+		if (this.multiline && !paragraphs) ensureParagraphs(this.editable);
 	}
 
 	private __emitChange() {
@@ -298,11 +485,24 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 	private __normalize(notify: boolean) {
 		if (this.readonly) return;
 
+		// правка текстовых узлов рвёт живые Range — запоминаем выделение по текстовым смещениям
+		const selection = this.__innerSelection();
+		const bounds = selection ? selectionCharBounds(this.editable, selection.getRangeAt(0)) : null;
+
 		const before = this.editable.innerHTML;
+		const textBefore = this.editable.textContent ?? "";
 		normalizeWhitespace(this.editable);
 		if (this.multiline) normalizeParagraphs(this.editable);
 		if (this.editable.innerHTML === before) return;
 
+		if (bounds && selection) {
+			// схлопнутые пробелы сдвигают смещения — переносим их на новый текст
+			const textAfter = this.editable.textContent ?? "";
+			const start = mapCharOffset(textBefore, textAfter, bounds[0]);
+			const end = bounds[1] === bounds[0] ? start : mapCharOffset(textBefore, textAfter, bounds[1]);
+			restoreSelection(this.editable, start, end, selection);
+		}
+
 		if (notify) this.__emitChange();
 	}
 
@@ -330,10 +530,12 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 				this.element.classList.add("focused");
 
 				// показываем общий тулбар над этим редактором
-				if (this.format && this.formatTools.length) formatToolbar.attach(this);
+				if (this.format && (this.formatTools.length || this.editorActions.length)) formatToolbar.attach(this);
 
 				if (this.readonly) selectAllContent(this.editable);
-				else if (!this.__hasInputClick) caretToEnd(this.editable, this.multiline);
+				// Каретку в конец ставим только когда её нет: клик ставит сам, а уже стоящую
+				// (фокус вернули из кода после вызова метода) двигать нельзя — уедет в конец текста.
+				else if (!this.__hasInputClick && !this.__innerSelection()) caretToEnd(this.editable, this.multiline);
 			},
 			{ signal }
 		);
@@ -414,12 +616,12 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 			const z = isHotkeyLetter(e, "z");
 			if (z && !e.shiftKey) {
 				e.preventDefault();
-				this.__undo();
+				this.undo();
 				return;
 			}
 			if (isHotkeyLetter(e, "y") || (z && e.shiftKey)) {
 				e.preventDefault();
-				this.__redo();
+				this.redo();
 				return;
 			}
 		}
@@ -450,9 +652,14 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 				return;
 			}
 
-			// Shift/Ctrl/Cmd+Enter — мягкий перенос (<br>) внутри абзаца; Enter — новый абзац (<p>)
+			// В режиме block Enter — новый абзац (<p>), модификатор — мягкий перенос (<br>).
+			// В режиме break наоборот: Enter переносит строку, как в мессенджерах, а абзац
+			// набирается двумя переносами.
+			const withModifier = e.shiftKey || e.ctrlKey || e.metaKey;
+			const soft = this.paragraph === "break" ? !withModifier : withModifier;
+
 			this.__history?.record("op");
-			if (e.shiftKey || e.ctrlKey || e.metaKey) insertSoftBreak(this.editable);
+			if (soft) insertSoftBreak(this.editable);
 			else insertParagraph(this.editable);
 
 			this.__clearPendingFormats();
@@ -601,7 +808,7 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 		if (this.__pendingFormats.size > 0 && e.inputType === "insertText" && e.data != null) {
 			e.preventDefault();
 			this.__history?.record("op");
-			this.__insertPendingText(e.data);
+			this.__insertText(e.data);
 			return;
 		}
 
@@ -615,9 +822,9 @@ export default class RichEditor extends UIElementBound<RichEditorEvents> {
 		formatToolbar.refresh();
 	}
 
-	private __insertPendingText(data: string) {
-		const selection = window.getSelection();
-		if (!selection || !this.editable.contains(selection.anchorNode)) return;
+	private __insertText(data: string) {
+		const selection = this.__innerSelection();
+		if (!selection) return;
 
 		insertFormattedText(this.editable, data, Array.from(this.__pendingFormats), selection);
 

package/source/selection.ts

@@ -6,6 +6,14 @@ import { ALL_FORMAT_TOOLS, FORMAT_TOOLS, type FormatTool } from "./format-config
 /** Канонические теги форматирования (в верхнем регистре, как tagName). */
 const FORMAT_TAG_NAMES = ALL_FORMAT_TOOLS.map((t) => FORMAT_TOOLS[t].tag.toUpperCase());
 
+// Все распознаваемые теги форматирования (канонические и синонимы) — для снятия форматирования
+// целиком: в содержимом редактора синонимов быть не должно, но вставка и setValue могут их принести.
+const MATCH_TAG_NAMES = Array.from(new Set(ALL_FORMAT_TOOLS.flatMap((t) => FORMAT_TOOLS[t].matchTags)));
+
+// Селекторы считаем один раз: обе выборки идут на каждую правку формата и на каждое обновление панели.
+const FORMAT_SELECTOR = FORMAT_TAG_NAMES.join(",").toLowerCase();
+const MATCH_SELECTOR = MATCH_TAG_NAMES.join(",").toLowerCase();
+
 /** Ближайший предок-элемент с одним из тегов (в пределах root, не включая root). */
 function formatAncestor(node: Node, tags: string[], root: HTMLElement): HTMLElement | null {
 	let el = node.parentElement;
@@ -27,6 +35,26 @@ export function selectionCharBounds(root: HTMLElement, range: Range): [number, n
 	return [start, end];
 }
 
+/**
+ * Пересчитывает абсолютное текстовое смещение после нормализации пробелов.
+ *
+ * Нормализация только удаляет символы (схлопывает пробелы) и заменяет табы пробелами,
+ * поэтому старый и новый текст выравниваются одним проходом: несовпадение означает
+ * удалённый символ. Без пересчёта каретка отстаёт ровно на число схлопнутых перед ней
+ * пробелов и может уехать в соседнее слово.
+ */
+export function mapCharOffset(before: string, after: string, offset: number): number {
+	const same = (a: string, b: string) => a === b || (b === " " && (a === " " || a === "\t"));
+
+	let i = 0;
+	let j = 0;
+	while (i < offset && j < after.length) {
+		if (same(before[i], after[j])) j++;
+		i++;
+	}
+	return j;
+}
+
 /** Находит текстовый узел и локальное смещение по абсолютному текстовому смещению. */
 function locateChar(root: HTMLElement, target: number): { node: Text; offset: number } | null {
 	const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
@@ -97,12 +125,13 @@ function nodeWithinRange(node: Node, range: Range): boolean {
 	);
 }
 
-function collectTextNodes(root: HTMLElement, range: Range, strict: boolean): Text[] {
+/** Непустые текстовые узлы, целиком попавшие в диапазон (частично задетые правке не подлежат). */
+function collectTextNodes(root: HTMLElement, range: Range): Text[] {
 	const nodes: Text[] = [];
 	const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
 	let n = walker.nextNode() as Text | null;
 	while (n) {
-		if (n.length > 0 && (strict ? nodeWithinRange(n, range) : range.intersectsNode(n))) nodes.push(n);
+		if (n.length > 0 && nodeWithinRange(n, range)) nodes.push(n);
 		n = walker.nextNode() as Text | null;
 	}
 	return nodes;
@@ -151,13 +180,11 @@ function unwrapElement(el: HTMLElement) {
 
 /** Чистит разметку: убирает пустые теги, схлопывает вложенные и соседние одинаковые, склеивает текст. */
 export function cleanupFormatting(root: HTMLElement) {
-	const selector = FORMAT_TAG_NAMES.join(",").toLowerCase();
-
 	let changed = true;
 	while (changed) {
 		changed = false;
 
-		for (const el of Array.from(root.querySelectorAll<HTMLElement>(selector))) {
+		for (const el of Array.from(root.querySelectorAll<HTMLElement>(FORMAT_SELECTOR))) {
 			if (!el.isConnected) continue;
 
 			// пустой тег
@@ -190,41 +217,114 @@ export function cleanupFormatting(root: HTMLElement) {
 }
 
 /**
- * Переключает форматирование инструмента на выделении.
- * Если весь выделенный текст уже отформатирован — снимает формат, иначе применяет.
+ * Каркас правки форматирования на выделении: доводит границы Range до целых текстовых узлов,
+ * отдаёт строго попавшие узлы в `mutate` и восстанавливает выделение.
  *
  * По умолчанию восстанавливает выделение, на котором работал. Через `restoreBounds`
  * можно восстановить другое выделение (например, исходное до расширения до слова).
  */
-export function toggleFormat(
+function editSelection(
 	root: HTMLElement,
 	range: Range,
-	tool: FormatTool,
 	selection: Selection,
-	restoreBounds?: [number, number]
+	restoreBounds: [number, number] | undefined,
+	mutate: (nodes: Text[]) => void
 ) {
 	if (range.collapsed) return;
 
-	const def = FORMAT_TOOLS[tool];
-	const tags = def.matchTags;
 	const [startChar, endChar] = restoreBounds ?? selectionCharBounds(root, range);
 
 	splitBoundaries(range);
 
-	const nodes = collectTextNodes(root, range, true);
+	const nodes = collectTextNodes(root, range);
 	if (!nodes.length) return;
 
-	const allFormatted = nodes.every((n) => formatAncestor(n, tags, root) !== null);
-	if (allFormatted) {
-		for (const n of nodes) removeFormatFromNode(n, tags, root);
-	} else {
-		for (const n of nodes) if (!formatAncestor(n, tags, root)) wrapTextNode(n, def.tag);
-	}
+	mutate(nodes);
 
 	cleanupFormatting(root);
 	restoreSelection(root, startChar, endChar, selection);
 }
 
+/**
+ * Переключает форматирование инструмента на выделении.
+ * Если весь выделенный текст уже отформатирован — снимает формат, иначе применяет.
+ */
+export function toggleFormat(
+	root: HTMLElement,
+	range: Range,
+	tool: FormatTool,
+	selection: Selection,
+	restoreBounds?: [number, number]
+) {
+	const def = FORMAT_TOOLS[tool];
+	const tags = def.matchTags;
+
+	editSelection(root, range, selection, restoreBounds, (nodes) => {
+		const allFormatted = nodes.every((n) => formatAncestor(n, tags, root) !== null);
+		if (allFormatted) {
+			for (const n of nodes) removeFormatFromNode(n, tags, root);
+		} else {
+			for (const n of nodes) if (!formatAncestor(n, tags, root)) wrapTextNode(n, def.tag);
+		}
+	});
+}
+
+/** Снимает всё форматирование с выделения (все инструменты сразу, включая теги-синонимы). */
+export function clearFormat(root: HTMLElement, range: Range, selection: Selection, restoreBounds?: [number, number]) {
+	editSelection(root, range, selection, restoreBounds, (nodes) => {
+		for (const n of nodes) removeFormatFromNode(n, MATCH_TAG_NAMES, root);
+	});
+}
+
+/** Снимает всё форматирование со всего содержимого (выделение не участвует). */
+export function clearAllFormat(root: HTMLElement) {
+	// вложенные элементы после разворачивания родителя остаются в дереве — снимок обходим целиком
+	for (const el of Array.from(root.querySelectorAll<HTMLElement>(MATCH_SELECTOR))) unwrapElement(el);
+
+	root.normalize();
+}
+
+/**
+ * Состояние форматирования на выделении указанными тегами.
+ * `every` — отформатирован весь текст (подсветка кнопки инструмента),
+ * `some` — отформатирована хоть какая-то часть (доступность очистки).
+ * Обход прерывается на первом узле, решающем исход.
+ */
+function rangeFormatState(root: HTMLElement, range: Range, tags: string[], mode: "every" | "some"): boolean {
+	if (range.collapsed) {
+		const node = range.startContainer;
+		const probe = node.nodeType === Node.TEXT_NODE ? node : (node.childNodes[range.startOffset] ?? node);
+		return formatAncestor(probe, tags, root) !== null;
+	}
+
+	const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+	let found = false;
+
+	for (let n = walker.nextNode() as Text | null; n; n = walker.nextNode() as Text | null) {
+		if (!n.length || !range.intersectsNode(n)) continue;
+
+		const formatted = formatAncestor(n, tags, root) !== null;
+		if (mode === "some") {
+			if (formatted) return true;
+		} else if (!formatted) return false;
+
+		found = true;
+	}
+
+	// every: пустое выделение — не «отформатировано целиком»; some: ни одного форматированного узла
+	return mode === "every" && found;
+}
+
+/** Есть ли форматирование на выделении (или под кареткой) — для доступности кнопки очистки. */
+export function hasFormatting(root: HTMLElement, range: Range): boolean {
+	return rangeFormatState(root, range, MATCH_TAG_NAMES, "some");
+}
+
+/** Есть ли форматирование хоть где-то в содержимом. */
+export function hasAnyFormatting(root: HTMLElement): boolean {
+	return root.querySelector(MATCH_SELECTOR) !== null;
+}
+
 /**
  * Вставляет текст в позицию каретки, оборачивая его в указанные форматы (режим набора).
  * Каретка ставится сразу после вставленного текста; соседние одинаковые теги склеиваются.
@@ -253,15 +353,5 @@ export function insertFormattedText(root: HTMLElement, data: string, tools: Form
 
 /** Активен ли формат инструмента на текущем выделении (для подсветки кнопки). */
 export function isFormatActive(root: HTMLElement, range: Range, tool: FormatTool): boolean {
-	const tags = FORMAT_TOOLS[tool].matchTags;
-
-	if (range.collapsed) {
-		const node = range.startContainer;
-		const probe = node.nodeType === Node.TEXT_NODE ? node : (node.childNodes[range.startOffset] ?? node);
-		return formatAncestor(probe, tags, root) !== null;
-	}
-
-	const nodes = collectTextNodes(root, range, false);
-	if (!nodes.length) return false;
-	return nodes.every((n) => formatAncestor(n, tags, root) !== null);
+	return rangeFormatState(root, range, FORMAT_TOOLS[tool].matchTags, "every");
 }