Choice

# Brok UI: Choicebox (`choicebox`)

The option card: a label around a real radio or checkbox (native control, keyboard, focus ring, invalid state, plain form submission) that styles itself off :has(:checked), with the control at the end, the start (a row) or hidden, sm/md sizes, an icon slot and a badge; choicebox.group renders a set from an options array. Supersedes radio-rows.

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

## Install

```bash
php artisan ui:add choicebox
```

## Usage

```blade
{{-- Radio cards in a group: the group shares `name` (and type, size, indicator)
     down, so a card only states its own value. The native radio sits at the end. --}}
<x-ui.choicebox.group name="plan" label="{{ __('Plan') }}" class="w-full max-w-md">
    <x-ui.choicebox value="pro" checked :title="__('Pro')" :description="__('Everything in Starter plus advanced analytics and priority support.')" :badge="__('Popular')" />
    <x-ui.choicebox value="starter" :title="__('Starter')" :description="__('For individuals getting started, up to 3 projects.')" />
    <x-ui.choicebox value="enterprise" disabled :title="__('Enterprise')" :description="__('Custom limits, SSO and a dedicated account manager.')" />
</x-ui.choicebox.group>
```

## Props

- `type` (string, default `radio`) — Underlying control: radio for single-select, checkbox for multi-select.
- `name` (mixed|null, default `null`) — Field name; shared from a wrapping group or field via @aware, or set per card.
- `value` (mixed|null, default `null`) — Submitted value for this card's control.
- `title` (mixed|null, default `null`) — Card headline shown beside the badge.
- `description` (mixed|null, default `null`) — Supporting text shown under the title.
- `checked` (bool, default `false`) — Initial checked state; overridden by old() input when a matching field name is flashed.
- `disabled` (bool, default `false`) — Disables the control and dims the card.
- `disabledReason` (string|null, default `null`) — Why a disabled card cannot be picked. Shown under the description in full foreground (still readable on the dimmed card) and tied to the control with aria-describedby. Ignored while the card is enabled; choicebox.group takes it per option as disabledReason.
- `badge` (mixed|null, default `null`) — Optional badge rendered beside the title.
- `size` (md|sm, default `md`) — md is a surface-sized card (rounded-lg, p-6); sm is control-sized (rounded-md, p-4).
- `indicator` (string, default `end`) — Where the native control sits: end (classic card), start (a row), or none (card border alone shows selection).
- `tone` (neutral|primary, default `neutral`) — Colour of the checked card: neutral uses a foreground border and ring on a faint neutral tint, so a product that keeps primary for its one main action and focus is not diluted; primary uses the brand border, ring and tint. The card's radio or checkbox and its icon chip follow the tone; choicebox.group shares it with every card.
- `options` (array, default `[]`) — Declared by @props in the registry Blade source.
- `label` (mixed|null, default `null`) — Declared by @props in the registry Blade source.

## Use when

- Use for a small set of mutually exclusive options that users should compare visibly before choosing.
- Presenting a small set of options as tappable cards with a title, description, icon or badge.
- Letting the whole card area, not just a small control, respond to selection.

## Avoid when

- Do not hide a small option set in a dropdown when recognition and comparison matter.
- Listing more than a handful of plain-text options; use radio or checkbox directly.
- Building a dense inline row of pill-style choices; use radio-tabs.

## Anti-patterns

- Hiding a small comparable set in a dropdown

## Rules

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

{{-- A wrapping <x-ui.choicebox.group name="…"> or <x-ui.field name="…"> shares
     its name (and type, size, indicator) down via @aware, so a card never repeats
     them. Inert with no ancestor and no own `name` — fully backward-compatible. --}}
@aware([
    'name' => null,
    'type' => 'radio',
    'size' => 'md',
    'indicator' => 'end',
    'tone' => 'neutral',
])

