Lutra/ui/src/components/editor/reveal.ts
danny 6c75c08d70 M2.2: PHP highlighting, syntax colour tokens and editor.reveal
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 12:17:17 +02:00

88 lines
3.4 KiB
TypeScript

/**
* 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<typeof useEditorStore>;
/**
* 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<string, unknown>) : {};
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<void> {
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",
});
}