Command

# Brok UI: Command (`command`)

A filterable, keyboard-navigable command palette for server-authorized commands with stable action keys, disabled reasons, grouped links, shortcuts, and empty-state handling.

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

## Install

```bash
php artisan ui:add command
```

## Usage

```blade
<x-ui.command class="w-full max-w-md">
    <x-ui.command.input :placeholder="__('Type a command or search…')" />
    <x-ui.command.list>
        <x-ui.command.empty>{{ __('No results found.') }}</x-ui.command.empty>
        <x-ui.command.item value="calendar">{{ __('Calendar') }}</x-ui.command.item>
        <x-ui.command.item value="search-emoji">{{ __('Search Emoji') }}</x-ui.command.item>
        <x-ui.command.item value="calculator">{{ __('Calculator') }}</x-ui.command.item>
        <x-ui.command.item value="profile">{{ __('Profile') }}</x-ui.command.item>
        <x-ui.command.item value="settings">{{ __('Settings') }}</x-ui.command.item>
    </x-ui.command.list>
</x-ui.command>
```

## Props

- `resetOnSelect` (bool, default `true`) — Clear the typed query once an item is chosen. Set false for a list that stays open and keeps its filter.
- `filter` (bool, default `true`) — Filter items client-side against the typed query. Set false when the host already returns only matching hits (a debounced server search); the keyboard model still covers every item.
- `clearOnEscape` (bool, default `true`) — Escape clears a typed query first and closes a wrapping dialog on the next press. Set false to close on the first Escape even with text typed; the query clears as the dialog closes.
- `field` (bool, default `false`) — Field mode: no palette surface. The input renders as a standalone search field and the host places the list (a floating popover under the field), as record-search does.
- `hotkey` (string|null, default `null`) — Opt-in global shortcut registered with the hotkey registry, for example 'mod+k' (Cmd+K on macOS, Ctrl+K elsewhere). Inside a dialog it opens and closes that dialog; an inline palette focuses its input. Fires while typing; blocked by any other open modal.
- `hotkeyDescription` (string, default `Open command palette`) — Description of the shortcut in the hotkeys help list.
- `hotkeyGroup` (string, default `General`) — Group of the shortcut in the hotkeys help list.
- `match` (substring|fuzzy, default `substring`) — How the typed query matches an item: substring keeps items whose search text contains the query; fuzzy keeps items that contain every word of the query in order, with gaps allowed ("gs" finds "Go to settings").
- `rank` (bool, default `false`) — Opt-in ranking. While a query is typed, matching items show best first: the whole query as a phrase on word boundaries, then every word as a whole word, then word prefixes, then substrings, then scattered fuzzy matches (match="fuzzy"); ties keep document order. Items rank within their group and groups order by their best item; persistent rows and the actions footer stay last, server-mode sequenced results keep the host order, and an empty query shows document order. The reorder is visual (CSS order on a flex list and groups), so the DOM, Livewire morphs and x-for rows are untouched, and the arrow keys, Home/End and the first active option follow what is on screen. Give every group separator so the divider follows the visual order.
- `recent` (string|null, default `null`) — A localStorage key. When set, chosen items are remembered (newest first) and listed in a Recent group at the top of <x-ui.command.list> while nothing is typed. A recent row activates the original item; when it is no longer rendered, its remembered link is followed or command-select fires with its value.
- `recentMax` (int, default `5`) — How many recent items are kept.
- `recentHeading` (string, default `Recent`) — Heading of the Recent group (translated with __()).
- `server` (bool, default `false`) — Server mode: a query change dispatches command-search { query, sequence, done(), fail(message), isCurrent() } after debounce ms. Until done() the list is busy (aria-busy, a loading row, a polite status). Off: the palette filters in the browser as before.
- `debounce` (int, default `200`) — Server mode: milliseconds after the last query change before command-search is dispatched.
- `loadingText` (string|null, default `null`) — Server mode: loading row and status text; null uses the translated "Searching…".
- `errorText` (string|null, default `null`) — Server mode: text shown when the host calls fail() without a message; null uses the translated default.
- `disabled` (false|true, default `false`) — Documented catalog control used by the preview workbench.
- `placeholder` (mixed, default `__('Type a command or search…')`) — Declared by @props in the registry Blade source.
- `expanded` (string, default `true`) — Declared by @props in the registry Blade source.
- `actionsLabel` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `value` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `actionKey` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `keywords` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `href` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `disabledReason` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `valueExpr` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `keywordsExpr` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `selectedExpr` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `persistent` (bool, default `false`) — Declared by @props in the registry Blade source.
- `heading` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `separator` (bool, default `false`) — Declared by @props in the registry Blade source.
- `keys` (array, default `[]`) — Declared by @props in the registry Blade source.
- `sequence` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `sequenceExpr` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `removable` (bool, default `true`) — Declared by @props in the registry Blade source.
- `hints` (array, default `[]`) — Declared by @props in the registry Blade source.

## Use when

- Use when the option set is long enough that search, suggestion, or filtering speeds selection.
- Users need to search and invoke actions from a keyboard-friendly palette.
- A long action or navigation list benefits from client-side filtering and grouping.
- A search asks the server (Livewire or fetch) for results as the user types; use server mode.

## Avoid when

- Do not use advanced selection UI when a simpler visible control would be clearer.
- The user is choosing a form value; use combobox or select-advanced.
- There are only a few always-visible actions; use buttons or a menu.

## Anti-patterns

- Using advanced search for a tiny list

## Rules

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

