Reflect/docs/Apple-Features.md

Apple Platform Features

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

---

1. Control Center Widget

File: ReflectWidget/ReflectMoodControlWidget.swift (ReflectMoodControlWidget)

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

How to Add to Control Center

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

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. Reflect app should open

Implementation Details

• Uses ControlWidget and StaticControlConfiguration
• OpenReflectIntent (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 > Reflect > Health
2. Grant write permission for "State of Mind"

How to Test

1. Go to Reflect 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 Reflect"
  • "Log mood as [mood] in Reflect"
  • "Record my mood in Reflect"
  • "I'm feeling [mood] in Reflect"
  • "Track my mood in Reflect"

Check Today's Mood

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

Get Mood Streak

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

How to Test

1. Say "Hey Siri, log my mood in Reflect"
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 "Reflect"
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. Custom Tips System

Files:

• Shared/ReflectTips.swift (Tips definitions and manager)
• Shared/Views/TipModalView.swift (Modal UI)

What it does: Shows themed modal tips to help users discover features throughout the app. Tips appear as beautiful sheets that match the app's current theme.

Available Tips

Tip	Location	Trigger
CustomizeLayoutTip	Customize screen	First visit
AIInsightsTip	Insights tab	After 7 moods logged
SiriShortcutTip	Settings	After 3 mood logs
HealthKitSyncTip	Settings	After viewing settings
WidgetVotingTip	Day view	After 2 days usage
TimeViewTip	Day view	First visit
MoodStreakTip	Day view	When streak >= 3

How to Test

1. Tips appear automatically based on conditions (one per session)
2. To reset tips for testing:

ReflectTipsManager.shared.resetAllTips()

3. To disable tips globally:

ReflectTipsManager.shared.tipsEnabled = false

Implementation Details

• ReflectTipsManager.shared.resetSession() called in ReflectApp.init()
• Each tip has isEligible property based on user activity parameters
• Tips show as themed modal sheets with gradient headers
• Only one tip shown per app session

---

5. Live Activities

Files:

• Shared/MoodStreakActivity.swift (Manager + Attributes)
• ReflectWidget/ReflectMoodControlWidget.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 > Reflect > 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 (Reflect (iOS).entitlements)

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

Info.plist (Reflect--iOS--Info.plist)

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

Widget Info.plist (ReflectWidgetExtension-Info.plist)

• NSSupportsLiveActivities - Enables Live Activity widget

---

Testing Checklist

• Control Center widget appears and opens app
• Siri responds to "Log my mood in Reflect"
• 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