iot/spore-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: remove obsolete docs

Browse Source
This commit is contained in:
0x1d
2025-08-31 12:20:58 +02:00
parent 948a8a1fab
commit 83d252f3cc
3 changed files with 0 additions and 635 deletions
Download Patch File Download Diff File Expand all files Collapse all files

266
docs/STATE_PRESERVATION.md
View File

@@ -1,266 +0,0 @@
# SPORE UI State Preservation System
## Overview
The SPORE UI framework now includes an advanced state preservation system that prevents UI state loss during data refreshes. This system ensures that user interactions like expanded cards, active tabs, and other UI state are maintained when data is updated from the server.
## Key Features
### 1. **UI State Persistence**
- **Expanded Cards**: When cluster member cards are expanded, their state is preserved across data refreshes
- **Active Tabs**: Active tab selections within node detail views are maintained
- **User Interactions**: All user-initiated UI changes are stored and restored automatically
### 2. **Smart Data Updates**
- **Change Detection**: The system detects when data has actually changed and only updates what's necessary
- **Partial Updates**: Components can update specific data without re-rendering the entire UI
- **State Preservation**: UI state is automatically preserved during all data operations
### 3. **Efficient Rendering**
- **No Full Re-renders**: Components avoid unnecessary full re-renders when only data changes
- **Granular Updates**: Only changed properties trigger UI updates
- **Performance Optimization**: Reduced DOM manipulation and improved user experience
## Architecture
### Enhanced ViewModel Class
The base `ViewModel` class now includes:
```javascript
class ViewModel {
// UI State Management
setUIState(key, value) // Store UI state
getUIState(key) // Retrieve UI state
getAllUIState() // Get all stored UI state
clearUIState(key) // Clear specific or all UI state
// Change Detection
hasChanged(property) // Check if property changed
getPrevious(property) // Get previous value
// Batch Updates
batchUpdate(updates, options) // Update multiple properties with state preservation
}
```
### Enhanced Component Class
The base `Component` class now includes:
```javascript
class Component {
// UI State Management
setUIState(key, value) // Store local UI state
getUIState(key) // Get local or view model state
getAllUIState() // Get merged state
restoreUIState() // Restore state from view model
// Partial Updates
updatePartial(property, newValue, previousValue) // Handle partial updates
}
```
## Implementation Examples
### 1. **Cluster Members Component**
The `ClusterMembersComponent` demonstrates state preservation:
```javascript
class ClusterMembersComponent extends Component {
setupViewModelListeners() {
// Listen with change detection
this.subscribeToProperty('members', this.handleMembersUpdate.bind(this));
}
handleMembersUpdate(newMembers, previousMembers) {
if (this.shouldPreserveState(newMembers, previousMembers)) {
// Partial update preserves UI state
this.updateMembersPartially(newMembers, previousMembers);
} else {
// Full re-render only when necessary
this.render();
}
}
shouldPreserveState(newMembers, previousMembers) {
// Check if member structure allows state preservation
if (newMembers.length !== previousMembers.length) return false;
const newIps = new Set(newMembers.map(m => m.ip));
const prevIps = new Set(previousMembers.map(m => m.ip));
return newIps.size === prevIps.size &&
[...newIps].every(ip => prevIps.has(ip));
}
}
```
### 2. **Node Details Component**
The `NodeDetailsComponent` preserves active tab state:
```javascript
class NodeDetailsComponent extends Component {
setupViewModelListeners() {
this.subscribeToProperty('activeTab', this.handleActiveTabUpdate.bind(this));
}
handleActiveTabUpdate(newTab, previousTab) {
// Update tab UI without full re-render
this.updateActiveTab(newTab, previousTab);
}
updateActiveTab(newTab) {
// Update only the tab UI, preserving other state
const tabButtons = this.findAllElements('.tab-button');
const tabContents = this.findAllElements('.tab-content');
tabButtons.forEach(btn => btn.classList.remove('active'));
tabContents.forEach(content => content.classList.remove('active'));
const activeButton = this.findElement(`[data-tab="${newTab}"]`);
const activeContent = this.findElement(`#${newTab}-tab`);
if (activeButton) activeButton.classList.add('active');
if (activeContent) activeContent.classList.add('active');
}
}
```
## Usage Patterns
### 1. **Storing UI State**
```javascript
// In a component
this.setUIState('expandedCard', memberIp);
this.setUIState('activeTab', 'firmware');
// In a view model
this.setUIState('userPreferences', { theme: 'dark', layout: 'compact' });
```
### 2. **Retrieving UI State**
```javascript
// Get specific state
const expandedCard = this.getUIState('expandedCard');
const activeTab = this.getUIState('activeTab');
// Get all state
const allState = this.getAllUIState();
```
### 3. **Batch Updates with State Preservation**
```javascript
// Update data while preserving UI state
this.viewModel.batchUpdate({
members: newMembers,
lastUpdateTime: new Date().toISOString()
}, { preserveUIState: true });
```
### 4. **Smart Updates**
```javascript
// Use smart update to preserve state
await this.viewModel.smartUpdate();
```
## Benefits
### 1. **Improved User Experience**
- Users don't lose their place in the interface
- Expanded cards remain expanded
- Active tabs stay selected
- No jarring UI resets
### 2. **Better Performance**
- Reduced unnecessary DOM manipulation
- Efficient partial updates
- Optimized rendering cycles
### 3. **Maintainable Code**
- Clear separation of concerns
- Consistent state management patterns
- Easy to extend and modify
## Testing
Use the `test-state-preservation.html` file to test the state preservation system:
1. **Expand cluster member cards**
2. **Change active tabs in node details**
3. **Trigger data refresh**
4. **Verify state is preserved**
## Migration Guide
### From Old System
If you're upgrading from the old system:
1. **Update ViewModel Listeners**: Change from `this.render.bind(this)` to specific update handlers
2. **Add State Management**: Use `setUIState()` and `getUIState()` for UI state
3. **Implement Partial Updates**: Override `updatePartial()` method for efficient updates
4. **Use Smart Updates**: Replace direct data updates with `smartUpdate()` calls
### Example Migration
**Old Code:**
```javascript
this.subscribeToProperty('members', this.render.bind(this));
async handleRefresh() {
await this.viewModel.updateClusterMembers();
}
```
**New Code:**
```javascript
this.subscribeToProperty('members', this.handleMembersUpdate.bind(this));
async handleRefresh() {
await this.viewModel.smartUpdate();
}
handleMembersUpdate(newMembers, previousMembers) {
if (this.shouldPreserveState(newMembers, previousMembers)) {
this.updateMembersPartially(newMembers, previousMembers);
} else {
this.render();
}
}
```
## Best Practices
1. **Always Store UI State**: Use `setUIState()` for any user interaction
2. **Implement Partial Updates**: Override `updatePartial()` for efficient updates
3. **Use Change Detection**: Leverage `hasChanged()` to avoid unnecessary updates
4. **Batch Related Updates**: Use `batchUpdate()` for multiple property changes
5. **Test State Preservation**: Verify that UI state is maintained during data refreshes
## Troubleshooting
### Common Issues
1. **State Not Preserved**: Ensure you're using `setUIState()` and `getUIState()`
2. **Full Re-renders**: Check if `shouldPreserveState()` logic is correct
3. **Performance Issues**: Verify you're using partial updates instead of full renders
### Debug Tips
1. **Enable Console Logging**: Check browser console for state preservation logs
2. **Use State Indicators**: Monitor state changes in the test interface
3. **Verify Change Detection**: Ensure `hasChanged()` is working correctly
## Future Enhancements
- **State Synchronization**: Real-time state sync across multiple browser tabs
- **Advanced Change Detection**: Deep object comparison for complex data structures
- **State Persistence**: Save UI state to localStorage for session persistence
- **State Rollback**: Ability to revert to previous UI states

146
docs/TOPOLOGY_VIEW.md
View File

@@ -1,146 +0,0 @@
# Topology View - Network Topology Visualization
## Overview
The Topology view provides an interactive, force-directed graph visualization of the SPORE cluster network topology. It displays each cluster member as a node and shows the connections (links) between them with latency information.
## Features
### 🎯 **Interactive Network Graph**
- **Force-directed layout**: Nodes automatically arrange themselves based on connections
- **Zoom and pan**: Navigate through large network topologies
- **Drag and drop**: Reposition nodes manually for better visualization
- **Responsive design**: Adapts to different screen sizes
### 📊 **Node Information**
- **Status indicators**: Color-coded nodes based on member status (ACTIVE, INACTIVE, DEAD)
- **Hostname display**: Shows the human-readable name of each node
- **IP addresses**: Displays the network address of each member
- **Resource information**: Access to system resources and capabilities
### 🔗 **Connection Visualization**
- **Latency display**: Shows network latency between connected nodes
- **Color-coded links**: Different colors indicate latency ranges:
- 🟢 Green: ≤5ms (excellent)
- 🟠 Orange: 6-15ms (good)
- 🔴 Red-orange: 16-30ms (fair)
- 🔴 Red: >30ms (poor)
- **Bidirectional connections**: Shows actual network topology from each node's perspective
### 🎨 **Visual Enhancements**
- **Legend**: Explains node status colors and latency ranges
- **Hover effects**: Interactive feedback when hovering over nodes and links
- **Selection highlighting**: Click nodes to select and highlight them
- **Smooth animations**: Force simulation provides natural movement
## Technical Implementation
### Architecture
- **ViewModel**: `TopologyViewModel` manages data and state
- **Component**: `TopologyGraphComponent` handles rendering and interactions
- **Framework**: Integrates with the existing SPORE UI framework
- **Library**: Uses D3.js v7 for graph visualization
### Data Flow
1. **Primary node query**: Fetches cluster members from the primary node
2. **Individual node queries**: Gets cluster view from each member node
3. **Topology building**: Constructs network graph from actual connections
4. **Fallback mesh**: Creates basic mesh if no actual connections found
### API Endpoints
- `/api/cluster/members` - Get cluster membership from primary node
- `/api/cluster/members?ip={nodeIP}` - Get cluster view from specific node
## Usage
### Navigation
1. Click the "🌐 Topology" tab in the main navigation
2. The view automatically loads and displays the network topology
3. Use the refresh button to update the visualization
### Interaction
- **Zoom**: Use mouse wheel or pinch gestures
- **Pan**: Click and drag on empty space
- **Select nodes**: Click on any node to highlight it
- **Move nodes**: Drag nodes to reposition them
- **Hover**: Hover over nodes and links for additional information
### Refresh
- Click the "Refresh" button to reload network topology data
- Useful after network changes or when adding/removing nodes
## Configuration
### Graph Parameters
- **Node spacing**: 120px between connected nodes
- **Repulsion force**: -400 strength for node separation
- **Collision radius**: 40px minimum distance between nodes
- **Zoom limits**: 0.1x to 4x zoom range
### Visual Settings
- **Node sizes**: Vary based on status (ACTIVE: 10px, INACTIVE: 8px, DEAD: 6px)
- **Link thickness**: Proportional to latency (2-8px range)
- **Colors**: Semantic color scheme for status and latency
## Troubleshooting
### Common Issues
#### No Graph Displayed
- Check browser console for JavaScript errors
- Verify D3.js library is loading correctly
- Ensure cluster has discovered nodes
#### Missing Connections
- Verify nodes are responding to API calls
- Check network connectivity between nodes
- Review cluster discovery configuration
#### Performance Issues
- Reduce number of displayed nodes
- Adjust force simulation parameters
- Use zoom to focus on specific areas
### Debug Information
- Test file available at `test-topology-view.html`
- Console logging provides detailed component lifecycle information
- Network topology data is logged during updates
## Future Enhancements
### Planned Features
- **Real-time updates**: WebSocket integration for live topology changes
- **Metrics overlay**: CPU, memory, and network usage display
- **Path finding**: Show routes between specific nodes
- **Export options**: Save graph as image or data file
- **Custom layouts**: Alternative visualization algorithms
### Performance Optimizations
- **Lazy loading**: Load node details on demand
- **Virtualization**: Handle large numbers of nodes efficiently
- **Caching**: Store topology data locally
- **Web Workers**: Offload computation to background threads
## Dependencies
- **D3.js v7**: Force-directed graph visualization
- **SPORE UI Framework**: Component architecture and state management
- **Modern Browser**: ES6+ support required
- **Network Access**: Ability to reach cluster nodes
## Browser Support
- **Chrome**: 80+ (recommended)
- **Firefox**: 75+
- **Safari**: 13+
- **Edge**: 80+
## Contributing
To contribute to the Members view:
1. Follow the existing code style and patterns
2. Test with different cluster configurations
3. Ensure responsive design works on mobile devices
4. Add appropriate error handling and logging
5. Update documentation for new features

223
docs/VIEW_SWITCHING_FIXES.md
View File

@@ -1,223 +0,0 @@
# View Switching Fixes for Member Card Issues
## Problem Description
When switching between the cluster and firmware views, member cards were experiencing:
- **Wrong UI state**: Expanded cards, active tabs, and other UI state was being lost
- **Flickering**: Visual glitches and rapid re-rendering during view switches
- **Broken functionality**: Member cards not working properly after view switches
- **Inefficient rendering**: Components were completely unmounted and remounted on every view switch
- **Incorrect state restoration**: UI state was incorrectly restored on first load (all cards expanded, wrong tabs active)
## Root Causes Identified
1. **Aggressive DOM Manipulation**: Complete component unmounting/remounting on every view switch
2. **Race Conditions**: Multiple async operations and timeouts interfering with each other
3. **State Loss**: UI state not properly preserved across view switches
4. **Rapid Navigation**: Multiple rapid clicks could cause navigation conflicts
5. **CSS Transition Conflicts**: Multiple transitions causing visual flickering
6. **No Component Caching**: Every view switch created new component instances
7. **Complex State Restoration**: Attempting to restore UI state caused incorrect behavior on first load
## Fixes Implemented
### 1. **Component Caching System** (`framework.js`)
- **Component Cache**: Components are created once and cached, never re-created
- **Pause/Resume Pattern**: Components are paused (not unmounted) when switching away
- **Pre-initialization**: Components are created during route registration for better performance
- **Simple Show/Hide**: Components are just shown/hidden without touching UI state
### 2. **Enhanced Navigation System** (`framework.js`)
- **Debounced Navigation**: Added 300ms cooldown between navigation requests
- **Navigation Queue**: Queues navigation requests when one is already in progress
- **Smooth Transitions**: Added opacity transitions to prevent abrupt view changes
- **No Component Destruction**: Components are kept alive and just paused/resumed
### 3. **Simplified State Management** (`view-models.js`)
- **No UI State Persistence**: Removed complex localStorage state restoration
- **Clean State on Load**: Components start with default state (collapsed cards, status tab)
- **No State Corruption**: Eliminates incorrect state restoration on first load
### 4. **Enhanced Component Lifecycle** (`components.js`)
- **Pause/Resume Methods**: Components can be paused and resumed without losing state
- **Default State**: Member cards always start collapsed, tabs start on 'status'
- **No State Restoration**: Components maintain their current state without external interference
- **Render Guards**: Prevents multiple simultaneous render operations
- **View Switch Detection**: Skips rendering during view transitions
- **Improved Unmounting**: Better cleanup of timeouts and event listeners
- **State Tracking**: Tracks if data has already been loaded to prevent unnecessary reloads
### 5. **CSS Improvements** (`styles.css`)
- **Smooth Transitions**: Added fade-in/fade-out animations for view switching
- **Reduced Transition Times**: Shortened member card transitions from 0.3s to 0.2s
- **Better Animations**: Improved expand/collapse animations for member cards
- **Loading States**: Added fade-in animations for loading, error, and empty states
### 6. **View Model Enhancements**
- **Smart Updates**: Only updates changed data to minimize re-renders
- **Change Detection**: Compares data before triggering updates
- **Clean Initialization**: No complex state restoration logic
## Technical Details
### Component Caching Flow
1. **Route Registration**: Components are created and cached during app initialization
2. **Navigation**: When switching views, current component is paused (not unmounted)
3. **State Preservation**: All component state, DOM, and event listeners remain intact
4. **Resume**: When returning to a view, component is resumed from paused state
5. **No Re-rendering**: Components maintain their exact state and appearance
6. **Simple Show/Hide**: No complex state restoration, just show/hide components
### Pause/Resume Pattern
```javascript
// Component is paused instead of unmounted
onPause() {
// Clear timers, pause operations
// Component state and DOM remain intact
}
onResume() {
// Restore timers, resume operations
// No re-rendering needed
}
```
### Navigation Flow
1. **Cooldown Check**: 300ms minimum between navigation requests
2. **Queue Management**: Multiple requests queued and processed sequentially
3. **Pause Current**: Current component paused (opacity: 0)
4. **Show New View**: New view becomes visible with fade-in animation
5. **Resume Component**: Cached component resumed from paused state
6. **No Unmounting**: Components are never destroyed during view switches
7. **No State Touch**: UI state is not modified during view switches
### State Management
- **Default State**: Member cards start collapsed, tabs start on 'status'
- **No Persistence**: No localStorage state restoration
- **Clean Initialization**: Components always start with predictable state
- **No State Corruption**: Eliminates incorrect state restoration issues
### Render Optimization
- **No Re-rendering**: Components maintain their exact state across view switches
- **Pause/Resume**: Components are paused instead of unmounted
- **State Persistence**: All UI state preserved in memory (not localStorage)
- **Change Detection**: Only updates changed data when resuming
- **Default Behavior**: Always starts with clean, predictable state
## Testing
Use the test page `test-view-switching.html` to verify fixes:
1. **Rapid Switching Test**: Clicks navigation tabs rapidly to test cooldown
2. **State Preservation Test**: Expands cards, switches views, verifies state restoration
3. **Component Caching Test**: Verify components are not re-created on view switches
4. **Default State Test**: Verify components start with correct default state
5. **Console Monitoring**: Check console for detailed operation logs
## Expected Results
After implementing these fixes:
- ✅ **No More Re-rendering**: Components are cached and never re-created
- ✅ **No More Flickering**: Smooth transitions between views
- ✅ **Correct Default State**: Member cards start collapsed, tabs start on 'status'
- ✅ **No State Corruption**: No incorrect state restoration on first load
- ✅ **Stable Navigation**: No more broken member cards after view switches
- ✅ **Better Performance**: No unnecessary component creation/destruction
- ✅ **Improved UX**: Smoother, more professional feel
- ✅ **Memory Efficiency**: Components reused instead of recreated
- ✅ **Predictable Behavior**: Components always start with clean state
## Configuration
### Navigation Cooldown
```javascript
this.navigationCooldown = 300; // 300ms between navigation requests
```
### Component Caching
```javascript
// Components are automatically cached during route registration
app.registerRoute('cluster', ClusterViewComponent, 'cluster-view', clusterViewModel);
```
### Transition Timing
```css
.view-content {
transition: opacity 0.2s ease-in-out;
}
```
### Member Card Transitions
```css
.member-card {
transition: all 0.2s ease;
}
```
## Architecture Benefits
### 1. **Performance**
- No component recreation on view switches
- Faster view transitions
- Reduced memory allocation/deallocation
### 2. **State Management**
- Clean, predictable default state
- No state corruption on first load
- Consistent user experience
### 3. **Maintainability**
- Cleaner component lifecycle
- No complex state restoration logic
- Easier debugging and testing
- More predictable behavior
### 4. **User Experience**
- No flickering or visual glitches
- Instant view switching
- Maintained user context
- Predictable component behavior
## Key Changes Made
### Removed Complex State Restoration
- ❌ `preserveUIState()` method
- ❌ `restoreUIState()` method
- ❌ localStorage state persistence
- ❌ Complex tab state restoration
- ❌ Expanded card state restoration
### Simplified Component Behavior
- ✅ Components start with default state
- ✅ Member cards always start collapsed
- ✅ Tabs always start on 'status'
- ✅ No external state interference
- ✅ Clean, predictable initialization
### Maintained Performance Benefits
- ✅ Component caching still works
- ✅ No re-rendering on view switches
- ✅ Smooth transitions
- ✅ Better memory efficiency
## Future Improvements
1. **Virtual Scrolling**: For large numbers of member cards
2. **Animation Preferences**: User-configurable transition speeds
3. **State Sync**: Real-time state synchronization across multiple tabs
4. **Performance Metrics**: Track and optimize render performance
5. **Lazy Loading**: Load components only when first accessed
6. **Memory Management**: Intelligent cache cleanup for unused components
7. **User Preferences**: Allow users to set default states if desired