You are an expert AI assistant tasked with building a single-page React application (SPA) that serves as an interactive learning guide for Magit, focusing on advanced Git operations like rebasing. The application aims to simplify complex Git workflows for developers by providing visual explanations and interactive practice environments.
**1. PROJECT OVERVIEW:**
The primary goal of this application is to demystify advanced Git operations, specifically rebasing within the context of Magit. Many developers struggle with the complexities of Git, and Magit, while powerful, has a learning curve. This platform will offer a guided, visual, and interactive learning experience to empower developers to use Magit's advanced features confidently. The core value proposition is to reduce the friction associated with complex Git operations, leading to more efficient and error-free development workflows. The application will act as a "Git Master" guide, focusing initially on Magit's rebasing capabilities, inspired by user pain points expressed on platforms like Hacker News.
**2. TECH STACK:**
- **Frontend Framework:** React.js (using functional components and hooks)
- **Styling:** Tailwind CSS for rapid and utility-first styling.
- **State Management:** Zustand for simple and efficient global state management.
- **Routing:** React Router DOM for client-side navigation within the SPA.
- **UI Components:** Potentially a library like Shadcn/ui for pre-built, accessible, and customizable components, styled with Tailwind CSS.
- **Syntax Highlighting:** Prism.js or Highlight.js for code snippets.
- **Markdown Rendering:** `react-markdown` with `remark-gfm` for rendering educational content.
- **Drag and Drop (for potential future interactive features):** `react-beautiful-dnd` or similar.
- **Icons:** `react-icons` for a variety of icon options.
**3. CORE FEATURES:**
**a) Interactive Rebase Tutorial Module:**
* **User Flow:** The user navigates to the 'Rebase Tutorial' section. They are presented with a series of steps, each explaining a concept or a specific Magit command related to rebasing (e.g., `git rebase -i`, interactive mode, commit editing, squashing, rewording, dropping commits). Each step includes a concise explanation, a visual representation (e.g., diagrams of commit history before and after), and the corresponding Magit command invocation (e.g., `F3` then `r`). After the explanation, the user is prompted to perform the action in a simulated environment.
* **Details:** The tutorial will break down the process logically, starting with the basics of interactive rebase and progressing to more complex scenarios. Visual aids will be crucial. Hints will be provided contextually.
**b) Rebase Scenario Simulator:**
* **User Flow:** Users can select pre-defined rebase scenarios (e.g., 'Squash two commits', 'Reorder commits', 'Edit a commit message'). The simulator presents a mock Git history. The user then uses the application's interface (mimicking Magit commands) to manipulate the history according to the scenario's goal. The simulator provides real-time feedback on whether the actions are correct and guides them towards the solution if they get stuck. This will use mock data to represent the Git log and commit structure.
* **Details:** This feature allows hands-on practice without affecting a real repository. It will involve abstracting Git history into a manageable data structure within the app.
**c) Error & Solutions Guide:**
* **User Flow:** Users can browse a list of common rebasing errors (e.g., 'conflicts during rebase', 'non-fast-forward errors'). Each error entry provides a clear explanation of why the error occurs, how to identify it within Magit/Git, and step-by-step instructions on how to resolve it using Magit commands. Links to relevant parts of the interactive tutorial or simulator could be included.
* **Details:** This acts as a quick reference and troubleshooting guide.
**d) Magit Command Explorer (Git Log Focus):**
* **User Flow:** A dedicated section where users can explore Magit commands related to viewing and interacting with the Git log. Similar to the tutorial, it will explain commands like `lL` (log all branches), filtering by author (`-A`), date (`=u`), graph views, and diffstats. Hovering over commands or options will reveal hints and explanations.
* **Details:** This leverages the inspiration from the Hacker News post, providing a direct reference for common Magit log interactions.
**4. UI/UX DESIGN:**
* **Layout:** A clean, single-page layout with a persistent sidebar for navigation between tutorial modules, simulator, error guide, and command explorer. The main content area will display the educational material, interactive elements, or simulator interface. A top navigation bar might include global actions or user profile elements (if authentication is added later).
* **Color Palette:** A modern, developer-friendly palette. Primary colors: Dark background (e.g., `#1a1a1a` or a deep blue/purple) for a terminal-like feel. Accent colors: Vibrant but not distracting (e.g., electric blue, green, or orange) for interactive elements, highlights, and CTAs. Secondary colors: Grays for text and borders. Ensure high contrast for readability.
* **Typography:** A clean, monospace font for code snippets (e.g., 'Fira Code', 'JetBrains Mono') and a readable sans-serif font for body text (e.g., 'Inter', 'Roboto'). Clear hierarchy using font sizes and weights.
* **Responsive Design:** Mobile-first approach. The sidebar should collapse into a hamburger menu on smaller screens. Content should reflow and resize gracefully. Ensure usability on tablets and desktops.
* **Interactivity:** Clear visual cues for interactive elements (buttons, input fields). Loading states should be clearly indicated. Use subtle animations to guide the user's attention and provide feedback.
**5. DATA MODEL:**
* **State Structure (Zustand):**
* `tutorialState`: { `currentStep`: number, `steps`: TutorialStep[], `completedSteps`: Set<number> }
* `simulatorState`: { `currentScenario`: Scenario, `mockHistory`: MockCommit[], `userActions`: Action[], `isCorrect`: boolean, `feedback`: string }
* `errorGuideState`: { `selectedError`: ErrorEntry | null, `errors`: ErrorEntry[] }
* `commandExplorerState`: { `selectedCommand`: string | null, `commands`: Command[] }
* **Mock Data Formats:**
* `TutorialStep`: { `id`: number, `title`: string, `explanation`: string, `magitCommand`: string, `visualAidUrl`?: string, `simulationTask`?: object }
* `MockCommit`: { `id`: string, `hash`: string, `parentHashes`: string[], `author`: string, `date`: string, `message`: string, `diffStat`?: string }
* `Scenario`: { `id`: string, `title`: string, `description`: string, `initialHistory`: MockCommit[], `goal`: string, `steps`: object[] }
* `ErrorEntry`: { `id`: string, `title`: string, `cause`: string, `resolution`: string, `exampleCommand`: string }
* `Command`: { `name`: string, `description`: string, `magitKeybinding`: string, `options`: Option[] }
* `Option`: { `key`: string, `description`: string }
**6. COMPONENT BREAKDOWN:**
* **`App.js`:** Main application component, sets up routing, global layout, and state provider.
* **`NavigationSidebar.js`:** Handles sidebar navigation, displays links to different sections (Tutorial, Simulator, etc.). Receives navigation state and functions from `App.js`.
* Props: `activeSection`, `onNavigate`.
* **`RebaseTutorial.js`:** Main component for the tutorial section. Manages tutorial state, displays steps, and renders `StepDisplay` and `SimulationPrompt`.
* Props: `tutorialState`, `actions` (e.g., `nextStep`, `prevStep`, `submitAction`).
* **`StepDisplay.js`:** Renders a single tutorial step's content (title, explanation, visual aids).
* Props: `stepData`.
* **`SimulationPrompt.js`:** Renders the interactive simulation part for a tutorial step or a standalone scenario.
* Props: `scenarioData`, `currentActionIndex`, `onUserAction`.
* **`RebaseSimulator.js`:** Orchestrates the simulator section. Loads scenarios, manages mock history, and renders `SimulationPrompt`.
* Props: `selectedScenarioId`.
* **`ErrorGuide.js`:** Displays the list of errors and the details of a selected error.
* Props: `errors`, `selectedError`, `onSelectError`.
* **`CommandExplorer.js`:** Displays Magit commands and their explanations.
* Props: `commands`, `selectedCommand`, `onSelectCommand`.
* **`CodeSnippet.js`:** Renders syntax-highlighted code blocks.
* Props: `code`, `language`.
* **`HistoryGraph.js`:** (Future enhancement) Visualizes Git history using diagrams or graphs.
* Props: `commits`.
* **`Button.js`, `Card.js`, `Modal.js`:** Reusable UI components styled with Tailwind CSS.
**7. ANIMATIONS & INTERACTIONS:**
* **Page Transitions:** Subtle fade or slide transitions between different sections using React Router's `<Transition>` component or libraries like `Framer Motion`.
* **Hover Effects:** Slight scale-up, background color changes, or shadow lifts on interactive elements (buttons, links, cards) to indicate interactivity.
* **Loading States:** Skeleton loaders or spinners when fetching mock data or processing simulation steps. Use Tailwind CSS animations for spinners.
* **Micro-interactions:** Smooth expansion/collapse of explanation details, animated feedback (e.g., a green checkmark for correct actions, a red cross for incorrect ones) in the simulator, subtle typing animations for input fields.
* **Command Hints:** On hover or after a short delay in the command explorer, display tooltips with command descriptions.
**8. EDGE CASES:**
* **Empty States:** Display informative messages when there are no tutorials available, no errors listed, or no scenarios selected (e.g., "Start learning with our interactive rebase tutorial!").
* **Error Handling:** Gracefully handle potential errors during data loading or simulation. Display user-friendly error messages. Implement validation for any user inputs (e.g., in custom simulator commands).
* **A11y (Accessibility):** Use semantic HTML5 elements. Ensure sufficient color contrast. Add ARIA attributes where necessary. Ensure keyboard navigation is fully supported for all interactive elements. Use `alt` text for images/visual aids.
* **Simulation Reset:** Provide clear options to reset the simulator to its initial state or retry a scenario.
* **State Persistence:** Consider using `localStorage` to save progress in tutorials or simulator states, allowing users to resume later.
**9. SAMPLE DATA:**
* **`MockCommit` Example:**
```json
{
"id": "c1",
"hash": "a1b2c3d4",
"parentHashes": ["e5f6g7h8"],
"author": "Alice",
"date": "2023-10-27T10:00:00Z",
"message": "Feat: Implement user login"
}
```
* **`TutorialStep` Example:**
```json
{
"id": 1,
"title": "Interactive Rebase: The Basics",
"explanation": "Interactive rebase lets you change commit history. Use 'git rebase -i <base-commit>' to start.",
"magitCommand": "Press F3, then type 'r' followed by the base commit hash.",
"visualAidUrl": "/images/rebase-interactive-start.png",
"simulationTask": {
"type": "START_REBASE",
"baseCommit": "e5f6g7h8"
}
}
```
* **`Scenario` Example:**
```json
{
"id": "squash_two",
"title": "Squash Two Consecutive Commits",
"description": "Combine the last two commits into a single one.",
"initialHistory": [
{ "id": "c3", "hash": "1111aaaa", "parentHashes": ["2222bbbb"], "author": "Bob", "date": "...", "message": "Fix: Correct typo in README" },
{ "id": "c2", "hash": "2222bbbb", "parentHashes": ["a1b2c3d4"], "author": "Alice", "date": "...", "message": "Refactor: Improve data validation logic" },
{ "id": "c1", "hash": "a1b2c3d4", "parentHashes": [], "author": "Alice", "date": "...", "message": "Feat: Initial project setup" }
],
"goal": "Create a history with only two commits, where the second commit incorporates changes from both original last two.",
"steps": [] // Detailed steps for user interaction
}
```
* **`ErrorEntry` Example:**
```json
{
"id": "rebase_conflict_1",
"title": "Conflict During Rebase",
"cause": "The current commit being applied has conflicting changes with the target branch's content.",
"resolution": "1. Use Magit's conflict resolution tools (e.g., 'c' to continue rebase after manual merge). 2. Manually edit the conflicted files, then stage them ('s'). 3. Run 'git rebase --continue' (or equivalent Magit command).",
"exampleCommand": "c (in Magit to continue)"
}
```
* **`Command` Example:**
```json
{
"name": "Log All Branches",
"description": "View the commit log for all local branches and their remote-tracking branches.",
"magitKeybinding": "lL",
"options": [
{ "key": "-A", "description": "Filter by author" },
{ "key": "=u", "description": "Filter by date range" },
{ "key": "--graph", "description": "Show commit graph" }
]
}
```
**10. DEPLOYMENT NOTES:**
* **Build:** Use Create React App's or Vite's production build command (`npm run build` or `yarn build`).
* **Environment Variables:** Utilize `.env` files for configuration (e.g., API endpoints if external services are integrated later). Use `PUBLIC_URL` for static asset paths.
* **Performance:** Code-split components using React.lazy and Suspense for faster initial loads. Optimize image assets. Minimize bundle size by analyzing dependencies.
* **Hosting:** Deployable on static hosting platforms like Vercel, Netlify, or GitHub Pages.
* **SEO:** Implement basic SEO tags in `index.html` for discoverability, even as an SPA.
* **PWA:** Consider adding PWA capabilities (service workers, manifest file) for offline access and better mobile experience, especially for the learning content.