@ckeditor/ckeditor5-list 0.0.0-internal-20241017.0

package/src/list/listcommand.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/list/listcommand
+ */
+import type { Element } from 'ckeditor5/src/engine.js';
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import { type ListType } from './listediting.js';
+/**
+ * The list command. It is used by the {@link module:list/list~List list feature}.
+ */
+export default class ListCommand extends Command {
+    /**
+     * The type of the list created by the command.
+     */
+    readonly type: ListType;
+    /**
+     * A flag indicating whether the command is active, which means that the selection starts in a list of the same type.
+     *
+     * @observable
+     * @readonly
+     */
+    value: boolean;
+    /**
+     * List Walker options that change the range of the list items to be changed when the selection is collapsed within a list item.
+     *
+     * In a multi-level list, when the selection is collapsed within a list item, instead of changing only the list items of the same list
+     * type and current indent level, the entire list structure is changed (all list items at all indent levels of any list type).
+     */
+    private readonly _listWalkerOptions?;
+    /**
+     * Creates an instance of the command.
+     *
+     * @param editor The editor instance.
+     * @param type List type that will be handled by this command.
+     */
+    constructor(editor: Editor, type: ListType, options?: {
+        multiLevel?: boolean;
+    });
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the list command.
+     *
+     * @fires execute
+     * @fires afterExecute
+     * @param options Command options.
+     * @param options.forceValue If set, it will force the command behavior. If `true`, the command will try to convert the
+     * selected items and potentially the neighbor elements to the proper list items. If set to `false` it will convert selected elements
+     * to paragraphs. If not set, the command will toggle selected elements to list items or paragraphs, depending on the selection.
+     * @param options.additionalAttributes Additional attributes that are set for list items when the command is executed.
+     */
+    execute(options?: {
+        forceValue?: boolean;
+        additionalAttributes?: Record<string, unknown>;
+    }): void;
+    /**
+     * Fires the `afterExecute` event.
+     *
+     * @param changedBlocks The changed list elements.
+     */
+    private _fireAfterExecute;
+    /**
+     * Checks the command's {@link #value}.
+     *
+     * @returns The current value.
+     */
+    private _getValue;
+    /**
+     * Checks whether the command can be enabled in the current context.
+     *
+     * @returns Whether the command should be enabled.
+     */
+    private _checkEnabled;
+}
+/**
+ * Event fired by the {@link ~ListCommand#execute} method.
+ *
+ * It allows to execute an action after executing the {@link ~ListCommand#execute} method,
+ * for example adjusting attributes of changed list items.
+ *
+ * @internal
+ * @eventName ~ListCommand#afterExecute
+ */
+export type ListCommandAfterExecuteEvent = {
+    name: 'afterExecute';
+    args: [changedBlocks: Array<Element>];
+};

package/src/list/listcommand.js

