Radio

# Brok UI: Radio (`radio`)

Native radio control with token-driven focus and disabled states, plus a neutral fieldset-based group with legend, orientation, help text and Laravel validation wiring.

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

## Install

```bash
php artisan ui:add radio
```

## Usage

```blade
<brok:radio.group name="preview-radio" label="Shipping method" hint="Choose one delivery speed." class="max-w-md text-start">
    <label class="flex items-center gap-2 text-sm text-foreground">
        <brok:radio value="standard" checked />
        {{ __('Standard shipping') }}
    </label>
    <label class="flex items-center gap-2 text-sm text-foreground">
        <brok:radio value="express" />
        {{ __('Express shipping') }}
    </label>
</brok:radio.group>
```

## Props

- `invalid` (bool, default `false`) — Declared by @props in the shipped Blade source.
- `disabled` (bool, default `false`) — Disables the whole fieldset, including every radio inside it.
- `tone` (neutral|primary, default `neutral`) — Fill of the checked dot, set on each <x-ui.radio>: neutral uses the foreground colour, so a product that keeps primary for its one main action and focus is not diluted; primary uses the brand primary.
- `orientation` (vertical|horizontal, default `vertical`) — Documented catalog control used by the preview workbench.
- `name` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `label` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `hint` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `required` (bool, default `false`) — 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.
- Choosing exactly one option from a small, visible set of mutually exclusive values.
- Grouping radios under a labelled fieldset with shared validation, hint text and orientation.

## Avoid when

- Do not hide a small option set in a dropdown when recognition and comparison matter.
- Prefer this over a select when the option set is small and should remain visible for comparison.
- Selecting zero or more options; use checkbox instead.
- Presenting more than a handful of options or options that need progressive disclosure; use select or combobox.

## Anti-patterns

- Hiding a small comparable set in a dropdown

## Rules

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

{{-- A wrapping <brok:field name="…"> shares its name down via @aware, so the
     radio self-wires aria-invalid/aria-describedby off the shared $errors bag.
     Inert with no field ancestor and no own name — fully backward-compatible.
     (A radio group's name is normally set by the consumer on each radio; @aware
     just lets a single field-wrapped radio inherit it.) --}}
@aware([
    'name' => null,
    'htmlName' => null,
    'required' => false,
])

@props([
    'invalid' => false,
    'disabled' => false,
    // Fill of the selected dot. neutral (default) uses the foreground colour,
    // so a product that keeps primary for its one main action and for focus is
    // not diluted; primary uses the brand primary.
    'tone' => 'neutral',
])

@php
    // Use the native control tinted with the tone's accent (no extra border —
    // drawing our own border on top of the native widget produced a doubled
    // "outer ring"). accent-color renders a clean filled radio in modern browsers.
    // An invisible ::before reaches 4px past the dot on every side: a 24x24
    // pointer target (WCAG 2.5.8) with the drawn size and layout unchanged.
    // `relative` anchors the hit area unless the caller positions the dot itself.
    $positioned = preg_match('/(^|\s)(absolute|fixed|sticky)(\s|$)/', (string) $attributes->get('class')) === 1;
    $base = ($positioned ? '' : 'relative ').'size-4 shrink-0 cursor-pointer transition-colors before:absolute before:-inset-1 '
        .'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';

    // Laravel-native wiring (mirrors input/checkbox).
    $awareName = $name ?? null;
    $awareHtmlName = $htmlName ?? null;
    $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);
    $isInvalid = $invalid || $hasBagError;
    $describedBy = (filled($awareName) && $hasBagError) ? $fieldName.'-error' : null;
    // Radios share a name, so the id comes from the name and the value
    // (plan-pro): a group never repeats an id. A value that is not id-safe
    // keeps a readable slug plus a short hash. An explicit id wins.
    $radioValue = $attributes->get('value');
    $defaultId = null;
    if (filled($fieldName)) {
        $valueKey = (string) $radioValue;
        $idSuffix = preg_match('/^[A-Za-z0-9_-]+$/', $valueKey) === 1
            ? $valueKey
            : ltrim(trim((string) preg_replace('/[^A-Za-z0-9_-]+/', '-', $valueKey), '-').'-'.substr(md5($valueKey), 0, 6), '-');
        $defaultId = $radioValue === null ? $fieldName : $fieldName.'-'.$idSuffix;
    }
    $resolvedId = $attributes->get('id', $defaultId);

    // Full class strings per tone so Tailwind's JIT can see every utility.
    $tones = [
        'neutral' => 'accent-foreground',
        'primary' => 'accent-primary',
    ];
    $tone = isset($tones[$tone]) ? $tone : 'neutral';
    $state = $isInvalid ? 'accent-destructive' : $tones[$tone];

    $classes = trim($base.' '.$state);
@endphp

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

@props([
    'name' => null,
    'label' => null,
    'hint' => null,
    'required' => false,
    'disabled' => false,
    'orientation' => 'vertical',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $radioGroup = $styles['radioGroup'];
    $resolvedOrientation = in_array($orientation, ['vertical', 'horizontal'], true) ? $orientation : 'vertical';

    $bag = ($errors ?? null) instanceof \Illuminate\Support\ViewErrorBag ? $errors : null;
    $message = ($bag && filled($name)) ? $bag->first($name) : null;
    $hasError = filled($message);
    $descriptionId = filled($name) && filled($hint) && ! $hasError ? $name.'-description' : null;
    $errorId = filled($name) && $hasError ? $name.'-error' : null;
    $describedBy = $errorId ?? $descriptionId;
@endphp

<fieldset
    data-slot="radio-group"
    data-orientation="{{ $resolvedOrientation }}"
    @if ($hasError) data-invalid="true" @endif
    @if (filled($describedBy)) aria-describedby="{{ $describedBy }}" @endif
    @disabled($disabled)
    {{ $attributes->except('name')->merge(['class' => $radioGroup['root']]) }}
>
    @if (filled($label))
        <legend data-slot="radio-group-label" class="text-sm font-medium leading-none text-foreground">
            {{ __($label) }}
            @if ($required)
                <span class="text-destructive" aria-hidden="true">*</span>
                <span class="sr-only">{{ __('(required)') }}</span>
            @endif
        </legend>
    @endif

    <div data-slot="radio-group-items" class="{{ $radioGroup['items'][$resolvedOrientation] }}">
        {{ $slot }}
    </div>

    @if ($hasError)
        <p data-slot="radio-group-error" id="{{ $errorId }}" role="alert" class="break-words text-sm font-medium text-destructive">
            {{ $message }}
        </p>
    @elseif (filled($hint))
        <p data-slot="radio-group-description" @if ($descriptionId) id="{{ $descriptionId }}" @endif class="break-words text-sm text-muted-foreground">
            {{ __($hint) }}
        </p>
    @endif
</fieldset>