Cluster

# Brok UI: Cluster (`cluster`)

An overflow-safe inline layout primitive for wrapping actions, tags, filters, and metadata with an approved gap vocabulary.

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

## Install

```bash
php artisan ui:add cluster
```

## Usage

```blade
{{-- A cluster is a wrapping row with an approved gap: tags, filters, actions
     and metadata that must wrap safely at any width. Narrow the frame and the
     items flow onto new lines instead of overflowing. --}}
<div class="w-full max-w-md space-y-6">
    <x-ui.cluster gap="2">
        @foreach (['Design', 'Engineering', 'Marketing', 'Research', 'Operations', 'Support', 'Finance', 'Legal'] as $team)
            <x-ui.badge variant="secondary">{{ $team }}</x-ui.badge>
        @endforeach
    </x-ui.cluster>

    {{-- justify="between" pushes the two ends apart while each end still wraps. --}}
    <x-ui.cluster gap="3" justify="between">
        <x-ui.cluster gap="2">
            <x-ui.badge variant="soft-success">{{ __('Published') }}</x-ui.badge>
            <span class="text-sm text-muted-foreground">{{ __('Updated 2 hours ago') }}</span>
        </x-ui.cluster>
        <x-ui.cluster gap="2">
            <x-ui.button variant="outline" size="sm">{{ __('Preview') }}</x-ui.button>
            <x-ui.button size="sm">{{ __('Save') }}</x-ui.button>
        </x-ui.cluster>
    </x-ui.cluster>
</div>
```

## Props

- `gap` (string, default `3`) — Gap between items, from the fixed step vocabulary (0-16, or sm/md/lg tokens).
- `align` (string, default `center`) — Cross-axis alignment: start, center, end, baseline, or stretch.
- `justify` (string, default `start`) — Main-axis distribution: start, center, end, between, around, or evenly.
- `wrap` (bool, default `true`) — Whether items wrap onto new lines when they run out of horizontal space.
- `as` (string, default `div`) — HTML tag to render: div, section, nav, header, footer, ul, or ol.

## Use when

- Use to structure hierarchy, spacing, and responsiveness so content is easier to scan and navigate.
- Laying out an inline group of tags, filter chips, buttons, or metadata that should wrap onto new lines as space runs out.
- Needing a fixed gap vocabulary and overflow-safe children (min-width: 0) without hand-writing flex-wrap utilities.

## Avoid when

- Do not let layout primitives substitute for semantics, headings, or interaction rules users still need.
- Building a strict one-dimensional row or column with no wrapping; use stack instead.
- Laying out a two-dimensional grid of cards or tiles; use grid.

## Anti-patterns

- Using visual layout as a substitute for semantic structure

## Rules

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

@props([
    'gap' => '3',
    'align' => 'center',
    'justify' => 'start',
    'wrap' => true,
    'as' => 'div',
])

@php
    $allowedTags = ['div', 'section', 'nav', 'header', 'footer', 'ul', 'ol'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'div';
    $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',
    ];
    $alignments = [
        'start' => 'items-start', 'center' => 'items-center',
        'end' => 'items-end', 'baseline' => 'items-baseline',
        'stretch' => 'items-stretch',
    ];
    $justifications = [
        'start' => 'justify-start', 'center' => 'justify-center',
        'end' => 'justify-end', 'between' => 'justify-between',
        'around' => 'justify-around', 'evenly' => 'justify-evenly',
    ];

    $gapKey = array_key_exists((string) $gap, $gaps) ? (string) $gap : '3';
    $alignKey = array_key_exists($align, $alignments) ? $align : 'center';
    $justifyKey = array_key_exists($justify, $justifications) ? $justify : 'start';
    $classes = implode(' ', [
        'flex max-w-full min-w-0',
        $wrap ? 'flex-wrap' : 'flex-nowrap',
        $gaps[$gapKey],
        $alignments[$alignKey],
        $justifications[$justifyKey],
        '[&>*]:min-w-0',
    ]);
@endphp

<{{ $tag }}
    data-slot="cluster"
    data-gap="{{ $gapKey }}"
    {{ $attributes->merge(['class' => $classes]) }}
>{{ $slot }}</{{ $tag }}>