Status

# Brok UI: Status (`status`)

A compact status dot with an optional label and ping/pulse motion. Presence (online, offline, busy, away, neutral) and system (active, fixing, down, idle) vocabularies share one dot.

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

## Install

```bash
php artisan ui:add status
```

## Usage

```blade
{{-- One presence dot; the playground's variant and size controls drive it. --}}
<x-ui.status variant="online" label="{{ __('Online') }}" :pulse="true" />
```

## Props

- `variant` (online|busy|away|offline|neutral, default `online`) — Presence (online, busy, away, offline, neutral) or system (active, fixing, down, idle) state; unknown values fall back to neutral.
- `label` (mixed|null, default `null`) — Visible label text; when omitted, the variant name is announced to screen readers only.
- `pulse` (mixed|null, default `null`) — Motion override: true or 'ping' echoes a ring outward, 'pulse' breathes the dot, false stays still; unset lets the variant decide (active pings, fixing pulses).
- `size` (md|sm|lg, default `md`) — Dot and text size: sm, md, or lg.
- `appearance` (string, default `dot`) — dot renders a plain dot and label; pill renders a soft tinted chip with the dot inside.

## Use when

- Use to show state, status, notification, or lightweight social feedback near the relevant object.
- Showing a presence or system state (online, busy, away, offline, active, fixing, down, idle) as a compact dot with an optional label.
- Wanting a pill appearance for a table cell or card header instead of a bare dot and label.

## Avoid when

- Do not overload small status elements with explanations that should remain visible in text.
- Announcing a one-off outcome message rather than an ongoing state; use alert or a toast instead.
- Needing a numeric count on a trigger corner; use notification-badge instead.

## Anti-patterns

- Using color or icon alone to communicate state

## Rules

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

@props([
    // Presence: online | busy | away | offline | neutral.
    // System:   active | fixing | down | idle.
    'variant' => 'online',
    'label'   => null,
    // Motion on the dot: true|'ping' echoes a ring outward, 'pulse' breathes
    // the dot itself, false is still. Unset, the variant decides — active
    // pings and fixing pulses; every other variant is still.
    'pulse'   => null,
    'size'    => 'md',
    // dot (default): a dot and a plain label. pill: a soft tinted chip with the
    // dot inside — for a table cell or a card header.
    'appearance' => 'dot',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $variant = array_key_exists($variant, $styles['status']['variants']) ? $variant : 'neutral';
    $size = in_array($size, ['sm', 'md', 'lg'], true) ? $size : 'md';
    $appearance = $appearance === 'pill' ? 'pill' : 'dot';
    $status = $styles['status'];
    $motion = match (true) {
        $pulse === null => $status['motion'][$variant] ?? false,
        $pulse === true || $pulse === 'ping' => 'ping',
        $pulse === 'pulse' => 'pulse',
        default => false,
    };
    // status-indicator renders this component under its own name; the
    // browser keeps only the first of two identical attributes, so read the
    // override out of the bag and print exactly one.
    $slotName = (string) ($attributes->get('data-slot') ?: 'status');

    $dotColour = $status['variants'][$variant];
    $sizeStyles = $status['sizes'][$size];
    $dotSize = $sizeStyles['dot'];
    // A hollow (offline) dot has no fill for the ping to echo; it pulses the ring colour.
    $pingColour = $variant === 'offline' ? 'bg-muted-foreground/60' : $dotColour;

    $rootClasses = $appearance === 'pill'
        ? 'inline-flex items-center gap-2 rounded-full font-medium '.$status['pills'][$variant].' '.$sizeStyles['pill']
        : $status['base'];
@endphp

<span
    data-slot="{{ $slotName }}"
    data-variant="{{ $variant }}"
    data-appearance="{{ $appearance }}"
    @if ($motion) data-motion="{{ $motion }}" @endif
    role="status"
    {{ $attributes->except('data-slot')->merge(['class' => $rootClasses]) }}
>
    {{-- Dot wrapper (relative so the ping layer can be absolute) --}}
    <span class="relative inline-flex shrink-0 {{ $dotSize }}">
        @if ($motion === 'ping')
            <span data-slot="status-dot-ping" aria-hidden="true" class="{{ $status['pingBase'] }} {{ $pingColour }}"></span>
        @endif
        <span data-slot="status-dot" aria-hidden="true" class="{{ $status['dotBase'] }} {{ $dotSize }} {{ $dotColour }} {{ $motion === 'pulse' ? $status['pulseDot'] : '' }}"></span>
    </span>

    @if ($label !== null)
        <span data-slot="status-label" class="{{ $appearance === 'pill' ? 'leading-none' : $status['labelBase'].' '.$sizeStyles['text'] }}">{{ $label }}</span>
    @else
        {{-- No visible label: give screen readers the variant name --}}
        <span class="sr-only">{{ ucfirst($variant) }}</span>
    @endif
</span>