Bleed

# Brok UI: Bleed (`bleed`)

A controlled full-bleed primitive for tables, code, and media, with an optional contained horizontal scroll mode.

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

## Install

```bash
php artisan ui:add bleed
```

## Usage

```blade
<x-ui.surface class="w-full max-w-md">
    <x-ui.bleed scroll>
        <div class="min-w-2xl rounded-md bg-muted p-4 text-sm text-muted-foreground">
            {{ __('Wide content scrolls inside the bleed region without widening the page.') }}
        </div>
    </x-ui.bleed>
</x-ui.surface>
```

## Props

- `size` (6|4|8|sm|md|lg, default `6`) — Negative margin and matching inner padding step: 4, 6, 8, or the gutter tokens sm/md/lg.
- `scroll` (bool, default `false`) — When true, the bled region becomes a horizontally scrollable, keyboard-focusable strip instead of overflowing visually.
- `as` (string, default `div`) — HTML tag to render: div, section, main, or aside.

## Use when

- Use to structure hierarchy, spacing, and responsiveness so content is easier to scan and navigate.
- Letting a table, code block, or media item extend to the container's outer edge inside an otherwise padded parent.
- Needing a scrollable full-width strip (with scroll) that still respects the surrounding gutter's padding.

## Avoid when

- Do not let layout primitives substitute for semantics, headings, or interaction rules users still need.
- The content already fits inside the parent's padding; a bleed adds negative margin with no visual benefit.
- Building a general horizontal-scroll container unrelated to a parent's gutter; compose overflow-x-auto directly.

## Anti-patterns

- Using visual layout as a substitute for semantic structure

## Rules

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

@props([
    'size' => '6',
    'scroll' => false,
    'as' => 'div',
])

@php
    $allowedTags = ['div', 'section', 'main', 'aside'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'div';
    $sizes = [
        '4' => '-mx-4 px-4',
        '6' => '-mx-6 px-6',
        '8' => '-mx-8 px-8',
        'sm' => '-mx-gutter-sm px-gutter-sm',
        'md' => '-mx-gutter-md px-gutter-md',
        'lg' => '-mx-gutter-lg px-gutter-lg',
    ];
    $sizeKey = array_key_exists((string) $size, $sizes) ? (string) $size : '6';
@endphp

<{{ $tag }}
    data-slot="bleed"
    data-size="{{ $sizeKey }}"
    data-scroll="{{ $scroll ? 'true' : 'false' }}"
    @if ($scroll && ! $attributes->has('tabindex')) tabindex="0" @endif
    {{ $attributes->merge(['class' => trim('min-w-0 max-w-full '.$sizes[$sizeKey].' '.($scroll ? 'overflow-x-auto overscroll-x-contain' : ''))]) }}
>{{ $slot }}</{{ $tag }}>