@props([
    'type' => 'radio',
    'name' => null,
    'value' => null,
    'title' => null,
    'description' => null,
    'checked' => false,
    'disabled' => false,
    // Why a disabled option cannot be picked ("Needs a client first"). Shown
    // under the description and read with the control through
    // aria-describedby. Ignored while the card is enabled.
    'disabledReason' => null,
    'badge' => null,
    // md: surface-sized card (rounded-lg, p-6); sm: control-sized (rounded-md, p-4).
    'size' => 'md',
    // Where the native control sits: end (the classic card), start (a row), none.
    'indicator' => 'end',
    // Colour of the checked card. neutral (default): a foreground border and
    // ring on a faint neutral tint, so a product that keeps primary for its one
    // main action and for focus is not diluted. primary: the brand border,
    // ring and tint. The card's radio or checkbox follows the same tone.
    'tone' => 'neutral',
])

@php
    $awareName = $name ?? null;
    $fieldName = $awareName ?? $attributes->get('name');
    $type = $type === 'checkbox' ? 'checkbox' : 'radio';
    $size = in_array($size, ['sm', 'md'], true) ? $size : 'md';
    $indicator = in_array($indicator, ['start', 'end', 'none'], true) ? $indicator : 'end';

    // Full class strings per tone so Tailwind's JIT can see every utility: the
    // checked card (border, ring, tint) and the checked icon chip.
    $tones = [
        'neutral' => [
            'card' => 'has-[:checked]:border-foreground has-[:checked]:bg-foreground/[0.03] has-[:checked]:ring-1 has-[:checked]:ring-foreground',
            'icon' => 'group-has-[:checked]:bg-foreground group-has-[:checked]:text-background',
        ],
        'primary' => [
            'card' => 'has-[:checked]:border-primary has-[:checked]:bg-primary/[0.03] has-[:checked]:ring-1 has-[:checked]:ring-primary',
            'icon' => 'group-has-[:checked]:bg-primary group-has-[:checked]:text-primary-foreground',
        ],
    ];
    $tone = isset($tones[$tone]) ? $tone : 'neutral';

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

    // Restore selection from old() after a failed redirect-back. A radio card is
    // checked when its value equals the flashed scalar; a checkbox card when its
    // value is in the flashed array. Falls back to the explicit `checked` prop.
    $isChecked = $checked;
    if (filled($fieldName) && $value !== null && app('session')->hasOldInput($fieldName)) {
        $old = old($fieldName);
        $isChecked = $type === 'checkbox'
            ? in_array((string) $value, array_map('strval', (array) $old), true)
            : (string) $old === (string) $value;
    }

    $describedBy = (filled($awareName) && $hasBagError) ? $fieldName.'-error' : null;
    // A stable id from the card's own data, so a render is deterministic.
    $reasonId = ($disabled && filled($disabledReason))
        ? 'choicebox-reason-'.substr(md5($fieldName.'|'.$value.'|'.$disabledReason), 0, 10)
        : null;
    $describedBy = trim(($describedBy ?? '').' '.($reasonId ?? '')) ?: null;
    $controlName = filled($fieldName) ? ($type === 'checkbox' ? $fieldName.'[]' : $fieldName) : null;

    // One id per option, from the field name and the value: a named group no
    // longer repeats the field name as every control's id. A value that is not
    // id-safe keeps a readable slug plus a short hash, so ids stay unique.
    $valueKey = (string) $value;
    $idSuffix = preg_match('/^[A-Za-z0-9_-]+$/', $valueKey) === 1
        ? $valueKey
        : trim((string) preg_replace('/[^A-Za-z0-9_-]+/', '-', $valueKey), '-').'-'.substr(md5($valueKey), 0, 6);
    $controlId = filled($fieldName) ? $fieldName.'-'.ltrim($idSuffix, '-') : null;

    // wire:model / x-model on the card bind its native control, not the label.
    $modelAttributes = $attributes->whereStartsWith(['wire:model', 'x-model'])->getAttributes();

    // Border, ring, background and the control move on one 150ms curve so a pick
    // reads as one change; hover and press make the card feel pressable.
    $shape = $size === 'sm' ? 'rounded-md p-4' : 'rounded-lg p-6';
    $card = 'group relative flex items-start gap-3 border border-border bg-card text-start '.$shape.' '
        .'transition-[border-color,box-shadow,background-color,scale] duration-150 ease-out motion-reduce:transition-none '
        .$tones[$tone]['card'].' '
        .($disabled
            ? 'cursor-not-allowed opacity-60'
            : 'cursor-pointer hover:border-input hover:bg-muted/40 active:scale-[0.995]');
