Flaro/Packages/FlixyKit/Sources/FlixyDesign/Components/HeroBanner.swift

import SwiftUI

/// Das Aufmacher-Bild oben auf der Startseite.
///
/// Die Aktionsknöpfe kommen von außen, weil ein Film „Abspielen" und
/// „Herunterladen" braucht, eine angefangene Folge dagegen „Weiterschauen".
/// Der Baustein legt nur Bild, Verlauf und Textsatz fest.
public struct HeroBanner<Actions: View>: View {
    private let title: String
    private let metadata: String?
    private let summary: String?
    private let artworkURL: URL?
    /// Der freigestellte Schriftzug des Films. Steht er zur Verfügung, tritt
    /// er an die Stelle des gesetzten Titels — „Harry Potter" in seiner
    /// eigenen Schrift ist wiedererkennbar, eine Systemschrift nicht.
    private let logoURL: URL?
    private let aspectRatio: CGFloat
    /// Ob der Aufmacher den Platz einnimmt, den er bekommt.
    private let fillsAvailableSpace: Bool
    private let actions: Actions

    @State private var logo: PlatformImage?

    /// Wie weit die Navigationsleiste hereinragt.
    ///
    /// Nur das **Bild** greift danach; Titel, Beschreibung und Knöpfe nicht.
    /// Die liegen in einer Überlagerung, und die sitzt auf dem ungedehnten
    /// Rahmen — sie stehen also von selbst da, wo auch die Reihen darunter
    /// anfangen.
    @Environment(\.flixyChromeInset) private var chromeInset

    public init(
        title: String,
        metadata: String? = nil,
        summary: String? = nil,
        artworkURL: URL?,
        logoURL: URL? = nil,
        // 16:9, weil Plex genau das als `art` liefert. Vorher stand hier
        // 3:4 — mit `scaledToFill` wurde das Bild dadurch links und rechts
        // kräftig beschnitten, und vom Aufmacher war nur ein Ausschnitt zu
        // sehen.
        aspectRatio: CGFloat = FlixyAspectRatio.hero,
        fillsAvailableSpace: Bool = false,
        @ViewBuilder actions: () -> Actions
    ) {
        self.title = title
        self.metadata = metadata
        self.summary = summary
        self.artworkURL = artworkURL
        self.logoURL = logoURL
        self.aspectRatio = aspectRatio
        self.fillsAvailableSpace = fillsAvailableSpace
        self.actions = actions()
    }

    /// Wie stark Schrift und Schriftzug mitwachsen.
    ///
    /// Der Aufmacher ist so breit wie das Fenster. Bei fester Schriftgröße
    /// wirkt derselbe Titel auf einem iPad groß und in einem breiten
    /// Mac-Fenster verloren — das Bild wächst, die Schrift nicht. Bezugsgröße
    /// ist die Breite eines iPads im Hochformat; alles darüber wächst mit,
    /// aber gedeckelt, damit ein Fenster über die ganze Wand nicht in
    /// Plakatschrift endet.
    private func scale(for width: CGFloat) -> CGFloat {
        min(max(width / 834, 1), 1.7)
    }

    /// Schriftzug, wenn vorhanden — sonst gesetzter Titel.
    ///
    /// Geladen wird über `ArtworkLoader`, **nicht** über `AsyncImage`. Der
    /// Unterschied ist beim Überblenden des Aufmachers zu sehen: `AsyncImage`
    /// bringt seine eigene Einblendung mit und fängt erst an zu laden, wenn es
    /// erscheint. Der Schriftzug blendete sich dann getrennt und später ein,
    /// während Titelzeile, Beschreibung und Knöpfe längst mitgewandert waren —
    /// zwei Bewegungen, wo eine sein soll.
    ///
    /// Jetzt liegt das Bild beim Erscheinen schon im Zwischenspeicher (das
    /// Karussell holt es vor) und wird ohne eigene Bewegung gezeigt: es gehört
    /// zum Aufmacher und macht mit, was der Aufmacher macht.
    ///
    /// Ohne Bild-Transcoder, weil der Schriftzug ein freigestelltes PNG ist und
    /// der Transcoder JPEG liefert — aus dem Logo würde sonst ein schwarzer
    /// Kasten.
    @ViewBuilder
    private func titleView(scale: CGFloat) -> some View {
        Group {
            if let logo = availableLogo {
                Image(platform: logo)
                    .resizable()
                    .scaledToFit()
                    // Nach oben begrenzt: manche Schriftzüge sind fast
                    // quadratisch, andere sehr breit. Ohne Deckel schöbe ein
                    // hohes Logo die Knöpfe aus dem Bild.
                    .frame(maxWidth: 260 * scale, maxHeight: 76 * scale, alignment: .leading)
                    .accessibilityLabel(Text(title))
            } else {
                // Solange nichts da ist — und wenn es scheitert — bleibt es
                // beim gesetzten Titel. Ein leerer Platz wäre schlimmer als
                // eine Systemschrift.
                plainTitle(scale: scale)
            }
        }
        .task(id: logoURL) {
            guard let logoURL, ArtworkLoader.cachedImage(for: logoURL) == nil else { return }
            logo = await ArtworkLoader.shared.image(for: logoURL)
        }
    }

