Collection Surfer

# Brok UI: Collection Surfer (`collection-surfer`)

A coverflow-style collection browser: a horizontal row of cards where the centered card is enlarged and front-facing while neighbours recede and rotate in 3D. Navigable by click, arrow keys and drag.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add collection-surfer
```

## Usage

```blade
<x-ui.collection-surfer class="w-full max-w-2xl" />
```

## Props

- `items` (array, default `[]`) — Collection entries to browse; each needs a title, with optional subtitle and art gradient classes.
- `perspective` (string, default `1000px`) — CSS perspective value for the 3D stage.
- `active` (int, default `0`) — Index of the initially active card.

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- Browsing a horizontal collection (album art, product thumbnails, a media library) where the centred item should read as a physical coverflow with a reflection under the active card.
- Wanting drag-to-scrub navigation where the whole row glides continuously under the finger and snaps to the nearest item on release.

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- A flatter, simpler carousel without 3D depth or a reflection is enough; use carousel.

## Anti-patterns

- Heavy effects in forms or task-dense workflows
- Motion that interferes with reading or focus

## Rules

- Use the `<brok:collection-surfer>` tag (or `<x-ui.collection-surfer>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/collection-surfer
- Registry JSON (files, props, contract): https://brokui.dev/r/open/collection-surfer.json

@props([
    'items' => [],
    'perspective' => '1000px',
    'active' => 0,
])

@php
    // Self-contained demo set so the component renders meaningfully with no
    // props. Each item: title, subtitle and a token-based gradient (`art`).
    $defaultItems = [
        ['title' => 'Nocturne', 'subtitle' => 'Ambient', 'art' => 'from-chart-4 to-chart-1'],
        ['title' => 'Daybreak', 'subtitle' => 'Indie Pop', 'art' => 'from-chart-3 to-chart-5'],
        ['title' => 'Undertow', 'subtitle' => 'Electronic', 'art' => 'from-chart-1 to-chart-2'],
        ['title' => 'Ember', 'subtitle' => 'Folk', 'art' => 'from-chart-5 to-chart-3'],
        ['title' => 'Glasshouse', 'subtitle' => 'Jazz', 'art' => 'from-chart-2 to-chart-4'],
        ['title' => 'Parallax', 'subtitle' => 'Synthwave', 'art' => 'from-primary to-chart-4'],
        ['title' => 'Lowlands', 'subtitle' => 'Lo-fi', 'art' => 'from-chart-2 to-primary'],
    ];

    $surferItems = ! empty($items) ? array_values($items) : $defaultItems;
    $total = count($surferItems);
    $initial = max(0, min((int) $active, $total - 1));

    $config = [
        'active' => $initial,
        'count' => $total,
    ];
@endphp

<div
    x-data="uiCollectionSurfer(@js($config))"
    data-slot="collection-surfer"
    role="listbox"
    aria-roledescription="coverflow"
    aria-label="{{ __('Collection') }}"
    aria-orientation="horizontal"
    tabindex="0"
    @keydown="onKey($event)"
    @pointerdown="onPointerDown($event)"
    {{ $attributes->merge(['class' => 'relative outline-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-lg']) }}