@endphp

{{--
    Choicebox — the option card. The whole card is a <label> around a real
    <x-ui.radio> or <x-ui.checkbox>, so it submits in a plain <form> with no
    JavaScript, the native control carries keyboard, focus ring and invalid
    state, and the card styles itself off :has(:checked). `indicator` puts
    the control at the end (card), the start (row), or hides it (`none`, the
    card border alone shows selection). Optional leading `icon` slot and a
    trailing `badge`. Group cards with <x-ui.choicebox.group>.
--}}
<label
    data-slot="{{ $attributes->get('data-slot', 'choicebox') }}"
    {{ $attributes->except(['name', 'data-slot', ...array_keys($modelAttributes)])->merge(['class' => $card]) }}
    data-type="{{ $type }}"
    data-size="{{ $size }}"
    data-indicator="{{ $indicator }}"
    data-tone="{{ $tone }}"
    @if ($hasBagError) data-invalid="true" @endif
>
    @php
        $controlAttributes = [
            'id' => $controlId,
            'name' => $controlName,
            'value' => $value,
            'checked' => $isChecked,
            'disabled' => $disabled,
            'tone' => $tone,
            'aria-describedby' => $describedBy,
            'class' => $indicator === 'none' ? 'sr-only' : 'mt-0.5',
            // A bound choicebox.group finds and syncs its cards' controls by this marker.
            'data-choicebox-control' => true,
        ] + $modelAttributes;
    @endphp

    @if ($indicator !== 'end')
        @if ($type === 'checkbox')
            <x-ui.checkbox :attributes="new \Illuminate\View\ComponentAttributeBag($controlAttributes)" :invalid="$hasBagError" />
        @else
            <x-ui.radio :attributes="new \Illuminate\View\ComponentAttributeBag($controlAttributes)" :invalid="$hasBagError" />
        @endif
    @endif

    @if (isset($icon))
        <span class="mt-0.5 flex size-9 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground transition-colors duration-150 ease-out motion-reduce:transition-none {{ $tones[$tone]['icon'] }}" aria-hidden="true">
            {{ $icon }}
        </span>
    @endif

    <span class="flex min-w-0 flex-1 flex-col gap-1">
        @if ($title || $badge)
            <span class="flex items-center gap-2">
                @if ($title)
                    <span class="text-sm font-medium leading-snug text-foreground">{{ $title }}</span>
                @endif
                @if ($badge)
                    <x-ui.badge variant="secondary" size="sm">{{ $badge }}</x-ui.badge>
                @endif
            </span>
        @endif
        @if ($description)
            <span class="text-sm leading-normal text-muted-foreground">{{ $description }}</span>
        @endif
        @if ($reasonId)
            {{-- Full foreground: the dimmed card leaves it at the muted tone and
                 still above 4.5:1, where muted text would drop below it. --}}
            <span id="{{ $reasonId }}" data-slot="choicebox-reason" class="text-sm leading-normal text-foreground">{{ $disabledReason }}</span>
        @endif
        {{ $slot }}
    </span>

    @if ($indicator === 'end')
        @if ($type === 'checkbox')
            <x-ui.checkbox :attributes="new \Illuminate\View\ComponentAttributeBag($controlAttributes)" :invalid="$hasBagError" />
        @else
            <x-ui.radio :attributes="new \Illuminate\View\ComponentAttributeBag($controlAttributes)" :invalid="$hasBagError" />
        @endif
    @endif
</label>

{{-- A wrapping <x-ui.field name="…"> shares its name down via @aware; the group
     adopts it, forwards name/type/size/indicator/tone to every card (each reads them
     via @aware) and self-wires aria-invalid/aria-describedby off the shared
     $errors bag. --}}
@aware([
    'name' => null,
])

