mad-form-* (layout) — Componentes (Admin)

Componentes de estrutura para organizar campos dentro de <mad-form>. Combinam-se livremente para montar qualquer formulário.

Hierarquia típica

<mad-form submit="onSave">
    <mad-form-section title="..." icon="...">         {{-- bloco semântico --}}
        <mad-form-grid :cols="2">                      {{-- campos lado a lado --}}
            <mad-input-field ... />
            <mad-input-field ... />
        </mad-form-grid>

        <mad-form-stack>                               {{-- campos empilhados --}}
            <mad-textarea-field ... />
        </mad-form-stack>
    </mad-form-section>

    <mad-separator />                                  {{-- divisor visual --}}

    <mad-form-section title="..." icon="...">
        ...
    </mad-form-section>

    <mad-form-actions>                                 {{-- botões --}}
        <mad-btn type="submit" variant="primary" icon="save">Salvar</mad-btn>
    </mad-form-actions>
</mad-form>

`<mad-form>` — wrapper

Prop	Tipo	Default	Descrição
`submit`	string	''	Método PHP chamado no submit (ex: `onSave`)
`id`	string	''	ID do form
`class`	string	''	Classes CSS extras
`attrs`	string	''	Atributos HTML extras no `<form>`

`<mad-form-section>` — bloco com título

Bloco semântico com header (ícone + título + linha divisória).

Prop	Tipo	Default	Descrição
`title`	string	''	Título da seção
`subtitle`	string	null	Subtítulo (menor, cinza)
`icon`	string	null	Ícone Lucide
`class`	string	''	Classes CSS extras na `<section>`
`style`	string	''	Estilo inline extra na `<section>`

<mad-form-section title="Dados pessoais" icon="user">
    <mad-form-grid :cols="2">
        <mad-input-field name="nome" label="Nome" required />
        <mad-input-field name="email" label="Email" />
    </mad-form-grid>
</mad-form-section>

<mad-form-section title="Endereço" subtitle="Endereço de entrega" icon="map-pin">
    ...
</mad-form-section>

`<mad-form-grid>` — grid de colunas

Distribui campos em colunas iguais via CSS grid. Responsivo.

Prop	Tipo	Default	Descrição
`cols`	int	2	Colunas: 1 a 6 (ignorado quando `template` é definido)
`gap`	int	4	Espaçamento (indice): 0=0px, 1=4px, 2=8px, 3=12px, 4=16px, 5=20px, 6=24px, 8=32px
`template`	string	null	`grid-template-columns` CSS customizado — sobrescreve `cols`
`class`	string	''	Classes CSS extras
`style`	string	''	Estilo inline extra

<mad-form-grid :cols="2">
    <mad-input-field name="nome" label="Nome" />
    <mad-input-field name="email" label="Email" />
</mad-form-grid>

<mad-form-grid :cols="3">
    <mad-input-field name="cidade" label="Cidade" />
    <mad-dbcombo-field name="estado_id" label="Estado" model="Estado" display="nome" />
    <mad-input-field name="cep" label="CEP" />
</mad-form-grid>

Múltiplos grids na mesma seção

<mad-form-section title="Produto" icon="package">
    <mad-form-grid :cols="2">
        <mad-input-field name="nome" label="Nome" required />
        <mad-input-field name="cod_barras" label="Cod. Barras" />
    </mad-form-grid>
    <mad-form-grid :cols="3">
        <mad-numeric-field name="valor" label="Valor" prefix="R$" />
        <mad-numeric-field name="peso" label="Peso (kg)" />
        <mad-input-field name="unidade" label="Unidade" />
    </mad-form-grid>
</mad-form-section>

Grid com `template` customizado

Quando as colunas não devem ter a mesma largura, template sobrescreve cols com um grid-template-columns CSS literal.

<mad-form-grid template="120px 1fr 80px">
    <mad-input-field name="codigo" label="Código" />
    <mad-input-field name="nome" label="Nome" />
    <mad-input-field name="qtd" label="Qtd." />
</mad-form-grid>

`<mad-form-grid-item>` — item com largura customizada (span)

Filho opcional de <mad-form-grid> para um campo ocupar mais de uma coluna (grid-column: span N), sem precisar quebrar em outro grid.

Prop	Tipo	Default	Descrição
`span`	int	1	Quantidade de colunas que o item ocupa
`class`	string	''	Classes CSS extras

<mad-form-grid :cols="3">
    <mad-form-grid-item :span="2">
        <mad-input-field name="nome" label="Nome" required />
    </mad-form-grid-item>
    <mad-input-field name="cod_barras" label="Cod. Barras" />
</mad-form-grid>

`<mad-form-stack>` — campos empilhados

Flex column com gap. Equivalente a <mad-form-grid :cols="1"> mas semanticamente indica lista vertical, não grid.

Prop	Tipo	Default	Descrição
`gap`	int	4	Espaçamento (mesmos índices de `<mad-form-grid>`: 0=0px … 6=24px, 8=32px)
`class`	string	''	Classes CSS extras

<mad-form-stack>
    <mad-input-field name="titulo" label="Título" required />
    <mad-textarea-field name="descricao" label="Descrição" />
    <mad-html-editor-field name="conteudo" label="Conteúdo" />
</mad-form-stack>

`<mad-form-actions>` — footer de botões

Container flex para botões de ação.

Prop	Tipo	Default	Descrição
`align`	string	`left`	left \| right \| center
`class`	string	''	Classes CSS extras
`style`	string	''	Estilo inline extra