{{--
    Command palette (spec §17 + §19). A filterable, keyboard-navigable list.
    Type to filter items, ArrowUp/Down to move the active option, Enter to
    activate it. Escape clears a typed query; with nothing typed (or with
    clear-on-escape off) it closes a wrapping <x-ui.dialog>. Inside a dialog the query is cleared whenever the
    dialog closes, so the palette reopens empty. Works standalone or inside a
    <x-ui.dialog>.
--}}
@props([
    // Clear the typed query once an item is chosen (a reopened palette starts
    // clean). Set false for a list that stays open and keeps its filter.
    'resetOnSelect' => true,
    // Filter the items client-side against the typed query. Set false when the
    // host already returns only matching hits (a debounced server search) and
    // the query is not expected to appear in an item's text — the keyboard
    // model (active option, Arrow/Home/End/Enter) still applies to every item.
    'filter' => true,
    // Escape clears a typed query first and closes a wrapping dialog on the
    // next press. Set false to close on the first Escape even with text typed
    // (the query clears as the dialog closes), for a palette whose search is
    // only a way to find the item.
    'clearOnEscape' => true,
    // Field mode: no palette surface. The input renders as a standalone
    // search field and the list is left for the host to place (a floating
    // popover under the field), so a search box gets the combobox keyboard
    // model without the palette chrome.
    'field' => false,
    // Global shortcut that opens the palette through the hotkey registry, for
    // example 'mod+k' (Cmd+K on macOS, Ctrl+K elsewhere). Inside a
    // dialog it opens (and, pressed again, closes) that dialog; an
    // inline palette focuses its input. Off by default. Another open modal
    // blocks it, so it never acts behind a focus trap.
    'hotkey' => null,
    // Help-list description and group for the shortcut.
    'hotkeyDescription' => 'Open command palette',
    'hotkeyGroup' => 'General',
    // How the typed query matches an item: 'substring' (default) or 'fuzzy'
    // (every word of the query in order, gaps allowed: "gp" finds "Go to
    // projects").
    'match' => 'substring',
    // Opt-in ranking: while a query is typed, matching items show best first
    // (the query as a phrase, then whole words, word prefixes, substrings and
    // scattered fuzzy matches), within each group, and groups order by their
    // best item. Ties, an empty query, persistent rows, the actions footer and
    // server-mode results keep document order. Visual only: the DOM stays.
    'rank' => false,
    // Remember chosen items under this localStorage key and list them in a
    // Recent group at the top of the command list while nothing is typed.
    // Off by default.
    'recent' => null,
    'recentMax' => 5,
    'recentHeading' => 'Recent',
    // Server mode: the host supplies the results. A query change dispatches
    // `command-search` { query, sequence, done(), fail(message), isCurrent() }
    // after `debounce` ms; until done() the list is busy (aria-busy, a
    // loading row and a polite status). Results rendered in a
    // command.group with `sequence` show only for the latest query and skip
    // the browser filter. Off by default: the palette filters in the browser.
    'server' => false,
    'debounce' => 200,
    // Loading row and status text while an answer is on its way.
    'loadingText' => null,
    // Row shown when the host calls fail() without a message.
    'errorText' => null,
])

@php
    $match = $match === 'fuzzy' ? 'fuzzy' : 'substring';
    $searchTexts = $server ? [
        'loading' => $loadingText ?? __('Searching…'),
        'error' => $errorText ?? __('The search failed. Try again.'),
        'empty' => __('No results found.'),
        'one' => __('1 result'),
        'many' => __(':count results'),
    ] : [];
    $surface = $field
        ? 'relative w-full text-foreground'
        : 'flex w-full flex-col overflow-hidden rounded-lg border border-border bg-popover text-popover-foreground';
    $rank = filter_var($rank, FILTER_VALIDATE_BOOLEAN);
    // Ranking reorders rows with CSS `order`, so the list and its groups are
    // flex columns whose rows never shrink, and the actions footer stays last.
    if ($rank) {
        $surface .= ' [&_[data-slot=command-list]]:flex [&_[data-slot=command-list]]:flex-col [&_[data-slot=command-list]>*]:shrink-0 [&_[data-slot=command-group]]:flex [&_[data-slot=command-group]]:flex-col [&_[data-slot=command-group]>*]:shrink-0 [&_[data-slot=command-actions]]:order-last';
    }
@endphp

<div
    x-data="uiCommand({ resetOnSelect: {{ \Illuminate\Support\Js::from((bool) $resetOnSelect) }}, filter: {{ \Illuminate\Support\Js::from((bool) $filter) }}, clearOnEscape: {{ \Illuminate\Support\Js::from((bool) $clearOnEscape) }}, match: @js($match){{ $rank ? ', rank: true' : '' }}{{ filled($recent) ? ', recent: '.\Illuminate\Support\Js::from((string) $recent).', recentMax: '.max(1, (int) $recentMax) : '' }}@if (filled($hotkey)), hotkey: {{ \Illuminate\Support\Js::from((string) $hotkey) }}, hotkeyDescription: {{ \Illuminate\Support\Js::from(__($hotkeyDescription)) }}, hotkeyGroup: {{ \Illuminate\Support\Js::from(__($hotkeyGroup)) }}@endif @if ($server), server: true, debounce: {{ max(0, (int) $debounce) }}, texts: {{ \Illuminate\Support\Js::from($searchTexts) }}@endif })"
    x-id="['command-list']"
    data-slot="command"
    data-authorization="server-filtered"
    @if ($field) data-field @endif
    @if (filled($hotkey)) data-hotkey="{{ $hotkey }}" @endif
    data-match="{{ $match }}"
    @if ($rank) data-rank @endif
    @if (filled($recent)) data-recent="{{ $recent }}" @endif
    @if ($server) data-server x-bind:data-busy="busy ? 'true' : 'false'" @endif
    @keydown.escape="onEscape($event)"
    @keydown.down.prevent="move(1)"
    @keydown.up.prevent="move(-1)"
    @keydown.enter="choose($event)"
    @keydown.home.prevent="moveTo(0)"
    @keydown.end.prevent="moveTo(-1)"
    {{ $attributes->merge(['class' => $surface]) }}
>
    {{ $slot }}
    @if ($server)
        {{-- Outside the listbox: announces loading, the result count and a failure. --}}
        <div data-slot="command-status" role="status" aria-live="polite" aria-atomic="true" class="sr-only" x-text="statusText"></div>
    @endif
</div>

@aware([
    'field' => false,
])

@props([
    'placeholder' => __('Type a command or search…'),
    // Alpine expression for aria-expanded. A palette's list is always shown;
    // a field-mode host whose list floats in a popover binds it to that
    // popover's open state so the combobox reports the truth.
    'expanded' => 'true',
])

@php
    // A host composing this input under its own name (record-search) passes
    // `data-slot`; the browser keeps only the first of two identical
    // attributes, so read the override out of the bag and print exactly one.
    // Same for `type`: a search field is `type="search"`.
    $slotName = (string) ($attributes->get('data-slot') ?: 'command-input');
    $type = (string) ($attributes->get('type') ?: 'text');

    $wrapperClass = $field
        ? 'relative'
        : 'flex items-center gap-2 border-b border-border px-3';
    $iconClass = $field
        ? 'pointer-events-none absolute inset-y-0 start-0 flex items-center ps-3 text-muted-foreground'
        : 'shrink-0 text-muted-foreground';
    $inputClass = $field
        ? 'h-10 w-full min-w-0 rounded-md border border-input bg-background ps-9 pe-9 text-sm text-foreground shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring focus-visible:ring-offset-[length:var(--ring-offset-width)] focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50'
        : 'h-control-h-md w-full min-w-0 bg-transparent text-sm text-foreground outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50';
