@ckeditor/ckeditor5-widget - npm Package Compare versions

Comparing version 10.2.0 to 10.3.0

CHANGELOG.md

 Changelog
 =========
 
+## [10.3.0](https://github.com/ckeditor/ckeditor5-widget/compare/v10.2.0...v10.3.0) (2018-10-08)
+
+### Features
+
+* Introduced the `findOptimalInsertionPostion()` utility function. ([9c0d4ce](https://github.com/ckeditor/ckeditor5-widget/commit/9c0d4ce))
+* Introduced the widget toolbar repository. Closes [ckeditor/ckeditor5-ui#442](https://github.com/ckeditor/ckeditor5-ui/issues/442). ([bc45176](https://github.com/ckeditor/ckeditor5-widget/commit/bc45176))
+
+
 ## [10.2.0](https://github.com/ckeditor/ckeditor5-widget/compare/v10.1.0...v10.2.0) (2018-07-18)
@@ -5,0 +13,0 @@

package.json

 {
   "name": "@ckeditor/ckeditor5-widget",
-  "version": "10.2.0",
+  "version": "10.3.0",
   "description": "Widget API for CKEditor 5.",
@@ -12,11 +12,16 @@ "keywords": [
   "dependencies": {
-    "@ckeditor/ckeditor5-core": "^11.0.0",
-    "@ckeditor/ckeditor5-engine": "^10.2.0",
-    "@ckeditor/ckeditor5-utils": "^10.2.0",
-    "@ckeditor/ckeditor5-theme-lark": "^11.0.0",
-    "@ckeditor/ckeditor5-ui": "^11.0.0"
+    "@ckeditor/ckeditor5-core": "^11.0.1",
+    "@ckeditor/ckeditor5-engine": "^11.0.0",
+    "@ckeditor/ckeditor5-utils": "^11.0.0",
+    "@ckeditor/ckeditor5-theme-lark": "^11.1.0",
+    "@ckeditor/ckeditor5-ui": "^11.1.0"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-typing": "^11.0.0",
-    "eslint": "^4.15.0",
+    "@ckeditor/ckeditor5-basic-styles": "^10.0.3",
+    "@ckeditor/ckeditor5-editor-balloon": "^11.0.1",
+    "@ckeditor/ckeditor5-editor-classic": "^11.0.1",
+    "@ckeditor/ckeditor5-essentials": "^10.1.2",
+    "@ckeditor/ckeditor5-paragraph": "^10.0.3",
+    "@ckeditor/ckeditor5-typing": "^11.0.1",
+    "eslint": "^5.5.0",
     "eslint-config-ckeditor5": "^1.0.7",
@@ -23,0 +28,0 @@ "husky": "^0.14.3",

README.md

@@ -17,3 +17,3 @@ CKEditor 5 widget API
 
-See the [`@ckeditor/ckeditor5-widget` package](https://docs.ckeditor.com/ckeditor5/latest/api/widget.html) page in [CKEditor 5 documentation](https://docs.ckeditor.com/ckeditor5/latest/).
+See the [`@ckeditor/ckeditor5-widget` package](https://ckeditor.com/docs/ckeditor5/latest/api/widget.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
 
@@ -20,0 +20,0 @@ ## License

src/highlightstack.js

@@ -37,3 +37,3 @@ /**
 	 * @param {module:engine/conversion/downcast-converters~HighlightDescriptor} descriptor
-	 * @param {module:engine/view/writer~Writer} writer
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer
 	 */
@@ -63,3 +63,3 @@ add( descriptor, writer ) {
 	 * @param {String} id Id of the descriptor to remove.
-	 * @param {module:engine/view/writer~Writer} writer
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer
 	 */
@@ -177,3 +177,3 @@ remove( id, writer ) {
  * descriptor. It will be `undefined` when first descriptor is added to the stack.
- * @param {module:engine/view/writer~Writer} writer View writer that can be used to modify element.
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer View writer that can be used to modify element.
  */

src/utils.js

@@ -11,3 +11,4 @@ /**
 import HighlightStack from './highlightstack';
-import Position from '@ckeditor/ckeditor5-engine/src/view/position';
+import ViewPosition from '@ckeditor/ckeditor5-engine/src/view/position';
+import ModelPosition from '@ckeditor/ckeditor5-engine/src/model/position';
 import IconView from '@ckeditor/ckeditor5-ui/src/icon/iconview';
@@ -47,13 +48,42 @@ import env from '@ckeditor/ckeditor5-utils/src/env';
  * Converts given {@link module:engine/view/element~Element} to widget in following way:
+ *
  * * sets `contenteditable` attribute to `"true"`,
- * * adds custom `getFillerOffset` method returning `null`,
  * * adds `ck-widget` CSS class,
- * * adds custom property allowing to recognize widget elements by using {@link ~isWidget},
- * * implements `addHighlight` and `removeHighlight` custom properties to handle view highlight on widgets.
+ * * adds custom {@link module:engine/view/element~Element#getFillerOffset `getFillerOffset()`} method returning `null`,
+ * * adds custom property allowing to recognize widget elements by using {@link ~isWidget `isWidget()`},
+ * * implements {@link ~setHighlightHandling view highlight on widgets}.
  *
+ * This function needs to be used in conjuction with {@link module:engine/conversion/downcast-converters downcast converters}
+ * like {@link module:engine/conversion/downcast-converters~downcastElementToElement `downcastElementToElement()`}.
+ * Moreover, typically you will want to use `toWidget()` only for `editingDowncast`, while keeping the `dataDowncast` clean.
+ *
+ * For example, in order to convert a `<widget>` model element to `<div class="widget">` in the view, you can define
+ * such converters:
+ *
+ *		editor.conversion.for( 'editingDowncast' )
+ *			.add( downcastElementToElement( {
+ *				model: 'widget',
+ *				view: ( modelItem, writer ) => {
+ *					const div = writer.createContainerElement( 'div', { class: 'widget' } );
+ *
+ *					return toWidget( div, writer, { label: 'some widget' } );
+ *				}
+ *			} ) );
+ *
+ *		editor.conversion.for( 'dataDowncast' )
+ *			.add( downcastElementToElement( {
+ *				model: 'widget',
+ *				view: ( modelItem, writer ) => {
+ *					return writer.createContainerElement( 'div', { class: 'widget' } );
+ *				}
+ *			} ) );
+ *
+ * See a full source code of a widget (with nested editable) schema definition and converters in
+ * [this sample](https://github.com/ckeditor/ckeditor5-widget/blob/master/tests/manual/widget-with-nestededitable.js).
+ *
  * @param {module:engine/view/element~Element} element
- * @param {module:engine/view/writer~Writer} writer
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer
  * @param {Object} [options={}]
  * @param {String|Function} [options.label] Element's label provided to {@link ~setLabel} function. It can be passed as
- * a plain string or a function returning a string.
+ * a plain string or a function returning a string. It represents the widget for assistive technologies (like screen readers).
  * @param {Boolean} [options.hasSelectionHandler=false] If `true`, the widget will have a selection handler added.
@@ -101,3 +131,3 @@ * @returns {module:engine/view/element~Element} Returns same element.
  * @param {module:engine/view/element~Element} element
- * @param {module:engine/view/writer~Writer} writer
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer
  * @param {Function} add
@@ -126,7 +156,7 @@ * @param {Function} remove
  * It can be passed as a plain string or a function returning a string. Function will be called each time label is retrieved by
- * {@link ~getLabel}.
+ * {@link ~getLabel `getLabel()`}.
  *
  * @param {module:engine/view/element~Element} element
  * @param {String|Function} labelOrCreator
- * @param {module:engine/view/writer~Writer} writer
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer
  */
@@ -138,3 +168,3 @@ export function setLabel( element, labelOrCreator, writer ) {
 /**
- * Returns label for provided element.
+ * Returns the label of the provided element.
  *
@@ -155,10 +185,38 @@ * @param {module:engine/view/element~Element} element
 /**
- * Adds functionality to provided {module:engine/view/editableelement~EditableElement} to act as a widget's editable:
+ * Adds functionality to a provided {@link module:engine/view/editableelement~EditableElement} to act as a widget's editable:
+ *
+ * * sets `contenteditable` as `true` when {@link module:engine/view/editableelement~EditableElement#isReadOnly} is `false`
+ * otherwise set `false`,
  * * adds `ck-editor__editable` and `ck-editor__nested-editable` CSS classes,
- * * sets `contenteditable` as `true` when {module:engine/view/editableelement~EditableElement#isReadOnly} is `false`
- * otherwise set `false`,
- * * adds `ck-editor__nested-editable_focused` CSS class when editable is focused and removes it when it's blurred.
+ * * adds `ck-editor__nested-editable_focused` CSS class when editable is focused and removes it when it is blurred.
  *
+ * Similarly to {@link ~toWidget `toWidget()`} this function should be used in `dataDowncast` only and it is usually
+ * used together with {@link module:engine/conversion/downcast-converters~downcastElementToElement `downcastElementToElement()`}.
+ *
+ * For example, in order to convert a `<nested>` model element to `<div class="nested">` in the view, you can define
+ * such converters:
+ *
+ *		editor.conversion.for( 'editingDowncast' )
+ *			.add( downcastElementToElement( {
+ *				model: 'nested',
+ *				view: ( modelItem, writer ) => {
+ *					const div = writer.createEditableElement( 'div', { class: 'nested' } );
+ *
+ *					return toWidgetEditable( nested, writer );
+ *				}
+ *			} ) );
+ *
+ *		editor.conversion.for( 'dataDowncast' )
+ *			.add( downcastElementToElement( {
+ *				model: 'nested',
+ *				view: ( modelItem, writer ) => {
+ *					return writer.createContainerElement( 'div', { class: 'nested' } );
+ *				}
+ *			} ) );
+ *
+ * See a full source code of a widget (with nested editable) schema definition and converters in
+ * [this sample](https://github.com/ckeditor/ckeditor5-widget/blob/master/tests/manual/widget-with-nestededitable.js).
+ *
  * @param {module:engine/view/editableelement~EditableElement} editable
- * @param {module:engine/view/writer~Writer} writer
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer
  * @returns {module:engine/view/editableelement~EditableElement} Returns same element that was provided in `editable` param.
@@ -192,2 +250,47 @@ */
 
+/**
+ * Returns a model position which is optimal (in terms of UX) for inserting a widget block.
+ *
+ * For instance, if a selection is in the middle of a paragraph, the position before this paragraph
+ * will be returned so that it is not split. If the selection is at the end of a paragraph,
+ * the position after this paragraph will be returned.
+ *
+ * Note: If the selection is placed in an empty block, that block will be returned. If that position
+ * is then passed to {@link module:engine/model/model~Model#insertContent},
+ * the block will be fully replaced by the image.
+ *
+ * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+ * The selection based on which the insertion position should be calculated.
+ * @returns {module:engine/model/position~Position} The optimal position.
+ */
+export function findOptimalInsertionPosition( selection ) {
+	const selectedElement = selection.getSelectedElement();
+
+	if ( selectedElement ) {
+		return ModelPosition.createAfter( selectedElement );
+	}
+
+	const firstBlock = selection.getSelectedBlocks().next().value;
+
+	if ( firstBlock ) {
+		// If inserting into an empty block – return position in that block. It will get
+		// replaced with the image by insertContent(). #42.
+		if ( firstBlock.isEmpty ) {
+			return ModelPosition.createAt( firstBlock );
+		}
+
+		const positionAfter = ModelPosition.createAfter( firstBlock );
+
+		// If selection is at the end of the block - return position after the block.
+		if ( selection.focus.isTouching( positionAfter ) ) {
+			return positionAfter;
+		}
+
+		// Otherwise return position before the block.
+		return ModelPosition.createBefore( firstBlock );
+	}
+
+	return selection.focus;
+}
+
 // Default filler offset function applied to all widget elements.
@@ -203,3 +306,3 @@ //
 // @param {module:engine/view/editableelement~EditableElement}
-// @param {module:engine/view/writer~Writer} writer
+// @param {module:engine/view/downcastwriter~DowncastWriter} writer
 function addSelectionHandler( editable, writer ) {
@@ -222,4 +325,4 @@ const selectionHandler = writer.createUIElement( 'div', { class: 'ck ck-widget__selection-handler' }, function( domDocument ) {
 	// Append the selection handler into the widget wrapper.
-	writer.insert( Position.createAt( editable ), selectionHandler );
+	writer.insert( ViewPosition.createAt( editable ), selectionHandler );
 	writer.addClass( [ 'ck-widget_selectable' ], editable );
 }

src/widget.js

@@ -25,7 +25,13 @@ /**
 /**
- * The widget plugin.
- * Registers model to view selection converter for editing pipeline. It is hooked after default selection conversion.
- * If converted selection is placed around widget element, selection is marked as fake. Additionally, proper CSS class
+ * The widget plugin. It enables base support for widgets.
+ *
+ * See {@glink api/widget package page} for more details and documentation.
+ *
+ * This plugin enables multiple behaiors required by the widgets:
+ *
+ * * The model to view selection converter for the editing pipeline (it handles widget custom selection rendering).
+ * If a converted selection is wraps around a widget element, that selection is marked as
+ * {@link module:engine/view/selection~Selection#isFake fake}. Additionally, proper the `ck-widget_selected` CSS class
  * is added to indicate that widget has been selected.
- * Adds default {@link module:engine/view/document~Document#event:mousedown mousedown} handling on widget elements.
+ * * The mouse and keyboard events handling on and around widget elements.
  *
@@ -378,3 +384,3 @@ * @extends module:core/plugin~Plugin.
 	 * @private
-	 * @param {module:engine/view/writer~Writer} writer
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer
 	 */
@@ -381,0 +387,0 @@ _clearPreviouslySelectedWidgets( writer ) {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

50668

increased by33.12%

Number of package files

10

increased by11.11%

Lines of code

1027

increased by43.44%

Worsened metrics

Dev dependency count

10

increased by100%

Dependency changes

• + Added@ckeditor/ckeditor5-engine@11.0.0(transitive)

• - Removed@ckeditor/ckeditor5-engine@10.2.0(transitive)

• - Removed@ckeditor/ckeditor5-utils@10.2.1(transitive)

• Updated@ckeditor/ckeditor5-core@^11.0.1

• Updated@ckeditor/ckeditor5-engine@^11.0.0

• Updated@ckeditor/ckeditor5-theme-lark@^11.1.0

• Updated@ckeditor/ckeditor5-ui@^11.1.0

• Updated@ckeditor/ckeditor5-utils@^11.0.0