Command Palette with a Remote Search

This page builds a <x-wirekit::command-palette> whose results come from a server.

A search that asks a server has two answers the empty state cannot give: the results are not here yet, or the request failed. And the controls that narrow such a search belong above the results, not beneath them. Three slots cover both:

• filters renders between the input and the list. Tab moves from the input into it.
• loading shows while your request is out.
• error shows when it failed.

The palette cannot see your request, so you report where it stands with the wirekit:command-palette-state event. Open the demo and type: the loading line shows until the answer arrives. Switch the section to narrow the list, and type offline to see the failure. The demo only pretends to ask a server; Show Code has the markup of a real search, and the factory it calls follows below.

The Demo

{{-- 1. The search lives in the factory registered below. The directives only
        call its methods, so the same markup runs under Alpine's CSP build. --}}
<div x-data="siteSearch">
    {{-- 2. The palette announces every keystroke (debounced) with the query event. --}}
    <x-wirekit::command-palette x-on:wirekit-command-palette-query="search($event.detail.query)">
        {{-- 3. Render the answer as options. `href="#"` makes each one a real link,
                the binding sets where it goes, and a stable id keeps the highlight
                on its row when the list re-renders. --}}
        <template x-for="result in results" :key="result.id">
            <x-wirekit::command-palette.item href="#" x-bind:href="result.url" x-bind:id="'search-' + result.id">
                <span x-text="result.title"></span>
            </x-wirekit::command-palette.item>
        </template>

        {{-- 4. The filter row, between the input and the list. --}}
        <x-slot:filters>
            <x-wirekit::segmented-control name="search-section" aria-label="Search in" size="sm" value="all"
                :options="['all' => 'All', 'docs' => 'Docs', 'blueprints' => 'Blueprints']"
                x-on:input="narrow($event.target.value)" />
        </x-slot:filters>

        {{-- 5. Plain text: the palette announces both through a region of its own. --}}
        <x-slot:loading>Searching…</x-slot:loading>
        <x-slot:error>The search is unavailable right now. Try again in a moment.</x-slot:error>

        <x-slot:empty>
            <x-wirekit::command-palette.empty>Nothing matches that search.</x-wirekit::command-palette.empty>
        </x-slot:empty>
    </x-wirekit::command-palette>
</div>

The Search Factory

The factory holds the request. A newer query aborts the older one, so a slow answer never overwrites a fast one, and a failure is reported, so the error slot shows instead of "nothing matched". Register it before Alpine starts:

// 1. In a script loaded with `defer`, so it runs before Alpine starts.
document.addEventListener('alpine:init', () => {
    Alpine.data('siteSearch', () => ({
        section: 'all',
        term: '',
        results: [],
        controller: null,

        // 2. Ask the server for one query. A newer query aborts this one.
        async search(term) {
            this.term = term;
            this.controller?.abort();
            this.controller = new AbortController();
            this.$dispatch('wirekit:command-palette-state', { state: 'loading' });

            try {
                const url = '/search?q=' + encodeURIComponent(term) + '&section=' + this.section;
                const response = await fetch(url, { signal: this.controller.signal });

                if (! response.ok) {
                    throw new Error('Search answered ' + response.status);
                }

                this.results = await response.json();
                this.$dispatch('wirekit:command-palette-state', { state: 'idle' });
            } catch (error) {
                // 3. A request a newer query aborted reports nothing.
                if (error.name === 'AbortError') {
                    return;
                }

                this.results = [];
                this.$dispatch('wirekit:command-palette-state', { state: 'error' });
            }
        },

        // 4. A new section asks again for the same words.
        narrow(section) {
            this.section = section;
            this.search(this.term);
        },
    }));
});

Reporting Where the Request Stands

The event takes one of three states:

Any other value counts as idle, so a palette never stays in the loading state because of an unexpected word. The event is page-wide, like wirekit-command-palette-show: dispatch it without naming a palette. Opening the palette resets the state to idle before it announces the empty query, so a request you start in answer to that query keeps its loading.

From a Livewire component, dispatch the same event with named arguments:

// 1. The request failed on the server — show the error slot.
$this->dispatch('wirekit:command-palette-state', state: 'error');

The Three Slots

A few things to know about them:

• loading and error take plain content. The palette announces both through a role="status" region of its own, which is always in the page so a change inside it is read out. A spinner or anything else with its own role="status" inside it would be announced twice.
• Put mutually exclusive filters in a segmented-control. It is one Tab stop, and the arrow keys switch the section.
• The list keys belong to the input. ArrowUp, ArrowDown, Home, End and Enter move through the results only while the input has focus. A control in the filter row or the footer keeps its own keys.

Further Reading

• Command Palette — every prop, slot and keyboard interaction of the component.
• Overlay Events — the palette's show, close, query and state events beside the other overlays.