Media Masking

# Brok UI: Image Mask (`image-mask`)

An image clipped to a decorative shape (circle, hexagon, diamond, star, arch, blob) via CSS clip-path — colour-free and fully responsive.

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

## Install

```bash
php artisan ui:add image-mask
```

## Usage

```blade
<div class="w-full flex flex-wrap items-center justify-center gap-6">
    <x-ui.image-mask src="https://picsum.photos/seed/mask-a/400/400" alt="Masked sample" shape="blob" class="w-32" />
    <x-ui.image-mask src="https://picsum.photos/seed/mask-b/400/400" alt="Masked sample" shape="hexagon" class="w-32" />
    <x-ui.image-mask src="https://picsum.photos/seed/mask-c/400/400" alt="Masked sample" shape="arch" aspect="3 / 4" class="w-28" />
    <x-ui.image-mask src="https://picsum.photos/seed/mask-d/400/400" alt="Masked sample" shape="star" class="w-32" />
</div>
```

## Props

- `src` (string, default ``) — Image URL.
- `alt` (string, default ``) — Accessible alt text for the image.
- `shape` (string, default `circle`) — Clip-path shape: circle, hexagon, diamond, star, arch, or blob.
- `aspect` (string, default `1 / 1`) — CSS aspect-ratio the image is cropped to before the shape mask is applied.

## Use when

- Use when image or video selection, preview, or media-based comparison is part of the task.
- Giving a photo a decorative non-rectangular silhouette, such as a hexagon or blob, for marketing or editorial imagery.
- Needing the shape to stay colour-free and scale responsively instead of relying on an exported PNG mask.

## Avoid when

- Do not require media-heavy interaction when a simpler text or list solution would be faster.
- The image is functional (an avatar, a data thumbnail) where a plain rectangle or circle utility is clearer and lighter weight.
- The masked media is video rather than a still image; use video-mask.

## Anti-patterns

- Requiring media-heavy interaction when text is faster

## Rules

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

@props([
    'src' => '',
    'alt' => '',
    'shape' => 'circle',
    'aspect' => '1 / 1',
])

@php
    // Image Mask — clips an <img> to a decorative shape with CSS `clip-path`.
    // Every shape is expressed in percentages so it scales with the box (set via
    // `aspect`), and uses no colour at all, so it never trips the raw-colour
    // guard. Pair with `video-mask` (shared shape vocabulary) for the same effect
    // on video. Pick a shape from the whitelist; anything else falls back to a
    // circle so the clip-path is always valid.
    $shapes = [
        'circle' => 'circle(50%)',
        'hexagon' => 'polygon(25% 0%, 75% 0%, 100% 50%, 75% 100%, 25% 100%, 0% 50%)',
        'diamond' => 'polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)',
        'star' => 'polygon(50% 0%, 61% 35%, 98% 35%, 68% 57%, 79% 91%, 50% 70%, 21% 91%, 32% 57%, 2% 35%, 39% 35%)',
        'arch' => 'inset(0 round 999px 999px 0 0)',
        'blob' => 'polygon(40% 4%, 66% 9%, 89% 26%, 96% 51%, 88% 76%, 64% 93%, 38% 96%, 16% 79%, 6% 53%, 13% 27%)',
    ];
    $shape = array_key_exists($shape, $shapes) ? $shape : 'circle';
    $clip = $shapes[$shape];
@endphp

<figure
    data-slot="image-mask"
    data-shape="{{ $shape }}"
    style="aspect-ratio: {{ $aspect }};"
    {{ $attributes->merge(['class' => 'relative block overflow-hidden bg-muted']) }}
>
    <img
        src="{{ $src }}"
        alt="{{ $alt }}"
        loading="lazy"
        decoding="async"
        class="h-full w-full object-cover"
        style="clip-path: {{ $clip }};"
    />
</figure>