Property Picker

# Brok UI: Property Picker (`property-picker`)

A compact, Linear-style popover picker that changes one property of a record (state, priority, assignee, labels) with search, check marks, digit shortcuts, a hotkey and wire:model.

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

## Install

```bash
php artisan ui:add property-picker
```

## Usage

```blade
{{-- The properties of one task, each a picker: state, priority, assignee
     and labels. Click a property, or focus the row and press S, P, A or L. --}}
<div
    x-data="{ state: 'unstarted', priority: 'medium', assignee: null, labels: ['feature', 'design'] }"
    data-hotkey-scope="task"
    tabindex="0"
    class="flex w-full max-w-xl flex-wrap items-center gap-1 rounded-md border border-border p-2 focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring"
>
    <span class="me-2 min-w-0 flex-1 truncate text-sm font-medium text-foreground">{{ __('Draft the launch checklist') }}</span>

    <x-ui.property-picker x-model="state" :label="__('State')" :placeholder="__('Change state to…')" hotkey="s">
        @foreach ([['backlog', __('Backlog')], ['unstarted', __('Todo')], ['started', __('In progress')], ['completed', __('Done')], ['cancelled', __('Cancelled')]] as [$value, $name])
            <x-ui.property-picker.option :value="$value" :label="$name" :shortcut="(string) $loop->iteration">
                <x-slot:icon><x-ui.issue-row.state :state="$value" :label="$name" :announce="false" /></x-slot:icon>
            </x-ui.property-picker.option>
        @endforeach
    </x-ui.property-picker>

    <x-ui.property-picker x-model="priority" variant="icon" :label="__('Priority')" :placeholder="__('Set priority to…')" hotkey="p">
        @foreach ([['none', __('No priority')], ['urgent', __('Urgent')], ['high', __('High')], ['medium', __('Medium')], ['low', __('Low')]] as [$value, $name])
            <x-ui.property-picker.option :value="$value" :label="$name" :shortcut="(string) $loop->index">
                <x-slot:icon><x-ui.issue-row.priority :priority="$value" :label="$name" /></x-slot:icon>
            </x-ui.property-picker.option>
        @endforeach
    </x-ui.property-picker>

    <x-ui.property-picker x-model="assignee" variant="icon" :label="__('Assignee')" :placeholder="__('Assign to…')" hotkey="a" :empty-label="__('No assignee')">
        @foreach ([[1, 'Ada Lovelace', 'AL'], [2, 'Grace Hopper', 'GH']] as [$id, $person, $initials])
            <x-ui.property-picker.option :value="$id" :label="$person">
                <x-slot:icon><x-ui.avatar size="xs" :fallback="$initials" class="!size-5 text-2xs" /></x-slot:icon>
            </x-ui.property-picker.option>
        @endforeach
    </x-ui.property-picker>

    <x-ui.property-picker x-model="labels" multiple :label="__('Labels')" :placeholder="__('Add labels…')" hotkey="l" :empty-label="__('Add label')" :count-label="__(':count labels')">
        @foreach ([['bug', __('Bug')], ['feature', __('Feature')], ['design', __('Design')]] as [$value, $name])
            <x-ui.property-picker.option :value="$value" :label="$name">
                <x-slot:icon><span class="size-2 rounded-full bg-muted-foreground"></span></x-slot:icon>
            </x-ui.property-picker.option>
        @endforeach
    </x-ui.property-picker>
</div>
```

## Props

