Loaders

# Brok UI: Grid Loader (`grid-loader`)

A 3x3 grid of squares animating in four faithful loading-ui.com patterns — grid (diagonal pulse wave), square-accordion, conveyor and snake.

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

## Install

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

## Usage

```blade
<div class="flex flex-wrap items-start gap-10">
    <div class="flex flex-col items-center gap-3">
        <x-ui.grid-loader variant="grid" label="grid" />
        <span class="text-xs text-muted-foreground">grid</span>
    </div>
    <div class="flex flex-col items-center gap-3">
        <x-ui.grid-loader variant="square-accordion" label="square-accordion" />
        <span class="text-xs text-muted-foreground">square-accordion</span>
    </div>
    <div class="flex flex-col items-center gap-3">
        <x-ui.grid-loader variant="conveyor" label="conveyor" />
        <span class="text-xs text-muted-foreground">conveyor</span>
    </div>
    <div class="flex flex-col items-center gap-3">
        <x-ui.grid-loader variant="snake" label="snake" />
        <span class="text-xs text-muted-foreground">snake</span>
    </div>
</div>
```

## Props

- `variant` (grid|square-accordion|conveyor|snake, default `grid`) — Motion pattern: grid, square-accordion, conveyor, or snake.
- `size` (md|sm|lg, default `md`) — Overall grid box size: sm, md, or lg.
- `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 square-grid indicator.
- Wanting a choice of four grid motions (grid, square-accordion, conveyor, snake) 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:grid-loader>` tag (or `<x-ui.grid-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/grid-loader
- Registry JSON (files, props, contract): https://brokui.dev/r/open/grid-loader.json

@props([
    'variant' => 'grid',
    'size' => 'md',
    'label' => 'Loading',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    // Faithful loading-ui.com square-grid loaders. A fixed 3x3 grid of bg-current
    // squares; `variant` picks the motion. ALL animation lives in ui.css keyed on
    // [data-slot="grid-loader"][data-variant="…"] (reduced-motion gated, token-only
    // colours). Per-cell timing rides on inline `animation-delay` so the wave /
    // snake / conveyor ordering works without splicing values into Tailwind classes.
    $allowed = ['grid', 'square-accordion', 'conveyor', 'snake'];
    $variant = in_array($variant, $allowed, true) ? $variant : 'grid';

    // Per-size box + grid gap. Fixed class strings only — never spliced.
    $sizes = [
        'sm' => 'size-6 gap-0.5',
        'md' => 'size-9 gap-1',
        'lg' => 'size-12 gap-2',
    ];
    $box = $sizes[$size] ?? $sizes['md'];

    // Per-variant cell-delay ordering for the 9 cells (indices 0..8, row-major):
    //   0 1 2
    //   3 4 5
    //   6 7 8
    // `grid`   — diagonal wave: delay grows with (row + col).
    // square-accordion — row-by-row ripple: delay grows with the row.
    // conveyor — clockwise loop around the 8 edge cells; centre rests.
    // snake    — boustrophedon path lighting cells one after another.
    $step = 110; // ms between successive cells

    $diagonal = [0, 1, 2, 1, 2, 3, 2, 3, 4]; // row + col per index
    $rowOf = [0, 0, 0, 1, 1, 1, 2, 2, 2];
    // Clockwise edge ring order: TL,T,TR,R,BR,B,BL,L. Centre (index 4) = null.
    $conveyorOrder = [0 => 0, 1 => 1, 2 => 2, 5 => 3, 8 => 4, 7 => 5, 6 => 6, 3 => 7, 4 => null];
    // Snake path: row0 L→R, row1 R→L, row2 L→R.
    $snakeOrder = [0 => 0, 1 => 1, 2 => 2, 5 => 3, 4 => 4, 3 => 5, 6 => 6, 7 => 7, 8 => 8];

    $delays = [];
    for ($i = 0; $i < 9; $i++) {
        if ($variant === 'square-accordion') {
            $delays[$i] = $rowOf[$i] * $step * 2;
        } elseif ($variant === 'conveyor') {
            $order = $conveyorOrder[$i];
            $delays[$i] = $order === null ? null : $order * $step;
        } elseif ($variant === 'snake') {
            $delays[$i] = $snakeOrder[$i] * $step;
        } else { // grid — diagonal wave
            $delays[$i] = $diagonal[$i] * $step;
        }
    }
@endphp

{{--
    Grid loader — a 3x3 grid of squares animating in faithful loading-ui.com
    patterns. `grid` (diagonal pulse wave), `square-accordion` (row-by-row ripple),
    `conveyor` (edge cells loop clockwise) and `snake` (cells light along a snake
    path). Motion is defined in ui.css keyed on [data-slot="grid-loader"]
    [data-variant="…"] and gated for reduced motion; colours are tokens only.
--}}
<span
    data-slot="grid-loader"
    data-variant="{{ $variant }}"
    data-size="{{ $size }}"
    role="status"
    aria-label="{{ __($label) }}"
    {{ $attributes->merge(['class' => 'inline-grid grid-cols-3 text-muted-foreground '.$box]) }}
>
    @for ($i = 0; $i < 9; $i++)
        <span
            class="grid-loader-cell rounded-[2px] bg-current"
            aria-hidden="true"
            @if (! is_null($delays[$i])) style="animation-delay:{{ $delays[$i] }}ms" @else data-rest="true" @endif
        ></span>
    @endfor
    <span class="sr-only">{{ __($label) }}</span>
</span>