random

2025-12-19 17:24:00 -06:00
parent 440b04159e
commit 31a68b7102
3 changed files with 265 additions and 1 deletions
--- a/docs/Apple-Features.md
+++ b/docs/Apple-Features.md
@@ -0,0 +1,246 @@
+# 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:
+```swift
+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
+```swift
+// 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
+```swift
+LiveActivityManager.shared.updateActivity(
+    streak: newStreak,
+    mood: loggedMood
+)
+```
+
+### How to End Activity
+```swift
+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