Text Effects

# Brok UI: Text Gradient (`text-gradient`)

Wraps text so it renders with a color gradient via bg-clip-text. Defaults use semantic tokens. Optional animated mode flows the gradient through the glyphs on a loop (reduced-motion safe).

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

## Install

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

## Usage

```blade
<div class="space-y-6">
    {{-- Default gradient: from-primary -> to-accent --}}
    <x-ui.text-gradient as="h2" class="text-4xl font-bold">
        {{ __('Build beautiful interfaces faster') }}
    </x-ui.text-gradient>

    {{-- Override with a via stop for a three-color gradient --}}
    <x-ui.text-gradient as="h2" via="via-accent" to="to-primary" class="text-4xl font-bold">
        {{ __('Designed with semantic tokens') }}
    </x-ui.text-gradient>
</div>
```

## Props

- `as` (string, default `span`) — Root tag: span, p, or h1 through h6.
- `direction` (string, default `bg-gradient-to-r`) — Tailwind gradient-direction utility class.
- `from` (string, default `from-primary`) — Gradient start colour utility.
- `via` (mixed|null, default `null`) — Optional gradient midpoint colour utility; when animated is true and via is omitted, one is derived from from.
- `to` (string, default `to-foreground`) — Gradient end colour utility.
- `animated` (bool, default `false`) — Flows the gradient through the glyphs on a loop instead of holding it static.
- `duration` (int, default `3`) — Seconds for one animated wave cycle, clamped to a minimum of 0.1; only used when animated is true.

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- Rendering a heading or short phrase with a semantic-token colour gradient clipped to the glyphs.
- Wanting an optional Apple-style animated wave that flows the gradient through the text on a loop.

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- Needing a solid, single-colour heading; a plain text-* utility is simpler and avoids the bg-clip-text setup.
- Needing per-letter or per-word motion instead of a colour sweep; use text-animate, kinetic-text-reveal, or letter-cascade instead.

## Anti-patterns

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

## Rules

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

@props([
    'as' => 'span',
    'direction' => 'bg-gradient-to-r',
    'from' => 'from-primary',
    'via' => null,
    'to' => 'to-foreground',
    // When true the gradient flows through the glyphs on a loop (Apple-style wave).
    // Motion lives in ui.css keyed on [data-slot][data-animate]; only the cycle
    // duration travels inline as the --text-gradient-duration custom property.
    // Reduced-motion users see the gradient resting, static.
    'animated' => false,
    // Seconds for one wave cycle (only used when `animated`).
    'duration' => 3,
])

@php
    $allowedTags = ['span', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'span';
    // Assemble the gradient utilities. `via` is optional and filtered out when null.
    // Defaults reference our semantic color tokens (from-primary → to-foreground),
    // not raw palette colors, so they adapt with the token layer (incl. dark mode)
    // and stay legible on any surface — `to-accent` would fade into a light
    // background. Override from/via/to for a different ramp.
    // `bg-clip-text` + `text-transparent` clip the gradient to the glyphs.
    // For the animated wave a mid stop makes the flow read best, so when animated
    // with no `via` supplied, derive one from the `from` token (from-X → via-X) so
    // the colour pulses through a midpoint as it slides. Pass an explicit `via`
    // (e.g. via-info) and matching from/to for a perfectly seamless loop.
    $waveVia = $animated && $via === null ? preg_replace('/^from-/', 'via-', $from) : $via;

    $classes = trim(implode(' ', array_filter([
        $direction,
        $from,
        $waveVia,
        $to,
        'bg-clip-text',
        'text-transparent',
    ])));

    $dur = is_numeric($duration) ? max(0.1, (float) $duration) : 3;
@endphp

<{{ $tag }}
    data-slot="text-gradient"
    @if ($animated) data-animate="true" style="--text-gradient-duration: {{ $dur }}s;" @endif
    {{ $attributes->merge(['class' => $classes]) }}
>{{ $slot }}</{{ $tag }}>