Stack

# Brok UI: Stack (`stack`)

A flexbox layout primitive that arranges children in a row or column with consistent spacing, alignment, and optional dividers.

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

## Install

```bash
php artisan ui:add stack
```

## Usage

```blade
<div class="flex flex-col gap-10 p-6">
    {{-- Vertical stack (default) --}}
    <div>
        <p class="mb-3 text-xs font-medium uppercase tracking-widest text-muted-foreground">{{ __('Vertical (col)') }}</p>
        <x-ui.stack gap="3" class="w-48">
            <div class="rounded-lg border border-border bg-card px-4 py-3 text-sm text-card-foreground">{{ __('Item one') }}</div>
            <div class="rounded-lg border border-border bg-card px-4 py-3 text-sm text-card-foreground">{{ __('Item two') }}</div>
            <div class="rounded-lg border border-border bg-card px-4 py-3 text-sm text-card-foreground">{{ __('Item three') }}</div>
        </x-ui.stack>
    </div>

    {{-- Horizontal stack --}}
    <div>
        <p class="mb-3 text-xs font-medium uppercase tracking-widest text-muted-foreground">{{ __('Horizontal (row)') }}</p>
        <x-ui.stack direction="row" gap="3" align="center">
            <span class="inline-flex items-center rounded-full bg-primary px-3 py-1 text-xs font-medium text-primary-foreground">{{ __('Alpha') }}</span>
            <span class="inline-flex items-center rounded-full bg-secondary px-3 py-1 text-xs font-medium text-secondary-foreground">{{ __('Beta') }}</span>
            <span class="inline-flex items-center rounded-full bg-muted px-3 py-1 text-xs font-medium text-muted-foreground">{{ __('Gamma') }}</span>
        </x-ui.stack>
    </div>

    {{-- Vertical stack with dividers --}}
    <div>
        <p class="mb-3 text-xs font-medium uppercase tracking-widest text-muted-foreground">{{ __('Vertical with dividers') }}</p>
        <x-ui.stack gap="0" divider class="w-48 rounded-lg border border-border bg-card">
            <div class="px-4 py-3 text-sm text-card-foreground">{{ __('Section A') }}</div>
            <div class="px-4 py-3 text-sm text-card-foreground">{{ __('Section B') }}</div>
            <div class="px-4 py-3 text-sm text-card-foreground">{{ __('Section C') }}</div>
        </x-ui.stack>
    </div>
</div>
```

## Props

- `direction` (string, default `col`) — Flex direction: col (vertical stack) or row (horizontal stack).
- `gap` (string, default `4`) — Gap between items, from the fixed step vocabulary (0-16, or sm/md/lg tokens).
- `align` (string, default `stretch`) — 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 `false`) — Whether items wrap onto new lines when they run out of space.
- `divider` (bool, default `false`) — Draws a border between adjacent children instead of relying on gap alone.
- `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.
- Arranging a simple one-dimensional row or column of elements with consistent spacing.
- Needing an optional divider line drawn between children instead of hand-composing separator elements.

## Avoid when

- Do not let layout primitives substitute for semantics, headings, or interaction rules users still need.
- Items should wrap onto multiple lines as space runs out; use cluster 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:stack>` tag (or `<x-ui.stack>`) 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/stack
- Registry JSON (files, props, contract): https://brokui.dev/r/open/stack.json

@props([
    'direction' => 'col',
    'gap'       => '4',
    'align'     => 'stretch',
    'justify'   => 'start',
    'wrap'      => false,
    'divider'   => false,
    'as'        => 'div',
])

@php
    $allowedTags = ['div', 'section', 'nav', 'header', 'footer', 'ul', 'ol'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'div';
    $dirClass = match ($direction) {
        'row'   => 'flex flex-row',
        default => 'flex flex-col',
    };

    $alignClass = match ($align) {
        'start'    => 'items-start',
        'center'   => 'items-center',
        'end'      => 'items-end',
        'baseline' => 'items-baseline',
        default    => 'items-stretch',
    };

    $justifyClass = match ($justify) {
        'center'  => 'justify-center',
        'end'     => 'justify-end',
        'between' => 'justify-between',
        'around'  => 'justify-around',
        'evenly'  => 'justify-evenly',
        default   => 'justify-start',
    };

    $divideClass = $divider
        ? ($direction === 'row' ? 'divide-x divide-border' : 'divide-y divide-border')
        : '';

    // Fixed vocabulary: every class is literal so Tailwind can discover it.
    // Unknown values fall back to the standard 16px stack rhythm.
    $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',
    ];
    $gapKey      = array_key_exists((string) $gap, $gaps) ? (string) $gap : '4';
    $gapClass    = $gaps[$gapKey];
    $wrapClass   = $wrap ? 'flex-wrap' : '';

    $classes = trim(implode(' ', array_filter([
        $dirClass,
        $gapClass,
        $alignClass,
        $justifyClass,
        $wrapClass,
        $divideClass,
    ])));
@endphp

<{{ $tag }}
    data-slot="stack"
    data-direction="{{ $direction === 'row' ? 'row' : 'col' }}"
    data-gap="{{ $gapKey }}"
    {{ $attributes->merge(['class' => $classes]) }}
>{{ $slot }}</{{ $tag }}>