- `value` (string|int|array|null, default `null`) — The first chosen value, or an array with multiple. Later values arrive through wire:model or x-model; the value is kept out of x-data, so a Livewire render never starts the picker again.
- `multiple` (bool, default `false`) — Choose any number of options (labels). Each pick toggles a value, the picker stays open and the list is aria-multiselectable.
- `label` (string|null, default `null`) — The property's name ("Priority"). It names the panel and the list, and the trigger reads "<label>: <value>". Null: the translated "Options".
- `placeholder` (string|null, default `null`) — Placeholder of the search field. Null: the translated "Filter…".
- `emptyText` (string|null, default `null`) — Row shown when no option matches the search. Null: the translated "No options match.".
- `emptyLabel` (string|null, default `null`) — Trigger text while nothing is chosen ("No priority"). Null: the translated "None".
- `countLabel` (string|null, default `null`) — Trigger text for two or more chosen values, with :count. Null: the translated ":count selected".
- `variant` (property|button|icon, default `property`) — Look of the default trigger: property is a quiet row property, button an outlined button, icon shows the icon only and keeps the value readable to screen readers.
- `hotkey` (string|null, default `null`) — Key that opens the picker through the hotkey registry ("p"). Inside an element with data-hotkey-scope the key belongs to that scope, so the focused row's picker opens.
- `hotkeyDescription` (string|null, default `null`) — Help-list text of the hotkey. Null: the translated "Change :property".
- `hotkeyGroup` (string|null, default `null`) — Help-list group of the hotkey. Null: the translated "Properties".
- `closeOnSelect` (bool|null, default `null`) — Close after a pick. Null: close for a single value, stay open with multiple.
- `name` (string|null, default `null`) — Form field name: the chosen value(s) go in hidden inputs (name[] with multiple).
- `disabled` (bool, default `false`) — Disables the trigger and the hotkey.
- `server` (bool, default `false`) — Server mode of the inner command: the picker dispatches property-picker-search { query, sequence, done(), fail(), isCurrent() } and the host renders the options (see command server mode).
- `debounce` (int, default `200`) — Server mode: milliseconds before property-picker-search is dispatched.
- `side` (top|bottom|start|end, default `bottom`) — Preferred side of the panel; it flips when there is no room.
- `align` (start|center|end, default `start`) — Alignment of the panel along the trigger.
- `detached` (bool, default `false`) — No trigger of its own: the picker opens only from property-picker-open { id, anchor } or its hotkey, placed against that element, so one picker can serve every row of a list. Without an anchor it opens against the focused element.
- `actionsLabel` (string|null, default `null`) — Accessible name of the `actions` footer group. Null: the command's translated "Actions".
- `keywords` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `shortcut` (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.
- `labelExpr` (mixed|null, default `null`) — 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.
- A row or a detail page changes one property of a record (state, priority, assignee, labels) in place, by click or by a key.
- The choice needs search, icons and a visible check on the current value, in less space than a select field.

## Avoid when

- Do not hide a small option set in a dropdown when recognition and comparison matter.
- A form field with a label and validation text; use combobox or select.
- Running commands rather than setting a value; use command.
- A status pill whose menu previews each status as a pill; use status-select.

## Anti-patterns

- Hiding a small comparable set in a dropdown

## Rules

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

@props([
    // The chosen value (a string or number), or with `multiple` an array.
    // Later values arrive through wire:model / x-model.
    'value' => null,
    // Choose any number of options; the picker then stays open on a pick.
    'multiple' => false,
    // The property's name ("Priority"). It names the panel and the list, and
    // the trigger reads "<label>: <value>" to assistive technology.
    'label' => null,
    // Placeholder of the search field. Null: the translated "Filter…".
    'placeholder' => null,
    // Row shown when no option matches the search. Null: the translated default.
    'emptyText' => null,
    // Trigger text while nothing is chosen ("No priority"). Null: "None".
    'emptyLabel' => null,
    // Trigger text for two or more chosen values. Null: ":count selected".
    'countLabel' => null,
    // Look of the default trigger: property (a quiet row property), button
    // (an outlined button) or icon (the icon only, the text for screen readers).
    'variant' => 'property',
    // Key that opens the picker through the hotkey registry ("p"). Inside an
    // element with data-hotkey-scope the key belongs to that scope, so the
    // focused row's picker opens.
    'hotkey' => null,
    'hotkeyDescription' => null,
    'hotkeyGroup' => null,
    // Close after a pick. Null: close for a single value, stay open with `multiple`.
    'closeOnSelect' => null,
    // Form field name; the chosen value(s) go in hidden inputs (name[] with `multiple`).
    'name' => null,
    'disabled' => false,
    // Server mode of the inner command: the host supplies the options for the
    // typed text through `property-picker-search` (see command `server`).
    'server' => false,
    'debounce' => 200,
    // Preferred side and alignment of the panel.
    'side' => 'bottom',
    'align' => 'start',
    // No trigger of its own: the picker opens only from
    // `property-picker-open` { id, anchor } (or its hotkey), anchored to that
    // element, so one picker can serve every row of a list.
    'detached' => false,
    // Name of the `actions` footer group. Null: the command's "Actions".
    'actionsLabel' => null,
])

@php
    // Accept a string, a backed enum or a Stringable for `variant`.
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $label = filled($label) ? (string) $label : __('Options');
    $config = [
        'multiple' => (bool) $multiple,
        'closeOnSelect' => $closeOnSelect === null ? ! $multiple : (bool) $closeOnSelect,
        'disabled' => (bool) $disabled,
        'detached' => (bool) $detached,
        'texts' => [
            'empty' => filled($emptyLabel) ? (string) $emptyLabel : __('None'),
            'count' => filled($countLabel) ? (string) $countLabel : __(':count selected'),
        ],
    ];
    if (filled($hotkey)) {
        $config += [
            'hotkey' => (string) $hotkey,
            'hotkeyDescription' => filled($hotkeyDescription) ? (string) $hotkeyDescription : __('Change :property', ['property' => $label]),
            'hotkeyGroup' => filled($hotkeyGroup) ? (string) $hotkeyGroup : __('Properties'),
        ];
    }
    $initial = $multiple
        ? array_values(array_filter((array) $value, fn ($item) => $item !== null && $item !== ''))
        : (is_array($value) ? ($value[0] ?? null) : $value);
@endphp

{{--
    Property picker (Linear-style): a compact popover that changes one
    property of a record. It composes popover (anchored placement, outside
    click, Escape and focus return) and command (search field, filtering,
    arrow keys, Enter); this root holds the chosen value(s) for wire:model and
    x-model and dispatches `change` { value, context? }. Any element can open
    it: dispatch `property-picker-open` { id, anchor, value?, context? } and
    the panel is placed against `anchor` and returns focus to it on close. The first value sits in a data
    attribute, so a Livewire render never starts the component again.

    The `actions` slot is the command list's footer: command.item rows
    (usually `persistent`, such as "Create label “<query>”"; the typed text
    is `query` in Alpine scope). Picking one never changes the value: the
    picker dispatches `property-picker-action` { value, query, context? }
    and closes, unless a listener calls preventDefault().
--}}
<div
    x-data="uiPropertyPicker(@js($config))"
    x-modelable="model"
    data-slot="property-picker"
    data-value="{{ json_encode($initial) }}"
    data-multiple="{{ $multiple ? 'true' : 'false' }}"
    @if ($disabled) data-disabled="true" @endif
    @if ($detached) data-detached="true" @endif
    x-on:property-picker-open.window="openFromEvent($event)"
    {{-- Detached, the root has no box: its panel is teleported and opens beside the anchor. --}}
    {{ $attributes->merge(['class' => $detached ? 'hidden' : 'inline-flex min-w-0 max-w-full']) }}
>
    @if (filled($name))
        <template x-for="item in picked" :key="String(item)">
            <input type="hidden" name="{{ $multiple ? $name.'[]' : $name }}" x-bind:value="item" />
        </template>
    @endif

    <x-ui.popover anchored class="min-w-0 max-w-full" x-effect="onPickerToggle(open)">
        @if ($detached)
            {{-- Detached: the panel opens from the element named in property-picker-open. --}}
        @elseif (isset($trigger))
            {{ $trigger }}
        @else
            <x-ui.property-picker.trigger :variant="$variant" />
        @endif

        <x-ui.popover.content :side="$side" :align="$align" :aria-label="$label" data-property-picker-panel class="!w-64 overflow-hidden !p-0">
            <x-ui.command
                :server="$server"
                :debounce="$debounce"
                :clear-on-escape="false"
                class="!rounded-none !border-0 !bg-transparent"
                x-on:command-select="pickFromCommand($event)"
                x-on:command-search="forwardSearch($event)"
                x-on:keydown="onPickerKeydown($event)"
            >
                <x-ui.command.input :placeholder="filled($placeholder) ? $placeholder : __('Filter…')" :aria-label="$label" />
                <x-ui.command.list :aria-label="$label" :aria-multiselectable="$multiple ? 'true' : null" :actions-label="$actionsLabel">
                    <x-ui.command.empty>{{ filled($emptyText) ? $emptyText : __('No options match.') }}</x-ui.command.empty>
                    {{ $slot }}
                    @isset($actions)
                        <x-slot:actions>{{ $actions }}</x-slot:actions>
                    @endisset
                </x-ui.command.list>
            </x-ui.command>
        </x-ui.popover.content>
    </x-ui.popover>
</div>

@aware([
    'label' => null,
    'disabled' => false,
])

@props([
    // property: a quiet row property. button: an outlined button. icon: the
    // icon only; the value stays readable to screen readers.
    'variant' => 'property',
])

@php
    // Accept a string, a backed enum or a Stringable for `variant`.
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $variant = in_array($variant, ['property', 'button', 'icon'], true) ? $variant : 'property';
    $shared = 'min-w-0 gap-2 text-sm text-foreground transition-colors hover:bg-accent hover:text-accent-foreground aria-expanded:bg-accent focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-transparent motion-reduce:transition-none';
    $variants = [
        'property' => 'h-8 max-w-full !justify-start rounded-sm px-2',
        'button' => 'h-8 max-w-full !justify-start rounded-md border border-input bg-background px-3 shadow-sm',
        'icon' => 'size-8 rounded-sm',
    ];
    $name = filled($label) ? (string) $label : __('Options');
@endphp

{{-- The trigger of a property picker. With no slot it shows the chosen
     value's icon and label (or the count), kept current in the browser; a
     slot replaces that with server-rendered content, for a host that renders
     again after each change (wire:model.live). --}}
<x-ui.popover.trigger
    data-property-picker-trigger
    data-variant="{{ $variant }}"
    aria-haspopup="dialog"
    :disabled="(bool) $disabled"
    {{ $attributes->merge(['class' => $shared.' '.$variants[$variant]]) }}
>
    <span class="sr-only">{{ $name }}:</span>
    @if ($slot->isEmpty())
        <span data-slot="property-picker-value" wire:ignore class="inline-flex min-w-0 items-center gap-2" x-effect="renderPickerValue($el, @js($variant === 'icon' ? 'icon' : 'full'))"></span>
    @else
        <span data-slot="property-picker-value" class="inline-flex min-w-0 items-center gap-2">{{ $slot }}</span>
    @endif
</x-ui.popover.trigger>

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

@props([
    // The option's value; its type (a string or a number) is kept for wire:model.
    'value' => null,
    // The option's name. Null: the text of the slot.
    'label' => null,
    // More words the search matches ("p1 urgent").
    'keywords' => null,
    // A digit that picks the option while the search field is empty ("1").
    'shortcut' => null,
    'disabled' => false,
    'disabledReason' => null,
    // Client data: Alpine expressions for the value and the name, for an
    // option rendered inside <template x-for> (value-expr="person.id",
    // label-expr="person.name"). They replace value and label.
    'valueExpr' => null,
    'labelExpr' => null,
])

@php
    $dynamic = filled($valueExpr);
    $text = filled($label) ? (string) $label : html_entity_decode(trim(strip_tags((string) $slot)), ENT_QUOTES);
    $valueJs = $dynamic ? '('.$valueExpr.')' : \Illuminate\Support\Js::from($value)->toHtml();
    $labelJs = $dynamic ? '('.(filled($labelExpr) ? $labelExpr : $valueExpr).')' : \Illuminate\Support\Js::from($text)->toHtml();
    $shortcutText = $shortcut === null || $shortcut === '' ? null : (string) $shortcut;
    $keywordsExpr = $dynamic ? (filled($keywords) ? $labelJs.' + '.\Illuminate\Support\Js::from(' '.$keywords)->toHtml() : $labelJs) : null;
@endphp

{{-- One option of a property picker: a command item whose aria-selected
     reports the chosen value(s); the icon slot also shows in the trigger. --}}
<x-ui.command.item
    :value="$dynamic ? null : $value"
    :keywords="$dynamic ? null : trim($text.' '.$keywords)"
    :value-expr="$dynamic ? $valueExpr : null"
    :keywords-expr="$keywordsExpr"
    :disabled="$disabled"
    :disabled-reason="$disabledReason"
    :selected-expr="'isPicked('.$valueJs.')'"
    :aria-keyshortcuts="$shortcutText"
    data-property-picker-option
    {{ $attributes }}
>
    @if ($multiple)
        <span aria-hidden="true" class="flex size-4 shrink-0 items-center justify-center rounded-xs border border-input text-background" x-bind:class="isPicked({{ $valueJs }}) ? 'border-foreground bg-foreground' : 'bg-background'">
            <svg x-show="isPicked({{ $valueJs }})" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" class="size-3">
                <path d="M20 6 9 17l-5-5" />
            </svg>
        </span>
    @endif
    @isset($icon)
        <span data-slot="property-picker-icon" class="inline-flex shrink-0 items-center">{{ $icon }}</span>
    @endisset
    <span
        data-slot="property-picker-label"
        class="min-w-0 flex-1 truncate"
        x-init="registerPickerOption({{ $valueJs }}, {{ $labelJs }}, @js($shortcutText), $el.closest('[data-slot=command-item]'), @js(! $disabled))"
        @if ($dynamic && $slot->isEmpty()) x-text="{{ $labelJs }}" @endif
    >@unless ($dynamic && $slot->isEmpty()){{ $slot->isEmpty() ? $text : $slot }}@endunless</span>
    @unless ($multiple)
        <svg aria-hidden="true" x-show="isPicked({{ $valueJs }})" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 text-foreground">
            <path d="M20 6 9 17l-5-5" />
        </svg>
    @endunless
    @if ($shortcutText !== null)
        <x-ui.command.shortcut class="w-4 text-center">{{ $shortcutText }}</x-ui.command.shortcut>
    @endif
</x-ui.command.item>

/**
 * Property picker behavior: a compact, Linear-style picker for one property
 * of a record (state, priority, assignee, labels).
 *
 * It composes two items and adds only the selection model:
 * - `popover` (anchored) owns placement, outside click, Escape and focus
 *   return to the trigger;
 * - `command` owns the search field, filtering, the active option
 *   (aria-activedescendant) and Arrow/Home/End/Enter;
 * - this component owns the chosen value(s): x-modelable (`wire:model`,
 *   `x-model`), the `change` event, the check marks (aria-selected through
 *   command.item's selected-expr), digit shortcuts, the hotkey that opens
 *   the picker and the trigger's value display.
 *
 * Any element can open the picker: `property-picker-open` on window with
 * { id, anchor, value?, context? } opens the picker with that id against
 * `anchor` (popover's showFrom()), so the panel sits beside that element and
 * focus returns to it on close. `value` sets the chosen value(s) first
 * without a change event, and `context` (a row id) comes back in every
 * `change` detail until the next open, so one picker can serve a whole list.
 * With `detached` the picker has no trigger of its own.
 *
 * The panel is teleported to <body>, so events from inside it do not bubble
 * through the picker root. Handlers inside the panel run in the picker's
 * scope and dispatch on the stored root element instead.
 *
 * Methods here run with `this` bound to the scope of the calling element,
 * which can be the command or the popover inside the picker; the picker's
 * own fields therefore have names that no inner component uses.
 */
import './command.js';
import './popover.js';
import './hotkeys.js';

document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiPropertyPicker', (config = {}) => ({
        pickerMultiple: config.multiple ?? false,
        pickerClosesOnSelect: config.closeOnSelect ?? !(config.multiple ?? false),
        pickerTexts: config.texts ?? {},
        // The chosen values, with the types the options gave them.
        picked: [],
        // [{ value, label, shortcut, enabled, el }] in registration order;
        // `el` is the option's command item.
        pickerOptions: [],
        pickerRoot: null,
        pickerWasOpen: false,
        pickerHotkey: null,
        // The `context` of the last property-picker-open (a row id), handed
        // back in the change detail. Null: not sent.
        pickerContext: null,

        init() {
            this.pickerRoot = this.$el;
            let value = null;
            try {
                value = JSON.parse(this.$el.dataset.value ?? 'null');
            } catch {
                value = null;
            }
            this.picked = this.normalizePicked(value);

            if (config.hotkey) {
                this.pickerHotkey = this.$hotkeys.register(config.hotkey, () => {
                    this.pickerContext = null;
                    this.openPicker();
                }, {
                    description: config.hotkeyDescription ?? '',
                    group: config.hotkeyGroup ?? '',
                    enabled: () => !config.disabled,
                    visible: true,
                });
            }
        },

        destroy() {
            this.pickerHotkey?.unregister();
            this.pickerHotkey = null;
        },

        /**
         * Modelable value: the chosen value (null when none) or, with
         * `multiple`, the array of chosen values.
         */
        get model() {
            return this.pickerMultiple ? [...this.picked] : (this.picked[0] ?? null);
        },
        set model(value) {
            const next = this.normalizePicked(value);
            if (JSON.stringify(next.map(String)) === JSON.stringify(this.picked.map(String))) return;
            this.picked = next;
        },

        normalizePicked(value) {
            const list = Array.isArray(value) ? value : (value == null || value === '' ? [] : [value]);

            return this.pickerMultiple ? list.filter((item) => item != null && item !== '') : list.slice(0, 1);
        },

        /** An empty option value ("No assignee") stands for "nothing chosen". */
        isPicked(value) {
            if (!this.pickerMultiple && (value === '' || value == null)) return this.picked.length === 0;

            return this.picked.some((item) => String(item) === String(value));
        },

        /** An option registers its value, label, digit and element. */
        registerPickerOption(value, label, shortcut, el, enabled = true) {
            const entry = { value, label: String(label ?? value), shortcut: shortcut == null ? null : String(shortcut), enabled, el };
            const index = this.pickerOptions.findIndex((option) => option.el === el);
            if (index === -1) {
                this.pickerOptions.push(entry);
                if (el && typeof window.Alpine?.onElRemoved === 'function') {
                    window.Alpine.onElRemoved(el, () => {
                        this.pickerOptions = this.pickerOptions.filter((option) => option.el !== el);
                    });
                }
            } else {
                this.pickerOptions.splice(index, 1, entry);
            }
        },

        /**
         * command-select hands over the option key as text; map it back to the
         * option's own value, so a numeric id stays a number for wire:model.
         */
        pick(key) {
            const option = this.pickerOptions.find((item) => String(item.value) === String(key));
            if (option && !option.enabled) return;
            const value = option ? option.value : key;

            if (this.pickerMultiple) {
                this.picked = this.isPicked(value)
                    ? this.picked.filter((item) => String(item) !== String(value))
                    : [...this.picked, value];
            } else {
                this.picked = value === '' || value == null ? [] : [value];
            }

            const detail = this.pickerContext === null ? { value: this.model } : { value: this.model, context: this.pickerContext };
            this.pickerRoot.dispatchEvent(new CustomEvent('change', { bubbles: true, detail }));

            if (this.pickerClosesOnSelect) this.closePicker();
        },

        /**
         * command-select from the inner command. A row of the list's `actions`
         * footer ("Create label …") is not a value: it dispatches
         * `property-picker-action` { value, query, context? } (as combobox-action) from the picker
         * root and closes the panel, unless a listener prevents the default.
         * Any other row picks its value.
         */
        pickFromCommand(event) {
            const key = event.detail?.value;
            const command = event.currentTarget instanceof Element ? event.currentTarget : null;
            const action = command?.querySelector(`[data-slot="command-actions"] [data-slot="command-item"][data-value="${CSS.escape(String(key))}"]`);
            if (!action) {
                this.pick(key);

                return;
            }
            const query = String(window.Alpine.$data(command)?.query ?? '');
            const detail = this.pickerContext === null ? { value: key, query } : { value: key, query, context: this.pickerContext };
            const proceed = this.pickerRoot.dispatchEvent(new CustomEvent('property-picker-action', { bubbles: true, cancelable: true, detail }));
            if (proceed) this.closePicker();
        },

        /** The popover component inside the picker. */
        pickerPopover() {
            const el = this.pickerRoot?.querySelector('[data-slot="popover"]');

            return el ? window.Alpine.$data(el) : null;
        },

        /**
         * Open the panel, against `anchor` when given. A detached picker with
         * no anchor opens against the focused element, so it still has a
         * place and a focus return.
         */
        openPicker(anchor = null) {
            if (config.disabled) return;
            const popover = this.pickerPopover();
            if (!popover) return;
            let from = anchor instanceof Element ? anchor : null;
            if (!from && config.detached && document.activeElement instanceof Element && document.activeElement !== document.body) {
                from = document.activeElement;
            }
            if (from) {
                popover.showFrom(from);
            } else if (!popover.open) {
                popover.show();
            }
        },

        closePicker() {
            this.pickerPopover()?.closeAndFocus();
        },

        /**
         * `property-picker-open` on window with { id, anchor?, value?,
         * context? } opens the picker with that id. The same anchor while the
         * panel is open closes it again (a toggle); another anchor moves it.
         */
        openFromEvent(event) {
            const detail = event.detail ?? {};
            if (!detail.id || detail.id !== this.pickerRoot.id || config.disabled) return;
            const popover = this.pickerPopover();
            const anchor = detail.anchor instanceof Element ? detail.anchor : null;
            if (popover?.open && anchor && popover.anchorEl?.() === anchor) {
                this.closePicker();

                return;
            }
            if (Object.prototype.hasOwnProperty.call(detail, 'value')) this.model = detail.value;
            this.pickerContext = detail.context ?? null;
            this.openPicker(anchor);
            // A panel that moves to another row stays open, so the toggle
            // below does not run: mark the new row's value here as well.
            this.$nextTick(() => this.activatePicked());
        },

        /** The command component inside the (teleported) panel. */
        pickerCommand() {
            const panel = this.pickerPopover()?.$refs?.panel;
            const el = panel?.querySelector('[data-slot="command"]');

            return el ? window.Alpine.$data(el) : null;
        },

        /**
         * Make the (first) chosen option the command's active option and
         * scroll it into view, so Enter keeps the value and the arrow keys
         * start from it. With nothing chosen, or a chosen option that is
         * hidden or disabled, the first option is active. Typing a query then
         * makes the first match active, as the command always does.
         */
        activatePicked() {
            const command = this.pickerCommand();
            if (!command || typeof command.visible !== 'function') return;
            const chosen = command.visible().find((item) => item.el && this.pickerOptions.some((option) => option.el === item.el && this.isPicked(option.value)));
            if (chosen) {
                command.active = chosen.value;
            } else {
                command.reset();
            }
            command.scrollActiveIntoView?.();
        },

        /**
         * Runs from the popover root (x-effect) with its open state. Opening
         * makes the chosen option the active one (activatePicked()). Closing
         * dispatches a `blur` on the picker root, so wire:model.blur and
         * wire:model.live.blur send the value when the picker closes.
         */
        onPickerToggle(open) {
            if (this.pickerWasOpen && !open) {
                this.pickerRoot.dispatchEvent(new FocusEvent('blur'));
            }
            if (open && !this.pickerWasOpen) {
                this.$nextTick(() => this.activatePicked());
            }
            this.pickerWasOpen = open;
        },

        /**
         * Keys in the panel: a digit picks the option that shows it while the
         * search field is empty; Tab closes the picker and returns focus to
         * the trigger, as the panel sits at the end of the page.
         */
        onPickerKeydown(event) {
            if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;
            if (event.key === 'Tab') {
                event.preventDefault();
                this.closePicker();

                return;
            }
            if (!/^[0-9]$/.test(event.key) || String(this.query ?? '') !== '') return;
            const option = this.pickerOptions.find((item) => item.shortcut === event.key && item.enabled && item.el?.isConnected);
            if (!option) return;
            event.preventDefault();
            this.pick(option.value);
        },

        /** Server mode: the command's search event, re-dispatched from the picker root. */
        forwardSearch(event) {
            event.stopPropagation();
            this.pickerRoot.dispatchEvent(new CustomEvent('property-picker-search', { bubbles: true, detail: event.detail }));
        },

        /**
         * Draw the chosen value(s) into the trigger: the option icons (cloned
         * inside an x-ignore wrapper, without ids) and the label, or the
         * count with `multiple`. Text goes in through textContent only.
         */
        renderPickerValue(el, display = 'full') {
            const chosen = this.picked.map((value) => this.pickerOptions.find((option) => String(option.value) === String(value))
                ?? { value, label: String(value), el: null });
            el.replaceChildren();
            el.dataset.empty = chosen.length === 0 ? 'true' : 'false';

            const icons = document.createElement('span');
            icons.setAttribute('x-ignore', '');
            icons.setAttribute('aria-hidden', 'true');
            icons.className = 'inline-flex shrink-0 items-center -space-x-1 rtl:space-x-reverse';
            for (const option of chosen.slice(0, 3)) {
                const icon = option.el?.querySelector('[data-slot="property-picker-icon"]');
                if (!icon) continue;
                const copy = icon.cloneNode(true);
                copy.removeAttribute('data-slot');
                for (const node of [copy, ...copy.querySelectorAll('[id]')]) node.removeAttribute('id');
                icons.append(copy);
            }

            const text = document.createElement('span');
            text.className = 'min-w-0 truncate';
            if (chosen.length === 0) {
                text.textContent = this.pickerTexts.empty ?? '';
                text.classList.add('text-muted-foreground');
            } else if (chosen.length === 1) {
                text.textContent = chosen[0].label;
            } else {
                text.textContent = String(this.pickerTexts.count ?? ':count').replace(':count', String(chosen.length));
            }
            if (display === 'icon' && icons.childElementCount > 0) text.classList.add('sr-only');

            if (icons.childElementCount > 0) el.append(icons);
            el.append(text);
        },
    }));
});