@ckeditor/ckeditor5-list 41.3.1 → 41.4.0

package/dist/types/listconfig.d.ts

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

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

@@ -0,0 +1,23 @@
+/**
+ * @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
+ */
+/**
+ * @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/dist/types/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
+ */
+/**
+ * @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
+     */
+    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;
+    }
+}

package/dist/types/listproperties/listpropertiesui.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
+ */
+/**
+ * @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/listpropertiesui
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import '../../theme/liststyles.css';
+/**
+ * The list properties UI plugin. It introduces the extended `'bulletedList'` and `'numberedList'` toolbar
+ * buttons that allow users to control such aspects of list as the marker, start index or order.
+ *
+ * **Note**: Buttons introduced by this plugin override implementations from the {@link module:list/list/listui~ListUI}
+ * (because they share the same names).
+ */
+export default class ListPropertiesUI extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ListPropertiesUI";
+    init(): void;
+}

package/dist/types/listproperties/listpropertiesutils.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
+ */
+/**
+ * @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/listpropertiesutils
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * A set of helpers related to document lists.
+ */
+export default class ListPropertiesUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "ListPropertiesUtils";
+    /**
+     * 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;
+}

package/dist/types/listproperties/listreversedcommand.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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
+ */
+/**
+ * @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/listreversedcommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The list reversed command. It changes the `listReversed` attribute of the selected list items,
+ * letting the user to choose the order of an ordered list.
+ * It is used by the {@link module:list/listproperties~ListProperties list properties feature}.
+ */
+export default class ListReversedCommand 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}.
+     */
+    private _getValue;
+}

package/dist/types/listproperties/liststartcommand.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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
+ */
+/**
+ * @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/liststartcommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * The list start index command. It changes the `listStart` attribute of the selected list items,
+ * letting the user to choose the starting point of an ordered list.
+ * It is used by the {@link module:list/listproperties~ListProperties list properties feature}.
+ */
+export default class ListStartCommand 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/listproperties/liststylecommand.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @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
+ */
+/**
+ * @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/liststylecommand
+ */
+import { Command, type Editor } from 'ckeditor5/src/core.js';
+/**
+ * The list style command. It changes `listStyle` attribute of the selected list items,
+ * letting the user choose styles for the list item markers.
+ * It is used by the {@link module:list/listproperties~ListProperties list properties feature}.
+ */
+export default class ListStyleCommand extends Command {
+    /**
+     * @inheritDoc
+     */
+    value: string | null;
+    /**
+     * The default type of the list style.
+     */
+    readonly defaultType: string;
+    /**
+     * The list of supported style types by this command.
+     */
+    private _supportedTypes;
+    /**
+     * 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.
+     * @param supportedTypes The list of supported style types by this command.
+     */
+    constructor(editor: Editor, defaultType: string, supportedTypes?: Array<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 if the given style type is supported by this plugin.
+     */
+    isStyleTypeSupported(value: string): boolean;
+    /**
+     * 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;
+    /**
+     * Check if the provided list style is valid. Also change the selection to a list if it's not set yet.
+     *
+     * @param options.type The type of the list style. If `null` is specified, the function does nothing.
+    */
+    private _tryToConvertItemsToList;
+}

package/dist/types/listproperties/ui/listpropertiesview.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
+ */
+/**
+ * @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/ui/listpropertiesview
+ */
+import { View, ViewCollection, FocusCycler, SwitchButtonView, LabeledFieldView, CollapsibleView, type ButtonView, type InputNumberView, type FocusableView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import type { ListPropertiesConfig } from '../../listconfig.js';
+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<FocusableView>;
+    /**
+     * 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 ~ListPropertiesView#startIndexFieldView}.
+ *
+ * @eventName ~ListPropertiesView#listStart
+ */
+export type ListPropertiesViewListStartEvent = {
+    name: 'listStart';
+    args: [data: {
+        startIndex: number;
+    }];
+};
+/**
+ * Fired when the list order has changed (reversed) via {@link ~ListPropertiesView#reversedSwitchButtonView}.
+ *
+ * @eventName ~ListPropertiesView#listReversed
+ */
+export type ListPropertiesViewListReversedEvent = {
+    name: 'listReversed';
+    args: [];
+};

package/dist/types/listproperties/utils/style.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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
+ */
+/**
+ * @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
+ */
+/**
+ * Gets all the style types supported by given list type.
+ */
+export declare function getAllSupportedStyleTypes(): Array<string>;
+/**
+ * Checks whether the given list-style-type is supported by numbered or bulleted list.
+ */
+export declare function getListTypeFromListStyleType(listStyleType: string): 'bulleted' | 'numbered' | null;
+/**
+ * Converts `type` attribute of `<ul>` or `<ol>` elements to `list-style-type` equivalent.
+ */
+export declare function getListStyleTypeFromTypeAttribute(value: string): string | null;
+/**
+ * Converts `list-style-type` style to `type` attribute of `<ul>` or `<ol>` elements.
+ */
+export declare function getTypeAttributeFromListStyleType(value: string): string | null;