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

package/src/converters/tableproperties.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @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 table/converters/tableproperites
+ */
+import type { Conversion, ViewElement } from 'ckeditor5/src/engine';
+/**
+ * Conversion helper for upcasting attributes using normalized styles.
+ *
+ * @param options.modelAttribute The attribute to set.
+ * @param options.styleName The style name to convert.
+ * @param options.viewElement The view element name that should be converted.
+ * @param options.defaultValue The default value for the specified `modelAttribute`.
+ * @param options.shouldUpcast The function which returns `true` if style should be upcasted from this element.
+ */
+export declare function upcastStyleToAttribute(conversion: Conversion, options: {
+    modelAttribute: string;
+    styleName: string;
+    viewElement: string | RegExp;
+    defaultValue: string;
+    reduceBoxSides?: boolean;
+    shouldUpcast?: (viewElement: ViewElement) => boolean;
+}): void;
+export interface StyleValues {
+    color: string;
+    style: string;
+    width: string;
+}
+/**
+ * Conversion helper for upcasting border styles for view elements.
+ *
+ * @param defaultBorder The default border values.
+ * @param defaultBorder.color The default `borderColor` value.
+ * @param defaultBorder.style The default `borderStyle` value.
+ * @param defaultBorder.width The default `borderWidth` value.
+ */
+export declare function upcastBorderStyles(conversion: Conversion, viewElementName: string, modelAttributes: StyleValues, defaultBorder: StyleValues): void;
+/**
+ * Conversion helper for downcasting an attribute to a style.
+ */
+export declare function downcastAttributeToStyle(conversion: Conversion, options: {
+    modelElement: string;
+    modelAttribute: string;
+    styleName: string;
+}): void;
+/**
+ * Conversion helper for downcasting attributes from the model table to a view table (not to `<figure>`).
+ */
+export declare function downcastTableAttribute(conversion: Conversion, options: {
+    modelAttribute: string;
+    styleName: string;
+}): void;

package/src/converters/tableproperties.js

@@ -2,190 +2,158 @@
  * @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 table/converters/tableproperites
- */
-
 /**
  * Conversion helper for upcasting attributes using normalized styles.
  *
- * @param {module:engine/conversion/conversion~Conversion} conversion
- * @param {Object} options
- * @param {String} options.modelAttribute The attribute to set.
- * @param {String} options.styleName The style name to convert.
- * @param {String} options.viewElement The view element name that should be converted.
- * @param {String} options.defaultValue The default value for the specified `modelAttribute`.
- * @param {Boolean} [options.reduceBoxSides=false]
- * @param {Function} [options.shouldUpcast] The function which returns `true` if style should be upcasted from this element.
+ * @param options.modelAttribute The attribute to set.
+ * @param options.styleName The style name to convert.
+ * @param options.viewElement The view element name that should be converted.
+ * @param options.defaultValue The default value for the specified `modelAttribute`.
+ * @param options.shouldUpcast The function which returns `true` if style should be upcasted from this element.
  */