@endphp

<div data-slot="command-input-wrapper" class="{{ $wrapperClass }}">
    <span class="{{ $iconClass }}" aria-hidden="true">
        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4">
            <circle cx="11" cy="11" r="8" />
            <path d="m21 21-4.3-4.3" />
        </svg>
    </span>
    {{-- Context chips (<x-ui.command.chip>) sit before the text field. --}}
    {{ $slot }}
    <input
        type="{{ $type }}"
        data-slot="{{ $slotName }}"
        role="combobox"
        aria-autocomplete="list"
        :aria-expanded="{{ $expanded }}"
        x-bind:aria-controls="$id('command-list')"
        x-bind:aria-activedescendant="({{ $expanded }}) ? activeId() : null"
        x-model="query"
        @input="reset()"
        @keydown.backspace="onBackspace($event)"
        placeholder="{{ $placeholder }}"
        autocomplete="off"
        {{ $attributes->except(['data-slot', 'type'])->merge(['class' => $inputClass]) }}
    />
</div>

@aware([
    'recent' => null,
    'recentHeading' => 'Recent',
    'server' => false,
])

@props([
    // Name of the `actions` footer group. Null: the translated "Actions".
    'actionsLabel' => null,
])

@php($recentId = 'command-recent-'.\Illuminate\Support\Str::random(6))

<div
    data-slot="command-list"
    role="listbox"
    x-ref="list"
    x-bind:id="$id('command-list')"
    @if ($server) x-bind:aria-busy="busy ? 'true' : 'false'" @endif
    {{ $attributes->merge(['class' => 'max-h-72 overflow-y-auto overflow-x-hidden p-1']) }}
>
    @if (filled($recent))
        {{-- Recent: the palette's remembered choices, newest first, shown
             only while nothing is typed. A row activates the original item. --}}
        <div data-slot="command-group" data-recent role="group" aria-labelledby="{{ $recentId }}" x-show="showRecent()" style="display: none" class="overflow-hidden">
            <div id="{{ $recentId }}" data-slot="command-group-heading" class="px-2 py-2 text-xs font-medium text-muted-foreground select-none">{{ __($recentHeading) }}</div>
            <template x-for="entry in recentEntries" :key="'recent:' + entry.value">
                <button
                    type="button"
                    role="option"
                    data-slot="command-item"
                    data-recent
                    x-bind:id="$id('command-list') + '-item-' + encodeId('recent:' + entry.value)"
                    x-bind:data-value="'recent:' + entry.value"
                    x-init="registerItem('recent:' + entry.value, '', true, $el)"
                    :aria-selected="active === 'recent:' + entry.value"
                    :data-active="active === 'recent:' + entry.value"
                    @click="chooseRecent(entry)"
                    @mousemove="active = 'recent:' + entry.value"
                    class="flex w-full cursor-pointer items-center gap-2 rounded-sm px-2 py-2 text-start text-sm text-popover-foreground outline-none transition-colors data-[active=true]:bg-accent data-[active=true]:text-accent-foreground motion-reduce:transition-none"
                >
                    <svg aria-hidden="true" class="size-4 shrink-0 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9" /><path d="M12 7v5l3 2" /></svg>
                    <span class="min-w-0 truncate" x-text="entry.label"></span>
                </button>
            </template>
        </div>
    @endif
    {{ $slot }}
    @if ($server)
        {{-- The status region on the command root announces these rows. --}}
        <div data-slot="command-loading" role="presentation" x-show="busy" x-cloak class="flex items-center gap-2 px-2 py-2 text-sm text-muted-foreground">
            <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" class="size-4 shrink-0 motion-safe:animate-spin">
                <path d="M21 12a9 9 0 1 1-6.2-8.56" />
            </svg>
            <span x-text="texts.loading"></span>
        </div>
        <div data-slot="command-error" role="presentation" x-show="!busy && error !== ''" x-cloak class="px-2 py-6 text-center text-sm text-muted-foreground" x-text="error"></div>
    @endif
    @isset($actions)
        {{-- Footer actions ("Create …"): command.item rows (usually persistent)
             in a named group that stays at the bottom while the list scrolls.
             They are options, so the arrow keys and Enter reach them. --}}
        <div data-slot="command-actions" role="group" aria-label="{{ filled($actionsLabel) ? $actionsLabel : __('Actions') }}" class="sticky bottom-0 mt-1 border-t border-border bg-popover pt-1">
            {{ $actions }}
        </div>
    @endisset
</div>

@aware([
    'rank' => false,
])

@props([
    'value' => null,
    'actionKey' => null,
    'keywords' => null,
    'href' => null,
    'disabled' => false,
    'disabledReason' => null,
    // Client data: Alpine expressions for the value and the search text, for
    // an item rendered inside `<template x-for>` (`value-expr="hit.id"`,
    // `keywords-expr="hit.title + ' ' + hit.team"`). They replace `value`,
    // `action-key` and `keywords`; the search text defaults to the value.
    'valueExpr' => null,
    'keywordsExpr' => null,
    // Alpine expression for aria-selected. Null: the active option is the
    // selected one (a palette). A picker passes its own selection
    // (`selected-expr="isPicked('high')"`), so aria-selected reports the
    // chosen values while data-active keeps showing the keyboard position.
    'selectedExpr' => null,
    // Always shown, whatever the query: an action row such as "Create …" in
    // the list's `actions` footer. It stays an option (arrow keys, Enter).
    'persistent' => false,
])

@php($dynamic = filled($valueExpr))
@php($search = $keywords ?? $value)
@php($key = filled($actionKey) ? (string) $actionKey : (string) $value)
@php($encoded = preg_replace('/[^a-zA-Z0-9_-]/', '-', $key))
@php($keyExpr = $dynamic ? '('.$valueExpr.')' : null)
@php($searchExpr = $dynamic ? (filled($keywordsExpr) ? '('.$keywordsExpr.')' : $keyExpr) : null)

@php($tag = filled($href) ? 'a' : 'button')
@php($ranked = filter_var($rank, FILTER_VALIDATE_BOOLEAN))

<{{ $tag }}
    @if ($tag === 'button') type="button" @disabled($disabled) @elseif (! $disabled) href="{{ $href }}" @else tabindex="-1" @endif
    data-slot="command-item"
    role="option"
    @if ($persistent) data-persistent @endif
