@ckeditor/ckeditor5-list 0.0.0-internal-20241017.0

package/src/list/listutils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module list/list/listutils
+ */
+import type { Element, Node } from 'ckeditor5/src/engine.js';
+import type { ArrayOrItem } from 'ckeditor5/src/utils.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+import { type ListElement } from './utils/model.js';
+import type { ListType } from './listediting.js';
+/**
+ * A set of helpers related to document lists.
+ */
+export default class ListUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ListUtils";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * Expands the given list of selected blocks to include all the items of the lists they're in.
+     *
+     * @param blocks The list of selected blocks.
+     */
+    expandListBlocksToCompleteList(blocks: ArrayOrItem<Element>): Array<Element>;
+    /**
+     * Check if the given block is the first in the list item.
+     *
+     * @param listBlock The list block element.
+     */
+    isFirstBlockOfListItem(listBlock: Element): boolean;
+    /**
+     * Returns true if the given model node is a list item block.
+     *
+     * @param node A model node.
+     */
+    isListItemBlock(node: Node | null): node is ListElement;
+    /**
+     * Expands the given list of selected blocks to include the leading and tailing blocks of partially selected list items.
+     *
+     * @param blocks The list of selected blocks.
+     * @param options.withNested Whether should include nested list items.
+     */
+    expandListBlocksToCompleteItems(blocks: ArrayOrItem<Element>, options?: {
+        withNested?: boolean;
+    }): Array<Element>;
+    /**
+     * Returns true if listType is of type `numbered` or `customNumbered`.
+     */
+    isNumberedListType(listType: ListType): boolean;
+}

package/src/list/listutils.js

@@ -0,0 +1,62 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import { expandListBlocksToCompleteItems, expandListBlocksToCompleteList, isFirstBlockOfListItem, isListItemBlock, isNumberedListType } from './utils/model.js';
+/**
+ * A set of helpers related to document lists.
+ */
+export default class ListUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'ListUtils';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * Expands the given list of selected blocks to include all the items of the lists they're in.
+     *
+     * @param blocks The list of selected blocks.
+     */
+    expandListBlocksToCompleteList(blocks) {
+        return expandListBlocksToCompleteList(blocks);
+    }
+    /**
+     * Check if the given block is the first in the list item.
+     *
+     * @param listBlock The list block element.
+     */
+    isFirstBlockOfListItem(listBlock) {
+        return isFirstBlockOfListItem(listBlock);
+    }
+    /**
+     * Returns true if the given model node is a list item block.
+     *
+     * @param node A model node.
+     */
+    isListItemBlock(node) {
+        return isListItemBlock(node);
+    }
+    /**
+     * Expands the given list of selected blocks to include the leading and tailing blocks of partially selected list items.
+     *
+     * @param blocks The list of selected blocks.
+     * @param options.withNested Whether should include nested list items.
+     */
+    expandListBlocksToCompleteItems(blocks, options = {}) {
+        return expandListBlocksToCompleteItems(blocks, options);
+    }
+    /**
+     * Returns true if listType is of type `numbered` or `customNumbered`.
+     */
+    isNumberedListType(listType) {
+        return isNumberedListType(listType);
+    }
+}

