Text Effects

# Brok UI: Encrypted Text (`encrypted-text`)

A scramble/decrypt text reveal: the text starts as random glyphs and decrypts character-by-character, left to right, into the real string. Triggers on scroll-into-view, hover, or load. Reduced-motion safe (final text shown immediately).

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

## Install

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

## Usage

```blade
<x-ui.encrypted-text as="p" class="text-xl font-semibold tracking-tight">Access granted to the mainframe</x-ui.encrypted-text>
```

## Props

- `as` (string, default `div`) — Root tag: div, span, p, or h1 through h6.
- `trigger` (string, default `view`) — When the decrypt starts: view (scrolled into view), hover, or load.
- `speed` (int, default `40`) — Milliseconds between scramble ticks for not-yet-revealed characters.
- `revealDelay` (int, default `60`) — Milliseconds between locking each additional leading character to its final value.
- `characters` (string, default `!<>-_\\/[]{}—=+*^?#________`) — Pool of glyphs cycled through while a character is still scrambled.

## Use when

- Use only when visual expression supports storytelling, brand differentiation, or a clear showcase moment.
- Revealing a heading or short line of text with a scramble-to-real decrypt animation, triggered on scroll into view, hover, or load.
- Wanting a cyberpunk/hacker-style text reveal while keeping the real string immediately available to assistive tech.

## Avoid when

- Do not place heavy effects in task-dense workflows where clarity, speed, and readability matter more.
- Revealing long paragraphs of body copy; the scramble effect is best for short headings or labels.
- Needing a typewriter-style character-by-character typing effect; use typewriter instead.

## Anti-patterns

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

## Rules

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

@props([
    'as' => 'div',
    'trigger' => 'view',
    'speed' => 40,
    'revealDelay' => 60,
    'characters' => '!<>-_\\/[]{}—=+*^?#________',
])

@php
    // Restrict the root tag to a safe, known set of inline/block containers.
    $allowedTags = ['div', 'span', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'div';

    // Whitelist the trigger so JS only ever receives a known value.
    $allowedTriggers = ['view', 'hover', 'load'];
    $trigger = in_array($trigger, $allowedTriggers, true) ? $trigger : 'view';

    // The real text comes from the slot and is the SSR/accessible fallback.
    $text = trim((string) ($slot ?? ''));

    $config = [
        'trigger' => $trigger,
        'speed' => max(1, (int) $speed),
        'revealDelay' => max(0, (int) $revealDelay),
        'characters' => (string) $characters,
    ];
@endphp

<{{ $tag }}
    data-slot="encrypted-text"
    x-data="uiEncryptedText(@js($config))"
    @if ($trigger === 'hover') @mouseenter="start()" @endif
    role="img"
    aria-label="{{ $text }}"
    {{ $attributes->merge(['class' => 'text-foreground']) }}
>{{ $text }}</{{ $tag }}>

/**
 * Encrypted-text behavior.
 *
 * Renders the real text as scrambled glyphs, then "decrypts" it
 * character-by-character from left to right into the final string. Each not-yet-
 * revealed character cycles through random glyphs from a pool on a fixed tick;
 * a separate cadence advances how many leading characters are locked to their
 * final value. The real text lives in `aria-label` on the root, so the animated
 * glyph spans are decorative (`aria-hidden`) and assistive tech reads the true
 * string. Honors reduced-motion by showing the final text immediately.
 *
 * Triggers:
 *   - "view": start once when scrolled into view (IntersectionObserver).
 *   - "hover": (re)start on mouseenter (wired in the Blade via @mouseenter).
 *   - "load": start in init().
 *
 * All timers/observers are torn down in destroy() so unmounting mid-animation
 * cannot leak. Self-registers on `alpine:init` so import order does not matter.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiEncryptedText', (config = {}) => ({
        trigger: config.trigger ?? 'view',
        speed: config.speed ?? 40,
        revealDelay: config.revealDelay ?? 60,
        characters: (config.characters ?? '!<>-_\\/[]{}—=+*^?#________').split(''),

        _text: '',
        _revealed: 0,
        _scrambleTimer: null,
        _revealTimer: null,
        _observer: null,
        _running: false,

        init() {
            // Capture the SSR text content, then take over rendering.
            this._text = this.$el.textContent;

            // Reduced motion: leave the final text in place, no scramble.
            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
                return;
            }

            // Show a fully-scrambled frame immediately so nothing flashes the
            // real text before the chosen trigger fires.
            this._revealed = 0;
            this._render();

            if (this.trigger === 'load') {
                this.start();
            } else if (this.trigger === 'view') {
                this._observe();
            }
            // "hover" is started by the @mouseenter binding in the Blade.
        },

        // Begin (or restart) the decrypt animation from a fully-scrambled state.
        start() {
            if (this._running || !this._text.length) {
                return;
            }
            this._running = true;
            this._revealed = 0;

            // Continuously scramble every not-yet-revealed character.
            this._scrambleTimer = setInterval(() => this._render(), this.speed);

            // Lock one more leading character to its final value each cadence,
            // walking left to right until the whole string is revealed.
            const step = () => {
                this._revealed++;
                this._render();
                if (this._revealed >= this._text.length) {
                    this._stopScrambling();
                    return;
                }
                this._revealTimer = setTimeout(step, this.revealDelay);
            };
            this._revealTimer = setTimeout(step, this.revealDelay);
        },

        // Paint the current frame: revealed chars settled, the rest scrambled.
        _render() {
            let html = '';
            for (let i = 0; i < this._text.length; i++) {
                const ch = this._text[i];
                // Preserve whitespace as-is so word boundaries are stable.
                if (/\s/.test(ch)) {
                    html += ch;
                    continue;
                }
                if (i < this._revealed) {
                    html += `<span aria-hidden="true" class="text-foreground">${this._escape(ch)}</span>`;
                } else {
                    const glyph = this.characters[Math.floor(Math.random() * this.characters.length)] ?? ch;
                    html += `<span aria-hidden="true" class="text-muted-foreground">${this._escape(glyph)}</span>`;
                }
            }
            this.$el.innerHTML = html;
        },

        // Escape so glyphs/text can never inject markup into innerHTML.
        _escape(value) {
            return value
                .replace(/&/g, '&amp;')
                .replace(/</g, '&lt;')
                .replace(/>/g, '&gt;');
        },

        // Start the animation the first time the element scrolls into view.
        _observe() {
            if (!('IntersectionObserver' in window)) {
                this.start();
                return;
            }
            this._observer = new IntersectionObserver((entries) => {
                entries.forEach((entry) => {
                    if (entry.isIntersecting) {
                        this.start();
                        this._observer.disconnect();
                        this._observer = null;
                    }
                });
            });
            this._observer.observe(this.$el);
        },

        _stopScrambling() {
            if (this._scrambleTimer) {
                clearInterval(this._scrambleTimer);
                this._scrambleTimer = null;
            }
            if (this._revealTimer) {
                clearTimeout(this._revealTimer);
                this._revealTimer = null;
            }
            this._running = false;
        },

        destroy() {
            this._stopScrambling();
            if (this._observer) {
                this._observer.disconnect();
                this._observer = null;
            }
        },
    }));
});