/** * @file * * Mock of Obsidian's `Editor`, backed by an in-memory string buffer. */ import type { EditorChange as EditorChangeOriginal, EditorCommandName as EditorCommandNameOriginal, Editor as EditorOriginal, EditorPosition as EditorPositionOriginal, EditorRange as EditorRangeOriginal, EditorSelectionOrCaret as EditorSelectionOrCaretOriginal, EditorSelection as EditorSelectionOriginal, EditorTransaction as EditorTransactionOriginal } from 'obsidian'; import { EditorView } from '@codemirror/view'; import type { CoordsLeftTop } from '../internal/types.cjs'; /** * Mock of Obsidian's abstract `Editor`, the common interface over the CodeMirror editors. * * The document is a plain string with `\n` line breaks. The mock tracks one selection (an anchor and a head), * focus and scroll position, and keeps whole-document snapshots for undo and redo, each carrying the selection its * change started from. Folding and scrolling a range into view are no-ops. * * Two properties of CodeMirror's history are deliberately not modelled, because both would make the mock's * history depend on wall-clock time or on where the cursor has been since a change: a bare selection change is * not recorded against the last change (CodeMirror's `selectionsAfter`, which would take precedence over the * mapped selection when redoing), and consecutive typing or deleting changes are never grouped into one history * entry (CodeMirror's `addChanges` joins them within its `newGroupDelay`, keyed on the `origin` the mock ignores). */ export declare abstract class Editor { /** * The CodeMirror 6 `EditorView` behind the editor, as Obsidian's `Editor.cm` is. * * A REAL `EditorView`, built on first read and then kept in step with the mock's buffer in BOTH * directions: a change or selection made through the mock is dispatched into it, and a transaction * dispatched into it is applied to the mock as one change, undone in one step, carrying the selection CodeMirror * ended up with. So `cm.state.doc.toString()` and {@link Editor.getValue} never disagree, and library * code that reconfigures the view through it — `@mnaoumov/obsidian-lib`'s resource lock appends a * `Compartment` and reconfigures it to `EditorState.readOnly` — runs against the real thing. * * What it is NOT is a rendered editor: the view is detached, nothing measures or paints, and it * carries no extensions of its own beyond the listener that reads changes back. Its `state` is * therefore the honest part, and its DOM is not. * * @returns The view, the same instance on every read. */ get cm(): EditorView; private anchor; private codeMirror; private content; private focused; private head; private isSyncingCodeMirror; private redoStack; private scrollLeft; private scrollTop; private readonly undoStack; /** * Creates an editor with an empty document, the cursor at the start and no focus. */ constructor(); /** * Mock-only: views a value typed as Obsidian's `Editor` as this mock. * * @param value - The value typed as the original `Editor`. * @returns The same object, typed as the mock. */ static fromOriginalType__(value: EditorOriginal): Editor; /** * Mock-only: views this mock as Obsidian's `Editor` type. * * @returns The same object, typed as the original `Editor`. */ asOriginalType__(): EditorOriginal; /** * Removes focus from the editor; {@link Editor.hasFocus} then returns `false`. */ blur(): void; /** * Mock-only construction hook, called at the end of the constructor; a no-op meant for * `vi.spyOn(Editor.prototype, 'constructor__')`. */ constructor__(): void; /** * Runs a built-in editor command. The mock implements cursor movement, line deletion, line swapping, * indentation with tabs and newline-with-indent against its buffer; the folding commands are no-ops. * * @param command - The command to run. */ exec(command: EditorCommandNameOriginal): void; /** * Gives the editor focus; {@link Editor.hasFocus} then returns `true`. */ focus(): void; /** * Gets one end of the selection. * * @param side - `'anchor'` or `'head'` for that end, `'from'` or `'to'` for the earlier or later end; the head * when omitted. * @returns A copy of the requested position. */ getCursor(side?: 'anchor' | 'from' | 'head' | 'to'): EditorPositionOriginal; /** * Gets the document object. * * @returns This editor. */ getDoc(): this; /** * Gets the text of a line. * * @param line - The zero-based line number. * @returns The line's text without its line break, or `''` when the line does not exist. */ getLine(line: number): string; /** * Gets the text between two positions. * * @param from - The start position. * @param to - The end position, exclusive. * @returns The text in that range. */ getRange(from: EditorPositionOriginal, to: EditorPositionOriginal): string; /** * Gets the scroll position. * * @returns The position last set with {@link Editor.scrollTo}, initially `0` on both axes. */ getScrollInfo(): CoordsLeftTop; /** * Gets the selected text. * * @returns The text between the anchor and the head, or `''` when nothing is selected. */ getSelection(): string; /** * Gets the whole document. * * @returns The document text. */ getValue(): string; /** * Checks whether the editor has focus. * * @returns The state set by {@link Editor.focus} and {@link Editor.blur}, initially `false`. */ hasFocus(): boolean; /** * Gets the number of the last line. * * @returns The zero-based index of the last line. */ lastLine(): number; /** * Gets the number of lines in the document. * * @returns The line count; an empty document has one line. */ lineCount(): number; /** * Lists the selections. * * @returns A single selection, since the mock tracks only one, with copies of its anchor and head. */ listSelections(): EditorSelectionOriginal[]; /** * Converts a character offset into a line and column position. * * @param offset - The offset from the start of the document; clamped to the document's bounds. * @returns The matching position. */ offsetToPos(offset: number): EditorPositionOriginal; /** * Converts a line and column position into a character offset, resolving it the way Obsidian does. * * @param pos - The position. A line before the first resolves to the start of the document and a line past the * last to its end. A non-finite column resolves to the end of its line, and a negative one counts back from that * end, stopping at the line's start. Any other column is added to the line's start as is, so a column past the end * of its line runs on into the lines after it. * @returns The offset from the start of the document. */ posToOffset(pos: EditorPositionOriginal): number; /** * Reads the lines the selection covers and applies the changes computed from them as one transaction, as Obsidian * does. `read` is called for every such line first, then `write` for each of them, so both see the document as it * was before any change, and the whole pass is a single undo step. * * @typeParam T - The type of the value read from each line. * @param read - Called for each line the selection covers; returns a value for `write`, or `null`. * @param write - Called for each line with the value `read` returned; returns the change to make, if any. * @param ignoreEmpty - Whether to skip lines that hold nothing but whitespace, which are then neither read nor * written; `true` when omitted, and only honoured when more than one line is in play. */ processLines(read: (line: number, lineText: string) => null | T, write: (line: number, lineText: string, value: null | T) => EditorChangeOriginal | undefined, ignoreEmpty?: boolean): void; /** * Redoes the last undone change. The mock restores the document and the selection the change was undone from, as * CodeMirror's history does, so redoing an insertion puts the cursor after the inserted text. */ redo(): void; /** * Re-measures and redraws the editor. A no-op in the mock, which renders nothing. */ refresh(): void; /** * Replaces the text between two positions, or inserts it at one, as one change: it can be undone, it clears the * redo history, and the selection is mapped through it rather than set, as Obsidian dispatches no selection of its * own. So a cursor exactly at the insertion point stays in FRONT of the inserted text, and one after it shifts * along. A change that changes nothing is no change at all. * * @param replacement - The text to insert. * @param from - The start of the range. * @param to - The end of the range; when omitted the text is inserted at `from`. * @param _origin - The change's origin, used by Obsidian for undo grouping; ignored by the mock. * @throws RangeError when the range runs backwards or ends past the end of the document. */ replaceRange(replacement: string, from: EditorPositionOriginal, to?: EditorPositionOriginal, _origin?: string): void; /** * Replaces the selected text, or inserts at the cursor when nothing is selected. Unlike * {@link Editor.replaceRange}, this one sets the selection: the cursor goes after the inserted text, as * CodeMirror's `EditorState.replaceSelection` puts it. * * @param replacement - The text to insert. * @param _origin - The change's origin; ignored by the mock. */ replaceSelection(replacement: string, _origin?: string): void; /** * Mock-only: replaces the whole document and drops the undo and redo history, as Obsidian does when a view loads * a file into a fresh editor state. The cursor moves to the start of the document. * * @param content - The new document text. */ resetState__(content: string): void; /** * Scrolls a range into view. A no-op in the mock; the scroll position is unchanged. * * @param _range - The range to reveal. * @param _center - Whether to center the range in the viewport. */ scrollIntoView(_range: EditorRangeOriginal, _center?: boolean): void; /** * Scrolls to a position. The mock only records it for {@link Editor.getScrollInfo}. * * @param x - The horizontal scroll position; `null` or omitted keeps the current one. * @param y - The vertical scroll position; `null` or omitted keeps the current one. */ scrollTo(x?: null | number, y?: null | number): void; /** * Moves the cursor, collapsing the selection. * * @param pos - The position, or a zero-based line number. * @param ch - The column, when `pos` is a line number; `0` when omitted. */ setCursor(pos: EditorPositionOriginal | number, ch?: number): void; /** * Replaces the text of a line, as a {@link Editor.replaceRange} over the whole line. * * @param n - The zero-based line number. * @param text - The new text of the line. * @throws When the line does not exist. */ setLine(n: number, text: string): void; /** * Sets the selection. * * @param anchor - The fixed end of the selection. * @param head - The moving end; when omitted the selection collapses to a cursor at `anchor`. */ setSelection(anchor: EditorPositionOriginal, head?: EditorPositionOriginal): void; /** * Sets multiple selections. The mock tracks only one, so it keeps the main range. * * @param ranges - The selections or carets. * @param main - The index of the main selection; the first range is used when that index does not exist. * @throws When `ranges` is empty. */ setSelections(ranges: EditorSelectionOrCaretOriginal[], main?: number): void; /** * Replaces the whole document as one change, as Obsidian does: the change can be undone and clears the redo * history, and the selection is mapped through it, so a cursor at the end of the old document stays at the end of * the new one and a cursor anywhere else moves to the start. Replacing an empty document with an empty one is no * change at all. * * @param content - The new document text. */ setValue(content: string): void; /** * Checks whether any text is selected. * * @returns `true` when the anchor and head differ. */ somethingSelected(): boolean; /** * Applies a set of changes and selections as one transaction, as Obsidian does. * * `replaceSelection` replaces the selected text and `changes` follow it. Every position in them refers to the * document as it was BEFORE the transaction, the way CodeMirror reads a change set, so a change listed after one * that precedes it in the document still lands where its positions say. The whole transaction is a single undo * step. * * The selection is then taken from `selections` (the mock keeps the first), else `selection`, both resolved against * the document AFTER the changes; else the cursor goes after the `replaceSelection` text; else the existing * selection is mapped through the changes. * * @param tx - The changes and selection to apply. * @param _origin - The transaction's origin; ignored by the mock. */ transaction(tx: EditorTransactionOriginal, _origin?: string): void; /** * Undoes the last change. The mock restores the document and the selection the change started from, as * CodeMirror's history does. */ undo(): void; /** * Finds the word at a position, as CodeMirror does. A word is a run of letters, digits and underscores on one line, * found from either side of the position, so a position just after a word (the end of a line included) finds that * word. * * @param pos - The position to look at, resolved as {@link Editor.posToOffset} resolves it. * @returns The range of the word, or `null` when neither the character before the position nor the one after it is * a word character. * @throws RangeError when the position resolves past the end of the document. */ wordAt(pos: EditorPositionOriginal): EditorRangeOriginal | null; private codeMirrorSelection; private createCodeMirror; private dispatchChanges; private execDeleteLine; private execGoDown; private execGoEnd; private execGoLeft; private execGoRight; private execGoUp; private execGoWordLeft; private execGoWordRight; private execIndent; private execNewlineAndIndent; private execSwapLine; private getLines; private maxPos; private minPos; private offsetBelow; private popHistory; private readCodeMirrorUpdate; private selectedLineBlock; private syncCodeMirror; }