diffdown.com
Diffdown is a real-time collaborative Markdown editor/previewer built on the AT Protocol
diffdown.com
1/**
2A text iterator iterates over a sequence of strings. When
3iterating over a [`Text`](https://codemirror.net/6/docs/ref/#state.Text) document, result values will
4either be lines or line breaks.
5*/
6interface TextIterator extends Iterator<string>, Iterable<string> {
7 /**
8 Retrieve the next string. Optionally skip a given number of
9 positions after the current position. Always returns the object
10 itself.
11 */
12 next(skip?: number): this;
13 /**
14 The current string. Will be the empty string when the cursor is
15 at its end or `next` hasn't been called on it yet.
16 */
17 value: string;
18 /**
19 Whether the end of the iteration has been reached. You should
20 probably check this right after calling `next`.
21 */
22 done: boolean;
23 /**
24 Whether the current string represents a line break.
25 */
26 lineBreak: boolean;
27}
28/**
29The data structure for documents. @nonabstract
30*/
31declare abstract class Text implements Iterable<string> {
32 /**
33 The length of the string.
34 */
35 abstract readonly length: number;
36 /**
37 The number of lines in the string (always >= 1).
38 */
39 abstract readonly lines: number;
40 /**
41 Get the line description around the given position.
42 */
43 lineAt(pos: number): Line;
44 /**
45 Get the description for the given (1-based) line number.
46 */
47 line(n: number): Line;
48 /**
49 Replace a range of the text with the given content.
50 */
51 replace(from: number, to: number, text: Text): Text;
52 /**
53 Append another document to this one.
54 */
55 append(other: Text): Text;
56 /**
57 Retrieve the text between the given points.
58 */
59 slice(from: number, to?: number): Text;
60 /**
61 Retrieve a part of the document as a string
62 */
63 abstract sliceString(from: number, to?: number, lineSep?: string): string;
64 /**
65 Test whether this text is equal to another instance.
66 */
67 eq(other: Text): boolean;
68 /**
69 Iterate over the text. When `dir` is `-1`, iteration happens
70 from end to start. This will return lines and the breaks between
71 them as separate strings.
72 */
73 iter(dir?: 1 | -1): TextIterator;
74 /**
75 Iterate over a range of the text. When `from` > `to`, the
76 iterator will run in reverse.
77 */
78 iterRange(from: number, to?: number): TextIterator;
79 /**
80 Return a cursor that iterates over the given range of lines,
81 _without_ returning the line breaks between, and yielding empty
82 strings for empty lines.
83
84 When `from` and `to` are given, they should be 1-based line numbers.
85 */
86 iterLines(from?: number, to?: number): TextIterator;
87 /**
88 Return the document as a string, using newline characters to
89 separate lines.
90 */
91 toString(): string;
92 /**
93 Convert the document to an array of lines (which can be
94 deserialized again via [`Text.of`](https://codemirror.net/6/docs/ref/#state.Text^of)).
95 */
96 toJSON(): string[];
97 /**
98 If this is a branch node, `children` will hold the `Text`
99 objects that it is made up of. For leaf nodes, this holds null.
100 */
101 abstract readonly children: readonly Text[] | null;
102 /**
103 @hide
104 */
105 [Symbol.iterator]: () => Iterator<string>;
106 /**
107 Create a `Text` instance for the given array of lines.
108 */
109 static of(text: readonly string[]): Text;
110 /**
111 The empty document.
112 */
113 static empty: Text;
114}
115/**
116This type describes a line in the document. It is created
117on-demand when lines are [queried](https://codemirror.net/6/docs/ref/#state.Text.lineAt).
118*/
119declare class Line {
120 /**
121 The position of the start of the line.
122 */
123 readonly from: number;
124 /**
125 The position at the end of the line (_before_ the line break,
126 or at the end of document for the last line).
127 */
128 readonly to: number;
129 /**
130 This line's line number (1-based).
131 */
132 readonly number: number;
133 /**
134 The line's content.
135 */
136 readonly text: string;
137 /**
138 The length of the line (not including any line break after it).
139 */
140 get length(): number;
141}
142
143/**
144Distinguishes different ways in which positions can be mapped.
145*/
146declare enum MapMode {
147 /**
148 Map a position to a valid new position, even when its context
149 was deleted.
150 */
151 Simple = 0,
152 /**
153 Return null if deletion happens across the position.
154 */
155 TrackDel = 1,
156 /**
157 Return null if the character _before_ the position is deleted.
158 */
159 TrackBefore = 2,
160 /**
161 Return null if the character _after_ the position is deleted.
162 */
163 TrackAfter = 3
164}
165/**
166A change description is a variant of [change set](https://codemirror.net/6/docs/ref/#state.ChangeSet)
167that doesn't store the inserted text. As such, it can't be
168applied, but is cheaper to store and manipulate.
169*/
170declare class ChangeDesc {
171 /**
172 The length of the document before the change.
173 */
174 get length(): number;
175 /**
176 The length of the document after the change.
177 */
178 get newLength(): number;
179 /**
180 False when there are actual changes in this set.
181 */
182 get empty(): boolean;
183 /**
184 Iterate over the unchanged parts left by these changes. `posA`
185 provides the position of the range in the old document, `posB`
186 the new position in the changed document.
187 */
188 iterGaps(f: (posA: number, posB: number, length: number) => void): void;
189 /**
190 Iterate over the ranges changed by these changes. (See
191 [`ChangeSet.iterChanges`](https://codemirror.net/6/docs/ref/#state.ChangeSet.iterChanges) for a
192 variant that also provides you with the inserted text.)
193 `fromA`/`toA` provides the extent of the change in the starting
194 document, `fromB`/`toB` the extent of the replacement in the
195 changed document.
196
197 When `individual` is true, adjacent changes (which are kept
198 separate for [position mapping](https://codemirror.net/6/docs/ref/#state.ChangeDesc.mapPos)) are
199 reported separately.
200 */
201 iterChangedRanges(f: (fromA: number, toA: number, fromB: number, toB: number) => void, individual?: boolean): void;
202 /**
203 Get a description of the inverted form of these changes.
204 */
205 get invertedDesc(): ChangeDesc;
206 /**
207 Compute the combined effect of applying another set of changes
208 after this one. The length of the document after this set should
209 match the length before `other`.
210 */
211 composeDesc(other: ChangeDesc): ChangeDesc;
212 /**
213 Map this description, which should start with the same document
214 as `other`, over another set of changes, so that it can be
215 applied after it. When `before` is true, map as if the changes
216 in `this` happened before the ones in `other`.
217 */
218 mapDesc(other: ChangeDesc, before?: boolean): ChangeDesc;
219 /**
220 Map a given position through these changes, to produce a
221 position pointing into the new document.
222
223 `assoc` indicates which side the position should be associated
224 with. When it is negative, the mapping will try to keep the
225 position close to the character before it (if any), and will
226 move it before insertions at that point or replacements across
227 that point. When it is zero or positive, the position is associated
228 with the character after it, and will be moved forward for
229 */
230 /**
231
232 `mode` determines whether deletions should be
233 [reported](https://codemirror.net/6/docs/ref/#state.MapMode). It defaults to
234 [`MapMode.Simple`](https://codemirror.net/6/docs/ref/#state.MapMode.Simple) (don't report
235 deletions).
236 */
237 mapPos(pos: number, assoc?: number): number;
238 mapPos(pos: number, assoc: number, mode: MapMode): number | null;
239 /**
240 Check whether these changes touch a given range. When one of the
241 changes entirely covers the range, the string `"cover"` is
242 returned.
243 */
244 touchesRange(from: number, to?: number): boolean | "cover";
245 /**
246 Serialize this change desc to a JSON-representable value.
247 */
248 toJSON(): readonly number[];
249 /**
250 Create a change desc from its JSON representation (as produced
251 by [`toJSON`](https://codemirror.net/6/docs/ref/#state.ChangeDesc.toJSON).
252 */
253 static fromJSON(json: any): ChangeDesc;
254}
255/**
256This type is used as argument to
257[`EditorState.changes`](https://codemirror.net/6/docs/ref/#state.EditorState.changes) and in the
258[`changes` field](https://codemirror.net/6/docs/ref/#state.TransactionSpec.changes) of transaction
259specs to succinctly describe document changes. It may either be a
260plain object describing a change (a deletion, insertion, or
261replacement, depending on which fields are present), a [change
262set](https://codemirror.net/6/docs/ref/#state.ChangeSet), or an array of change specs.
263*/
264type ChangeSpec = {
265 from: number;
266 to?: number;
267 insert?: string | Text;
268} | ChangeSet | readonly ChangeSpec[];
269/**
270A change set represents a group of modifications to a document. It
271stores the document length, and can only be applied to documents
272with exactly that length.
273*/
274declare class ChangeSet extends ChangeDesc {
275 private constructor();
276 /**
277 Apply the changes to a document, returning the modified
278 document.
279 */
280 apply(doc: Text): Text;
281 mapDesc(other: ChangeDesc, before?: boolean): ChangeDesc;
282 /**
283 Given the document as it existed _before_ the changes, return a
284 change set that represents the inverse of this set, which could
285 be used to go from the document created by the changes back to
286 the document as it existed before the changes.
287 */
288 invert(doc: Text): ChangeSet;
289 /**
290 Combine two subsequent change sets into a single set. `other`
291 must start in the document produced by `this`. If `this` goes
292 `docA` → `docB` and `other` represents `docB` → `docC`, the
293 returned value will represent the change `docA` → `docC`.
294 */
295 compose(other: ChangeSet): ChangeSet;
296 /**
297 Given another change set starting in the same document, maps this
298 change set over the other, producing a new change set that can be
299 applied to the document produced by applying `other`. When
300 `before` is `true`, order changes as if `this` comes before
301 `other`, otherwise (the default) treat `other` as coming first.
302
303 Given two changes `A` and `B`, `A.compose(B.map(A))` and
304 `B.compose(A.map(B, true))` will produce the same document. This
305 provides a basic form of [operational
306 transformation](https://en.wikipedia.org/wiki/Operational_transformation),
307 and can be used for collaborative editing.
308 */
309 map(other: ChangeDesc, before?: boolean): ChangeSet;
310 /**
311 Iterate over the changed ranges in the document, calling `f` for
312 each, with the range in the original document (`fromA`-`toA`)
313 and the range that replaces it in the new document
314 (`fromB`-`toB`).
315
316 When `individual` is true, adjacent changes are reported
317 separately.
318 */
319 iterChanges(f: (fromA: number, toA: number, fromB: number, toB: number, inserted: Text) => void, individual?: boolean): void;
320 /**
321 Get a [change description](https://codemirror.net/6/docs/ref/#state.ChangeDesc) for this change
322 set.
323 */
324 get desc(): ChangeDesc;
325 /**
326 Serialize this change set to a JSON-representable value.
327 */
328 toJSON(): any;
329 /**
330 Create a change set for the given changes, for a document of the
331 given length, using `lineSep` as line separator.
332 */
333 static of(changes: ChangeSpec, length: number, lineSep?: string): ChangeSet;
334 /**
335 Create an empty changeset of the given length.
336 */
337 static empty(length: number): ChangeSet;
338 /**
339 Create a changeset from its JSON representation (as produced by
340 [`toJSON`](https://codemirror.net/6/docs/ref/#state.ChangeSet.toJSON).
341 */
342 static fromJSON(json: any): ChangeSet;
343}
344
345/**
346A single selection range. When
347[`allowMultipleSelections`](https://codemirror.net/6/docs/ref/#state.EditorState^allowMultipleSelections)
348is enabled, a [selection](https://codemirror.net/6/docs/ref/#state.EditorSelection) may hold
349multiple ranges. By default, selections hold exactly one range.
350*/
351declare class SelectionRange {
352 /**
353 The lower boundary of the range.
354 */
355 readonly from: number;
356 /**
357 The upper boundary of the range.
358 */
359 readonly to: number;
360 private flags;
361 private constructor();
362 /**
363 The anchor of the range—the side that doesn't move when you
364 extend it.
365 */
366 get anchor(): number;
367 /**
368 The head of the range, which is moved when the range is
369 [extended](https://codemirror.net/6/docs/ref/#state.SelectionRange.extend).
370 */
371 get head(): number;
372 /**
373 True when `anchor` and `head` are at the same position.
374 */
375 get empty(): boolean;
376 /**
377 If this is a cursor that is explicitly associated with the
378 character on one of its sides, this returns the side. -1 means
379 the character before its position, 1 the character after, and 0
380 means no association.
381 */
382 get assoc(): -1 | 0 | 1;
383 /**
384 The bidirectional text level associated with this cursor, if
385 any.
386 */
387 get bidiLevel(): number | null;
388 /**
389 The goal column (stored vertical offset) associated with a
390 cursor. This is used to preserve the vertical position when
391 [moving](https://codemirror.net/6/docs/ref/#view.EditorView.moveVertically) across
392 lines of different length.
393 */
394 get goalColumn(): number | undefined;
395 /**
396 Map this range through a change, producing a valid range in the
397 updated document.
398 */
399 map(change: ChangeDesc, assoc?: number): SelectionRange;
400 /**
401 Extend this range to cover at least `from` to `to`.
402 */
403 extend(from: number, to?: number): SelectionRange;
404 /**
405 Compare this range to another range.
406 */
407 eq(other: SelectionRange, includeAssoc?: boolean): boolean;
408 /**
409 Return a JSON-serializable object representing the range.
410 */
411 toJSON(): any;
412 /**
413 Convert a JSON representation of a range to a `SelectionRange`
414 instance.
415 */
416 static fromJSON(json: any): SelectionRange;
417}
418/**
419An editor selection holds one or more selection ranges.
420*/
421declare class EditorSelection {
422 /**
423 The ranges in the selection, sorted by position. Ranges cannot
424 overlap (but they may touch, if they aren't empty).
425 */
426 readonly ranges: readonly SelectionRange[];
427 /**
428 The index of the _main_ range in the selection (which is
429 usually the range that was added last).
430 */
431 readonly mainIndex: number;
432 private constructor();
433 /**
434 Map a selection through a change. Used to adjust the selection
435 position for changes.
436 */
437 map(change: ChangeDesc, assoc?: number): EditorSelection;
438 /**
439 Compare this selection to another selection. By default, ranges
440 are compared only by position. When `includeAssoc` is true,
441 cursor ranges must also have the same
442 [`assoc`](https://codemirror.net/6/docs/ref/#state.SelectionRange.assoc) value.
443 */
444 eq(other: EditorSelection, includeAssoc?: boolean): boolean;
445 /**
446 Get the primary selection range. Usually, you should make sure
447 your code applies to _all_ ranges, by using methods like
448 [`changeByRange`](https://codemirror.net/6/docs/ref/#state.EditorState.changeByRange).
449 */
450 get main(): SelectionRange;
451 /**
452 Make sure the selection only has one range. Returns a selection
453 holding only the main range from this selection.
454 */
455 asSingle(): EditorSelection;
456 /**
457 Extend this selection with an extra range.
458 */
459 addRange(range: SelectionRange, main?: boolean): EditorSelection;
460 /**
461 Replace a given range with another range, and then normalize the
462 selection to merge and sort ranges if necessary.
463 */
464 replaceRange(range: SelectionRange, which?: number): EditorSelection;
465 /**
466 Convert this selection to an object that can be serialized to
467 JSON.
468 */
469 toJSON(): any;
470 /**
471 Create a selection from a JSON representation.
472 */
473 static fromJSON(json: any): EditorSelection;
474 /**
475 Create a selection holding a single range.
476 */
477 static single(anchor: number, head?: number): EditorSelection;
478 /**
479 Sort and merge the given set of ranges, creating a valid
480 selection.
481 */
482 static create(ranges: readonly SelectionRange[], mainIndex?: number): EditorSelection;
483 /**
484 Create a cursor selection range at the given position. You can
485 safely ignore the optional arguments in most situations.
486 */
487 static cursor(pos: number, assoc?: number, bidiLevel?: number, goalColumn?: number): SelectionRange;
488 /**
489 Create a selection range.
490 */
491 static range(anchor: number, head: number, goalColumn?: number, bidiLevel?: number): SelectionRange;
492}
493
494type FacetConfig<Input, Output> = {
495 /**
496 How to combine the input values into a single output value. When
497 not given, the array of input values becomes the output. This
498 function will immediately be called on creating the facet, with
499 an empty array, to compute the facet's default value when no
500 inputs are present.
501 */
502 combine?: (value: readonly Input[]) => Output;
503 /**
504 How to compare output values to determine whether the value of
505 the facet changed. Defaults to comparing by `===` or, if no
506 `combine` function was given, comparing each element of the
507 array with `===`.
508 */
509 compare?: (a: Output, b: Output) => boolean;
510 /**
511 How to compare input values to avoid recomputing the output
512 value when no inputs changed. Defaults to comparing with `===`.
513 */
514 compareInput?: (a: Input, b: Input) => boolean;
515 /**
516 Forbids dynamic inputs to this facet.
517 */
518 static?: boolean;
519 /**
520 If given, these extension(s) (or the result of calling the given
521 function with the facet) will be added to any state where this
522 facet is provided. (Note that, while a facet's default value can
523 be read from a state even if the facet wasn't present in the
524 state at all, these extensions won't be added in that
525 situation.)
526 */
527 enables?: Extension | ((self: Facet<Input, Output>) => Extension);
528};
529/**
530A facet is a labeled value that is associated with an editor
531state. It takes inputs from any number of extensions, and combines
532those into a single output value.
533
534Examples of uses of facets are the [tab
535size](https://codemirror.net/6/docs/ref/#state.EditorState^tabSize), [editor
536attributes](https://codemirror.net/6/docs/ref/#view.EditorView^editorAttributes), and [update
537listeners](https://codemirror.net/6/docs/ref/#view.EditorView^updateListener).
538
539Note that `Facet` instances can be used anywhere where
540[`FacetReader`](https://codemirror.net/6/docs/ref/#state.FacetReader) is expected.
541*/
542declare class Facet<Input, Output = readonly Input[]> implements FacetReader<Output> {
543 private isStatic;
544 private constructor();
545 /**
546 Returns a facet reader for this facet, which can be used to
547 [read](https://codemirror.net/6/docs/ref/#state.EditorState.facet) it but not to define values for it.
548 */
549 get reader(): FacetReader<Output>;
550 /**
551 Define a new facet.
552 */
553 static define<Input, Output = readonly Input[]>(config?: FacetConfig<Input, Output>): Facet<Input, Output>;
554 /**
555 Returns an extension that adds the given value to this facet.
556 */
557 of(value: Input): Extension;
558 /**
559 Create an extension that computes a value for the facet from a
560 state. You must take care to declare the parts of the state that
561 this value depends on, since your function is only called again
562 for a new state when one of those parts changed.
563
564 In cases where your value depends only on a single field, you'll
565 want to use the [`from`](https://codemirror.net/6/docs/ref/#state.Facet.from) method instead.
566 */
567 compute(deps: readonly Slot<any>[], get: (state: EditorState) => Input): Extension;
568 /**
569 Create an extension that computes zero or more values for this
570 facet from a state.
571 */
572 computeN(deps: readonly Slot<any>[], get: (state: EditorState) => readonly Input[]): Extension;
573 /**
574 Shorthand method for registering a facet source with a state
575 field as input. If the field's type corresponds to this facet's
576 input type, the getter function can be omitted. If given, it
577 will be used to retrieve the input from the field value.
578 */
579 from<T extends Input>(field: StateField<T>): Extension;
580 from<T>(field: StateField<T>, get: (value: T) => Input): Extension;
581 tag: Output;
582}
583/**
584A facet reader can be used to fetch the value of a facet, through
585[`EditorState.facet`](https://codemirror.net/6/docs/ref/#state.EditorState.facet) or as a dependency
586in [`Facet.compute`](https://codemirror.net/6/docs/ref/#state.Facet.compute), but not to define new
587values for the facet.
588*/
589type FacetReader<Output> = {
590 /**
591 Dummy tag that makes sure TypeScript doesn't consider all object
592 types as conforming to this type. Not actually present on the
593 object.
594 */
595 tag: Output;
596};
597type Slot<T> = FacetReader<T> | StateField<T> | "doc" | "selection";
598type StateFieldSpec<Value> = {
599 /**
600 Creates the initial value for the field when a state is created.
601 */
602 create: (state: EditorState) => Value;
603 /**
604 Compute a new value from the field's previous value and a
605 [transaction](https://codemirror.net/6/docs/ref/#state.Transaction).
606 */
607 update: (value: Value, transaction: Transaction) => Value;
608 /**
609 Compare two values of the field, returning `true` when they are
610 the same. This is used to avoid recomputing facets that depend
611 on the field when its value did not change. Defaults to using
612 `===`.
613 */
614 compare?: (a: Value, b: Value) => boolean;
615 /**
616 Provide extensions based on this field. The given function will
617 be called once with the initialized field. It will usually want
618 to call some facet's [`from`](https://codemirror.net/6/docs/ref/#state.Facet.from) method to
619 create facet inputs from this field, but can also return other
620 extensions that should be enabled when the field is present in a
621 configuration.
622 */
623 provide?: (field: StateField<Value>) => Extension;
624 /**
625 A function used to serialize this field's content to JSON. Only
626 necessary when this field is included in the argument to
627 [`EditorState.toJSON`](https://codemirror.net/6/docs/ref/#state.EditorState.toJSON).
628 */
629 toJSON?: (value: Value, state: EditorState) => any;
630 /**
631 A function that deserializes the JSON representation of this
632 field's content.
633 */
634 fromJSON?: (json: any, state: EditorState) => Value;
635};
636/**
637Fields can store additional information in an editor state, and
638keep it in sync with the rest of the state.
639*/
640declare class StateField<Value> {
641 private createF;
642 private updateF;
643 private compareF;
644 private constructor();
645 /**
646 Define a state field.
647 */
648 static define<Value>(config: StateFieldSpec<Value>): StateField<Value>;
649 private create;
650 /**
651 Returns an extension that enables this field and overrides the
652 way it is initialized. Can be useful when you need to provide a
653 non-default starting value for the field.
654 */
655 init(create: (state: EditorState) => Value): Extension;
656 /**
657 State field instances can be used as
658 [`Extension`](https://codemirror.net/6/docs/ref/#state.Extension) values to enable the field in a
659 given state.
660 */
661 get extension(): Extension;
662}
663/**
664Extension values can be
665[provided](https://codemirror.net/6/docs/ref/#state.EditorStateConfig.extensions) when creating a
666state to attach various kinds of configuration and behavior
667information. They can either be built-in extension-providing
668objects, such as [state fields](https://codemirror.net/6/docs/ref/#state.StateField) or [facet
669providers](https://codemirror.net/6/docs/ref/#state.Facet.of), or objects with an extension in its
670`extension` property. Extensions can be nested in arrays
671arbitrarily deep—they will be flattened when processed.
672*/
673type Extension = {
674 extension: Extension;
675} | readonly Extension[];
676/**
677By default extensions are registered in the order they are found
678in the flattened form of nested array that was provided.
679Individual extension values can be assigned a precedence to
680override this. Extensions that do not have a precedence set get
681the precedence of the nearest parent with a precedence, or
682[`default`](https://codemirror.net/6/docs/ref/#state.Prec.default) if there is no such parent. The
683final ordering of extensions is determined by first sorting by
684precedence and then by order within each precedence.
685*/
686declare const Prec: {
687 /**
688 The highest precedence level, for extensions that should end up
689 near the start of the precedence ordering.
690 */
691 highest: (ext: Extension) => Extension;
692 /**
693 A higher-than-default precedence, for extensions that should
694 come before those with default precedence.
695 */
696 high: (ext: Extension) => Extension;
697 /**
698 The default precedence, which is also used for extensions
699 without an explicit precedence.
700 */
701 default: (ext: Extension) => Extension;
702 /**
703 A lower-than-default precedence.
704 */
705 low: (ext: Extension) => Extension;
706 /**
707 The lowest precedence level. Meant for things that should end up
708 near the end of the extension order.
709 */
710 lowest: (ext: Extension) => Extension;
711};
712/**
713Extension compartments can be used to make a configuration
714dynamic. By [wrapping](https://codemirror.net/6/docs/ref/#state.Compartment.of) part of your
715configuration in a compartment, you can later
716[replace](https://codemirror.net/6/docs/ref/#state.Compartment.reconfigure) that part through a
717transaction.
718*/
719declare class Compartment {
720 /**
721 Create an instance of this compartment to add to your [state
722 configuration](https://codemirror.net/6/docs/ref/#state.EditorStateConfig.extensions).
723 */
724 of(ext: Extension): Extension;
725 /**
726 Create an [effect](https://codemirror.net/6/docs/ref/#state.TransactionSpec.effects) that
727 reconfigures this compartment.
728 */
729 reconfigure(content: Extension): StateEffect<unknown>;
730 /**
731 Get the current content of the compartment in the state, or
732 `undefined` if it isn't present.
733 */
734 get(state: EditorState): Extension | undefined;
735}
736
737/**
738Annotations are tagged values that are used to add metadata to
739transactions in an extensible way. They should be used to model
740things that effect the entire transaction (such as its [time
741stamp](https://codemirror.net/6/docs/ref/#state.Transaction^time) or information about its
742[origin](https://codemirror.net/6/docs/ref/#state.Transaction^userEvent)). For effects that happen
743_alongside_ the other changes made by the transaction, [state
744effects](https://codemirror.net/6/docs/ref/#state.StateEffect) are more appropriate.
745*/
746declare class Annotation<T> {
747 /**
748 The annotation type.
749 */
750 readonly type: AnnotationType<T>;
751 /**
752 The value of this annotation.
753 */
754 readonly value: T;
755 /**
756 Define a new type of annotation.
757 */
758 static define<T>(): AnnotationType<T>;
759 private _isAnnotation;
760}
761/**
762Marker that identifies a type of [annotation](https://codemirror.net/6/docs/ref/#state.Annotation).
763*/
764declare class AnnotationType<T> {
765 /**
766 Create an instance of this annotation.
767 */
768 of(value: T): Annotation<T>;
769}
770interface StateEffectSpec<Value> {
771 /**
772 Provides a way to map an effect like this through a position
773 mapping. When not given, the effects will simply not be mapped.
774 When the function returns `undefined`, that means the mapping
775 deletes the effect.
776 */
777 map?: (value: Value, mapping: ChangeDesc) => Value | undefined;
778}
779/**
780Representation of a type of state effect. Defined with
781[`StateEffect.define`](https://codemirror.net/6/docs/ref/#state.StateEffect^define).
782*/
783declare class StateEffectType<Value> {
784 /**
785 @internal
786 */
787 readonly map: (value: any, mapping: ChangeDesc) => any | undefined;
788 /**
789 Create a [state effect](https://codemirror.net/6/docs/ref/#state.StateEffect) instance of this
790 type.
791 */
792 of(value: Value): StateEffect<Value>;
793}
794/**
795State effects can be used to represent additional effects
796associated with a [transaction](https://codemirror.net/6/docs/ref/#state.Transaction.effects). They
797are often useful to model changes to custom [state
798fields](https://codemirror.net/6/docs/ref/#state.StateField), when those changes aren't implicit in
799document or selection changes.
800*/
801declare class StateEffect<Value> {
802 /**
803 The value of this effect.
804 */
805 readonly value: Value;
806 /**
807 Map this effect through a position mapping. Will return
808 `undefined` when that ends up deleting the effect.
809 */
810 map(mapping: ChangeDesc): StateEffect<Value> | undefined;
811 /**
812 Tells you whether this effect object is of a given
813 [type](https://codemirror.net/6/docs/ref/#state.StateEffectType).
814 */
815 is<T>(type: StateEffectType<T>): this is StateEffect<T>;
816 /**
817 Define a new effect type. The type parameter indicates the type
818 of values that his effect holds. It should be a type that
819 doesn't include `undefined`, since that is used in
820 [mapping](https://codemirror.net/6/docs/ref/#state.StateEffect.map) to indicate that an effect is
821 removed.
822 */
823 static define<Value = null>(spec?: StateEffectSpec<Value>): StateEffectType<Value>;
824 /**
825 Map an array of effects through a change set.
826 */
827 static mapEffects(effects: readonly StateEffect<any>[], mapping: ChangeDesc): readonly StateEffect<any>[];
828 /**
829 This effect can be used to reconfigure the root extensions of
830 the editor. Doing this will discard any extensions
831 [appended](https://codemirror.net/6/docs/ref/#state.StateEffect^appendConfig), but does not reset
832 the content of [reconfigured](https://codemirror.net/6/docs/ref/#state.Compartment.reconfigure)
833 compartments.
834 */
835 static reconfigure: StateEffectType<Extension>;
836 /**
837 Append extensions to the top-level configuration of the editor.
838 */
839 static appendConfig: StateEffectType<Extension>;
840}
841/**
842Describes a [transaction](https://codemirror.net/6/docs/ref/#state.Transaction) when calling the
843[`EditorState.update`](https://codemirror.net/6/docs/ref/#state.EditorState.update) method.
844*/
845interface TransactionSpec {
846 /**
847 The changes to the document made by this transaction.
848 */
849 changes?: ChangeSpec;
850 /**
851 When set, this transaction explicitly updates the selection.
852 Offsets in this selection should refer to the document as it is
853 _after_ the transaction.
854 */
855 selection?: EditorSelection | {
856 anchor: number;
857 head?: number;
858 } | undefined;
859 /**
860 Attach [state effects](https://codemirror.net/6/docs/ref/#state.StateEffect) to this transaction.
861 Again, when they contain positions and this same spec makes
862 changes, those positions should refer to positions in the
863 updated document.
864 */
865 effects?: StateEffect<any> | readonly StateEffect<any>[];
866 /**
867 Set [annotations](https://codemirror.net/6/docs/ref/#state.Annotation) for this transaction.
868 */
869 annotations?: Annotation<any> | readonly Annotation<any>[];
870 /**
871 Shorthand for `annotations:` [`Transaction.userEvent`](https://codemirror.net/6/docs/ref/#state.Transaction^userEvent)`.of(...)`.
872 */
873 userEvent?: string;
874 /**
875 When set to `true`, the transaction is marked as needing to
876 scroll the current selection into view.
877 */
878 scrollIntoView?: boolean;
879 /**
880 By default, transactions can be modified by [change
881 filters](https://codemirror.net/6/docs/ref/#state.EditorState^changeFilter) and [transaction
882 filters](https://codemirror.net/6/docs/ref/#state.EditorState^transactionFilter). You can set this
883 to `false` to disable that. This can be necessary for
884 transactions that, for example, include annotations that must be
885 kept consistent with their changes.
886 */
887 filter?: boolean;
888 /**
889 Normally, when multiple specs are combined (for example by
890 [`EditorState.update`](https://codemirror.net/6/docs/ref/#state.EditorState.update)), the
891 positions in `changes` are taken to refer to the document
892 positions in the initial document. When a spec has `sequental`
893 set to true, its positions will be taken to refer to the
894 document created by the specs before it instead.
895 */
896 sequential?: boolean;
897}
898/**
899Changes to the editor state are grouped into transactions.
900Typically, a user action creates a single transaction, which may
901contain any number of document changes, may change the selection,
902or have other effects. Create a transaction by calling
903[`EditorState.update`](https://codemirror.net/6/docs/ref/#state.EditorState.update), or immediately
904dispatch one by calling
905[`EditorView.dispatch`](https://codemirror.net/6/docs/ref/#view.EditorView.dispatch).
906*/
907declare class Transaction {
908 /**
909 The state from which the transaction starts.
910 */
911 readonly startState: EditorState;
912 /**
913 The document changes made by this transaction.
914 */
915 readonly changes: ChangeSet;
916 /**
917 The selection set by this transaction, or undefined if it
918 doesn't explicitly set a selection.
919 */
920 readonly selection: EditorSelection | undefined;
921 /**
922 The effects added to the transaction.
923 */
924 readonly effects: readonly StateEffect<any>[];
925 /**
926 Whether the selection should be scrolled into view after this
927 transaction is dispatched.
928 */
929 readonly scrollIntoView: boolean;
930 private constructor();
931 /**
932 The new document produced by the transaction. Contrary to
933 [`.state`](https://codemirror.net/6/docs/ref/#state.Transaction.state)`.doc`, accessing this won't
934 force the entire new state to be computed right away, so it is
935 recommended that [transaction
936 filters](https://codemirror.net/6/docs/ref/#state.EditorState^transactionFilter) use this getter
937 when they need to look at the new document.
938 */
939 get newDoc(): Text;
940 /**
941 The new selection produced by the transaction. If
942 [`this.selection`](https://codemirror.net/6/docs/ref/#state.Transaction.selection) is undefined,
943 this will [map](https://codemirror.net/6/docs/ref/#state.EditorSelection.map) the start state's
944 current selection through the changes made by the transaction.
945 */
946 get newSelection(): EditorSelection;
947 /**
948 The new state created by the transaction. Computed on demand
949 (but retained for subsequent access), so it is recommended not to
950 access it in [transaction
951 filters](https://codemirror.net/6/docs/ref/#state.EditorState^transactionFilter) when possible.
952 */
953 get state(): EditorState;
954 /**
955 Get the value of the given annotation type, if any.
956 */
957 annotation<T>(type: AnnotationType<T>): T | undefined;
958 /**
959 Indicates whether the transaction changed the document.
960 */
961 get docChanged(): boolean;
962 /**
963 Indicates whether this transaction reconfigures the state
964 (through a [configuration compartment](https://codemirror.net/6/docs/ref/#state.Compartment) or
965 with a top-level configuration
966 [effect](https://codemirror.net/6/docs/ref/#state.StateEffect^reconfigure).
967 */
968 get reconfigured(): boolean;
969 /**
970 Returns true if the transaction has a [user
971 event](https://codemirror.net/6/docs/ref/#state.Transaction^userEvent) annotation that is equal to
972 or more specific than `event`. For example, if the transaction
973 has `"select.pointer"` as user event, `"select"` and
974 `"select.pointer"` will match it.
975 */
976 isUserEvent(event: string): boolean;
977 /**
978 Annotation used to store transaction timestamps. Automatically
979 added to every transaction, holding `Date.now()`.
980 */
981 static time: AnnotationType<number>;
982 /**
983 Annotation used to associate a transaction with a user interface
984 event. Holds a string identifying the event, using a
985 dot-separated format to support attaching more specific
986 information. The events used by the core libraries are:
987
988 - `"input"` when content is entered
989 - `"input.type"` for typed input
990 - `"input.type.compose"` for composition
991 - `"input.paste"` for pasted input
992 - `"input.drop"` when adding content with drag-and-drop
993 - `"input.complete"` when autocompleting
994 - `"delete"` when the user deletes content
995 - `"delete.selection"` when deleting the selection
996 - `"delete.forward"` when deleting forward from the selection
997 - `"delete.backward"` when deleting backward from the selection
998 - `"delete.cut"` when cutting to the clipboard
999 - `"move"` when content is moved
1000 - `"move.drop"` when content is moved within the editor through drag-and-drop
1001 - `"select"` when explicitly changing the selection
1002 - `"select.pointer"` when selecting with a mouse or other pointing device
1003 - `"undo"` and `"redo"` for history actions
1004
1005 Use [`isUserEvent`](https://codemirror.net/6/docs/ref/#state.Transaction.isUserEvent) to check
1006 whether the annotation matches a given event.
1007 */
1008 static userEvent: AnnotationType<string>;
1009 /**
1010 Annotation indicating whether a transaction should be added to
1011 the undo history or not.
1012 */
1013 static addToHistory: AnnotationType<boolean>;
1014 /**
1015 Annotation indicating (when present and true) that a transaction
1016 represents a change made by some other actor, not the user. This
1017 is used, for example, to tag other people's changes in
1018 collaborative editing.
1019 */
1020 static remote: AnnotationType<boolean>;
1021}
1022
1023/**
1024The categories produced by a [character
1025categorizer](https://codemirror.net/6/docs/ref/#state.EditorState.charCategorizer). These are used
1026do things like selecting by word.
1027*/
1028declare enum CharCategory {
1029 /**
1030 Word characters.
1031 */
1032 Word = 0,
1033 /**
1034 Whitespace.
1035 */
1036 Space = 1,
1037 /**
1038 Anything else.
1039 */
1040 Other = 2
1041}
1042
1043/**
1044Options passed when [creating](https://codemirror.net/6/docs/ref/#state.EditorState^create) an
1045editor state.
1046*/
1047interface EditorStateConfig {
1048 /**
1049 The initial document. Defaults to an empty document. Can be
1050 provided either as a plain string (which will be split into
1051 lines according to the value of the [`lineSeparator`
1052 facet](https://codemirror.net/6/docs/ref/#state.EditorState^lineSeparator)), or an instance of
1053 the [`Text`](https://codemirror.net/6/docs/ref/#state.Text) class (which is what the state will use
1054 to represent the document).
1055 */
1056 doc?: string | Text;
1057 /**
1058 The starting selection. Defaults to a cursor at the very start
1059 of the document.
1060 */
1061 selection?: EditorSelection | {
1062 anchor: number;
1063 head?: number;
1064 };
1065 /**
1066 [Extension(s)](https://codemirror.net/6/docs/ref/#state.Extension) to associate with this state.
1067 */
1068 extensions?: Extension;
1069}
1070/**
1071The editor state class is a persistent (immutable) data structure.
1072To update a state, you [create](https://codemirror.net/6/docs/ref/#state.EditorState.update) a
1073[transaction](https://codemirror.net/6/docs/ref/#state.Transaction), which produces a _new_ state
1074instance, without modifying the original object.
1075
1076As such, _never_ mutate properties of a state directly. That'll
1077just break things.
1078*/
1079declare class EditorState {
1080 /**
1081 The current document.
1082 */
1083 readonly doc: Text;
1084 /**
1085 The current selection.
1086 */
1087 readonly selection: EditorSelection;
1088 private constructor();
1089 /**
1090 Retrieve the value of a [state field](https://codemirror.net/6/docs/ref/#state.StateField). Throws
1091 an error when the state doesn't have that field, unless you pass
1092 `false` as second parameter.
1093 */
1094 field<T>(field: StateField<T>): T;
1095 field<T>(field: StateField<T>, require: false): T | undefined;
1096 /**
1097 Create a [transaction](https://codemirror.net/6/docs/ref/#state.Transaction) that updates this
1098 state. Any number of [transaction specs](https://codemirror.net/6/docs/ref/#state.TransactionSpec)
1099 can be passed. Unless
1100 [`sequential`](https://codemirror.net/6/docs/ref/#state.TransactionSpec.sequential) is set, the
1101 [changes](https://codemirror.net/6/docs/ref/#state.TransactionSpec.changes) (if any) of each spec
1102 are assumed to start in the _current_ document (not the document
1103 produced by previous specs), and its
1104 [selection](https://codemirror.net/6/docs/ref/#state.TransactionSpec.selection) and
1105 [effects](https://codemirror.net/6/docs/ref/#state.TransactionSpec.effects) are assumed to refer
1106 to the document created by its _own_ changes. The resulting
1107 transaction contains the combined effect of all the different
1108 specs. For [selection](https://codemirror.net/6/docs/ref/#state.TransactionSpec.selection), later
1109 specs take precedence over earlier ones.
1110 */
1111 update(...specs: readonly TransactionSpec[]): Transaction;
1112 /**
1113 Create a [transaction spec](https://codemirror.net/6/docs/ref/#state.TransactionSpec) that
1114 replaces every selection range with the given content.
1115 */
1116 replaceSelection(text: string | Text): TransactionSpec;
1117 /**
1118 Create a set of changes and a new selection by running the given
1119 function for each range in the active selection. The function
1120 can return an optional set of changes (in the coordinate space
1121 of the start document), plus an updated range (in the coordinate
1122 space of the document produced by the call's own changes). This
1123 method will merge all the changes and ranges into a single
1124 changeset and selection, and return it as a [transaction
1125 spec](https://codemirror.net/6/docs/ref/#state.TransactionSpec), which can be passed to
1126 [`update`](https://codemirror.net/6/docs/ref/#state.EditorState.update).
1127 */
1128 changeByRange(f: (range: SelectionRange) => {
1129 range: SelectionRange;
1130 changes?: ChangeSpec;
1131 effects?: StateEffect<any> | readonly StateEffect<any>[];
1132 }): {
1133 changes: ChangeSet;
1134 selection: EditorSelection;
1135 effects: readonly StateEffect<any>[];
1136 };
1137 /**
1138 Create a [change set](https://codemirror.net/6/docs/ref/#state.ChangeSet) from the given change
1139 description, taking the state's document length and line
1140 separator into account.
1141 */
1142 changes(spec?: ChangeSpec): ChangeSet;
1143 /**
1144 Using the state's [line
1145 separator](https://codemirror.net/6/docs/ref/#state.EditorState^lineSeparator), create a
1146 [`Text`](https://codemirror.net/6/docs/ref/#state.Text) instance from the given string.
1147 */
1148 toText(string: string): Text;
1149 /**
1150 Return the given range of the document as a string.
1151 */
1152 sliceDoc(from?: number, to?: number): string;
1153 /**
1154 Get the value of a state [facet](https://codemirror.net/6/docs/ref/#state.Facet).
1155 */
1156 facet<Output>(facet: FacetReader<Output>): Output;
1157 /**
1158 Convert this state to a JSON-serializable object. When custom
1159 fields should be serialized, you can pass them in as an object
1160 mapping property names (in the resulting object, which should
1161 not use `doc` or `selection`) to fields.
1162 */
1163 toJSON(fields?: {
1164 [prop: string]: StateField<any>;
1165 }): any;
1166 /**
1167 Deserialize a state from its JSON representation. When custom
1168 fields should be deserialized, pass the same object you passed
1169 to [`toJSON`](https://codemirror.net/6/docs/ref/#state.EditorState.toJSON) when serializing as
1170 third argument.
1171 */
1172 static fromJSON(json: any, config?: EditorStateConfig, fields?: {
1173 [prop: string]: StateField<any>;
1174 }): EditorState;
1175 /**
1176 Create a new state. You'll usually only need this when
1177 initializing an editor—updated states are created by applying
1178 transactions.
1179 */
1180 static create(config?: EditorStateConfig): EditorState;
1181 /**
1182 A facet that, when enabled, causes the editor to allow multiple
1183 ranges to be selected. Be careful though, because by default the
1184 editor relies on the native DOM selection, which cannot handle
1185 multiple selections. An extension like
1186 [`drawSelection`](https://codemirror.net/6/docs/ref/#view.drawSelection) can be used to make
1187 secondary selections visible to the user.
1188 */
1189 static allowMultipleSelections: Facet<boolean, boolean>;
1190 /**
1191 Configures the tab size to use in this state. The first
1192 (highest-precedence) value of the facet is used. If no value is
1193 given, this defaults to 4.
1194 */
1195 static tabSize: Facet<number, number>;
1196 /**
1197 The size (in columns) of a tab in the document, determined by
1198 the [`tabSize`](https://codemirror.net/6/docs/ref/#state.EditorState^tabSize) facet.
1199 */
1200 get tabSize(): number;
1201 /**
1202 The line separator to use. By default, any of `"\n"`, `"\r\n"`
1203 and `"\r"` is treated as a separator when splitting lines, and
1204 lines are joined with `"\n"`.
1205
1206 When you configure a value here, only that precise separator
1207 will be used, allowing you to round-trip documents through the
1208 editor without normalizing line separators.
1209 */
1210 static lineSeparator: Facet<string, string | undefined>;
1211 /**
1212 Get the proper [line-break](https://codemirror.net/6/docs/ref/#state.EditorState^lineSeparator)
1213 string for this state.
1214 */
1215 get lineBreak(): string;
1216 /**
1217 This facet controls the value of the
1218 [`readOnly`](https://codemirror.net/6/docs/ref/#state.EditorState.readOnly) getter, which is
1219 consulted by commands and extensions that implement editing
1220 functionality to determine whether they should apply. It
1221 defaults to false, but when its highest-precedence value is
1222 `true`, such functionality disables itself.
1223
1224 Not to be confused with
1225 [`EditorView.editable`](https://codemirror.net/6/docs/ref/#view.EditorView^editable), which
1226 controls whether the editor's DOM is set to be editable (and
1227 thus focusable).
1228 */
1229 static readOnly: Facet<boolean, boolean>;
1230 /**
1231 Returns true when the editor is
1232 [configured](https://codemirror.net/6/docs/ref/#state.EditorState^readOnly) to be read-only.
1233 */
1234 get readOnly(): boolean;
1235 /**
1236 Registers translation phrases. The
1237 [`phrase`](https://codemirror.net/6/docs/ref/#state.EditorState.phrase) method will look through
1238 all objects registered with this facet to find translations for
1239 its argument.
1240 */
1241 static phrases: Facet<{
1242 [key: string]: string;
1243 }, readonly {
1244 [key: string]: string;
1245 }[]>;
1246 /**
1247 Look up a translation for the given phrase (via the
1248 [`phrases`](https://codemirror.net/6/docs/ref/#state.EditorState^phrases) facet), or return the
1249 original string if no translation is found.
1250
1251 If additional arguments are passed, they will be inserted in
1252 place of markers like `$1` (for the first value) and `$2`, etc.
1253 A single `$` is equivalent to `$1`, and `$$` will produce a
1254 literal dollar sign.
1255 */
1256 phrase(phrase: string, ...insert: any[]): string;
1257 /**
1258 A facet used to register [language
1259 data](https://codemirror.net/6/docs/ref/#state.EditorState.languageDataAt) providers.
1260 */
1261 static languageData: Facet<(state: EditorState, pos: number, side: 0 | 1 | -1) => readonly {
1262 [name: string]: any;
1263 }[], readonly ((state: EditorState, pos: number, side: 0 | 1 | -1) => readonly {
1264 [name: string]: any;
1265 }[])[]>;
1266 /**
1267 Find the values for a given language data field, provided by the
1268 the [`languageData`](https://codemirror.net/6/docs/ref/#state.EditorState^languageData) facet.
1269
1270 Examples of language data fields are...
1271
1272 - [`"commentTokens"`](https://codemirror.net/6/docs/ref/#commands.CommentTokens) for specifying
1273 comment syntax.
1274 - [`"autocomplete"`](https://codemirror.net/6/docs/ref/#autocomplete.autocompletion^config.override)
1275 for providing language-specific completion sources.
1276 - [`"wordChars"`](https://codemirror.net/6/docs/ref/#state.EditorState.charCategorizer) for adding
1277 characters that should be considered part of words in this
1278 language.
1279 - [`"closeBrackets"`](https://codemirror.net/6/docs/ref/#autocomplete.CloseBracketConfig) controls
1280 bracket closing behavior.
1281 */
1282 languageDataAt<T>(name: string, pos: number, side?: -1 | 0 | 1): readonly T[];
1283 /**
1284 Return a function that can categorize strings (expected to
1285 represent a single [grapheme cluster](https://codemirror.net/6/docs/ref/#state.findClusterBreak))
1286 into one of:
1287
1288 - Word (contains an alphanumeric character or a character
1289 explicitly listed in the local language's `"wordChars"`
1290 language data, which should be a string)
1291 - Space (contains only whitespace)
1292 - Other (anything else)
1293 */
1294 charCategorizer(at: number): (char: string) => CharCategory;
1295 /**
1296 Find the word at the given position, meaning the range
1297 containing all [word](https://codemirror.net/6/docs/ref/#state.CharCategory.Word) characters
1298 around it. If no word characters are adjacent to the position,
1299 this returns null.
1300 */
1301 wordAt(pos: number): SelectionRange | null;
1302 /**
1303 Facet used to register change filters, which are called for each
1304 transaction (unless explicitly
1305 [disabled](https://codemirror.net/6/docs/ref/#state.TransactionSpec.filter)), and can suppress
1306 part of the transaction's changes.
1307
1308 Such a function can return `true` to indicate that it doesn't
1309 want to do anything, `false` to completely stop the changes in
1310 the transaction, or a set of ranges in which changes should be
1311 suppressed. Such ranges are represented as an array of numbers,
1312 with each pair of two numbers indicating the start and end of a
1313 range. So for example `[10, 20, 100, 110]` suppresses changes
1314 between 10 and 20, and between 100 and 110.
1315 */
1316 static changeFilter: Facet<(tr: Transaction) => boolean | readonly number[], readonly ((tr: Transaction) => boolean | readonly number[])[]>;
1317 /**
1318 Facet used to register a hook that gets a chance to update or
1319 replace transaction specs before they are applied. This will
1320 only be applied for transactions that don't have
1321 [`filter`](https://codemirror.net/6/docs/ref/#state.TransactionSpec.filter) set to `false`. You
1322 can either return a single transaction spec (possibly the input
1323 transaction), or an array of specs (which will be combined in
1324 the same way as the arguments to
1325 [`EditorState.update`](https://codemirror.net/6/docs/ref/#state.EditorState.update)).
1326
1327 When possible, it is recommended to avoid accessing
1328 [`Transaction.state`](https://codemirror.net/6/docs/ref/#state.Transaction.state) in a filter,
1329 since it will force creation of a state that will then be
1330 discarded again, if the transaction is actually filtered.
1331
1332 (This functionality should be used with care. Indiscriminately
1333 modifying transaction is likely to break something or degrade
1334 the user experience.)
1335 */
1336 static transactionFilter: Facet<(tr: Transaction) => TransactionSpec | readonly TransactionSpec[], readonly ((tr: Transaction) => TransactionSpec | readonly TransactionSpec[])[]>;
1337 /**
1338 This is a more limited form of
1339 [`transactionFilter`](https://codemirror.net/6/docs/ref/#state.EditorState^transactionFilter),
1340 which can only add
1341 [annotations](https://codemirror.net/6/docs/ref/#state.TransactionSpec.annotations) and
1342 [effects](https://codemirror.net/6/docs/ref/#state.TransactionSpec.effects). _But_, this type
1343 of filter runs even if the transaction has disabled regular
1344 [filtering](https://codemirror.net/6/docs/ref/#state.TransactionSpec.filter), making it suitable
1345 for effects that don't need to touch the changes or selection,
1346 but do want to process every transaction.
1347
1348 Extenders run _after_ filters, when both are present.
1349 */
1350 static transactionExtender: Facet<(tr: Transaction) => Pick<TransactionSpec, "effects" | "annotations"> | null, readonly ((tr: Transaction) => Pick<TransactionSpec, "effects" | "annotations"> | null)[]>;
1351}
1352
1353/**
1354Subtype of [`Command`](https://codemirror.net/6/docs/ref/#view.Command) that doesn't require access
1355to the actual editor view. Mostly useful to define commands that
1356can be run and tested outside of a browser environment.
1357*/
1358type StateCommand = (target: {
1359 state: EditorState;
1360 dispatch: (transaction: Transaction) => void;
1361}) => boolean;
1362
1363/**
1364Utility function for combining behaviors to fill in a config
1365object from an array of provided configs. `defaults` should hold
1366default values for all optional fields in `Config`.
1367
1368The function will, by default, error
1369when a field gets two values that aren't `===`-equal, but you can
1370provide combine functions per field to do something else.
1371*/
1372declare function combineConfig<Config extends object>(configs: readonly Partial<Config>[], defaults: Partial<Config>, // Should hold only the optional properties of Config, but I haven't managed to express that
1373combine?: {
1374 [P in keyof Config]?: (first: Config[P], second: Config[P]) => Config[P];
1375}): Config;
1376
1377/**
1378Each range is associated with a value, which must inherit from
1379this class.
1380*/
1381declare abstract class RangeValue {
1382 /**
1383 Compare this value with another value. Used when comparing
1384 rangesets. The default implementation compares by identity.
1385 Unless you are only creating a fixed number of unique instances
1386 of your value type, it is a good idea to implement this
1387 properly.
1388 */
1389 eq(other: RangeValue): boolean;
1390 /**
1391 The bias value at the start of the range. Determines how the
1392 range is positioned relative to other ranges starting at this
1393 position. Defaults to 0.
1394 */
1395 startSide: number;
1396 /**
1397 The bias value at the end of the range. Defaults to 0.
1398 */
1399 endSide: number;
1400 /**
1401 The mode with which the location of the range should be mapped
1402 when its `from` and `to` are the same, to decide whether a
1403 change deletes the range. Defaults to `MapMode.TrackDel`.
1404 */
1405 mapMode: MapMode;
1406 /**
1407 Determines whether this value marks a point range. Regular
1408 ranges affect the part of the document they cover, and are
1409 meaningless when empty. Point ranges have a meaning on their
1410 own. When non-empty, a point range is treated as atomic and
1411 shadows any ranges contained in it.
1412 */
1413 point: boolean;
1414 /**
1415 Create a [range](https://codemirror.net/6/docs/ref/#state.Range) with this value.
1416 */
1417 range(from: number, to?: number): Range<this>;
1418}
1419/**
1420A range associates a value with a range of positions.
1421*/
1422declare class Range<T extends RangeValue> {
1423 /**
1424 The range's start position.
1425 */
1426 readonly from: number;
1427 /**
1428 Its end position.
1429 */
1430 readonly to: number;
1431 /**
1432 The value associated with this range.
1433 */
1434 readonly value: T;
1435 private constructor();
1436}
1437/**
1438Collection of methods used when comparing range sets.
1439*/
1440interface RangeComparator<T extends RangeValue> {
1441 /**
1442 Notifies the comparator that a range (in positions in the new
1443 document) has the given sets of values associated with it, which
1444 are different in the old (A) and new (B) sets.
1445 */
1446 compareRange(from: number, to: number, activeA: T[], activeB: T[]): void;
1447 /**
1448 Notification for a changed (or inserted, or deleted) point range.
1449 */
1450 comparePoint(from: number, to: number, pointA: T | null, pointB: T | null): void;
1451 /**
1452 Notification for a changed boundary between ranges. For example,
1453 if the same span is covered by two partial ranges before and one
1454 bigger range after, this is called at the point where the ranges
1455 used to be split.
1456 */
1457 boundChange?(pos: number): void;
1458}
1459/**
1460Methods used when iterating over the spans created by a set of
1461ranges. The entire iterated range will be covered with either
1462`span` or `point` calls.
1463*/
1464interface SpanIterator<T extends RangeValue> {
1465 /**
1466 Called for any ranges not covered by point decorations. `active`
1467 holds the values that the range is marked with (and may be
1468 empty). `openStart` indicates how many of those ranges are open
1469 (continued) at the start of the span.
1470 */
1471 span(from: number, to: number, active: readonly T[], openStart: number): void;
1472 /**
1473 Called when going over a point decoration. The active range
1474 decorations that cover the point and have a higher precedence
1475 are provided in `active`. The open count in `openStart` counts
1476 the number of those ranges that started before the point and. If
1477 the point started before the iterated range, `openStart` will be
1478 `active.length + 1` to signal this.
1479 */
1480 point(from: number, to: number, value: T, active: readonly T[], openStart: number, index: number): void;
1481}
1482/**
1483A range cursor is an object that moves to the next range every
1484time you call `next` on it. Note that, unlike ES6 iterators, these
1485start out pointing at the first element, so you should call `next`
1486only after reading the first range (if any).
1487*/
1488interface RangeCursor<T> {
1489 /**
1490 Move the iterator forward.
1491 */
1492 next(): void;
1493 /**
1494 Jump the cursor to the given position.
1495 */
1496 goto(pos: number): void;
1497 /**
1498 The next range's value. Holds `null` when the cursor has reached
1499 its end.
1500 */
1501 value: T | null;
1502 /**
1503 The next range's start position.
1504 */
1505 from: number;
1506 /**
1507 The next end position.
1508 */
1509 to: number;
1510 /**
1511 The position of the set that this range comes from in the array
1512 of sets being iterated over.
1513 */
1514 rank: number;
1515}
1516type RangeSetUpdate<T extends RangeValue> = {
1517 /**
1518 An array of ranges to add. If given, this should be sorted by
1519 `from` position and `startSide` unless
1520 [`sort`](https://codemirror.net/6/docs/ref/#state.RangeSet.update^updateSpec.sort) is given as
1521 `true`.
1522 */
1523 add?: readonly Range<T>[];
1524 /**
1525 Indicates whether the library should sort the ranges in `add`.
1526 Defaults to `false`.
1527 */
1528 sort?: boolean;
1529 /**
1530 Filter the ranges already in the set. Only those for which this
1531 function returns `true` are kept.
1532 */
1533 filter?: (from: number, to: number, value: T) => boolean;
1534 /**
1535 Can be used to limit the range on which the filter is
1536 applied. Filtering only a small range, as opposed to the entire
1537 set, can make updates cheaper.
1538 */
1539 filterFrom?: number;
1540 /**
1541 The end position to apply the filter to.
1542 */
1543 filterTo?: number;
1544};
1545/**
1546A range set stores a collection of [ranges](https://codemirror.net/6/docs/ref/#state.Range) in a
1547way that makes them efficient to [map](https://codemirror.net/6/docs/ref/#state.RangeSet.map) and
1548[update](https://codemirror.net/6/docs/ref/#state.RangeSet.update). This is an immutable data
1549structure.
1550*/
1551declare class RangeSet<T extends RangeValue> {
1552 private constructor();
1553 /**
1554 The number of ranges in the set.
1555 */
1556 get size(): number;
1557 /**
1558 Update the range set, optionally adding new ranges or filtering
1559 out existing ones.
1560
1561 (Note: The type parameter is just there as a kludge to work
1562 around TypeScript variance issues that prevented `RangeSet<X>`
1563 from being a subtype of `RangeSet<Y>` when `X` is a subtype of
1564 `Y`.)
1565 */
1566 update<U extends T>(updateSpec: RangeSetUpdate<U>): RangeSet<T>;
1567 /**
1568 Map this range set through a set of changes, return the new set.
1569 */
1570 map(changes: ChangeDesc): RangeSet<T>;
1571 /**
1572 Iterate over the ranges that touch the region `from` to `to`,
1573 calling `f` for each. There is no guarantee that the ranges will
1574 be reported in any specific order. When the callback returns
1575 `false`, iteration stops.
1576 */
1577 between(from: number, to: number, f: (from: number, to: number, value: T) => void | false): void;
1578 /**
1579 Iterate over the ranges in this set, in order, including all
1580 ranges that end at or after `from`.
1581 */
1582 iter(from?: number): RangeCursor<T>;
1583 /**
1584 Iterate over the ranges in a collection of sets, in order,
1585 starting from `from`.
1586 */
1587 static iter<T extends RangeValue>(sets: readonly RangeSet<T>[], from?: number): RangeCursor<T>;
1588 /**
1589 Iterate over two groups of sets, calling methods on `comparator`
1590 to notify it of possible differences.
1591 */
1592 static compare<T extends RangeValue>(oldSets: readonly RangeSet<T>[], newSets: readonly RangeSet<T>[],
1593 /**
1594 This indicates how the underlying data changed between these
1595 ranges, and is needed to synchronize the iteration.
1596 */
1597 textDiff: ChangeDesc, comparator: RangeComparator<T>,
1598 /**
1599 Can be used to ignore all non-point ranges, and points below
1600 the given size. When -1, all ranges are compared.
1601 */
1602 minPointSize?: number): void;
1603 /**
1604 Compare the contents of two groups of range sets, returning true
1605 if they are equivalent in the given range.
1606 */
1607 static eq<T extends RangeValue>(oldSets: readonly RangeSet<T>[], newSets: readonly RangeSet<T>[], from?: number, to?: number): boolean;
1608 /**
1609 Iterate over a group of range sets at the same time, notifying
1610 the iterator about the ranges covering every given piece of
1611 content. Returns the open count (see
1612 [`SpanIterator.span`](https://codemirror.net/6/docs/ref/#state.SpanIterator.span)) at the end
1613 of the iteration.
1614 */
1615 static spans<T extends RangeValue>(sets: readonly RangeSet<T>[], from: number, to: number, iterator: SpanIterator<T>,
1616 /**
1617 When given and greater than -1, only points of at least this
1618 size are taken into account.
1619 */
1620 minPointSize?: number): number;
1621 /**
1622 Create a range set for the given range or array of ranges. By
1623 default, this expects the ranges to be _sorted_ (by start
1624 position and, if two start at the same position,
1625 `value.startSide`). You can pass `true` as second argument to
1626 cause the method to sort them.
1627 */
1628 static of<T extends RangeValue>(ranges: readonly Range<T>[] | Range<T>, sort?: boolean): RangeSet<T>;
1629 /**
1630 Join an array of range sets into a single set.
1631 */
1632 static join<T extends RangeValue>(sets: readonly RangeSet<T>[]): RangeSet<T>;
1633 /**
1634 The empty set of ranges.
1635 */
1636 static empty: RangeSet<any>;
1637}
1638/**
1639A range set builder is a data structure that helps build up a
1640[range set](https://codemirror.net/6/docs/ref/#state.RangeSet) directly, without first allocating
1641an array of [`Range`](https://codemirror.net/6/docs/ref/#state.Range) objects.
1642*/
1643declare class RangeSetBuilder<T extends RangeValue> {
1644 private chunks;
1645 private chunkPos;
1646 private chunkStart;
1647 private last;
1648 private lastFrom;
1649 private lastTo;
1650 private from;
1651 private to;
1652 private value;
1653 private maxPoint;
1654 private setMaxPoint;
1655 private nextLayer;
1656 private finishChunk;
1657 /**
1658 Create an empty builder.
1659 */
1660 constructor();
1661 /**
1662 Add a range. Ranges should be added in sorted (by `from` and
1663 `value.startSide`) order.
1664 */
1665 add(from: number, to: number, value: T): void;
1666 /**
1667 Finish the range set. Returns the new set. The builder can't be
1668 used anymore after this has been called.
1669 */
1670 finish(): RangeSet<T>;
1671}
1672
1673/**
1674Returns a next grapheme cluster break _after_ (not equal to)
1675`pos`, if `forward` is true, or before otherwise. Returns `pos`
1676itself if no further cluster break is available in the string.
1677Moves across surrogate pairs, extending characters (when
1678`includeExtending` is true), characters joined with zero-width
1679joiners, and flag emoji.
1680*/
1681declare function findClusterBreak(str: string, pos: number, forward?: boolean, includeExtending?: boolean): number;
1682/**
1683Find the code point at the given position in a string (like the
1684[`codePointAt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/codePointAt)
1685string method).
1686*/
1687declare function codePointAt(str: string, pos: number): number;
1688/**
1689Given a Unicode codepoint, return the JavaScript string that
1690respresents it (like
1691[`String.fromCodePoint`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint)).
1692*/
1693declare function fromCodePoint(code: number): string;
1694/**
1695The amount of positions a character takes up in a JavaScript string.
1696*/
1697declare function codePointSize(code: number): 1 | 2;
1698
1699/**
1700Count the column position at the given offset into the string,
1701taking extending characters and tab size into account.
1702*/
1703declare function countColumn(string: string, tabSize: number, to?: number): number;
1704/**
1705Find the offset that corresponds to the given column position in a
1706string, taking extending characters and tab size into account. By
1707default, the string length is returned when it is too short to
1708reach the column. Pass `strict` true to make it return -1 in that
1709situation.
1710*/
1711declare function findColumn(string: string, col: number, tabSize: number, strict?: boolean): number;
1712
1713export { Annotation, AnnotationType, ChangeDesc, ChangeSet, type ChangeSpec, CharCategory, Compartment, EditorSelection, EditorState, type EditorStateConfig, type Extension, Facet, type FacetReader, Line, MapMode, Prec, Range, type RangeComparator, type RangeCursor, RangeSet, RangeSetBuilder, RangeValue, SelectionRange, type SpanIterator, type StateCommand, StateEffect, StateEffectType, StateField, Text, type TextIterator, Transaction, type TransactionSpec, codePointAt, codePointSize, combineConfig, countColumn, findClusterBreak, findColumn, fromCodePoint };