M1.8: command palette, global keymap, UI commands

- Engine: ui.registerCommands (validated, replaces the previous set),
  UI commands in listCommands with ui: true and labelKey, running one
  through the engine emits uiCommand {id, params}.
- Frontend: ui/src/commands/ (keymap by key code, fuzzy ranking, Pinia
  commands store with handlers, recents and error toasts), the command
  palette (Mod+Shift+P), UI commands palette.open, settings.open (Mod+,,
  disabled until M1.9b) and view.toggleProjectTree (Mod+1). The editor's
  shortcuts.ts moved into the global keymap.
- Tests: engine and control-channel tests for registration and
  uiCommand, Vitest for keymap, ranking, store, palette and App wiring.
- Docs: architecture, ui-parity, target-app-parity, gaps, roadmap,
  ROADMAP, README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-16 16:59:43 +02:00
parent 2f8fef876b
commit 184b8a3468
33 changed files with 2282 additions and 233 deletions

View file

@ -2,12 +2,15 @@
/**
* Root component: mounts the main window layout with the editor area; the
* slogan shows while no tab is open, and the restore dialog for unsaved
* texts from the recovery journal, and the toast stack. Loads product
* information from the engine on mount, starts showing notifications and
* following the theme (see `theme.ts`); a failed theme report raises an
* error toast.
* texts from the recovery journal, the toast stack and the command
* palette. Loads product information from the engine on mount, starts
* showing notifications, following the theme (see `theme.ts`; a failed
* theme report raises an error toast) and the global keymap with the UI
* commands (see `commands/store.ts`).
*/
import { onMounted, onUnmounted } from "vue";
import { useCommandsStore } from "./commands/store";
import CommandPalette from "./components/palette/CommandPalette.vue";
import EditorArea from "./components/editor/EditorArea.vue";
import MainLayout from "./components/layout/MainLayout.vue";
import NotificationStack from "./components/notifications/NotificationStack.vue";
@ -18,6 +21,7 @@ import { startTheme } from "./theme";
const app = useAppStore();
const notifications = useNotificationsStore();
const commands = useCommandsStore();
/** Stops following the theme; set while mounted. */
let stopTheme: (() => void) | null = null;
@ -25,12 +29,14 @@ let stopTheme: (() => void) | null = null;
onMounted(() => {
notifications.start();
stopTheme = startTheme((error) => notifications.notifyError("theme.systemPreference", error));
void commands.start();
void app.loadAbout();
});
onUnmounted(() => {
stopTheme?.();
stopTheme = null;
commands.stop();
notifications.stop();
});
</script>
@ -44,6 +50,7 @@ onUnmounted(() => {
</EditorArea>
</MainLayout>
<RecoveryDialog />
<CommandPalette />
<NotificationStack />
</template>

205
ui/src/commands/keymap.ts Normal file
View file

@ -0,0 +1,205 @@
/**
* The global keymap: default shortcuts of every command, engine and UI,
* matched against key presses by key code.
*
* Shortcuts are written in Lutra notation (`Mod+Alt+S`, `Mod` = Cmd on
* macOS, Ctrl elsewhere) and come from the command list (`listCommands`
* plus the UI commands); nothing here hard-codes a key.
*/
import { t } from "../i18n";
/** A parsed shortcut. */
export interface Shortcut {
/** Ctrl must be held. */
ctrl: boolean;
/** Meta (Cmd) must be held. */
meta: boolean;
/** Alt (Option) must be held. */
alt: boolean;
/** Shift must be held. */
shift: boolean;
/** The key, lower case (`s`, `f4`, `enter`, `,`). */
key: string;
}
/** One binding of the keymap. */
export interface Binding {
/** The command id. */
command: string;
/** The shortcut that runs it. */
shortcut: Shortcut;
}
/** Whether the frontend runs on macOS, where `Mod` means Cmd. */
export function isMac(): boolean {
return typeof navigator !== "undefined" && /Mac OS X|Macintosh|iPhone|iPad/.test(navigator.userAgent);
}
/**
* Parses a shortcut in Lutra notation.
*
* @param text - for example `Mod+Alt+S`; a trailing `+` is the plus key
* (`Mod++`).
* @param mac - whether `Mod` means Cmd.
* @returns the shortcut, or null when the text has no key or an unknown modifier.
*/
export function parseShortcut(text: string, mac: boolean): Shortcut | null {
const plusKey = text.endsWith("++");
const parts = (plusKey ? text.slice(0, -2) : text).split("+").map((part) => part.trim().toLowerCase());
const key = plusKey ? "+" : parts.pop();
if (key === undefined || key === "") {
return null;
}
const shortcut: Shortcut = { ctrl: false, meta: false, alt: false, shift: false, key };
for (const part of parts) {
switch (part) {
case "":
if (!plusKey) {
return null;
}
break;
case "mod":
if (mac) {
shortcut.meta = true;
} else {
shortcut.ctrl = true;
}
break;
case "ctrl":
shortcut.ctrl = true;
break;
case "cmd":
case "meta":
shortcut.meta = true;
break;
case "alt":
shortcut.alt = true;
break;
case "shift":
shortcut.shift = true;
break;
default:
return null;
}
}
return shortcut;
}
/** Punctuation keys by `KeyboardEvent.code`, as the US layout labels them. */
const PUNCTUATION: Readonly<Record<string, string>> = {
Comma: ",",
Period: ".",
Slash: "/",
Semicolon: ";",
Quote: "'",
BracketLeft: "[",
BracketRight: "]",
Backslash: "\\",
Minus: "-",
Equal: "=",
Backquote: "`",
};
/**
* The key of an event, independent of the keyboard layout effects of Alt
* and Shift for letters, digits and punctuation (`Alt+S` on macOS types
* `ß`, `Shift+1` types `!`).
*
* @param event - the key event.
*/
export function eventKey(event: KeyboardEvent): string {
const code = event.code;
if (/^Key[A-Z]$/.test(code)) {
return code.slice(3).toLowerCase();
}
if (/^(Digit|Numpad)[0-9]$/.test(code)) {
return code.slice(-1);
}
const punctuation = PUNCTUATION[code];
if (punctuation !== undefined) {
return punctuation;
}
return event.key.toLowerCase();
}
/**
* Whether a key event matches a shortcut exactly.
*
* @param event - the key event.
* @param shortcut - the shortcut.
*/
export function matches(event: KeyboardEvent, shortcut: Shortcut): boolean {
return (
event.ctrlKey === shortcut.ctrl &&
event.metaKey === shortcut.meta &&
event.altKey === shortcut.alt &&
event.shiftKey === shortcut.shift &&
eventKey(event) === shortcut.key
);
}
/**
* Builds the keymap from command descriptions. Commands without a shortcut
* or with one that does not parse are left out; when two commands share a
* shortcut, the first one listed wins.
*
* @param commands - id and default shortcut of each command.
* @param mac - whether `Mod` means Cmd.
*/
export function buildKeymap(
commands: readonly { id: string; defaultShortcut?: string | null | undefined }[],
mac: boolean,
): Binding[] {
const keymap: Binding[] = [];
for (const command of commands) {
const raw: unknown = command.defaultShortcut;
const shortcut = typeof raw === "string" ? parseShortcut(raw, mac) : null;
if (shortcut) {
keymap.push({ command: command.id, shortcut });
}
}
return keymap;
}
/**
* The command a key event triggers.
*
* @param keymap - the keymap.
* @param event - the key event.
* @returns the command id, or null.
*/
export function commandFor(keymap: readonly Binding[], event: KeyboardEvent): string | null {
return keymap.find((binding) => matches(event, binding.shortcut))?.command ?? null;
}
/**
* Formats a shortcut for display: modifier names from the catalog, in the
* order Ctrl, Alt, Shift, Cmd, and the key in upper case
* (`Ctrl+Shift+P`, `Cmd+,`).
*
* @param text - the shortcut in Lutra notation.
* @param mac - whether `Mod` means Cmd.
* @returns the display text, or null when the shortcut does not parse.
*/
export function formatShortcut(text: string, mac: boolean): string | null {
const shortcut = parseShortcut(text, mac);
if (shortcut === null) {
return null;
}
const parts: string[] = [];
if (shortcut.ctrl) {
parts.push(t("command.key.ctrl"));
}
if (shortcut.alt) {
parts.push(mac ? t("command.key.option") : t("command.key.alt"));
}
if (shortcut.shift) {
parts.push(t("command.key.shift"));
}
if (shortcut.meta) {
parts.push(t("command.key.cmd"));
}
const key = shortcut.key;
parts.push(key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1));
return parts.join("+");
}

189
ui/src/commands/rank.ts Normal file
View file

@ -0,0 +1,189 @@
/**
* Fuzzy ranking of commands for the palette.
*
* A query matches a command's label (the catalog text) or its id. Matches
* fall into tiers, best first: the text starts with the query; a word of
* the text starts with it; the query is spread over the starts of
* consecutive words (`togpro` → "Toggle Project"); the text contains it;
* its characters appear in order. Within a tier, recently run commands come
* first, then shorter texts, then the label alphabetically. Without a query
* every command is listed, recent ones first.
*/
/** Tier of a match; higher is better. */
export const Tier = {
/** Characters of the query appear in order. */
Fuzzy: 1,
/** The text contains the query. */
Substring: 2,
/** The query is spread over the starts of consecutive words. */
WordStarts: 3,
/** A word of the text starts with the query. */
WordPrefix: 4,
/** The text starts with the query. */
Prefix: 5,
} as const;
/** Longest query considered; longer ones are cut. */
export const MAX_QUERY = 100;
/** A match: its tier and how well it fits within the tier (higher is better). */
export interface Match {
/** The tier. */
tier: number;
/** Fit within the tier; shorter texts and tighter matches fit better. */
fit: number;
}
/** What the ranking needs of a command. */
export interface Rankable {
/** Command id. */
id: string;
/** Label as shown. */
label: string;
}
/**
* Splits a text into lower-case words at spaces, punctuation and camelCase
* boundaries (`view.toggleProjectTree` → view, toggle, project, tree).
*
* @param text - the text.
*/
export function words(text: string): string[] {
return text
.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
.toLowerCase()
.split(/[^\p{L}\p{N}]+/u)
.filter((word) => word !== "");
}
/**
* Whether the query can be split into pieces that start consecutive words,
* in order, each piece starting a later word than the one before.
*
* @param query - the query, lower case, without spaces.
* @param list - the words of the text.
*/
function spreadOverWordStarts(query: string, list: readonly string[]): boolean {
const memo = new Map<string, boolean>();
const from = (q: number, w: number): boolean => {
if (q === query.length) {
return true;
}
const memoKey = `${String(q)}:${String(w)}`;
const known = memo.get(memoKey);
if (known !== undefined) {
return known;
}
let found = false;
for (let i = w; i < list.length && !found; i += 1) {
const word = list[i] ?? "";
let k = 0;
while (k < word.length && q + k < query.length && word[k] === query[q + k]) {
k += 1;
}
for (let take = k; take >= 1 && !found; take -= 1) {
found = from(q + take, i + 1);
}
}
memo.set(memoKey, found);
return found;
};
return from(0, 0);
}
/**
* Matches a query against one text.
*
* @param query - the query; case and surrounding spaces are ignored.
* @param text - the label or id.
* @returns the match, or null if the query does not match.
*/
export function matchText(query: string, text: string): Match | null {
const q = query.trim().toLowerCase().slice(0, MAX_QUERY);
const lower = text.toLowerCase();
const length = -text.length;
if (q === "") {
return { tier: Tier.Prefix, fit: length };
}
if (lower.startsWith(q)) {
return { tier: Tier.Prefix, fit: length };
}
const list = words(text);
if (list.some((_, i) => list.slice(i).join(" ").startsWith(q))) {
return { tier: Tier.WordPrefix, fit: length };
}
const compact = q.replace(/\s+/g, "");
if (compact !== "" && spreadOverWordStarts(compact, list)) {
return { tier: Tier.WordStarts, fit: length };
}
const at = lower.indexOf(q);
if (at >= 0) {
return { tier: Tier.Substring, fit: length - at };
}
let gaps = 0;
let pos = -1;
for (const ch of compact) {
const next = lower.indexOf(ch, pos + 1);
if (next < 0) {
return null;
}
if (pos >= 0) {
gaps += next - pos - 1;
}
pos = next;
}
return compact === "" ? null : { tier: Tier.Fuzzy, fit: -gaps * 100 + length };
}
/**
* The better of two matches.
*
* @param a - a match or null.
* @param b - a match or null.
*/
function better(a: Match | null, b: Match | null): Match | null {
if (a === null) {
return b;
}
if (b === null) {
return a;
}
if (a.tier !== b.tier) {
return a.tier > b.tier ? a : b;
}
return a.fit >= b.fit ? a : b;
}
/**
* Ranks commands for a query.
*
* @param items - the commands.
* @param query - what the user typed.
* @param recent - ids of recently run commands, most recent first.
* @returns the matching commands, best first.
*/
export function rank<T extends Rankable>(items: readonly T[], query: string, recent: readonly string[]): T[] {
const recency = new Map(recent.map((id, i) => [id, i]));
const scored: { item: T; match: Match; recent: number }[] = [];
for (const item of items) {
const match = better(matchText(query, item.label), matchText(query, item.id));
if (match !== null) {
scored.push({ item, match, recent: recency.get(item.id) ?? Number.MAX_SAFE_INTEGER });
}
}
const empty = query.trim() === "";
scored.sort((a, b) => {
if (!empty && a.match.tier !== b.match.tier) {
return b.match.tier - a.match.tier;
}
if (a.recent !== b.recent) {
return a.recent - b.recent;
}
if (!empty && a.match.fit !== b.match.fit) {
return b.match.fit - a.match.fit;
}
return a.item.label.localeCompare(b.item.label);
});
return scored.map((entry) => entry.item);
}

301
ui/src/commands/store.ts Normal file
View file

@ -0,0 +1,301 @@
/**
* 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).
*/
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 { 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<void>;
/** 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;
/**
* 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();
/** Commands as the engine lists them; empty until loaded. */
const infos = ref<CommandInfo[]>([]);
/** Handlers supplied by components, by command id. */
const handlers = shallowReactive(new Map<string, CommandHandler>());
/** Ids of recently run commands, most recent first. */
const recent = ref<string[]>([]);
/** 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<CommandInfo[]>(() => {
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<PaletteEntry[]>(() =>
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.
*
* @param id - the command id.
* @param params - the params.
*/
async function execute(id: string, params: JsonValue = {}): Promise<void> {
if (!isEnabled(id)) {
return;
}
remember(id);
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<void> {
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<void> {
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<void> {
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 };
});

View file

@ -0,0 +1,27 @@
/**
* UI commands: commands the frontend runs itself. They are registered with
* the engine (`ui.registerCommands`) so `listCommands`, the palette, the
* keymap and agents see them; running one through the engine comes back as
* a `uiCommand` event. Components supply the behaviour with
* `useCommandsStore().provide(id, handler)`; a UI command nobody provides
* is disabled.
*/
/** A UI command as registered with the engine. */
export interface UiCommandSpec {
/** Command id, `area.action` in camelCase. */
id: string;
/** Catalog key of the label. */
labelKey: string;
/** Menu path with `/` separators. */
menuPath?: string;
/** Default shortcut in Lutra notation. */
defaultShortcut?: string;
}
/** The frontend's UI commands. */
export const UI_COMMANDS: readonly UiCommandSpec[] = [
{ id: "palette.open", labelKey: "command.palette.open", defaultShortcut: "Mod+Shift+P" },
{ id: "settings.open", labelKey: "command.settings.open", defaultShortcut: "Mod+," },
{ id: "view.toggleProjectTree", labelKey: "command.view.toggleProjectTree", defaultShortcut: "Mod+1" },
];

View file

@ -3,65 +3,39 @@
* The editor area: tab bar, a notice line for the active tab, the editor
* and the close question. Without open tabs it shows the default slot.
*
* Shortcuts come from the engine's command specs (see `shortcuts.ts`); the
* area listens on the window in the capture phase so they also work while
* CodeMirror has the focus. A keymap that cannot be loaded raises an
* error toast.
* Save, save all and close run through the global keymap and the
* palette (`commands/store.ts`): the area supplies their behaviour with the
* active buffer as context and says when they can run.
*/
import { onBeforeUnmount, onMounted } from "vue";
import { useCommandsStore } from "../../commands/store";
import { t } from "../../i18n";
import { useEditorStore } from "../../stores/editor";
import { useNotificationsStore } from "../../stores/notifications";
import ClosePrompt from "./ClosePrompt.vue";
import CodeEditor from "./CodeEditor.vue";
import EditorTabs from "./EditorTabs.vue";
import { commandFor, loadEditorKeymap, type EditorKeymap } from "./shortcuts";
const editor = useEditorStore();
const notifications = useNotificationsStore();
const commands = useCommandsStore();
/** Keymap loaded from the engine, empty until loaded. */
let keymap: EditorKeymap = [];
/**
* Runs the editor command bound to a key press.
*
* @param event - a key press anywhere in the window.
*/
function onKeydown(event: KeyboardEvent): void {
const command = commandFor(keymap, event);
if (command === null) {
return;
}
event.preventDefault();
event.stopPropagation();
switch (command) {
case "file.save":
void editor.save();
break;
case "file.saveAll":
void editor.saveAll();
break;
case "buffer.close":
void editor.requestClose();
break;
}
}
/** Withdraws the command handlers; filled while mounted. */
let withdraw: (() => void)[] = [];
onMounted(() => {
editor.start();
window.addEventListener("keydown", onKeydown, true);
void loadEditorKeymap().then((result) => {
if (result.ok) {
keymap = result.value;
} else {
notifications.notifyError("listCommands", result.error);
}
});
const hasActive = (): boolean => editor.activeTab !== null;
withdraw = [
commands.provide("file.save", { run: async () => { await editor.save(); }, enabled: hasActive }),
commands.provide("file.saveAll", { run: () => editor.saveAll(), enabled: () => editor.tabs.length > 0 }),
commands.provide("buffer.close", { run: () => editor.requestClose(), enabled: hasActive }),
];
});
onBeforeUnmount(() => {
window.removeEventListener("keydown", onKeydown, true);
for (const fn of withdraw) {
fn();
}
withdraw = [];
editor.stop();
});
</script>

View file

@ -1,156 +0,0 @@
/**
* Editor shortcuts, taken from the engine's command specs.
*
* The engine defines default shortcuts in Lutra notation (`Mod+Alt+S`,
* `Mod` = Cmd on macOS, Ctrl elsewhere). The editor area loads them with
* `listCommands` and maps key presses to the editor commands it handles
* with context (the active buffer): saving, saving all and closing a tab.
* Nothing here hard-codes a key.
*/
import { t } from "../../i18n";
import { listCommands, type CommandInfo, type RunResult } from "../../ipc";
/** Engine commands the editor area runs with the active buffer as context. */
export const EDITOR_SHORTCUT_COMMANDS = ["file.save", "file.saveAll", "buffer.close"] as const;
/** One of {@link EDITOR_SHORTCUT_COMMANDS}. */
export type EditorShortcutCommand = (typeof EDITOR_SHORTCUT_COMMANDS)[number];
/** A parsed shortcut. */
export interface Shortcut {
/** Ctrl must be held. */
ctrl: boolean;
/** Meta (Cmd) must be held. */
meta: boolean;
/** Alt (Option) must be held. */
alt: boolean;
/** Shift must be held. */
shift: boolean;
/** The key, lower case (`s`, `f4`, `enter`). */
key: string;
}
/** Whether the frontend runs on macOS, where `Mod` means Cmd. */
export function isMac(): boolean {
return typeof navigator !== "undefined" && /Mac OS X|Macintosh|iPhone|iPad/.test(navigator.userAgent);
}
/**
* Parses a shortcut in Lutra notation.
*
* @param text - for example `Mod+Alt+S`.
* @param mac - whether `Mod` means Cmd.
* @returns the shortcut, or null when the text has no key or an unknown modifier.
*/
export function parseShortcut(text: string, mac: boolean): Shortcut | null {
const parts = text.split("+").map((part) => part.trim().toLowerCase());
const key = parts.pop();
if (key === undefined || key === "") {
return null;
}
const shortcut: Shortcut = { ctrl: false, meta: false, alt: false, shift: false, key };
for (const part of parts) {
switch (part) {
case "mod":
if (mac) {
shortcut.meta = true;
} else {
shortcut.ctrl = true;
}
break;
case "ctrl":
shortcut.ctrl = true;
break;
case "cmd":
case "meta":
shortcut.meta = true;
break;
case "alt":
shortcut.alt = true;
break;
case "shift":
shortcut.shift = true;
break;
default:
return null;
}
}
return shortcut;
}
/**
* The key of an event, independent of keyboard layout effects of Alt and
* Shift for letters and digits (`Alt+S` on macOS types `ß`).
*
* @param event - the key event.
*/
function eventKey(event: KeyboardEvent): string {
const code = event.code;
if (/^Key[A-Z]$/.test(code)) {
return code.slice(3).toLowerCase();
}
if (/^Digit[0-9]$/.test(code)) {
return code.slice(5);
}
return event.key.toLowerCase();
}
/**
* Whether a key event matches a shortcut exactly.
*
* @param event - the key event.
* @param shortcut - the shortcut.
*/
export function matches(event: KeyboardEvent, shortcut: Shortcut): boolean {
return (
event.ctrlKey === shortcut.ctrl &&
event.metaKey === shortcut.meta &&
event.altKey === shortcut.alt &&
event.shiftKey === shortcut.shift &&
eventKey(event) === shortcut.key
);
}
/** Shortcuts of the editor commands, by command. */
export type EditorKeymap = { command: EditorShortcutCommand; shortcut: Shortcut }[];
/**
* Loads the default shortcuts of the editor commands from the engine.
*
* @param mac - whether `Mod` means Cmd.
* @returns the keymap, or the error of `listCommands`.
*/
export async function loadEditorKeymap(mac = isMac()): Promise<RunResult<EditorKeymap>> {
const result = await listCommands();
if (!result.ok) {
return result;
}
const list: unknown = result.value;
if (!Array.isArray(list)) {
return { ok: false, error: { code: "ipc", message: t("common.error.unexpectedResult", { command: "listCommands" }) } };
}
const commands = (list as unknown[]).filter(
(c): c is CommandInfo => typeof c === "object" && c !== null && "id" in c,
);
const keymap: EditorKeymap = [];
for (const command of EDITOR_SHORTCUT_COMMANDS) {
const info = commands.find((c) => c.id === command);
const raw: unknown = info?.defaultShortcut;
const shortcut = typeof raw === "string" ? parseShortcut(raw, mac) : null;
if (shortcut) {
keymap.push({ command, shortcut });
}
}
return { ok: true, value: keymap };
}
/**
* The editor command a key event triggers.
*
* @param keymap - the loaded keymap.
* @param event - the key event.
* @returns the command, or null.
*/
export function commandFor(keymap: EditorKeymap, event: KeyboardEvent): EditorShortcutCommand | null {
return keymap.find((entry) => matches(event, entry.shortcut))?.command ?? null;
}

View file

@ -4,9 +4,12 @@
* editor area in the middle and the status bar along the bottom.
*
* The editor area is a slot so the editor (M1.6) can replace the
* placeholder without touching the layout.
* placeholder without touching the layout. The layout supplies the UI
* command `view.toggleProjectTree` (`Mod+1`), which shows or hides the
* Project tool window.
*/
import { ref } from "vue";
import { onBeforeUnmount, onMounted, ref } from "vue";
import { useCommandsStore } from "../../commands/store";
import { t } from "../../i18n";
import ProjectToolWindow from "../project/ProjectToolWindow.vue";
import StatusBar from "../StatusBar.vue";
@ -16,6 +19,24 @@ import ToolWindow from "./ToolWindow.vue";
const leftWidth = ref(260);
/** Whether the left tool window is shown. */
const leftOpen = ref(true);
const commands = useCommandsStore();
/** Withdraws the command handler; set while mounted. */
let withdraw: (() => void) | null = null;
onMounted(() => {
withdraw = commands.provide("view.toggleProjectTree", {
run: () => {
leftOpen.value = !leftOpen.value;
},
});
});
onBeforeUnmount(() => {
withdraw?.();
withdraw = null;
});
</script>
<template>

View file

@ -0,0 +1,298 @@
<script setup lang="ts">
/**
* The command palette (`palette.open`, `Mod+Shift+P`): an overlay with a
* search field over every command the user can run, engine and UI.
*
* Typing ranks the commands fuzzily by label and id (see `rank.ts`);
* recently run commands come first. Each row shows the command's
* shortcut; commands that cannot run now are dimmed and cannot be chosen.
* Arrow keys move the selection, Enter runs it, Escape or a click outside
* closes. The command runs after the palette closed and gave the focus
* back, so a command that asks something (closing a dirty tab) gets it.
*/
import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
import { rank } from "../../commands/rank";
import { useCommandsStore, type PaletteEntry } from "../../commands/store";
import { t } from "../../i18n";
const commands = useCommandsStore();
/** Whether the palette is shown. */
const open = ref(false);
/** What the user typed. */
const query = ref("");
/** Index of the selected row. */
const selected = ref(0);
/** The search field. */
const input = ref<HTMLInputElement | null>(null);
/** The list. */
const list = ref<HTMLElement | null>(null);
/** The element that had the focus before the palette opened. */
let returnFocus: HTMLElement | null = null;
/** Withdraws the `palette.open` handler; set while mounted. */
let withdraw: (() => void) | null = null;
/** The matching commands, best first. */
const results = computed<PaletteEntry[]>(() => rank(commands.entries, query.value, commands.recent));
/** DOM id of the selected row, for `aria-activedescendant`. */
const activeId = computed(() => (results.value.length > 0 ? `lt-palette-${String(selected.value)}` : undefined));
watch(query, () => {
selected.value = 0;
});
/** Opens the palette with an empty query and refreshes the enabled states. */
async function show(): Promise<void> {
if (!open.value) {
const active = document.activeElement;
returnFocus = active instanceof HTMLElement ? active : null;
}
query.value = "";
selected.value = 0;
open.value = true;
await nextTick();
input.value?.focus();
await commands.refresh();
}
/** Closes the palette and gives the focus back. */
function close(): void {
if (!open.value) {
return;
}
open.value = false;
returnFocus?.focus();
returnFocus = null;
}
/**
* Runs a row's command if it is enabled; the palette closes first.
*
* @param entry - the row.
*/
function choose(entry: PaletteEntry | undefined): void {
if (!entry?.enabled) {
return;
}
close();
void commands.execute(entry.id);
}
/**
* Moves the selection, wrapping around, and keeps the row in view.
*
* @param step - rows to move, negative for up.
*/
function move(step: number): void {
const count = results.value.length;
if (count === 0) {
return;
}
selected.value = (selected.value + step + count) % count;
void nextTick(() => {
const row = list.value?.querySelector<HTMLElement>(`#lt-palette-${String(selected.value)}`);
row?.scrollIntoView({ block: "nearest" });
});
}
/**
* Keyboard handling of the search field.
*
* @param event - the key press.
*/
function onKeydown(event: KeyboardEvent): void {
switch (event.key) {
case "ArrowDown":
move(1);
break;
case "ArrowUp":
move(-1);
break;
case "Enter":
choose(results.value[selected.value]);
break;
case "Escape":
close();
break;
default:
return;
}
event.preventDefault();
event.stopPropagation();
}
onMounted(() => {
withdraw = commands.provide("palette.open", { run: show });
});
onBeforeUnmount(() => {
withdraw?.();
withdraw = null;
});
defineExpose({ show, close });
</script>
<template>
<div
v-if="open"
class="palette"
data-test="palette"
@mousedown.self.prevent="close()"
>
<div
class="palette__dialog"
role="dialog"
aria-modal="true"
:aria-label="t('palette.label')"
>
<input
ref="input"
v-model="query"
class="palette__input"
type="text"
role="combobox"
aria-autocomplete="list"
aria-expanded="true"
aria-controls="lt-palette-list"
:aria-activedescendant="activeId"
:aria-label="t('palette.label')"
:placeholder="t('palette.placeholder')"
spellcheck="false"
autocomplete="off"
data-test="palette-input"
@keydown="onKeydown"
>
<ul
id="lt-palette-list"
ref="list"
class="palette__list"
role="listbox"
:aria-label="t('palette.label')"
>
<li
v-for="(entry, index) in results"
:id="`lt-palette-${String(index)}`"
:key="entry.id"
class="palette__row"
:class="{
'palette__row--selected': index === selected,
'palette__row--disabled': !entry.enabled,
}"
role="option"
:aria-selected="index === selected"
:aria-disabled="!entry.enabled"
:data-command="entry.id"
data-test="palette-row"
@mousemove="selected = index"
@mousedown.prevent
@click="choose(entry)"
>
<span class="palette__label">{{ entry.label }}</span>
<span class="palette__id">{{ entry.id }}</span>
<kbd
v-if="entry.shortcut"
class="palette__shortcut"
data-test="palette-shortcut"
>{{ entry.shortcut }}</kbd>
</li>
</ul>
<p
v-if="results.length === 0"
class="palette__empty"
role="status"
data-test="palette-empty"
>
{{ t("palette.noMatches") }}
</p>
</div>
</div>
</template>
<style scoped>
.palette {
position: fixed;
inset: 0;
display: flex;
align-items: flex-start;
justify-content: center;
padding-top: 12vh;
background: color-mix(in srgb, var(--lt-bg) 40%, transparent);
z-index: 30;
}
.palette__dialog {
width: min(600px, 90vw);
max-height: 60vh;
display: flex;
flex-direction: column;
background: var(--lt-bg);
color: var(--lt-fg);
border: 1px solid var(--lt-border);
border-radius: 6px;
overflow: hidden;
}
.palette__input {
padding: 8px 12px;
font: inherit;
color: var(--lt-fg);
background: var(--lt-editor-bg);
border: none;
border-bottom: 1px solid var(--lt-border);
outline: none;
}
.palette__list {
margin: 0;
padding: 4px 0;
list-style: none;
overflow-y: auto;
}
.palette__row {
display: flex;
align-items: baseline;
gap: 12px;
padding: 4px 12px;
cursor: default;
}
.palette__row--selected {
background: var(--lt-editor-selection-bg);
}
.palette__row--disabled {
opacity: 0.55;
}
.palette__label {
flex-shrink: 0;
}
.palette__id {
flex: 1;
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
color: var(--lt-fg-muted);
}
.palette__shortcut {
font: inherit;
color: var(--lt-fg-muted);
}
.palette__row--selected .palette__id,
.palette__row--selected .palette__shortcut {
color: var(--lt-fg);
}
.palette__empty {
margin: 0;
padding: 8px 12px;
color: var(--lt-fg-muted);
}
</style>

View file

@ -1,5 +1,14 @@
{
"app.statusBar.version": "{name} {version}",
"command.key.alt": "Alt",
"command.key.cmd": "Cmd",
"command.key.ctrl": "Ctrl",
"command.key.option": "Option",
"command.key.shift": "Shift",
"command.palette.open": "Command Palette",
"command.settings.open": "Settings…",
"command.unavailable": "{command} cannot run right now",
"command.view.toggleProjectTree": "Show or Hide Project",
"common.cancel": "Cancel",
"common.close": "Close",
"common.dismiss": "Dismiss",
@ -31,6 +40,9 @@
"notification.stack.more": "+{count} more",
"notification.vfs.pumpFailed": "Applying changes on disk failed: {reason}",
"notification.watch.failed": "Lutra stopped watching the project for changes on disk: {reason}",
"palette.label": "Command palette",
"palette.noMatches": "No matching commands",
"palette.placeholder": "Type a command name",
"project.empty.noFolder": "No folder is open.",
"project.openFolder": "Open Folder…",
"project.toolWindow.title": "Project",

View file

@ -44,6 +44,13 @@ export type EngineEventPayload =
message?: unknown;
/** Placeholder values; unchecked. */
params?: unknown;
}
| {
kind: "uiCommand";
/** Id of the UI command to run; unchecked, it comes from the engine. */
id: unknown;
/** The params it was run with, as given; unchecked. */
params?: unknown;
};
/** Callback receiving engine events. */
@ -140,8 +147,10 @@ export type RunResult<T> = { ok: true; value: T } | { ok: false; error: EngineEr
export interface CommandInfo {
/** Command id, e.g. `app.about`. */
id: string;
/** Label shown in menus and the command palette. */
/** Label shown in menus and the command palette; for UI commands the catalog key. */
label: string;
/** Catalog key of the label; set for UI commands. */
labelKey?: string;
/** Menu path such as `Help/About Lutra`, or null if not in a menu. */
menuPath: string | null;
/** Default shortcut in Lutra notation (`Mod+Q`), or null. */
@ -150,6 +159,8 @@ export interface CommandInfo {
params: string;
/** Whether the command can run in the current state. */
enabled: boolean;
/** Whether the frontend registered the command (`ui.registerCommands`) and runs it. */
ui?: boolean;
}
/**

View file

@ -1,6 +1,8 @@
/**
* Tests for the root component: it loads product information on mount and
* shows it, or the error, in the status bar.
* shows it, or the error, in the status bar, and it wires the UI commands:
* `Mod+1` hides and shows the Project tool window, `Mod+Shift+P` opens the
* palette.
*/
import { flushPromises, mount } from "@vue/test-utils";
import { createPinia, setActivePinia } from "pinia";
@ -39,4 +41,25 @@ describe("App", () => {
expect(bar.text()).toBe("engine unavailable");
expect(bar.classes()).toContain("status-bar--error");
});
it("toggles the project tree and opens the palette from the keyboard", async () => {
invoke.mockImplementation((command: string) =>
Promise.resolve(command === "engine_list_commands" ? [] : null),
);
const wrapper = mount(App, { attachTo: document.body });
await flushPromises();
const press = async (init: KeyboardEventInit): Promise<void> => {
window.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, cancelable: true, ...init }));
await flushPromises();
};
expect(wrapper.find("[data-test=tool-window]").exists()).toBe(true);
await press({ key: "1", code: "Digit1", ctrlKey: true });
expect(wrapper.find("[data-test=tool-window]").exists()).toBe(false);
expect(wrapper.find("[data-test=tool-window-stripe]").exists()).toBe(true);
await press({ key: "1", code: "Digit1", ctrlKey: true });
expect(wrapper.find("[data-test=tool-window]").exists()).toBe(true);
await press({ key: "P", code: "KeyP", ctrlKey: true, shiftKey: true });
expect(wrapper.find("[data-test=palette]").exists()).toBe(true);
wrapper.unmount();
});
});

