@ckeditor/ckeditor5-paragraph 30.0.0

package/LICENSE.md

@@ -0,0 +1,17 @@
+Software License Agreement
+==========================
+
+**CKEditor 5 paragraph feature** – https://github.com/ckeditor/ckeditor5-paragraph <br>
+Copyright (c) 2003-2021, [CKSource](http://cksource.com) Frederico Knabben. All rights reserved.
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).
+
+Sources of Intellectual Property Included in CKEditor
+-----------------------------------------------------
+
+Where not otherwise indicated, all CKEditor content is authored by CKSource engineers and consists of CKSource-owned intellectual property. In some specific instances, CKEditor will incorporate work done by developers outside of CKSource with their express permission.
+
+Trademarks
+----------
+
+**CKEditor** is a trademark of [CKSource](http://cksource.com) Frederico Knabben. All other brand and product names are trademarks, registered trademarks or service marks of their respective holders.

package/README.md

@@ -0,0 +1,16 @@
+CKEditor 5 paragraph feature
+========================================
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-paragraph.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-paragraph)
+[![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5?branch=master)
+[![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://travis-ci.com/ckeditor/ckeditor5)
+
+This package implements paragraph support for CKEditor 5.
+
+## Documentation
+
+See the [`@ckeditor/ckeditor5-paragraph` package](https://ckeditor.com/docs/ckeditor5/latest/api/paragraph.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
+
+## License
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html). For full details about the license, please check the `LICENSE.md` file or [https://ckeditor.com/legal/ckeditor-oss-license](https://ckeditor.com/legal/ckeditor-oss-license).

package/ckeditor5-metadata.json

@@ -0,0 +1,17 @@
+{
+	"plugins": [
+		{
+			"name": "Paragraph",
+			"className": "Paragraph",
+			"description": "Enables support for adding paragraphs to your content.",
+			"path": "src/paragraph.js",
+			"htmlOutput": [
+				{
+					"elements": "p",
+					"implements": "$block",
+					"_comment": "The HTML element may contain classes, styles or attributes that are created by other plugins, which alter the <code>`$block`</code> element."
+				}
+			]
+		}
+	]
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@ckeditor/ckeditor5-paragraph",
+  "version": "30.0.0",
+  "description": "Paragraph feature for CKEditor 5.",
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "ckeditor 5",
+    "ckeditor5-feature",
+    "ckeditor5-plugin",
+    "ckeditor5-dll"
+  ],
+  "main": "src/index.js",
+  "dependencies": {
+    "@ckeditor/ckeditor5-core": "^30.0.0",
+    "@ckeditor/ckeditor5-ui": "^30.0.0",
+    "@ckeditor/ckeditor5-utils": "^30.0.0"
+  },
+  "devDependencies": {
+    "@ckeditor/ckeditor5-basic-styles": "^30.0.0",
+    "@ckeditor/ckeditor5-clipboard": "^30.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^30.0.0",
+    "@ckeditor/ckeditor5-engine": "^30.0.0",
+    "@ckeditor/ckeditor5-enter": "^30.0.0",
+    "@ckeditor/ckeditor5-heading": "^30.0.0",
+    "@ckeditor/ckeditor5-link": "^30.0.0",
+    "@ckeditor/ckeditor5-typing": "^30.0.0",
+    "@ckeditor/ckeditor5-undo": "^30.0.0"
+  },
+  "engines": {
+    "node": ">=12.0.0",
+    "npm": ">=5.7.1"
+  },
+  "author": "CKSource (http://cksource.com/)",
+  "license": "GPL-2.0-or-later",
+  "homepage": "https://ckeditor.com/ckeditor-5",
+  "bugs": "https://github.com/ckeditor/ckeditor5/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ckeditor/ckeditor5.git",
+    "directory": "packages/ckeditor5-paragraph"
+  },
+  "files": [
+    "lang",
+    "src",
+    "theme",
+    "ckeditor5-metadata.json"
+  ]
+}

package/src/index.js

@@ -0,0 +1,11 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module paragraph
+ */
+
+export { default as Paragraph } from './paragraph';
+export { default as ParagraphButtonUI } from './paragraphbuttonui';

package/src/insertparagraphcommand.js

@@ -0,0 +1,62 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module paragraph/insertparagraphcommand
+ */
+
+import Command from '@ckeditor/ckeditor5-core/src/command';
+
+/**
+ * The insert paragraph command. It inserts a new paragraph at a specific
+ * {@link module:engine/model/position~Position document position}.
+ *
+ *		// Insert a new paragraph before an element in the document.
+ *		editor.execute( 'insertParagraph', {
+ *			position: editor.model.createPositionBefore( element )
+ *		} );
+ *
+ * If a paragraph is disallowed in the context of the specific position, the command
+ * will attempt to split position ancestors to find a place where it is possible
+ * to insert a paragraph.
+ *
+ * **Note**: This command moves the selection to the inserted paragraph.
+ *
+ * @extends module:core/command~Command
+ */
+export default class InsertParagraphCommand extends Command {
+	/**
+	 * Executes the command.
+	 *
+	 * @param {Object} options Options for the executed command.
+	 * @param {module:engine/model/position~Position} options.position The model position at which
+	 * the new paragraph will be inserted.
+	 * @fires execute
+	 */
+	execute( options ) {
+		const model = this.editor.model;
+		let position = options.position;
+
+		model.change( writer => {
+			const paragraph = writer.createElement( 'paragraph' );
+
+			if ( !model.schema.checkChild( position.parent, paragraph ) ) {
+				const allowedParent = model.schema.findAllowedParent( position, paragraph );
+
+				// It could be there's no ancestor limit that would allow paragraph.
+				// In theory, "paragraph" could be disallowed even in the "$root".
+				if ( !allowedParent ) {
+					return;
+				}
+
+				position = writer.split( position, allowedParent ).position;
+			}
+
+			model.insertContent( paragraph, position );
+
+			writer.setSelection( paragraph, 'in' );
+		} );
+	}
+}

package/src/paragraph.js

@@ -0,0 +1,118 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module paragraph/paragraph
+ */
+
+import ParagraphCommand from './paragraphcommand';
+import InsertParagraphCommand from './insertparagraphcommand';
+
+import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
+
+/**
+ * The paragraph feature for the editor.
+ *
+ * It introduces the `<paragraph>` element in the model which renders as a `<p>` element in the DOM and data.
+ *
+ * It also brings two editors commands:
+ *
+ * * The {@link module:paragraph/paragraphcommand~ParagraphCommand `'paragraph'`} command that converts all
+ * blocks in the model selection into paragraphs.
+ * * The {@link module:paragraph/insertparagraphcommand~InsertParagraphCommand `'insertParagraph'`} command
+ * that inserts a new paragraph at a specified location in the model.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class Paragraph extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'Paragraph';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const editor = this.editor;
+		const model = editor.model;
+
+		editor.commands.add( 'paragraph', new ParagraphCommand( editor ) );
+		editor.commands.add( 'insertParagraph', new InsertParagraphCommand( editor ) );
+
+		// Schema.
+		model.schema.register( 'paragraph', { inheritAllFrom: '$block' } );
+
+		editor.conversion.elementToElement( { model: 'paragraph', view: 'p' } );
+
+		// Conversion for paragraph-like elements which has not been converted by any plugin.
+		editor.conversion.for( 'upcast' ).elementToElement( {
+			model: ( viewElement, { writer } ) => {
+				if ( !Paragraph.paragraphLikeElements.has( viewElement.name ) ) {
+					return null;
+				}
+
+				// Do not auto-paragraph empty elements.
+				if ( viewElement.isEmpty ) {
+					return null;
+				}
+
+				return writer.createElement( 'paragraph' );
+			},
+			view: /.+/,
+			converterPriority: 'low'
+		} );
+	}
+}
+
+/**
+ * A list of element names which should be treated by the autoparagraphing algorithms as
+ * paragraph-like. This means that e.g. the following content:
+ *
+ *		<h1>Foo</h1>
+ *		<table>
+ *			<tr>
+ *				<td>X</td>
+ *				<td>
+ *					<ul>
+ *						<li>Y</li>
+ *						<li>Z</li>
+ *					</ul>
+ *				</td>
+ *			</tr>
+ *		</table>
+ *
+ * contains five paragraph-like elements: `<h1>`, two `<td>`s and two `<li>`s.
+ * Hence, if none of the features is going to convert those elements the above content will be automatically handled
+ * by the paragraph feature and converted to:
+ *
+ *		<p>Foo</p>
+ *		<p>X</p>
+ *		<p>Y</p>
+ *		<p>Z</p>
+ *
+ * Note: The `<td>` containing two `<li>` elements was ignored as the innermost paragraph-like elements
+ * have a priority upon conversion.
+ *
+ * @member {Set.<String>} module:paragraph/paragraph~Paragraph.paragraphLikeElements
+ */
+Paragraph.paragraphLikeElements = new Set( [
+	'blockquote',
+	'dd',
+	'div',
+	'dt',
+	'h1',
+	'h2',
+	'h3',
+	'h4',
+	'h5',
+	'h6',
+	'li',
+	'p',
+	'td',
+	'th'
+] );

package/src/paragraphbuttonui.js

@@ -0,0 +1,54 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module paragraph/paragraphbuttonui
+ */
+
+import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
+import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';
+import icon from '../theme/icons/paragraph.svg';
+
+/**
+ * This plugin defines the `'paragraph'` button. It can be used together with
+ * {@link module:heading/headingbuttonsui~HeadingButtonsUI} to replace the standard heading dropdown.
+ *
+ * This plugin is not loaded automatically by the {@link module:paragraph/paragraph~Paragraph} plugin. It must
+ * be added manually.
+ *
+ *		ClassicEditor
+ *			.create( {
+ *				plugins: [ ..., Heading, Paragraph, HeadingButtonsUI, ParagraphButtonUI ]
+ *				toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3' ]
+ *			} )
+ *			.then( ... )
+ *			.catch( ... );
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class ParagraphButtonUI extends Plugin {
+	init() {
+		const editor = this.editor;
+		const t = editor.t;
+
+		editor.ui.componentFactory.add( 'paragraph', locale => {
+			const view = new ButtonView( locale );
+			const command = editor.commands.get( 'paragraph' );
+
+			view.label = t( 'Paragraph' );
+			view.icon = icon;
+			view.tooltip = true;
+			view.isToggleable = true;
+			view.bind( 'isEnabled' ).to( command );
+			view.bind( 'isOn' ).to( command, 'value' );
+
+			view.on( 'execute', () => {
+				editor.execute( 'paragraph' );
+			} );
+
+			return view;
+		} );
+	}
+}

package/src/paragraphcommand.js

@@ -0,0 +1,73 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module paragraph/paragraphcommand
+ */
+
+import Command from '@ckeditor/ckeditor5-core/src/command';
+import first from '@ckeditor/ckeditor5-utils/src/first';
+
+/**
+ * The paragraph command.
+ *
+ * @extends module:core/command~Command
+ */
+export default class ParagraphCommand extends Command {
+	/**
+	 * The value of the command. Indicates whether the selection start is placed in a paragraph.
+	 *
+	 * @readonly
+	 * @observable
+	 * @member {Boolean} #value
+	 */
+
+	/**
+	 * @inheritDoc
+	 */
+	refresh() {
+		const model = this.editor.model;
+		const document = model.document;
+		const block = first( document.selection.getSelectedBlocks() );
+
+		this.value = !!block && block.is( 'element', 'paragraph' );
+		this.isEnabled = !!block && checkCanBecomeParagraph( block, model.schema );
+	}
+
+	/**
+	 * Executes the command. All the blocks (see {@link module:engine/model/schema~Schema}) in the selection
+	 * will be turned to paragraphs.
+	 *
+	 * @fires execute
+	 * @param {Object} [options] Options for the executed command.
+	 * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} [options.selection]
+	 * The selection that the command should be applied to.
+	 * By default, if not provided, the command is applied to the {@link module:engine/model/document~Document#selection}.
+	 */
+	execute( options = {} ) {
+		const model = this.editor.model;
+		const document = model.document;
+
+		model.change( writer => {
+			const blocks = ( options.selection || document.selection ).getSelectedBlocks();
+
+			for ( const block of blocks ) {
+				if ( !block.is( 'element', 'paragraph' ) && checkCanBecomeParagraph( block, model.schema ) ) {
+					writer.rename( block, 'paragraph' );
+				}
+			}
+		} );
+	}
+}
+
+// Checks whether the given block can be replaced by a paragraph.
+//
+// @private
+// @param {module:engine/model/element~Element} block A block to be tested.
+// @param {module:engine/model/schema~Schema} schema The schema of the document.
+// @returns {Boolean}
+function checkCanBecomeParagraph( block, schema ) {
+	return schema.checkChild( block.parent, 'paragraph' ) && !schema.isObject( block );
+}

package/theme/icons/paragraph.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg"><path d="M10.5 5.5H7v5h3.5a2.5 2.5 0 1 0 0-5zM5 3h6.5v.025a5 5 0 0 1 0 9.95V13H7v4a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1z"/></svg>