@ckeditor/ckeditor5-engine 40.0.0 → 40.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 (243) hide show
  1. package/CHANGELOG.md +39 -39
  2. package/LICENSE.md +3 -3
  3. package/package.json +2 -2
  4. package/src/controller/datacontroller.d.ts +334 -334
  5. package/src/controller/datacontroller.js +481 -481
  6. package/src/controller/editingcontroller.d.ts +98 -98
  7. package/src/controller/editingcontroller.js +191 -191
  8. package/src/conversion/conversion.d.ts +478 -478
  9. package/src/conversion/conversion.js +601 -601
  10. package/src/conversion/conversionhelpers.d.ts +26 -26
  11. package/src/conversion/conversionhelpers.js +32 -32
  12. package/src/conversion/downcastdispatcher.d.ts +562 -562
  13. package/src/conversion/downcastdispatcher.js +548 -547
  14. package/src/conversion/downcasthelpers.d.ts +1226 -1226
  15. package/src/conversion/downcasthelpers.js +2178 -2183
  16. package/src/conversion/mapper.d.ts +503 -503
  17. package/src/conversion/mapper.js +536 -536
  18. package/src/conversion/modelconsumable.d.ts +201 -201
  19. package/src/conversion/modelconsumable.js +333 -333
  20. package/src/conversion/upcastdispatcher.d.ts +492 -492
  21. package/src/conversion/upcastdispatcher.js +460 -460
  22. package/src/conversion/upcasthelpers.d.ts +499 -499
  23. package/src/conversion/upcasthelpers.js +950 -950
  24. package/src/conversion/viewconsumable.d.ts +369 -369
  25. package/src/conversion/viewconsumable.js +536 -532
  26. package/src/dataprocessor/basichtmlwriter.d.ts +18 -18
  27. package/src/dataprocessor/basichtmlwriter.js +20 -19
  28. package/src/dataprocessor/dataprocessor.d.ts +61 -61
  29. package/src/dataprocessor/dataprocessor.js +5 -5
  30. package/src/dataprocessor/htmldataprocessor.d.ts +76 -76
  31. package/src/dataprocessor/htmldataprocessor.js +96 -96
  32. package/src/dataprocessor/htmlwriter.d.ts +16 -16
  33. package/src/dataprocessor/htmlwriter.js +5 -5
  34. package/src/dataprocessor/xmldataprocessor.d.ts +90 -90
  35. package/src/dataprocessor/xmldataprocessor.js +108 -108
  36. package/src/dev-utils/model.d.ts +124 -124
  37. package/src/dev-utils/model.js +395 -395
  38. package/src/dev-utils/operationreplayer.d.ts +51 -51
  39. package/src/dev-utils/operationreplayer.js +112 -112
  40. package/src/dev-utils/utils.d.ts +37 -37
  41. package/src/dev-utils/utils.js +73 -73
  42. package/src/dev-utils/view.d.ts +319 -319
  43. package/src/dev-utils/view.js +967 -967
  44. package/src/index.d.ts +114 -114
  45. package/src/index.js +78 -78
  46. package/src/model/batch.d.ts +106 -106
  47. package/src/model/batch.js +96 -96
  48. package/src/model/differ.d.ts +387 -387
  49. package/src/model/differ.js +1149 -1149
  50. package/src/model/document.d.ts +272 -272
  51. package/src/model/document.js +360 -361
  52. package/src/model/documentfragment.d.ts +200 -200
  53. package/src/model/documentfragment.js +306 -306
  54. package/src/model/documentselection.d.ts +420 -420
  55. package/src/model/documentselection.js +993 -993
  56. package/src/model/element.d.ts +165 -165
  57. package/src/model/element.js +281 -281
  58. package/src/model/history.d.ts +114 -114
  59. package/src/model/history.js +207 -207
  60. package/src/model/item.d.ts +14 -14
  61. package/src/model/item.js +5 -5
  62. package/src/model/liveposition.d.ts +77 -77
  63. package/src/model/liveposition.js +93 -93
  64. package/src/model/liverange.d.ts +102 -102
  65. package/src/model/liverange.js +120 -120
  66. package/src/model/markercollection.d.ts +335 -335
  67. package/src/model/markercollection.js +403 -403
  68. package/src/model/model.d.ts +919 -919
  69. package/src/model/model.js +842 -842
  70. package/src/model/node.d.ts +256 -256
  71. package/src/model/node.js +375 -375
  72. package/src/model/nodelist.d.ts +91 -91
  73. package/src/model/nodelist.js +163 -163
  74. package/src/model/operation/attributeoperation.d.ts +103 -103
  75. package/src/model/operation/attributeoperation.js +148 -148
  76. package/src/model/operation/detachoperation.d.ts +60 -60
  77. package/src/model/operation/detachoperation.js +77 -77
  78. package/src/model/operation/insertoperation.d.ts +90 -90
  79. package/src/model/operation/insertoperation.js +135 -135
  80. package/src/model/operation/markeroperation.d.ts +91 -91
  81. package/src/model/operation/markeroperation.js +107 -107
  82. package/src/model/operation/mergeoperation.d.ts +100 -100
  83. package/src/model/operation/mergeoperation.js +167 -167
  84. package/src/model/operation/moveoperation.d.ts +96 -96
  85. package/src/model/operation/moveoperation.js +164 -164
  86. package/src/model/operation/nooperation.d.ts +38 -38
  87. package/src/model/operation/nooperation.js +48 -48
  88. package/src/model/operation/operation.d.ts +96 -96
  89. package/src/model/operation/operation.js +59 -62
  90. package/src/model/operation/operationfactory.d.ts +18 -18
  91. package/src/model/operation/operationfactory.js +44 -44
  92. package/src/model/operation/renameoperation.d.ts +83 -83
  93. package/src/model/operation/renameoperation.js +115 -115
  94. package/src/model/operation/rootattributeoperation.d.ts +98 -98
  95. package/src/model/operation/rootattributeoperation.js +155 -155
  96. package/src/model/operation/rootoperation.d.ts +76 -76
  97. package/src/model/operation/rootoperation.js +90 -90
  98. package/src/model/operation/splitoperation.d.ts +109 -109
  99. package/src/model/operation/splitoperation.js +194 -194
  100. package/src/model/operation/transform.d.ts +100 -100
  101. package/src/model/operation/transform.js +1985 -1985
  102. package/src/model/operation/utils.d.ts +71 -71
  103. package/src/model/operation/utils.js +217 -213
  104. package/src/model/position.d.ts +539 -539
  105. package/src/model/position.js +979 -979
  106. package/src/model/range.d.ts +458 -458
  107. package/src/model/range.js +875 -875
  108. package/src/model/rootelement.d.ts +60 -60
  109. package/src/model/rootelement.js +74 -74
  110. package/src/model/schema.d.ts +1186 -1186
  111. package/src/model/schema.js +1242 -1242
  112. package/src/model/selection.d.ts +482 -482
  113. package/src/model/selection.js +789 -789
  114. package/src/model/text.d.ts +66 -66
  115. package/src/model/text.js +85 -85
  116. package/src/model/textproxy.d.ts +144 -144
  117. package/src/model/textproxy.js +189 -189
  118. package/src/model/treewalker.d.ts +186 -186
  119. package/src/model/treewalker.js +244 -244
  120. package/src/model/typecheckable.d.ts +285 -285
  121. package/src/model/typecheckable.js +16 -16
  122. package/src/model/utils/autoparagraphing.d.ts +37 -37
  123. package/src/model/utils/autoparagraphing.js +63 -63
  124. package/src/model/utils/deletecontent.d.ts +58 -58
  125. package/src/model/utils/deletecontent.js +488 -488
  126. package/src/model/utils/findoptimalinsertionrange.d.ts +32 -32
  127. package/src/model/utils/findoptimalinsertionrange.js +57 -57
  128. package/src/model/utils/getselectedcontent.d.ts +30 -30
  129. package/src/model/utils/getselectedcontent.js +125 -125
  130. package/src/model/utils/insertcontent.d.ts +46 -46
  131. package/src/model/utils/insertcontent.js +705 -705
  132. package/src/model/utils/insertobject.d.ts +44 -44
  133. package/src/model/utils/insertobject.js +139 -139
  134. package/src/model/utils/modifyselection.d.ts +48 -48
  135. package/src/model/utils/modifyselection.js +186 -186
  136. package/src/model/utils/selection-post-fixer.d.ts +74 -74
  137. package/src/model/utils/selection-post-fixer.js +260 -260
  138. package/src/model/writer.d.ts +851 -851
  139. package/src/model/writer.js +1306 -1306
  140. package/src/view/attributeelement.d.ts +108 -108
  141. package/src/view/attributeelement.js +184 -184
  142. package/src/view/containerelement.d.ts +49 -49
  143. package/src/view/containerelement.js +80 -80
  144. package/src/view/datatransfer.d.ts +79 -79
  145. package/src/view/datatransfer.js +98 -98
  146. package/src/view/document.d.ts +184 -184
  147. package/src/view/document.js +122 -120
  148. package/src/view/documentfragment.d.ts +153 -149
  149. package/src/view/documentfragment.js +234 -228
  150. package/src/view/documentselection.d.ts +306 -306
  151. package/src/view/documentselection.js +256 -256
  152. package/src/view/domconverter.d.ts +652 -640
  153. package/src/view/domconverter.js +1473 -1450
  154. package/src/view/downcastwriter.d.ts +996 -996
  155. package/src/view/downcastwriter.js +1696 -1696
  156. package/src/view/editableelement.d.ts +62 -62
  157. package/src/view/editableelement.js +62 -62
  158. package/src/view/element.d.ts +468 -468
  159. package/src/view/element.js +724 -724
  160. package/src/view/elementdefinition.d.ts +87 -87
  161. package/src/view/elementdefinition.js +5 -5
  162. package/src/view/emptyelement.d.ts +41 -41
  163. package/src/view/emptyelement.js +73 -73
  164. package/src/view/filler.d.ts +111 -111
  165. package/src/view/filler.js +150 -150
  166. package/src/view/item.d.ts +14 -14
  167. package/src/view/item.js +5 -5
  168. package/src/view/matcher.d.ts +486 -486
  169. package/src/view/matcher.js +507 -507
  170. package/src/view/node.d.ts +163 -163
  171. package/src/view/node.js +228 -228
  172. package/src/view/observer/arrowkeysobserver.d.ts +45 -45
  173. package/src/view/observer/arrowkeysobserver.js +40 -40
  174. package/src/view/observer/bubblingemittermixin.d.ts +166 -166
  175. package/src/view/observer/bubblingemittermixin.js +172 -172
  176. package/src/view/observer/bubblingeventinfo.d.ts +47 -47
  177. package/src/view/observer/bubblingeventinfo.js +37 -37
  178. package/src/view/observer/clickobserver.d.ts +43 -43
  179. package/src/view/observer/clickobserver.js +29 -29
  180. package/src/view/observer/compositionobserver.d.ts +82 -82
  181. package/src/view/observer/compositionobserver.js +60 -60
  182. package/src/view/observer/domeventdata.d.ts +50 -50
  183. package/src/view/observer/domeventdata.js +47 -47
  184. package/src/view/observer/domeventobserver.d.ts +73 -73
  185. package/src/view/observer/domeventobserver.js +79 -79
  186. package/src/view/observer/fakeselectionobserver.d.ts +47 -47
  187. package/src/view/observer/fakeselectionobserver.js +91 -91
  188. package/src/view/observer/focusobserver.d.ts +82 -82
  189. package/src/view/observer/focusobserver.js +86 -86
  190. package/src/view/observer/inputobserver.d.ts +86 -86
  191. package/src/view/observer/inputobserver.js +164 -164
  192. package/src/view/observer/keyobserver.d.ts +66 -66
  193. package/src/view/observer/keyobserver.js +39 -39
  194. package/src/view/observer/mouseobserver.d.ts +89 -89
  195. package/src/view/observer/mouseobserver.js +29 -29
  196. package/src/view/observer/mutationobserver.d.ts +86 -86
  197. package/src/view/observer/mutationobserver.js +206 -206
  198. package/src/view/observer/observer.d.ts +89 -89
  199. package/src/view/observer/observer.js +84 -84
  200. package/src/view/observer/selectionobserver.d.ts +148 -148
  201. package/src/view/observer/selectionobserver.js +202 -202
  202. package/src/view/observer/tabobserver.d.ts +46 -46
  203. package/src/view/observer/tabobserver.js +42 -42
  204. package/src/view/placeholder.d.ts +96 -96
  205. package/src/view/placeholder.js +267 -267
  206. package/src/view/position.d.ts +189 -189
  207. package/src/view/position.js +324 -324
  208. package/src/view/range.d.ts +279 -279
  209. package/src/view/range.js +430 -430
  210. package/src/view/rawelement.d.ts +73 -73
  211. package/src/view/rawelement.js +105 -105
  212. package/src/view/renderer.d.ts +265 -265
  213. package/src/view/renderer.js +1000 -999
  214. package/src/view/rooteditableelement.d.ts +41 -41
  215. package/src/view/rooteditableelement.js +69 -69
  216. package/src/view/selection.d.ts +375 -375
  217. package/src/view/selection.js +559 -559
  218. package/src/view/styles/background.d.ts +33 -33
  219. package/src/view/styles/background.js +74 -74
  220. package/src/view/styles/border.d.ts +43 -43
  221. package/src/view/styles/border.js +316 -316
  222. package/src/view/styles/margin.d.ts +29 -29
  223. package/src/view/styles/margin.js +34 -34
  224. package/src/view/styles/padding.d.ts +29 -29
  225. package/src/view/styles/padding.js +34 -34
  226. package/src/view/styles/utils.d.ts +93 -93
  227. package/src/view/styles/utils.js +219 -219
  228. package/src/view/stylesmap.d.ts +675 -675
  229. package/src/view/stylesmap.js +765 -766
  230. package/src/view/text.d.ts +74 -74
  231. package/src/view/text.js +93 -93
  232. package/src/view/textproxy.d.ts +97 -97
  233. package/src/view/textproxy.js +124 -124
  234. package/src/view/treewalker.d.ts +195 -195
  235. package/src/view/treewalker.js +327 -327
  236. package/src/view/typecheckable.d.ts +448 -448
  237. package/src/view/typecheckable.js +19 -19
  238. package/src/view/uielement.d.ts +96 -96
  239. package/src/view/uielement.js +183 -182
  240. package/src/view/upcastwriter.d.ts +417 -417
  241. package/src/view/upcastwriter.js +359 -359
  242. package/src/view/view.d.ts +487 -487
  243. 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
+ };