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.

Documentation/textual/README.md

@@ -0,0 +1,61 @@
+# Textual API Reference
+
+This directory contains a comprehensive reference for the Textual library API, focusing on the components used in StreamLens.
+
+## Overview
+
+Textual is a TUI (Text User Interface) framework for Python. This reference covers the key APIs we use.
+
+## Quick Links
+
+- [DataTable Widget Reference](./datatable.md) - Complete DataTable API
+- [Events Reference](./events.md) - Event handling and messages
+- [Common Widgets](./widgets.md) - Other widgets used in StreamLens
+- [Styling Guide](./styling.md) - CSS and styling reference
+
+## Core Concepts
+
+### Messages and Events
+
+Textual uses a message-passing system for communication between widgets:
+
+1. **Events** - User interactions (keyboard, mouse)
+2. **Messages** - Widget-to-widget communication
+3. **Handlers** - Methods that respond to events/messages
+
+### Event Handler Naming
+
+Event handlers follow the pattern: `on_<widget_class>_<event_name>`
+
+Example:
+```python
+def on_data_table_row_selected(self, event: DataTable.RowSelected):
+    # Handle row selection
+```
+
+### Common Pitfalls
+
+1. **RowKey Type**: DataTable row keys are not strings by default
+2. **Event Names**: Check exact event class names (e.g., `RowHighlighted` not `CursorMoved`)
+3. **Method Availability**: Not all expected methods exist (e.g., no `set_row_style()`)
+
+## API Validation
+
+Always validate API usage before implementation:
+
+```python
+# Check available events
+from textual.widgets import DataTable
+print([attr for attr in dir(DataTable) if 'Selected' in attr or 'Highlighted' in attr])
+
+# Check specific method
+print(hasattr(DataTable, 'method_name'))
+```
+
+## Directory Structure
+
+- `datatable.md` - Complete DataTable API reference
+- `events.md` - Events and message handling
+- `widgets.md` - Common widget APIs
+- `styling.md` - CSS and theming
+- `examples/` - Working code examples