Kordant/tasks/ios-production/15-home-screen-widgets.md

15. Home Screen Widgets

meta: id: ios-production-15 feature: ios-production priority: P2 depends_on: [] tags: [native-features, widgets, production]

objective:

• Implement home screen widgets to display threat score and recent alerts at a glance

deliverables:

• Widget extension target
• Small, medium, and large widget sizes
• Widget configuration intent
• Timelines with refresh strategy

steps:

1. Create widget extension:
   • Add Widget Extension target in Xcode
   • Configure app group for data sharing
   • Set up widget bundle with multiple widgets
2. Design widgets:
   • Small widget: Threat score gauge only
   • Medium widget: Threat score + 2 recent alerts
   • Large widget: Threat score + alert list + quick actions
   • Use SwiftUI for widget UI
   • Match app design system colors
3. Implement widget timeline:
   • Create TimelineProvider
   • Fetch data from shared UserDefaults or App Group
   • Update every 15 minutes (widget limit)
   • Handle placeholder, snapshot, and timeline entries
4. Add widget configuration:
   • Intent for selecting widget type (if multiple variants)
   • Intent for filtering alerts by severity
   • Configuration UI in widget gallery
5. Share data with widget:
   • Write threat score and alerts to shared container
   • Update shared data when app refreshes
   • Use WidgetCenter to reload timelines after app update
6. Add deep linking:
   • Tap widget → open app to relevant screen
   • Tap alert in widget → open alert detail
   • Tap threat score → open dashboard

tests:

• Unit: Test timeline provider data formatting
• UI: Test widget rendering in all sizes
• Integration: Test data sharing between app and widget

acceptance_criteria:

• Widget extension building and running
• Small widget showing threat score
• Medium widget showing threat score + recent alerts
• Large widget showing full alert summary
• Widgets update every 15 minutes
• Data shared correctly between app and widget
• Deep links from widget to correct app screens
• Widgets match app design system
• Placeholder and snapshot states look good
• Widgets work in dark mode
• No crashes when widget data is missing

validation:

• Add widget to home screen → displays current threat score
• Receive new alert → widget updates within 15 minutes
• Tap widget → app opens to dashboard
• Tap specific alert in widget → alert detail opens
• Check widget in dark mode → colors correct

notes:

• Widgets cannot make network requests directly
• App must write data to shared container for widgets to read
• Widget memory limits are strict (especially for small widgets)
• Use WidgetCenter.reloadTimelines(ofKind:) to force updates