# Command

Command menu for search and quick actions.

Source: https://webjs.dev/ui/docs/components/command

```ts
import { html } from '@webjsdev/core';
import {
  CalculatorIcon, CalendarIcon, CreditCardIcon, SettingsIcon, SmileIcon, UserIcon,
} from '#lib/ui/lucide.ts';

export default function CommandDemo() {
  return html`
    <ui-command label="Command menu" class="max-w-sm rounded-lg border">
      <ui-command-input placeholder="Type a command or search..."></ui-command-input>
      <ui-command-list>
        <ui-command-empty>No results found.</ui-command-empty>
        <ui-command-group heading="Suggestions">
          <ui-command-item>
            ${CalendarIcon()}
            <span>Calendar</span>
          </ui-command-item>
          <ui-command-item>
            ${SmileIcon()}
            <span>Search Emoji</span>
          </ui-command-item>
          <ui-command-item disabled>
            ${CalculatorIcon()}
            <span>Calculator</span>
          </ui-command-item>
        </ui-command-group>
        <ui-command-separator></ui-command-separator>
        <ui-command-group heading="Settings">
          <ui-command-item>
            ${UserIcon()}
            <span>Profile</span>
            <ui-command-shortcut>⌘P</ui-command-shortcut>
          </ui-command-item>
          <ui-command-item>
            ${CreditCardIcon()}
            <span>Billing</span>
            <ui-command-shortcut>⌘B</ui-command-shortcut>
          </ui-command-item>
          <ui-command-item>
            ${SettingsIcon()}
            <span>Settings</span>
            <ui-command-shortcut>⌘S</ui-command-shortcut>
          </ui-command-item>
        </ui-command-group>
      </ui-command-list>
    </ui-command>
  `;
}
```

## About

