PROJECT OVERVIEW:
This project aims to create a single-page web application (SPA) that serves as a development tool for 'Lisette', a niche programming language inspired by Rust and designed to compile into Go. The core value proposition is to enable developers to leverage Rust-like features (algebraic data types, pattern matching, immutability by default, no nil, Hindley-Milner type system) while compiling to the efficient and widely-used Go ecosystem. This tool will provide a convenient web-based interface for writing, compiling, and integrating Lisette code with Go.
TECH STACK:
- Frontend Framework: React (using Vite for fast development server and build process)
- Styling: Tailwind CSS for utility-first styling and rapid UI development
- State Management: Zustand for simple and performant global state management
- Code Editor Component: Monaco Editor (the core of VS Code) for a rich code editing experience with syntax highlighting and error reporting.
- Routing: React Router DOM for handling different views within the SPA (e.g., editor, documentation, settings).
- Build Tool: Vite
CORE FEATURES:
1. **Lisette Code Editor:**
* **User Flow:** User lands on the page, sees an editor pane pre-populated with a Lisette example. They can type, edit, and format Lisette code. The editor should provide syntax highlighting for Lisette keywords, types, and structures. It should also display errors inline as the user types or upon compilation attempt.
* **Details:** Integrate the Monaco Editor. Implement a custom language definition for Lisette within Monaco to enable syntax highlighting and basic error diagnostics. Provide a toolbar with 'Compile', 'Clear', and 'Format' actions.
2. **Lisette to Go Compiler/Transpiler:**
* **User Flow:** After writing Lisette code, the user clicks the 'Compile' button. The application sends the Lisette code to a backend service (simulated for MVP, or a simple WebAssembly-based transpiler if feasible for frontend-only). The service returns the equivalent Go code or any compilation errors. The Go code is then displayed in a separate output pane.
* **Details:** For MVP, the compilation logic might be simplified or mocked. A true implementation would require a Lisette compiler. The output pane should display the generated Go code clearly, with syntax highlighting for Go.
3. **Go Ecosystem Integration Snippets:**
* **User Flow:** Users can select common Go packages (e.g., 'fmt', 'io', 'os') to import. The tool can then show how to use these packages within the generated Go code, based on the Lisette input. This demonstrates interoperability.
* **Details:** Provide pre-defined templates or suggestions for integrating standard Go libraries. For example, showing how a Lisette `load_config` function translates to Go using `os` and `io` packages, including error handling.
4. **Error Reporting & Diagnostics:**
* **User Flow:** If the Lisette code is invalid or the compilation fails, clear error messages should be displayed, ideally linked to the specific line in the editor. The Go output pane should also show any Go-level compilation errors if the transpiled code is faulty.
* **Details:** Leverage Monaco Editor's diagnostic API. Display errors in a dedicated 'Errors' panel or inline within the editor.
5. **Example Library:**
* **User Flow:** A sidebar or dropdown allows users to load pre-written Lisette examples (e.g., 'Enums & Pattern Matching', 'Structs & Impl', 'Expression Oriented'). This helps new users quickly understand Lisette's capabilities.
* **Details:** Store example code snippets as JSON or directly in the code. Allow users to load them into the editor with one click.
UI/UX DESIGN:
- **Layout:** A two-column layout is recommended. The left column contains the Lisette code editor and potentially a sidebar for examples/documentation. The right column displays the compiled Go code and any errors. A top toolbar for global actions (Compile, Clear, Settings). The layout should be responsive, collapsing to a single column or stacking elements on smaller screens.
- **Color Palette:** Primary: Dark grey/black for code editors and background (developer-focused aesthetic). Accent: A vibrant color (e.g., teal, electric blue, or orange) for UI elements like buttons, active states, and highlights. Secondary: Light grey for borders, dividers, and secondary text.
- **Typography:** Monospace font (e.g., 'Fira Code', 'JetBrains Mono') for code editors. A clean sans-serif font (e.g., 'Inter', 'Roboto') for UI text and labels.
- **Responsive Design:** Utilize Tailwind CSS's responsive modifiers (sm:, md:, lg:, xl:). Ensure usability across desktop, tablet, and mobile devices. Editor panes should resize gracefully.
COMPONENT BREAKDOWN:
- **`App.tsx`**: Main application component. Handles routing, overall layout structure, and theme management.
- Props: None
- Responsibility: Orchestrates the main components, sets up routing.
- **`EditorPane.tsx`**: Container for the Lisette code editor.
- Props: `initialCode` (string), `onCodeChange` (function), `errors` (array of diagnostic objects)
- Responsibility: Initializes and manages the Monaco Editor instance, displays inline errors, handles code changes.
- **`OutputPane.tsx`**: Container for the compiled Go code and error messages.
- Props: `goCode` (string), `errors` (array of diagnostic objects)
- Responsibility: Displays the generated Go code with syntax highlighting, shows compilation/runtime errors.
- **`Toolbar.tsx`**: Contains global action buttons (Compile, Clear, Load Example).
- Props: `onCompile` (function), `onClear` (function), `onLoadExample` (function)
- Responsibility: Provides user controls for core actions.
- **`ExampleSelector.tsx`**: Component to browse and load example Lisette code snippets.
- Props: `onSelectExample` (function)
- Responsibility: Lists available examples, handles selection.
- **`CodeEditor.tsx`**: Wrapper around the Monaco Editor instance.
- Props: `language` (string), `value` (string), `onChange` (function), `options` (object), `editorDidMount` (function), `theme` (string)
- Responsibility: Core logic for integrating and configuring Monaco Editor.
DATA MODEL:
- **State:** Managed using Zustand.
- `codeState`: {
`lisetteCode`: string,
`goCode`: string,
`lisetteErrors`: Array<{ message: string, severity: 'error' | 'warning', startLine: number, startChar: number, endLine: number, endChar: number }>,
`goErrors`: Array<{ message: string, severity: 'error' | 'warning' }>
}
- `editorState`: {
`currentTheme`: 'dark' | 'light',
`fontSize`: number
}
- `examplesState`: { `examples`: Array<{ name: string, code: string }> }
- **Mock Data:**
- `MockLisetteCode`: Example Lisette code string for initial editor state.
- `MockGoCode`: Example Go code string generated from `MockLisetteCode`.
- `MockLisetteErrors`: Sample error objects for invalid Lisette code.
- `MockGoErrors`: Sample error objects for invalid Go code.
- `MockExamples`: Array of objects, each with `name` and `code` properties for the example selector.
ANIMATIONS & INTERACTIONS:
- **Hover Effects:** Subtle background color changes on toolbar buttons and example links when hovered.
- **Transitions:** Smooth transitions for panel resizing, sidebar opening/closing (if implemented), and theme changes.
- **Loading States:** Display a subtle loading spinner or skeleton screen when compilation is in progress.
- **Micro-interactions:** Visual feedback when copying Go code (e.g., a small checkmark animation).
- **Syntax Highlighting:** Implemented via Monaco Editor's tokenization.
EDGE CASES:
- **Empty State:** Editor should show placeholder text or a welcome message when empty. Output pane should display a message indicating no code has been compiled yet.
- **Error Handling:** Gracefully handle network errors if a backend compiler is used. Display user-friendly messages for invalid input or unexpected failures. Ensure inline error markers are accurately placed.
- **Validation:** Basic client-side checks for input types. The primary validation happens during the compilation step.
- **Accessibility (a11y):** Ensure proper ARIA attributes are used for interactive elements. Keyboard navigation should be fully supported. Sufficient color contrast for text and UI elements.
- **Large Codebases:** Consider performance implications if users attempt to compile very large Lisette files. Debounce editor input to avoid excessive recompilation attempts.
SAMPLE DATA:
```json
[
{
"name": "Basic Struct & Function",
"code": "import \"go:fmt\"\n\nstruct Point { x: float64, y: float64 }\n\nimpl Point {\n fn distance(self, other: Point) -> float64 {\n let dx = self.x - other.x\n let dy = self.y - other.y\n math.Sqrt(dx*dx + dy*dy) // Assuming math import\n }\n}\n\nfn main() {\n let p1 = Point { x: 0.0, y: 0.0 }\n let p2 = Point { x: 3.0, y: 4.0 }\n fmt.Println(f\"Distance: {p1.distance(p2)}\")\n}"
},
{
"name": "Enum & Pattern Matching",
"code": "import \"go:fmt\"\n\nenum Message {\n Quit,\n Write(string),\n Move { x: int, y: int }\n}\n\nfn handle(msg: Message) -> string {\n match msg {\n Message.Quit => \"quitting\",\n Message.Write(text) => f\"writing: {text}\",\n Message.Move { x, y } => f\"moving to ({x}, {y})\",\n }\n}\n\nfn main() {\n fmt.Println(handle(Message.Write(\"hello\")))\n fmt.Println(handle(Message.Move { x: 10, y: 20 }))\n fmt.Println(handle(Message.Quit))\n}"
},
{
"name": "Result Type Example",
"code": "import \"go:fmt\", \"go:os\"\n\nstruct Cfg { setting: string }\n\nfn load_config(path: string) -> Result<Cfg, error> {\n let file = os.Open(path)? // Use ? for error propagation\n defer file.Close()\n let data = io.ReadAll(file)? // Assume io is imported\n parse_yaml(data) // Assume parse_yaml exists\n}\n\nfn main() {\n match load_config(\"app.yaml\") {\n Ok(config) => fmt.Println(\"Config loaded: \", config.setting),\n Err(e) => fmt.Println(\"Error loading config: \", e),\n }\n}"
}
]
```
DEPLOYMENT NOTES:
- **Build Command:** `npm run build` or `yarn build` (using Vite).
- **Environment Variables:** Use `.env` files for configuration (e.g., API endpoints if a backend is used, though MVP is likely frontend-only simulation). Vite uses `VITE_` prefix for client-side variables.
- **Performance Optimizations:** Code splitting with React Router. Lazy loading components. Optimize Monaco Editor initialization. Ensure efficient state updates with Zustand. Minify production builds.
- **Static Hosting:** The SPA can be easily deployed on static hosting platforms like Vercel, Netlify, GitHub Pages.
- **WebAssembly (Optional):** For a true compiler experience without a backend, the Lisette compiler could potentially be compiled to WebAssembly. This adds complexity but enables offline use and eliminates backend server costs.