Item

# Brok UI: Item (`item`)

A flexible layout for list rows: media, content (title, description), actions, plus full-width header and footer rows; grouped with separators, as a container, link or button.

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

## Install

```bash
php artisan ui:add item
```

## Usage

```blade
<x-ui.item variant="outline">
    <x-ui.item.media variant="icon">
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
            <path d="M2 7a2 2 0 0 1 2-2h5l2 2h9a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2z" />
        </svg>
    </x-ui.item.media>

    <x-ui.item.content>
        <x-ui.item.title>{{ __('Project Alpha') }}</x-ui.item.title>
        <x-ui.item.description>{{ __('Updated 2 hours ago') }}</x-ui.item.description>
    </x-ui.item.content>

    <x-ui.item.actions>
        <x-ui.button variant="outline" size="sm">{{ __('View') }}</x-ui.button>
    </x-ui.item.actions>
</x-ui.item>
```

## Props

- `variant` (default|outline|muted|icon|image|icon-sm, default `default`) — Border treatment: default (transparent), outline, or muted (filled background).
- `size` (default|md|sm|xs, default `default`) — Padding and gap tier: default/md, sm, or xs.
- `href` (mixed|null, default `null`) — When set, renders the item as a link and makes it interactive.
- `clickable` (bool, default `false`) — Renders the item as a button and makes it interactive, when href is not set.
- `active` (bool, default `false`) — Marks the item as the current selection, applying accent styling and aria-current or aria-pressed.
- `disabled` (bool, default `false`) — Disables interaction and dims the item; a disabled link also drops out of tab order.

## Use when

- Use to group related content into scannable units for browsing, prioritization, or rearrangement.
- Building a list row that combines media, a title and description, and trailing actions in one consistent layout.
- Grouping several rows with item.group and item.separator, optionally as clickable links or buttons.

## Avoid when

- Do not use card-like structures when dense row-by-row comparison would be clearer in a list or table.
- The row is a simple key-value pair with no media or actions; a plain flex row is lighter weight.
- The rows need multi-column sortable data; use table instead.

## Anti-patterns

- Turning every object into a card

## Rules

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

@props([
    'variant' => 'default',
    'size' => 'default',
    'href' => null,
    'clickable' => false,
    'active' => false,
    'disabled' => false,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $variants = [
        'default' => 'border-transparent',
        'outline' => 'border-border',
        'muted' => 'border-transparent bg-muted',
    ];

    $sizes = [
        // `md` is the house default-size token; `default` is kept as an alias so
        // existing `size="default"` usage stays valid (shared map value).
        'md' => 'gap-4 p-4 text-sm',
        'default' => 'gap-4 p-4 text-sm',
        'sm' => 'gap-3 p-3 text-sm',
        'xs' => 'gap-2 px-3 py-2 text-xs',
    ];

    // An item becomes interactive when given an href or marked clickable.
    // Links and buttons provide their keyboard behavior and semantics natively.
    $isLink = $href !== null;
    $isInteractive = $isLink || $clickable;
    $tag = $isLink ? 'a' : ($clickable ? 'button' : 'div');
    $forwardedAttributes = $tag === 'button' ? $attributes->except(['type']) : $attributes;

    $base = 'group/item flex flex-wrap items-center rounded-md border transition-colors motion-reduce:transition-none';

    $interactiveClass = $isInteractive
        ? 'cursor-pointer hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background'
        : '';

    $activeClass = $active ? 'bg-accent text-accent-foreground' : '';

    $disabledClass = $disabled ? 'pointer-events-none opacity-50' : '';

    $classes = trim(implode(' ', array_filter([
        $base,
        $variants[$variant] ?? $variants['default'],
        $sizes[$size] ?? $sizes['default'],
        $interactiveClass,
        $activeClass,
        $disabledClass,
    ])));
@endphp

<{{ $tag }}
    data-slot="item"
    data-variant="{{ $variant }}"
    data-size="{{ $size }}"
    @if ($active) data-active="true" @endif
    @if ($isLink) href="{{ $disabled ? null : $href }}" @endif
    @if ($tag === 'button') type="{{ $attributes->get('type', 'button') }}" @disabled($disabled) @endif
    @if ($isLink && $active) aria-current="true" @endif
    @if ($tag === 'button') aria-pressed="{{ $active ? 'true' : 'false' }}" @endif
    @if ($isInteractive && $disabled) aria-disabled="true" @endif
    @if ($isLink && $disabled) tabindex="-1" @endif
    {{ $forwardedAttributes->merge(['class' => $classes]) }}
>
    {{ $slot }}
</{{ $tag }}>

@props([
    'variant' => 'default',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $variants = [
        'default' => '',
        'icon' => 'size-8 rounded-sm bg-muted [&_svg]:size-4',
        'image' => 'size-10 overflow-hidden rounded-sm',
        // Compact icon tile for sm/xs item rows and dense menus.
        'icon-sm' => 'size-6 rounded-sm bg-muted [&_svg]:size-4',
    ];

    $base = 'flex shrink-0 items-center justify-center text-foreground';

    $classes = trim($base.' '.($variants[$variant] ?? $variants['default']));
@endphp

<div
    data-slot="item-media"
    data-variant="{{ $variant }}"
    {{ $attributes->merge(['class' => $classes]) }}
>
    {{ $slot }}
</div>