-export function upcastStyleToAttribute( conversion, options ) {
-	const { viewElement, defaultValue, modelAttribute, styleName, reduceBoxSides = false, shouldUpcast = () => true } = options;
-
-	conversion.for( 'upcast' ).attributeToAttribute( {
-		view: {
-			name: viewElement,
-			styles: {
-				[ styleName ]: /[\s\S]+/
-			}
-		},
-		model: {
-			key: modelAttribute,
-			value: viewElement => {
-				if ( !shouldUpcast( viewElement ) ) {
-					return;
-				}
-
-				const normalized = viewElement.getNormalizedStyle( styleName );
-				const value = reduceBoxSides ? reduceBoxSidesValue( normalized ) : normalized;
-
-				if ( defaultValue !== value ) {
-					return value;
-				}
-			}
-		}
-	} );
+export function upcastStyleToAttribute(conversion, options) {
+    const { modelAttribute, styleName, viewElement, defaultValue, reduceBoxSides = false, shouldUpcast = () => true } = options;
+    conversion.for('upcast').attributeToAttribute({
+        view: {
+            name: viewElement,
+            styles: {
+                [styleName]: /[\s\S]+/
+            }
+        },
+        model: {
+            key: modelAttribute,
+            value: (viewElement) => {
+                if (!shouldUpcast(viewElement)) {
+                    return;
+                }
+                const normalized = viewElement.getNormalizedStyle(styleName);
+                const value = reduceBoxSides ? reduceBoxSidesValue(normalized) : normalized;
+                if (defaultValue !== value) {
+                    return value;
+                }
+            }
+        }
+    });
 }
-
 /**
  * Conversion helper for upcasting border styles for view elements.
  *
- * @param {module:engine/conversion/conversion~Conversion} conversion
- * @param {String} viewElementName
- * @param {Object} modelAttributes
- * @param {Object} defaultBorder The default border values.
- * @param {String} defaultBorder.color The default `borderColor` value.
- * @param {String} defaultBorder.style The default `borderStyle` value.
- * @param {String} defaultBorder.width The default `borderWidth` value.
+ * @param defaultBorder The default border values.
+ * @param defaultBorder.color The default `borderColor` value.
+ * @param defaultBorder.style The default `borderStyle` value.
+ * @param defaultBorder.width The default `borderWidth` value.
  */
-export function upcastBorderStyles( conversion, viewElementName, modelAttributes, defaultBorder ) {
-	conversion.for( 'upcast' ).add( dispatcher => dispatcher.on( 'element:' + viewElementName, ( evt, data, conversionApi ) => {
-		// If the element was not converted by element-to-element converter,
-		// we should not try to convert the style. See #8393.
-		if ( !data.modelRange ) {
-			return;
-		}
-
-		// Check the most detailed properties. These will be always set directly or
-		// when using the "group" properties like: `border-(top|right|bottom|left)` or `border`.
-		const stylesToConsume = [
-			'border-top-width',
-			'border-top-color',
-			'border-top-style',
-			'border-bottom-width',
-			'border-bottom-color',
-			'border-bottom-style',
-			'border-right-width',
-			'border-right-color',
-			'border-right-style',
-			'border-left-width',
-			'border-left-color',
-			'border-left-style'
-		].filter( styleName => data.viewItem.hasStyle( styleName ) );
-
-		if ( !stylesToConsume.length ) {
-			return;
-		}
-
-		const matcherPattern = {
-			styles: stylesToConsume
-		};
-
-		// Try to consume appropriate values from consumable values list.
-		if ( !conversionApi.consumable.test( data.viewItem, matcherPattern ) ) {
-			return;
-		}
-
-		const modelElement = [ ...data.modelRange.getItems( { shallow: true } ) ].pop();
-
-		conversionApi.consumable.consume( data.viewItem, matcherPattern );
-
-		const normalizedBorder = {
-			style: data.viewItem.getNormalizedStyle( 'border-style' ),
-			color: data.viewItem.getNormalizedStyle( 'border-color' ),
-			width: data.viewItem.getNormalizedStyle( 'border-width' )
-		};
-
-		const reducedBorder = {
-			style: reduceBoxSidesValue( normalizedBorder.style ),
-			color: reduceBoxSidesValue( normalizedBorder.color ),
-			width: reduceBoxSidesValue( normalizedBorder.width )
-		};
-
-		if ( reducedBorder.style !== defaultBorder.style ) {
-			conversionApi.writer.setAttribute( modelAttributes.style, reducedBorder.style, modelElement );
-		}
-
-		if ( reducedBorder.color !== defaultBorder.color ) {
-			conversionApi.writer.setAttribute( modelAttributes.color, reducedBorder.color, modelElement );
-		}
-
-		if ( reducedBorder.width !== defaultBorder.width ) {
-			conversionApi.writer.setAttribute( modelAttributes.width, reducedBorder.width, modelElement );
-		}
-	} ) );
+export function upcastBorderStyles(conversion, viewElementName, modelAttributes, defaultBorder) {
+    conversion.for('upcast').add(dispatcher => dispatcher.on('element:' + viewElementName, (evt, data, conversionApi) => {
+        // If the element was not converted by element-to-element converter,
+        // we should not try to convert the style. See #8393.
+        if (!data.modelRange) {
+            return;
+        }
+        // Check the most detailed properties. These will be always set directly or
+        // when using the "group" properties like: `border-(top|right|bottom|left)` or `border`.
+        const stylesToConsume = [
+            'border-top-width',
+            'border-top-color',
+            'border-top-style',
+            'border-bottom-width',
+            'border-bottom-color',
+            'border-bottom-style',
+            'border-right-width',
+            'border-right-color',
+            'border-right-style',
+            'border-left-width',
+            'border-left-color',
+            'border-left-style'
+        ].filter(styleName => data.viewItem.hasStyle(styleName));
+        if (!stylesToConsume.length) {
+            return;
+        }
+        const matcherPattern = {
+            styles: stylesToConsume
+        };
+        // Try to consume appropriate values from consumable values list.
+        if (!conversionApi.consumable.test(data.viewItem, matcherPattern)) {
+            return;
+        }
+        const modelElement = [...data.modelRange.getItems({ shallow: true })].pop();
+        conversionApi.consumable.consume(data.viewItem, matcherPattern);
+        const normalizedBorder = {
+            style: data.viewItem.getNormalizedStyle('border-style'),
+            color: data.viewItem.getNormalizedStyle('border-color'),
+            width: data.viewItem.getNormalizedStyle('border-width')
+        };
+        const reducedBorder = {
+            style: reduceBoxSidesValue(normalizedBorder.style),
+            color: reduceBoxSidesValue(normalizedBorder.color),
+            width: reduceBoxSidesValue(normalizedBorder.width)
+        };
+        if (reducedBorder.style !== defaultBorder.style) {
+            conversionApi.writer.setAttribute(modelAttributes.style, reducedBorder.style, modelElement);
+        }
+        if (reducedBorder.color !== defaultBorder.color) {
+            conversionApi.writer.setAttribute(modelAttributes.color, reducedBorder.color, modelElement);
+        }
+        if (reducedBorder.width !== defaultBorder.width) {
+            conversionApi.writer.setAttribute(modelAttributes.width, reducedBorder.width, modelElement);
+        }
+    }));
 }
-
 /**
  * Conversion helper for downcasting an attribute to a style.
- *
- * @param {module:engine/conversion/conversion~Conversion} conversion
- * @param {Object} options
- * @param {String} options.modelElement
- * @param {String} options.modelAttribute
- * @param {String} options.styleName
  */
-export function downcastAttributeToStyle( conversion, { modelElement, modelAttribute, styleName } ) {
-	conversion.for( 'downcast' ).attributeToAttribute( {
-		model: {
-			name: modelElement,
-			key: modelAttribute
-		},
-		view: modelAttributeValue => ( {
-			key: 'style',
-			value: {
-				[ styleName ]: modelAttributeValue
-			}
-		} )
-	} );
+export function downcastAttributeToStyle(conversion, options) {
+    const { modelElement, modelAttribute, styleName } = options;
+    conversion.for('downcast').attributeToAttribute({
+        model: {
+            name: modelElement,
+            key: modelAttribute
+        },
+        view: modelAttributeValue => ({
+            key: 'style',
+            value: {
+                [styleName]: modelAttributeValue
+            }
+        })
+    });
 }
-
 /**
  * Conversion helper for downcasting attributes from the model table to a view table (not to `<figure>`).
- *
- * @param {module:engine/conversion/conversion~Conversion} conversion
- * @param {Object} options
- * @param {String} options.modelAttribute
- * @param {String} options.styleName
  */
-export function downcastTableAttribute( conversion, { modelAttribute, styleName } ) {
-	conversion.for( 'downcast' ).add( dispatcher => dispatcher.on( `attribute:${ modelAttribute }:table`, ( evt, data, conversionApi ) => {
-		const { item, attributeNewValue } = data;
-		const { mapper, writer } = conversionApi;
-
-		if ( !conversionApi.consumable.consume( data.item, evt.name ) ) {
-			return;
-		}
-
-		const table = [ ...mapper.toViewElement( item ).getChildren() ].find( child => child.is( 'element', 'table' ) );
-
-		if ( attributeNewValue ) {
-			writer.setStyle( styleName, attributeNewValue, table );
-		} else {
-			writer.removeStyle( styleName, table );
-		}
-	} ) );
+export function downcastTableAttribute(conversion, options) {
+    const { modelAttribute, styleName } = options;
+    conversion.for('downcast').add(dispatcher => dispatcher.on(`attribute:${modelAttribute}:table`, (evt, data, conversionApi) => {
+        const { item, attributeNewValue } = data;
+        const { mapper, writer } = conversionApi;
+        if (!conversionApi.consumable.consume(data.item, evt.name)) {
+            return;
+        }
+        const table = [...mapper.toViewElement(item).getChildren()].find(child => child.is('element', 'table'));
+        if (attributeNewValue) {
+            writer.setStyle(styleName, attributeNewValue, table);
+        }
+        else {
+            writer.removeStyle(styleName, table);
+        }
+    }));
 }
-
-// Reduces the full top, right, bottom, left object to a single string if all sides are equal.
-function reduceBoxSidesValue( style ) {
-	if ( !style ) {
-		return;
-	}
-
-	const commonValue = [ 'top', 'right', 'bottom', 'left' ]
-		.map( side => style[ side ] )
-		.reduce( ( result, side ) => result == side ? result : null );
-
-	return commonValue || style;
+/**
+ * Reduces the full top, right, bottom, left object to a single string if all sides are equal.
+ * Returns original style otherwise.
+ */
+function reduceBoxSidesValue(style) {
+    if (!style) {
+        return;
+    }
+    const sides = ['top', 'right', 'bottom', 'left'];
+    const allSidesDefined = sides.every(side => style[side]);
+    if (!allSidesDefined) {
+        return style;
+    }
+    const topSideStyle = style.top;
+    const allSidesEqual = sides.every(side => style[side] === topSideStyle);
+    if (!allSidesEqual) {
+        return style;
+    }
+    return topSideStyle;
 }

package/src/converters/upcasttable.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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 table/converters/upcasttable
+ */
+import type { UpcastDispatcher } from 'ckeditor5/src/engine';
+/**
+ * Returns a function that converts the table view representation:
+ *
+ * ```xml
+ * <figure class="table"><table>...</table></figure>
+ * ```
+ *
+ * to the model representation:
+ *
+ * ```xml
+ * <table></table>
+ * ```
+ */
+export declare function upcastTableFigure(): (dispatcher: UpcastDispatcher) => void;
+/**
+ * View table element to model table element conversion helper.
+ *
+ * This conversion helper converts the table element as well as table rows.
+ *
+ * @returns Conversion helper.
+ */
+export default function upcastTable(): (dispatcher: UpcastDispatcher) => void;
+/**
+ * A conversion helper that skips empty <tr> elements from upcasting at the beginning of the table.
+ *
+ * An empty row is considered a table model error but when handling clipboard data there could be rows that contain only row-spanned cells
+ * and empty TR-s are used to maintain the table structure (also {@link module:table/tablewalker~TableWalker} assumes that there are only
+ * rows that have related `tableRow` elements).
+ *
+ * *Note:* Only the first empty rows are removed because they have no meaning and it solves the issue
+ * of an improper table with all empty rows.
+ *
+ * @returns Conversion helper.
+ */
+export declare function skipEmptyTableRow(): (dispatcher: UpcastDispatcher) => void;
+/**
+ * A converter that ensures an empty paragraph is inserted in a table cell if no other content was converted.
+ *
+ * @returns Conversion helper.
+ */
+export declare function ensureParagraphInTableCell(elementName: string): (dispatcher: UpcastDispatcher) => void;