@ckeditor/ckeditor5-list 32.0.0 → 34.0.1

package/src/documentlist/utils/view.js

@@ -0,0 +1,148 @@
+/**
+ * @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/documentlist/utils/view
+ */
+
+/**
+ * Checks if view element is a list type (ul or ol).
+ *
+ * @protected
+ * @param {module:engine/view/element~Element} viewElement
+ * @returns {Boolean}
+ */
+export function isListView( viewElement ) {
+	return viewElement.is( 'element', 'ol' ) || viewElement.is( 'element', 'ul' );
+}
+
+/**
+ * Checks if view element is a list item (li).
+ *
+ * @protected
+ * @param {module:engine/view/element~Element} viewElement
+ * @returns {Boolean}
+ */
+export function isListItemView( viewElement ) {
+	return viewElement.is( 'element', 'li' );
+}
+
+/**
+ * Calculates the indent value for a list item. Handles HTML compliant and non-compliant lists.
+ *
+ * Also, fixes non HTML compliant lists indents:
+ *
+ * 		before:                                     fixed list:
+ * 		OL                                          OL
+ * 		|-> LI (parent LIs: 0)                      |-> LI     (indent: 0)
+ * 		    |-> OL                                  |-> OL
+ * 		        |-> OL                                  |
+ * 		        |   |-> OL                              |
+ * 		        |       |-> OL                          |
+ * 		        |           |-> LI (parent LIs: 1)      |-> LI (indent: 1)
+ * 		        |-> LI (parent LIs: 1)                  |-> LI (indent: 1)
+ *
+ * 		before:                                     fixed list:
+ * 		OL                                          OL
+ * 		|-> OL                                      |
+ * 		    |-> OL                                  |
+ * 		         |-> OL                             |
+ * 		             |-> LI (parent LIs: 0)         |-> LI        (indent: 0)
+ *
+ * 		before:                                     fixed list:
+ * 		OL                                          OL
+ * 		|-> LI (parent LIs: 0)                      |-> LI         (indent: 0)
+ * 		|-> OL                                          |-> OL
+ * 		    |-> LI (parent LIs: 0)                          |-> LI (indent: 1)
+ *
+ * @protected
+ * @param {module:engine/view/element~Element} listItem
+ * @returns {Number}
+ */
+export function getIndent( listItem ) {
+	let indent = 0;
+	let parent = listItem.parent;
+
+	while ( parent ) {
+		// Each LI in the tree will result in an increased indent for HTML compliant lists.
+		if ( isListItemView( parent ) ) {
+			indent++;
+		} else {
+			// If however the list is nested in other list we should check previous sibling of any of the list elements...
+			const previousSibling = parent.previousSibling;
+
+			// ...because the we might need increase its indent:
+			//		before:                           fixed list:
+			//		OL                                OL
+			//		|-> LI (parent LIs: 0)            |-> LI         (indent: 0)
+			//		|-> OL                                |-> OL
+			//		    |-> LI (parent LIs: 0)                |-> LI (indent: 1)
+			if ( previousSibling && isListItemView( previousSibling ) ) {
+				indent++;
+			}
+		}
+
+		parent = parent.parent;
+	}
+
+	return indent;
+}
+
+/**
+ * Creates a list attribute element (ol or ul).
+ *
+ * @protected
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer The downcast writer.
+ * @param {Number} indent The list item indent.
+ * @param {'bulleted'|'numbered'} type The list type.
+ * @returns {module:engine/view/attributeelement~AttributeElement}
+ */
+export function createListElement( writer, indent, type, id = getViewElementIdForListType( type, indent ) ) {
+	// Negative priorities so that restricted editing attribute won't wrap lists.
+	return writer.createAttributeElement( getViewElementNameForListType( type ), null, {
+		priority: 2 * indent / 100 - 100,
+		id
+	} );
+}
+
+/**
+ * Creates a list item attribute element (li).
+ *
+ * @protected
+ * @param {module:engine/view/downcastwriter~DowncastWriter} writer The downcast writer.
+ * @param {Number} indent The list item indent.
+ * @param {String} id The list item ID.
+ * @returns {module:engine/view/attributeelement~AttributeElement}
+ */
+export function createListItemElement( writer, indent, id ) {
+	// Negative priorities so that restricted editing attribute won't wrap list items.
+	return writer.createAttributeElement( 'li', null, {
+		priority: ( 2 * indent + 1 ) / 100 - 100,
+		id
+	} );
+}
+
+/**
+ * Returns a view element name for the given list type.
+ *
+ * @protected
+ * @param {'bulleted'|'numbered'} type The list type.
+ * @returns {String}
+ */
+export function getViewElementNameForListType( type ) {
+	return type == 'numbered' ? 'ol' : 'ul';
+}
+
+/**
+ * Returns a view element ID for the given list type and indent.
+ *
+ * @protected
+ * @param {'bulleted'|'numbered'} type The list type.
+ * @param {Number} indent The list indent level.
+ * @returns {String}
+ */
+export function getViewElementIdForListType( type, indent ) {
+	return `list-${ type }-${ indent }`;
+}

