Bento Grid

# Brok UI: Bento Grid (`bento`)

A responsive bento-box grid with span-controlled cells for showcasing features.

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

## Install

```bash
php artisan ui:add bento
```

## Usage

```blade
<x-ui.bento class="max-w-3xl">
    <x-ui.bento.item
        :colSpan="2"
        title="Lightning fast"
        description="Server-rendered Blade with zero runtime JavaScript for the layout."
    />
    <x-ui.bento.item
        :rowSpan="2"
        title="Composable"
        description="Drop cells in any order and let the grid flow around their spans."
    />
    <x-ui.bento.item
        title="Accessible"
        description="Semantic tokens and reduced-motion friendly out of the box."
    />
    <x-ui.bento.item
        title="Theme aware"
        description="Adapts to light and dark automatically."
    />
    <x-ui.bento.item
        :colSpan="2"
        title="Responsive"
        description="One column on mobile, two on tablet, full grid on desktop."
    />
</x-ui.bento>
```

## Props

- `cols` (int, default `3`) — Column count at the large breakpoint; smaller breakpoints fall back to a fixed 1/2 column ramp.
- `gap` (int, default `4`) — Gap between cells: 2, 3, 4, 6, or 8.
- `colSpan` (int, default `1`) — Declared by @props in the registry Blade source.
- `rowSpan` (int, default `1`) — Declared by @props in the registry Blade source.
- `title` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `description` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `icon` (mixed|null, default `null`) — Declared by @props in the registry Blade source.

## Use when

- Use to group related content into scannable units for browsing, prioritization, or rearrangement.
- Showcasing a set of features or highlights as an asymmetric grid of differently sized cells.
- Needing individual cells that can span multiple columns or rows to create visual emphasis.

## Avoid when

- Do not use card-like structures when dense row-by-row comparison would be clearer in a list or table.
- The grid should be uniform, with every cell the same size; use grid instead.
- The content is primarily data to scan or compare; use table or a plain card grid.

## Anti-patterns

- Turning every object into a card

## Rules

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

@props([
    'cols' => 3,
    'gap' => 4,
])

@php
    // The large-breakpoint column count is dynamic, so it is fed through a CSS
    // custom property + an arbitrary-value class to stay Tailwind-purge safe.
    // Small/medium breakpoints fall back to a fixed 1/2 column ramp.
    $gapClass = match ((int) $gap) {
        2 => 'gap-2',
        3 => 'gap-3',
        6 => 'gap-6',
        8 => 'gap-8',
        default => 'gap-4',
    };
@endphp

<div
    data-slot="bento"
    style="--bento-cols: {{ (int) $cols }};"
    {{ $attributes->merge(['class' => 'grid grid-cols-1 sm:grid-cols-2 lg:[grid-template-columns:repeat(var(--bento-cols),minmax(0,1fr))] '.$gapClass]) }}
>
    {{ $slot }}
</div>

@props([
    'colSpan' => 1,
    'rowSpan' => 1,
    'title' => null,
    'description' => null,
    'icon' => null,
])

@php
    // Spans are dynamic, so they go through inline grid-* styles rather than
    // dynamic class names (which Tailwind's JIT purge would strip).
    $hasHeader = filled($title) || filled($description) || $icon;
@endphp

<div
    data-slot="bento-item"
    style="grid-column: span {{ (int) $colSpan }}; grid-row: span {{ (int) $rowSpan }};"
    {{ $attributes->merge(['class' => 'group relative overflow-hidden rounded-lg border border-border bg-card p-6 transition-colors hover:bg-accent/50 motion-reduce:transition-none']) }}
>
    @if ($icon)
        <div data-slot="bento-item-icon" class="mb-4 text-primary">
            {{ $icon }}
        </div>
    @endif

    @if (filled($title))
        <h3 class="font-semibold text-foreground">{{ $title }}</h3>
    @endif

    @if (filled($description))
        <p class="text-sm text-muted-foreground @if (filled($title)) mt-1 @endif">{{ $description }}</p>
    @endif

    @if ($hasHeader && trim($slot) !== '')
        <div class="mt-4">{{ $slot }}</div>
    @else
        {{ $slot }}
    @endif
</div>