User Identity

# Brok UI: User Identity (`user-identity`)

A consistent user identity row with avatar fallback, display name, secondary identifier, and optional role and presence status in compact or full form.

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

## Install

```bash
php artisan ui:add user-identity
```

## Usage

```blade
<x-ui.user-identity name="Avery Stone" secondary="[email protected]" role="Owner" status="online" />
```

## Props

- `name` (string, default `required`) — Visible display name.
- `secondary` (string|null, default `null`) — Email, handle, or another secondary identifier.
- `src` (url|null, default `null`) — Validated image URL.
- `fallback` (string|null, default `null`) — Explicit avatar fallback; initials are derived when absent.
- `role` (string|null, default `null`) — Optional role label.
- `status` (online|offline|busy|away|neutral|null, default `null`) — Optional visible presence state.
- `mode` (compact|full|card, default `full`) — compact: avatar and name on one line; full: name, role and a secondary line; card: a bordered card with a large avatar, the status in words and an actions slot.
- `href` (url|null, default `null`) — Optional profile link.

## Use when

- Use to summarize, sequence, or present data so users can scan it quickly.
- Show the same user identity contract in tables, lists, audit feeds, and menus.

## Avoid when

- Do not add display-only ornament when the user needs actionable structure or exact comparison instead.
- Use avatar when only an image or initials are needed.

## Anti-patterns

- Adding display ornament without informational value

## Rules

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

@props([
    'name',
    'secondary' => null,
    'src' => null,
    'fallback' => null,
    'role' => null,
    // online | busy | away | offline | neutral — drawn as a dot on the avatar's
    // edge (named for assistive tech), never as a second text tag in the row.
    'status' => null,
    // compact: avatar sm + name on one line. full: avatar md, name + role, a
    // secondary line. card: a bordered card with avatar lg and room for actions.
    'mode' => 'full',
    'href' => null,
])

@php
    $mode = in_array($mode, ['compact', 'full', 'card'], true) ? $mode : 'full';
    $tag = filled($href) ? 'a' : ($mode === 'card' ? 'div' : 'span');
    $status = in_array($status, ['online', 'busy', 'away', 'offline', 'neutral'], true) ? $status : null;
    $initials = $fallback ?? collect(preg_split('/\s+/', trim((string) $name)) ?: [])
        ->filter()
        ->take(2)
        ->map(fn ($part) => mb_strtoupper(mb_substr($part, 0, 1)))
        ->implode('');
    $avatarSize = ['compact' => 'sm', 'full' => 'md', 'card' => 'lg'][$mode];
    // The presence dot sits on the avatar's bottom-end edge, ringed by the surface.
    $dotSize = ['compact' => 'size-2', 'full' => 'size-3', 'card' => 'size-3'][$mode];
    $dotColour = [
        'online' => 'bg-success',
        'busy' => 'bg-destructive',
        'away' => 'bg-warning',
        'offline' => 'border-2 border-muted-foreground/60 bg-background',
        'neutral' => 'bg-muted-foreground/60',
    ];
    $statusLabels = ['online' => __('Online'), 'busy' => __('Busy'), 'away' => __('Away'), 'offline' => __('Offline'), 'neutral' => __('Unknown')];
    $rootClasses = match ($mode) {
        'card' => 'flex min-w-0 items-center gap-4 rounded-lg border border-border bg-card p-6 text-start text-card-foreground',
        default => 'inline-flex min-w-0 items-center gap-3 text-start text-foreground',
    };
    if ($tag === 'a') {
        $rootClasses .= ' rounded-md transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring focus-visible:ring-offset-[length:var(--ring-offset-width)] focus-visible:ring-offset-background motion-reduce:transition-none';
        $rootClasses .= $mode === 'card' ? ' hover:bg-muted/40' : '';
    }
@endphp

<{{ $tag }}
    data-slot="user-identity"
    data-mode="{{ $mode }}"
    @if ($status) data-status="{{ $status }}" @endif
    @if ($tag === 'a') href="{{ $href }}" @endif
    {{ $attributes->merge(['class' => $rootClasses]) }}
>
    <span class="relative inline-flex shrink-0">
        <x-ui.avatar :src="$src" :alt="$src ? (string) $name : ''" :fallback="$initials" :size="$avatarSize" />
        @if ($status)
            <span data-slot="user-identity-status" class="absolute bottom-0 end-0 rounded-full ring-2 ring-background {{ $dotSize }} {{ $dotColour[$status] }}" title="{{ $statusLabels[$status] }}" aria-hidden="true"></span>
            <span class="sr-only">{{ $statusLabels[$status] }}</span>
        @endif
    </span>

    <span class="min-w-0 flex-1">
        <span class="flex min-w-0 items-center gap-2">
            <span class="truncate {{ $mode === 'card' ? 'text-base font-semibold' : 'text-sm font-medium' }}">{{ $name }}</span>
            @if (filled($role))
                <x-ui.badge variant="outline" size="sm" class="shrink-0">{{ $role }}</x-ui.badge>
            @endif
        </span>
        @if ($mode !== 'compact' && filled($secondary))
            <span class="block truncate text-sm text-muted-foreground">{{ $secondary }}</span>
        @endif
        @if ($mode === 'card' && $status)
            <span class="mt-1 block text-xs text-muted-foreground">{{ $statusLabels[$status] }}</span>
        @endif
    </span>

    @isset($actions)
        <span class="flex shrink-0 items-center gap-2">{{ $actions }}</span>
    @endisset
</{{ $tag }}>