@if ($dynamic)
    x-bind:id="$id('command-list') + '-item-' + encodeId({{ $keyExpr }})"
    x-bind:data-value="{{ $keyExpr }}"
    x-bind:data-action-key="{{ $keyExpr }}"
    x-init="registerItem({{ $keyExpr }}, {{ $searchExpr }}, @js(! $disabled), $el)"
    x-show="matches({{ $searchExpr }}, $el)"
    @if ($ranked) x-bind:style="rankStyle($el, {{ $searchExpr }})" @endif
    @if (filled($selectedExpr)) :aria-selected="({{ $selectedExpr }}) ? 'true' : 'false'" @else :aria-selected="active === {{ $keyExpr }}" @endif
    :data-active="active === {{ $keyExpr }}"
    @if ($disabled) aria-disabled="true" title="{{ $disabledReason }}" @else @click="select({{ $keyExpr }})" @mousemove="active = {{ $keyExpr }}" @endif
@else
    x-bind:id="$id('command-list') + '-item-' + @js($encoded)"
    data-value="{{ $key }}"
    data-action-key="{{ $key }}"
    x-init="registerItem(@js($key), @js($search), @js(! $disabled), $el)"
    x-show="matches(@js($search), $el)"
    @if ($ranked) x-bind:style="rankStyle($el, @js($search))" @endif
    @if (filled($selectedExpr)) :aria-selected="({{ $selectedExpr }}) ? 'true' : 'false'" @else :aria-selected="active === @js($key)" @endif
    :data-active="active === @js($key)"
    @if ($disabled) aria-disabled="true" title="{{ $disabledReason }}" @else @click="select(@js($key))" @mousemove="active = @js($key)" @endif
@endif
    {{ $attributes->merge(['class' => 'flex w-full cursor-pointer items-center gap-2 rounded-sm px-2 py-2 text-start text-sm text-popover-foreground outline-none transition-colors data-[active=true]:bg-accent data-[active=true]:text-accent-foreground disabled:cursor-not-allowed disabled:opacity-50 aria-disabled:cursor-not-allowed aria-disabled:opacity-50']) }}
>
    {{ $slot }}
</{{ $tag }}>

@aware([
    'rank' => false,
])

@props([
    // Visible label for the group, rendered above its items.
    'heading' => null,
    // Render a top divider before this group (set on the 2nd+ group).
    'separator' => false,
    // The searchable strings of this group's items (their `value` or
    // `keywords`). Lets the whole group hide once every child is filtered out,
    // so a stale heading never floats above an empty region. Optional — when
    // omitted the group is always shown.
    'keys' => [],
    // Server mode: the sequence number of the answer this group belongs to
    // (from the command-search event). The group and its items show, take
    // keys and skip the browser filter only while it is the latest number,
    // so a late, older answer never shows. Key the group on it
    // (a wire:key that contains the number) so a render replaces its
    // options in one step.
    'sequence' => null,
    // Client data: an Alpine expression for the sequence number of the
    // answer on screen (sequence-expr="answer.sequence"), for results a
    // fetch put in Alpine state.
    'sequenceExpr' => null,
])

@php
    $labelId = 'command-group-'.\Illuminate\Support\Str::random(6);
    $keysCheck = empty($keys) ? null : 'groupMatches('.\Illuminate\Support\Js::from(array_values($keys)).')';
    $sequenced = $sequence !== null || filled($sequenceExpr);
    // A sequenced group shows for the latest answer, and only with results.
    $visibleWhen = implode(' && ', array_filter([$sequenced ? 'isCurrent($el) && hasItemsIn($el)' : null, $keysCheck]));
@endphp

<div
    data-slot="command-group"
    role="group"
    @if ($heading) aria-labelledby="{{ $labelId }}" @endif
    @if ($sequenced) data-sequenced @endif
    @if ($sequenced || ! empty($keys)) x-show="{{ $visibleWhen }}" @endif
    @if (! empty($keys)) data-keys="{{ json_encode(array_values($keys)) }}" @endif
    @if (filter_var($rank, FILTER_VALIDATE_BOOLEAN)) x-bind:style="groupRankStyle($el)" @endif
    {{ $attributes->merge(['class' => 'overflow-hidden']) }}
