Download the PHP package gsferro/filament-stat-plus-easy without Composer

Filament Stat Plus Easy

🇧🇷 Português · 🇺🇸 English

O Stat do Filament v3, v4 e v5 com o visual que todo dashboard acaba pedindo: ícone no canto superior direito, borda de acento colorida à esquerda e contador animado — mais um esqueleto de carregamento com a mesma forma do card.

Troque Stat::make(...) por StatPlus::make(...), acrescente ->icon(...) e pronto. Nenhuma view publicada, nenhum CSS no seu tema.

🎬 Demo

StatPlus no dashboard — ícone no canto, borda de acento e contador animado:

Cores independentes — o ícone numa cor, a borda em outra (ou sem borda):

Esqueleto do carregamento lazy — mesma forma do card real, então nada salta na troca:

O que o pacote entrega

Compatibilidade

PHP 8.2+. O pacote não publica nem substitui a view nativa do Stat: ele injeta classes e CSS custom properties no elemento raiz que a view já imprime nas três versões. Upgrade de Filament não pede nada daqui.

Instalação

filament:assets copia o CSS do pacote para public/ — é o passo que faz o visual aparecer. Rode-o também no deploy.

Registro do plugin (opcional, só para trocar padrões):

Publicar a config (opcional):

Uso

O básico

->icon() é o gatilho: com ícone, o card ganha o quadrado no canto e a borda à esquerda, ambos na cor do stat.

Sem ->icon() e sem ->accentColor(), o StatPlus renderiza exatamente como o stat nativo. É o que torna a migração incremental segura: troque a classe hoje, acrescente o ícone quando quiser.

Cores — ícone e borda são independentes

Resolução da cor do ícone:

1. ->iconColor('success') — vence sempre
2. senão, ->color('danger') (o método nativo, que também pinta description e chart)
3. senão, config('filament-stat-plus-easy.icon_color') (padrão: primary)

Resolução da cor da borda:

1. ->accentColor(false) — sem borda
2. ->accentColor('danger') — cor própria
3. senão, a cor do ícone — e, sem ícone, não há borda

As cores são nomes de cores registradas no painel (->colors([...])), não hex. O CSS lê a escala pela variável --{cor}-500, que é o que faz o card seguir o tema e o modo escuro. Cor passada como array de 11 tons cai no padrão.

Tudo do Stat nativo continua valendo

Chart, description, url, polling, extraAttributes — nada é substituído. O que o pacote acrescenta é somado ao que você já passou (classe e style concatenam, não sobrescrevem).

Contador animado

StatPlus estende o OdometerStat do filament-odometer-easy — que vem junto como dependência —, então o valor anima sozinho:

Quer o acento sem o contador? Aplique o trait na sua própria classe:

Esqueleto de carregamento (widget lazy)

Widget lazy pinta um placeholder até hidratar. O padrão do Filament é um card liso — quando o widget real entra com ícone e borda, o layout mexe. O trait resolve:

Por padrão o esqueleto desenha 4 cards, todos com acento, e não executa getStats() — o placeholder roda antes da hidratação, e chamar os stats ali executaria justamente as queries que o lazy adia.

Ajustes, todos opcionais:

O esqueleto usa as mesmas classes do card real (fi-wi-stats-overview-stat, fi-stat-plus, fi-stat-plus-bordered), só que em cinza — é o que garante que a troca não desloque nada. E respeita o columnSpan do widget.

Configuração

Fluente, por painel

Ou pelo arquivo de config

Medidas, via CSS

Tamanho do ícone, raio, deslocamento, espessura da borda e opacidade do fundo são custom properties com valor padrão. Sobrescreva onde fizer sentido — no tema (global), por painel ou num card só:

Como funciona por baixo dos panos

• Nada de view publicada. A view nativa do Stat já imprime $getExtraAttributeBag() no elemento raiz em v3, v4 e v5. O pacote injeta ali duas classes (fi-stat-plus, fi-stat-plus-bordered) e duas custom properties (--stat-plus-icon, --stat-plus-accent). O CSS faz o resto: o card já é relative em todas as versões, então o ícone só precisa ser posicionado.
• CSS estático, registrado como asset. Nada de @apply, utilitário do Tailwind ou @layer — o arquivo não passa pelo build do app consumidor. Por isso o pacote dispensa qualquer edição de tema; filament:assets copia e o Filament injeta em todos os painéis.
• Uma diferença real entre as versões: o formato das variáveis de cor. O v3 guarda canais RGB (--primary-500: 217 119 6) e o v4/v5 guardam a cor pronta (oklch(...)). Quem resolve é o PHP, escrevendo rgb(var(--primary-500)) ou var(--primary-500) conforme a versão instalada. O CSS fica igual para todo mundo.
• O ícone mudou de markup entre as versões (.fi-wi-stats-overview-stat-icon no v3, .fi-icon dentro de .fi-wi-stats-overview-stat-label-ctn no v4/v5), então a regra cobre os dois seletores. Nenhum dos dois alcança o ícone da description.
• Nome de cor é validado antes de entrar na string de style (o Filament não escapa valores de atributo extra): só slug [a-z0-9-] passa, o resto cai no padrão. Importa quando a cor vem de dado, como identidade visual por tenant.

Desenvolvimento

O CSS é plain CSS versionado em resources/dist/filament-stat-plus-easy.css — não há passo de build. Editou, testou, commitou.

Os GIFs do README saem de art/demo/index.html (a página carrega o CSS real do pacote) com bash art/make-gifs.sh — Chrome headless para os quadros, ffmpeg para montar. Cada quadro é um screenshot com um ?t= diferente, então a captura é determinística. A capa da página de plugins (art/thumbnail.jpg, 1280x720) sai da mesma página com bash art/make-thumbnail.sh.

Testes

Changelog

Veja o CHANGELOG.

Contributing

Veja o CONTRIBUTING.

Security Vulnerabilities

Veja a política de segurança.

Credits

• gsferro
• Todos os contribuidores
• filament-odometer-easy — o contador animado que vem junto

License

MIT. Veja o arquivo de licença.