@ckeditor/ckeditor5-list 0.0.0-internal-20241017.0

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

@@ -0,0 +1,82 @@
+/**
+ * @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/view
+ */
+import type { DowncastWriter, ViewAttributeElement, ViewDocumentFragment, ViewElement, ViewNode } from 'ckeditor5/src/engine.js';
+import { type ListType } from '../listediting.js';
+/**
+ * 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: ListType, 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?: ListType): 'ol' | 'ul';
+/**
+ * Returns a view element ID for the given list type and indent.
+ *
+ * @internal
+ */
+export declare function getViewElementIdForListType(type?: ListType, indent?: number): string;

package/src/list/utils/view.js

@@ -0,0 +1,117 @@
+/**
+ * @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
+ */
+/**
+ * Checks if view element is a list type (ul or ol).
+ *
+ * @internal
+ */
+export function isListView(viewElement) {
+    return viewElement.is('element', 'ol') || viewElement.is('element', 'ul');
+}
+/**
+ * Checks if view element is a list item (li).
+ *
+ * @internal
+ */
+export function isListItemView(viewElement) {
+    return viewElement.is('element', '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 function getIndent(listItem) {
+    let indent = 0;
+    let parent = listItem.parent;
+    while (parent) {
+        // Each LI in the tree will result in an increased indent for HTML compliant lists.
+        if (isListItemView(parent)) {
+            indent++;
+        }
+        else {
+            // If however the list is nested in other list we should check previous sibling of any of the list elements...
+            const previousSibling = parent.previousSibling;
+            // ...because the we might need increase its indent:
+            //		before:                           fixed list:
+            //		OL                                OL
+            //		|-> LI (parent LIs: 0)            |-> LI         (indent: 0)
+            //		|-> OL                                |-> OL
+            //		    |-> LI (parent LIs: 0)                |-> LI (indent: 1)
+            if (previousSibling && isListItemView(previousSibling)) {
+                indent++;
+            }
+        }
+        parent = parent.parent;
+    }
+    return indent;
+}
+/**
+ * Creates a list attribute element (ol or ul).
+ *
+ * @internal
+ */
+export function createListElement(writer, indent, type, id = getViewElementIdForListType(type, indent)) {
+    // Negative priorities so that restricted editing attribute won't wrap lists.
+    return writer.createAttributeElement(getViewElementNameForListType(type), null, {
+        priority: 2 * indent / 100 - 100,
+        id
+    });
+}
+/**
+ * Creates a list item attribute element (li).
+ *
+ * @internal
+ */
+export function createListItemElement(writer, indent, id) {
+    // Negative priorities so that restricted editing attribute won't wrap list items.
+    return writer.createAttributeElement('li', null, {
+        priority: (2 * indent + 1) / 100 - 100,
+        id
+    });
+}
+/**
+ * Returns a view element name for the given list type.
+ *
+ * @internal
+ */
+export function getViewElementNameForListType(type) {
+    return type == 'numbered' || type == 'customNumbered' ? 'ol' : 'ul';
+}
+/**
+ * Returns a view element ID for the given list type and indent.
+ *
+ * @internal
+ */
+export function getViewElementIdForListType(type, indent) {
+    return `list-${type}-${indent}`;
+}

package/src/list/utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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
+ */
+import type { Editor } from 'ckeditor5/src/core.js';
+/**
+ * Helper method for creating toolbar and menu buttons and linking them with an appropriate command.
+ *
+ * @internal
+ * @param editor The editor instance to which the UI component will be added.
+ * @param commandName The name of the command.
+ * @param label The button label.
+ * @param icon The source of the icon.
+ */
+export declare function createUIComponents(editor: Editor, commandName: 'bulletedList' | 'numberedList' | 'todoList', label: string, icon: string): void;

package/src/list/utils.js

@@ -0,0 +1,51 @@
+/**
+ * @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 { ButtonView, MenuBarMenuListItemButtonView } from 'ckeditor5/src/ui.js';
+/**
+ * Helper method for creating toolbar and menu buttons and linking them with an appropriate command.
+ *
+ * @internal
+ * @param editor The editor instance to which the UI component will be added.
+ * @param commandName The name of the command.
+ * @param label The button label.
+ * @param icon The source of the icon.
+ */
+export function createUIComponents(editor, commandName, label, icon) {
+    editor.ui.componentFactory.add(commandName, () => {
+        const buttonView = _createButton(ButtonView, editor, commandName, label, icon);
+        buttonView.set({
+            tooltip: true,
+            isToggleable: true
+        });
+        return buttonView;
+    });
+    editor.ui.componentFactory.add(`menuBar:${commandName}`, () => {
+        const buttonView = _createButton(MenuBarMenuListItemButtonView, editor, commandName, label, icon);
+        buttonView.set({
+            role: 'menuitemcheckbox',
+            isToggleable: true
+        });
+        return buttonView;
+    });
+}
+/**
+ * Creates a button to use either in toolbar or in menu bar.
+ */
+function _createButton(ButtonClass, editor, commandName, label, icon) {
+    const command = editor.commands.get(commandName);
+    const view = new ButtonClass(editor.locale);
+    view.set({
+        label,
+        icon
+    });
+    // Bind button model to command.
+    view.bind('isOn', 'isEnabled').to(command, 'value', 'isEnabled');
+    // Execute the command.
+    view.on('execute', () => {
+        editor.execute(commandName);
+        editor.editing.view.focus();
+    });
+    return view;
+}

package/src/list.d.ts

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

package/src/list.js

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

package/src/listconfig.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @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/listconfig
+ */
+import { type ArrayOrItem } from 'ckeditor5/src/utils.js';
+/**
+ * The configuration of the {@link module:list/list~List list} feature
+ * and the {@link module:list/legacylist~LegacyList legacy list} feature.
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		list:  ... // The list feature configuration.
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ *
+ * @interface ListConfig
+ */
+export interface ListConfig {
+    /**
+     * The configuration of the {@link module:list/listproperties~ListProperties} feature and the
+     * {@link module:list/legacylistproperties~LegacyListProperties legacy list properties} feature.
+     *
+     * Read more in {@link module:list/listconfig~ListPropertiesConfig}.
+     */
+    properties?: ListPropertiesConfig;
+    /**
+     * Allows multiple blocks in single list item.
+     *
+     * With this option enabled you can have block widgets, for example images or even tables, within a list item.
+     *
+     * **Note:** This is enabled by default.
+     *
+     * @default true
+     */
+    multiBlock?: boolean;
+}
+/**
+ * The configuration of the {@link module:list/listproperties~ListProperties list properties} feature and the
+ * {@link module:list/legacylistproperties~LegacyListProperties legacy list properties} feature.
+ *
+ * This configuration controls the individual list properties. For instance, it enables or disables specific editor commands
+ * operating on lists ({@link module:list/listproperties/liststylecommand~ListStyleCommand `'listStyle'`},
+ * {@link module:list/listproperties/liststartcommand~ListStartCommand `'listStart'`},
+ * {@link module:list/listproperties/listreversedcommand~ListReversedCommand `'listReversed'`}, or on the legacy lists
+ * {@link module:list/legacylistproperties/legacyliststylecommand~LegacyListStyleCommand `'listStyle'`},
+ * {@link module:list/legacylistproperties/legacyliststartcommand~LegacyListStartCommand `'listStart'`},
+ * {@link module:list/legacylistproperties/legacylistreversedcommand~LegacyListReversedCommand `'listReversed'`}), the look of the UI
+ * (`'numberedList'` and `'bulletedList'` dropdowns), and the editor data pipeline (allowed HTML attributes).
+ *
+ * ```ts
+ * ClassicEditor
+ * 	.create( editorElement, {
+ * 		list: {
+ * 			properties: {
+ * 				styles: true,
+ * 				startIndex: true,
+ * 				reversed: true
+ * 			}
+ * 		}
+ * 	} )
+ * 	.then( ... )
+ * 	.catch( ... );
+ * ```
+ */
+export interface ListPropertiesConfig {
+    /**
+     * When set, the list style feature will be enabled.
+     * It allows changing the `list-style-type` style or the `type` HTML attribute of a list.
+     *
+     * **Note**: Styling using the `type` HTML attribute is only available in
+     * {@link module:list/listproperties~ListProperties list properties}
+     * ({@link module:list/listconfig~ListPropertiesStyleConfig learn more}).
+     *
+     * @default true
+     */
+    styles?: boolean | ListPropertiesStyleConfig | ArrayOrItem<ListPropertiesStyleListType>;
+    /**
+     * When set, the list start index feature will be enabled. It allows changing the `start` HTML attribute of the numbered lists. As a
+     * result, it will be possible to specify the start value of the first item in an ordered list.
+     *
+     * **Note**: This configuration does not affect bulleted and to-do lists.
+     *
+     * @default false
+     */
+    startIndex?: boolean;
+    /**
+     * When set, the reversed list feature will be enabled. It allows changing the `reversed` HTML attribute of the numbered lists. As a
+     * result, it will be possible to make the list order descending instead of ascending.
+     *
+     * **Note**: This configuration does not affect bulleted and to-do lists.
+     *
+     * @default false
+     */
+    reversed?: boolean;
+}
+export interface ListPropertiesStyleConfig {
+    /**
+     * Enable style feature for the given list type only.
+     *
+     * ```ts
+     * {
+     * 	list: {
+     * 		properties: {
+     * 			styles: {
+     * 				listTypes: 'numbered'
+     * 			}
+     *
+     * 			// ...
+     * 		}
+     * 	},
+     *
+     * 	// ...
+     * }
+     * ```
+     *
+     *
+     * **Note**: This configuration works only with
+     * {@link module:list/listproperties~ListProperties list properties}.
+     *
+     * @default ['bulleted','numbered']
+     */
+    listTypes?: ArrayOrItem<ListPropertiesStyleListType>;
+    /**
+     * When set `true`, the list style feature will use the `type` attribute of `<ul>` and `<ol>` elements instead of the `list-style-type`
+     * style.
+     *
+     * ```ts
+     * {
+     * 	list: {
+     * 		properties: {
+     * 			styles: {
+     * 				useAttribute: true
+     * 			},
+     *
+     * 			// ...
+     * 		}
+     * 	},
+     *
+     * 	// ...
+     * }
+     * ```
+     *
+     * **Note**: Due to limitations of HTML, the "Decimal with leading zero" style is impossible to set using the `type` attribute.
+     *
+     * **Note**: This configuration works only with
+     * {@link module:list/listproperties~ListProperties list properties}.
+     *
+     * @default false
+     */
+    useAttribute?: boolean;
+}
+export type ListPropertiesStyleListType = 'numbered' | 'bulleted';

package/src/listconfig.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/listproperties/converters.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @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/listproperties/converters
+ */
+import type { UpcastElementEvent } from 'ckeditor5/src/engine.js';
+import type { GetCallback } from 'ckeditor5/src/utils.js';
+import type { AttributeStrategy } from './listpropertiesediting.js';
+/**
+ * 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/listproperties/converters.js

@@ -0,0 +1,43 @@
+/**
+ * @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
+ */
+/**
+ * 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 function listPropertiesUpcastConverter(strategy) {
+    return (evt, data, conversionApi) => {
+        const { writer, schema, consumable } = conversionApi;
+        // If there is no view consumable to consume, set the default attribute value to be able to reconvert nested lists on parent change.
+        // So abort converting if attribute was directly consumed.
+        if (consumable.test(data.viewItem, strategy.viewConsumables) === false) {
+            return;
+        }
+        if (!data.modelRange) {
+            Object.assign(data, conversionApi.convertChildren(data.viewItem, data.modelCursor));
+        }
+        let applied = false;
+        for (const item of data.modelRange.getItems({ shallow: true })) {
+            if (!schema.checkAttribute(item, strategy.attributeName)) {
+                continue;
+            }
+            if (!strategy.appliesToListItem(item)) {
+                continue;
+            }
+            // Set list attributes only on same level items, those nested deeper are already handled by the recursive conversion.
+            if (item.hasAttribute(strategy.attributeName)) {
+                continue;
+            }
+            writer.setAttribute(strategy.attributeName, strategy.getAttributeOnUpcast(data.viewItem), item);
+            applied = true;
+        }
+        if (applied) {
+            consumable.consume(data.viewItem, strategy.viewConsumables);
+        }
+    };
+}

package/src/listproperties/listpropertiesediting.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @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/listproperties/listpropertiesediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import type { Consumables, DowncastWriter, Element, Item, ViewElement } from 'ckeditor5/src/engine.js';
+import ListEditing, { type ListItemAttributesMap } from '../list/listediting.js';
+import ListPropertiesUtils from './listpropertiesutils.js';
+/**
+ * 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 ListPropertiesEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof ListEditing, typeof ListPropertiesUtils];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ListPropertiesEditing";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @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 '../list/listediting' {
+    interface ListItemAttributesMap {
+        listStyle?: string;
+        listStart?: number;
+        listReversed?: boolean;
+    }
+}
+declare module '../list/utils/model' {
+    interface ListElement {
+        getAttribute(key: 'listStyle'): string;
+        getAttribute(key: 'listStart'): number;
+        getAttribute(key: 'listReversed'): boolean;
+    }
+}