todos/App/Sources/Enumerations/TodoGroup.swift

import Foundation
import SwiftUI

/// Categorizes todo tasks into groups based on their due dates and completion status.
///
/// This enumeration provides a semantic grouping mechanism for organizing and filtering todo tasks throughout the application.
/// Each case represents a distinct category that helps users manage their tasks based on temporal relevance and completion state.
///
/// ## Features
/// - Provides localized titles and icons for each group
/// - Supports filtering of completed tasks within temporal groups
/// - Enables color-coded visual categorization
///
/// ## Groups
/// Groups are categorized into two types:
/// - **Temporal groups** (`.today`, `.upcoming`, `.overdue`): Time-based categorization that can optionally include completed tasks
/// - **Status group** (`.completed`): Contains all completed tasks regardless of due date
enum TodoGroup {
    /// Tasks that have been marked as done, regardless of due date.
    case completed
    /// Tasks with due dates in the past that remain incomplete.
    case overdue
    /// Tasks due on the current day that are not yet completed.
    case today
    /// Tasks due in the future that are not yet completed.
    case upcoming
}

// MARK: - Computed

extension TodoGroup {

    /// Indicates whether this group supports toggling the visibility of completed tasks.
    ///
    /// This property determines if a show/hide completed tasks action should be available for the group.
    ///
    /// - Returns: `true` for temporal groups (`.today`, `.upcoming`, `.overdue`) that can optionally
    ///   show or hide completed tasks. Returns `false` for the `.completed` group since it exclusively
    ///   displays completed tasks.
    var canShowCompleted: Bool {
        self != .completed
    }

    /// The color associated with the task group.
    var color: Color {
        switch self {
            case .completed: .gray
            case .overdue: .red
            case .today: .blue
            case .upcoming: .green
        }
    }

    /// The system icon name for the task group.
    var iconName: String {
        switch self {
            case .completed: "checkmark.circle.fill"
            case .overdue: "calendar.badge.exclamationmark"
            case .today: "calendar.badge.clock"
            case .upcoming: "calendar"
        }
    }

    /// The localized display title for the task group.
    var title: LocalizedStringKey {
        switch self {
            case .completed: "enumeration.todo-group.title.completed"
            case .overdue: "enumeration.todo-group.title.overdue"
            case .today: "enumeration.todo-group.title.today"
            case .upcoming: "enumeration.todo-group.title.upcoming"

        }
    }

}

// MARK: - CaseIterable

extension TodoGroup: CaseIterable {

    /// All todo group cases in their display order.
    ///
    /// The cases are ordered by priority and temporal relevance:
    /// 1. `.today` - Most immediate tasks
    /// 2. `.upcoming` - Future tasks
    /// 3. `.overdue` - Past due tasks requiring attention
    /// 4. `.completed` - Finished tasks
    static var allCases: [TodoGroup] { [.today, .upcoming, .overdue, .completed] }

}

// MARK: - Identifiable

extension TodoGroup: Identifiable {

    /// The unique identifier for the group.
    ///
    /// Uses the case itself as the identifier, enabling use in SwiftUI's `ForEach` and other collection views.
    var id: Self { self }

}