migration complete

2025-11-01 03:01:29 -05:00 · 2025-11-01 03:01:29 -05:00 · 88d84fee4c
commit 88d84fee4c
parent c0c1148fde
34 changed files with 4641 additions and 281 deletions
--- a/docs/languages/flutter-dart.md
+++ b/docs/languages/flutter-dart.md
@ -0,0 +1,295 @@
+# Flutter & Dart Development
+
+Complete reference for Flutter and Dart development in Neovim.
+
+## Quick Start
+
+1. Open any `.dart` file to activate Flutter tools
+2. Select device: `<Space>fd`
+3. Run app: `<Space>fr`
+4. Hot reload during development: `<Space>fh`
+
+## Essential Keymaps
+
+### App Lifecycle
+
+| Key | Command | Description |
+|-----|---------|-------------|
+| `<Space>fr` | FlutterRun | Run the app (auto-selects last used device) |
+| `<Space>fh` | FlutterReload | Hot reload (faster, preserves state) |
+| `<Space>fR` | FlutterRestart | Hot restart (full reload, resets state) |
+| `<Space>fq` | FlutterQuit | Stop the running app |
+
+**Workflow**: First time, use `<Space>fd` to select a device, then `<Space>fr` to run. Subsequent runs remember your device.
+
+### Device Management
+
+| Key | Command | Description |
+|-----|---------|-------------|
+| `<Space>fd` | FlutterDevices | List and select connected devices |
+| `<Space>fe` | FlutterEmulators | Launch an emulator |
+| `<Space>fa` | FlutterAttach | Attach to an already running app |
+| `<Space>fD` | FlutterDetach | Detach from app (keeps it running) |
+
+### Developer Tools
+
+| Key | Command | Description |
+|-----|---------|-------------|
+| `<Space>ft` | FlutterDevTools | Start Dart DevTools server |
+| `<Space>fc` | FlutterCopyProfilerUrl | Copy profiler URL to clipboard |
+| `<Space>fo` | FlutterOutlineToggle | Toggle widget tree outline |
+| `<Space>fL` | FlutterLogToggle | Show/hide application logs |
+
+**DevTools Workflow**:
+1. Run your app: `<Space>fr`
+2. Start DevTools: `<Space>ft`
+3. Copy profiler URL: `<Space>fc`
+4. Open URL in browser for full DevTools experience
+
+### Code Actions & Refactoring
+
+| Key | Command | Description |
+|-----|---------|-------------|
+| `<Space>.` | Code Actions | Quick actions (like Cmd+. in VS Code) |
+| `gra` | Code Actions | Alternative LSP keymap |
+
+**Common Code Actions**:
+- Wrap widget with Padding, Center, Column, etc.
+- Remove widget (unwrap)
+- Extract widget to new class
+- Extract method
+- Add import
+- Organize imports
+
+### LSP & Language Server
+
+| Key | Command | Description |
+|-----|---------|-------------|
+| `<Space>fl` | FlutterLspRestart | Restart Dart language server |
+| `K` | Hover | Show documentation |
+| `grd` | Go to Definition | Jump to definition |
+| `grr` | Go to References | Find all references |
+| `grn` | Rename | Rename symbol |
+
+## Flutter-Specific Features
+
+### Widget Tree Outline
+
+The outline window shows your widget tree structure:
+
+```
+<Space>fo  # Toggle outline window
+```
+
+The outline updates as you edit and shows:
+- Widget hierarchy
+- Widget types
+- Quick navigation to widgets
+
+### Closing Tags
+
+Automatically shows closing tags for deeply nested widgets:
+
+```dart
+Container(                    // Container
+  child: Column(              // Column
+    children: [
+      Text('Hello'),
+      Text('World'),
+    ],
+  ),                          // Column
+),                            // Container
+```
+
+### Color Preview
+
+Material Design colors show inline preview:
+
+```dart
+Colors.red                    # Shows red color indicator
+Color(0xFF42A5F5)            # Shows the actual color
+```
+
+### Hot Reload vs Hot Restart
+
+| Hot Reload (`<Space>fh`) | Hot Restart (`<Space>fR`) |
+|---------------------------|---------------------------|
+| Fast (< 1 second) | Slower (few seconds) |
+| Preserves app state | Resets app state |
+| UI changes only | Can handle code structure changes |
+| Use during active development | Use after changing initState, constructors |
+
+## Debugging
+
+### Debug Keymaps
+
+Available when debugging (after `<F5>` or breakpoint hit):
+
+| Key | Description |
+|-----|-------------|
+| `F5` | Start/Continue |
+| `F10` | Step over |
+| `F11` | Step into |
+| `F12` | Step out |
+| `<Space>db` | Toggle breakpoint |
+| `<Space>dB` | Conditional breakpoint |
+| `<Space>dt` | Terminate debug session |
+| `<Space>dr` | Toggle REPL |
+| `<Space>du` | Toggle debug UI |
+
+### Debug Workflow
+
+1. Set breakpoints: Position cursor, press `<Space>db`
+2. Start debugging: `F5` (launches app in debug mode)
+3. App pauses at breakpoint
+4. Inspect variables in debug UI panels
+5. Step through code: `F10`, `F11`, `F12`
+6. Continue execution: `F5`
+
+### Debug UI Panels
+
+When debugging starts, you get:
+- **Scopes**: Local and global variables
+- **Breakpoints**: All breakpoints in your project  
+- **Call Stack**: Function call hierarchy
+- **Watches**: Custom expressions to monitor
+- **REPL**: Evaluate Dart expressions live
+- **Console**: Debug output and print statements
+
+## Logs
+
+```
+<Space>fL   # Toggle log buffer
+```
+
+The log buffer shows:
+- `print()` statements
+- Flutter framework messages
+- Hot reload/restart confirmations
+- Error messages and stack traces
+
+## Tips & Tricks
+
+### Fast Development Loop
+
+```
+1. Make UI changes
+2. <Space>fh for instant hot reload
+3. See changes immediately
+4. Repeat
+```
+
+### When Hot Reload Fails
+
+If hot reload shows unexpected behavior:
+
+```
+<Space>fR   # Hot restart (full reload)
+```
+
+If issues persist:
+
+```
+<Space>fq   # Quit app
+<Space>fl   # Restart LSP
+<Space>fr   # Run again
+```
+
+### Multiple Devices
+
+Switch between devices without restarting:
+
+```
+<Space>fq   # Quit current
+<Space>fd   # Select new device
+<Space>fr   # Run on new device
+```
+
+### Widget Extraction
+
+To extract a widget to a new class:
+
+1. Visual select the widget code
+2. Press `<Space>.` or `gra`
+3. Choose "Extract Widget"
+4. Enter new widget name
+
+### Attach to Running App
+
+If your app is already running (started outside Neovim):
+
+```
+<Space>fa   # Attach to running process
+```
+
+This enables hot reload and debugging for external apps.
+
+## Configuration
+
+Flutter tools are configured in `lua/custom/plugins/flutter.lua`.
+
+Key settings:
+- **Auto-start DevTools**: `dev_tools.autostart = false` (manual start)
+- **Widget guides**: `widget_guides.enabled = true` (visual nesting guides)
+- **Closing tags**: `closing_tags.enabled = true` (shows widget closing comments)
+- **Color preview**: `lsp.color.enabled = true` (inline color indicators)
+
+## Troubleshooting
+
+### LSP Not Working
+
+```
+:FlutterLspRestart
+# or
+<Space>fl
+```
+
+### Can't Select Device
+
+Ensure Flutter can see your devices:
+
+```
+:!flutter devices
+```
+
+If devices don't show, check:
+- Android emulator is running
+- iOS simulator is running  
+- Physical device is connected and authorized
+- Chrome is installed (for web)
+
+### Hot Reload Not Responding
+
+```
+<Space>fR   # Force hot restart
+```
+
+If still not working:
+
+```
+<Space>fq   # Quit
+<Space>fr   # Restart fresh
+```
+
+### Dart Analysis Errors
+
+Force re-analysis:
+
+```
+:FlutterReanalyze
+```
+
+Or restart LSP: `<Space>fl`
+
+## Resources
+
+- [Flutter Documentation](https://flutter.dev/docs)
+- [Dart Language Tour](https://dart.dev/guides/language/language-tour)
+- [Widget Catalog](https://flutter.dev/docs/development/ui/widgets)
+- [flutter-tools.nvim GitHub](https://github.com/akinsho/flutter-tools.nvim)
+
+## See Also
+
+- [Debug Keymaps](../keymaps/README.md#debugging) - Complete debugging reference
+- [LSP Features](../plugins/lsp.md) - Language Server Protocol features
+- [Code Actions](../keymaps/README.md#lsp) - All code action keymaps