The `<ui-command>` element follows the model of [cmdk](https://github.com/dip/cmdk) by [Dip](https://www.dip.org/), built on the platform with no dependency: typing in the input filters and ranks the items, the arrow keys move the selection while focus stays in the input, and Enter runs the selected item.

## Installation

```bash
npx @webjsdev/ui add command
```

### Copy and paste the following code into your project.

````ts title="components/ui/command.ts"
/**
 * Command: a searchable list of actions, the menu behind a command palette.
 * Tier-2. It is cmdk's model, built on the platform: typing in the input
 * filters and ranks the items, the arrow keys move a selection while focus
 * stays in the input, and Enter runs the selected item. `<ui-command-dialog>`
 * puts the same command in a native modal `<dialog>`.
 *
 * shadcn parity:
 *   Command (label, shouldFilter, loop)
 *                            → <ui-command label should-filter="false" loop>
 *   CommandInput placeholder → <ui-command-input placeholder>
 *   CommandList              → <ui-command-list>
 *   CommandEmpty             → <ui-command-empty>No results.</ui-command-empty>
 *   CommandGroup heading     → <ui-command-group heading="Suggestions">
 *   CommandItem (value, keywords, disabled, onSelect)
 *                            → <ui-command-item value keywords="a b" disabled>, firing `ui-select`
 *   CommandShortcut          → <ui-command-shortcut>
 *   CommandSeparator         → <ui-command-separator>
 *   CommandDialog (open, title, description, showCloseButton)
 *                            → <ui-command-dialog open title description show-close-button>
 *                              around a <ui-command>
 *   onValueChange (Command)  → `ui-value-change` ({ detail: { value } }) as the selection moves
 *   onValueChange (Input)    → `ui-search-change` ({ detail: { search } })
 *
 * An item's value is its `value` attribute, else its text. A search ranks
 * items by how well the value and `keywords` match (a prefix beats a word
 * start beats a substring beats letters in order), hides the rest, hides a
 * group left empty and every separator, and shows `<ui-command-empty>` when
 * nothing matches. `should-filter="false"` leaves filtering to you (a list a
 * server action returns). Activating an item that holds a link follows it.
 *
 * Keyboard (as cmdk's): ArrowDown / ArrowUp (and Ctrl+N / Ctrl+P, Ctrl+J /
 * Ctrl+K) move the selection, `loop` wraps it, Home / End jump to the ends,
 * Enter runs the selected item. Pointing at an item selects it.
 *
 * A11y (handled by the element, plus your part): the input is a
 * `role="combobox"` controlling a `role="listbox"` and pointing at the
 * selected `role="option"` through `aria-activedescendant`, so focus never
 * leaves it. Groups are named by their heading and a disabled item is
 * announced and skipped. Your part: name the command (`label`, read by a
 * screen reader only), since a placeholder is not a name.
 *
 * @example
 * ```html
 * <ui-command label="Command menu" class="rounded-lg border shadow-md md:min-w-[450px]">
 *   <ui-command-input placeholder="Type a command or search"></ui-command-input>
 *   <ui-command-list>
 *     <ui-command-empty>No results found.</ui-command-empty>
 *     <ui-command-group heading="Suggestions">
 *       <ui-command-item>Calendar</ui-command-item>
 *       <ui-command-item keywords="emoji smiley">Search Emoji</ui-command-item>
 *       <ui-command-item disabled>Calculator</ui-command-item>
 *     </ui-command-group>
 *     <ui-command-separator></ui-command-separator>
 *     <ui-command-group heading="Settings">
 *       <ui-command-item>Profile<ui-command-shortcut>⌘P</ui-command-shortcut></ui-command-item>
 *     </ui-command-group>
 *   </ui-command-list>
 * </ui-command>
 * ```
 */
import { WebComponent, html, prop, signal, nothing } from '@webjsdev/core';
import { cn, takeAuthoredClass } from '../lib/utils.ts';
import { inputGroupClass, inputGroupAddonClass } from './input-group.ts';
import { UiDialog, UiDialogContent } from './dialog.ts';

/** The command's classes (the element applies them). */
export const commandClass = (): string => 'h-full w-full rounded-md bg-popover text-popover-foreground flex size-full flex-col overflow-hidden';
/** The command dialog's panel classes (the element applies them). */
export const commandDialogClass = (): string => '**:data-[slot=command-input-wrapper]:h-12 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5 top-1/3 translate-y-0 overflow-hidden p-0';
/** The input's wrapper (the element applies them). */
export const commandInputWrapperClass = (): string => 'flex h-9 items-center border-b';
/** The input group around the input (the element applies them). */
export const commandInputGroupClass = (): string => 'h-full rounded-none border-0 bg-transparent shadow-none dark:bg-transparent';
/** The input's classes (the element applies them). */
export const commandInputClass = (): string =>
  'flex h-10 w-full rounded-md bg-transparent py-3 ps-2 pe-3 text-sm placeholder:text-muted-foreground outline-hidden disabled:cursor-not-allowed disabled:opacity-50';
/** The search icon. */
export const commandInputIconClass = (): string => 'size-4 shrink-0 opacity-50';
/** The list's classes (the element applies them). */
export const commandListClass = (): string => 'max-h-[300px] scroll-py-1 flex flex-col overflow-x-hidden overflow-y-auto';
/** The empty state's classes (the element applies them). */
export const commandEmptyClass = (): string => 'py-6 text-center text-sm';
/** A group's classes (the element applies them). */
export const commandGroupClass = (): string => 'overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground';
/** A separator's classes (the element applies them). */
export const commandSeparatorClass = (): string => '-mx-1 h-px bg-border';
/** An item's classes (the element applies them). */
export const commandItemClass = (): string =>
  "relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground [&_svg:not([class*='size-'])]:size-4 [&_svg:not([class*='text-'])]:text-muted-foreground group/command-item data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0";
/** A checked item's check mark. */
export const commandItemIndicatorClass = (): string =>
  'ms-auto opacity-0 group-has-data-[slot=command-shortcut]/command-item:hidden group-data-[checked=true]/command-item:opacity-100';
/** A keyboard shortcut hint's classes. */
export const commandShortcutClass = (): string => 'ms-auto text-xs tracking-widest text-muted-foreground';

/**
 * How well `search` matches `text`, 0 for no match: a prefix scores highest,
 * then a match at a word start, then a substring, then the letters in order.
 * Shorter texts win ties, as in cmdk's command-score.
 */
export function commandScore(text: string, search: string): number {
  const t = text.toLowerCase();
  const s = search.trim().toLowerCase();
  if (!s) return 1;
  if (!t) return 0;
  const brevity = 1 / (1 + t.length / 100);
  if (t.startsWith(s)) return 0.9 + 0.09 * brevity;
  const at = t.indexOf(s);
  if (at > 0) {
    const wordStart = /[\s\-_/.:]/.test(t[at - 1]);
    return (wordStart ? 0.7 : 0.5) + 0.09 * brevity;
  }
  let i = 0;
  for (const ch of t) {
    if (ch === s[i]) i++;
    if (i === s.length) return 0.1 + 0.09 * brevity;
  }
  return 0;
}

const ROOT = 'ui-command';
let uid = 0;

// shadcn's className on each Command part lands on the element that part
// renders (the command, its input, list, empty state, groups and items), so a
// class written on the host moves there, read once at first render. The
// hosts stay boxes rather than display: contents, since a group, an item and
// the empty state hide themselves through the hidden attribute, which a
// display utility on the host would override.
function takeAuthored(part: HTMLElement): string | null {
  return takeAuthoredClass(part, null);
}

type ItemState = { visible: boolean; selected: boolean; order: number };

export class UiCommand extends WebComponent({
  label: String,
  shouldFilter: prop(String, { attribute: 'should-filter' }),
  loop: Boolean,
  // The selected item's value.
  value: prop(String, { reflect: true }),
}) {
  readonly #search = signal('');
  _id = '';

  constructor() {
    super();
    this.label = '';
    this.shouldFilter = 'true';
    this.loop = false;
    this.value = '';
  }

  connectedCallback(): void {
    super.connectedCallback?.();
    this._id ||= `ui-command-${++uid}`;
  }

  // The ids exist once the root has connected. The server never connects an
  // element, so it serves none rather than a `-list` every box would share;
  // hydration renders them in.
  get listId(): string | null {
    return this._id ? `${this._id}-list` : null;
  }

  get labelId(): string | null {
    return this._id ? `${this._id}-label` : null;
  }

  // The root never hides itself, so its host can be display: contents: the
  // command box is then the flex item of whatever holds it, and a `max-w-sm`
  // with the box's `size-full` sizes against that parent, as shadcn's does.
  // The host's box is turned off through its style, which the server serves.
  render() {
    const authored = takeAuthored(this);
    if (typeof this.getAttribute === 'function' && !this.getAttribute('style')) this.setAttribute('style', 'display: contents');
    return html`<div data-slot="command" cmdk-root="" class=${cn(commandClass(), authored)} @keydown=${this._onKeyDown}>${this.label
      ? html`<label id=${this.labelId || nothing} cmdk-label="" class="sr-only">${this.label}</label>`
      : ''}<slot></slot></div>`;
  }

  // The parts that belong to this command, not to a command nested in it.
  _own<T extends Element>(selector: string): T[] {
    if (typeof this.querySelectorAll !== 'function') return [];
    return Array.from(this.querySelectorAll<T>(selector)).filter((el) => el.closest(ROOT) === this);
  }

  /** The items currently shown, in the order they are shown. */
  visibleItems(): UiCommandItem[] {
    return this._own<UiCommandItem>(`${ROOT}-item`)
      .filter((i) => i.state?.get().visible)
      .sort((a, b) => a.state?.get().order - b.state?.get().order);
  }

  /** Set the search text, as typing does. */
  setSearch(search: string): void {
    if (search === this.#search.get()) return;
    this.#search.set(search);
    this.dispatchEvent(new CustomEvent('ui-search-change', { bubbles: true, detail: { search } }));
    this.refresh(true);
  }

  /**
   * Re-rank and redraw the items. A new search selects the best match; a
   * redraw otherwise keeps the selection where it is when it is still shown.
   */
  refresh(reselect = false): void {
    const filter = this.shouldFilter !== 'false';
    const search = this.#search.get();
    const items = this._own<UiCommandItem>(`${ROOT}-item`);
    const scored = items.map((item, dom) => ({
      item,
      dom,
      score: filter ? commandScore(`${item.itemValue} ${item.keywords ?? ''}`, search) : 1,
    }));
    const ranked = search && filter
      ? scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score || a.dom - b.dom)
      : scored;
    const rank = new Map(ranked.map((s, i) => [s.item, i]));
    // A group sits where its best item ranks.
    const groups = this._own<UiCommandGroup>(`${ROOT}-group`);
    const groupRank = new Map<UiCommandGroup, number>();
    for (const g of groups) {
      const ranks = items.filter((i) => i.closest(`${ROOT}-group`) === g && rank.has(i)).map((i) => rank.get(i) as number);
      groupRank.set(g, ranks.length ? Math.min(...ranks) : Infinity);
    }
    const sorting = !!search && filter;
    const visible = ranked.map((s) => s.item);
    const enabled = visible.filter((i) => !i.disabled);
    let selected = items.find((i) => i.itemValue === this.value && rank.has(i) && !i.disabled) ?? null;
    if (reselect || !selected) {
      selected = sorting
        ? enabled[0] ?? null
        : enabled.slice().sort((a, b) => items.indexOf(a) - items.indexOf(b))[0] ?? null;
    }
    for (const item of items) {
      const r = rank.get(item);
      item.state?.set({ visible: r !== undefined, selected: item === selected, order: sorting && r !== undefined ? r : items.indexOf(item) });
    }
    for (const g of groups) {
      const r = groupRank.get(g) ?? Infinity;
      g.shown?.set(r !== Infinity);
      g.order?.set(sorting && r !== Infinity ? r : 0);
    }
    for (const sep of this._own<UiCommandSeparator>(`${ROOT}-separator`)) sep.shown?.set(!search);
    for (const empty of this._own<UiCommandEmpty>(`${ROOT}-empty`)) empty.shown?.set(visible.length === 0);
    this._select(selected);
  }

  _select(item: UiCommandItem | null): void {
    const value = item?.itemValue ?? '';
    for (const i of this._own<UiCommandItem>(`${ROOT}-item`)) {
      if (i.state?.get().selected !== (i === item)) i.state?.set({ ...i.state?.get(), selected: i === item });
    }
    const input = this._own<UiCommandInput>(`${ROOT}-input`)[0];
    if (input) input.activeId?.set(item?.optionId ?? '');
    item?.scrollIntoViewIfShown?.();
    if (value !== this.value) {
      this.value = value;
      this.dispatchEvent(new CustomEvent('ui-value-change', { bubbles: true, detail: { value } }));
    }
  }

  /** Move the selection to an item (used by pointing). */
  selectItem(item: UiCommandItem): void {
    if (item.disabled || !item.state?.get().visible) return;
    this._select(item);
  }

  /** Run an item: fire its ui-select, and follow a link it holds. */
  run(item: UiCommandItem | null): void {
    if (!item || item.disabled) return;
    const ok = item.dispatchEvent(new CustomEvent('ui-select', { bubbles: true, cancelable: true, detail: { value: item.itemValue } }));
    if (!ok) return;
    item.querySelector<HTMLAnchorElement>('a[href]')?.click();
  }

  _move(by: number | 'first' | 'last'): void {
    const enabled = this.visibleItems().filter((i) => !i.disabled);
    if (!enabled.length) return;
    const at = enabled.findIndex((i) => i.state?.get().selected);
    let next: number;
    if (by === 'first') next = 0;
    else if (by === 'last') next = enabled.length - 1;
    else {
      next = at + by;
      if (this.loop) next = (next + enabled.length) % enabled.length;
      else next = Math.max(0, Math.min(enabled.length - 1, next));
    }
    this._select(enabled[next]);
  }

  _onKeyDown = (e: KeyboardEvent): void => {
    if (e.isComposing) return;
    const ctrl = e.ctrlKey && !e.metaKey && !e.altKey;
    if (e.key === 'ArrowDown' || (ctrl && (e.key === 'n' || e.key === 'j'))) { e.preventDefault(); this._move(1); }
    else if (e.key === 'ArrowUp' || (ctrl && (e.key === 'p' || e.key === 'k'))) { e.preventDefault(); this._move(-1); }
    else if (e.key === 'Home') { e.preventDefault(); this._move('first'); }
    else if (e.key === 'End') { e.preventDefault(); this._move('last'); }
    else if (e.key === 'Enter') {
      e.preventDefault();
      this.run(this.visibleItems().find((i) => i.state?.get().selected) ?? null);
    }
  };

  // Parts connected after the first render (a client render appends children
  // in order) are ranked once they are all in place.
  _partConnected(): void {
    if (this._queued) return;
    this._queued = true;
    queueMicrotask(() => { this._queued = false; this.refresh(); });
  }

  _queued = false;
}
UiCommand.register('ui-command');

// --------------------------------------------------------------------------
// <ui-command-input>
// --------------------------------------------------------------------------

export class UiCommandInput extends WebComponent({
  placeholder: String,
}) {
  readonly activeId = signal('');
  constructor() {
    super();
    this.placeholder = '';
  }

  connectedCallback(): void {
    super.connectedCallback?.();
    this._root()?._partConnected();
  }

  _root(): UiCommand | null {
    return this.closest(ROOT) as UiCommand | null;
  }

  render() {
    const root = this._root();
    const named = root?.label ? root.labelId || nothing : nothing;
    return html`<div data-slot="command-input-wrapper" cmdk-input-wrapper="" class=${commandInputWrapperClass()}><div
      data-slot="input-group" class=${cn(inputGroupClass(), commandInputGroupClass())}
    ><input
      data-slot="command-input"
      cmdk-input=""
      type="text"
      role="combobox"
      autocomplete="off"
      autocorrect="off"
      spellcheck="false"
      aria-autocomplete="list"
      aria-expanded="true"
      aria-controls=${root?.listId || nothing}
      aria-labelledby=${named}
      aria-label=${named ? nothing : this.getAttribute?.('aria-label') || this.placeholder || nothing}
      aria-activedescendant=${this.activeId.get() || nothing}
      placeholder=${this.placeholder || nothing}
      class=${cn(commandInputClass(), takeAuthored(this))}
      @input=${this._onInput}
    ><div data-slot="input-group-addon" data-align="inline-start" class=${inputGroupAddonClass()}><svg
      xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"
      class=${commandInputIconClass()}
    ><circle cx="11" cy="11" r="8"></circle><path d="m21 21-4.3-4.3"></path></svg></div></div></div>`;
  }

  _onInput = (e: Event): void => {
    this._root()?.setSearch((e.target as HTMLInputElement).value);
  };
}
UiCommandInput.register('ui-command-input');

// --------------------------------------------------------------------------
// <ui-command-list>
// --------------------------------------------------------------------------

export class UiCommandList extends WebComponent {
  render() {
    const root = this.closest?.(ROOT) as UiCommand | null;
    return html`<div
      data-slot="command-list"
      cmdk-list=""
      role="listbox"
      id=${root?.listId || nothing}
      aria-label=${this.getAttribute?.('aria-label') || 'Suggestions'}
      class=${cn(commandListClass(), takeAuthored(this))}
    ><slot></slot></div>`;
  }
}
UiCommandList.register('ui-command-list');

// --------------------------------------------------------------------------
// <ui-command-empty>
// --------------------------------------------------------------------------

export class UiCommandEmpty extends WebComponent {
  readonly shown = signal(false);
  constructor() {
    super();
  }

  connectedCallback(): void {
    super.connectedCallback?.();
    (this.closest(ROOT) as UiCommand | null)?._partConnected();
  }

  render() {
    return html`<div data-slot="command-empty" cmdk-empty="" role="presentation" ?hidden=${!this.shown.get()} class=${cn(commandEmptyClass(), takeAuthored(this))}><slot></slot></div>`;
  }
}
UiCommandEmpty.register('ui-command-empty');

// --------------------------------------------------------------------------
// <ui-command-group>
// --------------------------------------------------------------------------

export class UiCommandGroup extends WebComponent({
  heading: String,
}) {
  readonly shown = signal(true);
  readonly order = signal(0);
  _id = '';

  constructor() {
    super();
    this.heading = '';
  }

  connectedCallback(): void {
    super.connectedCallback?.();
    this._id ||= `ui-command-group-${++uid}`;
    (this.closest(ROOT) as UiCommand | null)?._partConnected();
  }

  updated(changedProperties: Map<string, unknown>): void {
    super.updated?.(changedProperties);
    this.style.order = this.order.get() ? String(this.order.get()) : '';
    this.hidden = !this.shown.get();
  }

  render() {
    // No id before connect (the server never connects an element), so the
    // served group is named by aria-label instead of a shared `-heading` id.
    const headingId = this.heading && this._id ? `${this._id}-heading` : nothing;
    return html`<div data-slot="command-group" cmdk-group="" role="presentation" class=${cn(commandGroupClass(), takeAuthored(this))}>${this.heading
      ? html`<div cmdk-group-heading="" aria-hidden="true" id=${headingId}>${this.heading}</div>`
      : ''}<div cmdk-group-items="" role="group" aria-labelledby=${headingId} aria-label=${this.heading && !headingId ? this.heading : nothing} class="flex flex-col"><slot></slot></div></div>`;
  }
}
UiCommandGroup.register('ui-command-group');

// --------------------------------------------------------------------------
// <ui-command-separator>
// --------------------------------------------------------------------------

export class UiCommandSeparator extends WebComponent {
  readonly shown = signal(true);
  constructor() {
    super();
  }

  connectedCallback(): void {
    super.connectedCallback?.();
    (this.closest(ROOT) as UiCommand | null)?._partConnected();
  }

  render() {
    return html`<div data-slot="command-separator" cmdk-separator="" role="separator" ?hidden=${!this.shown.get()} class=${commandSeparatorClass()}></div>`;
  }
}
UiCommandSeparator.register('ui-command-separator');

// --------------------------------------------------------------------------
// <ui-command-item>
// --------------------------------------------------------------------------

export class UiCommandItem extends WebComponent({
  value: String,
  keywords: String,
  disabled: Boolean,
  checked: Boolean,
}) {
  readonly state = signal<ItemState>({ visible: true, selected: false, order: 0 });
  _id = '';

  constructor() {
    super();
    this.value = '';
    this.keywords = '';
    this.disabled = false;
    this.checked = false;
  }

  connectedCallback(): void {
    super.connectedCallback?.();
    this._id ||= `ui-command-item-${++uid}`;
    (this.closest(ROOT) as UiCommand | null)?._partConnected();
  }

  get optionId(): string {
    return `${this._id}-option`;
  }

  /** The item's value: its `value` attribute, else its text. */
  get itemValue(): string {
    if (this.value) return this.value;
    const text = this.querySelector?.('[data-slot="command-item"]')?.textContent ?? this.textContent ?? '';
    return text.trim();
  }

  scrollIntoViewIfShown(): void {
    const option = this.querySelector?.<HTMLElement>('[data-slot="command-item"]');
    if (option && typeof option.scrollIntoView === 'function') option.scrollIntoView({ block: 'nearest' });
  }

  updated(changedProperties: Map<string, unknown>): void {
    super.updated?.(changedProperties);
    const { order, visible } = this.state.get();
    this.style.order = order ? String(order) : '';
    this.hidden = !visible;
  }

  render() {
    const s = this.state.get();
    return html`<div
      data-slot="command-item"
      cmdk-item=""
      role="option"
      id=${this._id ? this.optionId : nothing}
      aria-selected=${s.selected ? 'true' : 'false'}
      data-selected=${s.selected ? 'true' : 'false'}
      aria-disabled=${this.disabled ? 'true' : nothing}
      data-disabled=${this.disabled ? 'true' : 'false'}
      data-checked=${this.checked ? 'true' : nothing}
      data-value=${this.value || nothing}
      class=${cn(commandItemClass(), takeAuthored(this))}
      @pointermove=${this._onPointerMove}
      @click=${this._onClick}
    ><slot></slot><svg
      xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"
      class=${commandItemIndicatorClass()}
    ><path d="M20 6 9 17l-5-5"></path></svg></div>`;
  }

  _onPointerMove = (): void => {
    if (this.state.get().selected) return;
    (this.closest(ROOT) as UiCommand | null)?.selectItem(this);
  };

  _onClick = (e: Event): void => {
    // A click on a link inside follows it natively; run the item's event too.
    const root = this.closest(ROOT) as UiCommand | null;
    if (!root || this.disabled) return;
    const onLink = (e.target as Element).closest('a[href]');
    const ok = this.dispatchEvent(new CustomEvent('ui-select', { bubbles: true, cancelable: true, detail: { value: this.itemValue } }));
    if (!ok && onLink) e.preventDefault();
  };
}
UiCommandItem.register('ui-command-item');

// --------------------------------------------------------------------------
// <ui-command-shortcut>
// --------------------------------------------------------------------------

export class UiCommandShortcut extends WebComponent {
  // The span is the item's flex item, as shadcn's CommandShortcut is, so the
  // styles' `ml-auto` pushes it to the end of the row. A shortcut never hides
  // itself, so unlike the other parts its host can be display: contents,
  // turned off through its style, which the server serves.
  render() {
    const authored = takeAuthored(this);
    if (typeof this.getAttribute === 'function' && !this.getAttribute('style')) this.setAttribute('style', 'display: contents');
    return html`<span data-slot="command-shortcut" class=${cn(commandShortcutClass(), authored)}><slot></slot></span>`;
  }
}
UiCommandShortcut.register('ui-command-shortcut');

// --------------------------------------------------------------------------
// <ui-command-dialog>
// --------------------------------------------------------------------------

/**
 * A command in a native modal dialog: a `<ui-dialog>` whose content the
 * element renders itself, with a screen-reader title and description, around
 * the `<ui-command>` you put inside, as in shadcn's CommandDialog.
 */
export class UiCommandDialog extends UiDialog {
  static rootTag = 'ui-command-dialog';
  static contentTag = 'ui-command-dialog-content';
  static slotPrefix = 'dialog';

  // shadcn's CommandDialog passes its className to the DialogContent, so the
  // class written on this host goes to the content, which puts it on the panel.
  _authored: string | null = null;

  render() {
    this._authored = takeAuthoredClass(this, null);
    const title = this.getAttribute?.('title') || 'Command Palette';
    const description = this.getAttribute?.('description') || 'Search for a command to run...';
    const close = this.getAttribute?.('show-close-button') ?? 'false';
    return html`<div data-slot="dialog" data-state=${this.open ? 'open' : 'closed'}><ui-command-dialog-content
      show-close-button=${close} class=${this._authored}><h2 data-slot="dialog-title" class="sr-only">${title}</h2><p
      data-slot="dialog-description" class="sr-only">${description}</p><slot></slot></ui-command-dialog-content></div>`;
  }
}
UiCommandDialog.register('ui-command-dialog');

export class UiCommandDialogContent extends UiDialogContent {
  static rootTag = 'ui-command-dialog';
  static slotPrefix = 'dialog';

  _panelClass(): string {
    return cn(super._panelClass(), commandDialogClass());
  }
}
UiCommandDialogContent.register('ui-command-dialog-content');
````

### Update the import paths to match your project setup.

## Usage

```ts
import '#components/ui/command.ts';
```

```ts
<ui-command label="Command menu" class="max-w-sm rounded-lg border">
  <ui-command-input placeholder="Type a command or search..."></ui-command-input>
  <ui-command-list>
    <ui-command-empty>No results found.</ui-command-empty>
    <ui-command-group heading="Suggestions">
      <ui-command-item>Calendar</ui-command-item>
      <ui-command-item>Search Emoji</ui-command-item>
      <ui-command-item>Calculator</ui-command-item>
    </ui-command-group>
    <ui-command-separator></ui-command-separator>
    <ui-command-group heading="Settings">
      <ui-command-item>Profile</ui-command-item>
      <ui-command-item>Billing</ui-command-item>
      <ui-command-item>Settings</ui-command-item>
    </ui-command-group>
  </ui-command-list>
</ui-command>
```

## Composition

Use the following composition to build a command:

```text
ui-command
├── ui-command-input
└── ui-command-list
    ├── ui-command-empty
    ├── ui-command-group
    │   ├── ui-command-item
    │   └── ui-command-item
    ├── ui-command-separator
    └── ui-command-group
        ├── ui-command-item
        └── ui-command-item
```

## Basic

A simple command menu in a dialog. It is a [Dialog](https://webjs.dev/ui/docs/components/dialog) whose content takes `commandDialogClass()` and holds the command, with its title and description for screen readers only.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { commandDialogClass } from '#components/ui/command.ts';

// shadcn's CommandDialog is a Dialog around a Command, so the button opens a
// <ui-dialog> whose content holds the command, with the title and the
// description for screen readers only.
export default function CommandBasic() {
  return html`
    <div class="flex flex-col gap-4">
      <ui-dialog>
        <ui-dialog-trigger>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit')}>Open Menu</button>
        </ui-dialog-trigger>
        <ui-dialog-content show-close-button="false" class=${commandDialogClass()}>
          <div data-slot="dialog-header" class="sr-only">
            <h2 data-slot="dialog-title">Command Palette</h2>
            <p data-slot="dialog-description">Search for a command to run...</p>
          </div>
          <ui-command label="Command Palette">
            <ui-command-input placeholder="Type a command or search..."></ui-command-input>
            <ui-command-list>
              <ui-command-empty>No results found.</ui-command-empty>
              <ui-command-group heading="Suggestions">
                <ui-command-item>Calendar</ui-command-item>
                <ui-command-item>Search Emoji</ui-command-item>
                <ui-command-item>Calculator</ui-command-item>
              </ui-command-group>
            </ui-command-list>
          </ui-command>
        </ui-dialog-content>
      </ui-dialog>
    </div>
  `;
}
```

## Shortcuts

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { commandDialogClass } from '#components/ui/command.ts';
import { CreditCardIcon, SettingsIcon, UserIcon } from '#lib/ui/lucide.ts';

export default function CommandWithShortcuts() {
  return html`
    <div class="flex flex-col gap-4">
      <ui-dialog>
        <ui-dialog-trigger>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit')}>Open Menu</button>
        </ui-dialog-trigger>
        <ui-dialog-content show-close-button="false" class=${commandDialogClass()}>
          <div data-slot="dialog-header" class="sr-only">
            <h2 data-slot="dialog-title">Command Palette</h2>
            <p data-slot="dialog-description">Search for a command to run...</p>
          </div>
          <ui-command label="Command Palette">
            <ui-command-input placeholder="Type a command or search..."></ui-command-input>
            <ui-command-list>
              <ui-command-empty>No results found.</ui-command-empty>
              <ui-command-group heading="Settings">
                <ui-command-item>
                  ${UserIcon()}
                  <span>Profile</span>
                  <ui-command-shortcut>⌘P</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${CreditCardIcon()}
                  <span>Billing</span>
                  <ui-command-shortcut>⌘B</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${SettingsIcon()}
                  <span>Settings</span>
                  <ui-command-shortcut>⌘S</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
            </ui-command-list>
          </ui-command>
        </ui-dialog-content>
      </ui-dialog>
    </div>
  `;
}
```

## Groups

A command menu with groups, icons and separators.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { commandDialogClass } from '#components/ui/command.ts';
import {
  CalculatorIcon, CalendarIcon, CreditCardIcon, SettingsIcon, SmileIcon, UserIcon,
} from '#lib/ui/lucide.ts';

export default function CommandWithGroups() {
  return html`
    <div class="flex flex-col gap-4">
      <ui-dialog>
        <ui-dialog-trigger>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit')}>Open Menu</button>
        </ui-dialog-trigger>
        <ui-dialog-content show-close-button="false" class=${commandDialogClass()}>
          <div data-slot="dialog-header" class="sr-only">
            <h2 data-slot="dialog-title">Command Palette</h2>
            <p data-slot="dialog-description">Search for a command to run...</p>
          </div>
          <ui-command label="Command Palette">
            <ui-command-input placeholder="Type a command or search..."></ui-command-input>
            <ui-command-list>
              <ui-command-empty>No results found.</ui-command-empty>
              <ui-command-group heading="Suggestions">
                <ui-command-item>
                  ${CalendarIcon()}
                  <span>Calendar</span>
                </ui-command-item>
                <ui-command-item>
                  ${SmileIcon()}
                  <span>Search Emoji</span>
                </ui-command-item>
                <ui-command-item>
                  ${CalculatorIcon()}
                  <span>Calculator</span>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="Settings">
                <ui-command-item>
                  ${UserIcon()}
                  <span>Profile</span>
                  <ui-command-shortcut>⌘P</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${CreditCardIcon()}
                  <span>Billing</span>
                  <ui-command-shortcut>⌘B</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${SettingsIcon()}
                  <span>Settings</span>
                  <ui-command-shortcut>⌘S</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
            </ui-command-list>
          </ui-command>
        </ui-dialog-content>
      </ui-dialog>
    </div>
  `;
}
```

## Scrollable

Scrollable command menu with multiple items.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { commandDialogClass } from '#components/ui/command.ts';
import {
  BellIcon, CalculatorIcon, CalendarIcon, ClipboardPasteIcon, CodeIcon, CopyIcon,
  CreditCardIcon, FileTextIcon, FolderIcon, FolderPlusIcon, HelpCircleIcon, HomeIcon,
  ImageIcon, InboxIcon, LayoutGridIcon, ListIcon, PlusIcon, ScissorsIcon, SettingsIcon,
  TrashIcon, UserIcon, ZoomInIcon, ZoomOutIcon,
} from '#lib/ui/lucide.ts';

export default function CommandManyItems() {
  return html`
    <div class="flex flex-col gap-4">
      <ui-dialog>
        <ui-dialog-trigger>
          <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${cn(buttonClass({ variant: 'outline' }), 'w-fit')}>Open Menu</button>
        </ui-dialog-trigger>
        <ui-dialog-content show-close-button="false" class=${commandDialogClass()}>
          <div data-slot="dialog-header" class="sr-only">
            <h2 data-slot="dialog-title">Command Palette</h2>
            <p data-slot="dialog-description">Search for a command to run...</p>
          </div>
          <ui-command label="Command Palette">
            <ui-command-input placeholder="Type a command or search..."></ui-command-input>
            <ui-command-list>
              <ui-command-empty>No results found.</ui-command-empty>
              <ui-command-group heading="Navigation">
                <ui-command-item>
                  ${HomeIcon()}
                  <span>Home</span>
                  <ui-command-shortcut>⌘H</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${InboxIcon()}
                  <span>Inbox</span>
                  <ui-command-shortcut>⌘I</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${FileTextIcon()}
                  <span>Documents</span>
                  <ui-command-shortcut>⌘D</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${FolderIcon()}
                  <span>Folders</span>
                  <ui-command-shortcut>⌘F</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="Actions">
                <ui-command-item>
                  ${PlusIcon()}
                  <span>New File</span>
                  <ui-command-shortcut>⌘N</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${FolderPlusIcon()}
                  <span>New Folder</span>
                  <ui-command-shortcut>⇧⌘N</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${CopyIcon()}
                  <span>Copy</span>
                  <ui-command-shortcut>⌘C</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${ScissorsIcon()}
                  <span>Cut</span>
                  <ui-command-shortcut>⌘X</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${ClipboardPasteIcon()}
                  <span>Paste</span>
                  <ui-command-shortcut>⌘V</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${TrashIcon()}
                  <span>Delete</span>
                  <ui-command-shortcut>⌫</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="View">
                <ui-command-item>
                  ${LayoutGridIcon()}
                  <span>Grid View</span>
                </ui-command-item>
                <ui-command-item>
                  ${ListIcon()}
                  <span>List View</span>
                </ui-command-item>
                <ui-command-item>
                  ${ZoomInIcon()}
                  <span>Zoom In</span>
                  <ui-command-shortcut>⌘+</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${ZoomOutIcon()}
                  <span>Zoom Out</span>
                  <ui-command-shortcut>⌘-</ui-command-shortcut>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="Account">
                <ui-command-item>
                  ${UserIcon()}
                  <span>Profile</span>
                  <ui-command-shortcut>⌘P</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${CreditCardIcon()}
                  <span>Billing</span>
                  <ui-command-shortcut>⌘B</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${SettingsIcon()}
                  <span>Settings</span>
                  <ui-command-shortcut>⌘S</ui-command-shortcut>
                </ui-command-item>
                <ui-command-item>
                  ${BellIcon()}
                  <span>Notifications</span>
                </ui-command-item>
                <ui-command-item>
                  ${HelpCircleIcon()}
                  <span>Help &amp; Support</span>
                </ui-command-item>
              </ui-command-group>
              <ui-command-separator></ui-command-separator>
              <ui-command-group heading="Tools">
                <ui-command-item>
                  ${CalculatorIcon()}
                  <span>Calculator</span>
                </ui-command-item>
                <ui-command-item>
                  ${CalendarIcon()}
                  <span>Calendar</span>
                </ui-command-item>
                <ui-command-item>
                  ${ImageIcon()}
                  <span>Image Editor</span>
                </ui-command-item>
                <ui-command-item>
                  ${CodeIcon()}
                  <span>Code Editor</span>
                </ui-command-item>
              </ui-command-group>
            </ui-command-list>
          </ui-command>
        </ui-dialog-content>
      </ui-dialog>
    </div>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import {
  CalculatorIcon, CalendarIcon, CreditCardIcon, SettingsIcon, SmileIcon, UserIcon,
} from '#lib/ui/lucide.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      placeholder: 'Type a command or search...',
      empty: 'No results found.',
      suggestions: 'Suggestions',
      calendar: 'Calendar',
      searchEmoji: 'Search Emoji',
      calculator: 'Calculator',
      settings: 'Settings',
      profile: 'Profile',
      billing: 'Billing',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      placeholder: 'اكتب أمرًا أو ابحث...',
      empty: 'لم يتم العثور على نتائج.',
      suggestions: 'اقتراحات',
      calendar: 'التقويم',
      searchEmoji: 'البحث عن الرموز التعبيرية',
      calculator: 'الآلة الحاسبة',
      settings: 'الإعدادات',
      profile: 'الملف الشخصي',
      billing: 'الفوترة',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      placeholder: 'הקלד פקודה או חפש...',
      empty: 'לא נמצאו תוצאות.',
      suggestions: 'הצעות',
      calendar: 'לוח שנה',
      searchEmoji: "חפש אמוג'י",
      calculator: 'מחשבון',
      settings: 'הגדרות',
      profile: 'פרופיל',
      billing: 'חיוב',
    },
  },
};

