mad-unique-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"

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 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.

---

<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
width	string	''	Largura do .mad-field (numero puro = px)
max-width	string	''	Largura maxima do .mad-field

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::find($value);
    $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 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	Query builder Eloquent pronta (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

Uso#

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

Auto-fill de outros campos — filhos <fill>#

O <mad-dbunique-search-field> aceita filhos <fill>: ao selecionar um registro, o servidor devolve os campos pedidos e preenche outros campos do formulario — sem escrever JS e sem mad:change. Vale tambem para <mad-dbcombo-field> e <mad-dbselect-field>; os search-fields manuais (<mad-unique-search-field>, <mad-multi-search-field>) e os multi DB nao aceitam <fill>.

Atributos do <fill>:

Atributo	Obrig.	Descricao
field	sim	Campo do FORMULARIO a preencher (destino)
from	sim	Coluna, caminho de relacao (a->b->c) ou template {x} do registro
transform	nao	DSL server-side (Mad\Form\MadFillTransform), ex. date:d/m/Y
only-empty	nao	So preenche se o campo destino estiver vazio

<mad-dbunique-search-field name="cliente_id" label="Cliente"
    model="Cliente" 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>

Use <fill> no lugar de um mad:change que so copia colunas do registro selecionado — o caminho declarativo evita round-trip escrito a mao.

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" />

---

<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')->all();
@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 o enhancement de busca na mao com JS --}}
<select id="meu-select" class="mad-input"></select>
<script>/* código custom pra dar busca/filtro ao select — reinventando o MAD Select */</script>

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

---

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

Todos os search fields com 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-rules.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-quick-fields	[]	Campos extras pedidos no cadastro inline (array)
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.