Shortcut Governance and Compatibility

Purpose

Shortcuts are a product API. They need ownership, versioning discipline, and compatibility standards.

Governance model

• central registry for all global shortcuts
• ownership metadata per shortcut
• reserved combinations documented
• deprecation path for changed shortcuts

Compatibility rules

• use meta or ctrl abstraction
• normalize key casing
• avoid clobbering browser critical defaults
• gate execution by focus context

Context guard utility

export function shouldHandleGlobalShortcut(target: EventTarget | null): boolean {
  const el = target as HTMLElement | null;
  if (!el) return true;
  const tag = (el.tagName || "").toLowerCase();
  const editable = el.getAttribute("contenteditable") === "true";
  return !editable && tag !== "input" && tag !== "textarea";
}

Conflict management

If conflict is detected:

1. prefer browser critical behavior
2. allow override only with explicit product decision
3. emit telemetry for blocked shortcut events

Test suite requirements

• unit tests for predicate logic
• integration tests for lifecycle registration and cleanup
• browser coverage in Chromium, Firefox, WebKit
• OS coverage in macOS and Linux or Windows

Operational metrics

• shortcut_used
• shortcut_blocked
• shortcut_conflict
• shortcut_handler_error

Release checklist

• registry updated
• docs updated
• keyboard QA completed
• no duplicate listeners detected

Anti-patterns

• shortcut logic scattered across nested components
• no cleanup on route changes
• direct key checks without modifier abstraction