Alert

# Brok UI: Alert (`alert`)

A callout for short, important messages with semantic variants.

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

## Install

```bash
php artisan ui:add alert
```

## Usage

```blade
<x-ui.alert class="w-full max-w-md text-start">
    <x-ui.alert.title>{{ __('Heads up') }}</x-ui.alert.title>
    <x-ui.alert.description>{{ __('You can add components to your app using the CLI.') }}</x-ui.alert.description>
</x-ui.alert>
```

## Props

- `variant` (default|destructive|success|warning|info, default `default`) — Semantic tone: default, info, success, warning, or destructive.
- `icon` (bool, default `true`) — Leading icon: true shows the variant's glyph, the icon slot overrides it, false hides it.
- `dismissible` (bool, default `false`) — Adds a close button that hides the alert and dispatches alert:dismiss.
- `role` (string, default `alert`) — ARIA role: alert for assertive announcement, status for a polite outcome, region or none for a static callout.

## Use when

- Use for important messages that should stay visible long enough to read and act on.
- Surfacing a short, important message inline with the page, such as a form-level error or a success confirmation.
- Needing a semantic tone (default, info, success, warning, destructive) with a consistent icon and layout.

## Avoid when

- Do not downgrade important guidance into transient messaging users can miss.
- Needing a transient, auto-dismissing notification detached from the page flow; use toaster instead.
- Announcing a page-wide incident or maintenance notice; use system-banner instead.

## Anti-patterns

- Downgrading important outcomes to transient feedback

## Rules

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

@props([
    'variant' => 'default',
    // Leading icon: the variant's default glyph, an <svg> via the `icon` slot,
    // or false for none.
    'icon' => true,
    // Renders a close button; the alert hides itself and dispatches `alert:dismiss`.
    'dismissible' => false,
    // ARIA role: `alert` (assertive) for a problem that needs attention now,
    // `status` (polite) for an outcome banner such as "Saved", `region` or
    // `none` for a static callout that is not a live region.
    'role' => 'alert',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $alert = $styles['alert'];

    $classes = trim($alert['base'].' '.($alert['variants'][$variant] ?? $alert['variants']['default']));
    $tone = $alert['tones'][$variant] ?? $alert['tones']['default'];
    $showIcon = ! ($icon === false || $icon === 'false' || $icon === '0');
    // Optional named slot: buttons or links that act on the message. They sit
    // under the text, start-aligned with it, and wrap on a narrow alert.
    $hasActions = ($actions ?? null) instanceof \Illuminate\View\ComponentSlot && trim((string) $actions) !== '';
    $iconIsSlot = $icon instanceof \Illuminate\View\ComponentSlot && ! $icon->isEmpty();
    $glyphs = [
        'default' => '<circle cx="12" cy="12" r="10" /><path d="M12 16v-4M12 8h.01" />',
        'info' => '<circle cx="12" cy="12" r="10" /><path d="M12 16v-4M12 8h.01" />',
        'success' => '<circle cx="12" cy="12" r="10" /><path d="m9 12 2 2 4-4" />',
        'warning' => '<path d="m21.7 18-8-14a2 2 0 0 0-3.4 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.7-3" /><path d="M12 9v4M12 17h.01" />',
        'destructive' => '<circle cx="12" cy="12" r="10" /><path d="m15 9-6 6M9 9l6 6" />',
    ];
@endphp

<div
    data-slot="alert"
    data-variant="{{ $variant }}"
    @if ($role !== 'none' && $role !== false) role="{{ $role }}" @endif
    @if ($dismissible) x-data="{ open: true }" x-show="open" @endif
    {{ $attributes->merge(['class' => $classes]) }}
>
    @if ($showIcon)
        <span data-slot="alert-icon" class="mt-px shrink-0 {{ $tone }} [&>svg]:size-4" aria-hidden="true">
            @if ($iconIsSlot)
                {{ $icon }}
            @else
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">{!! $glyphs[$variant] ?? $glyphs['default'] !!}</svg>
            @endif
        </span>
    @endif
    <div class="min-w-0 flex-1">
        {{ $slot }}
        @if ($hasActions)
            <div data-slot="alert-actions" {{ $actions->attributes->merge(['class' => 'mt-3 flex flex-wrap items-center gap-2']) }}>
                {{ $actions }}
            </div>
        @endif
    </div>
    @if ($dismissible)
        <button
            type="button"
            data-slot="alert-dismiss"
            @click="open = false; $dispatch('alert:dismiss')"
            aria-label="{{ __('Dismiss') }}"
            class="-me-1 -mt-1 inline-flex size-7 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors hover:bg-foreground/5 hover:text-foreground focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring motion-reduce:transition-none"
        >
            <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12" /></svg>
        </button>
    @endif
</div>