@ckeditor/ckeditor5-list 29.2.0 → 32.0.0

package/src/listpropertiesui.js

@@ -0,0 +1,314 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module list/listpropertiesui
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import { ButtonView, SplitButtonView, createDropdown } from 'ckeditor5/src/ui';
+
+import ListPropertiesView from './ui/listpropertiesview';
+
+import bulletedListIcon from '../theme/icons/bulletedlist.svg';
+import numberedListIcon from '../theme/icons/numberedlist.svg';
+
+import listStyleDiscIcon from '../theme/icons/liststyledisc.svg';
+import listStyleCircleIcon from '../theme/icons/liststylecircle.svg';
+import listStyleSquareIcon from '../theme/icons/liststylesquare.svg';
+import listStyleDecimalIcon from '../theme/icons/liststyledecimal.svg';
+import listStyleDecimalWithLeadingZeroIcon from '../theme/icons/liststyledecimalleadingzero.svg';
+import listStyleLowerRomanIcon from '../theme/icons/liststylelowerroman.svg';
+import listStyleUpperRomanIcon from '../theme/icons/liststyleupperroman.svg';
+import listStyleLowerLatinIcon from '../theme/icons/liststylelowerlatin.svg';
+import listStyleUpperLatinIcon from '../theme/icons/liststyleupperlatin.svg';
+
+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/listui~ListUI}
+ * (because they share the same names).
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class ListPropertiesUI extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'ListPropertiesUI';
+	}
+
+	init() {
+		const editor = this.editor;
+		const t = editor.locale.t;
+		const enabledProperties = editor.config.get( 'list.properties' );
+
+		// Note: When this plugin does not register the "bulletedList" dropdown due to properties configuration,
+		// a simple button will be still registered under the same name by ListUI as a fallback. This should happen
+		// in most editor configuration because the List plugin automatically requires ListUI.
+		if ( enabledProperties.styles ) {
+			editor.ui.componentFactory.add( 'bulletedList', getDropdownViewCreator( {
+				editor,
+				parentCommandName: 'bulletedList',
+				buttonLabel: t( 'Bulleted List' ),
+				buttonIcon: bulletedListIcon,
+				styleGridAriaLabel: t( 'Bulleted list styles toolbar' ),
+				styleDefinitions: [
+					{
+						label: t( 'Toggle the disc list style' ),
+						tooltip: t( 'Disc' ),
+						type: 'disc',
+						icon: listStyleDiscIcon
+					},
+					{
+						label: t( 'Toggle the circle list style' ),
+						tooltip: t( 'Circle' ),
+						type: 'circle',
+						icon: listStyleCircleIcon
+					},
+					{
+						label: t( 'Toggle the square list style' ),
+						tooltip: t( 'Square' ),
+						type: 'square',
+						icon: listStyleSquareIcon
+					}
+				]
+			} ) );
+		}
+
+		// Note: When this plugin does not register the "numberedList" dropdown due to properties configuration,
+		// a simple button will be still registered under the same name by ListUI as a fallback. This should happen
+		// in most editor configuration because the List plugin automatically requires ListUI.
+		if ( enabledProperties.styles || enabledProperties.startIndex || enabledProperties.reversed ) {
+			editor.ui.componentFactory.add( 'numberedList', getDropdownViewCreator( {
+				editor,
+				parentCommandName: 'numberedList',
+				buttonLabel: t( 'Numbered List' ),
+				buttonIcon: numberedListIcon,
+				styleGridAriaLabel: t( 'Numbered list styles toolbar' ),
+				styleDefinitions: [
+					{
+						label: t( 'Toggle the decimal list style' ),
+						tooltip: t( 'Decimal' ),
+						type: 'decimal',
+						icon: listStyleDecimalIcon
+					},
+					{
+						label: t( 'Toggle the decimal with leading zero list style' ),
+						tooltip: t( 'Decimal with leading zero' ),
+						type: 'decimal-leading-zero',
+						icon: listStyleDecimalWithLeadingZeroIcon
+					},
+					{
+						label: t( 'Toggle the lower–roman list style' ),
+						tooltip: t( 'Lower–roman' ),
+						type: 'lower-roman',
+						icon: listStyleLowerRomanIcon
+					},
+					{
+						label: t( 'Toggle the upper–roman list style' ),
+						tooltip: t( 'Upper-roman' ),
+						type: 'upper-roman',
+						icon: listStyleUpperRomanIcon
+					},
+					{
+						label: t( 'Toggle the lower–latin list style' ),
+						tooltip: t( 'Lower-latin' ),
+						type: 'lower-latin',
+						icon: listStyleLowerLatinIcon
+					},
+					{
+						label: t( 'Toggle the upper–latin list style' ),
+						tooltip: t( 'Upper-latin' ),
+						type: 'upper-latin',
+						icon: listStyleUpperLatinIcon
+					}
+				]
+			} ) );
+		}
+	}
+}
+
+// A helper that returns a function that creates a split button with a toolbar in the dropdown,
+// which in turn contains buttons allowing users to change list styles in the context of the current selection.
+//
+// @param {Object} options
+// @param {module:core/editor/editor~Editor} options.editor
+// @param {'bulletedList'|'numberedList'} options.parentCommandName The name of the higher-order editor command associated with
+// the set of particular list styles (e.g. "bulletedList" for "disc", "circle", and "square" styles).
+// @param {String} options.buttonLabel Label of the main part of the split button.
+// @param {String} options.buttonIcon The SVG string of an icon for the main part of the split button.
+// @param {String} options.styleGridAriaLabel The ARIA label for the styles grid in the split button dropdown.
+// @param {Object} options.styleDefinitions Definitions of the style buttons.
+// @returns {Function} A function that can be passed straight into {@link module:ui/componentfactory~ComponentFactory#add}.
+function getDropdownViewCreator( { editor, parentCommandName, buttonLabel, buttonIcon, styleGridAriaLabel, styleDefinitions } ) {
+	const parentCommand = editor.commands.get( parentCommandName );
+
+	// @param {module:utils/locale~Locale} locale
+	// @returns {module:ui/dropdown/dropdownview~DropdownView}
+	return locale => {
+		const dropdownView = createDropdown( locale, SplitButtonView );
+		const mainButtonView = dropdownView.buttonView;
+
+		dropdownView.bind( 'isEnabled' ).to( parentCommand );
+		dropdownView.class = 'ck-list-styles-dropdown';
+
+		// Main button was clicked.
+		mainButtonView.on( 'execute', () => {
+			editor.execute( parentCommandName );
+			editor.editing.view.focus();
+		} );
+
+		mainButtonView.set( {
+			label: buttonLabel,
+			icon: buttonIcon,
+			tooltip: true,
+			isToggleable: true
+		} );
+
+		mainButtonView.bind( 'isOn' ).to( parentCommand, 'value', value => !!value );
+
+		const listPropertiesView = createListPropertiesView( {
+			editor,
+			dropdownView,
+			parentCommandName,
+			styleGridAriaLabel,
+			styleDefinitions
+		} );
+
+		dropdownView.panelView.children.add( listPropertiesView );
+
+		return dropdownView;
+	};
+}
+
+// A helper that returns a function (factory) that creates individual buttons used by users to change styles
+// of lists.
+//
+// @param {Object} options
+// @param {module:core/editor/editor~Editor} options.editor
+// @param {module:list/liststylecommand~ListStylesCommand} options.listStyleCommand The instance of the `ListStylesCommand` class.
+// @param {'bulletedList'|'numberedList'} options.parentCommandName The name of the higher-order command associated with a
+// particular list style (e.g. "bulletedList" is associated with "square" and "numberedList" is associated with "roman").
+// @returns {Function} A function that can be passed straight into {@link module:ui/componentfactory~ComponentFactory#add}.
+function getStyleButtonCreator( { editor, listStyleCommand, parentCommandName } ) {
+	const locale = editor.locale;
+	const parentCommand = editor.commands.get( parentCommandName );
+
+	// @param {String} label The label of the style button.
+	// @param {String} type The type of the style button (e.g. "roman" or "circle").
+	// @param {String} icon The SVG string of an icon of the style button.
+	// @param {String} tooltip The tooltip text of the button (shorter than verbose label).
+	// @returns {module:ui/button/buttonview~ButtonView}
+	return ( { label, type, icon, tooltip } ) => {
+		const button = new ButtonView( locale );
+
+		button.set( { label, icon, tooltip } );
+
+		listStyleCommand.on( 'change:value', () => {
+			button.isOn = listStyleCommand.value === type;
+		} );
+
+		button.on( 'execute', () => {
+			// If the content the selection is anchored to is a list, let's change its style.
+			if ( parentCommand.value ) {
+				// If the current list style is not set in the model or the style is different than the
+				// one to be applied, simply apply the new style.
+				if ( listStyleCommand.value !== type ) {
+					editor.execute( 'listStyle', { type } );
+				}
+				// If the style was the same, remove it (the button works as an off toggle).
+				else {
+					editor.execute( 'listStyle', { type: listStyleCommand._defaultType } );
+				}
+			}
+			// If the content the selection is anchored to is not a list, let's create a list of a desired style.
+			else {
+				editor.model.change( () => {
+					editor.execute( parentCommandName );
+					editor.execute( 'listStyle', { type } );
+				} );
+			}
+
+			editor.editing.view.focus();
+		} );
+
+		return button;
+	};
+}
+
+// A helper that creates the properties view for the individual style dropdown.
+//
+// @param {Object} options
+// @param {module:core/editor/editor~Editor} options.editor Editor instance.
+// @param {module:ui/dropdown/dropdownview~DropdownView} options.dropdownView Styles dropdown view that hosts the properties view.
+// @param {'bulletedList'|'numberedList'} options.parentCommandName The name of the higher-order editor command associated with
+// the set of particular list styles (e.g. "bulletedList" for "disc", "circle", and "square" styles).
+// @param {Object} options.styleDefinitions Definitions of the style buttons.
+// @param {String} options.styleGridAriaLabel An assistive technologies label set on the grid of styles (if the grid is rendered).
+// @returns {module:list/ui/listpropertiesview~ListPropertiesView}
+function createListPropertiesView( {
+	editor,
+	dropdownView,
+	parentCommandName,
+	styleDefinitions,
+	styleGridAriaLabel
+} ) {
+	const locale = editor.locale;
+	const enabledProperties = editor.config.get( 'list.properties' );
+	let styleButtonViews;
+
+	if ( parentCommandName != 'numberedList' ) {
+		enabledProperties.startIndex = false;
+		enabledProperties.reversed = false;
+	}
+
+	if ( enabledProperties.styles ) {
+		const listStyleCommand = editor.commands.get( 'listStyle' );
+
+		const styleButtonCreator = getStyleButtonCreator( {
+			editor,
+			parentCommandName,
+			listStyleCommand
+		} );
+
+		styleButtonViews = styleDefinitions.map( styleButtonCreator );
+	}
+
+	const listPropertiesView = new ListPropertiesView( locale, {
+		styleGridAriaLabel,
+		enabledProperties,
+		styleButtonViews
+	} );
+
+	if ( enabledProperties.startIndex ) {
+		const listStartCommand = editor.commands.get( 'listStart' );
+
+		listPropertiesView.startIndexFieldView.bind( 'isEnabled' ).to( listStartCommand );
+		listPropertiesView.startIndexFieldView.fieldView.bind( 'value' ).to( listStartCommand );
+		listPropertiesView.on( 'listStart', ( evt, data ) => editor.execute( 'listStart', data ) );
+	}
+
+	if ( enabledProperties.reversed ) {
+		const listReversedCommand = editor.commands.get( 'listReversed' );
+
+		listPropertiesView.reversedSwitchButtonView.bind( 'isEnabled' ).to( listReversedCommand );
+		listPropertiesView.reversedSwitchButtonView.bind( 'isOn' ).to( listReversedCommand, 'value' );
+		listPropertiesView.on( 'listReversed', () => {
+			const isReversed = listReversedCommand.value;
+
+			editor.execute( 'listReversed', { reversed: !isReversed } );
+		} );
+	}
+
+	// Make sure applying styles closes the dropdown.
+	listPropertiesView.delegate( 'execute' ).to( dropdownView );
+
+	return listPropertiesView;
+}

