danvics/Pulse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Pulse/.gemini/artifacts/alert-thresholds-redesign-plan.md
rcourtman 41004ebcea feat(thresholds): add collapsible accordion sections and UX improvements 
- Add CollapsibleSection component with animated expand/collapse
- Wrap all 6 resource sections (Nodes, VMs, PBS, Storage, Backups, Snapshots) with accordion UI
- Add section icons and resource counts in headers
- Add expand all / collapse all buttons for quick navigation
- Make help banner dismissible with localStorage persistence
- Add Ctrl/Cmd+F keyboard shortcut to focus search
- Add keyboard shortcut hint badge on search input
- Add icons to tab navigation for quick identification
- Improve mobile tab labels with shorter text on small screens
- Create reusable components: ThresholdBadge, ResourceCard, GlobalDefaultsRow
- Create useCollapsedSections hook with localStorage persistence
- Default less-used sections (Storage, Backups, Snapshots, PBS) to collapsed
2025-12-18 15:47:44 +00:00

325 lines
16 KiB
Markdown
Raw Blame History

# Alert Thresholds Page Redesign
## Executive Summary
The current Alert Thresholds page suffers from information overload, poor scalability, and a monolithic codebase (~3000 lines in a single component). This plan outlines a comprehensive redesign focused on:
1. **Collapsible accordion-based layout** - Users can focus on what matters
2. **Component decomposition** - Maintainable, testable code
3. **Progressive disclosure** - Show summaries first, details on demand
4. **Responsive design** - Works on all screen sizes
5. **Improved visual hierarchy** - Clear information architecture
---
## Current Problems
### User Experience Issues
| Problem | Impact | Current State |
|---------|--------|---------------|
| Information overload | High | 6+ tables stacked vertically, no way to collapse |
| Wide tables | High | 7+ columns cause horizontal scroll |
| No visual hierarchy | Medium | Everything looks equal priority |
| Help banner always visible | Low | Takes space after users understand |
| No density controls | Medium | Can't see more resources at once |
| Unclear tab labels | Low | "Proxmox / PBS" bundles too much |
### Technical Debt
| Problem | Impact |
|---------|--------|
| `ThresholdsTable.tsx` is ~3000 lines | Very hard to maintain |
| Tightly coupled rendering and state | Difficult to test |
| Repeated code patterns | Inconsistent behavior |
| No clear component boundaries | Hard to extend |
---
## Proposed Architecture
### New Component Structure
```
src/components/Alerts/Thresholds/
├── index.ts # Public exports
├── ThresholdsPage.tsx # Main page layout (~200 lines)
├── ThresholdsContext.tsx # State management context
├── sections/
│ ├── CollapsibleSection.tsx # Reusable accordion section
│ ├── ProxmoxNodesSection.tsx # Nodes-specific logic
│ ├── GuestsSection.tsx # VMs/CTs with node grouping
│ ├── StorageSection.tsx # Storage devices
│ ├── PBSSection.tsx # PBS servers
│ ├── BackupsSection.tsx # Backup thresholds
│ └── SnapshotsSection.tsx # Snapshot thresholds
├── components/
│ ├── ResourceCard.tsx # Expandable resource card
│ ├── ThresholdBadge.tsx # Colored threshold pill
│ ├── ThresholdEditor.tsx # Inline/modal threshold editing
│ ├── GlobalDefaultsRow.tsx # Editable defaults row
│ ├── SearchBar.tsx # Enhanced search/filter
│ └── ViewToggle.tsx # List/Compact toggle
├── hooks/
│ ├── useThresholds.ts # Threshold state management
│ ├── useCollapsedSections.ts # Persist collapsed state
│ └── useResourceFilter.ts # Search/filter logic
└── types.ts # TypeScript interfaces
```
### Component Responsibilities
#### `ThresholdsPage.tsx` (~200 lines)
- Page layout and header
- Tab navigation (Proxmox/PBS, Mail Gateway, Hosts, Containers)
- Search bar and view toggle
- Renders appropriate section components based on active tab
#### `CollapsibleSection.tsx` (~150 lines)
- Reusable accordion wrapper
- Expand/collapse with animation
- Header with title, count, and actions
- Persists collapsed state to localStorage
#### `ResourceCard.tsx` (~200 lines)
- Compact collapsed view: Name, status, key thresholds as pills
- Expanded view: Full threshold editing grid
- Handles inline editing
- Shows "Custom" badge when overridden
#### `ThresholdBadge.tsx` (~50 lines)
- Colored pill showing threshold value
- Color indicates severity (green = conservative, red = aggressive, gray = disabled)
- Clickable to edit
---
## New Layout Design
### Page Structure
```
┌─────────────────────────────────────────────────────────────────┐
│ Alert Thresholds │
│ Tune resource thresholds and override rules │
├─────────────────────────────────────────────────────────────────┤
│ [🔍 Search resources...] [List ▼] [💡 Tips] │
├─────────────────────────────────────────────────────────────────┤
│ [Proxmox/PBS] [Mail Gateway] [Host Agents] [Containers] │
╞═════════════════════════════════════════════════════════════════╡
│ │
│ ▼ Proxmox Nodes 2 resources [Edit Defaults]│
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ Global Defaults ││
│ │ [CPU 80%] [Mem 85%] [Disk 90%] [Temp 80°C] ││
│ ├─────────────────────────────────────────────────────────────┤│
│ │ ✓ delly Online [CPU 80%] [Mem 85%] [▼] ││
│ │ ✓ minipc Online [CPU 80%] [Mem 85%] [▼] ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ▼ VMs & Containers 24 resources [Edit Defaults]│
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ Global Defaults ││
│ │ [CPU 80%] [Mem 85%] [Disk 90%] [I/O: Off] ││
│ ├─────────────────────────────────────────────────────────────┤│
│ │ ▼ delly 12 guests ││
│ │ ✓ homeassistant Running [Custom] [CPU 70%] [▼] ││
│ │ ✓ frigate Running [CPU 80%] [▼] ││
│ │ ✓ mqtt Running [CPU 80%] [▼] ││
│ │ ... 9 more ││
│ ├─────────────────────────────────────────────────────────────┤│
│ │ ► minipc 12 guests ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ► Storage 4 resources [Edit Defaults]│
│ │
│ ► PBS Servers 0 resources [Edit Defaults]│
│ │
│ ► Backups [Edit Defaults]│
│ │
│ ► Snapshots [Edit Defaults]│
│ │
└─────────────────────────────────────────────────────────────────┘
```
### Expanded Resource Card
When a resource is expanded:
```
┌─────────────────────────────────────────────────────────────────┐
│ homeassistant [Custom] [Alerts: ON] [▲ Close]│
│ VM 100 • 192.168.1.100 • delly │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Performance Thresholds │
│ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│ │ CPU │ Memory │ Disk │ Temp │ │
│ │ [70 %] │ [85 %] │ [90 %] │ [80°C] │ │
│ └─────────────┴─────────────┴─────────────┴─────────────┘ │
│ │
│ I/O Thresholds │
│ ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│ │ Disk Read │ Disk Write │ Net In │ Net Out │ │
│ │ [Off] │ [Off] │ [Off] │ [Off] │ │
│ └─────────────┴─────────────┴─────────────┴─────────────┘ │
│ │
│ Offline Alerts: [Warning ▼] │
│ │
│ Note: [Production HA instance ] │
│ │
│ [Reset to Defaults] [Save] │
└─────────────────────────────────────────────────────────────────┘
```
---
## Key UX Improvements
### 1. Progressive Disclosure
- **Collapsed by default**: Sections show count and summary only
- **One-click expand**: Click anywhere on header to expand
- **Nested grouping**: VMs/Containers grouped by node, nodes collapsible
- **Remember state**: Collapsed/expanded state persisted in localStorage
### 2. Visual Hierarchy
- **Section headers**: Large, bold, with resource counts
- **Global defaults**: Always visible at top of each section
- **Custom indicators**: Blue "Custom" badge for overridden resources
- **Status colors**: Green checkmarks for healthy, warning/critical indicators
### 3. Threshold Badges
Color-coded pills that instantly communicate threshold severity:
- **Gray**: Disabled (Off)
- **Green**: Conservative (≥85%)
- **Yellow**: Moderate (70-84%)
- **Orange**: Aggressive (50-69%)
- **Red**: Very aggressive (<50%)
### 4. Search & Filter
Enhanced command bar supporting:
- Simple text search: `homeassistant`
- Property filters: `node:delly`, `type:vm`, `custom:true`
- Threshold filters: `cpu>80`, `memory<70`
- Combination: `node:delly custom:true`
### 5. Responsive Design
- **Wide screens**: Full grid layout with all columns
- **Medium screens**: Hide I/O thresholds, show on expand
- **Narrow screens**: Single column cards, full expand for editing
---
## Implementation Phases
### Phase 1: Component Decomposition (Foundation)
**Goal**: Break up `ThresholdsTable.tsx` without changing UI
1. Extract shared types to `types.ts`
2. Create `ThresholdsContext.tsx` for state management
3. Extract `ResourceCard.tsx` from table row rendering
4. Extract `ThresholdBadge.tsx` for threshold display
5. Create section components that wrap current logic
6. Update imports and ensure tests pass
**Deliverable**: Same UI, cleaner code, easier to modify
### Phase 2: Collapsible Sections
**Goal**: Add accordion behavior to sections
1. Create `CollapsibleSection.tsx` component
2. Add collapse/expand animation
3. Persist collapsed state to localStorage
4. Add resource counts to headers
5. Move "Edit Defaults" to section headers
**Deliverable**: Users can collapse sections they don't need
### Phase 3: Resource Cards
**Goal**: Replace table rows with expandable cards
1. Create compact card view (collapsed)
2. Create full editor view (expanded)
3. Add transition animation
4. Implement inline editing
5. Show threshold pills in collapsed view
**Deliverable**: Cleaner resource display, less horizontal scroll
### Phase 4: Enhanced Filtering
**Goal**: Powerful search and filter
1. Create `SearchBar.tsx` with command palette style
2. Implement filter parsers
3. Add quick filter buttons
4. Keyboard navigation support
5. Search highlighting in results
**Deliverable**: Users can quickly find specific resources
### Phase 5: Polish & Accessibility
**Goal**: Production-ready quality
1. Keyboard navigation throughout
2. Screen reader labels
3. Focus management
4. Loading states
5. Error handling
6. Empty states
7. Responsive testing
**Deliverable**: Accessible, polished experience
---
## Success Metrics
| Metric | Current | Target |
|--------|---------|--------|
| Lines in main component | ~3000 | <300 |
| Horizontal scroll needed | Often | Rarely |
| Clicks to find resource | 2-5 + scroll | 1-2 |
| Time to understand page | ~30s | <10s |
| Mobile usability | Poor | Good |
---
## Files to Create/Modify
### New Files
- `src/components/Alerts/Thresholds/index.ts`
- `src/components/Alerts/Thresholds/ThresholdsPage.tsx`
- `src/components/Alerts/Thresholds/ThresholdsContext.tsx`
- `src/components/Alerts/Thresholds/types.ts`
- `src/components/Alerts/Thresholds/sections/CollapsibleSection.tsx`
- `src/components/Alerts/Thresholds/sections/ProxmoxNodesSection.tsx`
- `src/components/Alerts/Thresholds/sections/GuestsSection.tsx`
- `src/components/Alerts/Thresholds/sections/StorageSection.tsx`
- `src/components/Alerts/Thresholds/components/ResourceCard.tsx`
- `src/components/Alerts/Thresholds/components/ThresholdBadge.tsx`
- `src/components/Alerts/Thresholds/components/ThresholdEditor.tsx`
- `src/components/Alerts/Thresholds/components/GlobalDefaultsRow.tsx`
- `src/components/Alerts/Thresholds/hooks/useThresholds.ts`
- `src/components/Alerts/Thresholds/hooks/useCollapsedSections.ts`
### Modified Files
- `src/components/Alerts/ThresholdsTable.tsx` → Eventually deprecated
- `src/pages/Alerts.tsx` → Use new ThresholdsPage
- `src/components/Alerts/ResourceTable.tsx` → Simplify or deprecate
---
## Risk Mitigation
1. **Incremental migration**: Keep old component working during transition
2. **Feature flags**: Can switch between old/new implementations
3. **Comprehensive tests**: Add tests for new components before replacing old
4. **User feedback**: Consider A/B testing or beta flag
---
## Next Steps
1. ✅ Create this implementation plan
2. ⬜ Generate visual mockup for approval
3. ⬜ Begin Phase 1: Component decomposition
4. ⬜ Add tests for extracted components
5. ⬜ Proceed through remaining phases
Reference in a new issue View git blame Copy permalink