// Plaaayground v2 — KeyboardShortcuts
// Blueprint: 06 — Declarative hotkey registration wrapper (no UI)

import { useEffect } from "react";

export interface Shortcut {
  key: string;
  mod?: "meta" | "ctrl" | "shift" | "alt";
  action: () => void;
  description?: string;
  enabled?: boolean;
}

export interface KeyboardShortcutsProps {
  shortcuts: Shortcut[];
  enabled?: boolean;
  children?: React.ReactNode;
}

export function KeyboardShortcuts({
  shortcuts,
  enabled = true,
  children,
}: KeyboardShortcutsProps) {
  useEffect(() => {
    if (!enabled) return;

    function handleKeyDown(e: KeyboardEvent) {
      for (const shortcut of shortcuts) {
        if (shortcut.enabled === false) continue;

        const keyMatch = e.key.toLowerCase() === shortcut.key.toLowerCase();
        if (!keyMatch) continue;

        let modMatch = true;
        if (shortcut.mod === "meta") modMatch = e.metaKey || e.ctrlKey;
        else if (shortcut.mod === "ctrl") modMatch = e.ctrlKey;
        else if (shortcut.mod === "shift") modMatch = e.shiftKey;
        else if (shortcut.mod === "alt") modMatch = e.altKey;
        else modMatch = !e.metaKey && !e.ctrlKey && !e.altKey;

        if (modMatch) {
          e.preventDefault();
          shortcut.action();
          break;
        }
      }
    }

    window.addEventListener("keydown", handleKeyDown);
    return () => window.removeEventListener("keydown", handleKeyDown);
  }, [shortcuts, enabled]);

  return <>{children}</>;
}

Prop	Type	Default	Description

shortcuts*	`Shortcut[]`	—	Array of shortcut definitions
enabled	`boolean`	`true`	Enable/disable all shortcuts
children	`ReactNode`	—	Wrapped content

KeyboardShortcuts

API Reference

Source Code