View file

@ -0,0 +1,86 @@
/**
* Tests of the global keymap: parsing Lutra notation (`Mod` per platform),
* matching by key code independent of what Alt and Shift type, building
* the keymap from command descriptions and formatting shortcuts for
* display.
*/
import { describe, expect, it } from "vitest";
import { buildKeymap, commandFor, eventKey, formatShortcut, matches, parseShortcut } from "../../src/commands/keymap";
/**
* A key event.
*
* @param init - its properties.
*/
function key(init: KeyboardEventInit): KeyboardEvent {
return new KeyboardEvent("keydown", init);
}
describe("parseShortcut", () => {
it("maps Mod to Ctrl or Cmd", () => {
expect(parseShortcut("Mod+Shift+P", false)).toEqual({ ctrl: true, meta: false, alt: false, shift: true, key: "p" });
expect(parseShortcut("Mod+Shift+P", true)).toEqual({ ctrl: false, meta: true, alt: false, shift: true, key: "p" });
});
it("reads punctuation, digits and the plus key", () => {
expect(parseShortcut("Mod+,", false)?.key).toBe(",");
expect(parseShortcut("Mod+1", false)?.key).toBe("1");
expect(parseShortcut("Mod++", false)).toEqual({ ctrl: true, meta: false, alt: false, shift: false, key: "+" });
});
it("rejects unknown modifiers and missing keys", () => {
expect(parseShortcut("Hyper+S", false)).toBeNull();
expect(parseShortcut("Mod+", false)).toBeNull();
expect(parseShortcut("", false)).toBeNull();
expect(parseShortcut("Mod++S", false)).toBeNull();
});
});
describe("matching", () => {
it("uses the key code for letters, digits and punctuation", () => {
expect(eventKey(key({ key: "ß", code: "KeyS" }))).toBe("s");
expect(eventKey(key({ key: "!", code: "Digit1" }))).toBe("1");
expect(eventKey(key({ key: ";", code: "Comma" }))).toBe(",");
expect(eventKey(key({ key: "F4", code: "F4" }))).toBe("f4");
});
it("requires the exact modifiers", () => {
const shortcut = parseShortcut("Mod+Shift+P", false);
expect(shortcut).not.toBeNull();
if (!shortcut) {
return;
}
expect(matches(key({ key: "P", code: "KeyP", ctrlKey: true, shiftKey: true }), shortcut)).toBe(true);
expect(matches(key({ key: "p", code: "KeyP", ctrlKey: true }), shortcut)).toBe(false);
expect(matches(key({ key: "P", code: "KeyP", ctrlKey: true, shiftKey: true, altKey: true }), shortcut)).toBe(false);
});
it("finds the command of a key press, the first listed winning", () => {
const keymap = buildKeymap(
[
{ id: "palette.open", defaultShortcut: "Mod+Shift+P" },
{ id: "settings.open", defaultShortcut: "Mod+," },
{ id: "view.toggleProjectTree", defaultShortcut: "Mod+1" },
{ id: "other.palette", defaultShortcut: "Mod+Shift+P" },
{ id: "no.shortcut", defaultShortcut: null },
{ id: "bad.shortcut", defaultShortcut: "Hyper+X" },
],
false,
);
expect(keymap.map((b) => b.command)).toEqual(["palette.open", "settings.open", "view.toggleProjectTree", "other.palette"]);
expect(commandFor(keymap, key({ key: "P", code: "KeyP", ctrlKey: true, shiftKey: true }))).toBe("palette.open");
expect(commandFor(keymap, key({ key: ",", code: "Comma", ctrlKey: true }))).toBe("settings.open");
expect(commandFor(keymap, key({ key: "1", code: "Digit1", ctrlKey: true }))).toBe("view.toggleProjectTree");
expect(commandFor(keymap, key({ key: "1", code: "Digit1", metaKey: true }))).toBeNull();
});
});
describe("formatShortcut", () => {
it("names the modifiers of the platform", () => {
expect(formatShortcut("Mod+Shift+P", false)).toBe("Ctrl+Shift+P");
expect(formatShortcut("Mod+Alt+S", true)).toBe("Option+Cmd+S");
expect(formatShortcut("Mod+,", false)).toBe("Ctrl+,");
expect(formatShortcut("Shift+F4", false)).toBe("Shift+F4");
expect(formatShortcut("Nope+X", false)).toBeNull();
});
});

