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

package/src/listproperties/liststylecommand.js

@@ -7,6 +7,7 @@
  */
 import { Command } from 'ckeditor5/src/core';
 import { getListTypeFromListStyleType, getSelectedListItems } from '../list/utils';
+import '../listcommands';
 /**
  * The list style command. It changes the `listStyle` attribute of the selected list items.
  *
@@ -77,7 +78,7 @@ export default class ListStyleCommand extends Command {
         return numberedList.isEnabled || bulletedList.isEnabled;
     }
     /**
-     * Check if the provided list style is valid. Also change the selection to a list if it's not set yet.
+     * 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.
     */

package/src/listproperties/ui/collapsibleview.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @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/ui/collapsibleview
+ */
+import type { Locale } from 'ckeditor5/src/utils';
+import { View, ButtonView, type ViewCollection } from 'ckeditor5/src/ui';
+import '../../../theme/collapsible.css';
+/**
+ * A collapsible UI component. Consists of a labeled button and a container which can be collapsed
+ * by clicking the button. The collapsible container can be a host to other UI views.
+ *
+ * @internal
+ */
+export default class CollapsibleView extends View {
+    /**
+     * `true` when the container with {@link #children} is collapsed. `false` otherwise.
+     *
+     * @observable
+     */
+    isCollapsed: boolean;
+    /**
+     * The text label of the {@link #buttonView}.
+     *
+     * @observable
+     * @default 'Show more'
+     */
+    label: string;
+    /**
+     * The ID of the label inside the {@link #buttonView} that describes the collapsible
+     * container for assistive technologies. Set after the button was {@link #render rendered}.
+     *
+     * @internal
+     * @readonly
+     * @observable
+     */
+    _collapsibleAriaLabelUid: string | undefined;
+    /**
+     * The main button that, when clicked, collapses or expands the container with {@link #children}.
+     */
+    readonly buttonView: ButtonView;
+    /**
+     * A collection of the child views that can be collapsed by clicking the {@link #buttonView}.
+     */
+    readonly children: ViewCollection;
+    /**
+     * Creates an instance of the collapsible view.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param childViews An optional array of initial child views to be inserted into the collapsible.
+     */
+    constructor(locale: Locale, childViews?: Array<View>);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * Creates the main {@link #buttonView} of the collapsible.
+     */
+    private _createButtonView;
+}

package/src/listproperties/ui/listpropertiesview.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @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/ui/listpropertiesview
+ */
+import { View, ViewCollection, FocusCycler, SwitchButtonView, LabeledFieldView, type ButtonView, type InputNumberView } from 'ckeditor5/src/ui';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils';
+import CollapsibleView from './collapsibleview';
+import type { ListPropertiesConfig } from '../../listconfig';
+import '../../../theme/listproperties.css';
+/**
+ * The list properties view to be displayed in the list dropdown.
+ *
+ * Contains a grid of available list styles and, for numbered list, also the list start index and reversed fields.
+ *
+ * @internal
+ */
+export default class ListPropertiesView extends View {
+    /**
+     * @inheritDoc
+     */
+    locale: Locale;
+    /**
+     * A collection of the child views.
+     */
+    readonly children: ViewCollection;
+    /**
+     * A view that renders the grid of list styles.
+     */
+    readonly stylesView: StylesView | null;
+    /**
+     * A collapsible view that hosts additional list property fields ({@link #startIndexFieldView} and
+     * {@link #reversedSwitchButtonView}) to visually separate them from the {@link #stylesView grid of styles}.
+     *
+     * **Note**: Only present when:
+     * * the view represents **numbered** list properties,
+     * * and the {@link #stylesView} is rendered,
+     * * and either {@link #startIndexFieldView} or {@link #reversedSwitchButtonView} is rendered.
+     *
+     * @readonly
+     */
+    additionalPropertiesCollapsibleView: CollapsibleView | null;
+    /**
+     * A labeled number field allowing the user to set the start index of the list.
+     *
+     * **Note**: Only present when the view represents **numbered** list properties.
+     *
+     * @readonly
+     */
+    startIndexFieldView: LabeledFieldView<InputNumberView> | null;
+    /**
+     * A switch button allowing the user to make the edited list reversed.
+     *
+     * **Note**: Only present when the view represents **numbered** list properties.
+     *
+     * @readonly
+     */
+    reversedSwitchButtonView: SwitchButtonView | null;
+    /**
+     * Tracks information about the DOM focus in the view.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * A collection of views that can be focused in the properties view.
+     */
+    readonly focusables: ViewCollection;
+    /**
+     * Helps cycling over {@link #focusables} in the view.
+     */
+    readonly focusCycler: FocusCycler;
+    /**
+     * Creates an instance of the list properties view.
+     *
+     * @param locale The {@link module:core/editor/editor~Editor#locale} instance.
+     * @param options Options of the view.
+     * @param options.enabledProperties An object containing the configuration of enabled list property names.
+     * Allows conditional rendering the sub-components of the properties view.
+     * @param options.styleButtonViews A list of style buttons to be rendered
+     * inside the styles grid. The grid will not be rendered when `enabledProperties` does not include the `'styles'` key.
+     * @param options.styleGridAriaLabel An assistive technologies label set on the grid of styles (if the grid is rendered).
+     */
+    constructor(locale: Locale, { enabledProperties, styleButtonViews, styleGridAriaLabel }: {
+        enabledProperties: ListPropertiesConfig;
+        styleButtonViews: Array<ButtonView> | null;
+        styleGridAriaLabel: string;
+    });
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    focus(): void;
+    /**
+     * @inheritDoc
+     */
+    focusLast(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Creates the list styles grid.
+     *
+     * @param styleButtons Buttons to be placed in the grid.
+     * @param styleGridAriaLabel The assistive technology label of the grid.
+     */
+    private _createStylesView;
+    /**
+     * Renders {@link #startIndexFieldView} and/or {@link #reversedSwitchButtonView} depending on the configuration of the properties view.
+     *
+     * @param enabledProperties An object containing the configuration of enabled list property names
+     * (see {@link #constructor}).
+     */
+    private _addNumberedListPropertyViews;
+    /**
+     * Creates the list start index labeled field.
+     */
+    private _createStartIndexField;
+    /**
+     * Creates the reversed list switch button.
+     */
+    private _createReversedSwitchButton;
+}
+export type StylesView = View & {
+    children: ViewCollection;
+    focusTracker: FocusTracker;
+    keystrokes: KeystrokeHandler;
+    focus(): void;
+};
+/**
+ * Fired when the list start index value has changed via {@link #startIndexFieldView}.
+ *
+ * @eventName listStart
+ */
+export type ListPropertiesViewListStartEvent = {
+    name: 'listStart';
+    args: [data: {
+        startIndex: number;
+    }];
+};
+/**
+ * Fired when the list order has changed (reversed) via {@link #reversedSwitchButtonView}.
+ *
+ * @eventName listReversed
+ */
+export type ListPropertiesViewListReversedEvent = {
+    name: 'listReversed';
+    args: [];
+};

package/src/listproperties.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/listproperties
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import './listconfig';
+/**
+ * The list properties feature.
+ *
+ * This is a "glue" plugin that loads the {@link module:list/listproperties/listpropertiesediting~ListPropertiesEditing list properties
+ * editing feature} and the {@link module:list/listproperties/listpropertiesui~ListPropertiesUI list properties UI feature}.
+ */
+export default class ListProperties extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ListProperties';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [ListProperties.pluginName]: ListProperties;
+    }
+}

