@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,19 +2,16 @@
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 module:engine/model/documentfragment
8
7
  */
9
-
10
- import NodeList from './nodelist';
8
+ import TypeCheckable from './typecheckable';
11
9
  import Element from './element';
10
+ import NodeList from './nodelist';
12
11
  import Text from './text';
13
12
  import TextProxy from './textproxy';
14
13
  import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
15
-
16
14
  // @if CK_DEBUG_ENGINE // const { stringifyMap } = require( '../dev-utils/utils' );
17
-
18
15
  /**
19
16
  * DocumentFragment represents a part of model which does not have a common root but its top-level nodes
20
17
  * can be seen as siblings. In other words, it is a detached part of model tree, without a root.
@@ -23,368 +20,334 @@ import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
23
20
  * will be set to the {@link module:engine/model/model~Model#markers model markers} by a
24
21
  * {@link module:engine/model/writer~Writer#insert} function.
25
22
  */
26
- export default class DocumentFragment {
27
- /**
28
- * Creates an empty `DocumentFragment`.
29
- *
30
- * **Note:** Constructor of this class shouldn't be used directly in the code.
31
- * Use the {@link module:engine/model/writer~Writer#createDocumentFragment} method instead.
32
- *
33
- * @protected
34
- * @param {module:engine/model/node~Node|Iterable.<module:engine/model/node~Node>} [children]
35
- * Nodes to be contained inside the `DocumentFragment`.
36
- */
37
- constructor( children ) {
38
- /**
39
- * DocumentFragment static markers map. This is a list of names and {@link module:engine/model/range~Range ranges}
40
- * which will be set as Markers to {@link module:engine/model/model~Model#markers model markers collection}
41
- * when DocumentFragment will be inserted to the document.
42
- *
43
- * @readonly
44
- * @member {Map<String,module:engine/model/range~Range>} module:engine/model/documentfragment~DocumentFragment#markers
45
- */
46
- this.markers = new Map();
47
-
48
- /**
49
- * List of nodes contained inside the document fragment.
50
- *
51
- * @private
52
- * @member {module:engine/model/nodelist~NodeList} module:engine/model/documentfragment~DocumentFragment#_children
53
- */
54
- this._children = new NodeList();
55
-
56
- if ( children ) {
57
- this._insertChild( 0, children );
58
- }
59
- }
60
-
61
- /**
62
- * Returns an iterator that iterates over all nodes contained inside this document fragment.
63
- *
64
- * @returns {Iterable.<module:engine/model/node~Node>}
65
- */
66
- [ Symbol.iterator ]() {
67
- return this.getChildren();
68
- }
69
-
70
- /**
71
- * Number of this document fragment's children.
72
- *
73
- * @readonly
74
- * @type {Number}
75
- */
76
- get childCount() {
77
- return this._children.length;
78
- }
79
-
80
- /**
81
- * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all of this document fragment's children.
82
- *
83
- * @readonly
84
- * @type {Number}
85
- */
86
- get maxOffset() {
87
- return this._children.maxOffset;
88
- }
89
-
90
- /**
91
- * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
92
- *
93
- * @readonly
94
- * @type {Boolean}
95
- */
96
- get isEmpty() {
97
- return this.childCount === 0;
98
- }
99
-
100
- /**
101
- * Artificial root of `DocumentFragment`. Returns itself. Added for compatibility reasons.
102
- *
103
- * @readonly
104
- * @type {module:engine/model/documentfragment~DocumentFragment}
105
- */
106
- get root() {
107
- return this;
108
- }
109
-
110
- /**
111
- * Artificial parent of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
112
- *
113
- * @readonly
114
- * @type {null}
115
- */
116
- get parent() {
117
- return null;
118
- }
119
-
120
- /**
121
- * Checks whether this object is of the given type.
122
- *
123
- * docFrag.is( 'documentFragment' ); // -> true
124
- * docFrag.is( 'model:documentFragment' ); // -> true
125
- *
126
- * docFrag.is( 'view:documentFragment' ); // -> false
127
- * docFrag.is( 'element' ); // -> false
128
- * docFrag.is( 'node' ); // -> false
129
- *
130
- * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
131
- *
132
- * @param {String} type
133
- * @returns {Boolean}
134
- */
135
- is( type ) {
136
- return type === 'documentFragment' || type === 'model:documentFragment';
137
- }
138
-
139
- /**
140
- * Gets the child at the given index. Returns `null` if incorrect index was passed.
141
- *
142
- * @param {Number} index Index of child.
143
- * @returns {module:engine/model/node~Node|null} Child node.
144
- */
145
- getChild( index ) {
146
- return this._children.getNode( index );
147
- }
148
-
149
- /**
150
- * Returns an iterator that iterates over all of this document fragment's children.
151
- *
152
- * @returns {Iterable.<module:engine/model/node~Node>}
153
- */
154
- getChildren() {
155
- return this._children[ Symbol.iterator ]();
156
- }
157
-
158
- /**
159
- * Returns an index of the given child node. Returns `null` if given node is not a child of this document fragment.
160
- *
161
- * @param {module:engine/model/node~Node} node Child node to look for.
162
- * @returns {Number|null} Child node's index.
163
- */
164
- getChildIndex( node ) {
165
- return this._children.getNodeIndex( node );
166
- }
167
-
168
- /**
169
- * Returns the starting offset of given child. Starting offset is equal to the sum of
170
- * {@link module:engine/model/node~Node#offsetSize offset sizes} of all node's siblings that are before it. Returns `null` if
171
- * given node is not a child of this document fragment.
172
- *
173
- * @param {module:engine/model/node~Node} node Child node to look for.
174
- * @returns {Number|null} Child node's starting offset.
175
- */
176
- getChildStartOffset( node ) {
177
- return this._children.getNodeStartOffset( node );
178
- }
179
-
180
- /**
181
- * Returns path to a `DocumentFragment`, which is an empty array. Added for compatibility reasons.
182
- *
183
- * @returns {Array}
184
- */
185
- getPath() {
186
- return [];
187
- }
188
-
189
- /**
190
- * Returns a descendant node by its path relative to this element.
191
- *
192
- * // <this>a<b>c</b></this>
193
- * this.getNodeByPath( [ 0 ] ); // -> "a"
194
- * this.getNodeByPath( [ 1 ] ); // -> <b>
195
- * this.getNodeByPath( [ 1, 0 ] ); // -> "c"
196
- *
197
- * @param {Array.<Number>} relativePath Path of the node to find, relative to this element.
198
- * @returns {module:engine/model/node~Node|module:engine/model/documentfragment~DocumentFragment}
199
- */
200
- getNodeByPath( relativePath ) {
201
- let node = this; // eslint-disable-line consistent-this
202
-
203
- for ( const index of relativePath ) {
204
- node = node.getChild( node.offsetToIndex( index ) );
205
- }
206
-
207
- return node;
208
- }
209
-
210
- /**
211
- * Converts offset "position" to index "position".
212
- *
213
- * Returns index of a node that occupies given offset. If given offset is too low, returns `0`. If given offset is
214
- * too high, returns index after last child}.
215
- *
216
- * const textNode = new Text( 'foo' );
217
- * const pElement = new Element( 'p' );
218
- * const docFrag = new DocumentFragment( [ textNode, pElement ] );
219
- * docFrag.offsetToIndex( -1 ); // Returns 0, because offset is too low.
220
- * docFrag.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
221
- * docFrag.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
222
- * docFrag.offsetToIndex( 2 ); // Returns 0.
223
- * docFrag.offsetToIndex( 3 ); // Returns 1.
224
- * docFrag.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.
225
- *
226
- * @param {Number} offset Offset to look for.
227
- * @returns {Number} Index of a node that occupies given offset.
228
- */
229
- offsetToIndex( offset ) {
230
- return this._children.offsetToIndex( offset );
231
- }
232
-
233
- /**
234
- * Converts `DocumentFragment` instance to plain object and returns it.
235
- * Takes care of converting all of this document fragment's children.
236
- *
237
- * @returns {Object} `DocumentFragment` instance converted to plain object.
238
- */
239
- toJSON() {
240
- const json = [];
241
-
242
- for ( const node of this._children ) {
243
- json.push( node.toJSON() );
244
- }
245
-
246
- return json;
247
- }
248
-
249
- /**
250
- * Creates a `DocumentFragment` instance from given plain object (i.e. parsed JSON string).
251
- * Converts `DocumentFragment` children to proper nodes.
252
- *
253
- * @param {Object} json Plain object to be converted to `DocumentFragment`.
254
- * @returns {module:engine/model/documentfragment~DocumentFragment} `DocumentFragment` instance created using given plain object.
255
- */
256
- static fromJSON( json ) {
257
- const children = [];
258
-
259
- for ( const child of json ) {
260
- if ( child.name ) {
261
- // If child has name property, it is an Element.
262
- children.push( Element.fromJSON( child ) );
263
- } else {
264
- // Otherwise, it is a Text node.
265
- children.push( Text.fromJSON( child ) );
266
- }
267
- }
268
-
269
- return new DocumentFragment( children );
270
- }
271
-
272
- /**
273
- * {@link #_insertChild Inserts} one or more nodes at the end of this document fragment.
274
- *
275
- * @protected
276
- * @param {module:engine/model/item~Item|Iterable.<module:engine/model/item~Item>} items Items to be inserted.
277
- */
278
- _appendChild( items ) {
279
- this._insertChild( this.childCount, items );
280
- }
281
-
282
- /**
283
- * Inserts one or more nodes at the given index and sets {@link module:engine/model/node~Node#parent parent} of these nodes
284
- * to this document fragment.
285
- *
286
- * @protected
287
- * @param {Number} index Index at which nodes should be inserted.
288
- * @param {module:engine/model/item~Item|Iterable.<module:engine/model/item~Item>} items Items to be inserted.
289
- */
290
- _insertChild( index, items ) {
291
- const nodes = normalize( items );
292
-
293
- for ( const node of nodes ) {
294
- // If node that is being added to this element is already inside another element, first remove it from the old parent.
295
- if ( node.parent !== null ) {
296
- node._remove();
297
- }
298
-
299
- node.parent = this;
300
- }
301
-
302
- this._children._insertNodes( index, nodes );
303
- }
304
-
305
- /**
306
- * Removes one or more nodes starting at the given index
307
- * and sets {@link module:engine/model/node~Node#parent parent} of these nodes to `null`.
308
- *
309
- * @protected
310
- * @param {Number} index Index of the first node to remove.
311
- * @param {Number} [howMany=1] Number of nodes to remove.
312
- * @returns {Array.<module:engine/model/node~Node>} Array containing removed nodes.
313
- */
314
- _removeChildren( index, howMany = 1 ) {
315
- const nodes = this._children._removeNodes( index, howMany );
316
-
317
- for ( const node of nodes ) {
318
- node.parent = null;
319
- }
320
-
321
- return nodes;
322
- }
323
-
324
- // @if CK_DEBUG_ENGINE // toString() {
325
- // @if CK_DEBUG_ENGINE // return 'documentFragment';
326
- // @if CK_DEBUG_ENGINE // }
327
-
328
- // @if CK_DEBUG_ENGINE // log() {
329
- // @if CK_DEBUG_ENGINE // console.log( 'ModelDocumentFragment: ' + this );
330
- // @if CK_DEBUG_ENGINE // }
331
-
332
- // @if CK_DEBUG_ENGINE // printTree() {
333
- // @if CK_DEBUG_ENGINE // let string = 'ModelDocumentFragment: [';
334
-
335
- // @if CK_DEBUG_ENGINE // for ( const child of this.getChildren() ) {
336
- // @if CK_DEBUG_ENGINE // string += '\n';
337
-
338
- // @if CK_DEBUG_ENGINE // if ( child.is( '$text' ) ) {
339
- // @if CK_DEBUG_ENGINE // const textAttrs = stringifyMap( child._attrs );
340
-
341
- // @if CK_DEBUG_ENGINE // string += '\t'.repeat( 1 );
342
-
343
- // @if CK_DEBUG_ENGINE // if ( textAttrs !== '' ) {
344
- // @if CK_DEBUG_ENGINE // string += `<$text${ textAttrs }>` + child.data + '</$text>';
345
- // @if CK_DEBUG_ENGINE // } else {
346
- // @if CK_DEBUG_ENGINE // string += child.data;
347
- // @if CK_DEBUG_ENGINE // }
348
- // @if CK_DEBUG_ENGINE // } else {
349
- // @if CK_DEBUG_ENGINE // string += child.printTree( 1 );
350
- // @if CK_DEBUG_ENGINE // }
351
- // @if CK_DEBUG_ENGINE // }
352
-
353
- // @if CK_DEBUG_ENGINE // string += '\n]';
354
-
355
- // @if CK_DEBUG_ENGINE // return string;
356
- // @if CK_DEBUG_ENGINE // }
357
-
358
- // @if CK_DEBUG_ENGINE // logTree() {
359
- // @if CK_DEBUG_ENGINE // console.log( this.printTree() );
360
- // @if CK_DEBUG_ENGINE // }
23
+ export default class DocumentFragment extends TypeCheckable {
24
+ /**
25
+ * Creates an empty `DocumentFragment`.
26
+ *
27
+ * **Note:** Constructor of this class shouldn't be used directly in the code.
28
+ * Use the {@link module:engine/model/writer~Writer#createDocumentFragment} method instead.
29
+ *
30
+ * @protected
31
+ * @param {module:engine/model/node~Node|Iterable.<module:engine/model/node~Node>} [children]
32
+ * Nodes to be contained inside the `DocumentFragment`.
33
+ */
34
+ constructor(children) {
35
+ super();
36
+ /**
37
+ * DocumentFragment static markers map. This is a list of names and {@link module:engine/model/range~Range ranges}
38
+ * which will be set as Markers to {@link module:engine/model/model~Model#markers model markers collection}
39
+ * when DocumentFragment will be inserted to the document.
40
+ *
41
+ * @readonly
42
+ * @member {Map<String,module:engine/model/range~Range>} module:engine/model/documentfragment~DocumentFragment#markers
43
+ */
44
+ this.markers = new Map();
45
+ /**
46
+ * List of nodes contained inside the document fragment.
47
+ *
48
+ * @private
49
+ * @member {module:engine/model/nodelist~NodeList} module:engine/model/documentfragment~DocumentFragment#_children
50
+ */
51
+ this._children = new NodeList();
52
+ if (children) {
53
+ this._insertChild(0, children);
54
+ }
55
+ }
56
+ /**
57
+ * Returns an iterator that iterates over all nodes contained inside this document fragment.
58
+ *
59
+ * @returns {Iterator.<module:engine/model/node~Node>}
60
+ */
61
+ [Symbol.iterator]() {
62
+ return this.getChildren();
63
+ }
64
+ /**
65
+ * Number of this document fragment's children.
66
+ *
67
+ * @readonly
68
+ * @type {Number}
69
+ */
70
+ get childCount() {
71
+ return this._children.length;
72
+ }
73
+ /**
74
+ * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all of this document fragment's children.
75
+ *
76
+ * @readonly
77
+ * @type {Number}
78
+ */
79
+ get maxOffset() {
80
+ return this._children.maxOffset;
81
+ }
82
+ /**
83
+ * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
84
+ *
85
+ * @readonly
86
+ * @type {Boolean}
87
+ */
88
+ get isEmpty() {
89
+ return this.childCount === 0;
90
+ }
91
+ /**
92
+ * Artificial next sibling. Returns `null`. Added for compatibility reasons.
93
+ *
94
+ * @readonly
95
+ * @type {null}
96
+ */
97
+ get nextSibling() {
98
+ return null;
99
+ }
100
+ /**
101
+ * Artificial previous sibling. Returns `null`. Added for compatibility reasons.
102
+ *
103
+ * @readonly
104
+ * @type {null}
105
+ */
106
+ get previousSibling() {
107
+ return null;
108
+ }
109
+ /**
110
+ * Artificial root of `DocumentFragment`. Returns itself. Added for compatibility reasons.
111
+ *
112
+ * @readonly
113
+ * @type {module:engine/model/documentfragment~DocumentFragment}
114
+ */
115
+ get root() {
116
+ return this;
117
+ }
118
+ /**
119
+ * Artificial parent of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
120
+ *
121
+ * @readonly
122
+ * @type {null}
123
+ */
124
+ get parent() {
125
+ return null;
126
+ }
127
+ /**
128
+ * Artificial owner of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
129
+ *
130
+ * @readonly
131
+ * @type {null}
132
+ */
133
+ get document() {
134
+ return null;
135
+ }
136
+ /**
137
+ * Returns empty array. Added for compatibility reasons.
138
+ *
139
+ * @returns {Array}
140
+ */
141
+ getAncestors() {
142
+ return [];
143
+ }
144
+ /**
145
+ * Gets the child at the given index. Returns `null` if incorrect index was passed.
146
+ *
147
+ * @param {Number} index Index of child.
148
+ * @returns {module:engine/model/node~Node|null} Child node.
149
+ */
150
+ getChild(index) {
151
+ return this._children.getNode(index);
152
+ }
153
+ /**
154
+ * Returns an iterator that iterates over all of this document fragment's children.
155
+ *
156
+ * @returns {Iterable.<module:engine/model/node~Node>}
157
+ */
158
+ getChildren() {
159
+ return this._children[Symbol.iterator]();
160
+ }
161
+ /**
162
+ * Returns an index of the given child node. Returns `null` if given node is not a child of this document fragment.
163
+ *
164
+ * @param {module:engine/model/node~Node} node Child node to look for.
165
+ * @returns {Number|null} Child node's index.
166
+ */
167
+ getChildIndex(node) {
168
+ return this._children.getNodeIndex(node);
169
+ }
170
+ /**
171
+ * Returns the starting offset of given child. Starting offset is equal to the sum of
172
+ * {@link module:engine/model/node~Node#offsetSize offset sizes} of all node's siblings that are before it. Returns `null` if
173
+ * given node is not a child of this document fragment.
174
+ *
175
+ * @param {module:engine/model/node~Node} node Child node to look for.
176
+ * @returns {Number|null} Child node's starting offset.
177
+ */
178
+ getChildStartOffset(node) {
179
+ return this._children.getNodeStartOffset(node);
180
+ }
181
+ /**
182
+ * Returns path to a `DocumentFragment`, which is an empty array. Added for compatibility reasons.
183
+ *
184
+ * @returns {Array}
185
+ */
186
+ getPath() {
187
+ return [];
188
+ }
189
+ /**
190
+ * Returns a descendant node by its path relative to this element.
191
+ *
192
+ * // <this>a<b>c</b></this>
193
+ * this.getNodeByPath( [ 0 ] ); // -> "a"
194
+ * this.getNodeByPath( [ 1 ] ); // -> <b>
195
+ * this.getNodeByPath( [ 1, 0 ] ); // -> "c"
196
+ *
197
+ * @param {Array.<Number>} relativePath Path of the node to find, relative to this element.
198
+ * @returns {module:engine/model/node~Node|module:engine/model/documentfragment~DocumentFragment}
199
+ */
200
+ getNodeByPath(relativePath) {
201
+ // eslint-disable-next-line @typescript-eslint/no-this-alias, consistent-this
202
+ let node = this;
203
+ for (const index of relativePath) {
204
+ node = node.getChild(node.offsetToIndex(index));
205
+ }
206
+ return node;
207
+ }
208
+ /**
209
+ * Converts offset "position" to index "position".
210
+ *
211
+ * Returns index of a node that occupies given offset. If given offset is too low, returns `0`. If given offset is
212
+ * too high, returns index after last child}.
213
+ *
214
+ * const textNode = new Text( 'foo' );
215
+ * const pElement = new Element( 'p' );
216
+ * const docFrag = new DocumentFragment( [ textNode, pElement ] );
217
+ * docFrag.offsetToIndex( -1 ); // Returns 0, because offset is too low.
218
+ * docFrag.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0.
219
+ * docFrag.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too.
220
+ * docFrag.offsetToIndex( 2 ); // Returns 0.
221
+ * docFrag.offsetToIndex( 3 ); // Returns 1.
222
+ * docFrag.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.
223
+ *
224
+ * @param {Number} offset Offset to look for.
225
+ * @returns {Number} Index of a node that occupies given offset.
226
+ */
227
+ offsetToIndex(offset) {
228
+ return this._children.offsetToIndex(offset);
229
+ }
230
+ /**
231
+ * Converts `DocumentFragment` instance to plain object and returns it.
232
+ * Takes care of converting all of this document fragment's children.
233
+ *
234
+ * @returns {Object} `DocumentFragment` instance converted to plain object.
235
+ */
236
+ toJSON() {
237
+ const json = [];
238
+ for (const node of this._children) {
239
+ json.push(node.toJSON());
240
+ }
241
+ return json;
242
+ }
243
+ /**
244
+ * Creates a `DocumentFragment` instance from given plain object (i.e. parsed JSON string).
245
+ * Converts `DocumentFragment` children to proper nodes.
246
+ *
247
+ * @param {Object} json Plain object to be converted to `DocumentFragment`.
248
+ * @returns {module:engine/model/documentfragment~DocumentFragment} `DocumentFragment` instance created using given plain object.
249
+ */
250
+ static fromJSON(json) {
251
+ const children = [];
252
+ for (const child of json) {
253
+ if (child.name) {
254
+ // If child has name property, it is an Element.
255
+ children.push(Element.fromJSON(child));
256
+ }
257
+ else {
258
+ // Otherwise, it is a Text node.
259
+ children.push(Text.fromJSON(child));
260
+ }
261
+ }
262
+ return new DocumentFragment(children);
263
+ }
264
+ /**
265
+ * {@link #_insertChild Inserts} one or more nodes at the end of this document fragment.
266
+ *
267
+ * @internal
268
+ * @protected
269
+ * @param {String|module:engine/model/item~Item|Iterable.<String|module:engine/model/item~Item>} items Items to be inserted.
270
+ */
271
+ _appendChild(items) {
272
+ this._insertChild(this.childCount, items);
273
+ }
274
+ /**
275
+ * Inserts one or more nodes at the given index and sets {@link module:engine/model/node~Node#parent parent} of these nodes
276
+ * to this document fragment.
277
+ *
278
+ * @internal
279
+ * @protected
280
+ * @param {Number} index Index at which nodes should be inserted.
281
+ * @param {String|module:engine/model/item~Item|Iterable.<String|module:engine/model/item~Item>} items Items to be inserted.
282
+ */
283
+ _insertChild(index, items) {
284
+ const nodes = normalize(items);
285
+ for (const node of nodes) {
286
+ // If node that is being added to this element is already inside another element, first remove it from the old parent.
287
+ if (node.parent !== null) {
288
+ node._remove();
289
+ }
290
+ node.parent = this;
291
+ }
292
+ this._children._insertNodes(index, nodes);
293
+ }
294
+ /**
295
+ * Removes one or more nodes starting at the given index
296
+ * and sets {@link module:engine/model/node~Node#parent parent} of these nodes to `null`.
297
+ *
298
+ * @internal
299
+ * @protected
300
+ * @param {Number} index Index of the first node to remove.
301
+ * @param {Number} [howMany=1] Number of nodes to remove.
302
+ * @returns {Array.<module:engine/model/node~Node>} Array containing removed nodes.
303
+ */
304
+ _removeChildren(index, howMany = 1) {
305
+ const nodes = this._children._removeNodes(index, howMany);
306
+ for (const node of nodes) {
307
+ node.parent = null;
308
+ }
309
+ return nodes;
310
+ }
361
311
  }
362
-
312
+ /**
313
+ * Checks whether this object is of the given type.
314
+ *
315
+ * docFrag.is( 'documentFragment' ); // -> true
316
+ * docFrag.is( 'model:documentFragment' ); // -> true
317
+ *
318
+ * docFrag.is( 'view:documentFragment' ); // -> false
319
+ * docFrag.is( 'element' ); // -> false
320
+ * docFrag.is( 'node' ); // -> false
321
+ *
322
+ * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
323
+ *
324
+ * @param {String} type
325
+ * @returns {Boolean}
326
+ */
327
+ DocumentFragment.prototype.is = function (type) {
328
+ return type === 'documentFragment' || type === 'model:documentFragment';
329
+ };
363
330
  // Converts strings to Text and non-iterables to arrays.
364
331
  //
365
332
  // @param {String|module:engine/model/item~Item|Iterable.<module:engine/model/item~Item>}
366
333
  // @returns {Iterable.<module:engine/model/node~Node>}
367
- function normalize( nodes ) {
368
- // Separate condition because string is iterable.
369
- if ( typeof nodes == 'string' ) {
370
- return [ new Text( nodes ) ];
371
- }
372
-
373
- if ( !isIterable( nodes ) ) {
374
- nodes = [ nodes ];
375
- }
376
-
377
- // Array.from to enable .map() on non-arrays.
378
- return Array.from( nodes )
379
- .map( node => {
380
- if ( typeof node == 'string' ) {
381
- return new Text( node );
382
- }
383
-
384
- if ( node instanceof TextProxy ) {
385
- return new Text( node.data, node.getAttributes() );
386
- }
387
-
388
- return node;
389
- } );
334
+ function normalize(nodes) {
335
+ // Separate condition because string is iterable.
336
+ if (typeof nodes == 'string') {
337
+ return [new Text(nodes)];
338
+ }
339
+ if (!isIterable(nodes)) {
340
+ nodes = [nodes];
341
+ }
342
+ // Array.from to enable .map() on non-arrays.
343
+ return Array.from(nodes)
344
+ .map(node => {
345
+ if (typeof node == 'string') {
346
+ return new Text(node);
347
+ }
348
+ if (node instanceof TextProxy) {
349
+ return new Text(node.data, node.getAttributes());
350
+ }
351
+ return node;
352
+ });
390
353
  }