Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

6.0 KB
Raw Blame
import { useEffect, useRef, useCallback } from 'react';
import { Keyboard, X } from 'lucide-react';
import { useKeyboardHelp } from '../hooks/useKeyboardHelp';
import { useScrollLock } from '../hooks/useScrollLock';
import { modKey } from '../utils/platform';
import Modal from './ui/Modal';
import Kbd from './ui/Kbd';

const SHORTCUT_SECTIONS = [
  {
    title: 'Global',
    shortcuts: [
      { keys: [`${modKey}+K`], description: 'Open command palette' },
      { keys: ['?'], description: 'Show keyboard shortcuts' },
      { keys: ['Esc'], description: 'Close overlays' },
      { keys: ['Alt+Shift+N'], description: 'Focus the newest notification' },
    ],
  },
  {
    title: 'Command Palette (when open)',
    shortcuts: [
      { keys: ['\u2191', '\u2193'], description: 'Navigate commands and results' },
      { keys: ['Enter'], description: 'Go to page, run action, or open result' },
      { keys: ['Esc'], description: 'Close palette' },
    ],
  },
  {
    title: 'Dashboard Arrange (when a move or resize handle is focused)',
    shortcuts: [
      { keys: ['Enter', 'Space'], description: 'Grab the widget — press again to place it' },
      { keys: ['←', '→'], description: 'Move a column, or resize by a column' },
      { keys: ['↑', '↓'], description: 'Move up or down the order, or resize by a row' },
      { keys: ['Esc'], description: 'Put the widget back where it was' },
    ],
  },
  {
    title: 'OpenWorld',
    shortcuts: [
      { keys: ['W', 'A', 'S', 'D'], description: 'Move around' },
      { keys: ['Tab'], description: 'Toggle mode' },
      { keys: ['E'], description: 'Interact with building' },
    ],
  },
  {
    // The terminal keeps Tab for shell completion, so the way back out is a
    // backtab — see useShellSession's attachCustomKeyEventHandler.
    title: 'Shell',
    shortcuts: [
      { keys: ['Shift+Tab'], description: 'Move focus out of the terminal' },
    ],
  },
];


export default function KeyboardHelp() {
  const { open, setOpen } = useKeyboardHelp();
  const dialogRef = useRef(null);
  const closeButtonRef = useRef(null);
  const previousFocusRef = useRef(null);

  const close = useCallback(() => setOpen(false), [setOpen]);

  // Lock body scroll when open
  useScrollLock(open);

  // Focus management: capture previous focus, focus close button on open, restore on close
  useEffect(() => {
    if (open) {
      previousFocusRef.current = document.activeElement;
      // Defer focus to after portal render
      requestAnimationFrame(() => closeButtonRef.current?.focus());
    } else if (previousFocusRef.current) {
      previousFocusRef.current.focus();
      previousFocusRef.current = null;
    }
  }, [open]);

  // Focus trap: keep Tab/Shift+Tab within the dialog
  const handleKeyDown = useCallback((e) => {
    if (e.key !== 'Tab') return;
    const dialog = dialogRef.current;
    if (!dialog) return;
    const focusable = dialog.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
    if (focusable.length === 0) return;
    const first = focusable[0];
    const last = focusable[focusable.length - 1];
    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault();
      last.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault();
      first.focus();
    }
  }, []);

  return (
    <Modal
      open={open}
      onClose={close}
      // Modal installs bubble-phase keydown listeners on BOTH `document`
      // and `window`. Its document listener is registered at module load
      // (before useKeyboardHelp's mount-time effect), so it fires first as
      // the top-most-modal dispatch and calls our `close`. The
      // `stopImmediatePropagation` then blocks useKeyboardHelp's later-
      // registered document listener — but the result is identical
      // (`setOpen(false)`), so the redundancy is harmless.
      size="md"
      align="top"
      usePortal
      zIndexClassName="z-[9999]"
      backdropClassName="bg-black/60"
      ariaLabelledBy="keyboard-help-title"
      panelClassName="bg-port-card rounded-xl border border-port-border shadow-2xl overflow-hidden"
    >
      <div ref={dialogRef} onKeyDown={handleKeyDown}>
        {/* Header */}
        <div className="flex items-center justify-between px-5 py-4 border-b border-port-border">
          <div className="flex items-center gap-2.5">
            <Keyboard size={18} className="text-port-accent" />
            <h2 id="keyboard-help-title" className="text-sm font-semibold text-white">Keyboard Shortcuts</h2>
          </div>
          <button
            ref={closeButtonRef}
            onClick={close}
            className="p-1 text-gray-500 hover:text-white transition-colors rounded min-h-[44px] min-w-[44px] flex items-center justify-center"
            aria-label="Close keyboard shortcuts"
          >
            <X size={16} />
          </button>
        </div>

        {/* Sections */}
        <div className="max-h-[60vh] overflow-y-auto p-5 space-y-5">
          {SHORTCUT_SECTIONS.map(section => (
            <div key={section.title}>
              <h3 className="text-xs font-medium text-gray-400 uppercase tracking-wide mb-2.5">
                {section.title}
              </h3>
              <div className="space-y-2">
                {section.shortcuts.map((shortcut, i) => (
                  <div key={i} className="flex items-center justify-between">
                    <span className="text-sm text-gray-300">{shortcut.description}</span>
                    <div className="flex items-center gap-1">
                      {shortcut.keys.map((key, j) => (
                        <Kbd key={j}>{key}</Kbd>
                      ))}
                    </div>
                  </div>
                ))}
              </div>
            </div>
          ))}
        </div>

        {/* Footer */}
        <div className="px-5 py-3 border-t border-port-border">
          <p className="text-xs text-gray-500 text-center">
            Press <Kbd>?</Kbd> to toggle this dialog
          </p>
        </div>
      </div>
    </Modal>
  );
}