// The provider is the dir attribute: every part styles itself with logical
// properties, so dir="rtl" on the command flips the whole menu.
export default function CommandRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <ui-command label=${t.suggestions} dir=${dir} lang=${lang} class="max-w-sm rounded-lg border">
      <ui-command-input placeholder=${t.placeholder}></ui-command-input>
      <ui-command-list>
        <ui-command-empty>${t.empty}</ui-command-empty>
        <ui-command-group heading=${t.suggestions}>
          <ui-command-item>
            ${CalendarIcon()}
            <span>${t.calendar}</span>
          </ui-command-item>
          <ui-command-item>
            ${SmileIcon()}
            <span>${t.searchEmoji}</span>
          </ui-command-item>
          <ui-command-item disabled>
            ${CalculatorIcon()}
            <span>${t.calculator}</span>
          </ui-command-item>
        </ui-command-group>
        <ui-command-separator></ui-command-separator>
        <ui-command-group heading=${t.settings}>
          <ui-command-item>
            ${UserIcon()}
            <span>${t.profile}</span>
            <ui-command-shortcut>⌘P</ui-command-shortcut>
          </ui-command-item>
          <ui-command-item>
            ${CreditCardIcon()}
            <span>${t.billing}</span>
            <ui-command-shortcut>⌘B</ui-command-shortcut>
          </ui-command-item>
          <ui-command-item>
            ${SettingsIcon()}
            <span>${t.settings}</span>
            <ui-command-shortcut>⌘S</ui-command-shortcut>
          </ui-command-item>
        </ui-command-group>
      </ui-command-list>
    </ui-command>
  `;
}
```

