lanework/Kanban/App/TemplateChooserView.swift

import AppKit
import SwiftUI
import os

/// The template chooser — File ▸ New Board… (⌥⌘N), 09-templates.md's picker.
///
/// ### Pages' shape, over real board folders
///
/// A grid of template cards, each showing a **mini per-lane preview** above its name, one selected at
/// a time, with Cancel and Choose at the bottom (03-board-ui.md § Welcome screen & templates: "a
/// Pages-style chooser with a mini per-lane preview per template"). The grid is filled by
/// `TemplateEngine.chooserRows()` — the app bundle's `Templates/` folder, then the user store — each
/// entry loaded through the ordinary `BoardLoader`, so name, blurb, icon and preview all come off the
/// template board's own `index.md` rather than from a Swift catalog.
///
/// **The order is 09's, and it is the engine's** (09 ▸ Storage: "bundled templates by
/// `template.order`, then keyed user templates by `template.order`, then keyless user boards last,
/// sorted by display name"). This view renders the list it is handed and never re-sorts it.
///
/// ### One bad template never fails the chooser
///
/// A user-store folder the loader rejects is **listed anyway** — by folder name, marked unloadable,
/// carrying the loader's fail-fast specifics, not previewable and not choosable (09 ▸ Why this
/// format). The store is hand-editable, so a malformed board there is one edit away; a chooser that
/// refused to open, or that silently dropped the row, would leave the user with no way to see which
/// folder is broken or why. Selecting the row shows the loader's own sentence where a blurb would be.
///
/// ### Reveal in Finder, and how fresh the list is
///
/// 09 keeps the Application Support store honest with "a **Reveal in Finder** affordance in the
/// template chooser": the button beside the header, which **creates the store and then reveals it**
/// (`TemplateEngine.createUserStore`) — the store's two minters are Save as Template and this, so a
/// user who has never saved one still gets a folder to drop a board into rather than a Finder window
/// full of nothing.
///
/// **The store is not watched** — 09 asks for a Reveal affordance, not a live folder — so the list is
/// re-read on every presentation and again whenever the app comes back to the front. The second is
/// the Reveal round trip made honest: the user reveals the folder, drops a board in, comes back, and
/// the row is there. A folder dropped in with this window already frontmost appears on the next
/// activation or the next opening, which is the documented minimum rather than an oversight.
///
/// ### Choosing is three steps, and the middle one is a save panel
///
/// Choose runs `NSSavePanel`, instantiates into the chosen location, and opens the result. The panel
/// is not ceremony: a sandboxed app cannot write anywhere the user has not pointed at, so the panel
/// *is* how a new board gets a location it is allowed to occupy (09 files this under "seed the save
/// panel's suggested name"). The chooser stays open if the panel is cancelled — a cancelled location
/// is not a cancelled choice.
///
// m9-templates: the in-progress row with Cancel that copy-shaped work is owed (02-architecture.md
// § The banner surface) still has nowhere to live here — this window has no banner surface, and the
// board that would host one does not exist yet. The engine takes the cancellation seam
// (`TemplateEngine.instantiate(…, isCancelled:)`) and this view runs the copy off the main actor, so
// the row has something to spin over when the window grows a strip. Save as Template, whose copy
// *does* have a board window behind it, already carries its row.
///
/// ### Failure is an alert here, deliberately
///
/// Everywhere else in the app a failed write is a banner in the window that produced it
/// (02-architecture.md § Write-failure surfacing). A failed *create* has no such window: the board
/// that would host the banner is the one that did not get created, welcome may not be open (⌥⌘N
/// works from a board window), and filing it under `AppModel.launchFailures` would put it in a
/// recents-adjacent list belonging to boards the registry knows — which this one, having never
/// existed, is not. So it is an `NSAlert`, continuing the modal conversation the user is already in
/// with the save panel, in the same sentence the banner would have used
/// (`BannerCenter.headline(for:)`) so the app has one vocabulary for a failed write rather than two.
struct TemplateChooserView: View {

    @Environment(AppModel.self) private var appModel
    @Environment(\.dismiss) private var dismiss

