Badge

# Brok UI: Badge (`badge`)

Compact status label with semantic variants, sizes, and a read-model `tone` (positive/attention/negative/info/neutral) that resolves to the soft recipe in one place.

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

## Install

```bash
php artisan ui:add badge
```

## Usage

```blade
<x-ui.badge>{{ __('Badge') }}</x-ui.badge>
```

## Props

- `variant` (default|secondary|destructive|success|warning|info|outline|ghost, default `default`) — Visual recipe: default, secondary, destructive, success, warning, info, outline, ghost, or a soft-* tone recipe.
- `size` (md|sm|lg, default `md`) — Badge height and padding: sm, md, or lg.
- `as` (string, default `span`) — Tag rendered: span, button, or a; any other value falls back to span.
- `tone` (mixed|null, default `null`) — Semantic state (success, warning, destructive, info, neutral) that resolves to the matching soft variant, overriding variant when set.
- `dot` (bool, default `false`) — Adds a leading status dot: true uses the badge's text color, or pass a tone name for a colored dot on a neutral badge.
- `leading` (mixed|null, default `null`) — Medallion, such as an icon or avatar, rendered at the start edge and sized to the badge.
- `items` (array, default `[]`) — Declared by @props in the registry Blade source.
- `max` (int, default `3`) — Declared by @props in the registry Blade source.

## Use when

- Use for compact labels, counts, and concise metadata that support scanning.
- Labeling a status, count, category, or trend inline next to other content.
- Marking a semantic state with the tone prop so the same word always resolves to the same color across the app.

## Avoid when

- Do not force badges or short labels to carry complex explanations that need sentence-level context.
- The label is the trigger for a primary action; use button instead of as="button".

## Anti-patterns

- Encoding complex meaning in a badge alone

## Rules

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

{{--
    Badge.

    `as` lets the badge be the thing you press without growing a second
    component that has to be kept the same shape by hand. A count you can open
    is still a badge; it just needs to be a button to be reachable by keyboard
    and announced as one.

    `tone` is the semantic entry point a read model uses: it sends
    positive/attention/negative/info/neutral and never a CSS class or a
    variant name, so the palette lives in one place and a status pill, a
    sidebar count and a KPI delta all resolve the same word to the same
    colour. A tone always maps to the soft recipe (tinted ground, readable
    text); pass `variant` instead when a solid fill is wanted. When both are
    given, `tone` wins, because it is the more specific statement.
--}}
{{--
    `dot`: a leading status dot — true takes the badge's text colour, or a tone
    (success | warning | destructive | info | neutral) for a coloured dot on a
    neutral badge. `leading` slot: a medallion (an avatar, an icon) hugging the
    start edge, sized to the badge whatever size the child asked for.
--}}
@props([
    'variant' => 'default',
    'size' => 'md',
    'as' => 'span',
    'tone' => null,
    'dot' => false,
    'leading' => null,
])

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

    if ($tone !== null) {
        $variant = $badge['tones'][$tone] ?? $badge['tones']['neutral'];
    }

    // Anything else would let a caller inject an arbitrary tag name.
    $tag = in_array($as, ['span', 'button', 'a'], true) ? $as : 'span';

    $dotClass = match (true) {
        $dot === false || $dot === null || $dot === 'false' => null,
        in_array($dot, ['success', 'warning', 'destructive', 'info'], true) => 'bg-'.$dot,
        $dot === 'neutral' => 'bg-muted-foreground',
        default => 'bg-current',
    };
    $hasLeading = $leading !== null && ! $leading->isEmpty();

    $classes = trim(
        $badge['base']
        .' '.($badge['variants'][$variant] ?? $badge['variants']['default'])
        .' '.($badge['sizes'][$size] ?? $badge['sizes']['md'])
        .($tag === 'span' ? '' : ' cursor-pointer transition-colors')
    );
@endphp

<{{ $tag }}
    data-slot="badge"
    data-variant="{{ $variant }}"
    @if ($tone !== null) data-tone="{{ $tone }}" @endif
    data-size="{{ $size }}"
    @if ($tag === 'button') type="button" @endif
    {{ $attributes->merge(['class' => $classes]) }}
>
    @if ($hasLeading)
        <span data-slot="badge-leading" class="-ms-1 inline-flex shrink-0 items-center [&>*]:!size-4 [&>*]:!text-2xs" aria-hidden="true">{{ $leading }}</span>
    @endif
    @if ($dotClass)
        <span data-slot="badge-dot" class="size-2 shrink-0 rounded-full {{ $dotClass }}" aria-hidden="true"></span>
    @endif
    {{-- Icons and controls inside the label render inline: the preflight makes
         svg a block element, which would break a badge onto two lines; a bare
         span (a hand-made dot) gets its box back the same way. --}}
    <span data-slot="badge-label" class="min-w-0 truncate [&_svg]:inline-block [&_svg]:shrink-0 [&_svg]:align-[-0.125em] [&>span]:inline-block [&>span]:align-[-0.125em] [&_button]:align-middle">{{ $slot }}</span>
</{{ $tag }}>

@props([
    // The labels to show; anything past `max` folds into a "+N" badge.
    'items' => [],
    'max' => 3,
    'variant' => 'secondary',
    'size' => 'md',
    // Optional tone for every item badge (a read model's positive/attention/…).
    'tone' => null,
])

@php
    // Accept a string, a backed enum or a Stringable for `variant`.
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $items = array_values(array_filter((array) $items, static fn ($item) => is_scalar($item) && (string) $item !== ''));
    $max = max(0, (int) $max);
    $visible = array_slice($items, 0, $max);
    $overflow = count($items) - count($visible);
    $hidden = array_slice($items, $max);
@endphp

{{-- A row of badges that folds the rest into "+N" — the "+N" carries the
     hidden labels in its title and an sr-only list, so nothing is lost. --}}
<span
    data-slot="badge-group"
    {{ $attributes->merge(['class' => 'inline-flex flex-wrap items-center gap-2']) }}
>
    @foreach ($visible as $item)
        <x-ui.badge :variant="$variant" :size="$size" :tone="$tone">{{ $item }}</x-ui.badge>
    @endforeach

    @if ($overflow > 0)
        <x-ui.badge data-slot="badge-group-more" variant="outline" :size="$size" :title="implode(', ', $hidden)" class="tabular-nums">
            <span aria-hidden="true">+{{ $overflow }}</span>
            <span class="sr-only">{{ trans_choice(':count more: :items|:count more: :items', $overflow, ['count' => $overflow, 'items' => implode(', ', $hidden)]) }}</span>
        </x-ui.badge>
    @endif

    @if ($items === [])
        {{ $slot }}
    @endif
</span>