Files
kandev/apps/web/lib/keyboard/shortcut-conflicts.ts
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

63 lines
2.3 KiB
TypeScript

/**
* Pure conflict detection over a list of resolved (effective) keyboard
* shortcuts — used to warn about core-vs-plugin and plugin-vs-plugin combo
* collisions in Settings > Keyboard Shortcuts. Detection only; UI surfacing
* is a lightweight per-row indicator (see `keyboard-shortcuts-card.tsx`).
*/
import type { KeyboardShortcut } from "./constants";
import { isUnboundShortcut } from "./shortcut-overrides";
import type { ShortcutEntry } from "./plugin-shortcuts";
/**
* Canonicalizes a shortcut to a comparable string, resolving `ctrlOrCmd` to
* the concrete modifier the given platform would fire (mirrors
* `matchesShortcut`'s runtime behavior). Returns null for an unbound
* shortcut — unbound entries never conflict with anything.
*/
export function comboKey(shortcut: KeyboardShortcut, isMacPlatform: boolean): string | null {
if (isUnboundShortcut(shortcut)) return null;
const modifiers = shortcut.modifiers;
const ctrl = !!modifiers?.ctrl || !!(modifiers?.ctrlOrCmd && !isMacPlatform);
const cmd = !!modifiers?.cmd || !!(modifiers?.ctrlOrCmd && isMacPlatform);
const alt = !!modifiers?.alt;
const shift = !!modifiers?.shift;
return [shortcut.key.toLowerCase(), ctrl, cmd, alt, shift].join("|");
}
/** A group of two or more entries whose effective combo collides. */
export interface ShortcutConflictGroup {
comboKey: string;
entries: ShortcutEntry[];
}
/**
* Groups `entries` (already resolved to their effective shortcut, e.g. via
* `resolveShortcutEntry`) by collision. Only groups with 2+ members are
* returned. Dispatch order for a colliding combo is registration order (see
* `hooks/use-plugin-shortcuts.ts`) — this helper only detects and reports,
* it doesn't resolve precedence.
*/
export function findShortcutConflicts(
resolved: { entry: ShortcutEntry; shortcut: KeyboardShortcut }[],
isMacPlatform: boolean,
): ShortcutConflictGroup[] {
const groups = new Map<string, ShortcutEntry[]>();
for (const { entry, shortcut } of resolved) {
const key = comboKey(shortcut, isMacPlatform);
if (key === null) continue;
const group = groups.get(key);
if (group) {
group.push(entry);
} else {
groups.set(key, [entry]);
}
}
return Array.from(groups.entries())
.filter(([, list]) => list.length > 1)
.map(([key, list]) => ({ comboKey: key, entries: list }));
}