@ckeditor/ckeditor5-list 40.2.0 → 41.0.0

package/src/legacylist/legacyutils.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @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/legacylist/legacyutils
+ */
+import { type DowncastConversionApi, type DowncastWriter, type Element, type Item, type Model, type Position, type ViewContainerElement, type ViewElement, type ViewItem, type ViewPosition } from 'ckeditor5/src/engine.js';
+/**
+ * Creates a list item {@link module:engine/view/containerelement~ContainerElement}.
+ *
+ * @param writer The writer instance.
+ */
+export declare function createViewListItemElement(writer: DowncastWriter): ViewContainerElement;
+/**
+ * Helper function that creates a `<ul><li></li></ul>` or (`<ol>`) structure out of the given `modelItem` model `listItem` element.
+ * Then, it binds the created view list item (`<li>`) with the model `listItem` element.
+ * The function then returns the created view list item (`<li>`).
+ *
+ * @param modelItem Model list item.
+ * @param conversionApi Conversion interface.
+ * @returns View list element.
+ */
+export declare function generateLiInUl(modelItem: Item, conversionApi: DowncastConversionApi): ViewContainerElement;
+/**
+ * Helper function that inserts a view list at a correct place and merges it with its siblings.
+ * It takes a model list item element (`modelItem`) and a corresponding view list item element (`injectedItem`). The view list item
+ * should be in a view list element (`<ul>` or `<ol>`) and should be its only child.
+ * See comments below to better understand the algorithm.
+ *
+ * @param modelItem Model list item.
+ * @param injectedItem
+ * @param conversionApi Conversion interface.
+ * @param model The model instance.
+ */
+export declare function injectViewList(modelItem: Element, injectedItem: ViewContainerElement, conversionApi: DowncastConversionApi, model: Model): void;
+/**
+ * Helper function that takes two parameters that are expected to be view list elements, and merges them.
+ * The merge happens only if both parameters are list elements of the same type (the same element name and the same class attributes).
+ *
+ * @param viewWriter The writer instance.
+ * @param firstList The first element to compare.
+ * @param secondList The second element to compare.
+ * @returns The position after merge or `null` when there was no merge.
+ */
+export declare function mergeViewLists(viewWriter: DowncastWriter, firstList: ViewItem, secondList: ViewItem): ViewPosition | null;
+/**
+ * Helper function that for a given `view.Position`, returns a `view.Position` that is after all `view.UIElement`s that
+ * are after the given position.
+ *
+ * For example:
+ * `<container:p>foo^<ui:span></ui:span><ui:span></ui:span>bar</container:p>`
+ * For position ^, the position before "bar" will be returned.
+ *
+ */
+export declare function positionAfterUiElements(viewPosition: ViewPosition): ViewPosition;
+/**
+ * Helper function that searches for a previous list item sibling of a given model item that meets the given criteria
+ * passed by the options object.
+ *
+ * @param options Search criteria.
+ * @param options.sameIndent Whether the sought sibling should have the same indentation.
+ * @param options.smallerIndent Whether the sought sibling should have a smaller indentation.
+ * @param options.listIndent The reference indentation.
+ * @param options.direction Walking direction.
+ */
+export declare function getSiblingListItem(modelItem: Item | null, options: {
+    sameIndent?: boolean;
+    smallerIndent?: boolean;
+    listIndent?: number;
+    direction?: 'forward' | 'backward';
+}): Element | null;
+/**
+ * Returns a first list view element that is direct child of the given view element.
+ */
+export declare function findNestedList(viewElement: ViewElement): ViewElement | null;
+/**
+ * Returns an array with all `listItem` elements that represent the same list.
+ *
+ * It means that values of `listIndent`, `listType`, `listStyle`, `listReversed` and `listStart` for all items are equal.
+ *
+ * Additionally, if the `position` is inside a list item, that list item will be returned as well.
+ *
+ * @param position Starting position.
+ * @param direction Walking direction.
+ */
+export declare function getSiblingNodes(position: Position, direction: 'forward' | 'backward'): Array<Element>;
+/**
+ * Returns an array with all `listItem` elements in the model selection.
+ *
+ * It returns all the items even if only a part of the list is selected, including items that belong to nested lists.
+ * If no list is selected, it returns an empty array.
+ * The order of the elements is not specified.
+ *
+ * @internal
+ */
+export declare function getSelectedListItems(model: Model): Array<Element>;
+/**
+ * Checks whether the given list-style-type is supported by numbered or bulleted list.
+ */
+export declare function getListTypeFromListStyleType(listStyleType: string): 'bulleted' | 'numbered' | null;

