/** * The assist UI commands, so the palette, the keymap, agents and the * control channel reach completion, quick documentation and parameter * info without typing: * - `editor.complete` opens the completion list at the cursor (in the * editor also `Ctrl-Space`, CodeMirror's key). * - `editor.quickDocumentation` shows the hover documentation of the * symbol at the cursor (`Mod+I`); `Escape` or moving on closes it. * - `editor.parameterInfo` shows the signature help (in the editor also * `Mod-Shift-Space`). * * They act on the active PHP editor, which a view plugin of the assist * extensions records ({@link assistTracker}); without one they are * disabled. */ import { startCompletion } from "@codemirror/autocomplete"; import { StateEffect, StateField, type Extension } from "@codemirror/state"; import { EditorView, ViewPlugin, keymap, showTooltip, type Tooltip } from "@codemirror/view"; import { hoverAt } from "./hover"; import { requestSignatureHelp } from "./signature"; import type { AssistBuffer, AssistTransport } from "./types"; /** Command ids. */ export const COMPLETE_COMMAND = "editor.complete"; /** Command id of quick documentation. */ export const QUICK_DOC_COMMAND = "editor.quickDocumentation"; /** Command id of parameter info. */ export const PARAMETER_INFO_COMMAND = "editor.parameterInfo"; /** The active PHP editor and what its assist features use. */ interface Active { /** The view. */ view: EditorView; /** Its buffer. */ buffer: AssistBuffer; /** How it reaches the engine. */ transport: AssistTransport; } /** The active PHP editor, if any. */ let active: Active | null = null; /** Shows (a tooltip) or clears (null) the quick documentation. */ const setQuickDoc = StateEffect.define(); /** The quick documentation tooltip; closed by any edit or cursor move. */ const quickDocField = StateField.define({ create: () => null, update(value, tr) { for (const effect of tr.effects) { if (effect.is(setQuickDoc)) { return effect.value; } } return tr.docChanged || tr.selection ? null : value; }, provide: (field) => showTooltip.from(field), }); /** * Records the view as the active PHP editor while it shows a state with * these extensions, and adds the quick documentation tooltip. * * @param buffer - the buffer the state shows. * @param transport - how to reach the engine. */ export function assistTracker(buffer: AssistBuffer, transport: AssistTransport): Extension { return [ quickDocField, ViewPlugin.define((view) => { active = { view, buffer, transport }; return { destroy(): void { if (active?.view === view) { active = null; } }, }; }), keymap.of([ { key: "Escape", run: (view) => { if (!view.state.field(quickDocField, false)) { return false; } view.dispatch({ effects: setQuickDoc.of(null) }); return true; }, }, ]), ]; } /** Whether an assist command can run (a PHP editor is active). */ export function assistEnabled(): boolean { return active !== null; } /** Opens the completion list at the cursor. */ export function completeAtCursor(): void { if (active) { active.view.focus(); startCompletion(active.view); } } /** Shows the documentation of the symbol at the cursor. */ export async function quickDocumentation(): Promise { const current = active; if (!current) { return; } const { view } = current; const pos = view.state.selection.main.head; const tooltip = await hoverAt(view, pos, current.buffer, current.transport); if (tooltip && view.state.selection.main.head === pos) { view.dispatch({ effects: setQuickDoc.of({ ...tooltip, pos, end: pos }) }); } } /** Shows the signature help at the cursor. */ export function parameterInfo(): void { if (active) { requestSignatureHelp(active.view); } }