feat: Reactive Widget System for Dashboard (Phase 5)
Implement comprehensive widget rendering system allowing SecuBox apps to display
live metrics, status, and controls as responsive widgets on the dashboard.
## Widget Rendering Engine
**New**: `/secubox-admin/widget-renderer.js` (~450 lines)
Core widget system with:
- **WidgetRenderer Class**: Main rendering engine with plugin architecture
- **Template System**: Pluggable widget templates by category
- **Auto-refresh**: Configurable polling (default: 30s per widget)
- **Responsive Grid**: CSS Grid with auto, fixed-2, fixed-3, fixed-4 modes
- **Lifecycle Management**: Initialize, update, destroy with cleanup
### Built-in Templates
1. **Security Widget** (`template: 'security'`):
- Status indicator (ok/warning/error)
- Metric rows with labels/values
- Last event timestamp
- Color-coded border (red)
2. **Network Widget** (`template: 'network'`):
- Active connections count
- Bandwidth display (up/down) with auto-formatting
- Custom metrics support
- Color-coded border (blue)
3. **Monitoring Widget** (`template: 'monitoring'`):
- Health status badge (healthy/degraded/down)
- Metrics grid (responsive cards)
- Uptime display with formatting
- Color-coded border (green)
4. **Hosting Widget** (`template: 'hosting'`):
- Services list with running/stopped status
- Service status icons (✓/✗)
- Metrics section
- Color-coded border (orange)
5. **Compact Widget** (`template: 'compact'`):
- Small icon + title
- Large primary metric value
- Label text
- Minimal space usage
6. **Default Widget** (`template: 'default'`):
- Fallback for apps without specific template
- Icon + title + status
- Simple display
### Features
- **Custom Templates**: `registerTemplate(name, {render: fn})` API
- **Metric Rendering**: `renderMetric()`, `renderMetricCard()` helpers
- **Data Formatting**: Bandwidth, uptime, timestamps (relative)
- **Error Handling**: Try-catch with error display
- **Loading States**: Spinner + message
- **Polling Management**: Automatic cleanup on destroy
## Widget Styles
**New**: `/secubox-admin/widgets.css` (~600 lines)
Comprehensive responsive styles:
### Grid System
- `.widget-grid-auto`: Auto-fill minmax(300px, 1fr)
- `.widget-grid-fixed-2/3/4`: Fixed column grids
- Responsive breakpoints: 1400px → 1024px → 768px
- Mobile: Single column layout
### Widget Components
- **Widget Item**: Card with shadow, hover effects, transform
- **Widget Header**: Icon + title + status indicator/badge
- **Metrics**: Row layout and grid layout variants
- **Status Colors**: Success (green), warning (orange), error (red), unknown (gray)
- **Loading State**: Animated spinner with message
- **Error State**: Icon + message + details
### Category Styling
- Left border color coding by category
- Security: Red (#f44336)
- Network: Blue (#2196f3)
- Monitoring: Green (#4caf50)
- Hosting: Orange (#ff9800)
- Productivity: Purple (#9c27b0)
### Dark Mode Support
- Media query for `prefers-color-scheme: dark`
- Adjusted backgrounds, borders, text colors
- Maintains readability and contrast
### Print Styles
- Break-inside: avoid for widgets
- Border styles for print
- Block layout (no grid)
## Dashboard Integration
**Modified**: `view/secubox-admin/dashboard.js`
Enhanced with widget support:
### Changes
1. Import `widget-renderer` module
2. Add widget renderer instance: `widgetRenderer: null`
3. Load widgets.css stylesheet
4. New section: `renderWidgetsSection(apps)`
- Filters apps with `widget.enabled === true`
- Shows widget count
- Creates container `#dashboard-widgets-container`
5. New method: `initializeWidgets(apps)`
- Creates WidgetRenderer instance
- Config: 30s refresh, auto grid mode
- Renders all enabled widgets
6. Lifecycle: `addFooter()`
- Cleanup widget renderer on page leave
- Removes all poll handles
### Widget Section UI
- Card layout matching other dashboard sections
- Header with "App Widgets" title + count
- Container for widget grid
- Initialized via `requestAnimationFrame` (DOM ready)
## Widget Configuration Schema
Apps in catalog.json can include:
```json
{
"id": "app-id",
"widget": {
"enabled": true,
"template": "security|network|monitoring|hosting|compact|default",
"refresh_interval": 30,
"metrics": [
{
"id": "active_sessions",
"label": "Active Sessions",
"type": "counter",
"source": "ubus",
"method": "app.get_sessions"
}
]
}
}
```
## Data Flow
```
Dashboard Init
↓
WidgetRenderer.render()
↓
For each app with widget.enabled:
├── Create widget container (DOM)
├── Show loading spinner
├── API.getWidgetData(app_id)
↓
RPCD: luci.secubox.get_widget_data(app_id)
↓
Return widget data (metrics, status, etc.)
↓
Template.render(container, app, data)
↓
Display widget with live data
↓
Poll every N seconds (refresh_interval)
```
## Widget Renderer API
```javascript
// Create renderer
var renderer = new WidgetRenderer({
containerId: 'widget-container',
apps: appsWithWidgets,
defaultRefreshInterval: 30,
gridMode: 'auto' // 'auto', 'fixed-2', 'fixed-3', 'fixed-4'
});
// Render all widgets
renderer.render();
// Register custom template
renderer.registerTemplate('mytemplate', {
render: function(container, app, data) {
container.innerHTML = '<div>...</div>';
}
});
// Cleanup
renderer.destroy();
```
## Key Features Delivered
✅ **Pluggable template system** for different app categories
✅ **Responsive grid layout** with breakpoints
✅ **Auto-refresh** with configurable intervals per widget
✅ **Error handling** with graceful degradation
✅ **Loading states** with spinners
✅ **Dark mode** support via media queries
✅ **Category styling** with color-coded borders
✅ **Lifecycle management** with cleanup
✅ **Formatting utilities** for bandwidth, uptime, timestamps
✅ **Print-friendly** styles
## Files Changed/Created
**Created (2)**:
- `luci-app-secubox-admin/htdocs/luci-static/resources/secubox-admin/widget-renderer.js`
- `luci-app-secubox-admin/htdocs/luci-static/resources/secubox-admin/widgets.css`
**Modified (1)**:
- `luci-app-secubox-admin/htdocs/luci-static/resources/view/secubox-admin/dashboard.js`
**Total**: ~1,100 lines added
## Next Steps
To enable widgets for apps:
1. Add `widget` section to app entries in catalog.json
2. Implement `get_widget_data()` in app's RPCD handler
3. Return metrics, status, and relevant data
4. Widget will auto-refresh and display on dashboard
Example apps ready for widgets:
- Auth Guardian (security template)
- Bandwidth Manager (network template)
- System monitors (monitoring template)
- Hosting services (hosting template)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
CyberMind-FR
f2ee564b1a