@ckeditor/ckeditor5-engine 35.0.1 → 35.2.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 +176 -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 +980 -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 +757 -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 +199 -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,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
  }