    /// Der Schriftzug, wenn er **jetzt** gezeigt werden kann.
    ///
    /// Das Karussell holt ihn vor; liegt er bereit, steht er schon im ersten
    /// Bild des Übergangs da. Nur wenn nicht, wird nachgeladen — und dann
    /// steht bis dahin der gesetzte Titel.
    private var availableLogo: PlatformImage? {
        if let logo { return logo }
        guard let logoURL else { return nil }
        return ArtworkLoader.cachedImage(for: logoURL)
    }

    private func plainTitle(scale: CGFloat) -> some View {
        Text(title)
            .font(.system(size: 34 * scale, weight: .bold))
            .foregroundStyle(Color.flixyTextPrimary)
            .lineLimit(2)
    }

    public var body: some View {
        FlixyArtwork(url: artworkURL, aspectRatio: aspectRatio, fillsFrame: fillsAvailableSpace)
            .overlay(alignment: .bottom) {
                // Der Verlauf endet in der Hintergrundfarbe der Seite, nicht in
                // Schwarz: sonst entsteht genau dort, wo der Aufmacher in die
                // erste Reihe übergeht, eine sichtbare Kante.
                LinearGradient(
                    stops: [
                        .init(color: .clear, location: 0),
                        .init(color: Color.flixyCanvas.opacity(0.75), location: 0.45),
                        .init(color: Color.flixyCanvas, location: 1),
                    ],
                    startPoint: .top,
                    endPoint: .bottom
                )
                .frame(maxHeight: .infinity, alignment: .bottom)
                .allowsHitTesting(false)
            }
            // Erst **hier** nach links ausbrechen, nach dem Verlauf und vor
            // der Schrift.
            //
            // Ein negativer Rand dehnt zwar, was er umschließt, meldet nach
            // außen aber die alte Breite. Stand er ganz oben, legten sich
            // Verlauf und Schrift deshalb nur über den alten Bereich — und die
            // zwölf Punkte daneben blieben ohne Verlauf und damit hell. Das war
            // der leuchtende Streifen an der Kante der Seitenleiste.
            //
            // In dieser Reihenfolge stimmt beides: der Verlauf wird mitgedehnt
            // und deckt bis zum Rand, die Schrift bleibt auf der gemeldeten
            // Breite und fängt damit von selbst dort an, wo auch die Reihen
            // darunter anfangen.
            //
            // (Hier stand einmal `backgroundExtensionEffect()`. Der spiegelte
            // den Bildrand, statt das Bild weiterlaufen zu lassen — je größer
            // die Fläche, desto mehr übernahm der Spiegel das Bild.)
            .padding(.leading, -chromeInset)
            .overlay(alignment: .bottomLeading) {
                GeometryReader { geometry in
                    let scale = scale(for: geometry.size.width)

                    VStack(alignment: .leading, spacing: FlixySpacing.snug * scale) {
                        titleView(scale: scale)

                        if let metadata {
                            Text(metadata)
                                .font(.system(size: 12 * scale))
                                .foregroundStyle(Color.flixyTextSecondary)
                        }

                        if let summary {
                            Text(summary)
                                .font(.system(size: 12 * scale))
                                .foregroundStyle(Color.flixyTextSecondary)
                                .lineLimit(2)
                                // Ein Satz über die ganze Breite eines großen
                                // Fensters ist unlesbar; das Auge verliert die
                                // Zeile. Achtzig Zeichen sind die Grenze, ab
                                // der Satzspiegel unangenehm werden.
                                .frame(maxWidth: 640 * scale, alignment: .leading)
                        }

                        HStack(spacing: FlixySpacing.regular) {
                            actions
                        }
                        .padding(.top, FlixySpacing.tight)
                    }
                    .padding(.horizontal, FlixySpacing.screenMargin * scale)
                    .padding(.bottom, FlixySpacing.loose * scale)
                    .frame(
                        width: geometry.size.width,
                        height: geometry.size.height,
                        alignment: .bottomLeading
                    )
                }
            }
    }
}