Tray

# Brok UI: Tray (`tray`)

A tinted outer frame with a header row (icon, title, end action) around a raised inner well for KPI tiles, chart panels and short lists.

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

## Install

```bash
php artisan ui:add tray
```

## Usage

```blade
{{-- Two KPI tiles (a `stat` in `plain` variant fills the well) and one tray
     with a "View all" action wrapping a short transaction list. --}}
<div class="mx-auto flex w-full max-w-3xl flex-col gap-4">
    <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
        <x-ui.tray title="{{ __('Total revenue') }}">
            <x-slot:icon>
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 3v18h18" /><path d="M7 16v-4" /><path d="M12 16V8" /><path d="M17 16v-7" /></svg>
            </x-slot:icon>
            <x-ui.stat variant="plain" value="$4,500" delta="+12.5%" />
        </x-ui.tray>

        <x-ui.tray title="{{ __('Net profit') }}">
            <x-slot:icon>
                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9" /><path d="M12 7v10M8.5 9.5h4.75a1.75 1.75 0 1 1 0 3.5h-2.5a1.75 1.75 0 1 0 0 3.5H15.5" /></svg>
            </x-slot:icon>
            <x-ui.stat variant="plain" value="$4,800" delta="+12.5%" />
        </x-ui.tray>
    </div>

    <x-ui.tray :title="__('Transactions')" :action-label="__('View all')" action-href="#" padding="none">
        <x-slot:icon>
            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m17 3 4 4-4 4" /><path d="M21 7H9" /><path d="m7 21-4-4 4-4" /><path d="M3 17h12" /></svg>
        </x-slot:icon>
        <ul role="list" class="divide-y divide-border">
            @foreach ([
                ['name' => __('Northwind'), 'subtitle' => __('Subscription'), 'amount' => __('-$220.36'), 'time' => __('2 min ago')],
                ['name' => __('Acme'), 'subtitle' => __('Subscription'), 'amount' => __('-$110.00'), 'time' => __('10 min ago')],
                ['name' => __('Harbor Payroll'), 'subtitle' => __('Payment'), 'amount' => __('+$3,500.00'), 'time' => __('12 Jul 2026')],
            ] as $row)
                <li class="flex items-center gap-3 px-4 py-3">
                    <x-ui.avatar size="sm" :alt="$row['name']" :fallback="mb_strtoupper(mb_substr($row['name'], 0, 1))" class="shrink-0" />
                    <span class="min-w-0 flex-1">
                        <span class="block truncate text-sm font-medium text-foreground">{{ $row['name'] }}</span>
                        <span class="block truncate text-xs text-muted-foreground">{{ $row['subtitle'] }}</span>
                    </span>
                    <span class="shrink-0 text-end">
                        <span class="block text-sm font-medium tabular-nums text-foreground">{{ $row['amount'] }}</span>
                        <span class="block text-xs text-muted-foreground">{{ $row['time'] }}</span>
                    </span>
                </li>
            @endforeach
        </ul>
    </x-ui.tray>
</div>
```

## Props

- `as` (string, default `div`) — Element the frame renders as: div, section, or article.
- `title` (string|null, default `null`) — Header title, shown small/medium/muted above the well.
- `headingLevel` (string|null, default `null`) — h2..h6 — promotes the title to a real heading element. Left null it stays a plain label.
- `actionLabel` (string|null, default `null`) — Convenience end-action link text (e.g. 'View all'), paired with actionHref. The action slot wins when both are supplied.
- `actionHref` (string|null, default `null`) — Href for the actionLabel convenience link.
- `padding` (none|sm|md|lg, default `md`) — The well's inner padding. none lets the slot's own content (a table, a chart) own the inset.

## Use when

- Use when self-contained content objects benefit from a recognizable card-like presentation with local actions or metadata.
- Grouping a KPI tile, chart, or short list inside a tinted frame with a small header (icon, title, and an optional 'View all' action) — the dashboard panel pattern.
- Giving a raised, bordered well its own frame so several trays read as one system across a grid of tiles and wider panels.

## Avoid when

- Do not use card widgets where a simpler list, table, or plain text block would make comparison faster.
- A single flat surface with no header is enough; use card instead.
- The list itself needs the card chrome and rows, with no outer frame or well; use list-panel instead.