package/src/list/utils/listwalker.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module list/list/utils/listwalker
+ */
+import { type ArrayOrItem } from 'ckeditor5/src/utils.js';
+import { type ListElement } from './model.js';
+import type { Element, Node } from 'ckeditor5/src/engine.js';
+/**
+ * Document list blocks iterator.
+ */
+export default class ListWalker {
+    /**
+     * The start list item block element.
+     */
+    private _startElement;
+    /**
+     * The reference indent. Initialized by the indent of the start block.
+     */
+    private _referenceIndent;
+    /**
+     * The iterating direction.
+     */
+    private _isForward;
+    /**
+     * Whether start block should be included in the result (if it's matching other criteria).
+     */
+    private _includeSelf;
+    /**
+     * Additional attributes that must be the same for each block.
+     */
+    private _sameAttributes;
+    /**
+     * Whether blocks with the same indent level as the start block should be included in the result.
+     */
+    private _sameIndent;
+    /**
+     * Whether blocks with a lower indent level than the start block should be included in the result.
+     */
+    private _lowerIndent;
+    /**
+     * Whether blocks with a higher indent level than the start block should be included in the result.
+     */
+    private _higherIndent;
+    /**
+     * Creates a document list iterator.
+     *
+     * @param startElement The start list item block element.
+     * @param options.direction The iterating direction.
+     * @param options.includeSelf Whether start block should be included in the result (if it's matching other criteria).
+     * @param options.sameAttributes Additional attributes that must be the same for each block.
+     * @param options.sameIndent Whether blocks with the same indent level as the start block should be included
+     * in the result.
+     * @param options.lowerIndent Whether blocks with a lower indent level than the start block should be included
+     * in the result.
+     * @param options.higherIndent Whether blocks with a higher indent level than the start block should be included
+     * in the result.
+     */
+    constructor(startElement: Node, options: ListWalkerOptions);
+    /**
+     * Performs only first step of iteration and returns the result.
+     *
+     * @param startElement The start list item block element.
+     * @param options.direction The iterating direction.
+     * @param options.includeSelf Whether start block should be included in the result (if it's matching other criteria).
+     * @param options.sameAttributes Additional attributes that must be the same for each block.
+     * @param options.sameIndent Whether blocks with the same indent level as the start block should be included
+     * in the result.
+     * @param options.lowerIndent Whether blocks with a lower indent level than the start block should be included
+     * in the result.
+     * @param options.higherIndent Whether blocks with a higher indent level than the start block should be included
+     * in the result.
+     */
+    static first(startElement: Node, options: ListWalkerOptions): ListElement | null;
+    /**
+     * Iterable interface.
+     */
+    [Symbol.iterator](): Iterator<ListElement>;
+    /**
+     * Returns the model element to start iterating.
+     */
+    private _getStartNode;
+}
+/**
+ * Iterates sibling list blocks starting from the given node.
+ *
+ * @internal
+ * @param node The model node.
+ * @param direction Iteration direction.
+ * @returns The object with `node` and `previous` {@link module:engine/model/element~Element blocks}.
+ */
+export declare function iterateSiblingListBlocks(node: Node | null, direction?: 'forward' | 'backward'): IterableIterator<ListIteratorValue>;
+/**
+ * The iterable protocol over the list elements.
+ *
+ * @internal
+ */
+export declare class ListBlocksIterable {
+    private _listHead;
+    /**
+     * @param listHead The head element of a list.
+     */
+    constructor(listHead: Element);
+    /**
+     * List blocks iterator.
+     *
+     * Iterates over all blocks of a list.
+     */
+    [Symbol.iterator](): Iterator<ListIteratorValue>;
+}
+/**
+ * Object returned by `iterateSiblingListBlocks()` when traversing a list.
+ *
+ * @internal
+ */
+export interface ListIteratorValue {
+    /**
+     * The current list node.
+     */
+    node: ListElement;
+    /**
+     * The previous list node.
+     */
+    previous: ListElement | null;
+    /**
+     * The previous list node at the same indent as current node.
+     */
+    previousNodeInList: ListElement | null;
+}
+/**
+ * Document list blocks iterator options.
+ */
+export type ListWalkerOptions = {
+    direction?: 'forward' | 'backward';
+    includeSelf?: boolean;
+    sameAttributes?: ArrayOrItem<string>;
+    sameIndent?: boolean;
+    lowerIndent?: boolean;
+    higherIndent?: boolean;
+};

package/src/list/utils/listwalker.js

