a81b205e1f
- Add UI_REQUIREMENTS.md with detailed UI component specifications - Add ui-integration-examples.ts with ready-to-use UI components - Document all required UI elements for plugin integration - Include platform-specific UI components (Android/iOS/Web) - Provide complete implementation examples with TypeScript - Add responsive design guidelines and accessibility requirements - Include error handling and status monitoring UI components - Update README.md to reference new UI documentation UI Components Covered: ✅ Permission management dialogs and status displays ✅ Configuration panels for settings and preferences ✅ Status dashboards with real-time monitoring ✅ Platform-specific components (battery optimization, background refresh) ✅ Error handling and recovery UI ✅ Testing and debug components ✅ Complete integration examples with event handling
504 lines
14 KiB
Markdown
504 lines
14 KiB
Markdown
# Daily Notification Plugin - UI Requirements
|
|
|
|
**Author**: Matthew Raymer
|
|
**Version**: 1.0.0
|
|
**Last Updated**: 2025-01-27
|
|
**Purpose**: Comprehensive UI requirements for integrating the Daily Notification Plugin
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The Daily Notification Plugin requires specific UI components to provide a complete user experience for notification management, configuration, and monitoring. This document outlines all required UI elements, their functionality, and implementation patterns.
|
|
|
|
---
|
|
|
|
## Core UI Components
|
|
|
|
### 1. **Permission Management UI**
|
|
|
|
#### **Permission Request Dialog**
|
|
**Purpose**: Request notification permissions from users
|
|
|
|
**Required Elements**:
|
|
- **Title**: "Enable Daily Notifications"
|
|
- **Description**: Explain why notifications are needed
|
|
- **Permission Buttons**:
|
|
- "Allow Notifications" (primary)
|
|
- "Not Now" (secondary)
|
|
- "Never Ask Again" (tertiary)
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface PermissionDialogProps {
|
|
onAllow: () => Promise<void>;
|
|
onDeny: () => void;
|
|
onNever: () => void;
|
|
platform: 'android' | 'ios' | 'web';
|
|
}
|
|
```
|
|
|
|
#### **Permission Status Display**
|
|
**Purpose**: Show current permission status
|
|
|
|
**Required Elements**:
|
|
- **Status Indicator**: Green (granted), Yellow (partial), Red (denied)
|
|
- **Permission Details**:
|
|
- Notifications: granted/denied
|
|
- Background Refresh (iOS): enabled/disabled
|
|
- Exact Alarms (Android): granted/denied
|
|
- **Action Buttons**: "Request Permissions", "Open Settings"
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface PermissionStatusProps {
|
|
status: PermissionStatus;
|
|
onRequestPermissions: () => Promise<void>;
|
|
onOpenSettings: () => void;
|
|
}
|
|
```
|
|
|
|
### 2. **Configuration UI**
|
|
|
|
#### **Notification Settings Panel**
|
|
**Purpose**: Configure notification preferences
|
|
|
|
**Required Elements**:
|
|
- **Enable/Disable Toggle**: Master switch for notifications
|
|
- **Time Picker**: Select notification time (HH:MM format)
|
|
- **Content Type Selection**:
|
|
- Offers (new/changed to me/my projects)
|
|
- Projects (local/new/changed/favorited)
|
|
- People (local/new/changed/favorited/contacts)
|
|
- Items (local/new/changed/favorited)
|
|
- **Notification Preferences**:
|
|
- Sound: on/off
|
|
- Vibration: on/off
|
|
- Priority: low/normal/high
|
|
- Badge: on/off
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface NotificationSettingsProps {
|
|
settings: NotificationSettings;
|
|
onUpdateSettings: (settings: NotificationSettings) => Promise<void>;
|
|
onTestNotification: () => Promise<void>;
|
|
}
|
|
```
|
|
|
|
#### **Advanced Configuration Panel**
|
|
**Purpose**: Configure advanced plugin settings
|
|
|
|
**Required Elements**:
|
|
- **TTL Settings**: Content validity duration (1-24 hours)
|
|
- **Prefetch Lead Time**: Minutes before notification (5-60 minutes)
|
|
- **Retry Configuration**:
|
|
- Max retries (1-5)
|
|
- Retry interval (1-30 minutes)
|
|
- **Storage Settings**:
|
|
- Cache size limit
|
|
- Retention period
|
|
- **Network Settings**:
|
|
- Timeout duration
|
|
- Offline fallback
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface AdvancedSettingsProps {
|
|
config: ConfigureOptions;
|
|
onUpdateConfig: (config: ConfigureOptions) => Promise<void>;
|
|
onResetToDefaults: () => Promise<void>;
|
|
}
|
|
```
|
|
|
|
### 3. **Status Monitoring UI**
|
|
|
|
#### **Notification Status Dashboard**
|
|
**Purpose**: Display current notification system status
|
|
|
|
**Required Elements**:
|
|
- **Overall Status**: Active/Inactive/Paused
|
|
- **Next Notification**: Time until next notification
|
|
- **Last Notification**: When last notification was sent
|
|
- **Content Cache Status**:
|
|
- Last fetch time
|
|
- Cache age
|
|
- TTL status
|
|
- **Background Tasks**:
|
|
- Fetch status
|
|
- Delivery status
|
|
- Error count
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface StatusDashboardProps {
|
|
status: DualScheduleStatus;
|
|
onRefresh: () => Promise<void>;
|
|
onViewDetails: () => void;
|
|
}
|
|
```
|
|
|
|
#### **Performance Metrics Display**
|
|
**Purpose**: Show system performance and health
|
|
|
|
**Required Elements**:
|
|
- **Success Rate**: Percentage of successful notifications
|
|
- **Average Response Time**: Time for content fetch
|
|
- **Error Rate**: Percentage of failed operations
|
|
- **Battery Impact**: Estimated battery usage
|
|
- **Network Usage**: Data consumption statistics
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface PerformanceMetricsProps {
|
|
metrics: PerformanceMetrics;
|
|
onExportData: () => void;
|
|
onViewHistory: () => void;
|
|
}
|
|
```
|
|
|
|
### 4. **Platform-Specific UI**
|
|
|
|
#### **Android-Specific Components**
|
|
|
|
##### **Battery Optimization Dialog**
|
|
**Purpose**: Handle Android battery optimization
|
|
|
|
**Required Elements**:
|
|
- **Warning Message**: "Battery optimization may prevent notifications"
|
|
- **Action Button**: "Open Battery Settings"
|
|
- **Skip Option**: "Continue Anyway"
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface BatteryOptimizationProps {
|
|
onOpenSettings: () => Promise<void>;
|
|
onSkip: () => void;
|
|
onCheckStatus: () => Promise<BatteryStatus>;
|
|
}
|
|
```
|
|
|
|
##### **Exact Alarm Permission Dialog**
|
|
**Purpose**: Request exact alarm permissions
|
|
|
|
**Required Elements**:
|
|
- **Explanation**: Why exact alarms are needed
|
|
- **Permission Button**: "Grant Exact Alarm Permission"
|
|
- **Fallback Info**: "Will use approximate timing if denied"
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface ExactAlarmProps {
|
|
status: ExactAlarmStatus;
|
|
onRequestPermission: () => Promise<void>;
|
|
onOpenSettings: () => Promise<void>;
|
|
}
|
|
```
|
|
|
|
#### **iOS-Specific Components**
|
|
|
|
##### **Background App Refresh Dialog**
|
|
**Purpose**: Handle iOS background app refresh
|
|
|
|
**Required Elements**:
|
|
- **Explanation**: "Background App Refresh enables content fetching"
|
|
- **Settings Button**: "Open Settings"
|
|
- **Fallback Info**: "Will use cached content if disabled"
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface BackgroundRefreshProps {
|
|
enabled: boolean;
|
|
onOpenSettings: () => void;
|
|
onCheckStatus: () => Promise<boolean>;
|
|
}
|
|
```
|
|
|
|
##### **Rolling Window Management**
|
|
**Purpose**: Manage iOS rolling window
|
|
|
|
**Required Elements**:
|
|
- **Window Status**: Current window state
|
|
- **Maintenance Button**: "Maintain Rolling Window"
|
|
- **Statistics**: Window performance metrics
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface RollingWindowProps {
|
|
stats: RollingWindowStats;
|
|
onMaintain: () => Promise<void>;
|
|
onViewStats: () => void;
|
|
}
|
|
```
|
|
|
|
#### **Web-Specific Components**
|
|
|
|
##### **Service Worker Status**
|
|
**Purpose**: Monitor web service worker
|
|
|
|
**Required Elements**:
|
|
- **Worker Status**: Active/Inactive/Error
|
|
- **Registration Status**: Registered/Unregistered
|
|
- **Background Sync**: Enabled/Disabled
|
|
- **Push Notifications**: Supported/Not Supported
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface ServiceWorkerProps {
|
|
status: ServiceWorkerStatus;
|
|
onRegister: () => Promise<void>;
|
|
onUnregister: () => Promise<void>;
|
|
}
|
|
```
|
|
|
|
### 5. **Error Handling UI**
|
|
|
|
#### **Error Display Component**
|
|
**Purpose**: Show errors and provide recovery options
|
|
|
|
**Required Elements**:
|
|
- **Error Message**: Clear description of the issue
|
|
- **Error Code**: Technical error identifier
|
|
- **Recovery Actions**:
|
|
- "Retry" button
|
|
- "Reset Configuration" button
|
|
- "Contact Support" button
|
|
- **Error History**: List of recent errors
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface ErrorDisplayProps {
|
|
error: NotificationError;
|
|
onRetry: () => Promise<void>;
|
|
onReset: () => Promise<void>;
|
|
onContactSupport: () => void;
|
|
}
|
|
```
|
|
|
|
#### **Network Error Dialog**
|
|
**Purpose**: Handle network connectivity issues
|
|
|
|
**Required Elements**:
|
|
- **Error Message**: "Unable to fetch content"
|
|
- **Retry Options**:
|
|
- "Retry Now"
|
|
- "Retry Later"
|
|
- "Use Cached Content"
|
|
- **Offline Mode**: Toggle for offline operation
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface NetworkErrorProps {
|
|
onRetry: () => Promise<void>;
|
|
onUseCache: () => void;
|
|
onEnableOffline: () => void;
|
|
}
|
|
```
|
|
|
|
### 6. **Testing and Debug UI**
|
|
|
|
#### **Test Notification Panel**
|
|
**Purpose**: Test notification functionality
|
|
|
|
**Required Elements**:
|
|
- **Test Button**: "Send Test Notification"
|
|
- **Custom Content**: Input for test message
|
|
- **Test Results**: Success/failure status
|
|
- **Log Display**: Test execution logs
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface TestPanelProps {
|
|
onSendTest: (content?: string) => Promise<void>;
|
|
onClearLogs: () => void;
|
|
logs: string[];
|
|
}
|
|
```
|
|
|
|
#### **Debug Information Panel**
|
|
**Purpose**: Display debug information for troubleshooting
|
|
|
|
**Required Elements**:
|
|
- **System Information**: Platform, version, capabilities
|
|
- **Configuration**: Current settings
|
|
- **Status Details**: Detailed system status
|
|
- **Log Export**: Export logs for support
|
|
|
|
**Implementation**:
|
|
```typescript
|
|
interface DebugPanelProps {
|
|
debugInfo: DebugInfo;
|
|
onExportLogs: () => void;
|
|
onClearCache: () => Promise<void>;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## UI Layout Patterns
|
|
|
|
### 1. **Settings Page Layout**
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Notification Settings │
|
|
├─────────────────────────────────────┤
|
|
│ [Enable Notifications] Toggle │
|
|
│ │
|
|
│ Time: [09:00] [AM/PM] │
|
|
│ │
|
|
│ Content Types: │
|
|
│ ☑ Offers │
|
|
│ ☑ Projects │
|
|
│ ☑ People │
|
|
│ ☑ Items │
|
|
│ │
|
|
│ Preferences: │
|
|
│ Sound: [On] Vibration: [On] │
|
|
│ Priority: [Normal] Badge: [On] │
|
|
│ │
|
|
│ [Test Notification] [Save Settings] │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
### 2. **Status Dashboard Layout**
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Notification Status │
|
|
├─────────────────────────────────────┤
|
|
│ Status: ● Active │
|
|
│ Next: 2 hours 15 minutes │
|
|
│ Last: Yesterday 9:00 AM │
|
|
│ │
|
|
│ Content Cache: │
|
|
│ Last Fetch: 1 hour ago │
|
|
│ Cache Age: Fresh │
|
|
│ TTL: Valid for 23 hours │
|
|
│ │
|
|
│ Background Tasks: │
|
|
│ Fetch: ● Success │
|
|
│ Delivery: ● Success │
|
|
│ Errors: 0 │
|
|
│ │
|
|
│ [Refresh] [View Details] │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
### 3. **Permission Request Layout**
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ Enable Daily Notifications │
|
|
├─────────────────────────────────────┤
|
|
│ │
|
|
│ Get notified about new offers, │
|
|
│ projects, people, and items in │
|
|
│ your TimeSafari community. │
|
|
│ │
|
|
│ • New offers directed to you │
|
|
│ • Changes to your projects │
|
|
│ • Updates from favorited people │
|
|
│ • New items of interest │
|
|
│ │
|
|
│ [Allow Notifications] │
|
|
│ [Not Now] [Never Ask Again] │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Guidelines
|
|
|
|
### 1. **Responsive Design**
|
|
- **Mobile First**: Design for mobile, scale up
|
|
- **Touch Friendly**: Minimum 44px touch targets
|
|
- **Accessibility**: WCAG 2.1 AA compliance
|
|
- **Platform Native**: Use platform-specific design patterns
|
|
|
|
### 2. **State Management**
|
|
- **Loading States**: Show loading indicators
|
|
- **Error States**: Clear error messages
|
|
- **Success States**: Confirmation feedback
|
|
- **Empty States**: Helpful empty state messages
|
|
|
|
### 3. **User Experience**
|
|
- **Progressive Disclosure**: Show advanced options when needed
|
|
- **Contextual Help**: Tooltips and help text
|
|
- **Confirmation Dialogs**: For destructive actions
|
|
- **Undo Functionality**: Where appropriate
|
|
|
|
### 4. **Performance**
|
|
- **Lazy Loading**: Load components when needed
|
|
- **Debounced Inputs**: Prevent excessive API calls
|
|
- **Optimistic Updates**: Update UI immediately
|
|
- **Error Boundaries**: Graceful error handling
|
|
|
|
---
|
|
|
|
## Platform-Specific Considerations
|
|
|
|
### **Android**
|
|
- **Material Design**: Follow Material Design guidelines
|
|
- **Battery Optimization**: Handle battery optimization prompts
|
|
- **Exact Alarms**: Request exact alarm permissions
|
|
- **WorkManager**: Show background task status
|
|
|
|
### **iOS**
|
|
- **Human Interface Guidelines**: Follow iOS design patterns
|
|
- **Background App Refresh**: Handle background refresh settings
|
|
- **Rolling Window**: Show rolling window management
|
|
- **BGTaskScheduler**: Display background task status
|
|
|
|
### **Web**
|
|
- **Progressive Web App**: PWA-compatible design
|
|
- **Service Worker**: Show service worker status
|
|
- **Push Notifications**: Handle push notification permissions
|
|
- **Offline Support**: Offline functionality indicators
|
|
|
|
---
|
|
|
|
## Testing Requirements
|
|
|
|
### **Unit Tests**
|
|
- Component rendering
|
|
- User interactions
|
|
- State management
|
|
- Error handling
|
|
|
|
### **Integration Tests**
|
|
- API integration
|
|
- Permission flows
|
|
- Configuration persistence
|
|
- Cross-platform compatibility
|
|
|
|
### **User Testing**
|
|
- Usability testing
|
|
- Accessibility testing
|
|
- Performance testing
|
|
- Cross-device testing
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
The Daily Notification Plugin requires a comprehensive UI that handles:
|
|
|
|
1. **Permission Management**: Request and display permission status
|
|
2. **Configuration**: Settings and preferences management
|
|
3. **Status Monitoring**: Real-time system status and performance
|
|
4. **Platform-Specific Features**: Android, iOS, and Web-specific components
|
|
5. **Error Handling**: User-friendly error messages and recovery
|
|
6. **Testing and Debug**: Tools for testing and troubleshooting
|
|
|
|
The UI should be responsive, accessible, and follow platform-specific design guidelines while providing a consistent user experience across all platforms.
|
|
|
|
---
|
|
|
|
**Next Steps**:
|
|
1. Implement core UI components
|
|
2. Add platform-specific features
|
|
3. Integrate with plugin API
|
|
4. Test across all platforms
|
|
5. Optimize for performance and accessibility
|