chore(ckeditor5-admonition): integrate code structure

packages/ckeditor5-admonition/src/admonition.ts

@@ -1,8 +1,16 @@
 import { Plugin, ButtonView } from 'ckeditor5';
 
-import ckeditor5Icon from '../theme/icons/ckeditor.svg';
+import admonitionIcon from '../theme/icons/admonition.svg';
+import AdmonitionEditing from './admonitionediting.js';
+import AdmonitionUI from './admonitionui.js';
+import AdmonitionAutoformat from './admonitionautoformat.js';
 
 export default class Admonition extends Plugin {
+
+	public static get requires() {
+		return [ AdmonitionEditing, AdmonitionUI, AdmonitionAutoformat ] as const;
+	}
+
 	public static get pluginName() {
 		return 'Admonition' as const;
 	}
@@ -18,7 +26,7 @@ export default class Admonition extends Plugin {
 
 			view.set( {
 				label: t( 'Admonition' ),
-				icon: ckeditor5Icon,
+				icon: admonitionIcon,
 				tooltip: true
 			} );
 

packages/ckeditor5-admonition/src/admonitionautoformat.ts

@@ -0,0 +1,41 @@
+import { Autoformat, blockAutoformatEditing, Plugin } from "ckeditor5";
+import { AdmonitionType, ADMONITION_TYPES } from "./admonitioncommand.js";
+
+function tryParseAdmonitionType(match: RegExpMatchArray) {
+	if (match.length !== 2) {
+		return;
+	}
+
+	if ((ADMONITION_TYPES as readonly string[]).includes(match[1])) {
+		return match[1] as AdmonitionType;
+	}
+}
+
+export default class AdmonitionAutoformat extends Plugin {
+
+	static get requires() {
+		return [ Autoformat ];
+	}
+
+	afterInit() {
+		if (!this.editor.commands.get("admonition")) {
+			return;
+		}
+
+		const instance = (this as any);
+		blockAutoformatEditing(this.editor, instance, /^\!\!\[*\! (.+) $/, ({ match }) => {
+			const type = tryParseAdmonitionType(match);
+
+			if (type) {
+				// User has entered the admonition type, so we insert as-is.
+				this.editor.execute("admonition", { forceValue: type });
+			} else {
+				// User has not entered a valid type, assume it's part of the text of the admonition.
+				this.editor.execute("admonition");
+				if (match.length > 1) {
+					this.editor.execute("insertText", { text: (match[1] ?? "") + " " });
+				}
+			}
+		});
+	}
+}

packages/ckeditor5-admonition/src/admonitioncommand.ts

@@ -0,0 +1,275 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module admonition/admonitioncommand
+ */
+
+import { Command, first } from 'ckeditor5';
+import type { DocumentFragment, Element, Position, Range, Schema, Writer } from 'ckeditor5';
+
+/**
+ * The block quote command plugin.
+ *
+ * @extends module:core/command~Command
+ */
+
+export const ADMONITION_TYPES = [ "note", "tip", "important", "caution", "warning" ] as const;
+export const ADMONITION_TYPE_ATTRIBUTE = "admonitionType";
+export const DEFAULT_ADMONITION_TYPE = ADMONITION_TYPES[0];
+export type AdmonitionType = typeof ADMONITION_TYPES[number];
+
+interface ExecuteOpts {
+	/**
+	 * If set, it will force the command behavior. If `true`, the command will apply a block quote,
+	 * otherwise the command will remove the block quote. If not set, the command will act basing on its current value.
+	 */
+	forceValue?: AdmonitionType;
+	/**
+	 * If set to true and `forceValue` is not specified, the command will apply the previous admonition type (if the command was already executed).
+	 */
+	usePreviousChoice?: boolean
+}
+
+export default class AdmonitionCommand extends Command {
+	/**
+	 * Whether the selection starts in a block quote.
+	 *
+	 * @observable
+	 * @readonly
+	 */
+	declare public value: AdmonitionType | false;
+
+	private _lastType?: AdmonitionType;
+
+	/**
+	 * @inheritDoc
+	 */
+	public override refresh(): void {
+		this.value = this._getValue();
+		this.isEnabled = this._checkEnabled();
+	}
+
+	/**
+	 * Executes the command. When the command {@link #value is on}, all top-most block quotes within
+	 * the selection will be removed. If it is off, all selected blocks will be wrapped with
+	 * a block quote.
+	 *
+	 * @fires execute
+	 * @param options Command options.
+	 */
+	public override execute( options: ExecuteOpts = {} ): void {
+		const model = this.editor.model;
+		const schema = model.schema;
+		const selection = model.document.selection;
+
+		const blocks = Array.from( selection.getSelectedBlocks() );
+
+		const value = this._getType(options);
+
+		model.change( writer => {
+			if ( !value ) {
+				this._removeQuote( writer, blocks.filter( findQuote ) );
+			} else {
+				const blocksToQuote = blocks.filter( block => {
+					// Already quoted blocks needs to be considered while quoting too
+					// in order to reuse their <bQ> elements.
+					return findQuote( block ) || checkCanBeQuoted( schema, block );
+				} );
+
+				this._applyQuote( writer, blocksToQuote, value);
+			}
+		} );
+	}
+
+	private _getType(options: ExecuteOpts): AdmonitionType | false {
+		const value = (options.forceValue === undefined) ? !this.value : options.forceValue;
+
+		// Allow removing the admonition.
+		if (!value) {
+			return false;
+		}
+
+		// Prefer the type from the command, if any.
+		if (typeof value === "string") {
+			return value;
+		}
+
+		// See if we can restore the previous language.
+		if (options.usePreviousChoice && this._lastType) {
+			return this._lastType;
+		}
+
+		// Otherwise return a default.
+		return "note";
+	}
+
+	/**
+	 * Checks the command's {@link #value}.
+	 */
+	private _getValue(): AdmonitionType | false {
+		const selection = this.editor.model.document.selection;
+		const firstBlock = first( selection.getSelectedBlocks() );
+		if (!firstBlock) {
+			return false;
+		}
+
+		// In the current implementation, the admonition must be an immediate parent of a block element.
+		const firstQuote = findQuote( firstBlock );
+		if (firstQuote?.is("element")) {
+			return firstQuote.getAttribute(ADMONITION_TYPE_ATTRIBUTE) as AdmonitionType;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Checks whether the command can be enabled in the current context.
+	 *
+	 * @returns Whether the command should be enabled.
+	 */
+	private _checkEnabled(): boolean {
+		if ( this.value ) {
+			return true;
+		}
+
+		const selection = this.editor.model.document.selection;
+		const schema = this.editor.model.schema;
+
+		const firstBlock = first( selection.getSelectedBlocks() );
+
+		if ( !firstBlock ) {
+			return false;
+		}
+
+		return checkCanBeQuoted( schema, firstBlock );
+	}
+
+	/**
+	 * Removes the quote from given blocks.
+	 *
+	 * If blocks which are supposed to be "unquoted" are in the middle of a quote,
+	 * start it or end it, then the quote will be split (if needed) and the blocks
+	 * will be moved out of it, so other quoted blocks remained quoted.
+	 */
+	private _removeQuote( writer: Writer, blocks: Array<Element> ): void {
+		// Unquote all groups of block. Iterate in the reverse order to not break following ranges.
+		getRangesOfBlockGroups( writer, blocks ).reverse().forEach( groupRange => {
+			if ( groupRange.start.isAtStart && groupRange.end.isAtEnd ) {
+				writer.unwrap( groupRange.start.parent as Element );
+
+				return;
+			}
+
+			// The group of blocks are at the beginning of an <bQ> so let's move them left (out of the <bQ>).
+			if ( groupRange.start.isAtStart ) {
+				const positionBefore = writer.createPositionBefore( groupRange.start.parent as Element );
+
+				writer.move( groupRange, positionBefore );
+
+				return;
+			}
+
+			// The blocks are in the middle of an <bQ> so we need to split the <bQ> after the last block
+			// so we move the items there.
+			if ( !groupRange.end.isAtEnd ) {
+				writer.split( groupRange.end );
+			}
+
+			// Now we are sure that groupRange.end.isAtEnd is true, so let's move the blocks right.
+
+			const positionAfter = writer.createPositionAfter( groupRange.end.parent as Element );
+
+			writer.move( groupRange, positionAfter );
+		} );
+	}
+
+	/**
+	 * Applies the quote to given blocks.
+	 */
+	private _applyQuote( writer: Writer, blocks: Array<Element>, type?: AdmonitionType): void {
+		this._lastType = type;
+		const quotesToMerge: Array<Element | DocumentFragment> = [];
+
+		// Quote all groups of block. Iterate in the reverse order to not break following ranges.
+		getRangesOfBlockGroups( writer, blocks ).reverse().forEach( groupRange => {
+			let quote = findQuote( groupRange.start );
+
+			if ( !quote ) {
+				const attributes: Record<string, unknown> = {};
+				attributes[ADMONITION_TYPE_ATTRIBUTE] = type;
+				quote = writer.createElement( 'aside', attributes);
+
+				writer.wrap( groupRange, quote );
+			} else if (quote.is("element")) {
+				this.editor.model.change((writer) => {
+					writer.setAttribute(ADMONITION_TYPE_ATTRIBUTE, type, quote as Element);
+				});
+			}
+
+			quotesToMerge.push( quote );
+		} );
+
+		// Merge subsequent <bQ> elements. Reverse the order again because this time we want to go through
+		// the <bQ> elements in the source order (due to how merge works – it moves the right element's content
+		// to the first element and removes the right one. Since we may need to merge a couple of subsequent `<bQ>` elements
+		// we want to keep the reference to the first (furthest left) one.
+		quotesToMerge.reverse().reduce( ( currentQuote, nextQuote ) => {
+			if ( currentQuote.nextSibling == nextQuote ) {
+				writer.merge( writer.createPositionAfter( currentQuote ) );
+
+				return currentQuote;
+			}
+
+			return nextQuote;
+		} );
+	}
+}
+
+function findQuote( elementOrPosition: Element | Position ): Element | DocumentFragment | null {
+	return elementOrPosition.parent!.name == 'aside' ? elementOrPosition.parent : null;
+}
+
+/**
+ * Returns a minimal array of ranges containing groups of subsequent blocks.
+ *
+ * content:         abcdefgh
+ * blocks:          [ a, b, d, f, g, h ]
+ * output ranges:   [ab]c[d]e[fgh]
+ */
+function getRangesOfBlockGroups( writer: Writer, blocks: Array<Element> ): Array<Range> {
+	let startPosition;
+	let i = 0;
+	const ranges = [];
+
+	while ( i < blocks.length ) {
+		const block = blocks[ i ];
+		const nextBlock = blocks[ i + 1 ];
+
+		if ( !startPosition ) {
+			startPosition = writer.createPositionBefore( block );
+		}
+
+		if ( !nextBlock || block.nextSibling != nextBlock ) {
+			ranges.push( writer.createRange( startPosition, writer.createPositionAfter( block ) ) );
+			startPosition = null;
+		}
+
+		i++;
+	}
+
+	return ranges;
+}
+
+/**
+ * Checks whether <bQ> can wrap the block.
+ */
+function checkCanBeQuoted( schema: Schema, block: Element ): boolean {
+	// TMP will be replaced with schema.checkWrap().
+	const isBQAllowed = schema.checkChild( block.parent as Element, 'aside' );
+	const isBlockAllowedInBQ = schema.checkChild( [ '$root', 'aside' ], block );
+
+	return isBQAllowed && isBlockAllowedInBQ;
+}

packages/ckeditor5-admonition/src/admonitionediting.ts

@@ -0,0 +1,177 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module admonition/admonitionediting
+ */
+
+import { Delete, Enter, Plugin, ViewDocumentDeleteEvent, ViewDocumentEnterEvent } from 'ckeditor5';
+import AdmonitionCommand, { AdmonitionType, ADMONITION_TYPES, DEFAULT_ADMONITION_TYPE, ADMONITION_TYPE_ATTRIBUTE } from './admonitioncommand.js';
+
+/**
+ * The block quote editing.
+ *
+ * Introduces the `'admonition'` command and the `'aside'` model element.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class AdmonitionEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	public static get pluginName() {
+		return 'AdmonitionEditing' as const;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public static get requires() {
+		return [ Enter, Delete ] as const;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public init(): void {
+		const editor = this.editor;
+		const schema = editor.model.schema;
+
+		editor.commands.add( 'admonition', new AdmonitionCommand( editor ) );
+
+		schema.register( 'aside', {
+			inheritAllFrom: '$container',
+			allowAttributes: ADMONITION_TYPE_ATTRIBUTE
+		} );
+
+		editor.conversion.for("upcast").elementToElement({
+			view: {
+				name: "aside",
+				classes: "admonition",
+			},
+			model: (viewElement, { writer }) => {
+				let type: AdmonitionType = DEFAULT_ADMONITION_TYPE;
+				for (const className of viewElement.getClassNames()) {
+					if (className !== "admonition" && (ADMONITION_TYPES as readonly string[]).includes(className)) {
+						type = className as AdmonitionType;
+					}
+				}
+
+				const attributes: Record<string, unknown> = {};
+				attributes[ADMONITION_TYPE_ATTRIBUTE] = type;
+				return writer.createElement("aside", attributes);
+			}
+		});
+
+		editor.conversion.for("downcast")
+			.elementToElement( {
+				model: 'aside',
+				view: "aside"
+			})
+			.attributeToAttribute({
+				model: ADMONITION_TYPE_ATTRIBUTE,
+				view: (value) => ({
+					key: "class",
+					value: [ "admonition", value as string ]
+				})
+			});
+
+		// Postfixer which cleans incorrect model states connected with block quotes.
+		editor.model.document.registerPostFixer( writer => {
+			const changes = editor.model.document.differ.getChanges();
+
+			for ( const entry of changes ) {
+				if ( entry.type == 'insert' ) {
+					const element = entry.position.nodeAfter;
+
+					if ( !element ) {
+						// We are inside a text node.
+						continue;
+					}
+
+					if ( element.is( 'element', 'aside' ) && element.isEmpty ) {
+						// Added an empty aside - remove it.
+						writer.remove( element );
+
+						return true;
+					} else if ( element.is( 'element', 'aside' ) && !schema.checkChild( entry.position, element ) ) {
+						// Added a aside in incorrect place. Unwrap it so the content inside is not lost.
+						writer.unwrap( element );
+
+						return true;
+					} else if ( element.is( 'element' ) ) {
+						// Just added an element. Check that all children meet the scheme rules.
+						const range = writer.createRangeIn( element );
+
+						for ( const child of range.getItems() ) {
+							if (
+								child.is( 'element', 'aside' ) &&
+								!schema.checkChild( writer.createPositionBefore( child ), child )
+							) {
+								writer.unwrap( child );
+
+								return true;
+							}
+						}
+					}
+				} else if ( entry.type == 'remove' ) {
+					const parent = entry.position.parent;
+
+					if ( parent.is( 'element', 'aside' ) && parent.isEmpty ) {
+						// Something got removed and now aside is empty. Remove the aside as well.
+						writer.remove( parent );
+
+						return true;
+					}
+				}
+			}
+
+			return false;
+		} );
+
+		const viewDocument = this.editor.editing.view.document;
+		const selection = editor.model.document.selection;
+		const admonitionCommand = editor.commands.get( 'admonition' );
+		if (!admonitionCommand) {
+			return;
+		}
+
+		// Overwrite default Enter key behavior.
+		// If Enter key is pressed with selection collapsed in empty block inside a quote, break the quote.
+		this.listenTo<ViewDocumentEnterEvent>( viewDocument, 'enter', ( evt, data ) => {
+			if ( !selection.isCollapsed || !admonitionCommand.value ) {
+				return;
+			}
+
+			const positionParent = selection.getLastPosition()!.parent;
+
+			if ( positionParent.isEmpty ) {
+				editor.execute( 'admonition' );
+				editor.editing.view.scrollToTheSelection();
+
+				data.preventDefault();
+				evt.stop();
+			}
+		}, { context: 'aside' } );
+
+		// Overwrite default Backspace key behavior.
+		// If Backspace key is pressed with selection collapsed in first empty block inside a quote, break the quote.
+		this.listenTo<ViewDocumentDeleteEvent>( viewDocument, 'delete', ( evt, data ) => {
+			if ( data.direction != 'backward' || !selection.isCollapsed || !admonitionCommand!.value ) {
+				return;
+			}
+
+			const positionParent = selection.getLastPosition()!.parent;
+
+			if ( positionParent.isEmpty && !positionParent.previousSibling ) {
+				editor.execute( 'admonition' );
+				editor.editing.view.scrollToTheSelection();
+
+				data.preventDefault();
+				evt.stop();
+			}
+		}, { context: 'aside' } );
+	}
+}

packages/ckeditor5-admonition/src/admonitionui.ts

@@ -0,0 +1,127 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module admonition/admonitionui
+ */
+
+import { Plugin, addListToDropdown, createDropdown, ListDropdownItemDefinition, SplitButtonView, ViewModel } from 'ckeditor5';
+
+import '../theme/blockquote.css';
+import admonitionIcon from '../theme/icons/admonition.svg';
+import { AdmonitionType } from './admonitioncommand.js';
+import { Collection } from 'ckeditor5';
+
+interface AdmonitionDefinition {
+	title: string;
+}
+
+export const ADMONITION_TYPES: Record<AdmonitionType, AdmonitionDefinition> = {
+	note: {
+		title: "Note"
+	},
+	tip: {
+		title: "Tip"
+	},
+	important: {
+		title: "Important"
+	},
+	caution: {
+		title: "Caution"
+	},
+	warning: {
+		title: "Warning"
+	}
+};
+
+/**
+ * The block quote UI plugin.
+ *
+ * It introduces the `'admonition'` button.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class AdmonitionUI extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	public static get pluginName() {
+		return 'AdmonitionUI' as const;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public init(): void {
+		const editor = this.editor;
+
+		editor.ui.componentFactory.add( 'admonition', () => {
+			const buttonView = this._createButton();
+
+			return buttonView;
+		} );
+	}
+
+	/**
+	 * Creates a button for admonition command to use either in toolbar or in menu bar.
+	 */
+	private _createButton() {
+		const editor = this.editor;
+		const locale = editor.locale;
+		const command = editor.commands.get( 'admonition' )!;
+		const dropdownView = createDropdown(locale, SplitButtonView);
+		const splitButtonView = dropdownView.buttonView;
+		const t = locale.t;
+
+		addListToDropdown(dropdownView, this._getDropdownItems())
+
+		// Button configuration.
+		splitButtonView.set( {
+			label: t( 'Admonition' ),
+			icon: admonitionIcon,
+			isToggleable: true,
+			tooltip: true
+		} );
+		splitButtonView.on("execute", () => {
+			editor.execute("admonition", { usePreviousChoice: true });
+			editor.editing.view.focus();
+		});
+		splitButtonView.bind( 'isOn' ).to( command, 'value', value => (!!value) as boolean);
+
+		// Dropdown configuration
+		dropdownView.bind( 'isEnabled' ).to( command, 'isEnabled' );
+		dropdownView.on("execute", evt => {
+			editor.execute("admonition", { forceValue: ( evt.source as any ).commandParam } );
+			editor.editing.view.focus();
+		});
+
+		return dropdownView;
+	}
+
+	private _getDropdownItems() {
+		const itemDefinitions = new Collection<ListDropdownItemDefinition>();
+		const command = this.editor.commands.get("admonition");
+		if (!command) {
+			return itemDefinitions;
+		}
+
+		for (const [ type, admonition ] of Object.entries(ADMONITION_TYPES)) {
+			const definition: ListDropdownItemDefinition = {
+				type: "button",
+				model: new ViewModel({
+					commandParam: type,
+					label: admonition.title,
+					role: 'menuitemradio',
+					withText: true
+				})
+			}
+
+			definition.model.bind("isOn").to(command, "value", currentType => currentType === type);
+			itemDefinitions.add(definition);
+		}
+
+		return itemDefinitions;
+	}
+}

packages/ckeditor5-admonition/src/augmentation.ts

@@ -1,7 +1,17 @@
+import AdmonitionCommand from './admonitioncommand.js';
+import AdmonitionEditing from './admonitionediting.js';
+import AdmonitionUI from './admonitionui.js';
 import type { Admonition } from './index.js';
 
 declare module 'ckeditor5' {
 	interface PluginsMap {
 		[ Admonition.pluginName ]: Admonition;
+		[ AdmonitionEditing.pluginName ]: AdmonitionEditing;
+		[ AdmonitionUI.pluginName ]: AdmonitionUI;
 	}
+
+	interface CommandsMap {
+		admonition: AdmonitionCommand;
+	}
+
 }

packages/ckeditor5-admonition/src/index.ts

@@ -1,7 +1,12 @@
 import ckeditor from './../theme/icons/ckeditor.svg';
 import './augmentation.js';
+import "../theme/blockquote.css";
 
 export { default as Admonition } from './admonition.js';
+export { default as AdmonitionEditing } from './admonitionediting.js';
+export { default as AdmonitionUI } from './admonitionui.js';
+export { default as AdmonitionAutoformat } from './admonitionautoformat.js';
+export type { default as AdmonitionCommand } from './admonitioncommand.js';
 
 export const icons = {
 	ckeditor