@ckeditor/ckeditor5-list 41.1.0 → 41.3.0-alpha.0

package/dist/types/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;
+}

package/dist/types/legacylistproperties/legacylistreversedcommand.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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/legacylistreversedcommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The reversed list command. It changes the `listReversed` attribute of the selected list items. As a result, the list order will be
+ * reversed.
+ * It is used by the {@link module:list/legacylistproperties~LegacyListProperties legacy list properties feature}.
+ */
+export default class LegacyListReversedCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    value: boolean | null;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options.reversed Whether the list should be reversed.
+     */
+    execute(options?: {
+        reversed?: boolean;
+    }): void;
+    /**
+     * Checks the command's {@link #value}.
+     *
+     * @returns The current value.
+     */
+    private _getValue;
+}

package/dist/types/legacylistproperties/legacyliststartcommand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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/legacyliststartcommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The list start index command. It changes the `listStart` attribute of the selected list items.
+ * It is used by the {@link module:list/legacylistproperties~LegacyListProperties legacy list properties feature}.
+ */
+export default class LegacyListStartCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    value: number | null;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options.startIndex The list start index.
+     */
+    execute({ startIndex }?: {
+        startIndex?: number;
+    }): void;
+    /**
+     * Checks the command's {@link #value}.
+     *
+     * @returns The current value.
+     */
+    private _getValue;
+}

package/dist/types/legacylistproperties/legacyliststylecommand.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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/legacyliststylecommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The list style command. It changes the `listStyle` attribute of the selected list items.
+ *
+ * If the list type (numbered or bulleted) can be inferred from the passed style type,
+ * the command tries to convert selected items to a list of that type.
+ * It is used by the {@link module:list/legacylistproperties~LegacyListProperties legacy list properties feature}.
+ */
+export default class LegacyListStyleCommand extends Command {
+    isStyleTypeSupported: undefined;
+    /**
+     * @inheritDoc
+     * @readonly
+     */
+    value: string | null;
+    /**
+     * The default type of the list style.
+     */
+    readonly defaultType: string;
+    /**
+     * Creates an instance of the command.
+     *
+     * @param editor The editor instance.
+     * @param defaultType The list type that will be used by default if the value was not specified during
+     * the command execution.
+     */
+    constructor(editor: Editor, defaultType: string);
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options.type The type of the list style, e.g. `'disc'` or `'square'`. If `null` is specified, the default
+     * style will be applied.
+     */
+    execute(options?: {
+        type?: string | null;
+    }): void;
+    /**
+     * 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;
+    /**
+     * Checks if the provided list style is valid. Also changes the selection to a list if it's not set yet.
+     *
+     * @param The type of the list style. If `null` is specified, the function does nothing.
+    */
+    private _tryToConvertItemsToList;
+}

package/dist/types/legacylistproperties.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import LegacyListPropertiesEditing from './legacylistproperties/legacylistpropertiesediting.js';
+import ListPropertiesUI from './listproperties/listpropertiesui.js';
+/**
+ * The legacy list properties feature.
+ *
+ * This is a "glue" plugin that loads the {@link module:list/legacylistproperties/legacylistpropertiesediting~LegacyListPropertiesEditing
+ * legacy list properties editing feature} and the
+ * {@link module:list/listproperties/listpropertiesui~ListPropertiesUI list properties UI feature}.
+ */
+export default class LegacyListProperties extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof LegacyListPropertiesEditing, typeof ListPropertiesUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LegacyListProperties";
+}

package/dist/types/legacytodolist/legacychecktodolistcommand.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @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/legacytodolist/legacychecktodolistcommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+import type { Element } from 'ckeditor5/src/engine.js';
+/**
+ * The check to-do command.
+ *
+ * The command is registered by the {@link module:list/legacytodolist/legacytodolistediting~LegacyTodoListEditing} as
+ * the `checkTodoList` editor command and it is also available via aliased `todoListCheck` name.
+ */
+export default class LegacyCheckTodoListCommand extends Command {
+    /**
+     * A list of to-do list items selected by the {@link module:engine/model/selection~Selection}.
+     *
+     * @observable
+     * @readonly
+     */
+    value: boolean;
+    /**
+     * A list of to-do list items selected by the {@link module:engine/model/selection~Selection}.
+     *
+     * @internal
+     */
+    _selectedElements: Array<Element>;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * Updates the command's {@link #value} and {@link #isEnabled} properties based on the current selection.
+     */
+    refresh(): void;
+    /**
+     * Gets all to-do list items selected by the {@link module:engine/model/selection~Selection}.
+     */
+    private _getSelectedItems;
+    /**
+     * Executes the command.
+     *
+     * @param options.forceValue If set, it will force the command behavior. If `true`, the command will apply
+     * the attribute. Otherwise, the command will remove the attribute. If not set, the command will look for its current
+     * value to decide what it should do.
+     */
+    execute(options?: {
+        forceValue?: boolean;
+    }): void;
+}