View file

@ -0,0 +1,94 @@
/**
* Tests of the palette ranking: the match tiers (prefix, word prefix,
* word starts, substring, in-order characters), matching on the id as
* well as the label, recently run commands first, and the order without a
* query.
*/
import { describe, expect, it } from "vitest";
import { Tier, matchText, rank, words } from "../../src/commands/rank";
/** Commands as the palette ranks them. */
const COMMANDS = [
{ id: "file.save", label: "Save" },
{ id: "file.saveAll", label: "Save All" },
{ id: "project.openDialog", label: "Open Folder…" },
{ id: "project.close", label: "Close Project" },
{ id: "buffer.close", label: "Close Tab" },
{ id: "view.toggleProjectTree", label: "Show or Hide Project" },
{ id: "palette.open", label: "Command Palette" },
{ id: "app.quit", label: "Quit" },
];
/**
* The ids of the ranking.
*
* @param query - the query.
* @param recent - recently run ids.
*/
function ids(query: string, recent: string[] = []): string[] {
return rank(COMMANDS, query, recent).map((c) => c.id);
}
describe("words", () => {
it("splits at punctuation, spaces and camelCase", () => {
expect(words("view.toggleProjectTree")).toEqual(["view", "toggle", "project", "tree"]);
expect(words("Open Folder…")).toEqual(["open", "folder"]);
});
});
describe("matchText", () => {
it("sorts matches into tiers", () => {
expect(matchText("sav", "Save All")?.tier).toBe(Tier.Prefix);
expect(matchText("all", "Save All")?.tier).toBe(Tier.WordPrefix);
expect(matchText("hide proj", "Show or Hide Project")?.tier).toBe(Tier.WordPrefix);
expect(matchText("shp", "Show or Hide Project")?.tier).toBe(Tier.WordStarts);
expect(matchText("togpro", "view.toggleProjectTree")?.tier).toBe(Tier.WordStarts);
expect(matchText("ave", "Save All")?.tier).toBe(Tier.Substring);
expect(matchText("sel", "Save All")?.tier).toBe(Tier.Fuzzy);
expect(matchText("xyz", "Save All")).toBeNull();
});
it("ignores case and surrounding spaces", () => {
expect(matchText(" SAVE ", "save all")?.tier).toBe(Tier.Prefix);
});
});
describe("rank", () => {
it("puts prefix and word-start matches before in-order characters", () => {
expect(ids("clo")).toEqual(["buffer.close", "project.close", "project.openDialog"]);
expect(ids("pro").slice(0, 3)).toEqual(["project.close", "project.openDialog", "view.toggleProjectTree"]);
expect(ids("sa")[0]).toBe("file.save");
});
it("matches the id too", () => {
expect(ids("togglepro")).toEqual(["view.toggleProjectTree"]);
expect(ids("app.quit")).toEqual(["app.quit"]);
});
it("puts recent commands first within a tier", () => {
expect(ids("clo", ["project.close"]).slice(0, 2)).toEqual(["project.close", "buffer.close"]);
expect(ids("sav", ["file.saveAll"])).toEqual(["file.saveAll", "file.save"]);
expect(ids("sav", ["project.close"])).toEqual(["file.save", "file.saveAll"]);
});
it("does not let recency beat a better tier", () => {
expect(ids("sa", ["view.toggleProjectTree"])[0]).toBe("file.save");
});
it("lists everything without a query, recent first, then by label", () => {
expect(ids("", ["app.quit", "file.save"])).toEqual([
"app.quit",
"file.save",
"project.close",
"buffer.close",
"palette.open",
"project.openDialog",
"file.saveAll",
"view.toggleProjectTree",
]);
});
it("returns nothing for a query that matches nothing", () => {
expect(ids("zzz")).toEqual([]);
});
});

