mad-dbselect-field — Componentes (Admin)

<mad-dbselect-field> é um alias de compatibilidade de <mad-dbcombo-field>: mesmo componente, mesmo HTML, mesmo comportamento (select com busca via o widget MAD Select, auto-query do banco, depends-on para cascata, e no-results-* para cadastro inline). Historicamente dbselect era um <select> nativo sem busca e dbcombo tinha busca — os dois foram unificados num componente só; a tag <mad-dbselect-field> ficou apenas para não quebrar templates existentes.

Para código novo, prefira <mad-dbcombo-field> diretamente — o nome reflete melhor o comportamento atual.

Props

Mesmas props de <mad-dbcombo-field> (ver dbcombo-field.md para a lista completa). Resumo:

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (obrigatorio)
label	string	''	Label do campo
model	string	''	Classe do model Eloquent (obrigatorio, exceto com `:query`)
database	string	MAIN_DATABASE	Conexao do banco
key	string	'id'	Campo PK
display	string	'nome'	Campo de exibicao. Aceita template `{nome} ({sigla})`
order-by	string	display	Ordenacao
filters	array	[]	`[['campo','op','val'], ...]` — vira WHERE no builder
query	Builder\|null	null	Eloquent/Query Builder já filtrado (`:query="$that->metodo()"`). Tem prioridade sobre `model`+`filters`; incompatível com `depends-on`
selected	string	''	Valor pre-selecionado
placeholder	string	'Selecione...'	Opcao vazia
depends-on	string	''	Campo pai para cascata automatica
depends-column	string	depends-on	Coluna do model filho a filtrar
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false
attrs	string	''	Atributos HTML extras
no-results-create-action	string	''	`Classe::metodo` — botao abaixo do campo (abre form em drawer/modal)
no-results-create-label	string	'Cadastrar novo'
no-results-create-icon	string	'plus'
no-results-create-class	string	'mad-btn mad-btn-primary mad-btn-sm'
no-results-quick-register-action	string	''	`Classe::metodoEstatico` — input + botao abaixo do campo (cadastro inline)
no-results-quick-register-label	string	'Adicionar'
no-results-quick-register-icon	string	'check'
no-results-quick-register-class	string	'mad-btn mad-btn-success mad-btn-sm'
no-results-message	string	''	Mensagem exibida no topo do bloco

Uso basico

<mad-dbselect-field name="tipo_id" label="Tipo" model="TipoProduto" display="descricao" />

{{-- equivalente, forma preferida em código novo --}}
<mad-dbcombo-field name="tipo_id" label="Tipo" model="TipoProduto" display="descricao" />

Com filtros

<mad-dbselect-field name="status_id" label="Status" model="StatusPedido" display="nome"
    :filters="[['ativo', '=', '1']]" order-by="ordem" />

Depends-on (cascata)

<mad-dbselect-field name="estado_id" label="Estado" model="Estado" display="nome" />

<mad-dbselect-field name="cidade_id" label="Cidade" model="Cidade" display="nome"
    depends-on="estado_id" depends-column="estado_id" />

Auto-fill com `<fill>` (5.x)

Como select de banco de valor unico, <mad-dbselect-field> aceita filhos <fill> que preenchem outros campos do formulario com dados do registro selecionado (resolucao server-side):

<mad-dbselect-field name="cliente_id" label="Cliente" model="Cliente" display="nome">
    <fill field="email"  from="email" />
    <fill field="cidade" from="cidade->nome" />
    <fill field="cpf"    from="documento" transform="mask:###.###.###-##" only-empty />
</mad-dbselect-field>

Atributos: field (campo destino do form, obrigatorio), from (coluna, caminho de relacao a->b->c ou template {x}, obrigatorio), transform (DSL: upper lower title trim date:FMT money number:N mask:PADRAO Classe::metodo, encadeavel com |) e only-empty (flag — so preenche campo vazio).

API detalhada em dbunique-search.md (secao "Auto-fill com <fill>") — o compilador Mad\Form\MadAutoFillCompiler e o mesmo para os tres selects de banco unicos (dbselect, dbcombo, dbunique-search).

Quando usar dbselect/dbcombo vs dbunique-search

Como hoje os dois renderizam o mesmo widget com busca, a escolha real é entre carregar tudo no DOM (dbcombo/dbselect) ou buscar via AJAX no servidor (dbunique-search):

Cenario	Usar
Lista pequena/media (até ~200 itens), busca client-side	`<mad-dbcombo-field>` (ou `<mad-dbselect-field>`, equivalente)
Lista grande (200+), busca server-side AJAX	`<mad-dbunique-search-field>`
Busca com multiplas colunas visiveis	`<mad-seek>`

NUNCA fazer

{{-- ERRADO: carregar options manualmente do banco --}}
@php $tipos = TipoProduto::pluck('nome', 'id')->toArray(); @endphp
<mad-select-field name="tipo_id" :items="$tipos" />

{{-- CERTO --}}
<mad-dbselect-field name="tipo_id" model="TipoProduto" display="nome" />

{{-- ERRADO: usar dbselect/dbcombo para lista grande --}}
<mad-dbselect-field name="pessoa_id" model="Pessoa" display="nome" />
{{-- 10.000+ registros no DOM --}}

{{-- CERTO: usar dbunique-search (busca AJAX) --}}
<mad-dbunique-search-field name="pessoa_id" model="Pessoa" display="nome" />

Props#

Uso basico#

Com filtros#

Depends-on (cascata)#

Auto-fill com <fill> (5.x)#

Quando usar dbselect/dbcombo vs dbunique-search#

NUNCA fazer#