@ckeditor/ckeditor5-list 32.0.0 → 34.0.1

package/src/documentlist/utils/model.js

@@ -0,0 +1,534 @@
+/**
+ * @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 list/documentlist/utils/model
+ */
+
+import { uid, toArray } from 'ckeditor5/src/utils';
+import ListWalker, { iterateSiblingListBlocks } from './listwalker';
+
+/**
+ * The list item ID generator.
+ *
+ * @protected
+ */
+export class ListItemUid {
+	/**
+	 * Returns the next ID.
+	 *
+	 * @protected
+	 * @returns {String}
+	 */
+	/* istanbul ignore next: static function definition */
+	static next() {
+		return uid();
+	}
+}
+
+/**
+ * Returns true if the given model node is a list item block.
+ *
+ * @protected
+ * @param {module:engine/model/node~Node} node A model node.
+ * @returns {Boolean}
+ */
+export function isListItemBlock( node ) {
+	return !!node && node.is( 'element' ) && node.hasAttribute( 'listItemId' );
+}
+
+/**
+ * Returns an array with all elements that represents the same list item.
+ *
+ * It means that values for `listIndent`, and `listItemId` for all items are equal.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element} listItem Starting list item element.
+ * @param {Object} [options]
+ * @param {Boolean} [options.higherIndent=false] Whether blocks with a higher indent level than the start block should be included
+ * in the result.
+ * @return {Array.<module:engine/model/element~Element>}
+ */
+export function getAllListItemBlocks( listItem, options = {} ) {
+	return [
+		...getListItemBlocks( listItem, { ...options, direction: 'backward' } ),
+		...getListItemBlocks( listItem, { ...options, direction: 'forward' } )
+	];
+}
+
+/**
+ * Returns an array with elements that represents the same list item in the specified direction.
+ *
+ * It means that values for `listIndent` and `listItemId` for all items are equal.
+ *
+ * **Note**: For backward search the provided item is not included, but for forward search it is included in the result.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element} listItem Starting list item element.
+ * @param {Object} [options]
+ * @param {'forward'|'backward'} [options.direction='backward'] Walking direction.
+ * @param {Boolean} [options.higherIndent=false] Whether blocks with a higher indent level than the start block should be included
+ * in the result.
+ * @returns {Array.<module:engine/model/element~Element>}
+ */
+export function getListItemBlocks( listItem, options = {} ) {
+	const isForward = options.direction == 'forward';
+
+	const items = Array.from( new ListWalker( listItem, {
+		...options,
+		includeSelf: isForward,
+		sameIndent: true,
+		sameAttributes: 'listItemId'
+	} ) );
+
+	return isForward ? items : items.reverse();
+}
+
+/**
+ * Returns a list items nested inside the given list item.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element} listItem Starting list item element.
+ * @returns {Array.<module:engine/model/element~Element>}
+ */
+export function getNestedListBlocks( listItem ) {
+	return Array.from( new ListWalker( listItem, {
+		direction: 'forward',
+		higherIndent: true
+	} ) );
+}
+
+/**
+ * Returns array of all blocks/items of the same list as given block (same indent, same type and properties).
+ *
+ * @protected
+ * @param {module:engine/model/element~Element} listItem Starting list item element.
+ * @returns {Array.<module:engine/model/element~Element>}
+ */
+export function getListItems( listItem ) {
+	const backwardBlocks = new ListWalker( listItem, {
+		sameIndent: true,
+		sameAttributes: 'listType'
+	} );
+
+	const forwardBlocks = new ListWalker( listItem, {
+		sameIndent: true,
+		sameAttributes: 'listType',
+		includeSelf: true,
+		direction: 'forward'
+	} );
+
+	return [
+		...Array.from( backwardBlocks ).reverse(),
+		...forwardBlocks
+	];
+}
+
+/**
+ * Check if the given block is the first in the list item.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element} listBlock The list block element.
+ * @returns {Boolean}
+ */
+export function isFirstBlockOfListItem( listBlock ) {
+	const previousSibling = ListWalker.first( listBlock, {
+		sameIndent: true,
+		sameAttributes: 'listItemId'
+	} );
+
+	if ( !previousSibling ) {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Check if the given block is the last in the list item.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element} listBlock The list block element.
+ * @returns {Boolean}
+ */
+export function isLastBlockOfListItem( listBlock ) {
+	const nextSibling = ListWalker.first( listBlock, {
+		direction: 'forward',
+		sameIndent: true,
+		sameAttributes: 'listItemId'
+	} );
+
+	if ( !nextSibling ) {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Expands the given list of selected blocks to include the leading and tailing blocks of partially selected list items.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element|Array.<module:engine/model/element~Element>} blocks The list of selected blocks.
+ * @param {Object} [options]
+ * @param {Boolean} [options.withNested=true] Whether should include nested list items.
+ * @returns {Array.<module:engine/model/element~Element>}
+ */
+export function expandListBlocksToCompleteItems( blocks, options = {} ) {
+	blocks = toArray( blocks );
+
+	const higherIndent = options.withNested !== false;
+	const allBlocks = new Set();
+
+	for ( const block of blocks ) {
+		for ( const itemBlock of getAllListItemBlocks( block, { higherIndent } ) ) {
+			allBlocks.add( itemBlock );
+		}
+	}
+
+	return sortBlocks( allBlocks );
+}
+
+/**
+ * Expands the given list of selected blocks to include all the items of the lists they're in.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element|Array.<module:engine/model/element~Element>} blocks The list of selected blocks.
+ * @returns {Array.<module:engine/model/element~Element>}
+ */
+export function expandListBlocksToCompleteList( blocks ) {
+	blocks = toArray( blocks );
+
+	const allBlocks = new Set();
+
+	for ( const block of blocks ) {
+		for ( const itemBlock of getListItems( block ) ) {
+			allBlocks.add( itemBlock );
+		}
+	}
+
+	return sortBlocks( allBlocks );
+}
+
+/**
+ * Splits the list item just before the provided list block.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element} listBlock The list block element.
+ * @param {module:engine/model/writer~Writer} writer The model writer.
+ * @returns {Array.<module:engine/model/element~Element>} The array of updated blocks.
+ */
+export function splitListItemBefore( listBlock, writer ) {
+	const blocks = getListItemBlocks( listBlock, { direction: 'forward' } );
+	const id = ListItemUid.next();
+
+	for ( const block of blocks ) {
+		writer.setAttribute( 'listItemId', id, block );
+	}
+
+	return blocks;
+}
+
+/**
+ * Merges the list item with the parent list item.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element} listBlock The list block element.
+ * @param {module:engine/model/element~Element} parentBlock The list block element to merge with.
+ * @param {module:engine/model/writer~Writer} writer The model writer.
+ * @returns {Array.<module:engine/model/element~Element>} The array of updated blocks.
+ */
+export function mergeListItemBefore( listBlock, parentBlock, writer ) {
+	const attributes = {};
+
+	for ( const [ key, value ] of parentBlock.getAttributes() ) {
+		if ( key.startsWith( 'list' ) ) {
+			attributes[ key ] = value;
+		}
+	}
+
+	const blocks = getListItemBlocks( listBlock, { direction: 'forward' } );
+
+	for ( const block of blocks ) {
+		writer.setAttributes( attributes, block );
+	}
+
+	return blocks;
+}
+
+/**
+ * Increases indentation of given list blocks.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element|Iterable.<module:engine/model/element~Element>} blocks The block or iterable of blocks.
+ * @param {module:engine/model/writer~Writer} writer The model writer.
+ * @param {Object} [options]
+ * @param {Boolean} [options.expand=false] Whether should expand the list of blocks to include complete list items.
+ * @param {Number} [options.indentBy=1] The number of levels the indentation should change (could be negative).
+ */
+export function indentBlocks( blocks, writer, { expand, indentBy = 1 } = {} ) {
+	blocks = toArray( blocks );
+
+	// Expand the selected blocks to contain the whole list items.
+	const allBlocks = expand ? expandListBlocksToCompleteItems( blocks ) : blocks;
+
+	for ( const block of allBlocks ) {
+		const blockIndent = block.getAttribute( 'listIndent' ) + indentBy;
+
+		if ( blockIndent < 0 ) {
+			removeListAttributes( block, writer );
+		} else {
+			writer.setAttribute( 'listIndent', blockIndent, block );
+		}
+	}
+
+	return allBlocks;
+}
+
+/**
+ * Decreases indentation of given list of blocks. If the indentation of some blocks matches the indentation
+ * of surrounding blocks, they get merged together.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element|Iterable.<module:engine/model/element~Element>} blocks The block or iterable of blocks.
+ * @param {module:engine/model/writer~Writer} writer The model writer.
+ */
+export function outdentBlocksWithMerge( blocks, writer ) {
+	blocks = toArray( blocks );
+
+	// Expand the selected blocks to contain the whole list items.
+	const allBlocks = expandListBlocksToCompleteItems( blocks );
+	const visited = new Set();
+
+	const referenceIndent = Math.min( ...allBlocks.map( block => block.getAttribute( 'listIndent' ) ) );
+	const parentBlocks = new Map();
+
+	// Collect parent blocks before the list structure gets altered.
+	for ( const block of allBlocks ) {
+		parentBlocks.set( block, ListWalker.first( block, { lowerIndent: true } ) );
+	}
+
+	for ( const block of allBlocks ) {
+		if ( visited.has( block ) ) {
+			continue;
+		}
+
+		visited.add( block );
+
+		const blockIndent = block.getAttribute( 'listIndent' ) - 1;
+
+		if ( blockIndent < 0 ) {
+			removeListAttributes( block, writer );
+
+			continue;
+		}
+
+		// Merge with parent list item while outdenting and indent matches reference indent.
+		if ( block.getAttribute( 'listIndent' ) == referenceIndent ) {
+			const mergedBlocks = mergeListItemIfNotLast( block, parentBlocks.get( block ), writer );
+
+			// All list item blocks are updated while merging so add those to visited set.
+			for ( const mergedBlock of mergedBlocks ) {
+				visited.add( mergedBlock );
+			}
+
+			// The indent level was updated while merging so continue to next block.
+			if ( mergedBlocks.length ) {
+				continue;
+			}
+		}
+
+		writer.setAttribute( 'listIndent', blockIndent, block );
+	}
+
+	return sortBlocks( visited );
+}
+
+/**
+ * Removes all list attributes from the given blocks.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element|Iterable.<module:engine/model/element~Element>} blocks The block or iterable of blocks.
+ * @param {module:engine/model/writer~Writer} writer The model writer.
+ * @returns {Array.<module:engine/model/element~Element>} Array of altered blocks.
+ */
+export function removeListAttributes( blocks, writer ) {
+	blocks = toArray( blocks );
+
+	for ( const block of blocks ) {
+		for ( const attributeKey of block.getAttributeKeys() ) {
+			if ( attributeKey.startsWith( 'list' ) ) {
+				writer.removeAttribute( attributeKey, block );
+			}
+		}
+	}
+
+	return blocks;
+}
+
+/**
+ * Checks whether the given blocks are related to a single list item.
+ *
+ * @protected
+ * @param {Array.<module:engine/model/element~Element>} blocks The list block elements.
+ * @returns {Boolean}
+ */
+export function isSingleListItem( blocks ) {
+	if ( !blocks.length ) {
+		return false;
+	}
+
+	const firstItemId = blocks[ 0 ].getAttribute( 'listItemId' );
+
+	if ( !firstItemId ) {
+		return false;
+	}
+
+	return !blocks.some( item => item.getAttribute( 'listItemId' ) != firstItemId );
+}
+
+/**
+ * Modifies the indents of list blocks following the given list block so the indentation is valid after
+ * the given block is no longer a list item.
+ *
+ * @protected
+ * @param {module:engine/model/element~Element} lastBlock The last list block that has become a non-list element.
+ * @param {module:engine/model/writer~Writer} writer The model writer.
+ * @returns {Array.<module:engine/model/element~Element>} Array of altered blocks.
+ */
+export function outdentFollowingItems( lastBlock, writer ) {
+	const changedBlocks = [];
+
+	// Start from the model item that is just after the last turned-off item.
+	let currentIndent = Number.POSITIVE_INFINITY;
+
+	// Correct indent of all items after the last turned off item.
+	// Rules that should be followed:
+	// 1. All direct sub-items of turned-off item should become indent 0, because the first item after it
+	//    will be the first item of a new list. Other items are at the same level, so should have same 0 index.
+	// 2. All items with indent lower than indent of turned-off item should become indent 0, because they
+	//    should not end up as a child of any of list items that they were not children of before.
+	// 3. All other items should have their indent changed relatively to it's parent.
+	//
+	// For example:
+	// 1  * --------
+	// 2     * --------
+	// 3        * --------			<-- this is turned off.
+	// 4           * --------		<-- this has to become indent = 0, because it will be first item on a new list.
+	// 5              * --------	<-- this should be still be a child of item above, so indent = 1.
+	// 6        * --------			<-- this has to become indent = 0, because it should not be a child of any of items above.
+	// 7           * --------		<-- this should be still be a child of item above, so indent = 1.
+	// 8     * --------				<-- this has to become indent = 0.
+	// 9        * --------			<-- this should still be a child of item above, so indent = 1.
+	// 10          * --------		<-- this should still be a child of item above, so indent = 2.
+	// 11          * --------		<-- this should still be at the same level as item above, so indent = 2.
+	// 12 * --------				<-- this and all below are left unchanged.
+	// 13    * --------
+	// 14       * --------
+	//
+	// After turning off 3 the list becomes:
+	//
+	// 1  * --------
+	// 2     * --------
+	//
+	// 3  --------
+	//
+	// 4  * --------
+	// 5     * --------
+	// 6  * --------
+	// 7     * --------
+	// 8  * --------
+	// 9     * --------
+	// 10       * --------
+	// 11       * --------
+	// 12 * --------
+	// 13    * --------
+	// 14       * --------
+	//
+	// Thanks to this algorithm no lists are mismatched and no items get unexpected children/parent, while
+	// those parent-child connection which are possible to maintain are still maintained. It's worth noting
+	// that this is the same effect that we would be get by multiple use of outdent command. However doing
+	// it like this is much more efficient because it's less operation (less memory usage, easier OT) and
+	// less conversion (faster).
+	for ( const { node } of iterateSiblingListBlocks( lastBlock.nextSibling, 'forward' ) ) {
+		// Check each next list item, as long as its indent is higher than 0.
+		const indent = node.getAttribute( 'listIndent' );
+
+		// If the indent is 0 we are not going to change anything anyway.
+		if ( indent == 0 ) {
+			break;
+		}
+
+		// We check if that's item indent is lower than current relative indent.
+		if ( indent < currentIndent ) {
+			// If it is, current relative indent becomes that indent.
+			currentIndent = indent;
+		}
+
+		// Fix indent relatively to current relative indent.
+		// Note, that if we just changed the current relative indent, the newIndent will be equal to 0.
+		const newIndent = indent - currentIndent;
+
+		writer.setAttribute( 'listIndent', newIndent, node );
+		changedBlocks.push( node );
+	}
+
+	return changedBlocks;
+}
+
+/**
+ * Returns the array of given blocks sorted by model indexes (document order).
+ *
+ * @protected
+ * @param {Iterable.<module:engine/model/element~Element>} blocks The array of blocks.
+ * @returns {Array.<module:engine/model/element~Element>} The sorted array of blocks.
+ */
+export function sortBlocks( blocks ) {
+	return Array.from( blocks )
+		.filter( block => block.root.rootName !== '$graveyard' )
+		.sort( ( a, b ) => a.index - b.index );
+}
+
+/**
+ * Returns a selected block object. If a selected object is inline or when there is no selected
+ * object, `null` is returned.
+ *
+ * @protected
+ * @param {module:engine/model/model~Model} model The instance of editor model.
+ * @returns {module:engine/model/element~Element|null} Selected block object or `null`.
+ */
+export function getSelectedBlockObject( model ) {
+	const selectedElement = model.document.selection.getSelectedElement();
+
+	if ( !selectedElement ) {
+		return null;
+	}
+
+	if ( model.schema.isObject( selectedElement ) && model.schema.isBlock( selectedElement ) ) {
+		return selectedElement;
+	}
+
+	return null;
+}
+
+// Merges a given block to the given parent block if parent is a list item and there is no more blocks in the same item.
+function mergeListItemIfNotLast( block, parentBlock, writer ) {
+	const parentItemBlocks = getListItemBlocks( parentBlock, { direction: 'forward' } );
+
+	// Merge with parent only if outdented item wasn't the last one in its parent.
+	// Merge:
+	// * a			->		* a
+	//   * [b]		->		  b
+	//   c			->		  c
+	// Don't merge:
+	// * a			->		* a
+	//   * [b]		-> 		* b
+	// * c			->		* c
+	if ( parentItemBlocks.pop().index > block.index ) {
+		return mergeListItemBefore( block, parentBlock, writer );
+	}
+
+	return [];
+}

package/src/documentlist/utils/postfixers.js

@@ -0,0 +1,138 @@
+/**
+ * @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 list/documentlist/utils/postfixers
+ */
+
+import { iterateSiblingListBlocks } from './listwalker';
+import { getListItemBlocks, isListItemBlock, ListItemUid } from './model';
+
+/**
+ * Based on the provided positions looks for the list head and stores it in the provided map.
+ *
+ * @protected
+ * @param {module:engine/model/position~Position} position The search starting position.
+ * @param {Map.<module:engine/model/element~Element,module:engine/model/element~Element>} itemToListHead The map from list item element
+ * to the list head element.
+ */
+export function findAndAddListHeadToMap( position, itemToListHead ) {
+	const previousNode = position.nodeBefore;
+
+	if ( !isListItemBlock( previousNode ) ) {
+		const item = position.nodeAfter;
+
+		if ( isListItemBlock( item ) ) {
+			itemToListHead.set( item, item );
+		}
+	} else {
+		let listHead = previousNode;
+
+		for ( { node: listHead } of iterateSiblingListBlocks( listHead, 'backward' ) ) {
+			if ( itemToListHead.has( listHead ) ) {
+				return;
+			}
+		}
+
+		itemToListHead.set( previousNode, listHead );
+	}
+}
+
+/**
+ * Scans the list starting from the given list head element and fixes items' indentation.
+ *
+ * @protected
+ * @param {Iterable.<module:list/documentlist/utils/listwalker~ListIteratorValue>} listNodes The iterable of list nodes.
+ * @param {module:engine/model/writer~Writer} writer The model writer.
+ * @returns {Boolean} Whether the model was modified.
+ */
+export function fixListIndents( listNodes, writer ) {
+	let maxIndent = 0; // Guards local sublist max indents that need fixing.
+	let prevIndent = -1; // Previous item indent.
+	let fixBy = null;
+	let applied = false;
+
+	for ( const { node } of listNodes ) {
+		const itemIndent = node.getAttribute( 'listIndent' );
+
+		if ( itemIndent > maxIndent ) {
+			let newIndent;
+
+			if ( fixBy === null ) {
+				fixBy = itemIndent - maxIndent;
+				newIndent = maxIndent;
+			} else {
+				if ( fixBy > itemIndent ) {
+					fixBy = itemIndent;
+				}
+
+				newIndent = itemIndent - fixBy;
+			}
+
+			if ( newIndent > prevIndent + 1 ) {
+				newIndent = prevIndent + 1;
+			}
+
+			writer.setAttribute( 'listIndent', newIndent, node );
+
+			applied = true;
+			prevIndent = newIndent;
+		} else {
+			fixBy = null;
+			maxIndent = itemIndent + 1;
+			prevIndent = itemIndent;
+		}
+	}
+
+	return applied;
+}
+
+/**
+ * Scans the list starting from the given list head element and fixes items' types.
+ *
+ * @protected
+ * @param {Iterable.<module:list/documentlist/utils/listwalker~ListIteratorValue>} listNodes The iterable of list nodes.
+ * @param {Set.<String>} seenIds The set of already known IDs.
+ * @param {module:engine/model/writer~Writer} writer The model writer.
+ * @returns {Boolean} Whether the model was modified.
+ */
+export function fixListItemIds( listNodes, seenIds, writer ) {
+	const visited = new Set();
+	let applied = false;
+
+	for ( const { node } of listNodes ) {
+		if ( visited.has( node ) ) {
+			continue;
+		}
+
+		let listType = node.getAttribute( 'listType' );
+		let listItemId = node.getAttribute( 'listItemId' );
+
+		// Use a new ID if this one was spot earlier (even in other list).
+		if ( seenIds.has( listItemId ) ) {
+			listItemId = ListItemUid.next();
+		}
+
+		seenIds.add( listItemId );
+
+		for ( const block of getListItemBlocks( node, { direction: 'forward' } ) ) {
+			visited.add( block );
+
+			// Use a new ID if a block of a bigger list item has different type.
+			if ( block.getAttribute( 'listType' ) != listType ) {
+				listItemId = ListItemUid.next();
+				listType = block.getAttribute( 'listType' );
+			}
+
+			if ( block.getAttribute( 'listItemId' ) != listItemId ) {
+				writer.setAttribute( 'listItemId', listItemId, block );
+
+				applied = true;
+			}
+		}
+	}
+
+	return applied;
+}