Glow & border effects

# Brok UI: Spotlight (`spotlight`)

A wrapper whose soft radial glow follows the cursor, with an optional hover/focus-only mode and a faint currentColor border for a spotlight-card look; falls back to a static centred glow with no pointer or reduced motion.

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

## Install

```bash
php artisan ui:add spotlight
```

## Usage

```blade
<div class="grid w-full max-w-lg gap-4 sm:grid-cols-2">
    <x-ui.spotlight class="rounded-lg border border-border bg-card p-10">
        <p class="text-center text-sm text-foreground">{{ __('Move your cursor across me') }}</p>
    </x-ui.spotlight>
    <x-ui.spotlight border mode="hover" color="chart-2" class="border border-border bg-card p-10">
        <p class="text-center text-sm text-foreground">{{ __('The rim lights up on hover') }}</p>
    </x-ui.spotlight>
</div>
```

## Props

- `color` (string, default `ring`) — Glow colour token: primary, accent, foreground, ring, or chart-1 through chart-5.
- `size` (string, default `350px`) — Diameter of the radial glow.
- `opacity` (string, default `0.25`) — Glow opacity at full strength.
- `mode` (string, default `always`) — always keeps the glow lit; hover fades it in only on hover or focus-within.
- `border` (bool, default `false`) — Also lights a faint currentColor rim around the wrapper, for a spotlight-card look.

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- Wrapping a card or panel in a soft radial glow that follows the cursor, for an interactive spotlight-card look.
- Wanting an always-on ambient glow or a hover/focus-only glow (mode="hover"), optionally with a matching lit border (border=true).

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- Wanting a rotating animated border instead of a cursor-following glow; use border-glow instead.
- Wanting a static, non-interactive brand bloom behind a hero; use glow instead.

## Anti-patterns

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

## Rules

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

@props([
    // primary | accent | foreground | ring | chart-1 … chart-5. `ring` (the
    // indigo focus hue) is the default: in the neutral palette `primary` is near
    // black, and a black glow reads as a shadow.
    'color' => 'ring',
    'size' => '350px',
    'opacity' => '0.25',
    'mode' => 'always',
    // Light the border where the pointer is: a second glow masked to a 1px
    // rim, so the edge itself catches the light.
    'border' => false,
])

@php
    // A cursor-tracking radial glow. Alpine (uiSpotlight) writes the pointer
    // position into the `--x`/`--y` CSS vars on @pointermove; the overlay paints
    // a radial-gradient centred there using `currentColor` (themed by a `text-*`
    // token). `--x`/`--y` default to 50% so with no pointer — or for
    // reduced-motion users, where onMove() bails via prefers-reduced-motion — a
    // static centred glow still shows. The overlay is decorative
    // (aria-hidden, pointer-events-none).
    //
    // - `mode='always'` keeps the glow lit (the original behaviour);
    //   `mode='hover'` fades the glow in only on hover/focus-within.
    // - `border` draws a faint currentColor rim (a "spotlight card") that shares
    //   the glow's token colour.
    $colorClass = match ($color) {
        'primary' => 'text-primary',
        'accent' => 'text-accent',
        'foreground' => 'text-foreground',
        'ring' => 'text-ring',
        'chart-1' => 'text-chart-1',
        'chart-2' => 'text-chart-2',
        'chart-3' => 'text-chart-3',
        'chart-4' => 'text-chart-4',
        'chart-5' => 'text-chart-5',
        default => 'text-ring',
    };

    $hoverMode = $mode === 'hover';
@endphp

<div
    data-slot="spotlight"
    data-mode="{{ $hoverMode ? 'hover' : 'always' }}"
    x-data="uiSpotlight({ hover: @js($hoverMode), opacity: @js((float) $opacity) })"
    @pointermove="onMove($event)"
    @if ($hoverMode) @pointerenter="active = true" @pointerleave="active = false" @focusin="active = true" @focusout="active = false" @endif
    style="--x:50%; --y:50%; --spot-size:{{ $size }}; --spot-opacity:{{ $opacity }};"
    {{ $attributes->merge(['class' => 'relative overflow-hidden '.($border ? 'rounded-lg' : '')]) }}
>
    <div
        aria-hidden="true"
        class="pointer-events-none absolute inset-0 transition-opacity duration-300 {{ $colorClass }}"
        style="background: radial-gradient(var(--spot-size) circle at var(--x) var(--y), currentColor, transparent 70%); opacity: var(--spot-opacity);"
        x-bind:style="{ opacity: (hover && !active) ? 0 : opacity }"
    ></div>
    @if ($border)
        {{-- The rim: the same gradient, masked to a 1px frame (padding-box cut
             out of border-box), so the border lights up under the pointer. --}}
        <div
            aria-hidden="true"
            data-slot="spotlight-rim"
            class="pointer-events-none absolute inset-0 rounded-[inherit] border border-transparent transition-opacity duration-300 {{ $colorClass }}"
            style="background: radial-gradient(calc(var(--spot-size) * 0.8) circle at var(--x) var(--y), currentColor, transparent 70%) border-box;"
            x-bind:style="{ opacity: (hover && !active) ? 0 : 1 }"
        ></div>
    @endif
    <div class="relative {{ $border ? 'text-foreground' : '' }}">{{ $slot }}</div>
</div>

/**
 * Spotlight behavior (spec §19 behavior layer).
 *
 * Tracks the pointer over the wrapper and writes its position (in px, relative
 * to the element) into the `--x`/`--y` CSS custom properties that the overlay's
 * radial-gradient reads. Movement is gated behind `prefers-reduced-motion`: when
 * reduced motion is requested onMove() bails, leaving the Blade defaults
 * (`--x:50%; --y:50%`) so a static centred glow remains.
 *
 * In `hover` mode the overlay's opacity is driven by `active` (set from the
 * Blade's pointerenter/leave + focusin/out handlers) so the glow only paints on
 * hover or keyboard focus; in the default `always` mode the static opacity wins.
 *
 * Self-registers on `alpine:init` so import order does not matter.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiSpotlight', (config = {}) => ({
        reduced: window.matchMedia('(prefers-reduced-motion: reduce)').matches,
        hover: config.hover ?? false,
        opacity: config.opacity ?? 0.15,
        active: false,

        onMove(event) {
            if (this.reduced) return;
            const rect = this.$el.getBoundingClientRect();
            this.$el.style.setProperty('--x', `${event.clientX - rect.left}px`);
            this.$el.style.setProperty('--y', `${event.clientY - rect.top}px`);
        },
    }));
});