Widgets, Complications and Controls (WidgetKit)

// Shared/SharedNoteAccess.swift  (target membership: FieldNotes, FieldNotesWatch, FieldNotesWidgets, FieldNotesWatchWidgets)
import SwiftData
import FieldNotesModel
import FieldNotesServices

enum SharedNoteAccess {
    /// Widget and control kinds, shared so the app can reload them without linking the extension's types.
    static let pinnedNotesWidgetKind = "PinnedNotesWidget"
    static let lastNotePinControlKind = "com.example.fieldnotes.LastNotePinControl"

    /// One container per process: the app, each extension and every intent in it share this instance, so a
    /// process never opens the store (or, in the app, its CloudKit mirroring) twice.
    private nonisolated static let shared = Result {
        SwiftDataNotePersistence(modelContainer: try ModelContainer.fieldNotes())
    }

    /// The App Group store for this process.
    static func persistence() throws -> SwiftDataNotePersistence {
        try shared.get()
    }

    /// Only pinned notes are fetched (see `pinnedNotes(limit:)` on the SwiftData page), so a reload never loads
    /// the whole library into the widget extension's small memory budget.
    static func pinnedNotes(taggedWith tag: String? = nil, limit: Int = 4) async throws -> [Note] {
        let persistence = try persistence()
        guard let tag else { return try await persistence.pinnedNotes(limit: limit) }
        // `tags` is an array attribute, so the tag filter runs in Swift, over the pinned notes only.
        return Array(try await persistence.pinnedNotes().filter { $0.tags.contains(tag) }.prefix(limit))
    }
}

// FieldNotesWidgets/PinnedNotes/PinnedNotesEntry.swift
import WidgetKit
import FieldNotesModel

struct PinnedNotesEntry: TimelineEntry {
    let date: Date
    let notes: [Note]
    let tag: String?

    static let sample = PinnedNotesEntry(
        date: .now,
        notes: [Note(title: "Heron nest, north bank", tags: ["birds"], isPinned: true),
                Note(title: "Water sample B-3", tags: ["water"], isPinned: true)],
        tag: nil)
}

// FieldNotesWidgets/PinnedNotes/PinnedNotesConfiguration.swift
import AppIntents

struct PinnedNotesConfiguration: WidgetConfigurationIntent {
    static let title: LocalizedStringResource = "Pinned Notes"
    static let description = IntentDescription("Shows your most recent pinned notes.")

    @Parameter(title: "Only notes tagged")
    var tag: String?
}

// FieldNotesWidgets/PinnedNotes/PinnedNotesProvider.swift
import WidgetKit

struct PinnedNotesProvider: AppIntentTimelineProvider {
    func placeholder(in context: Context) -> PinnedNotesEntry {
        .sample
    }

    func snapshot(for configuration: PinnedNotesConfiguration, in context: Context) async -> PinnedNotesEntry {
        if context.isPreview { return .sample }                  // widget gallery: never wait on disk
        return await entry(for: configuration, limit: Self.limit(for: context.family))
    }

    func timeline(for configuration: PinnedNotesConfiguration, in context: Context) async -> Timeline<PinnedNotesEntry> {
        let entry = await entry(for: configuration, limit: Self.limit(for: context.family))
        // Pinned notes change on events, not on a clock. The app and push updates ask for reloads;
        // the four-hour fallback only keeps relative dates honest if nothing else happens.
        return Timeline(entries: [entry], policy: .after(.now.addingTimeInterval(4 * 60 * 60)))
    }

    private func entry(for configuration: PinnedNotesConfiguration, limit: Int) async -> PinnedNotesEntry {
        let notes = (try? await SharedNoteAccess.pinnedNotes(taggedWith: configuration.tag, limit: limit)) ?? []
        return PinnedNotesEntry(date: .now, notes: notes, tag: configuration.tag)
    }

    private static func limit(for family: WidgetFamily) -> Int {
        switch family {
        case .systemSmall, .accessoryRectangular: 1
        case .systemMedium: 3
        case .accessoryCircular, .accessoryInline: 1
        default: 6
        }
    }
}

