Select

# Brok UI: Native Select (`select`)

A native select control with a custom chevron and an optional leading icon. Inside a <x-ui.field name> (or with its own name) it self-wires name/id and aria-invalid/aria-describedby from the shared $errors bag.

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

## Install

```bash
php artisan ui:add select
```

## Usage

```blade
<x-ui.select aria-label="{{ __('Country') }}" class="max-w-sm">
    <option>{{ __('United States') }}</option>
    <option>{{ __('Netherlands') }}</option>
    <option>{{ __('Japan') }}</option>
</x-ui.select>
```

## Props

- `size` (sm|default|lg, default `md`) — Control height and text size.
- `invalid` (bool|null, default `false`) — Overrides validation-derived invalid state.
- `disabled` (bool, default `false`) — Declared by @props in the shipped Blade source.
- `icon` (mixed|null, default `null`) — Declared by @props in the shipped Blade source.

## Use when

- Use when users choose among a bounded set and space efficiency matters more than always-visible comparison.
- Selecting one value from a compact list where native platform behavior is desirable.
- A server-submitted form needs resilient no-JavaScript behavior.

## Avoid when

- Do not use for tiny lists or when users benefit from seeing all options at once.
- Use to save space with longer lists; do not hide tiny sets that deserve direct comparison.
- Options need search, rich metadata, or custom multi-select behavior; use select-advanced or combobox.
- There are only two to five choices that should remain visible; use radio or choicebox.

## Anti-patterns

- Hiding tiny or high-frequency option sets

## Rules

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

{{-- Inherited from a wrapping field with a name (see input for the rationale). --}}
@aware([
    'name' => null,
    'htmlName' => null,
    'hint' => null,
    'required' => false,
])

@props([
    'size' => 'md',
    'invalid' => false,
    'disabled' => false,
    'icon' => null,
])

@php
    $hasIcon = filled($icon ?? null);

    // @aware leaves $name undefined when there is no wrapping field, so normalise it.
    $awareName = $name ?? null;
    $awareHtmlName = $htmlName ?? null;

    // Effective field name: the @aware value from a wrapping field, else an explicit
    // `name` attribute on the select itself. (Selected-option repopulation lives in
    // the slotted options, so old() selection is the consumer's call here; we wire
    // name/id/aria so labels + validation messaging associate correctly.)
    $fieldName = $awareName ?? $attributes->get('name');
    $resolvedHtmlName = $awareName
        ? ($awareHtmlName ?? collect(explode('.', $awareName))->reduce(
            fn ($carry, $segment, $index) => $index === 0 ? $segment : $carry.'['.$segment.']',
            ''
        ))
        : $attributes->get('name');

    $bag = ($errors ?? null) instanceof \Illuminate\Support\ViewErrorBag ? $errors : null;
    $hasBagError = $bag && filled($fieldName) && $bag->has($fieldName);
    $describedBy = collect(preg_split('/\s+/', trim((string) $attributes->get('aria-describedby', ''))) ?: [])
        ->when(filled($awareName) && filled($hint ?? null), fn ($ids) => $ids->push($fieldName.'-description'))
        ->when(filled($awareName) && $hasBagError, fn ($ids) => $ids->push($fieldName.'-error'))
        ->filter()
        ->unique()
        ->implode(' ');
    $resolvedId = $attributes->get('id', filled($fieldName) ? $fieldName : null);
    $isRequired = (bool) ($required ?? false) || $attributes->has('required');

    // Leading icon shifts the option text padding so it clears the icon; the
    // trailing chevron always reserves end-padding. Logical props keep it RTL-safe.
    $sizes = [
        'sm' => ($hasIcon ? 'ps-9' : 'ps-control-x-sm').' h-control-h-sm pe-9 text-sm',
        'md' => ($hasIcon ? 'ps-9' : 'ps-control-x-md').' h-control-h-md pe-9 text-sm',
        'lg' => ($hasIcon ? 'ps-11' : 'ps-control-x-lg').' h-control-h-lg pe-10 text-base',
    ];

    $iconStart = $size === 'lg' ? 'start-4' : 'start-3';

    $base = 'w-full min-w-0 appearance-none rounded-md border bg-background text-foreground shadow-sm transition-colors '
        .'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background '
        .'disabled:cursor-not-allowed disabled:opacity-50';

    $isInvalid = $invalid || $hasBagError;
    $state = $isInvalid ? 'border-destructive focus-visible:ring-destructive' : 'border-input';

    // 'default' is shadcn's canonical size token; alias it to md (additive).
    $size = $size === 'default' ? 'md' : $size;

    $classes = trim($base.' '.$state.' '.($sizes[$size] ?? $sizes['md']));

    // Width utilities (`w-*`, `max-w-*`, `min-w-*`, with any variant prefix) size
    // the wrapper — the element that anchors the chevron/icon overlays — so the
    // chevron stays inside a narrowed control instead of drifting to the end of
    // a full-width wrapper. Everything else lands on the <select> itself.
    [$widthClasses, $controlClasses] = collect(preg_split('/\s+/', (string) $attributes->get('class', '')) ?: [])
        ->filter()
        ->partition(fn (string $class) => preg_match('/^(?:[a-z0-9-]+:)*(?:max-w|min-w|w)-/', $class) === 1);
    $attributes = $attributes->except('class')->merge(['class' => trim($controlClasses->implode(' '))]);
@endphp

{{-- The wrapper anchors the chevron/icon overlays; consumer `class` lands on the
     <select> itself (matching input/textarea) so e.g. `class="h-20"` sizes the
     actual control, while width utilities size the wrapper (see above). --}}
<div data-slot="select" class="{{ trim('relative inline-flex w-full items-center '.$widthClasses->implode(' ')) }}">
    @if ($hasIcon)
        {{-- Optional leading icon: a decorative, pointer-transparent overlay. The
             slot supplies an <svg>/icon; we only position and tint it. --}}
        <span data-slot="select-icon" aria-hidden="true" class="pointer-events-none absolute {{ $iconStart }} flex size-4 items-center justify-center text-muted-foreground [&_svg]:size-4">
            {{ $icon }}
        </span>
    @endif

    <select
        @if (filled($resolvedHtmlName)) name="{{ $resolvedHtmlName }}" @endif
        @if (filled($resolvedId)) id="{{ $resolvedId }}" @endif
        @disabled($disabled)
        @required($isRequired)
        @if ($isRequired) aria-required="true" @endif
        @if ($isInvalid) aria-invalid="true" @endif
        @if (filled($describedBy)) aria-describedby="{{ $describedBy }}" @endif
        {{ $attributes->except(['name', 'id', 'required', 'aria-required', 'aria-describedby'])->merge(['class' => $classes]) }}
    >
        {{ $slot }}
    </select>

    <svg
        class="pointer-events-none absolute end-3 size-4 text-muted-foreground"
        viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"
    >
        <path d="m6 9 6 6 6-6" stroke-linecap="round" stroke-linejoin="round" />
    </svg>
</div>