Command

Command é o primitivo para paletas de comandos estilo ⌘K — uma busca com resultados filtrados, agrupados e navegáveis por teclado. É construído sobre cmdk e pode ser usado inline em uma página ou dentro de um Dialog para virar uma paleta global.

'use client';

import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from '@uranus-workspace/design-system';
import { CreditCard, FileText, Plus, Settings, User, Users } from 'lucide-react';

export default function CommandDefault() {
  return (
    <Command className="w-full max-w-md rounded-lg border shadow-md">
      <CommandInput placeholder="Buscar páginas, ações e configurações…" />
      <CommandList>
        <CommandEmpty>Nenhum resultado encontrado.</CommandEmpty>
        <CommandGroup heading="Sugestões">
          <CommandItem>
            <FileText />
            Novo documento
            <CommandShortcut>⌘N</CommandShortcut>
          </CommandItem>
          <CommandItem>
            <Plus />
            Criar projeto
            <CommandShortcut>⌘P</CommandShortcut>
          </CommandItem>
          <CommandItem>
            <Users />
            Convidar membro da equipe
          </CommandItem>
        </CommandGroup>
        <CommandSeparator />
        <CommandGroup heading="Configurações">
          <CommandItem>
            <User />
            Perfil
            <CommandShortcut>⇧⌘P</CommandShortcut>
          </CommandItem>
          <CommandItem>
            <CreditCard />
            Faturamento
          </CommandItem>
          <CommandItem>
            <Settings />
            Preferências
            <CommandShortcut>⌘,</CommandShortcut>
          </CommandItem>
        </CommandGroup>
      </CommandList>
    </Command>
  );
}

Anatomia

• Command — raiz que mantém o estado do filtro e do item selecionado.
• CommandInput — o campo de busca no topo, já inclui um ícone de lupa.
• CommandList — o container rolável dos resultados.
• CommandEmpty — mensagem exibida quando nenhum item corresponde à busca.
• CommandGroup — agrupa itens relacionados sob um heading.
• CommandItem — linha individual, selecionável via teclado ou mouse.
• CommandSeparator — divisor entre grupos.
• CommandShortcut — texto alinhado à direita, para atalhos.
• CommandDialog — wrapper que renderiza o Command dentro de um diálogo modal.

Uso

import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
} from '@uranus-workspace/design-system';

<Command>
  <CommandInput placeholder="Buscar…" />
  <CommandList>
    <CommandEmpty>Nenhum resultado.</CommandEmpty>
    <CommandGroup heading="Sugestões">
      <CommandItem>Novo documento</CommandItem>
      <CommandItem>Criar projeto</CommandItem>
    </CommandGroup>
    <CommandSeparator />
    <CommandGroup heading="Configurações">
      <CommandItem>Perfil</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

Para transformá-lo em uma paleta global disparada por ⌘K, envolva em CommandDialog e controle open a partir de um useEffect que ouve o atalho.

Faça

• Use CommandGroup com heading para dar contexto aos resultados.
• Escreva rótulos no imperativo ("Criar projeto", "Abrir configurações"), igual aos demais menus.
• Inclua sempre um CommandEmpty — a paleta fica quebrada sem feedback de "nada encontrado".
• Mostre o atalho global (⌘K) na UI para que o usuário descubra a paleta.

Não faça

• Não use Command para listas curtas e estáticas — um Select ou DropdownMenu serve melhor.
• Não coloque mais do que umas poucas dezenas de itens visíveis de uma vez; confie no filtro por busca.
• Não esconda o CommandInput — a paleta sem busca é apenas uma lista.

Acessibilidade

• cmdk expõe o input como role="combobox" e a lista como role="listbox", seguindo o padrão WAI-ARIA Combobox.
• Teclado: Setas cima/baixo movem o item selecionado, Enter dispara, Esc fecha (quando dentro de CommandDialog).
• O item ativo tem aria-selected="true" e um data-selected="true" para estilo.
• Quando usado dentro de CommandDialog, o foco fica preso e retorna ao trigger ao fechar, como qualquer diálogo.