Command Palette

Busca global em overlay (`mk-command-palette`) com trigger fixo, campo de busca interno e resultados agrupados.

O mk-command-palette concentra um fluxo de busca rapida em overlay com trigger fixo, campo de busca interno e lista de resultados agrupados. Use quando a aplicacao precisa de um ponto unico para localizar paginas e acoes por teclado ou mouse.

Padrao

Use o trigger como ponto de entrada visual para a busca global. Ao clicar, pressionar Enter ou Space, o overlay abre e leva o foco para o campo de busca interno.

import { MkCommandPalette } from '@db1/makuco-ui-react';

export const commandPaletteItems = [
  {
    label: 'Paginas',
    items: [
      { value: '/clientes', label: 'Clientes', description: '/clientes' },
      { value: '/pedidos', label: 'Pedidos', description: '/pedidos' },
    ],
  },
  {
    label: 'Acoes',
    items: [{ value: 'new-customer', label: 'Novo cliente', description: 'Criar cadastro' }],
  },
];

<MkCommandPalette items={commandPaletteItems} placeholder="Buscar" />

<mk-command-palette [items]="commandPaletteItems" placeholder="Buscar"></mk-command-palette>

Estado vazio

Quando items esta vazio, ou todos os grupos chegam sem itens, o componente exibe um estado vazio centralizado com titulo e descricao configuraveis.

<MkCommandPalette
  open
  items={[]}
  emptyTitle="Inicie sua busca"
  emptyDescription="Procure pelo termo desejado"
/>

<mk-command-palette
  [open]="true"
  [items]="[]"
  empty-title="Inicie sua busca"
  empty-description="Procure pelo termo desejado"
></mk-command-palette>

Com resultados

Passe os grupos via items e controle value conforme necessario. O componente expoe mkChange para atualizar a query e mkSelect para reagir ao item escolhido.

<MkCommandPalette open items={commandPaletteItems} value="cli" />

<mk-command-palette [open]="true" [items]="commandPaletteItems" value="cli"></mk-command-palette>

Navegacao por teclado

A navegacao percorre apenas itens folha, na ordem visual dos grupos. Com loop={true}, a seta continua do ultimo para o primeiro item ao atingir o fim da lista.

<MkCommandPalette open items={commandPaletteItems} value="cli" loop />

<mk-command-palette
  [open]="true"
  [items]="commandPaletteItems"
  value="cli"
  [loop]="true"
></mk-command-palette>

Props

Prop	Tipo	Padrao	Descricao
`items`	`CommandPaletteGroup[]`	`[]`	Lista de grupos com itens folha selecionaveis.
`open`	`boolean`	`false`	Controla a abertura do overlay. Refletido como atributo.
`value`	`string`	`""`	Query atual exibida no campo de busca interno.
`placeholder`	`string`	`"Buscar"`	Texto base do trigger e placeholder do campo interno.
`disabled`	`boolean`	`false`	Desabilita o trigger e impede a abertura do painel.
`emptyTitle`	`string`	`"Inicie sua busca"`	Titulo do estado vazio.
`emptyDescription`	`string`	`"Procure pelo termo desejado"`	Texto auxiliar do estado vazio.
`closeOnBackdrop`	`boolean`	`true`	Fecha o overlay quando o usuario clica fora do painel.
`loop`	`boolean`	`false`	Quando `true`, a navegacao por setas volta ao primeiro item apos o ultimo.

Eventos

Evento	Payload	Descricao
`mkOpen`	`void`	Emitido quando o trigger abre o painel.
`mkClose`	`void`	Emitido ao fechar via `Escape`, backdrop ou selecao.
`mkChange`	`string`	Emitido sempre que a query muda.
`mkSelect`	`CommandPaletteSelectDetail`	Retorna o item selecionado, o grupo pai e a query ativa.

Acessibilidade

O painel usa role="dialog" com aria-modal="true" e rótulo vinculado por aria-labelledby.
O campo de busca é o componente mk-search; o foco é delegado para o input interno ao abrir.
O listbox usa role="listbox" com aria-activedescendant apontando para o item ativo durante a navegação.
Cada opção tem role="option" e aria-selected refletindo o estado de navegação atual.
O foco retorna ao trigger ao fechar; Tab/Shift+Tab ficam presos dentro do overlay.

Tecla	Comportamento
`Enter`	Abre pelo trigger e confirma o item ativo dentro do painel.
`Space`	Abre o painel a partir do trigger.
`ArrowDown` / `ArrowUp`	Navega pelos itens visiveis sem focar os cabecalhos de grupo.
`Escape`	Fecha o overlay e restaura o foco ao trigger.
`Tab` / `Shift + Tab`	Mantem o foco dentro do overlay enquanto ele estiver aberto.