Shimmering Text

# Brok UI: Shimmering Text (`shimmering-text`)

Text with a bright highlight that sweeps across it on a loop, built from semantic tokens via bg-clip-text. Pure CSS, motion-safe (reduced motion shows static muted text).

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

## Install

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

## Usage

```blade
<div class="space-y-6">
    <x-ui.shimmering-text as="span" class="text-3xl font-semibold">
        {{ __('Generating response…') }}
    </x-ui.shimmering-text>

    <x-ui.shimmering-text as="span" :duration="3" :spread="3" class="text-base">
        {{ __('Thinking through the best answer for you') }}
    </x-ui.shimmering-text>
</div>
```

## Props

- `as` (string, default `span`) — Root tag: span, p, or h1 through h6.
- `duration` (int, default `2`) — Seconds for one sweep of the highlight, clamped to a minimum of 0.1.
- `spread` (int, default `2`) — Width of the bright band, in rem, clamped to a minimum of 0.

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- Adding a subtle, looping bright-highlight sweep across a heading or label to suggest premium or loading emphasis.
- Wanting a pure-CSS text effect built entirely from semantic tokens, with tunable sweep duration and band width.

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- Needing a loading indicator with a status role; use text-loader instead, since this component carries no ARIA status semantics.
- Applying the effect to long paragraphs; a continuously sweeping highlight is best for short headlines or labels.

## Anti-patterns

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

## Rules

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

@props([
    'as' => 'span',
    'duration' => 2,
    'spread' => 2,
])

@php
    // A bright highlight sweeps across muted text, looping. The effect is built
    // entirely from semantic tokens: the resting glyph colour is `--muted-foreground`
    // and the moving band is `--foreground`, both wired up in ui.css keyed off
    // `data-slot` (so nothing raw-coloured lives in this markup). Only the two
    // numeric tuning knobs travel inline as CSS custom properties:
    //   --shimmer-duration : seconds for one sweep
    //   --shimmer-spread   : width of the bright band (rem)
    // Motion-safe only — reduced-motion users see calm, static muted text.
    $dur = is_numeric($duration) ? max(0.1, (float) $duration) : 2;
    $spread = is_numeric($spread) ? max(0, (float) $spread) : 2;
    $allowedTags = ['span', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'span';
@endphp

<{{ $tag }}
    data-slot="shimmering-text"
    data-animate="true"
    style="--shimmer-duration: {{ $dur }}s; --shimmer-spread: {{ $spread }}rem;"
    {{ $attributes->merge(['class' => 'relative inline-block bg-clip-text text-transparent']) }}
>{{ $slot }}</{{ $tag }}>