Data table

<?php

namespace App\Control\Tutor;

use App\Models\TutorDemo\TutorDemoPedido;
use App\Support\Tutor\TutorDemoSeed;
use App\Support\Tutor\TutorPage;
use Illuminate\Database\Eloquent\Builder;

/**
 * TutorGridsDataTable — catálogo grids_data_table (tag única: mad-data-table).
 *
 * <mad-data-table> é read-only: sem actions, edit, search ou paginação.
 * Fonte dos dados, por precedência (packages/mad-framework/src/mad/grid/
 * MadGridCompiler.php::compileDataTableBlock + GridRenderHelpers::
 * renderDataTable): `:query` (Builder pronto) > `model=` (auto-query da tag)
 * > `:items` (array PHP).
 *
 * GOTCHA validado na fonte (GridRenderHelpers::normalizeRows): `{relacao->
 * campo}` só resolve sozinho quando o item por trás é um objeto Eloquent
 * (fontes `:query` e `model=`, que sempre entregam Model). Com `:items`
 * (array puro) não existe objeto pra disparar o lazy-load — por isso
 * pedidosResumo() abaixo já entrega os nomes de cliente/categoria
 * achatados em string, e não usa a notação `{relacao->campo}`.
 */
class TutorGridsDataTable extends TutorPage
{
    protected string $catalogKey = 'grids_data_table';

    public function mount(array $params = []): void
    {
        TutorDemoSeed::ensure();
    }

    /**
     * Linhas achatadas (fonte do exemplo `:items`) — cliente/categoria já
     * resolvidos em string aqui, porque `:items` não lazy-loada relação.
     */
    public function pedidosResumo(int $limit = 30): array
    {
        return TutorDemoPedido::query()
            ->with(['cliente', 'categoria'])
            ->orderByDesc('dt_pedido')
            ->limit($limit)
            ->get()
            ->map(fn (TutorDemoPedido $p) => [
                'pedido'    => $p->descricao,
                'cliente'   => $p->cliente->nome ?? '—',
                'categoria' => $p->categoria->nome ?? '—',
                'data'      => $p->dt_pedido,
                'valor'     => (float) $p->valor_total,
            ])
            ->all();
    }

    /**
     * Builder pronto (fonte do exemplo `:query`) — aqui `{relacao->campo}`
     * resolve sozinho no Blade porque os itens são Model de verdade;
     * with() evita N+1 (a coluna ainda dispara lazy-load se você esquecer).
     */
    public function pedidosQuery(): Builder
    {
        return TutorDemoPedido::query()->with(['cliente', 'estado']);
    }
}

<x-tutor-page page="grids_data_table">
    <mad-callout type="warning" title="mad_validate acusa R045 nestas 4 demos — falso positivo" icon="alert-triangle">
        <code>items</code>, <code>query</code>, <code>model</code>, <code>database</code>,
        <code>filters</code>, <code>order-by</code>, <code>limit</code>, <code>group-by</code> e
        <code>group-mask</code> não estão no schema do <code>mad_props</code> (nem na lista de
        props conhecidas do R045) — mas existem de verdade em
        <code>MadGridCompiler::compileDataTableBlock</code> (packages/mad-framework/src/mad/grid/
        MadGridCompiler.php) e são exatamente o que essas demos usam. Metadado desatualizado, não
        erro de marcação — vale reportar pra quem mantém o schema do MCP.
    </mad-callout>

    <x-tutor-demo demo="tutor.examples.grids-data-table.items"
        title="Fonte :items (array PHP)"
        desc="Sem model — array já achatado (cliente/categoria em string) por TutorGridsDataTable::pedidosResumo()."
        php="TutorGridsDataTable::pedidosResumo" />

    <x-tutor-demo demo="tutor.examples.grids-data-table.query"
        title="Fonte :query (Builder Eloquent)"
        desc="Builder pronto com with(); aqui {relacao->campo} resolve sozinho — os itens são Model de verdade."
        php="TutorGridsDataTable::pedidosQuery" />

    <x-tutor-demo demo="tutor.examples.grids-data-table.model"
        title="Fonte model= direto na tag (zero PHP)"
        desc="model + database + :filters (DSL) resolvidos pelo próprio componente, sem método no controller." />

    <x-tutor-demo demo="tutor.examples.grids-data-table.agrupamento"
        title="Agrupamento (group-by + group-mask + group-total)"
        desc="Mesma fonte :items da 1ª demo, agrupada por categoria com subtotal por grupo." />
</x-tutor-page>