Editor Media

# Brok UI: Editor Media (`editor-media`)

A semantic media element renderer for the editor — image, video, file, and embed types — with alignment, captions, placeholder states, and optional aspect-ratio constraint. Static; no JavaScript. Composed as <x-ui.editor.media>; <x-ui.editor-media> stays as the compatibility tag.

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

## Install

```bash
php artisan ui:add editor-media
```

## Usage

```blade
<div class="mx-auto grid max-w-2xl gap-6 p-6">
    <x-ui.editor.media type="image" caption="A captioned image element." />
    <x-ui.editor.media type="video" caption="A video placeholder." />
    <x-ui.editor.media type="file" caption="annual-report.pdf" />
    <x-ui.editor.media type="embed" src="https://example.com/embed/123" caption="An embedded resource." />
</div>
```

## Props

- `type` (string, default `image`) — Media kind rendered: image, video, file, or embed.
- `src` (mixed|null, default `null`) — Source URL for the image, video, file, or embed link.
- `alt` (string, default ``) — Accessible alt text for the image variant.
- `caption` (mixed|null, default `null`) — Optional caption text shown below the media and used to derive a file's displayed name.
- `align` (string, default `center`) — Alignment of the media block: left, center (default), or right.
- `ratio` (mixed, default `16 / 9`) — Aspect ratio applied to the image and video placeholder frames.

## Use when

- Use when users need rich structured authoring, annotation, or collaborative editing controls.
- Rendering an editable image, video, file, or embed block inside the editor's document body.

## Avoid when

- Do not use rich editor affordances for simple one-line or plain-text tasks.
- The media needs to actually play or be interactive, such as a real video player; this renders an editor placeholder, not a media player.

## Anti-patterns

- Rich editors for one-line or easily validated input

## Rules

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

@props([
    'type'    => 'image',   // 'image' | 'video' | 'file' | 'embed'
    'src'     => null,
    'alt'     => '',
    'caption' => null,
    'align'   => 'center',  // 'left' | 'center' | 'right'
    'ratio'   => 16 / 9,
])

{{--
    Editor Media: a semantic media element renderer.

    Renders inside the editor body as an editable block representation for the
    four supported media types:

      image  — <img> inside <x-ui.aspect-ratio>; a bg-muted placeholder when no
               $src is set.
      video  — <x-ui.aspect-ratio> with a muted poster area and a centered
               primary-coloured play-button overlay (no actual <video> element —
               this is an editor placeholder, not a media player).
      file   — a token-styled chip row: file icon, name, <x-ui.badge> extension,
               and a download icon button.
      embed  — a bordered bg-card frame with a globe icon, "Embedded content"
               label, and the $src shown as a muted link.

    An optional <figcaption> is rendered when $caption is set.

    Alignment is applied to the outer <figure> via logical margin utilities so
    it mirrors correctly under dir="rtl":
      left   → me-auto
      center → mx-auto
      right  → ms-auto
--}}

@php
    // Alignment wrapper classes (logical properties — RTL-safe).
    $alignClass = match ($align) {
        'left'  => 'me-auto',
        'right' => 'ms-auto',
        default => 'mx-auto',
    };

    // Derive a file extension from the caption or src for the badge.
    $filename  = $caption ?? ($src ? basename($src) : __('document.pdf'));
    $extension = strtoupper(pathinfo($filename, PATHINFO_EXTENSION) ?: 'FILE');

    // The download and embed links use $src as an href: link it only when its
    // scheme is http(s) or it is relative, never javascript: or data:.
    $scheme = preg_match('/^([a-z][a-z0-9+.-]*):/i', (string) preg_replace('/[\x00-\x20]/', '', (string) $src), $match) ? strtolower($match[1]) : null;
    $href = $src && ($scheme === null || in_array($scheme, ['http', 'https'], true)) ? $src : null;
@endphp

<figure
    data-slot="editor-media"
    data-type="{{ $type }}"
    {{ $attributes->merge(['class' => 'my-3 w-full max-w-prose ' . $alignClass]) }}
>
    @if ($type === 'image')

        @if ($src)
            {{-- Image with aspect-ratio constraint --}}
            <x-ui.aspect-ratio :ratio="$ratio" class="overflow-hidden rounded-lg border border-border bg-muted">
                <img
                    src="{{ $src }}"
                    alt="{{ $alt }}"
                    loading="lazy"
                    class="h-full w-full object-cover"
                />
            </x-ui.aspect-ratio>
        @else
            {{-- Placeholder: shown when no src is provided yet --}}
            <div class="flex flex-col items-center justify-center gap-2 rounded-lg border border-dashed border-border bg-muted py-12 text-muted-foreground">
                <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect width="18" height="18" x="3" y="3" rx="2" ry="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21"/></svg>
                <span class="text-sm">{{ __('Add an image') }}</span>
            </div>
        @endif

    @elseif ($type === 'video')

        {{-- Video placeholder with play button overlay --}}
        <x-ui.aspect-ratio :ratio="$ratio" class="overflow-hidden rounded-lg border border-border bg-muted">
            <div class="flex h-full w-full items-center justify-center">
                <button
                    type="button"
                    aria-label="{{ __('Play video') }}"
                    class="flex h-14 w-14 items-center justify-center rounded-full bg-primary text-primary-foreground shadow-lg transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring"
                >
                    <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor"><polygon points="5 3 19 12 5 21 5 3"/></svg>
                </button>
            </div>
        </x-ui.aspect-ratio>

    @elseif ($type === 'file')

        {{-- File chip row --}}
        <div class="flex items-center gap-3 rounded-md border border-border bg-card px-4 py-3">
            {{-- File icon --}}
            <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="shrink-0 text-muted-foreground"><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><polyline points="14 2 14 8 20 8"/></svg>

            {{-- Filename --}}
            <span class="min-w-0 flex-1 truncate text-sm text-foreground">{{ $filename }}</span>

            {{-- Extension badge --}}
            <x-ui.badge variant="secondary" size="sm">{{ $extension }}</x-ui.badge>

            {{-- Download button --}}
            @if ($href)
                <a
                    href="{{ $href }}"
                    download
                    aria-label="{{ __('Download :file', ['file' => $filename]) }}"
                    class="shrink-0 rounded p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring"
                >
                    <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>
                </a>
            @endif
        </div>

    @else

        {{-- Embed frame --}}
        <div class="flex flex-col gap-2 rounded-lg border border-border bg-card px-6 py-6">
            <div class="flex items-center gap-2 text-muted-foreground">
                <svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg>
                <span class="text-sm font-medium text-foreground">{{ __('Embedded content') }}</span>
            </div>
            @if ($href)
                <a
                    href="{{ $href }}"
                    target="_blank"
                    rel="noopener noreferrer"
                    class="truncate text-xs text-muted-foreground underline underline-offset-2 hover:text-foreground"
                >{{ $src }}</a>
            @elseif ($src)
                <span class="truncate text-xs text-muted-foreground">{{ $src }}</span>
            @else
                <span class="text-xs text-muted-foreground">{{ __('https://example.com') }}</span>
            @endif
        </div>

    @endif

    {{-- Optional caption --}}
    @if ($caption)
        <figcaption class="mt-2 text-center text-sm text-muted-foreground">{{ $caption }}</figcaption>
    @endif
</figure>