@ckeditor/ckeditor5-engine 48.2.0-alpha.7 → 48.3.0-alpha.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 (129) hide show
  1. package/dist/controller/datacontroller.d.ts +329 -328
  2. package/dist/controller/editingcontroller.d.ts +95 -94
  3. package/dist/conversion/comparemarkers.d.ts +45 -45
  4. package/dist/conversion/conversion.d.ts +474 -474
  5. package/dist/conversion/conversionhelpers.d.ts +21 -21
  6. package/dist/conversion/downcastdispatcher.d.ts +539 -538
  7. package/dist/conversion/downcasthelpers.d.ts +1129 -1129
  8. package/dist/conversion/mapper.d.ts +692 -697
  9. package/dist/conversion/modelconsumable.d.ts +196 -196
  10. package/dist/conversion/upcastdispatcher.d.ts +483 -482
  11. package/dist/conversion/upcasthelpers.d.ts +491 -491
  12. package/dist/conversion/viewconsumable.d.ts +330 -330
  13. package/dist/dataprocessor/basichtmlwriter.d.ts +15 -15
  14. package/dist/dataprocessor/dataprocessor.d.ts +57 -57
  15. package/dist/dataprocessor/htmldataprocessor.d.ts +72 -72
  16. package/dist/dataprocessor/htmlwriter.d.ts +11 -11
  17. package/dist/dataprocessor/xmldataprocessor.d.ts +86 -86
  18. package/dist/dev-utils/model.d.ts +128 -123
  19. package/dist/dev-utils/operationreplayer.d.ts +49 -49
  20. package/dist/dev-utils/utils.d.ts +33 -33
  21. package/dist/dev-utils/view.d.ts +314 -309
  22. package/dist/engineconfig.d.ts +39 -39
  23. package/dist/index.css.map +1 -1
  24. package/dist/index.d.ts +150 -150
  25. package/dist/index.js +34026 -40107
  26. package/dist/index.js.map +1 -1
  27. package/dist/legacyerrors.d.ts +0 -4
  28. package/dist/model/batch.d.ts +86 -86
  29. package/dist/model/differ.d.ts +504 -504
  30. package/dist/model/document.d.ts +265 -268
  31. package/dist/model/documentfragment.d.ts +214 -214
  32. package/dist/model/documentselection.d.ts +406 -410
  33. package/dist/model/element.d.ts +182 -182
  34. package/dist/model/history.d.ts +109 -109
  35. package/dist/model/item.d.ts +9 -9
  36. package/dist/model/liveposition.d.ts +70 -69
  37. package/dist/model/liverange.d.ts +93 -92
  38. package/dist/model/markercollection.d.ts +317 -324
  39. package/dist/model/model.d.ts +889 -909
  40. package/dist/model/node.d.ts +254 -254
  41. package/dist/model/nodelist.d.ts +110 -110
  42. package/dist/model/operation/attributeoperation.d.ts +98 -98
  43. package/dist/model/operation/detachoperation.d.ts +57 -57
  44. package/dist/model/operation/insertoperation.d.ts +85 -85
  45. package/dist/model/operation/markeroperation.d.ts +87 -87
  46. package/dist/model/operation/mergeoperation.d.ts +95 -95
  47. package/dist/model/operation/moveoperation.d.ts +97 -97
  48. package/dist/model/operation/nooperation.d.ts +33 -33
  49. package/dist/model/operation/operation.d.ts +94 -94
  50. package/dist/model/operation/operationfactory.d.ts +14 -14
  51. package/dist/model/operation/renameoperation.d.ts +78 -78
  52. package/dist/model/operation/rootattributeoperation.d.ts +93 -93
  53. package/dist/model/operation/rootoperation.d.ts +71 -71
  54. package/dist/model/operation/splitoperation.d.ts +104 -104
  55. package/dist/model/operation/transform.d.ts +91 -91
  56. package/dist/model/operation/utils.d.ts +58 -58
  57. package/dist/model/position.d.ts +535 -535
  58. package/dist/model/range.d.ts +458 -453
  59. package/dist/model/rootelement.d.ts +55 -55
  60. package/dist/model/schema.d.ts +1325 -1327
  61. package/dist/model/selection.d.ts +452 -471
  62. package/dist/model/text.d.ts +62 -62
  63. package/dist/model/textproxy.d.ts +140 -140
  64. package/dist/model/treewalker.d.ts +190 -190
  65. package/dist/model/typecheckable.d.ts +281 -281
  66. package/dist/model/utils/autoparagraphing.d.ts +29 -29
  67. package/dist/model/utils/deletecontent.d.ts +68 -68
  68. package/dist/model/utils/getselectedcontent.d.ts +27 -27
  69. package/dist/model/utils/insertcontent.d.ts +42 -42
  70. package/dist/model/utils/insertobject.d.ts +41 -41
  71. package/dist/model/utils/modifyselection.d.ts +44 -44
  72. package/dist/model/utils/selection-post-fixer.d.ts +71 -71
  73. package/dist/model/writer.d.ts +854 -854
  74. package/dist/view/attributeelement.d.ts +123 -123
  75. package/dist/view/containerelement.d.ts +49 -49
  76. package/dist/view/datatransfer.d.ts +70 -70
  77. package/dist/view/document.d.ts +175 -177
  78. package/dist/view/documentfragment.d.ts +158 -157
  79. package/dist/view/documentselection.d.ts +308 -307
  80. package/dist/view/domconverter.d.ts +612 -657
  81. package/dist/view/downcastwriter.d.ts +1006 -1006
  82. package/dist/view/editableelement.d.ts +64 -63
  83. package/dist/view/element.d.ts +754 -754
  84. package/dist/view/elementdefinition.d.ts +79 -79
  85. package/dist/view/emptyelement.d.ts +42 -42
  86. package/dist/view/filler.d.ts +75 -75
  87. package/dist/view/item.d.ts +9 -9
  88. package/dist/view/matcher.d.ts +412 -487
  89. package/dist/view/node.d.ts +164 -163
  90. package/dist/view/observer/arrowkeysobserver.d.ts +37 -37
  91. package/dist/view/observer/bubblingemittermixin.d.ts +163 -153
  92. package/dist/view/observer/bubblingeventinfo.d.ts +45 -42
  93. package/dist/view/observer/clickobserver.d.ts +36 -36
  94. package/dist/view/observer/compositionobserver.d.ts +67 -67
  95. package/dist/view/observer/domeventdata.d.ts +46 -46
  96. package/dist/view/observer/domeventobserver.d.ts +77 -74
  97. package/dist/view/observer/fakeselectionobserver.d.ts +42 -42
  98. package/dist/view/observer/focusobserver.d.ts +84 -84
  99. package/dist/view/observer/inputobserver.d.ts +76 -76
  100. package/dist/view/observer/keyobserver.d.ts +53 -53
  101. package/dist/view/observer/mouseobserver.d.ts +73 -73
  102. package/dist/view/observer/mutationobserver.d.ts +101 -101
  103. package/dist/view/observer/observer.d.ts +84 -83
  104. package/dist/view/observer/pointerobserver.d.ts +63 -63
  105. package/dist/view/observer/selectionobserver.d.ts +136 -136
  106. package/dist/view/observer/tabobserver.d.ts +38 -38
  107. package/dist/view/observer/touchobserver.d.ts +60 -60
  108. package/dist/view/placeholder.d.ts +80 -80
  109. package/dist/view/position.d.ts +187 -187
  110. package/dist/view/range.d.ts +282 -282
  111. package/dist/view/rawelement.d.ts +72 -72
  112. package/dist/view/renderer.d.ts +270 -272
  113. package/dist/view/rooteditableelement.d.ts +43 -43
  114. package/dist/view/selection.d.ts +356 -369
  115. package/dist/view/styles/background.d.ts +15 -15
  116. package/dist/view/styles/border.d.ts +27 -27
  117. package/dist/view/styles/margin.d.ts +12 -12
  118. package/dist/view/styles/padding.d.ts +12 -12
  119. package/dist/view/styles/utils.d.ts +72 -72
  120. package/dist/view/stylesmap.d.ts +715 -715
  121. package/dist/view/text.d.ts +75 -75
  122. package/dist/view/textproxy.d.ts +92 -92
  123. package/dist/view/tokenlist.d.ts +104 -104
  124. package/dist/view/treewalker.d.ts +201 -201
  125. package/dist/view/typecheckable.d.ts +445 -445
  126. package/dist/view/uielement.d.ts +93 -93
  127. package/dist/view/upcastwriter.d.ts +412 -412
  128. package/dist/view/view.d.ts +466 -469
  129. package/package.json +2 -2