    /// The chooser's rows — both tiers, in 09's order, re-read on presentation and on activation
    /// (see the type's doc). `@State` rather than a computed property because discovery *loads every
    /// template board*, and a computed one would re-run that on every SwiftUI rebuild.
    @State private var rows: [TemplateRow] = []

    @State private var selection: TemplateRow.ID?

    private static let logger = Logger(subsystem: "dev.rzen.indie.Kanban", category: "templates")

    /// The selected row, defaulting to the first — which is Basic, the bundled tier's lowest order,
    /// so the chooser always opens with something choosable in hand.
    private var selected: TemplateRow? {
        rows.first { $0.id == selection } ?? rows.first
    }

    var body: some View {
        VStack(spacing: 0) {
            header
            Divider()
            grid
            Divider()
            footer
        }
        .frame(width: 620, height: 480)
        .task {
            rescan()
            // Returning to the foreground is when a folder dropped into the revealed store becomes
            // this window's problem — `ClipboardStore`'s activation observer, in the shape a view can
            // hold: the sequence ends with the task, which ends with the window.
            for await _ in NotificationCenter.default.notifications(named: NSApplication.didBecomeActiveNotification) {
                rescan()
            }
        }
    }

    /// Re-reads both stores, keeping the selection if the row it named is still there.
    private func rescan() {
        rows = TemplateEngine.chooserRows()
        if let selection, !rows.contains(where: { $0.id == selection }) {
            self.selection = nil
        }
    }

    // MARK: Header

    private var header: some View {
        HStack(alignment: .firstTextBaseline) {
            VStack(alignment: .leading, spacing: 2) {
                Text("Choose a Template")
                    .font(.title3.weight(.semibold))
                Text("Every template is an ordinary board — lanes and cards you can change afterwards.")
                    .font(.callout)
                    .foregroundStyle(.secondary)
            }

            Spacer(minLength: 16)

            // 09's honesty affordance: the store is plain board folders, and this is where the user
            // is shown that. It mints the folder on the way — see the type's doc.
            Button {
                revealUserStore()
            } label: {
                Label("My Templates", systemImage: "folder")
            }
            .help("Reveal your templates folder in the Finder. Any board folder you put there becomes a template.")
        }
        .padding(20)
    }

    // MARK: Grid

