Loaders

# Brok UI: Text Loader (`text-loader`)

Text-based loading indicator in four variants — shimmer sweep, blink fade, trailing dots and a per-letter wave.

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

## Install

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

## Usage

```blade
<div class="flex flex-col items-start gap-6">
    <div class="flex flex-col items-start gap-1">
        <x-ui.text-loader variant="shimmer" text="Loading" />
        <span class="text-xs text-muted-foreground">shimmer</span>
    </div>
    <div class="flex flex-col items-start gap-1">
        <x-ui.text-loader variant="blink" text="Loading" />
        <span class="text-xs text-muted-foreground">blink</span>
    </div>
    <div class="flex flex-col items-start gap-1">
        <x-ui.text-loader variant="dots" text="Loading" />
        <span class="text-xs text-muted-foreground">dots</span>
    </div>
    <div class="flex flex-col items-start gap-1">
        <x-ui.text-loader variant="wave" text="Loading" />
        <span class="text-xs text-muted-foreground">wave</span>
    </div>
</div>
```

## Props

- `variant` (shimmer|blink|dots|wave, default `shimmer`) — Motion pattern: shimmer, blink, dots, or wave.
- `text` (string, default `Loading`) — The loading message, both displayed and used as the accessible label.
- `size` (md|sm|lg, default `md`) — Text size: sm, md, or lg.

## Use when

- Use while content or system work is in progress so users understand the interface is responding.
- Indicating an in-progress action with the loading text itself as the animated element, instead of a separate icon.
- Wanting a choice of four text motions (shimmer, blink, dots, wave) 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 an icon-only, compact loading indicator; use spinner or one of the shape loaders instead.
- Showing a determinate progress value; use progress instead.

## Anti-patterns

- Indefinite loading with no progress or recovery

## Rules

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

@props([
    'variant' => 'shimmer',
    'text' => 'Loading',
    'size' => 'md',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    // Text-based loaders faithful to loading-ui.com. Four visually distinct
    // variants — `shimmer` (a bright foreground band sweeps across muted text via
    // bg-clip-text), `blink` (whole text fades opacity), `dots` (trailing dots
    // appear one-by-one) and `wave` (each letter bobs in a travelling wave). All
    // motion lives in ui.css keyed on [data-slot="text-loader"][data-variant="…"]
    // and is gated for reduced-motion; all colour comes from semantic tokens so it
    // themes for free. The only inline styles are non-colour timing knobs
    // (animation-delay), and the accessible name is always present in the markup.
    $allowed = ['shimmer', 'blink', 'dots', 'wave'];
    $variant = in_array($variant, $allowed, true) ? $variant : 'shimmer';

    $sizes = [
        'sm' => 'text-sm',
        'md' => 'text-base',
        'lg' => 'text-lg',
    ];
    $size = array_key_exists($size, $sizes) ? $size : 'md';
    $sizeClass = $sizes[$size];

    $label = __($text);
@endphp

<div
    data-slot="text-loader"
    data-variant="{{ $variant }}"
    data-size="{{ $size }}"
    role="status"
    aria-label="{{ $label }}"
    {{ $attributes->merge(['class' => 'inline-flex items-center font-medium text-muted-foreground '.$sizeClass]) }}
>
    @if ($variant === 'shimmer')
        <span class="text-loader-shimmer relative inline-block bg-clip-text text-transparent">{{ $label }}</span>
    @elseif ($variant === 'blink')
        <span class="text-loader-blink inline-block">{{ $label }}</span>
    @elseif ($variant === 'dots')
        <span>{{ $label }}</span><span class="inline-flex" aria-hidden="true"><span class="text-loader-dot" style="animation-delay:0ms">.</span><span class="text-loader-dot" style="animation-delay:200ms">.</span><span class="text-loader-dot" style="animation-delay:400ms">.</span></span>
    @elseif ($variant === 'wave')
        @php
            $chars = preg_split('//u', $label, -1, PREG_SPLIT_NO_EMPTY) ?: [];
        @endphp
        <span aria-hidden="true">@foreach ($chars as $i => $char)<span class="text-loader-wave-letter inline-block" style="animation-delay:{{ $i * 80 }}ms">@if ($char === ' '){!! '&nbsp;' !!}@else{{ $char }}@endif</span>@endforeach</span>
    @endif
</div>