@ckeditor/ckeditor5-engine 36.0.1 → 37.0.0-alpha.0

package/src/view/styles/border.js

@@ -6,7 +6,9 @@ import { getShorthandValues, getBoxSidesValueReducer, getBoxSidesValues, isLengt
 /**
  * Adds a border CSS styles processing rules.
  *
- *		editor.data.addStyleProcessorRules( addBorderRules );
+ * ```ts
+ * editor.data.addStyleProcessorRules( addBorderRules );
+ * ```
  *
  * This rules merges all [border](https://developer.mozilla.org/en-US/docs/Web/CSS/border) styles notation shorthands:
  *
@@ -25,15 +27,15 @@ import { getShorthandValues, getBoxSidesValueReducer, getBoxSidesValues, isLengt
  *
  * The normalized model stores border values as:
  *
- *		const styles = {
- *			border: {
- *				color: { top, right, bottom, left },
- *				style: { top, right, bottom, left },
- *				width: { top, right, bottom, left },
- *			}
- *		};
- *
- * @param {module:engine/view/stylesmap~StylesProcessor} stylesProcessor
+ * ```ts
+ * const styles = {
+ * 	border: {
+ * 		color: { top, right, bottom, left },
+ * 		style: { top, right, bottom, left },
+ * 		width: { top, right, bottom, left },
+ * 	}
+ * };
+ * ```
  */
 export function addBorderRules(stylesProcessor) {
     stylesProcessor.setNormalizer('border', getBorderNormalizer());
@@ -197,32 +199,38 @@ function normalizeBorderShorthand(string) {
     }
     return result;
 }
-// The border reducer factory.
-//
-// It tries to produce the most optimal output for the specified styles.
-//
-// For a border style:
-//
-//      style: {top: "solid", bottom: "solid", right: "solid", left: "solid"}
-//
-// It will produce: `border-style: solid`.
-// For a border style and color:
-//
-//      color: {top: "#ff0", bottom: "#ff0", right: "#ff0", left: "#ff0"}
-//      style: {top: "solid", bottom: "solid", right: "solid", left: "solid"}
-//
-// It will produce: `border-color: #ff0; border-style: solid`.
-// If all border parameters are specified:
-//
-//      color: {top: "#ff0", bottom: "#ff0", right: "#ff0", left: "#ff0"}
-//      style: {top: "solid", bottom: "solid", right: "solid", left: "solid"}
-//      width: {top: "2px", bottom: "2px", right: "2px", left: "2px"}
-//
-// It will combine everything into a single property: `border: 2px solid #ff0`.
-//
-// The definitions are merged only if all border selectors have the same values.
-//
-// @returns {Function}
+/**
+ * The border reducer factory.
+ *
+ * It tries to produce the most optimal output for the specified styles.
+ *
+ * For a border style:
+ *
+ * ```css
+ * style: {top: "solid", bottom: "solid", right: "solid", left: "solid"}
+ * ```
+ *
+ * It will produce: `border-style: solid`.
+ * For a border style and color:
+ *
+ * ```css
+ * color: {top: "#ff0", bottom: "#ff0", right: "#ff0", left: "#ff0"}
+ * style: {top: "solid", bottom: "solid", right: "solid", left: "solid"}
+ * ```
+ *
+ * It will produce: `border-color: #ff0; border-style: solid`.
+ * If all border parameters are specified:
+ *
+ * ```css
+ * color: {top: "#ff0", bottom: "#ff0", right: "#ff0", left: "#ff0"}
+ * style: {top: "solid", bottom: "solid", right: "solid", left: "solid"}
+ * width: {top: "2px", bottom: "2px", right: "2px", left: "2px"}
+ * ```
+ *
+ * It will combine everything into a single property: `border: 2px solid #ff0`.
+ *
+ * The definitions are merged only if all border selectors have the same values.
+ */
 function getBorderReducer() {
     return value => {
         const topStyles = extractBorderPosition(value, 'top');
@@ -258,8 +266,9 @@ function getBorderReducer() {
             ...reduceBorderPosition(leftStyles, 'left')
         ];
     };
-    // @param {Array.<Object>} styles The array of objects with `style`, `color`, `width` properties.
-    // @param {'width'|'style'|'color'} type
+    /**
+     * @param styles The array of objects with `style`, `color`, `width` properties.
+     */
     function getReducedStyleValueForType(styles, type) {
         return styles
             .map(style => style[type])
@@ -269,16 +278,17 @@ function getBorderReducer() {
 function getBorderPositionReducer(which) {
     return value => reduceBorderPosition(value, which);
 }
-// Returns an array with reduced border styles depending on the specified values.
-//
-// If all border properties (width, style, color) are specified, the returned selector will be
-// merged into a group: `border-*: [width] [style] [color]`.
-//
-// Otherwise, the specific definitions will be returned: `border-(width|style|color)-*: [value]`.
-//
-// @param {Object|null} value Styles if defined.
-// @param {'top'|'right'|'bottom'|'left'|'all'} which The border position.
-// @returns {Array}
+/**
+ * Returns an array with reduced border styles depending on the specified values.
+ *
+ * If all border properties (width, style, color) are specified, the returned selector will be
+ * merged into a group: `border-*: [width] [style] [color]`.
+ *
+ * Otherwise, the specific definitions will be returned: `border-(width|style|color)-*: [value]`.
+ *
+ * @param value Styles if defined.
+ * @param which The border position.
+ */
 function reduceBorderPosition(value, which) {
     const borderTypes = [];
     if (value && (value.width)) {

package/src/view/styles/margin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 engine/view/styles/margin
+ */
+import type { StylesProcessor } from '../stylesmap';
+/**
+ * Adds a margin CSS styles processing rules.
+ *
+ * ```ts
+ * editor.data.addStyleProcessorRules( addMarginRules );
+ * ```
+ *
+ * The normalized value is stored as:
+ *
+ * ```ts
+ * const styles = {
+ * 	margin: {
+ * 		top,
+ * 		right,
+ * 		bottom,
+ * 		left
+ * 	}
+ * };
+ * ```
+ */
+export declare function addMarginRules(stylesProcessor: StylesProcessor): void;

package/src/view/styles/margin.js

@@ -6,20 +6,22 @@ import { getPositionShorthandNormalizer, getBoxSidesValueReducer } from './utils
 /**
  * Adds a margin CSS styles processing rules.
  *
- *		editor.data.addStyleProcessorRules( addMarginRules );
+ * ```ts
+ * editor.data.addStyleProcessorRules( addMarginRules );
+ * ```
  *
  * The normalized value is stored as:
  *
- *		const styles = {
- *			margin: {
- *				top,
- *				right,
- *				bottom,
- *				left
- *			}
- *		};
- *
- * @param {module:engine/view/stylesmap~StylesProcessor} stylesProcessor
+ * ```ts
+ * const styles = {
+ * 	margin: {
+ * 		top,
+ * 		right,
+ * 		bottom,
+ * 		left
+ * 	}
+ * };
+ * ```
  */
 export function addMarginRules(stylesProcessor) {
     stylesProcessor.setNormalizer('margin', getPositionShorthandNormalizer('margin'));

package/src/view/styles/padding.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 engine/view/styles/padding
+ */
+import type { StylesProcessor } from '../stylesmap';
+/**
+ * Adds a margin CSS styles processing rules.
+ *
+ * ```ts
+ * editor.data.addStyleProcessorRules( addPaddingRules );
+ * ```
+ *
+ * The normalized value is stored as:
+ *
+ * ```ts
+ * const styles = {
+ * 	padding: {
+ * 		top,
+ * 		right,
+ * 		bottom,
+ * 		left
+ * 	}
+ * };
+ * ```
+ */
+export declare function addPaddingRules(stylesProcessor: StylesProcessor): void;

package/src/view/styles/padding.js

@@ -6,20 +6,22 @@ import { getPositionShorthandNormalizer, getBoxSidesValueReducer } from './utils
 /**
  * Adds a margin CSS styles processing rules.
  *
- *		editor.data.addStyleProcessorRules( addPaddingRules );
+ * ```ts
+ * editor.data.addStyleProcessorRules( addPaddingRules );
+ * ```
  *
  * The normalized value is stored as:
  *
- *		const styles = {
- *			padding: {
- *				top,
- *				right,
- *				bottom,
- *				left
- *			}
- *		};
- *
- * @param {module:engine/view/stylesmap~StylesProcessor} stylesProcessor
+ * ```ts
+ * const styles = {
+ * 	padding: {
+ * 		top,
+ * 		right,
+ * 		bottom,
+ * 		left
+ * 	}
+ * };
+ * ```
  */
 export function addPaddingRules(stylesProcessor) {
     stylesProcessor.setNormalizer('padding', getPositionShorthandNormalizer('padding'));

package/src/view/styles/utils.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @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 engine/view/styles/utils
+ */
+import type { BoxSides, PropertyDescriptor, StyleValue } from '../stylesmap';
+/**
+ * Checks if string contains [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color) CSS value.
+ *
+ * ```ts
+ * isColor( '#f00' );						// true
+ * isColor( '#AA00BB33' );					// true
+ * isColor( 'rgb(0, 0, 250)' );				// true
+ * isColor( 'hsla(240, 100%, 50%, .7)' );	// true
+ * isColor( 'deepskyblue' );				// true
+ * ```
+ *
+ * **Note**: It does not support CSS Level 4 whitespace syntax, system colors and radius values for HSL colors.
+ */
+export declare function isColor(string: string): boolean;
+/**
+ * Checks if string contains [line style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style) CSS value.
+ */
+export declare function isLineStyle(string: string): boolean;
+/**
+ * Checks if string contains [length](https://developer.mozilla.org/en-US/docs/Web/CSS/length) CSS value.
+ */
+export declare function isLength(string: string): boolean;
+/**
+ * Checks if string contains [percentage](https://developer.mozilla.org/en-US/docs/Web/CSS/percentage) CSS value.
+ */
+export declare function isPercentage(string: string): boolean;
+/**
+ * Checks if string contains [background repeat](https://developer.mozilla.org/en-US/docs/Web/CSS/background-repeat) CSS value.
+ */
+export declare function isRepeat(string: string): boolean;
+/**
+ * Checks if string contains [background position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) CSS value.
+ */
+export declare function isPosition(string: string): boolean;
+/**
+ * Checks if string contains [background attachment](https://developer.mozilla.org/en-US/docs/Web/CSS/background-attachment) CSS value.
+ */
+export declare function isAttachment(string: string): boolean;
+/**
+ * Checks if string contains [URL](https://developer.mozilla.org/en-US/docs/Web/CSS/url) CSS value.
+ */
+export declare function isURL(string: string): boolean;
+/**
+ * Parses box sides as individual values.
+ */
+export declare function getBoxSidesValues(value?: string): BoxSides;
+/**
+ * Default reducer for CSS properties that concerns edges of a box
+ * [shorthand](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) notations:
+ *
+ * ```ts
+ * stylesProcessor.setReducer( 'padding', getBoxSidesValueReducer( 'padding' ) );
+ * ```
+ */
+export declare function getBoxSidesValueReducer(styleShorthand: string): (value: StyleValue) => Array<PropertyDescriptor>;
+/**
+ * Returns a [shorthand](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) notation
+ * of a CSS property value.
+ *
+ * ```ts
+ * getBoxSidesShorthandValue( { top: '1px', right: '1px', bottom: '2px', left: '1px' } );
+ * // will return '1px 1px 2px'
+ * ```
+ */
+export declare function getBoxSidesShorthandValue({ top, right, bottom, left }: BoxSides): string;
+/**
+ * Creates a normalizer for a [shorthand](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) 1-to-4 value.
+ *
+ * ```ts
+ * stylesProcessor.setNormalizer( 'margin', getPositionShorthandNormalizer( 'margin' ) );
+ * ```
+ */
+export declare function getPositionShorthandNormalizer(shorthand: string): (value: string) => {
+    path: string;
+    value: BoxSides;
+};
+/**
+ * Parses parts of a 1-to-4 value notation - handles some CSS values with spaces (like RGB()).
+ *
+ * ```ts
+ * getShorthandValues( 'red blue RGB(0, 0, 0)');
+ * // will return [ 'red', 'blue', 'RGB(0, 0, 0)' ]
+ * ```
+ */
+export declare function getShorthandValues(string: string): Array<string>;

package/src/view/styles/utils.js

@@ -43,16 +43,15 @@ const COLOR_NAMES = new Set([
 /**
  * Checks if string contains [color](https://developer.mozilla.org/en-US/docs/Web/CSS/color) CSS value.
  *
- *		isColor( '#f00' );						// true
- *		isColor( '#AA00BB33' );					// true
- *		isColor( 'rgb(0, 0, 250)' );			// true
- *		isColor( 'hsla(240, 100%, 50%, .7)' );	// true
- *		isColor( 'deepskyblue' );				// true
+ * ```ts
+ * isColor( '#f00' );						// true
+ * isColor( '#AA00BB33' );					// true
+ * isColor( 'rgb(0, 0, 250)' );				// true
+ * isColor( 'hsla(240, 100%, 50%, .7)' );	// true
+ * isColor( 'deepskyblue' );				// true
+ * ```
  *
  * **Note**: It does not support CSS Level 4 whitespace syntax, system colors and radius values for HSL colors.
- *
- * @param {String} string
- * @returns {Boolean}
  */
 export function isColor(string) {
     // As far as I was able to test checking some pre-conditions is faster than joining each test with ||.
@@ -71,9 +70,6 @@ export function isColor(string) {
 const lineStyleValues = ['none', 'hidden', 'dotted', 'dashed', 'solid', 'double', 'groove', 'ridge', 'inset', 'outset'];
 /**
  * Checks if string contains [line style](https://developer.mozilla.org/en-US/docs/Web/CSS/border-style) CSS value.
- *
- * @param {String} string
- * @returns {Boolean}
  */
 export function isLineStyle(string) {
     return lineStyleValues.includes(string);
@@ -81,9 +77,6 @@ export function isLineStyle(string) {
 const lengthRegExp = /^([+-]?[0-9]*([.][0-9]+)?(px|cm|mm|in|pc|pt|ch|em|ex|rem|vh|vw|vmin|vmax)|0)$/;
 /**
  * Checks if string contains [length](https://developer.mozilla.org/en-US/docs/Web/CSS/length) CSS value.
- *
- * @param {String} string
- * @returns {Boolean}
  */
 export function isLength(string) {
     return lengthRegExp.test(string);
@@ -91,9 +84,6 @@ export function isLength(string) {
 const PERCENTAGE_VALUE_REGEXP = /^[+-]?[0-9]*([.][0-9]+)?%$/;
 /**
  * Checks if string contains [percentage](https://developer.mozilla.org/en-US/docs/Web/CSS/percentage) CSS value.
- *
- * @param {String} string
- * @returns {Boolean}
  */
 export function isPercentage(string) {
     return PERCENTAGE_VALUE_REGEXP.test(string);
@@ -101,9 +91,6 @@ export function isPercentage(string) {
 const repeatValues = ['repeat-x', 'repeat-y', 'repeat', 'space', 'round', 'no-repeat'];
 /**
  * Checks if string contains [background repeat](https://developer.mozilla.org/en-US/docs/Web/CSS/background-repeat) CSS value.
- *
- * @param {String} string
- * @returns {Boolean}
  */
 export function isRepeat(string) {
     return repeatValues.includes(string);
@@ -111,9 +98,6 @@ export function isRepeat(string) {
 const positionValues = ['center', 'top', 'bottom', 'left', 'right'];
 /**
  * Checks if string contains [background position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) CSS value.
- *
- * @param {String} string
- * @returns {Boolean}
  */
 export function isPosition(string) {
     return positionValues.includes(string);
@@ -121,9 +105,6 @@ export function isPosition(string) {
 const attachmentValues = ['fixed', 'scroll', 'local'];
 /**
  * Checks if string contains [background attachment](https://developer.mozilla.org/en-US/docs/Web/CSS/background-attachment) CSS value.
- *
- * @param {String} string
- * @returns {Boolean}
  */
 export function isAttachment(string) {
     return attachmentValues.includes(string);
@@ -131,15 +112,12 @@ export function isAttachment(string) {
 const urlRegExp = /^url\(/;
 /**
  * Checks if string contains [URL](https://developer.mozilla.org/en-US/docs/Web/CSS/url) CSS value.
- *
- * @param {String} string
- * @returns {Boolean}
  */
 export function isURL(string) {
     return urlRegExp.test(string);
 }
 /**
- * TODO: Docs
+ * Parses box sides as individual values.
  */
 export function getBoxSidesValues(value = '') {
     if (value === '') {
@@ -156,10 +134,9 @@ export function getBoxSidesValues(value = '') {
  * Default reducer for CSS properties that concerns edges of a box
  * [shorthand](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) notations:
  *
- *		stylesProcessor.setReducer( 'padding', getBoxSidesValueReducer( 'padding' ) );
- *
- * @param {String} styleShorthand
- * @returns {Function}
+ * ```ts
+ * stylesProcessor.setReducer( 'padding', getBoxSidesValueReducer( 'padding' ) );
+ * ```
  */
 export function getBoxSidesValueReducer(styleShorthand) {
     return (value) => {
@@ -189,11 +166,10 @@ export function getBoxSidesValueReducer(styleShorthand) {
  * Returns a [shorthand](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) notation
  * of a CSS property value.
  *
- *		getBoxSidesShorthandValue( { top: '1px', right: '1px', bottom: '2px', left: '1px' } );
- *		// will return '1px 1px 2px'
- *
- * @param {module:engine/view/stylesmap~BoxSides} styleShorthand
- * @returns {String}
+ * ```ts
+ * getBoxSidesShorthandValue( { top: '1px', right: '1px', bottom: '2px', left: '1px' } );
+ * // will return '1px 1px 2px'
+ * ```
  */
 export function getBoxSidesShorthandValue({ top, right, bottom, left }) {
     const out = [];
@@ -214,10 +190,9 @@ export function getBoxSidesShorthandValue({ top, right, bottom, left }) {
 /**
  * Creates a normalizer for a [shorthand](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties) 1-to-4 value.
  *
- *		stylesProcessor.setNormalizer( 'margin', getPositionShorthandNormalizer( 'margin' ) );
- *
- * @param {String} shorthand
- * @returns {Function}
+ * ```ts
+ * stylesProcessor.setNormalizer( 'margin', getPositionShorthandNormalizer( 'margin' ) );
+ * ```
  */
 export function getPositionShorthandNormalizer(shorthand) {
     return (value) => {
@@ -230,11 +205,10 @@ export function getPositionShorthandNormalizer(shorthand) {
 /**
  * Parses parts of a 1-to-4 value notation - handles some CSS values with spaces (like RGB()).
  *
- *		getShorthandValues( 'red blue RGB(0, 0, 0)');
- *		// will return [ 'red', 'blue', 'RGB(0, 0, 0)' ]
- *
- * @param {String} string
- * @returns {Array.<String>}
+ * ```ts
+ * getShorthandValues( 'red blue RGB(0, 0, 0)');
+ * // will return [ 'red', 'blue', 'RGB(0, 0, 0)' ]
+ * ```
  */
 export function getShorthandValues(string) {
     return string