Loaders

# Brok UI: Terminal Loader (`terminal-loader`)

A terminal-window loader whose command lines reveal one-by-one with a blinking block cursor, looping as ongoing work.

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

## Install

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

## Usage

```blade
<div class="w-full flex justify-center"><x-ui.terminal-loader class="w-72" /></div>
```

## Props

- `lines` (array, default `['$ npm install', '› building modules…', '› optimizing…', '✓ ready']`) — Command lines revealed one-by-one, in order; falls back to a two-line default when empty.
- `label` (string, default `Loading`) — Accessible status label announced to screen readers.
- `variant` (string, default `default`) — Reserved for future looks; any value currently renders the same default look.

## Use when

- Use while content or system work is in progress so users understand the interface is responding.
- Indicating background build, install, or processing work with a faithful terminal-window animation.
- Wanting command lines to reveal one-by-one with a blinking cursor, looping as ongoing work.

## Avoid when

- Do not use indefinite loading indicators when you can show structure, progress, or a next step instead.
- Needing a generic, chrome-free loading indicator; use spinner or dots-loader instead.
- Showing a real, live command output stream; this component only loops a fixed, static set of lines.

## Anti-patterns

- Indefinite loading with no progress or recovery

## Rules

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

@props([
    'lines' => ['$ npm install', '› building modules…', '› optimizing…', '✓ ready'],
    'label' => 'Loading',
    'variant' => 'default',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    // A faithful loading-ui.com "terminal" loader: a small window where command
    // lines reveal one-by-one and the last line carries a blinking block cursor.
    // The whole sequence loops so it reads as ongoing work. Motion lives in
    // ui.css keyed on [data-slot="terminal-loader"] and is reduced-motion gated;
    // line text is escaped via {{ }} so arbitrary strings stay inert.
    $variant = $variant === 'default' ? 'default' : 'default';
    $lines = array_values(array_filter((array) $lines, fn ($l) => $l !== null));
    if ($lines === []) {
        $lines = ['$ npm install', '✓ ready'];
    }
    $last = count($lines) - 1;
@endphp

<div
    data-slot="terminal-loader"
    data-variant="{{ $variant }}"
    role="status"
    aria-label="{{ __($label) }}"
    {{ $attributes->merge(['class' => 'inline-block bg-card border border-border rounded-lg font-mono text-xs text-muted-foreground overflow-hidden']) }}
>
    <span class="sr-only">{{ __($label) }}</span>

    <div class="flex items-center gap-2 border-b border-border px-3 py-2" aria-hidden="true">
        <span class="size-2 rounded-full bg-muted-foreground/40"></span>
        <span class="size-2 rounded-full bg-muted-foreground/40"></span>
        <span class="size-2 rounded-full bg-muted-foreground/40"></span>
    </div>

    <div class="flex flex-col gap-1 px-3 py-3 leading-5" aria-hidden="true">
        @foreach ($lines as $line)
            <div class="terminal-loader-line flex items-center" style="animation-delay:{{ $loop->index * 350 }}ms">
                <span>{{ $line }}</span>
                @if ($loop->index === $last)
                    <span class="terminal-loader-cursor ms-1 inline-block h-4 w-2 bg-foreground"></span>
                @endif
            </div>
        @endforeach
    </div>
</div>