>
    {{-- Stage: every card sits at the centre and is moved by transform alone
         (no native scrolling under a 3D transform, which is what made the old
         coverflow stutter). A drag moves the whole row live; release snaps
         to the nearest card. Reduced-motion users get a flat row with no
         depth or rotation. --}}
    <div
        x-ref="track"
        class="relative h-64 w-full touch-pan-y overflow-hidden sm:h-72"
        style="perspective: {{ $perspective }};"
        :data-dragging="dragging ? 'true' : null"
    >
        @foreach ($surferItems as $i => $item)
            @php
                $title = is_array($item) ? ($item['title'] ?? '') : $item;
                $subtitle = is_array($item) ? ($item['subtitle'] ?? null) : null;
                $art = is_array($item) ? ($item['art'] ?? 'from-primary to-accent') : 'from-primary to-accent';
            @endphp
            <button
                type="button"
                role="option"
                :aria-selected="isActive({{ $i }}) ? 'true' : 'false'"
                :tabindex="isActive({{ $i }}) ? 0 : -1"
                @click="onCardClick({{ $i }})"
                :class="{ 'is-active': isActive({{ $i }}), '!transition-none': dragging }"
                :style="itemStyle({{ $i }})"
                class="absolute left-1/2 top-1/2 origin-center cursor-pointer rounded-lg outline-none transition-[transform,opacity] duration-500 ease-[cubic-bezier(0.2,0.8,0.2,1)] will-change-transform [transform-style:preserve-3d] focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none"
            >
                <div class="flex h-44 w-36 flex-col justify-end overflow-hidden rounded-md border border-border bg-gradient-to-br {{ $art }} p-3 text-left shadow-lg sm:h-52 sm:w-40">
                    <span class="text-sm font-semibold text-primary-foreground drop-shadow-sm">{{ $title }}</span>
                    @if ($subtitle)
                        <span class="text-xs text-primary-foreground">{{ $subtitle }}</span>
                    @endif
                </div>
                {{-- Reflection: a faded, flipped copy under the active card. --}}
                <span aria-hidden="true" class="pointer-events-none absolute inset-x-0 top-full mt-1 h-10 overflow-hidden rounded-md opacity-25 [transform:scaleY(-1)] [mask-image:linear-gradient(to_top,transparent,black)]">
                    <span class="block h-44 w-36 rounded-md bg-gradient-to-br {{ $art }} sm:h-52 sm:w-40"></span>
                </span>
                <span class="sr-only" x-text="isActive({{ $i }}) ? '{{ __('(current)') }}' : ''"></span>
            </button>
        @endforeach
    </div>

    {{-- Prev / next affordance. Hidden from AT (the listbox is keyboard
         navigable); pointer users get explicit controls. Composes
         carousel.previous/next against this component's own
         prev()/next()/canPrev()/canNext(). --}}
    <x-ui.carousel.previous
        data-slot="collection-surfer-prev"
        aria-hidden="true"
        tabindex="-1"
        on-click="prev()"
        disabled="!canPrev()"
        class="!start-1 !size-9 !bg-background/80 !backdrop-blur hover:!bg-accent hover:!text-accent-foreground"
    />
    <x-ui.carousel.next
        data-slot="collection-surfer-next"
        aria-hidden="true"
        tabindex="-1"
        on-click="next()"
        disabled="!canNext()"
        class="!end-1 !size-9 !bg-background/80 !backdrop-blur hover:!bg-accent hover:!text-accent-foreground"
    />
</div>

