@ckeditor/ckeditor5-engine 44.2.1 → 44.3.0-alpha.0

package/src/view/element.d.ts

@@ -7,8 +7,8 @@
  */
 import Node from './node.js';
 import { type ArrayOrItem } from '@ckeditor/ckeditor5-utils';
-import { type MatcherPattern } from './matcher.js';
-import { type StyleValue } from './stylesmap.js';
+import { type MatcherPattern, type NormalizedPropertyPattern } from './matcher.js';
+import { type Styles, type StyleValue } from './stylesmap.js';
 import type Document from './document.js';
 import type Item from './item.js';
 /**
@@ -60,18 +60,22 @@ export default class Element extends Node {
      */
     private readonly _children;
     /**
-     * Set of classes associated with element instance.
+     * Map of custom properties.
+     * Custom properties can be added to element instance, will be cloned but not rendered into DOM.
      */
-    private readonly _classes;
+    private readonly _customProperties;
     /**
-     * Normalized styles.
+     * Set of classes associated with element instance.
+     *
+     * Note that this is just an alias for `this._attrs.get( 'class' );`
      */
-    private readonly _styles;
+    private get _classes();
     /**
-     * Map of custom properties.
-     * Custom properties can be added to element instance, will be cloned but not rendered into DOM.
+     * Normalized styles.
+     *
+     * Note that this is just an alias for `this._attrs.get( 'style' );`
      */
-    private readonly _customProperties;
+    private get _styles();
     /**
      * Creates a view element.
      *
@@ -144,7 +148,7 @@ export default class Element extends Node {
      * @param key Attribute key.
      * @returns `true` if attribute with the specified key exists in the element, `false` otherwise.
      */
-    hasAttribute(key: string): boolean;
+    hasAttribute(key: string, token?: string): boolean;
     /**
      * Checks if this element is similar to other element.
      * Both elements should have the same name and attributes to be considered as similar. Two similar elements
@@ -164,9 +168,9 @@ export default class Element extends Node {
     /**
      * Returns iterator that contains all class names.
      */
-    getClassNames(): Iterable<string>;
+    getClassNames(): IterableIterator<string>;
     /**
-     * Returns style value for the given property mae.
+     * Returns style value for the given property name.
      * If the style does not exist `undefined` is returned.
      *
      * **Note**: This method can work with normalized style names if
@@ -225,13 +229,13 @@ export default class Element extends Node {
      *
      * @param property Name of CSS property
      */
-    getNormalizedStyle(property: string): StyleValue;
+    getNormalizedStyle(property: string): StyleValue | undefined;
     /**
-     * Returns iterator that contains all style names.
+     * Returns an array that contains all style names.
      *
      * @param expand Expand shorthand style properties and return all equivalent style representations.
      */
-    getStyleNames(expand?: boolean): Iterable<string>;
+    getStyleNames(expand?: boolean): Array<string>;
     /**
      * Returns true if style keys are present.
      * If more then one style property is provided - returns true only when all properties are present.
@@ -345,19 +349,21 @@ export default class Element extends Node {
      * @internal
      * @param key Attribute key.
      * @param value Attribute value.
+     * @param overwrite Whether tokenized attribute should override the attribute value or just add a token.
      * @fires change
      */
-    _setAttribute(key: string, value: unknown): void;
+    _setAttribute(key: string, value: unknown, overwrite?: boolean): void;
     /**
      * Removes attribute from the element.
      *
      * @see module:engine/view/downcastwriter~DowncastWriter#removeAttribute
      * @internal
      * @param key Attribute key.
+     * @param tokens Attribute value tokens to remove. The whole attribute is removed if not specified.
      * @returns Returns true if an attribute existed and has been removed.
      * @fires change
      */
-    _removeAttribute(key: string): boolean;
+    _removeAttribute(key: string, tokens?: ArrayOrItem<string>): boolean;
     /**
      * Adds specified class.
      *
@@ -441,6 +447,150 @@ export default class Element extends Node {
      * @fires change
      */
     _removeStyle(property: ArrayOrItem<string>): void;
