mad-dbunique-search-field

Tres componentes manuais (:options em PHP) + duas versoes DB (auto-query AJAX).

Visao geral#

Componente	Tipo	Para que serve
<mad-search-field>	input text	Busca livre (search box de filtro/listagem). Nao seleciona valor de uma lista.
<mad-unique-search-field>	select MAD Select	Selecao unica com busca em options pre-carregadas
<mad-multi-search-field>	select multiple MAD Select	Selecao multipla com busca, suporta mode="comma" ou mode="table" (pivot)
<mad-dbunique-search-field>	select MAD Select AJAX	Selecao unica com busca server-side no banco via MadDbSearchService
<mad-dbmulti-search-field>	select multiple MAD Select AJAX	Selecao multipla com busca server-side, suporta mode="comma" ou mode="table"

"MAD Select" é o widget JS próprio do framework (não usa nenhuma lib de terceiros) que dá busca/filtro client-side a um <select> nativo.

Os search-fields manuais recebem :options prontas. Os db variants fazem busca AJAX com config criptografada — usar para listas grandes (200+ registros). Para listas medias com busca client-side use <mad-dbcombo-field> (ver dbcombo-rules.md).

---

<mad-search-field> — Busca livre#

Input type="search" com icone de lupa e botao de limpar. Usado em toolbars de filtro, NAO grava valor selecionado de uma lista.

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo
label	string	''	Label
placeholder	string	'Pesquisar...'	Placeholder
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false
attrs	string	''	Atributos HTML extras

Uso#

<mad-search-field name="busca" label="Buscar" placeholder="Nome ou codigo..." />

Em filtro de listagem#

<mad-form submit="onReload">
    <mad-form-grid :cols="2">
        <mad-search-field name="busca" label="Busca rapida" placeholder="Nome, email, CPF..." />
        <mad-dbcombo-field name="status" label="Status" model="Estado" display="nome" />
    </mad-form-grid>
    <mad-form-actions>
        <mad-btn type="submit" variant="primary" icon="search">Buscar</mad-btn>
    </mad-form-actions>
</mad-form>

---

<mad-unique-search-field> — Selecao unica com busca#

Select MAD Select com 1 valor. Usuario digita para filtrar opcoes. Use quando ja tem o array de opcoes em memoria (do contrario, prefira <mad-dbcombo-field>).

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo
label	string	''	Label
options	array	[]	[id => label, ...]
selected	string	''	Valor pre-selecionado
placeholder	string	'Selecione...'
min-length	int	0	Caracteres minimos antes de filtrar
hint	string	''
error	string	''
required	bool	false
disabled	bool	false
attrs	string	''	Atributos HTML extras

Uso basico#

<mad-unique-search-field name="produto_id" label="Produto" :options="$produtos" />

Com pre-selecionado#

<mad-unique-search-field name="vendedor_id" label="Vendedor"
    :options="$vendedores" :selected="$pedido->vendedor_id" />

Min-length (so filtra apos N caracteres)#

<mad-unique-search-field name="cliente_id" label="Cliente"
    :options="$clientes" min-length="3"
    placeholder="Digite ao menos 3 letras..." />

---

<mad-multi-search-field> — Selecao multipla com busca#

Select MAD Select com multiplos valores (chips). Suporta dois modos de persistencia: comma (string CSV numa coluna) ou table (tabela pivot 1:N).

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo
label	string	''	Label
options	array	[]	[id => label, ...]
selected	array/string	[]	IDs pre-selecionados (array ou CSV)
placeholder	string	'Selecione...'
min-length	int	0	Caracteres minimos antes de filtrar
max-size	int	0	Maximo de itens (0 = ilimitado)
mode	string	'comma'	comma (CSV na coluna) ou table (pivot)
pivot-model	string	''	Model Eloquent da tabela pivot (mode=table)
foreign-key	string	''	Coluna FK do registro pai (mode=table)
item-key	string	''	Coluna FK do item selecionado (mode=table)
database	string	MAIN_DATABASE	Conexao (mode=table)
hint	string	''
error	string	''
required	bool	false
disabled	bool	false
attrs	string	''	Atributos HTML extras

Mode comma — CSV numa coluna#

<mad-multi-search-field name="tags" label="Tags"
    :options="$tagOptions" />

No banco: tags = '1,5,12'. O form->save() persiste como string. No onEdit, form->fill($record) distribui automaticamente.

Mode table — pivot 1:N#

<mad-multi-search-field name="produtos" label="Produtos do pacote"
    :options="$prodOptions"
    mode="table"
    pivot-model="PacoteProduto"
    foreign-key="pacote_id"
    item-key="produto_id" />

O form->save($pacote) faz delete all + insert na tabela pacote_produto automaticamente no _afterStore(). No onEdit, o componente carrega os IDs ja vinculados via MadRenderContext::loadPivotSelected() — nao precisa fazer nada manual.

Com max-size#

