Carousels

# Brok UI: Progressive Carousel (`progressive-carousel`)

An auto-advancing carousel whose active panel expands while the rest collapse to slivers — pauses on hover/focus, advances with arrow keys, and respects reduced motion. `trigger="hover"` previews a panel on hover instead (the image-accordion shape).

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

## Install

```bash
php artisan ui:add progressive-carousel
```

## Usage

```blade
<x-ui.progressive-carousel
    class="max-w-2xl"
    :interval="3500"
    :items="[
        ['title' => 'Discover', 'subtitle' => 'Find what moves you', 'src' => 'https://picsum.photos/seed/pc-a/800/600'],
        ['title' => 'Create', 'subtitle' => 'Make it your own', 'src' => 'https://picsum.photos/seed/pc-b/800/600'],
        ['title' => 'Share', 'subtitle' => 'Bring others along', 'src' => 'https://picsum.photos/seed/pc-c/800/600'],
        ['title' => 'Grow', 'subtitle' => 'Scale with confidence', 'src' => 'https://picsum.photos/seed/pc-d/800/600'],
    ]"
/>
```

## Props

- `items` (array, default `[]`) — Panels in the strip; each needs a title, with optional subtitle, src and alt.
- `interval` (int, default `4000`) — Milliseconds between automatic panel advances.
- `autoplay` (bool, default `true`) — Advances the active panel automatically on a timer when true.
- `vertical` (bool, default `false`) — Stacks panels top-to-bottom instead of side-by-side when true.
- `trigger` (string, default `click`) — click pins the active panel on click/focus; hover previews a panel on hover and pins on click/focus/leave — the image-accordion shape.

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- An auto-advancing strip of panels where the active panel should visually expand and the rest collapse to slivers, such as a feature or destination showcase.
- Wanting a hover-preview accordion of images (trigger="hover") that pins to the last clicked/focused panel on pointer-leave — the image-accordion shape.

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- A conventional carousel with equally-sized slides is wanted; use carousel, which doesn't expand/collapse panels.
- 3D depth or a coverflow look is wanted; use card-carousel-3d or carousel-cylinder instead.

## Anti-patterns

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

## Rules

- Use the `<brok:progressive-carousel>` tag (or `<x-ui.progressive-carousel>`) 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/progressive-carousel
- Registry JSON (files, props, contract): https://brokui.dev/r/open/progressive-carousel.json

@props([
    'items' => [],
    'interval' => 4000,
    'autoplay' => true,
    'vertical' => false,
    // click (default): the active panel changes only on click/focus.
    // hover: the active panel previews on hover and pins on click/focus/leave
    // — the image-accordion shape. Typically paired with :autoplay="false".
    'trigger' => 'click',
])

@php
    // Progressive Carousel — an auto-advancing strip of panels where the active
    // panel expands (flex-grow) and the rest collapse to slivers, cycling on a
    // timer. Pauses on hover/focus, advances with Arrow keys, and lets you click
    // any panel to make it active. Autoplay is gated behind reduced motion and
    // its timer is torn down in destroy(). Panels with no `src` fall back to a
    // token gradient so it renders with no external assets. `trigger="hover"`
    // additionally previews a panel on hover without pinning it (image-accordion
    // shares this DOM outline, so hover-preview is a variant prop here rather
    // than a separate component — see docs/adr/002-compositions-and-variants.md).
    $vertical = (bool) $vertical;
    $trigger = in_array($trigger, ['hover', 'click'], true) ? $trigger : 'click';
    $items = ! empty($items) ? $items : [
        ['title' => 'Discover', 'subtitle' => 'Find what moves you'],
        ['title' => 'Create', 'subtitle' => 'Make it your own'],
        ['title' => 'Share', 'subtitle' => 'Bring others along'],
        ['title' => 'Grow', 'subtitle' => 'Scale with confidence'],
    ];
    $count = count($items);

    // image-accordion composes this as <x-ui.progressive-carousel
    // trigger="hover" data-slot="image-accordion">; the browser keeps only
    // the first of two identical attributes, so read the override and print
    // exactly one.
    $slotName = (string) ($attributes->get('data-slot') ?: 'progressive-carousel');
@endphp

<div
    data-slot="{{ $slotName }}"
    data-orientation="{{ $vertical ? 'vertical' : 'horizontal' }}"
    data-trigger="{{ $trigger }}"
    x-data="uiProgressiveCarousel({ count: {{ $count }}, interval: {{ (int) $interval }}, autoplay: @js((bool) $autoplay), vertical: @js($vertical), trigger: @js($trigger) })"
    @mouseenter="pause()"
    @mouseleave="resume()"
    @focusin="pause()"
    @focusout="resume()"
    @keydown="onKey($event)"
    role="group"
    aria-roledescription="{{ __('carousel') }}"
    aria-label="{{ __('Progressive carousel') }}"
    {{ $attributes->except('data-slot')->merge(['class' => ($vertical ? 'flex-col ' : 'flex-row ').'flex h-80 w-full gap-2 overflow-hidden']) }}