>
    @if ($sequenced)
        {{-- The answer's number, on a child without x-show, so a render updates it. --}}
        <span data-slot="command-sequence" hidden @if (filled($sequenceExpr)) x-bind:data-sequence="{{ $sequenceExpr }}" @else data-sequence="{{ (int) $sequence }}" @endif></span>
    @endif
    @if ($separator)
        {{-- Only between two visible groups: once the group above filters out,
             the line would otherwise sit directly under the input. --}}
        <div data-slot="command-separator" role="none" x-show="hasVisibleGroupBefore($el.parentElement)" class="-mx-1 my-1 h-px bg-border"></div>
    @endif

    @if ($heading)
        <div id="{{ $labelId }}" data-slot="command-group-heading" class="px-2 py-2 text-xs font-medium text-muted-foreground select-none">
            {{ $heading }}
        </div>
    @endif

    {{ $slot }}
</div>

@props([
    // A registry key string ("mod+k", "g p"). When set, the hint renders
    // through the hotkeys hint: platform labels (⌘ on macOS, Ctrl
    // elsewhere) and the "then" step of a sequence. The slot stays the
    // free-text fallback.
    'keys' => null,
])

{{-- Decorative (aria-hidden): the item's own text names the action. --}}
@if (filled($keys))
    <span
        data-slot="command-shortcut"
        dir="ltr"
        data-keys="{{ $keys }}"
        aria-hidden="true"
        {{ $attributes->merge(['class' => 'ms-auto inline-flex shrink-0 items-center text-muted-foreground']) }}
    ><x-ui.hotkeys.hint :keys="(string) $keys" /></span>
@else
    <span
        data-slot="command-shortcut"
        dir="ltr"
        aria-hidden="true"
        {{ $attributes->merge(['class' => 'ms-auto text-xs tracking-widest text-muted-foreground']) }}
    >
        {{ $slot }}
    </span>
@endif

@props([
    // Value sent with `command-chip-remove`, so a host with several chips
    // knows which one to drop.
    'value' => null,
    // Show the remove button. A chip the user cannot drop (a fixed scope)
    // passes false; Backspace then skips it.
    'removable' => true,
])

{{--
    Context chip in the palette input, such as "2 selected" or the focused
    task. Place it in <x-ui.command.input>'s slot, before the text field.
    Removing it (its button, or Backspace in an empty query) dispatches
    `command-chip-remove` { value } from the chip; the host drops its own
    state and stops rendering the chip (x-show, x-if or @if).
--}}
<span
    data-slot="command-chip"
    @if ($removable) data-removable @endif
    @if (filled($value)) data-value="{{ $value }}" @endif
    {{ $attributes->merge(['class' => 'inline-flex h-6 min-w-0 max-w-48 shrink-0 items-center gap-1 rounded-sm border border-border bg-muted ps-2 text-xs font-medium text-foreground '.($removable ? 'pe-0.5' : 'pe-2')]) }}
>
    <span data-slot="command-chip-label" class="min-w-0 truncate">{{ $slot }}</span>
    @if ($removable)
        <button
            type="button"
            data-slot="command-chip-remove"
            x-on:click="removeChip($el.closest('[data-slot=command-chip]'))"
            class="inline-flex size-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring motion-reduce:transition-none"
        >
            <span class="sr-only">{{ __('Remove :label', ['label' => trim(strip_tags((string) $slot))]) }}</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-3">
                <path d="M18 6 6 18M6 6l12 12" />
            </svg>
        </button>
    @endif
</span>

/**
 * Command palette behavior (spec §17 keyboard + §19 behavior layer).
 *
 * Items register themselves with the root so filtering and navigation are fully
 * reactive (no DOM polling): `query` drives a computed visible list, the active
 * item is tracked by value, and ArrowUp/Down/Home/End/Enter move over the
 * currently visible items only (so navigation skips filtered-out rows).
 *
 * Items rendered from client data (`<template x-for>` with the item's
 * `value-expr`) register the same way. An item unregisters when Alpine removes
 * its element, and navigation follows document order, so a list that is
 * filtered, reordered or replaced on the client never keeps a stale row.
 *
 * Matching (`match`): 'substring' (default) keeps an item when its search
 * text contains the query; 'fuzzy' keeps it when every word of the query
 * appears in order, with gaps allowed ("gp" finds "Go to projects").
 *
 * Ranking (`rank`, opt-in): while a query is typed, matching items show best
 * first instead of in document order. Tiers, best first: (0) the whole query
 * as a phrase on word boundaries; (1) every query word as a whole word;
 * (2) every query word as a word prefix; (3) the query or every word as a
 * substring; (4) a scattered fuzzy match. Ties keep document order. Items
 * rank within their group, and groups order by their best item. Persistent
 * rows, the `actions` footer group and server-mode sequenced regions keep
 * their place (the footer stays last; sequenced results stay in host order).
 * The reorder is visual only (CSS `order` on the flex list and groups), so
 * the DOM, Livewire morphs and `x-for` rows are untouched; the arrow keys,
 * Home/End and the first active option follow the visual order, and clearing
 * the query restores document order. aria-activedescendant names the active
 * option, so a screen reader hears the same item the eye sees.
 *
 * Recent (`recent`: a storage key): each chosen item is remembered in
 * localStorage (newest first, at most `recentMax`) and listed in a Recent
 * group at the top while the query is empty. Choosing a recent row activates
 * the original item (its link or its command-select); when the original is no
 * longer rendered, a remembered link is followed, else command-select fires
 * with the remembered value.
 *
 * Server mode (`server`): the host supplies the results. Every change of the
 * query takes a new sequence number at once and, after `debounce` ms,
 * dispatches `command-search` { query, sequence, done(), fail(message),
 * isCurrent() }. Until done() or fail() comes for the latest number the list
 * is busy (aria-busy, a loading row, a polite status). Groups and items the
 * host renders inside a sequenced region (command.group's
 * `sequence` prop) show, filter and take keys only while that number is the
 * latest, so an older answer that arrives late never shows and never takes
 * Enter; they also skip the browser filter, because the host has filtered.
 *
 * Footer actions: command.list's `actions` slot holds rows such as
 * "Create …" at the bottom of the list. A `persistent` item there matches
 * every query and stays an option for the arrow keys and Enter, but does not
 * count as a result, so the empty row still shows beside it.
 */
const RECENT_PREFIX = 'recent:';

function readRecent(key) {
    try {
        const value = JSON.parse(window.localStorage.getItem(key) || '[]');

        return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.value === 'string') : [];
    } catch {
        return [];
    }
}

function writeRecent(key, entries) {
    try {
        window.localStorage.setItem(key, JSON.stringify(entries));
    } catch {
        // Private mode or a full quota: recent items are simply not kept.
    }
}

function safeHref(href) {
    return typeof href === 'string' && href !== '' && !/^\s*(javascript|data|vbscript):/i.test(href) ? href : null;
}
import './hotkeys.js';
import { documentOrder, fuzzyMatch, rankMethods } from './command-rank.js';

document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiCommand', (config = {}) => ({
        ...rankMethods,
        query: '',
        active: null,
        items: [],
        // Clear the query once an item is chosen, so a palette that is closed
        // and reopened (or reused after an action) starts clean.
        resetOnSelect: config.resetOnSelect ?? true,
        // Client-side filtering of items against `query`. Off when the host
        // already returns only matching hits (a server search): every item
        // then stays visible and the keyboard model covers all of them.
        filter: config.filter ?? true,
        // Escape clears a typed query before it closes. False: Escape is never
        // handled here, so a wrapping dialog closes on the first press and
        // clears the query as it closes (a search used only to find an item).
        clearOnEscape: config.clearOnEscape ?? true,
        matchMode: config.match === 'fuzzy' ? 'fuzzy' : 'substring',
        // Opt-in: order matching items best first while a query is typed.
        rank: config.rank ?? false,
        recentKey: config.recent ? `command-recent:${config.recent}` : null,
        recentMax: Math.max(1, Number(config.recentMax) || 5),
        recentEntries: [],
        hotkeyBinding: null,
        // Server mode: see the header. `sequence` is the number of the latest
        // query; `busy` holds until its answer is done; `error` is the text of
        // a failed answer.
        server: config.server ?? false,
        debounce: config.debounce ?? 200,
        sequence: 0,
        revision: 0,
        busy: false,
        error: '',
        searchTimer: null,
        sequenceObserver: null,
        // True once the arrow keys moved after the last query change, so an
        // arriving answer does not move the active option away from the user.
        movedSinceQuery: false,
        texts: config.texts ?? {},

        /**
         * `hotkey` (opt-in) registers a global shortcut with the hotkey
         * registry. The binding is registered from the palette root, so while
         * the palette's own dialog is on top it stays live (a second press
         * closes it), and any other open modal blocks it. It goes through the
         * store, not x-hotkey, on purpose: the palette is hidden while its
         * dialog is closed, and only store bindings may act on hidden UI.
         */
        init() {
            if (this.recentKey) this.recentEntries = readRecent(this.recentKey).slice(0, this.recentMax);
            this.watchDialog();
            if (this.server) {
                this.$watch('query', (query) => this.queueSearch(query));
                this.observeSequences();
            }
            if (!config.hotkey) return;
            this.hotkeyBinding = this.$store.hotkeys.register(config.hotkey, () => this.toggleFromHotkey(), {
                el: this.$el,
                scope: 'global',
                inputs: true,
                description: config.hotkeyDescription ?? '',
                group: config.hotkeyGroup ?? '',
            });
        },

        /**
         * Inside a dialog, clear the query whenever the dialog closes, however
         * it closes (Escape, backdrop, the hotkey, a link). The palette then
         * always reopens empty, so the first Escape closes it, as in Linear;
         * a typed query is only ever cleared by Escape while it is on screen.
         */
        watchDialog() {
            if (typeof this.show !== 'function' || typeof this.hide !== 'function' || !('open' in this)) return;
            this.$watch('open', (open) => {
                if (open || this.query === '') return;
                this.query = '';
                this.reset();
            });
        },

        destroy() {
            this.hotkeyBinding?.unregister();
            this.hotkeyBinding = null;
            clearTimeout(this.searchTimer);
            this.sequenceObserver?.disconnect();
        },

        /**
         * Server mode: a render can change the sequence marker of an element
         * it keeps (after done() ran), so check the rows again when one changes.
         */
        observeSequences() {
            if (typeof MutationObserver === 'undefined') return;
            this.sequenceObserver = new MutationObserver(() => { this.revision++; });
            this.sequenceObserver.observe(this.$el, { subtree: true, attributes: true, attributeFilter: ['data-sequence'] });
        },

        /**
         * Server mode: a query change makes every earlier answer stale at
         * once (its groups hide and leave the keyboard model) and asks the host
         * for the new one after the debounce.
         */
        queueSearch(query) {
            clearTimeout(this.searchTimer);
            const sequence = ++this.sequence;
            this.busy = true;
            this.error = '';
            this.movedSinceQuery = false;
            this.reset();
            this.searchTimer = setTimeout(() => {
                if (sequence !== this.sequence) return;
                this.$dispatch('command-search', {
                    query: String(query ?? ''),
                    sequence,
                    done: () => this.settle(sequence),
                    fail: (message) => this.settle(sequence, message ?? this.texts.error ?? ''),
                    isCurrent: () => sequence === this.sequence,
                });
            }, Math.max(0, Number(this.debounce) || 0));
        },

        /**
         * The answer for `sequence` arrived (or failed). An older one changes
         * nothing. The active option goes to the first result, unless the
         * arrow keys moved while the answer was on its way.
         */
        settle(sequence, error = null) {
            if (sequence !== this.sequence) return;
            this.busy = false;
            this.error = error === null ? '' : String(error || this.texts.error || '');
            this.$nextTick(() => {
                if (sequence !== this.sequence) return;
                this.revision++;
                // Forget entries whose element a render removed.
                this.items = this.items.filter((item) => !item.el || item.el.isConnected);
                if (!this.movedSinceQuery || !this.visibleValues().includes(this.active)) this.reset();
            });
        },

        /** True for an element outside any sequenced region, or in the latest one. */
        isCurrent(el) {
            // Read the revision too: settle() bumps it after the answer's
            // render, so rows whose data-sequence changed without a new query
            // number (client data, a reused element) are checked again.
            void this.sequence;
            void this.revision;
            const holder = el?.closest?.('[data-sequenced]');
            if (!holder) return true;
            // The number sits on a hidden marker child: Alpine's morph leaves
            // the attributes of an element alone when its x-show state
            // changes, so a number on the shown element itself would not update.
            const marker = holder.querySelector(':scope > [data-sequence]');

            return Number(marker?.dataset.sequence) === this.sequence;
        },

        /** True when a shown item (enabled or not) sits inside `el` (a results group). */
        hasItemsIn(el) {
            return this.items.some((item) => item.el && item.el.isConnected && el.contains(item.el) && this.matches(item.search, item.el));
        },

        /** Polite status text for screen readers in server mode. */
        get statusText() {
            if (!this.server) return '';
            if (this.busy) return this.texts.loading ?? '';
            if (this.error !== '') return this.error;
            if (this.query.trim() === '') return '';
            const count = this.visible().length;
            if (count === 0) return this.texts.empty ?? '';
            if (count === 1) return this.texts.one ?? '';

            return String(this.texts.many ?? '').replace(':count', String(count));
        },

        /**
         * Inside a dialog, Alpine's scope chain exposes the dialog's `open`,
         * `show()` and `hide()`: toggle it, so the dialog keeps owning focus
         * trap, inert background and focus return. An inline palette focuses
         * its input instead. Either way `command-hotkey` is dispatched.
         */
        toggleFromHotkey() {
            this.$dispatch('command-hotkey');
            if (typeof this.show === 'function' && typeof this.hide === 'function') {
                if (this.open) this.hide();
                else this.show();

                return;
            }
            this.$el.querySelector('[data-slot="command-input"]')?.focus();
        },

        registerItem(value, search, enabled = true, el = null) {
            // Items rendered inside a `<template x-if>` register again on every
            // re-render; replace the entry so navigation never steps twice.
            const recent = String(value).startsWith(RECENT_PREFIX) && el?.hasAttribute?.('data-recent');
            const entry = { value, search: String(search ?? '').toLowerCase(), enabled, el, recent };
            const index = this.items.findIndex((item) => item.value === value);
            if (index === -1) this.items.push(entry);
            else this.items.splice(index, 1, entry);
            // Alpine runs this when it removes the element (an x-for row whose
            // data went away, an x-if branch that closed).
            if (el && typeof window.Alpine?.onElRemoved === 'function') {
                window.Alpine.onElRemoved(el, () => this.unregisterItem(value, el));
            }
            if (this.active === null && enabled) {
                this.active = value;
            }
        },

        /**
         * Drop an item. With `el`, only when that element still owns the entry,
         * so a re-rendered row that registered first is kept.
         */
        unregisterItem(value, el = null) {
            const index = this.items.findIndex((item) => item.value === value && (!el || item.el === el));
            if (index === -1) return;
            this.items.splice(index, 1);
            if (this.active === value) this.reset();
        },

        /**
         * Backspace in an empty query removes the last removable context chip
         * (<x-ui.command.chip>), as in a token field.
         */
        onBackspace(event) {
            if (this.query !== '' || event.target.selectionStart !== event.target.selectionEnd) return;
            // $el is the element the handler runs on (the input); $root is the palette.
            const chips = Array.from(this.$root.querySelectorAll('[data-slot="command-chip"][data-removable]'))
                .filter((chip) => chip.getClientRects().length > 0);
            const last = chips[chips.length - 1];
            if (!last) return;
            event.preventDefault();
            this.removeChip(last);
        },

        /** Tell the host to drop a chip, and keep focus in the query field. */
        removeChip(chip) {
            if (!chip) return;
            chip.dispatchEvent(new CustomEvent('command-chip-remove', {
                bubbles: true,
                detail: { value: chip.dataset.value ?? null },
            }));
            this.$root.querySelector('[data-slot="command-input"]')?.focus();
        },

        /**
         * Escape clears a typed query first and keeps the palette open; with
         * nothing typed, or with `clearOnEscape` off, it bubbles on (to a
         * wrapping dialog, which closes on that first press).
         */
        onEscape(event) {
            if (this.query === '' || !this.clearOnEscape) return;
            event.stopPropagation();
            this.query = '';
            this.reset();
        },

        /**
         * With `el`, an item in a stale sequenced region never matches, and one
         * in the latest region skips the browser filter (the host filtered).
         */
        matches(search, el = null) {
            // A persistent row (a footer action) shows whatever the query.
            if (el?.hasAttribute?.('data-persistent')) return true;
            if (el && el.closest?.('[data-sequenced]')) return this.isCurrent(el);
            if (!this.filter) return true;
            const q = this.query.trim().toLowerCase();
            if (q === '') return true;
            const text = String(search).toLowerCase();

            return this.matchMode === 'fuzzy' ? fuzzyMatch(text, q) : text.includes(q);
        },

        /** The Recent group shows only while nothing is typed. */
        showRecent() {
            return this.recentEntries.length > 0 && this.query.trim() === '';
        },

        /** Enabled, matching items in visual order: document order, or ranked (see the header). */
        visible() {
            const shown = this.items
                .filter((item) => item.enabled && (!item.el || item.el.isConnected) && (item.recent ? this.showRecent() : this.matches(item.search, item.el)));
            if (!this.ranking()) {
                return shown.sort((a, b) => (!a.el || !b.el ? 0 : documentOrder(a.el, b.el)));
            }
            return this.sortRanked(shown);
        },

        visibleValues() {
            return this.visible().map((item) => item.value);
        },

        /** True with a matching row; a persistent footer action does not count. */
        get hasResults() {
            return this.visible().some((item) => !item.el?.hasAttribute?.('data-persistent'));
        },

        /** Reset active to the first visible item after the query changes. */
        reset() {
            const values = this.visibleValues();
            this.active = values[0] ?? null;
        },

        move(direction) {
            this.movedSinceQuery = true;
            const values = this.visibleValues();
            if (values.length === 0) {
                this.active = null;
                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();
        },

        moveTo(index) {
            this.movedSinceQuery = true;
            const values = this.visibleValues();
            if (values.length === 0) {
                return;
            }
            this.active = index < 0 ? values[values.length - 1] : values[index];
            this.scrollActiveIntoView();
        },

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

        /**
         * Enter activates the active option. With nothing active the key is
         * left alone, so a focused link the host rendered inside the list (a
         * slot-driven row that never registered) keeps its native Enter.
         */
        choose(event) {
            if (this.active == null) {
                return;
            }
            event?.preventDefault();
            if (!this.visibleValues().includes(this.active)) {
                this.reset();

                return;
            }
            this.$refs.list
                ?.querySelector(`[data-slot="command-item"][data-value="${CSS.escape(this.active)}"]`)
                ?.click();
        },

        /** Remember a chosen item for the Recent group. */
        remember(value) {
            if (!this.recentKey || String(value).startsWith(RECENT_PREFIX)) return;
            const el = this.$refs.list?.querySelector(`[data-slot="command-item"][data-value="${CSS.escape(value)}"]:not([data-recent])`);
            let label = el?.dataset.recentLabel ?? '';
            if (!label && el) {
                const copy = el.cloneNode(true);
                copy.querySelectorAll('[data-slot="command-shortcut"], [aria-hidden="true"]').forEach((node) => node.remove());
                label = copy.textContent.replace(/\s+/g, ' ').trim();
            }
            const entry = { value: String(value), label: label || String(value), href: safeHref(el?.getAttribute('href')) };
            this.recentEntries = [entry, ...this.recentEntries.filter((item) => item.value !== entry.value)].slice(0, this.recentMax);
            writeRecent(this.recentKey, this.recentEntries);
        },

        /** Forget every recent item. */
        clearRecent() {
            this.recentEntries = [];
            if (this.recentKey) writeRecent(this.recentKey, []);
        },

        /** A recent row activates the original item, else its remembered link or value. */
        chooseRecent(entry) {
            const original = this.$refs.list?.querySelector(`[data-slot="command-item"][data-value="${CSS.escape(entry.value)}"]:not([data-recent])`);
            if (original && original.getAttribute('aria-disabled') !== 'true' && !original.disabled) {
                original.click();

                return;
            }
            this.select(entry.value);
            const href = safeHref(entry.href);
            if (href) window.location.assign(href);
        },

        select(value) {
            this.active = value;
            this.remember(value);
            this.$dispatch('command-select', { value, key: value });
            if (this.resetOnSelect && this.query !== '') {
                this.query = '';
                this.reset();
                // Once the Recent rows have rendered, the newest one leads.
                if (this.recentKey) this.$nextTick(() => this.reset());
            }
        },

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

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

        /**
         * True when a group region still has at least one matching item. Lets a
         * <x-ui.command.group> hide its heading/separator once every child is
         * filtered out. Reads `query` so it stays reactive to typing.
         */
        groupMatches(searches) {
            void this.query;
            return (searches || []).some((search) => this.matches(search));
        },

        /**
         * True when a group with matching items precedes `el` in the list, so a
         * group's top divider only shows between two visible groups (never as a
         * stale line under the input once the first group filtered out).
         */
        hasVisibleGroupBefore(el) {
            void this.query;
            const shows = (node) => {
                if (node.dataset.slot !== 'command-group') return false;
                if (node.hasAttribute('data-sequenced') && !this.isCurrent(node)) return false;
                const keys = node.dataset.keys ? JSON.parse(node.dataset.keys) : null;

                return keys === null || this.groupMatches(keys);
            };
            // Ranked: "before" is the visual order (group order, then document order).
            const mine = this.groupOrder(el);
            if (mine !== null) {
                for (const node of el.parentElement.children) {
                    if (node === el || node.hasAttribute('data-recent') || !shows(node)) continue;
                    const order = this.groupOrder(node) ?? 0;
                    if (order < mine || (order === mine && documentOrder(node, el) < 0)) return true;
                }

                return false;
            }
            for (let node = el.previousElementSibling; node; node = node.previousElementSibling) {
                if (shows(node)) return true;
            }
            return false;
        },
    }));
});