<mad-form-actions>
    <mad-btn type="submit" variant="primary" icon="save">Salvar</mad-btn>
</mad-form-actions>

<mad-form-actions>
    <mad-btn type="submit" variant="primary" icon="search">Buscar</mad-btn>
    <mad-btn variant="ghost" icon="x-circle" mad:click="onLimpar">Limpar</mad-btn>
</mad-form-actions>

<mad-form-actions align="right">
    <mad-btn variant="ghost" close-drawer>Cancelar</mad-btn>
    <mad-btn type="submit" variant="primary" icon="save">Salvar</mad-btn>
</mad-form-actions>

`<mad-separator>` — divisor

Prop	Tipo	Default	Descrição
`label`	string	''	Texto central (divisor com label)
`vertical`	bool	false	Separador vertical (só aplica quando `label` está vazio)
`class`	string	''	Classes CSS extras

<mad-separator />
<mad-separator label="ou" />

Exemplos

CRUD simples (drawer)

<mad-form submit="onSave">
    <mad-form-section title="Dados da unidade" icon="building-2">
        <mad-form-grid :cols="1">
            <mad-input-field name="name" label="Nome" required />
        </mad-form-grid>
    </mad-form-section>

    <mad-separator />

    <mad-form-actions>
        <mad-btn variant="primary" type="submit" icon="save">Salvar</mad-btn>
    </mad-form-actions>
</mad-form>

CRUD com múltiplas seções

<mad-form submit="onSave">
    <mad-form-section title="Dados pessoais" icon="user">
        <mad-form-grid :cols="2">
            <mad-input-field name="nome" label="Nome" required />
            <mad-input-field name="login" label="Login" required />
        </mad-form-grid>
        <mad-form-grid :cols="2">
            <mad-input-field name="email" label="Email" />
            <mad-switch-field name="ativo" label="Ativo" />
        </mad-form-grid>
    </mad-form-section>

    <mad-separator />

    <mad-form-section title="Acesso" icon="lock">
        <mad-form-grid :cols="2">
            <mad-input-field name="password" label="Senha" type="password" />
            <mad-input-field name="repassword" label="Confirmar" type="password" />
        </mad-form-grid>
    </mad-form-section>

    <mad-separator />

    <mad-form-actions>
        <mad-btn variant="primary" type="submit" icon="save">Salvar</mad-btn>
    </mad-form-actions>
</mad-form>

Form com imagem + campos

<mad-form submit="onSave">
    <mad-form-section title="Foto" icon="image">
        <mad-image-field name="foto" label="Foto do produto"
            storage="disk" folder="uploads/fotos"
            crop aspect-ratio="4:3" />
    </mad-form-section>

    <mad-separator />

    <mad-form-section title="Dados" icon="package">
        <mad-form-grid :cols="2">
            <mad-input-field name="nome" label="Nome" required />
            <mad-numeric-field name="valor" label="Valor" prefix="R$" />
        </mad-form-grid>
        <mad-form-grid :cols="1">
            <mad-textarea-field name="descricao" label="Descrição" />
        </mad-form-grid>
    </mad-form-section>

    <mad-separator />

    <mad-form-actions>
        <mad-btn variant="primary" type="submit" icon="save">Salvar</mad-btn>
    </mad-form-actions>
</mad-form>

Quando usar o que

Preciso...	Usar
Agrupar campos com título	`<mad-form-section>`
Campos lado a lado	`<mad-form-grid :cols="N">`
Campos empilhados 100% largura	`<mad-form-stack>` ou `<mad-form-grid :cols="1">`
Divisor entre seções	`<mad-separator />`
Botões de ação	`<mad-form-actions>`
Mudar colunas no meio da seção	Dois `<mad-form-grid>` consecutivos
Um campo ocupar mais de uma coluna dentro do mesmo grid	`<mad-form-grid-item :span="N">`
Colunas com larguras diferentes (não uniformes)	`<mad-form-grid template="...">`

NUNCA fazer

{{-- ERRADO: div com style inline para botões --}}
<div style="display:flex;gap:8px;margin-top:16px;">
    <mad-btn type="submit">Salvar</mad-btn>
</div>

{{-- CERTO --}}
<mad-form-actions>
    <mad-btn type="submit">Salvar</mad-btn>
</mad-form-actions>

{{-- ERRADO: div com style inline para grid --}}
<div style="display:grid;grid-template-columns:1fr 1fr;gap:16px;">
    <mad-input-field ... />
</div>

{{-- CERTO --}}
<mad-form-grid :cols="2">
    <mad-input-field ... />
</mad-form-grid>

{{-- ERRADO: <hr> para separar --}}
<hr style="margin:16px 0;">

{{-- CERTO --}}
<mad-separator />

{{-- ERRADO: form nativo --}}
<form data-mad-submit="onSave">...</form>

{{-- CERTO --}}
<mad-form submit="onSave">...</mad-form>

Hierarquia típica#

<mad-form> — wrapper#

<mad-form-section> — bloco com título#

<mad-form-grid> — grid de colunas#

Múltiplos grids na mesma seção#

Grid com template customizado#

<mad-form-grid-item> — item com largura customizada (span)#

<mad-form-stack> — campos empilhados#

<mad-form-actions> — footer de botões#

<mad-separator> — divisor#

Exemplos#

CRUD simples (drawer)#

CRUD com múltiplas seções#

Form com imagem + campos#

Quando usar o que#

NUNCA fazer#