/**
 * Collection surfer behavior (spec §19 behavior layer).
 *
 * A coverflow / collection browser. Every card sits at the stage centre and is
 * placed by transform alone from its signed distance to `pos` — the fractional
 * row position, equal to the active `index` at rest and following the finger
 * during a drag — so the row glides continuously and snaps on release. The
 * active card is front-facing and full size; neighbours step aside, turn and
 * recede in 3D.
 *
 * Navigation: clicking a card activates it, ArrowLeft/ArrowRight step the
 * active index (swapped under RTL so navigation follows reading order), a drag
 * moves the row live. Reduced-motion users get a flat row (no depth, no
 * rotation) that still slides between cards.
 *
 * Self-registers on `alpine:init` so import order does not matter — import this
 * file once from your bundle (e.g. resources/js/ui/index.js).
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiCollectionSurfer', (config = {}) => ({
        index: config.active ?? 0,
        count: config.count ?? 0,
        motion: true,
        dragX: null,

        init() {
            this.count = this.$refs.track ? this.$refs.track.children.length : this.count;
            this.index = Math.min(Math.max(this.index, 0), Math.max(0, this.count - 1));
            this.pos = this.index;

            const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
            this.motion = !mq.matches;
            this._onMq = (e) => { this.motion = !e.matches; };
            mq.addEventListener('change', this._onMq);
            this._mq = mq;

            this.$nextTick(() => this.scrollToActive());
        },

        destroy() {
            if (this._mq && this._onMq) this._mq.removeEventListener('change', this._onMq);
            if (this._onMove) window.removeEventListener('pointermove', this._onMove);
            if (this._onUp) {
                window.removeEventListener('pointerup', this._onUp);
                window.removeEventListener('pointercancel', this._onUp);
            }
        },

        rtl() {
            return getComputedStyle(this.$el).direction === 'rtl';
        },

        select(i) {
            this.index = Math.min(Math.max(i, 0), Math.max(0, this.count - 1));
            this.scrollToActive();
        },

        next() {
            if (this.index < this.count - 1) { this.index++; this.scrollToActive(); }
        },

        prev() {
            if (this.index > 0) { this.index--; this.scrollToActive(); }
        },

        canPrev() { return this.index > 0; },
        canNext() { return this.index < this.count - 1; },
        isActive(i) { return i === this.index; },

        // Signed distance from the active card. Negative = before, positive = after.
        offset(i) {
            return (this.rtl() ? -1 : 1) * (i - this.index);
        },

        // Fractional position of the row while a drag is in flight (equals
        // `index` at rest). Every card's transform is computed from its signed
        // distance to this, so the whole row glides under the finger.
        pos: 0,
        dragging: false,
        _startX: 0,
        _startPos: 0,
        _moved: false,
        _onMove: null,
        _onUp: null,

        // Inline transform for a card based on its distance from the active
        // position. Reduced motion collapses depth and rotation to a flat row.
        itemStyle(i) {
            const d = (this.rtl() ? -1 : 1) * (i - this.pos);
            const ad = Math.abs(d);
            const sign = d === 0 ? 0 : d / ad;
            if (!this.motion) {
                return { transform: `translate(calc(-50% + ${d * 176}px), -50%)`, opacity: 1, zIndex: 100 - Math.round(ad) };
            }
            // Neighbours step out by a card width, then bunch up further away.
            const spread = sign * (ad <= 1 ? ad * 150 : 150 + (ad - 1) * 56);
            const rotate = -sign * Math.min(50, ad * 50);
            const depth = -Math.min(ad, 4) * 70;
            const scale = Math.max(0.72, 1 - ad * 0.1);
            const opacity = Math.max(0.3, 1 - Math.max(0, ad - 0.5) * 0.25);
            return {
                transform: `translate(calc(-50% + ${spread}px), -50%) translateZ(${depth}px) rotateY(${rotate}deg) scale(${scale})`,
                opacity,
                zIndex: 100 - Math.round(ad * 2),
                pointerEvents: ad > 3.5 ? 'none' : 'auto',
            };
        },

        scrollToActive() {
            this.pos = this.index;
        },

        onCardClick(i) {
            // A drag that ended on a card is not a click.
            if (this._moved) return;
            this.select(i);
        },

        // Pointer drag: the row follows the finger (one card per 160px) and
        // snaps to the nearest card on release; a flick of any length past a
        // third of a card advances.
        onPointerDown(e) {
            if (e.button !== undefined && e.button !== 0) return;
            this._startX = e.clientX;
            this._startPos = this.pos;
            this._moved = false;
            this._onMove = (ev) => {
                const dx = ev.clientX - this._startX;
                if (!this._moved && Math.abs(dx) < 4) return;
                this._moved = true;
                this.dragging = true;
                ev.preventDefault();
                const dir = this.rtl() ? 1 : -1;
                this.pos = Math.min(this.count - 1, Math.max(0, this._startPos + (dir * dx) / 160));
            };
            this._onUp = () => {
                window.removeEventListener('pointermove', this._onMove);
                window.removeEventListener('pointerup', this._onUp);
                window.removeEventListener('pointercancel', this._onUp);
                this._onMove = this._onUp = null;
                this.dragging = false;
                if (this._moved) {
                    this.index = Math.round(this.pos);
                    this.pos = this.index;
                    setTimeout(() => (this._moved = false), 0);
                }
            };
            window.addEventListener('pointermove', this._onMove);
            window.addEventListener('pointerup', this._onUp);
            window.addEventListener('pointercancel', this._onUp);
        },

        onKey(e) {
            const rtl = this.rtl();
            if (e.key === 'ArrowRight') {
                e.preventDefault();
                rtl ? this.prev() : this.next();
            } else if (e.key === 'ArrowLeft') {
                e.preventDefault();
                rtl ? this.next() : this.prev();
            } else if (e.key === 'Home') {
                e.preventDefault();
                this.select(0);
            } else if (e.key === 'End') {
                e.preventDefault();
                this.select(this.count - 1);
            }
        },

    }));
});