honeyDueKMP/iosApp/TASK_SUMMARY_USAGE_IOS.md

Task Summary Card - iOS Usage Guide

Overview

The TaskSummaryCard SwiftUI component displays task statistics dynamically based on backend data. All metadata (icons, colors, display names) comes from the API.

Files Created

1. Components/TaskSummaryCard.swift - Main component

Note: The component uses the existing Color(hex:) initializer from Design/DesignSystem.swift, so no additional files are needed.

Basic Usage

Example 1: Show All Categories

In ResidenceDetailView.swift or ResidencesListView.swift:

import SwiftUI
import Shared

struct ResidenceDetailView: View {
    let residence: ResidenceSummary

    var body: some View {
        ScrollView {
            VStack(spacing: 16) {
                // Residence info...

                // Task summary with all categories
                TaskSummaryCard(taskSummary: residence.taskSummary)
                    .padding(.horizontal)
            }
        }
    }
}

Example 2: Show Only Specific Categories

For the main residence list, show only key categories:

struct ResidenceCard: View {
    let residence: ResidenceSummary

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(residence.name)
                .font(.title2)
                .fontWeight(.bold)

            Text(residence.streetAddress)
                .font(.subheadline)
                .foregroundColor(.secondary)

            // Only show overdue, current, and in progress
            TaskSummaryCard(
                taskSummary: residence.taskSummary,
                visibleCategories: [
                    "overdue_tasks",
                    "current_tasks",
                    "in_progress_tasks"
                ]
            )
        }
        .padding()
        .background(Color(.systemBackground))
        .cornerRadius(12)
        .shadow(radius: 2)
    }
}

Example 3: In Home Screen

struct HomeScreenView: View {
    @StateObject private var viewModel = ResidenceViewModel()

    var body: some View {
        ScrollView {
            VStack(spacing: 20) {
                ForEach(viewModel.residences, id: \.id) { residence in
                    VStack(alignment: .leading, spacing: 12) {
                        NavigationLink(destination: ResidenceDetailView(residence: residence)) {
                            VStack(alignment: .leading) {
                                Text(residence.name)
                                    .font(.headline)

                                // Show task summary for quick overview
                                TaskSummaryCard(
                                    taskSummary: residence.taskSummary,
                                    visibleCategories: ["overdue_tasks", "current_tasks"]
                                )
                            }
                        }
                    }
                    .padding()
                }
            }
        }
    }
}

Available Categories

The backend provides these categories (can filter with visibleCategories):

1. overdue_tasks - Red (#FF3B30) - exclamationmark.triangle
2. current_tasks - Blue (#007AFF) - calendar
3. in_progress_tasks - Orange (#FF9500) - play.circle
4. backlog_tasks - Purple (#5856D6) - tray
5. done_tasks - Green (#34C759) - checkmark.circle
6. archived_tasks - Gray (#8E8E93) - archivebox

Customization

Custom Styling

TaskSummaryCard(taskSummary: taskSummary)
    .padding()
    .background(Color(.secondarySystemBackground))
    .cornerRadius(16)
    .shadow(color: Color.black.opacity(0.2), radius: 8, x: 0, y: 4)

Filter Specific Categories

// Show only active tasks
TaskSummaryCard(
    taskSummary: taskSummary,
    visibleCategories: [
        "overdue_tasks",
        "current_tasks",
        "in_progress_tasks",
        "backlog_tasks"
    ]
)

Access Individual Category Counts

If you need to access counts programmatically:

extension TaskSummary {
    func categoryCount(for name: String) -> Int {
        categories.first { $0.name == name }?.count ?? 0
    }
}

// Usage:
let overdueCount = taskSummary.categoryCount(for: "overdue_tasks")

Component Features

✅ Dynamic Icons - Uses SF Symbols from backend (e.g., calendar, exclamationmark.triangle) ✅ Dynamic Colors - Parses hex colors from backend ✅ Flexible Filtering - Show only categories you need ✅ Live Preview - Includes SwiftUI preview with mock data ✅ Responsive - Adapts to different screen sizes ✅ Native Look - Uses iOS design patterns and typography

Preview

The component includes a preview for development. In Xcode:

1. Open Components/TaskSummaryCard.swift
2. Click "Resume" in the preview canvas
3. See both "all categories" and "filtered" versions

Integration Example

Here's a complete example for ResidenceDetailView:

import SwiftUI
import Shared

struct ResidenceDetailView: View {
    let residence: ResidenceSummary
    @State private var showingManageUsers = false
    @State private var showingTasks = false

    var body: some View {
        ScrollView {
            VStack(alignment: .leading, spacing: 20) {
                // Header
                VStack(alignment: .leading, spacing: 8) {
                    Text(residence.name)
                        .font(.title)
                        .fontWeight(.bold)

                    Text(residence.streetAddress)
                        .font(.subheadline)
                        .foregroundColor(.secondary)
                }
                .padding(.horizontal)

                // Task Summary Card
                TaskSummaryCard(
                    taskSummary: residence.taskSummary,
                    visibleCategories: [
                        "overdue_tasks",
                        "current_tasks",
                        "in_progress_tasks"
                    ]
                )
                .padding(.horizontal)
                .onTapGesture {
                    showingTasks = true
                }

                // Other residence details...
            }
            .padding(.vertical)
        }
        .navigationTitle("Residence Details")
        .navigationBarTitleDisplayMode(.inline)
        .sheet(isPresented: $showingTasks) {
            TasksView(residenceId: residence.id)
        }
    }
}

Benefits

✅ Backend-Driven - All icons, colors, names from API ✅ Single Source of Truth - Change in task/constants.py updates everywhere ✅ Type-Safe - Full Swift type safety with Shared models ✅ Reusable - Use in any view that has TaskSummary ✅ Consistent - Matches Android implementation ✅ Maintainable - No hardcoded values

Troubleshooting

Colors not showing correctly

Make sure Extensions/Color+Hex.swift is included in your target.

Icons not appearing

The component uses SF Symbols. Ensure the icon names from backend are valid SF Symbol names.

Type errors

Make sure you're importing Shared module which contains the TaskSummary models.

Preview not working

The preview uses mock data. If you get compiler errors, make sure all model types are properly imported.