Merge pull request #1 from ckeditor/t/ckeditor/1365

Feature: Initial implementation of the feature. Closes ckeditor/ckeditor5#1365.

docs/_snippets/features/horizontal-rule.html

@@ -0,0 +1,6 @@
+<div id="snippet-horizontal-rule">
+	<h1>What is Lorem Ipsum?</h1>
+	<p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry’s standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.</p>
+	<hr>
+	<p>It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.</p>
+</div>

docs/_snippets/features/horizontal-rule.js

@@ -0,0 +1,61 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window, document, console */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import HorizontalRule from '@ckeditor/ckeditor5-horizontal-rule/src/horizontalrule';
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor.builtinPlugins.push( HorizontalRule );
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-horizontal-rule' ), {
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'bulletedList',
+				'numberedList',
+				'blockQuote',
+				'link',
+				'|',
+				'imageUpload',
+				'mediaEmbed',
+				'insertTable',
+				'horizontalRule',
+				'|',
+				'undo',
+				'redo',
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		image: {
+			styles: [
+				'full',
+				'alignLeft',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:full',
+				'imageStyle:alignRight',
+				'|',
+				'imageTextAlternative'
+			]
+		},
+		table: {
+			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells' ]
+		},
+		cloudServices: CS_CONFIG
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

docs/api/horizontal-rule.md