package/src/legacylist/legacyutils.js

@@ -0,0 +1,347 @@
+/**
+ * @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/legacylist/legacyutils
+ */
+import { TreeWalker, getFillerOffset } from 'ckeditor5/src/engine.js';
+/**
+ * Creates a list item {@link module:engine/view/containerelement~ContainerElement}.
+ *
+ * @param writer The writer instance.
+ */
+export function createViewListItemElement(writer) {
+    const viewItem = writer.createContainerElement('li');
+    viewItem.getFillerOffset = getListItemFillerOffset;
+    return viewItem;
+}
+/**
+ * Helper function that creates a `<ul><li></li></ul>` or (`<ol>`) structure out of the given `modelItem` model `listItem` element.
+ * Then, it binds the created view list item (`<li>`) with the model `listItem` element.
+ * The function then returns the created view list item (`<li>`).
+ *
+ * @param modelItem Model list item.
+ * @param conversionApi Conversion interface.
+ * @returns View list element.
+ */
+export function generateLiInUl(modelItem, conversionApi) {
+    const mapper = conversionApi.mapper;
+    const viewWriter = conversionApi.writer;
+    const listType = modelItem.getAttribute('listType') == 'numbered' ? 'ol' : 'ul';
+    const viewItem = createViewListItemElement(viewWriter);
+    const viewList = viewWriter.createContainerElement(listType, null);
+    viewWriter.insert(viewWriter.createPositionAt(viewList, 0), viewItem);
+    mapper.bindElements(modelItem, viewItem);
+    return viewItem;
+}
+/**
+ * Helper function that inserts a view list at a correct place and merges it with its siblings.
+ * It takes a model list item element (`modelItem`) and a corresponding view list item element (`injectedItem`). The view list item
+ * should be in a view list element (`<ul>` or `<ol>`) and should be its only child.
+ * See comments below to better understand the algorithm.
+ *
+ * @param modelItem Model list item.
+ * @param injectedItem
+ * @param conversionApi Conversion interface.
+ * @param model The model instance.
+ */
+export function injectViewList(modelItem, injectedItem, conversionApi, model) {
+    const injectedList = injectedItem.parent;
+    const mapper = conversionApi.mapper;
+    const viewWriter = conversionApi.writer;
+    // The position where the view list will be inserted.
+    let insertPosition = mapper.toViewPosition(model.createPositionBefore(modelItem));
+    // 1. Find the previous list item that has the same or smaller indent. Basically we are looking for the first model item
+    // that is a "parent" or "sibling" of the injected model item.
+    // If there is no such list item, it means that the injected list item is the first item in "its list".
+    const refItem = getSiblingListItem(modelItem.previousSibling, {
+        sameIndent: true,
+        smallerIndent: true,
+        listIndent: modelItem.getAttribute('listIndent')
+    });
+    const prevItem = modelItem.previousSibling;
+    if (refItem && refItem.getAttribute('listIndent') == modelItem.getAttribute('listIndent')) {
+        // There is a list item with the same indent - we found the same-level sibling.
+        // Break the list after it. The inserted view item will be added in the broken space.
+        const viewItem = mapper.toViewElement(refItem);
+        insertPosition = viewWriter.breakContainer(viewWriter.createPositionAfter(viewItem));
+    }
+    else {
+        // There is no list item with the same indent. Check the previous model item.
+        if (prevItem && prevItem.name == 'listItem') {
+            // If it is a list item, it has to have a lower indent.
+            // It means that the inserted item should be added to it as its nested item.
+            insertPosition = mapper.toViewPosition(model.createPositionAt(prevItem, 'end'));
+            // There could be some not mapped elements (eg. span in to-do list) but we need to insert
+            // a nested list directly inside the li element.
+            const mappedViewAncestor = mapper.findMappedViewAncestor(insertPosition);
+            const nestedList = findNestedList(mappedViewAncestor);
+            // If there already is some nested list, then use it's position.
+            if (nestedList) {
+                insertPosition = viewWriter.createPositionBefore(nestedList);
+            }
+            else {
+                // Else just put new list on the end of list item content.
+                insertPosition = viewWriter.createPositionAt(mappedViewAncestor, 'end');
+            }
+        }
+        else {
+            // The previous item is not a list item (or does not exist at all).
+            // Just map the position and insert the view item at the mapped position.
+            insertPosition = mapper.toViewPosition(model.createPositionBefore(modelItem));
+        }
+    }
+    insertPosition = positionAfterUiElements(insertPosition);
+    // Insert the view item.
+    viewWriter.insert(insertPosition, injectedList);
+    // 2. Handle possible children of the injected model item.
+    if (prevItem && prevItem.name == 'listItem') {
+        const prevView = mapper.toViewElement(prevItem);
+        const walkerBoundaries = viewWriter.createRange(viewWriter.createPositionAt(prevView, 0), insertPosition);
+        const walker = walkerBoundaries.getWalker({ ignoreElementEnd: true });
+        for (const value of walker) {
+            if (value.item.is('element', 'li')) {
+                const breakPosition = viewWriter.breakContainer(viewWriter.createPositionBefore(value.item));
+                const viewList = value.item.parent;
+                const targetPosition = viewWriter.createPositionAt(injectedItem, 'end');
+                mergeViewLists(viewWriter, targetPosition.nodeBefore, targetPosition.nodeAfter);
+                viewWriter.move(viewWriter.createRangeOn(viewList), targetPosition);
+                // This is bad, but those lists will be removed soon anyway.
+                walker._position = breakPosition;
+            }
+        }
+    }
+    else {
+        const nextViewList = injectedList.nextSibling;
+        if (nextViewList && (nextViewList.is('element', 'ul') || nextViewList.is('element', 'ol'))) {
+            let lastSubChild = null;
+            for (const child of nextViewList.getChildren()) {
+                const modelChild = mapper.toModelElement(child);
+                if (modelChild &&
+                    modelChild.getAttribute('listIndent') > modelItem.getAttribute('listIndent')) {
+                    lastSubChild = child;
+                }
+                else {
+                    break;
+                }
+            }
+            if (lastSubChild) {
+                viewWriter.breakContainer(viewWriter.createPositionAfter(lastSubChild));
+                viewWriter.move(viewWriter.createRangeOn(lastSubChild.parent), viewWriter.createPositionAt(injectedItem, 'end'));
+            }
+        }
+    }
+    // Merge the inserted view list with its possible neighbor lists.
+    mergeViewLists(viewWriter, injectedList, injectedList.nextSibling);
+    mergeViewLists(viewWriter, injectedList.previousSibling, injectedList);
+}
+export function mergeViewLists(viewWriter, firstList, secondList) {
+    // Check if two lists are going to be merged.
+    if (!firstList || !secondList || (firstList.name != 'ul' && firstList.name != 'ol')) {
+        return null;
+    }
+    // Both parameters are list elements, so compare types now.
+    if (firstList.name != secondList.name || firstList.getAttribute('class') !== secondList.getAttribute('class')) {
+        return null;
+    }
+    return viewWriter.mergeContainers(viewWriter.createPositionAfter(firstList));
+}
+/**
+ * Helper function that for a given `view.Position`, returns a `view.Position` that is after all `view.UIElement`s that
+ * are after the given position.
+ *
+ * For example:
+ * `<container:p>foo^<ui:span></ui:span><ui:span></ui:span>bar</container:p>`
+ * For position ^, the position before "bar" will be returned.
+ *
+ */
+export function positionAfterUiElements(viewPosition) {
+    return viewPosition.getLastMatchingPosition(value => value.item.is('uiElement'));
+}
+/**
+ * Helper function that searches for a previous list item sibling of a given model item that meets the given criteria
+ * passed by the options object.
+ *
+ * @param options Search criteria.
+ * @param options.sameIndent Whether the sought sibling should have the same indentation.
+ * @param options.smallerIndent Whether the sought sibling should have a smaller indentation.
+ * @param options.listIndent The reference indentation.
+ * @param options.direction Walking direction.
+ */
+export function getSiblingListItem(modelItem, options) {
+    const sameIndent = !!options.sameIndent;
+    const smallerIndent = !!options.smallerIndent;
+    const indent = options.listIndent;
+    let item = modelItem;
+    while (item && item.name == 'listItem') {
+        const itemIndent = item.getAttribute('listIndent');
+        if ((sameIndent && indent == itemIndent) || (smallerIndent && indent > itemIndent)) {
+            return item;
+        }
+        if (options.direction === 'forward') {
+            item = item.nextSibling;
+        }
+        else {
+            item = item.previousSibling;
+        }
+    }
+    return null;
+}
+/**
+ * Returns a first list view element that is direct child of the given view element.
+ */
+export function findNestedList(viewElement) {
+    for (const node of viewElement.getChildren()) {
+        if (node.name == 'ul' || node.name == 'ol') {
+            return node;
+        }
+    }
+    return null;
+}
+/**
+ * Returns an array with all `listItem` elements that represent the same list.
+ *
+ * It means that values of `listIndent`, `listType`, `listStyle`, `listReversed` and `listStart` for all items are equal.
+ *
+ * Additionally, if the `position` is inside a list item, that list item will be returned as well.
+ *
+ * @param position Starting position.
+ * @param direction Walking direction.
+ */
+export function getSiblingNodes(position, direction) {
+    const items = [];
+    const listItem = position.parent;
+    const walkerOptions = {
+        ignoreElementEnd: false,
+        startPosition: position,
+        shallow: true,
+        direction
+    };
+    const limitIndent = listItem.getAttribute('listIndent');
+    const nodes = [...new TreeWalker(walkerOptions)]
+        .filter(value => value.item.is('element'))
+        .map(value => value.item);
+    for (const element of nodes) {
+        // If found something else than `listItem`, we're out of the list scope.
+        if (!element.is('element', 'listItem')) {
+            break;
+        }
+        // If current parsed item has lower indent that element that the element that was a starting point,
+        // it means we left a nested list. Abort searching items.
+        //
+        // ■ List item 1.       [listIndent=0]
+        //     ○ List item 2.[] [listIndent=1], limitIndent = 1,
+        //     ○ List item 3.   [listIndent=1]
+        // ■ List item 4.       [listIndent=0]
+        //
+        // Abort searching when leave nested list.
+        if (element.getAttribute('listIndent') < limitIndent) {
+            break;
+        }
+        // ■ List item 1.[]     [listIndent=0] limitIndent = 0,
+        //     ○ List item 2.   [listIndent=1]
+        //     ○ List item 3.   [listIndent=1]
+        // ■ List item 4.       [listIndent=0]
+        //
+        // Ignore nested lists.
+        if (element.getAttribute('listIndent') > limitIndent) {
+            continue;
+        }
+        // ■ List item 1.[]  [listType=bulleted]
+        // 1. List item 2.   [listType=numbered]
+        // 2.List item 3.    [listType=numbered]
+        //
+        // Abort searching when found a different kind of a list.
+        if (element.getAttribute('listType') !== listItem.getAttribute('listType')) {
+            break;
+        }
+        // ■ List item 1.[]  [listType=bulleted]
+        // ■ List item 2.    [listType=bulleted]
+        // ○ List item 3.    [listType=bulleted]
+        // ○ List item 4.    [listType=bulleted]
+        //
+        // Abort searching when found a different list style,
+        if (element.getAttribute('listStyle') !== listItem.getAttribute('listStyle')) {
+            break;
+        }
+        // ... different direction
+        if (element.getAttribute('listReversed') !== listItem.getAttribute('listReversed')) {
+            break;
+        }
+        // ... and different start index
+        if (element.getAttribute('listStart') !== listItem.getAttribute('listStart')) {
+            break;
+        }
+        if (direction === 'backward') {
+            items.unshift(element);
+        }
+        else {
+            items.push(element);
+        }
+    }
+    return items;
+}
+/**
+ * Returns an array with all `listItem` elements in the model selection.
+ *
+ * It returns all the items even if only a part of the list is selected, including items that belong to nested lists.
+ * If no list is selected, it returns an empty array.
+ * The order of the elements is not specified.
+ *
+ * @internal
+ */
+export function getSelectedListItems(model) {
+    const document = model.document;
+    // For all selected blocks find all list items that are being selected
+    // and update the `listStyle` attribute in those lists.
+    let listItems = [...document.selection.getSelectedBlocks()]
+        .filter(element => element.is('element', 'listItem'))
+        .map(element => {
+        const position = model.change(writer => writer.createPositionAt(element, 0));
+        return [
+            ...getSiblingNodes(position, 'backward'),
+            ...getSiblingNodes(position, 'forward')
+        ];
+    })
+        .flat();
+    // Since `getSelectedBlocks()` can return items that belong to the same list, and
+    // `getSiblingNodes()` returns the entire list, we need to remove duplicated items.
+    listItems = [...new Set(listItems)];
+    return listItems;
+}
+const BULLETED_LIST_STYLE_TYPES = ['disc', 'circle', 'square'];
+// There's a lot of them (https://www.w3.org/TR/css-counter-styles-3/#typedef-counter-style).
+// Let's support only those that can be selected by ListPropertiesUI.
+const NUMBERED_LIST_STYLE_TYPES = [
+    'decimal',
+    'decimal-leading-zero',
+    'lower-roman',
+    'upper-roman',
+    'lower-latin',
+    'upper-latin'
+];
+/**
+ * Checks whether the given list-style-type is supported by numbered or bulleted list.
+ */
+export function getListTypeFromListStyleType(listStyleType) {
+    if (BULLETED_LIST_STYLE_TYPES.includes(listStyleType)) {
+        return 'bulleted';
+    }
+    if (NUMBERED_LIST_STYLE_TYPES.includes(listStyleType)) {
+        return 'numbered';
+    }
+    return null;
+}
+/**
+ * Implementation of getFillerOffset for view list item element.
+ *
+ * @returns Block filler offset or `null` if block filler is not needed.
+ */
+function getListItemFillerOffset() {
+    const hasOnlyLists = !this.isEmpty && (this.getChild(0).name == 'ul' || this.getChild(0).name == 'ol');
+    if (this.isEmpty || hasOnlyLists) {
+        return 0;
+    }
+    return getFillerOffset.call(this);
+}

