bmad-elsabro 1.0.0

package/renderer/components/test-center/ELI5Guide.tsx

@@ -0,0 +1,521 @@
+/**
+ * ELI5Guide Component
+ *
+ * "Explain Like I'm 5" guidance system for the Test Center.
+ * Displays simple, beginner-friendly explanations for testing concepts.
+ *
+ * Features:
+ * - Click-to-open help icon trigger
+ * - Modal overlay with detailed explanations
+ * - Examples and analogies for better understanding
+ * - Related topics navigation
+ * - Dark/light theme support
+ * - Keyboard navigation (Esc to close)
+ * - Accessible with ARIA labels
+ *
+ * Usage:
+ * ```tsx
+ * <ELI5Guide topic="test-scenarios" />
+ * <ELI5Guide topic="assertions" inline />
+ * ```
+ *
+ * @module renderer/components/test-center/ELI5Guide
+ */
+
+import React, { useState, useEffect, useCallback, useRef } from 'react';
+import testingGuidesData from '../../data/testing-guides.json';
+
+/**
+ * Testing guide data structure
+ */
+export interface TestingGuide {
+  /**
+   * Unique identifier for the guide
+   */
+  id: string;
+
+  /**
+   * Guide topic/title
+   */
+  topic: string;
+
+  /**
+   * Short one-line description
+   */
+  shortDescription: string;
+
+  /**
+   * Main ELI5 explanation
+   */
+  explanation: string;
+
+  /**
+   * Examples to illustrate the concept
+   */
+  examples?: Array<string | Record<string, any>>;
+
+  /**
+   * Steps for processes
+   */
+  steps?: Array<Record<string, any>>;
+
+  /**
+   * Comparison data
+   */
+  comparison?: Array<Record<string, any>>;
+
+  /**
+   * Visualization hints
+   */
+  visualization?: Record<string, string>;
+
+  /**
+   * Benefits list
+   */
+  benefits?: string[];
+
+  /**
+   * Common mistakes
+   */
+  commonMistakes?: string[];
+
+  /**
+   * Guide category
+   */
+  category: 'basics' | 'concepts' | 'tools' | 'metrics' | 'advanced' | 'troubleshooting';
+
+  /**
+   * Related topic IDs
+   */
+  relatedTopics?: string[];
+}
+
+/**
+ * Props for ELI5Guide component
+ */
+export interface ELI5GuideProps {
+  /**
+   * Topic ID to display (matches guide.id in testing-guides.json)
+   */
+  topic: string;
+
+  /**
+   * Display inline instead of as an icon
+   * @default false
+   */
+  inline?: boolean;
+
+  /**
+   * Custom icon to display
+   * @default "?"
+   */
+  icon?: string;
+
+  /**
+   * Position of the help icon
+   * @default "right"
+   */
+  iconPosition?: 'left' | 'right' | 'top';
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+
+  /**
+   * Callback when guide is opened
+   */
+  onOpen?: () => void;
+
+  /**
+   * Callback when guide is closed
+   */
+  onClose?: () => void;
+}
+
+/**
+ * ELI5Guide Component
+ *
+ * Displays "Explain Like I'm 5" guidance for testing concepts.
+ * Can be triggered by clicking a help icon or displayed inline.
+ */
+const ELI5Guide: React.FC<ELI5GuideProps> = ({
+  topic,
+  inline = false,
+  icon = '?',
+  iconPosition = 'right',
+  className = '',
+  onOpen,
+  onClose,
+}) => {
+  const [isOpen, setIsOpen] = useState(inline);
+  const [currentTopic, setCurrentTopic] = useState(topic);
+  const modalRef = useRef<HTMLDivElement>(null);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  // Find the guide data for the current topic
+  const guide: TestingGuide | undefined = testingGuidesData.guides.find(
+    (g) => g.id === currentTopic
+  );
+
+  /**
+   * Open the guide modal
+   */
+  const handleOpen = useCallback(() => {
+    setIsOpen(true);
+    onOpen?.();
+  }, [onOpen]);
+
+  /**
+   * Close the guide modal
+   */
+  const handleClose = useCallback(() => {
+    setIsOpen(false);
+    setCurrentTopic(topic); // Reset to original topic
+    onClose?.();
+    buttonRef.current?.focus(); // Return focus to trigger button
+  }, [topic, onClose]);
+
+  /**
+   * Navigate to a related topic
+   */
+  const handleNavigateToTopic = useCallback((topicId: string) => {
+    setCurrentTopic(topicId);
+  }, []);
+
+  /**
+   * Handle keyboard events (Esc to close)
+   */
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && isOpen && !inline) {
+        handleClose();
+      }
+    };
+
+    if (isOpen && !inline) {
+      document.addEventListener('keydown', handleKeyDown);
+      // Trap focus in modal
+      modalRef.current?.focus();
+    }
+
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isOpen, inline, handleClose]);
+
+  /**
+   * Update current topic when prop changes
+   */
+  useEffect(() => {
+    setCurrentTopic(topic);
+  }, [topic]);
+
+  // If guide not found, don't render anything
+  if (!guide) {
+    console.warn(`ELI5Guide: No guide found for topic "${currentTopic}"`);
+    return null;
+  }
+
+  /**
+   * Render the guide content
+   */
+  const renderGuideContent = () => {
+    return (
+      <div className="space-y-4">
+        {/* Topic header */}
+        <div>
+          <h3 className="text-xl font-bold text-gray-900 dark:text-white mb-2">
+            💡 {guide.topic}
+          </h3>
+          <p className="text-sm text-gray-600 dark:text-gray-400">
+            {guide.shortDescription}
+          </p>
+        </div>
+
+        {/* Main explanation */}
+        <div className="bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg p-4">
+          <p className="text-sm text-blue-900 dark:text-blue-100 leading-relaxed">
+            {guide.explanation}
+          </p>
+        </div>
+
+        {/* Examples */}
+        {guide.examples && guide.examples.length > 0 && (
+          <div>
+            <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">
+              📚 Examples
+            </h4>
+            <div className="space-y-2">
+              {guide.examples.map((example, index) => {
+                // Handle both string and object examples
+                if (typeof example === 'string') {
+                  return (
+                    <div
+                      key={index}
+                      className="flex items-start gap-2 text-sm text-gray-700 dark:text-gray-300"
+                    >
+                      <span className="text-green-600 dark:text-green-400 mt-0.5">✓</span>
+                      <span>{example}</span>
+                    </div>
+                  );
+                } else {
+                  return (
+                    <div
+                      key={index}
+                      className="p-3 bg-gray-50 dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700"
+                    >
+                      {example.emoji && <span className="text-xl mr-2">{example.emoji}</span>}
+                      {example.type && (
+                        <div className="font-semibold text-gray-900 dark:text-white mb-1">
+                          {example.type}
+                        </div>
+                      )}
+                      {example.description && (
+                        <div className="text-sm text-gray-700 dark:text-gray-300 mb-1">
+                          {example.description}
+                        </div>
+                      )}
+                      {example.example && (
+                        <div className="text-xs text-gray-600 dark:text-gray-400 italic">
+                          Example: {example.example}
+                        </div>
+                      )}
+                      {example.bestFor && (
+                        <div className="text-xs text-gray-600 dark:text-gray-400 mt-1">
+                          Best for: {example.bestFor}
+                        </div>
+                      )}
+                    </div>
+                  );
+                }
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Steps (for processes like TDD) */}
+        {guide.steps && guide.steps.length > 0 && (
+          <div>
+            <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">
+              📋 Steps
+            </h4>
+            <div className="space-y-2">
+              {guide.steps.map((step, index) => (
+                <div
+                  key={index}
+                  className="flex items-start gap-3 p-3 bg-gray-50 dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700"
+                >
+                  {step.emoji && <span className="text-2xl">{step.emoji}</span>}
+                  <div className="flex-1">
+                    <div className="font-semibold text-gray-900 dark:text-white">
+                      {step.step && `${step.step}. `}{step.name || step.step}
+                    </div>
+                    <div className="text-sm text-gray-700 dark:text-gray-300">
+                      {step.description || step.tip}
+                    </div>
+                  </div>
+                </div>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {/* Comparison table */}
+        {guide.comparison && guide.comparison.length > 0 && (
+          <div>
+            <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">
+              ⚖️ Comparison
+            </h4>
+            <div className="overflow-x-auto">
+              <table className="w-full text-sm border-collapse">
+                <tbody>
+                  {guide.comparison.map((row, index) => (
+                    <tr key={index} className="border-b border-gray-200 dark:border-gray-700">
+                      <td className="py-2 pr-4 font-medium text-gray-900 dark:text-white">
+                        {row.aspect}
+                      </td>
+                      <td className="py-2 px-4 text-gray-700 dark:text-gray-300 bg-green-50 dark:bg-green-900/20">
+                        {row.unit}
+                      </td>
+                      <td className="py-2 pl-4 text-gray-700 dark:text-gray-300 bg-blue-50 dark:bg-blue-900/20">
+                        {row.integration}
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+            {guide.analogy && (
+              <div className="mt-2 text-sm italic text-gray-600 dark:text-gray-400">
+                💭 {guide.analogy}
+              </div>
+            )}
+          </div>
+        )}
+
+        {/* Visualization */}
+        {guide.visualization && (
+          <div>
+            <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">
+              🎨 Visual Guide
+            </h4>
+            <div className="space-y-1">
+              {Object.entries(guide.visualization).map(([key, value]) => (
+                <div
+                  key={key}
+                  className="text-sm text-gray-700 dark:text-gray-300"
+                >
+                  {value}
+                </div>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {/* Benefits */}
+        {guide.benefits && guide.benefits.length > 0 && (
+          <div>
+            <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">
+              ✨ Benefits
+            </h4>
+            <ul className="space-y-1">
+              {guide.benefits.map((benefit, index) => (
+                <li
+                  key={index}
+                  className="flex items-start gap-2 text-sm text-gray-700 dark:text-gray-300"
+                >
+                  <span className="text-green-600 dark:text-green-400 mt-0.5">+</span>
+                  <span>{benefit}</span>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+
+        {/* Common Mistakes */}
+        {guide.commonMistakes && guide.commonMistakes.length > 0 && (
+          <div>
+            <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">
+              ⚠️ Common Mistakes to Avoid
+            </h4>
+            <ul className="space-y-1">
+              {guide.commonMistakes.map((mistake, index) => (
+                <li
+                  key={index}
+                  className="flex items-start gap-2 text-sm text-gray-700 dark:text-gray-300"
+                >
+                  <span className="text-red-600 dark:text-red-400 mt-0.5">!</span>
+                  <span>{mistake}</span>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+
+        {/* Related Topics */}
+        {guide.relatedTopics && guide.relatedTopics.length > 0 && (
+          <div>
+            <h4 className="text-sm font-semibold text-gray-900 dark:text-white mb-2">
+              🔗 Related Topics
+            </h4>
+            <div className="flex flex-wrap gap-2">
+              {guide.relatedTopics.map((relatedId) => {
+                const relatedGuide = testingGuidesData.guides.find((g) => g.id === relatedId);
+                if (!relatedGuide) return null;
+                return (
+                  <button
+                    key={relatedId}
+                    onClick={() => handleNavigateToTopic(relatedId)}
+                    className="px-3 py-1.5 text-xs bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 text-gray-700 dark:text-gray-300 rounded-full transition-colors"
+                    aria-label={`Navigate to ${relatedGuide.topic}`}
+                  >
+                    {relatedGuide.topic}
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        )}
+
+        {/* Category badge */}
+        <div className="pt-4 border-t border-gray-200 dark:border-gray-700">
+          <span className="inline-block px-3 py-1 text-xs bg-purple-100 dark:bg-purple-900/30 text-purple-700 dark:text-purple-300 rounded-full">
+            Category: {guide.category}
+          </span>
+        </div>
+      </div>
+    );
+  };
+
+  /**
+   * Render inline version (no modal)
+   */
+  if (inline) {
+    return (
+      <div className={`eli5-guide-inline ${className}`}>
+        {renderGuideContent()}
+      </div>
+    );
+  }
+
+  /**
+   * Render modal version with trigger button
+   */
+  return (
+    <div className={`eli5-guide ${className}`}>
+      {/* Help icon trigger button */}
+      <button
+        ref={buttonRef}
+        onClick={handleOpen}
+        className="inline-flex items-center justify-center w-5 h-5 text-xs font-bold text-blue-600 dark:text-blue-400 bg-blue-100 dark:bg-blue-900/30 hover:bg-blue-200 dark:hover:bg-blue-800/50 rounded-full transition-colors cursor-help"
+        aria-label={`Get help about ${guide.topic}`}
+        title={guide.shortDescription}
+      >
+        {icon}
+      </button>
+
+      {/* Modal overlay */}
+      {isOpen && (
+        <div
+          className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/50 backdrop-blur-sm"
+          onClick={handleClose}
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby="eli5-guide-title"
+        >
+          {/* Modal content */}
+          <div
+            ref={modalRef}
+            onClick={(e) => e.stopPropagation()}
+            className="relative w-full max-w-2xl max-h-[90vh] overflow-y-auto bg-white dark:bg-gray-900 rounded-xl shadow-2xl border border-gray-200 dark:border-gray-700"
+            tabIndex={-1}
+          >
+            {/* Close button */}
+            <button
+              onClick={handleClose}
+              className="absolute top-4 right-4 w-8 h-8 flex items-center justify-center text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 rounded-full transition-colors"
+              aria-label="Close guide"
+            >
+              ✕
+            </button>
+
+            {/* Guide content */}
+            <div className="p-6 pr-12">
+              {renderGuideContent()}
+            </div>
+
+            {/* Footer with keyboard hint */}
+            <div className="px-6 py-3 bg-gray-50 dark:bg-gray-800 border-t border-gray-200 dark:border-gray-700 rounded-b-xl">
+              <p className="text-xs text-gray-600 dark:text-gray-400 text-center">
+                Press <kbd className="px-2 py-0.5 bg-white dark:bg-gray-700 border border-gray-300 dark:border-gray-600 rounded text-xs">Esc</kbd> to close
+              </p>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default ELI5Guide;