@ckeditor/ckeditor5-list 36.0.0 → 37.0.0-alpha.0

package/src/documentlist/documentlistutils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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 list/documentlist/documentlistutils
+ */
+import type { Element, Node } from 'ckeditor5/src/engine';
+import type { ArrayOrItem } from 'ckeditor5/src/utils';
+import { Plugin } from 'ckeditor5/src/core';
+/**
+ * A set of helpers related to document lists.
+ */
+export default class DocumentListUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'DocumentListUtils';
+    /**
+     * 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): boolean;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [DocumentListUtils.pluginName]: DocumentListUtils;
+    }
+}

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

@@ -0,0 +1,141 @@
+/**
+ * @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 list/documentlist/utils/listwalker
+ */
+import { type ArrayOrItem } from 'ckeditor5/src/utils';
+import { type ListElement } from './model';
+import type { Element, Node } from 'ckeditor5/src/engine';
+/**
+ * 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: {
+        direction?: 'forward' | 'backward';
+        includeSelf?: boolean;
+        sameAttributes?: ArrayOrItem<string>;
+        sameIndent?: boolean;
+        lowerIndent?: boolean;
+        higherIndent?: boolean;
+    });
+    /**
+     * 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: {
+        direction?: 'forward' | 'backward';
+        includeSelf?: boolean;
+        sameAttributes?: ArrayOrItem<string>;
+        sameIndent?: boolean;
+        lowerIndent?: boolean;
+        higherIndent?: boolean;
+    }): 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;
+}

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

@@ -0,0 +1,193 @@
+/**
+ * @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 list/documentlist/utils/model
+ */
+import type { DocumentFragment, Element, Model, Node, Writer, Item } from 'ckeditor5/src/engine';
+import { type ArrayOrItem } from 'ckeditor5/src/utils';
+/**
+ * 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'): 'numbered' | 'bulleted';
+    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.
+ */
+export declare function getListItems(listItem: Element): 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;

package/src/documentlist/utils/postfixers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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 list/documentlist/utils/postfixers
+ */
+import type { Position, Writer } from 'ckeditor5/src/engine';
+import { type ListIteratorValue } from './listwalker';
+import { type ListElement } from './model';
+/**
+ * Based on the provided positions looks for the list head and stores it in the provided map.
+ *
+ * @internal
+ * @param position The search starting position.
+ * @param itemToListHead The map from list item element to the list head element.
+ */
+export declare function findAndAddListHeadToMap(position: Position, itemToListHead: Map<ListElement, ListElement>): void;
+/**
+ * Scans the list starting from the given list head element and fixes items' indentation.
+ *
+ * @internal
+ * @param listNodes The iterable of list nodes.
+ * @param writer The model writer.
+ * @returns Whether the model was modified.
+ */
+export declare function fixListIndents(listNodes: Iterable<ListIteratorValue>, writer: Writer): boolean;
+/**
+ * Scans the list starting from the given list head element and fixes items' types.
+ *
+ * @internal
+ * @param listNodes The iterable of list nodes.
+ * @param seenIds The set of already known IDs.
+ * @param writer The model writer.
+ * @returns Whether the model was modified.
+ */
+export declare function fixListItemIds(listNodes: Iterable<ListIteratorValue>, seenIds: Set<string>, writer: Writer): boolean;

package/src/documentlist/utils/view.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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 list/documentlist/utils/view
+ */
+import type { DowncastWriter, ViewAttributeElement, ViewDocumentFragment, ViewElement, ViewNode } from 'ckeditor5/src/engine';
+/**
+ * Checks if view element is a list type (ul or ol).
+ *
+ * @internal
+ */
+export declare function isListView(viewElement: ViewNode | ViewDocumentFragment): viewElement is ViewElement & {
+    name: 'ul' | 'ol';
+};
+/**
+ * Checks if view element is a list item (li).
+ *
+ * @internal
+ */
+export declare function isListItemView(viewElement: ViewNode | ViewDocumentFragment): viewElement is ViewElement & {
+    name: 'li';
+};
+/**
+ * Calculates the indent value for a list item. Handles HTML compliant and non-compliant lists.
+ *
+ * Also, fixes non HTML compliant lists indents:
+ *
+ * ```
+ * before:                                     fixed list:
+ * OL                                          OL
+ * |-> LI (parent LIs: 0)                      |-> LI     (indent: 0)
+ *     |-> OL                                  |-> OL
+ *         |-> OL                                  |
+ *         |   |-> OL                              |
+ *         |       |-> OL                          |
+ *         |           |-> LI (parent LIs: 1)      |-> LI (indent: 1)
+ *         |-> LI (parent LIs: 1)                  |-> LI (indent: 1)
+ *
+ * before:                                     fixed list:
+ * OL                                          OL
+ * |-> OL                                      |
+ *     |-> OL                                  |
+ *          |-> OL                             |
+ *              |-> LI (parent LIs: 0)         |-> LI        (indent: 0)
+ *
+ * before:                                     fixed list:
+ * OL                                          OL
+ * |-> LI (parent LIs: 0)                      |-> LI         (indent: 0)
+ * |-> OL                                          |-> OL
+ *     |-> LI (parent LIs: 0)                          |-> LI (indent: 1)
+ * ```
+ *
+ * @internal
+ */
+export declare function getIndent(listItem: ViewElement): number;
+/**
+ * Creates a list attribute element (ol or ul).
+ *
+ * @internal
+ */
+export declare function createListElement(writer: DowncastWriter, indent: number, type: 'bulleted' | 'numbered', id?: string): ViewAttributeElement;
+/**
+ * Creates a list item attribute element (li).
+ *
+ * @internal
+ */
+export declare function createListItemElement(writer: DowncastWriter, indent: number, id: string): ViewAttributeElement;
+/**
+ * Returns a view element name for the given list type.
+ *
+ * @internal
+ */
+export declare function getViewElementNameForListType(type?: 'bulleted' | 'numbered'): 'ol' | 'ul';
+/**
+ * Returns a view element ID for the given list type and indent.
+ *
+ * @internal
+ */
+export declare function getViewElementIdForListType(type?: 'bulleted' | 'numbered', indent?: number): string;