<mad-multi-search-field name="categorias" label="Categorias"
    :options="$catOptions" max-size="3"
    placeholder="Ate 3 categorias" />

---

Evento change (PHP)#

Os tres componentes aceitam mad:change="metodo" via attrs:

<mad-unique-search-field name="cliente_id" label="Cliente"
    :options="$clientes"
    attrs='mad:change="onClienteChange"' />

public function onClienteChange(string $value): void
{
    $cliente = Cliente::findOrFail($value);   // leitura nao precisa de transacao
    $this->form->set('email', $cliente->email);
    $this->form->set('telefone', $cliente->telefone);
}

---

<mad-dbunique-search-field> — Selecao unica com busca AJAX no banco#

MAD Select com load() remoto via MadDbSearchService. Config da query criptografada server-side. Para listas grandes (200+ registros) onde dbcombo carregaria tudo no DOM.

Props DB (alem das props do unique-search)#

Prop	Tipo	Default	Descricao
model	string	''	Classe do model Eloquent (obrigatorio)
database	string	MAIN_DATABASE	Conexao
key	string	'id'	Campo PK
display	string	'nome'	Campo de exibicao. Aceita template {nome} - {documento}
order-by	string	''	Ordenacao
query	Builder|null	null	Eloquent/Query Builder já filtrado (:query="..."), alternativa a model+filters
filters	array	[]	[['campo','op','val'], ...]
depends-on	string	''	Campo pai para cascata
depends-column	string	depends-on	Coluna do model a filtrar
min-length	int	3	Chars minimos para buscar
placeholder	string	'Digite para buscar...'	Sobrescreve o default herdado do unique-search ('Selecione...') — texto adequado ao fluxo de busca AJAX

Uso#

<mad-dbunique-search-field name="pessoa_id" label="Pessoa"
    model="Pessoa" display="{nome} - {documento}"
    min-length="2" placeholder="Buscar pessoa..." required />

Com depends-on#

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

<mad-dbunique-search-field name="cidade_id" label="Cidade"
    model="Cidade" display="nome"
    depends-on="estado_id" depends-column="estado_id" min-length="2" />

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

O <mad-dbunique-search-field> aceita filhos <fill> que preenchem OUTROS campos do formulario com dados do registro selecionado. O preenchimento e server-side: ao escolher a opcao, o componente busca o registro e devolve os valores prontos (nada de logica no browser).

<mad-dbunique-search-field name="pessoa_id" label="Pessoa"
    model="Pessoa" display="{nome} - {documento}" min-length="2">
    <fill field="email"  from="email" />
    <fill field="cidade" from="cidade->nome" />
    <fill field="nasc"   from="data_nasc" transform="date:d/m/Y" only-empty />
</mad-dbunique-search-field>

Aceitam <fill> como filho: <mad-dbunique-search-field>, <mad-dbselect-field> e <mad-dbcombo-field> (selects de banco de valor unico). Multi-select nao aceita.

Atributos do <fill>#

Prop	Tipo	Default	Descricao
field	string	—	Obrigatorio. Campo do FORMULARIO a preencher (destino)
from	string	—	Obrigatorio. Coluna do registro, caminho de relacao (cidade->estado->sigla) ou template {nome} ({sigla})
transform	string	''	DSL server-side aplicada ao valor (ver abaixo)
only-empty	bool (flag)	false	So preenche se o campo destino estiver vazio

O compilador (Mad\Form\MadAutoFillCompiler) converte os <fill> numa prop :auto-fill="[...]" do componente pai — voce pode passar o array direto se preferir montar em PHP.

DSL de transform#

Vocabulario fixo (sem eval), encadeavel com |, aplicado esquerda→direita:

Spec	Efeito
upper / lower / title	Caixa do texto
trim	Remove espacos das pontas
date:FMT	Reformata data via Carbon (default d/m/Y)
money	number_format pt-BR, 2 casas (1234.5 → 1.234,50)
number:N	number_format pt-BR, N casas
mask:PADRAO	Preenche placeholders #, 9, A (ex.: mask:###.###.###-##)
Classe::metodo	Callable do dev: metodo(string $valor, ?object $registro): string

Regras de borda: valor vazio retorna ''; spec vazio e passthrough; spec desconhecido ou callable invalido/que lanca faz passthrough + error_log (um typo nunca derruba o auto-fill inteiro).

<fill field="cpf" from="documento" transform="mask:###.###.###-##" />
<fill field="razao" from="nome" transform="trim|upper" />
<fill field="doc_fmt" from="documento" transform="FillTransformer::formataCpf" />

A forma curta FillTransformer::metodo (tambem DocumentTransformer e GridTransformer) e resolvida para \App\Transformer\.... O spec viaja cifrado no token de estado — o cliente nao injeta callable.

---

<mad-dbmulti-search-field> — Selecao multipla com busca AJAX no banco#

MAD Select multi com load() remoto. Suporta mode="comma" (CSV) e mode="table" (pivot 1:N).

