index.d.ts 61 KB

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