Swap

# Brok UI: Swap (`swap`)

A button that cross-fades between an 'on' and 'off' named slot (e.g. two icons) with an accessible role="switch" toggle.

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

## Install

```bash
php artisan ui:add swap
```

## Usage

```blade
<div class="flex items-center gap-4">
    <x-ui.swap label="{{ __('Toggle theme') }}">
        <x-slot:on>
            {{-- Sun icon (active / light mode) --}}
            <svg xmlns="http://www.w3.org/2000/svg" class="size-6 text-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
                <path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"/>
                <circle cx="12" cy="12" r="4"/>
            </svg>
        </x-slot:on>
        <x-slot:off>
            {{-- Moon icon (inactive / dark mode) --}}
            <svg xmlns="http://www.w3.org/2000/svg" class="size-6 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
                <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
            </svg>
        </x-slot:off>
    </x-ui.swap>
    <span class="text-sm text-muted-foreground">{{ __('Toggle light / dark') }}</span>
</div>
```

## Props

- `active` (bool, default `false`) — Initial active state; modelable via x-model or wire:model.
- `name` (mixed|null, default `null`) — When set, mirrors the active state into a hidden input for plain form submission.
- `label` (mixed|null, default `null`) — Accessible name for the switch; falls back to a generic label unless aria-label or aria-labelledby is supplied.

## Use when

- Use for immediate state changes that are obvious and reversible.
- Toggling between two icons or short pieces of content, such as sun/moon or play/pause, with a cross-fade.
- Needing a single-button role="switch" that can bind with x-model or wire:model.

## Avoid when

- Do not use for choices that need explanation, confirmation, or a later Save step.
- Toggling a labelled setting with visible on/off text; use switch instead.
- Submitting a boolean form field with no visual swap needed; use checkbox or switch.

## Anti-patterns

- Using a switch when Save is required
- Using a switch for irreversible actions

## Rules

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

@props([
    'active' => false,
    'name'   => null,
    // Accessible name — role="switch" requires one, and both slots are
    // aria-hidden decoration. Pass a meaningful label in context; falls back to
    // a generic name. Skipped when the consumer supplies
    // aria-label/aria-labelledby themselves.
    'label' => null,
])
@php
    $needsName = $label === null && ! $attributes->has('aria-label') && ! $attributes->has('aria-labelledby');
@endphp

{{--
    Swap — toggles between an "on" and "off" named slot with a cross-fade
    transition. Works as a keyboard-accessible role="switch" button.

    Named slots: $on (shown when active), $off (shown when inactive).
    Prop `name`: when set, a hidden input mirrors the active state for forms.
--}}
<button
    type="button"
    x-data="uiSwap({ active: @js((bool) $active) })"
    {{-- Modelable: `x-model` (Alpine) and `wire:model` (Livewire binds through
         the same x-model contract) attach to the root. Inert without either. --}}
    x-modelable="active"
    data-slot="swap"
    role="switch"
    @if ($label !== null) aria-label="{{ $label }}" @elseif ($needsName) aria-label="{{ __('Toggle') }}" @endif
    :aria-checked="active.toString()"
    @click="toggle()"
    @keydown.enter.prevent="toggle()"
    @keydown.space.prevent="toggle()"
    tabindex="0"
    {{ $attributes->merge(['class' => 'relative inline-grid cursor-pointer select-none place-items-center focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50']) }}
>
    {{-- "on" state --}}
    <span
        x-show="active"
        x-transition:enter="transition duration-200 motion-reduce:transition-none"
        x-transition:enter-start="opacity-0 scale-75"
        x-transition:enter-end="opacity-100 scale-100"
        x-transition:leave="transition duration-150 motion-reduce:transition-none"
        x-transition:leave-start="opacity-100 scale-100"
        x-transition:leave-end="opacity-0 scale-75"
        class="col-start-1 row-start-1"
        aria-hidden="true"
    >@isset($on){{ $on }}@else<svg xmlns="http://www.w3.org/2000/svg" class="size-6" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"/><circle cx="12" cy="12" r="4"/></svg>@endisset</span>

    {{-- "off" state --}}
    <span
        x-show="!active"
        x-transition:enter="transition duration-200 motion-reduce:transition-none"
        x-transition:enter-start="opacity-0 scale-75"
        x-transition:enter-end="opacity-100 scale-100"
        x-transition:leave="transition duration-150 motion-reduce:transition-none"
        x-transition:leave-start="opacity-100 scale-100"
        x-transition:leave-end="opacity-0 scale-75"
        class="col-start-1 row-start-1"
        aria-hidden="true"
    >@isset($off){{ $off }}@else<svg xmlns="http://www.w3.org/2000/svg" class="size-6" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>@endisset</span>

    @if ($name)
        <input type="hidden" :name="@js($name)" :value="active ? '1' : '0'" />
    @endif
</button>