Select

# Brok UI: Advanced Select (`select-advanced`)

Custom listbox select with keyboard navigation, type-ahead, rich options (secondary meta) and a hidden form value.

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

## Install

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

## Usage

```blade
<div class="w-full max-w-xs">
    <x-ui.select-advanced name="fruit" :placeholder="__('Select a fruit')">
        <x-ui.select-advanced.option value="apple">{{ __('Apple') }}</x-ui.select-advanced.option>
        <x-ui.select-advanced.option value="banana">{{ __('Banana') }}</x-ui.select-advanced.option>
        <x-ui.select-advanced.option value="blueberry">{{ __('Blueberry') }}</x-ui.select-advanced.option>
        <x-ui.select-advanced.option value="grapes">{{ __('Grapes') }}</x-ui.select-advanced.option>
        <x-ui.select-advanced.option value="pineapple">{{ __('Pineapple') }}</x-ui.select-advanced.option>
    </x-ui.select-advanced>
</div>
```

## Props

- `name` (string|null, default `null`) — Hidden input name for the selected value.
- `value` (mixed, default ``) — On <x-ui.select-advanced.option>: the value submitted and matched when this option is chosen.
- `label` (mixed|null, default ``) — On <x-ui.select-advanced.option>: primary text; defaults to the slot content and drives type-ahead matching.
- `placeholder` (string, default `Select an option`) — Trigger label before selection.
- `description` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `meta` (mixed|null, default `null`) — Declared by @props in the registry Blade source.

## Use when

- Use when users choose among a bounded set and space efficiency matters more than always-visible comparison.
- Needing full keyboard support (arrow keys, type-ahead, Home/End) and rich options with a secondary description or trailing meta.
- Styling the trigger and option list beyond what a native <select> allows.

## Avoid when

- Do not use for tiny lists or when users benefit from seeing all options at once.
- A plain, short option list where native <select> semantics and mobile picker UI are preferred; use select instead.
- The user should be able to filter by typing; use combobox instead.

## Anti-patterns

- Hiding tiny or high-frequency option sets

## Rules

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

{{-- A wrapping <x-ui.field name="…"> shares its name down via @aware so this
     composite self-wires old()/aria-invalid/aria-describedby off the shared
     $errors bag. Inert with no field ancestor and no own `name` —
     fully backward-compatible. --}}
@aware([
    'name' => null,
])

