@ckeditor/ckeditor5-engine 35.4.0 → 36.0.0

package/src/model/utils/deletecontent.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
@@ -16,12 +16,9 @@ import Range from '../range';
  * which change the {@link module:engine/model/model~Model#deleteContent}
  * method's behavior.
  *
- * @param {module:engine/model/model~Model} model The model in context of which the insertion
- * should be performed.
- * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
- * Selection of which the content should be deleted.
- * @param {Object} [options]
- * @param {Boolean} [options.leaveUnmerged=false] Whether to merge elements after removing the content of the selection.
+ * @param model The model in context of which the insertion should be performed.
+ * @param selection Selection of which the content should be deleted.
+ * @param options.leaveUnmerged Whether to merge elements after removing the content of the selection.
  *
  * For example `<heading>x[x</heading><paragraph>y]y</paragraph>` will become:
  *
@@ -31,7 +28,7 @@ import Range from '../range';
  * Note: {@link module:engine/model/schema~Schema#isObject object} and {@link module:engine/model/schema~Schema#isLimit limit}
  * elements will not be merged.
  *
- * @param {Boolean} [options.doNotResetEntireContent=false] Whether to skip replacing the entire content with a
+ * @param options.doNotResetEntireContent Whether to skip replacing the entire content with a
  * paragraph when the entire content was selected.
  *
  * For example `<heading>[x</heading><paragraph>y]</paragraph>` will become:
@@ -39,7 +36,7 @@ import Range from '../range';
  * * `<paragraph>^</paragraph>` with the option disabled (`doNotResetEntireContent == false`)
  * * `<heading>^</heading>` with enabled (`doNotResetEntireContent == true`).
  *
- * @param {Boolean} [options.doNotAutoparagraph=false] Whether to create a paragraph if after content deletion selection is moved
+ * @param options.doNotAutoparagraph Whether to create a paragraph if after content deletion selection is moved
  * to a place where text cannot be inserted.
  *
  * For example `<paragraph>x</paragraph>[<imageBlock src="foo.jpg"></imageBlock>]` will become:
@@ -114,13 +111,17 @@ export default function deleteContent(model, selection, options = {}) {
         endPosition.detach();
     });
 }
-// Returns the live positions for the range adjusted to span only blocks selected from the user perspective. Example:
-//
-//     <heading1>[foo</heading1>
-//     <paragraph>bar</paragraph>
-//     <heading1>]abc</heading1>  <-- this block is not considered as selected
-//
-// This is the same behavior as in Selection#getSelectedBlocks() "special case".
+/**
+ * Returns the live positions for the range adjusted to span only blocks selected from the user perspective. Example:
+ *
+ * ```
+ * <heading1>[foo</heading1>
+ * <paragraph>bar</paragraph>
+ * <heading1>]abc</heading1>  <-- this block is not considered as selected
+ * ```
+ *
+ * This is the same behavior as in Selection#getSelectedBlocks() "special case".
+ */
 function getLivePositionsForSelectedBlocks(range) {
     const model = range.root.document.model;
     const startPosition = range.start;
@@ -154,8 +155,10 @@ function getLivePositionsForSelectedBlocks(range) {
         LivePosition.fromPosition(endPosition, 'toNext')
     ];
 }
-// Finds the lowest element in position's ancestors which is a block.
-// Returns null if a limit element is encountered before reaching a block element.
+/**
+ * Finds the lowest element in position's ancestors which is a block.
+ * Returns null if a limit element is encountered before reaching a block element.
+ */
 function getParentBlock(position) {
     const element = position.parent;
     const schema = element.root.document.model.schema;
@@ -169,8 +172,10 @@ function getParentBlock(position) {
         }
     }
 }