package/src/documentlist.js

@@ -0,0 +1,36 @@
+/**
+ * @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/documentlist
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+import DocumentListEditing from './documentlist/documentlistediting';
+import ListUI from './list/listui';
+
+/**
+ * The document list feature.
+ *
+ * This is a "glue" plugin that loads the {@link module:list/documentlist/documentlistediting~DocumentListEditing document list
+ * editing feature} and {@link module:list/list/listui~ListUI list UI feature}.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class DocumentList extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ DocumentListEditing, ListUI ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'DocumentList';
+	}
+}

package/src/documentlistproperties/converters.js

@@ -0,0 +1,57 @@
+/**
+ * @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/documentlistproperties/converters
+ */
+
+/**
+ * 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.
+ *
+ * @protected
+ * @param {module:list/documentlistproperties/documentlistpropertiesediting~AttributeStrategy} strategy
+ * @returns {Function}
+ */
+export function listPropertiesUpcastConverter( strategy ) {
+	return ( evt, data, conversionApi ) => {
+		const { writer, schema, consumable } = conversionApi;
+
+		// If there is no view consumable to consume, set the default attribute value to be able to reconvert nested lists on parent change.
+		// So abort converting if attribute was directly consumed.
+		if ( consumable.test( data.viewItem, strategy.viewConsumables ) === false ) {
+			return;
+		}
+
+		if ( !data.modelRange ) {
+			Object.assign( data, conversionApi.convertChildren( data.viewItem, data.modelCursor ) );
+		}
+
+		let applied = false;
+
+		for ( const item of data.modelRange.getItems( { shallow: true } ) ) {
+			if ( !schema.checkAttribute( item, strategy.attributeName ) ) {
+				continue;
+			}
+
+			if ( !strategy.appliesToListItem( item ) ) {
+				continue;
+			}
+
+			// Set list attributes only on same level items, those nested deeper are already handled by the recursive conversion.
+			if ( item.hasAttribute( strategy.attributeName ) ) {
+				continue;
+			}
+
+			writer.setAttribute( strategy.attributeName, strategy.getAttributeOnUpcast( data.viewItem ), item );
+			applied = true;
+		}
+
+		if ( applied ) {
+			consumable.consume( data.viewItem, strategy.viewConsumables );
+		}
+	};
+}

package/src/documentlistproperties/documentlistpropertiesediting.js