+    /**
+     * Used by the {@link module:engine/view/matcher~Matcher Matcher} to collect matching attribute tuples
+     * (attribute name and optional token).
+     *
+     * Normalized patterns can be used in following ways:
+     * - to match any attribute name with any or no value:
+     *
+     * ```ts
+     * patterns: [
+     * 	[ true, true ]
+     * ]
+     * ```
+     *
+     * - to match a specific attribute with any value:
+     *
+     * ```ts
+     * patterns: [
+     * 	[ 'required', true ]
+     * ]
+     * ```
+     *
+     * - to match an attribute name with a RegExp with any value:
+     *
+     * ```ts
+     * patterns: [
+     * 	[ /h[1-6]/, true ]
+     * ]
+     * ```
+     *
+     * 	- to match a specific attribute with the exact value:
+     *
+     * ```ts
+     * patterns: [
+     * 	[ 'rel', 'nofollow' ]
+     * ]
+     * ```
+     *
+     * 	- to match a specific attribute with a value matching a RegExp:
+     *
+     * ```ts
+     * patterns: [
+     * 	[ 'src', /^https/ ]
+     * ]
+     * ```
+     *
+     * 	- to match an attribute name with a RegExp and the exact value:
+     *
+     * ```ts
+     * patterns: [
+     * 	[ /^data-property-/, 'foobar' ],
+     * ]
+     * ```
+     *
+     * 	- to match an attribute name with a RegExp and match a value with another RegExp:
+     *
+     * ```ts
+     * patterns: [
+     * 	[ /^data-property-/, /^foo/ ]
+     * ]
+     * ```
+     *
+     * 	- to match a specific style property with the value matching a RegExp:
+     *
+     * ```ts
+     * patterns: [
+     * 	[ 'style', 'font-size', /px$/ ]
+     * ]
+     * ```
+     *
+     * 	- to match a specific class (class attribute is tokenized so it matches tokens individually):
+     *
+     * ```ts
+     * patterns: [
+     * 	[ 'class', 'foo' ]
+     * ]
+     * ```
+     *
+     * @internal
+     * @param patterns An array of normalized patterns (tuples of 2 or 3 items depending on if tokenized attribute value match is needed).
+     * @param match An array to populate with matching tuples.
+     * @param exclude Array of attribute names to exclude from match.
+     * @returns `true` if element matches all patterns. The matching tuples are pushed to the `match` array.
+     */
+    _collectAttributesMatch(patterns: Array<NormalizedPropertyPattern>, match: Array<[string, string?]>, exclude?: Array<string>): boolean;
+    /**
+     * Used by the {@link module:engine/conversion/viewconsumable~ViewConsumable} to collect the
+     * {@link module:engine/view/element~NormalizedConsumables} for the element.
+     *
+     * When `key` and `token` parameters are provided the output is filtered for the specified attribute and it's tokens and related tokens.
+     *
+     * @internal
+     * @param key Attribute name.
+     * @param token Reference token to collect all related tokens.
+     */
+    _getConsumables(key?: string, token?: string): NormalizedConsumables;
+    /**
+     * Verify if the given element can be merged without conflicts into the element.
+     *
+     * Note that this method is extended by the {@link module:engine/view/attributeelement~AttributeElement} implementation.
+     *
+     * This method is used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to merge it with other AttributeElement.
+     *
+     * @internal
+     * @returns Returns `true` if elements can be merged.
+     */
+    _canMergeAttributesFrom(otherElement: Element): boolean;
+    /**
+     * Merges attributes of a given element into the element.
+     * This includes also tokenized attributes like style and class.
+     *
+     * Note that you should make sure there are no conflicts before merging (see {@link #_canMergeAttributesFrom}).
+     *
+     * This method is used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to merge it with other AttributeElement.
+     *
+     * @internal
+     */
+    _mergeAttributesFrom(otherElement: Element): void;
+    /**
+     * Verify if the given element attributes can be fully subtracted from the element.
+     *
+     * Note that this method is extended by the {@link module:engine/view/attributeelement~AttributeElement} implementation.
+     *
+     * This method is used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to unwrap the AttributeElement.
+     *
+     * @internal
+     * @returns Returns `true` if elements attributes can be fully subtracted.
+     */
+    _canSubtractAttributesOf(otherElement: Element): boolean;
+    /**
+     * Removes (subtracts) corresponding attributes of the given element from the element.
+     * This includes also tokenized attributes like style and class.
+     * All attributes, classes and styles from given element should be present inside the element being unwrapped.
+     *
+     * Note that you should make sure all attributes could be subtracted before subtracting them (see {@link #_canSubtractAttributesOf}).
+     *
+     * This method is used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to unwrap the AttributeElement.
+     *
+     * @internal
+     */
+    _subtractAttributesOf(otherElement: Element): void;
     /**
      * Sets a custom property. Unlike attributes, custom properties are not rendered to the DOM,
      * so they can be used to add special data to elements.
@@ -457,12 +607,154 @@ export default class Element extends Node {
      * @returns Returns true if property was removed.
      */
     _removeCustomProperty(key: string | symbol): boolean;
+    /**
+     * Parses attributes provided to the element constructor before they are applied to an element. If attributes are passed
+     * as an object (instead of `Iterable`), the object is transformed to the map. Attributes with `null` value are removed.
+     * Attributes with non-`String` value are converted to `String`.
+     *
+     * @param attrs Attributes to parse.
+     * @returns Parsed attributes.
+     */
+    private _parseAttributes;
     /**
      * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
      */
     getFillerOffset?(): number | null;
 }
