qbz/crates/qbz-ui/ui/discover/Carousel.slint

// Discover section carousel — a title, prev/next page controls, and a
// clipped, sliding track of album cards.
//
// Pagination by slice (no scrollbar), mirroring the Svelte
// DiscoverySection. Because there is no ScrollView the height is exactly
// the card height — nothing injects extra vertical space.

import { Theme } from "../foundation/semantic-colors.slint";
import { Typography } from "../foundation/typography.slint";
import { DiscoverSection, ShellState, AppearanceState } from "../state.slint";
import { AlbumCard } from "AlbumCard.slint";
import { QbzIcon } from "../primitives/QbzIcon.slint";
import { QbzSelect } from "../primitives/QbzSelect.slint";

component NavButton inherits Rectangle {
    in property <image> icon;
    in property <bool> enabled: true;
    callback clicked();

    width: 28px;
    height: 28px;
    border-radius: 14px;
    opacity: root.enabled ? 1.0 : 0.4;
    background: ta.has-hover && root.enabled
        ? Theme.surface-hover
        : (ShellState.app-background-active
            ? Theme.surface-elevated.with-alpha(AppearanceState.app-background-surface-alpha)
            : Theme.surface-elevated);

    QbzIcon {
        source: root.icon;
        width: 15px;
        height: 15px;
        x: Math.round((parent.width - self.width) / 2 / 1px) * 1px;
        y: Math.round((parent.height - self.height) / 2 / 1px) * 1px;
        tint: root.enabled ? Theme.text-primary : Theme.text-muted;
    }

    ta := TouchArea {
        enabled: root.enabled;
        mouse-cursor: root.enabled ? pointer : default;
        clicked => {
            root.clicked();
        }
    }
}

component ViewAllLink inherits Rectangle {
    callback clicked();
    width: link-text.preferred-width + 16px;
    height: 26px;
    border-radius: 4px;
    background: ta.has-hover ? Theme.surface-hover : transparent;
    link-text := Text {
        // Muted, close to normal text (not the theme accent), with the
        // trailing arrow — matches Tauri's "See all →".
        text: @tr("View all →");
        color: ta.has-hover ? Theme.text-primary : Theme.text-secondary;
        font-size: 14px;
        font-weight: Typography.medium;
        x: Math.round((parent.width - self.width) / 2 / 1px) * 1px;
        y: Math.round((parent.height - self.height) / 2 / 1px) * 1px;
    }
    ta := TouchArea {
        mouse-cursor: pointer;
        clicked => {
            root.clicked();
        }
    }
}