@@ -0,0 +1,163 @@
+/**
+ * @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 { Command } from 'ckeditor5/src/core.js';
+import { splitListItemBefore, expandListBlocksToCompleteItems, getListItemBlocks, getListItems, removeListAttributes, outdentFollowingItems, ListItemUid, sortBlocks, getSelectedBlockObject, isListItemBlock, canBecomeSimpleListItem } from './utils/model.js';
+/**
+ * The list command. It is used by the {@link module:list/list~List list feature}.
+ */
+export default class ListCommand extends Command {
+    /**
+     * Creates an instance of the command.
+     *
+     * @param editor The editor instance.
+     * @param type List type that will be handled by this command.
+     */
+    constructor(editor, type, options = {}) {
+        super(editor);
+        this.type = type;
+        this._listWalkerOptions = options.multiLevel ? {
+            higherIndent: true,
+            lowerIndent: true,
+            sameAttributes: []
+        } : undefined;
+    }
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        this.value = this._getValue();
+        this.isEnabled = this._checkEnabled();
+    }
+    /**
+     * Executes the list command.
+     *
+     * @fires execute
+     * @fires afterExecute
+     * @param options Command options.
+     * @param options.forceValue If set, it will force the command behavior. If `true`, the command will try to convert the
+     * selected items and potentially the neighbor elements to the proper list items. If set to `false` it will convert selected elements
+     * to paragraphs. If not set, the command will toggle selected elements to list items or paragraphs, depending on the selection.
+     * @param options.additionalAttributes Additional attributes that are set for list items when the command is executed.
+     */
+    execute(options = {}) {
+        const model = this.editor.model;
+        const document = model.document;
+        const selectedBlockObject = getSelectedBlockObject(model);
+        const blocks = Array.from(document.selection.getSelectedBlocks())
+            .filter(block => model.schema.checkAttribute(block, 'listType') || canBecomeSimpleListItem(block, model.schema));
+        // Whether we are turning off some items.
+        const turnOff = options.forceValue !== undefined ? !options.forceValue : this.value;
+        model.change(writer => {
+            if (turnOff) {
+                const lastBlock = blocks[blocks.length - 1];
+                // Split the first block from the list item.
+                const itemBlocks = getListItemBlocks(lastBlock, { direction: 'forward' });
+                const changedBlocks = [];
+                if (itemBlocks.length > 1) {
+                    changedBlocks.push(...splitListItemBefore(itemBlocks[1], writer));
+                }
+                // Strip list attributes.
+                changedBlocks.push(...removeListAttributes(blocks, writer));
+                // Outdent items following the selected list item.
+                changedBlocks.push(...outdentFollowingItems(lastBlock, writer));
+                this._fireAfterExecute(changedBlocks);
+            }
+            // Changing type of list items for a collapsed selection inside a list item.
+            else if ((selectedBlockObject || document.selection.isCollapsed) && isListItemBlock(blocks[0])) {
+                const changedBlocks = getListItems(selectedBlockObject || blocks[0], this._listWalkerOptions);
+                for (const block of changedBlocks) {
+                    writer.setAttributes({
+                        ...options.additionalAttributes,
+                        listType: this.type
+                    }, block);
+                }
+                this._fireAfterExecute(changedBlocks);
+            }
+            // Turning on the list items for a non-collapsed selection.
+            else {
+                const changedBlocks = [];
+                for (const block of blocks) {
+                    // Promote the given block to the list item.
+                    if (!block.hasAttribute('listType')) {
+                        // Rename block to a simple list item if this option is enabled.
+                        if (!block.is('element', 'listItem') && canBecomeSimpleListItem(block, model.schema)) {
+                            writer.rename(block, 'listItem');
+                        }
+                        writer.setAttributes({
+                            ...options.additionalAttributes,
+                            listIndent: 0,
+                            listItemId: ListItemUid.next(),
+                            listType: this.type
+                        }, block);
+                        changedBlocks.push(block);
+                    }
+                    // Change the type of list item.
+                    else {
+                        for (const node of expandListBlocksToCompleteItems(block, { withNested: false })) {
+                            if (node.getAttribute('listType') != this.type) {
+                                writer.setAttributes({
+                                    ...options.additionalAttributes,
+                                    listType: this.type
+                                }, node);
+                                changedBlocks.push(node);
+                            }
+                        }
+                    }
+                }
+                this._fireAfterExecute(changedBlocks);
+            }
+        });
+    }
+    /**
+     * Fires the `afterExecute` event.
+     *
+     * @param changedBlocks The changed list elements.
+     */
+    _fireAfterExecute(changedBlocks) {
+        this.fire('afterExecute', sortBlocks(new Set(changedBlocks)));
+    }
+    /**
+     * Checks the command's {@link #value}.
+     *
+     * @returns The current value.
+     */
+    _getValue() {
+        const selection = this.editor.model.document.selection;
+        const blocks = Array.from(selection.getSelectedBlocks());
+        if (!blocks.length) {
+            return false;
+        }
+        for (const block of blocks) {
+            if (block.getAttribute('listType') != this.type) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Checks whether the command can be enabled in the current context.
+     *
+     * @returns Whether the command should be enabled.
+     */
+    _checkEnabled() {
+        const model = this.editor.model;
+        const schema = model.schema;
+        const selection = model.document.selection;
+        const blocks = Array.from(selection.getSelectedBlocks());
+        if (!blocks.length) {
+            return false;
+        }
+        // If command value is true it means that we are in list item, so the command should be enabled.
+        if (this.value) {
+            return true;
+        }
+        for (const block of blocks) {
+            if (schema.checkAttribute(block, 'listType') || canBecomeSimpleListItem(block, schema)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/src/list/listediting.d.ts

@@ -0,0 +1,226 @@
+/**
+ * @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/listediting
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import type { DowncastWriter, Element, ViewElement, ViewAttributeElement, Writer } from 'ckeditor5/src/engine.js';
+import { Delete } from 'ckeditor5/src/typing.js';
+import { Enter } from 'ckeditor5/src/enter.js';
+import ListUtils from './listutils.js';
+import { ListBlocksIterable } from './utils/listwalker.js';
+import { ClipboardPipeline } from 'ckeditor5/src/clipboard.js';
+import '../../theme/documentlist.css';
+import '../../theme/list.css';
+export type ListType = 'numbered' | 'bulleted' | 'todo' | 'customNumbered' | 'customBulleted';
+/**
+ * Map of model attributes applicable to list blocks.
+ */
+export interface ListItemAttributesMap {
+    listType?: ListType;
+    listIndent?: number;
+    listItemId?: string;
+}
+/**
+ * The editing part of the document-list feature. It handles creating, editing and removing lists and list items.
+ */
+export default class ListEditing extends Plugin {
+    /**
+     * The list of registered downcast strategies.
+     */
+    private readonly _downcastStrategies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ListEditing";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof Enter, typeof Delete, typeof ListUtils, typeof ClipboardPipeline];
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * @inheritDoc
+     */
+    afterInit(): void;
+    /**
+     * Registers a downcast strategy.
+     *
+     * **Note**: Strategies must be registered in the `Plugin#init()` phase so that it can be applied
+     * in the `ListEditing#afterInit()`.
+     *
+     * @param strategy The downcast strategy to register.
+     */
+    registerDowncastStrategy(strategy: DowncastStrategy): void;
+    /**
+     * Returns list of model attribute names that should affect downcast conversion.
+     */
+    getListAttributeNames(): Array<string>;
+    /**
+     * Attaches the listener to the {@link module:engine/view/document~Document#event:delete} event and handles backspace/delete
+     * keys in and around document lists.
+     */
+    private _setupDeleteIntegration;
+    /**
+     * Attaches a listener to the {@link module:engine/view/document~Document#event:enter} event and handles enter key press
+     * in document lists.
+     */
+    private _setupEnterIntegration;
+    /**
+     * Attaches a listener to the {@link module:engine/view/document~Document#event:tab} event and handles tab key and tab+shift keys
+     * presses in document lists.
+     */
+    private _setupTabIntegration;
+    /**
+     * Registers the conversion helpers for the document-list feature.
+     */
+    private _setupConversion;
+    /**
+     * Registers model post-fixers.
+     */
+    private _setupModelPostFixing;
+    /**
+     * Integrates the feature with the clipboard via {@link module:engine/model/model~Model#insertContent} and
+     * {@link module:engine/model/model~Model#getSelectedContent}.
+     */
+    private _setupClipboardIntegration;
+    /**
+     * Informs editor accessibility features about keystrokes brought by the plugin.
+     */
+    private _setupAccessibilityIntegration;
+}
+/**
+ * The attribute to attribute downcast strategy for UL, OL, LI elements.
+ */
+export interface AttributeDowncastStrategy {
+    /**
+     * The scope of the downcast (whether it applies to LI or OL/UL).
+     */
+    scope: 'list' | 'item';
+    /**
+     * The model attribute name.
+     */
+    attributeName: string;
+    /**
+     * Sets the property on the view element.
+     */
+    setAttributeOnDowncast(writer: DowncastWriter, value: unknown, element: ViewElement): void;
+}
+/**
+ * The custom marker downcast strategy.
+ */
+export interface ItemMarkerDowncastStrategy {
+    /**
+     * The scope of the downcast.
+     */
+    scope: 'itemMarker';
+    /**
+     * The model attribute name.
+     */
+    attributeName: string;
+    /**
+     * Creates a view element for a custom item marker.
+     */
+    createElement(writer: DowncastWriter, modelElement: Element, { dataPipeline }: {
+        dataPipeline?: boolean;
+    }): ViewElement | null;
+    /**
+     * Creates an AttributeElement to be used for wrapping a first block of a list item.
+     */
+    createWrapperElement?(writer: DowncastWriter, modelElement: Element, { dataPipeline }: {
+        dataPipeline?: boolean;
+    }): ViewAttributeElement;
+    /**
+     * Should return true if the given list block can be wrapped with the wrapper created by `createWrapperElement()`
+     * or only the marker element should be wrapped.
+     */
+    canWrapElement?(modelElement: Element): boolean;
+    /**
+     * Should return true if the custom marker can be injected into a given list block.
+     * Otherwise, custom marker view element is always injected before the block element.
+     */
+    canInjectMarkerIntoElement?(modelElement: Element): boolean;
+}
+/**
+ * The downcast strategy.
+ */
+export type DowncastStrategy = AttributeDowncastStrategy | ItemMarkerDowncastStrategy;
+/**
+ * Event fired on changes detected on the model list element to verify if the view representation of a list element
+ * is representing those attributes.
+ *
+ * It allows triggering a re-wrapping of a list item.
+ *
+ * @internal
+ * @eventName ~ListEditing#postFixer
+ * @param listHead The head element of a list.
+ * @param writer The writer to do changes with.
+ * @param seenIds The set of already known IDs.
+ * @returns If a post-fixer made a change of the model tree, it should return `true`.
+ */
+export type ListEditingPostFixerEvent = {
+    name: 'postFixer';
+    args: [
+        {
+            listNodes: ListBlocksIterable;
+            listHead: Element;
+            writer: Writer;
+            seenIds: Set<string>;
+        }
+    ];
+    return: boolean;
+};
+/**
+ * Event fired on changes detected on the model list element to verify if the view representation of a list element
+ * is representing those attributes.
+ *
+ * It allows triggering a re-wrapping of a list item.
+ *
+ * **Note**: For convenience this event is namespaced and could be captured as `checkAttributes:list` or `checkAttributes:item`.
+ *
+ * @internal
+ * @eventName ~ListEditing#checkAttributes
+ */
+export type ListEditingCheckAttributesEvent = {
+    name: 'checkAttributes' | 'checkAttributes:list' | 'checkAttributes:item';
+    args: [
+        {
+            viewElement: ViewElement & {
+                id?: string;
+            };
+            modelAttributes: ListItemAttributesMap;
+        }
+    ];
+    return: boolean;
+};
+/**
+ * Event fired on changes detected on the model list element to verify if the view representation of a list block element
+ * is representing those attributes.
+ *
+ * It allows triggering a reconversion of a list item block.
+ *
+ * @internal
+ * @eventName ~ListEditing#checkElement
+ */
+export type ListEditingCheckElementEvent = {
+    name: 'checkElement';
+    args: [
+        {
+            viewElement: ViewElement;
+            modelElement: Element;
+        }
+    ];
+    return: boolean;
+};