Link Preview

# Brok UI: Link Preview (`link-preview`)

A rich Open Graph link preview card with thumbnail, favicon, domain, title and description, wrapped as a single anchor.

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

## Install

```bash
php artisan ui:add link-preview
```

## Usage

```blade
<div class="mx-auto w-full max-w-md space-y-3">
    <x-ui.link-preview
        href="https://ui.heygaia.io"
        domain="heygaia.io"
        title="Designing a token-first UI system"
        description="How semantic design tokens keep light, dark and RTL themes in sync without touching a single component."
    />
    <x-ui.link-preview
        href="https://laravel.com/docs"
        domain="laravel.com"
        title="Laravel — The PHP framework for web artisans"
        description="Documentation for the elegant, expressive framework that powers this registry."
    />
</div>
```

## Props

- `href` (string, default `#`)
- `title` (string, default `Designing a token-first UI system`)
- `description` (string, default `How semantic design tokens keep light, dark and RTL themes in sync without touching a single component.`)
- `image` (mixed|null, default `null`)
- `domain` (string, default `heygaia.io`)
- `favicon` (mixed|null, default `null`)

## Use when

- Use when self-contained content objects benefit from a recognizable card-like presentation with local actions or metadata.
- Showing a rich preview of an external link with its image, favicon, domain and description.
- Rendering Open Graph data already fetched server-side.

## Avoid when

- Do not use card widgets where a simpler list, table, or plain text block would make comparison faster.
- Previewing on hover; hover-card is the transient surface.
- Fetching metadata client-side; the card only renders what it is given.

## Anti-patterns

- Using cards for dense cross-item comparison

## Rules

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

@props([
    'href' => '#',
    'title' => 'Designing a token-first UI system',
    'description' => 'How semantic design tokens keep light, dark and RTL themes in sync without touching a single component.',
    'image' => null,
    'domain' => 'heygaia.io',
    'favicon' => null,
])

@php
    // Derive a display domain from the href when one isn't supplied.
    $domain = $domain ?: (parse_url((string) $href, PHP_URL_HOST) ?? '');
@endphp

{{--
    Link preview — a rich Open Graph card for a URL. The whole card is a single
    anchor (so the entire surface is the click target); it stacks on mobile and
    lays the thumbnail beside the text from `sm` up. Falls back to a globe glyph
    when no favicon is given and hides the media rail when no image is supplied.
--}}
<a
    href="{{ $href }}"
    data-slot="link-preview"
    rel="noopener noreferrer"
    {{ $attributes->merge(['class' => 'group flex flex-col overflow-hidden rounded-lg border border-border bg-card text-foreground shadow-sm transition-colors hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring sm:flex-row']) }}
>
    @if ($image)
        <div class="aspect-video w-full shrink-0 overflow-hidden bg-muted sm:aspect-square sm:w-32">
            <img src="{{ $image }}" alt="" loading="lazy" class="size-full object-cover transition-transform duration-300 group-hover:scale-105 motion-reduce:transform-none" />
        </div>
    @endif

    <div class="min-w-0 flex-1 p-4">
        <div class="flex items-center gap-2 text-xs text-muted-foreground">
            @if ($favicon)
                <img src="{{ $favicon }}" alt="" class="size-4 shrink-0 rounded-sm" loading="lazy" />
            @else
                <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0">
                    <circle cx="12" cy="12" r="9" />
                    <path d="M3 12h18M12 3a14 14 0 0 1 0 18 14 14 0 0 1 0-18Z" />
                </svg>
            @endif
            <span class="truncate">{{ $domain }}</span>
        </div>

        <h3 class="mt-2 line-clamp-2 text-sm font-semibold leading-snug group-hover:underline">{{ $title }}</h3>

        @if ($description)
            <p class="mt-1 line-clamp-2 text-xs text-muted-foreground">{{ $description }}</p>
        @endif
    </div>
</a>