@ckeditor/ckeditor5-engine 35.0.1 → 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 (124) hide show
  1. package/CHANGELOG.md +4 -4
  2. package/package.json +30 -24
  3. package/src/controller/datacontroller.js +467 -561
  4. package/src/controller/editingcontroller.js +168 -204
  5. package/src/conversion/conversion.js +541 -565
  6. package/src/conversion/conversionhelpers.js +24 -28
  7. package/src/conversion/downcastdispatcher.js +457 -686
  8. package/src/conversion/downcasthelpers.js +1583 -1965
  9. package/src/conversion/mapper.js +518 -707
  10. package/src/conversion/modelconsumable.js +240 -283
  11. package/src/conversion/upcastdispatcher.js +372 -718
  12. package/src/conversion/upcasthelpers.js +707 -818
  13. package/src/conversion/viewconsumable.js +524 -581
  14. package/src/dataprocessor/basichtmlwriter.js +12 -16
  15. package/src/dataprocessor/dataprocessor.js +5 -0
  16. package/src/dataprocessor/htmldataprocessor.js +100 -116
  17. package/src/dataprocessor/htmlwriter.js +1 -18
  18. package/src/dataprocessor/xmldataprocessor.js +116 -137
  19. package/src/dev-utils/model.js +260 -352
  20. package/src/dev-utils/operationreplayer.js +106 -126
  21. package/src/dev-utils/utils.js +34 -51
  22. package/src/dev-utils/view.js +632 -753
  23. package/src/index.js +0 -11
  24. package/src/model/batch.js +111 -127
  25. package/src/model/differ.js +988 -1233
  26. package/src/model/document.js +340 -449
  27. package/src/model/documentfragment.js +327 -364
  28. package/src/model/documentselection.js +996 -1189
  29. package/src/model/element.js +306 -410
  30. package/src/model/history.js +224 -262
  31. package/src/model/item.js +5 -0
  32. package/src/model/liveposition.js +84 -145
  33. package/src/model/liverange.js +108 -185
  34. package/src/model/markercollection.js +379 -480
  35. package/src/model/model.js +883 -1034
  36. package/src/model/node.js +419 -463
  37. package/src/model/nodelist.js +175 -201
  38. package/src/model/operation/attributeoperation.js +153 -182
  39. package/src/model/operation/detachoperation.js +64 -83
  40. package/src/model/operation/insertoperation.js +135 -166
  41. package/src/model/operation/markeroperation.js +114 -140
  42. package/src/model/operation/mergeoperation.js +163 -191
  43. package/src/model/operation/moveoperation.js +157 -187
  44. package/src/model/operation/nooperation.js +28 -38
  45. package/src/model/operation/operation.js +106 -125
  46. package/src/model/operation/operationfactory.js +30 -34
  47. package/src/model/operation/renameoperation.js +109 -135
  48. package/src/model/operation/rootattributeoperation.js +155 -188
  49. package/src/model/operation/splitoperation.js +196 -232
  50. package/src/model/operation/transform.js +1833 -2204
  51. package/src/model/operation/utils.js +140 -204
  52. package/src/model/position.js +899 -1053
  53. package/src/model/range.js +910 -1028
  54. package/src/model/rootelement.js +77 -97
  55. package/src/model/schema.js +1189 -1835
  56. package/src/model/selection.js +745 -862
  57. package/src/model/text.js +90 -114
  58. package/src/model/textproxy.js +204 -240
  59. package/src/model/treewalker.js +316 -397
  60. package/src/model/typecheckable.js +16 -0
  61. package/src/model/utils/autoparagraphing.js +32 -44
  62. package/src/model/utils/deletecontent.js +334 -418
  63. package/src/model/utils/findoptimalinsertionrange.js +25 -36
  64. package/src/model/utils/getselectedcontent.js +96 -118
  65. package/src/model/utils/insertcontent.js +654 -773
  66. package/src/model/utils/insertobject.js +96 -119
  67. package/src/model/utils/modifyselection.js +120 -158
  68. package/src/model/utils/selection-post-fixer.js +153 -201
  69. package/src/model/writer.js +1305 -1474
  70. package/src/view/attributeelement.js +189 -225
  71. package/src/view/containerelement.js +75 -85
  72. package/src/view/document.js +172 -215
  73. package/src/view/documentfragment.js +200 -249
  74. package/src/view/documentselection.js +338 -367
  75. package/src/view/domconverter.js +1370 -1617
  76. package/src/view/downcastwriter.js +1747 -2076
  77. package/src/view/editableelement.js +81 -97
  78. package/src/view/element.js +739 -890
  79. package/src/view/elementdefinition.js +5 -0
  80. package/src/view/emptyelement.js +82 -92
  81. package/src/view/filler.js +35 -50
  82. package/src/view/item.js +5 -0
  83. package/src/view/matcher.js +260 -559
  84. package/src/view/node.js +274 -360
  85. package/src/view/observer/arrowkeysobserver.js +19 -28
  86. package/src/view/observer/bubblingemittermixin.js +120 -263
  87. package/src/view/observer/bubblingeventinfo.js +47 -55
  88. package/src/view/observer/clickobserver.js +7 -13
  89. package/src/view/observer/compositionobserver.js +14 -24
  90. package/src/view/observer/domeventdata.js +57 -67
  91. package/src/view/observer/domeventobserver.js +40 -64
  92. package/src/view/observer/fakeselectionobserver.js +81 -96
  93. package/src/view/observer/focusobserver.js +45 -61
  94. package/src/view/observer/inputobserver.js +7 -13
  95. package/src/view/observer/keyobserver.js +17 -27
  96. package/src/view/observer/mouseobserver.js +7 -14
  97. package/src/view/observer/mutationobserver.js +220 -315
  98. package/src/view/observer/observer.js +81 -102
  99. package/src/view/observer/selectionobserver.js +191 -246
  100. package/src/view/observer/tabobserver.js +23 -36
  101. package/src/view/placeholder.js +128 -173
  102. package/src/view/position.js +350 -401
  103. package/src/view/range.js +453 -513
  104. package/src/view/rawelement.js +85 -112
  105. package/src/view/renderer.js +874 -1018
  106. package/src/view/rooteditableelement.js +80 -90
  107. package/src/view/selection.js +608 -689
  108. package/src/view/styles/background.js +43 -44
  109. package/src/view/styles/border.js +220 -276
  110. package/src/view/styles/margin.js +8 -17
  111. package/src/view/styles/padding.js +8 -16
  112. package/src/view/styles/utils.js +127 -160
  113. package/src/view/stylesmap.js +728 -905
  114. package/src/view/text.js +102 -126
  115. package/src/view/textproxy.js +144 -170
  116. package/src/view/treewalker.js +383 -479
  117. package/src/view/typecheckable.js +19 -0
  118. package/src/view/uielement.js +166 -187
  119. package/src/view/upcastwriter.js +395 -449
  120. package/src/view/view.js +569 -664
  121. package/src/dataprocessor/dataprocessor.jsdoc +0 -64
  122. package/src/model/item.jsdoc +0 -14
  123. package/src/view/elementdefinition.jsdoc +0 -59
  124. 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
  }