>
    @foreach ($items as $i => $item)
        <button
            type="button"
            data-slot="progressive-carousel-item"
            @if ($trigger === 'hover') @mouseenter="preview({{ $i }})" @mouseleave="release()" @endif
            @click="goTo({{ $i }})"
            @focus="goTo({{ $i }})"
            :class="isActive({{ $i }}) ? 'flex-[5]' : 'flex-[1]'"
            :aria-current="isActive({{ $i }})"
            class="group relative min-h-0 min-w-0 cursor-pointer overflow-hidden rounded-lg border border-border text-start transition-all duration-700 ease-out focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none"
        >
            @if (! empty($item['src']))
                <img src="{{ $item['src'] }}" alt="{{ $item['alt'] ?? ($item['title'] ?? '') }}" loading="lazy" decoding="async" class="absolute inset-0 h-full w-full object-cover" />
            @else
                <span aria-hidden="true" class="absolute inset-0 bg-gradient-to-br from-primary/30 via-card to-secondary/40"></span>
            @endif
            <span aria-hidden="true" class="absolute inset-0 bg-gradient-to-t from-background/85 via-background/20 to-transparent"></span>

            <span
                class="absolute bottom-0 start-0 flex flex-col p-5 transition-all duration-500"
                :class="isActive({{ $i }}) ? 'opacity-100 translate-y-0' : 'opacity-0 translate-y-2'"
            >
                <span class="text-base font-semibold text-foreground">{{ __($item['title'] ?? '') }}</span>
                @if (! empty($item['subtitle']))
                    <span class="mt-0.5 text-sm text-muted-foreground">{{ __($item['subtitle']) }}</span>
                @endif
            </span>
        </button>
    @endforeach
</div>

/**
 * Progressive Carousel behavior.
 *
 * Default (`trigger="click"`): advances the active panel on a timer (looping),
 * with the active panel growing and the rest collapsing — the size is driven
 * by fixed `flex-[…]` classes in the Blade. Autoplay is disabled under
 * `prefers-reduced-motion`, paused on hover/focus via the Blade's
 * pause()/resume() handlers, and the interval is cleared in destroy() so it
 * can never leak. Arrow keys (orientation-aware, RTL-aware) step the active
 * panel and move focus to it; clicking/focusing a panel activates it and
 * "pins" it as the panel autoplay/hover-release returns to.
 *
 * `trigger="hover"` (the image-accordion shape): the active panel follows the
 * pointer via preview()/release() and snaps back to the last clicked/focused
 * ("pinned") panel on pointer-leave, instead of advancing on a timer —
 * typically paired with `:autoplay="false"`.
 *
 * Self-registers on `alpine:init` so import order does not matter.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiProgressiveCarousel', (config = {}) => ({
        count: config.count ?? 0,
        interval: config.interval ?? 4000,
        autoplay: config.autoplay ?? true,
        vertical: config.vertical ?? false,
        trigger: config.trigger ?? 'click',
        reduced: window.matchMedia('(prefers-reduced-motion: reduce)').matches,
        active: 0,
        pinned: 0,
        _timer: null,

        init() {
            if (this.autoplay && !this.reduced) this.start();
        },

        isActive(i) {
            return this.active === i;
        },

        goTo(i) {
            const idx = ((i % this.count) + this.count) % this.count;
            this.active = idx;
            this.pinned = idx;
        },

        /** trigger="hover" only: the active panel follows the pointer without pinning. */
        preview(i) {
            if (this.trigger === 'hover') this.active = i;
        },

        /** trigger="hover" only: on pointer-leave, snap back to the pinned panel. */
        release() {
            if (this.trigger === 'hover') this.active = this.pinned;
        },

        next() {
            this.goTo(this.active + 1);
        },

        prev() {
            this.goTo(this.active - 1);
        },

        start() {
            this.pause();
            this._timer = setInterval(() => this.next(), this.interval);
        },

        pause() {
            if (this._timer) {
                clearInterval(this._timer);
                this._timer = null;
            }
        },

        resume() {
            if (this.autoplay && !this.reduced && !this._timer) this.start();
        },

        onKey(e) {
            const keys = ['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown', 'Home', 'End'];
            if (!keys.includes(e.key)) return;

            const rtl = getComputedStyle(this.$el).direction === 'rtl';
            const fwd = this.vertical ? 'ArrowDown' : 'ArrowRight';
            const back = this.vertical ? 'ArrowUp' : 'ArrowLeft';
            let i = this.active;

            if (e.key === 'Home') {
                i = 0;
            } else if (e.key === 'End') {
                i = this.count - 1;
            } else if (e.key === fwd) {
                i = rtl && !this.vertical ? this.active - 1 : this.active + 1;
            } else if (e.key === back) {
                i = rtl && !this.vertical ? this.active + 1 : this.active - 1;
            } else {
                return;
            }

            e.preventDefault();
            this.goTo(i);
            const items = this.$el.querySelectorAll('[data-slot="progressive-carousel-item"]');
            if (items[this.active]) items[this.active].focus();
        },

        destroy() {
            this.pause();
        },
    }));
});