@ckeditor/ckeditor5-engine 34.2.0 → 35.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/CHANGELOG.md +823 -0
  2. package/LICENSE.md +4 -0
  3. package/package.json +32 -25
  4. package/src/controller/datacontroller.js +467 -561
  5. package/src/controller/editingcontroller.js +168 -204
  6. package/src/conversion/conversion.js +541 -565
  7. package/src/conversion/conversionhelpers.js +24 -28
  8. package/src/conversion/downcastdispatcher.js +457 -686
  9. package/src/conversion/downcasthelpers.js +1583 -1965
  10. package/src/conversion/mapper.js +518 -707
  11. package/src/conversion/modelconsumable.js +240 -283
  12. package/src/conversion/upcastdispatcher.js +372 -718
  13. package/src/conversion/upcasthelpers.js +707 -818
  14. package/src/conversion/viewconsumable.js +524 -581
  15. package/src/dataprocessor/basichtmlwriter.js +12 -16
  16. package/src/dataprocessor/dataprocessor.js +5 -0
  17. package/src/dataprocessor/htmldataprocessor.js +101 -117
  18. package/src/dataprocessor/htmlwriter.js +1 -18
  19. package/src/dataprocessor/xmldataprocessor.js +117 -138
  20. package/src/dev-utils/model.js +260 -352
  21. package/src/dev-utils/operationreplayer.js +106 -126
  22. package/src/dev-utils/utils.js +34 -51
  23. package/src/dev-utils/view.js +632 -753
  24. package/src/index.js +0 -11
  25. package/src/model/batch.js +111 -127
  26. package/src/model/differ.js +988 -1233
  27. package/src/model/document.js +340 -449
  28. package/src/model/documentfragment.js +327 -364
  29. package/src/model/documentselection.js +996 -1189
  30. package/src/model/element.js +306 -410
  31. package/src/model/history.js +224 -262
  32. package/src/model/item.js +5 -0
  33. package/src/model/liveposition.js +84 -145
  34. package/src/model/liverange.js +108 -185
  35. package/src/model/markercollection.js +379 -480
  36. package/src/model/model.js +883 -1034
  37. package/src/model/node.js +419 -463
  38. package/src/model/nodelist.js +175 -201
  39. package/src/model/operation/attributeoperation.js +153 -182
  40. package/src/model/operation/detachoperation.js +64 -83
  41. package/src/model/operation/insertoperation.js +135 -166
  42. package/src/model/operation/markeroperation.js +114 -140
  43. package/src/model/operation/mergeoperation.js +163 -191
  44. package/src/model/operation/moveoperation.js +157 -187
  45. package/src/model/operation/nooperation.js +28 -38
  46. package/src/model/operation/operation.js +106 -125
  47. package/src/model/operation/operationfactory.js +30 -34
  48. package/src/model/operation/renameoperation.js +109 -135
  49. package/src/model/operation/rootattributeoperation.js +155 -188
  50. package/src/model/operation/splitoperation.js +196 -232
  51. package/src/model/operation/transform.js +1833 -2204
  52. package/src/model/operation/utils.js +140 -204
  53. package/src/model/position.js +899 -1053
  54. package/src/model/range.js +910 -1028
  55. package/src/model/rootelement.js +77 -97
  56. package/src/model/schema.js +1189 -1835
  57. package/src/model/selection.js +745 -862
  58. package/src/model/text.js +90 -114
  59. package/src/model/textproxy.js +204 -240
  60. package/src/model/treewalker.js +316 -397
  61. package/src/model/typecheckable.js +16 -0
  62. package/src/model/utils/autoparagraphing.js +32 -44
  63. package/src/model/utils/deletecontent.js +334 -418
  64. package/src/model/utils/findoptimalinsertionrange.js +25 -36
  65. package/src/model/utils/getselectedcontent.js +96 -118
  66. package/src/model/utils/insertcontent.js +654 -773
  67. package/src/model/utils/insertobject.js +96 -119
  68. package/src/model/utils/modifyselection.js +120 -158
  69. package/src/model/utils/selection-post-fixer.js +153 -201
  70. package/src/model/writer.js +1305 -1474
  71. package/src/view/attributeelement.js +189 -225
  72. package/src/view/containerelement.js +75 -85
  73. package/src/view/document.js +172 -215
  74. package/src/view/documentfragment.js +200 -249
  75. package/src/view/documentselection.js +338 -367
  76. package/src/view/domconverter.js +1371 -1613
  77. package/src/view/downcastwriter.js +1747 -2076
  78. package/src/view/editableelement.js +81 -97
  79. package/src/view/element.js +739 -890
  80. package/src/view/elementdefinition.js +5 -0
  81. package/src/view/emptyelement.js +82 -92
  82. package/src/view/filler.js +35 -50
  83. package/src/view/item.js +5 -0
  84. package/src/view/matcher.js +260 -559
  85. package/src/view/node.js +274 -360
  86. package/src/view/observer/arrowkeysobserver.js +19 -28
  87. package/src/view/observer/bubblingemittermixin.js +120 -263
  88. package/src/view/observer/bubblingeventinfo.js +47 -55
  89. package/src/view/observer/clickobserver.js +7 -13
  90. package/src/view/observer/compositionobserver.js +14 -24
  91. package/src/view/observer/domeventdata.js +57 -67
  92. package/src/view/observer/domeventobserver.js +40 -64
  93. package/src/view/observer/fakeselectionobserver.js +81 -96
  94. package/src/view/observer/focusobserver.js +45 -61
  95. package/src/view/observer/inputobserver.js +7 -13
  96. package/src/view/observer/keyobserver.js +17 -27
  97. package/src/view/observer/mouseobserver.js +7 -14
  98. package/src/view/observer/mutationobserver.js +220 -315
  99. package/src/view/observer/observer.js +81 -102
  100. package/src/view/observer/selectionobserver.js +191 -246
  101. package/src/view/observer/tabobserver.js +23 -36
  102. package/src/view/placeholder.js +128 -173
  103. package/src/view/position.js +350 -401
  104. package/src/view/range.js +453 -513
  105. package/src/view/rawelement.js +85 -112
  106. package/src/view/renderer.js +874 -1014
  107. package/src/view/rooteditableelement.js +80 -90
  108. package/src/view/selection.js +608 -689
  109. package/src/view/styles/background.js +43 -44
  110. package/src/view/styles/border.js +220 -276
  111. package/src/view/styles/margin.js +8 -17
  112. package/src/view/styles/padding.js +8 -16
  113. package/src/view/styles/utils.js +127 -160
  114. package/src/view/stylesmap.js +728 -905
  115. package/src/view/text.js +102 -126
  116. package/src/view/textproxy.js +144 -170
  117. package/src/view/treewalker.js +383 -479
  118. package/src/view/typecheckable.js +19 -0
  119. package/src/view/uielement.js +166 -187
  120. package/src/view/upcastwriter.js +395 -449
  121. package/src/view/view.js +569 -664
  122. package/src/dataprocessor/dataprocessor.jsdoc +0 -64
  123. package/src/model/item.jsdoc +0 -14
  124. package/src/view/elementdefinition.jsdoc +0 -59
  125. package/src/view/item.jsdoc +0 -14
@@ -2,22 +2,19 @@
2
2
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
3
3
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
4
4
  */
5
-
6
5
  /**
7
6
  * @module engine/view/element
8
7
  */
9
-
10
8
  import Node from './node';
11
9
  import Text from './text';
12
10
  import TextProxy from './textproxy';
13
11
  import toMap from '@ckeditor/ckeditor5-utils/src/tomap';
14
12
  import toArray from '@ckeditor/ckeditor5-utils/src/toarray';
15
13
  import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
16
- import Matcher from './matcher';
17
- import StylesMap from './stylesmap';
18
-
14
+ import { default as Matcher } from './matcher';
15
+ import { default as StylesMap } from './stylesmap';
16
+ import { isPlainObject } from 'lodash-es';
19
17
  // @if CK_DEBUG_ENGINE // const { convertMapToTags } = require( '../dev-utils/utils' );
20
-
21
18
  /**
22
19
  * View element.
23
20
  *
@@ -44,906 +41,758 @@ import StylesMap from './stylesmap';
44
41
  * @extends module:engine/view/node~Node
45
42
  */