-// This function is a result of reaching the Ballmer's peak for just the right amount of time.
-// Even I had troubles documenting it after a while and after reading it again I couldn't believe that it really works.
+/**
+ * This function is a result of reaching the Ballmer's peak for just the right amount of time.
+ * Even I had troubles documenting it after a while and after reading it again I couldn't believe that it really works.
+ */
 function mergeBranches(writer, startPosition, endPosition) {
     const model = writer.model;
     // Verify if there is a need and possibility to merge.
@@ -220,19 +225,26 @@ function mergeBranches(writer, startPosition, endPosition) {
         mergeBranchesLeft(writer, startPosition, endPosition, startAncestor.parent);
     }
 }
-// Merging blocks to the left (properties of the left block are preserved).
-// Simple example:
-//     <heading1>foo[</heading1>    ->  <heading1>foo[bar</heading1>]
-//     <paragraph>]bar</paragraph>  ->              --^
-//
-// Nested example:
-//     <blockQuote>                     ->  <blockQuote>
-//         <heading1>foo[</heading1>    ->      <heading1>foo[bar</heading1>
-//     </blockQuote>                    ->  </blockQuote>]    ^
-//     <blockBlock>                     ->                    |
-//         <paragraph>]bar</paragraph>  ->                 ---
-//     </blockBlock>                    ->
-//
+/**
+ * Merging blocks to the left (properties of the left block are preserved).
+ * Simple example:
+ *
+ * ```
+ * <heading1>foo[</heading1>    ->  <heading1>foo[bar</heading1>]
+ * <paragraph>]bar</paragraph>  ->              --^
+ * ```
+ *
+ * Nested example:
+ *
+ * ```
+ * <blockQuote>                     ->  <blockQuote>
+ *     <heading1>foo[</heading1>    ->      <heading1>foo[bar</heading1>
+ * </blockQuote>                    ->  </blockQuote>]    ^
+ * <blockBlock>                     ->                    |
+ *     <paragraph>]bar</paragraph>  ->                 ---
+ * </blockBlock>                    ->
+ * ```
+ */
 function mergeBranchesLeft(writer, startPosition, endPosition, commonAncestor) {
     const startElement = startPosition.parent;
     const endElement = endPosition.parent;
@@ -289,19 +301,26 @@ function mergeBranchesLeft(writer, startPosition, endPosition, commonAncestor) {
     // Continue merging next level (blockQuote with blockBlock in the examples above if it would not be empty and got removed).
     mergeBranchesLeft(writer, startPosition, endPosition, commonAncestor);
 }
-// Merging blocks to the right (properties of the right block are preserved).
-// Simple example:
-//     <heading1>foo[</heading1>    ->            --v
-//     <paragraph>]bar</paragraph>  ->  [<paragraph>foo]bar</paragraph>
-//
-// Nested example:
-//     <blockQuote>                     ->
-//         <heading1>foo[</heading1>    ->              ---
-//     </blockQuote>                    ->                 |
-//     <blockBlock>                     ->  [<blockBlock>  v
-//         <paragraph>]bar</paragraph>  ->      <paragraph>foo]bar</paragraph>
-//     </blockBlock>                    ->  </blockBlock>
-//
+/**
+ * Merging blocks to the right (properties of the right block are preserved).
+ * Simple example:
+ *
+ * ```
+ * <heading1>foo[</heading1>    ->            --v
+ * <paragraph>]bar</paragraph>  ->  [<paragraph>foo]bar</paragraph>
+ * ```
+ *
+ * Nested example:
+ *
+ * ```
+ * <blockQuote>                     ->
+ *     <heading1>foo[</heading1>    ->              ---
+ * </blockQuote>                    ->                 |
+ * <blockBlock>                     ->  [<blockBlock>  v
+ *     <paragraph>]bar</paragraph>  ->      <paragraph>foo]bar</paragraph>
+ * </blockBlock>                    ->  </blockBlock>
+ * ```
+ */
 function mergeBranchesRight(writer, startPosition, endPosition, commonAncestor) {
     const startElement = startPosition.parent;
     const endElement = endPosition.parent;
@@ -359,7 +378,9 @@ function mergeBranchesRight(writer, startPosition, endPosition, commonAncestor)
     // Continue merging next level (blockQuote with blockBlock in the examples above if it would not be empty and got removed).
     mergeBranchesRight(writer, startPosition, endPosition, commonAncestor);
 }
-// There is no right merge operation so we need to simulate it.
+/**
+ * There is no right merge operation so we need to simulate it.
+ */
 function mergeRight(writer, position) {
     const startElement = position.nodeBefore;
     const endElement = position.nodeAfter;
@@ -370,8 +391,10 @@ function mergeRight(writer, position) {
     writer.setAttributes(Object.fromEntries(endElement.getAttributes()), startElement);
     writer.merge(position);
 }
-// Verifies if merging is needed and possible. It's not needed if both positions are in the same element
-// and it's not possible if some element is a limit or the range crosses a limit element.
+/**
+ * Verifies if merging is needed and possible. It's not needed if both positions are in the same element
+ * and it's not possible if some element is a limit or the range crosses a limit element.
+ */
 function checkShouldMerge(schema, startPosition, endPosition) {
     const startElement = startPosition.parent;
     const endElement = endPosition.parent;
@@ -389,7 +412,9 @@ function checkShouldMerge(schema, startPosition, endPosition) {
     // <limit><startElement>x[</startElement></limit><endElement>]</endElement>
     return isCrossingLimitElement(startPosition, endPosition, schema);
 }
-// Returns the elements that are the ancestors of the provided positions that are direct children of the common ancestor.
+/**
+ * Returns the elements that are the ancestors of the provided positions that are direct children of the common ancestor.
+ */
 function getAncestorsJustBelowCommonAncestor(positionA, positionB) {
     const ancestorsA = positionA.getAncestors();
     const ancestorsB = positionB.getAncestors();
@@ -404,12 +429,14 @@ function shouldAutoparagraph(schema, position) {
     const isParagraphAllowed = schema.checkChild(position, 'paragraph');
     return !isTextAllowed && isParagraphAllowed;
 }
-// Check if parents of two positions can be merged by checking if there are no limit/object
-// boundaries between those two positions.
-//
-// E.g. in <bQ><p>x[]</p></bQ><widget><caption>{}</caption></widget>
-// we'll check <p>, <bQ>, <widget> and <caption>.
-// Usually, widget and caption are marked as objects/limits in the schema, so in this case merging will be blocked.
+/**
+ * Check if parents of two positions can be merged by checking if there are no limit/object
+ * boundaries between those two positions.
+ *
+ * E.g. in <bQ><p>x[]</p></bQ><widget><caption>{}</caption></widget>
+ * we'll check <p>, <bQ>, <widget> and <caption>.
+ * Usually, widget and caption are marked as objects/limits in the schema, so in this case merging will be blocked.
+ */
 function isCrossingLimitElement(leftPos, rightPos, schema) {
     const rangeToCheck = new Range(leftPos, rightPos);
     for (const value of rangeToCheck.getWalker()) {
@@ -430,10 +457,12 @@ function replaceEntireContentWithParagraph(writer, selection) {
     writer.remove(writer.createRangeIn(limitElement));
     insertParagraph(writer, writer.createPositionAt(limitElement, 0), selection);
 }
-// We want to replace the entire content with a paragraph when:
-// * the entire content is selected,
-// * selection contains at least two elements,
-// * whether the paragraph is allowed in schema in the common ancestor.
+/**
+ * We want to replace the entire content with a paragraph when:
+ * * the entire content is selected,
+ * * selection contains at least two elements,
+ * * whether the paragraph is allowed in schema in the common ancestor.
+ */
 function shouldEntireContentBeReplacedWithParagraph(schema, selection) {
     const limitElement = schema.getLimitElement(selection);
     if (!selection.containsEntireContent(limitElement)) {
@@ -445,8 +474,10 @@ function shouldEntireContentBeReplacedWithParagraph(schema, selection) {
     }
     return schema.checkChild(limitElement, 'paragraph');
 }
-// Helper function that sets the selection. Depending whether given `selection` is a document selection or not,
-// uses a different method to set it.
+/**
+ * Helper function that sets the selection. Depending whether given `selection` is a document selection or not,
+ * uses a different method to set it.
+ */
 function collapseSelectionAt(writer, selection, positionOrRange) {
     if (selection instanceof DocumentSelection) {
         writer.setSelection(positionOrRange);

package/src/model/utils/findoptimalinsertionrange.js

@@ -1,34 +1,34 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
  * @module engine/model/utils/findoptimalinsertionrange
  */
 import { first } from '@ckeditor/ckeditor5-utils';
-// Returns a model range 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 collapsed range before this paragraph
-// will be returned so that it is not split. If the selection is at the end of a paragraph,
-// the collapsed range after this paragraph will be returned.
-//
-// Note: If the selection is placed in an empty block, the range in that block will be returned. If that range
-// is then passed to {@link module:engine/model/model~Model#insertContent}, the block will be fully replaced
-// by the inserted widget block.
-//
-// **Note:** Use {@link module:widget/utils#findOptimalInsertionRange} instead of this function outside engine.
-// This function is only exposed to be used by {@link module:widget/utils#findOptimalInsertionRange findOptimalInsertionRange()}
-// in the `widget` package and inside the `engine` package.
-//
-// @private
-// @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
-// The selection based on which the insertion position should be calculated.
-// @param {module:engine/model/model~Model} model Model instance.
-// @param {'auto'|'before'|'after'} [place='auto'] The place where to look for optimal insertion range.
-// The default `auto` value will determine itself the best position for insertion.
-// The `before` value will try to find a position before selection.
-// The `after` value will try to find a position after selection.
-// @returns {module:engine/model/range~Range} The optimal range.
+/**
+ * Returns a model range 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 collapsed range before this paragraph
+ * will be returned so that it is not split. If the selection is at the end of a paragraph,
+ * the collapsed range after this paragraph will be returned.
+ *
+ * Note: If the selection is placed in an empty block, the range in that block will be returned. If that range
+ * is then passed to {@link module:engine/model/model~Model#insertContent}, the block will be fully replaced
+ * by the inserted widget block.
+ *
+ * **Note:** Use {@link module:widget/utils#findOptimalInsertionRange} instead of this function outside engine.
+ * This function is only exposed to be used by {@link module:widget/utils#findOptimalInsertionRange findOptimalInsertionRange()}
+ * in the `widget` package and inside the `engine` package.
+ *
+ * @param selection The selection based on which the insertion position should be calculated.
+ * @param model Model instance.
+ * @param place The place where to look for optimal insertion range.
+ * The default `auto` value will determine itself the best position for insertion.
+ * The `before` value will try to find a position before selection.
+ * The `after` value will try to find a position after selection.
+ * @returns The optimal range.
+ */
 export function findOptimalInsertionRange(selection, model, place = 'auto') {
     const selectedElement = selection.getSelectedElement();
     if (selectedElement && model.schema.isObject(selectedElement) && !model.schema.isInline(selectedElement)) {

package/src/model/utils/getselectedcontent.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
@@ -20,11 +20,8 @@
  * <quote><h>st</h></quote><p>se</p>
  * ```
  *
- * @param {module:engine/model/model~Model} model The model in context of which
- * the selection modification should be performed.
- * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
- * The selection of which content will be returned.
- * @returns {module:engine/model/documentfragment~DocumentFragment}
+ * @param model The model in context of which the selection modification should be performed.
+ * @param selection The selection of which content will be returned.
  */
 export default function getSelectedContent(model, selection) {
     return model.change(writer => {