index.d.ts 65 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793
  1. import * as _codemirror_state from '@codemirror/state';
  2. import { RangeSet, RangeValue, Range, EditorState, Extension, Transaction, ChangeSet, EditorSelection, EditorStateConfig, TransactionSpec, SelectionRange, Line, StateEffect, Facet } from '@codemirror/state';
  3. import { StyleModule, StyleSpec } from 'style-mod';
  4. declare type Attrs = {
  5. [name: string]: string;
  6. };
  7. interface MarkDecorationSpec {
  8. /**
  9. Whether the mark covers its start and end position or not. This
  10. influences whether content inserted at those positions becomes
  11. part of the mark. Defaults to false.
  12. */
  13. inclusive?: boolean;
  14. /**
  15. Specify whether the start position of the marked range should be
  16. inclusive. Overrides `inclusive`, when both are present.
  17. */
  18. inclusiveStart?: boolean;
  19. /**
  20. Whether the end should be inclusive.
  21. */
  22. inclusiveEnd?: boolean;
  23. /**
  24. Add attributes to the DOM elements that hold the text in the
  25. marked range.
  26. */
  27. attributes?: {
  28. [key: string]: string;
  29. };
  30. /**
  31. Shorthand for `{attributes: {class: value}}`.
  32. */
  33. class?: string;
  34. /**
  35. Add a wrapping element around the text in the marked range. Note
  36. that there will not necessarily be a single element covering the
  37. entire range—other decorations with lower precedence might split
  38. this one if they partially overlap it, and line breaks always
  39. end decoration elements.
  40. */
  41. tagName?: string;
  42. /**
  43. Decoration specs allow extra properties, which can be retrieved
  44. through the decoration's [`spec`](https://codemirror.net/6/docs/ref/#view.Decoration.spec)
  45. property.
  46. */
  47. [other: string]: any;
  48. }
  49. interface WidgetDecorationSpec {
  50. /**
  51. The type of widget to draw here.
  52. */
  53. widget: WidgetType;
  54. /**
  55. Which side of the given position the widget is on. When this is
  56. positive, the widget will be drawn after the cursor if the
  57. cursor is on the same position. Otherwise, it'll be drawn before
  58. it. When multiple widgets sit at the same position, their `side`
  59. values will determine their ordering—those with a lower value
  60. come first. Defaults to 0.
  61. */
  62. side?: number;
  63. /**
  64. Determines whether this is a block widgets, which will be drawn
  65. between lines, or an inline widget (the default) which is drawn
  66. between the surrounding text.
  67. Note that block-level decorations should not have vertical
  68. margins, and if you dynamically change their height, you should
  69. make sure to call
  70. [`requestMeasure`](https://codemirror.net/6/docs/ref/#view.EditorView.requestMeasure), so that the
  71. editor can update its information about its vertical layout.
  72. */
  73. block?: boolean;
  74. /**
  75. Other properties are allowed.
  76. */
  77. [other: string]: any;
  78. }
  79. interface ReplaceDecorationSpec {
  80. /**
  81. An optional widget to drawn in the place of the replaced
  82. content.
  83. */
  84. widget?: WidgetType;
  85. /**
  86. Whether this range covers the positions on its sides. This
  87. influences whether new content becomes part of the range and
  88. whether the cursor can be drawn on its sides. Defaults to false
  89. for inline replacements, and true for block replacements.
  90. */
  91. inclusive?: boolean;
  92. /**
  93. Set inclusivity at the start.
  94. */
  95. inclusiveStart?: boolean;
  96. /**
  97. Set inclusivity at the end.
  98. */
  99. inclusiveEnd?: boolean;
  100. /**
  101. Whether this is a block-level decoration. Defaults to false.
  102. */
  103. block?: boolean;
  104. /**
  105. Other properties are allowed.
  106. */
  107. [other: string]: any;
  108. }
  109. interface LineDecorationSpec {
  110. /**
  111. DOM attributes to add to the element wrapping the line.
  112. */
  113. attributes?: {
  114. [key: string]: string;
  115. };
  116. /**
  117. Shorthand for `{attributes: {class: value}}`.
  118. */
  119. class?: string;
  120. /**
  121. Other properties are allowed.
  122. */
  123. [other: string]: any;
  124. }
  125. /**
  126. Widgets added to the content are described by subclasses of this
  127. class. Using a description object like that makes it possible to
  128. delay creating of the DOM structure for a widget until it is
  129. needed, and to avoid redrawing widgets even if the decorations
  130. that define them are recreated.
  131. */
  132. declare abstract class WidgetType {
  133. /**
  134. Build the DOM structure for this widget instance.
  135. */
  136. abstract toDOM(view: EditorView): HTMLElement;
  137. /**
  138. Compare this instance to another instance of the same type.
  139. (TypeScript can't express this, but only instances of the same
  140. specific class will be passed to this method.) This is used to
  141. avoid redrawing widgets when they are replaced by a new
  142. decoration of the same type. The default implementation just
  143. returns `false`, which will cause new instances of the widget to
  144. always be redrawn.
  145. */
  146. eq(widget: WidgetType): boolean;
  147. /**
  148. Update a DOM element created by a widget of the same type (but
  149. different, non-`eq` content) to reflect this widget. May return
  150. true to indicate that it could update, false to indicate it
  151. couldn't (in which case the widget will be redrawn). The default
  152. implementation just returns false.
  153. */
  154. updateDOM(dom: HTMLElement): boolean;
  155. /**
  156. The estimated height this widget will have, to be used when
  157. estimating the height of content that hasn't been drawn. May
  158. return -1 to indicate you don't know. The default implementation
  159. returns -1.
  160. */
  161. get estimatedHeight(): number;
  162. /**
  163. Can be used to configure which kinds of events inside the widget
  164. should be ignored by the editor. The default is to ignore all
  165. events.
  166. */
  167. ignoreEvent(event: Event): boolean;
  168. /**
  169. This is called when the an instance of the widget is removed
  170. from the editor view.
  171. */
  172. destroy(dom: HTMLElement): void;
  173. }
  174. /**
  175. A decoration set represents a collection of decorated ranges,
  176. organized for efficient access and mapping. See
  177. [`RangeSet`](https://codemirror.net/6/docs/ref/#state.RangeSet) for its methods.
  178. */
  179. declare type DecorationSet = RangeSet<Decoration>;
  180. /**
  181. The different types of blocks that can occur in an editor view.
  182. */
  183. declare enum BlockType {
  184. /**
  185. A line of text.
  186. */
  187. Text = 0,
  188. /**
  189. A block widget associated with the position after it.
  190. */
  191. WidgetBefore = 1,
  192. /**
  193. A block widget associated with the position before it.
  194. */
  195. WidgetAfter = 2,
  196. /**
  197. A block widget [replacing](https://codemirror.net/6/docs/ref/#view.Decoration^replace) a range of content.
  198. */
  199. WidgetRange = 3
  200. }
  201. /**
  202. A decoration provides information on how to draw or style a piece
  203. of content. You'll usually use it wrapped in a
  204. [`Range`](https://codemirror.net/6/docs/ref/#state.Range), which adds a start and end position.
  205. @nonabstract
  206. */
  207. declare abstract class Decoration extends RangeValue {
  208. /**
  209. The config object used to create this decoration. You can
  210. include additional properties in there to store metadata about
  211. your decoration.
  212. */
  213. readonly spec: any;
  214. protected constructor(
  215. /**
  216. @internal
  217. */
  218. startSide: number,
  219. /**
  220. @internal
  221. */
  222. endSide: number,
  223. /**
  224. @internal
  225. */
  226. widget: WidgetType | null,
  227. /**
  228. The config object used to create this decoration. You can
  229. include additional properties in there to store metadata about
  230. your decoration.
  231. */
  232. spec: any);
  233. abstract eq(other: Decoration): boolean;
  234. /**
  235. Create a mark decoration, which influences the styling of the
  236. content in its range. Nested mark decorations will cause nested
  237. DOM elements to be created. Nesting order is determined by
  238. precedence of the [facet](https://codemirror.net/6/docs/ref/#view.EditorView^decorations), with
  239. the higher-precedence decorations creating the inner DOM nodes.
  240. Such elements are split on line boundaries and on the boundaries
  241. of lower-precedence decorations.
  242. */
  243. static mark(spec: MarkDecorationSpec): Decoration;
  244. /**
  245. Create a widget decoration, which displays a DOM element at the
  246. given position.
  247. */
  248. static widget(spec: WidgetDecorationSpec): Decoration;
  249. /**
  250. Create a replace decoration which replaces the given range with
  251. a widget, or simply hides it.
  252. */
  253. static replace(spec: ReplaceDecorationSpec): Decoration;
  254. /**
  255. Create a line decoration, which can add DOM attributes to the
  256. line starting at the given position.
  257. */
  258. static line(spec: LineDecorationSpec): Decoration;
  259. /**
  260. Build a [`DecorationSet`](https://codemirror.net/6/docs/ref/#view.DecorationSet) from the given
  261. decorated range or ranges. If the ranges aren't already sorted,
  262. pass `true` for `sort` to make the library sort them for you.
  263. */
  264. static set(of: Range<Decoration> | readonly Range<Decoration>[], sort?: boolean): DecorationSet;
  265. /**
  266. The empty set of decorations.
  267. */
  268. static none: DecorationSet;
  269. }
  270. /**
  271. Basic rectangle type.
  272. */
  273. interface Rect {
  274. readonly left: number;
  275. readonly right: number;
  276. readonly top: number;
  277. readonly bottom: number;
  278. }
  279. declare type ScrollStrategy = "nearest" | "start" | "end" | "center";
  280. /**
  281. Command functions are used in key bindings and other types of user
  282. actions. Given an editor view, they check whether their effect can
  283. apply to the editor, and if it can, perform it as a side effect
  284. (which usually means [dispatching](https://codemirror.net/6/docs/ref/#view.EditorView.dispatch) a
  285. transaction) and return `true`.
  286. */
  287. declare type Command = (target: EditorView) => boolean;
  288. /**
  289. Log or report an unhandled exception in client code. Should
  290. probably only be used by extension code that allows client code to
  291. provide functions, and calls those functions in a context where an
  292. exception can't be propagated to calling code in a reasonable way
  293. (for example when in an event handler).
  294. Either calls a handler registered with
  295. [`EditorView.exceptionSink`](https://codemirror.net/6/docs/ref/#view.EditorView^exceptionSink),
  296. `window.onerror`, if defined, or `console.error` (in which case
  297. it'll pass `context`, when given, as first argument).
  298. */
  299. declare function logException(state: EditorState, exception: any, context?: string): void;
  300. /**
  301. This is the interface plugin objects conform to.
  302. */
  303. interface PluginValue extends Object {
  304. /**
  305. Notifies the plugin of an update that happened in the view. This
  306. is called _before_ the view updates its own DOM. It is
  307. responsible for updating the plugin's internal state (including
  308. any state that may be read by plugin fields) and _writing_ to
  309. the DOM for the changes in the update. To avoid unnecessary
  310. layout recomputations, it should _not_ read the DOM layout—use
  311. [`requestMeasure`](https://codemirror.net/6/docs/ref/#view.EditorView.requestMeasure) to schedule
  312. your code in a DOM reading phase if you need to.
  313. */
  314. update?(update: ViewUpdate): void;
  315. /**
  316. Called when the plugin is no longer going to be used. Should
  317. revert any changes the plugin made to the DOM.
  318. */
  319. destroy?(): void;
  320. }
  321. /**
  322. Provides additional information when defining a [view
  323. plugin](https://codemirror.net/6/docs/ref/#view.ViewPlugin).
  324. */
  325. interface PluginSpec<V extends PluginValue> {
  326. /**
  327. Register the given [event
  328. handlers](https://codemirror.net/6/docs/ref/#view.EditorView^domEventHandlers) for the plugin.
  329. When called, these will have their `this` bound to the plugin
  330. value.
  331. */
  332. eventHandlers?: DOMEventHandlers<V>;
  333. /**
  334. Specify that the plugin provides additional extensions when
  335. added to an editor configuration.
  336. */
  337. provide?: (plugin: ViewPlugin<V>) => Extension;
  338. /**
  339. Allow the plugin to provide decorations. When given, this should
  340. be a function that take the plugin value and return a
  341. [decoration set](https://codemirror.net/6/docs/ref/#view.DecorationSet). See also the caveat about
  342. [layout-changing decorations](https://codemirror.net/6/docs/ref/#view.EditorView^decorations) that
  343. depend on the view.
  344. */
  345. decorations?: (value: V) => DecorationSet;
  346. }
  347. /**
  348. View plugins associate stateful values with a view. They can
  349. influence the way the content is drawn, and are notified of things
  350. that happen in the view.
  351. */
  352. declare class ViewPlugin<V extends PluginValue> {
  353. /**
  354. Instances of this class act as extensions.
  355. */
  356. extension: Extension;
  357. private constructor();
  358. /**
  359. Define a plugin from a constructor function that creates the
  360. plugin's value, given an editor view.
  361. */
  362. static define<V extends PluginValue>(create: (view: EditorView) => V, spec?: PluginSpec<V>): ViewPlugin<V>;
  363. /**
  364. Create a plugin for a class whose constructor takes a single
  365. editor view as argument.
  366. */
  367. static fromClass<V extends PluginValue>(cls: {
  368. new (view: EditorView): V;
  369. }, spec?: PluginSpec<V>): ViewPlugin<V>;
  370. }
  371. interface MeasureRequest<T> {
  372. /**
  373. Called in a DOM read phase to gather information that requires
  374. DOM layout. Should _not_ mutate the document.
  375. */
  376. read(view: EditorView): T;
  377. /**
  378. Called in a DOM write phase to update the document. Should _not_
  379. do anything that triggers DOM layout.
  380. */
  381. write?(measure: T, view: EditorView): void;
  382. /**
  383. When multiple requests with the same key are scheduled, only the
  384. last one will actually be ran.
  385. */
  386. key?: any;
  387. }
  388. declare type AttrSource = Attrs | ((view: EditorView) => Attrs | null);
  389. /**
  390. View [plugins](https://codemirror.net/6/docs/ref/#view.ViewPlugin) are given instances of this
  391. class, which describe what happened, whenever the view is updated.
  392. */
  393. declare class ViewUpdate {
  394. /**
  395. The editor view that the update is associated with.
  396. */
  397. readonly view: EditorView;
  398. /**
  399. The new editor state.
  400. */
  401. readonly state: EditorState;
  402. /**
  403. The transactions involved in the update. May be empty.
  404. */
  405. readonly transactions: readonly Transaction[];
  406. /**
  407. The changes made to the document by this update.
  408. */
  409. readonly changes: ChangeSet;
  410. /**
  411. The previous editor state.
  412. */
  413. readonly startState: EditorState;
  414. private constructor();
  415. /**
  416. Tells you whether the [viewport](https://codemirror.net/6/docs/ref/#view.EditorView.viewport) or
  417. [visible ranges](https://codemirror.net/6/docs/ref/#view.EditorView.visibleRanges) changed in this
  418. update.
  419. */
  420. get viewportChanged(): boolean;
  421. /**
  422. Indicates whether the height of a block element in the editor
  423. changed in this update.
  424. */
  425. get heightChanged(): boolean;
  426. /**
  427. Returns true when the document was modified or the size of the
  428. editor, or elements within the editor, changed.
  429. */
  430. get geometryChanged(): boolean;
  431. /**
  432. True when this update indicates a focus change.
  433. */
  434. get focusChanged(): boolean;
  435. /**
  436. Whether the document changed in this update.
  437. */
  438. get docChanged(): boolean;
  439. /**
  440. Whether the selection was explicitly set in this update.
  441. */
  442. get selectionSet(): boolean;
  443. }
  444. /**
  445. Interface that objects registered with
  446. [`EditorView.mouseSelectionStyle`](https://codemirror.net/6/docs/ref/#view.EditorView^mouseSelectionStyle)
  447. must conform to.
  448. */
  449. interface MouseSelectionStyle {
  450. /**
  451. Return a new selection for the mouse gesture that starts with
  452. the event that was originally given to the constructor, and ends
  453. with the event passed here. In case of a plain click, those may
  454. both be the `mousedown` event, in case of a drag gesture, the
  455. latest `mousemove` event will be passed.
  456. When `extend` is true, that means the new selection should, if
  457. possible, extend the start selection. If `multiple` is true, the
  458. new selection should be added to the original selection.
  459. */
  460. get: (curEvent: MouseEvent, extend: boolean, multiple: boolean) => EditorSelection;
  461. /**
  462. Called when the view is updated while the gesture is in
  463. progress. When the document changes, it may be necessary to map
  464. some data (like the original selection or start position)
  465. through the changes.
  466. This may return `true` to indicate that the `get` method should
  467. get queried again after the update, because something in the
  468. update could change its result. Be wary of infinite loops when
  469. using this (where `get` returns a new selection, which will
  470. trigger `update`, which schedules another `get` in response).
  471. */
  472. update: (update: ViewUpdate) => boolean | void;
  473. }
  474. declare type MakeSelectionStyle = (view: EditorView, event: MouseEvent) => MouseSelectionStyle | null;
  475. /**
  476. Record used to represent information about a block-level element
  477. in the editor view.
  478. */
  479. declare class BlockInfo {
  480. /**
  481. The start of the element in the document.
  482. */
  483. readonly from: number;
  484. /**
  485. The length of the element.
  486. */
  487. readonly length: number;
  488. /**
  489. The top position of the element (relative to the top of the
  490. document).
  491. */
  492. readonly top: number;
  493. /**
  494. Its height.
  495. */
  496. readonly height: number;
  497. /**
  498. The type of element this is. When querying lines, this may be
  499. an array of all the blocks that make up the line.
  500. */
  501. readonly type: BlockType | readonly BlockInfo[];
  502. /**
  503. The end of the element as a document position.
  504. */
  505. get to(): number;
  506. /**
  507. The bottom position of the element.
  508. */
  509. get bottom(): number;
  510. }
  511. /**
  512. Used to indicate [text direction](https://codemirror.net/6/docs/ref/#view.EditorView.textDirection).
  513. */
  514. declare enum Direction {
  515. /**
  516. Left-to-right.
  517. */
  518. LTR = 0,
  519. /**
  520. Right-to-left.
  521. */
  522. RTL = 1
  523. }
  524. /**
  525. Represents a contiguous range of text that has a single direction
  526. (as in left-to-right or right-to-left).
  527. */
  528. declare class BidiSpan {
  529. /**
  530. The start of the span (relative to the start of the line).
  531. */
  532. readonly from: number;
  533. /**
  534. The end of the span.
  535. */
  536. readonly to: number;
  537. /**
  538. The ["bidi
  539. level"](https://unicode.org/reports/tr9/#Basic_Display_Algorithm)
  540. of the span (in this context, 0 means
  541. left-to-right, 1 means right-to-left, 2 means left-to-right
  542. number inside right-to-left text).
  543. */
  544. readonly level: number;
  545. /**
  546. The direction of this span.
  547. */
  548. get dir(): Direction;
  549. }
  550. /**
  551. The type of object given to the [`EditorView`](https://codemirror.net/6/docs/ref/#view.EditorView)
  552. constructor.
  553. */
  554. interface EditorViewConfig extends EditorStateConfig {
  555. /**
  556. The view's initial state. If not given, a new state is created
  557. by passing this configuration object to
  558. [`EditorState.create`](https://codemirror.net/6/docs/ref/#state.EditorState^create), using its
  559. `doc`, `selection`, and `extensions` field (if provided).
  560. */
  561. state?: EditorState;
  562. /**
  563. When given, the editor is immediately appended to the given
  564. element on creation. (Otherwise, you'll have to place the view's
  565. [`dom`](https://codemirror.net/6/docs/ref/#view.EditorView.dom) element in the document yourself.)
  566. */
  567. parent?: Element | DocumentFragment;
  568. /**
  569. If the view is going to be mounted in a shadow root or document
  570. other than the one held by the global variable `document` (the
  571. default), you should pass it here. If you provide `parent`, but
  572. not this option, the editor will automatically look up a root
  573. from the parent.
  574. */
  575. root?: Document | ShadowRoot;
  576. /**
  577. Override the transaction [dispatch
  578. function](https://codemirror.net/6/docs/ref/#view.EditorView.dispatch) for this editor view, which
  579. is the way updates get routed to the view. Your implementation,
  580. if provided, should probably call the view's [`update`
  581. method](https://codemirror.net/6/docs/ref/#view.EditorView.update).
  582. */
  583. dispatch?: (tr: Transaction) => void;
  584. }
  585. /**
  586. An editor view represents the editor's user interface. It holds
  587. the editable DOM surface, and possibly other elements such as the
  588. line number gutter. It handles events and dispatches state
  589. transactions for editing actions.
  590. */
  591. declare class EditorView {
  592. /**
  593. The current editor state.
  594. */
  595. get state(): EditorState;
  596. /**
  597. To be able to display large documents without consuming too much
  598. memory or overloading the browser, CodeMirror only draws the
  599. code that is visible (plus a margin around it) to the DOM. This
  600. property tells you the extent of the current drawn viewport, in
  601. document positions.
  602. */
  603. get viewport(): {
  604. from: number;
  605. to: number;
  606. };
  607. /**
  608. When there are, for example, large collapsed ranges in the
  609. viewport, its size can be a lot bigger than the actual visible
  610. content. Thus, if you are doing something like styling the
  611. content in the viewport, it is preferable to only do so for
  612. these ranges, which are the subset of the viewport that is
  613. actually drawn.
  614. */
  615. get visibleRanges(): readonly {
  616. from: number;
  617. to: number;
  618. }[];
  619. /**
  620. Returns false when the editor is entirely scrolled out of view
  621. or otherwise hidden.
  622. */
  623. get inView(): boolean;
  624. /**
  625. Indicates whether the user is currently composing text via
  626. [IME](https://en.wikipedia.org/wiki/Input_method), and at least
  627. one change has been made in the current composition.
  628. */
  629. get composing(): boolean;
  630. /**
  631. Indicates whether the user is currently in composing state. Note
  632. that on some platforms, like Android, this will be the case a
  633. lot, since just putting the cursor on a word starts a
  634. composition there.
  635. */
  636. get compositionStarted(): boolean;
  637. private _dispatch;
  638. /**
  639. The document or shadow root that the view lives in.
  640. */
  641. readonly root: DocumentOrShadowRoot;
  642. /**
  643. The DOM element that wraps the entire editor view.
  644. */
  645. readonly dom: HTMLElement;
  646. /**
  647. The DOM element that can be styled to scroll. (Note that it may
  648. not have been, so you can't assume this is scrollable.)
  649. */
  650. readonly scrollDOM: HTMLElement;
  651. /**
  652. The editable DOM element holding the editor content. You should
  653. not, usually, interact with this content directly though the
  654. DOM, since the editor will immediately undo most of the changes
  655. you make. Instead, [dispatch](https://codemirror.net/6/docs/ref/#view.EditorView.dispatch)
  656. [transactions](https://codemirror.net/6/docs/ref/#state.Transaction) to modify content, and
  657. [decorations](https://codemirror.net/6/docs/ref/#view.Decoration) to style it.
  658. */
  659. readonly contentDOM: HTMLElement;
  660. private announceDOM;
  661. private plugins;
  662. private pluginMap;
  663. private editorAttrs;
  664. private contentAttrs;
  665. private styleModules;
  666. private bidiCache;
  667. private destroyed;
  668. /**
  669. Construct a new view. You'll want to either provide a `parent`
  670. option, or put `view.dom` into your document after creating a
  671. view, so that the user can see the editor.
  672. */
  673. constructor(config?: EditorViewConfig);
  674. /**
  675. All regular editor state updates should go through this. It
  676. takes a transaction or transaction spec and updates the view to
  677. show the new state produced by that transaction. Its
  678. implementation can be overridden with an
  679. [option](https://codemirror.net/6/docs/ref/#view.EditorView.constructor^config.dispatch). This
  680. function is bound to the view instance, so it does not have to
  681. be called as a method.
  682. */
  683. dispatch(tr: Transaction): void;
  684. dispatch(...specs: TransactionSpec[]): void;
  685. /**
  686. Update the view for the given array of transactions. This will
  687. update the visible document and selection to match the state
  688. produced by the transactions, and notify view plugins of the
  689. change. You should usually call
  690. [`dispatch`](https://codemirror.net/6/docs/ref/#view.EditorView.dispatch) instead, which uses this
  691. as a primitive.
  692. */
  693. update(transactions: readonly Transaction[]): void;
  694. /**
  695. Reset the view to the given state. (This will cause the entire
  696. document to be redrawn and all view plugins to be reinitialized,
  697. so you should probably only use it when the new state isn't
  698. derived from the old state. Otherwise, use
  699. [`dispatch`](https://codemirror.net/6/docs/ref/#view.EditorView.dispatch) instead.)
  700. */
  701. setState(newState: EditorState): void;
  702. private updatePlugins;
  703. /**
  704. Get the CSS classes for the currently active editor themes.
  705. */
  706. get themeClasses(): string;
  707. private updateAttrs;
  708. private showAnnouncements;
  709. private mountStyles;
  710. private readMeasured;
  711. /**
  712. Schedule a layout measurement, optionally providing callbacks to
  713. do custom DOM measuring followed by a DOM write phase. Using
  714. this is preferable reading DOM layout directly from, for
  715. example, an event handler, because it'll make sure measuring and
  716. drawing done by other components is synchronized, avoiding
  717. unnecessary DOM layout computations.
  718. */
  719. requestMeasure<T>(request?: MeasureRequest<T>): void;
  720. /**
  721. Get the value of a specific plugin, if present. Note that
  722. plugins that crash can be dropped from a view, so even when you
  723. know you registered a given plugin, it is recommended to check
  724. the return value of this method.
  725. */
  726. plugin<T>(plugin: ViewPlugin<T>): T | null;
  727. /**
  728. The top position of the document, in screen coordinates. This
  729. may be negative when the editor is scrolled down. Points
  730. directly to the top of the first line, not above the padding.
  731. */
  732. get documentTop(): number;
  733. /**
  734. Reports the padding above and below the document.
  735. */
  736. get documentPadding(): {
  737. top: number;
  738. bottom: number;
  739. };
  740. /**
  741. Find the text line or block widget at the given vertical
  742. position (which is interpreted as relative to the [top of the
  743. document](https://codemirror.net/6/docs/ref/#view.EditorView.documentTop)
  744. */
  745. elementAtHeight(height: number): BlockInfo;
  746. /**
  747. Find the line block (see
  748. [`lineBlockAt`](https://codemirror.net/6/docs/ref/#view.EditorView.lineBlockAt) at the given
  749. height.
  750. */
  751. lineBlockAtHeight(height: number): BlockInfo;
  752. /**
  753. Get the extent and vertical position of all [line
  754. blocks](https://codemirror.net/6/docs/ref/#view.EditorView.lineBlockAt) in the viewport. Positions
  755. are relative to the [top of the
  756. document](https://codemirror.net/6/docs/ref/#view.EditorView.documentTop);
  757. */
  758. get viewportLineBlocks(): BlockInfo[];
  759. /**
  760. Find the line block around the given document position. A line
  761. block is a range delimited on both sides by either a
  762. non-[hidden](https://codemirror.net/6/docs/ref/#view.Decoration^replace) line breaks, or the
  763. start/end of the document. It will usually just hold a line of
  764. text, but may be broken into multiple textblocks by block
  765. widgets.
  766. */
  767. lineBlockAt(pos: number): BlockInfo;
  768. /**
  769. The editor's total content height.
  770. */
  771. get contentHeight(): number;
  772. /**
  773. Move a cursor position by [grapheme
  774. cluster](https://codemirror.net/6/docs/ref/#state.findClusterBreak). `forward` determines whether
  775. the motion is away from the line start, or towards it. In
  776. bidirectional text, the line is traversed in visual order, using
  777. the editor's [text direction](https://codemirror.net/6/docs/ref/#view.EditorView.textDirection).
  778. When the start position was the last one on the line, the
  779. returned position will be across the line break. If there is no
  780. further line, the original position is returned.
  781. By default, this method moves over a single cluster. The
  782. optional `by` argument can be used to move across more. It will
  783. be called with the first cluster as argument, and should return
  784. a predicate that determines, for each subsequent cluster,
  785. whether it should also be moved over.
  786. */
  787. moveByChar(start: SelectionRange, forward: boolean, by?: (initial: string) => (next: string) => boolean): SelectionRange;
  788. /**
  789. Move a cursor position across the next group of either
  790. [letters](https://codemirror.net/6/docs/ref/#state.EditorState.charCategorizer) or non-letter
  791. non-whitespace characters.
  792. */
  793. moveByGroup(start: SelectionRange, forward: boolean): SelectionRange;
  794. /**
  795. Move to the next line boundary in the given direction. If
  796. `includeWrap` is true, line wrapping is on, and there is a
  797. further wrap point on the current line, the wrap point will be
  798. returned. Otherwise this function will return the start or end
  799. of the line.
  800. */
  801. moveToLineBoundary(start: SelectionRange, forward: boolean, includeWrap?: boolean): SelectionRange;
  802. /**
  803. Move a cursor position vertically. When `distance` isn't given,
  804. it defaults to moving to the next line (including wrapped
  805. lines). Otherwise, `distance` should provide a positive distance
  806. in pixels.
  807. When `start` has a
  808. [`goalColumn`](https://codemirror.net/6/docs/ref/#state.SelectionRange.goalColumn), the vertical
  809. motion will use that as a target horizontal position. Otherwise,
  810. the cursor's own horizontal position is used. The returned
  811. cursor will have its goal column set to whichever column was
  812. used.
  813. */
  814. moveVertically(start: SelectionRange, forward: boolean, distance?: number): SelectionRange;
  815. /**
  816. Find the DOM parent node and offset (child offset if `node` is
  817. an element, character offset when it is a text node) at the
  818. given document position.
  819. Note that for positions that aren't currently in
  820. `visibleRanges`, the resulting DOM position isn't necessarily
  821. meaningful (it may just point before or after a placeholder
  822. element).
  823. */
  824. domAtPos(pos: number): {
  825. node: Node;
  826. offset: number;
  827. };
  828. /**
  829. Find the document position at the given DOM node. Can be useful
  830. for associating positions with DOM events. Will raise an error
  831. when `node` isn't part of the editor content.
  832. */
  833. posAtDOM(node: Node, offset?: number): number;
  834. /**
  835. Get the document position at the given screen coordinates. For
  836. positions not covered by the visible viewport's DOM structure,
  837. this will return null, unless `false` is passed as second
  838. argument, in which case it'll return an estimated position that
  839. would be near the coordinates if it were rendered.
  840. */
  841. posAtCoords(coords: {
  842. x: number;
  843. y: number;
  844. }, precise: false): number;
  845. posAtCoords(coords: {
  846. x: number;
  847. y: number;
  848. }): number | null;
  849. /**
  850. Get the screen coordinates at the given document position.
  851. `side` determines whether the coordinates are based on the
  852. element before (-1) or after (1) the position (if no element is
  853. available on the given side, the method will transparently use
  854. another strategy to get reasonable coordinates).
  855. */
  856. coordsAtPos(pos: number, side?: -1 | 1): Rect | null;
  857. /**
  858. The default width of a character in the editor. May not
  859. accurately reflect the width of all characters (given variable
  860. width fonts or styling of invididual ranges).
  861. */
  862. get defaultCharacterWidth(): number;
  863. /**
  864. The default height of a line in the editor. May not be accurate
  865. for all lines.
  866. */
  867. get defaultLineHeight(): number;
  868. /**
  869. The text direction
  870. ([`direction`](https://developer.mozilla.org/en-US/docs/Web/CSS/direction)
  871. CSS property) of the editor's content element.
  872. */
  873. get textDirection(): Direction;
  874. /**
  875. Find the text direction of the block at the given position, as
  876. assigned by CSS. If
  877. [`perLineTextDirection`](https://codemirror.net/6/docs/ref/#view.EditorView^perLineTextDirection)
  878. isn't enabled, or the given position is outside of the viewport,
  879. this will always return the same as
  880. [`textDirection`](https://codemirror.net/6/docs/ref/#view.EditorView.textDirection). Note that
  881. this may trigger a DOM layout.
  882. */
  883. textDirectionAt(pos: number): Direction;
  884. /**
  885. Whether this editor [wraps lines](https://codemirror.net/6/docs/ref/#view.EditorView.lineWrapping)
  886. (as determined by the
  887. [`white-space`](https://developer.mozilla.org/en-US/docs/Web/CSS/white-space)
  888. CSS property of its content element).
  889. */
  890. get lineWrapping(): boolean;
  891. /**
  892. Returns the bidirectional text structure of the given line
  893. (which should be in the current document) as an array of span
  894. objects. The order of these spans matches the [text
  895. direction](https://codemirror.net/6/docs/ref/#view.EditorView.textDirection)—if that is
  896. left-to-right, the leftmost spans come first, otherwise the
  897. rightmost spans come first.
  898. */
  899. bidiSpans(line: Line): readonly BidiSpan[];
  900. /**
  901. Check whether the editor has focus.
  902. */
  903. get hasFocus(): boolean;
  904. /**
  905. Put focus on the editor.
  906. */
  907. focus(): void;
  908. /**
  909. Clean up this editor view, removing its element from the
  910. document, unregistering event handlers, and notifying
  911. plugins. The view instance can no longer be used after
  912. calling this.
  913. */
  914. destroy(): void;
  915. /**
  916. Returns an effect that can be
  917. [added](https://codemirror.net/6/docs/ref/#state.TransactionSpec.effects) to a transaction to
  918. cause it to scroll the given position or range into view.
  919. */
  920. static scrollIntoView(pos: number | SelectionRange, options?: {
  921. /**
  922. By default (`"nearest"`) the position will be vertically
  923. scrolled only the minimal amount required to move the given
  924. position into view. You can set this to `"start"` to move it
  925. to the top of the view, `"end"` to move it to the bottom, or
  926. `"center"` to move it to the center.
  927. */
  928. y?: ScrollStrategy;
  929. /**
  930. Effect similar to
  931. [`y`](https://codemirror.net/6/docs/ref/#view.EditorView^scrollIntoView^options.y), but for the
  932. horizontal scroll position.
  933. */
  934. x?: ScrollStrategy;
  935. /**
  936. Extra vertical distance to add when moving something into
  937. view. Not used with the `"center"` strategy. Defaults to 5.
  938. */
  939. yMargin?: number;
  940. /**
  941. Extra horizontal distance to add. Not used with the `"center"`
  942. strategy. Defaults to 5.
  943. */
  944. xMargin?: number;
  945. }): StateEffect<unknown>;
  946. /**
  947. Facet to add a [style
  948. module](https://github.com/marijnh/style-mod#documentation) to
  949. an editor view. The view will ensure that the module is
  950. mounted in its [document
  951. root](https://codemirror.net/6/docs/ref/#view.EditorView.constructor^config.root).
  952. */
  953. static styleModule: Facet<StyleModule, readonly StyleModule[]>;
  954. /**
  955. Returns an extension that can be used to add DOM event handlers.
  956. The value should be an object mapping event names to handler
  957. functions. For any given event, such functions are ordered by
  958. extension precedence, and the first handler to return true will
  959. be assumed to have handled that event, and no other handlers or
  960. built-in behavior will be activated for it. These are registered
  961. on the [content element](https://codemirror.net/6/docs/ref/#view.EditorView.contentDOM), except
  962. for `scroll` handlers, which will be called any time the
  963. editor's [scroll element](https://codemirror.net/6/docs/ref/#view.EditorView.scrollDOM) or one of
  964. its parent nodes is scrolled.
  965. */
  966. static domEventHandlers(handlers: DOMEventHandlers<any>): Extension;
  967. /**
  968. An input handler can override the way changes to the editable
  969. DOM content are handled. Handlers are passed the document
  970. positions between which the change was found, and the new
  971. content. When one returns true, no further input handlers are
  972. called and the default behavior is prevented.
  973. */
  974. static inputHandler: Facet<(view: EditorView, from: number, to: number, text: string) => boolean, readonly ((view: EditorView, from: number, to: number, text: string) => boolean)[]>;
  975. /**
  976. By default, the editor assumes all its content has the same
  977. [text direction](https://codemirror.net/6/docs/ref/#view.Direction). Configure this with a `true`
  978. value to make it read the text direction of every (rendered)
  979. line separately.
  980. */
  981. static perLineTextDirection: Facet<boolean, boolean>;
  982. /**
  983. Allows you to provide a function that should be called when the
  984. library catches an exception from an extension (mostly from view
  985. plugins, but may be used by other extensions to route exceptions
  986. from user-code-provided callbacks). This is mostly useful for
  987. debugging and logging. See [`logException`](https://codemirror.net/6/docs/ref/#view.logException).
  988. */
  989. static exceptionSink: Facet<(exception: any) => void, readonly ((exception: any) => void)[]>;
  990. /**
  991. A facet that can be used to register a function to be called
  992. every time the view updates.
  993. */
  994. static updateListener: Facet<(update: ViewUpdate) => void, readonly ((update: ViewUpdate) => void)[]>;
  995. /**
  996. Facet that controls whether the editor content DOM is editable.
  997. When its highest-precedence value is `false`, the element will
  998. not have its `contenteditable` attribute set. (Note that this
  999. doesn't affect API calls that change the editor content, even
  1000. when those are bound to keys or buttons. See the
  1001. [`readOnly`](https://codemirror.net/6/docs/ref/#state.EditorState.readOnly) facet for that.)
  1002. */
  1003. static editable: Facet<boolean, boolean>;
  1004. /**
  1005. Allows you to influence the way mouse selection happens. The
  1006. functions in this facet will be called for a `mousedown` event
  1007. on the editor, and can return an object that overrides the way a
  1008. selection is computed from that mouse click or drag.
  1009. */
  1010. static mouseSelectionStyle: Facet<MakeSelectionStyle, readonly MakeSelectionStyle[]>;
  1011. /**
  1012. Facet used to configure whether a given selection drag event
  1013. should move or copy the selection. The given predicate will be
  1014. called with the `mousedown` event, and can return `true` when
  1015. the drag should move the content.
  1016. */
  1017. static dragMovesSelection: Facet<(event: MouseEvent) => boolean, readonly ((event: MouseEvent) => boolean)[]>;
  1018. /**
  1019. Facet used to configure whether a given selecting click adds a
  1020. new range to the existing selection or replaces it entirely. The
  1021. default behavior is to check `event.metaKey` on macOS, and
  1022. `event.ctrlKey` elsewhere.
  1023. */
  1024. static clickAddsSelectionRange: Facet<(event: MouseEvent) => boolean, readonly ((event: MouseEvent) => boolean)[]>;
  1025. /**
  1026. A facet that determines which [decorations](https://codemirror.net/6/docs/ref/#view.Decoration)
  1027. are shown in the view. Decorations can be provided in two
  1028. ways—directly, or via a function that takes an editor view.
  1029. Only decoration sets provided directly are allowed to influence
  1030. the editor's vertical layout structure. The ones provided as
  1031. functions are called _after_ the new viewport has been computed,
  1032. and thus **must not** introduce block widgets or replacing
  1033. decorations that cover line breaks.
  1034. */
  1035. static decorations: Facet<DecorationSet | ((view: EditorView) => DecorationSet), readonly (DecorationSet | ((view: EditorView) => DecorationSet))[]>;
  1036. /**
  1037. Used to provide ranges that should be treated as atoms as far as
  1038. cursor motion is concerned. This causes methods like
  1039. [`moveByChar`](https://codemirror.net/6/docs/ref/#view.EditorView.moveByChar) and
  1040. [`moveVertically`](https://codemirror.net/6/docs/ref/#view.EditorView.moveVertically) (and the
  1041. commands built on top of them) to skip across such regions when
  1042. a selection endpoint would enter them. This does _not_ prevent
  1043. direct programmatic [selection
  1044. updates](https://codemirror.net/6/docs/ref/#state.TransactionSpec.selection) from moving into such
  1045. regions.
  1046. */
  1047. static atomicRanges: Facet<(view: EditorView) => _codemirror_state.RangeSet<any>, readonly ((view: EditorView) => _codemirror_state.RangeSet<any>)[]>;
  1048. /**
  1049. Facet that allows extensions to provide additional scroll
  1050. margins (space around the sides of the scrolling element that
  1051. should be considered invisible). This can be useful when the
  1052. plugin introduces elements that cover part of that element (for
  1053. example a horizontally fixed gutter).
  1054. */
  1055. static scrollMargins: Facet<(view: EditorView) => Partial<Rect> | null, readonly ((view: EditorView) => Partial<Rect> | null)[]>;
  1056. /**
  1057. Create a theme extension. The first argument can be a
  1058. [`style-mod`](https://github.com/marijnh/style-mod#documentation)
  1059. style spec providing the styles for the theme. These will be
  1060. prefixed with a generated class for the style.
  1061. Because the selectors will be prefixed with a scope class, rule
  1062. that directly match the editor's [wrapper
  1063. element](https://codemirror.net/6/docs/ref/#view.EditorView.dom)—to which the scope class will be
  1064. added—need to be explicitly differentiated by adding an `&` to
  1065. the selector for that element—for example
  1066. `&.cm-focused`.
  1067. When `dark` is set to true, the theme will be marked as dark,
  1068. which will cause the `&dark` rules from [base
  1069. themes](https://codemirror.net/6/docs/ref/#view.EditorView^baseTheme) to be used (as opposed to
  1070. `&light` when a light theme is active).
  1071. */
  1072. static theme(spec: {
  1073. [selector: string]: StyleSpec;
  1074. }, options?: {
  1075. dark?: boolean;
  1076. }): Extension;
  1077. /**
  1078. This facet records whether a dark theme is active. The extension
  1079. returned by [`theme`](https://codemirror.net/6/docs/ref/#view.EditorView^theme) automatically
  1080. includes an instance of this when the `dark` option is set to
  1081. true.
  1082. */
  1083. static darkTheme: Facet<boolean, boolean>;
  1084. /**
  1085. Create an extension that adds styles to the base theme. Like
  1086. with [`theme`](https://codemirror.net/6/docs/ref/#view.EditorView^theme), use `&` to indicate the
  1087. place of the editor wrapper element when directly targeting
  1088. that. You can also use `&dark` or `&light` instead to only
  1089. target editors with a dark or light theme.
  1090. */
  1091. static baseTheme(spec: {
  1092. [selector: string]: StyleSpec;
  1093. }): Extension;
  1094. /**
  1095. Facet that provides additional DOM attributes for the editor's
  1096. editable DOM element.
  1097. */
  1098. static contentAttributes: Facet<AttrSource, readonly AttrSource[]>;
  1099. /**
  1100. Facet that provides DOM attributes for the editor's outer
  1101. element.
  1102. */
  1103. static editorAttributes: Facet<AttrSource, readonly AttrSource[]>;
  1104. /**
  1105. An extension that enables line wrapping in the editor (by
  1106. setting CSS `white-space` to `pre-wrap` in the content).
  1107. */
  1108. static lineWrapping: Extension;
  1109. /**
  1110. State effect used to include screen reader announcements in a
  1111. transaction. These will be added to the DOM in a visually hidden
  1112. element with `aria-live="polite"` set, and should be used to
  1113. describe effects that are visually obvious but may not be
  1114. noticed by screen reader users (such as moving to the next
  1115. search match).
  1116. */
  1117. static announce: _codemirror_state.StateEffectType<string>;
  1118. /**
  1119. Retrieve an editor view instance from the view's DOM
  1120. representation.
  1121. */
  1122. static findFromDOM(dom: HTMLElement): EditorView | null;
  1123. }
  1124. /**
  1125. Helper type that maps event names to event object types, or the
  1126. `any` type for unknown events.
  1127. */
  1128. interface DOMEventMap extends HTMLElementEventMap {
  1129. [other: string]: any;
  1130. }
  1131. /**
  1132. Event handlers are specified with objects like this. For event
  1133. types known by TypeScript, this will infer the event argument type
  1134. to hold the appropriate event object type. For unknown events, it
  1135. is inferred to `any`, and should be explicitly set if you want type
  1136. checking.
  1137. */
  1138. declare type DOMEventHandlers<This> = {
  1139. [event in keyof DOMEventMap]?: (this: This, event: DOMEventMap[event], view: EditorView) => boolean | void;
  1140. };
  1141. /**
  1142. Key bindings associate key names with
  1143. [command](https://codemirror.net/6/docs/ref/#view.Command)-style functions.
  1144. Key names may be strings like `"Shift-Ctrl-Enter"`—a key identifier
  1145. prefixed with zero or more modifiers. Key identifiers are based on
  1146. the strings that can appear in
  1147. [`KeyEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key).
  1148. Use lowercase letters to refer to letter keys (or uppercase letters
  1149. if you want shift to be held). You may use `"Space"` as an alias
  1150. for the `" "` name.
  1151. Modifiers can be given in any order. `Shift-` (or `s-`), `Alt-` (or
  1152. `a-`), `Ctrl-` (or `c-` or `Control-`) and `Cmd-` (or `m-` or
  1153. `Meta-`) are recognized.
  1154. When a key binding contains multiple key names separated by
  1155. spaces, it represents a multi-stroke binding, which will fire when
  1156. the user presses the given keys after each other.
  1157. You can use `Mod-` as a shorthand for `Cmd-` on Mac and `Ctrl-` on
  1158. other platforms. So `Mod-b` is `Ctrl-b` on Linux but `Cmd-b` on
  1159. macOS.
  1160. */
  1161. interface KeyBinding {
  1162. /**
  1163. The key name to use for this binding. If the platform-specific
  1164. property (`mac`, `win`, or `linux`) for the current platform is
  1165. used as well in the binding, that one takes precedence. If `key`
  1166. isn't defined and the platform-specific binding isn't either,
  1167. a binding is ignored.
  1168. */
  1169. key?: string;
  1170. /**
  1171. Key to use specifically on macOS.
  1172. */
  1173. mac?: string;
  1174. /**
  1175. Key to use specifically on Windows.
  1176. */
  1177. win?: string;
  1178. /**
  1179. Key to use specifically on Linux.
  1180. */
  1181. linux?: string;
  1182. /**
  1183. The command to execute when this binding is triggered. When the
  1184. command function returns `false`, further bindings will be tried
  1185. for the key.
  1186. */
  1187. run: Command;
  1188. /**
  1189. When given, this defines a second binding, using the (possibly
  1190. platform-specific) key name prefixed with `Shift-` to activate
  1191. this command.
  1192. */
  1193. shift?: Command;
  1194. /**
  1195. By default, key bindings apply when focus is on the editor
  1196. content (the `"editor"` scope). Some extensions, mostly those
  1197. that define their own panels, might want to allow you to
  1198. register bindings local to that panel. Such bindings should use
  1199. a custom scope name. You may also assign multiple scope names to
  1200. a binding, separating them by spaces.
  1201. */
  1202. scope?: string;
  1203. /**
  1204. When set to true (the default is false), this will always
  1205. prevent the further handling for the bound key, even if the
  1206. command(s) return false. This can be useful for cases where the
  1207. native behavior of the key is annoying or irrelevant but the
  1208. command doesn't always apply (such as, Mod-u for undo selection,
  1209. which would cause the browser to view source instead when no
  1210. selection can be undone).
  1211. */
  1212. preventDefault?: boolean;
  1213. }
  1214. /**
  1215. Facet used for registering keymaps.
  1216. You can add multiple keymaps to an editor. Their priorities
  1217. determine their precedence (the ones specified early or with high
  1218. priority get checked first). When a handler has returned `true`
  1219. for a given key, no further handlers are called.
  1220. */
  1221. declare const keymap: Facet<readonly KeyBinding[], readonly (readonly KeyBinding[])[]>;
  1222. /**
  1223. Run the key handlers registered for a given scope. The event
  1224. object should be a `"keydown"` event. Returns true if any of the
  1225. handlers handled it.
  1226. */
  1227. declare function runScopeHandlers(view: EditorView, event: KeyboardEvent, scope: string): boolean;
  1228. declare type SelectionConfig = {
  1229. /**
  1230. The length of a full cursor blink cycle, in milliseconds.
  1231. Defaults to 1200. Can be set to 0 to disable blinking.
  1232. */
  1233. cursorBlinkRate?: number;
  1234. /**
  1235. Whether to show a cursor for non-empty ranges. Defaults to
  1236. true.
  1237. */
  1238. drawRangeCursor?: boolean;
  1239. };
  1240. /**
  1241. Returns an extension that hides the browser's native selection and
  1242. cursor, replacing the selection with a background behind the text
  1243. (with the `cm-selectionBackground` class), and the
  1244. cursors with elements overlaid over the code (using
  1245. `cm-cursor-primary` and `cm-cursor-secondary`).
  1246. This allows the editor to display secondary selection ranges, and
  1247. tends to produce a type of selection more in line with that users
  1248. expect in a text editor (the native selection styling will often
  1249. leave gaps between lines and won't fill the horizontal space after
  1250. a line when the selection continues past it).
  1251. It does have a performance cost, in that it requires an extra DOM
  1252. layout cycle for many updates (the selection is drawn based on DOM
  1253. layout information that's only available after laying out the
  1254. content).
  1255. */
  1256. declare function drawSelection(config?: SelectionConfig): Extension;
  1257. /**
  1258. Draws a cursor at the current drop position when something is
  1259. dragged over the editor.
  1260. */
  1261. declare function dropCursor(): Extension;
  1262. interface SpecialCharConfig {
  1263. /**
  1264. An optional function that renders the placeholder elements.
  1265. The `description` argument will be text that clarifies what the
  1266. character is, which should be provided to screen readers (for
  1267. example with the
  1268. [`aria-label`](https://www.w3.org/TR/wai-aria/#aria-label)
  1269. attribute) and optionally shown to the user in other ways (such
  1270. as the
  1271. [`title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title)
  1272. attribute).
  1273. The given placeholder string is a suggestion for how to display
  1274. the character visually.
  1275. */
  1276. render?: ((code: number, description: string | null, placeholder: string) => HTMLElement) | null;
  1277. /**
  1278. Regular expression that matches the special characters to
  1279. highlight. Must have its 'g'/global flag set.
  1280. */
  1281. specialChars?: RegExp;
  1282. /**
  1283. Regular expression that can be used to add characters to the
  1284. default set of characters to highlight.
  1285. */
  1286. addSpecialChars?: RegExp | null;
  1287. }
  1288. /**
  1289. Returns an extension that installs highlighting of special
  1290. characters.
  1291. */
  1292. declare function highlightSpecialChars(
  1293. /**
  1294. Configuration options.
  1295. */
  1296. config?: SpecialCharConfig): Extension;
  1297. /**
  1298. Returns an extension that makes sure the content has a bottom
  1299. margin equivalent to the height of the editor, minus one line
  1300. height, so that every line in the document can be scrolled to the
  1301. top of the editor.
  1302. This is only meaningful when the editor is scrollable, and should
  1303. not be enabled in editors that take the size of their content.
  1304. */
  1305. declare function scrollPastEnd(): Extension;
  1306. /**
  1307. Mark lines that have a cursor on them with the `"cm-activeLine"`
  1308. DOM class.
  1309. */
  1310. declare function highlightActiveLine(): Extension;
  1311. /**
  1312. Extension that enables a placeholder—a piece of example content
  1313. to show when the editor is empty.
  1314. */
  1315. declare function placeholder(content: string | HTMLElement): Extension;
  1316. /**
  1317. Helper class used to make it easier to maintain decorations on
  1318. visible code that matches a given regular expression. To be used
  1319. in a [view plugin](https://codemirror.net/6/docs/ref/#view.ViewPlugin). Instances of this object
  1320. represent a matching configuration.
  1321. */
  1322. declare class MatchDecorator {
  1323. private regexp;
  1324. private getDeco;
  1325. private boundary;
  1326. private maxLength;
  1327. /**
  1328. Create a decorator.
  1329. */
  1330. constructor(config: {
  1331. /**
  1332. The regular expression to match against the content. Will only
  1333. be matched inside lines (not across them). Should have its 'g'
  1334. flag set.
  1335. */
  1336. regexp: RegExp;
  1337. /**
  1338. The decoration to apply to matches, either directly or as a
  1339. function of the match.
  1340. */
  1341. decoration: Decoration | ((match: RegExpExecArray, view: EditorView, pos: number) => Decoration);
  1342. /**
  1343. By default, changed lines are re-matched entirely. You can
  1344. provide a boundary expression, which should match single
  1345. character strings that can never occur in `regexp`, to reduce
  1346. the amount of re-matching.
  1347. */
  1348. boundary?: RegExp;
  1349. /**
  1350. Matching happens by line, by default, but when lines are
  1351. folded or very long lines are only partially drawn, the
  1352. decorator may avoid matching part of them for speed. This
  1353. controls how much additional invisible content it should
  1354. include in its matches. Defaults to 1000.
  1355. */
  1356. maxLength?: number;
  1357. });
  1358. /**
  1359. Compute the full set of decorations for matches in the given
  1360. view's viewport. You'll want to call this when initializing your
  1361. plugin.
  1362. */
  1363. createDeco(view: EditorView): _codemirror_state.RangeSet<Decoration>;
  1364. /**
  1365. Update a set of decorations for a view update. `deco` _must_ be
  1366. the set of decorations produced by _this_ `MatchDecorator` for
  1367. the view state before the update.
  1368. */
  1369. updateDeco(update: ViewUpdate, deco: DecorationSet): DecorationSet;
  1370. private updateRange;
  1371. }
  1372. /**
  1373. Create an extension that enables rectangular selections. By
  1374. default, it will react to left mouse drag with the Alt key held
  1375. down. When such a selection occurs, the text within the rectangle
  1376. that was dragged over will be selected, as one selection
  1377. [range](https://codemirror.net/6/docs/ref/#state.SelectionRange) per line.
  1378. */
  1379. declare function rectangularSelection(options?: {
  1380. /**
  1381. A custom predicate function, which takes a `mousedown` event and
  1382. returns true if it should be used for rectangular selection.
  1383. */
  1384. eventFilter?: (event: MouseEvent) => boolean;
  1385. }): Extension;
  1386. /**
  1387. Returns an extension that turns the pointer cursor into a
  1388. crosshair when a given modifier key, defaulting to Alt, is held
  1389. down. Can serve as a visual hint that rectangular selection is
  1390. going to happen when paired with
  1391. [`rectangularSelection`](https://codemirror.net/6/docs/ref/#view.rectangularSelection).
  1392. */
  1393. declare function crosshairCursor(options?: {
  1394. key?: "Alt" | "Control" | "Shift" | "Meta";
  1395. }): Extension;
  1396. /**
  1397. Creates an extension that configures tooltip behavior.
  1398. */
  1399. declare function tooltips(config?: {
  1400. /**
  1401. By default, tooltips use `"fixed"`
  1402. [positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/position),
  1403. which has the advantage that tooltips don't get cut off by
  1404. scrollable parent elements. However, CSS rules like `contain:
  1405. layout` can break fixed positioning in child nodes, which can be
  1406. worked about by using `"absolute"` here.
  1407. On iOS, which at the time of writing still doesn't properly
  1408. support fixed positioning, the library always uses absolute
  1409. positioning.
  1410. */
  1411. position?: "fixed" | "absolute";
  1412. /**
  1413. The element to put the tooltips into. By default, they are put
  1414. in the editor (`cm-editor`) element, and that is usually what
  1415. you want. But in some layouts that can lead to positioning
  1416. issues, and you need to use a different parent to work around
  1417. those.
  1418. */
  1419. parent?: HTMLElement;
  1420. /**
  1421. By default, when figuring out whether there is room for a
  1422. tooltip at a given position, the extension considers the entire
  1423. space between 0,0 and `innerWidth`,`innerHeight` to be available
  1424. for showing tooltips. You can provide a function here that
  1425. returns an alternative rectangle.
  1426. */
  1427. tooltipSpace?: (view: EditorView) => {
  1428. top: number;
  1429. left: number;
  1430. bottom: number;
  1431. right: number;
  1432. };
  1433. }): Extension;
  1434. /**
  1435. Describes a tooltip. Values of this type, when provided through
  1436. the [`showTooltip`](https://codemirror.net/6/docs/ref/#view.showTooltip) facet, control the
  1437. individual tooltips on the editor.
  1438. */
  1439. interface Tooltip {
  1440. /**
  1441. The document position at which to show the tooltip.
  1442. */
  1443. pos: number;
  1444. /**
  1445. The end of the range annotated by this tooltip, if different
  1446. from `pos`.
  1447. */
  1448. end?: number;
  1449. /**
  1450. A constructor function that creates the tooltip's [DOM
  1451. representation](https://codemirror.net/6/docs/ref/#view.TooltipView).
  1452. */
  1453. create(view: EditorView): TooltipView;
  1454. /**
  1455. Whether the tooltip should be shown above or below the target
  1456. position. Not guaranteed to be respected for hover tooltips
  1457. since all hover tooltips for the same range are always
  1458. positioned together. Defaults to false.
  1459. */
  1460. above?: boolean;
  1461. /**
  1462. Whether the `above` option should be honored when there isn't
  1463. enough space on that side to show the tooltip inside the
  1464. viewport. Defaults to false.
  1465. */
  1466. strictSide?: boolean;
  1467. /**
  1468. When set to true, show a triangle connecting the tooltip element
  1469. to position `pos`.
  1470. */
  1471. arrow?: boolean;
  1472. }
  1473. /**
  1474. Describes the way a tooltip is displayed.
  1475. */
  1476. interface TooltipView {
  1477. /**
  1478. The DOM element to position over the editor.
  1479. */
  1480. dom: HTMLElement;
  1481. /**
  1482. Adjust the position of the tooltip relative to its anchor
  1483. position. A positive `x` value will move the tooltip
  1484. horizontally along with the text direction (so right in
  1485. left-to-right context, left in right-to-left). A positive `y`
  1486. will move the tooltip up when it is above its anchor, and down
  1487. otherwise.
  1488. */
  1489. offset?: {
  1490. x: number;
  1491. y: number;
  1492. };
  1493. /**
  1494. By default, a tooltip's screen position will be based on the
  1495. text position of its `pos` property. This method can be provided
  1496. to make the tooltip view itself responsible for finding its
  1497. screen position.
  1498. */
  1499. getCoords?: (pos: number) => Rect;
  1500. /**
  1501. By default, tooltips are moved when they overlap with other
  1502. tooltips. Set this to `true` to disable that behavior for this
  1503. tooltip.
  1504. */
  1505. overlap?: boolean;
  1506. /**
  1507. Called after the tooltip is added to the DOM for the first time.
  1508. */
  1509. mount?(view: EditorView): void;
  1510. /**
  1511. Update the DOM element for a change in the view's state.
  1512. */
  1513. update?(update: ViewUpdate): void;
  1514. /**
  1515. Called when the tooltip has been (re)positioned.
  1516. */
  1517. positioned?(): void;
  1518. }
  1519. /**
  1520. Facet to which an extension can add a value to show a tooltip.
  1521. */
  1522. declare const showTooltip: Facet<Tooltip | null, readonly (Tooltip | null)[]>;
  1523. /**
  1524. Set up a hover tooltip, which shows up when the pointer hovers
  1525. over ranges of text. The callback is called when the mouse hovers
  1526. over the document text. It should, if there is a tooltip
  1527. associated with position `pos`, return the tooltip description
  1528. (either directly or in a promise). The `side` argument indicates
  1529. on which side of the position the pointer is—it will be -1 if the
  1530. pointer is before the position, 1 if after the position.
  1531. Note that all hover tooltips are hosted within a single tooltip
  1532. container element. This allows multiple tooltips over the same
  1533. range to be "merged" together without overlapping.
  1534. */
  1535. declare function hoverTooltip(source: (view: EditorView, pos: number, side: -1 | 1) => Tooltip | null | Promise<Tooltip | null>, options?: {
  1536. /**
  1537. Controls whether a transaction hides the tooltip. The default
  1538. is to not hide.
  1539. */
  1540. hideOn?: (tr: Transaction, tooltip: Tooltip) => boolean;
  1541. /**
  1542. When enabled (this defaults to false), close the tooltip
  1543. whenever the document changes or the selection is set.
  1544. */
  1545. hideOnChange?: boolean | "touch";
  1546. /**
  1547. Hover time after which the tooltip should appear, in
  1548. milliseconds. Defaults to 300ms.
  1549. */
  1550. hoverTime?: number;
  1551. }): Extension;
  1552. /**
  1553. Get the active tooltip view for a given tooltip, if available.
  1554. */
  1555. declare function getTooltip(view: EditorView, tooltip: Tooltip): TooltipView | null;
  1556. /**
  1557. Returns true if any hover tooltips are currently active.
  1558. */
  1559. declare function hasHoverTooltips(state: EditorState): boolean;
  1560. /**
  1561. Transaction effect that closes all hover tooltips.
  1562. */
  1563. declare const closeHoverTooltips: StateEffect<null>;
  1564. /**
  1565. Tell the tooltip extension to recompute the position of the active
  1566. tooltips. This can be useful when something happens (such as a
  1567. re-positioning or CSS change affecting the editor) that could
  1568. invalidate the existing tooltip positions.
  1569. */
  1570. declare function repositionTooltips(view: EditorView): void;
  1571. declare type PanelConfig = {
  1572. /**
  1573. By default, panels will be placed inside the editor's DOM
  1574. structure. You can use this option to override where panels with
  1575. `top: true` are placed.
  1576. */
  1577. topContainer?: HTMLElement;
  1578. /**
  1579. Override where panels with `top: false` are placed.
  1580. */
  1581. bottomContainer?: HTMLElement;
  1582. };
  1583. /**
  1584. Configures the panel-managing extension.
  1585. */
  1586. declare function panels(config?: PanelConfig): Extension;
  1587. /**
  1588. Object that describes an active panel.
  1589. */
  1590. interface Panel {
  1591. /**
  1592. The element representing this panel. The library will add the
  1593. `"cm-panel"` DOM class to this.
  1594. */
  1595. dom: HTMLElement;
  1596. /**
  1597. Optionally called after the panel has been added to the editor.
  1598. */
  1599. mount?(): void;
  1600. /**
  1601. Update the DOM for a given view update.
  1602. */
  1603. update?(update: ViewUpdate): void;
  1604. /**
  1605. Called when the panel is removed from the editor or the editor
  1606. is destroyed.
  1607. */
  1608. destroy?(): void;
  1609. /**
  1610. Whether the panel should be at the top or bottom of the editor.
  1611. Defaults to false.
  1612. */
  1613. top?: boolean;
  1614. }
  1615. /**
  1616. Get the active panel created by the given constructor, if any.
  1617. This can be useful when you need access to your panels' DOM
  1618. structure.
  1619. */
  1620. declare function getPanel(view: EditorView, panel: PanelConstructor): Panel | null;
  1621. /**
  1622. A function that initializes a panel. Used in
  1623. [`showPanel`](https://codemirror.net/6/docs/ref/#view.showPanel).
  1624. */
  1625. declare type PanelConstructor = (view: EditorView) => Panel;
  1626. /**
  1627. Opening a panel is done by providing a constructor function for
  1628. the panel through this facet. (The panel is closed again when its
  1629. constructor is no longer provided.) Values of `null` are ignored.
  1630. */
  1631. declare const showPanel: Facet<PanelConstructor | null, readonly (PanelConstructor | null)[]>;
  1632. /**
  1633. A gutter marker represents a bit of information attached to a line
  1634. in a specific gutter. Your own custom markers have to extend this
  1635. class.
  1636. */
  1637. declare abstract class GutterMarker extends RangeValue {
  1638. /**
  1639. Compare this marker to another marker of the same type.
  1640. */
  1641. eq(other: GutterMarker): boolean;
  1642. /**
  1643. Render the DOM node for this marker, if any.
  1644. */
  1645. toDOM?(view: EditorView): Node;
  1646. /**
  1647. This property can be used to add CSS classes to the gutter
  1648. element that contains this marker.
  1649. */
  1650. elementClass: string;
  1651. /**
  1652. Called if the marker has a `toDOM` method and its representation
  1653. was removed from a gutter.
  1654. */
  1655. destroy(dom: Node): void;
  1656. }
  1657. /**
  1658. Facet used to add a class to all gutter elements for a given line.
  1659. Markers given to this facet should _only_ define an
  1660. [`elementclass`](https://codemirror.net/6/docs/ref/#view.GutterMarker.elementClass), not a
  1661. [`toDOM`](https://codemirror.net/6/docs/ref/#view.GutterMarker.toDOM) (or the marker will appear
  1662. in all gutters for the line).
  1663. */
  1664. declare const gutterLineClass: Facet<RangeSet<GutterMarker>, readonly RangeSet<GutterMarker>[]>;
  1665. declare type Handlers = {
  1666. [event: string]: (view: EditorView, line: BlockInfo, event: Event) => boolean;
  1667. };
  1668. interface GutterConfig {
  1669. /**
  1670. An extra CSS class to be added to the wrapper (`cm-gutter`)
  1671. element.
  1672. */
  1673. class?: string;
  1674. /**
  1675. Controls whether empty gutter elements should be rendered.
  1676. Defaults to false.
  1677. */
  1678. renderEmptyElements?: boolean;
  1679. /**
  1680. Retrieve a set of markers to use in this gutter.
  1681. */
  1682. markers?: (view: EditorView) => (RangeSet<GutterMarker> | readonly RangeSet<GutterMarker>[]);
  1683. /**
  1684. Can be used to optionally add a single marker to every line.
  1685. */
  1686. lineMarker?: (view: EditorView, line: BlockInfo, otherMarkers: readonly GutterMarker[]) => GutterMarker | null;
  1687. /**
  1688. If line markers depend on additional state, and should be
  1689. updated when that changes, pass a predicate here that checks
  1690. whether a given view update might change the line markers.
  1691. */
  1692. lineMarkerChange?: null | ((update: ViewUpdate) => boolean);
  1693. /**
  1694. Add a hidden spacer element that gives the gutter its base
  1695. width.
  1696. */
  1697. initialSpacer?: null | ((view: EditorView) => GutterMarker);
  1698. /**
  1699. Update the spacer element when the view is updated.
  1700. */
  1701. updateSpacer?: null | ((spacer: GutterMarker, update: ViewUpdate) => GutterMarker);
  1702. /**
  1703. Supply event handlers for DOM events on this gutter.
  1704. */
  1705. domEventHandlers?: Handlers;
  1706. }
  1707. /**
  1708. Define an editor gutter. The order in which the gutters appear is
  1709. determined by their extension priority.
  1710. */
  1711. declare function gutter(config: GutterConfig): Extension;
  1712. /**
  1713. The gutter-drawing plugin is automatically enabled when you add a
  1714. gutter, but you can use this function to explicitly configure it.
  1715. Unless `fixed` is explicitly set to `false`, the gutters are
  1716. fixed, meaning they don't scroll along with the content
  1717. horizontally (except on Internet Explorer, which doesn't support
  1718. CSS [`position:
  1719. sticky`](https://developer.mozilla.org/en-US/docs/Web/CSS/position#sticky)).
  1720. */
  1721. declare function gutters(config?: {
  1722. fixed?: boolean;
  1723. }): Extension;
  1724. interface LineNumberConfig {
  1725. /**
  1726. How to display line numbers. Defaults to simply converting them
  1727. to string.
  1728. */
  1729. formatNumber?: (lineNo: number, state: EditorState) => string;
  1730. /**
  1731. Supply event handlers for DOM events on this gutter.
  1732. */
  1733. domEventHandlers?: Handlers;
  1734. }
  1735. /**
  1736. Facet used to provide markers to the line number gutter.
  1737. */
  1738. declare const lineNumberMarkers: Facet<RangeSet<GutterMarker>, readonly RangeSet<GutterMarker>[]>;
  1739. /**
  1740. Create a line number gutter extension.
  1741. */
  1742. declare function lineNumbers(config?: LineNumberConfig): Extension;
  1743. /**
  1744. Returns an extension that adds a `cm-activeLineGutter` class to
  1745. all gutter elements on the [active
  1746. line](https://codemirror.net/6/docs/ref/#view.highlightActiveLine).
  1747. */
  1748. declare function highlightActiveLineGutter(): Extension;
  1749. export { BidiSpan, BlockInfo, BlockType, Command, DOMEventHandlers, DOMEventMap, Decoration, DecorationSet, Direction, EditorView, EditorViewConfig, GutterMarker, KeyBinding, MatchDecorator, MouseSelectionStyle, Panel, PanelConstructor, PluginSpec, PluginValue, Rect, Tooltip, TooltipView, ViewPlugin, ViewUpdate, WidgetType, closeHoverTooltips, crosshairCursor, drawSelection, dropCursor, getPanel, getTooltip, gutter, gutterLineClass, gutters, hasHoverTooltips, highlightActiveLine, highlightActiveLineGutter, highlightSpecialChars, hoverTooltip, keymap, lineNumberMarkers, lineNumbers, logException, panels, placeholder, rectangularSelection, repositionTooltips, runScopeHandlers, scrollPastEnd, showPanel, showTooltip, tooltips };