Attention Banners

# Brok UI: Attention Banners (`admin-attention-banners`)

Why a screen needs a person, most severe first — one alert per cause with the action that owns the fix; renders nothing at all when the list is empty.

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

## Install

```bash
php artisan ui:add admin-attention-banners
```

## Usage

```blade
<div class="w-full">
    <x-ui.admin.attention-banners />
</div>
```

## Props

- `banners` (array|null, default `null`) — [['tone' => 'negative'|'attention'|'info'|'positive','title','body' => null,'actionLabel' => null,'actionHref' => null,'id' => null]]. `null` renders a sample set; `[]` renders nothing.
- `heading` (string|null, default `null`) — Accessible name of the region.

## Use when

- Use for important messages that should stay visible long enough to read and act on.
- A record or list has causes a person must act on, each with a screen that fixes it.
- A form was duplicated from another record and must say what was not copied.

## Avoid when

- Do not downgrade important guidance into transient messaging users can miss.
- A single inline field error — use `field`.
- Ambient system status — use `system-banner`.

## Anti-patterns

- Downgrading important outcomes to transient feedback

## Rules

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

{{--
    Attention Banners — why this screen needs a person, most severe first.

    One banner per cause. Each names what is wrong in the operator's words
    and offers the screen that owns the fix, so a banner is a route to the
    work rather than a report about it. A banner without a cause is
    decoration: the component renders nothing at all for a healthy record, and
    the caller never has to guard the include.

    Ordering is decided here, not by the caller: negative before attention
    before info, stable within a tone. A read model can emit its causes in
    whatever order it finds them and the screen still leads with the one
    that costs the most.

    Role gating is the caller's job. A banner whose conclusion is about
    margin is cost data even when it states no figure, so the page filters
    the list before passing it; this component renders what it is given and asks
    no questions about who is reading.

    Generalised from the Noord-C admin's `record/banners.blade.php` (five
    module copies) and the orders list's `operational-alerts.blade.php`.
--}}
@props([
    // null (absent) renders the sample set so the docs preview shows the
    // component; an explicit [] renders nothing, which is the promise above.
    'banners' => null,
    'heading' => null,
])

@php
    // Shapes documented in item.json knowledge.props:
    //   banners: [['tone' => 'negative'|'attention'|'info'|'positive', 'title', 'body' => null, 'actionLabel' => null, 'actionHref' => null, 'id' => null]]
    $banners ??= [
        [
            'tone' => 'attention',
            'title' => __('Payment sync delayed'),
            'body' => __('The payment provider has not confirmed a status for 6 orders in the last 15 minutes. Figures for those orders may be out of date.'),
            'actionLabel' => __('View affected orders'),
            'actionHref' => '#',
        ],
        [
            'tone' => 'negative',
            'title' => __('Stock claim failed'),
            'body' => __('Two lines on this order could not reserve stock. Fulfilment will stall until the warehouse resolves them.'),
            'actionLabel' => __('Open warehouse queue'),
            'actionHref' => '#',
        ],
        [
            'tone' => 'info',
            'title' => __('Duplicated from #1042'),
            'body' => __('Everything was copied except the customer credit, which belongs to the original order.'),
            'actionLabel' => __('Open #1042'),
            'actionHref' => '#',
        ],
    ];

    $severity = ['negative' => 0, 'attention' => 1, 'info' => 2, 'positive' => 3];
    $variants = ['negative' => 'destructive', 'attention' => 'warning', 'info' => 'info', 'positive' => 'success'];

    $banners = collect((array) $banners)
        ->filter(fn ($entry) => is_array($entry))
        ->sortBy(fn (array $banner): int => $severity[$banner['tone'] ?? 'info'] ?? 2, SORT_NUMERIC, false)
        ->values();

    $heading ??= __('Needs attention');
@endphp

@if ($banners->isNotEmpty())
    <section
        data-slot="attention-banners"
        data-surface="admin"
        aria-label="{{ $heading }}"
        {{ $attributes->merge(['class' => 'flex flex-col gap-2']) }}
    >
        @foreach ($banners as $banner)
            @php $tone = $banner['tone'] ?? 'info'; @endphp
            <x-ui.alert
                :variant="$variants[$tone] ?? 'info'"
                :data-tone="$tone"
                :id="$banner['id'] ?? null"
                class="flex flex-wrap items-start justify-between gap-x-6 gap-y-2"
            >
                <div class="min-w-0 flex-1 basis-64">
                    <x-ui.alert.title>{{ $banner['title'] ?? '' }}</x-ui.alert.title>
                    @if (! empty($banner['body']))
                        <x-ui.alert.description class="max-w-prose text-pretty">{{ $banner['body'] }}</x-ui.alert.description>
                    @endif
                </div>

                @if (! empty($banner['actionLabel']))
                    <x-ui.button variant="outline" size="sm" :href="$banner['actionHref'] ?? '#'" class="shrink-0">
                        {{ $banner['actionLabel'] }}
                    </x-ui.button>
                @endif
            </x-ui.alert>
        @endforeach
    </section>
@endif