Loaders

# Brok UI: Spinner (`spinner`)

Inline loading indicator with twelve ring/arc/comet/gradient spinner variants and three sizes.

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

## Install

```bash
php artisan ui:add spinner
```

## Usage

```blade
<div class="flex flex-wrap items-end gap-x-10 gap-y-8 text-foreground">
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="ring" /><span class="text-xs text-muted-foreground">ring</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="classic" /><span class="text-xs text-muted-foreground">classic</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="spokes" /><span class="text-xs text-muted-foreground">spokes</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="arc" /><span class="text-xs text-muted-foreground">arc</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="dual-arc" /><span class="text-xs text-muted-foreground">dual-arc</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="fade-arc" /><span class="text-xs text-muted-foreground">fade-arc</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="quarter" /><span class="text-xs text-muted-foreground">quarter</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="dash" /><span class="text-xs text-muted-foreground">dash</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="comet" /><span class="text-xs text-muted-foreground">comet</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="spiral" /><span class="text-xs text-muted-foreground">spiral</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="swirl" /><span class="text-xs text-muted-foreground">swirl</span></div>
    <div class="flex flex-col items-center gap-3"><x-ui.spinner variant="gradient" /><span class="text-xs text-muted-foreground">gradient</span></div>
</div>
```

## Props

- `size` (md|sm|lg, default `md`) — Overall size: sm, md, or lg.
- `variant` (ring|classic|spokes|dual-arc|swirl|arc|fade-arc|quarter|dash|comet|spiral|gradient, default `ring`) — Visual style: ring, classic, spokes, arc, dual-arc, fade-arc, quarter, dash, comet, spiral, swirl, or gradient.

## Use when

- Use while content or system work is in progress so users understand the interface is responding.
- Indicating an inline, indeterminate busy state on a button, panel, or page.
- Wanting a choice of twelve spinner looks (ring, classic, spokes, arc, dual-arc, fade-arc, quarter, dash, comet, spiral, swirl, gradient) in three sizes.

## Avoid when

- Do not use indefinite loading indicators when you can show structure, progress, or a next step instead.
- Indicating a determinate, measurable percentage; use progress instead.
- Wanting a themed or shaped loader (bars, dots, grid, shapes); use the matching loader component instead.

## Anti-patterns

- Indefinite loading with no progress or recovery

## Rules

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

@props([
    'size' => 'md',
    'variant' => 'ring',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    // Twelve faithful loading-ui.com looks. The default `ring` keeps the original
    // bordered single-edge spin (so `animate-spin` still ships); every other look
    // is structural classes here + motion keyed on
    // [data-slot="spinner"][data-variant="…"] in ui.css (reduced-motion gated,
    // token-only colours). Never splice a value into an arbitrary class.
    $variants = ['ring', 'classic', 'spokes', 'arc', 'dual-arc', 'fade-arc', 'quarter', 'dash', 'comet', 'spiral', 'swirl', 'gradient'];
    $variant = in_array($variant, $variants, true) ? $variant : 'ring';

    // Per-size box + the ring border weight (reused by border-based variants).
    $sizes = [
        'sm' => 'size-4',
        'md' => 'size-5',
        'lg' => 'size-8',
    ];
    $borders = [
        'sm' => 'border-2',
        'md' => 'border-2',
        'lg' => 'border-[3px]',
    ];
    $box = $sizes[$size] ?? $sizes['md'];
    $border = $borders[$size] ?? $borders['md'];

    // Structural (non-colour) class string per variant. Colour + motion come from
    // tokens/CSS. Multi-element variants render children below instead.
    $variantClasses = [
        'ring' => "animate-spin rounded-full border-current/25 border-t-current motion-reduce:animate-none $border",
        'arc' => "rounded-full $border border-transparent border-t-current border-e-current",
        'quarter' => "rounded-full $border border-current/20 border-t-current border-e-current",
        'dash' => "rounded-full border-dashed $border border-current",
        'fade-arc' => 'rounded-full',
        'comet' => 'rounded-full',
        'spiral' => 'rounded-full',
        'gradient' => 'rounded-full',
        'dual-arc' => 'relative',
        'swirl' => 'relative',
        'classic' => 'relative',
        'spokes' => 'relative',
    ];

    $multi = in_array($variant, ['classic', 'spokes', 'dual-arc', 'swirl'], true);

    $classes = trim('inline-block shrink-0 '.($variantClasses[$variant] ?? $variantClasses['ring']).' '.$box);
@endphp

<span
    data-slot="spinner"
    data-size="{{ $size }}"
    data-variant="{{ $variant }}"
    role="status"
    aria-label="{{ __('Loading') }}"
    {{ $attributes->merge(['class' => $classes]) }}
>
    @if ($variant === 'classic')
        @for ($i = 0; $i < 12; $i++)
            <span class="spinner-spoke" aria-hidden="true" style="transform:rotate({{ $i * 30 }}deg);animation-delay:{{ -1100 + $i * 92 }}ms"></span>
        @endfor
    @elseif ($variant === 'spokes')
        @for ($i = 0; $i < 8; $i++)
            <span class="spinner-spoke spinner-spoke-thick" aria-hidden="true" style="transform:rotate({{ $i * 45 }}deg);animation-delay:{{ -1000 + $i * 125 }}ms"></span>
        @endfor
    @elseif ($variant === 'dual-arc')
        <span class="spinner-arc spinner-arc-outer {{ $border }} rounded-full border-transparent border-t-current border-b-current" aria-hidden="true"></span>
        <span class="spinner-arc spinner-arc-inner {{ $border }} rounded-full border-transparent border-l-current border-r-current" aria-hidden="true"></span>
    @elseif ($variant === 'swirl')
        <span class="spinner-swirl-arc spinner-swirl-a {{ $border }} rounded-full border-transparent border-t-current" aria-hidden="true"></span>
        <span class="spinner-swirl-arc spinner-swirl-b {{ $border }} rounded-full border-transparent border-b-current" aria-hidden="true"></span>
    @endif
</span>