Scroll Fade

# Brok UI: Scroll Fade (`scroll-fade`)

A scrollable container that fades its edges to signal more content along the enabled axis.

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

## Install

```bash
php artisan ui:add scroll-fade
```

## Usage

```blade
<x-ui.scroll-fade axis="horizontal" class="max-w-md">
    <div class="flex gap-3 p-1">
        @foreach (range(1, 10) as $i)
            <div class="flex h-24 w-32 shrink-0 items-center justify-center rounded-lg border border-border bg-card text-lg font-semibold text-card-foreground">
                {{ __('Card') }} {{ $i }}
            </div>
        @endforeach
    </div>
</x-ui.scroll-fade>
```

## Props

- `axis` (string, default `horizontal`) — Scroll and fade direction: horizontal (default), vertical, or both.
- `hideScrollbar` (bool, default `true`) — Hides the native scrollbar while keeping the region scrollable.
- `intensity` (int, default `1`) — Opacity multiplier for the edge fades.
- `label` (mixed|null, default `null`) — Accessible name for the scrollable region; adds role="region" when set.

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- Signaling that a scrollable strip or panel has more content by fading its edges toward the background.
- Fading horizontally, vertically, or on both axes depending on how the content overflows.

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- The scrollable region already has a clear affordance, such as visible scrollbars or pagination; the fade is an additional cue, not a replacement for one.

## Anti-patterns

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

## Rules

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

@props([
    'axis' => 'horizontal',
    'hideScrollbar' => true,
    'intensity' => 1,
    // Accessible name for the scrollable region. A scroll container must be
    // keyboard-focusable (a11y: scrollable-region-focusable); we add tabindex
    // and, when labelled, a region role so it's announced.
    'label' => null,
])

@php
    $overflow = match ($axis) {
        'vertical' => 'overflow-y-auto overflow-x-hidden',
        'both' => 'overflow-auto',
        default => 'overflow-x-auto overflow-y-hidden',
    };

    // Cross-browser scrollbar hiding without a plugin.
    $hide = $hideScrollbar ? '[scrollbar-width:none] [&::-webkit-scrollbar]:hidden' : '';

    $fadeBase = 'pointer-events-none absolute z-10 from-background to-transparent';
@endphp

<div
    x-data="uiScrollFade({ axis: @js($axis), intensity: @js((float) $intensity) })"
    x-init="update(); $nextTick(() => update())"
    @resize.window="update()"
    data-slot="scroll-fade"
    data-axis="{{ $axis }}"
    {{ $attributes->merge(['class' => 'relative']) }}
>
    @if ($axis === 'horizontal' || $axis === 'both')
        <div x-show="start" class="{{ $fadeBase }} inset-y-0 start-0 w-12 bg-gradient-to-r rtl:bg-gradient-to-l" :style="`opacity:${intensity}`"></div>
        <div x-show="end" class="{{ $fadeBase }} inset-y-0 end-0 w-12 bg-gradient-to-l rtl:bg-gradient-to-r" :style="`opacity:${intensity}`"></div>
    @endif
    @if ($axis === 'vertical' || $axis === 'both')
        <div x-show="top" class="{{ $fadeBase }} inset-x-0 top-0 h-12 bg-gradient-to-b" :style="`opacity:${intensity}`"></div>
        <div x-show="bottom" class="{{ $fadeBase }} inset-x-0 bottom-0 h-12 bg-gradient-to-t" :style="`opacity:${intensity}`"></div>
    @endif

    <div
        x-ref="viewport"
        @scroll="update()"
        tabindex="0"
        @if ($label) role="region" aria-label="{{ $label }}" @endif
        class="{{ $overflow }} {{ $hide }} focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
    >
        {{ $slot }}
    </div>
</div>

/**
 * Scroll-fade behavior (spec §19 behavior layer).
 *
 * Tracks how far the viewport is scrolled on each enabled axis and exposes
 * boolean edge flags (start/end/top/bottom). The Blade markup binds fade
 * overlays to those flags so an edge gradient only shows when there is more
 * content to scroll in that direction.
 *
 * Self-registers on `alpine:init` so import order does not matter.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiScrollFade', (config = {}) => ({
        axis: config.axis || 'horizontal',
        intensity: config.intensity ?? 1,
        start: false,
        end: false,
        top: false,
        bottom: false,

        get horizontal() {
            return this.axis === 'horizontal' || this.axis === 'both';
        },
        get vertical() {
            return this.axis === 'vertical' || this.axis === 'both';
        },

        update() {
            const el = this.$refs.viewport;
            if (!el) return;

            if (this.horizontal) {
                // Math.abs keeps this correct for RTL (negative scrollLeft).
                const left = Math.abs(el.scrollLeft);
                this.start = left > 1;
                this.end = left + el.clientWidth < el.scrollWidth - 1;
            }
            if (this.vertical) {
                this.top = el.scrollTop > 1;
                this.bottom = el.scrollTop + el.clientHeight < el.scrollHeight - 1;
            }
        },
    }));
});