@props([
    'name' => null,
    'value' => '',
    'label' => '',
    'placeholder' => 'Select an option',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $trigger = $styles['field-trigger'];
    $awareName = $name ?? null;
    $fieldName = $awareName ?? $attributes->get('name');

    $bag = ($errors ?? null) instanceof \Illuminate\Support\ViewErrorBag ? $errors : null;
    $hasBagError = $bag && filled($fieldName) && $bag->has($fieldName);

    // old() repopulates the chosen value after a failed redirect-back.
    $resolvedValue = filled($fieldName) ? old($fieldName, $value) : $value;

    $describedBy = (filled($awareName) && $hasBagError) ? $fieldName.'-error' : null;
@endphp

{{--
    Advanced Select (spec §17 + §19). A custom listbox-based select with full
    keyboard support: ArrowUp/Down/Home/End to move, type-ahead to jump,
    Enter/Space to choose, Escape to close. Single value, mirrored to a hidden
    input for forms. For a plain native control use <x-ui.select> instead.
--}}
<div
    x-data="uiSelect({ value: @js($resolvedValue), label: @js($label) })"
    {{-- Modelable: `x-model` (Alpine) and `wire:model` (Livewire binds through
         the same x-model contract) attach to the root. Inert without either. --}}
    x-modelable="model"
    x-id="['select-list']"
    data-slot="select-advanced"
    @if ($hasBagError) data-invalid="true" @endif
    @keydown.escape="if (open) { $event.stopPropagation(); closeAndFocus() }"
    @click.outside="close()"
    {{ $attributes->except(['name'])->merge(['class' => 'relative w-full']) }}
>
    @if (filled($fieldName))
        <input type="hidden" name="{{ $fieldName }}" :value="value" />
    @endif

    <button
        type="button"
        data-slot="select-trigger"
        x-ref="trigger"
        role="combobox"
        aria-haspopup="listbox"
        x-bind:aria-label="label || @js($placeholder) || @js(__('Select option'))"
        :aria-expanded="open"
        x-bind:aria-controls="$id('select-list')"
        x-bind:aria-activedescendant="activeId()"
        @if ($hasBagError) aria-invalid="true" @endif
        @if (filled($describedBy)) aria-describedby="{{ $describedBy }}" @endif
        @click="toggle()"
        @keydown.down.prevent="open ? move(1) : show()"
        @keydown.up.prevent="open ? move(-1) : show()"
        @keydown.enter.prevent="open ? choose() : show()"
        @keydown.space.prevent="open ? choose() : show()"
        @keydown="typeahead($event)"
        class="{{ $trigger['base'] }} {{ $trigger['sizes']['md'] }} {{ $trigger['states'][$hasBagError ? 'invalid' : 'default'] }}"
    >
        <span class="truncate" :class="label ? 'text-foreground' : 'text-muted-foreground'" x-text="label || @js($placeholder)"></span>
        <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 text-muted-foreground">
            <path d="m6 9 6 6 6-6" />
        </svg>
    </button>

    <div
        data-slot="select-content"
        role="listbox"
        x-ref="list"
        x-bind:id="$id('select-list')"
        x-show="open"
        x-cloak
        x-transition:enter="motion-safe:transition motion-safe:duration-100 motion-safe:ease-out"
        x-transition:enter-start="opacity-0 motion-safe:scale-[0.97]"
        x-transition:enter-end="opacity-100 motion-safe:scale-100"
        x-transition:leave="motion-safe:transition motion-safe:duration-75 motion-safe:ease-in"
        x-transition:leave-start="opacity-100 motion-safe:scale-100"
        x-transition:leave-end="opacity-0 motion-safe:scale-[0.97]"
        class="absolute z-dropdown mt-1 max-h-60 w-full origin-top overflow-y-auto rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md motion-reduce:transition-none"
    >
        {{ $slot }}
    </div>
</div>

@props([
    'value',
    'label' => null,
    'description' => null,
    'meta' => null,
])

@php
    // Primary label drives type-ahead matching; the slot holds the visible
    // primary text (or the explicit `label` prop when given).
    $primary = $label ?? trim($slot);

    // A rich option carries a secondary line and/or a trailing meta adornment
    // (or a leading icon slot). Screen readers get the whole row as one phrase
    // via aria-label so label + description + meta read coherently.
    $isRich = filled($description) || filled($meta) || isset($icon);
    $ariaLabel = collect([$primary, $description, $meta])->filter()->implode(', ');
@endphp

<div
    data-slot="select-option"
    role="option"
    data-value="{{ $value }}"
    data-label="{{ $primary }}"
    x-bind:id="$id('select-list') + '-option-' + encodeId(@js($value))"
    @if ($isRich) aria-label="{{ $ariaLabel }}" @endif
    :aria-selected="value === @js($value)"
    :data-active="active === @js($value)"
    @click="select(@js($value), @js($primary))"
    @mousemove="active = @js($value)"
    {{ $attributes->merge(['class' => 'flex cursor-pointer items-center justify-between gap-2 rounded-sm px-2 py-2 text-sm text-popover-foreground outline-none transition-colors data-[active=true]:bg-accent data-[active=true]:text-accent-foreground']) }}
>
    <span class="flex min-w-0 items-center gap-2">
        @isset($icon)
            <span class="grid shrink-0 place-items-center text-muted-foreground" aria-hidden="true">{{ $icon }}</span>
        @endisset
        @if ($isRich)
            <span class="flex min-w-0 flex-col">
                <span class="truncate">{{ $primary }}</span>
                @if (filled($description))
                    <span class="truncate text-xs text-muted-foreground">{{ $description }}</span>
                @endif
            </span>
        @else
            <span class="truncate">{{ $slot }}</span>
        @endif
    </span>
    <span class="flex shrink-0 items-center gap-2">
        @if (filled($meta))
            <span class="text-xs text-muted-foreground">{{ $meta }}</span>
        @endif
        <svg x-show="value === @js($value)" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 text-primary">
            <path d="M20 6 9 17l-5-5" />
        </svg>
    </span>
</div>

/**
 * Advanced Select behavior (spec §17 + §19): a custom listbox select.
 *
 * Supports ArrowUp/Down/Home/End navigation, type-ahead (jump to the option
 * whose label starts with the typed characters), Enter/Space to choose, and
 * Escape to close. The selection mirrors to a hidden input for forms.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiSelect', (config = {}) => ({
        open: false,
        value: config.value ?? '',
        label: config.label ?? '',
        active: null,
        typed: '',
        typedTimer: null,

        /**
         * Modelable value (`x-modelable="model"` on the root). An inbound value
         * (Livewire, `x-model`) also refreshes the trigger label from the
         * matching option's markup.
         */
        get model() {
            return this.value;
        },
        set model(v) {
            const next = v == null ? '' : String(v);
            if (next === String(this.value)) return;
            this.value = next;
            const option = this.options().find((el) => el.dataset.value === next);
            this.label = option ? option.dataset.label || option.textContent.trim() : '';
        },

        options() {
            const list = this.$refs.list;
            if (!list) {
                return [];
            }
            return Array.from(list.querySelectorAll('[data-slot="select-option"]'));
        },

        values() {
            return this.options().map((el) => el.dataset.value);
        },

        toggle() {
            this.open ? this.close() : this.show();
        },

        show() {
            this.open = true;
            this.active = this.value || this.values()[0] || null;
            this.scrollActiveIntoView();
        },

        close() {
            this.open = false;
        },

        closeAndFocus() {
            if (!this.open) {
                return;
            }
            this.open = false;
            this.$nextTick(() => this.$refs.trigger?.focus());
        },

        move(direction) {
            const values = this.values();
            if (values.length === 0) {
                return;
            }
            const current = values.indexOf(this.active);
            const next = current === -1
                ? (direction > 0 ? 0 : values.length - 1)
                : (current + direction + values.length) % values.length;
            this.active = values[next];
            this.scrollActiveIntoView();
        },

        scrollActiveIntoView() {
            this.$nextTick(() => {
                this.$refs.list
                    ?.querySelector(`[data-slot="select-option"][data-value="${CSS.escape(this.active)}"]`)
                    ?.scrollIntoView({ block: 'nearest' });
            });
        },

        /**
         * Stable DOM id for the active option, so the trigger can point
         * `aria-activedescendant` at it. Returns null when nothing is active.
         */
        activeId() {
            return this.active == null
                ? null
                : `${this.$id('select-list')}-option-${this.encodeId(this.active)}`;
        },

        /** Turn an arbitrary option value into an id-safe suffix. */
        encodeId(value) {
            return String(value).replace(/[^a-zA-Z0-9_-]/g, '-');
        },

        typeahead(event) {
            // Only printable single characters; ignore navigation/modifier keys.
            if (event.key.length !== 1 || event.metaKey || event.ctrlKey || event.altKey) {
                return;
            }
            if (!this.open) {
                this.show();
            }
            clearTimeout(this.typedTimer);
            this.typed += event.key.toLowerCase();
            this.typedTimer = setTimeout(() => (this.typed = ''), 600);

            const match = this.options().find((el) =>
                (el.dataset.label || '').toLowerCase().startsWith(this.typed)
            );
            if (match) {
                this.active = match.dataset.value;
                this.scrollActiveIntoView();
            }
        },

        choose() {
            if (this.active == null) {
                return;
            }
            this.$refs.list
                ?.querySelector(`[data-slot="select-option"][data-value="${CSS.escape(this.active)}"]`)
                ?.click();
        },

        select(value, label) {
            this.value = value;
            this.label = label;
            this.open = false;
            this.$dispatch('change', { value });
            this.$nextTick(() => this.$refs.trigger?.focus());
        },

        destroy() {
            // Clear the pending type-ahead reset so the timer cannot fire after teardown.
            clearTimeout(this.typedTimer);
        },
    }));
});