Loaders

# Brok UI: Dots Loader (`dots-loader`)

Animated loading dots with an optional label, in seven variants — shimmer, bounce, pulse, bobbing, pulsating, typing and triple (triangle spinner).

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

## Install

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

## Usage

```blade
<div class="flex flex-col items-start gap-5">
    <x-ui.dots-loader variant="shimmer" label="shimmer" />
    <x-ui.dots-loader variant="bounce" label="bounce" />
    <x-ui.dots-loader variant="pulse" label="pulse" />
    <x-ui.dots-loader variant="bobbing" label="bobbing" />
    <x-ui.dots-loader variant="pulsating" label="pulsating" />
    <x-ui.dots-loader variant="typing" label="typing" />
    <x-ui.dots-loader variant="triple" label="triple" />
</div>
```

## Props

- `variant` (shimmer|bounce|pulse|bobbing|pulsating|typing|triple, default `shimmer`) — Motion pattern: shimmer, bounce, pulse, bobbing, pulsating, typing, or triple.
- `label` (string, default `Loading`) — Accessible status label announced to screen readers.

## Use when

- Use while content or system work is in progress so users understand the interface is responding.
- Indicating an in-progress background action with a compact animated dots indicator.
- Wanting a choice of seven dot motions (shimmer, bounce, pulse, bobbing, pulsating, typing, triple) to match a loading-ui.com aesthetic.

## Avoid when

- Do not use indefinite loading indicators when you can show structure, progress, or a next step instead.
- Needing a generic circular spinner; use spinner instead.
- Loading a full page or section; pair with skeleton for layout-shaped placeholders instead.

## Anti-patterns

- Indefinite loading with no progress or recovery

## Rules

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

@props([
    'variant' => 'shimmer',
    'label' => 'Loading',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);

    $allowed = ['shimmer', 'bounce', 'pulse', 'bobbing', 'pulsating', 'typing', 'triple'];
    $variant = in_array($variant, $allowed, true) ? $variant : 'shimmer';

    // shimmer/bounce read their dot classes from the shared _styles map. The new
    // variants define their classes inline here (so the shared file is untouched);
    // their motion is keyed on [data-slot][data-variant] in ui.css. Every dot keeps
    // the `dots-loader-dot` hook the CSS animations target.
    $inlineDots = [
        'pulse' => 'dots-loader-dot size-2 rounded-full bg-current',
        'bobbing' => 'dots-loader-dot size-2 rounded-full bg-current',
        'pulsating' => 'dots-loader-dot size-2 rounded-full bg-current',
        'typing' => 'dots-loader-dot size-2 rounded-full bg-current',
        'triple' => 'dots-loader-dot absolute size-2 rounded-full bg-current',
    ];

    $dotClass = $styles['dots-loader']['dots'][$variant] ?? $inlineDots[$variant];
    $tightGap = $variant === 'typing';
@endphp

{{--
    Dots loader — animated loading dots with an optional label, faithful to
    loading-ui.com. `variant` picks the motion: `shimmer` (gradient pulse) and
    `bounce` read from _styles.php; `pulse` (opacity fade), `bobbing` (gentle
    translateY), `pulsating` (scale), `typing` (tight chat-style bob) and `triple`
    (three dots rotating in a triangle) are defined inline + in ui.css, keyed on
    [data-slot="dots-loader"][data-variant="…"] and gated for reduced-motion so the
    raw-colour guard stays happy.
--}}
<div
    data-slot="dots-loader"
    data-variant="{{ $variant }}"
    role="status"
    aria-label="{{ __($label) }}"
    {{ $attributes->merge(['class' => 'inline-flex items-center gap-2 text-sm text-muted-foreground']) }}
>
    @if ($variant === 'triple')
        <span class="relative inline-block size-6" aria-hidden="true">
            <span class="{{ $dotClass }}" style="animation-delay:0ms"></span>
            <span class="{{ $dotClass }}" style="animation-delay:-1s"></span>
            <span class="{{ $dotClass }}" style="animation-delay:-2s"></span>
        </span>
    @else
        <span class="inline-flex items-center {{ $tightGap ? 'gap-0.5' : 'gap-1' }}" aria-hidden="true">
            <span class="{{ $dotClass }}" style="animation-delay:0ms"></span>
            <span class="{{ $dotClass }}" style="animation-delay:140ms"></span>
            <span class="{{ $dotClass }}" style="animation-delay:280ms"></span>
        </span>
    @endif
    <span>{{ __($label) }}</span>
</div>