Chat Bubble

# Brok UI: Chat Bubble (`chat-bubble`)

A chat bubble for a single sender turn with an optional avatar and name label; supports user, other, and system roles.

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

## Install

```bash
php artisan ui:add chat-bubble
```

## Usage

```blade
<div class="mx-auto flex w-full max-w-md flex-col gap-4">
    <x-ui.chat-bubble role="user" name="You">Is the Q3 launch still on track?</x-ui.chat-bubble>
    <x-ui.chat-bubble role="other" name="Support">Yes — the rollout is staged behind a flag and we are on schedule.</x-ui.chat-bubble>
    {{-- An assistant reply arriving: the text streams in once, with a caret. --}}
    <x-ui.chat-bubble role="other" name="Assistant" stream>The billing revamp ships first, then the new onboarding. Both are behind flags, so we can revert in one click.</x-ui.chat-bubble>
    {{-- The other side is typing. --}}
    <x-ui.chat-bubble role="other" name="Support" typing />
    <x-ui.chat-bubble role="system">Conversation summarised to save space.</x-ui.chat-bubble>
</div>
```

## Props

- `role` (string, default `user`)
- `name` (mixed|null, default `null`)
- `avatar` (mixed|null, default `null`)
- `typing` (bool, default `false`)
- `stream` (bool, default `false`)

## Use when

- Use to group related content into scannable units for browsing, prioritization, or rearrangement.
- Rendering one turn in a conversation, aligned and coloured by who sent it.
- Showing that the other party is typing, or streaming a reply in as it arrives.

## Avoid when

- Do not use card-like structures when dense row-by-row comparison would be clearer in a list or table.
- Laying out a full conversation; chat-thread stacks the bubbles.
- Displaying a notification or toast; those have their own primitives.

## Anti-patterns

- Turning every object into a card

## Rules

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

@props([
    'role' => 'user',
    'name' => null,
    'avatar' => null,
    // The sender is typing: the bubble shows three pulsing dots instead of text.
    'typing' => false,
    // Stream the text in once, a few characters at a time with a caret, the
    // way an assistant reply arrives; reduced motion shows it at once.
    'stream' => false,
])

@php
    // Normalize role to one of the three supported variants.
    $role = in_array($role, ['user', 'other', 'system'], true) ? $role : 'user';
    $isUser = $role === 'user';
    $isSystem = $role === 'system';

    // Build initials for the avatar fallback from the provided name.
    $initials = null;
    if ($name) {
        $parts = preg_split('/\s+/', trim((string) $name));
        $initials = collect($parts)
            ->filter()
            ->take(2)
            ->map(fn ($p) => mb_strtoupper(mb_substr($p, 0, 1)))
            ->implode('');
    }

    // System turns render as a centered, subtle notice rather than a sided bubble.
    if ($isSystem) {
        $rowClasses = 'flex w-full justify-center';
    } else {
        // User turns flow from the end (mirrored in RTL); other senders from the start.
        $rowClasses = 'flex w-full items-end gap-2 '.($isUser ? 'flex-row-reverse' : 'flex-row');
    }

    if ($isSystem) {
        $bubbleClasses = 'max-w-[90%] rounded-full bg-accent px-3 py-1 text-center text-xs text-muted-foreground';
    } elseif ($isUser) {
        // Flatten the end (trailing) corner toward the avatar/edge.
        $bubbleClasses = 'max-w-[80%] rounded-md rounded-ee-sm bg-primary px-4 py-2 text-sm text-primary-foreground';
    } else {
        // Flatten the start (leading) corner toward the avatar/edge.
        $bubbleClasses = 'max-w-[80%] rounded-md rounded-es-sm bg-muted px-4 py-2 text-sm text-foreground';
    }
@endphp

<div
    data-slot="chat-bubble"
    data-role="{{ $role }}"
    {{ $attributes->merge(['class' => $rowClasses]) }}
>
    @unless ($isSystem)
        @if ($avatar || $initials)
            <div
                aria-hidden="true"
                class="flex size-8 shrink-0 select-none items-center justify-center overflow-hidden rounded-full bg-accent text-xs font-medium text-muted-foreground"
            >
                @if ($avatar)
                    <img src="{{ $avatar }}" alt="" class="size-full object-cover" />
                @else
                    {{ $initials }}
                @endif
            </div>
        @endif
    @endunless

    <div class="flex min-w-0 flex-col gap-1 {{ $isUser ? 'items-end' : 'items-start' }}">
        @if ($name && ! $isSystem)
            <span class="px-1 text-xs font-medium text-muted-foreground">{{ $name }}</span>
        @endif

        @if ($typing)
            <div class="{{ $bubbleClasses }}" data-slot="chat-bubble-typing" role="status" aria-label="{{ $name ? __(':name is typing', ['name' => $name]) : __('Typing') }}">
                <span class="flex h-5 items-center gap-1" aria-hidden="true">
                    @foreach ([0, 160, 320] as $delay)
                        <span class="size-2 shrink-0 rounded-full bg-current opacity-50 motion-safe:animate-[ui-ai-typing-bounce_1.2s_ease-in-out_infinite]" style="animation-delay: {{ $delay }}ms"></span>
                    @endforeach
                </span>
            </div>
        @elseif ($stream)
            <div
                class="{{ $bubbleClasses }}"
                data-slot="chat-bubble-stream"
                x-data="{
                    text: '',
                    shown: '',
                    done: false,
                    init() {
                        this.text = this.$refs.source.textContent.trim();
                        if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
                            this.shown = this.text;
                            this.done = true;
                            return;
                        }
                        let i = 0;
                        const tick = () => {
                            i += 1 + Math.floor(Math.random() * 3);
                            this.shown = this.text.slice(0, i);
                            if (i >= this.text.length) {
                                this.done = true;
                                return;
                            }
                            setTimeout(tick, 28);
                        };
                        tick();
                    },
                }"
            >
                {{-- The full text stays in the DOM for assistive tech; sighted
                     readers watch it arrive. --}}
                <span x-ref="source" class="sr-only">{{ $slot }}</span>
                <span aria-hidden="true" class="whitespace-pre-line" x-text="shown"></span><span x-show="!done" aria-hidden="true" class="ms-0.5 inline-block h-[1em] w-px translate-y-[0.15em] bg-current motion-safe:animate-[ui-caret-blink_1s_steps(2)_infinite]"></span>
            </div>
        @else
            <div class="{{ $bubbleClasses }}">
                {{ $slot }}
            </div>
        @endif
    </div>
</div>