/** * The command store: every command the user can reach, engine and UI, the * global keymap built from their default shortcuts, and running commands * from the keyboard, the palette and `uiCommand` events. * * - **List:** `listCommands` from the engine, refreshed when a project opens * or closes and whenever the palette opens, plus the UI commands of * {@link UI_COMMANDS} (also before the engine lists them). * - **Keymap:** one listener on the window in the capture phase, so * shortcuts also work while CodeMirror or an input has the focus. A * disabled command's shortcut is swallowed and does nothing. * - **Handlers:** components supply the behaviour of UI commands and the * context of engine commands (the editor runs `file.save` with the active * buffer) with {@link useCommandsStore}'s `provide`. Other engine * commands run with empty params. * - **Errors:** a failed command raises an error toast (M1.12). * - **Palette:** running any command but `palette.open` closes the palette * first (the modal rule, `modals.ts`). */ import { defineStore } from "pinia"; import { computed, ref, shallowReactive } from "vue"; import { hasMessage, t } from "../i18n"; import { listCommands, onEngineEvent, run, type CommandInfo, type EngineEventPayload, type JsonValue } from "../ipc"; import { useNotificationsStore } from "../stores/notifications"; import { useModalsStore } from "./modals"; import { buildKeymap, commandFor, formatShortcut, isMac } from "./keymap"; import { UI_COMMANDS } from "./uiCommands"; /** Behaviour a component supplies for a command. */ export interface CommandHandler { /** * Runs the command. * * @param params - the params it was run with (`{}` from the keyboard and * the palette, as given in a `uiCommand` event). */ run: (params: JsonValue) => void | Promise; /** Whether it can run now; always when absent. Reactive reads update the palette. */ enabled?: () => boolean; } /** A command as the palette shows it. */ export interface PaletteEntry { /** Command id. */ id: string; /** Label: the catalog text for UI commands, the engine's label otherwise. */ label: string; /** Default shortcut formatted for display, or null. */ shortcut: string | null; /** Whether it can run now. */ enabled: boolean; } /** Most recently run commands remembered. */ export const MAX_RECENT = 20; /** The UI commands that open the go-to popup, which therefore keep it open. */ const GOTO_OPEN = new Set(["goto.fileOpen", "goto.classOpen", "goto.symbolOpen"]); /** * Reads the command list from the engine, keeping well-formed entries. * * @param raw - the `listCommands` result. */ function toCommandInfos(raw: unknown): CommandInfo[] | null { if (!Array.isArray(raw)) { return null; } return (raw as unknown[]).filter( (c): c is CommandInfo => typeof c === "object" && c !== null && "id" in c && typeof c.id === "string" && "label" in c && typeof c.label === "string", ); } /** * The label of a command: the catalog text of its `labelKey` when the * catalog has it, else the engine's label. * * @param info - the command. */ function labelOf(info: CommandInfo): string { return typeof info.labelKey === "string" && hasMessage(info.labelKey) ? t(info.labelKey) : info.label; } /** Store of the commands, the keymap and the recently run commands. */ export const useCommandsStore = defineStore("commands", () => { const notifications = useNotificationsStore(); const modals = useModalsStore(); /** Commands as the engine lists them; empty until loaded. */ const infos = ref([]); /** Handlers supplied by components, by command id. */ const handlers = shallowReactive(new Map()); /** Ids of recently run commands, most recent first. */ const recent = ref([]); /** Whether `Mod` means Cmd. */ const mac = isMac(); /** Ends the engine event subscription; set while started. */ let unsubscribe: (() => void) | null = null; /** Every command: the engine's list plus UI commands it does not list yet. */ const all = computed(() => { const listed = new Set(infos.value.map((info) => info.id)); const local = UI_COMMANDS.filter((spec) => !listed.has(spec.id)).map( (spec): CommandInfo => ({ id: spec.id, label: spec.labelKey, labelKey: spec.labelKey, menuPath: spec.menuPath ?? null, defaultShortcut: spec.defaultShortcut ?? null, params: "", enabled: true, ui: true, }), ); return [...infos.value, ...local]; }); /** The keymap of every command with a default shortcut. */ const keymap = computed(() => buildKeymap(all.value, mac)); /** * Whether a command can run now: its handler decides if it has one; a UI * command without a handler cannot run; otherwise the engine's state. * * @param id - the command id. */ function isEnabled(id: string): boolean { const handler = handlers.get(id); if (handler) { return handler.enabled?.() ?? true; } const info = all.value.find((c) => c.id === id); return info !== undefined && info.ui !== true && info.enabled; } /** * The commands the palette offers: UI commands and engine commands that * are user actions (they have a menu path or a default shortcut), not * the protocol commands clients call with data (`buffer.edit`). */ const entries = computed(() => all.value .filter((info) => info.ui === true || info.menuPath !== null || info.defaultShortcut !== null) .map((info) => ({ id: info.id, label: labelOf(info), shortcut: typeof info.defaultShortcut === "string" ? formatShortcut(info.defaultShortcut, mac) : null, enabled: isEnabled(info.id), })), ); /** * Supplies the behaviour of a command. * * @param id - the command id. * @param handler - what running it does. * @returns a function that withdraws the handler (only if it is still this one). */ function provide(id: string, handler: CommandHandler): () => void { handlers.set(id, handler); return () => { if (handlers.get(id) === handler) { handlers.delete(id); } }; } /** * Remembers a command as run most recently. Opening the palette itself * is not remembered: it would always head the list it opens. * * @param id - the command id. */ function remember(id: string): void { if (id === "palette.open") { return; } recent.value = [id, ...recent.value.filter((other) => other !== id)].slice(0, MAX_RECENT); } /** * Runs a command the user chose (keyboard or palette): through its * handler if a component supplied one, else through the engine. A * disabled command does nothing. A failure raises an error toast. Any * command but `palette.open` closes the palette before it runs, and any * command but the go-to open commands closes the go-to popup. * * @param id - the command id. * @param params - the params. */ async function execute(id: string, params: JsonValue = {}): Promise { if (!isEnabled(id)) { return; } remember(id); if (id !== "palette.open") { modals.dismiss("palette"); } if (!GOTO_OPEN.has(id)) { modals.dismiss("goto"); } const handler = handlers.get(id); if (handler) { try { await handler.run(params); } catch (reason: unknown) { notifications.notifyError(id, { code: "internal", message: reason instanceof Error ? reason.message : String(reason), }); } return; } const result = await run(id, params); if (!result.ok) { notifications.notifyError(id, result.error); } } /** * Runs a UI command the engine dispatched (`uiCommand`). One without a * handler, or disabled now, raises a warning toast instead, so an agent * learns that nothing happened. * * @param id - the command id; unchecked, it comes from the engine. * @param params - its params. */ async function dispatch(id: unknown, params: unknown): Promise { const name = typeof id === "string" ? id : String(id); const handler = handlers.get(name); if (!handler || !(handler.enabled?.() ?? true)) { notifications.notify({ level: "warning", message: t("command.unavailable", { command: name }) }); return; } await execute(name, (params ?? {}) as JsonValue); } /** Loads the command list from the engine; a failure raises an error toast. */ async function refresh(): Promise { const result = await listCommands(); const list = result.ok ? toCommandInfos(result.value) : null; if (list) { infos.value = list; } else { notifications.notifyError( "listCommands", result.ok ? { code: "ipc", message: t("common.error.unexpectedResult", { command: "listCommands" }) } : result.error, ); } } /** * Handles an engine event: runs `uiCommand`s and refreshes the enabled * states when a project opens or closes. * * @param event - the engine event. */ function onEvent(event: EngineEventPayload): void { if (event.kind === "uiCommand") { void dispatch(event.id, event.params); } else if (event.kind === "projectOpened" || event.kind === "projectClosed") { void refresh(); } } /** * Runs the command bound to a key press. * * @param event - a key press anywhere in the window. */ function onKeydown(event: KeyboardEvent): void { const id = commandFor(keymap.value, event); if (id === null) { return; } event.preventDefault(); event.stopPropagation(); void execute(id); } /** * Starts the keymap and the `uiCommand` subscription, registers the UI * commands with the engine and loads the command list. Starting twice is * a no-op. */ async function start(): Promise { if (unsubscribe) { return; } unsubscribe = onEngineEvent(onEvent); window.addEventListener("keydown", onKeydown, true); const registered = await run("ui.registerCommands", { commands: UI_COMMANDS.map((spec) => ({ ...spec })), }); if (!registered.ok) { notifications.notifyError("ui.registerCommands", registered.error); } await refresh(); } /** Stops the keymap and the subscription. */ function stop(): void { window.removeEventListener("keydown", onKeydown, true); unsubscribe?.(); unsubscribe = null; } return { infos, recent, keymap, entries, isEnabled, provide, execute, dispatch, refresh, start, stop }; });