Anatomia do MadComponent

MadComponent (Mad\Component\MadComponent) é a classe base de todo componente reativo do framework — formulários (DRAWER/MODAL), listagens (MadDataGrid extends MadComponent), dashboards, páginas internas (INTERNAL), e até este portal de documentação (MadSitePage extends MadComponent). Entender a anatomia dela é entender a unidade fundamental de UI reativa do MAD.

Estrutura mínima

namespace App\Components\Admin;

use Mad\Component\MadComponent;
use Mad\Form\MadForm;
use Mad\Http\MadResponse;

class PedidoForm extends MadComponent
{
    // Como o framework embrulha o componente quando ele e' aberto
    protected static string $wrapper = self::DRAWER;   // INTERNAL | MODAL | DRAWER
    protected static string $title   = 'Pedido';
    protected static string $size    = 'lg';            // sm | md | lg | xl | CSS direto
    protected static string $side    = 'right';          // right | left (so' DRAWER)

    // Props publicas = state reativo (serializado + criptografado a cada response)
    public int      $pedidoId = 0;
    public MadForm  $form;

    public function mount(int $pedidoId = 0): void
    {
        $this->pedidoId = $pedidoId;
        $this->form     = new MadForm('form');
        // carregado so' na 1a carga (GET) — nao roda de novo em actions AJAX
    }

    public function onSave(): MadResponse
    {
        $pedido = Pedido::updateOrCreate(['id' => $this->pedidoId], $this->form->fields);
        return MadToast::success('Pedido salvo!');
    }

    protected function view(): string|array
    {
        return 'admin.pedido-form';
    }
}

Quatro peças compõem qualquer MadComponent: configuração estática do wrapper (como ele é apresentado), props públicas (o state reativo), hooks de lifecycle (mount() e companhia) e o método abstrato view(), que decide qual template Blade renderizar.

Wrapper — como o componente é apresentado

Quatro props estáticas controlam o "chrome" ao redor do componente — INTERNAL (sem chrome, renderiza direto no main), MODAL (centralizado) ou DRAWER (painel lateral). Cobertura completa, com tamanhos e exemplos de cada um, em Wrappers.

Lifecycle hooks

Ordem real de execução, idêntica entre 1ª carga e ciclo AJAX exceto pelo que dispara antes da action:

Primeira carga (GET, via show()):
    boot() -> mount($params)
           -> [se o request trouxe `method` != 'show': chama esse metodo]
           -> rendering() -> render() -> rendered() -> dehydrate()

Requisicoes AJAX (mad:click, mad:model, mad:submit -> MadComponentHandler::process()):
    boot() -> hydrate() -> updating()/updated() (por prop alterada via mad:model)
           -> a action chamada -> rendering() -> render() -> rendered() -> dehydrate()

public function boot(): void
{
    // Roda em TODA requisicao (1a carga E cada action AJAX).
    // Setup compartilhado: ler config, resolver tenant, abrir algo que toda
    // execucao precisa — nunca operacao que deva rodar so' uma vez.
}

public function mount(MadRequest $req): void
{
    // Roda APENAS na 1a carga (GET). NAO roda de novo em actions subsequentes.
    $this->categoriaId = $req->int('categoria_id');
    $this->produtos    = Produto::where('categoria_id', $this->categoriaId)->get();
}

public function hydrate(): void
{
    // Roda apos restaurar o estado em requisicoes AJAX (nao na 1a carga).
    // Recarregue aqui o que NAO foi serializado no mad_state (relations, etc).
}

public function updating(string $prop, mixed $old, mixed $new): void
{
    // ANTES de uma prop publica mudar via mad:model. Normalize/valide o valor.
}

public function updated(string $prop, mixed $value): void
{
    // APOS a prop mudar. Efeitos colaterais: recalcular total, buscar dados.
    if ($prop === 'quantidade' || $prop === 'valorUnitario') {
        $this->total = $this->quantidade * $this->valorUnitario;
    }
}

public function rendering(): void { /* antes de render() — prepara dados de ultima hora */ }
public function rendered(string $html): void { /* recebe o HTML ja' renderizado */ }
public function dehydrate(): void { /* antes de serializar o estado — limpe props pesadas */ }

public function exception(\Throwable $e, callable $stopPropagation): void
{
    // Capture uma excecao da action atual. Chame $stopPropagation() para
    // tratar o erro localmente em vez de deixar subir como 500/erro generico.
    if ($e instanceof \App\Exceptions\EstoqueInsuficiente) {
        $this->erro = $e->getMessage();
        $stopPropagation();
    }
}

Actions

Métodos públicos chamáveis via mad:click, mad:submit ou mad:change. O framework resolve os argumentos automaticamente por Reflection — por nome, por tipo, ou passando o array inteiro:

// Sem argumentos
public function onSave(): MadResponse { /* ... */ }

// Com argumentos — resolvidos por Reflection (nome do parametro OU tipo)
public function onEdit(int $id): void
{
    $this->registroId = $id;
}

// Tipo array => recebe o payload inteiro (forma legada, ainda suportada)
public function onProcessar(array $params): void { /* ... */ }

// Type-hint MadRequest => injetado automaticamente com os dados da action
public function onFiltrar(MadRequest $req): MadResponse
{
    $this->busca = $req->string('busca');
    return new MadResponse();
}

// Array posicional (ex: linha de field-list) => mapeado por posicao
public function onRowEdit(array $rowData, int $editIndex): void { /* ... */ }

onShow() — nome reservado, não é hook de lifecycle

MadComponent declara public function onShow(): void na base como um no-op vazio. Ele não é chamado automaticamente por show(), mount() ou pelo ciclo AJAX — existe apenas como ponto de entrada nomeado convencional, para que navigate="ClienteForm::onShow({id})" e o parâmetro method do request resolvam sempre para um método existente, em vez de estourar em classes que não o definem.

Variáveis injetadas na view

Toda view de um MadComponent recebe automaticamente:

<h1>{{ $that->titulo }}</h1>
<mad-input-field name="nome" :value="$that->nome" />
<mad-btn mad:click="onSalvar">Salvar</mad-btn>

Defesa contra mass-assignment em mad:model

Valores que chegam via mad:model passam por _isModelAssignable() antes de tocar qualquer prop. Chaves começadas com _ são sempre recusadas; para props públicas, uma blacklist fixa bloqueia nomes sensíveis mesmo que a subclasse declare uma prop pública com esse nome — password, senha, permissions, role, is_admin, tenant_id, created_by/updated_by/deleted_by, _token/csrf_token, entre outras. Props públicas já inicializadas como objeto (ex.: um MadForm) também não podem ser sobrescritas por um escalar vindo do cliente. Subclasses podem reforçar essa regra sobrescrevendo _isModelAssignable().

Subclasses na base do framework

Próximos passos