@ckeditor/ckeditor5-engine 40.0.0 → 40.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 (242) hide show
  1. package/LICENSE.md +3 -3
  2. package/package.json +2 -2
  3. package/src/controller/datacontroller.d.ts +334 -334
  4. package/src/controller/datacontroller.js +481 -481
  5. package/src/controller/editingcontroller.d.ts +98 -98
  6. package/src/controller/editingcontroller.js +191 -191
  7. package/src/conversion/conversion.d.ts +478 -478
  8. package/src/conversion/conversion.js +601 -601
  9. package/src/conversion/conversionhelpers.d.ts +26 -26
  10. package/src/conversion/conversionhelpers.js +32 -32
  11. package/src/conversion/downcastdispatcher.d.ts +562 -562
  12. package/src/conversion/downcastdispatcher.js +547 -547
  13. package/src/conversion/downcasthelpers.d.ts +1226 -1226
  14. package/src/conversion/downcasthelpers.js +2178 -2183
  15. package/src/conversion/mapper.d.ts +503 -503
  16. package/src/conversion/mapper.js +536 -536
  17. package/src/conversion/modelconsumable.d.ts +201 -201
  18. package/src/conversion/modelconsumable.js +333 -333
  19. package/src/conversion/upcastdispatcher.d.ts +492 -492
  20. package/src/conversion/upcastdispatcher.js +460 -460
  21. package/src/conversion/upcasthelpers.d.ts +499 -499
  22. package/src/conversion/upcasthelpers.js +950 -950
  23. package/src/conversion/viewconsumable.d.ts +369 -369
  24. package/src/conversion/viewconsumable.js +536 -532
  25. package/src/dataprocessor/basichtmlwriter.d.ts +18 -18
  26. package/src/dataprocessor/basichtmlwriter.js +20 -19
  27. package/src/dataprocessor/dataprocessor.d.ts +61 -61
  28. package/src/dataprocessor/dataprocessor.js +5 -5
  29. package/src/dataprocessor/htmldataprocessor.d.ts +76 -76
  30. package/src/dataprocessor/htmldataprocessor.js +96 -96
  31. package/src/dataprocessor/htmlwriter.d.ts +16 -16
  32. package/src/dataprocessor/htmlwriter.js +5 -5
  33. package/src/dataprocessor/xmldataprocessor.d.ts +90 -90
  34. package/src/dataprocessor/xmldataprocessor.js +108 -108
  35. package/src/dev-utils/model.d.ts +124 -124
  36. package/src/dev-utils/model.js +395 -395
  37. package/src/dev-utils/operationreplayer.d.ts +51 -51
  38. package/src/dev-utils/operationreplayer.js +112 -112
  39. package/src/dev-utils/utils.d.ts +37 -37
  40. package/src/dev-utils/utils.js +73 -73
  41. package/src/dev-utils/view.d.ts +319 -319
  42. package/src/dev-utils/view.js +967 -967
  43. package/src/index.d.ts +114 -114
  44. package/src/index.js +78 -78
  45. package/src/model/batch.d.ts +106 -106
  46. package/src/model/batch.js +96 -96
  47. package/src/model/differ.d.ts +387 -387
  48. package/src/model/differ.js +1149 -1149
  49. package/src/model/document.d.ts +272 -272
  50. package/src/model/document.js +360 -361
  51. package/src/model/documentfragment.d.ts +200 -200
  52. package/src/model/documentfragment.js +306 -306
  53. package/src/model/documentselection.d.ts +420 -420
  54. package/src/model/documentselection.js +993 -993
  55. package/src/model/element.d.ts +165 -165
  56. package/src/model/element.js +281 -281
  57. package/src/model/history.d.ts +114 -114
  58. package/src/model/history.js +207 -207
  59. package/src/model/item.d.ts +14 -14
  60. package/src/model/item.js +5 -5
  61. package/src/model/liveposition.d.ts +77 -77
  62. package/src/model/liveposition.js +93 -93
  63. package/src/model/liverange.d.ts +102 -102
  64. package/src/model/liverange.js +120 -120
  65. package/src/model/markercollection.d.ts +335 -335
  66. package/src/model/markercollection.js +403 -403
  67. package/src/model/model.d.ts +919 -919
  68. package/src/model/model.js +842 -842
  69. package/src/model/node.d.ts +256 -256
  70. package/src/model/node.js +375 -375
  71. package/src/model/nodelist.d.ts +91 -91
  72. package/src/model/nodelist.js +163 -163
  73. package/src/model/operation/attributeoperation.d.ts +103 -103
  74. package/src/model/operation/attributeoperation.js +148 -148
  75. package/src/model/operation/detachoperation.d.ts +60 -60
  76. package/src/model/operation/detachoperation.js +77 -77
  77. package/src/model/operation/insertoperation.d.ts +90 -90
  78. package/src/model/operation/insertoperation.js +135 -135
  79. package/src/model/operation/markeroperation.d.ts +91 -91
  80. package/src/model/operation/markeroperation.js +107 -107
  81. package/src/model/operation/mergeoperation.d.ts +100 -100
  82. package/src/model/operation/mergeoperation.js +167 -167
  83. package/src/model/operation/moveoperation.d.ts +96 -96
  84. package/src/model/operation/moveoperation.js +164 -164
  85. package/src/model/operation/nooperation.d.ts +38 -38
  86. package/src/model/operation/nooperation.js +48 -48
  87. package/src/model/operation/operation.d.ts +96 -96
  88. package/src/model/operation/operation.js +59 -62
  89. package/src/model/operation/operationfactory.d.ts +18 -18
  90. package/src/model/operation/operationfactory.js +44 -44
  91. package/src/model/operation/renameoperation.d.ts +83 -83
  92. package/src/model/operation/renameoperation.js +115 -115
  93. package/src/model/operation/rootattributeoperation.d.ts +98 -98
  94. package/src/model/operation/rootattributeoperation.js +155 -155
  95. package/src/model/operation/rootoperation.d.ts +76 -76
  96. package/src/model/operation/rootoperation.js +90 -90
  97. package/src/model/operation/splitoperation.d.ts +109 -109
  98. package/src/model/operation/splitoperation.js +194 -194
  99. package/src/model/operation/transform.d.ts +100 -100
  100. package/src/model/operation/transform.js +1985 -1985
  101. package/src/model/operation/utils.d.ts +71 -71
  102. package/src/model/operation/utils.js +217 -213
  103. package/src/model/position.d.ts +539 -539
  104. package/src/model/position.js +979 -979
  105. package/src/model/range.d.ts +458 -458
  106. package/src/model/range.js +875 -875
  107. package/src/model/rootelement.d.ts +60 -60
  108. package/src/model/rootelement.js +74 -74
  109. package/src/model/schema.d.ts +1186 -1186
  110. package/src/model/schema.js +1242 -1242
  111. package/src/model/selection.d.ts +482 -482
  112. package/src/model/selection.js +789 -789
  113. package/src/model/text.d.ts +66 -66
  114. package/src/model/text.js +85 -85
  115. package/src/model/textproxy.d.ts +144 -144
  116. package/src/model/textproxy.js +189 -189
  117. package/src/model/treewalker.d.ts +186 -186
  118. package/src/model/treewalker.js +244 -244
  119. package/src/model/typecheckable.d.ts +285 -285
  120. package/src/model/typecheckable.js +16 -16
  121. package/src/model/utils/autoparagraphing.d.ts +37 -37
  122. package/src/model/utils/autoparagraphing.js +63 -63
  123. package/src/model/utils/deletecontent.d.ts +58 -58
  124. package/src/model/utils/deletecontent.js +488 -488
  125. package/src/model/utils/findoptimalinsertionrange.d.ts +32 -32
  126. package/src/model/utils/findoptimalinsertionrange.js +57 -57
  127. package/src/model/utils/getselectedcontent.d.ts +30 -30
  128. package/src/model/utils/getselectedcontent.js +125 -125
  129. package/src/model/utils/insertcontent.d.ts +46 -46
  130. package/src/model/utils/insertcontent.js +705 -705
  131. package/src/model/utils/insertobject.d.ts +44 -44
  132. package/src/model/utils/insertobject.js +139 -139
  133. package/src/model/utils/modifyselection.d.ts +48 -48
  134. package/src/model/utils/modifyselection.js +186 -186
  135. package/src/model/utils/selection-post-fixer.d.ts +74 -74
  136. package/src/model/utils/selection-post-fixer.js +260 -260
  137. package/src/model/writer.d.ts +851 -851
  138. package/src/model/writer.js +1306 -1306
  139. package/src/view/attributeelement.d.ts +108 -108
  140. package/src/view/attributeelement.js +184 -184
  141. package/src/view/containerelement.d.ts +49 -49
  142. package/src/view/containerelement.js +80 -80
  143. package/src/view/datatransfer.d.ts +79 -79
  144. package/src/view/datatransfer.js +98 -98
  145. package/src/view/document.d.ts +184 -184
  146. package/src/view/document.js +122 -120
  147. package/src/view/documentfragment.d.ts +153 -149
  148. package/src/view/documentfragment.js +234 -228
  149. package/src/view/documentselection.d.ts +306 -306
  150. package/src/view/documentselection.js +256 -256
  151. package/src/view/domconverter.d.ts +652 -640
  152. package/src/view/domconverter.js +1473 -1450
  153. package/src/view/downcastwriter.d.ts +996 -996
  154. package/src/view/downcastwriter.js +1696 -1696
  155. package/src/view/editableelement.d.ts +62 -62
  156. package/src/view/editableelement.js +62 -62
  157. package/src/view/element.d.ts +468 -468
  158. package/src/view/element.js +724 -724
  159. package/src/view/elementdefinition.d.ts +87 -87
  160. package/src/view/elementdefinition.js +5 -5
  161. package/src/view/emptyelement.d.ts +41 -41
  162. package/src/view/emptyelement.js +73 -73
  163. package/src/view/filler.d.ts +111 -111
  164. package/src/view/filler.js +150 -150
  165. package/src/view/item.d.ts +14 -14
  166. package/src/view/item.js +5 -5
  167. package/src/view/matcher.d.ts +486 -486
  168. package/src/view/matcher.js +507 -507
  169. package/src/view/node.d.ts +163 -163
  170. package/src/view/node.js +228 -228
  171. package/src/view/observer/arrowkeysobserver.d.ts +45 -45
  172. package/src/view/observer/arrowkeysobserver.js +40 -40
  173. package/src/view/observer/bubblingemittermixin.d.ts +166 -166
  174. package/src/view/observer/bubblingemittermixin.js +172 -172
  175. package/src/view/observer/bubblingeventinfo.d.ts +47 -47
  176. package/src/view/observer/bubblingeventinfo.js +37 -37
  177. package/src/view/observer/clickobserver.d.ts +43 -43
  178. package/src/view/observer/clickobserver.js +29 -29
  179. package/src/view/observer/compositionobserver.d.ts +82 -82
  180. package/src/view/observer/compositionobserver.js +60 -60
  181. package/src/view/observer/domeventdata.d.ts +50 -50
  182. package/src/view/observer/domeventdata.js +47 -47
  183. package/src/view/observer/domeventobserver.d.ts +73 -73
  184. package/src/view/observer/domeventobserver.js +79 -79
  185. package/src/view/observer/fakeselectionobserver.d.ts +47 -47
  186. package/src/view/observer/fakeselectionobserver.js +91 -91
  187. package/src/view/observer/focusobserver.d.ts +82 -82
  188. package/src/view/observer/focusobserver.js +86 -86
  189. package/src/view/observer/inputobserver.d.ts +86 -86
  190. package/src/view/observer/inputobserver.js +164 -164
  191. package/src/view/observer/keyobserver.d.ts +66 -66
  192. package/src/view/observer/keyobserver.js +39 -39
  193. package/src/view/observer/mouseobserver.d.ts +89 -89
  194. package/src/view/observer/mouseobserver.js +29 -29
  195. package/src/view/observer/mutationobserver.d.ts +86 -86
  196. package/src/view/observer/mutationobserver.js +206 -206
  197. package/src/view/observer/observer.d.ts +89 -89
  198. package/src/view/observer/observer.js +84 -84
  199. package/src/view/observer/selectionobserver.d.ts +148 -148
  200. package/src/view/observer/selectionobserver.js +202 -202
  201. package/src/view/observer/tabobserver.d.ts +46 -46
  202. package/src/view/observer/tabobserver.js +42 -42
  203. package/src/view/placeholder.d.ts +96 -96
  204. package/src/view/placeholder.js +267 -267
  205. package/src/view/position.d.ts +189 -189
  206. package/src/view/position.js +324 -324
  207. package/src/view/range.d.ts +279 -279
  208. package/src/view/range.js +430 -430
  209. package/src/view/rawelement.d.ts +73 -73
  210. package/src/view/rawelement.js +105 -105
  211. package/src/view/renderer.d.ts +265 -265
  212. package/src/view/renderer.js +1000 -999
  213. package/src/view/rooteditableelement.d.ts +41 -41
  214. package/src/view/rooteditableelement.js +69 -69
  215. package/src/view/selection.d.ts +375 -375
  216. package/src/view/selection.js +559 -559
  217. package/src/view/styles/background.d.ts +33 -33
  218. package/src/view/styles/background.js +74 -74
  219. package/src/view/styles/border.d.ts +43 -43
  220. package/src/view/styles/border.js +316 -316
  221. package/src/view/styles/margin.d.ts +29 -29
  222. package/src/view/styles/margin.js +34 -34
  223. package/src/view/styles/padding.d.ts +29 -29
  224. package/src/view/styles/padding.js +34 -34
  225. package/src/view/styles/utils.d.ts +93 -93
  226. package/src/view/styles/utils.js +219 -219
  227. package/src/view/stylesmap.d.ts +675 -675
  228. package/src/view/stylesmap.js +765 -766
  229. package/src/view/text.d.ts +74 -74
  230. package/src/view/text.js +93 -93
  231. package/src/view/textproxy.d.ts +97 -97
  232. package/src/view/textproxy.js +124 -124
  233. package/src/view/treewalker.d.ts +195 -195
  234. package/src/view/treewalker.js +327 -327
  235. package/src/view/typecheckable.d.ts +448 -448
  236. package/src/view/typecheckable.js +19 -19
  237. package/src/view/uielement.d.ts +96 -96
  238. package/src/view/uielement.js +183 -182
  239. package/src/view/upcastwriter.d.ts +417 -417
  240. package/src/view/upcastwriter.js +359 -359
  241. package/src/view/view.d.ts +487 -487
  242. package/src/view/view.js +546 -546
