BaseSearch

Campo de busca para filtrar uma lista ou tabela enquanto a pessoa digita. Tem lupa, botão para limpar e, opcionalmente, o atalho / para chegar ao campo de qualquer ponto da tela.

Buscar contratos

v-model (após 300 ms sem digitar): "" · último Enter: ""

Uso

• Use para filtrar o que já está na tela: contratos, itens da planilha, obras no mapa.
• O label é obrigatório e fica só para o leitor de tela. Diga o que é buscado: "Buscar contratos", não "Buscar". Dentro de um BaseField, o rótulo do BaseField dá o nome e o label pode ficar de fora.
• O placeholder mostra por onde se pode buscar: "Buscar por contrato, obra ou empresa". Ele não substitui o label.
• O v-model atualiza depois de debounce ms sem digitar (300 por padrão), para a lista não piscar a cada tecla. Enter e limpar atualizam na hora.
• Para busca no servidor, ouça o evento search (Enter) ou o v-model, e ligue loading enquanto a resposta não chega.
• Não use para escolher um valor de uma lista fechada: use um seletor.
• A busca do cabeçalho do protótipo, clara sobre o azul da marca, ainda não tem variante aqui: o BaseSearch é desenhado para fundo claro ou escuro de página.

Atalho de teclado

Buscar em todo o sistema

/

Atalho: tecla /

Com shortcut, a tecla / leva o foco ao campo quando o foco não está em outro campo de texto nem dentro de um modal aberto. Ligue em uma busca só por página, normalmente a do cabeçalho. A dica some quando há texto ou quando o campo está em foco.

Estados

Com texto

Carregando

Buscando

Inválido

Somente leitura

Desabilitado

invalid só marca a borda. Para dizer o que corrigir, coloque o campo num BaseField com invalid-text: a mensagem aparece com ícone e o leitor de tela a ouve junto com o campo.

Buscar por número

Use só letras, números e a barra, como em 012/2026.

Sem BaseField, ligue a mensagem pelo aria-describedby, que vai para o <input>: <BaseSearch invalid aria-describedby="erro-busca" />.

Tamanhos

Pequeno

Médio

Grande

Estilo

O campo é o BaseInput; veja BaseField e BaseInput para fundo, borda e estados.

Propriedade	Token
Lupa	--tj-icon-secondary, --tj-icon-sm
Botão limpar	--tj-text-helper; hover --tj-icon-primary sobre --tj-layer-accent-01; pressionado --tj-layer-accent-02; foco contorno de 2 px --tj-border-interactive com --tj-ring
Tamanho do botão limpar	altura do campo menos --tj-space-2 (24, 32 e 40 px)
Dica do atalho	--tj-text-helper sobre --tj-layer-accent-01, borda --tj-border-subtle-02, --tj-text-xs, --tj-radius-sm
Carregando	anel --tj-border-subtle-02 com --tj-interactive, --tj-icon-sm
Altura	--tj-control-sm/md/lg
Movimento	--tj-duration-fast-02, --tj-easing-standard

Código

<BaseSearch
  v-model="termo"
  label="Buscar contratos"
  placeholder="Buscar por contrato, obra ou empresa"
  :loading="carregando"
  shortcut
  @search="buscarNoServidor"
/>

Propriedade	Tipo	Padrão	Descrição
label	string	—	Nome do campo para o leitor de tela; obrigatório fora de um BaseField
v-model	string	''	Termo buscado, atualizado com atraso enquanto se digita
debounce	number	300	Milissegundos sem digitar antes de atualizar o v-model; 0 atualiza a cada tecla
size	'sm' | 'md' | 'lg'	'md'	Altura
placeholder	string	—	Exemplo do que se pode buscar
shortcut	boolean	false	Liga o atalho / e a dica
landmark	boolean	false	Envolve o campo num marco de busca (role="search")
loading	boolean	false	Mostra o indicador e anuncia "Buscando"
disabled, readonly, invalid	boolean	false	Estados; dentro de um BaseField, invalid e required vêm dele

Os outros atributos vão para o <input>: name, aria-controls (o id da lista ou tabela filtrada), aria-describedby (somado à ajuda do BaseField e à dica do atalho), required e autocomplete, que é off por padrão para o histórico do navegador não cobrir o botão limpar. class e style ficam no elemento de fora.

Evento	Carga	Quando
update:modelValue	string	Depois do debounce, no Enter e ao limpar
search	string	No Enter, com o termo atual; ao limpar, com ''

Acessibilidade

• É um <input type="search"> com <label for> escondido visualmente. Com landmark, segue o marco de busca (search landmark) do WAI-ARIA APG: o conjunto vira role="search" com o mesmo nome, para quem navega por marcos. Use landmark só na busca principal da página.
• Teclado: Tab chega no campo e depois no botão limpar; Enter busca na hora; Esc limpa. Com o campo já vazio, Esc segue para o componente pai, então um modal ainda fecha.
• O botão limpar se chama "Limpar busca", aparece só quando há texto e devolve o foco ao campo. O botão nativo do navegador fica escondido para não aparecer duas vezes.
• O atalho / não dispara com Ctrl, Alt ou ⌘, nem quando o foco está em outro campo. AltGr vale, porque é com ele que se digita a barra em teclados ABNT2 sem a tecla /. Com um modal aberto, o foco fica no modal. O campo leva aria-keyshortcuts="/" e o leitor de tela ouve "Atalho: tecla /" junto com ele; a dica visual é decorativa. Com o campo desabilitado, o atalho, a dica e a descrição saem.
• Atalho de uma tecla só (WCAG 2.1.4): ofereça um jeito de desligar, por exemplo uma preferência do usuário ligada à propriedade shortcut.
• loading anuncia "Buscando" numa região role="status" que existe desde o início, para o anúncio não se perder. O indicador gira mais devagar com prefers-reduced-motion.
• Ao terminar a busca, anuncie o resultado (ex.: "12 contratos encontrados") numa região role="status" perto da lista; o BaseSearch só anuncia "Buscando".
• No estado inválido a borda vermelha não basta: use a mensagem do BaseField (texto e ícone), que o campo liga pelo aria-describedby e marca com aria-invalid="true".
• O botão limpar mostra o foco com contorno sólido, e no modo de alto contraste do Windows usa as cores do sistema.
• Funciona nos temas claro e escuro; todas as cores vêm de tokens de papel.
• Testado com axe nos estados padrão, com texto, atalho (vazio, com texto, com marco), desabilitado, somente leitura, inválido, carregando (com e sem texto), tamanhos, dentro de um BaseField e com foco ao começar a carregar.