Grid

# Brok UI: Grid (`grid`)

A mobile-first grid primitive with fixed column and gap presets plus min-width-zero child defaults.

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

## Install

```bash
php artisan ui:add grid
```

## Usage

```blade
<x-ui.grid cols="3" gap="6" class="w-full">
    @foreach (['Alpha', 'Beta', 'Gamma'] as $label)
        <x-ui.card><x-ui.card.content class="pt-card">{{ __($label) }}</x-ui.card.content></x-ui.card>
    @endforeach
</x-ui.grid>
```

## Props

- `cols` (string, default `3`) — Column preset: 1, 2, 3, 4, 6, 12 (mobile-first breakpoints), or auto-sm/auto-md/auto-lg for an auto-fit grid.
- `gap` (string, default `6`) — Gap between cells, from the fixed step vocabulary (0-16, or sm/md/lg tokens).
- `as` (string, default `div`) — HTML tag to render: div, section, main, ul, or ol.

## Use when

- Use to structure hierarchy, spacing, and responsiveness so content is easier to scan and navigate.
- Laying out cards, tiles, or media in a responsive multi-column grid that adapts from one column on mobile up to the chosen count.
- Needing an auto-fit grid whose column count grows with available width instead of a fixed breakpoint count (auto-sm/auto-md/auto-lg).

## Avoid when

- Do not let layout primitives substitute for semantics, headings, or interaction rules users still need.
- The layout is a single row or column of items; use stack or cluster instead.
- The grid needs custom, non-uniform column spans; compose Tailwind's grid utilities directly.

## Anti-patterns

- Using visual layout as a substitute for semantic structure

## Rules

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

@props([
    'cols' => '3',
    'gap' => '6',
    'as' => 'div',
])

@php
    $allowedTags = ['div', 'section', 'main', 'ul', 'ol'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'div';
    $columns = [
        '1' => 'grid-cols-1',
        '2' => 'grid-cols-1 sm:grid-cols-2',
        '3' => 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
        '4' => 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
        '6' => 'grid-cols-2 sm:grid-cols-3 lg:grid-cols-6',
        '12' => 'grid-cols-4 sm:grid-cols-6 lg:grid-cols-12',
        'auto-sm' => 'grid-cols-[repeat(auto-fit,minmax(min(100%,var(--grid-min-sm)),1fr))]',
        'auto-md' => 'grid-cols-[repeat(auto-fit,minmax(min(100%,var(--grid-min-md)),1fr))]',
        'auto-lg' => 'grid-cols-[repeat(auto-fit,minmax(min(100%,var(--grid-min-lg)),1fr))]',
    ];
    $gaps = [
        '0' => 'gap-0', '1' => 'gap-1', '2' => 'gap-2', '3' => 'gap-3',
        '4' => 'gap-4', '6' => 'gap-6', '8' => 'gap-8', '12' => 'gap-12',
        '16' => 'gap-16', 'sm' => 'gap-stack-sm', 'md' => 'gap-stack-md',
        'lg' => 'gap-stack-lg',
    ];
    $colsKey = array_key_exists((string) $cols, $columns) ? (string) $cols : '3';
    $gapKey = array_key_exists((string) $gap, $gaps) ? (string) $gap : '6';
@endphp

<{{ $tag }}
    data-slot="grid"
    data-cols="{{ $colsKey }}"
    data-gap="{{ $gapKey }}"
    {{ $attributes->merge(['class' => 'grid min-w-0 max-w-full '.$columns[$colsKey].' '.$gaps[$gapKey].' [&>*]:min-w-0']) }}
>{{ $slot }}</{{ $tag }}>