/**
 * Command palette ranking (the `rank` prop; see command.js for the contract).
 *
 * rankTier(text, query) puts a matching item in a tier, best first:
 *   0  the whole query as a phrase on word boundaries ("sign in" in "Sign in")
 *   1  every query word as a whole word, in any order
 *   2  every query word as a word prefix ("inb" in "Inbox")
 *   3  the query, or every word, as a substring ("in" in "Pinned")
 *   4  a scattered fuzzy match ("csk" in "Create skill")
 * Unmatched rows get RANK_UNMATCHED. The palette shows items by tier within
 * their group and groups by their best tier, with CSS `order` on the flex list
 * and groups; ties keep document order. rankMethods are spread into the
 * uiCommand Alpine data, so `this` is the palette.
 */
export function fuzzyMatch(text, query) {
    return query.split(/\s+/).filter(Boolean).every((word) => {
        let from = 0;
        for (const char of word) {
            from = text.indexOf(char, from);
            if (from === -1) return false;
            from += 1;
        }

        return true;
    });
}

// Ranking (see the header). Unmatched rows rank after every tier; persistent
// rows and the actions footer keep their place at the end.
const RANK_UNMATCHED = 9;
const PERSISTENT_ORDER = 9000;
const ACTIONS_ORDER = 9999;
const WORD_START = '(?:^|[^\\p{L}\\p{N}])';
const WORD_END = '(?=$|[^\\p{L}\\p{N}])';
const tierCache = new Map();