## Anti-patterns

- Using cards for dense cross-item comparison

## Rules

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

@props([
    // The tag the outer frame renders as. 'div' (default), 'section', 'article'.
    'as' => 'div',
    // Header title, shown small/medium/muted above the well. Pass `headingLevel`
    // to promote it to a real heading; without one it stays a plain label — the
    // tray is usually one of several on a page and does not want to fragment
    // the document's h1/h2/h3 outline on its own.
    'title' => null,
    // 'h2'..'h6'. Renders `title` as that heading element instead of a plain
    // label — opt in when the tray IS the section landmark for its content.
    'headingLevel' => null,
    // Convenience end-action ("View all …"). Prefer the `action` slot for
    // anything richer than a single link; when both are supplied the slot wins.
    'actionLabel' => null,
    'actionHref' => null,
    // The well's inner padding: none (a table/chart owns its own), sm, md
    // (default), lg.
    'padding' => 'md',
])

{{--
    Tray — the "framed card" pattern: a muted, tinted outer frame holding an
    optional header row (icon + title + end action) above a raised inner
    "well" (bg-card, hairline border, subtle shadow) that carries the default
    slot content, and an optional footer strip under the well. Built for KPI
    tiles (`<x-ui.stat variant="plain">` in the well), chart panels, and short
    lists — anything that reads as "one tinted card, one raised panel inside
    it" rather than a single flat card.

    The frame itself never carries a padding utility alongside `rounded-lg` —
    an inner, unrounded wrapper owns the 8px inset instead — so the frame
    stays the 16px surface tier without tripping the surface/inset pairing
    guard. The well sits one radius tier down (`rounded-md`), per the design
    grid's "control radius when nested inside a surface" rule.
--}}

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $allowedTags = ['div', 'section', 'article'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'div';

    $allowedHeadings = ['h2', 'h3', 'h4', 'h5', 'h6'];
    $headingTag = in_array($headingLevel, $allowedHeadings, true) ? $headingLevel : null;

    $paddings = $styles['tray']['padding'];
    $paddingKey = array_key_exists($padding, $paddings) ? $padding : 'md';

    $hasHeader = $title !== null || isset($icon) || isset($action) || $actionLabel !== null;
    $hasAction = isset($action) || $actionLabel !== null;
@endphp

<{{ $tag }}
    data-slot="tray"
    {{ $attributes->merge(['class' => 'min-w-0 rounded-lg border border-border bg-muted text-foreground']) }}
>
    <div class="flex min-w-0 flex-col gap-2 p-2">
        @if ($hasHeader)
            <div data-slot="tray-header" class="flex min-w-0 items-center justify-between gap-3">
                <div class="flex min-w-0 items-center gap-2">
                    @isset($icon)
                        <span data-slot="tray-icon" class="shrink-0 text-muted-foreground [&_svg]:size-4" aria-hidden="true">{{ $icon }}</span>
                    @endisset

                    @if ($title !== null)
                        @if ($headingTag)
                            <{{ $headingTag }} data-slot="tray-title" class="truncate text-sm font-medium text-muted-foreground">{{ $title }}</{{ $headingTag }}>
                        @else
                            <span data-slot="tray-title" class="truncate text-sm font-medium text-muted-foreground">{{ $title }}</span>
                        @endif
                    @endif
                </div>

                @if ($hasAction)
                    <div data-slot="tray-action" class="shrink-0 text-sm text-muted-foreground [&_a]:font-medium [&_a]:underline-offset-4 [&_a:hover]:text-foreground [&_a:hover]:underline">
                        @isset($action)
                            {{ $action }}
                        @else
                            <a href="{{ $actionHref ?? '#' }}">{{ $actionLabel }}</a>
                        @endisset
                    </div>
                @endif
            </div>
        @endif

        <div data-slot="tray-well" data-padding="{{ $paddingKey }}" class="min-w-0 rounded-md border border-border bg-card text-card-foreground shadow-sm {{ $paddings[$paddingKey] }}">
            {{ $slot }}
        </div>

        @isset($footer)
            <div data-slot="tray-footer" class="text-sm text-muted-foreground">
                {{ $footer }}
            </div>
        @endisset
    </div>
</{{ $tag }}>