//
//  SETTINGS_IMPLEMENTATION_GUIDE.md
//  iSMARTtrain
//
//  Implementation Guide for Units Settings
//

# iSMARTtrain Settings Implementation

## Overview
A complete settings system has been created for the iSMARTtrain app with units preferences (System, Metric, Imperial) that are accessible throughout the app.

## Files Created

### 1. iSMARTtrainSettingsView.swift
- **UnitsPreference enum**: Defines three unit options (System, Metric, Imperial)
- **iSMARTtrainSettingsView**: The settings interface with a clean Form-based design
- Platform-specific styling (radio buttons on macOS, inline picker on iOS)
- Includes descriptions for each option

### 2. UnitsPreferenceHelpers.swift
- Extension methods for formatting measurements based on user preference
- Helper methods include:
  - `formatDistance(_:abbreviated:)` - Formats distances (meters → km/miles)
  - `formatElevation(_:abbreviated:)` - Formats elevation (meters → m/feet)
  - `formatSpeed(_:abbreviated:)` - Formats speed (m/s → km/h or mph)
  - `formatTemperature(_:abbreviated:)` - Formats temperature (C° → C°/F°)
- Computed properties: `usesMetric`, `usesImperial`, `measurementSystem`

### 3. ContentView_iSMARTtrain.swift
- Main content view with NavigationSplitView
- Toolbar with three buttons:
  - **+** button to add items
  - **Import** button (square.and.arrow.down icon)
  - **Settings** button (gear icon) - opens settings sheet/popover
- Settings presented as sheet on iOS, inline window on macOS

### 4. Item_iSMARTtrain.swift
- Basic SwiftData model for Item (as referenced in your schema)

## Integration Points

### In iSMARTtrainApp.swift
The Settings scene has been added for macOS:

```swift
#if os(macOS)
Settings {
    iSMARTtrainSettingsView()
}
#endif
```

This creates the standard macOS menu: **iSMARTtrain → Settings...** (⌘,)

### Access Settings Throughout Your App

In any SwiftUI view, add this property:

```swift
@AppStorage("SettingUnits") private var unitsPreference: UnitsPreference = .system
```

### Using the Helper Methods

```swift
// Example in any view
struct MyView: View {
    @AppStorage("SettingUnits") private var unitsPreference: UnitsPreference = .system
    
    var body: some View {
        VStack {
            // Format a distance of 5000 meters
            Text(unitsPreference.formatDistance(5000))  // "5 km" or "3.11 mi"
            
            // Format an elevation of 1500 meters
            Text(unitsPreference.formatElevation(1500))  // "1,500 m" or "4,921 ft"
            
            // Format a speed of 5.5 m/s
            Text(unitsPreference.formatSpeed(5.5))  // "19.8 km/h" or "12.3 mph"
            
            // Format temperature of 22°C
            Text(unitsPreference.formatTemperature(22))  // "22°C" or "71.6°F"
        }
    }
}
```

### Checking Current System

```swift
// Check which measurement system is in use
switch unitsPreference {
case .system:
    // Uses Locale.current.measurementSystem
case .metric:
    // Always metric
case .imperial:
    // Always imperial
}

// Or use helper properties
if unitsPreference.usesMetric {
    // Display metric units
}

if unitsPreference.usesImperial {
    // Display imperial units
}
```

## User Interface

### iOS/iPadOS
- Toolbar button with gear icon
- Tapping opens a sheet with settings
- "Done" button to dismiss

### macOS
- Toolbar button with gear icon
- Opens settings in a sheet/popover
- **Also available from app menu**: iSMARTtrain → Settings... (⌘,)
- Settings window is resizable with minimum size of 500×300

## Default Behavior
- Default setting: **System** (uses device's locale settings)
- Persists across app launches via AppStorage
- AppStorage key: `"SettingUnits"`

## Customization

### Adding More Settings
To add more settings options, extend `iSMARTtrainSettingsView`:

```swift
struct iSMARTtrainSettingsView: View {
    @AppStorage("SettingUnits") private var unitsPreference: UnitsPreference = .system
    @AppStorage("iSMARTtrain.theme") private var themePreference: ThemePreference = .auto
    
    var body: some View {
        Form {
            Section("Measurement Units") {
                // existing units picker
            }
            
            Section("Appearance") {
                Picker("Theme", selection: $themePreference) {
                    // theme options
                }
            }
        }
    }
}
```

### Custom Formatting
You can add more formatter methods in `UnitsPreferenceHelpers.swift` for other measurement types like:
- Weight (kg/lbs)
- Volume (liters/gallons)
- Pace (min/km or min/mile)

## Notes
- The settings are separate from the FitFileViewer target's SettingsView
- All files are prefixed or namespaced for clarity (iSMARTtrain prefix)
- Uses SwiftUI's native AppStorage for persistence
- Fully compatible with iOS, iPadOS, and macOS
- Default value is `.system` which respects user's device locale

## Testing
Test the settings work correctly by:
1. Changing the setting to each option
2. Verifying measurements update throughout the app
3. Closing and reopening the app to verify persistence
4. Testing on devices with different locale settings (especially with .system option)