@@ -0,0 +1,182 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module list/list/utils/listwalker
+ */
+import { first, toArray } from 'ckeditor5/src/utils.js';
+import { isListItemBlock } from './model.js';
+/**
+ * Document list blocks iterator.
+ */
+export default class ListWalker {
+    /**
+     * Creates a document list iterator.
+     *
+     * @param startElement The start list item block element.
+     * @param options.direction The iterating direction.
+     * @param options.includeSelf Whether start block should be included in the result (if it's matching other criteria).
+     * @param options.sameAttributes Additional attributes that must be the same for each block.
+     * @param options.sameIndent Whether blocks with the same indent level as the start block should be included
+     * in the result.
+     * @param options.lowerIndent Whether blocks with a lower indent level than the start block should be included
+     * in the result.
+     * @param options.higherIndent Whether blocks with a higher indent level than the start block should be included
+     * in the result.
+     */
+    constructor(startElement, options) {
+        this._startElement = startElement;
+        this._referenceIndent = startElement.getAttribute('listIndent');
+        this._isForward = options.direction == 'forward';
+        this._includeSelf = !!options.includeSelf;
+        this._sameAttributes = toArray(options.sameAttributes || []);
+        this._sameIndent = !!options.sameIndent;
+        this._lowerIndent = !!options.lowerIndent;
+        this._higherIndent = !!options.higherIndent;
+    }
+    /**
+     * Performs only first step of iteration and returns the result.
+     *
+     * @param startElement The start list item block element.
+     * @param options.direction The iterating direction.
+     * @param options.includeSelf Whether start block should be included in the result (if it's matching other criteria).
+     * @param options.sameAttributes Additional attributes that must be the same for each block.
+     * @param options.sameIndent Whether blocks with the same indent level as the start block should be included
+     * in the result.
+     * @param options.lowerIndent Whether blocks with a lower indent level than the start block should be included
+     * in the result.
+     * @param options.higherIndent Whether blocks with a higher indent level than the start block should be included
+     * in the result.
+     */
+    static first(startElement, options) {
+        const walker = new this(startElement, options);
+        const iterator = walker[Symbol.iterator]();
+        return first(iterator);
+    }
+    /**
+     * Iterable interface.
+     */
+    *[Symbol.iterator]() {
+        const nestedItems = [];
+        for (const { node } of iterateSiblingListBlocks(this._getStartNode(), this._isForward ? 'forward' : 'backward')) {
+            const indent = node.getAttribute('listIndent');
+            // Leaving a nested list.
+            if (indent < this._referenceIndent) {
+                // Abort searching blocks.
+                if (!this._lowerIndent) {
+                    break;
+                }
+                // While searching for lower indents, update the reference indent to find another parent in the next step.
+                this._referenceIndent = indent;
+            }
+            // Entering a nested list.
+            else if (indent > this._referenceIndent) {
+                // Ignore nested blocks.
+                if (!this._higherIndent) {
+                    continue;
+                }
+                // Collect nested blocks to verify if they are really nested, or it's a different item.
+                if (!this._isForward) {
+                    nestedItems.push(node);
+                    continue;
+                }
+            }
+            // Same indent level block.
+            else {
+                // Ignore same indent block.
+                if (!this._sameIndent) {
+                    // While looking for nested blocks, stop iterating while encountering first same indent block.
+                    if (this._higherIndent) {
+                        // No more nested blocks so yield nested items.
+                        if (nestedItems.length) {
+                            yield* nestedItems;
+                            nestedItems.length = 0;
+                        }
+                        break;
+                    }
+                    continue;
+                }
+                // Abort if item has any additionally specified attribute different.
+                if (this._sameAttributes.some(attr => node.getAttribute(attr) !== this._startElement.getAttribute(attr))) {
+                    break;
+                }
+            }
+            // There is another block for the same list item so the nested items were in the same list item.
+            if (nestedItems.length) {
+                yield* nestedItems;
+                nestedItems.length = 0;
+            }
+            yield node;
+        }
+    }
+    /**
+     * Returns the model element to start iterating.
+     */
+    _getStartNode() {
+        if (this._includeSelf) {
+            return this._startElement;
+        }
+        return this._isForward ?
+            this._startElement.nextSibling :
+            this._startElement.previousSibling;
+    }
+}
+/**
+ * Iterates sibling list blocks starting from the given node.
+ *
+ * @internal
+ * @param node The model node.
+ * @param direction Iteration direction.
+ * @returns The object with `node` and `previous` {@link module:engine/model/element~Element blocks}.
+ */
+export function* iterateSiblingListBlocks(node, direction = 'forward') {
+    const isForward = direction == 'forward';
+    const previousNodesByIndent = []; // Last seen nodes of lower indented lists.
+    let previous = null;
+    while (isListItemBlock(node)) {
+        let previousNodeInList = null; // It's like `previous` but has the same indent as current node.
+        if (previous) {
+            const nodeIndent = node.getAttribute('listIndent');
+            const previousNodeIndent = previous.getAttribute('listIndent');
+            // Let's find previous node for the same indent.
+            // We're going to need that when we get back to previous indent.
+            if (nodeIndent > previousNodeIndent) {
+                previousNodesByIndent[previousNodeIndent] = previous;
+            }
+            // Restore the one for given indent.
+            else if (nodeIndent < previousNodeIndent) {
+                previousNodeInList = previousNodesByIndent[nodeIndent];
+                previousNodesByIndent.length = nodeIndent;
+            }
+            // Same indent.
+            else {
+                previousNodeInList = previous;
+            }
+        }
+        yield { node, previous, previousNodeInList };
+        previous = node;
+        node = isForward ? node.nextSibling : node.previousSibling;
+    }
+}
+/**
+ * The iterable protocol over the list elements.
+ *
+ * @internal
+ */
+export class ListBlocksIterable {
+    /**
+     * @param listHead The head element of a list.
+     */
+    constructor(listHead) {
+        this._listHead = listHead;
+    }
+    /**
+     * List blocks iterator.
+     *
+     * Iterates over all blocks of a list.
+     */
+    [Symbol.iterator]() {
+        return iterateSiblingListBlocks(this._listHead, 'forward');
+    }
+}