## API Reference

The command follows cmdk's model, built on the platform: typing in the input filters and ranks the items, the arrow keys move a selection while focus stays in the input, and Enter runs the selected item.

### Elements

| Element | Description |
| --- | --- |
| `<ui-command>` | The root. Holds the search and the selection. |
| `<ui-command-input>` | The search field, a `role="combobox"` input that keeps focus and points at the selected item through `aria-activedescendant`. |
| `<ui-command-list>` | The `role="listbox"` holding the groups and items. |
| `<ui-command-empty>` | Shown when nothing matches the search. |
| `<ui-command-group>` | A group of items under a heading, hidden when none of its items match. |
| `<ui-command-item>` | One action, a `role="option"` carrying `data-selected="true"` while selected. |
| `<ui-command-shortcut>` | A keyboard shortcut hint at the end of an item. |
| `<ui-command-separator>` | A divider between groups, hidden while a search runs. |
| `<ui-command-dialog>` | A `<ui-command>` in a native modal dialog, with a screen-reader title and description. Open it with `show()`, or compose a Dialog as the demos above do. |

### ui-command

| Attribute | Type | Default |
| --- | --- | --- |
| `label` | `string`, the name a screen reader reads | - |
| `should-filter` | `"true" \| "false"` | `"true"` |
| `loop` | `boolean` | `false` |
| `value` | `string`, the selected item's value, reflected | - |

