Reflect/docs/Apple-Features.md

Apple Platform Features

This document covers the new Apple-specific features integrated into Feels, including how to trigger and test each one.

---

1. Control Center Widget

File: FeelsWidget2/FeelsWidget.swift (FeelsMoodControlWidget)

What it does: Adds a quick-access button to Control Center that opens Feels to log your mood.

How to Add to Control Center

1. Open Settings > Control Center
2. Scroll down to find Feels - Log Mood
3. Tap the + button to add it
4. Alternatively: Swipe down from top-right, tap + button, find Feels

How to Test

1. Add the widget to Control Center (steps above)
2. Open Control Center (swipe down from top-right corner)
3. Tap the "Log Mood" button
4. Feels app should open

Implementation Details

• Uses ControlWidget and StaticControlConfiguration
• OpenFeelsIntent (AppIntent) handles the button tap
• openAppWhenRun = true ensures the app opens

---

2. HealthKit State of Mind API

File: Shared/HealthKitManager.swift

What it does: Syncs mood entries to Apple Health using the State of Mind API, allowing users to see mood correlations with sleep, exercise, and other health metrics.

Setup Required

1. Enable HealthKit in Settings > Feels > Health
2. Grant write permission for "State of Mind"

How to Test

1. Go to Feels settings and enable HealthKit sync
2. Log a mood entry
3. Open Apple Health app
4. Go to Browse > Mental Wellbeing > State of Mind
5. Your mood entry should appear with the corresponding valence

Mood to Valence Mapping

Mood	Valence	HealthKit Labels
Horrible	-1.0	stressed, anxious
Bad	-0.5	sad, discouraged
Average	0.0	peaceful, content
Good	0.5	happy, joyful
Great	1.0	excited, grateful

Implementation Details

• Uses HKStateOfMind with kind: .dailyMood
• Valence ranges from -1.0 (very unpleasant) to 1.0 (very pleasant)
• Automatically syncs when mood is logged (if enabled)

---

3. App Intents / Siri Shortcuts

File: Shared/AppShortcuts.swift

What it does: Enables voice-activated mood logging via Siri and adds shortcuts to the Shortcuts app.

Available Shortcuts

Log Mood

• Phrases:
  • "Log my mood in Feels"
  • "Log mood as [mood] in Feels"
  • "Record my mood in Feels"
  • "I'm feeling [mood] in Feels"
  • "Track my mood in Feels"

Check Today's Mood

• Phrases:
  • "What's my mood today in Feels"
  • "Check today's mood in Feels"
  • "How am I feeling in Feels"

Get Mood Streak

• Phrases:
  • "What's my mood streak in Feels"
  • "Check my streak in Feels"
  • "How many days in a row in Feels"

How to Test

1. Say "Hey Siri, log my mood in Feels"
2. Siri will prompt you to select a mood (Horrible, Bad, Average, Good, Great)
3. Confirm selection
4. Siri responds with confirmation and shows a visual snippet

How to Add to Shortcuts App

1. Open Shortcuts app
2. Tap + to create new shortcut
3. Search for "Feels"
4. Available actions: Log Mood, Check Today's Mood, Get Mood Streak

Implementation Details

• MoodEntity provides the mood options for Siri parameter selection
• LogMoodIntent saves to DataController and optionally syncs to HealthKit
• MoodLoggedSnippetView shows visual confirmation in Siri

---

4. TipKit

File: Shared/FeelsTips.swift

What it does: Shows contextual tips to help users discover features throughout the app.

Available Tips

Tip	Location	Trigger
CustomizeLayoutTip	Customize screen	First visit
AIInsightsTip	Insights tab	After 7 days of data
SiriShortcutTip	Settings	After 3 mood logs
HealthKitSyncTip	Settings	After 5 mood logs
WidgetVotingTip	Day view	After first mood log
TimeViewTip	Day view header	After 2 days usage
MoodStreakTip	Day view	When streak >= 3
ControlCenterTip	Settings	After 10 mood logs

How to Test

1. Tips appear automatically based on conditions
2. To reset tips for testing, add this code temporarily:

try? Tips.resetDatastore()

3. Or use the Tips debug menu in Xcode:
   • Edit Scheme > Run > Arguments
   • Add: -com.apple.TipKit.DisplayFrequency weekly

Implementation Details

• TipsManager.shared.configure() called in FeelsApp.init()
• Each tip has rules based on @Parameter events and conditions
• Tips automatically dismiss after user interaction

---

5. Live Activities

Files:

• Shared/MoodStreakActivity.swift (Manager + Attributes)
• FeelsWidget2/FeelsWidget.swift (Widget views)

What it does: Shows mood streak progress on the Lock Screen and Dynamic Island.

How to Start a Live Activity

// In your code where you want to start tracking
await LiveActivityManager.shared.startStreakActivity(
    streak: currentStreak,
    lastMood: todaysMood,
    hasLoggedToday: true
)

How to Update After Mood Log

LiveActivityManager.shared.updateActivity(
    streak: newStreak,
    mood: loggedMood
)

How to End Activity

await LiveActivityManager.shared.endAllActivities()

Live Activity Views

Lock Screen View

• Shows flame icon with streak count
• Displays today's mood with color indicator
• Shows "Don't break your streak!" prompt if not logged

Dynamic Island

• Compact: Flame icon + streak number
• Expanded: Full streak info, mood status, voting window countdown
• Minimal: Flame icon only

How to Test

1. Ensure Live Activities are enabled: Settings > Feels > Live Activities
2. Start a Live Activity (see code above)
3. Lock your phone to see Lock Screen view
4. On iPhone 14 Pro+, check Dynamic Island

Requirements

• iPhone with iOS 16.1+ (Lock Screen)
• iPhone 14 Pro/Pro Max+ for Dynamic Island
• NSSupportsLiveActivities = true in Info.plist (already configured)

Implementation Details

• MoodStreakAttributes defines the activity data structure
• ActivityConfiguration renders both Lock Screen and Dynamic Island
• Activities automatically end at midnight via scheduleActivityEnd()

---

Entry Types

New entry types added to track mood entry sources:

Type	Raw Value	Description
.siri	7	Logged via Siri voice command
.controlCenter	8	Logged via Control Center widget
.liveActivity	9	Logged via Live Activity tap

---

Entitlements & Info.plist

Entitlements (Feels (iOS).entitlements)

• com.apple.developer.healthkit - HealthKit access
• com.apple.developer.healthkit.access - health-records

Info.plist (Feels--iOS--Info.plist)

• NSSupportsLiveActivities - Enables Live Activities
• NSHealthShareUsageDescription - HealthKit read permission description
• NSHealthUpdateUsageDescription - HealthKit write permission description

Widget Info.plist (FeelsWidgetExtension-Info.plist)

• NSSupportsLiveActivities - Enables Live Activity widget

---

Testing Checklist

• Control Center widget appears and opens app
• Siri responds to "Log my mood in Feels"
• Siri shows mood options and confirms selection
• HealthKit sync writes State of Mind entries
• Tips appear at appropriate times
• Live Activity shows on Lock Screen
• Dynamic Island updates (iPhone 14 Pro+)
• Entry types correctly recorded in database