Enhanced Textual TUI with proper API usage and documentation

- Fixed DataTable row selection and event handling
- Added explicit column keys to prevent auto-generated keys
- Implemented row-to-flow mapping for reliable selection tracking
- Converted left metrics panel to horizontal top bar
- Fixed all missing FlowStats/EnhancedAnalysisData attributes
- Created comprehensive Textual API documentation in Documentation/textual/
- Added validation checklist to prevent future API mismatches
- Preserved cursor position during data refreshes
- Fixed RowKey type handling and event names

The TUI now properly handles flow selection, displays metrics in a compact top bar,
and correctly correlates selected rows with the details pane.

TEXTUAL_API_CHECKLIST.md

@@ -0,0 +1,71 @@
+# Textual API Validation Checklist
+
+## Before Using Textual APIs
+
+### 1. Event Names
+- DataTable events:
+  - ✅ `RowHighlighted` - When cursor moves to a row
+  - ✅ `RowSelected` - When row is selected (Enter key)
+  - ✅ `CellHighlighted` - When cursor moves to a cell
+  - ✅ `CellSelected` - When cell is selected
+  - ✅ `ColumnHighlighted` - When column is highlighted
+  - ✅ `HeaderSelected` - When header is clicked
+  - ❌ `CursorMoved` - Does NOT exist
+  - ❌ `SelectionChanged` - Does NOT exist
+
+### 2. DataTable Methods
+- ✅ `add_row()` - Add a row with optional key
+- ✅ `clear()` - Clear all rows
+- ✅ `move_cursor()` - Move cursor programmatically
+- ❌ `set_row_style()` - Does NOT exist (use CSS classes)
+- ✅ `add_column()` - Add a column
+- ✅ `remove_row()` - Remove a row by key
+
+### 3. Common Attribute Patterns
+- Properties: `cursor_row`, `cursor_column`, `row_count`, `rows`
+- Events: Always check with `dir(Widget)` or test imports
+- Messages: Custom messages need `from textual.message import Message`
+
+### 4. Model Attributes Checklist
+When adding UI that accesses model attributes:
+- [ ] Check if attribute exists in model class
+- [ ] Add missing attributes with appropriate defaults
+- [ ] Consider if attribute should be calculated or stored
+- [ ] Update any related initialization code
+
+### 5. Testing Strategy
+```python
+# Quick validation script
+from textual.widgets import DataTable
+print("Available events:", [attr for attr in dir(DataTable) if 'Selected' in attr or 'Highlighted' in attr])
+```
+
+### 6. Common Pitfalls
+1. **Event naming**: Textual uses specific naming patterns
+2. **Method availability**: Not all expected methods exist
+3. **CSS vs API**: Some styling must be done via CSS
+4. **Message inheritance**: Custom messages need proper base class
+
+## Validation Commands
+
+```bash
+# Check available attributes
+source venv/bin/activate
+python -c "from textual.widgets import DataTable; print(dir(DataTable))"
+
+# Check specific event
+python -c "from textual.widgets import DataTable; print('EventName' in dir(DataTable))"
+
+# Check imports
+python -c "from textual.widgets import WidgetName"
+```
+
+## Model Validation
+
+Before running the app, validate all model attributes are present:
+```bash
+# Run a quick attribute check
+python -c "from analyzer.models.flow_stats import FlowStats, EnhancedAnalysisData; 
+fs = FlowStats('', ''); 
+print('Required attrs:', ['duration', 'first_seen', 'last_seen', 'jitter'])"
+```