package/dist/types/legacytodolist/legacytodolistconverters.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @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/legacytodolist/legacytodolistconverters
+ */
+import type { DowncastAttributeEvent, DowncastInsertEvent, Element, MapperModelToViewPositionEvent, Model, UpcastElementEvent, EditingView } from 'ckeditor5/src/engine.js';
+import { type GetCallback } from 'ckeditor5/src/utils.js';
+/**
+ * A model-to-view converter for the `listItem` model element insertion.
+ *
+ * It converts the `listItem` model element to an unordered list with a {@link module:engine/view/uielement~UIElement checkbox element}
+ * at the beginning of each list item. It also merges the list with surrounding lists (if available).
+ *
+ * It is used by {@link module:engine/controller/editingcontroller~EditingController}.
+ *
+ * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert
+ * @param model Model instance.
+ * @param onCheckboxChecked Callback function.
+ * @returns Returns a conversion callback.
+ */
+export declare function modelViewInsertion(model: Model, onCheckboxChecked: (element: Element) => void): GetCallback<DowncastInsertEvent<Element>>;
+/**
+ * A model-to-view converter for the `listItem` model element insertion.
+ *
+ * It is used by {@link module:engine/controller/datacontroller~DataController}.
+ *
+ * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:insert
+ * @param model Model instance.
+ * @returns Returns a conversion callback.
+ */
+export declare function dataModelViewInsertion(model: Model): GetCallback<DowncastInsertEvent<Element>>;
+/**
+ * A view-to-model converter for the checkbox element inside a view list item.
+ *
+ * It changes the `listType` of the model `listItem` to a `todo` value.
+ * When a view checkbox element is marked as checked, an additional `todoListChecked="true"` attribute is added to the model item.
+ *
+ * It is used by {@link module:engine/controller/datacontroller~DataController}.
+ *
+ * @see module:engine/conversion/upcastdispatcher~UpcastDispatcher#event:element
+ */
+export declare const dataViewModelCheckmarkInsertion: GetCallback<UpcastElementEvent>;
+/**
+ * A model-to-view converter for the `listType` attribute change on the `listItem` model element.
+ *
+ * This change means that the `<li>` element parent changes to `<ul class="todo-list">` and a
+ * {@link module:engine/view/uielement~UIElement checkbox UI element} is added at the beginning
+ * of the list item element (or vice versa).
+ *
+ * This converter is preceded by {@link module:list/legacylist/legacyconverters~modelViewChangeType} and followed by
+ * {@link module:list/legacylist/legacyconverters~modelViewMergeAfterChangeType} to handle splitting and merging surrounding lists
+ * of the same type.
+ *
+ * It is used by {@link module:engine/controller/editingcontroller~EditingController}.
+ *
+ * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute
+ * @param onCheckedChange Callback fired after clicking the checkbox UI element.
+ * @param view Editing view controller.
+ * @returns Returns a conversion callback.
+ */
+export declare function modelViewChangeType(onCheckedChange: (element: Element) => void, view: EditingView): GetCallback<DowncastAttributeEvent<Element>>;
+/**
+ * A model-to-view converter for the `todoListChecked` attribute change on the `listItem` model element.
+ *
+ * It marks the {@link module:engine/view/uielement~UIElement checkbox UI element} as checked.
+ *
+ * It is used by {@link module:engine/controller/editingcontroller~EditingController}.
+ *
+ * @see module:engine/conversion/downcastdispatcher~DowncastDispatcher#event:attribute
+ * @param onCheckedChange Callback fired after clicking the checkbox UI element.
+ * @returns Returns a conversion callback.
+ */
+export declare function modelViewChangeChecked(onCheckedChange: (element: Element) => void): GetCallback<DowncastAttributeEvent<Element>>;
+/**
+ * A model-to-view position at zero offset mapper.
+ *
+ * This helper ensures that position inside todo-list in the view is mapped after the checkbox.
+ *
+ * It only handles the position at the beginning of a list item as other positions are properly mapped be the default mapper.
+ */
+export declare function mapModelToViewPosition(view: EditingView): GetCallback<MapperModelToViewPositionEvent>;