Props DB (alem das props do multi-search)#

Mesmas props DB do dbunique-search + props de persistencia do multi-search (mode, pivot-model, foreign-key, item-key).

Uso — mode comma#

<mad-dbmulti-search-field name="tags" label="Tags"
    model="Tag" display="nome" mode="comma" min-length="2" />

Uso — mode table (pivot)#

<mad-dbmulti-search-field name="categorias" label="Categorias"
    model="Categoria" display="nome"
    mode="table" pivot-model="ProdutoCategoria"
    foreign-key="produto_id" item-key="categoria_id"
    min-length="2" />

---

Quando usar cada componente#

Cenario	Usar
Search box de filtro/listagem (texto livre)	<mad-search-field>
Selecao unica com options ja em memoria	<mad-unique-search-field>
Selecao unica com query do banco (lista media, client-side)	<mad-dbcombo-field>
Selecao unica com busca AJAX (lista grande, 200+)	<mad-dbunique-search-field>
Selecao multipla com options em memoria	<mad-multi-search-field>
Selecao multipla com busca AJAX (lista grande)	<mad-dbmulti-search-field>
Selecao multipla salva como CSV em coluna	mode="comma" (manual ou DB)
Selecao multipla salva em tabela pivot	mode="table" (manual ou DB)
Busca com modal grid (varias colunas, paginacao)	<mad-seek> (ver seek-rules.md)
Texto livre com sugestoes do banco	<mad-dbentry-field> (ver dbentry-rules.md)

---

NUNCA fazer#

{{-- ERRADO: usar search-field para selecionar valor de uma lista --}}
<mad-search-field name="cliente_id" label="Cliente" />
{{-- search-field e texto livre, nao tem options --}}

{{-- CERTO: usar unique-search ou dbcombo --}}
<mad-unique-search-field name="cliente_id" label="Cliente" :options="$clientes" />

{{-- ERRADO: usar unique-search quando ja existe model do banco --}}
@php
    $opts = Produto::pluck('nome', 'id')->toArray();
@endphp
<mad-unique-search-field name="produto_id" :options="$opts" />

{{-- CERTO: dbcombo carrega sozinho --}}
<mad-dbcombo-field name="produto_id" label="Produto" model="Produto" display="nome" />

{{-- ERRADO: select multiplo nativo com size --}}
<select name="tags[]" multiple size="5">
    @foreach($tags as $id => $nome)
        <option value="{{ $id }}">{{ $nome }}</option>
    @endforeach
</select>

{{-- CERTO --}}
<mad-multi-search-field name="tags" :options="$tags" />

{{-- ERRADO: persistir multi manualmente em tabela pivot --}}
$this->form->save($pacote);
PacoteProduto::where('pacote_id','=',$pacote->id)->delete();
foreach ($_POST['produtos'] as $pid) { /* insert */ }

{{-- CERTO: declarar mode=table no Blade, save() faz tudo --}}
<mad-multi-search-field name="produtos" :options="$opts"
    mode="table" pivot-model="PacoteProduto"
    foreign-key="pacote_id" item-key="produto_id" />

{{-- ERRADO: montar select com busca via JS de terceiros --}}
<select id="meu-select" class="mad-input"></select>
<script>/* alguma lib externa de combobox com busca */</script>

{{-- CERTO --}}
<mad-unique-search-field name="campo" :options="$opts" />

---

No-results create + quick register (MAD Select)#

Todos os search fields baseados no MAD Select (<mad-unique-search-field>, <mad-multi-search-field>, <mad-dbunique-search-field>, <mad-dbmulti-search-field>) aceitam as mesmas props de no-results do <mad-dbcombo-field> — ver dbcombo-field.md para API detalhada.

Resumo das props:

Prop	Default	Uso
no-results-create-action	''	Classe::metodo — abre form em drawer/modal
no-results-create-label	'Cadastrar novo'
no-results-create-icon	'plus'	Icone Lucide
no-results-create-class	'mad-btn mad-btn-primary mad-btn-sm'
no-results-quick-register-action	''	Classe::metodoEstatico — cadastro inline
no-results-quick-register-label	'Adicionar'
no-results-quick-register-icon	'check'
no-results-quick-register-class	'mad-btn mad-btn-success mad-btn-sm'
no-results-message	''	Texto exibido no topo do bloco

Exemplo em busca AJAX no banco:

<mad-dbunique-search-field name="pessoa_id" label="Pessoa"
    model="Pessoa" display="nome" min-length="2"
    no-results-create-action="PessoaForm::show"
    no-results-quick-register-action="PessoaForm::quickRegister"
    no-results-message="Nao achou? Cadastre:" />

O quickRegister precisa ser metodo estatico publico que recebe ['term' => $nomeDigitado, 'field_name' => ..., 'model' => ..., ...] e retorna ['value' => $id, 'label' => $display].

<mad-search-field> (input text puro) nao suporta essas props — e um campo de busca livre, nao selecao de valor.