@props([
    'name' => null,
    // Radio groups take one value; checkbox groups an array of values.
    'value' => null,
    'type' => 'radio',
    'size' => 'md',
    'indicator' => 'end',
    // Checked colour of every card (neutral | primary), read by each card via @aware.
    'tone' => 'neutral',
    // Declarative cards: [['value', 'title', 'description', 'badge', 'disabled', 'disabledReason']];
    // the card matching `value` is checked. Hand-composed cards mark `checked`
    // themselves (a parent's computed state cannot reach a child through @aware).
    'options' => [],
    'label' => null,
])

@php
    $awareName = $name ?? null;
    $fieldName = $awareName ?? $attributes->get('name');
    $type = $type === 'checkbox' ? 'checkbox' : 'radio';

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

    // Restore selection from old() after a failed redirect-back; fall back to
    // the passed `value` when there is no flashed input.
    $resolvedValue = filled($fieldName) ? old($fieldName, $value) : $value;
    $selected = array_map('strval', $type === 'checkbox' ? (array) $resolvedValue : ($resolvedValue === null ? [] : [$resolvedValue]));

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

    // wire:model / x-model on the group bind its value (a scalar for radio, an
    // array for checkbox). The root becomes modelable and keeps every card's
    // native control checked from the bound value, so a server-side change or
    // reset shows after a Livewire update. Without a binding the group stays
    // plain HTML with no JavaScript.
    $bound = $attributes->whereStartsWith(['wire:model', 'x-model'])->isNotEmpty();
    $initialChoice = $type === 'checkbox' ? $selected : ($selected[0] ?? null);
@endphp

<div
    role="{{ $type === 'checkbox' ? 'group' : 'radiogroup' }}"
    data-slot="{{ $attributes->get('data-slot', 'choicebox-group') }}"
    data-type="{{ $type }}"
    @if ($label) aria-label="{{ __($label) }}" @endif
    @if ($hasBagError) data-invalid="true" aria-invalid="true" @endif
    @if (filled($describedBy)) aria-describedby="{{ $describedBy }}" @endif
    @if ($bound)
        x-data="{ choice: @js($initialChoice) }"
        x-modelable="choice"
        @if ($type === 'checkbox')
            x-effect="const picked = (Array.isArray(choice) ? choice : []).map(String); $el.querySelectorAll('[data-choicebox-control]').forEach((control) => { control.checked = picked.includes(control.value) })"
            x-on:input="if ($event.target.hasAttribute('data-choicebox-control')) { choice = Array.from($el.querySelectorAll('[data-choicebox-control]:checked'), (control) => control.value) }"
        @else
            x-effect="const picked = choice === null || choice === undefined ? null : String(choice); $el.querySelectorAll('[data-choicebox-control]').forEach((control) => { control.checked = control.value === picked })"
            x-on:input="if ($event.target.hasAttribute('data-choicebox-control')) { choice = $event.target.value }"
        @endif
        {{-- .blur: blur does not bubble, so the group reports one when focus leaves it.
             Safari does not focus a radio or checkbox on click, so focus never
             entered the group and a mouse pick was never sent; focus it here. --}}
        x-on:change="if ($event.target.hasAttribute('data-choicebox-control') && document.activeElement !== $event.target) { $event.target.focus({ preventScroll: true }) }"
        x-on:focusout="if (! $el.contains($event.relatedTarget)) { $el.dispatchEvent(new FocusEvent('blur')) }"
    @endif
    {{ $attributes->except(['name', 'data-slot'])->merge(['class' => 'flex flex-col gap-2']) }}
>
    @if (! empty($options))
        @foreach ($options as $option)
            <x-ui.choicebox
                :value="$option['value']"
                :title="$option['title'] ?? null"
                :description="$option['description'] ?? null"
                :badge="$option['badge'] ?? null"
                :disabled="$option['disabled'] ?? false"
                :disabled-reason="$option['disabledReason'] ?? null"
                :checked="in_array((string) $option['value'], $selected, true)"
            />
        @endforeach
    @else
        {{ $slot }}
    @endif
</div>