Files
kandev/apps/web/components/global-commands.tsx
T
João Salavisa 99dfbbde58 feat(plugins): add keybindings and modal window capabilities (#1895)
* feat(plugins): add keybindings and modal window capabilities

Add two independent plugin UI capabilities.

Keybindings: plugins declare keybindings in the manifest under
ui.keybindings ({id, default, description}), validated backend-side
(combo grammar + unique ids, requires a UI bundle) and exposed to the
frontend. Plugin JS binds a handler via registry.registerKeybinding(id,
handler); a global dispatcher fires it. Combos are user-overridable in
Settings > Keyboard Shortcuts (namespaced plugin:{pluginId}:{id}) with
conflict detection against core and other plugins.

Modals: host.openModal({title?, content, size?, dismissible?}) returns a
{ close() } handle and renders in a single host-owned Dialog isolated by
PluginErrorBoundary, cleaned up on plugin unload.

Fixture plugin, PLUGIN-API.md / spec, and a Playwright e2e demonstrate a
keybinding handler opening a modal.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(plugins): address review feedback on keybinding dispatch and validation

Core shortcuts now take precedence over plugin keybindings on a colliding
combo (defaultPrevented cooperation between the two capture-phase
dispatchers), a throwing plugin handler no longer aborts dispatch to other
plugins, and the keybinding combo grammar is tightened: the backend validator
and frontend parser both drop the undocumented control/super modifier
aliases and reject shift+digit/symbol combos that can never actually fire
(KeyboardEvent.key reports the shifted character, not the token).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(plugins): stop conflicting core shortcut from double-firing with plugin keybindings

The earlier defaultPrevented guard only covered the central useAppShortcuts
dispatcher. Per-component core shortcuts registered via useKeyboardShortcut
run in the bubble phase, after the capture-phase plugin keybinding dispatcher,
so a plugin-handled-and-prevented combo still triggered the core action too.
Guard useKeyboardShortcut (and use-editor-keybinds, another capture-phase core
listener) on event.defaultPrevented so exactly one action fires per combo.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(plugins): make core shortcuts always win over plugin keybindings

Panel-search, task-switcher, and other core listeners never checked
event.defaultPrevented, so a plugin bound to the same combo (e.g. Cmd/Ctrl+F)
could still fire alongside them. Instead of patching every core listener,
usePluginShortcuts now computes the set of effective core shortcut combos
(registry, resolved through user overrides, plus FIND_IN_PANEL/SAVE) and
skips invoking any plugin handler whose combo is in that set, so the
matching core listener always handles the event exactly once.

Also adds a hook-level regression test for useEditorKeybinds' existing
defaultPrevented guard, and fixes a leaked capture-phase window listener in
use-keyboard-shortcut.test.ts that could bleed into later tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(web): keep Cmd+K closing the command panel after shortcut-precedence guard

cmdk's built-in vim bindings intercept Ctrl/Cmd+K and +P as list-navigation
shortcuts and call preventDefault() before the event reaches our window-level
useKeyboardShortcut listeners. Once that hook started bailing on
event.defaultPrevented (added to fix core/plugin shortcut double-firing), the
palette's own Cmd+K close/reopen toggle got silently suppressed whenever focus
was inside the open panel. Disable cmdk's vim bindings on the command palette
so its Ctrl/Cmd+K and +P always reach the app-level toggle.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(plugins): document keybindings and modal window plugin APIs

Fill in the public author-facing docs that the internal plugin-keybindings
and modal-window contract (PLUGIN-API.md, spec.md) already covers: the
registry.registerKeybinding / host.openModal JS surface, the ui.keybindings
manifest field with its combo grammar, and a capability mention on the
Plugins overview page.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Kandev Agent <agent@kandev.dev>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-24 11:45:28 +01:00

198 lines
6.0 KiB
TypeScript

"use client";
import { useMemo } from "react";
import { useRouter } from "@/lib/routing/client-router";
import { useTheme } from "@/components/theme/app-theme";
import {
IconHome,
IconList,
IconSettings,
IconChartBar,
IconSun,
IconMoon,
IconRobot,
IconCpu,
IconFolder,
IconMessageCircle,
IconSparkles,
IconBrandGithub,
} from "@tabler/icons-react";
import { useRegisterCommands } from "@/hooks/use-register-commands";
import { useKeyboardShortcut } from "@/hooks/use-keyboard-shortcut";
import { useAppShortcuts } from "@/hooks/use-app-shortcuts";
import { usePluginShortcuts } from "@/hooks/use-plugin-shortcuts";
import { useAppStore } from "@/components/state-provider";
import { useQuickChatLauncher } from "@/hooks/use-quick-chat-launcher";
import { getShortcut } from "@/lib/keyboard/shortcut-overrides";
import type { CommandItem } from "@/lib/commands/types";
type PushFn = ReturnType<typeof useRouter>["push"];
function buildNavigationCommands(push: PushFn): CommandItem[] {
return [
{
id: "nav-home",
label: "Go to Home",
group: "Navigation",
icon: <IconHome className="size-3.5" />,
keywords: ["home", "kanban", "board"],
action: () => push("/"),
},
{
id: "nav-tasks",
label: "Go to All Tasks",
group: "Navigation",
icon: <IconList className="size-3.5" />,
keywords: ["tasks", "list", "all"],
action: () => push("/tasks"),
},
{
id: "nav-settings",
label: "Go to Settings",
group: "Navigation",
icon: <IconSettings className="size-3.5" />,
keywords: ["settings", "preferences", "config", "general settings"],
action: () => push("/settings/general"),
},
{
id: "nav-stats",
label: "Go to Stats",
group: "Navigation",
icon: <IconChartBar className="size-3.5" />,
keywords: ["stats", "statistics", "analytics", "metrics"],
action: () => push("/stats"),
},
{
id: "nav-github",
label: "Go to GitHub Dashboard",
group: "Navigation",
icon: <IconBrandGithub className="size-3.5" />,
keywords: ["github", "dashboard", "pr", "pull request", "code review", "issues", "review"],
action: () => push("/github"),
},
{
id: "settings-agents",
label: "Agents Settings",
group: "Settings",
icon: <IconRobot className="size-3.5" />,
keywords: ["agents", "agent settings", "agent profiles", "installed agents", "claude"],
action: () => push("/settings/agents"),
},
{
id: "settings-executors",
label: "Executors Settings",
group: "Settings",
icon: <IconCpu className="size-3.5" />,
keywords: [
"executors",
"executor profiles",
"execution environment",
"environment variables",
"runtime",
"compute",
],
action: () => push("/settings/executors"),
},
{
id: "settings-workspace",
label: "Workspace Settings",
group: "Settings",
icon: <IconFolder className="size-3.5" />,
keywords: ["workspace", "workspaces"],
action: () => push("/settings/workspace"),
},
{
id: "settings-prompts",
label: "Prompts Settings",
group: "Settings",
icon: <IconMessageCircle className="size-3.5" />,
keywords: [
"prompts",
"prompt settings",
"custom prompts",
"prompt snippets",
"prompt templates",
],
action: () => push("/settings/prompts"),
},
];
}
function buildThemeCommand(
resolvedTheme: string | undefined,
setTheme: (theme: string) => void,
): CommandItem {
const isDark = resolvedTheme === "dark";
const destinationTheme = isDark ? "light" : "dark";
return {
id: "pref-theme",
label: isDark ? "Switch to Light Mode" : "Switch to Dark Mode",
group: "Preferences",
icon: isDark ? <IconSun className="size-3.5" /> : <IconMoon className="size-3.5" />,
keywords: ["theme", "color theme", "appearance"],
action: () => setTheme(destinationTheme),
};
}
export function GlobalCommands() {
const router = useRouter();
const { resolvedTheme, setTheme } = useTheme();
const activeWorkspaceId = useAppStore((s) => s.workspaces.activeId);
const handleOpenQuickChat = useQuickChatLauncher(activeWorkspaceId);
const handleOpenConfigChat = useQuickChatLauncher(activeWorkspaceId, "config");
const keyboardShortcuts = useAppStore((s) => s.userSettings.keyboardShortcuts);
const quickChatShortcut = getShortcut("QUICK_CHAT", keyboardShortcuts);
const quickChatCommand: CommandItem = useMemo(
() => ({
id: "quick-chat",
label: "Quick Chat",
group: "Actions",
icon: <IconMessageCircle className="size-3.5" />,
keywords: ["quick chat", "new quick chat", "quick question", "ask agent"],
shortcut: quickChatShortcut,
action: handleOpenQuickChat,
}),
[handleOpenQuickChat, quickChatShortcut],
);
const configChatCommand: CommandItem = useMemo(
() => ({
id: "config-chat",
label: "Configuration Chat",
group: "Actions",
icon: <IconSparkles className="size-3.5" />,
keywords: [
"config chat",
"config mode",
"configure kandev",
"workflow configuration",
"mcp configuration",
],
action: handleOpenConfigChat,
}),
[handleOpenConfigChat],
);
const commands = useMemo<CommandItem[]>(
() => [
...buildNavigationCommands(router.push),
buildThemeCommand(resolvedTheme, setTheme),
quickChatCommand,
configChatCommand,
],
[router.push, resolvedTheme, setTheme, quickChatCommand, configChatCommand],
);
useRegisterCommands(commands);
useKeyboardShortcut(quickChatShortcut, handleOpenQuickChat);
// Order matters: useAppShortcuts (core) must register its capture-phase
// keydown listener before usePluginShortcuts so core shortcuts win when a
// combo matches both — see the precedence note on each hook.
useAppShortcuts();
usePluginShortcuts();
return null;
}