Avatar

# Brok UI: Avatar (`avatar`)

User avatar with image and fallback rendering, size and shape variants.

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

## Install

```bash
php artisan ui:add avatar
```

## Usage

```blade
<div class="flex items-center gap-3">
    <x-ui.avatar size="sm" fallback="JD" alt="{{ __('Jane Doe') }}" />
    <x-ui.avatar fallback="AB" alt="{{ __('Alex Brown') }}" />
    <x-ui.avatar size="lg" fallback="CD" alt="{{ __('Casey Doyle') }}" />
</div>
```

## Props

- `src` (mixed|null, default `null`) — Image URL; when omitted the fallback content renders instead.
- `alt` (string, default ``) — Accessible name for the image; an empty string marks the avatar as decorative.
- `size` (md|xs|sm|lg|xl, default `md`) — Square size token from xs to xl.
- `shape` (string, default `null`) — Outline shape: circle, rounded, square, or tile (size-scaled rounded square). When omitted it follows kind (company: tile) and otherwise circle.
- `fallback` (mixed|null, default `null`) — Content shown when src is empty, typically initials.
- `name` (string|null, default `null`) — Opt-in name mode: derives 1-2 initials (first and last word, Unicode-aware, mb_ functions) and a tint the name always hashes to; labels the avatar with the name unless alt or decorative says otherwise; a src that fails to load shows the initials.
- `kind` (person|company|null, default `null`) — Default outline: person is a circle, company a rounded square (shape tile, radius scaled to the size). An explicit shape wins.
- `tone` (auto|neutral, default `auto`) — auto tints a named avatar with one of five chart-hue pairs (bg-chart-N/20 text-foreground); neutral keeps bg-muted. Without name the avatar is always neutral.
- `decorative` (bool, default `false`) — Hides the avatar from assistive tech (aria-hidden) even when alt or name is set; use it when a visible name sits next to the avatar.

## Use when

- Use to visually represent people or entities in collaborative or social contexts.
- Representing a single person or entity with a photo, falling back to initials or an icon when no image is available.
- Sizing and shaping a face consistently across lists, headers, and cards.

## Avoid when

- Do not rely on avatars alone when names or roles are needed for disambiguation.
- Showing several people at once; use avatar-group so the faces overlap and collapse into a count.

## Anti-patterns

- Relying on an avatar alone for identity

## Rules

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

@props([
    'src' => null,
    'alt' => '',
    'size' => 'md',
    'shape' => null,
    'fallback' => null,
    'name' => null,
    'kind' => null,
    'tone' => 'auto',
    'decorative' => false,
])

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

    $sizes = [
        'xs' => 'size-6 text-[0.625rem]',
        'sm' => 'size-8 text-xs',
        'md' => 'size-10 text-sm',
        'lg' => 'size-12 text-base',
        'xl' => 'size-16 text-lg',
    ];
    $size = isset($sizes[$size]) ? $size : 'md';

    // `kind` picks the default outline: a person is a circle, a company a
    // rounded square (`tile`). An explicit `shape` always wins.
    $kind = in_array($kind, ['person', 'company'], true) ? $kind : null;
    $shape = $shape ?? ($kind === 'company' ? 'tile' : 'circle');

    $shapes = [
        'circle' => 'rounded-full',
        'rounded' => 'rounded-lg',
        'square' => 'rounded-none',
        'tile' => $styles['avatar']['tileRadius'][$size],
    ];

    // Name mode: initials (first and last word, 1-2 letters) and a tint the
    // name always hashes to. Without a name the avatar renders as before.
    $name = filled($name) ? trim((string) $name) : null;
    $monogram = null;
    $toneIndex = null;
    $toneClass = 'bg-muted text-muted-foreground';

    if ($name !== null) {
        $letters = [];
        foreach (preg_split('/\s+/u', $name, -1, PREG_SPLIT_NO_EMPTY) ?: [] as $word) {
            if (preg_match('/[\p{L}\p{N}]/u', $word, $match) === 1) {
                $letters[] = $match[0];
            }
        }
        $picked = count($letters) > 1 ? [$letters[0], $letters[count($letters) - 1]] : $letters;
        $monogram = mb_strtoupper(implode('', $picked));

        if ($tone !== 'neutral') {
            $palette = $styles['avatar']['tones'];
            $toneIndex = crc32(mb_strtolower($name)) % count($palette);
            $toneClass = $palette[$toneIndex];
        }
    }

    $imageFallbackClass = '';
    if ($name !== null) {
        $imageFallbackClass = $styles['avatar']['imageFallbackBase'].' '
            .($toneIndex === null ? $styles['avatar']['imageFallbackNeutral'] : $styles['avatar']['imageFallback'][$toneIndex]);
    }

    $classes = trim('relative inline-flex shrink-0 items-center justify-center overflow-hidden '
        .$toneClass.' '
        .($shapes[$shape] ?? $shapes['circle']).' '
        .$sizes[$size]);

    $label = $decorative ? '' : ($alt !== '' ? (string) $alt : (string) $name);
    $content = $fallback ?? ($slot->isEmpty() ? $monogram : $slot);
    $imageFallback = is_string($fallback) && $fallback !== '' ? $fallback : (string) $monogram;
@endphp

@if ($name === null)
<span
    data-slot="avatar"
    data-size="{{ $size }}"
    data-shape="{{ $shape }}"
    @if ($kind) data-kind="{{ $kind }}" @endif
    @if ($decorative) aria-hidden="true" @endif
    {{ $attributes->merge(['class' => $classes]) }}
>
    @if ($src)
        <img src="{{ $src }}" alt="{{ $decorative ? '' : $alt }}" class="size-full object-cover" />
    @else
        <span class="font-medium" aria-hidden="{{ $alt === '' || $decorative ? 'true' : 'false' }}">{{ $fallback ?? $slot }}</span>
        @if ($alt !== '' && ! $decorative)
            <span class="sr-only">{{ $alt }}</span>
        @endif
    @endif
</span>
@else
{{-- Name mode: the root carries the accessible name (role="img") or is hidden
     when decorative. A broken image paints its pseudo-elements in Chromium
     and Firefox: ::before covers the broken-image glyph, ::after shows the
     tinted initials, so a failed
     load never shows a broken-image icon and needs no JavaScript. --}}
<span
    data-slot="avatar"
    data-size="{{ $size }}"
    data-shape="{{ $shape }}"
    @if ($kind) data-kind="{{ $kind }}" @endif
    data-tone="{{ $toneIndex === null ? 'neutral' : 'tint-'.($toneIndex + 1) }}"
    @if ($label !== '') role="img" aria-label="{{ $label }}" @else aria-hidden="true" @endif
    {{ $attributes->merge(['class' => $classes]) }}
>
    @if ($src)
        <img
            data-slot="avatar-image"
            src="{{ $src }}"
            alt=""
            data-fallback="{{ $imageFallback }}"
            class="absolute inset-0 size-full object-cover {{ $imageFallbackClass }}"
        />
    @else
        <span data-slot="avatar-fallback" class="font-medium" aria-hidden="true">{{ $content }}</span>
    @endif
</span>
@endif