@@ -0,0 +1,34 @@
+---
+category: api-reference
+---
+
+# Horizontal rule feature for CKEditor 5
+
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-horizontal-rule.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-horizontal-rule)
+
+This package implements the horizontal rule feature for CKEditor 5.
+
+## Demo
+
+Check out the {@link features/horizontal-rule#demo demo in the Horizontal rule feature} guide.
+
+## Documentation
+
+See the {@link features/horizontal-rule Horizontal rule feature} guide and the {@link module:horizontal-rule/horizontalrule~HorizontalRule} plugin documentation.
+
+## Installation
+
+```bash
+npm install --save @ckeditor/ckeditor5-horizontal-rule
+```
+
+## Contribute
+
+The source code of this package is available on GitHub in https://github.com/ckeditor/ckeditor5-horizontal-rule.
+
+## External links
+
+* [`@ckeditor/ckeditor5-horizontal-rule` on npm](https://www.npmjs.com/package/@ckeditor/ckeditor5-horizontal-rule)
+* [`ckeditor/ckeditor5-horizontal-rule` on GitHub](https://github.com/ckeditor/ckeditor5-horizontal-rule)
+* [Issue tracker](https://github.com/ckeditor/ckeditor5/issues)
+* [Changelog](https://github.com/ckeditor/ckeditor5-horizontal-rule/blob/master/CHANGELOG.md)

docs/features/horizontal-rule.md

@@ -0,0 +1,55 @@
+---
+category: features
+menu-title: Horizontal rule
+---
+
+# Horizontal rule
+
+The {@link module:horizontal-rule/horizontalrule~HorizontalRule} plugin provides a possibility to insert a horizontal rule in the rich-text editor.
+
+## Demo
+
+Use the editor below to see the {@link module:horizontal-rule/horizontalrule~HorizontalRule} plugin in action.
+
+{@snippet features/horizontal-rule}
+
+## Installation
+
+To add this feature to your rich-text editor, install the [`@ckeditor/ckeditor5-horizontal-rule`](https://www.npmjs.com/package/@ckeditor/ckeditor5-horizontal-rule) package:
+
+```bash
+npm install --save @ckeditor/ckeditor5-horizontal-rule
+```
+
+And add it to your plugin list configuration:
+
+```js
+import HorizontalRule from '@ckeditor/ckeditor5-horizontal-rule/src/horizontalrule';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ HorizontalRule, ... ],
+		toolbar: [ 'horizontalRule', ... ],
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+
+## Common API
+
+The {@link module:horizontal-rule/horizontalrule~HorizontalRule} plugin registers the UI button component (`'horizontalRule'`) and the `'horizontalRule'` command implemented by {@link module:horizontal-rule/horizontalrulecommand~HorizontalRuleCommand}. 
+
+The command can be executed using the {@link module:core/editor/editor~Editor#execute `editor.execute()`} method:
+
+```js
+// Inserts the horizontal rule to the selected content.
+editor.execute( 'horizontalRule' );
+```
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-horizontal-rule.

lang/contexts.json

@@ -0,0 +1,3 @@
+{
+	"Horizontal rule": "Horizontal rule"
+}

package.json

@@ -10,8 +10,16 @@
     "ckeditor5-plugin"
   ],
   "dependencies": {
+    "@ckeditor/ckeditor5-core": "^12.2.1",
+    "@ckeditor/ckeditor5-ui": "^14.0.0",
+    "@ckeditor/ckeditor5-widget": "^11.0.4"
   },
   "devDependencies": {
+    "@ckeditor/ckeditor5-cloud-services": "^11.0.5",
+    "@ckeditor/ckeditor5-editor-classic": "^12.1.3",
+    "@ckeditor/ckeditor5-easy-image": "^11.0.5",
+    "@ckeditor/ckeditor5-image": "^14.0.0",
+    "@ckeditor/ckeditor5-paragraph": "^11.0.5",
     "eslint": "^5.5.0",
     "eslint-config-ckeditor5": "^2.0.0",
     "husky": "^1.3.1",

src/horizontalrule.js

@@ -0,0 +1,33 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module horizontal-rule/horizontalrule
+ */
+
+import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
+import HorizontalRuleEditing from './horizontalruleediting';
+import HorizontalRuleUI from './horizontalruleui';
+
+/**
+ * The horizontal rule plugin provides a possibility to insert a horizontal rule in the rich-text editor.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class HorizontalRule extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ HorizontalRuleEditing, HorizontalRuleUI ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'HorizontalRule';
+	}
+}

src/horizontalrulecommand.js

@@ -0,0 +1,98 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module horizontal-rule/horizontalrulecommand
+ */
+
+import Command from '@ckeditor/ckeditor5-core/src/command';
+import { findOptimalInsertionPosition } from '@ckeditor/ckeditor5-widget/src/utils';
+
+/**
+ * The insert a horizontal rule command.
+ *
+ * The command is registered by the {@link module:horizontal-rule/horizontalruleediting~HorizontalRuleEditing} as `'horizontalRule'`.
+ *
+ * To insert the horizontal rule at the current selection, execute the command:
+ *
+ *		editor.execute( 'horizontalRule' );
+ *
+ * @extends module:core/command~Command
+ */
+export default class HorizontalRuleCommand extends Command {
+	/**
+	 * @inheritDoc
+	 */
+	refresh() {
+		this.isEnabled = isHorizontalRuleAllowed( this.editor.model );
+	}
+
+	/**
+	 * Executes the command.
+	 *
+	 * @fires execute
+	 */
+	execute() {
+		const model = this.editor.model;
+
+		model.change( writer => {
+			const modelElement = writer.createElement( 'horizontalRule' );
+
+			model.insertContent( modelElement );
+		} );
+	}
+}
+
+// Checks if the `horizontalRule` element can be inserted at current model selection.
+//
+// @param {module:engine/model/model~Model} model
+// @returns {Boolean}
+function isHorizontalRuleAllowed( model ) {
+	const schema = model.schema;
+	const selection = model.document.selection;
+
+	return isHorizontalRuleAllowedInParent( selection, schema, model ) &&
+		!checkSelectionOnObject( selection, schema );
+}
+
+// Checks if horizontal rule is allowed by schema in optimal insertion parent.
+//
+// @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+// @param {module:engine/model/schema~Schema} schema
+// @param {module:engine/model/model~Model} model Model instance.
+// @returns {Boolean}
+function isHorizontalRuleAllowedInParent( selection, schema, model ) {
+	const parent = getInsertHorizontalRuleParent( selection, model );
+
+	return schema.checkChild( parent, 'horizontalRule' );
+}
+
+// Check if selection is on object.
+//
+// @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+// @param {module:engine/model/schema~Schema} schema
+// @returns {Boolean}
+function checkSelectionOnObject( selection, schema ) {
+	const selectedElement = selection.getSelectedElement();
+
+	return selectedElement && schema.isObject( selectedElement );
+}
+
+// Returns a node that will be used to insert horizontal rule with `model.insertContent` to check if horizontal rule can be placed there.
+//
+// @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+// @param {module:engine/model/model~Model} model Model instance.
+// @returns {module:engine/model/element~Element}
+function getInsertHorizontalRuleParent( selection, model ) {
+	const insertAt = findOptimalInsertionPosition( selection, model );
+
+	const parent = insertAt.parent;
+
+	if ( parent.isEmpty && !parent.is( '$root' ) ) {
+		return parent.parent;
+	}
+
+	return parent;
+}

src/horizontalruleediting.js

@@ -0,0 +1,78 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module horizontal-rule/horizontalruleediting
+ */
+
+import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
+import HorizontalRuleCommand from './horizontalrulecommand';
+import { toWidget } from '@ckeditor/ckeditor5-widget/src/utils';
+
+import '../theme/horizontalrule.css';
+
+/**
+ * The horizontal rule editing feature.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class HorizontalRuleEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const editor = this.editor;
+		const schema = editor.model.schema;
+		const t = editor.t;
+		const conversion = editor.conversion;
+
+		schema.register( 'horizontalRule', {
+			isObject: true,
+			allowWhere: '$block'
+		} );
+
+		conversion.for( 'dataDowncast' ).elementToElement( {
+			model: 'horizontalRule',
+			view: ( modelElement, viewWriter ) => {
+				return viewWriter.createEmptyElement( 'hr' );
+			}
+		} );
+
+		conversion.for( 'editingDowncast' ).elementToElement( {
+			model: 'horizontalRule',
+			view: ( modelElement, viewWriter ) => {
+				const label = t( 'Horizontal rule' );
+				const viewWrapper = viewWriter.createContainerElement( 'div' );
+				const viewHrElement = viewWriter.createEmptyElement( 'hr' );
+
+				viewWriter.addClass( 'ck-horizontal-rule', viewWrapper );
+				viewWriter.setCustomProperty( 'hr', true, viewWrapper );
+
+				viewWriter.insert( viewWriter.createPositionAt( viewWrapper, 0 ), viewHrElement );
+
+				return toHorizontalRuleWidget( viewWrapper, viewWriter, label );
+			}
+		} );
+
+		conversion.for( 'upcast' ).elementToElement( { view: 'hr', model: 'horizontalRule' } );
+
+		editor.commands.add( 'horizontalRule', new HorizontalRuleCommand( editor ) );
+	}
+}
+
+// Converts a given {@link module:engine/view/element~Element} to a horizontal rule widget:
+// * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to
+//   recognize the horizontal rule widget element.
+// * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
+//
+//  @param {module:engine/view/element~Element} viewElement
+//  @param {module:engine/view/downcastwriter~DowncastWriter} writer An instance of the view writer.
+//  @param {String} label The element's label.
+//  @returns {module:engine/view/element~Element}
+function toHorizontalRuleWidget( viewElement, writer, label ) {
+	writer.setCustomProperty( 'horizontalRule', true, viewElement );
+
+	return toWidget( viewElement, writer, { label } );
+}