Docs›Componentes (Admin)›mad-db-metric-card
Componentes (Admin)

mad-db-metric-card

KPI auto-query via model Eloquent (count/sum/avg/min/max).

Componente indicador que faz query de agregação automaticamente no banco de dados e renderiza como metric card.

Props

Prop Tipo Default Descrição
model string '' Classe do model Eloquent (ex: PedidoVenda)
database string MAIN_DATABASE Conexão do banco
field string 'id' Campo para agregação
total string 'count' Função: count, sum, avg, min, max
query Builder null Eloquent/Query Builder pré-montado (alternativa a model+filters)
filters array [] Filtros: [['campo', 'op', 'val'], ...]
label string '' Texto do card
icon string null Nome do ícone Lucide
variant string 'default' default, success, warning, error, info
format string '' Passado ao MadChartFormatter: 'currency:R$', 'numeric:2', 'percent', 'integer', 'abbreviate', formatos de data… Aliases legados 'money:R$' → currency: e 'number:2' → numeric: continuam valendo
trend string null Ex: '+12%' ou '-5'
trend-label string null Ex: 'vs mês anterior'
trend-direction string null up | down | flat — direção explícita (é o trend de MadDashboard::computeDelta()). Sem ela, a direção é inferida do sinal em trend
trend-invert bool false Subir = ruim (custo, churn): inverte a cor do indicador de tendência
icon-color string null Cor custom do ícone (CSS)
icon-bg string null Cor de fundo custom do badge do ícone
style string '' Estilo inline extra no card
no-debug bool false Força ocultar o painel de debug SQL mesmo com debug=1 no ini (usado internamente por <mad-dashboard-metric-compare>)
class string '' Classes CSS extras

Uso básico

<mad-db-metric-card model="PedidoVenda" field="id" total="count"
    label="Total de Pedidos" icon="shopping-cart" format="integer" />

Com formatação monetária

<mad-db-metric-card model="PedidoVenda" field="valor_total" total="sum"
    label="Valor Total" icon="circle-dollar-sign" variant="success" format="money:R$" />

Com query externa (Eloquent Builder pronto)

@php
    $query = \App\Models\Cliente::where('ativo', '=', '1');
@endphp
<mad-db-metric-card :query="$query" field="id" total="count"
    label="Clientes Ativos" icon="users" variant="info" format="integer" />

Com filtros inline

<mad-db-metric-card model="Produto" field="id" total="count"
    :filters="[['ativo', '=', '1']]"
    label="Produtos Ativos" icon="package" format="integer" />

Com trend

<mad-db-metric-card model="PedidoVenda" field="valor_total" total="sum"
    label="Receita" icon="dollar-sign" variant="success" format="money:R$"
    trend="+12%" trend-label="vs mês anterior" />

Com direção explícita (vinda de computeDelta()) e semântica invertida — em custo/churn, subir é ruim:

@php $d = \Mad\Dashboard\MadDashboard::computeDelta($atual, $anterior); @endphp
<mad-db-metric-card model="Chamado" field="id" total="count"
    label="Churn" icon="user-minus" variant="warning"
    :trend="$d['label']" :trend-direction="$d['trend']"
    trend-invert trend-label="vs mês anterior" />

Grid de indicadores

<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:16px;margin-bottom:20px;">
    <mad-db-metric-card model="PedidoVenda" field="id" total="count" ... />
    <mad-db-metric-card model="PedidoVenda" field="valor_total" total="sum" ... />
    <mad-db-metric-card model="Cliente" field="id" total="count" ... />
</div>

Integração com MadDataGrid / MadDashboard (baseQuery)

Para usar os mesmos filtros ativos da listagem/dashboard (período + auto-filters declarados) nos metric cards, use baseQuery() — disponível em qualquer host que use MadFiltersTrait (MadDataGrid e MadDashboard). Contrato completo (period types, auto-discovery, <mad-grid-filters>/<mad-dash-filters>) em filtros declarativos:

@php $query = $that->baseQuery('PedidoVenda'); @endphp

<mad-db-metric-card :query="$query" field="id" total="count"
    label="Pedidos no período" icon="shopping-cart" format="integer" />

Comparação com período anterior

Não existe prop compare/criteria neste componente. Para um KPI com delta vs período anterior, use <mad-dashboard-metric-compare> — wrapper declarativo que recebe :current-query + :compare-query (dois Eloquent Builders) e computa o trend automaticamente. Ver "Comparação com período anterior" em dashboard.md.