46
43
  export default class Element extends Node {
47
- /**
48
- * Creates a view element.
49
- *
50
- * Attributes can be passed in various formats:
51
- *
52
- * new Element( viewDocument, 'div', { class: 'editor', contentEditable: 'true' } ); // object
53
- * new Element( viewDocument, 'div', [ [ 'class', 'editor' ], [ 'contentEditable', 'true' ] ] ); // map-like iterator
54
- * new Element( viewDocument, 'div', mapOfAttributes ); // map
55
- *
56
- * @protected
57
- * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
58
- * @param {String} name Node name.
59
- * @param {Object|Iterable} [attrs] Collection of attributes.
60
- * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
61
- * A list of nodes to be inserted into created element.
62
- */
63
- constructor( document, name, attrs, children ) {
64
- super( document );
65
-
66
- /**
67
- * Name of the element.
68
- *
69
- * @readonly
70
- * @member {String}
71
- */
72
- this.name = name;
73
-
74
- /**
75
- * Map of attributes, where attributes names are keys and attributes values are values.
76
- *
77
- * @protected
78
- * @member {Map} #_attrs
79
- */
80
- this._attrs = parseAttributes( attrs );
81
-
82
- /**
83
- * Array of child nodes.
84
- *
85
- * @protected
86
- * @member {Array.<module:engine/view/node~Node>}
87
- */
88
- this._children = [];
89
-
90
- if ( children ) {
91
- this._insertChild( 0, children );
92
- }
93
-
94
- /**
95
- * Set of classes associated with element instance.
96
- *
97
- * @protected
98
- * @member {Set}
99
- */
100
- this._classes = new Set();
101
-
102
- if ( this._attrs.has( 'class' ) ) {
103
- // Remove class attribute and handle it by class set.
104
- const classString = this._attrs.get( 'class' );
105
- parseClasses( this._classes, classString );
106
- this._attrs.delete( 'class' );
107
- }
108
-
109
- /**
110
- * Normalized styles.
111
- *
112
- * @protected
113
- * @member {module:engine/view/stylesmap~StylesMap} module:engine/view/element~Element#_styles
114
- */
115
- this._styles = new StylesMap( this.document.stylesProcessor );
116
-
117
- if ( this._attrs.has( 'style' ) ) {
118
- // Remove style attribute and handle it by styles map.
119
- this._styles.setTo( this._attrs.get( 'style' ) );
120
-
121
- this._attrs.delete( 'style' );
122
- }
123
-
124
- /**
125
- * Map of custom properties.
126
- * Custom properties can be added to element instance, will be cloned but not rendered into DOM.
127
- *
128
- * @protected
129
- * @member {Map}
130
- */
131
- this._customProperties = new Map();
132
-
133
- /**
134
- * A list of attribute names that should be rendered in the editing pipeline even though filtering mechanisms
135
- * implemented in the {@link module:engine/view/domconverter~DomConverter} (for instance,
136
- * {@link module:engine/view/domconverter~DomConverter#shouldRenderAttribute}) would filter them out.
137
- *
138
- * These attributes can be specified as an option when the element is created by
139
- * the {@link module:engine/view/downcastwriter~DowncastWriter}. To check whether an unsafe an attribute should
140
- * be permitted, use the {@link #shouldRenderUnsafeAttribute} method.
141
- *
142
- * @private
143
- * @readonly
144
- * @member {Array.<String>}
145
- */
146
- this._unsafeAttributesToRender = [];
147
- }
148
-
149
- /**
150
- * Number of element's children.
151
- *
152
- * @readonly
153
- * @type {Number}
154
- */
155
- get childCount() {
156
- return this._children.length;
157
- }
158
-
159
- /**
160
- * Is `true` if there are no nodes inside this element, `false` otherwise.
161
- *
162
- * @readonly
163
- * @type {Boolean}
164
- */
165
- get isEmpty() {
166
- return this._children.length === 0;
167
- }
168
-
169
- /**
170
- * Checks whether this object is of the given.
171
- *
172
- * element.is( 'element' ); // -> true
173
- * element.is( 'node' ); // -> true
174
- * element.is( 'view:element' ); // -> true
175
- * element.is( 'view:node' ); // -> true
176
- *
177
- * element.is( 'model:element' ); // -> false
178
- * element.is( 'documentSelection' ); // -> false
179
- *
180
- * Assuming that the object being checked is an element, you can also check its
181
- * {@link module:engine/view/element~Element#name name}:
182
- *
183
- * element.is( 'element', 'img' ); // -> true if this is an <img> element
184
- * text.is( 'element', 'img' ); -> false
185
- *
186
- * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
187
- *
188
- * @param {String} type Type to check.
189
- * @param {String} [name] Element name.
190
- * @returns {Boolean}
191
- */
192
- is( type, name = null ) {
193
- if ( !name ) {
194
- return type === 'element' || type === 'view:element' ||
195
- // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
196
- type === 'node' || type === 'view:node';
197
- } else {
198
- return name === this.name && ( type === 'element' || type === 'view:element' );
199
- }
200
- }
201
-
202
- /**
203
- * Gets child at the given index.
204
- *
205
- * @param {Number} index Index of child.
206
- * @returns {module:engine/view/node~Node} Child node.
207
- */
208
- getChild( index ) {
209
- return this._children[ index ];
210
- }
211
-
212
- /**
213
- * Gets index of the given child node. Returns `-1` if child node is not found.
214
- *
215
- * @param {module:engine/view/node~Node} node Child node.
216
- * @returns {Number} Index of the child node.
217
- */
218
- getChildIndex( node ) {
219
- return this._children.indexOf( node );
220
- }
221
-
222
- /**
223
- * Gets child nodes iterator.
224
- *
225
- * @returns {Iterable.<module:engine/view/node~Node>} Child nodes iterator.
226
- */
227
- getChildren() {
228
- return this._children[ Symbol.iterator ]();
229
- }
230
-
231
- /**
232
- * Returns an iterator that contains the keys for attributes. Order of inserting attributes is not preserved.
233
- *
234
- * @returns {Iterable.<String>} Keys for attributes.
235
- */
236
- * getAttributeKeys() {
237
- if ( this._classes.size > 0 ) {
238
- yield 'class';
239
- }
240
-
241
- if ( !this._styles.isEmpty ) {
242
- yield 'style';
243
- }
244
-
245
- yield* this._attrs.keys();
246
- }
247
-
248
- /**
249
- * Returns iterator that iterates over this element's attributes.
250
- *
251
- * Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value.
252
- * This format is accepted by native `Map` object and also can be passed in `Node` constructor.
253
- *
254
- * @returns {Iterable.<*>}
255
- */
256
- * getAttributes() {
257
- yield* this._attrs.entries();
258
-
259
- if ( this._classes.size > 0 ) {
260
- yield [ 'class', this.getAttribute( 'class' ) ];
261
- }
262
-
263
- if ( !this._styles.isEmpty ) {
264
- yield [ 'style', this.getAttribute( 'style' ) ];
265
- }
266
- }
267
-
268
- /**
269
- * Gets attribute by key. If attribute is not present - returns undefined.
270
- *
271
- * @param {String} key Attribute key.
272
- * @returns {String|undefined} Attribute value.
273
- */
274
- getAttribute( key ) {
275
- if ( key == 'class' ) {
276
- if ( this._classes.size > 0 ) {
277
- return [ ...this._classes ].join( ' ' );
278
- }
279
-
280
- return undefined;
281
- }
282
-
283
- if ( key == 'style' ) {
284
- const inlineStyle = this._styles.toString();
285
-
286
- return inlineStyle == '' ? undefined : inlineStyle;
287
- }
288
-
289
- return this._attrs.get( key );
290
- }
291
-
292
- /**
293
- * Returns a boolean indicating whether an attribute with the specified key exists in the element.
294
- *
295
- * @param {String} key Attribute key.
296
- * @returns {Boolean} `true` if attribute with the specified key exists in the element, false otherwise.
297
- */
298
- hasAttribute( key ) {
299
- if ( key == 'class' ) {
300
- return this._classes.size > 0;
301
- }
302
-
303
- if ( key == 'style' ) {
304
- return !this._styles.isEmpty;
305
- }
306
-
307
- return this._attrs.has( key );
308
- }
309
-
310
- /**
311
- * Checks if this element is similar to other element.
312
- * Both elements should have the same name and attributes to be considered as similar. Two similar elements
313
- * can contain different set of children nodes.
314
- *
315
- * @param {module:engine/view/element~Element} otherElement
316
- * @returns {Boolean}
317
- */
318
- isSimilar( otherElement ) {
319
- if ( !( otherElement instanceof Element ) ) {
320
- return false;
321
- }
322
-
323
- // If exactly the same Element is provided - return true immediately.
324
- if ( this === otherElement ) {
325
- return true;
326
- }
327
-
328
- // Check element name.
329
- if ( this.name != otherElement.name ) {
330
- return false;
331
- }
332
-
333
- // Check number of attributes, classes and styles.
334
- if ( this._attrs.size !== otherElement._attrs.size || this._classes.size !== otherElement._classes.size ||
335
- this._styles.size !== otherElement._styles.size ) {
336
- return false;
337
- }
338
-
339
- // Check if attributes are the same.
340
- for ( const [ key, value ] of this._attrs ) {
341
- if ( !otherElement._attrs.has( key ) || otherElement._attrs.get( key ) !== value ) {
342
- return false;
343
- }
344
- }
345
-
346
- // Check if classes are the same.
347
- for ( const className of this._classes ) {
348
- if ( !otherElement._classes.has( className ) ) {
349
- return false;
350
- }
351
- }
352
-
353
- // Check if styles are the same.
354
- for ( const property of this._styles.getStyleNames() ) {
355
- if (
356
- !otherElement._styles.has( property ) ||
357
- otherElement._styles.getAsString( property ) !== this._styles.getAsString( property )
358
- ) {
359
- return false;
360
- }
361
- }
362
-
363
- return true;
364
- }
365
-
366
- /**
367
- * Returns true if class is present.
368
- * If more then one class is provided - returns true only when all classes are present.
369
- *
370
- * element.hasClass( 'foo' ); // Returns true if 'foo' class is present.
371
- * element.hasClass( 'foo', 'bar' ); // Returns true if 'foo' and 'bar' classes are both present.
372
- *
373
- * @param {...String} className
374
- */
375
- hasClass( ...className ) {
376
- for ( const name of className ) {
377
- if ( !this._classes.has( name ) ) {
378
- return false;
379
- }
380
- }
381
-
382
- return true;
383
- }
384
-
385
- /**
386
- * Returns iterator that contains all class names.
387
- *
388
- * @returns {Iterable.<String>}
389
- */
390
- getClassNames() {
391
- return this._classes.keys();
392
- }
393
-
394
- /**
395
- * Returns style value for the given property mae.
396
- * If the style does not exist `undefined` is returned.
397
- *
398
- * **Note**: This method can work with normalized style names if
399
- * {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules a particular style processor rule is enabled}.
400
- * See {@link module:engine/view/stylesmap~StylesMap#getAsString `StylesMap#getAsString()`} for details.
401
- *
402
- * For an element with style set to `'margin:1px'`:
403
- *
404
- * // Enable 'margin' shorthand processing:
405
- * editor.data.addStyleProcessorRules( addMarginRules );
406
- *
407
- * const element = view.change( writer => {
408
- * const element = writer.createElement();
409
- * writer.setStyle( 'margin', '1px' );
410
- * writer.setStyle( 'margin-bottom', '3em' );
411
- *
412
- * return element;
413
- * } );
414
- *
415
- * element.getStyle( 'margin' ); // -> 'margin: 1px 1px 3em;'
416
- *
417
- * @param {String} property
418
- * @returns {String|undefined}
419
- */
420
- getStyle( property ) {
421
- return this._styles.getAsString( property );
422
- }
423
-
424
- /**
425
- * Returns a normalized style object or single style value.
426
- *
427
- * For an element with style set to: margin:1px 2px 3em;
428
- *
429
- * element.getNormalizedStyle( 'margin' ) );
430
- *
431
- * will return:
432
- *
433
- * {
434
- * top: '1px',
435
- * right: '2px',
436
- * bottom: '3em',
437
- * left: '2px' // a normalized value from margin shorthand
438
- * }
439
- *
440
- * and reading for single style value:
441
- *
442
- * styles.getNormalizedStyle( 'margin-left' );
443
- *
444
- * Will return a `2px` string.
445
- *
446
- * **Note**: This method will return normalized values only if
447
- * {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules a particular style processor rule is enabled}.
448
- * See {@link module:engine/view/stylesmap~StylesMap#getNormalized `StylesMap#getNormalized()`} for details.
449
- *
450
- *
451
- * @param {String} property Name of CSS property
452
- * @returns {Object|String|undefined}
453
- */
454
- getNormalizedStyle( property ) {
455
- return this._styles.getNormalized( property );
456
- }
457
-
458
- /**
459
- * Returns iterator that contains all style names.
460
- *
461
- * @param {Boolean} [expand=false] Expand shorthand style properties and return all equivalent style representations.
462
- * @returns {Iterable.<String>}
463
- */
464
- getStyleNames( expand = false ) {
465
- return this._styles.getStyleNames( expand );
466
- }
467
-
468
- /**
469
- * Returns true if style keys are present.
470
- * If more then one style property is provided - returns true only when all properties are present.
471
- *
472
- * element.hasStyle( 'color' ); // Returns true if 'border-top' style is present.
473
- * element.hasStyle( 'color', 'border-top' ); // Returns true if 'color' and 'border-top' styles are both present.
474
- *
475
- * @param {...String} property
476
- */
477
- hasStyle( ...property ) {
478
- for ( const name of property ) {
479
- if ( !this._styles.has( name ) ) {
480
- return false;
481
- }
482
- }
483
-
484
- return true;
485
- }
486
-
487
- /**
488
- * Returns ancestor element that match specified pattern.
489
- * Provided patterns should be compatible with {@link module:engine/view/matcher~Matcher Matcher} as it is used internally.
490
- *
491
- * @see module:engine/view/matcher~Matcher
492
- * @param {Object|String|RegExp|Function} patterns Patterns used to match correct ancestor.
493
- * See {@link module:engine/view/matcher~Matcher}.
494
- * @returns {module:engine/view/element~Element|null} Found element or `null` if no matching ancestor was found.
495
- */
496
- findAncestor( ...patterns ) {
497
- const matcher = new Matcher( ...patterns );
498
- let parent = this.parent;
499
-
500
- while ( parent ) {
501
- if ( matcher.match( parent ) ) {
502
- return parent;
503
- }
504
-
505
- parent = parent.parent;
506
- }
507
-
508
- return null;
509
- }
510
-
511
- /**
512
- * Returns the custom property value for the given key.
513
- *
514
- * @param {String|Symbol} key
515
- * @returns {*}
516
- */
517
- getCustomProperty( key ) {
518
- return this._customProperties.get( key );
519
- }
520
-
521
- /**
522
- * Returns an iterator which iterates over this element's custom properties.
523
- * Iterator provides `[ key, value ]` pairs for each stored property.
524
- *
525
- * @returns {Iterable.<*>}
526
- */
527
- * getCustomProperties() {
528
- yield* this._customProperties.entries();
529
- }
530
-
531
- /**
532
- * Returns identity string based on element's name, styles, classes and other attributes.
533
- * Two elements that {@link #isSimilar are similar} will have same identity string.
534
- * It has the following format:
535
- *
536
- * 'name class="class1,class2" style="style1:value1;style2:value2" attr1="val1" attr2="val2"'
537
- *
538
- * For example:
539
- *
540
- * const element = writer.createContainerElement( 'foo', {
541
- * banana: '10',
542
- * apple: '20',
543
- * style: 'color: red; border-color: white;',
544
- * class: 'baz'
545
- * } );
546
- *
547
- * // returns 'foo class="baz" style="border-color:white;color:red" apple="20" banana="10"'
548
- * element.getIdentity();
549
- *
550
- * **Note**: Classes, styles and other attributes are sorted alphabetically.
551
- *
552
- * @returns {String}
553
- */
554
- getIdentity() {
555
- const classes = Array.from( this._classes ).sort().join( ',' );
556
- const styles = this._styles.toString();
557
- const attributes = Array.from( this._attrs ).map( i => `${ i[ 0 ] }="${ i[ 1 ] }"` ).sort().join( ' ' );
558
-
559
- return this.name +
560
- ( classes == '' ? '' : ` class="${ classes }"` ) +
561
- ( !styles ? '' : ` style="${ styles }"` ) +
562
- ( attributes == '' ? '' : ` ${ attributes }` );
563
- }
564
-
565
- /**
566
- * Decides whether an unsafe attribute is whitelisted and should be rendered in the editing pipeline even though filtering mechanisms
567
- * like {@link module:engine/view/domconverter~DomConverter#shouldRenderAttribute} say it should not.
568
- *
569
- * Unsafe attribute names can be specified when creating an element via {@link module:engine/view/downcastwriter~DowncastWriter}.
570
- *
571
- * @param {String} attributeName The name of the attribute to be checked.
572
- * @returns {Boolean}
573
- */
574
- shouldRenderUnsafeAttribute( attributeName ) {
575
- return this._unsafeAttributesToRender.includes( attributeName );
576
- }
577
-
578
- /**
579
- * Clones provided element.
580
- *
581
- * @protected
582
- * @param {Boolean} [deep=false] If set to `true` clones element and all its children recursively. When set to `false`,
583
- * element will be cloned without any children.
584
- * @returns {module:engine/view/element~Element} Clone of this element.
585
- */
586
- _clone( deep = false ) {
587
- const childrenClone = [];
588
-
589
- if ( deep ) {
590
- for ( const child of this.getChildren() ) {
591
- childrenClone.push( child._clone( deep ) );
592
- }
593
- }
594
-
595
- // ContainerElement and AttributeElement should be also cloned properly.
596
- const cloned = new this.constructor( this.document, this.name, this._attrs, childrenClone );
597
-
598
- // Classes and styles are cloned separately - this solution is faster than adding them back to attributes and
599
- // parse once again in constructor.
600
- cloned._classes = new Set( this._classes );
601
- cloned._styles.set( this._styles.getNormalized() );
602
-
603
- // Clone custom properties.
604
- cloned._customProperties = new Map( this._customProperties );
605
-
606
- // Clone filler offset method.
607
- // We can't define this method in a prototype because it's behavior which
608
- // is changed by e.g. toWidget() function from ckeditor5-widget. Perhaps this should be one of custom props.
609
- cloned.getFillerOffset = this.getFillerOffset;
610
-
611
- // Clone unsafe attributes list.
612
- cloned._unsafeAttributesToRender = this._unsafeAttributesToRender;
613
-
614
- return cloned;
615
- }
616
-
617
- /**
618
- * {@link module:engine/view/element~Element#_insertChild Insert} a child node or a list of child nodes at the end of this node
619
- * and sets the parent of these nodes to this element.
620
- *
621
- * @see module:engine/view/downcastwriter~DowncastWriter#insert
622
- * @protected
623
- * @param {module:engine/view/item~Item|Iterable.<module:engine/view/item~Item>} items Items to be inserted.
624
- * @fires module:engine/view/node~Node#change
625
- * @returns {Number} Number of appended nodes.
626
- */
627
- _appendChild( items ) {
628
- return this._insertChild( this.childCount, items );
629
- }
630
-
631
- /**
632
- * Inserts a child node or a list of child nodes on the given index and sets the parent of these nodes to
633
- * this element.
634
- *
635
- * @see module:engine/view/downcastwriter~DowncastWriter#insert
636
- * @protected
637
- * @param {Number} index Position where nodes should be inserted.
638
- * @param {module:engine/view/item~Item|Iterable.<module:engine/view/item~Item>} items Items to be inserted.
639
- * @fires module:engine/view/node~Node#change
640
- * @returns {Number} Number of inserted nodes.
641
- */
642
- _insertChild( index, items ) {
643
- this._fireChange( 'children', this );
644
- let count = 0;
645
-
646
- const nodes = normalize( this.document, items );
647
-
648
- for ( const node of nodes ) {
649
- // If node that is being added to this element is already inside another element, first remove it from the old parent.
650
- if ( node.parent !== null ) {
651
- node._remove();
652
- }
653
-
654
- node.parent = this;
655
- node.document = this.document;
656
-
657
- this._children.splice( index, 0, node );
658
- index++;
659
- count++;
660
- }
661
-
662
- return count;
663
- }
664
-
665
- /**
666
- * Removes number of child nodes starting at the given index and set the parent of these nodes to `null`.
667
- *
668
- * @see module:engine/view/downcastwriter~DowncastWriter#remove
669
- * @protected
670
- * @param {Number} index Number of the first node to remove.
671
- * @param {Number} [howMany=1] Number of nodes to remove.
672
- * @fires module:engine/view/node~Node#change
673
- * @returns {Array.<module:engine/view/node~Node>} The array of removed nodes.
674
- */
675
- _removeChildren( index, howMany = 1 ) {
676
- this._fireChange( 'children', this );
677
-
678
- for ( let i = index; i < index + howMany; i++ ) {
679
- this._children[ i ].parent = null;
680
- }
681
-
682
- return this._children.splice( index, howMany );
683
- }
684
-
685
- /**
686
- * Adds or overwrite attribute with a specified key and value.
687
- *
688
- * @see module:engine/view/downcastwriter~DowncastWriter#setAttribute
689
- * @protected
690
- * @param {String} key Attribute key.
691
- * @param {String} value Attribute value.
692
- * @fires module:engine/view/node~Node#change
693
- */
694
- _setAttribute( key, value ) {
695
- value = String( value );
696
-
697
- this._fireChange( 'attributes', this );
698
-
699
- if ( key == 'class' ) {
700
- parseClasses( this._classes, value );
701
- } else if ( key == 'style' ) {
702
- this._styles.setTo( value );
703
- } else {
704
- this._attrs.set( key, value );
705
- }
706
- }
707
-
708
- /**
709
- * Removes attribute from the element.
710
- *
711
- * @see module:engine/view/downcastwriter~DowncastWriter#removeAttribute
712
- * @protected
713
- * @param {String} key Attribute key.
714
- * @returns {Boolean} Returns true if an attribute existed and has been removed.
715
- * @fires module:engine/view/node~Node#change
716
- */
717
- _removeAttribute( key ) {
718
- this._fireChange( 'attributes', this );
719
-
720
- // Remove class attribute.
721
- if ( key == 'class' ) {
722
- if ( this._classes.size > 0 ) {
723
- this._classes.clear();
724
-
725
- return true;
726
- }
727
-
728
- return false;
729
- }
730
-
731
- // Remove style attribute.
732
- if ( key == 'style' ) {
733
- if ( !this._styles.isEmpty ) {
734
- this._styles.clear();
735
-
736
- return true;
737
- }
738
-
739
- return false;
740
- }
741
-
742
- // Remove other attributes.
743
- return this._attrs.delete( key );
744
- }
745
-
746
- /**
747
- * Adds specified class.
748
- *
749
- * element._addClass( 'foo' ); // Adds 'foo' class.
750
- * element._addClass( [ 'foo', 'bar' ] ); // Adds 'foo' and 'bar' classes.
751
- *
752
- * @see module:engine/view/downcastwriter~DowncastWriter#addClass
753
- * @protected
754
- * @param {Array.<String>|String} className
755
- * @fires module:engine/view/node~Node#change
756
- */
757
- _addClass( className ) {
758
- this._fireChange( 'attributes', this );
759
-
760
- for ( const name of toArray( className ) ) {
761
- this._classes.add( name );
762
- }
763
- }
764
-
765
- /**
766
- * Removes specified class.
767
- *
768
- * element._removeClass( 'foo' ); // Removes 'foo' class.
769
- * element._removeClass( [ 'foo', 'bar' ] ); // Removes both 'foo' and 'bar' classes.
770
- *
771
- * @see module:engine/view/downcastwriter~DowncastWriter#removeClass
772
- * @protected
773
- * @param {Array.<String>|String} className
774
- * @fires module:engine/view/node~Node#change
775
- */
776
- _removeClass( className ) {
777
- this._fireChange( 'attributes', this );
778
-
779
- for ( const name of toArray( className ) ) {
780
- this._classes.delete( name );
781
- }
782
- }
783
-
784
- /**
785
- * Adds style to the element.
786
- *
787
- * element._setStyle( 'color', 'red' );
788
- * element._setStyle( {
789
- * color: 'red',
790
- * position: 'fixed'
791
- * } );
792
- *
793
- * **Note**: This method can work with normalized style names if
794
- * {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules a particular style processor rule is enabled}.
795
- * See {@link module:engine/view/stylesmap~StylesMap#set `StylesMap#set()`} for details.
796
- *
797
- * @see module:engine/view/downcastwriter~DowncastWriter#setStyle
798
- * @protected
799
- * @param {String|Object} property Property name or object with key - value pairs.
800
- * @param {String} [value] Value to set. This parameter is ignored if object is provided as the first parameter.
801
- * @fires module:engine/view/node~Node#change
802
- */
803
- _setStyle( property, value ) {
804
- this._fireChange( 'attributes', this );
805
-
806
- this._styles.set( property, value );
807
- }
808
-
809
- /**
810
- * Removes specified style.
811
- *
812
- * element._removeStyle( 'color' ); // Removes 'color' style.
813
- * element._removeStyle( [ 'color', 'border-top' ] ); // Removes both 'color' and 'border-top' styles.
814
- *
815
- * **Note**: This method can work with normalized style names if
816
- * {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules a particular style processor rule is enabled}.
817
- * See {@link module:engine/view/stylesmap~StylesMap#remove `StylesMap#remove()`} for details.
818
- *
819
- * @see module:engine/view/downcastwriter~DowncastWriter#removeStyle
820
- * @protected
821
- * @param {Array.<String>|String} property
822
- * @fires module:engine/view/node~Node#change
823
- */
824
- _removeStyle( property ) {
825
- this._fireChange( 'attributes', this );
826
-
827
- for ( const name of toArray( property ) ) {
828
- this._styles.remove( name );
829
- }
830
- }
831
-
832
- /**
833
- * Sets a custom property. Unlike attributes, custom properties are not rendered to the DOM,
834
- * so they can be used to add special data to elements.
835
- *
836
- * @see module:engine/view/downcastwriter~DowncastWriter#setCustomProperty
837
- * @protected
838
- * @param {String|Symbol} key
839
- * @param {*} value
840
- */
841
- _setCustomProperty( key, value ) {
842
- this._customProperties.set( key, value );
843
- }
844
-
845
- /**
846
- * Removes the custom property stored under the given key.
847
- *
848
- * @see module:engine/view/downcastwriter~DowncastWriter#removeCustomProperty
849
- * @protected
850
- * @param {String|Symbol} key
851
- * @returns {Boolean} Returns true if property was removed.
852
- */
853
- _removeCustomProperty( key ) {
854
- return this._customProperties.delete( key );
855
- }
856
-
857
- /**
858
- * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
859
- *
860
- * @abstract
861
- * @method module:engine/view/element~Element#getFillerOffset
862
- */
863
-
864
- // @if CK_DEBUG_ENGINE // printTree( level = 0) {
865
- // @if CK_DEBUG_ENGINE // let string = '';
866
-
867
- // @if CK_DEBUG_ENGINE // string += '\t'.repeat( level ) + `<${ this.name }${ convertMapToTags( this.getAttributes() ) }>`;
868
-
869
- // @if CK_DEBUG_ENGINE // for ( const child of this.getChildren() ) {
870
- // @if CK_DEBUG_ENGINE // if ( child.is( '$text' ) ) {
871
- // @if CK_DEBUG_ENGINE // string += '\n' + '\t'.repeat( level + 1 ) + child.data;
872
- // @if CK_DEBUG_ENGINE // } else {
873
- // @if CK_DEBUG_ENGINE // string += '\n' + child.printTree( level + 1 );
874
- // @if CK_DEBUG_ENGINE // }
875
- // @if CK_DEBUG_ENGINE // }
876
-
877
- // @if CK_DEBUG_ENGINE // if ( this.childCount ) {
878
- // @if CK_DEBUG_ENGINE // string += '\n' + '\t'.repeat( level );
879
- // @if CK_DEBUG_ENGINE // }
880
-
881
- // @if CK_DEBUG_ENGINE // string += `</${ this.name }>`;
882
-
883
- // @if CK_DEBUG_ENGINE // return string;
884
- // @if CK_DEBUG_ENGINE // }
885
-
886
- // @if CK_DEBUG_ENGINE // logTree() {
887
- // @if CK_DEBUG_ENGINE // console.log( this.printTree() );
888
- // @if CK_DEBUG_ENGINE // }
44
+ /**
45
+ * Creates a view element.
46
+ *
47
+ * Attributes can be passed in various formats:
48
+ *
49
+ * new Element( viewDocument, 'div', { class: 'editor', contentEditable: 'true' } ); // object
50
+ * new Element( viewDocument, 'div', [ [ 'class', 'editor' ], [ 'contentEditable', 'true' ] ] ); // map-like iterator
51
+ * new Element( viewDocument, 'div', mapOfAttributes ); // map
52
+ *
53
+ * @protected
54
+ * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
55
+ * @param {String} name Node name.
56
+ * @param {Object|Iterable} [attrs] Collection of attributes.
57
+ * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
58
+ * A list of nodes to be inserted into created element.
59
+ */
60
+ constructor(document, name, attrs, children) {
61
+ super(document);
62
+ /**
63
+ * Name of the element.
64
+ *
65
+ * @readonly
66
+ * @member {String}
67
+ */
68
+ this.name = name;
69
+ /**
70
+ * Map of attributes, where attributes names are keys and attributes values are values.
71
+ *
72
+ * @protected
73
+ * @member {Map} #_attrs
74
+ */
75
+ this._attrs = parseAttributes(attrs);
76
+ /**
77
+ * Array of child nodes.
78
+ *
79
+ * @protected
80
+ * @member {Array.<module:engine/view/node~Node>}
81
+ */
82
+ this._children = [];
83
+ if (children) {
84
+ this._insertChild(0, children);
85
+ }
86
+ /**
87
+ * Set of classes associated with element instance.
88
+ *
89
+ * @protected
90
+ * @member {Set}
91
+ */
92
+ this._classes = new Set();
93
+ if (this._attrs.has('class')) {
94
+ // Remove class attribute and handle it by class set.
95
+ const classString = this._attrs.get('class');
96
+ parseClasses(this._classes, classString);
97
+ this._attrs.delete('class');
98
+ }
99
+ /**
100
+ * Normalized styles.
101
+ *
102
+ * @protected
103
+ * @member {module:engine/view/stylesmap~StylesMap} module:engine/view/element~Element#_styles
104
+ */
105
+ this._styles = new StylesMap(this.document.stylesProcessor);
106
+ if (this._attrs.has('style')) {
107
+ // Remove style attribute and handle it by styles map.
108
+ this._styles.setTo(this._attrs.get('style'));
109
+ this._attrs.delete('style');
110
+ }
111
+ /**
112
+ * Map of custom properties.
113
+ * Custom properties can be added to element instance, will be cloned but not rendered into DOM.
114
+ *
115
+ * @protected
116
+ * @member {Map}
117
+ */
118
+ this._customProperties = new Map();
119
+ /**
120
+ * A list of attribute names that should be rendered in the editing pipeline even though filtering mechanisms
121
+ * implemented in the {@link module:engine/view/domconverter~DomConverter} (for instance,
122
+ * {@link module:engine/view/domconverter~DomConverter#shouldRenderAttribute}) would filter them out.
123
+ *
124
+ * These attributes can be specified as an option when the element is created by
125
+ * the {@link module:engine/view/downcastwriter~DowncastWriter}. To check whether an unsafe an attribute should
126
+ * be permitted, use the {@link #shouldRenderUnsafeAttribute} method.
127
+ *
128
+ * @private
129
+ * @readonly
130
+ * @member {Array.<String>}
131
+ */
132
+ this._unsafeAttributesToRender = [];
133
+ }
134
+ /**
135
+ * Number of element's children.
136
+ *
137
+ * @readonly
138
+ * @type {Number}
139
+ */
140
+ get childCount() {
141
+ return this._children.length;
142
+ }
143
+ /**
144
+ * Is `true` if there are no nodes inside this element, `false` otherwise.
145
+ *
146
+ * @readonly
147
+ * @type {Boolean}
148
+ */
149
+ get isEmpty() {
150
+ return this._children.length === 0;
151
+ }
152
+ /**
153
+ * Gets child at the given index.
154
+ *
155
+ * @param {Number} index Index of child.
156
+ * @returns {module:engine/view/node~Node} Child node.
157
+ */
158
+ getChild(index) {
159
+ return this._children[index];
160
+ }
161
+ /**
162
+ * Gets index of the given child node. Returns `-1` if child node is not found.
163
+ *
164
+ * @param {module:engine/view/node~Node} node Child node.
165
+ * @returns {Number} Index of the child node.
166
+ */
167
+ getChildIndex(node) {
168
+ return this._children.indexOf(node);
169
+ }
170
+ /**
171
+ * Gets child nodes iterator.
172
+ *
173
+ * @returns {Iterable.<module:engine/view/node~Node>} Child nodes iterator.
174
+ */
175
+ getChildren() {
176
+ return this._children[Symbol.iterator]();
177
+ }
178
+ /**
179
+ * Returns an iterator that contains the keys for attributes. Order of inserting attributes is not preserved.
180
+ *
181
+ * @returns {Iterable.<String>} Keys for attributes.
182
+ */
183
+ *getAttributeKeys() {
184
+ if (this._classes.size > 0) {
185
+ yield 'class';
186
+ }
187
+ if (!this._styles.isEmpty) {
188
+ yield 'style';
189
+ }
190
+ yield* this._attrs.keys();
191
+ }
192
+ /**
193
+ * Returns iterator that iterates over this element's attributes.
194
+ *
195
+ * Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value.
196
+ * This format is accepted by native `Map` object and also can be passed in `Node` constructor.
197
+ *
198
+ * @returns {Iterable.<*>}
199
+ */
200
+ *getAttributes() {
201
+ yield* this._attrs.entries();
202
+ if (this._classes.size > 0) {
203
+ yield ['class', this.getAttribute('class')];
204
+ }
205
+ if (!this._styles.isEmpty) {
206
+ yield ['style', this.getAttribute('style')];
207
+ }
208
+ }
209
+ /**
210
+ * Gets attribute by key. If attribute is not present - returns undefined.
211
+ *
212
+ * @param {String} key Attribute key.
213
+ * @returns {String|undefined} Attribute value.
214
+ */
215
+ getAttribute(key) {
216
+ if (key == 'class') {
217
+ if (this._classes.size > 0) {
218
+ return [...this._classes].join(' ');
219
+ }
220
+ return undefined;
221
+ }
222
+ if (key == 'style') {
223
+ const inlineStyle = this._styles.toString();
224
+ return inlineStyle == '' ? undefined : inlineStyle;
225
+ }
226
+ return this._attrs.get(key);
227
+ }
228
+ /**
229
+ * Returns a boolean indicating whether an attribute with the specified key exists in the element.
230
+ *
231
+ * @param {String} key Attribute key.
232
+ * @returns {Boolean} `true` if attribute with the specified key exists in the element, false otherwise.
233
+ */
234
+ hasAttribute(key) {
235
+ if (key == 'class') {
236
+ return this._classes.size > 0;
237
+ }
238
+ if (key == 'style') {
239
+ return !this._styles.isEmpty;
240
+ }
241
+ return this._attrs.has(key);
242
+ }
243
+ /**
244
+ * Checks if this element is similar to other element.
245
+ * Both elements should have the same name and attributes to be considered as similar. Two similar elements
246
+ * can contain different set of children nodes.
247
+ *
248
+ * @param {module:engine/view/element~Element} otherElement
249
+ * @returns {Boolean}
250
+ */
251
+ isSimilar(otherElement) {
252
+ if (!(otherElement instanceof Element)) {
253
+ return false;
254
+ }
255
+ // If exactly the same Element is provided - return true immediately.
256
+ if (this === otherElement) {
257
+ return true;
258
+ }
259
+ // Check element name.
260
+ if (this.name != otherElement.name) {
261
+ return false;
262
+ }
263
+ // Check number of attributes, classes and styles.
264
+ if (this._attrs.size !== otherElement._attrs.size || this._classes.size !== otherElement._classes.size ||
265
+ this._styles.size !== otherElement._styles.size) {
266
+ return false;
267
+ }
268
+ // Check if attributes are the same.
269
+ for (const [key, value] of this._attrs) {
270
+ if (!otherElement._attrs.has(key) || otherElement._attrs.get(key) !== value) {
271
+ return false;
272
+ }
273
+ }
274
+ // Check if classes are the same.
275
+ for (const className of this._classes) {
276
+ if (!otherElement._classes.has(className)) {
277
+ return false;
278
+ }
279
+ }
280
+ // Check if styles are the same.
281
+ for (const property of this._styles.getStyleNames()) {
282
+ if (!otherElement._styles.has(property) ||
283
+ otherElement._styles.getAsString(property) !== this._styles.getAsString(property)) {
284
+ return false;
285
+ }
286
+ }
287
+ return true;
288
+ }
289
+ /**
290
+ * Returns true if class is present.
291
+ * If more then one class is provided - returns true only when all classes are present.
292
+ *
293
+ * element.hasClass( 'foo' ); // Returns true if 'foo' class is present.
294
+ * element.hasClass( 'foo', 'bar' ); // Returns true if 'foo' and 'bar' classes are both present.
295
+ *
296
+ * @param {...String} className
297
+ */
298
+ hasClass(...className) {
299
+ for (const name of className) {
300
+ if (!this._classes.has(name)) {
301
+ return false;
302
+ }
303
+ }
304
+ return true;
305
+ }
306
+ /**
307
+ * Returns iterator that contains all class names.
308
+ *
309
+ * @returns {Iterable.<String>}
310
+ */
311
+ getClassNames() {
312
+ return this._classes.keys();
313
+ }
314
+ /**
315
+ * Returns style value for the given property mae.
316
+ * If the style does not exist `undefined` is returned.
317
+ *
318
+ * **Note**: This method can work with normalized style names if
319
+ * {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules a particular style processor rule is enabled}.
320
+ * See {@link module:engine/view/stylesmap~StylesMap#getAsString `StylesMap#getAsString()`} for details.
321
+ *
322
+ * For an element with style set to `'margin:1px'`:
323
+ *
324
+ * // Enable 'margin' shorthand processing:
325
+ * editor.data.addStyleProcessorRules( addMarginRules );
326
+ *
327
+ * const element = view.change( writer => {
328
+ * const element = writer.createElement();
329
+ * writer.setStyle( 'margin', '1px' );
330
+ * writer.setStyle( 'margin-bottom', '3em' );
331
+ *
332
+ * return element;
333
+ * } );
334
+ *
335
+ * element.getStyle( 'margin' ); // -> 'margin: 1px 1px 3em;'
336
+ *
337
+ * @param {String} property
338
+ * @returns {String|undefined}
339
+ */
340
+ getStyle(property) {
341
+ return this._styles.getAsString(property);
342
+ }
343
+ /**
344
+ * Returns a normalized style object or single style value.
345
+ *
346
+ * For an element with style set to: margin:1px 2px 3em;
347
+ *
348
+ * element.getNormalizedStyle( 'margin' ) );
349
+ *
350
+ * will return:
351
+ *
352
+ * {
353
+ * top: '1px',
354
+ * right: '2px',
355
+ * bottom: '3em',
356
+ * left: '2px' // a normalized value from margin shorthand
357
+ * }
358
+ *
359
+ * and reading for single style value:
360
+ *
361
+ * styles.getNormalizedStyle( 'margin-left' );
362
+ *
363
+ * Will return a `2px` string.
364
+ *
365
+ * **Note**: This method will return normalized values only if
366
+ * {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules a particular style processor rule is enabled}.
367
+ * See {@link module:engine/view/stylesmap~StylesMap#getNormalized `StylesMap#getNormalized()`} for details.
368
+ *
369
+ *
370
+ * @param {String} property Name of CSS property
371
+ * @returns {Object|String|undefined}
372
+ */
373
+ getNormalizedStyle(property) {
374
+ return this._styles.getNormalized(property);
375
+ }
376
+ /**
377
+ * Returns iterator that contains all style names.
378
+ *
379
+ * @param {Boolean} [expand=false] Expand shorthand style properties and return all equivalent style representations.
380
+ * @returns {Iterable.<String>}
381
+ */
382
+ getStyleNames(expand) {
383
+ return this._styles.getStyleNames(expand);
384
+ }
385
+ /**
386
+ * Returns true if style keys are present.
387
+ * If more then one style property is provided - returns true only when all properties are present.
388
+ *
389
+ * element.hasStyle( 'color' ); // Returns true if 'border-top' style is present.
390
+ * element.hasStyle( 'color', 'border-top' ); // Returns true if 'color' and 'border-top' styles are both present.
391
+ *
392
+ * @param {...String} property
393
+ */
394
+ hasStyle(...property) {
395
+ for (const name of property) {
396
+ if (!this._styles.has(name)) {
397
+ return false;
398
+ }
399
+ }
400
+ return true;
401
+ }
402
+ /**
403
+ * Returns ancestor element that match specified pattern.
404
+ * Provided patterns should be compatible with {@link module:engine/view/matcher~Matcher Matcher} as it is used internally.
405
+ *
406
+ * @see module:engine/view/matcher~Matcher
407
+ * @param {Object|String|RegExp|Function} patterns Patterns used to match correct ancestor.
408
+ * See {@link module:engine/view/matcher~Matcher}.
409
+ * @returns {module:engine/view/element~Element|null} Found element or `null` if no matching ancestor was found.
410
+ */
411
+ findAncestor(...patterns) {
412
+ const matcher = new Matcher(...patterns);
413
+ let parent = this.parent;
414
+ while (parent && !parent.is('documentFragment')) {
415
+ if (matcher.match(parent)) {
416
+ return parent;
417
+ }
418
+ parent = parent.parent;
419
+ }
420
+ return null;
421
+ }
422
+ /**
423
+ * Returns the custom property value for the given key.
424
+ *
425
+ * @param {String|Symbol} key
426
+ * @returns {*}
427
+ */
428
+ getCustomProperty(key) {
429
+ return this._customProperties.get(key);
430
+ }
431
+ /**
432
+ * Returns an iterator which iterates over this element's custom properties.
433
+ * Iterator provides `[ key, value ]` pairs for each stored property.
434
+ *
435
+ * @returns {Iterable.<*>}
436
+ */
437
+ *getCustomProperties() {
438
+ yield* this._customProperties.entries();
439
+ }
440
+ /**
441
+ * Returns identity string based on element's name, styles, classes and other attributes.
442
+ * Two elements that {@link #isSimilar are similar} will have same identity string.
443
+ * It has the following format:
444
+ *
445
+ * 'name class="class1,class2" style="style1:value1;style2:value2" attr1="val1" attr2="val2"'
446
+ *
447
+ * For example:
448
+ *
449
+ * const element = writer.createContainerElement( 'foo', {
450
+ * banana: '10',
451
+ * apple: '20',
452
+ * style: 'color: red; border-color: white;',
453
+ * class: 'baz'
454
+ * } );
455
+ *
456
+ * // returns 'foo class="baz" style="border-color:white;color:red" apple="20" banana="10"'
457
+ * element.getIdentity();
458
+ *
459
+ * **Note**: Classes, styles and other attributes are sorted alphabetically.
460
+ *
461
+ * @returns {String}
462
+ */
463
+ getIdentity() {
464
+ const classes = Array.from(this._classes).sort().join(',');
465
+ const styles = this._styles.toString();
466
+ const attributes = Array.from(this._attrs).map(i => `${i[0]}="${i[1]}"`).sort().join(' ');
467
+ return this.name +
468
+ (classes == '' ? '' : ` class="${classes}"`) +
469
+ (!styles ? '' : ` style="${styles}"`) +
470
+ (attributes == '' ? '' : ` ${attributes}`);
471
+ }
472
+ /**
473
+ * Decides whether an unsafe attribute is whitelisted and should be rendered in the editing pipeline even though filtering mechanisms
474
+ * like {@link module:engine/view/domconverter~DomConverter#shouldRenderAttribute} say it should not.
475
+ *
476
+ * Unsafe attribute names can be specified when creating an element via {@link module:engine/view/downcastwriter~DowncastWriter}.
477
+ *
478
+ * @param {String} attributeName The name of the attribute to be checked.
479
+ * @returns {Boolean}
480
+ */
481
+ shouldRenderUnsafeAttribute(attributeName) {
482
+ return this._unsafeAttributesToRender.includes(attributeName);
483
+ }
484
+ /**
485
+ * Clones provided element.
486
+ *
487
+ * @protected
488
+ * @param {Boolean} [deep=false] If set to `true` clones element and all its children recursively. When set to `false`,
489
+ * element will be cloned without any children.
490
+ * @returns {module:engine/view/element~Element} Clone of this element.
491
+ */
492
+ _clone(deep = false) {
493
+ const childrenClone = [];
494
+ if (deep) {
495
+ for (const child of this.getChildren()) {
496
+ childrenClone.push(child._clone(deep));
497
+ }
498
+ }
499
+ // ContainerElement and AttributeElement should be also cloned properly.
500
+ const cloned = new this.constructor(this.document, this.name, this._attrs, childrenClone);
501
+ // Classes and styles are cloned separately - this solution is faster than adding them back to attributes and
502
+ // parse once again in constructor.
503
+ cloned._classes = new Set(this._classes);
504
+ cloned._styles.set(this._styles.getNormalized());
505
+ // Clone custom properties.
506
+ cloned._customProperties = new Map(this._customProperties);
507
+ // Clone filler offset method.
508
+ // We can't define this method in a prototype because it's behavior which
509
+ // is changed by e.g. toWidget() function from ckeditor5-widget. Perhaps this should be one of custom props.
510
+ cloned.getFillerOffset = this.getFillerOffset;
511
+ // Clone unsafe attributes list.
512
+ cloned._unsafeAttributesToRender = this._unsafeAttributesToRender;
513
+ return cloned;
514
+ }
515
+ /**
516
+ * {@link module:engine/view/element~Element#_insertChild Insert} a child node or a list of child nodes at the end of this node
517
+ * and sets the parent of these nodes to this element.
518
+ *
519
+ * @see module:engine/view/downcastwriter~DowncastWriter#insert
520
+ * @protected
521
+ * @param {module:engine/view/item~Item|Iterable.<module:engine/view/item~Item>} items Items to be inserted.
522
+ * @fires module:engine/view/node~Node#change
523
+ * @returns {Number} Number of appended nodes.
524
+ */
525
+ _appendChild(items) {
526
+ return this._insertChild(this.childCount, items);
527
+ }
528
+ /**
529
+ * Inserts a child node or a list of child nodes on the given index and sets the parent of these nodes to
530
+ * this element.
531
+ *
532
+ * @internal
533
+ * @see module:engine/view/downcastwriter~DowncastWriter#insert
534
+ * @protected
535
+ * @param {Number} index Position where nodes should be inserted.
536
+ * @param {module:engine/view/item~Item|Iterable.<module:engine/view/item~Item>} items Items to be inserted.
537
+ * @fires module:engine/view/node~Node#change
538
+ * @returns {Number} Number of inserted nodes.
539
+ */
540
+ _insertChild(index, items) {
541
+ this._fireChange('children', this);
542
+ let count = 0;
543
+ const nodes = normalize(this.document, items);
544
+ for (const node of nodes) {
545
+ // If node that is being added to this element is already inside another element, first remove it from the old parent.
546
+ if (node.parent !== null) {
547
+ node._remove();
548
+ }
549
+ node.parent = this;
550
+ node.document = this.document;
551
+ this._children.splice(index, 0, node);
552
+ index++;
553
+ count++;
554
+ }
555
+ return count;
556
+ }
557
+ /**
558
+ * Removes number of child nodes starting at the given index and set the parent of these nodes to `null`.
559
+ *
560
+ * @see module:engine/view/downcastwriter~DowncastWriter#remove
561
+ * @protected
562
+ * @param {Number} index Number of the first node to remove.
563
+ * @param {Number} [howMany=1] Number of nodes to remove.
564
+ * @fires module:engine/view/node~Node#change
565
+ * @returns {Array.<module:engine/view/node~Node>} The array of removed nodes.
566
+ */
567
+ _removeChildren(index, howMany = 1) {
568
+ this._fireChange('children', this);
569
+ for (let i = index; i < index + howMany; i++) {
570
+ this._children[i].parent = null;
571
+ }
572
+ return this._children.splice(index, howMany);
573
+ }
574
+ /**
575
+ * Adds or overwrite attribute with a specified key and value.
576
+ *
577
+ * @see module:engine/view/downcastwriter~DowncastWriter#setAttribute
578
+ * @protected
579
+ * @param {String} key Attribute key.
580
+ * @param {String} value Attribute value.
581
+ * @fires module:engine/view/node~Node#change
582
+ */
583
+ _setAttribute(key, value) {
584
+ value = String(value);
585
+ this._fireChange('attributes', this);
586
+ if (key == 'class') {
587
+ parseClasses(this._classes, value);
588
+ }
589
+ else if (key == 'style') {
590
+ this._styles.setTo(value);
591
+ }
592
+ else {
593
+ this._attrs.set(key, value);
594
+ }
595
+ }
596
+ /**
597
+ * Removes attribute from the element.
598
+ *
599
+ * @see module:engine/view/downcastwriter~DowncastWriter#removeAttribute
600
+ * @protected
601
+ * @param {String} key Attribute key.
602
+ * @returns {Boolean} Returns true if an attribute existed and has been removed.
603
+ * @fires module:engine/view/node~Node#change
604
+ */
605
+ _removeAttribute(key) {
606
+ this._fireChange('attributes', this);
607
+ // Remove class attribute.
608
+ if (key == 'class') {
609
+ if (this._classes.size > 0) {
610
+ this._classes.clear();
611
+ return true;
612
+ }
613
+ return false;
614
+ }
615
+ // Remove style attribute.
616
+ if (key == 'style') {
617
+ if (!this._styles.isEmpty) {
618
+ this._styles.clear();
619
+ return true;
620
+ }
621
+ return false;
622
+ }
623
+ // Remove other attributes.
624
+ return this._attrs.delete(key);
625
+ }
626
+ /**
627
+ * Adds specified class.
628
+ *
629
+ * element._addClass( 'foo' ); // Adds 'foo' class.
630
+ * element._addClass( [ 'foo', 'bar' ] ); // Adds 'foo' and 'bar' classes.
631
+ *
632
+ * @see module:engine/view/downcastwriter~DowncastWriter#addClass
633
+ * @protected
634
+ * @param {Array.<String>|String} className
635
+ * @fires module:engine/view/node~Node#change
636
+ */
637
+ _addClass(className) {
638
+ this._fireChange('attributes', this);
639
+ for (const name of toArray(className)) {
640
+ this._classes.add(name);
641
+ }
642
+ }
643
+ /**
644
+ * Removes specified class.
645
+ *
646
+ * element._removeClass( 'foo' ); // Removes 'foo' class.
647
+ * element._removeClass( [ 'foo', 'bar' ] ); // Removes both 'foo' and 'bar' classes.
648
+ *
649
+ * @see module:engine/view/downcastwriter~DowncastWriter#removeClass
650
+ * @protected
651
+ * @param {Array.<String>|String} className
652
+ * @fires module:engine/view/node~Node#change
653
+ */
654
+ _removeClass(className) {
655
+ this._fireChange('attributes', this);
656
+ for (const name of toArray(className)) {
657
+ this._classes.delete(name);
658
+ }
659
+ }
660
+ _setStyle(property, value) {
661
+ this._fireChange('attributes', this);
662
+ if (isPlainObject(property)) {
663
+ this._styles.set(property);
664
+ }
665
+ else {
666
+ this._styles.set(property, value);
667
+ }
668
+ }
669
+ /**
670
+ * Removes specified style.
671
+ *
672
+ * element._removeStyle( 'color' ); // Removes 'color' style.
673
+ * element._removeStyle( [ 'color', 'border-top' ] ); // Removes both 'color' and 'border-top' styles.
674
+ *
675
+ * **Note**: This method can work with normalized style names if
676
+ * {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules a particular style processor rule is enabled}.
677
+ * See {@link module:engine/view/stylesmap~StylesMap#remove `StylesMap#remove()`} for details.
678
+ *
679
+ * @see module:engine/view/downcastwriter~DowncastWriter#removeStyle
680
+ * @protected
681
+ * @param {Array.<String>|String} property
682
+ * @fires module:engine/view/node~Node#change
683
+ */
684
+ _removeStyle(property) {
685
+ this._fireChange('attributes', this);
686
+ for (const name of toArray(property)) {
687
+ this._styles.remove(name);
688
+ }
689
+ }
690
+ /**
691
+ * Sets a custom property. Unlike attributes, custom properties are not rendered to the DOM,
692
+ * so they can be used to add special data to elements.
693
+ *
694
+ * @see module:engine/view/downcastwriter~DowncastWriter#setCustomProperty
695
+ * @protected
696
+ * @param {String|Symbol} key
697
+ * @param {*} value
698
+ */
699
+ _setCustomProperty(key, value) {
700
+ this._customProperties.set(key, value);
701
+ }
702
+ /**
703
+ * Removes the custom property stored under the given key.
704
+ *
705
+ * @see module:engine/view/downcastwriter~DowncastWriter#removeCustomProperty
706
+ * @protected
707
+ * @param {String|Symbol} key
708
+ * @returns {Boolean} Returns true if property was removed.
709
+ */
710
+ _removeCustomProperty(key) {
711
+ return this._customProperties.delete(key);
712
+ }
889
713
  }
