/** * The UI command `editor.reveal {path, line, column}`: shows a position in * the editor. It opens the file (`file.open`) unless a tab has it, * activates the tab, places the cursor and scrolls it to the centre. * * Positions follow the C3 contract: `line` is 0-based and `column` counts * UTF-16 code units inside the line, converted to a CodeMirror position by * {@link positionOf} (CRLF-safe). Out-of-range values are clamped. Without * a `path` it centres the cursor of the active tab, which is what running * it from the palette does. The Find, Go-to and Structure windows and * agents (`uiCommand`) call it. */ import { EditorView } from "@codemirror/view"; import { nextTick } from "vue"; import { t } from "../../i18n"; import type { useEditorStore } from "../../stores/editor"; import { positionOf } from "./engineText"; /** Command id of the reveal command. */ export const REVEAL_COMMAND = "editor.reveal"; /** A position to reveal. */ export interface RevealTarget { /** File path as `file.open` takes it; null for the active tab. */ path: string | null; /** 0-based line; null keeps the cursor. */ line: number | null; /** 0-based column in UTF-16 code units. */ column: number; } /** The editor store as reveal uses it. */ type EditorStore = ReturnType; /** * Reads the params of `editor.reveal`. * * @param params - untrusted params from the engine, the palette or a caller. * @returns the target, or null if a field has the wrong type. */ export function parseReveal(params: unknown): RevealTarget | null { const p = typeof params === "object" && params !== null && !Array.isArray(params) ? (params as Record) : {}; const number = (value: unknown): number | null | undefined => value === undefined || value === null ? null : typeof value === "number" && Number.isFinite(value) ? value : undefined; const path = p.path === undefined || p.path === null ? null : typeof p.path === "string" && p.path !== "" ? p.path : undefined; const line = number(p.line); const column = number(p.column); if (path === undefined || line === undefined || column === undefined) { return null; } return { path, line, column: column ?? 0 }; } /** * Reveals a position. * * @param editor - the editor store. * @param params - the command params, see {@link parseReveal}. * @throws Error with a catalog message when the params are invalid or the * file cannot be opened; the command store shows it as an error toast. */ export async function reveal(editor: EditorStore, params: unknown): Promise { const target = parseReveal(params); if (!target) { throw new Error(t("editor.reveal.invalidParams")); } let id = editor.activeId; if (target.path !== null) { const path = target.path; id = editor.tabs.find((tab) => tab.path === path)?.id ?? (await editor.openFile(path)); if (id === null) { throw new Error(editor.lastError?.message ?? t("editor.reveal.openFailed", { path })); } editor.activate(id); await nextTick(); } const sync = id === null ? undefined : editor.syncOf(id); if (!sync) { return; } const state = sync.state; const pos = target.line === null ? state.selection.main.head : positionOf(state.doc, target.line, target.column); sync.dispatch({ selection: { anchor: pos }, effects: EditorView.scrollIntoView(pos, { y: "center" }), userEvent: "select.reveal", }); }