package/src/listreversedcommand.js

@@ -0,0 +1,64 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module list/listreversedcommand
+ */
+
+import { Command } from 'ckeditor5/src/core';
+import { getSelectedListItems } from './utils';
+
+/**
+ * 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/listproperties~ListProperties list properties feature}.
+ *
+ * @extends module:core/command~Command
+ */
+export default class ListReversedCommand extends Command {
+	/**
+	 * @inheritDoc
+	 */
+	refresh() {
+		const value = this._getValue();
+		this.value = value;
+		this.isEnabled = value != null;
+	}
+
+	/**
+	 * Executes the command.
+	 *
+	 * @param {Object} options
+	 * @param {Boolean} [options.reversed=false] Whether the list should be reversed.
+	 * @protected
+	 */
+	execute( options = {} ) {
+		const model = this.editor.model;
+		const listItems = getSelectedListItems( model )
+			.filter( item => item.getAttribute( 'listType' ) == 'numbered' );
+
+		model.change( writer => {
+			for ( const item of listItems ) {
+				writer.setAttribute( 'listReversed', !!options.reversed, item );
+			}
+		} );
+	}
+
+	/**
+	 * Checks the command's {@link #value}.
+	 *
+	 * @private
+	 * @returns {Boolean|null} The current value.
+	 */
+	_getValue() {
+		const listItem = this.editor.model.document.selection.getFirstPosition().parent;
+
+		if ( listItem && listItem.is( 'element', 'listItem' ) && listItem.getAttribute( 'listType' ) == 'numbered' ) {
+			return listItem.getAttribute( 'listReversed' );
+		}
+
+		return null;
+	}
+}