package/src/legacylist.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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/legacylist
+ */
+import LegacyListEditing from './legacylist/legacylistediting.js';
+import ListUI from './list/listui.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The legacy list feature.
+ *
+ * This is a "glue" plugin that loads the {@link module:list/legacylist/legacylistediting~LegacyListEditing legacy list editing feature}
+ * and {@link module:list/list/listui~ListUI list UI feature}.
+ */
+export default class LegacyList extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof LegacyListEditing, typeof ListUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LegacyList";
+}

package/src/legacylist.js

@@ -0,0 +1,30 @@
+/**
+ * @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/legacylist
+ */
+import LegacyListEditing from './legacylist/legacylistediting.js';
+import ListUI from './list/listui.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * The legacy list feature.
+ *
+ * This is a "glue" plugin that loads the {@link module:list/legacylist/legacylistediting~LegacyListEditing legacy list editing feature}
+ * and {@link module:list/list/listui~ListUI list UI feature}.
+ */
+export default class LegacyList extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [LegacyListEditing, ListUI];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'LegacyList';
+    }
+}

package/src/legacylistproperties/legacylistpropertiesediting.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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/legacylistproperties/legacylistpropertiesediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import LegacyListEditing from '../legacylist/legacylistediting.js';
+/**
+ * The engine of the list properties feature.
+ *
+ * It sets the value for the `listItem` attribute of the {@link module:list/legacylist~LegacyList `<listItem>`} element that
+ * allows modifying the list style type.
+ *
+ * It registers the `'listStyle'`, `'listReversed'` and `'listStart'` commands if they are enabled in the configuration.
+ * Read more in {@link module:list/listconfig~ListPropertiesConfig}.
+ */
+export default class LegacyListPropertiesEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof LegacyListEditing];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LegacyListPropertiesEditing";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * Starts listening to {@link module:engine/model/model~Model#deleteContent} and checks whether two lists will be merged into a single
+     * one after deleting the content.
+     *
+     * The purpose of this action is to adjust the `listStyle`, `listReversed` and `listStart` values
+     * for the list that was merged.
+     *
+     * Consider the following model's content:
+     *
+     * ```xml
+     * <listItem listIndent="0" listType="bulleted" listStyle="square">UL List item 1</listItem>
+     * <listItem listIndent="0" listType="bulleted" listStyle="square">UL List item 2</listItem>
+     * <paragraph>[A paragraph.]</paragraph>
+     * <listItem listIndent="0" listType="bulleted" listStyle="circle">UL List item 1</listItem>
+     * <listItem listIndent="0" listType="bulleted" listStyle="circle">UL List item 2</listItem>
+     * ```
+     *
+     * After removing the paragraph element, the second list will be merged into the first one.
+     * We want to inherit the `listStyle` attribute for the second list from the first one.
+     *
+     * ```xml
+     * <listItem listIndent="0" listType="bulleted" listStyle="square">UL List item 1</listItem>
+     * <listItem listIndent="0" listType="bulleted" listStyle="square">UL List item 2</listItem>
+     * <listItem listIndent="0" listType="bulleted" listStyle="square">UL List item 1</listItem>
+     * <listItem listIndent="0" listType="bulleted" listStyle="square">UL List item 2</listItem>
+     * ```
+     *
+     * See https://github.com/ckeditor/ckeditor5/issues/7879.
+     *
+     * @param attributeStrategies Strategies for the enabled attributes.
+     */
+    private _mergeListAttributesWhileMergingLists;
+}