// =====================================================================
// Plaaayground v2 -- Keyboard Shortcuts Help Overlay (PLAY-91)
// Modal overlay showing all available shortcuts in categorized grid.
// Close on Escape or backdrop click. spring.gentle enter/exit.
// Respects prefers-reduced-motion.
// =====================================================================

import { useCallback, useEffect, useRef } from "react";
import { motion, AnimatePresence } from "framer-motion";
import { X } from "lucide-react";
import { spring, useReducedMotion } from "@/lib/motion";

// -- Types ------------------------------------------------------------

interface ShortcutsHelpProps {
  open: boolean;
  onClose: () => void;
}

interface ShortcutEntry {
  keys: string[];
  description: string;
}

interface ShortcutCategory {
  title: string;
  items: ShortcutEntry[];
}

// -- Data -------------------------------------------------------------

const isMac = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.userAgent);
const MOD = isMac ? "\u2318" : "Ctrl";

const SHORTCUT_CATEGORIES: ShortcutCategory[] = [
  {
    title: "Navigation",
    items: [
      { keys: [MOD, "K"], description: "Focus input bar" },
      { keys: ["Esc"], description: "Close panel / overlay" },
    ],
  },
  {
    title: "Canvas",
    items: [
      { keys: [MOD, "+"], description: "Zoom in" },
      { keys: [MOD, "\u2212"], description: "Zoom out" },
      { keys: [MOD, "0"], description: "Fit to view" },
      { keys: ["G"], description: "Toggle grid" },
    ],
  },
  {
    title: "Panels",
    items: [
      { keys: ["C"], description: "Toggle chat" },
      { keys: ["?"], description: "Toggle this help" },
    ],
  },
  {
    title: "Editing",
    items: [
      { keys: ["\u232B"], description: "Delete selected card" },
      { keys: [MOD, "Z"], description: "Undo" },
      { keys: [MOD, "\u21E7", "Z"], description: "Redo" },
    ],
  },
];

// -- Animation variants -----------------------------------------------

const backdropVariants = {
  hidden: { opacity: 0 },
  visible: { opacity: 1 },
};

const panelVariants = {
  hidden: { opacity: 0, scale: 0.96, y: 8 },
  visible: { opacity: 1, scale: 1, y: 0 },
};

const reducedPanelVariants = {
  hidden: { opacity: 0 },
  visible: { opacity: 1 },
};

// -- Component --------------------------------------------------------

export function ShortcutsHelp({ open, onClose }: ShortcutsHelpProps) {
  const reduced = useReducedMotion();
  const panelRef = useRef<HTMLDivElement>(null);

  // Close on backdrop click
  const handleBackdropClick = useCallback(
    (e: React.MouseEvent) => {
      if (panelRef.current && !panelRef.current.contains(e.target as Node)) {
        onClose();
      }
    },
    [onClose]
  );

  // Close on Escape (redundant safety -- useKeyboardShortcuts already handles this,
  // but users might open the overlay from outside the hook scope)
  useEffect(() => {
    if (!open) return;
    const handleKey = (e: KeyboardEvent) => {
      if (e.key === "Escape") onClose();
    };
    window.addEventListener("keydown", handleKey);
    return () => window.removeEventListener("keydown", handleKey);
  }, [open, onClose]);

  return (
    <AnimatePresence>
      {open && (
        <motion.div
          className="fixed inset-0 z-[100] flex items-center justify-center"
          variants={backdropVariants}
          initial="hidden"
          animate="visible"
          exit="hidden"
          transition={reduced ? { duration: 0.01 } : { duration: 0.2 }}
          onClick={handleBackdropClick}
        >
          {/* Backdrop */}
          <div className="absolute inset-0 bg-black/20 backdrop-blur-[2px]" />

          {/* Panel */}
          <motion.div
            ref={panelRef}
            className="relative w-full max-w-[480px] mx-4 bg-white border border-black/[0.06] shadow-[0_16px_48px_rgba(0,0,0,0.12),0_2px_8px_rgba(0,0,0,0.04)] overflow-hidden"
            variants={reduced ? reducedPanelVariants : panelVariants}
            initial="hidden"
            animate="visible"
            exit="hidden"
            transition={reduced ? { duration: 0.01 } : spring.gentle}
          >
            {/* Header */}
            <div className="flex items-center justify-between px-6 pt-5 pb-3">
              <h2 className="text-[15px] font-semibold text-foreground">
                Keyboard Shortcuts
              </h2>
              <button
                onClick={onClose}
                className="w-8 h-8 flex items-center justify-center text-foreground/40 hover:text-foreground/70 hover:bg-black/[0.04] transition-colors"
                aria-label="Close shortcuts help"
              >
                <X className="w-4 h-4" strokeWidth={2} />
              </button>
            </div>

            {/* Categories */}
            <div className="px-6 pb-6 space-y-5">
              {SHORTCUT_CATEGORIES.map((category) => (
                <div key={category.title}>
                  <h3 className="text-[11px] font-semibold uppercase tracking-wider text-foreground/35 mb-2.5">
                    {category.title}
                  </h3>
                  <div className="space-y-1.5">
                    {category.items.map((item) => (
                      <div
                        key={item.description}
                        className="flex items-center justify-between py-1"
                      >
                        <span className="text-[13px] text-foreground/70">
                          {item.description}
                        </span>
                        <div className="flex items-center gap-1">
                          {item.keys.map((k, i) => (
                            <kbd
                              key={`${item.description}-${i}`}
                              className="inline-flex items-center justify-center min-w-[24px] h-[24px] px-1.5 text-[11px] font-medium text-foreground/60 bg-black/[0.04] border border-black/[0.08]"
                            >
                              {k}
                            </kbd>
                          ))}
                        </div>
                      </div>
                    ))}
                  </div>
                </div>
              ))}
            </div>

            {/* Footer hint */}
            <div className="px-6 py-3 border-t border-black/[0.06] bg-black/[0.015]">
              <p className="text-[11px] text-foreground/30 text-center">
                Press <kbd className="inline px-1 py-0.5 text-[10px] bg-black/[0.04] border border-black/[0.06]">?</kbd> or <kbd className="inline px-1 py-0.5 text-[10px] bg-black/[0.04] border border-black/[0.06]">{MOD}/</kbd> to toggle
              </p>
            </div>
          </motion.div>
        </motion.div>
      )}
    </AnimatePresence>
  );
}
ShortcutsHelp

Source Code