`should-filter="false"` leaves filtering to you, for a list a server action returns.

### ui-command-input

| Attribute | Type | Default |
| --- | --- | --- |
| `placeholder` | `string` | - |

### ui-command-group

| Attribute | Type | Default |
| --- | --- | --- |
| `heading` | `string` | - |

### ui-command-item

| Attribute | Type | Default |
| --- | --- | --- |
| `value` | `string` | The item's text |
| `keywords` | `string`, space separated, matched by the search | - |
| `disabled` | `boolean` | `false` |

An item that holds a link follows it when it runs.

### ui-command-dialog

| Attribute | Type | Default |
| --- | --- | --- |
| `open` | `boolean`, reflected | `false` |
| `title` | `string` | `"Command Palette"` |
| `description` | `string` | `"Search for a command to run..."` |
| `show-close-button` | `"true" \| "false"` | `"false"` |

### Events

| Event | Detail | Fires |
| --- | --- | --- |
| `ui-select` | `{ value: string }` | On the item, when it runs (Enter or a click). Cancelable: cancel it to stop a link inside the item from being followed. |
| `ui-value-change` | `{ value: string }` | On `<ui-command>`, as the selection moves. |
| `ui-search-change` | `{ search: string }` | On `<ui-command>`, as the search text changes. |

### Keyboard

ArrowDown and ArrowUp (and Ctrl+N / Ctrl+P, Ctrl+J / Ctrl+K) move the selection, `loop` wraps it, Home and End jump to the ends, and Enter runs the selected item. Pointing at an item selects it.
