# Custom Tips System Documentation

This document describes all tips implemented in the Reflect app, including their display conditions and locations.

## Overview

Tips are displayed as themed modal sheets that match the user's chosen app theme. The system is managed by `ReflectTipsManager` (singleton) and configured with:
- **Display Frequency**: One tip per app session
- **Global Toggle**: `tipsEnabled` boolean in UserDefaults
- **Persistence**: Shown tip IDs stored in UserDefaults

---

## Tips

### 1. CustomizeLayoutTip

**Title**: "Personalize Your Experience"
**Message**: "Customize mood icons, colors, and layouts to make the app truly yours."
**Icon**: `paintbrush.fill`

**Display Conditions**: Always eligible (no rules)

**Location**: CustomizeContentView (via `.customizeLayoutTip()`)

---

### 2. AIInsightsTip

**Title**: "Discover AI Insights"
**Message**: "Get personalized insights about your mood patterns powered by Apple Intelligence."
**Icon**: `brain.head.profile`

**Display Conditions**:
- User has logged at least **7 moods**

**Parameter**: `moodLogCount: Int` (incremented via `ReflectTipsManager.shared.onMoodLogged()`)

**Location**: InsightsView (via `.aiInsightsTip()`)

---

### 3. SiriShortcutTip

**Title**: "Use Siri to Log Moods"
**Message**: "Say 'Hey Siri, log my mood as great in Reflect' for hands-free logging."
**Icon**: `mic.fill`

**Display Conditions**:
- User has logged at least **3 moods**

**Parameter**: `moodLogCount: Int` (incremented via `ReflectTipsManager.shared.onMoodLogged()`)

**Location**: SettingsContentView (Features section header, via `.siriShortcutTip()`)

---

### 4. HealthKitSyncTip

**Title**: "Sync with Apple Health"
**Message**: "Connect to Apple Health to see your mood data alongside sleep, exercise, and more."
**Icon**: `heart.fill`

**Display Conditions**:
- User has viewed the Settings screen

**Parameter**: `hasSeenSettings: Bool` (set via `ReflectTipsManager.shared.onSettingsViewed()`)

**Location**: SettingsContentView (Health Kit toggle, via `.healthKitSyncTip()`)

---

### 5. WidgetVotingTip

**Title**: "Vote from Your Home Screen"
**Message**: "Add the Mood Vote widget to quickly log your mood without opening the app."
**Icon**: `square.grid.2x2.fill`

**Display Conditions**:
- User has been using the app for at least **2 days**

**Parameter**: `daysUsingApp: Int`

**Location**: DayView (via `.widgetVotingTip()`)

---

### 6. TimeViewTip

**Title**: "View Your History"
**Message**: "Switch between Day, Month, and Year views to see your mood patterns over time."
**Icon**: `calendar`

**Display Conditions**: Always eligible (no rules)

**Location**: DayView (via `.timeViewTip()`)

---

### 7. MoodStreakTip

**Title**: "Build Your Streak!"
**Message**: "Log your mood daily to build a streak. Consistency helps you understand your patterns."
**Icon**: `flame.fill`

**Display Conditions**:
- User has a current streak of at least **3 days**

**Parameter**: `currentStreak: Int` (updated via `ReflectTipsManager.shared.updateStreak(_:)`)

**Location**: DayView (via `.moodStreakTip()`)

---

## ReflectTipsManager API

```swift
// Reset session flag (call on app launch)
ReflectTipsManager.shared.resetSession()

// Reset all tips (for testing)
ReflectTipsManager.shared.resetAllTips()

// Update parameters
ReflectTipsManager.shared.onMoodLogged()           // Increments mood log count
ReflectTipsManager.shared.onSettingsViewed()       // Marks settings as viewed
ReflectTipsManager.shared.updateDaysUsingApp(_:)   // Updates days using app
ReflectTipsManager.shared.updateStreak(_:)         // Updates current streak

// Global toggle
ReflectTipsManager.shared.tipsEnabled = true/false
```

---

## View Modifiers

Tips can be attached to views using these convenience modifiers:

```swift
.customizeLayoutTip()
.aiInsightsTip()
.siriShortcutTip()
.healthKitSyncTip()
.widgetVotingTip()
.timeViewTip()
.moodStreakTip()

// Or use the generic modifier with custom gradient colors:
.reflectTip(ReflectTips.customizeLayout, gradientColors: [.purple, .blue])
```

---

## Modal Design

Tips are displayed as themed modal sheets with:
- Gradient header (130pt) matching tip-specific colors
- SF Symbol icon (44pt, white)
- Title and message with theme text color
- "Got it" dismiss button with gradient background
- Spring animation on appearance

---

## Files

- **Tips & Manager**: `Shared/ReflectTips.swift`
- **Modal View**: `Shared/Views/TipModalView.swift`
- **Configuration**: `ReflectTipsManager.shared.resetSession()` called in `ReflectApp.swift`