// watchOS has no edit-widget sheet, so recommendations are how a watch face offers this widget: each one is a
// preconfigured `PinnedNotesConfiguration` the user picks when adding the complication. On iOS, iPadOS, macOS
// and visionOS the configuration UI is used instead and these recommendations are ignored. The default
// `recommendations()` is unavailable on watchOS, so a provider shared with `FieldNotesWatchWidgetBundle` must
// implement it.
extension PinnedNotesProvider {
    static let recommendedTags = ["birds", "plants", "water"]    // common field-trip tags; tags are free-form

    func recommendations() -> [AppIntentRecommendation<PinnedNotesConfiguration>] {
        let all = AppIntentRecommendation(intent: PinnedNotesConfiguration(), description: "All pinned notes")
        let tagged = Self.recommendedTags.map { tag in
            let intent = PinnedNotesConfiguration()
            intent.tag = tag
            return AppIntentRecommendation(intent: intent, description: "Pinned: \(tag)")
        }
        return [all] + tagged
    }
}

// FieldNotesWidgets/PinnedNotes/PinnedNotesWidget.swift
import WidgetKit
import SwiftUI

struct PinnedNotesWidget: Widget {
    static let kind = SharedNoteAccess.pinnedNotesWidgetKind

    var body: some WidgetConfiguration {
        AppIntentConfiguration(kind: Self.kind,
                               intent: PinnedNotesConfiguration.self,
                               provider: PinnedNotesProvider()) { entry in
            PinnedNotesWidgetView(entry: entry)
        }
        .configurationDisplayName("Pinned Notes")
        .description("Your latest pinned field notes at a glance.")
        .supportedFamilies(Self.families)
        .containerBackgroundRemovable(true)                // StandBy and CarPlay remove the background
        .pushHandler(PinnedNotesPushHandler.self)          // 26: WidgetKit push updates
        #if os(iOS)
        .disfavoredLocations([.carPlay], for: [.systemMedium, .systemLarge])
        #elseif os(visionOS)
        .supportedMountingStyles([.elevated, .recessed])
        .widgetTexture(.paper)
        #endif
    }

    private static var families: [WidgetFamily] {
        #if os(watchOS)
        [.accessoryCircular, .accessoryRectangular, .accessoryInline, .accessoryCorner]
        #elseif os(macOS)
        [.systemSmall, .systemMedium, .systemLarge]
        #elseif os(visionOS)
        [.systemSmall, .systemMedium, .systemLarge, .systemExtraLargePortrait]
        #else
        [.systemSmall, .systemMedium, .systemLarge, .systemExtraLarge,
         .accessoryCircular, .accessoryRectangular, .accessoryInline]
        #endif
    }
}

// FieldNotesWidgets/PinnedNotes/PinnedNotesWidgetView.swift
import WidgetKit
import SwiftUI
import FieldNotesModel

struct PinnedNotesWidgetView: View {
    let entry: PinnedNotesEntry
    @Environment(\.widgetFamily) private var family

    var body: some View {
        Group {
            switch family {
            case .accessoryInline:
                Text(entry.notes.first?.title ?? "No pinned notes")
            case .accessoryCircular:
                Gauge(value: Double(entry.notes.count), in: 0...6) { Image(systemName: "pin.fill") }
                    .gaugeStyle(.accessoryCircularCapacity)
            #if os(watchOS)
            case .accessoryCorner:
                if let note = entry.notes.first { NoteGlance(note: note) }
            #endif
            case .systemSmall, .accessoryRectangular:
                if let note = entry.notes.first {
                    NoteGlance(note: note)
                        .widgetURL(PinnedNotesWidgetView.url(for: note))
                } else {
                    ContentUnavailableView("No pinned notes", systemImage: "pin.slash")
                }
            default:
                PinnedNotesWidgetList(notes: entry.notes)
            }
        }
        .containerBackground(.fill.tertiary, for: .widget)
    }

    static func url(for note: Note) -> URL {
        URL(string: "fieldnotes://note/\(note.id.uuidString)")!
    }
}