package/src/documentlist.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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 list/documentlist
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import './listconfig';
+/**
+ * The document list feature.
+ *
+ * This is a "glue" plugin that loads the {@link module:list/documentlist/documentlistediting~DocumentListEditing document list
+ * editing feature} and {@link module:list/list/listui~ListUI list UI feature}.
+ */
+export default class DocumentList extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'DocumentList';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [DocumentList.pluginName]: DocumentList;
+    }
+}

package/src/documentlist.js

@@ -8,6 +8,7 @@
 import { Plugin } from 'ckeditor5/src/core';
 import DocumentListEditing from './documentlist/documentlistediting';
 import ListUI from './list/listui';
+import './listconfig';
 /**
  * The document list feature.
  *

package/src/documentlistproperties/converters.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @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 list/documentlistproperties/converters
+ */
+import type { UpcastElementEvent } from 'ckeditor5/src/engine';
+import type { GetCallback } from 'ckeditor5/src/utils';
+import type { AttributeStrategy } from './documentlistpropertiesediting';
+/**
+ * Returns a converter that consumes the `style`, `reversed`, and `start` attributes.
+ * In `style`, it searches for the `list-style-type` definition.
+ * If not found, the `"default"` value will be used.
+ *
+ * @internal
+ * @param strategy
+ */
+export declare function listPropertiesUpcastConverter(strategy: AttributeStrategy): GetCallback<UpcastElementEvent>;

package/src/documentlistproperties/documentlistpropertiesediting.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @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 list/documentlistproperties/documentlistpropertiesediting
+ */
+import { Plugin, type Editor, type PluginDependencies } from 'ckeditor5/src/core';
+import type { Consumables, DowncastWriter, Element, Item, ViewElement } from 'ckeditor5/src/engine';
+import { type ListItemAttributesMap } from '../documentlist/documentlistediting';
+/**
+ * The document list properties engine feature.
+ *
+ * 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 DocumentListPropertiesEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'DocumentListPropertiesEditing';
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}
+/**
+ * Strategy for dealing with `listItem` attributes supported by this plugin.
+ *
+ * @internal
+ */
+export interface AttributeStrategy {
+    /**
+     * The model attribute name.
+     */
+    attributeName: keyof ListItemAttributesMap;
+    /**
+     * The model attribute default value.
+     */
+    defaultValue: unknown;
+    /**
+     * The view consumable as expected by {@link module:engine/conversion/viewconsumable~ViewConsumable#consume `ViewConsumable`}.
+     */
+    viewConsumables: Consumables;
+    /**
+     * Registers an editor command.
+     */
+    addCommand(editor: Editor): void;
+    /**
+     * Verifies whether the strategy is applicable for the specified model element.
+     */
+    appliesToListItem(element: Item): boolean;
+    /**
+     * Verifies whether the model attribute value is valid.
+     */
+    hasValidAttribute(element: Element): boolean;
+    /**
+     * Sets the property on the view element.
+     */
+    setAttributeOnDowncast(writer: DowncastWriter, value: unknown, element: ViewElement): void;
+    /**
+     * Retrieves the property value from the view element.
+     */
+    getAttributeOnUpcast(element: ViewElement): unknown;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [DocumentListPropertiesEditing.pluginName]: DocumentListPropertiesEditing;
+    }
+}
+declare module '../documentlist/documentlistediting' {
+    interface ListItemAttributesMap {
+        listStyle?: string;
+        listStart?: number;
+        listReversed?: boolean;
+    }
+}
+declare module '../documentlist/utils/model' {
+    interface ListElement extends Element {
+        getAttribute(key: 'listStyle'): string;
+        getAttribute(key: 'listStart'): number;
+        getAttribute(key: 'listReversed'): boolean;
+    }
+}

package/src/documentlistproperties/documentlistpropertiesutils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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 list/documentlist/documentlistpropertiesutils
+ */
+import { Plugin } from 'ckeditor5/src/core';
+/**
+ * A set of helpers related to document lists.
+ */
+export default class DocumentListPropertiesUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'DocumentListPropertiesUtils';
+    /**
+     * Gets all the style types supported by given list type.
+     */
+    getAllSupportedStyleTypes(): Array<string>;
+    /**
+     * Checks whether the given list-style-type is supported by numbered or bulleted list.
+     */
+    getListTypeFromListStyleType(listStyleType: string): 'bulleted' | 'numbered' | null;
+    /**
+     * Converts `type` attribute of `<ul>` or `<ol>` elements to `list-style-type` equivalent.
+     */
+    getListStyleTypeFromTypeAttribute(value: string): string | null;
+    /**
+     * Converts `list-style-type` style to `type` attribute of `<ul>` or `<ol>` elements.
+     */
+    getTypeAttributeFromListStyleType(value: string): string | null;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [DocumentListPropertiesUtils.pluginName]: DocumentListPropertiesUtils;
+    }
+}