    private var grid: some View {
        ScrollView {
            LazyVGrid(columns: [GridItem(.adaptive(minimum: 170), spacing: 20)], spacing: 20) {
                ForEach(rows) { row in
                    TemplateCard(row: row, isSelected: row.id == selected?.id)
                        .onTapGesture { selection = row.id }
                        // The list convention welcome's recents use, for the same reason: a
                        // double click is how a chooser is answered without reaching for a button.
                        .onTapGesture(count: 2) { choose() }
                        .accessibilityAddTraits(row.id == selected?.id ? [.isSelected] : [])
                }
            }
            .padding(20)
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
        .background(Color(nsColor: .controlBackgroundColor))
    }

    // MARK: Footer

    /// The blurb — or, for an unloadable row, **the loader's own sentence**: fail-fast's specifics,
    /// unreworded, in the place the description would have been. It is the whole of what the user
    /// needs to go and fix the file.
    private var footer: some View {
        HStack(alignment: .firstTextBaseline) {
            if let unloadable = selected?.unloadable {
                Label(BannerCenter.headline(for: unloadable.error), systemImage: "exclamationmark.triangle")
                    .font(.callout)
                    .foregroundStyle(.secondary)
                    .lineLimit(2)
            } else {
                Text(selected?.template?.blurb ?? "")
                    .font(.callout)
                    .foregroundStyle(.secondary)
                    .lineLimit(2)
            }

            Spacer(minLength: 16)

            Button("Cancel", role: .cancel) { dismiss() }
                .keyboardShortcut(.cancelAction)

            Button("Choose") { choose() }
                .keyboardShortcut(.defaultAction)
                // An unloadable row "can't be instantiated or previewed" (09), which is this line.
                .disabled(selected?.template == nil)
        }
        .padding(20)
    }

    // MARK: - Reveal

    /// Creates the user store if it isn't there, then reveals it — 09's affordance, and one of the
    /// store's two minters (`TemplateEngine.createUserStore`).
    ///
    /// A store that cannot be created is logged and *still* revealed at its parent by
    /// `activateFileViewerSelecting`, which is the honest failure: something is wrong with
    /// Application Support, and the user is standing where they can see it.
    private func revealUserStore() {
        let store = TemplateEngine.userStore
        do {
            try TemplateEngine.createUserStore(at: store)
        } catch {
            Self.logger.error("could not create the user template store: \(error.localizedDescription, privacy: .public)")
        }
        NSWorkspace.shared.activateFileViewerSelecting([store])
    }

    // MARK: - Choosing

    /// Panel, instantiate, open — and only then dismiss, so a cancelled panel leaves the chooser
    /// exactly as the user left it.
    ///
    /// The copy runs in a detached task, `DuplicateBoardCommand`'s reasoning at a smaller scale: a
    /// user template can be a real board with real attachments, and a main thread blocked inside a
    /// tree copy is a frozen window. Detached rather than a child task so its cancellation is only
    /// ever the one a Cancel affordance hands it, never something inherited.
    private func choose() {
        guard let template = selected?.template, let url = Self.chooseLocation(for: template) else { return }
        let title = TemplateEngine.documentName(of: url)

        Task { @MainActor in
            let outcome = await Task.detached(priority: .userInitiated) {
                () -> Result<URL, TemplateEngine.Failure> in
                do throws(TemplateEngine.Failure) {
                    return .success(try TemplateEngine.instantiate(template: template, to: url, title: title))
                } catch {
                    return .failure(error)
                }
            }.value

            switch outcome {
            case .success:
                dismiss()
                // The ordinary open path, so the new board joins recents, gets its bookmark, and
                // closes welcome on the way in exactly like a board opened from a row.
                appModel.openBoard(at: url)
            case .failure(.cancelled):
                // Nothing was created and nothing failed, so nothing is said — the duplicate rule.
                Self.logger.notice("template instantiation cancelled — the partial board was removed")
            case let .failure(.failed(error)):
                Self.logger.error("template instantiation failed: \(error.description, privacy: .public)")
                Self.present(error)
            }
        }
    }

    /// The save panel — where the board goes and what it is called.
    ///
    /// **The suggestion is the template's own title** (`"Basic.kanban"`, `"Bug Tracker.kanban"`) —
    /// 09 ▸ Instantiation: "seed the save panel's suggested name from the template title". Whatever
    /// the user types instead becomes the new board's `title` as well as its folder name, so the two
    /// start out matching (01-storage-format.md § Board naming). The package extension is visible and
    /// editable, because an extension-less board folder is equally legal (§ Document packaging) and
    /// deleting the suffix should therefore work rather than be silently undone.
    ///
    /// A name that already exists gets the panel's own replace prompt; agreeing to it does not delete
    /// anything (the panel never does), so the engine's refusal to clobber an existing board is what
    /// the user sees — as an alert, naming the path. That is the honest outcome: this flow is a
    /// *create*, and quietly replacing a board with an empty one is not a thing it should be able to
    /// do.
    private static func chooseLocation(for template: BoardTemplate) -> URL? {
        let panel = NSSavePanel()
        panel.nameFieldStringValue = TemplateEngine.suggestedFileName(for: template)
        panel.canCreateDirectories = true
        panel.isExtensionHidden = false
        panel.allowsOtherFileTypes = true
        panel.prompt = "Create"
        panel.message = "Choose where to keep the new board."

        guard panel.runModal() == .OK, let url = panel.url else { return nil }
        return url
    }

    private static func present(_ error: BoardWriteError) {
        let alert = NSAlert()
        alert.alertStyle = .warning
        alert.messageText = BannerCenter.headline(for: error)
        alert.informativeText = error.path
        alert.addButton(withTitle: "OK")
        alert.runModal()
    }
}

// MARK: - Template card

/// One row in the grid: its preview, its name, and the selection ring — or, for a folder that did not
/// load, the same frame with an unloadable badge where the preview would be.
///
/// The two cases share a frame deliberately: an unloadable template is **the same kind of thing** as
/// the ones beside it, one edit away from working (09), so hiding it in a separate list would say the
/// opposite of what 09 means by "still listed".
private struct TemplateCard: View {

