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.
2025-07-27 18:37:55 -04:00
parent 5c2cb1a4ed
commit 36a576dc2c
29 changed files with 3751 additions and 51 deletions
--- a/TEXTUAL_TIPTOP_INSIGHTS.md
+++ b/TEXTUAL_TIPTOP_INSIGHTS.md
@@ -0,0 +1,154 @@
+# TipTop Design Insights for StreamLens Textual UI
+
+## Key Design Patterns from TipTop
+
+### 1. **Multi-Column Layout with Graphs**
+TipTop uses a clean multi-column layout:
+- Left column: System info and CPU details
+- Center column: Real-time graphs (CPU, Memory, Disk, Network)
+- Right column: Process list with live updates
+
+### 2. **Real-Time Sparkline Charts**
+- CPU usage shown as percentage with sparkline history
+- Memory usage with bar visualization
+- Disk I/O with read/write graphs
+- Network traffic with up/down visualization
+
+### 3. **Color-Coded Information**
+- Green for normal values
+- Yellow/Orange for warnings
+- Red for critical values
+- Subtle color gradients in graphs
+
+### 4. **Compact Information Display**
+- Multiple metrics per line (e.g., "CPU: 23.4% | Temp: 45°C")
+- Efficient use of terminal space
+- Clear visual hierarchy
+
+### 5. **Live Process Monitoring**
+- Sortable process list
+- Real-time updates
+- Resource usage per process
+
+## Application to StreamLens
+
+### Enhanced Flow Analysis View
+```python
+# Inspired by TipTop's layout
+class FlowAnalysisEnhanced(Container):
+    def compose(self):
+        # Left panel: Flow summary with sparklines
+        with Vertical(id="flow-summary", classes="column"):
+            yield Static("Flow Overview", classes="header")
+            yield FlowMetricsPanel()  # Total flows, packets, volume
+            yield SparklineChart(id="flow-rate")  # Flows/sec graph
+            
+        # Center panel: Main flow table with mini-graphs
+        with Vertical(id="flow-table", classes="column-wide"):
+            yield EnhancedFlowTable()  # DataTable with inline sparklines
+            
+        # Right panel: Selected flow details
+        with Vertical(id="flow-details", classes="column"):
+            yield Static("Flow Details", classes="header")
+            yield FlowTimingChart()  # Inter-arrival timing graph
+            yield ProtocolBreakdown()  # Pie chart of protocols
+```
+
+### Real-Time Metrics with Sparklines
+```python
+class FlowSparkline(Widget):
+    """Mini inline chart for flow metrics"""
+    
+    def render(self) -> Text:
+        # Create ASCII sparkline like TipTop
+        values = self.get_recent_values()
+        spark = self.create_sparkline(values)
+        return Text(f"Rate: {self.current_rate:>6.1f} pps {spark}")
+```
+
+### Enhanced DataTable Row Format
+Instead of static columns, include inline visualizations:
+```
+Flow  Source           Proto  Destination      Volume  Rate  Quality  Timing Graph
+  1   192.168.1.1:80  TCP    10.0.0.1:443    1.2GB   ████  95%     ▁▃▅▇█▅▃▁
+  2   10.0.0.2:53     UDP    8.8.8.8:53      450MB   ██░░  87%     ▇▇▅▃▁▁▃▅
+```
+
+### Color-Coded Quality Indicators
+```python
+def get_quality_style(quality: float) -> str:
+    if quality >= 90:
+        return "bold green"
+    elif quality >= 70:
+        return "yellow"
+    else:
+        return "bold red"
+```
+
+### Live Update Pattern
+```python
+class StreamLensApp(App):
+    def on_mount(self):
+        # TipTop-style periodic updates
+        self.set_interval(0.5, self.update_metrics)  # 2Hz for smooth graphs
+        self.set_interval(1.0, self.update_flows)    # 1Hz for flow data
+        
+    def update_metrics(self):
+        # Update sparklines and real-time graphs
+        for widget in self.query(SparklineChart):
+            widget.add_data_point()
+```
+
+### Compact Header Bar
+```
+StreamLens | Flows: 127 | Packets: 1.2M/s | Volume: 845MB/s | Enhanced: 12 | Outliers: 3
+```
+
+### CSS Styling Inspired by TipTop
+```css
+/* Dark theme with accent colors */
+Screen {
+    background: $surface;
+}
+
+.column {
+    width: 25%;
+    padding: 1;
+    border: solid $primary-lighten-3;
+}
+
+.column-wide {
+    width: 1fr;
+    padding: 1;
+}
+
+SparklineChart {
+    height: 3;
+    border: none;
+}
+
+.metric-good { color: $success; }
+.metric-warning { color: $warning; }
+.metric-critical { color: $error; }
+
+/* Subtle animations for live updates */
+.updating {
+    background: $primary 10%;
+    transition: background 200ms;
+}
+```
+
+## Implementation Priority
+
+1. **Phase 1**: Add sparkline charts to flow table
+2. **Phase 2**: Create multi-column layout with live metrics
+3. **Phase 3**: Implement inline bar charts for volume/quality
+4. **Phase 4**: Add color-coded alerts and thresholds
+5. **Phase 5**: Create smooth animations for updates
+
+## Benefits
+- **Information Density**: Show more data in less space
+- **Visual Clarity**: Instant understanding of trends
+- **Professional Look**: Modern monitoring aesthetic
+- **User Experience**: Smooth, responsive interface
+- **Real-Time Insight**: Immediate visibility of changes