package/src/model/node.js CHANGED
@@ -1,375 +1,375 @@
1
- /**
2
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
3
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
4
- */
5
- /* eslint-disable @typescript-eslint/no-unused-vars */
6
- /**
7
- * @module engine/model/node
8
- */
9
- import TypeCheckable from './typecheckable';
10
- import { CKEditorError, compareArrays, toMap } from '@ckeditor/ckeditor5-utils';
11
- // To check if component is loaded more than once.
12
- import '@ckeditor/ckeditor5-utils/src/version';
13
- /**
14
- * Model node. Most basic structure of model tree.
15
- *
16
- * This is an abstract class that is a base for other classes representing different nodes in model.
17
- *
18
- * **Note:** If a node is detached from the model tree, you can manipulate it using it's API.
19
- * However, it is **very important** that nodes already attached to model tree should be only changed through
20
- * {@link module:engine/model/writer~Writer Writer API}.
21
- *
22
- * Changes done by `Node` methods, like {@link module:engine/model/element~Element#_insertChild _insertChild} or
23
- * {@link module:engine/model/node~Node#_setAttribute _setAttribute}
24
- * do not generate {@link module:engine/model/operation/operation~Operation operations}
25
- * which are essential for correct editor work if you modify nodes in {@link module:engine/model/document~Document document} root.
26
- *
27
- * The flow of working on `Node` (and classes that inherits from it) is as such:
28
- * 1. You can create a `Node` instance, modify it using it's API.
29
- * 2. Add `Node` to the model using `Batch` API.
30
- * 3. Change `Node` that was already added to the model using `Batch` API.
31
- *
32
- * Similarly, you cannot use `Batch` API on a node that has not been added to the model tree, with the exception
33
- * of {@link module:engine/model/writer~Writer#insert inserting} that node to the model tree.
34
- *
35
- * Be aware that using {@link module:engine/model/writer~Writer#remove remove from Batch API} does not allow to use `Node` API because
36
- * the information about `Node` is still kept in model document.
37
- *
38
- * In case of {@link module:engine/model/element~Element element node}, adding and removing children also counts as changing a node and
39
- * follows same rules.
40
- */
41
- export default class Node extends TypeCheckable {
42
- /**
43
- * Creates a model node.
44
- *
45
- * This is an abstract class, so this constructor should not be used directly.
46
- *
47
- * @param attrs Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
48
- */
49
- constructor(attrs) {
50
- super();
51
- /**
52
- * Parent of this node. It could be {@link module:engine/model/element~Element}
53
- * or {@link module:engine/model/documentfragment~DocumentFragment}.
54
- * Equals to `null` if the node has no parent.
55
- */
56
- this.parent = null;
57
- this._attrs = toMap(attrs);
58
- }
59
- /**
60
- * {@link module:engine/model/document~Document Document} that owns this root element.
61
- */
62
- get document() {
63
- return null;
64
- }
65
- /**
66
- * Index of this node in its parent or `null` if the node has no parent.
67
- *
68
- * Accessing this property throws an error if this node's parent element does not contain it.
69
- * This means that model tree got broken.
70
- */
71
- get index() {
72
- let pos;
73
- if (!this.parent) {
74
- return null;
75
- }
76
- if ((pos = this.parent.getChildIndex(this)) === null) {
77
- throw new CKEditorError('model-node-not-found-in-parent', this);
78
- }
79
- return pos;
80
- }
81
- /**
82
- * Offset at which this node starts in its parent. It is equal to the sum of {@link #offsetSize offsetSize}
83
- * of all its previous siblings. Equals to `null` if node has no parent.
84
- *
85
- * Accessing this property throws an error if this node's parent element does not contain it.
86
- * This means that model tree got broken.
87
- */
88
- get startOffset() {
89
- let pos;
90
- if (!this.parent) {
91
- return null;
92
- }
93
- if ((pos = this.parent.getChildStartOffset(this)) === null) {
94
- throw new CKEditorError('model-node-not-found-in-parent', this);
95
- }
96
- return pos;
97
- }
98
- /**
99
- * Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent.
100
- * It is important for {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position
101
- * can be placed between that node start and end. `offsetSize` greater than `1` is for nodes that represents more
102
- * than one entity, i.e. {@link module:engine/model/text~Text text node}.
103
- */
104
- get offsetSize() {
105
- return 1;
106
- }
107
- /**
108
- * Offset at which this node ends in it's parent. It is equal to the sum of this node's
109
- * {@link module:engine/model/node~Node#startOffset start offset} and {@link #offsetSize offset size}.
110
- * Equals to `null` if the node has no parent.
111
- */
112
- get endOffset() {
113
- if (!this.parent) {
114
- return null;
115
- }
116
- return this.startOffset + this.offsetSize;
117
- }
118
- /**
119
- * Node's next sibling or `null` if the node is a last child of it's parent or if the node has no parent.
120
- */
121
- get nextSibling() {
122
- const index = this.index;
123
- return (index !== null && this.parent.getChild(index + 1)) || null;
124
- }
125
- /**
126
- * Node's previous sibling or `null` if the node is a first child of it's parent or if the node has no parent.
127
- */
128
- get previousSibling() {
129
- const index = this.index;
130
- return (index !== null && this.parent.getChild(index - 1)) || null;
131
- }
132
- /**
133
- * The top-most ancestor of the node. If node has no parent it is the root itself. If the node is a part
134
- * of {@link module:engine/model/documentfragment~DocumentFragment}, it's `root` is equal to that `DocumentFragment`.
135
- */
136
- get root() {
137
- // eslint-disable-next-line @typescript-eslint/no-this-alias, consistent-this
138
- let root = this;
139
- while (root.parent) {
140
- root = root.parent;
141
- }
142
- return root;
143
- }
144
- /**
145
- * Returns `true` if the node is inside a document root that is attached to the document.
146
- */
147
- isAttached() {
148
- // If the node has no parent it means that it is a root.
149
- // But this is not a `RootElement`, so it means that it is not attached.
150
- //
151
- // If this is not the root, check if this element's root is attached.
152
- return this.parent === null ? false : this.root.isAttached();
153
- }
154
- /**
155
- * Gets path to the node. The path is an array containing starting offsets of consecutive ancestors of this node,
156
- * beginning from {@link module:engine/model/node~Node#root root}, down to this node's starting offset. The path can be used to
157
- * create {@link module:engine/model/position~Position Position} instance.
158
- *
159
- * ```ts
160
- * const abc = new Text( 'abc' );
161
- * const foo = new Text( 'foo' );
162
- * const h1 = new Element( 'h1', null, new Text( 'header' ) );
163
- * const p = new Element( 'p', null, [ abc, foo ] );
164
- * const div = new Element( 'div', null, [ h1, p ] );
165
- * foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3.
166
- * h1.getPath(); // Returns [ 0 ].
167
- * div.getPath(); // Returns [].
168
- * ```
169
- */
170
- getPath() {
171
- const path = [];
172
- // eslint-disable-next-line @typescript-eslint/no-this-alias, consistent-this
173
- let node = this;
174
- while (node.parent) {
175
- path.unshift(node.startOffset);
176
- node = node.parent;
177
- }
178
- return path;
179
- }
180
- /**
181
- * Returns ancestors array of this node.
182
- *
183
- * @param options Options object.
184
- * @param options.includeSelf When set to `true` this node will be also included in parent's array.
185
- * @param options.parentFirst When set to `true`, array will be sorted from node's parent to root element,
186
- * otherwise root element will be the first item in the array.
187
- * @returns Array with ancestors.
188
- */
189
- getAncestors(options = {}) {
190
- const ancestors = [];
191
- let parent = options.includeSelf ? this : this.parent;
192
- while (parent) {
193
- ancestors[options.parentFirst ? 'push' : 'unshift'](parent);
194
- parent = parent.parent;
195
- }
196
- return ancestors;
197
- }
198
- /**
199
- * Returns a {@link module:engine/model/element~Element} or {@link module:engine/model/documentfragment~DocumentFragment}
200
- * which is a common ancestor of both nodes.
201
- *
202
- * @param node The second node.
203
- * @param options Options object.
204
- * @param options.includeSelf When set to `true` both nodes will be considered "ancestors" too.
205
- * Which means that if e.g. node A is inside B, then their common ancestor will be B.
206
- */
207
- getCommonAncestor(node, options = {}) {
208
- const ancestorsA = this.getAncestors(options);
209
- const ancestorsB = node.getAncestors(options);
210
- let i = 0;
211
- while (ancestorsA[i] == ancestorsB[i] && ancestorsA[i]) {
212
- i++;
213
- }
214
- return i === 0 ? null : ancestorsA[i - 1];
215
- }
216
- /**
217
- * Returns whether this node is before given node. `false` is returned if nodes are in different trees (for example,
218
- * in different {@link module:engine/model/documentfragment~DocumentFragment}s).
219
- *
220
- * @param node Node to compare with.
221
- */
222
- isBefore(node) {
223
- // Given node is not before this node if they are same.
224
- if (this == node) {
225
- return false;
226
- }
227
- // Return `false` if it is impossible to compare nodes.
228
- if (this.root !== node.root) {
229
- return false;
230
- }
231
- const thisPath = this.getPath();
232
- const nodePath = node.getPath();
233
- const result = compareArrays(thisPath, nodePath);
234
- switch (result) {
235
- case 'prefix':
236
- return true;
237
- case 'extension':
238
- return false;
239
- default:
240
- return thisPath[result] < nodePath[result];
241
- }
242
- }
243
- /**
244
- * Returns whether this node is after given node. `false` is returned if nodes are in different trees (for example,
245
- * in different {@link module:engine/model/documentfragment~DocumentFragment}s).
246
- *
247
- * @param node Node to compare with.
248
- */
249
- isAfter(node) {
250
- // Given node is not before this node if they are same.
251
- if (this == node) {
252
- return false;
253
- }
254
- // Return `false` if it is impossible to compare nodes.
255
- if (this.root !== node.root) {
256
- return false;
257
- }
258
- // In other cases, just check if the `node` is before, and return the opposite.
259
- return !this.isBefore(node);
260
- }
261
- /**
262
- * Checks if the node has an attribute with given key.
263
- *
264
- * @param key Key of attribute to check.
265
- * @returns `true` if attribute with given key is set on node, `false` otherwise.
266
- */
267
- hasAttribute(key) {
268
- return this._attrs.has(key);
269
- }
270
- /**
271
- * Gets an attribute value for given key or `undefined` if that attribute is not set on node.
272
- *
273
- * @param key Key of attribute to look for.
274
- * @returns Attribute value or `undefined`.
275
- */
276
- getAttribute(key) {
277
- return this._attrs.get(key);
278
- }
279
- /**
280
- * Returns iterator that iterates over this node's attributes.
281
- *
282
- * Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value.
283
- * This format is accepted by native `Map` object and also can be passed in `Node` constructor.
284
- */
285
- getAttributes() {
286
- return this._attrs.entries();
287
- }
288
- /**
289
- * Returns iterator that iterates over this node's attribute keys.
290
- */
291
- getAttributeKeys() {
292
- return this._attrs.keys();
293
- }
294
- /**
295
- * Converts `Node` to plain object and returns it.
296
- *
297
- * @returns `Node` converted to plain object.
298
- */
299
- toJSON() {
300
- const json = {};
301
- // Serializes attributes to the object.
302
- // attributes = { a: 'foo', b: 1, c: true }.
303
- if (this._attrs.size) {
304
- json.attributes = Array.from(this._attrs).reduce((result, attr) => {
305
- result[attr[0]] = attr[1];
306
- return result;
307
- }, {});
308
- }
309
- return json;
310
- }
311
- /**
312
- * Creates a copy of this node, that is a node with exactly same attributes, and returns it.
313
- *
314
- * @internal
315
- * @returns Node with same attributes as this node.
316
- */
317
- _clone(_deep) {
318
- return new this.constructor(this._attrs);
319
- }
320
- /**
321
- * Removes this node from it's parent.
322
- *
323
- * @internal
324
- * @see module:engine/model/writer~Writer#remove
325
- */
326
- _remove() {
327
- this.parent._removeChildren(this.index);
328
- }
329
- /**
330
- * Sets attribute on the node. If attribute with the same key already is set, it's value is overwritten.
331
- *
332
- * @see module:engine/model/writer~Writer#setAttribute
333
- * @internal
334
- * @param key Key of attribute to set.
335
- * @param value Attribute value.
336
- */
337
- _setAttribute(key, value) {
338
- this._attrs.set(key, value);
339
- }
340
- /**
341
- * Removes all attributes from the node and sets given attributes.
342
- *
343
- * @see module:engine/model/writer~Writer#setAttributes
344
- * @internal
345
- * @param attrs Attributes to set. See {@link module:utils/tomap~toMap} for a list of accepted values.
346
- */
347
- _setAttributesTo(attrs) {
348
- this._attrs = toMap(attrs);
349
- }
350
- /**
351
- * Removes an attribute with given key from the node.
352
- *
353
- * @see module:engine/model/writer~Writer#removeAttribute
354
- * @internal
355
- * @param key Key of attribute to remove.
356
- * @returns `true` if the attribute was set on the element, `false` otherwise.
357
- */
358
- _removeAttribute(key) {
359
- return this._attrs.delete(key);
360
- }
361
- /**
362
- * Removes all attributes from the node.
363
- *
364
- * @see module:engine/model/writer~Writer#clearAttributes
365
- * @internal
366
- */
367
- _clearAttributes() {
368
- this._attrs.clear();
369
- }
370
- }
371
- // The magic of type inference using `is` method is centralized in `TypeCheckable` class.
372
- // Proper overload would interfere with that.
373
- Node.prototype.is = function (type) {
374
- return type === 'node' || type === 'model:node';
375
- };
1
+ /**
2
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
4
+ */
5
+ /* eslint-disable @typescript-eslint/no-unused-vars */
6
+ /**
7
+ * @module engine/model/node
8
+ */
9
+ import TypeCheckable from './typecheckable';
10
+ import { CKEditorError, compareArrays, toMap } from '@ckeditor/ckeditor5-utils';
11
+ // To check if component is loaded more than once.
12
+ import '@ckeditor/ckeditor5-utils/src/version';
13
+ /**
14
+ * Model node. Most basic structure of model tree.
15
+ *
16
+ * This is an abstract class that is a base for other classes representing different nodes in model.
17
+ *
18
+ * **Note:** If a node is detached from the model tree, you can manipulate it using it's API.
19
+ * However, it is **very important** that nodes already attached to model tree should be only changed through
20
+ * {@link module:engine/model/writer~Writer Writer API}.
21
+ *
22
+ * Changes done by `Node` methods, like {@link module:engine/model/element~Element#_insertChild _insertChild} or
23
+ * {@link module:engine/model/node~Node#_setAttribute _setAttribute}
24
+ * do not generate {@link module:engine/model/operation/operation~Operation operations}
25
+ * which are essential for correct editor work if you modify nodes in {@link module:engine/model/document~Document document} root.
26
+ *
27
+ * The flow of working on `Node` (and classes that inherits from it) is as such:
28
+ * 1. You can create a `Node` instance, modify it using it's API.
29
+ * 2. Add `Node` to the model using `Batch` API.
30
+ * 3. Change `Node` that was already added to the model using `Batch` API.
31
+ *
32
+ * Similarly, you cannot use `Batch` API on a node that has not been added to the model tree, with the exception
33
+ * of {@link module:engine/model/writer~Writer#insert inserting} that node to the model tree.
34
+ *
35
+ * Be aware that using {@link module:engine/model/writer~Writer#remove remove from Batch API} does not allow to use `Node` API because
36
+ * the information about `Node` is still kept in model document.
37
+ *
38
+ * In case of {@link module:engine/model/element~Element element node}, adding and removing children also counts as changing a node and
39
+ * follows same rules.
40
+ */
41
+ export default class Node extends TypeCheckable {
42
+ /**
43
+ * Creates a model node.
44
+ *
45
+ * This is an abstract class, so this constructor should not be used directly.
46
+ *
47
+ * @param attrs Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
48
+ */
49
+ constructor(attrs) {
50
+ super();
51
+ /**
52
+ * Parent of this node. It could be {@link module:engine/model/element~Element}
53
+ * or {@link module:engine/model/documentfragment~DocumentFragment}.
54
+ * Equals to `null` if the node has no parent.
55
+ */
56
+ this.parent = null;
57
+ this._attrs = toMap(attrs);
58
+ }
59
+ /**
60
+ * {@link module:engine/model/document~Document Document} that owns this root element.
61
+ */
62
+ get document() {
63
+ return null;
64
+ }
65
+ /**
66
+ * Index of this node in its parent or `null` if the node has no parent.
67
+ *
68
+ * Accessing this property throws an error if this node's parent element does not contain it.
69
+ * This means that model tree got broken.
70
+ */
71
+ get index() {
72
+ let pos;
73
+ if (!this.parent) {
74
+ return null;
75
+ }
76
+ if ((pos = this.parent.getChildIndex(this)) === null) {
77
+ throw new CKEditorError('model-node-not-found-in-parent', this);
78
+ }
79
+ return pos;
80
+ }
81
+ /**
82
+ * Offset at which this node starts in its parent. It is equal to the sum of {@link #offsetSize offsetSize}
83
+ * of all its previous siblings. Equals to `null` if node has no parent.
84
+ *
85
+ * Accessing this property throws an error if this node's parent element does not contain it.
86
+ * This means that model tree got broken.
87
+ */
88
+ get startOffset() {
89
+ let pos;
90
+ if (!this.parent) {
91
+ return null;
92
+ }
93
+ if ((pos = this.parent.getChildStartOffset(this)) === null) {
94
+ throw new CKEditorError('model-node-not-found-in-parent', this);
95
+ }
96
+ return pos;
97
+ }
98
+ /**
99
+ * Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent.
100
+ * It is important for {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position
101
+ * can be placed between that node start and end. `offsetSize` greater than `1` is for nodes that represents more
102
+ * than one entity, i.e. {@link module:engine/model/text~Text text node}.
103
+ */
104
+ get offsetSize() {
105
+ return 1;
106
+ }
107
+ /**
108
+ * Offset at which this node ends in it's parent. It is equal to the sum of this node's
109
+ * {@link module:engine/model/node~Node#startOffset start offset} and {@link #offsetSize offset size}.
110
+ * Equals to `null` if the node has no parent.
111
+ */
112
+ get endOffset() {
113
+ if (!this.parent) {
114
+ return null;
115
+ }
116
+ return this.startOffset + this.offsetSize;
117
+ }
118
+ /**
119
+ * Node's next sibling or `null` if the node is a last child of it's parent or if the node has no parent.
120
+ */
121
+ get nextSibling() {
122
+ const index = this.index;
123
+ return (index !== null && this.parent.getChild(index + 1)) || null;
124
+ }
125
+ /**
126
+ * Node's previous sibling or `null` if the node is a first child of it's parent or if the node has no parent.
127
+ */
128
+ get previousSibling() {
129
+ const index = this.index;
130
+ return (index !== null && this.parent.getChild(index - 1)) || null;
131
+ }
132
+ /**
133
+ * The top-most ancestor of the node. If node has no parent it is the root itself. If the node is a part
134
+ * of {@link module:engine/model/documentfragment~DocumentFragment}, it's `root` is equal to that `DocumentFragment`.
135
+ */
136
+ get root() {
137
+ // eslint-disable-next-line @typescript-eslint/no-this-alias, consistent-this
138
+ let root = this;
139
+ while (root.parent) {
140
+ root = root.parent;
141
+ }
142
+ return root;
143
+ }
144
+ /**
145
+ * Returns `true` if the node is inside a document root that is attached to the document.
146
+ */
147
+ isAttached() {
148
+ // If the node has no parent it means that it is a root.
149
+ // But this is not a `RootElement`, so it means that it is not attached.
150
+ //
151
+ // If this is not the root, check if this element's root is attached.
152
+ return this.parent === null ? false : this.root.isAttached();
153
+ }
154
+ /**
155
+ * Gets path to the node. The path is an array containing starting offsets of consecutive ancestors of this node,
156
+ * beginning from {@link module:engine/model/node~Node#root root}, down to this node's starting offset. The path can be used to
157
+ * create {@link module:engine/model/position~Position Position} instance.
158
+ *
159
+ * ```ts
160
+ * const abc = new Text( 'abc' );
161
+ * const foo = new Text( 'foo' );
162
+ * const h1 = new Element( 'h1', null, new Text( 'header' ) );
163
+ * const p = new Element( 'p', null, [ abc, foo ] );
164
+ * const div = new Element( 'div', null, [ h1, p ] );
165
+ * foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3.
166
+ * h1.getPath(); // Returns [ 0 ].
167
+ * div.getPath(); // Returns [].
168
+ * ```
169
+ */
170
+ getPath() {
171
+ const path = [];
172
+ // eslint-disable-next-line @typescript-eslint/no-this-alias, consistent-this
173
+ let node = this;
174
+ while (node.parent) {
175
+ path.unshift(node.startOffset);
176
+ node = node.parent;
177
+ }
178
+ return path;
179
+ }
180
+ /**
181
+ * Returns ancestors array of this node.
182
+ *
183
+ * @param options Options object.
184
+ * @param options.includeSelf When set to `true` this node will be also included in parent's array.
185
+ * @param options.parentFirst When set to `true`, array will be sorted from node's parent to root element,
186
+ * otherwise root element will be the first item in the array.
187
+ * @returns Array with ancestors.
188
+ */
189
+ getAncestors(options = {}) {
190
+ const ancestors = [];
191
+ let parent = options.includeSelf ? this : this.parent;
192
+ while (parent) {
193
+ ancestors[options.parentFirst ? 'push' : 'unshift'](parent);
194
+ parent = parent.parent;
195
+ }
196
+ return ancestors;
197
+ }
198
+ /**
199
+ * Returns a {@link module:engine/model/element~Element} or {@link module:engine/model/documentfragment~DocumentFragment}
200
+ * which is a common ancestor of both nodes.
201
+ *
202
+ * @param node The second node.
203
+ * @param options Options object.
204
+ * @param options.includeSelf When set to `true` both nodes will be considered "ancestors" too.
205
+ * Which means that if e.g. node A is inside B, then their common ancestor will be B.
206
+ */
207
+ getCommonAncestor(node, options = {}) {
208
+ const ancestorsA = this.getAncestors(options);
209
+ const ancestorsB = node.getAncestors(options);
210
+ let i = 0;
211
+ while (ancestorsA[i] == ancestorsB[i] && ancestorsA[i]) {
212
+ i++;
213
+ }
214
+ return i === 0 ? null : ancestorsA[i - 1];
215
+ }
216
+ /**
217
+ * Returns whether this node is before given node. `false` is returned if nodes are in different trees (for example,
218
+ * in different {@link module:engine/model/documentfragment~DocumentFragment}s).
219
+ *
220
+ * @param node Node to compare with.
221
+ */
222
+ isBefore(node) {
223
+ // Given node is not before this node if they are same.
224
+ if (this == node) {
225
+ return false;
226
+ }
227
+ // Return `false` if it is impossible to compare nodes.
228
+ if (this.root !== node.root) {
229
+ return false;
230
+ }
231
+ const thisPath = this.getPath();
232
+ const nodePath = node.getPath();
233
+ const result = compareArrays(thisPath, nodePath);
234
+ switch (result) {
235
+ case 'prefix':
236
+ return true;
237
+ case 'extension':
238
+ return false;
239
+ default:
240
+ return thisPath[result] < nodePath[result];
241
+ }
242
+ }
243
+ /**
244
+ * Returns whether this node is after given node. `false` is returned if nodes are in different trees (for example,
245
+ * in different {@link module:engine/model/documentfragment~DocumentFragment}s).
246
+ *
247
+ * @param node Node to compare with.
248
+ */
249
+ isAfter(node) {
250
+ // Given node is not before this node if they are same.
251
+ if (this == node) {
252
+ return false;
253
+ }
254
+ // Return `false` if it is impossible to compare nodes.
255
+ if (this.root !== node.root) {
256
+ return false;
257
+ }
258
+ // In other cases, just check if the `node` is before, and return the opposite.
259
+ return !this.isBefore(node);
260
+ }
261
+ /**
262
+ * Checks if the node has an attribute with given key.
263
+ *
264
+ * @param key Key of attribute to check.
265
+ * @returns `true` if attribute with given key is set on node, `false` otherwise.
266
+ */
267
+ hasAttribute(key) {
268
+ return this._attrs.has(key);
269
+ }
270
+ /**
271
+ * Gets an attribute value for given key or `undefined` if that attribute is not set on node.
272
+ *
273
+ * @param key Key of attribute to look for.
274
+ * @returns Attribute value or `undefined`.
275
+ */
276
+ getAttribute(key) {
277
+ return this._attrs.get(key);
278
+ }
279
+ /**
280
+ * Returns iterator that iterates over this node's attributes.
281
+ *
282
+ * Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value.
283
+ * This format is accepted by native `Map` object and also can be passed in `Node` constructor.
284
+ */
285
+ getAttributes() {
286
+ return this._attrs.entries();
287
+ }
288
+ /**
289
+ * Returns iterator that iterates over this node's attribute keys.
290
+ */
291
+ getAttributeKeys() {
292
+ return this._attrs.keys();
293
+ }
294
+ /**
295
+ * Converts `Node` to plain object and returns it.
296
+ *
297
+ * @returns `Node` converted to plain object.
298
+ */
299
+ toJSON() {
300
+ const json = {};
301
+ // Serializes attributes to the object.
302
+ // attributes = { a: 'foo', b: 1, c: true }.
303
+ if (this._attrs.size) {
304
+ json.attributes = Array.from(this._attrs).reduce((result, attr) => {
305
+ result[attr[0]] = attr[1];
306
+ return result;
307
+ }, {});
308
+ }
309
+ return json;
310
+ }
311
+ /**
312
+ * Creates a copy of this node, that is a node with exactly same attributes, and returns it.
313
+ *
314
+ * @internal
315
+ * @returns Node with same attributes as this node.
316
+ */
317
+ _clone(_deep) {
318
+ return new this.constructor(this._attrs);
319
+ }
320
+ /**
321
+ * Removes this node from it's parent.
322
+ *
323
+ * @internal
324
+ * @see module:engine/model/writer~Writer#remove
325
+ */
326
+ _remove() {
327
+ this.parent._removeChildren(this.index);
328
+ }
329
+ /**
330
+ * Sets attribute on the node. If attribute with the same key already is set, it's value is overwritten.
331
+ *
332
+ * @see module:engine/model/writer~Writer#setAttribute
333
+ * @internal
334
+ * @param key Key of attribute to set.
335
+ * @param value Attribute value.
336
+ */
337
+ _setAttribute(key, value) {
338
+ this._attrs.set(key, value);
339
+ }
340
+ /**
341
+ * Removes all attributes from the node and sets given attributes.
342
+ *
343
+ * @see module:engine/model/writer~Writer#setAttributes
344
+ * @internal
345
+ * @param attrs Attributes to set. See {@link module:utils/tomap~toMap} for a list of accepted values.
346
+ */
347
+ _setAttributesTo(attrs) {
348
+ this._attrs = toMap(attrs);
349
+ }
350
+ /**
351
+ * Removes an attribute with given key from the node.
352
+ *
353
+ * @see module:engine/model/writer~Writer#removeAttribute
354
+ * @internal
355
+ * @param key Key of attribute to remove.
356
+ * @returns `true` if the attribute was set on the element, `false` otherwise.
357
+ */
358
+ _removeAttribute(key) {
359
+ return this._attrs.delete(key);
360
+ }
361
+ /**
362
+ * Removes all attributes from the node.
363
+ *
364
+ * @see module:engine/model/writer~Writer#clearAttributes
365
+ * @internal
366
+ */
367
+ _clearAttributes() {
368
+ this._attrs.clear();
369
+ }
370
+ }
371
+ // The magic of type inference using `is` method is centralized in `TypeCheckable` class.
372
+ // Proper overload would interfere with that.
373
+ Node.prototype.is = function (type) {
374
+ return type === 'node' || type === 'model:node';
375
+ };