@@ -0,0 +1,338 @@
+/**
+ * @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/documentlistproperties/documentlistpropertiesediting
+ */
+
+import { Plugin } from 'ckeditor5/src/core';
+
+import DocumentListEditing from '../documentlist/documentlistediting';
+import DocumentListStartCommand from './documentliststartcommand';
+import DocumentListStyleCommand from './documentliststylecommand';
+import DocumentListReversedCommand from './documentlistreversedcommand';
+import { listPropertiesUpcastConverter } from './converters';
+import { getListTypeFromListStyleType } from './utils/style';
+
+const DEFAULT_LIST_TYPE = 'default';
+
+/**
+ * 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/listproperties~ListPropertiesConfig}.
+ *
+ * @extends module:core/plugin~Plugin
+ */
+export default class DocumentListPropertiesEditing extends Plugin {
+	/**
+	 * @inheritDoc
+	 */
+	static get requires() {
+		return [ DocumentListEditing ];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	static get pluginName() {
+		return 'DocumentListPropertiesEditing';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	constructor( editor ) {
+		super( editor );
+
+		editor.config.define( 'list', {
+			properties: {
+				styles: true,
+				startIndex: false,
+				reversed: false
+			}
+		} );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	init() {
+		const editor = this.editor;
+		const model = editor.model;
+		const documentListEditing = editor.plugins.get( DocumentListEditing );
+
+		const enabledProperties = editor.config.get( 'list.properties' );
+		const strategies = createAttributeStrategies( enabledProperties );
+
+		for ( const strategy of strategies ) {
+			strategy.addCommand( editor );
+
+			model.schema.extend( '$container', { allowAttributes: strategy.attributeName } );
+			model.schema.extend( '$block', { allowAttributes: strategy.attributeName } );
+			model.schema.extend( '$blockObject', { allowAttributes: strategy.attributeName } );
+
+			// Register downcast strategy.
+			documentListEditing.registerDowncastStrategy( {
+				scope: 'list',
+				attributeName: strategy.attributeName,
+
+				setAttributeOnDowncast( writer, attributeValue, viewElement ) {
+					strategy.setAttributeOnDowncast( writer, attributeValue, viewElement );
+				}
+			} );
+		}
+
+		// Set up conversion.
+		editor.conversion.for( 'upcast' ).add( dispatcher => {
+			for ( const strategy of strategies ) {
+				dispatcher.on( 'element:ol', listPropertiesUpcastConverter( strategy ) );
+				dispatcher.on( 'element:ul', listPropertiesUpcastConverter( strategy ) );
+			}
+		} );
+
+		// Verify if the list view element (ul or ol) requires refreshing.
+		documentListEditing.on( 'checkAttributes:list', ( evt, { viewElement, modelAttributes } ) => {
+			for ( const strategy of strategies ) {
+				if ( strategy.getAttributeOnUpcast( viewElement ) != modelAttributes[ strategy.attributeName ] ) {
+					evt.return = true;
+					evt.stop();
+				}
+			}
+		} );
+
+		// Reset list properties after indenting list items.
+		this.listenTo( editor.commands.get( 'indentList' ), 'afterExecute', ( evt, changedBlocks ) => {
+			model.change( writer => {
+				for ( const node of changedBlocks ) {
+					for ( const strategy of strategies ) {
+						if ( strategy.appliesToListItem( node ) ) {
+							// Just reset the attribute.
+							// If there is a previous indented list that this node should be merged into,
+							// the postfixer will unify all the attributes of both sub-lists.
+							writer.setAttribute( strategy.attributeName, strategy.defaultValue, node );
+						}
+					}
+				}
+			} );
+		} );
+
+		// Add or remove list properties attributes depending on the list type.
+		documentListEditing.on( 'postFixer', ( evt, { listNodes, writer } ) => {
+			for ( const { node } of listNodes ) {
+				for ( const strategy of strategies ) {
+					// Check if attribute is valid.
+					if ( strategy.hasValidAttribute( node ) ) {
+						continue;
+					}
+
+					// Add missing default property attributes...
+					if ( strategy.appliesToListItem( node ) ) {
+						writer.setAttribute( strategy.attributeName, strategy.defaultValue, node );
+					}
+					// ...or remove invalid property attributes.
+					else {
+						writer.removeAttribute( strategy.attributeName, node );
+					}
+
+					evt.return = true;
+				}
+			}
+		} );
+
+		// Make sure that all items in a single list (items at the same level & listType) have the same properties.
+		documentListEditing.on( 'postFixer', ( evt, { listNodes, writer } ) => {
+			const previousNodesByIndent = []; // Last seen nodes of lower indented lists.
+
+			for ( const { node, previous } of listNodes ) {
+				// For the first list block there is nothing to compare with.
+				if ( !previous ) {
+					continue;
+				}
+
+				const nodeIndent = node.getAttribute( 'listIndent' );
+				const previousNodeIndent = previous.getAttribute( 'listIndent' );
+
+				let previousNodeInList = null; // It's like `previous` but has the same indent as current node.
+
+				// Let's find previous node for the same indent.
+				// We're going to need that when we get back to previous indent.
+				if ( nodeIndent > previousNodeIndent ) {
+					previousNodesByIndent[ previousNodeIndent ] = previous;
+				}
+				// Restore the one for given indent.
+				else if ( nodeIndent < previousNodeIndent ) {
+					previousNodeInList = previousNodesByIndent[ nodeIndent ];
+					previousNodesByIndent.length = nodeIndent;
+				}
+				// Same indent.
+				else {
+					previousNodeInList = previous;
+				}
+
+				// This is a first item of a nested list.
+				if ( !previousNodeInList ) {
+					continue;
+				}
+
+				// This is a first block of a list of a different type.
+				if ( previousNodeInList.getAttribute( 'listType' ) != node.getAttribute( 'listType' ) ) {
+					continue;
+				}
+
+				// Copy properties from the previous one.
+				for ( const strategy of strategies ) {
+					const { attributeName } = strategy;
+
+					if ( !strategy.appliesToListItem( node ) ) {
+						continue;
+					}
+
+					const value = previousNodeInList.getAttribute( attributeName );
+
+					if ( node.getAttribute( attributeName ) != value ) {
+						writer.setAttribute( attributeName, value, node );
+						evt.return = true;
+					}
+				}
+			}
+		} );
+	}
+}
+
+/**
+ * Strategy for dealing with `listItem` attributes supported by this plugin.
+ *
+ * @typedef {Object} module:list/documentlistproperties/documentlistpropertiesediting~AttributeStrategy
+ * @protected
+ * @property {String} attributeName The model attribute name.
+ * @property {*} defaultValue The model attribute default value.
+ * @property {Object} viewConsumables The view consumable as expected by
+ * {@link module:engine/conversion/viewconsumable~ViewConsumable#consume `ViewConsumable`}.
+ * @property {Function} addCommand Registers an editor command.
+ * @property {Function} appliesToListItem Verifies whether the strategy is applicable for the specified model element.
+ * @property {Function} hasValidAttribute Verifies whether the model attribute value is valid.
+ * @property {Function} setAttributeOnDowncast Sets the property on the view element.
+ * @property {Function} getAttributeOnUpcast Retrieves the property value from the view element.
+ */
+
+// Creates an array of strategies for dealing with enabled listItem attributes.
+//
+// @param {Object} enabledProperties
+// @param {Boolean} enabledProperties.styles
+// @param {Boolean} enabledProperties.reversed
+// @param {Boolean} enabledProperties.startIndex
+// @returns {Array.<module:list/documentlistproperties/documentlistpropertiesediting~AttributeStrategy>}
+function createAttributeStrategies( enabledProperties ) {
+	const strategies = [];
+
+	if ( enabledProperties.styles ) {
+		strategies.push( {
+			attributeName: 'listStyle',
+			defaultValue: DEFAULT_LIST_TYPE,
+			viewConsumables: { styles: 'list-style-type' },
+
+			addCommand( editor ) {
+				editor.commands.add( 'listStyle', new DocumentListStyleCommand( editor, DEFAULT_LIST_TYPE ) );
+			},
+
+			appliesToListItem() {
+				return true;
+			},
+
+			hasValidAttribute( item ) {
+				if ( !item.hasAttribute( 'listStyle' ) ) {
+					return false;
+				}
+
+				const value = item.getAttribute( 'listStyle' );
+
+				if ( value == DEFAULT_LIST_TYPE ) {
+					return true;
+				}
+
+				return getListTypeFromListStyleType( value ) == item.getAttribute( 'listType' );
+			},
+
+			setAttributeOnDowncast( writer, listStyle, element ) {
+				if ( listStyle && listStyle !== DEFAULT_LIST_TYPE ) {
+					writer.setStyle( 'list-style-type', listStyle, element );
+				} else {
+					writer.removeStyle( 'list-style-type', element );
+				}
+			},
+
+			getAttributeOnUpcast( listParent ) {
+				return listParent.getStyle( 'list-style-type' ) || DEFAULT_LIST_TYPE;
+			}
+		} );
+	}
+
+	if ( enabledProperties.reversed ) {
+		strategies.push( {
+			attributeName: 'listReversed',
+			defaultValue: false,
+			viewConsumables: { attributes: 'reversed' },
+
+			addCommand( editor ) {
+				editor.commands.add( 'listReversed', new DocumentListReversedCommand( editor ) );
+			},
+
+			appliesToListItem( item ) {
+				return item.getAttribute( 'listType' ) == 'numbered';
+			},
+
+			hasValidAttribute( item ) {
+				return this.appliesToListItem( item ) == item.hasAttribute( 'listReversed' );
+			},
+
+			setAttributeOnDowncast( writer, listReversed, element ) {
+				if ( listReversed ) {
+					writer.setAttribute( 'reversed', 'reversed', element );
+				} else {
+					writer.removeAttribute( 'reversed', element );
+				}
+			},
+
+			getAttributeOnUpcast( listParent ) {
+				return listParent.hasAttribute( 'reversed' );
+			}
+		} );
+	}
+
+	if ( enabledProperties.startIndex ) {
+		strategies.push( {
+			attributeName: 'listStart',
+			defaultValue: 1,
+			viewConsumables: { attributes: 'start' },
+
+			addCommand( editor ) {
+				editor.commands.add( 'listStart', new DocumentListStartCommand( editor ) );
+			},
+
+			appliesToListItem( item ) {
+				return item.getAttribute( 'listType' ) == 'numbered';
+			},
+
+			hasValidAttribute( item ) {
+				return this.appliesToListItem( item ) == item.hasAttribute( 'listStart' );
+			},
+
+			setAttributeOnDowncast( writer, listStart, element ) {
+				if ( listStart && listStart > 1 ) {
+					writer.setAttribute( 'start', listStart, element );
+				} else {
+					writer.removeAttribute( 'start', element );
+				}
+			},
+
+			getAttributeOnUpcast( listParent ) {
+				return listParent.getAttribute( 'start' ) || 1;
+			}
+		} );
+	}
+
+	return strategies;
+}

package/src/documentlistproperties/documentlistreversedcommand.js

@@ -0,0 +1,76 @@
+/**
+ * @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/documentlistproperties/documentlistreversedcommand
+ */
+
+import { Command } from 'ckeditor5/src/core';
+import { first } from 'ckeditor5/src/utils';
+import {
+	expandListBlocksToCompleteList,
+	isListItemBlock
+} from '../documentlist/utils/model';
+
+/**
+ * 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/documentlistproperties~DocumentListProperties list properties feature}.
+ *
+ * @extends module:core/command~Command
+ */
+export default class DocumentListReversedCommand extends Command {
+	/**
+	 * @inheritDoc
+	 */
+	refresh() {
+		const value = this._getValue();
+
+		this.value = value;
+		this.isEnabled = value != null;
+	}
+
+	/**
+	 * Executes the command.
+	 *
+	 * @fires execute
+	 * @param {Object} [options]
+	 * @param {Boolean} [options.reversed=false] 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}.
+	 *
+	 * @private
+	 * @returns {Boolean|null} The current 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;
+	}
+}