Loaders

# Brok UI: Eyes Loader (`eyes-loader`)

A wandering-eyes loader — two eyes whose pupils look left, right, up and down in sync, with an occasional blink; the pupils follow the pointer.

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

## Install

```bash
php artisan ui:add eyes-loader
```

## Usage

```blade
<div class="flex flex-wrap items-end gap-8">
    <div class="flex flex-col items-center gap-3"><x-ui.eyes-loader size="sm" /><span class="text-xs text-muted-foreground">sm</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.eyes-loader size="md" /><span class="text-xs text-muted-foreground">md</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.eyes-loader size="lg" /><span class="text-xs text-muted-foreground">lg</span></div>
</div>
```

## Props

- `label` (string, default `Loading`) — Accessible status label announced to screen readers.
- `size` (md|sm|lg, default `md`) — Eye and pupil size: sm, md, or lg.
- `variant` (string, default `default`) — Reserved for future looks; any value currently renders the same default look.
- `follow` (bool, default `true`) — Pupils track the pointer when true; false keeps the CSS wandering motion only.

## Use when

- Use while content or system work is in progress so users understand the interface is responding.
- Adding a playful, attention-catching loading indicator to an empty or waiting state, such as a chatbot or search widget.
- Wanting the pupils to track the pointer for a lightweight, characterful touch.

## Avoid when

- Do not use indefinite loading indicators when you can show structure, progress, or a next step instead.
- Needing a neutral, brand-agnostic loading indicator; use spinner or dots-loader instead.
- Building a dense, professional dashboard; the wandering eyes read as informal.

## Anti-patterns

- Indefinite loading with no progress or recovery

## Rules

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

@props([
    'label' => 'Loading',
    'size' => 'md',
    'variant' => 'default',
    // The pupils follow the pointer (fine pointers, motion allowed); false
    // keeps the CSS wandering only.
    'follow' => true,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    // Wandering-eyes loader, faithful to loading-ui.com. Two side-by-side eyes
    // (bg-card surface, border-border) each hold a foreground pupil that looks
    // around — left, right, up, down — in sync, with an occasional blink. A
    // single look ships (variant `default`). Motion lives in ui.css keyed on
    // [data-slot="eyes-loader"] (+ .ui-eyesloader-pupil), reduced-motion gated.
    // Never splice a value into an arbitrary class — pick from fixed maps.
    $variant = $variant === 'default' ? 'default' : 'default';

    $eyes = [
        'sm' => 'size-5',
        'md' => 'size-7',
        'lg' => 'size-10',
    ];
    $pupils = [
        'sm' => 'size-2',
        'md' => 'size-2',
        'lg' => 'size-4',
    ];
    $eye = $eyes[$size] ?? $eyes['md'];
    $pupil = $pupils[$size] ?? $pupils['md'];

    $eyeClass = "ui-eyesloader-eye relative inline-flex shrink-0 rounded-full bg-card border border-border $eye";
    // While following, the pupil's position comes from --eye-dx/--eye-dy set by
    // eyes-loader.js (ui.css swaps the keyframes for that transform).
    $pupilClass = "ui-eyesloader-pupil absolute left-1/2 top-1/2 rounded-full bg-foreground $pupil";
@endphp

<span
    data-slot="eyes-loader"
    data-variant="{{ $variant }}"
    data-size="{{ $size }}"
    x-data="uiEyesLoader({ follow: {{ \Illuminate\Support\Js::from((bool) $follow) }} })"
    :data-following="following ? 'true' : null"
    role="status"
    aria-label="{{ __($label) }}"
    {{ $attributes->merge(['class' => 'inline-flex items-center gap-2 text-muted-foreground']) }}
>
    <span class="inline-flex items-center gap-1" aria-hidden="true">
        <span class="{{ $eyeClass }}" data-eye>
            <span class="{{ $pupilClass }}"></span>
        </span>
        <span class="{{ $eyeClass }}" data-eye>
            <span class="{{ $pupilClass }}"></span>
        </span>
    </span>
    <span class="sr-only">{{ __($label) }}</span>
</span>

/**
 * Eyes loader behavior — the pupils follow the pointer.
 *
 * While a pointer moves anywhere on the page, each pupil looks towards it
 * (offset capped inside the eye); after 1.5s without movement the eyes go
 * back to the CSS wandering keyframes, so the loader never freezes into a
 * stare. Touch-only devices and reduced motion keep the CSS motion. `follow:
 * false` turns the tracking off. Listeners are removed on destroy.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiEyesLoader', (config = {}) => ({
        follow: config.follow ?? true,
        following: false,
        _onMove: null,
        _idle: null,
        _frame: null,

        init() {
            const fine = window.matchMedia('(pointer: fine)').matches;
            const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
            if (!this.follow || !fine || reduced) return;
            this._onMove = (e) => this.look(e.clientX, e.clientY);
            window.addEventListener('pointermove', this._onMove, { passive: true });
        },

        look(px, py) {
            cancelAnimationFrame(this._frame);
            this._frame = requestAnimationFrame(() => {
                this.following = true;
                this.$root.querySelectorAll('[data-eye]').forEach((eye) => {
                    const r = eye.getBoundingClientRect();
                    const cx = r.left + r.width / 2;
                    const cy = r.top + r.height / 2;
                    const dx = px - cx;
                    const dy = py - cy;
                    const distance = Math.hypot(dx, dy) || 1;
                    // The pupil travels at most 28% of the eye's radius from centre.
                    const reach = Math.min(distance, r.width * 0.28);
                    eye.style.setProperty('--eye-dx', `${(dx / distance) * reach}px`);
                    eye.style.setProperty('--eye-dy', `${(dy / distance) * reach}px`);
                });
            });
            clearTimeout(this._idle);
            this._idle = setTimeout(() => {
                this.following = false;
            }, 1500);
        },

        destroy() {
            if (this._onMove) window.removeEventListener('pointermove', this._onMove);
            clearTimeout(this._idle);
            cancelAnimationFrame(this._frame);
        },
    }));
});