@ckeditor/ckeditor5-engine 47.6.1 → 48.0.0-alpha.0

package/dist/index.js

@@ -3,7 +3,7 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 import { logWarning, EmitterMixin, CKEditorError, compareArrays, toArray, toMap, isIterable, ObservableMixin, count, EventInfo, Collection, keyCodes, isText, env, remove as remove$1, insertAt, diff, fastDiff, isNode, isComment, indexOf, global, isValidAttributeName, first, getAncestors, DomEmitterMixin, getCode, isArrowKeyCode, scrollViewportToShowTarget, uid, spliceArray, priorities, isInsideSurrogatePair, isInsideCombinedSymbol, isInsideEmojiSequence } from '@ckeditor/ckeditor5-utils/dist/index.js';
-import { isObject, get, merge, set, isPlainObject, extend, debounce, isEqualWith, cloneDeep, isEqual, clone } from 'es-toolkit/compat';
+import { isObject, get, merge, set, isPlainObject, extend, debounce, isEqualWith, cloneDeep, isEqual, clone, isEmpty } from 'es-toolkit/compat';
 
 // Each document stores information about its placeholder elements and check functions.
 const documentPlaceholders = new WeakMap();
@@ -267,8 +267,9 @@ let hasDisplayedPlaceholderDeprecationWarning = false;
 		 * The "text" option in the {@link module:engine/view/placeholder~enableViewPlaceholder `enableViewPlaceholder()`}
 		 * function is deprecated and will be removed soon.
 		 *
