Meteors

# Brok UI: Meteors (`meteors`)

A decorative shower of shooting meteors — token-coloured heads with fading gradient tails that streak diagonally across the box. Pure CSS, reduced-motion safe (static field).

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

## Install

```bash
php artisan ui:add meteors
```

## Usage

```blade
<div class="grid w-full max-w-2xl gap-4 sm:grid-cols-2">
    <div class="relative h-56 overflow-hidden rounded-lg border border-border bg-card">
        <x-ui.meteors :count="24" />
        <p class="absolute inset-x-0 bottom-4 text-center text-sm text-muted-foreground">{{ __('Foreground on a card') }}</p>
    </div>
    <div class="relative h-56 overflow-hidden rounded-lg bg-foreground">
        <x-ui.meteors :count="24" color="ring" />
        <p class="absolute inset-x-0 bottom-4 text-center text-sm text-background/70">{{ __('Ring hue on a dark field') }}</p>
    </div>
</div>
```

## Props

- `count` (int, default `20`) — Number of meteors, clamped to 80.
- `color` (string, default `foreground`) — Semantic colour token for the heads and tails (foreground, muted, primary, secondary, accent, ring, chart-1 … chart-5).

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- Adding a quick shooting-star flourish behind a hero or empty state, pure CSS with no canvas or WebGL cost.
- Wanting a decorative shower effect themed through a text-* colour utility.

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- Wanting a persistent ambient field rather than a transient streaking effect; use particles, sparkles or starfield instead.

## Anti-patterns

- Heavy effects in forms or task-dense workflows
- Motion that interferes with reading or focus

## Rules

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

@props([
    'count' => 20,
    // foreground | muted | primary | secondary | accent | ring | chart-1 … chart-5
    'color' => 'foreground',
])

@php
    // A decorative shower of shooting meteors. Each meteor is a small token-
    // coloured head with a fading gradient tail — both shapes live in ui.css as
    // `.ui-meteor` and inherit `currentColor`, so the design tokens stay the
    // single source of truth and nothing colour-bearing is written inline.
    // Pure CSS (no JS); motion-gated, so reduced-motion users get a static field.
    $colorClasses = [
        'foreground' => 'text-foreground',
        'muted' => 'text-muted-foreground',
        'primary' => 'text-primary',
        'secondary' => 'text-secondary-foreground',
        'accent' => 'text-accent-foreground',
        'ring' => 'text-ring',
        'chart-1' => 'text-chart-1',
        'chart-2' => 'text-chart-2',
        'chart-3' => 'text-chart-3',
        'chart-4' => 'text-chart-4',
        'chart-5' => 'text-chart-5',
    ];
    $colorClass = $colorClasses[$color] ?? 'text-foreground';

    // Clamp the count so a stray prop can't paint thousands of nodes.
    $count = max(1, min(80, (int) $count));
@endphp

{{-- Decorative fill layer: aria-hidden, non-interactive, clipped to its box. --}}
<div
    data-slot="meteors"
    aria-hidden="true"
    {{ $attributes->merge(['class' => $colorClass.' pointer-events-none absolute inset-0 overflow-hidden']) }}
>
    @for ($i = 0; $i < $count; $i++)
        @php
            // Spread the heads across the width and stagger delay/duration so the
            // shower never streaks in lockstep. These feed inline custom values
            // (position/timing only — never colour); they are NOT spliced into
            // utility classes, which the Tailwind JIT could not see.
            $left = mt_rand(0, 100);
            $top = mt_rand(-20, 40);                // heads start across the top band, not on one line
            $delay = mt_rand(0, 6000) / 1000;       // 0–6s before first streak
            $duration = mt_rand(2500, 7000) / 1000; // 2.5–7s per streak
            $size = mt_rand(1, 3);                  // 1–3px head; the tail scales with it
            $tail = mt_rand(3, 9);                  // 3–9rem tail
        @endphp
        <span
            class="ui-meteor"
            style="inset-inline-start: {{ $left }}%; --meteor-top: {{ $top }}%; --meteor-size: {{ $size }}px; --meteor-tail: {{ $tail }}rem; animation-delay: {{ $delay }}s; animation-duration: {{ $duration }}s;"
        ></span>
    @endfor
</div>