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