890
-
714
+ /**
715
+ * Checks whether this object is of the given.
716
+ *
717
+ * element.is( 'element' ); // -> true
718
+ * element.is( 'node' ); // -> true
719
+ * element.is( 'view:element' ); // -> true
720
+ * element.is( 'view:node' ); // -> true
721
+ *
722
+ * element.is( 'model:element' ); // -> false
723
+ * element.is( 'documentSelection' ); // -> false
724
+ *
725
+ * Assuming that the object being checked is an element, you can also check its
726
+ * {@link module:engine/view/element~Element#name name}:
727
+ *
728
+ * element.is( 'element', 'img' ); // -> true if this is an <img> element
729
+ * text.is( 'element', 'img' ); -> false
730
+ *
731
+ * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
732
+ *
733
+ * @param {String} type Type to check.
734
+ * @param {String} [name] Element name.
735
+ * @returns {Boolean}
736
+ */
737
+ Element.prototype.is = function (type, name) {
738
+ if (!name) {
739
+ return type === 'element' || type === 'view:element' ||
740
+ // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
741
+ type === 'node' || type === 'view:node';
742
+ }
743
+ else {
744
+ return name === this.name && (type === 'element' || type === 'view:element');
745
+ }
746
+ };
891
747
  // Parses attributes provided to the element constructor before they are applied to an element. If attributes are passed