// FieldNotes/FieldNotesApp.swift (excerpt): the parts this page adds
import SwiftUI
import WidgetKit
import FieldNotesServices

@main
struct FieldNotesApp: App {
    @State private var store = AppServices.shared.store   // the single owner, see Background Execution
    @Environment(\.scenePhase) private var scenePhase

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(store)
                .onChange(of: store.notes.filter(\.isPinned)) {
                    WidgetCenter.shared.reloadTimelines(ofKind: SharedNoteAccess.pinnedNotesWidgetKind)
                }
        }
        .onChange(of: scenePhase) { _, phase in
            if phase == .background {
                #if os(iOS) || os(macOS)
                ControlCenter.shared.reloadControls(ofKind: SharedNoteAccess.lastNotePinControlKind)
                #endif
            }
        }
    }
}

// FieldNotesWidgets/PinnedNotes/PinnedNotesWidgetView.swift (continued)
struct NoteGlance: View {
    let note: Note
    @Environment(\.widgetFamily) private var family

    var body: some View {
        #if os(watchOS)
        if family == .accessoryCorner {
            Image(systemName: "pin.fill")
                .widgetLabel { Text(note.title) }            // curved text along the dial
        } else {
            summary
        }
        #else
        summary
        #endif
    }

    private var summary: some View {
        VStack(alignment: .leading, spacing: 2) {
            Label(note.tags.first ?? "Pinned", systemImage: "pin.fill")
                .font(.caption2)
                .widgetAccentable()
            Text(note.title).font(.headline).lineLimit(2)
            Text(note.createdAt, style: .relative).font(.caption2).foregroundStyle(.secondary)
        }
    }
}

// From PinnedNotesWidget.body, iOS only
#if os(iOS)
.disfavoredLocations([.carPlay], for: [.systemMedium, .systemLarge])
#endif

// FieldNotesWidgets/Controls/QuickCaptureControl.swift  (also in FieldNotesWatchWidgets, see watchOS)
#if os(iOS) || os(macOS) || os(watchOS)
import WidgetKit
import SwiftUI
import AppIntents

struct QuickCaptureControl: ControlWidget {
    static let kind = "com.example.fieldnotes.QuickCaptureControl"

    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(kind: Self.kind) {
            ControlWidgetButton(action: OpenFieldNotesScreenIntent(screen: .capture)) {
                Label("Capture Note", systemImage: "square.and.pencil")
            }
        }
        .displayName("Quick Capture")
        .description("Start a new field note.")
    }
}
#endif

// FieldNotesWidgets/Controls/LastNotePinControl.swift
#if os(iOS) || os(macOS)
import WidgetKit
import SwiftUI
import AppIntents

struct LastNotePinControl: ControlWidget {
    static let kind = SharedNoteAccess.lastNotePinControlKind

    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(kind: Self.kind, provider: Provider()) { isPinned in
            ControlWidgetToggle("Pin Last Note", isOn: isPinned, action: SetLastNotePinnedIntent()) { isOn in
                Label(isOn ? "Pinned" : "Not pinned", systemImage: isOn ? "pin.fill" : "pin")
            }
        }
        .displayName("Pin Last Note")
    }

    struct Provider: ControlValueProvider {
        var previewValue: Bool { false }

        func currentValue() async throws -> Bool {
            let notes = try await SharedNoteAccess.persistence().fetchNotes()
            return notes.max(by: { $0.createdAt < $1.createdAt })?.isPinned ?? false
        }
    }
}

struct SetLastNotePinnedIntent: SetValueIntent {
    static let title: LocalizedStringResource = "Pin Last Note"

    @Parameter(title: "Pinned")
    var value: Bool

    func perform() async throws -> some IntentResult {
        let persistence = try SharedNoteAccess.persistence()
        guard var last = try await persistence.fetchNotes().max(by: { $0.createdAt < $1.createdAt }) else {
            return .result()
        }
        last.isPinned = value
        try await persistence.save(last)
        WidgetCenter.shared.reloadTimelines(ofKind: SharedNoteAccess.pinnedNotesWidgetKind)
        return .result()
    }
}
#endif