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.

MAXIMUM_WIDTH_LAYOUT.md

@@ -0,0 +1,121 @@
+# Maximum Width Dynamic Layout
+
+## Overview
+
+The Flow Analysis View now dynamically adjusts to use the maximum available terminal width, ensuring optimal use of screen real estate regardless of terminal size.
+
+## Dynamic Width Calculation
+
+### Available Space Calculation
+```python
+available_width = terminal_width - 16  # 4 chars left + 4 chars right + 8 safety margin
+```
+
+**Prevents Line Wrapping**: Very conservative calculation ensures content never exceeds terminal width, even on narrow terminals
+
+### Minimum Column Requirements
+| Column | Min Width | Purpose |
+|--------|-----------|---------|
+| Flow # | 3 chars | Flow number with space |
+| Source | 15 chars | Compact IP:port |
+| Proto | 4 chars | Transport protocol |
+| Destination | 15 chars | Compact IP:port |
+| Extended | 6 chars | Extended protocol |
+| Frame Type | 8 chars | Frame type name |
+| Pkts | 6 chars | Right-aligned numbers |
+| Volume | 8 chars | Right-aligned with units |
+| Timing | 8 chars | Right-aligned with units |
+| Quality | 8 chars | Right-aligned percentages |
+
+**Total Minimum**: 81 characters
+
+### Space Distribution Algorithm
+
+1. **Check Available Space**: If terminal width > minimum requirements
+2. **Calculate Extra Space**: `extra = available_width - minimum_total`
+3. **Distribute to Text Columns**: Extra space goes to expandable columns:
+   - Source (IP:port endpoints)
+   - Destination (IP:port endpoints)
+   - Extended (protocol names)
+   - Frame Type (frame type names)
+
+4. **Equal Distribution**: `extra_per_column = extra_space ÷ 4`
+5. **Remainder Handling**: Any leftover space goes to Source and Destination columns
+
+### Example Width Distributions
+
+#### Small Terminal (120 chars)
+```
+Available: 112 chars (120 - 8 margin)
+Extra: 6 chars (112 - 106 minimum)
+Distribution: +1 to Source, +1 to Destination, +1 to Extended, +1 to Frame Type, +2 remainder to Source/Dest
+```
+
+#### Medium Terminal (150 chars) 
+```
+Available: 142 chars (150 - 8 margin)
+Extra: 36 chars (142 - 106 minimum)
+Distribution: +9 to each expandable column
+```
+
+#### Large Terminal (200 chars)
+```
+Available: 192 chars (200 - 8 margin)
+Extra: 86 chars (192 - 106 minimum) 
+Distribution: +21 to each expandable column, +2 remainder to Source/Dest
+```
+
+## Adaptive Features
+
+### Intelligent Truncation
+- Source/Destination fields truncate based on their allocated width
+- IP addresses get maximum space before port numbers
+- Ellipsis (…) indicates truncated content
+
+### Perfect Alignment
+- All right-aligned columns maintain perfect edge alignment
+- Sub-row indentation matches main flow number column width
+- Headers automatically adjust to match column widths
+
+### Responsive Layout
+```
+Small Terminal (120 chars):
+  #   Source               Proto  Destination          Extended Frame Type    Pkts    Volume     Timing    Quality
+
+Large Terminal (200 chars):
+   #   Source                          Proto      Destination                     Extended       Frame Type            Pkts      Volume        Timing      Quality
+```
+
+## Benefits
+
+1. **Maximum Information Density**: Uses every available character of terminal width
+2. **Scalable Design**: Works equally well on narrow and wide terminals
+3. **Perfect Alignment**: All columns line up properly regardless of terminal size
+4. **Responsive Text**: Important text fields expand to show more information on wider screens
+5. **Consistent Metrics**: Numeric columns maintain consistent width for easy comparison
+
+## Implementation Details
+
+### Dynamic Column Width Object
+```python
+self.column_widths = {
+    'flow_num': 4,
+    'source': 25,      # Dynamically calculated
+    'proto': 6,
+    'destination': 25, # Dynamically calculated  
+    'extended': 12,    # Dynamically calculated
+    'frame_type': 14,  # Dynamically calculated
+    'pkts': 8,
+    'volume': 10,
+    'timing': 10,
+    'quality': 10
+}
+```
+
+### Formatting Functions
+- `_calculate_column_widths()`: Determines optimal column widths for current terminal
+- `_format_headers()`: Creates header line with dynamic spacing
+- `_format_flow_summary_line()`: Formats main flow lines with dynamic widths
+- `_format_protocol_frame_line()`: Formats sub-rows with matching alignment
+
+The layout now provides optimal readability and information display regardless of terminal size, from compact laptop screens to ultra-wide monitors.