892
748
  // as an object (instead of `Iterable`), the object is transformed to the map. Attributes with `null` value are removed.
893
749
  // Attributes with non-`String` value are converted to `String`.
894
750
  //
895
751
  // @param {Object|Iterable} attrs Attributes to parse.
896
752
  // @returns {Map} Parsed attributes.
897
- function parseAttributes( attrs ) {
898
- attrs = toMap( attrs );
899
-
900
- for ( const [ key, value ] of attrs ) {
901
- if ( value === null ) {
902
- attrs.delete( key );
903
- } else if ( typeof value != 'string' ) {
904
- attrs.set( key, String( value ) );
905
- }
906
- }
907
-
908
- return attrs;
753
+ function parseAttributes(attrs) {
754
+ const attrsMap = toMap(attrs);
755
+ for (const [key, value] of attrsMap) {
756
+ if (value === null) {
757
+ attrsMap.delete(key);
758
+ }
759
+ else if (typeof value != 'string') {
760
+ attrsMap.set(key, String(value));
761
+ }
762
+ }
763
+ return attrsMap;
909
764
  }
910
-
911
765
  // Parses class attribute and puts all classes into classes set.
912
766
  // Classes set s cleared before insertion.
913
767
  //
914
768
  // @param {Set.<String>} classesSet Set to insert parsed classes.
915
769
  // @param {String} classesString String with classes to parse.
916
- function parseClasses( classesSet, classesString ) {
917
- const classArray = classesString.split( /\s+/ );
918
- classesSet.clear();
919
- classArray.forEach( name => classesSet.add( name ) );
770
+ function parseClasses(classesSet, classesString) {
771
+ const classArray = classesString.split(/\s+/);
772
+ classesSet.clear();
773
+ classArray.forEach(name => classesSet.add(name));
920
774
  }
921
-
922
775
  // Converts strings to Text and non-iterables to arrays.
923
776
  //
924
777
  // @param {String|module:engine/view/item~Item|Iterable.<String|module:engine/view/item~Item>}
925
778
  // @returns {Iterable.<module:engine/view/node~Node>}
926
- function normalize( document, nodes ) {
927
- // Separate condition because string is iterable.
928
- if ( typeof nodes == 'string' ) {
929
- return [ new Text( document, nodes ) ];
930
- }
931
-
932
- if ( !isIterable( nodes ) ) {
933
- nodes = [ nodes ];
934
- }
935
-
936
- // Array.from to enable .map() on non-arrays.
937
- return Array.from( nodes )
938
- .map( node => {
939
- if ( typeof node == 'string' ) {
940
- return new Text( document, node );
941
- }
942
-
943
- if ( node instanceof TextProxy ) {
944
- return new Text( document, node.data );
945
- }
946
-
947
- return node;
948
- } );
779
+ function normalize(document, nodes) {
780
+ // Separate condition because string is iterable.
781
+ if (typeof nodes == 'string') {
782
+ return [new Text(document, nodes)];
783
+ }
784
+ if (!isIterable(nodes)) {
785
+ nodes = [nodes];
786
+ }
787
+ // Array.from to enable .map() on non-arrays.
788
+ return Array.from(nodes)
789
+ .map(node => {
790
+ if (typeof node == 'string') {
791
+ return new Text(document, node);
792
+ }
793
+ if (node instanceof TextProxy) {
794
+ return new Text(document, node.data);
795
+ }
796
+ return node;
797
+ });
949
798
  }