Dados remotos e carregamento

Componentes visuais não fazem chamadas HTTP. A aplicação escuta os eventos de interação, controla debounce, autenticação, cache e cancelamento e devolve os dados por propriedades, slots ou conteúdo projetado.

Busca em br-select

Use filterable e search-mode="remote". O evento brSelectSearch contém a consulta atual em event.detail.query, inclusive quando ela é limpa.

let requestId = 0;
let controller;

select.addEventListener('brSelectSearch', async ({ detail: { query } }) => {
  controller?.abort();
  const currentRequest = ++requestId;
  controller = new AbortController();
  select.loading = true;

  try {
    const url = new URL('/api/options', location.origin);
    url.searchParams.set('q', query.trim());
    const response = await fetch(url, { signal: controller.signal });
    if (!response.ok) throw new Error('Não foi possível carregar as opções.');
    const result = await response.json();
    if (currentRequest === requestId) await select.setOptions(result.items);
  } catch (error) {
    if (!(error instanceof DOMException && error.name === 'AbortError')) {
      // Mostre uma mensagem role="alert" fora do componente.
    }
  } finally {
    if (currentRequest === requestId) select.loading = false;
  }
});

Defina o limite mínimo de caracteres na aplicação. Por exemplo, antes de consultar o serviço, limpe as opções quando a consulta tiver menos de dois caracteres. O consumidor também pode mapear a resposta para o formato { label, value } antes de chamar setOptions().

O componente preserva a seleção atual quando o item selecionado não aparece na janela de resultados seguinte. O consumidor deve mapear e validar o payload da API antes de passá-lo ao componente.

br-pagination e br-table

br-pagination já emite brPaginationPageChange e brPaginationPerPageChange. Defina loading enquanto busca a página; os controles ficam bloqueados e aria-busy="true" é aplicado.

Use controlled quando a página visível só puder mudar após uma resposta bem-sucedida. Nesse modo, os eventos comunicam page ou perPage, mas a aplicação confirma a mudança atribuindo current ou perPage.

br-table recebe loading enquanto suas linhas são atualizadas. As linhas anteriores permanecem visíveis para evitar mudança de layout; o novo conteúdo continua sendo fornecido pelos slots header e body.

Outros campos

Validação remota em br-input e br-textarea

Para validar disponibilidade, unicidade ou outra regra de domínio no servidor, atribua uma função assíncrona a validator. A função recebe o valor textual e retorna null quando válido ou uma mensagem quando inválido. O componente expõe aria-busy="true", o slot validation-loading e um evento de início e fim da validação. A validação ocorre no change ou quando a aplicação chama validate(); não ocorre a cada tecla.

input.validator = async (value) => {
  const response = await fetch(`/api/usuarios/${encodeURIComponent(value)}`);
  if (!response.ok) throw new Error('Falha ao consultar o usuário.');
  return (await response.json()).available ? null : 'Valor já utilizado.';
};

const valid = await input.validate();

Use AbortController e um identificador de requisição na própria função quando a política da aplicação exigir cancelamento. O componente ignora o resultado de uma validação antiga, mas não cancela automaticamente o fetch. Consulte também as seções de validação do input e do textarea.

Upload assíncrono em br-upload

br-upload aceita uploadHandler como propriedade JavaScript. O callback recebe file, signal e onProgress; endpoint, autenticação e formato da resposta continuam externos. Use brUploadStart, brUploadProgress, brUploadSuccess e brUploadError para atualizar a aplicação. Sem uploadHandler, o componente mantém apenas a seleção e a validação dos arquivos.

upload.uploadHandler = async ({ file, signal, onProgress }) => {
  const body = new FormData();
  body.append('arquivo', file);

  // fetch não expõe progresso de upload; use um cliente que aceite onProgress
  // quando a interface precisar exibir percentual real.
  const response = await fetch('/api/arquivos', { method: 'POST', body, signal });
  if (!response.ok) throw new Error('Falha no envio.');
};

Quando o cliente de transporte oferecer progresso, encaminhe-o por onProgress. cancelUpload() aborta o envio atual pelo AbortSignal.

br-list e br-dropdown são componentes de composição e também não assumem transporte ou estado de dados.