    let row: TemplateRow
    let isSelected: Bool

    var body: some View {
        VStack(spacing: 8) {
            content
                .frame(height: 96)
                .frame(maxWidth: .infinity)
                .background(RoundedRectangle(cornerRadius: 8).fill(Color(nsColor: .textBackgroundColor)))
                .overlay(
                    RoundedRectangle(cornerRadius: 8)
                        .strokeBorder(isSelected ? Color.accentColor : Color(nsColor: .separatorColor),
                                      lineWidth: isSelected ? 3 : 1)
                )

            Label(row.name, systemImage: icon)
                .font(.callout)
                .labelStyle(.titleAndIcon)
                .lineLimit(1)
        }
        .contentShape(Rectangle())
        .accessibilityElement(children: .combine)
        .accessibilityLabel(row.name)
        .accessibilityHint(hint)
    }

    @ViewBuilder
    private var content: some View {
        switch row {
        case let .template(template):
            TemplatePreview(template: template)
        case .unloadable:
            // No preview, because there is no board to preview — the badge says why the tile is
            // empty rather than leaving it looking like a template with no lanes.
            VStack(spacing: 6) {
                Image(systemName: "exclamationmark.triangle")
                    .font(.title2)
                Text("Can't be read")
                    .font(.caption)
            }
            .foregroundStyle(.secondary)
        }
    }

    private var icon: String {
        switch row {
        case let .template(template): template.icon
        case .unloadable: "exclamationmark.triangle"
        }
    }

    private var hint: String {
        switch row {
        case let .template(template): template.blurb
        case let .unloadable(unloadable): BannerCenter.headline(for: unloadable.error)
        }
    }
}

/// The mini per-lane preview: one column per lane, a tinted title bar over the lane's **own cards**.
///
/// It renders **from the template's loaded `BoardModel`** (09-templates.md ▸ Why this format: "The
/// picker's mini per-lane preview renders from a real `BoardModel` via the normal loader"), and every
/// mark in it is read off that model rather than decorated in: the number of columns is the lane
/// count, each column's tint is the lane's own `iconColor` through `Palette`, and the number of card
/// shapes is how many cards the lane actually holds — templates "may contain starter cards", so a
/// board with a "How this board works" card in its first lane looks different here from one without.
///
/// Deliberately **textless**: legible lane names are not available at this size, and the point of the
/// preview is the shape of the board. A lane with no cards draws an empty column, which is the honest
/// picture of an empty lane rather than a decorative one.
private struct TemplatePreview: View {

    let template: BoardTemplate

    /// How many lanes and cards a tile can show before the marks stop being distinguishable. A
    /// template with more of either is truncated rather than shrunk to threads — the preview is an
    /// impression, and every bundled template fits inside both.
    private static let laneLimit = 6
    private static let cardLimit = 4

    var body: some View {
        HStack(alignment: .top, spacing: 5) {
            ForEach(template.lanes.prefix(Self.laneLimit)) { lane in
                VStack(spacing: 4) {
                    RoundedRectangle(cornerRadius: 2)
                        .fill(Self.tint(of: lane))
                        .frame(height: 5)
                    ForEach(0 ..< min(lane.cards.count, Self.cardLimit), id: \.self) { _ in
                        RoundedRectangle(cornerRadius: 3)
                            .fill(.quaternary)
                            .frame(height: 12)
                    }
                    Spacer(minLength: 0)
                }
            }
        }
        .padding(10)
        .accessibilityHidden(true)
    }

    /// The lane's palette tint, falling back to the accent colour — `Palette` is the one place a
    /// colour name is resolved, and a lane that names none looks like the chrome default here exactly
    /// as it does on a board.
    private static func tint(of lane: Lane) -> Color {
        (Palette.color(for: lane.iconColor) ?? .accentColor).opacity(0.65)
    }
}