export component Carousel inherits VerticalLayout {
    in property <DiscoverSection> section;
    in property <bool> show-view-all: false;
    // Optional refresh affordance in the row header (recently-played rows).
    in property <bool> show-refresh: false;
    // Optional sort dropdown in the row header, above/left of the page
    // chevrons (Library Albums #566). `sort-options` are the localized
    // labels; `sort-index` is the current selection; `sort-changed(i)` fires
    // when the user picks another option.
    in property <bool> show-sort: false;
    in property <[string]> sort-options: [];
    in property <int> sort-index: 0;
    callback sort-changed(int);
    callback album-clicked(string);
    callback media-action(string, string, string);
    callback view-all-clicked();
    callback refresh-clicked();

    property <length> card-width: 200px;
    // Overridable so a host view (Discover Recommendations) can give the row a
    // taller viewport + card when the default 246 clips the meta line.
    in property <length> card-height: 246px;
    property <length> gap: 32px;

    property <int> count: root.section.albums.length;
    property <int> per-page: Math.max(
        1,
        Math.floor((flick.width + root.gap) / (root.card-width + root.gap)));
    property <length> step: root.per-page * (root.card-width + root.gap);
    property <length> content-width:
        root.count * root.card-width + Math.max(0, root.count - 1) * root.gap;
    // Max leftward scroll (viewport-x is 0 at start, negative when
    // scrolled right). Zero when everything fits.
    property <length> max-scroll: Math.max(0px, root.content-width - flick.width);

    // --- Horizontal element windowing (always on) -------------------------
    // Only cards within ~one viewport of the visible band mount a real
    // AlbumCard; the rest are same-footprint placeholder slots, so the
    // content-width formula above (the scroll geometry) never changes.
    // Element-count only — NO artwork banding: every section's loader
    // dispatches artwork for the whole strip up front and it lands on the
    // model, so a card mounting later picks its cover up instantly.
    // The strip starts at x=0 inside the Flickable's content (no leading
    // padding), so the local left edge is just the negated viewport-x.
    //
    // POST-LAYOUT SNAPSHOT SAMPLING — same discipline as AlbumGrid in
    // AlbumCollectionView.slint (read the long comment there; third hit of
    // the "Recursion detected" class). The band state is PLAIN properties
    // written only by the sampler Timer: `changed` handlers and init-time
    // reads of flick.viewport-x / flick.width are forbidden here because
    // carousels instantiate from `ensure_updated` inside layout/render
    // property evaluation, where such reads can re-enter a mid-flight
    // property and panic. Do not wire these back to reactive bindings.
    property <length> col-stride: root.card-width + root.gap;
    // Pre-seed [0, 6]: roughly one viewport of cards mounted for the <=80ms
    // between mount and the first sampler tick.
    property <int> target-first-col: 0;
    property <int> target-last-col: 6;
    // Mounted band = target band + contract hysteresis. Expansion follows
    // the target immediately (a card must be mounted before it can reach the
    // visible area); contraction lags by `hysteresis-cols`, so a few-px
    // oscillation across a column boundary cannot mount/unmount cards on
    // every direction change.
    property <int> hysteresis-cols: 1;
    property <int> first-window-col: 0;
    property <int> last-window-col: 6;
    pure function desired-first-col() -> int {
        if (root.target-first-col < root.first-window-col) {
            return root.target-first-col;
        }
        if (root.target-first-col > root.first-window-col + root.hysteresis-cols) {
            return root.target-first-col - root.hysteresis-cols;
        }
        return root.first-window-col;
    }
    pure function desired-last-col() -> int {
        if (root.target-last-col > root.last-window-col) {
            return root.target-last-col;
        }
        if (root.target-last-col < root.last-window-col - root.hysteresis-cols) {
            return root.target-last-col + root.hysteresis-cols;
        }
        return root.last-window-col;
    }
    function apply-window() {
        if (root.desired-first-col() != root.first-window-col
            || root.desired-last-col() != root.last-window-col) {
            root.first-window-col = root.desired-first-col();
            root.last-window-col = root.desired-last-col();
        }
    }
    // The sampler: reads viewport-x / width live (safe — event-loop
    // context), recomputes the target band, applies hysteresis. The
    // one-viewport margin absorbs the 80ms cadence; a page jump from the
    // nav buttons shows placeholder slots for at most one tick.
    function sample-window() {
        root.target-first-col = Math.max(
            0,
            Math.floor((-flick.viewport-x - flick.width) / root.col-stride));
        root.target-last-col = Math.max(
            0,
            Math.floor((-flick.viewport-x + 2 * flick.width) / root.col-stride));
        root.apply-window();
    }
    Timer {
        interval: 80ms;
        running: root.count > 0;
        triggered => { root.sample-window(); }
    }

    spacing: 12px;

    // --- Header: title + page controls -----------------------------------
    HorizontalLayout {
        Text {
            text: root.section.title;
            color: Theme.text-primary;
            font-size: Typography.section;
            font-weight: Typography.semibold;
            vertical-alignment: center;
            horizontal-stretch: 1;
        }
        HorizontalLayout {
            spacing: 4px;
            // Sort dropdown (Library Albums): sits left of the page chevrons,
            // a compact toolbar-style select. Picking an option fires
            // sort-changed(i); the host re-orders the row's data in Rust.
            if root.show-sort: VerticalLayout {
                alignment: center;
                QbzSelect {
                    sm: true;
                    menu-width: 170px;
                    options: root.sort-options;
                    current-index: root.sort-index;
                    selected(i) => {
                        root.sort-changed(i);
                    }
                }
            }
            // "View all" sits to the LEFT of the carousel page chevrons,
            // matching the Tauri DiscoverySection header.
            if root.show-view-all: VerticalLayout {
                alignment: center;
                ViewAllLink {
                    clicked => {
                        root.view-all-clicked();
                    }
                }
            }
            if root.show-refresh: VerticalLayout {
                alignment: center;
                NavButton {
                    icon: @image-url("../assets/icons/refresh-cw.svg");
                    clicked => {
                        root.refresh-clicked();
                    }
                }
            }
            VerticalLayout {
                alignment: center;
                NavButton {
                    icon: @image-url("../assets/icons/chevron-left.svg");
                    enabled: flick.viewport-x < -1px;
                    clicked => {
                        flick.viewport-x = Math.min(0px, flick.viewport-x + root.step);
                    }
                }
            }
            VerticalLayout {
                alignment: center;
                NavButton {
                    icon: @image-url("../assets/icons/chevron-right.svg");
                    enabled: flick.viewport-x > -root.max-scroll + 1px;
                    clicked => {
                        flick.viewport-x = Math.max(-root.max-scroll, flick.viewport-x - root.step);
                    }
                }
            }
        }
    }

    // --- Track: a horizontal Flickable so the row drags by touch /
    // pointer (kinetic), while card taps still register — Flickable
    // distinguishes a flick from a tap, unlike nested TouchAreas. The
    // prev/next buttons nudge viewport-x by a page. viewport-height ==
    // height pins it to horizontal-only so it never fights the home
    // page's vertical Flickable.
    viewport := Rectangle {
        height: root.card-height;
        clip: true;

        flick := Flickable {
            width: 100%;
            height: root.card-height;
            viewport-width: root.content-width;
            viewport-height: self.height;

            HorizontalLayout {
                spacing: root.gap;
                for album[i] in root.section.albums: card-slot := Rectangle {
                    // Fixed-footprint slot: carries the card's exact size so
                    // the layout (and thus content-width / scroll geometry)
                    // is unchanged while the card itself is unmounted.
                    width: root.card-width;
                    height: root.card-height;
                    property <bool> in-window: i >= root.first-window-col
                        && i <= root.last-window-col;
                    // Placeholder tile while the real card is unmounted
                    // (fast scroll / far page jump).
                    border-radius: 8px;
                    background: card-slot.in-window ? transparent : Theme.surface-elevated;
                    if card-slot.in-window: AlbumCard {
                        album: album;
                        card-height: root.card-height;
                        clicked(id) => {
                            root.album-clicked(id);
                        }
                        media-action(kind, id, action) => {
                            root.media-action(kind, id, action);
                        }
                    }
                }
            }
        }

        // Cider-style edge fades — content dissolves into the page
        // background at the scrolled edges instead of a hard cut.
        Rectangle {
            x: 0px;
            width: 56px;
            background: @linear-gradient(90deg, Theme.surface-main 0%, transparent 100%);
            opacity: flick.viewport-x < -1px ? 1.0 : 0.0;
            visible: !ShellState.app-background-active;
            animate opacity { duration: 150ms; }
        }
        Rectangle {
            x: parent.width - self.width;
            width: 56px;
            background: @linear-gradient(90deg, transparent 0%, Theme.surface-main 100%);
            opacity: flick.viewport-x > -root.max-scroll + 1px ? 1.0 : 0.0;
            visible: !ShellState.app-background-active;
            animate opacity { duration: 150ms; }
        }
    }
}