+/**
+ * Common interface for a {@link module:engine/view/tokenlist~TokenList} and {@link module:engine/view/stylesmap~StylesMap}.
+ */
+export interface ElementAttributeValue {
+    /**
+     * Returns `true` if attribute has no value set.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Number of tokens (styles, classes or other tokens) defined.
+     */
+    get size(): number;
+    /**
+     * Checks if a given token (style, class, token) is set.
+     */
+    has(name: string): boolean;
+    /**
+     * Returns all tokens (styles, classes, other tokens).
+     */
+    keys(): Array<string>;
+    /**
+     * Resets the value to the given one.
+     */
+    setTo(value: string): this;
+    /**
+     * Sets a given style property and value.
+     */
+    set(name: string, value: StyleValue): void;
+    /**
+     * Sets a given token (for style also a record of properties).
+     */
+    set(stylesOrTokens: Styles | ArrayOrItem<string>): void;
+    /**
+     * Removes given token (style, class, other token).
+     */
+    remove(tokens: ArrayOrItem<string>): void;
+    /**
+     * Removes all tokens.
+     */
+    clear(): void;
+    /**
+     * Returns a normalized tokens string (styles, classes, etc.).
+     */
+    toString(): string;
+    /**
+     * Returns `true` if both attributes have the same content.
+     */
+    isSimilar(other: this): boolean;
+    /**
+     * Clones the attribute value.
+     */
+    _clone(): this;
+    /**
+     * Used by the {@link module:engine/view/matcher~Matcher Matcher} to collect matching attribute tokens.
+     *
+     * @param tokenPattern The matched token name pattern.
+     * @param valuePattern The matched token value pattern.
+     * @returns An array of matching tokens.
+     */
+    _getTokensMatch(tokenPattern: true | string | RegExp, valuePattern?: true | string | RegExp): Array<string> | undefined;
+    /**
+     * Returns a list of consumables for the attribute. This includes related tokens
+     * (for example other forms of notation of the same style property).
+     *
+     * Could be filtered by the given token name (class name, style property, etc.).
+     */
+    _getConsumables(name?: string): Array<string>;
+    /**
+     * Used by {@link ~Element#_canMergeAttributesFrom} to verify if the given attribute can be merged without conflicts into the attribute.
+     *
+     * This method is indirectly used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to merge it with other AttributeElement.
+     */
+    _canMergeFrom(other: this): boolean;
+    /**
+     * Used by {@link ~Element#_mergeAttributesFrom} to merge a given attribute into the attribute.
+     *
+     * This method is indirectly used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to merge it with other AttributeElement.
+     */
+    _mergeFrom(other: this): void;
+    /**
+     * Used by {@link ~Element#_canSubtractAttributesOf} to verify if the given attribute can be fully subtracted from the attribute.
+     *
+     * This method is indirectly used by the {@link module:engine/view/downcastwriter~DowncastWriter} while down-casting
+     * an {@link module:engine/view/attributeelement~AttributeElement} to unwrap the AttributeElement.
+     */
+    _isMatching(other: this): boolean;
+}
 /**
  * Collection of attributes.
  */
 export type ElementAttributes = Record<string, unknown> | Iterable<[string, unknown]> | null;
+/**
+ * Object describing all features of a view element that could be consumed and converted individually.
+ * This is a normalized form of {@link module:engine/conversion/viewconsumable~Consumables} generated from the view Element.
+ *
+ * Example element:
+ *
+ * ```html
+ * <a class="foo bar" style="color: red; margin: 5px" href="https://ckeditor.com" rel="nofollow noreferrer" target="_blank">
+ * ```
+ *
+ * The `NormalizedConsumables` would include:
+ *
+ * ```json
+ * {
+ * 	name: true,
+ * 	attributes: [
+ * 		[ "class", "foo" ],
+ * 		[ "class", "bar" ],
+ * 		[ "style", "color" ],
+ * 		[ "style", "margin-top" ],
+ * 		[ "style", "margin-right" ],
+ * 		[ "style", "margin-bottom" ],
+ * 		[ "style", "margin-left" ],
+        [ "style", "margin" ],
+ * 		[ "href" ],
+ * 		[ "rel", "nofollow" ],
+ * 		[ "rel", "noreferrer" ],
+ * 		[ "target" ]
+ * 	]
+ * }
+ * ```
+ */
+export interface NormalizedConsumables {
+    /**
+     * If set to `true` element's name will be included in a consumable.
+     * Depending on the usage context it would be added as consumable, tested for being available for consume or consumed.
+     */
+    name: boolean;
+    /**
+     * Array of tuples - an attribute name, and optional token for tokenized attributes.
+     * Note that there could be multiple entries for the same attribute with different tokens (class names or style properties).
+     */
+    attributes: Array<[string, string?]>;
+}