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