package/src/listproperties.js

@@ -8,6 +8,7 @@
 import { Plugin } from 'ckeditor5/src/core';
 import ListPropertiesEditing from './listproperties/listpropertiesediting';
 import ListPropertiesUI from './listproperties/listpropertiesui';
+import './listconfig';
 /**
  * The list properties feature.
  *

package/src/liststyle.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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/liststyle
+ */
+import { Plugin, type Editor, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * The list style feature.
+ *
+ * This is an obsolete plugin that exists for backward compatibility only.
+ * Use the {@link module:list/listproperties~ListProperties list properties plugin} instead.
+ *
+ * @deprecated
+ */
+export default class ListStyle extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'ListStyle';
+    constructor(editor: Editor);
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [ListStyle.pluginName]: ListStyle;
+    }
+}

package/src/todolist/checktodolistcommand.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @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/todolist/checktodolistcommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core';
+import type { Element } from 'ckeditor5/src/engine';
+import '../listcommands';
+/**
+ * The check to-do command.
+ *
+ * The command is registered by the {@link module:list/todolist/todolistediting~TodoListEditing} as
+ * the `checkTodoList` editor command and it is also available via aliased `todoListCheck` name.
+ */
+export default class CheckTodoListCommand 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/src/todolist/checktodolistcommand.js

@@ -7,6 +7,7 @@
  */
 import { Command } from 'ckeditor5/src/core';
 const attributeKey = 'todoListChecked';
+import '../listcommands';
 /**
  * The check to-do command.
  *

package/src/todolist/todolistconverters.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @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/todolist/todolistconverters
+ */
+import type { DowncastAttributeEvent, DowncastInsertEvent, Element, MapperModelToViewPositionEvent, Model, UpcastElementEvent, View } from 'ckeditor5/src/engine';
+import { type GetCallback } from 'ckeditor5/src/utils';
+/**
+ * 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/list/converters~modelViewChangeType} and followed by
+ * {@link module:list/list/converters~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: View): 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: View): GetCallback<MapperModelToViewPositionEvent>;

package/src/todolist/todolistediting.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @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
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+/**
+ * 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/list/listediting~ListEditing list editing plugin} and extends
+ * it with the commands:
+ *
+ * - `'todoList'`,
+ * - `'checkTodoList'`,
+ * - `'todoListCheck'` as an alias for `checkTodoList` command.
+ */
+export default class TodoListEditing extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TodoListEditing';
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @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;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [TodoListEditing.pluginName]: TodoListEditing;
+    }
+}

package/src/todolist/todolistui.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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
+ */
+import { Plugin } from 'ckeditor5/src/core';
+/**
+ * The to-do list UI feature. It introduces the `'todoList'` button that
+ * allows to convert elements to and from to-do list items and to indent or outdent them.
+ */
+export default class TodoListUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TodoListUI';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [TodoListUI.pluginName]: TodoListUI;
+    }
+}

package/src/todolist.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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
+ */
+import { Plugin, type PluginDependencies } from 'ckeditor5/src/core';
+import '../theme/todolist.css';
+/**
+ * The to-do list feature.
+ *
+ * This is a "glue" plugin that loads the {@link module:list/todolist/todolistediting~TodoListEditing to-do list editing feature}
+ * and the {@link module:list/todolist/todolistui~TodoListUI to-do list UI feature}.
+ */
+export default class TodoList extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): PluginDependencies;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'TodoList';
+}
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [TodoList.pluginName]: TodoList;
+    }
+}