package/src/liststartcommand.js

@@ -0,0 +1,63 @@
+/**
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module list/liststartcommand
+ */
+
+import { Command } from 'ckeditor5/src/core';
+import { getSelectedListItems } from './utils';
+
+/**
+ * The list start index command. It changes the `listStart` attribute of the selected list items.
+ * It is used by the {@link module:list/listproperties~ListProperties list properties feature}.
+ *
+ * @extends module:core/command~Command
+ */
+export default class ListStartCommand extends Command {
+	/**
+	 * @inheritDoc
+	 */
+	refresh() {
+		const value = this._getValue();
+		this.value = value;
+		this.isEnabled = value != null;
+	}
+
+	/**
+	 * Executes the command.
+	 *
+	 * @param {Object} options
+	 * @param {Number} [options.startIndex=1] The list start index.
+	 * @protected
+	 */
+	execute( options = {} ) {
+		const model = this.editor.model;
+		const listItems = getSelectedListItems( model )
+			.filter( item => item.getAttribute( 'listType' ) == 'numbered' );
+
+		model.change( writer => {
+			for ( const item of listItems ) {
+				writer.setAttribute( 'listStart', options.startIndex || 1, item );
+			}
+		} );
+	}
+
+	/**
+	 * Checks the command's {@link #value}.
+	 *
+	 * @private
+	 * @returns {Boolean|null} The current value.
+	 */
+	_getValue() {
+		const listItem = this.editor.model.document.selection.getFirstPosition().parent;
+
+		if ( listItem && listItem.is( 'element', 'listItem' ) && listItem.getAttribute( 'listType' ) == 'numbered' ) {
+			return listItem.getAttribute( 'listStart' );
+		}
+
+		return null;
+	}
+}

