List Toolbar

# Brok UI: List Toolbar (`admin-list-toolbar`)

One GET form of the controls that apply to a whole list — search, a date-window select with an inline custom range, saved views, a reset link when modified, and an export/tools cluster.

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

## Install

```bash
php artisan ui:add admin-list-toolbar
```

## Usage

```blade
<div class="w-full">
    <x-ui.admin.list-toolbar />
</div>
```

## Props

- `action` (string|null, default `null`) — GET target; empty submits to the current URL.
- `searchValue` (string, default ``) — Current search text.
- `searchName` (string, default `q`) — Search input name.
- `searchPlaceholder` (string|null, default `null`) — Search placeholder.
- `window` (string|null, default `null`) — Active window key; defaults to the second preset.
- `windowName` (string, default `window`) — Window select name; the custom range posts as `<windowName>_start`/`_end`.
- `windows` (array|null, default `null`) — [['key','label']] presets; `custom` is appended.
- `windowFrom` (string, default ``) — Custom range start.
- `windowTo` (string, default ``) — Custom range end.
- `views` (array, default `[]`) — The saved-views `views` array.
- `viewsMode` ('tabs'|'menu', default `tabs`) — Saved-views mode.
- `modified` (bool, default `false`) — Whether the list differs from its default view; shows the reset link.
- `resetHref` (string|null, default `null`) — Reset link target; defaults to `?`.
- `exportHref` (string|null, default `null`) — Export link; `#` sample when omitted.
- `exportLabel` (string|null, default `null`) — Export label.
- `hidden` (array, default `[]`) — [['name','value']] hidden inputs so a resubmit keeps filter state.

## Use when

- Use when the option set is long enough that search, suggestion, or filtering speeds selection.
- The row above an admin table: views choose which rows, this row refines how, column headers own field filters.
- Search and the date window must survive as URL state (a shareable, back-button-safe list).

## Avoid when

- Do not use advanced selection UI when a simpler visible control would be clearer.
- Faceted per-field filters — use `filters` beside it.
- A client-only list that never round-trips — bind your own controls to the list state.

## Anti-patterns

- Using advanced search for a tiny list

## Rules

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

{{--
    List Toolbar — the controls that apply to the whole list: search, the
    date window, which saved view you are in, a way back to the default,
    and the page-level tools (export) on the end side.

    The split is deliberate and the same on every list: views choose WHICH
    rows you are looking at, the toolbar refines HOW, and field filters live
    on the column headers where the data is. This row never grows a filter
    per column; that is what the applied-filters readout and the table's
    own header menus are for.

    The date window is a select of presets plus "Custom…", which reveals a
    start/end pair inline instead of in a popover: the whole row is one GET
    form, so a teleported panel would fall outside it. The reset link is
    rendered only when the list is `modified`, because a control that does
    nothing teaches the operator to stop reading the row.

    Generalised from the Noord-C admin's `toolbar.blade.php`, copied into
    twenty-five modules; belongs in `<x-slot:toolbar>` of an admin table.
--}}
@props([
    'action' => null,
    'searchValue' => '',
    'searchName' => 'q',
    'searchPlaceholder' => null,
    'window' => null,
    'windowName' => 'window',
    'windows' => null,
    'windowFrom' => '',
    'windowTo' => '',
    'views' => [],
    'viewsMode' => 'tabs',
    'modified' => false,
    'resetHref' => null,
    'exportHref' => null,
    'exportLabel' => null,
    'hidden' => [],
])

@php
    // Shapes documented in item.json knowledge.props:
    //   windows: [['key' => '30d', 'label' => 'Last 30 days']] — presets; a `custom` entry is appended automatically.
    //   views: the saved-views `views` array (href XOR event per view).
    //   hidden: [['name' => 'status', 'value' => 'paid']] — filter state to carry through a resubmit so search never drops a filter.
    $searchPlaceholder ??= __('Search by number, name, or email…');
    $windows ??= [
        ['key' => '7d', 'label' => __('Last 7 days')],
        ['key' => '30d', 'label' => __('Last 30 days')],
        ['key' => '90d', 'label' => __('Last 90 days')],
        ['key' => 'ytd', 'label' => __('This year')],
        ['key' => 'all', 'label' => __('All time')],
    ];
    $window ??= $windows[1]['key'] ?? 'all';
    $windows = collect($windows)->filter(fn ($entry) => is_array($entry))->push(['key' => 'custom', 'label' => __('Custom…')])->values();

    $views = $views !== [] ? $views : [
        ['key' => 'recent', 'label' => __('Recent activity'), 'href' => '?view=recent', 'active' => true, 'system' => true],
        ['key' => 'attention', 'label' => __('Needs attention'), 'href' => '?view=attention', 'count' => 9, 'tone' => 'attention', 'system' => true],
        ['key' => 'at_risk', 'label' => __('At risk'), 'href' => '?view=at_risk', 'count' => 4, 'system' => true],
    ];

    $exportLabel ??= __('Export');
    $exportHref ??= '#';
    $resetHref ??= '?';
@endphp

<form
    method="GET"
    action="{{ $action ?? '' }}"
    data-slot="list-toolbar"
    data-surface="admin"
    x-data="{ window: @js($window) }"
    {{ $attributes->merge(['class' => 'flex min-w-0 flex-wrap items-center gap-2']) }}
>
    @foreach ($hidden as $field)
        <input type="hidden" name="{{ $field['name'] ?? '' }}" value="{{ $field['value'] ?? '' }}" />
    @endforeach

    @isset($search)
        {{ $search }}
    @else
        <label class="min-w-0 flex-1 basis-64 sm:max-w-xs">
            <span class="sr-only">{{ __('Search') }}</span>
            <x-ui.input type="search" :name="$searchName" :value="$searchValue" :placeholder="$searchPlaceholder" autocomplete="off" enterkeyhint="search" />
        </label>
    @endisset

    <div class="flex min-w-0 flex-wrap items-center gap-2">
        <label class="min-w-0">
            <span class="sr-only">{{ __('Date window') }}</span>
            <x-ui.select :name="$windowName" x-model="window" x-on:change="if (window !== 'custom') $el.form.requestSubmit()">
                @foreach ($windows as $option)
                    <option value="{{ $option['key'] }}" @selected($option['key'] === $window)>{{ $option['label'] }}</option>
                @endforeach
            </x-ui.select>
        </label>

        <div x-show="window === 'custom'" x-cloak class="flex min-w-0 flex-wrap items-center gap-2">
            <div class="min-w-0 basis-64">
                <x-ui.date-range-picker :name="$windowName" :start-value="$windowFrom" :end-value="$windowTo" />
            </div>
            <x-ui.button type="submit" variant="secondary" size="sm">{{ __('Apply') }}</x-ui.button>
        </div>
    </div>

    @if ($views !== [])
        <x-ui.saved-views :views="$views" :mode="$viewsMode" />
    @endif

    <div class="ms-auto flex min-w-0 flex-wrap items-center gap-2">
        @if ($modified)
            <x-ui.button variant="link" size="sm" :href="$resetHref">{{ __('Reset view') }}</x-ui.button>
        @endif

        @isset($tools)
            {{ $tools }}
        @elseif ($exportHref !== null)
            <x-ui.button variant="outline" size="sm" :href="$exportHref">{{ $exportLabel }}</x-ui.button>
        @endisset
    </div>

    <noscript><x-ui.button type="submit" variant="secondary" size="sm">{{ __('Apply') }}</x-ui.button></noscript>
</form>