package/src/list/utils/model.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module list/list/utils/model
+ */
+import type { DocumentFragment, Element, Model, Node, Writer, Item, Schema } from 'ckeditor5/src/engine.js';
+import { type ArrayOrItem } from 'ckeditor5/src/utils.js';
+import { type ListWalkerOptions } from './listwalker.js';
+import { type ListType } from '../listediting.js';
+/**
+ * The list item ID generator.
+ *
+ * @internal
+ */
+export declare class ListItemUid {
+    /**
+     * Returns the next ID.
+     *
+     * @internal
+     */
+    static next(): string;
+}
+/**
+ * An {@link module:engine/model/element~Element} that is known to be a list element.
+ *
+ * @internal
+ */
+export interface ListElement extends Element {
+    getAttribute(key: 'listItemId'): string;
+    getAttribute(key: 'listIndent'): number;
+    getAttribute(key: 'listType'): ListType;
+    getAttribute(key: string): unknown;
+}
+/**
+ * Returns true if the given model node is a list item block.
+ *
+ * @internal
+ */
+export declare function isListItemBlock(node: Item | DocumentFragment | null): node is ListElement;
+/**
+ * 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.
+ *
+ * @internal
+ * @param listItem Starting list item element.
+ * @param options.higherIndent Whether blocks with a higher indent level than the start block should be included
+ * in the result.
+ */
+export declare function getAllListItemBlocks(listItem: Node, options?: {
+    higherIndent?: boolean;
+}): Array<ListElement>;
+/**
+ * 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.
+ *
+ * @internal
+ * @param listItem Starting list item element.
+ * @param options.direction Walking direction.
+ * @param options.higherIndent Whether blocks with a higher indent level than the start block should be included in the result.
+ */
+export declare function getListItemBlocks(listItem: Node, options?: {
+    direction?: 'forward' | 'backward';
+    higherIndent?: boolean;
+}): Array<ListElement>;
+/**
+ * Returns a list items nested inside the given list item.
+ *
+ * @internal
+ */
+export declare function getNestedListBlocks(listItem: Element): Array<ListElement>;
+/**
+ * Returns array of all blocks/items of the same list as given block (same indent, same type and properties).
+ *
+ * @internal
+ * @param listItem Starting list item element.
+ * @param options Additional list walker options to modify the range of returned list items.
+ */
+export declare function getListItems(listItem: Element, options?: ListWalkerOptions): Array<ListElement>;
+/**
+ * Check if the given block is the first in the list item.
+ *
+ * @internal
+ * @param listBlock The list block element.
+ */
+export declare function isFirstBlockOfListItem(listBlock: Node): boolean;
+/**
+ * Check if the given block is the last in the list item.
+ *
+ * @internal
+ */
+export declare function isLastBlockOfListItem(listBlock: Element): boolean;
+/**
+ * Expands the given list of selected blocks to include the leading and tailing blocks of partially selected list items.
+ *
+ * @internal
+ * @param blocks The list of selected blocks.
+ * @param options.withNested Whether should include nested list items.
+ */
+export declare function expandListBlocksToCompleteItems(blocks: ArrayOrItem<Element>, options?: {
+    withNested?: boolean;
+}): Array<ListElement>;
+/**
+ * Expands the given list of selected blocks to include all the items of the lists they're in.
+ *
+ * @internal
+ * @param blocks The list of selected blocks.
+ */
+export declare function expandListBlocksToCompleteList(blocks: ArrayOrItem<Element>): Array<ListElement>;
+/**
+ * Splits the list item just before the provided list block.
+ *
+ * @internal
+ * @param listBlock The list block element.
+ * @param writer The model writer.
+ * @returns The array of updated blocks.
+ */
+export declare function splitListItemBefore(listBlock: Element, writer: Writer): Array<ListElement>;
+/**
+ * Merges the list item with the parent list item.
+ *
+ * @internal
+ * @param listBlock The list block element.
+ * @param parentBlock The list block element to merge with.
+ * @param writer The model writer.
+ * @returns The array of updated blocks.
+ */
+export declare function mergeListItemBefore(listBlock: Node, parentBlock: Element, writer: Writer): Array<ListElement>;
+/**
+ * Increases indentation of given list blocks.
+ *
+ * @internal
+ * @param blocks The block or iterable of blocks.
+ * @param writer The model writer.
+ * @param options.expand Whether should expand the list of blocks to include complete list items.
+ * @param options.indentBy The number of levels the indentation should change (could be negative).
+ */
+export declare function indentBlocks(blocks: ArrayOrItem<ListElement>, writer: Writer, { expand, indentBy }?: {
+    expand?: boolean;
+    indentBy?: number;
+}): Array<ListElement>;
+/**
+ * Decreases indentation of given list of blocks. If the indentation of some blocks matches the indentation
+ * of surrounding blocks, they get merged together.
+ *
+ * @internal
+ * @param blocks The block or iterable of blocks.
+ * @param writer The model writer.
+ */
+export declare function outdentBlocksWithMerge(blocks: ArrayOrItem<ListElement>, writer: Writer): Array<ListElement>;
+/**
+ * Removes all list attributes from the given blocks.
+ *
+ * @internal
+ * @param blocks The block or iterable of blocks.
+ * @param writer The model writer.
+ * @returns Array of altered blocks.
+ */
+export declare function removeListAttributes(blocks: ArrayOrItem<Element>, writer: Writer): Array<Element>;
+/**
+ * Checks whether the given blocks are related to a single list item.
+ *
+ * @internal
+ * @param blocks The list block elements.
+ */
+export declare function isSingleListItem(blocks: Array<Node>): boolean;
+/**
+ * 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.
+ *
+ * @internal
+ * @param lastBlock The last list block that has become a non-list element.
+ * @param writer The model writer.
+ * @returns Array of altered blocks.
+ */
+export declare function outdentFollowingItems(lastBlock: Element, writer: Writer): Array<ListElement>;
+/**
+ * Returns the array of given blocks sorted by model indexes (document order).
+ *
+ * @internal
+ */
+export declare function sortBlocks<T extends Element>(blocks: Iterable<T>): Array<T>;
+/**
+ * Returns a selected block object. If a selected object is inline or when there is no selected
+ * object, `null` is returned.
+ *
+ * @internal
+ * @param model The instance of editor model.
+ * @returns Selected block object or `null`.
+ */
+export declare function getSelectedBlockObject(model: Model): Element | null;
+/**
+ * Checks whether the given block can be replaced by a listItem.
+ *
+ * Note that this is possible only when multiBlock = false option is set in feature config.
+ *
+ * @param block A block to be tested.
+ * @param schema The schema of the document.
+ */
+export declare function canBecomeSimpleListItem(block: Element, schema: Schema): boolean;
+/**
+ * Returns true if listType is of type `numbered` or `customNumbered`.
+ */
+export declare function isNumberedListType(listType: ListType): boolean;