Formatação e totais

<?php

namespace App\Control\Tutor;

use App\Models\TutorDemo\TutorDemoPedido;
use App\Support\Tutor\TutorDemoSeed;
use Mad\Grid\MadDataGrid;

/**
 * TutorGridsFormatacao — formatadores de <mad-col> (money/date/badge), transform
 * custom (com e sem HTML, com e sem relação via $row->__record), totais de
 * rodapé (total="sum") e agrupamento com subtotal (group-by/group-mask/group-total).
 *
 * ESTENDE MadDataGrid (não TutorPage): descoberto na prática (renderização real
 * via tinker, não só leitura de doc) que `<mad-grid model="...">` (modo
 * zero-PHP) NUNCA aplica groupBy/groupMask/groupTotal — MadGrid::mount()/
 * _renderFromConfig() só copiam model/database/perPage/actionSide/exportable/
 * searchable/defaultSort do config pro componente; agrupamento só existe em
 * MadDataGrid::_renderInlineGrid() (`<mad-grid self>`), que por sua vez só
 * existe numa subclasse de verdade. Os outros 4 exemplos desta página (que
 * não precisam de agrupamento) continuam em modo zero-PHP normalmente.
 *
 * Gotcha de nesting: `<mad-grid self>` compila para `$__component->
 * _renderInlineGrid(...)` — variável LEXICAL, não resolvida via
 * MadRenderContext. Como cada exemplo é um partial incluído dentro do
 * componente Blade <x-tutor-demo> (escopo isolado — confirmado empiricamente
 * com um teste descartável via tinker), $__component não sobrevive até lá.
 * O fix (mesmo usado por TutorGridsFiltros): reatribuir
 * `$__component = \Mad\Component\MadRenderContext::getComponent();` no TOPO
 * do partial que usa <mad-grid self> — esse helper é resolvido via um stack
 * estático (push/pop em MadComponent::render()), não por escopo léxico, então
 * atravessa qualquer aninhamento de componentes Blade.
 */
class TutorGridsFormatacao extends MadDataGrid
{
    protected static string $wrapper = self::INTERNAL;

    protected string $model    = TutorDemoPedido::class;
    protected string $database = 'business';
    protected array  $with     = ['cliente', 'estado'];

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

    // ── Transforms de coluna ──────────────────────────────────────────────
    // Assinatura: (mixed $value, object $row[, array $rowArr]) — 2o arg é
    // stdClass (cast do row), NUNCA array. Ver grid-datagrid.md.

    /** Transform de COLUNA com HTML (precisa do atributo `html` no <mad-col>). */
    public static function faixaValor(mixed $value, object $row): string
    {
        $valor = (float) $value;

        [$variant, $texto] = match (true) {
            $valor >= 1000 => ['success', 'Alto'],
            $valor >= 300  => ['warning', 'Médio'],
            default        => ['secondary', 'Baixo'],
        };

        return sprintf(
            '<span class="mad-badge mad-badge-%s">%s</span>',
            htmlspecialchars($variant, ENT_QUOTES),
            htmlspecialchars($texto, ENT_QUOTES)
        );
    }

    /** Transform de COLUNA em texto puro (sem `html` — o retorno é escapado normalmente). */
    public static function truncarDescricao(mixed $value, object $row): string
    {
        $texto = (string) $value;

        return $texto !== '' ? mb_strimwidth($texto, 0, 24, '…') : '-';
    }

    /**
     * Transform de coluna de RELAÇÃO — o model Eloquent não tem render('{rel->campo}')
     * como o Record legado, então uma coluna calculada a partir de uma relação
     * usa transform + `$row->__record` (a instância Eloquent real da linha) em
     * vez de tentar ler a relação a partir do array normalizado.
     */
    public static function colClienteCidade(mixed $value, object $row): string
    {
        $cliente = $row->__record->cliente ?? null;

        return $cliente ? "{$cliente->nome} ({$cliente->cidade}/{$cliente->uf})" : '—';
    }

    protected function view(): string|array
    {
        return 'tutor.grids.formatacao';
    }
}

<x-tutor-page page="grids_formatacao">
    <mad-callout type="warning" title="mad-data-row não é uma tag autoral" icon="triangle-alert">
        O catálogo lista <code>mad-data-row</code> nesta página, mas ela não existe
        como tag Blade pra escrever — é o nome do partial interno que o
        MadDataGrid usa pra renderizar cada <code>&lt;tr&gt;</code> (inclusive na
        atualização parcial via <code>manageRow()</code>/<code>removeRow()</code>).
        Não há atributo/prop pra declará-la diretamente no Blade; reportado
        como limitação/imprecisão do catálogo nesta versão do framework.
    </mad-callout>

    <x-tutor-demo demo="tutor.examples.grids-formatacao.formatadores"
        title="Formatadores de coluna" desc="prefix, badge, date e money — direto nos atributos do mad-col." />

    <x-tutor-demo demo="tutor.examples.grids-formatacao.transform"
        title="Transform customizado" desc="Callable PHP formata o valor exibido — com e sem HTML."
        php="TutorGridsFormatacao::faixaValor" />

    <x-tutor-demo demo="tutor.examples.grids-formatacao.totais"
        title="Totais no rodapé" desc="total=&quot;sum|avg|count&quot; agrega a coluna inteira no rodapé." />

    <x-tutor-demo demo="tutor.examples.grids-formatacao.agrupamento"
        title="Agrupamento com subtotal" desc="group-by + group-mask + group-total. O mask usa só o campo cru (categoria_id) — uma seta de relação dentro do valor do atributo quebra o parser da tag do grid (ver comentário no código-fonte do exemplo)." />
</x-tutor-page>