View file

@ -2,8 +2,9 @@
* Tests for the editor area and the editor store: opening tabs (from the
* tree and from engine events), editing through CodeMirror into
* `buffer.edit`, the dirty marker, closing (middle click, shortcut, the
* Save / Don't Save / Cancel question), saving through shortcuts loaded
* from the engine's command list, and the notice for files changed on disk.
* Save / Don't Save / Cancel question), saving through the global keymap
* (`commands/store.ts`) with shortcuts loaded from the engine's command
* list, and the notice for files changed on disk.
* The engine is a fake behind the mocked Tauri `invoke`.
*/
import { flushPromises, mount, type VueWrapper } from "@vue/test-utils";
@ -14,6 +15,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const invoke = vi.hoisted(() => vi.fn());
vi.mock("@tauri-apps/api/core", () => ({ invoke }));
import { useCommandsStore } from "../../src/commands/store";
import EditorArea from "../../src/components/editor/EditorArea.vue";
import { emitEditorEvent } from "../../src/components/editor/engineEvents";
import { emitEngineEvent } from "../../src/components/project/engineEvents";
@ -159,8 +161,9 @@ let pinia: Pinia;
/** Mounted components to unmount after each test. */
let mounted: VueWrapper[] = [];
/** Mounts the editor area. */
/** Mounts the editor area and starts the global keymap. */
async function mountArea(): Promise<VueWrapper> {
await useCommandsStore(pinia).start();
const wrapper = mount(EditorArea, {
attachTo: document.body,
slots: { default: "empty" },
@ -236,6 +239,7 @@ beforeEach(() => {
afterEach(async () => {
await flushPromises();
useCommandsStore(pinia).stop();
for (const wrapper of mounted) {
wrapper.unmount();
}

View file

@ -27,9 +27,12 @@ function sourceFiles(dir: string): string[] {
});
}
/** Every call of `t` with a literal first argument, by file. */
/**
* Every call of `t` with a literal first argument, and every literal
* `labelKey` (UI commands, whose labels the palette looks up), by file.
*/
const usedKeys = sourceFiles(SRC).flatMap((file) =>
[...readFileSync(file, "utf8").matchAll(/\bt\(\s*(["'`])([^"'`]*)\1/g)].map((m) => ({
[...readFileSync(file, "utf8").matchAll(/(?:\bt\(|\blabelKey:)\s*(["'`])([^"'`]*)\1/g)].map((m) => ({
file,
key: m[2] ?? "",
})),
@ -105,7 +108,7 @@ describe("en.json", () => {
it("uses flat dotted keys of known areas with string values", () => {
for (const [key, value] of Object.entries(en)) {
expect(key).toMatch(
/^(app|project|editor|common|theme|recovery|notification)\.[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$/,
/^(app|command|project|editor|common|palette|theme|recovery|notification)\.[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$/,
);
expect(typeof value).toBe("string");
expect(value.trim()).not.toBe("");

View file

@ -0,0 +1,350 @@
/**
* Tests of the command store and the palette: registering the UI commands
* with the engine, the global keymap, running engine and UI commands
* (error toasts for failures, disabled commands doing nothing), `uiCommand`
* events from the engine, and the palette's keyboard handling, ranking,
* shortcuts, dimmed disabled rows and recent commands. The engine is a
* fake behind the mocked Tauri `invoke` and `listen`.
*/
import { flushPromises, mount, type VueWrapper } from "@vue/test-utils";
import { createPinia, setActivePinia, type Pinia } from "pinia";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { defineComponent, h } from "vue";
const invoke = vi.hoisted(() => vi.fn());
const listen = vi.hoisted(() => vi.fn());
vi.mock("@tauri-apps/api/core", () => ({ invoke }));
vi.mock("@tauri-apps/api/event", () => ({ listen }));
import { useCommandsStore } from "../../src/commands/store";
import { UI_COMMANDS } from "../../src/commands/uiCommands";
import CommandPalette from "../../src/components/palette/CommandPalette.vue";
import { useNotificationsStore } from "../../src/stores/notifications";
/** Engine commands the fake lists. */
const ENGINE_COMMANDS = [
{ id: "app.quit", label: "Quit", menuPath: "File/Quit", defaultShortcut: "Mod+Q", params: "", enabled: true, ui: false },
{ id: "project.close", label: "Close Project", menuPath: "File/Close Project", defaultShortcut: null, params: "", enabled: false, ui: false },
{ id: "project.openDialog", label: "Open Folder…", menuPath: "File/Open Folder…", defaultShortcut: "Mod+O", params: "", enabled: true, ui: false },
{ id: "buffer.edit", label: "Edit Buffer", menuPath: null, defaultShortcut: null, params: "", enabled: true, ui: false },
];
/** Every `engine_execute` call, in order. */
let calls: { command: string; params: unknown }[];
/** Engine commands that fail, with their error code. */
let failing: Map<string, string>;
/** The engine event callback the store subscribed with. */
let deliver: ((payload: unknown) => void) | null;
/** Pinia of the current test. */
let pinia: Pinia;
/** Mounted components, unmounted after each test. */
let mounted: VueWrapper[];
/**
* The fake engine's listing: its commands plus the registered UI commands.
*/
function listing(): unknown[] {
const registered = calls.find((c) => c.command === "ui.registerCommands")?.params as
| { commands: { id: string; labelKey: string; defaultShortcut?: string }[] }
| undefined;
const ui = (registered?.commands ?? []).map((c) => ({
id: c.id,
label: c.labelKey,
labelKey: c.labelKey,
menuPath: null,
defaultShortcut: c.defaultShortcut ?? null,
params: "",
enabled: true,
ui: true,
}));
return [...ENGINE_COMMANDS, ...ui];
}
/**
* Sends an engine event to the store.
*
* @param payload - the event.
*/
async function emit(payload: unknown): Promise<void> {
deliver?.(payload);
await flushPromises();
}
/**
* Presses a key on the focused element (or the body).
*
* @param init - key event properties.
*/
async function press(init: KeyboardEventInit): Promise<void> {
const target = document.activeElement ?? document.body;
target.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, cancelable: true, ...init }));
await flushPromises();
}
/** Ctrl+Shift+P, the palette's shortcut off macOS. */
const PALETTE_KEY = { key: "P", code: "KeyP", ctrlKey: true, shiftKey: true };
/** A focusable button standing in for the editor. */
const Host = defineComponent({
setup: () => () => h("button", { id: "host-button" }, "host"),
});
/** Mounts the palette next to a focusable button and starts the store. */
async function mountPalette(): Promise<VueWrapper> {
const host = mount(Host, { attachTo: document.body });
const wrapper = mount(CommandPalette, { attachTo: document.body, global: { plugins: [pinia] } });
mounted.push(host, wrapper);
await useCommandsStore(pinia).start();
await flushPromises();
return wrapper;
}
/**
* The ids of the palette's rows, in order.
*
* @param wrapper - the palette.
*/
function rows(wrapper: VueWrapper): string[] {
return wrapper.findAll("[data-test=palette-row]").map((row) => row.attributes("data-command") ?? "");
}
/**
* Types into the palette's search field.
*
* @param wrapper - the palette.
* @param text - the query.
*/
async function type(wrapper: VueWrapper, text: string): Promise<void> {
await wrapper.find("[data-test=palette-input]").setValue(text);
await flushPromises();
}
beforeEach(() => {
pinia = createPinia();
setActivePinia(pinia);
calls = [];
failing = new Map();
deliver = null;
mounted = [];
Element.prototype.scrollIntoView = () => undefined;
invoke.mockReset();
listen.mockReset();
listen.mockImplementation((_name: string, callback: (event: { payload: unknown }) => void) => {
deliver = (payload) => {
callback({ payload });
};
return Promise.resolve(() => undefined);
});
invoke.mockImplementation((cmd: string, args?: { command: string; params: unknown }) => {
if (cmd === "engine_list_commands") {
return Promise.resolve(listing());
}
if (cmd === "engine_execute" && args) {
calls.push({ command: args.command, params: args.params });
const code = failing.get(args.command);
if (code !== undefined) {
return Promise.reject(Object.assign(new Error(code), { code, message: `${args.command} broke` }));
}
return Promise.resolve(null);
}
return Promise.resolve(null);
});
});
afterEach(() => {
useCommandsStore(pinia).stop();
for (const wrapper of mounted) {
wrapper.unmount();
}
});
describe("command store", () => {
it("registers the UI commands and lists them from the engine", async () => {
await mountPalette();
const store = useCommandsStore(pinia);
expect(calls[0]).toEqual({ command: "ui.registerCommands", params: { commands: UI_COMMANDS.map((c) => ({ ...c })) } });
expect(store.infos.filter((c) => c.ui === true).map((c) => c.id)).toEqual(UI_COMMANDS.map((c) => c.id));
expect(store.entries.map((e) => e.id)).not.toContain("buffer.edit");
const toggle = store.entries.find((e) => e.id === "view.toggleProjectTree");
expect(toggle).toEqual({ id: "view.toggleProjectTree", label: "Show or Hide Project", shortcut: "Ctrl+1", enabled: false });
});
it("keeps the UI commands when the engine refuses them, with an error toast", async () => {
failing.set("ui.registerCommands", "invalid_params");
await mountPalette();
const store = useCommandsStore(pinia);
expect(store.entries.map((e) => e.id)).toContain("palette.open");
expect(useNotificationsStore(pinia).toasts.map((t) => t.text)).toEqual([
"ui.registerCommands failed: ui.registerCommands broke",
]);
});
it("runs engine commands from their shortcut and reports failures", async () => {
await mountPalette();
failing.set("project.openDialog", "failed");
await press({ key: "o", code: "KeyO", ctrlKey: true });
expect(calls.at(-1)).toEqual({ command: "project.openDialog", params: {} });
expect(useNotificationsStore(pinia).toasts.map((t) => t.text)).toEqual([
"project.openDialog failed: project.openDialog broke",
]);
});
it("runs provided handlers and skips disabled commands", async () => {
await mountPalette();
const store = useCommandsStore(pinia);
let toggled = 0;
let allowed = false;
const withdraw = store.provide("view.toggleProjectTree", {
run: () => {
toggled += 1;
},
enabled: () => allowed,
});
const event = new KeyboardEvent("keydown", { key: "1", code: "Digit1", ctrlKey: true, bubbles: true, cancelable: true });
window.dispatchEvent(event);
await flushPromises();
expect(toggled).toBe(0);
expect(event.defaultPrevented).toBe(true);
allowed = true;
await press({ key: "1", code: "Digit1", ctrlKey: true });
expect(toggled).toBe(1);
withdraw();
await press({ key: "1", code: "Digit1", ctrlKey: true });
expect(toggled).toBe(1);
expect(calls.map((c) => c.command)).toEqual(["ui.registerCommands"]);
});
it("runs a uiCommand from the engine and warns about one nobody handles", async () => {
await mountPalette();
const store = useCommandsStore(pinia);
const seen: unknown[] = [];
store.provide("view.toggleProjectTree", {
run: (params) => {
seen.push(params);
},
});
await emit({ kind: "uiCommand", id: "view.toggleProjectTree", params: { from: "agent" } });
expect(seen).toEqual([{ from: "agent" }]);
await emit({ kind: "uiCommand", id: "settings.open", params: {} });
expect(useNotificationsStore(pinia).toasts.map((t) => t.text)).toEqual(["settings.open cannot run right now"]);
expect(store.recent).toEqual(["view.toggleProjectTree"]);
});
it("reports a handler that throws", async () => {
await mountPalette();
const store = useCommandsStore(pinia);
store.provide("view.toggleProjectTree", {
run: () => {
throw new Error("boom");
},
});
await store.execute("view.toggleProjectTree");
expect(useNotificationsStore(pinia).toasts.map((t) => t.text)).toEqual(["view.toggleProjectTree failed: boom"]);
});
it("reloads the enabled states when a project opens", async () => {
await mountPalette();
const before = invoke.mock.calls.filter(([cmd]) => cmd === "engine_list_commands").length;
await emit({ kind: "projectOpened", root: "/p", name: "p" });
expect(invoke.mock.calls.filter(([cmd]) => cmd === "engine_list_commands").length).toBe(before + 1);
});
});
describe("CommandPalette", () => {
it("opens with Mod+Shift+P and lists commands with shortcuts", async () => {
const wrapper = await mountPalette();
expect(wrapper.find("[data-test=palette]").exists()).toBe(false);
await press(PALETTE_KEY);
expect(wrapper.find("[data-test=palette]").exists()).toBe(true);
expect(document.activeElement).toBe(wrapper.find("[data-test=palette-input]").element);
expect(rows(wrapper)).toEqual([
"project.close",
"palette.open",
"project.openDialog",
"app.quit",
"settings.open",
"view.toggleProjectTree",
]);
const quit = wrapper.find("[data-command='app.quit']");
expect(quit.find("[data-test=palette-shortcut]").text()).toBe("Ctrl+Q");
expect(quit.text()).toContain("Quit");
});
it("opens from a uiCommand the engine sends (control channel)", async () => {
const wrapper = await mountPalette();
await emit({ kind: "uiCommand", id: "palette.open", params: {} });
expect(wrapper.find("[data-test=palette]").exists()).toBe(true);
});
it("filters and moves with the arrow keys, runs with Enter", async () => {
const wrapper = await mountPalette();
await press(PALETTE_KEY);
await type(wrapper, "o");
expect(rows(wrapper).slice(0, 2)).toEqual(["project.openDialog", "palette.open"]);
await type(wrapper, "open f");
expect(rows(wrapper)[0]).toBe("project.openDialog");
await press({ key: "ArrowDown" });
await press({ key: "ArrowUp" });
expect(wrapper.find("[aria-selected=true]").attributes("data-command")).toBe("project.openDialog");
await press({ key: "Enter" });
expect(wrapper.find("[data-test=palette]").exists()).toBe(false);
expect(calls.at(-1)).toEqual({ command: "project.openDialog", params: {} });
});
it("wraps around with the arrow keys", async () => {
const wrapper = await mountPalette();
await press(PALETTE_KEY);
await press({ key: "ArrowUp" });
expect(wrapper.find("[aria-selected=true]").attributes("data-command")).toBe("view.toggleProjectTree");
await press({ key: "ArrowDown" });
expect(wrapper.find("[aria-selected=true]").attributes("data-command")).toBe("project.close");
});
it("dims disabled commands, which Enter and clicks do not run", async () => {
const wrapper = await mountPalette();
await press(PALETTE_KEY);
await type(wrapper, "close proj");
const row = wrapper.find("[data-command='project.close']");
expect(row.attributes("aria-disabled")).toBe("true");
expect(row.classes()).toContain("palette__row--disabled");
await press({ key: "Enter" });
await row.trigger("click");
expect(wrapper.find("[data-test=palette]").exists()).toBe(true);
expect(calls.map((c) => c.command)).not.toContain("project.close");
await type(wrapper, "settings");
expect(wrapper.find("[data-command='settings.open']").attributes("aria-disabled")).toBe("true");
});
it("closes with Escape and gives the focus back", async () => {
const wrapper = await mountPalette();
const button = document.getElementById("host-button");
button?.focus();
await press(PALETTE_KEY);
expect(document.activeElement).not.toBe(button);
await press({ key: "Escape" });
expect(wrapper.find("[data-test=palette]").exists()).toBe(false);
expect(document.activeElement).toBe(button);
expect(calls.map((c) => c.command)).toEqual(["ui.registerCommands"]);
});
it("shows recently run commands first", async () => {
const wrapper = await mountPalette();
await press(PALETTE_KEY);
await type(wrapper, "quit");
await press({ key: "Enter" });
await press(PALETTE_KEY);
expect(rows(wrapper)[0]).toBe("app.quit");
await wrapper.find("[data-command='project.openDialog']").trigger("click");
await flushPromises();
await press(PALETTE_KEY);
expect(rows(wrapper).slice(0, 2)).toEqual(["project.openDialog", "app.quit"]);
});
it("says when nothing matches", async () => {
const wrapper = await mountPalette();
await press(PALETTE_KEY);
await type(wrapper, "zzzz");
expect(rows(wrapper)).toEqual([]);
expect(wrapper.find("[data-test=palette-empty]").text()).toBe("No matching commands");
});
});