@ckeditor/ckeditor5-list 0.0.0-internal-20241017.0

package/src/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
+ */
+/**
+ * @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";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * 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/src/listproperties/listpropertiesutils.js

@@ -0,0 +1,50 @@
+/**
+ * @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';
+import { getAllSupportedStyleTypes, getListStyleTypeFromTypeAttribute, getListTypeFromListStyleType, getTypeAttributeFromListStyleType } from './utils/style.js';
+/**
+ * A set of helpers related to document lists.
+ */
+export default class ListPropertiesUtils extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'ListPropertiesUtils';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * Gets all the style types supported by given list type.
+     */
+    getAllSupportedStyleTypes() {
+        return getAllSupportedStyleTypes();
+    }
+    /**
+     * Checks whether the given list-style-type is supported by numbered or bulleted list.
+     */
+    getListTypeFromListStyleType(listStyleType) {
+        return getListTypeFromListStyleType(listStyleType);
+    }
+    /**
+     * Converts `type` attribute of `<ul>` or `<ol>` elements to `list-style-type` equivalent.
+     */
+    getListStyleTypeFromTypeAttribute(value) {
+        return getListStyleTypeFromTypeAttribute(value);
+    }
+    /**
+     * Converts `list-style-type` style to `type` attribute of `<ul>` or `<ol>` elements.
+     */
+    getTypeAttributeFromListStyleType(value) {
+        return getTypeAttributeFromListStyleType(value);
+    }
+}

package/src/listproperties/listreversedcommand.d.ts

@@ -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/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/src/listproperties/listreversedcommand.js

@@ -0,0 +1,55 @@
+/**
+ * @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';
+import { first } from 'ckeditor5/src/utils.js';
+import { expandListBlocksToCompleteList, isListItemBlock } from '../list/utils/model.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
+     */
+    refresh() {
+        const value = this._getValue();
+        this.value = value;
+        this.isEnabled = value != null;
+    }
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options.reversed Whether the list should be reversed.
+     */
+    execute(options = {}) {
+        const model = this.editor.model;
+        const document = model.document;
+        let blocks = Array.from(document.selection.getSelectedBlocks())
+            .filter(block => isListItemBlock(block) && block.getAttribute('listType') == 'numbered');
+        blocks = expandListBlocksToCompleteList(blocks);
+        model.change(writer => {
+            for (const block of blocks) {
+                writer.setAttribute('listReversed', !!options.reversed, block);
+            }
+        });
+    }
+    /**
+     * Checks the command's {@link #value}.
+     */
+    _getValue() {
+        const model = this.editor.model;
+        const document = model.document;
+        const block = first(document.selection.getSelectedBlocks());
+        if (isListItemBlock(block) && block.getAttribute('listType') == 'numbered') {
+            return block.getAttribute('listReversed');
+        }
+        return null;
+    }
+}

package/src/listproperties/liststartcommand.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/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/src/listproperties/liststartcommand.js

@@ -0,0 +1,60 @@
+/**
+ * @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';
+import { first } from 'ckeditor5/src/utils.js';
+import { expandListBlocksToCompleteList, isListItemBlock, isNumberedListType } from '../list/utils/model.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
+     */
+    refresh() {
+        const value = this._getValue();
+        this.value = value;
+        this.isEnabled = value != null;
+    }
+    /**
+     * Executes the command.
+     *
+     * @fires execute
+     * @param options.startIndex The list start index.
+     */
+    execute({ startIndex = 1 } = {}) {
+        const model = this.editor.model;
+        const document = model.document;
+        let blocks = Array.from(document.selection.getSelectedBlocks())
+            .filter(block => isListItemBlock(block) &&
+            isNumberedListType(block.getAttribute('listType')));
+        blocks = expandListBlocksToCompleteList(blocks);
+        model.change(writer => {
+            for (const block of blocks) {
+                writer.setAttribute('listStart', startIndex >= 0 ? startIndex : 1, block);
+            }
+        });
+    }
+    /**
+     * Checks the command's {@link #value}.
+     *
+     * @returns The current value.
+     */
+    _getValue() {
+        const model = this.editor.model;
+        const document = model.document;
+        const block = first(document.selection.getSelectedBlocks());
+        if (block &&
+            isListItemBlock(block) &&
+            isNumberedListType(block.getAttribute('listType'))) {
+            return block.getAttribute('listStart');
+        }
+        return null;
+    }
+}

package/src/listproperties/liststylecommand.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/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/src/listproperties/liststylecommand.js

@@ -0,0 +1,113 @@
+/**
+ * @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 } from 'ckeditor5/src/core.js';
+import { first } from 'ckeditor5/src/utils.js';
+import { expandListBlocksToCompleteList, isListItemBlock } from '../list/utils/model.js';
+import { getListTypeFromListStyleType } from './utils/style.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 {
+    /**
+     * 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, defaultType, supportedTypes) {
+        super(editor);
+        this.defaultType = defaultType;
+        this._supportedTypes = supportedTypes;
+    }
+    /**
+     * @inheritDoc
+     */
+    refresh() {
+        this.value = this._getValue();
+        this.isEnabled = this._checkEnabled();
+    }
+    /**
+     * 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 = {}) {
+        const model = this.editor.model;
+        const document = model.document;
+        model.change(writer => {
+            this._tryToConvertItemsToList(options);
+            let blocks = Array.from(document.selection.getSelectedBlocks())
+                .filter(block => block.hasAttribute('listType'));
+            if (!blocks.length) {
+                return;
+            }
+            blocks = expandListBlocksToCompleteList(blocks);
+            for (const block of blocks) {
+                writer.setAttribute('listStyle', options.type || this.defaultType, block);
+            }
+        });
+    }
+    /**
+     * Checks if the given style type is supported by this plugin.
+     */
+    isStyleTypeSupported(value) {
+        if (!this._supportedTypes) {
+            return true;
+        }
+        return this._supportedTypes.includes(value);
+    }
+    /**
+     * Checks the command's {@link #value}.
+     *
+     * @returns The current value.
+     */
+    _getValue() {
+        const listItem = first(this.editor.model.document.selection.getSelectedBlocks());
+        if (isListItemBlock(listItem)) {
+            return listItem.getAttribute('listStyle');
+        }
+        return null;
+    }
+    /**
+     * Checks whether the command can be enabled in the current context.
+     *
+     * @returns Whether the command should be enabled.
+     */
+    _checkEnabled() {
+        const editor = this.editor;
+        const numberedList = editor.commands.get('numberedList');
+        const bulletedList = editor.commands.get('bulletedList');
+        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.
+     *
+     * @param options.type The type of the list style. If `null` is specified, the function does nothing.
+    */
+    _tryToConvertItemsToList(options) {
+        if (!options.type) {
+            return;
+        }
+        const listType = getListTypeFromListStyleType(options.type);
+        if (!listType) {
+            return;
+        }
+        const editor = this.editor;
+        const commandName = `${listType}List`;
+        const command = editor.commands.get(commandName);
+        if (!command.value) {
+            editor.execute(commandName);
+        }
+    }
+}

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

@@ -0,0 +1,156 @@
+/**
+ * @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 { NormalizedListPropertiesConfig } from '../utils/config.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: NormalizedListPropertiesConfig;
+        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: [];
+};