Merge pull request #13161 from ckeditor/ck/12999

Other (block-quote): Rewrite ckeditor5-block-quote to TypeScript. Closes #12999.

.gitignore

@@ -28,6 +28,7 @@ yalc.lock
 # Ignore compiled TypeScript files.
 packages/ckeditor5-alignment/src/**/*.js
 packages/ckeditor5-basic-styles/src/**/*.js
+packages/ckeditor5-block-quote/src/**/*.js
 packages/ckeditor5-clipboard/src/**/*.js
 packages/ckeditor5-code-block/src/**/*.js
 packages/ckeditor5-core/src/**/*.js

packages/ckeditor5-block-quote/package.json

@@ -10,7 +10,7 @@
     "ckeditor5-plugin",
     "ckeditor5-dll"
   ],
-  "main": "src/index.js",
+  "main": "src/index.ts",
   "dependencies": {
     "ckeditor5": "^35.4.0"
   },
@@ -28,6 +28,7 @@
     "@ckeditor/ckeditor5-table": "^35.4.0",
     "@ckeditor/ckeditor5-theme-lark": "^35.4.0",
     "@ckeditor/ckeditor5-typing": "^35.4.0",
+    "typescript": "^4.8.4",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"
   },
@@ -46,13 +47,16 @@
   },
   "files": [
     "lang",
-    "src",
+    "src/**/*.js",
+    "src/**/*.d.ts",
     "theme",
     "build",
     "ckeditor5-metadata.json",
     "CHANGELOG.md"
   ],
   "scripts": {
-    "dll:build": "webpack"
+    "dll:build": "webpack",
+    "build": "tsc -p ./tsconfig.release.json",
+    "postversion": "npm run build"
   }
 }

packages/ckeditor5-block-quote/src/blockquote.ts

@@ -0,0 +1,45 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module block-quote/blockquote
+ */
+
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+
+import BlockQuoteEditing from './blockquoteediting';
+import BlockQuoteUI from './blockquoteui';
+
+/**
+ * The block quote plugin.
+ *
+ * For more information about this feature check the {@glink api/block-quote package page}.
+ *
+ * This is a "glue" plugin which loads the {@link module:block-quote/blockquoteediting~BlockQuoteEditing block quote editing feature}
+ * and {@link module:block-quote/blockquoteui~BlockQuoteUI block quote UI feature}.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class BlockQuote extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	public static get requires(): PluginDependencies {
+		return [ BlockQuoteEditing, BlockQuoteUI ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public static get pluginName(): 'BlockQuote' {
+		return 'BlockQuote';
+	}
+}
+
+declare module '@ckeditor/ckeditor5-core' {
+	interface PluginsMap {
+		[ BlockQuote.pluginName ]: BlockQuote;
+	}
+}

packages/ckeditor5-block-quote/src/blockquotecommand.ts

@@ -0,0 +1,222 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module block-quote/blockquotecommand
+ */
+
+import { Command } from 'ckeditor5/src/core';
+import { first } from 'ckeditor5/src/utils';
+import type { DocumentFragment, Element, Position, Range, Schema, Writer } from 'ckeditor5/src/engine';
+
+/**
+ * The block quote command plugin.
+ *
+ * @extends module:core/command~Command
+ */
+export default class BlockQuoteCommand extends Command {
+	/**
+	 * Whether the selection starts in a block quote.
+	 *
+	 * @observable
+	 * @readonly
+	 */
+	declare public value: boolean;
+
+	/**
+	 * @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.
+	 * @param options.forceValue 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.
+	 */
+	public override execute( options: { forceValue?: boolean } = {} ): void {
+		const model = this.editor.model;
+		const schema = model.schema;
+		const selection = model.document.selection;
+
+		const blocks = Array.from( selection.getSelectedBlocks() );
+
+		const value = ( options.forceValue === undefined ) ? !this.value : options.forceValue;
+
+		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 );
+			}
+		} );
+	}
+
+	/**
+	 * Checks the command's {@link #value}.
+	 */
+	private _getValue(): boolean {
+		const selection = this.editor.model.document.selection;
+
+		const firstBlock = first( selection.getSelectedBlocks() );
+
+		// In the current implementation, the block quote must be an immediate parent of a block element.
+		return !!( firstBlock && findQuote( firstBlock ) );
+	}
+
+	/**
+	 * 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> ): void {
+		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 ) {
+				quote = writer.createElement( 'blockQuote' );
+
+				writer.wrap( groupRange, quote );
+			}
+
+			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 == 'blockQuote' ? 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, 'blockQuote' );
+	const isBlockAllowedInBQ = schema.checkChild( [ '$root', 'blockQuote' ], block );
+
+	return isBQAllowed && isBlockAllowedInBQ;
+}