package/dist/types/legacytodolist/legacytodolistediting.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import LegacyListEditing from '../legacylist/legacylistediting.js';
+/**
+ * The engine of the to-do list feature. It handles creating, editing and removing to-do lists and their items.
+ *
+ * It registers the entire functionality of the {@link module:list/legacylist/legacylistediting~LegacyListEditing legacy list editing
+ * plugin} and extends it with the commands:
+ *
+ * - `'todoList'`,
+ * - `'checkTodoList'`,
+ * - `'todoListCheck'` as an alias for `checkTodoList` command.
+ */
+export default class LegacyTodoListEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LegacyTodoListEditing";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof LegacyListEditing];
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Handles the checkbox element change, moves the selection to the corresponding model item to make it possible
+     * to toggle the `todoListChecked` attribute using the command, and restores the selection position.
+     *
+     * Some say it's a hack :) Moving the selection only for executing the command on a certain node and restoring it after,
+     * is not a clear solution. We need to design an API for using commands beyond the selection range.
+     * See https://github.com/ckeditor/ckeditor5/issues/1954.
+     */
+    private _handleCheckmarkChange;
+}

package/dist/types/legacytodolist.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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/legacytodolist
+ */
+import LegacyTodoListEditing from './legacytodolist/legacytodolistediting.js';
+import TodoListUI from './todolist/todolistui.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+import '../theme/todolist.css';
+/**
+ * The legacy to-do list feature.
+ *
+ * This is a "glue" plugin that loads the {@link module:list/legacytodolist/legacytodolistediting~LegacyTodoListEditing legacy to-do list
+ * editing feature} and the {@link module:list/todolist/todolistui~TodoListUI to-do list UI feature}.
+ */
+export default class LegacyTodoList extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof LegacyTodoListEditing, typeof TodoListUI];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "LegacyTodoList";
+}

package/dist/types/list/adjacentlistssupport.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+export default class AdjacentListsSupport extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "AdjacentListsSupport";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/list/converters.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @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/converters
+ */
+import { type DowncastAttributeEvent, type EditingController, type Element, type ElementCreatorFunction, type Mapper, type Model, type UpcastElementEvent, type ViewElement } from 'ckeditor5/src/engine.js';
+import type { GetCallback } from 'ckeditor5/src/utils.js';
+import { type ListElement } from './utils/model.js';
+import type { default as ListEditing, DowncastStrategy } from './listediting.js';
+/**
+ * Returns the upcast converter for list items. It's supposed to work after the block converters (content inside list items) are converted.
+ *
+ * @internal
+ */
+export declare function listItemUpcastConverter(): GetCallback<UpcastElementEvent>;
+/**
+ * Returns the upcast converter for the `<ul>` and `<ol>` view elements that cleans the input view of garbage.
+ * This is mostly to clean whitespaces from between the `<li>` view elements inside the view list element. However,
+ * incorrect data can also be cleared if the view was incorrect.
+ *
+ * @internal
+ */
+export declare function listUpcastCleanList(): GetCallback<UpcastElementEvent>;
+/**
+ * Returns a model document change:data event listener that triggers conversion of related items if needed.
+ *
+ * @internal
+ * @param model The editor model.
+ * @param editing The editing controller.
+ * @param attributeNames The list of all model list attributes (including registered strategies).
+ * @param listEditing The document list editing plugin.
+ */
+export declare function reconvertItemsOnDataChange(model: Model, editing: EditingController, attributeNames: Array<string>, listEditing: ListEditing): () => void;
+/**
+ * Returns the list item downcast converter.
+ *
+ * @internal
+ * @param attributeNames A list of attribute names that should be converted if they are set.
+ * @param strategies The strategies.
+ * @param model The model.
+ */
+export declare function listItemDowncastConverter(attributeNames: Array<string>, strategies: Array<DowncastStrategy>, model: Model, { dataPipeline }?: {
+    dataPipeline?: boolean;
+}): GetCallback<DowncastAttributeEvent<ListElement>>;
+/**
+ * Returns the bogus paragraph view element creator. A bogus paragraph is used if a list item contains only a single block or nested list.
+ *
+ * @internal
+ * @param attributeNames The list of all model list attributes (including registered strategies).
+ */
+export declare function bogusParagraphCreator(attributeNames: Array<string>, { dataPipeline }?: {
+    dataPipeline?: boolean;
+}): ElementCreatorFunction;
+/**
+ * Helper for mapping mode to view elements. It's using positions mapping instead of mapper.toViewElement( element )
+ * to find outermost view element. This is for cases when mapping is using inner view element like in the code blocks (pre > code).
+ *
+ * @internal
+ * @param element The model element.
+ * @param mapper The mapper instance.
+ * @param model The model.
+ */
+export declare function findMappedViewElement(element: Element, mapper: Mapper, model: Model): ViewElement | null;

package/dist/types/list/listcommand.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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';
+/**
+ * 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: 'numbered' | 'bulleted' | 'todo';
+    /**
+     * 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;
+    /**
+     * 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: 'numbered' | 'bulleted' | 'todo');
+    /**
+     * @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.
+     */
+    execute(options?: {
+        forceValue?: boolean;
+    }): 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>];
+};