-		 * See the {@glink updating/guides/update-to-39#view-element-placeholder Migration to v39} guide for
-		 * more information on how to apply this change.
+		 * See the `#view-element-placeholder` section in the `Update to v39.x` section in the
+		 * {@glink updating/guides/updating-from-older-versions updating from older versions} guide
+		 * for more information on how to apply this change.
 		 *
 		 * @error enableViewPlaceholder-deprecated-text-option
 		 */ logWarning('enableViewPlaceholder-deprecated-text-option');
@@ -1630,7 +1631,8 @@ ViewTextProxy.prototype.is = function(type) {
  * }
  * ```
  *
- * Refer to the {@glink updating/guides/update-to-29##update-to-ckeditor-5-v2910 Migration to v29.1.0} guide
+ * Refer to the `#update-to-ckeditor-5-v2910` section in the `Update to v29.x` section in the
+ * {@glink updating/guides/updating-from-older-versions updating from older versions} guide
  * and {@link module:engine/view/matcher~MatcherPattern} documentation.
  *
  * @param pattern Pattern with missing properties.
@@ -1660,7 +1662,8 @@ ViewTextProxy.prototype.is = function(type) {
  * }
  * ```
  *
- * Refer to the {@glink updating/guides/update-to-29##update-to-ckeditor-5-v2910 Migration to v29.1.0} guide
+ * Refer to the `#update-to-ckeditor-5-v2910` paragraph in the Update to v29.x guide in the
+ * {@glink updating/guides/updating-from-older-versions updating from older versions} guide
  * and the {@link module:engine/view/matcher~MatcherPattern} documentation.
  *
  * @param pattern Pattern with missing properties.
@@ -2534,7 +2537,9 @@ ViewTextProxy.prototype.is = function(type) {
  * Appends style definition to the styles object.
  */ function appendStyleValue(stylesObject, nameOrPath, valueOrObject) {
     let valueToSet = valueOrObject;
-    if (isObject(valueOrObject)) {
+    // We don't want to merge it with existing value when it's array. It's because some styles can be defined
+    // as array of layers (e.g. background-image) and in such case we want to override whole array instead of merging it with existing one.
+    if (isObject(valueOrObject) && !Array.isArray(valueOrObject)) {
         valueToSet = merge({}, get(stylesObject, nameOrPath), valueOrObject);
     }
     set(stylesObject, nameOrPath, valueToSet);
@@ -17851,7 +17856,7 @@ ModelNode.prototype.is = function(type) {
 	 * selection.setTo( paragraph, 'on' );
 	 * ```
 	 *
-	 * `Selection#setTo()`' method allow passing additional options (`backward`) as the last argument.
+	 * `Selection#setTo()` method allows passing additional options (`backward`) as the last argument.
 	 *
 	 * ```ts
 	 * // Sets backward selection.
@@ -35537,7 +35542,7 @@ function removeRangeContent(range, writer) {
         this._mergeOnRight();
         // TMP this will become a post-fixer.
         this.schema.removeDisallowedAttributes(this._filterAttributesAndChildrenOf, this.writer);
-        if (this.model._config?.get('experimentalFlags.modelInsertContentDeepSchemaVerification')) {
+        if (this.model._config?.get('experimentalFlags.modelInsertContentDeepSchemaVerification') !== false) {
             this._removeDisallowedChildren(this._filterAttributesAndChildrenOf);
         }
         this._filterAttributesAndChildrenOf = [];
@@ -36863,8 +36868,7 @@ function getSearchRange(start, isForward) {
         return getSelectedContent(this, selection);
     }
     /**
-	 * Checks whether the given {@link module:engine/model/range~ModelRange range} or
-	 * {@link module:engine/model/element~ModelElement element} has any meaningful content.
+	 * Checks whether given `subject` has any meaningful content.
 	 *
 	 * Meaningful content is:
 	 *
@@ -36878,11 +36882,35 @@ function getSearchRange(start, isForward) {
 	 * However, a range containing an `<imageBlock></imageBlock>` (which would normally be marked in the schema as an object element)
 	 * is considered non-empty.
 	 *
-	 * @param rangeOrElement Range or element to check.
+	 * @param subject Subject to check if includes meaningful content. Could be a model range, an element, a document fragment, or a
+	 * selection.
 	 * @param options.ignoreWhitespaces Whether text node with whitespaces only should be considered empty.
 	 * @param options.ignoreMarkers Whether markers should be ignored.
-	 */ hasContent(rangeOrElement, options = {}) {
-        const range = rangeOrElement instanceof ModelRange ? rangeOrElement : ModelRange._createIn(rangeOrElement);
+	 */ hasContent(subject, options = {}) {
+        let ranges;
+        if (subject.is('selection')) {
+            ranges = Array.from(subject.getRanges());
+        } else if (subject.is('range')) {
+            ranges = [
+                subject
+            ];
+        } else {
+            ranges = [
+                ModelRange._createIn(subject)
+            ];
+        }
+        for (const range of ranges){
+            if (this._rangeHasContent(range, options)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+	 * Checks whether given range has any meaningful content.
+	 *
+	 * Helper method for {@link #hasContent}.
+	 */ _rangeHasContent(range, options) {
         if (range.isCollapsed) {
             return false;
         }
@@ -37762,6 +37790,16 @@ const PERCENTAGE_VALUE_REGEXP = /^[+-]?[0-9]*([.][0-9]+)?%$/;
  */ function isPercentageStyleValue(string) {
     return PERCENTAGE_VALUE_REGEXP.test(string);
 }
+const sizeValues = [
+    'auto',
+    'cover',
+    'contain'
+];
+/**
+ * Checks if a string is a valid CSS `background-size` value token.
+ */ function isSizeStyleValue(value) {
+    return sizeValues.includes(value) || isLengthStyleValue(value) || isPercentageStyleValue(value);
+}
 const repeatValues = [
     'repeat-x',
     'repeat-y',
@@ -37797,6 +37835,27 @@ const attachmentValues = [
  */ function isAttachmentStyleValue(string) {
     return attachmentValues.includes(string);
 }
+const originValues = [
+    'border-box',
+    'padding-box',
+    'content-box'
+];
+/**
+ * Checks if string contains [background origin](https://developer.mozilla.org/en-US/docs/Web/CSS/background-origin) CSS value.
+ */ function isOriginStyleValue(string) {
+    return originValues.includes(string);
+}
+const clipValues = [
+    'border-box',
+    'padding-box',
+    'content-box',
+    'text'
+];
+/**
+ * Checks if string contains [background clip](https://developer.mozilla.org/en-US/docs/Web/CSS/background-clip) CSS value.
+ */ function isClipStyleValue(string) {
+    return clipValues.includes(string);
+}
 const urlRegExp = /^url\(/;
 /**
  * Checks if string contains [URL](https://developer.mozilla.org/en-US/docs/Web/CSS/url) CSS value.
@@ -37924,77 +37983,530 @@ const urlRegExp = /^url\(/;
 }
 
 /**
- * Adds a background CSS styles processing rules.
+ * CSS initial values for background longhand properties.
+ */ const BACKGROUND_INITIAL_ARRAY_VALUES = {
+    image: 'none',
+    repeat: 'repeat',
+    position: '0% 0%',
+    size: 'auto',
+    origin: 'padding-box',
+    clip: 'border-box',
+    attachment: 'scroll'
+};
+/**
+ * CSS function names that represent image values in the `background` shorthand.
+ */ const IMAGE_FUNCTIONS = [
+    'linear-gradient',
+    'repeating-linear-gradient',
+    'radial-gradient',
+    'repeating-radial-gradient',
+    'conic-gradient',
+    'repeating-conic-gradient',
+    'url'
+];
+/**
+ * Adds background CSS styles processing rules to the given `StylesProcessor`.
+ *
+ * Registers normalizers for the `background` shorthand and its longhand properties,
+ * reducers that serialize them back to CSS strings, and the relation mapping between them.
  *
  * ```ts
  * editor.data.addStyleProcessorRules( addBackgroundStylesRules );
  * ```
  *
- * The normalized value is stored as:
- *
- * ```ts
- * const styles = {
- * 	background: {
- * 		color,
- * 		repeat,
- * 		position,
- * 		attachment,
- * 		image
- * 	}
- * };
- * ````
- *
- * **Note**: Currently only `'background-color'` longhand value is parsed besides `'background'` shorthand. The reducer also supports only
- * `'background-color'` value.
+ * @param stylesProcessor The styles processor instance to register rules on.
  */ function addBackgroundStylesRules(stylesProcessor) {
-    stylesProcessor.setNormalizer('background', getBackgroundNormalizer());
     stylesProcessor.setNormalizer('background-color', getBackgroundColorNormalizer());
+    for(const property in BACKGROUND_INITIAL_ARRAY_VALUES){
+        stylesProcessor.setNormalizer(`background-${property}`, getBackgroundArrayPropertyNormalizer(`background.${property}`));
+        stylesProcessor.setReducer(`background-${property}`, getBackgroundArrayPropertyReducer(`background-${property}`));
+    }
+    // Normalized data format:
+    // {
+    // 	color: 'red',
+    // 	image: [ 'url(img1.png)', 'url(img2.png)' ],
+    // 	position: [ '0% 0%', '50% 50%' ],
+    // 	repeat: [ 'no-repeat', 'repeat' ],
+    // 	// ...
+    // }
+    stylesProcessor.setNormalizer('background', getBackgroundNormalizer());
     stylesProcessor.setReducer('background', getBackgroundReducer());
     stylesProcessor.setStyleRelation('background', [
-        'background-color'
+        'background-color',
+        'background-image',
+        'background-repeat',
+        'background-position',
+        'background-size',
+        'background-attachment',
+        'background-origin',
+        'background-clip'
     ]);
 }
-function getBackgroundNormalizer() {
+/**
+ * Returns a normalizer for the `background` shorthand property.
+ *
+ * Parses the raw CSS value into comma-separated layers and merges them into
+ * a structured `Background` object stored under the `background` path.
+ */ function getBackgroundNormalizer() {
     return (value)=>{
-        const background = {};
-        const parts = getShorthandStylesValues(value);
-        for (const part of parts){
-            if (isRepeatStyleValue(part)) {
-                background.repeat = background.repeat || [];
-                background.repeat.push(part);
-            } else if (isPositionStyleValue(part)) {
-                background.position = background.position || [];
-                background.position.push(part);
-            } else if (isAttachmentStyleValue(part)) {
-                background.attachment = part;
-            } else if (isColorStyleValue(part)) {
-                background.color = part;
-            } else if (isURLStyleValue(part)) {
-                background.image = part;
-            }
+        const layers = parseBackgroundIntoLayers(value);
+        // If for some reason, it was impossible to extract any valid layers from the input,
+        // assume it's color value for a single layer background, as it's the most common use
+        // case and better than losing the value completely.
+        if (!layers.length) {
+            layers.push({
+                ...getDefaultBackgroundLayer(),
+                color: value
+            });
         }
+        const background = normalizeBackgroundLayers(layers);
         return {
             path: 'background',
             value: background
         };
     };
 }
-function getBackgroundColorNormalizer() {
+/**
+ * Returns a normalizer for the `background-color` longhand property.
+ *
+ * Stores the raw color value directly under the `background.color` path.
+ */ function getBackgroundColorNormalizer() {
     return (value)=>({
             path: 'background.color',
             value
         });
 }
-function getBackgroundReducer() {
+/**
+ * Returns a normalizer for a comma-separated background array longhand property
+ * (e.g. `background-image`, `background-repeat`, `background-position`, `background-attachment`).
+ *
+ * Splits the raw value by top-level commas and stores the resulting array under the given path.
+ *
+ * @param path The target style path, e.g. `'background.image'`.
+ */ function getBackgroundArrayPropertyNormalizer(path) {
+    return (value)=>({
+            path,
+            value: splitByTopLevelCommas(value)
+        });
+}
+/**
+ * Returns a reducer for a comma-separated background array longhand property
+ * (e.g. `background-image`, `background-repeat`, `background-position`, `background-attachment`).
+ *
+ * Serializes an array of per-layer values back into a comma-separated CSS string.
+ *
+ * @param property The CSS property name to output, e.g. `'background-image'`.
+ */ function getBackgroundArrayPropertyReducer(property) {
     return (value)=>{
-        const ret = [];
-        ret.push([
+        const serialized = value.join(', ');
+        return [
+            [
+                property,
+                serialized
+            ]
+        ];
+    };
+}
+/**
+ * Returns a reducer for the `background` property. Depending on which longhand properties are present, it either:
+ *
+ * * Serializes into a concise `background` shorthand if all required longhand properties are present and non-empty, or
+ * * Serializes into individual longhand properties for those that have defined values.
+ *
+ * This prevents overwriting external stylesheet rules with default values that were not explicitly set in the model.
+ * For example, if only `background-color` is defined in the model, we emit just `background-color` rather than
+ * the full `background` shorthand, which would reset all other sub-properties to their initial values.
+ */ function getBackgroundReducer() {
+    return (value)=>{
+        const background = value;
+        // It is highly unlikely that all of these properties were set manually. If all fields are present,
+        // they were most likely populated by parsing the `background` shorthand, which fills all of them
+        // for every layer. In this case, we can safely serialize back to the `background` shorthand.
+        // On the other hand, if some fields are missing, it means the background was created by manually
+        // setting individual longhand properties (e.g., `background-origin`, `background-attachment`, etc.).
+        // We should preserve that intent and serialize to longhands to prevent emitting default values
+        // for the missing properties.
+        const allFieldsLayersFilled = Object.keys(BACKGROUND_INITIAL_ARRAY_VALUES).every((key)=>{
+            const value = background[key];
+            return value !== undefined && (!Array.isArray(value) || value.length > 0);
+        });
+        if (allFieldsLayersFilled) {
+            return serializeToShorthandBackground(background);
+        }
+        return serializeToLonghandBackground(background);
+    };
+}
+/**
+ * Serializes a structured `Background` object into a concise CSS `background` shorthand string.
+ */ function serializeToShorthandBackground(background) {
+    const result = [];
+    const shorthand = extractBackgroundLayers(background).map((layer)=>serializeBackgroundLayer(layer).trim()).filter(Boolean).join(', ');
+    if (shorthand) {
+        result.push([
+            'background',
+            shorthand
+        ]);
+    }
+    return result;
+}
+/**
+ * Serializes a structured `Background` object into individual CSS longhand properties for those that have defined values.
+ * Each longhand property is serialized into a comma-separated string of per-layer values.
+ *
+ * This is used when not all required longhand properties are present, to avoid emitting default values for missing properties
+ * and potentially overwriting external stylesheet rules.
+ */ function serializeToLonghandBackground(background) {
+    const result = [];
+    for(const key in BACKGROUND_INITIAL_ARRAY_VALUES){
+        const value = background[key];
+        if (Array.isArray(value)) {
+            result.push([
+                `background-${key}`,
+                value.join(', ')
+            ]);
+        }
+    }
+    if (background.color !== undefined) {
+        result.push([
             'background-color',
-            value.color
+            background.color
         ]);
-        return ret;
+    }
+    return result;
+}
+/**
+ * Serializes a single `BackgroundLayer` into a CSS background layer string.
+ * Properties equal to their CSS initial values are omitted.
+ *
+ * @param layer A single background layer to serialize.
+ * @returns A space-separated CSS string for the layer, or an empty string if no parts are present.
+ */ function serializeBackgroundLayer(layer) {
+    const parts = [];
+    if (layer.image && layer.image !== BACKGROUND_INITIAL_ARRAY_VALUES.image) {
+        parts.push(layer.image);
+    }
+    const positionStr = layer.position.join(' ');
+    const isPositionDefault = !positionStr || positionStr === BACKGROUND_INITIAL_ARRAY_VALUES.position;
+    if (!isPositionDefault) {
+        parts.push(positionStr);
+    }
+    const sizeStr = layer.size.join(' ');
+    const isSizeDefault = !sizeStr || sizeStr === BACKGROUND_INITIAL_ARRAY_VALUES.size;
+    if (!isSizeDefault) {
+        if (isPositionDefault) {
+            parts.push('0% 0%');
+        }
+        parts.push('/', sizeStr);
+    }
+    const repeatStr = layer.repeat.join(' ');
+    if (repeatStr && repeatStr !== BACKGROUND_INITIAL_ARRAY_VALUES.repeat) {
+        parts.push(repeatStr);
+    }
+    if (layer.attachment && layer.attachment !== BACKGROUND_INITIAL_ARRAY_VALUES.attachment) {
+        parts.push(layer.attachment);
+    }
+    const isOriginDefault = layer.origin === BACKGROUND_INITIAL_ARRAY_VALUES.origin;
+    const isClipDefault = layer.clip === BACKGROUND_INITIAL_ARRAY_VALUES.clip;
+    if (!isOriginDefault || !isClipDefault) {
+        parts.push(layer.origin);
+        if (layer.clip !== layer.origin) {
+            parts.push(layer.clip);
+        }
+    }
+    if (layer.color) {
+        parts.push(layer.color);
+    }
+    return parts.join(' ');
+}
+/**
+ * Splits a structured `Background` object into an array of individual `BackgroundLayer` objects.
+ *
+ * The number of layers is determined by the longest array among the longhand properties.
+ * The `color` value, if present, is always assigned to the last layer (per CSS spec).
+ *
+ * @param background The structured background object to split.
+ * @returns An array of per-layer background objects.
+ *
+ * @example
+ * // Input: { image: [ 'url(a.png)', 'url(b.png)' ], repeat: [ 'no-repeat', 'repeat' ], color: 'blue' }
+ * // Output: [
+ * //   { image: 'url(a.png)', repeat: [ 'no-repeat' ] },
+ * //   { image: 'url(b.png)', repeat: [ 'repeat' ], color: 'blue' }
+ * // ]
+ */ function extractBackgroundLayers(background) {
+    const layerCount = getTotalBackgroundLayers(background);
+    const layers = Array.from({
+        length: layerCount
+    }, (_, i)=>{
+        const layer = getDefaultBackgroundLayer();
+        if (background.image?.[i]) {
+            layer.image = background.image[i];
+        }
+        if (background.position?.[i]) {
+            layer.position = background.position[i].split(' ');
+        }
+        if (background.size?.[i]) {
+            layer.size = background.size[i].split(' ');
+        }
+        if (background.repeat?.[i]) {
+            layer.repeat = background.repeat[i].split(' ');
+        }
+        if (background.attachment?.[i]) {
+            layer.attachment = background.attachment[i];
+        }
+        if (background.origin?.[i]) {
+            layer.origin = background.origin[i];
+        }
+        if (background.clip?.[i]) {
+            layer.clip = background.clip[i];
+        }
+        return layer;
+    });
+    if (background.color) {
+        // According to standard, the last layer can contain the color definition,
+        // so we set it on the last layer if it exists.
+        layers.at(-1).color = background.color;
+    }
+    return layers;
+}
+/**
+ * Determines the total number of background layers based on the longest array among the longhand properties in the `Background` object.
+ *
+ * @param background The structured background object to analyze.
+ * @returns The total number of layers, which is the maximum length among the longhand property arrays.
+ */ function getTotalBackgroundLayers(background) {
+    let layersCount = 0;
+    for (const value of Object.values(background)){
+        if (Array.isArray(value) && value.length > layersCount) {
+            layersCount = value.length;
+        }
+    }
+    return layersCount;
+}
+/**
+ * Merges an array of `BackgroundLayer` objects into a single structured `Background` object,
+ * storing each longhand property as an array of per-layer values.
+ *
+ * Each input layer always has all properties defined (via `getDefaultBackgroundLayer`),
+ * so the resulting arrays are fully populated for every layer.
+ *
+ * @param layers An array of parsed background layers.
+ * @returns A merged `Background` object.
+ *
+ * @example
+ * // Input: [ { image: 'url(a.png)', repeat: [ 'no-repeat' ], position: [ '0%', '0%' ], ... }, { image: 'none', color: 'red', ... } ]
+ * // Output: {
+ * //   image: [ 'url(a.png)', 'none' ],
+ * //   position: [ '0% 0%', '0% 0%' ],
+ * //   repeat: [ 'no-repeat', 'repeat' ],
+ * //   ...
+ * //   color: 'red'
+ * // }
+ */ function normalizeBackgroundLayers(layers) {
+    const background = {
+        image: [],
+        position: [],
+        size: [],
+        repeat: [],
+        attachment: [],
+        origin: [],
+        clip: []
+    };
+    for (const layer of layers){
+        background.position.push(layer.position.join(' '));
+        background.size.push(layer.size.join(' '));
+        background.repeat.push(layer.repeat.join(' '));
+        background.image.push(layer.image);
+        background.attachment.push(layer.attachment);
+        background.origin.push(layer.origin);
+        background.clip.push(layer.clip);
+    }
+    if (layers.at(-1)?.color) {
+        background.color = layers.at(-1).color;
+    }
+    return background;
+}
+/**
+ * Parses a raw CSS `background` value and splits it into an array of `BackgroundLayer` objects,
+ * one per comma-separated layer.
+ *
+ * The CSS `background` shorthand syntax is:
+ * `background: [ <bg-layer> , ]* <final-bg-layer>`
+ *
+ * Commas inside function calls (e.g. `rgba()`, `linear-gradient()`) are correctly ignored
+ * during splitting.
+ *
+ * @param value The raw CSS background value string.
+ * @returns An array of parsed background layers.
+ *
+ * @example
+ * splitBackgroundIntoLayers( 'url(a.png) no-repeat, red' );
+ * // → [ { image: 'url(a.png)', repeat: [ 'no-repeat' ] }, { color: 'red' } ]
+ */ function parseBackgroundIntoLayers(value) {
+    return splitByTopLevelCommas(value).map(parseBackgroundLayer).filter((obj)=>obj !== null);
+}
+/**
+ * Parses a single CSS background layer string into a structured `BackgroundLayer` object.
+ *
+ * First extracts any image function (gradient or `url()`), then classifies the remaining
+ * space-separated tokens as repeat, position, attachment, or color values.
+ *
+ * @param layer A single (non-comma-separated) background layer string.
+ * @returns A structured background layer object. If no valid properties were found, returns `null`.
+ *
+ * @example
+ * parseBackgroundLayer( 'url(bg.png) top left no-repeat fixed' );
+ * // → { image: 'url(bg.png)', position: [ 'top', 'left' ], repeat: [ 'no-repeat' ], attachment: 'fixed' }
+ */ function parseBackgroundLayer(layer) {
+    const background = {};
+    const { value: valueWithoutImage, image } = extractBackgroundImage(layer);
+    const parts = getShorthandStylesValues(valueWithoutImage);
+    if (image) {
+        background.image = image;
+    }
+    for(let i = 0; i < parts.length; i++){
+        const part = parts[i];
+        if (part === '/') {
+            background.size = [];
+            while(i + 1 < parts.length && isSizeStyleValue(parts[i + 1])){
+                background.size.push(parts[++i]);
+            }
+        } else if (isRepeatStyleValue(part)) {
+            background.repeat ||= [];
+            background.repeat.push(part);
+        } else if (isPositionStyleValue(part) || isPercentageStyleValue(part)) {
+            background.position ||= [];
+            background.position.push(part);
+            // Percentage positions can be paired (e.g. '0% 0%'), so consume the next token if it's also a percentage.
+            if (i + 1 < parts.length && isPercentageStyleValue(part) && isPercentageStyleValue(parts[i + 1])) {
+                background.position.push(parts[++i]);
+            }
+        } else if (isAttachmentStyleValue(part)) {
+            background.attachment = part;
+        } else if (isClipStyleValue(part)) {
+            if (isOriginStyleValue(part) && !background.origin) {
+                // First box value sets both origin and clip (per CSS spec).
+                background.origin = part;
+                background.clip = part;
+            } else {
+                // Second box value (or 'text') sets only clip.
+                background.clip = part;
+            }
+        } else if (isColorStyleValue(part)) {
+            background.color = part;
+        }
+    }
+    if (isEmpty(background)) {
+        return null;
+    }
+    return {
+        ...getDefaultBackgroundLayer(),
+        ...background
+    };
+}
+/**
+ * Returns a `BackgroundLayer` object with all properties set to their CSS initial values.
+ *
+ * Used as the base when parsing the `background` shorthand so that every property of a parsed
+ * layer always has a defined value.
+ *
+ * @returns A background layer with default values.
+ */ function getDefaultBackgroundLayer() {
+    return {
+        attachment: BACKGROUND_INITIAL_ARRAY_VALUES.attachment,
+        image: BACKGROUND_INITIAL_ARRAY_VALUES.image,
+        origin: BACKGROUND_INITIAL_ARRAY_VALUES.origin,
+        clip: BACKGROUND_INITIAL_ARRAY_VALUES.clip,
+        position: BACKGROUND_INITIAL_ARRAY_VALUES.position.split(' '),
+        repeat: BACKGROUND_INITIAL_ARRAY_VALUES.repeat.split(' '),
+        size: BACKGROUND_INITIAL_ARRAY_VALUES.size.split(' ')
+    };
+}
+/**
+ * Extracts the first CSS image function (`linear-gradient`, `url`, etc.) from a raw CSS value string
+ * and returns it separately along with the remaining string with the image function removed.
+ *
+ * Handles arbitrarily nested parentheses correctly (e.g. `rgba()` inside a gradient).
+ * Only one image function is extracted per call — the caller is responsible for looping
+ * if multiple image functions may be present.
+ *
+ * @param value The raw CSS value string to process.
+ * @returns An object with `value` (the string with the image function removed) and
+ *          `image` (the extracted function string, or `null` if none was found).
+ *
+ * @example
+ * extractBackgroundImage( 'linear-gradient(red, blue) no-repeat' );
+ * // → { value: ' no-repeat', image: 'linear-gradient(red, blue)' }
+ */ function extractBackgroundImage(value) {
+    for (const imageFunction of IMAGE_FUNCTIONS){
+        const prefix = imageFunction + '(';
+        const firstIndex = value.indexOf(prefix);
+        if (firstIndex < 0) {
+            continue;
+        }
+        let acc = imageFunction;
+        let nesting = 0;
+        for(let i = firstIndex + imageFunction.length; i < value.length; i++){
+            const char = value[i];
+            if (char === '(') {
+                nesting++;
+            } else if (char === ')') {
+                nesting--;
+            }
+            acc += char;
+            if (nesting === 0) {
+                return {
+                    value: value.slice(0, firstIndex) + value.slice(i + 1),
+                    image: acc
+                };
+            }
+        }
+    }
+    // If no image functions were found, check if the value contains 'none', which is also a valid background-image value.
+    if (value.includes('none')) {
+        return {
+            value: value.replace('none', ''),
+            image: 'none'
+        };
+    }
+    return {
+        value,
+        image: null
     };
 }
+/**
+ * Splits a CSS value string by commas that are at the top level (i.e. not inside parentheses).
+ *
+ * This is necessary because commas appear both as layer separators in the `background` shorthand
+ * and as argument separators inside functions like `rgba()` or `linear-gradient()`.
+ *
+ * @param value The CSS value string to split.
+ * @returns An array of trimmed top-level comma-separated segments.
+ *
+ * @example
+ * splitByTopLevelCommas( 'linear-gradient(red, blue), center' );
+ * // → [ 'linear-gradient(red, blue)', 'center' ]
+ */ function splitByTopLevelCommas(value) {
+    const parts = [];
+    let current = '';
+    let nesting = 0;
+    for (const char of value){
+        if (char === '(') {
+            nesting++;
+        } else if (char === ')') {
+            nesting--;
+        } else if (char === ',' && nesting === 0) {
+            parts.push(current.trim());
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim()) {
+        parts.push(current.trim());
+    }
+    return parts;
+}
 
 /**
  * Adds a border CSS styles processing rules.
@@ -38017,19 +38529,13 @@ function getBackgroundReducer() {
  * and all corresponding longhand forms (like `border-top-color`, `border-top-style`, etc).
  *
  * It does not handle other shorthands (like `border-radius` or `border-image`).
- *
- * The normalized model stores border values as:
- *
- * ```ts
- * const styles = {
- * 	border: {
- * 		color: { top, right, bottom, left },
- * 		style: { top, right, bottom, left },
- * 		width: { top, right, bottom, left },
- * 	}
- * };
- * ```
  */ function addBorderStylesRules(stylesProcessor) {
+    // Normalized data format:
+    // {
+    // 	color: { top: 'red', right: 'red', bottom: 'red', left: 'red' },
+    // 	style: { top: 'solid', right: 'solid', bottom: 'solid', left: 'solid' },
+    // 	width: { top: '1px', right: '1px', bottom: '1px', left: '1px' }
+    // }
     stylesProcessor.setNormalizer('border', getBorderNormalizer());
     // Border-position shorthands.
     stylesProcessor.setNormalizer('border-top', getBorderPositionNormalizer('top'));
@@ -38368,20 +38874,14 @@ function getBorderPositionReducer(which) {
  * ```ts
  * editor.data.addStyleProcessorRules( addMarginStylesRules );
  * ```
- *
- * The normalized value is stored as:
- *
- * ```ts
- * const styles = {
- * 	margin: {
- * 		top,
- * 		right,
- * 		bottom,
- * 		left
- * 	}
- * };
- * ```
  */ function addMarginStylesRules(stylesProcessor) {
+    // Normalized data format:
+    // {
+    // 	top: '1px',
+    // 	right: '2px',
+    // 	bottom: '3px',
+    // 	left: '4px'
+    // }
     stylesProcessor.setNormalizer('margin', getPositionStyleShorthandNormalizer('margin'));
     stylesProcessor.setNormalizer('margin-top', (value)=>({
             path: 'margin.top',
@@ -38414,20 +38914,14 @@ function getBorderPositionReducer(which) {
  * ```ts
  * editor.data.addStyleProcessorRules( addPaddingStylesRules );
  * ```
- *
- * The normalized value is stored as:
- *
- * ```ts
- * const styles = {
- * 	padding: {
- * 		top,
- * 		right,
- * 		bottom,
- * 		left
- * 	}
- * };
- * ```
  */ function addPaddingStylesRules(stylesProcessor) {
+    // Normalized data format:
+    // {
+    // 	top: '1px',
+    // 	right: '2px',
+    // 	bottom: '3px',
+    // 	left: '4px'
+    // }
     stylesProcessor.setNormalizer('padding', getPositionStyleShorthandNormalizer('padding'));
     stylesProcessor.setNormalizer('padding-top', (value)=>({
             path: 'padding.top',
@@ -39983,5 +40477,5 @@ const maxTreeDumpLength = 20;
     }
 }
 
-export { AttributeOperation, Batch, BubblingEmitterMixin, BubblingEventInfo, ClickObserver, CompositionObserver, Conversion, ConversionHelpers, DataController, Differ, DomEventObserver, DowncastHelpers, EditingController, EditingView, FakeSelectionObserver, FocusObserver, History, HtmlDataProcessor, InputObserver, InsertOperation, KeyObserver, Mapper, MarkerCollection, MarkerOperation, Matcher, MergeOperation, Model, ModelDocument, ModelDocumentFragment, ModelDocumentSelection, ModelElement, ModelLivePosition, ModelLiveRange, ModelNode, ModelNodeList, ModelPosition, ModelRange, ModelRootElement, ModelSchema, ModelSchemaContext, ModelSelection, ModelText, ModelTextProxy, ModelTreeWalker, ModelTypeCheckable, ModelWriter, MouseObserver, MoveOperation, MutationObserver, NoOperation, Observer, OperationFactory, PointerObserver, RenameOperation, RootAttributeOperation, RootOperation, SelectionObserver, SplitOperation, StylesMap, StylesProcessor, TabObserver, TouchObserver, UpcastHelpers, ViewUpcastWriter as UpcastWriter, ViewAttributeElement, ViewContainerElement, ViewDataTransfer, ViewDocument, ViewDocumentDomEventData, ViewDocumentFragment, ViewDocumentSelection, ViewDomConverter, ViewDowncastWriter, ViewEditableElement, ViewElement, ViewEmptyElement, ViewNode, ViewPosition, ViewRange, ViewRawElement, ViewRenderer, ViewRootEditableElement, ViewSelection, ViewText, ViewTextProxy, ViewTokenList, ViewTreeWalker, ViewTypeCheckable, ViewUIElement, ViewUpcastWriter, XmlDataProcessor, BasicHtmlWriter as _DataProcessorBasicHtmlWriter, DetachOperation as _DetachOperation, MapperCache as _MapperCache, OperationReplayer as _OperationReplayer, BR_FILLER as _VIEW_BR_FILLER, INLINE_FILLER as _VIEW_INLINE_FILLER, INLINE_FILLER_LENGTH as _VIEW_INLINE_FILLER_LENGTH, MARKED_NBSP_FILLER as _VIEW_MARKED_NBSP_FILLER, NBSP_FILLER as _VIEW_NBSP_FILLER, ViewElementConsumables as _ViewElementConversionConsumables, autoParagraphEmptyRoots as _autoParagraphEmptyModelRoots, convertMapToStringifiedObject as _convertMapToStringifiedObject, convertMapToTags as _convertMapToTags, deleteContent as _deleteModelContent, cleanSelection as _downcastCleanSelection, convertCollapsedSelection as _downcastConvertCollapsedSelection, convertRangeSelection as _downcastConvertRangeSelection, createViewElementFromDowncastHighlightDescriptor as _downcastCreateViewElementFromDowncastHighlightDescriptor, insertAttributesAndChildren as _downcastInsertAttributesAndChildren, insertElement as _downcastInsertElement, insertStructure as _downcastInsertStructure, insertText as _downcastInsertText, insertUIElement as _downcastInsertUIElement, remove as _downcastRemove, wrap as _downcastWrap, dumpTrees as _dumpTrees, getDataWithoutFiller as _getDataWithoutViewFiller, _getModelData, getNodeAfterPosition as _getModelNodeAfterPosition, getNodeBeforePosition as _getModelNodeBeforePosition, getTextNodeAtPosition as _getModelTextNodeAtPosition, getSelectedContent as _getSelectedModelContent, _getViewData, initDocumentDumping as _initDocumentDumping, injectSelectionPostFixer as _injectModelSelectionPostFixer, injectQuirksHandling as _injectViewQuirksHandling, injectUiElementHandling as _injectViewUIElementHandling, _insert as _insertIntoModelNodeList, insertContent as _insertModelContent, insertObject as _insertModelObject, isInlineFiller as _isInlineViewFiller, isParagraphable as _isParagraphableModelNode, isPatternMatched as _isViewPatternMatched, logDocument as _logDocument, mergeIntersectingRanges as _mergeIntersectingModelRanges, modifySelection as _modifyModelSelection, _move as _moveInModelNodeList, normalizeConsumables as _normalizeConversionConsumables, _normalizeNodes as _normalizeInModelNodeList, transform$1 as _operationTransform, _parseModel, _parseView, _remove as _removeFromModelNodeList, _setAttribute as _setAttributeInModelNodeList, _setModelData, _setViewData, startsWithFiller as _startsWithViewFiller, _stringifyModel, _stringifyView, tryFixingRange as _tryFixingModelRange, convertSelectionChange as _upcastConvertSelectionChange, convertText as _upcastConvertText, convertToModelFragment$1 as _upcastConvertToModelFragment, wrapInParagraph as _wrapInModelParagraph, addBackgroundStylesRules, addBorderStylesRules, addMarginStylesRules, addPaddingStylesRules, autoParagraphEmptyRoots, disableViewPlaceholder, enableViewPlaceholder, getBoxSidesStyleShorthandValue, getBoxSidesStyleValueReducer, getBoxSidesStyleValues, getPositionStyleShorthandNormalizer, getShorthandStylesValues, getViewFillerOffset, hideViewPlaceholder, isAttachmentStyleValue, isColorStyleValue, isLengthStyleValue, isLineStyleValue, isParagraphable, isPercentageStyleValue, isPositionStyleValue, isRepeatStyleValue, isURLStyleValue, needsViewPlaceholder, showViewPlaceholder, transformOperationSets, wrapInParagraph };
+export { AttributeOperation, Batch, BubblingEmitterMixin, BubblingEventInfo, ClickObserver, CompositionObserver, Conversion, ConversionHelpers, DataController, Differ, DomEventObserver, DowncastHelpers, EditingController, EditingView, FakeSelectionObserver, FocusObserver, History, HtmlDataProcessor, InputObserver, InsertOperation, KeyObserver, Mapper, MarkerCollection, MarkerOperation, Matcher, MergeOperation, Model, ModelDocument, ModelDocumentFragment, ModelDocumentSelection, ModelElement, ModelLivePosition, ModelLiveRange, ModelNode, ModelNodeList, ModelPosition, ModelRange, ModelRootElement, ModelSchema, ModelSchemaContext, ModelSelection, ModelText, ModelTextProxy, ModelTreeWalker, ModelTypeCheckable, ModelWriter, MouseObserver, MoveOperation, MutationObserver, NoOperation, Observer, OperationFactory, PointerObserver, RenameOperation, RootAttributeOperation, RootOperation, SelectionObserver, SplitOperation, StylesMap, StylesProcessor, TabObserver, TouchObserver, UpcastHelpers, ViewUpcastWriter as UpcastWriter, ViewAttributeElement, ViewContainerElement, ViewDataTransfer, ViewDocument, ViewDocumentDomEventData, ViewDocumentFragment, ViewDocumentSelection, ViewDomConverter, ViewDowncastWriter, ViewEditableElement, ViewElement, ViewEmptyElement, ViewNode, ViewPosition, ViewRange, ViewRawElement, ViewRenderer, ViewRootEditableElement, ViewSelection, ViewText, ViewTextProxy, ViewTokenList, ViewTreeWalker, ViewTypeCheckable, ViewUIElement, ViewUpcastWriter, XmlDataProcessor, BasicHtmlWriter as _DataProcessorBasicHtmlWriter, DetachOperation as _DetachOperation, MapperCache as _MapperCache, OperationReplayer as _OperationReplayer, BR_FILLER as _VIEW_BR_FILLER, INLINE_FILLER as _VIEW_INLINE_FILLER, INLINE_FILLER_LENGTH as _VIEW_INLINE_FILLER_LENGTH, MARKED_NBSP_FILLER as _VIEW_MARKED_NBSP_FILLER, NBSP_FILLER as _VIEW_NBSP_FILLER, ViewElementConsumables as _ViewElementConversionConsumables, autoParagraphEmptyRoots as _autoParagraphEmptyModelRoots, convertMapToStringifiedObject as _convertMapToStringifiedObject, convertMapToTags as _convertMapToTags, deleteContent as _deleteModelContent, cleanSelection as _downcastCleanSelection, convertCollapsedSelection as _downcastConvertCollapsedSelection, convertRangeSelection as _downcastConvertRangeSelection, createViewElementFromDowncastHighlightDescriptor as _downcastCreateViewElementFromDowncastHighlightDescriptor, insertAttributesAndChildren as _downcastInsertAttributesAndChildren, insertElement as _downcastInsertElement, insertStructure as _downcastInsertStructure, insertText as _downcastInsertText, insertUIElement as _downcastInsertUIElement, remove as _downcastRemove, wrap as _downcastWrap, dumpTrees as _dumpTrees, getDataWithoutFiller as _getDataWithoutViewFiller, _getModelData, getNodeAfterPosition as _getModelNodeAfterPosition, getNodeBeforePosition as _getModelNodeBeforePosition, getTextNodeAtPosition as _getModelTextNodeAtPosition, getSelectedContent as _getSelectedModelContent, _getViewData, initDocumentDumping as _initDocumentDumping, injectSelectionPostFixer as _injectModelSelectionPostFixer, injectQuirksHandling as _injectViewQuirksHandling, injectUiElementHandling as _injectViewUIElementHandling, _insert as _insertIntoModelNodeList, insertContent as _insertModelContent, insertObject as _insertModelObject, isInlineFiller as _isInlineViewFiller, isParagraphable as _isParagraphableModelNode, isPatternMatched as _isViewPatternMatched, logDocument as _logDocument, mergeIntersectingRanges as _mergeIntersectingModelRanges, modifySelection as _modifyModelSelection, _move as _moveInModelNodeList, normalizeConsumables as _normalizeConversionConsumables, _normalizeNodes as _normalizeInModelNodeList, transform$1 as _operationTransform, _parseModel, _parseView, _remove as _removeFromModelNodeList, _setAttribute as _setAttributeInModelNodeList, _setModelData, _setViewData, startsWithFiller as _startsWithViewFiller, _stringifyModel, _stringifyView, tryFixingRange as _tryFixingModelRange, convertSelectionChange as _upcastConvertSelectionChange, convertText as _upcastConvertText, convertToModelFragment$1 as _upcastConvertToModelFragment, wrapInParagraph as _wrapInModelParagraph, addBackgroundStylesRules, addBorderStylesRules, addMarginStylesRules, addPaddingStylesRules, disableViewPlaceholder, enableViewPlaceholder, getBoxSidesStyleShorthandValue, getBoxSidesStyleValueReducer, getBoxSidesStyleValues, getPositionStyleShorthandNormalizer, getShorthandStylesValues, getViewFillerOffset, hideViewPlaceholder, isAttachmentStyleValue, isColorStyleValue, isLengthStyleValue, isLineStyleValue, isPercentageStyleValue, isPositionStyleValue, isRepeatStyleValue, isURLStyleValue, needsViewPlaceholder, showViewPlaceholder, transformOperationSets };
 //# sourceMappingURL=index.js.map