package/src/liststyle.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
@@ -8,14 +8,14 @@
  */
 
 import { Plugin } from 'ckeditor5/src/core';
-import ListStyleEditing from './liststyleediting';
-import ListStyleUI from './liststyleui';
+import ListProperties from './listproperties';
+import { logWarning } from 'ckeditor5/src/utils';
 
 /**
  * The list style feature.
  *
- * This is a "glue" plugin that loads the {@link module:list/liststyleediting~ListStyleEditing list style editing feature}
- * and the {@link module:list/liststyleui~ListStyleUI list style UI feature}.
+ * This is an obsolete plugin that exists for backward compatibility only.
+ * Use the {@link module:list/listproperties~ListProperties list properties plugin} instead.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -24,7 +24,7 @@ export default class ListStyle extends Plugin {
 	 * @inheritDoc
 	 */
 	static get requires() {
-		return [ ListStyleEditing, ListStyleUI ];
+		return [ ListProperties ];
 	}
 
 	/**
@@ -33,4 +33,10 @@ export default class ListStyle extends Plugin {
 	static get pluginName() {
 		return 'ListStyle';
 	}
+
+	constructor( editor ) {
+		super( editor );
+
+		logWarning( 'The `ListStyle` plugin is obsolete. Use `ListProperties` instead.' );
+	}
 }

package/src/liststylecommand.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
@@ -8,10 +8,11 @@
  */
 
 import { Command } from 'ckeditor5/src/core';
-import { getSiblingNodes } from './utils';
+import { getSelectedListItems } from './utils';
 
 /**
- * The list style command. It is used by the {@link module:list/liststyle~ListStyle list style feature}.
+ * The list style command. It changes the `listStyle` attribute of the selected list items.
+ * It is used by the {@link module:list/listproperties~ListProperties list properties feature}.
  *
  * @extends module:core/command~Command
  */
@@ -53,25 +54,7 @@ export default class ListStyleCommand extends Command {
 	 */
 	execute( options = {} ) {
 		const model = this.editor.model;
-		const document = model.document;
-
-		// For all selected blocks find all list items that are being selected
-		// and update the `listStyle` attribute in those lists.
-		let listItems = [ ...document.selection.getSelectedBlocks() ]
-			.filter( element => element.is( 'element', 'listItem' ) )
-			.map( element => {
-				const position = model.change( writer => writer.createPositionAt( element, 0 ) );
-
-				return [
-					...getSiblingNodes( position, 'backward' ),
-					...getSiblingNodes( position, 'forward' )
-				];
-			} )
-			.flat();
-
-		// Since `getSelectedBlocks()` can return items that belong to the same list, and
-		// `getSiblingNodes()` returns the entire list, we need to remove duplicated items.
-		listItems = [ ...new Set( listItems ) ];
+		const listItems = getSelectedListItems( model );
 
 		if ( !listItems.length ) {
 			return;

package/src/listui.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 

package/src/todolist.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 

package/src/todolistconverters.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 

package/src/todolistediting.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 

package/src/todolistui.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */