bmad-elsabro 1.0.0

package/renderer/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,249 @@
+/**
+ * useKeyboardShortcuts Hook
+ *
+ * Custom hook for managing keyboard shortcuts across the application.
+ * Provides platform-aware shortcuts (Ctrl on Windows/Linux, Cmd on macOS).
+ *
+ * Features:
+ * - Platform-specific key mappings (Ctrl/Cmd)
+ * - Dynamic shortcut registration and handling
+ * - Enable/disable individual shortcuts
+ * - Prevent default browser behavior
+ * - TypeScript type safety
+ */
+
+import { useEffect, useCallback, useRef } from 'react';
+import shortcutsData from '../data/shortcuts.json';
+
+export interface Shortcut {
+  /**
+   * Unique identifier for the shortcut
+   */
+  id: string;
+
+  /**
+   * Display name of the shortcut
+   */
+  name: string;
+
+  /**
+   * Description of what the shortcut does
+   */
+  description: string;
+
+  /**
+   * Keyboard combination for Windows/Linux (e.g., "ctrl+k")
+   */
+  key: string;
+
+  /**
+   * Keyboard combination for macOS (e.g., "cmd+k")
+   */
+  keyMac: string;
+
+  /**
+   * Category for grouping shortcuts
+   */
+  category: string;
+
+  /**
+   * Whether the shortcut is enabled
+   */
+  enabled: boolean;
+}
+
+export interface ShortcutHandler {
+  /**
+   * Callback function to execute when shortcut is triggered
+   */
+  (event: KeyboardEvent): void;
+}
+
+export interface UseKeyboardShortcutsReturn {
+  /**
+   * All available shortcuts
+   */
+  shortcuts: Shortcut[];
+
+  /**
+   * Register a handler for a specific shortcut ID
+   */
+  register: (shortcutId: string, handler: ShortcutHandler) => void;
+
+  /**
+   * Unregister a handler for a specific shortcut ID
+   */
+  unregister: (shortcutId: string) => void;
+
+  /**
+   * Check if a keyboard event matches a specific shortcut
+   */
+  matches: (event: KeyboardEvent, shortcutId: string) => boolean;
+
+  /**
+   * Get the appropriate key combination for the current platform
+   */
+  getKey: (shortcut: Shortcut) => string;
+}
+
+/**
+ * Detect if the current platform is macOS
+ */
+const isMac = (): boolean => {
+  if (typeof window === 'undefined') return false;
+  return /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+};
+
+/**
+ * Normalize key name for comparison
+ */
+const normalizeKey = (key: string): string => {
+  return key.toLowerCase().trim();
+};
+
+/**
+ * Parse a shortcut key string into components
+ * Examples: "ctrl+k" -> { ctrl: true, key: 'k' }
+ *           "cmd+shift+t" -> { cmd: true, shift: true, key: 't' }
+ */
+interface ParsedShortcut {
+  ctrl: boolean;
+  shift: boolean;
+  alt: boolean;
+  meta: boolean;
+  key: string;
+}
+
+const parseShortcutKey = (shortcutKey: string): ParsedShortcut => {
+  const parts = shortcutKey.toLowerCase().split('+').map(p => p.trim());
+
+  return {
+    ctrl: parts.includes('ctrl'),
+    shift: parts.includes('shift'),
+    alt: parts.includes('alt'),
+    meta: parts.includes('cmd') || parts.includes('meta'),
+    key: normalizeKey(parts[parts.length - 1]),
+  };
+};
+
+/**
+ * Check if a keyboard event matches a shortcut configuration
+ */
+const matchesShortcut = (event: KeyboardEvent, shortcutKey: string): boolean => {
+  const parsed = parseShortcutKey(shortcutKey);
+  const eventKey = normalizeKey(event.key);
+
+  // Handle special keys
+  let keyToMatch = parsed.key;
+  if (keyToMatch === '`' || keyToMatch === 'backtick') {
+    keyToMatch = '`';
+  }
+  if (keyToMatch === 'escape' || keyToMatch === 'esc') {
+    keyToMatch = 'escape';
+  }
+
+  // Check if all modifiers and the key match
+  return (
+    (parsed.ctrl === (event.ctrlKey || (isMac() && parsed.meta && event.metaKey))) &&
+    (parsed.shift === event.shiftKey) &&
+    (parsed.alt === event.altKey) &&
+    (parsed.meta === (!isMac() ? false : event.metaKey)) &&
+    (eventKey === keyToMatch || event.key === keyToMatch)
+  );
+};
+
+/**
+ * Custom hook for keyboard shortcuts management
+ *
+ * @example
+ * ```tsx
+ * const { register, unregister, shortcuts } = useKeyboardShortcuts();
+ *
+ * useEffect(() => {
+ *   register('toggle-sidebar', (event) => {
+ *     event.preventDefault();
+ *     setSidebarOpen(prev => !prev);
+ *   });
+ *
+ *   return () => unregister('toggle-sidebar');
+ * }, [register, unregister]);
+ * ```
+ */
+export const useKeyboardShortcuts = (): UseKeyboardShortcutsReturn => {
+  const shortcuts = shortcutsData.shortcuts as Shortcut[];
+  const handlersRef = useRef<Map<string, ShortcutHandler>>(new Map());
+
+  /**
+   * Get the appropriate key combination for the current platform
+   */
+  const getKey = useCallback((shortcut: Shortcut): string => {
+    return isMac() ? shortcut.keyMac : shortcut.key;
+  }, []);
+
+  /**
+   * Check if a keyboard event matches a specific shortcut
+   */
+  const matches = useCallback((event: KeyboardEvent, shortcutId: string): boolean => {
+    const shortcut = shortcuts.find(s => s.id === shortcutId);
+    if (!shortcut || !shortcut.enabled) return false;
+
+    const key = getKey(shortcut);
+    return matchesShortcut(event, key);
+  }, [shortcuts, getKey]);
+
+  /**
+   * Register a handler for a specific shortcut ID
+   */
+  const register = useCallback((shortcutId: string, handler: ShortcutHandler): void => {
+    handlersRef.current.set(shortcutId, handler);
+  }, []);
+
+  /**
+   * Unregister a handler for a specific shortcut ID
+   */
+  const unregister = useCallback((shortcutId: string): void => {
+    handlersRef.current.delete(shortcutId);
+  }, []);
+
+  /**
+   * Global keyboard event handler
+   */
+  const handleKeyDown = useCallback((event: KeyboardEvent): void => {
+    // Check each registered handler
+    handlersRef.current.forEach((handler, shortcutId) => {
+      const shortcut = shortcuts.find(s => s.id === shortcutId);
+      if (!shortcut || !shortcut.enabled) return;
+
+      const key = getKey(shortcut);
+      if (matchesShortcut(event, key)) {
+        // Prevent default browser behavior for registered shortcuts
+        event.preventDefault();
+        event.stopPropagation();
+
+        // Call the registered handler
+        handler(event);
+      }
+    });
+  }, [shortcuts, getKey]);
+
+  /**
+   * Set up global keyboard listener
+   */
+  useEffect(() => {
+    window.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+      window.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [handleKeyDown]);
+
+  return {
+    shortcuts,
+    register,
+    unregister,
+    matches,
+    getKey,
+  };
+};
+
+export default useKeyboardShortcuts;

package/renderer/hooks/useNotifications.ts

@@ -0,0 +1,267 @@
+/**
+ * useNotifications Hook
+ *
+ * Custom hook for managing application-wide notifications.
+ * Provides methods to show, dismiss, and clear notifications.
+ *
+ * Features:
+ * - Multiple notification types (success, error, warning, info)
+ * - Auto-dismiss with configurable timeout
+ * - Manual dismissal
+ * - Notification queue management
+ * - Unique ID generation
+ */
+
+import { useState, useCallback, useRef } from 'react';
+
+export type NotificationType = 'success' | 'error' | 'warning' | 'info';
+
+export interface Notification {
+  /**
+   * Unique identifier for the notification
+   */
+  id: string;
+
+  /**
+   * Type of notification (affects styling and icon)
+   */
+  type: NotificationType;
+
+  /**
+   * Main notification message
+   */
+  message: string;
+
+  /**
+   * Optional detailed description
+   */
+  description?: string;
+
+  /**
+   * Auto-dismiss timeout in milliseconds (0 = no auto-dismiss)
+   * @default 5000
+   */
+  duration?: number;
+
+  /**
+   * Timestamp when notification was created
+   */
+  timestamp: Date;
+
+  /**
+   * Whether the notification can be manually dismissed
+   * @default true
+   */
+  dismissible?: boolean;
+
+  /**
+   * Optional action button
+   */
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+}
+
+export interface UseNotificationsReturn {
+  /**
+   * Array of active notifications
+   */
+  notifications: Notification[];
+
+  /**
+   * Show a notification
+   */
+  notify: (
+    type: NotificationType,
+    message: string,
+    options?: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>>
+  ) => string;
+
+  /**
+   * Show a success notification
+   */
+  success: (message: string, options?: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>>) => string;
+
+  /**
+   * Show an error notification
+   */
+  error: (message: string, options?: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>>) => string;
+
+  /**
+   * Show a warning notification
+   */
+  warning: (message: string, options?: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>>) => string;
+
+  /**
+   * Show an info notification
+   */
+  info: (message: string, options?: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>>) => string;
+
+  /**
+   * Dismiss a specific notification by ID
+   */
+  dismiss: (id: string) => void;
+
+  /**
+   * Clear all notifications
+   */
+  clearAll: () => void;
+}
+
+/**
+ * Generate a unique notification ID
+ */
+const generateId = (): string => {
+  return `notification-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+};
+
+/**
+ * Custom hook for notification management
+ *
+ * @example
+ * ```tsx
+ * const { notifications, success, error, dismiss } = useNotifications();
+ *
+ * // Show success notification
+ * success('Operation completed successfully!');
+ *
+ * // Show error with custom duration
+ * error('Something went wrong', { duration: 10000 });
+ *
+ * // Show notification with action
+ * notify('info', 'New update available', {
+ *   action: {
+ *     label: 'Update Now',
+ *     onClick: () => handleUpdate()
+ *   }
+ * });
+ * ```
+ */
+export const useNotifications = (): UseNotificationsReturn => {
+  const [notifications, setNotifications] = useState<Notification[]>([]);
+  const timeoutsRef = useRef<Map<string, NodeJS.Timeout>>(new Map());
+
+  /**
+   * Schedule auto-dismiss for a notification
+   */
+  const scheduleAutoDismiss = useCallback((id: string, duration: number) => {
+    if (duration > 0) {
+      const timeout = setTimeout(() => {
+        dismiss(id);
+      }, duration);
+
+      timeoutsRef.current.set(id, timeout);
+    }
+  }, []);
+
+  /**
+   * Show a notification
+   */
+  const notify = useCallback(
+    (
+      type: NotificationType,
+      message: string,
+      options: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>> = {}
+    ): string => {
+      const id = generateId();
+      const duration = options.duration !== undefined ? options.duration : 5000;
+
+      const notification: Notification = {
+        id,
+        type,
+        message,
+        timestamp: new Date(),
+        duration,
+        dismissible: options.dismissible !== undefined ? options.dismissible : true,
+        ...options,
+      };
+
+      setNotifications((prev) => [...prev, notification]);
+
+      // Schedule auto-dismiss
+      scheduleAutoDismiss(id, duration);
+
+      return id;
+    },
+    [scheduleAutoDismiss]
+  );
+
+  /**
+   * Dismiss a specific notification
+   */
+  const dismiss = useCallback((id: string) => {
+    setNotifications((prev) => prev.filter((n) => n.id !== id));
+
+    // Clear timeout if exists
+    const timeout = timeoutsRef.current.get(id);
+    if (timeout) {
+      clearTimeout(timeout);
+      timeoutsRef.current.delete(id);
+    }
+  }, []);
+
+  /**
+   * Clear all notifications
+   */
+  const clearAll = useCallback(() => {
+    setNotifications([]);
+
+    // Clear all timeouts
+    timeoutsRef.current.forEach((timeout) => clearTimeout(timeout));
+    timeoutsRef.current.clear();
+  }, []);
+
+  /**
+   * Helper method for success notifications
+   */
+  const success = useCallback(
+    (message: string, options?: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>>) => {
+      return notify('success', message, options);
+    },
+    [notify]
+  );
+
+  /**
+   * Helper method for error notifications
+   */
+  const error = useCallback(
+    (message: string, options?: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>>) => {
+      return notify('error', message, { duration: 0, ...options }); // Errors don't auto-dismiss by default
+    },
+    [notify]
+  );
+
+  /**
+   * Helper method for warning notifications
+   */
+  const warning = useCallback(
+    (message: string, options?: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>>) => {
+      return notify('warning', message, options);
+    },
+    [notify]
+  );
+
+  /**
+   * Helper method for info notifications
+   */
+  const info = useCallback(
+    (message: string, options?: Partial<Omit<Notification, 'id' | 'type' | 'message' | 'timestamp'>>) => {
+      return notify('info', message, options);
+    },
+    [notify]
+  );
+
+  return {
+    notifications,
+    notify,
+    success,
+    error,
+    warning,
+    info,
+    dismiss,
+    clearAll,
+  };
+};
+
+export default useNotifications;

package/renderer/hooks/useTheme.ts

@@ -0,0 +1,149 @@
+/**
+ * useTheme Hook
+ *
+ * Custom hook for managing dark/light theme with localStorage persistence.
+ * Automatically applies theme class to document root and syncs with system preferences.
+ *
+ * Features:
+ * - Dark/light theme toggle
+ * - localStorage persistence
+ * - Automatic system theme detection
+ * - Document root class management
+ */
+
+import { useState, useEffect } from 'react';
+
+export type Theme = 'light' | 'dark';
+
+export interface UseThemeReturn {
+  /**
+   * Current theme value
+   */
+  theme: Theme;
+
+  /**
+   * Toggle between light and dark theme
+   */
+  toggleTheme: () => void;
+
+  /**
+   * Set a specific theme
+   */
+  setTheme: (theme: Theme) => void;
+}
+
+const STORAGE_KEY = 'bmad-studio-theme';
+
+/**
+ * Get the system's preferred color scheme
+ */
+const getSystemTheme = (): Theme => {
+  if (typeof window === 'undefined') return 'dark';
+
+  return window.matchMedia('(prefers-color-scheme: dark)').matches
+    ? 'dark'
+    : 'light';
+};
+
+/**
+ * Get the initial theme from localStorage or system preference
+ */
+const getInitialTheme = (): Theme => {
+  if (typeof window === 'undefined') return 'dark';
+
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'light' || stored === 'dark') {
+      return stored;
+    }
+  } catch (error) {
+    // localStorage might not be available
+  }
+
+  return getSystemTheme();
+};
+
+/**
+ * Apply theme class to document root
+ */
+const applyTheme = (theme: Theme): void => {
+  if (typeof document === 'undefined') return;
+
+  const root = document.documentElement;
+
+  if (theme === 'dark') {
+    root.classList.add('dark');
+  } else {
+    root.classList.remove('dark');
+  }
+};
+
+/**
+ * Custom hook for theme management
+ *
+ * @example
+ * ```tsx
+ * const { theme, toggleTheme, setTheme } = useTheme();
+ *
+ * return (
+ *   <button onClick={toggleTheme}>
+ *     Current theme: {theme}
+ *   </button>
+ * );
+ * ```
+ */
+export const useTheme = (): UseThemeReturn => {
+  const [theme, setThemeState] = useState<Theme>(getInitialTheme);
+
+  // Apply theme on mount and when it changes
+  useEffect(() => {
+    applyTheme(theme);
+
+    try {
+      localStorage.setItem(STORAGE_KEY, theme);
+    } catch (error) {
+      // localStorage might not be available
+    }
+  }, [theme]);
+
+  // Listen for system theme changes
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+
+    const handleChange = (e: MediaQueryListEvent) => {
+      // Only update if user hasn't set a preference
+      try {
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (!stored) {
+          setThemeState(e.matches ? 'dark' : 'light');
+        }
+      } catch (error) {
+        // localStorage might not be available
+      }
+    };
+
+    mediaQuery.addEventListener('change', handleChange);
+
+    return () => {
+      mediaQuery.removeEventListener('change', handleChange);
+    };
+  }, []);
+
+  const setTheme = (newTheme: Theme) => {
+    setThemeState(newTheme);
+  };
+
+  const toggleTheme = () => {
+    setThemeState((prev) => (prev === 'dark' ? 'light' : 'dark'));
+  };
+
+  return {
+    theme,
+    toggleTheme,
+    setTheme,
+  };
+};
+
+export default useTheme;