function escapeRegExp(value) {
    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}

/** The ranking tier of `text` for `query`: 0 (a phrase match) to 4 (fuzzy), else RANK_UNMATCHED. */
export function rankTier(text, query) {
    const q = String(query ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
    if (q === '') return 0;
    const t = String(text ?? '').toLowerCase().replace(/\s+/g, ' ');
    const cacheKey = `${q}\u0000${t}`;
    if (tierCache.has(cacheKey)) return tierCache.get(cacheKey);
    const words = q.split(' ');
    const whole = (word) => new RegExp(WORD_START + escapeRegExp(word) + WORD_END, 'u').test(t);
    const prefix = (word) => new RegExp(WORD_START + escapeRegExp(word), 'u').test(t);
    let tier = RANK_UNMATCHED;
    if (whole(q)) tier = 0;
    else if (words.every(whole)) tier = 1;
    else if (words.every(prefix)) tier = 2;
    else if (t.includes(q) || words.every((word) => t.includes(word))) tier = 3;
    else if (fuzzyMatch(t, q)) tier = 4;
    if (tierCache.size > 4000) tierCache.clear();
    tierCache.set(cacheKey, tier);

    return tier;
}

export function documentOrder(a, b) {
    if (a === b) return 0;

    return a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
}

export const rankMethods = {
    /** Sorts shown items into the visual order the CSS `order` values draw. */
    sortRanked(shown) {
        const groupOrders = new Map();
        const keys = new Map(shown.map((item) => [item, this.visualKey(item, groupOrders)]));

        return shown.sort((a, b) => {
            if (!a.el || !b.el || a.el === b.el) return 0;
            const ka = keys.get(a);
            const kb = keys.get(b);
            if (ka.outer !== kb.outer) return ka.outer - kb.outer;
            if (ka.outerEl !== kb.outerEl) return documentOrder(ka.outerEl, kb.outerEl);
            if (ka.inner !== kb.inner) return ka.inner - kb.inner;

            return documentOrder(a.el, b.el);
        });
    },

    /** True while ranking applies: `rank` is on and a query is typed. */
    ranking() {
        return Boolean(this.rank) && this.query.trim() !== '';
    },

    /**
     * The CSS order of an item inside its list, group or actions footer;
     * null when it is not ranked (no query, a sequenced or Recent row, or
     * an item wrapped in some other element whose order cannot follow).
     */
    itemOrder(el, search) {
        if (!this.ranking() || !el) return null;
        const parent = el.parentElement;
        const slot = parent?.dataset?.slot;
        // The actions footer is not a flex container, so its rows keep document order.
        if (slot !== 'command-list' && slot !== 'command-group') return null;
        if (el.closest('[data-sequenced]') || parent.hasAttribute('data-recent')) return null;
        if (el.hasAttribute('data-persistent')) return PERSISTENT_ORDER;

        return rankTier(search, this.query);
    },

    /** The CSS order of a group in the list: its best matching item's tier. */
    groupOrder(group) {
        if (!this.ranking() || !group || group.parentElement?.dataset?.slot !== 'command-list') return null;
        if (group.hasAttribute('data-sequenced') || group.hasAttribute('data-recent')) return null;
        let best = PERSISTENT_ORDER;
        for (const item of this.items) {
            if (!item.el || item.recent || !item.el.isConnected || !group.contains(item.el)) continue;
            if (item.el.hasAttribute('data-persistent') || !this.matches(item.search, item.el)) continue;
            best = Math.min(best, rankTier(item.search, this.query));
        }

        return best;
    },

    /** Sort key that mirrors the CSS order: the list-level child first, then the row inside it. */
    visualKey(item, groupOrders) {
        const el = item.el;
        const parent = el?.parentElement;
        const own = this.itemOrder(el, item.search);
        if (own !== null && parent.dataset.slot === 'command-group') {
            if (!groupOrders.has(parent)) groupOrders.set(parent, this.groupOrder(parent) ?? 0);

            return { outer: groupOrders.get(parent), outerEl: parent, inner: own };
        }
        if (own !== null) return { outer: own, outerEl: el, inner: 0 };
        // Not ranked: it moves with the list-level element that holds it.
        let top = el;
        while (top?.parentElement && top.parentElement.dataset.slot !== 'command-list') top = top.parentElement;
        const holder = top?.parentElement ? top : el;
        const outer = holder.dataset?.slot === 'command-actions'
            ? ACTIONS_ORDER
            : (holder.dataset?.slot === 'command-group' ? (this.groupOrder(holder) ?? 0) : 0);

        return { outer, outerEl: holder, inner: 0 };
    },

    /** x-bind:style for an item: its rank order while ranking, else nothing. */
    rankStyle(el, search) {
        const order = this.itemOrder(el, search);

        return order === null ? {} : { order: String(order) };
    },

    /** x-bind:style for a group: its best item's order while ranking, else nothing. */
    groupRankStyle(el) {
        const order = this.groupOrder(el);

        return order === null ? {} : { order: String(order) };
    },
};