@@ -1,933 +1,913 @@
1
1
  /**
2
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
- */
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
5
  /**
6
- * @module engine/model/model
7
- */
8
- import { Batch, type BatchType } from './batch.js';
9
- import { ModelDocument } from './document.js';
10
- import { MarkerCollection } from './markercollection.js';
11
- import { ModelPosition, type ModelPositionOffset, type ModelPositionStickiness } from './position.js';
12
- import { ModelRange } from './range.js';
13
- import { ModelSelection, type ModelPlaceOrOffset, type ModelSelectable } from './selection.js';
14
- import { ModelDocumentSelection } from './documentselection.js';
15
- import { ModelSchema } from './schema.js';
16
- import { ModelWriter } from './writer.js';
17
- import { ModelNode } from './node.js';
18
- import { type ModelDocumentFragment } from './documentfragment.js';
19
- import { type ModelItem } from './item.js';
20
- import { type ModelElement } from './element.js';
21
- import { type Operation } from './operation/operation.js';
22
- import { type DecoratedMethodEvent, type Config } from '@ckeditor/ckeditor5-utils';
23
- import type { EngineConfig } from '../engineconfig.js';
24
- declare const Model_base: {
25
- new (): import("@ckeditor/ckeditor5-utils").Observable;
26
- prototype: import("@ckeditor/ckeditor5-utils").Observable;
27
- };
6
+ * @module engine/model/model
7
+ */
8
+ import { Batch, type BatchType } from "./batch.js";
9
+ import { ModelDocument } from "./document.js";
10
+ import { MarkerCollection } from "./markercollection.js";
11
+ import { ModelPosition, type ModelPositionOffset, type ModelPositionStickiness } from "./position.js";
12
+ import { ModelRange } from "./range.js";
13
+ import { ModelSelection, type ModelPlaceOrOffset, type ModelSelectable } from "./selection.js";
14
+ import { ModelDocumentSelection } from "./documentselection.js";
15
+ import { ModelSchema } from "./schema.js";
16
+ import { ModelWriter } from "./writer.js";
17
+ import { ModelNode } from "./node.js";
18
+ import { type ModelDocumentFragment } from "./documentfragment.js";
19
+ import { type ModelItem } from "./item.js";
20
+ import { type ModelElement } from "./element.js";
21
+ import { type Operation } from "./operation/operation.js";
22
+ import { type DecoratedMethodEvent, type Config, type ObservableMixinConstructor } from "@ckeditor/ckeditor5-utils";
23
+ import type { EngineConfig } from "../engineconfig.js";
24
+ declare const ModelBase: ObservableMixinConstructor;
28
25
  /**
29
- * Editor's data model. Read about the model in the
30
- * {@glink framework/architecture/editing-engine engine architecture} guide.
31
- */
32
- export declare class Model extends /* #__PURE__ */ Model_base {
33
- /**
34
- * Model's marker collection.
35
- */
36
- readonly markers: MarkerCollection;
37
- /**
38
- * Model's document.
39
- */
40
- readonly document: ModelDocument;
41
- /**
42
- * Model's schema.
43
- */
44
- readonly schema: ModelSchema;
45
- /**
46
- * Stores all configurations specific to editor instance.
47
- *
48
- * @internal
49
- */
50
- readonly _config?: Config<EngineConfig>;
51
- /**
52
- * All callbacks added by {@link module:engine/model/model~Model#change} or
53
- * {@link module:engine/model/model~Model#enqueueChange} methods waiting to be executed.
54
- */
55
- private readonly _pendingChanges;
56
- /**
57
- * The last created and currently used writer instance.
58
- */
59
- private _currentWriter;
60
- constructor(config?: Config<EngineConfig>);
61
- /**
62
- * The `change()` method is the primary way of changing the model. You should use it to modify all document nodes
63
- * (including detached nodes – i.e. nodes not added to the {@link module:engine/model/model~Model#document model document}),
64
- * the {@link module:engine/model/document~ModelDocument#selection document's selection}, and
65
- * {@link module:engine/model/model~Model#markers model markers}.
66
- *
67
- * ```ts
68
- * model.change( writer => {
69
- * writer.insertText( 'foo', paragraph, 'end' );
70
- * } );
71
- * ```
72
- *
73
- * All changes inside the change block use the same {@link module:engine/model/batch~Batch} so they are combined
74
- * into a single undo step.
75
- *
76
- * ```ts
77
- * model.change( writer => {
78
- * writer.insertText( 'foo', paragraph, 'end' ); // foo.
79
- *
80
- * model.change( writer => {
81
- * writer.insertText( 'bar', paragraph, 'end' ); // foobar.
82
- * } );
83
- *
84
- * writer.insertText( 'bom', paragraph, 'end' ); // foobarbom.
85
- * } );
86
- * ```
87
- *
88
- * The callback of the `change()` block is executed synchronously.
89
- *
90
- * You can also return a value from the change block.
91
- *
92
- * ```ts
93
- * const img = model.change( writer => {
94
- * return writer.createElement( 'img' );
95
- * } );
96
- * ```
97
- *
98
- * @see #enqueueChange
99
- * @typeParam TReturn The return type of the provided callback.
100
- * @param callback Callback function which may modify the model.
101
- */
102
- change<TReturn>(callback: (writer: ModelWriter) => TReturn): TReturn;
103
- /**
104
- * The `enqueueChange()` method performs similar task as the {@link #change `change()` method}, with two major differences.
105
- *
106
- * First, the callback of `enqueueChange()` is executed when all other enqueued changes are done. It might be executed
107
- * immediately if it is not nested in any other change block, but if it is nested in another (enqueue)change block,
108
- * it will be delayed and executed after the outermost block.
109
- *
110
- * ```ts
111
- * model.change( writer => {
112
- * console.log( 1 );
113
- *
114
- * model.enqueueChange( writer => {
115
- * console.log( 2 );
116
- * } );
117
- *
118
- * console.log( 3 );
119
- * } ); // Will log: 1, 3, 2.
120
- * ```
121
- *
122
- * In addition to that, the changes enqueued with `enqueueChange()` will be converted separately from the changes
123
- * done in the outer `change()` block.
124
- *
125
- * By default, a new batch with the default {@link module:engine/model/batch~Batch#constructor batch type} is created.
126
- * To define the {@link module:engine/model/batch~Batch} into which you want to add your changes,
127
- * use {@link #enqueueChange:CUSTOM_BATCH `enqueueChange( batchOrType, callback )`}.
128
- *
129
- * @label DEFAULT_BATCH
130
- * @param callback Callback function which may modify the model.
131
- */
132
- enqueueChange(callback: (writer: ModelWriter) => unknown): void;
133
- /**
134
- * The `enqueueChange()` method performs similar task as the {@link #change `change()` method}, with two major differences.
135
- *
136
- * First, the callback of `enqueueChange()` is executed when all other enqueued changes are done. It might be executed
137
- * immediately if it is not nested in any other change block, but if it is nested in another (enqueue)change block,
138
- * it will be delayed and executed after the outermost block.
139
- *
140
- * ```ts
141
- * model.change( new Batch(), writer => {
142
- * console.log( 1 );
143
- *
144
- * model.enqueueChange( new Batch(), writer => {
145
- * console.log( 2 );
146
- * } );
147
- *
148
- * console.log( 3 );
149
- * } ); // Will log: 1, 3, 2.
150
- * ```
151
- *
152
- * In addition to that, the changes enqueued with `enqueueChange()` will be converted separately from the changes
153
- * done in the outer `change()` block.
154
- *
155
- * Second, it lets you define the {@link module:engine/model/batch~Batch} into which you want to add your changes.
156
- * If you want to use default {@link module:engine/model/batch~Batch#constructor batch type}, use
157
- * {@link #enqueueChange:DEFAULT_BATCH `enqueueChange( callback )`}.
158
- *
159
- * ```ts
160
- * model.enqueueChange( { isUndoable: false }, writer => {
161
- * writer.insertText( 'foo', paragraph, 'end' );
162
- * } );
163
- * ```
164
- *
165
- * When using the `enqueueChange()` block you can also add some changes to the batch you used before.
166
- *
167
- * ```ts
168
- * model.enqueueChange( batch, writer => {
169
- * writer.insertText( 'foo', paragraph, 'end' );
170
- * } );
171
- * ```
172
- *
173
- * In order to make a nested `enqueueChange()` create a single undo step together with the changes done in the outer `change()`
174
- * block, you can obtain the batch instance from the {@link module:engine/model/writer~ModelWriter#batch writer} of the outer block.
175
- *
176
- * @label CUSTOM_BATCH
177
- * @param batchOrType A batch or a {@link module:engine/model/batch~Batch#constructor batch type} that should be used in the callback.
178
- * If not defined, a new batch with the default type will be created.
179
- * @param callback Callback function which may modify the model.
180
- */
181
- enqueueChange(batchOrType: Batch | BatchType | undefined, callback: (writer: ModelWriter) => unknown): void;
182
- /**
183
- * {@link module:utils/observablemixin~Observable#decorate Decorated} function for applying
184
- * {@link module:engine/model/operation/operation~Operation operations} to the model.
185
- *
186
- * This is a low-level way of changing the model. It is exposed for very specific use cases (like the undo feature).
187
- * Normally, to modify the model, you will want to use {@link module:engine/model/writer~ModelWriter `Writer`}.
188
- * See also {@glink framework/architecture/editing-engine#changing-the-model Changing the model} section
189
- * of the {@glink framework/architecture/editing-engine Editing architecture} guide.
190
- *
191
- * @param operation The operation to apply.
192
- */
193
- applyOperation(operation: Operation): void;
194
- /**
195
- * Inserts content at the position in the editor specified by the selection, as one would expect the paste
196
- * functionality to work.
197
- *
198
- * **Note**: If you want to insert an {@glink framework/deep-dive/schema#object-elements object element}
199
- * (e.g. a {@link module:widget/utils~toWidget widget}), see {@link #insertObject} instead.
200
- *
201
- * This is a high-level method. It takes the {@link #schema schema} into consideration when inserting
202
- * the content, clears the given selection's content before inserting nodes and moves the selection
203
- * to its target position at the end of the process.
204
- * It can split elements, merge them, wrap bare text nodes with paragraphs, etc. &ndash; just like the
205
- * pasting feature should do.
206
- *
207
- * For lower-level methods see {@link module:engine/model/writer~ModelWriter `Writer`}.
208
- *
209
- * This method, unlike {@link module:engine/model/writer~ModelWriter `Writer`}'s methods, does not have to be used
210
- * inside a {@link #change `change()` block}.
211
- *
212
- * # Conversion and schema
213
- *
214
- * Inserting elements and text nodes into the model is not enough to make CKEditor 5 render that content
215
- * to the user. CKEditor 5 implements a model-view-controller architecture and what `model.insertContent()` does
216
- * is only adding nodes to the model. Additionally, you need to define
217
- * {@glink framework/architecture/editing-engine#conversion converters} between the model and view
218
- * and define those nodes in the {@glink framework/architecture/editing-engine#schema schema}.
219
- *
220
- * So, while this method may seem similar to CKEditor 4 `editor.insertHtml()` (in fact, both methods
221
- * are used for paste-like content insertion), the CKEditor 5 method cannot be use to insert arbitrary HTML
222
- * unless converters are defined for all elements and attributes in that HTML.
223
- *
224
- * # Examples
225
- *
226
- * Using `insertContent()` with a manually created model structure:
227
- *
228
- * ```ts
229
- * // Let's create a document fragment containing such content as:
230
- * //
231
- * // <paragraph>foo</paragraph>
232
- * // <blockQuote>
233
- * // <paragraph>bar</paragraph>
234
- * // </blockQuote>
235
- * const docFrag = editor.model.change( writer => {
236
- * const p1 = writer.createElement( 'paragraph' );
237
- * const p2 = writer.createElement( 'paragraph' );
238
- * const blockQuote = writer.createElement( 'blockQuote' );
239
- * const docFrag = writer.createDocumentFragment();
240
- *
241
- * writer.append( p1, docFrag );
242
- * writer.append( blockQuote, docFrag );
243
- * writer.append( p2, blockQuote );
244
- * writer.insertText( 'foo', p1 );
245
- * writer.insertText( 'bar', p2 );
246
- *
247
- * return docFrag;
248
- * } );
249
- *
250
- * // insertContent() does not have to be used in a change() block. It can, though,
251
- * // so this code could be moved to the callback defined above.
252
- * editor.model.insertContent( docFrag );
253
- * ```
254
- *
255
- * Using `insertContent()` with an HTML string converted to a model document fragment (similar to the pasting mechanism):
256
- *
257
- * ```ts
258
- * // You can create your own HtmlDataProcessor instance or use editor.data.processor
259
- * // if you have not overridden the default one (which is the HtmlDataProcessor instance).
260
- * const htmlDP = new HtmlDataProcessor( viewDocument );
261
- *
262
- * // Convert an HTML string to a view document fragment:
263
- * const viewFragment = htmlDP.toView( htmlString );
264
- *
265
- * // Convert the view document fragment to a model document fragment
266
- * // in the context of $root. This conversion takes the schema into
267
- * // account so if, for example, the view document fragment contained a bare text node,
268
- * // this text node cannot be a child of $root, so it will be automatically
269
- * // wrapped with a <paragraph>. You can define the context yourself (in the second parameter),
270
- * // and e.g. convert the content like it would happen in a <paragraph>.
271
- * // Note: The clipboard feature uses a custom context called $clipboardHolder
272
- * // which has a loosened schema.
273
- * const modelFragment = editor.data.toModel( viewFragment );
274
- *
275
- * editor.model.insertContent( modelFragment );
276
- * ```
277
- *
278
- * By default this method will use the document selection but it can also be used with a position, range or selection instance.
279
- *
280
- * ```ts
281
- * // Insert text at the current document selection position.
282
- * editor.model.change( writer => {
283
- * editor.model.insertContent( writer.createText( 'x' ) );
284
- * } );
285
- *
286
- * // Insert text at a given position - the document selection will not be modified.
287
- * editor.model.change( writer => {
288
- * editor.model.insertContent( writer.createText( 'x' ), doc.getRoot(), 2 );
289
- *
290
- * // Which is a shorthand for:
291
- * editor.model.insertContent( writer.createText( 'x' ), writer.createPositionAt( doc.getRoot(), 2 ) );
292
- * } );
293
- * ```
294
- *
295
- * If you want the document selection to be moved to the inserted content, use the
296
- * {@link module:engine/model/writer~ModelWriter#setSelection `setSelection()`} method of the writer after inserting
297
- * the content:
298
- *
299
- * ```ts
300
- * editor.model.change( writer => {
301
- * const paragraph = writer.createElement( 'paragraph' );
302
- *
303
- * // Insert an empty paragraph at the beginning of the root.
304
- * editor.model.insertContent( paragraph, writer.createPositionAt( editor.model.document.getRoot(), 0 ) );
305
- *
306
- * // Move the document selection to the inserted paragraph.
307
- * writer.setSelection( paragraph, 'in' );
308
- * } );
309
- * ```
310
- *
311
- * If an instance of the {@link module:engine/model/selection~ModelSelection model selection} is passed as `selectable`,
312
- * the new content will be inserted at the passed selection (instead of document selection):
313
- *
314
- * ```ts
315
- * editor.model.change( writer => {
316
- * // Create a selection in a paragraph that will be used as a place of insertion.
317
- * const selection = writer.createSelection( paragraph, 'in' );
318
- *
319
- * // Insert the new text at the created selection.
320
- * editor.model.insertContent( writer.createText( 'x' ), selection );
321
- *
322
- * // insertContent() modifies the passed selection instance so it can be used to set the document selection.
323
- * // Note: This is not necessary when you passed the document selection to insertContent().
324
- * writer.setSelection( selection );
325
- * } );
326
- * ```
327
- *
328
- * @fires insertContent
329
- * @param content The content to insert.
330
- * @param selectable The selection into which the content should be inserted.
331
- * If not provided the current model document selection will be used.
332
- * @param placeOrOffset To be used when a model item was passed as `selectable`.
333
- * This param defines a position in relation to that item.
334
- * at the insertion position.
335
- */
336
- insertContent(content: ModelItem | ModelDocumentFragment, selectable?: ModelSelectable, placeOrOffset?: ModelPlaceOrOffset, ...rest: Array<unknown>): ModelRange;
337
- /**
338
- * Inserts an {@glink framework/deep-dive/schema#object-elements object element} at a specific position in the editor content.
339
- *
340
- * This is a high-level API:
341
- * * It takes the {@link #schema schema} into consideration,
342
- * * It clears the content of passed `selectable` before inserting,
343
- * * It can move the selection at the end of the process,
344
- * * It will copy the selected block's attributes to preserve them upon insertion,
345
- * * It can split elements or wrap inline objects with paragraphs if they are not allowed in target position,
346
- * * etc.
347
- *
348
- * # Notes
349
- *
350
- * * If you want to insert a non-object content, see {@link #insertContent} instead.
351
- * * For lower-level API, see {@link module:engine/model/writer~ModelWriter `Writer`}.
352
- * * Unlike {@link module:engine/model/writer~ModelWriter `Writer`}, this method does not have to be used inside
353
- * a {@link #change `change()` block}.
354
- * * Inserting object into the model is not enough to make CKEditor 5 render that content to the user.
355
- * CKEditor 5 implements a model-view-controller architecture and what `model.insertObject()` does
356
- * is only adding nodes to the model. Additionally, you need to define
357
- * {@glink framework/architecture/editing-engine#conversion converters} between the model and view
358
- * and define those nodes in the {@glink framework/architecture/editing-engine#schema schema}.
359
- *
360
- * # Examples
361
- *
362
- * Use the following code to insert an object at the current selection and keep the selection on the inserted element:
363
- *
364
- * ```ts
365
- * const rawHtmlEmbedElement = writer.createElement( 'rawHtml' );
366
- *
367
- * model.insertObject( rawHtmlEmbedElement, null, null, {
368
- * setSelection: 'on'
369
- * } );
370
- * ```
371
- *
372
- * Use the following code to insert an object at the current selection and nudge the selection after the inserted object:
373
- *
374
- * ```ts
375
- * const pageBreakElement = writer.createElement( 'pageBreak' );
376
- *
377
- * model.insertObject( pageBreakElement, null, null, {
378
- * setSelection: 'after'
379
- * } );
380
- * ```
381
- *
382
- * Use the following code to insert an object at the current selection and avoid splitting the content (non-destructive insertion):
383
- *
384
- * ```ts
385
- * const tableElement = writer.createElement( 'table' );
386
- *
387
- * model.insertObject( tableElement, null, null, {
388
- * findOptimalPosition: 'auto'
389
- * } );
390
- * ```
391
- *
392
- * Use the following code to insert an object at the specific range (also: replace the content of the range):
393
- *
394
- * ```ts
395
- * const tableElement = writer.createElement( 'table' );
396
- * const range = model.createRangeOn( model.document.getRoot().getChild( 1 ) );
397
- *
398
- * model.insertObject( tableElement, range );
399
- * ```
400
- *
401
- * @param element An object to be inserted into the model document.
402
- * @param selectable A selectable where the content should be inserted. If not specified, the current
403
- * {@link module:engine/model/document~ModelDocument#selection document selection} will be used instead.
404
- * @param placeOrOffset Specifies the exact place or offset for the insertion to take place, relative to `selectable`.
405
- * @param options Additional options.
406
- * @param options.findOptimalPosition An option that, when set, adjusts the insertion position (relative to
407
- * `selectable` and `placeOrOffset`) so that the content of `selectable` is not split upon insertion (a.k.a. non-destructive insertion).
408
- * * When `'auto'`, the algorithm will decide whether to insert the object before or after `selectable` to avoid content splitting.
409
- * * When `'before'`, the closest position before `selectable` will be used that will not result in content splitting.
410
- * * When `'after'`, the closest position after `selectable` will be used that will not result in content splitting.
411
- *
412
- * Note that this option only works for block objects. Inline objects are inserted into text and do not split blocks.
413
- * @param options.setSelection An option that, when set, moves the
414
- * {@link module:engine/model/document~ModelDocument#selection document selection} after inserting the object.
415
- * * When `'on'`, the document selection will be set on the inserted object.
416
- * * When `'after'`, the document selection will move to the closest text node after the inserted object. If there is no
417
- * such text node, a paragraph will be created and the document selection will be moved inside it.
418
- * at the insertion position.
419
- */
420
- insertObject(element: ModelElement, selectable?: ModelSelectable, placeOrOffset?: ModelPlaceOrOffset | null, options?: {
421
- findOptimalPosition?: 'auto' | 'before' | 'after';
422
- setSelection?: 'on' | 'after';
423
- }, ...rest: Array<unknown>): ModelRange;
424
- /**
425
- * Deletes content of the selection and merge siblings. The resulting selection is always collapsed.
426
- *
427
- * **Note:** For the sake of predictability, the resulting selection should always be collapsed.
428
- * In cases where a feature wants to modify deleting behavior so selection isn't collapsed
429
- * (e.g. a table feature may want to keep row selection after pressing <kbd>Backspace</kbd>),
430
- * then that behavior should be implemented in the view's listener. At the same time, the table feature
431
- * will need to modify this method's behavior too, e.g. to "delete contents and then collapse
432
- * the selection inside the last selected cell" or "delete the row and collapse selection somewhere near".
433
- * That needs to be done in order to ensure that other features which use `deleteContent()` will work well with tables.
434
- *
435
- * @fires deleteContent
436
- * @param selection Selection of which the content should be deleted.
437
- * @param options.leaveUnmerged Whether to merge elements after removing the content of the selection.
438
- *
439
- * For example `<heading1>x[x</heading1><paragraph>y]y</paragraph>` will become:
440
- *
441
- * * `<heading1>x^y</heading1>` with the option disabled (`leaveUnmerged == false`)
442
- * * `<heading1>x^</heading1><paragraph>y</paragraph>` with enabled (`leaveUnmerged == true`).
443
- *
444
- * Note: {@link module:engine/model/schema~ModelSchema#isObject object} and {@link module:engine/model/schema~ModelSchema#isLimit limit}
445
- * elements will not be merged.
446
- *
447
- * @param options.doNotResetEntireContent Whether to skip replacing the entire content with a
448
- * paragraph when the entire content was selected.
449
- *
450
- * For example `<heading1>[x</heading1><paragraph>y]</paragraph>` will become:
451
- *
452
- * * `<paragraph>^</paragraph>` with the option disabled (`doNotResetEntireContent == false`)
453
- * * `<heading1>^</heading1>` with enabled (`doNotResetEntireContent == true`)
454
- *
455
- * @param options.doNotAutoparagraph Whether to create a paragraph if after content deletion selection is moved
456
- * to a place where text cannot be inserted.
457
- *
458
- * For example `<paragraph>x</paragraph>[<imageBlock src="foo.jpg"></imageBlock>]` will become:
459
- *
460
- * * `<paragraph>x</paragraph><paragraph>[]</paragraph>` with the option disabled (`doNotAutoparagraph == false`)
461
- * * `<paragraph>x[]</paragraph>` with the option enabled (`doNotAutoparagraph == true`).
462
- *
463
- * **Note:** if there is no valid position for the selection, the paragraph will always be created:
464
- *
465
- * `[<imageBlock src="foo.jpg"></imageBlock>]` -> `<paragraph>[]</paragraph>`.
466
- *
467
- * @param options.direction The direction in which the content is being consumed.
468
- * Deleting backward corresponds to using the <kbd>Backspace</kbd> key, while deleting content forward corresponds to
469
- * the <kbd>Shift</kbd>+<kbd>Backspace</kbd> keystroke.
470
- */
471
- deleteContent(selection: ModelSelection | ModelDocumentSelection, options?: {
472
- leaveUnmerged?: boolean;
473
- doNotResetEntireContent?: boolean;
474
- doNotAutoparagraph?: boolean;
475
- direction?: 'forward' | 'backward';
476
- [i: string]: unknown;
477
- }): void;
478
- /**
479
- * Modifies the selection. Currently, the supported modifications are:
480
- *
481
- * * Extending. The selection focus is moved in the specified `options.direction` with a step specified in `options.unit`.
482
- * Possible values for `unit` are:
483
- * * `'character'` (default) - moves selection by one user-perceived character. In most cases this means moving by one
484
- * character in `String` sense. However, unicode also defines "combing marks". These are special symbols, that combines
485
- * with a symbol before it ("base character") to create one user-perceived character. For example, `q̣̇` is a normal
486
- * letter `q` with two "combining marks": upper dot (`Ux0307`) and lower dot (`Ux0323`). For most actions, i.e. extending
487
- * selection by one position, it is correct to include both "base character" and all of it's "combining marks". That is
488
- * why `'character'` value is most natural and common method of modifying selection.
489
- * * `'codePoint'` - moves selection by one unicode code point. In contrary to, `'character'` unit, this will insert
490
- * selection between "base character" and "combining mark", because "combining marks" have their own unicode code points.
491
- * However, for technical reasons, unicode code points with values above `UxFFFF` are represented in native `String` by
492
- * two characters, called "surrogate pairs". Halves of "surrogate pairs" have a meaning only when placed next to each other.
493
- * For example `𨭎` is represented in `String` by `\uD862\uDF4E`. Both `\uD862` and `\uDF4E` do not have any meaning
494
- * outside the pair (are rendered as ? when alone). Position between them would be incorrect. In this case, selection
495
- * extension will include whole "surrogate pair".
496
- * * `'word'` - moves selection by a whole word.
497
- *
498
- * **Note:** if you extend a forward selection in a backward direction you will in fact shrink it.
499
- *
500
- * @fires modifySelection
501
- * @param selection The selection to modify.
502
- * @param options.direction The direction in which the selection should be modified.
503
- * @param options.unit The unit by which selection should be modified.
504
- * @param options.treatEmojiAsSingleUnit Whether multi-characer emoji sequences should be handled as single unit.
505
- */
506
- modifySelection(selection: ModelSelection | ModelDocumentSelection, options?: {
507
- direction?: 'forward' | 'backward';
508
- unit?: 'character' | 'codePoint' | 'word';
509
- treatEmojiAsSingleUnit?: boolean;
510
- }): void;
511
- /**
512
- * Gets a clone of the selected content.
513
- *
514
- * For example, for the following selection:
515
- *
516
- * ```html
517
- * <paragraph>x</paragraph>
518
- * <blockQuote>
519
- * <paragraph>y</paragraph>
520
- * <heading1>fir[st</heading1>
521
- * </blockQuote>
522
- * <paragraph>se]cond</paragraph>
523
- * <paragraph>z</paragraph>
524
- * ```
525
- *
526
- * It will return a document fragment with such a content:
527
- *
528
- * ```html
529
- * <blockQuote>
530
- * <heading1>st</heading1>
531
- * </blockQuote>
532
- * <paragraph>se</paragraph>
533
- * ```
534
- *
535
- * @fires getSelectedContent
536
- * @param selection The selection of which content will be returned.
537
- */
538
- getSelectedContent(selection: ModelSelection | ModelDocumentSelection): ModelDocumentFragment;
539
- /**
540
- * Checks whether given `subject` has any meaningful content.
541
- *
542
- * Meaningful content is:
543
- *
544
- * * any text node (`options.ignoreWhitespaces` allows controlling whether this text node must also contain
545
- * any non-whitespace characters),
546
- * * or any {@link module:engine/model/schema~ModelSchema#isContent content element},
547
- * * or any {@link module:engine/model/markercollection~Marker marker} which
548
- * {@link module:engine/model/markercollection~Marker#_affectsData affects data}.
549
- *
550
- * This means that a range containing an empty `<paragraph></paragraph>` is not considered to have a meaningful content.
551
- * However, a range containing an `<imageBlock></imageBlock>` (which would normally be marked in the schema as an object element)
552
- * is considered non-empty.
553
- *
554
- * @param subject Subject to check if includes meaningful content. Could be a model range, an element, a document fragment, or a
555
- * selection.
556
- * @param options.ignoreWhitespaces Whether text node with whitespaces only should be considered empty.
557
- * @param options.ignoreMarkers Whether markers should be ignored.
558
- */
559
- hasContent(subject: ModelRange | ModelElement | ModelDocumentFragment | ModelSelection | ModelDocumentSelection, options?: {
560
- ignoreWhitespaces?: boolean;
561
- ignoreMarkers?: boolean;
562
- }): boolean;
563
- /**
564
- * Checks whether given range has any meaningful content.
565
- *
566
- * Helper method for {@link #hasContent}.
567
- */
568
- private _rangeHasContent;
569
- /**
570
- * Check whether given selectable is at a place in the model where it can be edited (returns `true`) or not (returns `false`).
571
- *
572
- * Should be used instead of {@link module:core/editor/editor~Editor#isReadOnly} to check whether a user action can happen at
573
- * given selectable. It may be decorated and used differently in different environment (e.g. multi-root editor can disable
574
- * a particular root).
575
- *
576
- * This method is decorated. Although this method accepts any parameter of `Selectable` type, the
577
- * {@link ~Model#event:canEditAt `canEditAt` event} is fired with `selectable` normalized to an instance of
578
- * {@link module:engine/model/selection~ModelSelection} or {@link module:engine/model/documentselection~ModelDocumentSelection}
579
- *
580
- * @fires canEditAt
581
- */
582
- canEditAt(selectable: ModelSelectable): boolean;
583
- /**
584
- * Creates a position from the given root and path in that root.
585
- *
586
- * Note: This method is also available as
587
- * {@link module:engine/model/writer~ModelWriter#createPositionFromPath `Writer#createPositionFromPath()`}.
588
- *
589
- * @param root Root of the position.
590
- * @param path Position path. See {@link module:engine/model/position~ModelPosition#path}.
591
- * @param stickiness Position stickiness. See {@link module:engine/model/position~ModelPositionStickiness}.
592
- */
593
- createPositionFromPath(root: ModelElement | ModelDocumentFragment, path: ReadonlyArray<number>, stickiness?: ModelPositionStickiness): ModelPosition;
594
- /**
595
- * Creates position at the given location. The location can be specified as:
596
- *
597
- * * a {@link module:engine/model/position~ModelPosition position},
598
- * * a parent element and offset in that element,
599
- * * a parent element and `'end'` (the position will be set at the end of that element),
600
- * * a {@link module:engine/model/item~ModelItem model item} and `'before'` or `'after'`
601
- * (the position will be set before or after the given model item).
602
- *
603
- * This method is a shortcut to other factory methods such as:
604
- *
605
- * * {@link module:engine/model/model~Model#createPositionBefore `createPositionBefore()`},
606
- * * {@link module:engine/model/model~Model#createPositionAfter `createPositionAfter()`}.
607
- *
608
- * Note: This method is also available as
609
- * {@link module:engine/model/writer~ModelWriter#createPositionAt `Writer#createPositionAt()`},
610
- *
611
- * @param itemOrPosition
612
- * @param offset Offset or one of the flags. Used only when first parameter is a {@link module:engine/model/item~ModelItem model item}.
613
- */
614
- createPositionAt(itemOrPosition: ModelItem | ModelPosition | ModelDocumentFragment, offset?: ModelPositionOffset): ModelPosition;
615
- /**
616
- * Creates a new position after the given {@link module:engine/model/item~ModelItem model item}.
617
- *
618
- * Note: This method is also available as
619
- * {@link module:engine/model/writer~ModelWriter#createPositionAfter `Writer#createPositionAfter()`}.
620
- *
621
- * @param item Item after which the position should be placed.
622
- */
623
- createPositionAfter(item: ModelItem): ModelPosition;
624
- /**
625
- * Creates a new position before the given {@link module:engine/model/item~ModelItem model item}.
626
- *
627
- * Note: This method is also available as
628
- * {@link module:engine/model/writer~ModelWriter#createPositionBefore `Writer#createPositionBefore()`}.
629
- *
630
- * @param item Item before which the position should be placed.
631
- */
632
- createPositionBefore(item: ModelItem): ModelPosition;
633
- /**
634
- * Creates a range spanning from the `start` position to the `end` position.
635
- *
636
- * Note: This method is also available as
637
- * {@link module:engine/model/writer~ModelWriter#createRange `Writer#createRange()`}:
638
- *
639
- * ```ts
640
- * model.change( writer => {
641
- * const range = writer.createRange( start, end );
642
- * } );
643
- * ```
644
- *
645
- * @param start Start position.
646
- * @param end End position. If not set, the range will be collapsed to the `start` position.
647
- */
648
- createRange(start: ModelPosition, end?: ModelPosition): ModelRange;
649
- /**
650
- * Creates a range inside the given element which starts before the first child of
651
- * that element and ends after the last child of that element.
652
- *
653
- * Note: This method is also available as
654
- * {@link module:engine/model/writer~ModelWriter#createRangeIn `Writer#createRangeIn()`}:
655
- *
656
- * ```ts
657
- * model.change( writer => {
658
- * const range = writer.createRangeIn( paragraph );
659
- * } );
660
- * ```
661
- *
662
- * @param element Element which is a parent for the range.
663
- */
664
- createRangeIn(element: ModelElement | ModelDocumentFragment): ModelRange;
665
- /**
666
- * Creates a range that starts before the given {@link module:engine/model/item~ModelItem model item} and ends after it.
667
- *
668
- * Note: This method is also available on `writer` instance as
669
- * {@link module:engine/model/writer~ModelWriter#createRangeOn `Writer.createRangeOn()`}:
670
- *
671
- * ```ts
672
- * model.change( writer => {
673
- * const range = writer.createRangeOn( paragraph );
674
- * } );
675
- * ```
676
- *
677
- * @param item
678
- */
679
- createRangeOn(item: ModelItem): ModelRange;
680
- /**
681
- * Creates a new selection instance based on the given {@link module:engine/model/selection~ModelSelectable selectable}
682
- * or creates an empty selection if no arguments were passed.
683
- *
684
- * Note: This method is also available as
685
- * {@link module:engine/model/writer~ModelWriter#createSelection `Writer#createSelection()`}.
686
- *
687
- * ```ts
688
- * // Creates selection at the given offset in the given element.
689
- * const paragraph = writer.createElement( 'paragraph' );
690
- * const selection = writer.createSelection( paragraph, offset );
691
- *
692
- * // Creates a range inside an {@link module:engine/model/element~ModelElement element} which starts before the
693
- * // first child of that element and ends after the last child of that element.
694
- * const selection = writer.createSelection( paragraph, 'in' );
695
- *
696
- * // Creates a range on an {@link module:engine/model/item~ModelItem item} which starts before the item and ends
697
- * // just after the item.
698
- * const selection = writer.createSelection( paragraph, 'on' );
699
- *
700
- * // Additional options (`'backward'`) can be specified as the last argument.
701
- *
702
- * // Creates backward selection.
703
- * const selection = writer.createSelection( element, 'in', { backward: true } );
704
- * ```
705
- *
706
- * See also: {@link #createSelection:SELECTABLE `createSelection( selectable, options )`}.
707
- *
708
- * @label NODE_OFFSET
709
- */
710
- createSelection(selectable: ModelNode, placeOrOffset: ModelPlaceOrOffset, options?: {
711
- backward?: boolean;
712
- }): ModelSelection;
713
- /**
714
- * Creates a new selection instance based on the given {@link module:engine/model/selection~ModelSelectable selectable}
715
- * or creates an empty selection if no arguments were passed.
716
- *
717
- * Note: This method is also available as
718
- * {@link module:engine/model/writer~ModelWriter#createSelection `Writer#createSelection()`}.
719
- *
720
- * ```ts
721
- * // Creates empty selection without ranges.
722
- * const selection = writer.createSelection();
723
- *
724
- * // Creates selection at the given range.
725
- * const range = writer.createRange( start, end );
726
- * const selection = writer.createSelection( range );
727
- *
728
- * // Creates selection at the given ranges
729
- * const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
730
- * const selection = writer.createSelection( ranges );
731
- *
732
- * // Creates selection from the other selection.
733
- * // Note: It doesn't copies selection attributes.
734
- * const otherSelection = writer.createSelection();
735
- * const selection = writer.createSelection( otherSelection );
736
- *
737
- * // Creates selection from the given document selection.
738
- * // Note: It doesn't copies selection attributes.
739
- * const documentSelection = model.document.selection;
740
- * const selection = writer.createSelection( documentSelection );
741
- *
742
- * // Creates selection at the given position.
743
- * const position = writer.createPositionFromPath( root, path );
744
- * const selection = writer.createSelection( position );
745
- *
746
- * // Additional options (`'backward'`) can be specified as the last argument.
747
- *
748
- * // Creates backward selection.
749
- * const selection = writer.createSelection( range, { backward: true } );
750
- * ```
751
- *
752
- * See also: {@link #createSelection:NODE_OFFSET `createSelection( node, placeOrOffset, options )`}.
753
- *
754
- * @label SELECTABLE
755
- */
756
- createSelection(selectable?: Exclude<ModelSelectable, ModelNode>, options?: {
757
- backward?: boolean;
758
- }): ModelSelection;
759
- /**
760
- * Creates a {@link module:engine/model/batch~Batch} instance.
761
- *
762
- * **Note:** In most cases creating a batch instance is not necessary as they are created when using:
763
- *
764
- * * {@link #change `change()`},
765
- * * {@link #enqueueChange `enqueueChange()`}.
766
- *
767
- * @param type {@link module:engine/model/batch~Batch#constructor The type} of the batch.
768
- */
769
- createBatch(type?: BatchType): Batch;
770
- /**
771
- * Creates an operation instance from a JSON object (parsed JSON string).
772
- *
773
- * This is an alias for {@link module:engine/model/operation/operationfactory~OperationFactory.fromJSON `OperationFactory.fromJSON()`}.
774
- *
775
- * @param json Deserialized JSON object.
776
- */
777
- createOperationFromJSON(json: unknown): Operation;
778
- /**
779
- * Removes all events listeners set by model instance and destroys {@link module:engine/model/document~ModelDocument}.
780
- */
781
- destroy(): void;
782
- /**
783
- * Common part of {@link module:engine/model/model~Model#change} and {@link module:engine/model/model~Model#enqueueChange}
784
- * which calls callbacks and returns array of values returned by these callbacks.
785
- */
786
- private _runPendingChanges;
26
+ * Editor's data model. Read about the model in the
27
+ * {@glink framework/architecture/editing-engine engine architecture} guide.
28
+ */
29
+ export declare class Model extends ModelBase {
30
+ /**
31
+ * Model's marker collection.
32
+ */
33
+ readonly markers: MarkerCollection;
34
+ /**
35
+ * Model's document.
36
+ */
37
+ readonly document: ModelDocument;
38
+ /**
39
+ * Model's schema.
40
+ */
41
+ readonly schema: ModelSchema;
42
+ /**
43
+ * Stores all configurations specific to editor instance.
44
+ *
45
+ * @internal
46
+ */
47
+ readonly _config?: Config<EngineConfig>;
48
+ /**
49
+ * All callbacks added by {@link module:engine/model/model~Model#change} or
50
+ * {@link module:engine/model/model~Model#enqueueChange} methods waiting to be executed.
51
+ */
52
+ private readonly _pendingChanges;
53
+ /**
54
+ * The last created and currently used writer instance.
55
+ */
56
+ private _currentWriter;
57
+ constructor(config?: Config<EngineConfig>);
58
+ /**
59
+ * The `change()` method is the primary way of changing the model. You should use it to modify all document nodes
60
+ * (including detached nodes – i.e. nodes not added to the {@link module:engine/model/model~Model#document model document}),
61
+ * the {@link module:engine/model/document~ModelDocument#selection document's selection}, and
62
+ * {@link module:engine/model/model~Model#markers model markers}.
63
+ *
64
+ * ```ts
65
+ * model.change( writer => {
66
+ * writer.insertText( 'foo', paragraph, 'end' );
67
+ * } );
68
+ * ```
69
+ *
70
+ * All changes inside the change block use the same {@link module:engine/model/batch~Batch} so they are combined
71
+ * into a single undo step.
72
+ *
73
+ * ```ts
74
+ * model.change( writer => {
75
+ * writer.insertText( 'foo', paragraph, 'end' ); // foo.
76
+ *
77
+ * model.change( writer => {
78
+ * writer.insertText( 'bar', paragraph, 'end' ); // foobar.
79
+ * } );
80
+ *
81
+ * writer.insertText( 'bom', paragraph, 'end' ); // foobarbom.
82
+ * } );
83
+ * ```
84
+ *
85
+ * The callback of the `change()` block is executed synchronously.
86
+ *
87
+ * You can also return a value from the change block.
88
+ *
89
+ * ```ts
90
+ * const img = model.change( writer => {
91
+ * return writer.createElement( 'img' );
92
+ * } );
93
+ * ```
94
+ *
95
+ * @see #enqueueChange
96
+ * @typeParam TReturn The return type of the provided callback.
97
+ * @param callback Callback function which may modify the model.
98
+ */
99
+ change<TReturn>(callback: (writer: ModelWriter) => TReturn): TReturn;
100
+ /**
101
+ * The `enqueueChange()` method performs similar task as the {@link #change `change()` method}, with two major differences.
102
+ *
103
+ * First, the callback of `enqueueChange()` is executed when all other enqueued changes are done. It might be executed
104
+ * immediately if it is not nested in any other change block, but if it is nested in another (enqueue)change block,
105
+ * it will be delayed and executed after the outermost block.
106
+ *
107
+ * ```ts
108
+ * model.change( writer => {
109
+ * console.log( 1 );
110
+ *
111
+ * model.enqueueChange( writer => {
112
+ * console.log( 2 );
113
+ * } );
114
+ *
115
+ * console.log( 3 );
116
+ * } ); // Will log: 1, 3, 2.
117
+ * ```
118
+ *
119
+ * In addition to that, the changes enqueued with `enqueueChange()` will be converted separately from the changes
120
+ * done in the outer `change()` block.
121
+ *
122
+ * By default, a new batch with the default {@link module:engine/model/batch~Batch#constructor batch type} is created.
123
+ * To define the {@link module:engine/model/batch~Batch} into which you want to add your changes,
124
+ * use {@link #enqueueChange:CUSTOM_BATCH `enqueueChange( batchOrType, callback )`}.
125
+ *
126
+ * @label DEFAULT_BATCH
127
+ * @param callback Callback function which may modify the model.
128
+ */
129
+ enqueueChange(callback: (writer: ModelWriter) => unknown): void;
130
+ /**
131
+ * The `enqueueChange()` method performs similar task as the {@link #change `change()` method}, with two major differences.
132
+ *
133
+ * First, the callback of `enqueueChange()` is executed when all other enqueued changes are done. It might be executed
134
+ * immediately if it is not nested in any other change block, but if it is nested in another (enqueue)change block,
135
+ * it will be delayed and executed after the outermost block.
136
+ *
137
+ * ```ts
138
+ * model.change( new Batch(), writer => {
139
+ * console.log( 1 );
140
+ *
141
+ * model.enqueueChange( new Batch(), writer => {
142
+ * console.log( 2 );
143
+ * } );
144
+ *
145
+ * console.log( 3 );
146
+ * } ); // Will log: 1, 3, 2.
147
+ * ```
148
+ *
149
+ * In addition to that, the changes enqueued with `enqueueChange()` will be converted separately from the changes
150
+ * done in the outer `change()` block.
151
+ *
152
+ * Second, it lets you define the {@link module:engine/model/batch~Batch} into which you want to add your changes.
153
+ * If you want to use default {@link module:engine/model/batch~Batch#constructor batch type}, use
154
+ * {@link #enqueueChange:DEFAULT_BATCH `enqueueChange( callback )`}.
155
+ *
156
+ * ```ts
157
+ * model.enqueueChange( { isUndoable: false }, writer => {
158
+ * writer.insertText( 'foo', paragraph, 'end' );
159
+ * } );
160
+ * ```
161
+ *
162
+ * When using the `enqueueChange()` block you can also add some changes to the batch you used before.
163
+ *
164
+ * ```ts
165
+ * model.enqueueChange( batch, writer => {
166
+ * writer.insertText( 'foo', paragraph, 'end' );
167
+ * } );
168
+ * ```
169
+ *
170
+ * In order to make a nested `enqueueChange()` create a single undo step together with the changes done in the outer `change()`
171
+ * block, you can obtain the batch instance from the {@link module:engine/model/writer~ModelWriter#batch writer} of the outer block.
172
+ *
173
+ * @label CUSTOM_BATCH
174
+ * @param batchOrType A batch or a {@link module:engine/model/batch~Batch#constructor batch type} that should be used in the callback.
175
+ * If not defined, a new batch with the default type will be created.
176
+ * @param callback Callback function which may modify the model.
177
+ */
178
+ enqueueChange(batchOrType: Batch | BatchType | undefined, callback: (writer: ModelWriter) => unknown): void;
179
+ /**
180
+ * {@link module:utils/observablemixin~Observable#decorate Decorated} function for applying
181
+ * {@link module:engine/model/operation/operation~Operation operations} to the model.
182
+ *
183
+ * This is a low-level way of changing the model. It is exposed for very specific use cases (like the undo feature).
184
+ * Normally, to modify the model, you will want to use {@link module:engine/model/writer~ModelWriter `Writer`}.
185
+ * See also {@glink framework/architecture/editing-engine#changing-the-model Changing the model} section
186
+ * of the {@glink framework/architecture/editing-engine Editing architecture} guide.
187
+ *
188
+ * @param operation The operation to apply.
189
+ */
190
+ applyOperation(operation: Operation): void;
191
+ /**
192
+ * Inserts content at the position in the editor specified by the selection, as one would expect the paste
193
+ * functionality to work.
194
+ *
195
+ * **Note**: If you want to insert an {@glink framework/deep-dive/schema#object-elements object element}
196
+ * (e.g. a {@link module:widget/utils~toWidget widget}), see {@link #insertObject} instead.
197
+ *
198
+ * This is a high-level method. It takes the {@link #schema schema} into consideration when inserting
199
+ * the content, clears the given selection's content before inserting nodes and moves the selection
200
+ * to its target position at the end of the process.
201
+ * It can split elements, merge them, wrap bare text nodes with paragraphs, etc. &ndash; just like the
202
+ * pasting feature should do.
203
+ *
204
+ * For lower-level methods see {@link module:engine/model/writer~ModelWriter `Writer`}.
205
+ *
206
+ * This method, unlike {@link module:engine/model/writer~ModelWriter `Writer`}'s methods, does not have to be used
207
+ * inside a {@link #change `change()` block}.
208
+ *
209
+ * # Conversion and schema
210
+ *
211
+ * Inserting elements and text nodes into the model is not enough to make CKEditor 5 render that content
212
+ * to the user. CKEditor 5 implements a model-view-controller architecture and what `model.insertContent()` does
213
+ * is only adding nodes to the model. Additionally, you need to define
214
+ * {@glink framework/architecture/editing-engine#conversion converters} between the model and view
215
+ * and define those nodes in the {@glink framework/architecture/editing-engine#schema schema}.
216
+ *
217
+ * So, while this method may seem similar to CKEditor 4 `editor.insertHtml()` (in fact, both methods
218
+ * are used for paste-like content insertion), the CKEditor 5 method cannot be use to insert arbitrary HTML
219
+ * unless converters are defined for all elements and attributes in that HTML.
220
+ *
221
+ * # Examples
222
+ *
223
+ * Using `insertContent()` with a manually created model structure:
224
+ *
225
+ * ```ts
226
+ * // Let's create a document fragment containing such content as:
227
+ * //
228
+ * // <paragraph>foo</paragraph>
229
+ * // <blockQuote>
230
+ * // <paragraph>bar</paragraph>
231
+ * // </blockQuote>
232
+ * const docFrag = editor.model.change( writer => {
233
+ * const p1 = writer.createElement( 'paragraph' );
234
+ * const p2 = writer.createElement( 'paragraph' );
235
+ * const blockQuote = writer.createElement( 'blockQuote' );
236
+ * const docFrag = writer.createDocumentFragment();
237
+ *
238
+ * writer.append( p1, docFrag );
239
+ * writer.append( blockQuote, docFrag );
240
+ * writer.append( p2, blockQuote );
241
+ * writer.insertText( 'foo', p1 );
242
+ * writer.insertText( 'bar', p2 );
243
+ *
244
+ * return docFrag;
245
+ * } );
246
+ *
247
+ * // insertContent() does not have to be used in a change() block. It can, though,
248
+ * // so this code could be moved to the callback defined above.
249
+ * editor.model.insertContent( docFrag );
250
+ * ```
251
+ *
252
+ * Using `insertContent()` with an HTML string converted to a model document fragment (similar to the pasting mechanism):
253
+ *
254
+ * ```ts
255
+ * // You can create your own HtmlDataProcessor instance or use editor.data.processor
256
+ * // if you have not overridden the default one (which is the HtmlDataProcessor instance).
257
+ * const htmlDP = new HtmlDataProcessor( viewDocument );
258
+ *
259
+ * // Convert an HTML string to a view document fragment:
260
+ * const viewFragment = htmlDP.toView( htmlString );
261
+ *
262
+ * // Convert the view document fragment to a model document fragment
263
+ * // in the context of $root. This conversion takes the schema into
264
+ * // account so if, for example, the view document fragment contained a bare text node,
265
+ * // this text node cannot be a child of $root, so it will be automatically
266
+ * // wrapped with a <paragraph>. You can define the context yourself (in the second parameter),
267
+ * // and e.g. convert the content like it would happen in a <paragraph>.
268
+ * // Note: The clipboard feature uses a custom context called $clipboardHolder
269
+ * // which has a loosened schema.
270
+ * const modelFragment = editor.data.toModel( viewFragment );
271
+ *
272
+ * editor.model.insertContent( modelFragment );
273
+ * ```
274
+ *
275
+ * By default this method will use the document selection but it can also be used with a position, range or selection instance.
276
+ *
277
+ * ```ts
278
+ * // Insert text at the current document selection position.
279
+ * editor.model.change( writer => {
280
+ * editor.model.insertContent( writer.createText( 'x' ) );
281
+ * } );
282
+ *
283
+ * // Insert text at a given position - the document selection will not be modified.
284
+ * editor.model.change( writer => {
285
+ * editor.model.insertContent( writer.createText( 'x' ), doc.getRoot(), 2 );
286
+ *
287
+ * // Which is a shorthand for:
288
+ * editor.model.insertContent( writer.createText( 'x' ), writer.createPositionAt( doc.getRoot(), 2 ) );
289
+ * } );
290
+ * ```
291
+ *
292
+ * If you want the document selection to be moved to the inserted content, use the
293
+ * {@link module:engine/model/writer~ModelWriter#setSelection `setSelection()`} method of the writer after inserting
294
+ * the content:
295
+ *
296
+ * ```ts
297
+ * editor.model.change( writer => {
298
+ * const paragraph = writer.createElement( 'paragraph' );
299
+ *
300
+ * // Insert an empty paragraph at the beginning of the root.
301
+ * editor.model.insertContent( paragraph, writer.createPositionAt( editor.model.document.getRoot(), 0 ) );
302
+ *
303
+ * // Move the document selection to the inserted paragraph.
304
+ * writer.setSelection( paragraph, 'in' );
305
+ * } );
306
+ * ```
307
+ *
308
+ * If an instance of the {@link module:engine/model/selection~ModelSelection model selection} is passed as `selectable`,
309
+ * the new content will be inserted at the passed selection (instead of document selection):
310
+ *
311
+ * ```ts
312
+ * editor.model.change( writer => {
313
+ * // Create a selection in a paragraph that will be used as a place of insertion.
314
+ * const selection = writer.createSelection( paragraph, 'in' );
315
+ *
316
+ * // Insert the new text at the created selection.
317
+ * editor.model.insertContent( writer.createText( 'x' ), selection );
318
+ *
319
+ * // insertContent() modifies the passed selection instance so it can be used to set the document selection.
320
+ * // Note: This is not necessary when you passed the document selection to insertContent().
321
+ * writer.setSelection( selection );
322
+ * } );
323
+ * ```
324
+ *
325
+ * @fires insertContent
326
+ * @param content The content to insert.
327
+ * @param selectable The selection into which the content should be inserted.
328
+ * If not provided the current model document selection will be used.
329
+ * @param placeOrOffset To be used when a model item was passed as `selectable`.
330
+ * This param defines a position in relation to that item.
331
+ * at the insertion position.
332
+ */
333
+ insertContent(content: ModelItem | ModelDocumentFragment, selectable?: ModelSelectable, placeOrOffset?: ModelPlaceOrOffset, ...rest: Array<unknown>): ModelRange;
334
+ /**
335
+ * Inserts an {@glink framework/deep-dive/schema#object-elements object element} at a specific position in the editor content.
336
+ *
337
+ * This is a high-level API:
338
+ * * It takes the {@link #schema schema} into consideration,
339
+ * * It clears the content of passed `selectable` before inserting,
340
+ * * It can move the selection at the end of the process,
341
+ * * It will copy the selected block's attributes to preserve them upon insertion,
342
+ * * It can split elements or wrap inline objects with paragraphs if they are not allowed in target position,
343
+ * * etc.
344
+ *
345
+ * # Notes
346
+ *
347
+ * * If you want to insert a non-object content, see {@link #insertContent} instead.
348
+ * * For lower-level API, see {@link module:engine/model/writer~ModelWriter `Writer`}.
349
+ * * Unlike {@link module:engine/model/writer~ModelWriter `Writer`}, this method does not have to be used inside
350
+ * a {@link #change `change()` block}.
351
+ * * Inserting object into the model is not enough to make CKEditor 5 render that content to the user.
352
+ * CKEditor 5 implements a model-view-controller architecture and what `model.insertObject()` does
353
+ * is only adding nodes to the model. Additionally, you need to define
354
+ * {@glink framework/architecture/editing-engine#conversion converters} between the model and view
355
+ * and define those nodes in the {@glink framework/architecture/editing-engine#schema schema}.
356
+ *
357
+ * # Examples
358
+ *
359
+ * Use the following code to insert an object at the current selection and keep the selection on the inserted element:
360
+ *
361
+ * ```ts
362
+ * const rawHtmlEmbedElement = writer.createElement( 'rawHtml' );
363
+ *
364
+ * model.insertObject( rawHtmlEmbedElement, null, null, {
365
+ * setSelection: 'on'
366
+ * } );
367
+ * ```
368
+ *
369
+ * Use the following code to insert an object at the current selection and nudge the selection after the inserted object:
370
+ *
371
+ * ```ts
372
+ * const pageBreakElement = writer.createElement( 'pageBreak' );
373
+ *
374
+ * model.insertObject( pageBreakElement, null, null, {
375
+ * setSelection: 'after'
376
+ * } );
377
+ * ```
378
+ *
379
+ * Use the following code to insert an object at the current selection and avoid splitting the content (non-destructive insertion):
380
+ *
381
+ * ```ts
382
+ * const tableElement = writer.createElement( 'table' );
383
+ *
384
+ * model.insertObject( tableElement, null, null, {
385
+ * findOptimalPosition: 'auto'
386
+ * } );
387
+ * ```
388
+ *
389
+ * Use the following code to insert an object at the specific range (also: replace the content of the range):
390
+ *
391
+ * ```ts
392
+ * const tableElement = writer.createElement( 'table' );
393
+ * const range = model.createRangeOn( model.document.getRoot().getChild( 1 ) );
394
+ *
395
+ * model.insertObject( tableElement, range );
396
+ * ```
397
+ *
398
+ * @param element An object to be inserted into the model document.
399
+ * @param selectable A selectable where the content should be inserted. If not specified, the current
400
+ * {@link module:engine/model/document~ModelDocument#selection document selection} will be used instead.
401
+ * @param placeOrOffset Specifies the exact place or offset for the insertion to take place, relative to `selectable`.
402
+ * @param options Additional options.
403
+ * @param options.findOptimalPosition An option that, when set, adjusts the insertion position (relative to
404
+ * `selectable` and `placeOrOffset`) so that the content of `selectable` is not split upon insertion (a.k.a. non-destructive insertion).
405
+ * * When `'auto'`, the algorithm will decide whether to insert the object before or after `selectable` to avoid content splitting.
406
+ * * When `'before'`, the closest position before `selectable` will be used that will not result in content splitting.
407
+ * * When `'after'`, the closest position after `selectable` will be used that will not result in content splitting.
408
+ *
409
+ * Note that this option only works for block objects. Inline objects are inserted into text and do not split blocks.
410
+ * @param options.setSelection An option that, when set, moves the
411
+ * {@link module:engine/model/document~ModelDocument#selection document selection} after inserting the object.
412
+ * * When `'on'`, the document selection will be set on the inserted object.
413
+ * * When `'after'`, the document selection will move to the closest text node after the inserted object. If there is no
414
+ * such text node, a paragraph will be created and the document selection will be moved inside it.
415
+ * at the insertion position.
416
+ */
417
+ insertObject(element: ModelElement, selectable?: ModelSelectable, placeOrOffset?: ModelPlaceOrOffset | null, options?: {
418
+ findOptimalPosition?: "auto" | "before" | "after";
419
+ setSelection?: "on" | "after";
420
+ }, ...rest: Array<unknown>): ModelRange;
421
+ /**
422
+ * Deletes content of the selection and merge siblings. The resulting selection is always collapsed.
423
+ *
424
+ * **Note:** For the sake of predictability, the resulting selection should always be collapsed.
425
+ * In cases where a feature wants to modify deleting behavior so selection isn't collapsed
426
+ * (e.g. a table feature may want to keep row selection after pressing <kbd>Backspace</kbd>),
427
+ * then that behavior should be implemented in the view's listener. At the same time, the table feature
428
+ * will need to modify this method's behavior too, e.g. to "delete contents and then collapse
429
+ * the selection inside the last selected cell" or "delete the row and collapse selection somewhere near".
430
+ * That needs to be done in order to ensure that other features which use `deleteContent()` will work well with tables.
431
+ *
432
+ * @fires deleteContent
433
+ * @param selection Selection of which the content should be deleted.
434
+ * @param options.leaveUnmerged Whether to merge elements after removing the content of the selection.
435
+ *
436
+ * For example `<heading1>x[x</heading1><paragraph>y]y</paragraph>` will become:
437
+ *
438
+ * * `<heading1>x^y</heading1>` with the option disabled (`leaveUnmerged == false`)
439
+ * * `<heading1>x^</heading1><paragraph>y</paragraph>` with enabled (`leaveUnmerged == true`).
440
+ *
441
+ * Note: {@link module:engine/model/schema~ModelSchema#isObject object} and {@link module:engine/model/schema~ModelSchema#isLimit limit}
442
+ * elements will not be merged.
443
+ *
444
+ * @param options.doNotResetEntireContent Whether to skip replacing the entire content with a
445
+ * paragraph when the entire content was selected.
446
+ *
447
+ * For example `<heading1>[x</heading1><paragraph>y]</paragraph>` will become:
448
+ *
449
+ * * `<paragraph>^</paragraph>` with the option disabled (`doNotResetEntireContent == false`)
450
+ * * `<heading1>^</heading1>` with enabled (`doNotResetEntireContent == true`)
451
+ *
452
+ * @param options.doNotAutoparagraph Whether to create a paragraph if after content deletion selection is moved
453
+ * to a place where text cannot be inserted.
454
+ *
455
+ * For example `<paragraph>x</paragraph>[<imageBlock src="foo.jpg"></imageBlock>]` will become:
456
+ *
457
+ * * `<paragraph>x</paragraph><paragraph>[]</paragraph>` with the option disabled (`doNotAutoparagraph == false`)
458
+ * * `<paragraph>x[]</paragraph>` with the option enabled (`doNotAutoparagraph == true`).
459
+ *
460
+ * **Note:** if there is no valid position for the selection, the paragraph will always be created:
461
+ *
462
+ * `[<imageBlock src="foo.jpg"></imageBlock>]` -> `<paragraph>[]</paragraph>`.
463
+ *
464
+ * @param options.direction The direction in which the content is being consumed.
465
+ * Deleting backward corresponds to using the <kbd>Backspace</kbd> key, while deleting content forward corresponds to
466
+ * the <kbd>Shift</kbd>+<kbd>Backspace</kbd> keystroke.
467
+ */
468
+ deleteContent(selection: ModelSelection | ModelDocumentSelection, options?: {
469
+ leaveUnmerged?: boolean;
470
+ doNotResetEntireContent?: boolean;
471
+ doNotAutoparagraph?: boolean;
472
+ direction?: "forward" | "backward";
473
+ [i: string]: unknown;
474
+ }): void;
475
+ /**
476
+ * Modifies the selection. Currently, the supported modifications are:
477
+ *
478
+ * * Extending. The selection focus is moved in the specified `options.direction` with a step specified in `options.unit`.
479
+ * Possible values for `unit` are:
480
+ * * `'character'` (default) - moves selection by one user-perceived character. In most cases this means moving by one
481
+ * character in `String` sense. However, unicode also defines "combing marks". These are special symbols, that combines
482
+ * with a symbol before it ("base character") to create one user-perceived character. For example, `q̣̇` is a normal
483
+ * letter `q` with two "combining marks": upper dot (`Ux0307`) and lower dot (`Ux0323`). For most actions, i.e. extending
484
+ * selection by one position, it is correct to include both "base character" and all of it's "combining marks". That is
485
+ * why `'character'` value is most natural and common method of modifying selection.
486
+ * * `'codePoint'` - moves selection by one unicode code point. In contrary to, `'character'` unit, this will insert
487
+ * selection between "base character" and "combining mark", because "combining marks" have their own unicode code points.
488
+ * However, for technical reasons, unicode code points with values above `UxFFFF` are represented in native `String` by
489
+ * two characters, called "surrogate pairs". Halves of "surrogate pairs" have a meaning only when placed next to each other.
490
+ * For example `𨭎` is represented in `String` by `\uD862\uDF4E`. Both `\uD862` and `\uDF4E` do not have any meaning
491
+ * outside the pair (are rendered as ? when alone). Position between them would be incorrect. In this case, selection
492
+ * extension will include whole "surrogate pair".
493
+ * * `'word'` - moves selection by a whole word.
494
+ *
495
+ * **Note:** if you extend a forward selection in a backward direction you will in fact shrink it.
496
+ *
497
+ * @fires modifySelection
498
+ * @param selection The selection to modify.
499
+ * @param options.direction The direction in which the selection should be modified.
500
+ * @param options.unit The unit by which selection should be modified.
501
+ * @param options.treatEmojiAsSingleUnit Whether multi-characer emoji sequences should be handled as single unit.
502
+ */
503
+ modifySelection(selection: ModelSelection | ModelDocumentSelection, options?: {
504
+ direction?: "forward" | "backward";
505
+ unit?: "character" | "codePoint" | "word";
506
+ treatEmojiAsSingleUnit?: boolean;
507
+ }): void;
508
+ /**
509
+ * Gets a clone of the selected content.
510
+ *
511
+ * For example, for the following selection:
512
+ *
513
+ * ```html
514
+ * <paragraph>x</paragraph>
515
+ * <blockQuote>
516
+ * <paragraph>y</paragraph>
517
+ * <heading1>fir[st</heading1>
518
+ * </blockQuote>
519
+ * <paragraph>se]cond</paragraph>
520
+ * <paragraph>z</paragraph>
521
+ * ```
522
+ *
523
+ * It will return a document fragment with such a content:
524
+ *
525
+ * ```html
526
+ * <blockQuote>
527
+ * <heading1>st</heading1>
528
+ * </blockQuote>
529
+ * <paragraph>se</paragraph>
530
+ * ```
531
+ *
532
+ * @fires getSelectedContent
533
+ * @param selection The selection of which content will be returned.
534
+ */
535
+ getSelectedContent(selection: ModelSelection | ModelDocumentSelection): ModelDocumentFragment;
536
+ /**
537
+ * Checks whether given `subject` has any meaningful content.
538
+ *
539
+ * Meaningful content is:
540
+ *
541
+ * * any text node (`options.ignoreWhitespaces` allows controlling whether this text node must also contain
542
+ * any non-whitespace characters),
543
+ * * or any {@link module:engine/model/schema~ModelSchema#isContent content element},
544
+ * * or any {@link module:engine/model/markercollection~Marker marker} which
545
+ * {@link module:engine/model/markercollection~Marker#_affectsData affects data}.
546
+ *
547
+ * This means that a range containing an empty `<paragraph></paragraph>` is not considered to have a meaningful content.
548
+ * However, a range containing an `<imageBlock></imageBlock>` (which would normally be marked in the schema as an object element)
549
+ * is considered non-empty.
550
+ *
551
+ * @param subject Subject to check if includes meaningful content. Could be a model range, an element, a document fragment, or a
552
+ * selection.
553
+ * @param options.ignoreWhitespaces Whether text node with whitespaces only should be considered empty.
554
+ * @param options.ignoreMarkers Whether markers should be ignored.
555
+ */
556
+ hasContent(subject: ModelRange | ModelElement | ModelDocumentFragment | ModelSelection | ModelDocumentSelection, options?: {
557
+ ignoreWhitespaces?: boolean;
558
+ ignoreMarkers?: boolean;
559
+ }): boolean;
560
+ /**
561
+ * Checks whether given range has any meaningful content.
562
+ *
563
+ * Helper method for {@link #hasContent}.
564
+ */
565
+ private _rangeHasContent;
566
+ /**
567
+ * Check whether given selectable is at a place in the model where it can be edited (returns `true`) or not (returns `false`).
568
+ *
569
+ * Should be used instead of {@link module:core/editor/editor~Editor#isReadOnly} to check whether a user action can happen at
570
+ * given selectable. It may be decorated and used differently in different environment (e.g. multi-root editor can disable
571
+ * a particular root).
572
+ *
573
+ * This method is decorated. Although this method accepts any parameter of `Selectable` type, the
574
+ * {@link ~Model#event:canEditAt `canEditAt` event} is fired with `selectable` normalized to an instance of
575
+ * {@link module:engine/model/selection~ModelSelection} or {@link module:engine/model/documentselection~ModelDocumentSelection}
576
+ *
577
+ * @fires canEditAt
578
+ */
579
+ canEditAt(selectable: ModelSelectable): boolean;
580
+ /**
581
+ * Creates a position from the given root and path in that root.
582
+ *
583
+ * Note: This method is also available as
584
+ * {@link module:engine/model/writer~ModelWriter#createPositionFromPath `Writer#createPositionFromPath()`}.
585
+ *
586
+ * @param root Root of the position.
587
+ * @param path Position path. See {@link module:engine/model/position~ModelPosition#path}.
588
+ * @param stickiness Position stickiness. See {@link module:engine/model/position~ModelPositionStickiness}.
589
+ */
590
+ createPositionFromPath(root: ModelElement | ModelDocumentFragment, path: ReadonlyArray<number>, stickiness?: ModelPositionStickiness): ModelPosition;
591
+ /**
592
+ * Creates position at the given location. The location can be specified as:
593
+ *
594
+ * * a {@link module:engine/model/position~ModelPosition position},
595
+ * * a parent element and offset in that element,
596
+ * * a parent element and `'end'` (the position will be set at the end of that element),
597
+ * * a {@link module:engine/model/item~ModelItem model item} and `'before'` or `'after'`
598
+ * (the position will be set before or after the given model item).
599
+ *
600
+ * This method is a shortcut to other factory methods such as:
601
+ *
602
+ * * {@link module:engine/model/model~Model#createPositionBefore `createPositionBefore()`},
603
+ * * {@link module:engine/model/model~Model#createPositionAfter `createPositionAfter()`}.
604
+ *
605
+ * Note: This method is also available as
606
+ * {@link module:engine/model/writer~ModelWriter#createPositionAt `Writer#createPositionAt()`},
607
+ *
608
+ * @param itemOrPosition
609
+ * @param offset Offset or one of the flags. Used only when first parameter is a {@link module:engine/model/item~ModelItem model item}.
610
+ */
611
+ createPositionAt(itemOrPosition: ModelItem | ModelPosition | ModelDocumentFragment, offset?: ModelPositionOffset): ModelPosition;
612
+ /**
613
+ * Creates a new position after the given {@link module:engine/model/item~ModelItem model item}.
614
+ *
615
+ * Note: This method is also available as
616
+ * {@link module:engine/model/writer~ModelWriter#createPositionAfter `Writer#createPositionAfter()`}.
617
+ *
618
+ * @param item Item after which the position should be placed.
619
+ */
620
+ createPositionAfter(item: ModelItem): ModelPosition;
621
+ /**
622
+ * Creates a new position before the given {@link module:engine/model/item~ModelItem model item}.
623
+ *
624
+ * Note: This method is also available as
625
+ * {@link module:engine/model/writer~ModelWriter#createPositionBefore `Writer#createPositionBefore()`}.
626
+ *
627
+ * @param item Item before which the position should be placed.
628
+ */
629
+ createPositionBefore(item: ModelItem): ModelPosition;
630
+ /**
631
+ * Creates a range spanning from the `start` position to the `end` position.
632
+ *
633
+ * Note: This method is also available as
634
+ * {@link module:engine/model/writer~ModelWriter#createRange `Writer#createRange()`}:
635
+ *
636
+ * ```ts
637
+ * model.change( writer => {
638
+ * const range = writer.createRange( start, end );
639
+ * } );
640
+ * ```
641
+ *
642
+ * @param start Start position.
643
+ * @param end End position. If not set, the range will be collapsed to the `start` position.
644
+ */
645
+ createRange(start: ModelPosition, end?: ModelPosition): ModelRange;
646
+ /**
647
+ * Creates a range inside the given element which starts before the first child of
648
+ * that element and ends after the last child of that element.
649
+ *
650
+ * Note: This method is also available as
651
+ * {@link module:engine/model/writer~ModelWriter#createRangeIn `Writer#createRangeIn()`}:
652
+ *
653
+ * ```ts
654
+ * model.change( writer => {
655
+ * const range = writer.createRangeIn( paragraph );
656
+ * } );
657
+ * ```
658
+ *
659
+ * @param element Element which is a parent for the range.
660
+ */
661
+ createRangeIn(element: ModelElement | ModelDocumentFragment): ModelRange;
662
+ /**
663
+ * Creates a range that starts before the given {@link module:engine/model/item~ModelItem model item} and ends after it.
664
+ *
665
+ * Note: This method is also available on `writer` instance as
666
+ * {@link module:engine/model/writer~ModelWriter#createRangeOn `Writer.createRangeOn()`}:
667
+ *
668
+ * ```ts
669
+ * model.change( writer => {
670
+ * const range = writer.createRangeOn( paragraph );
671
+ * } );
672
+ * ```
673
+ *
674
+ * @param item
675
+ */
676
+ createRangeOn(item: ModelItem): ModelRange;
677
+ /**
678
+ * Creates a new selection instance based on the given {@link module:engine/model/selection~ModelSelectable selectable}
679
+ * or creates an empty selection if no arguments were passed.
680
+ *
681
+ * Note: This method is also available as
682
+ * {@link module:engine/model/writer~ModelWriter#createSelection `Writer#createSelection()`}.
683
+ *
684
+ * ```ts
685
+ * // Creates selection at the given offset in the given element.
686
+ * const paragraph = writer.createElement( 'paragraph' );
687
+ * const selection = writer.createSelection( paragraph, offset );
688
+ *
689
+ * // Creates a range inside an {@link module:engine/model/element~ModelElement element} which starts before the
690
+ * // first child of that element and ends after the last child of that element.
691
+ * const selection = writer.createSelection( paragraph, 'in' );
692
+ *
693
+ * // Creates a range on an {@link module:engine/model/item~ModelItem item} which starts before the item and ends
694
+ * // just after the item.
695
+ * const selection = writer.createSelection( paragraph, 'on' );
696
+ *
697
+ * // Additional options (`'backward'`) can be specified as the last argument.
698
+ *
699
+ * // Creates backward selection.
700
+ * const selection = writer.createSelection( element, 'in', { backward: true } );
701
+ * ```
702
+ *
703
+ * See also: {@link #createSelection:SELECTABLE `createSelection( selectable, options )`}.
704
+ *
705
+ * @label NODE_OFFSET
706
+ */
707
+ createSelection(selectable: ModelNode, placeOrOffset: ModelPlaceOrOffset, options?: {
708
+ backward?: boolean;
709
+ }): ModelSelection;
710
+ /**
711
+ * Creates a new selection instance based on the given {@link module:engine/model/selection~ModelSelectable selectable}
712
+ * or creates an empty selection if no arguments were passed.
713
+ *
714
+ * Note: This method is also available as
715
+ * {@link module:engine/model/writer~ModelWriter#createSelection `Writer#createSelection()`}.
716
+ *
717
+ * ```ts
718
+ * // Creates empty selection without ranges.
719
+ * const selection = writer.createSelection();
720
+ *
721
+ * // Creates selection at the given range.
722
+ * const range = writer.createRange( start, end );
723
+ * const selection = writer.createSelection( range );
724
+ *
725
+ * // Creates selection at the given ranges
726
+ * const ranges = [ writer.createRange( start1, end2 ), writer.createRange( star2, end2 ) ];
727
+ * const selection = writer.createSelection( ranges );
728
+ *
729
+ * // Creates selection from the other selection.
730
+ * // Note: It doesn't copies selection attributes.
731
+ * const otherSelection = writer.createSelection();
732
+ * const selection = writer.createSelection( otherSelection );
733
+ *
734
+ * // Creates selection from the given document selection.
735
+ * // Note: It doesn't copies selection attributes.
736
+ * const documentSelection = model.document.selection;
737
+ * const selection = writer.createSelection( documentSelection );
738
+ *
739
+ * // Creates selection at the given position.
740
+ * const position = writer.createPositionFromPath( root, path );
741
+ * const selection = writer.createSelection( position );
742
+ *
743
+ * // Additional options (`'backward'`) can be specified as the last argument.
744
+ *
745
+ * // Creates backward selection.
746
+ * const selection = writer.createSelection( range, { backward: true } );
747
+ * ```
748
+ *
749
+ * See also: {@link #createSelection:NODE_OFFSET `createSelection( node, placeOrOffset, options )`}.
750
+ *
751
+ * @label SELECTABLE
752
+ */
753
+ createSelection(selectable?: Exclude<ModelSelectable, ModelNode>, options?: {
754
+ backward?: boolean;
755
+ }): ModelSelection;
756
+ /**
757
+ * Creates a {@link module:engine/model/batch~Batch} instance.
758
+ *
759
+ * **Note:** In most cases creating a batch instance is not necessary as they are created when using:
760
+ *
761
+ * * {@link #change `change()`},
762
+ * * {@link #enqueueChange `enqueueChange()`}.
763
+ *
764
+ * @param type {@link module:engine/model/batch~Batch#constructor The type} of the batch.
765
+ */
766
+ createBatch(type?: BatchType): Batch;
767
+ /**
768
+ * Creates an operation instance from a JSON object (parsed JSON string).
769
+ *
770
+ * This is an alias for {@link module:engine/model/operation/operationfactory~OperationFactory.fromJSON `OperationFactory.fromJSON()`}.
771
+ *
772
+ * @param json Deserialized JSON object.
773
+ */
774
+ createOperationFromJSON(json: unknown): Operation;
775
+ /**
776
+ * Removes all events listeners set by model instance and destroys {@link module:engine/model/document~ModelDocument}.
777
+ */
778
+ destroy(): void;
779
+ /**
780
+ * Common part of {@link module:engine/model/model~Model#change} and {@link module:engine/model/model~Model#enqueueChange}
781
+ * which calls callbacks and returns array of values returned by these callbacks.
782
+ */
783
+ private _runPendingChanges;
787
784
  }
788
785
  /**
789
- * Fired when entering the outermost {@link module:engine/model/model~Model#enqueueChange} or
790
- * {@link module:engine/model/model~Model#change} block.
791
- *
792
- * @internal
793
- * @eventName ~Model#_beforeChanges
794
- */
786
+ * Fired when entering the outermost {@link module:engine/model/model~Model#enqueueChange} or
787
+ * {@link module:engine/model/model~Model#change} block.
788
+ *
789
+ * @internal
790
+ * @eventName ~Model#_beforeChanges
791
+ */
795
792
  export type BeforeChangesEvent = {
796
- name: '_beforeChanges';
797
- args: [];
793
+ name: "_beforeChanges";
794
+ args: [];
798
795
  };
799
796
  /**
800
- * Fired when leaving the outermost {@link module:engine/model/model~Model#enqueueChange} or
801
- * {@link module:engine/model/model~Model#change} block.
802
- *
803
- * @internal
804
- * @eventName ~Model#_afterChanges
805
- */
797
+ * Fired when leaving the outermost {@link module:engine/model/model~Model#enqueueChange} or
798
+ * {@link module:engine/model/model~Model#change} block.
799
+ *
800
+ * @internal
801
+ * @eventName ~Model#_afterChanges
802
+ */
806
803
  export type AfterChangesEvent = {
807
- name: '_afterChanges';
808
- args: [];
804
+ name: "_afterChanges";
805
+ args: [];
809
806
  };
810
807
  /**
811
- * Fired every time any {@link module:engine/model/operation/operation~Operation operation} is applied on the model
812
- * using {@link ~Model#applyOperation}.
813
- *
814
- * Note that this event is suitable only for very specific use-cases. Use it if you need to listen to every single operation
815
- * applied on the document. However, in most cases {@link module:engine/model/document~ModelDocument#event:change} should
816
- * be used.
817
- *
818
- * A few callbacks are already added to this event by engine internal classes:
819
- *
820
- * * with `highest` priority operation is validated,
821
- * * with `normal` priority operation is executed,
822
- * * with `low` priority the {@link module:engine/model/document~ModelDocument} updates its version,
823
- * * with `low` priority {@link module:engine/model/liveposition~ModelLivePosition} and {@link module:engine/model/liverange~ModelLiveRange}
824
- * update themselves.
825
- *
826
- * @eventName ~Model#applyOperation
827
- * @param args Arguments of the `applyOperation` which is an array with a single element - applied
828
- * {@link module:engine/model/operation/operation~Operation operation}.
829
- */
830
- export type ModelApplyOperationEvent = DecoratedMethodEvent<Model, 'applyOperation'>;
808
+ * Fired every time any {@link module:engine/model/operation/operation~Operation operation} is applied on the model
809
+ * using {@link ~Model#applyOperation}.
810
+ *
811
+ * Note that this event is suitable only for very specific use-cases. Use it if you need to listen to every single operation
812
+ * applied on the document. However, in most cases {@link module:engine/model/document~ModelDocument#event:change} should
813
+ * be used.
814
+ *
815
+ * A few callbacks are already added to this event by engine internal classes:
816
+ *
817
+ * * with `highest` priority operation is validated,
818
+ * * with `normal` priority operation is executed,
819
+ * * with `low` priority the {@link module:engine/model/document~ModelDocument} updates its version,
820
+ * * with `low` priority {@link module:engine/model/liveposition~ModelLivePosition} and {@link module:engine/model/liverange~ModelLiveRange}
821
+ * update themselves.
822
+ *
823
+ * @eventName ~Model#applyOperation
824
+ * @param args Arguments of the `applyOperation` which is an array with a single element - applied
825
+ * {@link module:engine/model/operation/operation~Operation operation}.
826
+ */
827
+ export type ModelApplyOperationEvent = DecoratedMethodEvent<Model, "applyOperation">;
831
828
  /**
832
- * Event fired when {@link ~Model#insertContent} method is called.
833
- *
834
- * The {@link ~Model#insertContent default action of that method} is implemented as a
835
- * listener to this event so it can be fully customized by the features.
836
- *
837
- * **Note** The `selectable` parameter for the {@link ~Model#insertContent} is optional. When `undefined` value is passed the method uses
838
- * {@link module:engine/model/document~ModelDocument#selection document selection}.
839
- *
840
- * @eventName ~Model#insertContent
841
- * @param args The arguments passed to the original method.
842
- */
829
+ * Event fired when {@link ~Model#insertContent} method is called.
830
+ *
831
+ * The {@link ~Model#insertContent default action of that method} is implemented as a
832
+ * listener to this event so it can be fully customized by the features.
833
+ *
834
+ * **Note** The `selectable` parameter for the {@link ~Model#insertContent} is optional. When `undefined` value is passed the method uses
835
+ * {@link module:engine/model/document~ModelDocument#selection document selection}.
836
+ *
837
+ * @eventName ~Model#insertContent
838
+ * @param args The arguments passed to the original method.
839
+ */
843
840
  export type ModelInsertContentEvent = {
844
- name: 'insertContent';
845
- args: [
846
- [
847
- content: ModelItem | ModelDocumentFragment,
848
- selectable?: ModelSelection | ModelDocumentSelection,
849
- ...rest: Array<unknown>
850
- ]
851
- ];
852
- return: ModelRange;
841
+ name: "insertContent";
842
+ args: [[content: ModelItem | ModelDocumentFragment, selectable?: ModelSelection | ModelDocumentSelection, ...rest: Array<unknown>]];
843
+ return: ModelRange;
853
844
  };
854
845
  /**
855
- * Event fired when the {@link ~Model#insertObject} method is called.
856
- *
857
- * The {@link ~Model#insertObject default action of that method} is implemented as a
858
- * listener to this event so it can be fully customized by the features.
859
- *
860
- * **Note** The `selectable` parameter for the {@link ~Model#insertObject} is optional. When `undefined` value is passed the method uses
861
- * {@link module:engine/model/document~ModelDocument#selection document selection}.
862
- *
863
- * @eventName ~Model#insertObject
864
- * @param args The arguments passed to the original method.
865
- */
846
+ * Event fired when the {@link ~Model#insertObject} method is called.
847
+ *
848
+ * The {@link ~Model#insertObject default action of that method} is implemented as a
849
+ * listener to this event so it can be fully customized by the features.
850
+ *
851
+ * **Note** The `selectable` parameter for the {@link ~Model#insertObject} is optional. When `undefined` value is passed the method uses
852
+ * {@link module:engine/model/document~ModelDocument#selection document selection}.
853
+ *
854
+ * @eventName ~Model#insertObject
855
+ * @param args The arguments passed to the original method.
856
+ */
866
857
  export type ModelInsertObjectEvent = {
867
- name: 'insertObject';
868
- args: [
869
- [
870
- element: ModelElement,
871
- selectable?: ModelSelection | ModelDocumentSelection | null,
872
- options?: {
873
- findOptimalPosition?: 'auto' | 'before' | 'after';
874
- setSelection?: 'on' | 'after';
875
- },
876
- ...rest: Array<unknown>
877
- ]
878
- ];
879
- return: ModelRange;
858
+ name: "insertObject";
859
+ args: [[element: ModelElement, selectable?: ModelSelection | ModelDocumentSelection | null, options?: {
860
+ findOptimalPosition?: "auto" | "before" | "after";
861
+ setSelection?: "on" | "after";
862
+ }, ...rest: Array<unknown>]];
863
+ return: ModelRange;
880
864
  };
881
865
  /**
882
- * Event fired when {@link ~Model#deleteContent} method is called.
883
- *
884
- * The {@link ~Model#deleteContent default action of that method} is implemented as a
885
- * listener to this event, so it can be fully customized by the features.
886
- *
887
- * @eventName ~Model#deleteContent
888
- * @param args The arguments passed to the original method.
889
- */
890
- export type ModelDeleteContentEvent = DecoratedMethodEvent<Model, 'deleteContent'>;
866
+ * Event fired when {@link ~Model#deleteContent} method is called.
867
+ *
868
+ * The {@link ~Model#deleteContent default action of that method} is implemented as a
869
+ * listener to this event, so it can be fully customized by the features.
870
+ *
871
+ * @eventName ~Model#deleteContent
872
+ * @param args The arguments passed to the original method.
873
+ */
874
+ export type ModelDeleteContentEvent = DecoratedMethodEvent<Model, "deleteContent">;
891
875
  /**
892
- * Event fired when {@link ~Model#modifySelection} method is called.
893
- *
894
- * The {@link ~Model#modifySelection default action of that method} is implemented as a
895
- * listener to this event, so it can be fully customized by the features.
896
- *
897
- * @eventName ~Model#modifySelection
898
- * @param args The arguments passed to the original method.
899
- */
900
- export type ModelModifySelectionEvent = DecoratedMethodEvent<Model, 'modifySelection'>;
876
+ * Event fired when {@link ~Model#modifySelection} method is called.
877
+ *
878
+ * The {@link ~Model#modifySelection default action of that method} is implemented as a
879
+ * listener to this event, so it can be fully customized by the features.
880
+ *
881
+ * @eventName ~Model#modifySelection
882
+ * @param args The arguments passed to the original method.
883
+ */
884
+ export type ModelModifySelectionEvent = DecoratedMethodEvent<Model, "modifySelection">;
901
885
  /**
902
- * Event fired when {@link ~Model#getSelectedContent} method is called.
903
- *
904
- * The {@link ~Model#getSelectedContent default action of that method} is implemented as a
905
- * listener to this event, so it can be fully customized by the features.
906
- *
907
- * @eventName ~Model#getSelectedContent
908
- * @param args The arguments passed to the original method.
909
- */
910
- export type ModelGetSelectedContentEvent = DecoratedMethodEvent<Model, 'getSelectedContent'>;
886
+ * Event fired when {@link ~Model#getSelectedContent} method is called.
887
+ *
888
+ * The {@link ~Model#getSelectedContent default action of that method} is implemented as a
889
+ * listener to this event, so it can be fully customized by the features.
890
+ *
891
+ * @eventName ~Model#getSelectedContent
892
+ * @param args The arguments passed to the original method.
893
+ */
894
+ export type ModelGetSelectedContentEvent = DecoratedMethodEvent<Model, "getSelectedContent">;
911
895
  /**
912
- * Event fired when {@link ~Model#canEditAt} method is called.
913
- *
914
- * The {@link ~Model#canEditAt default action of that method} is implemented as a
915
- * listener to this event, so it can be fully customized by the features.
916
- *
917
- * Although the original method accepts any parameter of `Selectable` type, this event is fired with `selectable` normalized
918
- * to an instance of {@link module:engine/model/selection~ModelSelection} or
919
- * {@link module:engine/model/documentselection~ModelDocumentSelection}.
920
- *
921
- * @eventName ~Model#canEditAt
922
- * @param args The arguments passed to the original method.
923
- */
896
+ * Event fired when {@link ~Model#canEditAt} method is called.
897
+ *
898
+ * The {@link ~Model#canEditAt default action of that method} is implemented as a
899
+ * listener to this event, so it can be fully customized by the features.
900
+ *
901
+ * Although the original method accepts any parameter of `Selectable` type, this event is fired with `selectable` normalized
902
+ * to an instance of {@link module:engine/model/selection~ModelSelection} or
903
+ * {@link module:engine/model/documentselection~ModelDocumentSelection}.
904
+ *
905
+ * @eventName ~Model#canEditAt
906
+ * @param args The arguments passed to the original method.
907
+ */
924
908
  export type ModelCanEditAtEvent = {
925
- name: 'canEditAt';
926
- args: [
927
- [
928
- selectable?: ModelSelection | ModelDocumentSelection
929
- ]
930
- ];
931
- return: boolean;
909
+ name: "canEditAt";
910
+ args: [[selectable?: ModelSelection | ModelDocumentSelection]];
911
+ return: boolean;
932
912
  };
933
913
  export {};